From 909126af0af434949b1d19f04ec393fb80733c4b Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 25 Sep 2026 17:44:12 +0200
Subject: [PATCH 001/286] feat(ai): add inputSchema to defineAgent

The parent model can now write the child's input when it calls the agent's tool, for example a short brief. run() reads the checked input as a typed ctx.input. A bad input goes back to the model as a tool error, and the child does not start. A router cannot write input, so chat() throws when subagents.router meets an agent with inputSchema.

Refs #1482
---
 .changeset/define-agent-input-schema.md       |   5 +
 .../activities/chat/agents/define-agent.ts    |  23 ++-
 .../ai/src/activities/chat/agents/spawn.ts    |  32 +--
 packages/ai/src/activities/chat/index.ts      |  10 +
 packages/ai/tests/define-agent.test.ts        | 190 +++++++++++++++++-
 packages/ai/tests/subagent-interrupts.test.ts | 135 ++++++++++---
 6 files changed, 347 insertions(+), 48 deletions(-)
 create mode 100644 .changeset/define-agent-input-schema.md

diff --git a/.changeset/define-agent-input-schema.md b/.changeset/define-agent-input-schema.md
new file mode 100644
index 0000000000..c46e444124
--- /dev/null
+++ b/.changeset/define-agent-input-schema.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai': minor
+---
+
+Add an optional `inputSchema` to `defineAgent`. The agent's tool shows the schema to the model, so the parent model writes the child's input, such as a short brief. `run` gets the checked input as a typed `ctx.input`. A bad input goes back to the model as a tool error, and the child does not start. `inputSchema` needs tool mode: `chat()` throws when `subagents.router` meets an agent that has one. Agents without `inputSchema` do not change.
diff --git a/packages/ai/src/activities/chat/agents/define-agent.ts b/packages/ai/src/activities/chat/agents/define-agent.ts
index 5137d0a148..e9822f64b8 100644
--- a/packages/ai/src/activities/chat/agents/define-agent.ts
+++ b/packages/ai/src/activities/chat/agents/define-agent.ts
@@ -2,6 +2,7 @@ import type { SubagentInfo as AGUISubagentInfo } from '@ag-ui/core'
 import type { InterruptDefinition } from '../../../interrupt-definition'
 import type {
   AnyTool,
+  InferSchemaType,
   ModelMessage,
   RunAgentResumeItem,
   SchemaInput,
@@ -12,8 +13,16 @@ import type { AnyClientTool } from '../tools/tool-definition'
 
 /**
  * Context the library passes into {@link defineAgent} `run`.
+ * `TInput` is the agent's `inputSchema`.
  */
-export interface SubagentRunContext {
+export interface SubagentRunContext<
+  TInput extends SchemaInput | undefined = any,
+> {
+  /**
+   * The input the parent model wrote for this child, checked against
+   * `inputSchema`. `undefined` when the agent has no `inputSchema`.
+   */
+  input: TInput extends SchemaInput ? InferSchemaType<TInput> : undefined
   messages: Array<UIMessage | ModelMessage>
   abortSignal?: AbortSignal
   threadId: string
@@ -53,13 +62,20 @@ export interface DefinedAgent<
   TSchema extends SchemaInput | undefined = SchemaInput | undefined,
   TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
     ReadonlyArray<InterruptDefinition<any, any, any, any>>,
+  TInput extends SchemaInput | undefined = any,
 > extends AGUISubagentInfo {
   name: TName
   /** Required here: the router and the synthetic tool both read it. */
   description: string
   run: (
-    ctx: SubagentRunContext,
+    ctx: SubagentRunContext<TInput>,
   ) => AsyncIterable<StreamChunk> | Promise<AsyncIterable<StreamChunk>>
+  /**
+   * The input the parent model writes when it calls this agent's tool, such
+   * as a short brief. `run` reads it as `ctx.input`. Tool mode only: a
+   * `subagents.router` cannot start an agent that has `inputSchema`.
+   */
+  inputSchema?: TInput
   tools?: TTools
   interrupts?: TInterrupts
   outputSchema?: TSchema
@@ -104,7 +120,8 @@ export function defineAgent<
   const TInterrupts extends ReadonlyArray<
     InterruptDefinition<any, any, any, any>
   > = readonly [],
->(agent: DefinedAgent<TName, TTools, TSchema, TInterrupts>) {
+  TInput extends SchemaInput | undefined = undefined,
+>(agent: DefinedAgent<TName, TTools, TSchema, TInterrupts, TInput>) {
   if (agent.name.trim() === '') {
     throw new Error('defineAgent requires a non-empty name')
   }
diff --git a/packages/ai/src/activities/chat/agents/spawn.ts b/packages/ai/src/activities/chat/agents/spawn.ts
index 9f16e34363..18e712007a 100644
--- a/packages/ai/src/activities/chat/agents/spawn.ts
+++ b/packages/ai/src/activities/chat/agents/spawn.ts
@@ -93,6 +93,8 @@ export function createSubagentSink(): SubagentSink {
 /** One child to start, or a suspended child to continue. */
 export interface SpawnEntry {
   name: string
+  /** The checked tool input for an agent with `inputSchema`. */
+  input?: unknown
   resume?: {
     subagentRunId: string
     /** The child's own messages from the interrupted run. */
@@ -248,6 +250,7 @@ function openAgentStream(
   return spawnAgentStream(
     agent,
     {
+      input: entry.input,
       messages: resumed?.messages ?? ctx.messages,
       ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}),
       threadId: childThreadId(bag.sandbox, ctx.threadId, entry.name),
@@ -721,8 +724,10 @@ export function createSyntheticSubagentTools(
   return bag.agents.map((agent) => ({
     name: agent.name,
     description: agent.description,
+    ...(agent.inputSchema !== undefined && { inputSchema: agent.inputSchema }),
     [SUBAGENT_TOOL]: true,
-    execute: async (_input: unknown, context?: unknown) => {
+    // The tool loop checks `input` against `inputSchema` before this runs.
+    execute: async (input: unknown, context?: unknown) => {
       const toolContext = context as
         | {
             toolCallId?: string
@@ -736,17 +741,20 @@ export function createSyntheticSubagentTools(
           child.parentToolCallId !== undefined &&
           child.parentToolCallId === toolCallId,
       )
-      const entry: SpawnEntry = suspended
-        ? {
-            name: agent.name,
-            resume: {
-              subagentRunId: suspended.subagentRunId,
-              messages: suspended.messages,
-              entries: suspended.resume,
-              text: suspended.text,
-            },
-          }
-        : { name: agent.name }
+      // An agent without `inputSchema` still gets `{}` from the model. Its
+      // `ctx.input` stays undefined.
+      const entry: SpawnEntry = {
+        name: agent.name,
+        ...(agent.inputSchema !== undefined && { input }),
+        ...(suspended && {
+          resume: {
+            subagentRunId: suspended.subagentRunId,
+            messages: suspended.messages,
+            entries: suspended.resume,
+            text: suspended.text,
+          },
+        }),
+      }
       const sink = createSubagentSink()
       const link = linkAbort(parent.abortSignal)
       let subagentRunId = suspended?.subagentRunId ?? ''
diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index 940390490d..29b8fc599f 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -5319,6 +5319,16 @@ async function* runRoutedSubagents(
     yield* runChatEngine(options, engineRef)
     return
   }
+  // ponytail: a router cannot write input yet. Add it to the router pick if
+  // someone needs it.
+  const withInput = bag.agents.find(
+    (agent: DefinedAgent) => agent.inputSchema !== undefined,
+  )
+  if (withInput) {
+    throw new Error(
+      `Subagent "${withInput.name}" has an inputSchema. inputSchema needs tool mode: remove subagents.router so the model writes the input.`,
+    )
+  }
   const threadId = options.threadId ?? `thread-${Date.now()}`
   const runId = options.runId ?? `run-${Date.now()}`
   const messages = options.messages ?? []
diff --git a/packages/ai/tests/define-agent.test.ts b/packages/ai/tests/define-agent.test.ts
index 2311652925..ba676a0549 100644
--- a/packages/ai/tests/define-agent.test.ts
+++ b/packages/ai/tests/define-agent.test.ts
@@ -1,4 +1,5 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, expectTypeOf, it } from 'vitest'
+import { z } from 'zod'
 import {
   defineAgent,
   type DefinedAgent,
@@ -710,6 +711,193 @@ describe('chat({ subagents }) synthetic tools', () => {
   })
 })
 
+describe('defineAgent inputSchema', () => {
+  const briefSchema = z.object({ task: z.string() })
+
+  /** A parent model that calls `researcher` once per args string, then stops. */
+  function parentCalling(...args: Array<string>) {
+    return createMockAdapter({
+      iterations: [
+        [
+          ev.runStarted(),
+          ...args.flatMap((json, index) => [
+            ev.toolStart(`call_${index}`, 'researcher'),
+            ev.toolArgs(`call_${index}`, json),
+          ]),
+          ev.runFinished('tool_calls'),
+        ],
+        [ev.runStarted(), ev.runFinished('stop')],
+      ],
+    })
+  }
+
+  /** A researcher that records every `ctx.input` it gets. */
+  function briefResearcher() {
+    const inputs: Array<{ task: string }> = []
+    const agent = defineAgent({
+      name: 'researcher',
+      description: 'Looks up facts',
+      inputSchema: briefSchema,
+      run: async function* (ctx) {
+        expectTypeOf(ctx.input).toEqualTypeOf<{ task: string }>()
+        inputs.push(ctx.input)
+      },
+    })
+    return { agent, inputs }
+  }
+
+  it('shows the schema to the model and passes the input to run', async () => {
+    const { agent, inputs } = briefResearcher()
+    const { adapter, calls } = parentCalling('{"task":"Price Vendor A"}')
+
+    await collectChunks(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'Compare pricing' }],
+        subagents: { agents: [agent] },
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    const tool = calls[0]?.tools?.find((entry) => entry.name === 'researcher')
+    expect(tool?.inputSchema).toMatchObject({
+      type: 'object',
+      properties: { task: { type: 'string' } },
+    })
+    expect(inputs).toEqual([{ task: 'Price Vendor A' }])
+  })
+
+  it('gives each call to the same agent its own input', async () => {
+    const { agent, inputs } = briefResearcher()
+    const { adapter } = parentCalling(
+      '{"task":"Price Vendor A"}',
+      '{"task":"Price Vendor B"}',
+    )
+
+    await collectChunks(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'Compare pricing' }],
+        subagents: { agents: [agent] },
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect(inputs).toHaveLength(2)
+    expect(inputs).toEqual(
+      expect.arrayContaining([
+        { task: 'Price Vendor A' },
+        { task: 'Price Vendor B' },
+      ]),
+    )
+  })
+
+  it('returns a bad input to the model and does not start the child', async () => {
+    const { agent, inputs } = briefResearcher()
+    const { adapter } = parentCalling('{}')
+
+    const chunks = await collectChunks(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'Compare pricing' }],
+        subagents: { agents: [agent] },
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    const result = chunks.find(
+      (chunk) =>
+        chunk.type === EventType.TOOL_CALL_RESULT &&
+        chunk.toolCallId === 'call_0',
+    )
+    expect(result).toMatchObject({
+      content: expect.stringContaining(
+        'Input validation failed for tool researcher',
+      ),
+    })
+    expect(chunks.some((chunk) => chunk.type === 'SUBAGENT_STARTED')).toBe(
+      false,
+    )
+    expect(inputs).toEqual([])
+  })
+
+  it('passes the parsed args through a plain JSON Schema', async () => {
+    const inputs: Array<unknown> = []
+    const agent = defineAgent({
+      name: 'researcher',
+      description: 'Looks up facts',
+      inputSchema: {
+        type: 'object',
+        properties: { task: { type: 'string' } },
+        required: ['task'],
+      },
+      run: async function* (ctx) {
+        inputs.push(ctx.input)
+      },
+    })
+    const { adapter, calls } = parentCalling('{"task":"Price Vendor A"}')
+
+    await collectChunks(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'Compare pricing' }],
+        subagents: { agents: [agent] },
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    const tool = calls[0]?.tools?.find((entry) => entry.name === 'researcher')
+    expect(tool?.inputSchema).toMatchObject({
+      properties: { task: { type: 'string' } },
+    })
+    expect(inputs).toEqual([{ task: 'Price Vendor A' }])
+  })
+
+  it('keeps ctx.input undefined for an agent without inputSchema', async () => {
+    const inputs: Array<unknown> = []
+    const agent = defineAgent({
+      name: 'researcher',
+      description: 'Looks up facts',
+      run: async function* (ctx) {
+        expectTypeOf(ctx.input).toEqualTypeOf<undefined>()
+        inputs.push(ctx.input)
+      },
+    })
+    const { adapter, calls } = parentCalling('{}')
+
+    await collectChunks(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'Research this' }],
+        subagents: { agents: [agent] },
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    const tool = calls[0]?.tools?.find((entry) => entry.name === 'researcher')
+    // The engine gives a tool with no schema an empty object schema.
+    expect(tool?.inputSchema?.properties ?? {}).toEqual({})
+    expect(inputs).toEqual([undefined])
+  })
+
+  it('throws when a router meets an agent with inputSchema', async () => {
+    const { agent } = briefResearcher()
+    let routerCalls = 0
+
+    await expect(
+      collectChunks(
+        chat({
+          adapter: parentAdapter().adapter,
+          messages: [{ role: 'user', content: 'Compare pricing' }],
+          subagents: {
+            agents: [agent],
+            router: () => {
+              routerCalls += 1
+              return 'main'
+            },
+          },
+        }) as AsyncIterable<StreamChunk>,
+      ),
+    ).rejects.toThrow('Subagent "researcher" has an inputSchema')
+    expect(routerCalls).toBe(0)
+  })
+})
+
 describe('subagent guards', () => {
   it('rejects the reserved name main', () => {
     expect(() => namedAgent('main')).toThrow("cannot use the name 'main'")
diff --git a/packages/ai/tests/subagent-interrupts.test.ts b/packages/ai/tests/subagent-interrupts.test.ts
index e86b3d9e01..f7eb5408ee 100644
--- a/packages/ai/tests/subagent-interrupts.test.ts
+++ b/packages/ai/tests/subagent-interrupts.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
 import { chat } from '../src/activities/chat'
 import { defineAgent } from '../src/activities/chat/agents/define-agent'
 import { StreamProcessor } from '../src/activities/chat/stream/processor'
@@ -22,8 +23,8 @@ const user: UIMessage = {
   parts: [{ type: 'text', content: 'Clean up' }],
 }
 
-/** A child that asks approval to delete a file, then reports. */
-function cleanerAgent({ needsApproval = true } = {}) {
+/** A child model that asks to delete a file, then reports. */
+function cleanerChild({ needsApproval = true } = {}) {
   const execute = vi.fn().mockReturnValue({ deleted: true })
   const { adapter } = createMockAdapter({
     iterations: [
@@ -51,27 +52,60 @@ function cleanerAgent({ needsApproval = true } = {}) {
       ],
     ],
   })
+  const tools = [{ ...serverTool('deleteFile', execute), needsApproval }]
+  const run = (ctx: SubagentRunContext) =>
+    chat({
+      adapter,
+      messages: ctx.messages,
+      threadId: ctx.threadId,
+      runId: ctx.runId,
+      parentRunId: ctx.parentRunId,
+      subagentRunId: ctx.subagentRunId,
+      resume: ctx.resume,
+      tools,
+    })
+  return { run, execute }
+}
+
+/** A child that asks approval to delete a file, then reports. */
+function cleanerAgent({ needsApproval = true } = {}) {
+  const { run, execute } = cleanerChild({ needsApproval })
   const contexts: Array<SubagentRunContext> = []
   const agent = defineAgent({
     name: 'cleaner',
     description: 'Deletes files',
     run: (ctx) => {
       contexts.push(ctx)
-      return chat({
-        adapter,
-        messages: ctx.messages,
-        threadId: ctx.threadId,
-        runId: ctx.runId,
-        parentRunId: ctx.parentRunId,
-        subagentRunId: ctx.subagentRunId,
-        resume: ctx.resume,
-        tools: [{ ...serverTool('deleteFile', execute), needsApproval }],
-      })
+      return run(ctx)
     },
   })
   return { agent, execute, contexts }
 }
 
+/** A parent model that calls `cleaner` with `args`, then wraps up. */
+function toolParent(args: string) {
+  return createMockAdapter({
+    iterations: [
+      [
+        ev.runStarted('p1'),
+        ev.textStart('parent-note'),
+        ev.textContent('Checking the disk first', 'parent-note'),
+        ev.textEnd('parent-note'),
+        ev.toolStart('call_p', 'cleaner'),
+        ev.toolArgs('call_p', args),
+        ev.runFinished('tool_calls', 'p1'),
+      ],
+      [
+        ev.runStarted('p2'),
+        ev.textStart('parent-done'),
+        ev.textContent('All clean', 'parent-done'),
+        ev.textEnd('parent-done'),
+        ev.runFinished('stop', 'p2'),
+      ],
+    ],
+  }).adapter
+}
+
 function cardOf(messages: ReadonlyArray<UIMessage>): SubagentPart {
   for (const message of messages) {
     for (const part of message.parts) {
@@ -386,26 +420,7 @@ describe('subagent interrupts', () => {
 
   it('suspends a child that a tool call started, then resumes it', async () => {
     const { agent, execute, contexts } = cleanerAgent()
-    const { adapter: parent } = createMockAdapter({
-      iterations: [
-        [
-          ev.runStarted('p1'),
-          ev.textStart('parent-note'),
-          ev.textContent('Checking the disk first', 'parent-note'),
-          ev.textEnd('parent-note'),
-          ev.toolStart('call_p', 'cleaner'),
-          ev.toolArgs('call_p', '{}'),
-          ev.runFinished('tool_calls', 'p1'),
-        ],
-        [
-          ev.runStarted('p2'),
-          ev.textStart('parent-done'),
-          ev.textContent('All clean', 'parent-done'),
-          ev.textEnd('parent-done'),
-          ev.runFinished('stop', 'p2'),
-        ],
-      ],
-    })
+    const parent = toolParent('{}')
     const subagents = { agents: [agent] }
 
     const first = await collectChunks(
@@ -477,6 +492,62 @@ describe('subagent interrupts', () => {
     expect(second.at(-1)).toMatchObject({ type: EventType.RUN_FINISHED })
     expect(second.at(-1)).not.toHaveProperty('outcome.type', 'interrupt')
   })
+
+  it('gives a resumed child the same input the model wrote', async () => {
+    const { run, execute } = cleanerChild()
+    const inputs: Array<{ folder: string }> = []
+    const agent = defineAgent({
+      name: 'cleaner',
+      description: 'Deletes files',
+      inputSchema: z.object({ folder: z.string() }),
+      run: (ctx) => {
+        inputs.push(ctx.input)
+        return run(ctx)
+      },
+    })
+    const parent = toolParent('{"folder":"old"}')
+    const subagents = { agents: [agent] }
+
+    const first = await collectChunks(
+      chat({
+        adapter: parent,
+        threadId: 't',
+        runId: 'run-1',
+        messages: [user],
+        subagents,
+      }) as AsyncIterable<StreamChunk>,
+    )
+    const processor = new StreamProcessor({ initialMessages: [user] })
+    replay(processor, first)
+    // The input stays on the parent's tool call, next to the card.
+    expect(
+      processor.getMessages().flatMap((message) => message.parts),
+    ).toContainEqual(
+      expect.objectContaining({
+        type: 'tool-call',
+        id: 'call_p',
+        arguments: '{"folder":"old"}',
+      }),
+    )
+
+    processor.addToolApprovalResponse('approval_call_c', true)
+    await collectChunks(
+      chat({
+        adapter: parent,
+        threadId: 't',
+        runId: 'run-2',
+        parentRunId: 'run-1',
+        messages: requestMessages(processor.getMessages()),
+        resume: [
+          { interruptId: 'approval_call_c', status: 'resolved', payload: true },
+        ],
+        subagents,
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect(inputs).toEqual([{ folder: 'old' }, { folder: 'old' }])
+    expect(execute).toHaveBeenCalledTimes(1)
+  })
 })
 
 describe('subagent cards', () => {

From 92268fae1d9fba7d39570cc97c6f1760767d8e9e Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 25 Sep 2026 17:44:13 +0200
Subject: [PATCH 002/286] test(e2e): cover a subagent brief written by the
 parent model

The child fixture matches only the brief text, so the test fails if the child gets the parent transcript instead.
---
 testing/e2e/fixtures/subagents/basic.json    | 31 ++++++++++++++++++++
 testing/e2e/src/lib/subagents-test.ts        | 10 +++++--
 testing/e2e/src/routes/api.subagents-test.ts | 25 +++++++++++++++-
 testing/e2e/tests/subagents.spec.ts          | 23 ++++++++++++++-
 4 files changed, 85 insertions(+), 4 deletions(-)

diff --git a/testing/e2e/fixtures/subagents/basic.json b/testing/e2e/fixtures/subagents/basic.json
index 610e6dd093..fd9d5b682f 100644
--- a/testing/e2e/fixtures/subagents/basic.json
+++ b/testing/e2e/fixtures/subagents/basic.json
@@ -78,6 +78,37 @@
       "response": {
         "content": "Research is done."
       }
+    },
+    {
+      "match": {
+        "userMessage": "[subagent-brief] compare squid facts",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "researcher",
+            "arguments": "{\"task\":\"[subagent-brief-task] List two squid facts.\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[subagent-brief-task] List two squid facts."
+      },
+      "response": {
+        "content": "Squids have three hearts and blue blood."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[subagent-brief] compare squid facts",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "The comparison is ready."
+      }
     }
   ]
 }
diff --git a/testing/e2e/src/lib/subagents-test.ts b/testing/e2e/src/lib/subagents-test.ts
index d6ff957740..b7dfad6c23 100644
--- a/testing/e2e/src/lib/subagents-test.ts
+++ b/testing/e2e/src/lib/subagents-test.ts
@@ -18,15 +18,21 @@ export const lookupFacts = toolDefinition({
   inputSchema: z.object({ topic: z.string() }),
 })
 
-export type SubagentScenario = 'route' | 'approval' | 'tool'
+export type SubagentScenario = 'route' | 'approval' | 'tool' | 'brief'
 
 /** The user message for each scenario. It matches `fixtures/subagents`. */
 export const SUBAGENT_PROMPTS: Record<SubagentScenario, string> = {
   route: '[subagent-route] research squids',
   approval: '[subagent-approval] clean up the old logs',
   tool: '[subagent-tool] research squids',
+  brief: '[subagent-brief] compare squid facts',
 }
 
 export function isSubagentScenario(value: unknown): value is SubagentScenario {
-  return value === 'route' || value === 'approval' || value === 'tool'
+  return (
+    value === 'route' ||
+    value === 'approval' ||
+    value === 'tool' ||
+    value === 'brief'
+  )
 }
diff --git a/testing/e2e/src/routes/api.subagents-test.ts b/testing/e2e/src/routes/api.subagents-test.ts
index 5abcfe4e2e..561fa9185f 100644
--- a/testing/e2e/src/routes/api.subagents-test.ts
+++ b/testing/e2e/src/routes/api.subagents-test.ts
@@ -6,7 +6,8 @@ import {
   maxIterations,
   toServerSentEventsResponse,
 } from '@tanstack/ai'
-import type { Tool } from '@tanstack/ai'
+import { z } from 'zod'
+import type { DefinedAgent, Tool } from '@tanstack/ai'
 import { createTextAdapter } from '@/lib/providers'
 import {
   deleteLogs,
@@ -27,6 +28,8 @@ import type { SubagentScenario } from '@/lib/subagents-test'
  *   the same child.
  * - `tool`: no router. The parent model calls the `researcher` tool, the
  *   child answers, and the parent reads its result.
+ * - `brief`: no router. The parent model writes a `task` for `researcher`,
+ *   and the child's only message is that task.
  */
 function subagentsFor(
   scenario: SubagentScenario,
@@ -72,6 +75,26 @@ function subagentsFor(
     ])
     return { agents: [cleaner], router: () => 'cleaner' }
   }
+  if (scenario === 'brief') {
+    const researcher = defineAgent({
+      name: 'researcher',
+      description: 'Researches one focused task',
+      inputSchema: z.object({ task: z.string() }),
+      run: (ctx) =>
+        chat({
+          ...createTextAdapter('openai', undefined, aimockPort, testId),
+          messages: [{ role: 'user', content: ctx.input.task }],
+          threadId: ctx.threadId,
+          runId: ctx.runId,
+          parentRunId: ctx.parentRunId,
+          subagentRunId: ctx.subagentRunId,
+          resume: ctx.resume,
+        }),
+    })
+    // Each branch returns its own bag, so give them one agent type.
+    const agents: Array<DefinedAgent> = [researcher]
+    return { agents }
+  }
   return { agents: [child('researcher', [])] }
 }
 
diff --git a/testing/e2e/tests/subagents.spec.ts b/testing/e2e/tests/subagents.spec.ts
index 8faf7d8968..20ae0d3f44 100644
--- a/testing/e2e/tests/subagents.spec.ts
+++ b/testing/e2e/tests/subagents.spec.ts
@@ -14,7 +14,7 @@ async function run(page: Page) {
 
 function open(
   page: Page,
-  scenario: 'route' | 'approval' | 'tool',
+  scenario: 'route' | 'approval' | 'tool' | 'brief',
   testId: string,
   aimockPort: number,
 ) {
@@ -111,4 +111,25 @@ test.describe('subagents', () => {
       'text:Squids have three hearts.',
     )
   })
+
+  test('the parent model writes the brief the child runs on', async ({
+    page,
+    testId,
+    aimockPort,
+  }) => {
+    await open(page, 'brief', testId, aimockPort)
+    await run(page)
+
+    await expect(page.getByTestId('parent-text')).toHaveText(
+      'The comparison is ready.',
+    )
+    await expect(page.getByTestId('card-status-researcher')).toHaveText(
+      'finished',
+    )
+    // The child's fixture matches only the brief. A child that got the
+    // transcript instead would get no reply.
+    await expect(page.getByTestId('card-researcher')).toContainText(
+      'text:Squids have three hearts and blue blood.',
+    )
+  })
 })

From 650a5f871d7f3a66e73fd884bd7b672d24d8970c Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 25 Sep 2026 17:44:13 +0200
Subject: [PATCH 003/286] docs: document subagent briefs with inputSchema

Add 'Let the model write the brief' and 'Show the brief on a card' to the subagents page.
---
 docs/chat/subagents.md | 85 ++++++++++++++++++++++++++++++++++++++++++
 docs/config.json       |  2 +-
 2 files changed, 86 insertions(+), 1 deletion(-)

diff --git a/docs/chat/subagents.md b/docs/chat/subagents.md
index a0c02f973f..de2f4698a3 100644
--- a/docs/chat/subagents.md
+++ b/docs/chat/subagents.md
@@ -156,6 +156,56 @@ const stream = chat({
 
 **Without a router.** The library adds one synthetic server tool per agent. The main model calls that tool. The public stream still emits `SUBAGENT_STARTED` / `SUBAGENT_FINISHED` (or `SUBAGENT_ERROR`) and nested parts. The UI does not treat spawn as a normal tool card. The child's events stream while the tool runs, and the child's text becomes the tool result. The child reads the conversation as it is at that tool call.
 
+## Let the model write the brief
+
+In a long thread, the child gets the full conversation at the tool call, with every earlier tool result. Each parallel child gets its own copy. The child must also find its task in that conversation.
+
+Add `inputSchema` to the agent. The main model then writes the child's input when it calls the tool. `run` reads that input as `ctx.input`:
+
+```ts
+import { chat, defineAgent } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+const messages = [
+  { role: 'user' as const, content: 'Compare pricing for the vendors we picked' },
+]
+
+const researcher = defineAgent({
+  name: 'researcher',
+  description: 'Researches one focused question and returns sourced findings',
+  inputSchema: z.object({
+    task: z
+      .string()
+      .describe('What to find and what to return. The researcher sees only this text.'),
+  }),
+  run: (ctx) =>
+    chat({
+      adapter: openaiText('gpt-5.6'),
+      messages: [{ role: 'user', content: ctx.input.task }],
+      threadId: ctx.threadId,
+      runId: ctx.runId,
+      parentRunId: ctx.parentRunId,
+      subagentRunId: ctx.subagentRunId,
+      resume: ctx.resume,
+    }),
+})
+
+const stream = chat({
+  adapter: openaiText('gpt-5.6'),
+  messages,
+  subagents: { agents: [researcher] },
+})
+```
+
+- `ctx.input` has the type of the schema. Here it is `{ task: string }`.
+- If the input does not match the schema, the model gets a tool error and can call the tool again. The child does not start.
+- `ctx.messages` still holds the parent conversation. Add parts of it when the child needs more context.
+- A resumed child gets the same `ctx.input` as the first run.
+- `inputSchema` needs tool mode. If `subagents.router` is set and an agent has `inputSchema`, `chat()` throws.
+
+To show the brief in the UI, see [Show the brief on a card](#show-the-brief-on-a-card).
+
 ## Strategy
 
 - `exclusive` (default): the chosen child owns the turn. Main does not answer after it.
@@ -497,6 +547,41 @@ export function ChatScreen() {
 
 When `run` imports server code, do not import the agent into the browser. Declare the agent once in a shared file, with its `name`, `description`, and tool definitions from `toolDefinition`. The server passes `defineAgent({ ...researcher, run })` to `chat()`. The client passes the declaration.
 
+### Show the brief on a card
+
+When an agent has `inputSchema`, the brief is the input of the tool call that started the child. That `tool-call` part is on the same assistant message as the card. `part.subagent.parentToolCallId` is its id:
+
+```tsx
+import type { UIMessage } from '@tanstack/ai-react'
+
+function briefOf(message: UIMessage, toolCallId: string) {
+  for (const part of message.parts) {
+    if (part.type !== 'tool-call' || part.id !== toolCallId) continue
+    const input = part.input
+    if (
+      typeof input === 'object' &&
+      input !== null &&
+      'task' in input &&
+      typeof input.task === 'string'
+    ) {
+      return input.task
+    }
+  }
+  return undefined
+}
+
+function Briefs({ message }: { message: UIMessage }) {
+  return message.parts.map((part) => {
+    if (part.type !== 'subagent') return null
+    const toolCallId = part.subagent.parentToolCallId
+    if (toolCallId === undefined) return null
+    return <p key={part.subagent.id}>{briefOf(message, toolCallId)}</p>
+  })
+}
+```
+
+A child that a router started has no `parentToolCallId`, so it has no brief.
+
 ### Style one child's parts
 
 The researcher's reasoning and tool calls use the root widgets by default. To make them look different on the researcher card only, pass widgets to that card's `Parts`:
diff --git a/docs/config.json b/docs/config.json
index 0d4770f15b..3c6e1f6f68 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -155,7 +155,7 @@
           "label": "Subagents",
           "to": "chat/subagents",
           "addedAt": "2026-09-21",
-          "updatedAt": "2026-09-24"
+          "updatedAt": "2026-09-25"
         },
         {
           "label": "Agentic Cycle",

From d2c6910ce7730511bbe4c0e6bed191e14739d850 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 25 Sep 2026 17:44:13 +0200
Subject: [PATCH 004/286] feat(examples): add a subagent brief demo to
 ts-react-chat

The /subagent-brief page shows each researcher card with the brief the parent model wrote and the child's answer.
---
 .../ts-react-chat/src/components/Header.tsx   |  14 ++
 examples/ts-react-chat/src/routeTree.gen.ts   |  42 ++++++
 .../src/routes/api.subagent-brief.ts          |  68 +++++++++
 .../src/routes/subagent-brief.tsx             | 135 ++++++++++++++++++
 4 files changed, 259 insertions(+)
 create mode 100644 examples/ts-react-chat/src/routes/api.subagent-brief.ts
 create mode 100644 examples/ts-react-chat/src/routes/subagent-brief.tsx

diff --git a/examples/ts-react-chat/src/components/Header.tsx b/examples/ts-react-chat/src/components/Header.tsx
index fc6d50cbb5..20d344a520 100644
--- a/examples/ts-react-chat/src/components/Header.tsx
+++ b/examples/ts-react-chat/src/components/Header.tsx
@@ -18,6 +18,7 @@ import {
   MessageSquare,
   Mic,
   Music,
+  Network,
   PauseCircle,
   Plug,
   RefreshCw,
@@ -381,6 +382,19 @@ export default function Header() {
             <span className="font-medium">WebSocket Chat</span>
           </Link>
 
+          <Link
+            to="/subagent-brief"
+            onClick={() => setIsOpen(false)}
+            className="flex items-center gap-3 p-3 rounded-lg hover:bg-gray-800 transition-colors mb-2"
+            activeProps={{
+              className:
+                'flex items-center gap-3 p-3 rounded-lg bg-cyan-600 hover:bg-cyan-700 transition-colors mb-2',
+            }}
+          >
+            <Network size={20} />
+            <span className="font-medium">Subagent Brief</span>
+          </Link>
+
           <Link
             to="/persistent-chat"
             onClick={() => setIsOpen(false)}
diff --git a/examples/ts-react-chat/src/routeTree.gen.ts b/examples/ts-react-chat/src/routeTree.gen.ts
index b0edbb8e74..4e7cafac3c 100644
--- a/examples/ts-react-chat/src/routeTree.gen.ts
+++ b/examples/ts-react-chat/src/routeTree.gen.ts
@@ -12,6 +12,7 @@ import { Route as rootRouteImport } from './routes/__root'
 import { Route as WebsocketChatRouteImport } from './routes/websocket-chat'
 import { Route as TypesafeToolsRouteImport } from './routes/typesafe-tools'
 import { Route as ThreadsRouteImport } from './routes/threads'
+import { Route as SubagentBriefRouteImport } from './routes/subagent-brief'
 import { Route as ServerFnChatRouteImport } from './routes/server-fn-chat'
 import { Route as SandboxesDurableRouteImport } from './routes/sandboxes-durable'
 import { Route as SandboxesRouteImport } from './routes/sandboxes'
@@ -46,6 +47,7 @@ import { Route as ExampleRuntimeContextRouteImport } from './routes/example.runt
 import { Route as ApiTranscribeRouteImport } from './routes/api.transcribe'
 import { Route as ApiTanchatRouteImport } from './routes/api.tanchat'
 import { Route as ApiSummarizeRouteImport } from './routes/api.summarize'
+import { Route as ApiSubagentBriefRouteImport } from './routes/api.subagent-brief'
 import { Route as ApiStructuredOutputRouteImport } from './routes/api.structured-output'
 import { Route as ApiStructuredChatRouteImport } from './routes/api.structured-chat'
 import { Route as ApiSandboxTriageDurableRouteImport } from './routes/api.sandbox-triage-durable'
@@ -96,6 +98,11 @@ const ThreadsRoute = ThreadsRouteImport.update({
   path: '/threads',
   getParentRoute: () => rootRouteImport,
 } as any)
+const SubagentBriefRoute = SubagentBriefRouteImport.update({
+  id: '/subagent-brief',
+  path: '/subagent-brief',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ServerFnChatRoute = ServerFnChatRouteImport.update({
   id: '/server-fn-chat',
   path: '/server-fn-chat',
@@ -271,6 +278,11 @@ const ApiSummarizeRoute = ApiSummarizeRouteImport.update({
   path: '/api/summarize',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiSubagentBriefRoute = ApiSubagentBriefRouteImport.update({
+  id: '/api/subagent-brief',
+  path: '/api/subagent-brief',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiStructuredOutputRoute = ApiStructuredOutputRouteImport.update({
   id: '/api/structured-output',
   path: '/api/structured-output',
@@ -464,6 +476,7 @@ export interface FileRoutesByFullPath {
   '/sandboxes': typeof SandboxesRoute
   '/sandboxes-durable': typeof SandboxesDurableRoute
   '/server-fn-chat': typeof ServerFnChatRoute
+  '/subagent-brief': typeof SubagentBriefRoute
   '/threads': typeof ThreadsRoute
   '/typesafe-tools': typeof TypesafeToolsRoute
   '/websocket-chat': typeof WebsocketChatRoute
@@ -494,6 +507,7 @@ export interface FileRoutesByFullPath {
   '/api/sandbox-triage-durable': typeof ApiSandboxTriageDurableRoute
   '/api/structured-chat': typeof ApiStructuredChatRoute
   '/api/structured-output': typeof ApiStructuredOutputRoute
+  '/api/subagent-brief': typeof ApiSubagentBriefRoute
   '/api/summarize': typeof ApiSummarizeRoute
   '/api/tanchat': typeof ApiTanchatRoute
   '/api/transcribe': typeof ApiTranscribeRoute
@@ -537,6 +551,7 @@ export interface FileRoutesByTo {
   '/sandboxes': typeof SandboxesRoute
   '/sandboxes-durable': typeof SandboxesDurableRoute
   '/server-fn-chat': typeof ServerFnChatRoute
+  '/subagent-brief': typeof SubagentBriefRoute
   '/threads': typeof ThreadsRoute
   '/typesafe-tools': typeof TypesafeToolsRoute
   '/websocket-chat': typeof WebsocketChatRoute
@@ -567,6 +582,7 @@ export interface FileRoutesByTo {
   '/api/sandbox-triage-durable': typeof ApiSandboxTriageDurableRoute
   '/api/structured-chat': typeof ApiStructuredChatRoute
   '/api/structured-output': typeof ApiStructuredOutputRoute
+  '/api/subagent-brief': typeof ApiSubagentBriefRoute
   '/api/summarize': typeof ApiSummarizeRoute
   '/api/tanchat': typeof ApiTanchatRoute
   '/api/transcribe': typeof ApiTranscribeRoute
@@ -611,6 +627,7 @@ export interface FileRoutesById {
   '/sandboxes': typeof SandboxesRoute
   '/sandboxes-durable': typeof SandboxesDurableRoute
   '/server-fn-chat': typeof ServerFnChatRoute
+  '/subagent-brief': typeof SubagentBriefRoute
   '/threads': typeof ThreadsRoute
   '/typesafe-tools': typeof TypesafeToolsRoute
   '/websocket-chat': typeof WebsocketChatRoute
@@ -641,6 +658,7 @@ export interface FileRoutesById {
   '/api/sandbox-triage-durable': typeof ApiSandboxTriageDurableRoute
   '/api/structured-chat': typeof ApiStructuredChatRoute
   '/api/structured-output': typeof ApiStructuredOutputRoute
+  '/api/subagent-brief': typeof ApiSubagentBriefRoute
   '/api/summarize': typeof ApiSummarizeRoute
   '/api/tanchat': typeof ApiTanchatRoute
   '/api/transcribe': typeof ApiTranscribeRoute
@@ -686,6 +704,7 @@ export interface FileRouteTypes {
     | '/sandboxes'
     | '/sandboxes-durable'
     | '/server-fn-chat'
+    | '/subagent-brief'
     | '/threads'
     | '/typesafe-tools'
     | '/websocket-chat'
@@ -716,6 +735,7 @@ export interface FileRouteTypes {
     | '/api/sandbox-triage-durable'
     | '/api/structured-chat'
     | '/api/structured-output'
+    | '/api/subagent-brief'
     | '/api/summarize'
     | '/api/tanchat'
     | '/api/transcribe'
@@ -759,6 +779,7 @@ export interface FileRouteTypes {
     | '/sandboxes'
     | '/sandboxes-durable'
     | '/server-fn-chat'
+    | '/subagent-brief'
     | '/threads'
     | '/typesafe-tools'
     | '/websocket-chat'
@@ -789,6 +810,7 @@ export interface FileRouteTypes {
     | '/api/sandbox-triage-durable'
     | '/api/structured-chat'
     | '/api/structured-output'
+    | '/api/subagent-brief'
     | '/api/summarize'
     | '/api/tanchat'
     | '/api/transcribe'
@@ -832,6 +854,7 @@ export interface FileRouteTypes {
     | '/sandboxes'
     | '/sandboxes-durable'
     | '/server-fn-chat'
+    | '/subagent-brief'
     | '/threads'
     | '/typesafe-tools'
     | '/websocket-chat'
@@ -862,6 +885,7 @@ export interface FileRouteTypes {
     | '/api/sandbox-triage-durable'
     | '/api/structured-chat'
     | '/api/structured-output'
+    | '/api/subagent-brief'
     | '/api/summarize'
     | '/api/tanchat'
     | '/api/transcribe'
@@ -906,6 +930,7 @@ export interface RootRouteChildren {
   SandboxesRoute: typeof SandboxesRoute
   SandboxesDurableRoute: typeof SandboxesDurableRoute
   ServerFnChatRoute: typeof ServerFnChatRoute
+  SubagentBriefRoute: typeof SubagentBriefRoute
   ThreadsRoute: typeof ThreadsRoute
   TypesafeToolsRoute: typeof TypesafeToolsRoute
   WebsocketChatRoute: typeof WebsocketChatRoute
@@ -936,6 +961,7 @@ export interface RootRouteChildren {
   ApiSandboxTriageDurableRoute: typeof ApiSandboxTriageDurableRoute
   ApiStructuredChatRoute: typeof ApiStructuredChatRoute
   ApiStructuredOutputRoute: typeof ApiStructuredOutputRoute
+  ApiSubagentBriefRoute: typeof ApiSubagentBriefRoute
   ApiSummarizeRoute: typeof ApiSummarizeRoute
   ApiTanchatRoute: typeof ApiTanchatRoute
   ApiTranscribeRoute: typeof ApiTranscribeRoute
@@ -981,6 +1007,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ThreadsRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/subagent-brief': {
+      id: '/subagent-brief'
+      path: '/subagent-brief'
+      fullPath: '/subagent-brief'
+      preLoaderRoute: typeof SubagentBriefRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/server-fn-chat': {
       id: '/server-fn-chat'
       path: '/server-fn-chat'
@@ -1219,6 +1252,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiSummarizeRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/subagent-brief': {
+      id: '/api/subagent-brief'
+      path: '/api/subagent-brief'
+      fullPath: '/api/subagent-brief'
+      preLoaderRoute: typeof ApiSubagentBriefRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/structured-output': {
       id: '/api/structured-output'
       path: '/api/structured-output'
@@ -1492,6 +1532,7 @@ const rootRouteChildren: RootRouteChildren = {
   SandboxesRoute: SandboxesRoute,
   SandboxesDurableRoute: SandboxesDurableRoute,
   ServerFnChatRoute: ServerFnChatRoute,
+  SubagentBriefRoute: SubagentBriefRoute,
   ThreadsRoute: ThreadsRoute,
   TypesafeToolsRoute: TypesafeToolsRoute,
   WebsocketChatRoute: WebsocketChatRoute,
@@ -1522,6 +1563,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiSandboxTriageDurableRoute: ApiSandboxTriageDurableRoute,
   ApiStructuredChatRoute: ApiStructuredChatRoute,
   ApiStructuredOutputRoute: ApiStructuredOutputRoute,
+  ApiSubagentBriefRoute: ApiSubagentBriefRoute,
   ApiSummarizeRoute: ApiSummarizeRoute,
   ApiTanchatRoute: ApiTanchatRoute,
   ApiTranscribeRoute: ApiTranscribeRoute,
diff --git a/examples/ts-react-chat/src/routes/api.subagent-brief.ts b/examples/ts-react-chat/src/routes/api.subagent-brief.ts
new file mode 100644
index 0000000000..0f229eb84c
--- /dev/null
+++ b/examples/ts-react-chat/src/routes/api.subagent-brief.ts
@@ -0,0 +1,68 @@
+import { createFileRoute } from '@tanstack/react-router'
+import {
+  chat,
+  chatParamsFromRequestBody,
+  defineAgent,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+/**
+ * The parent model writes the researcher's brief. The researcher's only
+ * message is that brief, not the parent conversation.
+ */
+const researcher = defineAgent({
+  name: 'researcher',
+  description:
+    'Researches one focused question and returns short findings. It cannot see this chat, so the task must hold every detail it needs.',
+  inputSchema: z.object({
+    task: z
+      .string()
+      .describe(
+        'What to find and what to return. The researcher sees only this text.',
+      ),
+  }),
+  run: (ctx) => {
+    console.log(
+      '[subagent-brief] child input:',
+      JSON.stringify(ctx.input),
+      '| parent messages available:',
+      ctx.messages.length,
+    )
+    return chat({
+      adapter: openaiText('gpt-5.6'),
+      messages: [{ role: 'user', content: ctx.input.task }],
+      threadId: ctx.threadId,
+      runId: ctx.runId,
+      parentRunId: ctx.parentRunId,
+      subagentRunId: ctx.subagentRunId,
+      resume: ctx.resume,
+    })
+  },
+})
+
+export const Route = createFileRoute('/api/subagent-brief')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const abortController = new AbortController()
+        const params = await chatParamsFromRequestBody(await request.json())
+        const stream = chat({
+          adapter: openaiText('gpt-5.6'),
+          messages: params.messages,
+          threadId: params.threadId,
+          runId: params.runId,
+          ...(params.parentRunId ? { parentRunId: params.parentRunId } : {}),
+          ...(params.resume ? { resume: params.resume } : {}),
+          systemPrompts: [
+            'For any research question, call the researcher tool. Then answer the user from its result.',
+          ],
+          subagents: { agents: [researcher] },
+          abortController,
+        })
+        return toServerSentEventsResponse(stream, { abortController })
+      },
+    },
+  },
+})
diff --git a/examples/ts-react-chat/src/routes/subagent-brief.tsx b/examples/ts-react-chat/src/routes/subagent-brief.tsx
new file mode 100644
index 0000000000..704e83a75b
--- /dev/null
+++ b/examples/ts-react-chat/src/routes/subagent-brief.tsx
@@ -0,0 +1,135 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { useState } from 'react'
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import type { UIMessage } from '@tanstack/ai-react'
+
+export const Route = createFileRoute('/subagent-brief')({
+  component: SubagentBriefPage,
+})
+
+/** The `task` the parent model wrote on the tool call that started a child. */
+function briefOf(message: UIMessage, toolCallId: string) {
+  for (const part of message.parts) {
+    if (part.type !== 'tool-call' || part.id !== toolCallId) continue
+    const input = part.input
+    if (
+      typeof input === 'object' &&
+      input !== null &&
+      'task' in input &&
+      typeof input.task === 'string'
+    ) {
+      return input.task
+    }
+  }
+  return undefined
+}
+
+function childText(messages: ReadonlyArray<UIMessage>) {
+  return messages
+    .flatMap((message) =>
+      message.parts.flatMap((part) =>
+        part.type === 'text' ? [part.content] : [],
+      ),
+    )
+    .join('')
+}
+
+function SubagentBriefPage() {
+  const { messages, sendMessage, isLoading } = useChat({
+    connection: fetchServerSentEvents('/api/subagent-brief'),
+  })
+  const [input, setInput] = useState(
+    'We picked three sea animals earlier: squid, octopus, and cuttlefish. Find how many hearts each one has.',
+  )
+
+  return (
+    <div style={page}>
+      <h1>Subagent brief</h1>
+      <p style={{ color: '#555' }}>
+        The parent model writes a short task for the <code>researcher</code>{' '}
+        subagent. The researcher reads only that task.
+      </p>
+
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+        {messages.map((message) => (
+          <div key={message.id} data-testid={`message-${message.role}`}>
+            <div style={roleLabel}>{message.role}</div>
+            {message.parts.map((part, index) => {
+              if (part.type === 'text' && part.content) {
+                return (
+                  <p key={index} data-testid="text" style={{ margin: 0 }}>
+                    {part.content}
+                  </p>
+                )
+              }
+              if (part.type !== 'subagent') return null
+              const toolCallId = part.subagent.parentToolCallId
+              return (
+                <section key={index} data-testid="card" style={card}>
+                  <div>
+                    <strong>{part.subagent.name}</strong>{' '}
+                    <span data-testid="card-status">
+                      {part.subagent.status}
+                    </span>
+                  </div>
+                  <div data-testid="brief" style={{ color: '#444' }}>
+                    Brief:{' '}
+                    {toolCallId === undefined
+                      ? '(none)'
+                      : (briefOf(message, toolCallId) ?? '(none)')}
+                  </div>
+                  <p data-testid="card-text" style={{ margin: 0 }}>
+                    {childText(part.subagent.messages)}
+                  </p>
+                </section>
+              )
+            })}
+          </div>
+        ))}
+      </div>
+
+      <form
+        onSubmit={(event) => {
+          event.preventDefault()
+          const text = input.trim()
+          if (!text || isLoading) return
+          setInput('')
+          void sendMessage(text)
+        }}
+        style={{ marginTop: 16, display: 'flex', gap: 8 }}
+      >
+        <input
+          data-testid="input"
+          value={input}
+          onChange={(event) => setInput(event.target.value)}
+          style={{ flex: 1, padding: 8 }}
+        />
+        <button data-testid="send" type="submit" disabled={isLoading}>
+          {isLoading ? 'Running...' : 'Send'}
+        </button>
+      </form>
+    </div>
+  )
+}
+
+const page: React.CSSProperties = {
+  maxWidth: 720,
+  margin: '0 auto',
+  padding: 24,
+  fontFamily: 'system-ui, sans-serif',
+}
+
+const card: React.CSSProperties = {
+  border: '1px solid #ddd',
+  borderRadius: 8,
+  padding: 12,
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+}
+
+const roleLabel: React.CSSProperties = {
+  fontSize: 11,
+  textTransform: 'uppercase',
+  color: '#999',
+}

From e82d79c36e9b2e2f17870949795788217c2d98a2 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 11:40:12 +0200
Subject: [PATCH 005/286] feat(ai): let a subagent return a value and call any
 activity

defineAgent run can now resolve to a plain value (an image result, a
string). The value lands on SUBAGENT_FINISHED.result and goes to the parent
model as the tool result, with very long strings shortened for the model.
run also gets bound activities on ctx (ctx.chat, ctx.generateImage, ...)
that fill in the child ids and abort signal, plus ctx.forward and an
optional produces field. SubagentsBag.binding lets a host add middleware to
every bound call.

RunRecord gets optional harness-session fields (kind, activity, agent,
result, artifacts, principal, leaseOwner, leaseExpiresAt, checkpoint), and
both memory run stores keep them. Also fixes the stale adapter comment about
capabilities.
---
 .changeset/harness-p0-agent-results.md        |   6 +
 docs/chat/subagents.md                        |  51 +++
 docs/config.json                              |   2 +-
 packages/ai-persistence/src/memory.ts         |  30 +-
 packages/ai/src/activities/chat/adapter.ts    |   6 +-
 .../ai/src/activities/chat/agents/bound.ts    | 151 +++++++++
 .../activities/chat/agents/define-agent.ts    |  62 +++-
 .../ai/src/activities/chat/agents/spawn.ts    | 114 ++++++-
 .../src/activities/chat/middleware/index.ts   |   3 +
 .../activities/chat/middleware/run-store.ts   |  80 +++--
 .../src/activities/chat/tools/tool-calls.ts   |  41 ++-
 packages/ai/src/activities/index.ts           |   7 +
 packages/ai/src/client.ts                     |   7 +
 packages/ai/src/index.ts                      |  10 +
 .../ai/tests/define-agent-results.test.ts     | 298 ++++++++++++++++++
 packages/ai/tests/run-record-fields.test.ts   |  57 ++++
 testing/e2e/fixtures/subagents/basic.json     |  31 ++
 testing/e2e/src/lib/subagents-test.ts         |  11 +-
 testing/e2e/src/routes/api.subagents-test.ts  |  18 ++
 testing/e2e/tests/subagents.spec.ts           |  19 +-
 20 files changed, 944 insertions(+), 60 deletions(-)
 create mode 100644 .changeset/harness-p0-agent-results.md
 create mode 100644 packages/ai/src/activities/chat/agents/bound.ts
 create mode 100644 packages/ai/tests/define-agent-results.test.ts
 create mode 100644 packages/ai/tests/run-record-fields.test.ts

diff --git a/.changeset/harness-p0-agent-results.md b/.changeset/harness-p0-agent-results.md
new file mode 100644
index 0000000000..af26a929b6
--- /dev/null
+++ b/.changeset/harness-p0-agent-results.md
@@ -0,0 +1,6 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-persistence': patch
+---
+
+A subagent can now return a plain value and call any activity. `defineAgent`'s `run` can return a promise of any value, such as an image result. The value arrives on `SUBAGENT_FINISHED.result`, and the parent model gets it as the tool result. A very long string in that result (for example a base64 image) reaches the parent model as a short note. `run` also gets the activities on `ctx` (`ctx.chat`, `ctx.generateImage`, `ctx.generateVideo`, and the rest), which fill in the thread id, a run id, and the abort signal, plus `ctx.forward` for a plain `chat()` call. The optional `produces` field says what an agent makes. `RunRecord` gets optional fields for harness sessions (`kind`, `activity`, `agent`, `result`, `artifacts`, `principal`, `leaseOwner`, `leaseExpiresAt`, `checkpoint`), and the memory run stores keep them.
diff --git a/docs/chat/subagents.md b/docs/chat/subagents.md
index de2f4698a3..25a05c6ad2 100644
--- a/docs/chat/subagents.md
+++ b/docs/chat/subagents.md
@@ -206,6 +206,57 @@ const stream = chat({
 
 To show the brief in the UI, see [Show the brief on a card](#show-the-brief-on-a-card).
 
+## Return a value, or call any activity
+
+A child does not have to be a chat. It can make an image, or return a plain value that the parent model reads as the tool result. Call the activity on `ctx` and return what it gives you:
+
+```ts group=subagent-values
+import { chat, defineAgent } from '@tanstack/ai'
+import { openaiImage, openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+const heroImage = defineAgent({
+  name: 'heroImage',
+  description: 'Makes a hero image for a post',
+  produces: 'image',
+  inputSchema: z.object({ prompt: z.string() }),
+  run: (ctx) =>
+    ctx.generateImage({
+      adapter: openaiImage('gpt-image-2'),
+      prompt: `${ctx.input.prompt}. Brand colors: blue and white.`,
+      size: '1536x1024',
+    }),
+})
+
+const stream = chat({
+  adapter: openaiText('gpt-5.6'),
+  messages: [{ role: 'user', content: 'Make a hero image about squids' }],
+  subagents: { agents: [heroImage] },
+})
+```
+
+- `ctx.chat`, `ctx.generateImage`, `ctx.generateVideo`, `ctx.generateSpeech`, and the other activities on `ctx` take the same options as the plain functions. They fill in the thread id, a run id, and the abort signal.
+- `ctx.chat` also uses the parent conversation (`ctx.messages`) when you do not pass `messages`.
+- `run` can return a promise of any value. The value arrives on `SUBAGENT_FINISHED.result`, and the parent model gets it as the tool result.
+- A string result also streams as the child's text, so the card shows it.
+- A very long string in the result (for example a base64 image) reaches the parent model as a short note, `[omitted 5000 characters]`. The full value stays on `SUBAGENT_FINISHED.result`.
+- `produces` says what the agent makes (`'image'`, `'text'`, and so on). It does not change how the agent runs.
+
+When you call the plain `chat()` instead, spread `ctx.forward` to pass the child's ids and abort controller in one line:
+
+```ts group=subagent-values
+const researcher = defineAgent({
+  name: 'researcher',
+  description: 'Looks up facts',
+  run: (ctx) =>
+    chat({
+      adapter: openaiText('gpt-5.6'),
+      messages: ctx.messages,
+      ...ctx.forward,
+    }),
+})
+```
+
 ## Strategy
 
 - `exclusive` (default): the chosen child owns the turn. Main does not answer after it.
diff --git a/docs/config.json b/docs/config.json
index 3c6e1f6f68..420a15ec03 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -155,7 +155,7 @@
           "label": "Subagents",
           "to": "chat/subagents",
           "addedAt": "2026-09-21",
-          "updatedAt": "2026-09-25"
+          "updatedAt": "2026-09-26"
         },
         {
           "label": "Agentic Cycle",
diff --git a/packages/ai-persistence/src/memory.ts b/packages/ai-persistence/src/memory.ts
index 5ab3c85ff7..849e30acf1 100644
--- a/packages/ai-persistence/src/memory.ts
+++ b/packages/ai-persistence/src/memory.ts
@@ -55,15 +55,9 @@ class MemoryMessageStore implements MessageStore {
 
 class MemoryRunStore implements RunStore {
   private readonly runs = new Map<string, RunRecord>()
-  createOrResume(input: {
-    runId: string
-    threadId: string
-    status?: RunRecord['status']
-    startedAt: number
-    parentRunId?: string
-    subagentRunId?: string
-    name?: string
-  }): Promise<RunRecord> {
+  createOrResume(
+    input: Parameters<RunStore['createOrResume']>[0],
+  ): Promise<RunRecord> {
     const existing = this.runs.get(input.runId)
     if (existing) return Promise.resolve(existing)
     const record: RunRecord = {
@@ -78,25 +72,17 @@ class MemoryRunStore implements RunStore {
         ? { subagentRunId: input.subagentRunId }
         : {}),
       ...(input.name !== undefined ? { name: input.name } : {}),
+      ...(input.kind !== undefined ? { kind: input.kind } : {}),
+      ...(input.activity !== undefined ? { activity: input.activity } : {}),
+      ...(input.agent !== undefined ? { agent: input.agent } : {}),
+      ...(input.principal !== undefined ? { principal: input.principal } : {}),
     }
     this.runs.set(record.runId, record)
     return Promise.resolve(record)
   }
   update(
     runId: string,
-    patch: Partial<
-      Pick<
-        RunRecord,
-        | 'status'
-        | 'finishedAt'
-        | 'error'
-        | 'usage'
-        | 'sandboxKey'
-        | 'detachedSince'
-        | 'cancelRequested'
-        | 'driverEpoch'
-      >
-    >,
+    patch: Parameters<RunStore['update']>[1],
   ): Promise<void> {
     const existing = this.runs.get(runId)
     if (existing) this.runs.set(runId, { ...existing, ...patch })
diff --git a/packages/ai/src/activities/chat/adapter.ts b/packages/ai/src/activities/chat/adapter.ts
index 102d297827..dd1b1d2cce 100644
--- a/packages/ai/src/activities/chat/adapter.ts
+++ b/packages/ai/src/activities/chat/adapter.ts
@@ -83,9 +83,9 @@ export interface TextAdapter<
   /**
    * Capabilities this adapter requires at runtime. `chat()` validates that the
    * configured middleware provides each one. Model adapters omit this; harness
-   * adapters (e.g. a future `claudeCode()`) declare e.g. `[sandboxCapability]`.
-   * Runtime access to capabilities from inside the adapter is not yet wired —
-   * this is the declaration/validation surface only.
+   * adapters (for example `claudeCode()`) declare `[sandboxCapability]`.
+   * At runtime the engine passes the provided capabilities to `chatStream` as
+   * `options.capabilities`.
    */
   readonly requires?: ReadonlyArray<CapabilityHandle>
 
diff --git a/packages/ai/src/activities/chat/agents/bound.ts b/packages/ai/src/activities/chat/agents/bound.ts
new file mode 100644
index 0000000000..bc73311b1a
--- /dev/null
+++ b/packages/ai/src/activities/chat/agents/bound.ts
@@ -0,0 +1,151 @@
+import { chat } from '../index'
+import { summarize } from '../../summarize/index'
+import { generateImage } from '../../generateImage/index'
+import { generateVideo } from '../../generateVideo/index'
+import { generateAudio } from '../../generateAudio/index'
+import { generateSpeech } from '../../generateSpeech/index'
+import { generateVoice } from '../../generateVoice/index'
+import { generateTranscription } from '../../generateTranscription/index'
+import { generateWorld } from '../../generateWorld/index'
+import { generateLiveVideo } from '../../generateLiveVideo/index'
+import { embed } from '../../embed/index'
+import { rerank } from '../../rerank/index'
+import { decide } from '../../evaluate/index'
+import type { GenerationMiddleware } from '../../middleware/types'
+import type { AnyChatMiddleware } from '../middleware/types'
+import type { RunAgentResumeItem } from '../../../types'
+import type { SubagentRunInput } from './define-agent'
+
+/**
+ * The fields a child `chat()` needs, in one spread:
+ * `chat({ adapter, messages, ...ctx.forward })`.
+ */
+export interface SubagentForward {
+  threadId: string
+  runId: string
+  parentRunId: string
+  subagentRunId: string
+  resume?: Array<RunAgentResumeItem>
+  /** Aborts when the parent run or the subagent group stops. */
+  abortController: AbortController
+}
+
+/**
+ * What a host (for example a harness session) adds to every activity call an
+ * agent makes through `ctx`. Apps using plain `chat({ subagents })` do not set
+ * it.
+ */
+export interface SubagentBinding {
+  /** Added before the call's own middleware on every `ctx.chat` call. */
+  chatMiddleware?: ReadonlyArray<AnyChatMiddleware>
+  /** Added before the call's own middleware on every generation call. */
+  generationMiddleware?: ReadonlyArray<GenerationMiddleware>
+}
+
+/**
+ * Activity functions bound to one child run. Each takes the same options as
+ * the plain function. Options you pass win over the bound defaults.
+ */
+export interface BoundActivities {
+  chat: typeof chat
+  summarize: typeof summarize
+  generateImage: typeof generateImage
+  generateVideo: typeof generateVideo
+  generateAudio: typeof generateAudio
+  generateSpeech: typeof generateSpeech
+  generateVoice: typeof generateVoice
+  generateTranscription: typeof generateTranscription
+  generateWorld: typeof generateWorld
+  generateLiveVideo: typeof generateLiveVideo
+  embed: typeof embed
+  rerank: typeof rerank
+  decide: typeof decide
+}
+
+/** Options every bound call can receive. Typed loosely: each wrapper forwards
+ *  to a function whose own signature checks the caller. */
+type LooseOptions = Record<string, any> & {
+  middleware?: Array<unknown>
+}
+
+export function createBoundActivities(
+  input: SubagentRunInput,
+  abortController: AbortController,
+  binding?: SubagentBinding,
+): BoundActivities {
+  let calls = 0
+  const signal = abortController.signal
+  const chatMiddleware = binding?.chatMiddleware ?? []
+  const generationMiddleware = binding?.generationMiddleware ?? []
+
+  // Every generation call gets its own run id under the child run.
+  const ids = (activity: string) => {
+    calls += 1
+    return {
+      threadId: input.threadId,
+      runId: `${input.runId}:${activity}-${calls}`,
+    }
+  }
+  const withGenerationMiddleware = (options: LooseOptions) => ({
+    ...options,
+    middleware: [...generationMiddleware, ...(options.middleware ?? [])],
+  })
+  // Activities that accept thread and run ids plus an abort signal.
+  const full = (activity: string, options: LooseOptions) =>
+    withGenerationMiddleware({
+      ...ids(activity),
+      abortSignal: signal,
+      ...options,
+    })
+
+  return {
+    chat: ((options: LooseOptions) =>
+      chat({
+        messages: input.messages,
+        threadId: input.threadId,
+        runId: input.runId,
+        parentRunId: input.parentRunId,
+        subagentRunId: input.subagentRunId,
+        ...(input.resume ? { resume: input.resume } : {}),
+        abortController,
+        ...options,
+        middleware: [...chatMiddleware, ...(options.middleware ?? [])],
+      } as never)) as typeof chat,
+    summarize: ((options: LooseOptions) =>
+      summarize(full('summarize', options) as never)) as typeof summarize,
+    generateImage: ((options: LooseOptions) =>
+      generateImage(full('image', options) as never)) as typeof generateImage,
+    generateVideo: ((options: LooseOptions) =>
+      generateVideo(full('video', options) as never)) as typeof generateVideo,
+    generateAudio: ((options: LooseOptions) =>
+      generateAudio(full('audio', options) as never)) as typeof generateAudio,
+    generateSpeech: ((options: LooseOptions) =>
+      generateSpeech(
+        full('speech', options) as never,
+      )) as typeof generateSpeech,
+    generateVoice: ((options: LooseOptions) =>
+      generateVoice(full('voice', options) as never)) as typeof generateVoice,
+    generateTranscription: ((options: LooseOptions) =>
+      generateTranscription(
+        full('transcription', options) as never,
+      )) as typeof generateTranscription,
+    generateWorld: ((options: LooseOptions) =>
+      generateWorld(full('world', options) as never)) as typeof generateWorld,
+    generateLiveVideo: ((options: LooseOptions) =>
+      generateLiveVideo(
+        full('liveVideo', options) as never,
+      )) as typeof generateLiveVideo,
+    // `embed` takes neither ids nor an abort signal.
+    embed: ((options: LooseOptions) =>
+      embed(withGenerationMiddleware(options) as never)) as typeof embed,
+    // `rerank` and `decide` take an abort signal but no ids.
+    rerank: ((options: LooseOptions) =>
+      rerank(
+        withGenerationMiddleware({ abortSignal: signal, ...options }) as never,
+      )) as typeof rerank,
+    decide: ((options: LooseOptions) =>
+      decide(
+        withGenerationMiddleware({ abortSignal: signal, ...options }) as never,
+      )) as typeof decide,
+  }
+}
diff --git a/packages/ai/src/activities/chat/agents/define-agent.ts b/packages/ai/src/activities/chat/agents/define-agent.ts
index e9822f64b8..0c6ea78b38 100644
--- a/packages/ai/src/activities/chat/agents/define-agent.ts
+++ b/packages/ai/src/activities/chat/agents/define-agent.ts
@@ -10,12 +10,13 @@ import type {
   UIMessage,
 } from '../../../types'
 import type { AnyClientTool } from '../tools/tool-definition'
+import type { BoundActivities, SubagentForward } from './bound'
 
 /**
- * Context the library passes into {@link defineAgent} `run`.
+ * What the library knows about a child run before `run` starts.
  * `TInput` is the agent's `inputSchema`.
  */
-export interface SubagentRunContext<
+export interface SubagentRunInput<
   TInput extends SchemaInput | undefined = any,
 > {
   /**
@@ -45,6 +46,35 @@ export interface SubagentRunContext<
   parentSubagentRunId?: string
 }
 
+/**
+ * Context the library passes into {@link defineAgent} `run`.
+ *
+ * - `forward` holds the fields a child `chat()` needs, in one spread:
+ *   `chat({ adapter, messages, ...ctx.forward })`.
+ * - The activity functions (`ctx.chat`, `ctx.generateImage`, and the rest)
+ *   take the same options as the plain functions and fill in the thread id,
+ *   a run id, the abort signal, and any middleware a host adds.
+ */
+export type SubagentRunContext<TInput extends SchemaInput | undefined = any> =
+  SubagentRunInput<TInput> & BoundActivities & { forward: SubagentForward }
+
+/**
+ * What an agent makes. Informative: plugins use it to find an agent by the
+ * kind of output it produces.
+ */
+export type AgentProduces =
+  | 'text'
+  | 'image'
+  | 'video'
+  | 'audio'
+  | 'speech'
+  | 'voice'
+  | 'transcription'
+  | 'embedding'
+  | 'world'
+  | 'liveVideo'
+  | (string & {})
+
 /**
  * A tool a child agent can carry into client part types.
  * Server tools and client tools both qualify.
@@ -52,9 +82,10 @@ export interface SubagentRunContext<
 export type SubagentTool = AnyTool | AnyClientTool
 
 /**
- * A named child agent. `run` is a `chat()` call (or any stream of AG-UI chunks).
+ * A named child agent. `run` is a `chat()` call (or any stream of AG-UI
+ * chunks), or a promise of a plain value such as an image result.
  * `TTools` and `TSchema` stay on the object so `useChat({ subagents })` can
- * type that child's parts.
+ * type that child's parts. `TResult` is the value a promise `run` resolves to.
  */
 export interface DefinedAgent<
   TName extends string = string,
@@ -63,13 +94,20 @@ export interface DefinedAgent<
   TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
     ReadonlyArray<InterruptDefinition<any, any, any, any>>,
   TInput extends SchemaInput | undefined = any,
+  TResult = unknown,
+  TProduces extends AgentProduces | undefined = AgentProduces | undefined,
 > extends AGUISubagentInfo {
   name: TName
   /** Required here: the router and the synthetic tool both read it. */
   description: string
   run: (
     ctx: SubagentRunContext<TInput>,
-  ) => AsyncIterable<StreamChunk> | Promise<AsyncIterable<StreamChunk>>
+  ) =>
+    | AsyncIterable<StreamChunk>
+    | Promise<AsyncIterable<StreamChunk>>
+    | Promise<TResult>
+  /** What this agent makes. See {@link AgentProduces}. */
+  produces?: TProduces
   /**
    * The input the parent model writes when it calls this agent's tool, such
    * as a short brief. `run` reads it as `ctx.input`. Tool mode only: a
@@ -121,7 +159,19 @@ export function defineAgent<
     InterruptDefinition<any, any, any, any>
   > = readonly [],
   TInput extends SchemaInput | undefined = undefined,
->(agent: DefinedAgent<TName, TTools, TSchema, TInterrupts, TInput>) {
+  TResult = unknown,
+  const TProduces extends AgentProduces | undefined = undefined,
+>(
+  agent: DefinedAgent<
+    TName,
+    TTools,
+    TSchema,
+    TInterrupts,
+    TInput,
+    TResult,
+    TProduces
+  >,
+) {
   if (agent.name.trim() === '') {
     throw new Error('defineAgent requires a non-empty name')
   }
diff --git a/packages/ai/src/activities/chat/agents/spawn.ts b/packages/ai/src/activities/chat/agents/spawn.ts
index 18e712007a..0b3733de42 100644
--- a/packages/ai/src/activities/chat/agents/spawn.ts
+++ b/packages/ai/src/activities/chat/agents/spawn.ts
@@ -25,7 +25,13 @@ import type {
   Tool,
   UIMessage,
 } from '../../../types'
-import type { DefinedAgent, SubagentRunContext } from './define-agent'
+import { createBoundActivities } from './bound'
+import type { SubagentBinding } from './bound'
+import type {
+  DefinedAgent,
+  SubagentRunContext,
+  SubagentRunInput,
+} from './define-agent'
 import type { ChatMiddleware } from '../middleware/types'
 import type { SubagentTurn } from './turn'
 
@@ -75,6 +81,12 @@ export interface SubagentsBag<
    */
   order?: 'parallel' | 'sequence'
   sandbox?: 'own' | 'inherit'
+  /**
+   * What a host adds to every activity call a child makes through `ctx`
+   * (`ctx.chat`, `ctx.generateImage`, and the rest). A harness session sets
+   * it. Apps do not.
+   */
+  binding?: SubagentBinding
 }
 
 /** What the children of one parent run left behind for the parent terminal. */
@@ -261,6 +273,7 @@ function openAgentStream(
     },
     sink,
     parentToolCallId,
+    bag.binding,
   )
 }
 
@@ -402,12 +415,87 @@ export function withChildUsage(
   return withTanstackMetadata(next, { usage: leftover }) as ParentTerminal
 }
 
+function isAsyncIterable(value: unknown): value is AsyncIterable<StreamChunk> {
+  return (
+    typeof value === 'object' && value !== null && Symbol.asyncIterator in value
+  )
+}
+
+/**
+ * Chunks for an agent whose `run` resolved to a plain value instead of a
+ * stream. A string also streams as the child's text, so the parent model, a
+ * `sequence` router, and the UI all read it like chat output.
+ */
+function* valueResultChunks(
+  value: unknown,
+  id: string,
+): Generator<StreamChunk> {
+  if (typeof value === 'string' && value !== '') {
+    const messageId = `${id}-text`
+    const timestamp = Date.now()
+    yield attributeChunk(
+      {
+        type: EventType.TEXT_MESSAGE_START,
+        messageId,
+        role: 'assistant',
+        timestamp,
+      },
+      id,
+    )
+    yield attributeChunk(
+      {
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId,
+        delta: value,
+        timestamp,
+      },
+      id,
+    )
+    yield attributeChunk(
+      { type: EventType.TEXT_MESSAGE_END, messageId, timestamp },
+      id,
+    )
+  }
+  yield {
+    type: SUBAGENT_FINISHED,
+    subagentRunId: id,
+    ...(value !== undefined ? { result: value } : {}),
+    timestamp: Date.now(),
+  } satisfies SubagentFinishedEvent
+}
+
+/**
+ * Build the context `run` receives: the spawn input plus `forward` and the
+ * bound activity functions.
+ */
+function runContext(
+  input: SubagentRunInput,
+  abortController: AbortController,
+  binding?: SubagentBinding,
+): SubagentRunContext {
+  return {
+    ...input,
+    forward: {
+      threadId: input.threadId,
+      runId: input.runId,
+      parentRunId: input.parentRunId,
+      subagentRunId: input.subagentRunId,
+      ...(input.resume ? { resume: input.resume } : {}),
+      abortController,
+    },
+    ...createBoundActivities(input, abortController, binding),
+  }
+}
+
 export async function* spawnAgentStream(
   agent: DefinedAgent,
-  ctx: SubagentRunContext,
+  input: SubagentRunInput,
   sink?: SubagentSink,
   parentToolCallId?: string,
+  binding?: SubagentBinding,
 ): AsyncIterable<StreamChunk> {
+  const link = linkAbort(input.abortSignal)
+  const ctx = runContext(input, link.controller, binding)
   const id = ctx.subagentRunId
   yield {
     type: SUBAGENT_STARTED,
@@ -428,11 +516,19 @@ export async function* spawnAgentStream(
       yield stoppedEvent(id)
       return
     }
-    const stream = await orAbort(
+    const produced: unknown = await orAbort(
       Promise.resolve(agent.run(ctx)),
       ctx.abortSignal,
     )
-    iterator = stream[Symbol.asyncIterator]()
+    if (!isAsyncIterable(produced)) {
+      if (ctx.abortSignal?.aborted) {
+        yield stoppedEvent(id)
+        return
+      }
+      yield* valueResultChunks(produced, id)
+      return
+    }
+    iterator = produced[Symbol.asyncIterator]()
     while (true) {
       if (ctx.abortSignal?.aborted) {
         yield stoppedEvent(id)
@@ -522,6 +618,7 @@ export async function* spawnAgentStream(
     } catch {
       // Child stream may already be closed or aborted.
     }
+    link.dispose()
   }
 }
 
@@ -760,6 +857,7 @@ export function createSyntheticSubagentTools(
       let subagentRunId = suspended?.subagentRunId ?? ''
       let text = suspended?.text ?? ''
       let error: string | undefined
+      let result: unknown
       try {
         for await (const chunk of openAgentStream(
           entry,
@@ -792,6 +890,13 @@ export function createSyntheticSubagentTools(
           ) {
             error = chunk.message
           }
+          if (
+            chunk.type === SUBAGENT_FINISHED &&
+            chunk.subagentRunId === subagentRunId &&
+            chunk.result !== undefined
+          ) {
+            result = chunk.result
+          }
           toolContext?.[EMIT_STREAM_CHUNK]?.(chunk)
         }
       } finally {
@@ -806,6 +911,7 @@ export function createSyntheticSubagentTools(
       return {
         subagentRunId,
         text,
+        ...(result !== undefined ? { result } : {}),
         ...(error !== undefined ? { error } : {}),
         ...(sink.interrupts.length > 0 ? { interrupts: sink.interrupts } : {}),
       } satisfies SubagentToolOutcome
diff --git a/packages/ai/src/activities/chat/middleware/index.ts b/packages/ai/src/activities/chat/middleware/index.ts
index 53da815b24..2c4b8a7fbd 100644
--- a/packages/ai/src/activities/chat/middleware/index.ts
+++ b/packages/ai/src/activities/chat/middleware/index.ts
@@ -80,6 +80,9 @@ export type {
   RunStatus,
   TerminalRunStatus,
   RunRecord,
+  RunKind,
+  RunArtifactRef,
+  RunCheckpoint,
   RunError,
   RunStore,
 } from './run-store'
diff --git a/packages/ai/src/activities/chat/middleware/run-store.ts b/packages/ai/src/activities/chat/middleware/run-store.ts
index 93d2361e8a..77847a74d9 100644
--- a/packages/ai/src/activities/chat/middleware/run-store.ts
+++ b/packages/ai/src/activities/chat/middleware/run-store.ts
@@ -176,6 +176,54 @@ export interface RunRecord {
    * loser nothing to read. Absent on a run that was never claimed.
    */
   driverEpoch?: number
+  /**
+   * What kind of work this run is, when a harness session recorded it:
+   * a chat turn, an agent run, one activity call inside an agent, a user
+   * command, or a compaction. Absent on runs recorded by plain `chat()`.
+   */
+  kind?: RunKind
+  /** The activity of a `kind: 'activity'` run (`'image'`, `'chat'`, ...). */
+  activity?: string
+  /** The agent name of a `kind: 'agent'` run. */
+  agent?: string
+  /** Terminal result metadata (ids, urls, text). Never media bytes. */
+  result?: unknown
+  /** Durable artifact references produced by this run. */
+  artifacts?: Array<RunArtifactRef>
+  /** Who started this run, from the host's `authorize`. */
+  principal?: { id: string }
+  /**
+   * The host that currently drives this run, and when its claim expires. The
+   * driver renews `leaseExpiresAt`. Another host may resume the run after it
+   * passes. Pairs with `driverEpoch` for fencing.
+   */
+  leaseOwner?: string
+  leaseExpiresAt?: number
+  /** Crash-resume data saved at the last model or tool boundary. */
+  checkpoint?: RunCheckpoint
+}
+
+/** Kinds of work a harness session records. */
+export type RunKind = 'chat' | 'agent' | 'activity' | 'command' | 'compact'
+
+/** A durable artifact a run produced. */
+export interface RunArtifactRef {
+  artifactId: string
+  name?: string
+  mimeType?: string
+  url?: string
+}
+
+/** What a run saved at its last model or tool boundary. */
+export interface RunCheckpoint {
+  /** Epoch ms of the checkpoint. */
+  at: number
+  /** Tools that started but had no result yet at the checkpoint. */
+  pendingTools?: Array<{
+    toolCallId: string
+    name: string
+    replay: 'safe' | 'never'
+  }>
 }
 
 /**
@@ -211,7 +259,7 @@ export interface RunStore {
       parentRunId?: string
       subagentRunId?: string
       name?: string
-    },
+    } & Partial<Pick<RunRecord, 'kind' | 'activity' | 'agent' | 'principal'>>,
   ) => Promise<RunRecord>
   /**
    * Patch a record's mutable fields.
@@ -232,6 +280,11 @@ export interface RunStore {
         | 'detachedSince'
         | 'cancelRequested'
         | 'driverEpoch'
+        | 'result'
+        | 'artifacts'
+        | 'leaseOwner'
+        | 'leaseExpiresAt'
+        | 'checkpoint'
       >
     >,
   ) => Promise<void>
@@ -371,12 +424,7 @@ export class InMemoryRunStore implements RunStore {
   private readonly runs = new Map<string, RunRecord>()
 
   createOrResume(
-    input: Pick<RunRecord, 'runId' | 'threadId' | 'startedAt'> & {
-      status?: RunStatus
-      parentRunId?: string
-      subagentRunId?: string
-      name?: string
-    },
+    input: Parameters<RunStore['createOrResume']>[0],
   ): Promise<RunRecord> {
     const existing = this.runs.get(input.runId)
     if (existing) return Promise.resolve(existing)
@@ -392,6 +440,10 @@ export class InMemoryRunStore implements RunStore {
         ? { subagentRunId: input.subagentRunId }
         : {}),
       ...(input.name !== undefined ? { name: input.name } : {}),
+      ...(input.kind !== undefined ? { kind: input.kind } : {}),
+      ...(input.activity !== undefined ? { activity: input.activity } : {}),
+      ...(input.agent !== undefined ? { agent: input.agent } : {}),
+      ...(input.principal !== undefined ? { principal: input.principal } : {}),
     }
     this.runs.set(record.runId, record)
     return Promise.resolve(record)
@@ -399,19 +451,7 @@ export class InMemoryRunStore implements RunStore {
 
   update(
     runId: string,
-    patch: Partial<
-      Pick<
-        RunRecord,
-        | 'status'
-        | 'finishedAt'
-        | 'error'
-        | 'usage'
-        | 'sandboxKey'
-        | 'detachedSince'
-        | 'cancelRequested'
-        | 'driverEpoch'
-      >
-    >,
+    patch: Parameters<RunStore['update']>[1],
   ): Promise<void> {
     const existing = this.runs.get(runId)
     if (existing) this.runs.set(runId, { ...existing, ...patch })
diff --git a/packages/ai/src/activities/chat/tools/tool-calls.ts b/packages/ai/src/activities/chat/tools/tool-calls.ts
index 2315ae5225..5293c2df7c 100644
--- a/packages/ai/src/activities/chat/tools/tool-calls.ts
+++ b/packages/ai/src/activities/chat/tools/tool-calls.ts
@@ -56,6 +56,12 @@ export const EMIT_STREAM_CHUNK = Symbol.for('tanstack.ai.emitStreamChunk')
 export interface SubagentToolOutcome {
   subagentRunId: string
   text: string
+  /**
+   * The child's typed result: the value a promise `run` resolved to, or the
+   * `RUN_FINISHED.result` of a child stream. When set, the parent model gets
+   * this instead of the child's text.
+   */
+  result?: unknown
   error?: string
   /** Set when the child stopped for outside input. The tool call stays open. */
   interrupts?: Array<Interrupt>
@@ -65,6 +71,33 @@ function isSubagentTool(tool: AnyTool): boolean {
   return (tool as { [SUBAGENT_TOOL]?: true })[SUBAGENT_TOOL] === true
 }
 
+/** Longest string a subagent result sends to the parent model unchanged. */
+const MODEL_RESULT_MAX_STRING = 2048
+
+/**
+ * A copy of a subagent result that is safe to send to the parent model.
+ * A string longer than {@link MODEL_RESULT_MAX_STRING} (for example a base64
+ * image) becomes a short note, so one image result cannot fill the context.
+ * The full result still travels on `SUBAGENT_FINISHED` for the UI.
+ */
+export function compactForModel(value: unknown, depth = 0): unknown {
+  if (typeof value === 'string') {
+    return value.length > MODEL_RESULT_MAX_STRING
+      ? `[omitted ${value.length} characters]`
+      : value
+  }
+  if (depth > 20 || typeof value !== 'object' || value === null) return value
+  if (Array.isArray(value)) {
+    return value.map((item) => compactForModel(item, depth + 1))
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      key,
+      compactForModel(item, depth + 1),
+    ]),
+  )
+}
+
 /**
  * MCP Apps metadata attached to a server tool at discovery (see
  * `@tanstack/ai-mcp` discovery + `MCPManager.discover()`).
@@ -672,7 +705,13 @@ export async function* executeServerTool<TContext = unknown>(
       }
       const modelResult = outcome.error
         ? { subagentRunId: outcome.subagentRunId, error: outcome.error }
-        : { subagentRunId: outcome.subagentRunId, result: outcome.text }
+        : {
+            subagentRunId: outcome.subagentRunId,
+            result:
+              outcome.result !== undefined
+                ? compactForModel(outcome.result)
+                : outcome.text,
+          }
       results.push({
         toolCallId: toolCall.id,
         toolName,
diff --git a/packages/ai/src/activities/index.ts b/packages/ai/src/activities/index.ts
index 2e7f298748..c2d9013816 100644
--- a/packages/ai/src/activities/index.ts
+++ b/packages/ai/src/activities/index.ts
@@ -45,7 +45,14 @@ export {
   type DefinedAgent,
   type SubagentChoiceOptions,
   type SubagentRunContext,
+  type SubagentRunInput,
+  type AgentProduces,
 } from './chat/agents/define-agent'
+export type {
+  BoundActivities,
+  SubagentBinding,
+  SubagentForward,
+} from './chat/agents/bound'
 export { subagentRoute, type SubagentRouteOptions } from './chat/agents/route'
 export type {
   SubagentOrder,
diff --git a/packages/ai/src/client.ts b/packages/ai/src/client.ts
index be1d03f72d..e6ab3963da 100644
--- a/packages/ai/src/client.ts
+++ b/packages/ai/src/client.ts
@@ -231,7 +231,14 @@ export {
   type DefinedAgent,
   type SubagentChoiceOptions,
   type SubagentRunContext,
+  type SubagentRunInput,
+  type AgentProduces,
 } from './activities/chat/agents/define-agent'
+export type {
+  BoundActivities,
+  SubagentBinding,
+  SubagentForward,
+} from './activities/chat/agents/bound'
 export {
   subagentRoute,
   type SubagentRouteOptions,
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index 30f7001403..bb2055aa0c 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -91,7 +91,14 @@ export {
   type DefinedAgent,
   type SubagentChoiceOptions,
   type SubagentRunContext,
+  type SubagentRunInput,
+  type AgentProduces,
 } from './activities/chat/agents/define-agent'
+export type {
+  BoundActivities,
+  SubagentBinding,
+  SubagentForward,
+} from './activities/chat/agents/bound'
 export {
   subagentRoute,
   type SubagentRouteOptions,
@@ -367,6 +374,9 @@ export type {
   RunStatus,
   TerminalRunStatus,
   RunRecord,
+  RunKind,
+  RunArtifactRef,
+  RunCheckpoint,
   RunError,
   RunStore,
 } from './activities/chat/middleware/index'
diff --git a/packages/ai/tests/define-agent-results.test.ts b/packages/ai/tests/define-agent-results.test.ts
new file mode 100644
index 0000000000..647f1bbdfb
--- /dev/null
+++ b/packages/ai/tests/define-agent-results.test.ts
@@ -0,0 +1,298 @@
+import { describe, expect, expectTypeOf, it, vi } from 'vitest'
+import { z } from 'zod'
+import { defineAgent } from '../src/activities/chat/agents/define-agent'
+import { chat } from '../src/activities/chat'
+import { compactForModel } from '../src/activities/chat/tools/tool-calls'
+import { collectChunks, createMockAdapter, ev } from './test-utils'
+import type { ImageAdapter } from '../src/activities/generateImage/adapter'
+import type { GenerationMiddleware } from '../src/activities/middleware/types'
+import type { ChatMiddleware } from '../src/activities/chat/middleware/types'
+import type { DefinedAgent } from '../src/activities/chat/agents/define-agent'
+import type { StreamChunk } from '../src/types'
+
+/** A parent model that calls `agentName` once with `args`, then answers. */
+function parentCalling(agentName: string, args = '{}') {
+  return createMockAdapter({
+    iterations: [
+      [
+        ev.runStarted(),
+        ev.toolStart('call_1', agentName),
+        ev.toolArgs('call_1', args),
+        ev.runFinished('tool_calls'),
+      ],
+      [ev.runStarted(), ev.runFinished('stop')],
+    ],
+  })
+}
+
+async function runParent(
+  agent: DefinedAgent<any, any, any, any, any, any, any>,
+  binding?: {
+    chatMiddleware?: Array<ChatMiddleware>
+    generationMiddleware?: Array<GenerationMiddleware>
+  },
+) {
+  const { adapter } = parentCalling(agent.name)
+  return collectChunks(
+    chat({
+      adapter,
+      messages: [{ role: 'user', content: 'Go' }],
+      threadId: 'thread-p',
+      runId: 'run-p',
+      subagents: { agents: [agent], ...(binding ? { binding } : {}) },
+    }) as AsyncIterable<StreamChunk>,
+  )
+}
+
+function toolResult(chunks: Array<StreamChunk>): unknown {
+  const chunk = chunks.find(
+    (entry) =>
+      entry.type === 'TOOL_CALL_RESULT' && entry.toolCallId === 'call_1',
+  )
+  if (chunk?.type !== 'TOOL_CALL_RESULT' || typeof chunk.content !== 'string') {
+    throw new Error('no tool result')
+  }
+  return JSON.parse(chunk.content)
+}
+
+function finished(chunks: Array<StreamChunk>) {
+  const chunk = chunks.find((entry) => entry.type === 'SUBAGENT_FINISHED')
+  if (chunk?.type !== 'SUBAGENT_FINISHED') throw new Error('no finish')
+  return chunk
+}
+
+function imageAdapter(generateImages = vi.fn()): ImageAdapter {
+  generateImages.mockResolvedValue({
+    id: 'img-1',
+    model: 'test-model',
+    images: [{ url: 'https://example.com/a.png' }],
+  })
+  return {
+    kind: 'image' as const,
+    name: 'test-image',
+    model: 'test-model',
+    '~types': {} as any,
+    generateImages,
+  }
+}
+
+describe('defineAgent promise results', () => {
+  it('sends a promise result to the parent model and on SUBAGENT_FINISHED', async () => {
+    const agent = defineAgent({
+      name: 'pricer',
+      description: 'Returns a price',
+      run: () => Promise.resolve({ price: 42, currency: 'EUR' }),
+    })
+
+    const chunks = await runParent(agent)
+
+    expect(finished(chunks).result).toEqual({ price: 42, currency: 'EUR' })
+    expect(toolResult(chunks)).toMatchObject({
+      result: { price: 42, currency: 'EUR' },
+    })
+  })
+
+  it('streams a string result as the child text', async () => {
+    const agent = defineAgent({
+      name: 'titler',
+      description: 'Writes a title',
+      run: () => Promise.resolve('A short title'),
+    })
+
+    const chunks = await runParent(agent)
+    const started = chunks.find((entry) => entry.type === 'SUBAGENT_STARTED')
+    const text = chunks.find(
+      (entry) =>
+        entry.type === 'TEXT_MESSAGE_CONTENT' && 'subagentRunId' in entry,
+    )
+
+    expect(text).toMatchObject({
+      delta: 'A short title',
+      subagentRunId:
+        started?.type === 'SUBAGENT_STARTED' ? started.subagentRunId : 'none',
+    })
+    expect(toolResult(chunks)).toMatchObject({ result: 'A short title' })
+  })
+
+  it('shortens long strings for the model but keeps them on SUBAGENT_FINISHED', async () => {
+    const b64 = 'a'.repeat(5000)
+    const agent = defineAgent({
+      name: 'painter',
+      description: 'Paints',
+      run: () => Promise.resolve({ images: [{ b64Json: b64 }] }),
+    })
+
+    const chunks = await runParent(agent)
+
+    expect(finished(chunks).result).toEqual({ images: [{ b64Json: b64 }] })
+    expect(toolResult(chunks)).toMatchObject({
+      result: { images: [{ b64Json: '[omitted 5000 characters]' }] },
+    })
+  })
+
+  it('reports a rejected promise as SUBAGENT_ERROR', async () => {
+    const agent = defineAgent({
+      name: 'broken',
+      description: 'Fails',
+      run: () => Promise.reject(new Error('provider down')),
+    })
+
+    const chunks = await runParent(agent)
+    const error = chunks.find((entry) => entry.type === 'SUBAGENT_ERROR')
+
+    expect(error).toMatchObject({ message: 'provider down' })
+    expect(toolResult(chunks)).toMatchObject({ error: 'provider down' })
+  })
+})
+
+describe('agent run context', () => {
+  it('gives run ctx.forward with the child ids and an abort controller', async () => {
+    const seen: Array<unknown> = []
+    const agent = defineAgent({
+      name: 'probe',
+      description: 'Records ctx.forward',
+      run: (ctx) => {
+        seen.push({
+          threadId: ctx.forward.threadId,
+          runId: ctx.forward.runId,
+          parentRunId: ctx.forward.parentRunId,
+          subagentRunId: ctx.forward.subagentRunId,
+          aborted: ctx.forward.abortController.signal.aborted,
+        })
+        return Promise.resolve('ok')
+      },
+    })
+
+    await runParent(agent)
+
+    expect(seen).toEqual([
+      expect.objectContaining({
+        threadId: 'thread-p:probe',
+        parentRunId: 'run-p',
+        aborted: false,
+      }),
+    ])
+    const forward = seen[0] as { runId: string; subagentRunId: string }
+    expect(forward.runId).toBe(`run-p:${forward.subagentRunId}`)
+  })
+
+  it('runs ctx.chat with the child ids, the parent messages, and host middleware', async () => {
+    const child = createMockAdapter({
+      iterations: [
+        [
+          ev.runStarted(),
+          ev.textStart('m'),
+          ev.textContent('child says hi', 'm'),
+          ev.textEnd('m'),
+          ev.runFinished('stop'),
+        ],
+      ],
+    })
+    const onStart = vi.fn()
+    const agent = defineAgent({
+      name: 'helper',
+      description: 'Uses ctx.chat',
+      run: (ctx) => ctx.chat({ adapter: child.adapter }),
+    })
+
+    const chunks = await runParent(agent, {
+      chatMiddleware: [{ name: 'host', onStart }],
+    })
+
+    expect(onStart).toHaveBeenCalledTimes(1)
+    const hostCtx = onStart.mock.calls[0]?.[0] as {
+      threadId: string
+      subagentRunId?: string
+    }
+    expect(hostCtx.threadId).toBe('thread-p:helper')
+    expect(hostCtx.subagentRunId).toBeDefined()
+    expect(child.calls[0]?.messages).toEqual(
+      expect.arrayContaining([expect.objectContaining({ content: 'Go' })]),
+    )
+    expect(toolResult(chunks)).toMatchObject({ result: 'child says hi' })
+  })
+
+  it('runs ctx.generateImage with a child run id, the abort signal, and host middleware', async () => {
+    const generateImages = vi.fn()
+    const adapter = imageAdapter(generateImages)
+    const onStart = vi.fn()
+    const agent = defineAgent({
+      name: 'illustrator',
+      description: 'Makes an image',
+      produces: 'image',
+      inputSchema: z.object({ prompt: z.string() }),
+      run: (ctx) =>
+        ctx.generateImage({
+          adapter,
+          prompt: ctx.input.prompt,
+          size: '1024x1024',
+        }),
+    })
+
+    const { adapter: parent } = parentCalling(
+      'illustrator',
+      '{"prompt":"a cat"}',
+    )
+    const chunks = await collectChunks(
+      chat({
+        adapter: parent,
+        messages: [{ role: 'user', content: 'Draw' }],
+        threadId: 'thread-p',
+        runId: 'run-p',
+        subagents: {
+          agents: [agent],
+          binding: { generationMiddleware: [{ name: 'host', onStart }] },
+        },
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect(generateImages).toHaveBeenCalledWith(
+      expect.objectContaining({ prompt: 'a cat', size: '1024x1024' }),
+    )
+    const request = generateImages.mock.calls[0]?.[0] as {
+      abortSignal?: AbortSignal
+      threadId?: unknown
+    }
+    expect(request.abortSignal).toBeInstanceOf(AbortSignal)
+    // Ids and middleware stay in the activity; the adapter never sees them.
+    expect(request.threadId).toBeUndefined()
+    const genCtx = onStart.mock.calls[0]?.[0] as {
+      threadId: string
+      runId: string
+    }
+    expect(genCtx.threadId).toBe('thread-p:illustrator')
+    expect(genCtx.runId).toMatch(/^run-p:subagent-.+:image-1$/)
+    expect(finished(chunks).result).toMatchObject({
+      images: [{ url: 'https://example.com/a.png' }],
+    })
+  })
+})
+
+describe('agent types', () => {
+  it('keeps produces as a literal and infers a promise result', () => {
+    const agent = defineAgent({
+      name: 'counter',
+      description: 'Counts',
+      produces: 'text',
+      run: () => Promise.resolve({ count: 1 }),
+    })
+
+    expectTypeOf(agent.produces).toEqualTypeOf<'text' | undefined>()
+    expectTypeOf(agent.run).returns.toMatchTypeOf<
+      AsyncIterable<StreamChunk> | Promise<unknown>
+    >()
+  })
+})
+
+describe('compactForModel', () => {
+  it('keeps short values and shortens long strings at any depth', () => {
+    expect(
+      compactForModel({ a: 'x', b: [{ c: 'y'.repeat(3000) }], n: 1, z: null }),
+    ).toEqual({
+      a: 'x',
+      b: [{ c: '[omitted 3000 characters]' }],
+      n: 1,
+      z: null,
+    })
+  })
+})
diff --git a/packages/ai/tests/run-record-fields.test.ts b/packages/ai/tests/run-record-fields.test.ts
new file mode 100644
index 0000000000..4276de9a2d
--- /dev/null
+++ b/packages/ai/tests/run-record-fields.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest'
+import { InMemoryRunStore } from '../src/activities/chat/middleware/run-store'
+
+describe('RunRecord harness fields', () => {
+  it('stores kind, activity, agent, and principal on first create only', async () => {
+    const store = new InMemoryRunStore()
+
+    await store.createOrResume({
+      runId: 'op-1',
+      threadId: 't-1',
+      startedAt: 1,
+      kind: 'activity',
+      activity: 'image',
+      agent: 'heroImage',
+      principal: { id: 'user-1' },
+    })
+    // A resume must not change identity fields.
+    const again = await store.createOrResume({
+      runId: 'op-1',
+      threadId: 't-1',
+      startedAt: 2,
+      kind: 'chat',
+    })
+
+    expect(again).toMatchObject({
+      kind: 'activity',
+      activity: 'image',
+      agent: 'heroImage',
+      principal: { id: 'user-1' },
+      startedAt: 1,
+    })
+  })
+
+  it('patches result, artifacts, lease, and checkpoint', async () => {
+    const store = new InMemoryRunStore()
+    await store.createOrResume({ runId: 'op-2', threadId: 't-1', startedAt: 1 })
+
+    await store.update('op-2', {
+      result: { url: 'https://example.com/a.png' },
+      artifacts: [{ artifactId: 'art-1', mimeType: 'image/png' }],
+      leaseOwner: 'host-a',
+      leaseExpiresAt: 30_000,
+      checkpoint: {
+        at: 10,
+        pendingTools: [{ toolCallId: 'c1', name: 'deploy', replay: 'never' }],
+      },
+    })
+
+    expect(await store.get('op-2')).toMatchObject({
+      result: { url: 'https://example.com/a.png' },
+      artifacts: [{ artifactId: 'art-1', mimeType: 'image/png' }],
+      leaseOwner: 'host-a',
+      leaseExpiresAt: 30_000,
+      checkpoint: { at: 10, pendingTools: [{ replay: 'never' }] },
+    })
+  })
+})
diff --git a/testing/e2e/fixtures/subagents/basic.json b/testing/e2e/fixtures/subagents/basic.json
index fd9d5b682f..284943524d 100644
--- a/testing/e2e/fixtures/subagents/basic.json
+++ b/testing/e2e/fixtures/subagents/basic.json
@@ -109,6 +109,37 @@
       "response": {
         "content": "The comparison is ready."
       }
+    },
+    {
+      "match": {
+        "userMessage": "[subagent-result] price vendor a",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "pricer",
+            "arguments": "{\"task\":\"[subagent-result-task] Price Vendor A.\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[subagent-result-task] Price Vendor A."
+      },
+      "response": {
+        "content": "Vendor A costs 42 EUR."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[subagent-result] price vendor a",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Pricing is ready."
+      }
     }
   ]
 }
diff --git a/testing/e2e/src/lib/subagents-test.ts b/testing/e2e/src/lib/subagents-test.ts
index b7dfad6c23..1b50135a93 100644
--- a/testing/e2e/src/lib/subagents-test.ts
+++ b/testing/e2e/src/lib/subagents-test.ts
@@ -18,7 +18,12 @@ export const lookupFacts = toolDefinition({
   inputSchema: z.object({ topic: z.string() }),
 })
 
-export type SubagentScenario = 'route' | 'approval' | 'tool' | 'brief'
+export type SubagentScenario =
+  | 'route'
+  | 'approval'
+  | 'tool'
+  | 'brief'
+  | 'result'
 
 /** The user message for each scenario. It matches `fixtures/subagents`. */
 export const SUBAGENT_PROMPTS: Record<SubagentScenario, string> = {
@@ -26,6 +31,7 @@ export const SUBAGENT_PROMPTS: Record<SubagentScenario, string> = {
   approval: '[subagent-approval] clean up the old logs',
   tool: '[subagent-tool] research squids',
   brief: '[subagent-brief] compare squid facts',
+  result: '[subagent-result] price vendor a',
 }
 
 export function isSubagentScenario(value: unknown): value is SubagentScenario {
@@ -33,6 +39,7 @@ export function isSubagentScenario(value: unknown): value is SubagentScenario {
     value === 'route' ||
     value === 'approval' ||
     value === 'tool' ||
-    value === 'brief'
+    value === 'brief' ||
+    value === 'result'
   )
 }
diff --git a/testing/e2e/src/routes/api.subagents-test.ts b/testing/e2e/src/routes/api.subagents-test.ts
index 561fa9185f..5f03bb403f 100644
--- a/testing/e2e/src/routes/api.subagents-test.ts
+++ b/testing/e2e/src/routes/api.subagents-test.ts
@@ -30,6 +30,9 @@ import type { SubagentScenario } from '@/lib/subagents-test'
  *   child answers, and the parent reads its result.
  * - `brief`: no router. The parent model writes a `task` for `researcher`,
  *   and the child's only message is that task.
+ * - `result`: no router. `pricer` calls the bound `ctx.chat` with
+ *   `stream: false`, so its `run` resolves to a string. The string streams as
+ *   the child's text and goes back to the parent model as the result.
  */
 function subagentsFor(
   scenario: SubagentScenario,
@@ -95,6 +98,21 @@ function subagentsFor(
     const agents: Array<DefinedAgent> = [researcher]
     return { agents }
   }
+  if (scenario === 'result') {
+    const pricer = defineAgent({
+      name: 'pricer',
+      description: 'Prices one vendor',
+      inputSchema: z.object({ task: z.string() }),
+      run: (ctx) =>
+        ctx.chat({
+          ...createTextAdapter('openai', undefined, aimockPort, testId),
+          messages: [{ role: 'user', content: ctx.input.task }],
+          stream: false,
+        }),
+    })
+    const agents: Array<DefinedAgent> = [pricer]
+    return { agents }
+  }
   return { agents: [child('researcher', [])] }
 }
 
diff --git a/testing/e2e/tests/subagents.spec.ts b/testing/e2e/tests/subagents.spec.ts
index 20ae0d3f44..c596063fe6 100644
--- a/testing/e2e/tests/subagents.spec.ts
+++ b/testing/e2e/tests/subagents.spec.ts
@@ -14,7 +14,7 @@ async function run(page: Page) {
 
 function open(
   page: Page,
-  scenario: 'route' | 'approval' | 'tool' | 'brief',
+  scenario: 'route' | 'approval' | 'tool' | 'brief' | 'result',
   testId: string,
   aimockPort: number,
 ) {
@@ -132,4 +132,21 @@ test.describe('subagents', () => {
       'text:Squids have three hearts and blue blood.',
     )
   })
+
+  test('a child whose run resolves to a string reports it to the parent', async ({
+    page,
+    testId,
+    aimockPort,
+  }) => {
+    await open(page, 'result', testId, aimockPort)
+    await run(page)
+
+    await expect(page.getByTestId('parent-text')).toHaveText(
+      'Pricing is ready.',
+    )
+    await expect(page.getByTestId('card-status-pricer')).toHaveText('finished')
+    await expect(page.getByTestId('card-pricer')).toContainText(
+      'text:Vendor A costs 42 EUR.',
+    )
+  })
 })

From 71bef105a672efc1c31ea7cf5e7b7ab8d611f0aa Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 12:09:40 +0200
Subject: [PATCH 006/286] feat(ai-harness): add sessions, typed agents, and
 plugins

New package @tanstack/ai-harness. defineHarness takes the chat() options
plus typed agents, plugins, and a busy policy. createHarnessHost().open()
opens a long-lived session per thread.

A session runs chat turns (prompt), takes messages during a turn (steer,
followUp, or busy: queue/steer/reject), answers approvals (resolve), and
cancels work (cancel). session.agents.<name>.run(input) runs a typed agent
from code and notes the result in the transcript; start(input, { wake })
runs it in the background and starts a turn when it is done. Every
operation streams AG-UI events with cursors, plus harness.* CUSTOM events
for input receipts and operation lifecycle.

definePlugin adds tools, prompts, chat middleware, generation middleware,
and agents. Plugins provide capabilities to each other, own resources with
rollback, and live for the session or for one turn. Collisions name both
owners.

@tanstack/ai-persistence adds the optional inbox store, so accepted inputs
survive a restart. @tanstack/ai exports the helpers a host needs.
---
 .changeset/harness-p1-core.md                 |   9 +
 docs/config.json                              |  11 +
 docs/harness/overview.md                      | 182 ++++
 packages/ai-harness/README.md                 |  71 ++
 packages/ai-harness/package.json              |  77 ++
 packages/ai-harness/src/agents.ts             |  93 ++
 packages/ai-harness/src/define.ts             | 137 +++
 packages/ai-harness/src/feed.ts               | 102 ++
 packages/ai-harness/src/host.ts               | 106 +++
 packages/ai-harness/src/index.ts              |  57 ++
 packages/ai-harness/src/operation.ts          | 109 +++
 packages/ai-harness/src/plugins.ts            | 357 +++++++
 packages/ai-harness/src/resources.ts          |  84 ++
 packages/ai-harness/src/session.ts            | 870 ++++++++++++++++++
 packages/ai-harness/src/types.ts              |  99 ++
 packages/ai-harness/tests/define.test.ts      |  64 ++
 packages/ai-harness/tests/helpers.ts          | 154 ++++
 packages/ai-harness/tests/plugins.test.ts     | 167 ++++
 packages/ai-harness/tests/session.test.ts     | 498 ++++++++++
 packages/ai-harness/tests/types.test-d.ts     |  39 +
 packages/ai-harness/tsconfig.json             |   8 +
 packages/ai-harness/vite.config.ts            |  35 +
 packages/ai-persistence/src/index.ts          |   5 +
 packages/ai-persistence/src/memory.ts         |  48 +-
 .../ai-persistence/src/testkit/conformance.ts |  63 ++
 packages/ai-persistence/src/types.ts          |  50 +
 packages/ai-persistence/tests/inbox.test.ts   |  37 +
 packages/ai-persistence/tests/memory.test.ts  |   1 +
 .../tests/persistence-types.test-d.ts         |   2 +
 packages/ai/src/index.ts                      |   8 +
 pnpm-lock.yaml                                |  18 +
 testing/e2e/fixtures/harness/basic.json       |  20 +
 testing/e2e/package.json                      |   1 +
 testing/e2e/src/routeTree.gen.ts              |  21 +
 testing/e2e/src/routes/api.harness-test.ts    |  80 ++
 testing/e2e/tests/harness.spec.ts             |  31 +
 36 files changed, 3712 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/harness-p1-core.md
 create mode 100644 docs/harness/overview.md
 create mode 100644 packages/ai-harness/README.md
 create mode 100644 packages/ai-harness/package.json
 create mode 100644 packages/ai-harness/src/agents.ts
 create mode 100644 packages/ai-harness/src/define.ts
 create mode 100644 packages/ai-harness/src/feed.ts
 create mode 100644 packages/ai-harness/src/host.ts
 create mode 100644 packages/ai-harness/src/index.ts
 create mode 100644 packages/ai-harness/src/operation.ts
 create mode 100644 packages/ai-harness/src/plugins.ts
 create mode 100644 packages/ai-harness/src/resources.ts
 create mode 100644 packages/ai-harness/src/session.ts
 create mode 100644 packages/ai-harness/src/types.ts
 create mode 100644 packages/ai-harness/tests/define.test.ts
 create mode 100644 packages/ai-harness/tests/helpers.ts
 create mode 100644 packages/ai-harness/tests/plugins.test.ts
 create mode 100644 packages/ai-harness/tests/session.test.ts
 create mode 100644 packages/ai-harness/tests/types.test-d.ts
 create mode 100644 packages/ai-harness/tsconfig.json
 create mode 100644 packages/ai-harness/vite.config.ts
 create mode 100644 packages/ai-persistence/tests/inbox.test.ts
 create mode 100644 testing/e2e/fixtures/harness/basic.json
 create mode 100644 testing/e2e/src/routes/api.harness-test.ts
 create mode 100644 testing/e2e/tests/harness.spec.ts

diff --git a/.changeset/harness-p1-core.md b/.changeset/harness-p1-core.md
new file mode 100644
index 0000000000..28c75291c4
--- /dev/null
+++ b/.changeset/harness-p1-core.md
@@ -0,0 +1,9 @@
+---
+'@tanstack/ai-harness': minor
+'@tanstack/ai': minor
+'@tanstack/ai-persistence': minor
+---
+
+New package `@tanstack/ai-harness`. `defineHarness` takes the same options as `chat()`, plus typed `agents`, `plugins`, and a `busy` policy. `createHarnessHost().open(harness, { threadId })` opens a long-lived session. A session runs chat turns with `prompt`, takes messages during a turn with `steer` and `followUp`, answers approvals with `resolve`, and cancels work with `cancel`. `session.agents.<name>.run(input)` runs a typed agent from code, and `start(input, { wake: true })` runs it in the background. Every operation streams AG-UI events with cursors. `definePlugin` adds tools, prompts, chat middleware, generation middleware, and agents, with capabilities that plugins provide to each other and resources that close with the session or the turn.
+
+`@tanstack/ai` exports `CapabilityRegistry`, `runAgentStream`, `createSubagentId`, `compactForModel`, and the `SubagentsBag` type for harness hosts. `@tanstack/ai-persistence` adds the optional `inbox` store (`InboxStore`, `defineInboxStore`) that keeps accepted session inputs across restarts. The memory backend and the conformance testkit cover it.
diff --git a/docs/config.json b/docs/config.json
index 420a15ec03..e08f6892b5 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -800,6 +800,17 @@
       ],
       "tab": "guides"
     },
+    {
+      "label": "Harness",
+      "tab": "guides",
+      "children": [
+        {
+          "label": "Build your first harness",
+          "to": "harness/overview",
+          "addedAt": "2026-09-26"
+        }
+      ]
+    },
     {
       "label": "Sandboxes",
       "tab": "guides",
diff --git a/docs/harness/overview.md b/docs/harness/overview.md
new file mode 100644
index 0000000000..5364f1e554
--- /dev/null
+++ b/docs/harness/overview.md
@@ -0,0 +1,182 @@
+---
+title: Build your first harness
+id: harness-overview
+order: 1
+description: "Keep one agent conversation alive across many turns. Queue or steer messages while it works, run typed agents from code, and add plugins."
+keywords:
+  - tanstack ai
+  - harness
+  - defineHarness
+  - session
+  - plugins
+  - agents
+---
+
+`chat()` answers one request. A coding agent, a support bot, or a media studio needs more: one conversation that stays open, takes new messages while it works, and runs other agents from code. A harness gives you that. You define it once with the same options as `chat()`, then open a session for each conversation.
+
+At the end of this page you have a session that answers prompts, queues and steers messages, runs a typed agent, and loads a plugin.
+
+## Install
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: @tanstack/ai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-openai
+vue: @tanstack/ai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-openai
+solid: @tanstack/ai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-openai
+svelte: @tanstack/ai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-openai
+preact: @tanstack/ai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-openai
+angular: @tanstack/ai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-openai
+vanilla: @tanstack/ai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-openai
+octane: @tanstack/ai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-openai
+
+<!-- ::end:tabs -->
+
+## 1. Define the harness
+
+`defineHarness` takes the `chat()` options you know (`adapter`, `systemPrompts`, `tools`, `middleware`, `subagents`), plus a `name`. Importing it starts nothing.
+
+```ts group=harness-first
+import { defineAgent } from '@tanstack/ai'
+import { defineHarness } from '@tanstack/ai-harness'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+const pricer = defineAgent({
+  name: 'pricer',
+  description: 'Looks up the price of a vendor plan',
+  inputSchema: z.object({ vendor: z.string() }),
+  run: async (ctx) => ({ vendor: ctx.input.vendor, cents: 1200 }),
+})
+
+export const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-5.6'),
+  systemPrompts: ['You are a helpful assistant.'],
+  agents: [pricer],
+})
+```
+
+`agents` are agents you run from code. Put an agent in `subagents` instead when the model must call it as a tool, the same as in `chat()`.
+
+## 2. Open a session
+
+A host runs sessions. Give it the stores from `@tanstack/ai-persistence`, then open a session for a conversation id.
+
+```ts group=harness-first
+import { createHarnessHost } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+const session = await host.open(assistant, { threadId: 'thread-1' })
+```
+
+Opening the same `threadId` again returns the live session.
+
+## 3. Send a prompt
+
+`prompt` returns an operation. Await it for the text of the turn.
+
+```ts group=harness-first
+const turn = await session.prompt('Write a haiku about the sea.')
+console.log(turn.text)
+```
+
+The session saves the transcript, so the next prompt continues the same conversation.
+
+To show the answer while it streams, read the events of the operation:
+
+```ts group=harness-first
+const next = session.prompt('Now one about the mountains.')
+for await (const entry of next.events()) {
+  if (entry.event.type === 'TEXT_MESSAGE_CONTENT') {
+    process.stdout.write(entry.event.delta)
+  }
+}
+```
+
+The events are standard AG-UI events. `session.events({ from: cursor })` gives the events of every operation, from a cursor you saved.
+
+## 4. Send messages while it works
+
+Users type while the agent works. Pick what a new message does:
+
+- `session.prompt(text)`: runs after the current turn. This is the default.
+- `session.prompt(text, { busy: 'reject' })`: refuses the message while a turn runs.
+- `session.steer(text)`: adds the message to the running turn, before its next model call.
+- `session.followUp(text)`: runs after all current work.
+
+```ts group=harness-first
+const long = session.prompt('Plan a three-day trip to Lisbon.')
+await session.steer('Keep it under 500 euros.')
+await long
+```
+
+If the turn makes no further model call, the steer message runs as the next turn.
+
+## 5. Run an agent from code
+
+Every agent in `agents` and `subagents` is on `session.agents`. The input and the result are typed from the definition.
+
+```ts group=harness-first
+const price = await session.agents.pricer.run({ vendor: 'acme' })
+console.log(price.cents)
+```
+
+The session adds a short note about the result to the transcript. The model sees it on the next turn. To run the agent in the background and start a new turn when it is done, use `start`:
+
+```ts group=harness-first
+session.agents.pricer.start({ vendor: 'globex' }, { wake: true })
+```
+
+## 6. Add a plugin
+
+A plugin adds tools, prompts, middleware, and agents to every session. `setup` runs once when the session opens. Resources you acquire close when the session closes.
+
+```ts group=harness-first
+import { toolDefinition } from '@tanstack/ai'
+import { definePlugin } from '@tanstack/ai-harness'
+
+const clock = definePlugin({
+  name: 'acme/clock',
+  setup: () => ({
+    prompts: [`Today is ${new Date().toDateString()}.`],
+    tools: [
+      toolDefinition({
+        name: 'current_time',
+        description: 'Get the current time',
+      }).server(async () => new Date().toISOString()),
+    ],
+  }),
+})
+
+export const withClock = defineHarness({
+  name: 'acme/assistant-with-clock',
+  adapter: openaiText('gpt-5.6'),
+  plugins: () => [clock],
+})
+```
+
+`plugins` is a function, so every session gets its own plugin instances. Set `lifetime: 'run'` on a plugin to set it up again for each turn.
+
+If two plugins add a tool with the same name, `host.open` fails and names both plugins.
+
+## Keep sessions across restarts
+
+The host takes the same stores as `withPersistence`. Add an `inbox` store and the session also keeps the messages it accepted but did not start yet. When the session opens again, it runs them.
+
+- `messages`: the transcript. Required.
+- `runs`: the record of every turn and agent run.
+- `interrupts`: approvals that wait for a user.
+- `inbox`: accepted messages that did not run yet.
+
+`memoryPersistence()` has every store, but it keeps them in memory only. Write your own stores to keep data in your database. See [Build your own adapter](../persistence/build-your-own-adapter).
+
+## What you have now
+
+- A harness defined once, with the same options as `chat()`.
+- A session that keeps the conversation and streams AG-UI events.
+- Queue, steer, and follow-up for messages that arrive during a turn.
+- Typed agents you run from code, in the foreground or the background.
+- Plugins that add tools and prompts to each session.
+
+Next: open the [subagents guide](../chat/subagents) to let the model call your agents as tools.
diff --git a/packages/ai-harness/README.md b/packages/ai-harness/README.md
new file mode 100644
index 0000000000..c6a4806cf6
--- /dev/null
+++ b/packages/ai-harness/README.md
@@ -0,0 +1,71 @@
+<div align="center">
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://tanstack.com/api/readme/ai.png?theme=dark"
+    />
+    <source
+      media="(prefers-color-scheme: light)"
+      srcset="https://tanstack.com/api/readme/ai.png"
+    />
+    <img
+      src="https://tanstack.com/api/readme/ai.png"
+      alt="TanStack AI"
+      width="900"
+    />
+  </picture>
+</div>
+
+<br />
+
+# @tanstack/ai-harness
+
+Build agent harnesses on TanStack AI: long-lived sessions, typed agents, and plugins.
+
+`chat()` answers one request. A harness keeps one conversation open across many turns. It takes new messages while it works, runs typed agents from code, and loads plugins that add tools, prompts, and middleware.
+
+## Installation
+
+```bash
+npm install @tanstack/ai @tanstack/ai-harness @tanstack/ai-persistence
+```
+
+## Usage
+
+```ts
+import { defineAgent } from '@tanstack/ai'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+const pricer = defineAgent({
+  name: 'pricer',
+  description: 'Looks up the price of a vendor plan',
+  inputSchema: z.object({ vendor: z.string() }),
+  run: async (ctx) => ({ vendor: ctx.input.vendor, cents: 1200 }),
+})
+
+const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-5.6'),
+  agents: [pricer],
+})
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+const session = await host.open(assistant, { threadId: 'thread-1' })
+
+const turn = await session.prompt('Hello!')
+console.log(turn.text)
+
+const price = await session.agents.pricer.run({ vendor: 'acme' })
+console.log(price.cents)
+```
+
+## Documentation
+
+Read [Build your first harness](https://tanstack.com/ai/latest/docs/harness/overview).
+
+## License
+
+MIT
diff --git a/packages/ai-harness/package.json b/packages/ai-harness/package.json
new file mode 100644
index 0000000000..5d45fa9b9d
--- /dev/null
+++ b/packages/ai-harness/package.json
@@ -0,0 +1,77 @@
+{
+  "name": "@tanstack/ai-harness",
+  "version": "0.0.0",
+  "description": "Build agent harnesses on TanStack AI: long-lived sessions, typed agents, and plugins",
+  "keywords": [
+    "agent",
+    "ai",
+    "harness",
+    "plugins",
+    "session",
+    "tanstack"
+  ],
+  "license": "MIT",
+  "author": "",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-harness"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "oxlint src --type-aware --fix",
+    "test:build": "publint --strict",
+    "test:oxlint": "oxlint src --type-aware",
+    "test:coverage": "vitest run --passWithNoTests --coverage --coverage.include='src/**' --coverage.reporter=text-summary --coverage.reporter=json-summary",
+    "test:lib": "vitest --passWithNoTests",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  },
+  "devDependencies": {
+    "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-persistence": "workspace:*",
+    "@vitest/coverage-v8": "4.1.10",
+    "zod": "^4.2.0"
+  },
+  "peerDependencies": {
+    "@tanstack/ai": "workspace:^",
+    "@tanstack/ai-persistence": "workspace:^"
+  },
+  "nx": {
+    "targets": {
+      "test:lib": {
+        "dependsOn": [
+          "build",
+          "^build"
+        ]
+      },
+      "test:coverage": {
+        "dependsOn": [
+          "build",
+          "^build"
+        ]
+      },
+      "test:types": {
+        "dependsOn": [
+          "build",
+          "^build"
+        ]
+      }
+    }
+  }
+}
diff --git a/packages/ai-harness/src/agents.ts b/packages/ai-harness/src/agents.ts
new file mode 100644
index 0000000000..1562c6e4ef
--- /dev/null
+++ b/packages/ai-harness/src/agents.ts
@@ -0,0 +1,93 @@
+import type {
+  AgentProduces,
+  DefinedAgent,
+  InferSchemaType,
+  SchemaInput,
+} from '@tanstack/ai'
+
+/** Any agent made with `defineAgent`, with its types kept. */
+export type AnyAgent = DefinedAgent<any, any, any, any, any, any, any>
+
+/** The input an agent takes: its `inputSchema` type, or `undefined`. */
+export type AgentInputOf<TAgent> = TAgent extends {
+  inputSchema?: infer TSchema
+}
+  ? TSchema extends SchemaInput
+    ? InferSchemaType<TSchema>
+    : undefined
+  : undefined
+
+/**
+ * What running an agent resolves to:
+ * - its `outputSchema` type, when it has one;
+ * - else the value its promise `run` resolves to;
+ * - else the child's text.
+ */
+export type AgentResultOf<TAgent> =
+  TAgent extends DefinedAgent<
+    any,
+    any,
+    infer TSchema,
+    any,
+    any,
+    infer TResult,
+    any
+  >
+    ? TSchema extends SchemaInput
+      ? InferSchemaType<TSchema>
+      : unknown extends TResult
+        ? string
+        : TResult
+    : unknown
+
+/** A read-only view of the agents a session can run. */
+export interface AgentRegistryView {
+  /** Every agent, in registration order. */
+  list: () => ReadonlyArray<AnyAgent>
+  /** The agent named `name`, or `undefined`. */
+  get: (name: string) => AnyAgent | undefined
+  /** The first agent whose `produces` matches, or `undefined`. */
+  find: (query: { produces: AgentProduces }) => AnyAgent | undefined
+}
+
+/**
+ * The agents of one session, with the owner of each (the harness, or a
+ * plugin name). Adding a name twice with two different agents is an error that
+ * names both owners. Adding the same agent object twice is allowed, so an
+ * agent can sit in both `agents` and `subagents.agents`.
+ */
+export class AgentRegistry implements AgentRegistryView {
+  private readonly agents = new Map<
+    string,
+    { agent: AnyAgent; owner: string }
+  >()
+
+  add(agent: AnyAgent, owner: string): void {
+    const existing = this.agents.get(agent.name)
+    if (existing && existing.agent !== agent) {
+      throw new Error(
+        `Duplicate agent "${agent.name}": first owner ${existing.owner}, second owner ${owner}.`,
+      )
+    }
+    if (!existing) this.agents.set(agent.name, { agent, owner })
+  }
+
+  list(): ReadonlyArray<AnyAgent> {
+    return [...this.agents.values()].map((entry) => entry.agent)
+  }
+
+  get(name: string): AnyAgent | undefined {
+    return this.agents.get(name)?.agent
+  }
+
+  find(query: { produces: AgentProduces }): AnyAgent | undefined {
+    return this.list().find((agent) => agent.produces === query.produces)
+  }
+
+  /** A copy for one chat turn, so run plugins can add agents for that turn only. */
+  fork(): AgentRegistry {
+    const copy = new AgentRegistry()
+    for (const [name, entry] of this.agents) copy.agents.set(name, entry)
+    return copy
+  }
+}
diff --git a/packages/ai-harness/src/define.ts b/packages/ai-harness/src/define.ts
new file mode 100644
index 0000000000..ca22eafa31
--- /dev/null
+++ b/packages/ai-harness/src/define.ts
@@ -0,0 +1,137 @@
+import type {
+  AgentLoopStrategy,
+  AnyChatMiddleware,
+  AnyTextAdapter,
+  AnyTool,
+  InterruptDefinition,
+  SubagentsBag,
+  SystemPrompt,
+} from '@tanstack/ai'
+import type { AnyAgent } from './agents'
+import type { HarnessPlugin } from './plugins'
+import type { BusyPolicy } from './types'
+
+/** The `subagents` option: the same as `chat({ subagents })`. */
+export type HarnessSubagents<TSubagents extends ReadonlyArray<AnyAgent>> = Omit<
+  SubagentsBag<TSubagents>,
+  'binding'
+>
+
+/**
+ * What `defineHarness` takes. Where it overlaps with `chat()`, the option
+ * names and types are the same.
+ */
+export interface HarnessConfig<
+  TAdapter extends AnyTextAdapter = AnyTextAdapter,
+  TAgents extends ReadonlyArray<AnyAgent> = ReadonlyArray<AnyAgent>,
+  TSubagents extends ReadonlyArray<AnyAgent> = ReadonlyArray<AnyAgent>,
+> {
+  /** A stable name, for example `'acme/studio'`. */
+  name: string
+  /** The main agent-loop model, the same as `chat({ adapter })`. */
+  adapter: TAdapter
+  systemPrompts?: Array<SystemPrompt>
+  tools?: ReadonlyArray<AnyTool>
+  middleware?: ReadonlyArray<AnyChatMiddleware>
+  agentLoopStrategy?: AgentLoopStrategy
+  modelOptions?: TAdapter['~types']['providerOptions']
+  interrupts?: ReadonlyArray<InterruptDefinition<any, any, any, any>>
+  /** Runtime context passed to middleware hooks and server tools. */
+  context?: unknown
+  /**
+   * Typed agents the session can run from code, commands, plugins, and
+   * exposed clients: `session.agents.<name>.run(input)`.
+   */
+  agents?: TAgents
+  /**
+   * Agents the main model can call as tools, the same as `chat({ subagents })`.
+   * They are also registered in `session.agents`.
+   */
+  subagents?: HarnessSubagents<TSubagents>
+  /** Called once per session, so every session gets fresh plugin instances. */
+  plugins?: () => ReadonlyArray<HarnessPlugin>
+  /** What a `prompt` does while a chat turn runs. Default `'queue'`. */
+  busy?: BusyPolicy
+  /** What clients may call. Nothing is exposed by default. */
+  expose?: {
+    agents?: ReadonlyArray<TAgents[number]['name'] | TSubagents[number]['name']>
+  }
+}
+
+const HARNESS_KIND = 'tanstack-ai-harness' as const
+
+/** An immutable harness definition. Importing it starts nothing. */
+export type HarnessDefinition<
+  TAdapter extends AnyTextAdapter = AnyTextAdapter,
+  TAgents extends ReadonlyArray<AnyAgent> = ReadonlyArray<AnyAgent>,
+  TSubagents extends ReadonlyArray<AnyAgent> = ReadonlyArray<AnyAgent>,
+> = Readonly<HarnessConfig<TAdapter, TAgents, TSubagents>> & {
+  readonly kind: typeof HARNESS_KIND
+  readonly version: 1
+}
+
+/** A harness definition with any type parameters. */
+export type AnyHarness = HarnessDefinition<any, any, any>
+
+/** Every agent a harness registers, as a union. */
+export type HarnessAgentsOf<THarness> =
+  THarness extends HarnessDefinition<any, infer TAgents, infer TSubagents>
+    ? TAgents[number] | TSubagents[number]
+    : never
+
+/** True for a value made with `defineHarness`. */
+export function isHarnessDefinition(value: unknown): value is AnyHarness {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { kind?: unknown }).kind === HARNESS_KIND &&
+    (value as { version?: unknown }).version === 1
+  )
+}
+
+/**
+ * Define a harness: a reusable, typed agent configuration. Use the same option
+ * names as `chat()`, plus `agents`, `plugins`, `busy`, and `expose`.
+ *
+ * @example
+ * ```ts
+ * const studio = defineHarness({
+ *   name: 'acme/studio',
+ *   adapter: anthropicText('claude-sonnet-4-5'),
+ *   agents: [heroImage],
+ *   subagents: { agents: [researcher] },
+ * })
+ * ```
+ */
+export function defineHarness<
+  TAdapter extends AnyTextAdapter,
+  const TAgents extends ReadonlyArray<AnyAgent> = readonly [],
+  const TSubagents extends ReadonlyArray<AnyAgent> = readonly [],
+>(
+  config: HarnessConfig<TAdapter, TAgents, TSubagents>,
+): HarnessDefinition<TAdapter, TAgents, TSubagents> {
+  if (config.name.trim() === '') {
+    throw new Error('defineHarness requires a non-empty name')
+  }
+  const byName = new Map<string, AnyAgent>()
+  for (const agent of [
+    ...(config.agents ?? []),
+    ...(config.subagents?.agents ?? []),
+  ]) {
+    const existing = byName.get(agent.name)
+    if (existing && existing !== agent) {
+      throw new Error(
+        `defineHarness "${config.name}": two different agents are named "${agent.name}".`,
+      )
+    }
+    byName.set(agent.name, agent)
+  }
+  for (const name of config.expose?.agents ?? []) {
+    if (!byName.has(name)) {
+      throw new Error(
+        `defineHarness "${config.name}": expose.agents names "${name}", which is not a registered agent.`,
+      )
+    }
+  }
+  return Object.freeze({ ...config, kind: HARNESS_KIND, version: 1 as const })
+}
diff --git a/packages/ai-harness/src/feed.ts b/packages/ai-harness/src/feed.ts
new file mode 100644
index 0000000000..0d9e031cfb
--- /dev/null
+++ b/packages/ai-harness/src/feed.ts
@@ -0,0 +1,102 @@
+import type { StreamChunk } from '@tanstack/ai'
+import type { Cursor, SessionEvent } from './types'
+
+// ponytail: in-memory log capped at MAX_EVENTS per session. A reader whose
+// cursor fell out of the window resumes from the oldest kept event. Durable
+// cross-process delivery goes through StreamDurability in the protocol layer.
+const MAX_EVENTS = 10_000
+
+/**
+ * The ordered event stream of one session. Every operation publishes here.
+ * Cursors are opaque to callers and increase with each event.
+ */
+export class SessionFeed {
+  private readonly entries: Array<SessionEvent> = []
+  private sequence = 0
+  private readonly waiters = new Set<() => void>()
+  private closed = false
+
+  publish(operationId: string, event: StreamChunk): SessionEvent {
+    this.sequence += 1
+    const entry: SessionEvent = {
+      cursor: String(this.sequence),
+      operationId,
+      event,
+    }
+    this.entries.push(entry)
+    if (this.entries.length > MAX_EVENTS) this.entries.shift()
+    this.wake()
+    return entry
+  }
+
+  /** The cursor of the newest event, or `'0'` for an empty feed. */
+  head(): Cursor {
+    return String(this.sequence)
+  }
+
+  /**
+   * Events after `from` (exclusive), then live events until `signal` aborts
+   * or the feed closes. Pass a `filter` to read one operation's events.
+   */
+  async *read(options: {
+    from?: Cursor
+    signal?: AbortSignal
+    filter?: (entry: SessionEvent) => boolean
+    /** Stop after `until()` returns true and no buffered event is left. */
+    until?: () => boolean
+  }): AsyncIterable<SessionEvent> {
+    let after = Number(options.from ?? '0')
+    if (!Number.isFinite(after)) after = 0
+    while (true) {
+      if (options.signal?.aborted) return
+      const next = this.entries.filter(
+        (entry) =>
+          Number(entry.cursor) > after &&
+          (options.filter ? options.filter(entry) : true),
+      )
+      for (const entry of next) {
+        if (options.signal?.aborted) return
+        after = Number(entry.cursor)
+        yield entry
+      }
+      if (next.length === 0) {
+        // Skip past events the filter rejected, so they are not scanned again.
+        after = Math.max(after, this.sequence)
+      }
+      if (this.closed || options.until?.()) {
+        const rest = this.entries.filter(
+          (entry) =>
+            Number(entry.cursor) > after &&
+            (options.filter ? options.filter(entry) : true),
+        )
+        for (const entry of rest) yield entry
+        return
+      }
+      await this.waitForNext(options.signal)
+    }
+  }
+
+  close(): void {
+    this.closed = true
+    this.wake()
+  }
+
+  private wake(): void {
+    const waiters = [...this.waiters]
+    this.waiters.clear()
+    for (const wake of waiters) wake()
+  }
+
+  private waitForNext(signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve) => {
+      if (signal?.aborted) return resolve()
+      const done = () => {
+        signal?.removeEventListener('abort', done)
+        this.waiters.delete(done)
+        resolve()
+      }
+      this.waiters.add(done)
+      signal?.addEventListener('abort', done, { once: true })
+    })
+  }
+}
diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
new file mode 100644
index 0000000000..dda6dd628e
--- /dev/null
+++ b/packages/ai-harness/src/host.ts
@@ -0,0 +1,106 @@
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { HarnessSession } from './session'
+import type {
+  AIPersistence,
+  ChatTranscriptStores,
+  InboxStore,
+} from '@tanstack/ai-persistence'
+import type { AnyHarness } from './define'
+import type { Principal } from './types'
+
+/**
+ * The stores a host needs: a message store, plus any of runs, interrupts,
+ * metadata, and inbox. Without an inbox, inputs are kept in memory and a
+ * restart loses the ones not yet applied.
+ */
+export type HarnessPersistence = AIPersistence<
+  ChatTranscriptStores & { inbox?: InboxStore }
+>
+
+export interface HarnessHostOptions {
+  /** Where sessions keep their state. Default: in memory, lost on restart. */
+  persistence?: HarnessPersistence
+}
+
+export interface OpenSessionOptions {
+  /** The conversation id. Opening the same id again returns the live session. */
+  threadId: string
+  /** Who opened the session. Stored on inputs and run records. */
+  principal?: Principal
+}
+
+/** Runs sessions for one or more harnesses in this process. */
+export interface HarnessHost {
+  /**
+   * Open a session, or return the live one for this harness and thread.
+   * Session plugins are set up here, so a plugin error rejects the promise.
+   */
+  open: <THarness extends AnyHarness>(
+    harness: THarness,
+    options: OpenSessionOptions,
+  ) => Promise<HarnessSession<THarness>>
+  /** Close every live session. */
+  close: () => Promise<void>
+}
+
+let warned = false
+
+/**
+ * Create a host for harness sessions.
+ *
+ * @example
+ * ```ts
+ * const host = createHarnessHost({ persistence })
+ * const session = await host.open(studio, { threadId: 'thread-1' })
+ * const turn = await session.prompt('Write a haiku about the sea.')
+ * ```
+ */
+export function createHarnessHost(
+  options: HarnessHostOptions = {},
+): HarnessHost {
+  if (!options.persistence && !warned) {
+    warned = true
+    console.warn(
+      '[@tanstack/ai-harness] No persistence given: sessions live in memory and are lost on restart.',
+    )
+  }
+  const persistence = options.persistence ?? memoryPersistence()
+  // ponytail: a memory inbox when the stores have none. Pass `stores.inbox`
+  // to keep accepted inputs across restarts.
+  const inbox = persistence.stores.inbox ?? memoryPersistence().stores.inbox
+  const sessions = new Map<string, Promise<HarnessSession>>()
+
+  return {
+    open(harness, { threadId, principal }) {
+      const key = `${harness.name}\u0000${threadId}`
+      let session = sessions.get(key)
+      if (!session) {
+        const created = new HarnessSession({
+          harness,
+          threadId,
+          persistence,
+          inbox,
+          ...(principal ? { principal } : {}),
+          onClose: () => sessions.delete(key),
+        })
+        session = created.open().then(
+          () => created,
+          (error: unknown) => {
+            sessions.delete(key)
+            throw error
+          },
+        )
+        sessions.set(key, session)
+      }
+      return session as Promise<HarnessSession<typeof harness>>
+    },
+    async close() {
+      const live = await Promise.allSettled(sessions.values())
+      await Promise.all(
+        live
+          .filter((entry) => entry.status === 'fulfilled')
+          .map((entry) => entry.value.close()),
+      )
+    },
+  }
+}
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
new file mode 100644
index 0000000000..ac889765b3
--- /dev/null
+++ b/packages/ai-harness/src/index.ts
@@ -0,0 +1,57 @@
+export { defineHarness, isHarnessDefinition } from './define'
+export type {
+  AnyHarness,
+  HarnessAgentsOf,
+  HarnessConfig,
+  HarnessDefinition,
+  HarnessSubagents,
+} from './define'
+
+export { definePlugin } from './plugins'
+export type {
+  HarnessPlugin,
+  PluginContributions,
+  PluginDefinition,
+  PluginLifetime,
+  PluginPrompt,
+  PluginSetupContext,
+} from './plugins'
+
+export type {
+  AgentInputOf,
+  AgentRegistryView,
+  AgentResultOf,
+  AnyAgent,
+} from './agents'
+
+export { createHarnessHost } from './host'
+export type {
+  HarnessHost,
+  HarnessHostOptions,
+  HarnessPersistence,
+  OpenSessionOptions,
+} from './host'
+
+export { HarnessSession } from './session'
+export type {
+  AgentHandle,
+  AgentHandles,
+  AgentRunOptions,
+  AgentStartOptions,
+  SessionSnapshot,
+} from './session'
+
+export { HARNESS_EVENTS } from './types'
+export type {
+  BusyPolicy,
+  ChatTurnResult,
+  Cursor,
+  HarnessInput,
+  Operation,
+  OperationKind,
+  OperationStatus,
+  Principal,
+  Receipt,
+  SessionEvent,
+  UserInput,
+} from './types'
diff --git a/packages/ai-harness/src/operation.ts b/packages/ai-harness/src/operation.ts
new file mode 100644
index 0000000000..33f80cd2e6
--- /dev/null
+++ b/packages/ai-harness/src/operation.ts
@@ -0,0 +1,109 @@
+import type { StreamChunk } from '@tanstack/ai'
+import type { SessionFeed } from './feed'
+import type {
+  Cursor,
+  Operation,
+  OperationKind,
+  OperationStatus,
+  Receipt,
+  SessionEvent,
+} from './types'
+
+let counter = 0
+
+/** A new operation id. It is also the AG-UI `runId` of the operation. */
+export function createOperationId(kind: OperationKind): string {
+  counter += 1
+  return `op-${kind}-${Date.now().toString(36)}-${counter}`
+}
+
+const TERMINAL: ReadonlySet<OperationStatus> = new Set([
+  'completed',
+  'failed',
+  'cancelled',
+  'interrupted',
+])
+
+/** The session-side implementation of {@link Operation}. */
+export class OperationImpl<TResult> implements Operation<TResult> {
+  readonly id: string
+  readonly abortController = new AbortController()
+  private current: OperationStatus = 'accepted'
+  private readonly settled: Promise<TResult>
+  private resolveResult!: (value: TResult) => void
+  private rejectResult!: (error: unknown) => void
+
+  constructor(
+    readonly kind: OperationKind,
+    private readonly feed: SessionFeed,
+    private readonly onCancel: (
+      operation: OperationImpl<TResult>,
+    ) => Promise<Receipt>,
+    readonly agent?: string,
+  ) {
+    this.id = createOperationId(kind)
+    this.settled = new Promise<TResult>((resolve, reject) => {
+      this.resolveResult = resolve
+      this.rejectResult = reject
+    })
+    // Nobody may await a failed background operation. Do not report that as an
+    // unhandled rejection. `then` still rejects for callers that await.
+    this.settled.catch(() => {})
+  }
+
+  then<TResult1 = TResult, TResult2 = never>(
+    onfulfilled?: ((value: TResult) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+  ): PromiseLike<TResult1 | TResult2> {
+    return this.settled.then(onfulfilled, onrejected)
+  }
+
+  status(): OperationStatus {
+    return this.current
+  }
+
+  isSettled(): boolean {
+    return TERMINAL.has(this.current)
+  }
+
+  setStatus(status: OperationStatus): void {
+    this.current = status
+  }
+
+  publish(event: StreamChunk): SessionEvent {
+    return this.feed.publish(this.id, event)
+  }
+
+  finish(status: 'completed' | 'interrupted', result: TResult): void {
+    this.current = status
+    this.resolveResult(result)
+  }
+
+  fail(status: 'failed' | 'cancelled', error: unknown): void {
+    this.current = status
+    this.rejectResult(error)
+  }
+
+  events(options?: {
+    from?: Cursor
+    signal?: AbortSignal
+  }): AsyncIterable<SessionEvent> {
+    return this.feed.read({
+      ...options,
+      filter: (entry) => entry.operationId === this.id,
+      until: () => this.isSettled(),
+    })
+  }
+
+  async *stream(options?: {
+    signal?: AbortSignal
+  }): AsyncIterable<StreamChunk> {
+    for await (const entry of this.events({ from: '0', ...options })) {
+      yield entry.event
+    }
+  }
+
+  cancel(_reason?: string): Promise<Receipt> {
+    return this.onCancel(this)
+  }
+}
diff --git a/packages/ai-harness/src/plugins.ts b/packages/ai-harness/src/plugins.ts
new file mode 100644
index 0000000000..550ec092fa
--- /dev/null
+++ b/packages/ai-harness/src/plugins.ts
@@ -0,0 +1,357 @@
+import { CapabilityRegistry } from '@tanstack/ai'
+import { ResourceScope, disposeAll } from './resources'
+import type {
+  AgentProduces,
+  AnyChatMiddleware,
+  AnyGenerationMiddleware,
+  AnyTool,
+  Capability,
+  CapabilityHandle,
+  SystemPrompt,
+} from '@tanstack/ai'
+import type { AgentRegistry, AgentRegistryView, AnyAgent } from './agents'
+
+/**
+ * How long a plugin's `setup` result and resources live:
+ * - `session` (default): from session open to session close. Resources such
+ *   as an index, a watcher, or an LSP server stay up across turns.
+ * - `run`: set up for each chat turn, disposed when that turn ends.
+ */
+export type PluginLifetime = 'session' | 'run'
+
+/** A prompt a plugin contributes. `id` must be unique in the session. */
+export interface PluginPrompt {
+  id: string
+  text: string
+}
+
+/** What a plugin's `setup` returns. Every field is optional. */
+export interface PluginContributions {
+  /** Tools for the main model. */
+  tools?: ReadonlyArray<AnyTool>
+  /** System prompt text for every chat turn. */
+  prompts?: ReadonlyArray<string | PluginPrompt>
+  /** Chat middleware, the same type as `chat({ middleware })`. */
+  middleware?: ReadonlyArray<AnyChatMiddleware>
+  /** Middleware for the activities agents call (`ctx.generateImage`, ...). */
+  generationMiddleware?: ReadonlyArray<AnyGenerationMiddleware>
+  /** Agents added to `session.agents`. */
+  agents?: ReadonlyArray<AnyAgent>
+}
+
+/** What a plugin's `setup` receives. */
+export interface PluginSetupContext {
+  /** Resources this plugin owns, with rollback and reverse-order cleanup. */
+  resources: {
+    acquire: <T>(
+      open: () => T | Promise<T>,
+      close: (resource: T) => unknown,
+    ) => Promise<T>
+    signal: AbortSignal
+  }
+  /** Read a capability another plugin or middleware provided. Throws if absent. */
+  get: <T>(capability: Capability<T>) => T
+  /** Read a capability, or `undefined` when nobody provided it. */
+  getOptional: <T>(capability: Capability<T>) => T | undefined
+  /** Provide a capability this plugin declared in `provides`. */
+  provide: <T>(capability: Capability<T>, value: T) => void
+  /** The agents of this session (harness agents plus earlier plugins' agents). */
+  agents: AgentRegistryView
+  session: { threadId: string }
+}
+
+export interface PluginDefinition {
+  /** A stable, unique name, for example `'acme/todos'`. */
+  name: string
+  lifetime?: PluginLifetime
+  /** Capabilities that an earlier plugin or harness middleware must provide. */
+  requires?: ReadonlyArray<CapabilityHandle>
+  /** Capabilities this plugin provides in `setup`. */
+  provides?: ReadonlyArray<CapabilityHandle>
+  /** Capabilities used when present. Never an error when missing. */
+  optionalRequires?: ReadonlyArray<CapabilityHandle>
+  /** Agent outputs this plugin needs the session to have. */
+  needs?: { produces?: ReadonlyArray<AgentProduces> }
+  setup?: (
+    ctx: PluginSetupContext,
+  ) => PluginContributions | void | Promise<PluginContributions | void>
+}
+
+const PLUGIN_BRAND = Symbol.for('tanstack.ai.harnessPlugin')
+
+/** A plugin made with {@link definePlugin}. */
+export type HarnessPlugin<
+  TDefinition extends PluginDefinition = PluginDefinition,
+> = Readonly<TDefinition> & { readonly [PLUGIN_BRAND]: true }
+
+/**
+ * Define a harness plugin. `setup` returns what the plugin contributes, and
+ * closures in it can use the resources it acquired.
+ *
+ * @example
+ * ```ts
+ * const today = definePlugin({
+ *   name: 'acme/today',
+ *   setup: () => ({ prompts: [`Today is ${new Date().toDateString()}.`] }),
+ * })
+ * ```
+ */
+export function definePlugin<const TDefinition extends PluginDefinition>(
+  definition: TDefinition,
+): HarnessPlugin<TDefinition> {
+  if (definition.name.trim() === '') {
+    throw new Error('definePlugin requires a non-empty name')
+  }
+  return Object.freeze({ ...definition, [PLUGIN_BRAND]: true as const })
+}
+
+/** A tool, prompt, or middleware with the plugin that contributed it. */
+interface Owned<T> {
+  value: T
+  owner: string
+}
+
+/** Everything a set of mounted plugins contributes, plus its cleanup. */
+export interface MountedPlugins {
+  tools: Array<AnyTool>
+  prompts: Array<SystemPrompt>
+  middleware: Array<AnyChatMiddleware>
+  generationMiddleware: Array<AnyGenerationMiddleware>
+  /**
+   * Chat middleware that provides every plugin capability to each chat run,
+   * so any chat middleware can read it with `getX(ctx)`. Goes first.
+   */
+  capabilityBridge: AnyChatMiddleware | undefined
+  /** The capability values, so a run mount can read session capabilities. */
+  values: CapabilityValues
+  /** Dispose every plugin scope, newest first. Safe to call twice. */
+  dispose: () => Promise<void>
+}
+
+export interface MountEnvironment {
+  threadId: string
+  registry: AgentRegistry
+  /** Names already taken by the harness itself. */
+  harnessTools: ReadonlyArray<AnyTool>
+  /** Capabilities provided by harness-level middleware. */
+  harnessProvides: ReadonlyArray<CapabilityHandle>
+  /** Capability values from an outer mount (session plugins, for a run mount). */
+  inherited?: CapabilityValues
+}
+
+/** Capability values provided by plugins, keyed by handle. */
+export class CapabilityValues {
+  readonly context = { capabilities: new CapabilityRegistry() }
+  readonly handles: Array<CapabilityHandle> = []
+
+  constructor(private readonly parent?: CapabilityValues) {}
+
+  provide<T>(handle: Capability<T>, value: T): void {
+    handle[1](this.context, value)
+    this.handles.push(handle)
+  }
+
+  get<T>(handle: Capability<T>): T | undefined {
+    if (handle.has(this.context)) return handle[0](this.context)
+    return this.parent?.get(handle)
+  }
+
+  /** Every handle provided here and in the parent chain. */
+  all(): Array<CapabilityHandle> {
+    return [...(this.parent?.all() ?? []), ...this.handles]
+  }
+}
+
+function checkCapabilityOrder(
+  plugins: ReadonlyArray<HarnessPlugin>,
+  available: Set<CapabilityHandle>,
+): void {
+  const byName = new Map<string, CapabilityHandle>()
+  for (const handle of available) byName.set(handle.capabilityName, handle)
+  const names = new Set<string>()
+  for (const plugin of plugins) {
+    if (names.has(plugin.name)) {
+      throw new Error(`Duplicate plugin: ${plugin.name}`)
+    }
+    names.add(plugin.name)
+    for (const handle of [
+      ...(plugin.requires ?? []),
+      ...(plugin.provides ?? []),
+      ...(plugin.optionalRequires ?? []),
+    ]) {
+      const other = byName.get(handle.capabilityName)
+      if (other && other !== handle) {
+        throw new Error(
+          `Two different capabilities are named "${handle.capabilityName}" (plugin ${plugin.name}). Capability names must be unique.`,
+        )
+      }
+      byName.set(handle.capabilityName, handle)
+    }
+    for (const handle of plugin.requires ?? []) {
+      if (!available.has(handle)) {
+        throw new Error(
+          `Plugin ${plugin.name} requires capability "${handle.capabilityName}", but no earlier plugin or harness middleware provides it. Add a provider before ${plugin.name}.`,
+        )
+      }
+    }
+    for (const handle of plugin.provides ?? []) available.add(handle)
+  }
+}
+
+function promptOf(prompt: string | PluginPrompt, owner: string, index: number) {
+  return typeof prompt === 'string'
+    ? { id: `${owner}#${index}`, text: prompt }
+    : prompt
+}
+
+/**
+ * Set up plugins in order and collect what they contribute.
+ *
+ * Before any `setup` runs: duplicate plugin names, capability name clashes,
+ * and missing providers are errors. If a `setup` throws, or a contribution
+ * clashes (the same tool, prompt id, or agent name from two owners), every
+ * plugin set up so far is disposed newest first, and no chat turn starts.
+ */
+export async function mountPlugins(
+  plugins: ReadonlyArray<HarnessPlugin>,
+  env: MountEnvironment,
+): Promise<MountedPlugins> {
+  const available = new Set<CapabilityHandle>([
+    ...env.harnessProvides,
+    ...(env.inherited?.all() ?? []),
+  ])
+  checkCapabilityOrder(plugins, available)
+
+  const values = new CapabilityValues(env.inherited)
+  const scopes: Array<ResourceScope> = []
+  const tools: Array<Owned<AnyTool>> = env.harnessTools.map((tool) => ({
+    value: tool,
+    owner: 'the harness',
+  }))
+  const prompts: Array<Owned<PluginPrompt>> = []
+  const middleware: Array<AnyChatMiddleware> = []
+  const generationMiddleware: Array<AnyGenerationMiddleware> = []
+
+  try {
+    for (const plugin of plugins) {
+      const scope = new ResourceScope()
+      scopes.push(scope)
+      const provided = new Set<CapabilityHandle>()
+      const declared = new Set<CapabilityHandle>([
+        ...(plugin.requires ?? []),
+        ...(plugin.optionalRequires ?? []),
+      ])
+      const contributions = await plugin.setup?.({
+        resources: {
+          acquire: (open, close) => scope.acquire(open, close),
+          signal: scope.signal,
+        },
+        get: (handle) => {
+          const value = values.get(handle)
+          if (value === undefined && !declared.has(handle)) {
+            throw new Error(
+              `Plugin ${plugin.name} reads capability "${handle.capabilityName}" without declaring it in requires.`,
+            )
+          }
+          if (value === undefined) {
+            throw new Error(
+              `Capability "${handle.capabilityName}" was requested by ${plugin.name} but never provided.`,
+            )
+          }
+          return value
+        },
+        getOptional: (handle) => values.get(handle),
+        provide: (handle, value) => {
+          if (!(plugin.provides ?? []).includes(handle)) {
+            throw new Error(
+              `Plugin ${plugin.name} provides "${handle.capabilityName}" without declaring it in provides.`,
+            )
+          }
+          values.provide(handle, value)
+          provided.add(handle)
+        },
+        agents: env.registry,
+        session: { threadId: env.threadId },
+      })
+      for (const handle of plugin.provides ?? []) {
+        if (!provided.has(handle)) {
+          throw new Error(
+            `Plugin ${plugin.name} declares capability "${handle.capabilityName}" in provides but did not provide it in setup.`,
+          )
+        }
+      }
+      if (!contributions) continue
+      for (const tool of contributions.tools ?? []) {
+        const clash = tools.find((entry) => entry.value.name === tool.name)
+        if (clash) {
+          throw new Error(
+            `Duplicate tool "${tool.name}": first owner ${clash.owner}, second owner ${plugin.name}. No run started.`,
+          )
+        }
+        tools.push({ value: tool, owner: plugin.name })
+      }
+      ;(contributions.prompts ?? []).forEach((prompt, index) => {
+        const section = promptOf(prompt, plugin.name, index)
+        const clash = prompts.find((entry) => entry.value.id === section.id)
+        if (clash) {
+          throw new Error(
+            `Duplicate prompt id "${section.id}": first owner ${clash.owner}, second owner ${plugin.name}.`,
+          )
+        }
+        prompts.push({ value: section, owner: plugin.name })
+      })
+      middleware.push(...(contributions.middleware ?? []))
+      generationMiddleware.push(...(contributions.generationMiddleware ?? []))
+      for (const agent of contributions.agents ?? []) {
+        env.registry.add(agent, plugin.name)
+      }
+    }
+    for (const plugin of plugins) {
+      for (const produces of plugin.needs?.produces ?? []) {
+        if (!env.registry.find({ produces })) {
+          throw new Error(
+            `Plugin ${plugin.name} needs an agent that produces "${produces}", but the session has none. Add one to agents or subagents.`,
+          )
+        }
+      }
+    }
+  } catch (error) {
+    try {
+      await disposeAll(scopes)
+    } catch (cleanupError) {
+      throw new AggregateError(
+        [error, cleanupError],
+        'Plugin setup failed, and cleanup also failed',
+        { cause: error },
+      )
+    }
+    throw error
+  }
+
+  const bridgeHandles = values.handles
+  const capabilityBridge: AnyChatMiddleware | undefined =
+    bridgeHandles.length > 0
+      ? {
+          name: 'harness:plugin-capabilities',
+          provides: bridgeHandles,
+          setup(ctx) {
+            for (const handle of bridgeHandles) {
+              handle[1](ctx, values.get(handle))
+            }
+          },
+        }
+      : undefined
+
+  let disposed: Promise<void> | undefined
+  return {
+    tools: tools
+      .filter((entry) => entry.owner !== 'the harness')
+      .map((entry) => entry.value),
+    prompts: prompts.map((entry) => entry.value.text),
+    middleware,
+    generationMiddleware,
+    capabilityBridge,
+    values,
+    dispose: () => (disposed ??= disposeAll(scopes)),
+  }
+}
diff --git a/packages/ai-harness/src/resources.ts b/packages/ai-harness/src/resources.ts
new file mode 100644
index 0000000000..41c093a521
--- /dev/null
+++ b/packages/ai-harness/src/resources.ts
@@ -0,0 +1,84 @@
+/**
+ * Resources one plugin owns for one lifetime (a session or a run).
+ *
+ * - `acquire(open, close)` registers `close` only after `open` succeeds.
+ * - If the scope closes while `open` is still running, the late resource is
+ *   closed as soon as it arrives.
+ * - `dispose()` closes resources newest first, runs every closer even when
+ *   one throws, and returns the same promise to every caller.
+ */
+export class ResourceScope {
+  private readonly controller = new AbortController()
+  readonly signal: AbortSignal = this.controller.signal
+  private readonly closers: Array<() => unknown> = []
+  private readonly pending = new Set<Promise<void>>()
+  private closing?: Promise<void>
+  private closed = false
+
+  async acquire<T>(
+    open: () => T | Promise<T>,
+    close: (resource: T) => unknown,
+  ): Promise<T> {
+    this.signal.throwIfAborted()
+    let release!: () => void
+    const pending = new Promise<void>((resolve) => {
+      release = resolve
+    })
+    this.pending.add(pending)
+    try {
+      const resource = await open()
+      if (this.closed) {
+        await close(resource)
+        throw this.signal.reason
+      }
+      this.closers.push(() => close(resource))
+      return resource
+    } finally {
+      this.pending.delete(pending)
+      release()
+    }
+  }
+
+  dispose(): Promise<void> {
+    if (this.closing) return this.closing
+    this.closed = true
+    this.controller.abort(new Error('Resource scope disposed'))
+    // Defer, so a closer that calls dispose() again gets the same promise.
+    this.closing = Promise.resolve().then(async () => {
+      await Promise.all(this.pending)
+      const errors: Array<unknown> = []
+      for (const close of this.closers.reverse()) {
+        try {
+          await close()
+        } catch (error) {
+          errors.push(error)
+        }
+      }
+      this.closers.length = 0
+      if (errors.length > 0) {
+        throw new AggregateError(errors, 'Resource cleanup failed')
+      }
+    })
+    return this.closing
+  }
+}
+
+/**
+ * Dispose scopes newest first. Every scope is disposed even when one fails.
+ * Throws an `AggregateError` with every failure, after all scopes ran.
+ */
+export async function disposeAll(
+  scopes: ReadonlyArray<ResourceScope>,
+): Promise<void> {
+  const errors: Array<unknown> = []
+  for (const scope of [...scopes].reverse()) {
+    try {
+      await scope.dispose()
+    } catch (error) {
+      errors.push(error)
+    }
+  }
+  if (errors.length > 0) {
+    throw new AggregateError(errors, 'Plugin cleanup failed')
+  }
+}
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
new file mode 100644
index 0000000000..9e5a74b5c3
--- /dev/null
+++ b/packages/ai-harness/src/session.ts
@@ -0,0 +1,870 @@
+import {
+  EventType,
+  RUN_CANCEL_REASON,
+  chat,
+  compactForModel,
+  createSubagentId,
+  runAgentStream,
+  validateWithStandardSchema,
+} from '@tanstack/ai'
+import { withPersistence } from '@tanstack/ai-persistence'
+import { AgentRegistry } from './agents'
+import { SessionFeed } from './feed'
+import { OperationImpl } from './operation'
+import { mountPlugins } from './plugins'
+import { HARNESS_EVENTS } from './types'
+import type {
+  AnyChatMiddleware,
+  Interrupt,
+  ModelMessage,
+  RunAgentResumeItem,
+  StreamChunk,
+  SubagentBinding,
+} from '@tanstack/ai'
+import type { InboxEntry, InboxStore } from '@tanstack/ai-persistence'
+import type {
+  AgentInputOf,
+  AgentRegistryView,
+  AgentResultOf,
+  AnyAgent,
+} from './agents'
+import type { AnyHarness, HarnessAgentsOf } from './define'
+import type { HarnessPersistence } from './host'
+import type { HarnessPlugin, MountedPlugins } from './plugins'
+import type {
+  BusyPolicy,
+  ChatTurnResult,
+  Cursor,
+  HarnessInput,
+  Operation,
+  Principal,
+  Receipt,
+  SessionEvent,
+  UserInput,
+} from './types'
+
+/** Options for running an agent from code. */
+export interface AgentRunOptions {
+  /**
+   * How the main model learns about the result on its next turn:
+   * `'reference'` (default) adds a short note to the transcript, `'none'` adds
+   * nothing.
+   */
+  attach?: 'reference' | 'none'
+}
+
+/** Options for starting an agent in the background. */
+export interface AgentStartOptions extends AgentRunOptions {
+  /** When the agent finishes, start a new chat turn with its result. */
+  wake?: boolean
+}
+
+type RunArgs<TAgent, TOptions> =
+  AgentInputOf<TAgent> extends undefined
+    ? [input?: undefined, options?: TOptions]
+    : [input: AgentInputOf<TAgent>, options?: TOptions]
+
+/** Run one agent of a session, typed from its definition. */
+export interface AgentHandle<TAgent> {
+  run: (
+    ...args: RunArgs<TAgent, AgentRunOptions>
+  ) => Operation<AgentResultOf<TAgent>>
+  start: (
+    ...args: RunArgs<TAgent, AgentStartOptions>
+  ) => Operation<AgentResultOf<TAgent>>
+}
+
+/** `session.agents`: one typed handle per registered agent name. */
+export type AgentHandles<THarness> = {
+  [TAgent in HarnessAgentsOf<THarness> as TAgent['name']]: AgentHandle<TAgent>
+}
+
+/** What a session looks like right now. */
+export interface SessionSnapshot {
+  threadId: string
+  /**
+   * `running`: a chat turn runs. `requires_action`: the last turn stopped for
+   * outside input. `idle`: ready for a prompt (agents may still run).
+   */
+  status: 'idle' | 'running' | 'requires_action'
+  activeOperations: Array<{ id: string; kind: string; agent?: string }>
+  queuedTurns: number
+  pendingInterrupts: Array<Interrupt>
+  /** The cursor of the newest event. */
+  cursor: Cursor
+}
+
+/** What the host hands a new session. */
+export interface SessionDependencies {
+  harness: AnyHarness
+  threadId: string
+  persistence: HarnessPersistence
+  inbox: InboxStore
+  principal?: Principal
+  onClose: () => void
+}
+
+interface QueuedTurn {
+  operation: OperationImpl<ChatTurnResult>
+  message?: UserInput
+  resume?: Array<RunAgentResumeItem>
+  parentRunId?: string
+  inputId?: string
+}
+
+function createInputId(): string {
+  return `in-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`
+}
+
+function createMessageId(): string {
+  return `msg-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`
+}
+
+function customEvent(
+  name: string,
+  value: Record<string, unknown>,
+): StreamChunk {
+  return { type: EventType.CUSTOM, name, value, timestamp: Date.now() }
+}
+
+/** A short transcript note about an agent result, for the next turn. */
+function referenceNote(agent: string, result: unknown): string {
+  const body =
+    typeof result === 'string'
+      ? result
+      : JSON.stringify(compactForModel(result))
+  const clipped = body.length > 2000 ? `${body.slice(0, 2000)}...` : body
+  return `[${agent} finished] ${clipped}`
+}
+
+/**
+ * A live harness session: one conversation (`threadId`) with its plugins,
+ * operations, inbox, and event stream. Open one with `host.open()`.
+ */
+export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
+  readonly threadId: string
+  readonly agents: AgentHandles<THarness>
+  /** The agents this session can run, for discovery. */
+  readonly registry: AgentRegistryView
+
+  private readonly harness: THarness
+  private readonly persistence: HarnessPersistence
+  private readonly inbox: InboxStore
+  private readonly principal: Principal | undefined
+  private readonly feed = new SessionFeed()
+  private readonly agentRegistry = new AgentRegistry()
+  private readonly operations = new Map<string, OperationImpl<unknown>>()
+  private readonly queue: Array<QueuedTurn> = []
+  /**
+   * Messages for the running turn. A steer that the turn never reached (no
+   * further model call) runs as the next turn instead.
+   */
+  private readonly steerQueue: Array<{
+    inputId: string
+    message: UserInput
+    operation?: OperationImpl<ChatTurnResult>
+  }> = []
+  private readonly pendingNotes: Array<string> = []
+  private activeTurn: OperationImpl<ChatTurnResult> | undefined
+  private interrupted:
+    | { runId: string; interrupts: Array<Interrupt> }
+    | undefined
+  private plugins: ReadonlyArray<HarnessPlugin> = []
+  private sessionPlugins: MountedPlugins | undefined
+  private closing: Promise<void> | undefined
+  private readonly onClose: () => void
+
+  constructor(deps: SessionDependencies) {
+    this.harness = deps.harness as THarness
+    this.threadId = deps.threadId
+    this.persistence = deps.persistence
+    this.inbox = deps.inbox
+    this.principal = deps.principal
+    this.onClose = deps.onClose
+    this.registry = this.agentRegistry
+    for (const agent of this.harness.agents ?? []) {
+      this.agentRegistry.add(agent, 'the harness')
+    }
+    for (const agent of this.harness.subagents?.agents ?? []) {
+      this.agentRegistry.add(agent, 'the harness')
+    }
+    this.agents = new Proxy({} as AgentHandles<THarness>, {
+      get: (_target, name) => {
+        if (typeof name !== 'string') return undefined
+        return {
+          run: (input?: unknown, options?: AgentRunOptions) =>
+            this.runAgent(name, input, { ...options, wake: false }),
+          start: (input?: unknown, options?: AgentStartOptions) =>
+            this.runAgent(name, input, options ?? {}),
+        }
+      },
+    })
+  }
+
+  /** @internal Mount session plugins and replay inputs left in the inbox. */
+  async open(): Promise<void> {
+    this.plugins = this.harness.plugins?.() ?? []
+    this.sessionPlugins = await mountPlugins(
+      this.plugins.filter(
+        (plugin) => (plugin.lifetime ?? 'session') === 'session',
+      ),
+      {
+        threadId: this.threadId,
+        registry: this.agentRegistry,
+        harnessTools: this.harness.tools ?? [],
+        harnessProvides: (this.harness.middleware ?? []).flatMap(
+          (middleware) => middleware.provides ?? [],
+        ),
+      },
+    )
+    await this.recoverInbox()
+  }
+
+  // ===========================
+  // Inputs
+  // ===========================
+
+  /** Start a chat turn, or queue it while one runs (see `busy`). */
+  prompt(
+    message: UserInput,
+    options?: { busy?: BusyPolicy },
+  ): Operation<ChatTurnResult> {
+    const busy = options?.busy ?? this.harness.busy ?? 'queue'
+    const inputId = createInputId()
+    const operation = this.createTurnOperation()
+    void this.accept(inputId, { op: 'prompt', message, busy }).then(() => {
+      if (this.activeTurn && busy === 'reject') {
+        this.reject(inputId, 'busy')
+        operation.fail('failed', new Error('A chat turn is already running.'))
+        return
+      }
+      if (this.activeTurn && busy === 'steer') {
+        this.steerQueue.push({ inputId, message, operation })
+        return
+      }
+      this.enqueueTurn({ operation, message, inputId })
+    })
+    return operation
+  }
+
+  /** Add a message to the running turn at its next model call. */
+  async steer(message: UserInput): Promise<Receipt> {
+    const inputId = createInputId()
+    await this.accept(inputId, { op: 'steer', message })
+    if (!this.activeTurn) {
+      const operation = this.createTurnOperation()
+      this.enqueueTurn({ operation, message, inputId })
+      return { inputId, status: 'accepted', operationId: operation.id }
+    }
+    this.steerQueue.push({ inputId, message })
+    return { inputId, status: 'accepted', operationId: this.activeTurn.id }
+  }
+
+  /** Run a turn after the current work settles. */
+  async followUp(message: UserInput): Promise<Receipt> {
+    const inputId = createInputId()
+    await this.accept(inputId, { op: 'followUp', message })
+    const operation = this.createTurnOperation()
+    const status =
+      this.activeTurn || this.queue.length > 0 ? 'queued' : 'accepted'
+    this.enqueueTurn({ operation, message, inputId })
+    return { inputId, status, operationId: operation.id }
+  }
+
+  /**
+   * Answer the interrupts of the last turn. One resume must answer every open
+   * interrupt of that turn (the AG-UI rule).
+   */
+  async resolve(resume: Array<RunAgentResumeItem>): Promise<Receipt> {
+    const inputId = createInputId()
+    await this.accept(inputId, { op: 'resolve', resume })
+    if (!this.interrupted) {
+      this.reject(inputId, 'no_pending_interrupts')
+      return { inputId, status: 'rejected', reason: 'no_pending_interrupts' }
+    }
+    if (this.activeTurn) {
+      this.reject(inputId, 'busy')
+      return { inputId, status: 'rejected', reason: 'busy' }
+    }
+    const parentRunId = this.interrupted.runId
+    this.interrupted = undefined
+    const operation = this.createTurnOperation()
+    this.enqueueTurn({ operation, resume, parentRunId, inputId })
+    return { inputId, status: 'accepted', operationId: operation.id }
+  }
+
+  /** Cancel one operation, or the running chat turn. */
+  async cancel(operationId?: string): Promise<Receipt> {
+    const inputId = createInputId()
+    await this.accept(inputId, { op: 'cancel', operationId })
+    const target = operationId
+      ? this.operations.get(operationId)
+      : this.activeTurn
+    if (!target || target.isSettled()) {
+      this.reject(inputId, 'not_running')
+      return { inputId, status: 'rejected', reason: 'not_running' }
+    }
+    const queued = this.queue.findIndex((turn) => turn.operation === target)
+    if (queued >= 0) {
+      this.queue.splice(queued, 1)
+      target.fail('cancelled', new Error('Cancelled before it started.'))
+      this.publishFinished(target)
+    } else {
+      target.abortController.abort(RUN_CANCEL_REASON)
+    }
+    await this.inbox.markApplied(inputId, target.id)
+    return { inputId, status: 'accepted', operationId: target.id }
+  }
+
+  // ===========================
+  // Events and state
+  // ===========================
+
+  /** The ordered events of every operation, from `from` (exclusive). */
+  events(options?: {
+    from?: Cursor
+    signal?: AbortSignal
+  }): AsyncIterable<SessionEvent> {
+    return this.feed.read(options ?? {})
+  }
+
+  snapshot(): SessionSnapshot {
+    const active = [...this.operations.values()].filter(
+      (operation) => !operation.isSettled(),
+    )
+    return {
+      threadId: this.threadId,
+      status: this.activeTurn
+        ? 'running'
+        : this.interrupted
+          ? 'requires_action'
+          : 'idle',
+      activeOperations: active.map((operation) => ({
+        id: operation.id,
+        kind: operation.kind,
+        ...(operation.agent ? { agent: operation.agent } : {}),
+      })),
+      queuedTurns: this.queue.length,
+      pendingInterrupts: this.interrupted?.interrupts ?? [],
+      cursor: this.feed.head(),
+    }
+  }
+
+  /**
+   * Stop every running operation, wait for them, then dispose session plugins.
+   * Safe to call twice.
+   */
+  close(): Promise<void> {
+    this.closing ??= (async () => {
+      for (const turn of this.queue.splice(0)) {
+        turn.operation.fail('cancelled', new Error('Session closed.'))
+      }
+      const running = [...this.operations.values()].filter(
+        (operation) => !operation.isSettled(),
+      )
+      for (const operation of running) {
+        operation.abortController.abort(RUN_CANCEL_REASON)
+      }
+      await Promise.allSettled(
+        running.map((operation) => Promise.resolve(operation)),
+      )
+      try {
+        await this.sessionPlugins?.dispose()
+      } finally {
+        this.feed.close()
+        this.onClose()
+      }
+    })()
+    return this.closing
+  }
+
+  // ===========================
+  // Chat turns
+  // ===========================
+
+  private createTurnOperation(): OperationImpl<ChatTurnResult> {
+    const operation = new OperationImpl<ChatTurnResult>(
+      'chat',
+      this.feed,
+      (target) => this.cancel(target.id),
+    )
+    this.operations.set(operation.id, operation as OperationImpl<unknown>)
+    return operation
+  }
+
+  private enqueueTurn(turn: QueuedTurn): void {
+    this.queue.push(turn)
+    this.drain()
+  }
+
+  private drain(): void {
+    if (this.activeTurn || this.closing) return
+    const next = this.queue.shift()
+    if (!next) return
+    this.activeTurn = next.operation
+    void this.runTurn(next).finally(() => {
+      this.activeTurn = undefined
+      this.drain()
+    })
+  }
+
+  /** Middleware that adds queued steer messages before each model call. */
+  private steering(): AnyChatMiddleware {
+    return {
+      name: 'harness:steering',
+      onConfig: (ctx, config) => {
+        if (ctx.phase !== 'beforeModel' || this.steerQueue.length === 0) {
+          return undefined
+        }
+        const steers = this.steerQueue.splice(0)
+        const running = this.activeTurn
+        for (const steer of steers) {
+          // A prompt that joined the running turn settles with that turn.
+          if (steer.operation && running) {
+            const joined = steer.operation
+            this.operations.delete(joined.id)
+            running.then(
+              (result) => joined.finish('completed', result),
+              (error: unknown) => joined.fail('failed', error),
+            )
+          }
+          void this.inbox.markApplied(steer.inputId, ctx.runId)
+          this.feed.publish(
+            ctx.runId,
+            customEvent(HARNESS_EVENTS.inputApplied, {
+              inputId: steer.inputId,
+              operationId: ctx.runId,
+            }),
+          )
+        }
+        return {
+          messages: [
+            ...config.messages,
+            ...steers.map(
+              (steer): ModelMessage => ({
+                id: createMessageId(),
+                role: 'user',
+                content: steer.message,
+              }),
+            ),
+          ],
+        }
+      },
+    }
+  }
+
+  private binding(): SubagentBinding {
+    return {
+      generationMiddleware: this.sessionPlugins?.generationMiddleware ?? [],
+    }
+  }
+
+  private async runTurn(turn: QueuedTurn): Promise<void> {
+    const { operation } = turn
+    operation.setStatus('running')
+    if (turn.inputId) await this.applied(turn.inputId, operation.id)
+    this.publishStarted(operation)
+
+    let runPlugins: MountedPlugins | undefined
+    let text = ''
+    let interrupts: Array<Interrupt> | undefined
+    let failure: string | undefined
+    try {
+      await this.flushNotes()
+      const perRun = this.plugins.filter((plugin) => plugin.lifetime === 'run')
+      if (perRun.length > 0) {
+        runPlugins = await mountPlugins(perRun, {
+          threadId: this.threadId,
+          registry: this.agentRegistry.fork(),
+          harnessTools: [
+            ...(this.harness.tools ?? []),
+            ...(this.sessionPlugins?.tools ?? []),
+          ],
+          harnessProvides: (this.harness.middleware ?? []).flatMap(
+            (middleware) => middleware.provides ?? [],
+          ),
+          ...(this.sessionPlugins
+            ? { inherited: this.sessionPlugins.values }
+            : {}),
+        })
+      }
+      const session = this.sessionPlugins
+      const bridges = [
+        session?.capabilityBridge,
+        runPlugins?.capabilityBridge,
+      ].filter((bridge): bridge is AnyChatMiddleware => bridge !== undefined)
+      const subagents = this.harness.subagents
+      const stream = chat({
+        adapter: this.harness.adapter,
+        messages:
+          turn.message !== undefined
+            ? [{ id: createMessageId(), role: 'user', content: turn.message }]
+            : [],
+        systemPrompts: [
+          ...(this.harness.systemPrompts ?? []),
+          ...(session?.prompts ?? []),
+          ...(runPlugins?.prompts ?? []),
+        ],
+        tools: [
+          ...(this.harness.tools ?? []),
+          ...(session?.tools ?? []),
+          ...(runPlugins?.tools ?? []),
+        ],
+        middleware: [
+          ...bridges,
+          withPersistence(this.persistence),
+          ...(this.harness.middleware ?? []),
+          ...(session?.middleware ?? []),
+          ...(runPlugins?.middleware ?? []),
+          this.steering(),
+        ],
+        ...(subagents
+          ? { subagents: { ...subagents, binding: this.binding() } }
+          : {}),
+        ...(this.harness.agentLoopStrategy
+          ? { agentLoopStrategy: this.harness.agentLoopStrategy }
+          : {}),
+        ...(this.harness.modelOptions !== undefined
+          ? { modelOptions: this.harness.modelOptions }
+          : {}),
+        ...(this.harness.interrupts
+          ? { interrupts: this.harness.interrupts }
+          : {}),
+        ...(this.harness.context !== undefined
+          ? { context: this.harness.context }
+          : {}),
+        threadId: this.threadId,
+        runId: operation.id,
+        ...(turn.parentRunId ? { parentRunId: turn.parentRunId } : {}),
+        ...(turn.resume ? { resume: turn.resume } : {}),
+        abortController: operation.abortController,
+        stream: true,
+      } as never) as AsyncIterable<StreamChunk>
+
+      for await (const chunk of stream) {
+        operation.publish(chunk)
+        if (
+          chunk.type === EventType.TEXT_MESSAGE_CONTENT &&
+          !('subagentRunId' in chunk && chunk.subagentRunId)
+        ) {
+          text += chunk.delta
+        }
+        if (
+          chunk.type === EventType.RUN_FINISHED &&
+          chunk.outcome?.type === 'interrupt'
+        ) {
+          interrupts = chunk.outcome.interrupts
+        }
+        if (chunk.type === EventType.RUN_ERROR) failure = chunk.message
+      }
+    } catch (error) {
+      failure = error instanceof Error ? error.message : String(error)
+      if (!operation.abortController.signal.aborted) {
+        operation.publish({
+          type: EventType.RUN_ERROR,
+          message: failure,
+          timestamp: Date.now(),
+        })
+      }
+    } finally {
+      await runPlugins?.dispose().catch(() => {})
+    }
+
+    if (operation.abortController.signal.aborted) {
+      operation.fail('cancelled', new Error('Cancelled.'))
+    } else if (failure !== undefined) {
+      operation.fail('failed', new Error(failure))
+    } else if (interrupts && interrupts.length > 0) {
+      this.interrupted = { runId: operation.id, interrupts }
+      operation.finish('interrupted', { text, interrupts })
+    } else {
+      operation.finish('completed', { text })
+    }
+    this.publishFinished(operation)
+    // Steers the turn never reached run next, before other queued turns.
+    this.queue.unshift(
+      ...this.steerQueue.splice(0).map((steer) => ({
+        operation: steer.operation ?? this.createTurnOperation(),
+        message: steer.message,
+        inputId: steer.inputId,
+      })),
+    )
+  }
+
+  // ===========================
+  // Agents
+  // ===========================
+
+  private runAgent(
+    name: string,
+    input: unknown,
+    options: AgentStartOptions,
+  ): OperationImpl<unknown> {
+    const operation = new OperationImpl<unknown>(
+      'agent',
+      this.feed,
+      (target) => this.cancel(target.id),
+      name,
+    )
+    this.operations.set(operation.id, operation)
+    void this.executeAgent(operation, name, input, options)
+    return operation
+  }
+
+  private async executeAgent(
+    operation: OperationImpl<unknown>,
+    name: string,
+    input: unknown,
+    options: AgentStartOptions,
+  ): Promise<void> {
+    const inputId = createInputId()
+    await this.accept(inputId, {
+      op: 'agent',
+      agent: name,
+      input,
+      ...(options.wake ? { detached: true } : {}),
+    })
+    const agent: AnyAgent | undefined = this.agentRegistry.get(name)
+    if (!agent) {
+      this.reject(inputId, 'unknown_agent')
+      operation.fail('failed', new Error(`Unknown agent: ${name}`))
+      return
+    }
+    let checkedInput: unknown = input
+    if (agent.inputSchema !== undefined) {
+      const checked = await validateWithStandardSchema(
+        agent.inputSchema,
+        input ?? {},
+      )
+      if (!checked.success) {
+        const reason = `Input validation failed for agent ${name}: ${checked.issues
+          .map((issue) => issue.message)
+          .join(', ')}`
+        this.reject(inputId, 'invalid_input')
+        operation.fail('failed', new Error(reason))
+        return
+      }
+      checkedInput = checked.data
+    }
+
+    operation.setStatus('running')
+    await this.applied(inputId, operation.id)
+    const runs = this.persistence.stores.runs
+    await runs?.createOrResume({
+      runId: operation.id,
+      threadId: this.threadId,
+      startedAt: Date.now(),
+      kind: 'agent',
+      agent: name,
+      ...(this.principal ? { principal: { id: this.principal.id } } : {}),
+    })
+    operation.publish({
+      type: EventType.RUN_STARTED,
+      runId: operation.id,
+      threadId: this.threadId,
+      timestamp: Date.now(),
+    })
+    this.publishStarted(operation)
+
+    let text = ''
+    let result: unknown
+    let failure: string | undefined
+    let subagentRunId = ''
+    try {
+      const messages = await this.persistence.stores.messages?.loadThread(
+        this.threadId,
+      )
+      subagentRunId = createSubagentId()
+      const stream = runAgentStream(
+        agent,
+        {
+          input: checkedInput,
+          messages: messages ?? [],
+          threadId: `${this.threadId}:${name}`,
+          runId: `${operation.id}:${subagentRunId}`,
+          parentRunId: operation.id,
+          subagentRunId,
+          abortSignal: operation.abortController.signal,
+        },
+        undefined,
+        undefined,
+        this.binding(),
+      )
+      for await (const chunk of stream) {
+        operation.publish(chunk)
+        if (
+          chunk.type === EventType.TEXT_MESSAGE_CONTENT &&
+          'subagentRunId' in chunk &&
+          chunk.subagentRunId === subagentRunId
+        ) {
+          text += chunk.delta
+        }
+        if (
+          chunk.type === EventType.SUBAGENT_FINISHED &&
+          chunk.subagentRunId === subagentRunId
+        ) {
+          result = chunk.result
+        }
+        if (
+          chunk.type === EventType.SUBAGENT_ERROR &&
+          chunk.subagentRunId === subagentRunId
+        ) {
+          failure = chunk.message
+        }
+      }
+    } catch (error) {
+      failure = error instanceof Error ? error.message : String(error)
+    }
+
+    const value = result !== undefined ? result : text
+    if (operation.abortController.signal.aborted) {
+      operation.publish({
+        type: EventType.RUN_FINISHED,
+        runId: operation.id,
+        threadId: this.threadId,
+        outcome: { type: 'cancelled' },
+        timestamp: Date.now(),
+      } as StreamChunk)
+      await runs?.update(operation.id, {
+        status: 'aborted',
+        finishedAt: Date.now(),
+      })
+      operation.fail('cancelled', new Error('Cancelled.'))
+    } else if (failure !== undefined) {
+      operation.publish({
+        type: EventType.RUN_ERROR,
+        message: failure,
+        timestamp: Date.now(),
+      })
+      await runs?.update(operation.id, {
+        status: 'failed',
+        finishedAt: Date.now(),
+        error: { message: failure },
+      })
+      operation.fail('failed', new Error(failure))
+    } else {
+      operation.publish({
+        type: EventType.RUN_FINISHED,
+        runId: operation.id,
+        threadId: this.threadId,
+        result: value,
+        timestamp: Date.now(),
+      } as StreamChunk)
+      await runs?.update(operation.id, {
+        status: 'completed',
+        finishedAt: Date.now(),
+        result: compactForModel(value),
+      })
+      if ((options.attach ?? 'reference') === 'reference') {
+        this.pendingNotes.push(referenceNote(name, value))
+        if (!this.activeTurn) await this.flushNotes()
+      }
+      operation.finish('completed', value)
+      if (options.wake) {
+        void this.followUp(
+          `Background agent ${name} finished: ${referenceNote(name, value)}`,
+        )
+      }
+    }
+    this.publishFinished(operation)
+  }
+
+  /** Write queued agent notes to the transcript while no turn is writing it. */
+  private async flushNotes(): Promise<void> {
+    const messages = this.persistence.stores.messages
+    if (!messages || this.pendingNotes.length === 0) return
+    const notes = this.pendingNotes.splice(0)
+    const history = await messages.loadThread(this.threadId)
+    await messages.saveThread(this.threadId, [
+      ...history,
+      ...notes.map(
+        (note): ModelMessage => ({
+          id: createMessageId(),
+          role: 'assistant',
+          content: note,
+        }),
+      ),
+    ])
+  }
+
+  // ===========================
+  // Inbox and lifecycle events
+  // ===========================
+
+  private async accept(inputId: string, input: HarnessInput): Promise<void> {
+    await this.inbox.append({
+      inputId,
+      threadId: this.threadId,
+      input,
+      createdAt: Date.now(),
+      ...(this.principal ? { principal: { id: this.principal.id } } : {}),
+    })
+    this.feed.publish(
+      'session',
+      customEvent(HARNESS_EVENTS.inputAccepted, { inputId, op: input.op }),
+    )
+  }
+
+  private async applied(inputId: string, operationId: string): Promise<void> {
+    await this.inbox.markApplied(inputId, operationId)
+    this.feed.publish(
+      operationId,
+      customEvent(HARNESS_EVENTS.inputApplied, { inputId, operationId }),
+    )
+  }
+
+  private reject(inputId: string, reason: string): void {
+    void this.inbox.markRejected(inputId, reason)
+    this.feed.publish(
+      'session',
+      customEvent(HARNESS_EVENTS.inputRejected, { inputId, reason }),
+    )
+  }
+
+  private publishStarted(
+    operation: OperationImpl<unknown> | OperationImpl<ChatTurnResult>,
+  ): void {
+    operation.publish(
+      customEvent(HARNESS_EVENTS.operationStarted, {
+        operationId: operation.id,
+        kind: operation.kind,
+        ...(operation.agent ? { agent: operation.agent } : {}),
+      }),
+    )
+  }
+
+  private publishFinished(
+    operation: OperationImpl<unknown> | OperationImpl<ChatTurnResult>,
+  ): void {
+    operation.publish(
+      customEvent(HARNESS_EVENTS.operationFinished, {
+        operationId: operation.id,
+        status: operation.status(),
+      }),
+    )
+  }
+
+  /** Re-run turns that were accepted but never applied before a restart. */
+  private async recoverInbox(): Promise<void> {
+    const pending: Array<InboxEntry> = await this.inbox.listPending(
+      this.threadId,
+    )
+    for (const entry of pending) {
+      const input = entry.input as HarnessInput
+      if (
+        input.op === 'prompt' ||
+        input.op === 'followUp' ||
+        input.op === 'steer'
+      ) {
+        const operation = this.createTurnOperation()
+        this.enqueueTurn({
+          operation,
+          message: input.message,
+          inputId: entry.inputId,
+        })
+      } else {
+        this.reject(entry.inputId, 'expired_on_restart')
+      }
+    }
+  }
+}
diff --git a/packages/ai-harness/src/types.ts b/packages/ai-harness/src/types.ts
new file mode 100644
index 0000000000..5d6b766ae9
--- /dev/null
+++ b/packages/ai-harness/src/types.ts
@@ -0,0 +1,99 @@
+import type {
+  ContentPart,
+  Interrupt,
+  RunAgentResumeItem,
+  StreamChunk,
+} from '@tanstack/ai'
+
+/** A user message: plain text, or content parts (text, images, files). */
+export type UserInput = string | Array<ContentPart>
+
+/**
+ * What a `prompt` does when a chat turn is already running:
+ * - `queue` (default): runs as a new turn after the current one settles.
+ * - `steer`: joins the running turn at its next model call.
+ * - `reject`: refuses the prompt.
+ */
+export type BusyPolicy = 'queue' | 'steer' | 'reject'
+
+/** Kinds of work a session runs. */
+export type OperationKind = 'chat' | 'agent' | 'command' | 'compact'
+
+export type OperationStatus =
+  | 'accepted'
+  | 'running'
+  | 'interrupted'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+
+/** The immediate answer to an input. `applied` arrives later as an event. */
+export interface Receipt {
+  inputId: string
+  status: 'accepted' | 'queued' | 'rejected'
+  operationId?: string
+  reason?: string
+}
+
+/** Opaque position in a session's event stream. */
+export type Cursor = string
+
+/** One event in a session's ordered stream. */
+export interface SessionEvent {
+  cursor: Cursor
+  /** The operation that produced the event. */
+  operationId: string
+  event: StreamChunk
+}
+
+/** An input a client sends to a session. Stored in the inbox. */
+export type HarnessInput =
+  | { op: 'prompt'; message: UserInput; busy?: BusyPolicy }
+  | { op: 'steer'; message: UserInput }
+  | { op: 'followUp'; message: UserInput }
+  | { op: 'resolve'; resume: Array<RunAgentResumeItem> }
+  | { op: 'agent'; agent: string; input?: unknown; detached?: boolean }
+  | { op: 'cancel'; operationId?: string }
+
+/** Who sent an input, from the host's `authorize`. */
+export interface Principal {
+  id: string
+  name?: string
+}
+
+/** What a chat turn operation resolves to. */
+export interface ChatTurnResult {
+  /** The main model's text for this turn (child agent text excluded). */
+  text: string
+  /** Set when the turn stopped for outside input. */
+  interrupts?: Array<Interrupt>
+}
+
+/**
+ * One accepted unit of work in a session. Await it for its result.
+ */
+export interface Operation<TResult> extends PromiseLike<TResult> {
+  /** Also the AG-UI `runId` of the operation. */
+  readonly id: string
+  readonly kind: OperationKind
+  /** The agent name, for `kind: 'agent'`. */
+  readonly agent?: string
+  status: () => OperationStatus
+  /** This operation's events, from `from` (exclusive) onward. */
+  events: (options?: {
+    from?: Cursor
+    signal?: AbortSignal
+  }) => AsyncIterable<SessionEvent>
+  /** This operation's raw AG-UI chunks, for existing transports. */
+  stream: (options?: { signal?: AbortSignal }) => AsyncIterable<StreamChunk>
+  cancel: (reason?: string) => Promise<Receipt>
+}
+
+/** Names of the `CUSTOM` events a harness session adds to the stream. */
+export const HARNESS_EVENTS = {
+  operationStarted: 'harness.operation.started',
+  operationFinished: 'harness.operation.finished',
+  inputAccepted: 'harness.input.accepted',
+  inputApplied: 'harness.input.applied',
+  inputRejected: 'harness.input.rejected',
+} as const
diff --git a/packages/ai-harness/tests/define.test.ts b/packages/ai-harness/tests/define.test.ts
new file mode 100644
index 0000000000..7e46b4f603
--- /dev/null
+++ b/packages/ai-harness/tests/define.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { defineAgent } from '@tanstack/ai'
+import { defineHarness, isHarnessDefinition } from '../src'
+import { mockAdapter } from './helpers'
+
+const agent = (name: string) =>
+  defineAgent({
+    name,
+    description: name,
+    inputSchema: z.object({ q: z.string() }),
+    run: async () => 'ok',
+  })
+
+describe('defineHarness', () => {
+  const { adapter } = mockAdapter([])
+
+  it('returns a frozen, branded definition', () => {
+    const harness = defineHarness({ name: 'acme/test', adapter })
+    expect(isHarnessDefinition(harness)).toBe(true)
+    expect(Object.isFrozen(harness)).toBe(true)
+    expect(isHarnessDefinition({ name: 'x' })).toBe(false)
+  })
+
+  it('rejects an empty name', () => {
+    expect(() => defineHarness({ name: ' ', adapter })).toThrow(
+      'non-empty name',
+    )
+  })
+
+  it('rejects two different agents with one name', () => {
+    expect(() =>
+      defineHarness({
+        name: 'acme/test',
+        adapter,
+        agents: [agent('same')],
+        subagents: { agents: [agent('same')] },
+      }),
+    ).toThrow('two different agents are named "same"')
+  })
+
+  it('allows one agent in both agents and subagents', () => {
+    const shared = agent('shared')
+    expect(() =>
+      defineHarness({
+        name: 'acme/test',
+        adapter,
+        agents: [shared],
+        subagents: { agents: [shared] },
+      }),
+    ).not.toThrow()
+  })
+
+  it('rejects expose names that are not agents', () => {
+    expect(() =>
+      defineHarness({
+        name: 'acme/test',
+        adapter,
+        agents: [agent('real')],
+        expose: { agents: ['missing' as 'real'] },
+      }),
+    ).toThrow('expose.agents names "missing"')
+  })
+})
diff --git a/packages/ai-harness/tests/helpers.ts b/packages/ai-harness/tests/helpers.ts
new file mode 100644
index 0000000000..e8e3876082
--- /dev/null
+++ b/packages/ai-harness/tests/helpers.ts
@@ -0,0 +1,154 @@
+import { EventType } from '@tanstack/ai'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+
+type Reply = (options: any) => AsyncIterable<StreamChunk> | Array<StreamChunk>
+
+/** A text adapter whose turns are scripted. Records every call. */
+export function mockAdapter(replies: Array<Reply> | Reply) {
+  const calls: Array<any> = []
+  const adapter: AnyTextAdapter = {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    '~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,
+    },
+    chatStream: (options: any) => {
+      calls.push(options)
+      const reply = Array.isArray(replies) ? replies[calls.length - 1] : replies
+      const result = reply ? reply(options) : text('')
+      return (async function* () {
+        yield* result
+      })()
+    },
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+  }
+  return { adapter, calls }
+}
+
+const now = () => Date.now()
+
+/** One model call that answers with `content`. */
+export function text(content: string): Array<StreamChunk> {
+  return [
+    {
+      type: EventType.RUN_STARTED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: now(),
+    },
+    {
+      type: EventType.TEXT_MESSAGE_START,
+      messageId: 'm',
+      role: 'assistant',
+      timestamp: now(),
+    },
+    {
+      type: EventType.TEXT_MESSAGE_CONTENT,
+      messageId: 'm',
+      delta: content,
+      timestamp: now(),
+    },
+    { type: EventType.TEXT_MESSAGE_END, messageId: 'm', timestamp: now() },
+    {
+      type: EventType.RUN_FINISHED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: now(),
+      metadata: { tanstack: { finishReason: 'stop' } },
+    },
+  ]
+}
+
+/** One model call that calls a tool. */
+export function toolCall(
+  name: string,
+  args: Record<string, unknown>,
+  id = 'call-1',
+): Array<StreamChunk> {
+  return [
+    {
+      type: EventType.RUN_STARTED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: now(),
+    },
+    {
+      type: EventType.TOOL_CALL_START,
+      toolCallId: id,
+      toolCallName: name,
+      timestamp: now(),
+    },
+    {
+      type: EventType.TOOL_CALL_ARGS,
+      toolCallId: id,
+      delta: JSON.stringify(args),
+      timestamp: now(),
+    },
+    { type: EventType.TOOL_CALL_END, toolCallId: id, timestamp: now() },
+    {
+      type: EventType.RUN_FINISHED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: now(),
+      metadata: { tanstack: { finishReason: 'tool_calls' } },
+    },
+  ]
+}
+
+/** A reply that waits until the call is aborted, then ends. */
+export function untilAborted(): Reply {
+  return (options: any) =>
+    (async function* () {
+      yield {
+        type: EventType.RUN_STARTED,
+        runId: 'r',
+        threadId: 't',
+        timestamp: now(),
+      }
+      const signal: AbortSignal | undefined =
+        options.abortController?.signal ?? options.request?.signal
+      await new Promise<void>((resolve) => {
+        if (!signal || signal.aborted) return resolve()
+        signal.addEventListener('abort', () => resolve(), { once: true })
+      })
+    })()
+}
+
+/** A promise you resolve from outside. */
+export function gate() {
+  let open!: () => void
+  const opened = new Promise<void>((resolve) => {
+    open = resolve
+  })
+  return { open, opened }
+}
+
+/** A reply that waits for `until` before answering with `content`. */
+export function after(until: Promise<void>, content: string): Reply {
+  return () =>
+    (async function* () {
+      await until
+      yield* text(content)
+    })()
+}
+
+/** The text of every message the adapter got on call `index`. */
+export function messageTexts(call: any): Array<string> {
+  return (call.messages as Array<any>).map((message) =>
+    typeof message.content === 'string'
+      ? message.content
+      : JSON.stringify(message.content),
+  )
+}
diff --git a/packages/ai-harness/tests/plugins.test.ts b/packages/ai-harness/tests/plugins.test.ts
new file mode 100644
index 0000000000..6cbfce4cf9
--- /dev/null
+++ b/packages/ai-harness/tests/plugins.test.ts
@@ -0,0 +1,167 @@
+import { describe, expect, it } from 'vitest'
+import { createCapability, defineAgent } from '@tanstack/ai'
+import { AgentRegistry } from '../src/agents'
+import { definePlugin, mountPlugins } from '../src/plugins'
+import { ResourceScope } from '../src/resources'
+
+const env = () => ({
+  threadId: 't1',
+  registry: new AgentRegistry(),
+  harnessTools: [],
+  harnessProvides: [],
+})
+
+describe('ResourceScope', () => {
+  it('closes resources newest first and reports every close error', async () => {
+    const scope = new ResourceScope()
+    const log: Array<string> = []
+    await scope.acquire(
+      () => 'a',
+      () => log.push('close a'),
+    )
+    await scope.acquire(
+      () => 'b',
+      () => {
+        log.push('close b')
+        throw new Error('b broke')
+      },
+    )
+    await scope.acquire(
+      () => 'c',
+      () => {
+        log.push('close c')
+        throw new Error('c broke')
+      },
+    )
+    await expect(scope.dispose()).rejects.toBeInstanceOf(AggregateError)
+    expect(log).toEqual(['close c', 'close b', 'close a'])
+    expect(scope.signal.aborted).toBe(true)
+  })
+
+  it('closes a resource that finishes opening after dispose', async () => {
+    const scope = new ResourceScope()
+    const log: Array<string> = []
+    let finishOpen!: () => void
+    const opening = scope.acquire(
+      () =>
+        new Promise<string>((resolve) => {
+          finishOpen = () => resolve('late')
+        }),
+      () => log.push('closed late'),
+    )
+    const disposed = scope.dispose()
+    finishOpen()
+    await expect(opening).rejects.toThrow('Resource scope disposed')
+    await disposed
+    expect(log).toEqual(['closed late'])
+    await expect(
+      scope.acquire(
+        () => 'x',
+        () => {},
+      ),
+    ).rejects.toThrow()
+  })
+})
+
+describe('mountPlugins', () => {
+  const store = createCapability<{ items: Array<string> }>()('test.store')
+
+  it('fails before any setup when a required capability has no provider', async () => {
+    let ran = false
+    const reader = definePlugin({
+      name: 'test/reader',
+      requires: [store],
+      setup: () => {
+        ran = true
+      },
+    })
+    await expect(mountPlugins([reader], env())).rejects.toThrow(
+      'requires capability "test.store"',
+    )
+    expect(ran).toBe(false)
+  })
+
+  it('lets a later plugin read what an earlier plugin provides', async () => {
+    const provider = definePlugin({
+      name: 'test/provider',
+      provides: [store],
+      setup: ({ provide }) => provide(store, { items: ['x'] }),
+    })
+    let read: Array<string> = []
+    const reader = definePlugin({
+      name: 'test/reader',
+      requires: [store],
+      setup: ({ get }) => {
+        read = get(store).items
+      },
+    })
+    const mounted = await mountPlugins([provider, reader], env())
+    expect(read).toEqual(['x'])
+    expect(mounted.capabilityBridge?.provides).toEqual([store])
+  })
+
+  it('rejects a provide that the plugin did not declare', async () => {
+    const sneaky = definePlugin({
+      name: 'test/sneaky',
+      setup: ({ provide }) => provide(store, { items: [] }),
+    })
+    await expect(mountPlugins([sneaky], env())).rejects.toThrow(
+      'without declaring it in provides',
+    )
+  })
+
+  it('disposes earlier plugins newest first when a setup throws', async () => {
+    const log: Array<string> = []
+    const opener = (name: string) =>
+      definePlugin({
+        name,
+        setup: async ({ resources }) => {
+          await resources.acquire(
+            () => name,
+            () => log.push(`close ${name}`),
+          )
+        },
+      })
+    const broken = definePlugin({
+      name: 'test/broken',
+      setup: () => {
+        throw new Error('setup failed')
+      },
+    })
+    await expect(
+      mountPlugins([opener('test/one'), opener('test/two'), broken], env()),
+    ).rejects.toThrow('setup failed')
+    expect(log).toEqual(['close test/two', 'close test/one'])
+  })
+
+  it('checks needs.produces against the agents after setup', async () => {
+    const needsImages = definePlugin({
+      name: 'test/gallery',
+      needs: { produces: ['image'] },
+    })
+    await expect(mountPlugins([needsImages], env())).rejects.toThrow(
+      'needs an agent that produces "image"',
+    )
+
+    const painter = defineAgent({
+      name: 'painter',
+      description: 'Paints',
+      produces: 'image',
+      run: async () => 'painted',
+    })
+    const withPainter = definePlugin({
+      name: 'test/painter',
+      setup: () => ({ agents: [painter] }),
+    })
+    const environment = env()
+    await mountPlugins([withPainter, needsImages], environment)
+    expect(environment.registry.find({ produces: 'image' })).toBe(painter)
+  })
+
+  it('rejects duplicate plugin names', async () => {
+    const a = definePlugin({ name: 'test/same' })
+    await expect(mountPlugins([a, a], env())).rejects.toThrow(
+      'Duplicate plugin: test/same',
+    )
+  })
+})
diff --git a/packages/ai-harness/tests/session.test.ts b/packages/ai-harness/tests/session.test.ts
new file mode 100644
index 0000000000..a46b30a72c
--- /dev/null
+++ b/packages/ai-harness/tests/session.test.ts
@@ -0,0 +1,498 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import {
+  EventType,
+  createCapability,
+  defineAgent,
+  toolDefinition,
+} from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  HARNESS_EVENTS,
+  createHarnessHost,
+  defineHarness,
+  definePlugin,
+} from '../src'
+import {
+  after,
+  gate,
+  messageTexts,
+  mockAdapter,
+  text,
+  toolCall,
+  untilAborted,
+} from './helpers'
+import type { StreamChunk } from '@tanstack/ai'
+import type { SessionEvent } from '../src'
+
+function setup() {
+  const persistence = memoryPersistence()
+  const host = createHarnessHost({ persistence })
+  return { persistence, host }
+}
+
+function customNames(events: Array<SessionEvent>): Array<string> {
+  return events
+    .map((entry) => entry.event)
+    .filter(
+      (event): event is Extract<StreamChunk, { type: 'CUSTOM' }> =>
+        event.type === EventType.CUSTOM,
+    )
+    .map((event) => event.name)
+}
+
+async function collect(
+  iterable: AsyncIterable<SessionEvent>,
+): Promise<Array<SessionEvent>> {
+  const out: Array<SessionEvent> = []
+  for await (const entry of iterable) out.push(entry)
+  return out
+}
+
+describe('chat turns', () => {
+  it('runs a prompt, returns its text, and saves the transcript', async () => {
+    const { host, persistence } = setup()
+    const { adapter } = mockAdapter([() => text('Hello there')])
+    const harness = defineHarness({ name: 'test/chat', adapter })
+    const session = await host.open(harness, { threadId: 't1' })
+
+    const turn = session.prompt('Hi')
+    await expect(turn).resolves.toEqual({ text: 'Hello there' })
+    expect(turn.status()).toBe('completed')
+
+    const saved = await persistence.stores.messages.loadThread('t1')
+    expect(saved.map((message) => message.role)).toEqual(['user', 'assistant'])
+    const names = customNames(await collect(turn.events({ from: '0' })))
+    expect(names).toContain(HARNESS_EVENTS.inputApplied)
+    expect(names).toContain(HARNESS_EVENTS.operationStarted)
+    expect(names.at(-1)).toBe(HARNESS_EVENTS.operationFinished)
+    await host.close()
+  })
+
+  it('queues a second prompt and gives it the first turn as history', async () => {
+    const { host } = setup()
+    const first = gate()
+    const { adapter, calls } = mockAdapter([
+      after(first.opened, 'one'),
+      () => text('two'),
+    ])
+    const session = await host.open(
+      defineHarness({ name: 'test/queue', adapter }),
+      {
+        threadId: 't1',
+      },
+    )
+
+    const a = session.prompt('first')
+    const b = session.prompt('second')
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    expect(session.snapshot().queuedTurns).toBe(1)
+    first.open()
+
+    await expect(a).resolves.toEqual({ text: 'one' })
+    await expect(b).resolves.toEqual({ text: 'two' })
+    expect(messageTexts(calls[1])).toEqual(['first', 'one', 'second'])
+    await host.close()
+  })
+
+  it('rejects a prompt with busy: reject while a turn runs', async () => {
+    const { host } = setup()
+    const first = gate()
+    const { adapter, calls } = mockAdapter([after(first.opened, 'one')])
+    const session = await host.open(
+      defineHarness({ name: 'test/reject', adapter }),
+      {
+        threadId: 't1',
+      },
+    )
+
+    const a = session.prompt('first')
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    await expect(session.prompt('second', { busy: 'reject' })).rejects.toThrow(
+      'already running',
+    )
+    first.open()
+    await a
+    await host.close()
+  })
+
+  it('adds a steer message before the next model call of the running turn', async () => {
+    const { host } = setup()
+    const toolStarted = gate()
+    const releaseTool = gate()
+    const lookup = toolDefinition({
+      name: 'lookup',
+      description: 'Look something up',
+      inputSchema: z.object({ q: z.string() }),
+    }).server(async () => {
+      toolStarted.open()
+      await releaseTool.opened
+      return { found: true }
+    })
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('lookup', { q: 'x' }),
+      () => text('done'),
+    ])
+    const session = await host.open(
+      defineHarness({ name: 'test/steer', adapter, tools: [lookup] }),
+      { threadId: 't1' },
+    )
+
+    const turn = session.prompt('find x')
+    await toolStarted.opened
+    const receipt = await session.steer('also check y')
+    expect(receipt).toMatchObject({ status: 'accepted', operationId: turn.id })
+    releaseTool.open()
+
+    await expect(turn).resolves.toEqual({ text: 'done' })
+    expect(calls).toHaveLength(2)
+    expect(messageTexts(calls[1]).at(-1)).toBe('also check y')
+    await host.close()
+  })
+
+  it('runs a steer that arrived too late as the next turn', async () => {
+    const { host } = setup()
+    const first = gate()
+    const { adapter, calls } = mockAdapter([
+      after(first.opened, 'one'),
+      () => text('two'),
+    ])
+    const session = await host.open(
+      defineHarness({ name: 'test/late', adapter }),
+      {
+        threadId: 't1',
+      },
+    )
+
+    const a = session.prompt('first')
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    const joined = session.prompt('and this', { busy: 'steer' })
+    first.open()
+
+    await expect(a).resolves.toEqual({ text: 'one' })
+    await expect(joined).resolves.toEqual({ text: 'two' })
+    expect(messageTexts(calls[1]).at(-1)).toBe('and this')
+    await host.close()
+  })
+
+  it('cancels the running turn', async () => {
+    const { host } = setup()
+    const { adapter, calls } = mockAdapter([untilAborted()])
+    const session = await host.open(
+      defineHarness({ name: 'test/cancel', adapter }),
+      {
+        threadId: 't1',
+      },
+    )
+
+    const turn = session.prompt('go')
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    const receipt = await turn.cancel()
+    expect(receipt.status).toBe('accepted')
+    await expect(turn).rejects.toThrow('Cancelled')
+    expect(turn.status()).toBe('cancelled')
+    expect(session.snapshot().status).toBe('idle')
+    await host.close()
+  })
+
+  it('stops for an approval and continues after resolve', async () => {
+    const { host } = setup()
+    const execute = vi.fn(async () => ({ ok: true }))
+    const remove = toolDefinition({
+      name: 'remove',
+      description: 'Remove a file',
+      needsApproval: true,
+      inputSchema: z.object({ path: z.string() }),
+    }).server(execute)
+    const { adapter } = mockAdapter([
+      () => toolCall('remove', { path: 'a.txt' }, 'call_1'),
+      () => text('removed'),
+    ])
+    const session = await host.open(
+      defineHarness({ name: 'test/approve', adapter, tools: [remove] }),
+      { threadId: 't1' },
+    )
+
+    const turn = await session.prompt('remove a.txt')
+    expect(turn.interrupts).toHaveLength(1)
+    expect(session.snapshot().status).toBe('requires_action')
+
+    const receipt = await session.resolve([
+      {
+        interruptId: turn.interrupts![0]!.id,
+        status: 'resolved',
+        payload: true,
+      },
+    ])
+    expect(receipt.status).toBe('accepted')
+    await vi.waitFor(() => expect(session.snapshot().status).toBe('idle'))
+    expect(execute).toHaveBeenCalledWith({ path: 'a.txt' }, expect.anything())
+    await host.close()
+  })
+
+  it('rejects resolve when nothing is waiting', async () => {
+    const { host } = setup()
+    const { adapter } = mockAdapter([() => text('hi')])
+    const session = await host.open(
+      defineHarness({ name: 'test/noresolve', adapter }),
+      {
+        threadId: 't1',
+      },
+    )
+    const receipt = await session.resolve([
+      { interruptId: 'x', status: 'resolved', payload: true },
+    ])
+    expect(receipt).toMatchObject({
+      status: 'rejected',
+      reason: 'no_pending_interrupts',
+    })
+    await host.close()
+  })
+})
+
+describe('events', () => {
+  it('replays events after a cursor', async () => {
+    const { host } = setup()
+    const { adapter } = mockAdapter([() => text('one'), () => text('two')])
+    const session = await host.open(
+      defineHarness({ name: 'test/events', adapter }),
+      {
+        threadId: 't1',
+      },
+    )
+    await session.prompt('a')
+    const cursor = session.snapshot().cursor
+    const second = session.prompt('b')
+    await second
+
+    const controller = new AbortController()
+    const seen: Array<SessionEvent> = []
+    for await (const entry of session.events({
+      from: cursor,
+      signal: controller.signal,
+    })) {
+      seen.push(entry)
+      if (
+        entry.event.type === EventType.CUSTOM &&
+        entry.event.name === HARNESS_EVENTS.operationFinished
+      ) {
+        controller.abort()
+      }
+    }
+    expect(seen.every((entry) => Number(entry.cursor) > Number(cursor))).toBe(
+      true,
+    )
+    expect(seen.some((entry) => entry.operationId === second.id)).toBe(true)
+    await host.close()
+  })
+})
+
+describe('agents', () => {
+  const pricer = defineAgent({
+    name: 'pricer',
+    description: 'Prices a vendor',
+    inputSchema: z.object({ vendor: z.string() }),
+    run: async (ctx) => ({ vendor: ctx.input.vendor, cents: 1200 }),
+  })
+
+  it('runs a typed agent from code and notes the result in the transcript', async () => {
+    const { host, persistence } = setup()
+    const { adapter, calls } = mockAdapter([() => text('noted')])
+    const session = await host.open(
+      defineHarness({ name: 'test/agents', adapter, agents: [pricer] }),
+      { threadId: 't1' },
+    )
+
+    const run = session.agents.pricer.run({ vendor: 'acme' })
+    const result = await run
+    expect(result).toEqual({ vendor: 'acme', cents: 1200 })
+    expect(run.kind).toBe('agent')
+
+    const record = await persistence.stores.runs.get(run.id)
+    expect(record).toMatchObject({
+      kind: 'agent',
+      agent: 'pricer',
+      status: 'completed',
+    })
+
+    await session.prompt('what did it cost?')
+    expect(
+      messageTexts(calls[0]).some((line) => line.includes('[pricer finished]')),
+    ).toBe(true)
+    await host.close()
+  })
+
+  it('rejects input that fails the schema', async () => {
+    const { host } = setup()
+    const { adapter } = mockAdapter([])
+    const session = await host.open(
+      defineHarness({ name: 'test/agents-bad', adapter, agents: [pricer] }),
+      { threadId: 't1' },
+    )
+    await expect(
+      session.agents.pricer.run({ vendor: 1 } as never),
+    ).rejects.toThrow('Input validation failed for agent pricer')
+    await host.close()
+  })
+
+  it('starts a background agent that wakes the session when done', async () => {
+    const { host } = setup()
+    const { adapter, calls } = mockAdapter([() => text('thanks')])
+    const session = await host.open(
+      defineHarness({ name: 'test/wake', adapter, agents: [pricer] }),
+      { threadId: 't1' },
+    )
+
+    await session.agents.pricer.start({ vendor: 'acme' }, { wake: true })
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    expect(messageTexts(calls[0]).at(-1)).toContain(
+      'Background agent pricer finished',
+    )
+    await vi.waitFor(() => expect(session.snapshot().status).toBe('idle'))
+    await host.close()
+  })
+})
+
+describe('inbox', () => {
+  it('runs a prompt that was accepted but never applied before a restart', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.inbox.append({
+      inputId: 'in-1',
+      threadId: 't1',
+      input: { op: 'prompt', message: 'left over' },
+      createdAt: Date.now(),
+    })
+    const { adapter, calls } = mockAdapter([() => text('recovered')])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({ name: 'test/recover', adapter }),
+      {
+        threadId: 't1',
+      },
+    )
+
+    await vi.waitFor(() => expect(session.snapshot().status).toBe('idle'))
+    expect((await persistence.stores.inbox.get('in-1'))?.status).toBe('applied')
+    expect(messageTexts(calls[0])).toEqual(['left over'])
+    await host.close()
+  })
+})
+
+describe('plugins', () => {
+  it('keeps session plugins across turns and sets up run plugins per turn', async () => {
+    const { host } = setup()
+    const log: Array<string> = []
+    const sessionPlugin = definePlugin({
+      name: 'test/session',
+      setup: async ({ resources }) => {
+        await resources.acquire(
+          () => log.push('session:open'),
+          () => log.push('session:close'),
+        )
+        return { prompts: ['Session prompt.'] }
+      },
+    })
+    const runPlugin = definePlugin({
+      name: 'test/run',
+      lifetime: 'run',
+      setup: async ({ resources }) => {
+        await resources.acquire(
+          () => log.push('run:open'),
+          () => log.push('run:close'),
+        )
+      },
+    })
+    const { adapter, calls } = mockAdapter([() => text('a'), () => text('b')])
+    const session = await host.open(
+      defineHarness({
+        name: 'test/plugins',
+        adapter,
+        plugins: () => [sessionPlugin, runPlugin],
+      }),
+      { threadId: 't1' },
+    )
+
+    await session.prompt('one')
+    await session.prompt('two')
+    await session.close()
+
+    expect(log).toEqual([
+      'session:open',
+      'run:open',
+      'run:close',
+      'run:open',
+      'run:close',
+      'session:close',
+    ])
+    expect(JSON.stringify(calls[0].systemPrompts)).toContain('Session prompt.')
+  })
+
+  it('gives plugin tools to the model and plugin capabilities to middleware', async () => {
+    const { host } = setup()
+    const clockCapability = createCapability<{ now: () => string }>()(
+      'test.clock',
+    )
+    const [getClock] = clockCapability
+    const seen: Array<string> = []
+    const clockPlugin = definePlugin({
+      name: 'test/clock',
+      provides: [clockCapability],
+      setup: ({ provide }) => {
+        provide(clockCapability, { now: () => 'noon' })
+        return {
+          tools: [
+            toolDefinition({
+              name: 'clock',
+              description: 'Tell the time',
+            }).server(async () => 'noon'),
+          ],
+          middleware: [
+            {
+              name: 'test/read-clock',
+              requires: [clockCapability],
+              onStart: (ctx) => {
+                seen.push(getClock(ctx).now())
+              },
+            },
+          ],
+        }
+      },
+    })
+    const { adapter, calls } = mockAdapter([() => text('ok')])
+    const session = await host.open(
+      defineHarness({
+        name: 'test/tools',
+        adapter,
+        plugins: () => [clockPlugin],
+      }),
+      { threadId: 't1' },
+    )
+
+    await session.prompt('time?')
+    expect(calls[0].tools.map((tool: { name: string }) => tool.name)).toContain(
+      'clock',
+    )
+    expect(seen).toEqual(['noon'])
+    await host.close()
+  })
+
+  it('fails open when two plugins add the same tool', async () => {
+    const { host } = setup()
+    const tool = toolDefinition({ name: 'dup', description: 'x' }).server(
+      async () => 1,
+    )
+    const a = definePlugin({ name: 'test/a', setup: () => ({ tools: [tool] }) })
+    const b = definePlugin({ name: 'test/b', setup: () => ({ tools: [tool] }) })
+    const { adapter } = mockAdapter([])
+    await expect(
+      host.open(
+        defineHarness({ name: 'test/dup', adapter, plugins: () => [a, b] }),
+        {
+          threadId: 't1',
+        },
+      ),
+    ).rejects.toThrow(
+      'Duplicate tool "dup": first owner test/a, second owner test/b',
+    )
+  })
+})
diff --git a/packages/ai-harness/tests/types.test-d.ts b/packages/ai-harness/tests/types.test-d.ts
new file mode 100644
index 0000000000..0a9ffe74ee
--- /dev/null
+++ b/packages/ai-harness/tests/types.test-d.ts
@@ -0,0 +1,39 @@
+import { expectTypeOf, it } from 'vitest'
+import { z } from 'zod'
+import { defineAgent } from '@tanstack/ai'
+import { defineHarness } from '../src'
+import { mockAdapter } from './helpers'
+import type { HarnessSession, Operation } from '../src'
+
+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 writer = defineAgent({
+  name: 'writer',
+  description: 'Writes text',
+  run: () => (async function* () {})(),
+})
+
+const harness = defineHarness({
+  name: 'test/types',
+  adapter: mockAdapter([]).adapter,
+  agents: [pricer],
+  subagents: { agents: [writer] },
+})
+
+declare const session: HarnessSession<typeof harness>
+
+it('types agent input and result from the definition', () => {
+  expectTypeOf(session.agents.pricer.run({ vendor: 'a' })).toEqualTypeOf<
+    Operation<{ vendor: string; cents: number }>
+  >()
+  expectTypeOf(session.agents.writer.run()).toEqualTypeOf<Operation<string>>()
+  // @ts-expect-error unknown agent
+  void session.agents.missing
+  // @ts-expect-error wrong input
+  void session.agents.pricer.run({ vendor: 1 })
+})
diff --git a/packages/ai-harness/tsconfig.json b/packages/ai-harness/tsconfig.json
new file mode 100644
index 0000000000..29112eff9f
--- /dev/null
+++ b/packages/ai-harness/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["vite.config.ts", "./src", "./tests"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/ai-harness/vite.config.ts b/packages/ai-harness/vite.config.ts
new file mode 100644
index 0000000000..1f3542380f
--- /dev/null
+++ b/packages/ai-harness/vite.config.ts
@@ -0,0 +1,35 @@
+import { defineConfig, mergeConfig } from 'vitest/config'
+import { tanstackViteConfig } from '@tanstack/vite-config'
+import packageJson from './package.json'
+
+const config = defineConfig({
+  test: {
+    name: packageJson.name,
+    dir: './',
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts', 'tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'lcov'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        'tests/',
+        '**/*.test.ts',
+        '**/*.config.ts',
+      ],
+      include: ['src/**/*.ts'],
+    },
+  },
+})
+
+export default mergeConfig(
+  config,
+  tanstackViteConfig({
+    entry: ['./src/index.ts'],
+    srcDir: './src',
+    cjs: false,
+  }),
+)
diff --git a/packages/ai-persistence/src/index.ts b/packages/ai-persistence/src/index.ts
index 3100a67c4c..eac9972b34 100644
--- a/packages/ai-persistence/src/index.ts
+++ b/packages/ai-persistence/src/index.ts
@@ -9,6 +9,7 @@ export {
   defineGenerationRunStore,
   defineArtifactStore,
   defineBlobStore,
+  defineInboxStore,
   // Run lifecycle helpers owned by @tanstack/ai, transiting through ./types so
   // this package's public surface stays a single import for backend authors.
   isTerminalRunStatus,
@@ -25,6 +26,10 @@ export type {
   InterruptStatus,
   InterruptStore,
   MetadataStore,
+  // Harness session inbox
+  InboxEntry,
+  InboxStatus,
+  InboxStore,
   // Named product shapes (prefer these over a sparse bag)
   ChatTranscriptStores,
   ChatPersistenceStores,
diff --git a/packages/ai-persistence/src/memory.ts b/packages/ai-persistence/src/memory.ts
index 849e30acf1..fd4df0b8b6 100644
--- a/packages/ai-persistence/src/memory.ts
+++ b/packages/ai-persistence/src/memory.ts
@@ -14,6 +14,8 @@ import type {
   BlobStore,
   GenerationRunRecord,
   GenerationRunStore,
+  InboxEntry,
+  InboxStore,
   InterruptCommitEntry,
   InterruptRecord,
   InterruptStore,
@@ -542,6 +544,45 @@ class MemoryBlobStore implements BlobStore {
   }
 }
 
+class MemoryInboxStore implements InboxStore {
+  private readonly entries = new Map<string, InboxEntry>()
+  append(entry: Omit<InboxEntry, 'status'>): Promise<InboxEntry> {
+    const existing = this.entries.get(entry.inputId)
+    if (existing) return Promise.resolve({ ...existing })
+    const stored: InboxEntry = { ...entry, status: 'pending' }
+    this.entries.set(entry.inputId, stored)
+    return Promise.resolve({ ...stored })
+  }
+  listPending(threadId: string): Promise<Array<InboxEntry>> {
+    // Map iteration keeps insertion order; sort by time in case clocks tie.
+    const pending = [...this.entries.values()]
+      .filter(
+        (entry) => entry.threadId === threadId && entry.status === 'pending',
+      )
+      .sort((a, b) => a.createdAt - b.createdAt)
+      .map((entry) => ({ ...entry }))
+    return Promise.resolve(pending)
+  }
+  markApplied(inputId: string, operationId: string): Promise<void> {
+    const existing = this.entries.get(inputId)
+    if (existing) {
+      this.entries.set(inputId, { ...existing, status: 'applied', operationId })
+    }
+    return Promise.resolve()
+  }
+  markRejected(inputId: string, reason: string): Promise<void> {
+    const existing = this.entries.get(inputId)
+    if (existing) {
+      this.entries.set(inputId, { ...existing, status: 'rejected', reason })
+    }
+    return Promise.resolve()
+  }
+  get(inputId: string): Promise<InboxEntry | null> {
+    const existing = this.entries.get(inputId)
+    return Promise.resolve(existing ? { ...existing } : null)
+  }
+}
+
 interface MemoryPersistenceStores {
   messages: MessageStore
   runs: RunStore
@@ -550,14 +591,16 @@ interface MemoryPersistenceStores {
   metadata: MetadataStore
   artifacts: ArtifactStore
   blobs: BlobStore
+  inbox: InboxStore
 }
 
 /**
  * In-process reference backend for the full state + generation store set.
  *
  * Returns messages + runs + generationRuns + interrupts + metadata + artifacts
- * + blobs. Locks are not included — use `InMemoryLockStore` + `withLocks` from
- * `@tanstack/ai` when a test or single-process app needs coordination.
+ * + blobs + inbox. Locks are not included — use `InMemoryLockStore` +
+ * `withLocks` from `@tanstack/ai` when a test or single-process app needs
+ * coordination.
  */
 export function memoryPersistence() {
   const stores: MemoryPersistenceStores = {
@@ -566,6 +609,7 @@ export function memoryPersistence() {
     generationRuns: new MemoryGenerationRunStore(),
     interrupts: new MemoryInterruptStore(),
     metadata: new MemoryMetadataStore(),
+    inbox: new MemoryInboxStore(),
     artifacts: new MemoryArtifactStore(),
     blobs: new MemoryBlobStore(),
   }
diff --git a/packages/ai-persistence/src/testkit/conformance.ts b/packages/ai-persistence/src/testkit/conformance.ts
index 253cc6e630..f621c7f6a2 100644
--- a/packages/ai-persistence/src/testkit/conformance.ts
+++ b/packages/ai-persistence/src/testkit/conformance.ts
@@ -1528,6 +1528,69 @@ export function runPersistenceConformance(
       })
     })
 
+    // The inbox is opt-in: only harness hosts read it. A backend without it
+    // skips these cases and needs no `skip` entry.
+    describe('inbox', () => {
+      it('appends idempotently, lists pending oldest first, and settles entries', async (ctx) => {
+        const store = persistence.stores.inbox
+        if (!store) return ctx.skip('inbox store not provided')
+
+        const first = await store.append({
+          inputId: 'in-1',
+          threadId: 'inbox-thread',
+          input: { op: 'prompt', message: 'hi' },
+          createdAt: 1,
+        })
+        expect(first.status).toBe('pending')
+        // Same id again: the stored entry wins, the new payload is ignored.
+        const again = await store.append({
+          inputId: 'in-1',
+          threadId: 'inbox-thread',
+          input: { op: 'prompt', message: 'changed' },
+          createdAt: 5,
+        })
+        expect(again.input).toEqual({ op: 'prompt', message: 'hi' })
+
+        await store.append({
+          inputId: 'in-2',
+          threadId: 'inbox-thread',
+          principal: { id: 'user-1' },
+          input: { op: 'steer', message: 'shorter' },
+          createdAt: 2,
+        })
+        await store.append({
+          inputId: 'in-other',
+          threadId: 'other-thread',
+          input: { op: 'prompt', message: 'x' },
+          createdAt: 0,
+        })
+
+        expect(
+          (await store.listPending('inbox-thread')).map(
+            (entry) => entry.inputId,
+          ),
+        ).toEqual(['in-1', 'in-2'])
+
+        await store.markApplied('in-1', 'op-1')
+        await store.markRejected('in-2', 'busy')
+        expect(await store.listPending('inbox-thread')).toEqual([])
+        expect(await store.get('in-1')).toMatchObject({
+          status: 'applied',
+          operationId: 'op-1',
+        })
+        expect(await store.get('in-2')).toMatchObject({
+          status: 'rejected',
+          reason: 'busy',
+          principal: { id: 'user-1' },
+        })
+
+        // Unknown ids are no-ops.
+        await store.markApplied('missing', 'op-x')
+        await store.markRejected('missing', 'nope')
+        expect(await store.get('missing')).toBeNull()
+      })
+    })
+
     describe('metadata', () => {
       it('sets, gets, namespaces, and deletes without composite-key collisions', async (ctx) => {
         const store = resolveStore('metadata')
diff --git a/packages/ai-persistence/src/types.ts b/packages/ai-persistence/src/types.ts
index 54c917d0b6..986c384bf0 100644
--- a/packages/ai-persistence/src/types.ts
+++ b/packages/ai-persistence/src/types.ts
@@ -368,6 +368,53 @@ export function defineInterruptStore(store: InterruptStore): InterruptStore {
 export function defineMetadataStore(store: MetadataStore): MetadataStore {
   return store
 }
+
+/** Lifecycle of one inbox entry. */
+export type InboxStatus = 'pending' | 'applied' | 'rejected' | 'expired'
+
+/**
+ * One input a client sent to a harness session (a prompt, a steer message, a
+ * follow-up, an interrupt answer, an agent run, a command). Written before the
+ * session answers with a receipt, so an accepted input survives a crash.
+ */
+export interface InboxEntry {
+  /** Idempotency key. A second append with the same id is a no-op. */
+  inputId: string
+  threadId: string
+  /** Who sent it, from the host's `authorize`. */
+  principal?: { id: string }
+  /** The input itself. Storage holds it as-is. The harness validates it. */
+  input: unknown
+  status: InboxStatus
+  createdAt: number
+  expiresAt?: number
+  /** The operation that applied the input. */
+  operationId?: string
+  /** Why the input was rejected. */
+  reason?: string
+}
+
+/** Durable store for harness session inputs. */
+export interface InboxStore {
+  /**
+   * Store a new entry as `'pending'`, or return the existing entry unchanged
+   * when `inputId` is already present.
+   */
+  append: (entry: Omit<InboxEntry, 'status'>) => Promise<InboxEntry>
+  /** Pending entries of a thread, oldest first. */
+  listPending: (threadId: string) => Promise<Array<InboxEntry>>
+  /** Mark an entry applied by `operationId`. A no-op for an unknown id. */
+  markApplied: (inputId: string, operationId: string) => Promise<void>
+  /** Mark an entry rejected with `reason`. A no-op for an unknown id. */
+  markRejected: (inputId: string, reason: string) => Promise<void>
+  /** The entry for `inputId`, or `null`. */
+  get: (inputId: string) => Promise<InboxEntry | null>
+}
+
+/** Type an {@link InboxStore} implementation inline. */
+export function defineInboxStore(store: InboxStore): InboxStore {
+  return store
+}
 /** Type a {@link GenerationRunStore} implementation inline. */
 export function defineGenerationRunStore(
   store: GenerationRunStore,
@@ -620,6 +667,8 @@ export interface AIPersistenceStores {
   generationRuns?: GenerationRunStore
   artifacts?: ArtifactStore
   blobs?: BlobStore
+  /** Harness session inputs. Optional: only harness hosts read it. */
+  inbox?: InboxStore
 }
 
 /**
@@ -795,6 +844,7 @@ const storeKeys = [
   'metadata',
   'artifacts',
   'blobs',
+  'inbox',
 ] satisfies Array<StoreKey>
 
 const storeKeySet = new Set<string>(storeKeys)
diff --git a/packages/ai-persistence/tests/inbox.test.ts b/packages/ai-persistence/tests/inbox.test.ts
new file mode 100644
index 0000000000..b88414483e
--- /dev/null
+++ b/packages/ai-persistence/tests/inbox.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest'
+import {
+  defineAIPersistence,
+  defineInboxStore,
+  memoryPersistence,
+} from '../src'
+
+describe('inbox store', () => {
+  it('ships in memoryPersistence', () => {
+    expect(memoryPersistence().stores.inbox).toBeDefined()
+  })
+
+  it('returns a copy, so callers cannot change stored entries', async () => {
+    const inbox = memoryPersistence().stores.inbox
+    const entry = await inbox.append({
+      inputId: 'in-1',
+      threadId: 't',
+      input: { op: 'prompt' },
+      createdAt: 1,
+    })
+    entry.status = 'applied'
+
+    expect((await inbox.get('in-1'))?.status).toBe('pending')
+  })
+
+  it('accepts a user-implemented inbox in defineAIPersistence', () => {
+    const inbox = defineInboxStore({
+      append: (entry) => Promise.resolve({ ...entry, status: 'pending' }),
+      listPending: () => Promise.resolve([]),
+      markApplied: () => Promise.resolve(),
+      markRejected: () => Promise.resolve(),
+      get: () => Promise.resolve(null),
+    })
+
+    expect(defineAIPersistence({ stores: { inbox } }).stores.inbox).toBe(inbox)
+  })
+})
diff --git a/packages/ai-persistence/tests/memory.test.ts b/packages/ai-persistence/tests/memory.test.ts
index 14c14374ab..db479ec83b 100644
--- a/packages/ai-persistence/tests/memory.test.ts
+++ b/packages/ai-persistence/tests/memory.test.ts
@@ -16,6 +16,7 @@ describe('memoryPersistence', () => {
       'artifacts',
       'blobs',
       'generationRuns',
+      'inbox',
       'interrupts',
       'messages',
       'metadata',
diff --git a/packages/ai-persistence/tests/persistence-types.test-d.ts b/packages/ai-persistence/tests/persistence-types.test-d.ts
index 7db2404d4b..467e17a3f0 100644
--- a/packages/ai-persistence/tests/persistence-types.test-d.ts
+++ b/packages/ai-persistence/tests/persistence-types.test-d.ts
@@ -21,6 +21,7 @@ import type {
   ChatTranscriptPersistence,
   ChatTranscriptStores,
   GenerationRunStore,
+  InboxStore,
   InterruptStore,
   MessagePage,
   MessageStore,
@@ -139,6 +140,7 @@ expectTypeOf(memoryPersistence()).toEqualTypeOf<
     metadata: MetadataStore
     artifacts: ArtifactStore
     blobs: BlobStore
+    inbox: InboxStore
   }>
 >()
 const transcript: ChatTranscriptPersistence = messagesOnly
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index bb2055aa0c..8e2889ab62 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -109,7 +109,14 @@ export type {
   SubagentRouterPlan,
   SubagentStep,
   SubagentStepsPlan,
+  SubagentsBag,
 } from './activities/chat/agents/spawn'
+// For hosts (a harness session) that run an agent outside a parent chat turn.
+export {
+  spawnAgentStream as runAgentStream,
+  createSubagentId,
+} from './activities/chat/agents/spawn'
+export { compactForModel } from './activities/chat/tools/tool-calls'
 
 // Tool definition
 export {
@@ -343,6 +350,7 @@ export type {
 // Capability primitives + middleware builder
 export {
   createCapability,
+  CapabilityRegistry,
   defineChatMiddleware,
   createChatMiddleware,
   MetadataCapability,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f850d1c3eb..ca0c6edf73 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2520,6 +2520,21 @@ importers:
         specifier: ^8.2.1
         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:
+    devDependencies:
+      '@tanstack/ai':
+        specifier: workspace:*
+        version: link:../ai
+      '@tanstack/ai-persistence':
+        specifier: workspace:*
+        version: link:../ai-persistence
+      '@vitest/coverage-v8':
+        specifier: 4.1.10
+        version: 4.1.10(vitest@4.1.11)
+      zod:
+        specifier: ^4.2.0
+        version: 4.3.6
+
   packages/ai-isolate-cloudflare:
     dependencies:
       '@tanstack/ai-code-mode':
@@ -3574,6 +3589,9 @@ importers:
       '@tanstack/ai-groq':
         specifier: workspace:*
         version: link:../../packages/ai-groq
+      '@tanstack/ai-harness':
+        specifier: workspace:*
+        version: link:../../packages/ai-harness
       '@tanstack/ai-llmgateway':
         specifier: workspace:*
         version: link:../../packages/ai-llmgateway
diff --git a/testing/e2e/fixtures/harness/basic.json b/testing/e2e/fixtures/harness/basic.json
new file mode 100644
index 0000000000..252c90de69
--- /dev/null
+++ b/testing/e2e/fixtures/harness/basic.json
@@ -0,0 +1,20 @@
+{
+  "fixtures": [
+    {
+      "match": { "userMessage": "[harness-turns] first" },
+      "response": { "content": "First answer." }
+    },
+    {
+      "match": { "userMessage": "[harness-turns] second" },
+      "response": { "content": "Second answer." }
+    },
+    {
+      "match": { "userMessage": "[harness-agent] price vendor a" },
+      "response": { "content": "Vendor A costs 12 dollars." }
+    },
+    {
+      "match": { "userMessage": "[harness-agent] what did it cost?" },
+      "response": { "content": "It cost 12 dollars." }
+    }
+  ]
+}
diff --git a/testing/e2e/package.json b/testing/e2e/package.json
index 148f58052e..41b655bed1 100644
--- a/testing/e2e/package.json
+++ b/testing/e2e/package.json
@@ -31,6 +31,7 @@
     "@tanstack/ai-gemini": "workspace:*",
     "@tanstack/ai-grok": "workspace:*",
     "@tanstack/ai-groq": "workspace:*",
+    "@tanstack/ai-harness": "workspace:*",
     "@tanstack/ai-llmgateway": "workspace:*",
     "@tanstack/ai-lovable": "workspace:*",
     "@tanstack/ai-mcp": "workspace:*",
diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index 7308d98796..87b7a9edc4 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -97,6 +97,7 @@ import { Route as ApiLazyToolsWireRouteImport } from './routes/api.lazy-tools-wi
 import { Route as ApiJoinRunClientToolRouteImport } from './routes/api.join-run-client-tool'
 import { Route as ApiInterruptsTestRouteImport } from './routes/api.interrupts-test'
 import { Route as ApiImageRouteImport } from './routes/api.image'
+import { Route as ApiHarnessTestRouteImport } from './routes/api.harness-test'
 import { Route as ApiGenerationPersistenceServerRouteImport } from './routes/api.generation-persistence-server'
 import { Route as ApiGenerationPersistenceResumeRouteImport } from './routes/api.generation-persistence-resume'
 import { Route as ApiGeminiNativeImageWireRouteImport } from './routes/api.gemini-native-image-wire'
@@ -585,6 +586,11 @@ const ApiImageRoute = ApiImageRouteImport.update({
   path: '/api/image',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiHarnessTestRoute = ApiHarnessTestRouteImport.update({
+  id: '/api/harness-test',
+  path: '/api/harness-test',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiGenerationPersistenceServerRoute =
   ApiGenerationPersistenceServerRouteImport.update({
     id: '/api/generation-persistence-server',
@@ -795,6 +801,7 @@ export interface FileRoutesByFullPath {
   '/api/gemini-native-image-wire': typeof ApiGeminiNativeImageWireRoute
   '/api/generation-persistence-resume': typeof ApiGenerationPersistenceResumeRoute
   '/api/generation-persistence-server': typeof ApiGenerationPersistenceServerRoute
+  '/api/harness-test': typeof ApiHarnessTestRoute
   '/api/image': typeof ApiImageRouteWithChildren
   '/api/interrupts-test': typeof ApiInterruptsTestRoute
   '/api/join-run-client-tool': typeof ApiJoinRunClientToolRoute
@@ -914,6 +921,7 @@ export interface FileRoutesByTo {
   '/api/gemini-native-image-wire': typeof ApiGeminiNativeImageWireRoute
   '/api/generation-persistence-resume': typeof ApiGenerationPersistenceResumeRoute
   '/api/generation-persistence-server': typeof ApiGenerationPersistenceServerRoute
+  '/api/harness-test': typeof ApiHarnessTestRoute
   '/api/image': typeof ApiImageRouteWithChildren
   '/api/interrupts-test': typeof ApiInterruptsTestRoute
   '/api/join-run-client-tool': typeof ApiJoinRunClientToolRoute
@@ -1034,6 +1042,7 @@ export interface FileRoutesById {
   '/api/gemini-native-image-wire': typeof ApiGeminiNativeImageWireRoute
   '/api/generation-persistence-resume': typeof ApiGenerationPersistenceResumeRoute
   '/api/generation-persistence-server': typeof ApiGenerationPersistenceServerRoute
+  '/api/harness-test': typeof ApiHarnessTestRoute
   '/api/image': typeof ApiImageRouteWithChildren
   '/api/interrupts-test': typeof ApiInterruptsTestRoute
   '/api/join-run-client-tool': typeof ApiJoinRunClientToolRoute
@@ -1155,6 +1164,7 @@ export interface FileRouteTypes {
     | '/api/gemini-native-image-wire'
     | '/api/generation-persistence-resume'
     | '/api/generation-persistence-server'
+    | '/api/harness-test'
     | '/api/image'
     | '/api/interrupts-test'
     | '/api/join-run-client-tool'
@@ -1274,6 +1284,7 @@ export interface FileRouteTypes {
     | '/api/gemini-native-image-wire'
     | '/api/generation-persistence-resume'
     | '/api/generation-persistence-server'
+    | '/api/harness-test'
     | '/api/image'
     | '/api/interrupts-test'
     | '/api/join-run-client-tool'
@@ -1393,6 +1404,7 @@ export interface FileRouteTypes {
     | '/api/gemini-native-image-wire'
     | '/api/generation-persistence-resume'
     | '/api/generation-persistence-server'
+    | '/api/harness-test'
     | '/api/image'
     | '/api/interrupts-test'
     | '/api/join-run-client-tool'
@@ -1513,6 +1525,7 @@ export interface RootRouteChildren {
   ApiGeminiNativeImageWireRoute: typeof ApiGeminiNativeImageWireRoute
   ApiGenerationPersistenceResumeRoute: typeof ApiGenerationPersistenceResumeRoute
   ApiGenerationPersistenceServerRoute: typeof ApiGenerationPersistenceServerRoute
+  ApiHarnessTestRoute: typeof ApiHarnessTestRoute
   ApiImageRoute: typeof ApiImageRouteWithChildren
   ApiInterruptsTestRoute: typeof ApiInterruptsTestRoute
   ApiJoinRunClientToolRoute: typeof ApiJoinRunClientToolRoute
@@ -2190,6 +2203,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiImageRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/harness-test': {
+      id: '/api/harness-test'
+      path: '/api/harness-test'
+      fullPath: '/api/harness-test'
+      preLoaderRoute: typeof ApiHarnessTestRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/generation-persistence-server': {
       id: '/api/generation-persistence-server'
       path: '/api/generation-persistence-server'
@@ -2511,6 +2531,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiGeminiNativeImageWireRoute: ApiGeminiNativeImageWireRoute,
   ApiGenerationPersistenceResumeRoute: ApiGenerationPersistenceResumeRoute,
   ApiGenerationPersistenceServerRoute: ApiGenerationPersistenceServerRoute,
+  ApiHarnessTestRoute: ApiHarnessTestRoute,
   ApiImageRoute: ApiImageRouteWithChildren,
   ApiInterruptsTestRoute: ApiInterruptsTestRoute,
   ApiJoinRunClientToolRoute: ApiJoinRunClientToolRoute,
diff --git a/testing/e2e/src/routes/api.harness-test.ts b/testing/e2e/src/routes/api.harness-test.ts
new file mode 100644
index 0000000000..6b7be92b52
--- /dev/null
+++ b/testing/e2e/src/routes/api.harness-test.ts
@@ -0,0 +1,80 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { defineAgent } from '@tanstack/ai'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { z } from 'zod'
+import { createTextAdapter } from '@/lib/providers'
+
+/**
+ * Harness session. The main model and the agent are real OpenAI adapters
+ * against aimock.
+ *
+ * - `turns`: two prompts sent back to back. The second waits for the first,
+ *   then runs with the first turn in its history.
+ * - `agent`: `pricer` runs from code with typed input. Its result goes into
+ *   the transcript, then a prompt runs.
+ */
+export const Route = createFileRoute('/api/harness-test')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const body = (await request.json()) as {
+          scenario?: string
+          testId?: string
+          aimockPort?: number
+        }
+        const testId = body.testId
+        const aimockPort = body.aimockPort
+        const openai = () =>
+          createTextAdapter('openai', undefined, aimockPort, testId).adapter
+
+        const pricer = defineAgent({
+          name: 'pricer',
+          description: 'Prices one vendor',
+          inputSchema: z.object({ task: z.string() }),
+          run: (ctx) =>
+            ctx.chat({
+              adapter: openai(),
+              messages: [{ role: 'user', content: ctx.input.task }],
+              stream: false,
+            }),
+        })
+        const harness = defineHarness({
+          name: 'e2e/harness',
+          adapter: openai(),
+          agents: [pricer],
+        })
+        const persistence = memoryPersistence()
+        const host = createHarnessHost({ persistence })
+        try {
+          const session = await host.open(harness, { threadId: 'e2e-thread' })
+          if (body.scenario === 'agent') {
+            const result = await session.agents.pricer.run({
+              task: '[harness-agent] price vendor a',
+            })
+            const turn = await session.prompt(
+              '[harness-agent] what did it cost?',
+            )
+            return Response.json({ result, text: turn.text })
+          }
+          const first = session.prompt('[harness-turns] first')
+          const second = session.prompt('[harness-turns] second')
+          const texts = [(await first).text, (await second).text]
+          const saved =
+            await persistence.stores.messages.loadThread('e2e-thread')
+          return Response.json({
+            texts,
+            roles: saved.map((message) => message.role),
+          })
+        } catch (error) {
+          return Response.json(
+            { error: error instanceof Error ? error.message : String(error) },
+            { status: 500 },
+          )
+        } finally {
+          await host.close()
+        }
+      },
+    },
+  },
+})
diff --git a/testing/e2e/tests/harness.spec.ts b/testing/e2e/tests/harness.spec.ts
new file mode 100644
index 0000000000..03e3c458a5
--- /dev/null
+++ b/testing/e2e/tests/harness.spec.ts
@@ -0,0 +1,31 @@
+import { test, expect } from './fixtures'
+
+test.describe('harness session', () => {
+  test('a second prompt waits for the first and keeps its history', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'turns', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    const body = await response.json()
+    expect(body.texts).toEqual(['First answer.', 'Second answer.'])
+    expect(body.roles).toEqual(['user', 'assistant', 'user', 'assistant'])
+  })
+
+  test('a typed agent runs from code and the next turn sees its result', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'agent', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    const body = await response.json()
+    expect(body.result).toBe('Vendor A costs 12 dollars.')
+    expect(body.text).toBe('It cost 12 dollars.')
+  })
+})

From 06b138dfe9be1b6af0e761bf6bc9579b6e47ff9d Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 12:41:03 +0200
Subject: [PATCH 007/286] feat(ai-harness): resume crashed turns and serve
 sessions to clients

Resume: a session holds a lease on each running turn, saves the transcript
around tool phases, and records tool calls that have no result. When a host
opens a thread whose turn lost its lease, it continues the turn in a new run
and emits harness.operation.resumed. toolDefinition({ replay }) decides
whether an unfinished tool runs again.

Protocol: createHarnessHandler serves capabilities, standard AG-UI runs, the
session event stream with cursors, control inputs with receipts, and
snapshots, behind a required authorize hook. handleHarnessSocket serves the
same session tier over a WebSocket. @tanstack/ai-harness/client adds a typed,
reconnecting client. harnessText runs a harness as the model of another
chat() call.

ACP: @tanstack/ai-acp/agent serves a harness as an ACP v2 agent (SDK 1.5),
with tool approvals as permission requests.

CLI: new @tanstack/ai-harness-cli. runCli(harness) gives an Ink terminal UI,
a print mode with exit codes, NDJSON output, --acp, and --serve.
---
 .changeset/harness-p2-protocols.md            |  14 +
 docs/config.json                              |  15 +
 docs/harness/cli.md                           |  83 +++++
 docs/harness/connect.md                       | 127 ++++++++
 docs/harness/durable-sessions.md              |  71 ++++
 packages/ai-acp/package.json                  |  14 +-
 packages/ai-acp/src/agent/index.ts            | 251 ++++++++++++++
 packages/ai-acp/tests/agent.test.ts           | 175 ++++++++++
 packages/ai-acp/vite.config.ts                |   2 +-
 packages/ai-harness-cli/README.md             |  63 ++++
 packages/ai-harness-cli/package.json          |  92 ++++++
 packages/ai-harness-cli/src/args.ts           |  68 ++++
 packages/ai-harness-cli/src/commands.ts       | 100 ++++++
 packages/ai-harness-cli/src/index.ts          | 111 +++++++
 packages/ai-harness-cli/src/interactive.tsx   | 170 ++++++++++
 packages/ai-harness-cli/src/lines.ts          |  80 +++++
 packages/ai-harness-cli/src/print.ts          |  54 +++
 packages/ai-harness-cli/src/serve.ts          | 113 +++++++
 packages/ai-harness-cli/src/session-view.ts   |  96 ++++++
 packages/ai-harness-cli/tests/cli.test.ts     | 265 +++++++++++++++
 .../ai-harness-cli/tests/interactive.test.ts  | 106 ++++++
 packages/ai-harness-cli/tsconfig.json         |   9 +
 packages/ai-harness-cli/vite.config.ts        |  35 ++
 packages/ai-harness/package.json              |   4 +
 packages/ai-harness/src/client.ts             | 198 +++++++++++
 packages/ai-harness/src/harness-text.ts       | 133 ++++++++
 packages/ai-harness/src/host.ts               |   2 +
 packages/ai-harness/src/http.ts               | 308 ++++++++++++++++++
 packages/ai-harness/src/index.ts              |  20 ++
 packages/ai-harness/src/protocol.ts           | 200 ++++++++++++
 packages/ai-harness/src/resume.ts             | 146 +++++++++
 packages/ai-harness/src/session.ts            |  67 ++++
 packages/ai-harness/src/types.ts              |   1 +
 packages/ai-harness/tests/client.test.ts      |  87 +++++
 .../ai-harness/tests/harness-text.test.ts     |  49 +++
 packages/ai-harness/tests/protocol.test.ts    | 287 ++++++++++++++++
 packages/ai-harness/tests/resume.test.ts      | 185 +++++++++++
 packages/ai-harness/vite.config.ts            |   2 +-
 .../activities/chat/tools/tool-definition.ts  |   7 +
 packages/ai/src/types.ts                      |   7 +
 pnpm-lock.yaml                                | 299 ++++++++++++++---
 testing/e2e/fixtures/harness/basic.json       |  40 ++-
 testing/e2e/src/routeTree.gen.ts              |  21 ++
 .../e2e/src/routes/api.harness-protocol.$.ts  |  57 ++++
 testing/e2e/tests/harness-protocol.spec.ts    |  83 +++++
 45 files changed, 4262 insertions(+), 55 deletions(-)
 create mode 100644 .changeset/harness-p2-protocols.md
 create mode 100644 docs/harness/cli.md
 create mode 100644 docs/harness/connect.md
 create mode 100644 docs/harness/durable-sessions.md
 create mode 100644 packages/ai-acp/src/agent/index.ts
 create mode 100644 packages/ai-acp/tests/agent.test.ts
 create mode 100644 packages/ai-harness-cli/README.md
 create mode 100644 packages/ai-harness-cli/package.json
 create mode 100644 packages/ai-harness-cli/src/args.ts
 create mode 100644 packages/ai-harness-cli/src/commands.ts
 create mode 100644 packages/ai-harness-cli/src/index.ts
 create mode 100644 packages/ai-harness-cli/src/interactive.tsx
 create mode 100644 packages/ai-harness-cli/src/lines.ts
 create mode 100644 packages/ai-harness-cli/src/print.ts
 create mode 100644 packages/ai-harness-cli/src/serve.ts
 create mode 100644 packages/ai-harness-cli/src/session-view.ts
 create mode 100644 packages/ai-harness-cli/tests/cli.test.ts
 create mode 100644 packages/ai-harness-cli/tests/interactive.test.ts
 create mode 100644 packages/ai-harness-cli/tsconfig.json
 create mode 100644 packages/ai-harness-cli/vite.config.ts
 create mode 100644 packages/ai-harness/src/client.ts
 create mode 100644 packages/ai-harness/src/harness-text.ts
 create mode 100644 packages/ai-harness/src/http.ts
 create mode 100644 packages/ai-harness/src/protocol.ts
 create mode 100644 packages/ai-harness/src/resume.ts
 create mode 100644 packages/ai-harness/tests/client.test.ts
 create mode 100644 packages/ai-harness/tests/harness-text.test.ts
 create mode 100644 packages/ai-harness/tests/protocol.test.ts
 create mode 100644 packages/ai-harness/tests/resume.test.ts
 create mode 100644 testing/e2e/src/routes/api.harness-protocol.$.ts
 create mode 100644 testing/e2e/tests/harness-protocol.spec.ts

diff --git a/.changeset/harness-p2-protocols.md b/.changeset/harness-p2-protocols.md
new file mode 100644
index 0000000000..cbdc0bbe0b
--- /dev/null
+++ b/.changeset/harness-p2-protocols.md
@@ -0,0 +1,14 @@
+---
+'@tanstack/ai-harness': minor
+'@tanstack/ai-harness-cli': minor
+'@tanstack/ai-acp': minor
+'@tanstack/ai': minor
+---
+
+Harness sessions now survive a crash and talk to clients.
+
+- **Resume.** A session holds a lease on each running turn, saves the transcript around each tool phase, and records tool calls that have no result yet. When a host opens a session whose turn lost its lease, it continues the turn in a new run and emits `harness.operation.resumed`. `toolDefinition({ replay: 'safe' | 'never' })` in `@tanstack/ai` decides whether an unfinished tool runs again.
+- **Protocol.** `createHarnessHandler` serves capabilities, standard AG-UI runs, the session event stream with cursors, control inputs with receipts, and snapshots. `authorize` is required. `handleHarnessSocket` serves the same session tier over a WebSocket. `createHarnessClient` in `@tanstack/ai-harness/client` is a typed, reconnecting client.
+- **`harnessText`** runs a harness as the text adapter of another `chat()` call.
+- **ACP v2.** `@tanstack/ai-acp/agent` adds `createAcpAgent` and `serveAcp`, which serve a harness as an ACP v2 agent (experimental, like the draft protocol). `@tanstack/ai-acp` now uses `@agentclientprotocol/sdk` 1.5. The existing ACP client adapters keep working.
+- **New package `@tanstack/ai-harness-cli`.** `runCli(harness)` gives a harness an Ink terminal UI, a print mode with exit codes, NDJSON output, `--acp`, and `--serve`.
diff --git a/docs/config.json b/docs/config.json
index e08f6892b5..4dac967f22 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -808,6 +808,21 @@
           "label": "Build your first harness",
           "to": "harness/overview",
           "addedAt": "2026-09-26"
+        },
+        {
+          "label": "Connect clients",
+          "to": "harness/connect",
+          "addedAt": "2026-09-26"
+        },
+        {
+          "label": "Run in the terminal",
+          "to": "harness/cli",
+          "addedAt": "2026-09-26"
+        },
+        {
+          "label": "Durable sessions",
+          "to": "harness/durable-sessions",
+          "addedAt": "2026-09-26"
         }
       ]
     },
diff --git a/docs/harness/cli.md b/docs/harness/cli.md
new file mode 100644
index 0000000000..a572a2bc02
--- /dev/null
+++ b/docs/harness/cli.md
@@ -0,0 +1,83 @@
+---
+title: Run a harness in the terminal
+id: harness-cli
+order: 3
+description: "Give your harness a terminal UI, a print mode for scripts and CI, NDJSON output, an ACP mode for editors, and an HTTP server."
+keywords:
+  - tanstack ai
+  - harness
+  - cli
+  - terminal
+  - ink
+---
+
+You built a harness and want to use it like Claude Code: type in a terminal, watch it work, approve tools. You also want to run it in CI. `runCli` gives one harness all of these modes.
+
+## Install
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: @tanstack/ai-harness-cli
+vue: @tanstack/ai-harness-cli
+solid: @tanstack/ai-harness-cli
+svelte: @tanstack/ai-harness-cli
+preact: @tanstack/ai-harness-cli
+angular: @tanstack/ai-harness-cli
+vanilla: @tanstack/ai-harness-cli
+octane: @tanstack/ai-harness-cli
+
+<!-- ::end:tabs -->
+
+The interactive UI uses Ink, which needs Node 22 or later.
+
+## 1. Write the entry file
+
+```ts group=harness-cli
+import { defineHarness } from '@tanstack/ai-harness'
+import { runCli } from '@tanstack/ai-harness-cli'
+import { openaiText } from '@tanstack/ai-openai'
+
+const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-5.6'),
+})
+
+process.exitCode = await runCli(assistant)
+```
+
+## 2. Pick a mode
+
+- No flags: the interactive UI. Type a message and press Enter. While the agent works, Enter steers it and Esc cancels.
+- `-p "prompt"`: run one prompt, print the answer, and exit.
+- `-p "prompt" --output ndjson`: print every AG-UI event as one JSON line.
+- `--acp`: serve the harness as an ACP v2 agent over stdio, for editors. Needs `@tanstack/ai-acp`.
+- `--serve`: serve the session protocol over HTTP on `127.0.0.1:8787`. Every request needs the bearer token. Pass `--token`, set `HARNESS_TOKEN`, or copy the token the CLI prints.
+
+When stdin is a pipe, the CLI reads one message or command per line and waits for each turn.
+
+## 3. Use it in CI
+
+`-p` exits with a code your script can check:
+
+| Code | Meaning |
+|---|---|
+| 0 | The turn finished. |
+| 1 | The turn failed. |
+| 2 | The turn waits for an approval. |
+| 130 | The turn was cancelled. |
+
+## Commands in the interactive UI
+
+- `/agents`: list the agents.
+- `/agent <name> {"json":"input"}`: run an agent in the background. When it is done, a new turn starts with its result.
+- `/cancel`: cancel the running turn.
+- `/status`: show what runs and what waits.
+- `/exit`: quit.
+
+When a turn stops for an approval, type `y` to approve or `n` to reject.
+
+## What you have now
+
+- One entry file that runs your harness as a terminal app, a script step, an editor agent, or a server.
+
+Next: keep long turns alive through crashes with [durable sessions](./durable-sessions).
diff --git a/docs/harness/connect.md b/docs/harness/connect.md
new file mode 100644
index 0000000000..f38633fb99
--- /dev/null
+++ b/docs/harness/connect.md
@@ -0,0 +1,127 @@
+---
+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, an editor over ACP, or another chat() call."
+keywords:
+  - tanstack ai
+  - harness
+  - AG-UI
+  - ACP
+  - websocket
+  - harnessText
+---
+
+Your harness runs on a server, but the people who use it are in a browser, an editor, or another agent. `createHarnessHandler` serves a session over HTTP. A web app talks to it with `createHarnessClient`, an editor with ACP, 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-5.6'),
+})
+
+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 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. Any AG-UI client works.
+- `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.
+- `GET snapshot?threadId=`: the status, running operations, and waiting approvals.
+
+## 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.
+
+## 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' } })
+}
+```
+
+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 from an editor (ACP)
+
+Editors such as Zed start agents as a process and talk ACP over stdio. `serveAcp` makes the harness an ACP v2 agent:
+
+```ts group=harness-connect
+import { serveAcp } from '@tanstack/ai-acp/agent'
+
+serveAcp({ host, harness: assistant })
+```
+
+Tool approvals become permission requests in the editor. ACP v2 is still a draft, so this API is experimental.
+
+## 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.
+
+## What you have now
+
+- One handler that serves standard AG-UI and the session stream.
+- A typed web client that reconnects and resumes from a cursor.
+- A WebSocket, an ACP agent for editors, and a harness you can call from `chat()`.
+
+Next: run the same harness in a terminal with the [CLI](./cli).
diff --git a/docs/harness/durable-sessions.md b/docs/harness/durable-sessions.md
new file mode 100644
index 0000000000..a97a22270b
--- /dev/null
+++ b/docs/harness/durable-sessions.md
@@ -0,0 +1,71 @@
+---
+title: Durable sessions
+id: harness-durable-sessions
+order: 4
+description: "Keep a harness turn alive through a crash or a deploy. The next host continues it from the last checkpoint."
+keywords:
+  - tanstack ai
+  - harness
+  - durability
+  - resume
+  - checkpoint
+---
+
+A long agent turn can outlive the process that started it: a deploy restarts the server, or the machine crashes in the middle of a tool call. With durable stores, the next host that opens the session continues the turn from its last checkpoint.
+
+## Give the host durable stores
+
+Use your own stores built with `defineAIPersistence`. Resume needs these:
+
+- `messages`: the transcript.
+- `runs`: the run records, with leases and checkpoints. Implement `listByThread`.
+- `inbox`: messages that were accepted but did not run yet.
+
+```ts group=harness-durable
+import { createHarnessHost } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+
+// Swap in your own stores. Memory stores do not survive a restart.
+const host = createHarnessHost({ persistence: memoryPersistence() })
+```
+
+## What the session saves while a turn runs
+
+- A lease on the run record. The host renews it every 10 seconds. It expires after 30 seconds.
+- The transcript before and after each tool phase.
+- Each tool call that started and has no result yet.
+
+## What happens after a crash
+
+When a host opens the session and finds a turn whose lease expired, it continues that turn in a new run:
+
+1. The old run is marked failed.
+2. Tool calls without a result get handled by their `replay` setting.
+3. A new chat run starts from the saved transcript.
+4. Clients see a `harness.operation.resumed` event, then the new events.
+
+## Mark tools that are safe to run again
+
+A crash can stop a run after a tool started but before its result was saved. Tell the harness what to do with `replay`:
+
+```ts group=harness-durable
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+
+const lookup = toolDefinition({
+  name: 'lookup_order',
+  description: 'Read an order',
+  inputSchema: z.object({ id: z.string() }),
+  replay: 'safe',
+}).server(async ({ id }) => ({ id, status: 'shipped' }))
+```
+
+- `replay: 'safe'`: the tool runs again. Use it for reads and other idempotent calls.
+- `replay: 'never'` (default): the model gets a note that the tool may or may not have run, and checks before it tries again.
+
+A model response that was cut in the middle runs again after resume. The provider can bill that call twice.
+
+## What you have now
+
+- Turns that continue after a crash or a deploy.
+- Tools that either run again safely or tell the model to check first.
diff --git a/packages/ai-acp/package.json b/packages/ai-acp/package.json
index 0e63ad861f..37012401e0 100644
--- a/packages/ai-acp/package.json
+++ b/packages/ai-acp/package.json
@@ -26,6 +26,10 @@
     ".": {
       "types": "./dist/esm/index.d.ts",
       "import": "./dist/esm/index.js"
+    },
+    "./agent": {
+      "types": "./dist/esm/agent/index.d.ts",
+      "import": "./dist/esm/agent/index.js"
     }
   },
   "files": [
@@ -44,14 +48,22 @@
     "test:types": "tsc"
   },
   "dependencies": {
-    "@agentclientprotocol/sdk": "^0.25.0"
+    "@agentclientprotocol/sdk": "^1.5.0"
   },
   "peerDependencies": {
     "@tanstack/ai": "workspace:^",
+    "@tanstack/ai-harness": "workspace:^",
     "@tanstack/ai-sandbox": "workspace:^"
   },
+  "peerDependenciesMeta": {
+    "@tanstack/ai-harness": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-harness": "workspace:*",
+    "@tanstack/ai-persistence": "workspace:*",
     "@tanstack/ai-sandbox": "workspace:*",
     "@tanstack/ai-sandbox-local-process": "workspace:*",
     "@vitest/coverage-v8": "4.1.10"
diff --git a/packages/ai-acp/src/agent/index.ts b/packages/ai-acp/src/agent/index.ts
new file mode 100644
index 0000000000..a9d3fc1af0
--- /dev/null
+++ b/packages/ai-acp/src/agent/index.ts
@@ -0,0 +1,251 @@
+import { EventType } from '@tanstack/ai'
+import {
+  PROTOCOL_VERSION,
+  agent,
+  ndJsonStream,
+} from '@agentclientprotocol/sdk/experimental/v2'
+import type {
+  AgentApp,
+  AgentContext,
+  AgentConnection,
+  SessionUpdate,
+  Stream,
+} from '@agentclientprotocol/sdk/experimental/v2'
+import type { Interrupt, RunAgentResumeItem, StreamChunk } from '@tanstack/ai'
+import type {
+  AnyHarness,
+  HarnessHost,
+  HarnessSession,
+  Operation,
+} from '@tanstack/ai-harness'
+
+export interface AcpAgentOptions {
+  host: HarnessHost
+  harness: AnyHarness
+  /** Reported in `initialize`. Default `'0.0.0'`. */
+  version?: string
+}
+
+/** The text of an ACP prompt. Non-text blocks are skipped. */
+function promptText(
+  prompt: ReadonlyArray<{ type: string; text?: unknown }>,
+): string {
+  return prompt
+    .map((block) =>
+      block.type === 'text' && typeof block.text === 'string' ? block.text : '',
+    )
+    .filter((text) => text !== '')
+    .join('\n')
+}
+
+/** One AG-UI chunk as an ACP session update, or `undefined` to skip it. */
+export function toSessionUpdate(chunk: StreamChunk): SessionUpdate | undefined {
+  // Child agent work stays inside the harness. ACP shows the main turn.
+  if ('subagentRunId' in chunk && chunk.subagentRunId) return undefined
+  if (chunk.type === EventType.TEXT_MESSAGE_CONTENT) {
+    return {
+      sessionUpdate: 'agent_message_chunk',
+      messageId: chunk.messageId,
+      content: { type: 'text', text: chunk.delta },
+    }
+  }
+  if (chunk.type === EventType.REASONING_MESSAGE_CONTENT) {
+    return {
+      sessionUpdate: 'agent_thought_chunk',
+      messageId: chunk.messageId,
+      content: { type: 'text', text: chunk.delta },
+    }
+  }
+  if (chunk.type === EventType.TOOL_CALL_START) {
+    return {
+      sessionUpdate: 'tool_call_update',
+      toolCallId: chunk.toolCallId,
+      name: chunk.toolCallName,
+      title: chunk.toolCallName,
+      status: 'in_progress',
+    }
+  }
+  if (chunk.type === EventType.TOOL_CALL_RESULT) {
+    return {
+      sessionUpdate: 'tool_call_update',
+      toolCallId: chunk.toolCallId,
+      status: 'completed',
+    }
+  }
+  return undefined
+}
+
+const APPROVAL_OPTIONS = [
+  { optionId: 'allow', name: 'Allow', kind: 'allow_once' },
+  { optionId: 'reject', name: 'Reject', kind: 'reject_once' },
+] as const
+
+/**
+ * An ACP v2 agent backed by a harness. Each ACP session is one harness
+ * session. Prompts follow the harness `busy` setting, tool approvals become
+ * `session/request_permission` requests, and cancel cancels the running turn.
+ *
+ * ACP v2 is a draft, so this API is experimental too.
+ */
+export function createAcpAgent(options: AcpAgentOptions): AgentApp {
+  const { host, harness } = options
+  const sessions = new Map<string, HarnessSession>()
+
+  const sessionFor = async (sessionId: string) => {
+    let session = sessions.get(sessionId)
+    if (!session) {
+      session = await host.open(harness, { threadId: sessionId })
+      sessions.set(sessionId, session)
+    }
+    return session
+  }
+
+  const notify = (
+    client: AgentContext,
+    sessionId: string,
+    update: SessionUpdate,
+  ) => client.notify('session/update', { sessionId, update }).catch(() => {})
+
+  /**
+   * Ask the client about each approval, then continue the turn. The next
+   * operation is wrapped, because an operation is thenable and an async
+   * function would unwrap it.
+   */
+  const approve = async (
+    client: AgentContext,
+    sessionId: string,
+    session: HarnessSession,
+    interrupts: ReadonlyArray<Interrupt>,
+  ): Promise<{ next: Operation<unknown> | undefined }> => {
+    await notify(client, sessionId, {
+      sessionUpdate: 'state_update',
+      state: 'requires_action',
+    })
+    const resume: Array<RunAgentResumeItem> = []
+    for (const interrupt of interrupts) {
+      const toolCallId = interrupt.toolCallId ?? interrupt.id
+      const response = await client.request('session/request_permission', {
+        sessionId,
+        title: interrupt.message ?? 'Allow this tool call?',
+        subject: { type: 'tool_call', toolCall: { toolCallId } },
+        options: [...APPROVAL_OPTIONS],
+      })
+      const allowed =
+        response.outcome.outcome === 'selected' &&
+        'optionId' in response.outcome &&
+        response.outcome.optionId === 'allow'
+      resume.push({
+        interruptId: interrupt.id,
+        status: 'resolved',
+        payload: allowed,
+      })
+    }
+    const receipt = await session.resolve(resume)
+    return {
+      next: receipt.operationId
+        ? session.operation(receipt.operationId)
+        : undefined,
+    }
+  }
+
+  /** Stream one turn to the client, through any approvals, then report idle. */
+  const pump = async (
+    client: AgentContext,
+    sessionId: string,
+    session: HarnessSession,
+    first: Operation<unknown>,
+  ) => {
+    await notify(client, sessionId, {
+      sessionUpdate: 'state_update',
+      state: 'running',
+    })
+    let operation: Operation<unknown> | undefined = first
+    let stopReason = 'end_turn'
+    while (operation) {
+      for await (const chunk of operation.stream()) {
+        const update = toSessionUpdate(chunk)
+        if (update) await notify(client, sessionId, update)
+      }
+      const result: unknown = await operation.then(
+        (value) => value,
+        () => undefined,
+      )
+      if (operation.status() === 'cancelled') stopReason = 'cancelled'
+      const interrupts =
+        typeof result === 'object' &&
+        result !== null &&
+        'interrupts' in result &&
+        Array.isArray(result.interrupts)
+          ? (result.interrupts as Array<Interrupt>)
+          : []
+      operation =
+        interrupts.length > 0
+          ? (await approve(client, sessionId, session, interrupts)).next
+          : undefined
+    }
+    await notify(client, sessionId, {
+      sessionUpdate: 'state_update',
+      state: 'idle',
+      stopReason,
+    })
+  }
+
+  return agent()
+    .onRequest('initialize', () => ({
+      protocolVersion: PROTOCOL_VERSION,
+      info: { name: harness.name, version: options.version ?? '0.0.0' },
+      capabilities: {},
+    }))
+    .onRequest('session/new', async () => {
+      const sessionId = `acp-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`
+      await sessionFor(sessionId)
+      return { sessionId }
+    })
+    .onRequest('session/resume', async ({ params }) => {
+      await sessionFor(params.sessionId)
+      return {}
+    })
+    .onRequest('session/prompt', async ({ params, client }) => {
+      const session = await sessionFor(params.sessionId)
+      const operation = session.prompt(promptText(params.prompt))
+      void pump(client, params.sessionId, session, operation)
+      return { messageId: operation.id }
+    })
+    .onRequest('session/close', async ({ params }) => {
+      const session = sessions.get(params.sessionId)
+      sessions.delete(params.sessionId)
+      await session?.close()
+    })
+    .onNotification('session/cancel', async ({ params }) => {
+      await sessions.get(params.sessionId)?.cancel()
+    })
+}
+
+/**
+ * Serve a harness as an ACP v2 agent over a stream. With no stream, it uses
+ * stdin and stdout as newline-delimited JSON (for editors that start the
+ * agent as a process).
+ */
+export function serveAcp(
+  options: AcpAgentOptions & { stream?: Stream },
+): AgentConnection {
+  return createAcpAgent(options).connect(options.stream ?? stdioStream())
+}
+
+function stdioStream(): Stream {
+  const output = new WritableStream<Uint8Array>({
+    write: (chunk) =>
+      new Promise((resolve, reject) =>
+        process.stdout.write(chunk, (error) =>
+          error ? reject(error) : resolve(),
+        ),
+      ),
+  })
+  const input = new ReadableStream<Uint8Array>({
+    start(controller) {
+      process.stdin.on('data', (data: Uint8Array) => controller.enqueue(data))
+      process.stdin.on('end', () => controller.close())
+    },
+  })
+  return ndJsonStream(output, input)
+}
diff --git a/packages/ai-acp/tests/agent.test.ts b/packages/ai-acp/tests/agent.test.ts
new file mode 100644
index 0000000000..0fcfe8bf57
--- /dev/null
+++ b/packages/ai-acp/tests/agent.test.ts
@@ -0,0 +1,175 @@
+import { describe, expect, it, vi } from 'vitest'
+import { EventType, toolDefinition } from '@tanstack/ai'
+import { client } from '@agentclientprotocol/sdk/experimental/v2'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { createAcpAgent } from '../src/agent'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import type { SessionUpdate } from '@agentclientprotocol/sdk/experimental/v2'
+
+const now = () => Date.now()
+
+function scripted(turns: Array<Array<StreamChunk>>) {
+  let call = 0
+  const adapter: AnyTextAdapter = {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    '~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,
+    },
+    chatStream: () => {
+      const chunks = turns[call] ?? []
+      call += 1
+      return (async function* () {
+        yield* chunks
+      })()
+    },
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+  }
+  return adapter
+}
+
+const textTurn = (text: string): Array<StreamChunk> => [
+  { type: EventType.RUN_STARTED, runId: 'r', threadId: 't', timestamp: now() },
+  {
+    type: EventType.TEXT_MESSAGE_START,
+    messageId: 'm',
+    role: 'assistant',
+    timestamp: now(),
+  },
+  {
+    type: EventType.TEXT_MESSAGE_CONTENT,
+    messageId: 'm',
+    delta: text,
+    timestamp: now(),
+  },
+  { type: EventType.TEXT_MESSAGE_END, messageId: 'm', timestamp: now() },
+  {
+    type: EventType.RUN_FINISHED,
+    runId: 'r',
+    threadId: 't',
+    timestamp: now(),
+    metadata: { tanstack: { finishReason: 'stop' } },
+  },
+]
+
+const toolTurn = (name: string, args: string): Array<StreamChunk> => [
+  { type: EventType.RUN_STARTED, runId: 'r', threadId: 't', timestamp: now() },
+  {
+    type: EventType.TOOL_CALL_START,
+    toolCallId: 'call_1',
+    toolCallName: name,
+    timestamp: now(),
+  },
+  {
+    type: EventType.TOOL_CALL_ARGS,
+    toolCallId: 'call_1',
+    delta: args,
+    timestamp: now(),
+  },
+  { type: EventType.TOOL_CALL_END, toolCallId: 'call_1', timestamp: now() },
+  {
+    type: EventType.RUN_FINISHED,
+    runId: 'r',
+    threadId: 't',
+    timestamp: now(),
+    metadata: { tanstack: { finishReason: 'tool_calls' } },
+  },
+]
+
+describe('ACP v2 agent', () => {
+  it('streams a prompt, asks for approval, and reports idle', async () => {
+    const remove = vi.fn(async () => ({ removed: true }))
+    const harness = defineHarness({
+      name: 'test/acp',
+      adapter: scripted([
+        toolTurn('remove', '{"path":"a.txt"}'),
+        textTurn('Removed a.txt.'),
+      ]),
+      tools: [
+        toolDefinition({
+          name: 'remove',
+          description: 'Remove a file',
+          needsApproval: true,
+          inputSchema: {
+            type: 'object',
+            properties: { path: { type: 'string' } },
+            required: ['path'],
+          },
+        }).server(remove),
+      ],
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const agentApp = createAcpAgent({ host, harness, version: '1.0.0' })
+
+    const updates: Array<SessionUpdate> = []
+    const permissions: Array<string> = []
+    const editor = client()
+      .onNotification('session/update', ({ params }) => {
+        updates.push(params.update)
+      })
+      .onRequest('session/request_permission', ({ params }) => {
+        permissions.push(params.title)
+        return { outcome: { outcome: 'selected', optionId: 'allow' } }
+      })
+
+    await editor.connectWith(agentApp, async (ctx) => {
+      const init = await ctx.request('initialize', {
+        protocolVersion: 2,
+        info: { name: 'test-editor', version: '1.0.0' },
+      })
+      expect(init.info.name).toBe('test/acp')
+
+      const { sessionId } = await ctx.request('session/new', {
+        cwd: '/tmp',
+        mcpServers: [],
+      })
+      const prompted = await ctx.request('session/prompt', {
+        sessionId,
+        prompt: [{ type: 'text', text: 'remove a.txt' }],
+      })
+      expect(prompted.messageId).toMatch(/^op-chat-/)
+
+      await vi.waitFor(() =>
+        expect(
+          updates.some(
+            (update) =>
+              update.sessionUpdate === 'state_update' &&
+              update.state === 'idle',
+          ),
+        ).toBe(true),
+      )
+    })
+
+    expect(permissions).toHaveLength(1)
+    expect(remove).toHaveBeenCalledTimes(1)
+    const states = updates
+      .filter((update) => update.sessionUpdate === 'state_update')
+      .map((update) => ('state' in update ? update.state : ''))
+    expect(states).toEqual(['running', 'requires_action', 'idle'])
+    const text = updates
+      .map((update) =>
+        update.sessionUpdate === 'agent_message_chunk'
+          ? JSON.stringify(update)
+          : '',
+      )
+      .join('')
+    expect(text).toContain('Removed a.txt.')
+    expect(
+      updates.some((update) => update.sessionUpdate === 'tool_call_update'),
+    ).toBe(true)
+    await host.close()
+  })
+})
diff --git a/packages/ai-acp/vite.config.ts b/packages/ai-acp/vite.config.ts
index 588ff924d2..ab0a9e68fc 100644
--- a/packages/ai-acp/vite.config.ts
+++ b/packages/ai-acp/vite.config.ts
@@ -33,7 +33,7 @@ const config = defineConfig({
 // Put package test settings last so they win over the shared build config.
 export default mergeConfig(
   tanstackViteConfig({
-    entry: ['./src/index.ts'],
+    entry: ['./src/index.ts', './src/agent/index.ts'],
     srcDir: './src',
     cjs: false,
   }),
diff --git a/packages/ai-harness-cli/README.md b/packages/ai-harness-cli/README.md
new file mode 100644
index 0000000000..1ff4d8ea4d
--- /dev/null
+++ b/packages/ai-harness-cli/README.md
@@ -0,0 +1,63 @@
+<div align="center">
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://tanstack.com/api/readme/ai.png?theme=dark"
+    />
+    <source
+      media="(prefers-color-scheme: light)"
+      srcset="https://tanstack.com/api/readme/ai.png"
+    />
+    <img
+      src="https://tanstack.com/api/readme/ai.png"
+      alt="TanStack AI"
+      width="900"
+    />
+  </picture>
+</div>
+
+<br />
+
+# @tanstack/ai-harness-cli
+
+Run a TanStack AI harness from the terminal: an interactive UI, a print mode for scripts and CI, NDJSON output, an ACP mode for editors, and an HTTP server.
+
+## Installation
+
+```bash
+npm install @tanstack/ai-harness @tanstack/ai-harness-cli
+```
+
+The interactive UI uses Ink, which needs Node 22 or later.
+
+## Usage
+
+```ts
+#!/usr/bin/env node
+import { defineHarness } from '@tanstack/ai-harness'
+import { runCli } from '@tanstack/ai-harness-cli'
+import { openaiText } from '@tanstack/ai-openai'
+
+const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-5.6'),
+})
+
+process.exitCode = await runCli(assistant)
+```
+
+| Flag                          | Mode                                               |
+| ----------------------------- | -------------------------------------------------- |
+| (none)                        | Interactive UI                                     |
+| `-p "prompt"`                 | Run one prompt and print the answer                |
+| `-p "prompt" --output ndjson` | Print every AG-UI event as JSON lines              |
+| `--acp`                       | ACP v2 agent over stdio (needs `@tanstack/ai-acp`) |
+| `--serve`                     | Session protocol over HTTP, with a bearer token    |
+
+## Documentation
+
+Read [Run a harness in the terminal](https://tanstack.com/ai/latest/docs/harness/cli).
+
+## License
+
+MIT
diff --git a/packages/ai-harness-cli/package.json b/packages/ai-harness-cli/package.json
new file mode 100644
index 0000000000..e9224933f2
--- /dev/null
+++ b/packages/ai-harness-cli/package.json
@@ -0,0 +1,92 @@
+{
+  "name": "@tanstack/ai-harness-cli",
+  "version": "0.0.0",
+  "description": "Run a TanStack AI harness from the terminal: interactive UI, print mode, NDJSON, ACP, and an HTTP server",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-harness-cli"
+  },
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "oxlint src --type-aware --fix",
+    "test:build": "publint --strict",
+    "test:oxlint": "oxlint src --type-aware",
+    "test:coverage": "vitest run --passWithNoTests --coverage --coverage.include='src/**' --coverage.reporter=text-summary --coverage.reporter=json-summary",
+    "test:lib": "vitest --passWithNoTests",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  },
+  "nx": {
+    "targets": {
+      "test:lib": {
+        "dependsOn": [
+          "build",
+          "^build"
+        ]
+      },
+      "test:coverage": {
+        "dependsOn": [
+          "build",
+          "^build"
+        ]
+      },
+      "test:types": {
+        "dependsOn": [
+          "build",
+          "^build"
+        ]
+      }
+    }
+  },
+  "keywords": [
+    "ai",
+    "tanstack",
+    "harness",
+    "agent",
+    "cli",
+    "terminal",
+    "acp"
+  ],
+  "dependencies": {
+    "ink": "^7.1.1",
+    "react": "^19.2.3"
+  },
+  "peerDependencies": {
+    "@tanstack/ai": "workspace:^",
+    "@tanstack/ai-acp": "workspace:^",
+    "@tanstack/ai-harness": "workspace:^",
+    "@tanstack/ai-persistence": "workspace:^"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/ai-acp": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-acp": "workspace:*",
+    "@tanstack/ai-harness": "workspace:*",
+    "@tanstack/ai-persistence": "workspace:*",
+    "@tanstack/ai-sandbox": "workspace:*",
+    "@types/react": "^19.2.7",
+    "@vitest/coverage-v8": "4.1.10"
+  }
+}
diff --git a/packages/ai-harness-cli/src/args.ts b/packages/ai-harness-cli/src/args.ts
new file mode 100644
index 0000000000..c83474e715
--- /dev/null
+++ b/packages/ai-harness-cli/src/args.ts
@@ -0,0 +1,68 @@
+import { parseArgs } from 'node:util'
+
+export interface CliArgs {
+  help: boolean
+  print?: string
+  output: 'text' | 'ndjson'
+  acp: boolean
+  serve: boolean
+  port: number
+  hostname: string
+  token?: string
+  thread: string
+}
+
+export const USAGE = `Usage: <your-cli> [options]
+
+With no options, starts the interactive UI.
+
+Options:
+  -p, --print <prompt>   Run one prompt, print the answer, and exit
+      --output <format>  Print format for --print: text (default) or ndjson
+      --acp              Serve the harness as an ACP v2 agent over stdio
+      --serve            Serve the session protocol over HTTP
+      --port <port>      Port for --serve (default 8787)
+      --host <name>      Host name for --serve (default 127.0.0.1)
+      --token <token>    Bearer token for --serve (default: HARNESS_TOKEN, or a new random token)
+      --thread <id>      Conversation id (default: main)
+  -h, --help             Show this help
+
+Exit codes for --print: 0 done, 1 failed, 2 waiting for approval, 130 cancelled.`
+
+/** Parse CLI flags. Throws with a short message on an unknown flag. */
+export function parseCliArgs(argv: ReadonlyArray<string>): CliArgs {
+  const { values } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: 'boolean', short: 'h' },
+      print: { type: 'string', short: 'p' },
+      output: { type: 'string' },
+      acp: { type: 'boolean' },
+      serve: { type: 'boolean' },
+      port: { type: 'string' },
+      host: { type: 'string' },
+      token: { type: 'string' },
+      thread: { type: 'string' },
+    },
+    strict: true,
+  })
+  const output = values.output ?? 'text'
+  if (output !== 'text' && output !== 'ndjson') {
+    throw new Error(`--output must be text or ndjson, got "${output}".`)
+  }
+  const port = Number(values.port ?? '8787')
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new Error(`--port must be a port number, got "${values.port}".`)
+  }
+  return {
+    help: values.help ?? false,
+    ...(values.print !== undefined ? { print: values.print } : {}),
+    output,
+    acp: values.acp ?? false,
+    serve: values.serve ?? false,
+    port,
+    hostname: values.host ?? '127.0.0.1',
+    ...(values.token !== undefined ? { token: values.token } : {}),
+    thread: values.thread ?? 'main',
+  }
+}
diff --git a/packages/ai-harness-cli/src/commands.ts b/packages/ai-harness-cli/src/commands.ts
new file mode 100644
index 0000000000..4c0ce10d28
--- /dev/null
+++ b/packages/ai-harness-cli/src/commands.ts
@@ -0,0 +1,100 @@
+import type { HarnessSession } from '@tanstack/ai-harness'
+
+export const HELP_TEXT = [
+  'Type a message and press Enter. While the agent works, a new message steers it.',
+  'Commands:',
+  '  /agents                  list the agents',
+  '  /agent <name> [json]     run an agent in the background',
+  '  /cancel                  cancel the running turn (or press Esc)',
+  '  /status                  show the session status',
+  '  /exit                    quit',
+].join('\n')
+
+/** What the UI does after a line of input. */
+export type LineResult =
+  | { type: 'notice'; text: string }
+  | { type: 'exit' }
+  | { type: 'sent' }
+
+/**
+ * Handle one line of user input: a slash command, a steer while a turn runs,
+ * or a new prompt. Shared by the interactive UI and the line mode.
+ */
+export async function handleLine(
+  session: HarnessSession,
+  line: string,
+): Promise<LineResult> {
+  const text = line.trim()
+  if (text === '') return { type: 'notice', text: '' }
+  if (!text.startsWith('/')) {
+    if (session.snapshot().status === 'running') await session.steer(text)
+    else void session.prompt(text)
+    return { type: 'sent' }
+  }
+  const [name = '', ...rest] = text.slice(1).split(' ')
+  const argText = rest.join(' ').trim()
+  switch (name) {
+    case 'help':
+      return { type: 'notice', text: HELP_TEXT }
+    case 'exit':
+    case 'quit':
+      return { type: 'exit' }
+    case 'cancel': {
+      const receipt = await session.cancel()
+      return {
+        type: 'notice',
+        text:
+          receipt.status === 'rejected' ? 'Nothing is running.' : 'Cancelled.',
+      }
+    }
+    case 'status': {
+      const snapshot = session.snapshot()
+      const active = snapshot.activeOperations
+        .map((operation) => operation.agent ?? operation.kind)
+        .join(', ')
+      return {
+        type: 'notice',
+        text: `Status: ${snapshot.status}. Running: ${active || 'nothing'}. Queued turns: ${snapshot.queuedTurns}.`,
+      }
+    }
+    case 'agents': {
+      const agents = session.registry.list()
+      return {
+        type: 'notice',
+        text:
+          agents.length === 0
+            ? 'This harness has no agents.'
+            : agents
+                .map((agent) => `  ${agent.name}: ${agent.description}`)
+                .join('\n'),
+      }
+    }
+    case 'agent': {
+      const [agentName = '', ...inputParts] = argText.split(' ')
+      const handle = session.agent(agentName)
+      if (!handle)
+        return {
+          type: 'notice',
+          text: `Unknown agent: ${agentName || '(none)'}`,
+        }
+      const inputText = inputParts.join(' ').trim()
+      let input: unknown
+      try {
+        input = inputText === '' ? undefined : JSON.parse(inputText)
+      } catch {
+        return {
+          type: 'notice',
+          text: 'The agent input must be JSON, for example {"vendor":"acme"}.',
+        }
+      }
+      const operation = handle.start(input, { wake: true })
+      operation.then(
+        () => {},
+        () => {},
+      )
+      return { type: 'notice', text: `Started ${agentName} in the background.` }
+    }
+    default:
+      return { type: 'notice', text: `Unknown command: /${name}. Type /help.` }
+  }
+}
diff --git a/packages/ai-harness-cli/src/index.ts b/packages/ai-harness-cli/src/index.ts
new file mode 100644
index 0000000000..d91dd0d9d7
--- /dev/null
+++ b/packages/ai-harness-cli/src/index.ts
@@ -0,0 +1,111 @@
+import { createHarnessHost } from '@tanstack/ai-harness'
+import { USAGE, parseCliArgs } from './args'
+import { runLines } from './lines'
+import { EXIT, runPrint } from './print'
+import { createToken, serve } from './serve'
+import type { AnyHarness, HarnessPersistence } from '@tanstack/ai-harness'
+
+export interface RunCliOptions {
+  /** Where sessions keep state. Default: in memory. */
+  persistence?: HarnessPersistence
+  /** Default: `process.argv.slice(2)`. */
+  argv?: ReadonlyArray<string>
+  stdin?: NodeJS.ReadStream
+  stdout?: { write: (text: string) => unknown }
+  stderr?: { write: (text: string) => unknown }
+  env?: Record<string, string | undefined>
+}
+
+/**
+ * Run a harness from the terminal. Resolves to the process exit code.
+ *
+ * @example
+ * ```ts
+ * #!/usr/bin/env node
+ * process.exitCode = await runCli(studio)
+ * ```
+ */
+export async function runCli(
+  harness: AnyHarness,
+  options: RunCliOptions = {},
+): Promise<number> {
+  const stdout = options.stdout ?? process.stdout
+  const stderr = options.stderr ?? process.stderr
+  const stdin = options.stdin ?? process.stdin
+  const env = options.env ?? process.env
+
+  let args
+  try {
+    args = parseCliArgs(options.argv ?? process.argv.slice(2))
+  } catch (error) {
+    stderr.write(
+      `${error instanceof Error ? error.message : String(error)}\n\n${USAGE}\n`,
+    )
+    return EXIT.failed
+  }
+  if (args.help) {
+    stdout.write(`${USAGE}\n`)
+    return EXIT.ok
+  }
+
+  const host = createHarnessHost(
+    options.persistence ? { persistence: options.persistence } : {},
+  )
+  try {
+    if (args.acp) {
+      const { serveAcp } = await import('@tanstack/ai-acp/agent').catch(() => {
+        throw new Error(
+          '--acp needs @tanstack/ai-acp. Install it next to @tanstack/ai-harness-cli.',
+        )
+      })
+      const connection = serveAcp({ host, harness })
+      await connection.closed
+      return EXIT.ok
+    }
+
+    if (args.serve) {
+      const token = args.token ?? env.HARNESS_TOKEN ?? createToken()
+      const server = await serve({
+        host,
+        harness,
+        port: args.port,
+        hostname: args.hostname,
+        token,
+      })
+      stderr.write(`Serving ${harness.name} at ${server.url}\n`)
+      if (!args.token && !env.HARNESS_TOKEN) stderr.write(`Token: ${token}\n`)
+      await new Promise<void>((resolve) => {
+        process.once('SIGINT', resolve)
+        process.once('SIGTERM', resolve)
+      })
+      await server.close()
+      return EXIT.ok
+    }
+
+    const session = await host.open(harness, { threadId: args.thread })
+    if (args.print !== undefined) {
+      return await runPrint(session, args.print, {
+        output: args.output,
+        stdout,
+        stderr,
+      })
+    }
+    if (stdin.isTTY) {
+      // Loaded only here, so the other modes never load React or Ink.
+      const { runInteractive } = await import('./interactive')
+      await runInteractive(session, harness)
+    } else {
+      await runLines(session, stdin, stdout)
+    }
+    return EXIT.ok
+  } catch (error) {
+    stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    return EXIT.failed
+  } finally {
+    await host.close()
+  }
+}
+
+export { parseCliArgs, USAGE } from './args'
+export type { CliArgs } from './args'
+export { EXIT } from './print'
diff --git a/packages/ai-harness-cli/src/interactive.tsx b/packages/ai-harness-cli/src/interactive.tsx
new file mode 100644
index 0000000000..d05540ed51
--- /dev/null
+++ b/packages/ai-harness-cli/src/interactive.tsx
@@ -0,0 +1,170 @@
+import { useEffect, useState } from 'react'
+import { Box, Text, render, useApp, useInput } from 'ink'
+import { HARNESS_EVENTS } from '@tanstack/ai-harness'
+import { EventType } from '@tanstack/ai'
+import { handleLine } from './commands'
+import { applyEvent, approvalQuestion, resolveAll } from './session-view'
+import type {
+  AnyHarness,
+  HarnessSession,
+  SessionSnapshot,
+} from '@tanstack/ai-harness'
+import type { ViewEntry } from './session-view'
+
+const MAX_ENTRIES = 200
+
+function Entry({ entry }: { entry: ViewEntry }) {
+  switch (entry.kind) {
+    case 'user':
+      return <Text color="cyan">{`> ${entry.text}`}</Text>
+    case 'assistant':
+      return <Text>{entry.text}</Text>
+    case 'tool':
+      return <Text color="yellow">{`  - ${entry.text}`}</Text>
+    case 'notice':
+      return <Text color="gray">{entry.text}</Text>
+  }
+}
+
+function App({
+  session,
+  harness,
+}: {
+  session: HarnessSession
+  harness: AnyHarness
+}) {
+  const { exit } = useApp()
+  const [entries, setEntries] = useState<Array<ViewEntry>>([
+    { kind: 'notice', text: `${harness.name}. Type /help for commands.` },
+  ])
+  const [input, setInput] = useState('')
+  const [snapshot, setSnapshot] = useState<SessionSnapshot>(() =>
+    session.snapshot(),
+  )
+
+  useEffect(() => {
+    const reader = new AbortController()
+    void (async () => {
+      for await (const entry of session.events({
+        from: session.snapshot().cursor,
+        signal: reader.signal,
+      })) {
+        setEntries((current) => applyEvent(current, entry).slice(-MAX_ENTRIES))
+        const event = entry.event
+        if (
+          event.type === EventType.CUSTOM &&
+          (event.name === HARNESS_EVENTS.operationStarted ||
+            event.name === HARNESS_EVENTS.operationFinished)
+        ) {
+          // Let the operation settle before reading the status.
+          setTimeout(() => setSnapshot(session.snapshot()), 0)
+        }
+      }
+    })()
+    return () => reader.abort()
+  }, [session])
+
+  const notice = (text: string) =>
+    setEntries((current) =>
+      [...current, { kind: 'notice' as const, text }].slice(-MAX_ENTRIES),
+    )
+
+  const submit = async (line: string) => {
+    const current = session.snapshot()
+    if (current.status === 'requires_action') {
+      const approved = /^y(es)?$/i.test(line.trim())
+      await resolveAll(session, current.pendingInterrupts, approved)
+      notice(approved ? 'Approved.' : 'Rejected.')
+      return
+    }
+    if (line.trim() !== '' && !line.trim().startsWith('/')) {
+      setEntries((list) =>
+        [...list, { kind: 'user' as const, text: line.trim() }].slice(
+          -MAX_ENTRIES,
+        ),
+      )
+    }
+    const result = await handleLine(session, line)
+    if (result.type === 'exit') exit()
+    else if (result.type === 'notice' && result.text) notice(result.text)
+    setSnapshot(session.snapshot())
+  }
+
+  useInput((character, key) => {
+    if (key.escape) {
+      void session.cancel().then(() => setSnapshot(session.snapshot()))
+      return
+    }
+    if (key.return) {
+      const line = input
+      setInput('')
+      void submit(line)
+      return
+    }
+    if (key.backspace || key.delete) {
+      setInput((current) => current.slice(0, -1))
+      return
+    }
+    if (key.ctrl || key.meta || !character) return
+    // A paste (or fast typing) can arrive as one chunk with line breaks in it.
+    const [first = '', ...rest] = character.split(/\r\n|\r|\n/)
+    if (rest.length === 0) {
+      setInput((current) => current + first)
+      return
+    }
+    const lines = [input + first, ...rest.slice(0, -1)]
+    setInput(rest.at(-1) ?? '')
+    void (async () => {
+      for (const line of lines) await submit(line)
+    })()
+  })
+
+  const status =
+    snapshot.status === 'running'
+      ? 'working (Esc to cancel, Enter steers)'
+      : snapshot.status === 'requires_action'
+        ? approvalQuestion(snapshot.pendingInterrupts)
+        : 'ready'
+  const background = snapshot.activeOperations.filter(
+    (operation) => operation.kind === 'agent',
+  )
+
+  return (
+    <Box flexDirection="column">
+      {entries.map((entry, index) => (
+        <Entry key={index} entry={entry} />
+      ))}
+      <Box marginTop={1}>
+        <Text
+          color={snapshot.status === 'requires_action' ? 'magenta' : 'gray'}
+        >
+          {status}
+          {background.length > 0
+            ? ` | agents: ${background.map((operation) => operation.agent).join(', ')}`
+            : ''}
+          {snapshot.queuedTurns > 0 ? ` | queued: ${snapshot.queuedTurns}` : ''}
+        </Text>
+      </Box>
+      <Text>
+        <Text color="cyan">{'> '}</Text>
+        {input}
+        <Text inverse> </Text>
+      </Text>
+    </Box>
+  )
+}
+
+/** Start the interactive UI. Resolves when the user quits. */
+export async function runInteractive(
+  session: HarnessSession,
+  harness: AnyHarness,
+  streams: {
+    stdin?: NodeJS.ReadStream
+    stdout?: NodeJS.WriteStream
+    /** Route `console` output above the UI. Default true. */
+    patchConsole?: boolean
+  } = {},
+): Promise<void> {
+  const instance = render(<App session={session} harness={harness} />, streams)
+  await instance.waitUntilExit()
+}
diff --git a/packages/ai-harness-cli/src/lines.ts b/packages/ai-harness-cli/src/lines.ts
new file mode 100644
index 0000000000..c16ff9e0ba
--- /dev/null
+++ b/packages/ai-harness-cli/src/lines.ts
@@ -0,0 +1,80 @@
+import { createInterface } from 'node:readline'
+import { handleLine } from './commands'
+import {
+  applyEvent,
+  approvalQuestion,
+  resolveAll,
+  waitIdle,
+} from './session-view'
+import type { HarnessSession } from '@tanstack/ai-harness'
+import type { ViewEntry } from './session-view'
+
+interface Output {
+  write: (text: string) => unknown
+}
+
+/**
+ * The line mode, for piped input: one message or command per line. Each
+ * line waits for the turn it started. When a turn stops for approval, the
+ * next line answers it (`y` approves, anything else rejects).
+ */
+export async function runLines(
+  session: HarnessSession,
+  input: NodeJS.ReadableStream,
+  stdout: Output,
+): Promise<void> {
+  const reader = new AbortController()
+  let entries: Array<ViewEntry> = []
+  let printed = 0
+  const printing = (async () => {
+    for await (const entry of session.events({
+      from: session.snapshot().cursor,
+      signal: reader.signal,
+    })) {
+      const next = applyEvent(entries, entry)
+      const last = next.at(-1)
+      if (next === entries || !last) continue
+      // Print the growth of the last assistant entry, or each new entry.
+      const previous = entries.at(-1)
+      if (
+        last.kind === 'assistant' &&
+        previous?.kind === 'assistant' &&
+        previous.operationId === last.operationId
+      ) {
+        stdout.write(last.text.slice(previous.text.length))
+      } else {
+        if (printed > 0) stdout.write('\n')
+        stdout.write(last.kind === 'assistant' ? last.text : `[${last.text}]`)
+      }
+      printed += 1
+      entries = next
+    }
+  })()
+
+  const lines = createInterface({ input, crlfDelay: Infinity })
+  for await (const line of lines) {
+    const snapshot = session.snapshot()
+    if (snapshot.status === 'requires_action') {
+      await resolveAll(
+        session,
+        snapshot.pendingInterrupts,
+        /^y(es)?$/i.test(line.trim()),
+      )
+    } else {
+      const result = await handleLine(session, line)
+      if (result.type === 'exit') break
+      if (result.type === 'notice' && result.text)
+        stdout.write(`${result.text}\n`)
+    }
+    await waitIdle(session)
+    const after = session.snapshot()
+    if (after.status === 'requires_action') {
+      stdout.write(`\n${approvalQuestion(after.pendingInterrupts)}\n`)
+    }
+  }
+  lines.close()
+  await waitIdle(session)
+  reader.abort()
+  await printing
+  if (printed > 0) stdout.write('\n')
+}
diff --git a/packages/ai-harness-cli/src/print.ts b/packages/ai-harness-cli/src/print.ts
new file mode 100644
index 0000000000..757c278d94
--- /dev/null
+++ b/packages/ai-harness-cli/src/print.ts
@@ -0,0 +1,54 @@
+import { EventType } from '@tanstack/ai'
+import type { HarnessSession } from '@tanstack/ai-harness'
+
+export const EXIT = {
+  ok: 0,
+  failed: 1,
+  needsAction: 2,
+  cancelled: 130,
+} as const
+
+interface Output {
+  write: (text: string) => unknown
+}
+
+/**
+ * Run one prompt and print it. `text` prints the answer as it streams.
+ * `ndjson` prints every AG-UI event as one JSON line.
+ */
+export async function runPrint(
+  session: HarnessSession,
+  prompt: string,
+  options: { output: 'text' | 'ndjson'; stdout: Output; stderr: Output },
+): Promise<number> {
+  const { stdout, stderr } = options
+  const operation = session.prompt(prompt)
+  for await (const chunk of operation.stream()) {
+    if (options.output === 'ndjson') {
+      stdout.write(`${JSON.stringify(chunk)}\n`)
+    } else if (
+      chunk.type === EventType.TEXT_MESSAGE_CONTENT &&
+      !('subagentRunId' in chunk && chunk.subagentRunId)
+    ) {
+      stdout.write(chunk.delta)
+    }
+  }
+  const failure: unknown = await operation.then(
+    () => undefined,
+    (error: unknown) => error,
+  )
+  if (options.output === 'text') stdout.write('\n')
+  const status = operation.status()
+  if (status === 'completed') return EXIT.ok
+  if (status === 'interrupted') {
+    stderr.write(
+      'The turn stopped for an approval. Run the interactive mode to answer it.\n',
+    )
+    return EXIT.needsAction
+  }
+  if (status === 'cancelled') return EXIT.cancelled
+  stderr.write(
+    `The turn failed: ${failure instanceof Error ? failure.message : String(failure)}\n`,
+  )
+  return EXIT.failed
+}
diff --git a/packages/ai-harness-cli/src/serve.ts b/packages/ai-harness-cli/src/serve.ts
new file mode 100644
index 0000000000..71bd801804
--- /dev/null
+++ b/packages/ai-harness-cli/src/serve.ts
@@ -0,0 +1,113 @@
+import { createServer } from 'node:http'
+import { Readable } from 'node:stream'
+import { randomBytes, timingSafeEqual } from 'node:crypto'
+import { createHarnessHandler } from '@tanstack/ai-harness'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { ReadableStream as NodeReadableStream } from 'node:stream/web'
+import type { AnyHarness, HarnessHost } from '@tanstack/ai-harness'
+
+export interface ServeOptions {
+  host: HarnessHost
+  harness: AnyHarness
+  port: number
+  hostname: string
+  /** Every request must send `Authorization: Bearer <token>`. */
+  token: string
+}
+
+/** A random token for `--serve` when none is given. */
+export function createToken(): string {
+  return randomBytes(24).toString('base64url')
+}
+
+function sameToken(given: string | null, expected: string): boolean {
+  if (!given?.startsWith('Bearer ')) return false
+  const a = Buffer.from(given.slice(7))
+  const b = Buffer.from(expected)
+  return a.length === b.length && timingSafeEqual(a, b)
+}
+
+async function toRequest(
+  req: IncomingMessage,
+  base: string,
+  signal: AbortSignal,
+): Promise<Request> {
+  const headers = new Headers()
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (typeof value === 'string') headers.set(key, value)
+    else if (Array.isArray(value)) headers.set(key, value.join(', '))
+  }
+  const hasBody = req.method !== 'GET' && req.method !== 'HEAD'
+  const chunks: Array<Buffer> = []
+  if (hasBody) for await (const chunk of req) chunks.push(Buffer.from(chunk))
+  return new Request(new URL(req.url ?? '/', base), {
+    method: req.method ?? 'GET',
+    headers,
+    signal,
+    ...(hasBody ? { body: Buffer.concat(chunks) } : {}),
+  })
+}
+
+async function send(res: ServerResponse, response: Response): Promise<void> {
+  res.writeHead(response.status, Object.fromEntries(response.headers))
+  if (!response.body) {
+    res.end()
+    return
+  }
+  // `Readable.fromWeb` takes the stream type from node:stream/web.
+  Readable.fromWeb(response.body as NodeReadableStream).pipe(res)
+}
+
+/**
+ * Serve the harness session protocol over HTTP (capabilities, run, events,
+ * control, snapshot). Every request needs the bearer token.
+ */
+export function serve(
+  options: ServeOptions,
+): Promise<{ url: string; close: () => Promise<void> }> {
+  const handler = createHarnessHandler({
+    host: options.host,
+    harness: options.harness,
+    authorize: (request) =>
+      sameToken(request.headers.get('authorization'), options.token)
+        ? { id: 'cli' }
+        : null,
+  })
+  const server = createServer((req, res) => {
+    const aborter = new AbortController()
+    res.on('close', () => aborter.abort())
+    void (async () => {
+      try {
+        const base = `http://${req.headers.host ?? `${options.hostname}:${options.port}`}`
+        await send(
+          res,
+          await handler(await toRequest(req, base, aborter.signal)),
+        )
+      } catch (error) {
+        if (!res.headersSent)
+          res.writeHead(500, { 'Content-Type': 'application/json' })
+        res.end(
+          JSON.stringify({
+            error: error instanceof Error ? error.message : String(error),
+          }),
+        )
+      }
+    })()
+  })
+  return new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(options.port, options.hostname, () => {
+      const address = server.address()
+      const port =
+        typeof address === 'object' && address ? address.port : options.port
+      resolve({
+        url: `http://${options.hostname}:${port}`,
+        close: () =>
+          new Promise<void>((done) => {
+            server.closeAllConnections()
+            server.close(() => done())
+          }),
+      })
+    })
+  })
+}
diff --git a/packages/ai-harness-cli/src/session-view.ts b/packages/ai-harness-cli/src/session-view.ts
new file mode 100644
index 0000000000..24325f072d
--- /dev/null
+++ b/packages/ai-harness-cli/src/session-view.ts
@@ -0,0 +1,96 @@
+import { EventType } from '@tanstack/ai'
+import { HARNESS_EVENTS } from '@tanstack/ai-harness'
+import type { Interrupt, RunAgentResumeItem } from '@tanstack/ai'
+import type { HarnessSession, SessionEvent } from '@tanstack/ai-harness'
+
+/** One line in the transcript view. */
+export type ViewEntry =
+  | { kind: 'user'; text: string }
+  | { kind: 'assistant'; operationId: string; text: string }
+  | { kind: 'tool'; text: string }
+  | { kind: 'notice'; text: string }
+
+/**
+ * Fold one session event into the view entries. Returns the new list, or the
+ * same list when the event changes nothing on screen.
+ */
+export function applyEvent(
+  entries: Array<ViewEntry>,
+  entry: SessionEvent,
+): Array<ViewEntry> {
+  const { event, operationId } = entry
+  if ('subagentRunId' in event && event.subagentRunId) {
+    if (event.type === EventType.SUBAGENT_STARTED) {
+      return [
+        ...entries,
+        { kind: 'tool', text: `agent ${event.name ?? ''} started` },
+      ]
+    }
+    return entries
+  }
+  if (event.type === EventType.TEXT_MESSAGE_CONTENT) {
+    const last = entries.at(-1)
+    if (last?.kind === 'assistant' && last.operationId === operationId) {
+      return [
+        ...entries.slice(0, -1),
+        { ...last, text: last.text + event.delta },
+      ]
+    }
+    return [...entries, { kind: 'assistant', operationId, text: event.delta }]
+  }
+  if (event.type === EventType.TOOL_CALL_START) {
+    return [...entries, { kind: 'tool', text: `tool ${event.toolCallName}` }]
+  }
+  if (event.type === EventType.RUN_ERROR) {
+    return [...entries, { kind: 'notice', text: `Error: ${event.message}` }]
+  }
+  if (
+    event.type === EventType.CUSTOM &&
+    event.name === HARNESS_EVENTS.operationResumed
+  ) {
+    return [
+      ...entries,
+      { kind: 'notice', text: 'Resumed a turn that a crash stopped.' },
+    ]
+  }
+  return entries
+}
+
+/** Answer every open interrupt of the last turn with one decision. */
+export function resolveAll(
+  session: HarnessSession,
+  interrupts: ReadonlyArray<Interrupt>,
+  approved: boolean,
+) {
+  const resume: Array<RunAgentResumeItem> = interrupts.map((interrupt) => ({
+    interruptId: interrupt.id,
+    status: 'resolved',
+    payload: approved,
+  }))
+  return session.resolve(resume)
+}
+
+/** A short question for the open interrupts. */
+export function approvalQuestion(interrupts: ReadonlyArray<Interrupt>): string {
+  const names = interrupts.map(
+    (interrupt) => interrupt.message ?? interrupt.toolCallId ?? interrupt.id,
+  )
+  return `Approve ${names.join(', ')}? [y/n]`
+}
+
+/** Resolves when no chat turn runs or waits in the queue. */
+export async function waitIdle(session: HarnessSession): Promise<void> {
+  while (true) {
+    const snapshot = session.snapshot()
+    const chatActive = snapshot.activeOperations.some(
+      (operation) => operation.kind === 'chat',
+    )
+    if (
+      snapshot.status !== 'running' &&
+      !chatActive &&
+      snapshot.queuedTurns === 0
+    )
+      return
+    await new Promise((resolve) => setTimeout(resolve, 20))
+  }
+}
diff --git a/packages/ai-harness-cli/tests/cli.test.ts b/packages/ai-harness-cli/tests/cli.test.ts
new file mode 100644
index 0000000000..645e5b9537
--- /dev/null
+++ b/packages/ai-harness-cli/tests/cli.test.ts
@@ -0,0 +1,265 @@
+import { Readable } from 'node:stream'
+import { describe, expect, it, vi } from 'vitest'
+import { EventType, defineAgent, toolDefinition } from '@tanstack/ai'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { EXIT, parseCliArgs, runCli } from '../src'
+import { serve } from '../src/serve'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+
+const now = () => Date.now()
+const textTurn = (text: string): Array<StreamChunk> => [
+  { type: EventType.RUN_STARTED, runId: 'r', threadId: 't', timestamp: now() },
+  {
+    type: EventType.TEXT_MESSAGE_START,
+    messageId: 'm',
+    role: 'assistant',
+    timestamp: now(),
+  },
+  {
+    type: EventType.TEXT_MESSAGE_CONTENT,
+    messageId: 'm',
+    delta: text,
+    timestamp: now(),
+  },
+  { type: EventType.TEXT_MESSAGE_END, messageId: 'm', timestamp: now() },
+  {
+    type: EventType.RUN_FINISHED,
+    runId: 'r',
+    threadId: 't',
+    timestamp: now(),
+    metadata: { tanstack: { finishReason: 'stop' } },
+  },
+]
+const toolTurn = (name: string, args: string): Array<StreamChunk> => [
+  { type: EventType.RUN_STARTED, runId: 'r', threadId: 't', timestamp: now() },
+  {
+    type: EventType.TOOL_CALL_START,
+    toolCallId: 'call_1',
+    toolCallName: name,
+    timestamp: now(),
+  },
+  {
+    type: EventType.TOOL_CALL_ARGS,
+    toolCallId: 'call_1',
+    delta: args,
+    timestamp: now(),
+  },
+  { type: EventType.TOOL_CALL_END, toolCallId: 'call_1', timestamp: now() },
+  {
+    type: EventType.RUN_FINISHED,
+    runId: 'r',
+    threadId: 't',
+    timestamp: now(),
+    metadata: { tanstack: { finishReason: 'tool_calls' } },
+  },
+]
+
+function scripted(turns: Array<Array<StreamChunk>>) {
+  let call = 0
+  const seen: Array<Array<{ role: string; content: unknown }>> = []
+  const adapter: AnyTextAdapter = {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    '~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,
+    },
+    chatStream: (options) => {
+      seen.push(options.messages)
+      const chunks = turns[call] ?? textTurn('')
+      call += 1
+      return (async function* () {
+        yield* chunks
+      })()
+    },
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+  }
+  return { adapter, seen }
+}
+
+function capture() {
+  let text = ''
+  return {
+    write: (chunk: string) => (text += chunk),
+    get text() {
+      return text
+    },
+  }
+}
+
+describe('parseCliArgs', () => {
+  it('reads flags and rejects bad values', () => {
+    expect(parseCliArgs(['-p', 'hi', '--output', 'ndjson'])).toMatchObject({
+      print: 'hi',
+      output: 'ndjson',
+      thread: 'main',
+    })
+    expect(() => parseCliArgs(['--output', 'xml'])).toThrow('--output')
+    expect(() => parseCliArgs(['--nope'])).toThrow()
+  })
+})
+
+describe('print mode', () => {
+  it('prints the answer and exits 0', async () => {
+    const { adapter } = scripted([textTurn('Hello from the harness.')])
+    const stdout = capture()
+    const code = await runCli(defineHarness({ name: 'test/print', adapter }), {
+      argv: ['-p', 'hi'],
+      stdout,
+      stderr: capture(),
+      persistence: memoryPersistence(),
+    })
+    expect(code).toBe(EXIT.ok)
+    expect(stdout.text).toBe('Hello from the harness.\n')
+  })
+
+  it('prints NDJSON AG-UI events', async () => {
+    const { adapter } = scripted([textTurn('x')])
+    const stdout = capture()
+    await runCli(defineHarness({ name: 'test/ndjson', adapter }), {
+      argv: ['-p', 'hi', '--output', 'ndjson'],
+      stdout,
+      stderr: capture(),
+      persistence: memoryPersistence(),
+    })
+    const events = stdout.text
+      .trim()
+      .split('\n')
+      .map((line) => JSON.parse(line))
+    expect(events.map((event) => event.type)).toContain('TEXT_MESSAGE_CONTENT')
+    expect(events.at(-1).name).toBe('harness.operation.finished')
+  })
+
+  it('exits 2 when the turn waits for an approval', async () => {
+    const { adapter } = scripted([toolTurn('remove', '{}')])
+    const stderr = capture()
+    const code = await runCli(
+      defineHarness({
+        name: 'test/approval',
+        adapter,
+        tools: [
+          toolDefinition({
+            name: 'remove',
+            description: 'Remove',
+            needsApproval: true,
+          }).server(async () => 'ok'),
+        ],
+      }),
+      {
+        argv: ['-p', 'remove it'],
+        stdout: capture(),
+        stderr,
+        persistence: memoryPersistence(),
+      },
+    )
+    expect(code).toBe(EXIT.needsAction)
+    expect(stderr.text).toContain('approval')
+  })
+})
+
+describe('line mode', () => {
+  it('runs piped lines as turns, answers approvals, and runs commands', async () => {
+    const remove = vi.fn(async () => 'removed')
+    const pricer = defineAgent({
+      name: 'pricer',
+      description: 'Prices a vendor',
+      run: async () => 'twelve dollars',
+    })
+    const { adapter } = scripted([
+      textTurn('First answer.'),
+      toolTurn('remove', '{}'),
+      textTurn('Done removing.'),
+    ])
+    const stdout = capture()
+    const input = Readable.from([
+      'hello\n',
+      'remove the file\n',
+      'y\n',
+      '/agents\n',
+      '/exit\n',
+    ])
+    const code = await runCli(
+      defineHarness({
+        name: 'test/lines',
+        adapter,
+        agents: [pricer],
+        tools: [
+          toolDefinition({
+            name: 'remove',
+            description: 'Remove',
+            needsApproval: true,
+          }).server(remove),
+        ],
+      }),
+      {
+        argv: [],
+        stdin: Object.assign(input, {
+          isTTY: false,
+        }) as unknown as NodeJS.ReadStream,
+        stdout,
+        stderr: capture(),
+        persistence: memoryPersistence(),
+      },
+    )
+    expect(code).toBe(EXIT.ok)
+    expect(remove).toHaveBeenCalledTimes(1)
+    expect(stdout.text).toContain('First answer.')
+    expect(stdout.text).toContain('[y/n]')
+    expect(stdout.text).toContain('Done removing.')
+    expect(stdout.text).toContain('pricer: Prices a vendor')
+  })
+})
+
+describe('serve mode', () => {
+  it('serves the session protocol and requires the token', async () => {
+    const { adapter } = scripted([textTurn('served')])
+    const harness = defineHarness({ name: 'test/serve', adapter })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const server = await serve({
+      host,
+      harness,
+      port: 0,
+      hostname: '127.0.0.1',
+      token: 'secret',
+    })
+    try {
+      const denied = await fetch(`${server.url}/capabilities`)
+      expect(denied.status).toBe(401)
+      const wrong = await fetch(`${server.url}/capabilities`, {
+        headers: { authorization: 'Bearer nope' },
+      })
+      expect(wrong.status).toBe(401)
+      const capabilities = await fetch(`${server.url}/capabilities`, {
+        headers: { authorization: 'Bearer secret' },
+      })
+      expect((await capabilities.json()).identity.name).toBe('test/serve')
+      const receipt = await fetch(`${server.url}/control`, {
+        method: 'POST',
+        headers: {
+          authorization: 'Bearer secret',
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify({
+          threadId: 't',
+          input: { op: 'prompt', message: 'hi' },
+        }),
+      })
+      expect((await receipt.json()).status).toBe('accepted')
+    } finally {
+      await server.close()
+      await host.close()
+    }
+  })
+})
diff --git a/packages/ai-harness-cli/tests/interactive.test.ts b/packages/ai-harness-cli/tests/interactive.test.ts
new file mode 100644
index 0000000000..9eaeb2845b
--- /dev/null
+++ b/packages/ai-harness-cli/tests/interactive.test.ts
@@ -0,0 +1,106 @@
+import { PassThrough } from 'node:stream'
+import { describe, expect, it } from 'vitest'
+import { EventType } from '@tanstack/ai'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { runInteractive } from '../src/interactive'
+import type { AnyTextAdapter } from '@tanstack/ai'
+
+const now = () => Date.now()
+const adapter: AnyTextAdapter = {
+  kind: 'text',
+  name: 'mock',
+  model: 'test-model',
+  '~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,
+  },
+  chatStream: () =>
+    (async function* () {
+      yield {
+        type: EventType.RUN_STARTED,
+        runId: 'r',
+        threadId: 't',
+        timestamp: now(),
+      }
+      yield {
+        type: EventType.TEXT_MESSAGE_START,
+        messageId: 'm',
+        role: 'assistant',
+        timestamp: now(),
+      }
+      yield {
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'm',
+        delta: 'Hi from the Ink UI',
+        timestamp: now(),
+      }
+      yield {
+        type: EventType.TEXT_MESSAGE_END,
+        messageId: 'm',
+        timestamp: now(),
+      }
+      yield {
+        type: EventType.RUN_FINISHED,
+        runId: 'r',
+        threadId: 't',
+        timestamp: now(),
+        metadata: { tanstack: { finishReason: 'stop' } },
+      }
+    })(),
+  structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+}
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+describe('interactive UI', () => {
+  it('sends a typed line, shows the answer, and quits on /exit', async () => {
+    const harness = defineHarness({ name: 'test/ink', adapter })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(harness, { threadId: 'ink' })
+
+    const stdin = Object.assign(new PassThrough(), {
+      isTTY: true,
+      setRawMode: () => stdin,
+      ref: () => stdin,
+      unref: () => stdin,
+    })
+    let output = ''
+    const stdout = Object.assign(new PassThrough(), {
+      isTTY: true,
+      columns: 100,
+      rows: 30,
+    })
+    stdout.on('data', (data: Buffer) => {
+      output += data.toString()
+    })
+
+    const done = runInteractive(session, harness, {
+      stdin: stdin as unknown as NodeJS.ReadStream,
+      stdout: stdout as unknown as NodeJS.WriteStream,
+      // Vitest's console cannot be patched.
+      patchConsole: false,
+    })
+    await wait(100)
+    // One chunk with a line break, the way a paste arrives.
+    stdin.write('hello\r')
+    await wait(300)
+    stdin.write('/exit\r')
+    await done
+
+    const plain = output.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '')
+    expect(plain).toContain('> hello')
+    expect(plain).toContain('Hi from the Ink UI')
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness-cli/tsconfig.json b/packages/ai-harness-cli/tsconfig.json
new file mode 100644
index 0000000000..b9045b913b
--- /dev/null
+++ b/packages/ai-harness-cli/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "jsx": "react-jsx"
+  },
+  "include": ["vite.config.ts", "./src", "./tests"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/ai-harness-cli/vite.config.ts b/packages/ai-harness-cli/vite.config.ts
new file mode 100644
index 0000000000..be372645e8
--- /dev/null
+++ b/packages/ai-harness-cli/vite.config.ts
@@ -0,0 +1,35 @@
+import { defineConfig, mergeConfig } from 'vitest/config'
+import { tanstackViteConfig } from '@tanstack/vite-config'
+import packageJson from './package.json'
+
+const config = defineConfig({
+  test: {
+    name: packageJson.name,
+    dir: './',
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'lcov'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        'tests/',
+        '**/*.test.ts',
+        '**/*.config.ts',
+      ],
+      include: ['src/**/*.{ts,tsx}'],
+    },
+  },
+})
+
+export default mergeConfig(
+  config,
+  tanstackViteConfig({
+    entry: ['./src/index.ts'],
+    srcDir: './src',
+    cjs: false,
+  }),
+)
diff --git a/packages/ai-harness/package.json b/packages/ai-harness/package.json
index 5d45fa9b9d..fd59be8e31 100644
--- a/packages/ai-harness/package.json
+++ b/packages/ai-harness/package.json
@@ -29,6 +29,10 @@
     ".": {
       "types": "./dist/esm/index.d.ts",
       "import": "./dist/esm/index.js"
+    },
+    "./client": {
+      "types": "./dist/esm/client.d.ts",
+      "import": "./dist/esm/client.js"
     }
   },
   "scripts": {
diff --git a/packages/ai-harness/src/client.ts b/packages/ai-harness/src/client.ts
new file mode 100644
index 0000000000..cd7f6d055d
--- /dev/null
+++ b/packages/ai-harness/src/client.ts
@@ -0,0 +1,198 @@
+// Browser-safe: this module has type-only imports from the rest of the
+// package, so no server code (adapters, stores, secrets) reaches a client.
+import type { RunAgentResumeItem } from '@tanstack/ai'
+import type { AgentInputOf } from './agents'
+import type { AnyHarness, HarnessAgentsOf } from './define'
+import type { SessionSnapshot } from './session'
+import type {
+  BusyPolicy,
+  Cursor,
+  HarnessInput,
+  Receipt,
+  SessionEvent,
+  UserInput,
+} from './types'
+
+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> {
+  prompt: (
+    message: UserInput,
+    options?: { busy?: BusyPolicy },
+  ) => Promise<Receipt>
+  steer: (message: UserInput) => Promise<Receipt>
+  followUp: (message: UserInput) => Promise<Receipt>
+  resolve: (resume: Array<RunAgentResumeItem>) => Promise<Receipt>
+  cancel: (operationId?: string) => Promise<Receipt>
+  agents: ClientAgentHandles<THarness>
+  /**
+   * The session events from `from` (exclusive). Reconnects after a network
+   * error and resumes from the last cursor. Ends when `signal` aborts.
+   */
+  events: (options?: {
+    from?: Cursor
+    signal?: AbortSignal
+  }) => AsyncIterable<SessionEvent>
+  snapshot: () => Promise<SessionSnapshot>
+}
+
+/**
+ * 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 ?? {})
+
+  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 response.json()
+    if (!response.ok) {
+      const message =
+        typeof body === 'object' && body !== null && 'error' in body
+          ? String(body.error)
+          : response.statusText
+      throw new Error(`Harness request failed (${response.status}): ${message}`)
+    }
+    // The handler answers /control with a Receipt.
+    return body as Receipt
+  }
+
+  async function* events(
+    eventOptions: { from?: Cursor; signal?: AbortSignal } = {},
+  ) {
+    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})`)
+        }
+        const reader = response.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 = ''
+        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
+            const frame: unknown = JSON.parse(data)
+            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
+      await new Promise((resolve) =>
+        setTimeout(resolve, options.reconnectDelayMs ?? 1000),
+      )
+    }
+  }
+
+  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 } : {}),
+      }),
+    steer: (message) => send({ op: 'steer', message }),
+    followUp: (message) => send({ op: 'followUp', message }),
+    resolve: (resume) => send({ op: 'resolve', resume }),
+    cancel: (operationId) =>
+      send({ op: 'cancel', ...(operationId ? { operationId } : {}) }),
+    agents,
+    events,
+    snapshot: async () => {
+      const query = new URLSearchParams({ threadId: options.threadId })
+      const response = await doFetch(`${base}/snapshot?${query}`, {
+        headers: headers(),
+      })
+      if (!response.ok)
+        throw new Error(`Harness snapshot failed (${response.status})`)
+      // The handler answers /snapshot with a SessionSnapshot.
+      return (await response.json()) as SessionSnapshot
+    },
+  }
+}
diff --git a/packages/ai-harness/src/harness-text.ts b/packages/ai-harness/src/harness-text.ts
new file mode 100644
index 0000000000..51b0aa7a21
--- /dev/null
+++ b/packages/ai-harness/src/harness-text.ts
@@ -0,0 +1,133 @@
+import { EventType } from '@tanstack/ai'
+import { createHarnessHost } from './host'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import type { AnyHarness } from './define'
+import type { HarnessHost } from './host'
+
+export interface HarnessTextOptions {
+  /** The host that runs the inner sessions. Default: a memory host. */
+  host?: HarnessHost
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null
+
+function lastUserText(messages: unknown): string {
+  const list: ReadonlyArray<unknown> = Array.isArray(messages) ? messages : []
+  const message = list.findLast(
+    (entry) => isRecord(entry) && entry.role === 'user',
+  )
+  if (!isRecord(message)) return ''
+  if (typeof message.content === 'string') return message.content
+  const parts: ReadonlyArray<unknown> = Array.isArray(message.content)
+    ? message.content
+    : []
+  return parts
+    .map((part) =>
+      isRecord(part) && part.type === 'text' && typeof part.content === 'string'
+        ? part.content
+        : '',
+    )
+    .join('')
+}
+
+/** Events of the inner turn that the outer chat shows as its own model output. */
+const FORWARDED = new Set<string>([
+  EventType.TEXT_MESSAGE_START,
+  EventType.TEXT_MESSAGE_CONTENT,
+  EventType.TEXT_MESSAGE_END,
+  EventType.REASONING_START,
+  EventType.REASONING_MESSAGE_START,
+  EventType.REASONING_MESSAGE_CONTENT,
+  EventType.REASONING_MESSAGE_END,
+  EventType.REASONING_END,
+])
+
+/**
+ * Use a harness as the model of a `chat()` call, the way you would call a
+ * coding agent. Each outer thread gets its own inner session, which keeps
+ * its own transcript, tools, plugins, and agents. The outer chat sees the
+ * inner turn's text and reasoning.
+ *
+ * @example
+ * ```ts
+ * const stream = chat({ adapter: harnessText(studio), messages, threadId })
+ * ```
+ */
+export function harnessText(
+  harness: AnyHarness,
+  options: HarnessTextOptions = {},
+): AnyTextAdapter {
+  let host = options.host
+  return {
+    kind: 'text',
+    name: 'harness',
+    model: harness.name,
+    '~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,
+    },
+    chatStream: (chatOptions) =>
+      (async function* (): AsyncGenerator<StreamChunk> {
+        host ??= createHarnessHost()
+        const threadId = `${chatOptions.threadId ?? 'default'}:${harness.name}`
+        const runId = chatOptions.runId ?? `harness-${Date.now().toString(36)}`
+        const signal =
+          isRecord(chatOptions.request) &&
+          chatOptions.request.signal instanceof AbortSignal
+            ? chatOptions.request.signal
+            : undefined
+        const session = await host.open(harness, { threadId })
+        const operation = session.prompt(lastUserText(chatOptions.messages))
+        signal?.addEventListener('abort', () => void operation.cancel(), {
+          once: true,
+        })
+
+        yield {
+          type: EventType.RUN_STARTED,
+          runId,
+          threadId,
+          timestamp: Date.now(),
+        }
+        let failed: string | undefined
+        for await (const chunk of operation.stream()) {
+          if (
+            FORWARDED.has(chunk.type) &&
+            !('subagentRunId' in chunk && chunk.subagentRunId)
+          ) {
+            yield chunk
+          }
+          if (chunk.type === EventType.RUN_ERROR) failed = chunk.message
+        }
+        if (failed !== undefined) {
+          yield {
+            type: EventType.RUN_ERROR,
+            message: failed,
+            timestamp: Date.now(),
+          }
+          return
+        }
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId,
+          threadId,
+          timestamp: Date.now(),
+          metadata: { tanstack: { finishReason: 'stop' } },
+        }
+      })(),
+    structuredOutput: () =>
+      Promise.reject(
+        new Error('harnessText does not support structured output.'),
+      ),
+  }
+}
diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
index dda6dd628e..dd8dafb6c7 100644
--- a/packages/ai-harness/src/host.ts
+++ b/packages/ai-harness/src/host.ts
@@ -69,6 +69,7 @@ export function createHarnessHost(
   // to keep accepted inputs across restarts.
   const inbox = persistence.stores.inbox ?? memoryPersistence().stores.inbox
   const sessions = new Map<string, Promise<HarnessSession>>()
+  const hostId = `host-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`
 
   return {
     open(harness, { threadId, principal }) {
@@ -80,6 +81,7 @@ export function createHarnessHost(
           threadId,
           persistence,
           inbox,
+          hostId,
           ...(principal ? { principal } : {}),
           onClose: () => sessions.delete(key),
         })
diff --git a/packages/ai-harness/src/http.ts b/packages/ai-harness/src/http.ts
new file mode 100644
index 0000000000..e9be9a5e24
--- /dev/null
+++ b/packages/ai-harness/src/http.ts
@@ -0,0 +1,308 @@
+import {
+  EventType,
+  chatParamsFromRequestBody,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import {
+  HARNESS_PROTOCOL_VERSION,
+  applyInput,
+  capabilitiesOf,
+  parseControlFrame,
+  parseHarnessInput,
+} from './protocol'
+import type { StreamChunk, WebSocketLike } from '@tanstack/ai'
+import type { AnyHarness } from './define'
+import type { HarnessHost } from './host'
+import type { HostFrame } from './protocol'
+import type { Principal } from './types'
+
+/**
+ * Decide who sends a request. Return `null` to refuse it with 401. Every
+ * endpoint calls it, so there is no unauthenticated route.
+ */
+export type Authorize = (
+  request: Request,
+) => Principal | null | Promise<Principal | null>
+
+export interface HarnessHandlerOptions {
+  host: HarnessHost
+  harness: AnyHarness
+  authorize: Authorize
+  /**
+   * May this principal use this thread? Default: yes. Use it to keep users
+   * out of each other's threads.
+   */
+  canAccess?: (
+    principal: Principal,
+    threadId: string,
+  ) => boolean | Promise<boolean>
+}
+
+const json = (body: unknown, status = 200) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  })
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null
+
+/** The text of the last user message of an AG-UI request. */
+function lastUserText(messages: ReadonlyArray<unknown>): string | undefined {
+  const message = messages.findLast(
+    (entry) => isRecord(entry) && entry.role === 'user',
+  )
+  if (!isRecord(message)) return undefined
+  if (typeof message.content === 'string') return message.content
+  const parts = Array.isArray(message.parts) ? message.parts : []
+  return parts
+    .map((part: unknown) =>
+      isRecord(part) && part.type === 'text' && typeof part.content === 'string'
+        ? part.content
+        : '',
+    )
+    .join('')
+}
+
+/**
+ * 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, streamed as SSE.
+ * - `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.
+ */
+export function createHarnessHandler(
+  options: HarnessHandlerOptions,
+): (request: Request) => Promise<Response> {
+  const { host, harness, authorize } = options
+  const canAccess = options.canAccess ?? (() => true)
+
+  const openFor = async (principal: Principal, threadId: string) => {
+    if (!(await canAccess(principal, threadId))) return null
+    return host.open(harness, { threadId, principal })
+  }
+
+  return async (request) => {
+    const principal = await authorize(request)
+    if (!principal) return json({ error: 'unauthorized' }, 401)
+    const url = new URL(request.url)
+    const route = url.pathname.split('/').at(-1)
+
+    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 = lastUserText(params.messages)
+        const session = await openFor(principal, params.threadId)
+        if (!session) return json({ error: 'forbidden' }, 403)
+        if (params.resume && params.resume.length > 0) {
+          const receipt = await session.resolve(params.resume)
+          if (receipt.status === 'rejected' || !receipt.operationId) {
+            return json({ error: receipt.reason ?? 'rejected' }, 409)
+          }
+          // Not `request.signal`: some servers abort it once the body is
+          // read. The response aborts this controller when the client leaves.
+          const reader = new AbortController()
+          const events = session.events({ signal: reader.signal })
+          return toServerSentEventsResponse(
+            followOperation(events, receipt.operationId),
+            {
+              abortController: reader,
+            },
+          )
+        }
+        if (message === undefined)
+          return json({ error: 'no user message' }, 400)
+        const operation = session.prompt(message)
+        const reader = new AbortController()
+        return toServerSentEventsResponse(
+          operation.stream({ signal: reader.signal }),
+          {
+            abortController: reader,
+          },
+        )
+      }
+
+      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
+        const encoder = new TextEncoder()
+        // Stops when the client cancels the response stream.
+        const reader = new AbortController()
+        const body = new ReadableStream<Uint8Array>({
+          cancel: () => reader.abort(),
+          async start(controller) {
+            try {
+              for await (const entry of session.events({
+                ...(from ? { from } : {}),
+                signal: reader.signal,
+              })) {
+                const frame: HostFrame = { type: 'harness.event', ...entry }
+                controller.enqueue(
+                  encoder.encode(
+                    `id: ${entry.cursor}\ndata: ${JSON.stringify(frame)}\n\n`,
+                  ),
+                )
+              }
+            } finally {
+              if (!reader.signal.aborted) controller.close()
+            }
+          },
+        })
+        return new Response(body, {
+          headers: {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+          },
+        })
+      }
+
+      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))
+      }
+
+      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())
+      }
+    } catch (error) {
+      return json(
+        { error: error instanceof Error ? error.message : String(error) },
+        400,
+      )
+    }
+    return json({ error: 'not found' }, 404)
+  }
+}
+
+/** Session events of one operation, until it finishes. */
+async function* followOperation(
+  events: AsyncIterable<{ operationId: string; event: StreamChunk }>,
+  operationId: string,
+) {
+  for await (const entry of events) {
+    if (entry.operationId !== operationId) continue
+    yield entry.event
+    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
+  canAccess?: (
+    principal: Principal,
+    threadId: string,
+  ) => boolean | Promise<boolean>
+}
+
+/**
+ * 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 } = options
+  const canAccess = options.canAccess ?? (() => true)
+  const reader = new AbortController()
+  let session: Awaited<ReturnType<HarnessHost['open']>> | 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 (session) throw new Error('Already subscribed.')
+          if (!(await canAccess(principal, frame.threadId))) {
+            send({ type: 'harness.error', message: 'forbidden' })
+            socket.close(4403, 'forbidden')
+            return
+          }
+          session = await host.open(harness, {
+            threadId: frame.threadId,
+            principal,
+          })
+          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 })
+          })()
+          return
+        }
+        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)
+        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 ac889765b3..e1de83cca8 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -38,6 +38,7 @@ export type {
   AgentHandles,
   AgentRunOptions,
   AgentStartOptions,
+  DynamicAgentHandle,
   SessionSnapshot,
 } from './session'
 
@@ -55,3 +56,22 @@ export type {
   SessionEvent,
   UserInput,
 } from './types'
+
+export {
+  HARNESS_PROTOCOL_VERSION,
+  applyInput,
+  capabilitiesOf,
+  parseControlFrame,
+  parseHarnessInput,
+} from './protocol'
+export type { ControlFrame, HostFrame } from './protocol'
+
+export { createHarnessHandler, handleHarnessSocket } from './http'
+export type {
+  Authorize,
+  HarnessHandlerOptions,
+  HarnessSocketOptions,
+} from './http'
+
+export { harnessText } from './harness-text'
+export type { HarnessTextOptions } from './harness-text'
diff --git a/packages/ai-harness/src/protocol.ts b/packages/ai-harness/src/protocol.ts
new file mode 100644
index 0000000000..3532454792
--- /dev/null
+++ b/packages/ai-harness/src/protocol.ts
@@ -0,0 +1,200 @@
+import { convertSchemaToJsonSchema } from '@tanstack/ai'
+import type { StreamChunk } from '@tanstack/ai'
+import type { AnyAgent } from './agents'
+import type { AnyHarness } from './define'
+import type { HarnessSession, SessionSnapshot } from './session'
+import type { Cursor, HarnessInput, 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',
+  'resolve',
+  'agent',
+  'cancel',
+])
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+/** 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'
+  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.')
+  }
+  // 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. Only agents in `expose.agents` can run
+ * from a client. Resolves to the receipt.
+ */
+export async function applyInput(
+  harness: AnyHarness,
+  session: HarnessSession,
+  input: HarnessInput,
+): Promise<Receipt> {
+  switch (input.op) {
+    case 'prompt': {
+      const operation = session.prompt(
+        input.message,
+        input.busy ? { busy: input.busy } : {},
+      )
+      const queued = session
+        .snapshot()
+        .activeOperations.some(
+          (active) => active.kind === 'chat' && active.id !== operation.id,
+        )
+      return {
+        inputId: operation.id,
+        status: queued ? 'queued' : 'accepted',
+        operationId: operation.id,
+      }
+    }
+    case 'steer':
+      return session.steer(input.message)
+    case 'followUp':
+      return session.followUp(input.message)
+    case 'resolve':
+      return session.resolve(input.resume)
+    case 'cancel':
+      return session.cancel(input.operationId)
+    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,
+      }
+    }
+  }
+}
+
+/** 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/resume.ts b/packages/ai-harness/src/resume.ts
new file mode 100644
index 0000000000..ea695840e0
--- /dev/null
+++ b/packages/ai-harness/src/resume.ts
@@ -0,0 +1,146 @@
+import type { AnyChatMiddleware, ModelMessage, RunRecord } from '@tanstack/ai'
+import type { HarnessPersistence } from './host'
+
+/** How often a running host renews its lease, and when a lease expires. */
+export const LEASE = { renewMs: 10_000, ttlMs: 30_000 }
+
+/** The tool result a crash leaves for a tool that must not run twice. */
+export const INTERRUPTED_TOOL_RESULT = {
+  interrupted: true,
+  note: 'The tool may or may not have run. Check before you retry.',
+}
+
+type PendingTool = {
+  toolCallId: string
+  name: string
+  replay: 'safe' | 'never'
+}
+
+/**
+ * Chat middleware that makes a turn resumable after a crash:
+ *
+ * - holds a lease on the run record and renews it while the turn runs;
+ * - saves the transcript before and after each tool phase;
+ * - records each tool call that started but has no result yet.
+ */
+export function checkpointMiddleware(
+  persistence: HarnessPersistence,
+  hostId: string,
+): AnyChatMiddleware {
+  const runs = persistence.stores.runs
+  const messages = persistence.stores.messages
+  const state = new WeakMap<
+    object,
+    { timer: ReturnType<typeof setInterval>; pending: Array<PendingTool> }
+  >()
+
+  const saveCheckpoint = async (runId: string, pending: Array<PendingTool>) => {
+    await runs?.update(runId, {
+      checkpoint: { at: Date.now(), pendingTools: [...pending] },
+    })
+  }
+  const stop = (ctx: object) => {
+    const entry = state.get(ctx)
+    if (entry) clearInterval(entry.timer)
+    state.delete(ctx)
+  }
+
+  return {
+    name: 'harness:checkpoint',
+    async onStart(ctx) {
+      const renew = () =>
+        runs?.update(ctx.runId, {
+          leaseOwner: hostId,
+          leaseExpiresAt: Date.now() + LEASE.ttlMs,
+        })
+      await renew()
+      const timer = setInterval(() => void renew(), LEASE.renewMs)
+      // A lease timer must not keep a CLI or a test process alive.
+      if (typeof timer === 'object' && 'unref' in timer) timer.unref()
+      state.set(ctx, { timer, pending: [] })
+    },
+    async onBeforeToolCall(ctx, hook) {
+      const entry = state.get(ctx)
+      if (!entry) return
+      // The first call of a phase: the transcript now holds the assistant
+      // message with the tool calls. Save it, so resume can find them.
+      if (entry.pending.length === 0) {
+        await messages.saveThread(ctx.threadId, [...ctx.messages])
+      }
+      entry.pending.push({
+        toolCallId: hook.toolCallId,
+        name: hook.toolName,
+        replay: hook.tool?.replay ?? 'never',
+      })
+      await saveCheckpoint(ctx.runId, entry.pending)
+    },
+    async onAfterToolCall(ctx, info) {
+      const entry = state.get(ctx)
+      if (!entry) return
+      entry.pending = entry.pending.filter(
+        (tool) => tool.toolCallId !== info.toolCallId,
+      )
+    },
+    async onToolPhaseComplete(ctx) {
+      const entry = state.get(ctx)
+      if (!entry) return
+      await messages.saveThread(ctx.threadId, [...ctx.messages])
+      entry.pending = []
+      await saveCheckpoint(ctx.runId, [])
+    },
+    onFinish: (ctx) => stop(ctx),
+    onAbort: (ctx) => stop(ctx),
+    onError: (ctx) => stop(ctx),
+  }
+}
+
+/** Chat runs of this thread that a crashed host left `running`. */
+export async function findCrashedRuns(
+  persistence: HarnessPersistence,
+  threadId: string,
+  now = Date.now(),
+): Promise<Array<RunRecord>> {
+  const runs = persistence.stores.runs
+  if (!runs?.listByThread) return []
+  const records = await runs.listByThread(threadId)
+  return records.filter(
+    (record) =>
+      record.status === 'running' &&
+      (record.kind === undefined || record.kind === 'chat') &&
+      record.leaseExpiresAt !== undefined &&
+      record.leaseExpiresAt < now,
+  )
+}
+
+/**
+ * Prepare the transcript of a crashed run for a new run. A tool with
+ * `replay: 'never'` gets {@link INTERRUPTED_TOOL_RESULT}. A tool with
+ * `replay: 'safe'` stays without a result, so the engine runs it again.
+ */
+export async function repairTranscript(
+  persistence: HarnessPersistence,
+  crashed: RunRecord,
+): Promise<void> {
+  const pending = crashed.checkpoint?.pendingTools ?? []
+  const never = pending.filter((tool) => tool.replay === 'never')
+  if (never.length === 0) return
+  const store = persistence.stores.messages
+  const history = await store.loadThread(crashed.threadId)
+  const answered = new Set(
+    history.flatMap((message) =>
+      message.role === 'tool' && message.toolCallId ? [message.toolCallId] : [],
+    ),
+  )
+  const notes = never
+    .filter((tool) => !answered.has(tool.toolCallId))
+    .map(
+      (tool): ModelMessage => ({
+        role: 'tool',
+        toolCallId: tool.toolCallId,
+        content: JSON.stringify(INTERRUPTED_TOOL_RESULT),
+      }),
+    )
+  if (notes.length > 0) {
+    await store.saveThread(crashed.threadId, [...history, ...notes])
+  }
+}
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 9e5a74b5c3..3e638d0f31 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -12,6 +12,11 @@ import { AgentRegistry } from './agents'
 import { SessionFeed } from './feed'
 import { OperationImpl } from './operation'
 import { mountPlugins } from './plugins'
+import {
+  checkpointMiddleware,
+  findCrashedRuns,
+  repairTranscript,
+} from './resume'
 import { HARNESS_EVENTS } from './types'
 import type {
   AnyChatMiddleware,
@@ -74,6 +79,12 @@ export interface AgentHandle<TAgent> {
   ) => Operation<AgentResultOf<TAgent>>
 }
 
+/** A handle for an agent picked by name at runtime. */
+export interface DynamicAgentHandle {
+  run: (input?: unknown, options?: AgentRunOptions) => Operation<unknown>
+  start: (input?: unknown, options?: AgentStartOptions) => Operation<unknown>
+}
+
 /** `session.agents`: one typed handle per registered agent name. */
 export type AgentHandles<THarness> = {
   [TAgent in HarnessAgentsOf<THarness> as TAgent['name']]: AgentHandle<TAgent>
@@ -101,6 +112,8 @@ export interface SessionDependencies {
   persistence: HarnessPersistence
   inbox: InboxStore
   principal?: Principal
+  /** Identifies this host on run leases. */
+  hostId: string
   onClose: () => void
 }
 
@@ -173,6 +186,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   private sessionPlugins: MountedPlugins | undefined
   private closing: Promise<void> | undefined
   private readonly onClose: () => void
+  private readonly checkpoint: AnyChatMiddleware
 
   constructor(deps: SessionDependencies) {
     this.harness = deps.harness as THarness
@@ -181,6 +195,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     this.inbox = deps.inbox
     this.principal = deps.principal
     this.onClose = deps.onClose
+    this.checkpoint = checkpointMiddleware(deps.persistence, deps.hostId)
     this.registry = this.agentRegistry
     for (const agent of this.harness.agents ?? []) {
       this.agentRegistry.add(agent, 'the harness')
@@ -201,6 +216,24 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     })
   }
 
+  /**
+   * The agent named `name`, for names known only at runtime (a slash
+   * command, a protocol input). `undefined` when no such agent exists.
+   */
+  agent(name: string): DynamicAgentHandle | undefined {
+    if (!this.agentRegistry.get(name)) return undefined
+    return {
+      run: (input, options) =>
+        this.runAgent(name, input, { ...options, wake: false }),
+      start: (input, options) => this.runAgent(name, input, options ?? {}),
+    }
+  }
+
+  /** An operation of this session by id, running or settled. */
+  operation(id: string): Operation<unknown> | undefined {
+    return this.operations.get(id)
+  }
+
   /** @internal Mount session plugins and replay inputs left in the inbox. */
   async open(): Promise<void> {
     this.plugins = this.harness.plugins?.() ?? []
@@ -217,6 +250,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         ),
       },
     )
+    await this.recoverCrashedTurn()
     await this.recoverInbox()
   }
 
@@ -513,6 +547,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         middleware: [
           ...bridges,
           withPersistence(this.persistence),
+          this.checkpoint,
           ...(this.harness.middleware ?? []),
           ...(session?.middleware ?? []),
           ...(runPlugins?.middleware ?? []),
@@ -844,6 +879,38 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     )
   }
 
+  /**
+   * Continue the newest chat turn that a crashed host left running. Older
+   * crashed turns are marked failed.
+   */
+  private async recoverCrashedTurn(): Promise<void> {
+    const crashed = await findCrashedRuns(this.persistence, this.threadId)
+    const newest = crashed.sort((a, b) => b.startedAt - a.startedAt)[0]
+    for (const record of crashed) {
+      await this.persistence.stores.runs?.update(record.runId, {
+        status: 'failed',
+        finishedAt: Date.now(),
+        error: {
+          message:
+            record === newest
+              ? 'The host stopped. The session continued this turn in a new run.'
+              : 'The host stopped during this turn.',
+        },
+      })
+    }
+    if (!newest) return
+    await repairTranscript(this.persistence, newest)
+    const operation = this.createTurnOperation()
+    this.feed.publish(
+      operation.id,
+      customEvent(HARNESS_EVENTS.operationResumed, {
+        operationId: operation.id,
+        resumedFrom: newest.runId,
+      }),
+    )
+    this.enqueueTurn({ operation })
+  }
+
   /** Re-run turns that were accepted but never applied before a restart. */
   private async recoverInbox(): Promise<void> {
     const pending: Array<InboxEntry> = await this.inbox.listPending(
diff --git a/packages/ai-harness/src/types.ts b/packages/ai-harness/src/types.ts
index 5d6b766ae9..43c65515b7 100644
--- a/packages/ai-harness/src/types.ts
+++ b/packages/ai-harness/src/types.ts
@@ -93,6 +93,7 @@ export interface Operation<TResult> extends PromiseLike<TResult> {
 export const HARNESS_EVENTS = {
   operationStarted: 'harness.operation.started',
   operationFinished: 'harness.operation.finished',
+  operationResumed: 'harness.operation.resumed',
   inputAccepted: 'harness.input.accepted',
   inputApplied: 'harness.input.applied',
   inputRejected: 'harness.input.rejected',
diff --git a/packages/ai-harness/tests/client.test.ts b/packages/ai-harness/tests/client.test.ts
new file mode 100644
index 0000000000..8f45fd9961
--- /dev/null
+++ b/packages/ai-harness/tests/client.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, it } 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 { 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,
+      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('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,
+      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()
+  })
+})
diff --git a/packages/ai-harness/tests/harness-text.test.ts b/packages/ai-harness/tests/harness-text.test.ts
new file mode 100644
index 0000000000..86bc7619ef
--- /dev/null
+++ b/packages/ai-harness/tests/harness-text.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest'
+import { EventType, chat } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness, harnessText } from '../src'
+import { messageTexts, mockAdapter, text } from './helpers'
+import type { StreamChunk } from '@tanstack/ai'
+
+describe('harnessText', () => {
+  it('runs a harness as the model of chat() and keeps its own transcript', async () => {
+    const inner = mockAdapter([
+      () => text('inner answer'),
+      () => text('second answer'),
+    ])
+    const studio = defineHarness({ name: 'test/inner', adapter: inner.adapter })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+
+    const collect = async (content: string) => {
+      const chunks: Array<StreamChunk> = []
+      for await (const chunk of chat({
+        adapter: harnessText(studio, { host }),
+        messages: [{ role: 'user', content }],
+        threadId: 'outer-1',
+      })) {
+        chunks.push(chunk)
+      }
+      return chunks
+    }
+
+    const first = await collect('hello')
+    const deltas = first
+      .filter((chunk) => chunk.type === EventType.TEXT_MESSAGE_CONTENT)
+      .map((chunk) =>
+        chunk.type === EventType.TEXT_MESSAGE_CONTENT ? chunk.delta : '',
+      )
+    expect(deltas.join('')).toBe('inner answer')
+    expect(first.some((chunk) => chunk.type === EventType.RUN_ERROR)).toBe(
+      false,
+    )
+
+    await collect('and then?')
+    // The inner session saw the first turn as history.
+    expect(messageTexts(inner.calls[1])).toEqual([
+      'hello',
+      'inner answer',
+      'and then?',
+    ])
+    await host.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..b37209e84c
--- /dev/null
+++ b/packages/ai-harness/tests/protocol.test.ts
@@ -0,0 +1,287 @@
+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,
+} from '../src'
+import { mockAdapter, text } from './helpers'
+import type { WebSocketLike } from '@tanstack/ai'
+import type { HostFrame } from '../src'
+
+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 = [() => 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' }
+
+async function readSse(response: Response, until: (data: any) => boolean) {
+  const reader = response.body!.getReader()
+  const decoder = new TextDecoder()
+  const frames: Array<any> = []
+  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
+      const parsed = 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 = (input: unknown) =>
+      handler(
+        new Request('http://x/api/harness/control', {
+          method: 'POST',
+          headers: { ...auth, 'content-type': 'application/json' },
+          body: JSON.stringify({ threadId: 'user-1-t', input }),
+        }),
+      )
+
+    const receipt = await (
+      await control({ op: 'prompt', message: 'hi' })
+    ).json()
+    expect(receipt.status).toBe('accepted')
+
+    const first = await readSse(
+      await handler(
+        new Request('http://x/api/harness/events?threadId=user-1-t', {
+          headers: auth,
+        }),
+      ),
+      (frame) => frame.event?.name === 'harness.operation.finished',
+    )
+    expect(first.every((frame) => frame.type === 'harness.event')).toBe(true)
+    const cursor = first.at(-1).cursor
+
+    await (await control({ op: 'prompt', message: 'more' })).json()
+    const second = await readSse(
+      await handler(
+        new Request('http://x/api/harness/events?threadId=user-1-t', {
+          headers: { ...auth, 'Last-Event-ID': cursor },
+        }),
+      ),
+      (frame) => frame.event?.name === 'harness.operation.finished',
+    )
+    expect(second.every((frame) => Number(frame.cursor) > Number(cursor))).toBe(
+      true,
+    )
+    expect(JSON.stringify(second)).toContain('again')
+    await host.close()
+  })
+
+  it('runs exposed agents from a client and refuses the others', async () => {
+    const { handler, host } = 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-a', input }),
+          }),
+        )
+      ).json()
+
+    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()
+  })
+})
+
+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' } })
+
+    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/resume.test.ts b/packages/ai-harness/tests/resume.test.ts
new file mode 100644
index 0000000000..c57c045baf
--- /dev/null
+++ b/packages/ai-harness/tests/resume.test.ts
@@ -0,0 +1,185 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { EventType, toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { HARNESS_EVENTS, createHarnessHost, defineHarness } from '../src'
+import { INTERRUPTED_TOOL_RESULT, LEASE } from '../src/resume'
+import { gate, mockAdapter, text, toolCall } from './helpers'
+import type { SessionEvent } from '../src'
+
+describe('checkpoints and leases', () => {
+  it('holds a lease and records the running tool with its replay mode', async () => {
+    const persistence = memoryPersistence()
+    const host = createHarnessHost({ persistence })
+    const started = gate()
+    const release = gate()
+    const lookup = toolDefinition({
+      name: 'lookup',
+      description: 'Look up a fact',
+      inputSchema: z.object({ q: z.string() }),
+      replay: 'safe',
+    }).server(async () => {
+      started.open()
+      await release.opened
+      return 'found'
+    })
+    const { adapter } = mockAdapter([
+      () => toolCall('lookup', { q: 'x' }),
+      () => text('done'),
+    ])
+    const session = await host.open(
+      defineHarness({ name: 'test/lease', adapter, tools: [lookup] }),
+      { threadId: 't1' },
+    )
+
+    const turn = session.prompt('go')
+    await started.opened
+    const running = await persistence.stores.runs.get(turn.id)
+    expect(running?.leaseOwner).toMatch(/^host-/)
+    expect(running?.leaseExpiresAt).toBeGreaterThan(Date.now())
+    expect(running?.leaseExpiresAt).toBeLessThanOrEqual(
+      Date.now() + LEASE.ttlMs,
+    )
+    expect(running?.checkpoint?.pendingTools).toEqual([
+      { toolCallId: 'call-1', name: 'lookup', replay: 'safe' },
+    ])
+    // The assistant message with the tool call is saved before the tool runs.
+    const saved = await persistence.stores.messages.loadThread('t1')
+    expect(saved.at(-1)?.toolCalls?.[0]?.function.name).toBe('lookup')
+
+    release.open()
+    await turn
+    const finished = await persistence.stores.runs.get(turn.id)
+    expect(finished?.checkpoint?.pendingTools).toEqual([])
+    await host.close()
+  })
+})
+
+describe('crash resume', () => {
+  it('continues a crashed turn, runs safe tools again, and notes the others', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.messages.saveThread('t1', [
+      { id: 'u1', role: 'user', content: 'refund and look up' },
+      {
+        id: 'a1',
+        role: 'assistant',
+        content: '',
+        toolCalls: [
+          {
+            id: 'call-charge',
+            type: 'function',
+            function: { name: 'charge', arguments: '{"cents":100}' },
+          },
+          {
+            id: 'call-lookup',
+            type: 'function',
+            function: { name: 'lookup', arguments: '{"q":"x"}' },
+          },
+        ],
+      },
+    ])
+    await persistence.stores.runs.createOrResume({
+      runId: 'crashed-run',
+      threadId: 't1',
+      startedAt: Date.now() - 60_000,
+    })
+    await persistence.stores.runs.update('crashed-run', {
+      leaseOwner: 'host-gone',
+      leaseExpiresAt: Date.now() - 1_000,
+      checkpoint: {
+        at: Date.now() - 2_000,
+        pendingTools: [
+          { toolCallId: 'call-charge', name: 'charge', replay: 'never' },
+          { toolCallId: 'call-lookup', name: 'lookup', replay: 'safe' },
+        ],
+      },
+    })
+
+    const charge = vi.fn(async () => 'charged')
+    const lookup = vi.fn(async () => 'found')
+    const tools = [
+      toolDefinition({
+        name: 'charge',
+        description: 'Charge a card',
+        inputSchema: z.object({ cents: z.number() }),
+      }).server(charge),
+      toolDefinition({
+        name: 'lookup',
+        description: 'Look up a fact',
+        inputSchema: z.object({ q: z.string() }),
+        replay: 'safe',
+      }).server(lookup),
+    ]
+    const { adapter, calls } = mockAdapter([() => text('recovered')])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({ name: 'test/resume', adapter, tools }),
+      { threadId: 't1' },
+    )
+
+    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 vi.waitFor(() => expect(session.snapshot().status).toBe('idle'))
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    controller.abort()
+    await reading
+
+    expect(lookup).toHaveBeenCalledTimes(1)
+    expect(charge).not.toHaveBeenCalled()
+    const transcript = await persistence.stores.messages.loadThread('t1')
+    const chargeResult = transcript.find(
+      (message) =>
+        message.role === 'tool' && message.toolCallId === 'call-charge',
+    )
+    expect(chargeResult?.content).toBe(JSON.stringify(INTERRUPTED_TOOL_RESULT))
+    expect(transcript.at(-1)?.content).toBe('recovered')
+
+    expect((await persistence.stores.runs.get('crashed-run'))?.status).toBe(
+      'failed',
+    )
+    const resumed = seen.find(
+      (entry) =>
+        entry.event.type === EventType.CUSTOM &&
+        entry.event.name === HARNESS_EVENTS.operationResumed,
+    )
+    expect(resumed?.event).toMatchObject({
+      value: { resumedFrom: 'crashed-run' },
+    })
+    await host.close()
+  })
+
+  it('leaves a run alone while its lease is still valid', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.runs.createOrResume({
+      runId: 'live-run',
+      threadId: 't1',
+      startedAt: Date.now(),
+    })
+    await persistence.stores.runs.update('live-run', {
+      leaseOwner: 'host-other',
+      leaseExpiresAt: Date.now() + 20_000,
+    })
+    const { adapter, calls } = mockAdapter([])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({ name: 'test/live', adapter }),
+      {
+        threadId: 't1',
+      },
+    )
+    expect(session.snapshot().status).toBe('idle')
+    expect(calls).toHaveLength(0)
+    expect((await persistence.stores.runs.get('live-run'))?.status).toBe(
+      'running',
+    )
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/vite.config.ts b/packages/ai-harness/vite.config.ts
index 1f3542380f..2fabdfea04 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'],
     srcDir: './src',
     cjs: false,
   }),
diff --git a/packages/ai/src/activities/chat/tools/tool-definition.ts b/packages/ai/src/activities/chat/tools/tool-definition.ts
index cbe4db76ca..a141e5d478 100644
--- a/packages/ai/src/activities/chat/tools/tool-definition.ts
+++ b/packages/ai/src/activities/chat/tools/tool-definition.ts
@@ -128,6 +128,7 @@ export interface ClientTool<
   needsApproval?: TNeedsApproval
   approvalSchema?: TApprovalSchema
   lazy?: boolean
+  replay?: 'safe' | 'never'
   metadata?: Record<string, unknown>
   execute?: ToolExecuteFunction<TInput, TOutput, TContext>
 }
@@ -220,6 +221,12 @@ export type ToolDefinitionConfig<
   inputSchema?: TInput
   outputSchema?: TOutput
   lazy?: boolean
+  /**
+   * Whether a harness may run this tool again after a crash cut the run
+   * between the call and its result. `'safe'` runs it again. `'never'`
+   * (default) gives the model a note that the tool may or may not have run.
+   */
+  replay?: 'safe' | 'never'
   metadata?: Record<string, unknown>
 } & ApprovalConfig<TNeedsApproval, TApprovalSchema>
 
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index 3d29433e71..33b6687fed 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -874,6 +874,13 @@ export interface Tool<
   /** If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools). */
   lazy?: boolean
 
+  /**
+   * Whether a harness may run this tool again after a crash cut the run
+   * between the call and its result. `'safe'` runs it again. `'never'`
+   * (default) gives the model a note that the tool may or may not have run.
+   */
+  replay?: 'safe' | 'never'
+
   /** Additional metadata for adapters or custom extensions */
   metadata?: Record<string, any> | undefined
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ca0c6edf73..4a914a15c6 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1979,12 +1979,18 @@ importers:
   packages/ai-acp:
     dependencies:
       '@agentclientprotocol/sdk':
-        specifier: ^0.25.0
-        version: 0.25.1(zod@4.3.6)
+        specifier: ^1.5.0
+        version: 1.5.0(zod@4.3.6)
     devDependencies:
       '@tanstack/ai':
         specifier: workspace:*
         version: link:../ai
+      '@tanstack/ai-harness':
+        specifier: workspace:*
+        version: link:../ai-harness
+      '@tanstack/ai-persistence':
+        specifier: workspace:*
+        version: link:../ai-persistence
       '@tanstack/ai-sandbox':
         specifier: workspace:*
         version: link:../ai-sandbox
@@ -2535,6 +2541,37 @@ importers:
         specifier: ^4.2.0
         version: 4.3.6
 
+  packages/ai-harness-cli:
+    dependencies:
+      ink:
+        specifier: ^7.1.1
+        version: 7.1.1(@types/react@19.3.0)(react-devtools-core@6.1.5)(react@19.2.3)
+      react:
+        specifier: ^19.2.3
+        version: 19.2.3
+    devDependencies:
+      '@tanstack/ai':
+        specifier: workspace:*
+        version: link:../ai
+      '@tanstack/ai-acp':
+        specifier: workspace:*
+        version: link:../ai-acp
+      '@tanstack/ai-harness':
+        specifier: workspace:*
+        version: link:../ai-harness
+      '@tanstack/ai-persistence':
+        specifier: workspace:*
+        version: link:../ai-persistence
+      '@tanstack/ai-sandbox':
+        specifier: workspace:*
+        version: link:../ai-sandbox
+      '@types/react':
+        specifier: ^19.2.7
+        version: 19.3.0
+      '@vitest/coverage-v8':
+        specifier: 4.1.10
+        version: 4.1.10(vitest@4.1.11)
+
   packages/ai-isolate-cloudflare:
     dependencies:
       '@tanstack/ai-code-mode':
@@ -3900,11 +3937,15 @@ packages:
       zod:
         optional: true
 
-  '@agentclientprotocol/sdk@0.25.1':
-    resolution: {integrity: sha512-jx2rF3bdpGwZ75Q/meyEDLLbYmbtxk82Uh9hDCdxDvcEedBnNSF5hZAnL/kJR5VNz56JqwOmqnAqasC84MwwkQ==}
+  '@agentclientprotocol/sdk@1.5.0':
+    resolution: {integrity: sha512-524jwbB2iYWA+kWWyv9fhKbhU89dH/lu9u5EXwVNmfYzopV8BujCDxByBDZhxRUkB7RWIJzISCnwivdDk+bdVg==}
     peerDependencies:
       zod: ^3.25.0 || ^4.0.0
 
+  '@alcalzone/ansi-tokenize@0.3.1':
+    resolution: {integrity: sha512-cUD0PT0YX+rImRhfn7BfMRduP/tX/Zqt/N0dHlAyn2RlcJssCb5KsCJkhln61eh9vuJDkH8wKn3L8zJzzWXPFg==}
+    engines: {node: '>=18'}
+
   '@ampproject/remapping@2.3.0':
     resolution: {integrity: sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw==}
     engines: {node: '>=6.0.0'}
@@ -11853,10 +11894,6 @@ packages:
     resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==}
     engines: {node: '>=8'}
 
-  ansi-regex@6.2.2:
-    resolution: {integrity: sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==}
-    engines: {node: '>=12'}
-
   ansi-regex@6.3.0:
     resolution: {integrity: sha512-WpDfL7NO6j7tH88IDBNVdUJxDh9nmCteAVW9dsep846XdwF4naCBK+/tGLX3KJgcpgMRXCFlTM2hKGoK9FsdrQ==}
     engines: {node: '>=12'}
@@ -11970,6 +12007,10 @@ packages:
   asynckit@0.4.0:
     resolution: {integrity: sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==}
 
+  auto-bind@5.0.1:
+    resolution: {integrity: sha512-ooviqdwwgfIfNmDwo94wlshcdzfO64XV0Cg6oDsDYBJfITDz1EngD2z7DkbvCWn+XIMsIqW27sEVF6qcpJrRcg==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   autoprefixer@10.4.22:
     resolution: {integrity: sha512-ARe0v/t9gO28Bznv6GgqARmVqcWOV3mfgUPn9becPHMiD3o9BwlRgaeccZnwTpZ7Zwqrm+c1sUSsMxIzQzc8Xg==}
     engines: {node: ^10 || ^12 || >=14}
@@ -12442,6 +12483,10 @@ packages:
     resolution: {integrity: sha512-/lzGpEWL/8PfI0BmBOPRwp0c/wFNX1RdUML3jK/RcSBA9T8mZDdQpqYBKtCFTOfQbwPqWEOpjqW+Fnayc0969g==}
     engines: {node: '>=10'}
 
+  cli-boxes@4.0.1:
+    resolution: {integrity: sha512-5IOn+jcCEHEraYolBPs/sT4BxYCe2nHg374OPiItB1O96KZFseS2gthU4twyYzeDcFew4DaUM/xwc5BQf08JJw==}
+    engines: {node: '>=18.20 <19 || >=20.10'}
+
   cli-cursor@2.1.0:
     resolution: {integrity: sha512-8lgKz8LmCRYZZQDpRyT2m5rKJ08TnU4tR9FFFW2rxpxR1FzWi4PQ/NfyODchAatHaUgnSPVcx/R5w6NuTBzFiw==}
     engines: {node: '>=4'}
@@ -12450,6 +12495,10 @@ packages:
     resolution: {integrity: sha512-I/zHAwsKf9FqGoXM4WWRACob9+SNukZTd94DWF57E4toouRulbCxcUh6RKUEOQlYTHJnzkPMySvPNaaSLNfLZw==}
     engines: {node: '>=8'}
 
+  cli-cursor@4.0.0:
+    resolution: {integrity: sha512-VGtlMu3x/4DOtIUwEkRezxUZ2lBacNJCHash0N0WeZDBS+7Ux1dm3XWAgWYxLJFMMdOeXMHXorshEFhbMSGelg==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   cli-cursor@5.0.0:
     resolution: {integrity: sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==}
     engines: {node: '>=18'}
@@ -12466,6 +12515,10 @@ packages:
     resolution: {integrity: sha512-xRwvIOMGrfOAnM1JYtqQImuaNtDEv9v6oIYAs4LIHwTiKee8uwvIi363igssOC0O5U04i4AlENs79LQLu9tEMw==}
     engines: {node: '>=20'}
 
+  cli-truncate@6.1.1:
+    resolution: {integrity: sha512-06p9vyLahLa4zkGcgsGxU6iEkSOiuI4fhCH6Emhe2lPAcoUv73n72DnODsnHA+5wwXGnV0n9M9/qOQJSjYhFhw==}
+    engines: {node: '>=22'}
+
   cli-width@4.1.0:
     resolution: {integrity: sha512-ouuZd4/dm2Sw5Gmqy6bGyNNNe1qt9RpmxveLSO7KcgsTnU7RXfsw+/bukWGo1abgBiMAic068rclZsO4IWmmxQ==}
     engines: {node: '>= 12'}
@@ -12501,6 +12554,10 @@ packages:
   code-block-writer@12.0.0:
     resolution: {integrity: sha512-q4dMFMlXtKR3XNBHyMHt/3pwYNA69EDk00lloMOaaUMKPUXBw6lpXtbu3MMVG6/uOihGnRDOlkyqsONEUj60+w==}
 
+  code-excerpt@4.0.0:
+    resolution: {integrity: sha512-xxodCmBen3iy2i0WtAK8FlFNrRzjUqjRsMfho58xT/wvZU1YTM3fCnRjcy1gJPMepaRlgm/0e6w8SpWHpn3/cA==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   color-convert@1.9.3:
     resolution: {integrity: sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==}
 
@@ -12631,6 +12688,10 @@ packages:
   convert-source-map@2.0.0:
     resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==}
 
+  convert-to-spaces@2.0.1:
+    resolution: {integrity: sha512-rcQ1bsQO9799wq24uE5AM2tAILy4gXGIK/njFWcVQkGNZ96edlpY+A7bjwvzjYvLDyzmG1MmMLZhpcsb+klNMQ==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   cookie-es@1.2.2:
     resolution: {integrity: sha512-+W7VmiVINB+ywl1HGXJXmrqkOhpKrIiVZV6tQuV54ZyQC7MMuBt81Vc336GMLoHBq5hV/F9eXgt5Mnx0Rha5Fg==}
 
@@ -13355,6 +13416,9 @@ packages:
     resolution: {integrity: sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==}
     engines: {node: '>= 0.4'}
 
+  es-toolkit@1.52.0:
+    resolution: {integrity: sha512-XTNEJQh1tY1ZJVcf6ayP/2n4ZPyaHlW2FWs7xvw5ddPuhUVjLD3olQVQS7kf58JbAB48iL0uL/jerTrjtV3lDA==}
+
   esbuild-plugin-solid@0.5.0:
     resolution: {integrity: sha512-ITK6n+0ayGFeDVUZWNMxX+vLsasEN1ILrg4pISsNOQ+mq4ljlJJiuXotInd+HE0MzwTcA9wExT1yzDE2hsqPsg==}
     peerDependencies:
@@ -13392,6 +13456,10 @@ packages:
     resolution: {integrity: sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==}
     engines: {node: '>=0.8.0'}
 
+  escape-string-regexp@2.0.0:
+    resolution: {integrity: sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w==}
+    engines: {node: '>=8'}
+
   escape-string-regexp@4.0.0:
     resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==}
     engines: {node: '>=10'}
@@ -13939,10 +14007,6 @@ packages:
     resolution: {integrity: sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==}
     engines: {node: 6.* || 8.* || >= 10.*}
 
-  get-east-asian-width@1.6.0:
-    resolution: {integrity: sha512-QRbvDIbx6YklUe6RxeTeleMR0yv3cYH6PsPZHcnVn7xv7zO1BHN8r0XETu8n6Ye3Q+ahtSarc3WgtNWmehIBfA==}
-    engines: {node: '>=18'}
-
   get-east-asian-width@1.7.0:
     resolution: {integrity: sha512-XjH1AECxf0giL2V1aU8vKyRR2ppRUb5c0EvT7zuJTokQ74bNo52zOtghqdWIqrhUD79fo3x0WfKZdOqxF6LG1Q==}
     engines: {node: '>=18'}
@@ -14346,6 +14410,10 @@ packages:
     resolution: {integrity: sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==}
     engines: {node: '>=0.8.19'}
 
+  indent-string@5.0.0:
+    resolution: {integrity: sha512-m6FAo/spmsW2Ab2fU35JTYwtOKa2yAwXSwgjSv1TJzh4Mh7mC3lzAOVLBprb72XsTrgkEIsl7YrFNAiDiRhIGg==}
+    engines: {node: '>=12'}
+
   inherits@2.0.4:
     resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
 
@@ -14355,6 +14423,19 @@ packages:
   injection-js@2.6.1:
     resolution: {integrity: sha512-dbR5bdhi7TWDoCye9cByZqeg/gAfamm8Vu3G1KZOTYkOif8WkuM8CD0oeDPtZYMzT5YH76JAFB7bkmyY9OJi2A==}
 
+  ink@7.1.1:
+    resolution: {integrity: sha512-Y43xxa1ZSPvpmfLHcN5o+OdP8Rf8ykkNJEuKYOUNZKT8wXVNLFTtEm1nSDMQkfBH+YANF4Xuu0hhZ4ejqAtN2w==}
+    engines: {node: '>=22'}
+    peerDependencies:
+      '@types/react': '>=19.2.0'
+      react: '>=19.2.0'
+      react-devtools-core: '>=6.1.2'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      react-devtools-core:
+        optional: true
+
   inline-style-parser@0.1.1:
     resolution: {integrity: sha512-7NXolsK4CAS5+xvdj5OMMbI962hU/wvwoxk+LWR9Ek9bVtyuuYScDN6eS0rUm6TxApFpw7CX1o4uJzcd4AyD3Q==}
 
@@ -14479,6 +14560,11 @@ packages:
     resolution: {integrity: sha512-S+OpgB5i7wzIue/YSE5hg0e5ZYfG3hhpNh9KGl6ayJ38p7ED6wxQLd1TV91xHpcTvw90KMJ9EwN3F/iNflHBVg==}
     engines: {node: '>=8'}
 
+  is-in-ci@2.0.0:
+    resolution: {integrity: sha512-cFeerHriAnhrQSbpAxL37W1wcJKUUX07HyLWZCW1URJT/ra3GyUTzBgUnh24TMVfNTV2Hij2HLxkPHFZfOZy5w==}
+    engines: {node: '>=20'}
+    hasBin: true
+
   is-in-ssh@1.0.0:
     resolution: {integrity: sha512-jYa6Q9rH90kR1vKB6NM7qqd1mge3Fx4Dhw5TVlK1MUBqhEOuCagrEHMevNuCcbECmXZ0ThXkRm+Ymr51HwEPAw==}
     engines: {node: '>=20'}
@@ -16182,6 +16268,10 @@ packages:
   partial-json@0.1.7:
     resolution: {integrity: sha512-Njv/59hHaokb/hRUjce3Hdv12wd60MtM9Z5Olmn+nehe0QDAsRtRbJPvJ0Z91TusF0SuZRIvnM+S4l6EIP8leA==}
 
+  patch-console@2.0.0:
+    resolution: {integrity: sha512-0YNdUceMdaQwoKce1gatDScmMo5pu/tfABfnzEqeG0gtTmd7mh/WcwgUjtAeOU7N8nFFlbQBnFK2gXW5fGvmMA==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   path-browserify@1.0.1:
     resolution: {integrity: sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g==}
 
@@ -16618,6 +16708,12 @@ packages:
       '@types/react':
         optional: true
 
+  react-reconciler@0.33.0:
+    resolution: {integrity: sha512-KetWRytFv1epdpJc3J4G75I4WrplZE5jOL7Yq0p34+OVOKF4Se7WrdIdVC45XsSSmUTlht2FM/fM1FZb1mfQeA==}
+    engines: {node: '>=0.10.0'}
+    peerDependencies:
+      react: ^19.2.0
+
   react-refresh@0.14.2:
     resolution: {integrity: sha512-jCvmsr+1IUSMUyzOkRcvnVbX3ZYC6g9TDrDbFuFmRDq7PD4yaGbLKNQL6k2jnArV8hjYxh7hVhAZB6s9HDGpZA==}
     engines: {node: '>=0.10.0'}
@@ -16858,6 +16954,10 @@ packages:
     resolution: {integrity: sha512-l+sSefzHpj5qimhFSE5a8nufZYAM3sBSVMAPtYkmC+4EH2anSGaEMXSD0izRQbu9nfyQ9y5JrVmp7E8oZrUjvA==}
     engines: {node: '>=8'}
 
+  restore-cursor@4.0.0:
+    resolution: {integrity: sha512-I9fPXU9geO9bHOt9pHHOhOkYerIMsmVaWB0rA2AI9ERh/+x/i7MV5HKBNrg+ljO5eoPVgCcnFuRjJ9uH6I/3eg==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   restore-cursor@5.1.0:
     resolution: {integrity: sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==}
     engines: {node: '>=18'}
@@ -17278,6 +17378,10 @@ packages:
     resolution: {integrity: sha512-stxByr12oeeOyY2BlviTNQlYV5xOj47GirPr4yA1hE9JCtxfQN0+tVbkxwCtYDQWhEKWFHsEK48ORg5jrouCAg==}
     engines: {node: '>=20'}
 
+  slice-ansi@9.0.1:
+    resolution: {integrity: sha512-aBY19bn/XA+hKOKX0qL7Z0UfdBsbQvc9hn993U8ALUjzxCvDcuZqLoRXjGJrUARWAlwMnsRVD9sw2AFNOYvalA==}
+    engines: {node: '>=22'}
+
   slugify@1.6.9:
     resolution: {integrity: sha512-vZ7rfeehZui7wQs438JXBckYLkIIdfHOXsaVEUMyS5fHo1483l1bMdo0EDSWYclY0yZKFOipDy4KHuKs6ssvdg==}
     engines: {node: '>=8.0.0'}
@@ -17375,6 +17479,10 @@ packages:
     resolution: {integrity: sha512-wPldCk3asibAjQ/kziWQQt1Wh3PgDFpC0XpwclzKcdT1vql6KeYxf5LIt4nlFkUeR8WuphYMKqUA56X4rjbfgQ==}
     engines: {node: '>=10.16.0'}
 
+  stack-utils@2.0.6:
+    resolution: {integrity: sha512-XlkWvfIm6RmsWtNJx+uqtKLS8eqFbxUg0ZzLXqY0caEy9l7hruX8IpiDnjsLavoBgqCCR71TqWO8MaXYheJ3RQ==}
+    engines: {node: '>=10'}
+
   stackback@0.0.2:
     resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}
 
@@ -17450,10 +17558,6 @@ packages:
     resolution: {integrity: sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==}
     engines: {node: '>=18'}
 
-  string-width@8.2.1:
-    resolution: {integrity: sha512-IIaP0g3iy9Cyy18w3M9YcaDudujEAVHKt3a3QJg1+sr/oX96TbaGUubG0hJyCjCBThFH+tFpcIyoUHUn1ogaLA==}
-    engines: {node: '>=20'}
-
   string-width@8.2.2:
     resolution: {integrity: sha512-GaPUh5gfdrYzqeVNZvUfT23vYYxXzKYidUcnMtJg/3rxRV63EFZy3k6xfKlmfeJD0176lnUV/Usr3XcwSvFzpg==}
     engines: {node: '>=20'}
@@ -17475,10 +17579,6 @@ packages:
     resolution: {integrity: sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==}
     engines: {node: '>=8'}
 
-  strip-ansi@7.1.2:
-    resolution: {integrity: sha512-gmBGslpoQJtgnMAvOVqGZpEz9dyoKTCzy2nfz/n8aIFhN/jCE/rCmcxabB6jOOHV+0WNnylOxaxBQPSvcWklhA==}
-    engines: {node: '>=12'}
-
   strip-ansi@7.2.0:
     resolution: {integrity: sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==}
     engines: {node: '>=12'}
@@ -17625,6 +17725,10 @@ packages:
     resolution: {integrity: sha512-un0FmiRUQNr5PJqy9kP7c40F5BOfpGlYTrxonDChEZB7pzZxRNp/bt+ymiy9/npwXya9KH99nJ/GXFIiUkYGFQ==}
     engines: {node: '>=8'}
 
+  terminal-size@4.0.1:
+    resolution: {integrity: sha512-avMLDQpUI9I5XFrklECw1ZEUPJhqzcwSWsyyI8blhRLT+8N1jLJWLWWYQpB2q2xthq8xDvjZPISVh53T/+CLYQ==}
+    engines: {node: '>=18'}
+
   terser@5.44.1:
     resolution: {integrity: sha512-t/R3R/n0MSwnnazuPpPNVO60LX0SKL45pyl9YlvxIdkH0Of7D5qM2EVe+yASRIlY5pZ73nclYJfNANGWPwFDZw==}
     engines: {node: '>=10'}
@@ -17866,6 +17970,10 @@ packages:
     resolution: {integrity: sha512-RAH822pAdBgcNMAfWnCBU3CFZcfZ/i1eZjwFU/dsLKumyuuP3niueg2UAukXYF0E2AAoc82ZSSf9J0WQBinzHA==}
     engines: {node: '>=12.20'}
 
+  type-fest@5.10.0:
+    resolution: {integrity: sha512-NoSdpq/WEiAg5sjmBkmV/hfxv6HJH4NqPNrqjtSO5CwRmpsDfaf4begxW34KdJykH/l1yHtwBWQkCRdoXO8mPA==}
+    engines: {node: '>=20'}
+
   type-fest@5.3.1:
     resolution: {integrity: sha512-VCn+LMHbd4t6sF3wfU/+HKT63C9OoyrSIf4b+vtWHpt2U7/4InZG467YDNMFMR70DdHjAdpPWmw2lzRdg0Xqqg==}
     engines: {node: '>=20'}
@@ -18786,6 +18894,10 @@ packages:
     resolution: {integrity: sha512-o0cyEG0e8GPzT4iGHphIOh0cJOV8fivsXxddQasHPHfoZf1ZexrfeA21w2NaEN1RHE+fXlfISmOE8R9N3u3Qig==}
     engines: {node: '>=12'}
 
+  widest-line@6.0.0:
+    resolution: {integrity: sha512-U89AsyEeAsyoF0zVJBkG9zBgekjgjK7yk9sje3F4IQpXBJ10TF6ByLlIfjMhcmHMJgHZI4KHt4rdNfktzxIAMA==}
+    engines: {node: '>=20'}
+
   word-wrap@1.2.5:
     resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==}
     engines: {node: '>=0.10.0'}
@@ -18810,6 +18922,10 @@ packages:
       '@cloudflare/workers-types':
         optional: true
 
+  wrap-ansi@10.0.2:
+    resolution: {integrity: sha512-6OLRNZqRntVGBm26ghZ5eZhCuWWyOkRCSn8XsOIuq5stpCE/tjLbdozd93naILZig0lmD8ANfRwnhn0DLeXGlg==}
+    engines: {node: '>=20'}
+
   wrap-ansi@6.2.0:
     resolution: {integrity: sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==}
     engines: {node: '>=8'}
@@ -18986,6 +19102,9 @@ packages:
     resolution: {integrity: sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug==}
     engines: {node: '>=18'}
 
+  yoga-layout@3.2.1:
+    resolution: {integrity: sha512-0LPOt3AxKqMdFBZA3HBAt/t/8vIKq7VaQYbuA8WxCgung+p9TVyKRYdpvCb80HcdTN2NkbIKbhNwKUfm3tQywQ==}
+
   youch-core@0.3.3:
     resolution: {integrity: sha512-ho7XuGjLaJ2hWHoK8yFnsUGy2Y5uDpqSTq1FkHLK4/oqKtyUU1AFbOOxY4IpC9f0fTLjwYbslUz0Po5BpD1wrA==}
 
@@ -19039,10 +19158,15 @@ snapshots:
     optionalDependencies:
       zod: 4.2.1
 
-  '@agentclientprotocol/sdk@0.25.1(zod@4.3.6)':
+  '@agentclientprotocol/sdk@1.5.0(zod@4.3.6)':
     dependencies:
       zod: 4.3.6
 
+  '@alcalzone/ansi-tokenize@0.3.1':
+    dependencies:
+      ansi-styles: 6.2.3
+      is-fullwidth-code-point: 5.1.0
+
   '@ampproject/remapping@2.3.0':
     dependencies:
       '@jridgewell/gen-mapping': 0.3.13
@@ -22599,7 +22723,7 @@ snapshots:
     dependencies:
       string-width: 5.1.2
       string-width-cjs: string-width@4.2.3
-      strip-ansi: 7.1.2
+      strip-ansi: 7.2.0
       strip-ansi-cjs: strip-ansi@6.0.1
       wrap-ansi: 8.1.0
       wrap-ansi-cjs: wrap-ansi@7.0.0
@@ -27077,7 +27201,7 @@ snapshots:
 
   '@tanstack/devtools-event-bus@0.3.3':
     dependencies:
-      ws: 8.21.0
+      ws: 8.21.3
     transitivePeerDependencies:
       - bufferutil
       - utf-8-validate
@@ -29666,8 +29790,6 @@ snapshots:
 
   ansi-regex@5.0.1: {}
 
-  ansi-regex@6.2.2: {}
-
   ansi-regex@6.3.0: {}
 
   ansi-styles@3.2.1:
@@ -29790,6 +29912,8 @@ snapshots:
 
   asynckit@0.4.0: {}
 
+  auto-bind@5.0.1: {}
+
   autoprefixer@10.4.22(postcss@8.5.26):
     dependencies:
       browserslist: 4.28.1
@@ -30455,6 +30579,8 @@ snapshots:
 
   cli-boxes@3.0.0: {}
 
+  cli-boxes@4.0.1: {}
+
   cli-cursor@2.1.0:
     dependencies:
       restore-cursor: 2.0.0
@@ -30463,6 +30589,10 @@ snapshots:
     dependencies:
       restore-cursor: 3.1.0
 
+  cli-cursor@4.0.0:
+    dependencies:
+      restore-cursor: 4.0.0
+
   cli-cursor@5.0.0:
     dependencies:
       restore-cursor: 5.1.0
@@ -30474,7 +30604,12 @@ snapshots:
   cli-truncate@5.2.0:
     dependencies:
       slice-ansi: 8.0.0
-      string-width: 8.2.1
+      string-width: 8.2.2
+
+  cli-truncate@6.1.1:
+    dependencies:
+      slice-ansi: 9.0.1
+      string-width: 8.2.2
 
   cli-width@4.1.0: {}
 
@@ -30510,6 +30645,10 @@ snapshots:
 
   code-block-writer@12.0.0: {}
 
+  code-excerpt@4.0.0:
+    dependencies:
+      convert-to-spaces: 2.0.1
+
   color-convert@1.9.3:
     dependencies:
       color-name: 1.1.3
@@ -30625,6 +30764,8 @@ snapshots:
 
   convert-source-map@2.0.0: {}
 
+  convert-to-spaces@2.0.1: {}
+
   cookie-es@1.2.2: {}
 
   cookie-es@1.2.3: {}
@@ -31259,6 +31400,8 @@ snapshots:
       has-tostringtag: 1.0.2
       hasown: 2.0.4
 
+  es-toolkit@1.52.0: {}
+
   esbuild-plugin-solid@0.5.0(esbuild@0.28.1)(solid-js@1.9.10):
     dependencies:
       '@babel/core': 7.29.7
@@ -31388,6 +31531,8 @@ snapshots:
 
   escape-string-regexp@1.0.5: {}
 
+  escape-string-regexp@2.0.0: {}
+
   escape-string-regexp@4.0.0: {}
 
   escape-string-regexp@5.0.0: {}
@@ -32087,8 +32232,6 @@ snapshots:
 
   get-caller-file@2.0.5: {}
 
-  get-east-asian-width@1.6.0: {}
-
   get-east-asian-width@1.7.0: {}
 
   get-intrinsic@1.3.0:
@@ -32599,6 +32742,8 @@ snapshots:
 
   imurmurhash@0.1.4: {}
 
+  indent-string@5.0.0: {}
+
   inherits@2.0.4: {}
 
   ini@1.3.8: {}
@@ -32607,6 +32752,41 @@ snapshots:
     dependencies:
       tslib: 2.8.1
 
+  ink@7.1.1(@types/react@19.3.0)(react-devtools-core@6.1.5)(react@19.2.3):
+    dependencies:
+      '@alcalzone/ansi-tokenize': 0.3.1
+      ansi-escapes: 7.3.0
+      ansi-styles: 6.2.3
+      auto-bind: 5.0.1
+      chalk: 5.6.2
+      cli-boxes: 4.0.1
+      cli-cursor: 4.0.0
+      cli-truncate: 6.1.1
+      code-excerpt: 4.0.0
+      es-toolkit: 1.52.0
+      indent-string: 5.0.0
+      is-in-ci: 2.0.0
+      patch-console: 2.0.0
+      react: 19.2.3
+      react-reconciler: 0.33.0(react@19.2.3)
+      scheduler: 0.27.0
+      signal-exit: 3.0.7
+      slice-ansi: 9.0.1
+      stack-utils: 2.0.6
+      string-width: 8.2.2
+      terminal-size: 4.0.1
+      type-fest: 5.10.0
+      widest-line: 6.0.0
+      wrap-ansi: 10.0.2
+      ws: 8.21.3
+      yoga-layout: 3.2.1
+    optionalDependencies:
+      '@types/react': 19.3.0
+      react-devtools-core: 6.1.5
+    transitivePeerDependencies:
+      - bufferutil
+      - utf-8-validate
+
   inline-style-parser@0.1.1: {}
 
   inline-style-parser@0.2.7: {}
@@ -32715,7 +32895,7 @@ snapshots:
 
   is-fullwidth-code-point@5.1.0:
     dependencies:
-      get-east-asian-width: 1.6.0
+      get-east-asian-width: 1.7.0
 
   is-glob@4.0.3:
     dependencies:
@@ -32727,6 +32907,8 @@ snapshots:
     dependencies:
       html-tags: 3.3.1
 
+  is-in-ci@2.0.0: {}
+
   is-in-ssh@1.0.0: {}
 
   is-inside-container@1.0.0:
@@ -33401,7 +33583,7 @@ snapshots:
       ansi-escapes: 7.3.0
       cli-cursor: 5.0.0
       slice-ansi: 7.1.2
-      strip-ansi: 7.1.2
+      strip-ansi: 7.2.0
       wrap-ansi: 9.0.2
 
   loglevel@1.9.2: {}
@@ -35389,6 +35571,8 @@ snapshots:
 
   partial-json@0.1.7: {}
 
+  patch-console@2.0.0: {}
+
   path-browserify@1.0.1: {}
 
   path-exists@3.0.0: {}
@@ -36123,6 +36307,11 @@ snapshots:
       - supports-color
       - utf-8-validate
 
+  react-reconciler@0.33.0(react@19.2.3):
+    dependencies:
+      react: 19.2.3
+      scheduler: 0.27.0
+
   react-refresh@0.14.2: {}
 
   react-refresh@0.17.0: {}
@@ -36478,6 +36667,11 @@ snapshots:
       onetime: 5.1.2
       signal-exit: 3.0.7
 
+  restore-cursor@4.0.0:
+    dependencies:
+      onetime: 5.1.2
+      signal-exit: 3.0.7
+
   restore-cursor@5.1.0:
     dependencies:
       onetime: 7.0.0
@@ -37124,6 +37318,11 @@ snapshots:
       ansi-styles: 6.2.3
       is-fullwidth-code-point: 5.1.0
 
+  slice-ansi@9.0.1:
+    dependencies:
+      ansi-styles: 6.2.3
+      is-fullwidth-code-point: 5.1.0
+
   slugify@1.6.9: {}
 
   smart-buffer@4.2.0: {}
@@ -37220,6 +37419,10 @@ snapshots:
       cpu-features: 0.0.10
       nan: 2.27.0
 
+  stack-utils@2.0.6:
+    dependencies:
+      escape-string-regexp: 2.0.0
+
   stackback@0.0.2: {}
 
   stackframe@1.3.4: {}
@@ -37285,18 +37488,13 @@ snapshots:
     dependencies:
       eastasianwidth: 0.2.0
       emoji-regex: 9.2.2
-      strip-ansi: 7.1.2
+      strip-ansi: 7.2.0
 
   string-width@7.2.0:
     dependencies:
       emoji-regex: 10.6.0
-      get-east-asian-width: 1.6.0
-      strip-ansi: 7.1.2
-
-  string-width@8.2.1:
-    dependencies:
-      get-east-asian-width: 1.6.0
-      strip-ansi: 7.1.2
+      get-east-asian-width: 1.7.0
+      strip-ansi: 7.2.0
 
   string-width@8.2.2:
     dependencies:
@@ -37324,10 +37522,6 @@ snapshots:
     dependencies:
       ansi-regex: 5.0.1
 
-  strip-ansi@7.1.2:
-    dependencies:
-      ansi-regex: 6.2.2
-
   strip-ansi@7.2.0:
     dependencies:
       ansi-regex: 6.3.0
@@ -37524,6 +37718,8 @@ snapshots:
       ansi-escapes: 4.3.2
       supports-hyperlinks: 2.3.0
 
+  terminal-size@4.0.1: {}
+
   terser@5.44.1:
     dependencies:
       '@jridgewell/source-map': 0.3.11
@@ -37799,6 +37995,10 @@ snapshots:
 
   type-fest@2.19.0: {}
 
+  type-fest@5.10.0:
+    dependencies:
+      tagged-tag: 1.0.0
+
   type-fest@5.3.1:
     dependencies:
       tagged-tag: 1.0.0
@@ -38851,6 +39051,10 @@ snapshots:
     dependencies:
       string-width: 5.1.2
 
+  widest-line@6.0.0:
+    dependencies:
+      string-width: 8.2.2
+
   word-wrap@1.2.5: {}
 
   workerd@1.20260609.1:
@@ -38886,6 +39090,11 @@ snapshots:
       - bufferutil
       - utf-8-validate
 
+  wrap-ansi@10.0.2:
+    dependencies:
+      ansi-styles: 6.2.3
+      string-width: 8.2.2
+
   wrap-ansi@6.2.0:
     dependencies:
       ansi-styles: 4.3.0
@@ -38902,13 +39111,13 @@ snapshots:
     dependencies:
       ansi-styles: 6.2.3
       string-width: 5.1.2
-      strip-ansi: 7.1.2
+      strip-ansi: 7.2.0
 
   wrap-ansi@9.0.2:
     dependencies:
       ansi-styles: 6.2.3
       string-width: 7.2.0
-      strip-ansi: 7.1.2
+      strip-ansi: 7.2.0
 
   wrappy@1.0.2: {}
 
@@ -39016,6 +39225,8 @@ snapshots:
 
   yoctocolors@2.1.2: {}
 
+  yoga-layout@3.2.1: {}
+
   youch-core@0.3.3:
     dependencies:
       '@poppinss/exception': 1.2.3
diff --git a/testing/e2e/fixtures/harness/basic.json b/testing/e2e/fixtures/harness/basic.json
index 252c90de69..edf1a61780 100644
--- a/testing/e2e/fixtures/harness/basic.json
+++ b/testing/e2e/fixtures/harness/basic.json
@@ -1,20 +1,44 @@
 {
   "fixtures": [
     {
-      "match": { "userMessage": "[harness-turns] first" },
-      "response": { "content": "First answer." }
+      "match": {
+        "userMessage": "[harness-turns] first"
+      },
+      "response": {
+        "content": "First answer."
+      }
     },
     {
-      "match": { "userMessage": "[harness-turns] second" },
-      "response": { "content": "Second answer." }
+      "match": {
+        "userMessage": "[harness-turns] second"
+      },
+      "response": {
+        "content": "Second answer."
+      }
     },
     {
-      "match": { "userMessage": "[harness-agent] price vendor a" },
-      "response": { "content": "Vendor A costs 12 dollars." }
+      "match": {
+        "userMessage": "[harness-agent] price vendor a"
+      },
+      "response": {
+        "content": "Vendor A costs 12 dollars."
+      }
     },
     {
-      "match": { "userMessage": "[harness-agent] what did it cost?" },
-      "response": { "content": "It cost 12 dollars." }
+      "match": {
+        "userMessage": "[harness-agent] what did it cost?"
+      },
+      "response": {
+        "content": "It cost 12 dollars."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-protocol] hello"
+      },
+      "response": {
+        "content": "Hello over the harness protocol."
+      }
     }
   ]
 }
diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index 87b7a9edc4..5c3c381028 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -126,6 +126,7 @@ import { Route as ApiVideoStreamRouteImport } from './routes/api.video.stream'
 import { Route as ApiTtsStreamRouteImport } from './routes/api.tts.stream'
 import { Route as ApiTranscriptionStreamRouteImport } from './routes/api.transcription.stream'
 import { Route as ApiImageStreamRouteImport } from './routes/api.image.stream'
+import { Route as ApiHarnessProtocolSplatRouteImport } from './routes/api.harness-protocol.$'
 import { Route as ApiAudioStreamRouteImport } from './routes/api.audio.stream'
 
 const WebsocketAdapterRoute = WebsocketAdapterRouteImport.update({
@@ -739,6 +740,11 @@ const ApiImageStreamRoute = ApiImageStreamRouteImport.update({
   path: '/stream',
   getParentRoute: () => ApiImageRoute,
 } as any)
+const ApiHarnessProtocolSplatRoute = ApiHarnessProtocolSplatRouteImport.update({
+  id: '/api/harness-protocol/$',
+  path: '/api/harness-protocol/$',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiAudioStreamRoute = ApiAudioStreamRouteImport.update({
   id: '/stream',
   path: '/stream',
@@ -860,6 +866,7 @@ export interface FileRoutesByFullPath {
   '/api/world': typeof ApiWorldRoute
   '/$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
@@ -980,6 +987,7 @@ export interface FileRoutesByTo {
   '/api/world': typeof ApiWorldRoute
   '/$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
@@ -1101,6 +1109,7 @@ export interface FileRoutesById {
   '/api/world': typeof ApiWorldRoute
   '/$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
@@ -1223,6 +1232,7 @@ export interface FileRouteTypes {
     | '/api/world'
     | '/$provider/'
     | '/api/audio/stream'
+    | '/api/harness-protocol/$'
     | '/api/image/stream'
     | '/api/transcription/stream'
     | '/api/tts/stream'
@@ -1343,6 +1353,7 @@ export interface FileRouteTypes {
     | '/api/world'
     | '/$provider'
     | '/api/audio/stream'
+    | '/api/harness-protocol/$'
     | '/api/image/stream'
     | '/api/transcription/stream'
     | '/api/tts/stream'
@@ -1463,6 +1474,7 @@ export interface FileRouteTypes {
     | '/api/world'
     | '/$provider/'
     | '/api/audio/stream'
+    | '/api/harness-protocol/$'
     | '/api/image/stream'
     | '/api/transcription/stream'
     | '/api/tts/stream'
@@ -1583,6 +1595,7 @@ export interface RootRouteChildren {
   ApiWebMcpPageToolsRoute: typeof ApiWebMcpPageToolsRoute
   ApiWorldRoute: typeof ApiWorldRoute
   ProviderIndexRoute: typeof ProviderIndexRoute
+  ApiHarnessProtocolSplatRoute: typeof ApiHarnessProtocolSplatRoute
 }
 
 declare module '@tanstack/react-router' {
@@ -2406,6 +2419,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiImageStreamRouteImport
       parentRoute: typeof ApiImageRoute
     }
+    '/api/harness-protocol/$': {
+      id: '/api/harness-protocol/$'
+      path: '/api/harness-protocol/$'
+      fullPath: '/api/harness-protocol/$'
+      preLoaderRoute: typeof ApiHarnessProtocolSplatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/audio/stream': {
       id: '/api/audio/stream'
       path: '/stream'
@@ -2589,6 +2609,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiWebMcpPageToolsRoute: ApiWebMcpPageToolsRoute,
   ApiWorldRoute: ApiWorldRoute,
   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..50eddad947
--- /dev/null
+++ b/testing/e2e/src/routes/api.harness-protocol.$.ts
@@ -0,0 +1,57 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { defineAgent } from '@tanstack/ai'
+import {
+  createHarnessHandler,
+  createHarnessHost,
+  defineHarness,
+} from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { z } from 'zod'
+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.
+ */
+const hosts = new Map<string, ReturnType<typeof createHarnessHost>>()
+
+function handlerFor(request: Request) {
+  const testId = request.headers.get('x-test-id') ?? 'default'
+  const port = Number(request.headers.get('x-aimock-port') ?? '4010')
+  let host = hosts.get(testId)
+  if (!host) {
+    host = createHarnessHost({ persistence: memoryPersistence() })
+    hosts.set(testId, host)
+  }
+  const harness = defineHarness({
+    name: 'e2e/protocol',
+    adapter: createTextAdapter('openai', undefined, port, testId).adapter,
+    agents: [
+      defineAgent({
+        name: 'echo',
+        description: 'Echoes its input',
+        inputSchema: z.object({ text: z.string() }),
+        run: async (ctx) => ctx.input.text,
+      }),
+    ],
+    expose: { agents: ['echo'] },
+  })
+  return createHarnessHandler({
+    host,
+    harness,
+    authorize: (req) =>
+      req.headers.get('authorization') === 'Bearer e2e-token'
+        ? { id: 'e2e' }
+        : null,
+  })
+}
+
+export const Route = createFileRoute('/api/harness-protocol/$')({
+  server: {
+    handlers: {
+      GET: ({ request }) => handlerFor(request)(request),
+      POST: ({ request }) => handlerFor(request)(request),
+    },
+  },
+})
diff --git a/testing/e2e/tests/harness-protocol.spec.ts b/testing/e2e/tests/harness-protocol.spec.ts
new file mode 100644
index 0000000000..43c81f3d47
--- /dev/null
+++ b/testing/e2e/tests/harness-protocol.spec.ts
@@ -0,0 +1,83 @@
+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}`,
+        runId: 'client-run',
+        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.')
+    expect(events.at(-1).name).toBe('harness.operation.finished')
+  })
+
+  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-/)
+  })
+})

From 1eb4b7f584ded69c17b40dd211aba27984baaf6d Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 13:05:33 +0200
Subject: [PATCH 008/286] feat(ai-harness): commands, settings, auth, and
 first-party plugins

Plugins can return commands (defineCommand), settings (configOption),
extension point items, and a main-model pick. The setup context adds
collect, typed events, persisted plugin state, settings, credentials, and a
session API with ask, prompt, transcript, and setConfig. The session adds
command, commands, setConfig, config, answer, and inspect, and the protocol
accepts command, answer, and config inputs.

Auth: oauthConnector adds connect/disconnect commands and gives tools a
fresh token. The OAuth runner does PKCE S256 with a single-use loopback on
127.0.0.1, and device-code sign-in. Missing credentials emit
harness.auth_required. ai-persistence adds the optional credentials store
and compare-and-set on the memory metadata store.

First-party plugins at @tanstack/ai-harness/plugins: permissions with modes,
workspaceTools, todos, modelPicker, projectInstructions, fileCommands,
compact, and usage. The CLI runs plugin commands, /config, /connect, answers
questions, and opens sign-in links.
---
 .changeset/harness-p3-plugins.md              |  15 +
 docs/config.json                              |  15 +
 docs/harness/auth.md                          | 101 ++++
 docs/harness/cli.md                           |   9 +-
 docs/harness/coding-agent.md                  |  97 ++++
 docs/harness/plugins.md                       | 156 ++++++
 packages/ai-harness-cli/src/commands.ts       | 130 ++++-
 packages/ai-harness-cli/src/interactive.tsx   |  23 +-
 packages/ai-harness-cli/src/lines.ts          |   7 +
 packages/ai-harness-cli/src/session-view.ts   |  60 ++-
 packages/ai-harness-cli/tests/cli.test.ts     |  74 ++-
 packages/ai-harness/package.json              |   4 +
 packages/ai-harness/src/auth.ts               |  67 +++
 packages/ai-harness/src/commands.ts           |  84 ++++
 packages/ai-harness/src/config.ts             |  88 ++++
 packages/ai-harness/src/connectors.ts         |  95 ++++
 packages/ai-harness/src/extensions.ts         |  40 ++
 packages/ai-harness/src/first-party/files.ts  |  92 ++++
 packages/ai-harness/src/first-party/index.ts  |  19 +
 .../src/first-party/model-picker.ts           |  62 +++
 .../ai-harness/src/first-party/permissions.ts | 150 ++++++
 .../src/first-party/session-tools.ts          | 115 +++++
 packages/ai-harness/src/first-party/todos.ts  | 100 ++++
 .../ai-harness/src/first-party/workspace.ts   | 275 +++++++++++
 packages/ai-harness/src/host.ts               |   8 +-
 packages/ai-harness/src/index.ts              |  35 ++
 packages/ai-harness/src/oauth.ts              | 298 +++++++++++
 packages/ai-harness/src/plugins.ts            | 214 +++++++-
 packages/ai-harness/src/protocol.ts           |  28 ++
 packages/ai-harness/src/session.ts            | 465 +++++++++++++++++-
 packages/ai-harness/src/types.ts              |   8 +
 packages/ai-harness/tests/auth.test.ts        | 273 ++++++++++
 packages/ai-harness/tests/extensions.test.ts  | 330 +++++++++++++
 packages/ai-harness/tests/first-party.test.ts | 218 ++++++++
 packages/ai-harness/tests/helpers.ts          |  12 +-
 packages/ai-harness/vite.config.ts            |   2 +-
 packages/ai-persistence/src/index.ts          |   4 +
 packages/ai-persistence/src/memory.ts         |  92 +++-
 .../ai-persistence/src/testkit/conformance.ts |  71 +++
 packages/ai-persistence/src/types.ts          |  36 ++
 packages/ai-persistence/tests/memory.test.ts  |   1 +
 .../tests/persistence-types.test-d.ts         |   2 +
 .../activities/chat/middleware/metadata.ts    |  21 +
 .../e2e/src/routes/api.harness-protocol.$.ts  |  24 +
 testing/e2e/tests/harness-protocol.spec.ts    |  29 ++
 45 files changed, 4012 insertions(+), 37 deletions(-)
 create mode 100644 .changeset/harness-p3-plugins.md
 create mode 100644 docs/harness/auth.md
 create mode 100644 docs/harness/coding-agent.md
 create mode 100644 docs/harness/plugins.md
 create mode 100644 packages/ai-harness/src/auth.ts
 create mode 100644 packages/ai-harness/src/commands.ts
 create mode 100644 packages/ai-harness/src/config.ts
 create mode 100644 packages/ai-harness/src/connectors.ts
 create mode 100644 packages/ai-harness/src/extensions.ts
 create mode 100644 packages/ai-harness/src/first-party/files.ts
 create mode 100644 packages/ai-harness/src/first-party/index.ts
 create mode 100644 packages/ai-harness/src/first-party/model-picker.ts
 create mode 100644 packages/ai-harness/src/first-party/permissions.ts
 create mode 100644 packages/ai-harness/src/first-party/session-tools.ts
 create mode 100644 packages/ai-harness/src/first-party/todos.ts
 create mode 100644 packages/ai-harness/src/first-party/workspace.ts
 create mode 100644 packages/ai-harness/src/oauth.ts
 create mode 100644 packages/ai-harness/tests/auth.test.ts
 create mode 100644 packages/ai-harness/tests/extensions.test.ts
 create mode 100644 packages/ai-harness/tests/first-party.test.ts

diff --git a/.changeset/harness-p3-plugins.md b/.changeset/harness-p3-plugins.md
new file mode 100644
index 0000000000..54c883daa5
--- /dev/null
+++ b/.changeset/harness-p3-plugins.md
@@ -0,0 +1,15 @@
+---
+'@tanstack/ai-harness': minor
+'@tanstack/ai-harness-cli': minor
+'@tanstack/ai-persistence': minor
+'@tanstack/ai': minor
+---
+
+Harness plugins can now do everything a Claude Code style agent needs.
+
+- **Plugin API.** `setup` can return `commands` (`defineCommand`, with typed input), `config` (`configOption.select`, `.boolean`, `.text`, `.number`), `contribute` for extension points (`createExtensionPoint`), and `adapter` to pick the main model. The setup context adds `collect`, typed events (`createPluginEvent`, `emit`, `on`), `state` (saved in the metadata store, published as `STATE_SNAPSHOT`), `config`, `credentials`, and `session` (`ask`, `prompt`, `transcript`, `setConfig`). Prompts can be functions called for each turn.
+- **Session.** `session.command`, `session.commands`, `session.setConfig`, `session.config`, `session.answer`, and `session.inspect`. The protocol accepts `command`, `answer`, and `config` inputs.
+- **Auth.** `oauthConnector` adds `connect:<id>` and `disconnect:<id>` commands and gives tools a fresh token. The OAuth runner (`loopbackLogin`, `deviceLogin`, `createPkce`, `exchangeCode`, `refreshCredential`) uses PKCE S256 and a single-use loopback on `127.0.0.1`. Tools that need a missing credential emit `harness.auth_required`.
+- **First-party plugins** in `@tanstack/ai-harness/plugins`: `permissions` (with `default`, `plan`, `acceptEdits`, and `bypass` modes and the `PermissionRules` extension point), `workspaceTools`, `todos`, `modelPicker`, `projectInstructions`, `fileCommands`, `compact`, and `usage`.
+- **`@tanstack/ai-persistence`** adds the optional `credentials` store (`CredentialStore`, `defineCredentialStore`) and compare-and-set on the memory metadata store. **`@tanstack/ai`** adds optional `getVersioned` and `setIf` to `MetadataStore`.
+- **CLI.** Plugin commands, `/config`, `/connect`, and `/disconnect`. Questions from plugins are answered on the next line. Sign-in links open in the browser.
diff --git a/docs/config.json b/docs/config.json
index 4dac967f22..784c711a32 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -823,6 +823,21 @@
           "label": "Durable sessions",
           "to": "harness/durable-sessions",
           "addedAt": "2026-09-26"
+        },
+        {
+          "label": "Write a plugin",
+          "to": "harness/plugins",
+          "addedAt": "2026-09-26"
+        },
+        {
+          "label": "Build a coding agent",
+          "to": "harness/coding-agent",
+          "addedAt": "2026-09-26"
+        },
+        {
+          "label": "Auth and connectors",
+          "to": "harness/auth",
+          "addedAt": "2026-09-26"
         }
       ]
     },
diff --git a/docs/harness/auth.md b/docs/harness/auth.md
new file mode 100644
index 0000000000..90e38aab16
--- /dev/null
+++ b/docs/harness/auth.md
@@ -0,0 +1,101 @@
+---
+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',
+  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-5.6'),
+  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`.
+- 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.
+
+Set `login: 'device'` for SSH sessions, containers, and CI. The CLI then shows a code to enter on the service's page.
+
+If a tool runs before sign-in, it stops with a `harness.auth_required` event. The CLI shows which service to connect.
+
+## Keep credentials
+
+The host reads credentials from `stores.credentials`, keyed by the session's principal. Without it, credentials live in memory until the process stops.
+
+```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.
+
+## 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 session's principal.
+
+## 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.
diff --git a/docs/harness/cli.md b/docs/harness/cli.md
index a572a2bc02..9889069159 100644
--- a/docs/harness/cli.md
+++ b/docs/harness/cli.md
@@ -68,13 +68,20 @@ When stdin is a pipe, the CLI reads one message or command per line and waits fo
 
 ## Commands in the interactive UI
 
+For the session:
+
 - `/agents`: list the agents.
 - `/agent <name> {"json":"input"}`: run an agent in the background. When it is done, a new turn starts with its result.
+- `/config`: show the settings. `/config <key> <value>` changes one.
+- `/connect <id>` and `/disconnect <id>`: sign in to a connector, or out.
+
+For the running work:
+
 - `/cancel`: cancel the running turn.
 - `/status`: show what runs and what waits.
 - `/exit`: quit.
 
-When a turn stops for an approval, type `y` to approve or `n` to reject.
+Plugin commands (for example `/model` or `/todos`) show up in `/help`. When a turn stops for an approval or a plugin asks a question, type your answer. For yes-or-no questions, `y` approves and `n` refuses.
 
 ## What you have now
 
diff --git a/docs/harness/coding-agent.md b/docs/harness/coding-agent.md
new file mode 100644
index 0000000000..8a45100343
--- /dev/null
+++ b/docs/harness/coding-agent.md
@@ -0,0 +1,97 @@
+---
+title: Build a coding agent
+id: harness-coding-agent
+order: 6
+description: "Turn a harness into a coding agent with file tools, permission modes, a todo list, a model picker, project instructions, and /compact."
+keywords:
+  - tanstack ai
+  - harness
+  - coding agent
+  - permissions
+  - workspace tools
+---
+
+You want your own coding agent in the terminal: it reads and edits files, runs commands after you approve them, and keeps a todo list. The first-party plugins in `@tanstack/ai-harness/plugins` give you those parts. You pick the model and the rules.
+
+## 1. Define the agent
+
+```ts group=harness-coding-agent
+import { defineHarness } from '@tanstack/ai-harness'
+import {
+  compact,
+  fileCommands,
+  modelPicker,
+  permissions,
+  projectInstructions,
+  todos,
+  usage,
+  workspaceTools,
+} from '@tanstack/ai-harness/plugins'
+import { runCli } from '@tanstack/ai-harness-cli'
+import { openaiText } from '@tanstack/ai-openai'
+
+const root = process.cwd()
+const smart = openaiText('gpt-5.6')
+const fast = openaiText('gpt-5.6-luna')
+
+const coder = defineHarness({
+  name: 'acme/coder',
+  adapter: smart,
+  systemPrompts: ['You are a careful coding agent. Read before you edit.'],
+  plugins: () => [
+    permissions(),
+    workspaceTools({ root }),
+    todos(),
+    modelPicker({ choices: { smart, fast }, default: 'smart' }),
+    projectInstructions({ root }),
+    fileCommands({ dir: `${root}/.claude/commands` }),
+    compact({ adapter: fast }),
+    usage(),
+  ],
+})
+
+process.exitCode = await runCli(coder)
+```
+
+## 2. Run it
+
+Run the file with `npx tsx coder.ts`. Ask for a change. The agent reads files freely and asks before it writes a file or runs a command. Type `y` to allow a call or `n` to refuse it.
+
+## What each plugin adds
+
+| Plugin | Adds |
+|---|---|
+| `permissions()` | Asks before risky tool calls. `/mode` switches between `default`, `plan` (read-only), `acceptEdits` (edits run without asking), and `bypass`. |
+| `workspaceTools({ root })` | `read_file`, `write_file`, `edit_file`, `list_files`, `grep`, and `bash`, confined to `root`. |
+| `todos()` | A `todo_write` tool the model uses for multi-step work, and `/todos`. |
+| `modelPicker({ choices })` | `/model <name>` switches the model at the next turn. |
+| `projectInstructions({ root })` | Adds `AGENTS.md` and `CLAUDE.md` to the system prompt. |
+| `fileCommands({ dir })` | Each `.md` file becomes a slash command. `$ARGUMENTS` is replaced by what you type after it. |
+| `compact({ adapter })` | `/compact` replaces a long conversation with a summary. |
+| `usage()` | `/usage` shows the tokens of the session. |
+
+## Add your own rules
+
+Tool plugins add permission rules to the `PermissionRules` extension point. Add your own for any tool:
+
+```ts group=harness-coding-agent
+import { PermissionRules } from '@tanstack/ai-harness/plugins'
+import { definePlugin } from '@tanstack/ai-harness'
+
+export const noDeploys = definePlugin({
+  name: 'acme/no-deploys',
+  setup: () => ({
+    contribute: [PermissionRules.item({ tool: 'deploy_*', decision: 'deny' })],
+  }),
+})
+```
+
+A trailing `*` matches every tool that starts with the text. The last matching rule wins.
+
+The workspace tools run on your machine with your permissions. Run code you do not trust in a sandbox.
+
+## What you have now
+
+- A terminal coding agent with file tools, approvals, modes, a todo list, and a model picker.
+
+Next: connect the agent to GitHub and other services with [auth and connectors](./auth).
diff --git a/docs/harness/plugins.md b/docs/harness/plugins.md
new file mode 100644
index 0000000000..4e01346a91
--- /dev/null
+++ b/docs/harness/plugins.md
@@ -0,0 +1,156 @@
+---
+title: Write a harness plugin
+id: harness-plugins
+order: 5
+description: "Package tools, prompts, middleware, settings, commands, and state as a plugin that any harness can load."
+keywords:
+  - tanstack ai
+  - harness
+  - plugins
+  - definePlugin
+  - extension points
+---
+
+You built a feature for one harness, a todo list or a GitHub integration, and now you want it in every harness you ship. A plugin packages it: tools and prompts for the model, commands for the user, settings, and state that survives restarts.
+
+## The smallest plugin
+
+```ts group=harness-plugins
+import { definePlugin } from '@tanstack/ai-harness'
+
+export const today = definePlugin({
+  name: 'acme/today',
+  setup: () => ({ prompts: [`Today is ${new Date().toDateString()}.`] }),
+})
+```
+
+Add it with `plugins: () => [today]` in `defineHarness`. `setup` runs once per session.
+
+## What `setup` can return
+
+- `tools`: tools for the model, made with `toolDefinition`.
+- `prompts`: text for the system prompt. A function runs for each turn, so it can show current state.
+- `middleware`: chat middleware, the same type as `chat({ middleware })`.
+- `generationMiddleware`: middleware for the activities agents call.
+- `agents`: agents added to `session.agents`.
+- `commands`: user actions, see below.
+- `config`: session settings, see below.
+- `contribute`: items for another plugin's extension point.
+
+If two plugins add the same tool, command, setting, or prompt id, `host.open` fails and names both plugins.
+
+## Add commands and settings
+
+Commands are actions for the user, not the model: slash commands, buttons, dashboard actions. Settings are typed, saved per session, and apply at the next turn.
+
+```ts group=harness-plugins
+import { configOption, defineCommand } from '@tanstack/ai-harness'
+import { z } from 'zod'
+
+export const greeter = definePlugin({
+  name: 'acme/greeter',
+  setup: (ctx) => ({
+    config: {
+      tone: configOption.select({ options: ['plain', 'warm'], default: 'plain' }),
+    },
+    commands: {
+      greet: defineCommand({
+        description: 'Greet someone',
+        input: z.object({ name: z.string() }),
+        run: async ({ name }, command) => {
+          const sure = await command.session.ask({
+            message: `Greet ${name}?`,
+            schema: z.boolean(),
+          })
+          if (!sure) return 'Skipped.'
+          return ctx.config.get('tone') === 'warm' ? `Hello, dear ${name}!` : `Hello, ${name}.`
+        },
+      }),
+    },
+  }),
+})
+```
+
+- `session.command('greet', { name: 'Ada' })` runs the command. The input is checked against its schema.
+- `session.setConfig('tone', 'warm')` changes the setting. A value the option does not accept is rejected.
+- `ask` waits for `session.answer(questionId, value)`. The question shows up in `session.snapshot().pendingQuestions`, and the CLI prompts for it.
+
+## Keep state
+
+`ctx.state(initial)` gives a plugin its own state, saved in the metadata store. Clients see each change as an AG-UI `STATE_SNAPSHOT` event.
+
+```ts group=harness-plugins
+export const counter = definePlugin({
+  name: 'acme/counter',
+  setup: (ctx) => {
+    const state = ctx.state({ count: 0 })
+    return {
+      commands: {
+        bump: defineCommand({
+          description: 'Add one',
+          run: async () => (await state.update((current) => ({ count: current.count + 1 }))).count,
+        }),
+      },
+    }
+  },
+})
+```
+
+When two writers race, `update` runs your function again with fresh state.
+
+## Let plugins work together
+
+Three ways, from simple to loose:
+
+- **Capabilities.** One plugin declares `provides: [cap]` and calls `ctx.provide(cap, value)`. Another declares `requires: [cap]` and reads `ctx.get(cap)`. The provider must come first.
+- **Extension points.** One plugin reads a list, and others add to it in any order.
+- **Events.** `ctx.emit(event, value)` reaches every `ctx.on(event, handler)`.
+
+```ts group=harness-plugins
+import { createExtensionPoint, createPluginEvent } from '@tanstack/ai-harness'
+
+export const Checks = createExtensionPoint<{ name: string }>('acme/checks')
+export const checked = createPluginEvent<{ name: string }>('acme/checked')
+
+export const runner = definePlugin({
+  name: 'acme/check-runner',
+  setup: (ctx) => {
+    const checks = ctx.collect(Checks)
+    return {
+      commands: {
+        check: defineCommand({
+          description: 'Run every check',
+          run: () => {
+            for (const check of checks) ctx.emit(checked, check)
+            return checks.map((check) => check.name)
+          },
+        }),
+      },
+    }
+  },
+})
+
+export const lint = definePlugin({
+  name: 'acme/lint',
+  setup: () => ({ contribute: [Checks.item({ name: 'lint' })] }),
+})
+```
+
+Read `ctx.collect` at run time (in a command, a tool, or a middleware hook). During `setup`, later plugins have not added their items yet.
+
+## Clean up resources
+
+Open resources with `ctx.resources.acquire(open, close)`. They close when the session closes, newest first. If a later plugin fails in `setup`, every plugin set up so far is cleaned up, and no model request is sent.
+
+Set `lifetime: 'run'` to set a plugin up again for each turn.
+
+## See the plan
+
+`session.inspect()` lists the plugins in order, and who owns each tool, prompt, command, setting, and extension point item.
+
+## What you have now
+
+- A plugin that adds tools, prompts, commands, settings, and state to any harness.
+- Plugins that share services, lists, and events without knowing each other.
+
+Next: see the [first-party plugins](./coding-agent) that turn a harness into a coding agent.
diff --git a/packages/ai-harness-cli/src/commands.ts b/packages/ai-harness-cli/src/commands.ts
index 4c0ce10d28..3f5ef06fd7 100644
--- a/packages/ai-harness-cli/src/commands.ts
+++ b/packages/ai-harness-cli/src/commands.ts
@@ -5,14 +5,79 @@ export const HELP_TEXT = [
   'Commands:',
   '  /agents                  list the agents',
   '  /agent <name> [json]     run an agent in the background',
+  '  /config [key value]      show or change a setting',
+  '  /connect <id>            sign in to a connector (and /disconnect <id>)',
   '  /cancel                  cancel the running turn (or press Esc)',
   '  /status                  show the session status',
   '  /exit                    quit',
 ].join('\n')
 
+/** A command argument: JSON when it parses, else the text itself. */
+function parseArg(text: string): unknown {
+  if (text === '') return undefined
+  try {
+    return JSON.parse(text)
+  } catch {
+    return text
+  }
+}
+
+function show(value: unknown): string {
+  if (value === undefined) return 'Done.'
+  return typeof value === 'string' ? value : JSON.stringify(value, null, 2)
+}
+
+/**
+ * Turn the user's reply into an answer: `y`/`n` for yes-or-no questions,
+ * JSON when it parses, else the text.
+ */
+export function parseAnswer(reply: string, schema: unknown): unknown {
+  const text = reply.trim()
+  const isBoolean =
+    typeof schema === 'object' &&
+    schema !== null &&
+    'type' in schema &&
+    schema.type === 'boolean'
+  if (isBoolean && /^(y|yes)$/i.test(text)) return true
+  if (isBoolean && /^(n|no)$/i.test(text)) return false
+  return parseArg(text)
+}
+
+async function runCommand(
+  session: HarnessSession,
+  name: string,
+  input: unknown,
+): Promise<LineResult> {
+  const describe = (
+    outcome: { ok: true; value: unknown } | { ok: false; error: unknown },
+  ) =>
+    outcome.ok
+      ? show(outcome.value)
+      : `/${name} failed: ${outcome.error instanceof Error ? outcome.error.message : String(outcome.error)}`
+  const settled = Promise.resolve(
+    session.command(name, input).then(
+      (value) => ({ ok: true as const, value }),
+      (error: unknown) => ({ ok: false as const, error }),
+    ),
+  )
+  // A command that asks a question waits for the next line, so return now
+  // and print its result when it is done.
+  let done = false
+  void settled.then(() => {
+    done = true
+  })
+  while (!done) {
+    if (session.snapshot().pendingQuestions.length > 0) {
+      return { type: 'notice', text: '', later: settled.then(describe) }
+    }
+    await new Promise((resolve) => setTimeout(resolve, 10))
+  }
+  return { type: 'notice', text: describe(await settled) }
+}
+
 /** What the UI does after a line of input. */
 export type LineResult =
-  | { type: 'notice'; text: string }
+  | { type: 'notice'; text: string; later?: Promise<string> }
   | { type: 'exit' }
   | { type: 'sent' }
 
@@ -26,6 +91,20 @@ export async function handleLine(
 ): Promise<LineResult> {
   const text = line.trim()
   if (text === '') return { type: 'notice', text: '' }
+  const [question] = session.snapshot().pendingQuestions
+  if (question) {
+    const receipt = await session.answer(
+      question.questionId,
+      parseAnswer(text, question.schema),
+    )
+    return {
+      type: 'notice',
+      text:
+        receipt.status === 'rejected'
+          ? `Answer again: ${receipt.reason ?? ''}`
+          : '',
+    }
+  }
   if (!text.startsWith('/')) {
     if (session.snapshot().status === 'running') await session.steer(text)
     else void session.prompt(text)
@@ -34,8 +113,50 @@ export async function handleLine(
   const [name = '', ...rest] = text.slice(1).split(' ')
   const argText = rest.join(' ').trim()
   switch (name) {
-    case 'help':
-      return { type: 'notice', text: HELP_TEXT }
+    case 'help': {
+      const commands = session.commands()
+      return {
+        type: 'notice',
+        text:
+          commands.length === 0
+            ? HELP_TEXT
+            : `${HELP_TEXT}\nPlugin commands:\n${commands
+                .map((command) => `  /${command.name}  ${command.description}`)
+                .join('\n')}`,
+      }
+    }
+    case 'config': {
+      const [key = '', ...valueParts] = argText.split(' ')
+      if (!key) {
+        const entries = Object.entries(session.config())
+        return {
+          type: 'notice',
+          text:
+            entries.length === 0
+              ? 'This harness has no settings.'
+              : entries
+                  .map(
+                    ([name, entry]) =>
+                      `  ${name} = ${JSON.stringify(entry.value)}`,
+                  )
+                  .join('\n'),
+        }
+      }
+      const receipt = await session.setConfig(
+        key,
+        parseArg(valueParts.join(' ').trim()),
+      )
+      return {
+        type: 'notice',
+        text:
+          receipt.status === 'rejected'
+            ? `Not changed: ${receipt.reason ?? ''}`
+            : `${key} changed.`,
+      }
+    }
+    case 'connect':
+    case 'disconnect':
+      return runCommand(session, `${name}:${argText}`, undefined)
     case 'exit':
     case 'quit':
       return { type: 'exit' }
@@ -95,6 +216,9 @@ export async function handleLine(
       return { type: 'notice', text: `Started ${agentName} in the background.` }
     }
     default:
+      if (session.commands().some((command) => command.name === name)) {
+        return runCommand(session, name, parseArg(argText))
+      }
       return { type: 'notice', text: `Unknown command: /${name}. Type /help.` }
   }
 }
diff --git a/packages/ai-harness-cli/src/interactive.tsx b/packages/ai-harness-cli/src/interactive.tsx
index d05540ed51..fbfc35bb45 100644
--- a/packages/ai-harness-cli/src/interactive.tsx
+++ b/packages/ai-harness-cli/src/interactive.tsx
@@ -3,7 +3,12 @@ import { Box, Text, render, useApp, useInput } from 'ink'
 import { HARNESS_EVENTS } from '@tanstack/ai-harness'
 import { EventType } from '@tanstack/ai'
 import { handleLine } from './commands'
-import { applyEvent, approvalQuestion, resolveAll } from './session-view'
+import {
+  applyEvent,
+  approvalQuestion,
+  openUrl,
+  resolveAll,
+} from './session-view'
 import type {
   AnyHarness,
   HarnessSession,
@@ -51,11 +56,11 @@ function App({
       })) {
         setEntries((current) => applyEvent(current, entry).slice(-MAX_ENTRIES))
         const event = entry.event
-        if (
-          event.type === EventType.CUSTOM &&
-          (event.name === HARNESS_EVENTS.operationStarted ||
-            event.name === HARNESS_EVENTS.operationFinished)
-        ) {
+        if (event.type === EventType.CUSTOM) {
+          if (event.name === HARNESS_EVENTS.authRequired) {
+            const url = (event.value as { url?: unknown }).url
+            if (typeof url === 'string') openUrl(url)
+          }
           // Let the operation settle before reading the status.
           setTimeout(() => setSnapshot(session.snapshot()), 0)
         }
@@ -119,8 +124,10 @@ function App({
     })()
   })
 
-  const status =
-    snapshot.status === 'running'
+  const question = snapshot.pendingQuestions[0]
+  const status = question
+    ? `${question.message} (type your answer)`
+    : snapshot.status === 'running'
       ? 'working (Esc to cancel, Enter steers)'
       : snapshot.status === 'requires_action'
         ? approvalQuestion(snapshot.pendingInterrupts)
diff --git a/packages/ai-harness-cli/src/lines.ts b/packages/ai-harness-cli/src/lines.ts
index c16ff9e0ba..26cc914f8e 100644
--- a/packages/ai-harness-cli/src/lines.ts
+++ b/packages/ai-harness-cli/src/lines.ts
@@ -52,6 +52,7 @@ export async function runLines(
   })()
 
   const lines = createInterface({ input, crlfDelay: Infinity })
+  const pendingLater: Array<Promise<void>> = []
   for await (const line of lines) {
     const snapshot = session.snapshot()
     if (snapshot.status === 'requires_action') {
@@ -65,6 +66,11 @@ export async function runLines(
       if (result.type === 'exit') break
       if (result.type === 'notice' && result.text)
         stdout.write(`${result.text}\n`)
+      if (result.type === 'notice' && result.later) {
+        pendingLater.push(
+          result.later.then((text) => void stdout.write(`\n${text}\n`)),
+        )
+      }
     }
     await waitIdle(session)
     const after = session.snapshot()
@@ -73,6 +79,7 @@ export async function runLines(
     }
   }
   lines.close()
+  await Promise.allSettled(pendingLater)
   await waitIdle(session)
   reader.abort()
   await printing
diff --git a/packages/ai-harness-cli/src/session-view.ts b/packages/ai-harness-cli/src/session-view.ts
index 24325f072d..43df00f9bb 100644
--- a/packages/ai-harness-cli/src/session-view.ts
+++ b/packages/ai-harness-cli/src/session-view.ts
@@ -53,6 +53,41 @@ export function applyEvent(
       { kind: 'notice', text: 'Resumed a turn that a crash stopped.' },
     ]
   }
+  if (
+    event.type === EventType.CUSTOM &&
+    event.name === HARNESS_EVENTS.question
+  ) {
+    const value = event.value as { message?: unknown }
+    return [
+      ...entries,
+      { kind: 'notice', text: `? ${String(value.message ?? '')}` },
+    ]
+  }
+  if (
+    event.type === EventType.CUSTOM &&
+    event.name === HARNESS_EVENTS.authRequired
+  ) {
+    const value = event.value as {
+      connector?: unknown
+      url?: unknown
+      userCode?: unknown
+    }
+    const code =
+      typeof value.userCode === 'string'
+        ? ` and enter the code ${value.userCode}`
+        : ''
+    const where =
+      typeof value.url === 'string'
+        ? ` Open ${value.url}${code}.`
+        : ` Run /connect ${String(value.connector)}.`
+    return [
+      ...entries,
+      {
+        kind: 'notice',
+        text: `Sign in to ${String(value.connector)}.${where}`,
+      },
+    ]
+  }
   return entries
 }
 
@@ -70,6 +105,25 @@ export function resolveAll(
   return session.resolve(resume)
 }
 
+/** Open an http(s) URL in the default browser. No shell is involved. */
+export function openUrl(url: string): void {
+  if (!/^https?:\/\//.test(url)) return
+  void import('node:child_process').then(({ spawn }) => {
+    const [command, args] =
+      process.platform === 'win32'
+        ? // Not `cmd /c start`: cmd would read `&` in the URL as a command separator.
+          ['rundll32', ['url.dll,FileProtocolHandler', url]]
+        : process.platform === 'darwin'
+          ? ['open', [url]]
+          : ['xdg-open', [url]]
+    try {
+      spawn(command, args, { stdio: 'ignore', detached: true }).unref()
+    } catch {
+      // The notice still shows the URL.
+    }
+  })
+}
+
 /** A short question for the open interrupts. */
 export function approvalQuestion(interrupts: ReadonlyArray<Interrupt>): string {
   const names = interrupts.map(
@@ -78,10 +132,14 @@ export function approvalQuestion(interrupts: ReadonlyArray<Interrupt>): string {
   return `Approve ${names.join(', ')}? [y/n]`
 }
 
-/** Resolves when no chat turn runs or waits in the queue. */
+/**
+ * Resolves when no chat turn runs or waits in the queue, or when the
+ * session waits for an answer to a question.
+ */
 export async function waitIdle(session: HarnessSession): Promise<void> {
   while (true) {
     const snapshot = session.snapshot()
+    if (snapshot.pendingQuestions.length > 0) return
     const chatActive = snapshot.activeOperations.some(
       (operation) => operation.kind === 'chat',
     )
diff --git a/packages/ai-harness-cli/tests/cli.test.ts b/packages/ai-harness-cli/tests/cli.test.ts
index 645e5b9537..7b2b8649b5 100644
--- a/packages/ai-harness-cli/tests/cli.test.ts
+++ b/packages/ai-harness-cli/tests/cli.test.ts
@@ -1,7 +1,13 @@
 import { Readable } from 'node:stream'
 import { describe, expect, it, vi } from 'vitest'
 import { EventType, defineAgent, toolDefinition } from '@tanstack/ai'
-import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import {
+  configOption,
+  createHarnessHost,
+  defineCommand,
+  defineHarness,
+  definePlugin,
+} from '@tanstack/ai-harness'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { EXIT, parseCliArgs, runCli } from '../src'
 import { serve } from '../src/serve'
@@ -222,6 +228,72 @@ describe('line mode', () => {
   })
 })
 
+describe('plugin commands in line mode', () => {
+  it('runs plugin commands, answers questions, and changes settings', async () => {
+    const tools = definePlugin({
+      name: 'test/tools',
+      setup: (ctx) => ({
+        config: {
+          tone: configOption.select({
+            options: ['plain', 'warm'],
+            default: 'plain',
+          }),
+        },
+        commands: {
+          greet: defineCommand({
+            description: 'Greet someone',
+            run: (input: unknown) =>
+              `Hello, ${typeof input === 'object' && input !== null && 'name' in input ? String(input.name) : 'you'}!`,
+          }),
+          confirm: defineCommand({
+            description: 'Ask first',
+            run: async () => {
+              const sure = await ctx.session.ask({
+                message: 'Really?',
+                schema: { type: 'boolean' },
+              })
+              return sure === true ? 'Confirmed.' : 'Stopped.'
+            },
+          }),
+        },
+      }),
+    })
+    const { adapter } = scripted([])
+    const stdout = capture()
+    const input = Readable.from([
+      '/greet {"name":"Ada"}\n',
+      '/confirm\n',
+      'yes\n',
+      '/config tone warm\n',
+      '/config\n',
+      '/help\n',
+      '/exit\n',
+    ])
+    await runCli(
+      defineHarness({
+        name: 'test/plugin-lines',
+        adapter,
+        plugins: () => [tools],
+      }),
+      {
+        argv: [],
+        stdin: Object.assign(input, {
+          isTTY: false,
+        }) as unknown as NodeJS.ReadStream,
+        stdout,
+        stderr: capture(),
+        persistence: memoryPersistence(),
+      },
+    )
+    expect(stdout.text).toContain('Hello, Ada!')
+    expect(stdout.text).toContain('? Really?')
+    expect(stdout.text).toContain('Confirmed.')
+    expect(stdout.text).toContain('tone changed.')
+    expect(stdout.text).toContain('tone = "warm"')
+    expect(stdout.text).toContain('/greet  Greet someone')
+  })
+})
+
 describe('serve mode', () => {
   it('serves the session protocol and requires the token', async () => {
     const { adapter } = scripted([textTurn('served')])
diff --git a/packages/ai-harness/package.json b/packages/ai-harness/package.json
index fd59be8e31..01b208a614 100644
--- a/packages/ai-harness/package.json
+++ b/packages/ai-harness/package.json
@@ -33,6 +33,10 @@
     "./client": {
       "types": "./dist/esm/client.d.ts",
       "import": "./dist/esm/client.js"
+    },
+    "./plugins": {
+      "types": "./dist/esm/first-party/index.d.ts",
+      "import": "./dist/esm/first-party/index.js"
     }
   },
   "scripts": {
diff --git a/packages/ai-harness/src/auth.ts b/packages/ai-harness/src/auth.ts
new file mode 100644
index 0000000000..a41e8a01a2
--- /dev/null
+++ b/packages/ai-harness/src/auth.ts
@@ -0,0 +1,67 @@
+import type { Scope } from '@tanstack/ai'
+import type { Credential, CredentialStore } from '@tanstack/ai-persistence'
+
+/**
+ * Thrown when a tool or command needs a credential the user has not saved.
+ * The session publishes `harness.auth_required`, so a host can show the
+ * sign-in link or run `/connect`.
+ */
+export class AuthRequiredError extends Error {
+  readonly connector: string
+  readonly url: string | undefined
+  constructor(connector: string, url?: string) {
+    super(
+      url
+        ? `Sign in to ${connector} first: ${url}`
+        : `Sign in to ${connector} first. Run /connect ${connector}.`,
+    )
+    this.name = 'AuthRequiredError'
+    this.connector = connector
+    this.url = url
+  }
+}
+
+/** Credentials of the session's principal, as plugins see them. */
+export interface CredentialsAccess {
+  get: (id: string) => Promise<Credential | null>
+  /** Like `get`, but throws {@link AuthRequiredError} when the credential is missing. */
+  require: (id: string) => Promise<Credential>
+  set: (id: string, credential: Credential) => Promise<void>
+  delete: (id: string) => Promise<void>
+  list: () => Promise<
+    Array<{ id: string; type: Credential['type']; expiresAt?: number }>
+  >
+}
+
+/** Scope credentials to one principal and thread. */
+export function credentialsFor(
+  store: CredentialStore,
+  scope: Scope,
+  onMissing: (error: AuthRequiredError) => void,
+): CredentialsAccess {
+  return {
+    get: (id) => store.get(scope, id),
+    require: async (id) => {
+      const credential = await store.get(scope, id)
+      if (credential) return credential
+      const error = new AuthRequiredError(id)
+      onMissing(error)
+      throw error
+    },
+    set: (id, credential) => store.set(scope, id, credential),
+    delete: (id) => store.delete(scope, id),
+    list: () => store.list(scope),
+  }
+}
+
+/** Remove secret-looking values from a message before it reaches a model or a log. */
+export function scrubSecrets(
+  text: string,
+  secrets: ReadonlyArray<string>,
+): string {
+  let scrubbed = text
+  for (const secret of secrets) {
+    if (secret.length >= 6) scrubbed = scrubbed.split(secret).join('[redacted]')
+  }
+  return scrubbed
+}
diff --git a/packages/ai-harness/src/commands.ts b/packages/ai-harness/src/commands.ts
new file mode 100644
index 0000000000..86a48a872e
--- /dev/null
+++ b/packages/ai-harness/src/commands.ts
@@ -0,0 +1,84 @@
+import type { InferSchemaType, ModelMessage, SchemaInput } from '@tanstack/ai'
+import type { SessionSnapshot } from './session'
+import type { Principal, Receipt } from './types'
+
+/** A question a command asks the user. The host renders it from the schema. */
+export interface Question<TSchema extends SchemaInput | undefined = undefined> {
+  message: string
+  /** The answer's shape. Without one, the answer is any text. */
+  schema?: TSchema
+}
+
+export type AnswerOf<TSchema> = TSchema extends SchemaInput
+  ? InferSchemaType<TSchema>
+  : string
+
+/** The parts of the session a plugin can use. */
+export interface PluginSessionApi {
+  threadId: string
+  principal: Principal | undefined
+  snapshot: () => SessionSnapshot
+  /** Start a chat turn, as if the user typed `text`. */
+  prompt: (text: string) => void
+  /** The saved transcript. */
+  transcript: () => Promise<Array<ModelMessage>>
+  /** Replace the saved transcript (for example after a summary). */
+  replaceTranscript: (messages: Array<ModelMessage>) => Promise<void>
+  /**
+   * Ask the user and wait for the answer. Hosts show it (the CLI prompts,
+   * ACP shows an elicitation). Rejects when the session closes.
+   */
+  ask: <TSchema extends SchemaInput | undefined = undefined>(
+    question: Question<TSchema>,
+  ) => Promise<AnswerOf<TSchema>>
+  /**
+   * Tell clients that the user must sign in. Hosts show the link (the CLI
+   * opens the browser) or the device code.
+   */
+  authRequired: (info: {
+    connector: string
+    url?: string
+    userCode?: string
+  }) => void
+  /** Change a session setting, the same as a client. Applies at the next turn. */
+  setConfig: (key: string, value: unknown) => Promise<Receipt>
+}
+
+/** What a command handler receives besides its input. */
+export interface CommandContext {
+  signal: AbortSignal
+  session: PluginSessionApi
+}
+
+/** A user action: a slash command, a button, a dashboard action. Not a model tool. */
+export interface CommandDefinition<
+  TSchema extends SchemaInput | undefined = SchemaInput | undefined,
+> {
+  description: string
+  /** The input shape, checked before `run`. */
+  input?: TSchema
+  run: (
+    input: TSchema extends SchemaInput ? InferSchemaType<TSchema> : undefined,
+    ctx: CommandContext,
+  ) => unknown
+}
+
+/** A command with any input type. */
+export type AnyCommand = CommandDefinition<any>
+
+/**
+ * Define a command with a typed input.
+ *
+ * @example
+ * ```ts
+ * const clear = defineCommand({
+ *   description: 'Remove every todo',
+ *   run: async () => ({ removed: await db.clear() }),
+ * })
+ * ```
+ */
+export function defineCommand<
+  const TSchema extends SchemaInput | undefined = undefined,
+>(command: CommandDefinition<TSchema>): CommandDefinition<TSchema> {
+  return command
+}
diff --git a/packages/ai-harness/src/config.ts b/packages/ai-harness/src/config.ts
new file mode 100644
index 0000000000..1ae460642f
--- /dev/null
+++ b/packages/ai-harness/src/config.ts
@@ -0,0 +1,88 @@
+/**
+ * A session setting a plugin declares, for example the model or the
+ * thinking level. Hosts render it from this description (a picker in the
+ * CLI, `configOptions` in ACP). A change applies at the next turn.
+ */
+export type ConfigOption =
+  | {
+      type: 'select'
+      options: ReadonlyArray<string>
+      default: string
+      description?: string
+      /** ACP category, for example `'model'` or `'thought_level'`. */
+      category?: string
+    }
+  | { type: 'boolean'; default: boolean; description?: string }
+  | { type: 'text'; default: string; description?: string }
+  | {
+      type: 'number'
+      default: number
+      min?: number
+      max?: number
+      description?: string
+    }
+
+type Without<T, K extends keyof T> = Omit<T, K>
+type Option<TType extends ConfigOption['type']> = Extract<
+  ConfigOption,
+  { type: TType }
+>
+
+/** Helpers to declare {@link ConfigOption}s. */
+export const configOption = {
+  select: (option: Without<Option<'select'>, 'type'>): Option<'select'> => {
+    if (!option.options.includes(option.default)) {
+      throw new Error(
+        `configOption.select: the default "${option.default}" is not an option.`,
+      )
+    }
+    return { type: 'select', ...option }
+  },
+  boolean: (option: Without<Option<'boolean'>, 'type'>): Option<'boolean'> => ({
+    type: 'boolean',
+    ...option,
+  }),
+  text: (option: Without<Option<'text'>, 'type'>): Option<'text'> => ({
+    type: 'text',
+    ...option,
+  }),
+  number: (option: Without<Option<'number'>, 'type'>): Option<'number'> => ({
+    type: 'number',
+    ...option,
+  }),
+}
+
+/** Check a value for an option. Returns the value, or throws with a reason. */
+export function checkConfigValue(
+  key: string,
+  option: ConfigOption,
+  value: unknown,
+): unknown {
+  const fail = (expected: string): never => {
+    throw new Error(
+      `Config "${key}" expects ${expected}, got ${JSON.stringify(value)}.`,
+    )
+  }
+  switch (option.type) {
+    case 'select':
+      if (typeof value !== 'string' || !option.options.includes(value)) {
+        fail(`one of ${option.options.join(', ')}`)
+      }
+      return value
+    case 'boolean':
+      if (typeof value !== 'boolean') fail('true or false')
+      return value
+    case 'text':
+      if (typeof value !== 'string') fail('text')
+      return value
+    case 'number': {
+      if (typeof value !== 'number' || !Number.isFinite(value))
+        return fail('a number')
+      if (option.min !== undefined && value < option.min)
+        fail(`a number >= ${option.min}`)
+      if (option.max !== undefined && value > option.max)
+        fail(`a number <= ${option.max}`)
+      return value
+    }
+  }
+}
diff --git a/packages/ai-harness/src/connectors.ts b/packages/ai-harness/src/connectors.ts
new file mode 100644
index 0000000000..7b5aad47cd
--- /dev/null
+++ b/packages/ai-harness/src/connectors.ts
@@ -0,0 +1,95 @@
+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
+  /** `'loopback'` (default) opens a browser here. `'device'` shows a code to enter elsewhere. */
+  login?: 'loopback' | 'device'
+  /**
+   * The tools of this service. Call `token()` inside a tool: it returns a
+   * fresh access token, or pauses with `auth_required` before sign-in.
+   */
+  tools?: (token: () => 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',
+ *   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 (): Promise<string> => {
+        let credential = await ctx.credentials.require(id)
+        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}`,
+            run: async () => {
+              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 ctx.credentials.set(id, credential)
+              return `Connected to ${label}.`
+            },
+          }),
+          [`disconnect:${id}`]: defineCommand({
+            description: `Sign out of ${label}`,
+            run: async () => {
+              await ctx.credentials.delete(id)
+              return `Disconnected from ${label}.`
+            },
+          }),
+        },
+      }
+    },
+  })
+}
diff --git a/packages/ai-harness/src/extensions.ts b/packages/ai-harness/src/extensions.ts
new file mode 100644
index 0000000000..3181822750
--- /dev/null
+++ b/packages/ai-harness/src/extensions.ts
@@ -0,0 +1,40 @@
+/**
+ * A list one plugin reads and other plugins add to, in any order. For
+ * example, a permissions plugin reads rules that tool plugins contribute.
+ *
+ * @example
+ * ```ts
+ * export const PermissionRules = createExtensionPoint<PermissionRule>('acme/permission-rules')
+ * // a tool plugin: contribute: [PermissionRules.item({ tool: 'write_file', decision: 'ask' })]
+ * // the permissions plugin, at run time: ctx.collect(PermissionRules)
+ * ```
+ */
+export interface ExtensionPoint<T> {
+  readonly name: string
+  item: (value: T) => ExtensionItem<T>
+}
+
+/** One contribution to an extension point. */
+export interface ExtensionItem<T = unknown> {
+  readonly point: string
+  readonly value: T
+}
+
+export function createExtensionPoint<T>(name: string): ExtensionPoint<T> {
+  return { name, item: (value) => ({ point: name, value }) }
+}
+
+/**
+ * A typed plugin event. `ctx.emit(event, value)` sends it to every
+ * `ctx.on(event, handler)` in the session, and clients see it as a
+ * `harness.plugin.event` CUSTOM event.
+ */
+export interface PluginEvent<T> {
+  readonly name: string
+  /** Type only. Never read at runtime. */
+  readonly __type?: T
+}
+
+export function createPluginEvent<T>(name: string): PluginEvent<T> {
+  return { name }
+}
diff --git a/packages/ai-harness/src/first-party/files.ts b/packages/ai-harness/src/first-party/files.ts
new file mode 100644
index 0000000000..2b9fa2e0d2
--- /dev/null
+++ b/packages/ai-harness/src/first-party/files.ts
@@ -0,0 +1,92 @@
+import { readFile, readdir } from 'node:fs/promises'
+import { basename, extname, resolve } from 'node:path'
+import { defineCommand } from '../commands'
+import { definePlugin } from '../plugins'
+import type { AnyCommand } from '../commands'
+
+async function readIfPresent(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Add project instruction files (AGENTS.md, CLAUDE.md) to the system prompt,
+ * read once when the session opens.
+ */
+export function projectInstructions(options: {
+  root: string
+  files?: ReadonlyArray<string>
+}) {
+  const files = options.files ?? ['AGENTS.md', 'CLAUDE.md']
+  return definePlugin({
+    name: 'tanstack/project-instructions',
+    setup: async () => {
+      const found: Array<string> = []
+      for (const file of files) {
+        const text = await readIfPresent(resolve(options.root, file))
+        if (text?.trim())
+          found.push(`Project instructions from ${file}:\n${text.trim()}`)
+      }
+      return { prompts: found }
+    },
+  })
+}
+
+/** Split `---` frontmatter from a Markdown file. */
+function splitFrontmatter(text: string): {
+  description?: string
+  body: string
+} {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text)
+  if (!match) return { body: text }
+  const description = /^description:\s*(.+)$/m.exec(match[1] ?? '')?.[1]?.trim()
+  return {
+    ...(description ? { description } : {}),
+    body: text.slice(match[0].length),
+  }
+}
+
+/**
+ * One command per Markdown file in `dir` (like `.claude/commands/*.md`).
+ * Running `/name args` sends the file as a prompt, with `$ARGUMENTS`
+ * replaced by the args.
+ */
+export function fileCommands(options: { dir: string }) {
+  return definePlugin({
+    name: 'tanstack/file-commands',
+    setup: async (ctx) => {
+      let names: Array<string> = []
+      try {
+        names = (await readdir(options.dir)).filter(
+          (file) => extname(file) === '.md',
+        )
+      } catch {
+        return {}
+      }
+      const commands: Record<string, AnyCommand> = {}
+      for (const file of names) {
+        const name = basename(file, '.md')
+        const { description, body } = splitFrontmatter(
+          await readFile(resolve(options.dir, file), 'utf8'),
+        )
+        commands[name] = defineCommand({
+          description: description ?? `Run ${file}`,
+          run: (input: unknown) => {
+            const args =
+              typeof input === 'string'
+                ? input
+                : input === undefined
+                  ? ''
+                  : JSON.stringify(input)
+            ctx.session.prompt(body.split('$ARGUMENTS').join(args).trim())
+            return `Sent /${name}.`
+          },
+        })
+      }
+      return { commands }
+    },
+  })
+}
diff --git a/packages/ai-harness/src/first-party/index.ts b/packages/ai-harness/src/first-party/index.ts
new file mode 100644
index 0000000000..0d49df50cc
--- /dev/null
+++ b/packages/ai-harness/src/first-party/index.ts
@@ -0,0 +1,19 @@
+// First-party plugins. This entry is Node only: some plugins use the file
+// system and the shell.
+export { modelPicker } from './model-picker'
+export {
+  PERMISSION_MODES,
+  PermissionRules,
+  decidePermission,
+  permissions,
+} from './permissions'
+export type {
+  PermissionDecision,
+  PermissionMode,
+  PermissionRule,
+} from './permissions'
+export { globToRegExp, workspaceTools } from './workspace'
+export { formatTodos, todos } from './todos'
+export type { Todo } from './todos'
+export { fileCommands, projectInstructions } from './files'
+export { compact, usage } from './session-tools'
diff --git a/packages/ai-harness/src/first-party/model-picker.ts b/packages/ai-harness/src/first-party/model-picker.ts
new file mode 100644
index 0000000000..18807debfa
--- /dev/null
+++ b/packages/ai-harness/src/first-party/model-picker.ts
@@ -0,0 +1,62 @@
+import { defineCommand } from '../commands'
+import { configOption } from '../config'
+import { definePlugin } from '../plugins'
+import type { AnyTextAdapter } from '@tanstack/ai'
+
+/**
+ * Switch the main model at the next turn with the `model` setting or the
+ * `/model <name>` command.
+ *
+ * @example
+ * ```ts
+ * modelPicker({
+ *   choices: { fast: openaiText('gpt-5.6-luna'), smart: openaiText('gpt-5.6') },
+ *   default: 'smart',
+ * })
+ * ```
+ */
+export function modelPicker(options: {
+  choices: Record<string, AnyTextAdapter>
+  default?: string
+}) {
+  const names = Object.keys(options.choices)
+  const fallback = options.default ?? names[0]
+  if (fallback === undefined)
+    throw new Error('modelPicker needs at least one choice.')
+  return definePlugin({
+    name: 'tanstack/model-picker',
+    setup: (ctx) => ({
+      config: {
+        model: configOption.select({
+          options: names,
+          default: fallback,
+          category: 'model',
+          description: 'The main model',
+        }),
+      },
+      adapter: () => {
+        const name = ctx.config.get('model')
+        return typeof name === 'string' ? options.choices[name] : undefined
+      },
+      commands: {
+        model: defineCommand({
+          description: `Show or switch the model (${names.join(', ')})`,
+          run: async (input: unknown) => {
+            const name =
+              typeof input === 'string'
+                ? input
+                : typeof input === 'object' && input !== null && 'name' in input
+                  ? String(input.name)
+                  : undefined
+            if (!name)
+              return `Model: ${String(ctx.config.get('model'))}. Choices: ${names.join(', ')}.`
+            if (!names.includes(name))
+              return `Unknown model "${name}". Choices: ${names.join(', ')}.`
+            await ctx.session.setConfig('model', name)
+            return `Model: ${name}. It applies at the next turn.`
+          },
+        }),
+      },
+    }),
+  })
+}
diff --git a/packages/ai-harness/src/first-party/permissions.ts b/packages/ai-harness/src/first-party/permissions.ts
new file mode 100644
index 0000000000..8f77eee0ed
--- /dev/null
+++ b/packages/ai-harness/src/first-party/permissions.ts
@@ -0,0 +1,150 @@
+import { defineCommand } from '../commands'
+import { configOption } from '../config'
+import { createExtensionPoint } from '../extensions'
+import { definePlugin } from '../plugins'
+
+export type PermissionDecision = 'allow' | 'ask' | 'deny'
+
+/** A rule for one tool. `kind` lets the modes treat edits and commands differently. */
+export interface PermissionRule {
+  /** A tool name. A trailing `*` matches a prefix, for example `git_*`. */
+  tool: string
+  decision: PermissionDecision
+  kind?: 'read' | 'edit' | 'execute'
+}
+
+/** Tool plugins add their rules here. `permissions()` reads them. */
+export const PermissionRules = createExtensionPoint<PermissionRule>(
+  'tanstack/permission-rules',
+)
+
+export const PERMISSION_MODES = [
+  'default',
+  'plan',
+  'acceptEdits',
+  'bypass',
+] as const
+export type PermissionMode = (typeof PERMISSION_MODES)[number]
+
+function matches(rule: PermissionRule, tool: string): boolean {
+  return rule.tool.endsWith('*')
+    ? tool.startsWith(rule.tool.slice(0, -1))
+    : rule.tool === tool
+}
+
+/** The decision for a tool in a mode. The last matching rule wins. */
+export function decidePermission(
+  rules: ReadonlyArray<PermissionRule>,
+  tool: string,
+  mode: PermissionMode,
+  fallback: PermissionDecision = 'allow',
+): PermissionDecision {
+  const rule = rules.findLast((candidate) => matches(candidate, tool))
+  const decision = rule?.decision ?? fallback
+  if (mode === 'bypass') return 'allow'
+  if (mode === 'plan') {
+    return rule?.kind === 'edit' ||
+      rule?.kind === 'execute' ||
+      decision !== 'allow'
+      ? 'deny'
+      : 'allow'
+  }
+  if (mode === 'acceptEdits' && rule?.kind === 'edit' && decision === 'ask')
+    return 'allow'
+  return decision
+}
+
+const PLAN_PROMPT =
+  'You are in plan mode. Do not change files or run commands. Read what you need, then describe your plan.'
+
+/**
+ * Check every tool call against permission rules, with a `mode` setting and a
+ * `/mode` command:
+ *
+ * - `default`: rules apply as written. `ask` asks the user.
+ * - `plan`: read-only. Edits and commands are denied.
+ * - `acceptEdits`: edits run without asking. Commands still ask.
+ * - `bypass`: everything runs.
+ */
+export function permissions(
+  options: {
+    rules?: ReadonlyArray<PermissionRule>
+    default?: PermissionDecision
+  } = {},
+) {
+  return definePlugin({
+    name: 'tanstack/permissions',
+    setup: (ctx) => {
+      const contributed = ctx.collect(PermissionRules)
+      const mode = (): PermissionMode => {
+        const value = ctx.config.get('mode')
+        return (
+          PERMISSION_MODES.find((candidate) => candidate === value) ?? 'default'
+        )
+      }
+      return {
+        config: {
+          mode: configOption.select({
+            options: PERMISSION_MODES,
+            default: 'default',
+            category: 'mode',
+            description: 'How tool calls are approved',
+          }),
+        },
+        prompts: [
+          {
+            id: 'tanstack/permissions:plan',
+            text: () => (mode() === 'plan' ? PLAN_PROMPT : ''),
+          },
+        ],
+        commands: {
+          mode: defineCommand({
+            description: `Show or switch the mode (${PERMISSION_MODES.join(', ')})`,
+            run: async (input: unknown) => {
+              const next = typeof input === 'string' ? input.trim() : ''
+              if (!next) return `Mode: ${mode()}.`
+              const receipt = await ctx.session.setConfig('mode', next)
+              return receipt.status === 'rejected'
+                ? `Unknown mode "${next}". Modes: ${PERMISSION_MODES.join(', ')}.`
+                : `Mode: ${next}.`
+            },
+          }),
+        },
+        middleware: [
+          {
+            name: 'tanstack/permissions',
+            onBeforeToolCall: async (_run, hook) => {
+              const rules = [...(options.rules ?? []), ...contributed]
+              const decision = decidePermission(
+                rules,
+                hook.toolName,
+                mode(),
+                options.default,
+              )
+              if (decision === 'allow') return undefined
+              if (decision === 'ask') {
+                const preview = JSON.stringify(hook.args ?? {}).slice(0, 300)
+                const answer: unknown = await ctx.session.ask({
+                  message: `Allow ${hook.toolName} ${preview}? (y/n)`,
+                })
+                const allowed =
+                  answer === true || /^y(es)?$/i.test(String(answer).trim())
+                if (allowed) return undefined
+              }
+              return {
+                type: 'skip',
+                result: {
+                  denied: true,
+                  reason:
+                    decision === 'ask'
+                      ? 'The user denied this tool call.'
+                      : `This tool is not allowed in ${mode()} mode.`,
+                },
+              }
+            },
+          },
+        ],
+      }
+    },
+  })
+}
diff --git a/packages/ai-harness/src/first-party/session-tools.ts b/packages/ai-harness/src/first-party/session-tools.ts
new file mode 100644
index 0000000000..02dbe6fb6c
--- /dev/null
+++ b/packages/ai-harness/src/first-party/session-tools.ts
@@ -0,0 +1,115 @@
+import { chat } from '@tanstack/ai'
+import { defineCommand } from '../commands'
+import { definePlugin } from '../plugins'
+import type { AnyTextAdapter, ModelMessage } from '@tanstack/ai'
+
+const SUMMARY_PROMPT =
+  'Summarize the conversation so far for yourself. Keep decisions, open tasks, file names, and facts you still need. Leave out small talk.'
+
+function textOf(message: ModelMessage): string {
+  if (typeof message.content === 'string') return message.content
+  if (Array.isArray(message.content)) {
+    return message.content
+      .map((part) =>
+        'text' in part && typeof part.text === 'string' ? part.text : '',
+      )
+      .join('')
+  }
+  return ''
+}
+
+/**
+ * `/compact`: replace a long transcript with a summary, so later turns send
+ * fewer tokens. The summary is written by `adapter`.
+ */
+export function compact(options: {
+  adapter: AnyTextAdapter
+  keepLast?: number
+}) {
+  return definePlugin({
+    name: 'tanstack/compact',
+    setup: (ctx) => ({
+      commands: {
+        compact: defineCommand({
+          description: 'Summarize the conversation to save tokens',
+          run: async () => {
+            const messages = await ctx.session.transcript()
+            const keep = options.keepLast ?? 0
+            if (messages.length <= keep + 2)
+              return 'The conversation is already short.'
+            const older = messages.slice(0, messages.length - keep)
+            const transcript = older
+              .map((message) => `${message.role}: ${textOf(message)}`)
+              .filter((line) => !line.endsWith(': '))
+              .join('\n')
+            const summary = await chat({
+              adapter: options.adapter,
+              messages: [
+                { role: 'user', content: `${SUMMARY_PROMPT}\n\n${transcript}` },
+              ],
+              stream: false,
+            })
+            await ctx.session.replaceTranscript([
+              {
+                role: 'user',
+                content: `Summary of our conversation so far:\n${summary}`,
+              },
+              {
+                role: 'assistant',
+                content: 'Understood. I will continue from this summary.',
+              },
+              ...messages.slice(messages.length - keep),
+            ])
+            return `Compacted ${older.length} messages into a summary.`
+          },
+        }),
+      },
+    }),
+  })
+}
+
+interface UsageTotals {
+  turns: number
+  promptTokens: number
+  completionTokens: number
+  totalTokens: number
+}
+
+/** Count tokens across the session. `/usage` shows the totals. */
+export function usage() {
+  return definePlugin({
+    name: 'tanstack/usage',
+    setup: (ctx) => {
+      const state = ctx.state<UsageTotals>({
+        turns: 0,
+        promptTokens: 0,
+        completionTokens: 0,
+        totalTokens: 0,
+      })
+      const show = (totals: UsageTotals) =>
+        `${totals.turns} model calls, ${totals.promptTokens} input tokens, ${totals.completionTokens} output tokens, ${totals.totalTokens} total.`
+      return {
+        middleware: [
+          {
+            name: 'tanstack/usage',
+            onUsage: async (_run, info) => {
+              await state.update((totals) => ({
+                turns: totals.turns + 1,
+                promptTokens: totals.promptTokens + (info.promptTokens ?? 0),
+                completionTokens:
+                  totals.completionTokens + (info.completionTokens ?? 0),
+                totalTokens: totals.totalTokens + (info.totalTokens ?? 0),
+              }))
+            },
+          },
+        ],
+        commands: {
+          usage: defineCommand({
+            description: 'Show token usage for this session',
+            run: async () => show(await state.get()),
+          }),
+        },
+      }
+    },
+  })
+}
diff --git a/packages/ai-harness/src/first-party/todos.ts b/packages/ai-harness/src/first-party/todos.ts
new file mode 100644
index 0000000000..eae2c2cce8
--- /dev/null
+++ b/packages/ai-harness/src/first-party/todos.ts
@@ -0,0 +1,100 @@
+import { toolDefinition } from '@tanstack/ai'
+import { defineCommand } from '../commands'
+import { definePlugin } from '../plugins'
+
+export interface Todo {
+  text: string
+  status: 'pending' | 'in_progress' | 'done'
+}
+
+function isTodo(value: unknown): value is Todo {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'text' in value &&
+    typeof value.text === 'string' &&
+    'status' in value &&
+    (value.status === 'pending' ||
+      value.status === 'in_progress' ||
+      value.status === 'done')
+  )
+}
+
+const MARK = { pending: '[ ]', in_progress: '[~]', done: '[x]' } as const
+
+export function formatTodos(items: ReadonlyArray<Todo>): string {
+  return items.map((item) => `${MARK[item.status]} ${item.text}`).join('\n')
+}
+
+/**
+ * A todo list the model keeps for multi-step work (like Claude Code's
+ * TodoWrite). The list is plugin state, so clients see it change and it
+ * survives restarts. `/todos` shows it.
+ */
+export function todos() {
+  return definePlugin({
+    name: 'tanstack/todos',
+    setup: async (ctx) => {
+      const state = ctx.state<{ items: Array<Todo> }>({ items: [] })
+      // The prompt runs for each turn, so keep a copy of the list at hand.
+      let current = (await state.get()).items
+      return {
+        tools: [
+          toolDefinition({
+            name: 'todo_write',
+            description:
+              'Replace the todo list. Use it for work with several steps. Mark one item in_progress at a time.',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                todos: {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      text: { type: 'string' },
+                      status: {
+                        type: 'string',
+                        enum: ['pending', 'in_progress', 'done'],
+                      },
+                    },
+                    required: ['text', 'status'],
+                  },
+                },
+              },
+              required: ['todos'],
+            },
+            replay: 'safe',
+          }).server(async (args: unknown) => {
+            const list =
+              typeof args === 'object' &&
+              args !== null &&
+              'todos' in args &&
+              Array.isArray(args.todos)
+                ? args.todos
+                : []
+            if (!list.every(isTodo))
+              throw new Error('Each todo needs text and a status.')
+            current = (await state.update(() => ({ items: list }))).items
+            return formatTodos(current) || 'The todo list is empty.'
+          }),
+        ],
+        prompts: [
+          {
+            id: 'tanstack/todos:list',
+            text: () =>
+              current.length > 0
+                ? `Current todo list:\n${formatTodos(current)}`
+                : '',
+          },
+        ],
+        commands: {
+          todos: defineCommand({
+            description: 'Show the todo list',
+            run: () => formatTodos(current) || 'The todo list is empty.',
+          }),
+        },
+      }
+    },
+  })
+}
diff --git a/packages/ai-harness/src/first-party/workspace.ts b/packages/ai-harness/src/first-party/workspace.ts
new file mode 100644
index 0000000000..98d9cb13aa
--- /dev/null
+++ b/packages/ai-harness/src/first-party/workspace.ts
@@ -0,0 +1,275 @@
+import { exec } from 'node:child_process'
+import { readFile, readdir, stat, writeFile, mkdir } from 'node:fs/promises'
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+import { toolDefinition } from '@tanstack/ai'
+import { definePlugin } from '../plugins'
+import { PermissionRules } from './permissions'
+
+const MAX_OUTPUT = 20_000
+const MAX_READ_LINES = 2000
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.nx', '.turbo'])
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function stringArg(args: unknown, key: string): string {
+  const value = isRecord(args) ? args[key] : undefined
+  if (typeof value === 'string') return value
+  throw new Error(`Argument "${key}" must be a string.`)
+}
+
+function optionalString(args: unknown, key: string): string | undefined {
+  const value = isRecord(args) ? args[key] : undefined
+  return typeof value === 'string' ? value : undefined
+}
+
+function clip(text: string): string {
+  return text.length > MAX_OUTPUT
+    ? `${text.slice(0, MAX_OUTPUT)}\n[${text.length - MAX_OUTPUT} more characters]`
+    : text
+}
+
+/** A simple glob to RegExp: `**` any path, `*` any name part, `?` one character. */
+export function globToRegExp(glob: string): RegExp {
+  let pattern = ''
+  for (let index = 0; index < glob.length; index += 1) {
+    const char = glob.charAt(index)
+    if (char === '*' && glob[index + 1] === '*') {
+      pattern += '.*'
+      index += glob[index + 2] === '/' ? 2 : 1
+    } else if (char === '*') pattern += '[^/]*'
+    else if (char === '?') pattern += '[^/]'
+    else pattern += char.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp(`^${pattern}$`)
+}
+
+/**
+ * File and shell tools for a coding agent, confined to `root`: `read_file`,
+ * `write_file`, `edit_file`, `list_files`, `grep`, and `bash`. Edits and
+ * `bash` ask for approval through `permissions()`.
+ *
+ * These tools run on this machine with the host's authority. Use a sandbox
+ * for code you do not trust.
+ */
+export function workspaceTools(options: {
+  root: string
+  bashTimeoutMs?: number
+}) {
+  const root = resolve(options.root)
+
+  const inRoot = (path: string): string => {
+    const full = isAbsolute(path) ? resolve(path) : resolve(root, path)
+    if (full !== root && !full.startsWith(root + sep)) {
+      throw new Error(`Path "${path}" is outside the workspace.`)
+    }
+    return full
+  }
+  const shown = (full: string) =>
+    relative(root, full).split(sep).join('/') || '.'
+
+  async function walk(dir: string, out: Array<string>): Promise<void> {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name))
+          await walk(resolve(dir, entry.name), out)
+      } else out.push(resolve(dir, entry.name))
+      if (out.length > 5000) return
+    }
+  }
+
+  const tools = [
+    toolDefinition({
+      name: 'read_file',
+      description:
+        'Read a text file in the workspace. Lines are numbered from 1.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          offset: { type: 'number', description: 'First line, from 1' },
+          limit: { type: 'number' },
+        },
+        required: ['path'],
+      },
+      replay: 'safe',
+    }).server(async (args: unknown) => {
+      const full = inRoot(stringArg(args, 'path'))
+      const lines = (await readFile(full, 'utf8')).split('\n')
+      const offset =
+        isRecord(args) && typeof args.offset === 'number'
+          ? Math.max(1, args.offset)
+          : 1
+      const limit =
+        isRecord(args) && typeof args.limit === 'number'
+          ? args.limit
+          : MAX_READ_LINES
+      return clip(
+        lines
+          .slice(offset - 1, offset - 1 + limit)
+          .map((line, index) => `${offset + index}\t${line}`)
+          .join('\n'),
+      )
+    }),
+    toolDefinition({
+      name: 'write_file',
+      description: 'Create or replace a file in the workspace.',
+      inputSchema: {
+        type: 'object',
+        properties: { path: { type: 'string' }, content: { type: 'string' } },
+        required: ['path', 'content'],
+      },
+    }).server(async (args: unknown) => {
+      const full = inRoot(stringArg(args, 'path'))
+      await mkdir(dirname(full), { recursive: true })
+      await writeFile(full, stringArg(args, 'content'), 'utf8')
+      return `Wrote ${shown(full)}.`
+    }),
+    toolDefinition({
+      name: 'edit_file',
+      description:
+        'Replace exact text in a file. `old` must appear once, unless `replaceAll` is true.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          old: { type: 'string' },
+          new: { type: 'string' },
+          replaceAll: { type: 'boolean' },
+        },
+        required: ['path', 'old', 'new'],
+      },
+    }).server(async (args: unknown) => {
+      const full = inRoot(stringArg(args, 'path'))
+      const before = await readFile(full, 'utf8')
+      const oldText = stringArg(args, 'old')
+      const newText = stringArg(args, 'new')
+      const count = before.split(oldText).length - 1
+      const replaceAll = isRecord(args) && args.replaceAll === true
+      if (count === 0) throw new Error('The old text is not in the file.')
+      if (count > 1 && !replaceAll) {
+        throw new Error(
+          `The old text appears ${count} times. Add context, or set replaceAll.`,
+        )
+      }
+      await writeFile(full, before.split(oldText).join(newText), 'utf8')
+      return `Edited ${shown(full)} (${replaceAll ? count : 1} change${count > 1 && replaceAll ? 's' : ''}).`
+    }),
+    toolDefinition({
+      name: 'list_files',
+      description:
+        'List files in the workspace, optionally matching a glob like `src/**/*.ts`.',
+      inputSchema: {
+        type: 'object',
+        properties: { pattern: { type: 'string' } },
+      },
+      replay: 'safe',
+    }).server(async (args: unknown) => {
+      const pattern = optionalString(args, 'pattern')
+      const files: Array<string> = []
+      await walk(root, files)
+      const regex = pattern ? globToRegExp(pattern) : undefined
+      const listed = files
+        .map(shown)
+        .filter((file) => !regex || regex.test(file))
+      return clip(listed.slice(0, 1000).join('\n') || 'No files.')
+    }),
+    toolDefinition({
+      name: 'grep',
+      description:
+        'Search file contents with a regular expression. Returns `file:line: text`.',
+      inputSchema: {
+        type: 'object',
+        properties: { pattern: { type: 'string' }, glob: { type: 'string' } },
+        required: ['pattern'],
+      },
+      replay: 'safe',
+    }).server(async (args: unknown) => {
+      const regex = new RegExp(stringArg(args, 'pattern'))
+      const glob = optionalString(args, 'glob')
+      const fileFilter = glob ? globToRegExp(glob) : undefined
+      const files: Array<string> = []
+      await walk(root, files)
+      const hits: Array<string> = []
+      for (const file of files) {
+        if (fileFilter && !fileFilter.test(shown(file))) continue
+        if ((await stat(file)).size > 1_000_000) continue
+        const lines = (await readFile(file, 'utf8')).split('\n')
+        lines.forEach((line, index) => {
+          if (hits.length < 200 && regex.test(line))
+            hits.push(`${shown(file)}:${index + 1}: ${line.trim()}`)
+        })
+        if (hits.length >= 200) break
+      }
+      return clip(hits.join('\n') || 'No matches.')
+    }),
+    toolDefinition({
+      name: 'bash',
+      description:
+        'Run a shell command in the workspace folder. Output is cut at 20,000 characters.',
+      inputSchema: {
+        type: 'object',
+        properties: { command: { type: 'string' } },
+        required: ['command'],
+      },
+      replay: 'never',
+    }).server(
+      (args: unknown) =>
+        new Promise<string>((done) => {
+          exec(
+            stringArg(args, 'command'),
+            {
+              cwd: root,
+              timeout: options.bashTimeoutMs ?? 120_000,
+              maxBuffer: 10 * 1024 * 1024,
+            },
+            (error, stdout, stderr) => {
+              const code = error && 'code' in error ? error.code : 0
+              done(
+                clip(
+                  `exit code: ${String(code ?? 0)}\n${stdout}${stderr ? `\nstderr:\n${stderr}` : ''}`,
+                ),
+              )
+            },
+          )
+        }),
+    ),
+  ]
+
+  return definePlugin({
+    name: 'tanstack/workspace-tools',
+    setup: () => ({
+      tools,
+      prompts: [`Your workspace is ${root}. Paths are relative to it.`],
+      contribute: [
+        PermissionRules.item({
+          tool: 'read_file',
+          decision: 'allow',
+          kind: 'read',
+        }),
+        PermissionRules.item({
+          tool: 'list_files',
+          decision: 'allow',
+          kind: 'read',
+        }),
+        PermissionRules.item({ tool: 'grep', decision: 'allow', kind: 'read' }),
+        PermissionRules.item({
+          tool: 'write_file',
+          decision: 'ask',
+          kind: 'edit',
+        }),
+        PermissionRules.item({
+          tool: 'edit_file',
+          decision: 'ask',
+          kind: 'edit',
+        }),
+        PermissionRules.item({
+          tool: 'bash',
+          decision: 'ask',
+          kind: 'execute',
+        }),
+      ],
+    }),
+  })
+}
diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
index dd8dafb6c7..9fb84539b7 100644
--- a/packages/ai-harness/src/host.ts
+++ b/packages/ai-harness/src/host.ts
@@ -3,6 +3,7 @@ import { HarnessSession } from './session'
 import type {
   AIPersistence,
   ChatTranscriptStores,
+  CredentialStore,
   InboxStore,
 } from '@tanstack/ai-persistence'
 import type { AnyHarness } from './define'
@@ -14,7 +15,7 @@ import type { Principal } from './types'
  * restart loses the ones not yet applied.
  */
 export type HarnessPersistence = AIPersistence<
-  ChatTranscriptStores & { inbox?: InboxStore }
+  ChatTranscriptStores & { inbox?: InboxStore; credentials?: CredentialStore }
 >
 
 export interface HarnessHostOptions {
@@ -68,6 +69,10 @@ export function createHarnessHost(
   // ponytail: a memory inbox when the stores have none. Pass `stores.inbox`
   // to keep accepted inputs across restarts.
   const inbox = persistence.stores.inbox ?? memoryPersistence().stores.inbox
+  // ponytail: memory credentials when the stores have none. Pass
+  // `stores.credentials` to keep sign-ins across restarts.
+  const credentials =
+    persistence.stores.credentials ?? memoryPersistence().stores.credentials
   const sessions = new Map<string, Promise<HarnessSession>>()
   const hostId = `host-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`
 
@@ -81,6 +86,7 @@ export function createHarnessHost(
           threadId,
           persistence,
           inbox,
+          credentials,
           hostId,
           ...(principal ? { principal } : {}),
           onClose: () => sessions.delete(key),
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index e1de83cca8..548768916e 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -15,8 +15,28 @@ export type {
   PluginLifetime,
   PluginPrompt,
   PluginSetupContext,
+  PluginState,
 } from './plugins'
 
+export { createExtensionPoint, createPluginEvent } from './extensions'
+export type { ExtensionItem, ExtensionPoint, PluginEvent } from './extensions'
+
+export { checkConfigValue, configOption } from './config'
+export type { ConfigOption } from './config'
+
+export { defineCommand } from './commands'
+export type {
+  AnswerOf,
+  AnyCommand,
+  CommandContext,
+  CommandDefinition,
+  PluginSessionApi,
+  Question,
+} from './commands'
+
+export { AuthRequiredError, scrubSecrets } from './auth'
+export type { CredentialsAccess } from './auth'
+
 export type {
   AgentInputOf,
   AgentRegistryView,
@@ -39,6 +59,7 @@ export type {
   AgentRunOptions,
   AgentStartOptions,
   DynamicAgentHandle,
+  SessionInspection,
   SessionSnapshot,
 } from './session'
 
@@ -75,3 +96,17 @@ export type {
 
 export { harnessText } from './harness-text'
 export type { HarnessTextOptions } from './harness-text'
+
+export {
+  buildAuthorizationUrl,
+  createPkce,
+  deviceLogin,
+  exchangeCode,
+  isExpired,
+  loopbackLogin,
+  refreshCredential,
+} from './oauth'
+export type { OAuthConfig } from './oauth'
+
+export { oauthConnector } from './connectors'
+export type { OAuthConnectorOptions } from './connectors'
diff --git a/packages/ai-harness/src/oauth.ts b/packages/ai-harness/src/oauth.ts
new file mode 100644
index 0000000000..8928322a76
--- /dev/null
+++ b/packages/ai-harness/src/oauth.ts
@@ -0,0 +1,298 @@
+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()
+
+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>'
+
+/**
+ * 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/plugins.ts b/packages/ai-harness/src/plugins.ts
index 550ec092fa..347dad4ac9 100644
--- a/packages/ai-harness/src/plugins.ts
+++ b/packages/ai-harness/src/plugins.ts
@@ -4,12 +4,16 @@ import type {
   AgentProduces,
   AnyChatMiddleware,
   AnyGenerationMiddleware,
+  AnyTextAdapter,
   AnyTool,
   Capability,
   CapabilityHandle,
-  SystemPrompt,
 } from '@tanstack/ai'
 import type { AgentRegistry, AgentRegistryView, AnyAgent } from './agents'
+import type { CredentialsAccess } from './auth'
+import type { AnyCommand, PluginSessionApi } from './commands'
+import type { ConfigOption } from './config'
+import type { ExtensionItem, ExtensionPoint, PluginEvent } from './extensions'
 
 /**
  * How long a plugin's `setup` result and resources live:
@@ -19,24 +23,55 @@ import type { AgentRegistry, AgentRegistryView, AnyAgent } from './agents'
  */
 export type PluginLifetime = 'session' | 'run'
 
-/** A prompt a plugin contributes. `id` must be unique in the session. */
+/**
+ * A prompt a plugin contributes. `id` must be unique in the session. A
+ * function `text` is called for each turn, so it can show current state.
+ */
 export interface PluginPrompt {
   id: string
-  text: string
+  text: string | (() => string)
 }
 
 /** What a plugin's `setup` returns. Every field is optional. */
 export interface PluginContributions {
   /** Tools for the main model. */
   tools?: ReadonlyArray<AnyTool>
-  /** System prompt text for every chat turn. */
-  prompts?: ReadonlyArray<string | PluginPrompt>
+  /** System prompt text for every chat turn. A function runs for each turn. */
+  prompts?: ReadonlyArray<string | (() => string) | PluginPrompt>
   /** Chat middleware, the same type as `chat({ middleware })`. */
   middleware?: ReadonlyArray<AnyChatMiddleware>
   /** Middleware for the activities agents call (`ctx.generateImage`, ...). */
   generationMiddleware?: ReadonlyArray<AnyGenerationMiddleware>
   /** Agents added to `session.agents`. */
   agents?: ReadonlyArray<AnyAgent>
+  /** User actions, keyed by name. Run with `session.command(name, input)`. */
+  commands?: Record<string, AnyCommand>
+  /** Session settings, keyed by name. Read with `ctx.config.get(name)`. */
+  config?: Record<string, ConfigOption>
+  /** Items for extension points that other plugins read. */
+  contribute?: ReadonlyArray<ExtensionItem>
+  /**
+   * Pick the main-loop adapter for the next turn, or return `undefined` to
+   * keep the harness adapter. The last plugin that returns one wins.
+   */
+  adapter?: () => AnyTextAdapter | undefined
+}
+
+/** Plugin state that survives restarts, stored in the metadata store. */
+export interface PluginState<T> {
+  get: () => Promise<T>
+  /** Change the state. On a write conflict, `change` runs again with fresh state. */
+  update: (change: (current: T) => T) => Promise<T>
+}
+
+/** What the session gives plugins. */
+export interface PluginServices {
+  emit: (plugin: string, name: string, value: unknown) => void
+  on: (name: string, handler: (value: unknown) => void) => () => void
+  config: { get: (key: string) => unknown }
+  state: <T>(plugin: string, initial: T) => PluginState<T>
+  credentials: CredentialsAccess
+  session: PluginSessionApi
 }
 
 /** What a plugin's `setup` receives. */
@@ -57,7 +92,23 @@ export interface PluginSetupContext {
   provide: <T>(capability: Capability<T>, value: T) => void
   /** The agents of this session (harness agents plus earlier plugins' agents). */
   agents: AgentRegistryView
-  session: { threadId: string }
+  /**
+   * The items other plugins contributed to `point`. The list fills while
+   * plugins set up, so read it at run time (in a tool, a command, or a
+   * middleware hook), not during `setup`.
+   */
+  collect: <T>(point: ExtensionPoint<T>) => ReadonlyArray<T>
+  /** Send a typed event to every plugin that listens, and to clients. */
+  emit: <T>(event: PluginEvent<T>, value: T) => void
+  /** Listen for a typed event. Returns a function that stops listening. */
+  on: <T>(event: PluginEvent<T>, handler: (value: T) => void) => () => void
+  /** This plugin's state, created with `initial` the first time. */
+  state: <T>(initial: T) => PluginState<T>
+  /** Session settings. A change applies at the next turn. */
+  config: { get: (key: string) => unknown }
+  /** Credentials of the session's principal. */
+  credentials: CredentialsAccess
+  session: PluginSessionApi
 }
 
 export interface PluginDefinition {
@@ -114,7 +165,24 @@ interface Owned<T> {
 /** Everything a set of mounted plugins contributes, plus its cleanup. */
 export interface MountedPlugins {
   tools: Array<AnyTool>
-  prompts: Array<SystemPrompt>
+  /** Strings, or functions to call for each turn. */
+  prompts: Array<string | (() => string)>
+  commands: Map<string, { command: AnyCommand; owner: string }>
+  config: Map<string, { option: ConfigOption; owner: string }>
+  /** Contributions to extension points, by point name. */
+  extensions: Map<string, Array<{ value: unknown; owner: string }>>
+  adapters: Array<() => AnyTextAdapter | undefined>
+  /** Who contributed what, for `session.inspect()`. */
+  owners: {
+    plugins: Array<{
+      name: string
+      lifetime: PluginLifetime
+      requires: Array<string>
+      provides: Array<string>
+    }>
+    tools: Array<{ name: string; owner: string }>
+    prompts: Array<{ id: string; owner: string }>
+  }
   middleware: Array<AnyChatMiddleware>
   generationMiddleware: Array<AnyGenerationMiddleware>
   /**
@@ -137,6 +205,45 @@ export interface MountEnvironment {
   harnessProvides: ReadonlyArray<CapabilityHandle>
   /** Capability values from an outer mount (session plugins, for a run mount). */
   inherited?: CapabilityValues
+  /** Names taken by an outer mount (session plugins, for a run mount). */
+  takenCommands?: ReadonlyMap<string, { owner: string }>
+  takenConfig?: ReadonlyMap<string, { owner: string }>
+  /** Extension items from an outer mount, visible to `collect`. */
+  inheritedExtensions?: ReadonlyMap<
+    string,
+    ReadonlyArray<{ value: unknown; owner: string }>
+  >
+  /** Session services. Tests of the mount alone can leave them out. */
+  services?: PluginServices
+}
+
+const unavailable = (what: string) => () => {
+  throw new Error(`${what} is only available inside a harness session.`)
+}
+
+const NO_SERVICES: PluginServices = {
+  emit: () => {},
+  on: () => () => {},
+  config: { get: () => undefined },
+  state: unavailable('ctx.state'),
+  credentials: {
+    get: unavailable('ctx.credentials'),
+    require: unavailable('ctx.credentials'),
+    set: unavailable('ctx.credentials'),
+    delete: unavailable('ctx.credentials'),
+    list: unavailable('ctx.credentials'),
+  },
+  session: {
+    threadId: '',
+    principal: undefined,
+    snapshot: unavailable('ctx.session'),
+    prompt: unavailable('ctx.session'),
+    transcript: unavailable('ctx.session'),
+    replaceTranscript: unavailable('ctx.session'),
+    ask: unavailable('ctx.session'),
+    authRequired: unavailable('ctx.session'),
+    setConfig: unavailable('ctx.session'),
+  },
 }
 
 /** Capability values provided by plugins, keyed by handle. */
@@ -198,8 +305,12 @@ function checkCapabilityOrder(
   }
 }
 
-function promptOf(prompt: string | PluginPrompt, owner: string, index: number) {
-  return typeof prompt === 'string'
+function promptOf(
+  prompt: string | (() => string) | PluginPrompt,
+  owner: string,
+  index: number,
+): PluginPrompt {
+  return typeof prompt === 'string' || typeof prompt === 'function'
     ? { id: `${owner}#${index}`, text: prompt }
     : prompt
 }
@@ -231,6 +342,14 @@ export async function mountPlugins(
   const prompts: Array<Owned<PluginPrompt>> = []
   const middleware: Array<AnyChatMiddleware> = []
   const generationMiddleware: Array<AnyGenerationMiddleware> = []
+  const commands = new Map<string, { command: AnyCommand; owner: string }>()
+  const config = new Map<string, { option: ConfigOption; owner: string }>()
+  const extensions = new Map<string, Array<{ value: unknown; owner: string }>>()
+  for (const [point, items] of env.inheritedExtensions ?? []) {
+    extensions.set(point, [...items])
+  }
+  const adapters: Array<() => AnyTextAdapter | undefined> = []
+  const services = env.services ?? NO_SERVICES
 
   try {
     for (const plugin of plugins) {
@@ -271,7 +390,29 @@ export async function mountPlugins(
           provided.add(handle)
         },
         agents: env.registry,
-        session: { threadId: env.threadId },
+        collect: <T>(point: ExtensionPoint<T>): ReadonlyArray<T> => {
+          let items = extensions.get(point.name)
+          if (!items) {
+            items = []
+            extensions.set(point.name, items)
+          }
+          const source = items
+          // A live view: items contributed after this call appear too.
+          return new Proxy<Array<T>>([], {
+            get: (_target, key) =>
+              Reflect.get(
+                source.map((item) => item.value as T),
+                key,
+              ),
+          })
+        },
+        emit: (event, value) => services.emit(plugin.name, event.name, value),
+        on: (event, handler) =>
+          services.on(event.name, (value) => handler(value as never)),
+        state: (initial) => services.state(plugin.name, initial),
+        config: services.config,
+        credentials: services.credentials,
+        session: services.session,
       })
       for (const handle of plugin.provides ?? []) {
         if (!provided.has(handle)) {
@@ -302,6 +443,35 @@ export async function mountPlugins(
       })
       middleware.push(...(contributions.middleware ?? []))
       generationMiddleware.push(...(contributions.generationMiddleware ?? []))
+      for (const [name, command] of Object.entries(
+        contributions.commands ?? {},
+      )) {
+        const clash = commands.get(name) ?? env.takenCommands?.get(name)
+        if (clash) {
+          throw new Error(
+            `Duplicate command "${name}": first owner ${clash.owner}, second owner ${plugin.name}.`,
+          )
+        }
+        commands.set(name, { command, owner: plugin.name })
+      }
+      for (const [key, option] of Object.entries(contributions.config ?? {})) {
+        const clash = config.get(key) ?? env.takenConfig?.get(key)
+        if (clash) {
+          throw new Error(
+            `Duplicate config key "${key}": first owner ${clash.owner}, second owner ${plugin.name}.`,
+          )
+        }
+        config.set(key, { option, owner: plugin.name })
+      }
+      for (const item of contributions.contribute ?? []) {
+        let items = extensions.get(item.point)
+        if (!items) {
+          items = []
+          extensions.set(item.point, items)
+        }
+        items.push({ value: item.value, owner: plugin.name })
+      }
+      if (contributions.adapter) adapters.push(contributions.adapter)
       for (const agent of contributions.agents ?? []) {
         env.registry.add(agent, plugin.name)
       }
@@ -350,6 +520,30 @@ export async function mountPlugins(
     prompts: prompts.map((entry) => entry.value.text),
     middleware,
     generationMiddleware,
+    commands,
+    config,
+    extensions,
+    adapters,
+    owners: {
+      plugins: plugins.map((plugin) => ({
+        name: plugin.name,
+        lifetime: plugin.lifetime ?? 'session',
+        requires: (plugin.requires ?? []).map(
+          (handle) => handle.capabilityName,
+        ),
+        provides: (plugin.provides ?? []).map(
+          (handle) => handle.capabilityName,
+        ),
+      })),
+      tools: tools.map((entry) => ({
+        name: entry.value.name,
+        owner: entry.owner,
+      })),
+      prompts: prompts.map((entry) => ({
+        id: entry.value.id,
+        owner: entry.owner,
+      })),
+    },
     capabilityBridge,
     values,
     dispose: () => (disposed ??= disposeAll(scopes)),
diff --git a/packages/ai-harness/src/protocol.ts b/packages/ai-harness/src/protocol.ts
index 3532454792..77a30fcf3d 100644
--- a/packages/ai-harness/src/protocol.ts
+++ b/packages/ai-harness/src/protocol.ts
@@ -41,6 +41,9 @@ const INPUT_OPS = new Set([
   'resolve',
   'agent',
   'cancel',
+  'command',
+  'answer',
+  'config',
 ])
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -71,6 +74,15 @@ export function parseHarnessInput(value: unknown): HarnessInput {
   if (value.op === 'agent' && typeof value.agent !== 'string') {
     throw new Error('Invalid input: agent needs an agent name.')
   }
+  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.')
+  }
   // The checks above cover every field the session reads.
   return value as HarnessInput
 }
@@ -134,6 +146,22 @@ export async function applyInput(
       return session.resolve(input.resume)
     case 'cancel':
       return session.cancel(input.operationId)
+    case 'command': {
+      const operation = session.command(input.name, input.input)
+      operation.then(
+        () => {},
+        () => {},
+      )
+      return {
+        inputId: operation.id,
+        status: 'accepted',
+        operationId: operation.id,
+      }
+    }
+    case 'answer':
+      return session.answer(input.questionId, input.value)
+    case 'config':
+      return session.setConfig(input.key, input.value)
     case 'agent': {
       const exposed = (harness.expose?.agents ?? []).includes(input.agent)
       if (!exposed) {
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 3e638d0f31..19c899c1e3 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -3,10 +3,13 @@ import {
   RUN_CANCEL_REASON,
   chat,
   compactForModel,
+  convertSchemaToJsonSchema,
   createSubagentId,
   runAgentStream,
   validateWithStandardSchema,
 } from '@tanstack/ai'
+import { credentialsFor } from './auth'
+import { checkConfigValue } from './config'
 import { withPersistence } from '@tanstack/ai-persistence'
 import { AgentRegistry } from './agents'
 import { SessionFeed } from './feed'
@@ -23,10 +26,18 @@ import type {
   Interrupt,
   ModelMessage,
   RunAgentResumeItem,
+  SchemaInput,
   StreamChunk,
   SubagentBinding,
 } from '@tanstack/ai'
-import type { InboxEntry, InboxStore } from '@tanstack/ai-persistence'
+import type {
+  CredentialStore,
+  InboxEntry,
+  InboxStore,
+} from '@tanstack/ai-persistence'
+import type { CredentialsAccess } from './auth'
+import type { PluginSessionApi, Question } from './commands'
+import type { ConfigOption } from './config'
 import type {
   AgentInputOf,
   AgentRegistryView,
@@ -35,7 +46,12 @@ import type {
 } from './agents'
 import type { AnyHarness, HarnessAgentsOf } from './define'
 import type { HarnessPersistence } from './host'
-import type { HarnessPlugin, MountedPlugins } from './plugins'
+import type {
+  HarnessPlugin,
+  MountedPlugins,
+  PluginServices,
+  PluginState,
+} from './plugins'
 import type {
   BusyPolicy,
   ChatTurnResult,
@@ -101,16 +117,34 @@ export interface SessionSnapshot {
   activeOperations: Array<{ id: string; kind: string; agent?: string }>
   queuedTurns: number
   pendingInterrupts: Array<Interrupt>
+  /** Questions a command or a plugin asked, waiting for `session.answer`. */
+  pendingQuestions: Array<{
+    questionId: string
+    message: string
+    schema?: unknown
+  }>
   /** The cursor of the newest event. */
   cursor: Cursor
 }
 
+/** The resolved plugin plan of a session, for debugging and tooling. */
+export interface SessionInspection {
+  plugins: MountedPlugins['owners']['plugins']
+  tools: MountedPlugins['owners']['tools']
+  prompts: MountedPlugins['owners']['prompts']
+  commands: Array<{ name: string; owner: string }>
+  config: Array<{ key: string; owner: string }>
+  extensionPoints: Record<string, Array<string>>
+  agents: Array<string>
+}
+
 /** What the host hands a new session. */
 export interface SessionDependencies {
   harness: AnyHarness
   threadId: string
   persistence: HarnessPersistence
   inbox: InboxStore
+  credentials: CredentialStore
   principal?: Principal
   /** Identifies this host on run leases. */
   hostId: string
@@ -187,6 +221,21 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   private closing: Promise<void> | undefined
   private readonly onClose: () => void
   private readonly checkpoint: AnyChatMiddleware
+  private readonly listeners = new Map<string, Set<(value: unknown) => void>>()
+  private readonly configValues = new Map<string, unknown>()
+  private readonly questions = new Map<
+    string,
+    {
+      message: string
+      schema: SchemaInput | undefined
+      resolve: (value: unknown) => void
+      reject: (error: unknown) => void
+    }
+  >()
+  private readonly stateDoc: Record<string, unknown> = {}
+  private readonly localState = new Map<string, unknown>()
+  private readonly credentialAccess: CredentialsAccess
+  private readonly services: PluginServices
 
   constructor(deps: SessionDependencies) {
     this.harness = deps.harness as THarness
@@ -196,6 +245,37 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     this.principal = deps.principal
     this.onClose = deps.onClose
     this.checkpoint = checkpointMiddleware(deps.persistence, deps.hostId)
+    this.credentialAccess = credentialsFor(
+      deps.credentials,
+      {
+        threadId: deps.threadId,
+        ...(deps.principal ? { userId: deps.principal.id } : {}),
+      },
+      (error) =>
+        this.feed.publish(
+          'session',
+          customEvent(HARNESS_EVENTS.authRequired, {
+            connector: error.connector,
+            ...(error.url ? { url: error.url } : {}),
+          }),
+        ),
+    )
+    this.services = {
+      emit: (plugin, name, value) => this.emitPluginEvent(plugin, name, value),
+      on: (name, handler) => {
+        let set = this.listeners.get(name)
+        if (!set) {
+          set = new Set()
+          this.listeners.set(name, set)
+        }
+        set.add(handler)
+        return () => set.delete(handler)
+      },
+      config: { get: (key) => this.configValue(key) },
+      state: (plugin, initial) => this.pluginState(plugin, initial),
+      credentials: this.credentialAccess,
+      session: this.pluginApi(),
+    }
     this.registry = this.agentRegistry
     for (const agent of this.harness.agents ?? []) {
       this.agentRegistry.add(agent, 'the harness')
@@ -248,8 +328,10 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         harnessProvides: (this.harness.middleware ?? []).flatMap(
           (middleware) => middleware.provides ?? [],
         ),
+        services: this.services,
       },
     )
+    await this.loadConfig()
     await this.recoverCrashedTurn()
     await this.recoverInbox()
   }
@@ -380,10 +462,361 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       })),
       queuedTurns: this.queue.length,
       pendingInterrupts: this.interrupted?.interrupts ?? [],
+      pendingQuestions: [...this.questions.entries()].map(
+        ([questionId, question]) => ({
+          questionId,
+          message: question.message,
+          ...(question.schema
+            ? { schema: convertSchemaToJsonSchema(question.schema) }
+            : {}),
+        }),
+      ),
       cursor: this.feed.head(),
     }
   }
 
+  // ===========================
+  // Config, commands, questions
+  // ===========================
+
+  /** Every session setting, with its option and current value. */
+  config(): Record<
+    string,
+    { option: ConfigOption; value: unknown; owner: string }
+  > {
+    const result: Record<
+      string,
+      { option: ConfigOption; value: unknown; owner: string }
+    > = {}
+    for (const [key, entry] of this.sessionPlugins?.config ?? []) {
+      result[key] = {
+        option: entry.option,
+        owner: entry.owner,
+        value: this.configValue(key),
+      }
+    }
+    return result
+  }
+
+  /** Change a session setting. It applies at the next turn. */
+  async setConfig(key: string, value: unknown): Promise<Receipt> {
+    const inputId = createInputId()
+    await this.accept(inputId, { op: 'config', key, value })
+    const entry = this.sessionPlugins?.config.get(key)
+    if (!entry) {
+      this.reject(inputId, 'unknown_config')
+      return { inputId, status: 'rejected', reason: 'unknown_config' }
+    }
+    let checked: unknown
+    try {
+      checked = checkConfigValue(key, entry.option, value)
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      this.reject(inputId, reason)
+      return { inputId, status: 'rejected', reason }
+    }
+    this.configValues.set(key, checked)
+    await this.persistence.stores.metadata?.set(
+      'harness:config',
+      this.threadId,
+      Object.fromEntries(this.configValues),
+    )
+    await this.applied(inputId, 'session')
+    this.feed.publish(
+      'session',
+      customEvent(HARNESS_EVENTS.configChanged, { key, value: checked }),
+    )
+    return { inputId, status: 'accepted' }
+  }
+
+  /** The commands of this session, for hosts to list. */
+  commands(): Array<{
+    name: string
+    description: string
+    owner: string
+    input?: unknown
+  }> {
+    return [...(this.sessionPlugins?.commands ?? [])].map(([name, entry]) => ({
+      name,
+      description: entry.command.description,
+      owner: entry.owner,
+      ...(entry.command.input
+        ? { input: convertSchemaToJsonSchema(entry.command.input) }
+        : {}),
+    }))
+  }
+
+  /** Run a plugin command. Its input is checked against the command's schema. */
+  command(name: string, input?: unknown): Operation<unknown> {
+    const operation = new OperationImpl<unknown>(
+      'command',
+      this.feed,
+      (target) => this.cancel(target.id),
+    )
+    this.operations.set(operation.id, operation)
+    void this.executeCommand(operation, name, input)
+    return operation
+  }
+
+  /** Answer a question from `ctx.session.ask`. */
+  async answer(questionId: string, value: unknown): Promise<Receipt> {
+    const inputId = createInputId()
+    await this.accept(inputId, { op: 'answer', questionId, value })
+    const question = this.questions.get(questionId)
+    if (!question) {
+      this.reject(inputId, 'unknown_question')
+      return { inputId, status: 'rejected', reason: 'unknown_question' }
+    }
+    let checked: unknown = value
+    if (question.schema !== undefined) {
+      const result = await validateWithStandardSchema(question.schema, value)
+      if (!result.success) {
+        const reason = `Invalid answer: ${result.issues.map((issue) => issue.message).join(', ')}`
+        this.reject(inputId, reason)
+        return { inputId, status: 'rejected', reason }
+      }
+      checked = result.data
+    }
+    this.questions.delete(questionId)
+    await this.applied(inputId, 'session')
+    this.feed.publish(
+      'session',
+      customEvent(HARNESS_EVENTS.questionAnswered, { questionId }),
+    )
+    question.resolve(checked)
+    return { inputId, status: 'accepted' }
+  }
+
+  /** The resolved plugin plan: order, owners, and extension contributors. */
+  inspect(): SessionInspection {
+    const mounted = this.sessionPlugins
+    const extensionPoints: Record<string, Array<string>> = {}
+    for (const [point, items] of mounted?.extensions ?? []) {
+      extensionPoints[point] = [...new Set(items.map((item) => item.owner))]
+    }
+    return {
+      plugins: mounted?.owners.plugins ?? [],
+      tools: mounted?.owners.tools ?? [],
+      prompts: mounted?.owners.prompts ?? [],
+      commands: [...(mounted?.commands ?? [])].map(([name, entry]) => ({
+        name,
+        owner: entry.owner,
+      })),
+      config: [...(mounted?.config ?? [])].map(([key, entry]) => ({
+        key,
+        owner: entry.owner,
+      })),
+      extensionPoints,
+      agents: this.agentRegistry.list().map((agent) => agent.name),
+    }
+  }
+
+  private configValue(key: string): unknown {
+    if (this.configValues.has(key)) return this.configValues.get(key)
+    return this.sessionPlugins?.config.get(key)?.option.default
+  }
+
+  private async loadConfig(): Promise<void> {
+    const stored = await this.persistence.stores.metadata?.get(
+      'harness:config',
+      this.threadId,
+    )
+    if (typeof stored !== 'object' || stored === null) return
+    for (const [key, value] of Object.entries(stored)) {
+      const entry = this.sessionPlugins?.config.get(key)
+      if (!entry) continue
+      try {
+        this.configValues.set(key, checkConfigValue(key, entry.option, value))
+      } catch {
+        // A stored value an option no longer accepts falls back to the default.
+      }
+    }
+  }
+
+  private ask(question: Question<SchemaInput | undefined>): Promise<unknown> {
+    if (this.closing) return Promise.reject(new Error('Session closed.'))
+    const questionId = `q-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`
+    return new Promise((resolve, reject) => {
+      this.questions.set(questionId, {
+        message: question.message,
+        schema: question.schema,
+        resolve,
+        reject,
+      })
+      this.feed.publish(
+        'session',
+        customEvent(HARNESS_EVENTS.question, {
+          questionId,
+          message: question.message,
+          ...(question.schema
+            ? { schema: convertSchemaToJsonSchema(question.schema) }
+            : {}),
+        }),
+      )
+    })
+  }
+
+  private pluginApi(): PluginSessionApi {
+    return {
+      threadId: this.threadId,
+      principal: this.principal,
+      snapshot: () => this.snapshot(),
+      prompt: (text) => {
+        this.prompt(text).then(
+          () => {},
+          () => {},
+        )
+      },
+      transcript: async () => [
+        ...(await this.persistence.stores.messages.loadThread(this.threadId)),
+      ],
+      replaceTranscript: (messages) =>
+        this.persistence.stores.messages.saveThread(this.threadId, messages),
+      // The public type narrows the answer from the schema.
+      ask: ((question: Question<SchemaInput | undefined>) =>
+        this.ask(question)) as PluginSessionApi['ask'],
+      authRequired: (info) =>
+        this.feed.publish(
+          'session',
+          customEvent(HARNESS_EVENTS.authRequired, { ...info }),
+        ),
+      setConfig: (key, value) => this.setConfig(key, value),
+    }
+  }
+
+  private emitPluginEvent(plugin: string, name: string, value: unknown): void {
+    this.feed.publish(
+      'session',
+      customEvent(HARNESS_EVENTS.pluginEvent, { plugin, name, value }),
+    )
+    for (const handler of this.listeners.get(name) ?? []) {
+      try {
+        handler(value)
+      } catch {
+        // One broken listener must not stop the others.
+      }
+    }
+  }
+
+  private pluginState<T>(plugin: string, initial: T): PluginState<T> {
+    const metadata = this.persistence.stores.metadata
+    const namespace = `plugin:${plugin}`
+    const key = this.threadId
+    const read = async (): Promise<{ value: T; revision: string | null }> => {
+      if (metadata?.getVersioned) {
+        const stored = await metadata.getVersioned(namespace, key)
+        // The store holds what this plugin wrote.
+        return stored
+          ? { value: stored.value as T, revision: stored.revision }
+          : { value: initial, revision: null }
+      }
+      if (metadata) {
+        const stored = await metadata.get(namespace, key)
+        return {
+          value: stored === null ? initial : (stored as T),
+          revision: null,
+        }
+      }
+      return {
+        value: this.localState.has(namespace)
+          ? (this.localState.get(namespace) as T)
+          : initial,
+        revision: null,
+      }
+    }
+    const publish = (value: T) => {
+      this.stateDoc[plugin] = value
+      this.feed.publish('session', {
+        type: EventType.STATE_SNAPSHOT,
+        snapshot: { plugins: { ...this.stateDoc } },
+        timestamp: Date.now(),
+      })
+    }
+    return {
+      get: async () => (await read()).value,
+      update: async (change) => {
+        for (let attempt = 0; attempt < 5; attempt += 1) {
+          const current = await read()
+          const next = change(structuredClone(current.value))
+          if (metadata?.setIf) {
+            const written = await metadata.setIf(
+              namespace,
+              key,
+              next,
+              current.revision,
+            )
+            if (!written.ok) continue
+          } else if (metadata) {
+            await metadata.set(namespace, key, next)
+          } else {
+            this.localState.set(namespace, next)
+          }
+          publish(next)
+          return next
+        }
+        throw new Error(`Plugin ${plugin}: state update conflicted 5 times.`)
+      },
+    }
+  }
+
+  private async executeCommand(
+    operation: OperationImpl<unknown>,
+    name: string,
+    input: unknown,
+  ): Promise<void> {
+    const inputId = createInputId()
+    await this.accept(inputId, { op: 'command', name, input })
+    const entry = this.sessionPlugins?.commands.get(name)
+    if (!entry) {
+      this.reject(inputId, 'unknown_command')
+      operation.fail('failed', new Error(`Unknown command: ${name}`))
+      return
+    }
+    let checked: unknown = input
+    if (entry.command.input !== undefined) {
+      const result = await validateWithStandardSchema(
+        entry.command.input,
+        input ?? {},
+      )
+      if (!result.success) {
+        const reason = `Input validation failed for command ${name}: ${result.issues
+          .map((issue) => issue.message)
+          .join(', ')}`
+        this.reject(inputId, 'invalid_input')
+        operation.fail('failed', new Error(reason))
+        return
+      }
+      checked = result.data
+    }
+    operation.setStatus('running')
+    await this.applied(inputId, operation.id)
+    this.publishStarted(operation)
+    try {
+      const result: unknown = await entry.command.run(checked, {
+        signal: operation.abortController.signal,
+        session: this.services.session,
+      })
+      operation.publish(
+        customEvent('harness.command.result', {
+          name,
+          result: compactForModel(result),
+        }),
+      )
+      operation.finish('completed', result)
+    } catch (error) {
+      operation.publish({
+        type: EventType.RUN_ERROR,
+        message: error instanceof Error ? error.message : String(error),
+        timestamp: Date.now(),
+      })
+      operation.fail(
+        operation.abortController.signal.aborted ? 'cancelled' : 'failed',
+        error,
+      )
+    }
+    this.publishFinished(operation)
+  }
+
   /**
    * Stop every running operation, wait for them, then dispose session plugins.
    * Safe to call twice.
@@ -399,6 +832,10 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       for (const operation of running) {
         operation.abortController.abort(RUN_CANCEL_REASON)
       }
+      for (const question of this.questions.values()) {
+        question.reject(new Error('Session closed.'))
+      }
+      this.questions.clear()
       await Promise.allSettled(
         running.map((operation) => Promise.resolve(operation)),
       )
@@ -518,8 +955,14 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             (middleware) => middleware.provides ?? [],
           ),
           ...(this.sessionPlugins
-            ? { inherited: this.sessionPlugins.values }
+            ? {
+                inherited: this.sessionPlugins.values,
+                takenCommands: this.sessionPlugins.commands,
+                takenConfig: this.sessionPlugins.config,
+                inheritedExtensions: this.sessionPlugins.extensions,
+              }
             : {}),
+          services: this.services,
         })
       }
       const session = this.sessionPlugins
@@ -528,16 +971,26 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         runPlugins?.capabilityBridge,
       ].filter((bridge): bridge is AnyChatMiddleware => bridge !== undefined)
       const subagents = this.harness.subagents
+      const picked = [
+        ...(session?.adapters ?? []),
+        ...(runPlugins?.adapters ?? []),
+      ]
+        .map((pick) => pick())
+        .filter((adapter) => adapter !== undefined)
+        .at(-1)
+      const resolvePrompt = (prompt: string | (() => string)) =>
+        typeof prompt === 'function' ? prompt() : prompt
       const stream = chat({
-        adapter: this.harness.adapter,
+        adapter: picked ?? this.harness.adapter,
         messages:
           turn.message !== undefined
             ? [{ id: createMessageId(), role: 'user', content: turn.message }]
             : [],
         systemPrompts: [
           ...(this.harness.systemPrompts ?? []),
-          ...(session?.prompts ?? []),
-          ...(runPlugins?.prompts ?? []),
+          ...[...(session?.prompts ?? []), ...(runPlugins?.prompts ?? [])]
+            .map(resolvePrompt)
+            .filter((prompt) => prompt !== ''),
         ],
         tools: [
           ...(this.harness.tools ?? []),
diff --git a/packages/ai-harness/src/types.ts b/packages/ai-harness/src/types.ts
index 43c65515b7..ffcf2efc89 100644
--- a/packages/ai-harness/src/types.ts
+++ b/packages/ai-harness/src/types.ts
@@ -54,6 +54,9 @@ export type HarnessInput =
   | { op: 'resolve'; resume: Array<RunAgentResumeItem> }
   | { op: 'agent'; agent: string; input?: unknown; detached?: boolean }
   | { op: 'cancel'; operationId?: string }
+  | { op: 'command'; name: string; input?: unknown }
+  | { op: 'answer'; questionId: string; value: unknown }
+  | { op: 'config'; key: string; value: unknown }
 
 /** Who sent an input, from the host's `authorize`. */
 export interface Principal {
@@ -94,6 +97,11 @@ export const HARNESS_EVENTS = {
   operationStarted: 'harness.operation.started',
   operationFinished: 'harness.operation.finished',
   operationResumed: 'harness.operation.resumed',
+  configChanged: 'harness.config.changed',
+  question: 'harness.question',
+  questionAnswered: 'harness.question.answered',
+  pluginEvent: 'harness.plugin.event',
+  authRequired: 'harness.auth_required',
   inputAccepted: 'harness.input.accepted',
   inputApplied: 'harness.input.applied',
   inputRejected: 'harness.input.rejected',
diff --git a/packages/ai-harness/tests/auth.test.ts b/packages/ai-harness/tests/auth.test.ts
new file mode 100644
index 0000000000..1a3509ea75
--- /dev/null
+++ b/packages/ai-harness/tests/auth.test.ts
@@ -0,0 +1,273 @@
+import { describe, expect, it, vi } from 'vitest'
+import { toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  HARNESS_EVENTS,
+  buildAuthorizationUrl,
+  createHarnessHost,
+  createPkce,
+  defineHarness,
+  deviceLogin,
+  exchangeCode,
+  loopbackLogin,
+  oauthConnector,
+  refreshCredential,
+  scrubSecrets,
+} from '../src'
+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(
+      { threadId: 't', userId: 'user-1' },
+      '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', () => {
+    expect(scrubSecrets('token gh-abcdef1234 failed', ['gh-abcdef1234'])).toBe(
+      'token [redacted] failed',
+    )
+  })
+})
diff --git a/packages/ai-harness/tests/extensions.test.ts b/packages/ai-harness/tests/extensions.test.ts
new file mode 100644
index 0000000000..4628ff8d6b
--- /dev/null
+++ b/packages/ai-harness/tests/extensions.test.ts
@@ -0,0 +1,330 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { EventType } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  HARNESS_EVENTS,
+  configOption,
+  createExtensionPoint,
+  createHarnessHost,
+  createPluginEvent,
+  defineCommand,
+  defineHarness,
+  definePlugin,
+} from '../src'
+import { mockAdapter, text } from './helpers'
+import type { StreamChunk } from '@tanstack/ai'
+
+describe('extension points', () => {
+  it('lets one plugin read what others contribute, in any order', async () => {
+    const Rules = createExtensionPoint<{ tool: string }>('test/rules')
+    let read: ReadonlyArray<{ tool: string }> = []
+    const reader = definePlugin({
+      name: 'test/reader',
+      setup: (ctx) => {
+        const rules = ctx.collect(Rules)
+        return {
+          commands: {
+            rules: defineCommand({
+              description: 'List rules',
+              run: () => (read = [...rules]),
+            }),
+          },
+        }
+      },
+    })
+    const writerA = definePlugin({
+      name: 'test/a',
+      setup: () => ({ contribute: [Rules.item({ tool: 'write_file' })] }),
+    })
+    const writerB = definePlugin({
+      name: 'test/b',
+      setup: () => ({ contribute: [Rules.item({ tool: 'bash' })] }),
+    })
+    const { adapter } = mockAdapter([])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/ext',
+        adapter,
+        plugins: () => [reader, writerA, writerB],
+      }),
+      { threadId: 't' },
+    )
+    await session.command('rules')
+    expect(read).toEqual([{ tool: 'write_file' }, { tool: 'bash' }])
+    expect(session.inspect().extensionPoints['test/rules']).toEqual([
+      'test/a',
+      'test/b',
+    ])
+    await host.close()
+  })
+})
+
+describe('events and state', () => {
+  it('delivers typed events and keeps plugin state', async () => {
+    const added = createPluginEvent<{ id: string }>('todo.added')
+    const heard: Array<string> = []
+    const todos = definePlugin({
+      name: 'test/todos',
+      setup: (ctx) => {
+        const state = ctx.state<{ items: Array<string> }>({ items: [] })
+        return {
+          commands: {
+            add: defineCommand({
+              description: 'Add a todo',
+              input: z.object({ text: z.string() }),
+              run: async ({ text: item }) => {
+                const next = await state.update((current) => ({
+                  items: [...current.items, item],
+                }))
+                ctx.emit(added, { id: item })
+                return next.items.length
+              },
+            }),
+          },
+        }
+      },
+    })
+    const listener = definePlugin({
+      name: 'test/listener',
+      setup: (ctx) => {
+        ctx.on(added, (value) => heard.push(value.id))
+      },
+    })
+    const persistence = memoryPersistence()
+    const { adapter } = mockAdapter([])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/state',
+        adapter,
+        plugins: () => [todos, listener],
+      }),
+      { threadId: 't' },
+    )
+
+    const seen: Array<StreamChunk> = []
+    const reader = new AbortController()
+    const reading = (async () => {
+      for await (const entry of session.events({ signal: reader.signal }))
+        seen.push(entry.event)
+    })()
+
+    expect(await session.command('add', { text: 'milk' })).toBe(1)
+    expect(await session.command('add', { text: 'eggs' })).toBe(2)
+    await expect(session.command('add', { text: 3 })).rejects.toThrow(
+      'Input validation failed',
+    )
+    expect(heard).toEqual(['milk', 'eggs'])
+    expect(
+      await persistence.stores.metadata.get('plugin:test/todos', 't'),
+    ).toEqual({
+      items: ['milk', 'eggs'],
+    })
+
+    await vi.waitFor(() =>
+      expect(
+        seen.some((event) => event.type === EventType.STATE_SNAPSHOT),
+      ).toBe(true),
+    )
+    reader.abort()
+    await reading
+    expect(
+      seen.some(
+        (event) =>
+          event.type === EventType.CUSTOM &&
+          event.name === HARNESS_EVENTS.pluginEvent,
+      ),
+    ).toBe(true)
+    await host.close()
+  })
+})
+
+describe('session config', () => {
+  it('validates, persists, and applies settings at the next turn', async () => {
+    const seenThinking: Array<unknown> = []
+    const thinking = definePlugin({
+      name: 'test/thinking',
+      setup: (ctx) => ({
+        config: {
+          thinking: configOption.select({
+            options: ['off', 'low', 'high'],
+            default: 'low',
+          }),
+        },
+        middleware: [
+          {
+            name: 'test/read-thinking',
+            onStart: () => void seenThinking.push(ctx.config.get('thinking')),
+          },
+        ],
+      }),
+    })
+    const persistence = memoryPersistence()
+    const { adapter } = mockAdapter([
+      () => text('a'),
+      () => text('b'),
+      () => text('c'),
+    ])
+    const harness = defineHarness({
+      name: 'test/config',
+      adapter,
+      plugins: () => [thinking],
+    })
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(harness, { threadId: 't' })
+
+    await session.prompt('one')
+    expect(await session.setConfig('thinking', 'extreme')).toMatchObject({
+      status: 'rejected',
+    })
+    expect(await session.setConfig('missing', 1)).toMatchObject({
+      reason: 'unknown_config',
+    })
+    expect(await session.setConfig('thinking', 'high')).toMatchObject({
+      status: 'accepted',
+    })
+    await session.prompt('two')
+    expect(seenThinking).toEqual(['low', 'high'])
+    expect(session.config().thinking).toMatchObject({
+      value: 'high',
+      owner: 'test/thinking',
+    })
+    await host.close()
+
+    // A new host reads the saved setting.
+    const again = await createHarnessHost({ persistence }).open(harness, {
+      threadId: 't',
+    })
+    expect(again.config().thinking?.value).toBe('high')
+    await again.close()
+  })
+})
+
+describe('commands and questions', () => {
+  it('asks the user inside a command and continues with the answer', async () => {
+    const deploy = definePlugin({
+      name: 'test/deploy',
+      setup: () => ({
+        commands: {
+          deploy: defineCommand({
+            description: 'Deploy after a confirmation',
+            run: async (_input, ctx) => {
+              const sure = await ctx.session.ask({
+                message: 'Deploy to production?',
+                schema: z.boolean(),
+              })
+              return sure ? 'deployed' : 'skipped'
+            },
+          }),
+        },
+      }),
+    })
+    const { adapter } = mockAdapter([])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({ name: 'test/ask', adapter, plugins: () => [deploy] }),
+      { threadId: 't' },
+    )
+
+    const running = session.command('deploy')
+    await vi.waitFor(() =>
+      expect(session.snapshot().pendingQuestions).toHaveLength(1),
+    )
+    const [question] = session.snapshot().pendingQuestions
+    expect(question?.message).toBe('Deploy to production?')
+    expect(
+      await session.answer(question!.questionId, 'yes please'),
+    ).toMatchObject({
+      status: 'rejected',
+    })
+    expect(await session.answer(question!.questionId, true)).toMatchObject({
+      status: 'accepted',
+    })
+    await expect(running).resolves.toBe('deployed')
+    expect(session.commands().map((command) => command.name)).toEqual([
+      'deploy',
+    ])
+    await host.close()
+  })
+
+  it('rejects two plugins with the same command or config key', async () => {
+    const make = (name: string) =>
+      definePlugin({
+        name,
+        setup: () => ({
+          commands: { same: defineCommand({ description: 'x', run: () => 1 }) },
+        }),
+      })
+    const { adapter } = mockAdapter([])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    await expect(
+      host.open(
+        defineHarness({
+          name: 'test/dup-cmd',
+          adapter,
+          plugins: () => [make('test/one'), make('test/two')],
+        }),
+        {
+          threadId: 't',
+        },
+      ),
+    ).rejects.toThrow(
+      'Duplicate command "same": first owner test/one, second owner test/two',
+    )
+  })
+})
+
+describe('adapter override and credentials', () => {
+  it('lets a plugin pick the main adapter and read credentials', async () => {
+    const main = mockAdapter([() => text('from main')])
+    const other = mockAdapter([() => text('from other')])
+    let token: string | undefined
+    const picker = definePlugin({
+      name: 'test/picker',
+      setup: (ctx) => ({
+        adapter: () =>
+          ctx.config.get('model') === 'other' ? other.adapter : undefined,
+        config: {
+          model: configOption.select({
+            options: ['main', 'other'],
+            default: 'main',
+          }),
+        },
+        commands: {
+          token: defineCommand({
+            description: 'Read the GitHub token',
+            run: async () => {
+              const credential = await ctx.credentials.require('github')
+              token =
+                credential.type === 'oauth'
+                  ? credential.accessToken
+                  : credential.value
+              return 'ok'
+            },
+          }),
+        },
+      }),
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/pick',
+        adapter: main.adapter,
+        plugins: () => [picker],
+      }),
+      { threadId: 't', principal: { id: 'user-1' } },
+    )
+
+    await session.setConfig('model', 'other')
+    expect(await session.prompt('hi')).toEqual({ text: 'from other' })
+    expect(main.calls).toHaveLength(0)
+
+    await expect(session.command('token')).rejects.toThrow(
+      'Sign in to github first',
+    )
+    expect(token).toBeUndefined()
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/first-party.test.ts b/packages/ai-harness/tests/first-party.test.ts
new file mode 100644
index 0000000000..2718939d76
--- /dev/null
+++ b/packages/ai-harness/tests/first-party.test.ts
@@ -0,0 +1,218 @@
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '../src'
+import {
+  compact,
+  decidePermission,
+  fileCommands,
+  globToRegExp,
+  modelPicker,
+  permissions,
+  projectInstructions,
+  todos,
+  usage,
+  workspaceTools,
+} from '../src/first-party'
+import { messageTexts, mockAdapter, text, toolCall } from './helpers'
+import type { HarnessPlugin } from '../src'
+import type { AnyTextAdapter } from '@tanstack/ai'
+
+let root = ''
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'harness-'))
+})
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+async function open(adapter: AnyTextAdapter, plugins: Array<HarnessPlugin>) {
+  const persistence = memoryPersistence()
+  const host = createHarnessHost({ persistence })
+  const session = await host.open(
+    defineHarness({
+      name: 'test/first-party',
+      adapter,
+      plugins: () => plugins,
+    }),
+    {
+      threadId: 't',
+    },
+  )
+  return { host, session, persistence }
+}
+
+describe('decidePermission', () => {
+  const rules = [
+    { tool: 'read_file', decision: 'allow' as const, kind: 'read' as const },
+    { tool: 'write_file', decision: 'ask' as const, kind: 'edit' as const },
+    { tool: 'bash', decision: 'ask' as const, kind: 'execute' as const },
+  ]
+  it('applies modes on top of the rules', () => {
+    expect(decidePermission(rules, 'write_file', 'default')).toBe('ask')
+    expect(decidePermission(rules, 'write_file', 'acceptEdits')).toBe('allow')
+    expect(decidePermission(rules, 'bash', 'acceptEdits')).toBe('ask')
+    expect(decidePermission(rules, 'write_file', 'plan')).toBe('deny')
+    expect(decidePermission(rules, 'read_file', 'plan')).toBe('allow')
+    expect(decidePermission(rules, 'bash', 'bypass')).toBe('allow')
+  })
+})
+
+describe('workspace tools with permissions', () => {
+  it('reads freely, asks before writing, and stays inside the root', async () => {
+    await writeFile(join(root, 'notes.txt'), 'hello\nworld\n')
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('read_file', { path: 'notes.txt' }, 'c1'),
+      () =>
+        toolCall('write_file', { path: 'out.txt', content: 'written' }, 'c2'),
+      () => toolCall('read_file', { path: '../escape.txt' }, 'c3'),
+      () => text('done'),
+    ])
+    const { host, session } = await open(adapter, [
+      permissions(),
+      workspaceTools({ root }),
+    ])
+
+    const turn = session.prompt('work')
+    await vi.waitFor(() =>
+      expect(session.snapshot().pendingQuestions).toHaveLength(1),
+    )
+    const [question] = session.snapshot().pendingQuestions
+    expect(question?.message).toContain('write_file')
+    await session.answer(question!.questionId, 'y')
+    await turn
+
+    expect(await readFile(join(root, 'out.txt'), 'utf8')).toBe('written')
+    const toolResults = JSON.stringify(calls[3].messages)
+    expect(toolResults).toContain('1\\thello')
+    expect(toolResults).toContain('outside the workspace')
+    await host.close()
+  })
+
+  it('denies edits in plan mode without asking', async () => {
+    const { adapter } = mockAdapter([
+      () => toolCall('write_file', { path: 'x.txt', content: 'x' }, 'c1'),
+      () => text('ok'),
+    ])
+    const { host, session } = await open(adapter, [
+      permissions(),
+      workspaceTools({ root }),
+    ])
+    expect(await session.command('mode', 'plan')).toBe('Mode: plan.')
+    await session.prompt('write')
+    await expect(readFile(join(root, 'x.txt'), 'utf8')).rejects.toThrow()
+    expect(session.snapshot().pendingQuestions).toHaveLength(0)
+    await host.close()
+  })
+
+  it('matches globs like the list tool', () => {
+    expect(globToRegExp('src/**/*.ts').test('src/a/b.ts')).toBe(true)
+    expect(globToRegExp('src/**/*.ts').test('src/b.ts')).toBe(true)
+    expect(globToRegExp('*.md').test('docs/a.md')).toBe(false)
+  })
+})
+
+describe('modelPicker', () => {
+  it('switches the main model with /model', async () => {
+    const fast = mockAdapter([() => text('fast answer')])
+    const smart = mockAdapter([() => text('smart answer')])
+    const { host, session } = await open(smart.adapter, [
+      modelPicker({
+        choices: { smart: smart.adapter, fast: fast.adapter },
+        default: 'smart',
+      }),
+    ])
+    expect(await session.command('model', 'fast')).toContain('Model: fast')
+    expect(await session.prompt('hi')).toEqual({ text: 'fast answer' })
+    expect(await session.command('model', 'nope')).toContain('Unknown model')
+    await host.close()
+  })
+})
+
+describe('todos', () => {
+  it('keeps the list in state and shows it in the next prompt', async () => {
+    const { adapter, calls } = mockAdapter([
+      () =>
+        toolCall('todo_write', {
+          todos: [{ text: 'write tests', status: 'in_progress' }],
+        }),
+      () => text('planned'),
+      () => text('next'),
+    ])
+    const { host, session, persistence } = await open(adapter, [todos()])
+    await session.prompt('plan it')
+    expect(await session.command('todos')).toBe('[~] write tests')
+    await session.prompt('continue')
+    expect(JSON.stringify(calls[2].systemPrompts)).toContain('[~] write tests')
+    expect(
+      await persistence.stores.metadata.get('plugin:tanstack/todos', 't'),
+    ).toEqual({
+      items: [{ text: 'write tests', status: 'in_progress' }],
+    })
+    await host.close()
+  })
+})
+
+describe('project files', () => {
+  it('adds AGENTS.md to the prompt and turns command files into commands', async () => {
+    await writeFile(join(root, 'AGENTS.md'), 'Use tabs.')
+    await mkdir(join(root, 'commands'))
+    await writeFile(
+      join(root, 'commands', 'review.md'),
+      '---\ndescription: Review a file\n---\nReview $ARGUMENTS carefully.',
+    )
+    const { adapter, calls } = mockAdapter([() => text('reviewed')])
+    const { host, session } = await open(adapter, [
+      projectInstructions({ root }),
+      fileCommands({ dir: join(root, 'commands') }),
+    ])
+    expect(session.commands()).toEqual([
+      {
+        name: 'review',
+        description: 'Review a file',
+        owner: 'tanstack/file-commands',
+      },
+    ])
+    await session.command('review', 'src/app.ts')
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    expect(messageTexts(calls[0])).toEqual(['Review src/app.ts carefully.'])
+    expect(JSON.stringify(calls[0].systemPrompts)).toContain('Use tabs.')
+    await vi.waitFor(() => expect(session.snapshot().status).toBe('idle'))
+    await host.close()
+  })
+})
+
+describe('compact and usage', () => {
+  it('replaces the transcript with a summary and counts tokens', async () => {
+    const summarizer = mockAdapter([() => text('We planned a trip.')])
+    // Real adapters report usage on RUN_FINISHED.
+    const withUsage = (answer: string) => () =>
+      text(answer).map((chunk) =>
+        chunk.type === 'RUN_FINISHED'
+          ? {
+              ...chunk,
+              usage: [{ inputTokens: 10, outputTokens: 5, totalTokens: 15 }],
+            }
+          : chunk,
+      )
+    const main = mockAdapter([withUsage('one'), withUsage('two')])
+    const { host, session, persistence } = await open(main.adapter, [
+      compact({ adapter: summarizer.adapter }),
+      usage(),
+    ])
+    await session.prompt('first')
+    await session.prompt('second')
+    expect(await session.command('compact')).toBe(
+      'Compacted 4 messages into a summary.',
+    )
+    const transcript = await persistence.stores.messages.loadThread('t')
+    expect(transcript).toHaveLength(2)
+    expect(transcript[0]?.content).toContain('We planned a trip.')
+    expect(await session.command('usage')).toBe(
+      '2 model calls, 20 input tokens, 10 output tokens, 30 total.',
+    )
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/helpers.ts b/packages/ai-harness/tests/helpers.ts
index e8e3876082..ae2e3ed929 100644
--- a/packages/ai-harness/tests/helpers.ts
+++ b/packages/ai-harness/tests/helpers.ts
@@ -39,8 +39,12 @@ export function mockAdapter(replies: Array<Reply> | Reply) {
 
 const now = () => Date.now()
 
-/** One model call that answers with `content`. */
+let messageCount = 0
+
+/** One model call that answers with `content`. Each call gets a new message id. */
 export function text(content: string): Array<StreamChunk> {
+  messageCount += 1
+  const m = `m-${messageCount}`
   return [
     {
       type: EventType.RUN_STARTED,
@@ -50,17 +54,17 @@ export function text(content: string): Array<StreamChunk> {
     },
     {
       type: EventType.TEXT_MESSAGE_START,
-      messageId: 'm',
+      messageId: m,
       role: 'assistant',
       timestamp: now(),
     },
     {
       type: EventType.TEXT_MESSAGE_CONTENT,
-      messageId: 'm',
+      messageId: m,
       delta: content,
       timestamp: now(),
     },
-    { type: EventType.TEXT_MESSAGE_END, messageId: 'm', timestamp: now() },
+    { type: EventType.TEXT_MESSAGE_END, messageId: m, timestamp: now() },
     {
       type: EventType.RUN_FINISHED,
       runId: 'r',
diff --git a/packages/ai-harness/vite.config.ts b/packages/ai-harness/vite.config.ts
index 2fabdfea04..c99a69e684 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', './src/client.ts'],
+    entry: ['./src/index.ts', './src/client.ts', './src/first-party/index.ts'],
     srcDir: './src',
     cjs: false,
   }),
diff --git a/packages/ai-persistence/src/index.ts b/packages/ai-persistence/src/index.ts
index eac9972b34..23b7903f28 100644
--- a/packages/ai-persistence/src/index.ts
+++ b/packages/ai-persistence/src/index.ts
@@ -10,6 +10,7 @@ export {
   defineArtifactStore,
   defineBlobStore,
   defineInboxStore,
+  defineCredentialStore,
   // Run lifecycle helpers owned by @tanstack/ai, transiting through ./types so
   // this package's public surface stays a single import for backend authors.
   isTerminalRunStatus,
@@ -30,6 +31,9 @@ export type {
   InboxEntry,
   InboxStatus,
   InboxStore,
+  // Harness credentials
+  Credential,
+  CredentialStore,
   // Named product shapes (prefer these over a sparse bag)
   ChatTranscriptStores,
   ChatPersistenceStores,
diff --git a/packages/ai-persistence/src/memory.ts b/packages/ai-persistence/src/memory.ts
index fd4df0b8b6..3565cbeb2a 100644
--- a/packages/ai-persistence/src/memory.ts
+++ b/packages/ai-persistence/src/memory.ts
@@ -14,8 +14,11 @@ import type {
   BlobStore,
   GenerationRunRecord,
   GenerationRunStore,
+  Credential,
+  CredentialStore,
   InboxEntry,
   InboxStore,
+  Scope,
   InterruptCommitEntry,
   InterruptRecord,
   InterruptStore,
@@ -300,6 +303,47 @@ class MemoryMetadataStore implements MetadataStore {
   // (This parameter is an app-defined metadata namespace string — not the
   // shared `Scope` identity type from `@tanstack/ai`.)
   private readonly values = new Map<string, Map<string, unknown>>()
+  private readonly revisions = new Map<string, Map<string, number>>()
+  private revisionOf(namespace: string, key: string): number | undefined {
+    return this.revisions.get(namespace)?.get(key)
+  }
+  private bump(namespace: string, key: string): string {
+    let bucket = this.revisions.get(namespace)
+    if (!bucket) {
+      bucket = new Map()
+      this.revisions.set(namespace, bucket)
+    }
+    const next = (bucket.get(key) ?? 0) + 1
+    bucket.set(key, next)
+    return String(next)
+  }
+  getVersioned(
+    namespace: string,
+    key: string,
+  ): Promise<{ value: unknown; revision: string } | null> {
+    const bucket = this.values.get(namespace)
+    if (!bucket || !bucket.has(key)) return Promise.resolve(null)
+    return Promise.resolve({
+      value: bucket.get(key),
+      revision: String(this.revisionOf(namespace, key) ?? 0),
+    })
+  }
+  async setIf(
+    namespace: string,
+    key: string,
+    value: unknown,
+    expectedRevision: string | null,
+  ): Promise<
+    { ok: true; revision: string } | { ok: false; reason: 'conflict' }
+  > {
+    const present = this.values.get(namespace)?.has(key) ?? false
+    const current = present
+      ? String(this.revisionOf(namespace, key) ?? 0)
+      : null
+    if (current !== expectedRevision) return { ok: false, reason: 'conflict' }
+    await this.set(namespace, key, value)
+    return { ok: true, revision: String(this.revisionOf(namespace, key)) }
+  }
   get(namespace: string, key: string): Promise<unknown | null> {
     const bucket = this.values.get(namespace)
     if (!bucket || !bucket.has(key)) return Promise.resolve(null)
@@ -312,11 +356,13 @@ class MemoryMetadataStore implements MetadataStore {
       this.values.set(namespace, bucket)
     }
     bucket.set(key, value)
+    this.bump(namespace, key)
     return Promise.resolve()
   }
   delete(namespace: string, key: string): Promise<void> {
     const bucket = this.values.get(namespace)
     if (!bucket) return Promise.resolve()
+    this.revisions.get(namespace)?.delete(key)
     bucket.delete(key)
     if (bucket.size === 0) this.values.delete(namespace)
     return Promise.resolve()
@@ -583,6 +629,48 @@ class MemoryInboxStore implements InboxStore {
   }
 }
 
+class MemoryCredentialStore implements CredentialStore {
+  private readonly values = new Map<string, Map<string, Credential>>()
+  // A credential without a userId belongs to the tenant.
+  private owner(scope: Scope): string {
+    return JSON.stringify([scope.tenantId ?? null, scope.userId ?? null])
+  }
+  get(scope: Scope, id: string): Promise<Credential | null> {
+    const stored = this.values.get(this.owner(scope))?.get(id)
+    return Promise.resolve(stored ? { ...stored } : null)
+  }
+  set(scope: Scope, id: string, credential: Credential): Promise<void> {
+    const key = this.owner(scope)
+    let bucket = this.values.get(key)
+    if (!bucket) {
+      bucket = new Map()
+      this.values.set(key, bucket)
+    }
+    bucket.set(id, { ...credential })
+    return Promise.resolve()
+  }
+  delete(scope: Scope, id: string): Promise<void> {
+    this.values.get(this.owner(scope))?.delete(id)
+    return Promise.resolve()
+  }
+  list(
+    scope: Scope,
+  ): Promise<
+    Array<{ id: string; type: Credential['type']; expiresAt?: number }>
+  > {
+    const bucket = this.values.get(this.owner(scope))
+    return Promise.resolve(
+      [...(bucket?.entries() ?? [])].map(([id, credential]) => ({
+        id,
+        type: credential.type,
+        ...(credential.type === 'oauth' && credential.expiresAt !== undefined
+          ? { expiresAt: credential.expiresAt }
+          : {}),
+      })),
+    )
+  }
+}
+
 interface MemoryPersistenceStores {
   messages: MessageStore
   runs: RunStore
@@ -592,13 +680,14 @@ interface MemoryPersistenceStores {
   artifacts: ArtifactStore
   blobs: BlobStore
   inbox: InboxStore
+  credentials: CredentialStore
 }
 
 /**
  * In-process reference backend for the full state + generation store set.
  *
  * Returns messages + runs + generationRuns + interrupts + metadata + artifacts
- * + blobs + inbox. Locks are not included — use `InMemoryLockStore` +
+ * + blobs + inbox + credentials. Locks are not included — use `InMemoryLockStore` +
  * `withLocks` from `@tanstack/ai` when a test or single-process app needs
  * coordination.
  */
@@ -610,6 +699,7 @@ export function memoryPersistence() {
     interrupts: new MemoryInterruptStore(),
     metadata: new MemoryMetadataStore(),
     inbox: new MemoryInboxStore(),
+    credentials: new MemoryCredentialStore(),
     artifacts: new MemoryArtifactStore(),
     blobs: new MemoryBlobStore(),
   }
diff --git a/packages/ai-persistence/src/testkit/conformance.ts b/packages/ai-persistence/src/testkit/conformance.ts
index f621c7f6a2..27b6d0e874 100644
--- a/packages/ai-persistence/src/testkit/conformance.ts
+++ b/packages/ai-persistence/src/testkit/conformance.ts
@@ -1528,6 +1528,77 @@ export function runPersistenceConformance(
       })
     })
 
+    // Credentials are opt-in: only harness hosts read them.
+    describe('credentials', () => {
+      it('keys by user and tenant, lists without values, and deletes', async (ctx) => {
+        const store = persistence.stores.credentials
+        if (!store) return ctx.skip('credentials store not provided')
+
+        const user = { threadId: 't', userId: 'u1', tenantId: 'org' }
+        const tenant = { threadId: 't', tenantId: 'org' }
+        await store.set(user, 'github', {
+          type: 'oauth',
+          accessToken: 'secret-access',
+          refreshToken: 'secret-refresh',
+          expiresAt: 100,
+        })
+        await store.set(tenant, 'notion', {
+          type: 'api_key',
+          value: 'secret-key',
+        })
+
+        expect(await store.get(user, 'github')).toMatchObject({
+          accessToken: 'secret-access',
+        })
+        // A user credential is not visible at tenant scope, and the other way around.
+        expect(await store.get(tenant, 'github')).toBeNull()
+        expect(await store.get(user, 'notion')).toBeNull()
+
+        const listed = await store.list(user)
+        expect(listed).toEqual([
+          { id: 'github', type: 'oauth', expiresAt: 100 },
+        ])
+        // `list` never returns secret values.
+        expect(JSON.stringify(listed)).not.toContain('secret')
+
+        await store.delete(user, 'github')
+        expect(await store.get(user, 'github')).toBeNull()
+        expect(await store.list(user)).toEqual([])
+      })
+    })
+
+    // Compare-and-set on metadata is opt-in.
+    describe('metadata setIf', () => {
+      it('writes only when the revision matches', async (ctx) => {
+        const store = persistence.stores.metadata
+        if (!store?.setIf || !store.getVersioned) {
+          return ctx.skip('metadata setIf not provided')
+        }
+        const created = await store.setIf('cas', 'k', { n: 1 }, null)
+        expect(created.ok).toBe(true)
+        expect(await store.setIf('cas', 'k', { n: 9 }, null)).toEqual({
+          ok: false,
+          reason: 'conflict',
+        })
+        const current = await store.getVersioned('cas', 'k')
+        expect(current?.value).toEqual({ n: 1 })
+        const revision = current?.revision ?? null
+        const updated = await store.setIf(
+          'cas',
+          'k',
+          { n: 2 },
+          revision,
+        )
+        expect(updated.ok).toBe(true)
+        expect(
+          await store.setIf('cas', 'k', { n: 3 }, revision),
+        ).toMatchObject({
+          ok: false,
+        })
+        expect(await store.get('cas', 'k')).toEqual({ n: 2 })
+      })
+    })
+
     // The inbox is opt-in: only harness hosts read it. A backend without it
     // skips these cases and needs no `skip` entry.
     describe('inbox', () => {
diff --git a/packages/ai-persistence/src/types.ts b/packages/ai-persistence/src/types.ts
index 986c384bf0..3785eb4240 100644
--- a/packages/ai-persistence/src/types.ts
+++ b/packages/ai-persistence/src/types.ts
@@ -415,6 +415,39 @@ export interface InboxStore {
 export function defineInboxStore(store: InboxStore): InboxStore {
   return store
 }
+
+/** A secret a user or an organization saved: an API key or OAuth tokens. */
+export type Credential =
+  | { type: 'api_key'; value: string }
+  | {
+      type: 'oauth'
+      accessToken: string
+      refreshToken?: string
+      expiresAt?: number
+      scopes?: Array<string>
+    }
+
+/**
+ * Durable store for credentials, keyed by scope and credential id (for
+ * example `'github'`). A credential saved without `scope.userId` belongs to
+ * the tenant. Encrypt at rest in your implementation.
+ */
+export interface CredentialStore {
+  get: (scope: Scope, id: string) => Promise<Credential | null>
+  set: (scope: Scope, id: string, credential: Credential) => Promise<void>
+  delete: (scope: Scope, id: string) => Promise<void>
+  /** Ids and types only. `list` never returns secret values. */
+  list: (
+    scope: Scope,
+  ) => Promise<
+    Array<{ id: string; type: Credential['type']; expiresAt?: number }>
+  >
+}
+
+/** Type a {@link CredentialStore} implementation inline. */
+export function defineCredentialStore(store: CredentialStore): CredentialStore {
+  return store
+}
 /** Type a {@link GenerationRunStore} implementation inline. */
 export function defineGenerationRunStore(
   store: GenerationRunStore,
@@ -669,6 +702,8 @@ export interface AIPersistenceStores {
   blobs?: BlobStore
   /** Harness session inputs. Optional: only harness hosts read it. */
   inbox?: InboxStore
+  /** User and tenant credentials. Optional: only harness hosts read it. */
+  credentials?: CredentialStore
 }
 
 /**
@@ -845,6 +880,7 @@ const storeKeys = [
   'artifacts',
   'blobs',
   'inbox',
+  'credentials',
 ] satisfies Array<StoreKey>
 
 const storeKeySet = new Set<string>(storeKeys)
diff --git a/packages/ai-persistence/tests/memory.test.ts b/packages/ai-persistence/tests/memory.test.ts
index db479ec83b..bf9aa03e61 100644
--- a/packages/ai-persistence/tests/memory.test.ts
+++ b/packages/ai-persistence/tests/memory.test.ts
@@ -15,6 +15,7 @@ describe('memoryPersistence', () => {
     expect(Object.keys(memoryPersistence().stores).sort()).toEqual([
       'artifacts',
       'blobs',
+      'credentials',
       'generationRuns',
       'inbox',
       'interrupts',
diff --git a/packages/ai-persistence/tests/persistence-types.test-d.ts b/packages/ai-persistence/tests/persistence-types.test-d.ts
index 467e17a3f0..d77673e7e6 100644
--- a/packages/ai-persistence/tests/persistence-types.test-d.ts
+++ b/packages/ai-persistence/tests/persistence-types.test-d.ts
@@ -22,6 +22,7 @@ import type {
   ChatTranscriptStores,
   GenerationRunStore,
   InboxStore,
+  CredentialStore,
   InterruptStore,
   MessagePage,
   MessageStore,
@@ -141,6 +142,7 @@ expectTypeOf(memoryPersistence()).toEqualTypeOf<
     artifacts: ArtifactStore
     blobs: BlobStore
     inbox: InboxStore
+    credentials: CredentialStore
   }>
 >()
 const transcript: ChatTranscriptPersistence = messagesOnly
diff --git a/packages/ai/src/activities/chat/middleware/metadata.ts b/packages/ai/src/activities/chat/middleware/metadata.ts
index 08d71987f1..eb37219235 100644
--- a/packages/ai/src/activities/chat/middleware/metadata.ts
+++ b/packages/ai/src/activities/chat/middleware/metadata.ts
@@ -13,6 +13,27 @@ export interface MetadataStore {
   set: (namespace: string, key: string, value: unknown) => Promise<void>
   /** Delete `(namespace, key)`. Do nothing when it is absent. */
   delete: (namespace: string, key: string) => Promise<void>
+  /**
+   * Optional. The value with a revision, or `null` when it is absent. Pair it
+   * with `setIf` for compare-and-set writes.
+   */
+  getVersioned?: (
+    namespace: string,
+    key: string,
+  ) => Promise<{ value: unknown; revision: string } | null>
+  /**
+   * Optional. Write only when the current revision is `expectedRevision`
+   * (`null` means "only when absent"). Returns the new revision, or
+   * `{ ok: false, reason: 'conflict' }` when someone else wrote first.
+   */
+  setIf?: (
+    namespace: string,
+    key: string,
+    value: unknown,
+    expectedRevision: string | null,
+  ) => Promise<
+    { ok: true; revision: string } | { ok: false; reason: 'conflict' }
+  >
 }
 
 export const MetadataCapability = createCapability<MetadataStore>()('metadata')
diff --git a/testing/e2e/src/routes/api.harness-protocol.$.ts b/testing/e2e/src/routes/api.harness-protocol.$.ts
index 50eddad947..727e618a92 100644
--- a/testing/e2e/src/routes/api.harness-protocol.$.ts
+++ b/testing/e2e/src/routes/api.harness-protocol.$.ts
@@ -1,10 +1,14 @@
 import { createFileRoute } from '@tanstack/react-router'
 import { defineAgent } from '@tanstack/ai'
 import {
+  configOption,
   createHarnessHandler,
   createHarnessHost,
+  defineCommand,
   defineHarness,
+  definePlugin,
 } from '@tanstack/ai-harness'
+import { todos } from '@tanstack/ai-harness/plugins'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { z } from 'zod'
 import { createTextAdapter } from '@/lib/providers'
@@ -36,6 +40,26 @@ function handlerFor(request: Request) {
       }),
     ],
     expose: { agents: ['echo'] },
+    plugins: () => [
+      todos(),
+      definePlugin({
+        name: 'e2e/settings',
+        setup: () => ({
+          config: {
+            tone: configOption.select({
+              options: ['plain', 'warm'],
+              default: 'plain',
+            }),
+          },
+          commands: {
+            greet: defineCommand({
+              description: 'Say hello',
+              run: () => 'hello',
+            }),
+          },
+        }),
+      }),
+    ],
   })
   return createHarnessHandler({
     host,
diff --git a/testing/e2e/tests/harness-protocol.spec.ts b/testing/e2e/tests/harness-protocol.spec.ts
index 43c81f3d47..7078085e49 100644
--- a/testing/e2e/tests/harness-protocol.spec.ts
+++ b/testing/e2e/tests/harness-protocol.spec.ts
@@ -61,6 +61,35 @@ test.describe('harness protocol', () => {
     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('takes a control input and returns a receipt', async ({
     request,
     testId,

From c0f5f9a8422dba25c6862be74997a36ddb1d9de8 Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Sat, 26 Sep 2026 11:07:34 +0000
Subject: [PATCH 009/286] ci: apply automated fixes

---
 .../ai-persistence/src/testkit/conformance.ts   | 17 ++++++-----------
 1 file changed, 6 insertions(+), 11 deletions(-)

diff --git a/packages/ai-persistence/src/testkit/conformance.ts b/packages/ai-persistence/src/testkit/conformance.ts
index 27b6d0e874..3b8ab62ebf 100644
--- a/packages/ai-persistence/src/testkit/conformance.ts
+++ b/packages/ai-persistence/src/testkit/conformance.ts
@@ -1583,18 +1583,13 @@ export function runPersistenceConformance(
         const current = await store.getVersioned('cas', 'k')
         expect(current?.value).toEqual({ n: 1 })
         const revision = current?.revision ?? null
-        const updated = await store.setIf(
-          'cas',
-          'k',
-          { n: 2 },
-          revision,
-        )
+        const updated = await store.setIf('cas', 'k', { n: 2 }, revision)
         expect(updated.ok).toBe(true)
-        expect(
-          await store.setIf('cas', 'k', { n: 3 }, revision),
-        ).toMatchObject({
-          ok: false,
-        })
+        expect(await store.setIf('cas', 'k', { n: 3 }, revision)).toMatchObject(
+          {
+            ok: false,
+          },
+        )
         expect(await store.get('cas', 'k')).toEqual({ n: 2 })
       })
     })

From 372784798f2df2d338db7e0af2de9dfff6e7ef94 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 13:15:21 +0200
Subject: [PATCH 010/286] feat(ai): subagent tree limits; harness ctx.agents
 and harness children

@tanstack/ai: subagents.limits (maxDepth, maxConcurrent, maxCalls,
timeoutMs) for the tree of children the model starts through tools. One
SubagentBudget per root run is shared by every child and passed on through
ctx.chat({ subagents }), so a child cannot reset it. A refused start reaches
the model as a tool error.

@tanstack/ai-harness: plugins get ctx.agents.run, start, and group (with
cancel-siblings or collect). harnessAgent(harness) turns a harness into a
child agent for subagents.agents, and defineHarness takes a description.
A harness applies default limits (depth 2, 3 at once, 12 per tree), and
agents started from code count against them.
---
 .changeset/harness-p4-subagents.md            |  11 ++
 docs/chat/subagents.md                        |  22 +++
 docs/config.json                              |   5 +
 docs/harness/subagents.md                     | 108 ++++++++++++
 packages/ai-harness/src/define.ts             |   2 +
 packages/ai-harness/src/harness-agent.ts      |  36 ++++
 packages/ai-harness/src/index.ts              |   5 +
 packages/ai-harness/src/plugins.ts            |  86 ++++++++-
 packages/ai-harness/src/session.ts            | 105 ++++++++++-
 packages/ai-harness/tests/subagents.test.ts   | 165 ++++++++++++++++++
 .../ai/src/activities/chat/agents/bound.ts    |  18 ++
 .../ai/src/activities/chat/agents/limits.ts   |  75 ++++++++
 .../ai/src/activities/chat/agents/spawn.ts    |  44 ++++-
 packages/ai/src/activities/index.ts           |   1 +
 packages/ai/src/index.ts                      |   4 +
 packages/ai/tests/subagent-limits.test.ts     | 159 +++++++++++++++++
 testing/e2e/fixtures/harness/basic.json       |  37 ++++
 testing/e2e/src/routes/api.harness-test.ts    |  24 +++
 testing/e2e/tests/harness.spec.ts             |  14 ++
 19 files changed, 909 insertions(+), 12 deletions(-)
 create mode 100644 .changeset/harness-p4-subagents.md
 create mode 100644 docs/harness/subagents.md
 create mode 100644 packages/ai-harness/src/harness-agent.ts
 create mode 100644 packages/ai-harness/tests/subagents.test.ts
 create mode 100644 packages/ai/src/activities/chat/agents/limits.ts
 create mode 100644 packages/ai/tests/subagent-limits.test.ts

diff --git a/.changeset/harness-p4-subagents.md b/.changeset/harness-p4-subagents.md
new file mode 100644
index 0000000000..3f64256a15
--- /dev/null
+++ b/.changeset/harness-p4-subagents.md
@@ -0,0 +1,11 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-harness': minor
+---
+
+Subagent trees now have limits, and a harness can run agents from code and call other harnesses.
+
+- **`subagents.limits`** in `@tanstack/ai`: `maxDepth`, `maxConcurrent`, `maxCalls`, and `timeoutMs` for the whole tree of children the model starts through tools. The tree shares one budget (`SubagentBudget`), which a child's `ctx.chat({ subagents })` passes on, so a child cannot reset it. A refused start reaches the model as a tool error.
+- **`ctx.agents`** in harness plugins: `run`, `start` (with `wake`), and `group` with `onFailure: 'cancel-siblings' | 'collect'`. Every child of a group settles before the group returns.
+- **`harnessAgent(harness)`** turns a harness into an agent for `subagents.agents`. `defineHarness` takes an optional `description`.
+- A harness applies default limits (`DEFAULT_SUBAGENT_LIMITS`: depth 2, 3 at once, 12 per tree) when `subagents.limits` is not set, and agents started from code count against them.
diff --git a/docs/chat/subagents.md b/docs/chat/subagents.md
index 25a05c6ad2..7916787a8f 100644
--- a/docs/chat/subagents.md
+++ b/docs/chat/subagents.md
@@ -257,6 +257,28 @@ const researcher = defineAgent({
 })
 ```
 
+## Limit the tree
+
+A child can have children of its own, and a model can call a child many times. Set `limits` so one request cannot start an unbounded tree:
+
+```ts group=subagent-values
+const limited = chat({
+  adapter: openaiText('gpt-5.6'),
+  messages: [{ role: 'user', content: 'Research squids in depth' }],
+  subagents: {
+    agents: [researcher],
+    limits: { maxDepth: 2, maxConcurrent: 3, maxCalls: 12, timeoutMs: 120_000 },
+  },
+})
+```
+
+- `maxDepth`: how deep the tree may grow. The first chat is depth 0.
+- `maxCalls`: how many children the whole tree may start.
+- `maxConcurrent`: how many children one run may have running at once.
+- `timeoutMs`: how long one child may run. A child never gets more time than its parent has left.
+
+The whole tree shares one budget. A child that calls `ctx.chat({ subagents })` passes it on, so a child cannot reset it. A refused start reaches the model as a tool error, for example `subagent limit reached (maxCalls 12)`.
+
 ## Strategy
 
 - `exclusive` (default): the chosen child owns the turn. Main does not answer after it.
diff --git a/docs/config.json b/docs/config.json
index 784c711a32..c1c32488d3 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -838,6 +838,11 @@
           "label": "Auth and connectors",
           "to": "harness/auth",
           "addedAt": "2026-09-26"
+        },
+        {
+          "label": "Run agents from a harness",
+          "to": "harness/subagents",
+          "addedAt": "2026-09-26"
         }
       ]
     },
diff --git a/docs/harness/subagents.md b/docs/harness/subagents.md
new file mode 100644
index 0000000000..71b89b77ea
--- /dev/null
+++ b/docs/harness/subagents.md
@@ -0,0 +1,108 @@
+---
+title: Run agents from a harness
+id: harness-subagents
+order: 8
+description: "Start typed agents from commands and plugins, run them in groups, call a whole harness as a child, and keep the tree within limits."
+keywords:
+  - tanstack ai
+  - harness
+  - subagents
+  - agents
+  - limits
+---
+
+A review command needs an explorer to collect facts, then a reviewer to judge them. A research task needs three explorers at once. In a harness, plugins and commands start agents from code, and a whole harness can be a child of another one.
+
+## Run agents from a plugin
+
+`ctx.agents` runs any agent of the session, or an agent you pass in. Input and result types come from the agent.
+
+```ts group=harness-subagents
+import { defineAgent } from '@tanstack/ai'
+import { defineCommand, definePlugin } from '@tanstack/ai-harness'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+const explorer = defineAgent({
+  name: 'explorer',
+  description: 'Collects facts about a topic',
+  inputSchema: z.object({ task: z.string() }),
+  run: (ctx) =>
+    ctx.chat({
+      adapter: openaiText('gpt-5.6-luna'),
+      messages: [{ role: 'user', content: ctx.input.task }],
+      stream: false,
+    }),
+})
+
+export const review = definePlugin({
+  name: 'acme/review',
+  setup: (ctx) => ({
+    agents: [explorer],
+    commands: {
+      review: defineCommand({
+        description: 'Review a topic',
+        input: z.object({ topic: z.string() }),
+        run: async ({ topic }) => {
+          const [auth, sessions] = await ctx.agents.group({ onFailure: 'cancel-siblings' }, (group) =>
+            Promise.all([
+              group.run(explorer, { task: `${topic}: auth checks` }),
+              group.run(explorer, { task: `${topic}: session expiry` }),
+            ]),
+          )
+          return `${auth}\n\n${sessions}`
+        },
+      }),
+    },
+  }),
+})
+```
+
+- `ctx.agents.run(agent, input)` runs one agent and resolves with its result.
+- `ctx.agents.start(agent, input, { wake: true })` runs it in the background and starts a turn when it is done.
+- `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.
+
+## Call a harness as a child
+
+`harnessAgent` turns a harness into an agent. Put it in `subagents.agents`, and the main model calls it as a tool. The child harness keeps its own tools, plugins, and history.
+
+```ts group=harness-subagents
+import { defineHarness, harnessAgent } from '@tanstack/ai-harness'
+
+const reviewer = defineHarness({
+  name: 'acme/reviewer',
+  description: 'Reviews a change and lists the risks',
+  adapter: openaiText('gpt-5.6'),
+})
+
+export const lead = defineHarness({
+  name: 'acme/lead',
+  adapter: openaiText('gpt-5.6'),
+  subagents: { agents: [harnessAgent(reviewer)] },
+})
+```
+
+The tool name comes from the harness name, with characters other than letters, digits, `_`, and `-` changed to `_`. Pass `name` to pick another.
+
+## Stay within limits
+
+A harness always limits its children. Without `subagents.limits`, it uses a depth of 2, 3 children at once, and 12 children per tree. Agents started from code count against the same limits:
+
+```ts group=harness-subagents
+export const careful = defineHarness({
+  name: 'acme/careful',
+  adapter: openaiText('gpt-5.6'),
+  subagents: {
+    agents: [explorer],
+    limits: { maxDepth: 1, maxConcurrent: 2, maxCalls: 6, timeoutMs: 60_000 },
+  },
+})
+```
+
+See [subagent limits](../chat/subagents) for what each limit does.
+
+## What you have now
+
+- Commands and plugins that start typed agents, alone or in groups.
+- Harnesses that call other harnesses as tools.
+- A tree of children that stays within limits.
diff --git a/packages/ai-harness/src/define.ts b/packages/ai-harness/src/define.ts
index ca22eafa31..aef7787bd7 100644
--- a/packages/ai-harness/src/define.ts
+++ b/packages/ai-harness/src/define.ts
@@ -28,6 +28,8 @@ export interface HarnessConfig<
 > {
   /** A stable name, for example `'acme/studio'`. */
   name: string
+  /** What the harness does. Shown when another agent can call it. */
+  description?: string
   /** The main agent-loop model, the same as `chat({ adapter })`. */
   adapter: TAdapter
   systemPrompts?: Array<SystemPrompt>
diff --git a/packages/ai-harness/src/harness-agent.ts b/packages/ai-harness/src/harness-agent.ts
new file mode 100644
index 0000000000..fbb7dddc58
--- /dev/null
+++ b/packages/ai-harness/src/harness-agent.ts
@@ -0,0 +1,36 @@
+import { defineAgent } from '@tanstack/ai'
+import { harnessText } from './harness-text'
+import type { AnyHarness } from './define'
+import type { HarnessHost } from './host'
+
+/**
+ * Use a whole harness as a child agent: put it in `subagents.agents` and the
+ * main model can call it as a tool, with its own tools, plugins, and history.
+ *
+ * @example
+ * ```ts
+ * defineHarness({
+ *   name: 'acme/lead',
+ *   adapter,
+ *   subagents: { agents: [harnessAgent(reviewer)] },
+ * })
+ * ```
+ */
+export function harnessAgent(
+  harness: AnyHarness,
+  options: { host?: HarnessHost; name?: string; description?: string } = {},
+) {
+  const adapter = harnessText(
+    harness,
+    options.host ? { host: options.host } : {},
+  )
+  return defineAgent({
+    // Tool names allow letters, digits, `_`, and `-`.
+    name: options.name ?? harness.name.replace(/[^a-zA-Z0-9_-]/g, '_'),
+    description:
+      options.description ??
+      harness.description ??
+      `The ${harness.name} harness`,
+    run: (ctx) => ctx.chat({ adapter }),
+  })
+}
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index 548768916e..3fda086bd6 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -14,6 +14,8 @@ export type {
   PluginDefinition,
   PluginLifetime,
   PluginPrompt,
+  AgentGroup,
+  PluginAgentActions,
   PluginSetupContext,
   PluginState,
 } from './plugins'
@@ -110,3 +112,6 @@ 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'
diff --git a/packages/ai-harness/src/plugins.ts b/packages/ai-harness/src/plugins.ts
index 347dad4ac9..d708655a19 100644
--- a/packages/ai-harness/src/plugins.ts
+++ b/packages/ai-harness/src/plugins.ts
@@ -9,7 +9,14 @@ import type {
   Capability,
   CapabilityHandle,
 } from '@tanstack/ai'
-import type { AgentRegistry, AgentRegistryView, AnyAgent } from './agents'
+import type {
+  AgentInputOf,
+  AgentRegistry,
+  AgentRegistryView,
+  AgentResultOf,
+  AnyAgent,
+} from './agents'
+import type { Operation } from './types'
 import type { CredentialsAccess } from './auth'
 import type { AnyCommand, PluginSessionApi } from './commands'
 import type { ConfigOption } from './config'
@@ -64,6 +71,61 @@ export interface PluginState<T> {
   update: (change: (current: T) => T) => Promise<T>
 }
 
+/** Run agents from a plugin: in the foreground, in the background, or as a group. */
+export interface PluginAgentActions {
+  run: {
+    <TAgent extends AnyAgent>(
+      agent: TAgent,
+      input?: AgentInputOf<TAgent>,
+    ): Operation<AgentResultOf<TAgent>>
+    (name: string, input?: unknown): Operation<unknown>
+  }
+  start: {
+    <TAgent extends AnyAgent>(
+      agent: TAgent,
+      input?: AgentInputOf<TAgent>,
+      options?: { wake?: boolean },
+    ): Operation<AgentResultOf<TAgent>>
+    (
+      name: string,
+      input?: unknown,
+      options?: { wake?: boolean },
+    ): Operation<unknown>
+  }
+  /**
+   * Run children together. With `onFailure: 'cancel-siblings'` (default), one
+   * failure cancels the others. Every child settles before `group` returns.
+   */
+  group: <T>(
+    options: { onFailure?: 'cancel-siblings' | 'collect' },
+    body: (group: AgentGroup) => Promise<T>,
+  ) => Promise<T>
+}
+
+/** The children of one `ctx.agents.group` call. */
+export interface AgentGroup {
+  run: {
+    <TAgent extends AnyAgent>(
+      agent: TAgent,
+      input?: AgentInputOf<TAgent>,
+    ): Promise<AgentResultOf<TAgent>>
+    (name: string, input?: unknown): Promise<unknown>
+  }
+  /** Like `run`, but never rejects: resolves with the result or the error. */
+  runSettled: {
+    <TAgent extends AnyAgent>(
+      agent: TAgent,
+      input?: AgentInputOf<TAgent>,
+    ): Promise<
+      { ok: true; value: AgentResultOf<TAgent> } | { ok: false; error: unknown }
+    >
+    (
+      name: string,
+      input?: unknown,
+    ): Promise<{ ok: true; value: unknown } | { ok: false; error: unknown }>
+  }
+}
+
 /** What the session gives plugins. */
 export interface PluginServices {
   emit: (plugin: string, name: string, value: unknown) => void
@@ -72,6 +134,7 @@ export interface PluginServices {
   state: <T>(plugin: string, initial: T) => PluginState<T>
   credentials: CredentialsAccess
   session: PluginSessionApi
+  agents: PluginAgentActions
 }
 
 /** What a plugin's `setup` receives. */
@@ -90,8 +153,11 @@ export interface PluginSetupContext {
   getOptional: <T>(capability: Capability<T>) => T | undefined
   /** Provide a capability this plugin declared in `provides`. */
   provide: <T>(capability: Capability<T>, value: T) => void
-  /** The agents of this session (harness agents plus earlier plugins' agents). */
-  agents: AgentRegistryView
+  /**
+   * The agents of this session (harness agents plus earlier plugins'
+   * agents): find them, and run them from commands, tools, and hooks.
+   */
+  agents: AgentRegistryView & PluginAgentActions
   /**
    * The items other plugins contributed to `point`. The list fills while
    * plugins set up, so read it at run time (in a tool, a command, or a
@@ -244,6 +310,11 @@ const NO_SERVICES: PluginServices = {
     authRequired: unavailable('ctx.session'),
     setConfig: unavailable('ctx.session'),
   },
+  agents: {
+    run: unavailable('ctx.agents.run') as PluginAgentActions['run'],
+    start: unavailable('ctx.agents.start') as PluginAgentActions['start'],
+    group: unavailable('ctx.agents.group'),
+  },
 }
 
 /** Capability values provided by plugins, keyed by handle. */
@@ -389,7 +460,14 @@ export async function mountPlugins(
           values.provide(handle, value)
           provided.add(handle)
         },
-        agents: env.registry,
+        agents: {
+          list: () => env.registry.list(),
+          get: (name) => env.registry.get(name),
+          find: (query) => env.registry.find(query),
+          run: services.agents.run,
+          start: services.agents.start,
+          group: services.agents.group,
+        },
         collect: <T>(point: ExtensionPoint<T>): ReadonlyArray<T> => {
           let items = extensions.get(point.name)
           if (!items) {
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 19c899c1e3..df0e852c08 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -1,6 +1,7 @@
 import {
   EventType,
   RUN_CANCEL_REASON,
+  SubagentBudget,
   chat,
   compactForModel,
   convertSchemaToJsonSchema,
@@ -47,8 +48,10 @@ import type {
 import type { AnyHarness, HarnessAgentsOf } from './define'
 import type { HarnessPersistence } from './host'
 import type {
+  AgentGroup,
   HarnessPlugin,
   MountedPlugins,
+  PluginAgentActions,
   PluginServices,
   PluginState,
 } from './plugins'
@@ -159,6 +162,13 @@ interface QueuedTurn {
   inputId?: string
 }
 
+/** Limits for a harness's children when `subagents.limits` is not set. */
+export const DEFAULT_SUBAGENT_LIMITS = {
+  maxDepth: 2,
+  maxConcurrent: 3,
+  maxCalls: 12,
+}
+
 function createInputId(): string {
   return `in-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`
 }
@@ -275,6 +285,23 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       state: (plugin, initial) => this.pluginState(plugin, initial),
       credentials: this.credentialAccess,
       session: this.pluginApi(),
+      agents: {
+        run: ((target: string | AnyAgent, input?: unknown) =>
+          this.runAgent(target, input, {
+            wake: false,
+          })) as PluginAgentActions['run'],
+        start: ((
+          target: string | AnyAgent,
+          input?: unknown,
+          options?: AgentStartOptions,
+        ) =>
+          this.runAgent(
+            target,
+            input,
+            options ?? {},
+          )) as PluginAgentActions['start'],
+        group: (options, body) => this.agentGroup(options, body),
+      },
     }
     this.registry = this.agentRegistry
     for (const agent of this.harness.agents ?? []) {
@@ -924,6 +951,16 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }
   }
 
+  /**
+   * A tree budget for a child started from code. The child counts as the
+   * first call, and its own children count against the same limits.
+   */
+  private codeBudget(): SubagentBudget {
+    const root = SubagentBudget.root(this.limits())
+    root.reserve(0)
+    return root.child()
+  }
+
   private binding(): SubagentBinding {
     return {
       generationMiddleware: this.sessionPlugins?.generationMiddleware ?? [],
@@ -1007,7 +1044,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           this.steering(),
         ],
         ...(subagents
-          ? { subagents: { ...subagents, binding: this.binding() } }
+          ? {
+              subagents: {
+                ...subagents,
+                limits: this.limits(),
+                binding: this.binding(),
+              },
+            }
           : {}),
         ...(this.harness.agentLoopStrategy
           ? { agentLoopStrategy: this.harness.agentLoopStrategy }
@@ -1083,28 +1126,75 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   // Agents
   // ===========================
 
+  /** The limits for children of this session, with the harness defaults. */
+  private limits() {
+    return this.harness.subagents?.limits ?? DEFAULT_SUBAGENT_LIMITS
+  }
+
   private runAgent(
-    name: string,
+    target: string | AnyAgent,
     input: unknown,
     options: AgentStartOptions,
   ): OperationImpl<unknown> {
+    const name = typeof target === 'string' ? target : target.name
     const operation = new OperationImpl<unknown>(
       'agent',
       this.feed,
-      (target) => this.cancel(target.id),
+      (running) => this.cancel(running.id),
       name,
     )
     this.operations.set(operation.id, operation)
-    void this.executeAgent(operation, name, input, options)
+    void this.executeAgent(operation, target, input, options)
     return operation
   }
 
+  /** Run a group of agents. Every child settles before the group returns. */
+  private async agentGroup<T>(
+    options: { onFailure?: 'cancel-siblings' | 'collect' },
+    body: (group: AgentGroup) => Promise<T>,
+  ): Promise<T> {
+    const started: Array<OperationImpl<unknown>> = []
+    const cancelOthers = (failed: OperationImpl<unknown>) => {
+      if (options.onFailure === 'collect') return
+      for (const operation of started) {
+        if (operation !== failed && !operation.isSettled())
+          void operation.cancel()
+      }
+    }
+    const group: AgentGroup = {
+      run: (target: string | AnyAgent, input?: unknown) => {
+        const operation = this.runAgent(target, input, { wake: false })
+        started.push(operation)
+        return Promise.resolve(operation).catch((error: unknown) => {
+          cancelOthers(operation)
+          throw error
+        })
+      },
+      runSettled: (target: string | AnyAgent, input?: unknown) => {
+        const operation = this.runAgent(target, input, { wake: false })
+        started.push(operation)
+        return Promise.resolve(operation).then(
+          (value) => ({ ok: true as const, value }),
+          (error: unknown) => ({ ok: false as const, error }),
+        )
+      },
+    } as AgentGroup
+    try {
+      return await body(group)
+    } finally {
+      await Promise.allSettled(
+        started.map((operation) => Promise.resolve(operation)),
+      )
+    }
+  }
+
   private async executeAgent(
     operation: OperationImpl<unknown>,
-    name: string,
+    target: string | AnyAgent,
     input: unknown,
     options: AgentStartOptions,
   ): Promise<void> {
+    const name = typeof target === 'string' ? target : target.name
     const inputId = createInputId()
     await this.accept(inputId, {
       op: 'agent',
@@ -1112,7 +1202,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       input,
       ...(options.wake ? { detached: true } : {}),
     })
-    const agent: AnyAgent | undefined = this.agentRegistry.get(name)
+    const agent: AnyAgent | undefined =
+      typeof target === 'string' ? this.agentRegistry.get(target) : target
     if (!agent) {
       this.reject(inputId, 'unknown_agent')
       operation.fail('failed', new Error(`Unknown agent: ${name}`))
@@ -1176,7 +1267,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         },
         undefined,
         undefined,
-        this.binding(),
+        { ...this.binding(), budget: this.codeBudget() },
       )
       for await (const chunk of stream) {
         operation.publish(chunk)
diff --git a/packages/ai-harness/tests/subagents.test.ts b/packages/ai-harness/tests/subagents.test.ts
new file mode 100644
index 0000000000..f4cc99a04d
--- /dev/null
+++ b/packages/ai-harness/tests/subagents.test.ts
@@ -0,0 +1,165 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { defineAgent } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  DEFAULT_SUBAGENT_LIMITS,
+  createHarnessHost,
+  defineCommand,
+  defineHarness,
+  definePlugin,
+  harnessAgent,
+} from '../src'
+import { mockAdapter, text, toolCall } from './helpers'
+
+describe('a harness as a child agent', () => {
+  it('lets the main model call another harness as a tool', async () => {
+    const inner = mockAdapter([() => text('Reviewed: looks good.')])
+    const reviewer = defineHarness({
+      name: 'acme/reviewer',
+      description: 'Reviews code',
+      adapter: inner.adapter,
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const child = harnessAgent(reviewer, { host })
+    expect(child.name).toBe('acme_reviewer')
+    expect(child.description).toBe('Reviews code')
+
+    const outer = mockAdapter([
+      () => toolCall('acme_reviewer', {}),
+      () => text('The reviewer approved.'),
+    ])
+    const lead = defineHarness({
+      name: 'acme/lead',
+      adapter: outer.adapter,
+      subagents: { agents: [child] },
+    })
+    const session = await host.open(lead, { threadId: 't' })
+    const turn = await session.prompt('review my change')
+    expect(turn.text).toBe('The reviewer approved.')
+    expect(JSON.stringify(outer.calls[1].messages)).toContain(
+      'Reviewed: looks good.',
+    )
+    await host.close()
+  })
+})
+
+describe('ctx.agents in plugins', () => {
+  const echo = defineAgent({
+    name: 'echo',
+    description: 'Echoes',
+    inputSchema: z.object({ text: z.string() }),
+    run: async (ctx) => ctx.input.text.toUpperCase(),
+  })
+  const failing = defineAgent({
+    name: 'failing',
+    description: 'Fails',
+    run: async () => {
+      throw new Error('boom')
+    },
+  })
+
+  it('runs agents one by one and as a group from a command', async () => {
+    let slowStopped = false
+    const slow = defineAgent({
+      name: 'slow',
+      description: 'Waits until stopped',
+      run: (ctx) =>
+        new Promise<string>((resolve) => {
+          ctx.abortSignal?.addEventListener('abort', () => {
+            slowStopped = true
+            resolve('stopped')
+          })
+        }),
+    })
+    const orchestrator = definePlugin({
+      name: 'test/orchestrator',
+      setup: (ctx) => ({
+        commands: {
+          one: defineCommand({
+            description: 'Run echo',
+            run: async () => ctx.agents.run(echo, { text: 'hi' }),
+          }),
+          both: defineCommand({
+            description: 'Run two echoes',
+            run: () =>
+              ctx.agents.group({}, (group) =>
+                Promise.all([
+                  group.run(echo, { text: 'a' }),
+                  group.run('echo', { text: 'b' }),
+                ]),
+              ),
+          }),
+          failFast: defineCommand({
+            description: 'One fails, the other is cancelled',
+            run: () =>
+              ctx.agents.group({ onFailure: 'cancel-siblings' }, (group) =>
+                Promise.all([group.run(slow), group.run(failing)]),
+              ),
+          }),
+          collect: defineCommand({
+            description: 'Collect every outcome',
+            run: () =>
+              ctx.agents.group({ onFailure: 'collect' }, (group) =>
+                Promise.all([
+                  group.runSettled(echo, { text: 'ok' }),
+                  group.runSettled(failing),
+                ]),
+              ),
+          }),
+        },
+      }),
+    })
+    const { adapter } = mockAdapter([])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/orchestrate',
+        adapter,
+        agents: [echo, failing, slow],
+        plugins: () => [orchestrator],
+      }),
+      { threadId: 't' },
+    )
+
+    expect(await session.command('one')).toBe('HI')
+    expect(await session.command('both')).toEqual(['A', 'B'])
+    await expect(session.command('failFast')).rejects.toThrow('boom')
+    expect(slowStopped).toBe(true)
+    const collected = await session.command('collect')
+    expect(collected).toMatchObject([{ ok: true, value: 'OK' }, { ok: false }])
+    await host.close()
+  })
+})
+
+describe('default limits', () => {
+  it('applies depth, concurrency, and call limits to the main model', async () => {
+    expect(DEFAULT_SUBAGENT_LIMITS).toEqual({
+      maxDepth: 2,
+      maxConcurrent: 3,
+      maxCalls: 12,
+    })
+    const run = vi.fn(async () => 'done')
+    const worker = defineAgent({ name: 'worker', description: 'Works', run })
+    const outer = mockAdapter([
+      () => toolCall('worker', {}, 'c1'),
+      () => toolCall('worker', {}, 'c2'),
+      () => text('stopped'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/limits',
+        adapter: outer.adapter,
+        subagents: { agents: [worker], limits: { maxCalls: 1 } },
+      }),
+      { threadId: 't' },
+    )
+    await session.prompt('work twice')
+    expect(run).toHaveBeenCalledTimes(1)
+    expect(JSON.stringify(outer.calls[2].messages)).toContain(
+      'subagent limit reached (maxCalls 1)',
+    )
+    await host.close()
+  })
+})
diff --git a/packages/ai/src/activities/chat/agents/bound.ts b/packages/ai/src/activities/chat/agents/bound.ts
index bc73311b1a..8cbd182921 100644
--- a/packages/ai/src/activities/chat/agents/bound.ts
+++ b/packages/ai/src/activities/chat/agents/bound.ts
@@ -15,6 +15,7 @@ import type { GenerationMiddleware } from '../../middleware/types'
 import type { AnyChatMiddleware } from '../middleware/types'
 import type { RunAgentResumeItem } from '../../../types'
 import type { SubagentRunInput } from './define-agent'
+import type { SubagentBudget } from './limits'
 
 /**
  * The fields a child `chat()` needs, in one spread:
@@ -40,6 +41,11 @@ export interface SubagentBinding {
   chatMiddleware?: ReadonlyArray<AnyChatMiddleware>
   /** Added before the call's own middleware on every generation call. */
   generationMiddleware?: ReadonlyArray<GenerationMiddleware>
+  /**
+   * The subagent tree budget. A child's `ctx.chat({ subagents })` passes it
+   * down, so limits hold across the whole tree.
+   */
+  budget?: SubagentBudget
 }
 
 /**
@@ -109,6 +115,18 @@ export function createBoundActivities(
         ...(input.resume ? { resume: input.resume } : {}),
         abortController,
         ...options,
+        // Nested children share the tree budget.
+        ...(options.subagents && binding?.budget
+          ? {
+              subagents: {
+                ...options.subagents,
+                binding: {
+                  ...options.subagents.binding,
+                  budget: binding.budget,
+                },
+              },
+            }
+          : {}),
         middleware: [...chatMiddleware, ...(options.middleware ?? [])],
       } as never)) as typeof chat,
     summarize: ((options: LooseOptions) =>
diff --git a/packages/ai/src/activities/chat/agents/limits.ts b/packages/ai/src/activities/chat/agents/limits.ts
new file mode 100644
index 0000000000..7210880ec0
--- /dev/null
+++ b/packages/ai/src/activities/chat/agents/limits.ts
@@ -0,0 +1,75 @@
+/**
+ * Limits for a whole subagent tree. The root run makes one budget, and every
+ * child shares it, so a child cannot reset it.
+ */
+export interface SubagentLimits {
+  /** How deep the tree may grow. The root run is depth 0. */
+  maxDepth?: number
+  /** How many children one run may have running at once. */
+  maxConcurrent?: number
+  /** How many children the whole tree may start. */
+  maxCalls?: number
+  /** How long one child may run. Never later than its parent's own deadline. */
+  timeoutMs?: number
+}
+
+/** The shared budget of one subagent tree. */
+export class SubagentBudget {
+  private constructor(
+    readonly limits: SubagentLimits,
+    /** The depth of the run that owns this budget view. */
+    readonly depth: number,
+    private readonly shared: { calls: number },
+    /** Epoch ms after which this run's children must stop, if any. */
+    readonly deadline: number | undefined,
+  ) {}
+
+  /** A budget for a root run. */
+  static root(limits: SubagentLimits = {}): SubagentBudget {
+    return new SubagentBudget(limits, 0, { calls: 0 }, undefined)
+  }
+
+  /** How many children the tree started so far. */
+  get calls(): number {
+    return this.shared.calls
+  }
+
+  /**
+   * Reserve one child spawn. Returns the refusal message the model sees, or
+   * `undefined` when the child may start. `active` is how many children this
+   * run has running now.
+   */
+  reserve(active: number): string | undefined {
+    const { maxDepth, maxCalls, maxConcurrent } = this.limits
+    if (maxDepth !== undefined && this.depth + 1 > maxDepth) {
+      return `subagent limit reached (maxDepth ${maxDepth})`
+    }
+    if (maxCalls !== undefined && this.shared.calls >= maxCalls) {
+      return `subagent limit reached (maxCalls ${maxCalls})`
+    }
+    if (maxConcurrent !== undefined && active >= maxConcurrent) {
+      return `subagent limit reached (maxConcurrent ${maxConcurrent})`
+    }
+    this.shared.calls += 1
+    return undefined
+  }
+
+  /** Milliseconds a child started now may run, or `undefined` for no limit. */
+  childTimeout(now = Date.now()): number | undefined {
+    const own = this.limits.timeoutMs
+    const remaining =
+      this.deadline === undefined ? undefined : Math.max(0, this.deadline - now)
+    if (own === undefined) return remaining
+    return remaining === undefined ? own : Math.min(own, remaining)
+  }
+
+  /** The budget a child's own subagents use: one level deeper, same counters. */
+  child(deadline?: number): SubagentBudget {
+    return new SubagentBudget(
+      this.limits,
+      this.depth + 1,
+      this.shared,
+      deadline ?? this.deadline,
+    )
+  }
+}
diff --git a/packages/ai/src/activities/chat/agents/spawn.ts b/packages/ai/src/activities/chat/agents/spawn.ts
index 0b3733de42..2782be0e7e 100644
--- a/packages/ai/src/activities/chat/agents/spawn.ts
+++ b/packages/ai/src/activities/chat/agents/spawn.ts
@@ -26,7 +26,9 @@ import type {
   UIMessage,
 } from '../../../types'
 import { createBoundActivities } from './bound'
+import { SubagentBudget } from './limits'
 import type { SubagentBinding } from './bound'
+import type { SubagentLimits } from './limits'
 import type {
   DefinedAgent,
   SubagentRunContext,
@@ -81,6 +83,12 @@ export interface SubagentsBag<
    */
   order?: 'parallel' | 'sequence'
   sandbox?: 'own' | 'inherit'
+  /**
+   * Limits for the whole tree of children the model starts through tools:
+   * depth, total calls, children at once, and time per child. A refused
+   * start returns to the model as a tool error.
+   */
+  limits?: SubagentLimits
   /**
    * What a host adds to every activity call a child makes through `ctx`
    * (`ctx.chat`, `ctx.generateImage`, and the rest). A harness session sets
@@ -240,6 +248,7 @@ function openAgentStream(
   ctx: SpawnContext,
   sink?: SubagentSink,
   parentToolCallId?: string,
+  binding: SubagentBinding | undefined = bag.binding,
 ) {
   const agent = agentByName(bag.agents, entry.name)
   const resume = entry.resume
@@ -273,7 +282,7 @@ function openAgentStream(
     },
     sink,
     parentToolCallId,
-    bag.binding,
+    binding,
   )
 }
 
@@ -818,6 +827,9 @@ export function createSyntheticSubagentTools(
     sink: SubagentSink
   },
 ): Array<Tool> {
+  // One budget per root run. A child run inherits its parent's budget.
+  const budget = bag.binding?.budget ?? SubagentBudget.root(bag.limits)
+  let active = 0
   return bag.agents.map((agent) => ({
     name: agent.name,
     description: agent.description,
@@ -852,8 +864,35 @@ export function createSyntheticSubagentTools(
           },
         }),
       }
+      // A resumed child already counted when it first started.
+      const refusal = suspended ? undefined : budget.reserve(active)
+      if (refusal !== undefined) {
+        return {
+          subagentRunId: '',
+          text: '',
+          error: refusal,
+        } satisfies SubagentToolOutcome
+      }
+      active += 1
       const sink = createSubagentSink()
       const link = linkAbort(parent.abortSignal)
+      const timeout = budget.childTimeout()
+      const timer =
+        timeout === undefined
+          ? undefined
+          : setTimeout(
+              () =>
+                link.controller.abort(
+                  new Error(`subagent timed out after ${timeout} ms`),
+                ),
+              timeout,
+            )
+      const childBinding: SubagentBinding = {
+        ...bag.binding,
+        budget: budget.child(
+          timeout === undefined ? undefined : Date.now() + timeout,
+        ),
+      }
       let subagentRunId = suspended?.subagentRunId ?? ''
       let text = suspended?.text ?? ''
       let error: string | undefined
@@ -873,6 +912,7 @@ export function createSyntheticSubagentTools(
           },
           sink,
           toolCallId,
+          childBinding,
         )) {
           if (chunk.type === SUBAGENT_STARTED && subagentRunId === '') {
             subagentRunId = chunk.subagentRunId
@@ -900,6 +940,8 @@ export function createSyntheticSubagentTools(
           toolContext?.[EMIT_STREAM_CHUNK]?.(chunk)
         }
       } finally {
+        active -= 1
+        if (timer !== undefined) clearTimeout(timer)
         link.dispose()
       }
       parent.sink.usage.push(...sink.usage)
diff --git a/packages/ai/src/activities/index.ts b/packages/ai/src/activities/index.ts
index c2d9013816..37fd9c9159 100644
--- a/packages/ai/src/activities/index.ts
+++ b/packages/ai/src/activities/index.ts
@@ -53,6 +53,7 @@ export type {
   SubagentBinding,
   SubagentForward,
 } from './chat/agents/bound'
+export { SubagentBudget, type SubagentLimits } from './chat/agents/limits'
 export { subagentRoute, type SubagentRouteOptions } from './chat/agents/route'
 export type {
   SubagentOrder,
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index 8e2889ab62..e442e22882 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -99,6 +99,10 @@ export type {
   SubagentBinding,
   SubagentForward,
 } from './activities/chat/agents/bound'
+export {
+  SubagentBudget,
+  type SubagentLimits,
+} from './activities/chat/agents/limits'
 export {
   subagentRoute,
   type SubagentRouteOptions,
diff --git a/packages/ai/tests/subagent-limits.test.ts b/packages/ai/tests/subagent-limits.test.ts
new file mode 100644
index 0000000000..031dcc4c86
--- /dev/null
+++ b/packages/ai/tests/subagent-limits.test.ts
@@ -0,0 +1,159 @@
+import { describe, expect, it, vi } from 'vitest'
+import { defineAgent } from '../src/activities/chat/agents/define-agent'
+import { SubagentBudget } from '../src/activities/chat/agents/limits'
+import { chat } from '../src/activities/chat'
+import { collectChunks, createMockAdapter, ev } from './test-utils'
+import type { StreamChunk } from '../src/types'
+
+/** A model that calls `name` once for each id, all in one turn, then stops. */
+function callsInOneTurn(name: string, ids: Array<string>) {
+  return createMockAdapter({
+    iterations: [
+      [
+        ev.runStarted(),
+        ...ids.flatMap((id) => [ev.toolStart(id, name), ev.toolArgs(id, '{}')]),
+        ev.runFinished('tool_calls'),
+      ],
+      [ev.runStarted(), ev.runFinished('stop')],
+    ],
+  })
+}
+
+function results(chunks: Array<StreamChunk>): Record<string, any> {
+  const out: Record<string, any> = {}
+  for (const chunk of chunks) {
+    if (
+      chunk.type === 'TOOL_CALL_RESULT' &&
+      typeof chunk.content === 'string'
+    ) {
+      out[chunk.toolCallId] = JSON.parse(chunk.content)
+    }
+  }
+  return out
+}
+
+describe('SubagentBudget', () => {
+  it('counts calls across the tree and checks depth', () => {
+    const root = SubagentBudget.root({ maxCalls: 2, maxDepth: 1 })
+    expect(root.reserve(0)).toBeUndefined()
+    const child = root.child()
+    expect(child.reserve(0)).toBe('subagent limit reached (maxDepth 1)')
+    expect(root.reserve(0)).toBeUndefined()
+    expect(root.reserve(0)).toBe('subagent limit reached (maxCalls 2)')
+    expect(child.calls).toBe(2)
+  })
+
+  it('never gives a child more time than its parent has left', () => {
+    const root = SubagentBudget.root({ timeoutMs: 10_000 })
+    expect(root.childTimeout(0)).toBe(10_000)
+    const child = root.child(5_000)
+    expect(child.childTimeout(1_000)).toBe(4_000)
+  })
+})
+
+describe('subagent limits', () => {
+  it('refuses children past maxCalls with a tool error', async () => {
+    const run = vi.fn(async () => 'done')
+    const worker = defineAgent({ name: 'worker', description: 'Works', run })
+    const { adapter } = callsInOneTurn('worker', ['c1', 'c2', 'c3'])
+    const chunks = await collectChunks(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'Go' }],
+        subagents: { agents: [worker], limits: { maxCalls: 2 } },
+      }) as AsyncIterable<StreamChunk>,
+    )
+    const byId = results(chunks)
+    const refused = Object.values(byId).filter(
+      (result) => result.error !== undefined,
+    )
+    expect(refused).toHaveLength(1)
+    expect(refused[0].error).toBe('subagent limit reached (maxCalls 2)')
+    expect(run).toHaveBeenCalledTimes(2)
+  })
+
+  it('passes the budget to nested children through ctx.chat', async () => {
+    const grandchildRun = vi.fn(async () => 'deep')
+    const grandchild = defineAgent({
+      name: 'grandchild',
+      description: 'Deep',
+      run: grandchildRun,
+    })
+    const child = defineAgent({
+      name: 'child',
+      description: 'Calls a grandchild',
+      run: (ctx) =>
+        ctx.chat({
+          adapter: callsInOneTurn('grandchild', ['g1']).adapter,
+          subagents: { agents: [grandchild] },
+        }),
+    })
+    const { adapter } = callsInOneTurn('child', ['c1'])
+    const chunks = await collectChunks(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'Go' }],
+        subagents: { agents: [child], limits: { maxDepth: 1 } },
+      }) as AsyncIterable<StreamChunk>,
+    )
+    expect(grandchildRun).not.toHaveBeenCalled()
+    const grandchildResult = chunks.find(
+      (chunk) => chunk.type === 'TOOL_CALL_RESULT' && chunk.toolCallId === 'g1',
+    )
+    expect(JSON.stringify(grandchildResult)).toContain('maxDepth 1')
+  })
+
+  it('stops a child that runs past timeoutMs', async () => {
+    const slow = defineAgent({
+      name: 'slow',
+      description: 'Never finishes on its own',
+      run: (ctx) =>
+        new Promise<string>((resolve) => {
+          ctx.abortSignal?.addEventListener('abort', () => resolve('stopped'))
+        }),
+    })
+    const { adapter } = callsInOneTurn('slow', ['c1'])
+    const chunks = await collectChunks(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'Go' }],
+        subagents: { agents: [slow], limits: { timeoutMs: 20 } },
+      }) as AsyncIterable<StreamChunk>,
+    )
+    expect(results(chunks).c1.error).toBeDefined()
+  })
+
+  it('refuses children past maxConcurrent in one turn', async () => {
+    let release!: () => void
+    const gate = new Promise<void>((resolve) => {
+      release = resolve
+    })
+    const waiting = defineAgent({
+      name: 'waiting',
+      description: 'Waits',
+      run: async () => {
+        await gate
+        return 'ok'
+      },
+    })
+    setTimeout(() => release(), 20)
+    const { adapter } = callsInOneTurn('waiting', ['c1', 'c2', 'c3'])
+    const chunks = await collectChunks(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'Go' }],
+        subagents: { agents: [waiting], limits: { maxConcurrent: 2 } },
+      }) as AsyncIterable<StreamChunk>,
+    )
+    const errors = Object.values(results(chunks))
+      .map((result) => result.error)
+      .filter(Boolean)
+    // Tool calls in one turn may run one after another; a refusal only happens
+    // when they overlap. Either way no more than two run at once.
+    expect(
+      errors.every(
+        (error) => error === 'subagent limit reached (maxConcurrent 2)',
+      ),
+    ).toBe(true)
+  })
+})
diff --git a/testing/e2e/fixtures/harness/basic.json b/testing/e2e/fixtures/harness/basic.json
index edf1a61780..f717368b80 100644
--- a/testing/e2e/fixtures/harness/basic.json
+++ b/testing/e2e/fixtures/harness/basic.json
@@ -39,6 +39,43 @@
       "response": {
         "content": "Hello over the harness protocol."
       }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-limits] work twice",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "worker",
+            "arguments": "{}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-limits] work twice",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "worker",
+            "arguments": "{}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-limits] work twice",
+        "sequenceIndex": 2
+      },
+      "response": {
+        "content": "The second call hit the limit."
+      }
     }
   ]
 }
diff --git a/testing/e2e/src/routes/api.harness-test.ts b/testing/e2e/src/routes/api.harness-test.ts
index 6b7be92b52..b66add840d 100644
--- a/testing/e2e/src/routes/api.harness-test.ts
+++ b/testing/e2e/src/routes/api.harness-test.ts
@@ -48,6 +48,30 @@ export const Route = createFileRoute('/api/harness-test')({
         const host = createHarnessHost({ persistence })
         try {
           const session = await host.open(harness, { threadId: 'e2e-thread' })
+          if (body.scenario === 'limits') {
+            // The main model calls `worker` twice. The limit allows one.
+            let workerRuns = 0
+            const worker = defineAgent({
+              name: 'worker',
+              description: 'Does one unit of work',
+              run: async () => {
+                workerRuns += 1
+                return 'worked'
+              },
+            })
+            const limited = defineHarness({
+              name: 'e2e/harness-limits',
+              adapter: openai(),
+              subagents: { agents: [worker], limits: { maxCalls: 1 } },
+            })
+            const limitedSession = await host.open(limited, {
+              threadId: 'e2e-limits',
+            })
+            const turn = await limitedSession.prompt(
+              '[harness-limits] work twice',
+            )
+            return Response.json({ workerRuns, text: turn.text })
+          }
           if (body.scenario === 'agent') {
             const result = await session.agents.pricer.run({
               task: '[harness-agent] price vendor a',
diff --git a/testing/e2e/tests/harness.spec.ts b/testing/e2e/tests/harness.spec.ts
index 03e3c458a5..609a642592 100644
--- a/testing/e2e/tests/harness.spec.ts
+++ b/testing/e2e/tests/harness.spec.ts
@@ -15,6 +15,20 @@ test.describe('harness session', () => {
     expect(body.roles).toEqual(['user', 'assistant', 'user', 'assistant'])
   })
 
+  test('subagent limits refuse the second child start', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'limits', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    const body = await response.json()
+    expect(body.workerRuns).toBe(1)
+    expect(body.text).toBe('The second call hit the limit.')
+  })
+
   test('a typed agent runs from code and the next turn sees its result', async ({
     request,
     testId,

From bd1ac5bc77e49c5d54a7f7b7d3e8ef222cd142b6 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 13:22:50 +0200
Subject: [PATCH 011/286] feat(ai-harness): build artifacts, worker mode, and
 remote harnessText

@tanstack/ai-harness/build: buildHarness bundles a harness with Bun into a
worker artifact (harness.js) plus harness.manifest.json (name, agents,
plugins, requirements, sha256 digest), and can compile a single executable.
artifactText(dir) checks the digest, starts one worker process per thread,
and uses it as a text adapter.

@tanstack/ai-harness/worker: runHarnessWorker serves session-tier frames as
NDJSON on stdin and stdout.

harnessText({ url, token }) uses a harness served on another machine (for
example with runCli --serve) as a text adapter.
---
 .changeset/harness-p5-build.md             |   9 +
 docs/config.json                           |   5 +
 docs/harness/deploy.md                     |  97 +++++
 packages/ai-harness/package.json           |   8 +
 packages/ai-harness/src/build.ts           | 428 +++++++++++++++++++++
 packages/ai-harness/src/harness-text.ts    | 136 +++++++
 packages/ai-harness/src/index.ts           |   2 +-
 packages/ai-harness/src/worker.ts          |  84 ++++
 packages/ai-harness/tests/build.test.ts    | 195 ++++++++++
 packages/ai-harness/vite.config.ts         |   4 +-
 testing/e2e/src/routes/api.harness-test.ts |  25 +-
 testing/e2e/tests/harness.spec.ts          |  14 +
 12 files changed, 1003 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/harness-p5-build.md
 create mode 100644 docs/harness/deploy.md
 create mode 100644 packages/ai-harness/src/build.ts
 create mode 100644 packages/ai-harness/src/worker.ts
 create mode 100644 packages/ai-harness/tests/build.test.ts

diff --git a/.changeset/harness-p5-build.md b/.changeset/harness-p5-build.md
new file mode 100644
index 0000000000..0a6e2a896d
--- /dev/null
+++ b/.changeset/harness-p5-build.md
@@ -0,0 +1,9 @@
+---
+'@tanstack/ai-harness': minor
+---
+
+Run a harness outside your server.
+
+- **`@tanstack/ai-harness/build`**: `buildHarness` bundles a harness with Bun into a worker artifact (`harness.js`) and writes `harness.manifest.json` (name, agents, plugins, requirements, sha256 digest). With `compile`, it also builds a single executable. `artifactText(dir)` runs the artifact as worker processes and uses it as a text adapter, after it checks the digest. `readManifest` reads and checks a manifest.
+- **`@tanstack/ai-harness/worker`**: `runHarnessWorker` serves a harness as session-tier frames over NDJSON on stdin and stdout.
+- **`harnessText({ url, token })`** uses a harness served by `createHarnessHandler` (or `runCli --serve`) on another machine as a text adapter.
diff --git a/docs/config.json b/docs/config.json
index c1c32488d3..533ad81083 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -843,6 +843,11 @@
           "label": "Run agents from a harness",
           "to": "harness/subagents",
           "addedAt": "2026-09-26"
+        },
+        {
+          "label": "Deploy a harness",
+          "to": "harness/deploy",
+          "addedAt": "2026-09-26"
         }
       ]
     },
diff --git a/docs/harness/deploy.md b/docs/harness/deploy.md
new file mode 100644
index 0000000000..d6d22b92db
--- /dev/null
+++ b/docs/harness/deploy.md
@@ -0,0 +1,97 @@
+---
+title: Deploy a harness
+id: harness-deploy
+order: 9
+description: "Run a harness in your server, as a worker process, on another machine, or as a single executable."
+keywords:
+  - tanstack ai
+  - harness
+  - deploy
+  - build
+  - worker
+---
+
+Your harness works on your laptop. Now it needs to run next to your API, in its own process, on a different machine, or as a CLI your team can download. You pick the place. The harness definition stays the same.
+
+| Place | How |
+|---|---|
+| Your server | `createHarnessHost` and `createHarnessHandler` in your routes. No build step. |
+| A worker process | `buildHarness`, then `artifactText(dir)` as the model of a `chat()` call. |
+| Another machine | `runCli(harness)` with `--serve` there, then `harnessText({ url, token })` here. |
+| A single executable | `buildHarness({ compile })` with Bun. |
+
+## Build a worker artifact
+
+`buildHarness` bundles the harness with Bun and writes a manifest next to it. Install [Bun](https://bun.sh) on the build machine.
+
+```ts group=harness-deploy
+import { artifactText, buildHarness } from '@tanstack/ai-harness/build'
+
+const { manifest } = await buildHarness({
+  entry: './src/studio.ts',
+  export: 'studio',
+  outDir: './dist/studio',
+})
+console.log(manifest.name, manifest.digest)
+```
+
+- `dist/studio/harness.js` starts the harness as a worker. It reads session frames on stdin and writes them on stdout.
+- `dist/studio/harness.manifest.json` names the harness, its agents and plugins, what it needs (file system, processes, network), and the sha256 digest of the bundle.
+
+The build imports your entry in a child process to read the harness name, agents, and plugins. Importing a module runs its code.
+
+## Run the artifact as a model
+
+`artifactText` starts one worker process per outer thread and checks the digest first. A changed bundle is refused.
+
+```ts group=harness-deploy
+import { chat } from '@tanstack/ai'
+
+const model = await artifactText('./dist/studio')
+const stream = chat({
+  adapter: model,
+  messages: [{ role: 'user', content: 'Plan the launch post.' }],
+  threadId: 'thread-1',
+})
+// When you are done with the workers:
+model.dispose()
+```
+
+The worker keeps the conversation of its thread between calls. Workers get the environment of the process that starts them, so they can read your provider keys.
+
+## Use a harness on another machine
+
+On the other machine, serve the harness with the CLI. It prints a token unless you set one:
+
+```bash
+HARNESS_TOKEN=your-token npx tsx cli.ts --serve --host 0.0.0.0
+```
+
+Here, use it as a model:
+
+```ts group=harness-deploy
+import { harnessText } from '@tanstack/ai-harness'
+
+const remote = harnessText({ url: 'http://build-box:8787', token: 'your-token' })
+```
+
+The remote session keeps the conversation, so each call sends only the new message.
+
+## Ship a single executable
+
+Point `compile.entry` at a file that calls `runCli`:
+
+```ts group=harness-deploy
+await buildHarness({
+  entry: './src/studio.ts',
+  export: 'studio',
+  outDir: './dist/studio',
+  compile: { entry: './src/cli.ts', outfile: './dist/studio-cli', target: 'bun-linux-x64' },
+})
+```
+
+Bun can build for another platform with `target`, for example `bun-darwin-arm64` or `bun-windows-x64`.
+
+## What you have now
+
+- The same harness in your server, in a worker process, on another machine, or as a binary.
diff --git a/packages/ai-harness/package.json b/packages/ai-harness/package.json
index 01b208a614..fcecc105a1 100644
--- a/packages/ai-harness/package.json
+++ b/packages/ai-harness/package.json
@@ -37,6 +37,14 @@
     "./plugins": {
       "types": "./dist/esm/first-party/index.d.ts",
       "import": "./dist/esm/first-party/index.js"
+    },
+    "./build": {
+      "types": "./dist/esm/build.d.ts",
+      "import": "./dist/esm/build.js"
+    },
+    "./worker": {
+      "types": "./dist/esm/worker.d.ts",
+      "import": "./dist/esm/worker.js"
     }
   },
   "scripts": {
diff --git a/packages/ai-harness/src/build.ts b/packages/ai-harness/src/build.ts
new file mode 100644
index 0000000000..4d3cf074e8
--- /dev/null
+++ b/packages/ai-harness/src/build.ts
@@ -0,0 +1,428 @@
+import { spawn } from 'node:child_process'
+import { createHash, randomUUID } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { createInterface } from 'node:readline'
+import { fileURLToPath } from 'node:url'
+import { EventType } from '@tanstack/ai'
+import { HARNESS_PROTOCOL_VERSION } from './protocol'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import type { HostFrame } from './protocol'
+
+/** What a built harness says about itself. Fields are claims; deploy policy decides. */
+export interface HarnessManifestV1 {
+  format: 'tanstack-ai-harness'
+  version: 1
+  name: string
+  /** sha256 of the bundle. */
+  digest: string
+  /** The bundle file, relative to the manifest. */
+  entry: string
+  runtime: { kind: 'node'; major: number }
+  protocol: typeof HARNESS_PROTOCOL_VERSION
+  agents: Array<{ name: string; produces?: string }>
+  plugins: Array<{ name: string }>
+  requires: {
+    filesystem: boolean
+    processExecution: boolean
+    network: 'model-only' | 'declared'
+  }
+}
+
+export interface BuildHarnessOptions {
+  /** The module that exports the harness. */
+  entry: string
+  /** The export name. Default `'default'`. */
+  export?: string
+  outDir: string
+  /**
+   * Also build a single executable of `compile.entry` (for example a file
+   * that calls `runCli`) with Bun.
+   */
+  compile?: { entry: string; outfile: string; target?: string }
+  /** The Bun executable. Default `'bun'`. */
+  bun?: string
+}
+
+const MANIFEST = 'harness.manifest.json'
+const BUNDLE = 'harness.js'
+
+function run(
+  command: string,
+  args: Array<string>,
+  cwd: string,
+): Promise<string> {
+  // On Windows, npm installs Bun as a `.cmd` shim, which only a shell can
+  // start. The arguments are paths this module builds, quoted for cmd.
+  const viaShell = process.platform === 'win32' && !/\.exe$/i.test(command)
+  return new Promise((done, fail) => {
+    const child = viaShell
+      ? spawn(
+          command,
+          args.map((arg) => `"${arg}"`),
+          { cwd, stdio: ['ignore', 'pipe', 'pipe'], shell: true },
+        )
+      : spawn(command, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] })
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', (data: Buffer) => (stdout += data.toString()))
+    child.stderr.on('data', (data: Buffer) => (stderr += data.toString()))
+    child.on('error', (error) =>
+      fail(
+        new Error(
+          `Could not run ${command}. buildHarness uses Bun: install it from https://bun.sh. (${error.message})`,
+        ),
+      ),
+    )
+    child.on('close', (code) =>
+      code === 0
+        ? done(stdout)
+        : fail(
+            new Error(
+              `${command} ${args[0] ?? ''} failed:\n${stderr || stdout}`,
+            ),
+          ),
+    )
+  })
+}
+
+/**
+ * Bundle a harness into a worker artifact: `harness.js` (starts a worker on
+ * stdin and stdout) and `harness.manifest.json`. With `compile`, also build a
+ * single executable.
+ *
+ * The build imports `entry` in a child process to read the harness name,
+ * agents, and plugin names. Importing a module runs its code.
+ */
+export async function buildHarness(
+  options: BuildHarnessOptions,
+): Promise<{
+  manifest: HarnessManifestV1
+  bundle: string
+  executable?: string
+}> {
+  const bun = options.bun ?? 'bun'
+  const entry = resolve(options.entry)
+  const outDir = resolve(options.outDir)
+  const exportName = options.export ?? 'default'
+  // Bun resolves plain absolute paths, not file:// URLs. Forward slashes
+  // keep Windows paths valid inside the generated modules.
+  const slash = (path: string) => path.split('\\').join('/')
+  const entryPath = slash(entry)
+  const builtWorker = fileURLToPath(new URL('./worker.js', import.meta.url))
+  // From source (tests), the worker module is still TypeScript.
+  const workerModule = slash(
+    existsSync(builtWorker) ? builtWorker : builtWorker.replace(/\.js$/, '.ts'),
+  )
+  await mkdir(outDir, { recursive: true })
+
+  // Temporary files sit next to the entry, so its imports resolve the same way.
+  const id = randomUUID().slice(0, 8)
+  const bootstrap = join(dirname(entry), `.harness-worker-${id}.mjs`)
+  const describe = join(dirname(entry), `.harness-describe-${id}.mjs`)
+  await writeFile(
+    bootstrap,
+    [
+      `import * as entry from ${JSON.stringify(entryPath)}`,
+      `import { runHarnessWorker } from ${JSON.stringify(workerModule)}`,
+      `await runHarnessWorker(entry[${JSON.stringify(exportName)}])`,
+    ].join('\n'),
+  )
+  await writeFile(
+    describe,
+    [
+      `const entry = await import(${JSON.stringify(entryPath)})`,
+      `const harness = entry[${JSON.stringify(exportName)}]`,
+      `if (!harness || harness.kind !== 'tanstack-ai-harness') throw new Error('Export ${exportName} of ${entry.replace(/\\/g, '/')} is not a harness.')`,
+      `const agents = [...(harness.agents ?? []), ...(harness.subagents?.agents ?? [])]`,
+      `const plugins = harness.plugins ? harness.plugins().map((plugin) => ({ name: plugin.name })) : []`,
+      `console.log(JSON.stringify({ name: harness.name, agents: agents.map((agent) => ({ name: agent.name, ...(agent.produces ? { produces: agent.produces } : {}) })), plugins }))`,
+    ].join('\n'),
+  )
+
+  try {
+    const bundle = join(outDir, BUNDLE)
+    await run(
+      bun,
+      ['build', bootstrap, '--target=node', `--outfile=${bundle}`],
+      dirname(entry),
+    )
+    const described: {
+      name: string
+      agents: HarnessManifestV1['agents']
+      plugins: HarnessManifestV1['plugins']
+    } = JSON.parse(
+      (await run(bun, [describe], dirname(entry))).trim().split('\n').at(-1) ??
+        '{}',
+    )
+    const names = described.plugins.map((plugin) => plugin.name)
+    const usesWorkspace = names.includes('tanstack/workspace-tools')
+    const manifest: HarnessManifestV1 = {
+      format: 'tanstack-ai-harness',
+      version: 1,
+      name: described.name,
+      digest: createHash('sha256')
+        .update(await readFile(bundle))
+        .digest('hex'),
+      entry: BUNDLE,
+      runtime: {
+        kind: 'node',
+        major: Number(process.versions.node.split('.')[0]),
+      },
+      protocol: HARNESS_PROTOCOL_VERSION,
+      agents: described.agents,
+      plugins: described.plugins,
+      requires: {
+        filesystem:
+          usesWorkspace || names.includes('tanstack/project-instructions'),
+        processExecution: usesWorkspace,
+        network: names.some((name) => name.startsWith('connector/'))
+          ? 'declared'
+          : 'model-only',
+      },
+    }
+    await writeFile(
+      join(outDir, MANIFEST),
+      `${JSON.stringify(manifest, null, 2)}\n`,
+    )
+
+    let executable: string | undefined
+    if (options.compile) {
+      executable = resolve(options.compile.outfile)
+      await run(
+        bun,
+        [
+          'build',
+          resolve(options.compile.entry),
+          '--compile',
+          `--outfile=${executable}`,
+          ...(options.compile.target
+            ? [`--target=${options.compile.target}`]
+            : []),
+        ],
+        dirname(resolve(options.compile.entry)),
+      )
+    }
+    return { manifest, bundle, ...(executable ? { executable } : {}) }
+  } finally {
+    await rm(bootstrap, { force: true })
+    await rm(describe, { force: true })
+  }
+}
+
+/** Read and check the manifest of a built harness. */
+export async function readManifest(dir: string): Promise<HarnessManifestV1> {
+  const manifest: unknown = JSON.parse(
+    await readFile(join(resolve(dir), MANIFEST), 'utf8'),
+  )
+  if (
+    typeof manifest !== 'object' ||
+    manifest === null ||
+    !('format' in manifest) ||
+    manifest.format !== 'tanstack-ai-harness' ||
+    !('version' in manifest) ||
+    manifest.version !== 1
+  ) {
+    throw new Error(`${dir} has no tanstack-ai-harness v1 manifest.`)
+  }
+  // The format and version checks above identify the file.
+  return manifest as HarnessManifestV1
+}
+
+const FORWARDED = new Set<string>([
+  EventType.TEXT_MESSAGE_START,
+  EventType.TEXT_MESSAGE_CONTENT,
+  EventType.TEXT_MESSAGE_END,
+  EventType.REASONING_START,
+  EventType.REASONING_MESSAGE_START,
+  EventType.REASONING_MESSAGE_CONTENT,
+  EventType.REASONING_MESSAGE_END,
+  EventType.REASONING_END,
+])
+
+interface Worker {
+  send: (frame: object) => void
+  frames: (listener: (frame: HostFrame) => void) => () => void
+  kill: () => void
+}
+
+function startWorker(node: string, bundle: string, threadId: string): Worker {
+  const child = spawn(node, [bundle], { stdio: ['pipe', 'pipe', 'inherit'] })
+  const listeners = new Set<(frame: HostFrame) => void>()
+  createInterface({ input: child.stdout }).on('line', (line) => {
+    try {
+      const frame = JSON.parse(line) as HostFrame
+      for (const listener of listeners) listener(frame)
+    } catch {
+      // A line that is not a frame (for example a stray log) is skipped.
+    }
+  })
+  const send = (frame: object) =>
+    child.stdin.write(`${JSON.stringify(frame)}\n`)
+  send({ type: 'harness.subscribe', threadId })
+  return {
+    send,
+    frames: (listener) => {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+    kill: () => {
+      child.stdin.end()
+      child.kill()
+    },
+  }
+}
+
+function lastUserText(messages: unknown): string {
+  const list: ReadonlyArray<unknown> = Array.isArray(messages) ? messages : []
+  const message = list.findLast(
+    (entry) =>
+      typeof entry === 'object' &&
+      entry !== null &&
+      'role' in entry &&
+      entry.role === 'user',
+  )
+  if (
+    typeof message !== 'object' ||
+    message === null ||
+    !('content' in message)
+  )
+    return ''
+  return typeof message.content === 'string' ? message.content : ''
+}
+
+/**
+ * Use a built harness as the model of a `chat()` call. Each outer thread gets
+ * its own worker process (`node harness.js`). Call `dispose()` to stop them.
+ */
+export async function artifactText(
+  dir: string,
+  options: { node?: string } = {},
+): Promise<AnyTextAdapter & { dispose: () => void }> {
+  const manifest = await readManifest(dir)
+  const bundle = join(resolve(dir), manifest.entry)
+  const digest = createHash('sha256')
+    .update(await readFile(bundle))
+    .digest('hex')
+  if (digest !== manifest.digest) {
+    throw new Error(`The bundle in ${dir} does not match its manifest digest.`)
+  }
+  const workers = new Map<string, Worker>()
+  let requests = 0
+
+  return {
+    kind: 'text',
+    name: 'harness-artifact',
+    model: manifest.name,
+    '~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,
+    },
+    dispose: () => {
+      for (const worker of workers.values()) worker.kill()
+      workers.clear()
+    },
+    structuredOutput: () =>
+      Promise.reject(
+        new Error('artifactText does not support structured output.'),
+      ),
+    chatStream: (chatOptions) =>
+      (async function* (): AsyncGenerator<StreamChunk> {
+        const threadId = chatOptions.threadId ?? 'default'
+        let worker = workers.get(threadId)
+        if (!worker) {
+          worker = startWorker(
+            options.node ?? process.execPath,
+            bundle,
+            threadId,
+          )
+          workers.set(threadId, worker)
+        }
+        const runId = chatOptions.runId ?? `artifact-${Date.now().toString(36)}`
+        const requestId = `r${(requests += 1)}`
+        const queue: Array<HostFrame> = []
+        let wake: (() => void) | undefined
+        const stop = worker.frames((frame) => {
+          queue.push(frame)
+          wake?.()
+        })
+        worker.send({
+          type: 'harness.input',
+          requestId,
+          input: { op: 'prompt', message: lastUserText(chatOptions.messages) },
+        })
+        yield {
+          type: EventType.RUN_STARTED,
+          runId,
+          threadId,
+          timestamp: Date.now(),
+        }
+        let operationId: string | undefined
+        const early: Array<Extract<HostFrame, { type: 'harness.event' }>> = []
+        try {
+          while (true) {
+            if (queue.length === 0) {
+              await new Promise<void>((resolveWait) => (wake = resolveWait))
+              wake = undefined
+            }
+            const frame = queue.shift()
+            if (!frame) continue
+            if (frame.type === 'harness.error') throw new Error(frame.message)
+            if (
+              frame.type === 'harness.receipt' &&
+              frame.requestId === requestId
+            ) {
+              if (frame.status === 'rejected')
+                throw new Error(
+                  frame.reason ?? 'The worker refused the prompt.',
+                )
+              operationId = frame.operationId
+              queue.unshift(
+                ...early.filter((entry) => entry.operationId === operationId),
+              )
+              continue
+            }
+            if (frame.type !== 'harness.event') continue
+            if (!operationId) {
+              early.push(frame)
+              continue
+            }
+            if (frame.operationId !== operationId) continue
+            const event = frame.event
+            if (
+              FORWARDED.has(event.type) &&
+              !('subagentRunId' in event && event.subagentRunId)
+            )
+              yield event
+            if (event.type === EventType.RUN_ERROR)
+              throw new Error(event.message)
+            if (
+              event.type === EventType.CUSTOM &&
+              event.name === 'harness.operation.finished'
+            )
+              break
+          }
+        } finally {
+          stop()
+        }
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId,
+          threadId,
+          timestamp: Date.now(),
+          metadata: { tanstack: { finishReason: 'stop' } },
+        }
+      })(),
+  }
+}
diff --git a/packages/ai-harness/src/harness-text.ts b/packages/ai-harness/src/harness-text.ts
index 51b0aa7a21..2550d5c659 100644
--- a/packages/ai-harness/src/harness-text.ts
+++ b/packages/ai-harness/src/harness-text.ts
@@ -1,6 +1,7 @@
 import { EventType } from '@tanstack/ai'
 import { createHarnessHost } from './host'
 import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import { isHarnessDefinition } from './define'
 import type { AnyHarness } from './define'
 import type { HarnessHost } from './host'
 
@@ -54,10 +55,145 @@ const FORWARDED = new Set<string>([
  * const stream = chat({ adapter: harnessText(studio), messages, threadId })
  * ```
  */
+/** A harness served by `createHarnessHandler` (or `runCli --serve`) on another machine. */
+export interface RemoteHarness {
+  /** The handler base URL, for example `http://127.0.0.1:8787`. */
+  url: string
+  /** The bearer token. */
+  token?: string
+  fetch?: typeof fetch
+}
+
+const 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,
+}
+
+/** Stream the SSE `data:` payloads of a response. */
+async function* sseData(response: Response): AsyncGenerator<unknown> {
+  if (!response.body) return
+  const reader = response.body.getReader()
+  const decoder = new TextDecoder()
+  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) yield JSON.parse(data)
+    }
+  }
+}
+
+function remoteHarnessText(remote: RemoteHarness): AnyTextAdapter {
+  const base = remote.url.replace(/\/$/, '')
+  const doFetch = remote.fetch ?? fetch
+  return {
+    kind: 'text',
+    name: 'harness-remote',
+    model: base,
+    '~types': TYPES,
+    structuredOutput: () =>
+      Promise.reject(
+        new Error('harnessText does not support structured output.'),
+      ),
+    chatStream: (chatOptions) =>
+      (async function* (): AsyncGenerator<StreamChunk> {
+        const threadId = chatOptions.threadId ?? 'default'
+        const runId = chatOptions.runId ?? `harness-${Date.now().toString(36)}`
+        const response = await doFetch(`${base}/run`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...(remote.token
+              ? { Authorization: `Bearer ${remote.token}` }
+              : {}),
+          },
+          body: JSON.stringify({
+            threadId,
+            runId,
+            // The remote session keeps its own history, so send the new message only.
+            messages: [
+              {
+                id: `${runId}-user`,
+                role: 'user',
+                content: lastUserText(chatOptions.messages),
+              },
+            ],
+            tools: [],
+            context: [],
+            state: {},
+            forwardedProps: {},
+          }),
+        })
+        if (!response.ok) {
+          throw new Error(
+            `Remote harness failed (${response.status}): ${await response.text()}`,
+          )
+        }
+        yield {
+          type: EventType.RUN_STARTED,
+          runId,
+          threadId,
+          timestamp: Date.now(),
+        }
+        for await (const data of sseData(response)) {
+          if (!isRecord(data) || typeof data.type !== 'string') continue
+          // The handler sends AG-UI chunks over SSE.
+          const chunk = data as StreamChunk
+          if (
+            FORWARDED.has(chunk.type) &&
+            !('subagentRunId' in chunk && chunk.subagentRunId)
+          ) {
+            yield chunk
+          }
+          if (chunk.type === EventType.RUN_ERROR) {
+            yield {
+              type: EventType.RUN_ERROR,
+              message: chunk.message,
+              timestamp: Date.now(),
+            }
+            return
+          }
+        }
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId,
+          threadId,
+          timestamp: Date.now(),
+          metadata: { tanstack: { finishReason: 'stop' } },
+        }
+      })(),
+  }
+}
+
 export function harnessText(
   harness: AnyHarness,
+  options?: HarnessTextOptions,
+): AnyTextAdapter
+export function harnessText(remote: RemoteHarness): AnyTextAdapter
+export function harnessText(
+  target: AnyHarness | RemoteHarness,
   options: HarnessTextOptions = {},
 ): AnyTextAdapter {
+  if (!isHarnessDefinition(target)) return remoteHarnessText(target)
+  const harness = target
   let host = options.host
   return {
     kind: 'text',
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index 3fda086bd6..cc4fa6a623 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -97,7 +97,7 @@ export type {
 } from './http'
 
 export { harnessText } from './harness-text'
-export type { HarnessTextOptions } from './harness-text'
+export type { HarnessTextOptions, RemoteHarness } from './harness-text'
 
 export {
   buildAuthorizationUrl,
diff --git a/packages/ai-harness/src/worker.ts b/packages/ai-harness/src/worker.ts
new file mode 100644
index 0000000000..233b005c31
--- /dev/null
+++ b/packages/ai-harness/src/worker.ts
@@ -0,0 +1,84 @@
+import { createInterface } from 'node:readline'
+import { createHarnessHost } from './host'
+import {
+  HARNESS_PROTOCOL_VERSION,
+  applyInput,
+  parseControlFrame,
+} from './protocol'
+import type { AnyHarness } from './define'
+import type { HarnessPersistence } from './host'
+import type { HostFrame } from './protocol'
+
+export interface HarnessWorkerOptions {
+  input?: NodeJS.ReadableStream
+  output?: { write: (text: string) => unknown }
+  persistence?: HarnessPersistence
+}
+
+/**
+ * Run a harness as a worker: session-tier frames as NDJSON on stdin and
+ * stdout. The first frame must be `harness.subscribe`. The worker exits when
+ * stdin closes. `artifactText` starts workers like this.
+ */
+export async function runHarnessWorker(
+  harness: AnyHarness,
+  options: HarnessWorkerOptions = {},
+): Promise<void> {
+  const output = options.output ?? process.stdout
+  const send = (frame: HostFrame) => output.write(`${JSON.stringify(frame)}\n`)
+  const host = createHarnessHost(
+    options.persistence ? { persistence: options.persistence } : {},
+  )
+  const reader = new AbortController()
+  let session: Awaited<ReturnType<typeof host.open>> | undefined
+  const lines = createInterface({
+    input: options.input ?? process.stdin,
+    crlfDelay: Infinity,
+  })
+
+  try {
+    for await (const line of lines) {
+      if (line.trim() === '') continue
+      try {
+        const frame = parseControlFrame(line)
+        if (frame.type === 'harness.subscribe') {
+          if (session) throw new Error('Already subscribed.')
+          session = await host.open(harness, { threadId: frame.threadId })
+          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 })
+          })()
+          continue
+        }
+        if (!session) throw new Error('Send harness.subscribe first.')
+        if (frame.type === 'harness.snapshot') {
+          send({ type: 'harness.snapshot', snapshot: session.snapshot() })
+          continue
+        }
+        const receipt = await applyInput(harness, session, frame.input)
+        send({
+          type: 'harness.receipt',
+          requestId: frame.requestId,
+          ...receipt,
+        })
+      } catch (error) {
+        send({
+          type: 'harness.error',
+          message: error instanceof Error ? error.message : String(error),
+        })
+      }
+    }
+  } finally {
+    reader.abort()
+    await host.close()
+  }
+}
diff --git a/packages/ai-harness/tests/build.test.ts b/packages/ai-harness/tests/build.test.ts
new file mode 100644
index 0000000000..90cd18fbd8
--- /dev/null
+++ b/packages/ai-harness/tests/build.test.ts
@@ -0,0 +1,195 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { PassThrough } from 'node:stream'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+import { afterAll, describe, expect, it } from 'vitest'
+import { EventType, chat } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  createHarnessHandler,
+  createHarnessHost,
+  defineHarness,
+  harnessText,
+} from '../src'
+import { artifactText, buildHarness, readManifest } from '../src/build'
+import { runHarnessWorker } from '../src/worker'
+import { mockAdapter, text } from './helpers'
+import type { StreamChunk } from '@tanstack/ai'
+
+async function textOf(stream: AsyncIterable<StreamChunk>): Promise<string> {
+  let out = ''
+  for await (const chunk of stream) {
+    if (chunk.type === EventType.TEXT_MESSAGE_CONTENT) out += chunk.delta
+    if (chunk.type === EventType.RUN_ERROR) throw new Error(chunk.message)
+  }
+  return out
+}
+
+describe('worker mode', () => {
+  it('speaks session frames over NDJSON', async () => {
+    const { adapter } = mockAdapter([() => text('from the worker')])
+    const input = new PassThrough()
+    const lines: Array<any> = []
+    const running = runHarnessWorker(
+      defineHarness({ name: 'test/worker', adapter }),
+      {
+        input,
+        output: { write: (line: string) => lines.push(JSON.parse(line)) },
+        persistence: memoryPersistence(),
+      },
+    )
+    input.write('{"type":"harness.subscribe","threadId":"w1"}\n')
+    input.write(
+      '{"type":"harness.input","requestId":"r1","input":{"op":"prompt","message":"hi"}}\n',
+    )
+    await new Promise<void>((resolve) => {
+      const check = setInterval(() => {
+        if (
+          lines.some(
+            (frame) => frame.event?.name === 'harness.operation.finished',
+          )
+        ) {
+          clearInterval(check)
+          resolve()
+        }
+      }, 10)
+    })
+    input.end()
+    await running
+    expect(lines[0]).toMatchObject({ type: 'harness.hello', threadId: 'w1' })
+    expect(
+      lines.find((frame) => frame.type === 'harness.receipt'),
+    ).toMatchObject({ requestId: 'r1', status: 'accepted' })
+    expect(JSON.stringify(lines)).toContain('from the worker')
+  })
+})
+
+describe('harnessText({ url })', () => {
+  it('uses a harness served over HTTP as a model', async () => {
+    const { adapter } = mockAdapter([() => text('from far away')])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const handler = createHarnessHandler({
+      host,
+      harness: defineHarness({ name: 'test/remote', adapter }),
+      authorize: (request) =>
+        request.headers.get('authorization') === 'Bearer t'
+          ? { id: 'u' }
+          : null,
+    })
+    const remote = harnessText({
+      url: 'http://remote.test/api',
+      token: 't',
+      fetch: (input, init) => handler(new Request(input, init)),
+    })
+    const answer = await textOf(
+      chat({
+        adapter: remote,
+        messages: [{ role: 'user', content: 'hi' }],
+        threadId: 'r',
+      }) as AsyncIterable<StreamChunk>,
+    )
+    expect(answer).toBe('from far away')
+    await host.close()
+  })
+})
+
+const tmp = fileURLToPath(new URL('./.tmp-build/', import.meta.url))
+
+describe('buildHarness and artifactText', () => {
+  afterAll(async () => {
+    await rm(tmp, { recursive: true, force: true })
+  })
+
+  it(
+    'bundles a harness, writes a manifest, and runs it as a worker process',
+    { timeout: 60_000 },
+    async () => {
+      await mkdir(tmp, { recursive: true })
+      const entry = join(tmp, 'studio.ts')
+      await writeFile(
+        entry,
+        `
+import { EventType, defineAgent } from '@tanstack/ai'
+import { defineHarness } from '../../src/index'
+
+let calls = 0
+const adapter = {
+  kind: 'text',
+  name: 'inline',
+  model: 'inline-model',
+  '~types': {},
+  structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+  chatStream: (options) =>
+    (async function* () {
+      calls += 1
+      const now = Date.now()
+      const messageId = 'm-' + calls
+      yield { type: EventType.RUN_STARTED, runId: 'r', threadId: 't', timestamp: now }
+      yield { type: EventType.TEXT_MESSAGE_START, messageId, role: 'assistant', timestamp: now }
+      yield { type: EventType.TEXT_MESSAGE_CONTENT, messageId, delta: 'worker saw ' + options.messages.length + ' messages', timestamp: now }
+      yield { type: EventType.TEXT_MESSAGE_END, messageId, timestamp: now }
+      yield { type: EventType.RUN_FINISHED, runId: 'r', threadId: 't', timestamp: now, metadata: { tanstack: { finishReason: 'stop' } } }
+    })(),
+}
+
+export const studio = defineHarness({
+  name: 'acme/built',
+  adapter,
+  agents: [defineAgent({ name: 'painter', description: 'Paints', produces: 'image', run: async () => 'art' })],
+})
+`,
+      )
+
+      const outDir = join(tmp, 'out')
+      const { manifest, bundle } = await buildHarness({
+        entry,
+        export: 'studio',
+        outDir,
+      })
+      expect(manifest).toMatchObject({
+        format: 'tanstack-ai-harness',
+        version: 1,
+        name: 'acme/built',
+        entry: 'harness.js',
+        agents: [{ name: 'painter', produces: 'image' }],
+        requires: {
+          filesystem: false,
+          processExecution: false,
+          network: 'model-only',
+        },
+      })
+      expect(manifest.digest).toMatch(/^[0-9a-f]{64}$/)
+      expect(await readManifest(outDir)).toEqual(manifest)
+      expect((await readFile(bundle)).length).toBeGreaterThan(1000)
+
+      const model = await artifactText(outDir)
+      try {
+        const ask = (content: string) =>
+          textOf(
+            chat({
+              adapter: model,
+              messages: [{ role: 'user', content }],
+              threadId: 'outer',
+            }) as AsyncIterable<StreamChunk>,
+          )
+        expect(await ask('first')).toBe('worker saw 1 messages')
+        // The worker keeps the conversation between calls.
+        expect(await ask('second')).toBe('worker saw 3 messages')
+      } finally {
+        model.dispose()
+      }
+    },
+  )
+
+  it(
+    'refuses a bundle that does not match its manifest',
+    { timeout: 60_000 },
+    async () => {
+      const outDir = join(tmp, 'out')
+      await writeFile(join(outDir, 'harness.js'), '// changed\n')
+      await expect(artifactText(outDir)).rejects.toThrow(
+        'does not match its manifest digest',
+      )
+    },
+  )
+})
diff --git a/packages/ai-harness/vite.config.ts b/packages/ai-harness/vite.config.ts
index c99a69e684..e0d86be566 100644
--- a/packages/ai-harness/vite.config.ts
+++ b/packages/ai-harness/vite.config.ts
@@ -28,7 +28,9 @@ const config = defineConfig({
 export default mergeConfig(
   config,
   tanstackViteConfig({
-    entry: ['./src/index.ts', './src/client.ts', './src/first-party/index.ts'],
+    entry: ['./src/index.ts', './src/client.ts', './src/first-party/index.ts',
+      './src/build.ts',
+      './src/worker.ts',],
     srcDir: './src',
     cjs: false,
   }),
diff --git a/testing/e2e/src/routes/api.harness-test.ts b/testing/e2e/src/routes/api.harness-test.ts
index b66add840d..ff75aba9b1 100644
--- a/testing/e2e/src/routes/api.harness-test.ts
+++ b/testing/e2e/src/routes/api.harness-test.ts
@@ -1,6 +1,10 @@
 import { createFileRoute } from '@tanstack/react-router'
-import { defineAgent } from '@tanstack/ai'
-import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { chat, defineAgent } from '@tanstack/ai'
+import {
+  createHarnessHost,
+  defineHarness,
+  harnessText,
+} from '@tanstack/ai-harness'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { z } from 'zod'
 import { createTextAdapter } from '@/lib/providers'
@@ -48,6 +52,23 @@ export const Route = createFileRoute('/api/harness-test')({
         const host = createHarnessHost({ persistence })
         try {
           const session = await host.open(harness, { threadId: 'e2e-thread' })
+          if (body.scenario === 'remote') {
+            // A harness on "another machine": the protocol route of this app,
+            // called over HTTP.
+            const remote = harnessText({
+              url: new URL('/api/harness-protocol', request.url).href,
+              token: 'e2e-token',
+            })
+            let answer = ''
+            for await (const chunk of chat({
+              adapter: remote,
+              messages: [{ role: 'user', content: '[harness-protocol] hello' }],
+              threadId: `remote-${testId ?? 'default'}`,
+            })) {
+              if (chunk.type === 'TEXT_MESSAGE_CONTENT') answer += chunk.delta
+            }
+            return Response.json({ answer })
+          }
           if (body.scenario === 'limits') {
             // The main model calls `worker` twice. The limit allows one.
             let workerRuns = 0
diff --git a/testing/e2e/tests/harness.spec.ts b/testing/e2e/tests/harness.spec.ts
index 609a642592..667f53389d 100644
--- a/testing/e2e/tests/harness.spec.ts
+++ b/testing/e2e/tests/harness.spec.ts
@@ -15,6 +15,20 @@ test.describe('harness session', () => {
     expect(body.roles).toEqual(['user', 'assistant', 'user', 'assistant'])
   })
 
+  test('a remote harness answers as the model of a chat call', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'remote', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    expect((await response.json()).answer).toBe(
+      'Hello over the harness protocol.',
+    )
+  })
+
   test('subagent limits refuse the second child start', async ({
     request,
     testId,

From 5d27a1d638fad2b69323f716ce266a62b5a6427c Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Sat, 26 Sep 2026 11:24:41 +0000
Subject: [PATCH 012/286] ci: apply automated fixes

---
 packages/ai-harness/src/build.ts                |  4 +---
 packages/ai-harness/vite.config.ts              |  8 ++++++--
 .../ai-persistence/src/testkit/conformance.ts   | 17 ++++++-----------
 3 files changed, 13 insertions(+), 16 deletions(-)

diff --git a/packages/ai-harness/src/build.ts b/packages/ai-harness/src/build.ts
index 4d3cf074e8..6ebfb5b5c2 100644
--- a/packages/ai-harness/src/build.ts
+++ b/packages/ai-harness/src/build.ts
@@ -95,9 +95,7 @@ function run(
  * The build imports `entry` in a child process to read the harness name,
  * agents, and plugin names. Importing a module runs its code.
  */
-export async function buildHarness(
-  options: BuildHarnessOptions,
-): Promise<{
+export async function buildHarness(options: BuildHarnessOptions): Promise<{
   manifest: HarnessManifestV1
   bundle: string
   executable?: string
diff --git a/packages/ai-harness/vite.config.ts b/packages/ai-harness/vite.config.ts
index e0d86be566..b5a782675a 100644
--- a/packages/ai-harness/vite.config.ts
+++ b/packages/ai-harness/vite.config.ts
@@ -28,9 +28,13 @@ const config = defineConfig({
 export default mergeConfig(
   config,
   tanstackViteConfig({
-    entry: ['./src/index.ts', './src/client.ts', './src/first-party/index.ts',
+    entry: [
+      './src/index.ts',
+      './src/client.ts',
+      './src/first-party/index.ts',
       './src/build.ts',
-      './src/worker.ts',],
+      './src/worker.ts',
+    ],
     srcDir: './src',
     cjs: false,
   }),
diff --git a/packages/ai-persistence/src/testkit/conformance.ts b/packages/ai-persistence/src/testkit/conformance.ts
index 27b6d0e874..3b8ab62ebf 100644
--- a/packages/ai-persistence/src/testkit/conformance.ts
+++ b/packages/ai-persistence/src/testkit/conformance.ts
@@ -1583,18 +1583,13 @@ export function runPersistenceConformance(
         const current = await store.getVersioned('cas', 'k')
         expect(current?.value).toEqual({ n: 1 })
         const revision = current?.revision ?? null
-        const updated = await store.setIf(
-          'cas',
-          'k',
-          { n: 2 },
-          revision,
-        )
+        const updated = await store.setIf('cas', 'k', { n: 2 }, revision)
         expect(updated.ok).toBe(true)
-        expect(
-          await store.setIf('cas', 'k', { n: 3 }, revision),
-        ).toMatchObject({
-          ok: false,
-        })
+        expect(await store.setIf('cas', 'k', { n: 3 }, revision)).toMatchObject(
+          {
+            ok: false,
+          },
+        )
         expect(await store.get('cas', 'k')).toEqual({ n: 2 })
       })
     })

From 61ce0041fabed895ecdc7037cc51069ae76dfea2 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 13:36:41 +0200
Subject: [PATCH 013/286] feat(ai-dashboard): self-hosted dashboard,
 --dashboard, and a runnable example

New package @tanstack/ai-dashboard. `npx @tanstack/ai-dashboard` (or
startDashboard) runs a node:http server with no new dependencies. Hosts dial
out with connectDashboard, pair with a one-time code, and get a revocable
host token. The relay uses SSE plus POST and caches recent events per
session; inputs for an offline host wait and are delivered on reconnect.
The web app lists hosts and sessions, streams messages and tool calls,
shows approval cards and plugin questions, and sends prompts, steers, and
stops. It installs as a PWA on a phone.

@tanstack/ai-harness-cli adds --dashboard <url>.

examples/harness-cli: a small coding agent (permissions, workspace tools,
todos, model picker, typed agent) that runs with OpenAI, Anthropic, or a
demo model.
---
 .changeset/harness-p6-dashboard.md        |   8 +
 docs/config.json                          |   5 +
 docs/harness/dashboard.md                 |  69 ++++
 examples/README.md                        |  17 +
 examples/harness-cli/README.md            |  33 ++
 examples/harness-cli/package.json         |  26 ++
 examples/harness-cli/playground/.gitkeep  |   0
 examples/harness-cli/playground/AGENTS.md |   1 +
 examples/harness-cli/src/cli.ts           |   4 +
 examples/harness-cli/src/harness.ts       | 136 +++++++
 examples/harness-cli/tsconfig.json        |  13 +
 packages/ai-dashboard/README.md           |  56 +++
 packages/ai-dashboard/bin/dashboard.mjs   |  26 ++
 packages/ai-dashboard/package.json        |  85 +++++
 packages/ai-dashboard/src/connect.ts      | 242 ++++++++++++
 packages/ai-dashboard/src/index.ts        |   2 +
 packages/ai-dashboard/src/server.ts       | 444 ++++++++++++++++++++++
 packages/ai-dashboard/src/ui.ts           | 194 ++++++++++
 packages/ai-dashboard/tests/relay.test.ts | 219 +++++++++++
 packages/ai-dashboard/tsconfig.json       |   8 +
 packages/ai-dashboard/vite.config.ts      |  35 ++
 packages/ai-harness-cli/package.json      |   5 +
 packages/ai-harness-cli/src/args.ts       |   4 +
 packages/ai-harness-cli/src/index.ts      |  32 ++
 packages/ai-harness-cli/src/lines.ts      |  34 +-
 pnpm-lock.yaml                            |  58 +++
 testing/e2e/package.json                  |   1 +
 testing/e2e/tests/dashboard.spec.ts       | 124 ++++++
 28 files changed, 1867 insertions(+), 14 deletions(-)
 create mode 100644 .changeset/harness-p6-dashboard.md
 create mode 100644 docs/harness/dashboard.md
 create mode 100644 examples/harness-cli/README.md
 create mode 100644 examples/harness-cli/package.json
 create mode 100644 examples/harness-cli/playground/.gitkeep
 create mode 100644 examples/harness-cli/playground/AGENTS.md
 create mode 100644 examples/harness-cli/src/cli.ts
 create mode 100644 examples/harness-cli/src/harness.ts
 create mode 100644 examples/harness-cli/tsconfig.json
 create mode 100644 packages/ai-dashboard/README.md
 create mode 100644 packages/ai-dashboard/bin/dashboard.mjs
 create mode 100644 packages/ai-dashboard/package.json
 create mode 100644 packages/ai-dashboard/src/connect.ts
 create mode 100644 packages/ai-dashboard/src/index.ts
 create mode 100644 packages/ai-dashboard/src/server.ts
 create mode 100644 packages/ai-dashboard/src/ui.ts
 create mode 100644 packages/ai-dashboard/tests/relay.test.ts
 create mode 100644 packages/ai-dashboard/tsconfig.json
 create mode 100644 packages/ai-dashboard/vite.config.ts
 create mode 100644 testing/e2e/tests/dashboard.spec.ts

diff --git a/.changeset/harness-p6-dashboard.md b/.changeset/harness-p6-dashboard.md
new file mode 100644
index 0000000000..dd71ffb871
--- /dev/null
+++ b/.changeset/harness-p6-dashboard.md
@@ -0,0 +1,8 @@
+---
+'@tanstack/ai-dashboard': minor
+'@tanstack/ai-harness-cli': minor
+---
+
+New package `@tanstack/ai-dashboard`: a self-hosted dashboard for harness sessions. `npx @tanstack/ai-dashboard` starts it (`startDashboard` in code). Agents dial out with `connectDashboard` from `@tanstack/ai-dashboard/connect`, pair with a one-time code, and get a revocable host token. The web app lists hosts and sessions, streams messages and tool calls, shows approval cards and plugin questions, and sends prompts, steers, and stops. It installs as a web app on a phone. Inputs for an offline host wait at the dashboard and reach it on reconnect.
+
+`@tanstack/ai-harness-cli` adds `--dashboard <url>`, which pairs on first use (or reads `HARNESS_DASHBOARD_TOKEN`) and keeps the session connected.
diff --git a/docs/config.json b/docs/config.json
index 533ad81083..c8e087348a 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -848,6 +848,11 @@
           "label": "Deploy a harness",
           "to": "harness/deploy",
           "addedAt": "2026-09-26"
+        },
+        {
+          "label": "Self-host the dashboard",
+          "to": "harness/dashboard",
+          "addedAt": "2026-09-26"
         }
       ]
     },
diff --git a/docs/harness/dashboard.md b/docs/harness/dashboard.md
new file mode 100644
index 0000000000..8bc06bcd83
--- /dev/null
+++ b/docs/harness/dashboard.md
@@ -0,0 +1,69 @@
+---
+title: Self-host the dashboard
+id: harness-dashboard
+order: 10
+description: "Watch and steer your harness sessions from a browser or a phone. Agents dial out to your dashboard server, so they need no open port."
+keywords:
+  - tanstack ai
+  - harness
+  - dashboard
+  - mobile
+  - relay
+---
+
+Your agent runs on a laptop, a server, or a CI runner, and it stops to ask for approval while you are away from that terminal. The dashboard shows every connected session in a browser or on your phone. You approve tools, answer questions, and send prompts from there. Agents connect out to the dashboard, so they need no open port.
+
+## 1. Start the dashboard
+
+```bash
+npx @tanstack/ai-dashboard --port 8790
+```
+
+It prints a sign-in link that holds the owner token. Set `DASHBOARD_OWNER_TOKEN` to keep the same token across restarts. Put the dashboard behind TLS when it is reachable from other machines.
+
+## 2. Connect an agent
+
+With the CLI, add `--dashboard`:
+
+```bash
+npx tsx cli.ts --dashboard http://127.0.0.1:8790
+```
+
+In your own host, call `connectDashboard`:
+
+```ts group=harness-dashboard
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { connectDashboard } from '@tanstack/ai-dashboard/connect'
+import { openaiText } from '@tanstack/ai-openai'
+
+const studio = defineHarness({ name: 'acme/studio', adapter: openaiText('gpt-5.6') })
+const host = createHarnessHost()
+
+const connection = await connectDashboard({
+  host,
+  harness: studio,
+  url: 'http://127.0.0.1:8790',
+  threads: ['main'],
+  onPairingCode: (code) => console.log(`Approve ${code} in the dashboard`),
+  onToken: (token) => console.log(`Save this host token: ${token}`),
+})
+```
+
+## 3. Pair it
+
+The first time, the agent prints a pairing code. Approve the code in the dashboard under "Pairing requests". The agent gets a host token. Pass it as `token` (or `HARNESS_DASHBOARD_TOKEN` for the CLI) to skip pairing next time. Revoke a host in the dashboard to cut it off.
+
+## What you can do in the dashboard
+
+- See hosts (online or offline) and sessions (running, waiting for you, idle).
+- Read the messages and tool calls of a session as they stream.
+- Approve or reject tool calls, and answer questions from plugins.
+- Send a prompt, steer a running turn, or stop it.
+
+Inputs for an offline host wait at the dashboard for 10 minutes and reach the host when it reconnects. Set `allowRemoteStart: true` in `connectDashboard` to let the dashboard open new sessions on the host.
+
+On a phone, open the dashboard and add it to the home screen. It works as an installed web app.
+
+## What you have now
+
+- Your sessions on any screen, with approvals and prompts a tap away.
diff --git a/examples/README.md b/examples/README.md
index b050e1b370..9406c3054e 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -11,6 +11,7 @@ Choose an example based on your use case:
 - **Want a table that fills as JSON streams?** → [Streaming Structured Table](#streaming-structured-table)
 - **Want typed ticket routing?** → [Evaluate](#evaluate)
 - **Want a blog desk with three agents?** → [Subagents](#subagents)
+- **Want your own coding agent in the terminal?** → [Harness CLI](#harness-cli)
 - **Want a full-stack TypeScript app?** → [TanStack Chat (ts-react-chat)](#tanstack-chat-ts-react-chat)
 - **Need a live world stream?** → [World generation (ts-react-media)](#world-generation-ts-react-media)
 - **Need a vanilla JS frontend?** → [Vanilla Chat](#vanilla-chat)
@@ -19,6 +20,22 @@ Choose an example based on your use case:
 
 ## TypeScript Examples
 
+### Harness CLI
+
+A small coding agent in the terminal, built with `@tanstack/ai-harness`. It edits files in `./playground`, asks before writes and commands, keeps a todo list, switches models, and connects to the self-hosted dashboard. Without an API key, a demo model answers.
+
+**Path:** `examples/harness-cli`
+
+**Getting Started:**
+
+```bash
+OPENAI_API_KEY=... pnpm --filter harness-cli-example start
+```
+
+📖 [Full Documentation](harness-cli/README.md)
+
+---
+
 ### Basic Chat
 
 A slim TanStack Start chat. One provider (OpenRouter). You paste your own key.
diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
new file mode 100644
index 0000000000..cd5f93c5fe
--- /dev/null
+++ b/examples/harness-cli/README.md
@@ -0,0 +1,33 @@
+# Harness CLI example
+
+A small coding agent in your terminal, built with `@tanstack/ai-harness`. It reads and edits files in `./playground`, asks before it writes a file or runs a command, keeps a todo list, and can switch models.
+
+## Run it
+
+From the repo root:
+
+1. `pnpm install`
+2. `pnpm build:all` (the example uses the local packages)
+3. Set a key: `OPENAI_API_KEY=...` or `ANTHROPIC_API_KEY=...`. Without one, a demo model answers.
+4. `pnpm --filter harness-cli-example start`
+
+Try these:
+
+- `create hello.txt with a short poem`: the agent asks before `write_file`. Type `y`.
+- `/mode plan`, then ask for another file: the write is refused.
+- `/todos`, `/usage`, `/model fast`, `/agents`
+- `/agent haiku {"topic":"rain"}`: runs a typed agent in the background.
+- Press Esc to stop a long answer. Type while it works to steer it.
+
+## Other modes
+
+- One prompt for scripts and CI: `pnpm --filter harness-cli-example start -p "list the files"`
+- AG-UI events as JSON lines: add `--output ndjson`.
+- As an editor agent (ACP): `pnpm --filter harness-cli-example start --acp`
+- As an HTTP server: `pnpm --filter harness-cli-example start --serve` (it prints a token).
+
+## Watch it from a browser or a phone
+
+1. In one terminal: `pnpm --filter harness-cli-example dashboard`. It prints a sign-in link.
+2. In another: `pnpm --filter harness-cli-example start --dashboard http://127.0.0.1:8790`. It prints a pairing code.
+3. Open the sign-in link, approve the code, and open the `main` session. Messages you send there reach the agent.
diff --git a/examples/harness-cli/package.json b/examples/harness-cli/package.json
new file mode 100644
index 0000000000..3038efe1ff
--- /dev/null
+++ b/examples/harness-cli/package.json
@@ -0,0 +1,26 @@
+{
+  "name": "harness-cli-example",
+  "private": true,
+  "type": "module",
+  "description": "A small coding agent in the terminal, built with @tanstack/ai-harness",
+  "scripts": {
+    "start": "tsx src/cli.ts",
+    "dashboard": "tanstack-ai-dashboard",
+    "test:types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-acp": "workspace:*",
+    "@tanstack/ai-anthropic": "workspace:*",
+    "@tanstack/ai-dashboard": "workspace:*",
+    "@tanstack/ai-harness": "workspace:*",
+    "@tanstack/ai-harness-cli": "workspace:*",
+    "@tanstack/ai-openai": "workspace:*",
+    "@tanstack/ai-persistence": "workspace:*",
+    "zod": "^4.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "tsx": "^4.23.12"
+  }
+}
diff --git a/examples/harness-cli/playground/.gitkeep b/examples/harness-cli/playground/.gitkeep
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/examples/harness-cli/playground/AGENTS.md b/examples/harness-cli/playground/AGENTS.md
new file mode 100644
index 0000000000..9fcc63b5ea
--- /dev/null
+++ b/examples/harness-cli/playground/AGENTS.md
@@ -0,0 +1 @@
+This is a playground folder. Keep files short and add a comment at the top of every new file.
diff --git a/examples/harness-cli/src/cli.ts b/examples/harness-cli/src/cli.ts
new file mode 100644
index 0000000000..774a33ba2e
--- /dev/null
+++ b/examples/harness-cli/src/cli.ts
@@ -0,0 +1,4 @@
+import { runCli } from '@tanstack/ai-harness-cli'
+import { assistant } from './harness'
+
+process.exitCode = await runCli(assistant)
diff --git a/examples/harness-cli/src/harness.ts b/examples/harness-cli/src/harness.ts
new file mode 100644
index 0000000000..c87b1a6434
--- /dev/null
+++ b/examples/harness-cli/src/harness.ts
@@ -0,0 +1,136 @@
+import { fileURLToPath } from 'node:url'
+import { EventType, defineAgent } from '@tanstack/ai'
+import { defineHarness } from '@tanstack/ai-harness'
+import {
+  compact,
+  modelPicker,
+  permissions,
+  projectInstructions,
+  todos,
+  usage,
+  workspaceTools,
+} from '@tanstack/ai-harness/plugins'
+import { anthropicText } from '@tanstack/ai-anthropic'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+import type { AnyTextAdapter } from '@tanstack/ai'
+
+// The agent works in ./playground, so it cannot touch the rest of your disk.
+const root = fileURLToPath(new URL('../playground', import.meta.url))
+
+/** Without an API key, a stand-in model that explains how to add one. */
+function demoModel(): AnyTextAdapter {
+  let calls = 0
+  return {
+    kind: 'text',
+    name: 'demo',
+    model: 'demo',
+    '~types': {
+      providerOptions: {},
+      inputModalities: ['text'],
+      messageMetadataByModality: {
+        text: undefined,
+        image: undefined,
+        audio: undefined,
+        video: undefined,
+        document: undefined,
+      },
+      toolCapabilities: [],
+      toolCallMetadata: undefined,
+      systemPromptMetadata: undefined as never,
+    },
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+    chatStream: (options) =>
+      (async function* () {
+        calls += 1
+        const messageId = `demo-${calls}`
+        const last = options.messages.at(-1)
+        const said = typeof last?.content === 'string' ? last.content : ''
+        const now = Date.now()
+        yield {
+          type: EventType.RUN_STARTED,
+          runId: 'demo',
+          threadId: 'demo',
+          timestamp: now,
+        }
+        yield {
+          type: EventType.TEXT_MESSAGE_START,
+          messageId,
+          role: 'assistant',
+          timestamp: now,
+        }
+        yield {
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          messageId,
+          delta: `(demo model) You said: "${said}". Set OPENAI_API_KEY or ANTHROPIC_API_KEY to talk to a real model.`,
+          timestamp: now,
+        }
+        yield { type: EventType.TEXT_MESSAGE_END, messageId, timestamp: now }
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId: 'demo',
+          threadId: 'demo',
+          timestamp: now,
+          metadata: { tanstack: { finishReason: 'stop' } },
+        }
+      })(),
+  }
+}
+
+function pickModels(): {
+  main: AnyTextAdapter
+  choices: Record<string, AnyTextAdapter>
+} {
+  if (process.env.OPENAI_API_KEY) {
+    const smart = openaiText('gpt-5.6')
+    return { main: smart, choices: { smart, fast: openaiText('gpt-5.6-luna') } }
+  }
+  if (process.env.ANTHROPIC_API_KEY) {
+    const smart = anthropicText('claude-opus-5-5')
+    return {
+      main: smart,
+      choices: { smart, fast: anthropicText('claude-sonnet-5') },
+    }
+  }
+  const demo = demoModel()
+  return { main: demo, choices: { demo } }
+}
+
+const { main, choices } = pickModels()
+
+/** A typed agent you can run with `/agent haiku {"topic":"rain"}`. */
+const haiku = defineAgent({
+  name: 'haiku',
+  description: 'Writes a haiku about a topic',
+  inputSchema: z.object({ topic: z.string() }),
+  run: (ctx) =>
+    ctx.chat({
+      adapter: main,
+      messages: [
+        {
+          role: 'user',
+          content: `Write one haiku about ${ctx.input.topic}. Only the haiku.`,
+        },
+      ],
+      stream: false,
+    }),
+})
+
+export const assistant = defineHarness({
+  name: 'example/coder',
+  description: 'A small coding agent that works in ./playground',
+  adapter: main,
+  systemPrompts: [
+    'You are a careful coding agent. Read files before you edit them. Keep answers short.',
+  ],
+  agents: [haiku],
+  plugins: () => [
+    permissions(),
+    workspaceTools({ root }),
+    todos(),
+    modelPicker({ choices, default: Object.keys(choices)[0] }),
+    projectInstructions({ root }),
+    compact({ adapter: main }),
+    usage(),
+  ],
+})
diff --git a/examples/harness-cli/tsconfig.json b/examples/harness-cli/tsconfig.json
new file mode 100644
index 0000000000..619816780b
--- /dev/null
+++ b/examples/harness-cli/tsconfig.json
@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "esModuleInterop": true
+  },
+  "include": ["src"]
+}
diff --git a/packages/ai-dashboard/README.md b/packages/ai-dashboard/README.md
new file mode 100644
index 0000000000..be3f0a764b
--- /dev/null
+++ b/packages/ai-dashboard/README.md
@@ -0,0 +1,56 @@
+<div align="center">
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://tanstack.com/api/readme/ai.png?theme=dark"
+    />
+    <source
+      media="(prefers-color-scheme: light)"
+      srcset="https://tanstack.com/api/readme/ai.png"
+    />
+    <img
+      src="https://tanstack.com/api/readme/ai.png"
+      alt="TanStack AI"
+      width="900"
+    />
+  </picture>
+</div>
+
+<br />
+
+# @tanstack/ai-dashboard
+
+A self-hosted dashboard for TanStack AI harnesses. Watch sessions, approve tool calls, answer questions, and send prompts from a browser or a phone. Agents dial out to it, so they need no open port.
+
+## Start the dashboard
+
+```bash
+npx @tanstack/ai-dashboard --port 8790
+```
+
+It prints a sign-in link with the owner token. Set `DASHBOARD_OWNER_TOKEN` to keep the same token across restarts.
+
+## Connect an agent
+
+```ts
+import { connectDashboard } from '@tanstack/ai-dashboard/connect'
+
+await connectDashboard({
+  host,
+  harness: studio,
+  url: 'http://127.0.0.1:8790',
+  threads: ['main'],
+  onPairingCode: (code) => console.log(`Approve ${code} in the dashboard`),
+  onToken: (token) => console.log(`Save this host token: ${token}`),
+})
+```
+
+With `@tanstack/ai-harness-cli`, run your CLI with `--dashboard <url>`.
+
+## Documentation
+
+Read [Self-host the dashboard](https://tanstack.com/ai/latest/docs/harness/dashboard).
+
+## License
+
+MIT
diff --git a/packages/ai-dashboard/bin/dashboard.mjs b/packages/ai-dashboard/bin/dashboard.mjs
new file mode 100644
index 0000000000..bf9a07d52e
--- /dev/null
+++ b/packages/ai-dashboard/bin/dashboard.mjs
@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Start a dashboard: npx @tanstack/ai-dashboard [--port 8790] [--host 127.0.0.1]
+import { parseArgs } from 'node:util'
+import { startDashboard } from '../dist/esm/index.js'
+
+const { values } = parseArgs({
+  options: { port: { type: 'string' }, host: { type: 'string' } },
+})
+const dashboard = await startDashboard({
+  port: Number(values.port ?? process.env.PORT ?? 8790),
+  hostname: values.host ?? process.env.HOST ?? '127.0.0.1',
+  ...(process.env.DASHBOARD_OWNER_TOKEN
+    ? { ownerToken: process.env.DASHBOARD_OWNER_TOKEN }
+    : {}),
+})
+console.log(`Dashboard: ${dashboard.url}`)
+if (!process.env.DASHBOARD_OWNER_TOKEN) {
+  console.log(`Owner token: ${dashboard.ownerToken}`)
+  console.log(`Sign in: ${dashboard.url}/#token=${dashboard.ownerToken}`)
+}
+const stop = async () => {
+  await dashboard.close()
+  process.exit(0)
+}
+process.once('SIGINT', stop)
+process.once('SIGTERM', stop)
diff --git a/packages/ai-dashboard/package.json b/packages/ai-dashboard/package.json
new file mode 100644
index 0000000000..5e096733d6
--- /dev/null
+++ b/packages/ai-dashboard/package.json
@@ -0,0 +1,85 @@
+{
+  "name": "@tanstack/ai-dashboard",
+  "version": "0.0.0",
+  "description": "A self-hosted dashboard for TanStack AI harnesses: watch sessions, approve tools, and send prompts from a browser or a phone",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-dashboard"
+  },
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "bin": {
+    "tanstack-ai-dashboard": "./bin/dashboard.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./connect": {
+      "types": "./dist/esm/connect.d.ts",
+      "import": "./dist/esm/connect.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "bin"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "oxlint src --type-aware --fix",
+    "test:build": "publint --strict",
+    "test:oxlint": "oxlint src --type-aware",
+    "test:coverage": "vitest run --passWithNoTests --coverage --coverage.include='src/**' --coverage.reporter=text-summary --coverage.reporter=json-summary",
+    "test:lib": "vitest --passWithNoTests",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  },
+  "nx": {
+    "targets": {
+      "test:lib": {
+        "dependsOn": [
+          "build",
+          "^build"
+        ]
+      },
+      "test:coverage": {
+        "dependsOn": [
+          "build",
+          "^build"
+        ]
+      },
+      "test:types": {
+        "dependsOn": [
+          "build",
+          "^build"
+        ]
+      }
+    }
+  },
+  "keywords": [
+    "ai",
+    "tanstack",
+    "harness",
+    "dashboard",
+    "relay",
+    "pwa"
+  ],
+  "peerDependencies": {
+    "@tanstack/ai": "workspace:^",
+    "@tanstack/ai-harness": "workspace:^"
+  },
+  "devDependencies": {
+    "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-harness": "workspace:*",
+    "@tanstack/ai-persistence": "workspace:*",
+    "@vitest/coverage-v8": "4.1.10"
+  }
+}
diff --git a/packages/ai-dashboard/src/connect.ts b/packages/ai-dashboard/src/connect.ts
new file mode 100644
index 0000000000..07f4cd66ac
--- /dev/null
+++ b/packages/ai-dashboard/src/connect.ts
@@ -0,0 +1,242 @@
+import { applyInput, parseHarnessInput } from '@tanstack/ai-harness'
+import type {
+  AnyHarness,
+  HarnessHost,
+  HarnessSession,
+} from '@tanstack/ai-harness'
+
+export interface ConnectDashboardOptions {
+  host: HarnessHost
+  harness: AnyHarness
+  /** The dashboard URL, for example `https://dash.example.com`. */
+  url: string
+  /** The host token. Without one, the host pairs first (see `onPairingCode`). */
+  token?: string
+  /** How this host shows up in the dashboard. */
+  name?: string
+  /** Threads to show in the dashboard at once. */
+  threads?: ReadonlyArray<string>
+  /** Let the dashboard open new sessions on this host. Default false. */
+  allowRemoteStart?: boolean
+  /** Called with the code to approve in the dashboard. */
+  onPairingCode?: (code: string) => void
+  /** Called with the new host token after pairing. Save it to skip pairing next time. */
+  onToken?: (token: string) => void
+  fetch?: typeof fetch
+  /** Wait between reconnects, doubled up to 30 s. Default 1000 ms. */
+  reconnectDelayMs?: number
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null
+
+async function* sseData(response: Response): AsyncGenerator<unknown> {
+  if (!response.body) return
+  const reader = response.body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+  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) yield JSON.parse(data)
+    }
+  }
+}
+
+/**
+ * Connect a harness host to a dashboard. The host dials out, so it needs no
+ * open port. The dashboard shows its sessions and sends inputs back. Every
+ * input goes through the same session API as a local client.
+ */
+export async function connectDashboard(options: ConnectDashboardOptions) {
+  const base = options.url.replace(/\/$/, '')
+  const doFetch = options.fetch ?? fetch
+  const stopped = new AbortController()
+  let token = options.token
+
+  if (!token) {
+    const started = await (
+      await doFetch(`${base}/api/pair/start`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name: options.name ?? options.harness.name }),
+      })
+    ).json()
+    if (
+      !isRecord(started) ||
+      typeof started.pairingId !== 'string' ||
+      typeof started.code !== 'string'
+    ) {
+      throw new Error('The dashboard did not start a pairing.')
+    }
+    options.onPairingCode?.(started.code)
+    while (!token) {
+      if (stopped.signal.aborted)
+        throw new Error('Stopped before pairing finished.')
+      await new Promise((resolve) => setTimeout(resolve, 1000))
+      const status: unknown = await (
+        await doFetch(
+          `${base}/api/pair/status?pairingId=${encodeURIComponent(started.pairingId)}`,
+        )
+      ).json()
+      if (
+        isRecord(status) &&
+        status.status === 'approved' &&
+        typeof status.token === 'string'
+      ) {
+        token = status.token
+      } else if (!isRecord(status) || status.status !== 'pending') {
+        throw new Error('The pairing expired. Start again.')
+      }
+    }
+    options.onToken?.(token)
+  }
+  const hostToken = token
+  const headers = {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${hostToken}`,
+  }
+
+  const post = (path: string, value: unknown) =>
+    doFetch(`${base}${path}`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(value),
+    })
+
+  await post('/api/host/hello', {
+    name: options.name ?? options.harness.name,
+    harnesses: [options.harness.name],
+  })
+
+  const attached = new Map<string, HarnessSession>()
+  const attach = async (threadId: string): Promise<HarnessSession> => {
+    const existing = attached.get(threadId)
+    if (existing) return existing
+    const session = await options.host.open(options.harness, { threadId })
+    attached.set(threadId, session)
+    // Batch events so a streaming answer is a few requests, not one per token.
+    let pending: Array<unknown> = []
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const flush = () => {
+      timer = undefined
+      const frames = pending
+      pending = []
+      if (frames.length > 0) {
+        void post('/api/host/frames', {
+          threadId,
+          harness: options.harness.name,
+          frames,
+        }).catch(() => {})
+      }
+    }
+    void (async () => {
+      for await (const entry of session.events({
+        from: '0',
+        signal: stopped.signal,
+      })) {
+        pending.push({ type: 'harness.event', ...entry })
+        timer ??= setTimeout(flush, 50)
+      }
+    })()
+    return session
+  }
+  for (const threadId of options.threads ?? []) await attach(threadId)
+
+  const handle = async (envelope: unknown) => {
+    if (
+      !isRecord(envelope) ||
+      typeof envelope.threadId !== 'string' ||
+      !isRecord(envelope.frame)
+    )
+      return
+    const { threadId, frame } = envelope
+    if (frame.type === 'harness.subscribe') {
+      if (attached.has(threadId) || options.allowRemoteStart)
+        await attach(threadId)
+      return
+    }
+    const session = attached.get(threadId)
+    if (!session) {
+      if (
+        frame.type === 'harness.input' &&
+        typeof frame.requestId === 'string'
+      ) {
+        await post('/api/host/frames', {
+          threadId,
+          frames: [
+            {
+              type: 'harness.receipt',
+              requestId: frame.requestId,
+              status: 'rejected',
+              reason: 'remote_start_disabled',
+            },
+          ],
+        })
+      }
+      return
+    }
+    if (frame.type === 'harness.input' && typeof frame.requestId === 'string') {
+      try {
+        const receipt = await applyInput(
+          options.harness,
+          session,
+          parseHarnessInput(frame.input),
+        )
+        await post('/api/host/frames', {
+          threadId,
+          frames: [
+            { type: 'harness.receipt', requestId: frame.requestId, ...receipt },
+          ],
+        })
+      } catch (error) {
+        await post('/api/host/frames', {
+          threadId,
+          frames: [
+            {
+              type: 'harness.error',
+              message: error instanceof Error ? error.message : String(error),
+            },
+          ],
+        })
+      }
+    }
+  }
+
+  // The control stream, with reconnects.
+  void (async () => {
+    let delay = options.reconnectDelayMs ?? 1000
+    while (!stopped.signal.aborted) {
+      try {
+        const response = await doFetch(`${base}/api/host/stream`, {
+          headers,
+          signal: stopped.signal,
+        })
+        if (response.status === 401)
+          throw new Error('The dashboard refused this host token.')
+        delay = options.reconnectDelayMs ?? 1000
+        for await (const envelope of sseData(response)) void handle(envelope)
+      } catch (error) {
+        if (stopped.signal.aborted) return
+        if (error instanceof Error && error.message.includes('refused')) return
+      }
+      await new Promise((resolve) => setTimeout(resolve, delay))
+      delay = Math.min(delay * 2, 30_000)
+    }
+  })()
+
+  return {
+    token: hostToken,
+    /** Show another thread in the dashboard. */
+    attach: (threadId: string) => attach(threadId).then(() => undefined),
+    close: () => stopped.abort(),
+  }
+}
diff --git a/packages/ai-dashboard/src/index.ts b/packages/ai-dashboard/src/index.ts
new file mode 100644
index 0000000000..2d67dee7c8
--- /dev/null
+++ b/packages/ai-dashboard/src/index.ts
@@ -0,0 +1,2 @@
+export { startDashboard } from './server'
+export type { ControlEnvelope, DashboardOptions } from './server'
diff --git a/packages/ai-dashboard/src/server.ts b/packages/ai-dashboard/src/server.ts
new file mode 100644
index 0000000000..9d561448bd
--- /dev/null
+++ b/packages/ai-dashboard/src/server.ts
@@ -0,0 +1,444 @@
+import { createServer } from 'node:http'
+import { randomBytes, randomInt, timingSafeEqual } from 'node:crypto'
+import { DASHBOARD_HTML, MANIFEST_JSON, SERVICE_WORKER } from './ui'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+/** One frame the dashboard sends a host: a session-tier control frame for a thread. */
+export interface ControlEnvelope {
+  threadId: string
+  frame: Record<string, unknown>
+}
+
+export interface DashboardOptions {
+  port?: number
+  hostname?: string
+  /** The owner's login token. Default: a new random token, returned by `startDashboard`. */
+  ownerToken?: string
+  /** Events kept per session for replay. Default 2000. */
+  cacheSize?: number
+  /** How long an input waits for an offline host. Default 10 minutes. */
+  queueTtlMs?: number
+}
+
+interface HostRecord {
+  hostId: string
+  name: string
+  harnesses: Array<string>
+  token: string
+  lastSeen: number
+  streams: Set<ServerResponse>
+  queue: Array<{ envelope: ControlEnvelope; expiresAt: number }>
+}
+
+interface SessionRecord {
+  hostId: string
+  threadId: string
+  harness?: string
+  events: Array<{
+    cursor: string
+    operationId: string
+    event: Record<string, unknown>
+  }>
+  lastActivity: number
+  status: 'idle' | 'running' | 'waiting'
+  clients: Set<ServerResponse>
+}
+
+const token = () => randomBytes(24).toString('base64url')
+
+function sameSecret(
+  given: string | null | undefined,
+  expected: string,
+): boolean {
+  if (!given) return false
+  const a = Buffer.from(given)
+  const b = Buffer.from(expected)
+  return a.length === b.length && timingSafeEqual(a, b)
+}
+
+function bearer(req: IncomingMessage, url: URL): string | null {
+  const header = req.headers.authorization
+  if (typeof header === 'string' && header.startsWith('Bearer '))
+    return header.slice(7)
+  // EventSource cannot send headers, so SSE clients pass the token in the URL.
+  return url.searchParams.get('token')
+}
+
+async function body(req: IncomingMessage): Promise<Record<string, unknown>> {
+  const chunks: Array<Buffer> = []
+  let size = 0
+  for await (const chunk of req) {
+    size += (chunk as Buffer).length
+    if (size > 5_000_000) throw new Error('Body too large.')
+    chunks.push(chunk as Buffer)
+  }
+  if (chunks.length === 0) return {}
+  const parsed: unknown = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+    throw new Error('Expected a JSON object.')
+  // Checked to be a plain object above.
+  return parsed as Record<string, unknown>
+}
+
+function json(res: ServerResponse, status: number, value: unknown): void {
+  res.writeHead(status, {
+    'Content-Type': 'application/json',
+    'Cache-Control': 'no-store',
+  })
+  res.end(JSON.stringify(value))
+}
+
+function openSse(res: ServerResponse): void {
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+  })
+  res.write(': connected\n\n')
+}
+
+function sse(res: ServerResponse, data: unknown, id?: string): void {
+  res.write(`${id ? `id: ${id}\n` : ''}data: ${JSON.stringify(data)}\n\n`)
+}
+
+/** A code a person can read out: 3 characters, a dash, 3 characters. */
+function pairingCode(): string {
+  const alphabet = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'
+  const pick = () => alphabet.charAt(randomInt(alphabet.length))
+  return `${pick()}${pick()}${pick()}-${pick()}${pick()}${pick()}`
+}
+
+/**
+ * Start a self-hosted dashboard server. Harness hosts dial out to it
+ * (`connectDashboard`), and people open it in a browser or on a phone.
+ *
+ * - Hosts pair with a one-time code that the owner approves, and get a host token.
+ * - The owner logs in with the owner token.
+ * - The server relays session frames and keeps a cache of recent events.
+ *   Hosts keep the transcripts.
+ */
+export async function startDashboard(options: DashboardOptions = {}) {
+  const ownerToken = options.ownerToken ?? token()
+  const cacheSize = options.cacheSize ?? 2000
+  const queueTtlMs = options.queueTtlMs ?? 10 * 60_000
+  const hosts = new Map<string, HostRecord>()
+  const hostByToken = new Map<string, string>()
+  const pairings = new Map<
+    string,
+    { code: string; name: string; expiresAt: number; hostId?: string }
+  >()
+  const sessions = new Map<string, SessionRecord>()
+  const sessionKey = (hostId: string, threadId: string) =>
+    `${hostId}\u0000${threadId}`
+
+  const isOwner = (req: IncomingMessage, url: URL) =>
+    sameSecret(bearer(req, url), ownerToken)
+  const hostFor = (req: IncomingMessage, url: URL): HostRecord | undefined => {
+    const given = bearer(req, url)
+    const hostId = given ? hostByToken.get(given) : undefined
+    const host = hostId ? hosts.get(hostId) : undefined
+    return host && sameSecret(given, host.token) ? host : undefined
+  }
+
+  const sessionFor = (hostId: string, threadId: string): SessionRecord => {
+    const key = sessionKey(hostId, threadId)
+    let session = sessions.get(key)
+    if (!session) {
+      session = {
+        hostId,
+        threadId,
+        events: [],
+        lastActivity: Date.now(),
+        status: 'idle',
+        clients: new Set(),
+      }
+      sessions.set(key, session)
+    }
+    return session
+  }
+
+  const sendToHost = (
+    host: HostRecord,
+    envelope: ControlEnvelope,
+  ): 'sent' | 'queued' => {
+    if (host.streams.size === 0) {
+      host.queue.push({ envelope, expiresAt: Date.now() + queueTtlMs })
+      return 'queued'
+    }
+    for (const stream of host.streams) sse(stream, envelope)
+    return 'sent'
+  }
+
+  const record = (session: SessionRecord, frame: Record<string, unknown>) => {
+    session.lastActivity = Date.now()
+    if (frame.type === 'harness.event') {
+      const event = frame.event as Record<string, unknown>
+      const name = event.type === 'CUSTOM' ? event.name : undefined
+      if (name === 'harness.operation.started') session.status = 'running'
+      if (name === 'harness.question') session.status = 'waiting'
+      if (name === 'harness.operation.finished') {
+        const value = event.value as { status?: unknown } | undefined
+        session.status = value?.status === 'interrupted' ? 'waiting' : 'idle'
+      }
+      session.events.push({
+        cursor: String(frame.cursor),
+        operationId: String(frame.operationId),
+        event,
+      })
+      if (session.events.length > cacheSize)
+        session.events.splice(0, session.events.length - cacheSize)
+    }
+    for (const client of session.clients)
+      sse(
+        client,
+        frame,
+        typeof frame.cursor === 'string' ? frame.cursor : undefined,
+      )
+  }
+
+  const route = async (req: IncomingMessage, res: ServerResponse) => {
+    const url = new URL(req.url ?? '/', 'http://dashboard')
+    const path = url.pathname
+    const method = req.method ?? 'GET'
+
+    // The app shell. It holds no data; every API call needs a token.
+    if (method === 'GET' && (path === '/' || path === '/index.html')) {
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+      res.end(DASHBOARD_HTML)
+      return
+    }
+    if (method === 'GET' && path === '/manifest.webmanifest') {
+      res.writeHead(200, { 'Content-Type': 'application/manifest+json' })
+      res.end(MANIFEST_JSON)
+      return
+    }
+    if (method === 'GET' && path === '/sw.js') {
+      res.writeHead(200, { 'Content-Type': 'text/javascript' })
+      res.end(SERVICE_WORKER)
+      return
+    }
+
+    // Pairing: a host asks, the owner approves, the host gets a token.
+    if (method === 'POST' && path === '/api/pair/start') {
+      const input = await body(req)
+      const pairingId = token()
+      const code = pairingCode()
+      pairings.set(pairingId, {
+        code,
+        name:
+          typeof input.name === 'string' ? input.name.slice(0, 100) : 'host',
+        expiresAt: Date.now() + 10 * 60_000,
+      })
+      json(res, 200, { pairingId, code })
+      return
+    }
+    if (method === 'GET' && path === '/api/pair/status') {
+      const pairing = pairings.get(url.searchParams.get('pairingId') ?? '')
+      if (!pairing || pairing.expiresAt < Date.now())
+        return json(res, 404, { error: 'unknown or expired pairing' })
+      if (!pairing.hostId) return json(res, 200, { status: 'pending' })
+      const host = hosts.get(pairing.hostId)
+      pairings.delete(url.searchParams.get('pairingId') ?? '')
+      return json(res, 200, {
+        status: 'approved',
+        hostId: pairing.hostId,
+        token: host?.token,
+      })
+    }
+
+    if (path.startsWith('/api/host/')) {
+      const host = hostFor(req, url)
+      if (!host) return json(res, 401, { error: 'unauthorized' })
+      host.lastSeen = Date.now()
+      if (method === 'GET' && path === '/api/host/stream') {
+        openSse(res)
+        host.streams.add(res)
+        const now = Date.now()
+        for (const queued of host.queue.splice(0)) {
+          if (queued.expiresAt > now) sse(res, queued.envelope)
+        }
+        const heartbeat = setInterval(() => res.write(': ping\n\n'), 15_000)
+        res.on('close', () => {
+          clearInterval(heartbeat)
+          host.streams.delete(res)
+        })
+        return
+      }
+      if (method === 'POST' && path === '/api/host/hello') {
+        const input = await body(req)
+        if (typeof input.name === 'string') host.name = input.name.slice(0, 100)
+        if (Array.isArray(input.harnesses))
+          host.harnesses = input.harnesses.map(String).slice(0, 50)
+        return json(res, 200, { hostId: host.hostId })
+      }
+      if (method === 'POST' && path === '/api/host/frames') {
+        const input = await body(req)
+        if (
+          typeof input.threadId !== 'string' ||
+          !Array.isArray(input.frames)
+        ) {
+          return json(res, 400, { error: 'expected { threadId, frames }' })
+        }
+        const session = sessionFor(host.hostId, input.threadId)
+        if (typeof input.harness === 'string') session.harness = input.harness
+        for (const frame of input.frames) {
+          if (typeof frame === 'object' && frame !== null)
+            record(session, frame as Record<string, unknown>)
+        }
+        return json(res, 200, { ok: true })
+      }
+      return json(res, 404, { error: 'not found' })
+    }
+
+    // Everything below is for the owner.
+    if (!path.startsWith('/api/')) return json(res, 404, { error: 'not found' })
+    if (!isOwner(req, url)) return json(res, 401, { error: 'unauthorized' })
+
+    if (method === 'GET' && path === '/api/pairings') {
+      const now = Date.now()
+      return json(
+        res,
+        200,
+        [...pairings.values()]
+          .filter((pairing) => !pairing.hostId && pairing.expiresAt > now)
+          .map((pairing) => ({ code: pairing.code, name: pairing.name })),
+      )
+    }
+    if (method === 'POST' && path === '/api/pair/approve') {
+      const input = await body(req)
+      const entry = [...pairings.entries()].find(
+        ([, pairing]) =>
+          pairing.code === input.code &&
+          !pairing.hostId &&
+          pairing.expiresAt > Date.now(),
+      )
+      if (!entry) return json(res, 404, { error: 'unknown or expired code' })
+      const hostId = `host-${randomBytes(6).toString('hex')}`
+      const hostToken = token()
+      hosts.set(hostId, {
+        hostId,
+        name: entry[1].name,
+        harnesses: [],
+        token: hostToken,
+        lastSeen: Date.now(),
+        streams: new Set(),
+        queue: [],
+      })
+      hostByToken.set(hostToken, hostId)
+      entry[1].hostId = hostId
+      return json(res, 200, { hostId })
+    }
+    if (method === 'POST' && path === '/api/hosts/revoke') {
+      const input = await body(req)
+      const host = hosts.get(String(input.hostId))
+      if (!host) return json(res, 404, { error: 'unknown host' })
+      hostByToken.delete(host.token)
+      for (const stream of host.streams) stream.end()
+      hosts.delete(host.hostId)
+      return json(res, 200, { ok: true })
+    }
+    if (method === 'GET' && path === '/api/hosts') {
+      return json(
+        res,
+        200,
+        [...hosts.values()].map((host) => ({
+          hostId: host.hostId,
+          name: host.name,
+          harnesses: host.harnesses,
+          online: host.streams.size > 0,
+          lastSeen: host.lastSeen,
+        })),
+      )
+    }
+    if (method === 'GET' && path === '/api/sessions') {
+      return json(
+        res,
+        200,
+        [...sessions.values()]
+          .sort((a, b) => b.lastActivity - a.lastActivity)
+          .map((session) => ({
+            hostId: session.hostId,
+            threadId: session.threadId,
+            harness: session.harness,
+            status: session.status,
+            lastActivity: session.lastActivity,
+            online: (hosts.get(session.hostId)?.streams.size ?? 0) > 0,
+          })),
+      )
+    }
+
+    const match =
+      /^\/api\/sessions\/([^/]+)\/([^/]+)\/(events|input|open)$/.exec(path)
+    if (match) {
+      const hostId = decodeURIComponent(match[1] ?? '')
+      const threadId = decodeURIComponent(match[2] ?? '')
+      const host = hosts.get(hostId)
+      if (!host) return json(res, 404, { error: 'unknown host' })
+      if (method === 'GET' && match[3] === 'events') {
+        const session = sessionFor(hostId, threadId)
+        openSse(res)
+        const from = Number(
+          url.searchParams.get('from') ?? req.headers['last-event-id'] ?? 0,
+        )
+        for (const entry of session.events) {
+          if (Number(entry.cursor) > from)
+            sse(res, { type: 'harness.event', ...entry }, entry.cursor)
+        }
+        session.clients.add(res)
+        const heartbeat = setInterval(() => res.write(': ping\n\n'), 15_000)
+        res.on('close', () => {
+          clearInterval(heartbeat)
+          session.clients.delete(res)
+        })
+        return
+      }
+      if (method === 'POST' && match[3] === 'input') {
+        const input = await body(req)
+        const requestId = `dash-${randomBytes(6).toString('hex')}`
+        const delivery = sendToHost(host, {
+          threadId,
+          frame: { type: 'harness.input', requestId, input: input.input },
+        })
+        return json(res, 202, { requestId, status: delivery })
+      }
+      if (method === 'POST' && match[3] === 'open') {
+        const delivery = sendToHost(host, {
+          threadId,
+          frame: { type: 'harness.subscribe', threadId },
+        })
+        return json(res, 202, { status: delivery })
+      }
+    }
+    return json(res, 404, { error: 'not found' })
+  }
+
+  const server = createServer((req, res) => {
+    route(req, res).catch((error: unknown) => {
+      if (!res.headersSent)
+        json(res, 400, {
+          error: error instanceof Error ? error.message : String(error),
+        })
+      else res.end()
+    })
+  })
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(options.port ?? 8790, options.hostname ?? '127.0.0.1', () =>
+      resolve(),
+    )
+  })
+  const address = server.address()
+  const port =
+    typeof address === 'object' && address
+      ? address.port
+      : (options.port ?? 8790)
+  return {
+    url: `http://${options.hostname ?? '127.0.0.1'}:${port}`,
+    ownerToken,
+    close: () =>
+      new Promise<void>((resolve) => {
+        server.closeAllConnections()
+        server.close(() => resolve())
+      }),
+  }
+}
diff --git a/packages/ai-dashboard/src/ui.ts b/packages/ai-dashboard/src/ui.ts
new file mode 100644
index 0000000000..4f0b2fd6ae
--- /dev/null
+++ b/packages/ai-dashboard/src/ui.ts
@@ -0,0 +1,194 @@
+// The dashboard web app: one static page, no build step. It renders every
+// value with textContent, never as HTML, so session content cannot inject
+// markup.
+
+export const MANIFEST_JSON = JSON.stringify({
+  name: 'TanStack AI Dashboard',
+  short_name: 'Harness',
+  start_url: '/',
+  display: 'standalone',
+  background_color: '#0b0d12',
+  theme_color: '#0b0d12',
+  icons: [],
+})
+
+// Caches the app shell only. API calls always go to the network.
+export const SERVICE_WORKER = `
+const SHELL = ['/', '/manifest.webmanifest']
+self.addEventListener('install', (event) => {
+  event.waitUntil(caches.open('harness-shell-v1').then((cache) => cache.addAll(SHELL)))
+})
+self.addEventListener('fetch', (event) => {
+  const url = new URL(event.request.url)
+  if (url.pathname.startsWith('/api/')) return
+  event.respondWith(fetch(event.request).catch(() => caches.match(event.request)))
+})
+`
+
+const SCRIPT = `
+const $ = (tag, props = {}, ...children) => {
+  const node = document.createElement(tag)
+  for (const [key, value] of Object.entries(props)) {
+    if (key === 'onclick' || key === 'onsubmit') node[key] = value
+    else if (key === 'class') node.className = value
+    else node.setAttribute(key, value)
+  }
+  for (const child of children) node.append(child instanceof Node ? child : document.createTextNode(String(child)))
+  return node
+}
+const fromHash = new URLSearchParams(location.hash.slice(1)).get('token')
+if (fromHash) { localStorage.setItem('harness-token', fromHash); history.replaceState(null, '', '/') }
+let token = localStorage.getItem('harness-token')
+let current = null
+let source = null
+
+async function api(path, options = {}) {
+  const response = await fetch(path, {
+    ...options,
+    headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + token, ...(options.headers || {}) },
+  })
+  if (response.status === 401) { localStorage.removeItem('harness-token'); token = null; render(); throw new Error('unauthorized') }
+  return response.json()
+}
+
+function login() {
+  const input = $('input', { type: 'password', placeholder: 'Owner token', autocomplete: 'off' })
+  return $('form', { class: 'card', onsubmit: (event) => {
+    event.preventDefault(); token = input.value.trim(); localStorage.setItem('harness-token', token); render()
+  } }, $('h2', {}, 'Sign in'), input, $('button', {}, 'Sign in'))
+}
+
+async function refresh() {
+  if (!token) return
+  const [pairings, hosts, sessions] = await Promise.all([api('/api/pairings'), api('/api/hosts'), api('/api/sessions')])
+  const side = document.getElementById('side')
+  side.replaceChildren(
+    $('h3', {}, 'Pairing requests'),
+    ...(pairings.length ? pairings.map((pairing) => $('div', { class: 'row' },
+      $('span', {}, pairing.name + ' ', $('code', {}, pairing.code)),
+      $('button', { onclick: async () => { await api('/api/pair/approve', { method: 'POST', body: JSON.stringify({ code: pairing.code }) }); refresh() } }, 'Approve'))) : [$('p', { class: 'muted' }, 'None')]),
+    $('h3', {}, 'Hosts'),
+    ...(hosts.length ? hosts.map((host) => $('div', { class: 'row' },
+      $('span', { class: host.online ? 'dot on' : 'dot' }), $('span', {}, host.name + ' (' + host.harnesses.join(', ') + ')'))) : [$('p', { class: 'muted' }, 'No hosts yet')]),
+    $('h3', {}, 'Sessions'),
+    ...(sessions.length ? sessions.map((session) => $('button', { class: 'session ' + session.status, onclick: () => open(session) },
+      session.threadId + ' | ' + (session.harness || '') + ' | ' + session.status)) : [$('p', { class: 'muted' }, 'No sessions yet')]),
+  )
+}
+
+function open(session) {
+  current = { ...session, messages: [], interrupts: [], questions: new Map(), running: false }
+  if (source) source.close()
+  const path = '/api/sessions/' + encodeURIComponent(session.hostId) + '/' + encodeURIComponent(session.threadId)
+  current.path = path
+  source = new EventSource(path + '/events?token=' + encodeURIComponent(token))
+  source.onmessage = (message) => { apply(JSON.parse(message.data)); draw() }
+  draw()
+}
+
+function apply(frame) {
+  if (frame.type !== 'harness.event' || !current) return
+  const event = frame.event
+  if (event.subagentRunId) return
+  if (event.type === 'TEXT_MESSAGE_CONTENT') {
+    const last = current.messages[current.messages.length - 1]
+    if (last && last.kind === 'assistant' && last.op === frame.operationId) last.text += event.delta
+    else current.messages.push({ kind: 'assistant', op: frame.operationId, text: event.delta })
+  } else if (event.type === 'TOOL_CALL_START') {
+    current.messages.push({ kind: 'tool', text: 'tool ' + event.toolCallName })
+  } else if (event.type === 'RUN_ERROR') {
+    current.messages.push({ kind: 'error', text: event.message })
+  } else if (event.type === 'RUN_FINISHED' && event.outcome && event.outcome.type === 'interrupt') {
+    current.interrupts = event.outcome.interrupts
+  } else if (event.type === 'CUSTOM') {
+    if (event.name === 'harness.operation.started') current.running = true
+    if (event.name === 'harness.operation.finished') current.running = false
+    if (event.name === 'harness.question') current.questions.set(event.value.questionId, event.value)
+    if (event.name === 'harness.question.answered') current.questions.delete(event.value.questionId)
+    if (event.name === 'harness.auth_required') current.messages.push({ kind: 'notice', text: 'Sign in to ' + event.value.connector + (event.value.url ? ': ' + event.value.url : '') })
+  }
+}
+
+async function send(input) {
+  if (input.op === 'prompt' || input.op === 'steer') current.messages.push({ kind: 'user', text: input.message })
+  const receipt = await api(current.path + '/input', { method: 'POST', body: JSON.stringify({ input }) })
+  if (receipt.status === 'queued') current.messages.push({ kind: 'notice', text: 'Queued: the host is offline.' })
+  draw()
+}
+
+function draw() {
+  const main = document.getElementById('main')
+  if (!current) { main.replaceChildren($('p', { class: 'muted' }, 'Pick a session.')); return }
+  const log = $('div', { class: 'log' }, ...current.messages.map((message) => $('div', { class: 'msg ' + message.kind }, message.text)))
+  const actions = []
+  if (current.interrupts.length) {
+    const decide = (approved) => { const resume = current.interrupts.map((interrupt) => ({ interruptId: interrupt.id, status: 'resolved', payload: approved })); current.interrupts = []; send({ op: 'resolve', resume }) }
+    actions.push($('div', { class: 'card' }, $('strong', {}, 'Waiting for approval: '), current.interrupts.map((interrupt) => interrupt.message || interrupt.toolCallId || interrupt.id).join(', '),
+      $('div', { class: 'row' }, $('button', { onclick: () => decide(true) }, 'Approve'), $('button', { class: 'ghost', onclick: () => decide(false) }, 'Reject'))))
+  }
+  for (const question of current.questions.values()) {
+    const answer = $('input', { placeholder: 'Your answer' })
+    const isBoolean = question.schema && question.schema.type === 'boolean'
+    actions.push($('div', { class: 'card' }, $('strong', {}, question.message),
+      isBoolean
+        ? $('div', { class: 'row' }, $('button', { onclick: () => send({ op: 'answer', questionId: question.questionId, value: true }) }, 'Yes'), $('button', { class: 'ghost', onclick: () => send({ op: 'answer', questionId: question.questionId, value: false }) }, 'No'))
+        : $('form', { class: 'row', onsubmit: (event) => { event.preventDefault(); send({ op: 'answer', questionId: question.questionId, value: answer.value }) } }, answer, $('button', {}, 'Answer'))))
+  }
+  const box = $('input', { placeholder: current.running ? 'Steer the running turn' : 'Send a message' })
+  const form = $('form', { class: 'row prompt', onsubmit: (event) => {
+    event.preventDefault(); const text = box.value.trim(); if (!text) return; box.value = ''
+    send({ op: current.running ? 'steer' : 'prompt', message: text })
+  } }, box, $('button', {}, 'Send'), $('button', { type: 'button', class: 'ghost', onclick: () => send({ op: 'cancel' }) }, 'Stop'))
+  main.replaceChildren($('h2', {}, current.threadId + (current.running ? ' (working)' : '')), log, ...actions, form)
+  log.scrollTop = log.scrollHeight
+}
+
+function render() {
+  const app = document.getElementById('app')
+  if (!token) { app.replaceChildren(login()); return }
+  app.replaceChildren($('aside', { id: 'side' }), $('main', { id: 'main' }))
+  draw(); refresh().catch(() => {})
+}
+setInterval(() => refresh().catch(() => {}), 5000)
+if ('serviceWorker' in navigator) navigator.serviceWorker.register('/sw.js').catch(() => {})
+render()
+`
+
+export const DASHBOARD_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="theme-color" content="#0b0d12">
+<link rel="manifest" href="/manifest.webmanifest">
+<title>TanStack AI Dashboard</title>
+<style>
+  :root { color-scheme: dark; --bg: #0b0d12; --panel: #141821; --line: #252b38; --text: #e6e9ef; --muted: #8b93a7; --accent: #6ea8fe; }
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 15px/1.45 system-ui, sans-serif; background: var(--bg); color: var(--text); }
+  #app { display: grid; grid-template-columns: 300px 1fr; min-height: 100vh; }
+  aside { border-right: 1px solid var(--line); padding: 16px; overflow-y: auto; }
+  main { padding: 16px; display: flex; flex-direction: column; gap: 12px; min-width: 0; }
+  h2, h3 { margin: 0 0 8px; } h3 { font-size: 13px; text-transform: uppercase; color: var(--muted); margin-top: 16px; }
+  .row { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; }
+  .muted { color: var(--muted); }
+  .card { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 12px; display: flex; flex-direction: column; gap: 8px; max-width: 420px; }
+  input { flex: 1; min-width: 0; padding: 10px; border-radius: 8px; border: 1px solid var(--line); background: var(--bg); color: var(--text); font: inherit; }
+  button { padding: 9px 14px; border-radius: 8px; border: 0; background: var(--accent); color: #06121f; font: inherit; font-weight: 600; cursor: pointer; }
+  button.ghost { background: transparent; color: var(--text); border: 1px solid var(--line); }
+  button.session { display: block; width: 100%; text-align: left; background: var(--panel); color: var(--text); border: 1px solid var(--line); margin-bottom: 6px; font-weight: 400; }
+  button.session.waiting { border-color: #f5b041; } button.session.running { border-color: var(--accent); }
+  .dot { width: 9px; height: 9px; border-radius: 50%; background: #555; display: inline-block; } .dot.on { background: #3ecf8e; }
+  .log { flex: 1; overflow-y: auto; display: flex; flex-direction: column; gap: 8px; min-height: 200px; max-height: 65vh; }
+  .msg { white-space: pre-wrap; padding: 10px 12px; border-radius: 10px; background: var(--panel); max-width: 80ch; }
+  .msg.user { align-self: flex-end; background: #1d3557; } .msg.tool, .msg.notice { color: var(--muted); background: transparent; padding: 2px 12px; }
+  .msg.error { border: 1px solid #e5484d; }
+  code { background: var(--panel); padding: 2px 6px; border-radius: 6px; }
+  @media (max-width: 720px) { #app { grid-template-columns: 1fr; } aside { border-right: 0; border-bottom: 1px solid var(--line); } }
+</style>
+</head>
+<body>
+<div id="app"></div>
+<script>${SCRIPT}</script>
+</body>
+</html>`
diff --git a/packages/ai-dashboard/tests/relay.test.ts b/packages/ai-dashboard/tests/relay.test.ts
new file mode 100644
index 0000000000..daee6fa05f
--- /dev/null
+++ b/packages/ai-dashboard/tests/relay.test.ts
@@ -0,0 +1,219 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { EventType } from '@tanstack/ai'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { startDashboard } from '../src'
+import { connectDashboard } from '../src/connect'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+
+let calls = 0
+function adapterSaying(answer: string): AnyTextAdapter {
+  return {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    '~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,
+    },
+    chatStream: () =>
+      (async function* (): AsyncGenerator<StreamChunk> {
+        calls += 1
+        const messageId = `m-${calls}`
+        const now = Date.now()
+        yield {
+          type: EventType.RUN_STARTED,
+          runId: 'r',
+          threadId: 't',
+          timestamp: now,
+        }
+        yield {
+          type: EventType.TEXT_MESSAGE_START,
+          messageId,
+          role: 'assistant',
+          timestamp: now,
+        }
+        yield {
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          messageId,
+          delta: answer,
+          timestamp: now,
+        }
+        yield { type: EventType.TEXT_MESSAGE_END, messageId, timestamp: now }
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId: 'r',
+          threadId: 't',
+          timestamp: now,
+          metadata: { tanstack: { finishReason: 'stop' } },
+        }
+      })(),
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+  }
+}
+
+const cleanups: Array<() => unknown> = []
+afterEach(async () => {
+  for (const cleanup of cleanups.splice(0).reverse()) await cleanup()
+})
+
+describe('dashboard relay', () => {
+  it(
+    'pairs a host, shows its session, and relays a prompt and its answer',
+    { timeout: 20_000 },
+    async () => {
+      const dashboard = await startDashboard({ port: 0 })
+      cleanups.push(() => dashboard.close())
+      const owner = {
+        Authorization: `Bearer ${dashboard.ownerToken}`,
+        'Content-Type': 'application/json',
+      }
+
+      // The app shell loads without a token; the API does not.
+      expect((await fetch(`${dashboard.url}/`)).status).toBe(200)
+      expect((await fetch(`${dashboard.url}/api/hosts`)).status).toBe(401)
+
+      const host = createHarnessHost({ persistence: memoryPersistence() })
+      cleanups.push(() => host.close())
+      const harness = defineHarness({
+        name: 'acme/remote',
+        adapter: adapterSaying('Hello from the host.'),
+      })
+
+      let savedToken = ''
+      const connecting = connectDashboard({
+        host,
+        harness,
+        url: dashboard.url,
+        threads: ['main'],
+        onPairingCode: (code) => {
+          // The owner approves the code in the dashboard.
+          void fetch(`${dashboard.url}/api/pair/approve`, {
+            method: 'POST',
+            headers: owner,
+            body: JSON.stringify({ code }),
+          })
+        },
+        onToken: (token) => {
+          savedToken = token
+        },
+      })
+      const connection = await connecting
+      cleanups.push(() => connection.close())
+      expect(savedToken).toBe(connection.token)
+
+      await vi.waitFor(async () => {
+        const hosts = await (
+          await fetch(`${dashboard.url}/api/hosts`, { headers: owner })
+        ).json()
+        expect(hosts).toMatchObject([
+          { name: 'acme/remote', online: true, harnesses: ['acme/remote'] },
+        ])
+      })
+      const [{ hostId }] = await (
+        await fetch(`${dashboard.url}/api/hosts`, { headers: owner })
+      ).json()
+      const receipt = await (
+        await fetch(`${dashboard.url}/api/sessions/${hostId}/main/input`, {
+          method: 'POST',
+          headers: owner,
+          body: JSON.stringify({
+            input: { op: 'prompt', message: 'hi from my phone' },
+          }),
+        })
+      ).json()
+      expect(receipt.status).toBe('sent')
+
+      // The answer comes back through the relay cache.
+      await vi.waitFor(async () => {
+        const sessions = await (
+          await fetch(`${dashboard.url}/api/sessions`, { headers: owner })
+        ).json()
+        expect(sessions).toMatchObject([
+          { hostId, threadId: 'main', harness: 'acme/remote', status: 'idle' },
+        ])
+      })
+      const controller = new AbortController()
+      const events = await fetch(
+        `${dashboard.url}/api/sessions/${hostId}/main/events?token=${dashboard.ownerToken}`,
+        {
+          signal: controller.signal,
+        },
+      )
+      const reader = events.body!.getReader()
+      let text = ''
+      while (!text.includes('harness.operation.finished')) {
+        const { value, done } = await reader.read()
+        if (done) break
+        text += new TextDecoder().decode(value)
+      }
+      controller.abort()
+      expect(text).toContain('Hello from the host.')
+    },
+  )
+
+  it(
+    'queues inputs for an offline host and refuses revoked hosts',
+    { timeout: 20_000 },
+    async () => {
+      const dashboard = await startDashboard({ port: 0 })
+      cleanups.push(() => dashboard.close())
+      const owner = {
+        Authorization: `Bearer ${dashboard.ownerToken}`,
+        'Content-Type': 'application/json',
+      }
+
+      const started = await (
+        await fetch(`${dashboard.url}/api/pair/start`, {
+          method: 'POST',
+          body: JSON.stringify({ name: 'laptop' }),
+        })
+      ).json()
+      await fetch(`${dashboard.url}/api/pair/approve`, {
+        method: 'POST',
+        headers: owner,
+        body: JSON.stringify({ code: started.code }),
+      })
+      const status = await (
+        await fetch(
+          `${dashboard.url}/api/pair/status?pairingId=${started.pairingId}`,
+        )
+      ).json()
+      expect(status.status).toBe('approved')
+
+      const queued = await (
+        await fetch(`${dashboard.url}/api/sessions/${status.hostId}/t/input`, {
+          method: 'POST',
+          headers: owner,
+          body: JSON.stringify({ input: { op: 'prompt', message: 'later' } }),
+        })
+      ).json()
+      expect(queued.status).toBe('queued')
+
+      await fetch(`${dashboard.url}/api/hosts/revoke`, {
+        method: 'POST',
+        headers: owner,
+        body: JSON.stringify({ hostId: status.hostId }),
+      })
+      const refused = await fetch(`${dashboard.url}/api/host/hello`, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${status.token}`,
+          'Content-Type': 'application/json',
+        },
+        body: '{}',
+      })
+      expect(refused.status).toBe(401)
+    },
+  )
+})
diff --git a/packages/ai-dashboard/tsconfig.json b/packages/ai-dashboard/tsconfig.json
new file mode 100644
index 0000000000..29112eff9f
--- /dev/null
+++ b/packages/ai-dashboard/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["vite.config.ts", "./src", "./tests"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/ai-dashboard/vite.config.ts b/packages/ai-dashboard/vite.config.ts
new file mode 100644
index 0000000000..dadc8e1df5
--- /dev/null
+++ b/packages/ai-dashboard/vite.config.ts
@@ -0,0 +1,35 @@
+import { defineConfig, mergeConfig } from 'vitest/config'
+import { tanstackViteConfig } from '@tanstack/vite-config'
+import packageJson from './package.json'
+
+const config = defineConfig({
+  test: {
+    name: packageJson.name,
+    dir: './',
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'lcov'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        'tests/',
+        '**/*.test.ts',
+        '**/*.config.ts',
+      ],
+      include: ['src/**/*.ts'],
+    },
+  },
+})
+
+export default mergeConfig(
+  config,
+  tanstackViteConfig({
+    entry: ['./src/index.ts', './src/connect.ts'],
+    srcDir: './src',
+    cjs: false,
+  }),
+)
diff --git a/packages/ai-harness-cli/package.json b/packages/ai-harness-cli/package.json
index e9224933f2..4f91fbfe82 100644
--- a/packages/ai-harness-cli/package.json
+++ b/packages/ai-harness-cli/package.json
@@ -72,17 +72,22 @@
   "peerDependencies": {
     "@tanstack/ai": "workspace:^",
     "@tanstack/ai-acp": "workspace:^",
+    "@tanstack/ai-dashboard": "workspace:^",
     "@tanstack/ai-harness": "workspace:^",
     "@tanstack/ai-persistence": "workspace:^"
   },
   "peerDependenciesMeta": {
     "@tanstack/ai-acp": {
       "optional": true
+    },
+    "@tanstack/ai-dashboard": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@tanstack/ai": "workspace:*",
     "@tanstack/ai-acp": "workspace:*",
+    "@tanstack/ai-dashboard": "workspace:*",
     "@tanstack/ai-harness": "workspace:*",
     "@tanstack/ai-persistence": "workspace:*",
     "@tanstack/ai-sandbox": "workspace:*",
diff --git a/packages/ai-harness-cli/src/args.ts b/packages/ai-harness-cli/src/args.ts
index c83474e715..9d49cf37c7 100644
--- a/packages/ai-harness-cli/src/args.ts
+++ b/packages/ai-harness-cli/src/args.ts
@@ -10,6 +10,7 @@ export interface CliArgs {
   hostname: string
   token?: string
   thread: string
+  dashboard?: string
 }
 
 export const USAGE = `Usage: <your-cli> [options]
@@ -25,6 +26,7 @@ Options:
       --host <name>      Host name for --serve (default 127.0.0.1)
       --token <token>    Bearer token for --serve (default: HARNESS_TOKEN, or a new random token)
       --thread <id>      Conversation id (default: main)
+      --dashboard <url>  Connect to a dashboard (pairs on first use; set HARNESS_DASHBOARD_TOKEN to skip)
   -h, --help             Show this help
 
 Exit codes for --print: 0 done, 1 failed, 2 waiting for approval, 130 cancelled.`
@@ -43,6 +45,7 @@ export function parseCliArgs(argv: ReadonlyArray<string>): CliArgs {
       host: { type: 'string' },
       token: { type: 'string' },
       thread: { type: 'string' },
+      dashboard: { type: 'string' },
     },
     strict: true,
   })
@@ -64,5 +67,6 @@ export function parseCliArgs(argv: ReadonlyArray<string>): CliArgs {
     hostname: values.host ?? '127.0.0.1',
     ...(values.token !== undefined ? { token: values.token } : {}),
     thread: values.thread ?? 'main',
+    ...(values.dashboard !== undefined ? { dashboard: values.dashboard } : {}),
   }
 }
diff --git a/packages/ai-harness-cli/src/index.ts b/packages/ai-harness-cli/src/index.ts
index d91dd0d9d7..18dbac479d 100644
--- a/packages/ai-harness-cli/src/index.ts
+++ b/packages/ai-harness-cli/src/index.ts
@@ -63,6 +63,38 @@ export async function runCli(
       return EXIT.ok
     }
 
+    if (args.dashboard) {
+      const { connectDashboard } =
+        await import('@tanstack/ai-dashboard/connect').catch(() => {
+          throw new Error(
+            '--dashboard needs @tanstack/ai-dashboard. Install it next to @tanstack/ai-harness-cli.',
+          )
+        })
+      const savedToken = env.HARNESS_DASHBOARD_TOKEN
+      const connection = await connectDashboard({
+        host,
+        harness,
+        url: args.dashboard,
+        threads: [args.thread],
+        ...(savedToken ? { token: savedToken } : {}),
+        onPairingCode: (code) =>
+          stderr.write(
+            `Pair this host in the dashboard with the code ${code}. Waiting for approval...\n`,
+          ),
+        onToken: (token) =>
+          stderr.write(
+            `Paired. Set HARNESS_DASHBOARD_TOKEN=${token} to skip pairing next time.\n`,
+          ),
+      })
+      stderr.write(`Connected to ${args.dashboard}. Press Ctrl+C to stop.\n`)
+      await new Promise<void>((resolve) => {
+        process.once('SIGINT', resolve)
+        process.once('SIGTERM', resolve)
+      })
+      connection.close()
+      return EXIT.ok
+    }
+
     if (args.serve) {
       const token = args.token ?? env.HARNESS_TOKEN ?? createToken()
       const server = await serve({
diff --git a/packages/ai-harness-cli/src/lines.ts b/packages/ai-harness-cli/src/lines.ts
index 26cc914f8e..741005b97d 100644
--- a/packages/ai-harness-cli/src/lines.ts
+++ b/packages/ai-harness-cli/src/lines.ts
@@ -25,7 +25,13 @@ export async function runLines(
 ): Promise<void> {
   const reader = new AbortController()
   let entries: Array<ViewEntry> = []
-  let printed = 0
+  // True while streamed text has no line break at its end yet.
+  let midLine = false
+  const line = (text: string) => {
+    if (midLine) stdout.write('\n')
+    midLine = false
+    stdout.write(`${text}\n`)
+  }
   const printing = (async () => {
     for await (const entry of session.events({
       from: session.snapshot().cursor,
@@ -42,40 +48,40 @@ export async function runLines(
         previous.operationId === last.operationId
       ) {
         stdout.write(last.text.slice(previous.text.length))
+        midLine = true
+      } else if (last.kind === 'assistant') {
+        if (midLine) stdout.write('\n')
+        stdout.write(last.text)
+        midLine = true
       } else {
-        if (printed > 0) stdout.write('\n')
-        stdout.write(last.kind === 'assistant' ? last.text : `[${last.text}]`)
+        line(`[${last.text}]`)
       }
-      printed += 1
       entries = next
     }
   })()
 
   const lines = createInterface({ input, crlfDelay: Infinity })
   const pendingLater: Array<Promise<void>> = []
-  for await (const line of lines) {
+  for await (const typed of lines) {
     const snapshot = session.snapshot()
     if (snapshot.status === 'requires_action') {
       await resolveAll(
         session,
         snapshot.pendingInterrupts,
-        /^y(es)?$/i.test(line.trim()),
+        /^y(es)?$/i.test(typed.trim()),
       )
     } else {
-      const result = await handleLine(session, line)
+      const result = await handleLine(session, typed)
       if (result.type === 'exit') break
-      if (result.type === 'notice' && result.text)
-        stdout.write(`${result.text}\n`)
+      if (result.type === 'notice' && result.text) line(result.text)
       if (result.type === 'notice' && result.later) {
-        pendingLater.push(
-          result.later.then((text) => void stdout.write(`\n${text}\n`)),
-        )
+        pendingLater.push(result.later.then((text) => line(text)))
       }
     }
     await waitIdle(session)
     const after = session.snapshot()
     if (after.status === 'requires_action') {
-      stdout.write(`\n${approvalQuestion(after.pendingInterrupts)}\n`)
+      line(approvalQuestion(after.pendingInterrupts))
     }
   }
   lines.close()
@@ -83,5 +89,5 @@ export async function runLines(
   await waitIdle(session)
   reader.abort()
   await printing
-  if (printed > 0) stdout.write('\n')
+  if (midLine) stdout.write('\n')
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4a914a15c6..d8f2711c60 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -174,6 +174,43 @@ importers:
         specifier: ^8.2.1
         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)
 
+  examples/harness-cli:
+    dependencies:
+      '@tanstack/ai':
+        specifier: workspace:*
+        version: link:../../packages/ai
+      '@tanstack/ai-acp':
+        specifier: workspace:*
+        version: link:../../packages/ai-acp
+      '@tanstack/ai-anthropic':
+        specifier: workspace:*
+        version: link:../../packages/ai-anthropic
+      '@tanstack/ai-dashboard':
+        specifier: workspace:*
+        version: link:../../packages/ai-dashboard
+      '@tanstack/ai-harness':
+        specifier: workspace:*
+        version: link:../../packages/ai-harness
+      '@tanstack/ai-harness-cli':
+        specifier: workspace:*
+        version: link:../../packages/ai-harness-cli
+      '@tanstack/ai-openai':
+        specifier: workspace:*
+        version: link:../../packages/ai-openai
+      '@tanstack/ai-persistence':
+        specifier: workspace:*
+        version: link:../../packages/ai-persistence
+      zod:
+        specifier: ^4.2.0
+        version: 4.3.6
+    devDependencies:
+      '@types/node':
+        specifier: ^24.10.1
+        version: 24.13.6
+      tsx:
+        specifier: ^4.23.12
+        version: 4.23.12
+
   examples/react/basic-chat:
     dependencies:
       '@tailwindcss/vite':
@@ -2335,6 +2372,21 @@ importers:
         specifier: 4.1.10
         version: 4.1.10(vitest@4.1.11)
 
+  packages/ai-dashboard:
+    devDependencies:
+      '@tanstack/ai':
+        specifier: workspace:*
+        version: link:../ai
+      '@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)
+
   packages/ai-devtools:
     dependencies:
       '@tanstack/ai':
@@ -2556,6 +2608,9 @@ importers:
       '@tanstack/ai-acp':
         specifier: workspace:*
         version: link:../ai-acp
+      '@tanstack/ai-dashboard':
+        specifier: workspace:*
+        version: link:../ai-dashboard
       '@tanstack/ai-harness':
         specifier: workspace:*
         version: link:../ai-harness
@@ -3611,6 +3666,9 @@ importers:
       '@tanstack/ai-compaction':
         specifier: workspace:*
         version: link:../../packages/ai-compaction
+      '@tanstack/ai-dashboard':
+        specifier: workspace:*
+        version: link:../../packages/ai-dashboard
       '@tanstack/ai-elevenlabs':
         specifier: workspace:*
         version: link:../../packages/ai-elevenlabs
diff --git a/testing/e2e/package.json b/testing/e2e/package.json
index 41b655bed1..03584db0fa 100644
--- a/testing/e2e/package.json
+++ b/testing/e2e/package.json
@@ -26,6 +26,7 @@
     "@tanstack/ai-client": "workspace:*",
     "@tanstack/ai-cloudflare": "workspace:*",
     "@tanstack/ai-compaction": "workspace:*",
+    "@tanstack/ai-dashboard": "workspace:*",
     "@tanstack/ai-elevenlabs": "workspace:*",
     "@tanstack/ai-fal": "workspace:*",
     "@tanstack/ai-gemini": "workspace:*",
diff --git a/testing/e2e/tests/dashboard.spec.ts b/testing/e2e/tests/dashboard.spec.ts
new file mode 100644
index 0000000000..786a8f0363
--- /dev/null
+++ b/testing/e2e/tests/dashboard.spec.ts
@@ -0,0 +1,124 @@
+import { EventType } from '@tanstack/ai'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { startDashboard } from '@tanstack/ai-dashboard'
+import { connectDashboard } from '@tanstack/ai-dashboard/connect'
+import { test, expect } from './fixtures'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+
+/** Answers with what the user said, so the test can follow the round trip. */
+function echoAdapter(): AnyTextAdapter {
+  let calls = 0
+  return {
+    kind: 'text',
+    name: 'echo',
+    model: 'echo',
+    '~types': {
+      providerOptions: {},
+      inputModalities: ['text'],
+      messageMetadataByModality: {
+        text: undefined,
+        image: undefined,
+        audio: undefined,
+        video: undefined,
+        document: undefined,
+      },
+      toolCapabilities: [],
+      toolCallMetadata: undefined,
+      systemPromptMetadata: undefined as never,
+    },
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+    chatStream: (options) =>
+      (async function* (): AsyncGenerator<StreamChunk> {
+        calls += 1
+        const messageId = `echo-${calls}`
+        const now = Date.now()
+        const last = options.messages.at(-1)
+        const said = typeof last?.content === 'string' ? last.content : ''
+        yield {
+          type: EventType.RUN_STARTED,
+          runId: 'r',
+          threadId: 't',
+          timestamp: now,
+        }
+        yield {
+          type: EventType.TEXT_MESSAGE_START,
+          messageId,
+          role: 'assistant',
+          timestamp: now,
+        }
+        yield {
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          messageId,
+          delta: `You said: ${said}`,
+          timestamp: now,
+        }
+        yield { type: EventType.TEXT_MESSAGE_END, messageId, timestamp: now }
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId: 'r',
+          threadId: 't',
+          timestamp: now,
+          metadata: { tanstack: { finishReason: 'stop' } },
+        }
+      })(),
+  }
+}
+
+test.describe('dashboard', () => {
+  test('a paired host shows up, and a prompt from a phone reaches it', async ({
+    page,
+  }) => {
+    const dashboard = await startDashboard({ port: 0 })
+    const owner = {
+      Authorization: `Bearer ${dashboard.ownerToken}`,
+      'Content-Type': 'application/json',
+    }
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const connection = await connectDashboard({
+      host,
+      harness: defineHarness({
+        name: 'acme/phone-demo',
+        adapter: echoAdapter(),
+      }),
+      url: dashboard.url,
+      threads: ['main'],
+      onPairingCode: (code) =>
+        void fetch(`${dashboard.url}/api/pair/approve`, {
+          method: 'POST',
+          headers: owner,
+          body: JSON.stringify({ code }),
+        }),
+    })
+    try {
+      const [{ hostId }] = await (
+        await fetch(`${dashboard.url}/api/hosts`, { headers: owner })
+      ).json()
+      await fetch(`${dashboard.url}/api/sessions/${hostId}/main/input`, {
+        method: 'POST',
+        headers: owner,
+        body: JSON.stringify({ input: { op: 'prompt', message: 'first' } }),
+      })
+
+      await page.setViewportSize({ width: 390, height: 844 })
+      await page.goto(`${dashboard.url}/#token=${dashboard.ownerToken}`)
+      await expect(
+        page.getByText('acme/phone-demo (acme/phone-demo)'),
+      ).toBeVisible()
+      await page.getByRole('button', { name: /main/ }).click()
+      await expect(page.getByText('You said: first')).toBeVisible()
+
+      await page
+        .getByPlaceholder(/Send a message|Steer/)
+        .fill('hello from the phone')
+      await page.getByRole('button', { name: 'Send' }).click()
+      await expect(
+        page.getByText('You said: hello from the phone'),
+      ).toBeVisible()
+    } finally {
+      connection.close()
+      await host.close()
+      await dashboard.close()
+    }
+  })
+})

From 551c8670ef921be19be1b2fa7aeae8ae244f0497 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 14:23:35 +0200
Subject: [PATCH 014/286] test(ai): cover every bound activity wrapper

---
 packages/ai/tests/bound-activities.test.ts | 148 +++++++++++++++++++++
 1 file changed, 148 insertions(+)
 create mode 100644 packages/ai/tests/bound-activities.test.ts

diff --git a/packages/ai/tests/bound-activities.test.ts b/packages/ai/tests/bound-activities.test.ts
new file mode 100644
index 0000000000..1eda9780c6
--- /dev/null
+++ b/packages/ai/tests/bound-activities.test.ts
@@ -0,0 +1,148 @@
+import { describe, expect, it, vi } from 'vitest'
+
+// Replace every activity with a spy that returns the options it got, so the
+// test sees exactly what each bound wrapper passes on.
+const record = (name: string) =>
+  vi.fn((options: unknown) => ({ name, options }))
+vi.mock('../src/activities/chat/index', async (importOriginal) => ({
+  ...(await importOriginal<object>()),
+  chat: record('chat'),
+}))
+vi.mock('../src/activities/summarize/index', () => ({
+  summarize: record('summarize'),
+}))
+vi.mock('../src/activities/generateImage/index', () => ({
+  generateImage: record('image'),
+}))
+vi.mock('../src/activities/generateVideo/index', () => ({
+  generateVideo: record('video'),
+}))
+vi.mock('../src/activities/generateAudio/index', () => ({
+  generateAudio: record('audio'),
+}))
+vi.mock('../src/activities/generateSpeech/index', () => ({
+  generateSpeech: record('speech'),
+}))
+vi.mock('../src/activities/generateVoice/index', () => ({
+  generateVoice: record('voice'),
+}))
+vi.mock('../src/activities/generateTranscription/index', () => ({
+  generateTranscription: record('transcription'),
+}))
+vi.mock('../src/activities/generateWorld/index', () => ({
+  generateWorld: record('world'),
+}))
+vi.mock('../src/activities/generateLiveVideo/index', () => ({
+  generateLiveVideo: record('liveVideo'),
+}))
+vi.mock('../src/activities/embed/index', () => ({ embed: record('embed') }))
+vi.mock('../src/activities/rerank/index', () => ({ rerank: record('rerank') }))
+vi.mock('../src/activities/evaluate/index', () => ({
+  decide: record('decide'),
+}))
+
+const { createBoundActivities } =
+  await import('../src/activities/chat/agents/bound')
+
+const input = {
+  input: undefined,
+  messages: [{ role: 'user' as const, content: 'hi' }],
+  threadId: 'thread-1',
+  runId: 'run-1',
+  parentRunId: 'parent-1',
+  subagentRunId: 'child-1',
+}
+
+type Recorded = { name: string; options: Record<string, any> }
+
+describe('createBoundActivities', () => {
+  const generationMiddleware = [{ name: 'host-generation' }]
+  const chatMiddleware = [{ name: 'host-chat' }]
+
+  function bound() {
+    const controller = new AbortController()
+    const activities = createBoundActivities(input, controller, {
+      chatMiddleware: chatMiddleware as never,
+      generationMiddleware: generationMiddleware as never,
+    })
+    return { activities, controller }
+  }
+
+  it('gives every id-taking activity its own run id, the thread, the signal, and host middleware first', () => {
+    const { activities, controller } = bound()
+    const own = { name: 'own' }
+    const calls: Array<[keyof typeof activities, string]> = [
+      ['summarize', 'summarize'],
+      ['generateImage', 'image'],
+      ['generateVideo', 'video'],
+      ['generateAudio', 'audio'],
+      ['generateSpeech', 'speech'],
+      ['generateVoice', 'voice'],
+      ['generateTranscription', 'transcription'],
+      ['generateWorld', 'world'],
+      ['generateLiveVideo', 'liveVideo'],
+    ]
+    calls.forEach(([method, activity], index) => {
+      const call = activities[method] as unknown as (
+        options: object,
+      ) => Recorded
+      const result = call({ prompt: 'x', middleware: [own] })
+      expect(result.name).toBe(activity)
+      expect(result.options).toMatchObject({
+        threadId: 'thread-1',
+        runId: `run-1:${activity}-${index + 1}`,
+        abortSignal: controller.signal,
+        prompt: 'x',
+      })
+      expect(result.options.middleware).toEqual([...generationMiddleware, own])
+    })
+  })
+
+  it('passes only middleware to embed, and the signal plus middleware to rerank and decide', () => {
+    const { activities, controller } = bound()
+    const embed = (
+      activities.embed as unknown as (options: object) => Recorded
+    )({ input: 'x' })
+    expect(embed.options).toEqual({
+      input: 'x',
+      middleware: generationMiddleware,
+    })
+
+    for (const method of ['rerank', 'decide'] as const) {
+      const call = activities[method] as unknown as (
+        options: object,
+      ) => Recorded
+      const result = call({ query: 'q' })
+      expect(result.options).toEqual({
+        query: 'q',
+        abortSignal: controller.signal,
+        middleware: generationMiddleware,
+      })
+    }
+  })
+
+  it('fills chat with the child ids and messages, and lets options win', () => {
+    const { activities, controller } = bound()
+    const chat = activities.chat as unknown as (options: object) => Recorded
+    const defaults = chat({ adapter: 'a' })
+    expect(defaults.options).toMatchObject({
+      messages: input.messages,
+      threadId: 'thread-1',
+      runId: 'run-1',
+      parentRunId: 'parent-1',
+      subagentRunId: 'child-1',
+      abortController: controller,
+      middleware: chatMiddleware,
+    })
+    const custom = chat({ adapter: 'a', messages: [], threadId: 'mine' })
+    expect(custom.options).toMatchObject({ messages: [], threadId: 'mine' })
+  })
+
+  it('works without a binding', () => {
+    const activities = createBoundActivities(input, new AbortController())
+    const result = (
+      activities.generateImage as unknown as (options: object) => Recorded
+    )({ prompt: 'x' })
+    expect(result.options.middleware).toEqual([])
+  })
+})

From 24c16d5a870535de80f166a512a27b1e479162da Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 14:27:18 +0200
Subject: [PATCH 015/286] test(ai-sandbox): type the snapshot fixture by the
 snapshot persistence shape

---
 packages/ai-sandbox/tests/snapshot-lifecycle.test.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/ai-sandbox/tests/snapshot-lifecycle.test.ts b/packages/ai-sandbox/tests/snapshot-lifecycle.test.ts
index f46eb5a61b..23371010c8 100644
--- a/packages/ai-sandbox/tests/snapshot-lifecycle.test.ts
+++ b/packages/ai-sandbox/tests/snapshot-lifecycle.test.ts
@@ -10,6 +10,7 @@ import {
 import { defineSandbox } from '../src/sandbox'
 import { withSandbox } from '../src/middleware'
 import { memorySandboxSnapshots } from '../src/memory-snapshots'
+import type { MemorySnapshotPersistence } from '../src/memory-snapshot-types'
 import { SandboxCapability } from '../src/capabilities'
 import { InMemorySandboxInstanceStore } from '../src/instance-store'
 import { InMemorySandboxCheckpointStore } from '../src/checkpoint-store'
@@ -72,7 +73,7 @@ type WorkspaceSeed =
   | { path: string; type: 'dir' }
   | { path: string; type: 'file'; data: Uint8Array }
 type FixtureOptions = {
-  persistence?: ReturnType<typeof memoryPersistence>
+  persistence?: MemorySnapshotPersistence
   checkpoints?: SandboxCheckpointStore
   workspace?: Array<WorkspaceSeed>
   onWorkspaceList?: (path: string) => void | Promise<void>
@@ -88,7 +89,7 @@ type Fixture = {
   events: Array<Event>
   instances: InMemorySandboxInstanceStore
   checkpoints: SandboxCheckpointStore
-  persistence: ReturnType<typeof memoryPersistence>
+  persistence: MemorySnapshotPersistence
   definition: ReturnType<typeof defineSandbox>
   resumed?: SandboxHandle
 }

From 924aa4f7008ea0f2f6f155552323983796882512 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 14:52:51 +0200
Subject: [PATCH 016/286] test(ai-harness): cover buildHarness without Bun, run
 the real build only where Bun exists

---
 packages/ai-harness/tests/build-stub.test.ts | 300 +++++++++++++++++++
 packages/ai-harness/tests/build.test.ts      |   7 +-
 2 files changed, 306 insertions(+), 1 deletion(-)
 create mode 100644 packages/ai-harness/tests/build-stub.test.ts

diff --git a/packages/ai-harness/tests/build-stub.test.ts b/packages/ai-harness/tests/build-stub.test.ts
new file mode 100644
index 0000000000..838085ef57
--- /dev/null
+++ b/packages/ai-harness/tests/build-stub.test.ts
@@ -0,0 +1,300 @@
+import { createHash } from 'node:crypto'
+import {
+  chmod,
+  mkdir,
+  readFile,
+  readdir,
+  rm,
+  writeFile,
+} from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { EventType, chat } from '@tanstack/ai'
+import { artifactText, buildHarness, readManifest } from '../src/build'
+import type { StreamChunk } from '@tanstack/ai'
+
+// These tests stand in a small script for Bun, so they run where Bun is not
+// installed. The script "bundles" by copying a hand-written worker that
+// speaks the harness frames. build.test.ts covers a real Bun build.
+const tmp = fileURLToPath(new URL('./.tmp-build-stub/', import.meta.url))
+const app = join(tmp, 'app')
+const broken = join(tmp, 'broken')
+const entry = join(app, 'studio.ts')
+
+const stubWorker = `
+import { createInterface } from 'node:readline'
+const send = (frame) => process.stdout.write(JSON.stringify(frame) + '\\n')
+let turns = 0
+createInterface({ input: process.stdin }).on('line', (line) => {
+  const frame = JSON.parse(line)
+  if (frame.type !== 'harness.input') return
+  const message = frame.input.message
+  if (message === 'reject') {
+    send({ type: 'harness.receipt', requestId: frame.requestId, status: 'rejected', reason: 'busy' })
+    return
+  }
+  if (message === 'reject quietly') {
+    send({ type: 'harness.receipt', requestId: frame.requestId, status: 'rejected' })
+    return
+  }
+  if (message === 'crash') {
+    send({ type: 'harness.error', message: 'worker crashed' })
+    return
+  }
+  turns += 1
+  const operationId = 'op-' + turns
+  const event = (value) =>
+    send({ type: 'harness.event', cursor: String(turns), operationId, event: { timestamp: 1, ...value } })
+  // One event arrives before the receipt, one belongs to another operation.
+  event({ type: 'TEXT_MESSAGE_START', messageId: 'm' + turns, role: 'assistant' })
+  send({ type: 'harness.event', cursor: 'x', operationId: 'other', event: { type: 'TEXT_MESSAGE_CONTENT', messageId: 'x', delta: 'ignored', timestamp: 1 } })
+  send({ type: 'harness.receipt', requestId: frame.requestId, status: 'accepted', operationId })
+  process.stdout.write('a stray log line\\n')
+  if (message === 'fail') {
+    event({ type: 'RUN_ERROR', message: 'turn failed' })
+    return
+  }
+  send({ type: 'harness.event', cursor: 'y', operationId: 'other', event: { type: 'TEXT_MESSAGE_CONTENT', messageId: 'x', delta: 'ignored', timestamp: 1 } })
+  event({ type: 'TOOL_CALL_START', toolCallId: 't', toolCallName: 'hidden' })
+  event({ type: 'TEXT_MESSAGE_CONTENT', messageId: 'm' + turns, delta: 'turn ' + turns + ': ' + message })
+  event({ type: 'TEXT_MESSAGE_CONTENT', messageId: 'c', delta: ' (child)', subagentRunId: 'child-1' })
+  event({ type: 'TEXT_MESSAGE_END', messageId: 'm' + turns })
+  event({ type: 'CUSTOM', name: 'harness.operation.finished', value: {} })
+})
+`
+
+const fakeBun = `
+import { copyFileSync, writeFileSync } from 'node:fs'
+const args = process.argv.slice(2)
+const outfile = args.find((arg) => arg.startsWith('--outfile='))?.slice('--outfile='.length)
+if (process.cwd().endsWith('broken')) {
+  process.stderr.write('bundle exploded')
+  process.exit(1)
+}
+if (args[0] === 'build' && args.includes('--compile')) {
+  writeFileSync(outfile, 'executable for ' + (args.find((arg) => arg.startsWith('--target=')) ?? 'this machine'))
+} else if (args[0] === 'build') {
+  copyFileSync(new URL('./stub-worker.mjs', import.meta.url), outfile)
+} else {
+  console.log('noise from the entry module')
+  console.log(JSON.stringify({
+    name: 'acme/stub',
+    agents: [{ name: 'painter', produces: 'image' }],
+    plugins: [{ name: 'tanstack/workspace-tools' }, { name: 'connector/notion' }],
+  }))
+}
+`
+
+let bun: string
+
+beforeAll(async () => {
+  await mkdir(app, { recursive: true })
+  await mkdir(broken, { recursive: true })
+  await writeFile(entry, 'export default {}\n')
+  await writeFile(join(broken, 'studio.ts'), 'export default {}\n')
+  await writeFile(join(tmp, 'stub-worker.mjs'), stubWorker)
+  await writeFile(join(tmp, 'fake-bun.mjs'), fakeBun)
+  if (process.platform === 'win32') {
+    bun = join(tmp, 'fake-bun.cmd')
+    await writeFile(bun, `@"${process.execPath}" "%~dp0fake-bun.mjs" %*\r\n`)
+  } else {
+    bun = join(tmp, 'fake-bun')
+    await writeFile(
+      bun,
+      `#!/bin/sh\nexec "${process.execPath}" "$(dirname "$0")/fake-bun.mjs" "$@"\n`,
+    )
+    await chmod(bun, 0o755)
+  }
+})
+
+afterAll(async () => {
+  await rm(tmp, { recursive: true, force: true })
+})
+
+async function textOf(stream: AsyncIterable<StreamChunk>): Promise<string> {
+  let out = ''
+  for await (const chunk of stream) {
+    if (chunk.type === EventType.TEXT_MESSAGE_CONTENT) out += chunk.delta
+  }
+  return out
+}
+
+describe('buildHarness with a stand-in bundler', () => {
+  it('writes a manifest from what the entry describes, then cleans up', async () => {
+    const outDir = join(tmp, 'out')
+    const { manifest, bundle, executable } = await buildHarness({
+      entry,
+      outDir,
+      bun,
+    })
+
+    const bytes = await readFile(bundle)
+    expect(manifest).toMatchObject({
+      format: 'tanstack-ai-harness',
+      version: 1,
+      name: 'acme/stub',
+      entry: 'harness.js',
+      digest: createHash('sha256').update(bytes).digest('hex'),
+      runtime: { kind: 'node' },
+      agents: [{ name: 'painter', produces: 'image' }],
+      plugins: [
+        { name: 'tanstack/workspace-tools' },
+        { name: 'connector/notion' },
+      ],
+      requires: {
+        filesystem: true,
+        processExecution: true,
+        network: 'declared',
+      },
+    })
+    expect(executable).toBeUndefined()
+    expect(await readManifest(outDir)).toEqual(manifest)
+    // The temporary bootstrap and describe modules are gone.
+    expect(
+      (await readdir(app)).filter((name) => name.startsWith('.harness-')),
+    ).toEqual([])
+  })
+
+  it('also compiles an executable when asked', async () => {
+    const outfile = join(tmp, 'studio-bin')
+    const { executable } = await buildHarness({
+      entry,
+      export: 'studio',
+      outDir: join(tmp, 'out-compiled'),
+      bun,
+      compile: { entry, outfile, target: 'bun-linux-x64' },
+    })
+    expect(executable).toBe(outfile)
+    expect(await readFile(outfile, 'utf8')).toBe(
+      'executable for --target=bun-linux-x64',
+    )
+
+    await buildHarness({
+      entry,
+      outDir: join(tmp, 'out-compiled-default'),
+      bun,
+      compile: { entry, outfile },
+    })
+    expect(await readFile(outfile, 'utf8')).toBe('executable for this machine')
+  })
+
+  it('reports a failed bundle with its output and still cleans up', async () => {
+    await expect(
+      buildHarness({
+        entry: join(broken, 'studio.ts'),
+        outDir: join(tmp, 'out-broken'),
+        bun,
+      }),
+    ).rejects.toThrow('bundle exploded')
+    expect(
+      (await readdir(broken)).filter((name) => name.startsWith('.harness-')),
+    ).toEqual([])
+  })
+
+  it('says to install Bun when the command cannot start', async () => {
+    // On Windows the command runs through a shell, which reports the missing
+    // command as a failed run instead of a spawn error.
+    await expect(
+      buildHarness({
+        entry,
+        outDir: join(tmp, 'out-missing'),
+        bun: join(tmp, 'no-such-bun.exe'),
+      }),
+    ).rejects.toThrow(/Could not run|failed/)
+  })
+})
+
+describe('readManifest', () => {
+  it('refuses a directory whose manifest is not a harness manifest', async () => {
+    const dir = join(tmp, 'not-a-harness')
+    await mkdir(dir, { recursive: true })
+    for (const manifest of [
+      null,
+      'text',
+      { format: 'other' },
+      { format: 'tanstack-ai-harness', version: 2 },
+    ]) {
+      await writeFile(
+        join(dir, 'harness.manifest.json'),
+        JSON.stringify(manifest),
+      )
+      await expect(readManifest(dir)).rejects.toThrow(
+        'has no tanstack-ai-harness v1 manifest',
+      )
+    }
+  })
+})
+
+describe('artifactText with a built stub', () => {
+  it('streams the worker text for each turn and keeps one worker per thread', async () => {
+    const outDir = join(tmp, 'out-chat')
+    await buildHarness({ entry, outDir, bun })
+    const model = await artifactText(outDir)
+    try {
+      expect(model.model).toBe('acme/stub')
+      const ask = (content: string, threadId: string) =>
+        textOf(
+          chat({
+            adapter: model,
+            messages: [
+              { role: 'assistant', content: 'earlier' },
+              { role: 'user', content },
+            ],
+            threadId,
+          }) as AsyncIterable<StreamChunk>,
+        )
+      expect(await ask('hello', 'a')).toBe('turn 1: hello')
+      expect(await ask('again', 'a')).toBe('turn 2: again')
+      // Another thread starts its own worker, so it counts from one.
+      expect(await ask('fresh', 'b')).toBe('turn 1: fresh')
+      await expect(model.structuredOutput({} as never)).rejects.toThrow(
+        'does not support structured output',
+      )
+    } finally {
+      model.dispose()
+    }
+  })
+
+  it('turns worker refusals and errors into errors', async () => {
+    const outDir = join(tmp, 'out-errors')
+    await buildHarness({ entry, outDir, bun })
+    const model = await artifactText(outDir, { node: process.execPath })
+    const stream = (content: unknown) =>
+      model.chatStream({
+        model: 'acme/stub',
+        messages: [{ role: 'user', content }],
+        threadId: 'errors',
+      } as never)
+    const drain = async (content: unknown) => {
+      for await (const _chunk of stream(content)) {
+        // Only the error matters.
+      }
+    }
+    try {
+      await expect(drain('reject')).rejects.toThrow('busy')
+      await expect(drain('reject quietly')).rejects.toThrow(
+        'The worker refused the prompt.',
+      )
+      await expect(drain('crash')).rejects.toThrow('worker crashed')
+      await expect(drain('fail')).rejects.toThrow('turn failed')
+      // A message without text content is sent as an empty prompt.
+      let text = ''
+      for await (const chunk of stream([{ type: 'text', content: 'x' }])) {
+        if (chunk.type === EventType.TEXT_MESSAGE_CONTENT) text += chunk.delta
+      }
+      expect(text).toBe('turn 2: ')
+    } finally {
+      model.dispose()
+    }
+  })
+
+  it('refuses a bundle that does not match its manifest', async () => {
+    const outDir = join(tmp, 'out-tampered')
+    await buildHarness({ entry, outDir, bun })
+    await writeFile(join(outDir, 'harness.js'), '// changed\n')
+    await expect(artifactText(outDir)).rejects.toThrow(
+      'does not match its manifest digest',
+    )
+  })
+})
diff --git a/packages/ai-harness/tests/build.test.ts b/packages/ai-harness/tests/build.test.ts
index 90cd18fbd8..748e14b619 100644
--- a/packages/ai-harness/tests/build.test.ts
+++ b/packages/ai-harness/tests/build.test.ts
@@ -1,3 +1,4 @@
+import { spawnSync } from 'node:child_process'
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { PassThrough } from 'node:stream'
 import { fileURLToPath } from 'node:url'
@@ -94,8 +95,12 @@ describe('harnessText({ url })', () => {
 })
 
 const tmp = fileURLToPath(new URL('./.tmp-build/', import.meta.url))
+// A real build needs Bun. build-stub.test.ts covers the rest without it.
+const hasBun =
+  spawnSync('bun', ['--version'], { shell: process.platform === 'win32' })
+    .status === 0
 
-describe('buildHarness and artifactText', () => {
+describe.skipIf(!hasBun)('buildHarness and artifactText', () => {
   afterAll(async () => {
     await rm(tmp, { recursive: true, force: true })
   })

From 0a8be1078978461d2d1facca8de4344f3a6c4f03 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 15:03:46 +0200
Subject: [PATCH 017/286] fix(ai-harness): read AG-UI text parts in /run
 prompts; cover protocol, client, resume, and ACP edges

---
 packages/ai-acp/tests/agent-handlers.test.ts  | 392 ++++++++++++
 packages/ai-harness/src/http.ts               |   7 +-
 .../ai-harness/tests/resume-edges.test.ts     | 279 ++++++++
 .../ai-harness/tests/transport-edges.test.ts  | 596 ++++++++++++++++++
 4 files changed, 1271 insertions(+), 3 deletions(-)
 create mode 100644 packages/ai-acp/tests/agent-handlers.test.ts
 create mode 100644 packages/ai-harness/tests/resume-edges.test.ts
 create mode 100644 packages/ai-harness/tests/transport-edges.test.ts

diff --git a/packages/ai-acp/tests/agent-handlers.test.ts b/packages/ai-acp/tests/agent-handlers.test.ts
new file mode 100644
index 0000000000..817c5bc7b1
--- /dev/null
+++ b/packages/ai-acp/tests/agent-handlers.test.ts
@@ -0,0 +1,392 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { EventType, toolDefinition } from '@tanstack/ai'
+import { client, ndJsonStream } from '@agentclientprotocol/sdk/experimental/v2'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { createAcpAgent, serveAcp, toSessionUpdate } from '../src/agent'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import type {
+  ClientApp,
+  SessionUpdate,
+} from '@agentclientprotocol/sdk/experimental/v2'
+
+const now = () => Date.now()
+
+/**
+ * A model that answers from the last user message: `wait` waits until the
+ * turn is cancelled, `remove` calls the remove tool, anything else echoes.
+ */
+function model(): AnyTextAdapter {
+  return {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    '~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: any) =>
+      (async function* (): AsyncGenerator<StreamChunk> {
+        const last = options.messages.at(-1)
+        const said = typeof last?.content === 'string' ? last.content : ''
+        yield {
+          type: EventType.RUN_STARTED,
+          runId: 'r',
+          threadId: 't',
+          timestamp: now(),
+        }
+        if (said === 'wait') {
+          const signal: AbortSignal | undefined =
+            options.abortController?.signal ?? options.request?.signal
+          await new Promise<void>((resolve) => {
+            if (!signal || signal.aborted) return resolve()
+            signal.addEventListener('abort', () => resolve(), { once: true })
+          })
+          return
+        }
+        if (said.startsWith('remove')) {
+          yield {
+            type: EventType.TOOL_CALL_START,
+            toolCallId: 'call_1',
+            toolCallName: 'remove',
+            timestamp: now(),
+          }
+          yield {
+            type: EventType.TOOL_CALL_ARGS,
+            toolCallId: 'call_1',
+            delta: '{"path":"a.txt"}',
+            timestamp: now(),
+          }
+          yield {
+            type: EventType.TOOL_CALL_END,
+            toolCallId: 'call_1',
+            timestamp: now(),
+          }
+          yield {
+            type: EventType.RUN_FINISHED,
+            runId: 'r',
+            threadId: 't',
+            timestamp: now(),
+            metadata: { tanstack: { finishReason: 'tool_calls' } },
+          }
+          return
+        }
+        const reply = last?.role === 'tool' ? 'Kept a.txt.' : `echo: ${said}`
+        yield {
+          type: EventType.TEXT_MESSAGE_START,
+          messageId: 'm',
+          role: 'assistant',
+          timestamp: now(),
+        }
+        yield {
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          messageId: 'm',
+          delta: reply,
+          timestamp: now(),
+        }
+        yield {
+          type: EventType.TEXT_MESSAGE_END,
+          messageId: 'm',
+          timestamp: now(),
+        }
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId: 'r',
+          threadId: 't',
+          timestamp: now(),
+          metadata: { tanstack: { finishReason: 'stop' } },
+        }
+      })(),
+  }
+}
+
+function setup() {
+  const remove = vi.fn(async () => ({ removed: true }))
+  const harness = defineHarness({
+    name: 'test/acp-handlers',
+    adapter: model(),
+    tools: [
+      toolDefinition({
+        name: 'remove',
+        description: 'Remove a file',
+        needsApproval: true,
+        inputSchema: {
+          type: 'object',
+          properties: { path: { type: 'string' } },
+          required: ['path'],
+        },
+      }).server(remove),
+    ],
+  })
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const updates: Array<{ sessionId: string; update: SessionUpdate }> = []
+  const permissions: Array<{ title: string; toolCallId: string }> = []
+  const editor: ClientApp = client()
+    .onNotification('session/update', ({ params }) => {
+      updates.push({ sessionId: params.sessionId, update: params.update })
+    })
+    .onRequest('session/request_permission', ({ params }) => {
+      permissions.push({
+        title: params.title,
+        // The subject names the tool call: `{ type, toolCall: { toolCallId } }`.
+        toolCallId: JSON.stringify(params.subject ?? null).includes('call_1')
+          ? 'call_1'
+          : '',
+      })
+      return { outcome: { outcome: 'selected', optionId: 'reject' } }
+    })
+  const idle = (sessionId: string) =>
+    updates.find(
+      (entry) =>
+        entry.sessionId === sessionId &&
+        entry.update.sessionUpdate === 'state_update' &&
+        entry.update.state === 'idle',
+    )?.update
+  const textOf = (sessionId: string) =>
+    updates
+      .filter((entry) => entry.sessionId === sessionId)
+      .map((entry) => {
+        if (entry.update.sessionUpdate !== 'agent_message_chunk') return ''
+        const content: unknown = entry.update.content
+        return typeof content === 'object' &&
+          content !== null &&
+          'text' in content &&
+          typeof content.text === 'string'
+          ? content.text
+          : ''
+      })
+      .join('')
+  const running = (sessionId: string) =>
+    updates.some(
+      (entry) =>
+        entry.sessionId === sessionId &&
+        entry.update.sessionUpdate === 'state_update' &&
+        entry.update.state === 'running',
+    )
+  return {
+    harness,
+    host,
+    editor,
+    updates,
+    permissions,
+    remove,
+    idle,
+    running,
+    textOf,
+  }
+}
+
+describe('toSessionUpdate', () => {
+  it('maps reasoning and tool results, and skips child and unknown events', () => {
+    expect(
+      toSessionUpdate({
+        type: EventType.REASONING_MESSAGE_CONTENT,
+        messageId: 'r1',
+        delta: 'thinking',
+        timestamp: 1,
+      }),
+    ).toEqual({
+      sessionUpdate: 'agent_thought_chunk',
+      messageId: 'r1',
+      content: { type: 'text', text: 'thinking' },
+    })
+    expect(
+      toSessionUpdate({
+        type: EventType.TOOL_CALL_RESULT,
+        messageId: 'm',
+        toolCallId: 'call_9',
+        content: 'done',
+        timestamp: 1,
+      }),
+    ).toEqual({
+      sessionUpdate: 'tool_call_update',
+      toolCallId: 'call_9',
+      status: 'completed',
+    })
+    expect(
+      toSessionUpdate({
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'm',
+        delta: 'from a child',
+        subagentRunId: 'child-1',
+        timestamp: 1,
+      } as StreamChunk),
+    ).toBeUndefined()
+    expect(
+      toSessionUpdate({
+        type: EventType.RUN_STARTED,
+        runId: 'r',
+        threadId: 't',
+        timestamp: 1,
+      }),
+    ).toBeUndefined()
+  })
+})
+
+describe('ACP agent handlers', () => {
+  let close: (() => Promise<void>) | undefined
+  afterEach(async () => {
+    await close?.()
+    close = undefined
+  })
+
+  it('keeps the tool from running when the editor rejects it', async () => {
+    const { harness, host, editor, permissions, remove, idle, textOf } = setup()
+    close = () => host.close()
+    await editor.connectWith(createAcpAgent({ host, harness }), async (ctx) => {
+      const init = await ctx.request('initialize', {
+        protocolVersion: 2,
+        info: { name: 'editor', version: '1.0.0' },
+      })
+      expect(init.info.version).toBe('0.0.0')
+      const { sessionId } = await ctx.request('session/new', {
+        cwd: '/tmp',
+        mcpServers: [],
+      })
+      await ctx.request('session/prompt', {
+        sessionId,
+        prompt: [
+          { type: 'image', data: 'AA==', mimeType: 'image/png' },
+          { type: 'text', text: 'remove a.txt' },
+        ],
+      })
+      await vi.waitFor(() => expect(idle(sessionId)).toBeDefined())
+      expect(idle(sessionId)).toMatchObject({ stopReason: 'end_turn' })
+      expect(textOf(sessionId)).toBe('Kept a.txt.')
+    })
+    expect(remove).not.toHaveBeenCalled()
+    expect(permissions).toEqual([
+      { title: expect.any(String), toolCallId: 'call_1' },
+    ])
+  })
+
+  it('resumes a session by id, cancels a running turn, and closes it', async () => {
+    const { harness, host, editor, idle, running, textOf } = setup()
+    close = () => host.close()
+    await editor.connectWith(createAcpAgent({ host, harness }), async (ctx) => {
+      await ctx.request('initialize', {
+        protocolVersion: 2,
+        info: { name: 'editor', version: '1.0.0' },
+      })
+      await ctx.request('session/resume', {
+        sessionId: 'kept-session',
+        cwd: '/tmp',
+      })
+      await ctx.request('session/prompt', {
+        sessionId: 'kept-session',
+        prompt: [{ type: 'text', text: 'hello' }],
+      })
+      await vi.waitFor(() => expect(idle('kept-session')).toBeDefined())
+      expect(textOf('kept-session')).toBe('echo: hello')
+
+      await ctx.request('session/prompt', {
+        sessionId: 'slow-session',
+        prompt: [{ type: 'text', text: 'wait' }],
+      })
+      await vi.waitFor(() => expect(running('slow-session')).toBe(true))
+      await ctx.notify('session/cancel', { sessionId: 'slow-session' })
+      await vi.waitFor(() => expect(idle('slow-session')).toBeDefined())
+      expect(idle('slow-session')).toMatchObject({ stopReason: 'cancelled' })
+
+      await ctx.request('session/close', { sessionId: 'kept-session' })
+      // Closing an unknown session and cancelling one are both quiet.
+      await ctx.request('session/close', { sessionId: 'never-opened' })
+      await ctx.notify('session/cancel', { sessionId: 'never-opened' })
+    })
+  })
+})
+
+describe('serveAcp', () => {
+  it('serves the agent over a stream', async () => {
+    const { harness, host, editor, idle, textOf } = setup()
+    const toClient = new TransformStream<Uint8Array, Uint8Array>()
+    const toAgent = new TransformStream<Uint8Array, Uint8Array>()
+    const connection = serveAcp({
+      host,
+      harness,
+      version: '2.0.0',
+      stream: ndJsonStream(toClient.writable, toAgent.readable),
+    })
+    await editor.connectWith(
+      ndJsonStream(toAgent.writable, toClient.readable),
+      async (ctx) => {
+        const init = await ctx.request('initialize', {
+          protocolVersion: 2,
+          info: { name: 'editor', version: '1.0.0' },
+        })
+        expect(init.info).toEqual({
+          name: 'test/acp-handlers',
+          version: '2.0.0',
+        })
+        const { sessionId } = await ctx.request('session/new', {
+          cwd: '/tmp',
+          mcpServers: [],
+        })
+        await ctx.request('session/prompt', {
+          sessionId,
+          prompt: [{ type: 'text', text: 'over a stream' }],
+        })
+        await vi.waitFor(() => expect(idle(sessionId)).toBeDefined())
+        expect(textOf(sessionId)).toBe('echo: over a stream')
+      },
+    )
+    connection.close()
+    await host.close()
+  })
+
+  it('uses stdin and stdout when no stream is given', async () => {
+    const { harness, host } = setup()
+    const listeners = new Map<string, (data?: Uint8Array) => void>()
+    const on = vi
+      .spyOn(process.stdin, 'on')
+      .mockImplementation((event: string | symbol, listener: any) => {
+        listeners.set(String(event), listener)
+        return process.stdin
+      })
+    const written: Array<string> = []
+    const write = vi
+      .spyOn(process.stdout, 'write')
+      .mockImplementation((chunk: any, callback?: any) => {
+        written.push(Buffer.from(chunk).toString())
+        if (typeof callback === 'function') callback()
+        return true
+      })
+    try {
+      const connection = serveAcp({ host, harness })
+      await vi.waitFor(() => expect(listeners.has('data')).toBe(true))
+      listeners.get('data')?.(
+        new TextEncoder().encode(
+          `${JSON.stringify({
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: {
+              protocolVersion: 2,
+              info: { name: 'editor', version: '1.0.0' },
+            },
+          })}\n`,
+        ),
+      )
+      await vi.waitFor(() =>
+        expect(written.join('')).toContain('test/acp-handlers'),
+      )
+      listeners.get('end')?.()
+      connection.close()
+    } finally {
+      on.mockRestore()
+      write.mockRestore()
+      await host.close()
+    }
+  })
+})
diff --git a/packages/ai-harness/src/http.ts b/packages/ai-harness/src/http.ts
index e9be9a5e24..3f222d5425 100644
--- a/packages/ai-harness/src/http.ts
+++ b/packages/ai-harness/src/http.ts
@@ -54,11 +54,12 @@ function lastUserText(messages: ReadonlyArray<unknown>): string | undefined {
   )
   if (!isRecord(message)) return undefined
   if (typeof message.content === 'string') return message.content
-  const parts = Array.isArray(message.parts) ? message.parts : []
+  // AG-UI content parts: `{ type: 'text', text }` and binary parts.
+  const parts = Array.isArray(message.content) ? message.content : []
   return parts
     .map((part: unknown) =>
-      isRecord(part) && part.type === 'text' && typeof part.content === 'string'
-        ? part.content
+      isRecord(part) && part.type === 'text' && typeof part.text === 'string'
+        ? part.text
         : '',
     )
     .join('')
diff --git a/packages/ai-harness/tests/resume-edges.test.ts b/packages/ai-harness/tests/resume-edges.test.ts
new file mode 100644
index 0000000000..7c9367ec33
--- /dev/null
+++ b/packages/ai-harness/tests/resume-edges.test.ts
@@ -0,0 +1,279 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { EventType, chat, defineAgent } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness, harnessText } from '../src'
+import {
+  INTERRUPTED_TOOL_RESULT,
+  findCrashedRuns,
+  repairTranscript,
+} from '../src/resume'
+import { messageTexts, mockAdapter, text, untilAborted } from './helpers'
+import type { RunRecord, StreamChunk } from '@tanstack/ai'
+import type { HarnessPersistence } from '../src/host'
+
+async function crash(
+  persistence: ReturnType<typeof memoryPersistence>,
+  runId: string,
+  startedAt: number,
+  pendingTools: NonNullable<RunRecord['checkpoint']>['pendingTools'] = [],
+) {
+  await persistence.stores.runs.createOrResume({
+    runId,
+    threadId: 't1',
+    startedAt,
+  })
+  await persistence.stores.runs.update(runId, {
+    leaseOwner: 'host-gone',
+    leaseExpiresAt: Date.now() - 1_000,
+    checkpoint: { at: startedAt, pendingTools },
+  })
+}
+
+describe('crash recovery edges', () => {
+  it('finds nothing when the run store cannot list a thread', async () => {
+    const noRuns = { stores: {} } as unknown as HarnessPersistence
+    expect(await findCrashedRuns(noRuns, 't1')).toEqual([])
+    const noList = {
+      stores: { runs: { get: async () => null } },
+    } as unknown as HarnessPersistence
+    expect(await findCrashedRuns(noList, 't1')).toEqual([])
+  })
+
+  it('continues only the newest crashed turn and fails the older ones', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.messages.saveThread('t1', [
+      { id: 'u1', role: 'user', content: 'hello' },
+    ])
+    await crash(persistence, 'old-run', Date.now() - 120_000)
+    await crash(persistence, 'new-run', Date.now() - 60_000)
+    const { adapter, calls } = mockAdapter([() => text('picked up')])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({ name: 'test/two-crashes', adapter }),
+      { threadId: 't1' },
+    )
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    await vi.waitFor(() => expect(session.snapshot().status).toBe('idle'))
+
+    expect(await persistence.stores.runs.get('old-run')).toMatchObject({
+      status: 'failed',
+      error: { message: 'The host stopped during this turn.' },
+    })
+    expect(await persistence.stores.runs.get('new-run')).toMatchObject({
+      status: 'failed',
+      error: {
+        message:
+          'The host stopped. The session continued this turn in a new run.',
+      },
+    })
+    await host.close()
+  })
+
+  it('leaves the transcript alone when no tool needs a note', async () => {
+    const persistence = memoryPersistence()
+    const history = [
+      { id: 'u1', role: 'user' as const, content: 'go' },
+      {
+        id: 'a1',
+        role: 'assistant' as const,
+        content: '',
+        toolCalls: [
+          {
+            id: 'call-a',
+            type: 'function' as const,
+            function: { name: 'charge', arguments: '{}' },
+          },
+        ],
+      },
+      {
+        id: 't1',
+        role: 'tool' as const,
+        toolCallId: 'call-a',
+        content: 'done',
+      },
+    ]
+    await persistence.stores.messages.saveThread('t1', history)
+    const save = vi.spyOn(persistence.stores.messages, 'saveThread')
+
+    // Only safe tools pending: nothing to note.
+    await repairTranscript(persistence, {
+      runId: 'r',
+      threadId: 't1',
+      status: 'running',
+      startedAt: 1,
+      checkpoint: {
+        at: 1,
+        pendingTools: [
+          { toolCallId: 'call-b', name: 'lookup', replay: 'safe' },
+        ],
+      },
+    })
+    // A never-replay tool that already has a result: nothing to note.
+    await repairTranscript(persistence, {
+      runId: 'r',
+      threadId: 't1',
+      status: 'running',
+      startedAt: 1,
+      checkpoint: {
+        at: 1,
+        pendingTools: [
+          { toolCallId: 'call-a', name: 'charge', replay: 'never' },
+        ],
+      },
+    })
+    // No checkpoint at all.
+    await repairTranscript(persistence, {
+      runId: 'r',
+      threadId: 't1',
+      status: 'running',
+      startedAt: 1,
+    })
+    expect(save).not.toHaveBeenCalled()
+    expect(
+      JSON.stringify(await persistence.stores.messages.loadThread('t1')),
+    ).not.toContain(JSON.stringify(INTERRUPTED_TOOL_RESULT))
+  })
+
+  it('releases the lease timer when a turn fails', async () => {
+    const persistence = memoryPersistence()
+    const { adapter } = mockAdapter([
+      () =>
+        (async function* (): AsyncGenerator<StreamChunk> {
+          yield {
+            type: EventType.RUN_STARTED,
+            runId: 'r',
+            threadId: 't',
+            timestamp: Date.now(),
+          }
+          throw new Error('model down')
+        })(),
+    ])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({ name: 'test/fails', adapter }),
+      { threadId: 't-fail' },
+    )
+    const turn = session.prompt('hi')
+    await expect(turn).rejects.toThrow('model down')
+    expect(turn.status()).toBe('failed')
+    await host.close()
+  })
+})
+
+describe('harnessText edges', () => {
+  it('uses a memory host by default and reads text content parts', async () => {
+    const inner = mockAdapter([() => text('parts answer'), () => text('empty')])
+    const studio = defineHarness({ name: 'test/parts', adapter: inner.adapter })
+    const model = harnessText(studio)
+    const collect = async (messages: Array<any>) => {
+      let out = ''
+      for await (const chunk of chat({ adapter: model, messages })) {
+        if (chunk.type === EventType.TEXT_MESSAGE_CONTENT) out += chunk.delta
+      }
+      return out
+    }
+    expect(
+      await collect([
+        {
+          role: 'user',
+          content: [
+            { type: 'text', content: 'one ' },
+            {
+              type: 'image',
+              source: { type: 'url', value: 'https://x/y.png' },
+            },
+            { type: 'text', content: 'two' },
+          ],
+        },
+      ]),
+    ).toBe('parts answer')
+    expect(messageTexts(inner.calls[0])).toEqual(['one two'])
+    await expect(model.structuredOutput({} as never)).rejects.toThrow(
+      'does not support structured output',
+    )
+  })
+
+  it('reports an inner failure as a run error', async () => {
+    const inner = mockAdapter([
+      () =>
+        (async function* (): AsyncGenerator<StreamChunk> {
+          yield {
+            type: EventType.RUN_STARTED,
+            runId: 'r',
+            threadId: 't',
+            timestamp: Date.now(),
+          }
+          throw new Error('inner broke')
+        })(),
+    ])
+    const studio = defineHarness({
+      name: 'test/inner-fail',
+      adapter: inner.adapter,
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const chunks: Array<StreamChunk> = []
+    for await (const chunk of harnessText(studio, { host }).chatStream({
+      model: 'test/inner-fail',
+      messages: [{ role: 'assistant', content: 'no user message here' }],
+    } as never)) {
+      chunks.push(chunk)
+    }
+    expect(chunks.at(-1)).toMatchObject({
+      type: EventType.RUN_ERROR,
+      message: 'inner broke',
+    })
+    await host.close()
+  })
+
+  it('cancels the inner turn when the outer request aborts', async () => {
+    const inner = mockAdapter([untilAborted()])
+    const studio = defineHarness({
+      name: 'test/inner-abort',
+      adapter: inner.adapter,
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const controller = new AbortController()
+    const stream = harnessText(studio, { host }).chatStream({
+      model: 'test/inner-abort',
+      threadId: 'outer',
+      messages: [{ role: 'user', content: 'wait' }],
+      request: { signal: controller.signal },
+    } as never)
+    const first = await stream[Symbol.asyncIterator]().next()
+    expect(first.value).toMatchObject({ type: EventType.RUN_STARTED })
+    await vi.waitFor(() => expect(inner.calls).toHaveLength(1))
+    controller.abort()
+    for await (const _chunk of stream) {
+      // Drains until the cancelled inner turn ends.
+    }
+    await host.close()
+  })
+})
+
+describe('session agent and operation lookups', () => {
+  it('finds agents and operations by name and id', async () => {
+    const echo = defineAgent({
+      name: 'echo',
+      description: 'Echoes',
+      inputSchema: z.object({ text: z.string() }),
+      run: async (ctx) => ctx.input.text.toUpperCase(),
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/lookups',
+        adapter: mockAdapter([]).adapter,
+        agents: [echo],
+      }),
+      { threadId: 't' },
+    )
+    expect(session.agent('missing')).toBeUndefined()
+    const handle = session.agent('echo')
+    const run = handle?.run({ text: 'hi' })
+    expect(await run).toBe('HI')
+    expect(session.operation(run?.id ?? '')).toBe(run)
+    expect(session.operation('nope')).toBeUndefined()
+    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..95c842698b
--- /dev/null
+++ b/packages/ai-harness/tests/transport-edges.test.ts
@@ -0,0 +1,596 @@
+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(404)
+
+    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)
+
+    const resumed = await call('run', {
+      method: 'POST',
+      body: runBody('user-1-resume', {
+        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' },
+    })
+    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' },
+    })
+    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('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' } })
+    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()
+  })
+})

From 37c04d30dc0bb020e6d3abddbaa10fde88299c8d Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 15:08:34 +0200
Subject: [PATCH 018/286] feat(ai-mcp, ai-harness): MCP connectors with browser
 sign-in, run-time tool discovery, and media in the example

---
 .changeset/harness-p7-connectors.md           |  11 +
 docs/config.json                              |   5 +
 docs/harness/dashboard.md                     |   2 +-
 docs/harness/deploy.md                        |   2 +-
 docs/harness/mcp.md                           | 121 ++++++
 docs/harness/subagents.md                     |   2 +-
 examples/harness-cli/.env.example             |   7 +
 examples/harness-cli/.gitignore               |   2 +
 examples/harness-cli/README.md                |  13 +-
 examples/harness-cli/package.json             |   4 +-
 examples/harness-cli/src/cli.ts               |   9 +-
 examples/harness-cli/src/credentials.ts       |  53 +++
 examples/harness-cli/src/harness.ts           |  37 +-
 examples/harness-cli/src/media.ts             |  90 +++++
 packages/ai-harness/src/define.ts             |   1 +
 packages/ai-harness/src/index.ts              |   1 +
 packages/ai-harness/src/oauth.ts              |  62 +++
 packages/ai-harness/src/plugins.ts            |  18 +
 packages/ai-harness/src/session.ts            |  54 ++-
 .../ai-harness/tests/discover-tools.test.ts   | 165 ++++++++
 packages/ai-mcp/package.json                  |  14 +
 packages/ai-mcp/src/connector.ts              | 291 ++++++++++++++
 packages/ai-mcp/tests/connector.test.ts       | 361 ++++++++++++++++++
 packages/ai-mcp/vite.config.ts                |   7 +-
 packages/ai-persistence/src/types.ts          |   5 +
 pnpm-lock.yaml                                |  12 +
 26 files changed, 1332 insertions(+), 17 deletions(-)
 create mode 100644 .changeset/harness-p7-connectors.md
 create mode 100644 docs/harness/mcp.md
 create mode 100644 examples/harness-cli/.env.example
 create mode 100644 examples/harness-cli/.gitignore
 create mode 100644 examples/harness-cli/src/credentials.ts
 create mode 100644 examples/harness-cli/src/media.ts
 create mode 100644 packages/ai-harness/tests/discover-tools.test.ts
 create mode 100644 packages/ai-mcp/src/connector.ts
 create mode 100644 packages/ai-mcp/tests/connector.test.ts

diff --git a/.changeset/harness-p7-connectors.md b/.changeset/harness-p7-connectors.md
new file mode 100644
index 0000000000..17ea459419
--- /dev/null
+++ b/.changeset/harness-p7-connectors.md
@@ -0,0 +1,11 @@
+---
+'@tanstack/ai-mcp': minor
+'@tanstack/ai-harness': minor
+'@tanstack/ai-persistence': minor
+---
+
+`@tanstack/ai-mcp/connector` adds `mcpConnector`: a harness plugin that signs the user in to a remote MCP server (Notion, Linear, and others) with OAuth, then gives the model the server's tools. `/connect <id>` registers a client, signs in with PKCE on a `127.0.0.1` loopback, and keeps the token in the credential store. Tools the server does not mark read-only ask for approval.
+
+`@tanstack/ai-harness` adds `discoverTools` to plugins, for tools found at run time, and `startLoopbackReceiver` for OAuth redirects. A harness turn now runs up to 50 model calls by default (`agentLoopStrategy` still overrides it).
+
+`@tanstack/ai-persistence`: an `oauth` credential can keep the OAuth `client` it was issued to.
diff --git a/docs/config.json b/docs/config.json
index 9ac515446a..8b9dea312f 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -839,6 +839,11 @@
           "to": "harness/auth",
           "addedAt": "2026-09-26"
         },
+        {
+          "label": "Use MCP servers",
+          "to": "harness/mcp",
+          "addedAt": "2026-09-26"
+        },
         {
           "label": "Run agents from a harness",
           "to": "harness/subagents",
diff --git a/docs/harness/dashboard.md b/docs/harness/dashboard.md
index 8bc06bcd83..3fab5e3e0a 100644
--- a/docs/harness/dashboard.md
+++ b/docs/harness/dashboard.md
@@ -1,7 +1,7 @@
 ---
 title: Self-host the dashboard
 id: harness-dashboard
-order: 10
+order: 11
 description: "Watch and steer your harness sessions from a browser or a phone. Agents dial out to your dashboard server, so they need no open port."
 keywords:
   - tanstack ai
diff --git a/docs/harness/deploy.md b/docs/harness/deploy.md
index d6d22b92db..e75187f2a4 100644
--- a/docs/harness/deploy.md
+++ b/docs/harness/deploy.md
@@ -1,7 +1,7 @@
 ---
 title: Deploy a harness
 id: harness-deploy
-order: 9
+order: 10
 description: "Run a harness in your server, as a worker process, on another machine, or as a single executable."
 keywords:
   - tanstack ai
diff --git a/docs/harness/mcp.md b/docs/harness/mcp.md
new file mode 100644
index 0000000000..52dff3f012
--- /dev/null
+++ b/docs/harness/mcp.md
@@ -0,0 +1,121 @@
+---
+title: Use MCP servers
+id: harness-mcp
+order: 8
+description: "Connect a harness to Notion, Linear, or another MCP server that signs in with OAuth. The user signs in once in the browser, and the tools appear after sign-in."
+keywords:
+  - tanstack ai
+  - harness
+  - mcp
+  - connectors
+  - oauth
+  - notion
+  - linear
+---
+
+Your agent needs to read the user's Linear issues and Notion pages. Both services run MCP servers that sign in with OAuth, so you do not register an app or copy an API key. `mcpConnector` adds `/connect linear`, keeps the token in your credential store, and gives the model the server's tools after sign-in.
+
+## 1. Add the connectors
+
+<!-- ::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 { mcpConnector } from '@tanstack/ai-mcp/connector'
+import { openaiText } from '@tanstack/ai-openai'
+
+const notion = mcpConnector({
+  id: 'notion',
+  label: 'Notion',
+  url: 'https://mcp.notion.com/mcp',
+})
+const linear = mcpConnector({
+  id: 'linear',
+  label: 'Linear',
+  url: 'https://mcp.linear.app/mcp',
+})
+
+export const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-5.6'),
+  plugins: () => [notion, linear],
+})
+```
+
+Any MCP server that speaks Streamable HTTP and OAuth works the same way. Give it an `id`, a `label`, and its `url`.
+
+## 2. Sign in
+
+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.
+- `/disconnect linear` deletes them.
+
+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.
+
+## 3. Choose which tools ask first
+
+The connector names each tool `<id>_<tool>`, for example `linear_list_issues`. A tool that the server does not mark read-only asks for approval before it runs. To change that rule, pass `needsApproval`:
+
+```ts group=harness-mcp
+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'),
+})
+```
+
+Other options:
+
+- `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
+
+- `/connect` and `/disconnect` for Notion, Linear, and other MCP servers.
+- One browser sign-in per service, kept in your credential store.
+- Server tools in the model's tool list, with approval for tools that change data.
diff --git a/docs/harness/subagents.md b/docs/harness/subagents.md
index 71b89b77ea..169770cb0d 100644
--- a/docs/harness/subagents.md
+++ b/docs/harness/subagents.md
@@ -1,7 +1,7 @@
 ---
 title: Run agents from a harness
 id: harness-subagents
-order: 8
+order: 9
 description: "Start typed agents from commands and plugins, run them in groups, call a whole harness as a child, and keep the tree within limits."
 keywords:
   - tanstack ai
diff --git a/examples/harness-cli/.env.example b/examples/harness-cli/.env.example
new file mode 100644
index 0000000000..bb89717ef3
--- /dev/null
+++ b/examples/harness-cli/.env.example
@@ -0,0 +1,7 @@
+# Copy to .env. Without keys, a demo model answers.
+# The main model: OpenAI first, then Anthropic.
+# OPENAI_API_KEY also turns on the image and video tools.
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+# Optional: make videos with Grok Imagine instead of OpenAI Sora.
+XAI_API_KEY=
diff --git a/examples/harness-cli/.gitignore b/examples/harness-cli/.gitignore
new file mode 100644
index 0000000000..ec9309579e
--- /dev/null
+++ b/examples/harness-cli/.gitignore
@@ -0,0 +1,2 @@
+.env
+playground/media/
diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index cd5f93c5fe..bd0afebc98 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -1,6 +1,6 @@
 # Harness CLI example
 
-A small coding agent in your terminal, built with `@tanstack/ai-harness`. It reads and edits files in `./playground`, asks before it writes a file or runs a command, keeps a todo list, and can switch models.
+A small coding agent in your terminal, built with `@tanstack/ai-harness`. It reads and edits files in `./playground`, asks before it writes a file or runs a command, keeps a todo list, and can switch models. It can also read Notion and Linear, and make images and videos.
 
 ## Run it
 
@@ -8,7 +8,7 @@ From the repo root:
 
 1. `pnpm install`
 2. `pnpm build:all` (the example uses the local packages)
-3. Set a key: `OPENAI_API_KEY=...` or `ANTHROPIC_API_KEY=...`. Without one, a demo model answers.
+3. Copy `.env.example` to `.env` and set `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`. Without a key, a demo model answers.
 4. `pnpm --filter harness-cli-example start`
 
 Try these:
@@ -19,6 +19,15 @@ Try these:
 - `/agent haiku {"topic":"rain"}`: runs a typed agent in the background.
 - Press Esc to stop a long answer. Type while it works to steer it.
 
+## Use Notion, Linear, images, and video
+
+1. Run `/connect notion`. Approve the consent page that opens in the browser. Do the same with `/connect linear`.
+2. Ask: `find my latest Linear issue, look for a related Notion page, then make an image and a short video about it`.
+3. The files land in `playground/media`.
+
+- Sign-ins are kept in `~/.tanstack-harness-example/credentials.json`, so you sign in once. `/disconnect notion` deletes one.
+- Images use `OPENAI_API_KEY`. Videos use Grok Imagine when `XAI_API_KEY` is set, and OpenAI Sora when it is not.
+
 ## Other modes
 
 - One prompt for scripts and CI: `pnpm --filter harness-cli-example start -p "list the files"`
diff --git a/examples/harness-cli/package.json b/examples/harness-cli/package.json
index 3038efe1ff..96c40cb7d6 100644
--- a/examples/harness-cli/package.json
+++ b/examples/harness-cli/package.json
@@ -4,7 +4,7 @@
   "type": "module",
   "description": "A small coding agent in the terminal, built with @tanstack/ai-harness",
   "scripts": {
-    "start": "tsx src/cli.ts",
+    "start": "tsx --env-file-if-exists=.env src/cli.ts",
     "dashboard": "tanstack-ai-dashboard",
     "test:types": "tsc --noEmit"
   },
@@ -13,8 +13,10 @@
     "@tanstack/ai-acp": "workspace:*",
     "@tanstack/ai-anthropic": "workspace:*",
     "@tanstack/ai-dashboard": "workspace:*",
+    "@tanstack/ai-grok": "workspace:*",
     "@tanstack/ai-harness": "workspace:*",
     "@tanstack/ai-harness-cli": "workspace:*",
+    "@tanstack/ai-mcp": "workspace:*",
     "@tanstack/ai-openai": "workspace:*",
     "@tanstack/ai-persistence": "workspace:*",
     "zod": "^4.2.0"
diff --git a/examples/harness-cli/src/cli.ts b/examples/harness-cli/src/cli.ts
index 774a33ba2e..a4b42ec82e 100644
--- a/examples/harness-cli/src/cli.ts
+++ b/examples/harness-cli/src/cli.ts
@@ -1,4 +1,11 @@
 import { runCli } from '@tanstack/ai-harness-cli'
+import { composePersistence, memoryPersistence } from '@tanstack/ai-persistence'
+import { fileCredentials } from './credentials'
 import { assistant } from './harness'
 
-process.exitCode = await runCli(assistant)
+// Everything in memory, except sign-ins, which are kept in a file.
+const persistence = composePersistence(memoryPersistence(), {
+  overrides: { credentials: fileCredentials() },
+})
+
+process.exitCode = await runCli(assistant, { persistence })
diff --git a/examples/harness-cli/src/credentials.ts b/examples/harness-cli/src/credentials.ts
new file mode 100644
index 0000000000..06c358356b
--- /dev/null
+++ b/examples/harness-cli/src/credentials.ts
@@ -0,0 +1,53 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { defineCredentialStore } from '@tanstack/ai-persistence'
+import type { Credential } from '@tanstack/ai-persistence'
+
+/**
+ * Sign-ins (Notion, Linear) saved in a file in your home folder, so they
+ * survive a restart. The file is readable by your user only. A production
+ * store would encrypt the values.
+ */
+export function fileCredentials(
+  file = join(homedir(), '.tanstack-harness-example', 'credentials.json'),
+) {
+  type Saved = Record<string, Record<string, Credential>>
+  const load = async (): Promise<Saved> => {
+    try {
+      const parsed: unknown = JSON.parse(await readFile(file, 'utf8'))
+      return typeof parsed === 'object' && parsed !== null
+        ? (parsed as Saved)
+        : {}
+    } catch {
+      return {}
+    }
+  }
+  const save = async (all: Saved) => {
+    await mkdir(dirname(file), { recursive: true })
+    await writeFile(file, JSON.stringify(all, null, 2), { mode: 0o600 })
+  }
+  const owner = (scope: { userId?: string; tenantId?: string }) =>
+    `${scope.tenantId ?? '-'}/${scope.userId ?? '-'}`
+
+  return defineCredentialStore({
+    get: async (scope, id) => (await load())[owner(scope)]?.[id] ?? null,
+    set: async (scope, id, credential) => {
+      const all = await load()
+      all[owner(scope)] = { ...all[owner(scope)], [id]: credential }
+      await save(all)
+    },
+    delete: async (scope, id) => {
+      const all = await load()
+      delete all[owner(scope)]?.[id]
+      await save(all)
+    },
+    list: async (scope) =>
+      Object.entries((await load())[owner(scope)] ?? {}).map(
+        ([id, credential]) => ({
+          id,
+          type: credential.type,
+        }),
+      ),
+  })
+}
diff --git a/examples/harness-cli/src/harness.ts b/examples/harness-cli/src/harness.ts
index c87b1a6434..86699642c0 100644
--- a/examples/harness-cli/src/harness.ts
+++ b/examples/harness-cli/src/harness.ts
@@ -11,12 +11,16 @@ import {
   workspaceTools,
 } from '@tanstack/ai-harness/plugins'
 import { anthropicText } from '@tanstack/ai-anthropic'
-import { openaiText } from '@tanstack/ai-openai'
+import { mcpConnector } from '@tanstack/ai-mcp/connector'
+import { grokVideo } from '@tanstack/ai-grok'
+import { openaiText, openaiVideo } from '@tanstack/ai-openai'
 import { z } from 'zod'
+import { imageAgent, videoAgent } from './media'
 import type { AnyTextAdapter } from '@tanstack/ai'
 
 // The agent works in ./playground, so it cannot touch the rest of your disk.
 const root = fileURLToPath(new URL('../playground', import.meta.url))
+const mediaDir = fileURLToPath(new URL('../playground/media', import.meta.url))
 
 /** Without an API key, a stand-in model that explains how to add one. */
 function demoModel(): AnyTextAdapter {
@@ -116,15 +120,46 @@ const haiku = defineAgent({
     }),
 })
 
+// The model calls the media agents as tools. Images use OpenAI. Videos use
+// Grok Imagine when XAI_API_KEY is set, else OpenAI Sora.
+const media = process.env.OPENAI_API_KEY
+  ? [
+      imageAgent(mediaDir),
+      videoAgent(
+        mediaDir,
+        process.env.XAI_API_KEY
+          ? grokVideo('grok-imagine-video')
+          : openaiVideo('sora-2'),
+      ),
+    ]
+  : []
+
+// Notion and Linear through their MCP servers. `/connect notion` signs in
+// through the browser. No app setup or API key is needed.
+const notion = mcpConnector({
+  id: 'notion',
+  label: 'Notion',
+  url: 'https://mcp.notion.com/mcp',
+})
+const linear = mcpConnector({
+  id: 'linear',
+  label: 'Linear',
+  url: 'https://mcp.linear.app/mcp',
+})
+
 export const assistant = defineHarness({
   name: 'example/coder',
   description: 'A small coding agent that works in ./playground',
   adapter: main,
   systemPrompts: [
     'You are a careful coding agent. Read files before you edit them. Keep answers short.',
+    'You can read Notion and Linear when they are connected, and make images and videos with the image and video tools. Media files are saved under ./playground/media.',
   ],
   agents: [haiku],
+  subagents: { agents: media },
   plugins: () => [
+    notion,
+    linear,
     permissions(),
     workspaceTools({ root }),
     todos(),
diff --git a/examples/harness-cli/src/media.ts b/examples/harness-cli/src/media.ts
new file mode 100644
index 0000000000..40b9329ae0
--- /dev/null
+++ b/examples/harness-cli/src/media.ts
@@ -0,0 +1,90 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { defineAgent, getVideoJobStatus } from '@tanstack/ai'
+import { openaiImage } from '@tanstack/ai-openai'
+import { z } from 'zod'
+import type { AnyVideoAdapter } from '@tanstack/ai'
+
+/** A short file name from a prompt: `a-fox-in-the-snow-1714000000000`. */
+function fileName(prompt: string): string {
+  const slug = prompt
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 40)
+  return `${slug || 'media'}-${Date.now()}`
+}
+
+async function download(url: string): Promise<Buffer> {
+  const response = await fetch(url)
+  if (!response.ok) throw new Error(`Download failed (${response.status}).`)
+  return Buffer.from(await response.arrayBuffer())
+}
+
+/** Makes an image with OpenAI and saves it as a PNG in `mediaDir`. */
+export function imageAgent(mediaDir: string) {
+  return defineAgent({
+    name: 'image',
+    description:
+      'Generates one image from a detailed visual prompt and saves it as a PNG file. Returns the file path.',
+    produces: 'image',
+    inputSchema: z.object({
+      prompt: z.string().describe('A detailed description of the image'),
+    }),
+    run: async (ctx) => {
+      const result = await ctx.generateImage({
+        adapter: openaiImage('gpt-image-2'),
+        prompt: ctx.input.prompt,
+        size: '1024x1024',
+      })
+      const image = result.images[0]
+      if (!image) throw new Error('The image model returned no image.')
+      let bytes: Buffer
+      if (image.b64Json) bytes = Buffer.from(image.b64Json, 'base64')
+      else if (image.url) bytes = await download(image.url)
+      else throw new Error('The image model returned no image data.')
+      await mkdir(mediaDir, { recursive: true })
+      const path = join(mediaDir, `${fileName(ctx.input.prompt)}.png`)
+      await writeFile(path, bytes)
+      return { saved: path, model: result.model }
+    },
+  })
+}
+
+/** Makes a short video with `adapter` and saves it as an MP4 in `mediaDir`. */
+export function videoAgent(mediaDir: string, adapter: AnyVideoAdapter) {
+  return defineAgent({
+    name: 'video',
+    description:
+      'Generates one short video clip from a detailed visual prompt and saves it as an MP4 file. Takes a minute or two. Returns the file path.',
+    produces: 'video',
+    inputSchema: z.object({
+      prompt: z
+        .string()
+        .describe('A detailed description of the scene and the motion'),
+    }),
+    run: async (ctx) => {
+      const { jobId } = await ctx.generateVideo({
+        adapter,
+        prompt: ctx.input.prompt,
+      })
+      // Video models work in the background, so poll until the job is done.
+      const deadline = Date.now() + 10 * 60_000
+      let url: string | undefined
+      while (!url) {
+        if (ctx.abortSignal?.aborted) throw new Error('Stopped.')
+        if (Date.now() > deadline)
+          throw new Error('The video took longer than 10 minutes.')
+        await new Promise((resolve) => setTimeout(resolve, 4000))
+        const status = await getVideoJobStatus({ adapter, jobId })
+        if (status.status === 'failed')
+          throw new Error(status.error ?? 'The video job failed.')
+        if (status.status === 'completed') url = status.url
+      }
+      await mkdir(mediaDir, { recursive: true })
+      const path = join(mediaDir, `${fileName(ctx.input.prompt)}.mp4`)
+      await writeFile(path, await download(url))
+      return { saved: path, model: adapter.model }
+    },
+  })
+}
diff --git a/packages/ai-harness/src/define.ts b/packages/ai-harness/src/define.ts
index aef7787bd7..a2bacc3968 100644
--- a/packages/ai-harness/src/define.ts
+++ b/packages/ai-harness/src/define.ts
@@ -35,6 +35,7 @@ export interface HarnessConfig<
   systemPrompts?: Array<SystemPrompt>
   tools?: ReadonlyArray<AnyTool>
   middleware?: ReadonlyArray<AnyChatMiddleware>
+  /** When a turn stops calling the model. Defaults to `maxIterations(50)`. */
   agentLoopStrategy?: AgentLoopStrategy
   modelOptions?: TAdapter['~types']['providerOptions']
   interrupts?: ReadonlyArray<InterruptDefinition<any, any, any, any>>
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index cc4fa6a623..9e5b6b473d 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -107,6 +107,7 @@ export {
   isExpired,
   loopbackLogin,
   refreshCredential,
+  startLoopbackReceiver,
 } from './oauth'
 export type { OAuthConfig } from './oauth'
 
diff --git a/packages/ai-harness/src/oauth.ts b/packages/ai-harness/src/oauth.ts
index 8928322a76..b73cf14f8e 100644
--- a/packages/ai-harness/src/oauth.ts
+++ b/packages/ai-harness/src/oauth.ts
@@ -158,6 +158,68 @@ export async function refreshCredential(
 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.
+ */
+export async function startLoopbackReceiver(
+  options: { timeoutMs?: number } = {},
+): Promise<{
+  redirectUri: string
+  waitForCode: (state: string) => Promise<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<string>((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')
+          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(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
diff --git a/packages/ai-harness/src/plugins.ts b/packages/ai-harness/src/plugins.ts
index d708655a19..21cce825ce 100644
--- a/packages/ai-harness/src/plugins.ts
+++ b/packages/ai-harness/src/plugins.ts
@@ -62,6 +62,12 @@ export interface PluginContributions {
    * keep the harness adapter. The last plugin that returns one wins.
    */
   adapter?: () => AnyTextAdapter | undefined
+  /**
+   * Tools found at run time, for example the tools of an MCP server the user
+   * signed in to after the session opened. Called before each chat turn. A
+   * name that another tool already uses is skipped.
+   */
+  discoverTools?: () => ReadonlyArray<AnyTool> | Promise<ReadonlyArray<AnyTool>>
 }
 
 /** Plugin state that survives restarts, stored in the metadata store. */
@@ -238,6 +244,10 @@ export interface MountedPlugins {
   /** Contributions to extension points, by point name. */
   extensions: Map<string, Array<{ value: unknown; owner: string }>>
   adapters: Array<() => AnyTextAdapter | undefined>
+  discoverers: Array<{
+    discover: () => ReadonlyArray<AnyTool> | Promise<ReadonlyArray<AnyTool>>
+    owner: string
+  }>
   /** Who contributed what, for `session.inspect()`. */
   owners: {
     plugins: Array<{
@@ -420,6 +430,7 @@ export async function mountPlugins(
     extensions.set(point, [...items])
   }
   const adapters: Array<() => AnyTextAdapter | undefined> = []
+  const discoverers: MountedPlugins['discoverers'] = []
   const services = env.services ?? NO_SERVICES
 
   try {
@@ -550,6 +561,12 @@ export async function mountPlugins(
         items.push({ value: item.value, owner: plugin.name })
       }
       if (contributions.adapter) adapters.push(contributions.adapter)
+      if (contributions.discoverTools) {
+        discoverers.push({
+          discover: contributions.discoverTools,
+          owner: plugin.name,
+        })
+      }
       for (const agent of contributions.agents ?? []) {
         env.registry.add(agent, plugin.name)
       }
@@ -602,6 +619,7 @@ export async function mountPlugins(
     config,
     extensions,
     adapters,
+    discoverers,
     owners: {
       plugins: plugins.map((plugin) => ({
         name: plugin.name,
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index df0e852c08..af056aa2b5 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -6,6 +6,7 @@ import {
   compactForModel,
   convertSchemaToJsonSchema,
   createSubagentId,
+  maxIterations,
   runAgentStream,
   validateWithStandardSchema,
 } from '@tanstack/ai'
@@ -24,6 +25,7 @@ import {
 import { HARNESS_EVENTS } from './types'
 import type {
   AnyChatMiddleware,
+  AnyTool,
   Interrupt,
   ModelMessage,
   RunAgentResumeItem,
@@ -906,6 +908,36 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     })
   }
 
+  /**
+   * Ask each plugin for the tools it found since the last turn. A plugin
+   * that fails (for example an MCP server that is down) is skipped, and
+   * clients get a `harness.plugin.warning` event.
+   */
+  private async discoverTools(
+    discoverers: MountedPlugins['discoverers'],
+    taken: Set<string>,
+    operation: OperationImpl<ChatTurnResult>,
+  ): Promise<Array<AnyTool>> {
+    const found: Array<AnyTool> = []
+    for (const { discover, owner } of discoverers) {
+      try {
+        for (const tool of await discover()) {
+          if (taken.has(tool.name)) continue
+          taken.add(tool.name)
+          found.push(tool)
+        }
+      } catch (error) {
+        operation.publish(
+          customEvent('harness.plugin.warning', {
+            plugin: owner,
+            message: error instanceof Error ? error.message : String(error),
+          }),
+        )
+      }
+    }
+    return found
+  }
+
   /** Middleware that adds queued steer messages before each model call. */
   private steering(): AnyChatMiddleware {
     return {
@@ -1017,6 +1049,16 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         .at(-1)
       const resolvePrompt = (prompt: string | (() => string)) =>
         typeof prompt === 'function' ? prompt() : prompt
+      const staticTools = [
+        ...(this.harness.tools ?? []),
+        ...(session?.tools ?? []),
+        ...(runPlugins?.tools ?? []),
+      ]
+      const discovered = await this.discoverTools(
+        [...(session?.discoverers ?? []), ...(runPlugins?.discoverers ?? [])],
+        new Set(staticTools.map((tool) => tool.name)),
+        operation,
+      )
       const stream = chat({
         adapter: picked ?? this.harness.adapter,
         messages:
@@ -1029,11 +1071,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             .map(resolvePrompt)
             .filter((prompt) => prompt !== ''),
         ],
-        tools: [
-          ...(this.harness.tools ?? []),
-          ...(session?.tools ?? []),
-          ...(runPlugins?.tools ?? []),
-        ],
+        tools: [...staticTools, ...discovered],
         middleware: [
           ...bridges,
           withPersistence(this.persistence),
@@ -1052,9 +1090,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
               },
             }
           : {}),
-        ...(this.harness.agentLoopStrategy
-          ? { agentLoopStrategy: this.harness.agentLoopStrategy }
-          : {}),
+        // chat() stops after 5 model calls by default. An agent that reads,
+        // searches, and calls tools needs more before it can answer.
+        agentLoopStrategy: this.harness.agentLoopStrategy ?? maxIterations(50),
         ...(this.harness.modelOptions !== undefined
           ? { modelOptions: this.harness.modelOptions }
           : {}),
diff --git a/packages/ai-harness/tests/discover-tools.test.ts b/packages/ai-harness/tests/discover-tools.test.ts
new file mode 100644
index 0000000000..1e7653645d
--- /dev/null
+++ b/packages/ai-harness/tests/discover-tools.test.ts
@@ -0,0 +1,165 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { EventType, toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  createHarnessHost,
+  defineHarness,
+  definePlugin,
+  startLoopbackReceiver,
+} from '../src'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { SessionEvent } from '../src'
+
+const echoTool = (name: string, reply: string) =>
+  toolDefinition({
+    name,
+    description: `The ${name} tool`,
+    inputSchema: z.object({}),
+  }).server(async () => reply)
+
+describe('discoverTools', () => {
+  it('adds tools a plugin finds at run time, skips taken names, and warns on failure', async () => {
+    let online = false
+    const connector = definePlugin({
+      name: 'test/connector',
+      setup: () => ({
+        discoverTools: () =>
+          online
+            ? [
+                echoTool('remote_search', 'remote result'),
+                echoTool('lookup', 'shadowed'),
+              ]
+            : [],
+      }),
+    })
+    const broken = definePlugin({
+      name: 'test/broken',
+      setup: () => ({
+        discoverTools: async () => {
+          throw new Error('server is down')
+        },
+      }),
+    })
+    const { adapter, calls } = mockAdapter([
+      () => text('nothing yet'),
+      () => toolCall('remote_search', {}),
+      () => text('done'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/discover',
+        adapter,
+        tools: [echoTool('lookup', 'local result')],
+        plugins: () => [connector, broken],
+      }),
+      { threadId: 't' },
+    )
+    const names = (call: number) =>
+      (calls[call].tools ?? []).map((tool: { name: string }) => tool.name)
+
+    const seen: Array<SessionEvent> = []
+    const controller = new AbortController()
+    const reading = (async () => {
+      for await (const entry of session.events({ signal: controller.signal }))
+        seen.push(entry)
+    })()
+
+    await session.prompt('before sign-in')
+    expect(names(0)).toEqual(['lookup'])
+
+    online = true
+    const turn = await session.prompt('after sign-in')
+    expect(turn.text).toBe('done')
+    // The static `lookup` wins over the discovered one with the same name.
+    expect(names(1)).toEqual(['lookup', 'remote_search'])
+    expect(JSON.stringify(calls[2].messages)).toContain('remote result')
+
+    controller.abort()
+    await reading
+    const warnings = seen.filter(
+      (entry) =>
+        entry.event.type === EventType.CUSTOM &&
+        entry.event.name === 'harness.plugin.warning',
+    )
+    expect(warnings[0]?.event).toMatchObject({
+      value: { plugin: 'test/broken', message: 'server is down' },
+    })
+    await host.close()
+  })
+})
+
+describe('the default agent loop', () => {
+  it('keeps calling the model past five steps', async () => {
+    const steps = Array.from(
+      { length: 7 },
+      (_, index) => () => toolCall('lookup', {}, `call-${index}`),
+    )
+    const { adapter, calls } = mockAdapter([...steps, () => text('finally')])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/long-turn',
+        adapter,
+        tools: [echoTool('lookup', 'fact')],
+      }),
+      { threadId: 't' },
+    )
+    const turn = await session.prompt('dig deep')
+    expect(calls).toHaveLength(8)
+    expect(turn.text).toBe('finally')
+    await host.close()
+  })
+})
+
+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).toBe('abc')
+  })
+
+  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-mcp/package.json b/packages/ai-mcp/package.json
index 7989380ff3..bb338abb69 100644
--- a/packages/ai-mcp/package.json
+++ b/packages/ai-mcp/package.json
@@ -44,6 +44,10 @@
     "./apps": {
       "types": "./dist/esm/apps/index.d.ts",
       "import": "./dist/esm/apps/index.js"
+    },
+    "./connector": {
+      "types": "./dist/esm/connector.d.ts",
+      "import": "./dist/esm/connector.js"
     }
   },
   "files": [
@@ -66,7 +70,17 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@tanstack/ai": "workspace:^"
   },
+  "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/src/connector.ts b/packages/ai-mcp/src/connector.ts
new file mode 100644
index 0000000000..3a9e94ab94
--- /dev/null
+++ b/packages/ai-mcp/src/connector.ts
@@ -0,0 +1,291 @@
+import { randomBytes } from 'node:crypto'
+import { auth } from '@modelcontextprotocol/sdk/client/auth.js'
+import {
+  AuthRequiredError,
+  defineCommand,
+  definePlugin,
+  startLoopbackReceiver,
+} from '@tanstack/ai-harness'
+import { createMCPClient } from './client'
+import type {
+  OAuthClientInformationMixed,
+  OAuthClientMetadata,
+  OAuthTokens,
+} from '@modelcontextprotocol/sdk/shared/auth.js'
+import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js'
+import type { AnyTool } from '@tanstack/ai'
+import type { CredentialsAccess } from '@tanstack/ai-harness'
+import type { MCPClient } from './client'
+
+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>`. */
+  prefix?: string
+  /** 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 | undefined
+    clientName: string
+    scopes: ReadonlyArray<string> | undefined
+    state?: string
+    onRedirect?: (url: URL) => void
+  },
+): OAuthClientProvider {
+  let client: OAuthClientInformationMixed | undefined
+  let verifier = ''
+  const stored = async () => {
+    const credential = await credentials.get(id)
+    return credential?.type === 'oauth' ? credential : undefined
+  }
+  return {
+    get redirectUrl() {
+      return options.redirectUri
+    },
+    get clientMetadata(): OAuthClientMetadata {
+      return {
+        client_name: options.clientName,
+        redirect_uris: options.redirectUri ? [options.redirectUri] : [],
+        grant_types: ['authorization_code', 'refresh_token'],
+        response_types: ['code'],
+        token_endpoint_auth_method: 'none',
+        ...(options.scopes?.length ? { scope: options.scopes.join(' ') } : {}),
+      }
+    },
+    ...(options.state ? { state: () => options.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
+      return saved
+        ? {
+            client_id: saved.clientId,
+            ...(saved.clientSecret
+              ? { client_secret: saved.clientSecret }
+              : {}),
+          }
+        : undefined
+    },
+    saveClientInformation: (information) => {
+      client = information
+    },
+    tokens: async (): Promise<OAuthTokens | undefined> => {
+      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),
+              ),
+            }
+          : {}),
+      }
+    },
+    saveTokens: async (tokens) => {
+      const previous = await stored()
+      const information =
+        client ??
+        (previous?.client
+          ? {
+              client_id: previous.client.clientId,
+              client_secret: previous.client.clientSecret,
+            }
+          : undefined)
+      await credentials.set(id, {
+        type: 'oauth',
+        accessToken: tokens.access_token,
+        ...(tokens.refresh_token
+          ? { refreshToken: tokens.refresh_token }
+          : previous?.refreshToken
+            ? { refreshToken: previous.refreshToken }
+            : {}),
+        ...(tokens.expires_in
+          ? { expiresAt: Date.now() + tokens.expires_in * 1000 }
+          : {}),
+        ...(tokens.scope ? { scopes: tokens.scope.split(' ') } : {}),
+        ...(information
+          ? {
+              client: {
+                clientId: information.client_id,
+                ...(information.client_secret
+                  ? { clientSecret: information.client_secret }
+                  : {}),
+                ...((options.redirectUri ?? previous?.client?.redirectUri)
+                  ? {
+                      redirectUri:
+                        options.redirectUri ?? previous?.client?.redirectUri,
+                    }
+                  : {}),
+              },
+            }
+          : {}),
+      })
+    },
+    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,
+  }
+}
+
+/**
+ * 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>`.
+ *   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) => {
+      let connected = (await ctx.credentials.get(id)) !== null
+      let client: MCPClient | undefined
+      let tools: ReadonlyArray<AnyTool> | undefined
+      const reset = async () => {
+        tools = undefined
+        const open = client
+        client = undefined
+        await open?.close().catch(() => {})
+      }
+      await ctx.resources.acquire(
+        () => undefined,
+        () => reset(),
+      )
+
+      return {
+        prompts: [
+          {
+            id: `connector/${id}:status`,
+            text: () =>
+              connected
+                ? ''
+                : `${label} is not connected. If the user asks for ${label}, tell them to run /connect ${id}.`,
+          },
+        ],
+        discoverTools: async () => {
+          if (!connected) return []
+          if (!tools) {
+            client = await createMCPClient({
+              transport: {
+                type: 'http',
+                url,
+                authProvider: credentialProvider(id, ctx.credentials, {
+                  redirectUri: undefined,
+                  clientName,
+                  scopes: options.scopes,
+                }),
+                ...(options.fetch ? { fetch: options.fetch } : {}),
+              },
+              prefix,
+              needsApproval:
+                options.needsApproval ??
+                ((tool) => tool.annotations?.readOnlyHint !== true),
+            })
+            tools = (await client.tools()) as ReadonlyArray<AnyTool>
+          }
+          return tools
+        },
+        commands: {
+          [`connect:${id}`]: defineCommand({
+            description: `Sign in to ${label}`,
+            run: async () => {
+              const receiver = await startLoopbackReceiver()
+              const state = randomBytes(16).toString('base64url')
+              try {
+                const provider = credentialProvider(id, ctx.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 } : {}
+                const first = await auth(provider, {
+                  serverUrl: url,
+                  ...fetchFn,
+                })
+                if (first === 'REDIRECT') {
+                  const code = await receiver.waitForCode(state)
+                  await auth(provider, {
+                    serverUrl: url,
+                    authorizationCode: code,
+                    ...fetchFn,
+                  })
+                }
+              } finally {
+                receiver.close()
+              }
+              connected = true
+              await reset()
+              return `Connected to ${label}.`
+            },
+          }),
+          [`disconnect:${id}`]: defineCommand({
+            description: `Sign out of ${label}`,
+            run: async () => {
+              await ctx.credentials.delete(id)
+              connected = false
+              await reset()
+              return `Disconnected from ${label}.`
+            },
+          }),
+        },
+      }
+    },
+  })
+}
diff --git a/packages/ai-mcp/tests/connector.test.ts b/packages/ai-mcp/tests/connector.test.ts
new file mode 100644
index 0000000000..55261ca78b
--- /dev/null
+++ b/packages/ai-mcp/tests/connector.test.ts
@@ -0,0 +1,361 @@
+import { createServer } from 'node:http'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+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 type { IncomingMessage, Server } from 'node:http'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+
+/**
+ * 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.
+ */
+async function startProtectedServer() {
+  const seen = { registrations: 0, tokenRequests: [] as Array<URLSearchParams> }
+  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'],
+        })
+      }
+      if (url.pathname === '/register' && req.method === 'POST') {
+        seen.registrations += 1
+        const metadata = JSON.parse(await readBody(req))
+        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,
+          })
+        }
+        return json(400, { error: 'invalid_grant' })
+      }
+      if (url.pathname === '/mcp') {
+        if (req.headers.authorization !== 'Bearer access-1') {
+          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 StreamableHTTPServerTransport({
+          sessionIdGenerator: undefined,
+          enableJsonResponse: true,
+        })
+        await mcp.connect(transport)
+        await transport.handleRequest(req, res, JSON.parse(await readBody(req)))
+        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`,
+    seen,
+    close: () =>
+      new Promise<void>((resolve) => {
+        server.closeAllConnections()
+        server.close(() => resolve())
+      }),
+  }
+}
+
+/** A model that calls `tool` once, then answers with the tool result it saw. */
+function modelCalling(
+  tool: string,
+  args: Record<string, unknown>,
+): AnyTextAdapter {
+  let call = 0
+  const now = () => Date.now()
+  return {
+    kind: 'text',
+    name: 'mock',
+    model: 'mock',
+    '~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) =>
+      (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' },
+    })
+
+    // Act as the browser: approve the sign-in by calling the loopback redirect.
+    const reader = new AbortController()
+    let authorizationUrl: URL | undefined
+    void (async () => {
+      for await (const entry of session.events({ signal: reader.signal })) {
+        const event = entry.event
+        if (
+          event.type === EventType.CUSTOM &&
+          event.name === HARNESS_EVENTS.authRequired
+        ) {
+          authorizationUrl = new URL(
+            String((event.value as { url: string }).url),
+          )
+          const redirect = new URL(
+            authorizationUrl.searchParams.get('redirect_uri') ?? '',
+          )
+          redirect.searchParams.set('code', 'code-1')
+          redirect.searchParams.set(
+            'state',
+            authorizationUrl.searchParams.get('state') ?? '',
+          )
+          await fetch(redirect)
+        }
+      }
+    })()
+    cleanups.push(() => reader.abort())
+
+    await expect(session.command('connect:demo')).resolves.toBe(
+      'Connected to Demo.',
+    )
+    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')
+    expect(protectedServer.seen.registrations).toBe(1)
+    expect(
+      protectedServer.seen.tokenRequests[0]?.get('code_verifier'),
+    ).toBeTruthy()
+
+    const saved = await persistence.stores.credentials.get(
+      { threadId: 't', userId: 'user-1' },
+      'demo',
+    )
+    expect(saved).toMatchObject({
+      type: 'oauth',
+      accessToken: 'access-1',
+      refreshToken: 'refresh-1',
+      client: { clientId: 'client-1' },
+    })
+
+    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(
+        { threadId: 't', userId: 'user-1' },
+        'demo',
+      ),
+    ).toBeNull()
+  })
+
+  it('tells the model to ask for /connect before sign-in', async () => {
+    const seen = vi.fn()
+    const adapter: AnyTextAdapter = {
+      ...modelCalling('x', {}),
+      chatStream: (options) => {
+        seen(options.systemPrompts)
+        return (async function* (): AsyncGenerator<StreamChunk> {
+          yield {
+            type: EventType.RUN_STARTED,
+            runId: 'r',
+            threadId: 't',
+            timestamp: Date.now(),
+          }
+          yield {
+            type: EventType.RUN_FINISHED,
+            runId: 'r',
+            threadId: 't',
+            timestamp: Date.now(),
+            metadata: { tanstack: { finishReason: 'stop' } },
+          }
+        })()
+      },
+    }
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    cleanups.push(() => host.close())
+    const session = await host.open(
+      defineHarness({
+        name: 'test/mcp-connector-off',
+        adapter,
+        plugins: () => [
+          mcpConnector({
+            id: 'demo',
+            label: 'Demo',
+            url: 'http://127.0.0.1:9/mcp',
+          }),
+        ],
+      }),
+      { threadId: 't' },
+    )
+    await session.prompt('hi')
+    expect(JSON.stringify(seen.mock.calls[0]?.[0])).toContain(
+      'run /connect demo',
+    )
+    expect(session.commands().map((command) => command.name)).toEqual([
+      'connect:demo',
+      'disconnect:demo',
+    ])
+  })
+})
diff --git a/packages/ai-mcp/vite.config.ts b/packages/ai-mcp/vite.config.ts
index 5a8fee615b..2c65c4ca38 100644
--- a/packages/ai-mcp/vite.config.ts
+++ b/packages/ai-mcp/vite.config.ts
@@ -25,7 +25,12 @@ const config = defineConfig({
 export default mergeConfig(
   config,
   tanstackViteConfig({
-    entry: ['./src/index.ts', './src/stdio.ts', './src/apps/index.ts'],
+    entry: [
+      './src/index.ts',
+      './src/stdio.ts',
+      './src/apps/index.ts',
+      './src/connector.ts',
+    ],
     srcDir: './src',
     cjs: false,
   }),
diff --git a/packages/ai-persistence/src/types.ts b/packages/ai-persistence/src/types.ts
index 3785eb4240..956aef08de 100644
--- a/packages/ai-persistence/src/types.ts
+++ b/packages/ai-persistence/src/types.ts
@@ -425,6 +425,11 @@ export type Credential =
       refreshToken?: string
       expiresAt?: number
       scopes?: Array<string>
+      /**
+       * The OAuth client these tokens belong to (for example one made by
+       * dynamic client registration). A refresh needs it.
+       */
+      client?: { clientId: string; clientSecret?: string; redirectUri?: string }
     }
 
 /**
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d8f2711c60..ea2077b4b1 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -188,12 +188,18 @@ importers:
       '@tanstack/ai-dashboard':
         specifier: workspace:*
         version: link:../../packages/ai-dashboard
+      '@tanstack/ai-grok':
+        specifier: workspace:*
+        version: link:../../packages/ai-grok
       '@tanstack/ai-harness':
         specifier: workspace:*
         version: link:../../packages/ai-harness
       '@tanstack/ai-harness-cli':
         specifier: workspace:*
         version: link:../../packages/ai-harness-cli
+      '@tanstack/ai-mcp':
+        specifier: workspace:*
+        version: link:../../packages/ai-mcp
       '@tanstack/ai-openai':
         specifier: workspace:*
         version: link:../../packages/ai-openai
@@ -2753,6 +2759,12 @@ importers:
         specifier: workspace:^
         version: link:../ai
     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)

From f479affcd432765345fd897b1b244bce02f2c6a4 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 15:19:27 +0200
Subject: [PATCH 019/286] feat(ai-code-mode, ai-harness): code mode plugin for
 harnesses with pluggable isolates

---
 .changeset/harness-p8-code-mode.md            |   8 +
 docs/config.json                              |   5 +
 docs/harness/code-mode.md                     |  96 ++++++
 docs/harness/dashboard.md                     |   2 +-
 docs/harness/deploy.md                        |   2 +-
 docs/harness/subagents.md                     |   2 +-
 examples/harness-cli/README.md                |   1 +
 examples/harness-cli/package.json             |   2 +
 examples/harness-cli/src/harness.ts           |   7 +
 packages/ai-code-mode/package.json            |  12 +
 packages/ai-code-mode/src/harness.ts          | 104 ++++++
 packages/ai-code-mode/tests/harness.test.ts   | 303 ++++++++++++++++++
 packages/ai-code-mode/vite.config.ts          |   2 +-
 packages/ai-harness/src/index.ts              |   8 +
 packages/ai-harness/src/plugins.ts            |  21 ++
 packages/ai-harness/src/session.ts            |  48 ++-
 .../ai-harness/tests/prepare-tools.test.ts    |  80 +++++
 pnpm-lock.yaml                                |  12 +
 18 files changed, 704 insertions(+), 11 deletions(-)
 create mode 100644 .changeset/harness-p8-code-mode.md
 create mode 100644 docs/harness/code-mode.md
 create mode 100644 packages/ai-code-mode/src/harness.ts
 create mode 100644 packages/ai-code-mode/tests/harness.test.ts
 create mode 100644 packages/ai-harness/tests/prepare-tools.test.ts

diff --git a/.changeset/harness-p8-code-mode.md b/.changeset/harness-p8-code-mode.md
new file mode 100644
index 0000000000..7c5d58f318
--- /dev/null
+++ b/.changeset/harness-p8-code-mode.md
@@ -0,0 +1,8 @@
+---
+'@tanstack/ai-code-mode': minor
+'@tanstack/ai-harness': minor
+---
+
+`@tanstack/ai-code-mode/harness` adds `codeMode({ driver })`: a harness plugin that gives the model one `execute_typescript` tool. The model writes a program that calls several tools, and the program runs in the isolate of any `@tanstack/ai-isolate-*` driver. Read-only tools move into code mode, including MCP tools found after sign-in. Tools that need approval, edits, and commands stay normal tool calls. Tool names that are not JavaScript identifiers (for example `notion-search`) get a safe name inside the program.
+
+`@tanstack/ai-harness` adds `prepareTools` to plugins, to change the tool list of each turn. `PermissionRules` and `decidePermission` are now also exported from the package root.
diff --git a/docs/config.json b/docs/config.json
index 8b9dea312f..71a5f53d3a 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -844,6 +844,11 @@
           "to": "harness/mcp",
           "addedAt": "2026-09-26"
         },
+        {
+          "label": "Code mode in a harness",
+          "to": "harness/code-mode",
+          "addedAt": "2026-09-26"
+        },
         {
           "label": "Run agents from a harness",
           "to": "harness/subagents",
diff --git a/docs/harness/code-mode.md b/docs/harness/code-mode.md
new file mode 100644
index 0000000000..c84a9e51fb
--- /dev/null
+++ b/docs/harness/code-mode.md
@@ -0,0 +1,96 @@
+---
+title: Code mode in a harness
+id: harness-code-mode
+order: 9
+description: "Let the harness model write one TypeScript program that calls many tools, and run it in an isolate. Any TanStack AI isolate driver plugs in."
+keywords:
+  - tanstack ai
+  - harness
+  - code mode
+  - isolate
+  - quickjs
+---
+
+Your agent has 100 tools from Notion and Linear, and it calls them one at a time. Each call is a model round trip, and every tool schema goes into every request. With code mode, the model writes one TypeScript program that calls the tools it needs, and the program runs in an isolate. The read-only tools leave the tool list and become functions in that program.
+
+## 1. Add the plugin
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: @tanstack/ai-code-mode @tanstack/ai-isolate-quickjs
+vue: @tanstack/ai-code-mode @tanstack/ai-isolate-quickjs
+solid: @tanstack/ai-code-mode @tanstack/ai-isolate-quickjs
+svelte: @tanstack/ai-code-mode @tanstack/ai-isolate-quickjs
+preact: @tanstack/ai-code-mode @tanstack/ai-isolate-quickjs
+angular: @tanstack/ai-code-mode @tanstack/ai-isolate-quickjs
+octane: @tanstack/ai-code-mode @tanstack/ai-isolate-quickjs
+vanilla: @tanstack/ai-code-mode @tanstack/ai-isolate-quickjs
+
+<!-- ::end:tabs -->
+
+```ts group=harness-code-mode
+import { defineHarness } from '@tanstack/ai-harness'
+import { codeMode } from '@tanstack/ai-code-mode/harness'
+import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs'
+import { mcpConnector } from '@tanstack/ai-mcp/connector'
+import { openaiText } from '@tanstack/ai-openai'
+
+const linear = mcpConnector({
+  id: 'linear',
+  label: 'Linear',
+  url: 'https://mcp.linear.app/mcp',
+})
+
+export const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-5.6'),
+  plugins: () => [
+    linear,
+    codeMode({ driver: createQuickJSIsolateDriver() }),
+  ],
+})
+```
+
+The model now has an `execute_typescript` tool. Inside the program, each moved tool is an `external_*` function, for example `external_linear_list_issues()`.
+
+## 2. Pick the isolate
+
+`driver` takes any isolate driver. Change one line to run the programs somewhere else:
+
+| Driver | Package | Runs in |
+| --- | --- | --- |
+| `createQuickJSIsolateDriver()` | `@tanstack/ai-isolate-quickjs` | WebAssembly, on any runtime |
+| `createNodeIsolateDriver()` | `@tanstack/ai-isolate-node` | A V8 isolate in Node |
+| `createCloudflareIsolateDriver()` | `@tanstack/ai-isolate-cloudflare` | A Cloudflare Worker |
+| `createDaytonaIsolateDriver()` | `@tanstack/ai-isolate-daytona` | A Daytona sandbox |
+
+[Code mode isolates](../code-mode/code-mode-isolates) has the options of each driver.
+
+## 3. Choose which tools move
+
+A call inside the program does not stop for approval. So by default, a tool moves into code mode only when it is safe to run without a question:
+
+- The tool runs on the server and does not set `needsApproval`.
+- The permission rules allow it in plan mode. File reads move. `write_file` and `run_command` stay.
+- MCP tools that the server does not mark read-only ask for approval, so they stay too.
+
+Every other tool stays a normal tool call, with its approvals. To pick the tools yourself, pass `include`:
+
+```ts group=harness-code-mode
+export const onlyLinear = codeMode({
+  driver: createQuickJSIsolateDriver(),
+  include: (tool) => tool.name.startsWith('linear_'),
+})
+```
+
+The other options of `createCodeMode` pass through: `timeout`, `memoryLimit`, `lazyToolsConfig`, and more.
+
+## Tools that appear after sign-in
+
+The plugin chooses the tools again before every turn. When the user runs `/connect linear`, the read-only Linear tools move into code mode on the next turn. A plugin can do the same with its own tool changes: return the new list from `prepareTools`. [Use MCP servers](./mcp) shows `discoverTools`, which adds the tools first.
+
+## What you have now
+
+- One `execute_typescript` tool in place of many read-only tools.
+- Programs that run in the isolate you choose.
+- Approvals kept for every tool that can change something.
diff --git a/docs/harness/dashboard.md b/docs/harness/dashboard.md
index 3fab5e3e0a..afbd511cd7 100644
--- a/docs/harness/dashboard.md
+++ b/docs/harness/dashboard.md
@@ -1,7 +1,7 @@
 ---
 title: Self-host the dashboard
 id: harness-dashboard
-order: 11
+order: 12
 description: "Watch and steer your harness sessions from a browser or a phone. Agents dial out to your dashboard server, so they need no open port."
 keywords:
   - tanstack ai
diff --git a/docs/harness/deploy.md b/docs/harness/deploy.md
index e75187f2a4..ea6cf77423 100644
--- a/docs/harness/deploy.md
+++ b/docs/harness/deploy.md
@@ -1,7 +1,7 @@
 ---
 title: Deploy a harness
 id: harness-deploy
-order: 10
+order: 11
 description: "Run a harness in your server, as a worker process, on another machine, or as a single executable."
 keywords:
   - tanstack ai
diff --git a/docs/harness/subagents.md b/docs/harness/subagents.md
index 169770cb0d..78de061c97 100644
--- a/docs/harness/subagents.md
+++ b/docs/harness/subagents.md
@@ -1,7 +1,7 @@
 ---
 title: Run agents from a harness
 id: harness-subagents
-order: 9
+order: 10
 description: "Start typed agents from commands and plugins, run them in groups, call a whole harness as a child, and keep the tree within limits."
 keywords:
   - tanstack ai
diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index bd0afebc98..b87e8aa82f 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -27,6 +27,7 @@ Try these:
 
 - Sign-ins are kept in `~/.tanstack-harness-example/credentials.json`, so you sign in once. `/disconnect notion` deletes one.
 - Images use `OPENAI_API_KEY`. Videos use Grok Imagine when `XAI_API_KEY` is set, and OpenAI Sora when it is not.
+- Code mode is on: read-only tools (file reads, read-only Notion and Linear tools) are `external_*` functions in one `execute_typescript` program, which runs in a QuickJS isolate. Ask: `in one program, list my Linear issues and search Notion for them`.
 
 ## Other modes
 
diff --git a/examples/harness-cli/package.json b/examples/harness-cli/package.json
index 96c40cb7d6..a9d609b2b8 100644
--- a/examples/harness-cli/package.json
+++ b/examples/harness-cli/package.json
@@ -12,10 +12,12 @@
     "@tanstack/ai": "workspace:*",
     "@tanstack/ai-acp": "workspace:*",
     "@tanstack/ai-anthropic": "workspace:*",
+    "@tanstack/ai-code-mode": "workspace:*",
     "@tanstack/ai-dashboard": "workspace:*",
     "@tanstack/ai-grok": "workspace:*",
     "@tanstack/ai-harness": "workspace:*",
     "@tanstack/ai-harness-cli": "workspace:*",
+    "@tanstack/ai-isolate-quickjs": "workspace:*",
     "@tanstack/ai-mcp": "workspace:*",
     "@tanstack/ai-openai": "workspace:*",
     "@tanstack/ai-persistence": "workspace:*",
diff --git a/examples/harness-cli/src/harness.ts b/examples/harness-cli/src/harness.ts
index 86699642c0..bc0563abda 100644
--- a/examples/harness-cli/src/harness.ts
+++ b/examples/harness-cli/src/harness.ts
@@ -11,8 +11,10 @@ import {
   workspaceTools,
 } from '@tanstack/ai-harness/plugins'
 import { anthropicText } from '@tanstack/ai-anthropic'
+import { codeMode } from '@tanstack/ai-code-mode/harness'
 import { mcpConnector } from '@tanstack/ai-mcp/connector'
 import { grokVideo } from '@tanstack/ai-grok'
+import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs'
 import { openaiText, openaiVideo } from '@tanstack/ai-openai'
 import { z } from 'zod'
 import { imageAgent, videoAgent } from './media'
@@ -167,5 +169,10 @@ export const assistant = defineHarness({
     projectInstructions({ root }),
     compact({ adapter: main }),
     usage(),
+    // Read-only tools (file reads, read-only Notion and Linear tools) move
+    // behind execute_typescript, so the model can call several in one program.
+    // The program runs in a QuickJS isolate. Any @tanstack/ai-isolate-* driver
+    // works here.
+    codeMode({ driver: createQuickJSIsolateDriver() }),
   ],
 })
diff --git a/packages/ai-code-mode/package.json b/packages/ai-code-mode/package.json
index b3370c1f6c..ce05e3b109 100644
--- a/packages/ai-code-mode/package.json
+++ b/packages/ai-code-mode/package.json
@@ -24,6 +24,10 @@
     ".": {
       "types": "./dist/esm/index.d.ts",
       "import": "./dist/esm/index.js"
+    },
+    "./harness": {
+      "types": "./dist/esm/harness.d.ts",
+      "import": "./dist/esm/harness.js"
     }
   },
   "sideEffects": false,
@@ -65,10 +69,18 @@
   },
   "peerDependencies": {
     "@tanstack/ai": "workspace:^",
+    "@tanstack/ai-harness": "workspace:^",
     "zod": "^3.0.0 || ^4.0.0"
   },
+  "peerDependenciesMeta": {
+    "@tanstack/ai-harness": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-harness": "workspace:*",
+    "@tanstack/ai-persistence": "workspace:*",
     "@vitest/coverage-v8": "4.1.10",
     "zod": "^4.2.0"
   }
diff --git a/packages/ai-code-mode/src/harness.ts b/packages/ai-code-mode/src/harness.ts
new file mode 100644
index 0000000000..392959b55c
--- /dev/null
+++ b/packages/ai-code-mode/src/harness.ts
@@ -0,0 +1,104 @@
+import {
+  PermissionRules,
+  decidePermission,
+  definePlugin,
+} from '@tanstack/ai-harness'
+import { createCodeMode } from './create-code-mode'
+import type { AnyTool } from '@tanstack/ai'
+import type { CodeModeTool, CodeModeToolConfig } from './types'
+
+export interface CodeModePluginOptions extends Omit<
+  CodeModeToolConfig,
+  'tools'
+> {
+  /**
+   * Which tools move into code mode. Default: every server tool that does
+   * not need approval and that the permission rules allow in plan mode (so
+   * no edits, no commands, nothing that asks first).
+   */
+  include?: (tool: CodeModeTool) => boolean
+}
+
+/**
+ * A name that works as a JavaScript identifier. Code mode turns each tool
+ * into an `external_<name>` function, and MCP tool names often have `-`.
+ */
+function identifierOf(name: string): string {
+  const safe = name.replace(/[^A-Za-z0-9_$]/g, '_')
+  return /^[0-9]/.test(safe) ? `_${safe}` : safe
+}
+
+/** A tool that runs on the server: not a client tool, and it has `execute`. */
+function isServerTool(tool: AnyTool): tool is CodeModeTool {
+  const side = '__toolSide' in tool ? tool.__toolSide : 'server'
+  return side === 'server' && typeof tool.execute === 'function'
+}
+
+/**
+ * A harness plugin that gives the model an `execute_typescript` tool. The
+ * model writes one TypeScript program that calls several tools, and the
+ * program runs in the isolate of `driver` (any `@tanstack/ai-isolate-*`
+ * driver). The tools it calls leave the model's tool list, including tools
+ * that plugins find at run time, such as MCP tools after `/connect`.
+ *
+ * Calls inside the isolate do not stop for approval, so by default only
+ * tools that are safe to run without a question move into code mode. The
+ * other tools stay normal tool calls.
+ *
+ * @example
+ * ```ts
+ * import { codeMode } from '@tanstack/ai-code-mode/harness'
+ * import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs'
+ *
+ * defineHarness({
+ *   name: 'acme/agent',
+ *   adapter,
+ *   plugins: () => [codeMode({ driver: createQuickJSIsolateDriver() })],
+ * })
+ * ```
+ */
+export function codeMode(options: CodeModePluginOptions) {
+  const { include, ...config } = options
+  return definePlugin({
+    name: 'tanstack/code-mode',
+    setup: (ctx) => {
+      const rules = ctx.collect(PermissionRules)
+      const safe = (tool: CodeModeTool) =>
+        !tool.needsApproval &&
+        decidePermission(rules, tool.name, 'plan') === 'allow'
+      // The system prompt for the tools of the current turn.
+      let prompt = ''
+      return {
+        prompts: [{ id: 'tanstack/code-mode', text: () => prompt }],
+        prepareTools: (tools) => {
+          // Two tools that map to the same identifier: the first one moves.
+          const byIdentifier = new Map<string, CodeModeTool>()
+          for (const tool of tools.filter(isServerTool)) {
+            if (!(include ? include(tool) : safe(tool))) continue
+            const identifier = identifierOf(tool.name)
+            if (!byIdentifier.has(identifier))
+              byIdentifier.set(identifier, tool)
+          }
+          if (byIdentifier.size === 0) {
+            prompt = ''
+            return tools
+          }
+          const created = createCodeMode({
+            ...config,
+            tools: [...byIdentifier].map(([identifier, tool]) =>
+              identifier === tool.name ? tool : { ...tool, name: identifier },
+            ),
+          })
+          prompt = created.systemPrompt
+          const moved = new Set(
+            [...byIdentifier.values()].map((tool) => tool.name),
+          )
+          return [
+            ...tools.filter((tool) => !moved.has(tool.name)),
+            ...created.tools,
+          ]
+        },
+      }
+    },
+  })
+}
diff --git a/packages/ai-code-mode/tests/harness.test.ts b/packages/ai-code-mode/tests/harness.test.ts
new file mode 100644
index 0000000000..8266bbf402
--- /dev/null
+++ b/packages/ai-code-mode/tests/harness.test.ts
@@ -0,0 +1,303 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { EventType, toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  PermissionRules,
+  createHarnessHost,
+  defineHarness,
+  definePlugin,
+} from '@tanstack/ai-harness'
+import { codeMode } from '../src/harness'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import type { ExecutionResult, IsolateDriver, ToolBinding } from '../src/types'
+
+const now = () => Date.now()
+
+/** A model whose turns are scripted. Records the options of every call. */
+function scripted(turns: Array<Array<StreamChunk>>) {
+  const calls: Array<any> = []
+  const adapter: AnyTextAdapter = {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    '~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: any) => {
+      calls.push(options)
+      const chunks = turns[calls.length - 1] ?? []
+      return (async function* () {
+        yield* chunks
+      })()
+    },
+  }
+  return { adapter, calls }
+}
+
+const textTurn = (content: string): Array<StreamChunk> => [
+  { type: EventType.RUN_STARTED, runId: 'r', threadId: 't', timestamp: now() },
+  {
+    type: EventType.TEXT_MESSAGE_START,
+    messageId: 'm',
+    role: 'assistant',
+    timestamp: now(),
+  },
+  {
+    type: EventType.TEXT_MESSAGE_CONTENT,
+    messageId: 'm',
+    delta: content,
+    timestamp: now(),
+  },
+  { type: EventType.TEXT_MESSAGE_END, messageId: 'm', timestamp: now() },
+  {
+    type: EventType.RUN_FINISHED,
+    runId: 'r',
+    threadId: 't',
+    timestamp: now(),
+    metadata: { tanstack: { finishReason: 'stop' } },
+  },
+]
+
+const codeTurn = (code: string): Array<StreamChunk> => [
+  { type: EventType.RUN_STARTED, runId: 'r', threadId: 't', timestamp: now() },
+  {
+    type: EventType.TOOL_CALL_START,
+    toolCallId: 'call-code',
+    toolCallName: 'execute_typescript',
+    timestamp: now(),
+  },
+  {
+    type: EventType.TOOL_CALL_ARGS,
+    toolCallId: 'call-code',
+    delta: JSON.stringify({ typescriptCode: code }),
+    timestamp: now(),
+  },
+  { type: EventType.TOOL_CALL_END, toolCallId: 'call-code', timestamp: now() },
+  {
+    type: EventType.RUN_FINISHED,
+    runId: 'r',
+    threadId: 't',
+    timestamp: now(),
+    metadata: { tanstack: { finishReason: 'tool_calls' } },
+  },
+]
+
+/**
+ * A stand-in isolate: it records the bindings it got and, for any program,
+ * calls `external_lookup` and `external_notion_search` and returns both
+ * results. Real drivers run the program itself.
+ */
+function fakeDriver() {
+  const seen: Array<Array<string>> = []
+  const driver: IsolateDriver = {
+    createContext: async ({ bindings }) => {
+      seen.push(Object.keys(bindings).sort())
+      const call = (name: string, args: unknown) =>
+        (bindings[name] as ToolBinding).execute(args)
+      return {
+        execute: async <T>(): Promise<ExecutionResult<T>> => {
+          const value = {
+            lookup: await call('external_lookup', { q: 'x' }),
+            notion: await call('external_notion_search', { query: 'y' }),
+          }
+          // The caller picks T. This stand-in always returns the two results.
+          return { success: true, value: value as T, logs: [] }
+        },
+        dispose: async () => {},
+      }
+    },
+  }
+  return { driver, seen }
+}
+
+const lookup = vi.fn(async () => 'fact')
+const notionSearch = vi.fn(async () => ({ results: ['page'] }))
+const tools = {
+  lookup: toolDefinition({
+    name: 'lookup',
+    description: 'Look up a fact',
+    inputSchema: z.object({ q: z.string() }),
+  }).server(lookup),
+  remove: toolDefinition({
+    name: 'remove',
+    description: 'Remove a file',
+    needsApproval: true,
+    inputSchema: z.object({ path: z.string() }),
+  }).server(async () => 'removed'),
+  writeFile: toolDefinition({
+    name: 'write_file',
+    description: 'Write a file',
+    inputSchema: z.object({ path: z.string() }),
+  }).server(async () => 'written'),
+  notionSearch: toolDefinition({
+    name: 'notion_search',
+    description: 'Search Notion',
+    inputSchema: z.object({ query: z.string() }),
+  }).server(notionSearch),
+  askUser: toolDefinition({
+    name: 'ask_user',
+    description: 'Ask the user in the browser',
+    inputSchema: z.object({}),
+  }).client(),
+}
+
+// A tool plugin that marks write_file as an edit, like workspaceTools does.
+const writes = definePlugin({
+  name: 'test/writes',
+  setup: () => ({
+    tools: [tools.writeFile],
+    contribute: [
+      PermissionRules.item({
+        tool: 'write_file',
+        decision: 'ask',
+        kind: 'edit',
+      }),
+    ],
+  }),
+})
+// A connector whose tool appears at run time.
+const notion = definePlugin({
+  name: 'test/notion',
+  setup: () => ({ discoverTools: () => [tools.notionSearch] }),
+})
+
+describe('codeMode', () => {
+  it('moves safe tools, including discovered ones, behind execute_typescript', async () => {
+    const { driver, seen } = fakeDriver()
+    const { adapter, calls } = scripted([
+      codeTurn('return { a: await external_lookup({ q: "x" }) }'),
+      textTurn('done'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/code-mode',
+        adapter,
+        tools: [tools.lookup, tools.remove, tools.askUser],
+        plugins: () => [writes, notion, codeMode({ driver })],
+      }),
+      { threadId: 't' },
+    )
+    const turn = await session.prompt('look it up')
+    expect(turn.text).toBe('done')
+
+    const names = calls[0].tools.map((tool: { name: string }) => tool.name)
+    expect(names).toEqual([
+      'remove',
+      'ask_user',
+      'write_file',
+      'execute_typescript',
+    ])
+    const prompts = JSON.stringify(calls[0].systemPrompts)
+    expect(prompts).toContain('external_lookup')
+    expect(prompts).toContain('external_notion_search')
+    expect(prompts).not.toContain('external_write_file')
+
+    expect(seen[0]).toEqual(['external_lookup', 'external_notion_search'])
+    expect(lookup).toHaveBeenCalledTimes(1)
+    expect(notionSearch).toHaveBeenCalledTimes(1)
+    expect(JSON.stringify(calls[1].messages)).toContain('page')
+    await host.close()
+  })
+
+  it('uses include to pick the tools, and leaves the list alone when none match', async () => {
+    const { driver } = fakeDriver()
+    const { adapter, calls } = scripted([textTurn('one'), textTurn('two')])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const picked = await host.open(
+      defineHarness({
+        name: 'test/code-mode-include',
+        adapter,
+        tools: [tools.lookup, tools.remove],
+        plugins: () => [
+          codeMode({ driver, include: (tool) => tool.name === 'remove' }),
+        ],
+      }),
+      { threadId: 'picked' },
+    )
+    await picked.prompt('hi')
+    expect(calls[0].tools.map((tool: { name: string }) => tool.name)).toEqual([
+      'lookup',
+      'execute_typescript',
+    ])
+
+    const none = await host.open(
+      defineHarness({
+        name: 'test/code-mode-none',
+        adapter,
+        tools: [tools.remove],
+        plugins: () => [codeMode({ driver })],
+      }),
+      { threadId: 'none' },
+    )
+    await none.prompt('hi')
+    expect(calls[1].tools.map((tool: { name: string }) => tool.name)).toEqual([
+      'remove',
+    ])
+    expect(JSON.stringify(calls[1].systemPrompts ?? [])).not.toContain(
+      'execute_typescript',
+    )
+    await host.close()
+  })
+
+  it('gives tools with names that are not identifiers a safe name', async () => {
+    const seen: Array<Array<string>> = []
+    const driver: IsolateDriver = {
+      createContext: async ({ bindings }) => {
+        seen.push(Object.keys(bindings).sort())
+        return {
+          execute: async <T>(): Promise<ExecutionResult<T>> => {
+            const binding = bindings['external_web_search'] as ToolBinding
+            const value: unknown = await binding.execute({})
+            // The caller picks T. This stand-in returns the one result.
+            return { success: true, value: value as T, logs: [] }
+          },
+          dispose: async () => {},
+        }
+      },
+    }
+    const named = (name: string, reply: string) =>
+      toolDefinition({
+        name,
+        description: 'A tool',
+        inputSchema: z.object({}),
+      }).server(async () => reply)
+    const { adapter, calls } = scripted([codeTurn('return 1'), textTurn('ok')])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/code-mode-names',
+        adapter,
+        tools: [
+          named('web-search', 'from web-search'),
+          named('web_search', 'from web_search'),
+          named('2fa', 'code'),
+        ],
+        plugins: () => [codeMode({ driver })],
+      }),
+      { threadId: 't' },
+    )
+    await session.prompt('search')
+    // web_search clashes with web-search after the rename, so it stays direct.
+    expect(calls[0].tools.map((tool: { name: string }) => tool.name)).toEqual([
+      'web_search',
+      'execute_typescript',
+    ])
+    expect(seen[0]).toEqual(['external__2fa', 'external_web_search'])
+    expect(JSON.stringify(calls[1].messages)).toContain('from web-search')
+    await host.close()
+  })
+})
diff --git a/packages/ai-code-mode/vite.config.ts b/packages/ai-code-mode/vite.config.ts
index 77bcc2e60b..525f4daf73 100644
--- a/packages/ai-code-mode/vite.config.ts
+++ b/packages/ai-code-mode/vite.config.ts
@@ -29,7 +29,7 @@ const config = defineConfig({
 export default mergeConfig(
   config,
   tanstackViteConfig({
-    entry: ['./src/index.ts'],
+    entry: ['./src/index.ts', './src/harness.ts'],
     srcDir: './src',
     cjs: false,
   }),
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index 9e5b6b473d..01e56f91f9 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -21,6 +21,14 @@ export type {
 } from './plugins'
 
 export { createExtensionPoint, createPluginEvent } from './extensions'
+// Portable (no Node imports), so edge-safe plugins such as code mode can read
+// the permission rules without the Node-only `./plugins` entry.
+export { PermissionRules, decidePermission } from './first-party/permissions'
+export type {
+  PermissionDecision,
+  PermissionMode,
+  PermissionRule,
+} from './first-party/permissions'
 export type { ExtensionItem, ExtensionPoint, PluginEvent } from './extensions'
 
 export { checkConfigValue, configOption } from './config'
diff --git a/packages/ai-harness/src/plugins.ts b/packages/ai-harness/src/plugins.ts
index 21cce825ce..92b39e4367 100644
--- a/packages/ai-harness/src/plugins.ts
+++ b/packages/ai-harness/src/plugins.ts
@@ -68,6 +68,15 @@ export interface PluginContributions {
    * name that another tool already uses is skipped.
    */
   discoverTools?: () => ReadonlyArray<AnyTool> | Promise<ReadonlyArray<AnyTool>>
+  /**
+   * Change the tool list of a turn: every tool the model gets, after
+   * `discoverTools`. Return the new list. Runs before prompts resolve, so a
+   * prompt `text()` can describe the tools this returned. Code mode uses it to
+   * move tools behind `execute_typescript`.
+   */
+  prepareTools?: (
+    tools: ReadonlyArray<AnyTool>,
+  ) => ReadonlyArray<AnyTool> | Promise<ReadonlyArray<AnyTool>>
 }
 
 /** Plugin state that survives restarts, stored in the metadata store. */
@@ -248,6 +257,10 @@ export interface MountedPlugins {
     discover: () => ReadonlyArray<AnyTool> | Promise<ReadonlyArray<AnyTool>>
     owner: string
   }>
+  preparers: Array<{
+    prepare: NonNullable<PluginContributions['prepareTools']>
+    owner: string
+  }>
   /** Who contributed what, for `session.inspect()`. */
   owners: {
     plugins: Array<{
@@ -431,6 +444,7 @@ export async function mountPlugins(
   }
   const adapters: Array<() => AnyTextAdapter | undefined> = []
   const discoverers: MountedPlugins['discoverers'] = []
+  const preparers: MountedPlugins['preparers'] = []
   const services = env.services ?? NO_SERVICES
 
   try {
@@ -567,6 +581,12 @@ export async function mountPlugins(
           owner: plugin.name,
         })
       }
+      if (contributions.prepareTools) {
+        preparers.push({
+          prepare: contributions.prepareTools,
+          owner: plugin.name,
+        })
+      }
       for (const agent of contributions.agents ?? []) {
         env.registry.add(agent, plugin.name)
       }
@@ -620,6 +640,7 @@ export async function mountPlugins(
     extensions,
     adapters,
     discoverers,
+    preparers,
     owners: {
       plugins: plugins.map((plugin) => ({
         name: plugin.name,
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index af056aa2b5..2c2352679b 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -927,17 +927,45 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           found.push(tool)
         }
       } catch (error) {
-        operation.publish(
-          customEvent('harness.plugin.warning', {
-            plugin: owner,
-            message: error instanceof Error ? error.message : String(error),
-          }),
-        )
+        this.warn(operation, owner, error)
       }
     }
     return found
   }
 
+  /**
+   * Let each plugin change the tool list of this turn, in plugin order. A
+   * plugin that fails leaves the list as it was, with a warning event.
+   */
+  private async prepareTools(
+    preparers: MountedPlugins['preparers'],
+    tools: Array<AnyTool>,
+    operation: OperationImpl<ChatTurnResult>,
+  ): Promise<Array<AnyTool>> {
+    let prepared = tools
+    for (const { prepare, owner } of preparers) {
+      try {
+        prepared = [...(await prepare(prepared))]
+      } catch (error) {
+        this.warn(operation, owner, error)
+      }
+    }
+    return prepared
+  }
+
+  private warn(
+    operation: OperationImpl<ChatTurnResult>,
+    plugin: string,
+    error: unknown,
+  ) {
+    operation.publish(
+      customEvent('harness.plugin.warning', {
+        plugin,
+        message: error instanceof Error ? error.message : String(error),
+      }),
+    )
+  }
+
   /** Middleware that adds queued steer messages before each model call. */
   private steering(): AnyChatMiddleware {
     return {
@@ -1059,6 +1087,12 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         new Set(staticTools.map((tool) => tool.name)),
         operation,
       )
+      // Before the chat() options below: prompts may describe these tools.
+      const tools = await this.prepareTools(
+        [...(session?.preparers ?? []), ...(runPlugins?.preparers ?? [])],
+        [...staticTools, ...discovered],
+        operation,
+      )
       const stream = chat({
         adapter: picked ?? this.harness.adapter,
         messages:
@@ -1071,7 +1105,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             .map(resolvePrompt)
             .filter((prompt) => prompt !== ''),
         ],
-        tools: [...staticTools, ...discovered],
+        tools,
         middleware: [
           ...bridges,
           withPersistence(this.persistence),
diff --git a/packages/ai-harness/tests/prepare-tools.test.ts b/packages/ai-harness/tests/prepare-tools.test.ts
new file mode 100644
index 0000000000..d12fe94c02
--- /dev/null
+++ b/packages/ai-harness/tests/prepare-tools.test.ts
@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { EventType, toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness, definePlugin } from '../src'
+import { mockAdapter, text } from './helpers'
+import type { SessionEvent } from '../src'
+
+const tool = (name: string) =>
+  toolDefinition({
+    name,
+    description: `The ${name} tool`,
+    inputSchema: z.object({}),
+  }).server(async () => name)
+
+describe('prepareTools', () => {
+  it('lets plugins rewrite the tool list in order, before prompts resolve', async () => {
+    let described = ''
+    const bundle = definePlugin({
+      name: 'test/bundle',
+      setup: () => ({
+        prompts: [{ id: 'test/bundle', text: () => described }],
+        prepareTools: (tools) => {
+          described = `Bundled: ${tools.map((entry) => entry.name).join(', ')}`
+          return [tool('bundled')]
+        },
+      }),
+    })
+    const extra = definePlugin({
+      name: 'test/extra',
+      setup: () => ({
+        prepareTools: async (tools) => [...tools, tool('extra')],
+      }),
+    })
+    const broken = definePlugin({
+      name: 'test/broken',
+      setup: () => ({
+        prepareTools: () => {
+          throw new Error('cannot prepare')
+        },
+      }),
+    })
+    const { adapter, calls } = mockAdapter([() => text('ok')])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/prepare',
+        adapter,
+        tools: [tool('a'), tool('b')],
+        plugins: () => [bundle, broken, extra],
+      }),
+      { threadId: 't' },
+    )
+    const seen: Array<SessionEvent> = []
+    const controller = new AbortController()
+    const reading = (async () => {
+      for await (const entry of session.events({ signal: controller.signal }))
+        seen.push(entry)
+    })()
+
+    await session.prompt('go')
+    expect(calls[0].tools.map((entry: { name: string }) => entry.name)).toEqual(
+      ['bundled', 'extra'],
+    )
+    expect(JSON.stringify(calls[0].systemPrompts)).toContain('Bundled: a, b')
+
+    controller.abort()
+    await reading
+    expect(
+      seen.find(
+        (entry) =>
+          entry.event.type === EventType.CUSTOM &&
+          entry.event.name === 'harness.plugin.warning',
+      )?.event,
+    ).toMatchObject({
+      value: { plugin: 'test/broken', message: 'cannot prepare' },
+    })
+    await host.close()
+  })
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ea2077b4b1..4bec7ae9ab 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -185,6 +185,9 @@ importers:
       '@tanstack/ai-anthropic':
         specifier: workspace:*
         version: link:../../packages/ai-anthropic
+      '@tanstack/ai-code-mode':
+        specifier: workspace:*
+        version: link:../../packages/ai-code-mode
       '@tanstack/ai-dashboard':
         specifier: workspace:*
         version: link:../../packages/ai-dashboard
@@ -197,6 +200,9 @@ importers:
       '@tanstack/ai-harness-cli':
         specifier: workspace:*
         version: link:../../packages/ai-harness-cli
+      '@tanstack/ai-isolate-quickjs':
+        specifier: workspace:*
+        version: link:../../packages/ai-isolate-quickjs
       '@tanstack/ai-mcp':
         specifier: workspace:*
         version: link:../../packages/ai-mcp
@@ -2254,6 +2260,12 @@ importers:
       '@tanstack/ai':
         specifier: workspace:*
         version: link:../ai
+      '@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)

From a725cf5004341a8cbfcc868b4d685dc904ce05fa Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 15:26:40 +0200
Subject: [PATCH 020/286] fix(ai-harness): deliver session events published
 while a reader is busy

---
 packages/ai-harness/src/feed.ts        |  3 ++
 packages/ai-harness/tests/feed.test.ts | 51 ++++++++++++++++++++++++++
 2 files changed, 54 insertions(+)
 create mode 100644 packages/ai-harness/tests/feed.test.ts

diff --git a/packages/ai-harness/src/feed.ts b/packages/ai-harness/src/feed.ts
index 0d9e031cfb..e5f8b63081 100644
--- a/packages/ai-harness/src/feed.ts
+++ b/packages/ai-harness/src/feed.ts
@@ -72,6 +72,9 @@ export class SessionFeed {
         for (const entry of rest) yield entry
         return
       }
+      // Events published while the reader handled `next` woke nobody, so
+      // scan again before waiting. An empty scan moves `after` to the head.
+      if (next.length > 0) continue
       await this.waitForNext(options.signal)
     }
   }
diff --git a/packages/ai-harness/tests/feed.test.ts b/packages/ai-harness/tests/feed.test.ts
new file mode 100644
index 0000000000..c8ffa35682
--- /dev/null
+++ b/packages/ai-harness/tests/feed.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest'
+import { EventType } from '@tanstack/ai'
+import { SessionFeed } from '../src/feed'
+
+const custom = (name: string) => ({
+  type: EventType.CUSTOM,
+  name,
+  value: {},
+  timestamp: Date.now(),
+})
+
+describe('SessionFeed', () => {
+  it('delivers events published while a reader handles earlier ones', async () => {
+    const feed = new SessionFeed()
+    const controller = new AbortController()
+    const seen: Array<string> = []
+    const reading = (async () => {
+      for await (const entry of feed.read({ signal: controller.signal })) {
+        seen.push(entry.event.type === EventType.CUSTOM ? entry.event.name : '')
+        // Two more events arrive while this one is handled, and nothing after.
+        if (seen.length === 1) {
+          await Promise.resolve()
+          feed.publish('op', custom('second'))
+          feed.publish('op', custom('third'))
+        }
+      }
+    })()
+    feed.publish('op', custom('first'))
+    await new Promise((resolve) => setTimeout(resolve, 20))
+    expect(seen).toEqual(['first', 'second', 'third'])
+    controller.abort()
+    await reading
+  })
+
+  it('skips filtered events and replays from a cursor', async () => {
+    const feed = new SessionFeed()
+    feed.publish('a', custom('one'))
+    feed.publish('b', custom('two'))
+    feed.publish('a', custom('three'))
+    feed.close()
+    const names: Array<string> = []
+    for await (const entry of feed.read({
+      from: '1',
+      filter: (item) => item.operationId === 'a',
+    })) {
+      names.push(entry.event.type === EventType.CUSTOM ? entry.event.name : '')
+    }
+    expect(names).toEqual(['three'])
+    expect(feed.head()).toBe('3')
+  })
+})

From f9a2cc6bd757d90613b1bfd53dbd04920dc5d3a0 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 15:28:38 +0200
Subject: [PATCH 021/286] test(ai-harness): type the feed test events

---
 packages/ai-harness/tests/feed.test.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/ai-harness/tests/feed.test.ts b/packages/ai-harness/tests/feed.test.ts
index c8ffa35682..ec2032bcab 100644
--- a/packages/ai-harness/tests/feed.test.ts
+++ b/packages/ai-harness/tests/feed.test.ts
@@ -1,8 +1,9 @@
 import { describe, expect, it } from 'vitest'
 import { EventType } from '@tanstack/ai'
 import { SessionFeed } from '../src/feed'
+import type { StreamChunk } from '@tanstack/ai'
 
-const custom = (name: string) => ({
+const custom = (name: string): StreamChunk => ({
   type: EventType.CUSTOM,
   name,
   value: {},

From 23158adb660283d22e411d7f9ecd9b8a78798545 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 15:29:11 +0200
Subject: [PATCH 022/286] fix(ai-harness): compact reads text content parts;
 cover OAuth, workspace tools, and plugin session APIs

---
 .../src/first-party/session-tools.ts          |   4 +-
 packages/ai-harness/tests/oauth-edges.test.ts | 334 ++++++++++
 .../ai-harness/tests/session-plugins.test.ts  | 595 ++++++++++++++++++
 .../ai-harness/tests/workspace-tools.test.ts  | 141 +++++
 4 files changed, 1071 insertions(+), 3 deletions(-)
 create mode 100644 packages/ai-harness/tests/oauth-edges.test.ts
 create mode 100644 packages/ai-harness/tests/session-plugins.test.ts
 create mode 100644 packages/ai-harness/tests/workspace-tools.test.ts

diff --git a/packages/ai-harness/src/first-party/session-tools.ts b/packages/ai-harness/src/first-party/session-tools.ts
index 02dbe6fb6c..219bfe5180 100644
--- a/packages/ai-harness/src/first-party/session-tools.ts
+++ b/packages/ai-harness/src/first-party/session-tools.ts
@@ -10,9 +10,7 @@ function textOf(message: ModelMessage): string {
   if (typeof message.content === 'string') return message.content
   if (Array.isArray(message.content)) {
     return message.content
-      .map((part) =>
-        'text' in part && typeof part.text === 'string' ? part.text : '',
-      )
+      .map((part) => (part.type === 'text' ? part.content : ''))
       .join('')
   }
   return ''
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..825b69f045
--- /dev/null
+++ b/packages/ai-harness/tests/oauth-edges.test.ts
@@ -0,0 +1,334 @@
+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',
+      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(
+      { threadId: 't1', userId: 'u1' },
+      'svc',
+      {
+        type: 'oauth',
+        accessToken: 'old',
+        refreshToken: 'r',
+        expiresAt: Date.now() - 1,
+      },
+    )
+    await persistence.stores.credentials.set(
+      { threadId: 't2', userId: 'u2' },
+      'svc',
+      {
+        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(
+        { threadId: 't1', userId: 'u1' },
+        '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({ threadId: 't' }, 'svc'),
+    ).toMatchObject({ accessToken: 'loop-token' })
+    expect(await session.command('disconnect:svc')).toBe(
+      'Disconnected from Service.',
+    )
+    expect(
+      await persistence.stores.credentials.get({ threadId: 't' }, '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/session-plugins.test.ts b/packages/ai-harness/tests/session-plugins.test.ts
new file mode 100644
index 0000000000..cafc4d4b2c
--- /dev/null
+++ b/packages/ai-harness/tests/session-plugins.test.ts
@@ -0,0 +1,595 @@
+import { mkdtemp, rm, writeFile, mkdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { EventType, toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  checkConfigValue,
+  configOption,
+  createHarnessHost,
+  createPluginEvent,
+  defineCommand,
+  defineHarness,
+  definePlugin,
+} from '../src'
+import {
+  compact,
+  fileCommands,
+  modelPicker,
+  projectInstructions,
+  todos,
+  usage,
+} from '../src/first-party'
+import { gate, mockAdapter, text, toolCall } from './helpers'
+import type { SessionEvent } from '../src'
+
+const settings = definePlugin({
+  name: 'test/settings',
+  setup: () => ({
+    config: {
+      level: configOption.select({ options: ['low', 'high'], default: 'low' }),
+      verbose: configOption.boolean({ default: false }),
+      label: configOption.text({ default: 'none' }),
+      retries: configOption.number({ default: 1, min: 0, max: 5 }),
+    },
+  }),
+})
+
+describe('config values', () => {
+  it('checks every option type and its limits', () => {
+    const number = configOption.number({ default: 1, min: 0, max: 5 })
+    expect(() => checkConfigValue('n', number, 'x')).toThrow('a number')
+    expect(() => checkConfigValue('n', number, Number.NaN)).toThrow('a number')
+    expect(() => checkConfigValue('n', number, -1)).toThrow('>= 0')
+    expect(() => checkConfigValue('n', number, 6)).toThrow('<= 5')
+    expect(checkConfigValue('n', configOption.number({ default: 1 }), 99)).toBe(
+      99,
+    )
+    expect(() =>
+      checkConfigValue('b', configOption.boolean({ default: false }), 'yes'),
+    ).toThrow('true or false')
+    expect(() =>
+      checkConfigValue('t', configOption.text({ default: '' }), 1),
+    ).toThrow('expects text')
+    expect(() => configOption.select({ options: ['a'], default: 'b' })).toThrow(
+      'is not an option',
+    )
+  })
+
+  it('rejects unknown keys and bad values, and loads saved values in a new session', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.metadata.set('harness:config', 't', {
+      verbose: 'not a boolean',
+      gone: 'old key',
+    })
+    const { adapter } = mockAdapter([])
+    const host = createHarnessHost({ persistence })
+    const harness = defineHarness({
+      name: 'test/config',
+      adapter,
+      plugins: () => [settings],
+    })
+    const session = await host.open(harness, { threadId: 't' })
+    // The saved values were invalid or unknown, so the defaults apply.
+    expect(session.config().verbose?.value).toBe(false)
+    expect(await session.setConfig('missing', 1)).toMatchObject({
+      status: 'rejected',
+      reason: 'unknown_config',
+    })
+    expect(await session.setConfig('retries', 9)).toMatchObject({
+      status: 'rejected',
+      reason: expect.stringContaining('<= 5'),
+    })
+    expect((await session.setConfig('level', 'high')).status).toBe('accepted')
+    expect((await session.setConfig('label', 'mine')).status).toBe('accepted')
+    await host.close()
+
+    const again = createHarnessHost({ persistence })
+    const reopened = await again.open(harness, { threadId: 't' })
+    expect(reopened.config()).toMatchObject({
+      level: { value: 'high', owner: 'test/settings' },
+      label: { value: 'mine' },
+      retries: { value: 1 },
+    })
+    await again.close()
+  })
+})
+
+describe('commands', () => {
+  it('lists commands with input schemas and reports failures', async () => {
+    const release = gate()
+    const tools = definePlugin({
+      name: 'test/commands',
+      setup: () => ({
+        commands: {
+          greet: defineCommand({
+            description: 'Greet someone',
+            input: z.object({ name: z.string() }),
+            run: (input) => `hello ${input.name}`,
+          }),
+          boom: defineCommand({
+            description: 'Throws',
+            run: () => {
+              throw new Error('command broke')
+            },
+          }),
+          wait: defineCommand({
+            description: 'Waits until stopped',
+            run: (_input, ctx) =>
+              new Promise((_resolve, reject) => {
+                ctx.signal.addEventListener('abort', () =>
+                  reject(new Error('stopped')),
+                )
+                release.open()
+              }),
+          }),
+        },
+      }),
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/cmds',
+        adapter: mockAdapter([]).adapter,
+        plugins: () => [tools],
+      }),
+      { threadId: 't' },
+    )
+    const listed = session.commands()
+    expect(listed.find((command) => command.name === 'greet')).toMatchObject({
+      owner: 'test/commands',
+      input: { type: 'object' },
+    })
+    expect(
+      listed.find((command) => command.name === 'boom')?.input,
+    ).toBeUndefined()
+
+    expect(await session.command('greet', { name: 'Ada' })).toBe('hello Ada')
+    await expect(session.command('greet', { name: 1 })).rejects.toThrow(
+      'Input validation failed for command greet',
+    )
+    await expect(session.command('nope')).rejects.toThrow(
+      'Unknown command: nope',
+    )
+    await expect(session.command('boom')).rejects.toThrow('command broke')
+
+    const waiting = session.command('wait')
+    await release.opened
+    await waiting.cancel()
+    await waiting.then(
+      () => undefined,
+      () => undefined,
+    )
+    expect(waiting.status()).toBe('cancelled')
+    await host.close()
+  })
+})
+
+describe('questions', () => {
+  it('asks with a schema, checks answers, and rejects open questions on close', async () => {
+    const asker = definePlugin({
+      name: 'test/asker',
+      setup: (ctx) => ({
+        commands: {
+          pick: defineCommand({
+            description: 'Pick a number',
+            run: async () => {
+              const answer = await ctx.session.ask({
+                message: 'How many?',
+                schema: z.object({ count: z.number() }),
+              })
+              return answer.count * 2
+            },
+          }),
+          open: defineCommand({
+            description: 'Asks and never gets an answer',
+            run: () => ctx.session.ask({ message: 'Still there?' }),
+          }),
+        },
+      }),
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/questions',
+        adapter: mockAdapter([]).adapter,
+        plugins: () => [asker],
+      }),
+      { threadId: 't' },
+    )
+    const picking = session.command('pick')
+    await vi.waitFor(() =>
+      expect(session.snapshot().pendingQuestions).toHaveLength(1),
+    )
+    const [question] = session.snapshot().pendingQuestions
+    expect(question).toMatchObject({
+      message: 'How many?',
+      schema: { type: 'object' },
+    })
+    expect(await session.answer('q-unknown', 1)).toMatchObject({
+      status: 'rejected',
+      reason: 'unknown_question',
+    })
+    expect(
+      await session.answer(question?.questionId ?? '', { count: 'two' }),
+    ).toMatchObject({
+      status: 'rejected',
+      reason: expect.stringContaining('Invalid answer'),
+    })
+    expect(
+      (await session.answer(question?.questionId ?? '', { count: 2 })).status,
+    ).toBe('accepted')
+    expect(await picking).toBe(4)
+
+    const open = session.command('open')
+    await vi.waitFor(() =>
+      expect(session.snapshot().pendingQuestions).toHaveLength(1),
+    )
+    await session.close()
+    await expect(open).rejects.toThrow('Session closed.')
+    await host.close()
+  })
+})
+
+describe('plugin state and events', () => {
+  const counter = createPluginEvent<number>('test/count')
+
+  function statePlugin(onValue: (value: number) => void) {
+    return definePlugin({
+      name: 'test/state',
+      setup: (ctx) => {
+        const state = ctx.state({ count: 0 })
+        const stop = ctx.on(counter, () => {
+          throw new Error('a listener that throws is ignored')
+        })
+        ctx.on(counter, onValue)
+        return {
+          commands: {
+            bump: defineCommand({
+              description: 'Add one',
+              run: async () => {
+                const next = await state.update((value) => ({
+                  count: value.count + 1,
+                }))
+                ctx.emit(counter, next.count)
+                stop()
+                return (await state.get()).count
+              },
+            }),
+          },
+        }
+      },
+    })
+  }
+
+  it('keeps state with a plain metadata store and with none', async () => {
+    const base = memoryPersistence()
+    const plain = {
+      ...base,
+      stores: {
+        ...base.stores,
+        metadata: {
+          get: (namespace: string, key: string) =>
+            base.stores.metadata.get(namespace, key),
+          set: (namespace: string, key: string, value: unknown) =>
+            base.stores.metadata.set(namespace, key, value),
+        },
+      },
+    }
+    const none = { ...base, stores: { ...base.stores, metadata: undefined } }
+    for (const persistence of [plain, none]) {
+      const seen: Array<number> = []
+      const host = createHarnessHost({ persistence: persistence as never })
+      const session = await host.open(
+        defineHarness({
+          name: 'test/state-store',
+          adapter: mockAdapter([]).adapter,
+          plugins: () => [statePlugin((value) => seen.push(value))],
+        }),
+        { threadId: 't' },
+      )
+      expect(await session.command('bump')).toBe(1)
+      expect(await session.command('bump')).toBe(2)
+      expect(seen).toEqual([1, 2])
+      await host.close()
+    }
+  })
+
+  it('gives up after five conflicting updates', async () => {
+    const base = memoryPersistence()
+    const conflicting = {
+      ...base,
+      stores: {
+        ...base.stores,
+        metadata: {
+          get: async () => null,
+          set: async () => {},
+          getVersioned: async () => ({ value: { count: 0 }, revision: 'r1' }),
+          setIf: async () => ({ ok: false }),
+        },
+      },
+    }
+    const host = createHarnessHost({ persistence: conflicting as never })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/state-conflict',
+        adapter: mockAdapter([]).adapter,
+        plugins: () => [statePlugin(() => {})],
+      }),
+      { threadId: 't' },
+    )
+    await expect(session.command('bump')).rejects.toThrow(
+      'state update conflicted 5 times',
+    )
+    await host.close()
+  })
+})
+
+describe('the plugin session API and inspect', () => {
+  it('reads and replaces the transcript, prompts, and describes the session', async () => {
+    let api: any
+    const probe = definePlugin({
+      name: 'test/probe',
+      setup: (ctx) => {
+        api = ctx.session
+        return {
+          tools: [
+            toolDefinition({ name: 'ping', description: 'Ping' }).server(
+              async () => 'pong',
+            ),
+          ],
+          prompts: ['Be brief.'],
+        }
+      },
+    })
+    const { adapter, calls } = mockAdapter([
+      () => text('first'),
+      () => text('from the plugin prompt'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/api',
+        adapter,
+        plugins: () => [probe, settings],
+      }),
+      { threadId: 't', principal: { id: 'u1' } },
+    )
+    expect(api.threadId).toBe('t')
+    expect(api.principal).toEqual({ id: 'u1' })
+    await session.prompt('hello')
+    expect(
+      (await api.transcript()).map((m: { content: string }) => m.content),
+    ).toEqual(['hello', 'first'])
+    await api.replaceTranscript([{ role: 'user', content: 'replaced' }])
+    expect(await api.transcript()).toEqual([
+      { role: 'user', content: 'replaced' },
+    ])
+    api.prompt('queued by a plugin')
+    await vi.waitFor(() => expect(calls).toHaveLength(2))
+    await vi.waitFor(() => expect(api.snapshot().status).toBe('idle'))
+    expect(JSON.stringify(calls[1].messages)).toContain('replaced')
+
+    const inspected = session.inspect()
+    expect(inspected.plugins.map((plugin) => plugin.name)).toEqual([
+      'test/probe',
+      'test/settings',
+    ])
+    expect(inspected.tools).toEqual(
+      expect.arrayContaining([expect.objectContaining({ name: 'ping' })]),
+    )
+    expect(inspected.config.map((entry) => entry.key)).toContain('retries')
+    await host.close()
+  })
+})
+
+describe('first-party plugin edges', () => {
+  let dir: string
+  beforeAll(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'harness-files-'))
+    await mkdir(join(dir, 'commands'))
+    await writeFile(
+      join(dir, 'commands', 'review.md'),
+      '---\ndescription: Review a file\n---\nReview $ARGUMENTS carefully.',
+    )
+    await writeFile(join(dir, 'commands', 'plain.md'), 'Say hi to $ARGUMENTS.')
+    await writeFile(join(dir, 'commands', 'skip.txt'), 'not a command')
+    await writeFile(join(dir, 'RULES.md'), 'Use tabs.')
+    await writeFile(join(dir, 'EMPTY.md'), '   ')
+  })
+  afterAll(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it('turns markdown files into commands and reads chosen instruction files', async () => {
+    const { adapter, calls } = mockAdapter([
+      () => text('a'),
+      () => text('b'),
+      () => text('c'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/files',
+        adapter,
+        plugins: () => [
+          fileCommands({ dir: join(dir, 'commands') }),
+          projectInstructions({
+            root: dir,
+            files: ['RULES.md', 'EMPTY.md', 'NONE.md'],
+          }),
+        ],
+      }),
+      { threadId: 't' },
+    )
+    const described = session.commands()
+    expect(
+      described.map((command) => [command.name, command.description]).sort(),
+    ).toEqual([
+      ['plain', 'Run plain.md'],
+      ['review', 'Review a file'],
+    ])
+    expect(await session.command('review', 'src/a.ts')).toBe('Sent /review.')
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    await vi.waitFor(() => expect(session.snapshot().status).toBe('idle'))
+    await session.command('plain', { who: 'Ada' })
+    await vi.waitFor(() => expect(calls).toHaveLength(2))
+    await vi.waitFor(() => expect(session.snapshot().status).toBe('idle'))
+    await session.command('plain')
+    await vi.waitFor(() => expect(calls).toHaveLength(3))
+
+    // A missing folder gives no commands.
+    const empty = await host.open(
+      defineHarness({
+        name: 'test/files-missing',
+        adapter,
+        plugins: () => [fileCommands({ dir: join(dir, 'missing') })],
+      }),
+      { threadId: 'empty' },
+    )
+    expect(empty.commands()).toEqual([])
+
+    const said = calls.map((call) => JSON.stringify(call.messages.at(-1)))
+    expect(said[0]).toContain('Review src/a.ts carefully.')
+    expect(said[1]).toContain('Say hi to {\\"who\\":\\"Ada\\"}.')
+    expect(said[2]).toContain('Say hi to .')
+    const prompts = JSON.stringify(calls[0].systemPrompts)
+    expect(prompts).toContain('Project instructions from RULES.md')
+    expect(prompts).not.toContain('EMPTY.md')
+    await host.close()
+  })
+
+  it('checks todo input and shows an empty list', async () => {
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('todo_write', { todos: [{ text: 'x', status: 'later' }] }),
+      () => text('bad input'),
+      () => toolCall('todo_write', { todos: [] }, 'call-2'),
+      () => text('cleared'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({ name: 'test/todos', adapter, plugins: () => [todos()] }),
+      { threadId: 't' },
+    )
+    await session.prompt('plan')
+    expect(JSON.stringify(calls[1].messages)).toContain(
+      'Each todo needs text and a status.',
+    )
+    await session.prompt('clear')
+    expect(JSON.stringify(calls[3].messages)).toContain(
+      'The todo list is empty.',
+    )
+    expect(await session.command('todos')).toBe('The todo list is empty.')
+    await host.close()
+  })
+
+  it('needs a model choice and answers every /model form', async () => {
+    expect(() => modelPicker({ choices: {} })).toThrow('at least one choice')
+    const fast = mockAdapter([]).adapter
+    const smart = mockAdapter([]).adapter
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/models',
+        adapter: smart,
+        plugins: () => [modelPicker({ choices: { smart, fast } })],
+      }),
+      { threadId: 't' },
+    )
+    expect(await session.command('model')).toBe(
+      'Model: smart. Choices: smart, fast.',
+    )
+    expect(await session.command('model', 'slow')).toBe(
+      'Unknown model "slow". Choices: smart, fast.',
+    )
+    expect(await session.command('model', { name: 'fast' })).toBe(
+      'Model: fast. It applies at the next turn.',
+    )
+    await host.close()
+  })
+
+  it('keeps short conversations, keeps the last messages, and counts usage', async () => {
+    const summarizer = mockAdapter([() => text('the summary')])
+    const withUsage = (content: string) =>
+      text(content).map((chunk) =>
+        chunk.type === EventType.RUN_FINISHED
+          ? {
+              ...chunk,
+              usage: { promptTokens: 3, completionTokens: 2, totalTokens: 5 },
+            }
+          : chunk,
+      )
+    const { adapter } = mockAdapter([
+      () => withUsage('one'),
+      () => withUsage('two'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/compact',
+        adapter,
+        plugins: () => [
+          compact({ adapter: summarizer.adapter, keepLast: 1 }),
+          usage(),
+        ],
+      }),
+      { threadId: 't' },
+    )
+    expect(await session.command('compact')).toBe(
+      'The conversation is already short.',
+    )
+    await session.prompt([{ type: 'text', content: 'first question' }] as never)
+    await session.prompt('second question')
+    expect(await session.command('compact')).toBe(
+      'Compacted 3 messages into a summary.',
+    )
+    expect(JSON.stringify(summarizer.calls[0].messages)).toContain(
+      'first question',
+    )
+    expect(await session.command('usage')).toBe(
+      '2 model calls, 6 input tokens, 4 output tokens, 10 total.',
+    )
+    await host.close()
+  })
+})
+
+describe('session events', () => {
+  it('publishes config changes', async () => {
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/events',
+        adapter: mockAdapter([]).adapter,
+        plugins: () => [settings],
+      }),
+      { threadId: 't' },
+    )
+    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.setConfig('verbose', true)
+    await vi.waitFor(() =>
+      expect(
+        seen.some(
+          (entry) =>
+            entry.event.type === EventType.CUSTOM &&
+            entry.event.value !== null &&
+            typeof entry.event.value === 'object' &&
+            'key' in entry.event.value &&
+            entry.event.value.key === 'verbose',
+        ),
+      ).toBe(true),
+    )
+    controller.abort()
+    await reading
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/workspace-tools.test.ts b/packages/ai-harness/tests/workspace-tools.test.ts
new file mode 100644
index 0000000000..c3e1f71f7f
--- /dev/null
+++ b/packages/ai-harness/tests/workspace-tools.test.ts
@@ -0,0 +1,141 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { workspaceTools } from '../src/first-party'
+import type { AnyTool } from '@tanstack/ai'
+
+let root: string
+let tools: Map<string, AnyTool>
+
+const run = (name: string, args: unknown): Promise<string> => {
+  const tool = tools.get(name)
+  if (!tool?.execute) throw new Error(`No tool ${name}`)
+  return Promise.resolve(tool.execute(args))
+}
+
+beforeAll(async () => {
+  root = await mkdtemp(join(tmpdir(), 'harness-workspace-'))
+  await mkdir(join(root, 'src', 'deep'), { recursive: true })
+  await mkdir(join(root, 'node_modules', 'pkg'), { recursive: true })
+  await writeFile(join(root, 'src', 'a.ts'), 'one\ntwo\nthree\nfour\n')
+  await writeFile(join(root, 'src', 'deep', 'b.ts'), 'const two = 2\n')
+  await writeFile(join(root, 'notes.md'), 'two words\n')
+  await writeFile(join(root, 'node_modules', 'pkg', 'index.js'), 'two\n')
+  await writeFile(join(root, 'big.txt'), `two\n${'x'.repeat(1_100_000)}`)
+  const plugin = workspaceTools({ root, bashTimeoutMs: 20_000 })
+  const contributions = await plugin.setup()
+  tools = new Map(
+    (contributions.tools ?? []).map((tool): [string, AnyTool] => [
+      tool.name,
+      tool,
+    ]),
+  )
+})
+
+afterAll(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+describe('read_file', () => {
+  it('reads a window of numbered lines', async () => {
+    expect(
+      await run('read_file', { path: 'src/a.ts', offset: 2, limit: 2 }),
+    ).toBe('2\ttwo\n3\tthree')
+    expect(
+      await run('read_file', { path: 'src/a.ts', offset: -4, limit: 1 }),
+    ).toBe('1\tone')
+  })
+
+  it('refuses paths outside the workspace and missing arguments', async () => {
+    await expect(run('read_file', { path: '../outside.txt' })).rejects.toThrow(
+      'outside the workspace',
+    )
+    await expect(
+      run('read_file', { path: join(tmpdir(), 'elsewhere.txt') }),
+    ).rejects.toThrow('outside the workspace')
+    await expect(run('read_file', {})).rejects.toThrow(
+      'Argument "path" must be a string.',
+    )
+    await expect(run('read_file', null)).rejects.toThrow('must be a string')
+  })
+
+  it('cuts very long output', async () => {
+    await writeFile(join(root, 'long.txt'), 'y'.repeat(25_000))
+    const text = await run('read_file', { path: 'long.txt' })
+    expect(text).toContain('more characters]')
+    expect(text.length).toBeLessThan(21_000)
+  })
+})
+
+describe('write_file and edit_file', () => {
+  it('creates folders and files', async () => {
+    expect(
+      await run('write_file', { path: 'new/dir/c.txt', content: 'hi' }),
+    ).toBe('Wrote new/dir/c.txt.')
+    expect(await readFile(join(root, 'new', 'dir', 'c.txt'), 'utf8')).toBe('hi')
+    await expect(run('write_file', { path: 'x.txt' })).rejects.toThrow(
+      'Argument "content" must be a string.',
+    )
+  })
+
+  it('edits one match, refuses ambiguous or missing text, and replaces all when asked', async () => {
+    await writeFile(join(root, 'e.txt'), 'a b a')
+    await expect(
+      run('edit_file', { path: 'e.txt', old: 'zzz', new: 'q' }),
+    ).rejects.toThrow('not in the file')
+    await expect(
+      run('edit_file', { path: 'e.txt', old: 'a', new: 'q' }),
+    ).rejects.toThrow('appears 2 times')
+    expect(
+      await run('edit_file', {
+        path: 'e.txt',
+        old: 'a',
+        new: 'q',
+        replaceAll: true,
+      }),
+    ).toBe('Edited e.txt (2 changes).')
+    expect(await run('edit_file', { path: 'e.txt', old: 'b', new: 'c' })).toBe(
+      'Edited e.txt (1 change).',
+    )
+    expect(await readFile(join(root, 'e.txt'), 'utf8')).toBe('q c q')
+  })
+})
+
+describe('list_files and grep', () => {
+  it('lists files, skips dependency folders, and filters by glob', async () => {
+    const all = await run('list_files', {})
+    expect(all).toContain('src/deep/b.ts')
+    expect(all).not.toContain('node_modules')
+    expect(await run('list_files', { pattern: 'src/**/*.ts' })).toBe(
+      'src/a.ts\nsrc/deep/b.ts',
+    )
+    expect(await run('list_files', { pattern: '*.none' })).toBe('No files.')
+  })
+
+  it('finds lines, skips big files, and filters by glob', async () => {
+    const hits = await run('grep', { pattern: 'two' })
+    expect(hits).toContain('src/a.ts:2: two')
+    expect(hits).toContain('notes.md:1: two words')
+    expect(hits).not.toContain('big.txt')
+    expect(hits).not.toContain('node_modules')
+    expect(await run('grep', { pattern: 'two', glob: '**/*.md' })).toBe(
+      'notes.md:1: two words',
+    )
+    expect(await run('grep', { pattern: 'nothing-like-this' })).toBe(
+      'No matches.',
+    )
+  })
+})
+
+describe('bash', () => {
+  it('reports the exit code and stderr', async () => {
+    const ok = await run('bash', {
+      command: `node -e "console.log('out'); console.error('warn')"`,
+    })
+    expect(ok).toMatch(/^exit code: 0\nout/)
+    expect(ok).toContain('stderr:\nwarn')
+    const failed = await run('bash', { command: `node -e "process.exit(3)"` })
+    expect(failed).toMatch(/^exit code: 3/)
+  })
+})

From 7672d22b180ae2693f78ebce3d64717c73c4435b Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 15:34:45 +0200
Subject: [PATCH 023/286] test(ai-harness): cover plugin agent lookups and
 services outside a session

---
 .../ai-harness/tests/plugin-agents.test.ts    | 125 ++++++++++++++++++
 1 file changed, 125 insertions(+)
 create mode 100644 packages/ai-harness/tests/plugin-agents.test.ts

diff --git a/packages/ai-harness/tests/plugin-agents.test.ts b/packages/ai-harness/tests/plugin-agents.test.ts
new file mode 100644
index 0000000000..2ce1ec81da
--- /dev/null
+++ b/packages/ai-harness/tests/plugin-agents.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { defineAgent } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  createHarnessHost,
+  createPluginEvent,
+  defineCommand,
+  defineHarness,
+  definePlugin,
+} from '../src'
+import { AgentRegistry } from '../src/agents'
+import { mountPlugins } from '../src/plugins'
+import { mockAdapter } from './helpers'
+
+const painter = defineAgent({
+  name: 'painter',
+  description: 'Paints',
+  produces: 'image',
+  inputSchema: z.object({ subject: z.string() }),
+  run: async (ctx) => `a painting of ${ctx.input.subject}`,
+})
+
+describe('ctx.agents inside a session', () => {
+  it('lists, gets, finds, and starts agents', async () => {
+    const director = definePlugin({
+      name: 'test/director',
+      setup: (ctx) => ({
+        commands: {
+          survey: defineCommand({
+            description: 'Look at the agents',
+            run: () => ({
+              names: ctx.agents.list().map((agent) => agent.name),
+              byName: ctx.agents.get('painter')?.description,
+              byOutput: ctx.agents.find({ produces: 'image' })?.name,
+              none: ctx.agents.find({ produces: 'video' }),
+            }),
+          }),
+          paint: defineCommand({
+            description: 'Start the painter by name, then by value',
+            run: async () => [
+              await ctx.agents.start('painter', { subject: 'rain' }),
+              await ctx.agents.start(
+                painter,
+                { subject: 'sun' },
+                { wake: false },
+              ),
+            ],
+          }),
+        },
+      }),
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/agents',
+        adapter: mockAdapter([]).adapter,
+        agents: [painter],
+        plugins: () => [director],
+      }),
+      { threadId: 't' },
+    )
+    expect(await session.command('survey')).toEqual({
+      names: ['painter'],
+      byName: 'Paints',
+      byOutput: 'painter',
+      none: undefined,
+    })
+    expect(await session.command('paint')).toEqual([
+      'a painting of rain',
+      'a painting of sun',
+    ])
+    await host.close()
+  })
+})
+
+describe('plugin services outside a session', () => {
+  it('ignores events and config, and refuses session-only services', async () => {
+    const ping = createPluginEvent<number>('test/ping')
+    let checks: Record<string, unknown> = {}
+    const probe = definePlugin({
+      name: 'test/probe',
+      setup: (ctx) => {
+        const stop = ctx.on(ping, () => {})
+        stop()
+        ctx.emit(ping, 1)
+        const refused = (call: () => unknown) => {
+          try {
+            call()
+            return 'ran'
+          } catch (error) {
+            return error instanceof Error ? error.message : String(error)
+          }
+        }
+        checks = {
+          config: ctx.config.get('anything'),
+          state: refused(() => ctx.state({})),
+          credentials: refused(() => ctx.credentials.get('x')),
+          session: refused(() => ctx.session.snapshot()),
+          run: refused(() => ctx.agents.run('painter')),
+          start: refused(() => ctx.agents.start('painter')),
+          group: refused(() => ctx.agents.group({}, async () => 1)),
+        }
+        return {}
+      },
+    })
+    await mountPlugins([probe], {
+      threadId: 't',
+      registry: new AgentRegistry(),
+      harnessTools: [],
+      harnessProvides: [],
+    })
+    expect(checks.config).toBeUndefined()
+    for (const key of [
+      'state',
+      'credentials',
+      'session',
+      'run',
+      'start',
+      'group',
+    ]) {
+      expect(checks[key]).toContain('only available inside a harness session')
+    }
+  })
+})

From d8d21525292ff5d6065b01bfc958a1a10b762990 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 15:38:25 +0200
Subject: [PATCH 024/286] test(ai-harness-cli): cover line commands, questions,
 and the session view

---
 packages/ai-harness-cli/package.json          |   3 +-
 .../ai-harness-cli/tests/commands.test.ts     | 306 ++++++++++++++++++
 pnpm-lock.yaml                                |   3 +
 3 files changed, 311 insertions(+), 1 deletion(-)
 create mode 100644 packages/ai-harness-cli/tests/commands.test.ts

diff --git a/packages/ai-harness-cli/package.json b/packages/ai-harness-cli/package.json
index e9224933f2..f1d78da10d 100644
--- a/packages/ai-harness-cli/package.json
+++ b/packages/ai-harness-cli/package.json
@@ -87,6 +87,7 @@
     "@tanstack/ai-persistence": "workspace:*",
     "@tanstack/ai-sandbox": "workspace:*",
     "@types/react": "^19.2.7",
-    "@vitest/coverage-v8": "4.1.10"
+    "@vitest/coverage-v8": "4.1.10",
+    "zod": "^4.2.0"
   }
 }
diff --git a/packages/ai-harness-cli/tests/commands.test.ts b/packages/ai-harness-cli/tests/commands.test.ts
new file mode 100644
index 0000000000..00fb3735c7
--- /dev/null
+++ b/packages/ai-harness-cli/tests/commands.test.ts
@@ -0,0 +1,306 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { EventType, defineAgent } from '@tanstack/ai'
+import {
+  HARNESS_EVENTS,
+  configOption,
+  createHarnessHost,
+  defineCommand,
+  defineHarness,
+  definePlugin,
+} from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { HELP_TEXT, handleLine, parseAnswer } from '../src/commands'
+import { applyEvent } from '../src/session-view'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import type { SessionEvent } from '@tanstack/ai-harness'
+
+/** A model that answers `echo: <text>`, or waits for cancel on "wait". */
+function model(): AnyTextAdapter {
+  return {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    '~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: any) =>
+      (async function* (): AsyncGenerator<StreamChunk> {
+        const said = String(options.messages.at(-1)?.content ?? '')
+        const now = Date.now()
+        yield {
+          type: EventType.RUN_STARTED,
+          runId: 'r',
+          threadId: 't',
+          timestamp: now,
+        }
+        if (said === 'wait') {
+          const signal: AbortSignal | undefined =
+            options.abortController?.signal ?? options.request?.signal
+          await new Promise<void>((resolve) => {
+            if (!signal || signal.aborted) return resolve()
+            signal.addEventListener('abort', () => resolve(), { once: true })
+          })
+          return
+        }
+        yield {
+          type: EventType.TEXT_MESSAGE_START,
+          messageId: 'm',
+          role: 'assistant',
+          timestamp: now,
+        }
+        yield {
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          messageId: 'm',
+          delta: `echo: ${said}`,
+          timestamp: now,
+        }
+        yield {
+          type: EventType.TEXT_MESSAGE_END,
+          messageId: 'm',
+          timestamp: now,
+        }
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId: 'r',
+          threadId: 't',
+          timestamp: now,
+          metadata: { tanstack: { finishReason: 'stop' } },
+        }
+      })(),
+  }
+}
+
+const tools = definePlugin({
+  name: 'test/tools',
+  setup: (ctx) => ({
+    config: {
+      level: configOption.select({ options: ['low', 'high'], default: 'low' }),
+    },
+    commands: {
+      quiet: defineCommand({
+        description: 'Returns nothing',
+        run: () => undefined,
+      }),
+      stats: defineCommand({
+        description: 'Returns an object',
+        run: () => ({ ok: true }),
+      }),
+      broken: defineCommand({
+        description: 'Throws',
+        run: () => {
+          throw new Error('it broke')
+        },
+      }),
+      echo: defineCommand({
+        description: 'Echoes',
+        run: (input: unknown) => input,
+      }),
+      confirm: defineCommand({
+        description: 'Asks a yes or no question',
+        run: async () => {
+          const answer = await ctx.session.ask({
+            message: 'Sure?',
+            schema: z.boolean(),
+          })
+          return answer ? 'confirmed' : 'declined'
+        },
+      }),
+      'connect:svc': defineCommand({
+        description: 'Sign in',
+        run: () => 'Connected to Svc.',
+      }),
+      'disconnect:svc': defineCommand({
+        description: 'Sign out',
+        run: () => {
+          throw new Error('not signed in')
+        },
+      }),
+    },
+  }),
+})
+
+const counter = defineAgent({
+  name: 'counter',
+  description: 'Counts letters',
+  inputSchema: z.object({ word: z.string() }),
+  run: async (ctx) => ctx.input.word.length,
+})
+
+async function open(plugins = true) {
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const session = await host.open(
+    defineHarness({
+      name: 'test/cli-commands',
+      adapter: model(),
+      ...(plugins ? { agents: [counter], plugins: () => [tools] } : {}),
+    }),
+    { threadId: 't' },
+  )
+  const say = async (line: string) => {
+    const result = await handleLine(session, line)
+    return result.type === 'notice' ? result.text : result.type
+  }
+  return { host, session, say }
+}
+
+describe('handleLine', () => {
+  it('answers built-in commands for a bare harness', async () => {
+    const { host, say } = await open(false)
+    expect(await say('   ')).toBe('')
+    expect(await say('/help')).toBe(HELP_TEXT)
+    expect(await say('/config')).toBe('This harness has no settings.')
+    expect(await say('/agents')).toBe('This harness has no agents.')
+    expect(await say('/cancel')).toBe('Nothing is running.')
+    expect(await say('/status')).toBe(
+      'Status: idle. Running: nothing. Queued turns: 0.',
+    )
+    expect(await say('/nope')).toBe('Unknown command: /nope. Type /help.')
+    expect(await say('/exit')).toBe('exit')
+    expect(await say('/quit')).toBe('exit')
+    await host.close()
+  })
+
+  it('lists plugin commands, settings, and agents, and changes settings', async () => {
+    const { host, say } = await open()
+    expect(await say('/help')).toContain('Plugin commands:\n')
+    expect(await say('/help')).toContain('/quiet  Returns nothing')
+    expect(await say('/config')).toBe('  level = "low"')
+    expect(await say('/config level high')).toBe('level changed.')
+    expect(await say('/config level extreme')).toMatch(/^Not changed: /)
+    expect(await say('/agents')).toBe('  counter: Counts letters')
+    await host.close()
+  })
+
+  it('runs plugin commands and shows their results or errors', async () => {
+    const { host, say } = await open()
+    expect(await say('/quiet')).toBe('Done.')
+    expect(await say('/stats')).toBe('{\n  "ok": true\n}')
+    expect(await say('/broken')).toBe('/broken failed: it broke')
+    expect(await say('/echo {"a":1}')).toBe('{\n  "a": 1\n}')
+    expect(await say('/echo plain words')).toBe('plain words')
+    expect(await say('/connect svc')).toBe('Connected to Svc.')
+    expect(await say('/disconnect svc')).toBe(
+      '/disconnect:svc failed: not signed in',
+    )
+    await host.close()
+  })
+
+  it('starts agents in the background and checks their input', async () => {
+    const { host, say } = await open()
+    expect(await say('/agent')).toBe('Unknown agent: (none)')
+    expect(await say('/agent ghost')).toBe('Unknown agent: ghost')
+    expect(await say('/agent counter {bad')).toContain('must be JSON')
+    expect(await say('/agent counter {"word":"four"}')).toBe(
+      'Started counter in the background.',
+    )
+    await host.close()
+  })
+
+  it('answers questions, including a rejected answer, then shows the result later', async () => {
+    const { host, session } = await open()
+    const asked = await handleLine(session, '/confirm')
+    expect(asked).toMatchObject({ type: 'notice', text: '' })
+    const later = asked.type === 'notice' ? asked.later : undefined
+    expect(later).toBeDefined()
+    expect(session.snapshot().pendingQuestions).toHaveLength(1)
+    expect(await handleLine(session, 'maybe')).toMatchObject({
+      text: expect.stringMatching(/^Answer again: /),
+    })
+    expect(await handleLine(session, 'y')).toMatchObject({ text: '' })
+    expect(await later).toBe('confirmed')
+    await host.close()
+  })
+
+  it('prompts when idle, steers while running, and cancels', async () => {
+    const { host, session, say } = await open()
+    expect(await say('wait')).toBe('sent')
+    await vi.waitFor(() => expect(session.snapshot().status).toBe('running'))
+    expect(await say('/status')).toMatch(/^Status: running\. Running: chat/)
+    expect(await say('go faster')).toBe('sent')
+    expect(await say('/cancel')).toBe('Cancelled.')
+    await host.close()
+  })
+})
+
+describe('parseAnswer', () => {
+  it('reads yes and no for boolean questions, JSON, and plain text', () => {
+    const boolean = { type: 'boolean' }
+    expect(parseAnswer('Yes', boolean)).toBe(true)
+    expect(parseAnswer(' n ', boolean)).toBe(false)
+    expect(parseAnswer('yes', { type: 'string' })).toBe('yes')
+    expect(parseAnswer('{"n":2}', undefined)).toEqual({ n: 2 })
+    expect(parseAnswer('', undefined)).toBeUndefined()
+  })
+})
+
+describe('applyEvent', () => {
+  const entry = (event: StreamChunk, operationId = 'op'): SessionEvent => ({
+    cursor: '1',
+    operationId,
+    event,
+  })
+  const custom = (name: string, value: unknown): StreamChunk => ({
+    type: EventType.CUSTOM,
+    name,
+    value,
+    timestamp: 1,
+  })
+
+  it('shows questions, sign-ins, resumes, errors, and child agents', () => {
+    const events: Array<StreamChunk> = [
+      custom(HARNESS_EVENTS.question, { message: 'Sure?' }),
+      custom(HARNESS_EVENTS.authRequired, {
+        connector: 'gh',
+        url: 'https://gh.example/device',
+        userCode: 'ABCD',
+      }),
+      custom(HARNESS_EVENTS.authRequired, { connector: 'svc' }),
+      custom(HARNESS_EVENTS.operationResumed, {}),
+      { type: EventType.RUN_ERROR, message: 'model down', timestamp: 1 },
+      {
+        type: EventType.SUBAGENT_STARTED,
+        subagentRunId: 'child',
+        name: 'painter',
+        timestamp: 1,
+      } as StreamChunk,
+    ]
+    const shown = events.reduce(
+      (entries, event) => applyEvent(entries, entry(event)),
+      [] as ReturnType<typeof applyEvent>,
+    )
+    expect(shown.map((item) => item.text)).toEqual([
+      '? Sure?',
+      'Sign in to gh. Open https://gh.example/device and enter the code ABCD.',
+      'Sign in to svc. Run /connect svc.',
+      'Resumed a turn that a crash stopped.',
+      'Error: model down',
+      'agent painter started',
+    ])
+    // Other child events and unknown custom events change nothing.
+    const unchanged = applyEvent(
+      shown,
+      entry({
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'x',
+        delta: 'child text',
+        subagentRunId: 'child',
+        timestamp: 1,
+      } as StreamChunk),
+    )
+    expect(unchanged).toBe(shown)
+    expect(applyEvent(shown, entry(custom('other.event', {})))).toBe(shown)
+  })
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4a914a15c6..320e1d7e5f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2571,6 +2571,9 @@ importers:
       '@vitest/coverage-v8':
         specifier: 4.1.10
         version: 4.1.10(vitest@4.1.11)
+      zod:
+        specifier: ^4.2.0
+        version: 4.3.6
 
   packages/ai-isolate-cloudflare:
     dependencies:

From b68dd4776275bd9bbef52b7a501ea9da7649dfee Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 16:08:33 +0200
Subject: [PATCH 025/286] test(ai-harness): cover remote harnessText and worker
 edge frames

---
 .../ai-harness/tests/remote-worker.test.ts    | 193 ++++++++++++++++++
 1 file changed, 193 insertions(+)
 create mode 100644 packages/ai-harness/tests/remote-worker.test.ts

diff --git a/packages/ai-harness/tests/remote-worker.test.ts b/packages/ai-harness/tests/remote-worker.test.ts
new file mode 100644
index 0000000000..8fa68281e9
--- /dev/null
+++ b/packages/ai-harness/tests/remote-worker.test.ts
@@ -0,0 +1,193 @@
+import { PassThrough } from 'node:stream'
+import { describe, expect, it, vi } from 'vitest'
+import { EventType, chat } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  createHarnessHandler,
+  createHarnessHost,
+  defineHarness,
+  harnessText,
+} from '../src'
+import { runHarnessWorker } from '../src/worker'
+import { mockAdapter, text } from './helpers'
+import type { StreamChunk } from '@tanstack/ai'
+
+async function collect(stream: AsyncIterable<StreamChunk>) {
+  const chunks: Array<StreamChunk> = []
+  for await (const chunk of stream) chunks.push(chunk)
+  return chunks
+}
+
+const textOf = (chunks: Array<StreamChunk>) =>
+  chunks
+    .map((chunk) =>
+      chunk.type === EventType.TEXT_MESSAGE_CONTENT ? chunk.delta : '',
+    )
+    .join('')
+
+describe('harnessText for a remote harness', () => {
+  it('sends the token and the last user message, and streams the answer', async () => {
+    const { adapter, calls } = mockAdapter([() => text('remote answer')])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const handler = createHarnessHandler({
+      host,
+      harness: defineHarness({ name: 'test/remote', adapter }),
+      authorize: (request) =>
+        request.headers.get('authorization') === 'Bearer secret'
+          ? { id: 'u' }
+          : null,
+    })
+    const remote = harnessText({
+      url: 'http://remote.test/api/harness/',
+      token: 'secret',
+      fetch: (input, init) => handler(new Request(input, init)),
+    })
+    expect(remote.model).toBe('http://remote.test/api/harness')
+    const chunks = await collect(
+      chat({
+        adapter: remote,
+        messages: [
+          { role: 'user', content: 'older question' },
+          { role: 'assistant', content: 'older answer' },
+          { role: 'user', content: 'new question' },
+        ],
+        threadId: 'outer',
+      }) as AsyncIterable<StreamChunk>,
+    )
+    expect(textOf(chunks)).toBe('remote answer')
+    expect(JSON.stringify(calls[0].messages)).toContain('new question')
+    expect(JSON.stringify(calls[0].messages)).not.toContain('older question')
+    await expect(remote.structuredOutput({} as never)).rejects.toThrow(
+      'does not support structured output',
+    )
+    await host.close()
+  })
+
+  it('reports a refused request', async () => {
+    const remote = harnessText({
+      url: 'http://remote.test',
+      fetch: async () => new Response('unauthorized', { status: 401 }),
+    })
+    await expect(
+      collect(
+        remote.chatStream({
+          model: 'x',
+          messages: [{ role: 'user', content: 'hi' }],
+        } as never),
+      ),
+    ).rejects.toThrow('Remote harness failed (401): unauthorized')
+  })
+
+  it('skips child and unknown data, and ends on a run error', async () => {
+    const sse = [
+      {
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'm',
+        delta: 'kept',
+        timestamp: 1,
+      },
+      {
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'c',
+        delta: 'child',
+        subagentRunId: 'x',
+        timestamp: 1,
+      },
+      'not an object',
+      { no: 'type' },
+      { type: EventType.RUN_ERROR, message: 'remote broke', timestamp: 1 },
+      {
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'm',
+        delta: 'after the error',
+        timestamp: 1,
+      },
+    ]
+      .map((data) => `data: ${JSON.stringify(data)}\n\n`)
+      .join('')
+    const remote = harnessText({
+      url: 'http://remote.test',
+      fetch: async () => new Response(`: comment\n\n${sse}`),
+    })
+    const chunks = await collect(
+      remote.chatStream({
+        model: 'x',
+        runId: 'run-1',
+        threadId: 'thread-1',
+        messages: [],
+      } as never),
+    )
+    expect(textOf(chunks)).toBe('kept')
+    expect(chunks.at(-1)).toMatchObject({
+      type: EventType.RUN_ERROR,
+      message: 'remote broke',
+    })
+  })
+
+  it('finishes cleanly when the response has no body', async () => {
+    const remote = harnessText({
+      url: 'http://remote.test',
+      fetch: async () => new Response(null, { status: 200 }),
+    })
+    const chunks = await collect(
+      remote.chatStream({ model: 'x', messages: [] } as never),
+    )
+    expect(chunks.map((chunk) => chunk.type)).toEqual([
+      EventType.RUN_STARTED,
+      EventType.RUN_FINISHED,
+    ])
+  })
+})
+
+describe('runHarnessWorker edges', () => {
+  it('answers bad frames, a second subscribe, and snapshots, and resumes from a cursor', async () => {
+    const { adapter } = mockAdapter([() => text('worker answer')])
+    const input = new PassThrough()
+    const frames: Array<any> = []
+    const running = runHarnessWorker(
+      defineHarness({ name: 'test/worker-edges', adapter }),
+      {
+        input,
+        output: { write: (line: string) => frames.push(JSON.parse(line)) },
+        persistence: memoryPersistence(),
+      },
+    )
+    const send = (frame: unknown) =>
+      input.write(
+        `${typeof frame === 'string' ? frame : JSON.stringify(frame)}\n`,
+      )
+
+    send('')
+    send({ type: 'harness.snapshot' })
+    await vi.waitFor(() =>
+      expect(frames.at(-1)).toEqual({
+        type: 'harness.error',
+        message: 'Send harness.subscribe first.',
+      }),
+    )
+    send('{not json')
+    await vi.waitFor(() => expect(frames).toHaveLength(2))
+    expect(frames[1].type).toBe('harness.error')
+
+    send({ type: 'harness.subscribe', threadId: 'w', from: '0' })
+    await vi.waitFor(() =>
+      expect(frames.some((frame) => frame.type === 'harness.hello')).toBe(true),
+    )
+    send({ type: 'harness.subscribe', threadId: 'w' })
+    await vi.waitFor(() =>
+      expect(frames.at(-1)).toEqual({
+        type: 'harness.error',
+        message: 'Already subscribed.',
+      }),
+    )
+    send({ type: 'harness.snapshot' })
+    await vi.waitFor(() =>
+      expect(frames.at(-1)).toMatchObject({
+        type: 'harness.snapshot',
+        snapshot: { threadId: 'w', status: 'idle' },
+      }),
+    )
+    input.end()
+    await running
+  })
+})

From ed8a768202c2b25c6ff32154440114f19fd5e815 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 16:10:47 +0200
Subject: [PATCH 026/286] test(ai-harness-cli): cover --dashboard pairing and
 saved-token reconnect

---
 .../ai-harness-cli/tests/dashboard.test.ts    | 118 ++++++++++++++++++
 1 file changed, 118 insertions(+)
 create mode 100644 packages/ai-harness-cli/tests/dashboard.test.ts

diff --git a/packages/ai-harness-cli/tests/dashboard.test.ts b/packages/ai-harness-cli/tests/dashboard.test.ts
new file mode 100644
index 0000000000..62d5f0d2b4
--- /dev/null
+++ b/packages/ai-harness-cli/tests/dashboard.test.ts
@@ -0,0 +1,118 @@
+import { describe, expect, it, vi } from 'vitest'
+import { EventType } from '@tanstack/ai'
+import { startDashboard } from '@tanstack/ai-dashboard'
+import { defineHarness } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { runCli } from '../src'
+import type { AnyTextAdapter } from '@tanstack/ai'
+
+const adapter: AnyTextAdapter = {
+  kind: 'text',
+  name: 'mock',
+  model: 'test-model',
+  '~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: () =>
+    (async function* () {
+      yield {
+        type: EventType.RUN_STARTED,
+        runId: 'r',
+        threadId: 't',
+        timestamp: 1,
+      }
+    })(),
+}
+
+/**
+ * Stop a CLI that waits for Ctrl+C by calling the listeners it added, not by
+ * sending a real signal to the test process.
+ */
+function stopper() {
+  const before = {
+    SIGINT: new Set(process.listeners('SIGINT')),
+    SIGTERM: new Set(process.listeners('SIGTERM')),
+  }
+  return () => {
+    for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+      for (const listener of process.listeners(signal)) {
+        if (before[signal].has(listener)) continue
+        process.removeListener(signal, listener)
+        if (signal === 'SIGINT') (listener as () => void)()
+      }
+    }
+  }
+}
+
+describe('--dashboard', () => {
+  it('pairs on first use, then reconnects with the saved token', async () => {
+    const dashboard = await startDashboard({ port: 0 })
+    const owner = {
+      Authorization: `Bearer ${dashboard.ownerToken}`,
+      'Content-Type': 'application/json',
+    }
+    const harness = defineHarness({ name: 'test/dashboard-cli', adapter })
+    try {
+      let log = ''
+      const stderr = {
+        write: (text: string) => {
+          log += text
+          const code = /with the code (\S+)\./.exec(text)?.[1]
+          if (code) {
+            void fetch(`${dashboard.url}/api/pair/approve`, {
+              method: 'POST',
+              headers: owner,
+              body: JSON.stringify({ code }),
+            })
+          }
+          return true
+        },
+      }
+      const stop = stopper()
+      const first = runCli(harness, {
+        argv: ['--dashboard', dashboard.url],
+        env: {},
+        stderr,
+        stdout: { write: () => true },
+        persistence: memoryPersistence(),
+      })
+      await vi.waitFor(() => expect(log).toContain('Connected to'), {
+        timeout: 5000,
+      })
+      stop()
+      expect(await first).toBe(0)
+      const token = /HARNESS_DASHBOARD_TOKEN=(\S+) /.exec(log)?.[1]
+      expect(token).toBeDefined()
+
+      log = ''
+      const stopAgain = stopper()
+      const second = runCli(harness, {
+        argv: ['--dashboard', dashboard.url],
+        env: { HARNESS_DASHBOARD_TOKEN: token ?? '' },
+        stderr,
+        stdout: { write: () => true },
+        persistence: memoryPersistence(),
+      })
+      await vi.waitFor(() => expect(log).toContain('Connected to'), {
+        timeout: 5000,
+      })
+      expect(log).not.toContain('Pair this host')
+      stopAgain()
+      expect(await second).toBe(0)
+    } finally {
+      await dashboard.close()
+    }
+  })
+})

From f72f17c83e969845464fd2f6380daa462da6f6bd Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 16:15:15 +0200
Subject: [PATCH 027/286] fix(ai-mcp): refresh expired connector tokens outside
 /connect; cover saved, refreshed, and revoked sign-ins

---
 packages/ai-mcp/src/connector.ts              |  10 +-
 packages/ai-mcp/tests/connector-edges.test.ts | 277 ++++++++++++++++++
 packages/ai-mcp/tests/connector.test.ts       | 118 +-------
 packages/ai-mcp/tests/protected-server.ts     | 133 +++++++++
 4 files changed, 421 insertions(+), 117 deletions(-)
 create mode 100644 packages/ai-mcp/tests/connector-edges.test.ts
 create mode 100644 packages/ai-mcp/tests/protected-server.ts

diff --git a/packages/ai-mcp/src/connector.ts b/packages/ai-mcp/src/connector.ts
index 3a9e94ab94..13d9327327 100644
--- a/packages/ai-mcp/src/connector.ts
+++ b/packages/ai-mcp/src/connector.ts
@@ -216,12 +216,20 @@ export function mcpConnector(options: McpConnectorOptions) {
         discoverTools: async () => {
           if (!connected) return []
           if (!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'
             client = await createMCPClient({
               transport: {
                 type: 'http',
                 url,
                 authProvider: credentialProvider(id, ctx.credentials, {
-                  redirectUri: undefined,
+                  redirectUri,
                   clientName,
                   scopes: options.scopes,
                 }),
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..af6565cfbc
--- /dev/null
+++ b/packages/ai-mcp/tests/connector-edges.test.ts
@@ -0,0 +1,277 @@
+import { afterEach, describe, expect, it } 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 { startProtectedServer } from './protected-server'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import type { SessionEvent } from '@tanstack/ai-harness'
+
+/** A model that records the tools it gets, calls `tool` once, then stops. */
+function recorder(tool?: string) {
+  const calls: Array<any> = []
+  const now = () => Date.now()
+  const adapter: AnyTextAdapter = {
+    kind: 'text',
+    name: 'mock',
+    model: 'mock',
+    '~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) => {
+      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: { name: string }) => entry.name)
+  return { adapter, calls, toolNames }
+}
+
+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?: Parameters<
+    ReturnType<typeof memoryPersistence>['stores']['credentials']['set']
+  >[2],
+) {
+  const server = await startProtectedServer()
+  cleanups.push(() => server.close())
+  const persistence = memoryPersistence()
+  if (credential)
+    await persistence.stores.credentials.set(scope, 'demo', credential)
+  const host = createHarnessHost({ persistence })
+  cleanups.push(() => host.close())
+  return { server, persistence, host }
+}
+
+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 host.open(
+      defineHarness({
+        name: 'test/saved',
+        adapter: model.adapter,
+        plugins: () => [
+          mcpConnector({ id: 'demo', label: 'Demo', url: server.url }),
+        ],
+      }),
+      { threadId: 't', principal: { id: 'user-1' } },
+    )
+    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('refreshes an expired token and keeps the old refresh token and client', async () => {
+    const { server, persistence, host } = await setup({
+      type: 'oauth',
+      accessToken: 'stale',
+      refreshToken: 'refresh-1',
+      expiresAt: Date.now() - 1000,
+      client: { clientId: 'client-1' },
+    })
+    const model = recorder('demo_echo')
+    const session = await host.open(
+      defineHarness({
+        name: 'test/refresh',
+        adapter: model.adapter,
+        plugins: () => [
+          mcpConnector({ id: 'demo', label: 'Demo', url: server.url }),
+        ],
+      }),
+      { threadId: 't', principal: { id: 'user-1' } },
+    )
+    await session.prompt('echo')
+    expect(model.toolNames(0)).toEqual(['demo_echo'])
+    expect(
+      server.seen.tokenRequests.some(
+        (form) => form.get('grant_type') === 'refresh_token',
+      ),
+    ).toBe(true)
+    expect(
+      await persistence.stores.credentials.get(scope, 'demo'),
+    ).toMatchObject({
+      accessToken: 'access-2',
+      refreshToken: 'refresh-1',
+      client: { clientId: 'client-1' },
+    })
+  })
+
+  it('drops the tools with a warning when the sign-in no longer works', async () => {
+    const { server, host } = await setup({
+      type: 'oauth',
+      accessToken: 'stale',
+      refreshToken: 'revoked',
+    })
+    const model = recorder()
+    const session = await host.open(
+      defineHarness({
+        name: 'test/revoked',
+        adapter: model.adapter,
+        plugins: () => [
+          mcpConnector({ id: 'demo', label: 'Demo', url: server.url }),
+        ],
+      }),
+      { threadId: 't', principal: { id: 'user-1' } },
+    )
+    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('hi')
+    controller.abort()
+    await reading
+    expect(model.toolNames(0)).toEqual([])
+    const warning = seen.find(
+      (entry) =>
+        entry.event.type === EventType.CUSTOM &&
+        entry.event.name === 'harness.plugin.warning',
+    )
+    expect(warning?.event).toMatchObject({
+      value: { plugin: 'connector/demo' },
+    })
+  })
+})
+
+describe('mcpConnector options', () => {
+  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 controller = new AbortController()
+    let scopeParam: string | null = null
+    void (async () => {
+      for await (const entry of session.events({ signal: controller.signal })) {
+        const event = entry.event
+        if (
+          event.type !== EventType.CUSTOM ||
+          event.name !== HARNESS_EVENTS.authRequired
+        )
+          continue
+        const url = new URL(String((event.value as { url: string }).url))
+        scopeParam = url.searchParams.get('scope')
+        const redirect = new URL(url.searchParams.get('redirect_uri') ?? '')
+        redirect.searchParams.set('code', 'code-1')
+        redirect.searchParams.set('state', url.searchParams.get('state') ?? '')
+        await fetch(redirect)
+      }
+    })()
+    cleanups.push(() => controller.abort())
+
+    expect(await session.command('connect:demo')).toBe('Connected to Demo.')
+    expect(scopeParam).toBe('read')
+    expect(server.seen.registrations[0]).toMatchObject({
+      client_name: 'Acme Agent',
+      scope: 'read',
+    })
+    expect(
+      await persistence.stores.credentials.get(scope, '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)
+  })
+})
diff --git a/packages/ai-mcp/tests/connector.test.ts b/packages/ai-mcp/tests/connector.test.ts
index 55261ca78b..5e299a4115 100644
--- a/packages/ai-mcp/tests/connector.test.ts
+++ b/packages/ai-mcp/tests/connector.test.ts
@@ -1,8 +1,4 @@
-import { createServer } from 'node:http'
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import { z } from 'zod'
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
 import { EventType } from '@tanstack/ai'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import {
@@ -11,119 +7,9 @@ import {
   defineHarness,
 } from '@tanstack/ai-harness'
 import { mcpConnector } from '../src/connector'
-import type { IncomingMessage, Server } from 'node:http'
+import { startProtectedServer } from './protected-server'
 import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
 
-/**
- * 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.
- */
-async function startProtectedServer() {
-  const seen = { registrations: 0, tokenRequests: [] as Array<URLSearchParams> }
-  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'],
-        })
-      }
-      if (url.pathname === '/register' && req.method === 'POST') {
-        seen.registrations += 1
-        const metadata = JSON.parse(await readBody(req))
-        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,
-          })
-        }
-        return json(400, { error: 'invalid_grant' })
-      }
-      if (url.pathname === '/mcp') {
-        if (req.headers.authorization !== 'Bearer access-1') {
-          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 StreamableHTTPServerTransport({
-          sessionIdGenerator: undefined,
-          enableJsonResponse: true,
-        })
-        await mcp.connect(transport)
-        await transport.handleRequest(req, res, JSON.parse(await readBody(req)))
-        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`,
-    seen,
-    close: () =>
-      new Promise<void>((resolve) => {
-        server.closeAllConnections()
-        server.close(() => resolve())
-      }),
-  }
-}
-
 /** A model that calls `tool` once, then answers with the tool result it saw. */
 function modelCalling(
   tool: string,
@@ -278,7 +164,7 @@ describe('mcpConnector', () => {
       new URL(authorizationUrl?.searchParams.get('redirect_uri') ?? '')
         .hostname,
     ).toBe('127.0.0.1')
-    expect(protectedServer.seen.registrations).toBe(1)
+    expect(protectedServer.seen.registrations).toHaveLength(1)
     expect(
       protectedServer.seen.tokenRequests[0]?.get('code_verifier'),
     ).toBeTruthy()
diff --git a/packages/ai-mcp/tests/protected-server.ts b/packages/ai-mcp/tests/protected-server.ts
new file mode 100644
index 0000000000..6d225bcdb3
--- /dev/null
+++ b/packages/ai-mcp/tests/protected-server.ts
@@ -0,0 +1,133 @@
+import { createServer } from 'node:http'
+import { z } from 'zod'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import type { IncomingMessage, Server } from 'node:http'
+
+/**
+ * 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 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() {
+  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'],
+        })
+      }
+      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') === '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 StreamableHTTPServerTransport({
+          sessionIdGenerator: undefined,
+          enableJsonResponse: true,
+        })
+        await mcp.connect(transport)
+        await transport.handleRequest(req, res, JSON.parse(await readBody(req)))
+        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`,
+    seen,
+    revoke: (token: string) => valid.delete(token),
+    close: () =>
+      new Promise<void>((resolve) => {
+        server.closeAllConnections()
+        server.close(() => resolve())
+      }),
+  }
+}

From ec2abc4f12d26e31ed9d85b834ae9f5c7c0a1d3c Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 16:42:28 +0200
Subject: [PATCH 028/286] test(ai-mcp, ai-opencode): cover stored connector
 credentials and the opencode server start paths

---
 packages/ai-mcp/tests/connector-edges.test.ts |  93 ++++++++++++
 .../ai-opencode/tests/sandbox-server.test.ts  | 141 ++++++++++++++++++
 2 files changed, 234 insertions(+)
 create mode 100644 packages/ai-opencode/tests/sandbox-server.test.ts

diff --git a/packages/ai-mcp/tests/connector-edges.test.ts b/packages/ai-mcp/tests/connector-edges.test.ts
index af6565cfbc..7aa3b5e7c9 100644
--- a/packages/ai-mcp/tests/connector-edges.test.ts
+++ b/packages/ai-mcp/tests/connector-edges.test.ts
@@ -275,3 +275,96 @@ describe('mcpConnector options', () => {
     expect(model.calls[0].tools[0].needsApproval).toBe(true)
   })
 })
+
+describe('mcpConnector stored credential shapes', () => {
+  function connectorHarness(url: string, model: ReturnType<typeof recorder>) {
+    return defineHarness({
+      name: 'test/shapes',
+      adapter: model.adapter,
+      plugins: () => [mcpConnector({ id: 'demo', label: 'Demo', url })],
+    })
+  }
+
+  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 host.open(connectorHarness(server.url, model), {
+      threadId: 't',
+      principal: { id: 'user-1' },
+    })
+    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 host.open(connectorHarness(server.url, recorder()), {
+      threadId: 't2',
+      principal: { id: 'user-1' },
+    })
+    expect(await fresh.command('disconnect:demo')).toBe(
+      'Disconnected from Demo.',
+    )
+    expect(await persistence.stores.credentials.get(scope, '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 bare.host.open(
+      connectorHarness(bare.server.url, model),
+      {
+        threadId: 't',
+        principal: { id: 'user-1' },
+      },
+    )
+    await session.prompt('hi')
+    expect(model.toolNames(0)).toEqual(['demo_echo'])
+    const saved = await bare.persistence.stores.credentials.get(scope, '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 withSecret.host.open(
+      connectorHarness(withSecret.server.url, recorder()),
+      { threadId: 't', principal: { id: 'user-1' } },
+    )
+    await other.prompt('hi')
+    expect(
+      await withSecret.persistence.stores.credentials.get(scope, '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 host.open(connectorHarness(server.url, model), {
+      threadId: 't',
+      principal: { id: 'user-1' },
+    })
+    await session.prompt('hi')
+    expect(model.toolNames(0)).toEqual([])
+  })
+})
diff --git a/packages/ai-opencode/tests/sandbox-server.test.ts b/packages/ai-opencode/tests/sandbox-server.test.ts
new file mode 100644
index 0000000000..583c013186
--- /dev/null
+++ b/packages/ai-opencode/tests/sandbox-server.test.ts
@@ -0,0 +1,141 @@
+import { describe, expect, it } from 'vitest'
+import { startOpencodeServerInSandbox } from '../src/process/sandbox-server'
+import type { SandboxHandle, SpawnHandle } from '@tanstack/ai-sandbox'
+
+async function* chunks(values: Array<string>): AsyncIterable<string> {
+  for (const value of values) {
+    await Promise.resolve()
+    yield value
+  }
+}
+
+async function* failing(message: string): AsyncIterable<string> {
+  await Promise.resolve()
+  throw new Error(message)
+}
+
+/** An iterable that never yields, like a server that prints nothing. */
+function silent(): AsyncIterable<string> {
+  return {
+    [Symbol.asyncIterator]: () => ({ next: () => new Promise(() => {}) }),
+  }
+}
+
+function sandboxWith(
+  streams: { stdout: AsyncIterable<string>; stderr: AsyncIterable<string> },
+  channel: { url: string; headers?: Record<string, string>; token?: string },
+): { sandbox: SandboxHandle; spawned: Array<unknown> } {
+  const spawned: Array<unknown> = []
+  const handle: SpawnHandle = {
+    pid: 1,
+    ...streams,
+    stdin: { write: () => Promise.resolve(), end: () => Promise.resolve() },
+    wait: () => Promise.resolve(0),
+    kill: () => Promise.resolve(),
+  }
+  const sandbox: SandboxHandle = {
+    id: 'sbx',
+    provider: 'mock',
+    capabilities: {} as SandboxHandle['capabilities'],
+    fs: {} as SandboxHandle['fs'],
+    git: {} as SandboxHandle['git'],
+    process: {
+      exec: () => Promise.reject(new Error('unused')),
+      spawn: (command, options) => {
+        spawned.push({ command, options })
+        return Promise.resolve(handle)
+      },
+    },
+    ports: { connect: () => Promise.resolve(channel) },
+    env: { set: () => Promise.resolve() },
+    destroy: () => Promise.resolve(),
+  }
+  return { sandbox, spawned }
+}
+
+const ready = 'opencode server listening on http://0.0.0.0:4096\n'
+
+describe('startOpencodeServerInSandbox edges', () => {
+  it('passes the channel headers through, with the host, env, and signal', async () => {
+    const { sandbox, spawned } = sandboxWith(
+      { stdout: chunks([ready]), stderr: chunks(['warming up\n']) },
+      { url: 'https://preview.test', headers: { 'x-preview-token': 't' } },
+    )
+    const controller = new AbortController()
+    const server = await startOpencodeServerInSandbox(sandbox, {
+      port: 4096,
+      hostname: '127.0.0.1',
+      cwd: '/workspace',
+      env: { OPENCODE_CONFIG_CONTENT: '{}' },
+      signal: controller.signal,
+    })
+    expect(server.headers).toEqual({ 'x-preview-token': 't' })
+    expect(spawned[0]).toMatchObject({
+      command: 'opencode serve --hostname=127.0.0.1 --port=4096',
+      options: { cwd: '/workspace', env: { OPENCODE_CONFIG_CONTENT: '{}' } },
+    })
+  })
+
+  it('turns a channel token into a bearer header', async () => {
+    const { sandbox } = sandboxWith(
+      { stdout: chunks([ready]), stderr: chunks([]) },
+      { url: 'https://preview.test', token: 'tok' },
+    )
+    const server = await startOpencodeServerInSandbox(sandbox, {
+      port: 4096,
+      cwd: '/workspace',
+    })
+    expect(server.headers).toEqual({ Authorization: 'Bearer tok' })
+  })
+
+  it('times out with the server output in the error', async () => {
+    const { sandbox } = sandboxWith(
+      { stdout: silent(), stderr: chunks(['address already in use\n']) },
+      { url: 'http://127.0.0.1:4096' },
+    )
+    await expect(
+      startOpencodeServerInSandbox(sandbox, {
+        port: 4096,
+        cwd: '/workspace',
+        timeoutMs: 30,
+      }),
+    ).rejects.toThrow(
+      'opencode serve did not become ready within 30ms: address already in use',
+    )
+  })
+
+  it('times out without output, and reports an exit with no output', async () => {
+    const quiet = sandboxWith(
+      { stdout: silent(), stderr: chunks([]) },
+      { url: 'http://127.0.0.1:4096' },
+    )
+    await expect(
+      startOpencodeServerInSandbox(quiet.sandbox, {
+        port: 4096,
+        cwd: '/workspace',
+        timeoutMs: 20,
+      }),
+    ).rejects.toThrow(/^opencode serve did not become ready within 20ms$/)
+
+    const exited = sandboxWith(
+      { stdout: chunks([]), stderr: chunks([]) },
+      { url: 'http://127.0.0.1:4096' },
+    )
+    await expect(
+      startOpencodeServerInSandbox(exited.sandbox, {
+        port: 4096,
+        cwd: '/workspace',
+      }),
+    ).rejects.toThrow('exited before becoming ready (no output)')
+  })
+
+  it('rejects when stdout fails, and ignores a failing stderr', async () => {
+    const { sandbox } = sandboxWith(
+      { stdout: failing('stdout closed'), stderr: failing('stderr closed') },
+      { url: 'http://127.0.0.1:4096' },
+    )
+    await expect(
+      startOpencodeServerInSandbox(sandbox, { port: 4096, cwd: '/workspace' }),
+    ).rejects.toThrow('stdout closed')
+  })
+})

From a65d4bad66b0e30daf2f3e1fe03003b46d4f988d Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 26 Sep 2026 16:42:58 +0200
Subject: [PATCH 029/286] test(ai-opencode): use a plain failing iterable

---
 packages/ai-opencode/tests/sandbox-server.test.ts | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/packages/ai-opencode/tests/sandbox-server.test.ts b/packages/ai-opencode/tests/sandbox-server.test.ts
index 583c013186..c4a5ba9e94 100644
--- a/packages/ai-opencode/tests/sandbox-server.test.ts
+++ b/packages/ai-opencode/tests/sandbox-server.test.ts
@@ -9,9 +9,13 @@ async function* chunks(values: Array<string>): AsyncIterable<string> {
   }
 }
 
-async function* failing(message: string): AsyncIterable<string> {
-  await Promise.resolve()
-  throw new Error(message)
+/** An iterable whose first read fails. */
+function failing(message: string): AsyncIterable<string> {
+  return {
+    [Symbol.asyncIterator]: () => ({
+      next: () => Promise.reject(new Error(message)),
+    }),
+  }
 }
 
 /** An iterable that never yields, like a server that prints nothing. */

From 9409b06db836e9d897569266d17747bc6f9fadef Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 11:23:13 +0200
Subject: [PATCH 030/286] feat(ai-sandbox, ai-harness): codingAgents plugin to
 delegate to Claude Code, Codex, and other coding agents; show child agent
 work in the CLI, ACP, and dashboard

---
 .changeset/harness-p9-coding-agents.md        |  13 +
 docs/config.json                              |  11 +-
 docs/harness/coding-agent.md                  |   4 +
 docs/harness/coding-agents.md                 | 122 ++++++
 docs/harness/dashboard.md                     |   2 +-
 docs/harness/deploy.md                        |   2 +-
 docs/harness/plugins.md                       |   1 +
 docs/harness/subagents.md                     |   2 +-
 examples/harness-cli/.env.example             |   4 +
 examples/harness-cli/.gitignore               |   2 +
 examples/harness-cli/README.md                |  10 +
 examples/harness-cli/package.json             |   4 +
 examples/harness-cli/src/harness.ts           |  55 +++
 packages/ai-acp/src/agent/index.ts            |   7 +-
 packages/ai-acp/tests/child-updates.test.ts   |  62 +++
 packages/ai-dashboard/src/ui.ts               |  31 +-
 .../ai-dashboard/tests/child-agents.test.ts   | 143 +++++++
 packages/ai-harness-cli/src/interactive.tsx   |   7 +
 packages/ai-harness-cli/src/lines.ts          |   4 +-
 packages/ai-harness-cli/src/session-view.ts   |  85 +++-
 .../ai-harness-cli/tests/child-view.test.ts   | 226 +++++++++++
 .../ai-harness-cli/tests/commands.test.ts     |  11 +-
 packages/ai-harness/src/plugins.ts            |  14 +
 packages/ai-harness/src/session.ts            |  12 +-
 .../ai-harness/tests/plugin-subagents.test.ts |  74 ++++
 packages/ai-sandbox/package.json              |   9 +
 packages/ai-sandbox/src/harness.ts            | 210 ++++++++++
 .../ai-sandbox/tests/coding-agents.test.ts    | 377 ++++++++++++++++++
 packages/ai-sandbox/vite.config.ts            |   7 +-
 pnpm-lock.yaml                                |  15 +
 30 files changed, 1502 insertions(+), 24 deletions(-)
 create mode 100644 .changeset/harness-p9-coding-agents.md
 create mode 100644 docs/harness/coding-agents.md
 create mode 100644 packages/ai-acp/tests/child-updates.test.ts
 create mode 100644 packages/ai-dashboard/tests/child-agents.test.ts
 create mode 100644 packages/ai-harness-cli/tests/child-view.test.ts
 create mode 100644 packages/ai-harness/tests/plugin-subagents.test.ts
 create mode 100644 packages/ai-sandbox/src/harness.ts
 create mode 100644 packages/ai-sandbox/tests/coding-agents.test.ts

diff --git a/.changeset/harness-p9-coding-agents.md b/.changeset/harness-p9-coding-agents.md
new file mode 100644
index 0000000000..62a57e4b40
--- /dev/null
+++ b/.changeset/harness-p9-coding-agents.md
@@ -0,0 +1,13 @@
+---
+'@tanstack/ai-sandbox': minor
+'@tanstack/ai-harness': minor
+'@tanstack/ai-harness-cli': minor
+'@tanstack/ai-acp': minor
+'@tanstack/ai-dashboard': minor
+---
+
+`@tanstack/ai-sandbox/harness` adds `codingAgents({ sandbox, agents, workspace? })`: a harness plugin that gives the lead model one tool per coding agent (Claude Code, Codex, Grok Build, or any ACP agent). Each agent runs in the sandbox, keeps its own session per thread (also after a restart), and starts read-only in the harness `plan` mode. `workspace: 'shared'` (default) runs one agent at a time in one sandbox per thread. `'per-agent'` gives each agent its own sandbox. `/fresh [agent]` starts new sessions.
+
+`@tanstack/ai-harness` plugins can contribute `subagents`: agents the model can call as tools.
+
+Child agent work is now visible: the CLI shows each child's tool calls and a finish line with the start of its answer, ACP editors get the child's tool calls, and the dashboard shows a block per child.
diff --git a/docs/config.json b/docs/config.json
index 71a5f53d3a..db8c43e1bc 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -827,12 +827,14 @@
         {
           "label": "Write a plugin",
           "to": "harness/plugins",
-          "addedAt": "2026-09-26"
+          "addedAt": "2026-09-26",
+          "updatedAt": "2026-09-28"
         },
         {
           "label": "Build a coding agent",
           "to": "harness/coding-agent",
-          "addedAt": "2026-09-26"
+          "addedAt": "2026-09-26",
+          "updatedAt": "2026-09-28"
         },
         {
           "label": "Auth and connectors",
@@ -849,6 +851,11 @@
           "to": "harness/code-mode",
           "addedAt": "2026-09-26"
         },
+        {
+          "label": "Delegate to coding agents",
+          "to": "harness/coding-agents",
+          "addedAt": "2026-09-28"
+        },
         {
           "label": "Run agents from a harness",
           "to": "harness/subagents",
diff --git a/docs/harness/coding-agent.md b/docs/harness/coding-agent.md
index 8a45100343..3e1c2663ec 100644
--- a/docs/harness/coding-agent.md
+++ b/docs/harness/coding-agent.md
@@ -90,6 +90,10 @@ A trailing `*` matches every tool that starts with the text. The last matching r
 
 The workspace tools run on your machine with your permissions. Run code you do not trust in a sandbox.
 
+## Hand work to Claude Code or Codex
+
+Your agent can also give tasks to coding agents you already use. [Delegate to coding agents](./coding-agents) shows how.
+
 ## What you have now
 
 - A terminal coding agent with file tools, approvals, modes, a todo list, and a model picker.
diff --git a/docs/harness/coding-agents.md b/docs/harness/coding-agents.md
new file mode 100644
index 0000000000..7f61e47424
--- /dev/null
+++ b/docs/harness/coding-agents.md
@@ -0,0 +1,122 @@
+---
+title: Delegate to coding agents
+id: harness-coding-agents
+order: 10
+description: "Let a harness hand coding work to Claude Code, Codex, Grok Build, or any ACP agent. Each one works in a sandbox and keeps its own session."
+keywords:
+  - tanstack ai
+  - harness
+  - claude code
+  - codex
+  - grok build
+  - sandbox
+  - subagents
+---
+
+Your lead agent plans the work, but you want Claude Code or Codex to do the edits, because they are good at code and you already use them. `codingAgents` gives the lead model one tool per coding agent. Each agent works in a sandbox, keeps its own session between calls, and its tool calls show up in your UI.
+
+## 1. Add the plugin
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: @tanstack/ai-harness @tanstack/ai-sandbox @tanstack/ai-sandbox-local-process @tanstack/ai-claude-code @tanstack/ai-codex
+vue: @tanstack/ai-harness @tanstack/ai-sandbox @tanstack/ai-sandbox-local-process @tanstack/ai-claude-code @tanstack/ai-codex
+solid: @tanstack/ai-harness @tanstack/ai-sandbox @tanstack/ai-sandbox-local-process @tanstack/ai-claude-code @tanstack/ai-codex
+svelte: @tanstack/ai-harness @tanstack/ai-sandbox @tanstack/ai-sandbox-local-process @tanstack/ai-claude-code @tanstack/ai-codex
+preact: @tanstack/ai-harness @tanstack/ai-sandbox @tanstack/ai-sandbox-local-process @tanstack/ai-claude-code @tanstack/ai-codex
+angular: @tanstack/ai-harness @tanstack/ai-sandbox @tanstack/ai-sandbox-local-process @tanstack/ai-claude-code @tanstack/ai-codex
+octane: @tanstack/ai-harness @tanstack/ai-sandbox @tanstack/ai-sandbox-local-process @tanstack/ai-claude-code @tanstack/ai-codex
+vanilla: @tanstack/ai-harness @tanstack/ai-sandbox @tanstack/ai-sandbox-local-process @tanstack/ai-claude-code @tanstack/ai-codex
+
+<!-- ::end:tabs -->
+
+```ts group=harness-coding-agents
+import { defineHarness } from '@tanstack/ai-harness'
+import { permissions } from '@tanstack/ai-harness/plugins'
+import { claudeCodeText } from '@tanstack/ai-claude-code'
+import { codexText } from '@tanstack/ai-codex'
+import { openaiText } from '@tanstack/ai-openai'
+import { defineSandbox, defineWorkspace, localSource } from '@tanstack/ai-sandbox'
+import { codingAgents } from '@tanstack/ai-sandbox/harness'
+import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'
+
+const repo = '/path/to/your/repo'
+
+export const lead = defineHarness({
+  name: 'acme/lead',
+  adapter: openaiText('gpt-5.6'),
+  plugins: () => [
+    permissions(),
+    codingAgents({
+      sandbox: defineSandbox({
+        id: 'repo',
+        provider: localProcessSandbox({ dir: repo }),
+        workspace: defineWorkspace({ source: localSource(repo) }),
+      }),
+      agents: {
+        claude_code: {
+          adapter: claudeCodeText('claude-opus-4-8', { permissionMode: 'acceptEdits' }),
+          description: 'Larger changes, refactors, and reviews',
+        },
+        codex: {
+          adapter: codexText('gpt-5.3-codex', { sandboxMode: 'workspace-write' }),
+          description: 'Quick fixes and tests',
+        },
+      },
+    }),
+  ],
+})
+```
+
+The lead model now has a `claude_code` tool and a `codex` tool. Each tool takes one `task`: the whole job, in words. The agent sees only that text and the files in its sandbox.
+
+## 2. Ask for work
+
+1. Start the harness, for example with the CLI.
+2. Ask the lead: `have claude_code add a test for the date parser, then have codex fix what fails`.
+3. Watch the child work. The CLI shows each agent's tool calls, then one line with the start of its answer:
+
+```text
+[agent claude_code started]
+[claude_code: tool Write]
+[agent claude_code finished: Added parse-date.test.ts with three cases.]
+```
+
+The dashboard shows the same work in a block under the lead's message. An ACP editor shows the child's tool calls next to the lead's own.
+
+## Sessions
+
+Each agent keeps its own session per harness thread. The next task for `claude_code` resumes the same Claude Code session, so it still knows the files it read. The session ids live in the plugin state, so they also survive a restart of the host.
+
+To start over, run `/fresh claude_code`, or `/fresh` for every agent.
+
+## Workspaces
+
+`workspace` chooses where the agents work:
+
+| Value | Where each agent works | At the same time |
+| --- | --- | --- |
+| `'shared'` (default) | One sandbox per harness thread | One agent at a time |
+| `'per-agent'` | A sandbox per agent | Yes |
+
+Use `'shared'` when the agents build on each other's changes. Use `'per-agent'` when they work on separate copies and you merge the results.
+
+## Plan mode
+
+When the `permissions()` plugin is in `plan` mode, the agents start read-only:
+
+- Claude Code gets `permissionMode: 'plan'`.
+- Codex gets `sandboxMode: 'read-only'`.
+- Any other agent gets its `planModelOptions`, for example `{ permissionMode: 'default' }` for an ACP agent that asks before each edit.
+
+## Other agents and sandboxes
+
+- `adapter` takes any coding-agent adapter: `grokBuildText` from `@tanstack/ai-grok-build`, or `acpCompatibleText` from `@tanstack/ai-acp` for any ACP agent.
+- `sandbox` takes any sandbox provider. [Sandbox providers](../sandbox/providers) lists them.
+- `modelOptions` on an agent is added to every call, for example a fixed `permissionMode`.
+
+## What you have now
+
+- A lead model that hands tasks to Claude Code and Codex.
+- One sandbox per thread, and one saved session per agent.
+- Child tool calls in the CLI, the dashboard, and ACP editors.
diff --git a/docs/harness/dashboard.md b/docs/harness/dashboard.md
index afbd511cd7..7ed93a5de4 100644
--- a/docs/harness/dashboard.md
+++ b/docs/harness/dashboard.md
@@ -1,7 +1,7 @@
 ---
 title: Self-host the dashboard
 id: harness-dashboard
-order: 12
+order: 13
 description: "Watch and steer your harness sessions from a browser or a phone. Agents dial out to your dashboard server, so they need no open port."
 keywords:
   - tanstack ai
diff --git a/docs/harness/deploy.md b/docs/harness/deploy.md
index ea6cf77423..04f94332f8 100644
--- a/docs/harness/deploy.md
+++ b/docs/harness/deploy.md
@@ -1,7 +1,7 @@
 ---
 title: Deploy a harness
 id: harness-deploy
-order: 11
+order: 12
 description: "Run a harness in your server, as a worker process, on another machine, or as a single executable."
 keywords:
   - tanstack ai
diff --git a/docs/harness/plugins.md b/docs/harness/plugins.md
index 4e01346a91..f05cd1d3bc 100644
--- a/docs/harness/plugins.md
+++ b/docs/harness/plugins.md
@@ -33,6 +33,7 @@ Add it with `plugins: () => [today]` in `defineHarness`. `setup` runs once per s
 - `middleware`: chat middleware, the same type as `chat({ middleware })`.
 - `generationMiddleware`: middleware for the activities agents call.
 - `agents`: agents added to `session.agents`.
+- `subagents`: agents the model can call as tools. They are also added to `session.agents`. [Delegate to coding agents](./coding-agents) uses them.
 - `commands`: user actions, see below.
 - `config`: session settings, see below.
 - `contribute`: items for another plugin's extension point.
diff --git a/docs/harness/subagents.md b/docs/harness/subagents.md
index 78de061c97..9e17ba8306 100644
--- a/docs/harness/subagents.md
+++ b/docs/harness/subagents.md
@@ -1,7 +1,7 @@
 ---
 title: Run agents from a harness
 id: harness-subagents
-order: 10
+order: 11
 description: "Start typed agents from commands and plugins, run them in groups, call a whole harness as a child, and keep the tree within limits."
 keywords:
   - tanstack ai
diff --git a/examples/harness-cli/.env.example b/examples/harness-cli/.env.example
index bb89717ef3..38405cac10 100644
--- a/examples/harness-cli/.env.example
+++ b/examples/harness-cli/.env.example
@@ -5,3 +5,7 @@ OPENAI_API_KEY=
 ANTHROPIC_API_KEY=
 # Optional: make videos with Grok Imagine instead of OpenAI Sora.
 XAI_API_KEY=
+# Optional: hand coding work to Claude Code and Codex (uses claude login and codex login).
+CODING_AGENTS=
+CODEX_MODEL=
+CODEX_SANDBOX_MODE=
diff --git a/examples/harness-cli/.gitignore b/examples/harness-cli/.gitignore
index ec9309579e..d3d132daa7 100644
--- a/examples/harness-cli/.gitignore
+++ b/examples/harness-cli/.gitignore
@@ -1,2 +1,4 @@
 .env
 playground/media/
+# Marker the sandbox writes into the workspace.
+playground/.tanstack-projected-*
diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index b87e8aa82f..65345557bb 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -29,6 +29,16 @@ Try these:
 - Images use `OPENAI_API_KEY`. Videos use Grok Imagine when `XAI_API_KEY` is set, and OpenAI Sora when it is not.
 - Code mode is on: read-only tools (file reads, read-only Notion and Linear tools) are `external_*` functions in one `execute_typescript` program, which runs in a QuickJS isolate. Ask: `in one program, list my Linear issues and search Notion for them`.
 
+## Hand work to Claude Code and Codex
+
+1. Sign in to the CLIs once: `claude login` and `codex login`.
+2. Start with `CODING_AGENTS=1`. If you use Codex with a ChatGPT login, also set `CODEX_MODEL` to the model in `~/.codex/config.toml`.
+3. Ask: `have claude_code create notes.md with one line, then have codex add a second line`.
+
+- Both agents work in `./playground` with your own logins. The API keys are removed from their processes.
+- The CLI shows each agent's tool calls and a finish line. `/fresh` starts new agent sessions.
+- On Windows, the Codex sandbox can block the folder (Access is denied). Then set `CODEX_SANDBOX_MODE=danger-full-access`, only for a folder you trust.
+
 ## Other modes
 
 - One prompt for scripts and CI: `pnpm --filter harness-cli-example start -p "list the files"`
diff --git a/examples/harness-cli/package.json b/examples/harness-cli/package.json
index a9d609b2b8..f85a495f63 100644
--- a/examples/harness-cli/package.json
+++ b/examples/harness-cli/package.json
@@ -12,7 +12,9 @@
     "@tanstack/ai": "workspace:*",
     "@tanstack/ai-acp": "workspace:*",
     "@tanstack/ai-anthropic": "workspace:*",
+    "@tanstack/ai-claude-code": "workspace:*",
     "@tanstack/ai-code-mode": "workspace:*",
+    "@tanstack/ai-codex": "workspace:*",
     "@tanstack/ai-dashboard": "workspace:*",
     "@tanstack/ai-grok": "workspace:*",
     "@tanstack/ai-harness": "workspace:*",
@@ -21,6 +23,8 @@
     "@tanstack/ai-mcp": "workspace:*",
     "@tanstack/ai-openai": "workspace:*",
     "@tanstack/ai-persistence": "workspace:*",
+    "@tanstack/ai-sandbox": "workspace:*",
+    "@tanstack/ai-sandbox-local-process": "workspace:*",
     "zod": "^4.2.0"
   },
   "devDependencies": {
diff --git a/examples/harness-cli/src/harness.ts b/examples/harness-cli/src/harness.ts
index bc0563abda..ce06031439 100644
--- a/examples/harness-cli/src/harness.ts
+++ b/examples/harness-cli/src/harness.ts
@@ -11,11 +11,20 @@ import {
   workspaceTools,
 } from '@tanstack/ai-harness/plugins'
 import { anthropicText } from '@tanstack/ai-anthropic'
+import { claudeCodeText } from '@tanstack/ai-claude-code'
 import { codeMode } from '@tanstack/ai-code-mode/harness'
+import { codexText } from '@tanstack/ai-codex'
 import { mcpConnector } from '@tanstack/ai-mcp/connector'
 import { grokVideo } from '@tanstack/ai-grok'
 import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs'
 import { openaiText, openaiVideo } from '@tanstack/ai-openai'
+import {
+  defineSandbox,
+  defineWorkspace,
+  localSource,
+} from '@tanstack/ai-sandbox'
+import { codingAgents } from '@tanstack/ai-sandbox/harness'
+import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'
 import { z } from 'zod'
 import { imageAgent, videoAgent } from './media'
 import type { AnyTextAdapter } from '@tanstack/ai'
@@ -149,6 +158,51 @@ const linear = mcpConnector({
   url: 'https://mcp.linear.app/mcp',
 })
 
+// With CODING_AGENTS=1, the lead model can hand coding work to Claude Code and
+// Codex. They work in ./playground with your own `claude login` and
+// `codex login`, so the API keys are removed from their processes.
+const coding =
+  process.env.CODING_AGENTS === '1'
+    ? [
+        codingAgents({
+          sandbox: defineSandbox({
+            id: 'playground',
+            provider: localProcessSandbox({
+              dir: root,
+              scrubEnv: ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY'],
+            }),
+            workspace: defineWorkspace({ source: localSource(root) }),
+          }),
+          agents: {
+            claude_code: {
+              adapter: claudeCodeText('claude-opus-4-8', {
+                authMode: 'host',
+                permissionMode: 'acceptEdits',
+              }),
+              description:
+                'Claude Code. Larger changes, refactors, and reviews in ./playground.',
+            },
+            codex: {
+              // A ChatGPT login supports only some models. Set CODEX_MODEL to the
+              // model in ~/.codex/config.toml.
+              adapter: codexText(process.env.CODEX_MODEL || 'gpt-5.3-codex', {
+                authMode: 'host',
+                // On Windows, the Codex sandbox can block the folder (Access is
+                // denied). Then set CODEX_SANDBOX_MODE=danger-full-access, only for
+                // a folder you trust.
+                sandboxMode:
+                  process.env.CODEX_SANDBOX_MODE === 'danger-full-access'
+                    ? 'danger-full-access'
+                    : 'workspace-write',
+                approvalPolicy: 'never',
+              }),
+              description: 'Codex. Quick fixes and tests in ./playground.',
+            },
+          },
+        }),
+      ]
+    : []
+
 export const assistant = defineHarness({
   name: 'example/coder',
   description: 'A small coding agent that works in ./playground',
@@ -174,5 +228,6 @@ export const assistant = defineHarness({
     // The program runs in a QuickJS isolate. Any @tanstack/ai-isolate-* driver
     // works here.
     codeMode({ driver: createQuickJSIsolateDriver() }),
+    ...coding,
   ],
 })
diff --git a/packages/ai-acp/src/agent/index.ts b/packages/ai-acp/src/agent/index.ts
index a9d3fc1af0..c36cb9ac8e 100644
--- a/packages/ai-acp/src/agent/index.ts
+++ b/packages/ai-acp/src/agent/index.ts
@@ -40,9 +40,11 @@ function promptText(
 
 /** One AG-UI chunk as an ACP session update, or `undefined` to skip it. */
 export function toSessionUpdate(chunk: StreamChunk): SessionUpdate | undefined {
-  // Child agent work stays inside the harness. ACP shows the main turn.
-  if ('subagentRunId' in chunk && chunk.subagentRunId) return undefined
+  // A child agent's text and thoughts stay out of the main message. Its tool
+  // calls (the edits and commands it runs) show up like the lead's own.
+  const fromChild = 'subagentRunId' in chunk && Boolean(chunk.subagentRunId)
   if (chunk.type === EventType.TEXT_MESSAGE_CONTENT) {
+    if (fromChild) return undefined
     return {
       sessionUpdate: 'agent_message_chunk',
       messageId: chunk.messageId,
@@ -50,6 +52,7 @@ export function toSessionUpdate(chunk: StreamChunk): SessionUpdate | undefined {
     }
   }
   if (chunk.type === EventType.REASONING_MESSAGE_CONTENT) {
+    if (fromChild) return undefined
     return {
       sessionUpdate: 'agent_thought_chunk',
       messageId: chunk.messageId,
diff --git a/packages/ai-acp/tests/child-updates.test.ts b/packages/ai-acp/tests/child-updates.test.ts
new file mode 100644
index 0000000000..fd67ee7526
--- /dev/null
+++ b/packages/ai-acp/tests/child-updates.test.ts
@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest'
+import { EventType } from '@tanstack/ai'
+import { toSessionUpdate } from '../src/agent'
+import type { StreamChunk } from '@tanstack/ai'
+
+const child = (event: Record<string, unknown>): StreamChunk =>
+  ({ subagentRunId: 'child-1', timestamp: 1, ...event }) as StreamChunk
+
+describe('toSessionUpdate for child agents', () => {
+  it('shows child tool calls like the lead tool calls', () => {
+    expect(
+      toSessionUpdate(
+        child({
+          type: EventType.TOOL_CALL_START,
+          toolCallId: 'edit-1',
+          toolCallName: 'Edit',
+        }),
+      ),
+    ).toEqual({
+      sessionUpdate: 'tool_call_update',
+      toolCallId: 'edit-1',
+      name: 'Edit',
+      title: 'Edit',
+      status: 'in_progress',
+    })
+    expect(
+      toSessionUpdate(
+        child({
+          type: EventType.TOOL_CALL_RESULT,
+          messageId: 'm',
+          toolCallId: 'edit-1',
+          content: 'ok',
+        }),
+      ),
+    ).toEqual({
+      sessionUpdate: 'tool_call_update',
+      toolCallId: 'edit-1',
+      status: 'completed',
+    })
+  })
+
+  it('keeps child text and thoughts out of the main message', () => {
+    expect(
+      toSessionUpdate(
+        child({
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          messageId: 'm',
+          delta: 'hi',
+        }),
+      ),
+    ).toBeUndefined()
+    expect(
+      toSessionUpdate(
+        child({
+          type: EventType.REASONING_MESSAGE_CONTENT,
+          messageId: 'r',
+          delta: 'hmm',
+        }),
+      ),
+    ).toBeUndefined()
+  })
+})
diff --git a/packages/ai-dashboard/src/ui.ts b/packages/ai-dashboard/src/ui.ts
index 4f0b2fd6ae..76d2e0c840 100644
--- a/packages/ai-dashboard/src/ui.ts
+++ b/packages/ai-dashboard/src/ui.ts
@@ -89,7 +89,7 @@ function open(session) {
 function apply(frame) {
   if (frame.type !== 'harness.event' || !current) return
   const event = frame.event
-  if (event.subagentRunId) return
+  if (event.subagentRunId) { applyChild(event); return }
   if (event.type === 'TEXT_MESSAGE_CONTENT') {
     const last = current.messages[current.messages.length - 1]
     if (last && last.kind === 'assistant' && last.op === frame.operationId) last.text += event.delta
@@ -109,6 +109,32 @@ function apply(frame) {
   }
 }
 
+// A child agent shows as one block under the message it came from: its name,
+// status, tool calls, and text.
+function applyChild(event) {
+  const children = current.children || (current.children = new Map())
+  if (event.type === 'SUBAGENT_STARTED') {
+    const node = { kind: 'agent', name: event.name || 'agent', status: 'working', tools: [], text: '' }
+    children.set(event.subagentRunId, node)
+    current.messages.push(node)
+    return
+  }
+  const node = children.get(event.subagentRunId)
+  if (!node) return
+  if (event.type === 'TEXT_MESSAGE_CONTENT') node.text += event.delta
+  else if (event.type === 'TOOL_CALL_START') node.tools.push(event.toolCallName)
+  else if (event.type === 'SUBAGENT_FINISHED') node.status = 'done'
+  else if (event.type === 'SUBAGENT_ERROR') { node.status = 'failed'; node.text += (node.text ? '\\n' : '') + event.message }
+}
+
+function messageNode(message) {
+  if (message.kind !== 'agent') return $('div', { class: 'msg ' + message.kind }, message.text)
+  return $('div', { class: 'msg agent ' + message.status },
+    $('strong', {}, 'agent ' + message.name + ' (' + message.status + ')'),
+    ...(message.tools.length ? [$('div', { class: 'tools' }, message.tools.map((tool) => 'tool ' + tool).join(', '))] : []),
+    ...(message.text ? [$('div', {}, message.text)] : []))
+}
+
 async function send(input) {
   if (input.op === 'prompt' || input.op === 'steer') current.messages.push({ kind: 'user', text: input.message })
   const receipt = await api(current.path + '/input', { method: 'POST', body: JSON.stringify({ input }) })
@@ -119,7 +145,7 @@ async function send(input) {
 function draw() {
   const main = document.getElementById('main')
   if (!current) { main.replaceChildren($('p', { class: 'muted' }, 'Pick a session.')); return }
-  const log = $('div', { class: 'log' }, ...current.messages.map((message) => $('div', { class: 'msg ' + message.kind }, message.text)))
+  const log = $('div', { class: 'log' }, ...current.messages.map(messageNode))
   const actions = []
   if (current.interrupts.length) {
     const decide = (approved) => { const resume = current.interrupts.map((interrupt) => ({ interruptId: interrupt.id, status: 'resolved', payload: approved })); current.interrupts = []; send({ op: 'resolve', resume }) }
@@ -183,6 +209,7 @@ export const DASHBOARD_HTML = `<!doctype html>
   .msg { white-space: pre-wrap; padding: 10px 12px; border-radius: 10px; background: var(--panel); max-width: 80ch; }
   .msg.user { align-self: flex-end; background: #1d3557; } .msg.tool, .msg.notice { color: var(--muted); background: transparent; padding: 2px 12px; }
   .msg.error { border: 1px solid #e5484d; }
+  .msg.agent { border-left: 3px solid #7c5cff; display: flex; flex-direction: column; gap: 4px; } .msg.agent.failed { border-left-color: #e5484d; } .msg.agent .tools { color: var(--muted); font-size: 0.9em; }
   code { background: var(--panel); padding: 2px 6px; border-radius: 6px; }
   @media (max-width: 720px) { #app { grid-template-columns: 1fr; } aside { border-right: 0; border-bottom: 1px solid var(--line); } }
 </style>
diff --git a/packages/ai-dashboard/tests/child-agents.test.ts b/packages/ai-dashboard/tests/child-agents.test.ts
new file mode 100644
index 0000000000..c5fcb36485
--- /dev/null
+++ b/packages/ai-dashboard/tests/child-agents.test.ts
@@ -0,0 +1,143 @@
+import { runInContext, createContext } from 'node:vm'
+import { describe, expect, it } from 'vitest'
+import { DASHBOARD_HTML } from '../src/ui'
+
+/** Just enough DOM for the page script: nodes with children and text. */
+class FakeNode {
+  children: Array<FakeNode> = []
+  className = ''
+  attributes: Record<string, string> = {}
+  constructor(
+    readonly tag: string,
+    readonly text = '',
+  ) {}
+  append(...children: Array<FakeNode>) {
+    this.children.push(...children)
+  }
+  replaceChildren(...children: Array<FakeNode>) {
+    this.children = children
+  }
+  setAttribute(key: string, value: string) {
+    this.attributes[key] = value
+  }
+  get textContent(): string {
+    return this.text + this.children.map((child) => child.textContent).join('')
+  }
+}
+
+function loadPage() {
+  const script = /<script>([\s\S]*)<\/script>/.exec(DASHBOARD_HTML)?.[1] ?? ''
+  const nodes = new Map<string, FakeNode>()
+  const context = createContext({
+    Node: FakeNode,
+    document: {
+      createElement: (tag: string) => new FakeNode(tag),
+      createTextNode: (text: string) => new FakeNode('#text', text),
+      getElementById: (id: string) => {
+        if (!nodes.has(id)) nodes.set(id, new FakeNode('div'))
+        return nodes.get(id)
+      },
+    },
+    location: { hash: '' },
+    history: { replaceState: () => {} },
+    localStorage: {
+      getItem: () => null,
+      setItem: () => {},
+      removeItem: () => {},
+    },
+    navigator: {},
+    setInterval: () => 0,
+    URLSearchParams,
+    Map,
+    JSON,
+  })
+  runInContext(script, context)
+  runInContext(
+    "current = { threadId: 't', messages: [], interrupts: [], questions: new Map(), running: false }",
+    context,
+  )
+  const apply = (event: Record<string, unknown>) =>
+    runInContext(
+      `apply(${JSON.stringify({ type: 'harness.event', operationId: 'op', event })})`,
+      context,
+    )
+  const messages = (): Array<Record<string, unknown>> =>
+    JSON.parse(runInContext('JSON.stringify(current.messages)', context))
+  const drawn = () => {
+    runInContext('draw()', context)
+    return nodes.get('main') ?? new FakeNode('main')
+  }
+  return { apply, messages, drawn }
+}
+
+const child = (event: Record<string, unknown>) => ({
+  subagentRunId: 'c1',
+  ...event,
+})
+
+describe('dashboard child agents', () => {
+  it('collects a child agent into one block with its tools and text', () => {
+    const page = loadPage()
+    page.apply({
+      type: 'TEXT_MESSAGE_CONTENT',
+      messageId: 'm',
+      delta: 'Delegating.',
+    })
+    page.apply(child({ type: 'SUBAGENT_STARTED', name: 'claude_code' }))
+    page.apply(
+      child({ type: 'TOOL_CALL_START', toolCallId: 't', toolCallName: 'Edit' }),
+    )
+    page.apply(
+      child({
+        type: 'TEXT_MESSAGE_CONTENT',
+        messageId: 'x',
+        delta: 'Added a test.',
+      }),
+    )
+    page.apply(child({ type: 'SUBAGENT_FINISHED' }))
+    // Events of a child the page never saw start are ignored.
+    page.apply({
+      subagentRunId: 'other',
+      type: 'TEXT_MESSAGE_CONTENT',
+      delta: 'lost',
+    })
+
+    expect(page.messages()).toEqual([
+      { kind: 'assistant', op: 'op', text: 'Delegating.' },
+      {
+        kind: 'agent',
+        name: 'claude_code',
+        status: 'done',
+        tools: ['Edit'],
+        text: 'Added a test.',
+      },
+    ])
+    const block = page
+      .drawn()
+      .children.flatMap((node) => node.children)
+      .find((node) => node.className === 'msg agent done')
+    expect(block?.textContent).toBe(
+      'agent claude_code (done)tool EditAdded a test.',
+    )
+  })
+
+  it('marks a failed child and shows its error', () => {
+    const page = loadPage()
+    page.apply(child({ type: 'SUBAGENT_STARTED' }))
+    page.apply(child({ type: 'SUBAGENT_ERROR', message: 'sandbox is down' }))
+    expect(page.messages()).toEqual([
+      {
+        kind: 'agent',
+        name: 'agent',
+        status: 'failed',
+        tools: [],
+        text: 'sandbox is down',
+      },
+    ])
+    const block = page
+      .drawn()
+      .children.flatMap((node) => node.children)
+      .find((node) => node.className === 'msg agent failed')
+    expect(block?.textContent).toBe('agent agent (failed)sandbox is down')
+  })
+})
diff --git a/packages/ai-harness-cli/src/interactive.tsx b/packages/ai-harness-cli/src/interactive.tsx
index fbfc35bb45..081b9d078e 100644
--- a/packages/ai-harness-cli/src/interactive.tsx
+++ b/packages/ai-harness-cli/src/interactive.tsx
@@ -28,6 +28,13 @@ function Entry({ entry }: { entry: ViewEntry }) {
       return <Text color="yellow">{`  - ${entry.text}`}</Text>
     case 'notice':
       return <Text color="gray">{entry.text}</Text>
+    case 'agent': {
+      // The child's latest words, live, while it works.
+      const latest = entry.answer.replace(/\s+/g, ' ').trim().slice(-80)
+      return (
+        <Text color="magenta">{`  - ${entry.text}${latest ? `: ${latest}` : ''}`}</Text>
+      )
+    }
   }
 }
 
diff --git a/packages/ai-harness-cli/src/lines.ts b/packages/ai-harness-cli/src/lines.ts
index 741005b97d..750d98a4cb 100644
--- a/packages/ai-harness-cli/src/lines.ts
+++ b/packages/ai-harness-cli/src/lines.ts
@@ -53,7 +53,9 @@ export async function runLines(
         if (midLine) stdout.write('\n')
         stdout.write(last.text)
         midLine = true
-      } else {
+      } else if (next.length > entries.length) {
+        // Only new entries print. An earlier entry that changed (a child's
+        // answer building up) prints later, in its finish line.
         line(`[${last.text}]`)
       }
       entries = next
diff --git a/packages/ai-harness-cli/src/session-view.ts b/packages/ai-harness-cli/src/session-view.ts
index 43df00f9bb..1e409dd0d6 100644
--- a/packages/ai-harness-cli/src/session-view.ts
+++ b/packages/ai-harness-cli/src/session-view.ts
@@ -9,6 +9,14 @@ export type ViewEntry =
   | { kind: 'assistant'; operationId: string; text: string }
   | { kind: 'tool'; text: string }
   | { kind: 'notice'; text: string }
+  /** A child agent. `answer` collects its text for the finish line. */
+  | {
+      kind: 'agent'
+      subagentRunId: string
+      name: string
+      text: string
+      answer: string
+    }
 
 /**
  * Fold one session event into the view entries. Returns the new list, or the
@@ -20,13 +28,7 @@ export function applyEvent(
 ): Array<ViewEntry> {
   const { event, operationId } = entry
   if ('subagentRunId' in event && event.subagentRunId) {
-    if (event.type === EventType.SUBAGENT_STARTED) {
-      return [
-        ...entries,
-        { kind: 'tool', text: `agent ${event.name ?? ''} started` },
-      ]
-    }
-    return entries
+    return applyChildEvent(entries, event.subagentRunId, event)
   }
   if (event.type === EventType.TEXT_MESSAGE_CONTENT) {
     const last = entries.at(-1)
@@ -152,3 +154,72 @@ export async function waitIdle(session: HarnessSession): Promise<void> {
     await new Promise((resolve) => setTimeout(resolve, 20))
   }
 }
+
+/** The first 200 characters of a child's answer, on one line. */
+function shortAnswer(text: string): string {
+  const line = text.replace(/\s+/g, ' ').trim()
+  return line.length > 200 ? `${line.slice(0, 200)}...` : line
+}
+
+/**
+ * Child agent work: its start, its tool calls, and a finish line with the
+ * start of its answer. The answer builds up on the agent entry, which is not
+ * the last entry, so line mode does not print it until the child finishes.
+ */
+function applyChildEvent(
+  entries: Array<ViewEntry>,
+  subagentRunId: string,
+  event: SessionEvent['event'],
+): Array<ViewEntry> {
+  const index = entries.findLastIndex(
+    (item) => item.kind === 'agent' && item.subagentRunId === subagentRunId,
+  )
+  const agent = entries[index]
+  const found = agent?.kind === 'agent' ? agent : undefined
+  const name = found?.name ?? 'agent'
+  switch (event.type) {
+    case EventType.SUBAGENT_STARTED: {
+      const started = event.name ?? 'agent'
+      return [
+        ...entries,
+        {
+          kind: 'agent',
+          subagentRunId,
+          name: started,
+          text: `agent ${started} started`,
+          answer: '',
+        },
+      ]
+    }
+    case EventType.TEXT_MESSAGE_CONTENT: {
+      if (!found) return entries
+      const next = [...entries]
+      next[index] = { ...found, answer: found.answer + event.delta }
+      return next
+    }
+    case EventType.TOOL_CALL_START:
+      return [
+        ...entries,
+        { kind: 'tool', text: `${name}: tool ${event.toolCallName}` },
+      ]
+    case EventType.SUBAGENT_FINISHED: {
+      const answer = shortAnswer(found?.answer ?? '')
+      return [
+        ...entries,
+        {
+          kind: 'tool',
+          text: answer
+            ? `agent ${name} finished: ${answer}`
+            : `agent ${name} finished`,
+        },
+      ]
+    }
+    case EventType.SUBAGENT_ERROR:
+      return [
+        ...entries,
+        { kind: 'notice', text: `agent ${name} failed: ${event.message}` },
+      ]
+    default:
+      return entries
+  }
+}
diff --git a/packages/ai-harness-cli/tests/child-view.test.ts b/packages/ai-harness-cli/tests/child-view.test.ts
new file mode 100644
index 0000000000..e3a8cd0d14
--- /dev/null
+++ b/packages/ai-harness-cli/tests/child-view.test.ts
@@ -0,0 +1,226 @@
+import { PassThrough } from 'node:stream'
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { EventType, defineAgent } from '@tanstack/ai'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { runLines } from '../src/lines'
+import { applyEvent } from '../src/session-view'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import type { SessionEvent } from '@tanstack/ai-harness'
+import type { ViewEntry } from '../src/session-view'
+
+const at = (event: StreamChunk): SessionEvent => ({
+  cursor: '1',
+  operationId: 'op',
+  event,
+})
+const child = (event: Record<string, unknown>): StreamChunk =>
+  ({ subagentRunId: 'child-1', timestamp: 1, ...event }) as StreamChunk
+
+function fold(events: Array<StreamChunk>): Array<ViewEntry> {
+  return events.reduce(
+    (entries, event) => applyEvent(entries, at(event)),
+    [] as Array<ViewEntry>,
+  )
+}
+
+describe('child agent entries', () => {
+  it('shows the start, tool calls, and a finish line with the answer', () => {
+    const entries = fold([
+      child({ type: EventType.SUBAGENT_STARTED, name: 'claude_code' }),
+      child({
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'm',
+        delta: 'Added a\n',
+      }),
+      child({
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 't',
+        toolCallName: 'Edit',
+      }),
+      child({
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'm',
+        delta: '  test.',
+      }),
+      child({ type: EventType.SUBAGENT_FINISHED }),
+    ])
+    expect(entries.map((entry) => entry.text)).toEqual([
+      'agent claude_code started',
+      'claude_code: tool Edit',
+      'agent claude_code finished: Added a test.',
+    ])
+    expect(entries[0]).toMatchObject({
+      kind: 'agent',
+      answer: 'Added a\n  test.',
+    })
+  })
+
+  it('shortens long answers, reports errors, and names unknown children "agent"', () => {
+    const long = 'word '.repeat(60)
+    const finished = fold([
+      child({ type: EventType.SUBAGENT_STARTED, name: 'codex' }),
+      child({
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'm',
+        delta: long,
+      }),
+      child({ type: EventType.SUBAGENT_FINISHED }),
+    ])
+    const last = finished.at(-1)?.text ?? ''
+    expect(last.startsWith('agent codex finished: word word')).toBe(true)
+    expect(last.endsWith('...')).toBe(true)
+
+    expect(
+      fold([
+        child({ type: EventType.SUBAGENT_STARTED }),
+        child({ type: EventType.SUBAGENT_FINISHED }),
+      ]).map((entry) => entry.text),
+    ).toEqual(['agent agent started', 'agent agent finished'])
+
+    const orphan = fold([
+      child({
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'm',
+        delta: 'lost',
+      }),
+      child({
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 't',
+        toolCallName: 'Read',
+      }),
+      child({ type: EventType.SUBAGENT_ERROR, message: 'crashed' }),
+      child({ type: EventType.STEP_STARTED, stepName: 's' }),
+    ])
+    expect(orphan.map((entry) => entry.text)).toEqual([
+      'agent: tool Read',
+      'agent agent failed: crashed',
+    ])
+  })
+})
+
+const 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,
+}
+
+function model(turns: Array<Array<StreamChunk>>): AnyTextAdapter {
+  let call = 0
+  return {
+    kind: 'text',
+    name: 'mock',
+    model: 'mock',
+    '~types': TYPES,
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+    chatStream: () => {
+      const chunks = turns[call] ?? []
+      call += 1
+      return (async function* () {
+        yield* chunks
+      })()
+    },
+  }
+}
+
+const say = (text: string, id: string): Array<StreamChunk> => [
+  { type: EventType.RUN_STARTED, runId: 'r', threadId: 't', timestamp: 1 },
+  {
+    type: EventType.TEXT_MESSAGE_START,
+    messageId: id,
+    role: 'assistant',
+    timestamp: 1,
+  },
+  {
+    type: EventType.TEXT_MESSAGE_CONTENT,
+    messageId: id,
+    delta: text,
+    timestamp: 1,
+  },
+  { type: EventType.TEXT_MESSAGE_END, messageId: id, timestamp: 1 },
+  {
+    type: EventType.RUN_FINISHED,
+    runId: 'r',
+    threadId: 't',
+    timestamp: 1,
+    metadata: { tanstack: { finishReason: 'stop' } },
+  },
+]
+
+describe('line mode with a child agent', () => {
+  it('prints the child once, in its finish line, and the lead answer after it', async () => {
+    const helper = defineAgent({
+      name: 'helper',
+      description: 'Helps',
+      inputSchema: z.object({ task: z.string() }),
+      run: (ctx) =>
+        ctx.chat({
+          adapter: model([say('child says hi', 'c1')]),
+          messages: [{ role: 'user', content: ctx.input.task }],
+        }),
+    })
+    const lead = model([
+      [
+        {
+          type: EventType.RUN_STARTED,
+          runId: 'r',
+          threadId: 't',
+          timestamp: 1,
+        },
+        {
+          type: EventType.TOOL_CALL_START,
+          toolCallId: 'call-1',
+          toolCallName: 'helper',
+          timestamp: 1,
+        },
+        {
+          type: EventType.TOOL_CALL_ARGS,
+          toolCallId: 'call-1',
+          delta: '{"task":"say hi"}',
+          timestamp: 1,
+        },
+        { type: EventType.TOOL_CALL_END, toolCallId: 'call-1', timestamp: 1 },
+        {
+          type: EventType.RUN_FINISHED,
+          runId: 'r',
+          threadId: 't',
+          timestamp: 1,
+          metadata: { tanstack: { finishReason: 'tool_calls' } },
+        },
+      ],
+      say('lead done', 'l1'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/child-lines',
+        adapter: lead,
+        subagents: { agents: [helper] },
+      }),
+      { threadId: 't' },
+    )
+    const input = new PassThrough()
+    let out = ''
+    const running = runLines(session, input, {
+      write: (text: string) => (out += text),
+    })
+    input.end('go\n')
+    await running
+    await host.close()
+
+    expect(out).toContain('[agent helper started]')
+    expect(out).toContain('[agent helper finished: child says hi]')
+    expect(out.split('child says hi')).toHaveLength(2)
+    expect(out.indexOf('lead done')).toBeGreaterThan(out.indexOf('finished'))
+  })
+})
diff --git a/packages/ai-harness-cli/tests/commands.test.ts b/packages/ai-harness-cli/tests/commands.test.ts
index 00fb3735c7..aa6fc6857d 100644
--- a/packages/ai-harness-cli/tests/commands.test.ts
+++ b/packages/ai-harness-cli/tests/commands.test.ts
@@ -289,8 +289,9 @@ describe('applyEvent', () => {
       'Error: model down',
       'agent painter started',
     ])
-    // Other child events and unknown custom events change nothing.
-    const unchanged = applyEvent(
+    // Child text builds up on the agent entry without adding a line, and an
+    // unknown custom event changes nothing.
+    const withText = applyEvent(
       shown,
       entry({
         type: EventType.TEXT_MESSAGE_CONTENT,
@@ -300,7 +301,11 @@ describe('applyEvent', () => {
         timestamp: 1,
       } as StreamChunk),
     )
-    expect(unchanged).toBe(shown)
+    expect(withText).toHaveLength(shown.length)
+    expect(withText.at(-1)).toMatchObject({
+      kind: 'agent',
+      answer: 'child text',
+    })
     expect(applyEvent(shown, entry(custom('other.event', {})))).toBe(shown)
   })
 })
diff --git a/packages/ai-harness/src/plugins.ts b/packages/ai-harness/src/plugins.ts
index 92b39e4367..ddc2fbeb06 100644
--- a/packages/ai-harness/src/plugins.ts
+++ b/packages/ai-harness/src/plugins.ts
@@ -51,6 +51,12 @@ export interface PluginContributions {
   generationMiddleware?: ReadonlyArray<AnyGenerationMiddleware>
   /** Agents added to `session.agents`. */
   agents?: ReadonlyArray<AnyAgent>
+  /**
+   * Agents the main model can call as tools, merged into the turn's
+   * `chat({ subagents })` after `defineHarness({ subagents })`. They are
+   * also added to `session.agents`.
+   */
+  subagents?: ReadonlyArray<AnyAgent>
   /** User actions, keyed by name. Run with `session.command(name, input)`. */
   commands?: Record<string, AnyCommand>
   /** Session settings, keyed by name. Read with `ctx.config.get(name)`. */
@@ -261,6 +267,8 @@ export interface MountedPlugins {
     prepare: NonNullable<PluginContributions['prepareTools']>
     owner: string
   }>
+  /** Agents plugins give the main model, in plugin order. */
+  subagents: Array<AnyAgent>
   /** Who contributed what, for `session.inspect()`. */
   owners: {
     plugins: Array<{
@@ -445,6 +453,7 @@ export async function mountPlugins(
   const adapters: Array<() => AnyTextAdapter | undefined> = []
   const discoverers: MountedPlugins['discoverers'] = []
   const preparers: MountedPlugins['preparers'] = []
+  const subagents: Array<AnyAgent> = []
   const services = env.services ?? NO_SERVICES
 
   try {
@@ -590,6 +599,10 @@ export async function mountPlugins(
       for (const agent of contributions.agents ?? []) {
         env.registry.add(agent, plugin.name)
       }
+      for (const agent of contributions.subagents ?? []) {
+        env.registry.add(agent, plugin.name)
+        subagents.push(agent)
+      }
     }
     for (const plugin of plugins) {
       for (const produces of plugin.needs?.produces ?? []) {
@@ -641,6 +654,7 @@ export async function mountPlugins(
     adapters,
     discoverers,
     preparers,
+    subagents,
     owners: {
       plugins: plugins.map((plugin) => ({
         name: plugin.name,
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 2c2352679b..b8b0ab2085 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -1067,7 +1067,12 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         session?.capabilityBridge,
         runPlugins?.capabilityBridge,
       ].filter((bridge): bridge is AnyChatMiddleware => bridge !== undefined)
-      const subagents = this.harness.subagents
+      // Agents the model can call: the harness's own, then the plugins'.
+      const subagentList = [
+        ...(this.harness.subagents?.agents ?? []),
+        ...(session?.subagents ?? []),
+        ...(runPlugins?.subagents ?? []),
+      ]
       const picked = [
         ...(session?.adapters ?? []),
         ...(runPlugins?.adapters ?? []),
@@ -1115,10 +1120,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           ...(runPlugins?.middleware ?? []),
           this.steering(),
         ],
-        ...(subagents
+        ...(subagentList.length > 0
           ? {
               subagents: {
-                ...subagents,
+                ...this.harness.subagents,
+                agents: subagentList,
                 limits: this.limits(),
                 binding: this.binding(),
               },
diff --git a/packages/ai-harness/tests/plugin-subagents.test.ts b/packages/ai-harness/tests/plugin-subagents.test.ts
new file mode 100644
index 0000000000..2e50f2750d
--- /dev/null
+++ b/packages/ai-harness/tests/plugin-subagents.test.ts
@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { defineAgent } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness, definePlugin } from '../src'
+import { mockAdapter, text, toolCall } from './helpers'
+
+const agentNamed = (name: string, reply: string) =>
+  defineAgent({
+    name,
+    description: `The ${name} agent`,
+    inputSchema: z.object({ task: z.string() }),
+    run: async (ctx) => `${reply}: ${ctx.input.task}`,
+  })
+
+const toolNames = (call: any): Array<string> =>
+  (call.tools ?? []).map((tool: { name: string }) => tool.name)
+
+describe('plugin subagents', () => {
+  it('lets the model call agents that session and run plugins give, after the harness ones', async () => {
+    const lead = agentNamed('lead_helper', 'lead')
+    const fromSession = definePlugin({
+      name: 'test/session-agents',
+      setup: () => ({ subagents: [agentNamed('painter', 'painted')] }),
+    })
+    const fromRun = definePlugin({
+      name: 'test/run-agents',
+      lifetime: 'run',
+      setup: () => ({ subagents: [agentNamed('writer', 'wrote')] }),
+    })
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('painter', { task: 'a fox' }),
+      () => text('done'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/plugin-subagents',
+        adapter,
+        subagents: { agents: [lead] },
+        plugins: () => [fromSession, fromRun],
+      }),
+      { threadId: 't' },
+    )
+
+    const turn = await session.prompt('paint a fox')
+    expect(turn.text).toBe('done')
+    expect(toolNames(calls[0])).toEqual(['lead_helper', 'painter', 'writer'])
+    expect(JSON.stringify(calls[1].messages)).toContain('painted: a fox')
+    // Plugin subagents are session agents too, so commands and clients can run them.
+    expect(await session.agent('painter')?.run({ task: 'a cat' })).toBe(
+      'painted: a cat',
+    )
+    await host.close()
+  })
+
+  it('gives no agent tools when neither the harness nor a plugin has any', async () => {
+    const { adapter, calls } = mockAdapter([() => text('hi')])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/no-subagents',
+        adapter,
+        plugins: () => [
+          definePlugin({ name: 'test/empty', setup: () => ({}) }),
+        ],
+      }),
+      { threadId: 't' },
+    )
+    await session.prompt('hello')
+    expect(toolNames(calls[0])).toEqual([])
+    await host.close()
+  })
+})
diff --git a/packages/ai-sandbox/package.json b/packages/ai-sandbox/package.json
index e1b7c0d814..b725e56d79 100644
--- a/packages/ai-sandbox/package.json
+++ b/packages/ai-sandbox/package.json
@@ -30,6 +30,10 @@
       "types": "./dist/esm/index.d.ts",
       "import": "./dist/esm/index.js"
     },
+    "./harness": {
+      "types": "./dist/esm/harness.d.ts",
+      "import": "./dist/esm/harness.js"
+    },
     "./ngrok": {
       "types": "./dist/esm/ngrok.d.ts",
       "import": "./dist/esm/ngrok.js"
@@ -84,10 +88,14 @@
   "peerDependencies": {
     "@ngrok/ngrok": "^1.0.0",
     "@tanstack/ai": "workspace:^",
+    "@tanstack/ai-harness": "workspace:^",
     "@tanstack/ai-persistence": "workspace:^",
     "vitest": "^4.1.10"
   },
   "peerDependenciesMeta": {
+    "@tanstack/ai-harness": {
+      "optional": true
+    },
     "@ngrok/ngrok": {
       "optional": true
     },
@@ -101,6 +109,7 @@
   "devDependencies": {
     "@ngrok/ngrok": "^1.7.0",
     "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-harness": "workspace:*",
     "@tanstack/ai-persistence": "workspace:*",
     "@vitest/coverage-v8": "4.1.10",
     "vitest": "^4.1.10"
diff --git a/packages/ai-sandbox/src/harness.ts b/packages/ai-sandbox/src/harness.ts
new file mode 100644
index 0000000000..f320e8588b
--- /dev/null
+++ b/packages/ai-sandbox/src/harness.ts
@@ -0,0 +1,210 @@
+import { EventType, defineAgent } from '@tanstack/ai'
+import { defineCommand, definePlugin } from '@tanstack/ai-harness'
+import { InMemorySandboxInstanceStore } from './instance-store'
+import { withSandbox } from './middleware'
+import type {
+  AnyChatMiddleware,
+  AnyTextAdapter,
+  JSONSchema,
+  StreamChunk,
+} from '@tanstack/ai'
+import type { SandboxMiddlewareOptions } from './middleware'
+import type { SandboxDefinition } from './sandbox'
+
+export interface CodingAgentConfig {
+  /** A coding-agent adapter: `claudeCodeText`, `codexText`, `grokBuildText`, `acpCompatibleText`, and more. */
+  adapter: AnyTextAdapter
+  /** When the lead model should pick this agent. */
+  description: string
+  /** Options for every call, for example Claude Code's `permissionMode`. */
+  modelOptions?: Record<string, unknown>
+  /**
+   * Options added when the harness `mode` setting is `plan`. Default: Claude
+   * Code `{ permissionMode: 'plan' }` and Codex `{ sandboxMode: 'read-only' }`.
+   */
+  planModelOptions?: Record<string, unknown>
+}
+
+export interface CodingAgentsOptions {
+  /** Where the agents work. One sandbox per harness thread (or per agent). */
+  sandbox: SandboxDefinition
+  /** The agents, keyed by the tool name the lead model sees. */
+  agents: Record<string, CodingAgentConfig>
+  /**
+   * `shared` (default): every agent of a thread works in one sandbox, one
+   * agent at a time. `per-agent`: each agent gets its own sandbox.
+   */
+  workspace?: 'shared' | 'per-agent'
+  /** Passed to `withSandbox`. Default: a memory instance store. */
+  sandboxOptions?: SandboxMiddlewareOptions
+}
+
+const PLAN_DEFAULTS: Record<string, Record<string, unknown>> = {
+  'claude-code': { permissionMode: 'plan' },
+  codex: { sandboxMode: 'read-only' },
+}
+
+const TASK_SCHEMA: JSONSchema = {
+  type: 'object',
+  properties: {
+    task: {
+      type: 'string',
+      description:
+        'The whole task: what to change, where, and how to check it. The agent sees only this text and the workspace.',
+    },
+  },
+  required: ['task'],
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+/**
+ * Run `open` while holding the lock for `key`. The lock is taken when the
+ * stream is first read, so a stream nobody reads never holds it.
+ */
+async function* serialized(
+  tails: Map<string, Promise<void>>,
+  key: string,
+  open: () => AsyncIterable<StreamChunk>,
+): AsyncGenerator<StreamChunk> {
+  const previous = tails.get(key) ?? Promise.resolve()
+  let release = () => {}
+  const current = new Promise<void>((resolve) => (release = resolve))
+  const tail = previous.then(() => current)
+  tails.set(key, tail)
+  await previous
+  try {
+    yield* open()
+  } finally {
+    release()
+    if (tails.get(key) === tail) tails.delete(key)
+  }
+}
+
+/**
+ * A harness plugin that lets the lead model hand coding work to Claude Code,
+ * Codex, Grok Build, or any ACP agent:
+ *
+ * - each agent runs in `sandbox`, so nobody wires `withSandbox` by hand;
+ * - each agent keeps its own coding session per thread, also after a restart
+ *   (`/fresh [agent]` starts over);
+ * - the harness `plan` mode starts the agents read-only.
+ *
+ * @example
+ * ```ts
+ * codingAgents({
+ *   sandbox: defineSandbox({ id: 'code', provider: localProcessSandbox() }),
+ *   agents: {
+ *     claude_code: { adapter: claudeCodeText('claude-opus-4-8'), description: 'Large refactors' },
+ *     codex: { adapter: codexText('gpt-5.5'), description: 'Quick fixes and tests' },
+ *   },
+ * })
+ * ```
+ */
+export function codingAgents(options: CodingAgentsOptions) {
+  const shared = (options.workspace ?? 'shared') === 'shared'
+  const sandboxOptions: SandboxMiddlewareOptions = {
+    instances: new InMemorySandboxInstanceStore(),
+    ...options.sandboxOptions,
+  }
+  // ponytail: an in-process lock per thread. Several hosts on one sandbox need a shared lock store.
+  const tails = new Map<string, Promise<void>>()
+  const names = Object.keys(options.agents)
+
+  return definePlugin({
+    name: 'tanstack/coding-agents',
+    setup: (ctx) => {
+      const state = ctx.state<{ sessions: Record<string, string> }>({
+        sessions: {},
+      })
+      // Saves the session id the adapter reports (`claude-code.session-id`, ...).
+      const capture = (agent: string): AnyChatMiddleware => ({
+        name: 'tanstack/coding-agents:session',
+        onChunk: async (_run, chunk) => {
+          if (chunk.type !== EventType.CUSTOM) return
+          if (!chunk.name.endsWith('.session-id')) return
+          const value: unknown = chunk.value
+          if (!isRecord(value) || typeof value.sessionId !== 'string') return
+          const sessionId = value.sessionId
+          await state.update((current) => ({
+            sessions: { ...current.sessions, [agent]: sessionId },
+          }))
+        },
+      })
+
+      const subagents = Object.entries(options.agents).map(([name, config]) =>
+        defineAgent({
+          name,
+          description: config.description,
+          inputSchema: TASK_SCHEMA,
+          run: async (run) => {
+            const input: unknown = run.input
+            const task =
+              isRecord(input) && typeof input.task === 'string'
+                ? input.task
+                : ''
+            const sessionId = (await state.get()).sessions[name]
+            const plan =
+              ctx.config.get('mode') === 'plan'
+                ? (config.planModelOptions ??
+                  PLAN_DEFAULTS[config.adapter.name] ??
+                  {})
+                : {}
+            const modelOptions = {
+              ...config.modelOptions,
+              ...plan,
+              ...(sessionId ? { sessionId } : {}),
+            }
+            // The harness thread, not `run.threadId`: a child's own thread is
+            // `<thread>:<agent>` by default.
+            const thread = ctx.session.threadId
+            const threadId = shared ? thread : `${thread}:${name}`
+            const open = () =>
+              run.chat({
+                adapter: config.adapter,
+                messages: [{ role: 'user', content: task }],
+                threadId,
+                ...(Object.keys(modelOptions).length > 0
+                  ? { modelOptions }
+                  : {}),
+                middleware: [
+                  withSandbox(options.sandbox, sandboxOptions),
+                  capture(name),
+                ],
+              }) as AsyncIterable<StreamChunk>
+            return shared ? serialized(tails, threadId, open) : open()
+          },
+        }),
+      )
+
+      return {
+        subagents,
+        commands: {
+          fresh: defineCommand({
+            description: `Start new coding-agent sessions (all, or one of: ${names.join(', ')})`,
+            run: async (input: unknown) => {
+              const name = typeof input === 'string' ? input.trim() : ''
+              if (name && !names.includes(name)) {
+                return `Unknown coding agent "${name}". Agents: ${names.join(', ')}.`
+              }
+              await state.update((current) => ({
+                sessions: name
+                  ? Object.fromEntries(
+                      Object.entries(current.sessions).filter(
+                        ([agent]) => agent !== name,
+                      ),
+                    )
+                  : {},
+              }))
+              return name
+                ? `${name} starts a new session next time.`
+                : 'Every coding agent starts a new session next time.'
+            },
+          }),
+        },
+      }
+    },
+  })
+}
diff --git a/packages/ai-sandbox/tests/coding-agents.test.ts b/packages/ai-sandbox/tests/coding-agents.test.ts
new file mode 100644
index 0000000000..3d9dfc1332
--- /dev/null
+++ b/packages/ai-sandbox/tests/coding-agents.test.ts
@@ -0,0 +1,377 @@
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { EventType } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { permissions } from '@tanstack/ai-harness/plugins'
+import { codingAgents } from '../src/harness'
+import { defineSandbox } from '../src/sandbox'
+import { defineWorkspace } from '../src/workspace'
+import { makeFakeProvider } from './fakes'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+
+const now = () => Date.now()
+// A small local project the sandboxes start from.
+const project = mkdtempSync(join(tmpdir(), 'coding-agents-'))
+writeFileSync(join(project, 'README.md'), '# demo\n')
+const 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,
+}
+
+function textChunks(content: string): Array<StreamChunk> {
+  return [
+    {
+      type: EventType.TEXT_MESSAGE_START,
+      messageId: `m-${content}`,
+      role: 'assistant',
+      timestamp: now(),
+    },
+    {
+      type: EventType.TEXT_MESSAGE_CONTENT,
+      messageId: `m-${content}`,
+      delta: content,
+      timestamp: now(),
+    },
+    {
+      type: EventType.TEXT_MESSAGE_END,
+      messageId: `m-${content}`,
+      timestamp: now(),
+    },
+    {
+      type: EventType.RUN_FINISHED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: now(),
+      metadata: { tanstack: { finishReason: 'stop' } },
+    },
+  ]
+}
+
+/** A lead model that calls the given tools in one step, then answers. */
+function lead(steps: Array<Array<[string, string]>>) {
+  let call = 0
+  const adapter: AnyTextAdapter = {
+    kind: 'text',
+    name: 'lead',
+    model: 'lead',
+    '~types': TYPES,
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+    chatStream: () => {
+      const step = steps[call]
+      call += 1
+      return (async function* (): AsyncGenerator<StreamChunk> {
+        yield {
+          type: EventType.RUN_STARTED,
+          runId: 'r',
+          threadId: 't',
+          timestamp: now(),
+        }
+        if (!step) {
+          yield* textChunks('lead done')
+          return
+        }
+        for (const [index, [tool, task]] of step.entries()) {
+          const id = `call-${call}-${index}`
+          yield {
+            type: EventType.TOOL_CALL_START,
+            toolCallId: id,
+            toolCallName: tool,
+            timestamp: now(),
+          }
+          yield {
+            type: EventType.TOOL_CALL_ARGS,
+            toolCallId: id,
+            delta: JSON.stringify({ task }),
+            timestamp: now(),
+          }
+          yield {
+            type: EventType.TOOL_CALL_END,
+            toolCallId: id,
+            timestamp: now(),
+          }
+        }
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId: 'r',
+          threadId: 't',
+          timestamp: now(),
+          metadata: { tanstack: { finishReason: 'tool_calls' } },
+        }
+      })()
+    },
+  }
+  return adapter
+}
+
+/**
+ * A stand-in coding agent. It records each call, reports a new session id the
+ * way Claude Code does (`<name>.session-id`), and answers with the task.
+ */
+function codingAgent(name: string, options: { wait?: Promise<void> } = {}) {
+  const calls: Array<any> = []
+  const log: Array<string> = []
+  const adapter: AnyTextAdapter = {
+    kind: 'text',
+    name,
+    model: `${name}-model`,
+    '~types': TYPES,
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+    chatStream: (chatOptions: any) => {
+      calls.push(chatOptions)
+      const index = calls.length
+      return (async function* (): AsyncGenerator<StreamChunk> {
+        log.push(`${name} start ${index}`)
+        yield {
+          type: EventType.RUN_STARTED,
+          runId: 'c',
+          threadId: 't',
+          timestamp: now(),
+        }
+        yield {
+          type: EventType.CUSTOM,
+          name: `${name}.session-id`,
+          value: { sessionId: `${name}-session-${index}` },
+          timestamp: now(),
+        }
+        if (options.wait) await options.wait
+        const task = String(chatOptions.messages.at(-1)?.content ?? '')
+        yield* textChunks(`${name} did: ${task}`)
+        log.push(`${name} end ${index}`)
+      })()
+    },
+  }
+  return { adapter, calls, log }
+}
+
+async function open(input: {
+  leadSteps: Array<Array<[string, string]>>
+  agents: Record<
+    string,
+    { adapter: AnyTextAdapter; planModelOptions?: Record<string, unknown> }
+  >
+  workspace?: 'shared' | 'per-agent'
+  persistence?: ReturnType<typeof memoryPersistence>
+}) {
+  const provider = makeFakeProvider()
+  const persistence = input.persistence ?? memoryPersistence()
+  const host = createHarnessHost({ persistence })
+  const harness = defineHarness({
+    name: 'test/coding-lead',
+    adapter: lead(input.leadSteps),
+    plugins: () => [
+      permissions(),
+      codingAgents({
+        sandbox: defineSandbox({
+          id: 'code',
+          provider,
+          workspace: defineWorkspace({
+            source: { type: 'local', path: project },
+          }),
+        }),
+        agents: Object.fromEntries(
+          Object.entries(input.agents).map(([name, agent]) => [
+            name,
+            { description: `The ${name} agent`, ...agent },
+          ]),
+        ),
+        ...(input.workspace ? { workspace: input.workspace } : {}),
+      }),
+    ],
+  })
+  const session = await host.open(harness, { threadId: 't' })
+  return { host, session, provider, persistence, harness }
+}
+
+describe('codingAgents', () => {
+  it('runs a delegate in the sandbox and resumes its session on the next call', async () => {
+    const claude = codingAgent('claude-code')
+    const { host, session, provider } = await open({
+      leadSteps: [
+        [['claude_code', 'add a test']],
+        [],
+        [['claude_code', 'fix the test']],
+      ],
+      agents: { claude_code: { adapter: claude.adapter } },
+    })
+    await session.prompt('first')
+    await session.prompt('second')
+
+    expect(claude.calls).toHaveLength(2)
+    expect(claude.calls[0].messages).toEqual([
+      { role: 'user', content: 'add a test' },
+    ])
+    expect(claude.calls[0].modelOptions?.sessionId).toBeUndefined()
+    // The second call resumes the session the first call reported.
+    expect(claude.calls[1].modelOptions).toEqual({
+      sessionId: 'claude-code-session-1',
+    })
+    expect(claude.calls[0].threadId).toBe('t')
+    // One sandbox for the thread, created once.
+    expect(provider.calls.create).toBe(1)
+    await host.close()
+  })
+
+  it('lists the delegates as session agents and forgets sessions with /fresh', async () => {
+    const claude = codingAgent('claude-code')
+    const codex = codingAgent('codex')
+    const { host, session } = await open({
+      leadSteps: [
+        [['claude_code', 'one']],
+        [],
+        [['codex', 'two']],
+        [],
+        [['claude_code', 'three']],
+      ],
+      agents: {
+        claude_code: { adapter: claude.adapter },
+        codex: { adapter: codex.adapter },
+      },
+    })
+    expect(session.registry.list().map((agent) => agent.name)).toEqual([
+      'claude_code',
+      'codex',
+    ])
+    await session.prompt('a')
+    await session.prompt('b')
+    expect(await session.command('fresh', 'nope')).toBe(
+      'Unknown coding agent "nope". Agents: claude_code, codex.',
+    )
+    expect(await session.command('fresh', 'claude_code')).toBe(
+      'claude_code starts a new session next time.',
+    )
+    await session.prompt('c')
+    expect(claude.calls[1].modelOptions?.sessionId).toBeUndefined()
+    expect(await session.command('fresh')).toBe(
+      'Every coding agent starts a new session next time.',
+    )
+    await host.close()
+  })
+
+  it('keeps sessions across a host restart', async () => {
+    const persistence = memoryPersistence()
+    const first = codingAgent('claude-code')
+    const before = await open({
+      leadSteps: [[['claude_code', 'start']]],
+      agents: { claude_code: { adapter: first.adapter } },
+      persistence,
+    })
+    await before.session.prompt('go')
+    await before.host.close()
+
+    const second = codingAgent('claude-code')
+    const after = await open({
+      leadSteps: [[['claude_code', 'continue']]],
+      agents: { claude_code: { adapter: second.adapter } },
+      persistence,
+    })
+    await after.session.prompt('go on')
+    expect(second.calls[0].modelOptions).toEqual({
+      sessionId: 'claude-code-session-1',
+    })
+    await after.host.close()
+  })
+
+  it('runs shared-workspace delegates one at a time, and per-agent ones side by side', async () => {
+    let release = () => {}
+    const gate = new Promise<void>((resolve) => (release = resolve))
+    const claude = codingAgent('claude-code', { wait: gate })
+    const codex = codingAgent('codex')
+    const shared = await open({
+      leadSteps: [],
+      agents: {
+        claude_code: { adapter: claude.adapter },
+        codex: { adapter: codex.adapter },
+      },
+    })
+    // Two background runs at once, like two /agent commands.
+    const first = shared.session.agent('claude_code')?.start({ task: 'edit a' })
+    const second = shared.session.agent('codex')?.start({ task: 'edit b' })
+    await new Promise((resolve) => setTimeout(resolve, 30))
+    // Codex waits for the lock while Claude Code holds the shared workspace.
+    expect(claude.calls).toHaveLength(1)
+    expect(codex.calls).toHaveLength(0)
+    release()
+    await first
+    await second
+    expect(codex.calls).toHaveLength(1)
+    expect(codex.calls[0].threadId).toBe('t')
+    expect(shared.provider.calls.create).toBe(1)
+    await shared.host.close()
+
+    let releaseSlow = () => {}
+    const slowGate = new Promise<void>((resolve) => (releaseSlow = resolve))
+    const slow = codingAgent('claude-code', { wait: slowGate })
+    const fast = codingAgent('codex')
+    const apart = await open({
+      leadSteps: [],
+      agents: {
+        claude_code: { adapter: slow.adapter },
+        codex: { adapter: fast.adapter },
+      },
+      workspace: 'per-agent',
+    })
+    const slowRun = apart.session
+      .agent('claude_code')
+      ?.start({ task: 'edit a' })
+    const fastRun = apart.session.agent('codex')?.start({ task: 'edit b' })
+    await fastRun
+    // Codex finished while Claude Code still works in its own sandbox.
+    expect(fast.calls[0].threadId).toBe('t:codex')
+    expect(slow.log).toEqual(['claude-code start 1'])
+    releaseSlow()
+    await slowRun
+    expect(slow.calls[0].threadId).toBe('t:claude_code')
+    expect(apart.provider.calls.create).toBe(2)
+    await apart.host.close()
+  })
+
+  it('starts delegates read-only in plan mode', async () => {
+    const claude = codingAgent('claude-code')
+    const codex = codingAgent('codex')
+    const other = codingAgent('grok-build')
+    const custom = codingAgent('acp')
+    const { host, session } = await open({
+      leadSteps: [
+        [
+          ['claude_code', 'look'],
+          ['codex', 'look'],
+          ['grok', 'look'],
+          ['custom', 'look'],
+        ],
+      ],
+      agents: {
+        claude_code: { adapter: claude.adapter },
+        codex: { adapter: codex.adapter },
+        grok: { adapter: other.adapter },
+        custom: {
+          adapter: custom.adapter,
+          planModelOptions: { readOnly: true },
+        },
+      },
+    })
+    await session.setConfig('mode', 'plan')
+    await session.prompt('plan it')
+    expect(claude.calls[0].modelOptions).toMatchObject({
+      permissionMode: 'plan',
+    })
+    expect(codex.calls[0].modelOptions).toMatchObject({
+      sandboxMode: 'read-only',
+    })
+    expect(other.calls[0].modelOptions).toBeUndefined()
+    expect(custom.calls[0].modelOptions).toMatchObject({ readOnly: true })
+    await host.close()
+  })
+})
diff --git a/packages/ai-sandbox/vite.config.ts b/packages/ai-sandbox/vite.config.ts
index 5eaa0e507a..e7d52c2e2a 100644
--- a/packages/ai-sandbox/vite.config.ts
+++ b/packages/ai-sandbox/vite.config.ts
@@ -34,7 +34,12 @@ export default mergeConfig(
     // (`@tanstack/ai-sandbox/ngrok`), which lazy-loads the optional `@ngrok/ngrok`
     // peer dep so the core never pulls in its native binary + the SandboxInstanceStore
     // conformance testkit (`@tanstack/ai-sandbox/testkit`).
-    entry: ['./src/index.ts', './src/ngrok.ts', './src/testkit/conformance.ts'],
+    entry: [
+      './src/index.ts',
+      './src/harness.ts',
+      './src/ngrok.ts',
+      './src/testkit/conformance.ts',
+    ],
     srcDir: './src',
     // The conformance testkit imports Vitest; keep it external so the built
     // artifact references the consumer's Vitest at test time.
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 42c97fce1d..4b907ac390 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -185,9 +185,15 @@ importers:
       '@tanstack/ai-anthropic':
         specifier: workspace:*
         version: link:../../packages/ai-anthropic
+      '@tanstack/ai-claude-code':
+        specifier: workspace:*
+        version: link:../../packages/ai-claude-code
       '@tanstack/ai-code-mode':
         specifier: workspace:*
         version: link:../../packages/ai-code-mode
+      '@tanstack/ai-codex':
+        specifier: workspace:*
+        version: link:../../packages/ai-codex
       '@tanstack/ai-dashboard':
         specifier: workspace:*
         version: link:../../packages/ai-dashboard
@@ -212,6 +218,12 @@ importers:
       '@tanstack/ai-persistence':
         specifier: workspace:*
         version: link:../../packages/ai-persistence
+      '@tanstack/ai-sandbox':
+        specifier: workspace:*
+        version: link:../../packages/ai-sandbox
+      '@tanstack/ai-sandbox-local-process':
+        specifier: workspace:*
+        version: link:../../packages/ai-sandbox-local-process
       zod:
         specifier: ^4.2.0
         version: 4.3.6
@@ -3142,6 +3154,9 @@ importers:
       '@tanstack/ai':
         specifier: workspace:*
         version: link:../ai
+      '@tanstack/ai-harness':
+        specifier: workspace:*
+        version: link:../ai-harness
       '@tanstack/ai-persistence':
         specifier: workspace:*
         version: link:../ai-persistence

From d62a6cdac11c74e326f11662b38af84fd4487129 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 11:51:58 +0200
Subject: [PATCH 031/286] test(ai-opencode, ai-harness-cli): cover the failed
 session start every run; use an if-chain for child events

The opencode durability tests reach the failed-start path only sometimes, so the
coverage number moved between runs. A new test starts a session against a closed
port, with and without a session to resume.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-harness-cli/src/session-view.ts   | 87 +++++++++----------
 .../ai-opencode/tests/session-start.test.ts   | 37 ++++++++
 2 files changed, 80 insertions(+), 44 deletions(-)
 create mode 100644 packages/ai-opencode/tests/session-start.test.ts

diff --git a/packages/ai-harness-cli/src/session-view.ts b/packages/ai-harness-cli/src/session-view.ts
index 1e409dd0d6..d1f904a310 100644
--- a/packages/ai-harness-cli/src/session-view.ts
+++ b/packages/ai-harness-cli/src/session-view.ts
@@ -177,49 +177,48 @@ function applyChildEvent(
   const agent = entries[index]
   const found = agent?.kind === 'agent' ? agent : undefined
   const name = found?.name ?? 'agent'
-  switch (event.type) {
-    case EventType.SUBAGENT_STARTED: {
-      const started = event.name ?? 'agent'
-      return [
-        ...entries,
-        {
-          kind: 'agent',
-          subagentRunId,
-          name: started,
-          text: `agent ${started} started`,
-          answer: '',
-        },
-      ]
-    }
-    case EventType.TEXT_MESSAGE_CONTENT: {
-      if (!found) return entries
-      const next = [...entries]
-      next[index] = { ...found, answer: found.answer + event.delta }
-      return next
-    }
-    case EventType.TOOL_CALL_START:
-      return [
-        ...entries,
-        { kind: 'tool', text: `${name}: tool ${event.toolCallName}` },
-      ]
-    case EventType.SUBAGENT_FINISHED: {
-      const answer = shortAnswer(found?.answer ?? '')
-      return [
-        ...entries,
-        {
-          kind: 'tool',
-          text: answer
-            ? `agent ${name} finished: ${answer}`
-            : `agent ${name} finished`,
-        },
-      ]
-    }
-    case EventType.SUBAGENT_ERROR:
-      return [
-        ...entries,
-        { kind: 'notice', text: `agent ${name} failed: ${event.message}` },
-      ]
-    default:
-      return entries
+  if (event.type === EventType.SUBAGENT_STARTED) {
+    const started = event.name ?? 'agent'
+    return [
+      ...entries,
+      {
+        kind: 'agent',
+        subagentRunId,
+        name: started,
+        text: `agent ${started} started`,
+        answer: '',
+      },
+    ]
+  }
+  if (event.type === EventType.TEXT_MESSAGE_CONTENT) {
+    if (!found) return entries
+    const next = [...entries]
+    next[index] = { ...found, answer: found.answer + event.delta }
+    return next
   }
+  if (event.type === EventType.TOOL_CALL_START) {
+    return [
+      ...entries,
+      { kind: 'tool', text: `${name}: tool ${event.toolCallName}` },
+    ]
+  }
+  if (event.type === EventType.SUBAGENT_FINISHED) {
+    const answer = shortAnswer(found?.answer ?? '')
+    return [
+      ...entries,
+      {
+        kind: 'tool',
+        text: answer
+          ? `agent ${name} finished: ${answer}`
+          : `agent ${name} finished`,
+      },
+    ]
+  }
+  if (event.type === EventType.SUBAGENT_ERROR) {
+    return [
+      ...entries,
+      { kind: 'notice', text: `agent ${name} failed: ${event.message}` },
+    ]
+  }
+  return entries
 }
diff --git a/packages/ai-opencode/tests/session-start.test.ts b/packages/ai-opencode/tests/session-start.test.ts
new file mode 100644
index 0000000000..3e3ea51757
--- /dev/null
+++ b/packages/ai-opencode/tests/session-start.test.ts
@@ -0,0 +1,37 @@
+import { createServer } from 'node:net'
+import { describe, expect, it } from 'vitest'
+import { startOpencodeSession } from '../src/process/server'
+
+/** A local port with nothing listening on it, so a connection fails at once. */
+async function closedPort(): Promise<number> {
+  const server = createServer()
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+  const address = server.address()
+  const port = typeof address === 'object' && address ? address.port : 0
+  await new Promise<void>((resolve) => server.close(() => resolve()))
+  return port
+}
+
+const options = (baseUrl: string) => ({
+  baseUrl,
+  providerID: 'anthropic',
+  modelID: 'claude-sonnet-4-5',
+  headers: { 'x-preview-token': 't' },
+  directory: '/workspace',
+  onEvent: () => {},
+  onPermissionRequest: () => 'reject' as const,
+})
+
+describe('startOpencodeSession when the server cannot be reached', () => {
+  it('rejects when a new session cannot be created', async () => {
+    const baseUrl = `http://127.0.0.1:${await closedPort()}`
+    await expect(startOpencodeSession(options(baseUrl))).rejects.toBeDefined()
+  })
+
+  it('rejects when a session to resume cannot be read', async () => {
+    const baseUrl = `http://127.0.0.1:${await closedPort()}`
+    await expect(
+      startOpencodeSession({ ...options(baseUrl), resumeSessionId: 'ses_1' }),
+    ).rejects.toBeDefined()
+  })
+})

From 06595208a24f4eb56c591751cf7ac8b455654e1f Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 11:54:46 +0200
Subject: [PATCH 032/286] feat(ai-harness): goal plugin that keeps working
 until the goal is met

---
 .changeset/harness-p10-goal.md                |   5 +
 docs/config.json                              |   5 +
 docs/harness/coding-agent.md                  |   1 +
 docs/harness/dashboard.md                     |   2 +-
 docs/harness/deploy.md                        |   2 +-
 docs/harness/goal.md                          | 100 ++++++
 docs/harness/subagents.md                     |   2 +-
 examples/harness-cli/README.md                |   1 +
 examples/harness-cli/src/harness.ts           |   3 +
 packages/ai-harness/src/first-party/goal.ts   | 287 +++++++++++++++
 packages/ai-harness/src/first-party/index.ts  |   2 +
 .../src/first-party/session-tools.ts          |  15 +-
 packages/ai-harness/tests/goal.test.ts        | 332 ++++++++++++++++++
 13 files changed, 749 insertions(+), 8 deletions(-)
 create mode 100644 .changeset/harness-p10-goal.md
 create mode 100644 docs/harness/goal.md
 create mode 100644 packages/ai-harness/src/first-party/goal.ts
 create mode 100644 packages/ai-harness/tests/goal.test.ts

diff --git a/.changeset/harness-p10-goal.md b/.changeset/harness-p10-goal.md
new file mode 100644
index 0000000000..10e3a32402
--- /dev/null
+++ b/.changeset/harness-p10-goal.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-harness': minor
+---
+
+Add the `goal({ judge })` plugin to `@tanstack/ai-harness/plugins`. `/goal <text>` sets a goal and starts a turn. After each turn, the `judge` model reads the goal and the end of the transcript and decides if the goal is met. If it is not met, the plugin starts the next turn, up to `maxRounds` turns (20 by default). The loop also stops when a turn waits for approval or fails, and when the user sends a message. `/goal` shows the status, `/goal stop` ends the goal, and `/goal resume` continues it. The goal is plugin state, so it survives a restart. The `GoalMet` event tells other plugins and clients that the goal is met.
diff --git a/docs/config.json b/docs/config.json
index db8c43e1bc..23fa369fbf 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -856,6 +856,11 @@
           "to": "harness/coding-agents",
           "addedAt": "2026-09-28"
         },
+        {
+          "label": "Work until a goal is met",
+          "to": "harness/goal",
+          "addedAt": "2026-09-28"
+        },
         {
           "label": "Run agents from a harness",
           "to": "harness/subagents",
diff --git a/docs/harness/coding-agent.md b/docs/harness/coding-agent.md
index 3e1c2663ec..f2a657a6a2 100644
--- a/docs/harness/coding-agent.md
+++ b/docs/harness/coding-agent.md
@@ -69,6 +69,7 @@ Run the file with `npx tsx coder.ts`. Ask for a change. The agent reads files fr
 | `fileCommands({ dir })` | Each `.md` file becomes a slash command. `$ARGUMENTS` is replaced by what you type after it. |
 | `compact({ adapter })` | `/compact` replaces a long conversation with a summary. |
 | `usage()` | `/usage` shows the tokens of the session. |
+| `goal({ judge })` | `/goal <text>` keeps the agent working until a judge model says that the goal is met. See [Work until a goal is met](./goal). |
 
 ## Add your own rules
 
diff --git a/docs/harness/dashboard.md b/docs/harness/dashboard.md
index 7ed93a5de4..a93340c52a 100644
--- a/docs/harness/dashboard.md
+++ b/docs/harness/dashboard.md
@@ -1,7 +1,7 @@
 ---
 title: Self-host the dashboard
 id: harness-dashboard
-order: 13
+order: 14
 description: "Watch and steer your harness sessions from a browser or a phone. Agents dial out to your dashboard server, so they need no open port."
 keywords:
   - tanstack ai
diff --git a/docs/harness/deploy.md b/docs/harness/deploy.md
index 04f94332f8..da8968388b 100644
--- a/docs/harness/deploy.md
+++ b/docs/harness/deploy.md
@@ -1,7 +1,7 @@
 ---
 title: Deploy a harness
 id: harness-deploy
-order: 12
+order: 13
 description: "Run a harness in your server, as a worker process, on another machine, or as a single executable."
 keywords:
   - tanstack ai
diff --git a/docs/harness/goal.md b/docs/harness/goal.md
new file mode 100644
index 0000000000..94601f9442
--- /dev/null
+++ b/docs/harness/goal.md
@@ -0,0 +1,100 @@
+---
+title: Work until a goal is met
+id: harness-goal
+order: 11
+description: "Give the harness a goal, for example all tests pass. After each turn, a judge model checks the goal, and the harness keeps working until the goal is met."
+keywords:
+  - tanstack ai
+  - harness
+  - goal
+  - judge
+  - agent loop
+---
+
+You ask your agent to make all tests pass. It fixes one test, then it stops and waits for you. You type "keep going" again and again.
+
+The `goal()` plugin keeps the harness working. You give the goal one time. After each turn, a judge model reads the goal and the end of the conversation. If the goal is not met, the plugin starts the next turn.
+
+## 1. Add the plugin
+
+```ts group=harness-goal
+import { defineHarness } from '@tanstack/ai-harness'
+import { goal, permissions, workspaceTools } from '@tanstack/ai-harness/plugins'
+import { openaiText } from '@tanstack/ai-openai'
+
+const root = process.cwd()
+
+export const coder = defineHarness({
+  name: 'acme/coder',
+  adapter: openaiText('gpt-5.6'),
+  plugins: () => [
+    permissions(),
+    workspaceTools({ root }),
+    goal({ judge: openaiText('gpt-5.6-luna') }),
+  ],
+})
+```
+
+`judge` is the model that decides if the goal is met. It can be a smaller model than the main model, or the same model.
+
+## 2. Give it a goal
+
+1. Start the harness, for example with the [CLI](./cli).
+2. Type `/goal all tests pass`. The first turn starts.
+3. Watch the turns. Each new turn tells the model the reason of the last check:
+
+```text
+Keep working on the goal: all tests pass. Last check: The date parser test still fails.
+```
+
+4. Type `/goal` to see the result:
+
+```text
+Goal: all tests pass
+Status: met, round 3 of 20.
+Last check: All 12 tests pass.
+```
+
+## How it stops
+
+The plugin starts no new turn in these cases:
+
+- The judge says that the goal is met. The status is `met`.
+- The plugin started `maxRounds` turns (20 by default). The status is `stopped`, and the last reason stays.
+- A turn waits for an approval, or a turn fails. The status is `paused`.
+- You send your own message. The status is `paused`, and your message runs as a normal turn.
+
+To change the limit, set `maxRounds`, for example `goal({ judge, maxRounds: 50 })`.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `/goal <text>` | Sets the goal and starts the first turn. |
+| `/goal` | Shows the goal, the status, the round, and the last reason. |
+| `/goal stop` | Ends the goal. The running turn finishes, and no new turn starts. |
+| `/goal resume` | Continues a paused or stopped goal with a new round count. The goal is plugin state, so this also works after a restart. |
+
+## Do something when the goal is met
+
+The plugin sends the `GoalMet` event with the goal and the last reason. Listen for it in your own plugin:
+
+```ts group=harness-goal
+import { definePlugin } from '@tanstack/ai-harness'
+import { GoalMet } from '@tanstack/ai-harness/plugins'
+
+export const notify = definePlugin({
+  name: 'acme/notify',
+  setup: (ctx) => {
+    ctx.on(GoalMet, (met) => console.log(`Done: ${met.goal}. ${met.reason}`))
+  },
+})
+```
+
+Clients get the same event as a `harness.plugin.event` with the name `tanstack/goal:met`.
+
+## What you have now
+
+- A harness that keeps working until the judge says that the goal is met.
+- A round limit, so the loop cannot run without end.
+- `/goal`, `/goal stop`, and `/goal resume` to see and control the goal.
diff --git a/docs/harness/subagents.md b/docs/harness/subagents.md
index 9e17ba8306..24fc535b0a 100644
--- a/docs/harness/subagents.md
+++ b/docs/harness/subagents.md
@@ -1,7 +1,7 @@
 ---
 title: Run agents from a harness
 id: harness-subagents
-order: 11
+order: 12
 description: "Start typed agents from commands and plugins, run them in groups, call a whole harness as a child, and keep the tree within limits."
 keywords:
   - tanstack ai
diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index 65345557bb..8f0f7a684b 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -17,6 +17,7 @@ Try these:
 - `/mode plan`, then ask for another file: the write is refused.
 - `/todos`, `/usage`, `/model fast`, `/agents`
 - `/agent haiku {"topic":"rain"}`: runs a typed agent in the background.
+- `/goal create a file hello.txt that says hi`: the agent keeps working until the model says the goal is met. `/goal` shows the status.
 - Press Esc to stop a long answer. Type while it works to steer it.
 
 ## Use Notion, Linear, images, and video
diff --git a/examples/harness-cli/src/harness.ts b/examples/harness-cli/src/harness.ts
index ce06031439..6cb9e04f2a 100644
--- a/examples/harness-cli/src/harness.ts
+++ b/examples/harness-cli/src/harness.ts
@@ -3,6 +3,7 @@ import { EventType, defineAgent } from '@tanstack/ai'
 import { defineHarness } from '@tanstack/ai-harness'
 import {
   compact,
+  goal,
   modelPicker,
   permissions,
   projectInstructions,
@@ -223,6 +224,8 @@ export const assistant = defineHarness({
     projectInstructions({ root }),
     compact({ adapter: main }),
     usage(),
+    // /goal keeps the agent working until the main model says the goal is met.
+    goal({ judge: main }),
     // Read-only tools (file reads, read-only Notion and Linear tools) move
     // behind execute_typescript, so the model can call several in one program.
     // The program runs in a QuickJS isolate. Any @tanstack/ai-isolate-* driver
diff --git a/packages/ai-harness/src/first-party/goal.ts b/packages/ai-harness/src/first-party/goal.ts
new file mode 100644
index 0000000000..f501b306cb
--- /dev/null
+++ b/packages/ai-harness/src/first-party/goal.ts
@@ -0,0 +1,287 @@
+import { EventType, chat } from '@tanstack/ai'
+import { defineCommand } from '../commands'
+import { createPluginEvent } from '../extensions'
+import { definePlugin } from '../plugins'
+import { textOf, transcriptText } from './session-tools'
+import type { AnyTextAdapter } from '@tanstack/ai'
+
+/** The goal of a session. It is plugin state, so it survives restarts. */
+export interface Goal {
+  text: string
+  status: 'active' | 'paused' | 'met' | 'stopped'
+  /** The turns the plugin started for this goal. */
+  round: number
+  /** The reason of the last check. */
+  reason: string
+  /** Why the goal paused or stopped. Empty while it is active or met. */
+  note: string
+  /** The message of the turn that the plugin queued, until that turn starts. */
+  queued: string
+}
+
+/** Sent when the judge says that the goal is met. */
+export const GoalMet = createPluginEvent<{ goal: string; reason: string }>(
+  'tanstack/goal:met',
+)
+
+const JUDGE_PROMPT =
+  'You check the work of an agent. Read the goal and the last part of the conversation. Set met to true only when the conversation shows that the goal is done. Give a short reason.'
+const USER_MESSAGE =
+  'You sent a message, so the goal paused. Run /goal resume to continue.'
+const TURN_FAILED = 'The last turn failed. Run /goal resume to try again.'
+const WAITS_FOR_APPROVAL =
+  'The last turn waits for approval. Answer it, then run /goal resume.'
+
+function isVerdict(value: unknown): value is { met: boolean; reason: string } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'met' in value &&
+    typeof value.met === 'boolean' &&
+    'reason' in value &&
+    typeof value.reason === 'string'
+  )
+}
+
+function keepWorking(text: string, reason: string) {
+  return `Keep working on the goal: ${text}. Last check: ${reason}`
+}
+
+function describe(saved: Goal | null, maxRounds: number) {
+  if (!saved) return 'No goal. Start one with /goal <what done looks like>.'
+  return [
+    `Goal: ${saved.text}`,
+    `Status: ${saved.status}, round ${saved.round} of ${maxRounds}.`,
+    saved.note,
+    saved.reason === '' ? '' : `Last check: ${saved.reason}`,
+  ]
+    .filter((line) => line !== '')
+    .join('\n')
+}
+
+/**
+ * Keep the harness working until a goal is met. `/goal <text>` starts the
+ * goal. After each turn, `judge` reads the goal and the end of the transcript
+ * and decides if the goal is met. If it is not, the plugin starts the next
+ * turn, up to `maxRounds` turns (default 20).
+ *
+ * The loop stops when the goal is met, at the round limit, when a turn waits
+ * for approval or fails, and when the user sends a message. `/goal` shows the
+ * goal, `/goal stop` ends it, and `/goal resume` continues it.
+ *
+ * @example
+ * ```ts
+ * plugins: () => [goal({ judge: openaiText('gpt-5.6-luna') })]
+ * ```
+ */
+export function goal(options: { judge: AnyTextAdapter; maxRounds?: number }) {
+  const maxRounds = options.maxRounds ?? 20
+  return definePlugin({
+    name: 'tanstack/goal',
+    setup: async (ctx) => {
+      const state = ctx.state<Goal | null>(null)
+      // The prompt runs for each turn, so keep a copy of the goal at hand.
+      let current = await state.get()
+      // The run id of the plugin's own turn while it runs.
+      let ownRun: string | undefined
+
+      /** Change the goal, but only while `text` is still the active goal. */
+      const change = async (text: string, next: Partial<Goal>) => {
+        let applied = false
+        current = await state.update((saved) => {
+          const isActive =
+            saved !== null && saved.status === 'active' && saved.text === text
+          applied = isActive
+          return isActive ? { ...saved, ...next } : saved
+        })
+        return applied
+      }
+
+      /** Make `text` the active goal with a new round count, and start a turn. */
+      const begin = async (text: string, reason: string) => {
+        const message =
+          reason === ''
+            ? `Work toward this goal: ${text}`
+            : keepWorking(text, reason)
+        // A turn that is still running belongs to the old goal.
+        ownRun = undefined
+        current = await state.update(() => ({
+          text,
+          status: 'active',
+          round: 0,
+          reason,
+          note: '',
+          queued: message,
+        }))
+        ctx.session.prompt(message)
+      }
+
+      /** Pause the goal when the plugin's own turn ends early. */
+      const pauseOwnTurn = async (runId: string, note: string) => {
+        if (runId !== ownRun || !current) return
+        ownRun = undefined
+        await change(current.text, { status: 'paused', note })
+      }
+
+      const judge = async (text: string) => {
+        // ponytail: the last 10 messages, clipped. Summarize first if a judge needs more.
+        const transcript = transcriptText(
+          (await ctx.session.transcript()).slice(-10),
+        ).slice(-8000)
+        const verdict = await chat({
+          adapter: options.judge,
+          messages: [
+            {
+              role: 'user',
+              content: `${JUDGE_PROMPT}\n\nGoal: ${text}\n\nThe last part of the conversation:\n${transcript}`,
+            },
+          ],
+          outputSchema: {
+            type: 'object',
+            properties: {
+              met: { type: 'boolean' },
+              reason: { type: 'string' },
+            },
+            required: ['met', 'reason'],
+          },
+        })
+        if (!isVerdict(verdict))
+          throw new Error('The judge did not answer with met and reason.')
+        return verdict
+      }
+
+      return {
+        prompts: [
+          {
+            id: 'tanstack/goal:active',
+            text: () =>
+              current?.status === 'active'
+                ? `You work toward this goal: ${current.text}. Keep going until it is done.`
+                : '',
+          },
+        ],
+        commands: {
+          goal: defineCommand({
+            description:
+              'Work until a goal is met: /goal <goal>. Also /goal, /goal stop, /goal resume',
+            run: async (input: unknown) => {
+              const arg = typeof input === 'string' ? input.trim() : ''
+              switch (arg) {
+                case '':
+                  return describe(current, maxRounds)
+                case 'stop': {
+                  const isRunning =
+                    current?.status === 'active' || current?.status === 'paused'
+                  if (!isRunning) return 'No goal is running.'
+                  current = await state.update(
+                    (saved) =>
+                      saved && {
+                        ...saved,
+                        status: 'stopped',
+                        note: 'You stopped the goal.',
+                      },
+                  )
+                  return describe(current, maxRounds)
+                }
+                case 'resume': {
+                  const canResume =
+                    current?.status === 'paused' ||
+                    current?.status === 'stopped'
+                  if (!current || !canResume)
+                    return describe(current, maxRounds)
+                  await begin(current.text, current.reason)
+                  return describe(current, maxRounds)
+                }
+                default:
+                  await begin(arg, '')
+                  return describe(current, maxRounds)
+              }
+            },
+          }),
+        },
+        middleware: [
+          {
+            name: 'tanstack/goal',
+            onConfig: async (run, config) => {
+              const saved = current
+              const last = config.messages.at(-1)
+              // A turn with a new user message. A resume has none.
+              const isNewMessage =
+                run.phase === 'init' &&
+                last !== undefined &&
+                last.role === 'user'
+              if (!isNewMessage || saved?.status !== 'active') return
+              if (textOf(last) !== saved.queued) {
+                await change(saved.text, {
+                  status: 'paused',
+                  note: USER_MESSAGE,
+                })
+                return
+              }
+              ownRun = run.runId
+              await change(saved.text, { round: saved.round + 1, queued: '' })
+            },
+            onChunk: async (run, chunk) => {
+              const isApproval =
+                chunk.type === EventType.RUN_FINISHED &&
+                chunk.outcome?.type === 'interrupt'
+              if (isApproval) await pauseOwnTurn(run.runId, WAITS_FOR_APPROVAL)
+              if (chunk.type === EventType.RUN_ERROR)
+                await pauseOwnTurn(run.runId, TURN_FAILED)
+            },
+            onError: (run) => pauseOwnTurn(run.runId, TURN_FAILED),
+            onAbort: (run) =>
+              pauseOwnTurn(
+                run.runId,
+                'The last turn was cancelled. Run /goal resume to continue.',
+              ),
+            // chat() waits for onFinish, so the turn is still running here and
+            // the next turn can only queue. It starts after this turn ends.
+            onFinish: async (run) => {
+              const saved = current
+              if (run.runId !== ownRun || saved?.status !== 'active') return
+              ownRun = undefined
+              const { text, round } = saved
+              const verdict = await judge(text).catch((error: unknown) =>
+                error instanceof Error ? error.message : String(error),
+              )
+              if (typeof verdict === 'string') {
+                await change(text, {
+                  status: 'paused',
+                  note: `The judge failed: ${verdict}`,
+                })
+                return
+              }
+              const { reason } = verdict
+              if (verdict.met) {
+                const met = await change(text, { status: 'met', reason })
+                if (met) ctx.emit(GoalMet, { goal: text, reason })
+                return
+              }
+              if (round >= maxRounds) {
+                await change(text, {
+                  status: 'stopped',
+                  reason,
+                  note: `The round limit (${maxRounds}) is reached. Run /goal resume for more rounds.`,
+                })
+                return
+              }
+              // The user queued a message while this turn ran.
+              if (ctx.session.snapshot().queuedTurns > 0) {
+                await change(text, {
+                  status: 'paused',
+                  reason,
+                  note: USER_MESSAGE,
+                })
+                return
+              }
+              const message = keepWorking(text, reason)
+              if (await change(text, { reason, queued: message }))
+                ctx.session.prompt(message)
+            },
+          },
+        ],
+      }
+    },
+  })
+}
diff --git a/packages/ai-harness/src/first-party/index.ts b/packages/ai-harness/src/first-party/index.ts
index 0d49df50cc..36f00240d2 100644
--- a/packages/ai-harness/src/first-party/index.ts
+++ b/packages/ai-harness/src/first-party/index.ts
@@ -17,3 +17,5 @@ export { formatTodos, todos } from './todos'
 export type { Todo } from './todos'
 export { fileCommands, projectInstructions } from './files'
 export { compact, usage } from './session-tools'
+export { GoalMet, goal } from './goal'
+export type { Goal } from './goal'
diff --git a/packages/ai-harness/src/first-party/session-tools.ts b/packages/ai-harness/src/first-party/session-tools.ts
index 219bfe5180..47417a4795 100644
--- a/packages/ai-harness/src/first-party/session-tools.ts
+++ b/packages/ai-harness/src/first-party/session-tools.ts
@@ -6,7 +6,7 @@ import type { AnyTextAdapter, ModelMessage } from '@tanstack/ai'
 const SUMMARY_PROMPT =
   'Summarize the conversation so far for yourself. Keep decisions, open tasks, file names, and facts you still need. Leave out small talk.'
 
-function textOf(message: ModelMessage): string {
+export function textOf(message: ModelMessage) {
   if (typeof message.content === 'string') return message.content
   if (Array.isArray(message.content)) {
     return message.content
@@ -16,6 +16,14 @@ function textOf(message: ModelMessage): string {
   return ''
 }
 
+/** One `role: text` line per message. Messages with no text are left out. */
+export function transcriptText(messages: ReadonlyArray<ModelMessage>) {
+  return messages
+    .map((message) => `${message.role}: ${textOf(message)}`)
+    .filter((line) => !line.endsWith(': '))
+    .join('\n')
+}
+
 /**
  * `/compact`: replace a long transcript with a summary, so later turns send
  * fewer tokens. The summary is written by `adapter`.
@@ -36,10 +44,7 @@ export function compact(options: {
             if (messages.length <= keep + 2)
               return 'The conversation is already short.'
             const older = messages.slice(0, messages.length - keep)
-            const transcript = older
-              .map((message) => `${message.role}: ${textOf(message)}`)
-              .filter((line) => !line.endsWith(': '))
-              .join('\n')
+            const transcript = transcriptText(older)
             const summary = await chat({
               adapter: options.adapter,
               messages: [
diff --git a/packages/ai-harness/tests/goal.test.ts b/packages/ai-harness/tests/goal.test.ts
new file mode 100644
index 0000000000..2c4ab9e01a
--- /dev/null
+++ b/packages/ai-harness/tests/goal.test.ts
@@ -0,0 +1,332 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness, definePlugin } from '../src'
+import { GoalMet, goal } from '../src/first-party'
+import {
+  after,
+  gate,
+  messageTexts,
+  mockAdapter,
+  text,
+  toolCall,
+  untilAborted,
+} from './helpers'
+import type { AnyTextAdapter, AnyTool } from '@tanstack/ai'
+import type { HarnessSession } from '../src'
+import type { Goal } from '../src/first-party'
+
+interface Verdict {
+  met: boolean
+  reason: string
+}
+
+/** A judge that answers with `verdicts` in order. Keeps what it read. */
+function scriptedJudge(verdicts: Array<Verdict>) {
+  const { adapter } = mockAdapter([])
+  const read: Array<string> = []
+  const judge: AnyTextAdapter = {
+    ...adapter,
+    structuredOutput: async (options) => {
+      read.push(JSON.stringify(options.chatOptions.messages))
+      const data = verdicts[read.length - 1] ?? {
+        met: false,
+        reason: 'No verdict left.',
+      }
+      return { data, rawText: JSON.stringify(data) }
+    },
+  }
+  return { judge, read }
+}
+
+async function start(options: {
+  replies: Parameters<typeof mockAdapter>[0]
+  verdicts?: Array<Verdict>
+  judge?: AnyTextAdapter
+  maxRounds?: number
+  tools?: Array<AnyTool>
+  persistence?: ReturnType<typeof memoryPersistence>
+}) {
+  const main = mockAdapter(options.replies)
+  const scripted = scriptedJudge(options.verdicts ?? [])
+  const met: Array<{ goal: string; reason: string }> = []
+  const listener = definePlugin({
+    name: 'test/goal-listener',
+    setup: (ctx) => {
+      ctx.on(GoalMet, (value) => met.push(value))
+    },
+  })
+  const persistence = options.persistence ?? memoryPersistence()
+  const host = createHarnessHost({ persistence })
+  const session = await host.open(
+    defineHarness({
+      name: 'test/goal',
+      adapter: main.adapter,
+      tools: options.tools ?? [],
+      plugins: () => [
+        goal({
+          judge: options.judge ?? scripted.judge,
+          maxRounds: options.maxRounds,
+        }),
+        listener,
+      ],
+    }),
+    { threadId: 't' },
+  )
+  return {
+    host,
+    session,
+    persistence,
+    calls: main.calls,
+    read: scripted.read,
+    met,
+  }
+}
+
+/** What `/goal` shows. */
+async function status(session: HarnessSession) {
+  return session.command('goal')
+}
+
+/** Wait until `/goal` shows `expected`. */
+async function waitForStatus(session: HarnessSession, expected: string) {
+  await vi.waitFor(async () => expect(await status(session)).toBe(expected))
+}
+
+/** The last message the main model got on `call`. */
+function lastMessage(call: unknown) {
+  return messageTexts(call).at(-1)
+}
+
+describe('goal', () => {
+  it('runs turns until the judge says the goal is met', async () => {
+    const { host, session, calls, read, met } = await start({
+      replies: [
+        () => text('wrote the test'),
+        () => text('fixed the bug'),
+        () => text('all green'),
+      ],
+      verdicts: [
+        { met: false, reason: 'The test fails.' },
+        { met: false, reason: 'One test still fails.' },
+        { met: true, reason: 'All tests pass.' },
+      ],
+    })
+
+    expect(await session.command('goal', 'all tests pass')).toBe(
+      'Goal: all tests pass\nStatus: active, round 0 of 20.',
+    )
+    await waitForStatus(
+      session,
+      'Goal: all tests pass\nStatus: met, round 3 of 20.\nLast check: All tests pass.',
+    )
+
+    expect(calls).toHaveLength(3)
+    expect(lastMessage(calls[0])).toBe('Work toward this goal: all tests pass')
+    expect(lastMessage(calls[2])).toBe(
+      'Keep working on the goal: all tests pass. Last check: One test still fails.',
+    )
+    expect(JSON.stringify(calls[0].systemPrompts)).toContain(
+      'You work toward this goal: all tests pass.',
+    )
+    expect(read).toHaveLength(3)
+    expect(read[0]).toContain('Goal: all tests pass')
+    expect(read[0]).toContain('assistant: wrote the test')
+    expect(met).toEqual([{ goal: 'all tests pass', reason: 'All tests pass.' }])
+    await vi.waitFor(() => expect(session.snapshot().status).toBe('idle'))
+    expect(session.snapshot().queuedTurns).toBe(0)
+    await host.close()
+  })
+
+  it('stops at the round limit and keeps the last reason', async () => {
+    const { host, session, calls } = await start({
+      replies: [() => text('try one'), () => text('try two')],
+      verdicts: [
+        { met: false, reason: 'Two tests fail.' },
+        { met: false, reason: 'One test fails.' },
+      ],
+      maxRounds: 2,
+    })
+
+    await session.command('goal', 'all tests pass')
+    await waitForStatus(
+      session,
+      'Goal: all tests pass\nStatus: stopped, round 2 of 2.\nThe round limit (2) is reached. Run /goal resume for more rounds.\nLast check: One test fails.',
+    )
+    await vi.waitFor(() => expect(session.snapshot().status).toBe('idle'))
+    expect(calls).toHaveLength(2)
+    await host.close()
+  })
+
+  it('shows the goal, stops it, and resumes it', async () => {
+    const hold = gate()
+    const { host, session, calls, read } = await start({
+      replies: [after(hold.opened, 'half done'), () => text('done')],
+      verdicts: [{ met: true, reason: 'The file exists.' }],
+    })
+
+    expect(await status(session)).toBe(
+      'No goal. Start one with /goal <what done looks like>.',
+    )
+    expect(await session.command('goal', 'stop')).toBe('No goal is running.')
+
+    await session.command('goal', 'create hello.txt')
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    expect(await session.command('goal', 'stop')).toBe(
+      'Goal: create hello.txt\nStatus: stopped, round 1 of 20.\nYou stopped the goal.',
+    )
+    hold.open()
+    await vi.waitFor(() => expect(session.snapshot().status).toBe('idle'))
+    expect(read).toHaveLength(0)
+
+    expect(await session.command('goal', 'resume')).toBe(
+      'Goal: create hello.txt\nStatus: active, round 0 of 20.',
+    )
+    await waitForStatus(
+      session,
+      'Goal: create hello.txt\nStatus: met, round 1 of 20.\nLast check: The file exists.',
+    )
+    expect(calls).toHaveLength(2)
+    expect(lastMessage(calls[1])).toBe(
+      'Work toward this goal: create hello.txt',
+    )
+    await host.close()
+  })
+
+  it('pauses when the user sends a message while a goal turn runs', async () => {
+    const hold = gate()
+    const { host, session, calls } = await start({
+      replies: [
+        after(hold.opened, 'step one'),
+        () => text('It is noon.'),
+        () => text('step two'),
+      ],
+      verdicts: [
+        { met: false, reason: 'Not yet.' },
+        { met: true, reason: 'Done.' },
+      ],
+    })
+
+    await session.command('goal', 'all tests pass')
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    const question = session.prompt('what time is it?')
+    hold.open()
+    await question
+
+    expect(await status(session)).toBe(
+      'Goal: all tests pass\nStatus: paused, round 1 of 20.\nYou sent a message, so the goal paused. Run /goal resume to continue.\nLast check: Not yet.',
+    )
+    expect(calls).toHaveLength(2)
+    expect(lastMessage(calls[1])).toBe('what time is it?')
+
+    await session.command('goal', 'resume')
+    await waitForStatus(
+      session,
+      'Goal: all tests pass\nStatus: met, round 1 of 20.\nLast check: Done.',
+    )
+    // No extra goal turn ran after the user's message.
+    expect(calls).toHaveLength(3)
+    expect(lastMessage(calls[2])).toBe(
+      'Keep working on the goal: all tests pass. Last check: Not yet.',
+    )
+    await host.close()
+  })
+
+  it('pauses when a user message starts a turn while the goal is active', async () => {
+    // A host that stopped during a goal turn leaves the goal active.
+    const persistence = memoryPersistence()
+    const active: Goal = {
+      text: 'all tests pass',
+      status: 'active',
+      round: 1,
+      reason: '',
+      note: '',
+      queued: '',
+    }
+    await persistence.stores.metadata.set('plugin:tanstack/goal', 't', active)
+    const { host, session, calls, read } = await start({
+      persistence,
+      replies: [() => text('Hello.')],
+    })
+
+    await session.prompt('hello')
+    expect(await status(session)).toBe(
+      'Goal: all tests pass\nStatus: paused, round 1 of 20.\nYou sent a message, so the goal paused. Run /goal resume to continue.',
+    )
+    expect(calls).toHaveLength(1)
+    expect(read).toHaveLength(0)
+    await host.close()
+  })
+
+  it('does not start a turn when a turn waits for approval', async () => {
+    const remove = toolDefinition({
+      name: 'remove',
+      description: 'Remove a file',
+      needsApproval: true,
+      inputSchema: z.object({ path: z.string() }),
+    }).server(async () => ({ removed: true }))
+    const { host, session, calls, read } = await start({
+      replies: [() => toolCall('remove', { path: 'old.txt' })],
+      tools: [remove],
+    })
+
+    await session.command('goal', 'clean the folder')
+    await vi.waitFor(() =>
+      expect(session.snapshot().status).toBe('requires_action'),
+    )
+    expect(await status(session)).toBe(
+      'Goal: clean the folder\nStatus: paused, round 1 of 20.\nThe last turn waits for approval. Answer it, then run /goal resume.',
+    )
+    expect(calls).toHaveLength(1)
+    expect(read).toHaveLength(0)
+    expect(session.snapshot().queuedTurns).toBe(0)
+    await host.close()
+  })
+
+  it('pauses when the judge does not answer with a verdict', async () => {
+    const { adapter: judge } = mockAdapter([])
+    const { host, session, calls } = await start({
+      replies: [() => text('did something')],
+      judge,
+    })
+
+    await session.command('goal', 'all tests pass')
+    await waitForStatus(
+      session,
+      'Goal: all tests pass\nStatus: paused, round 1 of 20.\nThe judge failed: The judge did not answer with met and reason.',
+    )
+    expect(calls).toHaveLength(1)
+    await host.close()
+  })
+
+  it('keeps the goal and its state across a restart', async () => {
+    const persistence = memoryPersistence()
+    const first = await start({
+      persistence,
+      replies: [() => text('step one'), untilAborted()],
+      verdicts: [{ met: false, reason: 'Half done.' }],
+    })
+    await first.session.command('goal', 'all tests pass')
+    await vi.waitFor(() => expect(first.calls).toHaveLength(2))
+    await first.host.close()
+
+    const second = await start({
+      persistence,
+      replies: [() => text('all green')],
+      verdicts: [{ met: true, reason: 'All tests pass.' }],
+    })
+    expect(await status(second.session)).toBe(
+      'Goal: all tests pass\nStatus: paused, round 2 of 20.\nThe last turn was cancelled. Run /goal resume to continue.\nLast check: Half done.',
+    )
+    await second.session.command('goal', 'resume')
+    await waitForStatus(
+      second.session,
+      'Goal: all tests pass\nStatus: met, round 1 of 20.\nLast check: All tests pass.',
+    )
+    expect(lastMessage(second.calls[0])).toBe(
+      'Keep working on the goal: all tests pass. Last check: Half done.',
+    )
+    await second.host.close()
+  })
+})

From 142704c0685f8fec860ce5a3ff99ffcb573680b1 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 11:57:58 +0200
Subject: [PATCH 033/286] fix(ai-harness): a plugin prompt always queues its
 turn

With busy: 'reject', ctx.session.prompt() from a running turn was rejected
without a sign, so the goal loop stopped after one round.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-harness/src/session.ts     |  3 ++-
 packages/ai-harness/tests/goal.test.ts | 21 +++++++++++++++++++++
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index b8b0ab2085..3daa303e4e 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -691,7 +691,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       principal: this.principal,
       snapshot: () => this.snapshot(),
       prompt: (text) => {
-        this.prompt(text).then(
+        // A plugin turn always waits its turn. It cannot see a busy rejection.
+        this.prompt(text, { busy: 'queue' }).then(
           () => {},
           () => {},
         )
diff --git a/packages/ai-harness/tests/goal.test.ts b/packages/ai-harness/tests/goal.test.ts
index 2c4ab9e01a..6cf45493df 100644
--- a/packages/ai-harness/tests/goal.test.ts
+++ b/packages/ai-harness/tests/goal.test.ts
@@ -47,6 +47,7 @@ async function start(options: {
   maxRounds?: number
   tools?: Array<AnyTool>
   persistence?: ReturnType<typeof memoryPersistence>
+  busy?: 'queue' | 'reject'
 }) {
   const main = mockAdapter(options.replies)
   const scripted = scriptedJudge(options.verdicts ?? [])
@@ -64,6 +65,7 @@ async function start(options: {
       name: 'test/goal',
       adapter: main.adapter,
       tools: options.tools ?? [],
+      busy: options.busy,
       plugins: () => [
         goal({
           judge: options.judge ?? scripted.judge,
@@ -139,6 +141,25 @@ describe('goal', () => {
     await host.close()
   })
 
+  it('keeps going on a harness that rejects prompts while busy', async () => {
+    const { host, session, calls } = await start({
+      replies: [() => text('try one'), () => text('done')],
+      verdicts: [
+        { met: false, reason: 'Not yet.' },
+        { met: true, reason: 'Done.' },
+      ],
+      busy: 'reject',
+    })
+
+    await session.command('goal', 'finish')
+    await waitForStatus(
+      session,
+      'Goal: finish\nStatus: met, round 2 of 20.\nLast check: Done.',
+    )
+    expect(calls).toHaveLength(2)
+    await host.close()
+  })
+
   it('stops at the round limit and keeps the last reason', async () => {
     const { host, session, calls } = await start({
       replies: [() => text('try one'), () => text('try two')],

From d3a80cabecf1511ca9b930373918f4ef6b19ee36 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 12:23:54 +0200
Subject: [PATCH 034/286] fix(ai-harness): the goal plugin drops its queued
 turn when the goal pauses or stops

A message typed during the last model call of a goal turn runs first, as a
steer that came too late, and pauses the goal. The goal's next turn was already
queued and still ran once. ctx.session.prompt() now returns the turn, and the
goal plugin cancels its queued turn when a user message pauses the goal, on
/goal stop, and when a new goal replaces it.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/harness-p10-goal.md              |  2 ++
 packages/ai-harness/src/commands.ts         |  9 ++++---
 packages/ai-harness/src/first-party/goal.ts | 25 ++++++++++++++---
 packages/ai-harness/src/session.ts          |  9 ++-----
 packages/ai-harness/tests/goal.test.ts      | 30 +++++++++++++++++++++
 5 files changed, 62 insertions(+), 13 deletions(-)

diff --git a/.changeset/harness-p10-goal.md b/.changeset/harness-p10-goal.md
index 10e3a32402..bf27c56dca 100644
--- a/.changeset/harness-p10-goal.md
+++ b/.changeset/harness-p10-goal.md
@@ -3,3 +3,5 @@
 ---
 
 Add the `goal({ judge })` plugin to `@tanstack/ai-harness/plugins`. `/goal <text>` sets a goal and starts a turn. After each turn, the `judge` model reads the goal and the end of the transcript and decides if the goal is met. If it is not met, the plugin starts the next turn, up to `maxRounds` turns (20 by default). The loop also stops when a turn waits for approval or fails, and when the user sends a message. `/goal` shows the status, `/goal stop` ends the goal, and `/goal resume` continues it. The goal is plugin state, so it survives a restart. The `GoalMet` event tells other plugins and clients that the goal is met.
+
+A plugin's `ctx.session.prompt(text)` now returns the turn, so the plugin can cancel it before it starts. The turn always waits in the queue, also on a harness with `busy: 'reject'`.
diff --git a/packages/ai-harness/src/commands.ts b/packages/ai-harness/src/commands.ts
index 86a48a872e..cdbe22a790 100644
--- a/packages/ai-harness/src/commands.ts
+++ b/packages/ai-harness/src/commands.ts
@@ -1,6 +1,6 @@
 import type { InferSchemaType, ModelMessage, SchemaInput } from '@tanstack/ai'
 import type { SessionSnapshot } from './session'
-import type { Principal, Receipt } from './types'
+import type { ChatTurnResult, Operation, Principal, Receipt } from './types'
 
 /** A question a command asks the user. The host renders it from the schema. */
 export interface Question<TSchema extends SchemaInput | undefined = undefined> {
@@ -18,8 +18,11 @@ export interface PluginSessionApi {
   threadId: string
   principal: Principal | undefined
   snapshot: () => SessionSnapshot
-  /** Start a chat turn, as if the user typed `text`. */
-  prompt: (text: string) => void
+  /**
+   * Start a chat turn, as if the user typed `text`. While a turn runs, the new
+   * turn waits in the queue. Cancel the returned turn to drop it before it starts.
+   */
+  prompt: (text: string) => Operation<ChatTurnResult>
   /** The saved transcript. */
   transcript: () => Promise<Array<ModelMessage>>
   /** Replace the saved transcript (for example after a summary). */
diff --git a/packages/ai-harness/src/first-party/goal.ts b/packages/ai-harness/src/first-party/goal.ts
index f501b306cb..6d02511bbe 100644
--- a/packages/ai-harness/src/first-party/goal.ts
+++ b/packages/ai-harness/src/first-party/goal.ts
@@ -4,6 +4,7 @@ import { createPluginEvent } from '../extensions'
 import { definePlugin } from '../plugins'
 import { textOf, transcriptText } from './session-tools'
 import type { AnyTextAdapter } from '@tanstack/ai'
+import type { ChatTurnResult, Operation } from '../types'
 
 /** The goal of a session. It is plugin state, so it survives restarts. */
 export interface Goal {
@@ -84,6 +85,19 @@ export function goal(options: { judge: AnyTextAdapter; maxRounds?: number }) {
       let current = await state.get()
       // The run id of the plugin's own turn while it runs.
       let ownRun: string | undefined
+      // The turn the plugin queued, until it starts.
+      let queuedTurn: Operation<ChatTurnResult> | undefined
+
+      const queue = (message: string) => {
+        queuedTurn = ctx.session.prompt(message)
+      }
+
+      /** Cancel the queued turn if it has not started. */
+      const dropQueued = async () => {
+        const turn = queuedTurn
+        queuedTurn = undefined
+        if (turn?.status() === 'accepted') await turn.cancel()
+      }
 
       /** Change the goal, but only while `text` is still the active goal. */
       const change = async (text: string, next: Partial<Goal>) => {
@@ -103,8 +117,9 @@ export function goal(options: { judge: AnyTextAdapter; maxRounds?: number }) {
           reason === ''
             ? `Work toward this goal: ${text}`
             : keepWorking(text, reason)
-        // A turn that is still running belongs to the old goal.
+        // A turn that is still running or queued belongs to the old goal.
         ownRun = undefined
+        await dropQueued()
         current = await state.update(() => ({
           text,
           status: 'active',
@@ -113,7 +128,7 @@ export function goal(options: { judge: AnyTextAdapter; maxRounds?: number }) {
           note: '',
           queued: message,
         }))
-        ctx.session.prompt(message)
+        queue(message)
       }
 
       /** Pause the goal when the plugin's own turn ends early. */
@@ -173,6 +188,7 @@ export function goal(options: { judge: AnyTextAdapter; maxRounds?: number }) {
                   const isRunning =
                     current?.status === 'active' || current?.status === 'paused'
                   if (!isRunning) return 'No goal is running.'
+                  await dropQueued()
                   current = await state.update(
                     (saved) =>
                       saved && {
@@ -212,12 +228,15 @@ export function goal(options: { judge: AnyTextAdapter; maxRounds?: number }) {
                 last.role === 'user'
               if (!isNewMessage || saved?.status !== 'active') return
               if (textOf(last) !== saved.queued) {
+                // A late steer runs before the goal's queued turn. Drop that turn.
+                await dropQueued()
                 await change(saved.text, {
                   status: 'paused',
                   note: USER_MESSAGE,
                 })
                 return
               }
+              queuedTurn = undefined
               ownRun = run.runId
               await change(saved.text, { round: saved.round + 1, queued: '' })
             },
@@ -277,7 +296,7 @@ export function goal(options: { judge: AnyTextAdapter; maxRounds?: number }) {
               }
               const message = keepWorking(text, reason)
               if (await change(text, { reason, queued: message }))
-                ctx.session.prompt(message)
+                queue(message)
             },
           },
         ],
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 3daa303e4e..b0967e39d5 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -690,13 +690,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       threadId: this.threadId,
       principal: this.principal,
       snapshot: () => this.snapshot(),
-      prompt: (text) => {
-        // A plugin turn always waits its turn. It cannot see a busy rejection.
-        this.prompt(text, { busy: 'queue' }).then(
-          () => {},
-          () => {},
-        )
-      },
+      // A plugin turn always waits its turn. It cannot see a busy rejection.
+      prompt: (text) => this.prompt(text, { busy: 'queue' }),
       transcript: async () => [
         ...(await this.persistence.stores.messages.loadThread(this.threadId)),
       ],
diff --git a/packages/ai-harness/tests/goal.test.ts b/packages/ai-harness/tests/goal.test.ts
index 6cf45493df..bad35d7160 100644
--- a/packages/ai-harness/tests/goal.test.ts
+++ b/packages/ai-harness/tests/goal.test.ts
@@ -254,6 +254,36 @@ describe('goal', () => {
     await host.close()
   })
 
+  it('drops its queued turn when a late steer pauses the goal', async () => {
+    const hold = gate()
+    const { host, session, calls } = await start({
+      replies: [
+        after(hold.opened, 'step one'),
+        () => text('It is noon.'),
+        () => text('an extra goal turn'),
+      ],
+      verdicts: [{ met: false, reason: 'Not yet.' }],
+    })
+
+    await session.command('goal', 'all tests pass')
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    // The last model call of the turn is in flight, so the steer comes too late.
+    await session.steer('what time is it?')
+    hold.open()
+
+    await waitForStatus(
+      session,
+      'Goal: all tests pass\nStatus: paused, round 1 of 20.\nYou sent a message, so the goal paused. Run /goal resume to continue.\nLast check: Not yet.',
+    )
+    await vi.waitFor(() => {
+      expect(session.snapshot().status).toBe('idle')
+      expect(session.snapshot().queuedTurns).toBe(0)
+    })
+    expect(calls).toHaveLength(2)
+    expect(lastMessage(calls[1])).toBe('what time is it?')
+    await host.close()
+  })
+
   it('pauses when a user message starts a turn while the goal is active', async () => {
     // A host that stopped during a goal turn leaves the goal active.
     const persistence = memoryPersistence()

From 154e0ac2ef23db25d7653f53fbf0cb3a228fe69c Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 12:25:57 +0200
Subject: [PATCH 035/286] test(ai-isolate-daytona): cover each timeout branch
 with a controlled clock

The timeout tests use a 1 ms budget, so the branch they end in depends on how
many milliseconds pass. The coverage number moved between runs. New tests fix
the clock and reach each of the five timeout exits every run.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .../tests/timeout-budget.test.ts              | 122 ++++++++++++++++++
 1 file changed, 122 insertions(+)
 create mode 100644 packages/ai-isolate-daytona/tests/timeout-budget.test.ts

diff --git a/packages/ai-isolate-daytona/tests/timeout-budget.test.ts b/packages/ai-isolate-daytona/tests/timeout-budget.test.ts
new file mode 100644
index 0000000000..e0f9e0a79a
--- /dev/null
+++ b/packages/ai-isolate-daytona/tests/timeout-budget.test.ts
@@ -0,0 +1,122 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createDaytonaIsolateDriver } from '../src/isolate-driver'
+import { DAYTONA_RESULT_MARKER } from '../src/wrap-code'
+import type { ToolBinding } from '@tanstack/ai-code-mode'
+import type {
+  DaytonaCodeRunResponse,
+  DaytonaExecutionEnvelope,
+  DaytonaSandboxLike,
+} from '../src/types'
+
+// Each test controls the clock, so every timeout branch runs on every run.
+let clock = 0
+
+beforeEach(() => {
+  clock = 0
+  vi.spyOn(Date, 'now').mockImplementation(() => clock)
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+/** A sandbox whose codeRun answers with `response`, using the marker in the code. */
+function sandboxFor(
+  codeRun: () => Promise<DaytonaExecutionEnvelope>,
+): DaytonaSandboxLike {
+  return {
+    process: {
+      codeRun: async (code): Promise<DaytonaCodeRunResponse> => {
+        const marker =
+          code.match(/"(__TANSTACK_AI_CODE_MODE_RESULT__:[^"]+)"/)?.[1] ??
+          DAYTONA_RESULT_MARKER
+        const stdout = `${marker}${JSON.stringify(await codeRun())}`
+        return { exitCode: 0, result: stdout, artifacts: { stdout } }
+      },
+    },
+  }
+}
+
+function binding(execute: () => Promise<unknown>): ToolBinding {
+  return {
+    name: 'add',
+    description: 'add tool',
+    inputSchema: { type: 'object', properties: {} },
+    execute,
+  }
+}
+
+const needAdd: DaytonaExecutionEnvelope = {
+  status: 'need_tools',
+  toolCalls: [{ id: 'tc_0', name: 'add', args: {} }],
+  logs: ['before'],
+}
+
+async function run(
+  codeRun: () => Promise<DaytonaExecutionEnvelope>,
+  execute: () => Promise<unknown> = async () => 1,
+) {
+  const driver = createDaytonaIsolateDriver({
+    sandbox: sandboxFor(codeRun),
+    timeout: 50,
+  })
+  const context = await driver.createContext({
+    bindings: { add: binding(execute) },
+  })
+  return context.execute('return await add({})')
+}
+
+describe('Daytona timeout budget', () => {
+  it('times out before the first code run when the budget is used up', async () => {
+    const codeRun = vi.fn(async () => needAdd)
+    const driver = createDaytonaIsolateDriver({
+      sandbox: sandboxFor(codeRun),
+      timeout: 50,
+    })
+    const context = await driver.createContext({ bindings: {} })
+    // The deadline reads 0, the first check reads 100.
+    vi.mocked(Date.now).mockReturnValueOnce(0).mockReturnValue(100)
+
+    const result = await context.execute('return 1')
+
+    expect(result.error?.name).toBe('TimeoutError')
+    expect(codeRun).not.toHaveBeenCalled()
+  })
+
+  it('times out when the code run does not answer in time', async () => {
+    const result = await run(() => new Promise(() => {}))
+
+    expect(result.error?.name).toBe('TimeoutError')
+  })
+
+  it('times out before the tools when the code run used the budget', async () => {
+    const execute = vi.fn(async () => 1)
+    const result = await run(async () => {
+      clock = 100
+      return needAdd
+    }, execute)
+
+    expect(result.error?.name).toBe('TimeoutError')
+    expect(result.logs).toEqual(['before'])
+    expect(execute).not.toHaveBeenCalled()
+  })
+
+  it('times out when the tools do not answer in time', async () => {
+    const codeRun = vi.fn(async () => needAdd)
+    const result = await run(codeRun, () => new Promise(() => {}))
+
+    expect(result.error?.name).toBe('TimeoutError')
+    expect(codeRun).toHaveBeenCalledTimes(1)
+  })
+
+  it('times out after the tools when they used the budget', async () => {
+    const codeRun = vi.fn(async () => needAdd)
+    const result = await run(codeRun, async () => {
+      clock = 100
+      return 1
+    })
+
+    expect(result.error?.name).toBe('TimeoutError')
+    expect(codeRun).toHaveBeenCalledTimes(1)
+  })
+})

From 8b46a04b64d31715f9b60cd2273fa580162d8789 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 13:09:16 +0200
Subject: [PATCH 036/286] feat(ai-harness): session.transcript(),
 session.describe(), and plugin state in the snapshot

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-harness/src/index.ts              |   1 +
 packages/ai-harness/src/session.ts            |  55 ++++++++-
 .../ai-harness/tests/session-reads.test.ts    | 112 ++++++++++++++++++
 3 files changed, 165 insertions(+), 3 deletions(-)
 create mode 100644 packages/ai-harness/tests/session-reads.test.ts

diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index 01e56f91f9..9530b80254 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -69,6 +69,7 @@ export type {
   AgentRunOptions,
   AgentStartOptions,
   DynamicAgentHandle,
+  SessionDescription,
   SessionInspection,
   SessionSnapshot,
 } from './session'
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index b0967e39d5..eec819381f 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -128,6 +128,8 @@ export interface SessionSnapshot {
     message: string
     schema?: unknown
   }>
+  /** The state of each plugin that uses `ctx.state`, by plugin name. */
+  plugins: Record<string, unknown>
   /** The cursor of the newest event. */
   cursor: Cursor
 }
@@ -143,6 +145,24 @@ export interface SessionInspection {
   agents: Array<string>
 }
 
+/** What a UI can show and run in a session: commands, settings, and tools. */
+export interface SessionDescription {
+  commands: Array<{
+    name: string
+    description: string
+    owner: string
+    /** The command input as JSON Schema, when it has one. */
+    input?: unknown
+  }>
+  config: Array<{
+    key: string
+    owner: string
+    value: unknown
+    option: ConfigOption
+  }>
+  tools: SessionInspection['tools']
+}
+
 /** What the host hands a new session. */
 export interface SessionDependencies {
   harness: AnyHarness
@@ -245,6 +265,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }
   >()
   private readonly stateDoc: Record<string, unknown> = {}
+  /** Reads each plugin's saved state, so the first snapshot has it. */
+  private readonly stateLoaders = new Map<string, () => Promise<unknown>>()
   private readonly localState = new Map<string, unknown>()
   private readonly credentialAccess: CredentialsAccess
   private readonly services: PluginServices
@@ -361,6 +383,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       },
     )
     await this.loadConfig()
+    await this.loadPluginState()
     await this.recoverCrashedTurn()
     await this.recoverInbox()
   }
@@ -500,6 +523,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             : {}),
         }),
       ),
+      plugins: { ...this.stateDoc },
       cursor: this.feed.head(),
     }
   }
@@ -575,6 +599,25 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }))
   }
 
+  /** The saved messages of this thread, oldest first. */
+  async transcript() {
+    return [
+      ...(await this.persistence.stores.messages.loadThread(this.threadId)),
+    ]
+  }
+
+  /** The commands, settings, and tools of this session, for a UI. */
+  describe() {
+    return {
+      commands: this.commands(),
+      config: Object.entries(this.config()).map(([key, entry]) => ({
+        key,
+        ...entry,
+      })),
+      tools: this.inspect().tools,
+    } satisfies SessionDescription
+  }
+
   /** Run a plugin command. Its input is checked against the command's schema. */
   command(name: string, input?: unknown): Operation<unknown> {
     const operation = new OperationImpl<unknown>(
@@ -662,6 +705,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }
   }
 
+  /** Put each plugin's saved state in the snapshot before the first read. */
+  private async loadPluginState() {
+    for (const [plugin, load] of this.stateLoaders) {
+      if (!(plugin in this.stateDoc)) this.stateDoc[plugin] = await load()
+    }
+  }
+
   private ask(question: Question<SchemaInput | undefined>): Promise<unknown> {
     if (this.closing) return Promise.reject(new Error('Session closed.'))
     const questionId = `q-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`
@@ -692,9 +742,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       snapshot: () => this.snapshot(),
       // A plugin turn always waits its turn. It cannot see a busy rejection.
       prompt: (text) => this.prompt(text, { busy: 'queue' }),
-      transcript: async () => [
-        ...(await this.persistence.stores.messages.loadThread(this.threadId)),
-      ],
+      transcript: () => this.transcript(),
       replaceTranscript: (messages) =>
         this.persistence.stores.messages.saveThread(this.threadId, messages),
       // The public type narrows the answer from the schema.
@@ -749,6 +797,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         revision: null,
       }
     }
+    this.stateLoaders.set(plugin, async () => (await read()).value)
     const publish = (value: T) => {
       this.stateDoc[plugin] = value
       this.feed.publish('session', {
diff --git a/packages/ai-harness/tests/session-reads.test.ts b/packages/ai-harness/tests/session-reads.test.ts
new file mode 100644
index 0000000000..2013dd125c
--- /dev/null
+++ b/packages/ai-harness/tests/session-reads.test.ts
@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  configOption,
+  createHarnessHost,
+  defineCommand,
+  defineHarness,
+  definePlugin,
+} from '../src'
+import { mockAdapter, text } from './helpers'
+
+const counter = definePlugin({
+  name: 'test/counter',
+  setup: (ctx) => {
+    const state = ctx.state({ count: 0 })
+    return {
+      tools: [
+        toolDefinition({ name: 'ping', description: 'Ping' }).server(
+          async () => 'pong',
+        ),
+      ],
+      config: {
+        level: configOption.select({
+          options: ['low', 'high'],
+          default: 'low',
+        }),
+      },
+      commands: {
+        bump: defineCommand({
+          description: 'Add to the count',
+          input: z.object({ by: z.number() }),
+          run: async (input) => {
+            await state.update((saved) => ({ count: saved.count + input.by }))
+            return 'bumped'
+          },
+        }),
+      },
+    }
+  },
+})
+
+async function open(persistence = memoryPersistence()) {
+  const { adapter } = mockAdapter([() => text('hello back')])
+  const host = createHarnessHost({ persistence })
+  const session = await host.open(
+    defineHarness({ name: 'test/reads', adapter, plugins: () => [counter] }),
+    { threadId: 't' },
+  )
+  return { host, session }
+}
+
+describe('session reads for UIs', () => {
+  it('returns the saved transcript', async () => {
+    const { host, session } = await open()
+    await session.prompt('hi')
+
+    const messages = await session.transcript()
+
+    expect(messages[0]).toMatchObject({ role: 'user', content: 'hi' })
+    expect(JSON.stringify(messages)).toContain('hello back')
+    await host.close()
+  })
+
+  it('describes commands, settings, and tools', async () => {
+    const { host, session } = await open()
+
+    const description = session.describe()
+
+    expect(description.commands).toEqual([
+      expect.objectContaining({
+        name: 'bump',
+        description: 'Add to the count',
+        owner: 'test/counter',
+      }),
+    ])
+    expect(description.commands[0]?.input).toMatchObject({ type: 'object' })
+    expect(description.config).toEqual([
+      {
+        key: 'level',
+        owner: 'test/counter',
+        value: 'low',
+        option: expect.objectContaining({ type: 'select' }),
+      },
+    ])
+    expect(description.tools).toContainEqual({
+      name: 'ping',
+      owner: 'test/counter',
+    })
+    await host.close()
+  })
+
+  it('puts saved plugin state in the first snapshot', async () => {
+    const persistence = memoryPersistence()
+    const first = await open(persistence)
+    expect(first.session.snapshot().plugins).toEqual({
+      'test/counter': { count: 0 },
+    })
+    await first.session.command('bump', { by: 2 })
+    expect(first.session.snapshot().plugins).toEqual({
+      'test/counter': { count: 2 },
+    })
+    await first.host.close()
+
+    const second = await open(persistence)
+    expect(second.session.snapshot().plugins).toEqual({
+      'test/counter': { count: 2 },
+    })
+    await second.host.close()
+  })
+})

From 7364ac59f37cf082e53a31b0611763601ef443c6 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 13:14:00 +0200
Subject: [PATCH 037/286] feat(ai-harness): remote transcript and describe
 reads, client answer/command/setConfig, and connection state

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-harness/src/client.ts             |  53 ++++++--
 packages/ai-harness/src/http.ts               |  17 +++
 .../ai-harness/tests/client-reads.test.ts     | 120 ++++++++++++++++++
 3 files changed, 177 insertions(+), 13 deletions(-)
 create mode 100644 packages/ai-harness/tests/client-reads.test.ts

diff --git a/packages/ai-harness/src/client.ts b/packages/ai-harness/src/client.ts
index cd7f6d055d..9896e42243 100644
--- a/packages/ai-harness/src/client.ts
+++ b/packages/ai-harness/src/client.ts
@@ -1,9 +1,9 @@
 // Browser-safe: this module has type-only imports from the rest of the
 // package, so no server code (adapters, stores, secrets) reaches a client.
-import type { RunAgentResumeItem } from '@tanstack/ai'
+import type { ModelMessage, RunAgentResumeItem } from '@tanstack/ai'
 import type { AgentInputOf } from './agents'
 import type { AnyHarness, HarnessAgentsOf } from './define'
-import type { SessionSnapshot } from './session'
+import type { SessionDescription, SessionSnapshot } from './session'
 import type {
   BusyPolicy,
   Cursor,
@@ -46,15 +46,28 @@ export interface HarnessClient<THarness extends AnyHarness> {
   resolve: (resume: Array<RunAgentResumeItem>) => Promise<Receipt>
   cancel: (operationId?: string) => Promise<Receipt>
   agents: ClientAgentHandles<THarness>
+  /** Answer a question from a command or a plugin. */
+  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: (key: string, value: unknown) => 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>
   snapshot: () => Promise<SessionSnapshot>
+  /** The saved messages of the thread. */
+  transcript: () => Promise<Array<ModelMessage>>
+  /** The commands, settings, and tools of the session. */
+  describe: () => Promise<SessionDescription>
 }
 
 /**
@@ -90,8 +103,24 @@ export function createHarnessClient<THarness extends AnyHarness>(
     return body as Receipt
   }
 
+  const read = async <T>(route: string) => {
+    const query = new URLSearchParams({ threadId: options.threadId })
+    const response = await doFetch(`${base}/${route}?${query}`, {
+      headers: headers(),
+    })
+    if (!response.ok)
+      throw new Error(`Harness ${route} failed (${response.status})`)
+    // Each GET route answers with the type of the `HarnessClient` member
+    // that reads it. That member type sets `T`.
+    return (await response.json()) as T
+  }
+
   async function* events(
-    eventOptions: { from?: Cursor; signal?: AbortSignal } = {},
+    eventOptions: {
+      from?: Cursor
+      signal?: AbortSignal
+      onConnection?: (state: 'open' | 'reconnecting') => void
+    } = {},
   ) {
     let cursor = eventOptions.from
     const signal = eventOptions.signal
@@ -106,6 +135,7 @@ export function createHarnessClient<THarness extends AnyHarness>(
         if (!response.ok || !response.body) {
           throw new Error(`Harness events failed (${response.status})`)
         }
+        eventOptions.onConnection?.('open')
         const reader = response.body.getReader()
         // Some fetch shims ignore the signal once the body streams.
         signal?.addEventListener('abort', () => void reader.cancel(), {
@@ -149,6 +179,7 @@ export function createHarnessClient<THarness extends AnyHarness>(
           throw error
       }
       if (signal?.aborted) return
+      eventOptions.onConnection?.('reconnecting')
       await new Promise((resolve) =>
         setTimeout(resolve, options.reconnectDelayMs ?? 1000),
       )
@@ -183,16 +214,12 @@ export function createHarnessClient<THarness extends AnyHarness>(
     cancel: (operationId) =>
       send({ op: 'cancel', ...(operationId ? { operationId } : {}) }),
     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 }),
     events,
-    snapshot: async () => {
-      const query = new URLSearchParams({ threadId: options.threadId })
-      const response = await doFetch(`${base}/snapshot?${query}`, {
-        headers: headers(),
-      })
-      if (!response.ok)
-        throw new Error(`Harness snapshot failed (${response.status})`)
-      // The handler answers /snapshot with a SessionSnapshot.
-      return (await response.json()) as SessionSnapshot
-    },
+    snapshot: () => read('snapshot'),
+    transcript: () => read('transcript'),
+    describe: () => read('describe'),
   }
 }
diff --git a/packages/ai-harness/src/http.ts b/packages/ai-harness/src/http.ts
index 3f222d5425..54853d3a59 100644
--- a/packages/ai-harness/src/http.ts
+++ b/packages/ai-harness/src/http.ts
@@ -75,6 +75,8 @@ function lastUserText(messages: ReadonlyArray<unknown>): string | undefined {
  *   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  .../describe?threadId=`: the commands, settings, and tools.
  */
 export function createHarnessHandler(
   options: HarnessHandlerOptions,
@@ -192,6 +194,21 @@ export function createHarnessHandler(
         return json(await applyInput(harness, session, input))
       }
 
+      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()
+            : session.describe(),
+        )
+      }
+
       if (request.method === 'GET' && route === 'snapshot') {
         const threadId = url.searchParams.get('threadId')
         if (!threadId) return json({ error: 'threadId is required' }, 400)
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..9a0755b64a
--- /dev/null
+++ b/packages/ai-harness/tests/client-reads.test.ts
@@ -0,0 +1,120 @@
+import { describe, expect, it, vi } from 'vitest'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  configOption,
+  createHarnessHandler,
+  createHarnessHost,
+  defineCommand,
+  defineHarness,
+  definePlugin,
+} from '../src'
+import { createHarnessClient } from '../src/client'
+import { mockAdapter, text } 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],
+  })
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const handler = createHarnessHandler({
+    host,
+    harness,
+    authorize: () => ({ id: 'u' }),
+  })
+  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 }
+}
+
+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(question?.questionId ?? '', 'yes')).status,
+    ).toBe('accepted')
+    await vi.waitFor(async () =>
+      expect((await client.snapshot()).pendingQuestions).toHaveLength(0),
+    )
+
+    expect((await client.setConfig('tone', 'warm')).status).toBe('accepted')
+    expect((await client.describe()).config[0]?.value).toBe('warm')
+    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()
+  })
+})

From 7779044a313ba74a6f9b4cbf879ddec6d0638993 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 13:18:07 +0200
Subject: [PATCH 038/286] feat(ai-harness): session view state and its pure
 reducer

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-harness/src/view/reduce.ts        | 578 ++++++++++++++++++
 packages/ai-harness/src/view/types.ts         | 101 +++
 packages/ai-harness/tests/view-reduce.test.ts | 426 +++++++++++++
 3 files changed, 1105 insertions(+)
 create mode 100644 packages/ai-harness/src/view/reduce.ts
 create mode 100644 packages/ai-harness/src/view/types.ts
 create mode 100644 packages/ai-harness/tests/view-reduce.test.ts

diff --git a/packages/ai-harness/src/view/reduce.ts b/packages/ai-harness/src/view/reduce.ts
new file mode 100644
index 0000000000..ae85982bf2
--- /dev/null
+++ b/packages/ai-harness/src/view/reduce.ts
@@ -0,0 +1,578 @@
+import { EventType } from '@tanstack/ai'
+import { HARNESS_EVENTS } from '../types'
+import type { Interrupt, ModelMessage, StreamChunk } from '@tanstack/ai'
+import type { SessionDescription, SessionSnapshot } from '../session'
+import type { SessionEvent } from '../types'
+import type {
+  AgentPart,
+  Approval,
+  NoticeKind,
+  SessionViewState,
+  SignIn,
+  ToolCallPart,
+  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_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
+  question: (
+    question: SessionSnapshot['pendingQuestions'][number],
+  ) => ViewQuestion
+}
+
+/** The state of a view before it reads anything from its session. */
+export function emptyState(): SessionViewState {
+  return {
+    threadId: '',
+    status: 'idle',
+    connection: 'open',
+    messages: [],
+    approvals: [],
+    questions: [],
+    signIns: [],
+    agents: [],
+    queuedTurns: 0,
+    commands: [],
+    config: [],
+    tools: [],
+    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('')
+}
+
+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 : {}
+}
+
+/** 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 at the end of the messages. */
+export function withUserMessage(
+  state: SessionViewState,
+  text: string,
+): SessionViewState {
+  const message: ViewMessage = {
+    id: `user-${state.messages.length}`,
+    role: 'user',
+    text,
+  }
+  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> {
+  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,
+      args: parseJson(call.argsText),
+    }))
+  if (event.type === EventType.TOOL_CALL_RESULT)
+    return mapToolCall(parts, event.toolCallId, (call) => ({
+      ...call,
+      status: '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) => {
+    if (event.type === EventType.SUBAGENT_FINISHED)
+      return { ...agent, status: 'done' }
+    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 }
+  })
+}
+
+/** 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 }
+}
+
+/** 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))
+    return updateTurn(state, operationId, (parts) => applyToParts(parts, event))
+  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.operationResumed)
+    return withNotice(state, 'info', 'Resumed a turn that a crash stopped.')
+  if (event.name === COMMAND_RESULT)
+    return typeof value.result === 'string' && value.result !== ''
+      ? withNotice(state, 'command', value.result)
+      : state
+  if (event.name === HARNESS_EVENTS.inputRejected)
+    return withNotice(
+      state,
+      'rejected',
+      `Not accepted: ${String(value.reason ?? 'unknown reason')}`,
+    )
+  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
+}
+
+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 = message.parts.find(
+      (item) => item.type === 'tool-call' && item.id === id,
+    )
+    if (part?.type === 'tool-call') return part
+  }
+  return undefined
+}
+
+function markWaiting(
+  messages: Array<ViewMessage>,
+  waiting: ReadonlySet<string>,
+): Array<ViewMessage> {
+  if (waiting.size === 0) return messages
+  let changed = false
+  const next = messages.map((message) => {
+    if (message.role !== 'assistant') return message
+    let touched = false
+    const parts = message.parts.map((part) => {
+      const isWaiting =
+        part.type === 'tool-call' &&
+        part.status === 'running' &&
+        waiting.has(part.id)
+      if (!isWaiting) return part
+      touched = true
+      return { ...part, status: 'needs-approval' as const }
+    })
+    if (!touched) return message
+    changed = true
+    return { ...message, parts }
+  })
+  return changed ? next : messages
+}
+
+/** `old` when `next` holds the same items, so selectors see no change. */
+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
+}
+
+/**
+ * Take status, approvals, questions, and background agents 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.map(
+      (interrupt) =>
+        state.approvals.find((item) => item.id === interrupt.id) ??
+        factory.approval(
+          interrupt,
+          findToolCall(state.messages, interrupt.toolCallId),
+        ),
+    ),
+  )
+  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) ?? {
+            id: operation.id,
+            name: operation.agent ?? 'agent',
+          },
+      ),
+  )
+  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 &&
+    approvals === state.approvals &&
+    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,
+    approvals,
+    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,
+  }
+}
+
+/** Messages for a saved transcript. Tool results fill in their tool calls. */
+export function messagesFromTranscript(
+  messages: ReadonlyArray<ModelMessage>,
+): Array<ViewMessage> {
+  const result: Array<ViewMessage> = []
+  messages.forEach((message, index) => {
+    const id = message.id ?? `history-${index}`
+    if (message.role === 'user') {
+      result.push({ id, role: 'user', text: textOf(message.content) })
+      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',
+        })
+      }
+      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))
+  })
+  return result
+}
diff --git a/packages/ai-harness/src/view/types.ts b/packages/ai-harness/src/view/types.ts
new file mode 100644
index 0000000000..746a64d5f0
--- /dev/null
+++ b/packages/ai-harness/src/view/types.ts
@@ -0,0 +1,101 @@
+import type { ConfigOption } from '../config'
+import type { Receipt } 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
+  parts: Array<ViewPart>
+}
+
+export type ViewPart =
+  | { type: 'text'; text: string }
+  | { type: 'reasoning'; text: string }
+  | ToolCallPart
+  | AgentPart
+
+/** Why a notice line is there. */
+export type NoticeKind = 'info' | 'error' | 'rejected' | 'command' | 'ui'
+
+export type ViewMessage =
+  | { id: string; role: 'user'; text: string }
+  | { id: string; role: 'assistant'; parts: Array<ViewPart> }
+  | { id: string; role: 'notice'; kind: NoticeKind; text: string }
+
+/** A tool call that waits for a yes or no. */
+export interface Approval {
+  id: string
+  toolCallId?: string
+  tool: string
+  args: unknown
+  message?: string
+  approve: () => void
+  reject: () => 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
+  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
+}
+
+/** Everything a UI can show about a session. */
+export interface SessionViewState {
+  threadId: string
+  status: 'idle' | 'running' | 'requires_action'
+  connection: 'open' | 'reconnecting' | 'closed'
+  messages: Array<ViewMessage>
+  approvals: Array<Approval>
+  questions: Array<ViewQuestion>
+  signIns: Array<SignIn>
+  /** Background agents that run now. */
+  agents: Array<{ id: string; name: string }>
+  queuedTurns: number
+  commands: Array<ViewCommand>
+  config: Array<ViewConfigEntry>
+  tools: Array<{ name: string; owner: string }>
+  /** Each plugin's saved state, by plugin name. */
+  plugins: Record<string, unknown>
+}
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..a6b7f2b3e8
--- /dev/null
+++ b/packages/ai-harness/tests/view-reduce.test.ts
@@ -0,0 +1,426 @@
+import { describe, expect, it } from 'vitest'
+import { EventType } from '@tanstack/ai'
+import { HARNESS_EVENTS } from '../src'
+import {
+  applyDescription,
+  applyEvent,
+  applySnapshot,
+  emptyState,
+  messagesFromTranscript,
+  withNotice,
+} from '../src/view/reduce'
+import type { StreamChunk } from '@tanstack/ai'
+import type { SessionEvent, SessionSnapshot } from '../src'
+import type { ItemFactory } from '../src/view/reduce'
+import type { SessionViewState } from '../src/view/types'
+
+let cursor = 0
+const at = (event: StreamChunk, operationId = 'op-1'): SessionEvent => {
+  cursor += 1
+  return { cursor: String(cursor), operationId, event }
+}
+const fold = (events: Array<SessionEvent>, start = emptyState()) =>
+  events.reduce(applyEvent, start)
+const custom = (name: string, value: unknown) =>
+  at({ type: EventType.CUSTOM, name, value }, 'session')
+
+const factory: ItemFactory = {
+  approval: (interrupt, call) => ({
+    id: interrupt.id,
+    ...(interrupt.toolCallId ? { toolCallId: interrupt.toolCallId } : {}),
+    tool: call?.name ?? 'tool',
+    args: call?.args,
+    approve: () => {},
+    reject: () => {},
+  }),
+  question: (question) => ({
+    id: question.questionId,
+    message: question.message,
+    answer: async () => ({ inputId: 'i', status: 'accepted' }),
+  }),
+}
+
+const snapshot = (over: Partial<SessionSnapshot> = {}): SessionSnapshot => ({
+  threadId: 't',
+  status: 'idle',
+  activeOperations: [],
+  queuedTurns: 0,
+  pendingInterrupts: [],
+  pendingQuestions: [],
+  plugins: {},
+  cursor: '0',
+  ...over,
+})
+
+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('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' }),
+    ])
+    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',
+      },
+    ])
+    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',
+      }),
+    ])
+    expect(signedOut.signIns).toEqual([
+      { connector: 'notion', url: 'https://b', userCode: 'X1' },
+    ])
+    const next = applyEvent(
+      signedOut,
+      custom(HARNESS_EVENTS.operationStarted, {
+        operationId: 'op-9',
+        kind: 'chat',
+      }),
+    )
+    expect(next.signIns).toEqual([])
+  })
+
+  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 = snapshot({
+      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).toEqual([{ 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('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',
+    ])
+  })
+})

From 3bf4c0c81591b1ff4857bce5d937d5a932361b76 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 13:35:51 +0200
Subject: [PATCH 039/286] feat(ai-harness): createSessionView, a live TanStack
 Store view of a session for any UI

Adds @tanstack/store ^0.11.1 and the browser-safe ./view export. Three examples
listed @tanstack/store ^0.8.0 without importing it; they move to ^0.11.1 so the
workspace keeps one version (sherif).

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 examples/ts-code-mode-web/package.json |   2 +-
 examples/ts-react-chat/package.json    |   2 +-
 examples/ts-solid-chat/package.json    |   2 +-
 packages/ai-harness/package.json       |   7 +
 packages/ai-harness/src/view/index.ts  | 454 +++++++++++++++++++++++++
 packages/ai-harness/tests/helpers.ts   |   4 +-
 packages/ai-harness/tests/view.test.ts | 265 +++++++++++++++
 packages/ai-harness/vite.config.ts     |   1 +
 pnpm-lock.yaml                         |  23 +-
 9 files changed, 749 insertions(+), 11 deletions(-)
 create mode 100644 packages/ai-harness/src/view/index.ts
 create mode 100644 packages/ai-harness/tests/view.test.ts

diff --git a/examples/ts-code-mode-web/package.json b/examples/ts-code-mode-web/package.json
index 6ffbec8b6e..ed5a5978ee 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.158.4",
     "@tanstack/react-start": "^1.159.0",
     "@tanstack/router-plugin": "^1.158.4",
-    "@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 9b28013536..555fa7ecff 100644
--- a/examples/ts-react-chat/package.json
+++ b/examples/ts-react-chat/package.json
@@ -55,7 +55,7 @@
     "@tanstack/react-start": "^1.159.0",
     "@tanstack/react-store": "^0.8.0",
     "@tanstack/router-plugin": "^1.158.4",
-    "@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 bccf27dce9..5ac6e3b16a 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.139.10",
     "@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 fcecc105a1..00f9bd8934 100644
--- a/packages/ai-harness/package.json
+++ b/packages/ai-harness/package.json
@@ -34,6 +34,10 @@
       "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"
+    },
     "./plugins": {
       "types": "./dist/esm/first-party/index.d.ts",
       "import": "./dist/esm/first-party/index.js"
@@ -58,6 +62,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/view/index.ts b/packages/ai-harness/src/view/index.ts
new file mode 100644
index 0000000000..f8b3aace45
--- /dev/null
+++ b/packages/ai-harness/src/view/index.ts
@@ -0,0 +1,454 @@
+// Browser-safe: runtime imports only from @tanstack/ai, @tanstack/store,
+// ../types, and ./reduce. Everything else is a type.
+import { EventType } from '@tanstack/ai'
+import { createStore } from '@tanstack/store'
+import { HARNESS_EVENTS } from '../types'
+import {
+  applyDescription,
+  applyEvent,
+  applySnapshot,
+  emptyState,
+  messagesFromTranscript,
+  withNotice,
+  withUserMessage,
+} from './reduce'
+import type { ModelMessage, RunAgentResumeItem } from '@tanstack/ai'
+import type { ReadonlyStore } from '@tanstack/store'
+import type { PluginEvent } from '../extensions'
+import type { SessionDescription, SessionSnapshot } from '../session'
+import type { Cursor, Receipt, SessionEvent } from '../types'
+import type { ItemFactory } from './reduce'
+import type { Approval, SessionViewState, SignIn, ViewQuestion } from './types'
+
+export type {
+  AgentPart,
+  Approval,
+  NoticeKind,
+  SessionViewState,
+  SignIn,
+  ToolCallPart,
+  ToolCallStatus,
+  ViewCommand,
+  ViewConfigEntry,
+  ViewMessage,
+  ViewPart,
+  ViewQuestion,
+} from './types'
+
+/** A local `HarnessSession` and a remote `HarnessClient` both fit this. */
+export interface SessionViewSource {
+  prompt: (message: string) => unknown
+  steer: (message: string) => Promise<Receipt>
+  resolve: (resume: Array<RunAgentResumeItem>) => Promise<Receipt>
+  cancel: (operationId?: string) => Promise<Receipt>
+  answer: (questionId: string, value: unknown) => Promise<Receipt>
+  command: (name: string, input?: unknown) => unknown
+  setConfig: (key: string, value: unknown) => 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>
+}
+
+/** What `view.on(name, handler)` sends. */
+export interface SessionViewEvents {
+  approval: Approval
+  question: ViewQuestion
+  signIn: SignIn
+  toolCall: { id: string; name: string }
+  agent: { id: string; name: string; status: 'running' | 'done' | 'failed' }
+  error: string
+  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. Empty text does nothing. */
+  send: (text: string) => Promise<void>
+  command: (name: string, input?: unknown) => Promise<void>
+  setConfig: (key: string, value: unknown) => Promise<void>
+  cancel: () => Promise<void>
+  approve: (id: string) => void
+  reject: (id: string) => 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. Later actions throw. */
+  dispose: () => void
+}
+
+/** 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)/.test(event.name)
+  )
+}
+
+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')
+ * ```
+ */
+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>>()
+  const decisions = new Map<string, boolean>()
+  const chatTurns = new Set<string>()
+  const agentNames = new Map<string, string>()
+  let resolving = false
+  let disposed = false
+
+  const get = () => internal.state
+  const commit = (next: SessionViewState) => {
+    if (!disposed && next !== internal.state) internal.setState(() => next)
+  }
+  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)
+  }
+  const alive = () => {
+    if (disposed) throw new Error('The session view is disposed.')
+  }
+  /** 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(undefined, fail)
+  }
+
+  const decide = (id: string, approved: boolean) => {
+    alive()
+    const open = get().approvals
+    const isDecided =
+      resolving || decisions.has(id) || !open.some((item) => item.id === id)
+    if (isDecided) return
+    decisions.set(id, approved)
+    if (!open.every((item) => decisions.has(item.id))) return
+    const resume: Array<RunAgentResumeItem> = open.map((item) => ({
+      interruptId: item.id,
+      status: 'resolved',
+      payload: decisions.get(item.id),
+    }))
+    decisions.clear()
+    resolving = true
+    commit({ ...get(), approvals: [] })
+    void source
+      .resolve(resume)
+      .then(undefined, fail)
+      .finally(() => {
+        resolving = false
+        refreshSnapshot()
+      })
+  }
+  const decideAll = (approved: boolean) => {
+    alive()
+    const open = get().approvals
+    for (const item of open) decide(item.id, approved)
+  }
+
+  const factory: ItemFactory = {
+    approval: (interrupt, call) => ({
+      id: interrupt.id,
+      ...(interrupt.toolCallId ? { toolCallId: interrupt.toolCallId } : {}),
+      tool: call?.name ?? interrupt.message ?? 'tool',
+      args: call?.args,
+      ...(interrupt.message ? { message: interrupt.message } : {}),
+      approve: () => decide(interrupt.id, true),
+      reject: () => decide(interrupt.id, false),
+    }),
+    question: (question) => ({
+      id: question.questionId,
+      message: question.message,
+      ...(question.schema ? { schema: question.schema } : {}),
+      answer: (value) => {
+        alive()
+        return source.answer(question.questionId, value)
+      },
+    }),
+  }
+
+  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 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)
+    }
+  })
+
+  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',
+          `Not accepted: ${String(value.reason ?? 'unknown 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)
+      if (isTurnEnd) emit('turnEnd', { operationId })
+      if (event.name === HARNESS_EVENTS.configChanged) refreshDescription()
+    }
+    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
+        const before = get()
+        const after = applyEvent(before, entry)
+        commit(after)
+        fire(entry, before, after)
+        if (changesSnapshot(entry)) refreshSnapshot()
+      }
+    } catch (error) {
+      fail(error)
+    }
+    if (!disposed) commit({ ...get(), connection: 'closed' })
+  }
+
+  const ready = (async () => {
+    const [transcript, snapshot, description] = await Promise.all([
+      source.transcript().catch((error: unknown) => {
+        fail(error)
+        return []
+      }),
+      Promise.resolve(source.snapshot()).catch((error: unknown) => {
+        fail(error)
+        return undefined
+      }),
+      Promise.resolve(source.describe()).catch((error: unknown) => {
+        fail(error)
+        return undefined
+      }),
+    ])
+    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))
+    void read(snapshot?.cursor)
+  })()
+
+  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) => {
+      alive()
+      const line = text.trim()
+      if (line === '') 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))
+      if (get().status === 'running') {
+        await source.steer(line).then(undefined, fail)
+        return
+      }
+      settle(source.prompt(line))
+    },
+    command: async (name, input) => {
+      alive()
+      settle(source.command(name, input))
+    },
+    setConfig: async (key, value) => {
+      alive()
+      await source.setConfig(key, value).then(undefined, fail)
+    },
+    cancel: async () => {
+      alive()
+      await source.cancel().then(undefined, fail)
+    },
+    approve: (id) => decide(id, true),
+    reject: (id) => decide(id, false),
+    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()
+    },
+  }
+  return view
+}
diff --git a/packages/ai-harness/tests/helpers.ts b/packages/ai-harness/tests/helpers.ts
index ae2e3ed929..3dfac1066b 100644
--- a/packages/ai-harness/tests/helpers.ts
+++ b/packages/ai-harness/tests/helpers.ts
@@ -1,7 +1,9 @@
 import { EventType } from '@tanstack/ai'
 import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
 
-type Reply = (options: any) => AsyncIterable<StreamChunk> | Array<StreamChunk>
+export type Reply = (
+  options: any,
+) => AsyncIterable<StreamChunk> | Array<StreamChunk>
 
 /** A text adapter whose turns are scripted. Records every call. */
 export function mockAdapter(replies: Array<Reply> | Reply) {
diff --git a/packages/ai-harness/tests/view.test.ts b/packages/ai-harness/tests/view.test.ts
new file mode 100644
index 0000000000..bd21ff624e
--- /dev/null
+++ b/packages/ai-harness/tests/view.test.ts
@@ -0,0 +1,265 @@
+import { describe, expect, it, vi } from 'vitest'
+import { 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'
+
+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('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, view } = await openView([])
+    const before = view.store.get()
+    const slow = vi.spyOn(session, 'snapshot')
+
+    view.dispose()
+    await session.command('ping')
+    await new Promise((resolve) => setTimeout(resolve, 20))
+
+    expect(view.store.get()).toEqual({ ...before, connection: 'closed' })
+    expect(slow).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,
+      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()
+  })
+})
diff --git a/packages/ai-harness/vite.config.ts b/packages/ai-harness/vite.config.ts
index b5a782675a..17373da93a 100644
--- a/packages/ai-harness/vite.config.ts
+++ b/packages/ai-harness/vite.config.ts
@@ -31,6 +31,7 @@ export default mergeConfig(
     entry: [
       './src/index.ts',
       './src/client.ts',
+      './src/view/index.ts',
       './src/first-party/index.ts',
       './src/build.ts',
       './src/worker.ts',
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4b907ac390..ae52fe1c33 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -895,8 +895,8 @@ importers:
         specifier: ^1.158.4
         version: 1.159.5(@tanstack/react-router@1.159.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(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.1
       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.158.4
         version: 1.159.5(@tanstack/react-router@1.159.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(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.1
       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.1
       highlight.js:
         specifier: ^11.11.1
         version: 11.11.1
@@ -2609,6 +2609,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.1
     devDependencies:
       '@tanstack/ai':
         specifier: workspace:*
@@ -11110,6 +11114,9 @@ packages:
     resolution: {integrity: sha512-fQO+O/5xJpli5KlV6pwDz6DtpbqO/0atdVSyVnkemzk0Mej9azm4HXtw+cKkIPtsSplWs4B1EbMtgGMb9ADhSA==}
     engines: {node: '>=12'}
 
+  '@tanstack/store@0.11.1':
+    resolution: {integrity: sha512-mzTOBhypOuDJAy/D8n2MfUZ1HFkXnmSETviRyhqEC8LUE7/IZQExOTxMANj3KjTofYTkFNpBY67qaVrT41YccA==}
+
   '@tanstack/store@0.7.7':
     resolution: {integrity: sha512-xa6pTan1bcaqYDS9BDpSiS63qa6EoDkPN9RsRaxHuDdVDNntzq3xNwR5YKTU/V3SkSyC9T4YVOPh2zRQN0nhIQ==}
 
@@ -27884,7 +27891,7 @@ snapshots:
   '@tanstack/router-core@1.141.1':
     dependencies:
       '@tanstack/history': 1.141.0
-      '@tanstack/store': 0.8.0
+      '@tanstack/store': 0.8.1
       cookie-es: 2.0.0
       seroval: 1.4.0
       seroval-plugins: 1.4.0(seroval@1.4.0)
@@ -28714,6 +28721,8 @@ snapshots:
       - xml2js
       - yaml
 
+  '@tanstack/store@0.11.1': {}
+
   '@tanstack/store@0.7.7': {}
 
   '@tanstack/store@0.8.0': {}

From c902163d08146e0a95811482082860f584821e61 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 13:40:09 +0200
Subject: [PATCH 040/286] feat(ai-harness): selectGoal reads the goal from a
 session view

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-harness/src/first-party/goal.ts  | 20 ++++++++++++++++
 packages/ai-harness/src/first-party/index.ts |  2 +-
 packages/ai-harness/tests/goal.test.ts       | 24 +++++++++++++++++++-
 3 files changed, 44 insertions(+), 2 deletions(-)

diff --git a/packages/ai-harness/src/first-party/goal.ts b/packages/ai-harness/src/first-party/goal.ts
index 6d02511bbe..1ff059565a 100644
--- a/packages/ai-harness/src/first-party/goal.ts
+++ b/packages/ai-harness/src/first-party/goal.ts
@@ -5,6 +5,7 @@ import { definePlugin } from '../plugins'
 import { textOf, transcriptText } from './session-tools'
 import type { AnyTextAdapter } from '@tanstack/ai'
 import type { ChatTurnResult, Operation } from '../types'
+import type { SessionViewState } from '../view/types'
 
 /** The goal of a session. It is plugin state, so it survives restarts. */
 export interface Goal {
@@ -44,6 +45,25 @@ function isVerdict(value: unknown): value is { met: boolean; reason: string } {
   )
 }
 
+function isGoal(value: unknown): value is Goal {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'text' in value &&
+    typeof value.text === 'string' &&
+    'status' in value &&
+    typeof value.status === 'string' &&
+    'round' in value &&
+    typeof value.round === 'number'
+  )
+}
+
+/** The goal of the session a view shows, or `null` when there is none. */
+export function selectGoal(state: SessionViewState) {
+  const saved = state.plugins['tanstack/goal']
+  return isGoal(saved) ? saved : null
+}
+
 function keepWorking(text: string, reason: string) {
   return `Keep working on the goal: ${text}. Last check: ${reason}`
 }
diff --git a/packages/ai-harness/src/first-party/index.ts b/packages/ai-harness/src/first-party/index.ts
index 36f00240d2..1faf68eda7 100644
--- a/packages/ai-harness/src/first-party/index.ts
+++ b/packages/ai-harness/src/first-party/index.ts
@@ -17,5 +17,5 @@ export { formatTodos, todos } from './todos'
 export type { Todo } from './todos'
 export { fileCommands, projectInstructions } from './files'
 export { compact, usage } from './session-tools'
-export { GoalMet, goal } from './goal'
+export { GoalMet, goal, selectGoal } from './goal'
 export type { Goal } from './goal'
diff --git a/packages/ai-harness/tests/goal.test.ts b/packages/ai-harness/tests/goal.test.ts
index bad35d7160..c30016ce6e 100644
--- a/packages/ai-harness/tests/goal.test.ts
+++ b/packages/ai-harness/tests/goal.test.ts
@@ -3,7 +3,8 @@ import { z } from 'zod'
 import { toolDefinition } from '@tanstack/ai'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness, definePlugin } from '../src'
-import { GoalMet, goal } from '../src/first-party'
+import { GoalMet, goal, selectGoal } from '../src/first-party'
+import { createSessionView } from '../src/view'
 import {
   after,
   gate,
@@ -380,4 +381,25 @@ describe('goal', () => {
     )
     await second.host.close()
   })
+
+  it('gives a UI the goal through the session view', async () => {
+    const { host, session } = await start({
+      replies: [() => text('done')],
+      verdicts: [{ met: true, reason: 'Done.' }],
+    })
+    const view = createSessionView(session)
+    await view.ready
+    expect(selectGoal(view.store.get())).toBeNull()
+
+    await session.command('goal', 'finish')
+
+    await vi.waitFor(() =>
+      expect(selectGoal(view.store.get())).toMatchObject({
+        text: 'finish',
+        status: 'met',
+      }),
+    )
+    view.dispose()
+    await host.close()
+  })
 })

From 4f87a949279517de30cdb0064e5f3726207c4308 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 13:55:06 +0200
Subject: [PATCH 041/286] docs(ai-harness): build your own UI with
 createSessionView

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/harness-p11-session-view.md |   7 +
 docs/config.json                       |   5 +
 docs/harness/custom-ui.md              | 316 +++++++++++++++++++++++++
 docs/harness/dashboard.md              |   2 +-
 docs/harness/deploy.md                 |   2 +-
 docs/harness/subagents.md              |   2 +-
 6 files changed, 331 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/harness-p11-session-view.md
 create mode 100644 docs/harness/custom-ui.md

diff --git a/.changeset/harness-p11-session-view.md b/.changeset/harness-p11-session-view.md
new file mode 100644
index 0000000000..845ea5b33b
--- /dev/null
+++ b/.changeset/harness-p11-session-view.md
@@ -0,0 +1,7 @@
+---
+'@tanstack/ai-harness': minor
+---
+
+Add `createSessionView(session | client)` at `@tanstack/ai-harness/view`. It keeps a live TanStack Store of everything a UI shows: messages with streaming text, tool calls, and child agents, plus approvals, questions, sign-ins, status, background agents, commands, settings, tools, and plugin state. It has actions (`send`, `command`, `setConfig`, `cancel`, `approve`, `reject`) and typed events (`view.on('approval', ...)`, `view.on(GoalMet, ...)`). It works with any UI library through the TanStack Store adapters or `store.subscribe`, and it works in the browser with `createHarnessClient`.
+
+New reads for it: `session.transcript()`, `session.describe()`, `snapshot().plugins`, and on the client `transcript()`, `describe()`, `answer()`, `command()`, `setConfig()`, and `events({ onConnection })`. `createHarnessHandler` serves `GET .../transcript` and `GET .../describe`. `selectGoal(state)` reads the goal from a view.
diff --git a/docs/config.json b/docs/config.json
index 23fa369fbf..70c5e697e7 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -861,6 +861,11 @@
           "to": "harness/goal",
           "addedAt": "2026-09-28"
         },
+        {
+          "label": "Build your own UI",
+          "to": "harness/custom-ui",
+          "addedAt": "2026-09-28"
+        },
         {
           "label": "Run agents from a harness",
           "to": "harness/subagents",
diff --git a/docs/harness/custom-ui.md b/docs/harness/custom-ui.md
new file mode 100644
index 0000000000..a57e2d3681
--- /dev/null
+++ b/docs/harness/custom-ui.md
@@ -0,0 +1,316 @@
+---
+title: Build your own UI
+id: harness-custom-ui
+order: 12
+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-5.6'),
+})
+
+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.
+
+## 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.
+- `questions`: questions from a command or a plugin.
+- `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.
+- `queuedTurns`: the number of messages that wait for their turn.
+- `commands`, `config`, and `tools`: what the session has, for a help screen or a settings panel.
+- `plugins`: the saved state of each plugin, by plugin name.
+
+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`.
+
+A notice has a `kind`:
+
+- `info`: the session continues a turn that a crash stopped.
+- `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
+
+Start and stop 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.command(name, input)`: runs a command, for example from a button.
+- `view.setConfig(key, value)`: changes a setting, for example `view.setConfig('mode', 'plan')`.
+- `view.cancel()`: cancels the running turn.
+- `view.dispose()`: stops the view when your screen closes. After that, each action throws an error.
+
+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.
+- `question.answer(value)`: answers a question.
+
+If a turn waits for more than one approval, the turn continues after you answer all of them.
+
+## 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.
+- `'question'`: a question with a `message`, a `schema`, 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.
+
+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.
+
+## 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. A plugin can export a selector that checks the shape of its state for you.
+
+With the [goal plugin](./goal) in your harness, `selectGoal` reads the goal from the state, or gives `null`. `GoalMet` is the typed event of the plugin:
+
+```ts group=harness-custom-ui
+import { GoalMet, selectGoal } from '@tanstack/ai-harness/plugins'
+
+const goal = selectGoal(view.store.get())
+if (goal) view.notice(`Goal: ${goal.text} (${goal.status}, round ${goal.round})`)
+
+view.on(GoalMet, (met) => view.notice(`Goal met: ${met.reason}`))
+```
+
+In a component, give the selector to `useSelector`: `useSelector(view.store, selectGoal)`. `view.on` takes any plugin event from `createPluginEvent`, and the handler gets its typed value. `@tanstack/ai-harness/plugins` runs only in Node, so use it with a local session. In a browser, read `state.plugins['tanstack/goal']` and 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-5.6'),
+})
+
+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()`.
+
+## 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.
+- Actions, typed events, and plugin state that work with any UI library.
diff --git a/docs/harness/dashboard.md b/docs/harness/dashboard.md
index a93340c52a..e83f0630b8 100644
--- a/docs/harness/dashboard.md
+++ b/docs/harness/dashboard.md
@@ -1,7 +1,7 @@
 ---
 title: Self-host the dashboard
 id: harness-dashboard
-order: 14
+order: 15
 description: "Watch and steer your harness sessions from a browser or a phone. Agents dial out to your dashboard server, so they need no open port."
 keywords:
   - tanstack ai
diff --git a/docs/harness/deploy.md b/docs/harness/deploy.md
index da8968388b..f5d875f1f0 100644
--- a/docs/harness/deploy.md
+++ b/docs/harness/deploy.md
@@ -1,7 +1,7 @@
 ---
 title: Deploy a harness
 id: harness-deploy
-order: 13
+order: 14
 description: "Run a harness in your server, as a worker process, on another machine, or as a single executable."
 keywords:
   - tanstack ai
diff --git a/docs/harness/subagents.md b/docs/harness/subagents.md
index 24fc535b0a..e97c17718a 100644
--- a/docs/harness/subagents.md
+++ b/docs/harness/subagents.md
@@ -1,7 +1,7 @@
 ---
 title: Run agents from a harness
 id: harness-subagents
-order: 12
+order: 13
 description: "Start typed agents from commands and plugins, run them in groups, call a whole harness as a child, and keep the tree within limits."
 keywords:
   - tanstack ai

From 3a53aa2d44d2881f26fa9b2e37d77e896243cb98 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 14:19:16 +0200
Subject: [PATCH 042/286] feat(ai-harness-cli)!: no UI library in the CLI;
 runCli({ ui }) runs any TUI on a session view

The CLI no longer depends on ink or react. An interactive terminal uses line
mode unless runCli gets a ui function, which receives a ready session view and
resolves when the user quits.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-harness-cli/package.json          |   5 -
 packages/ai-harness-cli/src/index.ts          |  20 +-
 packages/ai-harness-cli/src/interactive.tsx   | 184 ---------------
 packages/ai-harness-cli/tests/cli.test.ts     | 110 +++++++--
 .../ai-harness-cli/tests/interactive.test.ts  | 106 ---------
 pnpm-lock.yaml                                | 213 ------------------
 6 files changed, 104 insertions(+), 534 deletions(-)
 delete mode 100644 packages/ai-harness-cli/src/interactive.tsx
 delete mode 100644 packages/ai-harness-cli/tests/interactive.test.ts

diff --git a/packages/ai-harness-cli/package.json b/packages/ai-harness-cli/package.json
index 63dc20c327..682b353e9a 100644
--- a/packages/ai-harness-cli/package.json
+++ b/packages/ai-harness-cli/package.json
@@ -65,10 +65,6 @@
     "terminal",
     "acp"
   ],
-  "dependencies": {
-    "ink": "^7.1.1",
-    "react": "^19.2.3"
-  },
   "peerDependencies": {
     "@tanstack/ai": "workspace:^",
     "@tanstack/ai-acp": "workspace:^",
@@ -91,7 +87,6 @@
     "@tanstack/ai-harness": "workspace:*",
     "@tanstack/ai-persistence": "workspace:*",
     "@tanstack/ai-sandbox": "workspace:*",
-    "@types/react": "^19.2.7",
     "@vitest/coverage-v8": "4.1.10",
     "zod": "^4.2.0"
   }
diff --git a/packages/ai-harness-cli/src/index.ts b/packages/ai-harness-cli/src/index.ts
index 18dbac479d..92dfde9bb6 100644
--- a/packages/ai-harness-cli/src/index.ts
+++ b/packages/ai-harness-cli/src/index.ts
@@ -1,9 +1,11 @@
 import { createHarnessHost } from '@tanstack/ai-harness'
+import { createSessionView } from '@tanstack/ai-harness/view'
 import { USAGE, parseCliArgs } from './args'
 import { runLines } from './lines'
 import { EXIT, runPrint } from './print'
 import { createToken, serve } from './serve'
 import type { AnyHarness, HarnessPersistence } from '@tanstack/ai-harness'
+import type { SessionView } from '@tanstack/ai-harness/view'
 
 export interface RunCliOptions {
   /** Where sessions keep state. Default: in memory. */
@@ -14,6 +16,12 @@ export interface RunCliOptions {
   stdout?: { write: (text: string) => unknown }
   stderr?: { write: (text: string) => unknown }
   env?: Record<string, string | undefined>
+  /**
+   * Your own screen for an interactive terminal, with any UI library. It gets
+   * a ready session view and resolves when the user quits. Piped input and
+   * the other modes (`--print`, `--acp`, `--serve`, `--dashboard`) do not use it.
+   */
+  ui?: (view: SessionView) => Promise<void> | void
 }
 
 /**
@@ -122,10 +130,14 @@ export async function runCli(
         stderr,
       })
     }
-    if (stdin.isTTY) {
-      // Loaded only here, so the other modes never load React or Ink.
-      const { runInteractive } = await import('./interactive')
-      await runInteractive(session, harness)
+    if (stdin.isTTY && options.ui) {
+      const view = createSessionView(session)
+      try {
+        await view.ready
+        await options.ui(view)
+      } finally {
+        view.dispose()
+      }
     } else {
       await runLines(session, stdin, stdout)
     }
diff --git a/packages/ai-harness-cli/src/interactive.tsx b/packages/ai-harness-cli/src/interactive.tsx
deleted file mode 100644
index 081b9d078e..0000000000
--- a/packages/ai-harness-cli/src/interactive.tsx
+++ /dev/null
@@ -1,184 +0,0 @@
-import { useEffect, useState } from 'react'
-import { Box, Text, render, useApp, useInput } from 'ink'
-import { HARNESS_EVENTS } from '@tanstack/ai-harness'
-import { EventType } from '@tanstack/ai'
-import { handleLine } from './commands'
-import {
-  applyEvent,
-  approvalQuestion,
-  openUrl,
-  resolveAll,
-} from './session-view'
-import type {
-  AnyHarness,
-  HarnessSession,
-  SessionSnapshot,
-} from '@tanstack/ai-harness'
-import type { ViewEntry } from './session-view'
-
-const MAX_ENTRIES = 200
-
-function Entry({ entry }: { entry: ViewEntry }) {
-  switch (entry.kind) {
-    case 'user':
-      return <Text color="cyan">{`> ${entry.text}`}</Text>
-    case 'assistant':
-      return <Text>{entry.text}</Text>
-    case 'tool':
-      return <Text color="yellow">{`  - ${entry.text}`}</Text>
-    case 'notice':
-      return <Text color="gray">{entry.text}</Text>
-    case 'agent': {
-      // The child's latest words, live, while it works.
-      const latest = entry.answer.replace(/\s+/g, ' ').trim().slice(-80)
-      return (
-        <Text color="magenta">{`  - ${entry.text}${latest ? `: ${latest}` : ''}`}</Text>
-      )
-    }
-  }
-}
-
-function App({
-  session,
-  harness,
-}: {
-  session: HarnessSession
-  harness: AnyHarness
-}) {
-  const { exit } = useApp()
-  const [entries, setEntries] = useState<Array<ViewEntry>>([
-    { kind: 'notice', text: `${harness.name}. Type /help for commands.` },
-  ])
-  const [input, setInput] = useState('')
-  const [snapshot, setSnapshot] = useState<SessionSnapshot>(() =>
-    session.snapshot(),
-  )
-
-  useEffect(() => {
-    const reader = new AbortController()
-    void (async () => {
-      for await (const entry of session.events({
-        from: session.snapshot().cursor,
-        signal: reader.signal,
-      })) {
-        setEntries((current) => applyEvent(current, entry).slice(-MAX_ENTRIES))
-        const event = entry.event
-        if (event.type === EventType.CUSTOM) {
-          if (event.name === HARNESS_EVENTS.authRequired) {
-            const url = (event.value as { url?: unknown }).url
-            if (typeof url === 'string') openUrl(url)
-          }
-          // Let the operation settle before reading the status.
-          setTimeout(() => setSnapshot(session.snapshot()), 0)
-        }
-      }
-    })()
-    return () => reader.abort()
-  }, [session])
-
-  const notice = (text: string) =>
-    setEntries((current) =>
-      [...current, { kind: 'notice' as const, text }].slice(-MAX_ENTRIES),
-    )
-
-  const submit = async (line: string) => {
-    const current = session.snapshot()
-    if (current.status === 'requires_action') {
-      const approved = /^y(es)?$/i.test(line.trim())
-      await resolveAll(session, current.pendingInterrupts, approved)
-      notice(approved ? 'Approved.' : 'Rejected.')
-      return
-    }
-    if (line.trim() !== '' && !line.trim().startsWith('/')) {
-      setEntries((list) =>
-        [...list, { kind: 'user' as const, text: line.trim() }].slice(
-          -MAX_ENTRIES,
-        ),
-      )
-    }
-    const result = await handleLine(session, line)
-    if (result.type === 'exit') exit()
-    else if (result.type === 'notice' && result.text) notice(result.text)
-    setSnapshot(session.snapshot())
-  }
-
-  useInput((character, key) => {
-    if (key.escape) {
-      void session.cancel().then(() => setSnapshot(session.snapshot()))
-      return
-    }
-    if (key.return) {
-      const line = input
-      setInput('')
-      void submit(line)
-      return
-    }
-    if (key.backspace || key.delete) {
-      setInput((current) => current.slice(0, -1))
-      return
-    }
-    if (key.ctrl || key.meta || !character) return
-    // A paste (or fast typing) can arrive as one chunk with line breaks in it.
-    const [first = '', ...rest] = character.split(/\r\n|\r|\n/)
-    if (rest.length === 0) {
-      setInput((current) => current + first)
-      return
-    }
-    const lines = [input + first, ...rest.slice(0, -1)]
-    setInput(rest.at(-1) ?? '')
-    void (async () => {
-      for (const line of lines) await submit(line)
-    })()
-  })
-
-  const question = snapshot.pendingQuestions[0]
-  const status = question
-    ? `${question.message} (type your answer)`
-    : snapshot.status === 'running'
-      ? 'working (Esc to cancel, Enter steers)'
-      : snapshot.status === 'requires_action'
-        ? approvalQuestion(snapshot.pendingInterrupts)
-        : 'ready'
-  const background = snapshot.activeOperations.filter(
-    (operation) => operation.kind === 'agent',
-  )
-
-  return (
-    <Box flexDirection="column">
-      {entries.map((entry, index) => (
-        <Entry key={index} entry={entry} />
-      ))}
-      <Box marginTop={1}>
-        <Text
-          color={snapshot.status === 'requires_action' ? 'magenta' : 'gray'}
-        >
-          {status}
-          {background.length > 0
-            ? ` | agents: ${background.map((operation) => operation.agent).join(', ')}`
-            : ''}
-          {snapshot.queuedTurns > 0 ? ` | queued: ${snapshot.queuedTurns}` : ''}
-        </Text>
-      </Box>
-      <Text>
-        <Text color="cyan">{'> '}</Text>
-        {input}
-        <Text inverse> </Text>
-      </Text>
-    </Box>
-  )
-}
-
-/** Start the interactive UI. Resolves when the user quits. */
-export async function runInteractive(
-  session: HarnessSession,
-  harness: AnyHarness,
-  streams: {
-    stdin?: NodeJS.ReadStream
-    stdout?: NodeJS.WriteStream
-    /** Route `console` output above the UI. Default true. */
-    patchConsole?: boolean
-  } = {},
-): Promise<void> {
-  const instance = render(<App session={session} harness={harness} />, streams)
-  await instance.waitUntilExit()
-}
diff --git a/packages/ai-harness-cli/tests/cli.test.ts b/packages/ai-harness-cli/tests/cli.test.ts
index 7b2b8649b5..ec83ad229b 100644
--- a/packages/ai-harness-cli/tests/cli.test.ts
+++ b/packages/ai-harness-cli/tests/cli.test.ts
@@ -68,6 +68,7 @@ function scripted(turns: Array<Array<StreamChunk>>) {
     kind: 'text',
     name: 'mock',
     model: 'test-model',
+    // `~types` holds types only. Its values are never read, so they are casts.
     '~types': {
       providerOptions: {} as Record<string, unknown>,
       inputModalities: ['text'] as readonly ['text'],
@@ -105,6 +106,15 @@ function capture() {
   }
 }
 
+/** A stdin that reads `lines`, as a terminal or as a pipe. */
+function stdinFrom(lines: Array<string>, { isTTY }: { isTTY: boolean }) {
+  // NodeJS.ReadStream is a TTY socket. A test cannot make one without a real
+  // terminal, and runCli only reads the lines and `isTTY`, so this casts.
+  return Object.assign(Readable.from(lines), {
+    isTTY,
+  }) as unknown as NodeJS.ReadStream
+}
+
 describe('parseCliArgs', () => {
   it('reads flags and rejects bad values', () => {
     expect(parseCliArgs(['-p', 'hi', '--output', 'ndjson'])).toMatchObject({
@@ -189,13 +199,6 @@ describe('line mode', () => {
       textTurn('Done removing.'),
     ])
     const stdout = capture()
-    const input = Readable.from([
-      'hello\n',
-      'remove the file\n',
-      'y\n',
-      '/agents\n',
-      '/exit\n',
-    ])
     const code = await runCli(
       defineHarness({
         name: 'test/lines',
@@ -211,9 +214,10 @@ describe('line mode', () => {
       }),
       {
         argv: [],
-        stdin: Object.assign(input, {
-          isTTY: false,
-        }) as unknown as NodeJS.ReadStream,
+        stdin: stdinFrom(
+          ['hello\n', 'remove the file\n', 'y\n', '/agents\n', '/exit\n'],
+          { isTTY: false },
+        ),
         stdout,
         stderr: capture(),
         persistence: memoryPersistence(),
@@ -260,15 +264,6 @@ describe('plugin commands in line mode', () => {
     })
     const { adapter } = scripted([])
     const stdout = capture()
-    const input = Readable.from([
-      '/greet {"name":"Ada"}\n',
-      '/confirm\n',
-      'yes\n',
-      '/config tone warm\n',
-      '/config\n',
-      '/help\n',
-      '/exit\n',
-    ])
     await runCli(
       defineHarness({
         name: 'test/plugin-lines',
@@ -277,9 +272,18 @@ describe('plugin commands in line mode', () => {
       }),
       {
         argv: [],
-        stdin: Object.assign(input, {
-          isTTY: false,
-        }) as unknown as NodeJS.ReadStream,
+        stdin: stdinFrom(
+          [
+            '/greet {"name":"Ada"}\n',
+            '/confirm\n',
+            'yes\n',
+            '/config tone warm\n',
+            '/config\n',
+            '/help\n',
+            '/exit\n',
+          ],
+          { isTTY: false },
+        ),
         stdout,
         stderr: capture(),
         persistence: memoryPersistence(),
@@ -335,3 +339,65 @@ describe('serve mode', () => {
     }
   })
 })
+
+describe('custom ui', () => {
+  it('gives an interactive terminal a ready session view and waits for the ui', async () => {
+    const { adapter } = scripted([textTurn('Hi from the ui.')])
+    const seen: Array<string> = []
+    const code = await runCli(defineHarness({ name: 'test/ui', adapter }), {
+      argv: [],
+      stdin: stdinFrom([], { isTTY: true }),
+      stdout: capture(),
+      stderr: capture(),
+      persistence: memoryPersistence(),
+      ui: async (view) => {
+        seen.push(view.store.get().threadId)
+        await view.send('hello')
+        await vi.waitFor(() =>
+          expect(JSON.stringify(view.store.get().messages)).toContain(
+            'Hi from the ui.',
+          ),
+        )
+      },
+    })
+    expect(code).toBe(EXIT.ok)
+    expect(seen).toEqual(['main'])
+  })
+
+  it('uses line mode for piped input, even with a ui', async () => {
+    const { adapter } = scripted([textTurn('Piped answer.')])
+    const stdout = capture()
+    const ui = vi.fn()
+    const code = await runCli(
+      defineHarness({ name: 'test/ui-piped', adapter }),
+      {
+        argv: [],
+        stdin: stdinFrom(['hello\n'], { isTTY: false }),
+        stdout,
+        stderr: capture(),
+        persistence: memoryPersistence(),
+        ui,
+      },
+    )
+    expect(code).toBe(EXIT.ok)
+    expect(ui).not.toHaveBeenCalled()
+    expect(stdout.text).toContain('Piped answer.')
+  })
+
+  it('uses line mode in a terminal without a ui', async () => {
+    const { adapter } = scripted([textTurn('Terminal answer.')])
+    const stdout = capture()
+    const code = await runCli(
+      defineHarness({ name: 'test/ui-none', adapter }),
+      {
+        argv: [],
+        stdin: stdinFrom(['hello\n'], { isTTY: true }),
+        stdout,
+        stderr: capture(),
+        persistence: memoryPersistence(),
+      },
+    )
+    expect(code).toBe(EXIT.ok)
+    expect(stdout.text).toContain('Terminal answer.')
+  })
+})
diff --git a/packages/ai-harness-cli/tests/interactive.test.ts b/packages/ai-harness-cli/tests/interactive.test.ts
deleted file mode 100644
index 9eaeb2845b..0000000000
--- a/packages/ai-harness-cli/tests/interactive.test.ts
+++ /dev/null
@@ -1,106 +0,0 @@
-import { PassThrough } from 'node:stream'
-import { describe, expect, it } from 'vitest'
-import { EventType } from '@tanstack/ai'
-import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
-import { memoryPersistence } from '@tanstack/ai-persistence'
-import { runInteractive } from '../src/interactive'
-import type { AnyTextAdapter } from '@tanstack/ai'
-
-const now = () => Date.now()
-const adapter: AnyTextAdapter = {
-  kind: 'text',
-  name: 'mock',
-  model: 'test-model',
-  '~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,
-  },
-  chatStream: () =>
-    (async function* () {
-      yield {
-        type: EventType.RUN_STARTED,
-        runId: 'r',
-        threadId: 't',
-        timestamp: now(),
-      }
-      yield {
-        type: EventType.TEXT_MESSAGE_START,
-        messageId: 'm',
-        role: 'assistant',
-        timestamp: now(),
-      }
-      yield {
-        type: EventType.TEXT_MESSAGE_CONTENT,
-        messageId: 'm',
-        delta: 'Hi from the Ink UI',
-        timestamp: now(),
-      }
-      yield {
-        type: EventType.TEXT_MESSAGE_END,
-        messageId: 'm',
-        timestamp: now(),
-      }
-      yield {
-        type: EventType.RUN_FINISHED,
-        runId: 'r',
-        threadId: 't',
-        timestamp: now(),
-        metadata: { tanstack: { finishReason: 'stop' } },
-      }
-    })(),
-  structuredOutput: async () => ({ data: {}, rawText: '{}' }),
-}
-
-const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
-
-describe('interactive UI', () => {
-  it('sends a typed line, shows the answer, and quits on /exit', async () => {
-    const harness = defineHarness({ name: 'test/ink', adapter })
-    const host = createHarnessHost({ persistence: memoryPersistence() })
-    const session = await host.open(harness, { threadId: 'ink' })
-
-    const stdin = Object.assign(new PassThrough(), {
-      isTTY: true,
-      setRawMode: () => stdin,
-      ref: () => stdin,
-      unref: () => stdin,
-    })
-    let output = ''
-    const stdout = Object.assign(new PassThrough(), {
-      isTTY: true,
-      columns: 100,
-      rows: 30,
-    })
-    stdout.on('data', (data: Buffer) => {
-      output += data.toString()
-    })
-
-    const done = runInteractive(session, harness, {
-      stdin: stdin as unknown as NodeJS.ReadStream,
-      stdout: stdout as unknown as NodeJS.WriteStream,
-      // Vitest's console cannot be patched.
-      patchConsole: false,
-    })
-    await wait(100)
-    // One chunk with a line break, the way a paste arrives.
-    stdin.write('hello\r')
-    await wait(300)
-    stdin.write('/exit\r')
-    await done
-
-    const plain = output.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '')
-    expect(plain).toContain('> hello')
-    expect(plain).toContain('Hi from the Ink UI')
-    await host.close()
-  })
-})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ae52fe1c33..f6002c67d5 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2628,13 +2628,6 @@ importers:
         version: 4.3.6
 
   packages/ai-harness-cli:
-    dependencies:
-      ink:
-        specifier: ^7.1.1
-        version: 7.1.1(@types/react@19.3.0)(react-devtools-core@6.1.5)(react@19.2.3)
-      react:
-        specifier: ^19.2.3
-        version: 19.2.3
     devDependencies:
       '@tanstack/ai':
         specifier: workspace:*
@@ -2654,9 +2647,6 @@ importers:
       '@tanstack/ai-sandbox':
         specifier: workspace:*
         version: link:../ai-sandbox
-      '@types/react':
-        specifier: ^19.2.7
-        version: 19.3.0
       '@vitest/coverage-v8':
         specifier: 4.1.10
         version: 4.1.10(vitest@4.1.11)
@@ -4046,10 +4036,6 @@ packages:
     peerDependencies:
       zod: ^3.25.0 || ^4.0.0
 
-  '@alcalzone/ansi-tokenize@0.3.1':
-    resolution: {integrity: sha512-cUD0PT0YX+rImRhfn7BfMRduP/tX/Zqt/N0dHlAyn2RlcJssCb5KsCJkhln61eh9vuJDkH8wKn3L8zJzzWXPFg==}
-    engines: {node: '>=18'}
-
   '@ampproject/remapping@2.3.0':
     resolution: {integrity: sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw==}
     engines: {node: '>=6.0.0'}
@@ -12114,10 +12100,6 @@ packages:
   asynckit@0.4.0:
     resolution: {integrity: sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==}
 
-  auto-bind@5.0.1:
-    resolution: {integrity: sha512-ooviqdwwgfIfNmDwo94wlshcdzfO64XV0Cg6oDsDYBJfITDz1EngD2z7DkbvCWn+XIMsIqW27sEVF6qcpJrRcg==}
-    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
-
   autoprefixer@10.4.22:
     resolution: {integrity: sha512-ARe0v/t9gO28Bznv6GgqARmVqcWOV3mfgUPn9becPHMiD3o9BwlRgaeccZnwTpZ7Zwqrm+c1sUSsMxIzQzc8Xg==}
     engines: {node: ^10 || ^12 || >=14}
@@ -12590,10 +12572,6 @@ packages:
     resolution: {integrity: sha512-/lzGpEWL/8PfI0BmBOPRwp0c/wFNX1RdUML3jK/RcSBA9T8mZDdQpqYBKtCFTOfQbwPqWEOpjqW+Fnayc0969g==}
     engines: {node: '>=10'}
 
-  cli-boxes@4.0.1:
-    resolution: {integrity: sha512-5IOn+jcCEHEraYolBPs/sT4BxYCe2nHg374OPiItB1O96KZFseS2gthU4twyYzeDcFew4DaUM/xwc5BQf08JJw==}
-    engines: {node: '>=18.20 <19 || >=20.10'}
-
   cli-cursor@2.1.0:
     resolution: {integrity: sha512-8lgKz8LmCRYZZQDpRyT2m5rKJ08TnU4tR9FFFW2rxpxR1FzWi4PQ/NfyODchAatHaUgnSPVcx/R5w6NuTBzFiw==}
     engines: {node: '>=4'}
@@ -12602,10 +12580,6 @@ packages:
     resolution: {integrity: sha512-I/zHAwsKf9FqGoXM4WWRACob9+SNukZTd94DWF57E4toouRulbCxcUh6RKUEOQlYTHJnzkPMySvPNaaSLNfLZw==}
     engines: {node: '>=8'}
 
-  cli-cursor@4.0.0:
-    resolution: {integrity: sha512-VGtlMu3x/4DOtIUwEkRezxUZ2lBacNJCHash0N0WeZDBS+7Ux1dm3XWAgWYxLJFMMdOeXMHXorshEFhbMSGelg==}
-    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
-
   cli-cursor@5.0.0:
     resolution: {integrity: sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==}
     engines: {node: '>=18'}
@@ -12622,10 +12596,6 @@ packages:
     resolution: {integrity: sha512-xRwvIOMGrfOAnM1JYtqQImuaNtDEv9v6oIYAs4LIHwTiKee8uwvIi363igssOC0O5U04i4AlENs79LQLu9tEMw==}
     engines: {node: '>=20'}
 
-  cli-truncate@6.1.1:
-    resolution: {integrity: sha512-06p9vyLahLa4zkGcgsGxU6iEkSOiuI4fhCH6Emhe2lPAcoUv73n72DnODsnHA+5wwXGnV0n9M9/qOQJSjYhFhw==}
-    engines: {node: '>=22'}
-
   cli-width@4.1.0:
     resolution: {integrity: sha512-ouuZd4/dm2Sw5Gmqy6bGyNNNe1qt9RpmxveLSO7KcgsTnU7RXfsw+/bukWGo1abgBiMAic068rclZsO4IWmmxQ==}
     engines: {node: '>= 12'}
@@ -12661,10 +12631,6 @@ packages:
   code-block-writer@12.0.0:
     resolution: {integrity: sha512-q4dMFMlXtKR3XNBHyMHt/3pwYNA69EDk00lloMOaaUMKPUXBw6lpXtbu3MMVG6/uOihGnRDOlkyqsONEUj60+w==}
 
-  code-excerpt@4.0.0:
-    resolution: {integrity: sha512-xxodCmBen3iy2i0WtAK8FlFNrRzjUqjRsMfho58xT/wvZU1YTM3fCnRjcy1gJPMepaRlgm/0e6w8SpWHpn3/cA==}
-    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
-
   color-convert@1.9.3:
     resolution: {integrity: sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==}
 
@@ -12795,10 +12761,6 @@ packages:
   convert-source-map@2.0.0:
     resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==}
 
-  convert-to-spaces@2.0.1:
-    resolution: {integrity: sha512-rcQ1bsQO9799wq24uE5AM2tAILy4gXGIK/njFWcVQkGNZ96edlpY+A7bjwvzjYvLDyzmG1MmMLZhpcsb+klNMQ==}
-    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
-
   cookie-es@1.2.2:
     resolution: {integrity: sha512-+W7VmiVINB+ywl1HGXJXmrqkOhpKrIiVZV6tQuV54ZyQC7MMuBt81Vc336GMLoHBq5hV/F9eXgt5Mnx0Rha5Fg==}
 
@@ -13523,9 +13485,6 @@ packages:
     resolution: {integrity: sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==}
     engines: {node: '>= 0.4'}
 
-  es-toolkit@1.52.0:
-    resolution: {integrity: sha512-XTNEJQh1tY1ZJVcf6ayP/2n4ZPyaHlW2FWs7xvw5ddPuhUVjLD3olQVQS7kf58JbAB48iL0uL/jerTrjtV3lDA==}
-
   esbuild-plugin-solid@0.5.0:
     resolution: {integrity: sha512-ITK6n+0ayGFeDVUZWNMxX+vLsasEN1ILrg4pISsNOQ+mq4ljlJJiuXotInd+HE0MzwTcA9wExT1yzDE2hsqPsg==}
     peerDependencies:
@@ -13563,10 +13522,6 @@ packages:
     resolution: {integrity: sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==}
     engines: {node: '>=0.8.0'}
 
-  escape-string-regexp@2.0.0:
-    resolution: {integrity: sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w==}
-    engines: {node: '>=8'}
-
   escape-string-regexp@4.0.0:
     resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==}
     engines: {node: '>=10'}
@@ -14517,10 +14472,6 @@ packages:
     resolution: {integrity: sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==}
     engines: {node: '>=0.8.19'}
 
-  indent-string@5.0.0:
-    resolution: {integrity: sha512-m6FAo/spmsW2Ab2fU35JTYwtOKa2yAwXSwgjSv1TJzh4Mh7mC3lzAOVLBprb72XsTrgkEIsl7YrFNAiDiRhIGg==}
-    engines: {node: '>=12'}
-
   inherits@2.0.4:
     resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
 
@@ -14530,19 +14481,6 @@ packages:
   injection-js@2.6.1:
     resolution: {integrity: sha512-dbR5bdhi7TWDoCye9cByZqeg/gAfamm8Vu3G1KZOTYkOif8WkuM8CD0oeDPtZYMzT5YH76JAFB7bkmyY9OJi2A==}
 
-  ink@7.1.1:
-    resolution: {integrity: sha512-Y43xxa1ZSPvpmfLHcN5o+OdP8Rf8ykkNJEuKYOUNZKT8wXVNLFTtEm1nSDMQkfBH+YANF4Xuu0hhZ4ejqAtN2w==}
-    engines: {node: '>=22'}
-    peerDependencies:
-      '@types/react': '>=19.2.0'
-      react: '>=19.2.0'
-      react-devtools-core: '>=6.1.2'
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-      react-devtools-core:
-        optional: true
-
   inline-style-parser@0.1.1:
     resolution: {integrity: sha512-7NXolsK4CAS5+xvdj5OMMbI962hU/wvwoxk+LWR9Ek9bVtyuuYScDN6eS0rUm6TxApFpw7CX1o4uJzcd4AyD3Q==}
 
@@ -14667,11 +14605,6 @@ packages:
     resolution: {integrity: sha512-S+OpgB5i7wzIue/YSE5hg0e5ZYfG3hhpNh9KGl6ayJ38p7ED6wxQLd1TV91xHpcTvw90KMJ9EwN3F/iNflHBVg==}
     engines: {node: '>=8'}
 
-  is-in-ci@2.0.0:
-    resolution: {integrity: sha512-cFeerHriAnhrQSbpAxL37W1wcJKUUX07HyLWZCW1URJT/ra3GyUTzBgUnh24TMVfNTV2Hij2HLxkPHFZfOZy5w==}
-    engines: {node: '>=20'}
-    hasBin: true
-
   is-in-ssh@1.0.0:
     resolution: {integrity: sha512-jYa6Q9rH90kR1vKB6NM7qqd1mge3Fx4Dhw5TVlK1MUBqhEOuCagrEHMevNuCcbECmXZ0ThXkRm+Ymr51HwEPAw==}
     engines: {node: '>=20'}
@@ -16375,10 +16308,6 @@ packages:
   partial-json@0.1.7:
     resolution: {integrity: sha512-Njv/59hHaokb/hRUjce3Hdv12wd60MtM9Z5Olmn+nehe0QDAsRtRbJPvJ0Z91TusF0SuZRIvnM+S4l6EIP8leA==}
 
-  patch-console@2.0.0:
-    resolution: {integrity: sha512-0YNdUceMdaQwoKce1gatDScmMo5pu/tfABfnzEqeG0gtTmd7mh/WcwgUjtAeOU7N8nFFlbQBnFK2gXW5fGvmMA==}
-    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
-
   path-browserify@1.0.1:
     resolution: {integrity: sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g==}
 
@@ -16815,12 +16744,6 @@ packages:
       '@types/react':
         optional: true
 
-  react-reconciler@0.33.0:
-    resolution: {integrity: sha512-KetWRytFv1epdpJc3J4G75I4WrplZE5jOL7Yq0p34+OVOKF4Se7WrdIdVC45XsSSmUTlht2FM/fM1FZb1mfQeA==}
-    engines: {node: '>=0.10.0'}
-    peerDependencies:
-      react: ^19.2.0
-
   react-refresh@0.14.2:
     resolution: {integrity: sha512-jCvmsr+1IUSMUyzOkRcvnVbX3ZYC6g9TDrDbFuFmRDq7PD4yaGbLKNQL6k2jnArV8hjYxh7hVhAZB6s9HDGpZA==}
     engines: {node: '>=0.10.0'}
@@ -17061,10 +16984,6 @@ packages:
     resolution: {integrity: sha512-l+sSefzHpj5qimhFSE5a8nufZYAM3sBSVMAPtYkmC+4EH2anSGaEMXSD0izRQbu9nfyQ9y5JrVmp7E8oZrUjvA==}
     engines: {node: '>=8'}
 
-  restore-cursor@4.0.0:
-    resolution: {integrity: sha512-I9fPXU9geO9bHOt9pHHOhOkYerIMsmVaWB0rA2AI9ERh/+x/i7MV5HKBNrg+ljO5eoPVgCcnFuRjJ9uH6I/3eg==}
-    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
-
   restore-cursor@5.1.0:
     resolution: {integrity: sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==}
     engines: {node: '>=18'}
@@ -17485,10 +17404,6 @@ packages:
     resolution: {integrity: sha512-stxByr12oeeOyY2BlviTNQlYV5xOj47GirPr4yA1hE9JCtxfQN0+tVbkxwCtYDQWhEKWFHsEK48ORg5jrouCAg==}
     engines: {node: '>=20'}
 
-  slice-ansi@9.0.1:
-    resolution: {integrity: sha512-aBY19bn/XA+hKOKX0qL7Z0UfdBsbQvc9hn993U8ALUjzxCvDcuZqLoRXjGJrUARWAlwMnsRVD9sw2AFNOYvalA==}
-    engines: {node: '>=22'}
-
   slugify@1.6.9:
     resolution: {integrity: sha512-vZ7rfeehZui7wQs438JXBckYLkIIdfHOXsaVEUMyS5fHo1483l1bMdo0EDSWYclY0yZKFOipDy4KHuKs6ssvdg==}
     engines: {node: '>=8.0.0'}
@@ -17586,10 +17501,6 @@ packages:
     resolution: {integrity: sha512-wPldCk3asibAjQ/kziWQQt1Wh3PgDFpC0XpwclzKcdT1vql6KeYxf5LIt4nlFkUeR8WuphYMKqUA56X4rjbfgQ==}
     engines: {node: '>=10.16.0'}
 
-  stack-utils@2.0.6:
-    resolution: {integrity: sha512-XlkWvfIm6RmsWtNJx+uqtKLS8eqFbxUg0ZzLXqY0caEy9l7hruX8IpiDnjsLavoBgqCCR71TqWO8MaXYheJ3RQ==}
-    engines: {node: '>=10'}
-
   stackback@0.0.2:
     resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}
 
@@ -17832,10 +17743,6 @@ packages:
     resolution: {integrity: sha512-un0FmiRUQNr5PJqy9kP7c40F5BOfpGlYTrxonDChEZB7pzZxRNp/bt+ymiy9/npwXya9KH99nJ/GXFIiUkYGFQ==}
     engines: {node: '>=8'}
 
-  terminal-size@4.0.1:
-    resolution: {integrity: sha512-avMLDQpUI9I5XFrklECw1ZEUPJhqzcwSWsyyI8blhRLT+8N1jLJWLWWYQpB2q2xthq8xDvjZPISVh53T/+CLYQ==}
-    engines: {node: '>=18'}
-
   terser@5.44.1:
     resolution: {integrity: sha512-t/R3R/n0MSwnnazuPpPNVO60LX0SKL45pyl9YlvxIdkH0Of7D5qM2EVe+yASRIlY5pZ73nclYJfNANGWPwFDZw==}
     engines: {node: '>=10'}
@@ -18077,10 +17984,6 @@ packages:
     resolution: {integrity: sha512-RAH822pAdBgcNMAfWnCBU3CFZcfZ/i1eZjwFU/dsLKumyuuP3niueg2UAukXYF0E2AAoc82ZSSf9J0WQBinzHA==}
     engines: {node: '>=12.20'}
 
-  type-fest@5.10.0:
-    resolution: {integrity: sha512-NoSdpq/WEiAg5sjmBkmV/hfxv6HJH4NqPNrqjtSO5CwRmpsDfaf4begxW34KdJykH/l1yHtwBWQkCRdoXO8mPA==}
-    engines: {node: '>=20'}
-
   type-fest@5.3.1:
     resolution: {integrity: sha512-VCn+LMHbd4t6sF3wfU/+HKT63C9OoyrSIf4b+vtWHpt2U7/4InZG467YDNMFMR70DdHjAdpPWmw2lzRdg0Xqqg==}
     engines: {node: '>=20'}
@@ -19001,10 +18904,6 @@ packages:
     resolution: {integrity: sha512-o0cyEG0e8GPzT4iGHphIOh0cJOV8fivsXxddQasHPHfoZf1ZexrfeA21w2NaEN1RHE+fXlfISmOE8R9N3u3Qig==}
     engines: {node: '>=12'}
 
-  widest-line@6.0.0:
-    resolution: {integrity: sha512-U89AsyEeAsyoF0zVJBkG9zBgekjgjK7yk9sje3F4IQpXBJ10TF6ByLlIfjMhcmHMJgHZI4KHt4rdNfktzxIAMA==}
-    engines: {node: '>=20'}
-
   word-wrap@1.2.5:
     resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==}
     engines: {node: '>=0.10.0'}
@@ -19029,10 +18928,6 @@ packages:
       '@cloudflare/workers-types':
         optional: true
 
-  wrap-ansi@10.0.2:
-    resolution: {integrity: sha512-6OLRNZqRntVGBm26ghZ5eZhCuWWyOkRCSn8XsOIuq5stpCE/tjLbdozd93naILZig0lmD8ANfRwnhn0DLeXGlg==}
-    engines: {node: '>=20'}
-
   wrap-ansi@6.2.0:
     resolution: {integrity: sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==}
     engines: {node: '>=8'}
@@ -19209,9 +19104,6 @@ packages:
     resolution: {integrity: sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug==}
     engines: {node: '>=18'}
 
-  yoga-layout@3.2.1:
-    resolution: {integrity: sha512-0LPOt3AxKqMdFBZA3HBAt/t/8vIKq7VaQYbuA8WxCgung+p9TVyKRYdpvCb80HcdTN2NkbIKbhNwKUfm3tQywQ==}
-
   youch-core@0.3.3:
     resolution: {integrity: sha512-ho7XuGjLaJ2hWHoK8yFnsUGy2Y5uDpqSTq1FkHLK4/oqKtyUU1AFbOOxY4IpC9f0fTLjwYbslUz0Po5BpD1wrA==}
 
@@ -19269,11 +19161,6 @@ snapshots:
     dependencies:
       zod: 4.3.6
 
-  '@alcalzone/ansi-tokenize@0.3.1':
-    dependencies:
-      ansi-styles: 6.2.3
-      is-fullwidth-code-point: 5.1.0
-
   '@ampproject/remapping@2.3.0':
     dependencies:
       '@jridgewell/gen-mapping': 0.3.13
@@ -30021,8 +29908,6 @@ snapshots:
 
   asynckit@0.4.0: {}
 
-  auto-bind@5.0.1: {}
-
   autoprefixer@10.4.22(postcss@8.5.26):
     dependencies:
       browserslist: 4.28.1
@@ -30688,8 +30573,6 @@ snapshots:
 
   cli-boxes@3.0.0: {}
 
-  cli-boxes@4.0.1: {}
-
   cli-cursor@2.1.0:
     dependencies:
       restore-cursor: 2.0.0
@@ -30698,10 +30581,6 @@ snapshots:
     dependencies:
       restore-cursor: 3.1.0
 
-  cli-cursor@4.0.0:
-    dependencies:
-      restore-cursor: 4.0.0
-
   cli-cursor@5.0.0:
     dependencies:
       restore-cursor: 5.1.0
@@ -30715,11 +30594,6 @@ snapshots:
       slice-ansi: 8.0.0
       string-width: 8.2.2
 
-  cli-truncate@6.1.1:
-    dependencies:
-      slice-ansi: 9.0.1
-      string-width: 8.2.2
-
   cli-width@4.1.0: {}
 
   clipboardy@4.0.0:
@@ -30754,10 +30628,6 @@ snapshots:
 
   code-block-writer@12.0.0: {}
 
-  code-excerpt@4.0.0:
-    dependencies:
-      convert-to-spaces: 2.0.1
-
   color-convert@1.9.3:
     dependencies:
       color-name: 1.1.3
@@ -30873,8 +30743,6 @@ snapshots:
 
   convert-source-map@2.0.0: {}
 
-  convert-to-spaces@2.0.1: {}
-
   cookie-es@1.2.2: {}
 
   cookie-es@1.2.3: {}
@@ -31509,8 +31377,6 @@ snapshots:
       has-tostringtag: 1.0.2
       hasown: 2.0.4
 
-  es-toolkit@1.52.0: {}
-
   esbuild-plugin-solid@0.5.0(esbuild@0.28.1)(solid-js@1.9.10):
     dependencies:
       '@babel/core': 7.29.7
@@ -31640,8 +31506,6 @@ snapshots:
 
   escape-string-regexp@1.0.5: {}
 
-  escape-string-regexp@2.0.0: {}
-
   escape-string-regexp@4.0.0: {}
 
   escape-string-regexp@5.0.0: {}
@@ -32851,8 +32715,6 @@ snapshots:
 
   imurmurhash@0.1.4: {}
 
-  indent-string@5.0.0: {}
-
   inherits@2.0.4: {}
 
   ini@1.3.8: {}
@@ -32861,41 +32723,6 @@ snapshots:
     dependencies:
       tslib: 2.8.1
 
-  ink@7.1.1(@types/react@19.3.0)(react-devtools-core@6.1.5)(react@19.2.3):
-    dependencies:
-      '@alcalzone/ansi-tokenize': 0.3.1
-      ansi-escapes: 7.3.0
-      ansi-styles: 6.2.3
-      auto-bind: 5.0.1
-      chalk: 5.6.2
-      cli-boxes: 4.0.1
-      cli-cursor: 4.0.0
-      cli-truncate: 6.1.1
-      code-excerpt: 4.0.0
-      es-toolkit: 1.52.0
-      indent-string: 5.0.0
-      is-in-ci: 2.0.0
-      patch-console: 2.0.0
-      react: 19.2.3
-      react-reconciler: 0.33.0(react@19.2.3)
-      scheduler: 0.27.0
-      signal-exit: 3.0.7
-      slice-ansi: 9.0.1
-      stack-utils: 2.0.6
-      string-width: 8.2.2
-      terminal-size: 4.0.1
-      type-fest: 5.10.0
-      widest-line: 6.0.0
-      wrap-ansi: 10.0.2
-      ws: 8.21.3
-      yoga-layout: 3.2.1
-    optionalDependencies:
-      '@types/react': 19.3.0
-      react-devtools-core: 6.1.5
-    transitivePeerDependencies:
-      - bufferutil
-      - utf-8-validate
-
   inline-style-parser@0.1.1: {}
 
   inline-style-parser@0.2.7: {}
@@ -33016,8 +32843,6 @@ snapshots:
     dependencies:
       html-tags: 3.3.1
 
-  is-in-ci@2.0.0: {}
-
   is-in-ssh@1.0.0: {}
 
   is-inside-container@1.0.0:
@@ -35680,8 +35505,6 @@ snapshots:
 
   partial-json@0.1.7: {}
 
-  patch-console@2.0.0: {}
-
   path-browserify@1.0.1: {}
 
   path-exists@3.0.0: {}
@@ -36416,11 +36239,6 @@ snapshots:
       - supports-color
       - utf-8-validate
 
-  react-reconciler@0.33.0(react@19.2.3):
-    dependencies:
-      react: 19.2.3
-      scheduler: 0.27.0
-
   react-refresh@0.14.2: {}
 
   react-refresh@0.17.0: {}
@@ -36776,11 +36594,6 @@ snapshots:
       onetime: 5.1.2
       signal-exit: 3.0.7
 
-  restore-cursor@4.0.0:
-    dependencies:
-      onetime: 5.1.2
-      signal-exit: 3.0.7
-
   restore-cursor@5.1.0:
     dependencies:
       onetime: 7.0.0
@@ -37427,11 +37240,6 @@ snapshots:
       ansi-styles: 6.2.3
       is-fullwidth-code-point: 5.1.0
 
-  slice-ansi@9.0.1:
-    dependencies:
-      ansi-styles: 6.2.3
-      is-fullwidth-code-point: 5.1.0
-
   slugify@1.6.9: {}
 
   smart-buffer@4.2.0: {}
@@ -37528,10 +37336,6 @@ snapshots:
       cpu-features: 0.0.10
       nan: 2.27.0
 
-  stack-utils@2.0.6:
-    dependencies:
-      escape-string-regexp: 2.0.0
-
   stackback@0.0.2: {}
 
   stackframe@1.3.4: {}
@@ -37827,8 +37631,6 @@ snapshots:
       ansi-escapes: 4.3.2
       supports-hyperlinks: 2.3.0
 
-  terminal-size@4.0.1: {}
-
   terser@5.44.1:
     dependencies:
       '@jridgewell/source-map': 0.3.11
@@ -38104,10 +37906,6 @@ snapshots:
 
   type-fest@2.19.0: {}
 
-  type-fest@5.10.0:
-    dependencies:
-      tagged-tag: 1.0.0
-
   type-fest@5.3.1:
     dependencies:
       tagged-tag: 1.0.0
@@ -39160,10 +38958,6 @@ snapshots:
     dependencies:
       string-width: 5.1.2
 
-  widest-line@6.0.0:
-    dependencies:
-      string-width: 8.2.2
-
   word-wrap@1.2.5: {}
 
   workerd@1.20260609.1:
@@ -39199,11 +38993,6 @@ snapshots:
       - bufferutil
       - utf-8-validate
 
-  wrap-ansi@10.0.2:
-    dependencies:
-      ansi-styles: 6.2.3
-      string-width: 8.2.2
-
   wrap-ansi@6.2.0:
     dependencies:
       ansi-styles: 4.3.0
@@ -39334,8 +39123,6 @@ snapshots:
 
   yoctocolors@2.1.2: {}
 
-  yoga-layout@3.2.1: {}
-
   youch-core@0.3.3:
     dependencies:
       '@poppinss/exception': 1.2.3

From 9d7d38305ad6ad4d33337c21303ebf416fc08677 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 14:30:05 +0200
Subject: [PATCH 043/286] refactor(ai-harness-cli): line mode prints from the
 session view; remove the old event fold

In a terminal, line mode opens sign-in links in the browser.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-harness-cli/src/args.ts           |   3 +-
 packages/ai-harness-cli/src/commands.ts       |   6 +-
 packages/ai-harness-cli/src/index.ts          |   4 +-
 packages/ai-harness-cli/src/lines.ts          |  73 +++----
 packages/ai-harness-cli/src/printer.ts        |  98 +++++++++
 packages/ai-harness-cli/src/session-view.ts   | 179 ++--------------
 .../ai-harness-cli/tests/child-view.test.ts   |  94 +--------
 .../ai-harness-cli/tests/commands.test.ts     |  72 +------
 packages/ai-harness-cli/tests/printer.test.ts | 199 ++++++++++++++++++
 packages/ai-harness-cli/tsconfig.json         |   3 +-
 10 files changed, 350 insertions(+), 381 deletions(-)
 create mode 100644 packages/ai-harness-cli/src/printer.ts
 create mode 100644 packages/ai-harness-cli/tests/printer.test.ts

diff --git a/packages/ai-harness-cli/src/args.ts b/packages/ai-harness-cli/src/args.ts
index 9d49cf37c7..b62a8c5caa 100644
--- a/packages/ai-harness-cli/src/args.ts
+++ b/packages/ai-harness-cli/src/args.ts
@@ -15,7 +15,8 @@ export interface CliArgs {
 
 export const USAGE = `Usage: <your-cli> [options]
 
-With no options, starts the interactive UI.
+With no options in a terminal, starts the UI of this CLI, if it has one.
+Otherwise, and for piped input, reads one message or command per line.
 
 Options:
   -p, --print <prompt>   Run one prompt, print the answer, and exit
diff --git a/packages/ai-harness-cli/src/commands.ts b/packages/ai-harness-cli/src/commands.ts
index 3f5ef06fd7..e78eb69852 100644
--- a/packages/ai-harness-cli/src/commands.ts
+++ b/packages/ai-harness-cli/src/commands.ts
@@ -83,7 +83,7 @@ export type LineResult =
 
 /**
  * Handle one line of user input: a slash command, a steer while a turn runs,
- * or a new prompt. Shared by the interactive UI and the line mode.
+ * or a new prompt. Used by the line mode, and by any UI that calls it.
  */
 export async function handleLine(
   session: HarnessSession,
@@ -136,8 +136,8 @@ export async function handleLine(
               ? 'This harness has no settings.'
               : entries
                   .map(
-                    ([name, entry]) =>
-                      `  ${name} = ${JSON.stringify(entry.value)}`,
+                    ([option, entry]) =>
+                      `  ${option} = ${JSON.stringify(entry.value)}`,
                   )
                   .join('\n'),
         }
diff --git a/packages/ai-harness-cli/src/index.ts b/packages/ai-harness-cli/src/index.ts
index 92dfde9bb6..5eef2336a2 100644
--- a/packages/ai-harness-cli/src/index.ts
+++ b/packages/ai-harness-cli/src/index.ts
@@ -139,7 +139,9 @@ export async function runCli(
         view.dispose()
       }
     } else {
-      await runLines(session, stdin, stdout)
+      await runLines(session, stdin, stdout, {
+        openSignIns: Boolean(stdin.isTTY),
+      })
     }
     return EXIT.ok
   } catch (error) {
diff --git a/packages/ai-harness-cli/src/lines.ts b/packages/ai-harness-cli/src/lines.ts
index 750d98a4cb..a245db0c0b 100644
--- a/packages/ai-harness-cli/src/lines.ts
+++ b/packages/ai-harness-cli/src/lines.ts
@@ -1,13 +1,9 @@
 import { createInterface } from 'node:readline'
+import { createSessionView } from '@tanstack/ai-harness/view'
 import { handleLine } from './commands'
-import {
-  applyEvent,
-  approvalQuestion,
-  resolveAll,
-  waitIdle,
-} from './session-view'
+import { createPrinter } from './printer'
+import { approvalQuestion, openUrl, resolveAll, waitIdle } from './session-view'
 import type { HarnessSession } from '@tanstack/ai-harness'
-import type { ViewEntry } from './session-view'
 
 interface Output {
   write: (text: string) => unknown
@@ -17,50 +13,27 @@ interface Output {
  * The line mode, for piped input: one message or command per line. Each
  * line waits for the turn it started. When a turn stops for approval, the
  * next line answers it (`y` approves, anything else rejects).
+ *
+ * `openSignIns`: open sign-in links in the browser (for an interactive terminal).
  */
 export async function runLines(
   session: HarnessSession,
   input: NodeJS.ReadableStream,
   stdout: Output,
-): Promise<void> {
-  const reader = new AbortController()
-  let entries: Array<ViewEntry> = []
-  // True while streamed text has no line break at its end yet.
-  let midLine = false
-  const line = (text: string) => {
-    if (midLine) stdout.write('\n')
-    midLine = false
-    stdout.write(`${text}\n`)
-  }
-  const printing = (async () => {
-    for await (const entry of session.events({
-      from: session.snapshot().cursor,
-      signal: reader.signal,
-    })) {
-      const next = applyEvent(entries, entry)
-      const last = next.at(-1)
-      if (next === entries || !last) continue
-      // Print the growth of the last assistant entry, or each new entry.
-      const previous = entries.at(-1)
-      if (
-        last.kind === 'assistant' &&
-        previous?.kind === 'assistant' &&
-        previous.operationId === last.operationId
-      ) {
-        stdout.write(last.text.slice(previous.text.length))
-        midLine = true
-      } else if (last.kind === 'assistant') {
-        if (midLine) stdout.write('\n')
-        stdout.write(last.text)
-        midLine = true
-      } else if (next.length > entries.length) {
-        // Only new entries print. An earlier entry that changed (a child's
-        // answer building up) prints later, in its finish line.
-        line(`[${last.text}]`)
-      }
-      entries = next
-    }
-  })()
+  options: { openSignIns?: boolean } = {},
+) {
+  const view = createSessionView(session)
+  const printer = createPrinter((text) => stdout.write(text))
+  await view.ready
+  // Line mode prints only what happens from now on.
+  printer.mark(view.store.get())
+  const printing = view.store.subscribe((state) => printer.print(state))
+  const stopOpening = options.openSignIns
+    ? view.on('signIn', (signIn) => {
+        if (signIn.url) openUrl(signIn.url)
+      })
+    : () => {}
+  const line = printer.line
 
   const lines = createInterface({ input, crlfDelay: Infinity })
   const pendingLater: Array<Promise<void>> = []
@@ -89,7 +62,9 @@ export async function runLines(
   lines.close()
   await Promise.allSettled(pendingLater)
   await waitIdle(session)
-  reader.abort()
-  await printing
-  if (midLine) stdout.write('\n')
+  stopOpening()
+  printing.unsubscribe()
+  printer.print(view.store.get())
+  view.dispose()
+  printer.end()
 }
diff --git a/packages/ai-harness-cli/src/printer.ts b/packages/ai-harness-cli/src/printer.ts
new file mode 100644
index 0000000000..8b4c892721
--- /dev/null
+++ b/packages/ai-harness-cli/src/printer.ts
@@ -0,0 +1,98 @@
+import { shortAnswer, signInText } from './session-view'
+import type { AgentPart, SessionViewState } from '@tanstack/ai-harness/view'
+
+/**
+ * Prints a session view as lines: streamed text as it grows, and one
+ * bracketed line per tool call, child agent, notice, question, and sign-in.
+ * Notices that line mode prints itself (command results, rejected inputs,
+ * and UI notes) are skipped.
+ */
+export function createPrinter(write: (text: string) => unknown) {
+  const done = new Set<string>()
+  const written = new Map<string, number>()
+  // True while streamed text has no line break at its end yet.
+  let midLine = false
+  let lastStream = ''
+  let marking = false
+
+  const line = (text: string) => {
+    if (marking) return
+    if (midLine) write('\n')
+    midLine = false
+    write(`${text}\n`)
+  }
+  const once = (key: string, text: string) => {
+    if (done.has(key)) return
+    done.add(key)
+    line(`[${text}]`)
+  }
+  const stream = (key: string, text: string) => {
+    const before = written.get(key) ?? 0
+    if (text.length <= before) return
+    written.set(key, text.length)
+    if (marking) return
+    if (midLine && key !== lastStream) write('\n')
+    write(text.slice(before))
+    midLine = true
+    lastStream = key
+  }
+  const agent = (key: string, part: AgentPart) => {
+    once(`${key}:start`, `agent ${part.name} started`)
+    part.parts.forEach((inner, index) => {
+      if (inner.type === 'tool-call')
+        once(`${key}:${index}`, `${part.name}: tool ${inner.name}`)
+    })
+    const answer = shortAnswer(
+      part.parts
+        .map((inner) => (inner.type === 'text' ? inner.text : ''))
+        .join(''),
+    )
+    if (part.status === 'done')
+      once(
+        `${key}:end`,
+        answer
+          ? `agent ${part.name} finished: ${answer}`
+          : `agent ${part.name} finished`,
+      )
+    if (part.status === 'failed')
+      once(`${key}:end`, `agent ${part.name} failed: ${part.error ?? ''}`)
+  }
+  const print = (state: SessionViewState) => {
+    for (const message of state.messages) {
+      if (message.role === 'notice') {
+        if (message.kind === 'error' || message.kind === 'info')
+          once(message.id, message.text)
+        continue
+      }
+      if (message.role !== 'assistant') continue
+      message.parts.forEach((part, index) => {
+        const key = `${message.id}:${index}`
+        if (part.type === 'text') stream(key, part.text)
+        if (part.type === 'tool-call') once(key, `tool ${part.name}`)
+        if (part.type === 'agent') agent(key, part)
+      })
+    }
+    for (const question of state.questions)
+      once(`question:${question.id}`, `? ${question.message}`)
+    for (const signIn of state.signIns)
+      once(
+        `sign-in:${signIn.connector}:${signIn.url ?? ''}`,
+        signInText(signIn),
+      )
+  }
+
+  return {
+    print,
+    /** Mark everything in `state` as printed, for history. */
+    mark: (state: SessionViewState) => {
+      marking = true
+      print(state)
+      marking = false
+    },
+    line,
+    end: () => {
+      if (midLine) write('\n')
+      midLine = false
+    },
+  }
+}
diff --git a/packages/ai-harness-cli/src/session-view.ts b/packages/ai-harness-cli/src/session-view.ts
index d1f904a310..29dea42704 100644
--- a/packages/ai-harness-cli/src/session-view.ts
+++ b/packages/ai-harness-cli/src/session-view.ts
@@ -1,97 +1,6 @@
-import { EventType } from '@tanstack/ai'
-import { HARNESS_EVENTS } from '@tanstack/ai-harness'
 import type { Interrupt, RunAgentResumeItem } from '@tanstack/ai'
-import type { HarnessSession, SessionEvent } from '@tanstack/ai-harness'
-
-/** One line in the transcript view. */
-export type ViewEntry =
-  | { kind: 'user'; text: string }
-  | { kind: 'assistant'; operationId: string; text: string }
-  | { kind: 'tool'; text: string }
-  | { kind: 'notice'; text: string }
-  /** A child agent. `answer` collects its text for the finish line. */
-  | {
-      kind: 'agent'
-      subagentRunId: string
-      name: string
-      text: string
-      answer: string
-    }
-
-/**
- * Fold one session event into the view entries. Returns the new list, or the
- * same list when the event changes nothing on screen.
- */
-export function applyEvent(
-  entries: Array<ViewEntry>,
-  entry: SessionEvent,
-): Array<ViewEntry> {
-  const { event, operationId } = entry
-  if ('subagentRunId' in event && event.subagentRunId) {
-    return applyChildEvent(entries, event.subagentRunId, event)
-  }
-  if (event.type === EventType.TEXT_MESSAGE_CONTENT) {
-    const last = entries.at(-1)
-    if (last?.kind === 'assistant' && last.operationId === operationId) {
-      return [
-        ...entries.slice(0, -1),
-        { ...last, text: last.text + event.delta },
-      ]
-    }
-    return [...entries, { kind: 'assistant', operationId, text: event.delta }]
-  }
-  if (event.type === EventType.TOOL_CALL_START) {
-    return [...entries, { kind: 'tool', text: `tool ${event.toolCallName}` }]
-  }
-  if (event.type === EventType.RUN_ERROR) {
-    return [...entries, { kind: 'notice', text: `Error: ${event.message}` }]
-  }
-  if (
-    event.type === EventType.CUSTOM &&
-    event.name === HARNESS_EVENTS.operationResumed
-  ) {
-    return [
-      ...entries,
-      { kind: 'notice', text: 'Resumed a turn that a crash stopped.' },
-    ]
-  }
-  if (
-    event.type === EventType.CUSTOM &&
-    event.name === HARNESS_EVENTS.question
-  ) {
-    const value = event.value as { message?: unknown }
-    return [
-      ...entries,
-      { kind: 'notice', text: `? ${String(value.message ?? '')}` },
-    ]
-  }
-  if (
-    event.type === EventType.CUSTOM &&
-    event.name === HARNESS_EVENTS.authRequired
-  ) {
-    const value = event.value as {
-      connector?: unknown
-      url?: unknown
-      userCode?: unknown
-    }
-    const code =
-      typeof value.userCode === 'string'
-        ? ` and enter the code ${value.userCode}`
-        : ''
-    const where =
-      typeof value.url === 'string'
-        ? ` Open ${value.url}${code}.`
-        : ` Run /connect ${String(value.connector)}.`
-    return [
-      ...entries,
-      {
-        kind: 'notice',
-        text: `Sign in to ${String(value.connector)}.${where}`,
-      },
-    ]
-  }
-  return entries
-}
+import type { HarnessSession } from '@tanstack/ai-harness'
+import type { SignIn } from '@tanstack/ai-harness/view'
 
 /** Answer every open interrupt of the last turn with one decision. */
 export function resolveAll(
@@ -108,7 +17,7 @@ export function resolveAll(
 }
 
 /** Open an http(s) URL in the default browser. No shell is involved. */
-export function openUrl(url: string): void {
+export function openUrl(url: string) {
   if (!/^https?:\/\//.test(url)) return
   void import('node:child_process').then(({ spawn }) => {
     const [command, args] =
@@ -127,7 +36,7 @@ export function openUrl(url: string): void {
 }
 
 /** A short question for the open interrupts. */
-export function approvalQuestion(interrupts: ReadonlyArray<Interrupt>): string {
+export function approvalQuestion(interrupts: ReadonlyArray<Interrupt>) {
   const names = interrupts.map(
     (interrupt) => interrupt.message ?? interrupt.toolCallId ?? interrupt.id,
   )
@@ -138,87 +47,31 @@ export function approvalQuestion(interrupts: ReadonlyArray<Interrupt>): string {
  * Resolves when no chat turn runs or waits in the queue, or when the
  * session waits for an answer to a question.
  */
-export async function waitIdle(session: HarnessSession): Promise<void> {
+export async function waitIdle(session: HarnessSession) {
   while (true) {
     const snapshot = session.snapshot()
     if (snapshot.pendingQuestions.length > 0) return
     const chatActive = snapshot.activeOperations.some(
       (operation) => operation.kind === 'chat',
     )
-    if (
-      snapshot.status !== 'running' &&
-      !chatActive &&
-      snapshot.queuedTurns === 0
-    )
-      return
+    const isIdle =
+      snapshot.status !== 'running' && !chatActive && snapshot.queuedTurns === 0
+    if (isIdle) return
     await new Promise((resolve) => setTimeout(resolve, 20))
   }
 }
 
 /** The first 200 characters of a child's answer, on one line. */
-function shortAnswer(text: string): string {
+export function shortAnswer(text: string) {
   const line = text.replace(/\s+/g, ' ').trim()
   return line.length > 200 ? `${line.slice(0, 200)}...` : line
 }
 
-/**
- * Child agent work: its start, its tool calls, and a finish line with the
- * start of its answer. The answer builds up on the agent entry, which is not
- * the last entry, so line mode does not print it until the child finishes.
- */
-function applyChildEvent(
-  entries: Array<ViewEntry>,
-  subagentRunId: string,
-  event: SessionEvent['event'],
-): Array<ViewEntry> {
-  const index = entries.findLastIndex(
-    (item) => item.kind === 'agent' && item.subagentRunId === subagentRunId,
-  )
-  const agent = entries[index]
-  const found = agent?.kind === 'agent' ? agent : undefined
-  const name = found?.name ?? 'agent'
-  if (event.type === EventType.SUBAGENT_STARTED) {
-    const started = event.name ?? 'agent'
-    return [
-      ...entries,
-      {
-        kind: 'agent',
-        subagentRunId,
-        name: started,
-        text: `agent ${started} started`,
-        answer: '',
-      },
-    ]
-  }
-  if (event.type === EventType.TEXT_MESSAGE_CONTENT) {
-    if (!found) return entries
-    const next = [...entries]
-    next[index] = { ...found, answer: found.answer + event.delta }
-    return next
-  }
-  if (event.type === EventType.TOOL_CALL_START) {
-    return [
-      ...entries,
-      { kind: 'tool', text: `${name}: tool ${event.toolCallName}` },
-    ]
-  }
-  if (event.type === EventType.SUBAGENT_FINISHED) {
-    const answer = shortAnswer(found?.answer ?? '')
-    return [
-      ...entries,
-      {
-        kind: 'tool',
-        text: answer
-          ? `agent ${name} finished: ${answer}`
-          : `agent ${name} finished`,
-      },
-    ]
-  }
-  if (event.type === EventType.SUBAGENT_ERROR) {
-    return [
-      ...entries,
-      { kind: 'notice', text: `agent ${name} failed: ${event.message}` },
-    ]
-  }
-  return entries
+/** The sign-in line for a connector: its link and code, or the command. */
+export function signInText(signIn: SignIn) {
+  const code = signIn.userCode ? ` and enter the code ${signIn.userCode}` : ''
+  const where = signIn.url
+    ? ` Open ${signIn.url}${code}.`
+    : ` Run /connect ${signIn.connector}.`
+  return `Sign in to ${signIn.connector}.${where}`
 }
diff --git a/packages/ai-harness-cli/tests/child-view.test.ts b/packages/ai-harness-cli/tests/child-view.test.ts
index e3a8cd0d14..046e355427 100644
--- a/packages/ai-harness-cli/tests/child-view.test.ts
+++ b/packages/ai-harness-cli/tests/child-view.test.ts
@@ -5,101 +5,9 @@ import { EventType, defineAgent } from '@tanstack/ai'
 import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { runLines } from '../src/lines'
-import { applyEvent } from '../src/session-view'
 import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
-import type { SessionEvent } from '@tanstack/ai-harness'
-import type { ViewEntry } from '../src/session-view'
-
-const at = (event: StreamChunk): SessionEvent => ({
-  cursor: '1',
-  operationId: 'op',
-  event,
-})
-const child = (event: Record<string, unknown>): StreamChunk =>
-  ({ subagentRunId: 'child-1', timestamp: 1, ...event }) as StreamChunk
-
-function fold(events: Array<StreamChunk>): Array<ViewEntry> {
-  return events.reduce(
-    (entries, event) => applyEvent(entries, at(event)),
-    [] as Array<ViewEntry>,
-  )
-}
-
-describe('child agent entries', () => {
-  it('shows the start, tool calls, and a finish line with the answer', () => {
-    const entries = fold([
-      child({ type: EventType.SUBAGENT_STARTED, name: 'claude_code' }),
-      child({
-        type: EventType.TEXT_MESSAGE_CONTENT,
-        messageId: 'm',
-        delta: 'Added a\n',
-      }),
-      child({
-        type: EventType.TOOL_CALL_START,
-        toolCallId: 't',
-        toolCallName: 'Edit',
-      }),
-      child({
-        type: EventType.TEXT_MESSAGE_CONTENT,
-        messageId: 'm',
-        delta: '  test.',
-      }),
-      child({ type: EventType.SUBAGENT_FINISHED }),
-    ])
-    expect(entries.map((entry) => entry.text)).toEqual([
-      'agent claude_code started',
-      'claude_code: tool Edit',
-      'agent claude_code finished: Added a test.',
-    ])
-    expect(entries[0]).toMatchObject({
-      kind: 'agent',
-      answer: 'Added a\n  test.',
-    })
-  })
-
-  it('shortens long answers, reports errors, and names unknown children "agent"', () => {
-    const long = 'word '.repeat(60)
-    const finished = fold([
-      child({ type: EventType.SUBAGENT_STARTED, name: 'codex' }),
-      child({
-        type: EventType.TEXT_MESSAGE_CONTENT,
-        messageId: 'm',
-        delta: long,
-      }),
-      child({ type: EventType.SUBAGENT_FINISHED }),
-    ])
-    const last = finished.at(-1)?.text ?? ''
-    expect(last.startsWith('agent codex finished: word word')).toBe(true)
-    expect(last.endsWith('...')).toBe(true)
-
-    expect(
-      fold([
-        child({ type: EventType.SUBAGENT_STARTED }),
-        child({ type: EventType.SUBAGENT_FINISHED }),
-      ]).map((entry) => entry.text),
-    ).toEqual(['agent agent started', 'agent agent finished'])
-
-    const orphan = fold([
-      child({
-        type: EventType.TEXT_MESSAGE_CONTENT,
-        messageId: 'm',
-        delta: 'lost',
-      }),
-      child({
-        type: EventType.TOOL_CALL_START,
-        toolCallId: 't',
-        toolCallName: 'Read',
-      }),
-      child({ type: EventType.SUBAGENT_ERROR, message: 'crashed' }),
-      child({ type: EventType.STEP_STARTED, stepName: 's' }),
-    ])
-    expect(orphan.map((entry) => entry.text)).toEqual([
-      'agent: tool Read',
-      'agent agent failed: crashed',
-    ])
-  })
-})
 
+// `~types` holds types only. Its values are never read, so they are casts.
 const TYPES = {
   providerOptions: {} as Record<string, unknown>,
   inputModalities: ['text'] as readonly ['text'],
diff --git a/packages/ai-harness-cli/tests/commands.test.ts b/packages/ai-harness-cli/tests/commands.test.ts
index aa6fc6857d..e1d9c650cf 100644
--- a/packages/ai-harness-cli/tests/commands.test.ts
+++ b/packages/ai-harness-cli/tests/commands.test.ts
@@ -2,7 +2,6 @@ import { describe, expect, it, vi } from 'vitest'
 import { z } from 'zod'
 import { EventType, defineAgent } from '@tanstack/ai'
 import {
-  HARNESS_EVENTS,
   configOption,
   createHarnessHost,
   defineCommand,
@@ -11,9 +10,7 @@ import {
 } from '@tanstack/ai-harness'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { HELP_TEXT, handleLine, parseAnswer } from '../src/commands'
-import { applyEvent } from '../src/session-view'
 import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
-import type { SessionEvent } from '@tanstack/ai-harness'
 
 /** A model that answers `echo: <text>`, or waits for cancel on "wait". */
 function model(): AnyTextAdapter {
@@ -21,6 +18,7 @@ function model(): AnyTextAdapter {
     kind: 'text',
     name: 'mock',
     model: 'test-model',
+    // `~types` holds types only. Its values are never read, so they are casts.
     '~types': {
       providerOptions: {} as Record<string, unknown>,
       inputModalities: ['text'] as readonly ['text'],
@@ -36,7 +34,7 @@ function model(): AnyTextAdapter {
       systemPromptMetadata: undefined as never,
     },
     structuredOutput: async () => ({ data: {}, rawText: '{}' }),
-    chatStream: (options: any) =>
+    chatStream: (options) =>
       (async function* (): AsyncGenerator<StreamChunk> {
         const said = String(options.messages.at(-1)?.content ?? '')
         const now = Date.now()
@@ -47,7 +45,7 @@ function model(): AnyTextAdapter {
           timestamp: now,
         }
         if (said === 'wait') {
-          const signal: AbortSignal | undefined =
+          const signal =
             options.abortController?.signal ?? options.request?.signal
           await new Promise<void>((resolve) => {
             if (!signal || signal.aborted) return resolve()
@@ -245,67 +243,3 @@ describe('parseAnswer', () => {
     expect(parseAnswer('', undefined)).toBeUndefined()
   })
 })
-
-describe('applyEvent', () => {
-  const entry = (event: StreamChunk, operationId = 'op'): SessionEvent => ({
-    cursor: '1',
-    operationId,
-    event,
-  })
-  const custom = (name: string, value: unknown): StreamChunk => ({
-    type: EventType.CUSTOM,
-    name,
-    value,
-    timestamp: 1,
-  })
-
-  it('shows questions, sign-ins, resumes, errors, and child agents', () => {
-    const events: Array<StreamChunk> = [
-      custom(HARNESS_EVENTS.question, { message: 'Sure?' }),
-      custom(HARNESS_EVENTS.authRequired, {
-        connector: 'gh',
-        url: 'https://gh.example/device',
-        userCode: 'ABCD',
-      }),
-      custom(HARNESS_EVENTS.authRequired, { connector: 'svc' }),
-      custom(HARNESS_EVENTS.operationResumed, {}),
-      { type: EventType.RUN_ERROR, message: 'model down', timestamp: 1 },
-      {
-        type: EventType.SUBAGENT_STARTED,
-        subagentRunId: 'child',
-        name: 'painter',
-        timestamp: 1,
-      } as StreamChunk,
-    ]
-    const shown = events.reduce(
-      (entries, event) => applyEvent(entries, entry(event)),
-      [] as ReturnType<typeof applyEvent>,
-    )
-    expect(shown.map((item) => item.text)).toEqual([
-      '? Sure?',
-      'Sign in to gh. Open https://gh.example/device and enter the code ABCD.',
-      'Sign in to svc. Run /connect svc.',
-      'Resumed a turn that a crash stopped.',
-      'Error: model down',
-      'agent painter started',
-    ])
-    // Child text builds up on the agent entry without adding a line, and an
-    // unknown custom event changes nothing.
-    const withText = applyEvent(
-      shown,
-      entry({
-        type: EventType.TEXT_MESSAGE_CONTENT,
-        messageId: 'x',
-        delta: 'child text',
-        subagentRunId: 'child',
-        timestamp: 1,
-      } as StreamChunk),
-    )
-    expect(withText).toHaveLength(shown.length)
-    expect(withText.at(-1)).toMatchObject({
-      kind: 'agent',
-      answer: 'child text',
-    })
-    expect(applyEvent(shown, entry(custom('other.event', {})))).toBe(shown)
-  })
-})
diff --git a/packages/ai-harness-cli/tests/printer.test.ts b/packages/ai-harness-cli/tests/printer.test.ts
new file mode 100644
index 0000000000..084c825610
--- /dev/null
+++ b/packages/ai-harness-cli/tests/printer.test.ts
@@ -0,0 +1,199 @@
+import { describe, expect, it } from 'vitest'
+import { createPrinter } from '../src/printer'
+import type { SessionViewState } from '@tanstack/ai-harness/view'
+
+const base: SessionViewState = {
+  threadId: 't',
+  status: 'idle',
+  connection: 'open',
+  messages: [],
+  approvals: [],
+  questions: [],
+  signIns: [],
+  agents: [],
+  queuedTurns: 0,
+  commands: [],
+  config: [],
+  tools: [],
+  plugins: {},
+}
+
+describe('line printer', () => {
+  it('streams text growth, prints each item once, and breaks lines between turns', () => {
+    let out = ''
+    const printer = createPrinter((text) => (out += text))
+    printer.print({
+      ...base,
+      messages: [
+        {
+          id: 'turn-1',
+          role: 'assistant',
+          parts: [{ type: 'text', text: 'Hel' }],
+        },
+      ],
+    })
+    printer.print({
+      ...base,
+      messages: [
+        {
+          id: 'turn-1',
+          role: 'assistant',
+          parts: [
+            { type: 'text', text: 'Hello' },
+            {
+              type: 'tool-call',
+              id: 'c',
+              name: 'read',
+              argsText: '{}',
+              args: {},
+              status: 'done',
+            },
+            {
+              type: 'agent',
+              id: 'a',
+              name: 'helper',
+              status: 'done',
+              parts: [
+                { type: 'text', text: 'child says hi' },
+                {
+                  type: 'tool-call',
+                  id: 'd',
+                  name: 'Edit',
+                  argsText: '',
+                  args: undefined,
+                  status: 'done',
+                },
+              ],
+            },
+          ],
+        },
+        { id: 'notice-1', role: 'notice', kind: 'error', text: 'Error: boom' },
+        {
+          id: 'notice-2',
+          role: 'notice',
+          kind: 'command',
+          text: 'printed by handleLine',
+        },
+        {
+          id: 'turn-2',
+          role: 'assistant',
+          parts: [{ type: 'text', text: 'Second.' }],
+        },
+      ],
+      questions: [
+        {
+          id: 'q',
+          message: 'Really?',
+          answer: async () => ({ inputId: 'i', status: 'accepted' }),
+        },
+      ],
+      signIns: [{ connector: 'notion', url: 'https://x' }],
+    })
+    printer.end()
+
+    expect(out).toBe(
+      [
+        'Hello',
+        '[tool read]',
+        '[agent helper started]',
+        '[helper: tool Edit]',
+        '[agent helper finished: child says hi]',
+        '[Error: boom]',
+        'Second.',
+        '[? Really?]',
+        '[Sign in to notion. Open https://x.]',
+        '',
+      ].join('\n'),
+    )
+  })
+
+  it('cuts long child answers, reports failed children, and prints each kind of sign-in', () => {
+    let out = ''
+    const printer = createPrinter((text) => (out += text))
+    printer.print({
+      ...base,
+      messages: [
+        { id: 'user-1', role: 'user', text: 'hi' },
+        {
+          id: 'turn-1',
+          role: 'assistant',
+          parts: [
+            { type: 'reasoning', text: 'thinking' },
+            {
+              type: 'agent',
+              id: 'a',
+              name: 'codex',
+              status: 'done',
+              parts: [{ type: 'text', text: 'word '.repeat(60) }],
+            },
+            {
+              type: 'agent',
+              id: 'b',
+              name: 'painter',
+              status: 'failed',
+              error: 'crashed',
+              parts: [],
+            },
+            {
+              type: 'agent',
+              id: 'c',
+              name: 'quiet',
+              status: 'done',
+              parts: [],
+            },
+          ],
+        },
+        {
+          id: 'notice-1',
+          role: 'notice',
+          kind: 'info',
+          text: 'Resumed a turn that a crash stopped.',
+        },
+        {
+          id: 'notice-2',
+          role: 'notice',
+          kind: 'rejected',
+          text: 'Not accepted: busy',
+        },
+      ],
+      signIns: [
+        { connector: 'gh', url: 'https://gh.example/device', userCode: 'ABCD' },
+        { connector: 'svc' },
+      ],
+    })
+
+    expect(out).toBe(
+      [
+        '[agent codex started]',
+        `[agent codex finished: ${'word '.repeat(40)}...]`,
+        '[agent painter started]',
+        '[agent painter failed: crashed]',
+        '[agent quiet started]',
+        '[agent quiet finished]',
+        '[Resumed a turn that a crash stopped.]',
+        '[Sign in to gh. Open https://gh.example/device and enter the code ABCD.]',
+        '[Sign in to svc. Run /connect svc.]',
+        '',
+      ].join('\n'),
+    )
+  })
+
+  it('does not print what mark() saw', () => {
+    let out = ''
+    const printer = createPrinter((text) => (out += text))
+    const old: SessionViewState = {
+      ...base,
+      messages: [
+        {
+          id: 'history-0',
+          role: 'assistant',
+          parts: [{ type: 'text', text: 'Old.' }],
+        },
+      ],
+    }
+    printer.mark(old)
+    printer.print(old)
+    printer.line('new line')
+    expect(out).toBe('new line\n')
+  })
+})
diff --git a/packages/ai-harness-cli/tsconfig.json b/packages/ai-harness-cli/tsconfig.json
index b9045b913b..29112eff9f 100644
--- a/packages/ai-harness-cli/tsconfig.json
+++ b/packages/ai-harness-cli/tsconfig.json
@@ -1,8 +1,7 @@
 {
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
-    "outDir": "dist",
-    "jsx": "react-jsx"
+    "outDir": "dist"
   },
   "include": ["vite.config.ts", "./src", "./tests"],
   "exclude": ["node_modules", "dist"]

From fb1f97ec63cb30736524c4f5f64c7365fda9720e Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 14:36:47 +0200
Subject: [PATCH 044/286] test(ai-harness): cover the session view paths

The coverage gate failed because the new session view code had paths
that no test ran. These tests run them.

- view-paths.test.ts: a fake SessionViewSource forces each path of
  createSessionView. It covers failed reads at start, a failed or ended
  event stream, connection state, failed actions, approvals, on()
  handlers, the snapshot read coalesce, and dispose.
- view-reduce.test.ts: the reducer branches that return the same
  state, nested and sibling child agents, content-part tool results,
  run errors, and transcript edge cases.
- client-reads.test.ts: the transcript and describe routes answer 400
  and 403, and a failed read throws with its route and status.
- goal.test.ts: selectGoal gives null for state that is not a goal.
- view-fixtures.ts: event and snapshot helpers that the view tests share.

No production code changed.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .../ai-harness/tests/client-reads.test.ts     |  26 +-
 packages/ai-harness/tests/goal.test.ts        |  10 +
 packages/ai-harness/tests/view-fixtures.ts    |  58 ++
 packages/ai-harness/tests/view-paths.test.ts  | 814 ++++++++++++++++++
 packages/ai-harness/tests/view-reduce.test.ts | 429 ++++++++-
 5 files changed, 1314 insertions(+), 23 deletions(-)
 create mode 100644 packages/ai-harness/tests/view-fixtures.ts
 create mode 100644 packages/ai-harness/tests/view-paths.test.ts

diff --git a/packages/ai-harness/tests/client-reads.test.ts b/packages/ai-harness/tests/client-reads.test.ts
index 9a0755b64a..642578d4c9 100644
--- a/packages/ai-harness/tests/client-reads.test.ts
+++ b/packages/ai-harness/tests/client-reads.test.ts
@@ -39,6 +39,7 @@ function setup(
     host,
     harness,
     authorize: () => ({ id: 'u' }),
+    canAccess: (_principal, threadId) => threadId !== 'someone-else',
   })
   const direct: typeof globalThis.fetch = (input, init) =>
     handler(new Request(input, init))
@@ -48,7 +49,7 @@ function setup(
     fetch: fetchWrap ? fetchWrap(direct) : direct,
     reconnectDelayMs: 1,
   })
-  return { host, client }
+  return { host, client, handler }
 }
 
 describe('client reads and actions', () => {
@@ -92,6 +93,29 @@ describe('client reads and actions', () => {
     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('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) => {
diff --git a/packages/ai-harness/tests/goal.test.ts b/packages/ai-harness/tests/goal.test.ts
index c30016ce6e..f9db454233 100644
--- a/packages/ai-harness/tests/goal.test.ts
+++ b/packages/ai-harness/tests/goal.test.ts
@@ -5,6 +5,7 @@ import { memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness, definePlugin } from '../src'
 import { GoalMet, goal, selectGoal } from '../src/first-party'
 import { createSessionView } from '../src/view'
+import { emptyState } from '../src/view/reduce'
 import {
   after,
   gate,
@@ -402,4 +403,13 @@ describe('goal', () => {
     view.dispose()
     await host.close()
   })
+
+  it('gives no goal for goal plugin state that is not a goal', () => {
+    const state = {
+      ...emptyState(),
+      plugins: { 'tanstack/goal': { text: 'finish' } },
+    }
+
+    expect(selectGoal(state)).toBeNull()
+  })
 })
diff --git a/packages/ai-harness/tests/view-fixtures.ts b/packages/ai-harness/tests/view-fixtures.ts
new file mode 100644
index 0000000000..60aabffa42
--- /dev/null
+++ b/packages/ai-harness/tests/view-fixtures.ts
@@ -0,0 +1,58 @@
+import { EventType } from '@tanstack/ai'
+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: {},
+    cursor: '0',
+    ...over,
+  }
+}
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..7f81447714
--- /dev/null
+++ b/packages/ai-harness/tests/view-paths.test.ts
@@ -0,0 +1,814 @@
+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 type { Interrupt } from '@tanstack/ai'
+import type {
+  Cursor,
+  HarnessInput,
+  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('mode', '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('mode', '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('mode', '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('mode', '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'])
+  })
+})
+
+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('mode', '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
index a6b7f2b3e8..0060f46df9 100644
--- a/packages/ai-harness/tests/view-reduce.test.ts
+++ b/packages/ai-harness/tests/view-reduce.test.ts
@@ -8,21 +8,15 @@ import {
   emptyState,
   messagesFromTranscript,
   withNotice,
+  withUserMessage,
 } from '../src/view/reduce'
-import type { StreamChunk } from '@tanstack/ai'
-import type { SessionEvent, SessionSnapshot } from '../src'
+import { at, childRun, custom, sessionSnapshot } from './view-fixtures'
+import type { SessionEvent } from '../src'
 import type { ItemFactory } from '../src/view/reduce'
 import type { SessionViewState } from '../src/view/types'
 
-let cursor = 0
-const at = (event: StreamChunk, operationId = 'op-1'): SessionEvent => {
-  cursor += 1
-  return { cursor: String(cursor), operationId, event }
-}
 const fold = (events: Array<SessionEvent>, start = emptyState()) =>
   events.reduce(applyEvent, start)
-const custom = (name: string, value: unknown) =>
-  at({ type: EventType.CUSTOM, name, value }, 'session')
 
 const factory: ItemFactory = {
   approval: (interrupt, call) => ({
@@ -40,18 +34,6 @@ const factory: ItemFactory = {
   }),
 }
 
-const snapshot = (over: Partial<SessionSnapshot> = {}): SessionSnapshot => ({
-  threadId: 't',
-  status: 'idle',
-  activeOperations: [],
-  queuedTurns: 0,
-  pendingInterrupts: [],
-  pendingQuestions: [],
-  plugins: {},
-  cursor: '0',
-  ...over,
-})
-
 function assistantParts(state: SessionViewState) {
   const message = state.messages.find((item) => item.role === 'assistant')
   return message?.role === 'assistant' ? message.parts : []
@@ -263,6 +245,7 @@ describe('view reducer', () => {
         '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' },
@@ -279,6 +262,12 @@ describe('view reducer', () => {
         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' })
   })
@@ -294,9 +283,11 @@ describe('view reducer', () => {
         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,
@@ -348,7 +339,7 @@ describe('view reducer', () => {
       at({ type: EventType.TOOL_CALL_ARGS, toolCallId: 'c1', delta: '{}' }),
       at({ type: EventType.TOOL_CALL_END, toolCallId: 'c1' }),
     ])
-    const waiting = snapshot({
+    const waiting = sessionSnapshot({
       status: 'requires_action',
       pendingInterrupts: [
         { id: 'int-1', reason: 'tool_approval', toolCallId: 'c1' },
@@ -423,4 +414,398 @@ describe('view reducer', () => {
       '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).toEqual([{ 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: [] },
+    ])
+  })
 })

From 7a2dd0862cf15221f8e46f4b13a965d3f5eaaca1 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 14:47:30 +0200
Subject: [PATCH 045/286] docs(ai-harness-cli): your own screen with runCli({
 ui }), and an Ink screen in the example

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/harness-p12-cli.md        |   5 +
 docs/config.json                     |   6 +-
 docs/harness/cli.md                  |  36 +++-
 docs/harness/custom-ui.md            |   2 +
 examples/harness-cli/README.md       |  20 ++-
 examples/harness-cli/package.json    |   4 +
 examples/harness-cli/src/cli.ts      |   4 +-
 examples/harness-cli/src/tui.tsx     | 190 +++++++++++++++++++++
 examples/harness-cli/tsconfig.json   |   3 +-
 examples/ts-react-chat/package.json  |   2 +-
 packages/ai-harness-cli/README.md    |   8 +-
 packages/ai-harness-cli/package.json |   2 +-
 packages/ai-harness-cli/src/print.ts |   2 +-
 pnpm-lock.yaml                       | 236 ++++++++++++++++++++++++++-
 14 files changed, 496 insertions(+), 24 deletions(-)
 create mode 100644 .changeset/harness-p12-cli.md
 create mode 100644 examples/harness-cli/src/tui.tsx

diff --git a/.changeset/harness-p12-cli.md b/.changeset/harness-p12-cli.md
new file mode 100644
index 0000000000..148499ae0c
--- /dev/null
+++ b/.changeset/harness-p12-cli.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-harness-cli': minor
+---
+
+The CLI has no UI library now: it does not depend on `ink` or `react`. An interactive terminal uses line mode, which now prints from a session view and opens sign-in links in the browser. `runCli(harness, { ui })` runs your own screen with any TUI library: `ui` gets a ready `createSessionView` view and resolves when the user quits. An Ink screen is in `examples/harness-cli/src/tui.tsx`.
diff --git a/docs/config.json b/docs/config.json
index 70c5e697e7..082a0f47ae 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -817,7 +817,8 @@
         {
           "label": "Run in the terminal",
           "to": "harness/cli",
-          "addedAt": "2026-09-26"
+          "addedAt": "2026-09-26",
+          "updatedAt": "2026-09-28"
         },
         {
           "label": "Durable sessions",
@@ -864,7 +865,8 @@
         {
           "label": "Build your own UI",
           "to": "harness/custom-ui",
-          "addedAt": "2026-09-28"
+          "addedAt": "2026-09-28",
+          "updatedAt": "2026-09-28"
         },
         {
           "label": "Run agents from a harness",
diff --git a/docs/harness/cli.md b/docs/harness/cli.md
index 9889069159..6184735ab4 100644
--- a/docs/harness/cli.md
+++ b/docs/harness/cli.md
@@ -2,7 +2,7 @@
 title: Run a harness in the terminal
 id: harness-cli
 order: 3
-description: "Give your harness a terminal UI, a print mode for scripts and CI, NDJSON output, an ACP mode for editors, and an HTTP server."
+description: "Run your harness in a terminal with line mode or your own screen, a print mode for scripts and CI, NDJSON output, an ACP mode for editors, and an HTTP server."
 keywords:
   - tanstack ai
   - harness
@@ -28,8 +28,6 @@ octane: @tanstack/ai-harness-cli
 
 <!-- ::end:tabs -->
 
-The interactive UI uses Ink, which needs Node 22 or later.
-
 ## 1. Write the entry file
 
 ```ts group=harness-cli
@@ -47,13 +45,13 @@ process.exitCode = await runCli(assistant)
 
 ## 2. Pick a mode
 
-- No flags: the interactive UI. Type a message and press Enter. While the agent works, Enter steers it and Esc cancels.
+- No flags: line mode. Type a message and press Enter. With a `ui`, your own screen starts in its place (see [Run your own screen](#run-your-own-screen)).
 - `-p "prompt"`: run one prompt, print the answer, and exit.
 - `-p "prompt" --output ndjson`: print every AG-UI event as one JSON line.
 - `--acp`: serve the harness as an ACP v2 agent over stdio, for editors. Needs `@tanstack/ai-acp`.
 - `--serve`: serve the session protocol over HTTP on `127.0.0.1:8787`. Every request needs the bearer token. Pass `--token`, set `HARNESS_TOKEN`, or copy the token the CLI prints.
 
-When stdin is a pipe, the CLI reads one message or command per line and waits for each turn.
+Line mode reads one message or command per line and waits for each turn. It works the same in a terminal and with piped input. In a terminal, it also opens sign-in links in the browser.
 
 ## 3. Use it in CI
 
@@ -66,7 +64,7 @@ When stdin is a pipe, the CLI reads one message or command per line and waits fo
 | 2 | The turn waits for an approval. |
 | 130 | The turn was cancelled. |
 
-## Commands in the interactive UI
+## Commands in line mode
 
 For the session:
 
@@ -83,8 +81,34 @@ For the running work:
 
 Plugin commands (for example `/model` or `/todos`) show up in `/help`. When a turn stops for an approval or a plugin asks a question, type your answer. For yes-or-no questions, `y` approves and `n` refuses.
 
+## Run your own screen
+
+Line mode prints plain lines. For a full screen with your own layout, pass `ui` to `runCli`. It works with any TUI library, for example Ink, OpenTUI, or blessed.
+
+`ui` gets a ready [session view](./custom-ui) and resolves when the user quits. This entry file starts an Ink screen:
+
+```tsx ignore
+import { render } from 'ink'
+import { runCli } from '@tanstack/ai-harness-cli'
+import { assistant } from './harness'
+import { Screen } from './screen'
+
+process.exitCode = await runCli(assistant, {
+  ui: async (view) => {
+    await render(<Screen view={view} />).waitUntilExit()
+  },
+})
+```
+
+- `ui` runs only in an interactive terminal. Piped input uses line mode. `-p`, `--acp`, `--serve`, and `--dashboard` do not use `ui`.
+- When `ui` resolves, the CLI disposes the view and `runCli` returns.
+- To write `Screen`, read [Build your own UI](./custom-ui).
+
+For a full Ink screen with approvals, questions, sign-ins, and child agents, copy [`examples/harness-cli/src/tui.tsx`](https://github.com/TanStack/ai/blob/main/examples/harness-cli/src/tui.tsx).
+
 ## What you have now
 
 - One entry file that runs your harness as a terminal app, a script step, an editor agent, or a server.
+- Your own terminal screen on the same session, with any TUI library.
 
 Next: keep long turns alive through crashes with [durable sessions](./durable-sessions).
diff --git a/docs/harness/custom-ui.md b/docs/harness/custom-ui.md
index a57e2d3681..fcb7a6d3c8 100644
--- a/docs/harness/custom-ui.md
+++ b/docs/harness/custom-ui.md
@@ -103,6 +103,8 @@ 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.
 
+A full Ink screen, with approvals, questions, sign-ins, and child agents, is in [`examples/harness-cli/src/tui.tsx`](https://github.com/TanStack/ai/blob/main/examples/harness-cli/src/tui.tsx). It runs from [`runCli({ ui })`](./cli#run-your-own-screen).
+
 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
diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index 8f0f7a684b..692962f920 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -15,11 +15,25 @@ Try these:
 
 - `create hello.txt with a short poem`: the agent asks before `write_file`. Type `y`.
 - `/mode plan`, then ask for another file: the write is refused.
-- `/todos`, `/usage`, `/model fast`, `/agents`
-- `/agent haiku {"topic":"rain"}`: runs a typed agent in the background.
+- `/todos`, `/usage`, `/model fast`
 - `/goal create a file hello.txt that says hi`: the agent keeps working until the model says the goal is met. `/goal` shows the status.
 - Press Esc to stop a long answer. Type while it works to steer it.
 
+## The terminal screen
+
+In a terminal, `start` shows an Ink screen. The screen is `src/tui.tsx`, and `src/cli.ts` gives it to `runCli` as `ui`. It is plain example code on `createSessionView`, so copy it and change it.
+
+- It shows the messages, tool calls, child agents, approvals, questions, sign-ins, the goal, and the status.
+- It has `/help`, `/connect <id>`, `/disconnect <id>`, and `/exit`. Other commands, for example `/todos`, go to the plugins.
+- It opens sign-in links in the browser.
+
+Piped input uses line mode. Line mode also has `/agents` and `/agent <name> [json]`, which runs a typed agent in the background:
+
+```bash
+echo /agents | pnpm --filter harness-cli-example start
+echo '/agent haiku {"topic":"rain"}' | pnpm --filter harness-cli-example start
+```
+
 ## Use Notion, Linear, images, and video
 
 1. Run `/connect notion`. Approve the consent page that opens in the browser. Do the same with `/connect linear`.
@@ -37,7 +51,7 @@ Try these:
 3. Ask: `have claude_code create notes.md with one line, then have codex add a second line`.
 
 - Both agents work in `./playground` with your own logins. The API keys are removed from their processes.
-- The CLI shows each agent's tool calls and a finish line. `/fresh` starts new agent sessions.
+- The screen shows each agent with its status, its tool calls, and its latest text. `/fresh` starts new agent sessions.
 - On Windows, the Codex sandbox can block the folder (Access is denied). Then set `CODEX_SANDBOX_MODE=danger-full-access`, only for a folder you trust.
 
 ## Other modes
diff --git a/examples/harness-cli/package.json b/examples/harness-cli/package.json
index f85a495f63..917dd16f13 100644
--- a/examples/harness-cli/package.json
+++ b/examples/harness-cli/package.json
@@ -25,10 +25,14 @@
     "@tanstack/ai-persistence": "workspace:*",
     "@tanstack/ai-sandbox": "workspace:*",
     "@tanstack/ai-sandbox-local-process": "workspace:*",
+    "@tanstack/react-store": "^0.11.1",
+    "ink": "^7.1.1",
+    "react": "^19.2.3",
     "zod": "^4.2.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
     "tsx": "^4.23.12"
   }
 }
diff --git a/examples/harness-cli/src/cli.ts b/examples/harness-cli/src/cli.ts
index a4b42ec82e..b6e2eb2c7e 100644
--- a/examples/harness-cli/src/cli.ts
+++ b/examples/harness-cli/src/cli.ts
@@ -2,10 +2,12 @@ import { runCli } from '@tanstack/ai-harness-cli'
 import { composePersistence, memoryPersistence } from '@tanstack/ai-persistence'
 import { fileCredentials } from './credentials'
 import { assistant } from './harness'
+import { runTui } from './tui'
 
 // Everything in memory, except sign-ins, which are kept in a file.
 const persistence = composePersistence(memoryPersistence(), {
   overrides: { credentials: fileCredentials() },
 })
 
-process.exitCode = await runCli(assistant, { persistence })
+// A terminal shows the Ink screen from ./tui. Piped input uses line mode.
+process.exitCode = await runCli(assistant, { persistence, ui: runTui })
diff --git a/examples/harness-cli/src/tui.tsx b/examples/harness-cli/src/tui.tsx
new file mode 100644
index 0000000000..3a75571b3f
--- /dev/null
+++ b/examples/harness-cli/src/tui.tsx
@@ -0,0 +1,190 @@
+import { spawn } from 'node:child_process'
+import { useState } from 'react'
+import { Box, Text, render, useApp, useInput } from 'ink'
+import { useSelector } from '@tanstack/react-store'
+import { selectGoal } from '@tanstack/ai-harness/plugins'
+import type {
+  SessionView,
+  ViewMessage,
+  ViewPart,
+} from '@tanstack/ai-harness/view'
+
+function textOf(parts: ReadonlyArray<ViewPart>) {
+  return parts.map((part) => (part.type === 'text' ? part.text : '')).join('')
+}
+
+/** Open an http(s) link in the default browser. No shell is involved. */
+function openInBrowser(url: string) {
+  if (!/^https?:\/\//.test(url)) return
+  const isWindows = process.platform === 'win32'
+  // Not `cmd /c start`: cmd would read `&` in the URL as a command separator.
+  const command = isWindows
+    ? 'rundll32'
+    : process.platform === 'darwin'
+      ? 'open'
+      : 'xdg-open'
+  const args = isWindows ? ['url.dll,FileProtocolHandler', url] : [url]
+  const child = spawn(command, args, { stdio: 'ignore', detached: true })
+  // The screen still shows the link when no browser opens.
+  child.on('error', () => {})
+  child.unref()
+}
+
+function Part({ part }: { part: ViewPart }) {
+  if (part.type === 'text') return <Text>{part.text}</Text>
+  if (part.type === 'reasoning') return <Text dimColor>{part.text}</Text>
+  if (part.type === 'tool-call') {
+    const note =
+      part.status === 'needs-approval'
+        ? ' (waits for approval)'
+        : part.status === 'failed'
+          ? ' (failed)'
+          : ''
+    return <Text color="yellow">{`  - tool ${part.name}${note}`}</Text>
+  }
+  // A child agent, for example Claude Code or Codex, with its own tool calls.
+  const latest = textOf(part.parts).replace(/\s+/g, ' ').trim().slice(-80)
+  return (
+    <Box flexDirection="column">
+      <Text color="magenta">
+        {`  - agent ${part.name} (${part.status})${latest ? `: ${latest}` : ''}`}
+      </Text>
+      {part.parts.map((inner, index) =>
+        inner.type === 'tool-call' ? (
+          <Text key={index} color="yellow">{`    - tool ${inner.name}`}</Text>
+        ) : null,
+      )}
+    </Box>
+  )
+}
+
+function Message({ message }: { message: ViewMessage }) {
+  if (message.role === 'user')
+    return <Text color="cyan">{`> ${message.text}`}</Text>
+  if (message.role === 'notice')
+    return (
+      <Text color={message.kind === 'error' ? 'red' : 'gray'}>
+        {message.text}
+      </Text>
+    )
+  return (
+    <Box flexDirection="column">
+      {message.parts.map((part, index) => (
+        <Part key={index} part={part} />
+      ))}
+    </Box>
+  )
+}
+
+function Status({ view }: { view: SessionView }) {
+  const status = useSelector(view.store, (state) => state.status)
+  const approvals = useSelector(view.store, (state) => state.approvals)
+  const question = useSelector(view.store, (state) => state.questions.at(0))
+  const signIns = useSelector(view.store, (state) => state.signIns)
+  const goal = useSelector(view.store, selectGoal)
+  return (
+    <Box flexDirection="column" marginTop={1}>
+      {signIns.map((signIn) => (
+        <Text key={signIn.connector} color="magenta">
+          {`Sign in to ${signIn.connector}: ${signIn.url ?? `run /connect ${signIn.connector}`}${signIn.userCode ? ` (code ${signIn.userCode})` : ''}`}
+        </Text>
+      ))}
+      {approvals.length > 0 ? (
+        <Text color="magenta">
+          {`Approve ${approvals.map((item) => item.tool).join(', ')}? [y/n]`}
+        </Text>
+      ) : null}
+      {question ? <Text color="magenta">{`? ${question.message}`}</Text> : null}
+      {goal ? (
+        <Text color="green">
+          {`Goal: ${goal.text} (${goal.status}, round ${goal.round})`}
+        </Text>
+      ) : null}
+      <Text color="gray">
+        {status === 'running' ? 'working (Esc cancels, Enter steers)' : status}
+      </Text>
+    </Box>
+  )
+}
+
+/** Enter: answer an approval or a question, run a screen command, or send the line. */
+async function submit(view: SessionView, line: string, exit: () => void) {
+  const text = line.trim()
+  const state = view.store.get()
+  if (state.approvals.length > 0) {
+    if (/^y(es)?$/i.test(text)) view.approveAll()
+    else view.rejectAll()
+    return
+  }
+  const [question] = state.questions
+  if (question) {
+    const answer = /^y(es)?$/i.test(text)
+      ? true
+      : /^no?$/i.test(text)
+        ? false
+        : text
+    await question.answer(answer)
+    return
+  }
+  if (text === '/exit') return exit()
+  if (text === '/help') {
+    const commands = state.commands.map(
+      (command) => `/${command.name}  ${command.description}`,
+    )
+    view.notice(
+      ['/connect <id>, /disconnect <id>, /exit', ...commands].join('\n'),
+    )
+    return
+  }
+  const connect = /^\/(connect|disconnect) (\S+)$/.exec(text)
+  if (connect) return view.command(`${connect[1]}:${connect[2]}`)
+  await view.send(text)
+}
+
+function App({ view }: { view: SessionView }) {
+  const { exit } = useApp()
+  const messages = useSelector(view.store, (state) => state.messages)
+  const [input, setInput] = useState('')
+  useInput((character, key) => {
+    if (key.escape) {
+      if (view.store.get().status === 'running') void view.cancel()
+      return
+    }
+    if (key.return) {
+      setInput('')
+      void submit(view, input, exit)
+      return
+    }
+    if (key.backspace || key.delete) {
+      setInput((current) => current.slice(0, -1))
+      return
+    }
+    if (!key.ctrl && !key.meta && character)
+      setInput((current) => current + character)
+  })
+  return (
+    <Box flexDirection="column">
+      {messages.slice(-200).map((message) => (
+        <Message key={message.id} message={message} />
+      ))}
+      <Status view={view} />
+      <Text>
+        <Text color="cyan">{'> '}</Text>
+        {input}
+        <Text inverse> </Text>
+      </Text>
+    </Box>
+  )
+}
+
+/**
+ * The Ink screen for `runCli({ ui })`. It opens sign-in links in the browser,
+ * and resolves when the user types /exit or presses Ctrl+C.
+ */
+export async function runTui(view: SessionView) {
+  view.on('signIn', (signIn) => {
+    if (signIn.url) openInBrowser(signIn.url)
+  })
+  view.notice('Type a message, or /help for commands and /exit to quit.')
+  await render(<App view={view} />).waitUntilExit()
+}
diff --git a/examples/harness-cli/tsconfig.json b/examples/harness-cli/tsconfig.json
index 619816780b..cc93365a78 100644
--- a/examples/harness-cli/tsconfig.json
+++ b/examples/harness-cli/tsconfig.json
@@ -7,7 +7,8 @@
     "noEmit": true,
     "skipLibCheck": true,
     "types": ["node"],
-    "esModuleInterop": true
+    "esModuleInterop": true,
+    "jsx": "react-jsx"
   },
   "include": ["src"]
 }
diff --git a/examples/ts-react-chat/package.json b/examples/ts-react-chat/package.json
index 555fa7ecff..f5974c5b77 100644
--- a/examples/ts-react-chat/package.json
+++ b/examples/ts-react-chat/package.json
@@ -53,7 +53,7 @@
     "@tanstack/react-router-devtools": "^1.158.4",
     "@tanstack/react-router-ssr-query": "^1.158.4",
     "@tanstack/react-start": "^1.159.0",
-    "@tanstack/react-store": "^0.8.0",
+    "@tanstack/react-store": "^0.11.1",
     "@tanstack/router-plugin": "^1.158.4",
     "@tanstack/store": "^0.11.1",
     "dockerode": "^4.0.2",
diff --git a/packages/ai-harness-cli/README.md b/packages/ai-harness-cli/README.md
index 1ff4d8ea4d..713154e207 100644
--- a/packages/ai-harness-cli/README.md
+++ b/packages/ai-harness-cli/README.md
@@ -20,7 +20,7 @@
 
 # @tanstack/ai-harness-cli
 
-Run a TanStack AI harness from the terminal: an interactive UI, a print mode for scripts and CI, NDJSON output, an ACP mode for editors, and an HTTP server.
+Run a TanStack AI harness from the terminal: line mode or your own screen, a print mode for scripts and CI, NDJSON output, an ACP mode for editors, and an HTTP server.
 
 ## Installation
 
@@ -28,8 +28,6 @@ Run a TanStack AI harness from the terminal: an interactive UI, a print mode for
 npm install @tanstack/ai-harness @tanstack/ai-harness-cli
 ```
 
-The interactive UI uses Ink, which needs Node 22 or later.
-
 ## Usage
 
 ```ts
@@ -48,12 +46,14 @@ process.exitCode = await runCli(assistant)
 
 | Flag                          | Mode                                               |
 | ----------------------------- | -------------------------------------------------- |
-| (none)                        | Interactive UI                                     |
+| (none)                        | Line mode, or your `ui` screen in a terminal       |
 | `-p "prompt"`                 | Run one prompt and print the answer                |
 | `-p "prompt" --output ndjson` | Print every AG-UI event as JSON lines              |
 | `--acp`                       | ACP v2 agent over stdio (needs `@tanstack/ai-acp`) |
 | `--serve`                     | Session protocol over HTTP, with a bearer token    |
 
+Line mode reads one message or command per line. To show your own screen in a terminal, pass `ui` to `runCli`, with any TUI library. `ui` gets a ready session view from `@tanstack/ai-harness/view` and resolves when the user quits. An Ink screen is in [`examples/harness-cli/src/tui.tsx`](https://github.com/TanStack/ai/blob/main/examples/harness-cli/src/tui.tsx).
+
 ## Documentation
 
 Read [Run a harness in the terminal](https://tanstack.com/ai/latest/docs/harness/cli).
diff --git a/packages/ai-harness-cli/package.json b/packages/ai-harness-cli/package.json
index 682b353e9a..b44a52097b 100644
--- a/packages/ai-harness-cli/package.json
+++ b/packages/ai-harness-cli/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/ai-harness-cli",
   "version": "0.0.0",
-  "description": "Run a TanStack AI harness from the terminal: interactive UI, print mode, NDJSON, ACP, and an HTTP server",
+  "description": "Run a TanStack AI harness from the terminal: line mode or your own screen, print mode, NDJSON, ACP, and an HTTP server",
   "author": "",
   "license": "MIT",
   "repository": {
diff --git a/packages/ai-harness-cli/src/print.ts b/packages/ai-harness-cli/src/print.ts
index 757c278d94..fbb8ac271d 100644
--- a/packages/ai-harness-cli/src/print.ts
+++ b/packages/ai-harness-cli/src/print.ts
@@ -42,7 +42,7 @@ export async function runPrint(
   if (status === 'completed') return EXIT.ok
   if (status === 'interrupted') {
     stderr.write(
-      'The turn stopped for an approval. Run the interactive mode to answer it.\n',
+      'The turn stopped for an approval. Run without --print, in line mode, to answer it.\n',
     )
     return EXIT.needsAction
   }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f6002c67d5..d381e6702f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -224,6 +224,15 @@ importers:
       '@tanstack/ai-sandbox-local-process':
         specifier: workspace:*
         version: link:../../packages/ai-sandbox-local-process
+      '@tanstack/react-store':
+        specifier: ^0.11.1
+        version: 0.11.1(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      ink:
+        specifier: ^7.1.1
+        version: 7.1.1(@types/react@19.3.0)(react-devtools-core@6.1.5)(react@19.2.3)
+      react:
+        specifier: ^19.2.3
+        version: 19.2.3
       zod:
         specifier: ^4.2.0
         version: 4.3.6
@@ -231,6 +240,9 @@ importers:
       '@types/node':
         specifier: ^24.10.1
         version: 24.13.6
+      '@types/react':
+        specifier: ^19.2.7
+        version: 19.3.0
       tsx:
         specifier: ^4.23.12
         version: 4.23.12
@@ -1191,8 +1203,8 @@ importers:
         specifier: ^1.159.0
         version: 1.159.5(crossws@0.4.6(srvx@0.11.22))(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(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/react-store':
-        specifier: ^0.8.0
-        version: 0.8.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+        specifier: ^0.11.1
+        version: 0.11.1(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       '@tanstack/router-plugin':
         specifier: ^1.158.4
         version: 1.159.5(@tanstack/react-router@1.159.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(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))
@@ -4036,6 +4048,10 @@ packages:
     peerDependencies:
       zod: ^3.25.0 || ^4.0.0
 
+  '@alcalzone/ansi-tokenize@0.3.1':
+    resolution: {integrity: sha512-cUD0PT0YX+rImRhfn7BfMRduP/tX/Zqt/N0dHlAyn2RlcJssCb5KsCJkhln61eh9vuJDkH8wKn3L8zJzzWXPFg==}
+    engines: {node: '>=18'}
+
   '@ampproject/remapping@2.3.0':
     resolution: {integrity: sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw==}
     engines: {node: '>=6.0.0'}
@@ -10797,6 +10813,12 @@ packages:
       react-dom: '>=18.0.0 || >=19.0.0'
       vite: '>=7.0.0'
 
+  '@tanstack/react-store@0.11.1':
+    resolution: {integrity: sha512-HaIGKI3YLmjBYIvy5DFDY23oNaYZIsTZfngey07Uh5iLVJgM3bIGCnZeOFOqzjFld9JHWcaHJnasD/bKoGKwJQ==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
   '@tanstack/react-store@0.8.0':
     resolution: {integrity: sha512-1vG9beLIuB7q69skxK9r5xiLN3ztzIPfSQSs0GfeqWGO2tGIyInZx0x1COhpx97RKaONSoAb8C3dxacWksm1ow==}
     peerDependencies:
@@ -12100,6 +12122,10 @@ packages:
   asynckit@0.4.0:
     resolution: {integrity: sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==}
 
+  auto-bind@5.0.1:
+    resolution: {integrity: sha512-ooviqdwwgfIfNmDwo94wlshcdzfO64XV0Cg6oDsDYBJfITDz1EngD2z7DkbvCWn+XIMsIqW27sEVF6qcpJrRcg==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   autoprefixer@10.4.22:
     resolution: {integrity: sha512-ARe0v/t9gO28Bznv6GgqARmVqcWOV3mfgUPn9becPHMiD3o9BwlRgaeccZnwTpZ7Zwqrm+c1sUSsMxIzQzc8Xg==}
     engines: {node: ^10 || ^12 || >=14}
@@ -12572,6 +12598,10 @@ packages:
     resolution: {integrity: sha512-/lzGpEWL/8PfI0BmBOPRwp0c/wFNX1RdUML3jK/RcSBA9T8mZDdQpqYBKtCFTOfQbwPqWEOpjqW+Fnayc0969g==}
     engines: {node: '>=10'}
 
+  cli-boxes@4.0.1:
+    resolution: {integrity: sha512-5IOn+jcCEHEraYolBPs/sT4BxYCe2nHg374OPiItB1O96KZFseS2gthU4twyYzeDcFew4DaUM/xwc5BQf08JJw==}
+    engines: {node: '>=18.20 <19 || >=20.10'}
+
   cli-cursor@2.1.0:
     resolution: {integrity: sha512-8lgKz8LmCRYZZQDpRyT2m5rKJ08TnU4tR9FFFW2rxpxR1FzWi4PQ/NfyODchAatHaUgnSPVcx/R5w6NuTBzFiw==}
     engines: {node: '>=4'}
@@ -12580,6 +12610,10 @@ packages:
     resolution: {integrity: sha512-I/zHAwsKf9FqGoXM4WWRACob9+SNukZTd94DWF57E4toouRulbCxcUh6RKUEOQlYTHJnzkPMySvPNaaSLNfLZw==}
     engines: {node: '>=8'}
 
+  cli-cursor@4.0.0:
+    resolution: {integrity: sha512-VGtlMu3x/4DOtIUwEkRezxUZ2lBacNJCHash0N0WeZDBS+7Ux1dm3XWAgWYxLJFMMdOeXMHXorshEFhbMSGelg==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   cli-cursor@5.0.0:
     resolution: {integrity: sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==}
     engines: {node: '>=18'}
@@ -12596,6 +12630,10 @@ packages:
     resolution: {integrity: sha512-xRwvIOMGrfOAnM1JYtqQImuaNtDEv9v6oIYAs4LIHwTiKee8uwvIi363igssOC0O5U04i4AlENs79LQLu9tEMw==}
     engines: {node: '>=20'}
 
+  cli-truncate@6.1.1:
+    resolution: {integrity: sha512-06p9vyLahLa4zkGcgsGxU6iEkSOiuI4fhCH6Emhe2lPAcoUv73n72DnODsnHA+5wwXGnV0n9M9/qOQJSjYhFhw==}
+    engines: {node: '>=22'}
+
   cli-width@4.1.0:
     resolution: {integrity: sha512-ouuZd4/dm2Sw5Gmqy6bGyNNNe1qt9RpmxveLSO7KcgsTnU7RXfsw+/bukWGo1abgBiMAic068rclZsO4IWmmxQ==}
     engines: {node: '>= 12'}
@@ -12631,6 +12669,10 @@ packages:
   code-block-writer@12.0.0:
     resolution: {integrity: sha512-q4dMFMlXtKR3XNBHyMHt/3pwYNA69EDk00lloMOaaUMKPUXBw6lpXtbu3MMVG6/uOihGnRDOlkyqsONEUj60+w==}
 
+  code-excerpt@4.0.0:
+    resolution: {integrity: sha512-xxodCmBen3iy2i0WtAK8FlFNrRzjUqjRsMfho58xT/wvZU1YTM3fCnRjcy1gJPMepaRlgm/0e6w8SpWHpn3/cA==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   color-convert@1.9.3:
     resolution: {integrity: sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==}
 
@@ -12761,6 +12803,10 @@ packages:
   convert-source-map@2.0.0:
     resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==}
 
+  convert-to-spaces@2.0.1:
+    resolution: {integrity: sha512-rcQ1bsQO9799wq24uE5AM2tAILy4gXGIK/njFWcVQkGNZ96edlpY+A7bjwvzjYvLDyzmG1MmMLZhpcsb+klNMQ==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   cookie-es@1.2.2:
     resolution: {integrity: sha512-+W7VmiVINB+ywl1HGXJXmrqkOhpKrIiVZV6tQuV54ZyQC7MMuBt81Vc336GMLoHBq5hV/F9eXgt5Mnx0Rha5Fg==}
 
@@ -13485,6 +13531,9 @@ packages:
     resolution: {integrity: sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==}
     engines: {node: '>= 0.4'}
 
+  es-toolkit@1.52.0:
+    resolution: {integrity: sha512-XTNEJQh1tY1ZJVcf6ayP/2n4ZPyaHlW2FWs7xvw5ddPuhUVjLD3olQVQS7kf58JbAB48iL0uL/jerTrjtV3lDA==}
+
   esbuild-plugin-solid@0.5.0:
     resolution: {integrity: sha512-ITK6n+0ayGFeDVUZWNMxX+vLsasEN1ILrg4pISsNOQ+mq4ljlJJiuXotInd+HE0MzwTcA9wExT1yzDE2hsqPsg==}
     peerDependencies:
@@ -13522,6 +13571,10 @@ packages:
     resolution: {integrity: sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==}
     engines: {node: '>=0.8.0'}
 
+  escape-string-regexp@2.0.0:
+    resolution: {integrity: sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w==}
+    engines: {node: '>=8'}
+
   escape-string-regexp@4.0.0:
     resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==}
     engines: {node: '>=10'}
@@ -14472,6 +14525,10 @@ packages:
     resolution: {integrity: sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==}
     engines: {node: '>=0.8.19'}
 
+  indent-string@5.0.0:
+    resolution: {integrity: sha512-m6FAo/spmsW2Ab2fU35JTYwtOKa2yAwXSwgjSv1TJzh4Mh7mC3lzAOVLBprb72XsTrgkEIsl7YrFNAiDiRhIGg==}
+    engines: {node: '>=12'}
+
   inherits@2.0.4:
     resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
 
@@ -14481,6 +14538,19 @@ packages:
   injection-js@2.6.1:
     resolution: {integrity: sha512-dbR5bdhi7TWDoCye9cByZqeg/gAfamm8Vu3G1KZOTYkOif8WkuM8CD0oeDPtZYMzT5YH76JAFB7bkmyY9OJi2A==}
 
+  ink@7.1.1:
+    resolution: {integrity: sha512-Y43xxa1ZSPvpmfLHcN5o+OdP8Rf8ykkNJEuKYOUNZKT8wXVNLFTtEm1nSDMQkfBH+YANF4Xuu0hhZ4ejqAtN2w==}
+    engines: {node: '>=22'}
+    peerDependencies:
+      '@types/react': '>=19.2.0'
+      react: '>=19.2.0'
+      react-devtools-core: '>=6.1.2'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      react-devtools-core:
+        optional: true
+
   inline-style-parser@0.1.1:
     resolution: {integrity: sha512-7NXolsK4CAS5+xvdj5OMMbI962hU/wvwoxk+LWR9Ek9bVtyuuYScDN6eS0rUm6TxApFpw7CX1o4uJzcd4AyD3Q==}
 
@@ -14605,6 +14675,11 @@ packages:
     resolution: {integrity: sha512-S+OpgB5i7wzIue/YSE5hg0e5ZYfG3hhpNh9KGl6ayJ38p7ED6wxQLd1TV91xHpcTvw90KMJ9EwN3F/iNflHBVg==}
     engines: {node: '>=8'}
 
+  is-in-ci@2.0.0:
+    resolution: {integrity: sha512-cFeerHriAnhrQSbpAxL37W1wcJKUUX07HyLWZCW1URJT/ra3GyUTzBgUnh24TMVfNTV2Hij2HLxkPHFZfOZy5w==}
+    engines: {node: '>=20'}
+    hasBin: true
+
   is-in-ssh@1.0.0:
     resolution: {integrity: sha512-jYa6Q9rH90kR1vKB6NM7qqd1mge3Fx4Dhw5TVlK1MUBqhEOuCagrEHMevNuCcbECmXZ0ThXkRm+Ymr51HwEPAw==}
     engines: {node: '>=20'}
@@ -16308,6 +16383,10 @@ packages:
   partial-json@0.1.7:
     resolution: {integrity: sha512-Njv/59hHaokb/hRUjce3Hdv12wd60MtM9Z5Olmn+nehe0QDAsRtRbJPvJ0Z91TusF0SuZRIvnM+S4l6EIP8leA==}
 
+  patch-console@2.0.0:
+    resolution: {integrity: sha512-0YNdUceMdaQwoKce1gatDScmMo5pu/tfABfnzEqeG0gtTmd7mh/WcwgUjtAeOU7N8nFFlbQBnFK2gXW5fGvmMA==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   path-browserify@1.0.1:
     resolution: {integrity: sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g==}
 
@@ -16744,6 +16823,12 @@ packages:
       '@types/react':
         optional: true
 
+  react-reconciler@0.33.0:
+    resolution: {integrity: sha512-KetWRytFv1epdpJc3J4G75I4WrplZE5jOL7Yq0p34+OVOKF4Se7WrdIdVC45XsSSmUTlht2FM/fM1FZb1mfQeA==}
+    engines: {node: '>=0.10.0'}
+    peerDependencies:
+      react: ^19.2.0
+
   react-refresh@0.14.2:
     resolution: {integrity: sha512-jCvmsr+1IUSMUyzOkRcvnVbX3ZYC6g9TDrDbFuFmRDq7PD4yaGbLKNQL6k2jnArV8hjYxh7hVhAZB6s9HDGpZA==}
     engines: {node: '>=0.10.0'}
@@ -16984,6 +17069,10 @@ packages:
     resolution: {integrity: sha512-l+sSefzHpj5qimhFSE5a8nufZYAM3sBSVMAPtYkmC+4EH2anSGaEMXSD0izRQbu9nfyQ9y5JrVmp7E8oZrUjvA==}
     engines: {node: '>=8'}
 
+  restore-cursor@4.0.0:
+    resolution: {integrity: sha512-I9fPXU9geO9bHOt9pHHOhOkYerIMsmVaWB0rA2AI9ERh/+x/i7MV5HKBNrg+ljO5eoPVgCcnFuRjJ9uH6I/3eg==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   restore-cursor@5.1.0:
     resolution: {integrity: sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==}
     engines: {node: '>=18'}
@@ -17404,6 +17493,10 @@ packages:
     resolution: {integrity: sha512-stxByr12oeeOyY2BlviTNQlYV5xOj47GirPr4yA1hE9JCtxfQN0+tVbkxwCtYDQWhEKWFHsEK48ORg5jrouCAg==}
     engines: {node: '>=20'}
 
+  slice-ansi@9.0.1:
+    resolution: {integrity: sha512-aBY19bn/XA+hKOKX0qL7Z0UfdBsbQvc9hn993U8ALUjzxCvDcuZqLoRXjGJrUARWAlwMnsRVD9sw2AFNOYvalA==}
+    engines: {node: '>=22'}
+
   slugify@1.6.9:
     resolution: {integrity: sha512-vZ7rfeehZui7wQs438JXBckYLkIIdfHOXsaVEUMyS5fHo1483l1bMdo0EDSWYclY0yZKFOipDy4KHuKs6ssvdg==}
     engines: {node: '>=8.0.0'}
@@ -17501,6 +17594,10 @@ packages:
     resolution: {integrity: sha512-wPldCk3asibAjQ/kziWQQt1Wh3PgDFpC0XpwclzKcdT1vql6KeYxf5LIt4nlFkUeR8WuphYMKqUA56X4rjbfgQ==}
     engines: {node: '>=10.16.0'}
 
+  stack-utils@2.0.6:
+    resolution: {integrity: sha512-XlkWvfIm6RmsWtNJx+uqtKLS8eqFbxUg0ZzLXqY0caEy9l7hruX8IpiDnjsLavoBgqCCR71TqWO8MaXYheJ3RQ==}
+    engines: {node: '>=10'}
+
   stackback@0.0.2:
     resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}
 
@@ -17743,6 +17840,10 @@ packages:
     resolution: {integrity: sha512-un0FmiRUQNr5PJqy9kP7c40F5BOfpGlYTrxonDChEZB7pzZxRNp/bt+ymiy9/npwXya9KH99nJ/GXFIiUkYGFQ==}
     engines: {node: '>=8'}
 
+  terminal-size@4.0.1:
+    resolution: {integrity: sha512-avMLDQpUI9I5XFrklECw1ZEUPJhqzcwSWsyyI8blhRLT+8N1jLJWLWWYQpB2q2xthq8xDvjZPISVh53T/+CLYQ==}
+    engines: {node: '>=18'}
+
   terser@5.44.1:
     resolution: {integrity: sha512-t/R3R/n0MSwnnazuPpPNVO60LX0SKL45pyl9YlvxIdkH0Of7D5qM2EVe+yASRIlY5pZ73nclYJfNANGWPwFDZw==}
     engines: {node: '>=10'}
@@ -17984,6 +18085,10 @@ packages:
     resolution: {integrity: sha512-RAH822pAdBgcNMAfWnCBU3CFZcfZ/i1eZjwFU/dsLKumyuuP3niueg2UAukXYF0E2AAoc82ZSSf9J0WQBinzHA==}
     engines: {node: '>=12.20'}
 
+  type-fest@5.10.0:
+    resolution: {integrity: sha512-NoSdpq/WEiAg5sjmBkmV/hfxv6HJH4NqPNrqjtSO5CwRmpsDfaf4begxW34KdJykH/l1yHtwBWQkCRdoXO8mPA==}
+    engines: {node: '>=20'}
+
   type-fest@5.3.1:
     resolution: {integrity: sha512-VCn+LMHbd4t6sF3wfU/+HKT63C9OoyrSIf4b+vtWHpt2U7/4InZG467YDNMFMR70DdHjAdpPWmw2lzRdg0Xqqg==}
     engines: {node: '>=20'}
@@ -18904,6 +19009,10 @@ packages:
     resolution: {integrity: sha512-o0cyEG0e8GPzT4iGHphIOh0cJOV8fivsXxddQasHPHfoZf1ZexrfeA21w2NaEN1RHE+fXlfISmOE8R9N3u3Qig==}
     engines: {node: '>=12'}
 
+  widest-line@6.0.0:
+    resolution: {integrity: sha512-U89AsyEeAsyoF0zVJBkG9zBgekjgjK7yk9sje3F4IQpXBJ10TF6ByLlIfjMhcmHMJgHZI4KHt4rdNfktzxIAMA==}
+    engines: {node: '>=20'}
+
   word-wrap@1.2.5:
     resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==}
     engines: {node: '>=0.10.0'}
@@ -18928,6 +19037,10 @@ packages:
       '@cloudflare/workers-types':
         optional: true
 
+  wrap-ansi@10.0.2:
+    resolution: {integrity: sha512-6OLRNZqRntVGBm26ghZ5eZhCuWWyOkRCSn8XsOIuq5stpCE/tjLbdozd93naILZig0lmD8ANfRwnhn0DLeXGlg==}
+    engines: {node: '>=20'}
+
   wrap-ansi@6.2.0:
     resolution: {integrity: sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==}
     engines: {node: '>=8'}
@@ -19104,6 +19217,9 @@ packages:
     resolution: {integrity: sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug==}
     engines: {node: '>=18'}
 
+  yoga-layout@3.2.1:
+    resolution: {integrity: sha512-0LPOt3AxKqMdFBZA3HBAt/t/8vIKq7VaQYbuA8WxCgung+p9TVyKRYdpvCb80HcdTN2NkbIKbhNwKUfm3tQywQ==}
+
   youch-core@0.3.3:
     resolution: {integrity: sha512-ho7XuGjLaJ2hWHoK8yFnsUGy2Y5uDpqSTq1FkHLK4/oqKtyUU1AFbOOxY4IpC9f0fTLjwYbslUz0Po5BpD1wrA==}
 
@@ -19161,6 +19277,11 @@ snapshots:
     dependencies:
       zod: 4.3.6
 
+  '@alcalzone/ansi-tokenize@0.3.1':
+    dependencies:
+      ansi-styles: 6.2.3
+      is-fullwidth-code-point: 5.1.0
+
   '@ampproject/remapping@2.3.0':
     dependencies:
       '@jridgewell/gen-mapping': 0.3.13
@@ -22022,7 +22143,7 @@ snapshots:
       terminal-link: 2.1.1
       toqr: 0.1.1
       wrap-ansi: 7.0.0
-      ws: 8.21.0
+      ws: 8.21.3
       zod: 3.25.76
     optionalDependencies:
       react-native: 0.85.3(@babel/core@7.29.7)(@types/react@19.2.7)(react@19.2.3)(supports-color@7.2.0)
@@ -22097,7 +22218,7 @@ snapshots:
       terminal-link: 2.1.1
       toqr: 0.1.1
       wrap-ansi: 7.0.0
-      ws: 8.21.0
+      ws: 8.21.3
       zod: 3.25.76
     optionalDependencies:
       react-native: 0.85.3(@babel/core@7.29.7)(@types/react@19.2.7)(react@19.2.3)
@@ -27758,6 +27879,13 @@ snapshots:
       - vite-plugin-solid
       - webpack
 
+  '@tanstack/react-store@0.11.1(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
+    dependencies:
+      '@tanstack/store': 0.11.1
+      react: 19.2.3
+      react-dom: 19.2.3(react@19.2.3)
+      use-sync-external-store: 1.6.0(react@19.2.3)
+
   '@tanstack/react-store@0.8.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
     dependencies:
       '@tanstack/store': 0.8.0
@@ -29908,6 +30036,8 @@ snapshots:
 
   asynckit@0.4.0: {}
 
+  auto-bind@5.0.1: {}
+
   autoprefixer@10.4.22(postcss@8.5.26):
     dependencies:
       browserslist: 4.28.1
@@ -30573,6 +30703,8 @@ snapshots:
 
   cli-boxes@3.0.0: {}
 
+  cli-boxes@4.0.1: {}
+
   cli-cursor@2.1.0:
     dependencies:
       restore-cursor: 2.0.0
@@ -30581,6 +30713,10 @@ snapshots:
     dependencies:
       restore-cursor: 3.1.0
 
+  cli-cursor@4.0.0:
+    dependencies:
+      restore-cursor: 4.0.0
+
   cli-cursor@5.0.0:
     dependencies:
       restore-cursor: 5.1.0
@@ -30594,6 +30730,11 @@ snapshots:
       slice-ansi: 8.0.0
       string-width: 8.2.2
 
+  cli-truncate@6.1.1:
+    dependencies:
+      slice-ansi: 9.0.1
+      string-width: 8.2.2
+
   cli-width@4.1.0: {}
 
   clipboardy@4.0.0:
@@ -30628,6 +30769,10 @@ snapshots:
 
   code-block-writer@12.0.0: {}
 
+  code-excerpt@4.0.0:
+    dependencies:
+      convert-to-spaces: 2.0.1
+
   color-convert@1.9.3:
     dependencies:
       color-name: 1.1.3
@@ -30743,6 +30888,8 @@ snapshots:
 
   convert-source-map@2.0.0: {}
 
+  convert-to-spaces@2.0.1: {}
+
   cookie-es@1.2.2: {}
 
   cookie-es@1.2.3: {}
@@ -31377,6 +31524,8 @@ snapshots:
       has-tostringtag: 1.0.2
       hasown: 2.0.4
 
+  es-toolkit@1.52.0: {}
+
   esbuild-plugin-solid@0.5.0(esbuild@0.28.1)(solid-js@1.9.10):
     dependencies:
       '@babel/core': 7.29.7
@@ -31506,6 +31655,8 @@ snapshots:
 
   escape-string-regexp@1.0.5: {}
 
+  escape-string-regexp@2.0.0: {}
+
   escape-string-regexp@4.0.0: {}
 
   escape-string-regexp@5.0.0: {}
@@ -32715,6 +32866,8 @@ snapshots:
 
   imurmurhash@0.1.4: {}
 
+  indent-string@5.0.0: {}
+
   inherits@2.0.4: {}
 
   ini@1.3.8: {}
@@ -32723,6 +32876,41 @@ snapshots:
     dependencies:
       tslib: 2.8.1
 
+  ink@7.1.1(@types/react@19.3.0)(react-devtools-core@6.1.5)(react@19.2.3):
+    dependencies:
+      '@alcalzone/ansi-tokenize': 0.3.1
+      ansi-escapes: 7.3.0
+      ansi-styles: 6.2.3
+      auto-bind: 5.0.1
+      chalk: 5.6.2
+      cli-boxes: 4.0.1
+      cli-cursor: 4.0.0
+      cli-truncate: 6.1.1
+      code-excerpt: 4.0.0
+      es-toolkit: 1.52.0
+      indent-string: 5.0.0
+      is-in-ci: 2.0.0
+      patch-console: 2.0.0
+      react: 19.2.3
+      react-reconciler: 0.33.0(react@19.2.3)
+      scheduler: 0.27.0
+      signal-exit: 3.0.7
+      slice-ansi: 9.0.1
+      stack-utils: 2.0.6
+      string-width: 8.2.2
+      terminal-size: 4.0.1
+      type-fest: 5.10.0
+      widest-line: 6.0.0
+      wrap-ansi: 10.0.2
+      ws: 8.21.3
+      yoga-layout: 3.2.1
+    optionalDependencies:
+      '@types/react': 19.3.0
+      react-devtools-core: 6.1.5
+    transitivePeerDependencies:
+      - bufferutil
+      - utf-8-validate
+
   inline-style-parser@0.1.1: {}
 
   inline-style-parser@0.2.7: {}
@@ -32843,6 +33031,8 @@ snapshots:
     dependencies:
       html-tags: 3.3.1
 
+  is-in-ci@2.0.0: {}
+
   is-in-ssh@1.0.0: {}
 
   is-inside-container@1.0.0:
@@ -35505,6 +35695,8 @@ snapshots:
 
   partial-json@0.1.7: {}
 
+  patch-console@2.0.0: {}
+
   path-browserify@1.0.1: {}
 
   path-exists@3.0.0: {}
@@ -36239,6 +36431,11 @@ snapshots:
       - supports-color
       - utf-8-validate
 
+  react-reconciler@0.33.0(react@19.2.3):
+    dependencies:
+      react: 19.2.3
+      scheduler: 0.27.0
+
   react-refresh@0.14.2: {}
 
   react-refresh@0.17.0: {}
@@ -36594,6 +36791,11 @@ snapshots:
       onetime: 5.1.2
       signal-exit: 3.0.7
 
+  restore-cursor@4.0.0:
+    dependencies:
+      onetime: 5.1.2
+      signal-exit: 3.0.7
+
   restore-cursor@5.1.0:
     dependencies:
       onetime: 7.0.0
@@ -37240,6 +37442,11 @@ snapshots:
       ansi-styles: 6.2.3
       is-fullwidth-code-point: 5.1.0
 
+  slice-ansi@9.0.1:
+    dependencies:
+      ansi-styles: 6.2.3
+      is-fullwidth-code-point: 5.1.0
+
   slugify@1.6.9: {}
 
   smart-buffer@4.2.0: {}
@@ -37336,6 +37543,10 @@ snapshots:
       cpu-features: 0.0.10
       nan: 2.27.0
 
+  stack-utils@2.0.6:
+    dependencies:
+      escape-string-regexp: 2.0.0
+
   stackback@0.0.2: {}
 
   stackframe@1.3.4: {}
@@ -37631,6 +37842,8 @@ snapshots:
       ansi-escapes: 4.3.2
       supports-hyperlinks: 2.3.0
 
+  terminal-size@4.0.1: {}
+
   terser@5.44.1:
     dependencies:
       '@jridgewell/source-map': 0.3.11
@@ -37906,6 +38119,10 @@ snapshots:
 
   type-fest@2.19.0: {}
 
+  type-fest@5.10.0:
+    dependencies:
+      tagged-tag: 1.0.0
+
   type-fest@5.3.1:
     dependencies:
       tagged-tag: 1.0.0
@@ -38958,6 +39175,10 @@ snapshots:
     dependencies:
       string-width: 5.1.2
 
+  widest-line@6.0.0:
+    dependencies:
+      string-width: 8.2.2
+
   word-wrap@1.2.5: {}
 
   workerd@1.20260609.1:
@@ -38993,6 +39214,11 @@ snapshots:
       - bufferutil
       - utf-8-validate
 
+  wrap-ansi@10.0.2:
+    dependencies:
+      ansi-styles: 6.2.3
+      string-width: 8.2.2
+
   wrap-ansi@6.2.0:
     dependencies:
       ansi-styles: 4.3.0
@@ -39123,6 +39349,8 @@ snapshots:
 
   yoctocolors@2.1.2: {}
 
+  yoga-layout@3.2.1: {}
+
   youch-core@0.3.3:
     dependencies:
       '@poppinss/exception': 1.2.3

From 281d37b66726ef51ccb671454324958a65c35f7c Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 15:11:20 +0200
Subject: [PATCH 046/286] chore(examples): ts-solid-chat uses the latest
 @tanstack/solid-store

Every direct TanStack Store dependency in the workspace is now on the latest
release (store, react-store, and solid-store 0.11.1).

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 examples/ts-solid-chat/package.json |  2 +-
 pnpm-lock.yaml                      | 14 ++++++++++++--
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/examples/ts-solid-chat/package.json b/examples/ts-solid-chat/package.json
index 5ac6e3b16a..f4531527a9 100644
--- a/examples/ts-solid-chat/package.json
+++ b/examples/ts-solid-chat/package.json
@@ -27,7 +27,7 @@
     "@tanstack/solid-router-devtools": "^1.139.10",
     "@tanstack/solid-router-ssr-query": "^1.139.10",
     "@tanstack/solid-start": "^1.139.10",
-    "@tanstack/solid-store": "^0.8.0",
+    "@tanstack/solid-store": "^0.11.1",
     "@tanstack/store": "^0.11.1",
     "highlight.js": "^11.11.1",
     "lucide-solid": "^0.554.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d381e6702f..169f770bf9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1804,8 +1804,8 @@ importers:
         specifier: ^1.139.10
         version: 1.141.1(@tanstack/react-router@1.159.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(crossws@0.4.6(srvx@0.11.22))(solid-js@1.9.10)(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/solid-store':
-        specifier: ^0.8.0
-        version: 0.8.0(solid-js@1.9.10)
+        specifier: ^0.11.1
+        version: 0.11.1(solid-js@1.9.10)
       '@tanstack/store':
         specifier: ^0.11.1
         version: 0.11.1
@@ -11023,6 +11023,11 @@ packages:
       solid-js: '>=1.0.0'
       vite: '>=7.0.0'
 
+  '@tanstack/solid-store@0.11.1':
+    resolution: {integrity: sha512-wzJsiqqLHyQacqbYPT8dKNfhR00NNu743vGeWz2lEpOyE/R+6AYIfFLhXsCIT/Kb+KKiT1KDkB2/35DhLEGx8g==}
+    peerDependencies:
+      solid-js: ^1.6.0
+
   '@tanstack/solid-store@0.8.0':
     resolution: {integrity: sha512-JwqTedbxyOGw7mfmdGkB0RGgefRCw/tNauc8tlMcaS1mV5wTFT8c1KIB3LgttuHaanMJEBeqQJ7bc/R0WTP1fA==}
     peerDependencies:
@@ -28242,6 +28247,11 @@ snapshots:
       - vite-plugin-solid
       - webpack
 
+  '@tanstack/solid-store@0.11.1(solid-js@1.9.10)':
+    dependencies:
+      '@tanstack/store': 0.11.1
+      solid-js: 1.9.10
+
   '@tanstack/solid-store@0.8.0(solid-js@1.9.10)':
     dependencies:
       '@tanstack/store': 0.8.0

From 83825af227ef85ccae75dc1fcbd065d8c754a2e2 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 15:22:03 +0200
Subject: [PATCH 047/286] feat(ai, ai-harness): agentMiddleware runs plugin
 middleware in every agent

@tanstack/ai:
- The chat middleware context has subagentName and parentSubagentRunId.
  chat() takes both as options. The bound ctx.chat sets them.
- A child that calls ctx.chat({ subagents }) gives its own children the
  host chatMiddleware and generationMiddleware before their own, also
  when the binding has no budget.
- A nested child gets parentSubagentRunId on its run input. Its
  SUBAGENT_STARTED does not carry it in the stream of the chat that
  started it: attributeChunk adds it one level up, as before.

@tanstack/ai-harness:
- Plugins can contribute agentMiddleware: chat middleware for subagents,
  background agents, and their children. Not for the lead turn.
- The lead turn passes run plugins' agentMiddleware and
  generationMiddleware to its agents too.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/harness-p13-agent-middleware.md    |   8 +
 packages/ai-harness/src/plugins.ts            |  11 ++
 packages/ai-harness/src/session.ts            |  16 +-
 .../ai-harness/tests/agent-middleware.test.ts | 180 +++++++++++++++++
 .../ai/src/activities/chat/agents/bound.ts    |  32 ++-
 .../activities/chat/agents/define-agent.ts    |   1 +
 .../ai/src/activities/chat/agents/spawn.ts    |  25 ++-
 packages/ai/src/activities/chat/index.ts      |  12 ++
 .../src/activities/chat/middleware/types.ts   |   4 +
 packages/ai/src/types.ts                      |  10 +
 packages/ai/tests/bound-activities.test.ts    |  40 +++-
 .../ai/tests/define-agent-results.test.ts     | 186 +++++++++++++++---
 12 files changed, 477 insertions(+), 48 deletions(-)
 create mode 100644 .changeset/harness-p13-agent-middleware.md
 create mode 100644 packages/ai-harness/tests/agent-middleware.test.ts

diff --git a/.changeset/harness-p13-agent-middleware.md b/.changeset/harness-p13-agent-middleware.md
new file mode 100644
index 0000000000..263d74fb77
--- /dev/null
+++ b/.changeset/harness-p13-agent-middleware.md
@@ -0,0 +1,8 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-harness': minor
+---
+
+`@tanstack/ai`: the chat middleware context has `subagentName`, the agent name of a child that runs through `ctx.chat`, and `parentSubagentRunId`, the id of the child that started a nested child. `chat()` takes both as options. A child that calls `ctx.chat({ subagents })` now gives its own children the host middleware (`subagents.binding.chatMiddleware` and `generationMiddleware`) before their own, also when the binding has no budget.
+
+`@tanstack/ai-harness`: plugins can contribute `agentMiddleware`, chat middleware for every agent run: subagents the lead model calls (coding agents too), background agents, and their children. It does not run in the lead turn. Put the same middleware in `middleware` and `agentMiddleware` to see every model call. Run plugins' `generationMiddleware` now also reaches the agents of their turn.
diff --git a/packages/ai-harness/src/plugins.ts b/packages/ai-harness/src/plugins.ts
index ddc2fbeb06..d02e91e159 100644
--- a/packages/ai-harness/src/plugins.ts
+++ b/packages/ai-harness/src/plugins.ts
@@ -47,6 +47,12 @@ export interface PluginContributions {
   prompts?: ReadonlyArray<string | (() => string) | PluginPrompt>
   /** Chat middleware, the same type as `chat({ middleware })`. */
   middleware?: ReadonlyArray<AnyChatMiddleware>
+  /**
+   * Chat middleware for every agent run: subagents, background agents, and
+   * their children. Not the lead turn: add the same middleware to
+   * `middleware` for that.
+   */
+  agentMiddleware?: ReadonlyArray<AnyChatMiddleware>
   /** Middleware for the activities agents call (`ctx.generateImage`, ...). */
   generationMiddleware?: ReadonlyArray<AnyGenerationMiddleware>
   /** Agents added to `session.agents`. */
@@ -281,6 +287,8 @@ export interface MountedPlugins {
     prompts: Array<{ id: string; owner: string }>
   }
   middleware: Array<AnyChatMiddleware>
+  /** Chat middleware for every agent run. See `PluginContributions`. */
+  agentMiddleware: Array<AnyChatMiddleware>
   generationMiddleware: Array<AnyGenerationMiddleware>
   /**
    * Chat middleware that provides every plugin capability to each chat run,
@@ -443,6 +451,7 @@ export async function mountPlugins(
   }))
   const prompts: Array<Owned<PluginPrompt>> = []
   const middleware: Array<AnyChatMiddleware> = []
+  const agentMiddleware: Array<AnyChatMiddleware> = []
   const generationMiddleware: Array<AnyGenerationMiddleware> = []
   const commands = new Map<string, { command: AnyCommand; owner: string }>()
   const config = new Map<string, { option: ConfigOption; owner: string }>()
@@ -554,6 +563,7 @@ export async function mountPlugins(
         prompts.push({ value: section, owner: plugin.name })
       })
       middleware.push(...(contributions.middleware ?? []))
+      agentMiddleware.push(...(contributions.agentMiddleware ?? []))
       generationMiddleware.push(...(contributions.generationMiddleware ?? []))
       for (const [name, command] of Object.entries(
         contributions.commands ?? {},
@@ -647,6 +657,7 @@ export async function mountPlugins(
       .map((entry) => entry.value),
     prompts: prompts.map((entry) => entry.value.text),
     middleware,
+    agentMiddleware,
     generationMiddleware,
     commands,
     config,
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index eec819381f..f5be633c5d 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -1066,10 +1066,18 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     return root.child()
   }
 
-  private binding(): SubagentBinding {
+  /** What plugins add to every agent run: session plugins, then run plugins. */
+  private binding(runPlugins?: MountedPlugins) {
     return {
-      generationMiddleware: this.sessionPlugins?.generationMiddleware ?? [],
-    }
+      generationMiddleware: [
+        ...(this.sessionPlugins?.generationMiddleware ?? []),
+        ...(runPlugins?.generationMiddleware ?? []),
+      ],
+      chatMiddleware: [
+        ...(this.sessionPlugins?.agentMiddleware ?? []),
+        ...(runPlugins?.agentMiddleware ?? []),
+      ],
+    } satisfies SubagentBinding
   }
 
   private async runTurn(turn: QueuedTurn): Promise<void> {
@@ -1171,7 +1179,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
                 ...this.harness.subagents,
                 agents: subagentList,
                 limits: this.limits(),
-                binding: this.binding(),
+                binding: this.binding(runPlugins),
               },
             }
           : {}),
diff --git a/packages/ai-harness/tests/agent-middleware.test.ts b/packages/ai-harness/tests/agent-middleware.test.ts
new file mode 100644
index 0000000000..85f7e33e8d
--- /dev/null
+++ b/packages/ai-harness/tests/agent-middleware.test.ts
@@ -0,0 +1,180 @@
+import { describe, expect, it } from 'vitest'
+import { EventType, defineAgent } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness, definePlugin } from '../src'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { AnyChatMiddleware, StreamChunk } from '@tanstack/ai'
+import type { AnyHarness, PluginLifetime } from '../src'
+
+/** `chunks` with `totalTokens` of usage on RUN_FINISHED, as real models report. */
+function withUsage(chunks: Array<StreamChunk>, totalTokens: number) {
+  return chunks.map((chunk) =>
+    chunk.type === EventType.RUN_FINISHED
+      ? {
+          ...chunk,
+          usage: [{ inputTokens: totalTokens, outputTokens: 0, totalTokens }],
+        }
+      : chunk,
+  )
+}
+
+/** An agent that answers `answer` through `ctx.chat`. */
+function textAgent(name: string, answer = `${name} done`, tokens = 0) {
+  const { adapter } = mockAdapter([() => withUsage(text(answer), tokens)])
+  return defineAgent({
+    name,
+    description: `The ${name} agent`,
+    run: (ctx) => ctx.chat({ adapter }),
+  })
+}
+
+/** Chat middleware that records the name of every run it sees. */
+function recordRuns() {
+  const runs: Array<string> = []
+  const middleware: AnyChatMiddleware = {
+    name: 'test/record',
+    onStart: (ctx) => {
+      runs.push(ctx.subagentName ?? 'lead')
+    },
+  }
+  return { runs, middleware }
+}
+
+function agentPlugin(
+  middleware: AnyChatMiddleware,
+  lifetime: PluginLifetime = 'session',
+) {
+  return definePlugin({
+    name: 'test/agent-middleware',
+    lifetime,
+    setup: () => ({ agentMiddleware: [middleware] }),
+  })
+}
+
+async function open(harness: AnyHarness) {
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const session = await host.open(harness, { threadId: 't' })
+  return { host, session }
+}
+
+/**
+ * A model that calls `agent` once, then answers. `tokens` is the usage of the
+ * two calls.
+ */
+function leadCalling(agent: string, tokens: [number, number] = [0, 0]) {
+  return mockAdapter([
+    () => withUsage(toolCall(agent, {}), tokens[0]),
+    () => withUsage(text('lead done'), tokens[1]),
+  ]).adapter
+}
+
+/** An agent whose model calls `child` as a tool through `ctx.chat`. */
+function parentAgent(
+  name: string,
+  child: ReturnType<typeof textAgent>,
+  tokens: [number, number] = [0, 0],
+) {
+  const adapter = leadCalling(child.name, tokens)
+  return defineAgent({
+    name,
+    description: `Starts ${child.name}`,
+    run: (ctx) => ctx.chat({ adapter, subagents: { agents: [child] } }),
+  })
+}
+
+describe('plugin agentMiddleware', () => {
+  it('runs for a subagent the lead model calls and for its nested child, not for the lead turn', async () => {
+    const { runs, middleware } = recordRuns()
+    const researcher = parentAgent('researcher', textAgent('fetcher'))
+    const { host, session } = await open(
+      defineHarness({
+        name: 'test/agent-middleware',
+        adapter: leadCalling('researcher'),
+        subagents: { agents: [researcher] },
+        plugins: () => [agentPlugin(middleware)],
+      }),
+    )
+
+    const turn = await session.prompt('research')
+
+    expect(turn.text).toBe('lead done')
+    expect(runs).toEqual(['researcher', 'fetcher'])
+    await host.close()
+  })
+
+  it('runs for a background agent started from the session', async () => {
+    const { runs, middleware } = recordRuns()
+    const { host, session } = await open(
+      defineHarness({
+        name: 'test/agent-middleware',
+        adapter: mockAdapter([]).adapter,
+        agents: [textAgent('worker', 'worked')],
+        plugins: () => [agentPlugin(middleware)],
+      }),
+    )
+
+    const result = await session.agent('worker')?.start()
+
+    expect(result).toBe('worked')
+    expect(runs).toEqual(['worker'])
+    await host.close()
+  })
+
+  it('runs for a run-lifetime plugin too', async () => {
+    const { runs, middleware } = recordRuns()
+    const { host, session } = await open(
+      defineHarness({
+        name: 'test/agent-middleware',
+        adapter: leadCalling('helper'),
+        subagents: { agents: [textAgent('helper')] },
+        plugins: () => [agentPlugin(middleware, 'run')],
+      }),
+    )
+
+    await session.prompt('help')
+
+    expect(runs).toEqual(['helper'])
+    await host.close()
+  })
+
+  it('counts each model call once per agent when one tracker is in middleware and agentMiddleware', async () => {
+    const calls: Array<{ agent: string; totalTokens: number }> = []
+    const tracker: AnyChatMiddleware = {
+      name: 'test/usage',
+      onUsage: (ctx, usage) => {
+        calls.push({
+          agent: ctx.subagentName ?? 'lead',
+          totalTokens: usage.totalTokens,
+        })
+      },
+    }
+    const usagePlugin = definePlugin({
+      name: 'test/usage',
+      setup: () => ({ middleware: [tracker], agentMiddleware: [tracker] }),
+    })
+    const researcher = parentAgent(
+      'researcher',
+      textAgent('fetcher', 'fetched', 100),
+      [10, 20],
+    )
+    const { host, session } = await open(
+      defineHarness({
+        name: 'test/agent-middleware',
+        adapter: leadCalling('researcher', [1, 2]),
+        subagents: { agents: [researcher] },
+        plugins: () => [usagePlugin],
+      }),
+    )
+
+    await session.prompt('research')
+
+    expect(calls).toEqual([
+      { agent: 'lead', totalTokens: 1 },
+      { agent: 'researcher', totalTokens: 10 },
+      { agent: 'fetcher', totalTokens: 100 },
+      { agent: 'researcher', totalTokens: 20 },
+      { agent: 'lead', totalTokens: 2 },
+    ])
+    await host.close()
+  })
+})
diff --git a/packages/ai/src/activities/chat/agents/bound.ts b/packages/ai/src/activities/chat/agents/bound.ts
index 8cbd182921..22e1a2b21f 100644
--- a/packages/ai/src/activities/chat/agents/bound.ts
+++ b/packages/ai/src/activities/chat/agents/bound.ts
@@ -37,9 +37,15 @@ export interface SubagentForward {
  * it.
  */
 export interface SubagentBinding {
-  /** Added before the call's own middleware on every `ctx.chat` call. */
+  /**
+   * Added before the call's own middleware on every `ctx.chat` call. A
+   * child's `ctx.chat({ subagents })` passes it down to its own children.
+   */
   chatMiddleware?: ReadonlyArray<AnyChatMiddleware>
-  /** Added before the call's own middleware on every generation call. */
+  /**
+   * Added before the call's own middleware on every generation call. A
+   * child's `ctx.chat({ subagents })` passes it down to its own children.
+   */
   generationMiddleware?: ReadonlyArray<GenerationMiddleware>
   /**
    * The subagent tree budget. A child's `ctx.chat({ subagents })` passes it
@@ -75,10 +81,11 @@ type LooseOptions = Record<string, any> & {
 }
 
 export function createBoundActivities(
+  agentName: string,
   input: SubagentRunInput,
   abortController: AbortController,
   binding?: SubagentBinding,
-): BoundActivities {
+) {
   let calls = 0
   const signal = abortController.signal
   const chatMiddleware = binding?.chatMiddleware ?? []
@@ -112,17 +119,28 @@ export function createBoundActivities(
         runId: input.runId,
         parentRunId: input.parentRunId,
         subagentRunId: input.subagentRunId,
+        subagentName: agentName,
+        parentSubagentRunId: input.parentSubagentRunId,
         ...(input.resume ? { resume: input.resume } : {}),
         abortController,
         ...options,
-        // Nested children share the tree budget.
-        ...(options.subagents && binding?.budget
+        // Nested children get the host middleware before their own, and share
+        // the tree budget.
+        ...(options.subagents
           ? {
               subagents: {
                 ...options.subagents,
                 binding: {
                   ...options.subagents.binding,
-                  budget: binding.budget,
+                  chatMiddleware: [
+                    ...chatMiddleware,
+                    ...(options.subagents.binding?.chatMiddleware ?? []),
+                  ],
+                  generationMiddleware: [
+                    ...generationMiddleware,
+                    ...(options.subagents.binding?.generationMiddleware ?? []),
+                  ],
+                  ...(binding?.budget ? { budget: binding.budget } : {}),
                 },
               },
             }
@@ -165,5 +183,5 @@ export function createBoundActivities(
       decide(
         withGenerationMiddleware({ abortSignal: signal, ...options }) as never,
       )) as typeof decide,
-  }
+  } satisfies BoundActivities
 }
diff --git a/packages/ai/src/activities/chat/agents/define-agent.ts b/packages/ai/src/activities/chat/agents/define-agent.ts
index 0c6ea78b38..0ffde9cca0 100644
--- a/packages/ai/src/activities/chat/agents/define-agent.ts
+++ b/packages/ai/src/activities/chat/agents/define-agent.ts
@@ -43,6 +43,7 @@ export interface SubagentRunInput<
    * `ctx.subagentRunId`.
    */
   subagentRunId: string
+  /** The subagentRunId of the child that started this one, for a nested child. */
   parentSubagentRunId?: string
 }
 
diff --git a/packages/ai/src/activities/chat/agents/spawn.ts b/packages/ai/src/activities/chat/agents/spawn.ts
index 2782be0e7e..fcc8db333d 100644
--- a/packages/ai/src/activities/chat/agents/spawn.ts
+++ b/packages/ai/src/activities/chat/agents/spawn.ts
@@ -133,6 +133,8 @@ interface SpawnContext {
   parentRunId: string
   /** The interrupted parent run, on a resume. */
   interruptedRunId?: string
+  /** The parent chat's own subagentRunId, when that chat is a child too. */
+  parentSubagentRunId?: string
 }
 
 export function createSubagentId() {
@@ -278,6 +280,9 @@ function openAgentStream(
       runId: childRunId(ctx.parentRunId, subagentRunId),
       parentRunId: resumed?.parentRunId ?? ctx.parentRunId,
       subagentRunId,
+      ...(ctx.parentSubagentRunId !== undefined
+        ? { parentSubagentRunId: ctx.parentSubagentRunId }
+        : {}),
       ...(resumed ? { resume: resumed.resume } : {}),
     },
     sink,
@@ -478,10 +483,11 @@ function* valueResultChunks(
  * bound activity functions.
  */
 function runContext(
+  agentName: string,
   input: SubagentRunInput,
   abortController: AbortController,
   binding?: SubagentBinding,
-): SubagentRunContext {
+) {
   return {
     ...input,
     forward: {
@@ -492,8 +498,8 @@ function runContext(
       ...(input.resume ? { resume: input.resume } : {}),
       abortController,
     },
-    ...createBoundActivities(input, abortController, binding),
-  }
+    ...createBoundActivities(agentName, input, abortController, binding),
+  } satisfies SubagentRunContext
 }
 
 export async function* spawnAgentStream(
@@ -504,16 +510,16 @@ export async function* spawnAgentStream(
   binding?: SubagentBinding,
 ): AsyncIterable<StreamChunk> {
   const link = linkAbort(input.abortSignal)
-  const ctx = runContext(input, link.controller, binding)
+  const ctx = runContext(agent.name, input, link.controller, binding)
   const id = ctx.subagentRunId
+  // No parentSubagentRunId here, also for a nested child: the chat that
+  // started this child lists it as a direct child. attributeChunk adds the id
+  // one level up, in the stream of the parent child.
   yield {
     type: SUBAGENT_STARTED,
     subagentRunId: id,
     name: agent.name,
     description: agent.description,
-    ...(ctx.parentSubagentRunId !== undefined
-      ? { parentSubagentRunId: ctx.parentSubagentRunId }
-      : {}),
     ...(parentToolCallId !== undefined ? { parentToolCallId } : {}),
     timestamp: Date.now(),
   } satisfies SubagentStartedEvent
@@ -822,6 +828,8 @@ export function createSyntheticSubagentTools(
     threadId: string
     runId: string
     interruptedRunId?: string
+    /** The parent chat's own subagentRunId, when that chat is a child too. */
+    parentSubagentRunId?: string
     abortSignal?: AbortSignal
     turn?: SubagentTurn
     sink: SubagentSink
@@ -909,6 +917,9 @@ export function createSyntheticSubagentTools(
             ...(parent.interruptedRunId !== undefined
               ? { interruptedRunId: parent.interruptedRunId }
               : {}),
+            ...(parent.parentSubagentRunId !== undefined
+              ? { parentSubagentRunId: parent.parentSubagentRunId }
+              : {}),
           },
           sink,
           toolCallId,
diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index 4e33991787..32cd45e39a 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -537,6 +537,10 @@ export interface TextActivityOptions<
   parentRunId?: TextOptions['parentRunId']
   /** Subagent run id when this chat runs as a child. See `defineAgent`. */
   subagentRunId?: TextOptions['subagentRunId']
+  /** The agent name when this chat runs as a subagent. Middleware reads `ctx.subagentName`. */
+  subagentName?: TextOptions['subagentName']
+  /** The subagentRunId of the child that started this one, for a nested child. */
+  parentSubagentRunId?: TextOptions['parentSubagentRunId']
   /** Application state mirrored in a STATE_SNAPSHOT before an interrupt terminal. */
   state?: TextOptions['state']
   /**
@@ -1049,6 +1053,8 @@ class TextEngine<
       runId: this.runIdOverride ?? this.requestId,
       parentRunId: this.parentRunIdOverride,
       subagentRunId: this.subagentRunIdOverride,
+      subagentName: config.params.subagentName,
+      parentSubagentRunId: config.params.parentSubagentRunId,
       threadId: this.threadId,
       // Legacy alias kept on the ctx so middleware that reads
       // `ctx.conversationId` keeps working. Always equals `threadId`.
@@ -5319,6 +5325,9 @@ async function* streamTextChunks(
       ...(options.parentRunId !== undefined && {
         interruptedRunId: options.parentRunId,
       }),
+      ...(options.subagentRunId !== undefined && {
+        parentSubagentRunId: options.subagentRunId,
+      }),
       ...(options.abortController && {
         abortSignal: options.abortController.signal,
       }),
@@ -5502,6 +5511,9 @@ async function* runRoutedSubagents(
             ...(options.parentRunId !== undefined && {
               interruptedRunId: options.parentRunId,
             }),
+            ...(options.subagentRunId !== undefined && {
+              parentSubagentRunId: options.subagentRunId,
+            }),
           },
           sink,
         )) {
diff --git a/packages/ai/src/activities/chat/middleware/types.ts b/packages/ai/src/activities/chat/middleware/types.ts
index 80051b256c..50d177d1f0 100644
--- a/packages/ai/src/activities/chat/middleware/types.ts
+++ b/packages/ai/src/activities/chat/middleware/types.ts
@@ -198,6 +198,10 @@ export interface ChatMiddlewareContext<TContext = unknown> {
    * and on every chunk it streams. Absent on a top-level run.
    */
   subagentRunId?: string
+  /** The agent name when this run is a subagent. */
+  subagentName?: string
+  /** The subagentRunId of the child that started this one, for a nested child. */
+  parentSubagentRunId?: string
   /**
    * AG-UI thread identifier — a stable per-conversation ID used to
    * correlate client and server devtools events. Resolves to the
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index 5262545e2f..8b9faa4c0e 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -1182,6 +1182,16 @@ export interface TextOptions<
    * `ctx.subagentRunId`. Absent on a top-level run.
    */
   subagentRunId?: string
+  /**
+   * The agent name when this chat runs as a subagent. Middleware reads it as
+   * `ctx.subagentName`.
+   */
+  subagentName?: string
+  /**
+   * The subagentRunId of the child that started this one, for a nested child.
+   * Middleware reads it as `ctx.parentSubagentRunId`.
+   */
+  parentSubagentRunId?: string
 
   /** Application state mirrored in a STATE_SNAPSHOT before an interrupt terminal. */
   state?: unknown
diff --git a/packages/ai/tests/bound-activities.test.ts b/packages/ai/tests/bound-activities.test.ts
index 1eda9780c6..1e2d2e6d99 100644
--- a/packages/ai/tests/bound-activities.test.ts
+++ b/packages/ai/tests/bound-activities.test.ts
@@ -1,4 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
+import type { GenerationMiddleware } from '../src/activities/middleware/types'
+import type { ChatMiddleware } from '../src/activities/chat/middleware/types'
 
 // Replace every activity with a spy that returns the options it got, so the
 // test sees exactly what each bound wrapper passes on.
@@ -53,17 +55,21 @@ const input = {
   subagentRunId: 'child-1',
 }
 
+// The spies return this record, not the real return type. That is why each
+// bound function is cast to one that returns `Recorded` before the call.
 type Recorded = { name: string; options: Record<string, any> }
 
 describe('createBoundActivities', () => {
-  const generationMiddleware = [{ name: 'host-generation' }]
-  const chatMiddleware = [{ name: 'host-chat' }]
+  const generationMiddleware: Array<GenerationMiddleware> = [
+    { name: 'host-generation' },
+  ]
+  const chatMiddleware: Array<ChatMiddleware> = [{ name: 'host-chat' }]
 
   function bound() {
     const controller = new AbortController()
-    const activities = createBoundActivities(input, controller, {
-      chatMiddleware: chatMiddleware as never,
-      generationMiddleware: generationMiddleware as never,
+    const activities = createBoundActivities('helper', input, controller, {
+      chatMiddleware,
+      generationMiddleware,
     })
     return { activities, controller }
   }
@@ -131,6 +137,7 @@ describe('createBoundActivities', () => {
       runId: 'run-1',
       parentRunId: 'parent-1',
       subagentRunId: 'child-1',
+      subagentName: 'helper',
       abortController: controller,
       middleware: chatMiddleware,
     })
@@ -138,8 +145,29 @@ describe('createBoundActivities', () => {
     expect(custom.options).toMatchObject({ messages: [], threadId: 'mine' })
   })
 
+  it('gives nested children the host middleware first, then their own, with no budget', () => {
+    const { activities } = bound()
+    const chat = activities.chat as unknown as (options: object) => Recorded
+    const own = { name: 'own' }
+    const nested = chat({
+      adapter: 'a',
+      subagents: {
+        agents: [],
+        binding: { chatMiddleware: [own], generationMiddleware: [own] },
+      },
+    })
+    expect(nested.options.subagents.binding).toEqual({
+      chatMiddleware: [...chatMiddleware, own],
+      generationMiddleware: [...generationMiddleware, own],
+    })
+  })
+
   it('works without a binding', () => {
-    const activities = createBoundActivities(input, new AbortController())
+    const activities = createBoundActivities(
+      'helper',
+      input,
+      new AbortController(),
+    )
     const result = (
       activities.generateImage as unknown as (options: object) => Recorded
     )({ prompt: 'x' })
diff --git a/packages/ai/tests/define-agent-results.test.ts b/packages/ai/tests/define-agent-results.test.ts
index 647f1bbdfb..461ef4c774 100644
--- a/packages/ai/tests/define-agent-results.test.ts
+++ b/packages/ai/tests/define-agent-results.test.ts
@@ -6,10 +6,16 @@ import { compactForModel } from '../src/activities/chat/tools/tool-calls'
 import { collectChunks, createMockAdapter, ev } from './test-utils'
 import type { ImageAdapter } from '../src/activities/generateImage/adapter'
 import type { GenerationMiddleware } from '../src/activities/middleware/types'
-import type { ChatMiddleware } from '../src/activities/chat/middleware/types'
+import type {
+  ChatMiddleware,
+  ChatMiddlewareContext,
+} from '../src/activities/chat/middleware/types'
 import type { DefinedAgent } from '../src/activities/chat/agents/define-agent'
 import type { StreamChunk } from '../src/types'
 
+type ChatStart = NonNullable<ChatMiddleware['onStart']>
+type GenerationStart = NonNullable<GenerationMiddleware['onStart']>
+
 /** A parent model that calls `agentName` once with `args`, then answers. */
 function parentCalling(agentName: string, args = '{}') {
   return createMockAdapter({
@@ -68,14 +74,79 @@ function imageAdapter(generateImages = vi.fn()): ImageAdapter {
     images: [{ url: 'https://example.com/a.png' }],
   })
   return {
-    kind: 'image' as const,
+    kind: 'image',
     name: 'test-image',
     model: 'test-model',
-    '~types': {} as any,
+    '~types': {
+      providerOptions: {},
+      modelProviderOptionsByName: {},
+      modelSizeByName: {},
+      modelInputModalitiesByName: {},
+    },
     generateImages,
   }
 }
 
+/** The SUBAGENT_STARTED id of the child named `name`. */
+function idOf(chunks: Array<StreamChunk>, name: string): string {
+  const chunk = chunks.find(
+    (entry) => entry.type === 'SUBAGENT_STARTED' && entry.name === name,
+  )
+  if (chunk?.type !== 'SUBAGENT_STARTED') throw new Error(`no ${name}`)
+  return chunk.subagentRunId
+}
+
+/** An agent whose model calls `child` as a tool through `ctx.chat`. */
+function parentAgent(name: string, child: DefinedAgent) {
+  const { adapter } = parentCalling(child.name)
+  return defineAgent({
+    name,
+    description: `Starts ${child.name}`,
+    run: (ctx) => ctx.chat({ adapter, subagents: { agents: [child] } }),
+  })
+}
+
+/** A child that answers with one line of text through `ctx.chat`. */
+function textAgent(name: string) {
+  const { adapter } = createMockAdapter({
+    iterations: [
+      [
+        ev.runStarted(),
+        ev.textStart('t'),
+        ev.textContent(`${name} done`, 't'),
+        ev.textEnd('t'),
+        ev.runFinished('stop'),
+      ],
+    ],
+  })
+  return defineAgent({
+    name,
+    description: `The ${name} agent`,
+    run: (ctx) => ctx.chat({ adapter }),
+  })
+}
+
+/** Host chat middleware that records who each run is. */
+function recordRuns() {
+  const runs: Array<
+    Pick<
+      ChatMiddlewareContext,
+      'subagentName' | 'subagentRunId' | 'parentSubagentRunId'
+    >
+  > = []
+  const middleware: ChatMiddleware = {
+    name: 'host',
+    onStart: (ctx) => {
+      runs.push({
+        subagentName: ctx.subagentName,
+        subagentRunId: ctx.subagentRunId,
+        parentSubagentRunId: ctx.parentSubagentRunId,
+      })
+    },
+  }
+  return { runs, middleware }
+}
+
 describe('defineAgent promise results', () => {
   it('sends a promise result to the parent model and on SUBAGENT_FINISHED', async () => {
     const agent = defineAgent({
@@ -147,7 +218,13 @@ describe('defineAgent promise results', () => {
 
 describe('agent run context', () => {
   it('gives run ctx.forward with the child ids and an abort controller', async () => {
-    const seen: Array<unknown> = []
+    const seen: Array<{
+      threadId: string
+      runId: string
+      parentRunId: string
+      subagentRunId: string
+      aborted: boolean
+    }> = []
     const agent = defineAgent({
       name: 'probe',
       description: 'Records ctx.forward',
@@ -172,8 +249,8 @@ describe('agent run context', () => {
         aborted: false,
       }),
     ])
-    const forward = seen[0] as { runId: string; subagentRunId: string }
-    expect(forward.runId).toBe(`run-p:${forward.subagentRunId}`)
+    const forward = seen[0]
+    expect(forward?.runId).toBe(`run-p:${forward?.subagentRunId}`)
   })
 
   it('runs ctx.chat with the child ids, the parent messages, and host middleware', async () => {
@@ -188,7 +265,7 @@ describe('agent run context', () => {
         ],
       ],
     })
-    const onStart = vi.fn()
+    const onStart = vi.fn<ChatStart>()
     const agent = defineAgent({
       name: 'helper',
       description: 'Uses ctx.chat',
@@ -200,12 +277,10 @@ describe('agent run context', () => {
     })
 
     expect(onStart).toHaveBeenCalledTimes(1)
-    const hostCtx = onStart.mock.calls[0]?.[0] as {
-      threadId: string
-      subagentRunId?: string
-    }
-    expect(hostCtx.threadId).toBe('thread-p:helper')
-    expect(hostCtx.subagentRunId).toBeDefined()
+    const hostCtx = onStart.mock.calls[0]?.[0]
+    expect(hostCtx?.threadId).toBe('thread-p:helper')
+    expect(hostCtx?.subagentRunId).toBe(idOf(chunks, 'helper'))
+    expect(hostCtx?.subagentName).toBe('helper')
     expect(child.calls[0]?.messages).toEqual(
       expect.arrayContaining([expect.objectContaining({ content: 'Go' })]),
     )
@@ -215,7 +290,7 @@ describe('agent run context', () => {
   it('runs ctx.generateImage with a child run id, the abort signal, and host middleware', async () => {
     const generateImages = vi.fn()
     const adapter = imageAdapter(generateImages)
-    const onStart = vi.fn()
+    const onStart = vi.fn<GenerationStart>()
     const agent = defineAgent({
       name: 'illustrator',
       description: 'Makes an image',
@@ -249,25 +324,88 @@ describe('agent run context', () => {
     expect(generateImages).toHaveBeenCalledWith(
       expect.objectContaining({ prompt: 'a cat', size: '1024x1024' }),
     )
-    const request = generateImages.mock.calls[0]?.[0] as {
-      abortSignal?: AbortSignal
-      threadId?: unknown
-    }
+    const request = generateImages.mock.calls[0]?.[0]
     expect(request.abortSignal).toBeInstanceOf(AbortSignal)
     // Ids and middleware stay in the activity; the adapter never sees them.
     expect(request.threadId).toBeUndefined()
-    const genCtx = onStart.mock.calls[0]?.[0] as {
-      threadId: string
-      runId: string
-    }
-    expect(genCtx.threadId).toBe('thread-p:illustrator')
-    expect(genCtx.runId).toMatch(/^run-p:subagent-.+:image-1$/)
+    const genCtx = onStart.mock.calls[0]?.[0]
+    expect(genCtx?.threadId).toBe('thread-p:illustrator')
+    expect(genCtx?.runId).toMatch(/^run-p:subagent-.+:image-1$/)
     expect(finished(chunks).result).toMatchObject({
       images: [{ url: 'https://example.com/a.png' }],
     })
   })
 })
 
+describe('nested children', () => {
+  it('runs host chat middleware in a nested child, with each run name and parent', async () => {
+    const researcher = parentAgent('researcher', textAgent('fetcher'))
+    const { runs, middleware } = recordRuns()
+
+    const chunks = await runParent(researcher, { chatMiddleware: [middleware] })
+
+    const researcherId = idOf(chunks, 'researcher')
+    expect(runs).toEqual([
+      { subagentName: 'researcher', subagentRunId: researcherId },
+      {
+        subagentName: 'fetcher',
+        subagentRunId: idOf(chunks, 'fetcher'),
+        parentSubagentRunId: researcherId,
+      },
+    ])
+  })
+
+  it('runs host chat middleware in a nested child when the binding has no budget', async () => {
+    // A child a router starts gets the binding as it is, with no tree budget.
+    const lead = parentAgent('lead', textAgent('writer'))
+    const { runs, middleware } = recordRuns()
+    const { adapter } = createMockAdapter({ iterations: [] })
+
+    const chunks = await collectChunks(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'Go' }],
+        threadId: 'thread-p',
+        runId: 'run-p',
+        subagents: {
+          agents: [lead],
+          router: () => 'lead',
+          binding: { chatMiddleware: [middleware] },
+        },
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect(runs.map((run) => run.subagentName)).toEqual(['lead', 'writer'])
+    expect(runs[1]?.parentSubagentRunId).toBe(idOf(chunks, 'lead'))
+  })
+
+  it('passes host generation middleware down to a nested child', async () => {
+    const generateImages = vi.fn()
+    const onStart = vi.fn<GenerationStart>()
+    const illustrator = defineAgent({
+      name: 'illustrator',
+      description: 'Makes an image',
+      run: (ctx) =>
+        ctx.generateImage({
+          adapter: imageAdapter(generateImages),
+          prompt: 'a cat',
+          size: '1024x1024',
+        }),
+    })
+    const designer = parentAgent('designer', illustrator)
+
+    await runParent(designer, {
+      generationMiddleware: [{ name: 'host', onStart }],
+    })
+
+    expect(generateImages).toHaveBeenCalledTimes(1)
+    expect(onStart).toHaveBeenCalledTimes(1)
+    expect(onStart.mock.calls[0]?.[0].threadId).toBe(
+      'thread-p:designer:illustrator',
+    )
+  })
+})
+
 describe('agent types', () => {
   it('keeps produces as a literal and infers a promise result', () => {
     const agent = defineAgent({

From 6d97231580e2f9d461cd076a153e6fe0dc6d500c Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 15:22:11 +0200
Subject: [PATCH 048/286] docs(ai-harness): middleware in every agent

Add a "Middleware in every agent" section to the plugins page, with a
usage tracker that puts one middleware in middleware and
agentMiddleware. Link it from the harness subagents page. The chat
subagents page names the new subagentName and parentSubagentRunId
context fields.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 docs/chat/subagents.md    |  2 ++
 docs/config.json          |  5 +++--
 docs/harness/plugins.md   | 39 ++++++++++++++++++++++++++++++++++++++-
 docs/harness/subagents.md |  2 ++
 4 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/docs/chat/subagents.md b/docs/chat/subagents.md
index 7916787a8f..9da0c131fb 100644
--- a/docs/chat/subagents.md
+++ b/docs/chat/subagents.md
@@ -387,6 +387,8 @@ A child is its own `chat()` call. Put the child's middleware in that call. The p
 
 Inside a child, the middleware context has `subagentRunId`. Use it to tell a child run from a top-level run, and to link a child trace to its card.
 
+When the child calls `ctx.chat`, the context also has `subagentName`, the name of the agent. For a nested child, `parentSubagentRunId` is the id of the child that started it.
+
 On a routed turn where a child runs and main does not, the parent's middleware does not run. Only `withPersistence` records that turn. A turn where main runs, including a handoff, runs the parent's middleware as usual.
 
 ## Persistence
diff --git a/docs/config.json b/docs/config.json
index 082a0f47ae..8363ec63db 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -155,7 +155,7 @@
           "label": "Subagents",
           "to": "chat/subagents",
           "addedAt": "2026-09-21",
-          "updatedAt": "2026-09-26"
+          "updatedAt": "2026-09-28"
         },
         {
           "label": "Agentic Cycle",
@@ -871,7 +871,8 @@
         {
           "label": "Run agents from a harness",
           "to": "harness/subagents",
-          "addedAt": "2026-09-26"
+          "addedAt": "2026-09-26",
+          "updatedAt": "2026-09-28"
         },
         {
           "label": "Deploy a harness",
diff --git a/docs/harness/plugins.md b/docs/harness/plugins.md
index f05cd1d3bc..9efa2dd835 100644
--- a/docs/harness/plugins.md
+++ b/docs/harness/plugins.md
@@ -30,7 +30,7 @@ Add it with `plugins: () => [today]` in `defineHarness`. `setup` runs once per s
 
 - `tools`: tools for the model, made with `toolDefinition`.
 - `prompts`: text for the system prompt. A function runs for each turn, so it can show current state.
-- `middleware`: chat middleware, the same type as `chat({ middleware })`.
+- `middleware`: chat middleware for the lead turn, the same type as `chat({ middleware })`. `agentMiddleware` is for agent runs, see [Middleware in every agent](#middleware-in-every-agent).
 - `generationMiddleware`: middleware for the activities agents call.
 - `agents`: agents added to `session.agents`.
 - `subagents`: agents the model can call as tools. They are also added to `session.agents`. [Delegate to coding agents](./coding-agents) uses them.
@@ -99,6 +99,42 @@ export const counter = definePlugin({
 
 When two writers race, `update` runs your function again with fresh state.
 
+## Middleware in every agent
+
+You want to track token cost, or apply a policy, for every model call. But `middleware` runs only in the lead turn. The agents that the lead model calls, the agents you start in the background, and their own children each run a separate chat. Put the same middleware in `agentMiddleware` too. Then it runs in each of those chats.
+
+```ts group=harness-plugins
+import type { ChatMiddleware } from '@tanstack/ai'
+
+export const usageByAgent = definePlugin({
+  name: 'acme/usage-by-agent',
+  setup: () => {
+    const tokens = new Map<string, number>()
+    const tracker: ChatMiddleware = {
+      name: 'acme/usage-by-agent',
+      onUsage: (ctx, usage) => {
+        const agent = ctx.subagentName ?? 'lead'
+        tokens.set(agent, (tokens.get(agent) ?? 0) + usage.totalTokens)
+      },
+    }
+    return {
+      middleware: [tracker],
+      agentMiddleware: [tracker],
+      commands: {
+        tokens: defineCommand({
+          description: 'Show the tokens of each agent',
+          run: () => Object.fromEntries(tokens),
+        }),
+      },
+    }
+  },
+})
+```
+
+- `ctx.subagentName` is the name of the agent. In the lead turn, it is `undefined`.
+- `ctx.subagentRunId` is different for each run of an agent. For a nested child, `ctx.parentSubagentRunId` is the id of the child that started it.
+- Each model call goes to `onUsage` one time, in the run that made the call. The lead turn does not count the usage of a child again.
+
 ## Let plugins work together
 
 Three ways, from simple to loose:
@@ -152,6 +188,7 @@ Set `lifetime: 'run'` to set a plugin up again for each turn.
 ## What you have now
 
 - A plugin that adds tools, prompts, commands, settings, and state to any harness.
+- Middleware that sees every model call, in the lead turn and in every agent.
 - Plugins that share services, lists, and events without knowing each other.
 
 Next: see the [first-party plugins](./coding-agent) that turn a harness into a coding agent.
diff --git a/docs/harness/subagents.md b/docs/harness/subagents.md
index e97c17718a..5efc0a9b5e 100644
--- a/docs/harness/subagents.md
+++ b/docs/harness/subagents.md
@@ -62,6 +62,8 @@ export const review = definePlugin({
 - `ctx.agents.start(agent, input, { wake: true })` runs it in the background and starts a turn when it is done.
 - `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.
 
+To track usage or apply a policy in each of these runs, see [Middleware in every agent](./plugins#middleware-in-every-agent).
+
 ## Call a harness as a child
 
 `harnessAgent` turns a harness into an agent. Put it in `subagents.agents`, and the main model calls it as a tool. The child harness keeps its own tools, plugins, and history.

From 47ee22f76a13a6e0d248adea36bd944242d2a1bd Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 15:44:06 +0200
Subject: [PATCH 049/286] feat(ai-harness): usage() counts the model calls of
 every agent

The usage counter now sits in agentMiddleware too, so /usage covers the lead
turn, subagents, background agents, and their children.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/harness-p13-agent-middleware.md    |  2 +-
 docs/harness/coding-agent.md                  |  2 +-
 .../src/first-party/session-tools.ts          | 40 +++++++++++--------
 .../ai-harness/tests/agent-middleware.test.ts | 25 ++++++++++++
 4 files changed, 51 insertions(+), 18 deletions(-)

diff --git a/.changeset/harness-p13-agent-middleware.md b/.changeset/harness-p13-agent-middleware.md
index 263d74fb77..ea64d5500d 100644
--- a/.changeset/harness-p13-agent-middleware.md
+++ b/.changeset/harness-p13-agent-middleware.md
@@ -5,4 +5,4 @@
 
 `@tanstack/ai`: the chat middleware context has `subagentName`, the agent name of a child that runs through `ctx.chat`, and `parentSubagentRunId`, the id of the child that started a nested child. `chat()` takes both as options. A child that calls `ctx.chat({ subagents })` now gives its own children the host middleware (`subagents.binding.chatMiddleware` and `generationMiddleware`) before their own, also when the binding has no budget.
 
-`@tanstack/ai-harness`: plugins can contribute `agentMiddleware`, chat middleware for every agent run: subagents the lead model calls (coding agents too), background agents, and their children. It does not run in the lead turn. Put the same middleware in `middleware` and `agentMiddleware` to see every model call. Run plugins' `generationMiddleware` now also reaches the agents of their turn.
+`@tanstack/ai-harness`: plugins can contribute `agentMiddleware`, chat middleware for every agent run: subagents the lead model calls (coding agents too), background agents, and their children. It does not run in the lead turn. Put the same middleware in `middleware` and `agentMiddleware` to see every model call. Run plugins' `generationMiddleware` now also reaches the agents of their turn. The first-party `usage()` plugin now counts the model calls of every agent, not only the lead turn.
diff --git a/docs/harness/coding-agent.md b/docs/harness/coding-agent.md
index f2a657a6a2..d1dfe8e355 100644
--- a/docs/harness/coding-agent.md
+++ b/docs/harness/coding-agent.md
@@ -68,7 +68,7 @@ Run the file with `npx tsx coder.ts`. Ask for a change. The agent reads files fr
 | `projectInstructions({ root })` | Adds `AGENTS.md` and `CLAUDE.md` to the system prompt. |
 | `fileCommands({ dir })` | Each `.md` file becomes a slash command. `$ARGUMENTS` is replaced by what you type after it. |
 | `compact({ adapter })` | `/compact` replaces a long conversation with a summary. |
-| `usage()` | `/usage` shows the tokens of the session. |
+| `usage()` | `/usage` shows the tokens of the session: the lead turn and every agent. |
 | `goal({ judge })` | `/goal <text>` keeps the agent working until a judge model says that the goal is met. See [Work until a goal is met](./goal). |
 
 ## Add your own rules
diff --git a/packages/ai-harness/src/first-party/session-tools.ts b/packages/ai-harness/src/first-party/session-tools.ts
index 47417a4795..9e17dc2194 100644
--- a/packages/ai-harness/src/first-party/session-tools.ts
+++ b/packages/ai-harness/src/first-party/session-tools.ts
@@ -1,7 +1,11 @@
 import { chat } from '@tanstack/ai'
 import { defineCommand } from '../commands'
 import { definePlugin } from '../plugins'
-import type { AnyTextAdapter, ModelMessage } from '@tanstack/ai'
+import type {
+  AnyChatMiddleware,
+  AnyTextAdapter,
+  ModelMessage,
+} from '@tanstack/ai'
 
 const SUMMARY_PROMPT =
   'Summarize the conversation so far for yourself. Keep decisions, open tasks, file names, and facts you still need. Leave out small talk.'
@@ -78,7 +82,10 @@ interface UsageTotals {
   totalTokens: number
 }
 
-/** Count tokens across the session. `/usage` shows the totals. */
+/**
+ * Count tokens across the session: the lead turn and every agent run
+ * (subagents, background agents, and their children). `/usage` shows the totals.
+ */
 export function usage() {
   return definePlugin({
     name: 'tanstack/usage',
@@ -91,21 +98,22 @@ export function usage() {
       })
       const show = (totals: UsageTotals) =>
         `${totals.turns} model calls, ${totals.promptTokens} input tokens, ${totals.completionTokens} output tokens, ${totals.totalTokens} total.`
+      const count = {
+        name: 'tanstack/usage',
+        onUsage: async (_run, info) => {
+          await state.update((totals) => ({
+            turns: totals.turns + 1,
+            promptTokens: totals.promptTokens + (info.promptTokens ?? 0),
+            completionTokens:
+              totals.completionTokens + (info.completionTokens ?? 0),
+            totalTokens: totals.totalTokens + (info.totalTokens ?? 0),
+          }))
+        },
+      } satisfies AnyChatMiddleware
       return {
-        middleware: [
-          {
-            name: 'tanstack/usage',
-            onUsage: async (_run, info) => {
-              await state.update((totals) => ({
-                turns: totals.turns + 1,
-                promptTokens: totals.promptTokens + (info.promptTokens ?? 0),
-                completionTokens:
-                  totals.completionTokens + (info.completionTokens ?? 0),
-                totalTokens: totals.totalTokens + (info.totalTokens ?? 0),
-              }))
-            },
-          },
-        ],
+        // The same counter in the lead turn and in every agent run.
+        middleware: [count],
+        agentMiddleware: [count],
         commands: {
           usage: defineCommand({
             description: 'Show token usage for this session',
diff --git a/packages/ai-harness/tests/agent-middleware.test.ts b/packages/ai-harness/tests/agent-middleware.test.ts
index 85f7e33e8d..53991c13b3 100644
--- a/packages/ai-harness/tests/agent-middleware.test.ts
+++ b/packages/ai-harness/tests/agent-middleware.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { EventType, defineAgent } from '@tanstack/ai'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness, definePlugin } from '../src'
+import { usage } from '../src/first-party'
 import { mockAdapter, text, toolCall } from './helpers'
 import type { AnyChatMiddleware, StreamChunk } from '@tanstack/ai'
 import type { AnyHarness, PluginLifetime } from '../src'
@@ -177,4 +178,28 @@ describe('plugin agentMiddleware', () => {
     ])
     await host.close()
   })
+
+  it('lets the usage() plugin count the model calls of every agent', async () => {
+    const researcher = parentAgent(
+      'researcher',
+      textAgent('fetcher', 'fetched', 100),
+      [10, 20],
+    )
+    const { host, session } = await open(
+      defineHarness({
+        name: 'test/agent-middleware',
+        adapter: leadCalling('researcher', [1, 2]),
+        subagents: { agents: [researcher] },
+        plugins: () => [usage()],
+      }),
+    )
+
+    await session.prompt('research')
+
+    // The lead (1 + 2), the researcher (10 + 20), and the fetcher (100).
+    expect(await session.command('usage')).toBe(
+      '5 model calls, 133 input tokens, 0 output tokens, 133 total.',
+    )
+    await host.close()
+  })
 })

From ff6844a528f87e15121e365924a6549c82f72f50 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 17:39:18 +0200
Subject: [PATCH 050/286] feat(ai-mcp): serve a harness as an MCP server

Add createHarnessMcpServer at @tanstack/ai-mcp/harness. It opens
sessions with host.open(harness, { threadId }) and returns the
createMCPServer server, so any MCP client can use the harness.

Tools: chat, steer, cancel, approve, reject, resolve, answer, status,
agent_<name> for each exposed agent, and command_<name> for each plugin
command. Every tool takes an optional threadId. With approvals 'ask',
a client with elicitation answers each approval inline. Otherwise the
approvals come back in the result. approvals 'auto' approves all.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-mcp/package.json           |   4 +
 packages/ai-mcp/skills/ai-mcp/SKILL.md |   2 +
 packages/ai-mcp/src/harness.ts         | 516 +++++++++++++++++++++++++
 packages/ai-mcp/tests/harness.test.ts  | 490 +++++++++++++++++++++++
 packages/ai-mcp/vite.config.ts         |   1 +
 5 files changed, 1013 insertions(+)
 create mode 100644 packages/ai-mcp/src/harness.ts
 create mode 100644 packages/ai-mcp/tests/harness.test.ts

diff --git a/packages/ai-mcp/package.json b/packages/ai-mcp/package.json
index 25b6c7730e..e4bdc620d7 100644
--- a/packages/ai-mcp/package.json
+++ b/packages/ai-mcp/package.json
@@ -56,6 +56,10 @@
     "./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": [
diff --git a/packages/ai-mcp/skills/ai-mcp/SKILL.md b/packages/ai-mcp/skills/ai-mcp/SKILL.md
index 78170b96c3..2d0a350c36 100644
--- a/packages/ai-mcp/skills/ai-mcp/SKILL.md
+++ b/packages/ai-mcp/skills/ai-mcp/SKILL.md
@@ -54,6 +54,8 @@ The package has these subpaths:
 - `./server` exports `createMCPServer`.
 - `./server/stdio` exports `serveMCPStdio`.
 - `./apps` exports `createMcpAppCallHandler`.
+- `./harness` exports `createHarnessMcpServer`. It serves a TanStack AI
+  harness as an MCP server. See `docs/harness/mcp-server.md`.
 
 Import `./stdio` and `./server/stdio` only from Node code.
 Those entries use Node I/O.
diff --git a/packages/ai-mcp/src/harness.ts b/packages/ai-mcp/src/harness.ts
new file mode 100644
index 0000000000..710e44424a
--- /dev/null
+++ b/packages/ai-mcp/src/harness.ts
@@ -0,0 +1,516 @@
+import {
+  EventType,
+  convertSchemaToJsonSchema,
+  toolDefinition,
+} from '@tanstack/ai'
+import { HARNESS_EVENTS } from '@tanstack/ai-harness'
+import { createMCPServer } from './server/create-server'
+import type { Interrupt, JSONSchema } from '@tanstack/ai'
+import type {
+  AnyHarness,
+  Cursor,
+  HarnessHost,
+  HarnessSession,
+  Operation,
+} from '@tanstack/ai-harness'
+import type { MCPToolContext } from './server/context'
+
+/** 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.
+   */
+  approvals?: 'ask' | 'auto'
+  /** The MCP server name. Default: the harness name. */
+  name?: string
+  /** The MCP server version. Default `'1.0.0'`. */
+  version?: string
+}
+
+type Decision = { interruptId: string; approved: boolean }
+
+const threadIdSchema: JSONSchema = {
+  type: 'string',
+  description:
+    'The conversation id. Leave it out to use the default conversation.',
+}
+
+/**
+ * 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.
+ * Every tool takes an optional `threadId`. Sessions open with
+ * `host.open(harness, { threadId })`.
+ *
+ * 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, and the approval mode
+ *
+ * @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'
+  // 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,
+    })
+
+  async function decide(interrupts: Array<Interrupt>, context: MCPToolContext) {
+    if (approvals === 'auto') {
+      return interrupts.map((interrupt) => ({
+        interruptId: interrupt.id,
+        approved: true,
+      }))
+    }
+    const decisions: Array<Decision> = []
+    for (const interrupt of interrupts) {
+      try {
+        const answer = await context.requestInput({
+          message: approvalQuestion(interrupt),
+        })
+        decisions.push({ interruptId: interrupt.id, approved: 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 decisions
+  }
+
+  // Waits for the work. A chat turn that stops for approvals continues while
+  // the approval mode decides them.
+  async function finish(
+    session: HarnessSession,
+    work: Operation<unknown>,
+    workFrom: Cursor,
+    context: MCPToolContext,
+  ) {
+    let operation = work
+    let from = workFrom
+    while (true) {
+      const outcome = await settle(session, operation, from)
+      if (!outcome.done) {
+        waiting.set(outcome.questionId, operation)
+        return { status: 'waiting', ...pending(session) }
+      }
+      if (operation.kind !== 'chat') return outcome.value
+      const interrupts = session.snapshot().pendingInterrupts
+      const stopped =
+        operation.status() === 'interrupted' && interrupts.length > 0
+      const decisions = stopped ? await decide(interrupts, context) : undefined
+      if (decisions === undefined) {
+        return {
+          status: operation.status(),
+          text: turnText(outcome.value),
+          ...pending(session),
+        }
+      }
+      from = session.snapshot().cursor
+      operation = (await resolveAll(session, decisions)).turn
+    }
+  }
+
+  async function resume(
+    session: HarnessSession,
+    decisions: Array<Decision>,
+    context: MCPToolContext,
+  ) {
+    const from = session.snapshot().cursor
+    const { turn } = await resolveAll(session, decisions)
+    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
+    if (interrupts.length === 0) throw new Error('No approvals are waiting.')
+    const decisions = interrupts.map((interrupt) => ({
+      interruptId: interrupt.id,
+      approved,
+    }))
+    return resume(session, decisions, 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, and the approvals and questions that wait for you.',
+    inputSchema: withThreadId({
+      type: 'object',
+      properties: {
+        message: { type: 'string', description: 'The message.' },
+      },
+      required: ['message'],
+    }),
+  }).server<MCPToolContext>(async (args, ctx) => {
+    const session = await open(args)
+    const from = session.snapshot().cursor
+    const turn = session.prompt(textArg(args, '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.',
+    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.',
+    inputSchema: withThreadId(undefined),
+  }).server<MCPToolContext>(async (args, ctx) =>
+    decideAll(args, false, ctx.context),
+  )
+
+  const resolve = toolDefinition({
+    name: 'resolve',
+    description:
+      'Approve some tool calls and reject others, then wait for the turn to continue. Give one decision for each approval that waits.',
+    inputSchema: withThreadId({
+      type: 'object',
+      properties: {
+        decisions: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              interruptId: {
+                type: 'string',
+                description: 'The id of the approval.',
+              },
+              approved: { type: 'boolean' },
+            },
+            required: ['interruptId', 'approved'],
+          },
+        },
+      },
+      required: ['decisions'],
+    }),
+  }).server<MCPToolContext>(async (args, ctx) => {
+    const session = await open(args)
+    const decisions = decisionsOf(args)
+    const openIds = session.snapshot().pendingInterrupts.map(({ id }) => id)
+    const missing = openIds.filter(
+      (id) => !decisions.some((decision) => decision.interruptId === id),
+    )
+    if (missing.length > 0) {
+      throw new Error(
+        `resolve must answer every open approval. Missing: ${missing.join(', ')}.`,
+      )
+    }
+    const unknown = decisions
+      .map((decision) => decision.interruptId)
+      .filter((id) => !openIds.includes(id))
+    if (unknown.length > 0) {
+      throw new Error(`These approvals are not open: ${unknown.join(', ')}.`)
+    }
+    return resume(session, decisions, 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,
+      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 approvals 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 agentTools = exposed.flatMap((name) => {
+    const agent = session.registry.get(name)
+    if (agent === undefined) return []
+    const tool = toolDefinition({
+      name: toolName('agent', name),
+      description: agent.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)
+    })
+    return [tool]
+  })
+
+  const commandTools = session.describe().commands.map((command) =>
+    toolDefinition({
+      name: toolName('command', command.name),
+      description: command.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)
+    }),
+  )
+
+  return createMCPServer({
+    name: options.name ?? harness.name,
+    version: options.version ?? '1.0.0',
+    tools: [
+      chat,
+      steer,
+      cancel,
+      approve,
+      reject,
+      resolve,
+      answer,
+      status,
+      ...agentTools,
+      ...commandTools,
+    ],
+  })
+}
+
+// The harness needs one resolve that answers every open approval. An async
+// function waits for an operation that it returns, so the turn is wrapped.
+async function resolveAll(session: HarnessSession, decisions: Array<Decision>) {
+  const receipt = await session.resolve(
+    decisions.map((decision) => ({
+      interruptId: decision.interruptId,
+      status: 'resolved',
+      payload: decision.approved,
+    })),
+  )
+  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 {
+    approvals: snapshot.pendingInterrupts.map((interrupt) => ({
+      id: interrupt.id,
+      tool: interrupt.metadata?.toolName,
+      args: interrupt.metadata?.input,
+      message: interrupt.message,
+    })),
+    questions: snapshot.pendingQuestions.map(({ questionId, ...question }) => ({
+      id: questionId,
+      ...question,
+    })),
+  }
+}
+
+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 : ''
+}
+
+// MCP tool names allow letters, digits, and underscores, so `connect:notion`
+// becomes `command_connect_notion`.
+function toolName(prefix: string, name: string) {
+  return `${prefix}_${name.replace(/[^A-Za-z0-9_]/g, '_')}`
+}
+
+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' &&
+    typeof value.approved === 'boolean'
+  )
+}
+
+// `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/tests/harness.test.ts b/packages/ai-mcp/tests/harness.test.ts
new file mode 100644
index 0000000000..8e34780b6f
--- /dev/null
+++ b/packages/ai-mcp/tests/harness.test.ts
@@ -0,0 +1,490 @@
+import {
+  Client,
+  StreamableHTTPClientTransport,
+} from '@modelcontextprotocol/client'
+import { EventType, defineAgent, toolDefinition } from '@tanstack/ai'
+import {
+  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, ModelMessage, StreamChunk } from '@tanstack/ai'
+
+const serverUrl = new URL('https://harness.example.com/mcp')
+const now = () => Date.now()
+
+const pendingShape = z.object({
+  approvals: z.array(z.object({ id: z.string() })),
+  questions: z.array(z.object({ id: 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 asks to remove each path, one tool call per path. */
+function removeTurn(...paths: Array<string>): Array<StreamChunk> {
+  const calls = paths.flatMap(
+    (path, index): Array<StreamChunk> => [
+      {
+        type: EventType.TOOL_CALL_START,
+        toolCallId: `call-${index}`,
+        toolCallName: 'remove',
+        timestamp: now(),
+      },
+      {
+        type: EventType.TOOL_CALL_ARGS,
+        toolCallId: `call-${index}`,
+        delta: JSON.stringify({ path }),
+        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' } },
+    },
+  ]
+}
+
+/** 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 chunks = turns[calls.length] ?? textTurn('')
+      calls.push(options.messages)
+      return (async function* () {
+        yield* chunks
+      })()
+    },
+  }
+  return { adapter, calls }
+}
+
+function userTexts(messages: Array<ModelMessage> | undefined) {
+  return (messages ?? [])
+    .filter((message) => message.role === 'user')
+    .map((message) => message.content)
+}
+
+const pricer = defineAgent({
+  name: 'pricer',
+  description: 'Prices a vendor',
+  inputSchema: z.object({ vendor: z.string() }),
+  run: async (ctx) => `${ctx.input.vendor}: twelve dollars`,
+})
+
+const commands = definePlugin({
+  name: 'test/commands',
+  setup: (ctx) => ({
+    commands: {
+      'connect:notion': defineCommand({
+        description: 'Sign in to Notion',
+        run: () => 'Connected to Notion.',
+      }),
+      confirm: defineCommand({
+        description: 'Ask first',
+        run: async () => {
+          const sure = await ctx.session.ask({
+            message: 'Really?',
+            schema: { type: 'boolean' },
+          })
+          return sure === true ? 'Confirmed.' : 'Stopped.'
+        },
+      }),
+    },
+  }),
+})
+
+const cleanups: Array<() => Promise<unknown>> = []
+afterEach(async () => {
+  for (const cleanup of cleanups.splice(0).reverse()) await cleanup()
+})
+
+async function harnessServer(
+  turns: Array<Array<StreamChunk>>,
+  options: { approvals?: 'ask' | 'auto' } = {},
+) {
+  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}`
+  })
+  const harness = defineHarness({
+    name: 'test/mcp-harness',
+    adapter: model.adapter,
+    tools: [remove],
+    agents: [pricer],
+    expose: { agents: ['pricer'] },
+    plugins: () => [commands],
+  })
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  cleanups.push(() => host.close())
+  const server = await createHarnessMcpServer({ host, harness, ...options })
+  return { server, removed, calls: model.calls }
+}
+
+/**
+ * A real MCP client on `server.fetch`. With `answer`, the client supports
+ * elicitation and answers every question with it (spec 2025 sessions only).
+ */
+async function connect(
+  server: { fetch: (request: Request) => Promise<Response> },
+  options: { answer?: string } = {},
+) {
+  const answer = options.answer
+  const client = new Client(
+    { name: 'tester', version: '1.0.0' },
+    answer === undefined
+      ? { versionNegotiation: { mode: { pin: '2026-07-28' } } }
+      : { capabilities: { elicitation: { form: {} } } },
+  )
+  const asked: Array<string> = []
+  if (answer !== undefined) {
+    client.setRequestHandler('elicitation/create', async (request) => {
+      asked.push(request.params.message)
+      return { action: 'accept', content: { value: answer } }
+    })
+  }
+  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 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_pricer',
+      'answer',
+      'approve',
+      'cancel',
+      'chat',
+      'command_confirm',
+      'command_connect_notion',
+      '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')
+  })
+
+  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.',
+      approvals: [],
+      questions: [],
+    })
+  })
+
+  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: '',
+      approvals: [
+        {
+          id: expect.any(String),
+          tool: 'remove',
+          args: { path: 'a.txt' },
+          message: 'Approval required to run remove',
+        },
+      ],
+      questions: [],
+    })
+    expect(removed).toEqual([])
+
+    const status = await client.callTool({ name: 'status', arguments: {} })
+    expect(status.structuredContent).toMatchObject({
+      status: 'requires_action',
+      approvals: [{ tool: 'remove' }],
+      agents: [],
+      queuedTurns: 0,
+    })
+
+    const approved = await client.callTool({ name: 'approve', arguments: {} })
+    expect(approved.structuredContent).toEqual({
+      status: 'completed',
+      text: 'Removed a.txt.',
+      approvals: [],
+      questions: [],
+    })
+    expect(removed).toEqual(['a.txt'])
+  })
+
+  it('refuses a resolve that does not answer every open approval', 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 [first, second] = pendingShape.parse(
+      pending.structuredContent,
+    ).approvals
+    if (first === undefined || second === undefined) {
+      throw new Error('The turn did not stop for two approvals')
+    }
+
+    const partial = await client.callTool({
+      name: 'resolve',
+      arguments: { decisions: [{ interruptId: first.id, approved: true }] },
+    })
+    expect(partial.isError).toBe(true)
+    expect(partial.content).toEqual([
+      {
+        type: 'text',
+        text: `resolve must answer every open approval. Missing: ${second.id}.`,
+      },
+    ])
+    expect(removed).toEqual([])
+
+    const mixed = await client.callTool({
+      name: 'resolve',
+      arguments: {
+        decisions: [
+          { interruptId: first.id, approved: true },
+          { interruptId: second.id, approved: false },
+        ],
+      },
+    })
+    expect(mixed.structuredContent).toMatchObject({
+      status: 'completed',
+      text: 'Removed one file.',
+    })
+    expect(removed).toEqual(['a.txt'])
+  })
+
+  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.',
+      approvals: [],
+      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, { answer: '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('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',
+      approvals: [],
+      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('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('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('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'])
+  })
+})
diff --git a/packages/ai-mcp/vite.config.ts b/packages/ai-mcp/vite.config.ts
index 7fb331a0d9..a0d3ac34d4 100644
--- a/packages/ai-mcp/vite.config.ts
+++ b/packages/ai-mcp/vite.config.ts
@@ -32,6 +32,7 @@ export default mergeConfig(
       './src/server/index.ts',
       './src/server/stdio.ts',
       './src/connector.ts',
+      './src/harness.ts',
     ],
     srcDir: './src',
     cjs: false,

From c341668bba4f7c401f0f73d3e6e76e85b33e6ef9 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 17:39:18 +0200
Subject: [PATCH 051/286] feat(ai-harness-cli): add --mcp and --yes, and serve
 MCP at /mcp

--mcp serves the harness as an MCP server over stdio until stdin ends.
--yes approves every tool call in MCP mode. --serve also serves the MCP
server at /mcp behind the same bearer token. @tanstack/ai-mcp is an
optional peer with a clear error when it is missing.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-harness-cli/package.json      | 10 ++++-
 packages/ai-harness-cli/src/args.ts       | 10 ++++-
 packages/ai-harness-cli/src/index.ts      | 32 +++++++++++++-
 packages/ai-harness-cli/src/serve.ts      | 42 +++++++++++++-----
 packages/ai-harness-cli/tests/cli.test.ts | 52 +++++++++++++++++++++++
 pnpm-lock.yaml                            |  3 ++
 6 files changed, 135 insertions(+), 14 deletions(-)

diff --git a/packages/ai-harness-cli/package.json b/packages/ai-harness-cli/package.json
index b44a52097b..d4b508c774 100644
--- a/packages/ai-harness-cli/package.json
+++ b/packages/ai-harness-cli/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/ai-harness-cli",
   "version": "0.0.0",
-  "description": "Run a TanStack AI harness from the terminal: line mode or your own screen, print mode, NDJSON, ACP, and an HTTP server",
+  "description": "Run a TanStack AI harness from the terminal: line mode or your own screen, print mode, NDJSON, ACP, MCP, and an HTTP server",
   "author": "",
   "license": "MIT",
   "repository": {
@@ -63,13 +63,15 @@
     "agent",
     "cli",
     "terminal",
-    "acp"
+    "acp",
+    "mcp"
   ],
   "peerDependencies": {
     "@tanstack/ai": "workspace:^",
     "@tanstack/ai-acp": "workspace:^",
     "@tanstack/ai-dashboard": "workspace:^",
     "@tanstack/ai-harness": "workspace:^",
+    "@tanstack/ai-mcp": "workspace:^",
     "@tanstack/ai-persistence": "workspace:^"
   },
   "peerDependenciesMeta": {
@@ -78,6 +80,9 @@
     },
     "@tanstack/ai-dashboard": {
       "optional": true
+    },
+    "@tanstack/ai-mcp": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -85,6 +90,7 @@
     "@tanstack/ai-acp": "workspace:*",
     "@tanstack/ai-dashboard": "workspace:*",
     "@tanstack/ai-harness": "workspace:*",
+    "@tanstack/ai-mcp": "workspace:*",
     "@tanstack/ai-persistence": "workspace:*",
     "@tanstack/ai-sandbox": "workspace:*",
     "@vitest/coverage-v8": "4.1.10",
diff --git a/packages/ai-harness-cli/src/args.ts b/packages/ai-harness-cli/src/args.ts
index b62a8c5caa..aa9e0d06f8 100644
--- a/packages/ai-harness-cli/src/args.ts
+++ b/packages/ai-harness-cli/src/args.ts
@@ -5,6 +5,8 @@ export interface CliArgs {
   print?: string
   output: 'text' | 'ndjson'
   acp: boolean
+  mcp: boolean
+  yes: boolean
   serve: boolean
   port: number
   hostname: string
@@ -22,7 +24,9 @@ Options:
   -p, --print <prompt>   Run one prompt, print the answer, and exit
       --output <format>  Print format for --print: text (default) or ndjson
       --acp              Serve the harness as an ACP v2 agent over stdio
-      --serve            Serve the session protocol over HTTP
+      --mcp              Serve the harness as an MCP server over stdio
+      --yes              Approve every tool call in MCP mode (--mcp, and /mcp of --serve)
+      --serve            Serve the session protocol over HTTP (and MCP at /mcp, with @tanstack/ai-mcp)
       --port <port>      Port for --serve (default 8787)
       --host <name>      Host name for --serve (default 127.0.0.1)
       --token <token>    Bearer token for --serve (default: HARNESS_TOKEN, or a new random token)
@@ -41,6 +45,8 @@ export function parseCliArgs(argv: ReadonlyArray<string>): CliArgs {
       print: { type: 'string', short: 'p' },
       output: { type: 'string' },
       acp: { type: 'boolean' },
+      mcp: { type: 'boolean' },
+      yes: { type: 'boolean' },
       serve: { type: 'boolean' },
       port: { type: 'string' },
       host: { type: 'string' },
@@ -63,6 +69,8 @@ export function parseCliArgs(argv: ReadonlyArray<string>): CliArgs {
     ...(values.print !== undefined ? { print: values.print } : {}),
     output,
     acp: values.acp ?? false,
+    mcp: values.mcp ?? false,
+    yes: values.yes ?? false,
     serve: values.serve ?? false,
     port,
     hostname: values.host ?? '127.0.0.1',
diff --git a/packages/ai-harness-cli/src/index.ts b/packages/ai-harness-cli/src/index.ts
index 5eef2336a2..b2ef38b820 100644
--- a/packages/ai-harness-cli/src/index.ts
+++ b/packages/ai-harness-cli/src/index.ts
@@ -19,7 +19,7 @@ export interface RunCliOptions {
   /**
    * Your own screen for an interactive terminal, with any UI library. It gets
    * a ready session view and resolves when the user quits. Piped input and
-   * the other modes (`--print`, `--acp`, `--serve`, `--dashboard`) do not use it.
+   * the other modes (`--print`, `--acp`, `--mcp`, `--serve`, `--dashboard`) do not use it.
    */
   ui?: (view: SessionView) => Promise<void> | void
 }
@@ -59,6 +59,7 @@ export async function runCli(
   const host = createHarnessHost(
     options.persistence ? { persistence: options.persistence } : {},
   )
+  const approvals = args.yes ? 'auto' : 'ask'
   try {
     if (args.acp) {
       const { serveAcp } = await import('@tanstack/ai-acp/agent').catch(() => {
@@ -71,6 +72,33 @@ export async function runCli(
       return EXIT.ok
     }
 
+    if (args.mcp) {
+      const [{ createHarnessMcpServer }, { serveMCPStdio }] = await Promise.all(
+        [
+          import('@tanstack/ai-mcp/harness'),
+          import('@tanstack/ai-mcp/server/stdio'),
+        ],
+      ).catch(() => {
+        throw new Error(
+          '--mcp needs @tanstack/ai-mcp. Install it next to @tanstack/ai-harness-cli.',
+        )
+      })
+      const server = await createHarnessMcpServer({
+        host,
+        harness,
+        threadId: args.thread,
+        approvals,
+      })
+      // stdout carries only MCP messages. The server stops when stdin ends.
+      const ended = new Promise<void>((resolve) => {
+        process.stdin.once('end', resolve)
+      })
+      const stdio = serveMCPStdio(server)
+      await ended
+      await stdio.close()
+      return EXIT.ok
+    }
+
     if (args.dashboard) {
       const { connectDashboard } =
         await import('@tanstack/ai-dashboard/connect').catch(() => {
@@ -111,6 +139,8 @@ export async function runCli(
         port: args.port,
         hostname: args.hostname,
         token,
+        threadId: args.thread,
+        approvals,
       })
       stderr.write(`Serving ${harness.name} at ${server.url}\n`)
       if (!args.token && !env.HARNESS_TOKEN) stderr.write(`Token: ${token}\n`)
diff --git a/packages/ai-harness-cli/src/serve.ts b/packages/ai-harness-cli/src/serve.ts
index 71bd801804..944062f4ae 100644
--- a/packages/ai-harness-cli/src/serve.ts
+++ b/packages/ai-harness-cli/src/serve.ts
@@ -13,6 +13,22 @@ export interface ServeOptions {
   hostname: string
   /** Every request must send `Authorization: Bearer <token>`. */
   token: string
+  /** The conversation of an MCP tool call that names none. Default `'main'`. */
+  threadId?: string
+  /** How `/mcp` handles tool calls that need approval. Default `'ask'`. */
+  approvals?: 'ask' | 'auto'
+}
+
+/** The MCP server for `/mcp`, or `undefined` without `@tanstack/ai-mcp`. */
+async function mcpServer(options: ServeOptions) {
+  const mcp = await import('@tanstack/ai-mcp/harness').catch(() => undefined)
+  if (mcp === undefined) return undefined
+  return mcp.createHarnessMcpServer({
+    host: options.host,
+    harness: options.harness,
+    threadId: options.threadId,
+    approvals: options.approvals,
+  })
 }
 
 /** A random token for `--serve` when none is given. */
@@ -60,29 +76,35 @@ async function send(res: ServerResponse, response: Response): Promise<void> {
 
 /**
  * Serve the harness session protocol over HTTP (capabilities, run, events,
- * control, snapshot). Every request needs the bearer token.
+ * control, snapshot). With `@tanstack/ai-mcp` installed, `/mcp` serves the
+ * harness as an MCP server. Every request needs the bearer token.
  */
-export function serve(
+export async function serve(
   options: ServeOptions,
 ): Promise<{ url: string; close: () => Promise<void> }> {
+  const isAllowed = (request: Request) =>
+    sameToken(request.headers.get('authorization'), options.token)
   const handler = createHarnessHandler({
     host: options.host,
     harness: options.harness,
-    authorize: (request) =>
-      sameToken(request.headers.get('authorization'), options.token)
-        ? { id: 'cli' }
-        : null,
+    authorize: (request) => (isAllowed(request) ? { id: 'cli' } : null),
   })
+  const mcp = await mcpServer(options)
+  const route = (request: Request) => {
+    const isMcp = mcp !== undefined && new URL(request.url).pathname === '/mcp'
+    if (!isMcp) return handler(request)
+    if (!isAllowed(request)) {
+      return Response.json({ error: 'unauthorized' }, { status: 401 })
+    }
+    return mcp.fetch(request)
+  }
   const server = createServer((req, res) => {
     const aborter = new AbortController()
     res.on('close', () => aborter.abort())
     void (async () => {
       try {
         const base = `http://${req.headers.host ?? `${options.hostname}:${options.port}`}`
-        await send(
-          res,
-          await handler(await toRequest(req, base, aborter.signal)),
-        )
+        await send(res, await route(await toRequest(req, base, aborter.signal)))
       } catch (error) {
         if (!res.headersSent)
           res.writeHead(500, { 'Content-Type': 'application/json' })
diff --git a/packages/ai-harness-cli/tests/cli.test.ts b/packages/ai-harness-cli/tests/cli.test.ts
index ec83ad229b..93d7bea254 100644
--- a/packages/ai-harness-cli/tests/cli.test.ts
+++ b/packages/ai-harness-cli/tests/cli.test.ts
@@ -125,6 +125,14 @@ describe('parseCliArgs', () => {
     expect(() => parseCliArgs(['--output', 'xml'])).toThrow('--output')
     expect(() => parseCliArgs(['--nope'])).toThrow()
   })
+
+  it('reads --mcp and --yes, both off by default', () => {
+    expect(parseCliArgs(['--mcp', '--yes'])).toMatchObject({
+      mcp: true,
+      yes: true,
+    })
+    expect(parseCliArgs([])).toMatchObject({ mcp: false, yes: false })
+  })
 })
 
 describe('print mode', () => {
@@ -338,6 +346,50 @@ describe('serve mode', () => {
       await host.close()
     }
   })
+
+  it('serves the harness as an MCP server at /mcp behind the same token', async () => {
+    const { adapter } = scripted([])
+    const harness = defineHarness({ name: 'test/serve-mcp', adapter })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const server = await serve({
+      host,
+      harness,
+      port: 0,
+      hostname: '127.0.0.1',
+      token: 'secret',
+    })
+    const initialize = (headers: Record<string, string>) =>
+      fetch(`${server.url}/mcp`, {
+        method: 'POST',
+        headers: {
+          ...headers,
+          'content-type': 'application/json',
+          accept: 'application/json, text/event-stream',
+        },
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'initialize',
+          params: {
+            protocolVersion: '2025-11-25',
+            capabilities: {},
+            clientInfo: { name: 'raw', version: '1.0.0' },
+          },
+        }),
+      })
+    try {
+      const denied = await initialize({})
+      expect(denied.status).toBe(401)
+      const answered = await initialize({ authorization: 'Bearer secret' })
+      expect(answered.status).toBe(200)
+      expect((await answered.json()).result.serverInfo.name).toBe(
+        'test/serve-mcp',
+      )
+    } finally {
+      await server.close()
+      await host.close()
+    }
+  })
 })
 
 describe('custom ui', () => {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e7d01e934d..dc30e0890f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2705,6 +2705,9 @@ importers:
       '@tanstack/ai-harness':
         specifier: workspace:*
         version: link:../ai-harness
+      '@tanstack/ai-mcp':
+        specifier: workspace:*
+        version: link:../ai-mcp
       '@tanstack/ai-persistence':
         specifier: workspace:*
         version: link:../ai-persistence

From d66990e08679789ac3ef87dc20afe84dc75c7632 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 17:39:19 +0200
Subject: [PATCH 052/286] docs(harness): use a harness from any MCP client

New page docs/harness/mcp-server.md: the tools, harness --mcp with
claude mcp add and a JSON config, --yes, the /mcp route of --serve,
createHarnessMcpServer in your own server, approvals and elicitation.
Link it from the CLI and MCP connector pages, and add the changeset.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/harness-p14-mcp-server.md |   8 ++
 docs/config.json                     |   8 +-
 docs/harness/cli.md                  |  12 +-
 docs/harness/code-mode.md            |   2 +-
 docs/harness/coding-agents.md        |   2 +-
 docs/harness/custom-ui.md            |   2 +-
 docs/harness/dashboard.md            |   2 +-
 docs/harness/deploy.md               |   2 +-
 docs/harness/goal.md                 |   2 +-
 docs/harness/mcp-server.md           | 188 +++++++++++++++++++++++++++
 docs/harness/mcp.md                  |   2 +
 docs/harness/subagents.md            |   2 +-
 12 files changed, 221 insertions(+), 11 deletions(-)
 create mode 100644 .changeset/harness-p14-mcp-server.md
 create mode 100644 docs/harness/mcp-server.md

diff --git a/.changeset/harness-p14-mcp-server.md b/.changeset/harness-p14-mcp-server.md
new file mode 100644
index 0000000000..e2cb0e14a2
--- /dev/null
+++ b/.changeset/harness-p14-mcp-server.md
@@ -0,0 +1,8 @@
+---
+'@tanstack/ai-mcp': minor
+'@tanstack/ai-harness-cli': minor
+---
+
+`@tanstack/ai-mcp`: add `createHarnessMcpServer` at `@tanstack/ai-mcp/harness`. 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 plugin 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.
+
+`@tanstack/ai-harness-cli`: `--mcp` serves the harness as an MCP server over stdio, and `--yes` approves every tool call in MCP mode. `--serve` also serves MCP at `/mcp`, behind the same bearer token. Both need `@tanstack/ai-mcp`, which is an optional peer dependency.
diff --git a/docs/config.json b/docs/config.json
index 05716e0425..d74f1aeba1 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -907,7 +907,13 @@
         {
           "label": "Use MCP servers",
           "to": "harness/mcp",
-          "addedAt": "2026-09-26"
+          "addedAt": "2026-09-26",
+          "updatedAt": "2026-09-28"
+        },
+        {
+          "label": "Use from any MCP client",
+          "to": "harness/mcp-server",
+          "addedAt": "2026-09-28"
         },
         {
           "label": "Code mode in a harness",
diff --git a/docs/harness/cli.md b/docs/harness/cli.md
index 6184735ab4..cc45a4f81b 100644
--- a/docs/harness/cli.md
+++ b/docs/harness/cli.md
@@ -45,11 +45,17 @@ process.exitCode = await runCli(assistant)
 
 ## 2. Pick a mode
 
+To use the harness yourself:
+
 - No flags: line mode. Type a message and press Enter. With a `ui`, your own screen starts in its place (see [Run your own screen](#run-your-own-screen)).
 - `-p "prompt"`: run one prompt, print the answer, and exit.
 - `-p "prompt" --output ndjson`: print every AG-UI event as one JSON line.
+
+To use the harness from another program:
+
 - `--acp`: serve the harness as an ACP v2 agent over stdio, for editors. Needs `@tanstack/ai-acp`.
-- `--serve`: serve the session protocol over HTTP on `127.0.0.1:8787`. Every request needs the bearer token. Pass `--token`, set `HARNESS_TOKEN`, or copy the token the CLI prints.
+- `--mcp`: serve the harness as an MCP server over stdio, for Claude Code, Cursor, and other MCP clients. Needs `@tanstack/ai-mcp`. Add `--yes` to approve every tool call. Read [Use a harness from any MCP client](./mcp-server).
+- `--serve`: serve the session protocol over HTTP on `127.0.0.1:8787`. Every request needs the bearer token. Pass `--token`, set `HARNESS_TOKEN`, or copy the token the CLI prints. With `@tanstack/ai-mcp`, it also serves MCP at `/mcp`.
 
 Line mode reads one message or command per line and waits for each turn. It works the same in a terminal and with piped input. In a terminal, it also opens sign-in links in the browser.
 
@@ -100,7 +106,7 @@ process.exitCode = await runCli(assistant, {
 })
 ```
 
-- `ui` runs only in an interactive terminal. Piped input uses line mode. `-p`, `--acp`, `--serve`, and `--dashboard` do not use `ui`.
+- `ui` runs only in an interactive terminal. Piped input uses line mode. `-p`, `--acp`, `--mcp`, `--serve`, and `--dashboard` do not use `ui`.
 - When `ui` resolves, the CLI disposes the view and `runCli` returns.
 - To write `Screen`, read [Build your own UI](./custom-ui).
 
@@ -108,7 +114,7 @@ For a full Ink screen with approvals, questions, sign-ins, and child agents, cop
 
 ## What you have now
 
-- One entry file that runs your harness as a terminal app, a script step, an editor agent, or a server.
+- One entry file that runs your harness as a terminal app, a script step, an editor agent, an MCP server, or an HTTP server.
 - Your own terminal screen on the same session, with any TUI library.
 
 Next: keep long turns alive through crashes with [durable sessions](./durable-sessions).
diff --git a/docs/harness/code-mode.md b/docs/harness/code-mode.md
index c84a9e51fb..a73963b6f5 100644
--- a/docs/harness/code-mode.md
+++ b/docs/harness/code-mode.md
@@ -1,7 +1,7 @@
 ---
 title: Code mode in a harness
 id: harness-code-mode
-order: 9
+order: 10
 description: "Let the harness model write one TypeScript program that calls many tools, and run it in an isolate. Any TanStack AI isolate driver plugs in."
 keywords:
   - tanstack ai
diff --git a/docs/harness/coding-agents.md b/docs/harness/coding-agents.md
index 7f61e47424..94e65175c5 100644
--- a/docs/harness/coding-agents.md
+++ b/docs/harness/coding-agents.md
@@ -1,7 +1,7 @@
 ---
 title: Delegate to coding agents
 id: harness-coding-agents
-order: 10
+order: 11
 description: "Let a harness hand coding work to Claude Code, Codex, Grok Build, or any ACP agent. Each one works in a sandbox and keeps its own session."
 keywords:
   - tanstack ai
diff --git a/docs/harness/custom-ui.md b/docs/harness/custom-ui.md
index fcb7a6d3c8..aeedae39de 100644
--- a/docs/harness/custom-ui.md
+++ b/docs/harness/custom-ui.md
@@ -1,7 +1,7 @@
 ---
 title: Build your own UI
 id: harness-custom-ui
-order: 12
+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
diff --git a/docs/harness/dashboard.md b/docs/harness/dashboard.md
index e83f0630b8..f30c6f197c 100644
--- a/docs/harness/dashboard.md
+++ b/docs/harness/dashboard.md
@@ -1,7 +1,7 @@
 ---
 title: Self-host the dashboard
 id: harness-dashboard
-order: 15
+order: 16
 description: "Watch and steer your harness sessions from a browser or a phone. Agents dial out to your dashboard server, so they need no open port."
 keywords:
   - tanstack ai
diff --git a/docs/harness/deploy.md b/docs/harness/deploy.md
index f5d875f1f0..387381c432 100644
--- a/docs/harness/deploy.md
+++ b/docs/harness/deploy.md
@@ -1,7 +1,7 @@
 ---
 title: Deploy a harness
 id: harness-deploy
-order: 14
+order: 15
 description: "Run a harness in your server, as a worker process, on another machine, or as a single executable."
 keywords:
   - tanstack ai
diff --git a/docs/harness/goal.md b/docs/harness/goal.md
index 94601f9442..bdfb182d35 100644
--- a/docs/harness/goal.md
+++ b/docs/harness/goal.md
@@ -1,7 +1,7 @@
 ---
 title: Work until a goal is met
 id: harness-goal
-order: 11
+order: 12
 description: "Give the harness a goal, for example all tests pass. After each turn, a judge model checks the goal, and the harness keeps working until the goal is met."
 keywords:
   - tanstack ai
diff --git a/docs/harness/mcp-server.md b/docs/harness/mcp-server.md
new file mode 100644
index 0000000000..5412b95d64
--- /dev/null
+++ b/docs/harness/mcp-server.md
@@ -0,0 +1,188 @@
+---
+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. With `--mcp`, the CLI 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-cli @tanstack/ai-mcp
+vue: @tanstack/ai-harness-cli @tanstack/ai-mcp
+solid: @tanstack/ai-harness-cli @tanstack/ai-mcp
+svelte: @tanstack/ai-harness-cli @tanstack/ai-mcp
+preact: @tanstack/ai-harness-cli @tanstack/ai-mcp
+angular: @tanstack/ai-harness-cli @tanstack/ai-mcp
+octane: @tanstack/ai-harness-cli @tanstack/ai-mcp
+vanilla: @tanstack/ai-harness-cli @tanstack/ai-mcp
+
+<!-- ::end:tabs -->
+
+## 2. Add the harness to your client
+
+Start from the entry file in [Run a harness in the terminal](./cli). With `--mcp`, it reads MCP messages on stdin and writes the answers on stdout.
+
+For Claude Code, run this command one time:
+
+```bash
+claude mcp add --env OPENAI_API_KEY=your-key assistant -- npx tsx /path/to/cli.ts --mcp
+```
+
+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/cli.ts", "--mcp"],
+      "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.
+- `steer`: add a message to the running turn.
+- `cancel`: cancel the running turn.
+- `status`: show the status, the approvals and questions that wait, the background agents, and the queued turns.
+
+To answer the harness:
+
+- `approve` and `reject`: answer every approval that waits.
+- `resolve`: approve some tool calls and reject the others. Give one decision for each approval that waits.
+- `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 plugin command. The command `connect:notion` becomes the tool `command_connect_notion`.
+
+Every tool takes an optional `threadId`. Each thread is its own conversation. Without a `threadId`, a tool uses the `--thread` conversation (default `main`).
+
+`chat` answers with JSON:
+
+```json
+{
+  "status": "completed",
+  "text": "You have three open tickets.",
+  "approvals": [],
+  "questions": []
+}
+```
+
+## Approvals and questions
+
+A turn can stop for a tool call that needs approval. Then the client asks you in its own window (MCP elicitation). Answer `yes` to run the tool. Any other answer rejects it.
+
+If the client cannot ask you, `chat` returns the approvals with `status: "interrupted"`. The same happens when you close the question without an answer:
+
+```json
+{
+  "status": "interrupted",
+  "text": "",
+  "approvals": [
+    {
+      "id": "approval-1",
+      "tool": "remove",
+      "args": { "path": "old.log" },
+      "message": "Approval required to run remove"
+    }
+  ],
+  "questions": []
+}
+```
+
+Then the client calls `approve`, `reject`, or `resolve`. That call waits for the turn to continue and returns the same JSON as `chat`. `resolve` refuses a list that does not answer every approval.
+
+To approve every tool call without a question, start the CLI with `--yes`. Use it only with tools that you trust.
+
+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.
+
+## Serve MCP over HTTP
+
+If `@tanstack/ai-mcp` is installed, `--serve` also serves the MCP server at `/mcp`. The route uses the same bearer token as the other routes:
+
+```bash
+HARNESS_TOKEN=your-token npx tsx cli.ts --serve
+claude mcp add --transport http assistant http://127.0.0.1:8787/mcp --header "Authorization: Bearer your-token"
+```
+
+A request without the token gets a 401. `--yes` works on this route too.
+
+## Serve it from your own server
+
+To put the MCP server in your own app, use `createHarnessMcpServer`. It opens sessions on your host and returns a server with a `fetch` handler:
+
+```ts group=harness-mcp-server
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { createHarnessMcpServer } from '@tanstack/ai-mcp/harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { openaiText } from '@tanstack/ai-openai'
+
+const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-5.6'),
+})
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+
+export const server = await createHarnessMcpServer({
+  host,
+  harness: assistant,
+  threadId: 'main',
+  approvals: 'ask',
+})
+
+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)
+}
+```
+
+Mount `handleMcp` on a route, for example `/mcp`. The options are:
+
+- `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.
+- `name` and `version`: the MCP server name and version. Default: the harness name and `1.0.0`.
+
+For a process that a client starts, serve the same server on stdio:
+
+```ts group=harness-mcp-server
+import { serveMCPStdio } from '@tanstack/ai-mcp/server/stdio'
+
+serveMCPStdio(server)
+```
+
+## 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`, `reject`, and `resolve`.
+- The agents and commands of your harness as MCP tools.
+
+Next: put the harness on a server with [Deploy a harness](./deploy).
diff --git a/docs/harness/mcp.md b/docs/harness/mcp.md
index 52dff3f012..6e62f78d0b 100644
--- a/docs/harness/mcp.md
+++ b/docs/harness/mcp.md
@@ -15,6 +15,8 @@ keywords:
 
 Your agent needs to read the user's Linear issues and Notion pages. Both services run MCP servers that sign in with OAuth, so you do not register an app or copy an API key. `mcpConnector` adds `/connect linear`, keeps the token in your credential store, and gives the model the server's tools after sign-in.
 
+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 connectors
 
 <!-- ::start:tabs variant="package-manager" mode="install" -->
diff --git a/docs/harness/subagents.md b/docs/harness/subagents.md
index 5efc0a9b5e..0e33a72367 100644
--- a/docs/harness/subagents.md
+++ b/docs/harness/subagents.md
@@ -1,7 +1,7 @@
 ---
 title: Run agents from a harness
 id: harness-subagents
-order: 13
+order: 14
 description: "Start typed agents from commands and plugins, run them in groups, call a whole harness as a child, and keep the tree within limits."
 keywords:
   - tanstack ai

From e6f3fa2718911341a3133f70e69c23b7ab46ed56 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 18:15:12 +0200
Subject: [PATCH 053/286] test(ai-mcp): cover the connector branches after the
 v2 client move

The v2 MCP client saves the client information and keeps the refresh
token by itself. Because of this, some connector branches did not run
any more, and @tanstack/ai-mcp branch coverage fell 0.63 pp against
the base.

- Add tests for a sign-in that gives no refresh token, with and
  without an earlier sign-in.
- Add a test for a failed sign-in. The connector stays signed out.
- Run the refresh test with a saved redirect URI and with the
  fallback redirect URI.
- Run the revoked sign-in test for a revoked refresh token and for a
  revoked token that has no refresh token.
- Pin the default client name and the empty scope on a first sign-in.
- Move the mock model and the test browser into connector-helpers.ts,
  and remove the casts and the any type from the connector tests.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-mcp/tests/connector-edges.test.ts | 388 +++++++++---------
 packages/ai-mcp/tests/connector-helpers.ts    | 118 ++++++
 packages/ai-mcp/tests/connector.test.ts       | 198 +++------
 packages/ai-mcp/tests/protected-server.ts     |   7 +
 4 files changed, 386 insertions(+), 325 deletions(-)
 create mode 100644 packages/ai-mcp/tests/connector-helpers.ts

diff --git a/packages/ai-mcp/tests/connector-edges.test.ts b/packages/ai-mcp/tests/connector-edges.test.ts
index 7aa3b5e7c9..34b1f4d220 100644
--- a/packages/ai-mcp/tests/connector-edges.test.ts
+++ b/packages/ai-mcp/tests/connector-edges.test.ts
@@ -1,84 +1,16 @@
 import { afterEach, describe, expect, it } from 'vitest'
 import { EventType } from '@tanstack/ai'
 import { memoryPersistence } from '@tanstack/ai-persistence'
-import {
-  HARNESS_EVENTS,
-  createHarnessHost,
-  defineHarness,
-} from '@tanstack/ai-harness'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
 import { mcpConnector } from '../src/connector'
+import {
+  approveSignIns,
+  authorizationUrlOf,
+  recorder,
+} from './connector-helpers'
 import { startProtectedServer } from './protected-server'
-import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
-import type { SessionEvent } from '@tanstack/ai-harness'
-
-/** A model that records the tools it gets, calls `tool` once, then stops. */
-function recorder(tool?: string) {
-  const calls: Array<any> = []
-  const now = () => Date.now()
-  const adapter: AnyTextAdapter = {
-    kind: 'text',
-    name: 'mock',
-    model: 'mock',
-    '~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) => {
-      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: { name: string }) => entry.name)
-  return { adapter, calls, toolNames }
-}
+import type { Credential } from '@tanstack/ai-persistence'
+import type { HarnessSession, SessionEvent } from '@tanstack/ai-harness'
 
 const scope = { threadId: 't', userId: 'user-1' }
 const cleanups: Array<() => unknown> = []
@@ -86,11 +18,7 @@ afterEach(async () => {
   for (const cleanup of cleanups.splice(0).reverse()) await cleanup()
 })
 
-async function setup(
-  credential?: Parameters<
-    ReturnType<typeof memoryPersistence>['stores']['credentials']['set']
-  >[2],
-) {
+async function setup(credential?: Credential) {
   const server = await startProtectedServer()
   cleanups.push(() => server.close())
   const persistence = memoryPersistence()
@@ -101,6 +29,32 @@ async function setup(
   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 })],
+  })
+}
+
+/** 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
+}
+
 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({
@@ -115,103 +69,113 @@ describe('mcpConnector with a saved sign-in', () => {
       },
     })
     const model = recorder('demo_echo')
-    const session = await host.open(
-      defineHarness({
-        name: 'test/saved',
-        adapter: model.adapter,
-        plugins: () => [
-          mcpConnector({ id: 'demo', label: 'Demo', url: server.url }),
-        ],
-      }),
-      { threadId: 't', principal: { id: 'user-1' } },
-    )
+    const session = await host.open(connectorHarness(server.url, model), {
+      threadId: 't',
+      principal: { id: 'user-1' },
+    })
     await session.prompt('echo')
     expect(model.toolNames(0)).toEqual(['demo_echo'])
-    expect(JSON.stringify(model.calls[1].messages)).toContain('echo: hi')
+    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(
+    expect(JSON.stringify(model.calls[0]?.systemPrompts ?? [])).not.toContain(
       'is not connected',
     )
     expect(server.seen.registrations).toHaveLength(0)
   })
 
-  it('refreshes an expired token and keeps the old refresh token and client', async () => {
-    const { server, persistence, host } = await setup({
-      type: 'oauth',
-      accessToken: 'stale',
-      refreshToken: 'refresh-1',
-      expiresAt: Date.now() - 1000,
-      client: { clientId: 'client-1' },
-    })
-    const model = recorder('demo_echo')
-    const session = await host.open(
-      defineHarness({
-        name: 'test/refresh',
-        adapter: model.adapter,
-        plugins: () => [
-          mcpConnector({ id: 'demo', label: 'Demo', url: server.url }),
-        ],
-      }),
-      { threadId: 't', principal: { id: 'user-1' } },
-    )
-    await session.prompt('echo')
-    expect(model.toolNames(0)).toEqual(['demo_echo'])
-    expect(
-      server.seen.tokenRequests.some(
-        (form) => form.get('grant_type') === 'refresh_token',
-      ),
-    ).toBe(true)
-    expect(
-      await persistence.stores.credentials.get(scope, 'demo'),
-    ).toMatchObject({
-      accessToken: 'access-2',
-      refreshToken: 'refresh-1',
+  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 host.open(connectorHarness(server.url, model), {
+        threadId: 't',
+        principal: { id: 'user-1' },
+      })
+      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)
+      expect(await persistence.stores.credentials.get(scope, 'demo')).toEqual({
+        type: 'oauth',
+        accessToken: 'access-2',
+        refreshToken: 'refresh-1',
+        client: { clientId: 'client-1', redirectUri },
+      })
+    },
+  )
 
-  it('drops the tools with a warning when the sign-in no longer works', async () => {
-    const { server, host } = await setup({
-      type: 'oauth',
-      accessToken: 'stale',
-      refreshToken: 'revoked',
-    })
-    const model = recorder()
-    const session = await host.open(
-      defineHarness({
-        name: 'test/revoked',
-        adapter: model.adapter,
-        plugins: () => [
-          mcpConnector({ id: 'demo', label: 'Demo', url: server.url }),
-        ],
-      }),
-      { threadId: 't', principal: { id: 'user-1' } },
-    )
-    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('hi')
-    controller.abort()
-    await reading
-    expect(model.toolNames(0)).toEqual([])
-    const warning = seen.find(
-      (entry) =>
-        entry.event.type === EventType.CUSTOM &&
-        entry.event.name === 'harness.plugin.warning',
-    )
-    expect(warning?.event).toMatchObject({
-      value: { plugin: 'connector/demo' },
-    })
-  })
+  it.each([
+    {
+      failure: 'the refresh token is revoked',
+      credential: {
+        type: 'oauth',
+        accessToken: 'stale',
+        refreshToken: 'revoked',
+      },
+      revoke: [],
+    },
+    {
+      failure: 'the server revokes a token that has no refresh token',
+      credential: { type: 'oauth', accessToken: 'access-1' },
+      revoke: ['access-1'],
+    },
+  ] satisfies Array<{
+    failure: string
+    credential: Credential
+    revoke: Array<string>
+  }>)(
+    'drops the tools with a warning, and keeps the sign-in, when $failure',
+    async ({ credential, revoke }) => {
+      const { server, persistence, host } = await setup(credential)
+      for (const token of revoke) server.revoke(token)
+      const model = recorder()
+      const session = await host.open(connectorHarness(server.url, model), {
+        threadId: 't',
+        principal: { id: 'user-1' },
+      })
+      const seen = await promptAndCollect(session, 'hi')
+      expect(model.toolNames(0)).toEqual([])
+      const warning = seen.find(
+        (entry) =>
+          entry.event.type === EventType.CUSTOM &&
+          entry.event.name === 'harness.plugin.warning',
+      )
+      expect(warning?.event).toMatchObject({
+        value: { plugin: 'connector/demo' },
+      })
+      // Outside /connect, the connector never starts a browser sign-in.
+      expect(
+        seen.filter((entry) => authorizationUrlOf(entry.event) !== undefined),
+      ).toEqual([])
+      // Only /disconnect signs the user out.
+      expect(
+        await persistence.stores.credentials.get(scope, 'demo'),
+      ).toMatchObject({ type: 'oauth', accessToken: credential.accessToken })
+    },
+  )
 })
 
-describe('mcpConnector options', () => {
+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()
@@ -234,28 +198,11 @@ describe('mcpConnector options', () => {
       }),
       { threadId: 't', principal: { id: 'user-1' } },
     )
-    const controller = new AbortController()
-    let scopeParam: string | null = null
-    void (async () => {
-      for await (const entry of session.events({ signal: controller.signal })) {
-        const event = entry.event
-        if (
-          event.type !== EventType.CUSTOM ||
-          event.name !== HARNESS_EVENTS.authRequired
-        )
-          continue
-        const url = new URL(String((event.value as { url: string }).url))
-        scopeParam = url.searchParams.get('scope')
-        const redirect = new URL(url.searchParams.get('redirect_uri') ?? '')
-        redirect.searchParams.set('code', 'code-1')
-        redirect.searchParams.set('state', url.searchParams.get('state') ?? '')
-        await fetch(redirect)
-      }
-    })()
-    cleanups.push(() => controller.abort())
+    const browser = approveSignIns(session, 'code-1')
+    cleanups.push(browser.stop)
 
     expect(await session.command('connect:demo')).toBe('Connected to Demo.')
-    expect(scopeParam).toBe('read')
+    expect(browser.authorizationUrls[0]?.searchParams.get('scope')).toBe('read')
     expect(server.seen.registrations[0]).toMatchObject({
       client_name: 'Acme Agent',
       scope: 'read',
@@ -272,19 +219,70 @@ describe('mcpConnector options', () => {
 
     await session.prompt('hi')
     expect(model.toolNames(0)).toEqual(['d_echo'])
-    expect(model.calls[0].tools[0].needsApproval).toBe(true)
+    expect(model.calls[0]?.tools?.[0]?.needsApproval).toBe(true)
   })
-})
 
-describe('mcpConnector stored credential shapes', () => {
-  function connectorHarness(url: string, model: ReturnType<typeof recorder>) {
-    return defineHarness({
-      name: 'test/shapes',
-      adapter: model.adapter,
-      plugins: () => [mcpConnector({ id: 'demo', label: 'Demo', url })],
+  it.each([
+    { before: 'no earlier sign-in', earlier: undefined, kept: {} },
+    {
+      before: 'an earlier sign-in',
+      earlier: { type: 'oauth', accessToken: 'old', refreshToken: 'refresh-0' },
+      kept: { refreshToken: 'refresh-0' },
+    },
+  ] satisfies Array<{
+    before: string
+    earlier: Credential | undefined
+    kept: { refreshToken?: string }
+  }>)(
+    'saves a sign-in that gives no refresh token after $before',
+    async ({ earlier, kept }) => {
+      const { persistence, host, server } = await setup(earlier)
+      const session = await host.open(
+        connectorHarness(server.url, recorder()),
+        {
+          threadId: 't',
+          principal: { id: 'user-1' },
+        },
+      )
+      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, 'demo')).toEqual({
+        type: 'oauth',
+        accessToken: 'access-1',
+        ...kept,
+        client: {
+          clientId: 'client-1',
+          redirectUri: expect.stringMatching(/^http:\/\/127\.0\.0\.1:\d+\//),
+        },
+      })
+    },
+  )
+
+  it('stays signed out when the sign-in fails', async () => {
+    const { persistence, host, server } = await setup()
+    const model = recorder()
+    const session = await host.open(connectorHarness(server.url, model), {
+      threadId: 't',
+      principal: { id: 'user-1' },
     })
-  }
+    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, 'demo')).toBeNull()
+    await session.prompt('hi')
+    expect(JSON.stringify(model.calls[0]?.systemPrompts)).toContain(
+      'run /connect demo',
+    )
+    expect(model.toolNames(0)).toEqual([])
+  })
+})
 
+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',
diff --git a/packages/ai-mcp/tests/connector-helpers.ts b/packages/ai-mcp/tests/connector-helpers.ts
new file mode 100644
index 0000000000..a8c8131197
--- /dev/null
+++ b/packages/ai-mcp/tests/connector-helpers.ts
@@ -0,0 +1,118 @@
+import { EventType } from '@tanstack/ai'
+import { HARNESS_EVENTS } from '@tanstack/ai-harness'
+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) {
+  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)
+      redirect.searchParams.set(
+        'state',
+        authorizationUrl.searchParams.get('state') ?? '',
+      )
+      await fetch(redirect)
+    }
+  })()
+  return { authorizationUrls, stop: () => controller.abort() }
+}
diff --git a/packages/ai-mcp/tests/connector.test.ts b/packages/ai-mcp/tests/connector.test.ts
index 5e299a4115..e07021fb27 100644
--- a/packages/ai-mcp/tests/connector.test.ts
+++ b/packages/ai-mcp/tests/connector.test.ts
@@ -1,94 +1,41 @@
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it } from 'vitest'
 import { EventType } from '@tanstack/ai'
 import { memoryPersistence } from '@tanstack/ai-persistence'
-import {
-  HARNESS_EVENTS,
-  createHarnessHost,
-  defineHarness,
-} from '@tanstack/ai-harness'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
 import { mcpConnector } from '../src/connector'
+import { approveSignIns, mockTextAdapter, recorder } from './connector-helpers'
 import { startProtectedServer } from './protected-server'
-import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+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: Record<string, unknown>,
-): AnyTextAdapter {
+function modelCalling(tool: string, args: { text: string }) {
   let call = 0
   const now = () => Date.now()
-  return {
-    kind: 'text',
-    name: 'mock',
-    model: 'mock',
-    '~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) =>
-      (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)}`
+  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.TEXT_MESSAGE_START,
-          messageId: `m${call}`,
-          role: 'assistant',
+          type: EventType.TOOL_CALL_START,
+          toolCallId: 'c1',
+          toolCallName: tool,
           timestamp: now(),
         }
         yield {
-          type: EventType.TEXT_MESSAGE_CONTENT,
-          messageId: `m${call}`,
-          delta: text,
+          type: EventType.TOOL_CALL_ARGS,
+          toolCallId: 'c1',
+          delta: JSON.stringify(args),
           timestamp: now(),
         }
         yield {
-          type: EventType.TEXT_MESSAGE_END,
-          messageId: `m${call}`,
+          type: EventType.TOOL_CALL_END,
+          toolCallId: 'c1',
           timestamp: now(),
         }
         yield {
@@ -96,10 +43,38 @@ function modelCalling(
           runId: 'r',
           threadId: 't',
           timestamp: now(),
-          metadata: { tanstack: { finishReason: 'stop' } },
+          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> = []
@@ -125,37 +100,13 @@ describe('mcpConnector', () => {
       threadId: 't',
       principal: { id: 'user-1' },
     })
-
-    // Act as the browser: approve the sign-in by calling the loopback redirect.
-    const reader = new AbortController()
-    let authorizationUrl: URL | undefined
-    void (async () => {
-      for await (const entry of session.events({ signal: reader.signal })) {
-        const event = entry.event
-        if (
-          event.type === EventType.CUSTOM &&
-          event.name === HARNESS_EVENTS.authRequired
-        ) {
-          authorizationUrl = new URL(
-            String((event.value as { url: string }).url),
-          )
-          const redirect = new URL(
-            authorizationUrl.searchParams.get('redirect_uri') ?? '',
-          )
-          redirect.searchParams.set('code', 'code-1')
-          redirect.searchParams.set(
-            'state',
-            authorizationUrl.searchParams.get('state') ?? '',
-          )
-          await fetch(redirect)
-        }
-      }
-    })()
-    cleanups.push(() => reader.abort())
+    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',
@@ -164,7 +115,13 @@ describe('mcpConnector', () => {
       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()
@@ -180,6 +137,7 @@ describe('mcpConnector', () => {
       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.
@@ -197,34 +155,13 @@ describe('mcpConnector', () => {
   })
 
   it('tells the model to ask for /connect before sign-in', async () => {
-    const seen = vi.fn()
-    const adapter: AnyTextAdapter = {
-      ...modelCalling('x', {}),
-      chatStream: (options) => {
-        seen(options.systemPrompts)
-        return (async function* (): AsyncGenerator<StreamChunk> {
-          yield {
-            type: EventType.RUN_STARTED,
-            runId: 'r',
-            threadId: 't',
-            timestamp: Date.now(),
-          }
-          yield {
-            type: EventType.RUN_FINISHED,
-            runId: 'r',
-            threadId: 't',
-            timestamp: Date.now(),
-            metadata: { tanstack: { finishReason: 'stop' } },
-          }
-        })()
-      },
-    }
+    const model = recorder()
     const host = createHarnessHost({ persistence: memoryPersistence() })
     cleanups.push(() => host.close())
     const session = await host.open(
       defineHarness({
         name: 'test/mcp-connector-off',
-        adapter,
+        adapter: model.adapter,
         plugins: () => [
           mcpConnector({
             id: 'demo',
@@ -236,9 +173,10 @@ describe('mcpConnector', () => {
       { threadId: 't' },
     )
     await session.prompt('hi')
-    expect(JSON.stringify(seen.mock.calls[0]?.[0])).toContain(
+    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',
diff --git a/packages/ai-mcp/tests/protected-server.ts b/packages/ai-mcp/tests/protected-server.ts
index 93dc67e24d..cd24512590 100644
--- a/packages/ai-mcp/tests/protected-server.ts
+++ b/packages/ai-mcp/tests/protected-server.ts
@@ -22,6 +22,7 @@ function webHeaders(req: IncomingMessage) {
  * 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.
  */
@@ -82,6 +83,12 @@ export async function startProtectedServer() {
             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'

From d28914b0d905478d042a32216c122640548bbd95 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 18:23:51 +0200
Subject: [PATCH 054/286] fix(ai-mcp): concrete .d.ts import path, and cover
 the harness MCP server paths

The .d.ts of createHarnessMcpServer inlines the createMCPServer return
type. That type names MCPHandleOptions, and the emit picked the barrel
as './server.js', which does not resolve. Import createMCPServer from
'./server/index', so the emit writes './server/create-server.js'.

Add tests for the harness MCP server: reject, approve with no approval,
resolve with an unknown id or a harness refusal, answer refusals and a
question that no call waits on, elicitation "no" and decline, steer,
cancel, status with a running agent and a queued turn, errors from
commands, agents, and the model, a harness with no exposed agents, name
sanitizing, the server name and version, and the default thread.

The branches that stay uncovered in harness.ts are guards that the SDK
input check and defineHarness make unreachable. To keep the ai-mcp
coverage gate, also cover untested edges in pool (prefix '' and a
duplicate tool name), resources (a blob without a uri), prompts (a
message without content), and isMCPInputRequiredError (no kind). Remove
the casts and the computed expected values in the resources and prompts
tests.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-mcp/src/harness.ts               |   4 +-
 packages/ai-mcp/tests/harness.test.ts        | 534 +++++++++++++++++--
 packages/ai-mcp/tests/input-required.test.ts |   9 +
 packages/ai-mcp/tests/pool.test.ts           |  23 +
 packages/ai-mcp/tests/prompts.test.ts        |  52 +-
 packages/ai-mcp/tests/resources.test.ts      |  44 +-
 6 files changed, 584 insertions(+), 82 deletions(-)

diff --git a/packages/ai-mcp/src/harness.ts b/packages/ai-mcp/src/harness.ts
index 710e44424a..29850e8fee 100644
--- a/packages/ai-mcp/src/harness.ts
+++ b/packages/ai-mcp/src/harness.ts
@@ -4,7 +4,9 @@ import {
   toolDefinition,
 } from '@tanstack/ai'
 import { HARNESS_EVENTS } from '@tanstack/ai-harness'
-import { createMCPServer } from './server/create-server'
+// 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 } from './server/index'
 import type { Interrupt, JSONSchema } from '@tanstack/ai'
 import type {
   AnyHarness,
diff --git a/packages/ai-mcp/tests/harness.test.ts b/packages/ai-mcp/tests/harness.test.ts
index 8e34780b6f..0e36d203f8 100644
--- a/packages/ai-mcp/tests/harness.test.ts
+++ b/packages/ai-mcp/tests/harness.test.ts
@@ -4,6 +4,7 @@ import {
 } from '@modelcontextprotocol/client'
 import { EventType, defineAgent, toolDefinition } from '@tanstack/ai'
 import {
+  HARNESS_EVENTS,
   createHarnessHost,
   defineCommand,
   defineHarness,
@@ -14,6 +15,8 @@ import { afterEach, describe, expect, it } from 'vitest'
 import { z } from 'zod'
 import { createHarnessMcpServer } from '../src/harness'
 import type { AnyTextAdapter, 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()
@@ -23,6 +26,19 @@ const pendingShape = z.object({
   questions: z.array(z.object({ id: z.string() })),
 })
 
+const questionShape = z.object({ questionId: z.string() })
+
+const controlTools = [
+  'answer',
+  'approve',
+  'cancel',
+  'chat',
+  'reject',
+  'resolve',
+  'status',
+  'steer',
+]
+
 function textTurn(text: string): Array<StreamChunk> {
   return [
     {
@@ -58,6 +74,19 @@ function textTurn(text: string): Array<StreamChunk> {
   ]
 }
 
+/** 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>): Array<StreamChunk> {
   const calls = paths.flatMap(
@@ -99,8 +128,49 @@ function removeTurn(...paths: Array<string>): Array<StreamChunk> {
   ]
 }
 
+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<Array<StreamChunk>>) {
+function scripted(turns: Array<ScriptedTurn>) {
   const calls: Array<Array<ModelMessage>> = []
   const adapter: AnyTextAdapter = {
     kind: 'text',
@@ -123,11 +193,9 @@ function scripted(turns: Array<Array<StreamChunk>>) {
     },
     structuredOutput: async () => ({ data: {}, rawText: '{}' }),
     chatStream: (options) => {
-      const chunks = turns[calls.length] ?? textTurn('')
+      const turn = turns[calls.length] ?? textTurn('')
       calls.push(options.messages)
-      return (async function* () {
-        yield* chunks
-      })()
+      return play(turn)
     },
   }
   return { adapter, calls }
@@ -139,6 +207,28 @@ function userTexts(messages: Array<ModelMessage> | undefined) {
     .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 approvals that wait, from a tool result. */
+function approvalIds(result: { structuredContent?: unknown }) {
+  return pendingShape
+    .parse(result.structuredContent)
+    .approvals.map(({ id }) => id)
+}
+
+/** 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',
@@ -146,6 +236,14 @@ const pricer = defineAgent({
   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) => ({
@@ -154,6 +252,10 @@ const commands = definePlugin({
         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 () => {
@@ -164,6 +266,17 @@ const commands = definePlugin({
           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.')
+        },
+      }),
     },
   }),
 })
@@ -173,9 +286,18 @@ 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 }
+}
+
 async function harnessServer(
-  turns: Array<Array<StreamChunk>>,
-  options: { approvals?: 'ask' | 'auto' } = {},
+  turns: Array<ScriptedTurn>,
+  options: ServerOptions = {},
 ) {
   const model = scripted(turns)
   const removed: Array<string> = []
@@ -188,40 +310,57 @@ async function harnessServer(
     removed.push(path)
     return `removed ${path}`
   })
+  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],
-    agents: [pricer],
-    expose: { agents: ['pricer'] },
+    agents: [pricer, broken, waiter],
+    expose: { agents: ['pricer', 'broken', 'waiter'] },
     plugins: () => [commands],
   })
-  const host = createHarnessHost({ persistence: memoryPersistence() })
-  cleanups.push(() => host.close())
-  const server = await createHarnessMcpServer({ host, harness, ...options })
-  return { server, removed, calls: model.calls }
+  const { server, host } = await serve(harness, options)
+  const session = () => host.open(harness, { threadId: 'main' })
+  return { server, session, removed, 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 `answer`, the client supports
- * elicitation and answers every question with it (spec 2025 sessions only).
+ * 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: { answer?: string } = {},
+  options: { reply?: ElicitReply } = {},
 ) {
-  const answer = options.answer
+  const reply = options.reply
   const client = new Client(
     { name: 'tester', version: '1.0.0' },
-    answer === undefined
+    reply === undefined
       ? { versionNegotiation: { mode: { pin: '2026-07-28' } } }
       : { capabilities: { elicitation: { form: {} } } },
   )
   const asked: Array<string> = []
-  if (answer !== undefined) {
+  if (reply !== undefined) {
     client.setRequestHandler('elicitation/create', async (request) => {
       asked.push(request.params.message)
-      return { action: 'accept', content: { value: answer } }
+      return reply
     })
   }
   const transport = new StreamableHTTPClientTransport(serverUrl, {
@@ -239,13 +378,18 @@ describe('createHarnessMcpServer', () => {
 
     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',
@@ -261,8 +405,42 @@ describe('createHarnessMcpServer', () => {
       (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.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.'),
@@ -281,6 +459,17 @@ describe('createHarnessMcpServer', () => {
     })
   })
 
+  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'),
@@ -325,6 +514,35 @@ describe('createHarnessMcpServer', () => {
     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.',
+      approvals: [],
+      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 approval', async () => {
     const { server, removed } = await harnessServer([
       removeTurn('a.txt', 'b.txt'),
@@ -336,32 +554,25 @@ describe('createHarnessMcpServer', () => {
       name: 'chat',
       arguments: { message: 'remove both files' },
     })
-    const [first, second] = pendingShape.parse(
-      pending.structuredContent,
-    ).approvals
-    if (first === undefined || second === undefined) {
-      throw new Error('The turn did not stop for two approvals')
-    }
+    const ids = approvalIds(pending)
+    expect(ids).toHaveLength(2)
+    const [first, second] = ids
 
     const partial = await client.callTool({
       name: 'resolve',
-      arguments: { decisions: [{ interruptId: first.id, approved: true }] },
+      arguments: { decisions: [{ interruptId: first, approved: true }] },
     })
-    expect(partial.isError).toBe(true)
-    expect(partial.content).toEqual([
-      {
-        type: 'text',
-        text: `resolve must answer every open approval. Missing: ${second.id}.`,
-      },
-    ])
+    expect(partial).toMatchObject(
+      toolError(`resolve must answer every open approval. Missing: ${second}.`),
+    )
     expect(removed).toEqual([])
 
     const mixed = await client.callTool({
       name: 'resolve',
       arguments: {
         decisions: [
-          { interruptId: first.id, approved: true },
-          { interruptId: second.id, approved: false },
+          { interruptId: first, approved: true },
+          { interruptId: second, approved: false },
         ],
       },
     })
@@ -372,6 +583,44 @@ describe('createHarnessMcpServer', () => {
     expect(removed).toEqual(['a.txt'])
   })
 
+  it('refuses a resolve that names an approval 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] = approvalIds(pending)
+
+    const refused = await client.callTool({
+      name: 'resolve',
+      arguments: {
+        decisions: [
+          { interruptId: open, approved: true },
+          { interruptId: 'ghost', approved: true },
+        ],
+      },
+    })
+    expect(refused).toMatchObject(
+      toolError('These approvals 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.')],
@@ -397,7 +646,7 @@ describe('createHarnessMcpServer', () => {
       removeTurn('a.txt'),
       textTurn('Removed a.txt.'),
     ])
-    const { client, asked } = await connect(server, { answer: 'yes' })
+    const { client, asked } = await connect(server, { reply: accepted('yes') })
 
     const reply = await client.callTool({
       name: 'chat',
@@ -413,6 +662,44 @@ describe('createHarnessMcpServer', () => {
     ])
   })
 
+  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.',
+      approvals: [],
+      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',
+      approvals: [{ tool: 'remove', args: { path: 'a.txt' } }],
+    })
+    expect(asked).toHaveLength(1)
+    expect(removed).toEqual([])
+  })
+
   it('answer resolves the question of a command and returns its result', async () => {
     const { server } = await harnessServer([])
     const { client } = await connect(server)
@@ -442,6 +729,38 @@ describe('createHarnessMcpServer', () => {
     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',
+      approvals: [],
+      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)
@@ -455,6 +774,17 @@ describe('createHarnessMcpServer', () => {
     ])
   })
 
+  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)
@@ -468,6 +798,115 @@ describe('createHarnessMcpServer', () => {
     ])
   })
 
+  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',
+      approvals: [],
+      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'),
@@ -487,4 +926,25 @@ describe('createHarnessMcpServer', () => {
     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/input-required.test.ts b/packages/ai-mcp/tests/input-required.test.ts
index 0e40ef7f5d..5023e6307d 100644
--- a/packages/ai-mcp/tests/input-required.test.ts
+++ b/packages/ai-mcp/tests/input-required.test.ts
@@ -85,4 +85,13 @@ describe('MCPInputRequiredError', () => {
       }),
     ).toBe(false)
   })
+
+  it('rejects the shape without a kind', () => {
+    expect(
+      isMCPInputRequiredError({
+        name: 'MCPInputRequiredError',
+        request: { elicitationId: 'elicit-4' },
+      }),
+    ).toBe(false)
+  })
 })
diff --git a/packages/ai-mcp/tests/pool.test.ts b/packages/ai-mcp/tests/pool.test.ts
index bcf4c403b9..c0dd32ed60 100644
--- a/packages/ai-mcp/tests/pool.test.ts
+++ b/packages/ai-mcp/tests/pool.test.ts
@@ -4,6 +4,7 @@ import {
   SUPPORTED_PROTOCOL_VERSIONS,
 } from '@modelcontextprotocol/client'
 import { Server } from '@modelcontextprotocol/server'
+import { DuplicateToolNameError } from '../src/errors'
 import { createMCPClients } from '../src/pool'
 import {
   makeServerWithMismatchedResource,
@@ -25,6 +26,28 @@ describe('createMCPClients', () => {
     expect(names).toContain('beta_get_weather') // no collision despite same server tool name
   })
 
+  it("keeps the server tool names with prefix ''", async () => {
+    const a = await makeServerWithWeatherTool()
+    await using pool = await createMCPClients({
+      alpha: { transport: a.clientTransport, prefix: '' },
+    })
+    const names = (await pool.tools()).map((tool) => tool.name)
+    expect(names).toEqual(['get_weather'])
+    expect(pool.getServers()).toEqual({
+      alpha: { transport: undefined, prefix: undefined },
+    })
+  })
+
+  it('refuses two servers that give one tool name without a prefix', async () => {
+    const a = await makeServerWithWeatherTool()
+    const b = await makeServerWithWeatherTool()
+    await using pool = await createMCPClients({
+      alpha: { transport: a.clientTransport, prefix: '' },
+      beta: { transport: b.clientTransport, prefix: '' },
+    })
+    await expect(pool.tools()).rejects.toThrow(DuplicateToolNameError)
+  })
+
   it('exposes typed per-server access via .clients', async () => {
     const a = await makeServerWithWeatherTool()
     await using pool = await createMCPClients({
diff --git a/packages/ai-mcp/tests/prompts.test.ts b/packages/ai-mcp/tests/prompts.test.ts
index edf40ed3ba..c83bc65792 100644
--- a/packages/ai-mcp/tests/prompts.test.ts
+++ b/packages/ai-mcp/tests/prompts.test.ts
@@ -5,45 +5,46 @@ import { makeServerWithPrompt } from './helpers/in-memory-server'
 
 describe('mcpPromptToMessages', () => {
   it('converts a user text message correctly', () => {
-    const prompt = {
+    const messages = mcpPromptToMessages({
       messages: [{ role: 'user', content: { type: 'text', text: 'review x' } }],
-    }
-    const messages = mcpPromptToMessages(prompt)
+    })
 
-    expect(messages).toHaveLength(1)
-    expect(messages[0]!.role).toBe('user')
-    expect(messages[0]!.content).toBe('review x')
+    expect(messages).toEqual([{ role: 'user', content: 'review x' }])
   })
 
   it('maps assistant role correctly', () => {
-    const prompt = {
+    const messages = mcpPromptToMessages({
       messages: [
         { role: 'assistant', content: { type: 'text', text: 'looks good' } },
       ],
-    }
-    const messages = mcpPromptToMessages(prompt)
+    })
 
-    expect(messages[0]!.role).toBe('assistant')
-    expect(messages[0]!.content).toBe('looks good')
+    expect(messages).toEqual([{ role: 'assistant', content: 'looks good' }])
   })
 
   it('falls back to JSON.stringify for non-text content', () => {
     const content = { type: 'image', data: 'base64...' }
-    const prompt = {
+    const messages = mcpPromptToMessages({
       messages: [{ role: 'user', content }],
-    }
-    const messages = mcpPromptToMessages(prompt)
+    })
 
-    expect(messages[0]!.content).toBe(JSON.stringify(content))
+    expect(messages).toEqual([
+      { role: 'user', content: '{"type":"image","data":"base64..."}' },
+    ])
+  })
+
+  it('gives the text null for a message without content', () => {
+    const messages = mcpPromptToMessages({ messages: [{ role: 'user' }] })
+
+    expect(messages).toEqual([{ role: 'user', content: 'null' }])
   })
 
   it('treats unknown roles as user', () => {
-    const prompt = {
+    const messages = mcpPromptToMessages({
       messages: [{ role: 'system', content: { type: 'text', text: 'hi' } }],
-    }
-    const messages = mcpPromptToMessages(prompt)
+    })
 
-    expect(messages[0]!.role).toBe('user')
+    expect(messages).toEqual([{ role: 'user', content: 'hi' }])
   })
 })
 
@@ -53,13 +54,12 @@ describe('MCPClient prompts integration', () => {
       (await makeServerWithPrompt()).clientTransport,
     )
 
-    const list = await client.prompts()
-    expect(list.length).toBeGreaterThan(0)
-
-    const prompt = await client.getPrompt(list[0]!.name, { code: 'x = 1' })
-    const messages = mcpPromptToMessages(prompt)
+    const [listed] = await client.prompts()
+    if (listed === undefined) throw new Error('The server listed no prompt')
 
-    expect(messages[0]).toHaveProperty('role')
-    expect(messages[0]).toHaveProperty('content')
+    const prompt = await client.getPrompt(listed.name, { code: 'x = 1' })
+    expect(mcpPromptToMessages(prompt)).toEqual([
+      { role: 'user', content: 'Please review: x = 1' },
+    ])
   })
 })
diff --git a/packages/ai-mcp/tests/resources.test.ts b/packages/ai-mcp/tests/resources.test.ts
index 6abf1fdd89..4dca7333ef 100644
--- a/packages/ai-mcp/tests/resources.test.ts
+++ b/packages/ai-mcp/tests/resources.test.ts
@@ -6,8 +6,7 @@ import { makeServerWithResource } from './helpers/in-memory-server'
 describe('mcpResourceToContentPart', () => {
   it('converts a text content block to a TextPart', () => {
     const part = mcpResourceToContentPart({ uri: 'file:///x', text: 'hello' })
-    expect(part.type).toBe('text')
-    expect((part as { type: 'text'; content: string }).content).toBe('hello')
+    expect(part).toEqual({ type: 'text', content: 'hello' })
   })
 
   it('converts a blob content block to a TextPart with binary placeholder', () => {
@@ -15,22 +14,27 @@ describe('mcpResourceToContentPart', () => {
       uri: 'file:///img.png',
       blob: 'abc123',
     })
-    expect(part.type).toBe('text')
-    expect((part as { type: 'text'; content: string }).content).toBe(
-      '[binary resource file:///img.png]',
-    )
+    expect(part).toEqual({
+      type: 'text',
+      content: '[binary resource file:///img.png]',
+    })
+  })
+
+  it('leaves the uri out of the placeholder for a blob without a uri', () => {
+    const part = mcpResourceToContentPart({ blob: 'abc123' })
+    expect(part).toEqual({ type: 'text', content: '[binary resource ]' })
   })
 
   it('falls back to JSON.stringify for unknown content', () => {
-    const input = {
+    const part = mcpResourceToContentPart({
       uri: 'file:///unknown',
       mimeType: 'application/octet-stream',
-    }
-    const part = mcpResourceToContentPart(input)
-    expect(part.type).toBe('text')
-    expect((part as { type: 'text'; content: string }).content).toBe(
-      JSON.stringify(input),
-    )
+    })
+    expect(part).toEqual({
+      type: 'text',
+      content:
+        '{"uri":"file:///unknown","mimeType":"application/octet-stream"}',
+    })
   })
 })
 
@@ -40,11 +44,15 @@ describe('MCPClient resource methods (connected)', () => {
       (await makeServerWithResource()).clientTransport,
     )
 
-    const list = await client.resources()
-    expect(list.length).toBeGreaterThan(0)
+    const [listed] = await client.resources()
+    if (listed === undefined) throw new Error('The server listed no resource')
 
-    const read = await client.readResource(list[0]!.uri)
-    const part = mcpResourceToContentPart(read.contents[0]!)
-    expect(part.type).toBe('text')
+    const read = await client.readResource(listed.uri)
+    const [contents] = read.contents
+    if (contents === undefined) throw new Error('The resource has no contents')
+    expect(mcpResourceToContentPart(contents)).toEqual({
+      type: 'text',
+      content: 'hello from resource',
+    })
   })
 })

From 5945199247220f6bce4fa704585d58e146f2b159 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 18:45:47 +0200
Subject: [PATCH 055/286] fix(ai-mcp): answer each interrupt kind the right way
 in the harness MCP server, and keep tool names unique

The server answered every pending interrupt with true or false. A generic
middleware interrupt needs a value that matches its response schema, and a
client tool needs its output. The wrong answer failed the turn, and the
interrupt was lost.

- Read the kind from the interrupt binding: approval, client-tool, or
  generic.
- chat and status list every interrupt with its kind, tool, args, message,
  and responseSchema.
- approvals 'auto', inline elicitation, approve, and reject answer
  approvals only. When another kind is open, the turn comes back pending.
- resolve takes approved for an approval and payload for the others. It
  still answers every open interrupt in one call.

Two commands or agents could also get the same MCP tool name, and the
server then failed with HTTP 500. In name order, a later one now gets a
number (command_connect_notion_2), and its description names the original.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/harness-p14-mcp-server.md  |   2 +-
 docs/harness/mcp-server.md            |  68 +++-
 packages/ai-mcp/src/harness.ts        | 268 +++++++++++-----
 packages/ai-mcp/tests/harness.test.ts | 433 ++++++++++++++++++++++++--
 4 files changed, 644 insertions(+), 127 deletions(-)

diff --git a/.changeset/harness-p14-mcp-server.md b/.changeset/harness-p14-mcp-server.md
index e2cb0e14a2..91a5dceab1 100644
--- a/.changeset/harness-p14-mcp-server.md
+++ b/.changeset/harness-p14-mcp-server.md
@@ -3,6 +3,6 @@
 '@tanstack/ai-harness-cli': minor
 ---
 
-`@tanstack/ai-mcp`: add `createHarnessMcpServer` at `@tanstack/ai-mcp/harness`. 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 plugin 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.
+`@tanstack/ai-mcp`: add `createHarnessMcpServer` at `@tanstack/ai-mcp/harness`. 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 plugin 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. Each interrupt in a result has a `kind`: `approval`, `client-tool`, or `generic`. `resolve` answers every kind in one call: `approved` for an approval, and `payload` for the others.
 
 `@tanstack/ai-harness-cli`: `--mcp` serves the harness as an MCP server over stdio, and `--yes` approves every tool call in MCP mode. `--serve` also serves MCP at `/mcp`, behind the same bearer token. Both need `@tanstack/ai-mcp`, which is an optional peer dependency.
diff --git a/docs/harness/mcp-server.md b/docs/harness/mcp-server.md
index 5412b95d64..ff0af7099e 100644
--- a/docs/harness/mcp-server.md
+++ b/docs/harness/mcp-server.md
@@ -67,12 +67,12 @@ To talk to the harness:
 - `chat`: send a message and wait for the answer. While a turn runs, the message waits in the queue.
 - `steer`: add a message to the running turn.
 - `cancel`: cancel the running turn.
-- `status`: show the status, the approvals and questions that wait, the background agents, and the queued turns.
+- `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`: approve some tool calls and reject the others. Give one decision for each 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:
@@ -80,6 +80,8 @@ 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 plugin command. The command `connect:notion` becomes the tool `command_connect_notion`.
 
+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 `--thread` conversation (default `main`).
 
 `chat` answers with JSON:
@@ -88,36 +90,69 @@ Every tool takes an optional `threadId`. Each thread is its own conversation. Wi
 {
   "status": "completed",
   "text": "You have three open tickets.",
-  "approvals": [],
+  "interrupts": [],
   "questions": []
 }
 ```
 
-## Approvals and 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.
 
-A turn can stop for a tool call that needs approval. Then 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"`:
 
-If the client cannot ask you, `chat` returns the approvals with `status: "interrupted"`. The same happens when you close the question without an answer:
+- The client cannot ask you.
+- You close the question without an answer.
+- An interrupt of another kind also waits.
 
 ```json
 {
   "status": "interrupted",
-  "text": "",
-  "approvals": [
+  "text": "Here is the plan.",
+  "interrupts": [
     {
-      "id": "approval-1",
-      "tool": "remove",
-      "args": { "path": "old.log" },
-      "message": "Approval required to run remove"
+      "id": "interrupt-1",
+      "kind": "generic",
+      "message": "Review the plan",
+      "responseSchema": {
+        "type": "object",
+        "properties": { "note": { "type": "string" } },
+        "required": ["note"]
+      }
     }
   ],
   "questions": []
 }
 ```
 
-Then the client calls `approve`, `reject`, or `resolve`. That call waits for the turn to continue and returns the same JSON as `chat`. `resolve` refuses a list that does not answer every approval.
+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, start the CLI with `--yes`. Use it only with tools that you trust.
+To approve every tool call without a question, start the CLI with `--yes`. Use it only with tools that you trust. `--yes` 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.
 
@@ -168,7 +203,7 @@ export async function handleMcp(request: Request) {
 Mount `handleMcp` on a route, for example `/mcp`. The options are:
 
 - `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.
+- `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.
 - `name` and `version`: the MCP server name and version. Default: the harness name and `1.0.0`.
 
 For a process that a client starts, serve the same server on stdio:
@@ -182,7 +217,8 @@ serveMCPStdio(server)
 ## 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`, `reject`, and `resolve`.
+- 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.
 
 Next: put the harness on a server with [Deploy a harness](./deploy).
diff --git a/packages/ai-mcp/src/harness.ts b/packages/ai-mcp/src/harness.ts
index 29850e8fee..11a330212d 100644
--- a/packages/ai-mcp/src/harness.ts
+++ b/packages/ai-mcp/src/harness.ts
@@ -1,6 +1,7 @@
 import {
   EventType,
   convertSchemaToJsonSchema,
+  readUnopenedInterruptBinding,
   toolDefinition,
 } from '@tanstack/ai'
 import { HARNESS_EVENTS } from '@tanstack/ai-harness'
@@ -31,6 +32,10 @@ export interface HarnessMcpServerOptions {
    *   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 MCP server name. Default: the harness name. */
@@ -39,7 +44,11 @@ export interface HarnessMcpServerOptions {
   version?: string
 }
 
-type Decision = { interruptId: string; approved: boolean }
+/** 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 }
 
 const threadIdSchema: JSONSchema = {
   type: 'string',
@@ -57,6 +66,10 @@ const threadIdSchema: JSONSchema = {
  * 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.
+ *
  * The result is the server from `createMCPServer`. Mount `server.fetch` on
  * an HTTP route, or pass the server to `serveMCPStdio`.
  *
@@ -83,27 +96,31 @@ export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
           : 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,
-        approved: true,
+        payload: true,
       }))
     }
-    const decisions: Array<Decision> = []
+    const answers: Array<Answer> = []
     for (const interrupt of interrupts) {
       try {
         const answer = await context.requestInput({
           message: approvalQuestion(interrupt),
         })
-        decisions.push({ interruptId: interrupt.id, approved: isYes(answer) })
+        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 decisions
+    return answers
   }
 
   // Waits for the work. A chat turn that stops for approvals continues while
@@ -126,8 +143,8 @@ export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
       const interrupts = session.snapshot().pendingInterrupts
       const stopped =
         operation.status() === 'interrupted' && interrupts.length > 0
-      const decisions = stopped ? await decide(interrupts, context) : undefined
-      if (decisions === undefined) {
+      const answers = stopped ? await decide(interrupts, context) : undefined
+      if (answers === undefined) {
         return {
           status: operation.status(),
           text: turnText(outcome.value),
@@ -135,17 +152,17 @@ export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
         }
       }
       from = session.snapshot().cursor
-      operation = (await resolveAll(session, decisions)).turn
+      operation = (await resolveAll(session, answers)).turn
     }
   }
 
   async function resume(
     session: HarnessSession,
-    decisions: Array<Decision>,
+    answers: Array<Answer>,
     context: MCPToolContext,
   ) {
     const from = session.snapshot().cursor
-    const { turn } = await resolveAll(session, decisions)
+    const { turn } = await resolveAll(session, answers)
     return finish(session, turn, from, context)
   }
 
@@ -156,18 +173,22 @@ export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
   ) {
     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 decisions = interrupts.map((interrupt) => ({
+    const answers = interrupts.map((interrupt) => ({
       interruptId: interrupt.id,
-      approved,
+      payload: approved,
     }))
-    return resume(session, decisions, context)
+    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, and the approvals and questions that wait for you.',
+      '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, and the interrupts and questions that wait for you.',
     inputSchema: withThreadId({
       type: 'object',
       properties: {
@@ -204,7 +225,7 @@ export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
   const approve = toolDefinition({
     name: 'approve',
     description:
-      'Approve every tool call that waits for approval, then wait for the turn to continue.',
+      '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),
@@ -213,7 +234,7 @@ export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
   const reject = toolDefinition({
     name: 'reject',
     description:
-      'Reject every tool call that waits for approval, then wait for the turn to continue.',
+      '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),
@@ -222,7 +243,7 @@ export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
   const resolve = toolDefinition({
     name: 'resolve',
     description:
-      'Approve some tool calls and reject others, then wait for the turn to continue. Give one decision for each approval that waits.',
+      '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: {
@@ -233,11 +254,19 @@ export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
             properties: {
               interruptId: {
                 type: 'string',
-                description: 'The id of the approval.',
+                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.',
               },
-              approved: { type: 'boolean' },
             },
-            required: ['interruptId', 'approved'],
+            required: ['interruptId'],
           },
         },
       },
@@ -245,23 +274,9 @@ export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
     }),
   }).server<MCPToolContext>(async (args, ctx) => {
     const session = await open(args)
-    const decisions = decisionsOf(args)
-    const openIds = session.snapshot().pendingInterrupts.map(({ id }) => id)
-    const missing = openIds.filter(
-      (id) => !decisions.some((decision) => decision.interruptId === id),
-    )
-    if (missing.length > 0) {
-      throw new Error(
-        `resolve must answer every open approval. Missing: ${missing.join(', ')}.`,
-      )
-    }
-    const unknown = decisions
-      .map((decision) => decision.interruptId)
-      .filter((id) => !openIds.includes(id))
-    if (unknown.length > 0) {
-      throw new Error(`These approvals are not open: ${unknown.join(', ')}.`)
-    }
-    return resume(session, decisions, ctx.context)
+    const interrupts = session.snapshot().pendingInterrupts
+    const answers = answersOf(decisionsOf(args), interrupts)
+    return resume(session, answers, ctx.context)
   })
 
   const answer = toolDefinition({
@@ -301,7 +316,7 @@ export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
   const status = toolDefinition({
     name: 'status',
     description:
-      'Show what the harness does now: the status, the approvals and questions that wait, the background agents, and the queued turns.',
+      '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)
@@ -320,36 +335,42 @@ export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
   const session = await host.open(harness, { threadId: defaultThread })
 
   const exposed: ReadonlyArray<string> = harness.expose?.agents ?? []
-  const agentTools = exposed.flatMap((name) => {
+  const agents = exposed.flatMap((name) => {
     const agent = session.registry.get(name)
-    if (agent === undefined) return []
-    const tool = toolDefinition({
-      name: toolName('agent', name),
-      description: agent.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)
-    })
-    return [tool]
+    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)
+      }),
+  )
 
-  const commandTools = session.describe().commands.map((command) =>
-    toolDefinition({
-      name: toolName('command', command.name),
-      description: command.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)
-    }),
+  const commands = session.describe().commands
+  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)
+      }),
   )
 
   return createMCPServer({
@@ -370,15 +391,11 @@ export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
   })
 }
 
-// The harness needs one resolve that answers every open approval. An async
+// 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, decisions: Array<Decision>) {
+async function resolveAll(session: HarnessSession, answers: Array<Answer>) {
   const receipt = await session.resolve(
-    decisions.map((decision) => ({
-      interruptId: decision.interruptId,
-      status: 'resolved',
-      payload: decision.approved,
-    })),
+    answers.map((answer) => ({ ...answer, status: 'resolved' })),
   )
   const operation =
     receipt.operationId === undefined
@@ -439,11 +456,13 @@ async function questionAfter(
 function pending(session: HarnessSession) {
   const snapshot = session.snapshot()
   return {
-    approvals: snapshot.pendingInterrupts.map((interrupt) => ({
+    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,
@@ -452,6 +471,67 @@ function pending(session: HarnessSession) {
   }
 }
 
+/**
+ * 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)}.`
@@ -467,10 +547,42 @@ function turnText(value: unknown) {
   return isRecord(value) && typeof value.text === 'string' ? value.text : ''
 }
 
-// MCP tool names allow letters, digits, and underscores, so `connect:notion`
-// becomes `command_connect_notion`.
-function toolName(prefix: string, name: string) {
-  return `${prefix}_${name.replace(/[^A-Za-z0-9_]/g, '_')}`
+/**
+ * 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) {
@@ -504,7 +616,7 @@ function isDecision(value: unknown): value is Decision {
   return (
     isRecord(value) &&
     typeof value.interruptId === 'string' &&
-    typeof value.approved === 'boolean'
+    (value.approved === undefined || typeof value.approved === 'boolean')
   )
 }
 
diff --git a/packages/ai-mcp/tests/harness.test.ts b/packages/ai-mcp/tests/harness.test.ts
index 0e36d203f8..39681af237 100644
--- a/packages/ai-mcp/tests/harness.test.ts
+++ b/packages/ai-mcp/tests/harness.test.ts
@@ -2,7 +2,13 @@ import {
   Client,
   StreamableHTTPClientTransport,
 } from '@modelcontextprotocol/client'
-import { EventType, defineAgent, toolDefinition } from '@tanstack/ai'
+import {
+  EventType,
+  defineAgent,
+  defineChatMiddleware,
+  defineInterrupt,
+  toolDefinition,
+} from '@tanstack/ai'
 import {
   HARNESS_EVENTS,
   createHarnessHost,
@@ -14,7 +20,12 @@ 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, ModelMessage, StreamChunk } from '@tanstack/ai'
+import type {
+  AnyTextAdapter,
+  InterruptBoundaryPhase,
+  ModelMessage,
+  StreamChunk,
+} from '@tanstack/ai'
 import type { AnyHarness, HarnessSession } from '@tanstack/ai-harness'
 import type { HarnessMcpServerOptions } from '../src/harness'
 
@@ -22,10 +33,49 @@ const serverUrl = new URL('https://harness.example.com/mcp')
 const now = () => Date.now()
 
 const pendingShape = z.object({
-  approvals: z.array(z.object({ id: z.string() })),
+  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 = [
@@ -88,19 +138,28 @@ function errorTurn(message: string): Array<StreamChunk> {
 }
 
 /** One model call that asks to remove each path, one tool call per path. */
-function removeTurn(...paths: Array<string>): Array<StreamChunk> {
-  const calls = paths.flatMap(
-    (path, index): Array<StreamChunk> => [
+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: 'remove',
+        toolCallName: name,
         timestamp: now(),
       },
       {
         type: EventType.TOOL_CALL_ARGS,
         toolCallId: `call-${index}`,
-        delta: JSON.stringify({ path }),
+        delta: JSON.stringify(input),
         timestamp: now(),
       },
       {
@@ -212,11 +271,40 @@ function toolError(message: string) {
   return { isError: true, content: [{ type: 'text', text: message }] }
 }
 
-/** The ids of the approvals that wait, from a tool result. */
-function approvalIds(result: { structuredContent?: unknown }) {
+/** The ids of the interrupts that wait, from a tool result. */
+function interruptIds(result: { structuredContent?: unknown }) {
   return pendingShape
     .parse(result.structuredContent)
-    .approvals.map(({ id }) => id)
+    .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. */
@@ -295,10 +383,15 @@ async function serve(harness: AnyHarness, options: ServerOptions = {}) {
   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 = {},
+  options: ServerOptions & { reviewAt?: InterruptBoundaryPhase } = {},
 ) {
+  const { reviewAt: phase, ...serverOptions } = options
   const model = scripted(turns)
   const removed: Array<string> = []
   const remove = toolDefinition({
@@ -310,6 +403,14 @@ async function harnessServer(
     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',
@@ -322,14 +423,24 @@ async function harnessServer(
   const harness = defineHarness({
     name: 'test/mcp-harness',
     adapter: model.adapter,
-    tools: [remove],
+    tools: [remove, pickColor],
     agents: [pricer, broken, waiter],
     expose: { agents: ['pricer', 'broken', 'waiter'] },
     plugins: () => [commands],
+    ...(reviewer === undefined
+      ? {}
+      : { middleware: [reviewer.middleware], interrupts: [review] }),
   })
-  const { server, host } = await serve(harness, options)
+  const { server, host } = await serve(harness, serverOptions)
   const session = () => host.open(harness, { threadId: 'main' })
-  return { server, session, removed, calls: model.calls, agentHold }
+  return {
+    server,
+    session,
+    removed,
+    notes: reviewer?.notes ?? [],
+    calls: model.calls,
+    agentHold,
+  }
 }
 
 type ElicitReply =
@@ -422,6 +533,61 @@ describe('createHarnessMcpServer', () => {
     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],
+      }),
+    )
+    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.each([
     {
       options: {},
@@ -454,7 +620,7 @@ describe('createHarnessMcpServer', () => {
     expect(reply.structuredContent).toEqual({
       status: 'completed',
       text: 'Hello from the harness.',
-      approvals: [],
+      interrupts: [],
       questions: [],
     })
   })
@@ -484,12 +650,14 @@ describe('createHarnessMcpServer', () => {
     expect(pending.structuredContent).toEqual({
       status: 'interrupted',
       text: '',
-      approvals: [
+      interrupts: [
         {
           id: expect.any(String),
+          kind: 'approval',
           tool: 'remove',
           args: { path: 'a.txt' },
           message: 'Approval required to run remove',
+          responseSchema: removeApprovalSchema,
         },
       ],
       questions: [],
@@ -499,7 +667,7 @@ describe('createHarnessMcpServer', () => {
     const status = await client.callTool({ name: 'status', arguments: {} })
     expect(status.structuredContent).toMatchObject({
       status: 'requires_action',
-      approvals: [{ tool: 'remove' }],
+      interrupts: [{ kind: 'approval', tool: 'remove' }],
       agents: [],
       queuedTurns: 0,
     })
@@ -508,7 +676,7 @@ describe('createHarnessMcpServer', () => {
     expect(approved.structuredContent).toEqual({
       status: 'completed',
       text: 'Removed a.txt.',
-      approvals: [],
+      interrupts: [],
       questions: [],
     })
     expect(removed).toEqual(['a.txt'])
@@ -529,7 +697,7 @@ describe('createHarnessMcpServer', () => {
     expect(rejected.structuredContent).toEqual({
       status: 'completed',
       text: 'Kept a.txt.',
-      approvals: [],
+      interrupts: [],
       questions: [],
     })
     expect(removed).toEqual([])
@@ -543,7 +711,7 @@ describe('createHarnessMcpServer', () => {
     expect(refused).toMatchObject(toolError('No approvals are waiting.'))
   })
 
-  it('refuses a resolve that does not answer every open approval', async () => {
+  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.'),
@@ -554,7 +722,7 @@ describe('createHarnessMcpServer', () => {
       name: 'chat',
       arguments: { message: 'remove both files' },
     })
-    const ids = approvalIds(pending)
+    const ids = interruptIds(pending)
     expect(ids).toHaveLength(2)
     const [first, second] = ids
 
@@ -563,7 +731,9 @@ describe('createHarnessMcpServer', () => {
       arguments: { decisions: [{ interruptId: first, approved: true }] },
     })
     expect(partial).toMatchObject(
-      toolError(`resolve must answer every open approval. Missing: ${second}.`),
+      toolError(
+        `resolve must answer every open interrupt. Missing: ${second}.`,
+      ),
     )
     expect(removed).toEqual([])
 
@@ -583,7 +753,7 @@ describe('createHarnessMcpServer', () => {
     expect(removed).toEqual(['a.txt'])
   })
 
-  it('refuses a resolve that names an approval that is not open', async () => {
+  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)
 
@@ -591,7 +761,7 @@ describe('createHarnessMcpServer', () => {
       name: 'chat',
       arguments: { message: 'remove a.txt' },
     })
-    const [open] = approvalIds(pending)
+    const [open] = interruptIds(pending)
 
     const refused = await client.callTool({
       name: 'resolve',
@@ -603,7 +773,7 @@ describe('createHarnessMcpServer', () => {
       },
     })
     expect(refused).toMatchObject(
-      toolError('These approvals are not open: ghost.'),
+      toolError('These interrupts are not open: ghost.'),
     )
     expect(removed).toEqual([])
   })
@@ -635,7 +805,7 @@ describe('createHarnessMcpServer', () => {
     expect(reply.structuredContent).toEqual({
       status: 'completed',
       text: 'Removed a.txt.',
-      approvals: [],
+      interrupts: [],
       questions: [],
     })
     expect(removed).toEqual(['a.txt'])
@@ -676,7 +846,7 @@ describe('createHarnessMcpServer', () => {
     expect(reply.structuredContent).toEqual({
       status: 'completed',
       text: 'Kept a.txt.',
-      approvals: [],
+      interrupts: [],
       questions: [],
     })
     expect(removed).toEqual([])
@@ -694,12 +864,211 @@ describe('createHarnessMcpServer', () => {
     })
     expect(reply.structuredContent).toMatchObject({
       status: 'interrupted',
-      approvals: [{ tool: 'remove', args: { path: 'a.txt' } }],
+      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)
@@ -710,7 +1079,7 @@ describe('createHarnessMcpServer', () => {
     })
     expect(waiting.structuredContent).toEqual({
       status: 'waiting',
-      approvals: [],
+      interrupts: [],
       questions: [
         {
           id: expect.any(String),
@@ -742,7 +1111,7 @@ describe('createHarnessMcpServer', () => {
     })
     expect(answered.structuredContent).toEqual({
       status: 'answered',
-      approvals: [],
+      interrupts: [],
       questions: [],
     })
     expect(await confirm).toBe('Confirmed.')
@@ -897,7 +1266,7 @@ describe('createHarnessMcpServer', () => {
     const status = await client.callTool({ name: 'status', arguments: {} })
     expect(status.structuredContent).toEqual({
       status: 'running',
-      approvals: [],
+      interrupts: [],
       questions: [],
       agents: [{ id: expect.any(String), agent: 'waiter' }],
       queuedTurns: 1,

From c480fc3fcbc886c2bcc9659a8d42aadbeb54e237 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 28 Sep 2026 19:12:48 +0200
Subject: [PATCH 056/286] fix(ai-mcp): connector sign-in replaces old tokens,
 clear auth errors, no SEP-2352 warnings

- A new /connect saves only its own tokens. It does not keep the
  refresh token of an earlier sign-in any more. On a refresh, the v2
  client keeps the old refresh token itself.
- When the server wants a new sign-in, the connector publishes
  harness.auth_required, the plugin warning says "Sign in to <id>
  first. Run /connect <id>.", and the status prompt asks for /connect.
  Other connection failures stay "Failed to connect to MCP server".
- invalidateCredentials deletes the saved sign-in when the server
  refuses the saved client or refresh token (invalid_grant). A failed
  /connect keeps the earlier sign-in.
- The saved client keeps the issuer of the authorization server, and
  the provider keeps the discovery state next to the code verifier.
  The v2 client prints no SEP-2352 warning on /connect or on a refresh.
- Remove the branches that only the v1 client needed: redirectUri is
  a required string, state narrows without a fallback, and /connect
  does not check the result of the first auth() call.
- @tanstack/ai-persistence: Credential.client gets an optional issuer.
- docs/harness/mcp.md: what happens when the server no longer accepts
  the sign-in.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 docs/harness/mcp.md                           |   3 +
 packages/ai-mcp/src/connector.ts              | 163 ++++++-----
 packages/ai-mcp/tests/connector-edges.test.ts | 277 ++++++++++++------
 packages/ai-mcp/tests/protected-server.ts     |   2 +
 packages/ai-persistence/src/types.ts          |  10 +-
 5 files changed, 286 insertions(+), 169 deletions(-)

diff --git a/docs/harness/mcp.md b/docs/harness/mcp.md
index 6e62f78d0b..a9fe622a20 100644
--- a/docs/harness/mcp.md
+++ b/docs/harness/mcp.md
@@ -71,8 +71,11 @@ 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.
 
 ## 3. Choose which tools ask first
diff --git a/packages/ai-mcp/src/connector.ts b/packages/ai-mcp/src/connector.ts
index 6f85317f9c..5a1655cf01 100644
--- a/packages/ai-mcp/src/connector.ts
+++ b/packages/ai-mcp/src/connector.ts
@@ -7,11 +7,11 @@ import {
   startLoopbackReceiver,
 } from '@tanstack/ai-harness'
 import { createMCPClient } from './client'
+import { MCPConnectionError } from './errors'
 import type {
-  OAuthClientInformationMixed,
-  OAuthClientMetadata,
   OAuthClientProvider,
-  OAuthTokens,
+  OAuthDiscoveryState,
+  StoredOAuthClientInformation,
 } from '@modelcontextprotocol/client'
 import type { AnyTool } from '@tanstack/ai'
 import type { CredentialsAccess } from '@tanstack/ai-harness'
@@ -49,15 +49,17 @@ function credentialProvider(
   id: string,
   credentials: CredentialsAccess,
   options: {
-    redirectUri: string | undefined
+    redirectUri: string
     clientName: string
     scopes: ReadonlyArray<string> | undefined
     state?: string
     onRedirect?: (url: URL) => void
   },
-): OAuthClientProvider {
-  let client: OAuthClientInformationMixed | undefined
+) {
+  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
@@ -66,35 +68,35 @@ function credentialProvider(
     get redirectUrl() {
       return options.redirectUri
     },
-    get clientMetadata(): OAuthClientMetadata {
+    get clientMetadata() {
       return {
         client_name: options.clientName,
-        redirect_uris: options.redirectUri ? [options.redirectUri] : [],
+        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(' ') } : {}),
       }
     },
-    ...(options.state ? { state: () => options.state ?? '' } : {}),
+    ...(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
-      return saved
-        ? {
-            client_id: saved.clientId,
-            ...(saved.clientSecret
-              ? { client_secret: saved.clientSecret }
-              : {}),
-          }
-        : undefined
+      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 (): Promise<OAuthTokens | undefined> => {
+    tokens: async () => {
       if (options.onRedirect) return undefined
       const credential = await stored()
       if (!credential) return undefined
@@ -112,48 +114,45 @@ function credentialProvider(
               ),
             }
           : {}),
+        // The SDK checks that the tokens come from the same server (SEP-2352).
+        ...(credential.client?.issuer
+          ? { issuer: credential.client.issuer }
+          : {}),
       }
     },
     saveTokens: async (tokens) => {
-      const previous = await stored()
-      const information =
-        client ??
-        (previous?.client
-          ? {
-              client_id: previous.client.clientId,
-              client_secret: previous.client.clientSecret,
-            }
-          : undefined)
+      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, {
         type: 'oauth',
         accessToken: tokens.access_token,
-        ...(tokens.refresh_token
-          ? { refreshToken: tokens.refresh_token }
-          : previous?.refreshToken
-            ? { refreshToken: previous.refreshToken }
-            : {}),
+        ...(tokens.refresh_token ? { refreshToken: tokens.refresh_token } : {}),
         ...(tokens.expires_in
           ? { expiresAt: Date.now() + tokens.expires_in * 1000 }
           : {}),
         ...(tokens.scope ? { scopes: tokens.scope.split(' ') } : {}),
-        ...(information
-          ? {
-              client: {
-                clientId: information.client_id,
-                ...(information.client_secret
-                  ? { clientSecret: information.client_secret }
-                  : {}),
-                ...((options.redirectUri ?? previous?.client?.redirectUri)
-                  ? {
-                      redirectUri:
-                        options.redirectUri ?? previous?.client?.redirectUri,
-                    }
-                  : {}),
-              },
-            }
-          : {}),
+        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)
@@ -163,7 +162,13 @@ function credentialProvider(
       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
 }
 
 /**
@@ -224,22 +229,35 @@ export function mcpConnector(options: McpConnectorOptions) {
               (saved?.type === 'oauth'
                 ? saved.client?.redirectUri
                 : undefined) ?? 'http://127.0.0.1/callback'
-            client = await createMCPClient({
-              transport: {
-                type: 'http',
-                url,
-                authProvider: credentialProvider(id, ctx.credentials, {
-                  redirectUri,
-                  clientName,
-                  scopes: options.scopes,
-                }),
-                ...(options.fetch ? { fetch: options.fetch } : {}),
-              },
-              prefix,
-              needsApproval:
-                options.needsApproval ??
-                ((tool) => tool.annotations?.readOnlyHint !== true),
-            })
+            try {
+              client = await createMCPClient({
+                transport: {
+                  type: 'http',
+                  url,
+                  authProvider: credentialProvider(id, ctx.credentials, {
+                    redirectUri,
+                    clientName,
+                    scopes: options.scopes,
+                  }),
+                  ...(options.fetch ? { fetch: options.fetch } : {}),
+                },
+                prefix,
+                needsApproval:
+                  options.needsApproval ??
+                  ((tool) => tool.annotations?.readOnlyHint !== true),
+              })
+            } 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
+              connected = false
+              ctx.session.authRequired({ connector: id })
+              throw error.cause
+            }
             tools = (await client.tools()) as ReadonlyArray<AnyTool>
           }
           return tools
@@ -263,18 +281,15 @@ export function mcpConnector(options: McpConnectorOptions) {
                     }),
                 })
                 const fetchFn = options.fetch ? { fetchFn: options.fetch } : {}
-                const first = await auth(provider, {
+                // A new sign-in has no tokens, so this always ends in a
+                // redirect to the browser.
+                await auth(provider, { serverUrl: url, ...fetchFn })
+                const code = await receiver.waitForCode(state)
+                await auth(provider, {
                   serverUrl: url,
+                  authorizationCode: code,
                   ...fetchFn,
                 })
-                if (first === 'REDIRECT') {
-                  const code = await receiver.waitForCode(state)
-                  await auth(provider, {
-                    serverUrl: url,
-                    authorizationCode: code,
-                    ...fetchFn,
-                  })
-                }
               } finally {
                 receiver.close()
               }
diff --git a/packages/ai-mcp/tests/connector-edges.test.ts b/packages/ai-mcp/tests/connector-edges.test.ts
index 34b1f4d220..c6c5507bbd 100644
--- a/packages/ai-mcp/tests/connector-edges.test.ts
+++ b/packages/ai-mcp/tests/connector-edges.test.ts
@@ -1,16 +1,20 @@
-import { afterEach, describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 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,
-  authorizationUrlOf,
-  recorder,
-} from './connector-helpers'
+  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 { HarnessSession, SessionEvent } from '@tanstack/ai-harness'
+import type {
+  HarnessHost,
+  HarnessSession,
+  SessionEvent,
+} from '@tanstack/ai-harness'
 
 const scope = { threadId: 't', userId: 'user-1' }
 const cleanups: Array<() => unknown> = []
@@ -38,6 +42,19 @@ function connectorHarness(url: string, model: ReturnType<typeof recorder>) {
   })
 }
 
+/** 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> = []
@@ -55,6 +72,13 @@ async function promptAndCollect(session: HarnessSession, text: string) {
   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({
@@ -69,10 +93,7 @@ describe('mcpConnector with a saved sign-in', () => {
       },
     })
     const model = recorder('demo_echo')
-    const session = await host.open(connectorHarness(server.url, model), {
-      threadId: 't',
-      principal: { id: 'user-1' },
-    })
+    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')
@@ -105,21 +126,19 @@ describe('mcpConnector with a saved sign-in', () => {
         client,
       })
       const model = recorder('demo_echo')
-      const session = await host.open(connectorHarness(server.url, model), {
-        threadId: 't',
-        principal: { id: 'user-1' },
-      })
+      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, 'demo')).toEqual({
         type: 'oauth',
         accessToken: 'access-2',
         refreshToken: 'refresh-1',
-        client: { clientId: 'client-1', redirectUri },
+        client: { clientId: 'client-1', redirectUri, issuer: server.issuer },
       })
     },
   )
@@ -133,46 +152,86 @@ describe('mcpConnector with a saved sign-in', () => {
         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 with a warning, and keeps the sign-in, when $failure',
-    async ({ credential, revoke }) => {
+    '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 host.open(connectorHarness(server.url, model), {
-        threadId: 't',
-        principal: { id: 'user-1' },
-      })
+      const session = await openDemo(host, server.url, model)
       const seen = await promptAndCollect(session, 'hi')
       expect(model.toolNames(0)).toEqual([])
-      const warning = seen.find(
-        (entry) =>
-          entry.event.type === EventType.CUSTOM &&
-          entry.event.name === 'harness.plugin.warning',
+      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',
       )
-      expect(warning?.event).toMatchObject({
-        value: { plugin: 'connector/demo' },
-      })
-      // Outside /connect, the connector never starts a browser sign-in.
-      expect(
-        seen.filter((entry) => authorizationUrlOf(entry.event) !== undefined),
-      ).toEqual([])
-      // Only /disconnect signs the user out.
-      expect(
-        await persistence.stores.credentials.get(scope, 'demo'),
-      ).toMatchObject({ type: 'oauth', accessToken: credential.accessToken })
+      const saved = await persistence.stores.credentials.get(scope, '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, 'demo')).toEqual({
+      type: 'oauth',
+      accessToken: 'access-1',
+    })
+  })
 })
 
 describe('mcpConnector /connect', () => {
@@ -223,27 +282,24 @@ describe('mcpConnector /connect', () => {
   })
 
   it.each([
-    { before: 'no earlier sign-in', earlier: undefined, kept: {} },
+    { before: 'no earlier sign-in', earlier: undefined },
     {
       before: 'an earlier sign-in',
-      earlier: { type: 'oauth', accessToken: 'old', refreshToken: 'refresh-0' },
-      kept: { refreshToken: 'refresh-0' },
+      // 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
-    kept: { refreshToken?: string }
-  }>)(
-    'saves a sign-in that gives no refresh token after $before',
-    async ({ earlier, kept }) => {
+  ] 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 host.open(
-        connectorHarness(server.url, recorder()),
-        {
-          threadId: 't',
-          principal: { id: 'user-1' },
-        },
-      )
+      const session = await openDemo(host, server.url)
       const browser = approveSignIns(session, 'code-2')
       cleanups.push(browser.stop)
 
@@ -251,35 +307,88 @@ describe('mcpConnector /connect', () => {
       expect(await persistence.stores.credentials.get(scope, 'demo')).toEqual({
         type: 'oauth',
         accessToken: 'access-1',
-        ...kept,
         client: {
           clientId: 'client-1',
           redirectUri: expect.stringMatching(/^http:\/\/127\.0\.0\.1:\d+\//),
+          issuer: server.issuer,
         },
       })
     },
   )
 
-  it('stays signed out when the sign-in fails', async () => {
-    const { persistence, host, server } = await setup()
+  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 host.open(connectorHarness(server.url, model), {
-      threadId: 't',
-      principal: { id: 'user-1' },
-    })
-    const browser = approveSignIns(session, 'wrong-code')
+    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.')
 
-    await expect(session.command('connect:demo')).rejects.toMatchObject({
-      code: 'invalid_grant',
-    })
-    expect(await persistence.stores.credentials.get(scope, 'demo')).toBeNull()
+    // The server stops taking the first token, so the next turn refreshes it.
+    server.revoke('access-1')
     await session.prompt('hi')
-    expect(JSON.stringify(model.calls[0]?.systemPrompts)).toContain(
-      'run /connect demo',
+    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, '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(
+      [],
     )
-    expect(model.toolNames(0)).toEqual([])
   })
+
+  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, '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', () => {
@@ -289,19 +398,13 @@ describe('mcpConnector stored credential shapes', () => {
       accessToken: 'access-1',
     })
     const model = recorder()
-    const session = await host.open(connectorHarness(server.url, model), {
-      threadId: 't',
-      principal: { id: 'user-1' },
-    })
+    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 host.open(connectorHarness(server.url, recorder()), {
-      threadId: 't2',
-      principal: { id: 'user-1' },
-    })
+    const fresh = await openDemo(host, server.url, recorder(), 't2')
     expect(await fresh.command('disconnect:demo')).toBe(
       'Disconnected from Demo.',
     )
@@ -315,13 +418,7 @@ describe('mcpConnector stored credential shapes', () => {
       refreshToken: 'refresh-1',
     })
     const model = recorder()
-    const session = await bare.host.open(
-      connectorHarness(bare.server.url, model),
-      {
-        threadId: 't',
-        principal: { id: 'user-1' },
-      },
-    )
+    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, 'demo')
@@ -339,10 +436,7 @@ describe('mcpConnector stored credential shapes', () => {
       refreshToken: 'refresh-1',
       client: { clientId: 'client-1', clientSecret: 'secret-1' },
     })
-    const other = await withSecret.host.open(
-      connectorHarness(withSecret.server.url, recorder()),
-      { threadId: 't', principal: { id: 'user-1' } },
-    )
+    const other = await openDemo(withSecret.host, withSecret.server.url)
     await other.prompt('hi')
     expect(
       await withSecret.persistence.stores.credentials.get(scope, 'demo'),
@@ -358,10 +452,7 @@ describe('mcpConnector stored credential shapes', () => {
       value: 'not-oauth',
     })
     const model = recorder()
-    const session = await host.open(connectorHarness(server.url, model), {
-      threadId: 't',
-      principal: { id: 'user-1' },
-    })
+    const session = await openDemo(host, server.url, model)
     await session.prompt('hi')
     expect(model.toolNames(0)).toEqual([])
   })
diff --git a/packages/ai-mcp/tests/protected-server.ts b/packages/ai-mcp/tests/protected-server.ts
index cd24512590..f659296f05 100644
--- a/packages/ai-mcp/tests/protected-server.ts
+++ b/packages/ai-mcp/tests/protected-server.ts
@@ -149,6 +149,8 @@ export async function startProtectedServer() {
   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: () =>
diff --git a/packages/ai-persistence/src/types.ts b/packages/ai-persistence/src/types.ts
index 956aef08de..dc47fcfffb 100644
--- a/packages/ai-persistence/src/types.ts
+++ b/packages/ai-persistence/src/types.ts
@@ -427,9 +427,15 @@ export type Credential =
       scopes?: Array<string>
       /**
        * The OAuth client these tokens belong to (for example one made by
-       * dynamic client registration). A refresh needs it.
+       * dynamic client registration). A refresh needs it. `issuer` is the
+       * authorization server that issued the client and the tokens.
        */
-      client?: { clientId: string; clientSecret?: string; redirectUri?: string }
+      client?: {
+        clientId: string
+        clientSecret?: string
+        redirectUri?: string
+        issuer?: string
+      }
     }
 
 /**

From 4db4610a94166adcf228eac243271e9165133c53 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 29 Sep 2026 11:24:04 +0200
Subject: [PATCH 057/286] feat(ai, ai-harness): runtime inputModalities on text
 adapters, and harness media records and refs

Text adapters can now say at runtime which inputs the model reads. The harness gets MediaRecord, MediaKind, the harness.media event, and browser-safe helpers for harness-media: content parts.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/text-adapter-input-modalities.md   |   5 +
 packages/ai-harness/src/index.ts              |  10 ++
 packages/ai-harness/src/media-ref.ts          | 120 +++++++++++++++
 packages/ai-harness/src/types.ts              |  23 +++
 packages/ai-harness/tests/media-ref.test.ts   | 140 ++++++++++++++++++
 .../chat/adapter-input-modalities.test.ts     |  48 ++++++
 packages/ai/src/activities/chat/adapter.ts    |  12 ++
 7 files changed, 358 insertions(+)
 create mode 100644 .changeset/text-adapter-input-modalities.md
 create mode 100644 packages/ai-harness/src/media-ref.ts
 create mode 100644 packages/ai-harness/tests/media-ref.test.ts
 create mode 100644 packages/ai/src/activities/chat/adapter-input-modalities.test.ts

diff --git a/.changeset/text-adapter-input-modalities.md b/.changeset/text-adapter-input-modalities.md
new file mode 100644
index 0000000000..f614ac62b1
--- /dev/null
+++ b/.changeset/text-adapter-input-modalities.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai': minor
+---
+
+Text adapters can declare `inputModalities`, the input kinds the model reads, at runtime. A `BaseTextAdapter` subclass sets it from its model metadata, and `undefined` means not known.
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index 9530b80254..e63845e269 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -80,6 +80,8 @@ export type {
   ChatTurnResult,
   Cursor,
   HarnessInput,
+  MediaKind,
+  MediaRecord,
   Operation,
   OperationKind,
   OperationStatus,
@@ -89,6 +91,14 @@ export type {
   UserInput,
 } from './types'
 
+export {
+  MEDIA_URL_PREFIX,
+  kindOf,
+  mediaIdOf,
+  mediaOfMessage,
+  mediaPart,
+} from './media-ref'
+
 export {
   HARNESS_PROTOCOL_VERSION,
   applyInput,
diff --git a/packages/ai-harness/src/media-ref.ts b/packages/ai-harness/src/media-ref.ts
new file mode 100644
index 0000000000..ad849dfd36
--- /dev/null
+++ b/packages/ai-harness/src/media-ref.ts
@@ -0,0 +1,120 @@
+// Browser-safe media references. Type-only imports, no server code, so the
+// client and view entries can use these too.
+import type { ContentPart, ModelMessage } from '@tanstack/ai'
+import type { MediaKind, MediaRecord } from './types'
+
+/** The URL scheme of a content part that points to a harness media file. */
+export const MEDIA_URL_PREFIX = 'harness-media:'
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function isMediaKind(value: unknown): value is MediaKind {
+  return (
+    value === 'image' ||
+    value === 'audio' ||
+    value === 'video' ||
+    value === 'document'
+  )
+}
+
+function isOptionalString(value: unknown) {
+  return value === undefined || typeof value === 'string'
+}
+
+function isMediaRecord(value: unknown): value is MediaRecord {
+  if (!isRecord(value)) return false
+  const hasOptionalIds =
+    isOptionalString(value.runId) && isOptionalString(value.subagentRunId)
+  return (
+    hasOptionalIds &&
+    typeof value.id === 'string' &&
+    typeof value.threadId === 'string' &&
+    isMediaKind(value.kind) &&
+    typeof value.mimeType === 'string' &&
+    typeof value.name === 'string' &&
+    typeof value.size === 'number' &&
+    (value.source === 'user' || value.source === 'generated') &&
+    typeof value.createdAt === 'number'
+  )
+}
+
+/**
+ * The media kind of a MIME type, or `undefined` when the harness does not
+ * store that type. `image/*`, `audio/*`, and `video/*` map to their kind.
+ * `application/pdf` and `text/*` are documents.
+ *
+ * @example
+ * kindOf('image/png') // 'image'
+ * kindOf('application/zip') // undefined
+ */
+export function kindOf(mimeType: string) {
+  // A Content-Type header can carry parameters: `text/plain; charset=utf-8`.
+  const [type = ''] = mimeType.toLowerCase().split(';')
+  const [top = '', sub] = type.trim().split('/')
+  if (!sub) return undefined
+  switch (top) {
+    case 'image':
+    case 'audio':
+    case 'video':
+      return top
+    case 'text':
+      return 'document'
+    case 'application':
+      return sub === 'pdf' ? 'document' : undefined
+    default:
+      return undefined
+  }
+}
+
+/**
+ * The content part that sends a stored media file to a turn. Its source is
+ * the URL `harness-media:<id>`. The harness swaps it for the bytes only when
+ * it calls the model, so the transcript stays small.
+ *
+ * @example
+ * session.prompt([{ type: 'text', content: 'What is this?' }, mediaPart(record)])
+ */
+export function mediaPart(record: MediaRecord) {
+  const part: ContentPart = {
+    type: record.kind,
+    source: {
+      type: 'url',
+      value: `${MEDIA_URL_PREFIX}${record.id}`,
+      mimeType: record.mimeType,
+    },
+  }
+  return part
+}
+
+/**
+ * The media id of a part made by `mediaPart`, or `undefined` for any other
+ * value (text, a data source, a normal URL).
+ *
+ * @example
+ * const ids = parts.map(mediaIdOf).filter((id) => id !== undefined)
+ */
+export function mediaIdOf(part: unknown) {
+  if (!isRecord(part) || !isMediaKind(part.type) || !isRecord(part.source)) {
+    return undefined
+  }
+  const { type, value } = part.source
+  if (type !== 'url' || typeof value !== 'string') return undefined
+  if (!value.startsWith(MEDIA_URL_PREFIX)) return undefined
+  return value.slice(MEDIA_URL_PREFIX.length) || undefined
+}
+
+/**
+ * The media records saved on a message in `metadata.harness.media`: the
+ * media a turn made, kept on its last assistant message. Entries with a bad
+ * shape are skipped. Returns `[]` when there are none.
+ *
+ * @example
+ * for (const media of mediaOfMessage(message)) console.log(media.name)
+ */
+export function mediaOfMessage(message: ModelMessage) {
+  const harness: unknown = message.metadata?.harness
+  const media = isRecord(harness) ? harness.media : undefined
+  return Array.isArray(media) ? media.filter(isMediaRecord) : []
+}
diff --git a/packages/ai-harness/src/types.ts b/packages/ai-harness/src/types.ts
index ffcf2efc89..5088c0e8e5 100644
--- a/packages/ai-harness/src/types.ts
+++ b/packages/ai-harness/src/types.ts
@@ -92,6 +92,27 @@ export interface Operation<TResult> extends PromiseLike<TResult> {
   cancel: (reason?: string) => Promise<Receipt>
 }
 
+/** What a media file holds. It picks the content part a model gets. */
+export type MediaKind = 'image' | 'audio' | 'video' | 'document'
+
+/** A file in a thread's media store: sent by a user or made by an agent. */
+export interface MediaRecord {
+  id: string
+  threadId: string
+  kind: MediaKind
+  mimeType: string
+  name: string
+  /** Size in bytes. */
+  size: number
+  source: 'user' | 'generated'
+  /** Epoch milliseconds. */
+  createdAt: number
+  /** The operation that made generated media. */
+  runId?: string
+  /** The child agent run that made it, when a subagent did. */
+  subagentRunId?: string
+}
+
 /** Names of the `CUSTOM` events a harness session adds to the stream. */
 export const HARNESS_EVENTS = {
   operationStarted: 'harness.operation.started',
@@ -105,4 +126,6 @@ export const HARNESS_EVENTS = {
   inputAccepted: 'harness.input.accepted',
   inputApplied: 'harness.input.applied',
   inputRejected: 'harness.input.rejected',
+  /** A media file was stored. The value is a `MediaRecord`. */
+  media: 'harness.media',
 } as const
diff --git a/packages/ai-harness/tests/media-ref.test.ts b/packages/ai-harness/tests/media-ref.test.ts
new file mode 100644
index 0000000000..867218e368
--- /dev/null
+++ b/packages/ai-harness/tests/media-ref.test.ts
@@ -0,0 +1,140 @@
+import { describe, expect, it } from 'vitest'
+import { kindOf, mediaIdOf, mediaOfMessage, mediaPart } from '../src'
+import type { ModelMessage } from '@tanstack/ai'
+import type { MediaRecord } from '../src'
+
+function record(overrides?: Partial<MediaRecord>): MediaRecord {
+  return {
+    id: 'm1',
+    threadId: 't1',
+    kind: 'image',
+    mimeType: 'image/png',
+    name: 'cat.png',
+    size: 42,
+    source: 'user',
+    createdAt: 1_700_000_000_000,
+    ...overrides,
+  }
+}
+
+function assistantWith(metadata: ModelMessage['metadata']): ModelMessage {
+  return { role: 'assistant', content: 'done', metadata }
+}
+
+describe('kindOf', () => {
+  it.each([
+    ['image/png', 'image'],
+    ['audio/mpeg', 'audio'],
+    ['video/mp4', 'video'],
+    ['application/pdf', 'document'],
+    ['text/plain', 'document'],
+    ['text/markdown; charset=utf-8', 'document'],
+    ['IMAGE/JPEG', 'image'],
+  ] as const)('maps %s to %s', (mimeType, kind) => {
+    expect(kindOf(mimeType)).toBe(kind)
+  })
+
+  it.each(['application/zip', 'application/json', 'image', 'image/', ''])(
+    'returns undefined for %j',
+    (mimeType) => {
+      expect(kindOf(mimeType)).toBeUndefined()
+    },
+  )
+})
+
+describe('mediaPart', () => {
+  it.each([
+    ['image', 'image/png'],
+    ['audio', 'audio/wav'],
+    ['video', 'video/mp4'],
+    ['document', 'application/pdf'],
+  ] as const)('builds a %s part with a harness-media url', (kind, mimeType) => {
+    expect(mediaPart(record({ id: 'abc', kind, mimeType }))).toEqual({
+      type: kind,
+      source: { type: 'url', value: 'harness-media:abc', mimeType },
+    })
+  })
+})
+
+describe('mediaIdOf', () => {
+  it('reads the id of a harness media part', () => {
+    const part = {
+      type: 'audio',
+      source: { type: 'url', value: 'harness-media:clip-7' },
+    }
+    expect(mediaIdOf(part)).toBe('clip-7')
+  })
+
+  it.each([
+    [
+      'a plain https url',
+      {
+        type: 'image',
+        source: { type: 'url', value: 'https://acme.dev/cat.png' },
+      },
+    ],
+    [
+      'a data source',
+      {
+        type: 'image',
+        source: { type: 'data', value: 'aGk=', mimeType: 'image/png' },
+      },
+    ],
+    [
+      'a file handle',
+      { type: 'document', source: { type: 'file', value: 'harness-media:m1' } },
+    ],
+    [
+      'an empty id',
+      { type: 'image', source: { type: 'url', value: 'harness-media:' } },
+    ],
+    ['a text part', { type: 'text', content: 'harness-media:m1' }],
+    ['a bare string', 'harness-media:m1'],
+    ['null', null],
+  ])('returns undefined for %s', (_label, part) => {
+    expect(mediaIdOf(part)).toBeUndefined()
+  })
+})
+
+describe('mediaOfMessage', () => {
+  it('returns the media records in metadata.harness.media', () => {
+    const generated = record({
+      id: 'm2',
+      kind: 'video',
+      mimeType: 'video/mp4',
+      name: 'clip.mp4',
+      source: 'generated',
+      runId: 'run-1',
+      subagentRunId: 'sub-1',
+    })
+    const message = assistantWith({ harness: { media: [record(), generated] } })
+    expect(mediaOfMessage(message)).toEqual([record(), generated])
+  })
+
+  it('skips entries with a bad shape', () => {
+    const message = assistantWith({
+      harness: {
+        media: [
+          record({ id: 'good' }),
+          { ...record(), id: undefined },
+          { ...record(), kind: 'spreadsheet' },
+          { ...record(), source: 'robot' },
+          { ...record(), size: '42' },
+          { ...record(), runId: 7 },
+          'harness-media:m1',
+          null,
+        ],
+      },
+    })
+    expect(mediaOfMessage(message)).toEqual([record({ id: 'good' })])
+  })
+
+  it.each([
+    ['no metadata', undefined],
+    ['no harness key', { tanstack: {} }],
+    ['a harness value that is not an object', { harness: 'media' }],
+    ['media that is not an array', { harness: { media: { id: 'm1' } } }],
+  ])('returns [] for %s', (_label, metadata) => {
+    expect(mediaOfMessage(assistantWith(metadata))).toEqual([])
+  })
+})
diff --git a/packages/ai/src/activities/chat/adapter-input-modalities.test.ts b/packages/ai/src/activities/chat/adapter-input-modalities.test.ts
new file mode 100644
index 0000000000..5bc1131bff
--- /dev/null
+++ b/packages/ai/src/activities/chat/adapter-input-modalities.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest'
+import { BaseTextAdapter } from './adapter'
+import type { AnyTextAdapter } from './adapter'
+import type { DefaultMessageMetadataByModality, Modality } from '../../types'
+
+// Stands in for a provider's model-meta map.
+const INPUT_BY_MODEL: Record<string, ReadonlyArray<Modality>> = {
+  'vision-model': ['text', 'image'],
+}
+
+/** A provider adapter that does not set `inputModalities`. */
+class StubTextAdapter extends BaseTextAdapter<
+  string,
+  Record<string, never>,
+  ReadonlyArray<Modality>,
+  DefaultMessageMetadataByModality
+> {
+  readonly name = 'stub'
+
+  constructor(model: string) {
+    super({}, model)
+  }
+
+  async *chatStream() {}
+
+  structuredOutput() {
+    return Promise.resolve({ data: {}, rawText: '{}' })
+  }
+}
+
+/** A provider adapter that sets `inputModalities` from its model name. */
+class ModelMetaTextAdapter extends StubTextAdapter {
+  override readonly inputModalities = INPUT_BY_MODEL[this.model]
+}
+
+describe('TextAdapter inputModalities', () => {
+  it('exposes the list a subclass sets from its model name', () => {
+    const adapter: AnyTextAdapter = new ModelMetaTextAdapter('vision-model')
+
+    expect(adapter.inputModalities).toEqual(['text', 'image'])
+  })
+
+  it('is undefined when the subclass does not set it', () => {
+    const adapter: AnyTextAdapter = new StubTextAdapter('vision-model')
+
+    expect(adapter.inputModalities).toBeUndefined()
+  })
+})
diff --git a/packages/ai/src/activities/chat/adapter.ts b/packages/ai/src/activities/chat/adapter.ts
index dd1b1d2cce..c4c92c2fef 100644
--- a/packages/ai/src/activities/chat/adapter.ts
+++ b/packages/ai/src/activities/chat/adapter.ts
@@ -98,6 +98,13 @@ export interface TextAdapter<
    */
   readonly supportsFileSources?: boolean
 
+  /**
+   * The input kinds the model reads, at runtime, from the provider's model
+   * metadata. `undefined` means not known. This mirrors the type-level
+   * `'~types'.inputModalities`, which has no runtime value.
+   */
+  readonly inputModalities?: ReadonlyArray<Modality>
+
   /**
    * @internal Type-only properties for inference. Not assigned at runtime.
    */
@@ -219,6 +226,11 @@ export abstract class BaseTextAdapter<
   readonly model: TModel
   readonly requires?: ReadonlyArray<CapabilityHandle> = undefined
   readonly supportsFileSources: boolean = false
+  /**
+   * Provider subclasses override this from their model metadata, for example
+   * `override readonly inputModalities = INPUT_BY_MODEL[this.model]`.
+   */
+  readonly inputModalities?: ReadonlyArray<Modality> = undefined
 
   // Type-only property - never assigned at runtime
   declare '~types': {

From 9ed41b5a138b1cd69f28515cc3f6fbcaf33e7129 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 29 Sep 2026 11:41:41 +0200
Subject: [PATCH 058/286] feat: provider inputModalities, harness media store,
 view media parts, client media calls

Text adapters of openai, anthropic, gemini, mistral, groq, byteplus, grok, openrouter, and llmgateway now set inputModalities from their model metadata. The harness gets a media store with capture of generated media and a middleware that sends stored files to the model. The session view gets media parts, and the browser client can upload and load media.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/provider-input-modalities-a.md     |   8 +
 .changeset/provider-input-modalities-b.md     |   9 +
 packages/ai-anthropic/src/adapters/text.ts    |   3 +
 packages/ai-anthropic/src/model-meta.ts       |  25 +
 .../tests/input-modalities.test.ts            |  26 +
 packages/ai-byteplus/src/adapters/text.ts     |   3 +
 packages/ai-byteplus/src/model-meta.ts        |  30 +
 .../tests/input-modalities.test.ts            |  20 +
 packages/ai-gemini/src/adapters/text.ts       |   6 +-
 packages/ai-gemini/src/model-meta.ts          |  24 +
 .../ai-gemini/tests/input-modalities.test.ts  |  24 +
 packages/ai-grok/src/adapters/text.ts         |   2 +
 packages/ai-grok/src/model-meta.ts            |  21 +
 .../ai-grok/tests/input-modalities.test.ts    |  18 +
 packages/ai-groq/src/adapters/text.ts         |   2 +
 packages/ai-groq/src/model-meta.ts            |  25 +
 .../ai-groq/tests/input-modalities.test.ts    |  18 +
 packages/ai-harness/src/client.ts             | 112 +++-
 packages/ai-harness/src/media.ts              | 472 ++++++++++++++
 packages/ai-harness/src/view/index.ts         | 155 ++++-
 packages/ai-harness/src/view/reduce.ts        | 116 +++-
 packages/ai-harness/src/view/types.ts         |  29 +-
 .../ai-harness/tests/client-media.test.ts     | 148 +++++
 packages/ai-harness/tests/media.test.ts       | 421 ++++++++++++
 packages/ai-harness/tests/view-media.test.ts  | 375 +++++++++++
 packages/ai-llmgateway/src/adapters/text.ts   |   3 +
 packages/ai-llmgateway/src/model-meta.ts      |  26 +
 .../tests/input-modalities.test.ts            |  20 +
 packages/ai-mistral/src/adapters/text.ts      |   2 +
 .../ai-mistral/src/input-modalities.test.ts   |  24 +
 packages/ai-mistral/src/model-meta.ts         |  25 +
 .../src/adapters/text-chat-completions.ts     |   2 +
 packages/ai-openai/src/adapters/text.ts       |   6 +-
 packages/ai-openai/src/model-meta.ts          |  68 ++
 .../ai-openai/tests/input-modalities.test.ts  |  34 +
 .../src/adapters/responses-text.ts            |   3 +
 packages/ai-openrouter/src/adapters/text.ts   |   3 +
 packages/ai-openrouter/src/model-meta.ts      | 602 ++++++++++++++++++
 .../tests/input-modalities.test.ts            |  31 +
 scripts/convert-openrouter-models.ts          |  35 +
 40 files changed, 2942 insertions(+), 34 deletions(-)
 create mode 100644 .changeset/provider-input-modalities-a.md
 create mode 100644 .changeset/provider-input-modalities-b.md
 create mode 100644 packages/ai-anthropic/tests/input-modalities.test.ts
 create mode 100644 packages/ai-byteplus/tests/input-modalities.test.ts
 create mode 100644 packages/ai-gemini/tests/input-modalities.test.ts
 create mode 100644 packages/ai-grok/tests/input-modalities.test.ts
 create mode 100644 packages/ai-groq/tests/input-modalities.test.ts
 create mode 100644 packages/ai-harness/src/media.ts
 create mode 100644 packages/ai-harness/tests/client-media.test.ts
 create mode 100644 packages/ai-harness/tests/media.test.ts
 create mode 100644 packages/ai-harness/tests/view-media.test.ts
 create mode 100644 packages/ai-llmgateway/tests/input-modalities.test.ts
 create mode 100644 packages/ai-mistral/src/input-modalities.test.ts
 create mode 100644 packages/ai-openai/tests/input-modalities.test.ts
 create mode 100644 packages/ai-openrouter/tests/input-modalities.test.ts

diff --git a/.changeset/provider-input-modalities-a.md b/.changeset/provider-input-modalities-a.md
new file mode 100644
index 0000000000..660f89d774
--- /dev/null
+++ b/.changeset/provider-input-modalities-a.md
@@ -0,0 +1,8 @@
+---
+'@tanstack/ai-openai': patch
+'@tanstack/ai-anthropic': patch
+'@tanstack/ai-gemini': patch
+'@tanstack/ai-mistral': patch
+---
+
+The text adapters set `inputModalities` from their model metadata, so a known model gives the input kinds it reads and an unknown model gives `undefined`.
diff --git a/.changeset/provider-input-modalities-b.md b/.changeset/provider-input-modalities-b.md
new file mode 100644
index 0000000000..a0efb244a9
--- /dev/null
+++ b/.changeset/provider-input-modalities-b.md
@@ -0,0 +1,9 @@
+---
+'@tanstack/ai-groq': patch
+'@tanstack/ai-byteplus': patch
+'@tanstack/ai-grok': patch
+'@tanstack/ai-openrouter': patch
+'@tanstack/ai-llmgateway': patch
+---
+
+The text adapters set `inputModalities` from their model metadata, so a known model gives the input kinds it reads and an unknown model gives `undefined`.
diff --git a/packages/ai-anthropic/src/adapters/text.ts b/packages/ai-anthropic/src/adapters/text.ts
index b84a7a65c4..706a2df013 100644
--- a/packages/ai-anthropic/src/adapters/text.ts
+++ b/packages/ai-anthropic/src/adapters/text.ts
@@ -21,6 +21,7 @@ import {
 } from '../utils/client'
 import {
   ANTHROPIC_COMBINED_TOOLS_AND_SCHEMA_MODELS,
+  ANTHROPIC_MODEL_INPUT_MODALITIES,
   getAnthropicDefaultMaxTokens,
 } from '../model-meta'
 import type {
@@ -341,6 +342,8 @@ export class AnthropicTextAdapter<
   readonly name = 'anthropic' as const
   // Consumes `file_id` sources issued by anthropicFiles() (Files API beta).
   override readonly supportsFileSources = true
+  override readonly inputModalities =
+    ANTHROPIC_MODEL_INPUT_MODALITIES[this.model]
 
   private readonly client: SdkAnthropicMessagesClient
 
diff --git a/packages/ai-anthropic/src/model-meta.ts b/packages/ai-anthropic/src/model-meta.ts
index 4c2b30e928..07e6d9adfe 100644
--- a/packages/ai-anthropic/src/model-meta.ts
+++ b/packages/ai-anthropic/src/model-meta.ts
@@ -1,3 +1,4 @@
+import type { Modality } from '@tanstack/ai'
 import type {
   AnthropicAdaptiveOnlyThinkingOptions,
   AnthropicAdaptiveOrDisabledThinkingOptions,
@@ -990,3 +991,27 @@ export type AnthropicModelInputModalitiesByName = {
   [CLAUDE_FABLE_5_1.id]: typeof CLAUDE_FABLE_5_1.supports.input
   [CLAUDE_OPUS_5_5.id]: typeof CLAUDE_OPUS_5_5.supports.input
 }
+
+/**
+ * Runtime map from chat model id to its supported input modalities, for the
+ * text adapter's `inputModalities`. `satisfies` keeps it equal to
+ * {@link AnthropicModelInputModalitiesByName}. An unknown id gives `undefined`.
+ */
+export const ANTHROPIC_MODEL_INPUT_MODALITIES: Readonly<
+  Record<string, ReadonlyArray<Modality>>
+> = {
+  [CLAUDE_OPUS_4_6.id]: CLAUDE_OPUS_4_6.supports.input,
+  [CLAUDE_OPUS_4_5.id]: CLAUDE_OPUS_4_5.supports.input,
+  [CLAUDE_SONNET_4_6.id]: CLAUDE_SONNET_4_6.supports.input,
+  [CLAUDE_SONNET_4_5.id]: CLAUDE_SONNET_4_5.supports.input,
+  [CLAUDE_HAIKU_4_5.id]: CLAUDE_HAIKU_4_5.supports.input,
+  [CLAUDE_OPUS_4_1.id]: CLAUDE_OPUS_4_1.supports.input,
+  [CLAUDE_OPUS_4_7.id]: CLAUDE_OPUS_4_7.supports.input,
+  [CLAUDE_OPUS_4_8.id]: CLAUDE_OPUS_4_8.supports.input,
+  [CLAUDE_FABLE_5.id]: CLAUDE_FABLE_5.supports.input,
+  [CLAUDE_SONNET_5.id]: CLAUDE_SONNET_5.supports.input,
+  [CLAUDE_OPUS_5.id]: CLAUDE_OPUS_5.supports.input,
+  [CLAUDE_OPUS_5_FAST.id]: CLAUDE_OPUS_5_FAST.supports.input,
+  [CLAUDE_FABLE_5_1.id]: CLAUDE_FABLE_5_1.supports.input,
+  [CLAUDE_OPUS_5_5.id]: CLAUDE_OPUS_5_5.supports.input,
+} satisfies AnthropicModelInputModalitiesByName
diff --git a/packages/ai-anthropic/tests/input-modalities.test.ts b/packages/ai-anthropic/tests/input-modalities.test.ts
new file mode 100644
index 0000000000..b6913b323f
--- /dev/null
+++ b/packages/ai-anthropic/tests/input-modalities.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+import { AnthropicTextAdapter } from '../src/adapters/text'
+
+// Constructing the SDK client makes no network call.
+const config = { apiKey: 'test-key' }
+
+describe('Anthropic text adapter inputModalities', () => {
+  it('gives the input list of each known model', () => {
+    const expected = ['text', 'image', 'document']
+
+    expect(
+      new AnthropicTextAdapter(config, 'claude-opus-5-5').inputModalities,
+    ).toEqual(expected)
+    expect(
+      new AnthropicTextAdapter(config, 'claude-haiku-4-5').inputModalities,
+    ).toEqual(expected)
+  })
+
+  it('is undefined for a model the metadata does not list', () => {
+    // A JS caller, or a model id newer than this package, reaches the adapter.
+    // @ts-expect-error - 'claude-unknown-9000' is not a declared model
+    const adapter = new AnthropicTextAdapter(config, 'claude-unknown-9000')
+
+    expect(adapter.inputModalities).toBeUndefined()
+  })
+})
diff --git a/packages/ai-byteplus/src/adapters/text.ts b/packages/ai-byteplus/src/adapters/text.ts
index 751399c179..34ff423edc 100644
--- a/packages/ai-byteplus/src/adapters/text.ts
+++ b/packages/ai-byteplus/src/adapters/text.ts
@@ -7,6 +7,7 @@ import {
 import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
 import { generateId } from '@tanstack/ai-utils'
 import {
+  BYTEPLUS_MODEL_INPUT_MODALITIES,
   BYTEPLUS_STRUCTURED_OUTPUT_CHAT_MODELS,
   emitsEncryptedContent,
   supportsStructuredOutput,
@@ -107,6 +108,8 @@ export class BytePlusTextAdapter<
 > {
   override readonly kind = 'text' as const
   override readonly name = 'byteplus' as const
+  override readonly inputModalities =
+    BYTEPLUS_MODEL_INPUT_MODALITIES[this.model]
 
   constructor(config: BytePlusTextConfig, model: TModel) {
     super(
diff --git a/packages/ai-byteplus/src/model-meta.ts b/packages/ai-byteplus/src/model-meta.ts
index 9f1a126bc3..d6e85f035d 100644
--- a/packages/ai-byteplus/src/model-meta.ts
+++ b/packages/ai-byteplus/src/model-meta.ts
@@ -19,6 +19,7 @@
  * - The Seedance 2.0 family *requires* the `dreamina-` prefix.
  * - Older models reject the `dola-` prefix outright.
  */
+import type { Modality } from '@tanstack/ai'
 import type { DurationOptions } from '@tanstack/ai/adapters'
 import type { BytePlusTextProviderOptions } from './text/text-provider-options'
 
@@ -452,6 +453,35 @@ export type BytePlusModelInputModalitiesByName = {
   [GPT_OSS_120B_250805.name]: typeof GPT_OSS_120B_250805.supports.input
 }
 
+/**
+ * Runtime map from chat model name to its supported input modalities, read
+ * by the text adapter's `inputModalities`. `satisfies` ties it to
+ * {@link BytePlusModelInputModalitiesByName}, so the two cannot drift.
+ */
+export const BYTEPLUS_MODEL_INPUT_MODALITIES: Readonly<
+  Record<string, ReadonlyArray<Modality>>
+> = {
+  [DOLA_SEED_2_1_TURBO.name]: DOLA_SEED_2_1_TURBO.supports.input,
+  [SEED_2_0_LITE_260428.name]: SEED_2_0_LITE_260428.supports.input,
+  [SEED_2_0_MINI_260428.name]: SEED_2_0_MINI_260428.supports.input,
+  [SEED_2_0_PRO_260328.name]: SEED_2_0_PRO_260328.supports.input,
+  [SEED_2_0_LITE_260228.name]: SEED_2_0_LITE_260228.supports.input,
+  [SEED_2_0_MINI_260215.name]: SEED_2_0_MINI_260215.supports.input,
+  [SEED_2_0_CODE_PREVIEW_260328.name]:
+    SEED_2_0_CODE_PREVIEW_260328.supports.input,
+  [SEED_1_8_251228.name]: SEED_1_8_251228.supports.input,
+  [SEED_1_6_250915.name]: SEED_1_6_250915.supports.input,
+  [SEED_1_6_250615.name]: SEED_1_6_250615.supports.input,
+  [SEED_1_6_FLASH_250715.name]: SEED_1_6_FLASH_250715.supports.input,
+  [SEED_1_6_FLASH_250615.name]: SEED_1_6_FLASH_250615.supports.input,
+  [GLM_5_2_260617.name]: GLM_5_2_260617.supports.input,
+  [GLM_4_7_251222.name]: GLM_4_7_251222.supports.input,
+  [DEEPSEEK_V4_PRO_260425.name]: DEEPSEEK_V4_PRO_260425.supports.input,
+  [DEEPSEEK_V4_FLASH_260425.name]: DEEPSEEK_V4_FLASH_260425.supports.input,
+  [DEEPSEEK_V3_2_251201.name]: DEEPSEEK_V3_2_251201.supports.input,
+  [GPT_OSS_120B_250805.name]: GPT_OSS_120B_250805.supports.input,
+} satisfies BytePlusModelInputModalitiesByName
+
 /**
  * Type-only map from chat model name to its supported provider tools.
  * BytePlus exposes no provider-tool factories, so every model gets an empty
diff --git a/packages/ai-byteplus/tests/input-modalities.test.ts b/packages/ai-byteplus/tests/input-modalities.test.ts
new file mode 100644
index 0000000000..2e235da8f5
--- /dev/null
+++ b/packages/ai-byteplus/tests/input-modalities.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest'
+import { createBytePlusText } from '../src/adapters/text'
+
+describe('BytePlusTextAdapter inputModalities', () => {
+  it.each([
+    ['seed-2-0-lite-260428', ['text', 'image', 'video', 'audio']],
+    ['glm-5-2-260617', ['text']],
+  ] as const)('reads the list of %s from model-meta', (model, expected) => {
+    expect(createBytePlusText(model, 'ark-test-key').inputModalities).toEqual(
+      expected,
+    )
+  })
+
+  it('is undefined for a model id that model-meta does not list', () => {
+    // @ts-expect-error a JS caller or a cast can pass an id the types reject
+    const adapter = createBytePlusText('unlisted-model', 'ark-test-key')
+
+    expect(adapter.inputModalities).toBeUndefined()
+  })
+})
diff --git a/packages/ai-gemini/src/adapters/text.ts b/packages/ai-gemini/src/adapters/text.ts
index 13828b6f10..28ffc9c3cb 100644
--- a/packages/ai-gemini/src/adapters/text.ts
+++ b/packages/ai-gemini/src/adapters/text.ts
@@ -14,7 +14,10 @@ import {
   generateId,
   getGeminiApiKeyFromEnv,
 } from '../utils'
-import { GEMINI_COMBINED_TOOLS_AND_SCHEMA_MODELS } from '../model-meta'
+import {
+  GEMINI_COMBINED_TOOLS_AND_SCHEMA_MODELS,
+  GEMINI_MODEL_INPUT_MODALITIES,
+} from '../model-meta'
 import type {
   GEMINI_MODELS,
   GeminiChatModelProviderOptionsByName,
@@ -248,6 +251,7 @@ export class GeminiTextAdapter<
   readonly name = 'gemini' as const
   // Consumes Gemini Files API references (geminiFiles()) as fileData.fileUri.
   override readonly supportsFileSources = true
+  override readonly inputModalities = GEMINI_MODEL_INPUT_MODALITIES[this.model]
 
   private readonly client: GoogleGenAI
 
diff --git a/packages/ai-gemini/src/model-meta.ts b/packages/ai-gemini/src/model-meta.ts
index fe9e0de8de..6a673c8049 100644
--- a/packages/ai-gemini/src/model-meta.ts
+++ b/packages/ai-gemini/src/model-meta.ts
@@ -1,3 +1,4 @@
+import type { Modality } from '@tanstack/ai'
 import type {
   GeminiCachedContentOptions,
   GeminiCommonConfigOptions,
@@ -1389,3 +1390,26 @@ export type GeminiModelInputModalitiesByName = {
   // Models with text, image, audio, video (no document)
   [GEMINI_2_5_FLASH.name]: typeof GEMINI_2_5_FLASH.supports.input
 }
+
+/**
+ * Runtime map from chat model name to its supported input modalities, for the
+ * text adapter's `inputModalities`. `satisfies` keeps it equal to
+ * {@link GeminiModelInputModalitiesByName}. An unknown name gives `undefined`.
+ */
+export const GEMINI_MODEL_INPUT_MODALITIES: Readonly<
+  Record<string, ReadonlyArray<Modality>>
+> = {
+  [GEMINI_3_8_FLASH.name]: GEMINI_3_8_FLASH.supports.input,
+  [GEMINI_3_7_FLASH.name]: GEMINI_3_7_FLASH.supports.input,
+  [GEMINI_3_6_FLASH.name]: GEMINI_3_6_FLASH.supports.input,
+  [GEMINI_3_5_FLASH.name]: GEMINI_3_5_FLASH.supports.input,
+  [GEMINI_3_5_FLASH_LITE.name]: GEMINI_3_5_FLASH_LITE.supports.input,
+  [GEMINI_3_1_PRO.name]: GEMINI_3_1_PRO.supports.input,
+  [GEMINI_3_FLASH.name]: GEMINI_3_FLASH.supports.input,
+  [GEMINI_3_1_FLASH_LITE.name]: GEMINI_3_1_FLASH_LITE.supports.input,
+  [GEMINI_3_1_FLASH_LITE_PREVIEW.name]:
+    GEMINI_3_1_FLASH_LITE_PREVIEW.supports.input,
+  [GEMINI_2_5_PRO.name]: GEMINI_2_5_PRO.supports.input,
+  [GEMINI_2_5_FLASH_LITE.name]: GEMINI_2_5_FLASH_LITE.supports.input,
+  [GEMINI_2_5_FLASH.name]: GEMINI_2_5_FLASH.supports.input,
+} satisfies GeminiModelInputModalitiesByName
diff --git a/packages/ai-gemini/tests/input-modalities.test.ts b/packages/ai-gemini/tests/input-modalities.test.ts
new file mode 100644
index 0000000000..c0d6642791
--- /dev/null
+++ b/packages/ai-gemini/tests/input-modalities.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { GeminiTextAdapter } from '../src/adapters/text'
+
+// Constructing the SDK client makes no network call.
+const config = { apiKey: 'test-key' }
+
+describe('Gemini text adapter inputModalities', () => {
+  it('gives the input list of each known model', () => {
+    expect(
+      new GeminiTextAdapter(config, 'gemini-3.1-pro-preview').inputModalities,
+    ).toEqual(['text', 'image', 'audio', 'video', 'document'])
+    expect(
+      new GeminiTextAdapter(config, 'gemini-2.5-flash').inputModalities,
+    ).toEqual(['text', 'image', 'audio', 'video'])
+  })
+
+  it('is undefined for a model the metadata does not list', () => {
+    // A JS caller, or a model id newer than this package, reaches the adapter.
+    // @ts-expect-error - 'gemini-unknown-9000' is not a declared model
+    const adapter = new GeminiTextAdapter(config, 'gemini-unknown-9000')
+
+    expect(adapter.inputModalities).toBeUndefined()
+  })
+})
diff --git a/packages/ai-grok/src/adapters/text.ts b/packages/ai-grok/src/adapters/text.ts
index 346de08450..0f36af0510 100644
--- a/packages/ai-grok/src/adapters/text.ts
+++ b/packages/ai-grok/src/adapters/text.ts
@@ -1,6 +1,7 @@
 import OpenAI from 'openai'
 import { fileReferenceFor, isFileSource } from '@tanstack/ai'
 import { OpenAIBaseResponsesTextAdapter } from '@tanstack/openai-base'
+import { GROK_MODEL_INPUT_MODALITIES } from '../model-meta'
 import { getGrokApiKeyFromEnv, withGrokDefaults } from '../utils/client'
 import { convertToolsToProviderFormat } from '../tools'
 import type {
@@ -70,6 +71,7 @@ export class GrokTextAdapter<
   // public URL. See convertContentPartToInput below for why it is a URL and
   // not a file_id.
   override readonly supportsFileSources = true
+  override readonly inputModalities = GROK_MODEL_INPUT_MODALITIES[this.model]
 
   constructor(config: GrokTextConfig, model: TModel) {
     super(model, 'grok', new OpenAI(withGrokDefaults(config)))
diff --git a/packages/ai-grok/src/model-meta.ts b/packages/ai-grok/src/model-meta.ts
index 3fdb6278a3..21a0817a88 100644
--- a/packages/ai-grok/src/model-meta.ts
+++ b/packages/ai-grok/src/model-meta.ts
@@ -1,6 +1,7 @@
 /**
  * Model metadata interface for documentation and type inference
  */
+import type { Modality } from '@tanstack/ai'
 import type {
   GrokBuildProviderOptions,
   GrokTextProviderOptions,
@@ -436,6 +437,26 @@ export type GrokModelInputModalitiesByName = {
   [GROK_4_7.name]: typeof GROK_4_7.supports.input
 }
 
+/**
+ * Runtime map from Grok chat model name to its supported input modalities,
+ * read by the text adapter's `inputModalities`. `satisfies` ties it to
+ * {@link GrokModelInputModalitiesByName}, so the two cannot drift.
+ */
+export const GROK_MODEL_INPUT_MODALITIES: Readonly<
+  Record<string, ReadonlyArray<Modality>>
+> = {
+  [GROK_4_3.name]: GROK_4_3.supports.input,
+  [GROK_BUILD_0_1.name]: GROK_BUILD_0_1.supports.input,
+  [GROK_4_5.name]: GROK_4_5.supports.input,
+  [GROK_4_6.name]: GROK_4_6.supports.input,
+  [GROK_4_20_REASONING.name]: GROK_4_20_REASONING.supports.input,
+  [GROK_4_20_NON_REASONING.name]: GROK_4_20_NON_REASONING.supports.input,
+  [GROK_4_1_FAST_REASONING.name]: GROK_4_1_FAST_REASONING.supports.input,
+  [GROK_4_1_FAST_NON_REASONING.name]:
+    GROK_4_1_FAST_NON_REASONING.supports.input,
+  [GROK_4_7.name]: GROK_4_7.supports.input,
+} satisfies GrokModelInputModalitiesByName
+
 /**
  * Type-only map from Grok chat model name to its supported provider tools.
  * Keeps Grok provider-tool factories type-checked against the models that
diff --git a/packages/ai-grok/tests/input-modalities.test.ts b/packages/ai-grok/tests/input-modalities.test.ts
new file mode 100644
index 0000000000..8c1e20b2e3
--- /dev/null
+++ b/packages/ai-grok/tests/input-modalities.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+import { createGrokText } from '../src/adapters/text'
+
+describe('GrokTextAdapter inputModalities', () => {
+  it.each([
+    ['grok-4.7', ['text', 'image', 'document']],
+    ['grok-build-0.1', ['text', 'image']],
+  ] as const)('reads the list of %s from model-meta', (model, expected) => {
+    expect(createGrokText(model, 'test-key').inputModalities).toEqual(expected)
+  })
+
+  it('is undefined for a model id that model-meta does not list', () => {
+    // @ts-expect-error a JS caller or a cast can pass an id the types reject
+    const adapter = createGrokText('unlisted-model', 'test-key')
+
+    expect(adapter.inputModalities).toBeUndefined()
+  })
+})
diff --git a/packages/ai-groq/src/adapters/text.ts b/packages/ai-groq/src/adapters/text.ts
index 583f76d52a..61affd3f9a 100644
--- a/packages/ai-groq/src/adapters/text.ts
+++ b/packages/ai-groq/src/adapters/text.ts
@@ -1,5 +1,6 @@
 import OpenAI from 'openai'
 import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
+import { GROQ_MODEL_INPUT_MODALITIES } from '../model-meta'
 import { getGroqApiKeyFromEnv, withGroqDefaults } from '../utils/client'
 import { makeGroqStructuredOutputCompatibleWithMap } from '../utils/schema-converter'
 import type { Modality, TextOptions } from '@tanstack/ai'
@@ -58,6 +59,7 @@ export class GroqTextAdapter<
 > {
   override readonly kind = 'text' as const
   override readonly name = 'groq' as const
+  override readonly inputModalities = GROQ_MODEL_INPUT_MODALITIES[this.model]
 
   constructor(config: GroqTextConfig, model: TModel) {
     super(model, 'groq', new OpenAI(withGroqDefaults(config)), config)
diff --git a/packages/ai-groq/src/model-meta.ts b/packages/ai-groq/src/model-meta.ts
index 6eab05cc80..94f6cd6983 100644
--- a/packages/ai-groq/src/model-meta.ts
+++ b/packages/ai-groq/src/model-meta.ts
@@ -1,3 +1,4 @@
+import type { Modality } from '@tanstack/ai'
 import type { GroqTextProviderOptions } from './text/text-provider-options'
 import type { GroqTTSProviderOptions } from './audio/tts-provider-options'
 
@@ -358,6 +359,30 @@ export type GroqModelInputModalitiesByName = {
   [QWEN3_32B.name]: typeof QWEN3_32B.supports.input
 }
 
+/**
+ * Runtime map from Groq chat model name to its supported input modalities,
+ * read by the text adapter's `inputModalities`. `satisfies` ties it to
+ * {@link GroqModelInputModalitiesByName}, so the two cannot drift.
+ */
+export const GROQ_MODEL_INPUT_MODALITIES: Readonly<
+  Record<string, ReadonlyArray<Modality>>
+> = {
+  [LLAMA_3_1_8B_INSTANT.name]: LLAMA_3_1_8B_INSTANT.supports.input,
+  [LLAMA_3_3_70B_VERSATILE.name]: LLAMA_3_3_70B_VERSATILE.supports.input,
+  [LLAMA_4_MAVERICK_17B_128E_INSTRUCT.name]:
+    LLAMA_4_MAVERICK_17B_128E_INSTRUCT.supports.input,
+  [LLAMA_4_SCOUT_17B_16E_INSTRUCT.name]:
+    LLAMA_4_SCOUT_17B_16E_INSTRUCT.supports.input,
+  [LLAMA_GUARD_4_12B.name]: LLAMA_GUARD_4_12B.supports.input,
+  [LLAMA_PROMPT_GUARD_2_86M.name]: LLAMA_PROMPT_GUARD_2_86M.supports.input,
+  [LLAMA_PROMPT_GUARD_2_22M.name]: LLAMA_PROMPT_GUARD_2_22M.supports.input,
+  [GPT_OSS_20B.name]: GPT_OSS_20B.supports.input,
+  [GPT_OSS_120B.name]: GPT_OSS_120B.supports.input,
+  [GPT_OSS_SAFEGUARD_20B.name]: GPT_OSS_SAFEGUARD_20B.supports.input,
+  [KIMI_K2_INSTRUCT_0905.name]: KIMI_K2_INSTRUCT_0905.supports.input,
+  [QWEN3_32B.name]: QWEN3_32B.supports.input,
+} satisfies GroqModelInputModalitiesByName
+
 /**
  * Type-only map from Groq chat model name to its provider options type.
  */
diff --git a/packages/ai-groq/tests/input-modalities.test.ts b/packages/ai-groq/tests/input-modalities.test.ts
new file mode 100644
index 0000000000..3229ee42e8
--- /dev/null
+++ b/packages/ai-groq/tests/input-modalities.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+import { createGroqText } from '../src/adapters/text'
+
+describe('GroqTextAdapter inputModalities', () => {
+  it.each([
+    ['meta-llama/llama-4-scout-17b-16e-instruct', ['text', 'image']],
+    ['llama-3.3-70b-versatile', ['text']],
+  ] as const)('reads the list of %s from model-meta', (model, expected) => {
+    expect(createGroqText(model, 'test-key').inputModalities).toEqual(expected)
+  })
+
+  it('is undefined for a model id that model-meta does not list', () => {
+    // @ts-expect-error a JS caller or a cast can pass an id the types reject
+    const adapter = createGroqText('unlisted-model', 'test-key')
+
+    expect(adapter.inputModalities).toBeUndefined()
+  })
+})
diff --git a/packages/ai-harness/src/client.ts b/packages/ai-harness/src/client.ts
index 9896e42243..0c865699da 100644
--- a/packages/ai-harness/src/client.ts
+++ b/packages/ai-harness/src/client.ts
@@ -1,5 +1,6 @@
 // Browser-safe: this module has type-only imports from the rest of the
-// package, so no server code (adapters, stores, secrets) reaches a client.
+// package, plus `media-ref`, which has type-only imports itself. So no server
+// code (adapters, stores, secrets) reaches a client.
 import type { ModelMessage, RunAgentResumeItem } from '@tanstack/ai'
 import type { AgentInputOf } from './agents'
 import type { AnyHarness, HarnessAgentsOf } from './define'
@@ -8,11 +9,21 @@ import type {
   BusyPolicy,
   Cursor,
   HarnessInput,
+  MediaRecord,
   Receipt,
   SessionEvent,
   UserInput,
 } from './types'
 
+export {
+  MEDIA_URL_PREFIX,
+  kindOf,
+  mediaIdOf,
+  mediaOfMessage,
+  mediaPart,
+} from './media-ref'
+export type { MediaKind, MediaRecord } from './types'
+
 export interface HarnessClientOptions {
   /** The base URL of `createHarnessHandler`, for example `/api/harness`. */
   url: string
@@ -68,6 +79,36 @@ export interface HarnessClient<THarness extends AnyHarness> {
   transcript: () => Promise<Array<ModelMessage>>
   /** The commands, settings, and tools of the session. */
   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>
+}
+
+// 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'
+  )
 }
 
 /**
@@ -85,6 +126,18 @@ export function createHarnessClient<THarness extends AnyHarness>(
       ? 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}`,
+    )
+  }
+
   const send = async (input: HarnessInput): Promise<Receipt> => {
     const response = await doFetch(`${base}/control`, {
       method: 'POST',
@@ -92,29 +145,63 @@ export function createHarnessClient<THarness extends AnyHarness>(
       body: JSON.stringify({ threadId: options.threadId, input }),
     })
     const body: unknown = await response.json()
-    if (!response.ok) {
-      const message =
-        typeof body === 'object' && body !== null && 'error' in body
-          ? String(body.error)
-          : response.statusText
-      throw new Error(`Harness request failed (${response.status}): ${message}`)
-    }
+    if (!response.ok) throw failure('request', response, body)
     // The handler answers /control with a Receipt.
     return body as Receipt
   }
 
-  const read = async <T>(route: string) => {
-    const query = new URLSearchParams({ threadId: options.threadId })
+  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) =>
     // Each GET route answers with the type of the `HarnessClient` member
     // that reads it. That member type sets `T`.
-    return (await response.json()) as T
+    (await (await get(route)).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,
+    })
+    if (!response.ok) {
+      // A proxy can refuse a big upload with a page, not JSON.
+      const refusal: unknown = await response.json().catch(() => undefined)
+      throw failure('upload', response, refusal)
+    }
+    // The handler answers POST media with the stored MediaRecord.
+    // ponytail: no shape check here; `isMediaRecord` in media-ref.ts is not
+    // exported yet. Export it and narrow instead of this cast.
+    return (await response.json()) as MediaRecord
   }
 
+  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())
+
   async function* events(
     eventOptions: {
       from?: Cursor
@@ -221,5 +308,8 @@ export function createHarnessClient<THarness extends AnyHarness>(
     snapshot: () => read('snapshot'),
     transcript: () => read('transcript'),
     describe: () => read('describe'),
+    upload,
+    mediaUrl,
+    loadMedia,
   }
 }
diff --git a/packages/ai-harness/src/media.ts b/packages/ai-harness/src/media.ts
new file mode 100644
index 0000000000..371575708f
--- /dev/null
+++ b/packages/ai-harness/src/media.ts
@@ -0,0 +1,472 @@
+// The server side of harness media: the store, capture of generated media,
+// and the chat middleware that gives the model the bytes.
+import { generateTranscription } from '@tanstack/ai'
+import {
+  resolveBlobRange,
+  retrieveBlob,
+  withGenerationPersistence,
+} from '@tanstack/ai-persistence'
+import { kindOf, mediaIdOf } from './media-ref'
+import type {
+  AnyTranscriptionAdapter,
+  ChatMiddleware,
+  ChatMiddlewareContext,
+  ContentPart,
+  GenerationMiddleware,
+  Modality,
+  ModelMessage,
+  PersistedArtifactRef,
+} from '@tanstack/ai'
+import type {
+  AIPersistence,
+  ArtifactRecord,
+  ArtifactStore,
+  BlobBody,
+  BlobRange,
+  BlobStore,
+  GenerationRunStore,
+} from '@tanstack/ai-persistence'
+import type { MediaKind, MediaRecord } from './types'
+
+/** The `media` option of a harness: limits, and what the model reads. */
+export interface MediaOptions {
+  /** Refuse a file bigger than this many bytes. Default 100 MB. */
+  maxBytes?: number
+  /** The kinds a user can send. Default: all four. */
+  kinds?: ReadonlyArray<MediaKind>
+  /** The kinds the model reads. Narrows what the adapter says it reads. */
+  accepts?: ReadonlyArray<MediaKind>
+  /** Turns audio into text first when the model cannot read audio. */
+  transcribe?: AnyTranscriptionAdapter
+}
+
+/**
+ * A media request that failed. `status` is the HTTP status a route answers:
+ * 404 (not found, or another thread's), 413 (too big), 415 (type not allowed).
+ */
+export class MediaError extends Error {
+  readonly status: 404 | 413 | 415
+  constructor(status: 404 | 413 | 415, message: string) {
+    super(message)
+    this.name = 'MediaError'
+    this.status = status
+  }
+}
+
+/** The stores media lives in. */
+export type MediaPersistence = AIPersistence<{
+  artifacts: ArtifactStore
+  blobs: BlobStore
+}>
+
+/** The media store of one thread. */
+export type MediaStore = ReturnType<typeof createMediaStore>
+
+const DEFAULT_MAX_BYTES = 100 * 1024 * 1024
+const DATA_URL_MAX_BYTES = 1024 * 1024
+const ALL_KINDS: ReadonlyArray<MediaKind> = [
+  'image',
+  'audio',
+  'video',
+  'document',
+]
+
+// Uploads are artifact records with the run id `upload:<threadId>`, and their
+// bytes use the default artifact key `artifacts/<runId>/<id>`. Generated media
+// keeps what `withGenerationPersistence` gives it: a generation run id
+// `<operation>[:<subagentRunId>...]:<activity>-<n>`.
+function uploadRunId(threadId: string) {
+  return `upload:${threadId}`
+}
+
+function toMediaRecord(record: ArtifactRecord, kind: MediaKind) {
+  const isUpload = record.runId === uploadRunId(record.threadId)
+  const segments = isUpload ? [] : record.runId.split(':')
+  const [runId] = segments
+  const subagentRunId = segments.findLast((segment) =>
+    segment.startsWith('subagent-'),
+  )
+  const media: MediaRecord = {
+    id: record.artifactId,
+    threadId: record.threadId,
+    kind,
+    mimeType: record.mimeType,
+    name: record.name,
+    size: record.size,
+    source: isUpload ? 'user' : 'generated',
+    createdAt: record.createdAt,
+    ...(runId ? { runId } : {}),
+    ...(subagentRunId ? { subagentRunId } : {}),
+  }
+  return media
+}
+
+/** The byte length of a body, or `undefined` for a stream. */
+function sizeOf(body: BlobBody) {
+  if (typeof body === 'string') return new TextEncoder().encode(body).byteLength
+  if (body instanceof Blob) return body.size
+  if (body instanceof ReadableStream) return undefined
+  return body.byteLength
+}
+
+/**
+ * Base64 of `bytes`. It uses `btoa`, not the Node `Buffer`, so it runs on
+ * workerd too.
+ */
+export 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)
+}
+
+/**
+ * The media store of one thread, on the persistence `artifacts` and `blobs`
+ * stores. It sees only the media of `threadId`: an id of another thread reads
+ * as not found.
+ *
+ * `put` throws a `MediaError` with 413 (over `maxBytes`) or 415 (a MIME type
+ * with no media kind, or a kind not in `kinds`). `load` throws a `MediaError`
+ * with 404 when the record or its bytes are missing.
+ *
+ * @example
+ * const media = createMediaStore({ persistence, threadId })
+ * const record = await media.put(bytes, { mimeType: 'image/png', name: 'cat.png' })
+ * const url = await media.dataUrl(record.id)
+ */
+export function createMediaStore({
+  persistence,
+  threadId,
+  options = {},
+}: {
+  persistence: MediaPersistence
+  threadId: string
+  options?: MediaOptions
+}) {
+  const { artifacts, blobs } = persistence.stores
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES
+  const kinds = options.kinds ?? ALL_KINDS
+  const tooBig = () =>
+    new MediaError(
+      413,
+      `The file is bigger than the limit of ${maxBytes} bytes.`,
+    )
+
+  async function artifact(id: string) {
+    const record = await artifacts.get(id)
+    return record?.threadId === threadId ? record : null
+  }
+
+  async function get(id: string) {
+    const record = await artifact(id)
+    const kind = record ? kindOf(record.mimeType) : undefined
+    return record && kind ? toMediaRecord(record, kind) : null
+  }
+
+  async function load(id: string, range?: BlobRange) {
+    const record = await artifact(id)
+    const blob = record
+      ? await retrieveBlob(
+          persistence,
+          record,
+          range ? { range: resolveBlobRange(record.size, range) } : undefined,
+        )
+      : null
+    if (!blob) throw new MediaError(404, `Media ${id} was not found.`)
+    return new Uint8Array(await blob.arrayBuffer())
+  }
+
+  return {
+    /** Store a user file. Returns its record. */
+    async put(body: BlobBody, info: { mimeType: string; name: string }) {
+      const kind = kindOf(info.mimeType)
+      if (kind === undefined) {
+        throw new MediaError(
+          415,
+          `Files of type ${info.mimeType} are not supported.`,
+        )
+      }
+      if (!kinds.includes(kind)) {
+        throw new MediaError(415, `This harness does not accept ${kind} files.`)
+      }
+      const size = sizeOf(body)
+      if (size !== undefined && size > maxBytes) throw tooBig()
+
+      const id = crypto.randomUUID()
+      const runId = uploadRunId(threadId)
+      const blobKey = `artifacts/${runId}/${id}`
+      // A stream has no length up front, so count it as the store reads it.
+      let seen = 0
+      const counted =
+        body instanceof ReadableStream
+          ? body.pipeThrough(
+              new TransformStream({
+                transform(bytes: Uint8Array, controller) {
+                  seen += bytes.byteLength
+                  if (seen > maxBytes) controller.error(tooBig())
+                  else controller.enqueue(bytes)
+                },
+              }),
+            )
+          : body
+      try {
+        await blobs.put(blobKey, counted, { contentType: info.mimeType })
+      } catch (error) {
+        if (seen <= maxBytes) throw error
+        await blobs.delete(blobKey)
+        throw tooBig()
+      }
+      const record: ArtifactRecord = {
+        artifactId: id,
+        runId,
+        threadId,
+        blobKey,
+        name: info.name,
+        mimeType: info.mimeType,
+        size: size ?? seen,
+        createdAt: Date.now(),
+      }
+      await artifacts.save(record)
+      return toMediaRecord(record, kind)
+    },
+    /** The record of `id`, or `null` when it is missing or another thread's. */
+    get,
+    /** The bytes of `id`, or one `range` of them. */
+    load,
+    /** A data URL for a file up to 1 MB. `undefined` above that. */
+    async dataUrl(id: string) {
+      const record = await get(id)
+      if (!record || record.size > DATA_URL_MAX_BYTES) return undefined
+      return `data:${record.mimeType};base64,${toBase64(await load(id))}`
+    },
+  }
+}
+
+/**
+ * Generation middleware that keeps the media an agent makes and publishes a
+ * record for each new file. It is `withGenerationPersistence` plus a result
+ * transform that runs after it.
+ *
+ * A failed save or a failed `publish` does not fail the generation: the agent
+ * gets its result, and `onError` gets the error, so the caller can warn.
+ *
+ * @example
+ * const middleware = mediaCapture({
+ *   persistence,
+ *   threadId,
+ *   publish: (record) => console.log(`saved ${record.name}`),
+ *   onError: (error) => console.warn('media not kept', error),
+ * })
+ * await generateImage({ adapter, prompt, threadId, middleware })
+ */
+export function mediaCapture({
+  persistence,
+  threadId,
+  options = {},
+  publish,
+  onError,
+}: {
+  persistence: AIPersistence<{
+    artifacts: ArtifactStore
+    blobs: BlobStore
+    generationRuns: GenerationRunStore
+  }>
+  threadId: string
+  options?: MediaOptions
+  publish: (record: MediaRecord) => void | Promise<void>
+  onError?: (error: unknown) => void
+}) {
+  const store = createMediaStore({ persistence, threadId, options })
+  const persist = withGenerationPersistence(persistence, {
+    threadId,
+    maxArtifactBytes: options.maxBytes ?? DEFAULT_MAX_BYTES,
+  })
+  const keep: GenerationMiddleware = {
+    ...persist,
+    async onStart(ctx) {
+      const from = ctx.resultTransforms.length
+      await persist.onStart?.(ctx)
+      // Guard the transforms that save the bytes, so a store failure (or a
+      // file over the limit) keeps the agent's result.
+      const added = ctx.resultTransforms.splice(from)
+      for (const transform of added) {
+        ctx.resultTransforms.push(async (result, transformCtx) => {
+          try {
+            return await transform(result, transformCtx)
+          } catch (error) {
+            onError?.(error)
+            return undefined
+          }
+        })
+      }
+    },
+  }
+  const announce: GenerationMiddleware = {
+    name: 'harness:media-capture',
+    onStart(ctx) {
+      const runId = ctx.runId ?? ctx.requestId
+      // `artifacts` is what the persistence transform above added.
+      ctx.resultTransforms.push(
+        async (result: { artifacts?: Array<PersistedArtifactRef> }) => {
+          const refs = (result.artifacts ?? []).filter(
+            (ref) => ref.role === 'output' && ref.runId === runId,
+          )
+          for (const ref of refs) {
+            try {
+              const record = await store.get(ref.artifactId)
+              if (record) await publish(record)
+            } catch (error) {
+              onError?.(error)
+            }
+          }
+          return undefined
+        },
+      )
+    },
+  }
+  return [keep, announce]
+}
+
+type MediaContentPart = Exclude<ContentPart, { type: 'text' }>
+
+function textPart(content: string) {
+  const part: ContentPart = { type: 'text', content }
+  return part
+}
+
+function cannotRead(model: string, kind: MediaKind) {
+  const fix =
+    kind === 'audio'
+      ? 'Add media.transcribe'
+      : `Use a model that reads ${kind} files`
+  return `${model} cannot read ${kind} files. ${fix}, or send a text summary.`
+}
+
+function hasMediaRef(message: ModelMessage) {
+  return (
+    Array.isArray(message.content) &&
+    message.content.some((part) => mediaIdOf(part) !== undefined)
+  )
+}
+
+/**
+ * Chat middleware that gives the model the bytes of `harness-media:` parts.
+ * It changes only what the adapter gets (`providerMessages`), so the saved
+ * transcript keeps the small `harness-media:` URLs.
+ *
+ * - A part of a kind in `accepted` becomes a base64 data source. With
+ *   `accepted` undefined, every kind is sent.
+ * - Audio not in `accepted` becomes a transcript when `transcribe` is set.
+ * - Any other kind not in `accepted` stops the run with a clear error before
+ *   the model call.
+ * - A part whose file is gone becomes a short text note.
+ *
+ * List it after `withPersistence` and after any middleware that returns
+ * `messages`: a later `messages` result resets the provider messages.
+ *
+ * @example
+ * chat({
+ *   adapter,
+ *   messages,
+ *   middleware: [withPersistence(persistence), mediaMiddleware({ store })],
+ * })
+ */
+export function mediaMiddleware({
+  store,
+  accepted,
+  transcribe,
+}: {
+  store: MediaStore
+  accepted?: ReadonlyArray<Modality>
+  transcribe?: AnyTranscriptionAdapter
+}) {
+  // ponytail: one cache per run, so the loop does not load or transcribe a
+  // file again at every model call. A new turn does it again for history.
+  const runs = new WeakMap<object, Map<string, Promise<ContentPart>>>()
+
+  async function resolve(
+    ctx: ChatMiddlewareContext,
+    part: MediaContentPart,
+    id: string,
+  ) {
+    const record = await store.get(id)
+    if (!record) return textPart(`[${part.type} not found: ${id}]`)
+    const isAccepted = accepted === undefined || accepted.includes(record.kind)
+    const transcriber =
+      isAccepted || record.kind !== 'audio' ? undefined : transcribe
+    if (!isAccepted && transcriber === undefined) {
+      throw new Error(cannotRead(ctx.model, record.kind))
+    }
+    const bytes = await store.load(id).catch((error: unknown) => {
+      if (error instanceof MediaError && error.status === 404) return undefined
+      throw error
+    })
+    if (!bytes) return textPart(`[${record.kind} not found: ${record.name}]`)
+    if (transcriber === undefined) {
+      const swapped: ContentPart = {
+        ...part,
+        source: {
+          type: 'data',
+          value: toBase64(bytes),
+          mimeType: record.mimeType,
+        },
+      }
+      return swapped
+    }
+    const transcript = await generateTranscription({
+      adapter: transcriber,
+      audio: new Blob([bytes], { type: record.mimeType }),
+      ...(ctx.signal ? { abortSignal: ctx.signal } : {}),
+    })
+    return textPart(`[audio transcript: ${record.name}] ${transcript.text}`)
+  }
+
+  async function resolveMessage(
+    ctx: ChatMiddlewareContext,
+    cache: Map<string, Promise<ContentPart>>,
+    message: ModelMessage,
+  ) {
+    const { content } = message
+    if (!Array.isArray(content) || !hasMediaRef(message)) return message
+    const parts: Array<ContentPart> = []
+    for (const part of content) {
+      const id = part.type === 'text' ? undefined : mediaIdOf(part)
+      if (part.type === 'text' || id === undefined) {
+        parts.push(part)
+        continue
+      }
+      let pending = cache.get(id)
+      if (!pending) {
+        pending = resolve(ctx, part, id)
+        cache.set(id, pending)
+      }
+      parts.push(await pending)
+    }
+    return { ...message, content: parts }
+  }
+
+  const middleware: ChatMiddleware = {
+    name: 'harness:media',
+    // `init` runs before the user turn is stored, so a refusal stops the send
+    // early. `beforeModel` builds the provider messages again, so it runs
+    // there too (the cache makes that cheap).
+    async onConfig(ctx, config) {
+      const messages = config.providerMessages ?? config.messages
+      if (!messages.some(hasMediaRef)) return undefined
+      let cache = runs.get(ctx)
+      if (!cache) {
+        cache = new Map()
+        runs.set(ctx, cache)
+      }
+      const providerMessages: Array<ModelMessage> = []
+      for (const message of messages) {
+        providerMessages.push(await resolveMessage(ctx, cache, message))
+      }
+      return { providerMessages }
+    },
+  }
+  return middleware
+}
diff --git a/packages/ai-harness/src/view/index.ts b/packages/ai-harness/src/view/index.ts
index f8b3aace45..4975f3193e 100644
--- a/packages/ai-harness/src/view/index.ts
+++ b/packages/ai-harness/src/view/index.ts
@@ -1,28 +1,57 @@
 // Browser-safe: runtime imports only from @tanstack/ai, @tanstack/store,
-// ../types, and ./reduce. Everything else is a type.
+// ../types, ../media-ref, and ./reduce. Everything else is a type.
 import { EventType } from '@tanstack/ai'
 import { createStore } from '@tanstack/store'
+import { mediaPart } from '../media-ref'
 import { HARNESS_EVENTS } from '../types'
 import {
   applyDescription,
   applyEvent,
   applySnapshot,
   emptyState,
+  keep,
   messagesFromTranscript,
   withNotice,
   withUserMessage,
 } from './reduce'
-import type { ModelMessage, RunAgentResumeItem } from '@tanstack/ai'
+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'
-import type { Cursor, Receipt, SessionEvent } from '../types'
+import type {
+  Cursor,
+  MediaRecord,
+  Receipt,
+  SessionEvent,
+  UserInput,
+} from '../types'
 import type { ItemFactory } from './reduce'
-import type { Approval, SessionViewState, SignIn, ViewQuestion } from './types'
+import type {
+  Approval,
+  MediaPart,
+  SessionViewState,
+  SignIn,
+  ViewMessage,
+  ViewPart,
+  ViewQuestion,
+} from './types'
 
+export {
+  MEDIA_URL_PREFIX,
+  kindOf,
+  mediaIdOf,
+  mediaOfMessage,
+  mediaPart,
+} from '../media-ref'
+export type { MediaKind, MediaRecord } from '../types'
 export type {
   AgentPart,
   Approval,
+  MediaPart,
   NoticeKind,
   SessionViewState,
   SignIn,
@@ -35,10 +64,13 @@ export type {
   ViewQuestion,
 } from './types'
 
+/** 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: string) => unknown
-  steer: (message: string) => Promise<Receipt>
+  prompt: (message: UserInput) => unknown
+  steer: (message: UserInput) => Promise<Receipt>
   resolve: (resume: Array<RunAgentResumeItem>) => Promise<Receipt>
   cancel: (operationId?: string) => Promise<Receipt>
   answer: (questionId: string, value: unknown) => Promise<Receipt>
@@ -52,6 +84,10 @@ export interface SessionViewSource {
   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>
 }
 
 /** What `view.on(name, handler)` sends. */
@@ -80,8 +116,15 @@ export interface SessionView {
   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. Empty text does nothing. */
-  send: (text: string) => Promise<void>
+  /**
+   * A `/command`, a prompt, or a steer while a turn runs. `attachments` are
+   * stored media files (from `upload` or `putMedia`) that go with the text.
+   * A `/command` ignores them. Empty text with no attachments does nothing.
+   */
+  send: (
+    text: string,
+    attachments?: ReadonlyArray<MediaRecord>,
+  ) => Promise<void>
   command: (name: string, input?: unknown) => Promise<void>
   setConfig: (key: string, value: unknown) => Promise<void>
   cancel: () => Promise<void>
@@ -99,10 +142,19 @@ export interface SessionView {
     key: K,
     handler: (value: ViewEventValue<K>) => void,
   ) => () => void
-  /** Stop reading events. Later actions throw. */
+  /** 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
@@ -170,12 +222,16 @@ export function createSessionView(source: SessionViewSource) {
   const decisions = new Map<string, boolean>()
   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>>()
   let resolving = false
   let disposed = false
 
   const get = () => internal.state
   const commit = (next: SessionViewState) => {
-    if (!disposed && next !== internal.state) internal.setState(() => next)
+    if (disposed) return
+    const shown = withMediaActions(next)
+    if (shown !== internal.state) internal.setState(() => shown)
   }
   const emit = (key: string, value: unknown) => {
     const listeners = handlers.get(key) ?? []
@@ -205,6 +261,72 @@ export function createSessionView(source: SessionViewSource) {
     Promise.resolve(result).then(undefined, 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) => {
+    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 }
+  }
+
   const decide = (id: string, approved: boolean) => {
     alive()
     const open = get().approvals
@@ -405,22 +527,23 @@ export function createSessionView(source: SessionViewSource) {
   const view: SessionView = {
     store,
     ready,
-    send: async (text) => {
+    send: async (text, attachments = []) => {
       alive()
       const line = text.trim()
-      if (line === '') return
+      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))
+      commit(withUserMessage(get(), line, attachments))
+      const message = userInput(line, attachments)
       if (get().status === 'running') {
-        await source.steer(line).then(undefined, fail)
+        await source.steer(message).then(undefined, fail)
         return
       }
-      settle(source.prompt(line))
+      settle(source.prompt(message))
     },
     command: async (name, input) => {
       alive()
@@ -448,6 +571,8 @@ export function createSessionView(source: SessionViewSource) {
       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
index ae85982bf2..f16d167e0d 100644
--- a/packages/ai-harness/src/view/reduce.ts
+++ b/packages/ai-harness/src/view/reduce.ts
@@ -1,4 +1,5 @@
 import { EventType } from '@tanstack/ai'
+import { mediaIdOf, mediaOfMessage } from '../media-ref'
 import { HARNESS_EVENTS } from '../types'
 import type { Interrupt, ModelMessage, StreamChunk } from '@tanstack/ai'
 import type { SessionDescription, SessionSnapshot } from '../session'
@@ -6,6 +7,7 @@ import type { SessionEvent } from '../types'
 import type {
   AgentPart,
   Approval,
+  MediaPart,
   NoticeKind,
   SessionViewState,
   SignIn,
@@ -89,6 +91,66 @@ 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
+}
+
+/** The fields a media part needs from a `harness.media` event value. */
+function mediaInfoOf(value: Record<string, unknown>) {
+  const { id, kind, mimeType, name, size } = value
+  const isKind =
+    kind === 'image' ||
+    kind === 'audio' ||
+    kind === 'video' ||
+    kind === 'document'
+  const isInfo =
+    isKind &&
+    typeof id === 'string' &&
+    typeof mimeType === 'string' &&
+    typeof name === 'string' &&
+    typeof size === 'number'
+  if (!isInfo) return undefined
+  const info: MediaInfo = { id, kind, mimeType, name, size }
+  return info
+}
+
+/** Media parts for the `harness-media:` parts of a saved user message. */
+function userMedia(content: ModelMessage['content']) {
+  if (typeof content === 'string' || !content) return []
+  return content.flatMap((part) => {
+    const id = mediaIdOf(part)
+    if (id === undefined || part.type === 'text') return []
+    // ponytail: a saved part keeps only its id and MIME type, so the name is
+    // the id and the size is 0. Save the record on the message if a UI needs them.
+    return [
+      mediaView({
+        id,
+        kind: part.type,
+        mimeType: part.source.mimeType ?? '',
+        name: id,
+        size: 0,
+      }),
+    ]
+  })
+}
+
 /** Add a notice line at the end of the messages. */
 export function withNotice(
   state: SessionViewState,
@@ -104,15 +166,17 @@ export function withNotice(
   return { ...state, messages: [...state.messages, message] }
 }
 
-/** Add a user message at the end of the messages. */
+/** 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] }
 }
@@ -284,6 +348,31 @@ function updateTurn(
   return { ...state, messages }
 }
 
+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,
@@ -368,6 +457,13 @@ export function applyEvent(
   }
   if (event.type !== EventType.CUSTOM) return state
   const value = recordOf(event.value)
+  if (event.name === HARNESS_EVENTS.media) {
+    const media = mediaInfoOf(value)
+    if (!media) return state
+    const child =
+      typeof value.subagentRunId === 'string' ? value.subagentRunId : undefined
+    return withMedia(state, operationId, media, child)
+  }
   if (event.name === HARNESS_EVENTS.operationResumed)
     return withNotice(state, 'info', 'Resumed a turn that a crash stopped.')
   if (event.name === COMMAND_RESULT)
@@ -445,7 +541,7 @@ function markWaiting(
 }
 
 /** `old` when `next` holds the same items, so selectors see no change. */
-function keep<T>(old: Array<T>, next: Array<T>): Array<T> {
+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
@@ -535,7 +631,11 @@ export function applyDescription(
   }
 }
 
-/** Messages for a saved transcript. Tool results fill in their tool calls. */
+/**
+ * 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> {
@@ -543,7 +643,13 @@ export function messagesFromTranscript(
   messages.forEach((message, index) => {
     const id = message.id ?? `history-${index}`
     if (message.role === 'user') {
-      result.push({ id, role: 'user', text: textOf(message.content) })
+      const media = userMedia(message.content)
+      result.push({
+        id,
+        role: 'user',
+        text: textOf(message.content),
+        ...(media.length > 0 ? { media } : {}),
+      })
       return
     }
     if (message.role === 'assistant') {
@@ -564,6 +670,8 @@ export function messagesFromTranscript(
           status: 'running',
         })
       }
+      const media = mediaOfMessage(message)
+      for (const record of media) parts.push(mediaView(record))
       result.push({ id, role: 'assistant', parts })
       return
     }
diff --git a/packages/ai-harness/src/view/types.ts b/packages/ai-harness/src/view/types.ts
index 746a64d5f0..0d1671db7b 100644
--- a/packages/ai-harness/src/view/types.ts
+++ b/packages/ai-harness/src/view/types.ts
@@ -1,5 +1,5 @@
 import type { ConfigOption } from '../config'
-import type { Receipt } from '../types'
+import type { MediaKind, Receipt } from '../types'
 
 export type ToolCallStatus = 'running' | 'done' | 'failed' | 'needs-approval'
 
@@ -25,17 +25,42 @@ export interface AgentPart {
   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 }
+  | {
+      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 }
 
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..8b4e6c5159
--- /dev/null
+++ b/packages/ai-harness/tests/client-media.test.ts
@@ -0,0 +1,148 @@
+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('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/media.test.ts b/packages/ai-harness/tests/media.test.ts
new file mode 100644
index 0000000000..c8cf666bea
--- /dev/null
+++ b/packages/ai-harness/tests/media.test.ts
@@ -0,0 +1,421 @@
+import { describe, expect, it, vi } from 'vitest'
+import { chat, generateImage } from '@tanstack/ai'
+import { memoryPersistence, withPersistence } from '@tanstack/ai-persistence'
+import {
+  MediaError,
+  createMediaStore,
+  mediaCapture,
+  mediaMiddleware,
+} from '../src/media'
+import { mediaPart } from '../src/media-ref'
+import { mockAdapter, text } from './helpers'
+import type {
+  ContentPart,
+  ImageAdapter,
+  ModelMessage,
+  TranscriptionAdapter,
+} from '@tanstack/ai'
+import type { MediaOptions } from '../src/media'
+import type { MediaRecord } from '../src/types'
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+function setup(threadId = 't1', options?: MediaOptions) {
+  const persistence = memoryPersistence()
+  return {
+    persistence,
+    store: createMediaStore({ persistence, threadId, options }),
+  }
+}
+
+function imageAdapter(): ImageAdapter<string> {
+  return {
+    kind: 'image',
+    name: 'fake-image',
+    model: 'fake-image-model',
+    '~types': {
+      providerOptions: {},
+      modelProviderOptionsByName: {},
+      modelSizeByName: {},
+      modelInputModalitiesByName: {},
+    },
+    // 'aGVsbG8=' is base64 for "hello".
+    generateImages: async () => ({
+      id: 'image-1',
+      model: 'fake-image-model',
+      images: [{ b64Json: 'aGVsbG8=' }],
+    }),
+  }
+}
+
+/** A transcription adapter that answers with the text of the audio bytes. */
+function transcriptionAdapter(): TranscriptionAdapter<string> {
+  return {
+    kind: 'transcription',
+    name: 'fake-stt',
+    model: 'fake-stt-model',
+    '~types': { providerOptions: {} },
+    transcribe: async ({ audio }) => ({
+      id: 'transcript-1',
+      model: 'fake-stt-model',
+      text: audio instanceof Blob ? await audio.text() : 'not a blob',
+    }),
+  }
+}
+
+function userMessage(...parts: Array<ContentPart>): ModelMessage {
+  return {
+    role: 'user',
+    content: [{ type: 'text', content: 'Look' }, ...parts],
+  }
+}
+
+/** Run one chat turn and return what the adapter got and the saved thread. */
+async function runTurn(
+  persistence: ReturnType<typeof memoryPersistence>,
+  middleware: ReturnType<typeof mediaMiddleware>,
+  message: ModelMessage,
+) {
+  const { adapter, calls } = mockAdapter(() => text('ok'))
+  await chat({
+    adapter,
+    messages: [message],
+    threadId: 't1',
+    middleware: [withPersistence(persistence), middleware],
+    stream: false,
+  })
+  const [call] = calls
+  const sent: Array<ModelMessage> = call?.messages ?? []
+  return {
+    sent: sent[0]?.content,
+    saved: (await persistence.stores.messages.loadThread('t1'))[0]?.content,
+    calls,
+  }
+}
+
+describe('createMediaStore', () => {
+  it('stores a file and reads it back', async () => {
+    const { store } = setup()
+    const record = await store.put(encoder.encode('hello'), {
+      mimeType: 'image/png',
+      name: 'cat.png',
+    })
+    expect(record).toEqual({
+      id: expect.any(String),
+      threadId: 't1',
+      kind: 'image',
+      mimeType: 'image/png',
+      name: 'cat.png',
+      size: 5,
+      source: 'user',
+      createdAt: expect.any(Number),
+    })
+    expect(await store.get(record.id)).toEqual(record)
+    expect(decoder.decode(await store.load(record.id))).toBe('hello')
+  })
+
+  it.each([
+    ['a byte body', encoder.encode('hello')],
+    ['a stream body', new Blob(['hello']).stream()],
+  ])('refuses %s over maxBytes with 413', async (_label, body) => {
+    const { store } = setup('t1', { maxBytes: 4 })
+    const put = store.put(body, { mimeType: 'image/png', name: 'cat.png' })
+    await expect(put).rejects.toBeInstanceOf(MediaError)
+    await expect(put).rejects.toMatchObject({ status: 413 })
+  })
+
+  it('keeps nothing when a stream goes over maxBytes', async () => {
+    const { persistence, store } = setup('t1', { maxBytes: 4 })
+    // A store that keeps a partial write when the body fails.
+    const { blobs } = persistence.stores
+    const put = blobs.put.bind(blobs)
+    vi.spyOn(blobs, 'put').mockImplementation(async (key, body) => {
+      await put(key, 'partial')
+      return put(key, body)
+    })
+    await store
+      .put(new Blob(['hello']).stream(), { mimeType: 'image/png', name: 'a' })
+      .catch(() => undefined)
+    expect(await persistence.stores.artifacts.listForThread('t1')).toEqual([])
+    expect((await persistence.stores.blobs.list()).objects).toEqual([])
+  })
+
+  it.each([
+    ['a MIME type with no kind', 'application/zip', undefined],
+    ['a kind not in kinds', 'audio/mpeg', ['image'] as const],
+  ])('refuses %s with 415', async (_label, mimeType, kinds) => {
+    const { store } = setup('t1', { kinds })
+    await expect(
+      store.put(encoder.encode('hello'), { mimeType, name: 'file' }),
+    ).rejects.toMatchObject({ status: 415 })
+  })
+
+  it('does not show media of another thread', async () => {
+    const persistence = memoryPersistence()
+    const a = createMediaStore({ persistence, threadId: 'a' })
+    const b = createMediaStore({ persistence, threadId: 'b' })
+    const record = await a.put(encoder.encode('secret'), {
+      mimeType: 'image/png',
+      name: 'a.png',
+    })
+    expect(await b.get(record.id)).toBeNull()
+    await expect(b.load(record.id)).rejects.toMatchObject({ status: 404 })
+    expect(await b.dataUrl(record.id)).toBeUndefined()
+  })
+
+  it('throws 404 for an id that does not exist', async () => {
+    const { store } = setup()
+    await expect(store.load('nope')).rejects.toMatchObject({ status: 404 })
+  })
+
+  it.each([
+    [{ offset: 6 }, 'world'],
+    [{ offset: 0, length: 5 }, 'hello'],
+    [{ offset: 6, length: 100 }, 'world'],
+  ])('loads the range %j', async (range, expected) => {
+    const { store } = setup()
+    const record = await store.put('hello world', {
+      mimeType: 'text/plain',
+      name: 'a.txt',
+    })
+    expect(decoder.decode(await store.load(record.id, range))).toBe(expected)
+  })
+
+  it('makes a data URL up to 1 MB only', async () => {
+    const { store } = setup()
+    const small = await store.put(encoder.encode('hello'), {
+      mimeType: 'image/png',
+      name: 'small.png',
+    })
+    const big = await store.put(new Uint8Array(1024 * 1024 + 1), {
+      mimeType: 'image/png',
+      name: 'big.png',
+    })
+    expect(await store.dataUrl(small.id)).toBe('data:image/png;base64,aGVsbG8=')
+    expect(await store.dataUrl(big.id)).toBeUndefined()
+  })
+})
+
+describe('mediaCapture', () => {
+  it.each([
+    ['a child run', 'op-chat-1:subagent-9:image-1', 'op-chat-1', 'subagent-9'],
+    [
+      'a nested child run',
+      'op-chat-2:subagent-a:subagent-b:image-3',
+      'op-chat-2',
+      'subagent-b',
+    ],
+    ['a plain run', 'run-7', 'run-7', undefined],
+  ])(
+    'publishes generated media of %s',
+    async (_label, generationRunId, runId, subagentRunId) => {
+      const persistence = memoryPersistence()
+      const published: Array<MediaRecord> = []
+      const result = await generateImage({
+        adapter: imageAdapter(),
+        prompt: 'a cat',
+        // A background agent runs under its own thread id. Media still goes
+        // to the session thread.
+        threadId: 't1:painter',
+        runId: generationRunId,
+        middleware: mediaCapture({
+          persistence,
+          threadId: 't1',
+          publish: (record) => {
+            published.push(record)
+          },
+        }),
+      })
+      expect(result.images).toHaveLength(1)
+      expect(published).toEqual([
+        {
+          id: expect.any(String),
+          threadId: 't1',
+          kind: 'image',
+          mimeType: 'image/png',
+          name: expect.any(String),
+          size: 5,
+          source: 'generated',
+          createdAt: expect.any(Number),
+          runId,
+          subagentRunId,
+        },
+      ])
+      const store = createMediaStore({ persistence, threadId: 't1' })
+      const bytes = await store.load(published[0]?.id ?? '')
+      expect(decoder.decode(bytes)).toBe('hello')
+    },
+  )
+
+  it('keeps the generation result when publish throws', async () => {
+    const onError = vi.fn()
+    const result = await generateImage({
+      adapter: imageAdapter(),
+      prompt: 'a cat',
+      runId: 'op-chat-1:subagent-1:image-1',
+      middleware: mediaCapture({
+        persistence: memoryPersistence(),
+        threadId: 't1',
+        publish: () => {
+          throw new Error('feed closed')
+        },
+        onError,
+      }),
+    })
+    expect(result.images).toHaveLength(1)
+    expect(onError).toHaveBeenCalledWith(new Error('feed closed'))
+  })
+
+  it('keeps the generation result when the blob store fails', async () => {
+    const persistence = memoryPersistence()
+    vi.spyOn(persistence.stores.blobs, 'put').mockRejectedValue(
+      new Error('disk full'),
+    )
+    const onError = vi.fn()
+    const publish = vi.fn()
+    const result = await generateImage({
+      adapter: imageAdapter(),
+      prompt: 'a cat',
+      runId: 'op-chat-1:subagent-1:image-1',
+      middleware: mediaCapture({
+        persistence,
+        threadId: 't1',
+        publish,
+        onError,
+      }),
+    })
+    expect(result.images).toEqual([{ b64Json: 'aGVsbG8=' }])
+    expect(onError).toHaveBeenCalledWith(new Error('disk full'))
+    expect(publish).not.toHaveBeenCalled()
+  })
+})
+
+describe('mediaMiddleware', () => {
+  it('sends the bytes to the model and saves the harness-media URL', async () => {
+    const { persistence, store } = setup()
+    const record = await store.put(encoder.encode('hello'), {
+      mimeType: 'image/png',
+      name: 'cat.png',
+    })
+    // withPersistence comes first, as in a harness turn.
+    const { sent, saved } = await runTurn(
+      persistence,
+      mediaMiddleware({ store }),
+      userMessage(mediaPart(record)),
+    )
+    expect(sent).toEqual([
+      { type: 'text', content: 'Look' },
+      {
+        type: 'image',
+        source: { type: 'data', value: 'aGVsbG8=', mimeType: 'image/png' },
+      },
+    ])
+    expect(saved).toEqual([
+      { type: 'text', content: 'Look' },
+      {
+        type: 'image',
+        source: {
+          type: 'url',
+          value: `harness-media:${record.id}`,
+          mimeType: 'image/png',
+        },
+      },
+    ])
+  })
+
+  it.each([
+    [
+      'audio when transcribe is not set',
+      'audio/mpeg',
+      undefined,
+      'test-model cannot read audio files. Add media.transcribe, or send a text summary.',
+    ],
+    [
+      'video, also when transcribe is set',
+      'video/mp4',
+      transcriptionAdapter(),
+      'test-model cannot read video files. Use a model that reads video files, or send a text summary.',
+    ],
+  ])(
+    'refuses %s before the model call',
+    async (_label, mimeType, transcribe, message) => {
+      const { persistence, store } = setup()
+      const record = await store.put(encoder.encode('hello'), {
+        mimeType,
+        name: 'clip',
+      })
+      const { adapter, calls } = mockAdapter(() => text('ok'))
+      await expect(
+        chat({
+          adapter,
+          messages: [userMessage(mediaPart(record))],
+          threadId: 't1',
+          middleware: [
+            withPersistence(persistence),
+            mediaMiddleware({ store, accepted: ['text', 'image'], transcribe }),
+          ],
+          stream: false,
+        }),
+      ).rejects.toThrow(message)
+      expect(calls).toHaveLength(0)
+    },
+  )
+
+  it('turns audio into a transcript when the model cannot read audio', async () => {
+    const { persistence, store } = setup()
+    const record = await store.put(encoder.encode('meow meow'), {
+      mimeType: 'audio/mpeg',
+      name: 'voice.mp3',
+    })
+    const { sent } = await runTurn(
+      persistence,
+      mediaMiddleware({
+        store,
+        accepted: ['text', 'image'],
+        transcribe: transcriptionAdapter(),
+      }),
+      userMessage(mediaPart(record)),
+    )
+    expect(sent).toEqual([
+      { type: 'text', content: 'Look' },
+      { type: 'text', content: '[audio transcript: voice.mp3] meow meow' },
+    ])
+  })
+
+  it('sends a text note when the bytes are gone', async () => {
+    const { persistence, store } = setup()
+    const record = await store.put(encoder.encode('hello'), {
+      mimeType: 'image/png',
+      name: 'cat.png',
+    })
+    const blobKey = (await persistence.stores.artifacts.get(record.id))?.blobKey
+    await persistence.stores.blobs.delete(blobKey ?? '')
+    const { sent, calls } = await runTurn(
+      persistence,
+      mediaMiddleware({ store }),
+      userMessage(mediaPart(record)),
+    )
+    expect(calls).toHaveLength(1)
+    expect(sent).toEqual([
+      { type: 'text', content: 'Look' },
+      { type: 'text', content: '[image not found: cat.png]' },
+    ])
+  })
+
+  it('sends a text note when the record is gone', async () => {
+    const { persistence, store } = setup()
+    const { sent } = await runTurn(
+      persistence,
+      mediaMiddleware({ store }),
+      userMessage({
+        type: 'image',
+        source: { type: 'url', value: 'harness-media:deleted-1' },
+      }),
+    )
+    expect(sent).toEqual([
+      { type: 'text', content: 'Look' },
+      { type: 'text', content: '[image not found: deleted-1]' },
+    ])
+  })
+})
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..1b3f43e28f
--- /dev/null
+++ b/packages/ai-harness/tests/view-media.test.ts
@@ -0,0 +1,375 @@
+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('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-llmgateway/src/adapters/text.ts b/packages/ai-llmgateway/src/adapters/text.ts
index 390ad2b863..c7c04fe757 100644
--- a/packages/ai-llmgateway/src/adapters/text.ts
+++ b/packages/ai-llmgateway/src/adapters/text.ts
@@ -1,5 +1,6 @@
 import OpenAI from 'openai'
 import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
+import { LLMGATEWAY_MODEL_INPUT_MODALITIES } from '../model-meta'
 import {
   getLLMGatewayApiKeyFromEnv,
   withLLMGatewayDefaults,
@@ -61,6 +62,8 @@ export class LLMGatewayTextAdapter<
 > {
   override readonly kind = 'text' as const
   override readonly name = 'llmgateway' as const
+  override readonly inputModalities =
+    LLMGATEWAY_MODEL_INPUT_MODALITIES[this.model]
 
   constructor(config: LLMGatewayTextConfig, model: TModel) {
     super(
diff --git a/packages/ai-llmgateway/src/model-meta.ts b/packages/ai-llmgateway/src/model-meta.ts
index 7fe7b7db55..f3473c68e6 100644
--- a/packages/ai-llmgateway/src/model-meta.ts
+++ b/packages/ai-llmgateway/src/model-meta.ts
@@ -1,3 +1,4 @@
+import type { Modality } from '@tanstack/ai'
 import type { LLMGatewayTextProviderOptions } from './text/text-provider-options'
 
 /**
@@ -465,6 +466,31 @@ export type LLMGatewayModelInputModalitiesByName = {
   [GROK_4_5.name]: typeof GROK_4_5.supports.input
 }
 
+/**
+ * Runtime map from curated LLM Gateway chat model name to its supported
+ * input modalities, read by the text adapter's `inputModalities`. An
+ * uncurated id is not in it. `satisfies` ties it to
+ * {@link LLMGatewayModelInputModalitiesByName}, so the two cannot drift.
+ */
+export const LLMGATEWAY_MODEL_INPUT_MODALITIES: Readonly<
+  Record<string, ReadonlyArray<Modality>>
+> = {
+  [GPT_5_6_TERRA.name]: GPT_5_6_TERRA.supports.input,
+  [GPT_5_5.name]: GPT_5_5.supports.input,
+  [GPT_5_4_MINI.name]: GPT_5_4_MINI.supports.input,
+  [CLAUDE_OPUS_5.name]: CLAUDE_OPUS_5.supports.input,
+  [CLAUDE_SONNET_5.name]: CLAUDE_SONNET_5.supports.input,
+  [CLAUDE_HAIKU_4_5.name]: CLAUDE_HAIKU_4_5.supports.input,
+  [GEMINI_PRO_LATEST.name]: GEMINI_PRO_LATEST.supports.input,
+  [GEMINI_3_6_FLASH.name]: GEMINI_3_6_FLASH.supports.input,
+  [KIMI_K3.name]: KIMI_K3.supports.input,
+  [GLM_5_2.name]: GLM_5_2.supports.input,
+  [DEEPSEEK_V4_PRO.name]: DEEPSEEK_V4_PRO.supports.input,
+  [QWEN_3_7_MAX.name]: QWEN_3_7_MAX.supports.input,
+  [MINIMAX_M2_5.name]: MINIMAX_M2_5.supports.input,
+  [GROK_4_5.name]: GROK_4_5.supports.input,
+} satisfies LLMGatewayModelInputModalitiesByName
+
 /**
  * Type-only map from LLM Gateway chat model name to its provider options
  * type.
diff --git a/packages/ai-llmgateway/tests/input-modalities.test.ts b/packages/ai-llmgateway/tests/input-modalities.test.ts
new file mode 100644
index 0000000000..929701ffe2
--- /dev/null
+++ b/packages/ai-llmgateway/tests/input-modalities.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest'
+import { createLLMGatewayText } from '../src/adapters/text'
+
+describe('LLMGatewayTextAdapter inputModalities', () => {
+  it.each([
+    ['gpt-5.6-terra', ['text', 'image']],
+    ['deepseek-v4-pro', ['text']],
+  ] as const)('reads the list of %s from model-meta', (model, expected) => {
+    expect(createLLMGatewayText(model, 'test-key').inputModalities).toEqual(
+      expected,
+    )
+  })
+
+  // Model ids are open-ended here, so an uncurated id is a normal call.
+  it('is undefined for a model id that model-meta does not list', () => {
+    const adapter = createLLMGatewayText('vendor/uncurated-model', 'test-key')
+
+    expect(adapter.inputModalities).toBeUndefined()
+  })
+})
diff --git a/packages/ai-mistral/src/adapters/text.ts b/packages/ai-mistral/src/adapters/text.ts
index d9dbb70eb4..981ebed464 100644
--- a/packages/ai-mistral/src/adapters/text.ts
+++ b/packages/ai-mistral/src/adapters/text.ts
@@ -9,6 +9,7 @@ import {
 } from '../utils/client'
 import { makeMistralStructuredOutputCompatibleWithMap } from '../utils/schema-converter'
 import { createToolInputNormalizer } from '../utils/tool-input-normalizer'
+import { MISTRAL_MODEL_INPUT_MODALITIES } from '../model-meta'
 import type {
   ContentPart,
   Modality,
@@ -176,6 +177,7 @@ export class MistralTextAdapter<
   MistralMessageMetadataByModality
 > {
   readonly name = 'mistral' as const
+  override readonly inputModalities = MISTRAL_MODEL_INPUT_MODALITIES[this.model]
 
   private readonly client: Mistral
   private readonly rawConfig: MistralClientConfig
diff --git a/packages/ai-mistral/src/input-modalities.test.ts b/packages/ai-mistral/src/input-modalities.test.ts
new file mode 100644
index 0000000000..ec5cfd6e34
--- /dev/null
+++ b/packages/ai-mistral/src/input-modalities.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { MistralTextAdapter } from './adapters/text'
+
+// Constructing the SDK client makes no network call.
+const config = { apiKey: 'test-key' }
+
+describe('Mistral text adapter inputModalities', () => {
+  it('gives the input list of each known model', () => {
+    expect(
+      new MistralTextAdapter(config, 'mistral-large-latest').inputModalities,
+    ).toEqual(['text'])
+    expect(
+      new MistralTextAdapter(config, 'pixtral-large-latest').inputModalities,
+    ).toEqual(['text', 'image', 'document'])
+  })
+
+  it('is undefined for a model the metadata does not list', () => {
+    // A JS caller, or a model id newer than this package, reaches the adapter.
+    // @ts-expect-error - 'mistral-unknown-9000' is not a declared model
+    const adapter = new MistralTextAdapter(config, 'mistral-unknown-9000')
+
+    expect(adapter.inputModalities).toBeUndefined()
+  })
+})
diff --git a/packages/ai-mistral/src/model-meta.ts b/packages/ai-mistral/src/model-meta.ts
index 9c0fe276a6..d1d72094dc 100644
--- a/packages/ai-mistral/src/model-meta.ts
+++ b/packages/ai-mistral/src/model-meta.ts
@@ -1,3 +1,4 @@
+import type { Modality } from '@tanstack/ai'
 import type { MistralTextProviderOptions } from './text/text-provider-options'
 import type {
   CodestralEmbedProviderOptions,
@@ -322,6 +323,30 @@ export type MistralModelInputModalitiesByName = {
   [CODESTRAL_2.name]: typeof CODESTRAL_2.supports.input
 }
 
+/**
+ * Runtime map from Mistral chat model name to its supported input modalities,
+ * for the text adapter's `inputModalities`. `satisfies` keeps it equal to
+ * {@link MistralModelInputModalitiesByName}. An unknown name gives `undefined`.
+ */
+export const MISTRAL_MODEL_INPUT_MODALITIES: Readonly<
+  Record<string, ReadonlyArray<Modality>>
+> = {
+  [MISTRAL_LARGE_LATEST.name]: MISTRAL_LARGE_LATEST.supports.input,
+  [MISTRAL_MEDIUM_LATEST.name]: MISTRAL_MEDIUM_LATEST.supports.input,
+  [MISTRAL_SMALL_LATEST.name]: MISTRAL_SMALL_LATEST.supports.input,
+  [MINISTRAL_8B_LATEST.name]: MINISTRAL_8B_LATEST.supports.input,
+  [MINISTRAL_3B_LATEST.name]: MINISTRAL_3B_LATEST.supports.input,
+  [CODESTRAL_LATEST.name]: CODESTRAL_LATEST.supports.input,
+  [PIXTRAL_LARGE_LATEST.name]: PIXTRAL_LARGE_LATEST.supports.input,
+  [PIXTRAL_12B_2409.name]: PIXTRAL_12B_2409.supports.input,
+  [MAGISTRAL_MEDIUM_LATEST.name]: MAGISTRAL_MEDIUM_LATEST.supports.input,
+  [MAGISTRAL_SMALL_LATEST.name]: MAGISTRAL_SMALL_LATEST.supports.input,
+  [OPEN_MISTRAL_NEMO.name]: OPEN_MISTRAL_NEMO.supports.input,
+  [MISTRAL_MEDIUM_3.name]: MISTRAL_MEDIUM_3.supports.input,
+  [MISTRAL_SMALL_2503.name]: MISTRAL_SMALL_2503.supports.input,
+  [CODESTRAL_2.name]: CODESTRAL_2.supports.input,
+} satisfies MistralModelInputModalitiesByName
+
 /**
  * Type-only map from Mistral chat model name to its provider options type.
  */
diff --git a/packages/ai-openai/src/adapters/text-chat-completions.ts b/packages/ai-openai/src/adapters/text-chat-completions.ts
index 3d1f65844c..e0964e96b6 100644
--- a/packages/ai-openai/src/adapters/text-chat-completions.ts
+++ b/packages/ai-openai/src/adapters/text-chat-completions.ts
@@ -1,6 +1,7 @@
 import OpenAI from 'openai'
 import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
 import { getOpenAIApiKeyFromEnv } from '../utils/client'
+import { OPENAI_MODEL_INPUT_MODALITIES } from '../model-meta'
 import type {
   OPENAI_CHAT_MODELS,
   OpenAIChatModel,
@@ -65,6 +66,7 @@ export class OpenAIChatCompletionsTextAdapter<
   TToolCapabilities
 > {
   override readonly kind = 'text' as const
+  override readonly inputModalities = OPENAI_MODEL_INPUT_MODALITIES[this.model]
 
   constructor(config: OpenAIChatCompletionsConfig, model: TModel) {
     super(model, 'openai-chat', new OpenAI(config), config)
diff --git a/packages/ai-openai/src/adapters/text.ts b/packages/ai-openai/src/adapters/text.ts
index 94e47d4940..75a90a6688 100644
--- a/packages/ai-openai/src/adapters/text.ts
+++ b/packages/ai-openai/src/adapters/text.ts
@@ -6,7 +6,10 @@ import {
 import { validateTextProviderOptions } from '../text/text-provider-options'
 import { convertToolsToProviderFormat } from '../tools'
 import { getOpenAIApiKeyFromEnv } from '../utils/client'
-import { openAIModelRejectsSamplingParams } from '../model-meta'
+import {
+  OPENAI_MODEL_INPUT_MODALITIES,
+  openAIModelRejectsSamplingParams,
+} from '../model-meta'
 import type {
   OPENAI_CHAT_MODELS,
   OpenAIChatModel,
@@ -102,6 +105,7 @@ export class OpenAITextAdapter<
   // compatible subclasses of the openai-base adapter (Grok, Bedrock, custom)
   // — which have no such surface — fail closed in preflight.
   override readonly supportsFileSources = true
+  override readonly inputModalities = OPENAI_MODEL_INPUT_MODALITIES[this.model]
 
   constructor(config: OpenAITextConfig, model: TModel) {
     super(model, 'openai', new OpenAI(config), config)
diff --git a/packages/ai-openai/src/model-meta.ts b/packages/ai-openai/src/model-meta.ts
index daa6ea88a0..3f10b49616 100644
--- a/packages/ai-openai/src/model-meta.ts
+++ b/packages/ai-openai/src/model-meta.ts
@@ -1,3 +1,4 @@
+import type { Modality } from '@tanstack/ai'
 import type {
   OpenAIBaseOptions,
   OpenAIMetadataOptions,
@@ -3312,3 +3313,70 @@ export type OpenAIModelInputModalitiesByName = {
   [GPT_6_SOL.name]: typeof GPT_6_SOL.supports.input
   [GPT_6_SOL_PRO.name]: typeof GPT_6_SOL_PRO.supports.input
 }
+
+/**
+ * Runtime map from chat model name to its supported input modalities, for the
+ * text adapters' `inputModalities`. `satisfies` keeps it equal to
+ * {@link OpenAIModelInputModalitiesByName}. An unknown name gives `undefined`.
+ */
+export const OPENAI_MODEL_INPUT_MODALITIES: Readonly<
+  Record<string, ReadonlyArray<Modality>>
+> = {
+  [GPT5_2.name]: GPT5_2.supports.input,
+  [GPT5_2_PRO.name]: GPT5_2_PRO.supports.input,
+  [GPT5_2_CHAT.name]: GPT5_2_CHAT.supports.input,
+  [GPT5_1.name]: GPT5_1.supports.input,
+  [GPT5_1_CODEX.name]: GPT5_1_CODEX.supports.input,
+  [GPT5.name]: GPT5.supports.input,
+  [GPT5_MINI.name]: GPT5_MINI.supports.input,
+  [GPT5_NANO.name]: GPT5_NANO.supports.input,
+  [GPT5_PRO.name]: GPT5_PRO.supports.input,
+  [GPT5_CODEX.name]: GPT5_CODEX.supports.input,
+  [GPT4_1.name]: GPT4_1.supports.input,
+  [GPT4_1_MINI.name]: GPT4_1_MINI.supports.input,
+  [GPT4_1_NANO.name]: GPT4_1_NANO.supports.input,
+  [GPT_4O.name]: GPT_4O.supports.input,
+  [GPT_4O_MINI.name]: GPT_4O_MINI.supports.input,
+  [GPT_4_TURBO.name]: GPT_4_TURBO.supports.input,
+  [CHATGPT_40.name]: CHATGPT_40.supports.input,
+  [GPT_5_1_CHAT.name]: GPT_5_1_CHAT.supports.input,
+  [GPT_5_CHAT.name]: GPT_5_CHAT.supports.input,
+  [GPT_5_1_CODEX_MINI.name]: GPT_5_1_CODEX_MINI.supports.input,
+  [CODEX_MINI_LATEST.name]: CODEX_MINI_LATEST.supports.input,
+  [COMPUTER_USE_PREVIEW.name]: COMPUTER_USE_PREVIEW.supports.input,
+  [O3.name]: O3.supports.input,
+  [O3_PRO.name]: O3_PRO.supports.input,
+  [O3_DEEP_RESEARCH.name]: O3_DEEP_RESEARCH.supports.input,
+  [O4_MINI_DEEP_RESEARCH.name]: O4_MINI_DEEP_RESEARCH.supports.input,
+  [O4_MINI.name]: O4_MINI.supports.input,
+  [O1.name]: O1.supports.input,
+  [O1_PRO.name]: O1_PRO.supports.input,
+  [GPT_AUDIO.name]: GPT_AUDIO.supports.input,
+  [GPT_AUDIO_MINI.name]: GPT_AUDIO_MINI.supports.input,
+  [GPT_4O_AUDIO.name]: GPT_4O_AUDIO.supports.input,
+  [GPT_4O_MINI_AUDIO.name]: GPT_4O_MINI_AUDIO.supports.input,
+  [GPT_4.name]: GPT_4.supports.input,
+  [GPT_3_5_TURBO.name]: GPT_3_5_TURBO.supports.input,
+  [O3_MINI.name]: O3_MINI.supports.input,
+  [GPT_4O_SEARCH_PREVIEW.name]: GPT_4O_SEARCH_PREVIEW.supports.input,
+  [GPT_4O_MINI_SEARCH_PREVIEW.name]: GPT_4O_MINI_SEARCH_PREVIEW.supports.input,
+  [GPT_5_4_MINI.name]: GPT_5_4_MINI.supports.input,
+  [GPT_5_4_NANO.name]: GPT_5_4_NANO.supports.input,
+  [GPT_5_4_IMAGE_2.name]: GPT_5_4_IMAGE_2.supports.input,
+  [GPT_5_6.name]: GPT_5_6.supports.input,
+  [GPT_5_6_SOL.name]: GPT_5_6_SOL.supports.input,
+  [GPT_5_6_TERRA.name]: GPT_5_6_TERRA.supports.input,
+  [GPT_5_6_LUNA.name]: GPT_5_6_LUNA.supports.input,
+  [GPT_5_5.name]: GPT_5_5.supports.input,
+  [GPT_5_5_PRO.name]: GPT_5_5_PRO.supports.input,
+  [GPT_CHAT_LATEST.name]: GPT_CHAT_LATEST.supports.input,
+  [GPT_5_6_LUNA_PRO.name]: GPT_5_6_LUNA_PRO.supports.input,
+  [GPT_5_6_SOL_PRO.name]: GPT_5_6_SOL_PRO.supports.input,
+  [GPT_5_6_TERRA_PRO.name]: GPT_5_6_TERRA_PRO.supports.input,
+  [GPT_6_ASTRA.name]: GPT_6_ASTRA.supports.input,
+  [GPT_6_ASTRA_PRO.name]: GPT_6_ASTRA_PRO.supports.input,
+  [GPT_6_LUNA.name]: GPT_6_LUNA.supports.input,
+  [GPT_6_LUNA_PRO.name]: GPT_6_LUNA_PRO.supports.input,
+  [GPT_6_SOL.name]: GPT_6_SOL.supports.input,
+  [GPT_6_SOL_PRO.name]: GPT_6_SOL_PRO.supports.input,
+} satisfies OpenAIModelInputModalitiesByName
diff --git a/packages/ai-openai/tests/input-modalities.test.ts b/packages/ai-openai/tests/input-modalities.test.ts
new file mode 100644
index 0000000000..949cf80da1
--- /dev/null
+++ b/packages/ai-openai/tests/input-modalities.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import { OpenAITextAdapter } from '../src/adapters/text'
+import { OpenAIChatCompletionsTextAdapter } from '../src/adapters/text-chat-completions'
+
+// Constructing the SDK client makes no network call.
+const config = { apiKey: 'sk-test' }
+
+describe('OpenAI text adapter inputModalities', () => {
+  it('gives the input list of each known model', () => {
+    expect(new OpenAITextAdapter(config, 'gpt-5.2').inputModalities).toEqual([
+      'text',
+      'image',
+      'document',
+    ])
+    expect(new OpenAITextAdapter(config, 'gpt-audio').inputModalities).toEqual([
+      'text',
+      'audio',
+    ])
+  })
+
+  it('is undefined for a model the metadata does not list', () => {
+    // A JS caller, or a model id newer than this package, reaches the adapter.
+    // @ts-expect-error - 'gpt-unknown-9000' is not a declared model
+    const adapter = new OpenAITextAdapter(config, 'gpt-unknown-9000')
+
+    expect(adapter.inputModalities).toBeUndefined()
+  })
+
+  it('gives the same list on the Chat Completions adapter', () => {
+    const adapter = new OpenAIChatCompletionsTextAdapter(config, 'gpt-audio')
+
+    expect(adapter.inputModalities).toEqual(['text', 'audio'])
+  })
+})
diff --git a/packages/ai-openrouter/src/adapters/responses-text.ts b/packages/ai-openrouter/src/adapters/responses-text.ts
index 378bfc576b..0824b08d5d 100644
--- a/packages/ai-openrouter/src/adapters/responses-text.ts
+++ b/packages/ai-openrouter/src/adapters/responses-text.ts
@@ -15,6 +15,7 @@ import { extractRequestOptions } from '../internal/request-options'
 import { openRouterSupportsCombinedToolsAndSchema } from '../internal/combined-tools-and-schema'
 import { makeStructuredOutputCompatible } from '../internal/schema-converter'
 import { convertFunctionToolToResponsesFormat } from '../internal/responses-tool-converter'
+import { OPENROUTER_MODEL_INPUT_MODALITIES } from '../model-meta'
 import { isWebSearchTool } from '../tools/web-search-tool'
 import { isWebFetchTool } from '../tools/web-fetch-tool'
 import { getOpenRouterApiKeyFromEnv } from '../utils'
@@ -116,6 +117,8 @@ export class OpenRouterResponsesTextAdapter<
 > {
   override readonly kind = 'text' as const
   readonly name = 'openrouter-responses' as const
+  override readonly inputModalities =
+    OPENROUTER_MODEL_INPUT_MODALITIES[this.model]
 
   protected orClient: OpenRouter
 
diff --git a/packages/ai-openrouter/src/adapters/text.ts b/packages/ai-openrouter/src/adapters/text.ts
index 625027bdc2..ca3d910f12 100644
--- a/packages/ai-openrouter/src/adapters/text.ts
+++ b/packages/ai-openrouter/src/adapters/text.ts
@@ -14,6 +14,7 @@ import { generateId } from '@tanstack/ai-utils'
 import { extractRequestOptions } from '../internal/request-options'
 import { makeStructuredOutputCompatible } from '../internal/schema-converter'
 import { openRouterSupportsCombinedToolsAndSchema } from '../internal/combined-tools-and-schema'
+import { OPENROUTER_MODEL_INPUT_MODALITIES } from '../model-meta'
 import { convertToolsToProviderFormat } from '../tools'
 import { getOpenRouterApiKeyFromEnv } from '../utils'
 import { buildOpenRouterUsage } from '../usage'
@@ -138,6 +139,8 @@ export class OpenRouterTextAdapter<
 > {
   override readonly kind = 'text' as const
   readonly name = 'openrouter' as const
+  override readonly inputModalities =
+    OPENROUTER_MODEL_INPUT_MODALITIES[this.model]
 
   protected orClient: OpenRouter
   private readonly retryCodes: Array<string> | undefined
diff --git a/packages/ai-openrouter/src/model-meta.ts b/packages/ai-openrouter/src/model-meta.ts
index 9ccd8a57af..e2c0851a14 100644
--- a/packages/ai-openrouter/src/model-meta.ts
+++ b/packages/ai-openrouter/src/model-meta.ts
@@ -1,5 +1,6 @@
 // AUTO-GENERATED by scripts/convert-openrouter-models.ts from scripts/openrouter.models.json
 // (`pnpm generate:models`). Do not edit by hand — every block here is rewritten on sync.
+import type { Modality } from '@tanstack/ai'
 import type {
   OpenRouterBaseOptions,
   OpenRouterCommonOptions,
@@ -21372,6 +21373,607 @@ export const OPENROUTER_CHAT_MODELS = [
   'openrouter/auto',
 ] as const
 
+/**
+ * Generated: runtime map from chat model id to its input modalities, read by
+ * the text adapters' `inputModalities`. `satisfies` ties it to
+ * `OpenRouterModelInputModalitiesByName`, so the two cannot drift.
+ */
+export const OPENROUTER_MODEL_INPUT_MODALITIES: Readonly<
+  Record<string, ReadonlyArray<Modality>>
+> = {
+  [_ANTHROPIC_CLAUDE_FABLE_LATEST.id]:
+    _ANTHROPIC_CLAUDE_FABLE_LATEST.supports.input,
+  [_ANTHROPIC_CLAUDE_HAIKU_LATEST.id]:
+    _ANTHROPIC_CLAUDE_HAIKU_LATEST.supports.input,
+  [_ANTHROPIC_CLAUDE_OPUS_LATEST.id]:
+    _ANTHROPIC_CLAUDE_OPUS_LATEST.supports.input,
+  [_ANTHROPIC_CLAUDE_SONNET_LATEST.id]:
+    _ANTHROPIC_CLAUDE_SONNET_LATEST.supports.input,
+  [_DEEPSEEK_DEEPSEEK_FLASH_LATEST.id]:
+    _DEEPSEEK_DEEPSEEK_FLASH_LATEST.supports.input,
+  [_DEEPSEEK_DEEPSEEK_PRO_LATEST.id]:
+    _DEEPSEEK_DEEPSEEK_PRO_LATEST.supports.input,
+  [_DEEPSEEK_DEEPSEEK_V4_FLASH_LATEST.id]:
+    _DEEPSEEK_DEEPSEEK_V4_FLASH_LATEST.supports.input,
+  [_GOOGLE_GEMINI_FLASH_LATEST.id]: _GOOGLE_GEMINI_FLASH_LATEST.supports.input,
+  [_GOOGLE_GEMINI_PRO_LATEST.id]: _GOOGLE_GEMINI_PRO_LATEST.supports.input,
+  [_MOONSHOTAI_KIMI_LATEST.id]: _MOONSHOTAI_KIMI_LATEST.supports.input,
+  [_OPENAI_GPT_ASTRA_LATEST.id]: _OPENAI_GPT_ASTRA_LATEST.supports.input,
+  [_OPENAI_GPT_LUNA_LATEST.id]: _OPENAI_GPT_LUNA_LATEST.supports.input,
+  [_OPENAI_GPT_MINI_LATEST.id]: _OPENAI_GPT_MINI_LATEST.supports.input,
+  [_OPENAI_GPT_SOL_LATEST.id]: _OPENAI_GPT_SOL_LATEST.supports.input,
+  [_OPENAI_GPT_TERRA_LATEST.id]: _OPENAI_GPT_TERRA_LATEST.supports.input,
+  [_X_AI_GROK_LATEST.id]: _X_AI_GROK_LATEST.supports.input,
+  [_Z_AI_GLM_FLASH_LATEST.id]: _Z_AI_GLM_FLASH_LATEST.supports.input,
+  [_Z_AI_GLM_LATEST.id]: _Z_AI_GLM_LATEST.supports.input,
+  [AION_LABS_AION_2_0.id]: AION_LABS_AION_2_0.supports.input,
+  [AION_LABS_AION_3_0.id]: AION_LABS_AION_3_0.supports.input,
+  [AION_LABS_AION_3_0_MINI.id]: AION_LABS_AION_3_0_MINI.supports.input,
+  [AION_LABS_AION_3_5.id]: AION_LABS_AION_3_5.supports.input,
+  [AION_LABS_AION_3_5_MINI.id]: AION_LABS_AION_3_5_MINI.supports.input,
+  [AION_LABS_AION_RP_LLAMA_3_1_8B.id]:
+    AION_LABS_AION_RP_LLAMA_3_1_8B.supports.input,
+  [AMAZON_NOVA_2_LITE_V1.id]: AMAZON_NOVA_2_LITE_V1.supports.input,
+  [AMAZON_NOVA_LITE_V1.id]: AMAZON_NOVA_LITE_V1.supports.input,
+  [AMAZON_NOVA_MICRO_V1.id]: AMAZON_NOVA_MICRO_V1.supports.input,
+  [AMAZON_NOVA_PREMIER_V1.id]: AMAZON_NOVA_PREMIER_V1.supports.input,
+  [AMAZON_NOVA_PRO_V1.id]: AMAZON_NOVA_PRO_V1.supports.input,
+  [ANTHRACITE_ORG_MAGNUM_V4_72B.id]:
+    ANTHRACITE_ORG_MAGNUM_V4_72B.supports.input,
+  [ANTHROPIC_CLAUDE_3_HAIKU.id]: ANTHROPIC_CLAUDE_3_HAIKU.supports.input,
+  [ANTHROPIC_CLAUDE_FABLE_5.id]: ANTHROPIC_CLAUDE_FABLE_5.supports.input,
+  [ANTHROPIC_CLAUDE_FABLE_5_BATCH.id]:
+    ANTHROPIC_CLAUDE_FABLE_5_BATCH.supports.input,
+  [ANTHROPIC_CLAUDE_FABLE_5_1.id]: ANTHROPIC_CLAUDE_FABLE_5_1.supports.input,
+  [ANTHROPIC_CLAUDE_FABLE_5_1_BATCH.id]:
+    ANTHROPIC_CLAUDE_FABLE_5_1_BATCH.supports.input,
+  [ANTHROPIC_CLAUDE_HAIKU_4_5.id]: ANTHROPIC_CLAUDE_HAIKU_4_5.supports.input,
+  [ANTHROPIC_CLAUDE_HAIKU_4_5_BATCH.id]:
+    ANTHROPIC_CLAUDE_HAIKU_4_5_BATCH.supports.input,
+  [ANTHROPIC_CLAUDE_OPUS_4_1.id]: ANTHROPIC_CLAUDE_OPUS_4_1.supports.input,
+  [ANTHROPIC_CLAUDE_OPUS_4_1_BATCH.id]:
+    ANTHROPIC_CLAUDE_OPUS_4_1_BATCH.supports.input,
+  [ANTHROPIC_CLAUDE_OPUS_4_5.id]: ANTHROPIC_CLAUDE_OPUS_4_5.supports.input,
+  [ANTHROPIC_CLAUDE_OPUS_4_5_BATCH.id]:
+    ANTHROPIC_CLAUDE_OPUS_4_5_BATCH.supports.input,
+  [ANTHROPIC_CLAUDE_OPUS_4_6.id]: ANTHROPIC_CLAUDE_OPUS_4_6.supports.input,
+  [ANTHROPIC_CLAUDE_OPUS_4_6_BATCH.id]:
+    ANTHROPIC_CLAUDE_OPUS_4_6_BATCH.supports.input,
+  [ANTHROPIC_CLAUDE_OPUS_4_7.id]: ANTHROPIC_CLAUDE_OPUS_4_7.supports.input,
+  [ANTHROPIC_CLAUDE_OPUS_4_7_BATCH.id]:
+    ANTHROPIC_CLAUDE_OPUS_4_7_BATCH.supports.input,
+  [ANTHROPIC_CLAUDE_OPUS_4_8.id]: ANTHROPIC_CLAUDE_OPUS_4_8.supports.input,
+  [ANTHROPIC_CLAUDE_OPUS_4_8_BATCH.id]:
+    ANTHROPIC_CLAUDE_OPUS_4_8_BATCH.supports.input,
+  [ANTHROPIC_CLAUDE_OPUS_5.id]: ANTHROPIC_CLAUDE_OPUS_5.supports.input,
+  [ANTHROPIC_CLAUDE_OPUS_5_BATCH.id]:
+    ANTHROPIC_CLAUDE_OPUS_5_BATCH.supports.input,
+  [ANTHROPIC_CLAUDE_OPUS_5_5.id]: ANTHROPIC_CLAUDE_OPUS_5_5.supports.input,
+  [ANTHROPIC_CLAUDE_OPUS_5_5_BATCH.id]:
+    ANTHROPIC_CLAUDE_OPUS_5_5_BATCH.supports.input,
+  [ANTHROPIC_CLAUDE_SONNET_4.id]: ANTHROPIC_CLAUDE_SONNET_4.supports.input,
+  [ANTHROPIC_CLAUDE_SONNET_4_5.id]: ANTHROPIC_CLAUDE_SONNET_4_5.supports.input,
+  [ANTHROPIC_CLAUDE_SONNET_4_5_BATCH.id]:
+    ANTHROPIC_CLAUDE_SONNET_4_5_BATCH.supports.input,
+  [ANTHROPIC_CLAUDE_SONNET_4_6.id]: ANTHROPIC_CLAUDE_SONNET_4_6.supports.input,
+  [ANTHROPIC_CLAUDE_SONNET_4_6_BATCH.id]:
+    ANTHROPIC_CLAUDE_SONNET_4_6_BATCH.supports.input,
+  [ANTHROPIC_CLAUDE_SONNET_5.id]: ANTHROPIC_CLAUDE_SONNET_5.supports.input,
+  [ANTHROPIC_CLAUDE_SONNET_5_BATCH.id]:
+    ANTHROPIC_CLAUDE_SONNET_5_BATCH.supports.input,
+  [ARCEE_AI_TRINITY_LARGE_THINKING.id]:
+    ARCEE_AI_TRINITY_LARGE_THINKING.supports.input,
+  [BAIDU_ERNIE_4_5_VL_424B_A47B.id]:
+    BAIDU_ERNIE_4_5_VL_424B_A47B.supports.input,
+  [BYTEDANCE_SEED_SEED_1_6.id]: BYTEDANCE_SEED_SEED_1_6.supports.input,
+  [BYTEDANCE_SEED_SEED_1_6_FLASH.id]:
+    BYTEDANCE_SEED_SEED_1_6_FLASH.supports.input,
+  [BYTEDANCE_SEED_SEED_2_1_TURBO.id]:
+    BYTEDANCE_SEED_SEED_2_1_TURBO.supports.input,
+  [BYTEDANCE_SEED_SEED_2_0_CODE.id]:
+    BYTEDANCE_SEED_SEED_2_0_CODE.supports.input,
+  [BYTEDANCE_SEED_SEED_2_0_LITE.id]:
+    BYTEDANCE_SEED_SEED_2_0_LITE.supports.input,
+  [BYTEDANCE_SEED_SEED_2_0_MINI.id]:
+    BYTEDANCE_SEED_SEED_2_0_MINI.supports.input,
+  [BYTEDANCE_UI_TARS_1_5_7B.id]: BYTEDANCE_UI_TARS_1_5_7B.supports.input,
+  [COGNITIVECOMPUTATIONS_DOLPHIN_MISTRAL_24B_VENICE_EDITION.id]:
+    COGNITIVECOMPUTATIONS_DOLPHIN_MISTRAL_24B_VENICE_EDITION.supports.input,
+  [COHERE_COMMAND_A.id]: COHERE_COMMAND_A.supports.input,
+  [COHERE_COMMAND_A_PLUS.id]: COHERE_COMMAND_A_PLUS.supports.input,
+  [COHERE_COMMAND_R_08_2024.id]: COHERE_COMMAND_R_08_2024.supports.input,
+  [COHERE_COMMAND_R_PLUS_08_2024.id]:
+    COHERE_COMMAND_R_PLUS_08_2024.supports.input,
+  [COHERE_COMMAND_R7B_12_2024.id]: COHERE_COMMAND_R7B_12_2024.supports.input,
+  [COHERE_NORTH_MINI_CODE_FREE.id]: COHERE_NORTH_MINI_CODE_FREE.supports.input,
+  [DEEPSEEK_DEEPSEEK_CHAT.id]: DEEPSEEK_DEEPSEEK_CHAT.supports.input,
+  [DEEPSEEK_DEEPSEEK_CHAT_V3_0324.id]:
+    DEEPSEEK_DEEPSEEK_CHAT_V3_0324.supports.input,
+  [DEEPSEEK_DEEPSEEK_CHAT_V3_1.id]: DEEPSEEK_DEEPSEEK_CHAT_V3_1.supports.input,
+  [DEEPSEEK_DEEPSEEK_R1.id]: DEEPSEEK_DEEPSEEK_R1.supports.input,
+  [DEEPSEEK_DEEPSEEK_R1_0528.id]: DEEPSEEK_DEEPSEEK_R1_0528.supports.input,
+  [DEEPSEEK_DEEPSEEK_R1_DISTILL_LLAMA_70B.id]:
+    DEEPSEEK_DEEPSEEK_R1_DISTILL_LLAMA_70B.supports.input,
+  [DEEPSEEK_DEEPSEEK_V3_1_TERMINUS.id]:
+    DEEPSEEK_DEEPSEEK_V3_1_TERMINUS.supports.input,
+  [DEEPSEEK_DEEPSEEK_V3_2.id]: DEEPSEEK_DEEPSEEK_V3_2.supports.input,
+  [DEEPSEEK_DEEPSEEK_V3_2_EXP.id]: DEEPSEEK_DEEPSEEK_V3_2_EXP.supports.input,
+  [DEEPSEEK_DEEPSEEK_V4_FLASH.id]: DEEPSEEK_DEEPSEEK_V4_FLASH.supports.input,
+  [DEEPSEEK_DEEPSEEK_V4_FLASH_0731.id]:
+    DEEPSEEK_DEEPSEEK_V4_FLASH_0731.supports.input,
+  [DEEPSEEK_DEEPSEEK_V4_FLASH_VISION_EXP.id]:
+    DEEPSEEK_DEEPSEEK_V4_FLASH_VISION_EXP.supports.input,
+  [DEEPSEEK_DEEPSEEK_V4_PRO.id]: DEEPSEEK_DEEPSEEK_V4_PRO.supports.input,
+  [DEEPSEEK_DEEPSEEK_V4_PRO_0813.id]:
+    DEEPSEEK_DEEPSEEK_V4_PRO_0813.supports.input,
+  [DEEPSEEK_DEEPSEEK_V4_1_FLASH.id]:
+    DEEPSEEK_DEEPSEEK_V4_1_FLASH.supports.input,
+  [DEEPSEEK_DEEPSEEK_V4_1_FLASH_BATCH.id]:
+    DEEPSEEK_DEEPSEEK_V4_1_FLASH_BATCH.supports.input,
+  [DOTS_STUDIO_DOTS_3_NOTE_PREVIEW_FREE.id]:
+    DOTS_STUDIO_DOTS_3_NOTE_PREVIEW_FREE.supports.input,
+  [FIREWORKS_EMBER_1.id]: FIREWORKS_EMBER_1.supports.input,
+  [GOOGLE_GEMINI_2_5_FLASH.id]: GOOGLE_GEMINI_2_5_FLASH.supports.input,
+  [GOOGLE_GEMINI_2_5_FLASH_IMAGE.id]:
+    GOOGLE_GEMINI_2_5_FLASH_IMAGE.supports.input,
+  [GOOGLE_GEMINI_2_5_FLASH_LITE.id]:
+    GOOGLE_GEMINI_2_5_FLASH_LITE.supports.input,
+  [GOOGLE_GEMINI_2_5_FLASH_LITE_BATCH.id]:
+    GOOGLE_GEMINI_2_5_FLASH_LITE_BATCH.supports.input,
+  [GOOGLE_GEMINI_2_5_FLASH_BATCH.id]:
+    GOOGLE_GEMINI_2_5_FLASH_BATCH.supports.input,
+  [GOOGLE_GEMINI_2_5_PRO.id]: GOOGLE_GEMINI_2_5_PRO.supports.input,
+  [GOOGLE_GEMINI_2_5_PRO_PREVIEW.id]:
+    GOOGLE_GEMINI_2_5_PRO_PREVIEW.supports.input,
+  [GOOGLE_GEMINI_2_5_PRO_BATCH.id]: GOOGLE_GEMINI_2_5_PRO_BATCH.supports.input,
+  [GOOGLE_GEMINI_3_FLASH_PREVIEW.id]:
+    GOOGLE_GEMINI_3_FLASH_PREVIEW.supports.input,
+  [GOOGLE_GEMINI_3_FLASH_PREVIEW_BATCH.id]:
+    GOOGLE_GEMINI_3_FLASH_PREVIEW_BATCH.supports.input,
+  [GOOGLE_GEMINI_3_PRO_IMAGE.id]: GOOGLE_GEMINI_3_PRO_IMAGE.supports.input,
+  [GOOGLE_GEMINI_3_PRO_IMAGE_PREVIEW.id]:
+    GOOGLE_GEMINI_3_PRO_IMAGE_PREVIEW.supports.input,
+  [GOOGLE_GEMINI_3_1_FLASH_IMAGE.id]:
+    GOOGLE_GEMINI_3_1_FLASH_IMAGE.supports.input,
+  [GOOGLE_GEMINI_3_1_FLASH_IMAGE_PREVIEW.id]:
+    GOOGLE_GEMINI_3_1_FLASH_IMAGE_PREVIEW.supports.input,
+  [GOOGLE_GEMINI_3_1_FLASH_LITE.id]:
+    GOOGLE_GEMINI_3_1_FLASH_LITE.supports.input,
+  [GOOGLE_GEMINI_3_1_FLASH_LITE_IMAGE.id]:
+    GOOGLE_GEMINI_3_1_FLASH_LITE_IMAGE.supports.input,
+  [GOOGLE_GEMINI_3_1_FLASH_LITE_PREVIEW.id]:
+    GOOGLE_GEMINI_3_1_FLASH_LITE_PREVIEW.supports.input,
+  [GOOGLE_GEMINI_3_1_FLASH_LITE_BATCH.id]:
+    GOOGLE_GEMINI_3_1_FLASH_LITE_BATCH.supports.input,
+  [GOOGLE_GEMINI_3_1_PRO_PREVIEW.id]:
+    GOOGLE_GEMINI_3_1_PRO_PREVIEW.supports.input,
+  [GOOGLE_GEMINI_3_1_PRO_PREVIEW_CUSTOMTOOLS.id]:
+    GOOGLE_GEMINI_3_1_PRO_PREVIEW_CUSTOMTOOLS.supports.input,
+  [GOOGLE_GEMINI_3_1_PRO_PREVIEW_BATCH.id]:
+    GOOGLE_GEMINI_3_1_PRO_PREVIEW_BATCH.supports.input,
+  [GOOGLE_GEMINI_3_5_FLASH.id]: GOOGLE_GEMINI_3_5_FLASH.supports.input,
+  [GOOGLE_GEMINI_3_5_FLASH_LITE.id]:
+    GOOGLE_GEMINI_3_5_FLASH_LITE.supports.input,
+  [GOOGLE_GEMINI_3_5_FLASH_LITE_BATCH.id]:
+    GOOGLE_GEMINI_3_5_FLASH_LITE_BATCH.supports.input,
+  [GOOGLE_GEMINI_3_5_FLASH_BATCH.id]:
+    GOOGLE_GEMINI_3_5_FLASH_BATCH.supports.input,
+  [GOOGLE_GEMINI_3_6_FLASH.id]: GOOGLE_GEMINI_3_6_FLASH.supports.input,
+  [GOOGLE_GEMINI_3_6_FLASH_BATCH.id]:
+    GOOGLE_GEMINI_3_6_FLASH_BATCH.supports.input,
+  [GOOGLE_GEMINI_3_7_FLASH.id]: GOOGLE_GEMINI_3_7_FLASH.supports.input,
+  [GOOGLE_GEMINI_3_7_FLASH_BATCH.id]:
+    GOOGLE_GEMINI_3_7_FLASH_BATCH.supports.input,
+  [GOOGLE_GEMINI_3_8_FLASH.id]: GOOGLE_GEMINI_3_8_FLASH.supports.input,
+  [GOOGLE_GEMINI_3_8_FLASH_BATCH.id]:
+    GOOGLE_GEMINI_3_8_FLASH_BATCH.supports.input,
+  [GOOGLE_GEMMA_2_27B_IT.id]: GOOGLE_GEMMA_2_27B_IT.supports.input,
+  [GOOGLE_GEMMA_3_12B_IT.id]: GOOGLE_GEMMA_3_12B_IT.supports.input,
+  [GOOGLE_GEMMA_3_27B_IT.id]: GOOGLE_GEMMA_3_27B_IT.supports.input,
+  [GOOGLE_GEMMA_3_4B_IT.id]: GOOGLE_GEMMA_3_4B_IT.supports.input,
+  [GOOGLE_GEMMA_4_26B_A4B_IT.id]: GOOGLE_GEMMA_4_26B_A4B_IT.supports.input,
+  [GOOGLE_GEMMA_4_26B_A4B_IT_FREE.id]:
+    GOOGLE_GEMMA_4_26B_A4B_IT_FREE.supports.input,
+  [GOOGLE_GEMMA_4_31B_IT.id]: GOOGLE_GEMMA_4_31B_IT.supports.input,
+  [GOOGLE_GEMMA_4_31B_IT_FREE.id]: GOOGLE_GEMMA_4_31B_IT_FREE.supports.input,
+  [GRYPHE_MYTHOMAX_L2_13B.id]: GRYPHE_MYTHOMAX_L2_13B.supports.input,
+  [IBM_GRANITE_GRANITE_4_0_H_MICRO.id]:
+    IBM_GRANITE_GRANITE_4_0_H_MICRO.supports.input,
+  [IBM_GRANITE_GRANITE_4_2_8B.id]: IBM_GRANITE_GRANITE_4_2_8B.supports.input,
+  [INCEPTION_MERCURY_2.id]: INCEPTION_MERCURY_2.supports.input,
+  [INCEPTION_MERCURY_2_5.id]: INCEPTION_MERCURY_2_5.supports.input,
+  [INCLUSIONAI_LING_3_0_FLASH.id]: INCLUSIONAI_LING_3_0_FLASH.supports.input,
+  [INCLUSIONAI_LING_3_0_FLASH_FIN.id]:
+    INCLUSIONAI_LING_3_0_FLASH_FIN.supports.input,
+  [INCLUSIONAI_LING_3_0_FLASH_FIN_FREE.id]:
+    INCLUSIONAI_LING_3_0_FLASH_FIN_FREE.supports.input,
+  [INCLUSIONAI_LING_3_0_FLASH_SANTE_FREE.id]:
+    INCLUSIONAI_LING_3_0_FLASH_SANTE_FREE.supports.input,
+  [INCLUSIONAI_LING_3_0_FLASH_VL.id]:
+    INCLUSIONAI_LING_3_0_FLASH_VL.supports.input,
+  [INFERENCE_NET_SCHEMATRON_V2_SMALL.id]:
+    INFERENCE_NET_SCHEMATRON_V2_SMALL.supports.input,
+  [INFERENCE_NET_SCHEMATRON_V2_TURBO.id]:
+    INFERENCE_NET_SCHEMATRON_V2_TURBO.supports.input,
+  [KWAIPILOT_KAT_CODER_PRO_V2_5.id]:
+    KWAIPILOT_KAT_CODER_PRO_V2_5.supports.input,
+  [LIQUID_LFM_2_5_2_6B_FREE.id]: LIQUID_LFM_2_5_2_6B_FREE.supports.input,
+  [MANCER_WEAVER.id]: MANCER_WEAVER.supports.input,
+  [MEITUAN_LONGCAT_2_0.id]: MEITUAN_LONGCAT_2_0.supports.input,
+  [META_LLAMA_LLAMA_3_1_70B_INSTRUCT.id]:
+    META_LLAMA_LLAMA_3_1_70B_INSTRUCT.supports.input,
+  [META_LLAMA_LLAMA_3_1_8B_INSTRUCT.id]:
+    META_LLAMA_LLAMA_3_1_8B_INSTRUCT.supports.input,
+  [META_LLAMA_LLAMA_3_2_1B_INSTRUCT.id]:
+    META_LLAMA_LLAMA_3_2_1B_INSTRUCT.supports.input,
+  [META_LLAMA_LLAMA_3_2_3B_INSTRUCT.id]:
+    META_LLAMA_LLAMA_3_2_3B_INSTRUCT.supports.input,
+  [META_LLAMA_LLAMA_3_3_70B_INSTRUCT.id]:
+    META_LLAMA_LLAMA_3_3_70B_INSTRUCT.supports.input,
+  [META_LLAMA_LLAMA_4_MAVERICK.id]: META_LLAMA_LLAMA_4_MAVERICK.supports.input,
+  [META_LLAMA_LLAMA_4_SCOUT.id]: META_LLAMA_LLAMA_4_SCOUT.supports.input,
+  [META_LLAMA_LLAMA_GUARD_4_12B.id]:
+    META_LLAMA_LLAMA_GUARD_4_12B.supports.input,
+  [META_MUSE_GLIMMER_30B.id]: META_MUSE_GLIMMER_30B.supports.input,
+  [META_MUSE_SPARK_1_1.id]: META_MUSE_SPARK_1_1.supports.input,
+  [META_MUSE_SPARK_1_2.id]: META_MUSE_SPARK_1_2.supports.input,
+  [META_MUSE_SPARK_1_2_CONTRIBUTOR.id]:
+    META_MUSE_SPARK_1_2_CONTRIBUTOR.supports.input,
+  [META_MUSE_SPARK_1_3.id]: META_MUSE_SPARK_1_3.supports.input,
+  [META_MUSE_SPARK_1_3_CONTRIBUTOR.id]:
+    META_MUSE_SPARK_1_3_CONTRIBUTOR.supports.input,
+  [MICROSOFT_PHI_4.id]: MICROSOFT_PHI_4.supports.input,
+  [MICROSOFT_WIZARDLM_2_8X22B.id]: MICROSOFT_WIZARDLM_2_8X22B.supports.input,
+  [MINIMAX_MINIMAX_01.id]: MINIMAX_MINIMAX_01.supports.input,
+  [MINIMAX_MINIMAX_M1.id]: MINIMAX_MINIMAX_M1.supports.input,
+  [MINIMAX_MINIMAX_M2.id]: MINIMAX_MINIMAX_M2.supports.input,
+  [MINIMAX_MINIMAX_M2_HER.id]: MINIMAX_MINIMAX_M2_HER.supports.input,
+  [MINIMAX_MINIMAX_M2_1.id]: MINIMAX_MINIMAX_M2_1.supports.input,
+  [MINIMAX_MINIMAX_M2_5.id]: MINIMAX_MINIMAX_M2_5.supports.input,
+  [MINIMAX_MINIMAX_M2_7.id]: MINIMAX_MINIMAX_M2_7.supports.input,
+  [MINIMAX_MINIMAX_M3.id]: MINIMAX_MINIMAX_M3.supports.input,
+  [MISTRALAI_CODESTRAL_2508.id]: MISTRALAI_CODESTRAL_2508.supports.input,
+  [MISTRALAI_CODESTRAL_2508_BATCH.id]:
+    MISTRALAI_CODESTRAL_2508_BATCH.supports.input,
+  [MISTRALAI_DEVSTRAL_2512.id]: MISTRALAI_DEVSTRAL_2512.supports.input,
+  [MISTRALAI_MINISTRAL_14B_2512.id]:
+    MISTRALAI_MINISTRAL_14B_2512.supports.input,
+  [MISTRALAI_MINISTRAL_3B_2512.id]: MISTRALAI_MINISTRAL_3B_2512.supports.input,
+  [MISTRALAI_MINISTRAL_8B_2512.id]: MISTRALAI_MINISTRAL_8B_2512.supports.input,
+  [MISTRALAI_MINISTRAL_8B_2512_BATCH.id]:
+    MISTRALAI_MINISTRAL_8B_2512_BATCH.supports.input,
+  [MISTRALAI_MISTRAL_LARGE.id]: MISTRALAI_MISTRAL_LARGE.supports.input,
+  [MISTRALAI_MISTRAL_LARGE_2407.id]:
+    MISTRALAI_MISTRAL_LARGE_2407.supports.input,
+  [MISTRALAI_MISTRAL_LARGE_2512.id]:
+    MISTRALAI_MISTRAL_LARGE_2512.supports.input,
+  [MISTRALAI_MISTRAL_LARGE_2512_BATCH.id]:
+    MISTRALAI_MISTRAL_LARGE_2512_BATCH.supports.input,
+  [MISTRALAI_MISTRAL_MEDIUM_3.id]: MISTRALAI_MISTRAL_MEDIUM_3.supports.input,
+  [MISTRALAI_MISTRAL_MEDIUM_3_5.id]:
+    MISTRALAI_MISTRAL_MEDIUM_3_5.supports.input,
+  [MISTRALAI_MISTRAL_MEDIUM_3_5_BATCH.id]:
+    MISTRALAI_MISTRAL_MEDIUM_3_5_BATCH.supports.input,
+  [MISTRALAI_MISTRAL_MEDIUM_3_1.id]:
+    MISTRALAI_MISTRAL_MEDIUM_3_1.supports.input,
+  [MISTRALAI_MISTRAL_MEDIUM_3_1_BATCH.id]:
+    MISTRALAI_MISTRAL_MEDIUM_3_1_BATCH.supports.input,
+  [MISTRALAI_MISTRAL_NEMO.id]: MISTRALAI_MISTRAL_NEMO.supports.input,
+  [MISTRALAI_MISTRAL_SABA.id]: MISTRALAI_MISTRAL_SABA.supports.input,
+  [MISTRALAI_MISTRAL_SMALL_24B_INSTRUCT_2501.id]:
+    MISTRALAI_MISTRAL_SMALL_24B_INSTRUCT_2501.supports.input,
+  [MISTRALAI_MISTRAL_SMALL_2603.id]:
+    MISTRALAI_MISTRAL_SMALL_2603.supports.input,
+  [MISTRALAI_MISTRAL_SMALL_2603_BATCH.id]:
+    MISTRALAI_MISTRAL_SMALL_2603_BATCH.supports.input,
+  [MISTRALAI_MISTRAL_SMALL_3_1_24B_INSTRUCT.id]:
+    MISTRALAI_MISTRAL_SMALL_3_1_24B_INSTRUCT.supports.input,
+  [MISTRALAI_MISTRAL_SMALL_3_2_24B_INSTRUCT.id]:
+    MISTRALAI_MISTRAL_SMALL_3_2_24B_INSTRUCT.supports.input,
+  [MISTRALAI_MIXTRAL_8X22B_INSTRUCT.id]:
+    MISTRALAI_MIXTRAL_8X22B_INSTRUCT.supports.input,
+  [MISTRALAI_VOXTRAL_SMALL_24B_2507.id]:
+    MISTRALAI_VOXTRAL_SMALL_24B_2507.supports.input,
+  [MOONSHOTAI_KIMI_K2.id]: MOONSHOTAI_KIMI_K2.supports.input,
+  [MOONSHOTAI_KIMI_K2_0905.id]: MOONSHOTAI_KIMI_K2_0905.supports.input,
+  [MOONSHOTAI_KIMI_K2_THINKING.id]: MOONSHOTAI_KIMI_K2_THINKING.supports.input,
+  [MOONSHOTAI_KIMI_K2_5.id]: MOONSHOTAI_KIMI_K2_5.supports.input,
+  [MOONSHOTAI_KIMI_K2_6.id]: MOONSHOTAI_KIMI_K2_6.supports.input,
+  [MOONSHOTAI_KIMI_K2_7_CODE.id]: MOONSHOTAI_KIMI_K2_7_CODE.supports.input,
+  [MOONSHOTAI_KIMI_K3.id]: MOONSHOTAI_KIMI_K3.supports.input,
+  [MOONSHOTAI_KIMI_K3_BATCH.id]: MOONSHOTAI_KIMI_K3_BATCH.supports.input,
+  [MORPH_MORPH_V3_FAST.id]: MORPH_MORPH_V3_FAST.supports.input,
+  [MORPH_MORPH_V3_LARGE.id]: MORPH_MORPH_V3_LARGE.supports.input,
+  [NEX_AGI_NEX_N2_5_MINI_FREE.id]: NEX_AGI_NEX_N2_5_MINI_FREE.supports.input,
+  [NEX_AGI_NEX_N2_5_PRO_FREE.id]: NEX_AGI_NEX_N2_5_PRO_FREE.supports.input,
+  [NOUSRESEARCH_HERMES_3_LLAMA_3_1_405B.id]:
+    NOUSRESEARCH_HERMES_3_LLAMA_3_1_405B.supports.input,
+  [NOUSRESEARCH_HERMES_3_LLAMA_3_1_70B.id]:
+    NOUSRESEARCH_HERMES_3_LLAMA_3_1_70B.supports.input,
+  [NOUSRESEARCH_HERMES_4_405B.id]: NOUSRESEARCH_HERMES_4_405B.supports.input,
+  [NVIDIA_NEMOTRON_3_NANO_30B_A3B.id]:
+    NVIDIA_NEMOTRON_3_NANO_30B_A3B.supports.input,
+  [NVIDIA_NEMOTRON_3_NANO_OMNI_30B_A3B_REASONING_FREE.id]:
+    NVIDIA_NEMOTRON_3_NANO_OMNI_30B_A3B_REASONING_FREE.supports.input,
+  [NVIDIA_NEMOTRON_3_SUPER_120B_A12B.id]:
+    NVIDIA_NEMOTRON_3_SUPER_120B_A12B.supports.input,
+  [NVIDIA_NEMOTRON_3_SUPER_120B_A12B_FREE.id]:
+    NVIDIA_NEMOTRON_3_SUPER_120B_A12B_FREE.supports.input,
+  [NVIDIA_NEMOTRON_3_ULTRA_550B_A55B.id]:
+    NVIDIA_NEMOTRON_3_ULTRA_550B_A55B.supports.input,
+  [NVIDIA_NEMOTRON_3_ULTRA_550B_A55B_FREE.id]:
+    NVIDIA_NEMOTRON_3_ULTRA_550B_A55B_FREE.supports.input,
+  [NVIDIA_NEMOTRON_3_5_CONTENT_SAFETY.id]:
+    NVIDIA_NEMOTRON_3_5_CONTENT_SAFETY.supports.input,
+  [NVIDIA_NEMOTRON_3_5_CONTENT_SAFETY_FREE.id]:
+    NVIDIA_NEMOTRON_3_5_CONTENT_SAFETY_FREE.supports.input,
+  [NVIDIA_NEMOTRON_3_5_LIGHTNING.id]:
+    NVIDIA_NEMOTRON_3_5_LIGHTNING.supports.input,
+  [NVIDIA_NEMOTRON_3_5_LIGHTNING_FREE.id]:
+    NVIDIA_NEMOTRON_3_5_LIGHTNING_FREE.supports.input,
+  [OPENAI_GPT_3_5_TURBO.id]: OPENAI_GPT_3_5_TURBO.supports.input,
+  [OPENAI_GPT_3_5_TURBO_0613.id]: OPENAI_GPT_3_5_TURBO_0613.supports.input,
+  [OPENAI_GPT_3_5_TURBO_16K.id]: OPENAI_GPT_3_5_TURBO_16K.supports.input,
+  [OPENAI_GPT_3_5_TURBO_INSTRUCT.id]:
+    OPENAI_GPT_3_5_TURBO_INSTRUCT.supports.input,
+  [OPENAI_GPT_3_5_TURBO_BATCH.id]: OPENAI_GPT_3_5_TURBO_BATCH.supports.input,
+  [OPENAI_GPT_4.id]: OPENAI_GPT_4.supports.input,
+  [OPENAI_GPT_4_TURBO.id]: OPENAI_GPT_4_TURBO.supports.input,
+  [OPENAI_GPT_4_TURBO_BATCH.id]: OPENAI_GPT_4_TURBO_BATCH.supports.input,
+  [OPENAI_GPT_4_1.id]: OPENAI_GPT_4_1.supports.input,
+  [OPENAI_GPT_4_1_MINI.id]: OPENAI_GPT_4_1_MINI.supports.input,
+  [OPENAI_GPT_4_1_MINI_BATCH.id]: OPENAI_GPT_4_1_MINI_BATCH.supports.input,
+  [OPENAI_GPT_4_1_NANO.id]: OPENAI_GPT_4_1_NANO.supports.input,
+  [OPENAI_GPT_4_1_NANO_BATCH.id]: OPENAI_GPT_4_1_NANO_BATCH.supports.input,
+  [OPENAI_GPT_4_1_BATCH.id]: OPENAI_GPT_4_1_BATCH.supports.input,
+  [OPENAI_GPT_4O.id]: OPENAI_GPT_4O.supports.input,
+  [OPENAI_GPT_4O_2024_05_13.id]: OPENAI_GPT_4O_2024_05_13.supports.input,
+  [OPENAI_GPT_4O_2024_08_06.id]: OPENAI_GPT_4O_2024_08_06.supports.input,
+  [OPENAI_GPT_4O_2024_11_20.id]: OPENAI_GPT_4O_2024_11_20.supports.input,
+  [OPENAI_GPT_4O_MINI.id]: OPENAI_GPT_4O_MINI.supports.input,
+  [OPENAI_GPT_4O_MINI_2024_07_18.id]:
+    OPENAI_GPT_4O_MINI_2024_07_18.supports.input,
+  [OPENAI_GPT_4O_MINI_BATCH.id]: OPENAI_GPT_4O_MINI_BATCH.supports.input,
+  [OPENAI_GPT_4O_BATCH.id]: OPENAI_GPT_4O_BATCH.supports.input,
+  [OPENAI_GPT_5.id]: OPENAI_GPT_5.supports.input,
+  [OPENAI_GPT_5_IMAGE.id]: OPENAI_GPT_5_IMAGE.supports.input,
+  [OPENAI_GPT_5_IMAGE_MINI.id]: OPENAI_GPT_5_IMAGE_MINI.supports.input,
+  [OPENAI_GPT_5_MINI.id]: OPENAI_GPT_5_MINI.supports.input,
+  [OPENAI_GPT_5_MINI_BATCH.id]: OPENAI_GPT_5_MINI_BATCH.supports.input,
+  [OPENAI_GPT_5_NANO.id]: OPENAI_GPT_5_NANO.supports.input,
+  [OPENAI_GPT_5_NANO_BATCH.id]: OPENAI_GPT_5_NANO_BATCH.supports.input,
+  [OPENAI_GPT_5_PRO.id]: OPENAI_GPT_5_PRO.supports.input,
+  [OPENAI_GPT_5_PRO_BATCH.id]: OPENAI_GPT_5_PRO_BATCH.supports.input,
+  [OPENAI_GPT_5_BATCH.id]: OPENAI_GPT_5_BATCH.supports.input,
+  [OPENAI_GPT_5_1.id]: OPENAI_GPT_5_1.supports.input,
+  [OPENAI_GPT_5_1_CODEX.id]: OPENAI_GPT_5_1_CODEX.supports.input,
+  [OPENAI_GPT_5_1_CODEX_MAX.id]: OPENAI_GPT_5_1_CODEX_MAX.supports.input,
+  [OPENAI_GPT_5_1_CODEX_MINI.id]: OPENAI_GPT_5_1_CODEX_MINI.supports.input,
+  [OPENAI_GPT_5_1_BATCH.id]: OPENAI_GPT_5_1_BATCH.supports.input,
+  [OPENAI_GPT_5_2.id]: OPENAI_GPT_5_2.supports.input,
+  [OPENAI_GPT_5_2_CHAT.id]: OPENAI_GPT_5_2_CHAT.supports.input,
+  [OPENAI_GPT_5_2_CODEX.id]: OPENAI_GPT_5_2_CODEX.supports.input,
+  [OPENAI_GPT_5_2_PRO.id]: OPENAI_GPT_5_2_PRO.supports.input,
+  [OPENAI_GPT_5_2_PRO_BATCH.id]: OPENAI_GPT_5_2_PRO_BATCH.supports.input,
+  [OPENAI_GPT_5_2_BATCH.id]: OPENAI_GPT_5_2_BATCH.supports.input,
+  [OPENAI_GPT_5_3_CODEX.id]: OPENAI_GPT_5_3_CODEX.supports.input,
+  [OPENAI_GPT_5_4.id]: OPENAI_GPT_5_4.supports.input,
+  [OPENAI_GPT_5_4_IMAGE_2.id]: OPENAI_GPT_5_4_IMAGE_2.supports.input,
+  [OPENAI_GPT_5_4_MINI.id]: OPENAI_GPT_5_4_MINI.supports.input,
+  [OPENAI_GPT_5_4_MINI_BATCH.id]: OPENAI_GPT_5_4_MINI_BATCH.supports.input,
+  [OPENAI_GPT_5_4_NANO.id]: OPENAI_GPT_5_4_NANO.supports.input,
+  [OPENAI_GPT_5_4_NANO_BATCH.id]: OPENAI_GPT_5_4_NANO_BATCH.supports.input,
+  [OPENAI_GPT_5_4_PRO.id]: OPENAI_GPT_5_4_PRO.supports.input,
+  [OPENAI_GPT_5_4_PRO_BATCH.id]: OPENAI_GPT_5_4_PRO_BATCH.supports.input,
+  [OPENAI_GPT_5_4_BATCH.id]: OPENAI_GPT_5_4_BATCH.supports.input,
+  [OPENAI_GPT_5_5.id]: OPENAI_GPT_5_5.supports.input,
+  [OPENAI_GPT_5_5_PRO.id]: OPENAI_GPT_5_5_PRO.supports.input,
+  [OPENAI_GPT_5_5_PRO_BATCH.id]: OPENAI_GPT_5_5_PRO_BATCH.supports.input,
+  [OPENAI_GPT_5_5_BATCH.id]: OPENAI_GPT_5_5_BATCH.supports.input,
+  [OPENAI_GPT_5_6_LUNA.id]: OPENAI_GPT_5_6_LUNA.supports.input,
+  [OPENAI_GPT_5_6_LUNA_PRO.id]: OPENAI_GPT_5_6_LUNA_PRO.supports.input,
+  [OPENAI_GPT_5_6_LUNA_PRO_BATCH.id]:
+    OPENAI_GPT_5_6_LUNA_PRO_BATCH.supports.input,
+  [OPENAI_GPT_5_6_LUNA_BATCH.id]: OPENAI_GPT_5_6_LUNA_BATCH.supports.input,
+  [OPENAI_GPT_5_6_SOL.id]: OPENAI_GPT_5_6_SOL.supports.input,
+  [OPENAI_GPT_5_6_SOL_PRO.id]: OPENAI_GPT_5_6_SOL_PRO.supports.input,
+  [OPENAI_GPT_5_6_SOL_PRO_BATCH.id]:
+    OPENAI_GPT_5_6_SOL_PRO_BATCH.supports.input,
+  [OPENAI_GPT_5_6_SOL_BATCH.id]: OPENAI_GPT_5_6_SOL_BATCH.supports.input,
+  [OPENAI_GPT_5_6_TERRA.id]: OPENAI_GPT_5_6_TERRA.supports.input,
+  [OPENAI_GPT_5_6_TERRA_PRO.id]: OPENAI_GPT_5_6_TERRA_PRO.supports.input,
+  [OPENAI_GPT_5_6_TERRA_PRO_BATCH.id]:
+    OPENAI_GPT_5_6_TERRA_PRO_BATCH.supports.input,
+  [OPENAI_GPT_5_6_TERRA_BATCH.id]: OPENAI_GPT_5_6_TERRA_BATCH.supports.input,
+  [OPENAI_GPT_6_ASTRA.id]: OPENAI_GPT_6_ASTRA.supports.input,
+  [OPENAI_GPT_6_ASTRA_PRO.id]: OPENAI_GPT_6_ASTRA_PRO.supports.input,
+  [OPENAI_GPT_6_ASTRA_PRO_BATCH.id]:
+    OPENAI_GPT_6_ASTRA_PRO_BATCH.supports.input,
+  [OPENAI_GPT_6_ASTRA_BATCH.id]: OPENAI_GPT_6_ASTRA_BATCH.supports.input,
+  [OPENAI_GPT_6_LUNA.id]: OPENAI_GPT_6_LUNA.supports.input,
+  [OPENAI_GPT_6_LUNA_PRO.id]: OPENAI_GPT_6_LUNA_PRO.supports.input,
+  [OPENAI_GPT_6_LUNA_PRO_BATCH.id]: OPENAI_GPT_6_LUNA_PRO_BATCH.supports.input,
+  [OPENAI_GPT_6_LUNA_BATCH.id]: OPENAI_GPT_6_LUNA_BATCH.supports.input,
+  [OPENAI_GPT_6_SOL.id]: OPENAI_GPT_6_SOL.supports.input,
+  [OPENAI_GPT_6_SOL_PRO.id]: OPENAI_GPT_6_SOL_PRO.supports.input,
+  [OPENAI_GPT_6_SOL_PRO_BATCH.id]: OPENAI_GPT_6_SOL_PRO_BATCH.supports.input,
+  [OPENAI_GPT_6_SOL_BATCH.id]: OPENAI_GPT_6_SOL_BATCH.supports.input,
+  [OPENAI_GPT_AUDIO.id]: OPENAI_GPT_AUDIO.supports.input,
+  [OPENAI_GPT_AUDIO_MINI.id]: OPENAI_GPT_AUDIO_MINI.supports.input,
+  [OPENAI_GPT_CHAT_LATEST.id]: OPENAI_GPT_CHAT_LATEST.supports.input,
+  [OPENAI_GPT_OSS_120B.id]: OPENAI_GPT_OSS_120B.supports.input,
+  [OPENAI_GPT_OSS_120B_BATCH.id]: OPENAI_GPT_OSS_120B_BATCH.supports.input,
+  [OPENAI_GPT_OSS_20B.id]: OPENAI_GPT_OSS_20B.supports.input,
+  [OPENAI_GPT_OSS_20B_BATCH.id]: OPENAI_GPT_OSS_20B_BATCH.supports.input,
+  [OPENAI_GPT_OSS_SAFEGUARD_20B.id]:
+    OPENAI_GPT_OSS_SAFEGUARD_20B.supports.input,
+  [OPENAI_O1.id]: OPENAI_O1.supports.input,
+  [OPENAI_O1_PRO.id]: OPENAI_O1_PRO.supports.input,
+  [OPENAI_O3.id]: OPENAI_O3.supports.input,
+  [OPENAI_O3_MINI.id]: OPENAI_O3_MINI.supports.input,
+  [OPENAI_O3_MINI_HIGH.id]: OPENAI_O3_MINI_HIGH.supports.input,
+  [OPENAI_O3_MINI_BATCH.id]: OPENAI_O3_MINI_BATCH.supports.input,
+  [OPENAI_O3_PRO.id]: OPENAI_O3_PRO.supports.input,
+  [OPENAI_O3_BATCH.id]: OPENAI_O3_BATCH.supports.input,
+  [OPENAI_O4_MINI.id]: OPENAI_O4_MINI.supports.input,
+  [OPENAI_O4_MINI_HIGH.id]: OPENAI_O4_MINI_HIGH.supports.input,
+  [OPENAI_O4_MINI_BATCH.id]: OPENAI_O4_MINI_BATCH.supports.input,
+  [PERCEPTRON_PERCEPTRON_MK1.id]: PERCEPTRON_PERCEPTRON_MK1.supports.input,
+  [PERPLEXITY_SONAR.id]: PERPLEXITY_SONAR.supports.input,
+  [PERPLEXITY_SONAR_DEEP_RESEARCH.id]:
+    PERPLEXITY_SONAR_DEEP_RESEARCH.supports.input,
+  [PERPLEXITY_SONAR_PRO.id]: PERPLEXITY_SONAR_PRO.supports.input,
+  [PERPLEXITY_SONAR_PRO_SEARCH.id]: PERPLEXITY_SONAR_PRO_SEARCH.supports.input,
+  [PERPLEXITY_SONAR_REASONING_PRO.id]:
+    PERPLEXITY_SONAR_REASONING_PRO.supports.input,
+  [POOLSIDE_LAGUNA_S_2_1.id]: POOLSIDE_LAGUNA_S_2_1.supports.input,
+  [POOLSIDE_LAGUNA_S_2_1_FREE.id]: POOLSIDE_LAGUNA_S_2_1_FREE.supports.input,
+  [POOLSIDE_LAGUNA_XS_2_1.id]: POOLSIDE_LAGUNA_XS_2_1.supports.input,
+  [POOLSIDE_LAGUNA_XS_2_1_FREE.id]: POOLSIDE_LAGUNA_XS_2_1_FREE.supports.input,
+  [PRISM_ML_TERNARY_BONSAI_2_27B.id]:
+    PRISM_ML_TERNARY_BONSAI_2_27B.supports.input,
+  [QWEN_QWEN_2_5_72B_INSTRUCT.id]: QWEN_QWEN_2_5_72B_INSTRUCT.supports.input,
+  [QWEN_QWEN_2_5_7B_INSTRUCT.id]: QWEN_QWEN_2_5_7B_INSTRUCT.supports.input,
+  [QWEN_QWEN_2_5_CODER_32B_INSTRUCT.id]:
+    QWEN_QWEN_2_5_CODER_32B_INSTRUCT.supports.input,
+  [QWEN_QWEN_PLUS.id]: QWEN_QWEN_PLUS.supports.input,
+  [QWEN_QWEN_PLUS_2025_07_28.id]: QWEN_QWEN_PLUS_2025_07_28.supports.input,
+  [QWEN_QWEN2_5_VL_72B_INSTRUCT.id]:
+    QWEN_QWEN2_5_VL_72B_INSTRUCT.supports.input,
+  [QWEN_QWEN3_14B.id]: QWEN_QWEN3_14B.supports.input,
+  [QWEN_QWEN3_235B_A22B.id]: QWEN_QWEN3_235B_A22B.supports.input,
+  [QWEN_QWEN3_235B_A22B_2507.id]: QWEN_QWEN3_235B_A22B_2507.supports.input,
+  [QWEN_QWEN3_235B_A22B_THINKING_2507.id]:
+    QWEN_QWEN3_235B_A22B_THINKING_2507.supports.input,
+  [QWEN_QWEN3_30B_A3B.id]: QWEN_QWEN3_30B_A3B.supports.input,
+  [QWEN_QWEN3_30B_A3B_INSTRUCT_2507.id]:
+    QWEN_QWEN3_30B_A3B_INSTRUCT_2507.supports.input,
+  [QWEN_QWEN3_30B_A3B_THINKING_2507.id]:
+    QWEN_QWEN3_30B_A3B_THINKING_2507.supports.input,
+  [QWEN_QWEN3_32B.id]: QWEN_QWEN3_32B.supports.input,
+  [QWEN_QWEN3_8B.id]: QWEN_QWEN3_8B.supports.input,
+  [QWEN_QWEN3_CODER.id]: QWEN_QWEN3_CODER.supports.input,
+  [QWEN_QWEN3_CODER_30B_A3B_INSTRUCT.id]:
+    QWEN_QWEN3_CODER_30B_A3B_INSTRUCT.supports.input,
+  [QWEN_QWEN3_CODER_FLASH.id]: QWEN_QWEN3_CODER_FLASH.supports.input,
+  [QWEN_QWEN3_CODER_NEXT.id]: QWEN_QWEN3_CODER_NEXT.supports.input,
+  [QWEN_QWEN3_CODER_PLUS.id]: QWEN_QWEN3_CODER_PLUS.supports.input,
+  [QWEN_QWEN3_MAX.id]: QWEN_QWEN3_MAX.supports.input,
+  [QWEN_QWEN3_MAX_THINKING.id]: QWEN_QWEN3_MAX_THINKING.supports.input,
+  [QWEN_QWEN3_NEXT_80B_A3B_INSTRUCT.id]:
+    QWEN_QWEN3_NEXT_80B_A3B_INSTRUCT.supports.input,
+  [QWEN_QWEN3_NEXT_80B_A3B_THINKING.id]:
+    QWEN_QWEN3_NEXT_80B_A3B_THINKING.supports.input,
+  [QWEN_QWEN3_VL_235B_A22B_INSTRUCT.id]:
+    QWEN_QWEN3_VL_235B_A22B_INSTRUCT.supports.input,
+  [QWEN_QWEN3_VL_235B_A22B_THINKING.id]:
+    QWEN_QWEN3_VL_235B_A22B_THINKING.supports.input,
+  [QWEN_QWEN3_VL_30B_A3B_INSTRUCT.id]:
+    QWEN_QWEN3_VL_30B_A3B_INSTRUCT.supports.input,
+  [QWEN_QWEN3_VL_30B_A3B_THINKING.id]:
+    QWEN_QWEN3_VL_30B_A3B_THINKING.supports.input,
+  [QWEN_QWEN3_VL_32B_INSTRUCT.id]: QWEN_QWEN3_VL_32B_INSTRUCT.supports.input,
+  [QWEN_QWEN3_VL_8B_INSTRUCT.id]: QWEN_QWEN3_VL_8B_INSTRUCT.supports.input,
+  [QWEN_QWEN3_VL_8B_THINKING.id]: QWEN_QWEN3_VL_8B_THINKING.supports.input,
+  [QWEN_QWEN3_5_122B_A10B.id]: QWEN_QWEN3_5_122B_A10B.supports.input,
+  [QWEN_QWEN3_5_27B.id]: QWEN_QWEN3_5_27B.supports.input,
+  [QWEN_QWEN3_5_35B_A3B.id]: QWEN_QWEN3_5_35B_A3B.supports.input,
+  [QWEN_QWEN3_5_397B_A17B.id]: QWEN_QWEN3_5_397B_A17B.supports.input,
+  [QWEN_QWEN3_5_9B.id]: QWEN_QWEN3_5_9B.supports.input,
+  [QWEN_QWEN3_5_FLASH_02_23.id]: QWEN_QWEN3_5_FLASH_02_23.supports.input,
+  [QWEN_QWEN3_5_PLUS_02_15.id]: QWEN_QWEN3_5_PLUS_02_15.supports.input,
+  [QWEN_QWEN3_5_PLUS_20260420.id]: QWEN_QWEN3_5_PLUS_20260420.supports.input,
+  [QWEN_QWEN3_6_27B.id]: QWEN_QWEN3_6_27B.supports.input,
+  [QWEN_QWEN3_6_35B_A3B.id]: QWEN_QWEN3_6_35B_A3B.supports.input,
+  [QWEN_QWEN3_6_FLASH.id]: QWEN_QWEN3_6_FLASH.supports.input,
+  [QWEN_QWEN3_6_MAX_PREVIEW.id]: QWEN_QWEN3_6_MAX_PREVIEW.supports.input,
+  [QWEN_QWEN3_6_PLUS.id]: QWEN_QWEN3_6_PLUS.supports.input,
+  [QWEN_QWEN3_7_FLASH.id]: QWEN_QWEN3_7_FLASH.supports.input,
+  [QWEN_QWEN3_7_MAX.id]: QWEN_QWEN3_7_MAX.supports.input,
+  [QWEN_QWEN3_7_PLUS.id]: QWEN_QWEN3_7_PLUS.supports.input,
+  [QWEN_QWEN3_8_2_4T_A95B.id]: QWEN_QWEN3_8_2_4T_A95B.supports.input,
+  [QWEN_QWEN3_8_27B.id]: QWEN_QWEN3_8_27B.supports.input,
+  [QWEN_QWEN3_8_27B_FREE.id]: QWEN_QWEN3_8_27B_FREE.supports.input,
+  [QWEN_QWEN3_8_FLASH.id]: QWEN_QWEN3_8_FLASH.supports.input,
+  [QWEN_QWEN3_8_MAX_0902.id]: QWEN_QWEN3_8_MAX_0902.supports.input,
+  [QWEN_QWEN3_8_MAX_PRIME.id]: QWEN_QWEN3_8_MAX_PRIME.supports.input,
+  [QWEN_QWEN3_8_OMNI_FLASH.id]: QWEN_QWEN3_8_OMNI_FLASH.supports.input,
+  [REKAAI_REKA_EDGE.id]: REKAAI_REKA_EDGE.supports.input,
+  [REKAAI_REKA_FLASH_3.id]: REKAAI_REKA_FLASH_3.supports.input,
+  [RELACE_RELACE_APPLY_3.id]: RELACE_RELACE_APPLY_3.supports.input,
+  [RELACE_RELACE_SEARCH.id]: RELACE_RELACE_SEARCH.supports.input,
+  [SAKANA_FUGU_MAX.id]: SAKANA_FUGU_MAX.supports.input,
+  [SAKANA_FUGU_ULTRA.id]: SAKANA_FUGU_ULTRA.supports.input,
+  [SAKANA_FUGU_ULTRA_V2.id]: SAKANA_FUGU_ULTRA_V2.supports.input,
+  [SAKANA_SAKANA_NAMAZU.id]: SAKANA_SAKANA_NAMAZU.supports.input,
+  [SAO10K_L3_LUNARIS_8B.id]: SAO10K_L3_LUNARIS_8B.supports.input,
+  [SAO10K_L3_1_EURYALE_70B.id]: SAO10K_L3_1_EURYALE_70B.supports.input,
+  [SAO10K_L3_3_EURYALE_70B.id]: SAO10K_L3_3_EURYALE_70B.supports.input,
+  [STEALTH_SPACE_BUNNY_ALPHA.id]: STEALTH_SPACE_BUNNY_ALPHA.supports.input,
+  [STEPFUN_STEP_3_5_FLASH.id]: STEPFUN_STEP_3_5_FLASH.supports.input,
+  [STEPFUN_STEP_3_7_FLASH.id]: STEPFUN_STEP_3_7_FLASH.supports.input,
+  [TENCENT_HUNYUAN_A13B_INSTRUCT.id]:
+    TENCENT_HUNYUAN_A13B_INSTRUCT.supports.input,
+  [TENCENT_HY_MT2_1_8B.id]: TENCENT_HY_MT2_1_8B.supports.input,
+  [TENCENT_HY_MT2_30B_A3B.id]: TENCENT_HY_MT2_30B_A3B.supports.input,
+  [TENCENT_HY_MT2_7B.id]: TENCENT_HY_MT2_7B.supports.input,
+  [TENCENT_HY3.id]: TENCENT_HY3.supports.input,
+  [TENCENT_HY3_PREVIEW.id]: TENCENT_HY3_PREVIEW.supports.input,
+  [TENCENT_HY4_PREVIEW.id]: TENCENT_HY4_PREVIEW.supports.input,
+  [THEDRUMMER_CYDONIA_24B_V4_1.id]: THEDRUMMER_CYDONIA_24B_V4_1.supports.input,
+  [THEDRUMMER_SKYFALL_36B_V2.id]: THEDRUMMER_SKYFALL_36B_V2.supports.input,
+  [THEDRUMMER_UNSLOPNEMO_12B.id]: THEDRUMMER_UNSLOPNEMO_12B.supports.input,
+  [THINKINGMACHINES_INKLING.id]: THINKINGMACHINES_INKLING.supports.input,
+  [THINKINGMACHINES_INKLING_SMALL.id]:
+    THINKINGMACHINES_INKLING_SMALL.supports.input,
+  [THINKINGMACHINES_INKLING_SMALL_FREE.id]:
+    THINKINGMACHINES_INKLING_SMALL_FREE.supports.input,
+  [THINKINGMACHINES_INKLING_FREE.id]:
+    THINKINGMACHINES_INKLING_FREE.supports.input,
+  [UNBIASED_PARETO.id]: UNBIASED_PARETO.supports.input,
+  [UNDI95_REMM_SLERP_L2_13B.id]: UNDI95_REMM_SLERP_L2_13B.supports.input,
+  [UPSTAGE_SOLAR_MINI4.id]: UPSTAGE_SOLAR_MINI4.supports.input,
+  [UPSTAGE_SOLAR_PRO_3.id]: UPSTAGE_SOLAR_PRO_3.supports.input,
+  [UPSTAGE_SOLAR_PRO4.id]: UPSTAGE_SOLAR_PRO4.supports.input,
+  [WRITER_PALMYRA_X5.id]: WRITER_PALMYRA_X5.supports.input,
+  [X_AI_GROK_4_20.id]: X_AI_GROK_4_20.supports.input,
+  [X_AI_GROK_4_20_MULTI_AGENT.id]: X_AI_GROK_4_20_MULTI_AGENT.supports.input,
+  [X_AI_GROK_4_3.id]: X_AI_GROK_4_3.supports.input,
+  [X_AI_GROK_4_3_BATCH.id]: X_AI_GROK_4_3_BATCH.supports.input,
+  [X_AI_GROK_4_5.id]: X_AI_GROK_4_5.supports.input,
+  [X_AI_GROK_4_6.id]: X_AI_GROK_4_6.supports.input,
+  [X_AI_GROK_4_7.id]: X_AI_GROK_4_7.supports.input,
+  [X_AI_GROK_BUILD_0_1.id]: X_AI_GROK_BUILD_0_1.supports.input,
+  [XIAOMI_MIMO_V2_5.id]: XIAOMI_MIMO_V2_5.supports.input,
+  [XIAOMI_MIMO_V2_5_PRO.id]: XIAOMI_MIMO_V2_5_PRO.supports.input,
+  [XIAOMI_MIMO_V2_6_FLASH.id]: XIAOMI_MIMO_V2_6_FLASH.supports.input,
+  [XIAOMI_MIMO_V2_6_PRO.id]: XIAOMI_MIMO_V2_6_PRO.supports.input,
+  [XIAOMI_MIMO_V2_6_PRO_ULTRASPEED.id]:
+    XIAOMI_MIMO_V2_6_PRO_ULTRASPEED.supports.input,
+  [Z_AI_GLM_4_5.id]: Z_AI_GLM_4_5.supports.input,
+  [Z_AI_GLM_4_5_AIR.id]: Z_AI_GLM_4_5_AIR.supports.input,
+  [Z_AI_GLM_4_5V.id]: Z_AI_GLM_4_5V.supports.input,
+  [Z_AI_GLM_4_6.id]: Z_AI_GLM_4_6.supports.input,
+  [Z_AI_GLM_4_6V.id]: Z_AI_GLM_4_6V.supports.input,
+  [Z_AI_GLM_4_7.id]: Z_AI_GLM_4_7.supports.input,
+  [Z_AI_GLM_4_7_FLASH.id]: Z_AI_GLM_4_7_FLASH.supports.input,
+  [Z_AI_GLM_5.id]: Z_AI_GLM_5.supports.input,
+  [Z_AI_GLM_5_TURBO.id]: Z_AI_GLM_5_TURBO.supports.input,
+  [Z_AI_GLM_5_1.id]: Z_AI_GLM_5_1.supports.input,
+  [Z_AI_GLM_5_2.id]: Z_AI_GLM_5_2.supports.input,
+  [Z_AI_GLM_5_2_FREE.id]: Z_AI_GLM_5_2_FREE.supports.input,
+  [Z_AI_GLM_5_3.id]: Z_AI_GLM_5_3.supports.input,
+  [Z_AI_GLM_5_3_FLASH.id]: Z_AI_GLM_5_3_FLASH.supports.input,
+  [Z_AI_GLM_5_3_FLASH_BATCH.id]: Z_AI_GLM_5_3_FLASH_BATCH.supports.input,
+  [Z_AI_GLM_5_3_FLASHX.id]: Z_AI_GLM_5_3_FLASHX.supports.input,
+  [Z_AI_GLM_5_3_PRIME.id]: Z_AI_GLM_5_3_PRIME.supports.input,
+  [Z_AI_GLM_5_3_BATCH.id]: Z_AI_GLM_5_3_BATCH.supports.input,
+  [Z_AI_GLM_5V_TURBO.id]: Z_AI_GLM_5V_TURBO.supports.input,
+  'openrouter/auto': ['text', 'image', 'audio', 'video', 'document'],
+} satisfies {
+  [K in (typeof OPENROUTER_CHAT_MODELS)[number]]: OpenRouterModelInputModalitiesByName[K]
+}
+
 export type OpenRouterChatModelToolCapabilitiesByName = {
   [K in (typeof OPENROUTER_CHAT_MODELS)[number]]: readonly [
     'web_search',
diff --git a/packages/ai-openrouter/tests/input-modalities.test.ts b/packages/ai-openrouter/tests/input-modalities.test.ts
new file mode 100644
index 0000000000..a8c570f273
--- /dev/null
+++ b/packages/ai-openrouter/tests/input-modalities.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import { createOpenRouterText } from '../src/adapters/text'
+import { createOpenRouterResponsesText } from '../src/adapters/responses-text'
+import type { OpenRouterTextModels } from '../src/adapters/text'
+
+// Both text adapters read the same model-meta map, so each case checks both.
+function inputModalitiesOf(model: OpenRouterTextModels) {
+  return {
+    chat: createOpenRouterText(model, 'test-key').inputModalities,
+    responses: createOpenRouterResponsesText(model, 'test-key').inputModalities,
+  }
+}
+
+describe('OpenRouter text adapters inputModalities', () => {
+  it.each([
+    ['anthropic/claude-sonnet-4.5', ['text', 'image', 'document']],
+    ['deepseek/deepseek-v4-pro', ['text']],
+  ] as const)('reads the list of %s from model-meta', (model, expected) => {
+    expect(inputModalitiesOf(model)).toEqual({
+      chat: expected,
+      responses: expected,
+    })
+  })
+
+  it('is undefined for a model id that model-meta does not list', () => {
+    // @ts-expect-error a JS caller or a cast can pass an id the types reject
+    const modalities = inputModalitiesOf('unlisted/model')
+
+    expect(modalities).toEqual({ chat: undefined, responses: undefined })
+  })
+})
diff --git a/scripts/convert-openrouter-models.ts b/scripts/convert-openrouter-models.ts
index 3312738b43..1239398bdc 100644
--- a/scripts/convert-openrouter-models.ts
+++ b/scripts/convert-openrouter-models.ts
@@ -85,6 +85,38 @@ function generateChatModelsArray(): string {
     .join('\n')}\n] as const`
 }
 
+/**
+ * Runtime twin of OpenRouterModelInputModalitiesByName for the chat models,
+ * read by the text adapters' `inputModalities`. The `satisfies` clause makes a
+ * missing, extra, or different entry a type error.
+ */
+function generateChatModelInputModalitiesMap(): string {
+  const idRefs = Array.from(chatModels)
+  if (idRefs.length === 0) {
+    return ''
+  }
+  const entries = idRefs.map(
+    (idRef) => `  [${idRef}]: ${idRef.replace(/\.id$/, '.supports.input')},`,
+  )
+  if (
+    !idRefs.some(
+      (id) => id.includes('openrouter/auto') || id === 'OPENROUTER_AUTO.id',
+    )
+  ) {
+    entries.push(
+      `  'openrouter/auto': ['text', 'image', 'audio', 'video', 'document'],`,
+    )
+  }
+  return `/**
+ * Generated: runtime map from chat model id to its input modalities, read by
+ * the text adapters' \`inputModalities\`. \`satisfies\` ties it to
+ * \`OpenRouterModelInputModalitiesByName\`, so the two cannot drift.
+ */
+export const OPENROUTER_MODEL_INPUT_MODALITIES: Readonly<Record<string, ReadonlyArray<Modality>>> = {\n${entries.join(
+    '\n',
+  )}\n} satisfies { [K in (typeof OPENROUTER_CHAT_MODELS)[number]]: OpenRouterModelInputModalitiesByName[K] }`
+}
+
 /**
  * OpenRouter's web_search and web_fetch plugins work across all chat models via
  * the gateway, so the tool-capability map is structural and identical for every
@@ -359,6 +391,7 @@ console.log('// Generated ModelMeta entries:')
 console.log('')
 const file = `// AUTO-GENERATED by scripts/convert-openrouter-models.ts from scripts/openrouter.models.json
 // (\`pnpm generate:models\`). Do not edit by hand — every block here is rewritten on sync.
+import type { Modality } from '@tanstack/ai'
 import type { OpenRouterBaseOptions, OpenRouterCommonOptions } from './text/text-provider-options'
   
 ${convertModels(models)}
@@ -369,6 +402,8 @@ ${createPerModelInputModalities()}
 
 ${generateChatModelsArray()}
 
+${generateChatModelInputModalitiesMap()}
+
 ${generateChatToolCapabilitiesType()}
 ${generateVideoModelsArray()}
 ${generateVideoModelMeta()}

From 202661937bbd8259fc292712b0aedc95f91069e2 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 29 Sep 2026 11:56:42 +0200
Subject: [PATCH 059/286] feat(ai-harness): keep agent media, send stored files
 to the model, and media in history

defineHarness takes a media option. Sessions store files (putMedia, getMedia, loadMedia, mediaUrl), keep the media that agents make and publish a harness.media event for each file, check each file against the model's inputs, and save media records on messages so a UI can show them after a restart. The model sync now also updates the runtime input maps.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-harness/src/client.ts             |   9 +-
 packages/ai-harness/src/define.ts             |   9 +-
 packages/ai-harness/src/host.ts               |  27 +-
 packages/ai-harness/src/index.ts              |   4 +
 packages/ai-harness/src/media-ref.ts          |  10 +-
 packages/ai-harness/src/session.ts            | 205 +++++++-
 packages/ai-harness/src/view/reduce.ts        |  64 +--
 .../ai-harness/tests/session-media.test.ts    | 450 ++++++++++++++++++
 scripts/model-sync/native-insert.test.ts      | 116 +++--
 scripts/model-sync/native-insert.ts           |  40 +-
 10 files changed, 826 insertions(+), 108 deletions(-)
 create mode 100644 packages/ai-harness/tests/session-media.test.ts

diff --git a/packages/ai-harness/src/client.ts b/packages/ai-harness/src/client.ts
index 0c865699da..e1177f6f19 100644
--- a/packages/ai-harness/src/client.ts
+++ b/packages/ai-harness/src/client.ts
@@ -1,6 +1,7 @@
 // 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 { AgentInputOf } from './agents'
 import type { AnyHarness, HarnessAgentsOf } from './define'
@@ -186,10 +187,10 @@ export function createHarnessClient<THarness extends AnyHarness>(
       const refusal: unknown = await response.json().catch(() => undefined)
       throw failure('upload', response, refusal)
     }
-    // The handler answers POST media with the stored MediaRecord.
-    // ponytail: no shape check here; `isMediaRecord` in media-ref.ts is not
-    // exported yet. Export it and narrow instead of this cast.
-    return (await response.json()) as MediaRecord
+    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) => {
diff --git a/packages/ai-harness/src/define.ts b/packages/ai-harness/src/define.ts
index a2bacc3968..9e32beccfd 100644
--- a/packages/ai-harness/src/define.ts
+++ b/packages/ai-harness/src/define.ts
@@ -8,6 +8,7 @@ import type {
   SystemPrompt,
 } from '@tanstack/ai'
 import type { AnyAgent } from './agents'
+import type { MediaOptions } from './media'
 import type { HarnessPlugin } from './plugins'
 import type { BusyPolicy } from './types'
 
@@ -55,6 +56,12 @@ export interface HarnessConfig<
   plugins?: () => ReadonlyArray<HarnessPlugin>
   /** What a `prompt` does while a chat turn runs. Default `'queue'`. */
   busy?: BusyPolicy
+  /**
+   * Files sent to a turn, and media agents make: the size limit, the kinds a
+   * user can send, the kinds the model reads, and an optional transcriber for
+   * audio the model cannot read.
+   */
+  media?: MediaOptions
   /** What clients may call. Nothing is exposed by default. */
   expose?: {
     agents?: ReadonlyArray<TAgents[number]['name'] | TSubagents[number]['name']>
@@ -94,7 +101,7 @@ export function isHarnessDefinition(value: unknown): value is AnyHarness {
 
 /**
  * Define a harness: a reusable, typed agent configuration. Use the same option
- * names as `chat()`, plus `agents`, `plugins`, `busy`, and `expose`.
+ * names as `chat()`, plus `agents`, `plugins`, `busy`, `expose`, and `media`.
  *
  * @example
  * ```ts
diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
index 9fb84539b7..7766cabc88 100644
--- a/packages/ai-harness/src/host.ts
+++ b/packages/ai-harness/src/host.ts
@@ -2,8 +2,11 @@ import { memoryPersistence } from '@tanstack/ai-persistence'
 import { HarnessSession } from './session'
 import type {
   AIPersistence,
+  ArtifactStore,
+  BlobStore,
   ChatTranscriptStores,
   CredentialStore,
+  GenerationRunStore,
   InboxStore,
 } from '@tanstack/ai-persistence'
 import type { AnyHarness } from './define'
@@ -12,10 +15,17 @@ import type { Principal } from './types'
 /**
  * The stores a host needs: a message store, plus any of runs, interrupts,
  * metadata, and inbox. Without an inbox, inputs are kept in memory and a
- * restart loses the ones not yet applied.
+ * restart loses the ones not yet applied. Without `artifacts`, `blobs`, and
+ * `generationRuns`, media is kept in memory too.
  */
 export type HarnessPersistence = AIPersistence<
-  ChatTranscriptStores & { inbox?: InboxStore; credentials?: CredentialStore }
+  ChatTranscriptStores & {
+    inbox?: InboxStore
+    credentials?: CredentialStore
+    artifacts?: ArtifactStore
+    blobs?: BlobStore
+    generationRuns?: GenerationRunStore
+  }
 >
 
 export interface HarnessHostOptions {
@@ -73,6 +83,18 @@ export function createHarnessHost(
   // `stores.credentials` to keep sign-ins across restarts.
   const credentials =
     persistence.stores.credentials ?? memoryPersistence().stores.credentials
+  // ponytail: memory media stores when the stores have none. Pass
+  // `stores.artifacts`, `stores.blobs`, and `stores.generationRuns` to keep
+  // media across restarts.
+  const memory = memoryPersistence().stores
+  const media = {
+    stores: {
+      artifacts: persistence.stores.artifacts ?? memory.artifacts,
+      blobs: persistence.stores.blobs ?? memory.blobs,
+      generationRuns:
+        persistence.stores.generationRuns ?? memory.generationRuns,
+    },
+  }
   const sessions = new Map<string, Promise<HarnessSession>>()
   const hostId = `host-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`
 
@@ -87,6 +109,7 @@ export function createHarnessHost(
           persistence,
           inbox,
           credentials,
+          media,
           hostId,
           ...(principal ? { principal } : {}),
           onClose: () => sessions.delete(key),
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index e63845e269..3db6e68777 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -93,12 +93,16 @@ export type {
 
 export {
   MEDIA_URL_PREFIX,
+  isMediaRecord,
   kindOf,
   mediaIdOf,
   mediaOfMessage,
   mediaPart,
 } from './media-ref'
 
+export { MediaError } from './media'
+export type { MediaOptions } from './media'
+
 export {
   HARNESS_PROTOCOL_VERSION,
   applyInput,
diff --git a/packages/ai-harness/src/media-ref.ts b/packages/ai-harness/src/media-ref.ts
index ad849dfd36..5e83ac15d2 100644
--- a/packages/ai-harness/src/media-ref.ts
+++ b/packages/ai-harness/src/media-ref.ts
@@ -23,7 +23,15 @@ function isOptionalString(value: unknown) {
   return value === undefined || typeof value === 'string'
 }
 
-function isMediaRecord(value: unknown): value is MediaRecord {
+/**
+ * True for a value with the shape of a `MediaRecord`, for example the answer
+ * of an upload or the value of a `harness.media` event.
+ *
+ * @example
+ * const value: unknown = await response.json()
+ * if (isMediaRecord(value)) console.log(value.name)
+ */
+export function isMediaRecord(value: unknown): value is MediaRecord {
   if (!isRecord(value)) return false
   const hasOptionalIds =
     isOptionalString(value.runId) && isOptionalString(value.subagentRunId)
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index f5be633c5d..efce25b056 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -15,6 +15,8 @@ import { checkConfigValue } from './config'
 import { withPersistence } from '@tanstack/ai-persistence'
 import { AgentRegistry } from './agents'
 import { SessionFeed } from './feed'
+import { createMediaStore, mediaCapture, mediaMiddleware } from './media'
+import { mediaIdOf, mediaOfMessage } from './media-ref'
 import { OperationImpl } from './operation'
 import { mountPlugins } from './plugins'
 import {
@@ -25,8 +27,10 @@ import {
 import { HARNESS_EVENTS } from './types'
 import type {
   AnyChatMiddleware,
+  AnyTextAdapter,
   AnyTool,
   Interrupt,
+  Modality,
   ModelMessage,
   RunAgentResumeItem,
   SchemaInput,
@@ -34,11 +38,17 @@ import type {
   SubagentBinding,
 } from '@tanstack/ai'
 import type {
+  AIPersistence,
+  ArtifactStore,
+  BlobBody,
+  BlobStore,
   CredentialStore,
+  GenerationRunStore,
   InboxEntry,
   InboxStore,
 } from '@tanstack/ai-persistence'
 import type { CredentialsAccess } from './auth'
+import type { MediaStore } from './media'
 import type { PluginSessionApi, Question } from './commands'
 import type { ConfigOption } from './config'
 import type {
@@ -62,6 +72,8 @@ import type {
   ChatTurnResult,
   Cursor,
   HarnessInput,
+  MediaKind,
+  MediaRecord,
   Operation,
   Principal,
   Receipt,
@@ -170,6 +182,12 @@ export interface SessionDependencies {
   persistence: HarnessPersistence
   inbox: InboxStore
   credentials: CredentialStore
+  /** Where media lives: file records, bytes, and generation runs. */
+  media: AIPersistence<{
+    artifacts: ArtifactStore
+    blobs: BlobStore
+    generationRuns: GenerationRunStore
+  }>
   principal?: Principal
   /** Identifies this host on run leases. */
   hostId: string
@@ -216,6 +234,20 @@ function referenceNote(agent: string, result: unknown): string {
   return `[${agent} finished] ${clipped}`
 }
 
+/**
+ * The kinds a model reads: the adapter's input list, narrowed by
+ * `media.accepts`. Either one alone when only one is known, and `undefined`
+ * (send every kind) when neither is.
+ */
+function acceptedKinds(
+  modalities: ReadonlyArray<Modality> | undefined,
+  accepts: ReadonlyArray<MediaKind> | undefined,
+) {
+  if (modalities === undefined || accepts === undefined)
+    return accepts ?? modalities
+  return accepts.filter((kind) => modalities.includes(kind))
+}
+
 /**
  * A live harness session: one conversation (`threadId`) with its plugins,
  * operations, inbox, and event stream. Open one with `host.open()`.
@@ -270,12 +302,20 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   private readonly localState = new Map<string, unknown>()
   private readonly credentialAccess: CredentialsAccess
   private readonly services: PluginServices
+  private readonly media: SessionDependencies['media']
+  private readonly mediaStore: MediaStore
 
   constructor(deps: SessionDependencies) {
     this.harness = deps.harness as THarness
     this.threadId = deps.threadId
     this.persistence = deps.persistence
     this.inbox = deps.inbox
+    this.media = deps.media
+    this.mediaStore = createMediaStore({
+      persistence: deps.media,
+      threadId: deps.threadId,
+      options: this.harness.media,
+    })
     this.principal = deps.principal
     this.onClose = deps.onClose
     this.checkpoint = checkpointMiddleware(deps.persistence, deps.hostId)
@@ -528,6 +568,45 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }
   }
 
+  // ===========================
+  // Media
+  // ===========================
+
+  /**
+   * Store a file in the media store of this thread. Send it to a turn with
+   * `mediaPart(record)`. Throws a `MediaError`: 413 when the file is bigger
+   * than `media.maxBytes`, 415 for a type or kind the harness does not take.
+   *
+   * @example
+   * const record = await session.putMedia(bytes, { mimeType: 'image/png', name: 'cat.png' })
+   * session.prompt([{ type: 'text', content: 'What is this?' }, mediaPart(record)])
+   */
+  putMedia(body: BlobBody, info: { mimeType: string; name: string }) {
+    return this.mediaStore.put(body, info)
+  }
+
+  /** The record of a media file of this thread, or `null` when it is not found. */
+  getMedia(id: string) {
+    return this.mediaStore.get(id)
+  }
+
+  /** The bytes of a media file. Throws a `MediaError` with 404 when it is not found. */
+  loadMedia(id: string) {
+    return this.mediaStore.load(id)
+  }
+
+  /**
+   * A URL for a media file, for `<img>`, `<audio>`, or `<video>`. A session
+   * has no server, so this is a data URL for a file up to 1 MB, and `{}` for
+   * a bigger file (use `loadMedia`).
+   */
+  async mediaUrl(id: string) {
+    const url = await this.mediaStore.dataUrl(id)
+    const answer: { url?: string; expiresAt?: number } =
+      url === undefined ? {} : { url }
+    return answer
+  }
+
   // ===========================
   // Config, commands, questions
   // ===========================
@@ -999,7 +1078,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   }
 
   private warn(
-    operation: OperationImpl<ChatTurnResult>,
+    operation: OperationImpl<unknown> | OperationImpl<ChatTurnResult>,
     plugin: string,
     error: unknown,
   ) {
@@ -1066,20 +1145,94 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     return root.child()
   }
 
-  /** What plugins add to every agent run: session plugins, then run plugins. */
-  private binding(runPlugins?: MountedPlugins) {
+  /**
+   * What every agent run of `operation` gets: the middleware of session
+   * plugins, then of run plugins, then the session's media middleware. It
+   * keeps the media the agents make, publishes a `harness.media` event for
+   * each file, and pushes its record to `captured`.
+   */
+  private binding(
+    operation: OperationImpl<unknown> | OperationImpl<ChatTurnResult>,
+    captured: Array<MediaRecord>,
+    runPlugins?: MountedPlugins,
+  ) {
+    const options = this.harness.media
     return {
       generationMiddleware: [
         ...(this.sessionPlugins?.generationMiddleware ?? []),
         ...(runPlugins?.generationMiddleware ?? []),
+        ...mediaCapture({
+          persistence: this.media,
+          threadId: this.threadId,
+          options,
+          publish: (record) => {
+            captured.push(record)
+            operation.publish(customEvent(HARNESS_EVENTS.media, { ...record }))
+          },
+          onError: (error) =>
+            this.warn(
+              operation,
+              'harness:media',
+              `The media was not kept. ${String(error)}`,
+            ),
+        }),
       ],
       chatMiddleware: [
         ...(this.sessionPlugins?.agentMiddleware ?? []),
         ...(runPlugins?.agentMiddleware ?? []),
+        // Last, because a later middleware that returns `messages` resets
+        // what the model gets. A child's adapter is not known here, so only
+        // `media.accepts` narrows what it reads.
+        mediaMiddleware({
+          store: this.mediaStore,
+          accepted: options?.accepts,
+          transcribe: options?.transcribe,
+        }),
       ],
     } satisfies SubagentBinding
   }
 
+  /**
+   * The user message of a turn. It keeps the records of its media files in
+   * `metadata.harness.media`, so a UI can show their names and sizes later.
+   * An id this thread does not know is skipped.
+   */
+  private async userMessage(content: UserInput) {
+    const ids =
+      typeof content === 'string'
+        ? []
+        : content.map(mediaIdOf).filter((id) => id !== undefined)
+    const records = await Promise.all(ids.map((id) => this.getMedia(id)))
+    const media = records.filter((record) => record !== null)
+    const message: ModelMessage = {
+      id: createMessageId(),
+      role: 'user',
+      content,
+      ...(media.length > 0 ? { metadata: { harness: { media } } } : {}),
+    }
+    return message
+  }
+
+  /** Add the media a turn made to the last assistant message of the thread. */
+  private async saveTurnMedia(media: Array<MediaRecord>) {
+    const store = this.persistence.stores.messages
+    const history = await store.loadThread(this.threadId)
+    const index = history.findLastIndex(
+      (message) => message.role === 'assistant',
+    )
+    const last = history[index]
+    if (!last) return
+    const harness = {
+      ...last.metadata?.harness,
+      media: [...mediaOfMessage(last), ...media],
+    }
+    const updated: ModelMessage = {
+      ...last,
+      metadata: { ...last.metadata, harness },
+    }
+    await store.saveThread(this.threadId, history.with(index, updated))
+  }
+
   private async runTurn(turn: QueuedTurn): Promise<void> {
     const { operation } = turn
     operation.setStatus('running')
@@ -1090,6 +1243,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     let text = ''
     let interrupts: Array<Interrupt> | undefined
     let failure: string | undefined
+    const captured: Array<MediaRecord> = []
     try {
       await this.flushNotes()
       const perRun = this.plugins.filter((plugin) => plugin.lifetime === 'run')
@@ -1151,12 +1305,14 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         [...staticTools, ...discovered],
         operation,
       )
+      const adapter: AnyTextAdapter = picked ?? this.harness.adapter
+      const message =
+        turn.message !== undefined
+          ? await this.userMessage(turn.message)
+          : undefined
       const stream = chat({
-        adapter: picked ?? this.harness.adapter,
-        messages:
-          turn.message !== undefined
-            ? [{ id: createMessageId(), role: 'user', content: turn.message }]
-            : [],
+        adapter,
+        messages: message ? [message] : [],
         systemPrompts: [
           ...(this.harness.systemPrompts ?? []),
           ...[...(session?.prompts ?? []), ...(runPlugins?.prompts ?? [])]
@@ -1172,6 +1328,16 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           ...(session?.middleware ?? []),
           ...(runPlugins?.middleware ?? []),
           this.steering(),
+          // Last, because a later middleware that returns `messages` (as
+          // steering does) resets what the model gets.
+          mediaMiddleware({
+            store: this.mediaStore,
+            accepted: acceptedKinds(
+              adapter.inputModalities,
+              this.harness.media?.accepts,
+            ),
+            transcribe: this.harness.media?.transcribe,
+          }),
         ],
         ...(subagentList.length > 0
           ? {
@@ -1179,7 +1345,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
                 ...this.harness.subagents,
                 agents: subagentList,
                 limits: this.limits(),
-                binding: this.binding(runPlugins),
+                binding: this.binding(operation, captured, runPlugins),
               },
             }
           : {}),
@@ -1232,6 +1398,21 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       await runPlugins?.dispose().catch(() => {})
     }
 
+    // The stream has ended, so withPersistence has saved the turn. A failed or
+    // cancelled turn may not have saved its answer, and its last assistant
+    // message can be an older turn's, so its media stays in the store only.
+    const isSaved =
+      failure === undefined && !operation.abortController.signal.aborted
+    if (isSaved && captured.length > 0) {
+      await this.saveTurnMedia(captured).catch((error: unknown) =>
+        this.warn(
+          operation,
+          'harness:media',
+          `The media was not added to the transcript. ${String(error)}`,
+        ),
+      )
+    }
+
     if (operation.abortController.signal.aborted) {
       operation.fail('cancelled', new Error('Cancelled.'))
     } else if (failure !== undefined) {
@@ -1398,7 +1579,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         },
         undefined,
         undefined,
-        { ...this.binding(), budget: this.codeBudget() },
+        // ponytail: the media of a background agent is kept and published,
+        // but not written to history: its messages live in its own thread
+        // (`<threadId>:<name>`). Write it to the session thread if a UI must
+        // show it after a restart.
+        { ...this.binding(operation, []), budget: this.codeBudget() },
       )
       for await (const chunk of stream) {
         operation.publish(chunk)
diff --git a/packages/ai-harness/src/view/reduce.ts b/packages/ai-harness/src/view/reduce.ts
index f16d167e0d..e7f00225a8 100644
--- a/packages/ai-harness/src/view/reduce.ts
+++ b/packages/ai-harness/src/view/reduce.ts
@@ -1,5 +1,5 @@
 import { EventType } from '@tanstack/ai'
-import { mediaIdOf, mediaOfMessage } from '../media-ref'
+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'
@@ -112,42 +112,27 @@ function mediaView(media: MediaInfo) {
   return part
 }
 
-/** The fields a media part needs from a `harness.media` event value. */
-function mediaInfoOf(value: Record<string, unknown>) {
-  const { id, kind, mimeType, name, size } = value
-  const isKind =
-    kind === 'image' ||
-    kind === 'audio' ||
-    kind === 'video' ||
-    kind === 'document'
-  const isInfo =
-    isKind &&
-    typeof id === 'string' &&
-    typeof mimeType === 'string' &&
-    typeof name === 'string' &&
-    typeof size === 'number'
-  if (!isInfo) return undefined
-  const info: MediaInfo = { id, kind, mimeType, name, size }
-  return info
-}
-
-/** Media parts for the `harness-media:` parts of a saved user message. */
-function userMedia(content: ModelMessage['content']) {
+/**
+ * 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 []
-    // ponytail: a saved part keeps only its id and MIME type, so the name is
-    // the id and the size is 0. Save the record on the message if a UI needs them.
-    return [
-      mediaView({
-        id,
-        kind: part.type,
-        mimeType: part.source.mimeType ?? '',
-        name: id,
-        size: 0,
-      }),
-    ]
+    // 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)]
   })
 }
 
@@ -457,13 +442,10 @@ export function applyEvent(
   }
   if (event.type !== EventType.CUSTOM) return state
   const value = recordOf(event.value)
-  if (event.name === HARNESS_EVENTS.media) {
-    const media = mediaInfoOf(value)
-    if (!media) return state
-    const child =
-      typeof value.subagentRunId === 'string' ? value.subagentRunId : undefined
-    return withMedia(state, operationId, media, child)
-  }
+  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.')
   if (event.name === COMMAND_RESULT)
@@ -643,7 +625,7 @@ export function messagesFromTranscript(
   messages.forEach((message, index) => {
     const id = message.id ?? `history-${index}`
     if (message.role === 'user') {
-      const media = userMedia(message.content)
+      const media = userMedia(message)
       result.push({
         id,
         role: 'user',
diff --git a/packages/ai-harness/tests/session-media.test.ts b/packages/ai-harness/tests/session-media.test.ts
new file mode 100644
index 0000000000..ab20f23c3a
--- /dev/null
+++ b/packages/ai-harness/tests/session-media.test.ts
@@ -0,0 +1,450 @@
+import { describe, expect, it, vi } from 'vitest'
+import { EventType, defineAgent } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  HARNESS_EVENTS,
+  MediaError,
+  createHarnessHost,
+  defineHarness,
+  mediaPart,
+} from '../src'
+import { messagesFromTranscript } from '../src/view/reduce'
+import { mockAdapter, text, toolCall } from './helpers'
+import type {
+  AnyTextAdapter,
+  ImageAdapter,
+  Modality,
+  TranscriptionAdapter,
+} from '@tanstack/ai'
+import type {
+  AnyHarness,
+  HarnessPersistence,
+  MediaKind,
+  MediaOptions,
+  MediaRecord,
+  SessionEvent,
+  UserInput,
+} from '../src'
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+// ponytail: the image and transcription fakes repeat the ones in
+// media.test.ts. Move both to helpers.ts when a third file needs them.
+function imageAdapter(): ImageAdapter<string> {
+  return {
+    kind: 'image',
+    name: 'fake-image',
+    model: 'fake-image-model',
+    '~types': {
+      providerOptions: {},
+      modelProviderOptionsByName: {},
+      modelSizeByName: {},
+      modelInputModalitiesByName: {},
+    },
+    // 'aGVsbG8=' is base64 for "hello".
+    generateImages: async () => ({
+      id: 'image-1',
+      model: 'fake-image-model',
+      images: [{ b64Json: 'aGVsbG8=' }],
+    }),
+  }
+}
+
+/** A transcription adapter that answers with the text of the audio bytes. */
+function transcriptionAdapter(): TranscriptionAdapter<string> {
+  return {
+    kind: 'transcription',
+    name: 'fake-stt',
+    model: 'fake-stt-model',
+    '~types': { providerOptions: {} },
+    transcribe: async ({ audio }) => ({
+      id: 'transcript-1',
+      model: 'fake-stt-model',
+      text: audio instanceof Blob ? await audio.text() : 'not a blob',
+    }),
+  }
+}
+
+/** A text adapter that answers "ok" and reads the `inputs` kinds at runtime. */
+function reader(inputs?: ReadonlyArray<Modality>) {
+  const { adapter, calls } = mockAdapter(() => text('ok'))
+  const withInputs: AnyTextAdapter = { ...adapter, inputModalities: inputs }
+  return { adapter: withInputs, calls }
+}
+
+/** An agent that makes one image through `ctx.generateImage`. */
+const painter = defineAgent({
+  name: 'painter',
+  description: 'Paints',
+  run: async (ctx) => {
+    await ctx.generateImage({ adapter: imageAdapter(), prompt: 'a cat' })
+    return 'painted'
+  },
+})
+
+function harnessWith(adapter: AnyTextAdapter, media?: MediaOptions) {
+  return defineHarness({ name: 'test/media', adapter, media })
+}
+
+async function open<THarness extends AnyHarness>(
+  harness: THarness,
+  persistence: HarnessPersistence = memoryPersistence(),
+) {
+  const host = createHarnessHost({ persistence })
+  const session = await host.open(harness, { threadId: 't1' })
+  return { host, session }
+}
+
+/** A prompt that sends `record` with a question. */
+function askAbout(record: MediaRecord) {
+  const input: UserInput = [
+    { type: 'text', content: 'What is this?' },
+    mediaPart(record),
+  ]
+  return input
+}
+
+/** A stored user image with the bytes "hello". */
+function storedImage(record: Partial<MediaRecord> = {}) {
+  return {
+    id: expect.any(String),
+    threadId: 't1',
+    kind: 'image',
+    mimeType: 'image/png',
+    name: 'cat.png',
+    size: 5,
+    source: 'user',
+    createdAt: expect.any(Number),
+    ...record,
+  }
+}
+
+async function collect(iterable: AsyncIterable<SessionEvent>) {
+  const out: Array<SessionEvent> = []
+  for await (const entry of iterable) out.push(entry)
+  return out
+}
+
+/** The values of the `CUSTOM` events named `name`. */
+function customValues(events: Array<SessionEvent>, name: string) {
+  return events.flatMap(({ event }) =>
+    event.type === EventType.CUSTOM && event.name === name ? [event.value] : [],
+  )
+}
+
+/** The id of the one child run in `events`. */
+function childRunId(events: Array<SessionEvent>) {
+  const ids = events.flatMap(({ event }) =>
+    event.type === EventType.SUBAGENT_STARTED ? [event.subagentRunId] : [],
+  )
+  const [id] = ids
+  if (ids.length !== 1 || id === undefined)
+    throw new Error(`Expected one child run, got ${ids.length}`)
+  return id
+}
+
+describe('session media store', () => {
+  it('stores a file and reads it back', async () => {
+    const { host, session } = await open(harnessWith(mockAdapter([]).adapter))
+
+    const record = await session.putMedia(encoder.encode('hello'), {
+      mimeType: 'image/png',
+      name: 'cat.png',
+    })
+
+    expect(record).toEqual(storedImage())
+    expect(await session.getMedia(record.id)).toEqual(record)
+    expect(decoder.decode(await session.loadMedia(record.id))).toBe('hello')
+    await host.close()
+  })
+
+  it('keeps media in memory when the host has no media stores', async () => {
+    const { messages } = memoryPersistence().stores
+    const { host, session } = await open(harnessWith(mockAdapter([]).adapter), {
+      stores: { messages },
+    })
+
+    const record = await session.putMedia(encoder.encode('hello'), {
+      mimeType: 'image/png',
+      name: 'cat.png',
+    })
+
+    expect(decoder.decode(await session.loadMedia(record.id))).toBe('hello')
+    await host.close()
+  })
+
+  it('refuses a file over media.maxBytes with a 413 MediaError', async () => {
+    const { host, session } = await open(
+      harnessWith(mockAdapter([]).adapter, { maxBytes: 4 }),
+    )
+
+    const put = session.putMedia(encoder.encode('hello'), {
+      mimeType: 'image/png',
+      name: 'cat.png',
+    })
+
+    await expect(put).rejects.toBeInstanceOf(MediaError)
+    await expect(put).rejects.toMatchObject({ status: 413 })
+    await host.close()
+  })
+
+  it('does not show the media of another thread', async () => {
+    const harness = harnessWith(mockAdapter([]).adapter)
+    const { host, session } = await open(harness)
+    const other = await host.open(harness, { threadId: 't2' })
+
+    const record = await session.putMedia(encoder.encode('secret'), {
+      mimeType: 'image/png',
+      name: 'a.png',
+    })
+
+    expect(await other.getMedia(record.id)).toBeNull()
+    await host.close()
+  })
+
+  it('gives a data URL for a small file, and none for an unknown id', async () => {
+    const { host, session } = await open(harnessWith(mockAdapter([]).adapter))
+    const record = await session.putMedia(encoder.encode('hello'), {
+      mimeType: 'image/png',
+      name: 'cat.png',
+    })
+
+    expect(await session.mediaUrl(record.id)).toEqual({
+      url: 'data:image/png;base64,aGVsbG8=',
+    })
+    expect(await session.mediaUrl('nope')).toStrictEqual({})
+    await host.close()
+  })
+})
+
+describe('media sent to a turn', () => {
+  /** Send a stored image to a turn of a model with no input list. */
+  async function sendImage() {
+    const { adapter, calls } = reader()
+    const { host, session } = await open(harnessWith(adapter))
+    const record = await session.putMedia(encoder.encode('hello'), {
+      mimeType: 'image/png',
+      name: 'cat.png',
+    })
+    await session.prompt(askAbout(record))
+    return { host, session, record, calls }
+  }
+
+  it('sends the bytes when nothing limits the kinds, and saves the harness-media URL', async () => {
+    const { host, session, record, calls } = await sendImage()
+
+    expect(calls[0].messages[0].content).toEqual([
+      { type: 'text', content: 'What is this?' },
+      {
+        type: 'image',
+        source: { type: 'data', value: 'aGVsbG8=', mimeType: 'image/png' },
+      },
+    ])
+    const [saved] = await session.transcript()
+    expect(saved).toMatchObject({
+      role: 'user',
+      content: [
+        { type: 'text', content: 'What is this?' },
+        {
+          type: 'image',
+          source: {
+            type: 'url',
+            value: `harness-media:${record.id}`,
+            mimeType: 'image/png',
+          },
+        },
+      ],
+      metadata: { harness: { media: [record] } },
+    })
+    await host.close()
+  })
+
+  it('gives the view the name and size of a file from the saved user message', async () => {
+    const { host, session, record } = await sendImage()
+
+    const [user] = messagesFromTranscript(await session.transcript())
+
+    expect(user).toMatchObject({
+      role: 'user',
+      text: 'What is this?',
+      media: [
+        {
+          type: 'media',
+          id: record.id,
+          kind: 'image',
+          mimeType: 'image/png',
+          name: 'cat.png',
+          size: 5,
+        },
+      ],
+    })
+    await host.close()
+  })
+
+  const refusals: Array<{
+    label: string
+    inputs?: ReadonlyArray<Modality>
+    accepts?: ReadonlyArray<MediaKind>
+    mimeType: string
+    message: string
+  }> = [
+    {
+      label: 'an adapter that reads only text refuses an image',
+      inputs: ['text'],
+      mimeType: 'image/png',
+      message:
+        'test-model cannot read image files. Use a model that reads image files, or send a text summary.',
+    },
+    {
+      label: 'media.accepts refuses audio when the adapter has no list',
+      accepts: ['image'],
+      mimeType: 'audio/mpeg',
+      message:
+        'test-model cannot read audio files. Add media.transcribe, or send a text summary.',
+    },
+    {
+      label: 'media.accepts narrows the adapter list',
+      inputs: ['text', 'image'],
+      accepts: ['audio'],
+      mimeType: 'image/png',
+      message:
+        'test-model cannot read image files. Use a model that reads image files, or send a text summary.',
+    },
+    {
+      label: 'the adapter list narrows media.accepts',
+      inputs: ['text', 'image'],
+      accepts: ['audio'],
+      mimeType: 'audio/mpeg',
+      message:
+        'test-model cannot read audio files. Add media.transcribe, or send a text summary.',
+    },
+  ]
+
+  it.each(refusals)(
+    '$label before the model call',
+    async ({ inputs, accepts, mimeType, message }) => {
+      const { adapter, calls } = reader(inputs)
+      const { host, session } = await open(harnessWith(adapter, { accepts }))
+      const record = await session.putMedia(encoder.encode('hello'), {
+        mimeType,
+        name: 'file',
+      })
+
+      await expect(session.prompt(askAbout(record))).rejects.toThrow(message)
+      expect(calls).toHaveLength(0)
+      await host.close()
+    },
+  )
+
+  it('turns audio into a transcript with media.transcribe', async () => {
+    const { adapter, calls } = reader(['text'])
+    const { host, session } = await open(
+      harnessWith(adapter, { transcribe: transcriptionAdapter() }),
+    )
+    const record = await session.putMedia(encoder.encode('meow meow'), {
+      mimeType: 'audio/mpeg',
+      name: 'voice.mp3',
+    })
+
+    await session.prompt(askAbout(record))
+
+    expect(calls[0].messages[0].content).toEqual([
+      { type: 'text', content: 'What is this?' },
+      { type: 'text', content: '[audio transcript: voice.mp3] meow meow' },
+    ])
+    await host.close()
+  })
+})
+
+describe('media an agent makes', () => {
+  /** A generated image with the bytes "hello". */
+  function generatedImage(runId: string, subagentRunId: string) {
+    return {
+      id: expect.any(String),
+      threadId: 't1',
+      kind: 'image',
+      mimeType: 'image/png',
+      name: expect.any(String),
+      size: 5,
+      source: 'generated',
+      createdAt: expect.any(Number),
+      runId,
+      subagentRunId,
+    }
+  }
+
+  it('publishes the media of a subagent and saves it on the last assistant message', async () => {
+    const lead = mockAdapter([
+      () => toolCall('painter', {}),
+      () => text('Here is your cat.'),
+    ])
+    const { host, session } = await open(
+      defineHarness({
+        name: 'test/media',
+        adapter: lead.adapter,
+        subagents: { agents: [painter] },
+      }),
+    )
+
+    const turn = session.prompt('Paint a cat')
+    await turn
+    const events = await collect(turn.events({ from: '0' }))
+
+    const media = customValues(events, HARNESS_EVENTS.media)
+    expect(media).toEqual([generatedImage(turn.id, childRunId(events))])
+    expect((await session.transcript()).at(-1)).toMatchObject({
+      role: 'assistant',
+      content: 'Here is your cat.',
+      metadata: { harness: { media } },
+    })
+    await host.close()
+  })
+
+  it('publishes the media of a background agent', async () => {
+    const { host, session } = await open(
+      defineHarness({
+        name: 'test/media',
+        adapter: mockAdapter([]).adapter,
+        agents: [painter],
+      }),
+    )
+
+    const run = session.agents.painter.run()
+    await expect(run).resolves.toBe('painted')
+    const events = await collect(run.events({ from: '0' }))
+
+    expect(customValues(events, HARNESS_EVENTS.media)).toEqual([
+      generatedImage(run.id, childRunId(events)),
+    ])
+    await host.close()
+  })
+
+  it('warns and keeps the agent result when the media store fails', async () => {
+    const persistence = memoryPersistence()
+    vi.spyOn(persistence.stores.blobs, 'put').mockRejectedValue(
+      new Error('disk full'),
+    )
+    const { host, session } = await open(
+      defineHarness({
+        name: 'test/media',
+        adapter: mockAdapter([]).adapter,
+        agents: [painter],
+      }),
+      persistence,
+    )
+
+    const run = session.agents.painter.run()
+    await expect(run).resolves.toBe('painted')
+    const events = await collect(run.events({ from: '0' }))
+
+    expect(customValues(events, 'harness.plugin.warning')).toEqual([
+      {
+        plugin: 'harness:media',
+        message: 'The media was not kept. Error: disk full',
+      },
+    ])
+    expect(customValues(events, HARNESS_EVENTS.media)).toEqual([])
+    await host.close()
+  })
+})
diff --git a/scripts/model-sync/native-insert.test.ts b/scripts/model-sync/native-insert.test.ts
index 2be7ece3ac..8d0b8c1a11 100644
--- a/scripts/model-sync/native-insert.test.ts
+++ b/scripts/model-sync/native-insert.test.ts
@@ -23,6 +23,12 @@ export type AnthropicModelInputModalitiesByName = {
   [FOO.id]: typeof FOO.supports.input
 }
 
+export const ANTHROPIC_MODEL_INPUT_MODALITIES: Readonly<
+  Record<string, ReadonlyArray<Modality>>
+> = {
+  [FOO.id]: FOO.supports.input,
+} satisfies AnthropicModelInputModalitiesByName
+
 const ANTHROPIC_MODEL_MAX_OUTPUT_TOKENS: Record<string, number> = {
   [FOO.id]: FOO.max_output_tokens,
 }
@@ -38,15 +44,50 @@ const ANTHROPIC_CONFIG = {
   providerOptionsIsMappedType: false,
 }
 
+const FABLE_5_1 = {
+  constName: 'CLAUDE_FABLE_5_1',
+  providerOptionsEntry:
+    'AnthropicAdaptiveOnlyThinkingOptions & AnthropicMaxTokensOptions',
+  hasMaxOutputTokens: true,
+}
+
+/** An OpenAI file from before the runtime input-modalities map. */
+const OPENAI_STUB = `export const OPENAI_CHAT_MODELS = [
+  GPT5.name,
+] as const
+
+export type OpenAIChatModelProviderOptionsByName = {
+  [GPT5.name]: OpenAIBaseOptions
+}
+
+export type OpenAIChatModelToolCapabilitiesByName = {
+  [GPT5.name]: typeof GPT5.supports.tools
+}
+
+export type OpenAIModelInputModalitiesByName = {
+  [GPT5.name]: typeof GPT5.supports.input
+}
+`
+
+const OPENAI_CONFIG = {
+  chatArrayName: 'OPENAI_CHAT_MODELS',
+  arrayRef: '.name' as const,
+  providerOptionsTypeName: 'OpenAIChatModelProviderOptionsByName',
+  inputModalitiesTypeName: 'OpenAIModelInputModalitiesByName',
+  toolCapabilitiesTypeName: 'OpenAIChatModelToolCapabilitiesByName',
+  providerOptionsIsMappedType: false,
+}
+
+const GPT6 = {
+  constName: 'GPT6',
+  providerOptionsEntry: 'OpenAIBaseOptions',
+  hasMaxOutputTokens: false,
+}
+
 describe('applyChatModelCatalogInserts', () => {
   it('writes the tool-capabilities row for a new Anthropic model', () => {
     const result = applyChatModelCatalogInserts(STUB, ANTHROPIC_CONFIG, [
-      {
-        constName: 'CLAUDE_FABLE_5_1',
-        providerOptionsEntry:
-          'AnthropicAdaptiveOnlyThinkingOptions & AnthropicMaxTokensOptions',
-        hasMaxOutputTokens: true,
-      },
+      FABLE_5_1,
     ])
 
     expect(result).toContain('CLAUDE_FABLE_5_1.id,')
@@ -65,42 +106,39 @@ describe('applyChatModelCatalogInserts', () => {
   })
 
   it('writes the tool-capabilities row for OpenAI and Gemini (.name refs)', () => {
-    const openaiStub = `export const OPENAI_CHAT_MODELS = [
-  GPT5.name,
-] as const
+    const result = applyChatModelCatalogInserts(OPENAI_STUB, OPENAI_CONFIG, [
+      GPT6,
+    ])
 
-export type OpenAIChatModelProviderOptionsByName = {
-  [GPT5.name]: OpenAIBaseOptions
-}
+    expect(result).toContain('[GPT6.name]: typeof GPT6.supports.tools')
+    expect(result).toContain('GPT6.name,')
+  })
 
-export type OpenAIChatModelToolCapabilitiesByName = {
-  [GPT5.name]: typeof GPT5.supports.tools
-}
+  it('writes the input-modalities row into the type map and the runtime map', () => {
+    const result = applyChatModelCatalogInserts(STUB, ANTHROPIC_CONFIG, [
+      FABLE_5_1,
+    ])
 
-export type OpenAIModelInputModalitiesByName = {
-  [GPT5.name]: typeof GPT5.supports.input
-}
-`
-    const result = applyChatModelCatalogInserts(
-      openaiStub,
-      {
-        chatArrayName: 'OPENAI_CHAT_MODELS',
-        arrayRef: '.name',
-        providerOptionsTypeName: 'OpenAIChatModelProviderOptionsByName',
-        inputModalitiesTypeName: 'OpenAIModelInputModalitiesByName',
-        toolCapabilitiesTypeName: 'OpenAIChatModelToolCapabilitiesByName',
-        providerOptionsIsMappedType: false,
-      },
-      [
-        {
-          constName: 'GPT6',
-          providerOptionsEntry: 'OpenAIBaseOptions',
-          hasMaxOutputTokens: false,
-        },
-      ],
-    )
+    expect(result)
+      .toContain(`export type AnthropicModelInputModalitiesByName = {
+  [FOO.id]: typeof FOO.supports.input
+  [CLAUDE_FABLE_5_1.id]: typeof CLAUDE_FABLE_5_1.supports.input
+}`)
+    expect(result).toContain(`> = {
+  [FOO.id]: FOO.supports.input,
+  [CLAUDE_FABLE_5_1.id]: CLAUDE_FABLE_5_1.supports.input,
+} satisfies AnthropicModelInputModalitiesByName`)
+  })
 
-    expect(result).toContain('[GPT6.name]: typeof GPT6.supports.tools')
-    expect(result).toContain('GPT6.name,')
+  it('leaves a file without the runtime input-modalities map as it is', () => {
+    const result = applyChatModelCatalogInserts(OPENAI_STUB, OPENAI_CONFIG, [
+      GPT6,
+    ])
+
+    expect(result).toContain(`export type OpenAIModelInputModalitiesByName = {
+  [GPT5.name]: typeof GPT5.supports.input
+  [GPT6.name]: typeof GPT6.supports.input
+}`)
+    expect(result).not.toContain('GPT6.supports.input,')
   })
 })
diff --git a/scripts/model-sync/native-insert.ts b/scripts/model-sync/native-insert.ts
index fd966bdd5d..67b4811544 100644
--- a/scripts/model-sync/native-insert.ts
+++ b/scripts/model-sync/native-insert.ts
@@ -7,10 +7,7 @@
 
 type ArrayRef = '.name' | '.id'
 
-export function insertConstants(
-  content: string,
-  constants: Array<string>,
-): string {
+export function insertConstants(content: string, constants: Array<string>) {
   const block = '\n' + constants.join('\n\n') + '\n'
   const exportIndex = content.indexOf('\nexport ')
   if (exportIndex === -1) {
@@ -29,7 +26,7 @@ function addToArray(
   arrayName: string,
   entries: Array<string>,
   arrayRef: string,
-): string {
+) {
   const open = `export const ${arrayName} = [`
   const openIndex = content.indexOf(open)
   if (openIndex === -1) {
@@ -48,7 +45,7 @@ function addToTypeMap(
   content: string,
   typeName: string,
   entries: Array<string>,
-): string {
+) {
   const pattern = new RegExp(
     `(export type ${typeName} = \\{[\\s\\S]*?)(\\n\\})`,
   )
@@ -66,7 +63,7 @@ function addToObjectMap(
   content: string,
   mapName: string,
   entries: Array<string>,
-): string {
+) {
   const pattern = new RegExp(
     `(const ${mapName}: Record<string, number> = \\{[\\s\\S]*?)(\\n\\})`,
   )
@@ -80,6 +77,20 @@ function addToObjectMap(
   return content.replace(pattern, () => `${match[1]}\n${newEntries}${match[2]}`)
 }
 
+/**
+ * Append entries to the runtime map that ends with `} satisfies <typeName>`.
+ * A file without that map is left as it is.
+ */
+function addToSatisfyingMap(
+  content: string,
+  typeName: string,
+  entries: Array<string>,
+) {
+  // ponytail: found by its `satisfies` tail, so the sync config needs no map name.
+  const pattern = new RegExp(`\\n\\} satisfies ${typeName}\\b`)
+  return content.replace(pattern, (close) => `\n${entries.join('\n')}${close}`)
+}
+
 interface ChatModelInsert {
   constName: string
   providerOptionsEntry: string
@@ -98,14 +109,15 @@ interface ChatModelCatalogInsertConfig {
 
 /**
  * Write a new chat model into the catalog tables the adapter types read:
- * the exported id array, provider-options map, input-modalities map,
- * tool-capabilities map, and (Anthropic) max-output-tokens object.
+ * the exported id array, provider-options map, input-modalities type map and
+ * its runtime map (when the file has one), tool-capabilities map, and
+ * (Anthropic) max-output-tokens object.
  */
 export function applyChatModelCatalogInserts(
   content: string,
   config: ChatModelCatalogInsertConfig,
   chatModels: Array<ChatModelInsert>,
-): string {
+) {
   if (chatModels.length === 0) return content
 
   let next = addToArray(
@@ -134,6 +146,14 @@ export function applyChatModelCatalogInserts(
         `  [${constName}${config.arrayRef}]: typeof ${constName}.supports.input`,
     ),
   )
+  next = addToSatisfyingMap(
+    next,
+    config.inputModalitiesTypeName,
+    chatModels.map(
+      ({ constName }) =>
+        `  [${constName}${config.arrayRef}]: ${constName}.supports.input,`,
+    ),
+  )
 
   if (config.toolCapabilitiesTypeName) {
     next = addToTypeMap(

From 9f68d1e4f803f5d0e814747e9d5b6cc4107a2f84 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 29 Sep 2026 12:16:30 +0200
Subject: [PATCH 060/286] feat(ai-harness, ai-acp): HTTP media routes with
 signed URLs, media through /run and harnessText, and ACP media blocks

createHarnessHandler serves uploads (POST media), signed URLs (GET media-url), and file bytes with Range support (GET media). A signed URL works in <img>, <audio>, and <video> without auth headers. POST run and harnessText keep the content parts of the user message. The ACP agent stores image, audio, and resource blocks and advertises prompt capabilities.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-acp/src/agent/index.ts            | 127 +++++-
 packages/ai-acp/tests/agent-handlers.test.ts  |  12 +-
 packages/ai-acp/tests/agent-media.test.ts     | 267 ++++++++++++
 packages/ai-harness/src/harness-text.ts       | 113 ++---
 packages/ai-harness/src/http.ts               | 236 +++++++++--
 packages/ai-harness/src/oauth.ts              |   3 +-
 packages/ai-harness/src/session.ts            |  12 +-
 .../ai-harness/tests/client-media.test.ts     |  11 +
 .../tests/harness-text-media.test.ts          | 131 ++++++
 packages/ai-harness/tests/http-media.test.ts  | 386 ++++++++++++++++++
 .../ai-harness/tests/resume-edges.test.ts     |  29 +-
 11 files changed, 1207 insertions(+), 120 deletions(-)
 create mode 100644 packages/ai-acp/tests/agent-media.test.ts
 create mode 100644 packages/ai-harness/tests/harness-text-media.test.ts
 create mode 100644 packages/ai-harness/tests/http-media.test.ts

diff --git a/packages/ai-acp/src/agent/index.ts b/packages/ai-acp/src/agent/index.ts
index c36cb9ac8e..7c85e04af1 100644
--- a/packages/ai-acp/src/agent/index.ts
+++ b/packages/ai-acp/src/agent/index.ts
@@ -1,9 +1,12 @@
 import { EventType } from '@tanstack/ai'
 import {
+  ContentBlock,
   PROTOCOL_VERSION,
+  RequestError,
   agent,
   ndJsonStream,
 } from '@agentclientprotocol/sdk/experimental/v2'
+import { MediaError, kindOf, mediaPart } from '@tanstack/ai-harness'
 import type {
   AgentApp,
   AgentContext,
@@ -11,7 +14,12 @@ import type {
   SessionUpdate,
   Stream,
 } from '@agentclientprotocol/sdk/experimental/v2'
-import type { Interrupt, RunAgentResumeItem, StreamChunk } from '@tanstack/ai'
+import type {
+  ContentPart,
+  Interrupt,
+  RunAgentResumeItem,
+  StreamChunk,
+} from '@tanstack/ai'
 import type {
   AnyHarness,
   HarnessHost,
@@ -26,16 +34,89 @@ export interface AcpAgentOptions {
   version?: string
 }
 
-/** The text of an ACP prompt. Non-text blocks are skipped. */
-function promptText(
-  prompt: ReadonlyArray<{ type: string; text?: unknown }>,
-): string {
-  return prompt
-    .map((block) =>
-      block.type === 'text' && typeof block.text === 'string' ? block.text : '',
-    )
-    .filter((text) => text !== '')
-    .join('\n')
+function textPart(content: string) {
+  const part: ContentPart = { type: 'text', content }
+  return part
+}
+
+/** A text line that names a resource the prompt does not include. */
+function linkPart(uri: string) {
+  return textPart(`[resource link: ${uri}]`)
+}
+
+/** The last path segment of a URI, as a file name. */
+function fileName(uri: string) {
+  return uri.split('/').pop() || uri
+}
+
+/**
+ * Store the base64 `data` of a block in the media store of the session, and
+ * return the part that sends it. Throws a `MediaError` when the harness
+ * refuses the file.
+ */
+async function storedPart(
+  session: HarnessSession,
+  data: string,
+  info: { mimeType: string; name: string },
+) {
+  const bytes = Uint8Array.from(atob(data), (char) => char.charCodeAt(0))
+  return mediaPart(await session.putMedia(bytes, info))
+}
+
+/** One ACP prompt block as a content part, or `undefined` to skip it. */
+async function promptPart(session: HarnessSession, block: ContentBlock) {
+  // The SDK guards check the payload too, so a malformed block is skipped.
+  if (ContentBlock.isText(block)) {
+    return block.text === '' ? undefined : textPart(block.text)
+  }
+  if (ContentBlock.isImage(block)) {
+    return storedPart(session, block.data, {
+      mimeType: block.mimeType,
+      name: block.uri ? fileName(block.uri) : 'image',
+    })
+  }
+  if (ContentBlock.isAudio(block)) {
+    return storedPart(session, block.data, {
+      mimeType: block.mimeType,
+      name: 'audio',
+    })
+  }
+  // ponytail: a resource link is only named. The agent does not read it; the
+  // model can open it with its own tools.
+  if (ContentBlock.isResourceLink(block)) return linkPart(block.uri)
+  if (!ContentBlock.isResource(block)) return undefined
+  const { resource } = block
+  if ('text' in resource) {
+    return textPart(`[resource: ${resource.uri}]\n${resource.text}`)
+  }
+  const { mimeType } = resource
+  const isStored =
+    typeof mimeType === 'string' && kindOf(mimeType) !== undefined
+  if (!isStored) return linkPart(resource.uri)
+  return storedPart(session, resource.blob, {
+    mimeType,
+    name: fileName(resource.uri),
+  })
+}
+
+/**
+ * The turn input of an ACP prompt. Image and audio blocks, and embedded blobs
+ * of a type the harness stores, go to the media store of the session and
+ * become media parts. Embedded text and resource links become text. A prompt
+ * of only text is one string, as before.
+ */
+async function promptInput(
+  session: HarnessSession,
+  prompt: ReadonlyArray<ContentBlock>,
+) {
+  const blocks = await Promise.all(
+    prompt.map((block) => promptPart(session, block)),
+  )
+  const parts = blocks.filter((part) => part !== undefined)
+  const texts = parts.flatMap((part) =>
+    part.type === 'text' ? [part.content] : [],
+  )
+  return texts.length === parts.length ? texts.join('\n') : parts
 }
 
 /** One AG-UI chunk as an ACP session update, or `undefined` to skip it. */
@@ -87,6 +168,9 @@ const APPROVAL_OPTIONS = [
  * An ACP v2 agent backed by a harness. Each ACP session is one harness
  * session. Prompts follow the harness `busy` setting, tool approvals become
  * `session/request_permission` requests, and cancel cancels the running turn.
+ * Image, audio, and embedded resource blocks of a prompt go to the media
+ * store of the session. A file the harness refuses (too big, or a type it
+ * does not take) fails `session/prompt` with an invalid params error.
  *
  * ACP v2 is a draft, so this API is experimental too.
  */
@@ -197,7 +281,11 @@ export function createAcpAgent(options: AcpAgentOptions): AgentApp {
     .onRequest('initialize', () => ({
       protocolVersion: PROTOCOL_VERSION,
       info: { name: harness.name, version: options.version ?? '0.0.0' },
-      capabilities: {},
+      // Text and resource links are the baseline. Images, audio, and embedded
+      // resources go to the media store of the session.
+      capabilities: {
+        session: { prompt: { image: {}, audio: {}, embeddedContext: {} } },
+      },
     }))
     .onRequest('session/new', async () => {
       const sessionId = `acp-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`
@@ -210,7 +298,20 @@ export function createAcpAgent(options: AcpAgentOptions): AgentApp {
     })
     .onRequest('session/prompt', async ({ params, client }) => {
       const session = await sessionFor(params.sessionId)
-      const operation = session.prompt(promptText(params.prompt))
+      const input = await promptInput(session, params.prompt).catch(
+        (error: unknown) => {
+          // The editor sent a file the harness refuses, so the prompt is
+          // invalid: answer with the reason, not an internal error.
+          if (error instanceof MediaError) {
+            throw RequestError.invalidParams(
+              { status: error.status },
+              error.message,
+            )
+          }
+          throw error
+        },
+      )
+      const operation = session.prompt(input)
       void pump(client, params.sessionId, session, operation)
       return { messageId: operation.id }
     })
diff --git a/packages/ai-acp/tests/agent-handlers.test.ts b/packages/ai-acp/tests/agent-handlers.test.ts
index 817c5bc7b1..4bc4867714 100644
--- a/packages/ai-acp/tests/agent-handlers.test.ts
+++ b/packages/ai-acp/tests/agent-handlers.test.ts
@@ -4,7 +4,7 @@ import { client, ndJsonStream } from '@agentclientprotocol/sdk/experimental/v2'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
 import { createAcpAgent, serveAcp, toSessionUpdate } from '../src/agent'
-import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import type { AnyTextAdapter, ModelMessage, StreamChunk } from '@tanstack/ai'
 import type {
   ClientApp,
   SessionUpdate,
@@ -38,8 +38,14 @@ function model(): AnyTextAdapter {
     structuredOutput: async () => ({ data: {}, rawText: '{}' }),
     chatStream: (options: any) =>
       (async function* (): AsyncGenerator<StreamChunk> {
-        const last = options.messages.at(-1)
-        const said = typeof last?.content === 'string' ? last.content : ''
+        const last: ModelMessage | undefined = options.messages.at(-1)
+        // A prompt with an image comes as parts: read its text parts.
+        const said =
+          typeof last?.content === 'string'
+            ? last.content
+            : (last?.content ?? [])
+                .map((part) => (part.type === 'text' ? part.content : ''))
+                .join('')
         yield {
           type: EventType.RUN_STARTED,
           runId: 'r',
diff --git a/packages/ai-acp/tests/agent-media.test.ts b/packages/ai-acp/tests/agent-media.test.ts
new file mode 100644
index 0000000000..5dbee7a619
--- /dev/null
+++ b/packages/ai-acp/tests/agent-media.test.ts
@@ -0,0 +1,267 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { EventType } from '@tanstack/ai'
+import { client } from '@agentclientprotocol/sdk/experimental/v2'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  createHarnessHost,
+  defineHarness,
+  mediaOfMessage,
+} from '@tanstack/ai-harness'
+import { createAcpAgent } from '../src/agent'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import type {
+  ClientContext,
+  ContentBlock,
+  InitializeResponse,
+} from '@agentclientprotocol/sdk/experimental/v2'
+import type { MediaOptions, MediaRecord } from '@tanstack/ai-harness'
+
+const now = () => Date.now()
+
+/** Base64 of the four bytes 1, 2, 3, 4. */
+const FOUR_BYTES = 'AQIDBA=='
+
+// ponytail: a cut-down copy of the fake model in agent.test.ts. Move the
+// copies to one helpers file when a fourth test file needs one.
+/** A model that answers "ok" to every call. */
+function model(): AnyTextAdapter {
+  return {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    '~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: () =>
+      (async function* (): AsyncGenerator<StreamChunk> {
+        yield {
+          type: EventType.RUN_STARTED,
+          runId: 'r',
+          threadId: 't',
+          timestamp: now(),
+        }
+        yield {
+          type: EventType.TEXT_MESSAGE_START,
+          messageId: 'm',
+          role: 'assistant',
+          timestamp: now(),
+        }
+        yield {
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          messageId: 'm',
+          delta: 'ok',
+          timestamp: now(),
+        }
+        yield {
+          type: EventType.TEXT_MESSAGE_END,
+          messageId: 'm',
+          timestamp: now(),
+        }
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId: 'r',
+          threadId: 't',
+          timestamp: now(),
+          metadata: { tanstack: { finishReason: 'stop' } },
+        }
+      })(),
+  }
+}
+
+let close: (() => Promise<void>) | undefined
+afterEach(async () => {
+  await close?.()
+  close = undefined
+})
+
+/**
+ * A harness with `media` options behind an ACP agent. `connect` runs `run`
+ * with an editor that has sent `initialize`, and gives it that answer.
+ */
+function setup(media?: MediaOptions) {
+  const harness = defineHarness({
+    name: 'test/acp-media',
+    adapter: model(),
+    media,
+  })
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  close = () => host.close()
+  const connect = <T>(
+    run: (ctx: ClientContext, init: InitializeResponse) => Promise<T>,
+  ) =>
+    client().connectWith(createAcpAgent({ host, harness }), async (ctx) =>
+      run(
+        ctx,
+        await ctx.request('initialize', {
+          protocolVersion: 2,
+          info: { name: 'editor', version: '1.0.0' },
+        }),
+      ),
+    )
+  return { harness, host, connect }
+}
+
+/**
+ * Send `prompt` to a new ACP session and wait for the turn. Returns the
+ * harness session and the user message the turn saved.
+ */
+async function savedPrompt(prompt: Array<ContentBlock>) {
+  const { harness, host, connect } = setup()
+  const sent = await connect(async (ctx) => {
+    const { sessionId } = await ctx.request('session/new', {
+      cwd: '/tmp',
+      mcpServers: [],
+    })
+    const { messageId } = await ctx.request('session/prompt', {
+      sessionId,
+      prompt,
+    })
+    return { sessionId, messageId }
+  })
+  const session = await host.open(harness, { threadId: sent.sessionId })
+  await session.operation(sent.messageId)
+  const [user] = await session.transcript()
+  if (user?.role !== 'user') throw new Error('The turn saved no user message.')
+  return { session, user }
+}
+
+describe('ACP agent media', () => {
+  it('advertises image, audio, and embedded context prompts in initialize', async () => {
+    const { connect } = setup()
+
+    const init = await connect(async (_ctx, answer) => answer)
+
+    expect(init.info).toEqual({ name: 'test/acp-media', version: '0.0.0' })
+    expect(init.capabilities).toEqual({
+      session: { prompt: { image: {}, audio: {}, embeddedContext: {} } },
+    })
+  })
+
+  it.each([
+    {
+      label: 'an image block',
+      block: {
+        type: 'image',
+        data: FOUR_BYTES,
+        mimeType: 'image/png',
+        uri: 'file:///shots/cat.png',
+      },
+      stored: { kind: 'image', mimeType: 'image/png', name: 'cat.png' },
+    },
+    {
+      label: 'an audio block',
+      block: { type: 'audio', data: FOUR_BYTES, mimeType: 'audio/wav' },
+      stored: { kind: 'audio', mimeType: 'audio/wav', name: 'audio' },
+    },
+    {
+      label: 'an embedded blob resource',
+      block: {
+        type: 'resource',
+        resource: {
+          uri: 'file:///docs/spec.pdf',
+          blob: FOUR_BYTES,
+          mimeType: 'application/pdf',
+        },
+      },
+      stored: {
+        kind: 'document',
+        mimeType: 'application/pdf',
+        name: 'spec.pdf',
+      },
+    },
+  ] satisfies Array<{
+    label: string
+    block: ContentBlock
+    stored: Pick<MediaRecord, 'kind' | 'mimeType' | 'name'>
+  }>)(
+    'stores $label and sends it as a media part',
+    async ({ block, stored }) => {
+      const { session, user } = await savedPrompt([
+        { type: 'text', text: 'What is this?' },
+        block,
+      ])
+
+      const [record] = mediaOfMessage(user)
+      if (!record) throw new Error('The user message has no media record.')
+      expect(record).toMatchObject({ ...stored, size: 4, source: 'user' })
+      expect(user.content).toEqual([
+        { type: 'text', content: 'What is this?' },
+        {
+          type: stored.kind,
+          source: {
+            type: 'url',
+            value: `harness-media:${record.id}`,
+            mimeType: stored.mimeType,
+          },
+        },
+      ])
+      expect(await session.loadMedia(record.id)).toEqual(
+        new Uint8Array([1, 2, 3, 4]),
+      )
+    },
+  )
+
+  it('sends text resources, resource links, and blobs it cannot store as text', async () => {
+    const { user } = await savedPrompt([
+      { type: 'text', text: 'Review these.' },
+      {
+        type: 'resource',
+        resource: {
+          uri: 'file:///src/a.ts',
+          text: 'export const a = 1',
+          mimeType: 'text/typescript',
+        },
+      },
+      { type: 'resource_link', name: 'b.ts', uri: 'file:///src/b.ts' },
+      {
+        type: 'resource',
+        resource: {
+          uri: 'file:///build.zip',
+          blob: FOUR_BYTES,
+          mimeType: 'application/zip',
+        },
+      },
+    ])
+
+    expect(user.content).toBe(
+      'Review these.\n[resource: file:///src/a.ts]\nexport const a = 1\n[resource link: file:///src/b.ts]\n[resource link: file:///build.zip]',
+    )
+  })
+
+  it('answers the prompt with an error, and runs no turn, when a file is over the limit', async () => {
+    const { harness, host, connect } = setup({ maxBytes: 2 })
+
+    const threadId = await connect(async (ctx) => {
+      const { sessionId } = await ctx.request('session/new', {
+        cwd: '/tmp',
+        mcpServers: [],
+      })
+      await expect(
+        ctx.request('session/prompt', {
+          sessionId,
+          prompt: [{ type: 'image', data: FOUR_BYTES, mimeType: 'image/png' }],
+        }),
+      ).rejects.toMatchObject({
+        code: -32602,
+        message:
+          'Invalid params: The file is bigger than the limit of 2 bytes.',
+      })
+      return sessionId
+    })
+
+    const session = await host.open(harness, { threadId })
+    expect(await session.transcript()).toEqual([])
+  })
+})
diff --git a/packages/ai-harness/src/harness-text.ts b/packages/ai-harness/src/harness-text.ts
index 2550d5c659..c47cc45d7f 100644
--- a/packages/ai-harness/src/harness-text.ts
+++ b/packages/ai-harness/src/harness-text.ts
@@ -1,9 +1,16 @@
-import { EventType } from '@tanstack/ai'
+import { EventType, uiMessagesToWire } from '@tanstack/ai'
 import { createHarnessHost } from './host'
-import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import { acceptedKinds } from './session'
+import type {
+  AnyTextAdapter,
+  Modality,
+  ModelMessage,
+  StreamChunk,
+} from '@tanstack/ai'
 import { isHarnessDefinition } from './define'
 import type { AnyHarness } from './define'
 import type { HarnessHost } from './host'
+import type { UserInput } from './types'
 
 export interface HarnessTextOptions {
   /** The host that runs the inner sessions. Default: a memory host. */
@@ -13,23 +20,31 @@ export interface HarnessTextOptions {
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null
 
-function lastUserText(messages: unknown): string {
-  const list: ReadonlyArray<unknown> = Array.isArray(messages) ? messages : []
-  const message = list.findLast(
-    (entry) => isRecord(entry) && entry.role === 'user',
+/** The content of the last user message: its text, or its content parts. */
+function lastUserInput(messages: ReadonlyArray<ModelMessage>) {
+  const message = messages.findLast((entry) => entry.role === 'user')
+  const input: UserInput = message?.content ?? ''
+  return input
+}
+
+/**
+ * What a harness reads: text, plus the kinds its session sends the model
+ * (the adapter's list narrowed by `media.accepts`). `undefined` when neither
+ * is known, so the outer harness sends every kind.
+ */
+function inputsOf(harness: AnyHarness) {
+  // ponytail: the harness adapter only. A plugin that picks another model at
+  // runtime is not seen here.
+  const kinds = acceptedKinds(
+    harness.adapter.inputModalities,
+    harness.media?.accepts,
   )
-  if (!isRecord(message)) return ''
-  if (typeof message.content === 'string') return message.content
-  const parts: ReadonlyArray<unknown> = Array.isArray(message.content)
-    ? message.content
-    : []
-  return parts
-    .map((part) =>
-      isRecord(part) && part.type === 'text' && typeof part.content === 'string'
-        ? part.content
-        : '',
-    )
-    .join('')
+  if (kinds === undefined) return undefined
+  const inputs: ReadonlyArray<Modality> = [
+    'text',
+    ...kinds.filter((kind) => kind !== 'text'),
+  ]
+  return inputs
 }
 
 /** Events of the inner turn that the outer chat shows as its own model output. */
@@ -44,17 +59,6 @@ const FORWARDED = new Set<string>([
   EventType.REASONING_END,
 ])
 
-/**
- * Use a harness as the model of a `chat()` call, the way you would call a
- * coding agent. Each outer thread gets its own inner session, which keeps
- * its own transcript, tools, plugins, and agents. The outer chat sees the
- * inner turn's text and reasoning.
- *
- * @example
- * ```ts
- * const stream = chat({ adapter: harnessText(studio), messages, threadId })
- * ```
- */
 /** A harness served by `createHarnessHandler` (or `runCli --serve`) on another machine. */
 export interface RemoteHarness {
   /** The handler base URL, for example `http://127.0.0.1:8787`. */
@@ -64,9 +68,11 @@ export interface RemoteHarness {
   fetch?: typeof fetch
 }
 
+// Type-only fields. Every input kind type-checks, so `chat()` lets callers
+// send files. The runtime `inputModalities` says what the harness reads.
 const TYPES = {
   providerOptions: {} as Record<string, unknown>,
-  inputModalities: ['text'] as readonly ['text'],
+  inputModalities: ['text', 'image', 'audio', 'video', 'document'] as const,
   messageMetadataByModality: {
     text: undefined as unknown,
     image: undefined as unknown,
@@ -104,6 +110,8 @@ async function* sseData(response: Response): AsyncGenerator<unknown> {
 function remoteHarnessText(remote: RemoteHarness): AnyTextAdapter {
   const base = remote.url.replace(/\/$/, '')
   const doFetch = remote.fetch ?? fetch
+  // No runtime `inputModalities`: the model of the remote harness is not
+  // known here, so the outer harness sends every kind.
   return {
     kind: 'text',
     name: 'harness-remote',
@@ -117,6 +125,10 @@ function remoteHarnessText(remote: RemoteHarness): AnyTextAdapter {
       (async function* (): AsyncGenerator<StreamChunk> {
         const threadId = chatOptions.threadId ?? 'default'
         const runId = chatOptions.runId ?? `harness-${Date.now().toString(36)}`
+        // AG-UI parts: text parts carry `text`, media parts pass through.
+        const [message] = uiMessagesToWire([
+          { role: 'user', content: lastUserInput(chatOptions.messages) },
+        ])
         const response = await doFetch(`${base}/run`, {
           method: 'POST',
           headers: {
@@ -129,13 +141,7 @@ function remoteHarnessText(remote: RemoteHarness): AnyTextAdapter {
             threadId,
             runId,
             // The remote session keeps its own history, so send the new message only.
-            messages: [
-              {
-                id: `${runId}-user`,
-                role: 'user',
-                content: lastUserText(chatOptions.messages),
-              },
-            ],
+            messages: [{ ...message, id: `${runId}-user` }],
             tools: [],
             context: [],
             state: {},
@@ -183,6 +189,21 @@ function remoteHarnessText(remote: RemoteHarness): AnyTextAdapter {
   }
 }
 
+/**
+ * Use a harness as the model of a `chat()` call, the way you would call a
+ * coding agent. Each outer thread gets its own inner session, which keeps
+ * its own transcript, tools, plugins, and agents. The inner turn gets the
+ * last user message with its content parts (images, audio, video,
+ * documents). The outer chat sees the inner turn's text and reasoning.
+ *
+ * `inputModalities` is what the harness reads: its adapter's list narrowed
+ * by `media.accepts`. It is `undefined` for a remote harness.
+ *
+ * @example
+ * ```ts
+ * const stream = chat({ adapter: harnessText(studio), messages, threadId })
+ * ```
+ */
 export function harnessText(
   harness: AnyHarness,
   options?: HarnessTextOptions,
@@ -199,20 +220,8 @@ export function harnessText(
     kind: 'text',
     name: 'harness',
     model: harness.name,
-    '~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,
-    },
+    inputModalities: inputsOf(harness),
+    '~types': TYPES,
     chatStream: (chatOptions) =>
       (async function* (): AsyncGenerator<StreamChunk> {
         host ??= createHarnessHost()
@@ -224,7 +233,7 @@ export function harnessText(
             ? chatOptions.request.signal
             : undefined
         const session = await host.open(harness, { threadId })
-        const operation = session.prompt(lastUserText(chatOptions.messages))
+        const operation = session.prompt(lastUserInput(chatOptions.messages))
         signal?.addEventListener('abort', () => void operation.cancel(), {
           once: true,
         })
diff --git a/packages/ai-harness/src/http.ts b/packages/ai-harness/src/http.ts
index 54853d3a59..e5665309c9 100644
--- a/packages/ai-harness/src/http.ts
+++ b/packages/ai-harness/src/http.ts
@@ -1,8 +1,13 @@
 import {
   EventType,
   chatParamsFromRequestBody,
+  convertMessagesToModelMessages,
+  isContentPart,
   toServerSentEventsResponse,
 } from '@tanstack/ai'
+import { parseRangeHeader, resolveBlobRange } from '@tanstack/ai-persistence'
+import { MediaError } from './media'
+import { base64url } from './oauth'
 import {
   HARNESS_PROTOCOL_VERSION,
   applyInput,
@@ -10,15 +15,22 @@ import {
   parseControlFrame,
   parseHarnessInput,
 } from './protocol'
-import type { StreamChunk, WebSocketLike } from '@tanstack/ai'
+import type {
+  ModelMessage,
+  StreamChunk,
+  UIMessage,
+  WebSocketLike,
+} from '@tanstack/ai'
 import type { AnyHarness } from './define'
 import type { HarnessHost } from './host'
 import type { HostFrame } from './protocol'
-import type { Principal } from './types'
+import type { HarnessSession } from './session'
+import type { Principal, UserInput } from './types'
 
 /**
  * Decide who sends a request. Return `null` to refuse it with 401. Every
- * endpoint calls it, so there is no unauthenticated route.
+ * 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,
@@ -36,33 +48,105 @@ export interface HarnessHandlerOptions {
     principal: Principal,
     threadId: string,
   ) => boolean | Promise<boolean>
+  /**
+   * The secret that signs media URLs (HMAC SHA-256). Default: a random key
+   * per handler, so signed URLs stop working after a restart. Set it to keep
+   * them working, and use the same value on every server behind one URL.
+   */
+  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 json = (body: unknown, status = 200) =>
   new Response(JSON.stringify(body), {
     status,
     headers: { 'Content-Type': 'application/json' },
   })
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null
+/** 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 text of the last user message of an AG-UI request. */
-function lastUserText(messages: ReadonlyArray<unknown>): string | undefined {
-  const message = messages.findLast(
-    (entry) => isRecord(entry) && entry.role === 'user',
-  )
-  if (!isRecord(message)) return undefined
-  if (typeof message.content === 'string') return message.content
-  // AG-UI content parts: `{ type: 'text', text }` and binary parts.
-  const parts = Array.isArray(message.content) ? message.content : []
-  return parts
-    .map((part: unknown) =>
-      isRecord(part) && part.type === 'text' && typeof part.text === 'string'
-        ? part.text
-        : '',
-    )
-    .join('')
+/**
+ * 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
+}
+
+/** 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}`,
+    },
+  })
 }
 
 /**
@@ -71,12 +155,22 @@ function lastUserText(messages: ReadonlyArray<unknown>): string | undefined {
  *
  * - `GET  .../capabilities`: the AG-UI capabilities document.
  * - `POST .../run`: standard AG-UI. One request is one prompt, streamed as SSE.
+ *   The prompt keeps every content part of the last user message.
  * - `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  .../describe?threadId=`: the commands, settings, and tools.
+ * - `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.
  */
 export function createHarnessHandler(
   options: HarnessHandlerOptions,
@@ -89,11 +183,61 @@ export function createHarnessHandler(
     return host.open(harness, { threadId, principal })
   }
 
+  // ponytail: without `mediaSecret`, a random key per handler, so signed URLs
+  // stop working after a restart. Set `mediaSecret` to keep them.
+  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)
+  }
+
   return async (request) => {
-    const principal = await authorize(request)
-    if (!principal) return json({ error: 'unauthorized' }, 401)
     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') {
@@ -102,7 +246,7 @@ export function createHarnessHandler(
 
       if (request.method === 'POST' && route === 'run') {
         const params = await chatParamsFromRequestBody(await request.json())
-        const message = lastUserText(params.messages)
+        const message = lastUserInput(params.messages)
         const session = await openFor(principal, params.threadId)
         if (!session) return json({ error: 'forbidden' }, 403)
         if (params.resume && params.resume.length > 0) {
@@ -142,7 +286,6 @@ export function createHarnessHandler(
           request.headers.get('Last-Event-ID') ??
           url.searchParams.get('from') ??
           undefined
-        const encoder = new TextEncoder()
         // Stops when the client cancels the response stream.
         const reader = new AbortController()
         const body = new ReadableStream<Uint8Array>({
@@ -216,11 +359,46 @@ export function createHarnessHandler(
         if (!session) return json({ error: 'forbidden' }, 403)
         return json(session.snapshot())
       }
+
+      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 json(
-        { error: error instanceof Error ? error.message : String(error) },
-        400,
-      )
+      return failed(error)
     }
     return json({ error: 'not found' }, 404)
   }
diff --git a/packages/ai-harness/src/oauth.ts b/packages/ai-harness/src/oauth.ts
index b73cf14f8e..446ce1590d 100644
--- a/packages/ai-harness/src/oauth.ts
+++ b/packages/ai-harness/src/oauth.ts
@@ -16,7 +16,8 @@ type Fetch = typeof fetch
 
 const encoder = new TextEncoder()
 
-function base64url(bytes: Uint8Array): string {
+/** 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(/=+$/, '')
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index efce25b056..a0e3faddee 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -41,6 +41,7 @@ import type {
   AIPersistence,
   ArtifactStore,
   BlobBody,
+  BlobRange,
   BlobStore,
   CredentialStore,
   GenerationRunStore,
@@ -239,7 +240,7 @@ function referenceNote(agent: string, result: unknown): string {
  * `media.accepts`. Either one alone when only one is known, and `undefined`
  * (send every kind) when neither is.
  */
-function acceptedKinds(
+export function acceptedKinds(
   modalities: ReadonlyArray<Modality> | undefined,
   accepts: ReadonlyArray<MediaKind> | undefined,
 ) {
@@ -590,9 +591,12 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     return this.mediaStore.get(id)
   }
 
-  /** The bytes of a media file. Throws a `MediaError` with 404 when it is not found. */
-  loadMedia(id: string) {
-    return this.mediaStore.load(id)
+  /**
+   * The bytes of a media file, or of one `range` of them. Throws a
+   * `MediaError` with 404 when it is not found.
+   */
+  loadMedia(id: string, range?: BlobRange) {
+    return this.mediaStore.load(id, range)
   }
 
   /**
diff --git a/packages/ai-harness/tests/client-media.test.ts b/packages/ai-harness/tests/client-media.test.ts
index 8b4e6c5159..09cbaf46b6 100644
--- a/packages/ai-harness/tests/client-media.test.ts
+++ b/packages/ai-harness/tests/client-media.test.ts
@@ -94,6 +94,17 @@ describe('client media', () => {
     ).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({
diff --git a/packages/ai-harness/tests/harness-text-media.test.ts b/packages/ai-harness/tests/harness-text-media.test.ts
new file mode 100644
index 0000000000..9551c1321e
--- /dev/null
+++ b/packages/ai-harness/tests/harness-text-media.test.ts
@@ -0,0 +1,131 @@
+import { describe, expect, it } from 'vitest'
+import { chat } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness, harnessText } from '../src'
+import { mockAdapter, text } from './helpers'
+import type { AnyTextAdapter, ContentPart, Modality } from '@tanstack/ai'
+import type { MediaKind } from '../src'
+
+// 'aGVsbG8=' is base64 for "hello".
+const image: ContentPart = {
+  type: 'image',
+  source: { type: 'data', value: 'aGVsbG8=', mimeType: 'image/png' },
+}
+const question: Array<ContentPart> = [
+  { type: 'text', content: 'What is this?' },
+  image,
+]
+
+async function drain(stream: AsyncIterable<unknown>) {
+  for await (const _chunk of stream) {
+    // Runs the outer chat to its end.
+  }
+}
+
+/** A mock inner model that reads `inputs` at runtime. */
+function innerAdapter(inputs?: ReadonlyArray<Modality>) {
+  const { adapter, calls } = mockAdapter(() => text('a cat'))
+  const withInputs: AnyTextAdapter = { ...adapter, inputModalities: inputs }
+  return { adapter: withInputs, calls }
+}
+
+describe('harnessText media', () => {
+  it('passes the parts of the last user message to the inner session', async () => {
+    const inner = innerAdapter()
+    const studio = defineHarness({ name: 'test/inner', adapter: inner.adapter })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+
+    await drain(
+      chat({
+        adapter: harnessText(studio, { host }),
+        messages: [
+          { role: 'user', content: 'an older question' },
+          { role: 'user', content: question },
+        ],
+        threadId: 'outer',
+      }),
+    )
+
+    expect(inner.calls[0].messages).toHaveLength(1)
+    expect(inner.calls[0].messages[0].content).toEqual(question)
+    await host.close()
+  })
+
+  const inputs: Array<{
+    label: string
+    reads?: ReadonlyArray<Modality>
+    accepts?: ReadonlyArray<MediaKind>
+    expected: ReadonlyArray<Modality> | undefined
+  }> = [
+    {
+      label: 'the inner adapter list',
+      reads: ['text', 'image', 'audio'],
+      expected: ['text', 'image', 'audio'],
+    },
+    {
+      label: 'the inner adapter list narrowed by media.accepts',
+      reads: ['text', 'image', 'audio'],
+      accepts: ['image', 'video'],
+      expected: ['text', 'image'],
+    },
+    {
+      label: 'text plus media.accepts when the adapter has no list',
+      accepts: ['audio'],
+      expected: ['text', 'audio'],
+    },
+    { label: 'unknown when neither is known', expected: undefined },
+  ]
+
+  it.each(inputs)('reads $label', ({ reads, accepts, expected }) => {
+    const studio = defineHarness({
+      name: 'test/inputs',
+      adapter: innerAdapter(reads).adapter,
+      media: { accepts },
+    })
+
+    expect(harnessText(studio).inputModalities).toEqual(expected)
+  })
+
+  it('does not know what a remote harness reads', () => {
+    expect(harnessText({ url: 'http://remote.test' }).inputModalities).toBe(
+      undefined,
+    )
+  })
+
+  it('posts the parts of the last user message to a remote harness as AG-UI parts', async () => {
+    const bodies: Array<unknown> = []
+    const remote = harnessText({
+      url: 'http://remote.test/api/harness',
+      fetch: async (_input, init) => {
+        bodies.push(JSON.parse(String(init?.body)))
+        return new Response(null, { status: 200 })
+      },
+    })
+
+    await drain(
+      chat({
+        adapter: remote,
+        messages: [{ role: 'user', content: question }],
+        threadId: 'outer',
+      }),
+    )
+
+    expect(bodies).toEqual([
+      {
+        threadId: 'outer',
+        runId: expect.any(String),
+        messages: [
+          {
+            id: expect.any(String),
+            role: 'user',
+            content: [{ type: 'text', text: 'What is this?' }, image],
+          },
+        ],
+        tools: [],
+        context: [],
+        state: {},
+        forwardedProps: {},
+      },
+    ])
+  })
+})
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..9d4ea42057
--- /dev/null
+++ b/packages/ai-harness/tests/http-media.test.ts
@@ -0,0 +1,386 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { 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('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/resume-edges.test.ts b/packages/ai-harness/tests/resume-edges.test.ts
index 7c9367ec33..685de95ffa 100644
--- a/packages/ai-harness/tests/resume-edges.test.ts
+++ b/packages/ai-harness/tests/resume-edges.test.ts
@@ -8,7 +8,7 @@ import {
   findCrashedRuns,
   repairTranscript,
 } from '../src/resume'
-import { messageTexts, mockAdapter, text, untilAborted } from './helpers'
+import { mockAdapter, text, untilAborted } from './helpers'
 import type { RunRecord, StreamChunk } from '@tanstack/ai'
 import type { HarnessPersistence } from '../src/host'
 
@@ -162,7 +162,7 @@ describe('crash recovery edges', () => {
 })
 
 describe('harnessText edges', () => {
-  it('uses a memory host by default and reads text content parts', async () => {
+  it('uses a memory host by default and keeps the content parts', async () => {
     const inner = mockAdapter([() => text('parts answer'), () => text('empty')])
     const studio = defineHarness({ name: 'test/parts', adapter: inner.adapter })
     const model = harnessText(studio)
@@ -173,22 +173,15 @@ describe('harnessText edges', () => {
       }
       return out
     }
-    expect(
-      await collect([
-        {
-          role: 'user',
-          content: [
-            { type: 'text', content: 'one ' },
-            {
-              type: 'image',
-              source: { type: 'url', value: 'https://x/y.png' },
-            },
-            { type: 'text', content: 'two' },
-          ],
-        },
-      ]),
-    ).toBe('parts answer')
-    expect(messageTexts(inner.calls[0])).toEqual(['one two'])
+    const parts = [
+      { type: 'text', content: 'one ' },
+      { type: 'image', source: { type: 'url', value: 'https://x/y.png' } },
+      { type: 'text', content: 'two' },
+    ]
+    expect(await collect([{ role: 'user', content: parts }])).toBe(
+      'parts answer',
+    )
+    expect(inner.calls[0].messages[0].content).toEqual(parts)
     await expect(model.structuredOutput({} as never)).rejects.toThrow(
       'does not support structured output',
     )

From 116f1def149c8167ae79a8acaefdc4b6a1cc75f4 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 29 Sep 2026 12:32:33 +0200
Subject: [PATCH 061/286] feat(ai-mcp): harness MCP media (attachments, media
 in results, media links), and resource templates that read their URI

createHarnessMcpServer takes filePaths for path attachments, the chat tool takes path, url, and data attachments, and results carry the media a turn made: small images and audio inline, other files as harness-media:// links. resourceDefinition({ uriTemplate, argsSchema }) now gives read the parsed template variables and the URI, and a read result can set its own mimeType.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/mcp-resource-template-args.md      |   5 +
 docs/config.json                              |   3 +-
 docs/mcp/server-content.md                    |  12 +-
 packages/ai-mcp/src/direct-client.ts          |  10 +-
 packages/ai-mcp/src/harness.ts                | 377 +++++++++++++-
 packages/ai-mcp/src/server/create-server.ts   |  31 +-
 packages/ai-mcp/src/server/definitions.ts     |  41 +-
 packages/ai-mcp/tests/harness-media.test.ts   | 479 ++++++++++++++++++
 .../ai-mcp/tests/server/create-server.test.ts |  27 +
 .../ai-mcp/tests/server/definitions.test.ts   |  13 +
 10 files changed, 974 insertions(+), 24 deletions(-)
 create mode 100644 .changeset/mcp-resource-template-args.md
 create mode 100644 packages/ai-mcp/tests/harness-media.test.ts

diff --git a/.changeset/mcp-resource-template-args.md b/.changeset/mcp-resource-template-args.md
new file mode 100644
index 0000000000..b5126989b0
--- /dev/null
+++ b/.changeset/mcp-resource-template-args.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-mcp': minor
+---
+
+A resource with a `uriTemplate` can read the URI the host asked for. `resourceDefinition({ uriTemplate, argsSchema })` parses the template variables, and `read` gets them and the URI. A read result `{ text | blob, mimeType }` sets the MIME type of that answer.
diff --git a/docs/config.json b/docs/config.json
index d74f1aeba1..b43bb68369 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -530,7 +530,8 @@
         {
           "label": "Serve Resources and Prompts",
           "to": "mcp/server-content",
-          "addedAt": "2026-09-22"
+          "addedAt": "2026-09-22",
+          "updatedAt": "2026-09-29"
         },
         {
           "label": "Ask for Input",
diff --git a/docs/mcp/server-content.md b/docs/mcp/server-content.md
index 13d84c56f9..bf8af07df4 100644
--- a/docs/mcp/server-content.md
+++ b/docs/mcp/server-content.md
@@ -41,7 +41,8 @@ const file = resourceDefinition({
   name: 'file',
   mimeType: 'text/plain',
   uriTemplate: 'file:///{path}',
-}).read(async () => ({ text: 'file body' }))
+  argsSchema: z.object({ path: z.string() }),
+}).read(async ({ path }) => ({ text: `The body of ${path}` }))
 
 const summarize = promptDefinition({
   name: 'summarize',
@@ -72,7 +73,12 @@ If the resource has no `uri` and no `uriTemplate`, `resourceDefinition` throws `
 
 If you pass `uri` and `uriTemplate`, the server uses `uri`.
 
-`read` takes no arguments. `read` returns `{ text }` for a text document. For a binary document, `read` returns `{ blob }` with a base64 string.
+`read` returns `{ text }` for a text document. For a binary document, `read` returns `{ blob }` with a base64 string. Add `mimeType` to that object when one template serves files of different types.
+
+For a `uriTemplate`, `read` gets the variables of the URI the host asked for, and the URI itself:
+
+- `argsSchema.parse` runs first, so `read` gets the parsed variables. For `file:///notes.md`, `path` is `notes.md`.
+- Without `argsSchema`, `read` gets the variables as strings.
 
 ## Prompts
 
@@ -89,4 +95,6 @@ If `role` is not `user` or `assistant`, the server sends that message as `user`.
 
 The host reads `file:///readme.md`. The `text` is `# Hello`.
 
+The host reads `file:///notes.md`. The `text` is `The body of notes.md`.
+
 The host starts from the `summarize` prompt with topic `weather`. The `role` is `user`. The `content` string is `weather`.
diff --git a/packages/ai-mcp/src/direct-client.ts b/packages/ai-mcp/src/direct-client.ts
index 7719839a08..cb0233bbf2 100644
--- a/packages/ai-mcp/src/direct-client.ts
+++ b/packages/ai-mcp/src/direct-client.ts
@@ -113,7 +113,7 @@ type ListedTool = {
 
 type ListedResource = {
   uri?: string
-  read: () => unknown
+  read: (variables: Record<string, string | Array<string>>, uri: URL) => unknown
 }
 
 type ListedPrompt = {
@@ -179,10 +179,14 @@ export function directMCPClient<const TServer extends MCPServer>(
       if (resource === undefined) {
         throw new Error(`The MCP server has no resource ${uri}.`)
       }
-      const read = resource.read as () =>
+      const read = resource.read as (
+        variables: Record<string, string | Array<string>>,
+        uri: URL,
+      ) =>
         | ResourceContents<ResourceByUri<TServer['resources'], TUri>>
         | Promise<ResourceContents<ResourceByUri<TServer['resources'], TUri>>>
-      return read()
+      // A fixed uri has no template variables.
+      return read({}, new URL(uri))
     },
 
     async getPrompt<const TName extends PromptNames<TServer['prompts']>>(
diff --git a/packages/ai-mcp/src/harness.ts b/packages/ai-mcp/src/harness.ts
index 11a330212d..eacf38174c 100644
--- a/packages/ai-mcp/src/harness.ts
+++ b/packages/ai-mcp/src/harness.ts
@@ -4,18 +4,26 @@ import {
   readUnopenedInterruptBinding,
   toolDefinition,
 } from '@tanstack/ai'
-import { HARNESS_EVENTS } from '@tanstack/ai-harness'
+import {
+  HARNESS_EVENTS,
+  isMediaRecord,
+  kindOf,
+  mediaPart,
+} 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 } from './server/index'
-import type { Interrupt, JSONSchema } from '@tanstack/ai'
+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'
 
 /** Options for {@link createHarnessMcpServer}. */
@@ -38,6 +46,15 @@ export interface HarnessMcpServerOptions {
    * 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'`. */
@@ -50,12 +67,101 @@ 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
+
+// ponytail: common types only. Send any other file as data with its mimeType.
+const mimeTypes = new Map([
+  ['png', 'image/png'],
+  ['jpg', 'image/jpeg'],
+  ['jpeg', 'image/jpeg'],
+  ['gif', 'image/gif'],
+  ['webp', 'image/webp'],
+  ['mp3', 'audio/mpeg'],
+  ['wav', 'audio/wav'],
+  ['ogg', 'audio/ogg'],
+  ['m4a', 'audio/mp4'],
+  ['flac', 'audio/flac'],
+  ['mp4', 'video/mp4'],
+  ['webm', 'video/webm'],
+  ['mov', 'video/quicktime'],
+  ['pdf', 'application/pdf'],
+  ['txt', 'text/plain'],
+  ['md', 'text/markdown'],
+  ['csv', 'text/csv'],
+  ['html', 'text/html'],
+])
+
 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.
@@ -70,10 +176,17 @@ const threadIdSchema: JSONSchema = {
  * `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, and the approval mode
+ * @param options - The host, the harness, the default thread, the approval mode, and the folders for `path` attachments
  *
  * @example
  * ```ts
@@ -85,6 +198,7 @@ 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>>()
 
@@ -124,7 +238,7 @@ export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
   }
 
   // Waits for the work. A chat turn that stops for approvals continues while
-  // the approval mode decides them.
+  // the approval mode decides them. The result gets the media of the work.
   async function finish(
     session: HarnessSession,
     work: Operation<unknown>,
@@ -133,23 +247,29 @@ export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
   ) {
     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) }
       }
-      if (operation.kind !== 'chat') return outcome.value
+      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) {
-        return {
+        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
@@ -188,18 +308,20 @@ export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
   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, and the interrupts and questions that wait for you.',
+      '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(textArg(args, 'message'), { busy: 'queue' })
+    const turn = session.prompt(message, { busy: 'queue' })
     return finish(session, turn, from, ctx.context)
   })
 
@@ -373,9 +495,27 @@ export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
       }),
   )
 
+  // 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 ({ 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',
+    resources: [mediaResource],
     tools: [
       chat,
       steer,
@@ -471,6 +611,214 @@ function pending(session: HarnessSession) {
   }
 }
 
+/**
+ * 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 MIME type of a file name or URL path by its extension, or `undefined`. */
+function mimeTypeOf(path: string) {
+  const extension = /\.([^./\\]+)$/.exec(path)?.[1]
+  return extension === undefined
+    ? undefined
+    : mimeTypes.get(extension.toLowerCase())
+}
+
+/** 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
@@ -620,6 +968,17 @@ function isDecision(value: unknown): value is Decision {
   )
 }
 
+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)
diff --git a/packages/ai-mcp/src/server/create-server.ts b/packages/ai-mcp/src/server/create-server.ts
index 8d63123f62..ab64d63c4c 100644
--- a/packages/ai-mcp/src/server/create-server.ts
+++ b/packages/ai-mcp/src/server/create-server.ts
@@ -59,7 +59,8 @@ type McpResource = {
   mimeType: string
   uri?: string
   uriTemplate?: string
-  read: () => unknown
+  /** Gets the variables of a `uriTemplate` (none for a `uri`) and the URI. */
+  read: (variables: Record<string, string | Array<string>>, uri: URL) => unknown
 }
 
 // A method type is bivariant. A function property is strict, so a prompt
@@ -641,20 +642,38 @@ function isTextBlock(value: unknown): value is { type: 'text'; text: string } {
 
 function registerServerResource(server: McpServer, resource: McpResource) {
   const metadata = { mimeType: resource.mimeType }
-  const read = async (uri: URL) =>
-    resourceContents(uri.href, resource.mimeType, await resource.read())
+  const read = async (
+    uri: URL,
+    variables: Record<string, string | Array<string>>,
+  ) =>
+    resourceContents(
+      uri.href,
+      resource.mimeType,
+      await resource.read(variables, uri),
+    )
   if (resource.uri !== undefined) {
-    server.registerResource(resource.name, resource.uri, metadata, read)
+    // A fixed uri has no variables. The SDK's second argument is the request.
+    server.registerResource(resource.name, resource.uri, metadata, (uri) =>
+      read(uri, {}),
+    )
     return
   }
   if (resource.uriTemplate === undefined) return
   const template = new ResourceTemplate(resource.uriTemplate, {
     list: undefined,
   })
-  server.registerResource(resource.name, template, metadata, read)
+  // A template gets the variables the SDK matched in the asked-for URI.
+  server.registerResource(resource.name, template, metadata, (uri, variables) =>
+    read(uri, variables),
+  )
 }
 
-function resourceContents(uri: string, mimeType: string, body: unknown) {
+function resourceContents(uri: string, fallback: string, body: unknown) {
+  // A body can name its own MIME type: one template can serve many types.
+  const mimeType =
+    isRecord(body) && typeof body.mimeType === 'string'
+      ? body.mimeType
+      : fallback
   if (isRecord(body) && typeof body.text === 'string') {
     return { contents: [{ uri, mimeType, text: body.text }] }
   }
diff --git a/packages/ai-mcp/src/server/definitions.ts b/packages/ai-mcp/src/server/definitions.ts
index c24763f628..a006c2a50d 100644
--- a/packages/ai-mcp/src/server/definitions.ts
+++ b/packages/ai-mcp/src/server/definitions.ts
@@ -7,6 +7,15 @@ type PromptArgsSchema<TArgs> = {
   parse: (input: unknown) => TArgs
 }
 
+/** The variables of a `uriTemplate`, as the MCP SDK matches them. */
+type TemplateVariables = Record<string, string | Array<string>>
+
+type ResourceArgsOf<TConfig> = TConfig extends {
+  argsSchema: PromptArgsSchema<infer TArgs>
+}
+  ? TArgs
+  : TemplateVariables
+
 /**
  * Builds a resource definition for the MCP server.
  *
@@ -14,7 +23,12 @@ type PromptArgsSchema<TArgs> = {
  * If `uri` and `uriTemplate` are both missing, this function throws a TypeError.
  * Call `.read` with a function that returns the resource contents.
  *
- * @param config - The resource `name`, `mimeType`, and `uri` or `uriTemplate`.
+ * For a `uriTemplate`, the read function gets the variables of the URI the
+ * client asked for, and the URI itself. Pass `argsSchema` to parse the
+ * variables first. A body `{ text | blob, mimeType }` sets the MIME type of
+ * that answer, for a template whose files have different types.
+ *
+ * @param config - The resource `name`, `mimeType`, `uri` or `uriTemplate`, and an optional `argsSchema`.
  * @throws {TypeError} When `uri` and `uriTemplate` are both missing.
  *
  * @example
@@ -24,6 +38,13 @@ type PromptArgsSchema<TArgs> = {
  *   name: 'readme',
  *   mimeType: 'text/markdown',
  * }).read(async () => ({ text: '# Hello' }))
+ *
+ * const user = resourceDefinition({
+ *   uriTemplate: 'users://{id}',
+ *   name: 'user',
+ *   mimeType: 'application/json',
+ *   argsSchema: z.object({ id: z.string() }),
+ * }).read(async ({ id }) => ({ text: JSON.stringify(await loadUser(id)) }))
  * ```
  */
 export function resourceDefinition<
@@ -32,6 +53,7 @@ export function resourceDefinition<
     mimeType: string
     uri?: string
     uriTemplate?: string
+    argsSchema?: PromptArgsSchema<unknown>
   },
 >(config: TConfig) {
   const hasUri = config.uri !== undefined
@@ -44,10 +66,23 @@ export function resourceDefinition<
 
   return {
     ...config,
-    read<TContents>(readContents: () => TContents | Promise<TContents>) {
+    read<TContents>(
+      readContents: (
+        args: ResourceArgsOf<TConfig>,
+        uri: URL | undefined,
+      ) => TContents | Promise<TContents>,
+    ) {
       return {
         ...config,
-        read: readContents,
+        async read(variables: TemplateVariables = {}, uri?: URL) {
+          // Without `argsSchema`, the args are the variables as matched.
+          // `ResourceArgsOf` picks the same branch from the config type, which
+          // TypeScript cannot follow through the runtime check.
+          const args = (
+            config.argsSchema ? config.argsSchema.parse(variables) : variables
+          ) as ResourceArgsOf<TConfig>
+          return readContents(args, uri)
+        },
       }
     },
   }
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/server/create-server.test.ts b/packages/ai-mcp/tests/server/create-server.test.ts
index 98bdefdf50..792e066d75 100644
--- a/packages/ai-mcp/tests/server/create-server.test.ts
+++ b/packages/ai-mcp/tests/server/create-server.test.ts
@@ -1149,6 +1149,33 @@ describe('createMCPServer', () => {
     })
   })
 
+  it('reads a uri template with its variables and the MIME type of the body', async () => {
+    const server = createMCPServer({
+      name: 'files',
+      version: '1.0.0',
+      resources: [
+        resourceDefinition({
+          uriTemplate: 'media://{folder}/{id}',
+          name: 'media',
+          mimeType: 'application/octet-stream',
+          argsSchema: z.object({ folder: z.string(), id: z.string() }),
+        }).read(async ({ folder, id }) => ({
+          blob: btoa(`${folder}/${id}`),
+          mimeType: 'image/png',
+        })),
+      ],
+    })
+
+    await withClient(server, { era: '2026' }, async (client) => {
+      const read = await client.readResource({ uri: 'media://cats/7' })
+      expect(read.contents[0]).toEqual({
+        uri: 'media://cats/7',
+        mimeType: 'image/png',
+        blob: btoa('cats/7'),
+      })
+    })
+  })
+
   it('keeps assistant prompt messages and drops invalid ones', async () => {
     const server = createMCPServer({
       name: 'prompts',
diff --git a/packages/ai-mcp/tests/server/definitions.test.ts b/packages/ai-mcp/tests/server/definitions.test.ts
index 5fee912bc5..7f6de3d383 100644
--- a/packages/ai-mcp/tests/server/definitions.test.ts
+++ b/packages/ai-mcp/tests/server/definitions.test.ts
@@ -27,6 +27,19 @@ describe('resourceDefinition', () => {
     expect(await resource.read()).toEqual({ text: 'body' })
   })
 
+  it('gives the read function the variables parsed by argsSchema', async () => {
+    const resource = resourceDefinition({
+      name: 'user',
+      mimeType: 'text/plain',
+      uriTemplate: 'users://{id}',
+      argsSchema: z.object({ id: z.string().transform(Number) }),
+    }).read(async ({ id }, uri) => ({ text: `${id + 1} ${uri?.href}` }))
+
+    expect(await resource.read({ id: '41' }, new URL('users://41'))).toEqual({
+      text: '42 users://41',
+    })
+  })
+
   it('throws when uri and uriTemplate are missing', () => {
     expect(() =>
       resourceDefinition({

From f10e6f51bfbd46aca648f3ec62c3f829ba806496 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 29 Sep 2026 12:55:06 +0200
Subject: [PATCH 062/286] feat(ai-harness-cli): attach files with @path, save
 media to a folder, and an E2E test for web media

Line mode, -p, piped input, and a custom ui attach @path files. Generated media is saved to ./<harness>-media (--media-dir to change it): line mode prints a saved line, and -p --output ndjson adds the path to the harness.media event. --mcp lets path attachments read the working folder. The MIME lookup is shared as mimeTypeOf. The E2E test uploads an image, sends it, and loads the generated image from its signed URL.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-harness-cli/src/args.ts           |   7 +
 packages/ai-harness-cli/src/attach.ts         | 155 +++++++++
 packages/ai-harness-cli/src/commands.ts       |  21 +-
 packages/ai-harness-cli/src/index.ts          |  51 ++-
 packages/ai-harness-cli/src/lines.ts          |  14 +-
 packages/ai-harness-cli/src/print.ts          |  39 ++-
 packages/ai-harness-cli/src/printer.ts        |  24 +-
 packages/ai-harness-cli/tests/attach.test.ts  | 208 +++++++++++
 .../ai-harness-cli/tests/child-view.test.ts   |  12 +-
 .../ai-harness-cli/tests/cli-media.test.ts    | 323 ++++++++++++++++++
 packages/ai-harness/src/index.ts              |   1 +
 packages/ai-harness/src/media-ref.ts          |  38 +++
 packages/ai-mcp/src/harness.ts                |  31 +-
 testing/e2e/fixtures/harness/media.json       |  37 ++
 .../e2e/src/routes/api.harness-protocol.$.ts  |  30 +-
 testing/e2e/tests/harness-media.spec.ts       | 174 ++++++++++
 16 files changed, 1109 insertions(+), 56 deletions(-)
 create mode 100644 packages/ai-harness-cli/src/attach.ts
 create mode 100644 packages/ai-harness-cli/tests/attach.test.ts
 create mode 100644 packages/ai-harness-cli/tests/cli-media.test.ts
 create mode 100644 testing/e2e/fixtures/harness/media.json
 create mode 100644 testing/e2e/tests/harness-media.spec.ts

diff --git a/packages/ai-harness-cli/src/args.ts b/packages/ai-harness-cli/src/args.ts
index aa9e0d06f8..c5b89c797f 100644
--- a/packages/ai-harness-cli/src/args.ts
+++ b/packages/ai-harness-cli/src/args.ts
@@ -13,12 +13,14 @@ export interface CliArgs {
   token?: string
   thread: string
   dashboard?: string
+  mediaDir?: string
 }
 
 export const USAGE = `Usage: <your-cli> [options]
 
 With no options in a terminal, starts the UI of this CLI, if it has one.
 Otherwise, and for piped input, reads one message or command per line.
+In a message, @path sends a file with it (@"my cat.png" for a path with spaces).
 
 Options:
   -p, --print <prompt>   Run one prompt, print the answer, and exit
@@ -32,6 +34,7 @@ Options:
       --token <token>    Bearer token for --serve (default: HARNESS_TOKEN, or a new random token)
       --thread <id>      Conversation id (default: main)
       --dashboard <url>  Connect to a dashboard (pairs on first use; set HARNESS_DASHBOARD_TOKEN to skip)
+      --media-dir <dir>  Save the media a turn makes here (default: ./<harness name>-media)
   -h, --help             Show this help
 
 Exit codes for --print: 0 done, 1 failed, 2 waiting for approval, 130 cancelled.`
@@ -53,6 +56,7 @@ export function parseCliArgs(argv: ReadonlyArray<string>): CliArgs {
       token: { type: 'string' },
       thread: { type: 'string' },
       dashboard: { type: 'string' },
+      'media-dir': { type: 'string' },
     },
     strict: true,
   })
@@ -77,5 +81,8 @@ export function parseCliArgs(argv: ReadonlyArray<string>): CliArgs {
     ...(values.token !== undefined ? { token: values.token } : {}),
     thread: values.thread ?? 'main',
     ...(values.dashboard !== undefined ? { dashboard: values.dashboard } : {}),
+    ...(values['media-dir'] !== undefined
+      ? { mediaDir: values['media-dir'] }
+      : {}),
   }
 }
diff --git a/packages/ai-harness-cli/src/attach.ts b/packages/ai-harness-cli/src/attach.ts
new file mode 100644
index 0000000000..880689a407
--- /dev/null
+++ b/packages/ai-harness-cli/src/attach.ts
@@ -0,0 +1,155 @@
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises'
+import { basename, join, resolve } from 'node:path'
+import { mediaPart, mimeTypeOf } from '@tanstack/ai-harness'
+import type { ContentPart } from '@tanstack/ai'
+import type {
+  HarnessSession,
+  MediaRecord,
+  UserInput,
+} from '@tanstack/ai-harness'
+
+/**
+ * An `@path` token: an `@` at the start of the text or after white space,
+ * then a quoted path (`@"my cat.png"`) or the text up to the next white
+ * space. The white space before the `@` is part of the match, so it goes
+ * out of the text with the token.
+ */
+const TOKEN = /(^|\s)@(?:"([^"]+)"|(\S+))/g
+
+/** The path of a token. One of the two groups always matches. */
+function pathOf(token: RegExpExecArray) {
+  return token[2] ?? token[3] ?? ''
+}
+
+/**
+ * The file that `path` names, when it is a readable regular file, else
+ * `undefined`. A file with an extension that `mimeTypeOf` does not know
+ * throws.
+ */
+async function readToken(path: string, cwd: string) {
+  const file = resolve(cwd, path)
+  const info = await stat(file).catch(() => undefined)
+  if (!info?.isFile()) return undefined
+  const name = basename(file)
+  const mimeType = mimeTypeOf(name)
+  if (mimeType === undefined) {
+    throw new Error(
+      `Cannot attach ${name}: the file type is not known. To send the path as text, remove the @.`,
+    )
+  }
+  // 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.
+  const bytes = await readFile(file).catch(() => undefined)
+  return bytes === undefined ? undefined : { bytes, mimeType, name }
+}
+
+/**
+ * The message for `text`, with each `@path` token that names a file sent as
+ * a stored media part. The token goes out of the text. Any other `@` stays
+ * as typed: `me@acme.dev`, `@types/node`, or a path with no file. Returns
+ * `text` as it is when no token names a file.
+ *
+ * Throws for a file of a type it does not know, before it stores a file.
+ * `putMedia` throws a `MediaError` for a file over `media.maxBytes`, or of a
+ * kind that the harness does not take. The message does not go then.
+ */
+export async function attach(
+  session: HarnessSession,
+  text: string,
+  options: { cwd: string },
+) {
+  const tokens = [...text.matchAll(TOKEN)]
+  // Read every file first, so a bad file stops the send before a store.
+  const files = await Promise.all(
+    tokens.map((token) => readToken(pathOf(token), options.cwd)),
+  )
+  if (files.every((file) => file === undefined)) return text
+
+  const media: Array<ContentPart> = []
+  let rest = ''
+  let end = 0
+  for (const [index, token] of tokens.entries()) {
+    const file = files[index]
+    if (file === undefined) continue
+    rest += text.slice(end, token.index)
+    end = token.index + token[0].length
+    const record = await session.putMedia(file.bytes, {
+      mimeType: file.mimeType,
+      name: file.name,
+    })
+    media.push(mediaPart(record))
+  }
+  const content = `${rest}${text.slice(end)}`.trim()
+  const input: UserInput =
+    content === '' ? media : [{ type: 'text', content }, ...media]
+  return input
+}
+
+function isTaken(error: unknown) {
+  return error instanceof Error && 'code' in error && error.code === 'EEXIST'
+}
+
+/**
+ * Write the bytes of a media file into `dir`, and return the path. The file
+ * gets the name of the record, with `-1`, `-2`, ... before the extension
+ * when that name is taken. It never overwrites a file. A name with a folder
+ * in it (`/`, `\`, a drive `:`), `.`, or `..` is refused, because a name can
+ * come from an upload.
+ */
+export async function saveMedia(
+  session: HarnessSession,
+  record: Pick<MediaRecord, 'id' | 'name'>,
+  dir: string,
+) {
+  const { name } = record
+  const isPlainName =
+    name !== '' && name !== '.' && name !== '..' && !/[\\/:]/.test(name)
+  if (!isPlainName) {
+    throw new Error(
+      `Cannot save ${JSON.stringify(name)}: it is not a plain file name.`,
+    )
+  }
+  const bytes = await session.loadMedia(record.id)
+  await mkdir(dir, { recursive: true })
+  const dot = name.lastIndexOf('.')
+  const stem = dot > 0 ? name.slice(0, dot) : name
+  const extension = dot > 0 ? name.slice(dot) : ''
+  for (let count = 0; ; count += 1) {
+    const path = join(dir, count === 0 ? name : `${stem}-${count}${extension}`)
+    try {
+      // `wx` fails when the file is there, so a file is never overwritten.
+      await writeFile(path, bytes, { flag: 'wx' })
+      return path
+    } catch (error) {
+      if (!isTaken(error)) throw error
+    }
+  }
+}
+
+/**
+ * Save a media file with `saveMedia`, and get the line that says where it
+ * went, or why it was not saved. It does not throw.
+ */
+export async function saveMediaLine(
+  session: HarnessSession,
+  record: Pick<MediaRecord, 'id' | 'name' | 'kind'>,
+  dir: string,
+) {
+  try {
+    const path = await saveMedia(session, record, dir)
+    return { path, text: `[${record.kind} saved: ${path}]` }
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    return { text: `[${record.kind} not saved: ${reason}]` }
+  }
+}
+
+/**
+ * The default media folder of a harness, relative to the working folder:
+ * the name as a safe folder name, then `-media`. `acme/coder` saves into
+ * `acme-coder-media`.
+ */
+export function defaultMediaDir(harnessName: string) {
+  const safe = harnessName.replace(/[^\w.-]+/g, '-').replace(/^[-.]+|-+$/g, '')
+  return `${safe || 'harness'}-media`
+}
diff --git a/packages/ai-harness-cli/src/commands.ts b/packages/ai-harness-cli/src/commands.ts
index e78eb69852..34a7390945 100644
--- a/packages/ai-harness-cli/src/commands.ts
+++ b/packages/ai-harness-cli/src/commands.ts
@@ -1,4 +1,5 @@
-import type { HarnessSession } from '@tanstack/ai-harness'
+import { attach } from './attach'
+import type { HarnessSession, UserInput } from '@tanstack/ai-harness'
 
 export const HELP_TEXT = [
   'Type a message and press Enter. While the agent works, a new message steers it.',
@@ -83,7 +84,9 @@ export type LineResult =
 
 /**
  * Handle one line of user input: a slash command, a steer while a turn runs,
- * or a new prompt. Used by the line mode, and by any UI that calls it.
+ * or a new prompt. Used by the line mode, and by any UI that calls it. A
+ * prompt or a steer sends each `@path` file (relative to the working folder)
+ * with it. A command and an answer do not.
  */
 export async function handleLine(
   session: HarnessSession,
@@ -106,8 +109,18 @@ export async function handleLine(
     }
   }
   if (!text.startsWith('/')) {
-    if (session.snapshot().status === 'running') await session.steer(text)
-    else void session.prompt(text)
+    let input: UserInput
+    try {
+      input = await attach(session, text, { cwd: process.cwd() })
+    } catch (error) {
+      // A file that cannot go (a type it does not know, too big) stops the send.
+      return {
+        type: 'notice',
+        text: error instanceof Error ? error.message : String(error),
+      }
+    }
+    if (session.snapshot().status === 'running') await session.steer(input)
+    else void session.prompt(input)
     return { type: 'sent' }
   }
   const [name = '', ...rest] = text.slice(1).split(' ')
diff --git a/packages/ai-harness-cli/src/index.ts b/packages/ai-harness-cli/src/index.ts
index b2ef38b820..ac057e0a99 100644
--- a/packages/ai-harness-cli/src/index.ts
+++ b/packages/ai-harness-cli/src/index.ts
@@ -1,11 +1,17 @@
 import { createHarnessHost } from '@tanstack/ai-harness'
 import { createSessionView } from '@tanstack/ai-harness/view'
 import { USAGE, parseCliArgs } from './args'
+import { attach, defaultMediaDir } from './attach'
 import { runLines } from './lines'
 import { EXIT, runPrint } from './print'
 import { createToken, serve } from './serve'
-import type { AnyHarness, HarnessPersistence } from '@tanstack/ai-harness'
-import type { SessionView } from '@tanstack/ai-harness/view'
+import type {
+  AnyHarness,
+  HarnessPersistence,
+  HarnessSession,
+  UserInput,
+} from '@tanstack/ai-harness'
+import type { SessionView, SessionViewSource } from '@tanstack/ai-harness/view'
 
 export interface RunCliOptions {
   /** Where sessions keep state. Default: in memory. */
@@ -20,10 +26,43 @@ export interface RunCliOptions {
    * Your own screen for an interactive terminal, with any UI library. It gets
    * a ready session view and resolves when the user quits. Piped input and
    * the other modes (`--print`, `--acp`, `--mcp`, `--serve`, `--dashboard`) do not use it.
+   * `view.send(text)` sends each `@path` file in `text`, as line mode does.
    */
   ui?: (view: SessionView) => Promise<void> | void
 }
 
+/**
+ * The session for a `ui` view: a typed message or steer sends its `@path`
+ * files, as in line mode.
+ */
+function attachingSource(session: HarnessSession) {
+  const withFiles = (message: UserInput) =>
+    typeof message === 'string'
+      ? attach(session, message, { cwd: process.cwd() })
+      : Promise.resolve(message)
+  const source: SessionViewSource = {
+    // The view shows a failed operation from its events, so only a file that
+    // cannot go rejects here. It becomes an error notice in the view.
+    prompt: (message) =>
+      withFiles(message).then((input) => {
+        session.prompt(input).then(undefined, () => {})
+      }),
+    steer: async (message) => session.steer(await withFiles(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(),
+    mediaUrl: (id) => session.mediaUrl(id),
+    loadMedia: (id) => session.loadMedia(id),
+  }
+  return source
+}
+
 /**
  * Run a harness from the terminal. Resolves to the process exit code.
  *
@@ -88,6 +127,8 @@ export async function runCli(
         harness,
         threadId: args.thread,
         approvals,
+        // A local client can attach the files of the working folder by path.
+        filePaths: [process.cwd()],
       })
       // stdout carries only MCP messages. The server stops when stdin ends.
       const ended = new Promise<void>((resolve) => {
@@ -153,15 +194,18 @@ export async function runCli(
     }
 
     const session = await host.open(harness, { threadId: args.thread })
+    // Relative to the working folder, as a relative --media-dir is.
+    const mediaDir = args.mediaDir ?? defaultMediaDir(harness.name)
     if (args.print !== undefined) {
       return await runPrint(session, args.print, {
         output: args.output,
         stdout,
         stderr,
+        mediaDir,
       })
     }
     if (stdin.isTTY && options.ui) {
-      const view = createSessionView(session)
+      const view = createSessionView(attachingSource(session))
       try {
         await view.ready
         await options.ui(view)
@@ -171,6 +215,7 @@ export async function runCli(
     } else {
       await runLines(session, stdin, stdout, {
         openSignIns: Boolean(stdin.isTTY),
+        mediaDir,
       })
     }
     return EXIT.ok
diff --git a/packages/ai-harness-cli/src/lines.ts b/packages/ai-harness-cli/src/lines.ts
index a245db0c0b..a4d940dc87 100644
--- a/packages/ai-harness-cli/src/lines.ts
+++ b/packages/ai-harness-cli/src/lines.ts
@@ -1,5 +1,6 @@
 import { createInterface } from 'node:readline'
 import { createSessionView } from '@tanstack/ai-harness/view'
+import { saveMediaLine } from './attach'
 import { handleLine } from './commands'
 import { createPrinter } from './printer'
 import { approvalQuestion, openUrl, resolveAll, waitIdle } from './session-view'
@@ -15,15 +16,23 @@ interface Output {
  * next line answers it (`y` approves, anything else rejects).
  *
  * `openSignIns`: open sign-in links in the browser (for an interactive terminal).
+ * `mediaDir`: the folder for the media a turn makes. Each new file is saved
+ * there, with one `[image saved: <path>]` line.
  */
 export async function runLines(
   session: HarnessSession,
   input: NodeJS.ReadableStream,
   stdout: Output,
-  options: { openSignIns?: boolean } = {},
+  options: { openSignIns?: boolean; mediaDir: string },
 ) {
   const view = createSessionView(session)
-  const printer = createPrinter((text) => stdout.write(text))
+  const saves: Array<Promise<unknown>> = []
+  const printer = createPrinter((text) => stdout.write(text), {
+    onMedia: (part) => {
+      const saved = saveMediaLine(session, part, options.mediaDir)
+      saves.push(saved.then(({ text }) => printer.line(text)))
+    },
+  })
   await view.ready
   // Line mode prints only what happens from now on.
   printer.mark(view.store.get())
@@ -65,6 +74,7 @@ export async function runLines(
   stopOpening()
   printing.unsubscribe()
   printer.print(view.store.get())
+  await Promise.allSettled(saves)
   view.dispose()
   printer.end()
 }
diff --git a/packages/ai-harness-cli/src/print.ts b/packages/ai-harness-cli/src/print.ts
index fbb8ac271d..c5c06d2b16 100644
--- a/packages/ai-harness-cli/src/print.ts
+++ b/packages/ai-harness-cli/src/print.ts
@@ -1,4 +1,6 @@
 import { EventType } from '@tanstack/ai'
+import { HARNESS_EVENTS, isMediaRecord } from '@tanstack/ai-harness'
+import { attach, saveMediaLine } from './attach'
 import type { HarnessSession } from '@tanstack/ai-harness'
 
 export const EXIT = {
@@ -14,17 +16,44 @@ interface Output {
 
 /**
  * Run one prompt and print it. `text` prints the answer as it streams.
- * `ndjson` prints every AG-UI event as one JSON line.
+ * `ndjson` prints every AG-UI event as one JSON line. Each `@path` file in
+ * the prompt goes with it.
+ *
+ * Each media file the turn makes is saved into `mediaDir`. `ndjson` adds the
+ * saved `path` to the value of its `harness.media` event. `text` prints the
+ * saved line to stderr, so stdout keeps only the answer.
  */
 export async function runPrint(
   session: HarnessSession,
   prompt: string,
-  options: { output: 'text' | 'ndjson'; stdout: Output; stderr: Output },
-): Promise<number> {
+  options: {
+    output: 'text' | 'ndjson'
+    stdout: Output
+    stderr: Output
+    mediaDir: string
+  },
+) {
   const { stdout, stderr } = options
-  const operation = session.prompt(prompt)
+  const input = await attach(session, prompt, { cwd: process.cwd() })
+  const operation = session.prompt(input)
   for await (const chunk of operation.stream()) {
-    if (options.output === 'ndjson') {
+    const media =
+      chunk.type === EventType.CUSTOM &&
+      chunk.name === HARNESS_EVENTS.media &&
+      isMediaRecord(chunk.value)
+        ? chunk.value
+        : undefined
+    if (media !== undefined) {
+      const saved = await saveMediaLine(session, media, options.mediaDir)
+      if (options.output === 'text' || saved.path === undefined) {
+        stderr.write(`${saved.text}\n`)
+      }
+      if (options.output === 'ndjson') {
+        // A file that was not saved has no `path`: JSON drops `undefined`.
+        const value = { ...media, path: saved.path }
+        stdout.write(`${JSON.stringify({ ...chunk, value })}\n`)
+      }
+    } else if (options.output === 'ndjson') {
       stdout.write(`${JSON.stringify(chunk)}\n`)
     } else if (
       chunk.type === EventType.TEXT_MESSAGE_CONTENT &&
diff --git a/packages/ai-harness-cli/src/printer.ts b/packages/ai-harness-cli/src/printer.ts
index 8b4c892721..ead061f8ad 100644
--- a/packages/ai-harness-cli/src/printer.ts
+++ b/packages/ai-harness-cli/src/printer.ts
@@ -1,13 +1,24 @@
 import { shortAnswer, signInText } from './session-view'
-import type { AgentPart, SessionViewState } from '@tanstack/ai-harness/view'
+import type {
+  AgentPart,
+  MediaPart,
+  SessionViewState,
+  ViewPart,
+} from '@tanstack/ai-harness/view'
 
 /**
  * Prints a session view as lines: streamed text as it grows, and one
  * bracketed line per tool call, child agent, notice, question, and sign-in.
  * Notices that line mode prints itself (command results, rejected inputs,
  * and UI notes) are skipped.
+ *
+ * Media parts print nothing here. `onMedia` gets each new media part of an
+ * assistant message once, from the lead or from a child at any depth.
  */
-export function createPrinter(write: (text: string) => unknown) {
+export function createPrinter(
+  write: (text: string) => unknown,
+  options: { onMedia?: (part: MediaPart) => void } = {},
+) {
   const done = new Set<string>()
   const written = new Map<string, number>()
   // True while streamed text has no line break at its end yet.
@@ -57,6 +68,14 @@ export function createPrinter(write: (text: string) => unknown) {
     if (part.status === 'failed')
       once(`${key}:end`, `agent ${part.name} failed: ${part.error ?? ''}`)
   }
+  const media = (parts: ReadonlyArray<ViewPart>) => {
+    for (const part of parts) {
+      if (part.type === 'agent') media(part.parts)
+      if (part.type !== 'media' || done.has(`media:${part.id}`)) continue
+      done.add(`media:${part.id}`)
+      if (!marking) options.onMedia?.(part)
+    }
+  }
   const print = (state: SessionViewState) => {
     for (const message of state.messages) {
       if (message.role === 'notice') {
@@ -71,6 +90,7 @@ export function createPrinter(write: (text: string) => unknown) {
         if (part.type === 'tool-call') once(key, `tool ${part.name}`)
         if (part.type === 'agent') agent(key, part)
       })
+      media(message.parts)
     }
     for (const question of state.questions)
       once(`question:${question.id}`, `? ${question.message}`)
diff --git a/packages/ai-harness-cli/tests/attach.test.ts b/packages/ai-harness-cli/tests/attach.test.ts
new file mode 100644
index 0000000000..1f0aaea15b
--- /dev/null
+++ b/packages/ai-harness-cli/tests/attach.test.ts
@@ -0,0 +1,208 @@
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest'
+import {
+  createHarnessHost,
+  defineHarness,
+  mediaIdOf,
+} from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { attach, defaultMediaDir, saveMedia } from '../src/attach'
+import type { AnyTextAdapter } from '@tanstack/ai'
+import type {
+  HarnessHost,
+  HarnessSession,
+  UserInput,
+} from '@tanstack/ai-harness'
+
+// The real file system, with spies, so a test can see which files are read.
+vi.mock('node:fs/promises', { spy: true })
+
+/** A model that is never called: these tests only store and save files. */
+function idleModel(): AnyTextAdapter {
+  return {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    // `~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,
+    },
+    chatStream: () => {
+      throw new Error('The model must not be called.')
+    },
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+  }
+}
+
+/** The part that `attach` makes for a stored PNG. */
+const pngPart = {
+  type: 'image',
+  source: {
+    type: 'url',
+    value: expect.stringMatching(/^harness-media:./),
+    mimeType: 'image/png',
+  },
+}
+
+let dir = ''
+let host: HarnessHost
+let session: HarnessSession
+
+beforeAll(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'harness-attach-'))
+  await writeFile(join(dir, 'cat.png'), 'hello')
+  await writeFile(join(dir, 'my cat.png'), 'meow')
+  await writeFile(join(dir, 'notes.xyz'), 'plain')
+  await mkdir(join(dir, 'folder.png'))
+  host = createHarnessHost({ persistence: memoryPersistence() })
+  session = await host.open(
+    defineHarness({ name: 'test/attach', adapter: idleModel() }),
+    { threadId: 't' },
+  )
+})
+
+afterAll(async () => {
+  await host.close()
+  await rm(dir, { recursive: true, force: true })
+})
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+/** The name and text of each stored file that `input` sends. */
+async function storedFiles(input: UserInput) {
+  const parts = typeof input === 'string' ? [] : input
+  const ids = parts.flatMap((part) => mediaIdOf(part) ?? [])
+  return Promise.all(
+    ids.map(async (id) => ({
+      name: (await session.getMedia(id))?.name,
+      text: new TextDecoder().decode(await session.loadMedia(id)),
+    })),
+  )
+}
+
+describe('attach', () => {
+  it('sends a file token as a media part and takes the token out of the text', async () => {
+    const input = await attach(session, 'what is wrong in @cat.png today', {
+      cwd: dir,
+    })
+
+    expect(input).toEqual([
+      { type: 'text', content: 'what is wrong in today' },
+      pngPart,
+    ])
+    expect(await storedFiles(input)).toEqual([
+      { name: 'cat.png', text: 'hello' },
+    ])
+  })
+
+  it('reads a quoted path with spaces', async () => {
+    const input = await attach(session, 'look at @"my cat.png"', { cwd: dir })
+
+    expect(input).toEqual([{ type: 'text', content: 'look at' }, pngPart])
+    expect(await storedFiles(input)).toEqual([
+      { name: 'my cat.png', text: 'meow' },
+    ])
+  })
+
+  it('sends no text part for a message that is only a file', async () => {
+    expect(await attach(session, '@cat.png', { cwd: dir })).toEqual([pngPart])
+  })
+
+  it('keeps an email and a package name as text, and reads no file for the email', async () => {
+    const email = 'write to me@acme.dev'
+    const packageName = 'install @types/node first'
+
+    expect(await attach(session, email, { cwd: dir })).toBe(email)
+    expect(stat).not.toHaveBeenCalled()
+    expect(readFile).not.toHaveBeenCalled()
+    expect(await attach(session, packageName, { cwd: dir })).toBe(packageName)
+    // A token that can be a path is looked up, so the spy above sees reads.
+    expect(stat).toHaveBeenCalled()
+  })
+
+  it.each([
+    ['a missing file', 'see @missing.png now'],
+    ['a folder', 'see @folder.png now'],
+  ])('keeps %s as text', async (_label, text) => {
+    expect(await attach(session, text, { cwd: dir })).toBe(text)
+  })
+
+  it('refuses a file of a type it does not know', async () => {
+    await expect(
+      attach(session, 'read @notes.xyz', { cwd: dir }),
+    ).rejects.toThrow(
+      'Cannot attach notes.xyz: the file type is not known. To send the path as text, remove the @.',
+    )
+  })
+})
+
+describe('saveMedia', () => {
+  it('makes the folder and adds a number instead of overwriting a file', async () => {
+    const record = await session.putMedia(new TextEncoder().encode('hello'), {
+      mimeType: 'image/png',
+      name: 'cat.png',
+    })
+    const out = join(dir, 'saved', 'media')
+
+    const paths = [
+      await saveMedia(session, record, out),
+      await saveMedia(session, record, out),
+      await saveMedia(session, record, out),
+    ]
+
+    expect(paths).toEqual([
+      join(out, 'cat.png'),
+      join(out, 'cat-1.png'),
+      join(out, 'cat-2.png'),
+    ])
+    expect(await readFile(join(out, 'cat-2.png'), 'utf8')).toBe('hello')
+  })
+
+  it.each(['../escaped.png', 'sub/escaped.png', 'sub\\escaped.png', '..'])(
+    'refuses the name %s',
+    async (name) => {
+      const record = await session.putMedia(new TextEncoder().encode('x'), {
+        mimeType: 'image/png',
+        name,
+      })
+      const out = join(dir, 'refused')
+
+      await expect(saveMedia(session, record, out)).rejects.toThrow(
+        'it is not a plain file name',
+      )
+      await expect(stat(join(dir, 'escaped.png'))).rejects.toThrow()
+    },
+  )
+})
+
+describe('defaultMediaDir', () => {
+  it.each([
+    ['acme/coder', 'acme-coder-media'],
+    ['@acme/coder', 'acme-coder-media'],
+  ])('saves the media of %s into %s', (name, folder) => {
+    expect(defaultMediaDir(name)).toBe(folder)
+  })
+})
diff --git a/packages/ai-harness-cli/tests/child-view.test.ts b/packages/ai-harness-cli/tests/child-view.test.ts
index 046e355427..f06771b9fa 100644
--- a/packages/ai-harness-cli/tests/child-view.test.ts
+++ b/packages/ai-harness-cli/tests/child-view.test.ts
@@ -1,3 +1,5 @@
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { PassThrough } from 'node:stream'
 import { describe, expect, it } from 'vitest'
 import { z } from 'zod'
@@ -119,9 +121,13 @@ describe('line mode with a child agent', () => {
     )
     const input = new PassThrough()
     let out = ''
-    const running = runLines(session, input, {
-      write: (text: string) => (out += text),
-    })
+    // This turn makes no media, so nothing is written to the media folder.
+    const running = runLines(
+      session,
+      input,
+      { write: (text: string) => (out += text) },
+      { mediaDir: join(tmpdir(), 'child-view-media') },
+    )
     input.end('go\n')
     await running
     await host.close()
diff --git a/packages/ai-harness-cli/tests/cli-media.test.ts b/packages/ai-harness-cli/tests/cli-media.test.ts
new file mode 100644
index 0000000000..5cce9b5142
--- /dev/null
+++ b/packages/ai-harness-cli/tests/cli-media.test.ts
@@ -0,0 +1,323 @@
+import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Readable } from 'node:stream'
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
+import { EventType, defineAgent } from '@tanstack/ai'
+import { defineHarness } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { EXIT, runCli } from '../src'
+import type { AnyTextAdapter, ImageAdapter, StreamChunk } from '@tanstack/ai'
+
+// ponytail: `textTurn`, `toolTurn`, `scripted`, `capture`, and `stdinFrom`
+// repeat the ones in cli.test.ts. Move them to a helpers file when a third
+// test file needs them.
+const now = () => Date.now()
+const textTurn = (text: string): Array<StreamChunk> => [
+  { type: EventType.RUN_STARTED, runId: 'r', threadId: 't', timestamp: now() },
+  {
+    type: EventType.TEXT_MESSAGE_START,
+    messageId: 'm',
+    role: 'assistant',
+    timestamp: now(),
+  },
+  {
+    type: EventType.TEXT_MESSAGE_CONTENT,
+    messageId: 'm',
+    delta: text,
+    timestamp: now(),
+  },
+  { type: EventType.TEXT_MESSAGE_END, messageId: 'm', timestamp: now() },
+  {
+    type: EventType.RUN_FINISHED,
+    runId: 'r',
+    threadId: 't',
+    timestamp: now(),
+    metadata: { tanstack: { finishReason: 'stop' } },
+  },
+]
+const toolTurn = (name: string, args: string): Array<StreamChunk> => [
+  { type: EventType.RUN_STARTED, runId: 'r', threadId: 't', timestamp: now() },
+  {
+    type: EventType.TOOL_CALL_START,
+    toolCallId: 'call_1',
+    toolCallName: name,
+    timestamp: now(),
+  },
+  {
+    type: EventType.TOOL_CALL_ARGS,
+    toolCallId: 'call_1',
+    delta: args,
+    timestamp: now(),
+  },
+  { type: EventType.TOOL_CALL_END, toolCallId: 'call_1', timestamp: now() },
+  {
+    type: EventType.RUN_FINISHED,
+    runId: 'r',
+    threadId: 't',
+    timestamp: now(),
+    metadata: { tanstack: { finishReason: 'tool_calls' } },
+  },
+]
+
+function scripted(turns: Array<Array<StreamChunk>>) {
+  let call = 0
+  const seen: Array<Array<{ role: string; content: unknown }>> = []
+  const adapter: AnyTextAdapter = {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    // `~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,
+    },
+    chatStream: (options) => {
+      seen.push(options.messages)
+      const chunks = turns[call] ?? textTurn('')
+      call += 1
+      return (async function* () {
+        yield* chunks
+      })()
+    },
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+  }
+  return { adapter, seen }
+}
+
+function capture() {
+  let text = ''
+  return {
+    write: (chunk: string) => (text += chunk),
+    get text() {
+      return text
+    },
+  }
+}
+
+/** A stdin that reads `lines`, as a terminal or as a pipe. */
+function stdinFrom(lines: Array<string>, { isTTY }: { isTTY: boolean }) {
+  // NodeJS.ReadStream is a TTY socket. A test cannot make one without a real
+  // terminal, and runCli only reads the lines and `isTTY`, so this casts.
+  return Object.assign(Readable.from(lines), {
+    isTTY,
+  }) as unknown as NodeJS.ReadStream
+}
+
+/** An image model that paints the bytes "hello". */
+function imageAdapter(): ImageAdapter<string> {
+  return {
+    kind: 'image',
+    name: 'fake-image',
+    model: 'fake-image-model',
+    '~types': {
+      providerOptions: {},
+      modelProviderOptionsByName: {},
+      modelSizeByName: {},
+      modelInputModalitiesByName: {},
+    },
+    // 'aGVsbG8=' is base64 for "hello".
+    generateImages: async () => ({
+      id: 'image-1',
+      model: 'fake-image-model',
+      images: [{ b64Json: 'aGVsbG8=' }],
+    }),
+  }
+}
+
+const painter = defineAgent({
+  name: 'painter',
+  description: 'Paints',
+  run: async (ctx) => {
+    await ctx.generateImage({ adapter: imageAdapter(), prompt: 'a cat' })
+    return 'painted'
+  },
+})
+
+/**
+ * Run a harness whose lead calls the painter once, then answers, with
+ * `argv` and the piped `lines`. Gives the exit code and the output.
+ */
+async function paint(argv: Array<string>, lines: Array<string> = []) {
+  const { adapter } = scripted([
+    toolTurn('painter', '{}'),
+    textTurn('Here is your cat.'),
+  ])
+  const harness = defineHarness({
+    name: 'test/painting',
+    adapter,
+    subagents: { agents: [painter] },
+  })
+  const stdout = capture()
+  const stderr = capture()
+  const code = await runCli(harness, {
+    argv,
+    stdin: stdinFrom(lines, { isTTY: false }),
+    stdout,
+    stderr,
+    persistence: memoryPersistence(),
+  })
+  return { code, stdout: stdout.text, stderr: stderr.text }
+}
+
+let root = ''
+
+beforeAll(async () => {
+  root = await mkdtemp(join(tmpdir(), 'harness-cli-media-'))
+  await writeFile(join(root, 'cat.png'), 'hello')
+  await writeFile(join(root, 'notes.xyz'), 'plain')
+})
+
+afterAll(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+/** A prompt that sends cat.png by its full path, quoted for spaces. */
+const aboutCat = () => `what is @"${join(root, 'cat.png')}"`
+
+/** What the model sees for `aboutCat()`: the text, then the bytes. */
+const seenAboutCat = [
+  { type: 'text', content: 'what is' },
+  {
+    type: 'image',
+    source: { type: 'data', value: 'aGVsbG8=', mimeType: 'image/png' },
+  },
+]
+
+/** The one file in `dir`, as its path and its text. */
+async function onlyFile(dir: string) {
+  const names = await readdir(dir)
+  expect(names).toHaveLength(1)
+  const path = join(dir, names[0] ?? '')
+  return { path, text: await readFile(path, 'utf8') }
+}
+
+describe('media in line mode', () => {
+  it('saves a new image into the media folder once and prints where', async () => {
+    const mediaDir = join(root, 'lines')
+
+    const { code, stdout } = await paint(
+      ['--media-dir', mediaDir],
+      ['paint a cat\n'],
+    )
+
+    expect(code).toBe(EXIT.ok)
+    const saved = await onlyFile(mediaDir)
+    expect(saved.text).toBe('hello')
+    expect(stdout).toContain(`[image saved: ${saved.path}]\n`)
+    expect(stdout).toContain('Here is your cat.')
+  })
+
+  it('prints why a file cannot go, and does not call the model', async () => {
+    const { adapter, seen } = scripted([])
+    const stdout = capture()
+
+    await runCli(defineHarness({ name: 'test/media-refused', adapter }), {
+      argv: [],
+      stdin: stdinFrom([`read @"${join(root, 'notes.xyz')}"\n`], {
+        isTTY: false,
+      }),
+      stdout,
+      stderr: capture(),
+      persistence: memoryPersistence(),
+    })
+
+    expect(stdout.text).toContain(
+      'Cannot attach notes.xyz: the file type is not known.',
+    )
+    expect(seen).toHaveLength(0)
+  })
+})
+
+describe('media in print mode', () => {
+  it('prints the media event with the saved path in ndjson', async () => {
+    const mediaDir = join(root, 'ndjson')
+
+    const { stdout } = await paint([
+      '-p',
+      'paint a cat',
+      '--output',
+      'ndjson',
+      '--media-dir',
+      mediaDir,
+    ])
+
+    const saved = await onlyFile(mediaDir)
+    const media = stdout
+      .trim()
+      .split('\n')
+      .map((line) => JSON.parse(line))
+      .filter((event) => event.name === 'harness.media')
+    expect(media).toEqual([
+      expect.objectContaining({
+        type: 'CUSTOM',
+        value: expect.objectContaining({
+          kind: 'image',
+          source: 'generated',
+          size: 5,
+          path: saved.path,
+        }),
+      }),
+    ])
+  })
+
+  it('prints the saved line to stderr and only the answer to stdout', async () => {
+    const mediaDir = join(root, 'text')
+
+    const { code, stdout, stderr } = await paint([
+      '-p',
+      'paint a cat',
+      '--media-dir',
+      mediaDir,
+    ])
+
+    expect(code).toBe(EXIT.ok)
+    const saved = await onlyFile(mediaDir)
+    expect(stdout).toBe('Here is your cat.\n')
+    expect(stderr).toBe(`[image saved: ${saved.path}]\n`)
+  })
+
+  it('sends an @file to the model as data', async () => {
+    const { adapter, seen } = scripted([textTurn('A cat.')])
+
+    const code = await runCli(defineHarness({ name: 'test/attach', adapter }), {
+      argv: ['-p', aboutCat()],
+      stdout: capture(),
+      stderr: capture(),
+      persistence: memoryPersistence(),
+    })
+
+    expect(code).toBe(EXIT.ok)
+    expect(seen[0]?.at(-1)?.content).toEqual(seenAboutCat)
+  })
+})
+
+describe('media in a custom ui', () => {
+  it('sends an @file of view.send to the model', async () => {
+    const { adapter, seen } = scripted([textTurn('A cat.')])
+
+    await runCli(defineHarness({ name: 'test/ui-attach', adapter }), {
+      argv: [],
+      stdin: stdinFrom([], { isTTY: true }),
+      stdout: capture(),
+      stderr: capture(),
+      persistence: memoryPersistence(),
+      ui: async (view) => {
+        await view.send(aboutCat())
+        await vi.waitFor(() => expect(seen).toHaveLength(1))
+      },
+    })
+
+    expect(seen[0]?.at(-1)?.content).toEqual(seenAboutCat)
+  })
+})
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index 3db6e68777..6ae1431c6f 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -98,6 +98,7 @@ export {
   mediaIdOf,
   mediaOfMessage,
   mediaPart,
+  mimeTypeOf,
 } from './media-ref'
 
 export { MediaError } from './media'
diff --git a/packages/ai-harness/src/media-ref.ts b/packages/ai-harness/src/media-ref.ts
index 5e83ac15d2..b3806cecad 100644
--- a/packages/ai-harness/src/media-ref.ts
+++ b/packages/ai-harness/src/media-ref.ts
@@ -76,6 +76,44 @@ export function kindOf(mimeType: string) {
   }
 }
 
+// ponytail: common types only. Send any other file with its MIME type.
+const mimeTypes = new Map([
+  ['png', 'image/png'],
+  ['jpg', 'image/jpeg'],
+  ['jpeg', 'image/jpeg'],
+  ['gif', 'image/gif'],
+  ['webp', 'image/webp'],
+  ['mp3', 'audio/mpeg'],
+  ['wav', 'audio/wav'],
+  ['ogg', 'audio/ogg'],
+  ['m4a', 'audio/mp4'],
+  ['flac', 'audio/flac'],
+  ['mp4', 'video/mp4'],
+  ['webm', 'video/webm'],
+  ['mov', 'video/quicktime'],
+  ['pdf', 'application/pdf'],
+  ['txt', 'text/plain'],
+  ['md', 'text/markdown'],
+  ['csv', 'text/csv'],
+  ['html', 'text/html'],
+])
+
+/**
+ * The MIME type of a file name, a path, or a URL path, by its extension.
+ * Returns `undefined` for no extension or an extension it does not know.
+ * It knows the common image, audio, video, PDF, and text types.
+ *
+ * @example
+ * mimeTypeOf('cat.PNG') // 'image/png'
+ * mimeTypeOf('notes') // undefined
+ */
+export function mimeTypeOf(fileName: string) {
+  const extension = /\.([^./\\]+)$/.exec(fileName)?.[1]
+  return extension === undefined
+    ? undefined
+    : mimeTypes.get(extension.toLowerCase())
+}
+
 /**
  * The content part that sends a stored media file to a turn. Its source is
  * the URL `harness-media:<id>`. The harness swaps it for the bytes only when
diff --git a/packages/ai-mcp/src/harness.ts b/packages/ai-mcp/src/harness.ts
index eacf38174c..3a048208c4 100644
--- a/packages/ai-mcp/src/harness.ts
+++ b/packages/ai-mcp/src/harness.ts
@@ -9,6 +9,7 @@ import {
   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.
@@ -79,28 +80,6 @@ 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
 
-// ponytail: common types only. Send any other file as data with its mimeType.
-const mimeTypes = new Map([
-  ['png', 'image/png'],
-  ['jpg', 'image/jpeg'],
-  ['jpeg', 'image/jpeg'],
-  ['gif', 'image/gif'],
-  ['webp', 'image/webp'],
-  ['mp3', 'audio/mpeg'],
-  ['wav', 'audio/wav'],
-  ['ogg', 'audio/ogg'],
-  ['m4a', 'audio/mp4'],
-  ['flac', 'audio/flac'],
-  ['mp4', 'video/mp4'],
-  ['webm', 'video/webm'],
-  ['mov', 'video/quicktime'],
-  ['pdf', 'application/pdf'],
-  ['txt', 'text/plain'],
-  ['md', 'text/markdown'],
-  ['csv', 'text/csv'],
-  ['html', 'text/html'],
-])
-
 const threadIdSchema: JSONSchema = {
   type: 'string',
   description:
@@ -719,14 +698,6 @@ function urlPart(attachment: { url: string; mimeType?: string }) {
   return part
 }
 
-/** The MIME type of a file name or URL path by its extension, or `undefined`. */
-function mimeTypeOf(path: string) {
-  const extension = /\.([^./\\]+)$/.exec(path)?.[1]
-  return extension === undefined
-    ? undefined
-    : mimeTypes.get(extension.toLowerCase())
-}
-
 /** The media records that the settled `operation` published, in order. */
 async function mediaOf(operation: Operation<unknown>) {
   const records: Array<MediaRecord> = []
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/src/routes/api.harness-protocol.$.ts b/testing/e2e/src/routes/api.harness-protocol.$.ts
index 727e618a92..214f6bb3db 100644
--- a/testing/e2e/src/routes/api.harness-protocol.$.ts
+++ b/testing/e2e/src/routes/api.harness-protocol.$.ts
@@ -11,26 +11,39 @@ import {
 import { todos } from '@tanstack/ai-harness/plugins'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { z } from 'zod'
+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.
+ * 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.
  */
-const hosts = new Map<string, ReturnType<typeof createHarnessHost>>()
+// 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() })
 
 function handlerFor(request: Request) {
   const testId = request.headers.get('x-test-id') ?? 'default'
   const port = Number(request.headers.get('x-aimock-port') ?? '4010')
-  let host = hosts.get(testId)
-  if (!host) {
-    host = createHarnessHost({ persistence: memoryPersistence() })
-    hosts.set(testId, host)
-  }
+  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.'
+    },
+  })
   const harness = defineHarness({
     name: 'e2e/protocol',
     adapter: createTextAdapter('openai', undefined, port, testId).adapter,
+    subagents: { agents: [painter] },
     agents: [
       defineAgent({
         name: 'echo',
@@ -68,6 +81,9 @@ function handlerFor(request: Request) {
       req.headers.get('authorization') === 'Bearer e2e-token'
         ? { id: 'e2e' }
         : null,
+    // Each request makes a new handler, so a fixed secret keeps a signed URL
+    // working on the next request.
+    mediaSecret: 'e2e-media-secret',
   })
 }
 
diff --git a/testing/e2e/tests/harness-media.spec.ts b/testing/e2e/tests/harness-media.spec.ts
new file mode 100644
index 0000000000..449ba9ef24
--- /dev/null
+++ b/testing/e2e/tests/harness-media.spec.ts
@@ -0,0 +1,174 @@
+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,
+        runId: 'client-run',
+        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)
+  })
+})

From 44dfbe85db8266e77874a666b259ddc0a162fed8 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 29 Sep 2026 13:17:35 +0200
Subject: [PATCH 063/286] docs(harness): send and show media; example keeps
 agent media

A new page, "Send and show media", covers uploads, signed URLs, media from agents, limits, and the stores. The custom UI, CLI, MCP server, connect, and subagents pages show the media parts, @path attachments, the media folder, MCP attachments, and media links. The example lets the harness keep its images and videos, uses stream: true for video, and shows media lines in the Ink screen.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 docs/config.json                    |  17 +-
 docs/harness/cli.md                 |  27 +++
 docs/harness/connect.md             |   8 +-
 docs/harness/custom-ui.md           |  68 +++++++
 docs/harness/mcp-server.md          |  29 ++-
 docs/harness/media.md               | 278 ++++++++++++++++++++++++++++
 docs/harness/subagents.md           |   2 +
 examples/harness-cli/.gitignore     |   2 +
 examples/harness-cli/README.md      |   3 +-
 examples/harness-cli/src/harness.ts |  11 +-
 examples/harness-cli/src/media.ts   | 104 ++++-------
 examples/harness-cli/src/tui.tsx    | 194 +++++++++++++++----
 12 files changed, 622 insertions(+), 121 deletions(-)
 create mode 100644 docs/harness/media.md

diff --git a/docs/config.json b/docs/config.json
index b43bb68369..e8e81c4154 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -875,13 +875,19 @@
         {
           "label": "Connect clients",
           "to": "harness/connect",
-          "addedAt": "2026-09-26"
+          "addedAt": "2026-09-26",
+          "updatedAt": "2026-09-29"
+        },
+        {
+          "label": "Send and show media",
+          "to": "harness/media",
+          "addedAt": "2026-09-29"
         },
         {
           "label": "Run in the terminal",
           "to": "harness/cli",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-09-28"
+          "updatedAt": "2026-09-29"
         },
         {
           "label": "Durable sessions",
@@ -914,7 +920,8 @@
         {
           "label": "Use from any MCP client",
           "to": "harness/mcp-server",
-          "addedAt": "2026-09-28"
+          "addedAt": "2026-09-28",
+          "updatedAt": "2026-09-29"
         },
         {
           "label": "Code mode in a harness",
@@ -935,13 +942,13 @@
           "label": "Build your own UI",
           "to": "harness/custom-ui",
           "addedAt": "2026-09-28",
-          "updatedAt": "2026-09-28"
+          "updatedAt": "2026-09-29"
         },
         {
           "label": "Run agents from a harness",
           "to": "harness/subagents",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-09-28"
+          "updatedAt": "2026-09-29"
         },
         {
           "label": "Deploy a harness",
diff --git a/docs/harness/cli.md b/docs/harness/cli.md
index cc45a4f81b..1aecb74cfa 100644
--- a/docs/harness/cli.md
+++ b/docs/harness/cli.md
@@ -87,6 +87,32 @@ For the running work:
 
 Plugin commands (for example `/model` or `/todos`) show up in `/help`. When a turn stops for an approval or a plugin asks a question, type your answer. For yes-or-no questions, `y` approves and `n` refuses.
 
+## Send files and save media
+
+To send a file with a message, write `@` and the path of the file:
+
+```text
+what is wrong in @./bug.png
+compare @"old logo.png" with @./new-logo.png
+```
+
+- The path is relative to the working folder. Put quotes around a path with spaces.
+- `@path` works in line mode, with `-p`, with piped input, and in your own `ui`.
+- A `@word` that is not a file stays in the text, for example `@types/node`.
+- If the CLI does not know the type of the file, it does not send the message. To send the path as text, remove the `@`.
+
+The CLI saves the media that a turn makes in a folder. The default folder is `./<harness name>-media` in the working folder, for example `./acme-assistant-media`. To use another folder, add `--media-dir <dir>`:
+
+```bash
+npx tsx cli.ts -p "Draw a logo for acme" --media-dir ./out
+```
+
+- Line mode prints `[image saved: <path>]` for each file.
+- `-p` prints the same line on stderr, so stdout keeps only the answer.
+- `-p --output ndjson` adds the saved `path` to the value of the `harness.media` event.
+
+The CLI never replaces a file. If the name is taken, it adds `-1`, `-2`, and so on to the new name.
+
 ## Run your own screen
 
 Line mode prints plain lines. For a full screen with your own layout, pass `ui` to `runCli`. It works with any TUI library, for example Ink, OpenTUI, or blessed.
@@ -116,5 +142,6 @@ For a full Ink screen with approvals, questions, sign-ins, and child agents, cop
 
 - One entry file that runs your harness as a terminal app, a script step, an editor agent, an MCP server, or an HTTP server.
 - Your own terminal screen on the same session, with any TUI library.
+- Files that you send with `@path`, and a folder with the media that your agents make.
 
 Next: keep long turns alive through crashes with [durable sessions](./durable-sessions).
diff --git a/docs/harness/connect.md b/docs/harness/connect.md
index f38633fb99..2173bd9ebc 100644
--- a/docs/harness/connect.md
+++ b/docs/harness/connect.md
@@ -44,7 +44,7 @@ export const handler = createHarnessHandler({
 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. Any AG-UI client works.
+- `POST run`: standard AG-UI. One request runs one prompt and streams it as SSE. Any AG-UI client works. The prompt keeps every content part of the last user message, for example an image.
 - `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.
 - `GET snapshot?threadId=`: the status, running operations, and waiting approvals.
@@ -74,6 +74,8 @@ for await (const entry of client.events()) {
 
 `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).
+
 ## Use a WebSocket
 
 For one connection that carries events and inputs, authorize the upgrade, then hand the socket to `handleHarnessSocket`:
@@ -99,7 +101,7 @@ import { serveAcp } from '@tanstack/ai-acp/agent'
 serveAcp({ host, harness: assistant })
 ```
 
-Tool approvals become permission requests in the editor. ACP v2 is still a draft, so this API is experimental.
+Tool approvals become permission requests in the editor. Image blocks, audio blocks, and embedded files in a prompt go to the media store of the session. ACP v2 is still a draft, so this API is experimental.
 
 ## Use it as the model of another chat
 
@@ -116,7 +118,7 @@ const stream = chat({
 })
 ```
 
-Each outer thread gets its own inner session, so the harness keeps its own history.
+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.
 
 ## What you have now
 
diff --git a/docs/harness/custom-ui.md b/docs/harness/custom-ui.md
index aeedae39de..d243cde990 100644
--- a/docs/harness/custom-ui.md
+++ b/docs/harness/custom-ui.md
@@ -142,6 +142,7 @@ 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`.
+- `media`: a file that an agent made. See [Show media](#show-media).
 
 A notice has a `kind`:
 
@@ -195,6 +196,72 @@ Progress:
 
 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 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`.
+
 ## 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. A plugin can export a selector that checks the shape of its state for you.
@@ -316,3 +383,4 @@ export function Chat() {
 - 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.
 - 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/mcp-server.md b/docs/harness/mcp-server.md
index ff0af7099e..852852ff3a 100644
--- a/docs/harness/mcp-server.md
+++ b/docs/harness/mcp-server.md
@@ -64,7 +64,7 @@ Ask the client to use the harness, for example: "Ask assistant to summarize my o
 
 To talk to the harness:
 
-- `chat`: send a message and wait for the answer. While a turn runs, the message waits in the queue.
+- `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.
@@ -156,6 +156,31 @@ To approve every tool call without a question, start the CLI with `--yes`. Use i
 
 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" }]
+}
+```
+
+With `--mcp`, the server can read the files in its working folder. Over HTTP (`/mcp`), the server 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 MCP over HTTP
 
 If `@tanstack/ai-mcp` is installed, `--serve` also serves the MCP server at `/mcp`. The route uses the same bearer token as the other routes:
@@ -204,6 +229,7 @@ Mount `handleMcp` on a route, for example `/mcp`. The options are:
 
 - `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`.
 
 For a process that a client starts, serve the same server on stdio:
@@ -220,5 +246,6 @@ serveMCPStdio(server)
 - 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.
 
 Next: put the harness on a server with [Deploy a harness](./deploy).
diff --git a/docs/harness/media.md b/docs/harness/media.md
new file mode 100644
index 0000000000..5fd2b1de17
--- /dev/null
+++ b/docs/harness/media.md
@@ -0,0 +1,278 @@
+---
+title: Send and show media
+id: harness-media
+order: 2
+description: "Send images, audio, video, and documents to a harness turn, and show the media that your agents make. Upload from a web app, show files with signed URLs, and set limits."
+keywords:
+  - tanstack ai
+  - harness
+  - media
+  - upload
+  - signed url
+  - images
+---
+
+Your users want to send a photo, a voice note, or a PDF with a message. Your agents make images and videos, and your UI must show them. The harness saves both in one media store for each thread.
+
+A message holds only a small reference to a file. The harness gives the bytes to the model only at the model call, so the transcript stays small.
+
+At the end of this page, a web app uploads a photo, sends it with a prompt, and shows the images that your agents make.
+
+## 1. Serve media from your handler
+
+`createHarnessHandler` serves the media routes next to the other routes. Set `mediaSecret` to sign media URLs:
+
+```ts group=harness-media-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-astra'),
+})
+
+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),
+  mediaSecret: process.env.MEDIA_SECRET,
+})
+```
+
+The handler adds these routes:
+
+- `POST media?threadId=&name=`: saves the raw request body as a file of the thread. The `Content-Type` header gives its type. The answer is the media record.
+- `GET media-url?threadId=&id=`: gives `{ path, expiresAt }`, a signed path to the file. The path works for 1 hour.
+- `GET media?threadId=&id=&exp=&sig=`: gives the bytes, with `Range` support for video. A request with a good signature does not need `authorize`, so the URL works in `<img>`, `<audio>`, and `<video>`.
+
+The handler refuses a request with one of these codes:
+
+- `413`: the file is bigger than the size limit.
+- `415`: the harness does not take files of this type.
+- `403`: the signature is bad, or the URL expired.
+
+Without `mediaSecret`, the handler signs with a random key. Then a signed URL does not work after a restart. It also does not work when you make a new handler for each request. Use the same secret on every server behind one URL.
+
+Each media answer has `X-Content-Type-Options: nosniff` and a sandbox `Content-Security-Policy`. So an HTML or text file cannot run as a page of your site.
+
+## 2. Upload a file and send it
+
+`client.upload` saves a file in the media store of the thread and gives back its record. `mediaPart(record)` makes the content part that sends the file:
+
+```ts group=harness-media-client
+import { createHarnessClient, mediaPart } 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' },
+})
+
+export async function askAboutPhoto(file: File) {
+  const photo = await client.upload(file, { name: file.name, mimeType: file.type })
+  await client.prompt([{ type: 'text', content: 'What is in this photo?' }, mediaPart(photo)])
+}
+```
+
+- `upload` takes a `File`, a `Blob`, an `ArrayBuffer`, or a `Uint8Array`.
+- If the handler refuses the file, `upload` throws, for example `Harness upload failed (413): The file is bigger than the limit of 104857600 bytes.`
+- The transcript keeps a `harness-media:<id>` URL for the file. Only the model call gets the bytes.
+
+With a [session view](./custom-ui), give the records to `send`: `view.send('What is in this photo?', [photo])`.
+
+## 3. Show the media
+
+Each media part of a session view has a `url`. The view gets a signed URL for each part, and gets a new one before it expires. This component shows one part:
+
+```tsx
+import type { MediaPart } from '@tanstack/ai-harness/view'
+
+export 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>
+  )
+}
+```
+
+`url` is `undefined` until the view has the first signed URL, so the component shows the name first. To find the media parts in the messages, see [Show media](./custom-ui#show-media).
+
+Open your page, upload a photo, and ask about it. The answer streams in. Each image that an agent makes shows in the message.
+
+## Send a file from code
+
+On a server or in a script, a session saves a file with `putMedia`:
+
+```ts group=harness-media-code
+import { readFile } from 'node:fs/promises'
+import { createHarnessHost, defineHarness, mediaPart } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { openaiText } from '@tanstack/ai-openai'
+
+const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-6-astra'),
+})
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+const session = await host.open(assistant, { threadId: 'thread-1' })
+
+const scan = await session.putMedia(await readFile('./receipt.png'), {
+  mimeType: 'image/png',
+  name: 'receipt.png',
+})
+const turn = await session.prompt([
+  { type: 'text', content: 'What is the total on this receipt?' },
+  mediaPart(scan),
+])
+console.log(turn.text)
+```
+
+If the harness refuses the file, `putMedia` throws a `MediaError`. Its `status` is `413` or `415`, the same as the HTTP routes.
+
+The session also has:
+
+- `getMedia(id)`: the record, or `null` when the thread has no file with this id.
+- `loadMedia(id, range?)`: the bytes, or one range of them.
+- `mediaUrl(id)`: a data URL for a file up to 1 MB. A session has no server, so a bigger file has no URL. Use `loadMedia` for it.
+
+## Media that agents make
+
+The harness saves the result of each of these calls in an agent. You do not change the agent code:
+
+- `ctx.generateImage`
+- `ctx.generateSpeech`
+- `ctx.generateAudio`
+- `ctx.generateVideo` with `stream: true`
+
+Without `stream: true`, `ctx.generateVideo` only starts a job, and the harness does not save the video.
+
+```ts group=harness-media-agents
+import { defineAgent } from '@tanstack/ai'
+import { defineHarness } from '@tanstack/ai-harness'
+import { openaiImage, openaiText, openaiVideo } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+const illustrator = defineAgent({
+  name: 'illustrator',
+  description: 'Draws an image from a prompt',
+  inputSchema: z.object({ prompt: z.string() }),
+  run: (ctx) =>
+    ctx.generateImage({
+      adapter: openaiImage('gpt-image-2.5-flare'),
+      prompt: ctx.input.prompt,
+    }),
+})
+
+const animator = defineAgent({
+  name: 'animator',
+  description: 'Makes a short video from a prompt',
+  inputSchema: z.object({ prompt: z.string() }),
+  run: (ctx) =>
+    ctx.generateVideo({
+      adapter: openaiVideo('sora-2'),
+      prompt: ctx.input.prompt,
+      stream: true,
+    }),
+})
+
+export const studio = defineHarness({
+  name: 'acme/studio',
+  adapter: openaiText('gpt-6-astra'),
+  subagents: { agents: [illustrator, animator] },
+})
+```
+
+For each saved file, the turn publishes a `harness.media` event (`HARNESS_EVENTS.media`). Its value is the media record:
+
+```ts group=harness-media-agents
+import { HARNESS_EVENTS, createHarnessHost, isMediaRecord } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+const session = await host.open(studio, { threadId: 'thread-1' })
+
+const turn = session.prompt('Draw a lighthouse at night.')
+for await (const { event } of turn.events()) {
+  if (event.type === 'CUSTOM' && event.name === HARNESS_EVENTS.media && isMediaRecord(event.value)) {
+    console.log(`${event.value.kind} saved: ${event.value.name}`)
+  }
+}
+```
+
+A media record has:
+
+- `kind`, `mimeType`, `name`, and `size`: the file.
+- `source`: `'user'` for a file that a user sent, and `'generated'` for a file that an agent made.
+- `runId` and `subagentRunId`: the turn and the child agent run that made the file.
+
+At the end of a turn, the harness adds its records to the last assistant message, in `metadata.harness.media`. So the media comes back after a restart. Read the records with `mediaOfMessage(message)`. A failed or cancelled turn keeps its media in the store only.
+
+- If the harness cannot save a file, the agent still gets its result. The turn publishes a `harness.plugin.warning` event.
+- An agent that you run from code (`session.agents`, or `ctx.agents` in a plugin) also saves its media and publishes the event. This media is not added to the transcript.
+
+## Limit files, and choose what the model reads
+
+Set the `media` option on `defineHarness`:
+
+```ts
+import { defineHarness } from '@tanstack/ai-harness'
+import { openaiText, openaiTranscription } from '@tanstack/ai-openai'
+
+export const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-6-astra'),
+  media: {
+    maxBytes: 20 * 1024 * 1024,
+    kinds: ['image', 'audio'],
+    transcribe: openaiTranscription('gpt-4o-transcribe'),
+  },
+})
+```
+
+- `maxBytes`: the biggest file that a user can send. Default 100 MB.
+- `kinds`: the kinds of file that a user can send: `image`, `audio`, `video`, and `document` (a PDF or a text file). Default: all four.
+- `accepts`: the kinds that the model reads. It narrows the list that the adapter gives.
+- `transcribe`: a transcription adapter. Audio that the model cannot read becomes text before the model call.
+
+These adapters know what their model reads: OpenAI, Anthropic, Gemini, Mistral, Groq, BytePlus, Grok, OpenRouter, and LLM Gateway. Other adapters, for example Ollama and your own adapters, do not know. For them, set `accepts`. If the harness knows neither list, it sends every file to the model.
+
+If the model cannot read a file, the turn stops before the model call. For example, `gpt-6-astra` reads text and images. Without `transcribe`, an audio file gives this error:
+
+```text
+gpt-6-astra cannot read audio files. Add media.transcribe, or send a text summary.
+```
+
+In a child agent, `ctx.chat` gets the bytes of the files too. There, only `accepts` limits the kinds, because the harness does not know the adapter of the child.
+
+## Keep media across restarts
+
+The host keeps media in three stores of its persistence:
+
+- `artifacts`: the media records.
+- `blobs`: the bytes.
+- `generationRuns`: the runs that made the generated media.
+
+If a store is missing, the host keeps media in memory. `memoryPersistence()` has all three, but in memory only. To keep media across restarts, give the host these stores on your own database. See [Keep generated files](../persistence/keep-generated-files).
+
+## What you have now
+
+- Files that users upload from a web app and send with a prompt.
+- Signed URLs that work in `<img>`, `<audio>`, and `<video>`.
+- Media from your agents, saved and shown with no change to the agent code.
+- Limits, and a clear error when the model cannot read a file.
+
+Next: show media in your own screen with [Build your own UI](./custom-ui#show-media).
diff --git a/docs/harness/subagents.md b/docs/harness/subagents.md
index 0e33a72367..adb79e6170 100644
--- a/docs/harness/subagents.md
+++ b/docs/harness/subagents.md
@@ -64,6 +64,8 @@ export const review = definePlugin({
 
 To track usage or apply a policy in each of these runs, see [Middleware in every agent](./plugins#middleware-in-every-agent).
 
+The harness saves the images, audio, and video that these agents make, and the UI shows them. See [Media that agents make](./media#media-that-agents-make).
+
 ## Call a harness as a child
 
 `harnessAgent` turns a harness into an agent. Put it in `subagents.agents`, and the main model calls it as a tool. The child harness keeps its own tools, plugins, and history.
diff --git a/examples/harness-cli/.gitignore b/examples/harness-cli/.gitignore
index d3d132daa7..dbf9171399 100644
--- a/examples/harness-cli/.gitignore
+++ b/examples/harness-cli/.gitignore
@@ -1,4 +1,6 @@
 .env
 playground/media/
+# Media the CLI saves (the default --media-dir).
+example-coder-media/
 # Marker the sandbox writes into the workspace.
 playground/.tanstack-projected-*
diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index 692962f920..ee73c6229b 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -38,7 +38,8 @@ echo '/agent haiku {"topic":"rain"}' | pnpm --filter harness-cli-example start
 
 1. Run `/connect notion`. Approve the consent page that opens in the browser. Do the same with `/connect linear`.
 2. Ask: `find my latest Linear issue, look for a related Notion page, then make an image and a short video about it`.
-3. The files land in `playground/media`.
+3. The harness keeps each file. The CLI saves it in `example-coder-media` and prints `[image saved: <path>]`. Change the folder with `--media-dir <dir>`.
+4. To send a file, put `@` before its path: `describe @./playground/cat.png`.
 
 - Sign-ins are kept in `~/.tanstack-harness-example/credentials.json`, so you sign in once. `/disconnect notion` deletes one.
 - Images use `OPENAI_API_KEY`. Videos use Grok Imagine when `XAI_API_KEY` is set, and OpenAI Sora when it is not.
diff --git a/examples/harness-cli/src/harness.ts b/examples/harness-cli/src/harness.ts
index 6cb9e04f2a..bb0a3563cc 100644
--- a/examples/harness-cli/src/harness.ts
+++ b/examples/harness-cli/src/harness.ts
@@ -32,7 +32,6 @@ import type { AnyTextAdapter } from '@tanstack/ai'
 
 // The agent works in ./playground, so it cannot touch the rest of your disk.
 const root = fileURLToPath(new URL('../playground', import.meta.url))
-const mediaDir = fileURLToPath(new URL('../playground/media', import.meta.url))
 
 /** Without an API key, a stand-in model that explains how to add one. */
 function demoModel(): AnyTextAdapter {
@@ -133,14 +132,14 @@ const haiku = defineAgent({
 })
 
 // The model calls the media agents as tools. Images use OpenAI. Videos use
-// Grok Imagine when XAI_API_KEY is set, else OpenAI Sora.
+// Grok Imagine when XAI_API_KEY is set, else OpenAI Sora. The harness keeps
+// each file they make.
 const media = process.env.OPENAI_API_KEY
   ? [
-      imageAgent(mediaDir),
+      imageAgent,
       videoAgent(
-        mediaDir,
         process.env.XAI_API_KEY
-          ? grokVideo('grok-imagine-video')
+          ? grokVideo('grok-imagine-video-1.5')
           : openaiVideo('sora-2'),
       ),
     ]
@@ -210,7 +209,7 @@ export const assistant = defineHarness({
   adapter: main,
   systemPrompts: [
     'You are a careful coding agent. Read files before you edit them. Keep answers short.',
-    'You can read Notion and Linear when they are connected, and make images and videos with the image and video tools. Media files are saved under ./playground/media.',
+    'You can read Notion and Linear when they are connected, and make images and videos with the image and video tools. The user gets each file you make.',
   ],
   agents: [haiku],
   subagents: { agents: media },
diff --git a/examples/harness-cli/src/media.ts b/examples/harness-cli/src/media.ts
index 40b9329ae0..49969b02d8 100644
--- a/examples/harness-cli/src/media.ts
+++ b/examples/harness-cli/src/media.ts
@@ -1,62 +1,41 @@
-import { mkdir, writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
-import { defineAgent, getVideoJobStatus } from '@tanstack/ai'
+import { EventType, defineAgent } from '@tanstack/ai'
 import { openaiImage } from '@tanstack/ai-openai'
 import { z } from 'zod'
 import type { AnyVideoAdapter } from '@tanstack/ai'
 
-/** A short file name from a prompt: `a-fox-in-the-snow-1714000000000`. */
-function fileName(prompt: string): string {
-  const slug = prompt
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-|-$/g, '')
-    .slice(0, 40)
-  return `${slug || 'media'}-${Date.now()}`
-}
-
-async function download(url: string): Promise<Buffer> {
-  const response = await fetch(url)
-  if (!response.ok) throw new Error(`Download failed (${response.status}).`)
-  return Buffer.from(await response.arrayBuffer())
-}
-
-/** Makes an image with OpenAI and saves it as a PNG in `mediaDir`. */
-export function imageAgent(mediaDir: string) {
-  return defineAgent({
-    name: 'image',
-    description:
-      'Generates one image from a detailed visual prompt and saves it as a PNG file. Returns the file path.',
-    produces: 'image',
-    inputSchema: z.object({
-      prompt: z.string().describe('A detailed description of the image'),
-    }),
-    run: async (ctx) => {
-      const result = await ctx.generateImage({
-        adapter: openaiImage('gpt-image-2'),
-        prompt: ctx.input.prompt,
-        size: '1024x1024',
-      })
-      const image = result.images[0]
-      if (!image) throw new Error('The image model returned no image.')
-      let bytes: Buffer
-      if (image.b64Json) bytes = Buffer.from(image.b64Json, 'base64')
-      else if (image.url) bytes = await download(image.url)
-      else throw new Error('The image model returned no image data.')
-      await mkdir(mediaDir, { recursive: true })
-      const path = join(mediaDir, `${fileName(ctx.input.prompt)}.png`)
-      await writeFile(path, bytes)
-      return { saved: path, model: result.model }
-    },
-  })
-}
+/**
+ * Makes an image with OpenAI. The harness keeps the file and publishes a
+ * `harness.media` event, so the screen can show it and save it.
+ */
+export const imageAgent = defineAgent({
+  name: 'image',
+  description:
+    'Generates one image from a detailed visual prompt. The user gets the image.',
+  produces: 'image',
+  inputSchema: z.object({
+    prompt: z.string().describe('A detailed description of the image'),
+  }),
+  run: async (ctx) => {
+    const result = await ctx.generateImage({
+      adapter: openaiImage('gpt-image-2.5-flare'),
+      prompt: ctx.input.prompt,
+      size: '1024x1024',
+    })
+    if (result.images.length === 0)
+      throw new Error('The image model returned no image.')
+    return `Made the image with ${result.model}. The user has it.`
+  },
+})
 
-/** Makes a short video with `adapter` and saves it as an MP4 in `mediaDir`. */
-export function videoAgent(mediaDir: string, adapter: AnyVideoAdapter) {
+/**
+ * Makes a short video with `adapter`. The harness keeps only streamed video,
+ * so this uses `stream: true`: one stream from the job start to the file.
+ */
+export function videoAgent(adapter: AnyVideoAdapter) {
   return defineAgent({
     name: 'video',
     description:
-      'Generates one short video clip from a detailed visual prompt and saves it as an MP4 file. Takes a minute or two. Returns the file path.',
+      'Generates one short video clip from a detailed visual prompt. Takes a minute or two. The user gets the video.',
     produces: 'video',
     inputSchema: z.object({
       prompt: z
@@ -64,27 +43,16 @@ export function videoAgent(mediaDir: string, adapter: AnyVideoAdapter) {
         .describe('A detailed description of the scene and the motion'),
     }),
     run: async (ctx) => {
-      const { jobId } = await ctx.generateVideo({
+      const stream = ctx.generateVideo({
         adapter,
         prompt: ctx.input.prompt,
+        stream: true,
       })
-      // Video models work in the background, so poll until the job is done.
-      const deadline = Date.now() + 10 * 60_000
-      let url: string | undefined
-      while (!url) {
-        if (ctx.abortSignal?.aborted) throw new Error('Stopped.')
-        if (Date.now() > deadline)
-          throw new Error('The video took longer than 10 minutes.')
-        await new Promise((resolve) => setTimeout(resolve, 4000))
-        const status = await getVideoJobStatus({ adapter, jobId })
-        if (status.status === 'failed')
-          throw new Error(status.error ?? 'The video job failed.')
-        if (status.status === 'completed') url = status.url
+      for await (const chunk of stream) {
+        // The stream reports a failed or stopped job as an event, not a throw.
+        if (chunk.type === EventType.RUN_ERROR) throw new Error(chunk.message)
       }
-      await mkdir(mediaDir, { recursive: true })
-      const path = join(mediaDir, `${fileName(ctx.input.prompt)}.mp4`)
-      await writeFile(path, await download(url))
-      return { saved: path, model: adapter.model }
+      return `Made the video with ${adapter.model}. The user has it.`
     },
   })
 }
diff --git a/examples/harness-cli/src/tui.tsx b/examples/harness-cli/src/tui.tsx
index 3a75571b3f..81348483dd 100644
--- a/examples/harness-cli/src/tui.tsx
+++ b/examples/harness-cli/src/tui.tsx
@@ -1,14 +1,82 @@
 import { spawn } from 'node:child_process'
-import { useState } from 'react'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import { useEffect, useState } from 'react'
 import { Box, Text, render, useApp, useInput } from 'ink'
 import { useSelector } from '@tanstack/react-store'
 import { selectGoal } from '@tanstack/ai-harness/plugins'
+import { assistant } from './harness'
 import type {
+  AgentPart,
+  MediaPart,
   SessionView,
   ViewMessage,
   ViewPart,
 } from '@tanstack/ai-harness/view'
 
+/** Where each media file is saved or why not, by media id. */
+type MediaNotes = ReadonlyMap<string, string>
+
+// ponytail: the CLI's default media folder, `./<harness-name>-media`. A custom
+// ui gets no `--media-dir`, and the CLI does not export `defaultMediaDir`, so
+// this copies its rule. The media id in front of the name keeps names unique.
+const mediaDir = `${assistant.name.replace(/[^\w.-]+/g, '-').replace(/^[-.]+|-+$/g, '')}-media`
+
+/** Write the bytes of a media file into `mediaDir`, and return the path. */
+async function saveMedia(part: MediaPart) {
+  await mkdir(mediaDir, { recursive: true })
+  const path = join(mediaDir, `${part.id}-${basename(part.name)}`)
+  await writeFile(path, await part.load())
+  return path
+}
+
+/** Add the media parts of `parts` to `into`, also the ones of child agents. */
+function collectMedia(parts: ReadonlyArray<ViewPart>, into: Array<MediaPart>) {
+  for (const part of parts) {
+    if (part.type === 'media') into.push(part)
+    if (part.type === 'agent') collectMedia(part.parts, into)
+  }
+}
+
+/** The media files that the agents made, from the assistant messages. */
+function generatedMedia(messages: ReadonlyArray<ViewMessage>) {
+  const media: Array<MediaPart> = []
+  for (const message of messages) {
+    if (message.role === 'assistant') collectMedia(message.parts, media)
+  }
+  return media
+}
+
+/**
+ * Save each new media file once, and keep a note per file: the path, or why
+ * it was not saved. Files in the history when the screen opens are not saved
+ * again.
+ */
+function useSavedMedia(view: SessionView, messages: Array<ViewMessage>) {
+  const [notes, setNotes] = useState(() => new Map<string, string>())
+  const [seen] = useState(
+    () =>
+      new Set(generatedMedia(view.store.get().messages).map((part) => part.id)),
+  )
+  useEffect(() => {
+    const media = generatedMedia(messages)
+    for (const part of media) {
+      if (seen.has(part.id)) continue
+      seen.add(part.id)
+      const note = (text: string) =>
+        setNotes((current) => new Map(current).set(part.id, text))
+      saveMedia(part).then(
+        (path) => note(`saved: ${path}`),
+        (error: unknown) =>
+          note(
+            `not saved: ${error instanceof Error ? error.message : String(error)}`,
+          ),
+      )
+    }
+  }, [messages, seen])
+  return notes
+}
+
 function textOf(parts: ReadonlyArray<ViewPart>) {
   return parts.map((part) => (part.type === 'text' ? part.text : '')).join('')
 }
@@ -30,50 +98,100 @@ function openInBrowser(url: string) {
   child.unref()
 }
 
-function Part({ part }: { part: ViewPart }) {
-  if (part.type === 'text') return <Text>{part.text}</Text>
-  if (part.type === 'reasoning') return <Text dimColor>{part.text}</Text>
-  if (part.type === 'tool-call') {
-    const note =
-      part.status === 'needs-approval'
-        ? ' (waits for approval)'
-        : part.status === 'failed'
-          ? ' (failed)'
-          : ''
-    return <Text color="yellow">{`  - tool ${part.name}${note}`}</Text>
-  }
-  // A child agent, for example Claude Code or Codex, with its own tool calls.
+/** One line for a media file an agent made: kind, name, and where it went. */
+function MediaLine({
+  part,
+  notes,
+  indent,
+}: {
+  part: MediaPart
+  notes: MediaNotes
+  indent: string
+}) {
+  const note = notes.get(part.id)
+  return (
+    <Text color="green">
+      {`${indent}- ${part.kind} ${part.name}${note ? ` (${note})` : ''}`}
+    </Text>
+  )
+}
+
+/** A child agent, for example Claude Code or Codex, with its tool calls and media. */
+function Agent({ part, notes }: { part: AgentPart; notes: MediaNotes }) {
   const latest = textOf(part.parts).replace(/\s+/g, ' ').trim().slice(-80)
   return (
     <Box flexDirection="column">
       <Text color="magenta">
         {`  - agent ${part.name} (${part.status})${latest ? `: ${latest}` : ''}`}
       </Text>
-      {part.parts.map((inner, index) =>
-        inner.type === 'tool-call' ? (
-          <Text key={index} color="yellow">{`    - tool ${inner.name}`}</Text>
-        ) : null,
-      )}
+      {part.parts.map((inner, index) => {
+        if (inner.type === 'tool-call')
+          return (
+            <Text key={index} color="yellow">{`    - tool ${inner.name}`}</Text>
+          )
+        if (inner.type === 'media')
+          return (
+            <MediaLine key={index} part={inner} notes={notes} indent="    " />
+          )
+        return null
+      })}
     </Box>
   )
 }
 
-function Message({ message }: { message: ViewMessage }) {
-  if (message.role === 'user')
-    return <Text color="cyan">{`> ${message.text}`}</Text>
-  if (message.role === 'notice')
-    return (
-      <Text color={message.kind === 'error' ? 'red' : 'gray'}>
-        {message.text}
-      </Text>
-    )
-  return (
-    <Box flexDirection="column">
-      {message.parts.map((part, index) => (
-        <Part key={index} part={part} />
-      ))}
-    </Box>
-  )
+function Part({ part, notes }: { part: ViewPart; notes: MediaNotes }) {
+  switch (part.type) {
+    case 'text':
+      return <Text>{part.text}</Text>
+    case 'reasoning':
+      return <Text dimColor>{part.text}</Text>
+    case 'tool-call': {
+      const note =
+        part.status === 'needs-approval'
+          ? ' (waits for approval)'
+          : part.status === 'failed'
+            ? ' (failed)'
+            : ''
+      return <Text color="yellow">{`  - tool ${part.name}${note}`}</Text>
+    }
+    case 'agent':
+      return <Agent part={part} notes={notes} />
+    case 'media':
+      return <MediaLine part={part} notes={notes} indent="  " />
+  }
+}
+
+function Message({
+  message,
+  notes,
+}: {
+  message: ViewMessage
+  notes: MediaNotes
+}) {
+  switch (message.role) {
+    case 'user': {
+      // The files the user sent go after the text: `[image cat.png]`.
+      const files = (message.media ?? []).map(
+        (part) => `[${part.kind} ${part.name}]`,
+      )
+      const line = [message.text, ...files].filter((text) => text !== '')
+      return <Text color="cyan">{`> ${line.join(' ')}`}</Text>
+    }
+    case 'notice':
+      return (
+        <Text color={message.kind === 'error' ? 'red' : 'gray'}>
+          {message.text}
+        </Text>
+      )
+    case 'assistant':
+      return (
+        <Box flexDirection="column">
+          {message.parts.map((part, index) => (
+            <Part key={index} part={part} notes={notes} />
+          ))}
+        </Box>
+      )
+  }
 }
 
 function Status({ view }: { view: SessionView }) {
@@ -144,6 +262,7 @@ async function submit(view: SessionView, line: string, exit: () => void) {
 function App({ view }: { view: SessionView }) {
   const { exit } = useApp()
   const messages = useSelector(view.store, (state) => state.messages)
+  const notes = useSavedMedia(view, messages)
   const [input, setInput] = useState('')
   useInput((character, key) => {
     if (key.escape) {
@@ -165,7 +284,7 @@ function App({ view }: { view: SessionView }) {
   return (
     <Box flexDirection="column">
       {messages.slice(-200).map((message) => (
-        <Message key={message.id} message={message} />
+        <Message key={message.id} message={message} notes={notes} />
       ))}
       <Status view={view} />
       <Text>
@@ -179,7 +298,8 @@ function App({ view }: { view: SessionView }) {
 
 /**
  * The Ink screen for `runCli({ ui })`. It opens sign-in links in the browser,
- * and resolves when the user types /exit or presses Ctrl+C.
+ * saves the media the agents make into `./<harness-name>-media`, and resolves
+ * when the user types /exit or presses Ctrl+C.
  */
 export async function runTui(view: SessionView) {
   view.on('signIn', (signIn) => {

From fc24c4cfdf1a34260c1a8dc719c791e684d59a95 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 29 Sep 2026 13:26:38 +0200
Subject: [PATCH 064/286] chore: changeset for harness media

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/harness-media.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
 create mode 100644 .changeset/harness-media.md

diff --git a/.changeset/harness-media.md b/.changeset/harness-media.md
new file mode 100644
index 0000000000..5151e0647d
--- /dev/null
+++ b/.changeset/harness-media.md
@@ -0,0 +1,14 @@
+---
+'@tanstack/ai-harness': minor
+'@tanstack/ai-harness-cli': minor
+'@tanstack/ai-mcp': minor
+'@tanstack/ai-acp': minor
+---
+
+`@tanstack/ai-harness`: a harness turn can take images, audio, video, and documents, and the harness keeps the media that agents make. Sessions have `putMedia`, `getMedia`, `loadMedia`, and `mediaUrl`, and `mediaPart(record)` sends a stored file with a prompt. The transcript keeps a small `harness-media:<id>` URL, and only the model call gets the bytes. Every `ctx.generateImage`, `ctx.generateSpeech`, `ctx.generateAudio`, and `ctx.generateVideo({ stream: true })` result is saved and published as a `harness.media` event, and the records are saved on the message for history. `defineHarness({ media })` sets `maxBytes`, `kinds`, `accepts`, and `transcribe`, and a file the model cannot read stops the turn with a clear error. `createHarnessHandler` serves uploads, signed media URLs (`mediaSecret`), and file bytes with Range support. The browser client has `upload`, `mediaUrl`, and `loadMedia`, and the session view has media parts and `view.send(text, attachments)`.
+
+`@tanstack/ai-harness-cli`: `@path` in a message attaches a file. Generated media is saved to `./<harness-name>-media` (`--media-dir` to change it), and `--mcp` lets path attachments read the working folder.
+
+`@tanstack/ai-mcp`: the harness MCP server's `chat` tool takes `path`, `url`, and `data` attachments (`filePaths` sets the folders a path may read). Results carry the media of the turn: small images and audio inline, other files as `harness-media://` links that `resources/read` serves.
+
+`@tanstack/ai-acp`: the ACP agent takes image, audio, and resource blocks, and advertises its prompt capabilities.

From 10f008d57199ce9663e224e7d7ab649c48145e4d Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 29 Sep 2026 16:47:56 +0200
Subject: [PATCH 065/286] feat(examples/harness-cli): voice input, every media
 kind, a model picker across providers, and local Claude Code and Codex

The example is now an open-code style terminal agent that shows what the harness does out of the box:

- Voice: Ctrl+R records the microphone with ffmpeg, the transcript is sent, and spoken file names ("fox dot png", "the last image") are attached. /mic picks the microphone, a silent recording is not sent, and /voice sends a recorded file.
- Media agents: images (with the images you send as references), speech, video (Grok Imagine or Sora), and songs and sound effects through fal. The screen numbers and saves each file, and /open and /play show them.
- /model switches between gpt, claude, and grok models by the keys you have.
- Claude Code and Codex turn on when their CLIs are on the PATH, with your own logins. Codex uses the model and sandbox_mode of ~/.codex/config.toml. The screen shows each agent's output.
- Audio files you send become text for models that cannot read audio (media.transcribe).

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 examples/harness-cli/.env.example   |  17 +-
 examples/harness-cli/README.md      |  84 +++--
 examples/harness-cli/package.json   |   1 +
 examples/harness-cli/src/cli.ts     |   8 +-
 examples/harness-cli/src/harness.ts | 201 ++++++++----
 examples/harness-cli/src/media.ts   | 161 +++++++++-
 examples/harness-cli/src/store.ts   |  20 ++
 examples/harness-cli/src/tui.tsx    | 481 +++++++++++++++++++++-------
 examples/harness-cli/src/voice.ts   | 278 ++++++++++++++++
 pnpm-lock.yaml                      |   3 +
 10 files changed, 1028 insertions(+), 226 deletions(-)
 create mode 100644 examples/harness-cli/src/store.ts
 create mode 100644 examples/harness-cli/src/voice.ts

diff --git a/examples/harness-cli/.env.example b/examples/harness-cli/.env.example
index 38405cac10..0f9cd2f0c5 100644
--- a/examples/harness-cli/.env.example
+++ b/examples/harness-cli/.env.example
@@ -1,11 +1,20 @@
 # Copy to .env. Without keys, a demo model answers.
-# The main model: OpenAI first, then Anthropic.
-# OPENAI_API_KEY also turns on the image and video tools.
+# Each key adds models to /model, and turns on the tools of that provider.
+# OpenAI: the gpt models, images, speech, Sora video, and voice input.
 OPENAI_API_KEY=
+# Anthropic: the claude models.
 ANTHROPIC_API_KEY=
-# Optional: make videos with Grok Imagine instead of OpenAI Sora.
+# xAI: the grok model, and video with Grok Imagine (it wins over Sora).
 XAI_API_KEY=
-# Optional: hand coding work to Claude Code and Codex (uses claude login and codex login).
+# fal: songs and sound effects.
+FAL_KEY=
+# Claude Code and Codex turn on when `claude` and `codex` are on the PATH.
+# They use your own `claude login` and `codex login`. Set 0 to turn them off.
 CODING_AGENTS=
+# Codex uses the model and sandbox_mode of ~/.codex/config.toml. These win.
 CODEX_MODEL=
 CODEX_SANDBOX_MODE=
+# Voice input records the microphone with ffmpeg.
+FFMPEG_PATH=
+VOICE_DEVICE=
+VOICE_MIN_LOUDNESS=
diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index ee73c6229b..637dd4d5cf 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -1,6 +1,6 @@
 # Harness CLI example
 
-A small coding agent in your terminal, built with `@tanstack/ai-harness`. It reads and edits files in `./playground`, asks before it writes a file or runs a command, keeps a todo list, and can switch models. It can also read Notion and Linear, and make images and videos.
+A coding agent in your terminal, built with `@tanstack/ai-harness`. Talk to it or type. It edits files in `./playground`, makes images, video, speech, songs, and sound effects, reads Notion and Linear, and hands coding work to your local Claude Code and Codex.
 
 ## Run it
 
@@ -8,58 +8,76 @@ From the repo root:
 
 1. `pnpm install`
 2. `pnpm build:all` (the example uses the local packages)
-3. Copy `.env.example` to `.env` and set `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`. Without a key, a demo model answers.
+3. Copy `.env.example` to `.env` and set the keys you have. Each key turns on more (see the table). Without a key, a demo model answers.
 4. `pnpm --filter harness-cli-example start`
 
-Try these:
+| Key | Adds |
+|---|---|
+| `OPENAI_API_KEY` | the `gpt` models, images, speech, Sora video, and voice input |
+| `ANTHROPIC_API_KEY` | the `claude` models |
+| `XAI_API_KEY` | the `grok` model, and video with Grok Imagine |
+| `FAL_KEY` | songs and sound effects |
 
-- `create hello.txt with a short poem`: the agent asks before `write_file`. Type `y`.
-- `/mode plan`, then ask for another file: the write is refused.
-- `/todos`, `/usage`, `/model fast`
-- `/goal create a file hello.txt that says hi`: the agent keeps working until the model says the goal is met. `/goal` shows the status.
-- Press Esc to stop a long answer. Type while it works to steer it.
+## Talk to it
+
+1. Press Ctrl+R and speak.
+2. Press Ctrl+R (or Enter) again. The screen shows what it heard, and sends it.
 
-## The terminal screen
+- Name a file, and it is sent too: "describe fox dot png", "use cat.png as a reference".
+- Say "the last image" (or video, song) for the last file the agent made: "make a pencil sketch of the last image".
+- Say "Hey, run a Codex agent that adds a test": Codex runs, and the screen shows its output.
+- `/mic` lists the microphones, and `/mic 3` records from the third one. A recording with only silence is not sent.
+- `/voice note.m4a` sends a voice message that you recorded before.
 
-In a terminal, `start` shows an Ink screen. The screen is `src/tui.tsx`, and `src/cli.ts` gives it to `runCli` as `ui`. It is plain example code on `createSessionView`, so copy it and change it.
+Voice needs `ffmpeg` on the PATH, and `OPENAI_API_KEY` or `XAI_API_KEY` for the transcript.
 
-- It shows the messages, tool calls, child agents, approvals, questions, sign-ins, the goal, and the status.
-- It has `/help`, `/connect <id>`, `/disconnect <id>`, and `/exit`. Other commands, for example `/todos`, go to the plugins.
-- It opens sign-in links in the browser.
+## Make media
 
-Piped input uses line mode. Line mode also has `/agents` and `/agent <name> [json]`, which runs a typed agent in the background:
+Ask in words. The agent picks the tool:
 
-```bash
-echo /agents | pnpm --filter harness-cli-example start
-echo '/agent haiku {"topic":"rain"}' | pnpm --filter harness-cli-example start
-```
+- `make an image of a red fox in the snow`
+- `make a watercolor version of @./playground/fox.png`: the image tool uses the images you send as references.
+- `read this aloud with the nova voice: hello`
+- `compose a 30 second synth-pop song about foxes, with the lyrics "fox in the snow"`
+- `make a 5 second sound effect of rain on a window`
+- `make a short video of snow in a pine forest` (a minute or two)
+
+The harness keeps each file, and the screen saves it in `example-coder-media` with a number. `/open 2` opens file 2, and `/play` plays the last song or speech (with `ffplay` from ffmpeg).
+
+## Hand work to Claude Code and Codex
 
-## Use Notion, Linear, images, and video
+When `claude` and `codex` are on the PATH, the agent can call them. They work in `./playground` with your own `claude login` and `codex login`, and the API keys are removed from their processes.
+
+- Ask: `have codex create notes.md with one line, then have claude code add a second line`.
+- The screen shows each agent with its status, its tool calls, and its output. When it ends, the last lines of its answer stay.
+- Codex uses the `model` and `sandbox_mode` of your `~/.codex/config.toml`. `CODEX_MODEL` and `CODEX_SANDBOX_MODE` change them.
+- On Windows, the `workspace-write` sandbox of Codex can block the folder (Access is denied). Then use `danger-full-access`, only for a folder you trust.
+
+## Use Notion and Linear
 
 1. Run `/connect notion`. Approve the consent page that opens in the browser. Do the same with `/connect linear`.
-2. Ask: `find my latest Linear issue, look for a related Notion page, then make an image and a short video about it`.
-3. The harness keeps each file. The CLI saves it in `example-coder-media` and prints `[image saved: <path>]`. Change the folder with `--media-dir <dir>`.
-4. To send a file, put `@` before its path: `describe @./playground/cat.png`.
+2. Ask: `list the titles of my 3 latest Linear issues`, or `search Notion for the onboarding page`.
 
 - Sign-ins are kept in `~/.tanstack-harness-example/credentials.json`, so you sign in once. `/disconnect notion` deletes one.
-- Images use `OPENAI_API_KEY`. Videos use Grok Imagine when `XAI_API_KEY` is set, and OpenAI Sora when it is not.
-- Code mode is on: read-only tools (file reads, read-only Notion and Linear tools) are `external_*` functions in one `execute_typescript` program, which runs in a QuickJS isolate. Ask: `in one program, list my Linear issues and search Notion for them`.
+- Code mode is on: read-only tools (file reads, read-only Notion and Linear tools) are functions in one `execute_typescript` program, which runs in a QuickJS isolate.
 
-## Hand work to Claude Code and Codex
+## Everything else it shows
 
-1. Sign in to the CLIs once: `claude login` and `codex login`.
-2. Start with `CODING_AGENTS=1`. If you use Codex with a ChatGPT login, also set `CODEX_MODEL` to the model in `~/.codex/config.toml`.
-3. Ask: `have claude_code create notes.md with one line, then have codex add a second line`.
+- `/model` lists the models, and `/model claude` switches at the next turn. The header shows the current one.
+- `create hello.txt with a short poem`: the agent asks before `write_file`. Type `y`.
+- `/mode plan` makes it read-only. `/todos`, `/usage`, `/compact`.
+- `/goal create a file hello.txt that says hi`: the agent keeps working until the model says the goal is met.
+- Press Esc to stop a long answer. Type while it works to steer it.
+- `/help` lists every command.
 
-- Both agents work in `./playground` with your own logins. The API keys are removed from their processes.
-- The screen shows each agent with its status, its tool calls, and its latest text. `/fresh` starts new agent sessions.
-- On Windows, the Codex sandbox can block the folder (Access is denied). Then set `CODEX_SANDBOX_MODE=danger-full-access`, only for a folder you trust.
+The screen is `src/tui.tsx`, plain example code on `createSessionView`. `src/voice.ts` records and transcribes, and `src/media.ts` has the media agents. Copy them and change them.
 
 ## Other modes
 
-- One prompt for scripts and CI: `pnpm --filter harness-cli-example start -p "list the files"`
-- AG-UI events as JSON lines: add `--output ndjson`.
+- Piped input uses line mode: `echo '/agent haiku {"topic":"rain"}' | pnpm --filter harness-cli-example start`
+- One prompt for scripts and CI: `pnpm --filter harness-cli-example start -p "list the files"`. Add `--output ndjson` for AG-UI events as JSON lines.
 - As an editor agent (ACP): `pnpm --filter harness-cli-example start --acp`
+- As an MCP server for Claude Code or Cursor: `pnpm --filter harness-cli-example start --mcp`
 - As an HTTP server: `pnpm --filter harness-cli-example start --serve` (it prints a token).
 
 ## Watch it from a browser or a phone
diff --git a/examples/harness-cli/package.json b/examples/harness-cli/package.json
index 917dd16f13..0c269a4745 100644
--- a/examples/harness-cli/package.json
+++ b/examples/harness-cli/package.json
@@ -16,6 +16,7 @@
     "@tanstack/ai-code-mode": "workspace:*",
     "@tanstack/ai-codex": "workspace:*",
     "@tanstack/ai-dashboard": "workspace:*",
+    "@tanstack/ai-fal": "workspace:*",
     "@tanstack/ai-grok": "workspace:*",
     "@tanstack/ai-harness": "workspace:*",
     "@tanstack/ai-harness-cli": "workspace:*",
diff --git a/examples/harness-cli/src/cli.ts b/examples/harness-cli/src/cli.ts
index b6e2eb2c7e..24144390ca 100644
--- a/examples/harness-cli/src/cli.ts
+++ b/examples/harness-cli/src/cli.ts
@@ -1,13 +1,7 @@
 import { runCli } from '@tanstack/ai-harness-cli'
-import { composePersistence, memoryPersistence } from '@tanstack/ai-persistence'
-import { fileCredentials } from './credentials'
 import { assistant } from './harness'
+import { persistence } from './store'
 import { runTui } from './tui'
 
-// Everything in memory, except sign-ins, which are kept in a file.
-const persistence = composePersistence(memoryPersistence(), {
-  overrides: { credentials: fileCredentials() },
-})
-
 // A terminal shows the Ink screen from ./tui. Piped input uses line mode.
 process.exitCode = await runCli(assistant, { persistence, ui: runTui })
diff --git a/examples/harness-cli/src/harness.ts b/examples/harness-cli/src/harness.ts
index bb0a3563cc..2cf637cf3a 100644
--- a/examples/harness-cli/src/harness.ts
+++ b/examples/harness-cli/src/harness.ts
@@ -1,3 +1,6 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { delimiter, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { EventType, defineAgent } from '@tanstack/ai'
 import { defineHarness } from '@tanstack/ai-harness'
@@ -16,18 +19,29 @@ import { claudeCodeText } from '@tanstack/ai-claude-code'
 import { codeMode } from '@tanstack/ai-code-mode/harness'
 import { codexText } from '@tanstack/ai-codex'
 import { mcpConnector } from '@tanstack/ai-mcp/connector'
-import { grokVideo } from '@tanstack/ai-grok'
+import { grokText, grokVideo } from '@tanstack/ai-grok'
 import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs'
-import { openaiText, openaiVideo } from '@tanstack/ai-openai'
+import {
+  openaiText,
+  openaiTranscription,
+  openaiVideo,
+} from '@tanstack/ai-openai'
 import {
   defineSandbox,
   defineWorkspace,
   localSource,
 } from '@tanstack/ai-sandbox'
 import { codingAgents } from '@tanstack/ai-sandbox/harness'
+import type { CodingAgentConfig } from '@tanstack/ai-sandbox/harness'
 import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'
 import { z } from 'zod'
-import { imageAgent, videoAgent } from './media'
+import {
+  imageAgent,
+  songAgent,
+  soundAgent,
+  speechAgent,
+  videoAgent,
+} from './media'
 import type { AnyTextAdapter } from '@tanstack/ai'
 
 // The agent works in ./playground, so it cannot touch the rest of your disk.
@@ -92,27 +106,72 @@ function demoModel(): AnyTextAdapter {
   }
 }
 
-function pickModels(): {
-  main: AnyTextAdapter
-  choices: Record<string, AnyTextAdapter>
-} {
+/**
+ * The models `/model <name>` can switch to: one or two per provider with a
+ * key. The first one is the default.
+ */
+function pickModels() {
+  const choices: Record<string, AnyTextAdapter> = {}
   if (process.env.OPENAI_API_KEY) {
-    const smart = openaiText('gpt-5.6')
-    return { main: smart, choices: { smart, fast: openaiText('gpt-5.6-luna') } }
+    choices.gpt = openaiText('gpt-6-astra')
+    choices['gpt-fast'] = openaiText('gpt-6-luna')
   }
   if (process.env.ANTHROPIC_API_KEY) {
-    const smart = anthropicText('claude-opus-5-5')
-    return {
-      main: smart,
-      choices: { smart, fast: anthropicText('claude-sonnet-5') },
-    }
+    choices.claude = anthropicText('claude-opus-5-5')
+    choices['claude-fast'] = anthropicText('claude-sonnet-5')
   }
-  const demo = demoModel()
-  return { main: demo, choices: { demo } }
+  if (process.env.XAI_API_KEY) choices.grok = grokText('grok-4.7')
+  const [main = demoModel()] = Object.values(choices)
+  if (Object.keys(choices).length === 0) choices.demo = main
+  return { main, choices }
 }
 
 const { main, choices } = pickModels()
 
+/** Is `command` on the PATH? Checks the Windows extensions too. */
+function onPath(command: string) {
+  const extensions =
+    process.platform === 'win32'
+      ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';')
+      : ['']
+  return (process.env.PATH ?? '')
+    .split(delimiter)
+    .some((dir) =>
+      extensions.some((extension) =>
+        existsSync(join(dir, `${command}${extension.toLowerCase()}`)),
+      ),
+    )
+}
+
+/**
+ * A top-level setting of your ~/.codex/config.toml (the lines before the
+ * first `[section]`), so the example runs Codex the way you set it up.
+ */
+function codexSetting(key: string) {
+  const config = join(homedir(), '.codex', 'config.toml')
+  if (!existsSync(config)) return undefined
+  const [topLevel = ''] = readFileSync(config, 'utf8').split(/^\s*\[/m)
+  return new RegExp(`^\\s*${key}\\s*=\\s*"([^"]+)"`, 'm').exec(topLevel)?.[1]
+}
+
+const CODEX_SANDBOX_MODES = [
+  'read-only',
+  'workspace-write',
+  'danger-full-access',
+] as const
+
+/**
+ * The Codex sandbox: CODEX_SANDBOX_MODE, else `sandbox_mode` in your Codex
+ * config, else workspace-write. On Windows, workspace-write can block the
+ * folder (Access is denied).
+ */
+function codexSandbox() {
+  const mode = process.env.CODEX_SANDBOX_MODE ?? codexSetting('sandbox_mode')
+  return (
+    CODEX_SANDBOX_MODES.find((known) => known === mode) ?? 'workspace-write'
+  )
+}
+
 /** A typed agent you can run with `/agent haiku {"topic":"rain"}`. */
 const haiku = defineAgent({
   name: 'haiku',
@@ -131,19 +190,21 @@ const haiku = defineAgent({
     }),
 })
 
-// The model calls the media agents as tools. Images use OpenAI. Videos use
-// Grok Imagine when XAI_API_KEY is set, else OpenAI Sora. The harness keeps
-// each file they make.
-const media = process.env.OPENAI_API_KEY
-  ? [
-      imageAgent,
-      videoAgent(
-        process.env.XAI_API_KEY
-          ? grokVideo('grok-imagine-video-1.5')
-          : openaiVideo('sora-2'),
-      ),
-    ]
-  : []
+// The model calls the media agents as tools, and the harness keeps each file
+// they make. Each one turns on with the key its provider needs:
+// - OPENAI_API_KEY: images, speech, and video with Sora.
+// - XAI_API_KEY: video with Grok Imagine (it wins over Sora).
+// - FAL_KEY: songs and sound effects.
+const video = process.env.XAI_API_KEY
+  ? videoAgent(grokVideo('grok-imagine-video-1.5'))
+  : process.env.OPENAI_API_KEY
+    ? videoAgent(openaiVideo('sora-2'))
+    : undefined
+const media = [
+  ...(process.env.OPENAI_API_KEY ? [imageAgent, speechAgent] : []),
+  ...(video ? [video] : []),
+  ...(process.env.FAL_KEY ? [songAgent, soundAgent] : []),
+]
 
 // Notion and Linear through their MCP servers. `/connect notion` signs in
 // through the browser. No app setup or API key is needed.
@@ -158,11 +219,41 @@ const linear = mcpConnector({
   url: 'https://mcp.linear.app/mcp',
 })
 
-// With CODING_AGENTS=1, the lead model can hand coding work to Claude Code and
-// Codex. They work in ./playground with your own `claude login` and
+// The lead model can hand coding work to your local Claude Code and Codex.
+// Each one turns on when its CLI is on the PATH (CODING_AGENTS=0 turns both
+// off). They work in ./playground with your own `claude login` and
 // `codex login`, so the API keys are removed from their processes.
+const useCodingAgents = process.env.CODING_AGENTS !== '0'
+const codingAgentList: Record<string, CodingAgentConfig> = {}
+if (useCodingAgents && onPath('claude')) {
+  codingAgentList.claude_code = {
+    adapter: claudeCodeText('claude-opus-4-8', {
+      authMode: 'host',
+      permissionMode: 'acceptEdits',
+    }),
+    description:
+      'Claude Code, the local coding agent. Larger changes, refactors, and reviews in ./playground.',
+  }
+}
+if (useCodingAgents && onPath('codex')) {
+  codingAgentList.codex = {
+    // A ChatGPT login supports only some models, so the model and the sandbox
+    // come from your Codex config unless CODEX_MODEL or CODEX_SANDBOX_MODE is
+    // set.
+    adapter: codexText(
+      process.env.CODEX_MODEL ?? codexSetting('model') ?? 'gpt-5.3-codex',
+      {
+        authMode: 'host',
+        sandboxMode: codexSandbox(),
+        approvalPolicy: 'never',
+      },
+    ),
+    description:
+      'Codex, the local coding agent. Quick fixes, scripts, and tests in ./playground.',
+  }
+}
 const coding =
-  process.env.CODING_AGENTS === '1'
+  Object.keys(codingAgentList).length > 0
     ? [
         codingAgents({
           sandbox: defineSandbox({
@@ -173,46 +264,34 @@ const coding =
             }),
             workspace: defineWorkspace({ source: localSource(root) }),
           }),
-          agents: {
-            claude_code: {
-              adapter: claudeCodeText('claude-opus-4-8', {
-                authMode: 'host',
-                permissionMode: 'acceptEdits',
-              }),
-              description:
-                'Claude Code. Larger changes, refactors, and reviews in ./playground.',
-            },
-            codex: {
-              // A ChatGPT login supports only some models. Set CODEX_MODEL to the
-              // model in ~/.codex/config.toml.
-              adapter: codexText(process.env.CODEX_MODEL || 'gpt-5.3-codex', {
-                authMode: 'host',
-                // On Windows, the Codex sandbox can block the folder (Access is
-                // denied). Then set CODEX_SANDBOX_MODE=danger-full-access, only for
-                // a folder you trust.
-                sandboxMode:
-                  process.env.CODEX_SANDBOX_MODE === 'danger-full-access'
-                    ? 'danger-full-access'
-                    : 'workspace-write',
-                approvalPolicy: 'never',
-              }),
-              description: 'Codex. Quick fixes and tests in ./playground.',
-            },
-          },
+          agents: codingAgentList,
         }),
       ]
     : []
 
+const tools = [
+  ...media.map((agent) => agent.name),
+  ...Object.keys(codingAgentList),
+]
+
 export const assistant = defineHarness({
   name: 'example/coder',
-  description: 'A small coding agent that works in ./playground',
+  description:
+    'A coding agent in the terminal: files, voice, media, Notion, Linear, and local coding agents',
   adapter: main,
   systemPrompts: [
-    'You are a careful coding agent. Read files before you edit them. Keep answers short.',
-    'You can read Notion and Linear when they are connected, and make images and videos with the image and video tools. The user gets each file you make.',
+    'You are a careful coding agent that works in ./playground. Read files before you edit them. Keep answers short.',
+    `Your agent tools: ${tools.join(', ') || 'none'}. The user gets each file a media tool makes, so do not paste file contents or links.`,
+    'When the user asks to run Codex or Claude Code (by voice too: "run a Codex agent"), call that tool with a clear task, then give its answer back in a few lines.',
+    'The user can send files and voice messages. When they send an image and ask for a new version, a style, or an edit of it, call the image tool with useAttachedImages.',
+    'You can read Notion and Linear when they are connected. If a tool says to sign in, tell the user to run /connect notion or /connect linear.',
   ],
   agents: [haiku],
   subagents: { agents: media },
+  // Audio files the user sends become text for models that cannot read audio.
+  ...(process.env.OPENAI_API_KEY
+    ? { media: { transcribe: openaiTranscription('gpt-4o-transcribe') } }
+    : {}),
   plugins: () => [
     notion,
     linear,
diff --git a/examples/harness-cli/src/media.ts b/examples/harness-cli/src/media.ts
index 49969b02d8..a40bce363b 100644
--- a/examples/harness-cli/src/media.ts
+++ b/examples/harness-cli/src/media.ts
@@ -1,29 +1,93 @@
 import { EventType, defineAgent } from '@tanstack/ai'
-import { openaiImage } from '@tanstack/ai-openai'
+import { mediaIdOf } from '@tanstack/ai-harness'
+import { falAudio } from '@tanstack/ai-fal'
+import { openaiImage, openaiSpeech } from '@tanstack/ai-openai'
 import { z } from 'zod'
-import type { AnyVideoAdapter } from '@tanstack/ai'
+import { mediaBytes } from './store'
+import type {
+  AnyVideoAdapter,
+  ImagePart,
+  MediaInputMetadata,
+  ModelMessage,
+  UIMessage,
+} from '@tanstack/ai'
+
+// Every agent here returns a short text. The harness keeps each file it makes
+// and publishes a `harness.media` event, so the screen can show and save it.
 
 /**
- * Makes an image with OpenAI. The harness keeps the file and publishes a
- * `harness.media` event, so the screen can show it and save it.
+ * The images in the latest user message that has files: the ones the user
+ * sent with `@path`, or with a voice message that named a file.
  */
+async function attachedImages(
+  messages: ReadonlyArray<UIMessage | ModelMessage>,
+) {
+  for (const message of [...messages].reverse()) {
+    if (message.role !== 'user' || !('content' in message)) continue
+    if (!Array.isArray(message.content)) continue
+    const images: Array<ImagePart<MediaInputMetadata>> = []
+    for (const part of message.content) {
+      const id = mediaIdOf(part)
+      if (id === undefined || part.type !== 'image') continue
+      const bytes = await mediaBytes(id)
+      const mimeType = part.source.mimeType ?? 'image/png'
+      if (bytes) {
+        images.push({
+          type: 'image',
+          source: {
+            type: 'data',
+            value: Buffer.from(bytes).toString('base64'),
+            mimeType,
+          },
+        })
+      }
+    }
+    if (images.length > 0) return images
+  }
+  return []
+}
+
+/** Makes an image with OpenAI. It can start from the images the user sent. */
 export const imageAgent = defineAgent({
   name: 'image',
   description:
-    'Generates one image from a detailed visual prompt. The user gets the image.',
+    'Generates one image from a detailed visual prompt. Set useAttachedImages when the user sent images to use as references (a new version, a style, an edit). The user gets the image.',
   produces: 'image',
   inputSchema: z.object({
     prompt: z.string().describe('A detailed description of the image'),
+    useAttachedImages: z
+      .boolean()
+      .optional()
+      .describe('Use the images the user sent as references'),
   }),
   run: async (ctx) => {
-    const result = await ctx.generateImage({
-      adapter: openaiImage('gpt-image-2.5-flare'),
-      prompt: ctx.input.prompt,
-      size: '1024x1024',
-    })
+    const references = ctx.input.useAttachedImages
+      ? await attachedImages(ctx.messages)
+      : []
+    const adapter = openaiImage('gpt-image-2.5-flare')
+    // With references, the prompt is the text plus the images (an edit).
+    const result =
+      references.length > 0
+        ? await ctx.generateImage({
+            adapter,
+            prompt: [
+              { type: 'text', content: ctx.input.prompt },
+              ...references,
+            ],
+            size: '1024x1024',
+          })
+        : await ctx.generateImage({
+            adapter,
+            prompt: ctx.input.prompt,
+            size: '1024x1024',
+          })
     if (result.images.length === 0)
       throw new Error('The image model returned no image.')
-    return `Made the image with ${result.model}. The user has it.`
+    const from =
+      references.length > 0
+        ? ` from ${references.length} reference image(s)`
+        : ''
+    return `Made the image${from} with ${result.model}. The user has it.`
   },
 })
 
@@ -56,3 +120,78 @@ export function videoAgent(adapter: AnyVideoAdapter) {
     },
   })
 }
+
+/** Reads a text aloud with OpenAI text to speech. */
+export const speechAgent = defineAgent({
+  name: 'speech',
+  description:
+    'Reads a text aloud and makes an audio file of it (text to speech). The user gets the audio.',
+  produces: 'speech',
+  inputSchema: z.object({
+    text: z.string().describe('The exact words to say'),
+    voice: z
+      .enum(['alloy', 'echo', 'fable', 'onyx', 'nova', 'shimmer'])
+      .optional()
+      .describe('The voice. Default: alloy'),
+  }),
+  run: async (ctx) => {
+    const result = await ctx.generateSpeech({
+      adapter: openaiSpeech('tts-1-hd'),
+      text: ctx.input.text,
+      voice: ctx.input.voice ?? 'alloy',
+    })
+    return `Read the text aloud with ${result.model}. The user has the audio.`
+  },
+})
+
+/** Makes a song with vocals and music through fal (ElevenLabs Music). */
+export const songAgent = defineAgent({
+  name: 'song',
+  description:
+    'Composes a song or an instrumental track from a description (genre, mood, instruments, and lyrics if the user gave any). Takes up to a minute. The user gets the audio.',
+  produces: 'audio',
+  inputSchema: z.object({
+    prompt: z
+      .string()
+      .describe('The style, mood, instruments, and the lyrics, if any'),
+    seconds: z
+      .number()
+      .min(10)
+      .max(120)
+      .optional()
+      .describe('The length in seconds. Default: 30'),
+  }),
+  run: async (ctx) => {
+    const result = await ctx.generateAudio({
+      adapter: falAudio('fal-ai/elevenlabs/music'),
+      prompt: ctx.input.prompt,
+      duration: ctx.input.seconds ?? 30,
+    })
+    return `Composed the song with ${result.model}. The user has the audio.`
+  },
+})
+
+/** Makes a sound effect through fal (Stable Audio). */
+export const soundAgent = defineAgent({
+  name: 'sound_effect',
+  description:
+    'Makes a short sound effect or ambience from a description, for example rain on a window. The user gets the audio.',
+  produces: 'audio',
+  inputSchema: z.object({
+    prompt: z.string().describe('The sound to make'),
+    seconds: z
+      .number()
+      .min(1)
+      .max(30)
+      .optional()
+      .describe('The length in seconds. Default: 8'),
+  }),
+  run: async (ctx) => {
+    const result = await ctx.generateAudio({
+      adapter: falAudio('fal-ai/stable-audio-25/text-to-audio'),
+      prompt: ctx.input.prompt,
+      duration: ctx.input.seconds ?? 8,
+    })
+    return `Made the sound effect with ${result.model}. The user has the audio.`
+  },
+})
diff --git a/examples/harness-cli/src/store.ts b/examples/harness-cli/src/store.ts
new file mode 100644
index 0000000000..f1b25dab92
--- /dev/null
+++ b/examples/harness-cli/src/store.ts
@@ -0,0 +1,20 @@
+import {
+  composePersistence,
+  memoryPersistence,
+  retrieveBlob,
+} from '@tanstack/ai-persistence'
+import { fileCredentials } from './credentials'
+
+/**
+ * Everything in memory, except sign-ins, which are kept in a file. The
+ * memory stores also keep media: the files you send and the files agents make.
+ */
+export const persistence = composePersistence(memoryPersistence(), {
+  overrides: { credentials: fileCredentials() },
+})
+
+/** The bytes of a stored media file, or `undefined` when it is gone. */
+export async function mediaBytes(id: string) {
+  const blob = await retrieveBlob(persistence, id)
+  return blob ? new Uint8Array(await blob.arrayBuffer()) : undefined
+}
diff --git a/examples/harness-cli/src/tui.tsx b/examples/harness-cli/src/tui.tsx
index 81348483dd..df56a8851c 100644
--- a/examples/harness-cli/src/tui.tsx
+++ b/examples/harness-cli/src/tui.tsx
@@ -1,11 +1,23 @@
 import { spawn } from 'node:child_process'
-import { mkdir, writeFile } from 'node:fs/promises'
-import { basename, join } from 'node:path'
-import { useEffect, useState } from 'react'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { basename, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { useEffect, useRef, useState } from 'react'
 import { Box, Text, render, useApp, useInput } from 'ink'
 import { useSelector } from '@tanstack/react-store'
 import { selectGoal } from '@tanstack/ai-harness/plugins'
 import { assistant } from './harness'
+import {
+  currentMicrophone,
+  isSilent,
+  listMicrophones,
+  startRecording,
+  transcribe,
+  chooseMicrophone,
+  withSpokenFiles,
+} from './voice'
+import type { RenderOptions } from 'ink'
+import type { Recording } from './voice'
 import type {
   AgentPart,
   MediaPart,
@@ -14,13 +26,21 @@ import type {
   ViewPart,
 } from '@tanstack/ai-harness/view'
 
-/** Where each media file is saved or why not, by media id. */
-type MediaNotes = ReadonlyMap<string, string>
-
 // ponytail: the CLI's default media folder, `./<harness-name>-media`. A custom
 // ui gets no `--media-dir`, and the CLI does not export `defaultMediaDir`, so
 // this copies its rule. The media id in front of the name keeps names unique.
 const mediaDir = `${assistant.name.replace(/[^\w.-]+/g, '-').replace(/^[-.]+|-+$/g, '')}-media`
+const playground = fileURLToPath(new URL('../playground', import.meta.url))
+
+/** A media file the screen saved. `number` is what `/open` and `/play` take. */
+interface Saved {
+  id: string
+  number: number
+  kind: string
+  name: string
+  path?: string
+  error?: string
+}
 
 /** Write the bytes of a media file into `mediaDir`, and return the path. */
 async function saveMedia(part: MediaPart) {
@@ -48,98 +68,153 @@ function generatedMedia(messages: ReadonlyArray<ViewMessage>) {
 }
 
 /**
- * Save each new media file once, and keep a note per file: the path, or why
- * it was not saved. Files in the history when the screen opens are not saved
- * again.
+ * Save each new media file once, and number it. Files in the history when
+ * the screen opens are not saved again.
  */
 function useSavedMedia(view: SessionView, messages: Array<ViewMessage>) {
-  const [notes, setNotes] = useState(() => new Map<string, string>())
+  const [saved, setSaved] = useState<ReadonlyArray<Saved>>([])
   const [seen] = useState(
     () =>
       new Set(generatedMedia(view.store.get().messages).map((part) => part.id)),
   )
   useEffect(() => {
-    const media = generatedMedia(messages)
-    for (const part of media) {
+    for (const part of generatedMedia(messages)) {
       if (seen.has(part.id)) continue
       seen.add(part.id)
-      const note = (text: string) =>
-        setNotes((current) => new Map(current).set(part.id, text))
+      const number = seen.size
+      const update = (change: Partial<Saved>) =>
+        setSaved((current) =>
+          current.map((item) =>
+            item.id === part.id ? { ...item, ...change } : item,
+          ),
+        )
+      setSaved((current) => [
+        ...current,
+        { id: part.id, number, kind: part.kind, name: part.name },
+      ])
       saveMedia(part).then(
-        (path) => note(`saved: ${path}`),
+        (path) => update({ path }),
         (error: unknown) =>
-          note(
-            `not saved: ${error instanceof Error ? error.message : String(error)}`,
-          ),
+          update({
+            error: error instanceof Error ? error.message : String(error),
+          }),
       )
     }
   }, [messages, seen])
-  return notes
+  return saved
 }
 
 function textOf(parts: ReadonlyArray<ViewPart>) {
   return parts.map((part) => (part.type === 'text' ? part.text : '')).join('')
 }
 
-/** Open an http(s) link in the default browser. No shell is involved. */
-function openInBrowser(url: string) {
-  if (!/^https?:\/\//.test(url)) return
-  const isWindows = process.platform === 'win32'
-  // Not `cmd /c start`: cmd would read `&` in the URL as a command separator.
-  const command = isWindows
-    ? 'rundll32'
-    : process.platform === 'darwin'
-      ? 'open'
-      : 'xdg-open'
-  const args = isWindows ? ['url.dll,FileProtocolHandler', url] : [url]
+/** Start a program without a shell. The screen still shows the path on error. */
+function launch(command: string, args: Array<string>) {
   const child = spawn(command, args, { stdio: 'ignore', detached: true })
-  // The screen still shows the link when no browser opens.
   child.on('error', () => {})
   child.unref()
 }
 
-/** One line for a media file an agent made: kind, name, and where it went. */
+/** Open a link or a file with the default app. No shell is involved. */
+function openExternal(target: string) {
+  if (process.platform === 'win32') {
+    // Not `cmd /c start`: cmd would read `&` in a URL as a command separator.
+    if (/^https?:\/\//.test(target))
+      launch('rundll32', ['url.dll,FileProtocolHandler', target])
+    else launch('explorer', [resolve(target)])
+    return
+  }
+  launch(process.platform === 'darwin' ? 'open' : 'xdg-open', [target])
+}
+
+/** Play audio or video with ffplay, which comes with ffmpeg. */
+function play(item: Saved & { path: string }) {
+  const window = item.kind === 'video' ? [] : ['-nodisp']
+  launch(process.env.FFPLAY_PATH || 'ffplay', [
+    ...window,
+    '-autoexit',
+    '-loglevel',
+    'quiet',
+    item.path,
+  ])
+}
+
 function MediaLine({
   part,
-  notes,
+  saved,
   indent,
 }: {
   part: MediaPart
-  notes: MediaNotes
+  saved: ReadonlyArray<Saved>
   indent: string
 }) {
-  const note = notes.get(part.id)
+  const item = saved.find((entry) => entry.id === part.id)
+  const where = item?.path
+    ? ` saved: ${item.path}`
+    : item?.error
+      ? ` not saved: ${item.error}`
+      : ''
+  const number = item ? `[${item.number}] ` : ''
   return (
-    <Text color="green">
-      {`${indent}- ${part.kind} ${part.name}${note ? ` (${note})` : ''}`}
-    </Text>
+    <Text color="green">{`${indent}- ${number}${part.kind} ${part.name}${where}`}</Text>
   )
 }
 
-/** A child agent, for example Claude Code or Codex, with its tool calls and media. */
-function Agent({ part, notes }: { part: AgentPart; notes: MediaNotes }) {
-  const latest = textOf(part.parts).replace(/\s+/g, ' ').trim().slice(-80)
+/**
+ * A child agent, for example Codex or Claude Code: its status, its last tool
+ * calls, its media, and its output. While it runs, the last 3 lines show. When
+ * it ends, the last 15 lines of its answer stay.
+ */
+function Agent({
+  part,
+  saved,
+}: {
+  part: AgentPart
+  saved: ReadonlyArray<Saved>
+}) {
+  const lines = textOf(part.parts)
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim() !== '')
+  const output = part.status === 'running' ? lines.slice(-3) : lines.slice(-15)
+  const tools = part.parts.flatMap((inner) =>
+    inner.type === 'tool-call' ? [inner.name] : [],
+  )
+  const media = part.parts.flatMap((inner) =>
+    inner.type === 'media' ? [inner] : [],
+  )
+  const color =
+    part.status === 'failed'
+      ? 'red'
+      : part.status === 'done'
+        ? 'magenta'
+        : 'yellow'
   return (
     <Box flexDirection="column">
-      <Text color="magenta">
-        {`  - agent ${part.name} (${part.status})${latest ? `: ${latest}` : ''}`}
-      </Text>
-      {part.parts.map((inner, index) => {
-        if (inner.type === 'tool-call')
-          return (
-            <Text key={index} color="yellow">{`    - tool ${inner.name}`}</Text>
-          )
-        if (inner.type === 'media')
-          return (
-            <MediaLine key={index} part={inner} notes={notes} indent="    " />
-          )
-        return null
-      })}
+      <Text color={color}>{`  - agent ${part.name} (${part.status})`}</Text>
+      {tools.slice(-5).map((name, index) => (
+        <Text key={`tool-${index}`} color="yellow">{`    - tool ${name}`}</Text>
+      ))}
+      {media.map((inner) => (
+        <MediaLine key={inner.id} part={inner} saved={saved} indent="    " />
+      ))}
+      {output.map((line, index) => (
+        <Text key={`line-${index}`} dimColor={part.status === 'running'}>
+          {`    ${line}`}
+        </Text>
+      ))}
+      {part.error ? <Text color="red">{`    ${part.error}`}</Text> : null}
     </Box>
   )
 }
 
-function Part({ part, notes }: { part: ViewPart; notes: MediaNotes }) {
+function Part({
+  part,
+  saved,
+}: {
+  part: ViewPart
+  saved: ReadonlyArray<Saved>
+}) {
   switch (part.type) {
     case 'text':
       return <Text>{part.text}</Text>
@@ -155,26 +230,31 @@ function Part({ part, notes }: { part: ViewPart; notes: MediaNotes }) {
       return <Text color="yellow">{`  - tool ${part.name}${note}`}</Text>
     }
     case 'agent':
-      return <Agent part={part} notes={notes} />
+      return <Agent part={part} saved={saved} />
     case 'media':
-      return <MediaLine part={part} notes={notes} indent="  " />
+      return <MediaLine part={part} saved={saved} indent="  " />
   }
 }
 
 function Message({
   message,
-  notes,
+  saved,
 }: {
   message: ViewMessage
-  notes: MediaNotes
+  saved: ReadonlyArray<Saved>
 }) {
   switch (message.role) {
     case 'user': {
-      // The files the user sent go after the text: `[image cat.png]`.
+      // The files the user sent go after the text: `[image cat.png]`. A
+      // voice message names its files as `@"path"`, shown as `[cat.png]`.
       const files = (message.media ?? []).map(
         (part) => `[${part.kind} ${part.name}]`,
       )
-      const line = [message.text, ...files].filter((text) => text !== '')
+      const text = message.text.replace(
+        /@"([^"]+)"/g,
+        (_match, path: string) => `[${basename(path)}]`,
+      )
+      const line = [text, ...files].filter((item) => item !== '')
       return <Text color="cyan">{`> ${line.join(' ')}`}</Text>
     }
     case 'notice':
@@ -187,19 +267,55 @@ function Message({
       return (
         <Box flexDirection="column">
           {message.parts.map((part, index) => (
-            <Part key={index} part={part} notes={notes} />
+            <Part key={index} part={part} saved={saved} />
           ))}
         </Box>
       )
   }
 }
 
-function Status({ view }: { view: SessionView }) {
+type VoiceState = 'idle' | 'recording' | 'transcribing'
+
+function Header({ view }: { view: SessionView }) {
+  const model = useSelector(
+    view.store,
+    (state) => state.config.find((entry) => entry.key === 'model')?.value,
+  )
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Text
+        bold
+      >{`TanStack AI harness: ${assistant.name}  (model: ${String(model ?? '?')})`}</Text>
+      <Text color="gray">
+        Ctrl+R talk | Esc cancel | /help | /model | /connect notion | /open |
+        /play | /exit
+      </Text>
+    </Box>
+  )
+}
+
+function Status({
+  view,
+  voice,
+  microphone,
+}: {
+  view: SessionView
+  voice: VoiceState
+  microphone: string
+}) {
   const status = useSelector(view.store, (state) => state.status)
   const approvals = useSelector(view.store, (state) => state.approvals)
   const question = useSelector(view.store, (state) => state.questions.at(0))
   const signIns = useSelector(view.store, (state) => state.signIns)
   const goal = useSelector(view.store, selectGoal)
+  const line =
+    voice === 'recording'
+      ? `recording from ${microphone}: speak, then press Ctrl+R or Enter to send (Esc drops it)`
+      : voice === 'transcribing'
+        ? 'transcribing your voice message...'
+        : status === 'running'
+          ? 'working (Esc cancels, Enter steers)'
+          : status
   return (
     <Box flexDirection="column" marginTop={1}>
       {signIns.map((signIn) => (
@@ -218,60 +334,187 @@ function Status({ view }: { view: SessionView }) {
           {`Goal: ${goal.text} (${goal.status}, round ${goal.round})`}
         </Text>
       ) : null}
-      <Text color="gray">
-        {status === 'running' ? 'working (Esc cancels, Enter steers)' : status}
-      </Text>
+      <Text color={voice === 'recording' ? 'red' : 'gray'}>{line}</Text>
     </Box>
   )
 }
 
-/** Enter: answer an approval or a question, run a screen command, or send the line. */
-async function submit(view: SessionView, line: string, exit: () => void) {
-  const text = line.trim()
-  const state = view.store.get()
-  if (state.approvals.length > 0) {
-    if (/^y(es)?$/i.test(text)) view.approveAll()
-    else view.rejectAll()
-    return
-  }
-  const [question] = state.questions
-  if (question) {
-    const answer = /^y(es)?$/i.test(text)
-      ? true
-      : /^no?$/i.test(text)
-        ? false
-        : text
-    await question.answer(answer)
-    return
-  }
-  if (text === '/exit') return exit()
-  if (text === '/help') {
-    const commands = state.commands.map(
-      (command) => `/${command.name}  ${command.description}`,
-    )
-    view.notice(
-      ['/connect <id>, /disconnect <id>, /exit', ...commands].join('\n'),
-    )
-    return
-  }
-  const connect = /^\/(connect|disconnect) (\S+)$/.exec(text)
-  if (connect) return view.command(`${connect[1]}:${connect[2]}`)
-  await view.send(text)
-}
+const HELP = [
+  'Voice: press Ctrl+R, speak, press Ctrl+R again. Name a file ("use cat dot png") or say "the last image" to send it too.',
+  '/voice <audio file>  send a recorded voice message',
+  '/mic [n]  list the microphones, or record from microphone n',
+  '/open [n]  open media file n (default: the last one)',
+  '/play [n]  play audio or video file n',
+  '/connect <id>, /disconnect <id>  sign in to notion or linear',
+  '@path in a message sends that file. /exit quits.',
+]
 
 function App({ view }: { view: SessionView }) {
   const { exit } = useApp()
   const messages = useSelector(view.store, (state) => state.messages)
-  const notes = useSavedMedia(view, messages)
+  const saved = useSavedMedia(view, messages)
   const [input, setInput] = useState('')
+  const [voice, setVoice] = useState<VoiceState>('idle')
+  const [microphone, setMicrophone] = useState('')
+  const recording = useRef<Recording | undefined>(undefined)
+
+  const fail = (error: unknown) =>
+    view.notice(
+      `Voice: ${error instanceof Error ? error.message : String(error)}`,
+    )
+
+  /** A voice message: transcribe it, attach the files it names, and send it. */
+  const hear = async (audio: Uint8Array, name: string) => {
+    setVoice('transcribing')
+    try {
+      // A recording from the microphone that holds only silence is not sent:
+      // transcription models make up words for it.
+      if (name === 'voice.wav' && isSilent(audio))
+        return view.notice(
+          `Voice: only silence from "${await currentMicrophone()}". Speak closer, or pick another microphone with /mic.`,
+        )
+      const text = await transcribe(audio, name)
+      if (text === '') return view.notice('Voice: no speech heard.')
+      const recent = saved.flatMap((item) =>
+        item.path ? [{ kind: item.kind, path: item.path }] : [],
+      )
+      const message = await withSpokenFiles(
+        text,
+        [playground, mediaDir],
+        recent,
+      )
+      const files =
+        message.files.length > 0 ? ` (files: ${message.files.join(', ')})` : ''
+      view.notice(`Heard: "${text}"${files}`)
+      await view.send(message.text)
+    } catch (error) {
+      fail(error)
+    } finally {
+      setVoice('idle')
+    }
+  }
+
+  const toggleVoice = async () => {
+    if (voice === 'transcribing') return
+    const current = recording.current
+    if (current) {
+      recording.current = undefined
+      await current.stop().then((audio) => hear(audio, 'voice.wav'), fail)
+      return
+    }
+    try {
+      recording.current = await startRecording()
+      setVoice('recording')
+      setMicrophone(await currentMicrophone().catch(() => 'the default input'))
+    } catch (error) {
+      fail(error)
+    }
+  }
+
+  /** The saved media file `/open 2` or `/play` names. */
+  const pick = (arg: string | undefined) => {
+    const ready = saved.filter((item) => item.path !== undefined)
+    const item = arg
+      ? ready.find((entry) => entry.number === Number(arg))
+      : ready.at(-1)
+    if (!item?.path) {
+      view.notice(arg ? `No saved media file ${arg}.` : 'No media file yet.')
+      return undefined
+    }
+    return { ...item, path: item.path }
+  }
+
+  /** Enter: answer an approval or a question, run a screen command, or send. */
+  const submit = async (line: string) => {
+    const text = line.trim()
+    const state = view.store.get()
+    if (state.approvals.length > 0) {
+      if (/^y(es)?$/i.test(text)) view.approveAll()
+      else view.rejectAll()
+      return
+    }
+    const [question] = state.questions
+    if (question) {
+      const answer = /^y(es)?$/i.test(text)
+        ? true
+        : /^no?$/i.test(text)
+          ? false
+          : text
+      await question.answer(answer)
+      return
+    }
+    if (text === '/exit') return exit()
+    if (text === '/help') {
+      const commands = state.commands.map(
+        (command) => `/${command.name}  ${command.description}`,
+      )
+      view.notice([...HELP, ...commands].join('\n'))
+      return
+    }
+    const [command, ...rest] = text.split(' ')
+    const arg = rest.join(' ').trim() || undefined
+    if (command === '/mic') {
+      const names = await listMicrophones().catch((error: unknown) => {
+        fail(error)
+        return []
+      })
+      const chosen = arg ? names[Number(arg) - 1] : undefined
+      if (chosen) chooseMicrophone(chosen)
+      const current = await currentMicrophone().catch(() => undefined)
+      view.notice(
+        names.length === 0
+          ? `Recording from the default input${current ? ` (${current})` : ''}.`
+          : [
+              ...names.map(
+                (name, index) =>
+                  `${name === current ? '*' : ' '} ${index + 1}. ${name}`,
+              ),
+              '/mic <n> records from microphone n.',
+            ].join('\n'),
+      )
+      return
+    }
+    if (command === '/voice') {
+      if (!arg) return view.notice('Give an audio file: /voice note.m4a')
+      const audio = await readFile(arg.replace(/^@|^"|"$/g, '')).catch(fail)
+      if (audio) await hear(new Uint8Array(audio), basename(arg))
+      return
+    }
+    if (command === '/open' || command === '/play') {
+      const item = pick(arg)
+      if (!item) return
+      if (command === '/play' && item.kind !== 'image') play(item)
+      else openExternal(item.path)
+      return
+    }
+    const connect = /^\/(connect|disconnect) (\S+)$/.exec(text)
+    if (connect) return view.command(`${connect[1]}:${connect[2]}`)
+    await view.send(text)
+  }
+
   useInput((character, key) => {
+    if (key.ctrl && character === 'r') {
+      void toggleVoice()
+      return
+    }
     if (key.escape) {
+      const current = recording.current
+      if (current) {
+        recording.current = undefined
+        current.cancel()
+        setVoice('idle')
+        return
+      }
       if (view.store.get().status === 'running') void view.cancel()
       return
     }
     if (key.return) {
+      if (recording.current) {
+        void toggleVoice()
+        return
+      }
       setInput('')
-      void submit(view, input, exit)
+      void submit(input)
       return
     }
     if (key.backspace || key.delete) {
@@ -281,12 +524,14 @@ function App({ view }: { view: SessionView }) {
     if (!key.ctrl && !key.meta && character)
       setInput((current) => current + character)
   })
+
   return (
     <Box flexDirection="column">
+      <Header view={view} />
       {messages.slice(-200).map((message) => (
-        <Message key={message.id} message={message} notes={notes} />
+        <Message key={message.id} message={message} saved={saved} />
       ))}
-      <Status view={view} />
+      <Status view={view} voice={voice} microphone={microphone} />
       <Text>
         <Text color="cyan">{'> '}</Text>
         {input}
@@ -298,13 +543,29 @@ function App({ view }: { view: SessionView }) {
 
 /**
  * The Ink screen for `runCli({ ui })`. It opens sign-in links in the browser,
- * saves the media the agents make into `./<harness-name>-media`, and resolves
- * when the user types /exit or presses Ctrl+C.
+ * records voice messages, saves the media the agents make into
+ * `./<harness-name>-media`, and resolves when the user types /exit or presses
+ * Ctrl+C. `io` replaces the terminal, for a test.
  */
-export async function runTui(view: SessionView) {
+export async function runTui(view: SessionView, io: RenderOptions = {}) {
   view.on('signIn', (signIn) => {
-    if (signIn.url) openInBrowser(signIn.url)
+    if (signIn.url) openExternal(signIn.url)
   })
-  view.notice('Type a message, or /help for commands and /exit to quit.')
-  await render(<App view={view} />).waitUntilExit()
+  view.notice(
+    'Type a message, or press Ctrl+R to talk. /help lists the commands.',
+  )
+  // ponytail: the adapters warn on the console about tool schemas they send
+  // without strict mode. Ink prints console output above the screen, so the
+  // screen drops only those warnings.
+  const warn = console.warn
+  console.warn = (...args: Array<unknown>) => {
+    if (typeof args[0] === 'string' && args[0].includes('[tanstack-ai:warn]'))
+      return
+    warn(...args)
+  }
+  try {
+    await render(<App view={view} />, io).waitUntilExit()
+  } finally {
+    console.warn = warn
+  }
 }
diff --git a/examples/harness-cli/src/voice.ts b/examples/harness-cli/src/voice.ts
new file mode 100644
index 0000000000..de7ecf7dc6
--- /dev/null
+++ b/examples/harness-cli/src/voice.ts
@@ -0,0 +1,278 @@
+import { execFile, spawn } from 'node:child_process'
+import { readFile, readdir, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { basename, extname, join, relative } from 'node:path'
+import { generateTranscription } from '@tanstack/ai'
+import { grokTranscription } from '@tanstack/ai-grok'
+import { openaiTranscription } from '@tanstack/ai-openai'
+
+// Voice input for the terminal: ffmpeg records the microphone, a
+// transcription model turns it into text, and spoken file names become
+// `@path` attachments that the CLI sends with the message.
+
+const ffmpeg = process.env.FFMPEG_PATH || 'ffmpeg'
+
+/**
+ * The audio inputs ffmpeg can record on Windows (DirectShow). Other systems
+ * record the default input, so this is empty there.
+ */
+export function listMicrophones() {
+  if (process.platform !== 'win32') return Promise.resolve<Array<string>>([])
+  return new Promise<Array<string>>((resolve, reject) => {
+    execFile(
+      ffmpeg,
+      ['-hide_banner', '-list_devices', 'true', '-f', 'dshow', '-i', 'dummy'],
+      (error, _stdout, stderr) => {
+        if (error?.code === 'ENOENT')
+          return reject(
+            new Error('Voice needs ffmpeg on the PATH (or FFMPEG_PATH).'),
+          )
+        resolve(
+          [...stderr.matchAll(/"([^"]+)" \(audio\)/g)].map(
+            (match) => match[1] ?? '',
+          ),
+        )
+      },
+    )
+  })
+}
+
+// The microphone `/mic <n>` picked. VOICE_DEVICE wins over it.
+let picked: string | undefined
+
+/** Record from this microphone from now on. */
+export function chooseMicrophone(name: string) {
+  picked = name
+}
+
+/**
+ * The microphone to record from: VOICE_DEVICE, the one `/mic` picked, or the
+ * first real microphone in the list (not a capture card or a virtual input).
+ */
+export async function currentMicrophone() {
+  if (process.env.VOICE_DEVICE) return process.env.VOICE_DEVICE
+  if (picked) return picked
+  const names = await listMicrophones()
+  const real = names.find(
+    (name) => /microphone|mic\b/i.test(name) && !/virtual/i.test(name),
+  )
+  const name = real ?? names[0]
+  if (!name)
+    throw new Error('No microphone found. Set VOICE_DEVICE to its name.')
+  return name
+}
+
+/** The ffmpeg input arguments for the microphone. */
+async function microphoneInput() {
+  if (process.platform === 'win32')
+    return ['-f', 'dshow', '-i', `audio=${await currentMicrophone()}`]
+  if (process.platform === 'darwin')
+    return ['-f', 'avfoundation', '-i', `:${process.env.VOICE_DEVICE || '0'}`]
+  return ['-f', 'pulse', '-i', process.env.VOICE_DEVICE || 'default']
+}
+
+export interface Recording {
+  /** Stop, and give the recorded audio (16 kHz mono WAV). */
+  stop: () => Promise<Uint8Array>
+  /** Stop and drop the audio. */
+  cancel: () => void
+}
+
+/** Start recording the microphone until `stop` or `cancel`. */
+export async function startRecording(): Promise<Recording> {
+  const file = join(tmpdir(), `harness-voice-${Date.now()}.wav`)
+  const child = spawn(
+    ffmpeg,
+    [
+      '-hide_banner',
+      '-loglevel',
+      'error',
+      ...(await microphoneInput()),
+      '-ac',
+      '1',
+      '-ar',
+      '16000',
+      '-y',
+      file,
+    ],
+    { stdio: ['pipe', 'ignore', 'pipe'] },
+  )
+  let errors = ''
+  child.stderr.on('data', (chunk: Buffer) => (errors += chunk.toString()))
+  const exited = new Promise<number | null>((resolve, reject) => {
+    child.on('error', (error: NodeJS.ErrnoException) =>
+      reject(
+        error.code === 'ENOENT'
+          ? new Error('Voice needs ffmpeg on the PATH (or FFMPEG_PATH).')
+          : error,
+      ),
+    )
+    child.on('exit', resolve)
+  })
+  // ffmpeg stops at once when the device does not open.
+  const early = await Promise.race([
+    exited.then(() => 'exited' as const),
+    new Promise<'running'>((resolve) =>
+      setTimeout(() => resolve('running'), 400),
+    ),
+  ])
+  if (early === 'exited')
+    throw new Error(`The microphone did not open. ${errors.trim()}`.trim())
+  return {
+    stop: async () => {
+      // `q` makes ffmpeg finish the file.
+      child.stdin.end('q')
+      await exited
+      try {
+        return new Uint8Array(await readFile(file))
+      } finally {
+        await rm(file, { force: true })
+      }
+    },
+    cancel: () => {
+      child.kill()
+      void exited.finally(() => rm(file, { force: true }))
+    },
+  }
+}
+
+/** Where the samples of a WAV file start: after its `data` chunk header. */
+function wavDataStart(wav: Uint8Array) {
+  // ffmpeg adds a LIST chunk, so the header is not always 44 bytes.
+  const view = new DataView(wav.buffer, wav.byteOffset, wav.byteLength)
+  for (let offset = 12; offset + 8 <= wav.byteLength;) {
+    const id = String.fromCharCode(...wav.subarray(offset, offset + 4))
+    const size = view.getUint32(offset + 4, true)
+    if (id === 'data') return offset + 8
+    offset += 8 + size + (size % 2)
+  }
+  return wav.byteLength
+}
+
+/**
+ * The loudness of a WAV recording: the root mean square of its 16-bit
+ * samples, from 0 to 32768, without the constant offset some microphones add.
+ */
+export function loudness(wav: Uint8Array) {
+  const start = wav.byteOffset + wavDataStart(wav)
+  const count = Math.floor((wav.byteOffset + wav.byteLength - start) / 2)
+  const samples = new Int16Array(wav.buffer.slice(start, start + count * 2))
+  if (samples.length === 0) return 0
+  let sum = 0
+  let squares = 0
+  for (const sample of samples) {
+    sum += sample
+    squares += sample * sample
+  }
+  const mean = sum / samples.length
+  return Math.sqrt(Math.max(0, squares / samples.length - mean * mean))
+}
+
+/**
+ * Is a recording too quiet to hold speech? Transcription models make up words
+ * for silence, so a quiet recording is not sent. VOICE_MIN_LOUDNESS changes
+ * the limit.
+ */
+export function isSilent(wav: Uint8Array) {
+  return loudness(wav) < Number(process.env.VOICE_MIN_LOUDNESS || 300)
+}
+
+/**
+ * The words in `audio`, with OpenAI, or Grok when only an xAI key is set.
+ * `name` gives the format, for example `voice.wav`.
+ */
+export async function transcribe(audio: Uint8Array, name = 'voice.wav') {
+  const file = new File([audio.slice()], name)
+  if (process.env.OPENAI_API_KEY) {
+    const result = await generateTranscription({
+      adapter: openaiTranscription('gpt-4o-transcribe'),
+      audio: file,
+    })
+    return result.text.trim()
+  }
+  if (process.env.XAI_API_KEY) {
+    const result = await generateTranscription({
+      adapter: grokTranscription('grok-stt'),
+      audio: file,
+    })
+    return result.text.trim()
+  }
+  throw new Error(
+    'Voice needs OPENAI_API_KEY or XAI_API_KEY for transcription.',
+  )
+}
+
+const SKIP = new Set(['node_modules', '.git', 'dist'])
+
+/** The files in `dir` and its folders, 3 levels deep. */
+async function filesIn(dir: string, depth = 0): Promise<Array<string>> {
+  if (depth > 3) return []
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => [])
+  const files: Array<string> = []
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') || SKIP.has(entry.name)) continue
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) files.push(...(await filesIn(path, depth + 1)))
+    else files.push(path)
+  }
+  return files
+}
+
+/** Spoken text in a form that file names match: "cat dot png" is "cat.png". */
+function normalize(text: string) {
+  return text
+    .toLowerCase()
+    .replace(/\s+dot\s+/g, '.')
+    .replace(/\s*\.\s*(?=[a-z0-9]{2,4}\b)/g, '.')
+}
+
+/** The media a turn made, newest last, for "the last image" and the like. */
+export interface RecentMedia {
+  kind: string
+  path: string
+}
+
+const RECENT =
+  /\b(last|latest|previous|that|this|the)\s+(image|picture|photo|video|clip|song|track|audio|sound)\b/
+
+const KIND_OF_WORD: Record<string, string> = {
+  image: 'image',
+  picture: 'image',
+  photo: 'image',
+  video: 'video',
+  clip: 'video',
+  song: 'audio',
+  track: 'audio',
+  audio: 'audio',
+  sound: 'audio',
+}
+
+/**
+ * Turn the files a user names in a voice message into `@path` attachments.
+ * A file counts when its name is in the text ("use cat dot png as a
+ * reference"), or when the text says "the last image" and the screen saved
+ * one. The CLI reads each `@path` and sends the file with the message.
+ */
+export async function withSpokenFiles(
+  text: string,
+  roots: ReadonlyArray<string>,
+  recent: ReadonlyArray<RecentMedia> = [],
+) {
+  const spoken = normalize(text)
+  const found = new Set<string>()
+  for (const root of roots) {
+    for (const file of await filesIn(root)) {
+      const name = basename(file).toLowerCase()
+      if (extname(name) !== '' && spoken.includes(name)) found.add(file)
+    }
+  }
+  const match = RECENT.exec(spoken)
+  const kind = match ? KIND_OF_WORD[match[2] ?? ''] : undefined
+  const latest = kind
+    ? [...recent].reverse().find((media) => media.kind === kind)
+    : undefined
+  if (latest) found.add(latest.path)
+  const files = [...found].map((file) => relative(process.cwd(), file))
+  const refs = files.map((file) => `@"${file}"`)
+  return { text: [text, ...refs].join(' '), files }
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index dc30e0890f..6399e33f53 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -197,6 +197,9 @@ importers:
       '@tanstack/ai-dashboard':
         specifier: workspace:*
         version: link:../../packages/ai-dashboard
+      '@tanstack/ai-fal':
+        specifier: workspace:*
+        version: link:../../packages/ai-fal
       '@tanstack/ai-grok':
         specifier: workspace:*
         version: link:../../packages/ai-grok

From 3f1fc01af734f0b4ea7de0f89199a032ff7af12f Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Tue, 29 Sep 2026 14:50:08 +0000
Subject: [PATCH 066/286] ci: apply automated fixes

---
 examples/harness-cli/README.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index 637dd4d5cf..d649c4d427 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -11,12 +11,12 @@ From the repo root:
 3. Copy `.env.example` to `.env` and set the keys you have. Each key turns on more (see the table). Without a key, a demo model answers.
 4. `pnpm --filter harness-cli-example start`
 
-| Key | Adds |
-|---|---|
-| `OPENAI_API_KEY` | the `gpt` models, images, speech, Sora video, and voice input |
-| `ANTHROPIC_API_KEY` | the `claude` models |
-| `XAI_API_KEY` | the `grok` model, and video with Grok Imagine |
-| `FAL_KEY` | songs and sound effects |
+| Key                 | Adds                                                          |
+| ------------------- | ------------------------------------------------------------- |
+| `OPENAI_API_KEY`    | the `gpt` models, images, speech, Sora video, and voice input |
+| `ANTHROPIC_API_KEY` | the `claude` models                                           |
+| `XAI_API_KEY`       | the `grok` model, and video with Grok Imagine                 |
+| `FAL_KEY`           | songs and sound effects                                       |
 
 ## Talk to it
 

From 6882cd719eba2aca8cd7fe0c66b67861e7c51e9b Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 29 Sep 2026 17:46:42 +0200
Subject: [PATCH 067/286] feat(examples/harness-cli): a nicer screen,
 hold-to-talk voice, and the microphone picked by ear

The screen:
- A header card with the model and what is on. Tool calls have spinners and check marks.
- Each Codex or Claude Code run is its own card with its status and output. Media lines are colored by kind.
- A recording bar has a timer and a live level meter, and the input sits in its own box.
- The SDK's console warnings and errors no longer print over the screen.

Voice:
- Hold Ctrl+R to talk and let go to send, or tap it twice. A held key sends repeats, which used to start a new recording each time.
- The first recording listens on every microphone and keeps the one that heard you clearest (saved in ~/.tanstack-harness-example/voice.json).
- Audio streams from ffmpeg, so the meter is live. A silent clip is not sent. VOICE_LANGUAGE sets the transcript language.
- The phase is a ref, so fast key events cannot start a second recorder, and every recorder is killed when the app exits.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 examples/harness-cli/.env.example   |   5 +-
 examples/harness-cli/README.md      |  11 +-
 examples/harness-cli/src/harness.ts |  37 ++
 examples/harness-cli/src/tui.tsx    | 561 +++++++++++++++++++++-------
 examples/harness-cli/src/voice.ts   | 325 +++++++++++-----
 5 files changed, 703 insertions(+), 236 deletions(-)

diff --git a/examples/harness-cli/.env.example b/examples/harness-cli/.env.example
index 0f9cd2f0c5..8022cddd20 100644
--- a/examples/harness-cli/.env.example
+++ b/examples/harness-cli/.env.example
@@ -14,7 +14,10 @@ CODING_AGENTS=
 # Codex uses the model and sandbox_mode of ~/.codex/config.toml. These win.
 CODEX_MODEL=
 CODEX_SANDBOX_MODE=
-# Voice input records the microphone with ffmpeg.
+# Voice input records the microphone with ffmpeg. The first recording picks
+# the microphone; VOICE_DEVICE names one instead. VOICE_LANGUAGE (for example
+# en) is the language you talk in.
 FFMPEG_PATH=
 VOICE_DEVICE=
+VOICE_LANGUAGE=
 VOICE_MIN_LOUDNESS=
diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index d649c4d427..6c7c307f42 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -20,13 +20,16 @@ From the repo root:
 
 ## Talk to it
 
-1. Press Ctrl+R and speak.
-2. Press Ctrl+R (or Enter) again. The screen shows what it heard, and sends it.
+Hold Ctrl+R while you talk, and let go to send. Or tap Ctrl+R, talk, and tap it again. The meter shows that the microphone hears you.
 
 - Name a file, and it is sent too: "describe fox dot png", "use cat.png as a reference".
 - Say "the last image" (or video, song) for the last file the agent made: "make a pencil sketch of the last image".
-- Say "Hey, run a Codex agent that adds a test": Codex runs, and the screen shows its output.
-- `/mic` lists the microphones, and `/mic 3` records from the third one. A recording with only silence is not sent.
+- Say "Hey, run a Codex agent that adds a test": Codex runs in its own card, and the screen shows its output.
+
+The first recording listens on every microphone, and keeps the one that heard you clearest. `/mic` lists them, and `/mic 3` picks the third one. The choice is kept in `~/.tanstack-harness-example/voice.json`.
+
+- A silent recording (a muted microphone) is not sent.
+- Set `VOICE_LANGUAGE=en` (or your language) so the transcript is in that language.
 - `/voice note.m4a` sends a voice message that you recorded before.
 
 Voice needs `ffmpeg` on the PATH, and `OPENAI_API_KEY` or `XAI_API_KEY` for the transcript.
diff --git a/examples/harness-cli/src/harness.ts b/examples/harness-cli/src/harness.ts
index 2cf637cf3a..478a47f218 100644
--- a/examples/harness-cli/src/harness.ts
+++ b/examples/harness-cli/src/harness.ts
@@ -274,6 +274,43 @@ const tools = [
   ...Object.keys(codingAgentList),
 ]
 
+/** What this session can do, and what turns each one on, for the screen. */
+export const features = [
+  {
+    name: 'voice',
+    on: Boolean(process.env.OPENAI_API_KEY || process.env.XAI_API_KEY),
+    needs: 'OPENAI_API_KEY or XAI_API_KEY, and ffmpeg',
+  },
+  {
+    name: 'images',
+    on: Boolean(process.env.OPENAI_API_KEY),
+    needs: 'OPENAI_API_KEY',
+  },
+  {
+    name: 'speech',
+    on: Boolean(process.env.OPENAI_API_KEY),
+    needs: 'OPENAI_API_KEY',
+  },
+  {
+    name: 'video',
+    on: video !== undefined,
+    needs: 'XAI_API_KEY or OPENAI_API_KEY',
+  },
+  { name: 'songs', on: Boolean(process.env.FAL_KEY), needs: 'FAL_KEY' },
+  {
+    name: 'claude code',
+    on: 'claude_code' in codingAgentList,
+    needs: '`claude` on the PATH',
+  },
+  {
+    name: 'codex',
+    on: 'codex' in codingAgentList,
+    needs: '`codex` on the PATH',
+  },
+  { name: 'notion', on: true, needs: '' },
+  { name: 'linear', on: true, needs: '' },
+]
+
 export const assistant = defineHarness({
   name: 'example/coder',
   description:
diff --git a/examples/harness-cli/src/tui.tsx b/examples/harness-cli/src/tui.tsx
index df56a8851c..ff3a268bc6 100644
--- a/examples/harness-cli/src/tui.tsx
+++ b/examples/harness-cli/src/tui.tsx
@@ -3,29 +3,50 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { basename, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { useEffect, useRef, useState } from 'react'
-import { Box, Text, render, useApp, useInput } from 'ink'
+import {
+  Box,
+  Spacer,
+  Text,
+  render,
+  useAnimation,
+  useApp,
+  useInput,
+  usePaste,
+} from 'ink'
 import { useSelector } from '@tanstack/react-store'
 import { selectGoal } from '@tanstack/ai-harness/plugins'
-import { assistant } from './harness'
+import { assistant, features } from './harness'
 import {
+  canTranscribe,
+  chooseMicrophone,
   currentMicrophone,
   isSilent,
   listMicrophones,
   startRecording,
   transcribe,
-  chooseMicrophone,
   withSpokenFiles,
 } from './voice'
 import type { RenderOptions } from 'ink'
-import type { Recording } from './voice'
+import type { Recording, VoiceClip } from './voice'
 import type {
   AgentPart,
   MediaPart,
   SessionView,
+  ToolCallPart,
   ViewMessage,
   ViewPart,
 } from '@tanstack/ai-harness/view'
 
+// TanStack AI's accent color, the dark-mode step, so it reads on dark terminals.
+const ACCENT = '#e06e49'
+const KIND_COLOR: Record<string, string> = {
+  image: 'magenta',
+  audio: 'cyan',
+  video: 'blue',
+  document: 'white',
+}
+const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+
 // ponytail: the CLI's default media folder, `./<harness-name>-media`. A custom
 // ui gets no `--media-dir`, and the CLI does not export `defaultMediaDir`, so
 // this copies its rule. The media id in front of the name keeps names unique.
@@ -139,31 +160,85 @@ function play(item: Saved & { path: string }) {
   ])
 }
 
+function Spinner({ color = 'yellow' }: { color?: string }) {
+  const { frame } = useAnimation({ interval: 90 })
+  return <Text color={color}>{SPINNER[frame % SPINNER.length]}</Text>
+}
+
+/** A short one-line view of tool arguments. */
+function argsPreview(call: ToolCallPart) {
+  const text =
+    typeof call.args === 'object' && call.args !== null
+      ? Object.values(call.args)
+          .filter((value) => typeof value === 'string')
+          .join(', ')
+      : ''
+  const line = text.replace(/\s+/g, ' ').trim()
+  return line.length > 70 ? `${line.slice(0, 70)}...` : line
+}
+
+function ToolLine({
+  call,
+  indent = 2,
+}: {
+  call: ToolCallPart
+  indent?: number
+}) {
+  const icon =
+    call.status === 'running' ? (
+      <Spinner />
+    ) : call.status === 'done' ? (
+      <Text color="green">✓</Text>
+    ) : call.status === 'failed' ? (
+      <Text color="red">✗</Text>
+    ) : (
+      <Text color="magenta">?</Text>
+    )
+  const preview = argsPreview(call)
+  return (
+    <Box marginLeft={indent}>
+      {icon}
+      <Text color="yellow">{` ${call.name}`}</Text>
+      {preview ? <Text dimColor>{`  ${preview}`}</Text> : null}
+      {call.status === 'needs-approval' ? (
+        <Text color="magenta"> waits for your approval</Text>
+      ) : null}
+    </Box>
+  )
+}
+
 function MediaLine({
   part,
   saved,
-  indent,
+  indent = 2,
 }: {
   part: MediaPart
   saved: ReadonlyArray<Saved>
-  indent: string
+  indent?: number
 }) {
   const item = saved.find((entry) => entry.id === part.id)
-  const where = item?.path
-    ? ` saved: ${item.path}`
-    : item?.error
-      ? ` not saved: ${item.error}`
-      : ''
-  const number = item ? `[${item.number}] ` : ''
+  const color = KIND_COLOR[part.kind] ?? 'white'
   return (
-    <Text color="green">{`${indent}- ${number}${part.kind} ${part.name}${where}`}</Text>
+    <Box marginLeft={indent}>
+      <Text color={color} bold>
+        {`▣ ${item ? `${item.number} ` : ''}${part.kind}`}
+      </Text>
+      <Text>{`  ${part.name}`}</Text>
+      {item?.path ? <Text dimColor>{`  -> ${item.path}`}</Text> : null}
+      {item?.error ? (
+        <Text color="red">{`  not saved: ${item.error}`}</Text>
+      ) : null}
+      {item && !item.path && !item.error ? (
+        <Text dimColor> saving...</Text>
+      ) : null}
+    </Box>
   )
 }
 
 /**
- * A child agent, for example Codex or Claude Code: its status, its last tool
- * calls, its media, and its output. While it runs, the last 3 lines show. When
- * it ends, the last 15 lines of its answer stay.
+ * A child agent, for example Codex or Claude Code, in its own card: its
+ * status, its last tool calls, its media, and its output. While it runs, the
+ * last 4 lines show. When it ends, the last 15 lines of its answer stay.
  */
 function Agent({
   part,
@@ -176,34 +251,45 @@ function Agent({
     .split('\n')
     .map((line) => line.trimEnd())
     .filter((line) => line.trim() !== '')
-  const output = part.status === 'running' ? lines.slice(-3) : lines.slice(-15)
-  const tools = part.parts.flatMap((inner) =>
-    inner.type === 'tool-call' ? [inner.name] : [],
+  const running = part.status === 'running'
+  const output = running ? lines.slice(-4) : lines.slice(-15)
+  const calls = part.parts.flatMap((inner) =>
+    inner.type === 'tool-call' ? [inner] : [],
   )
   const media = part.parts.flatMap((inner) =>
     inner.type === 'media' ? [inner] : [],
   )
-  const color =
-    part.status === 'failed'
-      ? 'red'
-      : part.status === 'done'
-        ? 'magenta'
-        : 'yellow'
+  const color = part.status === 'failed' ? 'red' : running ? 'yellow' : 'green'
   return (
-    <Box flexDirection="column">
-      <Text color={color}>{`  - agent ${part.name} (${part.status})`}</Text>
-      {tools.slice(-5).map((name, index) => (
-        <Text key={`tool-${index}`} color="yellow">{`    - tool ${name}`}</Text>
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={color}
+      paddingX={1}
+      marginLeft={2}
+    >
+      <Box>
+        {running ? (
+          <Spinner color={color} />
+        ) : (
+          <Text color={color}>{part.status === 'done' ? '✓' : '✗'}</Text>
+        )}
+        <Text bold>{` ${part.name}`}</Text>
+        <Spacer />
+        <Text color={color}>{part.status}</Text>
+      </Box>
+      {calls.slice(-4).map((call) => (
+        <ToolLine key={call.id} call={call} indent={0} />
       ))}
       {media.map((inner) => (
-        <MediaLine key={inner.id} part={inner} saved={saved} indent="    " />
+        <MediaLine key={inner.id} part={inner} saved={saved} indent={0} />
       ))}
       {output.map((line, index) => (
-        <Text key={`line-${index}`} dimColor={part.status === 'running'}>
-          {`    ${line}`}
+        <Text key={`line-${index}`} dimColor={running}>
+          {line}
         </Text>
       ))}
-      {part.error ? <Text color="red">{`    ${part.error}`}</Text> : null}
+      {part.error ? <Text color="red">{part.error}</Text> : null}
     </Box>
   )
 }
@@ -217,22 +303,25 @@ function Part({
 }) {
   switch (part.type) {
     case 'text':
-      return <Text>{part.text}</Text>
+      return (
+        <Box marginLeft={2}>
+          <Text>{part.text}</Text>
+        </Box>
+      )
     case 'reasoning':
-      return <Text dimColor>{part.text}</Text>
-    case 'tool-call': {
-      const note =
-        part.status === 'needs-approval'
-          ? ' (waits for approval)'
-          : part.status === 'failed'
-            ? ' (failed)'
-            : ''
-      return <Text color="yellow">{`  - tool ${part.name}${note}`}</Text>
-    }
+      return (
+        <Box marginLeft={2}>
+          <Text dimColor italic>
+            {part.text}
+          </Text>
+        </Box>
+      )
+    case 'tool-call':
+      return <ToolLine call={part} />
     case 'agent':
       return <Agent part={part} saved={saved} />
     case 'media':
-      return <MediaLine part={part} saved={saved} indent="  " />
+      return <MediaLine part={part} saved={saved} />
   }
 }
 
@@ -245,27 +334,46 @@ function Message({
 }) {
   switch (message.role) {
     case 'user': {
-      // The files the user sent go after the text: `[image cat.png]`. A
-      // voice message names its files as `@"path"`, shown as `[cat.png]`.
-      const files = (message.media ?? []).map(
-        (part) => `[${part.kind} ${part.name}]`,
-      )
-      const text = message.text.replace(
-        /@"([^"]+)"/g,
-        (_match, path: string) => `[${basename(path)}]`,
+      // A voice message names its files as `@"path"`, shown as a file badge.
+      const named: Array<string> = []
+      const text = message.text
+        .replace(/@"([^"]+)"/g, (_match, path: string) => {
+          named.push(basename(path))
+          return ''
+        })
+        .trim()
+      const files = [
+        ...(message.media ?? []).map((part) => `${part.kind} ${part.name}`),
+        ...named,
+      ]
+      return (
+        <Box marginTop={1} flexWrap="wrap">
+          <Text bold>
+            <Text color={ACCENT}>❯ </Text>
+            {text}
+            {files.length > 0 ? ' ' : ''}
+          </Text>
+          {files.map((file) => (
+            <Text key={file} color="black" backgroundColor={ACCENT}>
+              {` ${file} `}
+            </Text>
+          ))}
+        </Box>
       )
-      const line = [text, ...files].filter((item) => item !== '')
-      return <Text color="cyan">{`> ${line.join(' ')}`}</Text>
     }
-    case 'notice':
+    case 'notice': {
+      const isError = message.kind === 'error'
       return (
-        <Text color={message.kind === 'error' ? 'red' : 'gray'}>
-          {message.text}
-        </Text>
+        <Box marginLeft={2}>
+          <Text
+            color={isError ? 'red' : 'gray'}
+          >{`${isError ? '✗' : '·'} ${message.text}`}</Text>
+        </Box>
       )
+    }
     case 'assistant':
       return (
-        <Box flexDirection="column">
+        <Box flexDirection="column" marginTop={1}>
           {message.parts.map((part, index) => (
             <Part key={index} part={part} saved={saved} />
           ))}
@@ -274,22 +382,60 @@ function Message({
   }
 }
 
-type VoiceState = 'idle' | 'recording' | 'transcribing'
-
 function Header({ view }: { view: SessionView }) {
   const model = useSelector(
     view.store,
     (state) => state.config.find((entry) => entry.key === 'model')?.value,
   )
   return (
-    <Box flexDirection="column" marginBottom={1}>
-      <Text
-        bold
-      >{`TanStack AI harness: ${assistant.name}  (model: ${String(model ?? '?')})`}</Text>
-      <Text color="gray">
-        Ctrl+R talk | Esc cancel | /help | /model | /connect notion | /open |
-        /play | /exit
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={ACCENT}
+      paddingX={1}
+    >
+      <Box>
+        <Text color={ACCENT} bold>
+          ◆ TanStack AI
+        </Text>
+        <Text bold> harness</Text>
+        <Text dimColor>{`  ${assistant.name}`}</Text>
+        <Spacer />
+        <Text dimColor>model </Text>
+        <Text color="cyan" bold>
+          {String(model ?? '?')}
+        </Text>
+      </Box>
+      <Box flexWrap="wrap">
+        {features.map((feature) => (
+          <Text key={feature.name} color={feature.on ? 'green' : 'gray'}>
+            {`${feature.on ? '●' : '○'} ${feature.name}   `}
+          </Text>
+        ))}
+      </Box>
+    </Box>
+  )
+}
+
+type VoiceState = 'idle' | 'starting' | 'recording' | 'transcribing'
+
+/** A live level meter from the microphone loudness (0 to 32768). */
+function LevelMeter({ recording }: { recording: Recording }) {
+  const { time } = useAnimation({ interval: 80 })
+  const level = recording.level()
+  // Map loudness to 0..1 on a log scale: -60 dB is empty, 0 dB is full.
+  const decibels = 20 * Math.log10(Math.max(level, 1) / 32768)
+  const filled = Math.round(Math.min(1, Math.max(0, (decibels + 60) / 60)) * 16)
+  const seconds = Math.floor(time / 1000)
+  const clock = `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`
+  return (
+    <Box>
+      <Text color="red" bold>{`● REC ${clock}  `}</Text>
+      <Text color={filled > 9 ? 'green' : filled > 4 ? 'yellow' : 'gray'}>
+        {'▮'.repeat(filled)}
       </Text>
+      <Text dimColor>{'▯'.repeat(16 - filled)}</Text>
+      <Text dimColor>{`  ${recording.microphone}`}</Text>
     </Box>
   )
 }
@@ -297,66 +443,123 @@ function Header({ view }: { view: SessionView }) {
 function Status({
   view,
   voice,
-  microphone,
+  recording,
 }: {
   view: SessionView
   voice: VoiceState
-  microphone: string
+  recording: Recording | undefined
 }) {
   const status = useSelector(view.store, (state) => state.status)
   const approvals = useSelector(view.store, (state) => state.approvals)
   const question = useSelector(view.store, (state) => state.questions.at(0))
   const signIns = useSelector(view.store, (state) => state.signIns)
   const goal = useSelector(view.store, selectGoal)
-  const line =
-    voice === 'recording'
-      ? `recording from ${microphone}: speak, then press Ctrl+R or Enter to send (Esc drops it)`
-      : voice === 'transcribing'
-        ? 'transcribing your voice message...'
-        : status === 'running'
-          ? 'working (Esc cancels, Enter steers)'
-          : status
   return (
     <Box flexDirection="column" marginTop={1}>
       {signIns.map((signIn) => (
         <Text key={signIn.connector} color="magenta">
-          {`Sign in to ${signIn.connector}: ${signIn.url ?? `run /connect ${signIn.connector}`}${signIn.userCode ? ` (code ${signIn.userCode})` : ''}`}
+          {`◇ Sign in to ${signIn.connector}: ${signIn.url ?? `run /connect ${signIn.connector}`}${signIn.userCode ? ` (code ${signIn.userCode})` : ''}`}
         </Text>
       ))}
       {approvals.length > 0 ? (
-        <Text color="magenta">
-          {`Approve ${approvals.map((item) => item.tool).join(', ')}? [y/n]`}
+        <Text color="magenta" bold>
+          {`◇ Approve ${approvals.map((item) => item.tool).join(', ')}? Type y or n.`}
         </Text>
       ) : null}
-      {question ? <Text color="magenta">{`? ${question.message}`}</Text> : null}
+      {question ? <Text color="magenta">{`◇ ${question.message}`}</Text> : null}
       {goal ? (
-        <Text color="green">
-          {`Goal: ${goal.text} (${goal.status}, round ${goal.round})`}
-        </Text>
+        <Text color="green">{`◎ Goal: ${goal.text} (${goal.status}, round ${goal.round})`}</Text>
+      ) : null}
+      {voice === 'recording' && recording ? (
+        <Box flexDirection="column">
+          <LevelMeter recording={recording} />
+          <Text dimColor>
+            Let go of Ctrl+R (or tap it again) to send. Esc drops it.
+          </Text>
+        </Box>
+      ) : voice === 'starting' ? (
+        <Box>
+          <Spinner color="red" />
+          <Text color="red"> opening the microphone...</Text>
+        </Box>
+      ) : voice === 'transcribing' ? (
+        <Box>
+          <Spinner color="cyan" />
+          <Text color="cyan"> listening to your voice message...</Text>
+        </Box>
+      ) : status === 'running' ? (
+        <Box>
+          <Spinner />
+          <Text color="yellow"> working</Text>
+          <Text dimColor> Esc cancels, typing steers</Text>
+        </Box>
       ) : null}
-      <Text color={voice === 'recording' ? 'red' : 'gray'}>{line}</Text>
+    </Box>
+  )
+}
+
+function InputBox({ input, voice }: { input: string; voice: VoiceState }) {
+  const active = voice === 'idle'
+  return (
+    <Box
+      borderStyle="round"
+      borderColor={voice === 'recording' ? 'red' : active ? ACCENT : 'gray'}
+      paddingX={1}
+    >
+      <Text color={ACCENT} bold>
+        {'❯ '}
+      </Text>
+      {input === '' ? (
+        <Text dimColor>
+          Type a message, @file to attach, or hold Ctrl+R to talk
+        </Text>
+      ) : (
+        <Text>{input}</Text>
+      )}
+      <Text inverse> </Text>
     </Box>
   )
 }
 
 const HELP = [
-  'Voice: press Ctrl+R, speak, press Ctrl+R again. Name a file ("use cat dot png") or say "the last image" to send it too.',
-  '/voice <audio file>  send a recorded voice message',
-  '/mic [n]  list the microphones, or record from microphone n',
-  '/open [n]  open media file n (default: the last one)',
-  '/play [n]  play audio or video file n',
-  '/connect <id>, /disconnect <id>  sign in to notion or linear',
-  '@path in a message sends that file. /exit quits.',
+  'Voice: hold Ctrl+R and talk, then let go. Or tap Ctrl+R, talk, tap again.',
+  '  Name a file ("use cat dot png") or say "the last image" to send it too.',
+  '  The first recording listens on all microphones and keeps the loudest.',
+  '/mic [n]      list the microphones, or record from microphone n',
+  '/voice <file> send a recorded voice message',
+  '/open [n]     open media file n (default: the last one)',
+  '/play [n]     play audio or video file n',
+  '/connect <id> sign in to notion or linear (/disconnect <id>)',
+  '/exit         quit',
 ]
 
+// A key held down repeats. Repeats closer than this are one press.
+const REPEAT_GAP = 1100
+// After the last repeat, the key is up when no repeat comes for this long.
+const RELEASE_WAIT = 450
+
 function App({ view }: { view: SessionView }) {
   const { exit } = useApp()
   const messages = useSelector(view.store, (state) => state.messages)
   const saved = useSavedMedia(view, messages)
   const [input, setInput] = useState('')
-  const [voice, setVoice] = useState<VoiceState>('idle')
-  const [microphone, setMicrophone] = useState('')
+  const [voice, setVoiceState] = useState<VoiceState>('idle')
+  // The phase in a ref too: key events come faster than React renders, and a
+  // second Ctrl+R must see "starting" at once, or it starts a second recorder.
+  const phase = useRef<VoiceState>('idle')
+  const setVoice = (next: VoiceState) => {
+    phase.current = next
+    setVoiceState(next)
+  }
   const recording = useRef<Recording | undefined>(undefined)
+  const [recorder, setRecorder] = useState<Recording | undefined>(undefined)
+  const talk = useRef({
+    last: 0,
+    holding: false,
+    stopWanted: false,
+    cancelWanted: false,
+  })
+  const release = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
 
   const fail = (error: unknown) =>
     view.notice(
@@ -364,14 +567,17 @@ function App({ view }: { view: SessionView }) {
     )
 
   /** A voice message: transcribe it, attach the files it names, and send it. */
-  const hear = async (audio: Uint8Array, name: string) => {
+  const hear = async (audio: Uint8Array, name: string, clip?: VoiceClip) => {
     setVoice('transcribing')
     try {
-      // A recording from the microphone that holds only silence is not sent:
-      // transcription models make up words for it.
-      if (name === 'voice.wav' && isSilent(audio))
+      if (clip?.pickedMicrophone)
+        view.notice(
+          `Voice: using "${clip.microphone}" from now on. /mic changes it.`,
+        )
+      // Transcription models make up words for silence, so it is not sent.
+      if (clip && isSilent(clip))
         return view.notice(
-          `Voice: only silence from "${await currentMicrophone()}". Speak closer, or pick another microphone with /mic.`,
+          `Voice: only silence from "${clip.microphone}". Hold Ctrl+R while you talk, or pick another microphone with /mic.`,
         )
       const text = await transcribe(audio, name)
       if (text === '') return view.notice('Voice: no speech heard.')
@@ -383,9 +589,6 @@ function App({ view }: { view: SessionView }) {
         [playground, mediaDir],
         recent,
       )
-      const files =
-        message.files.length > 0 ? ` (files: ${message.files.join(', ')})` : ''
-      view.notice(`Heard: "${text}"${files}`)
       await view.send(message.text)
     } catch (error) {
       fail(error)
@@ -394,23 +597,70 @@ function App({ view }: { view: SessionView }) {
     }
   }
 
-  const toggleVoice = async () => {
-    if (voice === 'transcribing') return
+  const stopTalking = async () => {
+    clearTimeout(release.current)
     const current = recording.current
-    if (current) {
-      recording.current = undefined
-      await current.stop().then((audio) => hear(audio, 'voice.wav'), fail)
+    if (!current) {
+      // Still opening: stop as soon as it is open.
+      talk.current.stopWanted = true
       return
     }
+    recording.current = undefined
+    setRecorder(undefined)
+    await current
+      .stop()
+      .then((clip) => hear(clip.audio, 'voice.wav', clip), fail)
+  }
+
+  const startTalking = async () => {
+    if (!canTranscribe())
+      return view.notice(
+        'Voice: set OPENAI_API_KEY or XAI_API_KEY in .env to turn voice on.',
+      )
+    talk.current = {
+      last: Date.now(),
+      holding: false,
+      stopWanted: false,
+      cancelWanted: false,
+    }
+    setVoice('starting')
     try {
-      recording.current = await startRecording()
+      const started = await startRecording()
+      if (talk.current.cancelWanted) {
+        started.cancel()
+        setVoice('idle')
+        return
+      }
+      recording.current = started
+      setRecorder(started)
       setVoice('recording')
-      setMicrophone(await currentMicrophone().catch(() => 'the default input'))
+      if (talk.current.stopWanted) await stopTalking()
     } catch (error) {
+      setVoice('idle')
       fail(error)
     }
   }
 
+  /**
+   * Ctrl+R. A terminal sends no key-up, only repeats while a key is held. So
+   * repeats mean "held": the recording stops when they stop. A single press
+   * starts, and the next single press stops.
+   */
+  const onTalkKey = () => {
+    const now = Date.now()
+    const gap = now - talk.current.last
+    talk.current.last = now
+    if (phase.current === 'transcribing') return
+    if (phase.current === 'idle') return void startTalking()
+    if (gap < REPEAT_GAP) {
+      talk.current.holding = true
+      clearTimeout(release.current)
+      release.current = setTimeout(() => void stopTalking(), RELEASE_WAIT)
+      return
+    }
+    if (!talk.current.holding) void stopTalking()
+  }
+
   /** The saved media file `/open 2` or `/play` names. */
   const pick = (arg: string | undefined) => {
     const ready = saved.filter((item) => item.path !== undefined)
@@ -445,10 +695,15 @@ function App({ view }: { view: SessionView }) {
     }
     if (text === '/exit') return exit()
     if (text === '/help') {
+      const off = features
+        .filter((feature) => !feature.on)
+        .map(
+          (feature) => `  ${feature.name} is off: it needs ${feature.needs}.`,
+        )
       const commands = state.commands.map(
         (command) => `/${command.name}  ${command.description}`,
       )
-      view.notice([...HELP, ...commands].join('\n'))
+      view.notice([...HELP, ...off, ...commands].join('\n'))
       return
     }
     const [command, ...rest] = text.split(' ')
@@ -459,25 +714,28 @@ function App({ view }: { view: SessionView }) {
         return []
       })
       const chosen = arg ? names[Number(arg) - 1] : undefined
-      if (chosen) chooseMicrophone(chosen)
-      const current = await currentMicrophone().catch(() => undefined)
+      if (chosen) await chooseMicrophone(chosen)
+      const current = await currentMicrophone()
       view.notice(
         names.length === 0
           ? `Recording from the default input${current ? ` (${current})` : ''}.`
           : [
               ...names.map(
                 (name, index) =>
-                  `${name === current ? '*' : ' '} ${index + 1}. ${name}`,
+                  `${name === current ? '●' : '○'} ${index + 1}. ${name}`,
               ),
-              '/mic <n> records from microphone n.',
+              current
+                ? '/mic <n> records from microphone n.'
+                : 'No microphone yet: the first recording picks the loudest.',
             ].join('\n'),
       )
       return
     }
     if (command === '/voice') {
       if (!arg) return view.notice('Give an audio file: /voice note.m4a')
-      const audio = await readFile(arg.replace(/^@|^"|"$/g, '')).catch(fail)
-      if (audio) await hear(new Uint8Array(audio), basename(arg))
+      const path = arg.replace(/^@|^"|"$/g, '')
+      const audio = await readFile(path).catch(fail)
+      if (audio) await hear(new Uint8Array(audio), basename(path))
       return
     }
     if (command === '/open' || command === '/play') {
@@ -492,15 +750,21 @@ function App({ view }: { view: SessionView }) {
     await view.send(text)
   }
 
+  usePaste((text) => setInput((current) => current + text))
+
   useInput((character, key) => {
-    if (key.ctrl && character === 'r') {
-      void toggleVoice()
-      return
-    }
+    if (key.ctrl && character === 'r') return onTalkKey()
     if (key.escape) {
+      clearTimeout(release.current)
+      if (phase.current === 'starting') {
+        // Drop the recording as soon as the microphone is open.
+        talk.current.cancelWanted = true
+        return
+      }
       const current = recording.current
       if (current) {
         recording.current = undefined
+        setRecorder(undefined)
         current.cancel()
         setVoice('idle')
         return
@@ -509,10 +773,8 @@ function App({ view }: { view: SessionView }) {
       return
     }
     if (key.return) {
-      if (recording.current) {
-        void toggleVoice()
-        return
-      }
+      if (phase.current === 'recording' || phase.current === 'starting')
+        return void stopTalking()
       setInput('')
       void submit(input)
       return
@@ -528,14 +790,15 @@ function App({ view }: { view: SessionView }) {
   return (
     <Box flexDirection="column">
       <Header view={view} />
-      {messages.slice(-200).map((message) => (
+      {messages.slice(-60).map((message) => (
         <Message key={message.id} message={message} saved={saved} />
       ))}
-      <Status view={view} voice={voice} microphone={microphone} />
-      <Text>
-        <Text color="cyan">{'> '}</Text>
-        {input}
-        <Text inverse> </Text>
+      <Status view={view} voice={voice} recording={recorder} />
+      <InputBox input={input} voice={voice} />
+      <Text dimColor>
+        {
+          '  Ctrl+R talk   Esc cancel   /model   /mic   /open   /play   /help   /exit'
+        }
       </Text>
     </Box>
   )
@@ -551,21 +814,31 @@ export async function runTui(view: SessionView, io: RenderOptions = {}) {
   view.on('signIn', (signIn) => {
     if (signIn.url) openExternal(signIn.url)
   })
-  view.notice(
-    'Type a message, or press Ctrl+R to talk. /help lists the commands.',
-  )
-  // ponytail: the adapters warn on the console about tool schemas they send
-  // without strict mode. Ink prints console output above the screen, so the
-  // screen drops only those warnings.
-  const warn = console.warn
-  console.warn = (...args: Array<unknown>) => {
-    if (typeof args[0] === 'string' && args[0].includes('[tanstack-ai:warn]'))
-      return
-    warn(...args)
+  const keys = ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'XAI_API_KEY']
+  if (!keys.some((key) => process.env[key]))
+    view.notice('No API keys yet: copy .env.example to .env and add yours.')
+  view.notice('Hold Ctrl+R to talk, or type. /help lists the commands.')
+  // ponytail: the SDK logs its warnings and errors on the console (the message,
+  // then its details with console.dir). Ink prints console output above the
+  // screen, and the screen shows those errors itself, so it drops them.
+  const { warn, error, dir } = console
+  let dropDetails = false
+  const quiet =
+    (log: (...args: Array<unknown>) => void) =>
+    (...args: Array<unknown>) => {
+      const text = typeof args[0] === 'string' ? args[0] : ''
+      dropDetails = /\[tanstack-ai:(warn|errors)\]/.test(text)
+      if (!dropDetails) log(...args)
+    }
+  console.warn = quiet(warn)
+  console.error = quiet(error)
+  console.dir = (...args: Parameters<typeof console.dir>) => {
+    if (dropDetails) dropDetails = false
+    else dir(...args)
   }
   try {
     await render(<App view={view} />, io).waitUntilExit()
   } finally {
-    console.warn = warn
+    Object.assign(console, { warn, error, dir })
   }
 }
diff --git a/examples/harness-cli/src/voice.ts b/examples/harness-cli/src/voice.ts
index de7ecf7dc6..2ae1f1398d 100644
--- a/examples/harness-cli/src/voice.ts
+++ b/examples/harness-cli/src/voice.ts
@@ -1,7 +1,8 @@
 import { execFile, spawn } from 'node:child_process'
-import { readFile, readdir, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { basename, extname, join, relative } from 'node:path'
+import type { ChildProcess } from 'node:child_process'
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { basename, dirname, extname, join, relative } from 'node:path'
 import { generateTranscription } from '@tanstack/ai'
 import { grokTranscription } from '@tanstack/ai-grok'
 import { openaiTranscription } from '@tanstack/ai-openai'
@@ -11,6 +12,14 @@ import { openaiTranscription } from '@tanstack/ai-openai'
 // `@path` attachments that the CLI sends with the message.
 
 const ffmpeg = process.env.FFMPEG_PATH || 'ffmpeg'
+const RATE = 16000
+// The microphone you picked, kept next to the sign-ins.
+const saved = join(homedir(), '.tanstack-harness-example', 'voice.json')
+
+/** Can this session turn speech into text? */
+export function canTranscribe() {
+  return Boolean(process.env.OPENAI_API_KEY || process.env.XAI_API_KEY)
+}
 
 /**
  * The audio inputs ffmpeg can record on Windows (DirectShow). Other systems
@@ -37,69 +46,163 @@ export function listMicrophones() {
   })
 }
 
-// The microphone `/mic <n>` picked. VOICE_DEVICE wins over it.
+// The microphone `/mic <n>` picked, or the first recording found.
 let picked: string | undefined
 
-/** Record from this microphone from now on. */
-export function chooseMicrophone(name: string) {
+/** Record from this microphone from now on, also after a restart. */
+export async function chooseMicrophone(name: string) {
   picked = name
+  await mkdir(dirname(saved), { recursive: true })
+  await writeFile(saved, JSON.stringify({ microphone: name }, null, 2))
 }
 
-/**
- * The microphone to record from: VOICE_DEVICE, the one `/mic` picked, or the
- * first real microphone in the list (not a capture card or a virtual input).
- */
+/** The microphone to record from, when one is set: VOICE_DEVICE, then yours. */
 export async function currentMicrophone() {
   if (process.env.VOICE_DEVICE) return process.env.VOICE_DEVICE
   if (picked) return picked
+  try {
+    const parsed: unknown = JSON.parse(await readFile(saved, 'utf8'))
+    if (
+      typeof parsed === 'object' &&
+      parsed !== null &&
+      'microphone' in parsed &&
+      typeof parsed.microphone === 'string'
+    )
+      picked = parsed.microphone
+  } catch {
+    // No saved microphone yet.
+  }
+  return picked
+}
+
+/**
+ * The inputs a first recording listens on: every microphone, without capture
+ * cards and virtual inputs (they are often silent).
+ */
+async function candidateMicrophones() {
   const names = await listMicrophones()
-  const real = names.find(
-    (name) => /microphone|mic\b/i.test(name) && !/virtual/i.test(name),
+  const real = names.filter(
+    (name) => !/hdmi|cam link|virtual|stereo mix|line in/i.test(name),
   )
-  const name = real ?? names[0]
-  if (!name)
-    throw new Error('No microphone found. Set VOICE_DEVICE to its name.')
-  return name
+  return real.length > 0 ? real : names
 }
 
-/** The ffmpeg input arguments for the microphone. */
-async function microphoneInput() {
+/** The ffmpeg input arguments for one microphone. */
+function microphoneInput(name: string | undefined) {
   if (process.platform === 'win32')
-    return ['-f', 'dshow', '-i', `audio=${await currentMicrophone()}`]
+    return ['-f', 'dshow', '-i', `audio=${name}`]
   if (process.platform === 'darwin')
-    return ['-f', 'avfoundation', '-i', `:${process.env.VOICE_DEVICE || '0'}`]
-  return ['-f', 'pulse', '-i', process.env.VOICE_DEVICE || 'default']
+    return ['-f', 'avfoundation', '-i', `:${name ?? '0'}`]
+  return ['-f', 'pulse', '-i', name ?? 'default']
 }
 
-export interface Recording {
-  /** Stop, and give the recorded audio (16 kHz mono WAV). */
-  stop: () => Promise<Uint8Array>
-  /** Stop and drop the audio. */
-  cancel: () => void
+/** The root mean square of 16-bit samples, without a constant offset. */
+function rms(samples: Int16Array) {
+  if (samples.length === 0) return 0
+  let sum = 0
+  let squares = 0
+  for (const sample of samples) {
+    sum += sample
+    squares += sample * sample
+  }
+  const mean = sum / samples.length
+  return Math.sqrt(Math.max(0, squares / samples.length - mean * mean))
 }
 
-/** Start recording the microphone until `stop` or `cancel`. */
-export async function startRecording(): Promise<Recording> {
-  const file = join(tmpdir(), `harness-voice-${Date.now()}.wav`)
+function samplesOf(pcm: Uint8Array) {
+  return new Int16Array(
+    pcm.buffer.slice(pcm.byteOffset, pcm.byteOffset + (pcm.byteLength & ~1)),
+  )
+}
+
+/**
+ * How much speech a clip holds, from its 100 ms windows:
+ * - `peak`: the loudness of the loud part (90th percentile), 0 to 32768.
+ * - `floor`: the loudness of the quiet part (20th percentile), the noise.
+ * Speech makes the peak much louder than the floor. Steady noise and a few
+ * clicks do not, so they read as silence.
+ */
+export function speechStats(pcm: Uint8Array) {
+  const samples = samplesOf(pcm)
+  const size = RATE / 10
+  const windows: Array<number> = []
+  for (let start = 0; start + size <= samples.length; start += size)
+    windows.push(rms(samples.subarray(start, start + size)))
+  windows.sort((a, b) => a - b)
+  const at = (share: number) =>
+    windows[Math.min(windows.length - 1, Math.floor(windows.length * share))] ??
+    0
+  return { peak: at(0.9), floor: at(0.2) }
+}
+
+/** How clearly a clip holds speech: the peak over the noise floor. */
+function speechScore(stats: { peak: number; floor: number }) {
+  return stats.peak / Math.max(stats.floor, 30)
+}
+
+/** A 16 kHz mono 16-bit WAV file for raw samples. */
+function wavFile(pcm: Uint8Array) {
+  const header = new DataView(new ArrayBuffer(44))
+  const text = (offset: number, value: string) => {
+    for (let index = 0; index < 4; index++)
+      header.setUint8(offset + index, value.charCodeAt(index))
+  }
+  text(0, 'RIFF')
+  header.setUint32(4, 36 + pcm.byteLength, true)
+  text(8, 'WAVE')
+  text(12, 'fmt ')
+  header.setUint32(16, 16, true)
+  header.setUint16(20, 1, true)
+  header.setUint16(22, 1, true)
+  header.setUint32(24, RATE, true)
+  header.setUint32(28, RATE * 2, true)
+  header.setUint16(32, 2, true)
+  header.setUint16(34, 16, true)
+  text(36, 'data')
+  header.setUint32(40, pcm.byteLength, true)
+  const file = new Uint8Array(44 + pcm.byteLength)
+  file.set(new Uint8Array(header.buffer))
+  file.set(pcm, 44)
+  return file
+}
+
+// Every ffmpeg recorder that runs. They are stopped when the app exits, so no
+// recorder keeps the microphone open after it.
+const recorders = new Set<ChildProcess>()
+process.once('exit', () => {
+  for (const child of recorders) child.kill()
+})
+
+/** One ffmpeg process that streams raw samples from one microphone. */
+function capture(name: string | undefined) {
   const child = spawn(
     ffmpeg,
     [
       '-hide_banner',
       '-loglevel',
       'error',
-      ...(await microphoneInput()),
+      ...microphoneInput(name),
       '-ac',
       '1',
       '-ar',
-      '16000',
-      '-y',
-      file,
+      String(RATE),
+      '-f',
+      's16le',
+      'pipe:1',
     ],
-    { stdio: ['pipe', 'ignore', 'pipe'] },
+    { stdio: ['pipe', 'pipe', 'pipe'] },
   )
+  recorders.add(child)
+  child.on('exit', () => recorders.delete(child))
+  const chunks: Array<Buffer> = []
+  let level = 0
   let errors = ''
+  child.stdout.on('data', (chunk: Buffer) => {
+    chunks.push(chunk)
+    level = rms(samplesOf(chunk))
+  })
   child.stderr.on('data', (chunk: Buffer) => (errors += chunk.toString()))
-  const exited = new Promise<number | null>((resolve, reject) => {
+  const exited = new Promise<void>((resolve, reject) => {
     child.on('error', (error: NodeJS.ErrnoException) =>
       reject(
         error.code === 'ENOENT'
@@ -107,86 +210,133 @@ export async function startRecording(): Promise<Recording> {
           : error,
       ),
     )
-    child.on('exit', resolve)
+    child.on('exit', () => resolve())
   })
-  // ffmpeg stops at once when the device does not open.
-  const early = await Promise.race([
-    exited.then(() => 'exited' as const),
-    new Promise<'running'>((resolve) =>
-      setTimeout(() => resolve('running'), 400),
-    ),
-  ])
-  if (early === 'exited')
-    throw new Error(`The microphone did not open. ${errors.trim()}`.trim())
+  let running = true
+  void exited.then(
+    () => (running = false),
+    () => (running = false),
+  )
   return {
+    name: name ?? 'the default input',
+    exited,
+    isRunning: () => running,
+    errors: () => errors.trim(),
+    level: () => level,
+    pcm: () => new Uint8Array(Buffer.concat(chunks)),
     stop: async () => {
-      // `q` makes ffmpeg finish the file.
+      // `q` makes ffmpeg stop cleanly. Kill it if it does not.
       child.stdin.end('q')
-      await exited
-      try {
-        return new Uint8Array(await readFile(file))
-      } finally {
-        await rm(file, { force: true })
-      }
-    },
-    cancel: () => {
-      child.kill()
-      void exited.finally(() => rm(file, { force: true }))
+      const timer = setTimeout(() => child.kill(), 2000)
+      await exited.catch(() => {})
+      clearTimeout(timer)
     },
+    kill: () => child.kill(),
   }
 }
 
-/** Where the samples of a WAV file start: after its `data` chunk header. */
-function wavDataStart(wav: Uint8Array) {
-  // ffmpeg adds a LIST chunk, so the header is not always 44 bytes.
-  const view = new DataView(wav.buffer, wav.byteOffset, wav.byteLength)
-  for (let offset = 12; offset + 8 <= wav.byteLength;) {
-    const id = String.fromCharCode(...wav.subarray(offset, offset + 4))
-    const size = view.getUint32(offset + 4, true)
-    if (id === 'data') return offset + 8
-    offset += 8 + size + (size % 2)
-  }
-  return wav.byteLength
+/** A voice message from the microphone. */
+export interface VoiceClip {
+  /** 16 kHz mono WAV. */
+  audio: Uint8Array
+  /** The loud part and the noise floor, from 0 to 32768. */
+  peak: number
+  floor: number
+  microphone: string
+  /** True when this recording picked the microphone (the clearest one). */
+  pickedMicrophone: boolean
+}
+
+export interface Recording {
+  /** The microphone, or "all microphones" while the first recording picks one. */
+  microphone: string
+  /** The loudness right now, from 0 to 32768, for a level meter. */
+  level: () => number
+  /** Stop, and give the voice message. */
+  stop: () => Promise<VoiceClip>
+  /** Stop and drop the audio. */
+  cancel: () => void
 }
 
 /**
- * The loudness of a WAV recording: the root mean square of its 16-bit
- * samples, from 0 to 32768, without the constant offset some microphones add.
+ * Start recording until `stop` or `cancel`. With no microphone set yet, it
+ * listens on every microphone, keeps the one that heard speech the clearest,
+ * and remembers it.
  */
-export function loudness(wav: Uint8Array) {
-  const start = wav.byteOffset + wavDataStart(wav)
-  const count = Math.floor((wav.byteOffset + wav.byteLength - start) / 2)
-  const samples = new Int16Array(wav.buffer.slice(start, start + count * 2))
-  if (samples.length === 0) return 0
-  let sum = 0
-  let squares = 0
-  for (const sample of samples) {
-    sum += sample
-    squares += sample * sample
+export async function startRecording(): Promise<Recording> {
+  const chosen = await currentMicrophone()
+  const names =
+    chosen !== undefined || process.platform !== 'win32'
+      ? [chosen]
+      : await candidateMicrophones()
+  if (names.length === 0)
+    throw new Error('No microphone found. Set VOICE_DEVICE to its name.')
+  const captures = names.map(capture)
+  // ffmpeg stops at once when a device does not open.
+  await new Promise((resolve) => setTimeout(resolve, 400))
+  const live = captures.filter((item) => item.isRunning())
+  if (live.length === 0) {
+    const errors = captures.map((item) => item.errors()).filter(Boolean)
+    throw new Error(`The microphone did not open. ${errors.join(' ')}`.trim())
+  }
+  const picking = chosen === undefined && live.length > 1
+  return {
+    microphone: picking ? 'all microphones' : (live[0]?.name ?? ''),
+    level: () => Math.max(...live.map((item) => item.level())),
+    stop: async () => {
+      await Promise.all(live.map((item) => item.stop()))
+      const clips = live.map((item) => {
+        const pcm = item.pcm()
+        return { name: item.name, pcm, ...speechStats(pcm) }
+      })
+      const best = clips.reduce((clearest, clip) =>
+        speechScore(clip) > speechScore(clearest) ? clip : clearest,
+      )
+      const clip: VoiceClip = {
+        audio: wavFile(best.pcm),
+        peak: best.peak,
+        floor: best.floor,
+        microphone: best.name,
+        pickedMicrophone: false,
+      }
+      // Keep that microphone only when it heard speech: in silence, the
+      // clearest one means nothing.
+      if (picking && !isSilent(clip)) {
+        await chooseMicrophone(best.name)
+        clip.pickedMicrophone = true
+      }
+      return clip
+    },
+    cancel: () => {
+      for (const item of live) item.kill()
+    },
   }
-  const mean = sum / samples.length
-  return Math.sqrt(Math.max(0, squares / samples.length - mean * mean))
 }
 
 /**
- * Is a recording too quiet to hold speech? Transcription models make up words
- * for silence, so a quiet recording is not sent. VOICE_MIN_LOUDNESS changes
- * the limit.
+ * Is a clip silent? Transcription models make up words for silence, so a
+ * silent clip is not sent. A clip is silent when its loud part is under
+ * VOICE_MIN_LOUDNESS (default 300), for example a muted microphone.
  */
-export function isSilent(wav: Uint8Array) {
-  return loudness(wav) < Number(process.env.VOICE_MIN_LOUDNESS || 300)
+export function isSilent(clip: Pick<VoiceClip, 'peak'>) {
+  return clip.peak < Number(process.env.VOICE_MIN_LOUDNESS || 300)
 }
 
 /**
  * The words in `audio`, with OpenAI, or Grok when only an xAI key is set.
- * `name` gives the format, for example `voice.wav`.
+ * `name` gives the format, for example `voice.wav`. VOICE_LANGUAGE (an
+ * ISO-639-1 code such as `en`) tells the model which language to expect.
  */
 export async function transcribe(audio: Uint8Array, name = 'voice.wav') {
   const file = new File([audio.slice()], name)
+  const language = process.env.VOICE_LANGUAGE
+    ? { language: process.env.VOICE_LANGUAGE }
+    : {}
   if (process.env.OPENAI_API_KEY) {
     const result = await generateTranscription({
       adapter: openaiTranscription('gpt-4o-transcribe'),
       audio: file,
+      ...language,
     })
     return result.text.trim()
   }
@@ -194,6 +344,7 @@ export async function transcribe(audio: Uint8Array, name = 'voice.wav') {
     const result = await generateTranscription({
       adapter: grokTranscription('grok-stt'),
       audio: file,
+      ...language,
     })
     return result.text.trim()
   }

From 6a90d924b0a14e38cfd52f14b8ece679c7bc8bee Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 29 Sep 2026 19:05:40 +0200
Subject: [PATCH 068/286] feat(ai, ai-harness, ai-openrouter): users connect
 their own model provider keys with /connect

A harness that ships to users no longer needs a .env file. Users connect a provider inside the app, and each user's key is kept in the harness credential store.

- @tanstack/ai: keyedAdapter(provider, create) builds an adapter from a key when it is needed, and agents get ctx.keys (get, require, adapter). A host sets the keys on the subagent binding, and children pass them down. Without a host, ctx.keys reads the provider's env var.
- @tanstack/ai-harness: the harness adapter, /model choices, compact, and goal take keyed adapters, and the session builds them per turn from the user's saved key, then the env var. A missing key stops the turn with harness.auth_required ("run /connect openai"). The new providerKeys() plugin adds /connect <provider> (a hidden key prompt, or a provider's own sign-in), /disconnect, and /keys, with plugin state for UIs. Questions can be secret, and a secret answer is never stored or shown.
- @tanstack/ai-openrouter: openrouterSignIn() signs in through the browser (PKCE with a 127.0.0.1 callback) and returns a key.
- @tanstack/ai-harness-cli: line mode hides the typing of a secret answer.
- The example lists every provider in /model, the media agents use ctx.keys, the screen hides a key as it is typed, and the header shows which providers are connected.
- Docs: a new page, "Connect model providers", and a section on keys inside agents.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/core-provider-keys.md              |   5 +
 .changeset/harness-provider-keys.md           |  10 +
 .changeset/openrouter-sign-in.md              |   5 +
 docs/advanced/byok.md                         |  29 ++
 docs/config.json                              |  10 +-
 docs/harness/cli.md                           |   2 +-
 docs/harness/overview.md                      |   2 +
 docs/harness/provider-keys.md                 | 181 ++++++++
 examples/harness-cli/.env.example             |  12 +-
 examples/harness-cli/README.md                |  47 ++-
 examples/harness-cli/package.json             |   1 +
 examples/harness-cli/src/credentials.ts       |   6 +-
 examples/harness-cli/src/harness.ts           | 187 +++++----
 examples/harness-cli/src/media.ts             |  97 +++--
 examples/harness-cli/src/store.ts             |  29 +-
 examples/harness-cli/src/tui.tsx              | 180 ++++++--
 examples/harness-cli/src/voice.ts             |  47 ++-
 packages/ai-harness-cli/src/commands.ts       |   3 +-
 packages/ai-harness-cli/src/lines.ts          | 102 ++++-
 packages/ai-harness-cli/src/printer.ts        |  15 +-
 packages/ai-harness-cli/tests/cli.test.ts     |  58 +++
 packages/ai-harness/src/auth.ts               |  54 ++-
 packages/ai-harness/src/commands.ts           |   5 +
 packages/ai-harness/src/define.ts             |   9 +-
 packages/ai-harness/src/first-party/goal.ts   |  12 +-
 packages/ai-harness/src/first-party/index.ts  |   1 +
 .../src/first-party/model-picker.ts           |  16 +-
 .../src/first-party/provider-keys.ts          | 152 +++++++
 .../src/first-party/session-tools.ts          |   8 +-
 packages/ai-harness/src/harness-text.ts       |   3 +-
 packages/ai-harness/src/plugins.ts            |  25 +-
 packages/ai-harness/src/session.ts            |  51 ++-
 packages/ai-harness/src/view/index.ts         |   1 +
 packages/ai-harness/src/view/types.ts         |   2 +
 .../ai-harness/tests/provider-keys.test.ts    | 392 ++++++++++++++++++
 packages/ai-openrouter/src/pkce.ts            | 150 ++++++-
 .../ai-openrouter/tests/pkce-sign-in.test.ts  | 116 ++++++
 .../ai/src/activities/chat/agents/bound.ts    |  12 +-
 .../activities/chat/agents/define-agent.ts    |   8 +-
 .../ai/src/activities/chat/agents/spawn.ts    |   6 +-
 packages/ai/src/byok.ts                       |   2 +
 packages/ai/src/byok/env-keys.ts              |  31 ++
 packages/ai/src/byok/get-key.ts               |  29 +-
 packages/ai/src/byok/keyed.ts                 |  85 ++++
 packages/ai/src/index.ts                      |   6 +
 packages/ai/tests/provider-keys.test.ts       | 177 ++++++++
 pnpm-lock.yaml                                |   3 +
 47 files changed, 2121 insertions(+), 263 deletions(-)
 create mode 100644 .changeset/core-provider-keys.md
 create mode 100644 .changeset/harness-provider-keys.md
 create mode 100644 .changeset/openrouter-sign-in.md
 create mode 100644 docs/harness/provider-keys.md
 create mode 100644 packages/ai-harness/src/first-party/provider-keys.ts
 create mode 100644 packages/ai-harness/tests/provider-keys.test.ts
 create mode 100644 packages/ai-openrouter/tests/pkce-sign-in.test.ts
 create mode 100644 packages/ai/src/byok/env-keys.ts
 create mode 100644 packages/ai/src/byok/keyed.ts
 create mode 100644 packages/ai/tests/provider-keys.test.ts

diff --git a/.changeset/core-provider-keys.md b/.changeset/core-provider-keys.md
new file mode 100644
index 0000000000..8280582361
--- /dev/null
+++ b/.changeset/core-provider-keys.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai': minor
+---
+
+`keyedAdapter(provider, create)` wraps an adapter factory that needs a provider key, and `isKeyedAdapter` tells it apart from a plain adapter. Agents get `ctx.keys` (`get`, `require`, and `adapter`) from the new `SubagentBinding.keys`, or else from each provider's `env` names.
diff --git a/.changeset/harness-provider-keys.md b/.changeset/harness-provider-keys.md
new file mode 100644
index 0000000000..3c8dd3962f
--- /dev/null
+++ b/.changeset/harness-provider-keys.md
@@ -0,0 +1,10 @@
+---
+'@tanstack/ai-harness': minor
+'@tanstack/ai-harness-cli': patch
+---
+
+Users of a shipped harness can connect their own model provider in the app, with no `.env` file. The new `providerKeys({ providers })` plugin in `@tanstack/ai-harness/plugins` adds `/connect <id>`, `/disconnect <id>`, and `/keys`. `/connect` runs the provider's `signIn` when it has one, or else asks the user to paste the key. The key is saved in the credential store of the user. `/keys` and the plugin state show where each key comes from: a saved key (the last 4 characters only), the env var, or no key.
+
+`defineHarness({ adapter })`, the `modelPicker` choices, `compact({ adapter })`, and `goal({ judge })` now accept a `keyedAdapter(...)`. The session builds it with the user's key just before each call. The saved key comes first, then the provider's env var. When there is no key, the turn stops with `harness.auth_required`, so the user sees `/connect <id>`. Agents get the same keys as `ctx.keys`, and plugins get them as `ctx.keys` on their setup context.
+
+A `Question` can set `secret: true`. The view gives it as `ViewQuestion.secret`, and the session does not keep a secret answer in the inbox. In a terminal, the CLI line mode hides what the user types for a secret question, and it never prints the answer.
diff --git a/.changeset/openrouter-sign-in.md b/.changeset/openrouter-sign-in.md
new file mode 100644
index 0000000000..1be7b413c2
--- /dev/null
+++ b/.changeset/openrouter-sign-in.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-openrouter': minor
+---
+
+Add `openrouterSignIn()` at `@tanstack/ai-openrouter/pkce`: a local app, such as a CLI, signs the user in to OpenRouter in the browser and gets an API key, with no key to copy.
diff --git a/docs/advanced/byok.md b/docs/advanced/byok.md
index cfcb72faf9..cdd67c5e60 100644
--- a/docs/advanced/byok.md
+++ b/docs/advanced/byok.md
@@ -182,6 +182,35 @@ byok.setServerCoverage(true);
 
 Then a send with no pasted key still POSTs. The relay uses the env key. If that is also empty, the relay returns `byokMissing` (401). The client sets `snapshot.prompt`.
 
+## Keys inside agents
+
+An agent that calls a model needs a key too. Wrap the adapter in `keyedAdapter`. Before the call, the agent makes it with `ctx.keys`:
+
+```typescript
+import { defineAgent, keyedAdapter } from "@tanstack/ai";
+import { createOpenaiChat } from "@tanstack/ai-openai";
+import { openaiByok } from "@tanstack/ai-openai/byok";
+
+const gpt = keyedAdapter(openaiByok, (key) =>
+  createOpenaiChat("gpt-6-astra", key),
+);
+
+export const writer = defineAgent({
+  name: "writer",
+  description: "Writes a short draft",
+  run: async (ctx) =>
+    ctx.chat({
+      adapter: await ctx.keys.adapter(gpt),
+      messages: [{ role: "user", content: "Write a short draft." }],
+      stream: false,
+    }),
+});
+```
+
+- Without a host, `ctx.keys` reads the env var of the provider, here `OPENAI_API_KEY`. If it is empty, the call throws `Missing OpenAI API key. Set OPENAI_API_KEY.`
+- A host can give its own keys in `subagents.binding.keys`. A child agent gives them to its own children.
+- In a harness, `ctx.keys` reads the key that each user saved with `/connect`. See [Connect model providers](../harness/provider-keys).
+
 ## Image, audio, and OpenRouter
 
 For other cases:
diff --git a/docs/config.json b/docs/config.json
index e8e81c4154..5b27976156 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -870,7 +870,8 @@
         {
           "label": "Build your first harness",
           "to": "harness/overview",
-          "addedAt": "2026-09-26"
+          "addedAt": "2026-09-26",
+          "updatedAt": "2026-09-29"
         },
         {
           "label": "Connect clients",
@@ -906,6 +907,11 @@
           "addedAt": "2026-09-26",
           "updatedAt": "2026-09-28"
         },
+        {
+          "label": "Connect model providers",
+          "to": "harness/provider-keys",
+          "addedAt": "2026-09-29"
+        },
         {
           "label": "Auth and connectors",
           "to": "harness/auth",
@@ -1171,7 +1177,7 @@
           "label": "Bring Your Own Key",
           "to": "advanced/byok",
           "addedAt": "2026-08-18",
-          "updatedAt": "2026-09-04"
+          "updatedAt": "2026-09-29"
         },
         {
           "label": "Debug Logging",
diff --git a/docs/harness/cli.md b/docs/harness/cli.md
index 1aecb74cfa..42364b1bce 100644
--- a/docs/harness/cli.md
+++ b/docs/harness/cli.md
@@ -77,7 +77,7 @@ For the session:
 - `/agents`: list the agents.
 - `/agent <name> {"json":"input"}`: run an agent in the background. When it is done, a new turn starts with its result.
 - `/config`: show the settings. `/config <key> <value>` changes one.
-- `/connect <id>` and `/disconnect <id>`: sign in to a connector, or out.
+- `/connect <id>` and `/disconnect <id>`: sign in to a connector, or out. With [`providerKeys`](./provider-keys), they also connect a model provider, for example `/connect openai`.
 
 For the running work:
 
diff --git a/docs/harness/overview.md b/docs/harness/overview.md
index 5364f1e554..45d9cd8aad 100644
--- a/docs/harness/overview.md
+++ b/docs/harness/overview.md
@@ -58,6 +58,8 @@ export const assistant = defineHarness({
 
 `agents` are agents you run from code. Put an agent in `subagents` instead when the model must call it as a tool, the same as in `chat()`.
 
+To ship the harness to users with no `.env` file, let each user connect their own key. See [Connect model providers](./provider-keys).
+
 ## 2. Open a session
 
 A host runs sessions. Give it the stores from `@tanstack/ai-persistence`, then open a session for a conversation id.
diff --git a/docs/harness/provider-keys.md b/docs/harness/provider-keys.md
new file mode 100644
index 0000000000..65d140344d
--- /dev/null
+++ b/docs/harness/provider-keys.md
@@ -0,0 +1,181 @@
+---
+title: Connect model providers
+id: harness-provider-keys
+order: 7
+description: "Let each user connect their own OpenAI, Anthropic, xAI, fal, or OpenRouter key inside your app with /connect. A harness that you ship needs no .env file."
+keywords:
+  - tanstack ai
+  - harness
+  - byok
+  - api key
+  - providerKeys
+  - keyedAdapter
+---
+
+You ship your harness to users: a CLI that they install, a desktop app, or a hosted app with accounts. `openaiText('gpt-6-astra')` reads `OPENAI_API_KEY` from the environment. Your users do not have your `.env` file, and they do not start your app from a terminal with a key set.
+
+With `providerKeys`, each user runs `/connect openai` in your app and pastes their own key. The harness saves the key for that user and uses it for every turn.
+
+## 1. Define keyed adapters
+
+A keyed adapter waits for a key. `keyedAdapter` takes the provider and a function that makes the adapter from the key:
+
+```ts group=harness-provider-keys
+import { keyedAdapter } from '@tanstack/ai'
+import { createAnthropicChat } from '@tanstack/ai-anthropic'
+import { anthropicByok } from '@tanstack/ai-anthropic/byok'
+import { createOpenaiChat } from '@tanstack/ai-openai'
+import { openaiByok } from '@tanstack/ai-openai/byok'
+
+const gpt = keyedAdapter(openaiByok, (key) => createOpenaiChat('gpt-6-astra', key))
+const claude = keyedAdapter(anthropicByok, (key) => createAnthropicChat('claude-sonnet-5', key))
+```
+
+- `openaiByok` describes the provider: the id `openai`, the label `OpenAI`, and the env var `OPENAI_API_KEY`.
+- Each provider package exports one from its `/byok` subpath, for example `anthropicByok`, `grokByok`, `falByok`, and `openrouterByok`.
+- `keyedAdapter` works for every adapter kind: text, image, speech, audio, and video.
+
+Before each turn, the session calls your function with the key of the user of that session.
+
+## 2. Add the providerKeys plugin
+
+Give the harness a keyed adapter as its `adapter`. Then list in `providerKeys` every provider that users can connect:
+
+```ts group=harness-provider-keys
+import { defineHarness } from '@tanstack/ai-harness'
+import { modelPicker, providerKeys } from '@tanstack/ai-harness/plugins'
+import { falByok } from '@tanstack/ai-fal/byok'
+import { grokByok } from '@tanstack/ai-grok/byok'
+import { openrouterByok } from '@tanstack/ai-openrouter/byok'
+import { openrouterSignIn } from '@tanstack/ai-openrouter/pkce'
+
+export const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: gpt,
+  plugins: () => [
+    providerKeys({
+      providers: [
+        openaiByok,
+        anthropicByok,
+        grokByok,
+        falByok,
+        { ...openrouterByok, signIn: openrouterSignIn() },
+      ],
+    }),
+    modelPicker({ choices: { gpt, claude }, default: 'gpt' }),
+  ],
+})
+```
+
+- For each provider, `providerKeys` adds `/connect <id>` and `/disconnect <id>`. It also adds `/keys`.
+- `modelPicker`, `compact`, and `goal` also take keyed adapters. After `/model claude`, the next turn uses the Anthropic key of the user.
+- `signIn` is optional. OpenRouter has one. See [Sign in with OpenRouter](#sign-in-with-openrouter).
+
+## 3. Connect a provider
+
+This is what your user does in the CLI:
+
+1. Run `/connect openai`.
+2. The harness asks `Paste your OpenAI API key`. In a terminal, the CLI hides what you type.
+3. Paste the key and press Enter.
+4. The CLI prints `Connected to OpenAI (key ...abcd).`
+
+`/disconnect openai` deletes the key. `/keys` shows where each key comes from:
+
+```text
+OpenAI: connected (key ...abcd)
+Anthropic: from the ANTHROPIC_API_KEY env var
+xAI Grok: missing. Run /connect grok.
+fal.ai: missing. Run /connect fal.
+OpenRouter: missing. Run /connect openrouter.
+```
+
+In [your own UI](./custom-ui), read the same list from `state.plugins['tanstack/provider-keys'].providers`. Each entry has an `id`, a `label`, and a `state`: `connected`, `env`, or `missing`. The key question has `secret: true`, so show a password field for it.
+
+### Sign in with OpenRouter
+
+OpenRouter has a browser sign-in, so users do not copy a key. `openrouterSignIn()` in the providers list turns it on:
+
+1. Run `/connect openrouter`.
+2. The CLI opens the OpenRouter sign-in page in the browser. Sign in and approve.
+3. The browser shows `You are signed in to OpenRouter. You can close this tab.`
+4. The CLI prints `Connected to OpenRouter (key ...wxyz).`
+
+The sign-in uses PKCE. It listens on `127.0.0.1` on a random port for one callback, and it checks a random state. After 10 minutes it stops. To change the time, pass `openrouterSignIn({ timeoutMs })`.
+
+The listener runs on the computer of the harness. So the sign-in works when the harness and the browser are on the same computer: a CLI or a desktop app. In a hosted app, remove `signIn`, and users paste their OpenRouter key.
+
+OpenAI and Anthropic have no sign-in for other apps, so users paste a key.
+
+## When a key is missing
+
+If a turn needs a key that the user did not connect, the turn stops before the model call:
+
+- Clients get a `harness.auth_required` event with the provider id.
+- The CLI prints `Sign in to openai. Run /connect openai.`
+- The turn fails with `Sign in to openai first. Run /connect openai.`
+
+After `/connect openai`, send the message again.
+
+## Where the keys are stored
+
+`/connect` saves the key in the credential store of the host, as an `api_key` credential with the provider id. The store keeps it for the user of the session:
+
+- CLI or desktop app: a file in the home folder of the user. The [CLI example](https://github.com/TanStack/ai/blob/main/examples/harness-cli/src/credentials.ts) has one. Give it to `runCli` in `persistence`.
+- Hosted app: your database. The principal that `authorize` returns is the user, so each user has their own keys. Write the store with `defineCredentialStore`, as in [Auth and connectors](./auth#keep-credentials).
+- No credential store: the keys stay in memory until the process stops.
+
+Encrypt the keys at rest in a real store.
+
+## The env var still works
+
+If the user has no saved key, the session reads the env var of the provider, for example `OPENAI_API_KEY`. A saved key wins over the env var. So you can develop with a `.env` file, and your users connect in the app.
+
+## Use the key of the user in an agent
+
+Your agent makes images with fal, so it needs the fal key of the user. Every agent gets `ctx.keys`. In a harness, `ctx.keys` reads the same keys as the turn:
+
+```ts group=harness-provider-keys
+import { defineAgent } from '@tanstack/ai'
+import { falImage } from '@tanstack/ai-fal'
+import { z } from 'zod'
+
+const flux = keyedAdapter(falByok, (key) => falImage('fal-ai/flux/dev', { apiKey: key }))
+
+export const illustrator = defineAgent({
+  name: 'illustrator',
+  description: 'Draws an image from a prompt',
+  inputSchema: z.object({ prompt: z.string() }),
+  run: async (ctx) =>
+    ctx.generateImage({
+      adapter: await ctx.keys.adapter(flux),
+      prompt: ctx.input.prompt,
+    }),
+})
+```
+
+Put the agent in `subagents.agents` of the harness, and the model calls it as a tool.
+
+- `ctx.keys.adapter(adapter)`: makes a keyed adapter with the key of the user. A plain adapter comes back unchanged.
+- `ctx.keys.get(provider)`: the key, or `null`.
+- `ctx.keys.require(provider)`: the key. If it is missing, the run stops with `harness.auth_required`, the same as a turn.
+- The children of the agent get the same keys.
+- Plugins get the same keys as `ctx.keys` in `setup`.
+
+Outside a harness, `ctx.keys` reads the env var. See [Keys inside agents](../advanced/byok#keys-inside-agents).
+
+## Keep keys safe
+
+- A key shows masked only: `...` and the last 4 characters.
+- The plugin never puts a key in an event, the transcript, or a command result.
+- The answer to the key question does not go into the inbox of the session.
+- Do not log a key. For error messages, use `maskKey` from `@tanstack/ai/byok`.
+
+## What you have now
+
+- `/connect` for OpenAI, Anthropic, xAI, fal, and OpenRouter in the harness that you ship, with no `.env` file.
+- One key for each user, in your credential store.
+- The env var as a fallback while you develop.
+- Agents and plugins that use the key of the user through `ctx.keys`.
+
+Next: serve the harness to signed-in users with [Connect clients](./connect).
diff --git a/examples/harness-cli/.env.example b/examples/harness-cli/.env.example
index 8022cddd20..6795c68083 100644
--- a/examples/harness-cli/.env.example
+++ b/examples/harness-cli/.env.example
@@ -1,13 +1,17 @@
-# Copy to .env. Without keys, a demo model answers.
-# Each key adds models to /model, and turns on the tools of that provider.
+# Optional. The app needs no .env file: run /connect openai (paste a key) or
+# /connect openrouter (sign in with the browser) inside the app.
+# This file is a shortcut for development. Copy it to .env. An env var works
+# when no key is saved with /connect.
 # OpenAI: the gpt models, images, speech, Sora video, and voice input.
 OPENAI_API_KEY=
 # Anthropic: the claude models.
 ANTHROPIC_API_KEY=
-# xAI: the grok model, and video with Grok Imagine (it wins over Sora).
+# xAI: the grok model, video with Grok Imagine (it wins over Sora), and voice.
 XAI_API_KEY=
 # fal: songs and sound effects.
 FAL_KEY=
+# OpenRouter: the openrouter-gpt and openrouter-claude models.
+OPENROUTER_API_KEY=
 # Claude Code and Codex turn on when `claude` and `codex` are on the PATH.
 # They use your own `claude login` and `codex login`. Set 0 to turn them off.
 CODING_AGENTS=
@@ -15,7 +19,7 @@ CODING_AGENTS=
 CODEX_MODEL=
 CODEX_SANDBOX_MODE=
 # Voice input records the microphone with ffmpeg. The first recording picks
-# the microphone; VOICE_DEVICE names one instead. VOICE_LANGUAGE (for example
+# the microphone. VOICE_DEVICE names one instead. VOICE_LANGUAGE (for example
 # en) is the language you talk in.
 FFMPEG_PATH=
 VOICE_DEVICE=
diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index 6c7c307f42..08551360e0 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -8,15 +8,42 @@ From the repo root:
 
 1. `pnpm install`
 2. `pnpm build:all` (the example uses the local packages)
-3. Copy `.env.example` to `.env` and set the keys you have. Each key turns on more (see the table). Without a key, a demo model answers.
-4. `pnpm --filter harness-cli-example start`
+3. `pnpm --filter harness-cli-example start`
+4. Type `/connect openai` and paste your OpenAI key. Or type `/connect openrouter` to sign in with the browser.
 
-| Key                 | Adds                                                          |
-| ------------------- | ------------------------------------------------------------- |
-| `OPENAI_API_KEY`    | the `gpt` models, images, speech, Sora video, and voice input |
-| `ANTHROPIC_API_KEY` | the `claude` models                                           |
-| `XAI_API_KEY`       | the `grok` model, and video with Grok Imagine                 |
-| `FAL_KEY`           | songs and sound effects                                       |
+Now send a message. After an OpenRouter sign-in, run `/model openrouter-gpt` first.
+
+## Connect your models
+
+You do not need a `.env` file. Connect each provider inside the app:
+
+- `/connect openai`: paste your key. The input shows dots, not the key.
+- `/connect openrouter`: sign in with the browser. OpenRouter gives the app a key.
+- `/keys`: show each provider and where its key comes from (saved, an env var, or missing).
+- `/disconnect openai`: delete the saved key.
+
+The app saves the key in `~/.tanstack-harness-example/credentials.json`. It shows only the last 4 characters of a key. The header shows which providers have a key, and it changes when you connect one.
+
+| Provider id  | Adds                                                                         |
+| ------------ | ---------------------------------------------------------------------------- |
+| `openai`     | the `gpt` and `gpt-fast` models, images, speech, Sora video, and voice input |
+| `anthropic`  | the `claude` and `claude-fast` models                                        |
+| `grok`       | the `grok` model, video with Grok Imagine, and voice input                   |
+| `fal`        | songs and sound effects                                                      |
+| `openrouter` | the `openrouter-gpt` and `openrouter-claude` models                          |
+
+If a provider has no key, its models and tools stop and tell you which `/connect` to run. If no key is set in the env, `/model demo` answers without a key.
+
+### Developer shortcut: a `.env` file
+
+1. Copy `.env.example` to `.env`.
+2. Set the keys that you have.
+
+An env var works when no key is saved. The first model with an env key starts. Audio files that you attach with `@file` become text only when `OPENAI_API_KEY` is set. Voice messages use the saved key.
+
+### Ship it to your users
+
+`src/harness.ts` wraps each model in `keyedAdapter`, and the `providerKeys` plugin adds `/connect`, `/disconnect`, and `/keys`. The harness saves the keys of each user in its credential store: a file here, your database in a hosted app. The guide is [Connect model providers](../../docs/harness/provider-keys.md).
 
 ## Talk to it
 
@@ -32,7 +59,7 @@ The first recording listens on every microphone, and keeps the one that heard yo
 - Set `VOICE_LANGUAGE=en` (or your language) so the transcript is in that language.
 - `/voice note.m4a` sends a voice message that you recorded before.
 
-Voice needs `ffmpeg` on the PATH, and `OPENAI_API_KEY` or `XAI_API_KEY` for the transcript.
+Voice needs `ffmpeg` on the PATH, and an OpenAI or xAI key for the transcript (`/connect openai` or `/connect grok`).
 
 ## Make media
 
@@ -45,6 +72,8 @@ Ask in words. The agent picks the tool:
 - `make a 5 second sound effect of rain on a window`
 - `make a short video of snow in a pine forest` (a minute or two)
 
+Each tool needs the key of its provider (see [Connect your models](#connect-your-models)).
+
 The harness keeps each file, and the screen saves it in `example-coder-media` with a number. `/open 2` opens file 2, and `/play` plays the last song or speech (with `ffplay` from ffmpeg).
 
 ## Hand work to Claude Code and Codex
diff --git a/examples/harness-cli/package.json b/examples/harness-cli/package.json
index 0c269a4745..f5b3cd8b0c 100644
--- a/examples/harness-cli/package.json
+++ b/examples/harness-cli/package.json
@@ -23,6 +23,7 @@
     "@tanstack/ai-isolate-quickjs": "workspace:*",
     "@tanstack/ai-mcp": "workspace:*",
     "@tanstack/ai-openai": "workspace:*",
+    "@tanstack/ai-openrouter": "workspace:*",
     "@tanstack/ai-persistence": "workspace:*",
     "@tanstack/ai-sandbox": "workspace:*",
     "@tanstack/ai-sandbox-local-process": "workspace:*",
diff --git a/examples/harness-cli/src/credentials.ts b/examples/harness-cli/src/credentials.ts
index 06c358356b..76d30a3a2e 100644
--- a/examples/harness-cli/src/credentials.ts
+++ b/examples/harness-cli/src/credentials.ts
@@ -5,9 +5,9 @@ import { defineCredentialStore } from '@tanstack/ai-persistence'
 import type { Credential } from '@tanstack/ai-persistence'
 
 /**
- * Sign-ins (Notion, Linear) saved in a file in your home folder, so they
- * survive a restart. The file is readable by your user only. A production
- * store would encrypt the values.
+ * Sign-ins (Notion, Linear) and model keys (`/connect openai`) saved in a
+ * file in your home folder, so they survive a restart. The file is readable
+ * by your user only. A production store would encrypt the values.
  */
 export function fileCredentials(
   file = join(homedir(), '.tanstack-harness-example', 'credentials.json'),
diff --git a/examples/harness-cli/src/harness.ts b/examples/harness-cli/src/harness.ts
index 478a47f218..d4b200d23c 100644
--- a/examples/harness-cli/src/harness.ts
+++ b/examples/harness-cli/src/harness.ts
@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { delimiter, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { EventType, defineAgent } from '@tanstack/ai'
+import { EventType, defineAgent, keyedAdapter } from '@tanstack/ai'
 import { defineHarness } from '@tanstack/ai-harness'
 import {
   compact,
@@ -10,22 +10,26 @@ import {
   modelPicker,
   permissions,
   projectInstructions,
+  providerKeys,
   todos,
   usage,
   workspaceTools,
 } from '@tanstack/ai-harness/plugins'
-import { anthropicText } from '@tanstack/ai-anthropic'
+import { createAnthropicChat } from '@tanstack/ai-anthropic'
+import { anthropicByok } from '@tanstack/ai-anthropic/byok'
 import { claudeCodeText } from '@tanstack/ai-claude-code'
 import { codeMode } from '@tanstack/ai-code-mode/harness'
 import { codexText } from '@tanstack/ai-codex'
+import { falByok } from '@tanstack/ai-fal/byok'
 import { mcpConnector } from '@tanstack/ai-mcp/connector'
-import { grokText, grokVideo } from '@tanstack/ai-grok'
+import { createGrokText } from '@tanstack/ai-grok'
+import { grokByok } from '@tanstack/ai-grok/byok'
 import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs'
-import {
-  openaiText,
-  openaiTranscription,
-  openaiVideo,
-} from '@tanstack/ai-openai'
+import { createOpenaiChat, openaiTranscription } from '@tanstack/ai-openai'
+import { openaiByok } from '@tanstack/ai-openai/byok'
+import { createOpenRouterText } from '@tanstack/ai-openrouter'
+import { openrouterByok } from '@tanstack/ai-openrouter/byok'
+import { openrouterSignIn } from '@tanstack/ai-openrouter/pkce'
 import {
   defineSandbox,
   defineWorkspace,
@@ -42,12 +46,14 @@ import {
   speechAgent,
   videoAgent,
 } from './media'
-import type { AnyTextAdapter } from '@tanstack/ai'
+import { envKey } from './store'
+import type { AnyTextAdapter, KeyedAdapter } from '@tanstack/ai'
+import type { ByokProvider, ProviderId } from '@tanstack/ai/byok'
 
 // The agent works in ./playground, so it cannot touch the rest of your disk.
 const root = fileURLToPath(new URL('../playground', import.meta.url))
 
-/** Without an API key, a stand-in model that explains how to add one. */
+/** Without any model key, a stand-in model that explains how to add one. */
 function demoModel(): AnyTextAdapter {
   let calls = 0
   return {
@@ -91,7 +97,7 @@ function demoModel(): AnyTextAdapter {
         yield {
           type: EventType.TEXT_MESSAGE_CONTENT,
           messageId,
-          delta: `(demo model) You said: "${said}". Set OPENAI_API_KEY or ANTHROPIC_API_KEY to talk to a real model.`,
+          delta: `(demo model) You said: "${said}". Run /connect openai (/keys lists the others), then /model gpt, to talk to a real model.`,
           timestamp: now,
         }
         yield { type: EventType.TEXT_MESSAGE_END, messageId, timestamp: now }
@@ -106,27 +112,57 @@ function demoModel(): AnyTextAdapter {
   }
 }
 
+/** Is a key for `provider` in the environment (the `.env` shortcut)? */
+function hasEnvKey(provider: ByokProvider | ProviderId) {
+  return typeof provider !== 'string' && envKey(provider) !== null
+}
+
 /**
- * The models `/model <name>` can switch to: one or two per provider with a
- * key. The first one is the default.
+ * The models `/model <name>` can switch to. Each one is built for each turn
+ * with the user's own key: the key saved with `/connect <provider>`, else the
+ * env var. A model without a key asks the user to connect.
  */
-function pickModels() {
-  const choices: Record<string, AnyTextAdapter> = {}
-  if (process.env.OPENAI_API_KEY) {
-    choices.gpt = openaiText('gpt-6-astra')
-    choices['gpt-fast'] = openaiText('gpt-6-luna')
-  }
-  if (process.env.ANTHROPIC_API_KEY) {
-    choices.claude = anthropicText('claude-opus-5-5')
-    choices['claude-fast'] = anthropicText('claude-sonnet-5')
-  }
-  if (process.env.XAI_API_KEY) choices.grok = grokText('grok-4.7')
-  const [main = demoModel()] = Object.values(choices)
-  if (Object.keys(choices).length === 0) choices.demo = main
-  return { main, choices }
+const models = {
+  gpt: keyedAdapter(openaiByok, (key) => createOpenaiChat('gpt-6-astra', key)),
+  'gpt-fast': keyedAdapter(openaiByok, (key) =>
+    createOpenaiChat('gpt-6-luna', key),
+  ),
+  claude: keyedAdapter(anthropicByok, (key) =>
+    createAnthropicChat('claude-opus-5-5', key),
+  ),
+  'claude-fast': keyedAdapter(anthropicByok, (key) =>
+    createAnthropicChat('claude-sonnet-5', key),
+  ),
+  grok: keyedAdapter(grokByok, (key) => createGrokText('grok-4.7', key)),
+  'openrouter-gpt': keyedAdapter(openrouterByok, (key) =>
+    createOpenRouterText('openai/gpt-6-astra', key),
+  ),
+  'openrouter-claude': keyedAdapter(openrouterByok, (key) =>
+    createOpenRouterText('anthropic/claude-opus-5.5', key),
+  ),
 }
 
-const { main, choices } = pickModels()
+// The first model with an env key starts, so a `.env` works as before. The
+// saved keys belong to a session, so without an env key `gpt` starts, and
+// the first message asks the user to run /connect openai.
+const envModel = Object.entries(models).find(([, model]) =>
+  hasEnvKey(model.provider),
+)
+const startModel = envModel?.[0] ?? 'gpt'
+// Any of the models: the harness, /compact, and /goal take this common type.
+const main: KeyedAdapter<AnyTextAdapter> = envModel?.[1] ?? models.gpt
+// With no env key at all, `/model demo` answers without a key.
+const choices = { ...models, ...(envModel ? {} : { demo: demoModel() }) }
+
+// `/connect openai` asks for the key (the screen hides it as you type), and
+// `/connect openrouter` signs in with the browser. `/keys` lists them all.
+const keyProviders = [
+  openaiByok,
+  anthropicByok,
+  grokByok,
+  falByok,
+  { ...openrouterByok, signIn: openrouterSignIn() },
+]
 
 /** Is `command` on the PATH? Checks the Windows extensions too. */
 function onPath(command: string) {
@@ -177,9 +213,9 @@ const haiku = defineAgent({
   name: 'haiku',
   description: 'Writes a haiku about a topic',
   inputSchema: z.object({ topic: z.string() }),
-  run: (ctx) =>
+  run: async (ctx) =>
     ctx.chat({
-      adapter: main,
+      adapter: await ctx.keys.adapter(main),
       messages: [
         {
           role: 'user',
@@ -191,20 +227,12 @@ const haiku = defineAgent({
 })
 
 // The model calls the media agents as tools, and the harness keeps each file
-// they make. Each one turns on with the key its provider needs:
-// - OPENAI_API_KEY: images, speech, and video with Sora.
-// - XAI_API_KEY: video with Grok Imagine (it wins over Sora).
-// - FAL_KEY: songs and sound effects.
-const video = process.env.XAI_API_KEY
-  ? videoAgent(grokVideo('grok-imagine-video-1.5'))
-  : process.env.OPENAI_API_KEY
-    ? videoAgent(openaiVideo('sora-2'))
-    : undefined
-const media = [
-  ...(process.env.OPENAI_API_KEY ? [imageAgent, speechAgent] : []),
-  ...(video ? [video] : []),
-  ...(process.env.FAL_KEY ? [songAgent, soundAgent] : []),
-]
+// they make. Each one uses the key its provider needs. Without the key, the
+// tool says which /connect to run:
+// - OpenAI: images, speech, and video with Sora.
+// - xAI Grok: video with Grok Imagine (it wins over Sora).
+// - fal: songs and sound effects.
+const media = [imageAgent, speechAgent, videoAgent, songAgent, soundAgent]
 
 // Notion and Linear through their MCP servers. `/connect notion` signs in
 // through the browser. No app setup or API key is needed.
@@ -274,41 +302,56 @@ const tools = [
   ...Object.keys(codingAgentList),
 ]
 
-/** What this session can do, and what turns each one on, for the screen. */
+/**
+ * A feature that a key for any one of `providers` turns on. `on` is the
+ * state at startup, from the env vars only. The screen follows the saved
+ * keys live.
+ */
+function keyFeature(
+  name: string,
+  providers: Array<ByokProvider>,
+  needs: string,
+) {
+  return {
+    name,
+    on: providers.some(hasEnvKey),
+    needs,
+    providers: providers.map((provider) => provider.id),
+  }
+}
+
+/**
+ * What this session can do, and what turns each one on, for the screen.
+ * `providers` are the ids of the key providers a feature needs (any one).
+ */
 export const features = [
-  {
-    name: 'voice',
-    on: Boolean(process.env.OPENAI_API_KEY || process.env.XAI_API_KEY),
-    needs: 'OPENAI_API_KEY or XAI_API_KEY, and ffmpeg',
-  },
-  {
-    name: 'images',
-    on: Boolean(process.env.OPENAI_API_KEY),
-    needs: 'OPENAI_API_KEY',
-  },
-  {
-    name: 'speech',
-    on: Boolean(process.env.OPENAI_API_KEY),
-    needs: 'OPENAI_API_KEY',
-  },
-  {
-    name: 'video',
-    on: video !== undefined,
-    needs: 'XAI_API_KEY or OPENAI_API_KEY',
-  },
-  { name: 'songs', on: Boolean(process.env.FAL_KEY), needs: 'FAL_KEY' },
+  keyFeature(
+    'voice',
+    [openaiByok, grokByok],
+    'an OpenAI or xAI key (/connect openai or /connect grok), and ffmpeg',
+  ),
+  keyFeature('images', [openaiByok], 'an OpenAI key (/connect openai)'),
+  keyFeature('speech', [openaiByok], 'an OpenAI key (/connect openai)'),
+  keyFeature(
+    'video',
+    [grokByok, openaiByok],
+    'an xAI or OpenAI key (/connect grok or /connect openai)',
+  ),
+  keyFeature('songs', [falByok], 'a fal key (/connect fal)'),
   {
     name: 'claude code',
     on: 'claude_code' in codingAgentList,
     needs: '`claude` on the PATH',
+    providers: [],
   },
   {
     name: 'codex',
     on: 'codex' in codingAgentList,
     needs: '`codex` on the PATH',
+    providers: [],
   },
-  { name: 'notion', on: true, needs: '' },
-  { name: 'linear', on: true, needs: '' },
+  { name: 'notion', on: true, needs: '', providers: [] },
+  { name: 'linear', on: true, needs: '', providers: [] },
 ]
 
 export const assistant = defineHarness({
@@ -321,11 +364,14 @@ export const assistant = defineHarness({
     `Your agent tools: ${tools.join(', ') || 'none'}. The user gets each file a media tool makes, so do not paste file contents or links.`,
     'When the user asks to run Codex or Claude Code (by voice too: "run a Codex agent"), call that tool with a clear task, then give its answer back in a few lines.',
     'The user can send files and voice messages. When they send an image and ask for a new version, a style, or an edit of it, call the image tool with useAttachedImages.',
-    'You can read Notion and Linear when they are connected. If a tool says to sign in, tell the user to run /connect notion or /connect linear.',
+    'You can read Notion and Linear when they are connected. If a tool says to sign in or that a key is missing, tell the user the /connect command it names, for example /connect notion or /connect openai.',
   ],
   agents: [haiku],
   subagents: { agents: media },
   // Audio files the user sends become text for models that cannot read audio.
+  // ponytail: `media.transcribe` takes a plain adapter, not a keyed one, so
+  // this needs OPENAI_API_KEY in the env. A key saved with /connect does not
+  // turn it on. Voice messages on the screen use the saved key (src/voice.ts).
   ...(process.env.OPENAI_API_KEY
     ? { media: { transcribe: openaiTranscription('gpt-4o-transcribe') } }
     : {}),
@@ -335,7 +381,8 @@ export const assistant = defineHarness({
     permissions(),
     workspaceTools({ root }),
     todos(),
-    modelPicker({ choices, default: Object.keys(choices)[0] }),
+    providerKeys({ providers: keyProviders }),
+    modelPicker({ choices, default: startModel }),
     projectInstructions({ root }),
     compact({ adapter: main }),
     usage(),
diff --git a/examples/harness-cli/src/media.ts b/examples/harness-cli/src/media.ts
index a40bce363b..c8e74eb365 100644
--- a/examples/harness-cli/src/media.ts
+++ b/examples/harness-cli/src/media.ts
@@ -1,7 +1,15 @@
-import { EventType, defineAgent } from '@tanstack/ai'
+import { EventType, defineAgent, keyedAdapter } from '@tanstack/ai'
 import { mediaIdOf } from '@tanstack/ai-harness'
 import { falAudio } from '@tanstack/ai-fal'
-import { openaiImage, openaiSpeech } from '@tanstack/ai-openai'
+import { falByok } from '@tanstack/ai-fal/byok'
+import { createGrokVideo } from '@tanstack/ai-grok'
+import { grokByok } from '@tanstack/ai-grok/byok'
+import {
+  createOpenaiImage,
+  createOpenaiSpeech,
+  createOpenaiVideo,
+} from '@tanstack/ai-openai'
+import { openaiByok } from '@tanstack/ai-openai/byok'
 import { z } from 'zod'
 import { mediaBytes } from './store'
 import type {
@@ -14,6 +22,26 @@ import type {
 
 // Every agent here returns a short text. The harness keeps each file it makes
 // and publishes a `harness.media` event, so the screen can show and save it.
+//
+// Each agent builds its model with the user's key just before the call: the
+// key saved with `/connect <provider>`, else the env var. Without a key, the
+// call stops, and the screen says which `/connect` to run.
+const gptImage = keyedAdapter(openaiByok, (key) =>
+  createOpenaiImage('gpt-image-2.5-flare', key),
+)
+const openaiVoice = keyedAdapter(openaiByok, (key) =>
+  createOpenaiSpeech('tts-1-hd', key),
+)
+const sora = keyedAdapter(openaiByok, (key) => createOpenaiVideo('sora-2', key))
+const grokImagine = keyedAdapter(grokByok, (key) =>
+  createGrokVideo('grok-imagine-video-1.5', key),
+)
+const falMusic = keyedAdapter(falByok, (key) =>
+  falAudio('fal-ai/elevenlabs/music', { apiKey: key }),
+)
+const falSound = keyedAdapter(falByok, (key) =>
+  falAudio('fal-ai/stable-audio-25/text-to-audio', { apiKey: key }),
+)
 
 /**
  * The images in the latest user message that has files: the ones the user
@@ -64,7 +92,7 @@ export const imageAgent = defineAgent({
     const references = ctx.input.useAttachedImages
       ? await attachedImages(ctx.messages)
       : []
-    const adapter = openaiImage('gpt-image-2.5-flare')
+    const adapter = await ctx.keys.adapter(gptImage)
     // With references, the prompt is the text plus the images (an edit).
     const result =
       references.length > 0
@@ -92,34 +120,37 @@ export const imageAgent = defineAgent({
 })
 
 /**
- * Makes a short video with `adapter`. The harness keeps only streamed video,
- * so this uses `stream: true`: one stream from the job start to the file.
+ * Makes a short video: with Grok Imagine when the user has an xAI key, else
+ * with Sora. The harness keeps only streamed video, so this uses
+ * `stream: true`: one stream from the job start to the file.
  */
-export function videoAgent(adapter: AnyVideoAdapter) {
-  return defineAgent({
-    name: 'video',
-    description:
-      'Generates one short video clip from a detailed visual prompt. Takes a minute or two. The user gets the video.',
-    produces: 'video',
-    inputSchema: z.object({
-      prompt: z
-        .string()
-        .describe('A detailed description of the scene and the motion'),
-    }),
-    run: async (ctx) => {
-      const stream = ctx.generateVideo({
-        adapter,
-        prompt: ctx.input.prompt,
-        stream: true,
-      })
-      for await (const chunk of stream) {
-        // The stream reports a failed or stopped job as an event, not a throw.
-        if (chunk.type === EventType.RUN_ERROR) throw new Error(chunk.message)
-      }
-      return `Made the video with ${adapter.model}. The user has it.`
-    },
-  })
-}
+export const videoAgent = defineAgent({
+  name: 'video',
+  description:
+    'Generates one short video clip from a detailed visual prompt. Takes a minute or two. The user gets the video.',
+  produces: 'video',
+  inputSchema: z.object({
+    prompt: z
+      .string()
+      .describe('A detailed description of the scene and the motion'),
+  }),
+  run: async (ctx) => {
+    const hasGrokKey = (await ctx.keys.get(grokByok)) !== null
+    const adapter: AnyVideoAdapter = hasGrokKey
+      ? await ctx.keys.adapter(grokImagine)
+      : await ctx.keys.adapter(sora)
+    const stream = ctx.generateVideo({
+      adapter,
+      prompt: ctx.input.prompt,
+      stream: true,
+    })
+    for await (const chunk of stream) {
+      // The stream reports a failed or stopped job as an event, not a throw.
+      if (chunk.type === EventType.RUN_ERROR) throw new Error(chunk.message)
+    }
+    return `Made the video with ${adapter.model}. The user has it.`
+  },
+})
 
 /** Reads a text aloud with OpenAI text to speech. */
 export const speechAgent = defineAgent({
@@ -136,7 +167,7 @@ export const speechAgent = defineAgent({
   }),
   run: async (ctx) => {
     const result = await ctx.generateSpeech({
-      adapter: openaiSpeech('tts-1-hd'),
+      adapter: await ctx.keys.adapter(openaiVoice),
       text: ctx.input.text,
       voice: ctx.input.voice ?? 'alloy',
     })
@@ -163,7 +194,7 @@ export const songAgent = defineAgent({
   }),
   run: async (ctx) => {
     const result = await ctx.generateAudio({
-      adapter: falAudio('fal-ai/elevenlabs/music'),
+      adapter: await ctx.keys.adapter(falMusic),
       prompt: ctx.input.prompt,
       duration: ctx.input.seconds ?? 30,
     })
@@ -188,7 +219,7 @@ export const soundAgent = defineAgent({
   }),
   run: async (ctx) => {
     const result = await ctx.generateAudio({
-      adapter: falAudio('fal-ai/stable-audio-25/text-to-audio'),
+      adapter: await ctx.keys.adapter(falSound),
       prompt: ctx.input.prompt,
       duration: ctx.input.seconds ?? 8,
     })
diff --git a/examples/harness-cli/src/store.ts b/examples/harness-cli/src/store.ts
index f1b25dab92..6e90175351 100644
--- a/examples/harness-cli/src/store.ts
+++ b/examples/harness-cli/src/store.ts
@@ -4,13 +4,18 @@ import {
   retrieveBlob,
 } from '@tanstack/ai-persistence'
 import { fileCredentials } from './credentials'
+import type { ByokProvider } from '@tanstack/ai/byok'
+
+/** Sign-ins and the model keys you save with `/connect`, kept in a file. */
+const credentials = fileCredentials()
 
 /**
- * Everything in memory, except sign-ins, which are kept in a file. The
- * memory stores also keep media: the files you send and the files agents make.
+ * Everything in memory, except sign-ins and keys, which are kept in a file.
+ * The memory stores also keep media: the files you send and the files agents
+ * make.
  */
 export const persistence = composePersistence(memoryPersistence(), {
-  overrides: { credentials: fileCredentials() },
+  overrides: { credentials },
 })
 
 /** The bytes of a stored media file, or `undefined` when it is gone. */
@@ -18,3 +23,21 @@ export async function mediaBytes(id: string) {
   const blob = await retrieveBlob(persistence, id)
   return blob ? new Uint8Array(await blob.arrayBuffer()) : undefined
 }
+
+/** The value of the first env var of `provider` that is set, or `null`. */
+export function envKey(provider: ByokProvider) {
+  const names = provider.env ?? []
+  const name = names.find((env) => Boolean(process.env[env]))
+  return name ? (process.env[name] ?? null) : null
+}
+
+/**
+ * The key for `provider` that the session of `threadId` uses: the one you
+ * saved with `/connect <id>`, else its env var, else `null`. The CLI opens
+ * its session without a user, so the scope is the thread only.
+ */
+export async function providerKey(provider: ByokProvider, threadId: string) {
+  const saved = await credentials.get({ threadId }, provider.id)
+  if (saved?.type === 'api_key') return saved.value
+  return envKey(provider)
+}
diff --git a/examples/harness-cli/src/tui.tsx b/examples/harness-cli/src/tui.tsx
index ff3a268bc6..aa6c046678 100644
--- a/examples/harness-cli/src/tui.tsx
+++ b/examples/harness-cli/src/tui.tsx
@@ -45,6 +45,8 @@ const KIND_COLOR: Record<string, string> = {
   video: 'blue',
   document: 'white',
 }
+// The name of the `providerKeys()` plugin: its state is in `state.plugins`.
+const PROVIDER_KEYS = 'tanstack/provider-keys'
 const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
 
 // ponytail: the CLI's default media folder, `./<harness-name>-media`. A custom
@@ -129,6 +131,56 @@ function textOf(parts: ReadonlyArray<ViewPart>) {
   return parts.map((part) => (part.type === 'text' ? part.text : '')).join('')
 }
 
+/** A model provider of `providerKeys()`, and where its key comes from. */
+interface ProviderKey {
+  id: string
+  label: string
+  state: 'connected' | 'env' | 'missing'
+}
+
+function isProviderKey(value: unknown): value is ProviderKey {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'id' in value &&
+    typeof value.id === 'string' &&
+    'label' in value &&
+    typeof value.label === 'string' &&
+    'state' in value &&
+    (value.state === 'connected' ||
+      value.state === 'env' ||
+      value.state === 'missing')
+  )
+}
+
+/**
+ * The providers in `saved`, the state of the provider-keys plugin (in
+ * `state.plugins`). `/connect` and `/disconnect` update it, so the screen
+ * shows the keys live. Empty before the plugin reports.
+ */
+function providerKeysIn(saved: unknown) {
+  const isState =
+    typeof saved === 'object' && saved !== null && 'providers' in saved
+  if (!isState) return []
+  const { providers } = saved
+  return Array.isArray(providers) ? providers.filter(isProviderKey) : []
+}
+
+/**
+ * Is `feature` on? A feature that needs a key follows the saved keys: any
+ * one of its providers with a key turns it on. The rest stay as at startup.
+ */
+function isOn(
+  feature: (typeof features)[number],
+  keys: ReadonlyArray<ProviderKey>,
+) {
+  const followsKeys = feature.providers.length > 0 && keys.length > 0
+  if (!followsKeys) return feature.on
+  return keys.some(
+    (key) => feature.providers.includes(key.id) && key.state !== 'missing',
+  )
+}
+
 /** Start a program without a shell. The screen still shows the path on error. */
 function launch(command: string, args: Array<string>) {
   const child = spawn(command, args, { stdio: 'ignore', detached: true })
@@ -387,6 +439,9 @@ function Header({ view }: { view: SessionView }) {
     view.store,
     (state) => state.config.find((entry) => entry.key === 'model')?.value,
   )
+  // The plugin state, not a new list, so the header renders only on a change.
+  const saved = useSelector(view.store, (state) => state.plugins[PROVIDER_KEYS])
+  const keys = providerKeysIn(saved)
   return (
     <Box
       flexDirection="column"
@@ -407,12 +462,28 @@ function Header({ view }: { view: SessionView }) {
         </Text>
       </Box>
       <Box flexWrap="wrap">
-        {features.map((feature) => (
-          <Text key={feature.name} color={feature.on ? 'green' : 'gray'}>
-            {`${feature.on ? '●' : '○'} ${feature.name}   `}
-          </Text>
-        ))}
+        {features.map((feature) => {
+          const on = isOn(feature, keys)
+          return (
+            <Text key={feature.name} color={on ? 'green' : 'gray'}>
+              {`${on ? '●' : '○'} ${feature.name}   `}
+            </Text>
+          )
+        })}
       </Box>
+      {keys.length > 0 ? (
+        <Box flexWrap="wrap">
+          <Text dimColor>keys </Text>
+          {keys.map((key) => (
+            <Text
+              key={key.id}
+              color={key.state === 'missing' ? 'gray' : 'green'}
+            >
+              {`${key.id} ${key.state === 'missing' ? '○' : '●'}  `}
+            </Text>
+          ))}
+        </Box>
+      ) : null}
     </Box>
   )
 }
@@ -498,7 +569,16 @@ function Status({
   )
 }
 
-function InputBox({ input, voice }: { input: string; voice: VoiceState }) {
+function InputBox({
+  input,
+  voice,
+  hidden,
+}: {
+  input: string
+  voice: VoiceState
+  /** The input is a secret (a key): show a dot for each character. */
+  hidden: boolean
+}) {
   const active = voice === 'idle'
   return (
     <Box
@@ -511,10 +591,12 @@ function InputBox({ input, voice }: { input: string; voice: VoiceState }) {
       </Text>
       {input === '' ? (
         <Text dimColor>
-          Type a message, @file to attach, or hold Ctrl+R to talk
+          {hidden
+            ? 'Paste the key. It stays hidden.'
+            : 'Type a message, @file to attach, or hold Ctrl+R to talk'}
         </Text>
       ) : (
-        <Text>{input}</Text>
+        <Text>{hidden ? '•'.repeat(input.length) : input}</Text>
       )}
       <Text inverse> </Text>
     </Box>
@@ -529,7 +611,9 @@ const HELP = [
   '/voice <file> send a recorded voice message',
   '/open [n]     open media file n (default: the last one)',
   '/play [n]     play audio or video file n',
-  '/connect <id> sign in to notion or linear (/disconnect <id>)',
+  '/connect <id> connect a model provider (/keys lists them), notion, or linear',
+  '/disconnect <id> remove that key or sign-in',
+  '/keys         show where each model key comes from',
   '/exit         quit',
 ]
 
@@ -542,7 +626,23 @@ function App({ view }: { view: SessionView }) {
   const { exit } = useApp()
   const messages = useSelector(view.store, (state) => state.messages)
   const saved = useSavedMedia(view, messages)
-  const [input, setInput] = useState('')
+  // The input line. `hidden`: it holds a secret (a key), typed while a
+  // question asked for one. It stays hidden until it is sent or deleted, also
+  // when the question ends first, so a key never shows or goes out as a
+  // message.
+  const [input, setInput] = useState({ text: '', hidden: false })
+  const secretAsked = useSelector(
+    view.store,
+    (state) => state.questions.at(0)?.secret === true,
+  )
+  /** Add typed or pasted text to the input line. */
+  const type = (text: string) => {
+    const asked = view.store.get().questions.at(0)?.secret === true
+    setInput((current) => ({
+      text: current.text + text,
+      hidden: asked || (current.hidden && current.text !== ''),
+    }))
+  }
   const [voice, setVoiceState] = useState<VoiceState>('idle')
   // The phase in a ref too: key events come faster than React renders, and a
   // second Ctrl+R must see "starting" at once, or it starts a second recorder.
@@ -579,7 +679,10 @@ function App({ view }: { view: SessionView }) {
         return view.notice(
           `Voice: only silence from "${clip.microphone}". Hold Ctrl+R while you talk, or pick another microphone with /mic.`,
         )
-      const text = await transcribe(audio, name)
+      const text = await transcribe(audio, {
+        name,
+        threadId: view.store.get().threadId,
+      })
       if (text === '') return view.notice('Voice: no speech heard.')
       const recent = saved.flatMap((item) =>
         item.path ? [{ kind: item.kind, path: item.path }] : [],
@@ -613,18 +716,21 @@ function App({ view }: { view: SessionView }) {
   }
 
   const startTalking = async () => {
-    if (!canTranscribe())
-      return view.notice(
-        'Voice: set OPENAI_API_KEY or XAI_API_KEY in .env to turn voice on.',
-      )
     talk.current = {
       last: Date.now(),
       holding: false,
       stopWanted: false,
       cancelWanted: false,
     }
+    // "starting" before the key check, so a repeated Ctrl+R starts nothing.
     setVoice('starting')
     try {
+      if (!(await canTranscribe(view.store.get().threadId))) {
+        setVoice('idle')
+        return view.notice(
+          'Voice: run /connect openai (or /connect grok) to turn voice on.',
+        )
+      }
       const started = await startRecording()
       if (talk.current.cancelWanted) {
         started.cancel()
@@ -675,15 +781,25 @@ function App({ view }: { view: SessionView }) {
   }
 
   /** Enter: answer an approval or a question, run a screen command, or send. */
-  const submit = async (line: string) => {
-    const text = line.trim()
+  const submit = async (line: { text: string; hidden: boolean }) => {
+    const text = line.text.trim()
     const state = view.store.get()
+    const [question] = state.questions
+    if (question?.secret) {
+      // The key goes as it is. The screen does not show it anywhere.
+      await question.answer(text)
+      return
+    }
+    if (line.hidden) {
+      // The question ended before Enter: drop the key, do not send it.
+      view.notice('The key question ended, so the key was not used.')
+      return
+    }
     if (state.approvals.length > 0) {
       if (/^y(es)?$/i.test(text)) view.approveAll()
       else view.rejectAll()
       return
     }
-    const [question] = state.questions
     if (question) {
       const answer = /^y(es)?$/i.test(text)
         ? true
@@ -695,8 +811,9 @@ function App({ view }: { view: SessionView }) {
     }
     if (text === '/exit') return exit()
     if (text === '/help') {
+      const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
       const off = features
-        .filter((feature) => !feature.on)
+        .filter((feature) => !isOn(feature, keys))
         .map(
           (feature) => `  ${feature.name} is off: it needs ${feature.needs}.`,
         )
@@ -750,7 +867,7 @@ function App({ view }: { view: SessionView }) {
     await view.send(text)
   }
 
-  usePaste((text) => setInput((current) => current + text))
+  usePaste(type)
 
   useInput((character, key) => {
     if (key.ctrl && character === 'r') return onTalkKey()
@@ -775,16 +892,15 @@ function App({ view }: { view: SessionView }) {
     if (key.return) {
       if (phase.current === 'recording' || phase.current === 'starting')
         return void stopTalking()
-      setInput('')
+      setInput({ text: '', hidden: false })
       void submit(input)
       return
     }
     if (key.backspace || key.delete) {
-      setInput((current) => current.slice(0, -1))
+      setInput((current) => ({ ...current, text: current.text.slice(0, -1) }))
       return
     }
-    if (!key.ctrl && !key.meta && character)
-      setInput((current) => current + character)
+    if (!key.ctrl && !key.meta && character) type(character)
   })
 
   return (
@@ -794,10 +910,14 @@ function App({ view }: { view: SessionView }) {
         <Message key={message.id} message={message} saved={saved} />
       ))}
       <Status view={view} voice={voice} recording={recorder} />
-      <InputBox input={input} voice={voice} />
+      <InputBox
+        input={input.text}
+        voice={voice}
+        hidden={secretAsked || (input.hidden && input.text !== '')}
+      />
       <Text dimColor>
         {
-          '  Ctrl+R talk   Esc cancel   /model   /mic   /open   /play   /help   /exit'
+          '  Ctrl+R talk   Esc cancel   /model   /keys   /mic   /open   /play   /help   /exit'
         }
       </Text>
     </Box>
@@ -814,9 +934,11 @@ export async function runTui(view: SessionView, io: RenderOptions = {}) {
   view.on('signIn', (signIn) => {
     if (signIn.url) openExternal(signIn.url)
   })
-  const keys = ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'XAI_API_KEY']
-  if (!keys.some((key) => process.env[key]))
-    view.notice('No API keys yet: copy .env.example to .env and add yours.')
+  const keys = providerKeysIn(view.store.get().plugins[PROVIDER_KEYS])
+  if (keys.every((key) => key.state === 'missing'))
+    view.notice(
+      'No model key yet. Run /connect openai to paste a key, or /connect openrouter to sign in with the browser. /keys lists them all.',
+    )
   view.notice('Hold Ctrl+R to talk, or type. /help lists the commands.')
   // ponytail: the SDK logs its warnings and errors on the console (the message,
   // then its details with console.dir). Ink prints console output above the
diff --git a/examples/harness-cli/src/voice.ts b/examples/harness-cli/src/voice.ts
index 2ae1f1398d..a7d3b097a8 100644
--- a/examples/harness-cli/src/voice.ts
+++ b/examples/harness-cli/src/voice.ts
@@ -4,8 +4,11 @@ import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { basename, dirname, extname, join, relative } from 'node:path'
 import { generateTranscription } from '@tanstack/ai'
-import { grokTranscription } from '@tanstack/ai-grok'
-import { openaiTranscription } from '@tanstack/ai-openai'
+import { createGrokTranscription } from '@tanstack/ai-grok'
+import { grokByok } from '@tanstack/ai-grok/byok'
+import { createOpenaiTranscription } from '@tanstack/ai-openai'
+import { openaiByok } from '@tanstack/ai-openai/byok'
+import { providerKey } from './store'
 
 // Voice input for the terminal: ffmpeg records the microphone, a
 // transcription model turns it into text, and spoken file names become
@@ -16,9 +19,16 @@ const RATE = 16000
 // The microphone you picked, kept next to the sign-ins.
 const saved = join(homedir(), '.tanstack-harness-example', 'voice.json')
 
-/** Can this session turn speech into text? */
-export function canTranscribe() {
-  return Boolean(process.env.OPENAI_API_KEY || process.env.XAI_API_KEY)
+/**
+ * Can the session of `threadId` turn speech into text? It needs an OpenAI or
+ * an xAI key: saved with `/connect`, or in the env.
+ */
+export async function canTranscribe(threadId: string) {
+  const keys = await Promise.all([
+    providerKey(openaiByok, threadId),
+    providerKey(grokByok, threadId),
+  ])
+  return keys.some((key) => key !== null)
 }
 
 /**
@@ -323,33 +333,40 @@ export function isSilent(clip: Pick<VoiceClip, 'peak'>) {
 }
 
 /**
- * The words in `audio`, with OpenAI, or Grok when only an xAI key is set.
- * `name` gives the format, for example `voice.wav`. VOICE_LANGUAGE (an
- * ISO-639-1 code such as `en`) tells the model which language to expect.
+ * The words in `audio`, with OpenAI, or Grok when there is only an xAI key.
+ * The key is the one the session of `threadId` uses: saved with `/connect`,
+ * else the env var. `name` gives the format, for example `voice.wav`.
+ * VOICE_LANGUAGE (an ISO-639-1 code such as `en`) tells the model which
+ * language to expect.
  */
-export async function transcribe(audio: Uint8Array, name = 'voice.wav') {
-  const file = new File([audio.slice()], name)
+export async function transcribe(
+  audio: Uint8Array,
+  options: { name: string; threadId: string },
+) {
+  const file = new File([audio.slice()], options.name)
   const language = process.env.VOICE_LANGUAGE
     ? { language: process.env.VOICE_LANGUAGE }
     : {}
-  if (process.env.OPENAI_API_KEY) {
+  const openaiKey = await providerKey(openaiByok, options.threadId)
+  if (openaiKey !== null) {
     const result = await generateTranscription({
-      adapter: openaiTranscription('gpt-4o-transcribe'),
+      adapter: createOpenaiTranscription('gpt-4o-transcribe', openaiKey),
       audio: file,
       ...language,
     })
     return result.text.trim()
   }
-  if (process.env.XAI_API_KEY) {
+  const grokKey = await providerKey(grokByok, options.threadId)
+  if (grokKey !== null) {
     const result = await generateTranscription({
-      adapter: grokTranscription('grok-stt'),
+      adapter: createGrokTranscription('grok-stt', grokKey),
       audio: file,
       ...language,
     })
     return result.text.trim()
   }
   throw new Error(
-    'Voice needs OPENAI_API_KEY or XAI_API_KEY for transcription.',
+    'Voice needs an OpenAI or xAI key for the transcript. Run /connect openai or /connect grok.',
   )
 }
 
diff --git a/packages/ai-harness-cli/src/commands.ts b/packages/ai-harness-cli/src/commands.ts
index 34a7390945..221a2f1c16 100644
--- a/packages/ai-harness-cli/src/commands.ts
+++ b/packages/ai-harness-cli/src/commands.ts
@@ -96,9 +96,10 @@ export async function handleLine(
   if (text === '') return { type: 'notice', text: '' }
   const [question] = session.snapshot().pendingQuestions
   if (question) {
+    // A secret (a key) is the text as typed: `123456` stays a string.
     const receipt = await session.answer(
       question.questionId,
-      parseAnswer(text, question.schema),
+      question.secret ? text : parseAnswer(text, question.schema),
     )
     return {
       type: 'notice',
diff --git a/packages/ai-harness-cli/src/lines.ts b/packages/ai-harness-cli/src/lines.ts
index a4d940dc87..e23916cbee 100644
--- a/packages/ai-harness-cli/src/lines.ts
+++ b/packages/ai-harness-cli/src/lines.ts
@@ -10,10 +10,63 @@ interface Output {
   write: (text: string) => unknown
 }
 
+/** A terminal, which can stop showing what the user types. A pipe cannot. */
+function isTerminal(input: NodeJS.ReadableStream): input is NodeJS.ReadStream {
+  return 'isTTY' in input && input.isTTY === true && 'setRawMode' in input
+}
+
+/**
+ * The text of a line typed in raw mode, where the terminal does not edit
+ * it: a backspace removes the character before it, and other control
+ * characters are dropped.
+ */
+function typedText(raw: string) {
+  let text = ''
+  for (const char of raw) {
+    if (char === '\u007f' || char === '\b') text = text.slice(0, -1)
+    else if (char >= ' ') text += char
+  }
+  return text
+}
+
+/**
+ * Hide what the user types in a terminal while a secret question (a key)
+ * waits. Raw mode stops the echo. It also stops Ctrl+C, so this sends
+ * SIGINT itself. Does nothing for a pipe.
+ */
+function secretTyping(input: NodeJS.ReadableStream) {
+  const terminal = isTerminal(input) ? input : undefined
+  let hidden = false
+  const onKeys = (chunk: unknown) => {
+    if (!String(chunk).includes('\u0003')) return
+    show()
+    process.kill(process.pid, 'SIGINT')
+  }
+  const show = () => {
+    if (!terminal || !hidden) return
+    hidden = false
+    terminal.off('data', onKeys)
+    terminal.setRawMode(false)
+  }
+  return {
+    canHide: terminal !== undefined,
+    isHidden: () => hidden,
+    hide: () => {
+      if (!terminal || hidden) return
+      hidden = true
+      terminal.setRawMode(true)
+      terminal.on('data', onKeys)
+    },
+    show,
+  }
+}
+
 /**
  * The line mode, for piped input: one message or command per line. Each
  * line waits for the turn it started. When a turn stops for approval, the
- * next line answers it (`y` approves, anything else rejects).
+ * next line answers it (`y` approves, anything else rejects). In a
+ * terminal, the answer to a secret question (a key) is not shown as the
+ * user types. Line mode never prints the answer.
  *
  * `openSignIns`: open sign-in links in the browser (for an interactive terminal).
  * `mediaDir`: the folder for the media a turn makes. Each new file is saved
@@ -27,11 +80,13 @@ export async function runLines(
 ) {
   const view = createSessionView(session)
   const saves: Array<Promise<unknown>> = []
+  const typing = secretTyping(input)
   const printer = createPrinter((text) => stdout.write(text), {
     onMedia: (part) => {
       const saved = saveMediaLine(session, part, options.mediaDir)
       saves.push(saved.then(({ text }) => printer.line(text)))
     },
+    hidesSecrets: typing.canHide,
   })
   await view.ready
   // Line mode prints only what happens from now on.
@@ -46,27 +101,34 @@ export async function runLines(
 
   const lines = createInterface({ input, crlfDelay: Infinity })
   const pendingLater: Array<Promise<void>> = []
-  for await (const typed of lines) {
-    const snapshot = session.snapshot()
-    if (snapshot.status === 'requires_action') {
-      await resolveAll(
-        session,
-        snapshot.pendingInterrupts,
-        /^y(es)?$/i.test(typed.trim()),
-      )
-    } else {
-      const result = await handleLine(session, typed)
-      if (result.type === 'exit') break
-      if (result.type === 'notice' && result.text) line(result.text)
-      if (result.type === 'notice' && result.later) {
-        pendingLater.push(result.later.then((text) => line(text)))
+  try {
+    for await (const raw of lines) {
+      const typed = typing.isHidden() ? typedText(raw) : raw
+      typing.show()
+      const snapshot = session.snapshot()
+      if (snapshot.status === 'requires_action') {
+        await resolveAll(
+          session,
+          snapshot.pendingInterrupts,
+          /^y(es)?$/i.test(typed.trim()),
+        )
+      } else {
+        const result = await handleLine(session, typed)
+        if (result.type === 'exit') break
+        if (result.type === 'notice' && result.text) line(result.text)
+        if (result.type === 'notice' && result.later) {
+          pendingLater.push(result.later.then((text) => line(text)))
+        }
       }
+      await waitIdle(session)
+      const after = session.snapshot()
+      if (after.status === 'requires_action') {
+        line(approvalQuestion(after.pendingInterrupts))
+      }
+      if (after.pendingQuestions[0]?.secret) typing.hide()
     }
-    await waitIdle(session)
-    const after = session.snapshot()
-    if (after.status === 'requires_action') {
-      line(approvalQuestion(after.pendingInterrupts))
-    }
+  } finally {
+    typing.show()
   }
   lines.close()
   await Promise.allSettled(pendingLater)
diff --git a/packages/ai-harness-cli/src/printer.ts b/packages/ai-harness-cli/src/printer.ts
index ead061f8ad..4ee76607cd 100644
--- a/packages/ai-harness-cli/src/printer.ts
+++ b/packages/ai-harness-cli/src/printer.ts
@@ -14,10 +14,12 @@ import type {
  *
  * Media parts print nothing here. `onMedia` gets each new media part of an
  * assistant message once, from the lead or from a child at any depth.
+ * `hidesSecrets`: the input hides what the user types for a secret
+ * question, so its line says so.
  */
 export function createPrinter(
   write: (text: string) => unknown,
-  options: { onMedia?: (part: MediaPart) => void } = {},
+  options: { onMedia?: (part: MediaPart) => void; hidesSecrets?: boolean } = {},
 ) {
   const done = new Set<string>()
   const written = new Map<string, number>()
@@ -92,8 +94,15 @@ export function createPrinter(
       })
       media(message.parts)
     }
-    for (const question of state.questions)
-      once(`question:${question.id}`, `? ${question.message}`)
+    for (const question of state.questions) {
+      const isHidden = question.secret === true && options.hidesSecrets === true
+      once(
+        `question:${question.id}`,
+        isHidden
+          ? `? ${question.message} (typing is hidden)`
+          : `? ${question.message}`,
+      )
+    }
     for (const signIn of state.signIns)
       once(
         `sign-in:${signIn.connector}:${signIn.url ?? ''}`,
diff --git a/packages/ai-harness-cli/tests/cli.test.ts b/packages/ai-harness-cli/tests/cli.test.ts
index 93d7bea254..3f8227edfa 100644
--- a/packages/ai-harness-cli/tests/cli.test.ts
+++ b/packages/ai-harness-cli/tests/cli.test.ts
@@ -1,6 +1,7 @@
 import { Readable } from 'node:stream'
 import { describe, expect, it, vi } from 'vitest'
 import { EventType, defineAgent, toolDefinition } from '@tanstack/ai'
+import { defineByokProvider } from '@tanstack/ai/byok'
 import {
   configOption,
   createHarnessHost,
@@ -8,6 +9,7 @@ import {
   defineHarness,
   definePlugin,
 } from '@tanstack/ai-harness'
+import { providerKeys } from '@tanstack/ai-harness/plugins'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { EXIT, parseCliArgs, runCli } from '../src'
 import { serve } from '../src/serve'
@@ -306,6 +308,62 @@ describe('plugin commands in line mode', () => {
   })
 })
 
+describe('secret answers in line mode', () => {
+  const acme = defineByokProvider({ id: 'acme', label: 'Acme' })
+
+  /** Run `/connect acme` and answer with `key`. Returns what was printed and saved. */
+  async function connect(
+    key: string,
+    stdin: (lines: Array<string>) => NodeJS.ReadStream,
+  ) {
+    const stdout = capture()
+    const persistence = memoryPersistence()
+    await runCli(
+      defineHarness({
+        name: 'test/secret',
+        adapter: scripted([]).adapter,
+        plugins: () => [providerKeys({ providers: [acme] })],
+      }),
+      {
+        argv: [],
+        stdin: stdin(['/connect acme\n', `${key}\n`, '/exit\n']),
+        stdout,
+        stderr: capture(),
+        persistence,
+      },
+    )
+    const saved = await persistence.stores.credentials.get(
+      { threadId: 'main' },
+      'acme',
+    )
+    return { printed: stdout.text, saved }
+  }
+
+  it('saves a pasted key as typed and never prints it', async () => {
+    const { printed, saved } = await connect('12345678', (lines) =>
+      stdinFrom(lines, { isTTY: false }),
+    )
+    expect(saved).toEqual({ type: 'api_key', value: '12345678' })
+    expect(printed).toContain('[? Paste your Acme API key]')
+    expect(printed).toContain('Connected to Acme (key ...5678).')
+    expect(printed).not.toContain('12345678')
+  })
+
+  it('hides typing in a terminal while the key question waits', async () => {
+    const rawModes: Array<boolean> = []
+    const { printed, saved } = await connect('sk-acme-x\u007fy-4321', (lines) =>
+      Object.assign(stdinFrom(lines, { isTTY: true }), {
+        setRawMode: (mode: boolean) => rawModes.push(mode),
+      }),
+    )
+    expect(rawModes).toEqual([true, false])
+    // Raw mode does not edit the line, so line mode applies the backspace.
+    expect(saved).toEqual({ type: 'api_key', value: 'sk-acme-y-4321' })
+    expect(printed).toContain('[? Paste your Acme API key (typing is hidden)]')
+    expect(printed).not.toContain('sk-acme')
+  })
+})
+
 describe('serve mode', () => {
   it('serves the session protocol and requires the token', async () => {
     const { adapter } = scripted([textTurn('served')])
diff --git a/packages/ai-harness/src/auth.ts b/packages/ai-harness/src/auth.ts
index a41e8a01a2..886d05b187 100644
--- a/packages/ai-harness/src/auth.ts
+++ b/packages/ai-harness/src/auth.ts
@@ -1,4 +1,6 @@
-import type { Scope } from '@tanstack/ai'
+import { isKeyedAdapter } from '@tanstack/ai'
+import type { ProviderKeys, Scope } from '@tanstack/ai'
+import type { ByokProvider, ProviderId } from '@tanstack/ai/byok'
 import type { Credential, CredentialStore } from '@tanstack/ai-persistence'
 
 /**
@@ -54,6 +56,56 @@ export function credentialsFor(
   }
 }
 
+/**
+ * The first name in `provider.env` that is set, with its value. A provider
+ * id has no env names. Where `process` is missing (a browser, a worker) it
+ * returns `null`.
+ */
+export function envKeyOf(provider: ByokProvider | ProviderId) {
+  if (typeof provider === 'string') return null
+  const env = globalThis.process?.env
+  for (const name of provider.env ?? []) {
+    const value = env?.[name]
+    if (typeof value === 'string' && value.length > 0) return { name, value }
+  }
+  return null
+}
+
+/**
+ * The provider keys of the session's principal. A key is the `api_key`
+ * credential saved under the provider id (`/connect <id>` saves it), else
+ * the first `provider.env` name that is set. A missing key calls `onMissing`
+ * and throws {@link AuthRequiredError}, so the user sees `/connect <id>`.
+ */
+export function providerKeysFor(
+  credentials: CredentialsAccess,
+  onMissing: (error: AuthRequiredError) => void,
+) {
+  const providerIdOf = (provider: ByokProvider | ProviderId) =>
+    typeof provider === 'string' ? provider : provider.id
+  const get = async (provider: ByokProvider | ProviderId) => {
+    const saved = await credentials.get(providerIdOf(provider))
+    if (saved?.type === 'api_key') return saved.value
+    return envKeyOf(provider)?.value ?? null
+  }
+  const requireKey = async (provider: ByokProvider | ProviderId) => {
+    const key = await get(provider)
+    if (key !== null) return key
+    const error = new AuthRequiredError(providerIdOf(provider))
+    onMissing(error)
+    throw error
+  }
+  const keys: ProviderKeys = {
+    get,
+    require: requireKey,
+    adapter: async (adapter) =>
+      isKeyedAdapter(adapter)
+        ? adapter.create(await requireKey(adapter.provider))
+        : adapter,
+  }
+  return keys
+}
+
 /** Remove secret-looking values from a message before it reaches a model or a log. */
 export function scrubSecrets(
   text: string,
diff --git a/packages/ai-harness/src/commands.ts b/packages/ai-harness/src/commands.ts
index cdbe22a790..e04e723567 100644
--- a/packages/ai-harness/src/commands.ts
+++ b/packages/ai-harness/src/commands.ts
@@ -7,6 +7,11 @@ export interface Question<TSchema extends SchemaInput | undefined = undefined> {
   message: string
   /** The answer's shape. Without one, the answer is any text. */
   schema?: TSchema
+  /**
+   * The answer is a secret, for example an API key or a password. Hosts hide
+   * it while the user types, and the session does not keep it in the inbox.
+   */
+  secret?: boolean
 }
 
 export type AnswerOf<TSchema> = TSchema extends SchemaInput
diff --git a/packages/ai-harness/src/define.ts b/packages/ai-harness/src/define.ts
index 9e32beccfd..5a8ced1b5a 100644
--- a/packages/ai-harness/src/define.ts
+++ b/packages/ai-harness/src/define.ts
@@ -4,6 +4,7 @@ import type {
   AnyTextAdapter,
   AnyTool,
   InterruptDefinition,
+  KeyedAdapter,
   SubagentsBag,
   SystemPrompt,
 } from '@tanstack/ai'
@@ -31,8 +32,12 @@ export interface HarnessConfig<
   name: string
   /** What the harness does. Shown when another agent can call it. */
   description?: string
-  /** The main agent-loop model, the same as `chat({ adapter })`. */
-  adapter: TAdapter
+  /**
+   * The main agent-loop model, the same as `chat({ adapter })`. A
+   * `keyedAdapter(...)` is built for each turn with the user's own key: the
+   * key saved with `/connect <provider>`, else the provider's env var.
+   */
+  adapter: TAdapter | KeyedAdapter<TAdapter>
   systemPrompts?: Array<SystemPrompt>
   tools?: ReadonlyArray<AnyTool>
   middleware?: ReadonlyArray<AnyChatMiddleware>
diff --git a/packages/ai-harness/src/first-party/goal.ts b/packages/ai-harness/src/first-party/goal.ts
index 1ff059565a..44e02a71f3 100644
--- a/packages/ai-harness/src/first-party/goal.ts
+++ b/packages/ai-harness/src/first-party/goal.ts
@@ -3,7 +3,7 @@ import { defineCommand } from '../commands'
 import { createPluginEvent } from '../extensions'
 import { definePlugin } from '../plugins'
 import { textOf, transcriptText } from './session-tools'
-import type { AnyTextAdapter } from '@tanstack/ai'
+import type { AnyTextAdapter, KeyedAdapter } from '@tanstack/ai'
 import type { ChatTurnResult, Operation } from '../types'
 import type { SessionViewState } from '../view/types'
 
@@ -88,14 +88,18 @@ function describe(saved: Goal | null, maxRounds: number) {
  *
  * The loop stops when the goal is met, at the round limit, when a turn waits
  * for approval or fails, and when the user sends a message. `/goal` shows the
- * goal, `/goal stop` ends it, and `/goal resume` continues it.
+ * goal, `/goal stop` ends it, and `/goal resume` continues it. A
+ * `keyedAdapter(...)` judge is built with the user's key for each check.
  *
  * @example
  * ```ts
  * plugins: () => [goal({ judge: openaiText('gpt-5.6-luna') })]
  * ```
  */
-export function goal(options: { judge: AnyTextAdapter; maxRounds?: number }) {
+export function goal(options: {
+  judge: AnyTextAdapter | KeyedAdapter<AnyTextAdapter>
+  maxRounds?: number
+}) {
   const maxRounds = options.maxRounds ?? 20
   return definePlugin({
     name: 'tanstack/goal',
@@ -164,7 +168,7 @@ export function goal(options: { judge: AnyTextAdapter; maxRounds?: number }) {
           (await ctx.session.transcript()).slice(-10),
         ).slice(-8000)
         const verdict = await chat({
-          adapter: options.judge,
+          adapter: await ctx.keys.adapter(options.judge),
           messages: [
             {
               role: 'user',
diff --git a/packages/ai-harness/src/first-party/index.ts b/packages/ai-harness/src/first-party/index.ts
index 1faf68eda7..19f0ca70e5 100644
--- a/packages/ai-harness/src/first-party/index.ts
+++ b/packages/ai-harness/src/first-party/index.ts
@@ -19,3 +19,4 @@ export { fileCommands, projectInstructions } from './files'
 export { compact, usage } from './session-tools'
 export { GoalMet, goal, selectGoal } from './goal'
 export type { Goal } from './goal'
+export { providerKeys } from './provider-keys'
diff --git a/packages/ai-harness/src/first-party/model-picker.ts b/packages/ai-harness/src/first-party/model-picker.ts
index 18807debfa..30261ae7f8 100644
--- a/packages/ai-harness/src/first-party/model-picker.ts
+++ b/packages/ai-harness/src/first-party/model-picker.ts
@@ -1,22 +1,28 @@
 import { defineCommand } from '../commands'
 import { configOption } from '../config'
 import { definePlugin } from '../plugins'
-import type { AnyTextAdapter } from '@tanstack/ai'
+import type { AnyTextAdapter, KeyedAdapter } from '@tanstack/ai'
 
 /**
  * Switch the main model at the next turn with the `model` setting or the
- * `/model <name>` command.
+ * `/model <name>` command. A choice can be a `keyedAdapter(...)`: the
+ * session builds it for each turn with the user's key.
  *
  * @example
  * ```ts
  * modelPicker({
- *   choices: { fast: openaiText('gpt-5.6-luna'), smart: openaiText('gpt-5.6') },
- *   default: 'smart',
+ *   choices: {
+ *     fast: openaiText('gpt-5.6-luna'),
+ *     claude: keyedAdapter(anthropicByok, (key) =>
+ *       createAnthropicChat('claude-sonnet-4-5', key),
+ *     ),
+ *   },
+ *   default: 'fast',
  * })
  * ```
  */
 export function modelPicker(options: {
-  choices: Record<string, AnyTextAdapter>
+  choices: Record<string, AnyTextAdapter | KeyedAdapter<AnyTextAdapter>>
   default?: string
 }) {
   const names = Object.keys(options.choices)
diff --git a/packages/ai-harness/src/first-party/provider-keys.ts b/packages/ai-harness/src/first-party/provider-keys.ts
new file mode 100644
index 0000000000..65c2aaf0d9
--- /dev/null
+++ b/packages/ai-harness/src/first-party/provider-keys.ts
@@ -0,0 +1,152 @@
+import { maskKey } from '@tanstack/ai/byok'
+import { envKeyOf } from '../auth'
+import { defineCommand } from '../commands'
+import { definePlugin } from '../plugins'
+import type { ByokProvider } from '@tanstack/ai/byok'
+import type { CredentialsAccess } from '../auth'
+import type { AnyCommand } from '../commands'
+
+/** Signs the user in and resolves to an API key, for example `openrouterSignIn()`. */
+type ProviderSignIn = (ctx: {
+  open: (url: string) => void
+  signal?: AbortSignal
+}) => Promise<string>
+
+/** A provider the user can connect: its BYOK descriptor, with a sign-in when it has one. */
+type KeyProvider = ByokProvider | (ByokProvider & { signIn: ProviderSignIn })
+
+interface ProviderKeyStatus {
+  id: string
+  label: string
+  /** `connected`: a saved key. `env`: the env var. `missing`: neither. */
+  state: 'connected' | 'env' | 'missing'
+}
+
+/** What UIs read from `state.plugins['tanstack/provider-keys']`. */
+interface ProviderKeysState {
+  providers: Array<ProviderKeyStatus>
+}
+
+/** The state of one provider, and its `/keys` line. The key shows masked only. */
+async function describeKey(
+  credentials: CredentialsAccess,
+  provider: ByokProvider,
+) {
+  const { id, label } = provider
+  const status = (state: ProviderKeyStatus['state']) => ({ id, label, state })
+  const saved = await credentials.get(id)
+  if (saved?.type === 'api_key') {
+    return {
+      status: status('connected'),
+      line: `${label}: connected (key ...${maskKey(saved.value)})`,
+    }
+  }
+  const env = envKeyOf(provider)
+  if (env) {
+    return {
+      status: status('env'),
+      line: `${label}: from the ${env.name} env var`,
+    }
+  }
+  return {
+    status: status('missing'),
+    line: `${label}: missing. Run /connect ${id}.`,
+  }
+}
+
+/**
+ * Let each user connect their own model providers inside the app, so a
+ * shipped harness needs no `.env` file. For each provider it adds
+ * `/connect <id>` and `/disconnect <id>`, and `/keys` lists where each key
+ * comes from. `/connect` runs the provider's `signIn` when it has one (the
+ * host opens the browser), else it asks the user to paste the key. The key
+ * is saved in the credential store of the session's principal. A
+ * `keyedAdapter(...)` for that provider then uses it. The env var still works
+ * when no key is saved. Keys show masked only (the last 4 characters).
+ *
+ * @param options.providers - BYOK descriptors, for example `openaiByok`. Add
+ *   `signIn` for a provider with a browser sign-in, for example
+ *   `{ ...openrouterByok, signIn: openrouterSignIn() }`.
+ *
+ * @example
+ * ```ts
+ * plugins: () => [
+ *   providerKeys({
+ *     providers: [
+ *       openaiByok,
+ *       anthropicByok,
+ *       { ...openrouterByok, signIn: openrouterSignIn() },
+ *     ],
+ *   }),
+ * ]
+ * ```
+ */
+export function providerKeys(options: {
+  providers: ReadonlyArray<KeyProvider>
+}) {
+  const { providers } = options
+  return definePlugin({
+    name: 'tanstack/provider-keys',
+    setup: async (ctx) => {
+      const state = ctx.state<ProviderKeysState>({ providers: [] })
+      /** Check every provider, keep the result for UIs, and return the `/keys` lines. */
+      const refresh = async () => {
+        const described = await Promise.all(
+          providers.map((provider) => describeKey(ctx.credentials, provider)),
+        )
+        await state.update(() => ({
+          providers: described.map((entry) => entry.status),
+        }))
+        return described.map((entry) => entry.line).join('\n')
+      }
+      await refresh()
+
+      /** The key from the provider's sign-in, else the one the user pastes. */
+      const readKey = async (provider: KeyProvider, signal: AbortSignal) => {
+        if ('signIn' in provider) {
+          return provider.signIn({
+            open: (url) =>
+              ctx.session.authRequired({ connector: provider.id, url }),
+            signal,
+          })
+        }
+        return ctx.session.ask({
+          message: `Paste your ${provider.label} API key`,
+          secret: true,
+        })
+      }
+
+      const commands: Record<string, AnyCommand> = {
+        keys: defineCommand({
+          description:
+            'Show the model providers and where their keys come from',
+          run: refresh,
+        }),
+      }
+      for (const provider of providers) {
+        const { id, label } = provider
+        commands[`connect:${id}`] = defineCommand({
+          description: `Connect ${label} with your own key`,
+          run: async (_input, { signal }) => {
+            const key = (await readKey(provider, signal)).trim()
+            if (key === '') {
+              throw new Error(`No ${label} key was given. Nothing was saved.`)
+            }
+            await ctx.credentials.set(id, { type: 'api_key', value: key })
+            await refresh()
+            return `Connected to ${label} (key ...${maskKey(key)}).`
+          },
+        })
+        commands[`disconnect:${id}`] = defineCommand({
+          description: `Remove your ${label} key`,
+          run: async () => {
+            await ctx.credentials.delete(id)
+            await refresh()
+            return `Disconnected from ${label}.`
+          },
+        })
+      }
+      return { commands }
+    },
+  })
+}
diff --git a/packages/ai-harness/src/first-party/session-tools.ts b/packages/ai-harness/src/first-party/session-tools.ts
index 9e17dc2194..5205419e01 100644
--- a/packages/ai-harness/src/first-party/session-tools.ts
+++ b/packages/ai-harness/src/first-party/session-tools.ts
@@ -4,6 +4,7 @@ import { definePlugin } from '../plugins'
 import type {
   AnyChatMiddleware,
   AnyTextAdapter,
+  KeyedAdapter,
   ModelMessage,
 } from '@tanstack/ai'
 
@@ -30,10 +31,11 @@ export function transcriptText(messages: ReadonlyArray<ModelMessage>) {
 
 /**
  * `/compact`: replace a long transcript with a summary, so later turns send
- * fewer tokens. The summary is written by `adapter`.
+ * fewer tokens. The summary is written by `adapter`. A `keyedAdapter(...)`
+ * is built with the user's key when `/compact` runs.
  */
 export function compact(options: {
-  adapter: AnyTextAdapter
+  adapter: AnyTextAdapter | KeyedAdapter<AnyTextAdapter>
   keepLast?: number
 }) {
   return definePlugin({
@@ -50,7 +52,7 @@ export function compact(options: {
             const older = messages.slice(0, messages.length - keep)
             const transcript = transcriptText(older)
             const summary = await chat({
-              adapter: options.adapter,
+              adapter: await ctx.keys.adapter(options.adapter),
               messages: [
                 { role: 'user', content: `${SUMMARY_PROMPT}\n\n${transcript}` },
               ],
diff --git a/packages/ai-harness/src/harness-text.ts b/packages/ai-harness/src/harness-text.ts
index c47cc45d7f..644db9d60c 100644
--- a/packages/ai-harness/src/harness-text.ts
+++ b/packages/ai-harness/src/harness-text.ts
@@ -34,7 +34,8 @@ function lastUserInput(messages: ReadonlyArray<ModelMessage>) {
  */
 function inputsOf(harness: AnyHarness) {
   // ponytail: the harness adapter only. A plugin that picks another model at
-  // runtime is not seen here.
+  // runtime is not seen here. A keyedAdapter has no model until a turn
+  // builds it, so it has no `inputModalities` and every kind is sent.
   const kinds = acceptedKinds(
     harness.adapter.inputModalities,
     harness.media?.accepts,
diff --git a/packages/ai-harness/src/plugins.ts b/packages/ai-harness/src/plugins.ts
index d02e91e159..f94a30e066 100644
--- a/packages/ai-harness/src/plugins.ts
+++ b/packages/ai-harness/src/plugins.ts
@@ -8,6 +8,8 @@ import type {
   AnyTool,
   Capability,
   CapabilityHandle,
+  KeyedAdapter,
+  ProviderKeys,
 } from '@tanstack/ai'
 import type {
   AgentInputOf,
@@ -71,9 +73,10 @@ export interface PluginContributions {
   contribute?: ReadonlyArray<ExtensionItem>
   /**
    * Pick the main-loop adapter for the next turn, or return `undefined` to
-   * keep the harness adapter. The last plugin that returns one wins.
+   * keep the harness adapter. The last plugin that returns one wins. The
+   * session builds a `keyedAdapter(...)` with the user's key.
    */
-  adapter?: () => AnyTextAdapter | undefined
+  adapter?: () => AnyTextAdapter | KeyedAdapter<AnyTextAdapter> | undefined
   /**
    * Tools found at run time, for example the tools of an MCP server the user
    * signed in to after the session opened. Called before each chat turn. A
@@ -160,6 +163,7 @@ export interface PluginServices {
   config: { get: (key: string) => unknown }
   state: <T>(plugin: string, initial: T) => PluginState<T>
   credentials: CredentialsAccess
+  keys: ProviderKeys
   session: PluginSessionApi
   agents: PluginAgentActions
 }
@@ -201,6 +205,13 @@ export interface PluginSetupContext {
   config: { get: (key: string) => unknown }
   /** Credentials of the session's principal. */
   credentials: CredentialsAccess
+  /**
+   * Model provider keys of the session's principal: the key saved with
+   * `/connect <provider>`, else the provider's env var. Build a
+   * `keyedAdapter(...)` with `await ctx.keys.adapter(adapter)` just before
+   * the call. A missing key throws `AuthRequiredError`.
+   */
+  keys: ProviderKeys
   session: PluginSessionApi
 }
 
@@ -264,7 +275,7 @@ export interface MountedPlugins {
   config: Map<string, { option: ConfigOption; owner: string }>
   /** Contributions to extension points, by point name. */
   extensions: Map<string, Array<{ value: unknown; owner: string }>>
-  adapters: Array<() => AnyTextAdapter | undefined>
+  adapters: Array<NonNullable<PluginContributions['adapter']>>
   discoverers: Array<{
     discover: () => ReadonlyArray<AnyTool> | Promise<ReadonlyArray<AnyTool>>
     owner: string
@@ -338,6 +349,11 @@ const NO_SERVICES: PluginServices = {
     delete: unavailable('ctx.credentials'),
     list: unavailable('ctx.credentials'),
   },
+  keys: {
+    get: unavailable('ctx.keys'),
+    require: unavailable('ctx.keys'),
+    adapter: unavailable('ctx.keys'),
+  },
   session: {
     threadId: '',
     principal: undefined,
@@ -459,7 +475,7 @@ export async function mountPlugins(
   for (const [point, items] of env.inheritedExtensions ?? []) {
     extensions.set(point, [...items])
   }
-  const adapters: Array<() => AnyTextAdapter | undefined> = []
+  const adapters: MountedPlugins['adapters'] = []
   const discoverers: MountedPlugins['discoverers'] = []
   const preparers: MountedPlugins['preparers'] = []
   const subagents: Array<AnyAgent> = []
@@ -533,6 +549,7 @@ export async function mountPlugins(
         state: (initial) => services.state(plugin.name, initial),
         config: services.config,
         credentials: services.credentials,
+        keys: services.keys,
         session: services.session,
       })
       for (const handle of plugin.provides ?? []) {
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index a0e3faddee..527aab8a46 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -10,7 +10,7 @@ import {
   runAgentStream,
   validateWithStandardSchema,
 } from '@tanstack/ai'
-import { credentialsFor } from './auth'
+import { credentialsFor, providerKeysFor } from './auth'
 import { checkConfigValue } from './config'
 import { withPersistence } from '@tanstack/ai-persistence'
 import { AgentRegistry } from './agents'
@@ -32,6 +32,7 @@ import type {
   Interrupt,
   Modality,
   ModelMessage,
+  ProviderKeys,
   RunAgentResumeItem,
   SchemaInput,
   StreamChunk,
@@ -48,7 +49,7 @@ import type {
   InboxEntry,
   InboxStore,
 } from '@tanstack/ai-persistence'
-import type { CredentialsAccess } from './auth'
+import type { AuthRequiredError, CredentialsAccess } from './auth'
 import type { MediaStore } from './media'
 import type { PluginSessionApi, Question } from './commands'
 import type { ConfigOption } from './config'
@@ -140,6 +141,8 @@ export interface SessionSnapshot {
     questionId: string
     message: string
     schema?: unknown
+    /** The answer is a secret (a key or a password). Hide it as the user types. */
+    secret?: boolean
   }>
   /** The state of each plugin that uses `ctx.state`, by plugin name. */
   plugins: Record<string, unknown>
@@ -293,6 +296,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     {
       message: string
       schema: SchemaInput | undefined
+      secret: boolean
       resolve: (value: unknown) => void
       reject: (error: unknown) => void
     }
@@ -302,6 +306,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   private readonly stateLoaders = new Map<string, () => Promise<unknown>>()
   private readonly localState = new Map<string, unknown>()
   private readonly credentialAccess: CredentialsAccess
+  /** Model provider keys: saved with `/connect <provider>`, else the env var. */
+  private readonly keys: ProviderKeys
   private readonly services: PluginServices
   private readonly media: SessionDependencies['media']
   private readonly mediaStore: MediaStore
@@ -320,21 +326,23 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     this.principal = deps.principal
     this.onClose = deps.onClose
     this.checkpoint = checkpointMiddleware(deps.persistence, deps.hostId)
+    const onMissing = (error: AuthRequiredError) =>
+      this.feed.publish(
+        'session',
+        customEvent(HARNESS_EVENTS.authRequired, {
+          connector: error.connector,
+          ...(error.url ? { url: error.url } : {}),
+        }),
+      )
     this.credentialAccess = credentialsFor(
       deps.credentials,
       {
         threadId: deps.threadId,
         ...(deps.principal ? { userId: deps.principal.id } : {}),
       },
-      (error) =>
-        this.feed.publish(
-          'session',
-          customEvent(HARNESS_EVENTS.authRequired, {
-            connector: error.connector,
-            ...(error.url ? { url: error.url } : {}),
-          }),
-        ),
+      onMissing,
     )
+    this.keys = providerKeysFor(this.credentialAccess, onMissing)
     this.services = {
       emit: (plugin, name, value) => this.emitPluginEvent(plugin, name, value),
       on: (name, handler) => {
@@ -349,6 +357,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       config: { get: (key) => this.configValue(key) },
       state: (plugin, initial) => this.pluginState(plugin, initial),
       credentials: this.credentialAccess,
+      keys: this.keys,
       session: this.pluginApi(),
       agents: {
         run: ((target: string | AnyAgent, input?: unknown) =>
@@ -562,6 +571,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           ...(question.schema
             ? { schema: convertSchemaToJsonSchema(question.schema) }
             : {}),
+          ...(question.secret ? { secret: true } : {}),
         }),
       ),
       plugins: { ...this.stateDoc },
@@ -716,7 +726,14 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   /** Answer a question from `ctx.session.ask`. */
   async answer(questionId: string, value: unknown): Promise<Receipt> {
     const inputId = createInputId()
-    await this.accept(inputId, { op: 'answer', questionId, value })
+    // A secret (a key or a password) stays out of the inbox. A restart does
+    // not replay an answer, so the inbox never needs it.
+    const isSecret = this.questions.get(questionId)?.secret === true
+    await this.accept(inputId, {
+      op: 'answer',
+      questionId,
+      value: isSecret ? '[secret]' : value,
+    })
     const question = this.questions.get(questionId)
     if (!question) {
       this.reject(inputId, 'unknown_question')
@@ -802,6 +819,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       this.questions.set(questionId, {
         message: question.message,
         schema: question.schema,
+        secret: question.secret === true,
         resolve,
         reject,
       })
@@ -813,6 +831,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           ...(question.schema
             ? { schema: convertSchemaToJsonSchema(question.schema) }
             : {}),
+          ...(question.secret ? { secret: true } : {}),
         }),
       )
     })
@@ -1153,7 +1172,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
    * What every agent run of `operation` gets: the middleware of session
    * plugins, then of run plugins, then the session's media middleware. It
    * keeps the media the agents make, publishes a `harness.media` event for
-   * each file, and pushes its record to `captured`.
+   * each file, and pushes its record to `captured`. The agents read the
+   * session's provider keys as `ctx.keys`.
    */
   private binding(
     operation: OperationImpl<unknown> | OperationImpl<ChatTurnResult>,
@@ -1193,6 +1213,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           transcribe: options?.transcribe,
         }),
       ],
+      keys: this.keys,
     } satisfies SubagentBinding
   }
 
@@ -1309,7 +1330,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         [...staticTools, ...discovered],
         operation,
       )
-      const adapter: AnyTextAdapter = picked ?? this.harness.adapter
+      // A keyed adapter is built for this turn with the user's key. A
+      // missing key publishes `auth_required` and fails the turn.
+      const adapter: AnyTextAdapter = await this.keys.adapter(
+        picked ?? this.harness.adapter,
+      )
       const message =
         turn.message !== undefined
           ? await this.userMessage(turn.message)
diff --git a/packages/ai-harness/src/view/index.ts b/packages/ai-harness/src/view/index.ts
index 4975f3193e..50f7cb4ac6 100644
--- a/packages/ai-harness/src/view/index.ts
+++ b/packages/ai-harness/src/view/index.ts
@@ -371,6 +371,7 @@ export function createSessionView(source: SessionViewSource) {
       id: question.questionId,
       message: question.message,
       ...(question.schema ? { schema: question.schema } : {}),
+      ...(question.secret ? { secret: true } : {}),
       answer: (value) => {
         alive()
         return source.answer(question.questionId, value)
diff --git a/packages/ai-harness/src/view/types.ts b/packages/ai-harness/src/view/types.ts
index 0d1671db7b..deafd1dfed 100644
--- a/packages/ai-harness/src/view/types.ts
+++ b/packages/ai-harness/src/view/types.ts
@@ -81,6 +81,8 @@ export interface ViewQuestion {
   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
   answer: (value: unknown) => Promise<Receipt>
 }
 
diff --git a/packages/ai-harness/tests/provider-keys.test.ts b/packages/ai-harness/tests/provider-keys.test.ts
new file mode 100644
index 0000000000..e67ff3c83a
--- /dev/null
+++ b/packages/ai-harness/tests/provider-keys.test.ts
@@ -0,0 +1,392 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { EventType, defineAgent } from '@tanstack/ai'
+import { defineByokProvider, keyedAdapter } from '@tanstack/ai/byok'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { HARNESS_EVENTS, createHarnessHost, defineHarness } from '../src'
+import { compact, goal, modelPicker, providerKeys } from '../src/first-party'
+import { createSessionView } from '../src/view'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { AnyTextAdapter } from '@tanstack/ai'
+import type {
+  AnyAgent,
+  HarnessPlugin,
+  HarnessSession,
+  SessionEvent,
+} from '../src'
+
+const acme = defineByokProvider({
+  id: 'acme',
+  label: 'Acme',
+  env: 'ACME_TEST_KEY',
+})
+const beta = defineByokProvider({
+  id: 'beta',
+  label: 'Beta',
+  env: 'BETA_TEST_KEY',
+})
+const gamma = defineByokProvider({ id: 'gamma', label: 'Gamma' })
+
+/** The credential scope of the test user. */
+const USER = { threadId: 't', userId: 'user-1' }
+const SAVED_KEY = 'sk-acme-saved-1234'
+const PASTED_KEY = 'sk-acme-pasted-5678'
+
+afterEach(() => {
+  vi.unstubAllEnvs()
+})
+
+/** A keyed adapter for `acme` whose turns are scripted. Records each key it got. */
+function keyedMock(replies: Parameters<typeof mockAdapter>[0]) {
+  const mock = mockAdapter(replies)
+  const keys: Array<string> = []
+  const adapter = keyedAdapter(acme, (key) => {
+    keys.push(key)
+    return mock.adapter
+  })
+  return { adapter, keys, calls: mock.calls }
+}
+
+async function open(options: {
+  adapter: AnyTextAdapter | ReturnType<typeof keyedMock>['adapter']
+  plugins?: Array<HarnessPlugin>
+  agents?: Array<AnyAgent>
+  subagents?: Array<AnyAgent>
+}) {
+  const persistence = memoryPersistence()
+  const host = createHarnessHost({ persistence })
+  const session = await host.open(
+    defineHarness({
+      name: 'test/provider-keys',
+      adapter: options.adapter,
+      agents: options.agents ?? [],
+      subagents: { agents: options.subagents ?? [] },
+      plugins: () => options.plugins ?? [],
+    }),
+    { 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)
+  })()
+  const saveKey = (value: string) =>
+    persistence.stores.credentials.set(USER, 'acme', {
+      type: 'api_key',
+      value,
+    })
+  const close = async () => {
+    reader.abort()
+    await reading
+    await host.close()
+  }
+  return { session, persistence, events, saveKey, close }
+}
+
+/** The connectors named by the `harness.auth_required` events. */
+function authRequired(events: ReadonlyArray<SessionEvent>) {
+  return events.flatMap(({ event }) =>
+    event.type === EventType.CUSTOM &&
+    event.name === HARNESS_EVENTS.authRequired
+      ? [event.value]
+      : [],
+  )
+}
+
+/** Start `/connect acme`, and answer its question with `answer`. */
+async function connectWith(session: HarnessSession, answer: string) {
+  const result = session.command('connect:acme')
+  await vi.waitFor(() =>
+    expect(session.snapshot().pendingQuestions).toHaveLength(1),
+  )
+  const [question] = session.snapshot().pendingQuestions
+  const receipt = await session.answer(question?.questionId ?? '', answer)
+  return { question, receipt, result: await result }
+}
+
+describe('a keyed main adapter', () => {
+  it('uses the key saved in the credential store before the env var', async () => {
+    vi.stubEnv('ACME_TEST_KEY', 'sk-acme-env-0000')
+    const keyed = keyedMock([() => text('hello from acme')])
+    const { session, saveKey, close } = await open({ adapter: keyed.adapter })
+    await saveKey(SAVED_KEY)
+    expect(await session.prompt('hi')).toEqual({ text: 'hello from acme' })
+    expect(keyed.keys).toEqual([SAVED_KEY])
+    await close()
+  })
+
+  it('reads the env var when no key is saved', async () => {
+    vi.stubEnv('ACME_TEST_KEY', 'sk-acme-env-0000')
+    const keyed = keyedMock([() => text('hello')])
+    const { session, close } = await open({ adapter: keyed.adapter })
+    await session.prompt('hi')
+    expect(keyed.keys).toEqual(['sk-acme-env-0000'])
+    await close()
+  })
+
+  it('stops the turn and asks for a sign-in when there is no key', async () => {
+    vi.stubEnv('ACME_TEST_KEY', '')
+    const keyed = keyedMock([() => text('never')])
+    const { session, events, close } = await open({ adapter: keyed.adapter })
+    await expect(session.prompt('hi')).rejects.toThrow(
+      'Sign in to acme first. Run /connect acme.',
+    )
+    expect(keyed.calls).toHaveLength(0)
+    expect(authRequired(events)).toEqual([{ connector: 'acme' }])
+    await close()
+  })
+
+  it('builds a keyed model picker choice after /model', async () => {
+    const plain = mockAdapter([() => text('plain answer')])
+    const keyed = keyedMock([() => text('keyed answer')])
+    const { session, saveKey, close } = await open({
+      adapter: plain.adapter,
+      plugins: [
+        modelPicker({
+          choices: { plain: plain.adapter, acme: keyed.adapter },
+          default: 'plain',
+        }),
+      ],
+    })
+    await saveKey(SAVED_KEY)
+    await session.command('model', 'acme')
+    expect(await session.prompt('hi')).toEqual({ text: 'keyed answer' })
+    expect(keyed.keys).toEqual([SAVED_KEY])
+    await close()
+  })
+})
+
+describe('ctx.keys in agents', () => {
+  /** An agent that builds a keyed adapter with `ctx.keys` and answers with it. */
+  function writerWith(adapter: ReturnType<typeof keyedMock>['adapter']) {
+    return defineAgent({
+      name: 'writer',
+      description: 'Writes with the Acme model',
+      run: async (ctx) =>
+        ctx.chat({ adapter: await ctx.keys.adapter(adapter), stream: false }),
+    })
+  }
+
+  it('gives a background agent the session keys', async () => {
+    const keyed = keyedMock([() => text('agent answer')])
+    const { session, saveKey, close } = await open({
+      adapter: mockAdapter([]).adapter,
+      agents: [writerWith(keyed.adapter)],
+    })
+    await saveKey(SAVED_KEY)
+    expect(await session.agent('writer')?.run()).toBe('agent answer')
+    expect(keyed.keys).toEqual([SAVED_KEY])
+    await close()
+  })
+
+  it('gives a subagent the model calls the session keys', async () => {
+    const keyed = keyedMock([() => text('draft')])
+    const lead = mockAdapter([
+      () => toolCall('writer', {}),
+      () => text('The writer is done.'),
+    ])
+    const { session, saveKey, close } = await open({
+      adapter: lead.adapter,
+      subagents: [writerWith(keyed.adapter)],
+    })
+    await saveKey(SAVED_KEY)
+    expect(await session.prompt('write it')).toEqual({
+      text: 'The writer is done.',
+    })
+    expect(keyed.keys).toEqual([SAVED_KEY])
+    await close()
+  })
+})
+
+describe('compact and goal with a keyed adapter', () => {
+  it('compacts with the saved key', async () => {
+    const summarizer = keyedMock([() => text('We talked.')])
+    const main = mockAdapter([() => text('one'), () => text('two')])
+    const { session, saveKey, close } = await open({
+      adapter: main.adapter,
+      plugins: [compact({ adapter: summarizer.adapter })],
+    })
+    await saveKey(SAVED_KEY)
+    await session.prompt('first')
+    await session.prompt('second')
+    expect(await session.command('compact')).toBe(
+      'Compacted 4 messages into a summary.',
+    )
+    expect(summarizer.keys).toEqual([SAVED_KEY])
+    await close()
+  })
+
+  it('judges the goal with the saved key', async () => {
+    const keys: Array<string> = []
+    const keyedJudge = keyedAdapter(acme, (key) => {
+      keys.push(key)
+      const judge: AnyTextAdapter = {
+        ...mockAdapter([]).adapter,
+        structuredOutput: async () => ({
+          data: { met: true, reason: 'Done.' },
+          rawText: '{"met":true,"reason":"Done."}',
+        }),
+      }
+      return judge
+    })
+    const { session, saveKey, close } = await open({
+      adapter: mockAdapter([() => text('did it')]).adapter,
+      plugins: [goal({ judge: keyedJudge })],
+    })
+    await saveKey(SAVED_KEY)
+    await session.command('goal', 'ship it')
+    await vi.waitFor(async () =>
+      expect(await session.command('goal')).toContain('Status: met'),
+    )
+    expect(keys).toEqual([SAVED_KEY])
+    await close()
+  })
+})
+
+describe('providerKeys', () => {
+  function plugin() {
+    return providerKeys({ providers: [acme, beta, gamma] })
+  }
+
+  it('saves a pasted key and shows it masked', async () => {
+    const { session, persistence, close } = await open({
+      adapter: mockAdapter([]).adapter,
+      plugins: [plugin()],
+    })
+    const { question, result } = await connectWith(session, `  ${PASTED_KEY}  `)
+    expect(question).toMatchObject({
+      message: 'Paste your Acme API key',
+      secret: true,
+    })
+    expect(result).toBe('Connected to Acme (key ...5678).')
+    expect(await persistence.stores.credentials.get(USER, 'acme')).toEqual({
+      type: 'api_key',
+      value: PASTED_KEY,
+    })
+    expect(await session.command('keys')).toContain(
+      'Acme: connected (key ...5678)',
+    )
+    await close()
+  })
+
+  it('refuses an empty key', async () => {
+    const { session, persistence, close } = await open({
+      adapter: mockAdapter([]).adapter,
+      plugins: [plugin()],
+    })
+    await expect(connectWith(session, '   ')).rejects.toThrow(
+      'No Acme key was given. Nothing was saved.',
+    )
+    expect(await persistence.stores.credentials.get(USER, 'acme')).toBeNull()
+    await close()
+  })
+
+  it('deletes the key on disconnect', async () => {
+    const { session, persistence, saveKey, close } = await open({
+      adapter: mockAdapter([]).adapter,
+      plugins: [plugin()],
+    })
+    await saveKey(SAVED_KEY)
+    expect(await session.command('disconnect:acme')).toBe(
+      'Disconnected from Acme.',
+    )
+    expect(await persistence.stores.credentials.get(USER, 'acme')).toBeNull()
+    expect(await session.command('keys')).toContain(
+      'Acme: missing. Run /connect acme.',
+    )
+    await close()
+  })
+
+  it('runs signIn with open through authRequired and saves its key', async () => {
+    const signIn = async (ctx: { open: (url: string) => void }) => {
+      ctx.open('https://acme.example/sign-in')
+      return 'sk-acme-signed-9876'
+    }
+    const { session, persistence, events, close } = await open({
+      adapter: mockAdapter([]).adapter,
+      plugins: [providerKeys({ providers: [{ ...acme, signIn }] })],
+    })
+    expect(await session.command('connect:acme')).toBe(
+      'Connected to Acme (key ...9876).',
+    )
+    expect(authRequired(events)).toEqual([
+      { connector: 'acme', url: 'https://acme.example/sign-in' },
+    ])
+    expect(await persistence.stores.credentials.get(USER, 'acme')).toEqual({
+      type: 'api_key',
+      value: 'sk-acme-signed-9876',
+    })
+    await close()
+  })
+
+  it('lists every provider with its state in the plugin state', async () => {
+    vi.stubEnv('BETA_TEST_KEY', 'sk-beta-env-4321')
+    const { session, close } = await open({
+      adapter: mockAdapter([]).adapter,
+      plugins: [plugin()],
+    })
+    expect(session.snapshot().plugins['tanstack/provider-keys']).toEqual({
+      providers: [
+        { id: 'acme', label: 'Acme', state: 'missing' },
+        { id: 'beta', label: 'Beta', state: 'env' },
+        { id: 'gamma', label: 'Gamma', state: 'missing' },
+      ],
+    })
+    expect(await session.command('keys')).toBe(
+      [
+        'Acme: missing. Run /connect acme.',
+        'Beta: from the BETA_TEST_KEY env var',
+        'Gamma: missing. Run /connect gamma.',
+      ].join('\n'),
+    )
+    await connectWith(session, PASTED_KEY)
+    expect(session.snapshot().plugins['tanstack/provider-keys']).toEqual({
+      providers: [
+        { id: 'acme', label: 'Acme', state: 'connected' },
+        { id: 'beta', label: 'Beta', state: 'env' },
+        { id: 'gamma', label: 'Gamma', state: 'missing' },
+      ],
+    })
+    await close()
+  })
+
+  it('shows a secret question as secret in the view', async () => {
+    const { session, close } = await open({
+      adapter: mockAdapter([]).adapter,
+      plugins: [plugin()],
+    })
+    const view = createSessionView(session)
+    await view.ready
+    const connecting = session.command('connect:acme')
+    await vi.waitFor(() =>
+      expect(view.store.get().questions).toMatchObject([
+        { message: 'Paste your Acme API key', secret: true },
+      ]),
+    )
+    await view.store.get().questions[0]?.answer(PASTED_KEY)
+    await connecting
+    view.dispose()
+    await close()
+  })
+
+  it('keeps the key out of events, results, the inbox, and the transcript', async () => {
+    const keyed = keyedMock([() => text('hello')])
+    const { session, persistence, events, close } = await open({
+      adapter: keyed.adapter,
+      plugins: [plugin()],
+    })
+    const { receipt, result } = await connectWith(session, PASTED_KEY)
+    const results = [
+      result,
+      await session.command('keys'),
+      await session.prompt('hi'),
+    ]
+    expect(keyed.keys).toEqual([PASTED_KEY])
+    const inbox = await persistence.stores.inbox.get(receipt.inputId)
+    const transcript = await persistence.stores.messages.loadThread('t')
+    const everything = JSON.stringify({ events, results, inbox, transcript })
+    expect(everything).not.toContain(PASTED_KEY)
+    expect(everything).toContain('...5678')
+    await close()
+  })
+})
diff --git a/packages/ai-openrouter/src/pkce.ts b/packages/ai-openrouter/src/pkce.ts
index 96a426fc68..530c89f86a 100644
--- a/packages/ai-openrouter/src/pkce.ts
+++ b/packages/ai-openrouter/src/pkce.ts
@@ -6,6 +6,11 @@ const KEYS_URL = `${AUTH_ORIGIN}/api/v1/auth/keys`
 const PENDING_STORAGE_KEY = 'byok:openrouter:pkce:v1'
 const VERIFIER_CHARS =
   'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~'
+const SIGN_IN_TIMEOUT_MS = 10 * 60_000
+const SIGNED_IN_PAGE =
+  '<!doctype html><title>Signed in</title><p>You are signed in to OpenRouter. You can close this tab.</p>'
+const SIGN_IN_FAILED_PAGE =
+  '<!doctype html><title>Sign-in failed</title><p>OpenRouter sign-in failed. You can close this tab and try again.</p>'
 
 export type OpenRouterPkceChallengeMethod = 'S256'
 
@@ -33,6 +38,12 @@ export interface ExchangeOpenRouterCodeOptions {
   fetchImpl?: typeof fetch
 }
 
+export interface OpenRouterSignInOptions {
+  /** How long to wait for the browser to come back. Default: 10 minutes. */
+  timeoutMs?: number
+  fetchImpl?: typeof fetch
+}
+
 export interface CompleteOpenRouterPkceFromUrlOptions {
   url?: string
   fetchImpl?: typeof fetch
@@ -48,12 +59,12 @@ export interface OpenRouterByokStore {
   update: (provider: string, key: string) => void | Promise<void>
 }
 
-function getSessionStorage(): Storage | null {
+function getSessionStorage() {
   if (typeof globalThis.sessionStorage === 'undefined') return null
   return globalThis.sessionStorage
 }
 
-function base64UrlEncode(bytes: Uint8Array): string {
+function base64UrlEncode(bytes: Uint8Array) {
   let binary = ''
   for (const byte of bytes) {
     binary += String.fromCharCode(byte)
@@ -65,7 +76,7 @@ function base64UrlEncode(bytes: Uint8Array): string {
   return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
 }
 
-export function generateCodeVerifier(length = 64): string {
+export function generateCodeVerifier(length = 64) {
   const size = Math.min(128, Math.max(43, length))
   const bytes = crypto.getRandomValues(new Uint8Array(size))
   let out = ''
@@ -76,9 +87,7 @@ export function generateCodeVerifier(length = 64): string {
   return out
 }
 
-export async function createS256CodeChallenge(
-  codeVerifier: string,
-): Promise<string> {
+export async function createS256CodeChallenge(codeVerifier: string) {
   const digest = await crypto.subtle.digest(
     'SHA-256',
     new TextEncoder().encode(codeVerifier),
@@ -86,9 +95,7 @@ export async function createS256CodeChallenge(
   return base64UrlEncode(new Uint8Array(digest))
 }
 
-export function buildOpenRouterAuthUrl(
-  options: OpenRouterAuthUrlOptions,
-): string {
+export function buildOpenRouterAuthUrl(options: OpenRouterAuthUrlOptions) {
   const url = new URL(AUTH_PATH, AUTH_ORIGIN)
   url.searchParams.set('callback_url', options.callbackUrl)
   if (options.codeChallenge) {
@@ -101,13 +108,11 @@ export function buildOpenRouterAuthUrl(
   return url.toString()
 }
 
-export function storeOpenRouterPkcePending(
-  pending: OpenRouterPkcePending,
-): void {
+export function storeOpenRouterPkcePending(pending: OpenRouterPkcePending) {
   getSessionStorage()?.setItem(PENDING_STORAGE_KEY, JSON.stringify(pending))
 }
 
-export function loadOpenRouterPkcePending(): OpenRouterPkcePending | null {
+export function loadOpenRouterPkcePending() {
   const raw = getSessionStorage()?.getItem(PENDING_STORAGE_KEY)
   if (!raw) return null
   try {
@@ -121,24 +126,28 @@ export function loadOpenRouterPkcePending(): OpenRouterPkcePending | null {
     if (typeof codeVerifier !== 'string') return null
     if (codeChallengeMethod !== 'S256') return null
     if (typeof callbackUrl !== 'string') return null
-    return { codeVerifier, codeChallengeMethod, callbackUrl }
+    return {
+      codeVerifier,
+      codeChallengeMethod,
+      callbackUrl,
+    } satisfies OpenRouterPkcePending
   } catch {
     return null
   }
 }
 
-export function clearOpenRouterPkcePending(): void {
+export function clearOpenRouterPkcePending() {
   getSessionStorage()?.removeItem(PENDING_STORAGE_KEY)
 }
 
-export function defaultOpenRouterCallbackUrl(): string {
+export function defaultOpenRouterCallbackUrl() {
   if (typeof globalThis.location === 'undefined') return ''
   return `${globalThis.location.origin}${globalThis.location.pathname}`
 }
 
 export async function startOpenRouterPkceLogin(
   options: StartOpenRouterPkceOptions = {},
-): Promise<void> {
+) {
   const callbackUrl = options.callbackUrl ?? defaultOpenRouterCallbackUrl()
   if (!callbackUrl) {
     throw new Error('OpenRouter PKCE login requires a callbackUrl')
@@ -165,7 +174,7 @@ export async function startOpenRouterPkceLogin(
 
 export async function exchangeOpenRouterCode(
   options: ExchangeOpenRouterCodeOptions,
-): Promise<string> {
+) {
   const fetchImpl = options.fetchImpl ?? fetch
   const body: Record<string, string> = { code: options.code }
   if (options.codeVerifier) {
@@ -204,7 +213,7 @@ export async function exchangeOpenRouterCode(
   return data.key
 }
 
-export function stripOpenRouterCodeFromUrl(href?: string): void {
+export function stripOpenRouterCodeFromUrl(href?: string) {
   if (typeof globalThis.history === 'undefined') return
   const base = href ?? globalThis.location.href
   const url = new URL(base)
@@ -216,7 +225,7 @@ export function stripOpenRouterCodeFromUrl(href?: string): void {
 
 export async function completeOpenRouterPkceFromUrl(
   options: CompleteOpenRouterPkceFromUrlOptions = {},
-): Promise<string | null> {
+) {
   const href =
     options.url ??
     (typeof globalThis.location !== 'undefined' ? globalThis.location.href : '')
@@ -247,9 +256,108 @@ export async function completeOpenRouterPkceFromUrl(
 export async function completeOpenRouterPkceIntoByok(
   byok: OpenRouterByokStore,
   options: CompleteOpenRouterPkceFromUrlOptions = {},
-): Promise<string | null> {
+) {
   const key = await completeOpenRouterPkceFromUrl(options)
   if (!key) return null
   await byok.update(openrouterByok.id, key)
   return key
 }
+
+/**
+ * OpenRouter sign-in for a local app, such as a CLI. The user signs in with a
+ * browser and the app gets an API key (PKCE with S256), so nobody copies a
+ * key by hand.
+ *
+ * The returned `signIn` starts a one-time listener on `127.0.0.1`, calls
+ * `open` with the OpenRouter sign-in URL, and waits for the browser to come
+ * back. Then it trades the code for a key and resolves with the key. The
+ * listener closes when `signIn` settles. `signIn` rejects when the state does
+ * not match, after `timeoutMs`, or when `signal` aborts.
+ *
+ * `node:http` loads only when `signIn` runs, so this module stays safe to
+ * import in a browser.
+ *
+ * @example
+ * const signIn = openrouterSignIn()
+ * const key = await signIn({ open: (url) => console.log(`Open ${url}`) })
+ */
+export function openrouterSignIn(options: OpenRouterSignInOptions = {}) {
+  return async (ctx: { open: (url: string) => void; signal?: AbortSignal }) => {
+    const { createServer } = await import('node:http')
+    const codeVerifier = generateCodeVerifier()
+    const codeChallenge = await createS256CodeChallenge(codeVerifier)
+    // OpenRouter sends back only `?code=`, so our state goes in the path.
+    const state = base64UrlEncode(crypto.getRandomValues(new Uint8Array(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 callbackPath = `/callback/${state}`
+    const callbackUrl = `http://127.0.0.1:${port}${callbackPath}`
+    // Aborts when `signIn` settles: it stops the timer and the abort listener.
+    const settled = new AbortController()
+    try {
+      const code = await new Promise<string>((resolve, reject) => {
+        const { signal } = ctx
+        if (signal?.aborted) {
+          reject(signal.reason)
+          return
+        }
+        signal?.addEventListener('abort', () => reject(signal.reason), {
+          signal: settled.signal,
+        })
+        const timer = setTimeout(
+          () => reject(new Error('OpenRouter sign-in timed out.')),
+          options.timeoutMs ?? SIGN_IN_TIMEOUT_MS,
+        )
+        settled.signal.addEventListener('abort', () => clearTimeout(timer))
+        server.on('request', (req, res) => {
+          const url = new URL(req.url ?? '/', callbackUrl)
+          if (!url.pathname.startsWith('/callback/')) {
+            res.writeHead(404).end()
+            return
+          }
+          const hasState = url.pathname === callbackPath
+          const returnedCode = url.searchParams.get('code')
+          const isSignedIn = hasState && Boolean(returnedCode)
+          res
+            .writeHead(isSignedIn ? 200 : 400, {
+              'content-type': 'text/html; charset=utf-8',
+              // The browser does not keep the connection, so the listener can close.
+              connection: 'close',
+            })
+            .end(isSignedIn ? SIGNED_IN_PAGE : SIGN_IN_FAILED_PAGE)
+          if (!hasState) {
+            reject(
+              new Error('OpenRouter sign-in failed: the state does not match.'),
+            )
+          } else if (!returnedCode) {
+            reject(
+              new Error('OpenRouter sign-in failed: the callback has no code.'),
+            )
+          } else resolve(returnedCode)
+        })
+        ctx.open(
+          buildOpenRouterAuthUrl({
+            callbackUrl,
+            codeChallenge,
+            codeChallengeMethod: 'S256',
+          }),
+        )
+      })
+      return await exchangeOpenRouterCode({
+        code,
+        codeVerifier,
+        codeChallengeMethod: 'S256',
+        fetchImpl: options.fetchImpl,
+      })
+    } finally {
+      settled.abort()
+      server.close()
+      server.closeIdleConnections()
+    }
+  }
+}
diff --git a/packages/ai-openrouter/tests/pkce-sign-in.test.ts b/packages/ai-openrouter/tests/pkce-sign-in.test.ts
new file mode 100644
index 0000000000..20ab3d519d
--- /dev/null
+++ b/packages/ai-openrouter/tests/pkce-sign-in.test.ts
@@ -0,0 +1,116 @@
+import { createHash } from 'node:crypto'
+import { describe, expect, it } from 'vitest'
+import { openrouterSignIn } from '../src/pkce'
+
+interface KeyExchangeBody {
+  code: string
+  code_verifier: string
+  code_challenge_method: string
+}
+
+/** Stands in for OpenRouter's key endpoint and keeps each request body. */
+function keyEndpoint() {
+  const bodies: Array<KeyExchangeBody> = []
+  const fetchImpl: typeof fetch = async (_input, init) => {
+    bodies.push(JSON.parse(typeof init?.body === 'string' ? init.body : '{}'))
+    return new Response(JSON.stringify({ key: 'sk-or-v1-live' }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    })
+  }
+  return { fetchImpl, bodies }
+}
+
+function callbackOf(authUrl: string) {
+  return new URL(new URL(authUrl).searchParams.get('callback_url') ?? '')
+}
+
+/**
+ * Plays the browser and OpenRouter. It keeps each auth URL. With `redirect`,
+ * it changes the callback URL the way OpenRouter does (adds `?code=`), then
+ * visits it and keeps the page text.
+ */
+function fakeBrowser(redirect?: (callback: URL) => void) {
+  const authUrls: Array<string> = []
+  const pages: Array<Promise<string>> = []
+  const open = (authUrl: string) => {
+    authUrls.push(authUrl)
+    if (!redirect) return
+    const callback = callbackOf(authUrl)
+    redirect(callback)
+    pages.push(fetch(callback).then((response) => response.text()))
+  }
+  return { open, authUrls, pages }
+}
+
+/** The listener is closed when a new request to its callback URL cannot connect. */
+async function expectListenerClosed(authUrl: string | undefined) {
+  expect(authUrl).toBeDefined()
+  await expect(fetch(callbackOf(authUrl ?? ''))).rejects.toThrow('fetch failed')
+}
+
+describe('openrouterSignIn', () => {
+  it('gets a key through a one-time listener on 127.0.0.1', async () => {
+    const { fetchImpl, bodies } = keyEndpoint()
+    const browser = fakeBrowser((callback) => {
+      callback.searchParams.set('code', 'abc')
+    })
+
+    const key = await openrouterSignIn({ fetchImpl })({ open: browser.open })
+
+    expect(key).toBe('sk-or-v1-live')
+    const [authUrl] = browser.authUrls
+    expect(callbackOf(authUrl ?? '').hostname).toBe('127.0.0.1')
+    expect(bodies).toEqual([
+      {
+        code: 'abc',
+        code_verifier: expect.any(String),
+        code_challenge_method: 'S256',
+      },
+    ])
+    // RFC 7636 S256: the challenge in the auth URL is base64url(sha256(verifier)).
+    const verifier = bodies[0]?.code_verifier ?? ''
+    expect(new URL(authUrl ?? '').searchParams.get('code_challenge')).toBe(
+      createHash('sha256').update(verifier).digest('base64url'),
+    )
+    expect(await browser.pages[0]).toContain('You can close this tab')
+    await expectListenerClosed(authUrl)
+  })
+
+  it('rejects a callback with the wrong state', async () => {
+    const { fetchImpl, bodies } = keyEndpoint()
+    const browser = fakeBrowser((callback) => {
+      callback.pathname = '/callback/forged'
+      callback.searchParams.set('code', 'abc')
+    })
+
+    await expect(
+      openrouterSignIn({ fetchImpl })({ open: browser.open }),
+    ).rejects.toThrow('the state does not match')
+    expect(bodies).toEqual([])
+  })
+
+  it('rejects when the browser does not come back in time', async () => {
+    const browser = fakeBrowser()
+
+    await expect(
+      openrouterSignIn({ timeoutMs: 20 })({ open: browser.open }),
+    ).rejects.toThrow('OpenRouter sign-in timed out')
+  })
+
+  it('rejects on abort and closes the listener', async () => {
+    const controller = new AbortController()
+    const browser = fakeBrowser()
+
+    await expect(
+      openrouterSignIn()({
+        open: (authUrl) => {
+          browser.open(authUrl)
+          controller.abort()
+        },
+        signal: controller.signal,
+      }),
+    ).rejects.toMatchObject({ name: 'AbortError' })
+    await expectListenerClosed(browser.authUrls[0])
+  })
+})
diff --git a/packages/ai/src/activities/chat/agents/bound.ts b/packages/ai/src/activities/chat/agents/bound.ts
index 22e1a2b21f..8566325366 100644
--- a/packages/ai/src/activities/chat/agents/bound.ts
+++ b/packages/ai/src/activities/chat/agents/bound.ts
@@ -16,6 +16,7 @@ import type { AnyChatMiddleware } from '../middleware/types'
 import type { RunAgentResumeItem } from '../../../types'
 import type { SubagentRunInput } from './define-agent'
 import type { SubagentBudget } from './limits'
+import type { ProviderKeys } from '../../../byok/keyed'
 
 /**
  * The fields a child `chat()` needs, in one spread:
@@ -52,6 +53,12 @@ export interface SubagentBinding {
    * down, so limits hold across the whole tree.
    */
   budget?: SubagentBudget
+  /**
+   * The provider keys an agent reads as `ctx.keys`. A child's
+   * `ctx.chat({ subagents })` passes them down to its own children. Without
+   * them, `ctx.keys` reads each provider's `env` names.
+   */
+  keys?: ProviderKeys
 }
 
 /**
@@ -124,13 +131,14 @@ export function createBoundActivities(
         ...(input.resume ? { resume: input.resume } : {}),
         abortController,
         ...options,
-        // Nested children get the host middleware before their own, and share
-        // the tree budget.
+        // Nested children get the host middleware before their own, share
+        // the tree budget, and get the host keys unless the call sets its own.
         ...(options.subagents
           ? {
               subagents: {
                 ...options.subagents,
                 binding: {
+                  ...(binding?.keys ? { keys: binding.keys } : {}),
                   ...options.subagents.binding,
                   chatMiddleware: [
                     ...chatMiddleware,
diff --git a/packages/ai/src/activities/chat/agents/define-agent.ts b/packages/ai/src/activities/chat/agents/define-agent.ts
index 0ffde9cca0..0d20ba4303 100644
--- a/packages/ai/src/activities/chat/agents/define-agent.ts
+++ b/packages/ai/src/activities/chat/agents/define-agent.ts
@@ -11,6 +11,7 @@ import type {
 } from '../../../types'
 import type { AnyClientTool } from '../tools/tool-definition'
 import type { BoundActivities, SubagentForward } from './bound'
+import type { ProviderKeys } from '../../../byok/keyed'
 
 /**
  * What the library knows about a child run before `run` starts.
@@ -55,9 +56,14 @@ export interface SubagentRunInput<
  * - The activity functions (`ctx.chat`, `ctx.generateImage`, and the rest)
  *   take the same options as the plain functions and fill in the thread id,
  *   a run id, the abort signal, and any middleware a host adds.
+ * - `keys` finds provider keys. `await ctx.keys.adapter(adapter)` builds a
+ *   `keyedAdapter(...)`. A host sets the keys. Without a host, they come
+ *   from each provider's `env` names, and a missing key throws an error that
+ *   names the env var.
  */
 export type SubagentRunContext<TInput extends SchemaInput | undefined = any> =
-  SubagentRunInput<TInput> & BoundActivities & { forward: SubagentForward }
+  SubagentRunInput<TInput> &
+    BoundActivities & { forward: SubagentForward; keys: ProviderKeys }
 
 /**
  * What an agent makes. Informative: plugins use it to find an agent by the
diff --git a/packages/ai/src/activities/chat/agents/spawn.ts b/packages/ai/src/activities/chat/agents/spawn.ts
index fcc8db333d..80a9732b28 100644
--- a/packages/ai/src/activities/chat/agents/spawn.ts
+++ b/packages/ai/src/activities/chat/agents/spawn.ts
@@ -25,6 +25,7 @@ import type {
   Tool,
   UIMessage,
 } from '../../../types'
+import { envProviderKeys } from '../../../byok/env-keys'
 import { createBoundActivities } from './bound'
 import { SubagentBudget } from './limits'
 import type { SubagentBinding } from './bound'
@@ -479,8 +480,8 @@ function* valueResultChunks(
 }
 
 /**
- * Build the context `run` receives: the spawn input plus `forward` and the
- * bound activity functions.
+ * Build the context `run` receives: the spawn input plus `forward`, the
+ * provider keys, and the bound activity functions.
  */
 function runContext(
   agentName: string,
@@ -498,6 +499,7 @@ function runContext(
       ...(input.resume ? { resume: input.resume } : {}),
       abortController,
     },
+    keys: binding?.keys ?? envProviderKeys,
     ...createBoundActivities(agentName, input, abortController, binding),
   } satisfies SubagentRunContext
 }
diff --git a/packages/ai/src/byok.ts b/packages/ai/src/byok.ts
index 57d25f2d9e..eeff8dfd11 100644
--- a/packages/ai/src/byok.ts
+++ b/packages/ai/src/byok.ts
@@ -15,3 +15,5 @@ export {
   ByokUnresolvedProviderError,
 } from './byok/errors'
 export { maskKey, scrubSecrets } from './byok/scrub'
+export { keyedAdapter, isKeyedAdapter } from './byok/keyed'
+export type { KeyedAdapter, ProviderKeys } from './byok/keyed'
diff --git a/packages/ai/src/byok/env-keys.ts b/packages/ai/src/byok/env-keys.ts
new file mode 100644
index 0000000000..d1e4ddc4df
--- /dev/null
+++ b/packages/ai/src/byok/env-keys.ts
@@ -0,0 +1,31 @@
+import { envKey } from './get-key'
+import { isKeyedAdapter } from './keyed'
+import type { ByokProvider } from './define-provider'
+import type { ProviderKeys } from './keyed'
+import type { ProviderId } from './providers'
+
+function missingKeyMessage(provider: ByokProvider | ProviderId) {
+  if (typeof provider === 'string') return `Missing ${provider} API key.`
+  const names = provider.env ?? []
+  const hint = names.length > 0 ? ` Set ${names.join(' or ')}.` : ''
+  return `Missing ${provider.label} API key.${hint}`
+}
+
+async function requireEnvKey(provider: ByokProvider | ProviderId) {
+  const key = envKey(provider)
+  if (key === null) throw new Error(missingKeyMessage(provider))
+  return key
+}
+
+/**
+ * The `ctx.keys` of an agent whose host sets no keys: each provider's `env`
+ * names. Not in `@tanstack/ai/byok`, so the client entry has no env access.
+ */
+export const envProviderKeys: ProviderKeys = {
+  get: async (provider) => envKey(provider),
+  require: requireEnvKey,
+  adapter: async (adapter) =>
+    isKeyedAdapter(adapter)
+      ? adapter.create(await requireEnvKey(adapter.provider))
+      : adapter,
+}
diff --git a/packages/ai/src/byok/get-key.ts b/packages/ai/src/byok/get-key.ts
index cd4da99c0c..9fc3983178 100644
--- a/packages/ai/src/byok/get-key.ts
+++ b/packages/ai/src/byok/get-key.ts
@@ -2,6 +2,21 @@ import { byokHeaderName, resolveProviderId } from './providers'
 import type { ByokProvider } from './define-provider'
 import type { ProviderId } from './providers'
 
+/**
+ * Read `provider.env` in order and return the first value that is set. A
+ * slug has no env names. Where `process` is missing (a browser) it returns
+ * `null`.
+ */
+export function envKey(provider: ProviderId | ByokProvider) {
+  if (typeof provider === 'string') return null
+  const env = globalThis.process?.env
+  for (const name of provider.env ?? []) {
+    const value = env?.[name]
+    if (typeof value === 'string' && value.length > 0) return value
+  }
+  return null
+}
+
 /**
  * Read a key on the relay. Import from `@tanstack/ai/byok/server` so this
  * `process.env` access is not in the client graph.
@@ -12,18 +27,13 @@ import type { ProviderId } from './providers'
 export function getByokKey(
   request: Request,
   provider: ProviderId | ByokProvider,
-): string | null {
+) {
   const value = request.headers.get(byokHeaderName(resolveProviderId(provider)))
   if (typeof value === 'string') {
     const trimmed = value.trim()
     if (trimmed.length > 0) return trimmed
   }
-  if (typeof provider === 'string') return null
-  for (const name of provider.env ?? []) {
-    const envValue = process.env[name]
-    if (typeof envValue === 'string' && envValue.length > 0) return envValue
-  }
-  return null
+  return envKey(provider)
 }
 
 /**
@@ -32,10 +42,7 @@ export function getByokKey(
  */
 export function getByokKeys<
   const TProviders extends Record<string, ProviderId | ByokProvider>,
->(
-  request: Request,
-  providers: TProviders,
-): { [K in keyof TProviders]: string | null } {
+>(request: Request, providers: TProviders) {
   return Object.fromEntries(
     Object.entries(providers).map(([name, provider]) => [
       name,
diff --git a/packages/ai/src/byok/keyed.ts b/packages/ai/src/byok/keyed.ts
new file mode 100644
index 0000000000..8551c66917
--- /dev/null
+++ b/packages/ai/src/byok/keyed.ts
@@ -0,0 +1,85 @@
+import { isProviderId, resolveProviderId } from './providers'
+import type { ByokProvider } from './define-provider'
+import type { ProviderId } from './providers'
+
+const KEYED_ADAPTER = Symbol.for('tanstack.ai.keyedAdapter')
+
+/**
+ * An adapter that needs a provider key before it exists. Make one with
+ * {@link keyedAdapter}. {@link ProviderKeys.adapter} builds it just before a
+ * call.
+ */
+export interface KeyedAdapter<TAdapter> {
+  readonly [KEYED_ADAPTER]: true
+  /** The provider whose key `create` needs. */
+  readonly provider: ByokProvider | ProviderId
+  /** Builds the adapter from the key. */
+  readonly create: (key: string) => TAdapter
+}
+
+/**
+ * Finds provider keys for a run. An agent reads it as `ctx.keys`. A host, for
+ * example a harness session, sets it on the binding and reads each user's
+ * own keys. Without a host, `ctx.keys` reads each provider's `env` names.
+ */
+export interface ProviderKeys {
+  /** The key for `provider`, or `null` when there is none. */
+  get: (provider: ByokProvider | ProviderId) => Promise<string | null>
+  /** The key for `provider`. Throws when there is none. */
+  require: (provider: ByokProvider | ProviderId) => Promise<string>
+  /**
+   * The adapter to call. A plain adapter comes back unchanged. A
+   * {@link KeyedAdapter} is built with the key from `require`.
+   */
+  adapter: <TAdapter>(
+    adapter: TAdapter | KeyedAdapter<TAdapter>,
+  ) => Promise<TAdapter>
+}
+
+/**
+ * Wrap an adapter factory that needs a provider key. The host finds the key
+ * and calls `create` just before each call, so the key is not in your code
+ * or in a `.env` file. Works for every adapter kind: text, image, speech,
+ * audio, video, and the rest.
+ *
+ * @param provider - The provider whose key `create` needs: a BYOK descriptor
+ *   such as `openaiByok` (its `env` names are the fallback), or a provider id.
+ * @param create - Builds the adapter from the key.
+ * @throws Error when the provider id is not a valid BYOK slug.
+ *
+ * @example
+ * ```ts
+ * import { createOpenaiChat } from '@tanstack/ai-openai'
+ * import { openaiByok } from '@tanstack/ai-openai/byok'
+ *
+ * const adapter = keyedAdapter(openaiByok, (key) =>
+ *   createOpenaiChat('gpt-5.5', key),
+ * )
+ * // In an agent: chat({ adapter: await ctx.keys.adapter(adapter), ... })
+ * ```
+ */
+export function keyedAdapter<TAdapter>(
+  provider: ByokProvider | ProviderId,
+  create: (key: string) => TAdapter,
+) {
+  const id = resolveProviderId(provider)
+  if (!isProviderId(id)) {
+    throw new Error(`Invalid BYOK provider id: ${id}`)
+  }
+  const keyed: KeyedAdapter<TAdapter> = {
+    [KEYED_ADAPTER]: true,
+    provider,
+    create,
+  }
+  return keyed
+}
+
+/**
+ * True when `value` came from {@link keyedAdapter}. A host uses it to decide
+ * if an adapter needs a key first.
+ */
+export function isKeyedAdapter<TAdapter>(
+  value: TAdapter | KeyedAdapter<TAdapter>,
+): value is KeyedAdapter<TAdapter> {
+  return typeof value === 'object' && value !== null && KEYED_ADAPTER in value
+}
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index 0cc1e6b2be..eac7cd1387 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -99,6 +99,12 @@ export type {
   SubagentBinding,
   SubagentForward,
 } from './activities/chat/agents/bound'
+export {
+  keyedAdapter,
+  isKeyedAdapter,
+  type KeyedAdapter,
+  type ProviderKeys,
+} from './byok/keyed'
 export {
   SubagentBudget,
   type SubagentLimits,
diff --git a/packages/ai/tests/provider-keys.test.ts b/packages/ai/tests/provider-keys.test.ts
new file mode 100644
index 0000000000..d45b83299c
--- /dev/null
+++ b/packages/ai/tests/provider-keys.test.ts
@@ -0,0 +1,177 @@
+import { afterEach, describe, expect, expectTypeOf, it, vi } from 'vitest'
+import { defineAgent } from '../src/activities/chat/agents/define-agent'
+import { spawnAgentStream } from '../src/activities/chat/agents/spawn'
+import { defineByokProvider, isKeyedAdapter, keyedAdapter } from '../src/byok'
+import { collectChunks, createMockAdapter } from './test-utils'
+import type { AnyTextAdapter } from '../src/activities/chat/adapter'
+import type { SubagentBinding } from '../src/activities/chat/agents/bound'
+import type { DefinedAgent } from '../src/activities/chat/agents/define-agent'
+import type { KeyedAdapter, ProviderKeys } from '../src/byok'
+
+const envName = 'TANSTACK_AI_PROVIDER_KEYS_TEST'
+const acme = defineByokProvider({ id: 'acme', label: 'Acme', env: envName })
+
+/** A made-up adapter that keeps the key it was built with. */
+const acmeImage = keyedAdapter(acme, (key) => ({ kind: 'image' as const, key }))
+
+const input = {
+  input: undefined,
+  messages: [],
+  threadId: 'thread-1',
+  runId: 'run-1',
+  parentRunId: 'parent-1',
+  subagentRunId: 'child-1',
+}
+
+/** Provider keys a host would pass: every provider gets `key`. */
+function hostKeys(key: string): ProviderKeys {
+  return {
+    get: async () => key,
+    require: async () => key,
+    adapter: async (adapter) =>
+      isKeyedAdapter(adapter) ? adapter.create(key) : adapter,
+  }
+}
+
+/** An agent that records the `ctx.keys` its run gets. */
+function probe() {
+  const seen: Array<ProviderKeys> = []
+  const agent = defineAgent({
+    name: 'probe',
+    description: 'Records ctx.keys',
+    run: (ctx) => {
+      seen.push(ctx.keys)
+      return Promise.resolve('ok')
+    },
+  })
+  return { agent, seen }
+}
+
+/** Run `agent` the way a host does, outside a parent chat turn. */
+function run(agent: DefinedAgent, binding?: SubagentBinding) {
+  return collectChunks(
+    spawnAgentStream(agent, input, undefined, undefined, binding),
+  )
+}
+
+/** The `ctx.keys` of one probe run. */
+async function runKeys(binding?: SubagentBinding) {
+  const { agent, seen } = probe()
+  await run(agent, binding)
+  const keys = seen[0]
+  if (!keys) throw new Error('the probe did not run')
+  return keys
+}
+
+/**
+ * The `ctx.keys` of a probe that a parent agent starts through its own
+ * `ctx.chat({ subagents })`. `own` is the binding that nested chat sets.
+ */
+async function nestedKeys(host: SubagentBinding, own?: SubagentBinding) {
+  const { agent: child, seen } = probe()
+  const { adapter } = createMockAdapter({ iterations: [] })
+  const lead = defineAgent({
+    name: 'lead',
+    description: 'Starts the probe',
+    run: (ctx) =>
+      ctx.chat({
+        adapter,
+        subagents: {
+          agents: [child],
+          router: () => 'probe',
+          ...(own ? { binding: own } : {}),
+        },
+      }),
+  })
+  await run(lead, host)
+  return seen[0]
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs()
+})
+
+describe('keyedAdapter', () => {
+  it('marks the value so a host can tell it from a plain adapter', () => {
+    const { adapter } = createMockAdapter({})
+    expect(isKeyedAdapter(acmeImage)).toBe(true)
+    expect(acmeImage.provider).toBe(acme)
+    expect(isKeyedAdapter(adapter)).toBe(false)
+    expect(isKeyedAdapter(null)).toBe(false)
+  })
+
+  it('throws on an invalid provider id', () => {
+    expect(() => keyedAdapter('Acme', (key) => key)).toThrow(
+      'Invalid BYOK provider id: Acme',
+    )
+  })
+})
+
+describe('ctx.keys', () => {
+  it('is the provider keys of the binding', async () => {
+    const keys = hostKeys('sk-host')
+    expect(await runKeys({ keys })).toBe(keys)
+  })
+
+  it('reads the provider env var when the host sets no keys', async () => {
+    vi.stubEnv(envName, 'sk-env')
+    const keys = await runKeys()
+    expect(await keys.get(acme)).toBe('sk-env')
+    expect(await keys.require(acme)).toBe('sk-env')
+    // A bare provider id has no env names.
+    expect(await keys.get('acme')).toBeNull()
+  })
+
+  it('throws an error that names the env var when the key is missing', async () => {
+    const keys = await runKeys()
+    expect(await keys.get(acme)).toBeNull()
+    await expect(keys.require(acme)).rejects.toThrow(
+      `Missing Acme API key. Set ${envName}.`,
+    )
+    await expect(keys.require('acme')).rejects.toThrow('Missing acme API key.')
+  })
+
+  it('returns no key where process is missing', async () => {
+    const keys = await runKeys()
+    vi.stubGlobal('process', undefined)
+    // `get` reads the env before its first await, so the stub is gone
+    // before vitest needs `process` again.
+    const pending = keys.get(acme)
+    vi.unstubAllGlobals()
+    expect(await pending).toBeNull()
+  })
+
+  it('builds a keyed adapter with the key and returns a plain adapter unchanged', async () => {
+    vi.stubEnv(envName, 'sk-env')
+    const keys = await runKeys()
+    const { adapter: text } = createMockAdapter({})
+    const choice: AnyTextAdapter | KeyedAdapter<AnyTextAdapter> = keyedAdapter(
+      acme,
+      () => text,
+    )
+
+    expect(await keys.adapter(acmeImage)).toEqual({
+      kind: 'image',
+      key: 'sk-env',
+    })
+    expect(await keys.adapter(text)).toBe(text)
+    expect(await keys.adapter(choice)).toBe(text)
+    expectTypeOf(keys.adapter(acmeImage)).resolves.toEqualTypeOf<{
+      kind: 'image'
+      key: string
+    }>()
+    expectTypeOf(keys.adapter(choice)).resolves.toEqualTypeOf<AnyTextAdapter>()
+  })
+
+  it('gives a nested child the keys of the parent binding', async () => {
+    const keys = hostKeys('sk-host')
+    expect(await nestedKeys({ keys })).toBe(keys)
+  })
+
+  it('lets a nested chat pass its own keys', async () => {
+    const own = hostKeys('sk-own')
+    expect(await nestedKeys({ keys: hostKeys('sk-host') }, { keys: own })).toBe(
+      own,
+    )
+  })
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6399e33f53..f201b46dc7 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -218,6 +218,9 @@ importers:
       '@tanstack/ai-openai':
         specifier: workspace:*
         version: link:../../packages/ai-openai
+      '@tanstack/ai-openrouter':
+        specifier: workspace:*
+        version: link:../../packages/ai-openrouter
       '@tanstack/ai-persistence':
         specifier: workspace:*
         version: link:../../packages/ai-persistence

From 4b61d2bf557643bf583706a912a98b0fd9e22fcd Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 09:21:48 +0200
Subject: [PATCH 069/286] feat(examples/harness-cli): command history, /
 suggestions, pickers, and a usage footer

- The up and down arrows go through the lines you sent. They are kept in
  ~/.tanstack-harness-example/history.json. Keys are never kept.
- Typing / lists the commands. The arrows move, Tab fills, Enter runs.
- /connect, /disconnect, /model, and /mic open a picker. /connect puts
  OpenRouter first, the provider with a browser sign-in.
- The cursor sits before the placeholder, and the arrows move it.
- The screen clears at startup. Settled messages print once (Ink Static).
- A footer shows the model, the context against its window, the tokens in
  and out, the model calls, and the features that are on.
- providerKeys: a provider can set keyUrl. /connect opens that page in the
  browser before it asks for the key.
- usage(): the state has contextTokens, the prompt tokens of the last lead
  model call.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/harness-provider-keys.md           |    4 +-
 docs/harness/coding-agent.md                  |    2 +-
 docs/harness/provider-keys.md                 |    5 +-
 examples/harness-cli/README.md                |   24 +-
 examples/harness-cli/src/harness.ts           |   44 +-
 examples/harness-cli/src/screen/editor.ts     |  131 +++
 examples/harness-cli/src/screen/footer.tsx    |   77 ++
 examples/harness-cli/src/screen/keys.ts       |   79 ++
 examples/harness-cli/src/screen/media.ts      |  125 ++
 examples/harness-cli/src/screen/menu.tsx      |   64 ++
 examples/harness-cli/src/screen/parts.tsx     |  273 +++++
 examples/harness-cli/src/screen/status.tsx    |   88 ++
 examples/harness-cli/src/screen/theme.ts      |   18 +
 examples/harness-cli/src/tui.tsx              | 1005 ++++++-----------
 .../src/first-party/provider-keys.ts          |   31 +-
 .../src/first-party/session-tools.ts          |   45 +-
 .../ai-harness/tests/agent-middleware.test.ts |    4 +
 .../ai-harness/tests/provider-keys.test.ts    |   26 +
 18 files changed, 1361 insertions(+), 684 deletions(-)
 create mode 100644 examples/harness-cli/src/screen/editor.ts
 create mode 100644 examples/harness-cli/src/screen/footer.tsx
 create mode 100644 examples/harness-cli/src/screen/keys.ts
 create mode 100644 examples/harness-cli/src/screen/media.ts
 create mode 100644 examples/harness-cli/src/screen/menu.tsx
 create mode 100644 examples/harness-cli/src/screen/parts.tsx
 create mode 100644 examples/harness-cli/src/screen/status.tsx
 create mode 100644 examples/harness-cli/src/screen/theme.ts

diff --git a/.changeset/harness-provider-keys.md b/.changeset/harness-provider-keys.md
index 3c8dd3962f..f95bdc073c 100644
--- a/.changeset/harness-provider-keys.md
+++ b/.changeset/harness-provider-keys.md
@@ -3,8 +3,10 @@
 '@tanstack/ai-harness-cli': patch
 ---
 
-Users of a shipped harness can connect their own model provider in the app, with no `.env` file. The new `providerKeys({ providers })` plugin in `@tanstack/ai-harness/plugins` adds `/connect <id>`, `/disconnect <id>`, and `/keys`. `/connect` runs the provider's `signIn` when it has one, or else asks the user to paste the key. The key is saved in the credential store of the user. `/keys` and the plugin state show where each key comes from: a saved key (the last 4 characters only), the env var, or no key.
+Users of a shipped harness can connect their own model provider in the app, with no `.env` file. The new `providerKeys({ providers })` plugin in `@tanstack/ai-harness/plugins` adds `/connect <id>`, `/disconnect <id>`, and `/keys`. `/connect` runs the provider's `signIn` when it has one, or else asks the user to paste the key. A provider can set `keyUrl`, the page where the user makes a key: `/connect` opens it in the browser before it asks. The key is saved in the credential store of the user. `/keys` and the plugin state show where each key comes from: a saved key (the last 4 characters only), the env var, or no key.
 
 `defineHarness({ adapter })`, the `modelPicker` choices, `compact({ adapter })`, and `goal({ judge })` now accept a `keyedAdapter(...)`. The session builds it with the user's key just before each call. The saved key comes first, then the provider's env var. When there is no key, the turn stops with `harness.auth_required`, so the user sees `/connect <id>`. Agents get the same keys as `ctx.keys`, and plugins get them as `ctx.keys` on their setup context.
 
+The `usage()` plugin state has `contextTokens`: the prompt tokens of the last lead model call, so a UI can show how full the context is.
+
 A `Question` can set `secret: true`. The view gives it as `ViewQuestion.secret`, and the session does not keep a secret answer in the inbox. In a terminal, the CLI line mode hides what the user types for a secret question, and it never prints the answer.
diff --git a/docs/harness/coding-agent.md b/docs/harness/coding-agent.md
index d1dfe8e355..134613bfce 100644
--- a/docs/harness/coding-agent.md
+++ b/docs/harness/coding-agent.md
@@ -68,7 +68,7 @@ Run the file with `npx tsx coder.ts`. Ask for a change. The agent reads files fr
 | `projectInstructions({ root })` | Adds `AGENTS.md` and `CLAUDE.md` to the system prompt. |
 | `fileCommands({ dir })` | Each `.md` file becomes a slash command. `$ARGUMENTS` is replaced by what you type after it. |
 | `compact({ adapter })` | `/compact` replaces a long conversation with a summary. |
-| `usage()` | `/usage` shows the tokens of the session: the lead turn and every agent. |
+| `usage()` | `/usage` shows the tokens of the session: the lead turn and every agent. Its state also has `contextTokens`, the prompt size of the last lead call, for a context meter. |
 | `goal({ judge })` | `/goal <text>` keeps the agent working until a judge model says that the goal is met. See [Work until a goal is met](./goal). |
 
 ## Add your own rules
diff --git a/docs/harness/provider-keys.md b/docs/harness/provider-keys.md
index 65d140344d..22db25c392 100644
--- a/docs/harness/provider-keys.md
+++ b/docs/harness/provider-keys.md
@@ -55,7 +55,7 @@ export const assistant = defineHarness({
   plugins: () => [
     providerKeys({
       providers: [
-        openaiByok,
+        { ...openaiByok, keyUrl: 'https://platform.openai.com/api-keys' },
         anthropicByok,
         grokByok,
         falByok,
@@ -70,13 +70,14 @@ export const assistant = defineHarness({
 - For each provider, `providerKeys` adds `/connect <id>` and `/disconnect <id>`. It also adds `/keys`.
 - `modelPicker`, `compact`, and `goal` also take keyed adapters. After `/model claude`, the next turn uses the Anthropic key of the user.
 - `signIn` is optional. OpenRouter has one. See [Sign in with OpenRouter](#sign-in-with-openrouter).
+- `keyUrl` is optional. It is the page where the user makes a key. `/connect` opens it in the browser, then asks for the key.
 
 ## 3. Connect a provider
 
 This is what your user does in the CLI:
 
 1. Run `/connect openai`.
-2. The harness asks `Paste your OpenAI API key`. In a terminal, the CLI hides what you type.
+2. The page to make a key opens in the browser (from `keyUrl`). The harness asks you to paste the key. In a terminal, the CLI hides what you type.
 3. Paste the key and press Enter.
 4. The CLI prints `Connected to OpenAI (key ...abcd).`
 
diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index 08551360e0..1f22446fe0 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -9,20 +9,21 @@ From the repo root:
 1. `pnpm install`
 2. `pnpm build:all` (the example uses the local packages)
 3. `pnpm --filter harness-cli-example start`
-4. Type `/connect openai` and paste your OpenAI key. Or type `/connect openrouter` to sign in with the browser.
+4. Type `/connect` and pick OpenRouter. It signs you in with the browser, with no key to paste.
+5. Type `/model` and pick `openrouter-gpt`.
 
-Now send a message. After an OpenRouter sign-in, run `/model openrouter-gpt` first.
+Now send a message.
 
 ## Connect your models
 
-You do not need a `.env` file. Connect each provider inside the app:
+You do not need a `.env` file. Type `/connect` and pick a provider from the list:
 
-- `/connect openai`: paste your key. The input shows dots, not the key.
-- `/connect openrouter`: sign in with the browser. OpenRouter gives the app a key.
-- `/keys`: show each provider and where its key comes from (saved, an env var, or missing).
-- `/disconnect openai`: delete the saved key.
+- OpenRouter signs you in with the browser. OpenRouter gives the app a key.
+- OpenAI, Anthropic, xAI, and fal have no browser sign-in for other apps. The page to make a key opens in the browser. Paste the key: the input shows dots, not the key.
+- `/connect openai` skips the list. `/keys` shows where each key comes from (saved, an env var, or missing).
+- `/disconnect` removes a saved key.
 
-The app saves the key in `~/.tanstack-harness-example/credentials.json`. It shows only the last 4 characters of a key. The header shows which providers have a key, and it changes when you connect one.
+The app saves the key in `~/.tanstack-harness-example/credentials.json`. It shows only the last 4 characters of a key. The footer shows which features are on, and it changes when you connect a provider.
 
 | Provider id  | Adds                                                                         |
 | ------------ | ---------------------------------------------------------------------------- |
@@ -95,14 +96,17 @@ When `claude` and `codex` are on the PATH, the agent can call them. They work in
 
 ## Everything else it shows
 
-- `/model` lists the models, and `/model claude` switches at the next turn. The header shows the current one.
+- `/model` opens a list of the models with their context size. `/model claude` switches at once. The change applies at the next turn.
+- The footer shows the model, how full its context is, the tokens in and out, and the model calls.
 - `create hello.txt with a short poem`: the agent asks before `write_file`. Type `y`.
 - `/mode plan` makes it read-only. `/todos`, `/usage`, `/compact`.
 - `/goal create a file hello.txt that says hi`: the agent keeps working until the model says the goal is met.
 - Press Esc to stop a long answer. Type while it works to steer it.
+- Type `/` for a list of the commands. The arrows move in it, Tab fills the command, and Enter runs it.
+- The up and down arrows go through the lines you sent, also after a restart. They are kept in `~/.tanstack-harness-example/history.json`. Keys are never kept.
 - `/help` lists every command.
 
-The screen is `src/tui.tsx`, plain example code on `createSessionView`. `src/voice.ts` records and transcribes, and `src/media.ts` has the media agents. Copy them and change them.
+The screen is `src/tui.tsx` and its parts in `src/screen/`, plain example code on `createSessionView`. `src/voice.ts` records and transcribes, and `src/media.ts` has the media agents. Copy them and change them.
 
 ## Other modes
 
diff --git a/examples/harness-cli/src/harness.ts b/examples/harness-cli/src/harness.ts
index d4b200d23c..b6733b6a82 100644
--- a/examples/harness-cli/src/harness.ts
+++ b/examples/harness-cli/src/harness.ts
@@ -97,7 +97,7 @@ function demoModel(): AnyTextAdapter {
         yield {
           type: EventType.TEXT_MESSAGE_CONTENT,
           messageId,
-          delta: `(demo model) You said: "${said}". Run /connect openai (/keys lists the others), then /model gpt, to talk to a real model.`,
+          delta: `(demo model) You said: "${said}". Type /connect to connect a provider, then /model to pick a real model.`,
           timestamp: now,
         }
         yield { type: EventType.TEXT_MESSAGE_END, messageId, timestamp: now }
@@ -106,6 +106,15 @@ function demoModel(): AnyTextAdapter {
           runId: 'demo',
           threadId: 'demo',
           timestamp: now,
+          // ponytail: about 4 characters a token, so the footer counts in demo mode too.
+          usage: {
+            promptTokens: Math.ceil(
+              JSON.stringify(options.messages).length / 4,
+            ),
+            completionTokens: 30,
+            totalTokens:
+              Math.ceil(JSON.stringify(options.messages).length / 4) + 30,
+          },
           metadata: { tanstack: { finishReason: 'stop' } },
         }
       })(),
@@ -154,14 +163,33 @@ const main: KeyedAdapter<AnyTextAdapter> = envModel?.[1] ?? models.gpt
 // With no env key at all, `/model demo` answers without a key.
 const choices = { ...models, ...(envModel ? {} : { demo: demoModel() }) }
 
-// `/connect openai` asks for the key (the screen hides it as you type), and
-// `/connect openrouter` signs in with the browser. `/keys` lists them all.
-const keyProviders = [
-  openaiByok,
-  anthropicByok,
-  grokByok,
-  falByok,
+/**
+ * What the screen shows for each model: the provider that must be connected,
+ * and the size of its context window (from each provider's model-meta).
+ */
+export const modelInfo: Record<
+  string,
+  { provider: string; contextWindow: number }
+> = {
+  gpt: { provider: 'openai', contextWindow: 1_050_000 },
+  'gpt-fast': { provider: 'openai', contextWindow: 1_050_000 },
+  claude: { provider: 'anthropic', contextWindow: 1_000_000 },
+  'claude-fast': { provider: 'anthropic', contextWindow: 1_000_000 },
+  grok: { provider: 'grok', contextWindow: 500_000 },
+  'openrouter-gpt': { provider: 'openrouter', contextWindow: 1_050_000 },
+  'openrouter-claude': { provider: 'openrouter', contextWindow: 1_000_000 },
+}
+
+// `/connect openrouter` signs in with the browser: no key to paste, and one
+// sign-in covers GPT, Claude, Gemini, and more. OpenAI, Anthropic, xAI, and
+// fal have no browser sign-in for other apps, so `/connect openai` opens the
+// page to make a key, then asks for it (the screen hides it as you type).
+export const keyProviders = [
   { ...openrouterByok, signIn: openrouterSignIn() },
+  { ...openaiByok, keyUrl: 'https://platform.openai.com/api-keys' },
+  { ...anthropicByok, keyUrl: 'https://console.anthropic.com/settings/keys' },
+  { ...grokByok, keyUrl: 'https://console.x.ai' },
+  { ...falByok, keyUrl: 'https://fal.ai/dashboard/keys' },
 ]
 
 /** Is `command` on the PATH? Checks the Windows extensions too. */
diff --git a/examples/harness-cli/src/screen/editor.ts b/examples/harness-cli/src/screen/editor.ts
new file mode 100644
index 0000000000..d829d6dcff
--- /dev/null
+++ b/examples/harness-cli/src/screen/editor.ts
@@ -0,0 +1,131 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { useReducer, useRef } from 'react'
+
+// The lines you sent, for the up and down arrows, kept next to the sign-ins.
+const historyFile = join(homedir(), '.tanstack-harness-example', 'history.json')
+const HISTORY_SIZE = 200
+
+function loadHistory() {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(historyFile, 'utf8'))
+    return Array.isArray(parsed)
+      ? parsed.filter((item) => typeof item === 'string')
+      : []
+  } catch {
+    return []
+  }
+}
+
+function saveHistory(lines: ReadonlyArray<string>) {
+  try {
+    mkdirSync(dirname(historyFile), { recursive: true })
+    writeFileSync(historyFile, JSON.stringify(lines.slice(-HISTORY_SIZE)))
+  } catch {
+    // ponytail: history is a convenience. A failed write loses it, no more.
+  }
+}
+
+/** The input line. `hidden`: it holds a secret (a key), shown as dots. */
+export interface Line {
+  text: string
+  cursor: number
+  hidden: boolean
+}
+
+const empty: Line = { text: '', cursor: 0, hidden: false }
+
+/**
+ * The input line of the screen: typing at the cursor, the arrow keys, and
+ * the history of sent lines. The line is in a ref, so a key that comes
+ * before React renders still sees the keys before it.
+ */
+export function useLineEditor() {
+  const current = useRef<Line>(empty)
+  const [, render] = useReducer((count: number) => count + 1, 0)
+  const history = useRef<Array<string>>(loadHistory())
+  // While you go through the history: where you are, and the line you had.
+  const browsing = useRef<{ index: number; draft: string } | undefined>(
+    undefined,
+  )
+  const show = (line: Line) => {
+    current.current = line
+    render()
+  }
+  const edit = (line: Line) => {
+    browsing.current = undefined
+    show(line)
+  }
+  const showText = (text: string) =>
+    show({ text, cursor: text.length, hidden: false })
+
+  return {
+    get line() {
+      return current.current
+    },
+    /** The line came from the history (the arrows), not from typing. */
+    get browsing() {
+      return browsing.current !== undefined
+    },
+    /** Type or paste at the cursor. A hidden line stays hidden until it is empty. */
+    insert: (text: string, hidden = false) => {
+      const line = current.current
+      edit({
+        text:
+          line.text.slice(0, line.cursor) + text + line.text.slice(line.cursor),
+        cursor: line.cursor + text.length,
+        hidden: hidden || (line.hidden && line.text !== ''),
+      })
+    },
+    /** Delete the character before the cursor. */
+    backspace: () => {
+      const line = current.current
+      if (line.cursor === 0) return
+      edit({
+        ...line,
+        text:
+          line.text.slice(0, line.cursor - 1) + line.text.slice(line.cursor),
+        cursor: line.cursor - 1,
+      })
+    },
+    /** Move the cursor by `by` characters, or to the start or the end. */
+    move: (by: number | 'start' | 'end') => {
+      const line = current.current
+      const target =
+        by === 'start' ? 0 : by === 'end' ? line.text.length : line.cursor + by
+      show({ ...line, cursor: Math.max(0, Math.min(line.text.length, target)) })
+    },
+    set: (text: string) => edit({ text, cursor: text.length, hidden: false }),
+    clear: () => edit(empty),
+    /** Keep a sent line for the up arrow. */
+    remember: (text: string) => {
+      const trimmed = text.trim()
+      if (trimmed === '' || history.current.at(-1) === trimmed) return
+      history.current.push(trimmed)
+      saveHistory(history.current)
+    },
+    /** The up arrow: the sent line before the one shown. */
+    older: () => {
+      const lines = history.current
+      if (lines.length === 0) return
+      const at = browsing.current
+      const index = at ? Math.max(0, at.index - 1) : lines.length - 1
+      browsing.current = { index, draft: at?.draft ?? current.current.text }
+      showText(lines[index] ?? '')
+    },
+    /** The down arrow: the next sent line, then the line you had typed. */
+    newer: () => {
+      const at = browsing.current
+      if (!at) return
+      if (at.index >= history.current.length - 1) {
+        browsing.current = undefined
+        showText(at.draft)
+        return
+      }
+      const index = at.index + 1
+      browsing.current = { ...at, index }
+      showText(history.current[index] ?? '')
+    },
+  }
+}
diff --git a/examples/harness-cli/src/screen/footer.tsx b/examples/harness-cli/src/screen/footer.tsx
new file mode 100644
index 0000000000..f4448517a7
--- /dev/null
+++ b/examples/harness-cli/src/screen/footer.tsx
@@ -0,0 +1,77 @@
+import { Box, Spacer, Text } from 'ink'
+import { useSelector } from '@tanstack/react-store'
+import { features, modelInfo } from '../harness'
+import { PROVIDER_KEYS, USAGE, isOn, providerKeysIn, usageIn } from './keys'
+import { ACCENT, compact } from './theme'
+import type { SessionView } from '@tanstack/ai-harness/view'
+
+const BAR = 10
+
+/**
+ * The status bar at the bottom: the model, how much of its context the
+ * conversation fills, the tokens and model calls so far, and which features
+ * are on. It follows the session live, so a `/connect` turns features on.
+ */
+export function Footer({ view }: { view: SessionView }) {
+  const model = useSelector(view.store, (state) =>
+    String(state.config.find((entry) => entry.key === 'model')?.value ?? '?'),
+  )
+  // The plugin states themselves, so the bar renders only when they change.
+  const usageState = useSelector(view.store, (state) => state.plugins[USAGE])
+  const keysState = useSelector(
+    view.store,
+    (state) => state.plugins[PROVIDER_KEYS],
+  )
+  const usage = usageIn(usageState)
+  const keys = providerKeysIn(keysState)
+  const info = modelInfo[model]
+  const window = info?.contextWindow
+  const share = window ? Math.min(1, usage.contextTokens / window) : 0
+  const filled = Math.round(share * BAR)
+  const barColor = share > 0.8 ? 'red' : share > 0.5 ? 'yellow' : 'green'
+  const needsKey =
+    info !== undefined &&
+    keys.find((key) => key.id === info.provider)?.state === 'missing'
+  return (
+    <Box flexDirection="column">
+      <Box>
+        <Text color={needsKey ? 'red' : ACCENT} bold>{`◆ ${model}`}</Text>
+        {needsKey ? (
+          <Text color="red">{`  (run /connect ${info.provider})`}</Text>
+        ) : null}
+        <Text dimColor>{'   context '}</Text>
+        <Text>
+          {compact(usage.contextTokens)}
+          {window ? `/${compact(window)}` : ''}
+        </Text>
+        {window ? (
+          <>
+            <Text> </Text>
+            <Text color={barColor}>{'▰'.repeat(filled)}</Text>
+            <Text dimColor>{'▱'.repeat(BAR - filled)}</Text>
+            <Text dimColor>{` ${Math.round(share * 100)}%`}</Text>
+          </>
+        ) : null}
+        <Text dimColor>{'   tokens in '}</Text>
+        <Text>{compact(usage.promptTokens)}</Text>
+        <Text dimColor>{' out '}</Text>
+        <Text>{compact(usage.completionTokens)}</Text>
+        <Text dimColor>{`   ${usage.turns} model calls`}</Text>
+      </Box>
+      <Box flexWrap="wrap">
+        {features.map((feature) => {
+          const on = isOn(feature, keys)
+          return (
+            <Text key={feature.name} color={on ? 'green' : 'gray'}>
+              {`${on ? '●' : '○'} ${feature.name}  `}
+            </Text>
+          )
+        })}
+        <Spacer />
+        <Text dimColor>
+          {'Ctrl+R talk   / commands   ↑↓ history   Esc cancel'}
+        </Text>
+      </Box>
+    </Box>
+  )
+}
diff --git a/examples/harness-cli/src/screen/keys.ts b/examples/harness-cli/src/screen/keys.ts
new file mode 100644
index 0000000000..ccd6c1ae9b
--- /dev/null
+++ b/examples/harness-cli/src/screen/keys.ts
@@ -0,0 +1,79 @@
+import type { features } from '../harness'
+
+// The names of the `providerKeys()` and `usage()` plugins: their state is in
+// the view's `state.plugins`.
+export const PROVIDER_KEYS = 'tanstack/provider-keys'
+export const USAGE = 'tanstack/usage'
+
+/** A model provider of `providerKeys()`, and where its key comes from. */
+export interface ProviderKey {
+  id: string
+  label: string
+  state: 'connected' | 'env' | 'missing'
+}
+
+function isProviderKey(value: unknown): value is ProviderKey {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'id' in value &&
+    typeof value.id === 'string' &&
+    'label' in value &&
+    typeof value.label === 'string' &&
+    'state' in value &&
+    (value.state === 'connected' ||
+      value.state === 'env' ||
+      value.state === 'missing')
+  )
+}
+
+/**
+ * The providers in `saved`, the state of the provider-keys plugin.
+ * `/connect` and `/disconnect` update it, so the screen shows the keys live.
+ * Empty before the plugin reports.
+ */
+export function providerKeysIn(saved: unknown) {
+  const isState =
+    typeof saved === 'object' && saved !== null && 'providers' in saved
+  if (!isState) return []
+  const { providers } = saved
+  return Array.isArray(providers) ? providers.filter(isProviderKey) : []
+}
+
+/**
+ * Is `feature` on? A feature that needs a key follows the saved keys: any
+ * one of its providers with a key turns it on. The rest stay as at startup.
+ */
+export function isOn(
+  feature: (typeof features)[number],
+  keys: ReadonlyArray<ProviderKey>,
+) {
+  const followsKeys = feature.providers.length > 0 && keys.length > 0
+  if (!followsKeys) return feature.on
+  return keys.some(
+    (key) => feature.providers.includes(key.id) && key.state !== 'missing',
+  )
+}
+
+/** The totals of the usage plugin. */
+export interface Usage {
+  turns: number
+  promptTokens: number
+  completionTokens: number
+  contextTokens: number
+}
+
+/** The usage plugin state in `saved`, with 0 for anything it has not counted. */
+export function usageIn(saved: unknown): Usage {
+  const read = (key: string) => {
+    if (typeof saved !== 'object' || saved === null || !(key in saved)) return 0
+    const value: unknown = Reflect.get(saved, key)
+    return typeof value === 'number' ? value : 0
+  }
+  return {
+    turns: read('turns'),
+    promptTokens: read('promptTokens'),
+    completionTokens: read('completionTokens'),
+    contextTokens: read('contextTokens'),
+  }
+}
diff --git a/examples/harness-cli/src/screen/media.ts b/examples/harness-cli/src/screen/media.ts
new file mode 100644
index 0000000000..6222ed8a3c
--- /dev/null
+++ b/examples/harness-cli/src/screen/media.ts
@@ -0,0 +1,125 @@
+import { spawn } from 'node:child_process'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { basename, join, resolve } from 'node:path'
+import { useEffect, useState } from 'react'
+import { assistant } from '../harness'
+import type {
+  MediaPart,
+  SessionView,
+  ViewMessage,
+  ViewPart,
+} from '@tanstack/ai-harness/view'
+
+// ponytail: the CLI's default media folder, `./<harness-name>-media`. A custom
+// ui gets no `--media-dir`, and the CLI does not export `defaultMediaDir`, so
+// this copies its rule. The media id in front of the name keeps names unique.
+export const mediaDir = `${assistant.name.replace(/[^\w.-]+/g, '-').replace(/^[-.]+|-+$/g, '')}-media`
+
+/** A media file the screen saved. `number` is what `/open` and `/play` take. */
+export interface Saved {
+  id: string
+  number: number
+  kind: string
+  name: string
+  path?: string
+  error?: string
+}
+
+/** Write the bytes of a media file into `mediaDir`, and return the path. */
+async function saveMedia(part: MediaPart) {
+  await mkdir(mediaDir, { recursive: true })
+  const path = join(mediaDir, `${part.id}-${basename(part.name)}`)
+  await writeFile(path, await part.load())
+  return path
+}
+
+/** Add the media parts of `parts` to `into`, also the ones of child agents. */
+function collectMedia(parts: ReadonlyArray<ViewPart>, into: Array<MediaPart>) {
+  for (const part of parts) {
+    if (part.type === 'media') into.push(part)
+    if (part.type === 'agent') collectMedia(part.parts, into)
+  }
+}
+
+/** The media files that the agents made, from the assistant messages. */
+function generatedMedia(messages: ReadonlyArray<ViewMessage>) {
+  const media: Array<MediaPart> = []
+  for (const message of messages) {
+    if (message.role === 'assistant') collectMedia(message.parts, media)
+  }
+  return media
+}
+
+/**
+ * Save each new media file once, and number it. Files in the history when
+ * the screen opens are not saved again. `saving(id)`: is that file new, and
+ * neither saved nor failed yet?
+ */
+export function useSavedMedia(view: SessionView, messages: Array<ViewMessage>) {
+  const [saved, setSaved] = useState<ReadonlyArray<Saved>>([])
+  const [seen] = useState(
+    () =>
+      new Set(generatedMedia(view.store.get().messages).map((part) => part.id)),
+  )
+  useEffect(() => {
+    for (const part of generatedMedia(messages)) {
+      if (seen.has(part.id)) continue
+      seen.add(part.id)
+      const number = seen.size
+      const update = (change: Partial<Saved>) =>
+        setSaved((current) =>
+          current.map((item) =>
+            item.id === part.id ? { ...item, ...change } : item,
+          ),
+        )
+      setSaved((current) => [
+        ...current,
+        { id: part.id, number, kind: part.kind, name: part.name },
+      ])
+      saveMedia(part).then(
+        (path) => update({ path }),
+        (error: unknown) =>
+          update({
+            error: error instanceof Error ? error.message : String(error),
+          }),
+      )
+    }
+  }, [messages, seen])
+  const saving = (id: string) => {
+    if (!seen.has(id)) return true
+    const item = saved.find((entry) => entry.id === id)
+    return item !== undefined && !item.path && !item.error
+  }
+  return { saved, saving }
+}
+
+/** Start a program without a shell. The screen still shows the path on error. */
+function launch(command: string, args: Array<string>) {
+  const child = spawn(command, args, { stdio: 'ignore', detached: true })
+  child.on('error', () => {})
+  child.unref()
+}
+
+/** Open a link or a file with the default app. No shell is involved. */
+export function openExternal(target: string) {
+  if (process.platform === 'win32') {
+    // Not `cmd /c start`: cmd would read `&` in a URL as a command separator.
+    if (/^https?:\/\//.test(target))
+      launch('rundll32', ['url.dll,FileProtocolHandler', target])
+    else launch('explorer', [resolve(target)])
+    return
+  }
+  launch(process.platform === 'darwin' ? 'open' : 'xdg-open', [target])
+}
+
+/** Play audio or video with ffplay, which comes with ffmpeg. */
+export function play(item: Saved & { path: string }) {
+  const window = item.kind === 'video' ? [] : ['-nodisp']
+  launch(process.env.FFPLAY_PATH || 'ffplay', [
+    ...window,
+    '-autoexit',
+    '-loglevel',
+    'quiet',
+    item.path,
+  ])
+}
diff --git a/examples/harness-cli/src/screen/menu.tsx b/examples/harness-cli/src/screen/menu.tsx
new file mode 100644
index 0000000000..de3c2e6bf1
--- /dev/null
+++ b/examples/harness-cli/src/screen/menu.tsx
@@ -0,0 +1,64 @@
+import { Box, Text } from 'ink'
+import { ACCENT } from './theme'
+
+/** One row of the command list or of a picker. */
+export interface MenuItem {
+  id: string
+  label: string
+  detail?: string
+  /** The current choice, for example the model in use. */
+  current?: boolean
+}
+
+const VISIBLE = 8
+
+/**
+ * A list you move through with the arrow keys: the `/` command list, or a
+ * picker such as `/connect` or `/model`. It shows at most 8 rows around the
+ * selected one.
+ */
+export function Menu({
+  title,
+  items,
+  selected,
+  hint,
+}: {
+  title?: string
+  items: ReadonlyArray<MenuItem>
+  selected: number
+  hint: string
+}) {
+  const start = Math.max(
+    0,
+    Math.min(selected - Math.floor(VISIBLE / 2), items.length - VISIBLE),
+  )
+  const shown = items.slice(start, start + VISIBLE)
+  const width = Math.max(...items.map((item) => item.label.length), 8)
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor="gray"
+      paddingX={1}
+    >
+      {title ? <Text bold>{title}</Text> : null}
+      {shown.map((item, index) => {
+        const isSelected = start + index === selected
+        return (
+          <Box key={item.id}>
+            <Text color={isSelected ? ACCENT : undefined} bold={isSelected}>
+              {`${isSelected ? '❯' : ' '} ${item.label.padEnd(width)}`}
+            </Text>
+            <Text color={item.current ? 'green' : 'gray'}>
+              {`  ${item.current ? '● ' : ''}${item.detail ?? ''}`}
+            </Text>
+          </Box>
+        )
+      })}
+      {items.length > VISIBLE ? (
+        <Text dimColor>{`  ${selected + 1} of ${items.length}`}</Text>
+      ) : null}
+      <Text dimColor>{hint}</Text>
+    </Box>
+  )
+}
diff --git a/examples/harness-cli/src/screen/parts.tsx b/examples/harness-cli/src/screen/parts.tsx
new file mode 100644
index 0000000000..fff1b30494
--- /dev/null
+++ b/examples/harness-cli/src/screen/parts.tsx
@@ -0,0 +1,273 @@
+import { basename } from 'node:path'
+import { Box, Spacer, Text, useAnimation } from 'ink'
+import { ACCENT, KIND_COLOR, SPINNER } from './theme'
+import type {
+  AgentPart,
+  MediaPart,
+  ToolCallPart,
+  ViewMessage,
+  ViewPart,
+} from '@tanstack/ai-harness/view'
+import type { Saved } from './media'
+
+export function Spinner({ color = 'yellow' }: { color?: string }) {
+  const { frame } = useAnimation({ interval: 90 })
+  return <Text color={color}>{SPINNER[frame % SPINNER.length]}</Text>
+}
+
+function textOf(parts: ReadonlyArray<ViewPart>) {
+  return parts.map((part) => (part.type === 'text' ? part.text : '')).join('')
+}
+
+/** A short one-line view of tool arguments. */
+function argsPreview(call: ToolCallPart) {
+  const text =
+    typeof call.args === 'object' && call.args !== null
+      ? Object.values(call.args)
+          .filter((value) => typeof value === 'string')
+          .join(', ')
+      : ''
+  const line = text.replace(/\s+/g, ' ').trim()
+  return line.length > 70 ? `${line.slice(0, 70)}...` : line
+}
+
+function ToolLine({
+  call,
+  indent = 2,
+}: {
+  call: ToolCallPart
+  indent?: number
+}) {
+  const icon =
+    call.status === 'running' ? (
+      <Spinner />
+    ) : call.status === 'done' ? (
+      <Text color="green">✓</Text>
+    ) : call.status === 'failed' ? (
+      <Text color="red">✗</Text>
+    ) : (
+      <Text color="magenta">?</Text>
+    )
+  const preview = argsPreview(call)
+  return (
+    <Box marginLeft={indent}>
+      {icon}
+      <Text color="yellow">{` ${call.name}`}</Text>
+      {preview ? <Text dimColor>{`  ${preview}`}</Text> : null}
+      {call.status === 'needs-approval' ? (
+        <Text color="magenta"> waits for your approval</Text>
+      ) : null}
+    </Box>
+  )
+}
+
+function MediaLine({
+  part,
+  saved,
+  indent = 2,
+}: {
+  part: MediaPart
+  saved: ReadonlyArray<Saved>
+  indent?: number
+}) {
+  const item = saved.find((entry) => entry.id === part.id)
+  const color = KIND_COLOR[part.kind] ?? 'white'
+  return (
+    <Box marginLeft={indent}>
+      <Text color={color} bold>
+        {`▣ ${item ? `${item.number} ` : ''}${part.kind}`}
+      </Text>
+      <Text>{`  ${part.name}`}</Text>
+      {item?.path ? <Text dimColor>{`  -> ${item.path}`}</Text> : null}
+      {item?.error ? (
+        <Text color="red">{`  not saved: ${item.error}`}</Text>
+      ) : null}
+      {item && !item.path && !item.error ? (
+        <Text dimColor> saving...</Text>
+      ) : null}
+    </Box>
+  )
+}
+
+/**
+ * A child agent, for example Codex or Claude Code, in its own card: its
+ * status, its last tool calls, its media, and its output. While it runs, the
+ * last 4 lines show. When it ends, the last 15 lines of its answer stay.
+ */
+function Agent({
+  part,
+  saved,
+}: {
+  part: AgentPart
+  saved: ReadonlyArray<Saved>
+}) {
+  const lines = textOf(part.parts)
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim() !== '')
+  const running = part.status === 'running'
+  const output = running ? lines.slice(-4) : lines.slice(-15)
+  const calls = part.parts.flatMap((inner) =>
+    inner.type === 'tool-call' ? [inner] : [],
+  )
+  const media = part.parts.flatMap((inner) =>
+    inner.type === 'media' ? [inner] : [],
+  )
+  const color = part.status === 'failed' ? 'red' : running ? 'yellow' : 'green'
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={color}
+      paddingX={1}
+      marginLeft={2}
+    >
+      <Box>
+        {running ? (
+          <Spinner color={color} />
+        ) : (
+          <Text color={color}>{part.status === 'done' ? '✓' : '✗'}</Text>
+        )}
+        <Text bold>{` ${part.name}`}</Text>
+        <Spacer />
+        <Text color={color}>{part.status}</Text>
+      </Box>
+      {calls.slice(-4).map((call) => (
+        <ToolLine key={call.id} call={call} indent={0} />
+      ))}
+      {media.map((inner) => (
+        <MediaLine key={inner.id} part={inner} saved={saved} indent={0} />
+      ))}
+      {output.map((line, index) => (
+        <Text key={`line-${index}`} dimColor={running}>
+          {line}
+        </Text>
+      ))}
+      {part.error ? <Text color="red">{part.error}</Text> : null}
+    </Box>
+  )
+}
+
+function Part({
+  part,
+  saved,
+}: {
+  part: ViewPart
+  saved: ReadonlyArray<Saved>
+}) {
+  switch (part.type) {
+    case 'text':
+      return (
+        <Box marginLeft={2}>
+          <Text>{part.text}</Text>
+        </Box>
+      )
+    case 'reasoning':
+      return (
+        <Box marginLeft={2}>
+          <Text dimColor italic>
+            {part.text}
+          </Text>
+        </Box>
+      )
+    case 'tool-call':
+      return <ToolLine call={part} />
+    case 'agent':
+      return <Agent part={part} saved={saved} />
+    case 'media':
+      return <MediaLine part={part} saved={saved} />
+  }
+}
+
+export function Message({
+  message,
+  saved,
+}: {
+  message: ViewMessage
+  saved: ReadonlyArray<Saved>
+}) {
+  switch (message.role) {
+    case 'user': {
+      // A voice message names its files as `@"path"`, shown as a file badge.
+      const named: Array<string> = []
+      const text = message.text
+        .replace(/@"([^"]+)"/g, (_match, path: string) => {
+          named.push(basename(path))
+          return ''
+        })
+        .trim()
+      const files = [
+        ...(message.media ?? []).map((part) => `${part.kind} ${part.name}`),
+        ...named,
+      ]
+      return (
+        <Box marginTop={1} flexWrap="wrap">
+          <Text bold>
+            <Text color={ACCENT}>❯ </Text>
+            {text}
+            {files.length > 0 ? ' ' : ''}
+          </Text>
+          {files.map((file) => (
+            <Text key={file} color="black" backgroundColor={ACCENT}>
+              {` ${file} `}
+            </Text>
+          ))}
+        </Box>
+      )
+    }
+    case 'notice': {
+      const isError = message.kind === 'error'
+      return (
+        <Box marginLeft={2}>
+          <Text color={isError ? 'red' : 'gray'}>
+            {`${isError ? '✗' : '·'} ${message.text}`}
+          </Text>
+        </Box>
+      )
+    }
+    case 'assistant':
+      return (
+        <Box flexDirection="column" marginTop={1}>
+          {message.parts.map((part, index) => (
+            <Part key={index} part={part} saved={saved} />
+          ))}
+        </Box>
+      )
+  }
+}
+
+/** Does a part still change: a running tool or agent, or media still saving? */
+function isLivePart(part: ViewPart, saving: (id: string) => boolean): boolean {
+  if (part.type === 'tool-call')
+    return part.status === 'running' || part.status === 'needs-approval'
+  if (part.type === 'agent')
+    return (
+      part.status === 'running' ||
+      part.parts.some((inner) => isLivePart(inner, saving))
+    )
+  return part.type === 'media' && saving(part.id)
+}
+
+/**
+ * How many messages from the start no longer change. The screen prints them
+ * once, above the live area, so a long conversation does not redraw.
+ * `running`: a turn streams now, so the last assistant message can still
+ * grow. The screen never takes back a printed message, so holding the one of
+ * the turn before costs nothing.
+ */
+export function settledCount(
+  messages: ReadonlyArray<ViewMessage>,
+  saving: (id: string) => boolean,
+  running: boolean,
+) {
+  const lastAssistant = messages
+    .map((message) => message.role)
+    .lastIndexOf('assistant')
+  for (const [index, message] of messages.entries()) {
+    if (message.role !== 'assistant') continue
+    const streaming = running && index === lastAssistant
+    if (streaming || message.parts.some((part) => isLivePart(part, saving)))
+      return index
+  }
+  return messages.length
+}
diff --git a/examples/harness-cli/src/screen/status.tsx b/examples/harness-cli/src/screen/status.tsx
new file mode 100644
index 0000000000..a823afe68f
--- /dev/null
+++ b/examples/harness-cli/src/screen/status.tsx
@@ -0,0 +1,88 @@
+import { Box, Text, useAnimation } from 'ink'
+import { useSelector } from '@tanstack/react-store'
+import { selectGoal } from '@tanstack/ai-harness/plugins'
+import { Spinner } from './parts'
+import type { SessionView } from '@tanstack/ai-harness/view'
+import type { Recording } from '../voice'
+
+export type VoiceState = 'idle' | 'starting' | 'recording' | 'transcribing'
+
+/** A live level meter from the microphone loudness (0 to 32768). */
+function LevelMeter({ recording }: { recording: Recording }) {
+  const { time } = useAnimation({ interval: 80 })
+  const level = recording.level()
+  // Map loudness to 0..1 on a log scale: -60 dB is empty, 0 dB is full.
+  const decibels = 20 * Math.log10(Math.max(level, 1) / 32768)
+  const filled = Math.round(Math.min(1, Math.max(0, (decibels + 60) / 60)) * 16)
+  const seconds = Math.floor(time / 1000)
+  const clock = `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`
+  return (
+    <Box>
+      <Text color="red" bold>{`● REC ${clock}  `}</Text>
+      <Text color={filled > 9 ? 'green' : filled > 4 ? 'yellow' : 'gray'}>
+        {'▮'.repeat(filled)}
+      </Text>
+      <Text dimColor>{'▯'.repeat(16 - filled)}</Text>
+      <Text dimColor>{`  ${recording.microphone}`}</Text>
+    </Box>
+  )
+}
+
+/** What waits for the user or runs now: sign-ins, approvals, voice, the turn. */
+export function Status({
+  view,
+  voice,
+  recording,
+}: {
+  view: SessionView
+  voice: VoiceState
+  recording: Recording | undefined
+}) {
+  const status = useSelector(view.store, (state) => state.status)
+  const approvals = useSelector(view.store, (state) => state.approvals)
+  const question = useSelector(view.store, (state) => state.questions.at(0))
+  const signIns = useSelector(view.store, (state) => state.signIns)
+  const goal = useSelector(view.store, selectGoal)
+  return (
+    <Box flexDirection="column" marginTop={1}>
+      {signIns.map((signIn) => (
+        <Text key={signIn.connector} color="magenta">
+          {`◇ Continue in your browser for ${signIn.connector}${signIn.url ? `: ${signIn.url}` : ''}${signIn.userCode ? ` (code ${signIn.userCode})` : ''}`}
+        </Text>
+      ))}
+      {approvals.length > 0 ? (
+        <Text color="magenta" bold>
+          {`◇ Approve ${approvals.map((item) => item.tool).join(', ')}? Type y or n.`}
+        </Text>
+      ) : null}
+      {question ? <Text color="magenta">{`◇ ${question.message}`}</Text> : null}
+      {goal ? (
+        <Text color="green">{`◎ Goal: ${goal.text} (${goal.status}, round ${goal.round})`}</Text>
+      ) : null}
+      {voice === 'recording' && recording ? (
+        <Box flexDirection="column">
+          <LevelMeter recording={recording} />
+          <Text dimColor>
+            Let go of Ctrl+R (or tap it again) to send. Esc drops it.
+          </Text>
+        </Box>
+      ) : voice === 'starting' ? (
+        <Box>
+          <Spinner color="red" />
+          <Text color="red"> opening the microphone...</Text>
+        </Box>
+      ) : voice === 'transcribing' ? (
+        <Box>
+          <Spinner color="cyan" />
+          <Text color="cyan"> listening to your voice message...</Text>
+        </Box>
+      ) : status === 'running' ? (
+        <Box>
+          <Spinner />
+          <Text color="yellow"> working</Text>
+          <Text dimColor> Esc cancels, typing steers</Text>
+        </Box>
+      ) : null}
+    </Box>
+  )
+}
diff --git a/examples/harness-cli/src/screen/theme.ts b/examples/harness-cli/src/screen/theme.ts
new file mode 100644
index 0000000000..62c223a38b
--- /dev/null
+++ b/examples/harness-cli/src/screen/theme.ts
@@ -0,0 +1,18 @@
+// TanStack AI's accent color, the dark-mode step, so it reads on dark terminals.
+export const ACCENT = '#e06e49'
+
+export const KIND_COLOR: Record<string, string> = {
+  image: 'magenta',
+  audio: 'cyan',
+  video: 'blue',
+  document: 'white',
+}
+
+export const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+
+/** 12400 is "12.4k", 1050000 is "1.05M". */
+export function compact(count: number) {
+  if (count >= 1_000_000) return `${Number((count / 1_000_000).toFixed(2))}M`
+  if (count >= 1_000) return `${Number((count / 1_000).toFixed(1))}k`
+  return String(count)
+}
diff --git a/examples/harness-cli/src/tui.tsx b/examples/harness-cli/src/tui.tsx
index aa6c046678..7e645562f4 100644
--- a/examples/harness-cli/src/tui.tsx
+++ b/examples/harness-cli/src/tui.tsx
@@ -1,21 +1,10 @@
-import { spawn } from 'node:child_process'
-import { mkdir, readFile, writeFile } from 'node:fs/promises'
-import { basename, join, resolve } from 'node:path'
+import { readFile } from 'node:fs/promises'
+import { basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { useEffect, useRef, useState } from 'react'
-import {
-  Box,
-  Spacer,
-  Text,
-  render,
-  useAnimation,
-  useApp,
-  useInput,
-  usePaste,
-} from 'ink'
+import { Box, Static, Text, render, useApp, useInput, usePaste } from 'ink'
 import { useSelector } from '@tanstack/react-store'
-import { selectGoal } from '@tanstack/ai-harness/plugins'
-import { assistant, features } from './harness'
+import { assistant, features, keyProviders, modelInfo } from './harness'
 import {
   canTranscribe,
   chooseMicrophone,
@@ -26,422 +15,149 @@ import {
   transcribe,
   withSpokenFiles,
 } from './voice'
+import { useLineEditor } from './screen/editor'
+import { Footer } from './screen/footer'
+import { PROVIDER_KEYS, isOn, providerKeysIn } from './screen/keys'
+import { mediaDir, openExternal, play, useSavedMedia } from './screen/media'
+import { Menu } from './screen/menu'
+import { Message, settledCount } from './screen/parts'
+import { Status } from './screen/status'
+import { ACCENT, compact } from './screen/theme'
 import type { RenderOptions } from 'ink'
 import type { Recording, VoiceClip } from './voice'
+import type { Line } from './screen/editor'
+import type { MenuItem } from './screen/menu'
+import type { VoiceState } from './screen/status'
 import type {
-  AgentPart,
-  MediaPart,
   SessionView,
-  ToolCallPart,
+  SessionViewState,
+  ViewCommand,
   ViewMessage,
-  ViewPart,
 } from '@tanstack/ai-harness/view'
 
-// TanStack AI's accent color, the dark-mode step, so it reads on dark terminals.
-const ACCENT = '#e06e49'
-const KIND_COLOR: Record<string, string> = {
-  image: 'magenta',
-  audio: 'cyan',
-  video: 'blue',
-  document: 'white',
-}
-// The name of the `providerKeys()` plugin: its state is in `state.plugins`.
-const PROVIDER_KEYS = 'tanstack/provider-keys'
-const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
-
-// ponytail: the CLI's default media folder, `./<harness-name>-media`. A custom
-// ui gets no `--media-dir`, and the CLI does not export `defaultMediaDir`, so
-// this copies its rule. The media id in front of the name keeps names unique.
-const mediaDir = `${assistant.name.replace(/[^\w.-]+/g, '-').replace(/^[-.]+|-+$/g, '')}-media`
 const playground = fileURLToPath(new URL('../playground', import.meta.url))
 
-/** A media file the screen saved. `number` is what `/open` and `/play` take. */
-interface Saved {
-  id: string
-  number: number
-  kind: string
-  name: string
-  path?: string
-  error?: string
-}
-
-/** Write the bytes of a media file into `mediaDir`, and return the path. */
-async function saveMedia(part: MediaPart) {
-  await mkdir(mediaDir, { recursive: true })
-  const path = join(mediaDir, `${part.id}-${basename(part.name)}`)
-  await writeFile(path, await part.load())
-  return path
-}
-
-/** Add the media parts of `parts` to `into`, also the ones of child agents. */
-function collectMedia(parts: ReadonlyArray<ViewPart>, into: Array<MediaPart>) {
-  for (const part of parts) {
-    if (part.type === 'media') into.push(part)
-    if (part.type === 'agent') collectMedia(part.parts, into)
-  }
-}
+/** The commands of the screen itself. The harness adds its own to the list. */
+const SCREEN_COMMANDS = [
+  {
+    name: 'connect',
+    description: 'Connect a model provider, Notion, or Linear',
+  },
+  { name: 'disconnect', description: 'Remove a key or a sign-in' },
+  { name: 'model', description: 'Pick the model' },
+  { name: 'mic', description: 'Pick the microphone' },
+  { name: 'open', description: 'Open a media file (default: the last one)' },
+  { name: 'play', description: 'Play an audio or video file' },
+  {
+    name: 'voice',
+    description: 'Send a recorded voice message: /voice note.m4a',
+  },
+  { name: 'help', description: 'Show the commands and the voice tips' },
+  { name: 'exit', description: 'Quit' },
+]
+// Commands that need text after the name: Enter in the list fills the name.
+const TAKES_INPUT = new Set(['voice'])
 
-/** The media files that the agents made, from the assistant messages. */
-function generatedMedia(messages: ReadonlyArray<ViewMessage>) {
-  const media: Array<MediaPart> = []
-  for (const message of messages) {
-    if (message.role === 'assistant') collectMedia(message.parts, media)
-  }
-  return media
-}
+const HELP = [
+  'Type / to see the commands. ↑ and ↓ go through the lines you sent.',
+  'Voice: hold Ctrl+R and talk, then let go. Or tap Ctrl+R, talk, tap again.',
+  '  Name a file ("use cat dot png") or say "the last image" to send it too.',
+  '  The first recording listens on all microphones and keeps the loudest.',
+]
 
-/**
- * Save each new media file once, and number it. Files in the history when
- * the screen opens are not saved again.
- */
-function useSavedMedia(view: SessionView, messages: Array<ViewMessage>) {
-  const [saved, setSaved] = useState<ReadonlyArray<Saved>>([])
-  const [seen] = useState(
-    () =>
-      new Set(generatedMedia(view.store.get().messages).map((part) => part.id)),
-  )
-  useEffect(() => {
-    for (const part of generatedMedia(messages)) {
-      if (seen.has(part.id)) continue
-      seen.add(part.id)
-      const number = seen.size
-      const update = (change: Partial<Saved>) =>
-        setSaved((current) =>
-          current.map((item) =>
-            item.id === part.id ? { ...item, ...change } : item,
-          ),
-        )
-      setSaved((current) => [
-        ...current,
-        { id: part.id, number, kind: part.kind, name: part.name },
-      ])
-      saveMedia(part).then(
-        (path) => update({ path }),
-        (error: unknown) =>
-          update({
-            error: error instanceof Error ? error.message : String(error),
-          }),
+/** The `/` commands that start with (or contain) what you typed after `/`. */
+function suggestionsFor(text: string, commands: ReadonlyArray<ViewCommand>) {
+  if (!/^\/\S*$/.test(text)) return []
+  const query = text.slice(1).toLowerCase()
+  const own = new Set(SCREEN_COMMANDS.map((command) => command.name))
+  const all: Array<MenuItem & { takesInput: boolean }> = [
+    ...SCREEN_COMMANDS.map((command) => ({
+      id: command.name,
+      label: `/${command.name}`,
+      detail: command.description,
+      takesInput: TAKES_INPUT.has(command.name),
+    })),
+    // `connect:openai` and the like are in the `/connect` picker instead.
+    ...commands
+      .filter(
+        (command) => !command.name.includes(':') && !own.has(command.name),
       )
-    }
-  }, [messages, seen])
-  return saved
-}
-
-function textOf(parts: ReadonlyArray<ViewPart>) {
-  return parts.map((part) => (part.type === 'text' ? part.text : '')).join('')
+      .map((command) => ({
+        id: command.name,
+        label: `/${command.name}`,
+        detail: command.description,
+        takesInput: command.input !== undefined,
+      })),
+  ]
+  return [
+    ...all.filter((item) => item.id.startsWith(query)),
+    ...all.filter(
+      (item) => !item.id.startsWith(query) && item.id.includes(query),
+    ),
+  ]
 }
 
-/** A model provider of `providerKeys()`, and where its key comes from. */
-interface ProviderKey {
-  id: string
-  label: string
-  state: 'connected' | 'env' | 'missing'
-}
-
-function isProviderKey(value: unknown): value is ProviderKey {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'id' in value &&
-    typeof value.id === 'string' &&
-    'label' in value &&
-    typeof value.label === 'string' &&
-    'state' in value &&
-    (value.state === 'connected' ||
-      value.state === 'env' ||
-      value.state === 'missing')
-  )
-}
-
-/**
- * The providers in `saved`, the state of the provider-keys plugin (in
- * `state.plugins`). `/connect` and `/disconnect` update it, so the screen
- * shows the keys live. Empty before the plugin reports.
- */
-function providerKeysIn(saved: unknown) {
-  const isState =
-    typeof saved === 'object' && saved !== null && 'providers' in saved
-  if (!isState) return []
-  const { providers } = saved
-  return Array.isArray(providers) ? providers.filter(isProviderKey) : []
-}
-
-/**
- * Is `feature` on? A feature that needs a key follows the saved keys: any
- * one of its providers with a key turns it on. The rest stay as at startup.
- */
-function isOn(
-  feature: (typeof features)[number],
-  keys: ReadonlyArray<ProviderKey>,
-) {
-  const followsKeys = feature.providers.length > 0 && keys.length > 0
-  if (!followsKeys) return feature.on
-  return keys.some(
-    (key) => feature.providers.includes(key.id) && key.state !== 'missing',
+/** Does `/connect <id>` sign in with the browser, with no key to paste? */
+function signsIn(id: string) {
+  return keyProviders.some(
+    (provider) => provider.id === id && 'signIn' in provider,
   )
 }
 
-/** Start a program without a shell. The screen still shows the path on error. */
-function launch(command: string, args: Array<string>) {
-  const child = spawn(command, args, { stdio: 'ignore', detached: true })
-  child.on('error', () => {})
-  child.unref()
-}
-
-/** Open a link or a file with the default app. No shell is involved. */
-function openExternal(target: string) {
-  if (process.platform === 'win32') {
-    // Not `cmd /c start`: cmd would read `&` in a URL as a command separator.
-    if (/^https?:\/\//.test(target))
-      launch('rundll32', ['url.dll,FileProtocolHandler', target])
-    else launch('explorer', [resolve(target)])
-    return
-  }
-  launch(process.platform === 'darwin' ? 'open' : 'xdg-open', [target])
-}
-
-/** Play audio or video with ffplay, which comes with ffmpeg. */
-function play(item: Saved & { path: string }) {
-  const window = item.kind === 'video' ? [] : ['-nodisp']
-  launch(process.env.FFPLAY_PATH || 'ffplay', [
-    ...window,
-    '-autoexit',
-    '-loglevel',
-    'quiet',
-    item.path,
-  ])
-}
-
-function Spinner({ color = 'yellow' }: { color?: string }) {
-  const { frame } = useAnimation({ interval: 90 })
-  return <Text color={color}>{SPINNER[frame % SPINNER.length]}</Text>
-}
-
-/** A short one-line view of tool arguments. */
-function argsPreview(call: ToolCallPart) {
-  const text =
-    typeof call.args === 'object' && call.args !== null
-      ? Object.values(call.args)
-          .filter((value) => typeof value === 'string')
-          .join(', ')
-      : ''
-  const line = text.replace(/\s+/g, ' ').trim()
-  return line.length > 70 ? `${line.slice(0, 70)}...` : line
+/** The rows of the `/connect` picker: the model providers, then the apps. */
+function connectItems(state: SessionViewState): Array<MenuItem> {
+  const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
+  const providers = keys.map((key) => ({
+    id: key.id,
+    label: key.label,
+    current: key.state !== 'missing',
+    detail:
+      key.state === 'connected'
+        ? 'connected'
+        : key.state === 'env'
+          ? 'key from the environment'
+          : signsIn(key.id)
+            ? 'sign in with the browser, no key to paste'
+            : 'opens the page to make a key, then you paste it',
+  }))
+  const apps = state.commands.flatMap((command) => {
+    const id = command.name.slice('connect:'.length)
+    const isApp =
+      command.name.startsWith('connect:') && !keys.some((key) => key.id === id)
+    return isApp ? [{ id, label: id, detail: command.description }] : []
+  })
+  return [...providers, ...apps]
 }
 
-function ToolLine({
-  call,
-  indent = 2,
-}: {
-  call: ToolCallPart
-  indent?: number
-}) {
-  const icon =
-    call.status === 'running' ? (
-      <Spinner />
-    ) : call.status === 'done' ? (
-      <Text color="green">✓</Text>
-    ) : call.status === 'failed' ? (
-      <Text color="red">✗</Text>
-    ) : (
-      <Text color="magenta">?</Text>
+/** The rows of the `/model` picker, with the provider and the context size. */
+function modelItems(state: SessionViewState): Array<MenuItem> {
+  const entry = state.config.find((item) => item.key === 'model')
+  if (entry?.option.type !== 'select') return []
+  const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
+  return entry.option.options.map((name) => {
+    const info = modelInfo[name]
+    const missing = keys.some(
+      (key) => key.id === info?.provider && key.state === 'missing',
     )
-  const preview = argsPreview(call)
-  return (
-    <Box marginLeft={indent}>
-      {icon}
-      <Text color="yellow">{` ${call.name}`}</Text>
-      {preview ? <Text dimColor>{`  ${preview}`}</Text> : null}
-      {call.status === 'needs-approval' ? (
-        <Text color="magenta"> waits for your approval</Text>
-      ) : null}
-    </Box>
-  )
-}
-
-function MediaLine({
-  part,
-  saved,
-  indent = 2,
-}: {
-  part: MediaPart
-  saved: ReadonlyArray<Saved>
-  indent?: number
-}) {
-  const item = saved.find((entry) => entry.id === part.id)
-  const color = KIND_COLOR[part.kind] ?? 'white'
-  return (
-    <Box marginLeft={indent}>
-      <Text color={color} bold>
-        {`▣ ${item ? `${item.number} ` : ''}${part.kind}`}
-      </Text>
-      <Text>{`  ${part.name}`}</Text>
-      {item?.path ? <Text dimColor>{`  -> ${item.path}`}</Text> : null}
-      {item?.error ? (
-        <Text color="red">{`  not saved: ${item.error}`}</Text>
-      ) : null}
-      {item && !item.path && !item.error ? (
-        <Text dimColor> saving...</Text>
-      ) : null}
-    </Box>
-  )
-}
-
-/**
- * A child agent, for example Codex or Claude Code, in its own card: its
- * status, its last tool calls, its media, and its output. While it runs, the
- * last 4 lines show. When it ends, the last 15 lines of its answer stay.
- */
-function Agent({
-  part,
-  saved,
-}: {
-  part: AgentPart
-  saved: ReadonlyArray<Saved>
-}) {
-  const lines = textOf(part.parts)
-    .split('\n')
-    .map((line) => line.trimEnd())
-    .filter((line) => line.trim() !== '')
-  const running = part.status === 'running'
-  const output = running ? lines.slice(-4) : lines.slice(-15)
-  const calls = part.parts.flatMap((inner) =>
-    inner.type === 'tool-call' ? [inner] : [],
-  )
-  const media = part.parts.flatMap((inner) =>
-    inner.type === 'media' ? [inner] : [],
-  )
-  const color = part.status === 'failed' ? 'red' : running ? 'yellow' : 'green'
-  return (
-    <Box
-      flexDirection="column"
-      borderStyle="round"
-      borderColor={color}
-      paddingX={1}
-      marginLeft={2}
-    >
-      <Box>
-        {running ? (
-          <Spinner color={color} />
-        ) : (
-          <Text color={color}>{part.status === 'done' ? '✓' : '✗'}</Text>
-        )}
-        <Text bold>{` ${part.name}`}</Text>
-        <Spacer />
-        <Text color={color}>{part.status}</Text>
-      </Box>
-      {calls.slice(-4).map((call) => (
-        <ToolLine key={call.id} call={call} indent={0} />
-      ))}
-      {media.map((inner) => (
-        <MediaLine key={inner.id} part={inner} saved={saved} indent={0} />
-      ))}
-      {output.map((line, index) => (
-        <Text key={`line-${index}`} dimColor={running}>
-          {line}
-        </Text>
-      ))}
-      {part.error ? <Text color="red">{part.error}</Text> : null}
-    </Box>
-  )
-}
-
-function Part({
-  part,
-  saved,
-}: {
-  part: ViewPart
-  saved: ReadonlyArray<Saved>
-}) {
-  switch (part.type) {
-    case 'text':
-      return (
-        <Box marginLeft={2}>
-          <Text>{part.text}</Text>
-        </Box>
-      )
-    case 'reasoning':
-      return (
-        <Box marginLeft={2}>
-          <Text dimColor italic>
-            {part.text}
-          </Text>
-        </Box>
-      )
-    case 'tool-call':
-      return <ToolLine call={part} />
-    case 'agent':
-      return <Agent part={part} saved={saved} />
-    case 'media':
-      return <MediaLine part={part} saved={saved} />
-  }
+    return {
+      id: name,
+      label: name,
+      current: name === entry.value,
+      detail: info
+        ? `${info.provider}, ${compact(info.contextWindow)} context${missing ? `, needs /connect ${info.provider}` : ''}`
+        : 'no key needed',
+    }
+  })
 }
 
-function Message({
-  message,
-  saved,
-}: {
-  message: ViewMessage
-  saved: ReadonlyArray<Saved>
-}) {
-  switch (message.role) {
-    case 'user': {
-      // A voice message names its files as `@"path"`, shown as a file badge.
-      const named: Array<string> = []
-      const text = message.text
-        .replace(/@"([^"]+)"/g, (_match, path: string) => {
-          named.push(basename(path))
-          return ''
-        })
-        .trim()
-      const files = [
-        ...(message.media ?? []).map((part) => `${part.kind} ${part.name}`),
-        ...named,
-      ]
-      return (
-        <Box marginTop={1} flexWrap="wrap">
-          <Text bold>
-            <Text color={ACCENT}>❯ </Text>
-            {text}
-            {files.length > 0 ? ' ' : ''}
-          </Text>
-          {files.map((file) => (
-            <Text key={file} color="black" backgroundColor={ACCENT}>
-              {` ${file} `}
-            </Text>
-          ))}
-        </Box>
-      )
-    }
-    case 'notice': {
-      const isError = message.kind === 'error'
-      return (
-        <Box marginLeft={2}>
-          <Text
-            color={isError ? 'red' : 'gray'}
-          >{`${isError ? '✗' : '·'} ${message.text}`}</Text>
-        </Box>
-      )
-    }
-    case 'assistant':
-      return (
-        <Box flexDirection="column" marginTop={1}>
-          {message.parts.map((part, index) => (
-            <Part key={index} part={part} saved={saved} />
-          ))}
-        </Box>
-      )
-  }
+/** A list open over the input line, for example the `/connect` picker. */
+interface Picker {
+  title: string
+  items: Array<MenuItem>
+  pick: (item: MenuItem) => unknown
 }
 
-function Header({ view }: { view: SessionView }) {
-  const model = useSelector(
-    view.store,
-    (state) => state.config.find((entry) => entry.key === 'model')?.value,
-  )
-  // The plugin state, not a new list, so the header renders only on a change.
-  const saved = useSelector(view.store, (state) => state.plugins[PROVIDER_KEYS])
-  const keys = providerKeysIn(saved)
+function Header() {
   return (
     <Box
       flexDirection="column"
@@ -455,194 +171,103 @@ function Header({ view }: { view: SessionView }) {
         </Text>
         <Text bold> harness</Text>
         <Text dimColor>{`  ${assistant.name}`}</Text>
-        <Spacer />
-        <Text dimColor>model </Text>
-        <Text color="cyan" bold>
-          {String(model ?? '?')}
-        </Text>
       </Box>
-      <Box flexWrap="wrap">
-        {features.map((feature) => {
-          const on = isOn(feature, keys)
-          return (
-            <Text key={feature.name} color={on ? 'green' : 'gray'}>
-              {`${on ? '●' : '○'} ${feature.name}   `}
-            </Text>
-          )
-        })}
-      </Box>
-      {keys.length > 0 ? (
-        <Box flexWrap="wrap">
-          <Text dimColor>keys </Text>
-          {keys.map((key) => (
-            <Text
-              key={key.id}
-              color={key.state === 'missing' ? 'gray' : 'green'}
-            >
-              {`${key.id} ${key.state === 'missing' ? '○' : '●'}  `}
-            </Text>
-          ))}
-        </Box>
-      ) : null}
-    </Box>
-  )
-}
-
-type VoiceState = 'idle' | 'starting' | 'recording' | 'transcribing'
-
-/** A live level meter from the microphone loudness (0 to 32768). */
-function LevelMeter({ recording }: { recording: Recording }) {
-  const { time } = useAnimation({ interval: 80 })
-  const level = recording.level()
-  // Map loudness to 0..1 on a log scale: -60 dB is empty, 0 dB is full.
-  const decibels = 20 * Math.log10(Math.max(level, 1) / 32768)
-  const filled = Math.round(Math.min(1, Math.max(0, (decibels + 60) / 60)) * 16)
-  const seconds = Math.floor(time / 1000)
-  const clock = `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`
-  return (
-    <Box>
-      <Text color="red" bold>{`● REC ${clock}  `}</Text>
-      <Text color={filled > 9 ? 'green' : filled > 4 ? 'yellow' : 'gray'}>
-        {'▮'.repeat(filled)}
-      </Text>
-      <Text dimColor>{'▯'.repeat(16 - filled)}</Text>
-      <Text dimColor>{`  ${recording.microphone}`}</Text>
-    </Box>
-  )
-}
-
-function Status({
-  view,
-  voice,
-  recording,
-}: {
-  view: SessionView
-  voice: VoiceState
-  recording: Recording | undefined
-}) {
-  const status = useSelector(view.store, (state) => state.status)
-  const approvals = useSelector(view.store, (state) => state.approvals)
-  const question = useSelector(view.store, (state) => state.questions.at(0))
-  const signIns = useSelector(view.store, (state) => state.signIns)
-  const goal = useSelector(view.store, selectGoal)
-  return (
-    <Box flexDirection="column" marginTop={1}>
-      {signIns.map((signIn) => (
-        <Text key={signIn.connector} color="magenta">
-          {`◇ Sign in to ${signIn.connector}: ${signIn.url ?? `run /connect ${signIn.connector}`}${signIn.userCode ? ` (code ${signIn.userCode})` : ''}`}
-        </Text>
-      ))}
-      {approvals.length > 0 ? (
-        <Text color="magenta" bold>
-          {`◇ Approve ${approvals.map((item) => item.tool).join(', ')}? Type y or n.`}
-        </Text>
-      ) : null}
-      {question ? <Text color="magenta">{`◇ ${question.message}`}</Text> : null}
-      {goal ? (
-        <Text color="green">{`◎ Goal: ${goal.text} (${goal.status}, round ${goal.round})`}</Text>
-      ) : null}
-      {voice === 'recording' && recording ? (
-        <Box flexDirection="column">
-          <LevelMeter recording={recording} />
-          <Text dimColor>
-            Let go of Ctrl+R (or tap it again) to send. Esc drops it.
-          </Text>
-        </Box>
-      ) : voice === 'starting' ? (
-        <Box>
-          <Spinner color="red" />
-          <Text color="red"> opening the microphone...</Text>
-        </Box>
-      ) : voice === 'transcribing' ? (
-        <Box>
-          <Spinner color="cyan" />
-          <Text color="cyan"> listening to your voice message...</Text>
-        </Box>
-      ) : status === 'running' ? (
-        <Box>
-          <Spinner />
-          <Text color="yellow"> working</Text>
-          <Text dimColor> Esc cancels, typing steers</Text>
-        </Box>
-      ) : null}
+      <Text dimColor>{process.cwd()}</Text>
     </Box>
   )
 }
 
 function InputBox({
-  input,
+  line,
   voice,
   hidden,
 }: {
-  input: string
+  line: Line
   voice: VoiceState
   /** The input is a secret (a key): show a dot for each character. */
   hidden: boolean
 }) {
-  const active = voice === 'idle'
+  const shown = hidden ? '•'.repeat(line.text.length) : line.text
   return (
     <Box
       borderStyle="round"
-      borderColor={voice === 'recording' ? 'red' : active ? ACCENT : 'gray'}
+      borderColor={
+        voice === 'recording' ? 'red' : voice === 'idle' ? ACCENT : 'gray'
+      }
       paddingX={1}
     >
       <Text color={ACCENT} bold>
         {'❯ '}
       </Text>
-      {input === '' ? (
-        <Text dimColor>
-          {hidden
-            ? 'Paste the key. It stays hidden.'
-            : 'Type a message, @file to attach, or hold Ctrl+R to talk'}
+      {shown === '' ? (
+        // The cursor goes before the hint, so the hint does not look typed.
+        <Text>
+          <Text inverse> </Text>
+          <Text dimColor>
+            {hidden
+              ? ' Paste the key. It stays hidden.'
+              : ' Type a message, / for commands, @file to attach, or hold Ctrl+R to talk'}
+          </Text>
         </Text>
       ) : (
-        <Text>{hidden ? '•'.repeat(input.length) : input}</Text>
+        <Text>
+          {shown.slice(0, line.cursor)}
+          <Text inverse>{shown[line.cursor] ?? ' '}</Text>
+          {shown.slice(line.cursor + 1)}
+        </Text>
       )}
-      <Text inverse> </Text>
     </Box>
   )
 }
 
-const HELP = [
-  'Voice: hold Ctrl+R and talk, then let go. Or tap Ctrl+R, talk, tap again.',
-  '  Name a file ("use cat dot png") or say "the last image" to send it too.',
-  '  The first recording listens on all microphones and keeps the loudest.',
-  '/mic [n]      list the microphones, or record from microphone n',
-  '/voice <file> send a recorded voice message',
-  '/open [n]     open media file n (default: the last one)',
-  '/play [n]     play audio or video file n',
-  '/connect <id> connect a model provider (/keys lists them), notion, or linear',
-  '/disconnect <id> remove that key or sign-in',
-  '/keys         show where each model key comes from',
-  '/exit         quit',
-]
-
 // A key held down repeats. Repeats closer than this are one press.
 const REPEAT_GAP = 1100
 // After the last repeat, the key is up when no repeat comes for this long.
 const RELEASE_WAIT = 450
 
+type Row = { id: 'header' } | ViewMessage
+
 function App({ view }: { view: SessionView }) {
   const { exit } = useApp()
   const messages = useSelector(view.store, (state) => state.messages)
-  const saved = useSavedMedia(view, messages)
-  // The input line. `hidden`: it holds a secret (a key), typed while a
-  // question asked for one. It stays hidden until it is sent or deleted, also
-  // when the question ends first, so a key never shows or goes out as a
-  // message.
-  const [input, setInput] = useState({ text: '', hidden: false })
+  const running = useSelector(view.store, (state) => state.status === 'running')
+  const { saved, saving } = useSavedMedia(view, messages)
+  // The input line. A line typed while a question asks for a key stays hidden
+  // until it is sent or deleted, also when the question ends first, so a key
+  // never shows or goes out as a message.
+  const editor = useLineEditor()
   const secretAsked = useSelector(
     view.store,
     (state) => state.questions.at(0)?.secret === true,
   )
-  /** Add typed or pasted text to the input line. */
-  const type = (text: string) => {
-    const asked = view.store.get().questions.at(0)?.secret === true
-    setInput((current) => ({
-      text: current.text + text,
-      hidden: asked || (current.hidden && current.text !== ''),
-    }))
-  }
+  const asksSecret = () => view.store.get().questions.at(0)?.secret === true
+  const commands = useSelector(view.store, (state) => state.commands)
+  const waiting = useSelector(
+    view.store,
+    (state) => state.questions.length > 0 || state.approvals.length > 0,
+  )
+  const [picker, setPicker] = useState<Picker | undefined>(undefined)
+  const [selected, setSelected] = useState(0)
+  const suggestions =
+    // A line from the history keeps the arrows for the history.
+    picker || waiting || editor.line.hidden || editor.browsing
+      ? []
+      : suggestionsFor(editor.line.text, commands)
+  const [suggested, setSuggested] = useState(0)
+  useEffect(() => setSuggested(0), [editor.line.text])
+
+  // Messages that no longer change print once, above the live area. The
+  // count only grows: a printed message is never printed again.
+  const printed = useRef(0)
+  printed.current = Math.max(
+    printed.current,
+    settledCount(messages, saving, running),
+  )
+  const rows: Array<Row> = [
+    { id: 'header' },
+    ...messages.slice(0, printed.current),
+  ]
+
   const [voice, setVoiceState] = useState<VoiceState>('idle')
   // The phase in a ref too: key events come faster than React renders, and a
   // second Ctrl+R must see "starting" at once, or it starts a second recorder.
@@ -662,6 +287,8 @@ function App({ view }: { view: SessionView }) {
   const release = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
 
   const fail = (error: unknown) =>
+    view.notice(error instanceof Error ? error.message : String(error))
+  const failVoice = (error: unknown) =>
     view.notice(
       `Voice: ${error instanceof Error ? error.message : String(error)}`,
     )
@@ -694,7 +321,7 @@ function App({ view }: { view: SessionView }) {
       )
       await view.send(message.text)
     } catch (error) {
-      fail(error)
+      failVoice(error)
     } finally {
       setVoice('idle')
     }
@@ -712,7 +339,7 @@ function App({ view }: { view: SessionView }) {
     setRecorder(undefined)
     await current
       .stop()
-      .then((clip) => hear(clip.audio, 'voice.wav', clip), fail)
+      .then((clip) => hear(clip.audio, 'voice.wav', clip), failVoice)
   }
 
   const startTalking = async () => {
@@ -728,7 +355,7 @@ function App({ view }: { view: SessionView }) {
       if (!(await canTranscribe(view.store.get().threadId))) {
         setVoice('idle')
         return view.notice(
-          'Voice: run /connect openai (or /connect grok) to turn voice on.',
+          'Voice: run /connect and pick OpenAI or xAI to turn voice on.',
         )
       }
       const started = await startRecording()
@@ -743,7 +370,7 @@ function App({ view }: { view: SessionView }) {
       if (talk.current.stopWanted) await stopTalking()
     } catch (error) {
       setVoice('idle')
-      fail(error)
+      failVoice(error)
     }
   }
 
@@ -780,8 +407,41 @@ function App({ view }: { view: SessionView }) {
     return { ...item, path: item.path }
   }
 
+  const openPicker = (next: Picker) => {
+    if (next.items.length === 0)
+      return view.notice(`${next.title}: nothing to pick.`)
+    setSelected(
+      Math.max(
+        0,
+        next.items.findIndex((item) => item.current),
+      ),
+    )
+    setPicker(next)
+  }
+
+  const pickMicrophone = async () => {
+    const names = await listMicrophones()
+    const current = await currentMicrophone()
+    if (names.length === 0)
+      return view.notice(
+        `Recording from the default input${current ? ` (${current})` : ''}.`,
+      )
+    openPicker({
+      title: 'Record from which microphone?',
+      items: names.map((name) => ({
+        id: name,
+        label: name,
+        current: name === current,
+      })),
+      pick: async (item) => {
+        await chooseMicrophone(item.id)
+        view.notice(`Voice: recording from "${item.id}".`)
+      },
+    })
+  }
+
   /** Enter: answer an approval or a question, run a screen command, or send. */
-  const submit = async (line: { text: string; hidden: boolean }) => {
+  const submit = async (line: Line) => {
     const text = line.text.trim()
     const state = view.store.get()
     const [question] = state.questions
@@ -809,68 +469,107 @@ function App({ view }: { view: SessionView }) {
       await question.answer(answer)
       return
     }
-    if (text === '/exit') return exit()
-    if (text === '/help') {
-      const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
-      const off = features
-        .filter((feature) => !isOn(feature, keys))
-        .map(
-          (feature) => `  ${feature.name} is off: it needs ${feature.needs}.`,
-        )
-      const commands = state.commands.map(
-        (command) => `/${command.name}  ${command.description}`,
-      )
-      view.notice([...HELP, ...off, ...commands].join('\n'))
-      return
-    }
     const [command, ...rest] = text.split(' ')
     const arg = rest.join(' ').trim() || undefined
-    if (command === '/mic') {
-      const names = await listMicrophones().catch((error: unknown) => {
-        fail(error)
-        return []
-      })
-      const chosen = arg ? names[Number(arg) - 1] : undefined
-      if (chosen) await chooseMicrophone(chosen)
-      const current = await currentMicrophone()
-      view.notice(
-        names.length === 0
-          ? `Recording from the default input${current ? ` (${current})` : ''}.`
-          : [
-              ...names.map(
-                (name, index) =>
-                  `${name === current ? '●' : '○'} ${index + 1}. ${name}`,
+    switch (command) {
+      case '/exit':
+        return exit()
+      case '/help': {
+        const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
+        const off = features
+          .filter((feature) => !isOn(feature, keys))
+          .map(
+            (feature) => `  ${feature.name} is off: it needs ${feature.needs}.`,
+          )
+        const list = suggestionsFor('/', state.commands).map(
+          (item) => `${item.label.padEnd(14)}${item.detail ?? ''}`,
+        )
+        return view.notice([...HELP, ...off, ...list].join('\n'))
+      }
+      case '/connect':
+        if (arg) return view.command(`connect:${arg}`)
+        return openPicker({
+          title: 'Connect to what?',
+          items: connectItems(state),
+          pick: (item) => view.command(`connect:${item.id}`),
+        })
+      case '/disconnect': {
+        if (arg) return view.command(`disconnect:${arg}`)
+        // A key from the environment cannot be removed here, so it is not listed.
+        const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
+        return openPicker({
+          title: 'Remove which key or sign-in?',
+          items: connectItems(state).filter(
+            (item) =>
+              !keys.some(
+                (key) => key.id === item.id && key.state !== 'connected',
               ),
-              current
-                ? '/mic <n> records from microphone n.'
-                : 'No microphone yet: the first recording picks the loudest.',
-            ].join('\n'),
-      )
-      return
-    }
-    if (command === '/voice') {
-      if (!arg) return view.notice('Give an audio file: /voice note.m4a')
-      const path = arg.replace(/^@|^"|"$/g, '')
-      const audio = await readFile(path).catch(fail)
-      if (audio) await hear(new Uint8Array(audio), basename(path))
-      return
-    }
-    if (command === '/open' || command === '/play') {
-      const item = pick(arg)
-      if (!item) return
-      if (command === '/play' && item.kind !== 'image') play(item)
-      else openExternal(item.path)
-      return
+          ),
+          pick: (item) => view.command(`disconnect:${item.id}`),
+        })
+      }
+      case '/model':
+        if (arg) break
+        return openPicker({
+          title: 'Pick the model',
+          items: modelItems(state),
+          pick: (item) => view.command('model', item.id),
+        })
+      case '/mic': {
+        if (!arg) return pickMicrophone().catch(failVoice)
+        const names = await listMicrophones().catch(() => [])
+        const chosen = names[Number(arg) - 1]
+        if (!chosen)
+          return view.notice(`No microphone ${arg}. /mic lists them.`)
+        await chooseMicrophone(chosen)
+        return view.notice(`Voice: recording from "${chosen}".`)
+      }
+      case '/voice': {
+        if (!arg) return view.notice('Give an audio file: /voice note.m4a')
+        const path = arg.replace(/^@|^"|"$/g, '')
+        const audio = await readFile(path).catch(failVoice)
+        if (audio) await hear(new Uint8Array(audio), basename(path))
+        return
+      }
+      case '/open':
+      case '/play': {
+        const item = pick(arg)
+        if (!item) return
+        if (command === '/play' && item.kind !== 'image') play(item)
+        else openExternal(item.path)
+        return
+      }
     }
-    const connect = /^\/(connect|disconnect) (\S+)$/.exec(text)
-    if (connect) return view.command(`${connect[1]}:${connect[2]}`)
     await view.send(text)
   }
 
-  usePaste(type)
+  /** Send a line and keep it for the up arrow, unless it is a key or an answer. */
+  const send = (line: Line) => {
+    const state = view.store.get()
+    const isAnswer = state.questions.length > 0 || state.approvals.length > 0
+    if (!line.hidden && !isAnswer) editor.remember(line.text)
+    editor.clear()
+    submit(line).catch(fail)
+  }
+
+  usePaste((text) => editor.insert(text, asksSecret()))
 
   useInput((character, key) => {
     if (key.ctrl && character === 'r') return onTalkKey()
+    if (picker) {
+      const count = picker.items.length
+      const number = Number(character)
+      const chosen = key.return
+        ? picker.items[selected]
+        : Number.isInteger(number) && number >= 1
+          ? picker.items[number - 1]
+          : undefined
+      if (key.escape || chosen) setPicker(undefined)
+      if (chosen) Promise.resolve(picker.pick(chosen)).catch(fail)
+      if (key.upArrow) setSelected((index) => (index - 1 + count) % count)
+      if (key.downArrow) setSelected((index) => (index + 1) % count)
+      return
+    }
     if (key.escape) {
       clearTimeout(release.current)
       if (phase.current === 'starting') {
@@ -887,48 +586,82 @@ function App({ view }: { view: SessionView }) {
         return
       }
       if (view.store.get().status === 'running') void view.cancel()
+      else editor.clear()
       return
     }
+    const suggestion = suggestions[Math.min(suggested, suggestions.length - 1)]
+    if (suggestion) {
+      const count = suggestions.length
+      if (key.upArrow)
+        return setSuggested((index) => (index - 1 + count) % count)
+      if (key.downArrow) return setSuggested((index) => (index + 1) % count)
+      if (key.tab) return editor.set(`/${suggestion.id} `)
+      if (key.return) {
+        if (suggestion.takesInput) return editor.set(`/${suggestion.id} `)
+        return send({ text: `/${suggestion.id}`, cursor: 0, hidden: false })
+      }
+    }
+    if (key.upArrow) return editor.older()
+    if (key.downArrow) return editor.newer()
+    if (key.leftArrow) return editor.move(-1)
+    if (key.rightArrow) return editor.move(1)
+    if (key.home) return editor.move('start')
+    if (key.end) return editor.move('end')
     if (key.return) {
       if (phase.current === 'recording' || phase.current === 'starting')
         return void stopTalking()
-      setInput({ text: '', hidden: false })
-      void submit(input)
-      return
-    }
-    if (key.backspace || key.delete) {
-      setInput((current) => ({ ...current, text: current.text.slice(0, -1) }))
-      return
+      return send(editor.line)
     }
-    if (!key.ctrl && !key.meta && character) type(character)
+    // Most terminals send Backspace as the delete key.
+    if (key.backspace || key.delete) return editor.backspace()
+    if (!key.ctrl && !key.meta && !key.tab && character)
+      editor.insert(character, asksSecret())
   })
 
   return (
     <Box flexDirection="column">
-      <Header view={view} />
-      {messages.slice(-60).map((message) => (
+      <Static items={rows}>
+        {(row) =>
+          'role' in row ? (
+            <Message key={row.id} message={row} saved={saved} />
+          ) : (
+            <Header key={row.id} />
+          )
+        }
+      </Static>
+      {messages.slice(printed.current).map((message) => (
         <Message key={message.id} message={message} saved={saved} />
       ))}
       <Status view={view} voice={voice} recording={recorder} />
       <InputBox
-        input={input.text}
+        line={editor.line}
         voice={voice}
-        hidden={secretAsked || (input.hidden && input.text !== '')}
+        hidden={secretAsked || (editor.line.hidden && editor.line.text !== '')}
       />
-      <Text dimColor>
-        {
-          '  Ctrl+R talk   Esc cancel   /model   /keys   /mic   /open   /play   /help   /exit'
-        }
-      </Text>
+      {picker ? (
+        <Menu
+          title={picker.title}
+          items={picker.items}
+          selected={selected}
+          hint="↑↓ move   Enter or a number picks   Esc closes"
+        />
+      ) : suggestions.length > 0 ? (
+        <Menu
+          items={suggestions}
+          selected={Math.min(suggested, suggestions.length - 1)}
+          hint="↑↓ move   Tab fills   Enter runs"
+        />
+      ) : null}
+      <Footer view={view} />
     </Box>
   )
 }
 
 /**
- * The Ink screen for `runCli({ ui })`. It opens sign-in links in the browser,
- * records voice messages, saves the media the agents make into
- * `./<harness-name>-media`, and resolves when the user types /exit or presses
- * Ctrl+C. `io` replaces the terminal, for a test.
+ * The Ink screen for `runCli({ ui })`. It clears the terminal, opens sign-in
+ * links in the browser, records voice messages, saves the media the agents
+ * make into `./<harness-name>-media`, and resolves when the user types /exit
+ * or presses Ctrl+C. `io` replaces the terminal, for a test.
  */
 export async function runTui(view: SessionView, io: RenderOptions = {}) {
   view.on('signIn', (signIn) => {
@@ -937,9 +670,8 @@ export async function runTui(view: SessionView, io: RenderOptions = {}) {
   const keys = providerKeysIn(view.store.get().plugins[PROVIDER_KEYS])
   if (keys.every((key) => key.state === 'missing'))
     view.notice(
-      'No model key yet. Run /connect openai to paste a key, or /connect openrouter to sign in with the browser. /keys lists them all.',
+      'No model key yet. Type /connect and pick OpenRouter to sign in with the browser.',
     )
-  view.notice('Hold Ctrl+R to talk, or type. /help lists the commands.')
   // ponytail: the SDK logs its warnings and errors on the console (the message,
   // then its details with console.dir). Ink prints console output above the
   // screen, and the screen shows those errors itself, so it drops them.
@@ -958,6 +690,9 @@ export async function runTui(view: SessionView, io: RenderOptions = {}) {
     if (dropDetails) dropDetails = false
     else dir(...args)
   }
+  // Start on a clean terminal: clear the screen and the scrollback.
+  if (!io.stdout && process.stdout.isTTY)
+    process.stdout.write('\x1b[2J\x1b[3J\x1b[H')
   try {
     await render(<App view={view} />, io).waitUntilExit()
   } finally {
diff --git a/packages/ai-harness/src/first-party/provider-keys.ts b/packages/ai-harness/src/first-party/provider-keys.ts
index 65c2aaf0d9..e6ab6261be 100644
--- a/packages/ai-harness/src/first-party/provider-keys.ts
+++ b/packages/ai-harness/src/first-party/provider-keys.ts
@@ -12,8 +12,15 @@ type ProviderSignIn = (ctx: {
   signal?: AbortSignal
 }) => Promise<string>
 
-/** A provider the user can connect: its BYOK descriptor, with a sign-in when it has one. */
-type KeyProvider = ByokProvider | (ByokProvider & { signIn: ProviderSignIn })
+/**
+ * A provider the user can connect: its BYOK descriptor, with a sign-in when
+ * it has one. `keyUrl` is the provider's page to make a key: `/connect` opens
+ * it in the browser before it asks for the key.
+ */
+type KeyProvider = ByokProvider & {
+  signIn?: ProviderSignIn
+  keyUrl?: string
+}
 
 interface ProviderKeyStatus {
   id: string
@@ -66,7 +73,9 @@ async function describeKey(
  *
  * @param options.providers - BYOK descriptors, for example `openaiByok`. Add
  *   `signIn` for a provider with a browser sign-in, for example
- *   `{ ...openrouterByok, signIn: openrouterSignIn() }`.
+ *   `{ ...openrouterByok, signIn: openrouterSignIn() }`, or `keyUrl` to open
+ *   the provider's key page before the question, for example
+ *   `{ ...openaiByok, keyUrl: 'https://platform.openai.com/api-keys' }`.
  *
  * @example
  * ```ts
@@ -103,15 +112,15 @@ export function providerKeys(options: {
 
       /** The key from the provider's sign-in, else the one the user pastes. */
       const readKey = async (provider: KeyProvider, signal: AbortSignal) => {
-        if ('signIn' in provider) {
-          return provider.signIn({
-            open: (url) =>
-              ctx.session.authRequired({ connector: provider.id, url }),
-            signal,
-          })
-        }
+        const open = (url: string) =>
+          ctx.session.authRequired({ connector: provider.id, url })
+        if (provider.signIn) return provider.signIn({ open, signal })
+        // No sign-in for other apps: open the page to make a key, then ask.
+        if (provider.keyUrl) open(provider.keyUrl)
         return ctx.session.ask({
-          message: `Paste your ${provider.label} API key`,
+          message: provider.keyUrl
+            ? `Paste your ${provider.label} API key. The page to make one is open in your browser.`
+            : `Paste your ${provider.label} API key`,
           secret: true,
         })
       }
diff --git a/packages/ai-harness/src/first-party/session-tools.ts b/packages/ai-harness/src/first-party/session-tools.ts
index 5205419e01..eba347d004 100644
--- a/packages/ai-harness/src/first-party/session-tools.ts
+++ b/packages/ai-harness/src/first-party/session-tools.ts
@@ -82,11 +82,18 @@ interface UsageTotals {
   promptTokens: number
   completionTokens: number
   totalTokens: number
+  /**
+   * The input tokens of the latest model call of the lead turn: how much of
+   * the model's context the conversation fills now.
+   */
+  contextTokens: number
 }
 
 /**
  * Count tokens across the session: the lead turn and every agent run
- * (subagents, background agents, and their children). `/usage` shows the totals.
+ * (subagents, background agents, and their children). `/usage` shows the
+ * totals. The plugin state also has `contextTokens`, the size of the lead
+ * model's context at its latest call, for a UI.
  */
 export function usage() {
   return definePlugin({
@@ -97,25 +104,31 @@ export function usage() {
         promptTokens: 0,
         completionTokens: 0,
         totalTokens: 0,
+        contextTokens: 0,
       })
       const show = (totals: UsageTotals) =>
         `${totals.turns} model calls, ${totals.promptTokens} input tokens, ${totals.completionTokens} output tokens, ${totals.totalTokens} total.`
-      const count = {
-        name: 'tanstack/usage',
-        onUsage: async (_run, info) => {
-          await state.update((totals) => ({
-            turns: totals.turns + 1,
-            promptTokens: totals.promptTokens + (info.promptTokens ?? 0),
-            completionTokens:
-              totals.completionTokens + (info.completionTokens ?? 0),
-            totalTokens: totals.totalTokens + (info.totalTokens ?? 0),
-          }))
-        },
-      } satisfies AnyChatMiddleware
+      const counter = (lead: boolean) =>
+        ({
+          name: 'tanstack/usage',
+          onUsage: async (_run, info) => {
+            await state.update((totals) => ({
+              turns: totals.turns + 1,
+              promptTokens: totals.promptTokens + (info.promptTokens ?? 0),
+              completionTokens:
+                totals.completionTokens + (info.completionTokens ?? 0),
+              totalTokens: totals.totalTokens + (info.totalTokens ?? 0),
+              contextTokens: lead
+                ? (info.promptTokens ?? totals.contextTokens)
+                : totals.contextTokens,
+            }))
+          },
+        }) satisfies AnyChatMiddleware
       return {
-        // The same counter in the lead turn and in every agent run.
-        middleware: [count],
-        agentMiddleware: [count],
+        // The same totals for the lead turn and every agent run. Only the
+        // lead turn sets the context size.
+        middleware: [counter(true)],
+        agentMiddleware: [counter(false)],
         commands: {
           usage: defineCommand({
             description: 'Show token usage for this session',
diff --git a/packages/ai-harness/tests/agent-middleware.test.ts b/packages/ai-harness/tests/agent-middleware.test.ts
index 53991c13b3..de3dc90a6b 100644
--- a/packages/ai-harness/tests/agent-middleware.test.ts
+++ b/packages/ai-harness/tests/agent-middleware.test.ts
@@ -200,6 +200,10 @@ describe('plugin agentMiddleware', () => {
     expect(await session.command('usage')).toBe(
       '5 model calls, 133 input tokens, 0 output tokens, 133 total.',
     )
+    // The context size is the input of the lead's latest call, not an agent's.
+    expect(session.snapshot().plugins['tanstack/usage']).toMatchObject({
+      contextTokens: 2,
+    })
     await host.close()
   })
 })
diff --git a/packages/ai-harness/tests/provider-keys.test.ts b/packages/ai-harness/tests/provider-keys.test.ts
index e67ff3c83a..ab0d292812 100644
--- a/packages/ai-harness/tests/provider-keys.test.ts
+++ b/packages/ai-harness/tests/provider-keys.test.ts
@@ -297,6 +297,32 @@ describe('providerKeys', () => {
     await close()
   })
 
+  it('opens the key page of a provider with keyUrl before it asks', async () => {
+    const { session, persistence, events, close } = await open({
+      adapter: mockAdapter([]).adapter,
+      plugins: [
+        providerKeys({
+          providers: [{ ...acme, keyUrl: 'https://acme.example/keys' }],
+        }),
+      ],
+    })
+    const { question, result } = await connectWith(session, PASTED_KEY)
+    expect(authRequired(events)).toEqual([
+      { connector: 'acme', url: 'https://acme.example/keys' },
+    ])
+    expect(question).toMatchObject({
+      message:
+        'Paste your Acme API key. The page to make one is open in your browser.',
+      secret: true,
+    })
+    expect(result).toBe('Connected to Acme (key ...5678).')
+    expect(await persistence.stores.credentials.get(USER, 'acme')).toEqual({
+      type: 'api_key',
+      value: PASTED_KEY,
+    })
+    await close()
+  })
+
   it('runs signIn with open through authRequired and saves its key', async () => {
     const signIn = async (ctx: { open: (url: string) => void }) => {
       ctx.open('https://acme.example/sign-in')

From 278c5ec60bce7382074e75afaa7a76d94398734c Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 09:22:52 +0200
Subject: [PATCH 070/286] docs: refresh updatedAt for the provider keys and
 coding agent pages

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 docs/config.json | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/config.json b/docs/config.json
index 5b27976156..ab70ce48d6 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -905,12 +905,13 @@
           "label": "Build a coding agent",
           "to": "harness/coding-agent",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-09-28"
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "Connect model providers",
           "to": "harness/provider-keys",
-          "addedAt": "2026-09-29"
+          "addedAt": "2026-09-29",
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "Auth and connectors",

From fd49987a07445b4abf3fcd08912e3bdbe723a2ac Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 11:17:08 +0200
Subject: [PATCH 071/286] fix(ai-harness, ai-mcp): Linear sign-in;
 feat(examples/harness-cli): markdown, charts, real models, /effort

Connect fixes:
- startLoopbackReceiver().waitForCode() resolves { code, iss }, and
  mcpConnector passes iss to the MCP SDK. Linear sends iss (RFC 9207), and
  without it the SDK refused the code with "Issuer mismatch".
- A sign-in error names the service ("Notion: Sign-in timed out.").
- The session view clears a connector's pending sign-in when its
  connect:<id> command ends.

Example screen:
- Answers render as markdown (marked + marked-terminal). Mermaid blocks
  render as text charts (beautiful-mermaid).
- The input stays at the bottom of the screen. Printed rows measure
  themselves, and empty space fills the rest.
- /model lists real model ids (gpt-6-astra, claude-opus-5-5, grok-4.7,
  openai/gpt-6-astra, and more) with their context size.
- /effort sets the reasoning level of the current model's provider.
- Connect results show in green, and a spinner waits for the browser.
- SDK warnings no longer reach the screen: the console filter now wraps
  the console that Ink installs.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/harness-connect-iss.md             |   8 +
 examples/harness-cli/README.md                |  36 +--
 examples/harness-cli/package.json             |   3 +
 examples/harness-cli/src/effort.ts            |  78 +++++++
 examples/harness-cli/src/harness.ts           | 138 +++++++++---
 examples/harness-cli/src/marked-terminal.d.ts |  10 +
 examples/harness-cli/src/screen/footer.tsx    |   7 +
 examples/harness-cli/src/screen/markdown.ts   |  64 ++++++
 examples/harness-cli/src/screen/parts.tsx     |  33 ++-
 examples/harness-cli/src/screen/status.tsx    |  21 +-
 examples/harness-cli/src/tui.tsx              | 211 ++++++++++++++----
 packages/ai-harness/src/oauth.ts              |  11 +-
 packages/ai-harness/src/view/reduce.ts        |  18 +-
 .../ai-harness/tests/discover-tools.test.ts   |  10 +-
 packages/ai-harness/tests/view-reduce.test.ts |  25 +++
 packages/ai-mcp/src/connector.ts              |  12 +-
 packages/ai-mcp/tests/connector-edges.test.ts |  20 +-
 packages/ai-mcp/tests/connector-helpers.ts    |   8 +-
 packages/ai-mcp/tests/protected-server.ts     |  10 +-
 pnpm-lock.yaml                                | 170 +++++++++++++-
 20 files changed, 772 insertions(+), 121 deletions(-)
 create mode 100644 .changeset/harness-connect-iss.md
 create mode 100644 examples/harness-cli/src/effort.ts
 create mode 100644 examples/harness-cli/src/marked-terminal.d.ts
 create mode 100644 examples/harness-cli/src/screen/markdown.ts

diff --git a/.changeset/harness-connect-iss.md b/.changeset/harness-connect-iss.md
new file mode 100644
index 0000000000..b1078a3245
--- /dev/null
+++ b/.changeset/harness-connect-iss.md
@@ -0,0 +1,8 @@
+---
+'@tanstack/ai-harness': patch
+'@tanstack/ai-mcp': patch
+---
+
+`/connect` now works with MCP servers that send `iss` on the sign-in callback (RFC 9207), such as Linear. `startLoopbackReceiver().waitForCode()` resolves `{ code, iss }`, and `mcpConnector` passes `iss` on to the MCP SDK. A sign-in error names the service, for example `Notion: Sign-in timed out.`
+
+The session view clears the pending sign-in of a connector when its `connect:<id>` command ends.
diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index 1f22446fe0..e1a54627ec 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -10,7 +10,7 @@ From the repo root:
 2. `pnpm build:all` (the example uses the local packages)
 3. `pnpm --filter harness-cli-example start`
 4. Type `/connect` and pick OpenRouter. It signs you in with the browser, with no key to paste.
-5. Type `/model` and pick `openrouter-gpt`.
+5. Type `/model` and pick `openai/gpt-6-astra`.
 
 Now send a message.
 
@@ -25,13 +25,13 @@ You do not need a `.env` file. Type `/connect` and pick a provider from the list
 
 The app saves the key in `~/.tanstack-harness-example/credentials.json`. It shows only the last 4 characters of a key. The footer shows which features are on, and it changes when you connect a provider.
 
-| Provider id  | Adds                                                                         |
-| ------------ | ---------------------------------------------------------------------------- |
-| `openai`     | the `gpt` and `gpt-fast` models, images, speech, Sora video, and voice input |
-| `anthropic`  | the `claude` and `claude-fast` models                                        |
-| `grok`       | the `grok` model, video with Grok Imagine, and voice input                   |
-| `fal`        | songs and sound effects                                                      |
-| `openrouter` | the `openrouter-gpt` and `openrouter-claude` models                          |
+| Provider id  | Adds                                                                                                |
+| ------------ | --------------------------------------------------------------------------------------------------- |
+| `openai`     | `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna`, images, speech, Sora video, and voice input               |
+| `anthropic`  | `claude-opus-5-5`, `claude-fable-5-1`, `claude-sonnet-5`, `claude-haiku-4-5`                        |
+| `grok`       | `grok-4.7`, `grok-4.6`, video with Grok Imagine, and voice input                                    |
+| `fal`        | songs and sound effects                                                                             |
+| `openrouter` | `openai/gpt-6-astra`, `anthropic/claude-opus-5.5`, `google/gemini-3.1-pro-preview`, `x-ai/grok-4.7` |
 
 If a provider has no key, its models and tools stop and tell you which `/connect` to run. If no key is set in the env, `/model demo` answers without a key.
 
@@ -88,23 +88,31 @@ When `claude` and `codex` are on the PATH, the agent can call them. They work in
 
 ## Use Notion and Linear
 
-1. Run `/connect notion`. Approve the consent page that opens in the browser. Do the same with `/connect linear`.
+1. Run `/connect notion`. Approve the consent page that opens in the browser. The screen waits with a spinner, then shows a green `✓ Connected to Notion.` Do the same with `/connect linear`.
 2. Ask: `list the titles of my 3 latest Linear issues`, or `search Notion for the onboarding page`.
 
 - Sign-ins are kept in `~/.tanstack-harness-example/credentials.json`, so you sign in once. `/disconnect notion` deletes one.
 - Code mode is on: read-only tools (file reads, read-only Notion and Linear tools) are functions in one `execute_typescript` program, which runs in a QuickJS isolate.
 
+## Pick the model and the effort
+
+- `/model` opens a list of the models, with the provider and the context size of each. `/model gpt-6-luna` switches at once. The change applies at the next turn.
+- `/effort` sets how hard the model thinks: `default` (the model decides), `low`, `medium`, `high`, or `max`. `claude-haiku-4-5` has no effort setting.
+- The footer shows the model, the effort, how full the context is, the tokens in and out, and the model calls.
+
+## The screen
+
+- Answers show as markdown: lists, tables, and highlighted code. A Mermaid block shows as a chart drawn in text. In demo mode, ask `draw me a chart`.
+- Type `/` for a list of the commands. The arrows move in it, Tab fills the command, and Enter runs it.
+- The up and down arrows go through the lines you sent, also after a restart. They are kept in `~/.tanstack-harness-example/history.json`. Keys are never kept.
+- The input stays at the bottom of the screen. `/help` lists every command.
+
 ## Everything else it shows
 
-- `/model` opens a list of the models with their context size. `/model claude` switches at once. The change applies at the next turn.
-- The footer shows the model, how full its context is, the tokens in and out, and the model calls.
 - `create hello.txt with a short poem`: the agent asks before `write_file`. Type `y`.
 - `/mode plan` makes it read-only. `/todos`, `/usage`, `/compact`.
 - `/goal create a file hello.txt that says hi`: the agent keeps working until the model says the goal is met.
 - Press Esc to stop a long answer. Type while it works to steer it.
-- Type `/` for a list of the commands. The arrows move in it, Tab fills the command, and Enter runs it.
-- The up and down arrows go through the lines you sent, also after a restart. They are kept in `~/.tanstack-harness-example/history.json`. Keys are never kept.
-- `/help` lists every command.
 
 The screen is `src/tui.tsx` and its parts in `src/screen/`, plain example code on `createSessionView`. `src/voice.ts` records and transcribes, and `src/media.ts` has the media agents. Copy them and change them.
 
diff --git a/examples/harness-cli/package.json b/examples/harness-cli/package.json
index f5b3cd8b0c..5007fc9041 100644
--- a/examples/harness-cli/package.json
+++ b/examples/harness-cli/package.json
@@ -28,7 +28,10 @@
     "@tanstack/ai-sandbox": "workspace:*",
     "@tanstack/ai-sandbox-local-process": "workspace:*",
     "@tanstack/react-store": "^0.11.1",
+    "beautiful-mermaid": "^1.1.3",
     "ink": "^7.1.1",
+    "marked": "^15.0.6",
+    "marked-terminal": "^7.3.0",
     "react": "^19.2.3",
     "zod": "^4.2.0"
   },
diff --git a/examples/harness-cli/src/effort.ts b/examples/harness-cli/src/effort.ts
new file mode 100644
index 0000000000..dd57671d45
--- /dev/null
+++ b/examples/harness-cli/src/effort.ts
@@ -0,0 +1,78 @@
+import { configOption, defineCommand, definePlugin } from '@tanstack/ai-harness'
+
+export const EFFORTS = ['default', 'low', 'medium', 'high', 'max'] as const
+type Effort = (typeof EFFORTS)[number]
+
+/**
+ * The model options that ask `provider` to think with `effort`. `max` is the
+ * highest level each provider has. `default` sends nothing: the model decides.
+ */
+function reasoningOptions(provider: string, effort: Effort) {
+  if (effort === 'default') return undefined
+  switch (provider) {
+    case 'anthropic':
+      return { output_config: { effort } }
+    case 'openrouter':
+      return { reasoning: { effort: effort === 'max' ? 'xhigh' : effort } }
+    case 'openai':
+    case 'grok':
+      return { reasoning: { effort: effort === 'max' ? 'high' : effort } }
+    default:
+      return undefined
+  }
+}
+
+/**
+ * `/effort`: how hard the main model thinks at the next turn. It sets the
+ * reasoning option of the current model's provider, for models where
+ * `providerOf` gives a provider (a model without reasoning gives none).
+ */
+export function effortPicker(options: {
+  providerOf: (model: string) => string | undefined
+}) {
+  return definePlugin({
+    name: 'example/effort',
+    setup: (ctx) => {
+      const current = (): Effort =>
+        EFFORTS.find((effort) => effort === ctx.config.get('effort')) ??
+        'default'
+      return {
+        config: {
+          effort: configOption.select({
+            options: EFFORTS,
+            default: 'default',
+            category: 'thought_level',
+            description: 'How hard the model thinks',
+          }),
+        },
+        middleware: [
+          {
+            name: 'example/effort',
+            onConfig: (_chat, config) => {
+              const provider = options.providerOf(
+                String(ctx.config.get('model')),
+              )
+              const extra = provider && reasoningOptions(provider, current())
+              if (!extra) return undefined
+              return { modelOptions: { ...config.modelOptions, ...extra } }
+            },
+          },
+        ],
+        commands: {
+          effort: defineCommand({
+            description: `Show or set how hard the model thinks (${EFFORTS.join(', ')})`,
+            run: async (input: unknown) => {
+              const name = typeof input === 'string' ? input.trim() : ''
+              if (name === '') return `Effort: ${current()}.`
+              const effort = EFFORTS.find((item) => item === name)
+              if (!effort)
+                return `Unknown effort "${name}". Choices: ${EFFORTS.join(', ')}.`
+              await ctx.session.setConfig('effort', effort)
+              return `Effort: ${effort}. It applies at the next turn.`
+            },
+          }),
+        },
+      }
+    },
+  })
+}
diff --git a/examples/harness-cli/src/harness.ts b/examples/harness-cli/src/harness.ts
index b6733b6a82..c8323cceef 100644
--- a/examples/harness-cli/src/harness.ts
+++ b/examples/harness-cli/src/harness.ts
@@ -46,6 +46,7 @@ import {
   speechAgent,
   videoAgent,
 } from './media'
+import { effortPicker } from './effort'
 import { envKey } from './store'
 import type { AnyTextAdapter, KeyedAdapter } from '@tanstack/ai'
 import type { ByokProvider, ProviderId } from '@tanstack/ai/byok'
@@ -53,6 +54,24 @@ import type { ByokProvider, ProviderId } from '@tanstack/ai/byok'
 // The agent works in ./playground, so it cannot touch the rest of your disk.
 const root = fileURLToPath(new URL('../playground', import.meta.url))
 
+/**
+ * The demo model's answer, in markdown, so the screen shows how it renders
+ * markdown. Ask it for a chart, and it draws one in Mermaid.
+ */
+function demoReply(said: string) {
+  const chart = /chart|mermaid|diagram/i.test(said)
+    ? '\n\n```mermaid\ngraph LR\n  You --> Harness --> Model\n  Harness --> Tools\n```'
+    : ''
+  return (
+    [
+      `**(demo model)** You said: "${said}".`,
+      '',
+      '- Type `/connect` to connect a provider.',
+      '- Type `/model` to pick a real model.',
+    ].join('\n') + chart
+  )
+}
+
 /** Without any model key, a stand-in model that explains how to add one. */
 function demoModel(): AnyTextAdapter {
   let calls = 0
@@ -97,7 +116,7 @@ function demoModel(): AnyTextAdapter {
         yield {
           type: EventType.TEXT_MESSAGE_CONTENT,
           messageId,
-          delta: `(demo model) You said: "${said}". Type /connect to connect a provider, then /model to pick a real model.`,
+          delta: demoReply(said),
           timestamp: now,
         }
         yield { type: EventType.TEXT_MESSAGE_END, messageId, timestamp: now }
@@ -126,58 +145,105 @@ function hasEnvKey(provider: ByokProvider | ProviderId) {
   return typeof provider !== 'string' && envKey(provider) !== null
 }
 
+const openai = (model: Parameters<typeof createOpenaiChat>[0]) =>
+  keyedAdapter(openaiByok, (key) => createOpenaiChat(model, key))
+const anthropic = (model: Parameters<typeof createAnthropicChat>[0]) =>
+  keyedAdapter(anthropicByok, (key) => createAnthropicChat(model, key))
+const grok = (model: Parameters<typeof createGrokText>[0]) =>
+  keyedAdapter(grokByok, (key) => createGrokText(model, key))
+const openrouter = (model: Parameters<typeof createOpenRouterText>[0]) =>
+  keyedAdapter(openrouterByok, (key) => createOpenRouterText(model, key))
+
 /**
- * The models `/model <name>` can switch to. Each one is built for each turn
- * with the user's own key: the key saved with `/connect <provider>`, else the
- * env var. A model without a key asks the user to connect.
+ * The models `/model <name>` can switch to, by their real model id. Each one
+ * is built for each turn with the user's own key: the key saved with
+ * `/connect <provider>`, else the env var. A model without a key asks the
+ * user to connect.
  */
 const models = {
-  gpt: keyedAdapter(openaiByok, (key) => createOpenaiChat('gpt-6-astra', key)),
-  'gpt-fast': keyedAdapter(openaiByok, (key) =>
-    createOpenaiChat('gpt-6-luna', key),
-  ),
-  claude: keyedAdapter(anthropicByok, (key) =>
-    createAnthropicChat('claude-opus-5-5', key),
-  ),
-  'claude-fast': keyedAdapter(anthropicByok, (key) =>
-    createAnthropicChat('claude-sonnet-5', key),
-  ),
-  grok: keyedAdapter(grokByok, (key) => createGrokText('grok-4.7', key)),
-  'openrouter-gpt': keyedAdapter(openrouterByok, (key) =>
-    createOpenRouterText('openai/gpt-6-astra', key),
-  ),
-  'openrouter-claude': keyedAdapter(openrouterByok, (key) =>
-    createOpenRouterText('anthropic/claude-opus-5.5', key),
-  ),
+  'gpt-6-astra': openai('gpt-6-astra'),
+  'gpt-6-sol': openai('gpt-6-sol'),
+  'gpt-6-luna': openai('gpt-6-luna'),
+  'claude-opus-5-5': anthropic('claude-opus-5-5'),
+  'claude-fable-5-1': anthropic('claude-fable-5-1'),
+  'claude-sonnet-5': anthropic('claude-sonnet-5'),
+  'claude-haiku-4-5': anthropic('claude-haiku-4-5'),
+  'grok-4.7': grok('grok-4.7'),
+  'grok-4.6': grok('grok-4.6'),
+  'openai/gpt-6-astra': openrouter('openai/gpt-6-astra'),
+  'anthropic/claude-opus-5.5': openrouter('anthropic/claude-opus-5.5'),
+  'google/gemini-3.1-pro-preview': openrouter('google/gemini-3.1-pro-preview'),
+  'x-ai/grok-4.7': openrouter('x-ai/grok-4.7'),
 }
 
 // The first model with an env key starts, so a `.env` works as before. The
-// saved keys belong to a session, so without an env key `gpt` starts, and
-// the first message asks the user to run /connect openai.
+// saved keys belong to a session, so without an env key `gpt-6-astra`
+// starts, and the first message asks the user to run /connect.
 const envModel = Object.entries(models).find(([, model]) =>
   hasEnvKey(model.provider),
 )
-const startModel = envModel?.[0] ?? 'gpt'
+const startModel = envModel?.[0] ?? 'gpt-6-astra'
 // Any of the models: the harness, /compact, and /goal take this common type.
-const main: KeyedAdapter<AnyTextAdapter> = envModel?.[1] ?? models.gpt
+const main: KeyedAdapter<AnyTextAdapter> =
+  envModel?.[1] ?? models['gpt-6-astra']
 // With no env key at all, `/model demo` answers without a key.
 const choices = { ...models, ...(envModel ? {} : { demo: demoModel() }) }
 
 /**
  * What the screen shows for each model: the provider that must be connected,
- * and the size of its context window (from each provider's model-meta).
+ * the size of its context window (from each provider's model-meta), and
+ * whether `/effort` can set how hard it thinks.
  */
 export const modelInfo: Record<
   string,
-  { provider: string; contextWindow: number }
+  { provider: string; contextWindow: number; effort: boolean }
 > = {
-  gpt: { provider: 'openai', contextWindow: 1_050_000 },
-  'gpt-fast': { provider: 'openai', contextWindow: 1_050_000 },
-  claude: { provider: 'anthropic', contextWindow: 1_000_000 },
-  'claude-fast': { provider: 'anthropic', contextWindow: 1_000_000 },
-  grok: { provider: 'grok', contextWindow: 500_000 },
-  'openrouter-gpt': { provider: 'openrouter', contextWindow: 1_050_000 },
-  'openrouter-claude': { provider: 'openrouter', contextWindow: 1_000_000 },
+  'gpt-6-astra': { provider: 'openai', contextWindow: 1_050_000, effort: true },
+  'gpt-6-sol': { provider: 'openai', contextWindow: 1_050_000, effort: true },
+  'gpt-6-luna': { provider: 'openai', contextWindow: 1_050_000, effort: true },
+  'claude-opus-5-5': {
+    provider: 'anthropic',
+    contextWindow: 1_000_000,
+    effort: true,
+  },
+  'claude-fable-5-1': {
+    provider: 'anthropic',
+    contextWindow: 1_000_000,
+    effort: true,
+  },
+  'claude-sonnet-5': {
+    provider: 'anthropic',
+    contextWindow: 1_000_000,
+    effort: true,
+  },
+  // Haiku has no effort setting (output_config) in its model-meta.
+  'claude-haiku-4-5': {
+    provider: 'anthropic',
+    contextWindow: 200_000,
+    effort: false,
+  },
+  'grok-4.7': { provider: 'grok', contextWindow: 500_000, effort: true },
+  'grok-4.6': { provider: 'grok', contextWindow: 500_000, effort: true },
+  'openai/gpt-6-astra': {
+    provider: 'openrouter',
+    contextWindow: 1_050_000,
+    effort: true,
+  },
+  'anthropic/claude-opus-5.5': {
+    provider: 'openrouter',
+    contextWindow: 1_000_000,
+    effort: true,
+  },
+  'google/gemini-3.1-pro-preview': {
+    provider: 'openrouter',
+    contextWindow: 1_048_576,
+    effort: true,
+  },
+  'x-ai/grok-4.7': {
+    provider: 'openrouter',
+    contextWindow: 500_000,
+    effort: true,
+  },
 }
 
 // `/connect openrouter` signs in with the browser: no key to paste, and one
@@ -411,6 +477,10 @@ export const assistant = defineHarness({
     todos(),
     providerKeys({ providers: keyProviders }),
     modelPicker({ choices, default: startModel }),
+    effortPicker({
+      providerOf: (model) =>
+        modelInfo[model]?.effort ? modelInfo[model].provider : undefined,
+    }),
     projectInstructions({ root }),
     compact({ adapter: main }),
     usage(),
diff --git a/examples/harness-cli/src/marked-terminal.d.ts b/examples/harness-cli/src/marked-terminal.d.ts
new file mode 100644
index 0000000000..aa3a2469a8
--- /dev/null
+++ b/examples/harness-cli/src/marked-terminal.d.ts
@@ -0,0 +1,10 @@
+// marked-terminal has no types of its own. This is the one function the
+// screen uses.
+declare module 'marked-terminal' {
+  import type { MarkedExtension } from 'marked'
+
+  export function markedTerminal(
+    options?: Record<string, unknown>,
+    highlightOptions?: Record<string, unknown>,
+  ): MarkedExtension
+}
diff --git a/examples/harness-cli/src/screen/footer.tsx b/examples/harness-cli/src/screen/footer.tsx
index f4448517a7..574933a9a2 100644
--- a/examples/harness-cli/src/screen/footer.tsx
+++ b/examples/harness-cli/src/screen/footer.tsx
@@ -16,6 +16,10 @@ export function Footer({ view }: { view: SessionView }) {
   const model = useSelector(view.store, (state) =>
     String(state.config.find((entry) => entry.key === 'model')?.value ?? '?'),
   )
+  const effort = useSelector(
+    view.store,
+    (state) => state.config.find((entry) => entry.key === 'effort')?.value,
+  )
   // The plugin states themselves, so the bar renders only when they change.
   const usageState = useSelector(view.store, (state) => state.plugins[USAGE])
   const keysState = useSelector(
@@ -39,6 +43,9 @@ export function Footer({ view }: { view: SessionView }) {
         {needsKey ? (
           <Text color="red">{`  (run /connect ${info.provider})`}</Text>
         ) : null}
+        {typeof effort === 'string' && effort !== 'default' ? (
+          <Text dimColor>{`  effort ${effort}`}</Text>
+        ) : null}
         <Text dimColor>{'   context '}</Text>
         <Text>
           {compact(usage.contextTokens)}
diff --git a/examples/harness-cli/src/screen/markdown.ts b/examples/harness-cli/src/screen/markdown.ts
new file mode 100644
index 0000000000..dbc0772205
--- /dev/null
+++ b/examples/harness-cli/src/screen/markdown.ts
@@ -0,0 +1,64 @@
+import { renderMermaidASCII } from 'beautiful-mermaid'
+import { Marked } from 'marked'
+import { markedTerminal } from 'marked-terminal'
+
+// A closed ```mermaid block. An open one (still streaming) stays code.
+const MERMAID = /```mermaid[^\n]*\n([\s\S]*?)```/g
+
+// One parser for each width: marked-terminal wraps text to the width.
+const parsers = new Map<number, Marked>()
+function parserFor(width: number) {
+  let parser = parsers.get(width)
+  if (!parser) {
+    parser = new Marked(
+      markedTerminal({
+        width,
+        reflowText: true,
+        tab: 2,
+        emoji: false,
+        showSectionPrefix: false,
+      }),
+      {
+        renderer: {
+          // ponytail: marked-terminal 7 prints the text of a list item as it
+          // is, so `**bold**` in a list stays raw. This parses it.
+          text(token) {
+            return 'tokens' in token && token.tokens
+              ? this.parser.parseInline(token.tokens)
+              : token.text
+          },
+        },
+      },
+    )
+    parsers.set(width, parser)
+  }
+  return parser
+}
+
+/**
+ * Markdown as terminal text, `width` columns wide: headings, lists, tables,
+ * links, and highlighted code. A Mermaid block becomes a chart drawn in text.
+ * A chart that does not parse stays a code block.
+ */
+export function renderMarkdown(text: string, width: number) {
+  const charts: Array<string> = []
+  const source = text.replace(MERMAID, (block, code: string) => {
+    try {
+      charts.push(renderMermaidASCII(code))
+      // A plain word marked-terminal keeps as it is, in its own paragraph.
+      return `\n\nMERMAIDCHART${charts.length - 1}\n\n`
+    } catch {
+      return block
+    }
+  })
+  return (
+    parserFor(Math.max(20, width))
+      // An open (still streaming) Mermaid block shows as plain code.
+      .parse(source.replace(/```mermaid/g, '```'), { async: false })
+      .replace(
+        /MERMAIDCHART(\d+)/g,
+        (_match, index: string) => charts[Number(index)] ?? '',
+      )
+      .trimEnd()
+  )
+}
diff --git a/examples/harness-cli/src/screen/parts.tsx b/examples/harness-cli/src/screen/parts.tsx
index fff1b30494..7c805be797 100644
--- a/examples/harness-cli/src/screen/parts.tsx
+++ b/examples/harness-cli/src/screen/parts.tsx
@@ -1,5 +1,7 @@
 import { basename } from 'node:path'
+import { useMemo } from 'react'
 import { Box, Spacer, Text, useAnimation } from 'ink'
+import { renderMarkdown } from './markdown'
 import { ACCENT, KIND_COLOR, SPINNER } from './theme'
 import type {
   AgentPart,
@@ -148,20 +150,28 @@ function Agent({
   )
 }
 
+/** The model's text as markdown, `width` columns wide. */
+function Markdown({ text, width }: { text: string; width: number }) {
+  const shown = useMemo(() => renderMarkdown(text, width), [text, width])
+  return (
+    <Box marginLeft={2}>
+      <Text>{shown}</Text>
+    </Box>
+  )
+}
+
 function Part({
   part,
   saved,
+  width,
 }: {
   part: ViewPart
   saved: ReadonlyArray<Saved>
+  width: number
 }) {
   switch (part.type) {
     case 'text':
-      return (
-        <Box marginLeft={2}>
-          <Text>{part.text}</Text>
-        </Box>
-      )
+      return <Markdown text={part.text} width={width - 2} />
     case 'reasoning':
       return (
         <Box marginLeft={2}>
@@ -182,9 +192,12 @@ function Part({
 export function Message({
   message,
   saved,
+  width,
 }: {
   message: ViewMessage
   saved: ReadonlyArray<Saved>
+  /** The terminal width, for the markdown of the model's text. */
+  width: number
 }) {
   switch (message.role) {
     case 'user': {
@@ -217,10 +230,14 @@ export function Message({
     }
     case 'notice': {
       const isError = message.kind === 'error'
+      // A command's answer, for example "Connected to Notion.", stands out.
+      const done =
+        message.kind === 'command' &&
+        /^(Connected|Disconnected|Model|Effort)\b/.test(message.text)
       return (
         <Box marginLeft={2}>
-          <Text color={isError ? 'red' : 'gray'}>
-            {`${isError ? '✗' : '·'} ${message.text}`}
+          <Text color={isError ? 'red' : done ? 'green' : 'gray'} bold={done}>
+            {`${isError ? '✗' : done ? '✓' : '·'} ${message.text}`}
           </Text>
         </Box>
       )
@@ -229,7 +246,7 @@ export function Message({
       return (
         <Box flexDirection="column" marginTop={1}>
           {message.parts.map((part, index) => (
-            <Part key={index} part={part} saved={saved} />
+            <Part key={index} part={part} saved={saved} width={width} />
           ))}
         </Box>
       )
diff --git a/examples/harness-cli/src/screen/status.tsx b/examples/harness-cli/src/screen/status.tsx
index a823afe68f..cd2fca880b 100644
--- a/examples/harness-cli/src/screen/status.tsx
+++ b/examples/harness-cli/src/screen/status.tsx
@@ -45,11 +45,22 @@ export function Status({
   const goal = useSelector(view.store, selectGoal)
   return (
     <Box flexDirection="column" marginTop={1}>
-      {signIns.map((signIn) => (
-        <Text key={signIn.connector} color="magenta">
-          {`◇ Continue in your browser for ${signIn.connector}${signIn.url ? `: ${signIn.url}` : ''}${signIn.userCode ? ` (code ${signIn.userCode})` : ''}`}
-        </Text>
-      ))}
+      {/* A key question says itself that the page is open, so it waits alone. */}
+      {question
+        ? null
+        : signIns.map((signIn) => (
+            <Box key={signIn.connector} flexDirection="column">
+              <Box>
+                <Spinner color="magenta" />
+                <Text color="magenta">
+                  {` Waiting for you to sign in to ${signIn.connector} in your browser${signIn.userCode ? ` (code ${signIn.userCode})` : ''}.`}
+                </Text>
+              </Box>
+              {signIn.url ? (
+                <Text dimColor>{`  No tab opened? Open ${signIn.url}`}</Text>
+              ) : null}
+            </Box>
+          ))}
       {approvals.length > 0 ? (
         <Text color="magenta" bold>
           {`◇ Approve ${approvals.map((item) => item.tool).join(', ')}? Type y or n.`}
diff --git a/examples/harness-cli/src/tui.tsx b/examples/harness-cli/src/tui.tsx
index 7e645562f4..96e8477164 100644
--- a/examples/harness-cli/src/tui.tsx
+++ b/examples/harness-cli/src/tui.tsx
@@ -1,8 +1,19 @@
 import { readFile } from 'node:fs/promises'
 import { basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { useEffect, useRef, useState } from 'react'
-import { Box, Static, Text, render, useApp, useInput, usePaste } from 'ink'
+import { useEffect, useLayoutEffect, useReducer, useRef, useState } from 'react'
+import {
+  Box,
+  Static,
+  Text,
+  measureElement,
+  render,
+  useApp,
+  useBoxMetrics,
+  useInput,
+  usePaste,
+  useWindowSize,
+} from 'ink'
 import { useSelector } from '@tanstack/react-store'
 import { assistant, features, keyProviders, modelInfo } from './harness'
 import {
@@ -23,7 +34,8 @@ import { Menu } from './screen/menu'
 import { Message, settledCount } from './screen/parts'
 import { Status } from './screen/status'
 import { ACCENT, compact } from './screen/theme'
-import type { RenderOptions } from 'ink'
+import type { ReactNode } from 'react'
+import type { DOMElement, RenderOptions } from 'ink'
 import type { Recording, VoiceClip } from './voice'
 import type { Line } from './screen/editor'
 import type { MenuItem } from './screen/menu'
@@ -45,6 +57,7 @@ const SCREEN_COMMANDS = [
   },
   { name: 'disconnect', description: 'Remove a key or a sign-in' },
   { name: 'model', description: 'Pick the model' },
+  { name: 'effort', description: 'Pick how hard the model thinks' },
   { name: 'mic', description: 'Pick the microphone' },
   { name: 'open', description: 'Open a media file (default: the last one)' },
   { name: 'play', description: 'Play an audio or video file' },
@@ -150,6 +163,30 @@ function modelItems(state: SessionViewState): Array<MenuItem> {
   })
 }
 
+const EFFORT_DETAIL: Record<string, string> = {
+  default: 'the model decides',
+  low: 'fastest, fewest tokens',
+  medium: 'balanced',
+  high: 'thinks longer',
+  max: 'the most the model can think',
+}
+
+/** The rows of the `/effort` picker, for the current model. */
+function effortItems(state: SessionViewState): Array<MenuItem> {
+  const entry = state.config.find((item) => item.key === 'effort')
+  if (entry?.option.type !== 'select') return []
+  const model = String(
+    state.config.find((item) => item.key === 'model')?.value ?? '',
+  )
+  const used = modelInfo[model]?.effort === true
+  return entry.option.options.map((name) => ({
+    id: name,
+    label: name,
+    current: name === entry.value,
+    detail: `${EFFORT_DETAIL[name] ?? ''}${used || name === 'default' ? '' : `, ${model} has no effort setting`}`,
+  }))
+}
+
 /** A list open over the input line, for example the `/connect` picker. */
 interface Picker {
   title: string
@@ -227,6 +264,45 @@ const RELEASE_WAIT = 450
 
 type Row = { id: 'header' } | ViewMessage
 
+/** Reports its height once, when Ink prints it (Static prints a row once). */
+function Measured({
+  id,
+  onHeight,
+  children,
+}: {
+  id: string
+  onHeight: (id: string, height: number) => void
+  children: ReactNode
+}) {
+  const ref = useRef<DOMElement>(null)
+  // Ink lays out the frame before layout effects run, so the height is there.
+  useLayoutEffect(() => {
+    if (ref.current) onHeight(id, measureElement(ref.current).height)
+  }, [])
+  return (
+    <Box ref={ref} flexDirection="column">
+      {children}
+    </Box>
+  )
+}
+
+/** One printed row: the header, or a message that no longer changes. */
+function PrintedRow({
+  row,
+  saved,
+  width,
+}: {
+  row: Row
+  saved: ReturnType<typeof useSavedMedia>['saved']
+  width: number
+}) {
+  return 'role' in row ? (
+    <Message message={row} saved={saved} width={width} />
+  ) : (
+    <Header />
+  )
+}
+
 function App({ view }: { view: SessionView }) {
   const { exit } = useApp()
   const messages = useSelector(view.store, (state) => state.messages)
@@ -268,6 +344,27 @@ function App({ view }: { view: SessionView }) {
     ...messages.slice(0, printed.current),
   ]
 
+  // The input sits at the bottom of the screen: until the printed rows fill
+  // the screen, empty space above the live area fills the rest. Each row
+  // measures itself when it prints. Ink redraws the whole screen for a frame
+  // as tall as the screen, so the frame stays one line shorter.
+  // ponytail: the heights are from the width at print time. A resize makes
+  // the space a little off until the screen is full.
+  const { columns, rows: screenRows } = useWindowSize()
+  const heights = useRef(new Map<string, number>())
+  const [, remeasure] = useReducer((count: number) => count + 1, 0)
+  const onHeight = (id: string, height: number) => {
+    heights.current.set(id, height)
+    remeasure()
+  }
+  const printedHeight = rows.reduce(
+    (sum, row) => sum + (heights.current.get(row.id) ?? 0),
+    0,
+  )
+  const live = useRef<DOMElement>(null)
+  const { height: liveHeight } = useBoxMetrics(live)
+  const space = Math.max(0, screenRows - 1 - printedHeight - liveHeight)
+
   const [voice, setVoiceState] = useState<VoiceState>('idle')
   // The phase in a ref too: key events come faster than React renders, and a
   // second Ctrl+R must see "starting" at once, or it starts a second recorder.
@@ -515,6 +612,13 @@ function App({ view }: { view: SessionView }) {
           items: modelItems(state),
           pick: (item) => view.command('model', item.id),
         })
+      case '/effort':
+        if (arg) break
+        return openPicker({
+          title: 'How hard should the model think?',
+          items: effortItems(state),
+          pick: (item) => view.command('effort', item.id),
+        })
       case '/mic': {
         if (!arg) return pickMicrophone().catch(failVoice)
         const names = await listMicrophones().catch(() => [])
@@ -621,38 +725,46 @@ function App({ view }: { view: SessionView }) {
   return (
     <Box flexDirection="column">
       <Static items={rows}>
-        {(row) =>
-          'role' in row ? (
-            <Message key={row.id} message={row} saved={saved} />
-          ) : (
-            <Header key={row.id} />
-          )
-        }
+        {(row) => (
+          <Measured key={row.id} id={row.id} onHeight={onHeight}>
+            <PrintedRow row={row} saved={saved} width={columns} />
+          </Measured>
+        )}
       </Static>
-      {messages.slice(printed.current).map((message) => (
-        <Message key={message.id} message={message} saved={saved} />
-      ))}
-      <Status view={view} voice={voice} recording={recorder} />
-      <InputBox
-        line={editor.line}
-        voice={voice}
-        hidden={secretAsked || (editor.line.hidden && editor.line.text !== '')}
-      />
-      {picker ? (
-        <Menu
-          title={picker.title}
-          items={picker.items}
-          selected={selected}
-          hint="↑↓ move   Enter or a number picks   Esc closes"
+      {space > 0 ? <Box height={space} /> : null}
+      <Box ref={live} flexDirection="column">
+        {messages.slice(printed.current).map((message) => (
+          <Message
+            key={message.id}
+            message={message}
+            saved={saved}
+            width={columns}
+          />
+        ))}
+        <Status view={view} voice={voice} recording={recorder} />
+        <InputBox
+          line={editor.line}
+          voice={voice}
+          hidden={
+            secretAsked || (editor.line.hidden && editor.line.text !== '')
+          }
         />
-      ) : suggestions.length > 0 ? (
-        <Menu
-          items={suggestions}
-          selected={Math.min(suggested, suggestions.length - 1)}
-          hint="↑↓ move   Tab fills   Enter runs"
-        />
-      ) : null}
-      <Footer view={view} />
+        {picker ? (
+          <Menu
+            title={picker.title}
+            items={picker.items}
+            selected={selected}
+            hint="↑↓ move   Enter or a number picks   Esc closes"
+          />
+        ) : suggestions.length > 0 ? (
+          <Menu
+            items={suggestions}
+            selected={Math.min(suggested, suggestions.length - 1)}
+            hint="↑↓ move   Tab fills   Enter runs"
+          />
+        ) : null}
+        <Footer view={view} />
+      </Box>
     </Box>
   )
 }
@@ -672,30 +784,37 @@ export async function runTui(view: SessionView, io: RenderOptions = {}) {
     view.notice(
       'No model key yet. Type /connect and pick OpenRouter to sign in with the browser.',
     )
-  // ponytail: the SDK logs its warnings and errors on the console (the message,
-  // then its details with console.dir). Ink prints console output above the
-  // screen, and the screen shows those errors itself, so it drops them.
-  const { warn, error, dir } = console
+  // Start on a clean terminal: clear the screen and the scrollback.
+  if (!io.stdout && process.stdout.isTTY)
+    process.stdout.write('\x1b[2J\x1b[3J\x1b[H')
+  const app = render(<App view={view} />, io)
+  // ponytail: the SDK logs its warnings and errors on the console (the
+  // message, then its details with console.dir), and the code highlighter
+  // warns about languages it does not know. Ink prints console output above
+  // the screen, and the screen shows the errors itself, so it drops them.
+  // This wraps the console after render(), because render() replaces it.
+  const before = { warn: console.warn, error: console.error, dir: console.dir }
   let dropDetails = false
   const quiet =
     (log: (...args: Array<unknown>) => void) =>
     (...args: Array<unknown>) => {
       const text = typeof args[0] === 'string' ? args[0] : ''
-      dropDetails = /\[tanstack-ai:(warn|errors)\]/.test(text)
+      dropDetails =
+        /\[tanstack-ai:(warn|errors)\]|Could not find the language/.test(text)
       if (!dropDetails) log(...args)
     }
-  console.warn = quiet(warn)
-  console.error = quiet(error)
+  const quietWarn = quiet(before.warn)
+  console.warn = quietWarn
+  console.error = quiet(before.error)
   console.dir = (...args: Parameters<typeof console.dir>) => {
     if (dropDetails) dropDetails = false
-    else dir(...args)
+    else before.dir(...args)
   }
-  // Start on a clean terminal: clear the screen and the scrollback.
-  if (!io.stdout && process.stdout.isTTY)
-    process.stdout.write('\x1b[2J\x1b[3J\x1b[H')
   try {
-    await render(<App view={view} />, io).waitUntilExit()
+    await app.waitUntilExit()
   } finally {
-    Object.assign(console, { warn, error, dir })
+    // Ink puts the first console back when it stops. Without its console
+    // (`patchConsole: false`), the screen puts it back itself.
+    if (console.warn === quietWarn) Object.assign(console, before)
   }
 }
diff --git a/packages/ai-harness/src/oauth.ts b/packages/ai-harness/src/oauth.ts
index 446ce1590d..9e3a1b2492 100644
--- a/packages/ai-harness/src/oauth.ts
+++ b/packages/ai-harness/src/oauth.ts
@@ -164,12 +164,16 @@ const DONE_PAGE =
  * 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<string>
+  waitForCode: (state: string) => Promise<{ code: string; iss?: string }>
   close: () => void
 }> {
   const { createServer } = await import('node:http')
@@ -189,7 +193,7 @@ export async function startLoopbackReceiver(
     redirectUri,
     close,
     waitForCode: (state) =>
-      new Promise<string>((resolve, reject) => {
+      new Promise((resolve, reject) => {
         const timer = setTimeout(
           () => {
             close()
@@ -207,6 +211,7 @@ export async function startLoopbackReceiver(
           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) {
@@ -215,7 +220,7 @@ export async function startLoopbackReceiver(
                 `Sign-in failed: ${url.searchParams.get('error') ?? 'no code'}`,
               ),
             )
-          } else resolve(code)
+          } else resolve(iss ? { code, iss } : { code })
         })
       }),
   }
diff --git a/packages/ai-harness/src/view/reduce.ts b/packages/ai-harness/src/view/reduce.ts
index e7f00225a8..d5fd857346 100644
--- a/packages/ai-harness/src/view/reduce.ts
+++ b/packages/ai-harness/src/view/reduce.ts
@@ -448,10 +448,22 @@ export function applyEvent(
       : state
   if (event.name === HARNESS_EVENTS.operationResumed)
     return withNotice(state, 'info', 'Resumed a turn that a crash stopped.')
-  if (event.name === COMMAND_RESULT)
-    return typeof value.result === 'string' && value.result !== ''
-      ? withNotice(state, 'command', value.result)
+  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,
diff --git a/packages/ai-harness/tests/discover-tools.test.ts b/packages/ai-harness/tests/discover-tools.test.ts
index 1e7653645d..34d7966de8 100644
--- a/packages/ai-harness/tests/discover-tools.test.ts
+++ b/packages/ai-harness/tests/discover-tools.test.ts
@@ -127,7 +127,15 @@ describe('startLoopbackReceiver', () => {
     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).toBe('abc')
+    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 () => {
diff --git a/packages/ai-harness/tests/view-reduce.test.ts b/packages/ai-harness/tests/view-reduce.test.ts
index 0060f46df9..42c6049e6c 100644
--- a/packages/ai-harness/tests/view-reduce.test.ts
+++ b/packages/ai-harness/tests/view-reduce.test.ts
@@ -299,6 +299,31 @@ describe('view reducer', () => {
     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: [],
diff --git a/packages/ai-mcp/src/connector.ts b/packages/ai-mcp/src/connector.ts
index 5a1655cf01..6b7f9f93a1 100644
--- a/packages/ai-mcp/src/connector.ts
+++ b/packages/ai-mcp/src/connector.ts
@@ -284,10 +284,20 @@ export function mcpConnector(options: McpConnectorOptions) {
                 // A new sign-in has no tokens, so this always ends in a
                 // redirect to the browser.
                 await auth(provider, { serverUrl: url, ...fetchFn })
-                const code = await receiver.waitForCode(state)
+                // 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 {
diff --git a/packages/ai-mcp/tests/connector-edges.test.ts b/packages/ai-mcp/tests/connector-edges.test.ts
index c6c5507bbd..637a4bbe5b 100644
--- a/packages/ai-mcp/tests/connector-edges.test.ts
+++ b/packages/ai-mcp/tests/connector-edges.test.ts
@@ -22,8 +22,11 @@ afterEach(async () => {
   for (const cleanup of cleanups.splice(0).reverse()) await cleanup()
 })
 
-async function setup(credential?: Credential) {
-  const server = await startProtectedServer()
+async function setup(
+  credential?: Credential,
+  serverOptions?: Parameters<typeof startProtectedServer>[0],
+) {
+  const server = await startProtectedServer(serverOptions)
   cleanups.push(() => server.close())
   const persistence = memoryPersistence()
   if (credential)
@@ -347,6 +350,19 @@ describe('mcpConnector /connect', () => {
     )
   })
 
+  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, 'demo'),
+    ).toMatchObject({ accessToken: 'access-1' })
+  })
+
   it.each([
     { before: 'no sign-in', earlier: undefined, tools: [], asks: true },
     {
diff --git a/packages/ai-mcp/tests/connector-helpers.ts b/packages/ai-mcp/tests/connector-helpers.ts
index a8c8131197..f330bc787b 100644
--- a/packages/ai-mcp/tests/connector-helpers.ts
+++ b/packages/ai-mcp/tests/connector-helpers.ts
@@ -95,7 +95,12 @@ export function authorizationUrlOf(event: StreamChunk) {
  * 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) {
+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 () => {
@@ -107,6 +112,7 @@ export function approveSignIns(session: HarnessSession, code: string) {
         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') ?? '',
diff --git a/packages/ai-mcp/tests/protected-server.ts b/packages/ai-mcp/tests/protected-server.ts
index f659296f05..a9b4e7ad59 100644
--- a/packages/ai-mcp/tests/protected-server.ts
+++ b/packages/ai-mcp/tests/protected-server.ts
@@ -26,7 +26,12 @@ function webHeaders(req: IncomingMessage) {
  * - 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() {
+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>,
@@ -61,6 +66,9 @@ export async function startProtectedServer() {
           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') {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f201b46dc7..6ea9be042b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -233,9 +233,18 @@ importers:
       '@tanstack/react-store':
         specifier: ^0.11.1
         version: 0.11.1(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      beautiful-mermaid:
+        specifier: ^1.1.3
+        version: 1.1.3
       ink:
         specifier: ^7.1.1
         version: 7.1.1(@types/react@19.3.0)(react-devtools-core@6.1.5)(react@19.2.3)
+      marked:
+        specifier: ^15.0.6
+        version: 15.0.12
+      marked-terminal:
+        specifier: ^7.3.0
+        version: 7.3.0(marked@15.0.12)
       react:
         specifier: ^19.2.3
         version: 19.2.3
@@ -5388,6 +5397,10 @@ packages:
   '@cloudflare/workers-types@4.20260317.1':
     resolution: {integrity: sha512-+G4eVwyCpm8Au1ex8vQBCuA9wnwqetz4tPNRoB/53qvktERWBRMQnrtvC1k584yRE3emMThtuY0gWshvSJ++PQ==}
 
+  '@colors/colors@1.5.0':
+    resolution: {integrity: sha512-ooWCrlZP11i8GImSjTHYHLkvFDP48nS4+204nGb1RiX/WXYHmJA2III9/e2DWVabCESdW7hBAEzHRqUn9OUVvQ==}
+    engines: {node: '>=0.1.90'}
+
   '@connectrpc/connect-web@2.2.0':
     resolution: {integrity: sha512-uuBUcBTYfb/r1o98LzCCZk1H90yx0vmZ5m21dpw/q4EUwsKwkCDGI8H0aEdjcZld+Q2jJ5A5ADvPqfb6lzQ/sg==}
     peerDependencies:
@@ -10348,6 +10361,10 @@ packages:
   '@sinclair/typebox@0.27.10':
     resolution: {integrity: sha512-MTBk/3jGLNB2tVxv6uLlFh1iu64iYOQ2PbdOSK3NW8JZsmlaOh2q6sdtKowBhfw8QFLmYNzTW4/oK4uATIi6ZA==}
 
+  '@sindresorhus/is@4.6.0':
+    resolution: {integrity: sha512-t09vSN3MdfsyCHoFcTRCH/iUtG7OJ0CsjzB8cjAmKc/va/kIgeDI/TxsigdncE/4be734m0cvIYwNaV4i2XqAw==}
+    engines: {node: '>=10'}
+
   '@sindresorhus/is@7.2.0':
     resolution: {integrity: sha512-P1Cz1dWaFfR4IR+U13mqqiGsLFf1KbayybWwdd2vfctdV6hDpUkgCY0nKOLLTMSoRd/jJNjtbqzf13K8DCCXQw==}
     engines: {node: '>=18'}
@@ -12386,6 +12403,9 @@ packages:
     resolution: {integrity: sha512-2Imdcw3LznDuxAbJM26RHniOLAzE6WgrK8OuvVXCQtNBS8rsnD9zsSEa3fHl4hHpUY7BYTlrpvtPVbvu9G6neg==}
     engines: {node: '>=18.0.0'}
 
+  beautiful-mermaid@1.1.3:
+    resolution: {integrity: sha512-TItrtrAyHp1vwFfFVYauWGrquouk/6SS21Aq3RsxindSYZODcN4xYrPZD6BiZRU+o5mKJzDPz9MUSMvELdylyg==}
+
   better-path-resolve@1.0.0:
     resolution: {integrity: sha512-pbnl5XzGBdrFU/wT4jqmJVPn2B6UHPBOhzMQkY/SPUPB6QtUXtmBHBIwCbXJol93mOpGMnQyP/+BB19q04xj7g==}
     engines: {node: '>=4'}
@@ -12605,6 +12625,10 @@ packages:
     resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
     engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
 
+  char-regex@1.0.2:
+    resolution: {integrity: sha512-kWWXztvZ5SBQV+eRgKFeh8q5sLuZY2+8WUIzlxWVTg+oGwY14qylx1KbKzHd8P6ZYkAg0xyIDU9JMHhyJMZ1jw==}
+    engines: {node: '>=10'}
+
   character-entities-html4@2.1.0:
     resolution: {integrity: sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==}
 
@@ -12702,6 +12726,11 @@ packages:
     resolution: {integrity: sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==}
     engines: {node: '>=18'}
 
+  cli-highlight@2.1.11:
+    resolution: {integrity: sha512-9KDcoEVwyUXrjcJNvHD0NFc/hiwe/WPVYIleQh2O1N2Zro5gWJZ/K+3DGn8w8P/F6FxOgzyC5bxDyHIgCSPhGg==}
+    engines: {node: '>=8.0.0', npm: '>=5.0.0'}
+    hasBin: true
+
   cli-spinners@2.6.1:
     resolution: {integrity: sha512-x/5fWmGMnbKQAaNwN+UZlV79qBLM9JFnJuJ03gIi5whrob0xV0ofNVHy9DhwGdsMJQc2OKv0oGmLzvaqvAVv+g==}
     engines: {node: '>=6'}
@@ -12710,6 +12739,10 @@ packages:
     resolution: {integrity: sha512-bXfOC4QcT1tKXGorxL3wbJm6XJPDqEnij2gQ2m7ESQuE+/z9YFIWnl/5RpTiKWbMq3EVKR4fRLJGn6DVfu0mpw==}
     engines: {node: '>=18.20'}
 
+  cli-table3@0.6.5:
+    resolution: {integrity: sha512-+W/5efTR7y5HRD7gACw9yQjqMVvEMLBHmboM/kPWam+H+Hmyrgjh6YncVKK122YZkXrLudzTuAukUw9FnMf7IQ==}
+    engines: {node: 10.* || >= 12.*}
+
   cli-truncate@5.2.0:
     resolution: {integrity: sha512-xRwvIOMGrfOAnM1JYtqQImuaNtDEv9v6oIYAs4LIHwTiKee8uwvIi363igssOC0O5U04i4AlENs79LQLu9tEMw==}
     engines: {node: '>=20'}
@@ -12726,6 +12759,9 @@ packages:
     resolution: {integrity: sha512-5mOlNS0mhX0707P2I0aZ2V/cmHUEO/fL7VFLqszkhUsxt7RwnmrInf/eEQKlf5GzvYeHIjT+Ov1HRfNmymlG0w==}
     engines: {node: '>=18'}
 
+  cliui@7.0.4:
+    resolution: {integrity: sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ==}
+
   cliui@8.0.1:
     resolution: {integrity: sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==}
     engines: {node: '>=12'}
@@ -13498,6 +13534,9 @@ packages:
   emoji-regex@9.2.2:
     resolution: {integrity: sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==}
 
+  emojilib@2.4.0:
+    resolution: {integrity: sha512-5U0rVMU5Y2n2+ykNLQqMoqklN9ICBT/KsvC1Gz6vqHbz2AXXGkG+Pm5rMWk/8Vjrr/mY9985Hi8DYzn1F09Nyw==}
+
   empathic@2.0.0:
     resolution: {integrity: sha512-i6UzDscO/XfAcNYD75CfICkmfLedpyPDdozrLMmQc5ORaQcdMoc21OnlEylMIqI7U8eniKrPMxxtj8k0vhmJhA==}
     engines: {node: '>=14'}
@@ -14446,6 +14485,9 @@ packages:
   hermes-parser@0.35.0:
     resolution: {integrity: sha512-9JLjeHxBx8T4CAsydZR49PNZUaix+WpQJwu9p2010lu+7Kwl6D/7wYFFJxoz+aXkaaClp9Zfg6W6/zVlSJORaA==}
 
+  highlight.js@10.7.3:
+    resolution: {integrity: sha512-tzcUFauisWKNHaRkN4Wjl/ZA07gENAjFl3J/c480dprkGTg5EQstgaNFqBfUqCq54kZRIEcreTsAgF/m2quD7A==}
+
   highlight.js@11.11.1:
     resolution: {integrity: sha512-Xwwo44whKBVCYoliBQwaPvtd/2tYFkRQtXDWj1nackaV2JPXx3L0+Jvd8/qCJ2p+ML0/XVkJ2q+Mr+UVdpJK5w==}
     engines: {node: '>=12.0.0'}
@@ -15534,6 +15576,12 @@ packages:
     peerDependencies:
       marked: '>=4 <18'
 
+  marked-terminal@7.3.0:
+    resolution: {integrity: sha512-t4rBvPsHc57uE/2nJOLmMbZCQ4tgAccAED3ngXQqW6g+TxA488JzJ+FK3lQkzBQOI1mRV/r/Kq+1ZlJ4D0owQw==}
+    engines: {node: '>=16.0.0'}
+    peerDependencies:
+      marked: '>=1 <16'
+
   marked@15.0.12:
     resolution: {integrity: sha512-8dD6FusOQSrpv9Z1rdNMdlSgQOIP880DHqnohobOmYLElGEqAL/JvxvuxZO16r4HtjTlfPRDC1hbvxC9dPN2nA==}
     engines: {node: '>= 18'}
@@ -16062,6 +16110,10 @@ packages:
     engines: {node: '>=10.5.0'}
     deprecated: Use your platform's native DOMException instead
 
+  node-emoji@2.2.0:
+    resolution: {integrity: sha512-Z3lTE9pLaJF47NyMhd4ww1yFTAP8YhYI8SleJiHzM46Fgpm5cnNzSl9XfzFNqbaz+VlJrIj3fXQ4DeN1Rjm6cw==}
+    engines: {node: '>=18'}
+
   node-fetch-native@1.6.7:
     resolution: {integrity: sha512-g9yhqoedzIUm0nTnTqAQvueMPVOuIY16bqgAJJC8XOOubYFNwz6IER9qs0Gq2Xd0+CecCKFjtdDTMA4u4xG06Q==}
 
@@ -16442,6 +16494,9 @@ packages:
   parse5-html-rewriting-stream@8.0.0:
     resolution: {integrity: sha512-wzh11mj8KKkno1pZEu+l2EVeWsuKDfR5KNWZOTsslfUX8lPDZx77m9T0kIoAVkFtD1nx6YF8oh4BnPHvxMtNMw==}
 
+  parse5-htmlparser2-tree-adapter@6.0.1:
+    resolution: {integrity: sha512-qPuWvbLgvDGilKc5BoicRovlT4MtYT6JfJyBOMDsKoiT+GiuP5qyrPCnR9HcPECIJJmZh5jRndyNThnhhb/vlA==}
+
   parse5-htmlparser2-tree-adapter@7.1.0:
     resolution: {integrity: sha512-ruw5xyKs6lrpo9x9rCZqZZnIUntICjQAd0Wsmp396Ul9lN/h+ifgVV1x1gZHi8euej6wTfpqX8j+BFQxF0NS/g==}
 
@@ -16451,6 +16506,12 @@ packages:
   parse5-sax-parser@8.0.0:
     resolution: {integrity: sha512-/dQ8UzHZwnrzs3EvDj6IkKrD/jIZyTlB+8XrHJvcjNgRdmWruNdN9i9RK/JtxakmlUdPwKubKPTCqvbTgzGhrw==}
 
+  parse5@5.1.1:
+    resolution: {integrity: sha512-ugq4DFI0Ptb+WWjAdOK16+u/nHfiIrcE+sh8kZMaM0WllQKLI9rOUq6c2b7cwPkXdzfQESqvoqK6ug7U/Yyzug==}
+
+  parse5@6.0.1:
+    resolution: {integrity: sha512-Ofn/CTFzRGTTxwpNEs9PP93gXShHcTq255nzRYSKe8AkVpZY7e1fpmTfOyoIvjP5HG7Z2ZM7VS9PPhQGW2pOpw==}
+
   parse5@7.3.0:
     resolution: {integrity: sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==}
 
@@ -17561,6 +17622,10 @@ packages:
   sisteransi@1.0.5:
     resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
 
+  skin-tone@2.0.0:
+    resolution: {integrity: sha512-kUMbT1oBJCpgrnKoSr0o6wPtvRWT9W9UKvGLwfJYO2WuahZRHOpEyL1ckyMGgMWh0UdpmaoFqKKD29WTomNEGA==}
+    engines: {node: '>=8'}
+
   slash@3.0.0:
     resolution: {integrity: sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==}
     engines: {node: '>=8'}
@@ -17842,6 +17907,10 @@ packages:
     resolution: {integrity: sha512-RpsAZlpWcDwOPQA22aCH4J0t7L8JmAvsCxfOSEwm7cQs3LshN36QaTkwd70DnBOXDWGssw2eUoc8CaRWT0XunA==}
     engines: {node: '>=8'}
 
+  supports-hyperlinks@3.2.0:
+    resolution: {integrity: sha512-zFObLMyZeEwzAoKCyu1B91U79K2t7ApXuQfo8OuxwXLDgcKxuwM+YvcbIhm6QWqz7mHUH1TVytR1PwVVjEuMig==}
+    engines: {node: '>=14.18'}
+
   supports-preserve-symlinks-flag@1.0.0:
     resolution: {integrity: sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w==}
     engines: {node: '>= 0.4'}
@@ -18295,6 +18364,10 @@ packages:
     resolution: {integrity: sha512-dA8WbNeb2a6oQzAQ55YlT5vQAWGV9WXOsi3SskE3bcCdM0P4SDd+24zS/OCacdRq5BkdsRj9q3Pg6YyQoxIGqg==}
     engines: {node: '>=4'}
 
+  unicode-emoji-modifier-base@1.0.0:
+    resolution: {integrity: sha512-yLSH4py7oFH3oG/9K+XWrz1pSi3dfUrWEnInbxMfArOfc1+33BlGPQtLsOYwvdMy11AwUBetYuaRxSPqgkq+8g==}
+    engines: {node: '>=4'}
+
   unicode-match-property-ecmascript@2.0.0:
     resolution: {integrity: sha512-5kaZCrbp5mmbz5ulBkDkbY0SsPOjKqVS35VpL9ulMPfSl0J0Xsm+9Evphv9CoIZFwre7aJoa94AY6seMKGVN5Q==}
     engines: {node: '>=4'}
@@ -19270,6 +19343,10 @@ packages:
     engines: {node: '>= 14.6'}
     hasBin: true
 
+  yargs-parser@20.2.9:
+    resolution: {integrity: sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w==}
+    engines: {node: '>=10'}
+
   yargs-parser@21.1.1:
     resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==}
     engines: {node: '>=12'}
@@ -19278,6 +19355,10 @@ packages:
     resolution: {integrity: sha512-rwu/ClNdSMpkSrUb+d6BRsSkLUq1fmfsY6TOpYzTwvwkg1/NRG85KBy3kq++A8LKQwX6lsu+aWad+2khvuXrqw==}
     engines: {node: ^20.19.0 || ^22.12.0 || >=23}
 
+  yargs@16.2.2:
+    resolution: {integrity: sha512-Nt9ZJjXTv5R8MHbqby/wXQ6Gi0Bb3TcYZkR1bzuL4yB2OxWPkXknz513gEF0GoA6tn00UpbPvERW8rzCuWCA6w==}
+    engines: {node: '>=10'}
+
   yargs@17.7.2:
     resolution: {integrity: sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==}
     engines: {node: '>=12'}
@@ -21611,6 +21692,9 @@ snapshots:
 
   '@cloudflare/workers-types@4.20260317.1': {}
 
+  '@colors/colors@1.5.0':
+    optional: true
+
   '@connectrpc/connect-web@2.2.0(@bufbuild/protobuf@2.15.0)(@connectrpc/connect@2.2.0(@bufbuild/protobuf@2.15.0))':
     dependencies:
       '@bufbuild/protobuf': 2.15.0
@@ -27075,6 +27159,8 @@ snapshots:
 
   '@sinclair/typebox@0.27.10': {}
 
+  '@sindresorhus/is@4.6.0': {}
+
   '@sindresorhus/is@7.2.0': {}
 
   '@sindresorhus/merge-streams@4.0.0': {}
@@ -30458,6 +30544,11 @@ snapshots:
       postcss-media-query-parser: 0.2.3
       postcss-safe-parser: 7.0.1(postcss@8.5.28)
 
+  beautiful-mermaid@1.1.3:
+    dependencies:
+      elkjs: 0.11.1
+      entities: 7.0.1
+
   better-path-resolve@1.0.0:
     dependencies:
       is-windows: 1.0.2
@@ -30710,6 +30801,8 @@ snapshots:
 
   chalk@5.6.2: {}
 
+  char-regex@1.0.2: {}
+
   character-entities-html4@2.1.0: {}
 
   character-entities-legacy@3.0.0: {}
@@ -30829,10 +30922,25 @@ snapshots:
     dependencies:
       restore-cursor: 5.1.0
 
+  cli-highlight@2.1.11:
+    dependencies:
+      chalk: 4.1.2
+      highlight.js: 10.7.3
+      mz: 2.7.0
+      parse5: 5.1.1
+      parse5-htmlparser2-tree-adapter: 6.0.1
+      yargs: 16.2.2
+
   cli-spinners@2.6.1: {}
 
   cli-spinners@3.4.0: {}
 
+  cli-table3@0.6.5:
+    dependencies:
+      string-width: 4.2.3
+    optionalDependencies:
+      '@colors/colors': 1.5.0
+
   cli-truncate@5.2.0:
     dependencies:
       slice-ansi: 8.0.0
@@ -30851,6 +30959,12 @@ snapshots:
       is-wsl: 3.1.0
       is64bit: 2.0.0
 
+  cliui@7.0.4:
+    dependencies:
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+      wrap-ansi: 7.0.0
+
   cliui@8.0.1:
     dependencies:
       string-width: 4.2.3
@@ -31521,8 +31635,7 @@ snapshots:
 
   electron-to-chromium@1.5.434: {}
 
-  elkjs@0.11.1:
-    optional: true
+  elkjs@0.11.1: {}
 
   emoji-regex@10.6.0: {}
 
@@ -31530,6 +31643,8 @@ snapshots:
 
   emoji-regex@9.2.2: {}
 
+  emojilib@2.4.0: {}
+
   empathic@2.0.0: {}
 
   encodeurl@1.0.2: {}
@@ -32819,6 +32934,8 @@ snapshots:
     dependencies:
       hermes-estree: 0.35.0
 
+  highlight.js@10.7.3: {}
+
   highlight.js@11.11.1: {}
 
   hls.js@1.7.2: {}
@@ -33922,6 +34039,17 @@ snapshots:
     dependencies:
       marked: 15.0.12
 
+  marked-terminal@7.3.0(marked@15.0.12):
+    dependencies:
+      ansi-escapes: 7.3.0
+      ansi-regex: 6.3.0
+      chalk: 5.6.2
+      cli-highlight: 2.1.11
+      cli-table3: 0.6.5
+      marked: 15.0.12
+      node-emoji: 2.2.0
+      supports-hyperlinks: 3.2.0
+
   marked@15.0.12: {}
 
   marked@17.0.1: {}
@@ -35085,6 +35213,13 @@ snapshots:
 
   node-domexception@1.0.0: {}
 
+  node-emoji@2.2.0:
+    dependencies:
+      '@sindresorhus/is': 4.6.0
+      char-regex: 1.0.2
+      emojilib: 2.4.0
+      skin-tone: 2.0.0
+
   node-fetch-native@1.6.7: {}
 
   node-fetch@2.7.0:
@@ -35774,6 +35909,10 @@ snapshots:
       parse5: 8.0.0
       parse5-sax-parser: 8.0.0
 
+  parse5-htmlparser2-tree-adapter@6.0.1:
+    dependencies:
+      parse5: 6.0.1
+
   parse5-htmlparser2-tree-adapter@7.1.0:
     dependencies:
       domhandler: 5.0.3
@@ -35787,6 +35926,10 @@ snapshots:
     dependencies:
       parse5: 8.0.0
 
+  parse5@5.1.1: {}
+
+  parse5@6.0.1: {}
+
   parse5@7.3.0:
     dependencies:
       entities: 6.0.1
@@ -37536,6 +37679,10 @@ snapshots:
 
   sisteransi@1.0.5: {}
 
+  skin-tone@2.0.0:
+    dependencies:
+      unicode-emoji-modifier-base: 1.0.0
+
   slash@3.0.0: {}
 
   slash@5.1.0: {}
@@ -37816,6 +37963,11 @@ snapshots:
       has-flag: 4.0.0
       supports-color: 7.2.0
 
+  supports-hyperlinks@3.2.0:
+    dependencies:
+      has-flag: 4.0.0
+      supports-color: 7.2.0
+
   supports-preserve-symlinks-flag@1.0.0: {}
 
   svelte-check@4.3.4(picomatch@4.0.7)(svelte@5.56.9(@typescript-eslint/types@8.59.4))(typescript@5.9.3):
@@ -38359,6 +38511,8 @@ snapshots:
 
   unicode-canonical-property-names-ecmascript@2.0.1: {}
 
+  unicode-emoji-modifier-base@1.0.0: {}
+
   unicode-match-property-ecmascript@2.0.0:
     dependencies:
       unicode-canonical-property-names-ecmascript: 2.0.1
@@ -39423,10 +39577,22 @@ snapshots:
 
   yaml@2.9.0: {}
 
+  yargs-parser@20.2.9: {}
+
   yargs-parser@21.1.1: {}
 
   yargs-parser@22.0.0: {}
 
+  yargs@16.2.2:
+    dependencies:
+      cliui: 7.0.4
+      escalade: 3.2.0
+      get-caller-file: 2.0.5
+      require-directory: 2.1.1
+      string-width: 4.2.3
+      y18n: 5.0.8
+      yargs-parser: 20.2.9
+
   yargs@17.7.2:
     dependencies:
       cliui: 8.0.1

From 432817b530027f55f13e0b4641b36c4245afa2d1 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 11:53:13 +0200
Subject: [PATCH 072/286] feat(ai-persistence): add the LogStore contract, a
 memory log store, and conformance cases

LogStore is an append-only log per thread. append writes a batch at a named position, all or nothing, and rejects with LogConflictError when another writer took that position. memoryLogStore() is the reference store. runPersistenceConformance runs the log cases when stores.log is present.
---
 packages/ai-persistence/src/index.ts          |   8 +-
 packages/ai-persistence/src/memory.ts         |  82 ++++++++++-
 .../ai-persistence/src/testkit/conformance.ts | 135 ++++++++++++++++++
 packages/ai-persistence/src/types.ts          |  92 ++++++++++++
 .../tests/memory.conformance.test.ts          |  13 +-
 5 files changed, 327 insertions(+), 3 deletions(-)

diff --git a/packages/ai-persistence/src/index.ts b/packages/ai-persistence/src/index.ts
index 23b7903f28..87683d10e7 100644
--- a/packages/ai-persistence/src/index.ts
+++ b/packages/ai-persistence/src/index.ts
@@ -11,6 +11,8 @@ export {
   defineBlobStore,
   defineInboxStore,
   defineCredentialStore,
+  defineLogStore,
+  LogConflictError,
   // Run lifecycle helpers owned by @tanstack/ai, transiting through ./types so
   // this package's public surface stays a single import for backend authors.
   isTerminalRunStatus,
@@ -34,6 +36,10 @@ export type {
   // Harness credentials
   Credential,
   CredentialStore,
+  // Harness session log
+  LogEntry,
+  LogRecord,
+  LogStore,
   // Named product shapes (prefer these over a sparse bag)
   ChatTranscriptStores,
   ChatPersistenceStores,
@@ -113,7 +119,7 @@ export {
 export { parseRangeHeader, resolveBlobRange } from './blob-range'
 
 // Reference in-memory implementation
-export { memoryPersistence } from './memory'
+export { memoryLogStore, memoryPersistence } from './memory'
 
 // Persistence-owned capabilities only. Locks: @tanstack/ai.
 export {
diff --git a/packages/ai-persistence/src/memory.ts b/packages/ai-persistence/src/memory.ts
index 3565cbeb2a..1b2890c371 100644
--- a/packages/ai-persistence/src/memory.ts
+++ b/packages/ai-persistence/src/memory.ts
@@ -1,4 +1,4 @@
-import { defineAIPersistence } from './types'
+import { LogConflictError, defineAIPersistence } from './types'
 import { resolveBlobRange } from './blob-range'
 import type { ModelMessage } from '@tanstack/ai'
 import type {
@@ -22,6 +22,9 @@ import type {
   InterruptCommitEntry,
   InterruptRecord,
   InterruptStore,
+  LogEntry,
+  LogRecord,
+  LogStore,
   MessageStore,
   MetadataStore,
   RunRecord,
@@ -671,6 +674,83 @@ class MemoryCredentialStore implements CredentialStore {
   }
 }
 
+/** A JSON copy, so the log never shares an object with a caller. */
+const copyRecord = (record: LogRecord) =>
+  JSON.parse(JSON.stringify(record)) as LogRecord
+
+class MemoryLogStore implements LogStore {
+  private readonly threads = new Map<string, Array<LogRecord>>()
+  private readonly listeners = new Map<string, Set<() => void>>()
+
+  append(
+    threadId: string,
+    seq: number,
+    records: ReadonlyArray<LogRecord>,
+  ): Promise<void> {
+    if (records.length === 0) return Promise.resolve()
+    const log = this.threads.get(threadId) ?? []
+    if (seq !== log.length + 1) {
+      return Promise.reject(new LogConflictError(threadId, seq))
+    }
+    // Copy the whole batch before the push, so a record that cannot become
+    // JSON rejects the batch with nothing written.
+    let copies: Array<LogRecord>
+    try {
+      copies = records.map(copyRecord)
+    } catch (error) {
+      return Promise.reject(error)
+    }
+    log.push(...copies)
+    this.threads.set(threadId, log)
+    for (const listener of [...(this.listeners.get(threadId) ?? [])]) {
+      listener()
+    }
+    return Promise.resolve()
+  }
+
+  read(
+    threadId: string,
+    options?: { after?: number; limit?: number },
+  ): Promise<Array<LogEntry>> {
+    const log = this.threads.get(threadId) ?? []
+    const after = options?.after ?? 0
+    const end =
+      options?.limit === undefined ? log.length : after + options.limit
+    const entries = log.slice(after, end).map((record, index) => ({
+      seq: after + index + 1,
+      record: copyRecord(record),
+    }))
+    return Promise.resolve(entries)
+  }
+
+  subscribe(threadId: string, listener: () => void): () => void {
+    let set = this.listeners.get(threadId)
+    if (!set) {
+      set = new Set()
+      this.listeners.set(threadId, set)
+    }
+    set.add(listener)
+    return () => {
+      set.delete(listener)
+    }
+  }
+}
+
+/**
+ * In-process reference {@link LogStore}, for tests and one-process hosts. The
+ * log is lost when the process stops. Records are JSON-copied in and out.
+ *
+ * @example
+ * ```ts
+ * const host = createHarnessHost({
+ *   persistence: { stores: { log: memoryLogStore(), runs } },
+ * })
+ * ```
+ */
+export function memoryLogStore(): LogStore {
+  return new MemoryLogStore()
+}
+
 interface MemoryPersistenceStores {
   messages: MessageStore
   runs: RunStore
diff --git a/packages/ai-persistence/src/testkit/conformance.ts b/packages/ai-persistence/src/testkit/conformance.ts
index 3b8ab62ebf..6db6f3824f 100644
--- a/packages/ai-persistence/src/testkit/conformance.ts
+++ b/packages/ai-persistence/src/testkit/conformance.ts
@@ -37,11 +37,13 @@
  * starting with `rc-`, or it silently changes that expected set.
  */
 import { beforeAll, describe, expect, it } from 'vitest'
+import { LogConflictError } from '../types'
 import type { ModelMessage } from '@tanstack/ai'
 import type {
   AIPersistence,
   AIPersistenceStores,
   ArtifactRecord,
+  LogStore,
   RunStore,
 } from '../types'
 
@@ -1657,6 +1659,139 @@ export function runPersistenceConformance(
       })
     })
 
+    // The session log is opt-in: only durable harness hosts read it. A backend
+    // without it skips these cases and needs no `skip` entry. Each case uses
+    // its own thread, because the suite shares one persistence.
+    describe('log', () => {
+      const newThread = () => `log-${crypto.randomUUID()}`
+      const types = async (store: LogStore, threadId: string) =>
+        (await store.read(threadId)).map((entry) => [
+          entry.seq,
+          entry.record.type,
+        ])
+
+      it('writes a batch at consecutive positions and reads it in order', async (ctx) => {
+        const store = persistence.stores.log
+        if (!store) return ctx.skip('log store not provided')
+        const threadId = newThread()
+
+        await store.append(threadId, 1, [
+          { type: 'a', n: 1 },
+          { type: 'b', n: 2 },
+        ])
+        await store.append(threadId, 3, [{ type: 'c', nested: { deep: [1] } }])
+
+        expect(await store.read(threadId)).toEqual([
+          { seq: 1, record: { type: 'a', n: 1 } },
+          { seq: 2, record: { type: 'b', n: 2 } },
+          { seq: 3, record: { type: 'c', nested: { deep: [1] } } },
+        ])
+      })
+
+      it('rejects a taken position or a gap with LogConflictError and writes nothing', async (ctx) => {
+        const store = persistence.stores.log
+        if (!store) return ctx.skip('log store not provided')
+        const threadId = newThread()
+        await store.append(threadId, 1, [{ type: 'first' }])
+
+        const taken = store.append(threadId, 1, [
+          { type: 'late-1' },
+          { type: 'late-2' },
+        ])
+        await expect(taken).rejects.toBeInstanceOf(LogConflictError)
+        await expect(taken).rejects.toMatchObject({ threadId, seq: 1 })
+
+        // A gap (position 3 while 2 is free) is a conflict too.
+        await expect(
+          store.append(threadId, 3, [{ type: 'gap' }]),
+        ).rejects.toBeInstanceOf(LogConflictError)
+
+        expect(await types(store, threadId)).toEqual([[1, 'first']])
+      })
+
+      it('writes nothing for an empty batch', async (ctx) => {
+        const store = persistence.stores.log
+        if (!store) return ctx.skip('log store not provided')
+        const threadId = newThread()
+
+        await store.append(threadId, 1, [])
+
+        expect(await store.read(threadId)).toEqual([])
+        await store.append(threadId, 1, [{ type: 'still-first' }])
+        expect(await types(store, threadId)).toEqual([[1, 'still-first']])
+      })
+
+      it('reads after a position, with a limit', async (ctx) => {
+        const store = persistence.stores.log
+        if (!store) return ctx.skip('log store not provided')
+        const threadId = newThread()
+        await store.append(threadId, 1, [
+          { type: 'r1' },
+          { type: 'r2' },
+          { type: 'r3' },
+          { type: 'r4' },
+        ])
+
+        const page = await store.read(threadId, { after: 1, limit: 2 })
+        expect(page.map((entry) => entry.seq)).toEqual([2, 3])
+        expect(
+          (await store.read(threadId, { after: 3 })).map((entry) => entry.seq),
+        ).toEqual([4])
+        expect(await store.read(threadId, { after: 4 })).toEqual([])
+        expect(await store.read(threadId, { limit: 0 })).toEqual([])
+        expect(await store.read(newThread())).toEqual([])
+      })
+
+      it('keeps threads apart', async (ctx) => {
+        const store = persistence.stores.log
+        if (!store) return ctx.skip('log store not provided')
+        const left = newThread()
+        const right = newThread()
+
+        await store.append(left, 1, [{ type: 'left' }])
+        // Position 1 is free on the other thread.
+        await store.append(right, 1, [{ type: 'right' }])
+
+        expect(await types(store, left)).toEqual([[1, 'left']])
+        expect(await types(store, right)).toEqual([[1, 'right']])
+      })
+
+      it('calls a listener after each append until it unsubscribes', async (ctx) => {
+        const store = persistence.stores.log
+        if (!store) return ctx.skip('log store not provided')
+        const threadId = newThread()
+        let calls = 0
+        const stop = store.subscribe(threadId, () => {
+          calls += 1
+        })
+
+        await store.append(threadId, 1, [{ type: 'one' }])
+        await expect.poll(() => calls).toBe(1)
+        stop()
+        await store.append(threadId, 2, [{ type: 'two' }])
+
+        // Give a store that notifies later (a poller) the time to call again.
+        await new Promise((resolve) => setTimeout(resolve, 50))
+        expect(calls).toBe(1)
+      })
+
+      it('does not share record objects with the caller', async (ctx) => {
+        const store = persistence.stores.log
+        if (!store) return ctx.skip('log store not provided')
+        const threadId = newThread()
+        const written = { type: 'shared', list: [1] }
+        await store.append(threadId, 1, [written])
+        written.list.push(2)
+
+        const [first] = await store.read(threadId)
+        if (first) first.record.type = 'changed'
+
+        expect(await store.read(threadId)).toEqual([
+          { seq: 1, record: { type: 'shared', list: [1] } },
+        ])
+      })
+    })
+
     describe('metadata', () => {
       it('sets, gets, namespaces, and deletes without composite-key collisions', async (ctx) => {
         const store = resolveStore('metadata')
diff --git a/packages/ai-persistence/src/types.ts b/packages/ai-persistence/src/types.ts
index dc47fcfffb..4a043069ca 100644
--- a/packages/ai-persistence/src/types.ts
+++ b/packages/ai-persistence/src/types.ts
@@ -416,6 +416,95 @@ export function defineInboxStore(store: InboxStore): InboxStore {
   return store
 }
 
+/**
+ * One record of a session log. `type` names the kind of record. The other
+ * fields are JSON. Records with a `type` that starts with `harness.` belong
+ * to `@tanstack/ai-harness`. A host adds its own records with other types.
+ */
+export interface LogRecord {
+  type: string
+  [key: string]: unknown
+}
+
+/** A {@link LogRecord} and its position in the log. */
+export interface LogEntry {
+  /** The position of the record. The first record of a thread is at 1. */
+  seq: number
+  record: LogRecord
+}
+
+/**
+ * The error {@link LogStore.append} rejects with when `seq` is not the next
+ * free position of the thread. It means that another writer appended first.
+ * Nothing of the rejected batch is written.
+ */
+export class LogConflictError extends Error {
+  readonly threadId: string
+  readonly seq: number
+
+  constructor(threadId: string, seq: number) {
+    super(
+      `Log conflict on thread ${JSON.stringify(threadId)}: position ${seq} is not the next free position.`,
+    )
+    this.name = 'LogConflictError'
+    this.threadId = threadId
+    this.seq = seq
+  }
+}
+
+/**
+ * Durable append-only log of a harness session, one log per thread. A durable
+ * harness host keeps the events, the transcript, the inputs, and the tool
+ * steps of a thread in it.
+ *
+ * The log has one writer at a time. `append` is a compare-and-append: the
+ * writer names the position of the first record, and the store refuses the
+ * batch when another writer took that position first. In SQL, a primary key
+ * on `(thread_id, seq)` and one transaction per batch give this.
+ */
+export interface LogStore {
+  /**
+   * Write `records` at positions `seq`, `seq + 1`, and so on.
+   *
+   * INVARIANT (atomic): the whole batch is written, or none of it is. A crash
+   * or an error never leaves a part of the batch.
+   *
+   * INVARIANT (compare-and-append): `seq` must be the next free position (the
+   * last position of the thread plus 1, or 1 for a new thread). For any other
+   * `seq`, a position that is taken or a gap, reject with
+   * {@link LogConflictError} and write nothing.
+   *
+   * An empty batch writes nothing and resolves.
+   */
+  append: (
+    threadId: string,
+    seq: number,
+    records: ReadonlyArray<LogRecord>,
+  ) => Promise<void>
+  /**
+   * The entries of `threadId` with `seq` greater than `after` (default 0), in
+   * ascending order, at most `limit` of them. `limit: 0` gives `[]`.
+   *
+   * INVARIANT: a thread that has no records gives `[]`. The returned records
+   * are copies: a change to them does not change the log.
+   */
+  read: (
+    threadId: string,
+    options?: { after?: number; limit?: number },
+  ) => Promise<Array<LogEntry>>
+  /**
+   * Call `listener` after each append to `threadId` that this store can see.
+   * A store that cannot see appends from other processes can poll. Returns a
+   * function that stops the calls.
+   */
+  subscribe: (threadId: string, listener: () => void) => () => void
+}
+
+/** Type a {@link LogStore} implementation inline. */
+export function defineLogStore(store: LogStore): LogStore {
+  return store
+}
+
 /** A secret a user or an organization saved: an API key or OAuth tokens. */
 export type Credential =
   | { type: 'api_key'; value: string }
@@ -715,6 +804,8 @@ export interface AIPersistenceStores {
   inbox?: InboxStore
   /** User and tenant credentials. Optional: only harness hosts read it. */
   credentials?: CredentialStore
+  /** The harness session log. Optional: only durable harness hosts read it. */
+  log?: LogStore
 }
 
 /**
@@ -892,6 +983,7 @@ const storeKeys = [
   'blobs',
   'inbox',
   'credentials',
+  'log',
 ] satisfies Array<StoreKey>
 
 const storeKeySet = new Set<string>(storeKeys)
diff --git a/packages/ai-persistence/tests/memory.conformance.test.ts b/packages/ai-persistence/tests/memory.conformance.test.ts
index a3a693f674..e55174dd25 100644
--- a/packages/ai-persistence/tests/memory.conformance.test.ts
+++ b/packages/ai-persistence/tests/memory.conformance.test.ts
@@ -1,6 +1,17 @@
 import { runPersistenceConformance } from '../src/testkit/conformance'
-import { memoryPersistence } from '../src/memory'
+import { memoryLogStore, memoryPersistence } from '../src/memory'
+import { defineAIPersistence } from '../src/types'
 
 runPersistenceConformance('memory', () => memoryPersistence(), {
   checks: ['messages.metadata', 'runs.listByThread.state'],
 })
+
+// memoryPersistence() has no log, so the log cases run in their own suite.
+runPersistenceConformance(
+  'memory + log',
+  () =>
+    defineAIPersistence({
+      stores: { ...memoryPersistence().stores, log: memoryLogStore() },
+    }),
+  { checks: ['messages.metadata', 'runs.listByThread.state'] },
+)

From f3d6ab12b902c39d8d1795615be3ab38bca43e51 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 11:55:48 +0200
Subject: [PATCH 073/286] feat(ai-harness): input ids, settlement and receipt
 types, durability option, and an event feed interface

HarnessInput takes an optional inputId. Operation gets a receipt promise. InputSettlement and InputRejectedError describe how an input ended. defineHarness takes durability limits. SessionFeed now implements an EventFeed interface, so a durable host can give the session a feed backed by the log.
---
 packages/ai-harness/src/define.ts         | 21 ++++++++++
 packages/ai-harness/src/feed.ts           | 44 ++++++++++++--------
 packages/ai-harness/src/operation.ts      | 22 +++++++---
 packages/ai-harness/src/types.ts          | 50 ++++++++++++++++++++++-
 packages/ai-harness/tests/types.test-d.ts | 44 +++++++++++++++++++-
 5 files changed, 157 insertions(+), 24 deletions(-)

diff --git a/packages/ai-harness/src/define.ts b/packages/ai-harness/src/define.ts
index 5a8ced1b5a..66b371c939 100644
--- a/packages/ai-harness/src/define.ts
+++ b/packages/ai-harness/src/define.ts
@@ -19,6 +19,25 @@ export type HarnessSubagents<TSubagents extends ReadonlyArray<AnyAgent>> = Omit<
   'binding'
 >
 
+/**
+ * Limits for one input on a durable host (a host with `stores.log`). A host
+ * without a log does not read them.
+ */
+export interface HarnessDurability {
+  /**
+   * Total attempts for one input, the first run included. Each recovery after
+   * a crash is one more attempt. When no attempt is left, the input fails
+   * with code `'attempts_exhausted'`. Default 10.
+   */
+  maxAttempts?: number
+  /**
+   * Time from the first run of an input until it fails with code
+   * `'timeout'`, in milliseconds. Retries do not reset it. Default: no
+   * timeout.
+   */
+  timeoutMs?: number
+}
+
 /**
  * What `defineHarness` takes. Where it overlaps with `chat()`, the option
  * names and types are the same.
@@ -61,6 +80,8 @@ export interface HarnessConfig<
   plugins?: () => ReadonlyArray<HarnessPlugin>
   /** What a `prompt` does while a chat turn runs. Default `'queue'`. */
   busy?: BusyPolicy
+  /** Attempt and time limits for each input on a durable host. */
+  durability?: HarnessDurability
   /**
    * Files sent to a turn, and media agents make: the size limit, the kinds a
    * user can send, the kinds the model reads, and an optional transcriber for
diff --git a/packages/ai-harness/src/feed.ts b/packages/ai-harness/src/feed.ts
index e5f8b63081..76280a4411 100644
--- a/packages/ai-harness/src/feed.ts
+++ b/packages/ai-harness/src/feed.ts
@@ -7,37 +7,49 @@ import type { Cursor, SessionEvent } from './types'
 const MAX_EVENTS = 10_000
 
 /**
- * The ordered event stream of one session. Every operation publishes here.
- * Cursors are opaque to callers and increase with each event.
+ * The ordered event stream of one session. Every operation publishes here. A
+ * host without a log uses {@link SessionFeed}. A durable host uses a feed
+ * that keeps the events in the session log.
  */
-export class SessionFeed {
+export interface EventFeed {
+  publish: (operationId: string, event: StreamChunk) => void
+  /** The cursor of the newest event, or `'0'` for an empty feed. */
+  head: () => Cursor
+  /**
+   * Events after `from` (exclusive), then live events until `signal` aborts
+   * or the feed closes. Pass a `filter` to read one operation's events.
+   */
+  read: (options: {
+    from?: Cursor
+    signal?: AbortSignal
+    filter?: (entry: SessionEvent) => boolean
+    /** Stop after `until()` returns true and no buffered event is left. */
+    until?: () => boolean
+  }) => AsyncIterable<SessionEvent>
+  close: () => void
+}
+
+/**
+ * The in-memory {@link EventFeed}. Cursors are opaque to callers and increase
+ * with each event.
+ */
+export class SessionFeed implements EventFeed {
   private readonly entries: Array<SessionEvent> = []
   private sequence = 0
   private readonly waiters = new Set<() => void>()
   private closed = false
 
-  publish(operationId: string, event: StreamChunk): SessionEvent {
+  publish(operationId: string, event: StreamChunk): void {
     this.sequence += 1
-    const entry: SessionEvent = {
-      cursor: String(this.sequence),
-      operationId,
-      event,
-    }
-    this.entries.push(entry)
+    this.entries.push({ cursor: String(this.sequence), operationId, event })
     if (this.entries.length > MAX_EVENTS) this.entries.shift()
     this.wake()
-    return entry
   }
 
-  /** The cursor of the newest event, or `'0'` for an empty feed. */
   head(): Cursor {
     return String(this.sequence)
   }
 
-  /**
-   * Events after `from` (exclusive), then live events until `signal` aborts
-   * or the feed closes. Pass a `filter` to read one operation's events.
-   */
   async *read(options: {
     from?: Cursor
     signal?: AbortSignal
diff --git a/packages/ai-harness/src/operation.ts b/packages/ai-harness/src/operation.ts
index 33f80cd2e6..386d1201bd 100644
--- a/packages/ai-harness/src/operation.ts
+++ b/packages/ai-harness/src/operation.ts
@@ -1,5 +1,5 @@
 import type { StreamChunk } from '@tanstack/ai'
-import type { SessionFeed } from './feed'
+import type { EventFeed } from './feed'
 import type {
   Cursor,
   Operation,
@@ -28,20 +28,27 @@ const TERMINAL: ReadonlySet<OperationStatus> = new Set([
 export class OperationImpl<TResult> implements Operation<TResult> {
   readonly id: string
   readonly abortController = new AbortController()
+  readonly receipt: Promise<Receipt>
   private current: OperationStatus = 'accepted'
   private readonly settled: Promise<TResult>
   private resolveResult!: (value: TResult) => void
   private rejectResult!: (error: unknown) => void
+  private settleReceipt!: (receipt: Receipt) => void
 
   constructor(
     readonly kind: OperationKind,
-    private readonly feed: SessionFeed,
+    private readonly feed: EventFeed,
     private readonly onCancel: (
       operation: OperationImpl<TResult>,
     ) => Promise<Receipt>,
     readonly agent?: string,
+    /** A stored operation id, when a restart rebuilds this operation. */
+    id?: string,
   ) {
-    this.id = createOperationId(kind)
+    this.id = id ?? createOperationId(kind)
+    this.receipt = new Promise<Receipt>((resolve) => {
+      this.settleReceipt = resolve
+    })
     this.settled = new Promise<TResult>((resolve, reject) => {
       this.resolveResult = resolve
       this.rejectResult = reject
@@ -70,8 +77,13 @@ export class OperationImpl<TResult> implements Operation<TResult> {
     this.current = status
   }
 
-  publish(event: StreamChunk): SessionEvent {
-    return this.feed.publish(this.id, event)
+  publish(event: StreamChunk): void {
+    this.feed.publish(this.id, event)
+  }
+
+  /** Answer `receipt`. The first answer wins. */
+  resolveReceipt(receipt: Receipt): void {
+    this.settleReceipt(receipt)
   }
 
   finish(status: 'completed' | 'interrupted', result: TResult): void {
diff --git a/packages/ai-harness/src/types.ts b/packages/ai-harness/src/types.ts
index 5088c0e8e5..61e8be36a5 100644
--- a/packages/ai-harness/src/types.ts
+++ b/packages/ai-harness/src/types.ts
@@ -46,8 +46,15 @@ export interface SessionEvent {
   event: StreamChunk
 }
 
-/** An input a client sends to a session. Stored in the inbox. */
-export type HarnessInput =
+/**
+ * An input a client sends to a session. Stored in the inbox, or in the log of
+ * a durable host.
+ *
+ * `inputId` is an optional id that the caller chooses. A second input with the
+ * same id and the same payload gets the first input's receipt and does not run
+ * again. The same id with another payload is rejected with `'conflict'`.
+ */
+export type HarnessInput = (
   | { op: 'prompt'; message: UserInput; busy?: BusyPolicy }
   | { op: 'steer'; message: UserInput }
   | { op: 'followUp'; message: UserInput }
@@ -57,6 +64,36 @@ export type HarnessInput =
   | { op: 'command'; name: string; input?: unknown }
   | { op: 'answer'; questionId: string; value: unknown }
   | { op: 'config'; key: string; value: unknown }
+) & { inputId?: string }
+
+/** How an input ended. `session.settled(inputId)` resolves to it. */
+export interface InputSettlement {
+  inputId: string
+  /**
+   * `interrupted`: the turn stopped for human input. The `resolve` that
+   * answers it is a new input with its own settlement.
+   */
+  outcome: 'completed' | 'failed' | 'aborted' | 'interrupted'
+  /** The operation that ran the input, when one started. */
+  operationId?: string
+  /** Set for `failed`. `code` is `'attempts_exhausted'`, `'timeout'`, or absent. */
+  error?: { message: string; code?: string }
+}
+
+/**
+ * An awaited operation rejects with this error when the session refused its
+ * input (for example `busy: 'reject'` while a turn runs, or an `inputId`
+ * conflict). `receipt` is the refused receipt.
+ */
+export class InputRejectedError extends Error {
+  readonly receipt: Receipt
+
+  constructor(receipt: Receipt) {
+    super(`The session rejected the input: ${receipt.reason ?? 'rejected'}.`)
+    this.name = 'InputRejectedError'
+    this.receipt = receipt
+  }
+}
 
 /** Who sent an input, from the host's `authorize`. */
 export interface Principal {
@@ -82,6 +119,13 @@ export interface Operation<TResult> extends PromiseLike<TResult> {
   /** The agent name, for `kind: 'agent'`. */
   readonly agent?: string
   status: () => OperationStatus
+  /**
+   * The answer to the input of this operation. It resolves after the session
+   * stored the input (`accepted` or `queued`), or refused it (`rejected`).
+   * With a durable host, a resolved receipt means that the input survives a
+   * restart.
+   */
+  readonly receipt: Promise<Receipt>
   /** This operation's events, from `from` (exclusive) onward. */
   events: (options?: {
     from?: Cursor
@@ -126,6 +170,8 @@ export const HARNESS_EVENTS = {
   inputAccepted: 'harness.input.accepted',
   inputApplied: 'harness.input.applied',
   inputRejected: 'harness.input.rejected',
+  /** An input ended. The value is an `InputSettlement`. */
+  inputSettled: 'harness.input.settled',
   /** A media file was stored. The value is a `MediaRecord`. */
   media: 'harness.media',
 } as const
diff --git a/packages/ai-harness/tests/types.test-d.ts b/packages/ai-harness/tests/types.test-d.ts
index 0a9ffe74ee..4650ac1577 100644
--- a/packages/ai-harness/tests/types.test-d.ts
+++ b/packages/ai-harness/tests/types.test-d.ts
@@ -3,7 +3,14 @@ import { z } from 'zod'
 import { defineAgent } from '@tanstack/ai'
 import { defineHarness } from '../src'
 import { mockAdapter } from './helpers'
-import type { HarnessSession, Operation } from '../src'
+import type {
+  HarnessConfig,
+  HarnessInput,
+  HarnessSession,
+  Operation,
+  Receipt,
+} from '../src'
+import type { InputSettlement } from '../src/types'
 
 const pricer = defineAgent({
   name: 'pricer',
@@ -26,6 +33,7 @@ const harness = defineHarness({
 })
 
 declare const session: HarnessSession<typeof harness>
+declare const input: HarnessInput
 
 it('types agent input and result from the definition', () => {
   expectTypeOf(session.agents.pricer.run({ vendor: 'a' })).toEqualTypeOf<
@@ -37,3 +45,37 @@ it('types agent input and result from the definition', () => {
   // @ts-expect-error wrong input
   void session.agents.pricer.run({ vendor: 1 })
 })
+
+it('takes an inputId on every input and keeps the op narrowing', () => {
+  const inputs = [
+    { op: 'prompt', message: 'hi', inputId: 'a' },
+    { op: 'cancel', inputId: 'b' },
+    { op: 'config', key: 'tone', value: 'warm', inputId: 'c' },
+  ] satisfies Array<HarnessInput>
+  expectTypeOf(inputs).toExtend<Array<HarnessInput>>()
+
+  if (input.op === 'prompt') {
+    expectTypeOf(input.message).toEqualTypeOf<
+      Extract<HarnessInput, { op: 'prompt' }>['message']
+    >()
+  }
+})
+
+it('gives every operation a receipt promise', () => {
+  expectTypeOf<Operation<string>['receipt']>().toEqualTypeOf<Promise<Receipt>>()
+})
+
+it('describes how an input ended', () => {
+  expectTypeOf<InputSettlement['outcome']>().toEqualTypeOf<
+    'completed' | 'failed' | 'aborted' | 'interrupted'
+  >()
+  expectTypeOf<InputSettlement['error']>().toEqualTypeOf<
+    { message: string; code?: string } | undefined
+  >()
+})
+
+it('takes attempt and time limits on the harness', () => {
+  expectTypeOf<HarnessConfig['durability']>().toEqualTypeOf<
+    { maxAttempts?: number; timeoutMs?: number } | undefined
+  >()
+})

From e62ee9fbe209649ade8b93006f874482ba617003 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 11:59:03 +0200
Subject: [PATCH 074/286] feat(ai-harness): configurable lease, tool error on
 the crash note, and repair that keeps finished results

checkpointMiddleware takes an options object with a lease and an onToolResult callback. repairTranscript sets error on the crash note, so the model sees a tool error, and it keeps the result of a call that finished before the crash.
---
 packages/ai-harness/src/resume.ts             | 115 ++++++++----
 packages/ai-harness/src/session.ts            |  16 +-
 .../ai-harness/tests/resume-edges.test.ts     |  63 +++----
 packages/ai-harness/tests/resume.test.ts      | 171 +++++++++++++++++-
 4 files changed, 293 insertions(+), 72 deletions(-)

diff --git a/packages/ai-harness/src/resume.ts b/packages/ai-harness/src/resume.ts
index ea695840e0..941efa9cd7 100644
--- a/packages/ai-harness/src/resume.ts
+++ b/packages/ai-harness/src/resume.ts
@@ -1,9 +1,23 @@
-import type { AnyChatMiddleware, ModelMessage, RunRecord } from '@tanstack/ai'
-import type { HarnessPersistence } from './host'
+import { normalizeToolResult } from '@tanstack/ai'
+import type {
+  AnyChatMiddleware,
+  ModelMessage,
+  RunRecord,
+  RunStore,
+} from '@tanstack/ai'
+import type { MessageStore } from '@tanstack/ai-persistence'
 
 /** How often a running host renews its lease, and when a lease expires. */
 export const LEASE = { renewMs: 10_000, ttlMs: 30_000 }
 
+/** Lease timing for a host. A missing field uses {@link LEASE}. */
+export interface LeaseOptions {
+  /** How long a lease lasts after each renewal, in milliseconds. */
+  ttlMs?: number
+  /** How often the running host renews its lease, in milliseconds. */
+  renewMs?: number
+}
+
 /** The tool result a crash leaves for a tool that must not run twice. */
 export const INTERRUPTED_TOOL_RESULT = {
   interrupted: true,
@@ -16,19 +30,31 @@ type PendingTool = {
   replay: 'safe' | 'never'
 }
 
+const errorText = (error: unknown) =>
+  error instanceof Error ? error.message : String(error)
+
 /**
  * Chat middleware that makes a turn resumable after a crash:
  *
  * - holds a lease on the run record and renews it while the turn runs;
  * - saves the transcript before and after each tool phase;
- * - records each tool call that started but has no result yet.
+ * - records each tool call that started but has no result yet;
+ * - gives `onToolResult` the tool message of each call that ends.
  */
-export function checkpointMiddleware(
-  persistence: HarnessPersistence,
-  hostId: string,
-): AnyChatMiddleware {
-  const runs = persistence.stores.runs
-  const messages = persistence.stores.messages
+export function checkpointMiddleware(options: {
+  runs?: RunStore
+  messages: MessageStore
+  hostId: string
+  lease?: LeaseOptions
+  /** Called after each tool call ends, with the tool message the model gets. */
+  onToolResult?: (info: {
+    toolCallId: string
+    message: ModelMessage
+  }) => void | Promise<void>
+}): AnyChatMiddleware {
+  const { runs, messages, hostId, onToolResult } = options
+  const ttlMs = options.lease?.ttlMs ?? LEASE.ttlMs
+  const renewMs = options.lease?.renewMs ?? LEASE.renewMs
   const state = new WeakMap<
     object,
     { timer: ReturnType<typeof setInterval>; pending: Array<PendingTool> }
@@ -51,10 +77,10 @@ export function checkpointMiddleware(
       const renew = () =>
         runs?.update(ctx.runId, {
           leaseOwner: hostId,
-          leaseExpiresAt: Date.now() + LEASE.ttlMs,
+          leaseExpiresAt: Date.now() + ttlMs,
         })
       await renew()
-      const timer = setInterval(() => void renew(), LEASE.renewMs)
+      const timer = setInterval(() => void renew(), renewMs)
       // A lease timer must not keep a CLI or a test process alive.
       if (typeof timer === 'object' && 'unref' in timer) timer.unref()
       state.set(ctx, { timer, pending: [] })
@@ -80,6 +106,21 @@ export function checkpointMiddleware(
       entry.pending = entry.pending.filter(
         (tool) => tool.toolCallId !== info.toolCallId,
       )
+      if (!onToolResult) return
+      // The same content the engine puts in its tool message.
+      const message: ModelMessage = info.ok
+        ? {
+            role: 'tool',
+            toolCallId: info.toolCallId,
+            content: normalizeToolResult(info.result),
+          }
+        : {
+            role: 'tool',
+            toolCallId: info.toolCallId,
+            content: JSON.stringify({ error: errorText(info.error) }),
+            error: errorText(info.error),
+          }
+      await onToolResult({ toolCallId: info.toolCallId, message })
     },
     async onToolPhaseComplete(ctx) {
       const entry = state.get(ctx)
@@ -96,11 +137,10 @@ export function checkpointMiddleware(
 
 /** Chat runs of this thread that a crashed host left `running`. */
 export async function findCrashedRuns(
-  persistence: HarnessPersistence,
+  runs: RunStore | undefined,
   threadId: string,
   now = Date.now(),
 ): Promise<Array<RunRecord>> {
-  const runs = persistence.stores.runs
   if (!runs?.listByThread) return []
   const records = await runs.listByThread(threadId)
   return records.filter(
@@ -113,34 +153,45 @@ export async function findCrashedRuns(
 }
 
 /**
- * Prepare the transcript of a crashed run for a new run. A tool with
- * `replay: 'never'` gets {@link INTERRUPTED_TOOL_RESULT}. A tool with
- * `replay: 'safe'` stays without a result, so the engine runs it again.
+ * Prepare the transcript of a crashed run for a new run:
+ *
+ * - A call in `finished` gets its finished tool message. It does not run
+ *   again.
+ * - Another call with `replay: 'never'` gets {@link INTERRUPTED_TOOL_RESULT}
+ *   as a tool error.
+ * - Another call with `replay: 'safe'` stays without a result, so the engine
+ *   runs it again.
  */
-export async function repairTranscript(
-  persistence: HarnessPersistence,
-  crashed: RunRecord,
-): Promise<void> {
+export async function repairTranscript(options: {
+  messages: MessageStore
+  crashed: RunRecord
+  /** Tool messages of calls that finished before the crash, by toolCallId. */
+  finished?: ReadonlyMap<string, ModelMessage>
+}): Promise<void> {
+  const { messages, crashed, finished } = options
   const pending = crashed.checkpoint?.pendingTools ?? []
-  const never = pending.filter((tool) => tool.replay === 'never')
-  if (never.length === 0) return
-  const store = persistence.stores.messages
-  const history = await store.loadThread(crashed.threadId)
+  if (pending.length === 0) return
+  const history = await messages.loadThread(crashed.threadId)
   const answered = new Set(
     history.flatMap((message) =>
       message.role === 'tool' && message.toolCallId ? [message.toolCallId] : [],
     ),
   )
-  const notes = never
-    .filter((tool) => !answered.has(tool.toolCallId))
-    .map(
-      (tool): ModelMessage => ({
+  const unanswered = pending.filter((tool) => !answered.has(tool.toolCallId))
+  const added = unanswered.flatMap((tool): Array<ModelMessage> => {
+    const result = finished?.get(tool.toolCallId)
+    if (result) return [result]
+    if (tool.replay === 'safe') return []
+    return [
+      {
         role: 'tool',
         toolCallId: tool.toolCallId,
         content: JSON.stringify(INTERRUPTED_TOOL_RESULT),
-      }),
-    )
-  if (notes.length > 0) {
-    await store.saveThread(crashed.threadId, [...history, ...notes])
+        error: INTERRUPTED_TOOL_RESULT.note,
+      },
+    ]
+  })
+  if (added.length > 0) {
+    await messages.saveThread(crashed.threadId, [...history, ...added])
   }
 }
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 527aab8a46..bdde6de1da 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -325,7 +325,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     })
     this.principal = deps.principal
     this.onClose = deps.onClose
-    this.checkpoint = checkpointMiddleware(deps.persistence, deps.hostId)
+    this.checkpoint = checkpointMiddleware({
+      runs: deps.persistence.stores.runs,
+      messages: deps.persistence.stores.messages,
+      hostId: deps.hostId,
+    })
     const onMissing = (error: AuthRequiredError) =>
       this.feed.publish(
         'session',
@@ -1773,7 +1777,10 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
    * crashed turns are marked failed.
    */
   private async recoverCrashedTurn(): Promise<void> {
-    const crashed = await findCrashedRuns(this.persistence, this.threadId)
+    const crashed = await findCrashedRuns(
+      this.persistence.stores.runs,
+      this.threadId,
+    )
     const newest = crashed.sort((a, b) => b.startedAt - a.startedAt)[0]
     for (const record of crashed) {
       await this.persistence.stores.runs?.update(record.runId, {
@@ -1788,7 +1795,10 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       })
     }
     if (!newest) return
-    await repairTranscript(this.persistence, newest)
+    await repairTranscript({
+      messages: this.persistence.stores.messages,
+      crashed: newest,
+    })
     const operation = this.createTurnOperation()
     this.feed.publish(
       operation.id,
diff --git a/packages/ai-harness/tests/resume-edges.test.ts b/packages/ai-harness/tests/resume-edges.test.ts
index 685de95ffa..7dc1f4e805 100644
--- a/packages/ai-harness/tests/resume-edges.test.ts
+++ b/packages/ai-harness/tests/resume-edges.test.ts
@@ -9,8 +9,7 @@ import {
   repairTranscript,
 } from '../src/resume'
 import { mockAdapter, text, untilAborted } from './helpers'
-import type { RunRecord, StreamChunk } from '@tanstack/ai'
-import type { HarnessPersistence } from '../src/host'
+import type { RunRecord, RunStore, StreamChunk } from '@tanstack/ai'
 
 async function crash(
   persistence: ReturnType<typeof memoryPersistence>,
@@ -32,11 +31,15 @@ async function crash(
 
 describe('crash recovery edges', () => {
   it('finds nothing when the run store cannot list a thread', async () => {
-    const noRuns = { stores: {} } as unknown as HarnessPersistence
-    expect(await findCrashedRuns(noRuns, 't1')).toEqual([])
-    const noList = {
-      stores: { runs: { get: async () => null } },
-    } as unknown as HarnessPersistence
+    expect(await findCrashedRuns(undefined, 't1')).toEqual([])
+    const runs = memoryPersistence().stores.runs
+    // A store with only the required methods: no listByThread.
+    const noList: RunStore = {
+      createOrResume: (input) => runs.createOrResume(input),
+      update: (runId, patch) => runs.update(runId, patch),
+      get: (runId) => runs.get(runId),
+      findActiveRun: (threadId) => runs.findActiveRun(threadId),
+    }
     expect(await findCrashedRuns(noList, 't1')).toEqual([])
   })
 
@@ -95,40 +98,30 @@ describe('crash recovery edges', () => {
     ]
     await persistence.stores.messages.saveThread('t1', history)
     const save = vi.spyOn(persistence.stores.messages, 'saveThread')
+    const repair = (checkpoint?: RunRecord['checkpoint']) =>
+      repairTranscript({
+        messages: persistence.stores.messages,
+        crashed: {
+          runId: 'r',
+          threadId: 't1',
+          status: 'running',
+          startedAt: 1,
+          ...(checkpoint ? { checkpoint } : {}),
+        },
+      })
 
     // Only safe tools pending: nothing to note.
-    await repairTranscript(persistence, {
-      runId: 'r',
-      threadId: 't1',
-      status: 'running',
-      startedAt: 1,
-      checkpoint: {
-        at: 1,
-        pendingTools: [
-          { toolCallId: 'call-b', name: 'lookup', replay: 'safe' },
-        ],
-      },
+    await repair({
+      at: 1,
+      pendingTools: [{ toolCallId: 'call-b', name: 'lookup', replay: 'safe' }],
     })
     // A never-replay tool that already has a result: nothing to note.
-    await repairTranscript(persistence, {
-      runId: 'r',
-      threadId: 't1',
-      status: 'running',
-      startedAt: 1,
-      checkpoint: {
-        at: 1,
-        pendingTools: [
-          { toolCallId: 'call-a', name: 'charge', replay: 'never' },
-        ],
-      },
+    await repair({
+      at: 1,
+      pendingTools: [{ toolCallId: 'call-a', name: 'charge', replay: 'never' }],
     })
     // No checkpoint at all.
-    await repairTranscript(persistence, {
-      runId: 'r',
-      threadId: 't1',
-      status: 'running',
-      startedAt: 1,
-    })
+    await repair()
     expect(save).not.toHaveBeenCalled()
     expect(
       JSON.stringify(await persistence.stores.messages.loadThread('t1')),
diff --git a/packages/ai-harness/tests/resume.test.ts b/packages/ai-harness/tests/resume.test.ts
index c57c045baf..2772f9818d 100644
--- a/packages/ai-harness/tests/resume.test.ts
+++ b/packages/ai-harness/tests/resume.test.ts
@@ -1,12 +1,48 @@
 import { describe, expect, it, vi } from 'vitest'
 import { z } from 'zod'
-import { EventType, toolDefinition } from '@tanstack/ai'
+import { EventType, chat, toolDefinition } from '@tanstack/ai'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { HARNESS_EVENTS, createHarnessHost, defineHarness } from '../src'
-import { INTERRUPTED_TOOL_RESULT, LEASE } from '../src/resume'
+import {
+  INTERRUPTED_TOOL_RESULT,
+  LEASE,
+  checkpointMiddleware,
+  repairTranscript,
+} from '../src/resume'
 import { gate, mockAdapter, text, toolCall } from './helpers'
+import type { AnyChatMiddleware, AnyTool, ModelMessage } from '@tanstack/ai'
 import type { SessionEvent } from '../src'
 
+/** Run one chat() turn with the checkpoint middleware and a fresh run record. */
+async function runWithCheckpoint(options: {
+  replies: Parameters<typeof mockAdapter>[0]
+  tools?: Array<AnyTool>
+  middleware: (
+    stores: ReturnType<typeof memoryPersistence>['stores'],
+  ) => AnyChatMiddleware
+}) {
+  const { stores } = memoryPersistence()
+  await stores.runs.createOrResume({
+    runId: 'run-1',
+    threadId: 't1',
+    startedAt: Date.now(),
+  })
+  const { adapter } = mockAdapter(options.replies)
+  const stream = chat({
+    adapter,
+    messages: [{ role: 'user', content: 'go' }],
+    tools: options.tools ?? [],
+    middleware: [options.middleware(stores)],
+    threadId: 't1',
+    runId: 'run-1',
+    stream: true,
+  })
+  for await (const _chunk of stream) {
+    // Run the turn to the end.
+  }
+  return stores
+}
+
 describe('checkpoints and leases', () => {
   it('holds a lease and records the running tool with its replay mode', async () => {
     const persistence = memoryPersistence()
@@ -140,6 +176,10 @@ describe('crash resume', () => {
         message.role === 'tool' && message.toolCallId === 'call-charge',
     )
     expect(chargeResult?.content).toBe(JSON.stringify(INTERRUPTED_TOOL_RESULT))
+    // The model gets the note as a tool error.
+    expect(chargeResult?.error).toBe(
+      'The tool may or may not have run. Check before you retry.',
+    )
     expect(transcript.at(-1)?.content).toBe('recovered')
 
     expect((await persistence.stores.runs.get('crashed-run'))?.status).toBe(
@@ -156,6 +196,66 @@ describe('crash resume', () => {
     await host.close()
   })
 
+  it('keeps the result of a tool that finished before the crash', async () => {
+    const { stores } = memoryPersistence()
+    await stores.messages.saveThread('t1', [
+      { id: 'u1', role: 'user', content: 'charge' },
+      {
+        id: 'a1',
+        role: 'assistant',
+        content: '',
+        toolCalls: [
+          {
+            id: 'call-charge',
+            type: 'function',
+            function: { name: 'charge', arguments: '{}' },
+          },
+          {
+            id: 'call-mail',
+            type: 'function',
+            function: { name: 'mail', arguments: '{}' },
+          },
+        ],
+      },
+    ])
+    const finished: ModelMessage = {
+      role: 'tool',
+      toolCallId: 'call-charge',
+      content: 'charged 100',
+    }
+
+    await repairTranscript({
+      messages: stores.messages,
+      crashed: {
+        runId: 'crashed',
+        threadId: 't1',
+        status: 'running',
+        startedAt: 1,
+        checkpoint: {
+          at: 1,
+          pendingTools: [
+            { toolCallId: 'call-charge', name: 'charge', replay: 'never' },
+            { toolCallId: 'call-mail', name: 'mail', replay: 'never' },
+          ],
+        },
+      },
+      finished: new Map([['call-charge', finished]]),
+    })
+
+    const tools = (await stores.messages.loadThread('t1')).filter(
+      (message) => message.role === 'tool',
+    )
+    expect(tools).toEqual([
+      { role: 'tool', toolCallId: 'call-charge', content: 'charged 100' },
+      {
+        role: 'tool',
+        toolCallId: 'call-mail',
+        content: JSON.stringify(INTERRUPTED_TOOL_RESULT),
+        error: 'The tool may or may not have run. Check before you retry.',
+      },
+    ])
+  })
+
   it('leaves a run alone while its lease is still valid', async () => {
     const persistence = memoryPersistence()
     await persistence.stores.runs.createOrResume({
@@ -183,3 +283,70 @@ describe('crash resume', () => {
     await host.close()
   })
 })
+
+describe('checkpoint middleware options', () => {
+  it('uses the lease time it gets', async () => {
+    const startedAt = Date.now()
+    const stores = await runWithCheckpoint({
+      replies: [() => text('done')],
+      middleware: ({ runs, messages }) =>
+        checkpointMiddleware({
+          runs,
+          messages,
+          hostId: 'host-a',
+          lease: { ttlMs: 5_000 },
+        }),
+    })
+
+    const record = await stores.runs.get('run-1')
+    expect(record?.leaseOwner).toBe('host-a')
+    // 5 seconds, not the default 30 seconds.
+    expect(record?.leaseExpiresAt).toBeGreaterThanOrEqual(startedAt + 5_000)
+    expect(record?.leaseExpiresAt).toBeLessThan(startedAt + 15_000)
+  })
+
+  it('gives onToolResult the tool message of each call that ends', async () => {
+    const seen: Array<{ toolCallId: string; message: ModelMessage }> = []
+    const tools = [
+      toolDefinition({ name: 'echo', description: 'Echo' }).server(
+        async () => 'echoed',
+      ),
+      toolDefinition({ name: 'boom', description: 'Fail' }).server(async () => {
+        throw new Error('boom failed')
+      }),
+    ]
+    await runWithCheckpoint({
+      replies: [
+        () => toolCall('echo', {}, 'call-echo'),
+        () => toolCall('boom', {}, 'call-boom'),
+        () => text('done'),
+      ],
+      tools,
+      middleware: ({ runs, messages }) =>
+        checkpointMiddleware({
+          runs,
+          messages,
+          hostId: 'host-a',
+          onToolResult: (info) => {
+            seen.push(info)
+          },
+        }),
+    })
+
+    expect(seen).toEqual([
+      {
+        toolCallId: 'call-echo',
+        message: { role: 'tool', toolCallId: 'call-echo', content: 'echoed' },
+      },
+      {
+        toolCallId: 'call-boom',
+        message: {
+          role: 'tool',
+          toolCallId: 'call-boom',
+          content: JSON.stringify({ error: 'boom failed' }),
+          error: 'boom failed',
+        },
+      },
+    ])
+  })
+})

From 0db128c6f6be1d331687c253dc7728d2d9307237 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 12:00:58 +0200
Subject: [PATCH 075/286] test(ai-harness): guard harness core against
 Node-only imports

Harness sessions run in edge runtimes. The test fails when a source file outside the Node entry points (build.ts, worker.ts, first-party/files.ts, first-party/workspace.ts) imports a Node built-in when the module loads. A lazy import('node:...') inside a function stays allowed.
---
 packages/ai-harness/tests/edge-safety.test.ts | 125 ++++++++++++++++++
 1 file changed, 125 insertions(+)
 create mode 100644 packages/ai-harness/tests/edge-safety.test.ts

diff --git a/packages/ai-harness/tests/edge-safety.test.ts b/packages/ai-harness/tests/edge-safety.test.ts
new file mode 100644
index 0000000000..f4c6b14f89
--- /dev/null
+++ b/packages/ai-harness/tests/edge-safety.test.ts
@@ -0,0 +1,125 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Harness sessions run in edge runtimes, for example inside a Cloudflare
+ * Durable Object. So the harness core must load without a Node-only module.
+ * Only the Node entry points in ALLOWED may import one. A lazy
+ * `await import('node:http')` inside a function is allowed everywhere: it runs
+ * only when that function runs (for example a loopback login on a laptop). This
+ * is a fast static check of the source files.
+ */
+
+const here = dirname(fileURLToPath(import.meta.url))
+const srcDir = resolve(here, '..', 'src')
+
+/** Node-only entry points, relative to `src`. */
+const ALLOWED = [
+  'build.ts',
+  'worker.ts',
+  'first-party/files.ts',
+  'first-party/workspace.ts',
+]
+
+const NODE_BUILTINS = [
+  'fs',
+  'path',
+  'os',
+  'child_process',
+  'worker_threads',
+  'module',
+  'vm',
+  'crypto',
+  'url',
+  'stream',
+  'events',
+  'util',
+  'http',
+  'https',
+  'net',
+  'tls',
+  'zlib',
+  'buffer',
+]
+
+// Any `node:` specifier, or a bare built-in with an optional `/subpath`, in a
+// form that loads with the module: `from '...'`, `import '...'`, and
+// `require('...')`. A dynamic `import('...')` does not match.
+const NODE_IMPORT = new RegExp(
+  `(?:from\\s*|import\\s+|require\\s*\\(\\s*)['"](?:node:[^'"]+|(?:${NODE_BUILTINS.join('|')})(?:/[^'"]*)?)['"]`,
+)
+
+function collectTsFiles(dir: string): Array<string> {
+  const files: Array<string> = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) files.push(...collectTsFiles(full))
+    else if (entry.name.endsWith('.ts')) files.push(full)
+  }
+  return files
+}
+
+// Remove comments but keep string literals, so an import named in a JSDoc
+// example does not count, and a `//` inside a string cannot hide an import.
+function stripComments(text: string): string {
+  return text.replace(
+    /(["'`])(?:\\.|(?!\1)[^\\])*\1|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g,
+    (match, quote: string | undefined) => (quote ? match : ''),
+  )
+}
+
+const importsNode = (source: string) => NODE_IMPORT.test(stripComments(source))
+
+describe('edge safety of the harness core', () => {
+  it('imports no Node-only module outside the Node entry points', () => {
+    const toPosix = (file: string) =>
+      relative(srcDir, file).split(sep).join('/')
+    const files = collectTsFiles(srcDir)
+    expect(files.length).toBeGreaterThan(0)
+
+    const offenders = files
+      .filter((file) => !ALLOWED.includes(toPosix(file)))
+      .filter((file) => importsNode(readFileSync(file, 'utf8')))
+      .map(toPosix)
+
+    expect(offenders).toEqual([])
+  })
+
+  it('lists only Node entry points that exist', () => {
+    const missing = ALLOWED.filter((file) => !existsSync(join(srcDir, file)))
+    expect(missing).toEqual([])
+  })
+})
+
+describe('edge safety check', () => {
+  it('flags a node: import and a bare built-in import', () => {
+    expect(importsNode(`import { readFile } from 'node:fs/promises'`)).toBe(
+      true,
+    )
+    expect(importsNode(`import { createHash } from 'crypto'`)).toBe(true)
+    expect(importsNode(`const fs = require('fs')`)).toBe(true)
+    expect(importsNode(`import 'node:process'`)).toBe(true)
+  })
+
+  it('allows a lazy dynamic import inside a function', () => {
+    expect(
+      importsNode(`async function f() { await import('node:http') }`),
+    ).toBe(false)
+  })
+
+  it('ignores an import that is only in a comment', () => {
+    expect(importsNode(`// import fs from 'node:fs'`)).toBe(false)
+    expect(importsNode(`/** import { join } from 'path' */`)).toBe(false)
+  })
+
+  it('flags a real import on a line with a comment-like string', () => {
+    expect(importsNode(`const s = "a//b"; import fs from 'fs'`)).toBe(true)
+  })
+
+  it('ignores packages whose names start like a built-in', () => {
+    expect(importsNode(`import { x } from 'events-polyfill'`)).toBe(false)
+    expect(importsNode(`import { chat } from '@tanstack/ai'`)).toBe(false)
+  })
+})

From 4a52a6aac1d080f0b8b5cc158b6c6f4e52ccb10e Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 12:01:27 +0200
Subject: [PATCH 076/286] chore: changeset for the harness durable session log

---
 .changeset/harness-durable-log.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
 create mode 100644 .changeset/harness-durable-log.md

diff --git a/.changeset/harness-durable-log.md b/.changeset/harness-durable-log.md
new file mode 100644
index 0000000000..c680ddd07a
--- /dev/null
+++ b/.changeset/harness-durable-log.md
@@ -0,0 +1,23 @@
+---
+'@tanstack/ai-persistence': minor
+'@tanstack/ai-harness': minor
+---
+
+Add a durable session log. A harness session can now keep its events, transcript, inputs, and tool steps in one append-only log, so a turn survives a crash, a retry does not run an input twice, and a tool does not repeat a finished side effect.
+
+`@tanstack/ai-persistence` adds the `LogStore` contract: `append` writes a batch at a position, all or nothing, and rejects with `LogConflictError` when another writer took that position. `read` and `subscribe` complete it. Put your store in `stores.log`. `defineLogStore` types an adapter, `memoryLogStore()` is the reference store, and `runPersistenceConformance` runs the log cases when `stores.log` is present.
+
+`@tanstack/ai-harness` turns on durable mode when the host gets `stores.log` and `stores.runs`:
+
+- `prompt`, `steer`, `followUp`, and `resolve` take an optional `inputId`. The same id with the same payload does not run again. `Operation.receipt` resolves when the input is stored, and `session.settled(inputId)` gives how an input ended, also after a restart.
+- `defineHarness({ durability: { maxAttempts, timeoutMs } })` limits each input. The default is 10 attempts and no timeout.
+- `durableTool(definition, execute)` gives a tool `step.do(name, fn)`. After a crash, a finished step returns its stored value and does not run again. The tool's `append(records)` adds host records to the same append as the tool batch.
+- `session.append(records)` adds host records to the log. The host option `project: { record, version }` folds host records into the model context. `logMessageStore` reads the transcript of a log outside a session.
+- Host options `coalesceMs` (default 100 ms in durable mode) and `lease: { ttlMs, renewMs }`. Clients get a `harness.input.settled` event when an input ends.
+- A `busy: 'steer'` prompt joins the running turn in the order it arrived, and it settles with that turn.
+
+Breaking changes in the harness:
+
+- `HarnessPersistence` is now a union of the current stores and the log stores.
+- After a crash, the note for a tool that may have run now sets `error`, so the model sees a tool error.
+- A steer that a turn did not reach is now answered in the same turn, not in a new turn.

From 8bbd84bf56e20d11346d1c0b775009f00f9fd074 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 12:04:41 +0200
Subject: [PATCH 077/286] feat(ai-harness): durableTool with step.do and staged
 append

durableTool(definition, execute) makes a server tool with replay 'safe'. execute gets step.do(name, fn) and append(records). A durable session binds them to the log with bindDurable. Outside a durable session, step.do runs fn each time and append throws.
---
 packages/ai-harness/src/durable-tool.ts       | 170 ++++++++++++++++++
 .../ai-harness/tests/durable-tool.test.ts     | 139 ++++++++++++++
 2 files changed, 309 insertions(+)
 create mode 100644 packages/ai-harness/src/durable-tool.ts
 create mode 100644 packages/ai-harness/tests/durable-tool.test.ts

diff --git a/packages/ai-harness/src/durable-tool.ts b/packages/ai-harness/src/durable-tool.ts
new file mode 100644
index 0000000000..1cb89d9674
--- /dev/null
+++ b/packages/ai-harness/src/durable-tool.ts
@@ -0,0 +1,170 @@
+import type {
+  AnyTool,
+  ApprovalSchemaConfig,
+  InferSchemaType,
+  SchemaInput,
+  ToolDefinition,
+  ToolExecutionContext,
+} from '@tanstack/ai'
+import type { LogRecord } from '@tanstack/ai-persistence'
+
+/** The durable steps of one tool call. */
+export interface ToolStep {
+  /**
+   * Run `fn` once for `name` in this tool call, and store its value in the
+   * session log before `do` resolves. When a crash makes the harness run the
+   * call again, a stored step returns its value and `fn` does not run again.
+   *
+   * A step is stored once and runs at least once: a crash after `fn` ends but
+   * before the value is stored runs `fn` again. The value must be JSON. Use a
+   * name that is the same on every run (for example `charge:${orderId}`).
+   * The same name twice in one call throws.
+   */
+  do: <T>(name: string, fn: () => T | Promise<T>) => Promise<T>
+}
+
+/** What the `execute` of a {@link durableTool} gets. */
+export type DurableToolContext<TContext = unknown> =
+  ToolExecutionContext<TContext> & {
+    step: ToolStep
+    /**
+     * Add host records to the session log with this tool batch. They land in
+     * the same append as the batch's transcript commit. If the batch never
+     * commits (a crash), the records never happened.
+     */
+    append: (records: ReadonlyArray<LogRecord>) => void
+  }
+
+type DurableExecute = (args: any, context: DurableToolContext) => unknown
+
+/**
+ * The key that keeps the durable `execute` on a tool. An own enumerable
+ * symbol key, so `{ ...tool }` in a plugin keeps it.
+ *
+ * @internal
+ */
+export const DURABLE_EXECUTE: unique symbol = Symbol(
+  'tanstack.ai-harness.durable-execute',
+)
+
+/** @internal Steps over `recorded` values, stored with `record`. */
+export function createToolStep(options: {
+  recorded: (name: string) => { found: true; value: unknown } | { found: false }
+  record: (name: string, value: unknown) => Promise<void>
+}) {
+  const used = new Set<string>()
+  const step = {
+    do: async <T>(name: string, fn: () => T | Promise<T>) => {
+      if (used.has(name)) {
+        throw new Error(
+          `step.do: the step name ${JSON.stringify(name)} is already used in this tool call.`,
+        )
+      }
+      used.add(name)
+      const stored = options.recorded(name)
+      // The log holds what an earlier run of this step returned.
+      if (stored.found) return stored.value as T
+      const value = await fn()
+      await options.record(name, value)
+      return value
+    },
+  } satisfies ToolStep
+  return step
+}
+
+const noLog = () => {
+  throw new Error(
+    'durableTool append needs a durable harness session (a host with stores.log).',
+  )
+}
+
+const emptyContext: ToolExecutionContext = { emitCustomEvent: () => {} }
+
+/**
+ * Make a server tool whose side effects survive a crash. `execute` gets
+ * `step` and `append` next to the normal tool context. Put each side effect
+ * in `step.do(name, fn)`: when a crash makes the harness run the call again,
+ * finished steps return their stored values. The tool has `replay: 'safe'`.
+ *
+ * Outside a durable harness session (plain `chat()`, or a host without
+ * `stores.log`), `step.do` runs `fn` each time and `append` throws.
+ *
+ * @example
+ * ```ts
+ * const createInvoice = durableTool(
+ *   toolDefinition({ name: 'create_invoice', description: 'Create an invoice', inputSchema }),
+ *   async ({ orderId }, { step }) => {
+ *     const invoice = await step.do(`create:${orderId}`, () => billing.create(orderId))
+ *     return { invoiceId: invoice.id }
+ *   },
+ * )
+ * ```
+ */
+export function durableTool<
+  TInput extends SchemaInput | undefined,
+  TOutput extends SchemaInput | undefined,
+  TName extends string,
+  TNeedsApproval extends boolean,
+  TApprovalSchema extends ApprovalSchemaConfig | undefined,
+>(
+  definition: ToolDefinition<
+    TInput,
+    TOutput,
+    TName,
+    TNeedsApproval,
+    TApprovalSchema
+  >,
+  execute: (
+    args: InferSchemaType<TInput>,
+    context: DurableToolContext,
+  ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
+) {
+  const tool = definition.server((args, context) =>
+    execute(args, {
+      ...(context ?? emptyContext),
+      step: createToolStep({
+        recorded: () => ({ found: false }),
+        record: async () => {},
+      }),
+      append: noLog,
+    }),
+  )
+  Object.defineProperty(tool, DURABLE_EXECUTE, {
+    value: execute,
+    enumerable: true,
+  })
+  return Object.assign(tool, { replay: 'safe' as const })
+}
+
+function isDurableTool(
+  tool: AnyTool,
+): tool is AnyTool & { [DURABLE_EXECUTE]: DurableExecute } {
+  return typeof Reflect.get(tool, DURABLE_EXECUTE) === 'function'
+}
+
+/**
+ * Give a {@link durableTool} the `step` and `append` of a durable session.
+ * `bind` gets the id of each call. Another tool comes back as it is.
+ *
+ * @internal
+ */
+export function bindDurable(
+  tool: AnyTool,
+  bind: (toolCallId: string) => {
+    step: ToolStep
+    append: DurableToolContext['append']
+  },
+) {
+  if (!isDurableTool(tool)) return tool
+  const execute = tool[DURABLE_EXECUTE]
+  return {
+    ...tool,
+    execute: (args: unknown, context?: ToolExecutionContext) => {
+      const base = context ?? emptyContext
+      if (!base.toolCallId) {
+        throw new Error('A durable tool call needs a tool call id.')
+      }
+      return execute(args, { ...base, ...bind(base.toolCallId) })
+    },
+  }
+}
diff --git a/packages/ai-harness/tests/durable-tool.test.ts b/packages/ai-harness/tests/durable-tool.test.ts
new file mode 100644
index 0000000000..d3ec3f2710
--- /dev/null
+++ b/packages/ai-harness/tests/durable-tool.test.ts
@@ -0,0 +1,139 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { EventType, chat, toolDefinition } from '@tanstack/ai'
+import { bindDurable, createToolStep, durableTool } from '../src/durable-tool'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { LogRecord } from '@tanstack/ai-persistence'
+
+const invoiceDefinition = toolDefinition({
+  name: 'create_invoice',
+  description: 'Create an invoice',
+  inputSchema: z.object({ orderId: z.string() }),
+})
+
+/** A step that remembers values in a map, like the session log does. */
+function mapStep(stored: Map<string, unknown>) {
+  return createToolStep({
+    recorded: (name) =>
+      stored.has(name)
+        ? { found: true, value: stored.get(name) }
+        : { found: false },
+    record: async (name, value) => {
+      stored.set(name, value)
+    },
+  })
+}
+
+describe('durableTool', () => {
+  it('runs in plain chat() and runs each step', async () => {
+    const create = vi.fn(async (orderId: string) => `inv-${orderId}`)
+    const tool = durableTool(invoiceDefinition, async ({ orderId }, ctx) => {
+      const invoiceId = await ctx.step.do(`create:${orderId}`, () =>
+        create(orderId),
+      )
+      return { invoiceId, callId: ctx.toolCallId }
+    })
+    const { adapter } = mockAdapter([
+      () => toolCall('create_invoice', { orderId: 'o1' }, 'call-9'),
+      () => text('done'),
+    ])
+
+    const results: Array<unknown> = []
+    for await (const chunk of chat({
+      adapter,
+      messages: [{ role: 'user', content: 'bill it' }],
+      tools: [tool],
+    })) {
+      if (chunk.type === EventType.TOOL_CALL_RESULT) results.push(chunk.content)
+    }
+
+    expect(tool.replay).toBe('safe')
+    expect(create).toHaveBeenCalledTimes(1)
+    expect(results).toEqual([
+      JSON.stringify({ invoiceId: 'inv-o1', callId: 'call-9' }),
+    ])
+  })
+
+  it('throws from append outside a durable session', async () => {
+    const tool = durableTool(invoiceDefinition, async (_args, ctx) => {
+      ctx.append([{ type: 'app.invoice_created' }])
+      return 'unreachable'
+    })
+
+    await expect(
+      Promise.resolve(tool.execute?.({ orderId: 'o1' })),
+    ).rejects.toThrow('durableTool append needs a durable harness session')
+  })
+})
+
+describe('createToolStep', () => {
+  it('returns a stored value without running the step again', async () => {
+    const stored = new Map<string, unknown>([['create:o1', 'inv-stored']])
+    const step = mapStep(stored)
+    const fresh = vi.fn(() => 'fresh')
+
+    expect(await step.do('create:o1', fresh)).toBe('inv-stored')
+    expect(fresh).not.toHaveBeenCalled()
+    expect(await step.do('send:o1', () => 'sent')).toBe('sent')
+    expect(stored.get('send:o1')).toBe('sent')
+  })
+
+  it('throws when a tool call uses a step name twice', async () => {
+    const step = mapStep(new Map())
+    await step.do('same', () => 1)
+
+    await expect(step.do('same', () => 2)).rejects.toThrow(
+      'the step name "same" is already used',
+    )
+  })
+})
+
+describe('bindDurable', () => {
+  it('gives a durable tool the bound step and append of its call', async () => {
+    const staged: Array<LogRecord> = []
+    const stored = new Map<string, unknown>([['create:o1', 'inv-stored']])
+    const tool = durableTool(invoiceDefinition, async ({ orderId }, ctx) => {
+      ctx.append([{ type: 'app.invoice_created', orderId }])
+      return ctx.step.do(`create:${orderId}`, () => 'inv-fresh')
+    })
+    const bound = bindDurable(tool, (toolCallId) => ({
+      step: mapStep(toolCallId === 'call-1' ? stored : new Map()),
+      append: (records) => staged.push(...records),
+    }))
+
+    const result = await bound.execute?.(
+      { orderId: 'o1' },
+      { toolCallId: 'call-1', emitCustomEvent: () => {} },
+    )
+
+    expect(result).toBe('inv-stored')
+    expect(staged).toEqual([{ type: 'app.invoice_created', orderId: 'o1' }])
+  })
+
+  it('keeps the durable marker when a plugin copies the tool', async () => {
+    const tool = durableTool(invoiceDefinition, async (_args, ctx) =>
+      ctx.step.do('only', () => 'fresh'),
+    )
+    const bound = bindDurable({ ...tool }, () => ({
+      step: mapStep(new Map([['only', 'bound']])),
+      append: () => {},
+    }))
+
+    expect(
+      await bound.execute?.(
+        { orderId: 'o1' },
+        { toolCallId: 'call-1', emitCustomEvent: () => {} },
+      ),
+    ).toBe('bound')
+  })
+
+  it('returns a tool that is not durable as it is', () => {
+    const plain = invoiceDefinition.server(async () => 'plain')
+    expect(
+      bindDurable(plain, () => ({
+        step: mapStep(new Map()),
+        append: () => {},
+      })),
+    ).toBe(plain)
+  })
+})

From 6b7b9977daac345d2289a30717996fc4d6598c14 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 12:14:08 +0200
Subject: [PATCH 078/286] feat(ai-harness): session log writer, fold,
 checkpoints, and logMessageStore

LogWriter appends records at the next position of the thread log, one batch at a time. It merges adjacent text, reasoning, and tool-argument deltas, and it keeps the fold of the log: the transcript, the inputs, the tool results, and the tool steps. Host records fold into the transcript through a pure project.record function. A fold checkpoint in the metadata store makes a cold load shorter. logMessageStore gives a MessageStore view of a log.
---
 packages/ai-harness/src/durable-tool.ts |   2 +-
 packages/ai-harness/src/log.ts          | 798 ++++++++++++++++++++++++
 packages/ai-harness/src/utils.ts        |   3 +
 packages/ai-harness/tests/log.test.ts   | 526 ++++++++++++++++
 4 files changed, 1328 insertions(+), 1 deletion(-)
 create mode 100644 packages/ai-harness/src/log.ts
 create mode 100644 packages/ai-harness/src/utils.ts
 create mode 100644 packages/ai-harness/tests/log.test.ts

diff --git a/packages/ai-harness/src/durable-tool.ts b/packages/ai-harness/src/durable-tool.ts
index 1cb89d9674..f718e1ada6 100644
--- a/packages/ai-harness/src/durable-tool.ts
+++ b/packages/ai-harness/src/durable-tool.ts
@@ -35,7 +35,7 @@ export type DurableToolContext<TContext = unknown> =
     append: (records: ReadonlyArray<LogRecord>) => void
   }
 
-type DurableExecute = (args: any, context: DurableToolContext) => unknown
+type DurableExecute = (args: unknown, context: DurableToolContext) => unknown
 
 /**
  * The key that keeps the durable `execute` on a tool. An own enumerable
diff --git a/packages/ai-harness/src/log.ts b/packages/ai-harness/src/log.ts
new file mode 100644
index 0000000000..5071d0b7c1
--- /dev/null
+++ b/packages/ai-harness/src/log.ts
@@ -0,0 +1,798 @@
+import { EventType } from '@tanstack/ai'
+import { LogConflictError } from '@tanstack/ai-persistence'
+import { isRecord } from './utils'
+import type { ModelMessage, StreamChunk } from '@tanstack/ai'
+import type {
+  LogEntry,
+  LogRecord,
+  LogStore,
+  MessageStore,
+  MetadataStore,
+} from '@tanstack/ai-persistence'
+import type { EventFeed } from './feed'
+import type {
+  Cursor,
+  HarnessInput,
+  InputSettlement,
+  SessionEvent,
+} from './types'
+
+/** The records the harness writes to a session log. */
+export type HarnessRecord =
+  | { type: 'harness.event'; operationId: string; event: StreamChunk }
+  | { type: 'harness.transcript'; keep: number; add: Array<ModelMessage> }
+  | {
+      type: 'harness.input'
+      inputId: string
+      input: HarnessInput
+      principal?: { id: string }
+      at: number
+    }
+  | {
+      type: 'harness.input.applied'
+      inputId: string
+      operationId: string
+      attempt: number
+      timeoutAt?: number
+    }
+  | { type: 'harness.input.joined'; inputId: string; into: string }
+  | { type: 'harness.input.rejected'; inputId: string; reason: string }
+  | { type: 'harness.input.abort'; inputId: string }
+  | {
+      type: 'harness.input.settled'
+      inputId: string
+      outcome: InputSettlement['outcome']
+      operationId?: string
+      error?: InputSettlement['error']
+    }
+  | { type: 'harness.tool.result'; toolCallId: string; message: ModelMessage }
+  | {
+      type: 'harness.tool.step'
+      toolCallId: string
+      name: string
+      value: unknown
+    }
+
+const HARNESS_RECORD_TYPES = new Set<string>([
+  'harness.event',
+  'harness.transcript',
+  'harness.input',
+  'harness.input.applied',
+  'harness.input.joined',
+  'harness.input.rejected',
+  'harness.input.abort',
+  'harness.input.settled',
+  'harness.tool.result',
+  'harness.tool.step',
+])
+
+// The harness wrote every record of these types, so the fields are its own.
+function isHarnessRecord(record: LogRecord): record is HarnessRecord {
+  return HARNESS_RECORD_TYPES.has(record.type)
+}
+
+/**
+ * Fold one host record into the model context. Return the new message list,
+ * or `undefined` for no change. It must be pure: the same log always folds to
+ * the same context, live and after a restart.
+ */
+export type ProjectRecord = (args: {
+  messages: ReadonlyArray<ModelMessage>
+  record: LogRecord
+}) => Array<ModelMessage> | undefined
+
+/** How a host folds its own records into the model context. */
+export interface ProjectOptions {
+  record: ProjectRecord
+  /**
+   * The version of `record`. A fold checkpoint with another version is
+   * ignored, so a change to `record` never reads an old fold.
+   */
+  version?: string
+}
+
+/** What the log knows about one input. */
+export interface InputState {
+  inputId: string
+  input: HarnessInput
+  principal?: { id: string }
+  at: number
+  status: 'pending' | 'applied' | 'joined' | 'rejected' | 'settled'
+  operationId?: string
+  attempt: number
+  timeoutAt?: number
+  /** The host input that this input joined. */
+  into?: string
+  abortRequested: boolean
+  /** Transcript length when the input was last applied. */
+  appliedAt?: number
+  settlement?: InputSettlement
+  reason?: string
+}
+
+/** The fold of a session log. */
+export interface LogState {
+  /** The position of the last folded record. */
+  seq: number
+  messages: Array<ModelMessage>
+  /** In admission order. */
+  inputs: Map<string, InputState>
+  toolResults: Map<string, ModelMessage>
+  /** By {@link stepKey}. */
+  steps: Map<string, unknown>
+}
+
+export function emptyLogState() {
+  const state: LogState = {
+    seq: 0,
+    messages: [],
+    inputs: new Map(),
+    toolResults: new Map(),
+    steps: new Map(),
+  }
+  return state
+}
+
+export const stepKey = (toolCallId: string, name: string) =>
+  `${toolCallId}\u0000${name}`
+
+/** A JSON copy: what a store gives back for `record`. */
+const normalize = <T>(value: T) => JSON.parse(JSON.stringify(value)) as T
+
+const sameJson = (left: unknown, right: unknown) =>
+  JSON.stringify(left) === JSON.stringify(right)
+
+/** A message out of the log gets its `createdAt` back as a `Date`. */
+function revive(message: ModelMessage) {
+  const createdAt: unknown = message.createdAt
+  return typeof createdAt === 'string'
+    ? { ...message, createdAt: new Date(createdAt) }
+    : message
+}
+
+/** How many messages at the start of `a` and `b` are the same. */
+export function commonPrefix(
+  a: ReadonlyArray<ModelMessage>,
+  b: ReadonlyArray<ModelMessage>,
+) {
+  const length = Math.min(a.length, b.length)
+  let index = 0
+  while (index < length && sameJson(a[index], b[index])) index += 1
+  return index
+}
+
+/** The transcript record that turns `current` into `next`, or none. */
+function transcriptRecord(
+  current: ReadonlyArray<ModelMessage>,
+  next: ReadonlyArray<ModelMessage>,
+): Array<HarnessRecord> {
+  const keep = commonPrefix(current, next)
+  const isSame = keep === current.length && keep === next.length
+  if (isSame) return []
+  return [
+    { type: 'harness.transcript', keep, add: normalize(next.slice(keep)) },
+  ]
+}
+
+function updateInput(
+  state: LogState,
+  inputId: string,
+  change: (input: InputState) => InputState,
+) {
+  const input = state.inputs.get(inputId)
+  if (input) state.inputs.set(inputId, change(input))
+}
+
+/** Fold one entry into `state`. */
+export function foldEntry(
+  state: LogState,
+  entry: LogEntry,
+  project?: ProjectRecord,
+) {
+  state.seq = entry.seq
+  const { record } = entry
+  if (!record.type.startsWith('harness.')) {
+    const next = project?.({ messages: state.messages, record })
+    if (next) state.messages = next
+    return
+  }
+  // A harness record type from a newer version is skipped.
+  if (!isHarnessRecord(record)) return
+  switch (record.type) {
+    case 'harness.event':
+      return
+    case 'harness.transcript':
+      state.messages = [
+        ...state.messages.slice(0, record.keep),
+        ...record.add.map(revive),
+      ]
+      return
+    case 'harness.input':
+      if (state.inputs.has(record.inputId)) return
+      state.inputs.set(record.inputId, {
+        inputId: record.inputId,
+        input: record.input,
+        ...(record.principal ? { principal: record.principal } : {}),
+        at: record.at,
+        status: 'pending',
+        attempt: 0,
+        abortRequested: false,
+      })
+      return
+    case 'harness.input.applied': {
+      const appliedAt = state.messages.length
+      updateInput(state, record.inputId, (input) => ({
+        ...input,
+        status: 'applied',
+        operationId: record.operationId,
+        attempt: record.attempt,
+        appliedAt,
+        ...(record.timeoutAt !== undefined
+          ? { timeoutAt: record.timeoutAt }
+          : {}),
+      }))
+      return
+    }
+    case 'harness.input.joined':
+      updateInput(state, record.inputId, (input) => ({
+        ...input,
+        status: 'joined',
+        into: record.into,
+      }))
+      return
+    case 'harness.input.rejected':
+      updateInput(state, record.inputId, (input) => ({
+        ...input,
+        status: 'rejected',
+        reason: record.reason,
+      }))
+      return
+    case 'harness.input.abort':
+      updateInput(state, record.inputId, (input) => ({
+        ...input,
+        abortRequested: true,
+      }))
+      return
+    case 'harness.input.settled':
+      updateInput(state, record.inputId, (input) => ({
+        ...input,
+        status: 'settled',
+        settlement: {
+          inputId: record.inputId,
+          outcome: record.outcome,
+          ...(record.operationId ? { operationId: record.operationId } : {}),
+          ...(record.error ? { error: record.error } : {}),
+        },
+      }))
+      return
+    case 'harness.tool.result':
+      state.toolResults.set(record.toolCallId, record.message)
+      return
+    case 'harness.tool.step':
+      state.steps.set(stepKey(record.toolCallId, record.name), record.value)
+      return
+  }
+}
+
+const CHECKPOINT_NAMESPACE = 'harness:log-checkpoint'
+// ponytail: a checkpoint every 50 appends. Tune it when a cold fold is slow.
+const CHECKPOINT_EVERY = 50
+const READ_PAGE = 500
+// ponytail: the in-memory event tail, like SessionFeed. Older cursors page
+// from the store.
+const MAX_TAIL = 10_000
+
+function serialize(state: LogState, version: string | undefined) {
+  return {
+    v: 1,
+    seq: state.seq,
+    ...(version !== undefined ? { version } : {}),
+    state: {
+      messages: state.messages,
+      inputs: [...state.inputs.values()],
+      toolResults: [...state.toolResults.entries()],
+      steps: [...state.steps.entries()],
+    },
+  }
+}
+
+/** A checkpoint that the harness wrote with `version`, or `undefined`. */
+function parseCheckpoint(value: unknown, version: string | undefined) {
+  if (!isRecord(value) || value.v !== 1) return undefined
+  if (typeof value.seq !== 'number' || value.version !== version)
+    return undefined
+  const saved = value.state
+  if (!isRecord(saved)) return undefined
+  const { messages, inputs, toolResults, steps } = saved
+  const isShaped =
+    Array.isArray(messages) &&
+    Array.isArray(inputs) &&
+    Array.isArray(toolResults) &&
+    Array.isArray(steps)
+  if (!isShaped) return undefined
+  // The harness wrote these arrays with `serialize`.
+  const state: LogState = {
+    seq: value.seq,
+    messages: (messages as Array<ModelMessage>).map(revive),
+    inputs: new Map(
+      (inputs as Array<InputState>).map((input) => [input.inputId, input]),
+    ),
+    toolResults: new Map(toolResults as Array<[string, ModelMessage]>),
+    steps: new Map(steps as Array<[string, unknown]>),
+  }
+  return state
+}
+
+/**
+ * Fold the log of `threadId`. With `metadata`, start from the newest fold
+ * checkpoint when it is valid for this log and this `project.version`.
+ */
+export async function loadLogState(options: {
+  store: LogStore
+  threadId: string
+  metadata?: MetadataStore
+  project?: ProjectOptions
+}) {
+  const { store, threadId, metadata, project } = options
+  const saved = metadata
+    ? await metadata.get(CHECKPOINT_NAMESPACE, threadId).catch(() => null)
+    : null
+  let state = parseCheckpoint(saved, project?.version) ?? emptyLogState()
+  if (state.seq > 0) {
+    // A checkpoint past the end of the log belongs to another log.
+    const [atCheckpoint] = await store.read(threadId, {
+      after: state.seq - 1,
+      limit: 1,
+    })
+    if (!atCheckpoint) state = emptyLogState()
+  }
+  for (;;) {
+    const page = await store.read(threadId, {
+      after: state.seq,
+      limit: READ_PAGE,
+    })
+    for (const entry of page) foldEntry(state, entry, project?.record)
+    if (page.length < READ_PAGE) return state
+  }
+}
+
+const DELTA_TYPES = new Set<string>([
+  EventType.TEXT_MESSAGE_CONTENT,
+  EventType.REASONING_MESSAGE_CONTENT,
+  EventType.TOOL_CALL_ARGS,
+])
+
+/** The fields of a delta event that must match for a merge. */
+function deltaKey(operationId: string, event: StreamChunk) {
+  if (!DELTA_TYPES.has(event.type) || !('delta' in event)) return undefined
+  const { delta: _delta, timestamp: _timestamp, ...rest } = event
+  return JSON.stringify([operationId, rest])
+}
+
+/**
+ * Writes a session log and keeps its fold. It is also the session's
+ * {@link EventFeed}: every reader reads the log.
+ *
+ * All writes run one after another. Each batch goes at the next position.
+ * When a write fails (another writer took the position, or the store failed
+ * twice), the writer calls `onFailure`, and every later write rejects.
+ */
+export class LogWriter implements EventFeed {
+  readonly threadId: string
+  readonly state: LogState
+  private readonly store: LogStore
+  private readonly project: ProjectOptions | undefined
+  private readonly metadata: MetadataStore | undefined
+  private readonly coalesceMs: number
+  private readonly onFailure: (error: unknown) => void
+  /** Events and host records that wait for the next append. */
+  private readonly pending: Array<LogRecord> = []
+  /** The merge key of the last pending record, when it is a delta event. */
+  private pendingKey: string | undefined
+  /** Host records that wait for the next transcript commit. */
+  private readonly staged: Array<LogRecord> = []
+  private timer: ReturnType<typeof setTimeout> | undefined
+  private scheduled = false
+  private chain: Promise<void> = Promise.resolve()
+  private failure: unknown
+  private readonly tail: Array<SessionEvent> = []
+  /** Every event after this position is in `tail`. */
+  private tailFrom: number
+  private readonly waiters = new Set<() => void>()
+  private closed = false
+  private writing = false
+  private writesSinceCheckpoint = 0
+  private readonly unsubscribe: () => void
+
+  constructor(options: {
+    store: LogStore
+    threadId: string
+    state: LogState
+    project?: ProjectOptions
+    metadata?: MetadataStore
+    coalesceMs: number
+    onFailure: (error: unknown) => void
+  }) {
+    this.store = options.store
+    this.threadId = options.threadId
+    this.state = options.state
+    this.project = options.project
+    this.metadata = options.metadata
+    this.coalesceMs = options.coalesceMs
+    this.onFailure = options.onFailure
+    this.tailFrom = options.state.seq
+    // Records from another writer (this host only reads) join the fold. A
+    // call during this writer's own append is its own records.
+    this.unsubscribe = options.store.subscribe(options.threadId, () => {
+      if (!this.writing) void this.enqueue(() => this.catchUp())
+    })
+  }
+
+  // ===========================
+  // Writes
+  // ===========================
+
+  publish(operationId: string, event: StreamChunk): void {
+    const record: HarnessRecord = {
+      type: 'harness.event',
+      operationId,
+      event: normalize(event),
+    }
+    const key = deltaKey(operationId, record.event)
+    const last = this.pending.at(-1)
+    const isSameDelta =
+      key !== undefined &&
+      key === this.pendingKey &&
+      last !== undefined &&
+      isHarnessRecord(last) &&
+      last.type === 'harness.event'
+    if (isSameDelta) last.event = mergeDelta(last.event, record.event)
+    else this.pending.push(record)
+    this.pendingKey = key
+    if (key === undefined) {
+      void this.flush().catch(() => {})
+      return
+    }
+    this.schedule()
+  }
+
+  /** Append `records` after the pending events, in one batch. */
+  append(records: ReadonlyArray<LogRecord>): Promise<void> {
+    this.pending.push(...records.map(normalize))
+    this.pendingKey = undefined
+    return this.flush()
+  }
+
+  /** Hold `records` until the next transcript commit. */
+  stage(records: ReadonlyArray<LogRecord>): void {
+    this.staged.push(...records.map(normalize))
+  }
+
+  /**
+   * One batch: the pending events, the transcript change to `messages` (if
+   * any), the staged records, then `records`.
+   */
+  commit(options: {
+    messages: ReadonlyArray<ModelMessage>
+    records?: ReadonlyArray<LogRecord>
+  }): Promise<void> {
+    const events = this.takePending()
+    const staged = this.staged.splice(0)
+    const records = (options.records ?? []).map(normalize)
+    return this.enqueue(() =>
+      this.write([
+        ...events,
+        ...transcriptRecord(this.state.messages, options.messages),
+        ...staged,
+        ...records,
+      ]),
+    )
+  }
+
+  /** Append the pending events now. */
+  flush(): Promise<void> {
+    const batch = this.takePending()
+    return this.enqueue(() => this.write(batch))
+  }
+
+  private takePending() {
+    if (this.timer !== undefined) clearTimeout(this.timer)
+    this.timer = undefined
+    this.scheduled = false
+    this.pendingKey = undefined
+    return this.pending.splice(0)
+  }
+
+  private schedule() {
+    if (this.scheduled) return
+    this.scheduled = true
+    if (this.coalesceMs <= 0) {
+      queueMicrotask(() => void this.flush().catch(() => {}))
+      return
+    }
+    this.timer = setTimeout(
+      () => void this.flush().catch(() => {}),
+      this.coalesceMs,
+    )
+    // A coalescing timer must not keep a CLI or a test process alive.
+    if (typeof this.timer === 'object' && 'unref' in this.timer) {
+      this.timer.unref()
+    }
+  }
+
+  private enqueue(task: () => Promise<void>) {
+    const run = this.chain.then(task)
+    this.chain = run.catch(() => {})
+    return run
+  }
+
+  private async write(batch: ReadonlyArray<LogRecord>) {
+    if (this.failure !== undefined) throw this.failure
+    if (batch.length === 0) return
+    const seq = this.state.seq + 1
+    this.writing = true
+    try {
+      await this.appendOnce(seq, batch)
+    } catch (error) {
+      this.failure = error
+      this.onFailure(error)
+      throw error
+    } finally {
+      this.writing = false
+    }
+    batch.forEach((record, index) => this.apply({ seq: seq + index, record }))
+    this.writesSinceCheckpoint += 1
+    if (this.writesSinceCheckpoint >= CHECKPOINT_EVERY) {
+      this.writesSinceCheckpoint = 0
+      // A lost checkpoint only makes the next cold fold longer.
+      void this.metadata
+        ?.set(
+          CHECKPOINT_NAMESPACE,
+          this.threadId,
+          normalize(serialize(this.state, this.project?.version)),
+        )
+        .catch(() => {})
+    }
+    this.wake()
+  }
+
+  /**
+   * Append once. After an error, read back: the batch may have landed before
+   * the error. When it did not land, a conflict fails at once, and another
+   * error gets one more try.
+   */
+  private async appendOnce(seq: number, batch: ReadonlyArray<LogRecord>) {
+    try {
+      await this.store.append(this.threadId, seq, batch)
+      return
+    } catch (error) {
+      if (await this.landed(seq, batch)) return
+      if (error instanceof LogConflictError) throw error
+    }
+    try {
+      await this.store.append(this.threadId, seq, batch)
+    } catch (error) {
+      if (await this.landed(seq, batch)) return
+      throw error
+    }
+  }
+
+  private async landed(seq: number, batch: ReadonlyArray<LogRecord>) {
+    try {
+      const entries = await this.store.read(this.threadId, {
+        after: seq - 1,
+        limit: batch.length,
+      })
+      return (
+        entries.length === batch.length &&
+        entries.every((entry, index) => sameJson(entry.record, batch[index]))
+      )
+    } catch {
+      return false
+    }
+  }
+
+  /** Fold records that another writer appended. */
+  private async catchUp() {
+    const entries = await this.store.read(this.threadId, {
+      after: this.state.seq,
+    })
+    for (const entry of entries) this.apply(entry)
+    if (entries.length > 0) this.wake()
+  }
+
+  private apply(entry: LogEntry) {
+    foldEntry(this.state, entry, this.project?.record)
+    const { record } = entry
+    if (!isHarnessRecord(record) || record.type !== 'harness.event') return
+    this.tail.push({
+      cursor: String(entry.seq),
+      operationId: record.operationId,
+      event: record.event,
+    })
+    if (this.tail.length > MAX_TAIL) {
+      const dropped = this.tail.shift()
+      if (dropped) this.tailFrom = Number(dropped.cursor)
+    }
+  }
+
+  // ===========================
+  // Reads
+  // ===========================
+
+  head(): Cursor {
+    return String(this.state.seq)
+  }
+
+  async *read(options: {
+    from?: Cursor
+    signal?: AbortSignal
+    filter?: (entry: SessionEvent) => boolean
+    until?: () => boolean
+  }): AsyncIterable<SessionEvent> {
+    const { signal, filter, until } = options
+    const accepts = (entry: SessionEvent) => (filter ? filter(entry) : true)
+    let after = Number(options.from ?? '0')
+    if (!Number.isFinite(after)) after = 0
+    for (;;) {
+      if (signal?.aborted) return
+      if (after < this.tailFrom) {
+        // Older than the in-memory tail: page it from the store.
+        const upTo = this.tailFrom
+        const page = await this.store.read(this.threadId, {
+          after,
+          limit: READ_PAGE,
+        })
+        for (const entry of page) {
+          if (entry.seq > upTo || signal?.aborted) break
+          after = entry.seq
+          const event = sessionEventOf(entry)
+          if (event && accepts(event)) yield event
+        }
+        if (page.length === 0) after = upTo
+        continue
+      }
+      const next = this.tail.filter(
+        (entry) => Number(entry.cursor) > after && accepts(entry),
+      )
+      for (const entry of next) {
+        if (signal?.aborted) return
+        after = Number(entry.cursor)
+        yield entry
+      }
+      // Skip past records that are not events or that the filter rejected.
+      if (next.length === 0) after = Math.max(after, this.state.seq)
+      if (this.closed || until?.()) {
+        for (const entry of this.tail) {
+          if (Number(entry.cursor) > after && accepts(entry)) yield entry
+        }
+        return
+      }
+      // A write while the reader handled `next` woke nobody: scan again.
+      if (next.length > 0) continue
+      await this.waitForNext(signal)
+    }
+  }
+
+  close(): void {
+    void this.flush().catch(() => {})
+    this.closed = true
+    this.unsubscribe()
+    this.wake()
+  }
+
+  private wake() {
+    const waiters = [...this.waiters]
+    this.waiters.clear()
+    for (const wake of waiters) wake()
+  }
+
+  private waitForNext(signal?: AbortSignal) {
+    return new Promise<void>((resolve) => {
+      if (signal?.aborted) return resolve()
+      const done = () => {
+        signal?.removeEventListener('abort', done)
+        this.waiters.delete(done)
+        resolve()
+      }
+      this.waiters.add(done)
+      signal?.addEventListener('abort', done, { once: true })
+    })
+  }
+}
+
+/** Join two adjacent deltas of one message or tool call. */
+function mergeDelta(first: StreamChunk, second: StreamChunk): StreamChunk {
+  const rest =
+    'delta' in second && typeof second.delta === 'string'
+      ? second.delta
+      : undefined
+  if (rest === undefined) return second
+  if (
+    first.type === EventType.TEXT_MESSAGE_CONTENT ||
+    first.type === EventType.REASONING_MESSAGE_CONTENT ||
+    first.type === EventType.TOOL_CALL_ARGS
+  ) {
+    return { ...first, delta: first.delta + rest, timestamp: second.timestamp }
+  }
+  return second
+}
+
+function sessionEventOf(entry: LogEntry) {
+  const { record } = entry
+  if (!isHarnessRecord(record) || record.type !== 'harness.event') {
+    return undefined
+  }
+  const event: SessionEvent = {
+    cursor: String(entry.seq),
+    operationId: record.operationId,
+    event: record.event,
+  }
+  return event
+}
+
+/**
+ * The `MessageStore` a durable session gives `withPersistence`. Its own
+ * thread goes through the session's writer. Another thread (a subagent
+ * transcript) reads and appends that thread's log directly.
+ */
+export function sessionMessageStore(options: {
+  writer: LogWriter
+  store: LogStore
+  project?: ProjectOptions
+}) {
+  const { writer } = options
+  const other = logMessageStore({
+    store: options.store,
+    ...(options.project ? { project: options.project } : {}),
+  })
+  const messages: MessageStore = {
+    loadThread: async (threadId: string) =>
+      threadId === writer.threadId
+        ? [...writer.state.messages]
+        : other.loadThread(threadId),
+    saveThread: (threadId, list) =>
+      threadId === writer.threadId
+        ? writer.commit({ messages: list })
+        : other.saveThread(threadId, list),
+  }
+  return messages
+}
+
+/**
+ * A `MessageStore` view of a session log, for a reader outside a session
+ * (for example `reconstructChat`). `loadThread` folds the log. `saveThread`
+ * appends the change as one transcript record.
+ *
+ * @example
+ * ```ts
+ * reconstructChat({ persistence: { stores: { messages: logMessageStore({ store: log }) } }, ... })
+ * ```
+ */
+export function logMessageStore(options: {
+  store: LogStore
+  project?: ProjectOptions
+}) {
+  const { store, project } = options
+  const load = (threadId: string) =>
+    loadLogState({ store, threadId, ...(project ? { project } : {}) })
+  const messages: MessageStore = {
+    loadThread: async (threadId: string) => (await load(threadId)).messages,
+    saveThread: async (threadId, list) => {
+      // ponytail: one retry after a conflict. The loser of a real race
+      // reloads, so a second conflict is an error.
+      for (let attempt = 1; ; attempt += 1) {
+        const state = await load(threadId)
+        const records = transcriptRecord(state.messages, list)
+        if (records.length === 0) return
+        try {
+          await store.append(threadId, state.seq + 1, records)
+          return
+        } catch (error) {
+          if (!(error instanceof LogConflictError) || attempt === 2) throw error
+        }
+      }
+    },
+  }
+  return messages
+}
diff --git a/packages/ai-harness/src/utils.ts b/packages/ai-harness/src/utils.ts
new file mode 100644
index 0000000000..533bad5e0d
--- /dev/null
+++ b/packages/ai-harness/src/utils.ts
@@ -0,0 +1,3 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
diff --git a/packages/ai-harness/tests/log.test.ts b/packages/ai-harness/tests/log.test.ts
new file mode 100644
index 0000000000..d32fd0925e
--- /dev/null
+++ b/packages/ai-harness/tests/log.test.ts
@@ -0,0 +1,526 @@
+import { describe, expect, it } from 'vitest'
+import { EventType } from '@tanstack/ai'
+import {
+  LogConflictError,
+  memoryLogStore,
+  memoryPersistence,
+} from '@tanstack/ai-persistence'
+import {
+  LogWriter,
+  emptyLogState,
+  loadLogState,
+  logMessageStore,
+  sessionMessageStore,
+} from '../src/log'
+import type { ModelMessage, StreamChunk } from '@tanstack/ai'
+import type {
+  LogRecord,
+  LogStore,
+  MetadataStore,
+} from '@tanstack/ai-persistence'
+import type { ProjectOptions } from '../src/log'
+import type { SessionEvent } from '../src/types'
+
+const THREAD = 't1'
+
+function newWriter(
+  store: LogStore,
+  options: {
+    coalesceMs?: number
+    project?: ProjectOptions
+    metadata?: MetadataStore
+    onFailure?: (error: unknown) => void
+    state?: ReturnType<typeof emptyLogState>
+  } = {},
+) {
+  return new LogWriter({
+    store,
+    threadId: THREAD,
+    state: options.state ?? emptyLogState(),
+    coalesceMs: options.coalesceMs ?? 0,
+    onFailure: options.onFailure ?? (() => {}),
+    ...(options.project ? { project: options.project } : {}),
+    ...(options.metadata ? { metadata: options.metadata } : {}),
+  })
+}
+
+/** A store that records the record types of each append batch. */
+function recordingStore(inner: LogStore = memoryLogStore()) {
+  const batches: Array<Array<string>> = []
+  const store: LogStore = {
+    append: async (threadId, seq, records) => {
+      await inner.append(threadId, seq, records)
+      batches.push(records.map((record) => record.type))
+    },
+    read: (threadId, options) => inner.read(threadId, options),
+    subscribe: (threadId, listener) => inner.subscribe(threadId, listener),
+  }
+  return { store, batches }
+}
+
+/** A view of `inner` that never notifies, like a store in another process. */
+function silentStore(inner: LogStore): LogStore {
+  return {
+    append: (threadId, seq, records) => inner.append(threadId, seq, records),
+    read: (threadId, options) => inner.read(threadId, options),
+    subscribe: () => () => {},
+  }
+}
+
+const records = async (store: LogStore, threadId = THREAD) =>
+  (await store.read(threadId)).map((entry) => entry.record)
+
+const user = (id: string, content: string): ModelMessage => ({
+  id,
+  role: 'user',
+  content,
+})
+const assistant = (id: string, content: string): ModelMessage => ({
+  id,
+  role: 'assistant',
+  content,
+})
+
+const textStart = (messageId: string): StreamChunk => ({
+  type: EventType.TEXT_MESSAGE_START,
+  messageId,
+  role: 'assistant',
+  timestamp: 1,
+})
+const textDelta = (messageId: string, delta: string): StreamChunk => ({
+  type: EventType.TEXT_MESSAGE_CONTENT,
+  messageId,
+  delta,
+  timestamp: 2,
+})
+const textEnd = (messageId: string): StreamChunk => ({
+  type: EventType.TEXT_MESSAGE_END,
+  messageId,
+  timestamp: 3,
+})
+
+/** Signals become user messages. A compaction keeps a summary and a tail. */
+const project: ProjectOptions = {
+  version: 'v1',
+  record: ({ messages, record }) => {
+    if (record.type === 'app.signal' && typeof record.text === 'string') {
+      return [...messages, { role: 'user', content: record.text }]
+    }
+    if (
+      record.type === 'app.compact' &&
+      typeof record.summary === 'string' &&
+      typeof record.firstKept === 'number'
+    ) {
+      return [
+        { role: 'assistant', content: record.summary },
+        ...messages.slice(record.firstKept),
+      ]
+    }
+    return undefined
+  },
+}
+
+describe('transcript fold', () => {
+  it('writes each change as one splice record and folds it back', async () => {
+    const store = memoryLogStore()
+    const writer = newWriter(store)
+    const u1 = user('u1', 'hi')
+    const a1 = assistant('a1', 'hello')
+
+    await writer.commit({ messages: [u1, a1] })
+    await writer.commit({ messages: [u1, a1, user('u2', 'more')] })
+    await writer.commit({ messages: [u1, assistant('x', 'edited')] })
+    await writer.commit({ messages: [u1] })
+    // No change: no record.
+    await writer.commit({ messages: [u1] })
+
+    expect(await records(store)).toEqual([
+      { type: 'harness.transcript', keep: 0, add: [u1, a1] },
+      { type: 'harness.transcript', keep: 2, add: [user('u2', 'more')] },
+      { type: 'harness.transcript', keep: 1, add: [assistant('x', 'edited')] },
+      { type: 'harness.transcript', keep: 1, add: [] },
+    ])
+    expect(writer.state.messages).toEqual([u1])
+    expect((await loadLogState({ store, threadId: THREAD })).messages).toEqual([
+      u1,
+    ])
+  })
+
+  it('folds host records through the projection, live and after a reload', async () => {
+    const store = memoryLogStore()
+    const writer = newWriter(store, { project })
+    const u1 = user('u1', 'hi')
+    const a1 = assistant('a1', 'hello')
+    await writer.commit({ messages: [u1, a1] })
+
+    await writer.append([{ type: 'app.signal', text: 'ping' }])
+    expect(writer.state.messages).toEqual([
+      u1,
+      a1,
+      { role: 'user', content: 'ping' },
+    ])
+
+    await writer.append([
+      { type: 'app.compact', summary: 'Earlier: greetings.', firstKept: 2 },
+    ])
+    const compacted = [
+      { role: 'assistant', content: 'Earlier: greetings.' },
+      { role: 'user', content: 'ping' },
+    ]
+    expect(writer.state.messages).toEqual(compacted)
+
+    // The next save adds only its new message. The projected messages are
+    // not written twice.
+    const a2 = assistant('a2', 'pong')
+    await writer.commit({ messages: [...writer.state.messages, a2] })
+    expect((await records(store)).at(-1)).toEqual({
+      type: 'harness.transcript',
+      keep: 2,
+      add: [a2],
+    })
+
+    const reloaded = await loadLogState({ store, threadId: THREAD, project })
+    expect(reloaded.messages).toEqual([...compacted, a2])
+  })
+
+  it('keeps live state equal to reloaded state for values that are not JSON', async () => {
+    const store = memoryLogStore()
+    const writer = newWriter(store)
+    const createdAt = new Date('2026-09-30T10:00:00.000Z')
+
+    await writer.commit({
+      messages: [
+        {
+          id: 'u1',
+          role: 'user',
+          content: 'hi',
+          createdAt,
+          metadata: { dropped: undefined },
+        },
+      ],
+    })
+
+    const expected = [
+      { id: 'u1', role: 'user', content: 'hi', createdAt, metadata: {} },
+    ]
+    expect(writer.state.messages).toEqual(expected)
+    expect((await loadLogState({ store, threadId: THREAD })).messages).toEqual(
+      expected,
+    )
+  })
+})
+
+describe('events and batches', () => {
+  it('merges adjacent deltas and flushes at a boundary', async () => {
+    const store = memoryLogStore()
+    // A long window: only the boundary can flush in time.
+    const writer = newWriter(store, { coalesceMs: 60_000 })
+
+    writer.publish('op-1', textStart('m1'))
+    writer.publish('op-1', textDelta('m1', 'a'))
+    writer.publish('op-1', textDelta('m1', 'b'))
+    writer.publish('op-1', textDelta('m2', 'other message'))
+    writer.publish('op-1', textDelta('m2', ' again'))
+    writer.publish('op-1', textEnd('m1'))
+    await writer.flush()
+
+    const events = (await records(store)).map((record) => record.event)
+    expect(events).toEqual([
+      textStart('m1'),
+      textDelta('m1', 'ab'),
+      textDelta('m2', 'other message again'),
+      textEnd('m1'),
+    ])
+  })
+
+  it('puts host records in the same batch as the pending events, in order', async () => {
+    const { store, batches } = recordingStore()
+    const writer = newWriter(store, { coalesceMs: 60_000 })
+
+    writer.publish('op-1', textDelta('m1', 'streaming'))
+    await writer.append([{ type: 'app.state_write', name: 'x', value: 1 }])
+
+    expect(batches).toEqual([['harness.event', 'app.state_write']])
+  })
+
+  it('writes concurrent appends in order, with no gap', async () => {
+    const store = memoryLogStore()
+    const failures: Array<unknown> = []
+    const writer = newWriter(store, { onFailure: (e) => failures.push(e) })
+
+    writer.publish('op-1', textStart('m1'))
+    await Promise.all([
+      writer.append([{ type: 'app.a' }]),
+      writer.append([{ type: 'app.b' }]),
+      writer.commit({ messages: [user('u1', 'hi')] }),
+      writer.flush(),
+    ])
+
+    const entries = await store.read(THREAD)
+    expect(entries.map((entry) => [entry.seq, entry.record.type])).toEqual([
+      [1, 'harness.event'],
+      [2, 'app.a'],
+      [3, 'app.b'],
+      [4, 'harness.transcript'],
+    ])
+    expect(failures).toEqual([])
+    expect(writer.state.seq).toBe(4)
+  })
+
+  it('reads events after a cursor from the store, then live', async () => {
+    const store = memoryLogStore()
+    const first = newWriter(store)
+    first.publish('op-a', textStart('m1'))
+    first.publish('op-b', textStart('m2'))
+    first.publish('op-a', textEnd('m1'))
+    await first.flush()
+    first.close()
+
+    // A new session: the first events are only in the store.
+    const state = await loadLogState({ store, threadId: THREAD })
+    const writer = newWriter(store, { state })
+    let done = false
+    const seen: Array<SessionEvent> = []
+    const reading = (async () => {
+      for await (const entry of writer.read({
+        from: '1',
+        filter: (item) => item.operationId === 'op-a',
+        until: () => done,
+      })) {
+        seen.push(entry)
+      }
+    })()
+    writer.publish('op-a', textStart('m3'))
+    await writer.flush()
+    done = true
+    writer.publish('op-a', textEnd('m3'))
+    await writer.flush()
+    await reading
+
+    expect(seen.map((entry) => [entry.cursor, entry.event])).toEqual([
+      ['3', textEnd('m1')],
+      ['4', textStart('m3')],
+      ['5', textEnd('m3')],
+    ])
+  })
+
+  it('folds records that another writer appends to the same store', async () => {
+    const store = memoryLogStore()
+    const reader = newWriter(store)
+    const other = newWriter(silentStore(store))
+
+    other.publish('op-1', textStart('m1'))
+    await other.flush()
+    await other.commit({ messages: [user('u1', 'from the other host')] })
+
+    await expect.poll(() => reader.state.seq).toBe(2)
+    expect(reader.state.messages).toEqual([user('u1', 'from the other host')])
+  })
+})
+
+describe('write failures', () => {
+  it('calls onFailure on a conflict and rejects every later write', async () => {
+    const store = memoryLogStore()
+    const failures: Array<unknown> = []
+    const stale = newWriter(silentStore(store), {
+      onFailure: (error) => failures.push(error),
+    })
+    await store.append(THREAD, 1, [{ type: 'app.from-another-host' }])
+
+    await expect(stale.append([{ type: 'app.late' }])).rejects.toBeInstanceOf(
+      LogConflictError,
+    )
+    await expect(stale.append([{ type: 'app.later' }])).rejects.toBeInstanceOf(
+      LogConflictError,
+    )
+    expect(failures).toHaveLength(1)
+    expect((await records(store)).map((record) => record.type)).toEqual([
+      'app.from-another-host',
+    ])
+  })
+
+  it('counts a batch that landed before an error as written', async () => {
+    const inner = memoryLogStore()
+    let calls = 0
+    const flaky: LogStore = {
+      ...silentStore(inner),
+      append: async (threadId, seq, batch) => {
+        calls += 1
+        await inner.append(threadId, seq, batch)
+        if (calls === 1) throw new Error('timeout after the write')
+      },
+    }
+    const writer = newWriter(flaky)
+
+    await writer.append([{ type: 'app.one' }])
+    await writer.append([{ type: 'app.two' }])
+
+    expect((await records(inner)).map((record) => record.type)).toEqual([
+      'app.one',
+      'app.two',
+    ])
+    expect(calls).toBe(2)
+  })
+
+  it('tries once more after a store error, then fails with that error', async () => {
+    let calls = 0
+    const down: LogStore = {
+      ...silentStore(memoryLogStore()),
+      append: async () => {
+        calls += 1
+        throw new Error('network down')
+      },
+    }
+    const failures: Array<unknown> = []
+    const writer = newWriter(down, { onFailure: (e) => failures.push(e) })
+
+    await expect(writer.append([{ type: 'app.one' }])).rejects.toThrow(
+      'network down',
+    )
+    await expect(writer.append([{ type: 'app.two' }])).rejects.toThrow(
+      'network down',
+    )
+    expect(calls).toBe(2)
+    expect(failures).toHaveLength(1)
+  })
+})
+
+describe('fold checkpoints', () => {
+  const NAMESPACE = 'harness:log-checkpoint'
+
+  async function seedLog(store: LogStore) {
+    const writer = newWriter(store)
+    await writer.commit({ messages: [user('u1', 'one')] })
+    await writer.commit({ messages: [user('u1', 'one'), user('u2', 'two')] })
+    writer.close()
+  }
+
+  const checkpoint = (overrides: Record<string, unknown>) => ({
+    v: 1,
+    seq: 1,
+    version: 'v1',
+    state: {
+      messages: [user('marker', 'from the checkpoint')],
+      inputs: [],
+      toolResults: [],
+      steps: [],
+    },
+    ...overrides,
+  })
+
+  it('starts the fold from a valid checkpoint', async () => {
+    const store = memoryLogStore()
+    await seedLog(store)
+    const { metadata } = memoryPersistence().stores
+    await metadata.set(NAMESPACE, THREAD, checkpoint({}))
+
+    const state = await loadLogState({
+      store,
+      threadId: THREAD,
+      metadata,
+      project,
+    })
+
+    // Record 2 folds on top of the checkpoint (keep 1, add u2).
+    expect(state.messages).toEqual([
+      user('marker', 'from the checkpoint'),
+      user('u2', 'two'),
+    ])
+  })
+
+  it.each([
+    ['not an object', 'garbage'],
+    ['another format', checkpoint({ v: 2 })],
+    ['another projection version', checkpoint({ version: 'v0' })],
+    ['a position past the end of the log', checkpoint({ seq: 99 })],
+    ['a state that is not shaped', checkpoint({ state: { messages: 'x' } })],
+  ])('ignores a checkpoint with %s', async (_name, value) => {
+    const store = memoryLogStore()
+    await seedLog(store)
+    const { metadata } = memoryPersistence().stores
+    await metadata.set(NAMESPACE, THREAD, value)
+
+    const state = await loadLogState({
+      store,
+      threadId: THREAD,
+      metadata,
+      project,
+    })
+
+    expect(state.messages).toEqual([user('u1', 'one'), user('u2', 'two')])
+  })
+
+  it('writes a checkpoint every 50 appends', async () => {
+    const store = memoryLogStore()
+    const { metadata } = memoryPersistence().stores
+    const writer = newWriter(store, { metadata, project })
+
+    for (let index = 0; index < 50; index += 1) {
+      await writer.append([{ type: 'app.tick', index }])
+    }
+
+    await expect
+      .poll(() => metadata.get(NAMESPACE, THREAD))
+      .toMatchObject({ v: 1, seq: 50, version: 'v1' })
+  })
+})
+
+describe('message stores', () => {
+  it('logMessageStore writes a change as one record and reads the fold', async () => {
+    const store = memoryLogStore()
+    const messages = logMessageStore({ store })
+    const u1 = user('u1', 'hi')
+    const a1 = assistant('a1', 'hello')
+
+    await messages.saveThread('t9', [u1])
+    await messages.saveThread('t9', [u1, a1])
+
+    expect(await messages.loadThread('t9')).toEqual([u1, a1])
+    expect(await records(store, 't9')).toEqual([
+      { type: 'harness.transcript', keep: 0, add: [u1] },
+      { type: 'harness.transcript', keep: 1, add: [a1] },
+    ])
+  })
+
+  it('logMessageStore reloads and tries once more after a conflict', async () => {
+    const inner = memoryLogStore()
+    let raced = false
+    const racing: LogStore = {
+      ...silentStore(inner),
+      append: async (threadId, seq, batch) => {
+        if (!raced) {
+          raced = true
+          // Another writer takes the position first.
+          await inner.append(threadId, seq, [{ type: 'app.other' }])
+        }
+        await inner.append(threadId, seq, batch)
+      },
+    }
+
+    await logMessageStore({ store: racing }).saveThread('t9', [
+      user('u1', 'hi'),
+    ])
+
+    expect((await records(inner, 't9')).map((record) => record.type)).toEqual([
+      'app.other',
+      'harness.transcript',
+    ])
+  })
+
+  it('sessionMessageStore uses the writer for its thread and the log for others', async () => {
+    const store = memoryLogStore()
+    const writer = newWriter(store)
+    const messages = sessionMessageStore({ writer, store })
+
+    await messages.saveThread(THREAD, [user('u1', 'main')])
+    await messages.saveThread('subagent:1', [user('c1', 'child')])
+
+    expect(writer.state.messages).toEqual([user('u1', 'main')])
+    expect(await messages.loadThread(THREAD)).toEqual([user('u1', 'main')])
+    expect(await messages.loadThread('subagent:1')).toEqual([
+      user('c1', 'child'),
+    ])
+    const child: Array<LogRecord> = await records(store, 'subagent:1')
+    expect(child).toHaveLength(1)
+  })
+})

From 892aac479f35f79866c05d8011d36ee14cc0352f Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 12:15:52 +0200
Subject: [PATCH 079/286] docs(persistence): the LogStore contract for backend
 authors

store-reference gets a LogStore section with the append, read, and subscribe rules and a SQL sketch. build-your-own-adapter says that a durable harness host needs log and runs, and that the conformance suite runs the log cases when stores.log is present.
---
 docs/persistence/build-your-own-adapter.md |  8 +++
 docs/persistence/store-reference.md        | 71 ++++++++++++++++++++--
 2 files changed, 75 insertions(+), 4 deletions(-)

diff --git a/docs/persistence/build-your-own-adapter.md b/docs/persistence/build-your-own-adapter.md
index b4573b8cd2..8a3543711b 100644
--- a/docs/persistence/build-your-own-adapter.md
+++ b/docs/persistence/build-your-own-adapter.md
@@ -85,6 +85,10 @@ with a tick:
 - **Sandbox files need a checkpoint store too.** That store lives on
   `@tanstack/ai-sandbox`, not in this table. See
   [Keep Files After Reload](../sandbox/portable-snapshots-configure).
+- **A durable harness host needs `log` and `runs`.** The log holds the transcript, so
+  that host takes no `messages` store. See the
+  [`LogStore` contract](./store-reference#logstore) and
+  [Durable sessions](../harness/durable-sessions).
 
 The common production shape is `messages` + `runs` + `interrupts`. When you
 keep generated files or rebuild sandbox files, add `artifacts` and `blobs`.
@@ -175,6 +179,10 @@ The optional run methods are `listByThread`, `listByParentRun`, and
 `skipMethods`. An omitted `listByParentRun` needs no entry: the subagent checks
 skip on their own.
 
+The `log` cases run when your persistence has `stores.log`. They check the atomic
+batch, the `LogConflictError` for a taken position or a gap, `read` with `after` and
+`limit`, and `subscribe`. A backend without a log needs no `skip` entry for it.
+
 ### Turn on the newer checks
 
 Some checks were added after the suite shipped. They are off by default, so an
diff --git a/docs/persistence/store-reference.md b/docs/persistence/store-reference.md
index 2a4bbcd8ef..ec9ce032ba 100644
--- a/docs/persistence/store-reference.md
+++ b/docs/persistence/store-reference.md
@@ -16,6 +16,7 @@ there is no separate enable list.
 | `generationRuns` | Generation run status and result metadata, keyed by its own `runId`. | `withGenerationPersistence`, required |
 | `artifacts` | File metadata. Needs `blobs`. | `withGenerationPersistence`, portable snapshots |
 | `blobs` | File bytes. Needs `artifacts`. | `withGenerationPersistence`, portable snapshots |
+| `log` | Append-only session log per thread. | Durable harness hosts, with `runs` |
 
 Named groupings of the chat stores (`ChatTranscriptStores`, `ChatPersistenceStores`,
 `ChatWithInterruptsStores`) are covered in [Controls](./controls).
@@ -540,6 +541,67 @@ asserts it. Ignoring `range` and returning the whole file is what makes
 entire artifact for every seek. A reference-only backend that stores no bytes
 skips `blobs` altogether instead.
 
+## LogStore
+
+A durable harness host keeps each thread's events, transcript, inputs, and tool
+steps in one append-only log. `LogStore` stores that log.
+
+```ts
+interface LogRecord {
+  type: string
+  [key: string]: unknown
+}
+
+interface LogEntry {
+  seq: number
+  record: LogRecord
+}
+
+interface LogStore {
+  append(
+    threadId: string,
+    seq: number,
+    records: ReadonlyArray<LogRecord>,
+  ): Promise<void>
+  read(
+    threadId: string,
+    options?: { after?: number; limit?: number },
+  ): Promise<Array<LogEntry>>
+  subscribe(threadId: string, listener: () => void): () => void
+}
+```
+
+- `append` writes the batch at `seq`, `seq + 1`, and so on. The first record of a
+  thread is at `1`.
+- The batch is atomic. Write all of it or none of it, in one transaction.
+- `seq` must be the next free position. For a taken position or a gap, reject with
+  `LogConflictError` from `@tanstack/ai-persistence`, and write nothing. This is how
+  the harness finds a second host that writes the same thread.
+- An empty batch writes nothing.
+- `read` returns the entries after `after`, in `seq` order, at most `limit`. A thread
+  with no records returns `[]`. Return copies, so a caller cannot change the log.
+- `subscribe` calls `listener` after each append that the store can see. A store that
+  cannot see appends from other processes can poll, or call only for its own appends.
+
+In SQL, a primary key on `(thread_id, seq)` gives the conflict rule. Insert the batch
+in one transaction, and map the key violation to `LogConflictError`:
+
+```sql
+CREATE TABLE harness_log (
+  thread_id TEXT NOT NULL,
+  seq INTEGER NOT NULL,
+  record TEXT NOT NULL,
+  PRIMARY KEY (thread_id, seq)
+);
+```
+
+A key violation covers a taken position. A gap needs one more check in the same
+transaction: `seq` must equal `MAX(seq) + 1` for the thread, or `1`.
+
+Each record is JSON. Store it as text or as a JSON column. The harness writes the
+record types that start with `harness.`, and a host adds its own types. The store does
+not read them.
+
 ## How the records relate
 
 The thread is not a table of its own: it exists as the `thread_id` the other records
@@ -597,11 +659,12 @@ erDiagram
 
 Each store has a `define*Store` helper (`defineMessageStore`, `defineRunStore`,
 `defineInterruptStore`, `defineMetadataStore`, `defineGenerationRunStore`,
-`defineArtifactStore`, `defineBlobStore`). They compose into `defineAIPersistence`,
-which tracks exact presence: the stores you passed autocomplete on
-`persistence.stores`, and reading one you did not pass is a compile error.
+`defineArtifactStore`, `defineBlobStore`, `defineLogStore`). They compose into
+`defineAIPersistence`, which tracks exact presence: the stores you passed autocomplete
+on `persistence.stores`, and reading one you did not pass is a compile error.
 
-Those seven keys are the only ones `stores` accepts. Anything else throws
+The keys in the table at the top are the only ones `stores` accepts, together with the
+harness keys `inbox` and `credentials`. Anything else throws
 `Unknown AIPersistence store key` at construction.
 
 To annotate the value instead, use a named shape:

From 6d593fa7ca358faee353ba8c2d012e4cf0da5373 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 12:28:41 +0200
Subject: [PATCH 080/286] feat(ai-harness): durable mode with a session log
 (events, transcript, host records)

A host with stores.log and stores.runs runs its sessions in durable mode. The session log is the event feed and the transcript. withPersistence and the checkpoints save through an engine view of the log: before each model call it commits the engine's messages and gives the model the fold, so the live context and a rebuild of the log are the same. session.append adds host records, and the host option project folds them into the context. A write conflict or a store failure stops the session.

HarnessPersistence is now a union of the current stores and the log stores. createHarnessHost takes project, coalesceMs, and lease.
---
 packages/ai-harness/src/host.ts               | 102 ++++-
 packages/ai-harness/src/index.ts              |  11 +-
 packages/ai-harness/src/log.ts                |  74 ++++
 packages/ai-harness/src/session.ts            | 200 ++++++++--
 .../ai-harness/tests/durable-session.test.ts  | 374 ++++++++++++++++++
 packages/ai-harness/tests/log.test.ts         | 112 ++++++
 6 files changed, 824 insertions(+), 49 deletions(-)
 create mode 100644 packages/ai-harness/tests/durable-session.test.ts

diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
index 7766cabc88..f8fb449cae 100644
--- a/packages/ai-harness/src/host.ts
+++ b/packages/ai-harness/src/host.ts
@@ -1,5 +1,6 @@
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { HarnessSession } from './session'
+import type { RunStore } from '@tanstack/ai'
 import type {
   AIPersistence,
   ArtifactStore,
@@ -8,29 +9,65 @@ import type {
   CredentialStore,
   GenerationRunStore,
   InboxStore,
+  InterruptStore,
+  LogStore,
+  MetadataStore,
 } from '@tanstack/ai-persistence'
 import type { AnyHarness } from './define'
+import type { ProjectOptions } from './log'
+import type { LeaseOptions } from './resume'
 import type { Principal } from './types'
 
+type SharedStores = {
+  credentials?: CredentialStore
+  artifacts?: ArtifactStore
+  blobs?: BlobStore
+  generationRuns?: GenerationRunStore
+}
+
 /**
- * The stores a host needs: a message store, plus any of runs, interrupts,
- * metadata, and inbox. Without an inbox, inputs are kept in memory and a
- * restart loses the ones not yet applied. Without `artifacts`, `blobs`, and
- * `generationRuns`, media is kept in memory too.
+ * The stores a host needs. Two shapes:
+ *
+ * - A message store, plus any of runs, interrupts, metadata, and inbox.
+ *   Without an inbox, inputs are kept in memory and a restart loses the ones
+ *   not yet applied.
+ * - Durable mode: a `log` and `runs`. The log holds the events, transcript,
+ *   inputs, and tool steps of each thread, so this shape has no `messages`
+ *   and no `inbox`.
+ *
+ * Without `artifacts`, `blobs`, and `generationRuns`, media is kept in memory.
  */
-export type HarnessPersistence = AIPersistence<
-  ChatTranscriptStores & {
-    inbox?: InboxStore
-    credentials?: CredentialStore
-    artifacts?: ArtifactStore
-    blobs?: BlobStore
-    generationRuns?: GenerationRunStore
-  }
->
+export type HarnessPersistence =
+  | AIPersistence<
+      ChatTranscriptStores & { inbox?: InboxStore; log?: never } & SharedStores
+    >
+  | AIPersistence<
+      {
+        log: LogStore
+        runs: RunStore
+        interrupts?: InterruptStore
+        metadata?: MetadataStore
+        messages?: never
+        inbox?: never
+      } & SharedStores
+    >
 
 export interface HarnessHostOptions {
   /** Where sessions keep their state. Default: in memory, lost on restart. */
   persistence?: HarnessPersistence
+  /**
+   * How a durable host folds your own log records into the model context.
+   * Only a host with `stores.log` reads it.
+   */
+  project?: ProjectOptions
+  /**
+   * How long a durable host merges streamed text before it appends it to the
+   * log, in milliseconds. Boundaries (a message start or end, a tool call, a
+   * run event) append at once. Default 100.
+   */
+  coalesceMs?: number
+  /** How long a run lease lasts, and how often the host renews it. */
+  lease?: LeaseOptions
 }
 
 export interface OpenSessionOptions {
@@ -56,6 +93,22 @@ export interface HarnessHost {
 
 let warned = false
 
+/** Throw a clear error for a durable store set that cannot work. */
+function checkDurableStores(persistence: HarnessPersistence) {
+  const { stores } = persistence
+  if (stores.log === undefined) return
+  if (stores.runs === undefined) {
+    throw new Error(
+      'A durable host (stores.log) needs stores.runs: run leases find a crashed host.',
+    )
+  }
+  if (stores.messages !== undefined || stores.inbox !== undefined) {
+    throw new Error(
+      'A durable host (stores.log) keeps the transcript and the inputs in the log. Remove stores.messages and stores.inbox. A reader outside a session can use logMessageStore({ store }).',
+    )
+  }
+}
+
 /**
  * Create a host for harness sessions.
  *
@@ -75,18 +128,20 @@ export function createHarnessHost(
       '[@tanstack/ai-harness] No persistence given: sessions live in memory and are lost on restart.',
     )
   }
-  const persistence = options.persistence ?? memoryPersistence()
+  const persistence: HarnessPersistence =
+    options.persistence ?? memoryPersistence()
+  checkDurableStores(persistence)
+  const memory = memoryPersistence().stores
   // ponytail: a memory inbox when the stores have none. Pass `stores.inbox`
-  // to keep accepted inputs across restarts.
-  const inbox = persistence.stores.inbox ?? memoryPersistence().stores.inbox
+  // to keep accepted inputs across restarts. A durable host keeps them in
+  // the log instead.
+  const inbox = persistence.stores.inbox ?? memory.inbox
   // ponytail: memory credentials when the stores have none. Pass
   // `stores.credentials` to keep sign-ins across restarts.
-  const credentials =
-    persistence.stores.credentials ?? memoryPersistence().stores.credentials
+  const credentials = persistence.stores.credentials ?? memory.credentials
   // ponytail: memory media stores when the stores have none. Pass
   // `stores.artifacts`, `stores.blobs`, and `stores.generationRuns` to keep
   // media across restarts.
-  const memory = memoryPersistence().stores
   const media = {
     stores: {
       artifacts: persistence.stores.artifacts ?? memory.artifacts,
@@ -95,6 +150,13 @@ export function createHarnessHost(
         persistence.stores.generationRuns ?? memory.generationRuns,
     },
   }
+  const log = persistence.stores.log
+    ? {
+        store: persistence.stores.log,
+        coalesceMs: options.coalesceMs ?? 100,
+        ...(options.project ? { project: options.project } : {}),
+      }
+    : undefined
   const sessions = new Map<string, Promise<HarnessSession>>()
   const hostId = `host-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`
 
@@ -111,6 +173,8 @@ export function createHarnessHost(
           credentials,
           media,
           hostId,
+          ...(log ? { log } : {}),
+          ...(options.lease ? { lease: options.lease } : {}),
           ...(principal ? { principal } : {}),
           onClose: () => sessions.delete(key),
         })
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index 6ae1431c6f..252d46f869 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -4,9 +4,17 @@ export type {
   HarnessAgentsOf,
   HarnessConfig,
   HarnessDefinition,
+  HarnessDurability,
   HarnessSubagents,
 } from './define'
 
+export { durableTool } from './durable-tool'
+export type { DurableToolContext, ToolStep } from './durable-tool'
+
+export { logMessageStore } from './log'
+export type { ProjectOptions, ProjectRecord } from './log'
+export type { LeaseOptions } from './resume'
+
 export { definePlugin } from './plugins'
 export type {
   HarnessPlugin,
@@ -74,12 +82,13 @@ export type {
   SessionSnapshot,
 } from './session'
 
-export { HARNESS_EVENTS } from './types'
+export { HARNESS_EVENTS, InputRejectedError } from './types'
 export type {
   BusyPolicy,
   ChatTurnResult,
   Cursor,
   HarnessInput,
+  InputSettlement,
   MediaKind,
   MediaRecord,
   Operation,
diff --git a/packages/ai-harness/src/log.ts b/packages/ai-harness/src/log.ts
index 5071d0b7c1..008a5afafd 100644
--- a/packages/ai-harness/src/log.ts
+++ b/packages/ai-harness/src/log.ts
@@ -759,6 +759,80 @@ export function sessionMessageStore(options: {
   return messages
 }
 
+/**
+ * The `MessageStore` the chat engine of a durable session saves through
+ * (`withPersistence` and the checkpoints). It remembers the list the engine
+ * holds. A host record can change the fold while the engine runs, and the
+ * engine does not see that until its next model call. So a save that only
+ * adds messages to what the engine holds puts them on top of the current
+ * fold, and a projected message is not lost. `beforeModel` commits the
+ * engine's list and gives the model the fold, so the two are the same at
+ * every model call.
+ */
+export function engineMessageStore(options: {
+  writer: LogWriter
+  store: LogStore
+  project?: ProjectOptions
+}) {
+  const { writer } = options
+  const shared = sessionMessageStore(options)
+  const fold = () => [...writer.state.messages]
+  let held = fold()
+  /**
+   * What to write for an engine save of `list`, when the engine held `base`:
+   *
+   * - The fold only added host messages after `base`: the engine's new
+   *   messages go first, then the host messages. So a signal never lands
+   *   between a tool call and its result.
+   * - A host record rewrote the fold (a compaction): the engine's new
+   *   messages go after the rewritten fold.
+   * - The engine changed older messages itself (a compaction middleware):
+   *   `list` wins.
+   */
+  const rebase = (base: Array<ModelMessage>, list: Array<ModelMessage>) => {
+    const current = writer.state.messages
+    const isEngineExtension = commonPrefix(base, list) === base.length
+    if (!isEngineExtension) return list
+    const added = list.slice(base.length)
+    const isFoldExtension = commonPrefix(base, current) === base.length
+    return isFoldExtension
+      ? [...base, ...added, ...current.slice(base.length)]
+      : [...current, ...added]
+  }
+  const engine = {
+    loadThread: async (threadId: string) => {
+      if (threadId !== writer.threadId) return shared.loadThread(threadId)
+      held = fold()
+      return [...held]
+    },
+    saveThread: (threadId: string, list: Array<ModelMessage>) => {
+      if (threadId !== writer.threadId) return shared.saveThread(threadId, list)
+      const target = rebase(held, list)
+      held = [...list]
+      return writer.commit({ messages: target })
+    },
+    /**
+     * Before each model call: commit the engine's `list` (it has the tool
+     * results of the last phase) on top of the fold. Returns the list the
+     * model gets when a host record changed it, else `undefined`.
+     */
+    beforeModel: async (list: ReadonlyArray<ModelMessage>) => {
+      const target = rebase(held, [...list])
+      held = [...target]
+      await writer.commit({ messages: target })
+      const isSame =
+        target.length === list.length &&
+        commonPrefix(target, list) === list.length
+      return isSame ? undefined : [...target]
+    },
+  } satisfies MessageStore & {
+    beforeModel: (
+      list: ReadonlyArray<ModelMessage>,
+    ) => Promise<Array<ModelMessage> | undefined>
+  }
+  return engine
+}
+
 /**
  * A `MessageStore` view of a session log, for a reader outside a session
  * (for example `reconstructChat`). `loadThread` folds the log. `saveThread`
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index bdde6de1da..15712e2933 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -12,9 +12,15 @@ import {
 } from '@tanstack/ai'
 import { credentialsFor, providerKeysFor } from './auth'
 import { checkConfigValue } from './config'
-import { withPersistence } from '@tanstack/ai-persistence'
+import { LogConflictError, withPersistence } from '@tanstack/ai-persistence'
 import { AgentRegistry } from './agents'
 import { SessionFeed } from './feed'
+import {
+  LogWriter,
+  engineMessageStore,
+  loadLogState,
+  sessionMessageStore,
+} from './log'
 import { createMediaStore, mediaCapture, mediaMiddleware } from './media'
 import { mediaIdOf, mediaOfMessage } from './media-ref'
 import { OperationImpl } from './operation'
@@ -44,12 +50,19 @@ import type {
   BlobBody,
   BlobRange,
   BlobStore,
+  ChatTranscriptStores,
   CredentialStore,
   GenerationRunStore,
   InboxEntry,
   InboxStore,
+  LogRecord,
+  LogStore,
+  MessageStore,
 } from '@tanstack/ai-persistence'
 import type { AuthRequiredError, CredentialsAccess } from './auth'
+import type { EventFeed } from './feed'
+import type { ProjectOptions } from './log'
+import type { LeaseOptions } from './resume'
 import type { MediaStore } from './media'
 import type { PluginSessionApi, Question } from './commands'
 import type { ConfigOption } from './config'
@@ -195,6 +208,9 @@ export interface SessionDependencies {
   principal?: Principal
   /** Identifies this host on run leases. */
   hostId: string
+  /** The session log of a durable host. */
+  log?: { store: LogStore; coalesceMs: number; project?: ProjectOptions }
+  lease?: LeaseOptions
   onClose: () => void
 }
 
@@ -252,6 +268,14 @@ export function acceptedKinds(
   return accepts.filter((kind) => modalities.includes(kind))
 }
 
+const notOpen = () => Promise.reject(new Error('The session is not open yet.'))
+
+/** The message store of a durable session before `open()` reads its log. */
+const notOpenMessages: MessageStore = {
+  loadThread: notOpen,
+  saveThread: notOpen,
+}
+
 /**
  * A live harness session: one conversation (`threadId`) with its plugins,
  * operations, inbox, and event stream. Open one with `host.open()`.
@@ -266,7 +290,18 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   private readonly persistence: HarnessPersistence
   private readonly inbox: InboxStore
   private readonly principal: Principal | undefined
-  private readonly feed = new SessionFeed()
+  /** The session log writer of a durable host. It is also the feed. */
+  private writer: LogWriter | undefined
+  private feed: EventFeed = new SessionFeed()
+  /** The transcript: `stores.messages`, or a view of the log. */
+  private messages: MessageStore
+  /** What `withPersistence` gets: the chat stores, with `messages`. */
+  private chatPersistence: AIPersistence<ChatTranscriptStores> | undefined
+  /** The message store the chat engine saves through, on a durable host. */
+  private engine: ReturnType<typeof engineMessageStore> | undefined
+  /** Why the session log stopped taking writes. */
+  private logFailure: Error | undefined
+  private readonly log: SessionDependencies['log']
   private readonly agentRegistry = new AgentRegistry()
   private readonly operations = new Map<string, OperationImpl<unknown>>()
   private readonly queue: Array<QueuedTurn> = []
@@ -288,7 +323,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   private sessionPlugins: MountedPlugins | undefined
   private closing: Promise<void> | undefined
   private readonly onClose: () => void
-  private readonly checkpoint: AnyChatMiddleware
+  private checkpoint: AnyChatMiddleware | undefined
+  private readonly hostId: string
+  private readonly lease: LeaseOptions | undefined
   private readonly listeners = new Map<string, Set<(value: unknown) => void>>()
   private readonly configValues = new Map<string, unknown>()
   private readonly questions = new Map<
@@ -325,11 +362,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     })
     this.principal = deps.principal
     this.onClose = deps.onClose
-    this.checkpoint = checkpointMiddleware({
-      runs: deps.persistence.stores.runs,
-      messages: deps.persistence.stores.messages,
-      hostId: deps.hostId,
-    })
+    this.hostId = deps.hostId
+    this.lease = deps.lease
+    this.log = deps.log
+    // A durable host gets its log view in `open()`.
+    this.messages = deps.persistence.stores.messages ?? notOpenMessages
     const onMissing = (error: AuthRequiredError) =>
       this.feed.publish(
         'session',
@@ -421,6 +458,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
 
   /** @internal Mount session plugins and replay inputs left in the inbox. */
   async open(): Promise<void> {
+    // First: plugins publish events while they mount.
+    await this.openLog()
     this.plugins = this.harness.plugins?.() ?? []
     this.sessionPlugins = await mountPlugins(
       this.plugins.filter(
@@ -442,6 +481,105 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     await this.recoverInbox()
   }
 
+  /**
+   * A durable host folds the thread's log and writes through it: the log is
+   * the event feed and the transcript. Then both modes build the stores that
+   * `withPersistence` and the checkpoints get.
+   */
+  private async openLog(): Promise<void> {
+    const { stores } = this.persistence
+    if (this.log) {
+      const { store, project, coalesceMs } = this.log
+      const state = await loadLogState({
+        store,
+        threadId: this.threadId,
+        ...(stores.metadata ? { metadata: stores.metadata } : {}),
+        ...(project ? { project } : {}),
+      })
+      this.writer = new LogWriter({
+        store,
+        threadId: this.threadId,
+        state,
+        coalesceMs,
+        ...(project ? { project } : {}),
+        ...(stores.metadata ? { metadata: stores.metadata } : {}),
+        onFailure: (error) => this.stopOnLogFailure(error),
+      })
+      this.feed = this.writer
+      const view = {
+        writer: this.writer,
+        store,
+        ...(project ? { project } : {}),
+      }
+      this.messages = sessionMessageStore(view)
+      this.engine = engineMessageStore(view)
+    }
+    const engineMessages = this.engine ?? this.messages
+    this.chatPersistence = {
+      stores: {
+        messages: engineMessages,
+        ...(stores.runs ? { runs: stores.runs } : {}),
+        ...(stores.interrupts ? { interrupts: stores.interrupts } : {}),
+        ...(stores.metadata ? { metadata: stores.metadata } : {}),
+      },
+    }
+    this.checkpoint = checkpointMiddleware({
+      ...(stores.runs ? { runs: stores.runs } : {}),
+      messages: engineMessages,
+      hostId: this.hostId,
+      ...(this.lease ? { lease: this.lease } : {}),
+    })
+  }
+
+  /**
+   * The log refused a write: another host wrote to this thread, or the store
+   * failed. The state of this session is not known any more, so it stops.
+   * The next `host.open` folds the log again.
+   */
+  private stopOnLogFailure(error: unknown): void {
+    if (this.logFailure) return
+    this.logFailure = new Error(
+      error instanceof LogConflictError
+        ? 'Another host wrote to this thread, so this session stopped. Open the thread again.'
+        : `The session log failed, so this session stopped: ${error instanceof Error ? error.message : String(error)}`,
+    )
+    for (const operation of this.operations.values()) {
+      if (!operation.isSettled())
+        operation.abortController.abort(this.logFailure)
+    }
+    void this.close()
+  }
+
+  /**
+   * Append host records to the session log, in one batch after the events
+   * that wait. Only a durable host (with `stores.log`) has a log. A `type`
+   * that starts with `harness.` is refused: the harness owns those.
+   *
+   * With `project` on the host, a record can change the model context. The
+   * running turn sees the change at its next model call.
+   *
+   * @example
+   * ```ts
+   * await session.append([{ type: 'app.signal', text: 'The build failed.' }])
+   * ```
+   */
+  async append(records: ReadonlyArray<LogRecord>): Promise<void> {
+    if (!this.writer) {
+      throw new Error(
+        'session.append needs a durable host (a host with stores.log).',
+      )
+    }
+    const reserved = records.find((record) =>
+      record.type.startsWith('harness.'),
+    )
+    if (reserved) {
+      throw new Error(
+        `The record type ${JSON.stringify(reserved.type)} is reserved for the harness.`,
+      )
+    }
+    await this.writer.append(records)
+  }
+
   // ===========================
   // Inputs
   // ===========================
@@ -698,9 +836,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
 
   /** The saved messages of this thread, oldest first. */
   async transcript() {
-    return [
-      ...(await this.persistence.stores.messages.loadThread(this.threadId)),
-    ]
+    return [...(await this.messages.loadThread(this.threadId))]
   }
 
   /** The commands, settings, and tools of this session, for a UI. */
@@ -850,7 +986,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       prompt: (text) => this.prompt(text, { busy: 'queue' }),
       transcript: () => this.transcript(),
       replaceTranscript: (messages) =>
-        this.persistence.stores.messages.saveThread(this.threadId, messages),
+        this.messages.saveThread(this.threadId, messages),
       // The public type narrows the answer from the schema.
       ask: ((question: Question<SchemaInput | undefined>) =>
         this.ask(question)) as PluginSessionApi['ask'],
@@ -1117,13 +1253,19 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     )
   }
 
-  /** Middleware that adds queued steer messages before each model call. */
+  /**
+   * Middleware that runs before each model call. On a durable host it
+   * commits the engine's messages, and it sends the folded log when a host
+   * record changed the context. Then it adds queued steer messages.
+   */
   private steering(): AnyChatMiddleware {
     return {
       name: 'harness:steering',
-      onConfig: (ctx, config) => {
-        if (ctx.phase !== 'beforeModel' || this.steerQueue.length === 0) {
-          return undefined
+      onConfig: async (ctx, config) => {
+        if (ctx.phase !== 'beforeModel') return undefined
+        const synced = await this.engine?.beforeModel(config.messages)
+        if (this.steerQueue.length === 0) {
+          return synced ? { messages: synced } : undefined
         }
         const steers = this.steerQueue.splice(0)
         const running = this.activeTurn
@@ -1148,7 +1290,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         }
         return {
           messages: [
-            ...config.messages,
+            ...(synced ?? config.messages),
             ...steers.map(
               (steer): ModelMessage => ({
                 id: createMessageId(),
@@ -1244,7 +1386,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
 
   /** Add the media a turn made to the last assistant message of the thread. */
   private async saveTurnMedia(media: Array<MediaRecord>) {
-    const store = this.persistence.stores.messages
+    const store = this.messages
     const history = await store.loadThread(this.threadId)
     const index = history.findLastIndex(
       (message) => message.role === 'assistant',
@@ -1343,6 +1485,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         turn.message !== undefined
           ? await this.userMessage(turn.message)
           : undefined
+      if (!this.chatPersistence || !this.checkpoint) {
+        throw new Error('The session is not open yet.')
+      }
       const stream = chat({
         adapter,
         messages: message ? [message] : [],
@@ -1355,7 +1500,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         tools,
         middleware: [
           ...bridges,
-          withPersistence(this.persistence),
+          withPersistence(this.chatPersistence),
           this.checkpoint,
           ...(this.harness.middleware ?? []),
           ...(session?.middleware ?? []),
@@ -1446,7 +1591,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       )
     }
 
-    if (operation.abortController.signal.aborted) {
+    if (this.logFailure) {
+      operation.fail('failed', this.logFailure)
+    } else if (operation.abortController.signal.aborted) {
       operation.fail('cancelled', new Error('Cancelled.'))
     } else if (failure !== undefined) {
       operation.fail('failed', new Error(failure))
@@ -1595,9 +1742,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     let failure: string | undefined
     let subagentRunId = ''
     try {
-      const messages = await this.persistence.stores.messages?.loadThread(
-        this.threadId,
-      )
+      const messages = await this.messages.loadThread(this.threadId)
       subagentRunId = createSubagentId()
       const stream = runAgentStream(
         agent,
@@ -1699,8 +1844,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
 
   /** Write queued agent notes to the transcript while no turn is writing it. */
   private async flushNotes(): Promise<void> {
-    const messages = this.persistence.stores.messages
-    if (!messages || this.pendingNotes.length === 0) return
+    const messages = this.messages
+    if (this.pendingNotes.length === 0) return
     const notes = this.pendingNotes.splice(0)
     const history = await messages.loadThread(this.threadId)
     await messages.saveThread(this.threadId, [
@@ -1795,10 +1940,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       })
     }
     if (!newest) return
-    await repairTranscript({
-      messages: this.persistence.stores.messages,
-      crashed: newest,
-    })
+    await repairTranscript({ messages: this.messages, crashed: newest })
     const operation = this.createTurnOperation()
     this.feed.publish(
       operation.id,
diff --git a/packages/ai-harness/tests/durable-session.test.ts b/packages/ai-harness/tests/durable-session.test.ts
new file mode 100644
index 0000000000..bc54f6232a
--- /dev/null
+++ b/packages/ai-harness/tests/durable-session.test.ts
@@ -0,0 +1,374 @@
+import { describe, expect, it, vi } from 'vitest'
+import { EventType, toolDefinition } from '@tanstack/ai'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '../src'
+import { loadLogState } from '../src/log'
+import { gate, messageTexts, mockAdapter, text, toolCall } from './helpers'
+import type { StreamChunk } from '@tanstack/ai'
+import type { LogStore } from '@tanstack/ai-persistence'
+import type { HarnessSession, ProjectOptions, SessionEvent } from '../src'
+import type { Reply } from './helpers'
+
+const THREAD = 't1'
+
+/** The stores of a durable host: a log, runs, and metadata. */
+function durablePersistence(log: LogStore = memoryLogStore()) {
+  const { runs, metadata } = memoryPersistence().stores
+  return { stores: { log, runs, metadata } }
+}
+
+/** Signals become user messages. A compaction keeps a summary and a tail. */
+const project: ProjectOptions = {
+  version: 'v1',
+  record: ({ messages, record }) => {
+    if (record.type === 'app.signal' && typeof record.text === 'string') {
+      return [...messages, { role: 'user', content: record.text }]
+    }
+    if (
+      record.type === 'app.compact' &&
+      typeof record.summary === 'string' &&
+      typeof record.firstKept === 'number'
+    ) {
+      return [
+        { role: 'assistant', content: record.summary },
+        ...messages.slice(record.firstKept),
+      ]
+    }
+    return undefined
+  },
+}
+
+/** A model call that streams `deltas` of message `messageId`, then waits. */
+function streamsThenWaits(
+  messageId: string,
+  deltas: Array<string>,
+  until: Promise<void>,
+): Reply {
+  return () =>
+    (async function* (): AsyncGenerator<StreamChunk> {
+      yield {
+        type: EventType.RUN_STARTED,
+        runId: 'r',
+        threadId: 't',
+        timestamp: Date.now(),
+      }
+      yield {
+        type: EventType.TEXT_MESSAGE_START,
+        messageId,
+        role: 'assistant',
+        timestamp: Date.now(),
+      }
+      for (const delta of deltas) {
+        yield {
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          messageId,
+          delta,
+          timestamp: Date.now(),
+        }
+      }
+      await until
+    })()
+}
+
+/** The events of a session from the start, once `isDone` holds for them. */
+async function eventsUntil(
+  session: HarnessSession,
+  isDone: (seen: Array<SessionEvent>) => boolean,
+) {
+  const controller = new AbortController()
+  const seen: Array<SessionEvent> = []
+  const reading = (async () => {
+    for await (const entry of session.events({
+      from: '0',
+      signal: controller.signal,
+    })) {
+      seen.push(entry)
+      if (isDone(seen)) controller.abort()
+    }
+  })()
+  await reading
+  return seen
+}
+
+const deltasOf = (seen: Array<SessionEvent>, messageId: string) =>
+  seen
+    .map((entry) => entry.event)
+    .filter(
+      (event) =>
+        event.type === EventType.TEXT_MESSAGE_CONTENT &&
+        event.messageId === messageId,
+    )
+    .map((event) => ('delta' in event ? event.delta : ''))
+    .join('')
+
+// The types refuse these store sets. The runtime check is for JavaScript
+// callers and dynamic store bags, so these tests pass them with `as never`.
+describe('durable host stores', () => {
+  it('needs runs next to the log', () => {
+    const { metadata } = memoryPersistence().stores
+    expect(() =>
+      createHarnessHost({
+        persistence: { stores: { log: memoryLogStore(), metadata } } as never,
+      }),
+    ).toThrow('needs stores.runs')
+  })
+
+  it('refuses a message store next to the log', () => {
+    const { messages, runs } = memoryPersistence().stores
+    expect(() =>
+      createHarnessHost({
+        persistence: {
+          stores: { log: memoryLogStore(), runs, messages },
+        } as never,
+      }),
+    ).toThrow('Remove stores.messages and stores.inbox')
+  })
+
+  it('refuses host records without a log, and harness record types', async () => {
+    const { adapter } = mockAdapter([])
+    const harness = defineHarness({ name: 'test/append', adapter })
+    const today = await createHarnessHost({
+      persistence: memoryPersistence(),
+    }).open(harness, { threadId: THREAD })
+    await expect(today.append([{ type: 'app.x' }])).rejects.toThrow(
+      'session.append needs a durable host',
+    )
+
+    const durable = await createHarnessHost({
+      persistence: durablePersistence(),
+    }).open(harness, { threadId: THREAD })
+    await expect(durable.append([{ type: 'harness.event' }])).rejects.toThrow(
+      'reserved for the harness',
+    )
+  })
+})
+
+describe('durable session log', () => {
+  it('keeps a streamed text block when the host stops in the middle', async () => {
+    const persistence = durablePersistence()
+    const release = gate()
+    const { adapter } = mockAdapter([
+      streamsThenWaits('m-live', ['Hello, ', 'wor'], release.opened),
+    ])
+    const harness = defineHarness({ name: 'test/crash-mid-text', adapter })
+    const first = createHarnessHost({ persistence, coalesceMs: 5 })
+    const session = await first.open(harness, { threadId: THREAD })
+    const turn = session.prompt('say hello')
+
+    // The deltas reach the log after the coalescing window.
+    await vi.waitFor(async () => {
+      const entries = await persistence.stores.log.read(THREAD)
+      const events = entries.map((entry) => entry.record.event)
+      expect(JSON.stringify(events)).toContain('wor')
+    })
+
+    // The first host never closes, like a process that stopped.
+    const next = createHarnessHost({ persistence })
+    const reopened = await next.open(harness, { threadId: THREAD })
+    const seen = await eventsUntil(
+      reopened,
+      (events) => deltasOf(events, 'm-live') === 'Hello, wor',
+    )
+
+    expect(seen.map((entry) => entry.event)).toContainEqual(
+      expect.objectContaining({
+        type: EventType.TEXT_MESSAGE_START,
+        messageId: 'm-live',
+      }),
+    )
+    expect(deltasOf(seen, 'm-live')).toBe('Hello, wor')
+
+    release.open()
+    await Promise.resolve(turn).catch(() => {})
+    await first.close()
+    await next.close()
+  })
+
+  it('writes host records in the same batch as the waiting events, in order', async () => {
+    const inner = memoryLogStore()
+    const batches: Array<Array<unknown>> = []
+    const log: LogStore = {
+      append: async (threadId, seq, records) => {
+        await inner.append(threadId, seq, records)
+        batches.push(
+          records.map((record) =>
+            record.type === 'harness.event' ? record.event : record,
+          ),
+        )
+      },
+      read: (threadId, options) => inner.read(threadId, options),
+      subscribe: (threadId, listener) => inner.subscribe(threadId, listener),
+    }
+    const release = gate()
+    const { adapter } = mockAdapter([
+      streamsThenWaits('m1', ['partial'], release.opened),
+    ])
+    const host = createHarnessHost({
+      persistence: durablePersistence(log),
+      coalesceMs: 60_000,
+    })
+    const session = await host.open(
+      defineHarness({ name: 'test/batch', adapter }),
+      { threadId: THREAD },
+    )
+    const turn = session.prompt('go')
+    await vi.waitFor(() =>
+      expect(JSON.stringify(batches)).toContain('TEXT_MESSAGE_START'),
+    )
+
+    await session.append([{ type: 'app.note', n: 1 }])
+
+    expect(batches.at(-1)).toEqual([
+      expect.objectContaining({
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        delta: 'partial',
+      }),
+      { type: 'app.note', n: 1 },
+    ])
+    release.open()
+    await Promise.resolve(turn).catch(() => {})
+    await host.close()
+  })
+
+  it('gives the model the same context that a rebuild of the log gives', async () => {
+    const persistence = durablePersistence()
+    let session: HarnessSession | undefined
+    const check = toolDefinition({
+      name: 'check',
+      description: 'Check the build',
+    }).server(async () => {
+      await session?.append([
+        { type: 'app.signal', text: '[signal] tests failed' },
+      ])
+      return 'checked'
+    })
+    const { adapter, calls } = mockAdapter([
+      () => text('first answer'),
+      () => toolCall('check', {}),
+      () => text('second answer'),
+    ])
+    const host = createHarnessHost({ persistence, project })
+    session = await host.open(
+      defineHarness({ name: 'test/project', adapter, tools: [check] }),
+      { threadId: THREAD },
+    )
+
+    await session.prompt('one')
+    // Between turns: the next turn starts with it.
+    await session.append([
+      { type: 'app.signal', text: '[signal] build failed' },
+    ])
+    await session.prompt('two')
+
+    expect(messageTexts(calls[1])).toEqual([
+      'one',
+      'first answer',
+      '[signal] build failed',
+      'two',
+    ])
+    // During a tool call: the next model call of the same turn has it, after
+    // the tool result.
+    // The tool-call message has no text: its content is null.
+    expect(messageTexts(calls[2]).slice(-3)).toEqual([
+      'null',
+      'checked',
+      '[signal] tests failed',
+    ])
+    const rebuilt = await loadLogState({
+      store: persistence.stores.log,
+      threadId: THREAD,
+      project,
+    })
+    expect(await session.transcript()).toEqual(rebuilt.messages)
+    expect(rebuilt.messages.map((message) => message.content).at(-1)).toBe(
+      'second answer',
+    )
+    await host.close()
+  })
+
+  it('hides the older span after a compaction record', async () => {
+    const persistence = durablePersistence()
+    const { adapter, calls } = mockAdapter([
+      () => text('a1'),
+      () => text('a2'),
+      () => text('a3'),
+    ])
+    const host = createHarnessHost({ persistence, project })
+    const session = await host.open(
+      defineHarness({ name: 'test/compact', adapter }),
+      { threadId: THREAD },
+    )
+    await session.prompt('q1')
+    await session.prompt('q2')
+
+    await session.append([
+      { type: 'app.compact', summary: 'Earlier: q1 and a1.', firstKept: 2 },
+    ])
+    await session.prompt('q3')
+
+    expect(messageTexts(calls[2])).toEqual([
+      'Earlier: q1 and a1.',
+      'q2',
+      'a2',
+      'q3',
+    ])
+    const rebuilt = await loadLogState({
+      store: persistence.stores.log,
+      threadId: THREAD,
+      project,
+    })
+    expect(rebuilt.messages.map((message) => message.content)).toEqual([
+      'Earlier: q1 and a1.',
+      'q2',
+      'a2',
+      'q3',
+      'a3',
+    ])
+    await host.close()
+  })
+
+  it('stops the session when another host wrote to the thread', async () => {
+    const inner = memoryLogStore()
+    // This host does not see the other writer, like one in another process.
+    const log: LogStore = {
+      append: (threadId, seq, records) => inner.append(threadId, seq, records),
+      read: (threadId, options) => inner.read(threadId, options),
+      subscribe: () => () => {},
+    }
+    const { adapter } = mockAdapter([() => text('never saved')])
+    const host = createHarnessHost({ persistence: durablePersistence(log) })
+    const harness = defineHarness({ name: 'test/conflict', adapter })
+    const session = await host.open(harness, { threadId: THREAD })
+    await inner.append(THREAD, 1, [{ type: 'app.from-another-host' }])
+
+    await expect(session.prompt('hi')).rejects.toThrow('Another host wrote')
+
+    // The host opens a new session, which folds the log again.
+    await vi.waitFor(async () =>
+      expect(await host.open(harness, { threadId: THREAD })).not.toBe(session),
+    )
+    await host.close()
+  })
+
+  it('lets a second host read live events without fencing the first', async () => {
+    const persistence = durablePersistence()
+    const { adapter } = mockAdapter([() => text('streamed answer')])
+    const harness = defineHarness({ name: 'test/reader', adapter })
+    const writer = createHarnessHost({ persistence })
+    const reader = createHarnessHost({ persistence })
+    const live = await writer.open(harness, { threadId: THREAD })
+    const watching = await reader.open(harness, { threadId: THREAD })
+
+    const seen = eventsUntil(watching, (events) =>
+      events.some((entry) => entry.event.type === EventType.TEXT_MESSAGE_END),
+    )
+    const result = await live.prompt('hi')
+
+    expect(result.text).toBe('streamed answer')
+    expect((await seen).map((entry) => entry.event.type)).toContain(
+      EventType.TEXT_MESSAGE_CONTENT,
+    )
+    await writer.close()
+    await reader.close()
+  })
+})
diff --git a/packages/ai-harness/tests/log.test.ts b/packages/ai-harness/tests/log.test.ts
index d32fd0925e..40a5696778 100644
--- a/packages/ai-harness/tests/log.test.ts
+++ b/packages/ai-harness/tests/log.test.ts
@@ -8,6 +8,7 @@ import {
 import {
   LogWriter,
   emptyLogState,
+  engineMessageStore,
   loadLogState,
   logMessageStore,
   sessionMessageStore,
@@ -465,6 +466,117 @@ describe('fold checkpoints', () => {
   })
 })
 
+describe('engine message store', () => {
+  const toolCallMessage: ModelMessage = {
+    id: 'a1',
+    role: 'assistant',
+    content: '',
+    toolCalls: [
+      {
+        id: 'call-1',
+        type: 'function',
+        function: { name: 'check', arguments: '{}' },
+      },
+    ],
+  }
+  const toolResult: ModelMessage = {
+    role: 'tool',
+    toolCallId: 'call-1',
+    content: 'checked',
+  }
+  const signal: ModelMessage = {
+    role: 'user',
+    content: '[signal] build failed',
+  }
+
+  async function engineOnLog() {
+    const store = memoryLogStore()
+    const writer = newWriter(store, { project })
+    const engine = engineMessageStore({ writer, store, project })
+    return { writer, engine }
+  }
+
+  it('puts a host message that arrives in a tool phase after the tool result', async () => {
+    const { writer, engine } = await engineOnLog()
+    const u1 = user('u1', 'go')
+    await engine.loadThread(THREAD)
+    // The engine saves before the first tool call of the phase.
+    await engine.saveThread(THREAD, [u1, toolCallMessage])
+
+    // During the tool call, a host record projects a user message.
+    await writer.append([{ type: 'app.signal', text: '[signal] build failed' }])
+    // At the end of the phase the engine saves again, still without the
+    // result: the engine adds tool results after this hook.
+    await engine.saveThread(THREAD, [u1, toolCallMessage])
+    const forModel = await engine.beforeModel([u1, toolCallMessage, toolResult])
+
+    const expected = [u1, toolCallMessage, toolResult, signal]
+    expect(forModel).toEqual(expected)
+    expect(writer.state.messages).toEqual(expected)
+  })
+
+  it('adds engine messages after a host rewrite of the fold', async () => {
+    const { writer, engine } = await engineOnLog()
+    await engine.loadThread(THREAD)
+    await engine.saveThread(THREAD, [user('u1', 'one'), assistant('a1', 'two')])
+
+    await writer.append([
+      { type: 'app.compact', summary: 'Earlier: one, two.', firstKept: 2 },
+    ])
+    await engine.saveThread(THREAD, [
+      user('u1', 'one'),
+      assistant('a1', 'two'),
+      user('u2', 'three'),
+    ])
+
+    expect(writer.state.messages).toEqual([
+      { role: 'assistant', content: 'Earlier: one, two.' },
+      user('u2', 'three'),
+    ])
+  })
+
+  it('lets an engine save that changes older messages win', async () => {
+    const { writer, engine } = await engineOnLog()
+    await engine.loadThread(THREAD)
+    await engine.saveThread(THREAD, [user('u1', 'one'), assistant('a1', 'two')])
+    await writer.append([{ type: 'app.signal', text: '[signal] late' }])
+
+    await engine.saveThread(THREAD, [assistant('s', 'engine summary')])
+
+    expect(writer.state.messages).toEqual([assistant('s', 'engine summary')])
+  })
+
+  it('commits the engine list before a model call and changes it only for a host record', async () => {
+    const { writer, engine } = await engineOnLog()
+    await engine.loadThread(THREAD)
+    await engine.saveThread(THREAD, [user('u1', 'one'), toolCallMessage])
+
+    // No host record: the tool result is committed, and the engine keeps its list.
+    expect(
+      await engine.beforeModel([
+        user('u1', 'one'),
+        toolCallMessage,
+        toolResult,
+      ]),
+    ).toBeUndefined()
+    expect(writer.state.messages).toEqual([
+      user('u1', 'one'),
+      toolCallMessage,
+      toolResult,
+    ])
+
+    await writer.append([{ type: 'app.signal', text: '[signal] build failed' }])
+
+    expect(
+      await engine.beforeModel([
+        user('u1', 'one'),
+        toolCallMessage,
+        toolResult,
+      ]),
+    ).toEqual([user('u1', 'one'), toolCallMessage, toolResult, signal])
+  })
+})
+
 describe('message stores', () => {
   it('logMessageStore writes a change as one record and reads the fold', async () => {
     const store = memoryLogStore()

From 615b21c8e6b19aa7773cfc78d31fb199d16352c5 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 12:39:13 +0200
Subject: [PATCH 081/286] feat(ai-harness): input ids, receipts, settlement,
 attempt budget, timeout, and abort

prompt, steer, followUp, and resolve take an optional inputId. A duplicate with the same payload gets the first input's operation or receipt and does not run again, also after a restart on a durable host. Another payload is rejected as a conflict. Operation.receipt resolves when the input is stored, and applyInput answers with it. session.settled(inputId) gives how a chat input ended, and clients get a harness.input.settled event.

On a durable host each apply is one attempt. Recovery settles an input aborted after an abort request, failed when defineHarness durability.maxAttempts (default 10) or timeoutMs is used up, and completed when the log already has the final answer. Else it runs the next attempt. A turn past its time limit is aborted live.
---
 packages/ai-harness/src/protocol.ts           |  37 +-
 packages/ai-harness/src/session.ts            | 638 ++++++++++++++++--
 packages/ai-harness/src/types.ts              |  10 +-
 .../ai-harness/tests/durable-inputs.test.ts   | 354 ++++++++++
 packages/ai-harness/tests/protocol.test.ts    |  28 +
 5 files changed, 998 insertions(+), 69 deletions(-)
 create mode 100644 packages/ai-harness/tests/durable-inputs.test.ts

diff --git a/packages/ai-harness/src/protocol.ts b/packages/ai-harness/src/protocol.ts
index 77a30fcf3d..74e8a2e4c6 100644
--- a/packages/ai-harness/src/protocol.ts
+++ b/packages/ai-harness/src/protocol.ts
@@ -1,4 +1,5 @@
 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'
@@ -46,10 +47,6 @@ const INPUT_OPS = new Set([
   'config',
 ])
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null
-}
-
 /** Check the shape of a client input. Throws with a short reason. */
 export function parseHarnessInput(value: unknown): HarnessInput {
   if (
@@ -83,6 +80,9 @@ export function parseHarnessInput(value: unknown): HarnessInput {
   if (value.op === 'config' && typeof value.key !== 'string') {
     throw new Error('Invalid input: config needs a key.')
   }
+  if (value.inputId !== undefined && typeof value.inputId !== 'string') {
+    throw new Error('Invalid input: inputId must be a string.')
+  }
   // The checks above cover every field the session reads.
   return value as HarnessInput
 }
@@ -121,29 +121,26 @@ export async function applyInput(
   session: HarnessSession,
   input: HarnessInput,
 ): Promise<Receipt> {
+  const id = input.inputId === undefined ? {} : { inputId: input.inputId }
   switch (input.op) {
     case 'prompt': {
-      const operation = session.prompt(
-        input.message,
-        input.busy ? { busy: input.busy } : {},
+      const operation = session.prompt(input.message, {
+        ...(input.busy ? { busy: input.busy } : {}),
+        ...id,
+      })
+      // Nobody may await a turn a client started. Its receipt is the answer.
+      operation.then(
+        () => {},
+        () => {},
       )
-      const queued = session
-        .snapshot()
-        .activeOperations.some(
-          (active) => active.kind === 'chat' && active.id !== operation.id,
-        )
-      return {
-        inputId: operation.id,
-        status: queued ? 'queued' : 'accepted',
-        operationId: operation.id,
-      }
+      return operation.receipt
     }
     case 'steer':
-      return session.steer(input.message)
+      return session.steer(input.message, id)
     case 'followUp':
-      return session.followUp(input.message)
+      return session.followUp(input.message, id)
     case 'resolve':
-      return session.resolve(input.resume)
+      return session.resolve(input.resume, id)
     case 'cancel':
       return session.cancel(input.operationId)
     case 'command': {
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 15712e2933..226564ee65 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -15,6 +15,7 @@ import { checkConfigValue } from './config'
 import { LogConflictError, withPersistence } from '@tanstack/ai-persistence'
 import { AgentRegistry } from './agents'
 import { SessionFeed } from './feed'
+import { isRecord } from './utils'
 import {
   LogWriter,
   engineMessageStore,
@@ -30,7 +31,7 @@ import {
   findCrashedRuns,
   repairTranscript,
 } from './resume'
-import { HARNESS_EVENTS } from './types'
+import { HARNESS_EVENTS, InputRejectedError } from './types'
 import type {
   AnyChatMiddleware,
   AnyTextAdapter,
@@ -87,6 +88,7 @@ import type {
   ChatTurnResult,
   Cursor,
   HarnessInput,
+  InputSettlement,
   MediaKind,
   MediaRecord,
   Operation,
@@ -268,6 +270,31 @@ export function acceptedKinds(
   return accepts.filter((kind) => modalities.includes(kind))
 }
 
+/** The inputs that run as chat turns, and settle. */
+const CHAT_OPS = new Set<string>(['prompt', 'steer', 'followUp', 'resolve'])
+
+/** Why a turn stops when its input passes its time limit. */
+const TIMEOUT_REASON = 'harness:input-timeout'
+
+/** The text of the last assistant message, for an operation rebuilt from the log. */
+function lastAssistantText(messages: ReadonlyArray<ModelMessage>) {
+  const last = messages.findLast((message) => message.role === 'assistant')
+  return typeof last?.content === 'string' ? last.content : ''
+}
+
+/** The turn has its final answer: an assistant message with no open tool call after it was applied. */
+function hasFinalAnswer(
+  messages: ReadonlyArray<ModelMessage>,
+  appliedAt: number,
+) {
+  const last = messages.at(-1)
+  return (
+    messages.length > appliedAt &&
+    last?.role === 'assistant' &&
+    (last.toolCalls?.length ?? 0) === 0
+  )
+}
+
 const notOpen = () => Promise.reject(new Error('The session is not open yet.'))
 
 /** The message store of a durable session before `open()` reads its log. */
@@ -302,6 +329,19 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   /** Why the session log stopped taking writes. */
   private logFailure: Error | undefined
   private readonly log: SessionDependencies['log']
+  /** Inputs this session stored, by id, as JSON: the duplicate check. */
+  private readonly admitted = new Map<string, string>()
+  /** The receipt of each chat input this session answered, by input id. */
+  private readonly receipts = new Map<string, Receipt>()
+  /** The turn operation of each chat input, by input id. */
+  private readonly turnOperations = new Map<
+    string,
+    OperationImpl<ChatTurnResult>
+  >()
+  /** The input of each turn operation, by operation id. */
+  private readonly operationInputs = new Map<string, string>()
+  /** How the chat inputs of this session ended, for `settled()`. */
+  private readonly settlements = new Map<string, InputSettlement>()
   private readonly agentRegistry = new AgentRegistry()
   private readonly operations = new Map<string, OperationImpl<unknown>>()
   private readonly queue: Array<QueuedTurn> = []
@@ -477,6 +517,10 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     )
     await this.loadConfig()
     await this.loadPluginState()
+    if (this.writer) {
+      await this.recoverFromLog(this.writer)
+      return
+    }
     await this.recoverCrashedTurn()
     await this.recoverInbox()
   }
@@ -584,60 +628,120 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   // Inputs
   // ===========================
 
-  /** Start a chat turn, or queue it while one runs (see `busy`). */
+  /**
+   * Start a chat turn, or queue it while one runs (see `busy`).
+   *
+   * `inputId` is an id you choose. A second prompt with the same id and the
+   * same message returns the first input's operation and does not run again.
+   * The same id with another message is rejected with `'conflict'`.
+   * `await operation.receipt` resolves when the input is stored.
+   */
   prompt(
     message: UserInput,
-    options?: { busy?: BusyPolicy },
+    options?: { busy?: BusyPolicy; inputId?: string },
   ): Operation<ChatTurnResult> {
     const busy = options?.busy ?? this.harness.busy ?? 'queue'
-    const inputId = createInputId()
+    const inputId = options?.inputId ?? createInputId()
+    const input: HarnessInput = { op: 'prompt', message, busy }
+    const known = this.knownTurn(inputId, input)
+    if (known) return known
     const operation = this.createTurnOperation()
-    void this.accept(inputId, { op: 'prompt', message, busy }).then(() => {
-      if (this.activeTurn && busy === 'reject') {
-        this.reject(inputId, 'busy')
-        operation.fail('failed', new Error('A chat turn is already running.'))
-        return
-      }
-      if (this.activeTurn && busy === 'steer') {
-        this.steerQueue.push({ inputId, message, operation })
-        return
-      }
-      this.enqueueTurn({ operation, message, inputId })
-    })
+    this.bindTurn(inputId, operation)
+    void this.accept(inputId, input).then(
+      (admission) => {
+        if (admission !== 'new') {
+          this.answerDuplicate(operation, inputId, admission)
+          return
+        }
+        if (this.activeTurn && busy === 'reject') {
+          this.reject(inputId, 'busy')
+          this.refuse(operation, {
+            inputId,
+            status: 'rejected',
+            reason: 'busy',
+          })
+          return
+        }
+        const isWaiting = this.activeTurn !== undefined || this.queue.length > 0
+        this.answerTurn(operation, {
+          inputId,
+          status: isWaiting && busy !== 'steer' ? 'queued' : 'accepted',
+          operationId: operation.id,
+        })
+        if (this.activeTurn && busy === 'steer') {
+          this.steerQueue.push({ inputId, message, operation })
+          return
+        }
+        this.enqueueTurn({ operation, message, inputId })
+      },
+      (error: unknown) => {
+        // The input was not stored. After a log failure, say why the
+        // session stopped.
+        const failure = this.logFailure ?? error
+        this.answerTurn(operation, {
+          inputId,
+          status: 'rejected',
+          reason: failure instanceof Error ? failure.message : String(failure),
+        })
+        operation.fail('failed', failure)
+      },
+    )
     return operation
   }
 
   /** Add a message to the running turn at its next model call. */
-  async steer(message: UserInput): Promise<Receipt> {
-    const inputId = createInputId()
-    await this.accept(inputId, { op: 'steer', message })
+  async steer(
+    message: UserInput,
+    options?: { inputId?: string },
+  ): Promise<Receipt> {
+    const inputId = options?.inputId ?? createInputId()
+    const admission = await this.accept(inputId, { op: 'steer', message })
+    if (admission !== 'new') return this.duplicateReceipt(inputId, admission)
     if (!this.activeTurn) {
       const operation = this.createTurnOperation()
+      this.bindTurn(inputId, operation)
       this.enqueueTurn({ operation, message, inputId })
-      return { inputId, status: 'accepted', operationId: operation.id }
+      return this.keep({
+        inputId,
+        status: 'accepted',
+        operationId: operation.id,
+      })
     }
     this.steerQueue.push({ inputId, message })
-    return { inputId, status: 'accepted', operationId: this.activeTurn.id }
+    return this.keep({
+      inputId,
+      status: 'accepted',
+      operationId: this.activeTurn.id,
+    })
   }
 
   /** Run a turn after the current work settles. */
-  async followUp(message: UserInput): Promise<Receipt> {
-    const inputId = createInputId()
-    await this.accept(inputId, { op: 'followUp', message })
+  async followUp(
+    message: UserInput,
+    options?: { inputId?: string },
+  ): Promise<Receipt> {
+    const inputId = options?.inputId ?? createInputId()
+    const admission = await this.accept(inputId, { op: 'followUp', message })
+    if (admission !== 'new') return this.duplicateReceipt(inputId, admission)
     const operation = this.createTurnOperation()
+    this.bindTurn(inputId, operation)
     const status =
       this.activeTurn || this.queue.length > 0 ? 'queued' : 'accepted'
     this.enqueueTurn({ operation, message, inputId })
-    return { inputId, status, operationId: operation.id }
+    return this.keep({ inputId, status, operationId: operation.id })
   }
 
   /**
    * Answer the interrupts of the last turn. One resume must answer every open
    * interrupt of that turn (the AG-UI rule).
    */
-  async resolve(resume: Array<RunAgentResumeItem>): Promise<Receipt> {
-    const inputId = createInputId()
-    await this.accept(inputId, { op: 'resolve', resume })
+  async resolve(
+    resume: Array<RunAgentResumeItem>,
+    options?: { inputId?: string },
+  ): Promise<Receipt> {
+    const inputId = options?.inputId ?? createInputId()
+    const admission = await this.accept(inputId, { op: 'resolve', resume })
+    if (admission !== 'new') return this.duplicateReceipt(inputId, admission)
     if (!this.interrupted) {
       this.reject(inputId, 'no_pending_interrupts')
       return { inputId, status: 'rejected', reason: 'no_pending_interrupts' }
@@ -649,11 +753,16 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     const parentRunId = this.interrupted.runId
     this.interrupted = undefined
     const operation = this.createTurnOperation()
+    this.bindTurn(inputId, operation)
     this.enqueueTurn({ operation, resume, parentRunId, inputId })
-    return { inputId, status: 'accepted', operationId: operation.id }
+    return this.keep({ inputId, status: 'accepted', operationId: operation.id })
   }
 
-  /** Cancel one operation, or the running chat turn. */
+  /**
+   * Cancel one operation, or the running chat turn. On a durable host the
+   * abort request is stored first, so a turn that a crash stops later settles
+   * `aborted` and does not run again.
+   */
   async cancel(operationId?: string): Promise<Receipt> {
     const inputId = createInputId()
     await this.accept(inputId, { op: 'cancel', operationId })
@@ -664,18 +773,69 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       this.reject(inputId, 'not_running')
       return { inputId, status: 'rejected', reason: 'not_running' }
     }
+    const targetInput = this.operationInputs.get(target.id)
+    if (this.writer && targetInput) {
+      await this.writer.append([
+        { type: 'harness.input.abort', inputId: targetInput },
+      ])
+    }
     const queued = this.queue.findIndex((turn) => turn.operation === target)
     if (queued >= 0) {
       this.queue.splice(queued, 1)
+      if (targetInput) {
+        await this.settle({
+          inputId: targetInput,
+          outcome: 'aborted',
+          operationId: target.id,
+        })
+      }
       target.fail('cancelled', new Error('Cancelled before it started.'))
       this.publishFinished(target)
     } else {
       target.abortController.abort(RUN_CANCEL_REASON)
     }
-    await this.inbox.markApplied(inputId, target.id)
+    await this.markApplied(inputId, target.id)
     return { inputId, status: 'accepted', operationId: target.id }
   }
 
+  /**
+   * How a chat input ended: `completed`, `failed`, `aborted`, or
+   * `interrupted` (the turn waits for human input). It waits until the input
+   * ends. On a durable host it reads the log, so it also works after a
+   * restart and from another host that opens the thread.
+   *
+   * Rejects with `InputRejectedError` when the session refused the input,
+   * and with an error for an id this session does not know.
+   *
+   * @example
+   * ```ts
+   * const turn = session.prompt('Summarize the report.', { inputId: 'req-42' })
+   * const { outcome } = await session.settled('req-42')
+   * ```
+   */
+  async settled(inputId: string): Promise<InputSettlement> {
+    const known = this.knownSettlement(inputId)
+    if (known) return known
+    if (!this.isChatInput(inputId)) {
+      throw new Error(
+        `The session knows no chat input with the id ${JSON.stringify(inputId)}.`,
+      )
+    }
+    const settledEvent = (entry: SessionEvent) =>
+      entry.event.type === EventType.CUSTOM &&
+      entry.event.name === HARNESS_EVENTS.inputSettled &&
+      isRecord(entry.event.value) &&
+      entry.event.value.inputId === inputId
+    for await (const _entry of this.feed.read({
+      from: this.feed.head(),
+      filter: settledEvent,
+    })) {
+      const settlement = this.knownSettlement(inputId)
+      if (settlement) return settlement
+    }
+    throw new Error('The session closed before the input ended.')
+  }
+
   // ===========================
   // Events and state
   // ===========================
@@ -1169,11 +1329,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   // Chat turns
   // ===========================
 
-  private createTurnOperation(): OperationImpl<ChatTurnResult> {
+  private createTurnOperation(id?: string): OperationImpl<ChatTurnResult> {
     const operation = new OperationImpl<ChatTurnResult>(
       'chat',
       this.feed,
       (target) => this.cancel(target.id),
+      undefined,
+      id,
     )
     this.operations.set(operation.id, operation as OperationImpl<unknown>)
     return operation
@@ -1404,10 +1566,41 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     await store.saveThread(this.threadId, history.with(index, updated))
   }
 
+  /**
+   * Abort `operation` when its input passes `timeoutAt` (a durable host with
+   * `durability.timeoutMs`). Returns the function that stops the timer.
+   */
+  private startTimeout(
+    inputId: string | undefined,
+    operation: OperationImpl<ChatTurnResult>,
+  ) {
+    const timeoutAt =
+      inputId === undefined
+        ? undefined
+        : this.writer?.state.inputs.get(inputId)?.timeoutAt
+    if (timeoutAt === undefined) return () => {}
+    const timer = setTimeout(
+      () => operation.abortController.abort(TIMEOUT_REASON),
+      Math.max(0, timeoutAt - Date.now()),
+    )
+    if (typeof timer === 'object' && 'unref' in timer) timer.unref()
+    return () => clearTimeout(timer)
+  }
+
   private async runTurn(turn: QueuedTurn): Promise<void> {
     const { operation } = turn
     operation.setStatus('running')
-    if (turn.inputId) await this.applied(turn.inputId, operation.id)
+    if (turn.inputId) {
+      try {
+        await this.applied(turn.inputId, operation.id)
+      } catch (error) {
+        // The log refused the write, so the session stops.
+        operation.fail('failed', this.logFailure ?? error)
+        this.publishFinished(operation)
+        return
+      }
+    }
+    const stopTimer = this.startTimeout(turn.inputId, operation)
     this.publishStarted(operation)
 
     let runPlugins: MountedPlugins | undefined
@@ -1573,8 +1766,10 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         })
       }
     } finally {
+      stopTimer()
       await runPlugins?.dispose().catch(() => {})
     }
+    const timedOut = operation.abortController.signal.reason === TIMEOUT_REASON
 
     // The stream has ended, so withPersistence has saved the turn. A failed or
     // cancelled turn may not have saved its answer, and its last assistant
@@ -1591,26 +1786,54 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       )
     }
 
+    const { inputId } = turn
+    // The settlement lands before the operation ends, so a caller that sees
+    // the result can also read it with `settled()`.
+    const settleTurn = (
+      settlement: Omit<InputSettlement, 'inputId' | 'operationId'>,
+    ) =>
+      inputId === undefined || this.logFailure
+        ? Promise.resolve()
+        : this.settle({
+            inputId,
+            operationId: operation.id,
+            ...settlement,
+          }).catch(() => {})
     if (this.logFailure) {
       operation.fail('failed', this.logFailure)
+    } else if (timedOut) {
+      const message = 'The input passed its time limit.'
+      await settleTurn({
+        outcome: 'failed',
+        error: { message, code: 'timeout' },
+      })
+      operation.fail('failed', new Error(message))
     } else if (operation.abortController.signal.aborted) {
+      await settleTurn({ outcome: 'aborted' })
       operation.fail('cancelled', new Error('Cancelled.'))
     } else if (failure !== undefined) {
+      await settleTurn({ outcome: 'failed', error: { message: failure } })
       operation.fail('failed', new Error(failure))
     } else if (interrupts && interrupts.length > 0) {
       this.interrupted = { runId: operation.id, interrupts }
+      await settleTurn({ outcome: 'interrupted' })
       operation.finish('interrupted', { text, interrupts })
     } else {
+      await settleTurn({ outcome: 'completed' })
       operation.finish('completed', { text })
     }
     this.publishFinished(operation)
     // Steers the turn never reached run next, before other queued turns.
     this.queue.unshift(
-      ...this.steerQueue.splice(0).map((steer) => ({
-        operation: steer.operation ?? this.createTurnOperation(),
-        message: steer.message,
-        inputId: steer.inputId,
-      })),
+      ...this.steerQueue.splice(0).map((steer) => {
+        const next = steer.operation ?? this.createTurnOperation()
+        this.bindTurn(steer.inputId, next)
+        return {
+          operation: next,
+          message: steer.message,
+          inputId: steer.inputId,
+        }
+      }),
     )
   }
 
@@ -1864,22 +2087,81 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   // Inbox and lifecycle events
   // ===========================
 
-  private async accept(inputId: string, input: HarnessInput): Promise<void> {
-    await this.inbox.append({
-      inputId,
-      threadId: this.threadId,
-      input,
-      createdAt: Date.now(),
-      ...(this.principal ? { principal: { id: this.principal.id } } : {}),
-    })
+  /**
+   * Store an input, unless its id is known. The check before the first
+   * `await` is synchronous, so a second call with the same id in the same
+   * tick is a duplicate too.
+   */
+  private async accept(
+    inputId: string,
+    input: HarnessInput,
+  ): Promise<'new' | 'duplicate' | 'conflict'> {
+    const payload = JSON.stringify(input)
+    const local = this.admitted.get(inputId)
+    if (local !== undefined) return local === payload ? 'duplicate' : 'conflict'
+    const logged = this.writer?.state.inputs.get(inputId)
+    if (logged) {
+      return JSON.stringify(logged.input) === payload ? 'duplicate' : 'conflict'
+    }
+    this.admitted.set(inputId, payload)
+    const at = Date.now()
+    const principal = this.principal
+      ? { principal: { id: this.principal.id } }
+      : {}
+    if (this.writer) {
+      await this.writer.append([
+        { type: 'harness.input', inputId, input, at, ...principal },
+      ])
+    } else {
+      const stored = await this.inbox.append({
+        inputId,
+        threadId: this.threadId,
+        input,
+        createdAt: at,
+        ...principal,
+      })
+      // The inbox had the id before this session: a restart.
+      if (stored.createdAt !== at || stored.status !== 'pending') {
+        return JSON.stringify(stored.input) === payload
+          ? 'duplicate'
+          : 'conflict'
+      }
+    }
     this.feed.publish(
       'session',
       customEvent(HARNESS_EVENTS.inputAccepted, { inputId, op: input.op }),
     )
+    return 'new'
+  }
+
+  /** Record that `operationId` runs the input. A durable host counts attempts. */
+  private async markApplied(
+    inputId: string,
+    operationId: string,
+  ): Promise<void> {
+    if (!this.writer) {
+      await this.inbox.markApplied(inputId, operationId)
+      return
+    }
+    const logged = this.writer.state.inputs.get(inputId)
+    const timeoutMs = this.harness.durability?.timeoutMs
+    // Stamped once, at the first apply. Retries do not move it.
+    const timeoutAt =
+      logged?.timeoutAt ??
+      (timeoutMs !== undefined ? Date.now() + timeoutMs : undefined)
+    await this.writer.append([
+      {
+        type: 'harness.input.applied',
+        inputId,
+        operationId,
+        attempt: (logged?.attempt ?? 0) + 1,
+        ...(timeoutAt !== undefined ? { timeoutAt } : {}),
+      },
+    ])
   }
 
   private async applied(inputId: string, operationId: string): Promise<void> {
-    await this.inbox.markApplied(inputId, operationId)
+    await this.markApplied(inputId, operationId)
     this.feed.publish(
       operationId,
       customEvent(HARNESS_EVENTS.inputApplied, { inputId, operationId }),
@@ -1887,13 +2169,178 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   }
 
   private reject(inputId: string, reason: string): void {
-    void this.inbox.markRejected(inputId, reason)
+    if (this.writer) {
+      void this.writer
+        .append([{ type: 'harness.input.rejected', inputId, reason }])
+        .catch(() => {})
+    } else {
+      void this.inbox.markRejected(inputId, reason)
+    }
+    this.receipts.set(inputId, { inputId, status: 'rejected', reason })
     this.feed.publish(
       'session',
       customEvent(HARNESS_EVENTS.inputRejected, { inputId, reason }),
     )
   }
 
+  /**
+   * Record how inputs ended, all in one append: a turn and the inputs that
+   * joined it settle together. Clients get a `harness.input.settled` event.
+   */
+  private async settle(...settlements: Array<InputSettlement>): Promise<void> {
+    if (this.writer) {
+      await this.writer.append(
+        settlements.map((settlement) => ({
+          type: 'harness.input.settled',
+          ...settlement,
+        })),
+      )
+    }
+    for (const settlement of settlements) {
+      this.settlements.set(settlement.inputId, settlement)
+      this.feed.publish(
+        settlement.operationId ?? 'session',
+        customEvent(HARNESS_EVENTS.inputSettled, { ...settlement }),
+      )
+    }
+  }
+
+  /** How a chat input ended, when it did. Throws for a refused input. */
+  private knownSettlement(inputId: string): InputSettlement | undefined {
+    const logged = this.writer?.state.inputs.get(inputId)
+    if (logged?.settlement) return logged.settlement
+    const refused =
+      logged?.status === 'rejected'
+        ? { inputId, status: 'rejected' as const, reason: logged.reason ?? '' }
+        : this.receipts.get(inputId)
+    if (refused?.status === 'rejected') throw new InputRejectedError(refused)
+    return this.settlements.get(inputId)
+  }
+
+  private isChatInput(inputId: string) {
+    const input = this.writer?.state.inputs.get(inputId)?.input
+    if (input) return CHAT_OPS.has(input.op)
+    return this.turnOperations.has(inputId) || this.receipts.has(inputId)
+  }
+
+  /** Link a turn operation and its input. */
+  private bindTurn(inputId: string, operation: OperationImpl<ChatTurnResult>) {
+    this.turnOperations.set(inputId, operation)
+    this.operationInputs.set(operation.id, inputId)
+  }
+
+  /** Keep a chat input's receipt, for a duplicate of the input. */
+  private keep(receipt: Receipt): Receipt {
+    this.receipts.set(receipt.inputId, receipt)
+    return receipt
+  }
+
+  /** Resolve a turn's receipt, and keep it for a duplicate. */
+  private answerTurn(
+    operation: OperationImpl<ChatTurnResult>,
+    receipt: Receipt,
+  ) {
+    operation.resolveReceipt(this.keep(receipt))
+  }
+
+  private refuse(operation: OperationImpl<ChatTurnResult>, receipt: Receipt) {
+    this.answerTurn(operation, receipt)
+    operation.fail('failed', new InputRejectedError(receipt))
+  }
+
+  /** What a duplicate or a conflicting chat input gets back. */
+  private duplicateReceipt(
+    inputId: string,
+    admission: 'duplicate' | 'conflict',
+  ): Receipt {
+    if (admission === 'conflict') {
+      return { inputId, status: 'rejected', reason: 'conflict' }
+    }
+    const kept = this.receipts.get(inputId)
+    if (kept) return kept
+    const operationId = this.writer?.state.inputs.get(inputId)?.operationId
+    return {
+      inputId,
+      status: 'accepted',
+      ...(operationId ? { operationId } : {}),
+    }
+  }
+
+  /**
+   * The operation for a prompt whose id is known: the live one, one that
+   * settles from the log, or a refused one for another payload.
+   */
+  private knownTurn(inputId: string, input: HarnessInput) {
+    const payload = JSON.stringify(input)
+    const local = this.admitted.get(inputId)
+    const logged = this.writer?.state.inputs.get(inputId)
+    const stored = local ?? (logged ? JSON.stringify(logged.input) : undefined)
+    if (stored === undefined) return undefined
+    if (stored !== payload) {
+      const refused = this.createTurnOperation()
+      this.refuse(refused, { inputId, status: 'rejected', reason: 'conflict' })
+      return refused
+    }
+    const live = this.turnOperations.get(inputId)
+    if (live) return live
+    const replay = this.createTurnOperation(logged?.operationId)
+    this.answerDuplicate(replay, inputId, 'duplicate')
+    return replay
+  }
+
+  /** Settle `operation` like the earlier input with the same id. */
+  private answerDuplicate(
+    operation: OperationImpl<ChatTurnResult>,
+    inputId: string,
+    admission: 'duplicate' | 'conflict',
+  ) {
+    const receipt = this.duplicateReceipt(inputId, admission)
+    if (receipt.status === 'rejected') {
+      this.refuse(operation, receipt)
+      return
+    }
+    operation.resolveReceipt(receipt)
+    if (!this.writer) {
+      // Without a log, the result of an input from before a restart is gone.
+      operation.fail(
+        'failed',
+        new Error(
+          'This input ran before a restart. Keep its result with a durable host (stores.log).',
+        ),
+      )
+      return
+    }
+    void this.settled(inputId).then(
+      (settlement) => this.settleOperation(operation, settlement),
+      (error: unknown) => operation.fail('failed', error),
+    )
+  }
+
+  /** End `operation` with a stored settlement. */
+  private settleOperation(
+    operation: OperationImpl<ChatTurnResult>,
+    settlement: InputSettlement,
+  ) {
+    const text = lastAssistantText(this.writer?.state.messages ?? [])
+    switch (settlement.outcome) {
+      case 'completed':
+        operation.finish('completed', { text })
+        return
+      case 'interrupted':
+        operation.finish('interrupted', { text, interrupts: [] })
+        return
+      case 'aborted':
+        operation.fail('cancelled', new Error('Cancelled.'))
+        return
+      case 'failed':
+        operation.fail(
+          'failed',
+          new Error(settlement.error?.message ?? 'The input failed.'),
+        )
+        return
+    }
+  }
+
   private publishStarted(
     operation: OperationImpl<unknown> | OperationImpl<ChatTurnResult>,
   ): void {
@@ -1965,6 +2412,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         input.op === 'steer'
       ) {
         const operation = this.createTurnOperation()
+        this.admitted.set(entry.inputId, JSON.stringify(input))
+        this.bindTurn(entry.inputId, operation)
         this.enqueueTurn({
           operation,
           message: input.message,
@@ -1975,4 +2424,97 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       }
     }
   }
+
+  /**
+   * Recover a durable session from its log, input by input, in admission
+   * order. A chat turn whose host stopped (its run lease expired) settles
+   * `aborted` when an abort was asked, settles `failed` when no attempt or no
+   * time is left, settles `completed` when the log already has its final
+   * answer, and else runs again as the next attempt. An input that never ran
+   * runs now. Other inputs are rejected with `expired_on_restart`.
+   */
+  private async recoverFromLog(writer: LogWriter): Promise<void> {
+    const runs = this.persistence.stores.runs
+    const maxAttempts = this.harness.durability?.maxAttempts ?? 10
+    const inputs = [...writer.state.inputs.values()]
+    for (const input of inputs) {
+      const isChat = CHAT_OPS.has(input.input.op)
+      if (input.status === 'pending') {
+        if (isChat && 'message' in input.input) {
+          const operation = this.createTurnOperation()
+          this.bindTurn(input.inputId, operation)
+          this.enqueueTurn({
+            operation,
+            message: input.input.message,
+            inputId: input.inputId,
+          })
+        } else {
+          this.reject(input.inputId, 'expired_on_restart')
+        }
+        continue
+      }
+      if (input.status !== 'applied' || !isChat) continue
+      const run = input.operationId ? await runs?.get(input.operationId) : null
+      const now = Date.now()
+      const isAlive =
+        run?.status === 'running' &&
+        run.leaseExpiresAt !== undefined &&
+        run.leaseExpiresAt >= now
+      // Another host still drives this turn.
+      if (isAlive) continue
+      if (run?.status === 'running') {
+        await runs?.update(run.runId, {
+          status: 'failed',
+          finishedAt: now,
+          error: { message: 'The host stopped during this turn.' },
+        })
+      }
+      const operationId = input.operationId
+      const ended = (settlement: Omit<InputSettlement, 'inputId'>) =>
+        this.settle({
+          inputId: input.inputId,
+          ...(operationId ? { operationId } : {}),
+          ...settlement,
+        })
+      if (input.abortRequested) {
+        await ended({ outcome: 'aborted' })
+      } else if (input.attempt >= maxAttempts) {
+        await ended({
+          outcome: 'failed',
+          error: {
+            message: `The input stopped the host ${input.attempt} times.`,
+            code: 'attempts_exhausted',
+          },
+        })
+      } else if (input.timeoutAt !== undefined && now >= input.timeoutAt) {
+        await ended({
+          outcome: 'failed',
+          error: {
+            message: 'The input passed its time limit.',
+            code: 'timeout',
+          },
+        })
+      } else if (hasFinalAnswer(writer.state.messages, input.appliedAt ?? 0)) {
+        await ended({ outcome: 'completed' })
+      } else {
+        if (run) {
+          await repairTranscript({
+            messages: this.messages,
+            crashed: run,
+            finished: writer.state.toolResults,
+          })
+        }
+        const operation = this.createTurnOperation()
+        this.bindTurn(input.inputId, operation)
+        this.feed.publish(
+          operation.id,
+          customEvent(HARNESS_EVENTS.operationResumed, {
+            operationId: operation.id,
+            ...(operationId ? { resumedFrom: operationId } : {}),
+          }),
+        )
+        this.enqueueTurn({ operation, inputId: input.inputId })
+      }
+    }
+  }
 }
diff --git a/packages/ai-harness/src/types.ts b/packages/ai-harness/src/types.ts
index 61e8be36a5..f941a60ea7 100644
--- a/packages/ai-harness/src/types.ts
+++ b/packages/ai-harness/src/types.ts
@@ -89,12 +89,20 @@ export class InputRejectedError extends Error {
   readonly receipt: Receipt
 
   constructor(receipt: Receipt) {
-    super(`The session rejected the input: ${receipt.reason ?? 'rejected'}.`)
+    super(rejectionMessage(receipt.reason))
     this.name = 'InputRejectedError'
     this.receipt = receipt
   }
 }
 
+function rejectionMessage(reason: string | undefined) {
+  if (reason === 'busy') return 'A chat turn is already running.'
+  if (reason === 'conflict') {
+    return 'An earlier input has this inputId and another payload.'
+  }
+  return `The session rejected the input: ${reason ?? 'rejected'}.`
+}
+
 /** Who sent an input, from the host's `authorize`. */
 export interface Principal {
   id: string
diff --git a/packages/ai-harness/tests/durable-inputs.test.ts b/packages/ai-harness/tests/durable-inputs.test.ts
new file mode 100644
index 0000000000..5e891bf9ac
--- /dev/null
+++ b/packages/ai-harness/tests/durable-inputs.test.ts
@@ -0,0 +1,354 @@
+import { describe, expect, it, vi } from 'vitest'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { InputRejectedError, createHarnessHost, defineHarness } from '../src'
+import { gate, mockAdapter, text, untilAborted } from './helpers'
+import type { ModelMessage } from '@tanstack/ai'
+import type { LogRecord } from '@tanstack/ai-persistence'
+import type { HarnessDurability } from '../src'
+import type { Reply } from './helpers'
+
+const THREAD = 't1'
+
+function durablePersistence() {
+  const { runs, metadata } = memoryPersistence().stores
+  return { stores: { log: memoryLogStore(), runs, metadata } }
+}
+
+type Durable = ReturnType<typeof durablePersistence>
+
+/**
+ * The log and run of a host that stopped during attempt `attempt` of input
+ * `in-1`: the input, its applied record, and the user message that the turn
+ * saved. The run lease has expired.
+ */
+async function seedStoppedTurn(
+  persistence: Durable,
+  options: {
+    attempt: number
+    timeoutAt?: number
+    abort?: boolean
+    answer?: string
+  },
+) {
+  const user: ModelMessage = { id: 'u1', role: 'user', content: 'go' }
+  const records: Array<LogRecord> = [
+    {
+      type: 'harness.input',
+      inputId: 'in-1',
+      input: { op: 'prompt', message: 'go', busy: 'queue' },
+      at: 1,
+    },
+    {
+      type: 'harness.input.applied',
+      inputId: 'in-1',
+      operationId: 'op-stopped',
+      attempt: options.attempt,
+      ...(options.timeoutAt !== undefined
+        ? { timeoutAt: options.timeoutAt }
+        : {}),
+    },
+    {
+      type: 'harness.transcript',
+      keep: 0,
+      add: options.answer
+        ? [user, { id: 'a1', role: 'assistant', content: options.answer }]
+        : [user],
+    },
+    ...(options.abort
+      ? [{ type: 'harness.input.abort', inputId: 'in-1' }]
+      : []),
+  ]
+  await persistence.stores.log.append(THREAD, 1, records)
+  await persistence.stores.runs.createOrResume({
+    runId: 'op-stopped',
+    threadId: THREAD,
+    startedAt: Date.now() - 60_000,
+  })
+  await persistence.stores.runs.update('op-stopped', {
+    leaseOwner: 'host-gone',
+    leaseExpiresAt: Date.now() - 1_000,
+    checkpoint: { at: 1, pendingTools: [] },
+  })
+}
+
+async function openDurable(options: {
+  persistence: Durable
+  replies: Array<Reply>
+  durability?: HarnessDurability
+}) {
+  const { adapter, calls } = mockAdapter(options.replies)
+  const host = createHarnessHost({ persistence: options.persistence })
+  const session = await host.open(
+    defineHarness({
+      name: 'test/durable-inputs',
+      adapter,
+      ...(options.durability ? { durability: options.durability } : {}),
+    }),
+    { threadId: THREAD },
+  )
+  return { host, session, calls }
+}
+
+const recordTypes = async (persistence: Durable) =>
+  (await persistence.stores.log.read(THREAD)).map((entry) => entry.record.type)
+
+describe('recovery of a durable input', () => {
+  it('settles failed when the attempts are used up, with no model call', async () => {
+    const persistence = durablePersistence()
+    await seedStoppedTurn(persistence, { attempt: 3 })
+
+    const { host, session, calls } = await openDurable({
+      persistence,
+      replies: [() => text('never')],
+      durability: { maxAttempts: 3 },
+    })
+
+    expect(await session.settled('in-1')).toEqual({
+      inputId: 'in-1',
+      outcome: 'failed',
+      operationId: 'op-stopped',
+      error: {
+        message: 'The input stopped the host 3 times.',
+        code: 'attempts_exhausted',
+      },
+    })
+    expect(calls).toHaveLength(0)
+    expect((await persistence.stores.runs.get('op-stopped'))?.status).toBe(
+      'failed',
+    )
+    await host.close()
+  })
+
+  it('runs the next attempt while attempts are left', async () => {
+    const persistence = durablePersistence()
+    await seedStoppedTurn(persistence, { attempt: 1 })
+
+    const { host, session, calls } = await openDurable({
+      persistence,
+      replies: [() => text('recovered')],
+      durability: { maxAttempts: 3 },
+    })
+    const settlement = await session.settled('in-1')
+
+    expect(settlement.outcome).toBe('completed')
+    expect(calls).toHaveLength(1)
+    const applied = (await persistence.stores.log.read(THREAD))
+      .map((entry) => entry.record)
+      .filter((record) => record.type === 'harness.input.applied')
+    expect(applied.map((record) => record.attempt)).toEqual([1, 2])
+    await host.close()
+  })
+
+  it('settles failed when the time limit passed, with attempts left', async () => {
+    const persistence = durablePersistence()
+    await seedStoppedTurn(persistence, {
+      attempt: 1,
+      timeoutAt: Date.now() - 1,
+    })
+
+    const { host, session, calls } = await openDurable({
+      persistence,
+      replies: [() => text('never')],
+      durability: { maxAttempts: 10, timeoutMs: 60_000 },
+    })
+
+    expect(await session.settled('in-1')).toMatchObject({
+      outcome: 'failed',
+      error: { code: 'timeout' },
+    })
+    expect(calls).toHaveLength(0)
+    await host.close()
+  })
+
+  it('settles aborted after an abort request, with no model call', async () => {
+    const persistence = durablePersistence()
+    await seedStoppedTurn(persistence, { attempt: 1, abort: true })
+
+    const { host, session, calls } = await openDurable({
+      persistence,
+      replies: [() => text('never')],
+    })
+
+    expect(await session.settled('in-1')).toMatchObject({ outcome: 'aborted' })
+    expect(calls).toHaveLength(0)
+    await host.close()
+  })
+
+  it('settles completed when the log already has the final answer', async () => {
+    const persistence = durablePersistence()
+    await seedStoppedTurn(persistence, { attempt: 1, answer: 'done before' })
+
+    const { host, session, calls } = await openDurable({
+      persistence,
+      replies: [() => text('never')],
+    })
+
+    expect(await session.settled('in-1')).toMatchObject({
+      outcome: 'completed',
+    })
+    expect(calls).toHaveLength(0)
+    await host.close()
+  })
+})
+
+describe('durable input limits while a turn runs', () => {
+  it('aborts a turn at its time limit and settles it failed', async () => {
+    const persistence = durablePersistence()
+    const { host, session } = await openDurable({
+      persistence,
+      replies: [untilAborted()],
+      durability: { timeoutMs: 30 },
+    })
+
+    const turn = session.prompt('slow', { inputId: 'slow-1' })
+
+    await expect(turn).rejects.toThrow('The input passed its time limit.')
+    expect(await session.settled('slow-1')).toMatchObject({
+      outcome: 'failed',
+      error: { code: 'timeout' },
+    })
+    await host.close()
+  })
+
+  it('stores the abort request before it cancels the turn', async () => {
+    const persistence = durablePersistence()
+    const { host, session, calls } = await openDurable({
+      persistence,
+      replies: [untilAborted()],
+    })
+    const turn = session.prompt('wait', { inputId: 'wait-1' })
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+
+    await session.cancel(turn.id)
+
+    await expect(turn).rejects.toThrow('Cancelled.')
+    expect(await session.settled('wait-1')).toMatchObject({
+      outcome: 'aborted',
+    })
+    const types = await recordTypes(persistence)
+    expect(types.indexOf('harness.input.abort')).toBeLessThan(
+      types.indexOf('harness.input.settled'),
+    )
+    await host.close()
+  })
+})
+
+describe('input ids', () => {
+  it('returns the first operation for a duplicate, and runs once', async () => {
+    const persistence = durablePersistence()
+    const { host, session, calls } = await openDurable({
+      persistence,
+      replies: [() => text('once')],
+    })
+
+    const first = session.prompt('hi', { inputId: 'dup-1' })
+    const again = session.prompt('hi', { inputId: 'dup-1' })
+
+    expect(again).toBe(first)
+    expect(await first).toEqual({ text: 'once' })
+    expect(calls).toHaveLength(1)
+    await host.close()
+  })
+
+  it('rejects the same id with another payload as a conflict', async () => {
+    const persistence = durablePersistence()
+    const { host, session } = await openDurable({
+      persistence,
+      replies: [() => text('first')],
+    })
+    await session.prompt('hi', { inputId: 'dup-1' })
+
+    const other = session.prompt('something else', { inputId: 'dup-1' })
+
+    await expect(other).rejects.toBeInstanceOf(InputRejectedError)
+    expect(await other.receipt).toEqual({
+      inputId: 'dup-1',
+      status: 'rejected',
+      reason: 'conflict',
+    })
+    expect(await session.followUp('x', { inputId: 'dup-1' })).toMatchObject({
+      status: 'rejected',
+      reason: 'conflict',
+    })
+    await host.close()
+  })
+
+  it('settles a duplicate after a restart from the log, with no model call', async () => {
+    const persistence = durablePersistence()
+    const first = await openDurable({
+      persistence,
+      replies: [() => text('from the first host')],
+    })
+    const original = first.session.prompt('hi', { inputId: 'dup-1' })
+    await original
+    await first.host.close()
+
+    const second = await openDurable({
+      persistence,
+      replies: [() => text('never')],
+    })
+    const replay = second.session.prompt('hi', { inputId: 'dup-1' })
+
+    expect(await replay).toEqual({ text: 'from the first host' })
+    expect(await replay.receipt).toEqual({
+      inputId: 'dup-1',
+      status: 'accepted',
+      operationId: original.id,
+    })
+    expect(second.calls).toHaveLength(0)
+    await second.host.close()
+  })
+
+  it('resolves the receipt when the input is in the log, before the turn ends', async () => {
+    const persistence = durablePersistence()
+    const release = gate()
+    const { host, session } = await openDurable({
+      persistence,
+      replies: [
+        () =>
+          (async function* () {
+            await release.opened
+            yield* text('late')
+          })(),
+      ],
+    })
+
+    const turn = session.prompt('hi', { inputId: 'r-1' })
+    const receipt = await turn.receipt
+
+    expect(receipt).toEqual({
+      inputId: 'r-1',
+      status: 'accepted',
+      operationId: turn.id,
+    })
+    expect(await recordTypes(persistence)).toContain('harness.input')
+    expect(turn.status()).not.toBe('completed')
+    release.open()
+    await turn
+    await host.close()
+  })
+})
+
+describe('settled() without a log', () => {
+  it('gives the outcome of a live input, and refuses an unknown id', async () => {
+    const { adapter } = mockAdapter([() => text('fine')])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({ name: 'test/settled', adapter }),
+      { threadId: THREAD },
+    )
+
+    const turn = session.prompt('hi', { inputId: 'live-1' })
+    await turn
+
+    expect(await session.settled('live-1')).toEqual({
+      inputId: 'live-1',
+      outcome: 'completed',
+      operationId: turn.id,
+    })
+    await expect(session.settled('missing')).rejects.toThrow(
+      'knows no chat input',
+    )
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/protocol.test.ts b/packages/ai-harness/tests/protocol.test.ts
index b37209e84c..70d9cadf73 100644
--- a/packages/ai-harness/tests/protocol.test.ts
+++ b/packages/ai-harness/tests/protocol.test.ts
@@ -180,6 +180,34 @@ describe('HTTP handler', () => {
     await host.close()
   })
 
+  it('answers a retried prompt with the same inputId with the first receipt', async () => {
+    const { handler, host, calls } = 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-retry', input }),
+          }),
+        )
+      ).json()
+
+    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 = async (input: unknown) =>

From e571a53e7f9197ba7ec71ed14b64d9c902158103 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 12:45:21 +0200
Subject: [PATCH 082/286] feat(ai-harness): durable ordered joins, and late
 steers answered in the same turn

Steers join the running turn in admission order before the next model call. On a durable host one append holds the join records and the transcript commit with their messages, so a crash never splits a join. A turn and the inputs that joined it settle together. When steers still wait after a final answer, the turn runs chat() again in the same operation, so a late steer is answered in the same turn. snapshot().queuedTurns now counts steers that wait to join.
---
 packages/ai-harness/src/log.ts                |  13 +-
 packages/ai-harness/src/session.ts            | 318 +++++++++++-------
 .../ai-harness/tests/durable-joins.test.ts    | 254 ++++++++++++++
 packages/ai-harness/tests/goal.test.ts        |   2 +-
 packages/ai-harness/tests/session.test.ts     |  12 +-
 5 files changed, 464 insertions(+), 135 deletions(-)
 create mode 100644 packages/ai-harness/tests/durable-joins.test.ts

diff --git a/packages/ai-harness/src/log.ts b/packages/ai-harness/src/log.ts
index 008a5afafd..6e5f13eb76 100644
--- a/packages/ai-harness/src/log.ts
+++ b/packages/ai-harness/src/log.ts
@@ -813,13 +813,17 @@ export function engineMessageStore(options: {
     },
     /**
      * Before each model call: commit the engine's `list` (it has the tool
-     * results of the last phase) on top of the fold. Returns the list the
-     * model gets when a host record changed it, else `undefined`.
+     * results of the last phase) on top of the fold, with `records` in the
+     * same append. Returns the list the model gets when a host record
+     * changed it, else `undefined`.
      */
-    beforeModel: async (list: ReadonlyArray<ModelMessage>) => {
+    beforeModel: async (
+      list: ReadonlyArray<ModelMessage>,
+      records: ReadonlyArray<LogRecord> = [],
+    ) => {
       const target = rebase(held, [...list])
       held = [...target]
-      await writer.commit({ messages: target })
+      await writer.commit({ messages: target, records })
       const isSame =
         target.length === list.length &&
         commonPrefix(target, list) === list.length
@@ -828,6 +832,7 @@ export function engineMessageStore(options: {
   } satisfies MessageStore & {
     beforeModel: (
       list: ReadonlyArray<ModelMessage>,
+      records?: ReadonlyArray<LogRecord>,
     ) => Promise<Array<ModelMessage> | undefined>
   }
   return engine
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 226564ee65..f8f7925987 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -340,6 +340,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   >()
   /** The input of each turn operation, by operation id. */
   private readonly operationInputs = new Map<string, string>()
+  /** The inputs that joined each turn, by operation id. */
+  private readonly turnJoins = new Map<string, Array<string>>()
   /** How the chat inputs of this session ended, for `settled()`. */
   private readonly settlements = new Map<string, InputSettlement>()
   private readonly agentRegistry = new AgentRegistry()
@@ -864,7 +866,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         kind: operation.kind,
         ...(operation.agent ? { agent: operation.agent } : {}),
       })),
-      queuedTurns: this.queue.length,
+      // A steer that waits to join the running turn waits too.
+      queuedTurns: this.queue.length + this.steerQueue.length,
       pendingInterrupts: this.interrupted?.interrupts ?? [],
       pendingQuestions: [...this.questions.entries()].map(
         ([questionId, question]) => ({
@@ -1416,56 +1419,84 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   }
 
   /**
-   * Middleware that runs before each model call. On a durable host it
-   * commits the engine's messages, and it sends the folded log when a host
-   * record changed the context. Then it adds queued steer messages.
+   * Middleware that runs before each model call. Queued steers join the
+   * running turn in admission order. On a durable host, one append commits
+   * the engine's messages, the steer messages, and the join records, so a
+   * crash never splits a join. The model gets the folded log when a host
+   * record changed the context.
    */
   private steering(): AnyChatMiddleware {
     return {
       name: 'harness:steering',
       onConfig: async (ctx, config) => {
         if (ctx.phase !== 'beforeModel') return undefined
-        const synced = await this.engine?.beforeModel(config.messages)
-        if (this.steerQueue.length === 0) {
-          return synced ? { messages: synced } : undefined
-        }
         const steers = this.steerQueue.splice(0)
-        const running = this.activeTurn
-        for (const steer of steers) {
-          // A prompt that joined the running turn settles with that turn.
-          if (steer.operation && running) {
-            const joined = steer.operation
-            this.operations.delete(joined.id)
-            running.then(
-              (result) => joined.finish('completed', result),
-              (error: unknown) => joined.fail('failed', error),
-            )
-          }
-          void this.inbox.markApplied(steer.inputId, ctx.runId)
-          this.feed.publish(
-            ctx.runId,
-            customEvent(HARNESS_EVENTS.inputApplied, {
+        const added = steers.map(
+          (steer): ModelMessage => ({
+            id: createMessageId(),
+            role: 'user',
+            content: steer.message,
+          }),
+        )
+        const hostInput = this.operationInputs.get(ctx.runId)
+        const joins = hostInput
+          ? steers.map((steer) => ({
+              type: 'harness.input.joined',
               inputId: steer.inputId,
-              operationId: ctx.runId,
-            }),
-          )
-        }
-        return {
-          messages: [
-            ...(synced ?? config.messages),
-            ...steers.map(
-              (steer): ModelMessage => ({
-                id: createMessageId(),
-                role: 'user',
-                content: steer.message,
-              }),
-            ),
-          ],
-        }
+              into: hostInput,
+            }))
+          : []
+        const list = [...config.messages, ...added]
+        const synced = await this.engine?.beforeModel(list, joins)
+        for (const steer of steers) this.join(ctx.runId, steer)
+        if (steers.length === 0 && !synced) return undefined
+        return { messages: synced ?? list }
       },
     }
   }
 
+  /**
+   * `steer` joined the running turn `operationId`: it settles with that
+   * turn, and a prompt that joined gets the turn's result.
+   */
+  private join(
+    operationId: string,
+    steer: { inputId: string; operation?: OperationImpl<ChatTurnResult> },
+  ) {
+    const joined = this.turnJoins.get(operationId) ?? []
+    joined.push(steer.inputId)
+    this.turnJoins.set(operationId, joined)
+    const running = this.activeTurn
+    if (steer.operation && running) {
+      const follower = steer.operation
+      this.operations.delete(follower.id)
+      running.then(
+        (result) => follower.finish('completed', result),
+        (error: unknown) => follower.fail('failed', error),
+      )
+    }
+    if (!this.writer) void this.inbox.markApplied(steer.inputId, operationId)
+    this.feed.publish(
+      operationId,
+      customEvent(HARNESS_EVENTS.inputApplied, {
+        inputId: steer.inputId,
+        operationId,
+      }),
+    )
+  }
+
+  /** The inputs that joined the turn of `hostInput` (or operation). */
+  private joinedInputs(operationId: string, hostInput: string | undefined) {
+    if (this.writer && hostInput !== undefined) {
+      return [...this.writer.state.inputs.values()]
+        .filter(
+          (input) => input.status === 'joined' && input.into === hostInput,
+        )
+        .map((input) => input.inputId)
+    }
+    return this.turnJoins.get(operationId) ?? []
+  }
+
   /**
    * A tree budget for a child started from code. The child counts as the
    * first call, and its own children count against the same limits.
@@ -1674,87 +1705,108 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       const adapter: AnyTextAdapter = await this.keys.adapter(
         picked ?? this.harness.adapter,
       )
-      const message =
+      let message =
         turn.message !== undefined
           ? await this.userMessage(turn.message)
           : undefined
-      if (!this.chatPersistence || !this.checkpoint) {
+      let resume = turn.resume
+      let parentRunId = turn.parentRunId
+      const { chatPersistence, checkpoint } = this
+      if (!chatPersistence || !checkpoint) {
         throw new Error('The session is not open yet.')
       }
-      const stream = chat({
-        adapter,
-        messages: message ? [message] : [],
-        systemPrompts: [
-          ...(this.harness.systemPrompts ?? []),
-          ...[...(session?.prompts ?? []), ...(runPlugins?.prompts ?? [])]
-            .map(resolvePrompt)
-            .filter((prompt) => prompt !== ''),
-        ],
-        tools,
-        middleware: [
-          ...bridges,
-          withPersistence(this.chatPersistence),
-          this.checkpoint,
-          ...(this.harness.middleware ?? []),
-          ...(session?.middleware ?? []),
-          ...(runPlugins?.middleware ?? []),
-          this.steering(),
-          // Last, because a later middleware that returns `messages` (as
-          // steering does) resets what the model gets.
-          mediaMiddleware({
-            store: this.mediaStore,
-            accepted: acceptedKinds(
-              adapter.inputModalities,
-              this.harness.media?.accepts,
-            ),
-            transcribe: this.harness.media?.transcribe,
-          }),
-        ],
-        ...(subagentList.length > 0
-          ? {
-              subagents: {
-                ...this.harness.subagents,
-                agents: subagentList,
-                limits: this.limits(),
-                binding: this.binding(operation, captured, runPlugins),
-              },
-            }
-          : {}),
-        // chat() stops after 5 model calls by default. An agent that reads,
-        // searches, and calls tools needs more before it can answer.
-        agentLoopStrategy: this.harness.agentLoopStrategy ?? maxIterations(50),
-        ...(this.harness.modelOptions !== undefined
-          ? { modelOptions: this.harness.modelOptions }
-          : {}),
-        ...(this.harness.interrupts
-          ? { interrupts: this.harness.interrupts }
-          : {}),
-        ...(this.harness.context !== undefined
-          ? { context: this.harness.context }
-          : {}),
-        threadId: this.threadId,
-        runId: operation.id,
-        ...(turn.parentRunId ? { parentRunId: turn.parentRunId } : {}),
-        ...(turn.resume ? { resume: turn.resume } : {}),
-        abortController: operation.abortController,
-        stream: true,
-      } as never) as AsyncIterable<StreamChunk>
-
-      for await (const chunk of stream) {
-        operation.publish(chunk)
-        if (
-          chunk.type === EventType.TEXT_MESSAGE_CONTENT &&
-          !('subagentRunId' in chunk && chunk.subagentRunId)
-        ) {
-          text += chunk.delta
-        }
-        if (
-          chunk.type === EventType.RUN_FINISHED &&
-          chunk.outcome?.type === 'interrupt'
-        ) {
-          interrupts = chunk.outcome.interrupts
+      // One chat() run, and one more each time steers wait after a final
+      // answer: a late join gets its answer in this turn.
+      for (;;) {
+        const stream = chat({
+          adapter,
+          messages: message ? [message] : [],
+          systemPrompts: [
+            ...(this.harness.systemPrompts ?? []),
+            ...[...(session?.prompts ?? []), ...(runPlugins?.prompts ?? [])]
+              .map(resolvePrompt)
+              .filter((prompt) => prompt !== ''),
+          ],
+          tools,
+          middleware: [
+            ...bridges,
+            withPersistence(chatPersistence),
+            checkpoint,
+            ...(this.harness.middleware ?? []),
+            ...(session?.middleware ?? []),
+            ...(runPlugins?.middleware ?? []),
+            this.steering(),
+            // Last, because a later middleware that returns `messages` (as
+            // steering does) resets what the model gets.
+            mediaMiddleware({
+              store: this.mediaStore,
+              accepted: acceptedKinds(
+                adapter.inputModalities,
+                this.harness.media?.accepts,
+              ),
+              transcribe: this.harness.media?.transcribe,
+            }),
+          ],
+          ...(subagentList.length > 0
+            ? {
+                subagents: {
+                  ...this.harness.subagents,
+                  agents: subagentList,
+                  limits: this.limits(),
+                  binding: this.binding(operation, captured, runPlugins),
+                },
+              }
+            : {}),
+          // chat() stops after 5 model calls by default. An agent that reads,
+          // searches, and calls tools needs more before it can answer.
+          agentLoopStrategy:
+            this.harness.agentLoopStrategy ?? maxIterations(50),
+          ...(this.harness.modelOptions !== undefined
+            ? { modelOptions: this.harness.modelOptions }
+            : {}),
+          ...(this.harness.interrupts
+            ? { interrupts: this.harness.interrupts }
+            : {}),
+          ...(this.harness.context !== undefined
+            ? { context: this.harness.context }
+            : {}),
+          threadId: this.threadId,
+          runId: operation.id,
+          ...(parentRunId ? { parentRunId } : {}),
+          ...(resume ? { resume } : {}),
+          abortController: operation.abortController,
+          stream: true,
+        } as never) as AsyncIterable<StreamChunk>
+
+        for await (const chunk of stream) {
+          operation.publish(chunk)
+          if (
+            chunk.type === EventType.TEXT_MESSAGE_CONTENT &&
+            !('subagentRunId' in chunk && chunk.subagentRunId)
+          ) {
+            text += chunk.delta
+          }
+          if (
+            chunk.type === EventType.RUN_FINISHED &&
+            chunk.outcome?.type === 'interrupt'
+          ) {
+            interrupts = chunk.outcome.interrupts
+          }
+          if (chunk.type === EventType.RUN_ERROR) failure = chunk.message
         }
-        if (chunk.type === EventType.RUN_ERROR) failure = chunk.message
+        const hasLateJoin =
+          this.steerQueue.length > 0 &&
+          failure === undefined &&
+          (interrupts?.length ?? 0) === 0 &&
+          !operation.abortController.signal.aborted
+        if (!hasLateJoin) break
+        message = undefined
+        resume = undefined
+        parentRunId = undefined
+        // withPersistence finished the run. It runs again, for the join.
+        await this.persistence.stores.runs?.update(operation.id, {
+          status: 'running',
+        })
       }
     } catch (error) {
       failure = error instanceof Error ? error.message : String(error)
@@ -1787,18 +1839,26 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }
 
     const { inputId } = turn
-    // The settlement lands before the operation ends, so a caller that sees
-    // the result can also read it with `settled()`.
+    // The turn and every input that joined it settle in one append. The
+    // settlement lands before the operation ends, so a caller that sees the
+    // result can also read it with `settled()`.
+    const settled = [
+      ...(inputId === undefined ? [] : [inputId]),
+      ...this.joinedInputs(operation.id, inputId),
+    ]
+    this.turnJoins.delete(operation.id)
     const settleTurn = (
       settlement: Omit<InputSettlement, 'inputId' | 'operationId'>,
     ) =>
-      inputId === undefined || this.logFailure
+      settled.length === 0 || this.logFailure
         ? Promise.resolve()
-        : this.settle({
-            inputId,
-            operationId: operation.id,
-            ...settlement,
-          }).catch(() => {})
+        : this.settle(
+            ...settled.map((id) => ({
+              inputId: id,
+              operationId: operation.id,
+              ...settlement,
+            })),
+          ).catch(() => {})
     if (this.logFailure) {
       operation.fail('failed', this.logFailure)
     } else if (timedOut) {
@@ -2470,12 +2530,16 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         })
       }
       const operationId = input.operationId
+      // The inputs that joined this turn settle with it, in one append.
+      const joined = this.joinedInputs(operationId ?? '', input.inputId)
       const ended = (settlement: Omit<InputSettlement, 'inputId'>) =>
-        this.settle({
-          inputId: input.inputId,
-          ...(operationId ? { operationId } : {}),
-          ...settlement,
-        })
+        this.settle(
+          ...[input.inputId, ...joined].map((inputId) => ({
+            inputId,
+            ...(operationId ? { operationId } : {}),
+            ...settlement,
+          })),
+        )
       if (input.abortRequested) {
         await ended({ outcome: 'aborted' })
       } else if (input.attempt >= maxAttempts) {
diff --git a/packages/ai-harness/tests/durable-joins.test.ts b/packages/ai-harness/tests/durable-joins.test.ts
new file mode 100644
index 0000000000..8872be9888
--- /dev/null
+++ b/packages/ai-harness/tests/durable-joins.test.ts
@@ -0,0 +1,254 @@
+import { describe, expect, it, vi } from 'vitest'
+import { EventType, toolDefinition } from '@tanstack/ai'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '../src'
+import {
+  after,
+  gate,
+  messageTexts,
+  mockAdapter,
+  text,
+  toolCall,
+} from './helpers'
+import type { AnyTool, ModelMessage, StreamChunk } from '@tanstack/ai'
+import type { LogRecord, LogStore } from '@tanstack/ai-persistence'
+import type { Reply } from './helpers'
+
+const THREAD = 't1'
+
+/** A durable store set. `batches` has the record types of each append. */
+function durablePersistence() {
+  const inner = memoryLogStore()
+  const batches: Array<Array<string>> = []
+  const log: LogStore = {
+    append: async (threadId, seq, records) => {
+      await inner.append(threadId, seq, records)
+      batches.push(records.map((record) => record.type))
+    },
+    read: (threadId, options) => inner.read(threadId, options),
+    subscribe: (threadId, listener) => inner.subscribe(threadId, listener),
+  }
+  const { runs, metadata } = memoryPersistence().stores
+  return { persistence: { stores: { log, runs, metadata } }, batches }
+}
+
+type Durable = ReturnType<typeof durablePersistence>['persistence']
+
+async function openDurable(
+  persistence: Durable,
+  replies: Array<Reply>,
+  tools: Array<AnyTool> = [],
+) {
+  const { adapter, calls } = mockAdapter(replies)
+  const host = createHarnessHost({ persistence })
+  const session = await host.open(
+    defineHarness({ name: 'test/joins', adapter, tools }),
+    { threadId: THREAD },
+  )
+  return { host, session, calls }
+}
+
+/** A model call that fails. */
+const fails: Reply = () =>
+  (async function* (): AsyncGenerator<StreamChunk> {
+    yield {
+      type: EventType.RUN_STARTED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: Date.now(),
+    }
+    throw new Error('model down')
+  })()
+
+/**
+ * The log and run of a host that stopped during input `in-1`. With
+ * `joined`, input `in-2` had joined it: its join record and its message are
+ * in one append. Without it, `in-2` was only accepted.
+ */
+async function seedStoppedTurn(
+  persistence: Durable,
+  options: { joined: boolean },
+) {
+  const go: ModelMessage = { id: 'u1', role: 'user', content: 'go' }
+  const more: ModelMessage = { id: 'u2', role: 'user', content: 'and more' }
+  const records: Array<LogRecord> = [
+    {
+      type: 'harness.input',
+      inputId: 'in-1',
+      input: { op: 'prompt', message: 'go', busy: 'queue' },
+      at: 1,
+    },
+    {
+      type: 'harness.input.applied',
+      inputId: 'in-1',
+      operationId: 'op-stopped',
+      attempt: 1,
+    },
+    { type: 'harness.transcript', keep: 0, add: [go] },
+    {
+      type: 'harness.input',
+      inputId: 'in-2',
+      input: { op: 'prompt', message: 'and more', busy: 'steer' },
+      at: 2,
+    },
+    ...(options.joined
+      ? [
+          { type: 'harness.transcript', keep: 1, add: [more] },
+          { type: 'harness.input.joined', inputId: 'in-2', into: 'in-1' },
+        ]
+      : []),
+  ]
+  await persistence.stores.log.append(THREAD, 1, records)
+  await persistence.stores.runs.createOrResume({
+    runId: 'op-stopped',
+    threadId: THREAD,
+    startedAt: Date.now() - 60_000,
+  })
+  await persistence.stores.runs.update('op-stopped', {
+    leaseOwner: 'host-gone',
+    leaseExpiresAt: Date.now() - 1_000,
+    checkpoint: { at: 1, pendingTools: [] },
+  })
+}
+
+describe('durable joins', () => {
+  it('joins three inputs in admission order at the next boundary, in one append', async () => {
+    const { persistence, batches } = durablePersistence()
+    const toolDone = gate()
+    const toolStarted = gate()
+    const wait = toolDefinition({ name: 'wait', description: 'Wait' }).server(
+      async () => {
+        toolStarted.open()
+        await toolDone.opened
+        return 'waited'
+      },
+    )
+    const { host, session, calls } = await openDurable(
+      persistence,
+      [() => toolCall('wait', {}), () => text('all three answered')],
+      [wait],
+    )
+
+    const turn = session.prompt('start', { inputId: 'host' })
+    await toolStarted.opened
+    const joins = ['a', 'b', 'c'].map((name) =>
+      session.prompt(name, { busy: 'steer', inputId: `join-${name}` }),
+    )
+    await Promise.all(joins.map((join) => join.receipt))
+    toolDone.open()
+    await turn
+
+    expect(messageTexts(calls[1]).slice(-3)).toEqual(['a', 'b', 'c'])
+    const joinBatch = batches.find((batch) =>
+      batch.includes('harness.input.joined'),
+    )
+    expect(
+      joinBatch?.filter((type) => type === 'harness.input.joined'),
+    ).toHaveLength(3)
+    expect(joinBatch).toContain('harness.transcript')
+    for (const name of ['a', 'b', 'c']) {
+      expect(await session.settled(`join-${name}`)).toEqual({
+        inputId: `join-${name}`,
+        outcome: 'completed',
+        operationId: turn.id,
+      })
+    }
+    await host.close()
+  })
+
+  it('answers a join that arrives after the last tool call in the same turn', async () => {
+    const { persistence } = durablePersistence()
+    const release = gate()
+    const { host, session, calls } = await openDurable(persistence, [
+      after(release.opened, 'first answer'),
+      () => text('late answer'),
+    ])
+
+    const turn = session.prompt('first', { inputId: 'host' })
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    const late = session.prompt('one more thing', {
+      busy: 'steer',
+      inputId: 'late',
+    })
+    await late.receipt
+    release.open()
+
+    expect(await turn).toEqual({ text: 'first answerlate answer' })
+    expect(calls).toHaveLength(2)
+    expect(messageTexts(calls[1]).at(-1)).toBe('one more thing')
+    expect(await session.settled('late')).toMatchObject({
+      outcome: 'completed',
+      operationId: turn.id,
+    })
+    await host.close()
+  })
+
+  it('settles the joined inputs failed when the turn fails', async () => {
+    const { persistence } = durablePersistence()
+    const release = gate()
+    const { host, session, calls } = await openDurable(persistence, [
+      after(release.opened, 'first answer'),
+      fails,
+    ])
+
+    const turn = session.prompt('first', { inputId: 'host' })
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    const late = session.prompt('this fails', {
+      busy: 'steer',
+      inputId: 'late',
+    })
+    await late.receipt
+    release.open()
+
+    await expect(turn).rejects.toThrow('model down')
+    const expected = {
+      outcome: 'failed',
+      operationId: turn.id,
+      error: { message: 'model down' },
+    }
+    expect(await session.settled('host')).toMatchObject(expected)
+    expect(await session.settled('late')).toMatchObject(expected)
+    await host.close()
+  })
+})
+
+describe('recovery of durable joins', () => {
+  it('adopts a join whose record is in the log: it settles with the next attempt', async () => {
+    const { persistence } = durablePersistence()
+    await seedStoppedTurn(persistence, { joined: true })
+
+    const { host, session, calls } = await openDurable(persistence, [
+      () => text('answered both'),
+    ])
+    const host1 = await session.settled('in-1')
+
+    expect(calls).toHaveLength(1)
+    expect(messageTexts(calls[0]).slice(-2)).toEqual(['go', 'and more'])
+    expect(host1.outcome).toBe('completed')
+    expect(await session.settled('in-2')).toEqual({
+      inputId: 'in-2',
+      outcome: 'completed',
+      operationId: host1.operationId,
+    })
+    await host.close()
+  })
+
+  it('runs an input whose join record is not in the log as its own turn', async () => {
+    const { persistence } = durablePersistence()
+    await seedStoppedTurn(persistence, { joined: false })
+
+    const { host, session, calls } = await openDurable(persistence, [
+      () => text('answer to go'),
+      () => text('answer to more'),
+    ])
+    const first = await session.settled('in-1')
+    const second = await session.settled('in-2')
+
+    expect(calls).toHaveLength(2)
+    expect(messageTexts(calls[1]).at(-1)).toBe('and more')
+    expect(first.outcome).toBe('completed')
+    expect(second.outcome).toBe('completed')
+    expect(second.operationId).not.toBe(first.operationId)
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/goal.test.ts b/packages/ai-harness/tests/goal.test.ts
index f9db454233..3921c2efbe 100644
--- a/packages/ai-harness/tests/goal.test.ts
+++ b/packages/ai-harness/tests/goal.test.ts
@@ -256,7 +256,7 @@ describe('goal', () => {
     await host.close()
   })
 
-  it('drops its queued turn when a late steer pauses the goal', async () => {
+  it('pauses, and queues no goal turn, when a late steer joins its turn', async () => {
     const hold = gate()
     const { host, session, calls } = await start({
       replies: [
diff --git a/packages/ai-harness/tests/session.test.ts b/packages/ai-harness/tests/session.test.ts
index a46b30a72c..9fba1f4c7f 100644
--- a/packages/ai-harness/tests/session.test.ts
+++ b/packages/ai-harness/tests/session.test.ts
@@ -150,7 +150,7 @@ describe('chat turns', () => {
     await host.close()
   })
 
-  it('runs a steer that arrived too late as the next turn', async () => {
+  it('answers a steer that arrived after the last model call in the same turn', async () => {
     const { host } = setup()
     const first = gate()
     const { adapter, calls } = mockAdapter([
@@ -169,9 +169,15 @@ describe('chat turns', () => {
     const joined = session.prompt('and this', { busy: 'steer' })
     first.open()
 
-    await expect(a).resolves.toEqual({ text: 'one' })
-    await expect(joined).resolves.toEqual({ text: 'two' })
+    // One turn answers both messages: the joined prompt settles with it.
+    await expect(a).resolves.toEqual({ text: 'onetwo' })
+    await expect(joined).resolves.toEqual({ text: 'onetwo' })
     expect(messageTexts(calls[1]).at(-1)).toBe('and this')
+    expect(await session.settled((await joined.receipt).inputId)).toEqual({
+      inputId: (await joined.receipt).inputId,
+      outcome: 'completed',
+      operationId: a.id,
+    })
     await host.close()
   })
 

From c98ae3dbd7c537b8f5cef87f458166800e59f75e Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 12:56:15 +0200
Subject: [PATCH 083/286] test(e2e): a duplicate inputId over the harness
 protocol runs once

The harness protocol route gets a durable host (a memory log and run leases) behind the x-harness-durable header. Two control prompts with one inputId get the same receipt and one answer in the transcript. The same id with another message is a conflict.
---
 testing/e2e/fixtures/harness/basic.json       |  8 ++++
 .../e2e/src/routes/api.harness-protocol.$.ts  | 11 ++++-
 testing/e2e/tests/harness-protocol.spec.ts    | 42 +++++++++++++++++++
 3 files changed, 59 insertions(+), 2 deletions(-)

diff --git a/testing/e2e/fixtures/harness/basic.json b/testing/e2e/fixtures/harness/basic.json
index f717368b80..bf217db275 100644
--- a/testing/e2e/fixtures/harness/basic.json
+++ b/testing/e2e/fixtures/harness/basic.json
@@ -40,6 +40,14 @@
         "content": "Hello over the harness protocol."
       }
     },
+    {
+      "match": {
+        "userMessage": "[harness-durable] run once"
+      },
+      "response": {
+        "content": "Stored once."
+      }
+    },
     {
       "match": {
         "userMessage": "[harness-limits] work twice",
diff --git a/testing/e2e/src/routes/api.harness-protocol.$.ts b/testing/e2e/src/routes/api.harness-protocol.$.ts
index 214f6bb3db..660bb755ae 100644
--- a/testing/e2e/src/routes/api.harness-protocol.$.ts
+++ b/testing/e2e/src/routes/api.harness-protocol.$.ts
@@ -9,7 +9,7 @@ import {
   definePlugin,
 } from '@tanstack/ai-harness'
 import { todos } from '@tanstack/ai-harness/plugins'
-import { memoryPersistence } from '@tanstack/ai-persistence'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { z } from 'zod'
 import { createImageAdapter } from '@/lib/media-providers'
 import { createTextAdapter } from '@/lib/providers'
@@ -24,6 +24,13 @@ import { createTextAdapter } from '@/lib/providers'
 // 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 },
+  },
+})
 
 function handlerFor(request: Request) {
   const testId = request.headers.get('x-test-id') ?? 'default'
@@ -75,7 +82,7 @@ function handlerFor(request: Request) {
     ],
   })
   return createHarnessHandler({
-    host,
+    host: request.headers.get('x-harness-durable') === '1' ? durableHost : host,
     harness,
     authorize: (req) =>
       req.headers.get('authorization') === 'Bearer e2e-token'
diff --git a/testing/e2e/tests/harness-protocol.spec.ts b/testing/e2e/tests/harness-protocol.spec.ts
index 7078085e49..0bfdc3d9e9 100644
--- a/testing/e2e/tests/harness-protocol.spec.ts
+++ b/testing/e2e/tests/harness-protocol.spec.ts
@@ -90,6 +90,48 @@ test.describe('harness protocol', () => {
     expect(command.operationId).toMatch(/^op-command-/)
   })
 
+  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('takes a control input and returns a receipt', async ({
     request,
     testId,

From 58d4c2b953174d8997035517e30fe37f0e1f146e Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 13:01:27 +0200
Subject: [PATCH 084/286] feat(ai-harness): durable tool steps, kept tool
 results, and staged records in the batch commit

On a durable host each durableTool call gets steps in the log: after a crash, finished steps return their stored values and only the rest run. Each finished tool result is appended as it ends, and the crash repair walks the batch in order: a finished call keeps its result, a pending replay 'never' call gets the error note, and the rest run again. Records that a tool stages with append land with the commit when the tool phase completes, so a cut batch leaves none.

A writer that already wrote and then sees another writer's records stops, as after a conflict, so a stopped host that follows the log cannot keep writing.
---
 packages/ai-harness/src/log.ts                |  15 +-
 packages/ai-harness/src/resume.ts             |  53 ++--
 packages/ai-harness/src/session.ts            |  55 +++-
 .../ai-harness/tests/durable-tools.test.ts    | 268 ++++++++++++++++++
 packages/ai-harness/tests/log.test.ts         |  22 ++
 packages/ai-harness/tests/resume.test.ts      |  56 ++++
 6 files changed, 447 insertions(+), 22 deletions(-)
 create mode 100644 packages/ai-harness/tests/durable-tools.test.ts

diff --git a/packages/ai-harness/src/log.ts b/packages/ai-harness/src/log.ts
index 6e5f13eb76..832704e1eb 100644
--- a/packages/ai-harness/src/log.ts
+++ b/packages/ai-harness/src/log.ts
@@ -401,6 +401,7 @@ export class LogWriter implements EventFeed {
   private readonly waiters = new Set<() => void>()
   private closed = false
   private writing = false
+  private hasWritten = false
   private writesSinceCheckpoint = 0
   private readonly unsubscribe: () => void
 
@@ -541,6 +542,7 @@ export class LogWriter implements EventFeed {
       this.writing = false
     }
     batch.forEach((record, index) => this.apply({ seq: seq + index, record }))
+    this.hasWritten = true
     this.writesSinceCheckpoint += 1
     if (this.writesSinceCheckpoint >= CHECKPOINT_EVERY) {
       this.writesSinceCheckpoint = 0
@@ -592,11 +594,22 @@ export class LogWriter implements EventFeed {
     }
   }
 
-  /** Fold records that another writer appended. */
+  /**
+   * Fold records that another writer appended. A host that only reads
+   * follows the log. A writer that already wrote has lost the thread to
+   * another host, so it stops, as after a conflict.
+   */
   private async catchUp() {
+    if (this.failure !== undefined) return
     const entries = await this.store.read(this.threadId, {
       after: this.state.seq,
     })
+    const [first] = entries
+    if (first && this.hasWritten) {
+      this.failure = new LogConflictError(this.threadId, first.seq)
+      this.onFailure(this.failure)
+      return
+    }
     for (const entry of entries) this.apply(entry)
     if (entries.length > 0) this.wake()
   }
diff --git a/packages/ai-harness/src/resume.ts b/packages/ai-harness/src/resume.ts
index 941efa9cd7..ad55779dff 100644
--- a/packages/ai-harness/src/resume.ts
+++ b/packages/ai-harness/src/resume.ts
@@ -153,14 +153,15 @@ export async function findCrashedRuns(
 }
 
 /**
- * Prepare the transcript of a crashed run for a new run:
+ * Prepare the transcript of a crashed run for a new run. It walks the tool
+ * calls of the batch (the last assistant message with tool calls) in order:
  *
  * - A call in `finished` gets its finished tool message. It does not run
  *   again.
- * - Another call with `replay: 'never'` gets {@link INTERRUPTED_TOOL_RESULT}
- *   as a tool error.
- * - Another call with `replay: 'safe'` stays without a result, so the engine
- *   runs it again.
+ * - A pending call with `replay: 'never'` gets
+ *   {@link INTERRUPTED_TOOL_RESULT} as a tool error.
+ * - A pending call with `replay: 'safe'`, or a call that never started, stays
+ *   without a result, so the engine runs it.
  */
 export async function repairTranscript(options: {
   messages: MessageStore
@@ -170,27 +171,39 @@ export async function repairTranscript(options: {
 }): Promise<void> {
   const { messages, crashed, finished } = options
   const pending = crashed.checkpoint?.pendingTools ?? []
-  if (pending.length === 0) return
+  if (pending.length === 0 && (finished?.size ?? 0) === 0) return
   const history = await messages.loadThread(crashed.threadId)
   const answered = new Set(
     history.flatMap((message) =>
       message.role === 'tool' && message.toolCallId ? [message.toolCallId] : [],
     ),
   )
-  const unanswered = pending.filter((tool) => !answered.has(tool.toolCallId))
-  const added = unanswered.flatMap((tool): Array<ModelMessage> => {
-    const result = finished?.get(tool.toolCallId)
-    if (result) return [result]
-    if (tool.replay === 'safe') return []
-    return [
-      {
-        role: 'tool',
-        toolCallId: tool.toolCallId,
-        content: JSON.stringify(INTERRUPTED_TOOL_RESULT),
-        error: INTERRUPTED_TOOL_RESULT.note,
-      },
-    ]
-  })
+  const batch = history.findLast(
+    (message) => message.role === 'assistant' && message.toolCalls?.length,
+  )
+  const pendingById = new Map(pending.map((tool) => [tool.toolCallId, tool]))
+  const callIds = [
+    ...new Set([
+      ...(batch?.toolCalls ?? []).map((call) => call.id),
+      ...pending.map((tool) => tool.toolCallId),
+    ]),
+  ]
+  const added = callIds
+    .filter((toolCallId) => !answered.has(toolCallId))
+    .flatMap((toolCallId): Array<ModelMessage> => {
+      const result = finished?.get(toolCallId)
+      if (result) return [result]
+      const tool = pendingById.get(toolCallId)
+      if (!tool || tool.replay === 'safe') return []
+      return [
+        {
+          role: 'tool',
+          toolCallId,
+          content: JSON.stringify(INTERRUPTED_TOOL_RESULT),
+          error: INTERRUPTED_TOOL_RESULT.note,
+        },
+      ]
+    })
   if (added.length > 0) {
     await messages.saveThread(crashed.threadId, [...history, ...added])
   }
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index f8f7925987..c9473d5e86 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -16,11 +16,13 @@ import { LogConflictError, withPersistence } from '@tanstack/ai-persistence'
 import { AgentRegistry } from './agents'
 import { SessionFeed } from './feed'
 import { isRecord } from './utils'
+import { bindDurable, createToolStep } from './durable-tool'
 import {
   LogWriter,
   engineMessageStore,
   loadLogState,
   sessionMessageStore,
+  stepKey,
 } from './log'
 import { createMediaStore, mediaCapture, mediaMiddleware } from './media'
 import { mediaIdOf, mediaOfMessage } from './media-ref'
@@ -569,14 +571,56 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         ...(stores.metadata ? { metadata: stores.metadata } : {}),
       },
     }
+    const { writer } = this
     this.checkpoint = checkpointMiddleware({
       ...(stores.runs ? { runs: stores.runs } : {}),
       messages: engineMessages,
       hostId: this.hostId,
       ...(this.lease ? { lease: this.lease } : {}),
+      // A durable host keeps each finished tool result, so a crash later in
+      // the batch does not lose it.
+      ...(writer
+        ? {
+            onToolResult: ({ toolCallId, message }) =>
+              writer.append([
+                { type: 'harness.tool.result', toolCallId, message },
+              ]),
+          }
+        : {}),
     })
   }
 
+  /**
+   * The `step` and `append` a durable tool call gets. A step value is in the
+   * log before `step.do` resolves. Staged records land with the next
+   * transcript commit, when the tool phase completes, so a batch that a
+   * crash cuts leaves none of them.
+   */
+  private durableBinding(writer: LogWriter, toolCallId: string) {
+    const step = createToolStep({
+      recorded: (name) => {
+        const key = stepKey(toolCallId, name)
+        return writer.state.steps.has(key)
+          ? { found: true, value: writer.state.steps.get(key) }
+          : { found: false }
+      },
+      record: (name, value) =>
+        writer.append([{ type: 'harness.tool.step', toolCallId, name, value }]),
+    })
+    const append = (records: ReadonlyArray<LogRecord>) => {
+      const reserved = records.find((record) =>
+        record.type.startsWith('harness.'),
+      )
+      if (reserved) {
+        throw new Error(
+          `The record type ${JSON.stringify(reserved.type)} is reserved for the harness.`,
+        )
+      }
+      writer.stage(records)
+    }
+    return { step, append }
+  }
+
   /**
    * The log refused a write: another host wrote to this thread, or the store
    * failed. The state of this session is not known any more, so it stops.
@@ -1695,11 +1739,20 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         operation,
       )
       // Before the chat() options below: prompts may describe these tools.
-      const tools = await this.prepareTools(
+      const prepared = await this.prepareTools(
         [...(session?.preparers ?? []), ...(runPlugins?.preparers ?? [])],
         [...staticTools, ...discovered],
         operation,
       )
+      // A durable host gives each durableTool call its steps in the log.
+      const { writer } = this
+      const tools = writer
+        ? prepared.map((tool) =>
+            bindDurable(tool, (toolCallId) =>
+              this.durableBinding(writer, toolCallId),
+            ),
+          )
+        : prepared
       // A keyed adapter is built for this turn with the user's key. A
       // missing key publishes `auth_required` and fails the turn.
       const adapter: AnyTextAdapter = await this.keys.adapter(
diff --git a/packages/ai-harness/tests/durable-tools.test.ts b/packages/ai-harness/tests/durable-tools.test.ts
new file mode 100644
index 0000000000..a307fae198
--- /dev/null
+++ b/packages/ai-harness/tests/durable-tools.test.ts
@@ -0,0 +1,268 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { EventType, toolDefinition } from '@tanstack/ai'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness, durableTool } from '../src'
+import { INTERRUPTED_TOOL_RESULT } from '../src/resume'
+import { gate, mockAdapter, text, toolCall } from './helpers'
+import type { AnyTool, StreamChunk } from '@tanstack/ai'
+import type { Reply } from './helpers'
+
+const THREAD = 't1'
+
+function durablePersistence() {
+  const { runs, metadata } = memoryPersistence().stores
+  return { stores: { log: memoryLogStore(), runs, metadata } }
+}
+
+type Durable = ReturnType<typeof durablePersistence>
+
+async function openDurable(
+  persistence: Durable,
+  replies: Array<Reply>,
+  tools: Array<AnyTool>,
+) {
+  const { adapter, calls } = mockAdapter(replies)
+  const host = createHarnessHost({ persistence })
+  const session = await host.open(
+    defineHarness({ name: 'test/durable-tools', adapter, tools }),
+    { threadId: THREAD },
+  )
+  return { host, session, calls }
+}
+
+/** The records of the log, of one type. */
+async function recordsOf(persistence: Durable, type: string) {
+  return (await persistence.stores.log.read(THREAD))
+    .map((entry) => entry.record)
+    .filter((record) => record.type === type)
+}
+
+/** Wait like a host that stopped, until the call is aborted at close. */
+const untilAborted = (signal: AbortSignal | undefined) =>
+  new Promise<never>((_resolve, reject) => {
+    signal?.addEventListener('abort', () => reject(new Error('stopped')), {
+      once: true,
+    })
+  })
+
+/** Let another host take over: the run lease of `runId` expires. */
+const expireLease = (persistence: Durable, runId: string) =>
+  persistence.stores.runs.update(runId, { leaseExpiresAt: Date.now() - 1 })
+
+/** One model call that calls every tool in `calls`. */
+function toolCalls(
+  calls: Array<{ id: string; name: string }>,
+): Array<StreamChunk> {
+  const now = Date.now()
+  return [
+    { type: EventType.RUN_STARTED, runId: 'r', threadId: 't', timestamp: now },
+    ...calls.flatMap(
+      ({ id, name }): Array<StreamChunk> => [
+        {
+          type: EventType.TOOL_CALL_START,
+          toolCallId: id,
+          toolCallName: name,
+          timestamp: now,
+        },
+        {
+          type: EventType.TOOL_CALL_ARGS,
+          toolCallId: id,
+          delta: '{}',
+          timestamp: now,
+        },
+        { type: EventType.TOOL_CALL_END, toolCallId: id, timestamp: now },
+      ],
+    ),
+    {
+      type: EventType.RUN_FINISHED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: now,
+      metadata: { tanstack: { finishReason: 'tool_calls' } },
+    },
+  ]
+}
+
+describe('durable tools across a crash', () => {
+  it('replays the finished steps and runs only the rest', async () => {
+    const persistence = durablePersistence()
+    const reserve = vi.fn(async () => 'r-1')
+    const charge = vi.fn(async () => 'c-1')
+    const ship = vi.fn(async () => 's-1')
+    const twoDone = gate()
+    const hostStops = gate()
+    let isFirstRun = true
+    const pay = durableTool(
+      toolDefinition({
+        name: 'pay',
+        description: 'Reserve, charge, and ship an order',
+        inputSchema: z.object({ orderId: z.string() }),
+      }),
+      async ({ orderId }, { step }) => {
+        const reservation = await step.do('reserve', reserve)
+        const payment = await step.do('charge', charge)
+        if (isFirstRun) {
+          isFirstRun = false
+          twoDone.open()
+          // The first host stops here.
+          await hostStops.opened
+        }
+        const shipment = await step.do('ship', ship)
+        return `${orderId}:${reservation}:${payment}:${shipment}`
+      },
+    )
+    const first = await openDurable(
+      persistence,
+      [() => toolCall('pay', { orderId: 'o1' }, 'call-pay')],
+      [pay],
+    )
+    const turn = first.session.prompt('pay order o1', { inputId: 'pay-1' })
+    await twoDone.opened
+    await vi.waitFor(async () =>
+      expect(
+        (await recordsOf(persistence, 'harness.tool.step')).map(
+          (record) => record.name,
+        ),
+      ).toEqual(['reserve', 'charge']),
+    )
+    await expireLease(persistence, turn.id)
+
+    const next = await openDurable(persistence, [() => text('paid')], [pay])
+
+    expect(await next.session.settled('pay-1')).toMatchObject({
+      outcome: 'completed',
+    })
+    expect(reserve).toHaveBeenCalledTimes(1)
+    expect(charge).toHaveBeenCalledTimes(1)
+    expect(ship).toHaveBeenCalledTimes(1)
+    const result = (await next.session.transcript()).find(
+      (message) => message.role === 'tool' && message.toolCallId === 'call-pay',
+    )
+    expect(result?.content).toBe('o1:r-1:c-1:s-1')
+
+    hostStops.open()
+    await Promise.resolve(turn).catch(() => {})
+    await first.host.close()
+    await next.host.close()
+  })
+
+  it('keeps finished results of a cut batch, and gives the rest an error', async () => {
+    const persistence = durablePersistence()
+    const charge = vi.fn(async () => 'charged 100')
+    const mailStarted = gate()
+    const mail = vi.fn(
+      async (_args: unknown, context?: { abortSignal?: AbortSignal }) => {
+        mailStarted.open()
+        // The first host stops while the mail runs.
+        return untilAborted(context?.abortSignal)
+      },
+    )
+    const tools = [
+      toolDefinition({ name: 'charge', description: 'Charge a card' }).server(
+        charge,
+      ),
+      toolDefinition({ name: 'mail', description: 'Send a mail' }).server(mail),
+    ]
+    const first = await openDurable(
+      persistence,
+      [
+        () =>
+          toolCalls([
+            { id: 'call-charge', name: 'charge' },
+            { id: 'call-mail', name: 'mail' },
+          ]),
+      ],
+      tools,
+    )
+    const turn = first.session.prompt('charge and mail', { inputId: 'batch-1' })
+    await mailStarted.opened
+    await vi.waitFor(async () =>
+      expect(await recordsOf(persistence, 'harness.tool.result')).toHaveLength(
+        1,
+      ),
+    )
+    await expireLease(persistence, turn.id)
+
+    const next = await openDurable(persistence, [() => text('done')], tools)
+    await next.session.settled('batch-1')
+
+    const results = (await next.session.transcript()).filter(
+      (message) => message.role === 'tool',
+    )
+    expect(results).toEqual([
+      { role: 'tool', toolCallId: 'call-charge', content: 'charged 100' },
+      {
+        role: 'tool',
+        toolCallId: 'call-mail',
+        content: JSON.stringify(INTERRUPTED_TOOL_RESULT),
+        error: INTERRUPTED_TOOL_RESULT.note,
+      },
+    ])
+    expect(charge).toHaveBeenCalledTimes(1)
+    expect(mail).toHaveBeenCalledTimes(1)
+    await first.host.close().catch(() => {})
+    await next.host.close()
+  })
+})
+
+describe('host records of a tool batch', () => {
+  const noteDefinition = toolDefinition({
+    name: 'note',
+    description: 'Write a note to the state',
+  })
+
+  it('lands them when the tool phase completes', async () => {
+    const persistence = durablePersistence()
+    const note = durableTool(noteDefinition, async (_args, { append }) => {
+      append([{ type: 'app.state_write', name: 'x', value: 1 }])
+      return 'noted'
+    })
+    const { host, session } = await openDurable(
+      persistence,
+      [() => toolCall('note', {}, 'call-note'), () => text('done')],
+      [note],
+    )
+
+    await session.prompt('note it')
+
+    expect(await recordsOf(persistence, 'app.state_write')).toEqual([
+      { type: 'app.state_write', name: 'x', value: 1 },
+    ])
+    await host.close()
+  })
+
+  it('never lands them when a crash cuts the batch', async () => {
+    const persistence = durablePersistence()
+    const appended = gate()
+    const note = durableTool(
+      noteDefinition,
+      async (_args, { append, abortSignal }) => {
+        append([{ type: 'app.state_write', name: 'x', value: 1 }])
+        appended.open()
+        // The host stops before the batch completes.
+        return untilAborted(abortSignal)
+      },
+    )
+    const first = await openDurable(
+      persistence,
+      [() => toolCall('note', {}, 'call-note')],
+      [note],
+    )
+    const turn = first.session.prompt('note it', { inputId: 'note-1' })
+    await appended.opened
+    await expireLease(persistence, turn.id)
+
+    // The durable tool runs again on the next host, and stops again there.
+    const next = await openDurable(persistence, [], [note])
+    await vi.waitFor(async () =>
+      expect(
+        await recordsOf(persistence, 'harness.input.applied'),
+      ).toHaveLength(2),
+    )
+
+    expect(await recordsOf(persistence, 'app.state_write')).toEqual([])
+    await first.host.close().catch(() => {})
+    await next.host.close().catch(() => {})
+  })
+})
diff --git a/packages/ai-harness/tests/log.test.ts b/packages/ai-harness/tests/log.test.ts
index 40a5696778..7900248625 100644
--- a/packages/ai-harness/tests/log.test.ts
+++ b/packages/ai-harness/tests/log.test.ts
@@ -320,6 +320,28 @@ describe('events and batches', () => {
 })
 
 describe('write failures', () => {
+  it('stops a writer that sees another writer after it wrote', async () => {
+    const store = memoryLogStore()
+    const failures: Array<unknown> = []
+    const first = newWriter(store, { onFailure: (e) => failures.push(e) })
+    await first.append([{ type: 'app.mine' }])
+    const state = await loadLogState({ store, threadId: THREAD })
+    const next = newWriter(store, { state })
+
+    // The newer host writes. The first host is notified and stops.
+    await next.append([{ type: 'app.newer' }])
+
+    await expect.poll(() => failures.length).toBe(1)
+    expect(failures[0]).toBeInstanceOf(LogConflictError)
+    await expect(first.append([{ type: 'app.zombie' }])).rejects.toBeInstanceOf(
+      LogConflictError,
+    )
+    expect((await records(store)).map((record) => record.type)).toEqual([
+      'app.mine',
+      'app.newer',
+    ])
+  })
+
   it('calls onFailure on a conflict and rejects every later write', async () => {
     const store = memoryLogStore()
     const failures: Array<unknown> = []
diff --git a/packages/ai-harness/tests/resume.test.ts b/packages/ai-harness/tests/resume.test.ts
index 2772f9818d..f4d6d893e7 100644
--- a/packages/ai-harness/tests/resume.test.ts
+++ b/packages/ai-harness/tests/resume.test.ts
@@ -256,6 +256,62 @@ describe('crash resume', () => {
     ])
   })
 
+  it('keeps a finished result that is no longer pending, in batch order', async () => {
+    const { stores } = memoryPersistence()
+    await stores.messages.saveThread('t1', [
+      { id: 'u1', role: 'user', content: 'charge, then mail' },
+      {
+        id: 'a1',
+        role: 'assistant',
+        content: '',
+        toolCalls: [
+          {
+            id: 'call-charge',
+            type: 'function',
+            function: { name: 'charge', arguments: '{}' },
+          },
+          {
+            id: 'call-mail',
+            type: 'function',
+            function: { name: 'mail', arguments: '{}' },
+          },
+        ],
+      },
+    ])
+
+    await repairTranscript({
+      messages: stores.messages,
+      crashed: {
+        runId: 'crashed',
+        threadId: 't1',
+        status: 'running',
+        startedAt: 1,
+        // The charge ended, so only the mail is still pending.
+        checkpoint: {
+          at: 1,
+          pendingTools: [
+            { toolCallId: 'call-mail', name: 'mail', replay: 'never' },
+          ],
+        },
+      },
+      finished: new Map([
+        [
+          'call-charge',
+          { role: 'tool', toolCallId: 'call-charge', content: 'charged' },
+        ],
+      ]),
+    })
+
+    const tools = (await stores.messages.loadThread('t1')).filter(
+      (message) => message.role === 'tool',
+    )
+    expect(tools.map((message) => message.toolCallId)).toEqual([
+      'call-charge',
+      'call-mail',
+    ])
+    expect(tools[0]?.content).toBe('charged')
+  })
+
   it('leaves a run alone while its lease is still valid', async () => {
     const persistence = memoryPersistence()
     await persistence.stores.runs.createOrResume({

From 740e3aea031f57d49cf17855bdd73a8b3c64159d Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 13:06:18 +0200
Subject: [PATCH 085/286] docs(harness): durable sessions, inputs, durable
 tools, and the session log

durable-sessions covers the session log, attempt and time limits, the recovery order, and one host per thread. New pages: inputs (inputId, receipts, settled, and joins), durable-tools (durableTool steps and staged records), and session-log (host records, the project fold, logMessageStore, and coalesceMs). createHarnessClient prompt, steer, and followUp now take inputId, so the client side of the inputs page works.
---
 .changeset/harness-durable-log.md        |   2 +-
 docs/config.json                         |  22 ++++-
 docs/harness/durable-sessions.md         |  83 +++++++++++-----
 docs/harness/durable-tools.md            |  96 +++++++++++++++++++
 docs/harness/inputs.md                   | 114 ++++++++++++++++++++++
 docs/harness/session-log.md              | 116 +++++++++++++++++++++++
 packages/ai-harness/src/client.ts        |  31 +++++-
 packages/ai-harness/tests/client.test.ts |  27 ++++++
 8 files changed, 459 insertions(+), 32 deletions(-)
 create mode 100644 docs/harness/durable-tools.md
 create mode 100644 docs/harness/inputs.md
 create mode 100644 docs/harness/session-log.md

diff --git a/.changeset/harness-durable-log.md b/.changeset/harness-durable-log.md
index c680ddd07a..1646e8b7ef 100644
--- a/.changeset/harness-durable-log.md
+++ b/.changeset/harness-durable-log.md
@@ -9,7 +9,7 @@ Add a durable session log. A harness session can now keep its events, transcript
 
 `@tanstack/ai-harness` turns on durable mode when the host gets `stores.log` and `stores.runs`:
 
-- `prompt`, `steer`, `followUp`, and `resolve` take an optional `inputId`. The same id with the same payload does not run again. `Operation.receipt` resolves when the input is stored, and `session.settled(inputId)` gives how an input ended, also after a restart.
+- `prompt`, `steer`, `followUp`, and `resolve` take an optional `inputId`, and so do `prompt`, `steer`, and `followUp` of `createHarnessClient`. The same id with the same payload does not run again. `Operation.receipt` resolves when the input is stored, and `session.settled(inputId)` gives how an input ended, also after a restart.
 - `defineHarness({ durability: { maxAttempts, timeoutMs } })` limits each input. The default is 10 attempts and no timeout.
 - `durableTool(definition, execute)` gives a tool `step.do(name, fn)`. After a crash, a finished step returns its stored value and does not run again. The tool's `append(records)` adds host records to the same append as the tool batch.
 - `session.append(records)` adds host records to the log. The host option `project: { record, version }` folds host records into the model context. `logMessageStore` reads the transcript of a log outside a session.
diff --git a/docs/config.json b/docs/config.json
index e51bc8931b..92a006c69c 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -658,7 +658,7 @@
           "label": "Build Your Own Adapter",
           "to": "persistence/build-your-own-adapter",
           "addedAt": "2026-08-04",
-          "updatedAt": "2026-09-25"
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "Migrations",
@@ -706,7 +706,7 @@
           "label": "Store Reference",
           "to": "persistence/store-reference",
           "addedAt": "2026-08-04",
-          "updatedAt": "2026-09-24"
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "How Persistence Works",
@@ -894,7 +894,23 @@
         {
           "label": "Durable sessions",
           "to": "harness/durable-sessions",
-          "addedAt": "2026-09-26"
+          "addedAt": "2026-09-26",
+          "updatedAt": "2026-09-30"
+        },
+        {
+          "label": "Send inputs safely",
+          "to": "harness/inputs",
+          "addedAt": "2026-09-30"
+        },
+        {
+          "label": "Run side effects once",
+          "to": "harness/durable-tools",
+          "addedAt": "2026-09-30"
+        },
+        {
+          "label": "Build on the session log",
+          "to": "harness/session-log",
+          "addedAt": "2026-09-30"
         },
         {
           "label": "Write a plugin",
diff --git a/docs/harness/durable-sessions.md b/docs/harness/durable-sessions.md
index a97a22270b..6c925d6a17 100644
--- a/docs/harness/durable-sessions.md
+++ b/docs/harness/durable-sessions.md
@@ -2,51 +2,74 @@
 title: Durable sessions
 id: harness-durable-sessions
 order: 4
-description: "Keep a harness turn alive through a crash or a deploy. The next host continues it from the last checkpoint."
+description: "Keep a harness turn alive through a crash or a deploy. The next host continues it from the session log, and a turn that keeps failing stops after a limit."
 keywords:
   - tanstack ai
   - harness
   - durability
   - resume
-  - checkpoint
+  - session log
+  - retries
 ---
 
-A long agent turn can outlive the process that started it: a deploy restarts the server, or the machine crashes in the middle of a tool call. With durable stores, the next host that opens the session continues the turn from its last checkpoint.
+A long agent turn can outlive the process that started it: a deploy restarts the server, or the machine crashes in the middle of a tool call. Give the host a session log, and the next host that opens the thread continues the turn. A turn that crashes the host every time stops after a limit.
 
-## Give the host durable stores
+## Give the host a session log
 
-Use your own stores built with `defineAIPersistence`. Resume needs these:
+A durable host takes two stores:
 
-- `messages`: the transcript.
-- `runs`: the run records, with leases and checkpoints. Implement `listByThread`.
-- `inbox`: messages that were accepted but did not run yet.
+- `log`: one append-only log per thread. It keeps the events, the transcript, the inputs, and the tool steps.
+- `runs`: run records with leases. A lease tells the next host that the last one stopped.
 
 ```ts group=harness-durable
 import { createHarnessHost } from '@tanstack/ai-harness'
-import { memoryPersistence } from '@tanstack/ai-persistence'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 
 // Swap in your own stores. Memory stores do not survive a restart.
-const host = createHarnessHost({ persistence: memoryPersistence() })
+const { runs, metadata } = memoryPersistence().stores
+
+const host = createHarnessHost({
+  persistence: { stores: { log: memoryLogStore(), runs, metadata } },
+})
+```
+
+`metadata` is optional. With it, the host keeps a fold checkpoint of each log, so a long thread opens faster. To store the log in your database, implement the [`LogStore` contract](../persistence/store-reference#logstore).
+
+## Limit attempts and time
+
+Each run of an input is one attempt: the first run, and each run after a crash. Set the limits on the harness:
+
+```ts group=harness-durable
+import { defineHarness } from '@tanstack/ai-harness'
+import { openaiText } from '@tanstack/ai-openai'
+
+const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-5.6'),
+  durability: { maxAttempts: 5, timeoutMs: 30 * 60_000 },
+})
 ```
 
-## What the session saves while a turn runs
+- `maxAttempts`: the total attempts for one input. The default is 10.
+- `timeoutMs`: the time from the first run until the input fails. A retry does not reset it. The default is no timeout, because some agent turns run for hours.
 
-- A lease on the run record. The host renews it every 10 seconds. It expires after 30 seconds.
-- The transcript before and after each tool phase.
-- Each tool call that started and has no result yet.
+A turn that passes its time limit is stopped. It ends with the error code `timeout`.
 
 ## What happens after a crash
 
-When a host opens the session and finds a turn whose lease expired, it continues that turn in a new run:
+When a host opens the thread and finds a turn whose lease expired, it checks these, in order:
 
-1. The old run is marked failed.
-2. Tool calls without a result get handled by their `replay` setting.
-3. A new chat run starts from the saved transcript.
-4. Clients see a `harness.operation.resumed` event, then the new events.
+1. An abort was asked for the turn: the input ends `aborted`. The model is not called.
+2. No attempt is left: the input ends `failed`, with the error code `attempts_exhausted`.
+3. The time limit passed: the input ends `failed`, with the error code `timeout`.
+4. The log already has the final answer: the input ends `completed`. The model is not called again.
+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. See [Send inputs safely](./inputs) to read how an input ended.
 
 ## Mark tools that are safe to run again
 
-A crash can stop a run after a tool started but before its result was saved. Tell the harness what to do with `replay`:
+A crash can stop a run after a tool started but before its result was stored. Tell the harness what to do with `replay`:
 
 ```ts group=harness-durable
 import { toolDefinition } from '@tanstack/ai'
@@ -61,11 +84,25 @@ const lookup = toolDefinition({
 ```
 
 - `replay: 'safe'`: the tool runs again. Use it for reads and other idempotent calls.
-- `replay: 'never'` (default): the model gets a note that the tool may or may not have run, and checks before it tries again.
+- `replay: 'never'` (default): the model gets a tool error. Nobody knows if the tool ran, so the model checks before it tries again.
+
+A tool that finished before the crash keeps its result. It does not run again. For a tool with side effects, such as a payment, see [Run side effects once](./durable-tools).
+
+## One host drives a thread
+
+Only one host writes to the log of a thread at a time. A host that only reads (for example `GET /events` on a second server) follows the log and writes nothing. When a second host writes to the thread, the first host's session stops, and its running turn fails with a clear error. Open the thread again to continue on that host.
 
-A model response that was cut in the middle runs again after resume. The provider can bill that call twice.
+The lease decides when a stopped host counts as gone. Change its timing on the host:
+
+```ts group=harness-durable
+const leasedHost = createHarnessHost({
+  persistence: { stores: { log: memoryLogStore(), runs } },
+  lease: { ttlMs: 60_000, renewMs: 20_000 },
+})
+```
 
 ## What you have now
 
-- Turns that continue after a crash or a deploy.
+- Turns that continue after a crash or a deploy, from the session log.
+- A turn that stops after `maxAttempts` or `timeoutMs`, with a clear error code.
 - Tools that either run again safely or tell the model to check first.
diff --git a/docs/harness/durable-tools.md b/docs/harness/durable-tools.md
new file mode 100644
index 0000000000..cc0a7da867
--- /dev/null
+++ b/docs/harness/durable-tools.md
@@ -0,0 +1,96 @@
+---
+title: Run side effects once
+id: harness-durable-tools
+order: 4
+description: "Put each side effect of a tool in a durable step. After a crash, the harness runs the tool again, and the finished steps return their stored values instead of running twice."
+keywords:
+  - tanstack ai
+  - harness
+  - durableTool
+  - steps
+  - idempotency
+  - side effects
+---
+
+A crash can stop a tool between two side effects: the card is charged, but the invoice is not sent. When the harness runs the tool again, the card is charged a second time. Put each side effect in a durable step. After a crash, the finished steps return their stored values, and only the rest run.
+
+## Put each side effect in a step
+
+Make the tool with `durableTool`. Its `execute` gets `step` next to the normal tool context:
+
+```ts group=harness-durable-tools
+import { toolDefinition } from '@tanstack/ai'
+import { durableTool } from '@tanstack/ai-harness'
+import { z } from 'zod'
+
+declare const billing: {
+  charge: (orderId: string) => Promise<{ id: string }>
+  sendInvoice: (chargeId: string) => Promise<void>
+}
+
+export const checkout = durableTool(
+  toolDefinition({
+    name: 'checkout',
+    description: 'Charge an order and send the invoice',
+    inputSchema: z.object({ orderId: z.string() }),
+  }),
+  async ({ orderId }, { step }) => {
+    const payment = await step.do(`charge:${orderId}`, () =>
+      billing.charge(orderId),
+    )
+    await step.do(`invoice:${payment.id}`, () =>
+      billing.sendInvoice(payment.id),
+    )
+    return { chargeId: payment.id }
+  },
+)
+```
+
+Add it to `tools` in `defineHarness`, as any other tool. On a [durable host](./durable-sessions), each finished step is in the session log before `step.do` resolves.
+
+## Rules for steps
+
+- Give each step a name that is the same on every run, for example `charge:${orderId}`.
+- The same name twice in one tool call throws.
+- A step value must be JSON. Keep it small: store big data somewhere else and return its id.
+- A step is stored once, but it can run more than once: a crash after `fn` ends and before the value is stored runs `fn` again. Make that case safe, for example with an idempotency key.
+
+`durableTool` sets `replay: 'safe'`, so the harness runs the tool again after a crash.
+
+## Add records with the tool batch
+
+`append` adds your own records to the session log. They land when the tool phase completes, in the same append as the batch commit. If a crash cuts the batch, the records never happened.
+
+```ts group=harness-durable-tools
+export const remember = durableTool(
+  toolDefinition({
+    name: 'remember',
+    description: 'Remember a fact about the user',
+    inputSchema: z.object({ fact: z.string() }),
+  }),
+  async ({ fact }, { append }) => {
+    append([{ type: 'app.memory', fact }])
+    return 'Remembered.'
+  },
+)
+```
+
+A record type that starts with `harness.` is reserved and throws. [Build on the session log](./session-log) shows how to read your records back.
+
+## The other tools of a cut batch
+
+After a crash, the harness looks at each call of the batch:
+
+- A call that finished keeps its result. It does not run again.
+- A `durableTool` call, or another tool with `replay: 'safe'`, runs again.
+- Any other call gets a tool error: nobody knows if the tool ran, so the model checks before it tries again.
+
+## Outside a durable session
+
+The same tool works in plain `chat()` and on a host without a log. There, `step.do` runs `fn` each time, and `append` throws, because there is no log to hold the records.
+
+## What you have now
+
+- Side effects that do not repeat after a crash.
+- Your own records that land together with the tool batch, or not at all.
+- One tool definition for durable and plain runs.
diff --git a/docs/harness/inputs.md b/docs/harness/inputs.md
new file mode 100644
index 0000000000..c546591534
--- /dev/null
+++ b/docs/harness/inputs.md
@@ -0,0 +1,114 @@
+---
+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, and ask the session how an input ended, also after a restart."
+keywords:
+  - tanstack ai
+  - harness
+  - inputId
+  - idempotency
+  - settled
+  - steer
+---
+
+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-5.6'),
+})
+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.
+
+## 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.
+
+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)
+  }
+}
+```
+
+## 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.
+
+## 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.
diff --git a/docs/harness/session-log.md b/docs/harness/session-log.md
new file mode 100644
index 0000000000..cada620bf8
--- /dev/null
+++ b/docs/harness/session-log.md
@@ -0,0 +1,116 @@
+---
+title: Build on the session log
+id: harness-session-log
+order: 4
+description: "Keep your framework's own records (signals, state writes, compaction) in the harness session log, and fold them into the model context."
+keywords:
+  - tanstack ai
+  - harness
+  - session log
+  - LogStore
+  - projection
+  - compaction
+---
+
+Your framework keeps its own state next to the conversation: signals for the model, state writes, a compaction summary. Kept in a second store, it can drift from the transcript after a crash. Put these records in the harness session log. They share its atomic appends, its order, and its recovery.
+
+## Append your own records
+
+`session.append` adds records to the log of a [durable host](./durable-sessions), in one batch after the events that wait:
+
+```ts group=harness-session-log
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { openaiText } from '@tanstack/ai-openai'
+
+const log = memoryLogStore()
+const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-5.6'),
+})
+const host = createHarnessHost({
+  persistence: { stores: { log, runs: memoryPersistence().stores.runs } },
+})
+const session = await host.open(assistant, { threadId: 'thread-1' })
+
+await session.append([{ type: 'app.signal', text: 'The build failed.' }])
+```
+
+- A record is JSON with a `type`. Types that start with `harness.` belong to the harness, so `append` refuses them.
+- `append` resolves when the records are in the log.
+- In a tool, use `append` from [`durableTool`](./durable-tools), so the records land with the tool batch.
+
+## Fold records into the model context
+
+By default, the model does not see your records. Give the host a `project` function that folds a record into the messages. It gets one object, `{ messages, record }`, and returns the new list, or `undefined` for no change:
+
+```ts group=harness-session-log
+import type { ProjectOptions } from '@tanstack/ai-harness'
+
+const project: ProjectOptions = {
+  version: 'v1',
+  record: ({ messages, record }) => {
+    if (record.type === 'app.signal' && typeof record.text === 'string') {
+      return [...messages, { role: 'user', content: record.text }]
+    }
+    if (
+      record.type === 'app.compaction' &&
+      typeof record.summary === 'string' &&
+      typeof record.firstKept === 'number'
+    ) {
+      return [
+        { role: 'assistant', content: record.summary },
+        ...messages.slice(record.firstKept),
+      ]
+    }
+    return undefined
+  },
+}
+
+const projectedHost = createHarnessHost({
+  persistence: { stores: { log, runs: memoryPersistence().stores.runs } },
+  project,
+})
+```
+
+- `record` must be pure: the same log always folds to the same context, live and after a restart.
+- The model sees the change at its next model call. A message that arrives during a tool call comes after the tool result.
+- Change `version` when you change `record`. A fold checkpoint with another version is ignored.
+
+## Read the log
+
+The store is yours, so read your records back from it, for example to rebuild your state when a session opens:
+
+```ts group=harness-session-log
+const entries = await log.read('thread-1')
+const signals = entries.filter((entry) => entry.record.type === 'app.signal')
+console.log(signals.map((entry) => entry.seq))
+```
+
+A reader outside a session that needs a `MessageStore`, for example `reconstructChat`, uses `logMessageStore`. It folds the log with the same `project`:
+
+```ts group=harness-session-log
+import { logMessageStore } from '@tanstack/ai-harness'
+
+const messages = logMessageStore({ store: log, project })
+console.log(await messages.loadThread('thread-1'))
+```
+
+## Tune how text streams into the log
+
+A durable host merges streamed text for `coalesceMs` (default 100) before it appends it. A message start or end, a tool call, and your own records append at once.
+
+```ts group=harness-session-log
+const smoothHost = createHarnessHost({
+  persistence: { stores: { log, runs: memoryPersistence().stores.runs } },
+  coalesceMs: 250,
+})
+```
+
+A larger value writes less often, and clients get text in larger parts.
+
+## What you have now
+
+- Your records in the same durable log as the conversation.
+- A model context that folds them in, the same live and after a restart.
+- A transcript that any reader can fold from the log.
diff --git a/packages/ai-harness/src/client.ts b/packages/ai-harness/src/client.ts
index e1177f6f19..531344c6db 100644
--- a/packages/ai-harness/src/client.ts
+++ b/packages/ai-harness/src/client.ts
@@ -49,12 +49,22 @@ export type ClientAgentHandles<THarness> = {
 }
 
 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.
+   */
   prompt: (
     message: UserInput,
-    options?: { busy?: BusyPolicy },
+    options?: { busy?: BusyPolicy; inputId?: string },
+  ) => Promise<Receipt>
+  steer: (
+    message: UserInput,
+    options?: { inputId?: string },
+  ) => Promise<Receipt>
+  followUp: (
+    message: UserInput,
+    options?: { inputId?: string },
   ) => Promise<Receipt>
-  steer: (message: UserInput) => Promise<Receipt>
-  followUp: (message: UserInput) => Promise<Receipt>
   resolve: (resume: Array<RunAgentResumeItem>) => Promise<Receipt>
   cancel: (operationId?: string) => Promise<Receipt>
   agents: ClientAgentHandles<THarness>
@@ -295,9 +305,20 @@ export function createHarnessClient<THarness extends AnyHarness>(
         op: 'prompt',
         message,
         ...(promptOptions?.busy ? { busy: promptOptions.busy } : {}),
+        ...(promptOptions?.inputId ? { inputId: promptOptions.inputId } : {}),
+      }),
+    steer: (message, steerOptions) =>
+      send({
+        op: 'steer',
+        message,
+        ...(steerOptions?.inputId ? { inputId: steerOptions.inputId } : {}),
+      }),
+    followUp: (message, followOptions) =>
+      send({
+        op: 'followUp',
+        message,
+        ...(followOptions?.inputId ? { inputId: followOptions.inputId } : {}),
       }),
-    steer: (message) => send({ op: 'steer', message }),
-    followUp: (message) => send({ op: 'followUp', message }),
     resolve: (resume) => send({ op: 'resolve', resume }),
     cancel: (operationId) =>
       send({ op: 'cancel', ...(operationId ? { operationId } : {}) }),
diff --git a/packages/ai-harness/tests/client.test.ts b/packages/ai-harness/tests/client.test.ts
index 8f45fd9961..c004ec1943 100644
--- a/packages/ai-harness/tests/client.test.ts
+++ b/packages/ai-harness/tests/client.test.ts
@@ -64,6 +64,33 @@ describe('createHarnessClient', () => {
     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,
+      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('throws on a refused request instead of retrying', async () => {
     const { adapter } = mockAdapter([])
     const studio = defineHarness({ name: 'test/client-denied', adapter })

From dc92d101bad803d8bacc0d3dd47c9f0fd99063e4 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 13:52:48 +0200
Subject: [PATCH 086/286] feat(ai, ai-models): chat({ reasoning }) and the
 @tanstack/ai-models catalog

- @tanstack/ai: a `reasoning` option on chat() (a level, or { level,
  summary, budgetTokens }). Adapters declare each model's levels in
  '~types'.reasoning; with none, the option is a type error. The engine
  passes it to the adapter as options.reasoning, and middleware can change
  it in onConfig. supportedReasoningLevels and clampReasoningLevel follow
  pi's rules.
- @tanstack/ai-models (new): a runtime catalog of 38 providers and 1,932
  models from models.dev and the OpenRouter and Vercel lists, with prices,
  limits, reasoning maps, and wire quirks. One subpath per provider. Every
  model id of pi 0.87.1's covered providers resolves.
- scripts: fetch-models-dev.ts, generate-ai-models.ts, and
  sync-model-reasoning.ts, which writes src/model-reasoning.ts into each
  provider package. A drift test compares those with the catalog.

The adapters do not read `reasoning` yet. That comes next.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 package.json                                  |     4 +-
 packages/ai-anthropic/src/model-reasoning.ts  |   216 +
 packages/ai-bedrock/src/model-reasoning.ts    |   109 +
 packages/ai-byteplus/src/model-reasoning.ts   |   159 +
 .../ai-claude-code/src/model-reasoning.ts     |   109 +
 packages/ai-cloudflare/src/model-reasoning.ts |   209 +
 packages/ai-codex/src/model-reasoning.ts      |    84 +
 packages/ai-gemini/src/model-reasoning.ts     |   164 +
 packages/ai-grok-build/src/model-reasoning.ts |    25 +
 packages/ai-grok/src/model-reasoning.ts       |    82 +
 packages/ai-groq/src/model-reasoning.ts       |    68 +
 packages/ai-llmgateway/src/model-reasoning.ts |   233 +
 packages/ai-lovable/src/model-reasoning.ts    |   327 +
 packages/ai-mistral/src/model-reasoning.ts    |    53 +
 packages/ai-models/LICENSE                    |    21 +
 packages/ai-models/README.md                  |    38 +
 packages/ai-models/package.json               |   213 +
 packages/ai-models/scripts/catalog.ts         |   160 +
 packages/ai-models/scripts/known-ids.ts       |   250 +
 packages/ai-models/scripts/overrides.ts       |    44 +
 packages/ai-models/scripts/providers.ts       |   606 +
 packages/ai-models/scripts/rules.ts           |   200 +
 packages/ai-models/src/catalog.ts             |    84 +
 packages/ai-models/src/cost.ts                |    23 +
 packages/ai-models/src/index.ts               |    40 +
 .../ai-models/src/providers/amazon-bedrock.ts |  3385 +
 packages/ai-models/src/providers/ant-ling.ts  |    81 +
 packages/ai-models/src/providers/anthropic.ts |   375 +
 .../src/providers/azure-openai-responses.ts   |  1782 +
 packages/ai-models/src/providers/baseten.ts   |   748 +
 packages/ai-models/src/providers/cerebras.ts  |    59 +
 .../src/providers/cloudflare-ai-gateway.ts    |  1772 +
 .../src/providers/cloudflare-workers-ai.ts    |   670 +
 packages/ai-models/src/providers/deepseek.ts  |   131 +
 packages/ai-models/src/providers/fireworks.ts |   971 +
 .../ai-models/src/providers/google-vertex.ts  |   940 +
 packages/ai-models/src/providers/google.ts    |   585 +
 packages/ai-models/src/providers/groq.ts      |   242 +
 .../ai-models/src/providers/huggingface.ts    |  1284 +
 .../ai-models/src/providers/kimi-coding.ts    |    94 +
 packages/ai-models/src/providers/meta.ts      |   120 +
 .../ai-models/src/providers/minimax-cn.ts     |   106 +
 packages/ai-models/src/providers/minimax.ts   |   106 +
 packages/ai-models/src/providers/mistral.ts   |   501 +
 .../ai-models/src/providers/moonshotai-cn.ts  |   122 +
 .../ai-models/src/providers/moonshotai.ts     |   122 +
 packages/ai-models/src/providers/nvidia.ts    |  2225 +
 packages/ai-models/src/providers/openai.ts    |   989 +
 .../ai-models/src/providers/opencode-go.ts    |   839 +
 packages/ai-models/src/providers/opencode.ts  |  2573 +
 .../ai-models/src/providers/openrouter.ts     | 11572 ++++
 .../src/providers/qwen-token-plan-cn.ts       |   592 +
 .../providers/qwen-token-plan-individual.ts   |   284 +
 .../src/providers/qwen-token-plan.ts          |   593 +
 packages/ai-models/src/providers/together.ts  |   990 +
 .../src/providers/vercel-ai-gateway.ts        |  6055 ++
 packages/ai-models/src/providers/xai.ts       |   164 +
 .../src/providers/xiaomi-token-plan-ams.ts    |   111 +
 .../src/providers/xiaomi-token-plan-cn.ts     |   111 +
 .../src/providers/xiaomi-token-plan-sgp.ts    |   111 +
 packages/ai-models/src/providers/xiaomi.ts    |   231 +
 .../ai-models/src/providers/zai-coding-cn.ts  |   256 +
 packages/ai-models/src/providers/zai.ts       |   600 +
 packages/ai-models/src/reasoning.ts           |    53 +
 packages/ai-models/src/types.ts               |   152 +
 packages/ai-models/tests/catalog.test.ts      |   123 +
 packages/ai-models/tests/drift.test.ts        |    31 +
 packages/ai-models/tests/parity.test.ts       |    64 +
 packages/ai-models/tests/rules.test.ts        |   125 +
 packages/ai-models/tsconfig.json              |     8 +
 packages/ai-models/vite.config.ts             |    43 +
 packages/ai-ollama/src/model-reasoning.ts     |   445 +
 packages/ai-openai/src/model-reasoning.ts     |   579 +
 packages/ai-opencode/src/model-reasoning.ts   |    83 +
 packages/ai-openrouter/src/model-reasoning.ts |  3840 ++
 .../ai-vercel-gateway/src/model-reasoning.ts  |  2824 +
 packages/ai/src/activities/chat/adapter.ts    |    25 +-
 packages/ai/src/activities/chat/index.ts      |    29 +-
 .../src/activities/chat/middleware/types.ts   |     3 +
 packages/ai/src/adapter-internals.ts          |     5 +
 packages/ai/src/index.ts                      |    17 +
 packages/ai/src/reasoning.ts                  |   174 +
 packages/ai/src/types.ts                      |     8 +
 packages/ai/tests/reasoning-types.test-d.ts   |    46 +
 packages/ai/tests/reasoning.test.ts           |   147 +
 pnpm-lock.yaml                                |    15 +
 scripts/fetch-models-dev.ts                   |   137 +
 scripts/generate-ai-models.ts                 |   105 +
 scripts/model-sync/gateway-models.ts          |    87 +
 scripts/model-sync/reasoning-drift.test.ts    |    49 +
 scripts/model-sync/reasoning-targets.ts       |   180 +
 scripts/models-dev.models.json                | 55292 ++++++++++++++++
 scripts/sync-model-reasoning.ts               |   212 +
 93 files changed, 110908 insertions(+), 6 deletions(-)
 create mode 100644 packages/ai-anthropic/src/model-reasoning.ts
 create mode 100644 packages/ai-bedrock/src/model-reasoning.ts
 create mode 100644 packages/ai-byteplus/src/model-reasoning.ts
 create mode 100644 packages/ai-claude-code/src/model-reasoning.ts
 create mode 100644 packages/ai-cloudflare/src/model-reasoning.ts
 create mode 100644 packages/ai-codex/src/model-reasoning.ts
 create mode 100644 packages/ai-gemini/src/model-reasoning.ts
 create mode 100644 packages/ai-grok-build/src/model-reasoning.ts
 create mode 100644 packages/ai-grok/src/model-reasoning.ts
 create mode 100644 packages/ai-groq/src/model-reasoning.ts
 create mode 100644 packages/ai-llmgateway/src/model-reasoning.ts
 create mode 100644 packages/ai-lovable/src/model-reasoning.ts
 create mode 100644 packages/ai-mistral/src/model-reasoning.ts
 create mode 100644 packages/ai-models/LICENSE
 create mode 100644 packages/ai-models/README.md
 create mode 100644 packages/ai-models/package.json
 create mode 100644 packages/ai-models/scripts/catalog.ts
 create mode 100644 packages/ai-models/scripts/known-ids.ts
 create mode 100644 packages/ai-models/scripts/overrides.ts
 create mode 100644 packages/ai-models/scripts/providers.ts
 create mode 100644 packages/ai-models/scripts/rules.ts
 create mode 100644 packages/ai-models/src/catalog.ts
 create mode 100644 packages/ai-models/src/cost.ts
 create mode 100644 packages/ai-models/src/index.ts
 create mode 100644 packages/ai-models/src/providers/amazon-bedrock.ts
 create mode 100644 packages/ai-models/src/providers/ant-ling.ts
 create mode 100644 packages/ai-models/src/providers/anthropic.ts
 create mode 100644 packages/ai-models/src/providers/azure-openai-responses.ts
 create mode 100644 packages/ai-models/src/providers/baseten.ts
 create mode 100644 packages/ai-models/src/providers/cerebras.ts
 create mode 100644 packages/ai-models/src/providers/cloudflare-ai-gateway.ts
 create mode 100644 packages/ai-models/src/providers/cloudflare-workers-ai.ts
 create mode 100644 packages/ai-models/src/providers/deepseek.ts
 create mode 100644 packages/ai-models/src/providers/fireworks.ts
 create mode 100644 packages/ai-models/src/providers/google-vertex.ts
 create mode 100644 packages/ai-models/src/providers/google.ts
 create mode 100644 packages/ai-models/src/providers/groq.ts
 create mode 100644 packages/ai-models/src/providers/huggingface.ts
 create mode 100644 packages/ai-models/src/providers/kimi-coding.ts
 create mode 100644 packages/ai-models/src/providers/meta.ts
 create mode 100644 packages/ai-models/src/providers/minimax-cn.ts
 create mode 100644 packages/ai-models/src/providers/minimax.ts
 create mode 100644 packages/ai-models/src/providers/mistral.ts
 create mode 100644 packages/ai-models/src/providers/moonshotai-cn.ts
 create mode 100644 packages/ai-models/src/providers/moonshotai.ts
 create mode 100644 packages/ai-models/src/providers/nvidia.ts
 create mode 100644 packages/ai-models/src/providers/openai.ts
 create mode 100644 packages/ai-models/src/providers/opencode-go.ts
 create mode 100644 packages/ai-models/src/providers/opencode.ts
 create mode 100644 packages/ai-models/src/providers/openrouter.ts
 create mode 100644 packages/ai-models/src/providers/qwen-token-plan-cn.ts
 create mode 100644 packages/ai-models/src/providers/qwen-token-plan-individual.ts
 create mode 100644 packages/ai-models/src/providers/qwen-token-plan.ts
 create mode 100644 packages/ai-models/src/providers/together.ts
 create mode 100644 packages/ai-models/src/providers/vercel-ai-gateway.ts
 create mode 100644 packages/ai-models/src/providers/xai.ts
 create mode 100644 packages/ai-models/src/providers/xiaomi-token-plan-ams.ts
 create mode 100644 packages/ai-models/src/providers/xiaomi-token-plan-cn.ts
 create mode 100644 packages/ai-models/src/providers/xiaomi-token-plan-sgp.ts
 create mode 100644 packages/ai-models/src/providers/xiaomi.ts
 create mode 100644 packages/ai-models/src/providers/zai-coding-cn.ts
 create mode 100644 packages/ai-models/src/providers/zai.ts
 create mode 100644 packages/ai-models/src/reasoning.ts
 create mode 100644 packages/ai-models/src/types.ts
 create mode 100644 packages/ai-models/tests/catalog.test.ts
 create mode 100644 packages/ai-models/tests/drift.test.ts
 create mode 100644 packages/ai-models/tests/parity.test.ts
 create mode 100644 packages/ai-models/tests/rules.test.ts
 create mode 100644 packages/ai-models/tsconfig.json
 create mode 100644 packages/ai-models/vite.config.ts
 create mode 100644 packages/ai-ollama/src/model-reasoning.ts
 create mode 100644 packages/ai-openai/src/model-reasoning.ts
 create mode 100644 packages/ai-opencode/src/model-reasoning.ts
 create mode 100644 packages/ai-openrouter/src/model-reasoning.ts
 create mode 100644 packages/ai-vercel-gateway/src/model-reasoning.ts
 create mode 100644 packages/ai/src/reasoning.ts
 create mode 100644 packages/ai/tests/reasoning-types.test-d.ts
 create mode 100644 packages/ai/tests/reasoning.test.ts
 create mode 100644 scripts/fetch-models-dev.ts
 create mode 100644 scripts/generate-ai-models.ts
 create mode 100644 scripts/model-sync/gateway-models.ts
 create mode 100644 scripts/model-sync/reasoning-drift.test.ts
 create mode 100644 scripts/model-sync/reasoning-targets.ts
 create mode 100644 scripts/models-dev.models.json
 create mode 100644 scripts/sync-model-reasoning.ts

diff --git a/package.json b/package.json
index bf53daf734..e90bfa751d 100644
--- a/package.json
+++ b/package.json
@@ -47,8 +47,8 @@
     "generate-docs": "node scripts/generate-docs.ts && pnpm run copy:readme",
     "generate:fal-image-fields": "tsx scripts/generate-fal-image-field-map.ts",
     "generate:models": "pnpm generate:models:fetch && pnpm regenerate:models && tsx scripts/sync-provider-models.ts && pnpm format",
-    "generate:models:fetch": "tsx scripts/fetch-openrouter-models.ts && tsx scripts/fetch-vercel-gateway-models.ts && tsx scripts/fetch-lovable-gateway-models.ts",
-    "regenerate:models": "tsx scripts/convert-openrouter-models.ts && tsx scripts/convert-vercel-gateway-models.ts",
+    "generate:models:fetch": "tsx scripts/fetch-openrouter-models.ts && tsx scripts/fetch-vercel-gateway-models.ts && tsx scripts/fetch-lovable-gateway-models.ts && tsx scripts/fetch-models-dev.ts",
+    "regenerate:models": "tsx scripts/convert-openrouter-models.ts && tsx scripts/convert-vercel-gateway-models.ts && tsx scripts/generate-ai-models.ts && tsx scripts/sync-model-reasoning.ts",
     "sync-docs-config": "node scripts/sync-docs-config.ts",
     "copy:readme": "node scripts/copy-readme.js",
     "changeset": "changeset",
diff --git a/packages/ai-anthropic/src/model-reasoning.ts b/packages/ai-anthropic/src/model-reasoning.ts
new file mode 100644
index 0000000000..6d300d0e5c
--- /dev/null
+++ b/packages/ai-anthropic/src/model-reasoning.ts
@@ -0,0 +1,216 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type AnthropicModelReasoningByName = {
+  'claude-sonnet-5-5': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'claude-opus-5-5': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'claude-fable-5-1': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'claude-opus-5': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'claude-opus-5-fast': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: true
+  }
+  'claude-opus-4-6': { levels: 'low' | 'medium' | 'high' | 'max'; budget: true }
+  'claude-opus-4-5': { levels: 'low' | 'medium' | 'high'; budget: true }
+  'claude-sonnet-4-6': {
+    levels: 'low' | 'medium' | 'high' | 'max'
+    budget: true
+  }
+  'claude-sonnet-4-5': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'claude-haiku-4-5': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'claude-opus-4-1': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'claude-opus-4-7': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'claude-opus-4-8': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'claude-fable-5': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'claude-sonnet-5': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const ANTHROPIC_MODEL_REASONING: Readonly<
+  Record<string, ModelReasoning>
+> = {
+  'claude-sonnet-5-5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'claude-opus-5-5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'claude-fable-5-1': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'claude-opus-5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'claude-opus-5-fast': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: true,
+  },
+  'claude-opus-4-6': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: true,
+  },
+  'claude-opus-4-5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: true,
+  },
+  'claude-sonnet-4-6': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: true,
+  },
+  'claude-sonnet-4-5': { budget: true },
+  'claude-haiku-4-5': { budget: true },
+  'claude-opus-4-1': { budget: true },
+  'claude-opus-4-7': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'claude-opus-4-8': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'claude-fable-5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'claude-sonnet-5': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+}
diff --git a/packages/ai-bedrock/src/model-reasoning.ts b/packages/ai-bedrock/src/model-reasoning.ts
new file mode 100644
index 0000000000..cf14007e07
--- /dev/null
+++ b/packages/ai-bedrock/src/model-reasoning.ts
@@ -0,0 +1,109 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type BedrockModelReasoningByName = {
+  'openai.gpt-oss-120b-1:0': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai.gpt-oss-20b-1:0': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'us.anthropic.claude-sonnet-4-5-20250929-v1:0': {
+    levels: 'off' | 'high'
+    budget: true
+  }
+  'us.anthropic.claude-haiku-4-5-20251001-v1:0': {
+    levels: 'off' | 'high'
+    budget: true
+  }
+  'us.deepseek.r1-v1:0': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google.gemma-4-31b': { levels: 'off' | 'high'; budget: false }
+  'google.gemma-4-26b-a4b': { levels: 'off' | 'high'; budget: false }
+  'google.gemma-4-e2b': { levels: 'off' | 'high'; budget: false }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const BEDROCK_MODEL_REASONING: Readonly<Record<string, ModelReasoning>> =
+  {
+    'openai.gpt-oss-120b-1:0': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'openai.gpt-oss-20b-1:0': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'us.anthropic.claude-sonnet-4-5-20250929-v1:0': {
+      map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+      budget: true,
+    },
+    'us.anthropic.claude-haiku-4-5-20251001-v1:0': {
+      map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+      budget: true,
+    },
+    'us.amazon.nova-pro-v1:0': false,
+    'us.amazon.nova-lite-v1:0': false,
+    'us.amazon.nova-micro-v1:0': false,
+    'us.meta.llama3-3-70b-instruct-v1:0': false,
+    'us.meta.llama4-maverick-17b-instruct-v1:0': false,
+    'us.mistral.pixtral-large-2502-v1:0': false,
+    'us.deepseek.r1-v1:0': { budget: false },
+    'google.gemma-4-31b': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'google.gemma-4-26b-a4b': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'google.gemma-4-e2b': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+  }
diff --git a/packages/ai-byteplus/src/model-reasoning.ts b/packages/ai-byteplus/src/model-reasoning.ts
new file mode 100644
index 0000000000..e603d06159
--- /dev/null
+++ b/packages/ai-byteplus/src/model-reasoning.ts
@@ -0,0 +1,159 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type BytePlusModelReasoningByName = {
+  'seed-2-0-lite-260428': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'seed-2-0-mini-260428': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'seed-2-0-pro-260328': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'seed-2-0-code-preview-260328': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'seed-1-8-251228': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'seed-1-6-250915': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'seed-1-6-250615': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'seed-1-6-flash-250715': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'glm-5-2-260617': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const BYTEPLUS_MODEL_REASONING: Readonly<
+  Record<string, ModelReasoning>
+> = {
+  'seed-2-0-lite-260428': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'seed-2-0-mini-260428': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'seed-2-0-pro-260328': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'seed-2-0-code-preview-260328': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'seed-1-8-251228': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'seed-1-6-250915': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'seed-1-6-250615': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'seed-1-6-flash-250715': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'glm-5-2-260617': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+}
diff --git a/packages/ai-claude-code/src/model-reasoning.ts b/packages/ai-claude-code/src/model-reasoning.ts
new file mode 100644
index 0000000000..9cd2945f18
--- /dev/null
+++ b/packages/ai-claude-code/src/model-reasoning.ts
@@ -0,0 +1,109 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type ClaudeCodeModelReasoningByName = {
+  'claude-opus-4-8': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'claude-opus-4-7': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'claude-opus-4-6': { levels: 'low' | 'medium' | 'high' | 'max'; budget: true }
+  'claude-sonnet-4-6': {
+    levels: 'low' | 'medium' | 'high' | 'max'
+    budget: true
+  }
+  'claude-haiku-4-5': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  opus: { levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'; budget: false }
+  sonnet: { levels: 'low' | 'medium' | 'high' | 'max'; budget: true }
+  haiku: { levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'; budget: true }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const CLAUDE_CODE_MODEL_REASONING: Readonly<
+  Record<string, ModelReasoning>
+> = {
+  'claude-opus-4-8': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'claude-opus-4-7': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'claude-opus-4-6': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: true,
+  },
+  'claude-sonnet-4-6': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: true,
+  },
+  'claude-haiku-4-5': { budget: true },
+  opus: {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  sonnet: {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: true,
+  },
+  haiku: { budget: true },
+}
diff --git a/packages/ai-cloudflare/src/model-reasoning.ts b/packages/ai-cloudflare/src/model-reasoning.ts
new file mode 100644
index 0000000000..83e26c2e12
--- /dev/null
+++ b/packages/ai-cloudflare/src/model-reasoning.ts
@@ -0,0 +1,209 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type CloudflareModelReasoningByName = {
+  '@cf/google/gemma-4-26b-a4b-it': { levels: 'off' | 'high'; budget: false }
+  '@cf/deepseek-ai/deepseek-v4-flash-0731': {
+    levels: 'off' | 'low' | 'high' | 'max'
+    budget: false
+  }
+  '@cf/deepseek-ai/deepseek-v4-pro-0813': {
+    levels: 'off' | 'low' | 'high' | 'max'
+    budget: false
+  }
+  '@cf/deepseek-ai/deepseek-r1-distill-qwen-32b': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  '@cf/moonshotai/kimi-k2.6': { levels: 'off' | 'high'; budget: false }
+  '@cf/moonshotai/kimi-k2.7-code': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  '@cf/zai-org/glm-5.3-flash': { levels: 'low' | 'high' | 'max'; budget: false }
+  '@cf/zai-org/glm-4.7-flash': { levels: 'off' | 'high'; budget: false }
+  '@cf/zai-org/glm-5.2': { levels: 'off' | 'high' | 'max'; budget: false }
+  '@cf/zai-org/glm-5.3': { levels: 'low' | 'high' | 'max'; budget: false }
+  '@cf/nvidia/nemotron-3-120b-a12b': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  '@cf/qwen/qwen3.8-27b': {
+    levels: 'off' | 'low' | 'medium' | 'xhigh'
+    budget: false
+  }
+  '@cf/qwen/qwq-32b': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  '@cf/qwen/qwen3-30b-a3b-fp8': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  '@cf/openai/gpt-oss-20b': { levels: 'low' | 'medium' | 'high'; budget: false }
+  '@cf/openai/gpt-oss-120b': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const CLOUDFLARE_MODEL_REASONING: Readonly<
+  Record<string, ModelReasoning>
+> = {
+  '@cf/meta/llama-3.3-70b-instruct-fp8-fast': false,
+  '@cf/meta/llama-guard-3-8b': false,
+  '@cf/meta/llama-3.1-8b-instruct-fp8': false,
+  '@cf/meta/llama-3.2-11b-vision-instruct': false,
+  '@cf/meta/llama-3.2-1b-instruct': false,
+  '@cf/meta/llama-4-scout-17b-16e-instruct': false,
+  '@cf/meta/llama-3.2-3b-instruct': false,
+  '@cf/google/gemma-4-26b-a4b-it': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  '@cf/aisingapore/gemma-sea-lion-v4-27b-it': false,
+  '@cf/ibm-granite/granite-4.0-h-micro': false,
+  '@cf/deepseek-ai/deepseek-v4-flash-0731': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  '@cf/deepseek-ai/deepseek-v4-pro-0813': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  '@cf/deepseek-ai/deepseek-r1-distill-qwen-32b': { budget: false },
+  '@cf/mistralai/mistral-small-3.1-24b-instruct': false,
+  '@cf/moonshotai/kimi-k2.6': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  '@cf/moonshotai/kimi-k2.7-code': { budget: false },
+  '@cf/zai-org/glm-5.3-flash': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  '@cf/zai-org/glm-4.7-flash': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  '@cf/zai-org/glm-5.2': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  '@cf/zai-org/glm-5.3': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  '@cf/nvidia/nemotron-3-120b-a12b': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  '@cf/qwen/qwen3.8-27b': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  '@cf/qwen/qwq-32b': { budget: false },
+  '@cf/qwen/qwen3-30b-a3b-fp8': { budget: false },
+  '@cf/qwen/qwen2.5-coder-32b-instruct': false,
+  '@cf/openai/gpt-oss-20b': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  '@cf/openai/gpt-oss-120b': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+}
diff --git a/packages/ai-codex/src/model-reasoning.ts b/packages/ai-codex/src/model-reasoning.ts
new file mode 100644
index 0000000000..99f4e1ef03
--- /dev/null
+++ b/packages/ai-codex/src/model-reasoning.ts
@@ -0,0 +1,84 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type CodexModelReasoningByName = {
+  'gpt-5.3-codex': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'gpt-5.2-codex': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'gpt-5.1-codex': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'gpt-5.1-codex-mini': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'gpt-5.1': { levels: 'off' | 'low' | 'medium' | 'high'; budget: false }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const CODEX_MODEL_REASONING: Readonly<Record<string, ModelReasoning>> = {
+  'gpt-5.3-codex': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'gpt-5.2-codex': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'gpt-5.1-codex': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'gpt-5.1-codex-mini': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'gpt-5.1': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+}
diff --git a/packages/ai-gemini/src/model-reasoning.ts b/packages/ai-gemini/src/model-reasoning.ts
new file mode 100644
index 0000000000..174ee85ff4
--- /dev/null
+++ b/packages/ai-gemini/src/model-reasoning.ts
@@ -0,0 +1,164 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type GeminiModelReasoningByName = {
+  'gemini-3.8-flash': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'gemini-3.7-flash': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'gemini-3.6-flash': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'gemini-3.5-flash': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'gemini-3.5-flash-lite': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'gemini-3.1-pro-preview': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'gemini-3-flash-preview': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'gemini-3.1-flash-lite': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'gemini-3.1-flash-lite-preview': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'gemini-2.5-pro': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'gemini-2.5-flash': { levels: 'off' | 'high'; budget: true }
+  'gemini-2.5-flash-lite': { levels: 'off' | 'high'; budget: true }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const GEMINI_MODEL_REASONING: Readonly<Record<string, ModelReasoning>> =
+  {
+    'gemini-3.8-flash': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gemini-3.7-flash': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gemini-3.6-flash': {
+      map: {
+        off: null,
+        minimal: 'minimal',
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gemini-3.5-flash': {
+      map: {
+        off: null,
+        minimal: 'minimal',
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gemini-3.5-flash-lite': {
+      map: {
+        off: null,
+        minimal: 'minimal',
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gemini-3.1-pro-preview': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gemini-3-flash-preview': {
+      map: {
+        off: null,
+        minimal: 'minimal',
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gemini-3.1-flash-lite': {
+      map: {
+        off: null,
+        minimal: 'minimal',
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gemini-3.1-flash-lite-preview': {
+      map: {
+        off: null,
+        minimal: 'minimal',
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gemini-2.5-pro': { budget: true },
+    'gemini-2.5-flash': {
+      map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+      budget: true,
+    },
+    'gemini-2.5-flash-lite': {
+      map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+      budget: true,
+    },
+  }
diff --git a/packages/ai-grok-build/src/model-reasoning.ts b/packages/ai-grok-build/src/model-reasoning.ts
new file mode 100644
index 0000000000..82f8f78ff1
--- /dev/null
+++ b/packages/ai-grok-build/src/model-reasoning.ts
@@ -0,0 +1,25 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type GrokBuildModelReasoningByName = {
+  'grok-build': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'grok-build-0.1': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const GROK_BUILD_MODEL_REASONING: Readonly<
+  Record<string, ModelReasoning>
+> = {
+  'grok-build': { budget: false },
+  'grok-build-0.1': { budget: false },
+}
diff --git a/packages/ai-grok/src/model-reasoning.ts b/packages/ai-grok/src/model-reasoning.ts
new file mode 100644
index 0000000000..556ec3b704
--- /dev/null
+++ b/packages/ai-grok/src/model-reasoning.ts
@@ -0,0 +1,82 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type GrokModelReasoningByName = {
+  'grok-4.7': { levels: 'low' | 'medium' | 'high' | 'xhigh'; budget: false }
+  'grok-4.5': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'grok-4.6': { levels: 'low' | 'medium' | 'high' | 'xhigh'; budget: false }
+  'grok-build-0.1': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'grok-4.3': { levels: 'off' | 'low' | 'medium' | 'high'; budget: false }
+  'grok-4.20-reasoning': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'grok-4.1-fast-reasoning': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const GROK_MODEL_REASONING: Readonly<Record<string, ModelReasoning>> = {
+  'grok-4.7': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'grok-4.5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'grok-4.6': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'grok-build-0.1': { budget: false },
+  'grok-4.3': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'grok-4.20-reasoning': { budget: false },
+  'grok-4.20-non-reasoning': false,
+  'grok-4.1-fast-reasoning': { budget: false },
+  'grok-4.1-fast-non-reasoning': false,
+}
diff --git a/packages/ai-groq/src/model-reasoning.ts b/packages/ai-groq/src/model-reasoning.ts
new file mode 100644
index 0000000000..b726235c80
--- /dev/null
+++ b/packages/ai-groq/src/model-reasoning.ts
@@ -0,0 +1,68 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type GroqModelReasoningByName = {
+  'openai/gpt-oss-20b': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'openai/gpt-oss-120b': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'openai/gpt-oss-safeguard-20b': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'qwen/qwen3-32b': { levels: 'off' | 'high'; budget: true }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const GROQ_MODEL_REASONING: Readonly<Record<string, ModelReasoning>> = {
+  'llama-3.1-8b-instant': false,
+  'llama-3.3-70b-versatile': false,
+  'meta-llama/llama-4-maverick-17b-128e-instruct': false,
+  'meta-llama/llama-4-scout-17b-16e-instruct': false,
+  'meta-llama/llama-guard-4-12b': false,
+  'meta-llama/llama-prompt-guard-2-86m': false,
+  'meta-llama/llama-prompt-guard-2-22m': false,
+  'openai/gpt-oss-20b': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-oss-120b': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-oss-safeguard-20b': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'moonshotai/kimi-k2-instruct-0905': false,
+  'qwen/qwen3-32b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: true,
+  },
+}
diff --git a/packages/ai-llmgateway/src/model-reasoning.ts b/packages/ai-llmgateway/src/model-reasoning.ts
new file mode 100644
index 0000000000..43ef000961
--- /dev/null
+++ b/packages/ai-llmgateway/src/model-reasoning.ts
@@ -0,0 +1,233 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type LLMGatewayModelReasoningByName = {
+  'gpt-5.6-terra': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'gpt-5.5': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'gpt-5.4-mini': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'claude-opus-5': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'claude-sonnet-5': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'claude-haiku-4-5': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'gemini-pro-latest': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'gemini-3.6-flash': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'kimi-k3': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'glm-5.2': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'deepseek-v4-pro': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'qwen3.7-max': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'minimax-m2.5': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'grok-4-5': { levels: 'low' | 'medium' | 'high'; budget: false }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const LLMGATEWAY_MODEL_REASONING: Readonly<
+  Record<string, ModelReasoning>
+> = {
+  'gpt-5.6-terra': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'gpt-5.5': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'gpt-5.4-mini': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'claude-opus-5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'claude-sonnet-5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'claude-haiku-4-5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'gemini-pro-latest': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'gemini-3.6-flash': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'kimi-k3': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'glm-5.2': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'deepseek-v4-pro': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'qwen3.7-max': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'minimax-m2.5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'grok-4-5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+}
diff --git a/packages/ai-lovable/src/model-reasoning.ts b/packages/ai-lovable/src/model-reasoning.ts
new file mode 100644
index 0000000000..a433496be8
--- /dev/null
+++ b/packages/ai-lovable/src/model-reasoning.ts
@@ -0,0 +1,327 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type LovableModelReasoningByName = {
+  'google/gemini-3.7-flash': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.6-flash': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.5-flash': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.1-pro-preview': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.1-flash-lite': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3-flash-preview': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-2.5-pro': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'google/gemini-2.5-flash': { levels: 'off' | 'high'; budget: true }
+  'google/gemini-2.5-flash-lite': { levels: 'off' | 'high'; budget: true }
+  'openai/gpt-5.6-sol': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-terra': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-luna': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.5-pro': { levels: 'medium' | 'high' | 'xhigh'; budget: false }
+  'openai/gpt-5.5': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.4-pro': { levels: 'medium' | 'high' | 'xhigh'; budget: false }
+  'openai/gpt-5.4': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.4-mini': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.4-nano': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.2': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5-mini': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5-nano': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const LOVABLE_MODEL_REASONING: Readonly<Record<string, ModelReasoning>> =
+  {
+    'google/gemini-3.7-flash': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'google/gemini-3.6-flash': {
+      map: {
+        off: null,
+        minimal: 'minimal',
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'google/gemini-3.5-flash': {
+      map: {
+        off: null,
+        minimal: 'minimal',
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'google/gemini-3.1-pro-preview': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'google/gemini-3.1-flash-lite': {
+      map: {
+        off: null,
+        minimal: 'minimal',
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'google/gemini-3-flash-preview': {
+      map: {
+        off: null,
+        minimal: 'minimal',
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'google/gemini-2.5-pro': { budget: true },
+    'google/gemini-2.5-flash': {
+      map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+      budget: true,
+    },
+    'google/gemini-2.5-flash-lite': {
+      map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+      budget: true,
+    },
+    'openai/gpt-5.6-sol': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'openai/gpt-5.6-terra': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'openai/gpt-5.6-luna': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'openai/gpt-5.5-pro': {
+      map: {
+        off: null,
+        minimal: null,
+        low: null,
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: null,
+      },
+      budget: false,
+    },
+    'openai/gpt-5.5': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: null,
+      },
+      budget: false,
+    },
+    'openai/gpt-5.4-pro': {
+      map: {
+        off: null,
+        minimal: null,
+        low: null,
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: null,
+      },
+      budget: false,
+    },
+    'openai/gpt-5.4': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: null,
+      },
+      budget: false,
+    },
+    'openai/gpt-5.4-mini': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: null,
+      },
+      budget: false,
+    },
+    'openai/gpt-5.4-nano': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: null,
+      },
+      budget: false,
+    },
+    'openai/gpt-5.2': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: null,
+      },
+      budget: false,
+    },
+    'openai/gpt-5': {
+      map: {
+        off: null,
+        minimal: 'minimal',
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'openai/gpt-5-mini': {
+      map: {
+        off: null,
+        minimal: 'minimal',
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'openai/gpt-5-nano': {
+      map: {
+        off: null,
+        minimal: 'minimal',
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+  }
diff --git a/packages/ai-mistral/src/model-reasoning.ts b/packages/ai-mistral/src/model-reasoning.ts
new file mode 100644
index 0000000000..91f8f90443
--- /dev/null
+++ b/packages/ai-mistral/src/model-reasoning.ts
@@ -0,0 +1,53 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type MistralModelReasoningByName = {
+  'mistral-medium-latest': { levels: 'off' | 'high'; budget: false }
+  'mistral-small-latest': { levels: 'off' | 'high'; budget: false }
+  'magistral-medium-latest': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const MISTRAL_MODEL_REASONING: Readonly<Record<string, ModelReasoning>> =
+  {
+    'mistral-large-latest': false,
+    'mistral-medium-latest': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'mistral-small-latest': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'ministral-8b-latest': false,
+    'ministral-3b-latest': false,
+    'codestral-latest': false,
+    'pixtral-large-latest': false,
+    'magistral-medium-latest': { budget: false },
+    'open-mistral-nemo': false,
+    'mistral-medium-3': false,
+    'mistral-small-2503': false,
+  }
diff --git a/packages/ai-models/LICENSE b/packages/ai-models/LICENSE
new file mode 100644
index 0000000000..308cb68dc0
--- /dev/null
+++ b/packages/ai-models/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/packages/ai-models/README.md b/packages/ai-models/README.md
new file mode 100644
index 0000000000..f9fd3467a1
--- /dev/null
+++ b/packages/ai-models/README.md
@@ -0,0 +1,38 @@
+<div align="center">
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://tanstack.com/api/readme/ai.png?theme=dark"
+    />
+    <source
+      media="(prefers-color-scheme: light)"
+      srcset="https://tanstack.com/api/readme/ai.png"
+    />
+    <img
+      src="https://tanstack.com/api/readme/ai.png"
+      alt="TanStack AI"
+      width="900"
+    />
+  </picture>
+</div>
+
+<br />
+
+# @tanstack/ai-models
+
+A model catalog you can read at runtime: each model's context window, price, reasoning levels, input kinds, and wire quirks, for 38 providers.
+
+```ts
+import { getModel, modelCost, clampReasoningLevel } from '@tanstack/ai-models'
+
+const model = getModel('deepseek', 'deepseek-v4-flash')
+model?.contextWindow // 1000000
+modelCost(model!, { input: 12_000, output: 800 }).total // USD
+clampReasoningLevel(model!, 'medium') // 'high': the nearest level the model has
+```
+
+- No dependencies, and no Node.js APIs, so it runs on edge runtimes too.
+- One subpath per provider (`@tanstack/ai-models/deepseek`), so a build ships only the providers it imports.
+- The data comes from [models.dev](https://models.dev) and the OpenRouter and Vercel model lists. `pnpm generate:models` refreshes it.
+
+Read the guide: [Model catalog](https://tanstack.com/ai/latest/docs/models/catalog).
diff --git a/packages/ai-models/package.json b/packages/ai-models/package.json
new file mode 100644
index 0000000000..1dc57084aa
--- /dev/null
+++ b/packages/ai-models/package.json
@@ -0,0 +1,213 @@
+{
+  "name": "@tanstack/ai-models",
+  "version": "0.0.0",
+  "description": "A runtime model catalog for TanStack AI: context windows, prices, reasoning levels, and wire quirks per provider.",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "homepage": "https://tanstack.com/ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-models"
+  },
+  "bugs": {
+    "url": "https://github.com/TanStack/ai/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./amazon-bedrock": {
+      "types": "./dist/esm/providers/amazon-bedrock.d.ts",
+      "import": "./dist/esm/providers/amazon-bedrock.js"
+    },
+    "./ant-ling": {
+      "types": "./dist/esm/providers/ant-ling.d.ts",
+      "import": "./dist/esm/providers/ant-ling.js"
+    },
+    "./anthropic": {
+      "types": "./dist/esm/providers/anthropic.d.ts",
+      "import": "./dist/esm/providers/anthropic.js"
+    },
+    "./azure-openai-responses": {
+      "types": "./dist/esm/providers/azure-openai-responses.d.ts",
+      "import": "./dist/esm/providers/azure-openai-responses.js"
+    },
+    "./baseten": {
+      "types": "./dist/esm/providers/baseten.d.ts",
+      "import": "./dist/esm/providers/baseten.js"
+    },
+    "./cerebras": {
+      "types": "./dist/esm/providers/cerebras.d.ts",
+      "import": "./dist/esm/providers/cerebras.js"
+    },
+    "./cloudflare-ai-gateway": {
+      "types": "./dist/esm/providers/cloudflare-ai-gateway.d.ts",
+      "import": "./dist/esm/providers/cloudflare-ai-gateway.js"
+    },
+    "./cloudflare-workers-ai": {
+      "types": "./dist/esm/providers/cloudflare-workers-ai.d.ts",
+      "import": "./dist/esm/providers/cloudflare-workers-ai.js"
+    },
+    "./deepseek": {
+      "types": "./dist/esm/providers/deepseek.d.ts",
+      "import": "./dist/esm/providers/deepseek.js"
+    },
+    "./fireworks": {
+      "types": "./dist/esm/providers/fireworks.d.ts",
+      "import": "./dist/esm/providers/fireworks.js"
+    },
+    "./google": {
+      "types": "./dist/esm/providers/google.d.ts",
+      "import": "./dist/esm/providers/google.js"
+    },
+    "./google-vertex": {
+      "types": "./dist/esm/providers/google-vertex.d.ts",
+      "import": "./dist/esm/providers/google-vertex.js"
+    },
+    "./groq": {
+      "types": "./dist/esm/providers/groq.d.ts",
+      "import": "./dist/esm/providers/groq.js"
+    },
+    "./huggingface": {
+      "types": "./dist/esm/providers/huggingface.d.ts",
+      "import": "./dist/esm/providers/huggingface.js"
+    },
+    "./kimi-coding": {
+      "types": "./dist/esm/providers/kimi-coding.d.ts",
+      "import": "./dist/esm/providers/kimi-coding.js"
+    },
+    "./meta": {
+      "types": "./dist/esm/providers/meta.d.ts",
+      "import": "./dist/esm/providers/meta.js"
+    },
+    "./minimax": {
+      "types": "./dist/esm/providers/minimax.d.ts",
+      "import": "./dist/esm/providers/minimax.js"
+    },
+    "./minimax-cn": {
+      "types": "./dist/esm/providers/minimax-cn.d.ts",
+      "import": "./dist/esm/providers/minimax-cn.js"
+    },
+    "./mistral": {
+      "types": "./dist/esm/providers/mistral.d.ts",
+      "import": "./dist/esm/providers/mistral.js"
+    },
+    "./moonshotai": {
+      "types": "./dist/esm/providers/moonshotai.d.ts",
+      "import": "./dist/esm/providers/moonshotai.js"
+    },
+    "./moonshotai-cn": {
+      "types": "./dist/esm/providers/moonshotai-cn.d.ts",
+      "import": "./dist/esm/providers/moonshotai-cn.js"
+    },
+    "./nvidia": {
+      "types": "./dist/esm/providers/nvidia.d.ts",
+      "import": "./dist/esm/providers/nvidia.js"
+    },
+    "./openai": {
+      "types": "./dist/esm/providers/openai.d.ts",
+      "import": "./dist/esm/providers/openai.js"
+    },
+    "./opencode": {
+      "types": "./dist/esm/providers/opencode.d.ts",
+      "import": "./dist/esm/providers/opencode.js"
+    },
+    "./opencode-go": {
+      "types": "./dist/esm/providers/opencode-go.d.ts",
+      "import": "./dist/esm/providers/opencode-go.js"
+    },
+    "./openrouter": {
+      "types": "./dist/esm/providers/openrouter.d.ts",
+      "import": "./dist/esm/providers/openrouter.js"
+    },
+    "./qwen-token-plan": {
+      "types": "./dist/esm/providers/qwen-token-plan.d.ts",
+      "import": "./dist/esm/providers/qwen-token-plan.js"
+    },
+    "./qwen-token-plan-cn": {
+      "types": "./dist/esm/providers/qwen-token-plan-cn.d.ts",
+      "import": "./dist/esm/providers/qwen-token-plan-cn.js"
+    },
+    "./qwen-token-plan-individual": {
+      "types": "./dist/esm/providers/qwen-token-plan-individual.d.ts",
+      "import": "./dist/esm/providers/qwen-token-plan-individual.js"
+    },
+    "./together": {
+      "types": "./dist/esm/providers/together.d.ts",
+      "import": "./dist/esm/providers/together.js"
+    },
+    "./vercel-ai-gateway": {
+      "types": "./dist/esm/providers/vercel-ai-gateway.d.ts",
+      "import": "./dist/esm/providers/vercel-ai-gateway.js"
+    },
+    "./xai": {
+      "types": "./dist/esm/providers/xai.d.ts",
+      "import": "./dist/esm/providers/xai.js"
+    },
+    "./xiaomi": {
+      "types": "./dist/esm/providers/xiaomi.d.ts",
+      "import": "./dist/esm/providers/xiaomi.js"
+    },
+    "./xiaomi-token-plan-ams": {
+      "types": "./dist/esm/providers/xiaomi-token-plan-ams.d.ts",
+      "import": "./dist/esm/providers/xiaomi-token-plan-ams.js"
+    },
+    "./xiaomi-token-plan-cn": {
+      "types": "./dist/esm/providers/xiaomi-token-plan-cn.d.ts",
+      "import": "./dist/esm/providers/xiaomi-token-plan-cn.js"
+    },
+    "./xiaomi-token-plan-sgp": {
+      "types": "./dist/esm/providers/xiaomi-token-plan-sgp.d.ts",
+      "import": "./dist/esm/providers/xiaomi-token-plan-sgp.js"
+    },
+    "./zai": {
+      "types": "./dist/esm/providers/zai.d.ts",
+      "import": "./dist/esm/providers/zai.js"
+    },
+    "./zai-coding-cn": {
+      "types": "./dist/esm/providers/zai-coding-cn.d.ts",
+      "import": "./dist/esm/providers/zai-coding-cn.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "oxlint src --type-aware --fix",
+    "test:build": "publint --strict",
+    "test:oxlint": "oxlint src --type-aware",
+    "test:coverage": "vitest run --coverage --coverage.include='src/**' --coverage.reporter=text-summary --coverage.reporter=json-summary",
+    "test:lib": "vitest run",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  },
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "typescript",
+    "tanstack",
+    "models",
+    "model-catalog",
+    "pricing",
+    "context-window"
+  ],
+  "devDependencies": {
+    "@tanstack/ai": "workspace:*",
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "vite": "^8.2.1"
+  }
+}
diff --git a/packages/ai-models/scripts/catalog.ts b/packages/ai-models/scripts/catalog.ts
new file mode 100644
index 0000000000..69af0ab2d1
--- /dev/null
+++ b/packages/ai-models/scripts/catalog.ts
@@ -0,0 +1,160 @@
+import { BORROW, ONLY } from './known-ids'
+import { EXTRA_MODELS, MODEL_OVERRIDES } from './overrides'
+import {
+  inputModalities,
+  makesText,
+  modelHints,
+  reasoningMapFrom,
+  takesBudget,
+} from './rules'
+import type { ProviderRow, Wire } from './providers'
+import type { DevModel } from './rules'
+import type {
+  ModelCompat,
+  ModelRecord,
+  ProviderRecord,
+  WireApi,
+} from '../src/types'
+
+/** The trimmed models.dev catalog (`scripts/models-dev.models.json`). */
+export type DevCatalog = Readonly<
+  Record<string, { models: Readonly<Record<string, DevModel>> }>
+>
+
+/** A gateway's own model list, turned into models.dev's shape. */
+export type GatewayModels = ReadonlyArray<DevModel>
+
+/** The inputs of one build. */
+export interface CatalogInputs {
+  dev: DevCatalog
+  /** Extra model lists per provider id, for example OpenRouter's own API. */
+  gateways?: Readonly<Record<string, GatewayModels>>
+}
+
+/** Drop undefined fields, so the generated files stay small. */
+function compact<T extends object>(value: T): T {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, field]) => field !== undefined),
+  ) as T
+}
+
+const mergeCompat = (
+  ...parts: ReadonlyArray<ModelCompat | undefined>
+): ModelCompat | undefined => {
+  const merged: ModelCompat = Object.assign({}, ...parts)
+  return Object.keys(merged).length > 0 ? merged : undefined
+}
+
+/** Turn one models.dev model into a catalog record for `row`. */
+export function toRecord(
+  row: ProviderRow,
+  id: string,
+  model: DevModel,
+  sourceId: string,
+  borrowedFrom?: string,
+): ModelRecord {
+  const wire: Wire = row.wire?.({
+    id: sourceId,
+    ...(model.provider?.npm ? { npm: model.provider.npm } : {}),
+  }) ?? { api: row.api, baseUrl: row.baseUrl }
+  const reasoning = model.reasoning === true
+  const map = reasoning ? reasoningMapFrom(model.reasoning_options) : undefined
+  const budget = reasoning && takesBudget(model.reasoning_options)
+  const compat = mergeCompat(
+    row.compat,
+    row.modelCompat?.(id, wire),
+    modelHints(model, wire, row.effortByModel === true),
+  )
+  return compact({
+    id,
+    provider: row.id,
+    name: model.name ?? id,
+    api: wire.api,
+    baseUrl: wire.baseUrl,
+    input: inputModalities(model.modalities?.input),
+    reasoning,
+    reasoningMap: map,
+    reasoningBudget: budget || undefined,
+    cost: {
+      input: model.cost?.input ?? 0,
+      output: model.cost?.output ?? 0,
+      cacheRead: model.cost?.cache_read ?? 0,
+      cacheWrite: model.cost?.cache_write ?? 0,
+    },
+    contextWindow: model.limit?.context ?? 0,
+    maxTokens: model.limit?.output ?? 0,
+    headers: row.headers,
+    compat,
+    borrowedFrom,
+  })
+}
+
+/** Find `provider/model` in the catalog. Model ids can hold `/`. */
+function lookup(dev: DevCatalog, source: string): DevModel | undefined {
+  const slash = source.indexOf('/')
+  return dev[source.slice(0, slash)]?.models[source.slice(slash + 1)]
+}
+
+/** Every model of one provider, sorted by id. */
+export function buildModels(
+  row: ProviderRow,
+  inputs: CatalogInputs,
+): ReadonlyArray<ModelRecord> {
+  const records = new Map<string, ModelRecord>()
+  const only = ONLY[row.id]
+  const allowed = (id: string) => !only || only.includes(id)
+
+  for (const source of row.sources)
+    for (const [sourceId, model] of Object.entries(
+      inputs.dev[source]?.models ?? {},
+    )) {
+      const id = row.modelId?.(sourceId) ?? sourceId
+      if (records.has(id) || !allowed(id) || !makesText(model)) continue
+      records.set(id, toRecord(row, id, model, sourceId))
+    }
+
+  // The gateway's own list has models models.dev does not (for example
+  // OpenRouter's `:batch` variants).
+  for (const model of inputs.gateways?.[row.id] ?? []) {
+    if (records.has(model.id) || !makesText(model)) continue
+    records.set(model.id, toRecord(row, model.id, model, model.id))
+  }
+
+  for (const [id, source] of Object.entries(BORROW[row.id] ?? {})) {
+    if (records.has(id)) continue
+    const model = lookup(inputs.dev, source)
+    if (model) records.set(id, toRecord(row, id, model, id, source))
+  }
+
+  for (const extra of EXTRA_MODELS[row.id] ?? [])
+    if (!records.has(extra.id))
+      records.set(extra.id, {
+        provider: row.id,
+        api: row.api,
+        baseUrl: row.baseUrl,
+        ...(row.headers ? { headers: row.headers } : {}),
+        ...extra,
+      })
+
+  for (const [id, override] of Object.entries(MODEL_OVERRIDES[row.id] ?? {})) {
+    const record = records.get(id)
+    if (record) records.set(id, { ...record, ...override })
+  }
+
+  return [...records.values()].sort((a, b) => a.id.localeCompare(b.id))
+}
+
+/** The provider record of a row, with the wires its models use. */
+export function buildProvider(
+  row: ProviderRow,
+  models: ReadonlyArray<ModelRecord>,
+): ProviderRecord {
+  const apis = [...new Set<WireApi>([row.api, ...models.map((m) => m.api)])]
+  return {
+    id: row.id,
+    name: row.name,
+    baseUrl: row.baseUrl,
+    apis: apis.sort(),
+    env: row.env,
+  }
+}
diff --git a/packages/ai-models/scripts/known-ids.ts b/packages/ai-models/scripts/known-ids.ts
new file mode 100644
index 0000000000..a0eb81df49
--- /dev/null
+++ b/packages/ai-models/scripts/known-ids.ts
@@ -0,0 +1,250 @@
+// Model ids that the generator cannot find on its own. It compares with the
+// catalog of pi 0.87.1 (the models Flue users write today). Keep it by hand:
+// add an id here when a provider drops it from models.dev but still serves it.
+
+/** A model id at a provider, and the models.dev model to take its data from. */
+export const BORROW: Readonly<
+  Record<string, Readonly<Record<string, string>>>
+> = {
+  'ant-ling': {
+    'Ling-2.6-1T': 'novita-ai/inclusionai/ling-2.6-1t',
+    'Ling-2.6-flash': 'novita-ai/inclusionai/ling-2.6-flash',
+    'Ring-2.6-1T': 'novita-ai/inclusionai/ring-2.6-1t',
+  },
+  'azure-openai-responses': {
+    'gpt-4': 'openai/gpt-4',
+    'gpt-4o-2024-05-13': 'openai/gpt-4o-2024-05-13',
+    'gpt-4o-2024-08-06': 'openai/gpt-4o-2024-08-06',
+    'gpt-4o-2024-11-20': 'openai/gpt-4o-2024-11-20',
+    'gpt-5-chat-latest': 'jiekou/gpt-5-chat-latest',
+    'gpt-5.2-chat-latest': 'openai/gpt-5.2-chat-latest',
+    'gpt-5.2-pro': 'openai/gpt-5.2-pro',
+    'gpt-5.3-chat-latest': 'openai/gpt-5.3-chat-latest',
+    'gpt-5.3-codex-spark': 'openai/gpt-5.3-codex-spark',
+    'gpt-5.5-pro': 'openai/gpt-5.5-pro',
+    'gpt-realtime-2.1': 'openai/gpt-realtime-2.1',
+    'o1-pro': 'openai/o1-pro',
+    'o3-pro': 'openai/o3-pro',
+  },
+  'cloudflare-ai-gateway': {
+    'workers-ai/@cf/deepseek-ai/deepseek-v4-flash-0731':
+      'cloudflare-workers-ai/@cf/deepseek-ai/deepseek-v4-flash-0731',
+    'workers-ai/@cf/deepseek-ai/deepseek-v4-pro-0813':
+      'cloudflare-workers-ai/@cf/deepseek-ai/deepseek-v4-pro-0813',
+    'workers-ai/@cf/google/gemma-4-26b-a4b-it':
+      'cloudflare-workers-ai/@cf/google/gemma-4-26b-a4b-it',
+    'workers-ai/@cf/ibm-granite/granite-4.0-h-micro':
+      'cloudflare-workers-ai/@cf/ibm-granite/granite-4.0-h-micro',
+    'workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast':
+      'cloudflare-workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast',
+    'workers-ai/@cf/meta/llama-4-scout-17b-16e-instruct':
+      'cloudflare-workers-ai/@cf/meta/llama-4-scout-17b-16e-instruct',
+    'workers-ai/@cf/mistralai/mistral-small-3.1-24b-instruct':
+      'cloudflare-workers-ai/@cf/mistralai/mistral-small-3.1-24b-instruct',
+    'workers-ai/@cf/moonshotai/kimi-k2.6':
+      'cloudflare-workers-ai/@cf/moonshotai/kimi-k2.6',
+    'workers-ai/@cf/moonshotai/kimi-k2.7-code':
+      'cloudflare-workers-ai/@cf/moonshotai/kimi-k2.7-code',
+    'workers-ai/@cf/nvidia/nemotron-3-120b-a12b':
+      'cloudflare-workers-ai/@cf/nvidia/nemotron-3-120b-a12b',
+    'workers-ai/@cf/openai/gpt-oss-120b':
+      'cloudflare-workers-ai/@cf/openai/gpt-oss-120b',
+    'workers-ai/@cf/openai/gpt-oss-20b':
+      'cloudflare-workers-ai/@cf/openai/gpt-oss-20b',
+    'workers-ai/@cf/qwen/qwen3-30b-a3b-fp8':
+      'cloudflare-workers-ai/@cf/qwen/qwen3-30b-a3b-fp8',
+    'workers-ai/@cf/qwen/qwen3.8-27b':
+      'cloudflare-workers-ai/@cf/qwen/qwen3.8-27b',
+    'workers-ai/@cf/zai-org/glm-4.7-flash':
+      'cloudflare-workers-ai/@cf/zai-org/glm-4.7-flash',
+    'workers-ai/@cf/zai-org/glm-5.2':
+      'cloudflare-workers-ai/@cf/zai-org/glm-5.2',
+    'workers-ai/@cf/zai-org/glm-5.3':
+      'cloudflare-workers-ai/@cf/zai-org/glm-5.3',
+    'workers-ai/@cf/zai-org/glm-5.3-flash':
+      'cloudflare-workers-ai/@cf/zai-org/glm-5.3-flash',
+  },
+  fireworks: {
+    'accounts/fireworks/models/deepseek-v4-flash-0731':
+      'deepinfra/deepseek-ai/DeepSeek-V4-Flash-0731',
+    'accounts/fireworks/models/deepseek-v4-flash-vision-exp':
+      'deepseek/deepseek-v4-flash-vision-exp',
+    'accounts/fireworks/models/deepseek-v4-pro': 'deepseek/deepseek-v4-pro',
+    'accounts/fireworks/models/deepseek-v4-pro-0813':
+      'deepinfra/deepseek-ai/DeepSeek-V4-Pro-0813',
+    'accounts/fireworks/models/kimi-k2p6': 'moonshotai/kimi-k2.6',
+    'accounts/fireworks/models/kimi-k2p7-code': 'moonshotai/kimi-k2.7-code',
+    'accounts/fireworks/models/minimax-m2p7': 'minimax/MiniMax-M2.7',
+    'accounts/fireworks/models/muse-glimmer-30b':
+      'empiriolabs/muse-glimmer-30b',
+    'accounts/fireworks/models/qwen3p7-plus': 'alibaba/qwen3.7-plus',
+    'accounts/fireworks/routers/deepseek-pro-latest':
+      'kilo/~deepseek/deepseek-pro-latest',
+    'accounts/fireworks/models/glm-5p2': 'zai/glm-5.2',
+    'accounts/fireworks/routers/glm-5p2-fast': 'baseten/zai-org/GLM-5.2-Fast',
+  },
+  mistral: {
+    'mistral-medium-3.5': 'nano-gpt/mistralai/mistral-medium-3.5',
+  },
+  openai: {
+    'gpt-5-chat-latest': 'jiekou/gpt-5-chat-latest',
+  },
+  'opencode-go': {
+    'glm-5.1': 'zai/glm-5.1',
+  },
+  openrouter: {
+    'anthropic/claude-3-haiku': 'vercel/anthropic/claude-3-haiku',
+    auto: 'kilo/openrouter/auto',
+    'inclusionai/ling-3.0-flash-fin:free':
+      'kilo/inclusionai/ling-3.0-flash-fin',
+    'inclusionai/ling-3.0-flash-vl:free':
+      'nano-gpt/inclusionai/ling-3.0-flash-vl',
+    'nex-agi/nex-n2.5-mini:free': 'kilo/nex-agi/nex-n2.5-mini',
+    'nex-agi/nex-n2.5-pro:free': 'kilo/nex-agi/nex-n2.5-pro',
+  },
+  'qwen-token-plan': {
+    'MiniMax-M2.5': 'minimax/MiniMax-M2.5',
+    'deepseek-v3.2': 'deepinfra/deepseek-ai/DeepSeek-V3.2',
+    'deepseek-v4-flash': 'deepseek/deepseek-v4-flash',
+    'deepseek-v4-pro': 'deepseek/deepseek-v4-pro',
+    'deepseek-v4-pro-0813': 'deepinfra/deepseek-ai/DeepSeek-V4-Pro-0813',
+    'deepseek-v4.1-flash': 'deepinfra/deepseek-ai/DeepSeek-V4.1-Flash',
+    'glm-5': 'zai/glm-5',
+    'glm-5.1': 'zai/glm-5.1',
+    'glm-5.3': 'zai/glm-5.3',
+    'kimi-k2.5': 'deepinfra/moonshotai/Kimi-K2.5',
+    'kimi-k2.6': 'moonshotai/kimi-k2.6',
+    'kimi-k2.7-code': 'moonshotai/kimi-k2.7-code',
+  },
+  'qwen-token-plan-cn': {
+    'deepseek-v3.2': 'deepinfra/deepseek-ai/DeepSeek-V3.2',
+    'deepseek-v4-flash-0731': 'deepinfra/deepseek-ai/DeepSeek-V4-Flash-0731',
+    'deepseek-v4-pro-0813': 'deepinfra/deepseek-ai/DeepSeek-V4-Pro-0813',
+    'kimi-k2.7-code': 'moonshotai/kimi-k2.7-code',
+  },
+  'qwen-token-plan-individual': {
+    'deepseek-v4-pro': 'deepseek/deepseek-v4-pro',
+    'deepseek-v4-pro-0813': 'deepinfra/deepseek-ai/DeepSeek-V4-Pro-0813',
+  },
+  together: {
+    'moonshotai/Kimi-K2.6': 'moonshotai/kimi-k2.6',
+    'moonshotai/Kimi-K2.7-Code': 'moonshotai/kimi-k2.7-code',
+  },
+  'vercel-ai-gateway': {
+    'inclusionai/ling-3.0-flash-fin-free':
+      'kilo/inclusionai/ling-3.0-flash-fin',
+    'inclusionai/ling-3.0-flash-vl-free':
+      'nano-gpt/inclusionai/ling-3.0-flash-vl',
+  },
+  zai: {
+    'glm-5.2-highspeed': 'zai-coding-plan/glm-5.2-highspeed',
+    'glm-5.3-highspeed': 'zhipuai-coding-plan/glm-5.3-highspeed',
+  },
+}
+
+/**
+ * Plan providers that share a models.dev list with the full API but serve
+ * only some of its models. Only these ids are in the catalog.
+ */
+export const ONLY: Readonly<Record<string, ReadonlyArray<string>>> = {
+  'qwen-token-plan': [
+    'MiniMax-M2.5',
+    'deepseek-v3.2',
+    'deepseek-v4-flash',
+    'deepseek-v4-flash-0731',
+    'deepseek-v4-pro',
+    'deepseek-v4-pro-0813',
+    'deepseek-v4.1-flash',
+    'glm-5',
+    'glm-5.1',
+    'glm-5.2',
+    'glm-5.3',
+    'kimi-k2.5',
+    'kimi-k2.6',
+    'kimi-k2.7-code',
+    'qwen3.6-flash',
+    'qwen3.6-plus',
+    'qwen3.7-max',
+    'qwen3.7-plus',
+    'qwen3.8-flash',
+    'qwen3.8-max',
+  ],
+  'qwen-token-plan-cn': [
+    'MiniMax-M2.5',
+    'deepseek-v3.2',
+    'deepseek-v4-flash',
+    'deepseek-v4-flash-0731',
+    'deepseek-v4-pro',
+    'deepseek-v4-pro-0813',
+    'deepseek-v4.1-flash',
+    'glm-5',
+    'glm-5.1',
+    'glm-5.2',
+    'glm-5.3',
+    'kimi-k2.5',
+    'kimi-k2.6',
+    'kimi-k2.7-code',
+    'qwen3.6-flash',
+    'qwen3.6-plus',
+    'qwen3.7-max',
+    'qwen3.7-plus',
+    'qwen3.8-flash',
+    'qwen3.8-max',
+  ],
+  'qwen-token-plan-individual': [
+    'deepseek-v4-flash-0731',
+    'deepseek-v4-pro',
+    'deepseek-v4-pro-0813',
+    'glm-5.2',
+    'qwen3.6-flash',
+    'qwen3.7-max',
+    'qwen3.7-plus',
+    'qwen3.8-flash',
+    'qwen3.8-max',
+  ],
+  'xiaomi-token-plan-ams': [
+    'mimo-v2.5',
+    'mimo-v2.5-pro',
+    'mimo-v2.6-flash',
+    'mimo-v2.6-pro',
+  ],
+  'xiaomi-token-plan-cn': [
+    'mimo-v2.5',
+    'mimo-v2.5-pro',
+    'mimo-v2.6-flash',
+    'mimo-v2.6-pro',
+  ],
+  'xiaomi-token-plan-sgp': [
+    'mimo-v2.5',
+    'mimo-v2.5-pro',
+    'mimo-v2.6-flash',
+    'mimo-v2.6-pro',
+  ],
+}
+
+/** Fireworks models on its Anthropic Messages endpoint. The rest use Chat Completions. */
+export const FIREWORKS_ANTHROPIC_WIRE: ReadonlyArray<string> = [
+  'accounts/fireworks/models/deepseek-v4-flash-0731',
+  'accounts/fireworks/models/deepseek-v4-flash-vision-exp',
+  'accounts/fireworks/models/deepseek-v4-pro',
+  'accounts/fireworks/models/deepseek-v4-pro-0813',
+  'accounts/fireworks/models/deepseek-v4p1-flash',
+  'accounts/fireworks/models/gpt-oss-120b',
+  'accounts/fireworks/models/inkling',
+  'accounts/fireworks/models/kimi-k2p6',
+  'accounts/fireworks/models/kimi-k2p7-code',
+  'accounts/fireworks/models/minimax-m2p7',
+  'accounts/fireworks/models/minimax-m3',
+  'accounts/fireworks/models/muse-glimmer-30b',
+  'accounts/fireworks/models/nemotron-3-ultra-nvfp4',
+  'accounts/fireworks/models/nemotron-lightning-3p5-30b-a3b',
+  'accounts/fireworks/models/qwen3p7-plus',
+  'accounts/fireworks/models/qwen3p8-2p4t-a95b',
+  'accounts/fireworks/models/qwen3p8-max',
+  'accounts/fireworks/routers/deepseek-flash-latest',
+  'accounts/fireworks/routers/deepseek-pro-latest',
+  'accounts/fireworks/routers/kimi-fast-latest',
+  'accounts/fireworks/routers/kimi-latest',
+  'accounts/fireworks/routers/minimax-latest',
+  'accounts/fireworks/routers/qwen-max-latest',
+]
diff --git a/packages/ai-models/scripts/overrides.ts b/packages/ai-models/scripts/overrides.ts
new file mode 100644
index 0000000000..ea66304d03
--- /dev/null
+++ b/packages/ai-models/scripts/overrides.ts
@@ -0,0 +1,44 @@
+import type { ModelRecord } from '../src/types'
+
+/** A model record without the fields its provider row fills in. */
+export type ExtraModel = Omit<ModelRecord, 'provider' | 'api' | 'baseUrl'> &
+  Partial<Pick<ModelRecord, 'api' | 'baseUrl'>>
+
+/**
+ * Models that no source has, written by hand. Values from the provider's
+ * price page (as pi 0.87.1 lists them).
+ */
+export const EXTRA_MODELS: Readonly<Record<string, ReadonlyArray<ExtraModel>>> =
+  {
+    mistral: [
+      {
+        id: 'magistral-small',
+        name: 'Magistral Small',
+        input: ['text'],
+        reasoning: true,
+        cost: { input: 0.5, output: 1.5, cacheRead: 0.05, cacheWrite: 0 },
+        contextWindow: 128000,
+        maxTokens: 128000,
+      },
+    ],
+    openrouter: [
+      {
+        id: 'openrouter/auto-beta',
+        name: 'Auto Router (Beta)',
+        input: ['text', 'image'],
+        reasoning: true,
+        // The router picks a model per call, so the price is not known ahead.
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 2000000,
+        maxTokens: 4096,
+      },
+    ],
+  }
+
+/**
+ * Corrections for single models, merged over the generated record. Keep a
+ * comment on each one that says why.
+ */
+export const MODEL_OVERRIDES: Readonly<
+  Record<string, Readonly<Record<string, Partial<ModelRecord>>>>
+> = {}
diff --git a/packages/ai-models/scripts/providers.ts b/packages/ai-models/scripts/providers.ts
new file mode 100644
index 0000000000..7e361400c8
--- /dev/null
+++ b/packages/ai-models/scripts/providers.ts
@@ -0,0 +1,606 @@
+import { FIREWORKS_ANTHROPIC_WIRE } from './known-ids'
+import type { ModelCompat, WireApi } from '../src/types'
+
+/** Where one model is served: its wire protocol and endpoint. */
+export interface Wire {
+  api: WireApi
+  baseUrl: string
+}
+
+/** What a provider row can read from a models.dev model. */
+export interface SourceModel {
+  id: string
+  /** The AI SDK package models.dev lists for this model, when it differs from the provider's. */
+  npm?: string
+}
+
+/**
+ * One provider, by hand. The quirk rules follow pi's `detectCompat()`
+ * (`pi-ai/dist/api/openai-completions.js`) and the values pi sets on every
+ * model of the provider. Per-model hints come from models.dev (see
+ * `rules.ts`), and the model value wins.
+ */
+export interface ProviderRow {
+  id: string
+  name: string
+  /** models.dev provider ids to read models from. The first one wins on a clash. */
+  sources: ReadonlyArray<string>
+  baseUrl: string
+  env: ReadonlyArray<ReadonlyArray<string>>
+  /** Wire and endpoint per model. Default: `api` at `baseUrl`. */
+  api: WireApi
+  wire?: (model: SourceModel) => Wire
+  /** The model id the catalog uses, from the models.dev id. Default: the same. */
+  modelId?: (sourceId: string) => string
+  /** Quirks of every model of this provider. */
+  compat?: ModelCompat
+  /** Quirks of some models of this provider, by model id. */
+  modelCompat?: (id: string, wire: Wire) => ModelCompat | undefined
+  /** `true`: `supportsReasoningEffort` follows each model's `effort` option. */
+  effortByModel?: boolean
+  headers?: Readonly<Record<string, string>>
+}
+
+const completions = (baseUrl: string): Wire => ({
+  api: 'openai-completions',
+  baseUrl,
+})
+
+/** Chat Completions rules of the "non-standard" providers in pi's detectCompat. */
+const NON_STANDARD: ModelCompat = {
+  supportsStore: false,
+  supportsDeveloperRole: false,
+}
+
+/** A DeepSeek-family model on a gateway sends thinking the DeepSeek way. */
+const deepseekFamily = (id: string): ModelCompat | undefined =>
+  /deepseek/i.test(id)
+    ? {
+        thinkingFormat: 'deepseek',
+        requiresReasoningContentOnAssistantMessages: true,
+      }
+    : undefined
+
+/** OpenCode serves each model on the wire of the SDK models.dev lists. */
+const opencodeWire =
+  (root: string) =>
+  (model: SourceModel): Wire => {
+    if (model.npm === '@ai-sdk/anthropic')
+      return { api: 'anthropic-messages', baseUrl: root }
+    if (model.npm === '@ai-sdk/google')
+      return { api: 'google-generative-ai', baseUrl: `${root}/v1` }
+    if (model.npm === '@ai-sdk/openai')
+      return { api: 'openai-responses', baseUrl: `${root}/v1` }
+    return completions(`${root}/v1`)
+  }
+
+const opencodeCompat = (id: string, wire: Wire): ModelCompat | undefined => {
+  if (wire.api === 'openai-completions')
+    return {
+      ...NON_STANDARD,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      ...deepseekFamily(id),
+    }
+  if (wire.api === 'openai-responses')
+    return { sessionAffinityFormat: 'openai-nosession' }
+  return undefined
+}
+
+const CLOUDFLARE_GATEWAY =
+  'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}'
+
+export const PROVIDERS: ReadonlyArray<ProviderRow> = [
+  {
+    id: 'amazon-bedrock',
+    name: 'Amazon Bedrock',
+    sources: ['amazon-bedrock'],
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    api: 'bedrock-converse-stream',
+    // The `eu.` cross-region profiles run in eu-central-1.
+    wire: (model) => ({
+      api: 'bedrock-converse-stream',
+      baseUrl: model.id.startsWith('eu.')
+        ? 'https://bedrock-runtime.eu-central-1.amazonaws.com'
+        : 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    }),
+    env: [
+      ['AWS_PROFILE'],
+      ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY'],
+      ['AWS_BEARER_TOKEN_BEDROCK'],
+      ['AWS_CONTAINER_CREDENTIALS_RELATIVE_URI'],
+      ['AWS_CONTAINER_CREDENTIALS_FULL_URI'],
+      ['AWS_WEB_IDENTITY_TOKEN_FILE'],
+    ],
+  },
+  {
+    id: 'ant-ling',
+    name: 'Ant Ling',
+    sources: [],
+    baseUrl: 'https://api.ant-ling.com/v1',
+    api: 'openai-completions',
+    env: [['ANT_LING_API_KEY']],
+    compat: {
+      ...NON_STANDARD,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'ant-ling',
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+    },
+  },
+  {
+    id: 'anthropic',
+    name: 'Anthropic',
+    sources: ['anthropic'],
+    baseUrl: 'https://api.anthropic.com',
+    api: 'anthropic-messages',
+    env: [
+      ['ANTHROPIC_API_KEY'],
+      ['ANTHROPIC_OAUTH_TOKEN'],
+      ['ANTHROPIC_AUTH_TOKEN'],
+    ],
+    compat: { supportsStrictTools: true },
+  },
+  {
+    id: 'azure-openai-responses',
+    name: 'Azure OpenAI',
+    sources: ['azure'],
+    // Each Azure resource has its own endpoint.
+    baseUrl: '',
+    api: 'azure-openai-responses',
+    env: [['AZURE_OPENAI_API_KEY']],
+  },
+  {
+    id: 'baseten',
+    name: 'Baseten',
+    sources: ['baseten'],
+    baseUrl: 'https://inference.baseten.co/v1',
+    api: 'openai-completions',
+    env: [['BASETEN_API_KEY']],
+    effortByModel: true,
+    compat: {
+      ...NON_STANDARD,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+    },
+  },
+  {
+    id: 'cerebras',
+    name: 'Cerebras',
+    sources: ['cerebras'],
+    baseUrl: 'https://api.cerebras.ai/v1',
+    api: 'openai-completions',
+    env: [['CEREBRAS_API_KEY']],
+    compat: NON_STANDARD,
+  },
+  {
+    id: 'cloudflare-ai-gateway',
+    name: 'Cloudflare AI Gateway',
+    sources: ['cloudflare-ai-gateway'],
+    baseUrl: `${CLOUDFLARE_GATEWAY}/compat`,
+    api: 'openai-completions',
+    env: [['CLOUDFLARE_API_KEY']],
+    // Claude and OpenAI models have their own routes, and pi drops the
+    // vendor part of their id. Every other model goes through `/compat`.
+    modelId: (id) => id.replace(/^(anthropic|openai)\//, ''),
+    wire: (model) => {
+      if (model.id.startsWith('anthropic/'))
+        return {
+          api: 'anthropic-messages',
+          baseUrl: `${CLOUDFLARE_GATEWAY}/anthropic`,
+        }
+      if (model.id.startsWith('openai/'))
+        return {
+          api: 'openai-responses',
+          baseUrl: `${CLOUDFLARE_GATEWAY}/openai`,
+        }
+      return completions(`${CLOUDFLARE_GATEWAY}/compat`)
+    },
+    compat: { sendSessionAffinityHeaders: true },
+    modelCompat: (id, wire) =>
+      wire.api === 'openai-completions'
+        ? {
+            ...NON_STANDARD,
+            supportsReasoningEffort: false,
+            maxTokensField: 'max_tokens',
+            supportsLongCacheRetention: false,
+            ...deepseekFamily(id),
+          }
+        : wire.api === 'openai-responses'
+          ? { supportsStrictMode: true, sendSessionAffinityHeaders: false }
+          : undefined,
+  },
+  {
+    id: 'cloudflare-workers-ai',
+    name: 'Cloudflare Workers AI',
+    sources: ['cloudflare-workers-ai'],
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    api: 'openai-completions',
+    env: [['CLOUDFLARE_API_KEY']],
+    compat: {
+      ...NON_STANDARD,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+    modelCompat: deepseekFamily,
+  },
+  {
+    id: 'deepseek',
+    name: 'DeepSeek',
+    sources: ['deepseek'],
+    baseUrl: 'https://api.deepseek.com',
+    api: 'openai-completions',
+    env: [['DEEPSEEK_API_KEY']],
+    compat: {
+      ...NON_STANDARD,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+      supportsStrictMode: true,
+    },
+  },
+  {
+    id: 'fireworks',
+    name: 'Fireworks AI',
+    sources: ['fireworks-ai'],
+    baseUrl: 'https://api.fireworks.ai/inference/v1',
+    api: 'openai-completions',
+    env: [['FIREWORKS_API_KEY']],
+    wire: (model) =>
+      FIREWORKS_ANTHROPIC_WIRE.includes(model.id)
+        ? {
+            api: 'anthropic-messages',
+            baseUrl: 'https://api.fireworks.ai/inference',
+          }
+        : completions('https://api.fireworks.ai/inference/v1'),
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+    },
+    modelCompat: (id, wire) =>
+      wire.api === 'anthropic-messages'
+        ? {
+            allowEmptySignature: true,
+            supportsEagerToolInputStreaming: false,
+            supportsCacheControlOnTools: false,
+          }
+        : { ...NON_STANDARD, supportsStrictMode: true, ...deepseekFamily(id) },
+  },
+  {
+    id: 'google',
+    name: 'Google',
+    sources: ['google'],
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    api: 'google-generative-ai',
+    env: [['GEMINI_API_KEY']],
+  },
+  {
+    id: 'google-vertex',
+    name: 'Google Vertex AI',
+    sources: ['google-vertex'],
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    api: 'google-vertex',
+    // An API key, or Application Default Credentials with a project and a location.
+    env: [
+      ['GOOGLE_CLOUD_API_KEY'],
+      [
+        'GOOGLE_APPLICATION_CREDENTIALS',
+        'GOOGLE_CLOUD_PROJECT',
+        'GOOGLE_CLOUD_LOCATION',
+      ],
+      [
+        'GOOGLE_APPLICATION_CREDENTIALS',
+        'GCLOUD_PROJECT',
+        'GOOGLE_CLOUD_LOCATION',
+      ],
+    ],
+  },
+  {
+    id: 'groq',
+    name: 'Groq',
+    sources: ['groq'],
+    baseUrl: 'https://api.groq.com/openai/v1',
+    api: 'openai-completions',
+    env: [['GROQ_API_KEY']],
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'huggingface',
+    name: 'Hugging Face',
+    sources: ['huggingface'],
+    baseUrl: 'https://router.huggingface.co/v1',
+    api: 'openai-completions',
+    env: [['HF_TOKEN']],
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'kimi-coding',
+    name: 'Kimi For Coding',
+    sources: ['kimi-code-plan-global', 'kimi-code-plan-cn'],
+    baseUrl: 'https://api.kimi.com/coding',
+    api: 'anthropic-messages',
+    env: [['KIMI_API_KEY']],
+    compat: { forceAdaptiveThinking: true },
+  },
+  {
+    id: 'meta',
+    name: 'Meta',
+    sources: ['meta'],
+    baseUrl: 'https://api.meta.ai/v1',
+    api: 'openai-responses',
+    env: [['META_API_KEY']],
+  },
+  {
+    id: 'minimax',
+    name: 'MiniMax',
+    sources: ['minimax'],
+    baseUrl: 'https://api.minimax.io/anthropic',
+    api: 'anthropic-messages',
+    env: [['MINIMAX_API_KEY']],
+  },
+  {
+    id: 'minimax-cn',
+    name: 'MiniMax (China)',
+    sources: ['minimax-cn'],
+    baseUrl: 'https://api.minimaxi.com/anthropic',
+    api: 'anthropic-messages',
+    env: [['MINIMAX_CN_API_KEY']],
+  },
+  {
+    id: 'mistral',
+    name: 'Mistral',
+    sources: ['mistral'],
+    baseUrl: 'https://api.mistral.ai',
+    api: 'mistral-conversations',
+    env: [['MISTRAL_API_KEY']],
+  },
+  ...(['moonshotai', 'moonshotai-cn'] as const).map(
+    (id): ProviderRow => ({
+      id,
+      name: id === 'moonshotai' ? 'Moonshot AI' : 'Moonshot AI (China)',
+      sources: [id],
+      baseUrl:
+        id === 'moonshotai'
+          ? 'https://api.moonshot.ai/v1'
+          : 'https://api.moonshot.cn/v1',
+      api: 'openai-completions',
+      env: [['MOONSHOT_API_KEY']],
+      effortByModel: true,
+      compat: {
+        ...NON_STANDARD,
+        maxTokensField: 'max_tokens',
+        supportsStrictMode: false,
+        supportsMidConvoSystemMessages: true,
+        thinkingFormat: 'deepseek',
+      },
+    }),
+  ),
+  {
+    id: 'nvidia',
+    name: 'NVIDIA',
+    sources: ['nvidia'],
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    api: 'openai-completions',
+    env: [['NVIDIA_API_KEY']],
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      ...NON_STANDARD,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'openai',
+    name: 'OpenAI',
+    sources: ['openai'],
+    baseUrl: 'https://api.openai.com/v1',
+    api: 'openai-responses',
+    env: [['OPENAI_API_KEY']],
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'opencode',
+    name: 'OpenCode Zen',
+    sources: ['opencode'],
+    baseUrl: 'https://opencode.ai/zen/v1',
+    api: 'openai-completions',
+    env: [['OPENCODE_API_KEY']],
+    wire: opencodeWire('https://opencode.ai/zen'),
+    modelCompat: opencodeCompat,
+  },
+  {
+    id: 'opencode-go',
+    name: 'OpenCode Go',
+    sources: ['opencode-go'],
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    api: 'openai-completions',
+    env: [['OPENCODE_API_KEY']],
+    wire: opencodeWire('https://opencode.ai/zen/go'),
+    modelCompat: opencodeCompat,
+  },
+  {
+    id: 'openrouter',
+    name: 'OpenRouter',
+    sources: ['openrouter'],
+    baseUrl: 'https://openrouter.ai/api/v1',
+    api: 'openai-completions',
+    env: [['OPENROUTER_API_KEY']],
+    // Claude goes through OpenRouter's Anthropic Messages endpoint. Its
+    // `:batch` variants are Chat Completions only.
+    wire: (model) =>
+      model.id.startsWith('anthropic/') && !model.id.endsWith(':batch')
+        ? { api: 'anthropic-messages', baseUrl: 'https://openrouter.ai/api' }
+        : completions('https://openrouter.ai/api/v1'),
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+    },
+    modelCompat: (id) => ({
+      supportsDeveloperRole: /^(anthropic|openai)\//.test(id),
+      ...(id.startsWith('anthropic/')
+        ? { cacheControlFormat: 'anthropic' as const }
+        : {}),
+    }),
+  },
+  ...(
+    [
+      [
+        'qwen-token-plan',
+        'Qwen Token Plan',
+        'alibaba',
+        'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+        'QWEN_TOKEN_PLAN_API_KEY',
+      ],
+      [
+        'qwen-token-plan-cn',
+        'Qwen Token Plan (China)',
+        'alibaba-cn',
+        'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+        'QWEN_TOKEN_PLAN_CN_API_KEY',
+      ],
+      [
+        'qwen-token-plan-individual',
+        'Qwen Token Plan (Individual)',
+        'alibaba',
+        'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+        'QWEN_TOKEN_PLAN_API_KEY',
+      ],
+    ] as const
+  ).map(
+    ([id, name, source, baseUrl, key]): ProviderRow => ({
+      id,
+      name,
+      sources: [source],
+      baseUrl,
+      api: 'openai-completions',
+      env: [[key]],
+      effortByModel: true,
+      compat: {
+        ...NON_STANDARD,
+        supportsStrictMode: true,
+        thinkingFormat: 'qwen',
+      },
+    }),
+  ),
+  {
+    id: 'together',
+    name: 'Together AI',
+    sources: ['togetherai'],
+    baseUrl: 'https://api.together.ai/v1',
+    api: 'openai-completions',
+    env: [['TOGETHER_API_KEY']],
+    compat: {
+      ...NON_STANDARD,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'vercel-ai-gateway',
+    name: 'Vercel AI Gateway',
+    sources: ['vercel'],
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    api: 'anthropic-messages',
+    env: [['AI_GATEWAY_API_KEY']],
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'xai',
+    name: 'xAI',
+    sources: ['xai'],
+    baseUrl: 'https://api.x.ai/v1',
+    api: 'openai-responses',
+    env: [['XAI_API_KEY']],
+    compat: { supportsLongCacheRetention: false },
+  },
+  ...(
+    [
+      [
+        'xiaomi',
+        'Xiaomi MiMo',
+        'https://api.xiaomimimo.com/v1',
+        'XIAOMI_API_KEY',
+      ],
+      [
+        'xiaomi-token-plan-ams',
+        'Xiaomi MiMo Token Plan (Amsterdam)',
+        'https://token-plan-ams.xiaomimimo.com/v1',
+        'XIAOMI_TOKEN_PLAN_AMS_API_KEY',
+      ],
+      [
+        'xiaomi-token-plan-cn',
+        'Xiaomi MiMo Token Plan (China)',
+        'https://token-plan-cn.xiaomimimo.com/v1',
+        'XIAOMI_TOKEN_PLAN_CN_API_KEY',
+      ],
+      [
+        'xiaomi-token-plan-sgp',
+        'Xiaomi MiMo Token Plan (Singapore)',
+        'https://token-plan-sgp.xiaomimimo.com/v1',
+        'XIAOMI_TOKEN_PLAN_SGP_API_KEY',
+      ],
+    ] as const
+  ).map(
+    ([id, name, baseUrl, key]): ProviderRow => ({
+      id,
+      name,
+      sources: ['xiaomi'],
+      baseUrl,
+      api: 'openai-completions',
+      env: [[key]],
+      compat: {
+        supportsStrictMode: true,
+        requiresReasoningContentOnAssistantMessages: true,
+        thinkingFormat: 'deepseek',
+      },
+    }),
+  ),
+  ...(
+    [
+      [
+        'zai',
+        'Z.AI',
+        ['zai'],
+        'https://api.z.ai/api/coding/paas/v4',
+        'ZAI_API_KEY',
+      ],
+      [
+        'zai-coding-cn',
+        'Zhipu AI Coding Plan',
+        ['zhipuai-coding-plan', 'zai-coding-plan'],
+        'https://open.bigmodel.cn/api/coding/paas/v4',
+        'ZAI_CODING_CN_API_KEY',
+      ],
+    ] as const
+  ).map(
+    ([id, name, sources, baseUrl, key]): ProviderRow => ({
+      id,
+      name,
+      sources,
+      baseUrl,
+      api: 'openai-completions',
+      env: [[key]],
+      effortByModel: true,
+      compat: {
+        ...NON_STANDARD,
+        maxTokensField: 'max_tokens',
+        thinkingFormat: 'zai',
+        supportsStrictMode: true,
+        zaiToolStream: true,
+      },
+    }),
+  ),
+]
diff --git a/packages/ai-models/scripts/rules.ts b/packages/ai-models/scripts/rules.ts
new file mode 100644
index 0000000000..0057245cda
--- /dev/null
+++ b/packages/ai-models/scripts/rules.ts
@@ -0,0 +1,200 @@
+import type { Wire } from './providers'
+import type {
+  InputModality,
+  ModelCompat,
+  ReasoningLevel,
+  ReasoningMap,
+} from '../src/types'
+
+/** One entry of models.dev `reasoning_options`. */
+export type ReasoningOptionEntry =
+  | { type: 'effort'; values?: ReadonlyArray<string> }
+  | { type: 'toggle' }
+  | { type: 'budget_tokens'; min?: number; max?: number }
+  | { type: string }
+
+/** The fields of a models.dev model that the generator reads. */
+export interface DevModel {
+  id: string
+  name?: string
+  reasoning?: boolean
+  reasoning_options?: ReadonlyArray<ReasoningOptionEntry>
+  interleaved?: boolean | { field?: string }
+  temperature?: boolean
+  modalities?: {
+    input?: ReadonlyArray<string>
+    output?: ReadonlyArray<string>
+  }
+  cost?: {
+    input?: number
+    output?: number
+    cache_read?: number
+    cache_write?: number
+  }
+  limit?: { context?: number; output?: number }
+  provider?: { npm?: string; api?: string }
+  canonical_model_id?: string
+  status?: string
+}
+
+const THINKING_LEVELS: ReadonlyArray<Exclude<ReasoningLevel, 'off'>> = [
+  'minimal',
+  'low',
+  'medium',
+  'high',
+  'xhigh',
+  'max',
+]
+
+const effortValues = (
+  options: ReadonlyArray<ReasoningOptionEntry>,
+): ReadonlyArray<string> | undefined => {
+  const effort = options.find((option) => option.type === 'effort')
+  if (!effort || !('values' in effort)) return undefined
+  return effort.values
+}
+
+/**
+ * The level map from models.dev `reasoning_options`:
+ * - `effort` values: each value names its level, `none` is the `off` value,
+ *   and a level the model does not list is `null`. A `toggle` next to it
+ *   also gives `off: 'none'`.
+ * - `toggle` alone: only `off` and `high`.
+ * - `budget_tokens` alone, or nothing: no map (every level up to `high`
+ *   passes, and the adapter turns it into a budget).
+ */
+export function reasoningMapFrom(
+  options: ReadonlyArray<ReasoningOptionEntry> | undefined,
+): ReasoningMap | undefined {
+  if (!options || options.length === 0) return undefined
+  const values = effortValues(options)
+  const toggle = options.some((option) => option.type === 'toggle')
+  if (values && values.length > 0) {
+    const map: ReasoningMap = {
+      off: values.includes('none') || toggle ? 'none' : null,
+    }
+    for (const level of THINKING_LEVELS)
+      map[level] = values.includes(level) ? level : null
+    return map
+  }
+  if (toggle)
+    return { off: 'off', minimal: null, low: null, medium: null, high: 'high' }
+  return undefined
+}
+
+/** `true` when the model takes a thinking token budget. */
+export function takesBudget(
+  options: ReadonlyArray<ReasoningOptionEntry> | undefined,
+): boolean {
+  return (options ?? []).some((option) => option.type === 'budget_tokens')
+}
+
+/** The model hints models.dev has for the wire quirks. */
+export function modelHints(
+  model: DevModel,
+  wire: Wire,
+  effortByModel: boolean,
+): ModelCompat {
+  const hints: ModelCompat = {}
+  const interleaved = model.interleaved
+  const replayField =
+    typeof interleaved === 'object' ? interleaved.field : undefined
+  if (wire.api === 'openai-completions' && replayField === 'reasoning_content')
+    hints.requiresReasoningContentOnAssistantMessages = true
+  if (model.temperature === false) hints.supportsTemperature = false
+  const options = model.reasoning_options ?? []
+  // Claude with `effort` and no token budget thinks adaptively only.
+  if (
+    wire.api === 'anthropic-messages' &&
+    effortValues(options) !== undefined &&
+    !takesBudget(options)
+  )
+    hints.forceAdaptiveThinking = true
+  if (effortByModel && wire.api === 'openai-completions')
+    hints.supportsReasoningEffort = (effortValues(options)?.length ?? 0) > 0
+  return hints
+}
+
+const INPUTS: ReadonlyArray<InputModality> = [
+  'text',
+  'image',
+  'audio',
+  'video',
+  'document',
+]
+
+/** models.dev input kinds, in the catalog's names. `pdf` and `file` are documents. */
+export function inputModalities(
+  input: ReadonlyArray<string> | undefined,
+): ReadonlyArray<InputModality> {
+  const mapped = (input ?? ['text']).map((kind) =>
+    kind === 'pdf' || kind === 'file' ? 'document' : kind,
+  )
+  const known = INPUTS.filter((kind) => mapped.includes(kind))
+  return known.length > 0 ? known : ['text']
+}
+
+/** A model that makes text (not only images, speech, or embeddings). */
+export function makesText(model: DevModel): boolean {
+  return (model.modalities?.output ?? ['text']).includes('text')
+}
+
+/**
+ * The form of a model id used to find the same model at another provider:
+ * the last path part, in lower case, with no `:free` or `:batch`, and with
+ * dots and `p` version separators as dashes (`4.5` and `k2p6` match `4-5`
+ * and `k2-6`).
+ */
+export function normalizeModelId(id: string): string {
+  return (id.split('/').pop() ?? id)
+    .toLowerCase()
+    .replace(/:(free|batch)$/, '')
+    .replace(/-free$/, '')
+    .replace(/(\d)p(\d)/g, '$1-$2')
+    .replace(/\./g, '-')
+}
+
+/** The model maker to prefer when the same model is at many providers. */
+const MAKERS: ReadonlyArray<readonly [RegExp, ReadonlyArray<string>]> = [
+  [/claude/i, ['anthropic']],
+  [/^(gpt|o\d|chatgpt|codex)/i, ['openai']],
+  [/gemini|gemma/i, ['google']],
+  [/deepseek/i, ['deepseek']],
+  [/kimi/i, ['moonshotai']],
+  [/glm/i, ['zai']],
+  [/minimax/i, ['minimax']],
+  [/mistral|magistral|codestral|ministral|devstral/i, ['mistral']],
+  [/grok/i, ['xai']],
+  [/qwen/i, ['alibaba']],
+]
+
+/**
+ * The same model at another provider: by the normalized id, else by
+ * `canonical_model_id`. The model maker wins over a reseller.
+ */
+export function findSameModel(
+  dev: Readonly<Record<string, { models: Readonly<Record<string, DevModel>> }>>,
+  id: string,
+): { source: string; model: DevModel } | undefined {
+  const key = normalizeModelId(id)
+  const byId: Array<{ source: string; model: DevModel }> = []
+  const byCanonical: Array<{ source: string; model: DevModel }> = []
+  for (const [provider, { models }] of Object.entries(dev))
+    for (const [modelId, model] of Object.entries(models)) {
+      if (normalizeModelId(modelId) === key)
+        byId.push({ source: `${provider}/${modelId}`, model })
+      else if (
+        model.canonical_model_id &&
+        normalizeModelId(model.canonical_model_id) === key
+      )
+        byCanonical.push({ source: `${provider}/${modelId}`, model })
+    }
+  const hits = byId.length > 0 ? byId : byCanonical
+  const name = id.split('/').pop() ?? id
+  const makers = MAKERS.find(([pattern]) => pattern.test(name))?.[1] ?? []
+  for (const maker of makers) {
+    const hit = hits.find((entry) => entry.source.startsWith(`${maker}/`))
+    if (hit) return hit
+  }
+  return hits[0]
+}
diff --git a/packages/ai-models/src/catalog.ts b/packages/ai-models/src/catalog.ts
new file mode 100644
index 0000000000..71b3773e09
--- /dev/null
+++ b/packages/ai-models/src/catalog.ts
@@ -0,0 +1,84 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import * as amazonBedrock from './providers/amazon-bedrock'
+import * as antLing from './providers/ant-ling'
+import * as anthropic from './providers/anthropic'
+import * as azureOpenaiResponses from './providers/azure-openai-responses'
+import * as baseten from './providers/baseten'
+import * as cerebras from './providers/cerebras'
+import * as cloudflareAiGateway from './providers/cloudflare-ai-gateway'
+import * as cloudflareWorkersAi from './providers/cloudflare-workers-ai'
+import * as deepseek from './providers/deepseek'
+import * as fireworks from './providers/fireworks'
+import * as google from './providers/google'
+import * as googleVertex from './providers/google-vertex'
+import * as groq from './providers/groq'
+import * as huggingface from './providers/huggingface'
+import * as kimiCoding from './providers/kimi-coding'
+import * as meta from './providers/meta'
+import * as minimax from './providers/minimax'
+import * as minimaxCn from './providers/minimax-cn'
+import * as mistral from './providers/mistral'
+import * as moonshotai from './providers/moonshotai'
+import * as moonshotaiCn from './providers/moonshotai-cn'
+import * as nvidia from './providers/nvidia'
+import * as openai from './providers/openai'
+import * as opencode from './providers/opencode'
+import * as opencodeGo from './providers/opencode-go'
+import * as openrouter from './providers/openrouter'
+import * as qwenTokenPlan from './providers/qwen-token-plan'
+import * as qwenTokenPlanCn from './providers/qwen-token-plan-cn'
+import * as qwenTokenPlanIndividual from './providers/qwen-token-plan-individual'
+import * as together from './providers/together'
+import * as vercelAiGateway from './providers/vercel-ai-gateway'
+import * as xai from './providers/xai'
+import * as xiaomi from './providers/xiaomi'
+import * as xiaomiTokenPlanAms from './providers/xiaomi-token-plan-ams'
+import * as xiaomiTokenPlanCn from './providers/xiaomi-token-plan-cn'
+import * as xiaomiTokenPlanSgp from './providers/xiaomi-token-plan-sgp'
+import * as zai from './providers/zai'
+import * as zaiCodingCn from './providers/zai-coding-cn'
+
+/** The day the catalog was generated, as `YYYY-MM-DD`. */
+export const generatedAt = '2026-09-30'
+
+/** Every provider module, in id order. */
+export const providerModules = [
+  amazonBedrock,
+  antLing,
+  anthropic,
+  azureOpenaiResponses,
+  baseten,
+  cerebras,
+  cloudflareAiGateway,
+  cloudflareWorkersAi,
+  deepseek,
+  fireworks,
+  google,
+  googleVertex,
+  groq,
+  huggingface,
+  kimiCoding,
+  meta,
+  minimax,
+  minimaxCn,
+  mistral,
+  moonshotai,
+  moonshotaiCn,
+  nvidia,
+  openai,
+  opencode,
+  opencodeGo,
+  openrouter,
+  qwenTokenPlan,
+  qwenTokenPlanCn,
+  qwenTokenPlanIndividual,
+  together,
+  vercelAiGateway,
+  xai,
+  xiaomi,
+  xiaomiTokenPlanAms,
+  xiaomiTokenPlanCn,
+  xiaomiTokenPlanSgp,
+  zai,
+  zaiCodingCn,
+]
diff --git a/packages/ai-models/src/cost.ts b/packages/ai-models/src/cost.ts
new file mode 100644
index 0000000000..5e79fd481f
--- /dev/null
+++ b/packages/ai-models/src/cost.ts
@@ -0,0 +1,23 @@
+import type { Cost, ModelRecord, TokenCounts } from './types'
+
+/**
+ * What a call cost in USD: each price is per 1M tokens, so the cost of a part
+ * is `price / 1_000_000 * tokens`.
+ */
+export function modelCost(
+  model: Pick<ModelRecord, 'cost'>,
+  usage: TokenCounts,
+): Cost {
+  const part = (price: number, tokens = 0) => (price / 1_000_000) * tokens
+  const input = part(model.cost.input, usage.input)
+  const output = part(model.cost.output, usage.output)
+  const cacheRead = part(model.cost.cacheRead, usage.cacheRead)
+  const cacheWrite = part(model.cost.cacheWrite, usage.cacheWrite)
+  return {
+    input,
+    output,
+    cacheRead,
+    cacheWrite,
+    total: input + output + cacheRead + cacheWrite,
+  }
+}
diff --git a/packages/ai-models/src/index.ts b/packages/ai-models/src/index.ts
new file mode 100644
index 0000000000..11cdbc144d
--- /dev/null
+++ b/packages/ai-models/src/index.ts
@@ -0,0 +1,40 @@
+import { generatedAt, providerModules } from './catalog'
+import type { ModelRecord, ProviderRecord } from './types'
+
+export { generatedAt }
+export { clampReasoningLevel, supportedReasoningLevels } from './reasoning'
+export { modelCost } from './cost'
+export type {
+  Cost,
+  InputModality,
+  ModelCompat,
+  ModelCostRates,
+  ModelRecord,
+  ProviderRecord,
+  ReasoningLevel,
+  ReasoningMap,
+  ThinkingFormat,
+  TokenCounts,
+  WireApi,
+} from './types'
+
+/** Every provider, in id order. */
+export function getProviders(): ReadonlyArray<ProviderRecord> {
+  return providerModules.map((module) => module.provider)
+}
+
+/** Every model of a provider, sorted by id. Empty for an unknown provider. */
+export function getModels(providerId: string): ReadonlyArray<ModelRecord> {
+  return (
+    providerModules.find((module) => module.provider.id === providerId)
+      ?.models ?? []
+  )
+}
+
+/** One model, or `undefined` when the catalog does not have it. */
+export function getModel(
+  providerId: string,
+  modelId: string,
+): ModelRecord | undefined {
+  return getModels(providerId).find((model) => model.id === modelId)
+}
diff --git a/packages/ai-models/src/providers/amazon-bedrock.ts b/packages/ai-models/src/providers/amazon-bedrock.ts
new file mode 100644
index 0000000000..625115bdbc
--- /dev/null
+++ b/packages/ai-models/src/providers/amazon-bedrock.ts
@@ -0,0 +1,3385 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Amazon Bedrock. */
+export const provider: ProviderRecord = {
+  id: 'amazon-bedrock',
+  name: 'Amazon Bedrock',
+  baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+  apis: ['bedrock-converse-stream'],
+  env: [
+    ['AWS_PROFILE'],
+    ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY'],
+    ['AWS_BEARER_TOKEN_BEDROCK'],
+    ['AWS_CONTAINER_CREDENTIALS_RELATIVE_URI'],
+    ['AWS_CONTAINER_CREDENTIALS_FULL_URI'],
+    ['AWS_WEB_IDENTITY_TOKEN_FILE'],
+  ],
+}
+
+/** Every Amazon Bedrock model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'amazon.nova-2-lite-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova 2 Lite',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.33, output: 2.75, cacheRead: 0.0825, cacheWrite: 0.33 },
+    contextWindow: 1000000,
+    maxTokens: 65535,
+  },
+  {
+    id: 'amazon.nova-lite-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova Lite',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: false,
+    cost: { input: 0.06, output: 0.24, cacheRead: 0.015, cacheWrite: 0.06 },
+    contextWindow: 300000,
+    maxTokens: 10000,
+  },
+  {
+    id: 'amazon.nova-micro-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova Micro',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.035, output: 0.14, cacheRead: 0.00875, cacheWrite: 0.035 },
+    contextWindow: 128000,
+    maxTokens: 10000,
+  },
+  {
+    id: 'amazon.nova-pro-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova Pro',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: false,
+    cost: { input: 0.8, output: 3.2, cacheRead: 0.2, cacheWrite: 0.8 },
+    contextWindow: 300000,
+    maxTokens: 10000,
+  },
+  {
+    id: 'anthropic.claude-fable-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Fable 5',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'anthropic.claude-fable-5-1',
+    provider: 'amazon-bedrock',
+    name: 'Claude Fable 5.1',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 0.25, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'anthropic.claude-haiku-4-5-20251001-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Haiku 4.5',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'anthropic.claude-opus-4-1-20250805-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.1',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+    contextWindow: 200000,
+    maxTokens: 32000,
+  },
+  {
+    id: 'anthropic.claude-opus-4-5-20251101-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.5',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'anthropic.claude-opus-4-6-v1',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.6',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'anthropic.claude-opus-4-7',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.7',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'anthropic.claude-opus-4-8',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.8',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'anthropic.claude-opus-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 5',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'anthropic.claude-opus-5-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 5.5',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.2, cacheWrite: 5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'anthropic.claude-sonnet-4-5-20250929-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 4.5',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'anthropic.claude-sonnet-4-6',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 4.6',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 3.3, output: 16.5, cacheRead: 0.33, cacheWrite: 4.125 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'anthropic.claude-sonnet-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 5',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'anthropic.claude-sonnet-5-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 5.5',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'apac.amazon.nova-lite-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova Lite (APAC)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: false,
+    cost: {
+      input: 0.063,
+      output: 0.252,
+      cacheRead: 0.01575,
+      cacheWrite: 0.063,
+    },
+    contextWindow: 300000,
+    maxTokens: 10000,
+  },
+  {
+    id: 'apac.amazon.nova-micro-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova Micro (APAC)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: false,
+    cost: {
+      input: 0.037,
+      output: 0.148,
+      cacheRead: 0.00925,
+      cacheWrite: 0.037,
+    },
+    contextWindow: 128000,
+    maxTokens: 10000,
+  },
+  {
+    id: 'apac.amazon.nova-pro-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova Pro (APAC)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: false,
+    cost: { input: 0.84, output: 3.36, cacheRead: 0.21, cacheWrite: 0.84 },
+    contextWindow: 300000,
+    maxTokens: 10000,
+  },
+  {
+    id: 'apac.anthropic.claude-sonnet-4-20250514-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 4 (APAC)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'au.anthropic.claude-haiku-4-5-20251001-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Haiku 4.5 (AU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 1.1, output: 5.5, cacheRead: 0.11, cacheWrite: 1.375 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'au.anthropic.claude-opus-4-6-v1',
+    provider: 'amazon-bedrock',
+    name: 'AU Anthropic Claude Opus 4.6',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'au.anthropic.claude-opus-4-7',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.7 (AU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'au.anthropic.claude-opus-4-8',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.8 (AU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'au.anthropic.claude-opus-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 5 (AU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'au.anthropic.claude-opus-5-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 5.5 (AU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4.4, output: 22, cacheRead: 0.22, cacheWrite: 5.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'au.anthropic.claude-sonnet-4-5-20250929-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 4.5 (AU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 3.3, output: 16.5, cacheRead: 0.33, cacheWrite: 4.125 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'au.anthropic.claude-sonnet-4-6',
+    provider: 'amazon-bedrock',
+    name: 'AU Anthropic Claude Sonnet 4.6',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 3.3, output: 16.5, cacheRead: 0.33, cacheWrite: 4.125 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'au.anthropic.claude-sonnet-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 5 (AU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2.2, output: 11, cacheRead: 0.22, cacheWrite: 2.75 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'ca.amazon.nova-lite-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova Lite (CA)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: false,
+    cost: { input: 0.064, output: 0.256, cacheRead: 0.016, cacheWrite: 0.064 },
+    contextWindow: 300000,
+    maxTokens: 10000,
+  },
+  {
+    id: 'deepseek.r1-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'DeepSeek-R1',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 1.35, output: 5.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 32768,
+  },
+  {
+    id: 'deepseek.v3-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'DeepSeek-V3.1',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.58, output: 1.68, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 81920,
+  },
+  {
+    id: 'deepseek.v3.2',
+    provider: 'amazon-bedrock',
+    name: 'DeepSeek V3.2',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.62, output: 1.85, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 81920,
+  },
+  {
+    id: 'eu.amazon.nova-2-lite-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova 2 Lite (EU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.eu-central-1.amazonaws.com',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.374, output: 3.157, cacheRead: 0.0935, cacheWrite: 0.374 },
+    contextWindow: 1000000,
+    maxTokens: 65535,
+  },
+  {
+    id: 'eu.amazon.nova-lite-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova Lite (EU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.eu-central-1.amazonaws.com',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: false,
+    cost: {
+      input: 0.069,
+      output: 0.276,
+      cacheRead: 0.01725,
+      cacheWrite: 0.069,
+    },
+    contextWindow: 300000,
+    maxTokens: 10000,
+  },
+  {
+    id: 'eu.amazon.nova-micro-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova Micro (EU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.eu-central-1.amazonaws.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.04, output: 0.16, cacheRead: 0.01, cacheWrite: 0.04 },
+    contextWindow: 128000,
+    maxTokens: 10000,
+  },
+  {
+    id: 'eu.amazon.nova-pro-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova Pro (EU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.eu-central-1.amazonaws.com',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: false,
+    cost: { input: 0.92, output: 3.68, cacheRead: 0.23, cacheWrite: 0.92 },
+    contextWindow: 300000,
+    maxTokens: 10000,
+  },
+  {
+    id: 'eu.anthropic.claude-fable-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Fable 5 (EU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.eu-central-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 11, output: 55, cacheRead: 1.1, cacheWrite: 13.75 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'eu.anthropic.claude-haiku-4-5-20251001-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Haiku 4.5 (EU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.eu-central-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 1.1, output: 5.5, cacheRead: 0.11, cacheWrite: 1.375 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'eu.anthropic.claude-opus-4-5-20251101-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.5 (EU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.eu-central-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'eu.anthropic.claude-opus-4-6-v1',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.6 (EU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.eu-central-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'eu.anthropic.claude-opus-4-7',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.7 (EU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.eu-central-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'eu.anthropic.claude-opus-4-8',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.8 (EU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.eu-central-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'eu.anthropic.claude-opus-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 5 (EU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.eu-central-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'eu.anthropic.claude-opus-5-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 5.5 (EU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.eu-central-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4.4, output: 22, cacheRead: 0.22, cacheWrite: 5.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'eu.anthropic.claude-sonnet-4-20250514-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 4 (EU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.eu-central-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'eu.anthropic.claude-sonnet-4-5-20250929-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 4.5 (EU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.eu-central-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 3.3, output: 16.5, cacheRead: 0.33, cacheWrite: 4.125 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'eu.anthropic.claude-sonnet-4-6',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 4.6 (EU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.eu-central-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 3.3, output: 16.5, cacheRead: 0.33, cacheWrite: 4.125 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'eu.anthropic.claude-sonnet-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 5 (EU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.eu-central-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2.2, output: 11, cacheRead: 0.22, cacheWrite: 2.75 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'eu.mistral.pixtral-large-2502-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Pixtral Large (25.02) (EU)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.eu-central-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 2, output: 6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'global.amazon.nova-2-lite-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova 2 Lite (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.3, output: 2.5, cacheRead: 0.075, cacheWrite: 0.3 },
+    contextWindow: 1000000,
+    maxTokens: 65535,
+  },
+  {
+    id: 'global.anthropic.claude-fable-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Fable 5 (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'global.anthropic.claude-fable-5-1',
+    provider: 'amazon-bedrock',
+    name: 'Claude Fable 5.1 (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 0.25, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'global.anthropic.claude-haiku-4-5-20251001-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Haiku 4.5 (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'global.anthropic.claude-opus-4-5-20251101-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.5 (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'global.anthropic.claude-opus-4-6-v1',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.6 (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'global.anthropic.claude-opus-4-7',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.7 (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'global.anthropic.claude-opus-4-8',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.8 (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'global.anthropic.claude-opus-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 5 (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'global.anthropic.claude-opus-5-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 5.5 (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.2, cacheWrite: 5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'global.anthropic.claude-sonnet-4-20250514-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 4 (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'global.anthropic.claude-sonnet-4-5-20250929-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 4.5 (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'global.anthropic.claude-sonnet-4-6',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 4.6 (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'global.anthropic.claude-sonnet-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 5 (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'global.anthropic.claude-sonnet-5-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 5.5 (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'global.moonshotai.kimi-k3',
+    provider: 'amazon-bedrock',
+    name: 'Kimi K3 (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 1048576,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'global.openai.gpt-5.6-luna',
+    provider: 'amazon-bedrock',
+    name: 'GPT-5.6 Luna (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'global.openai.gpt-5.6-sol',
+    provider: 'amazon-bedrock',
+    name: 'GPT-5.6 Sol (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'global.openai.gpt-5.6-terra',
+    provider: 'amazon-bedrock',
+    name: 'GPT-5.6 Terra (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'global.openai.gpt-6-astra',
+    provider: 'amazon-bedrock',
+    name: 'GPT-6 Astra (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'global.openai.gpt-6-luna',
+    provider: 'amazon-bedrock',
+    name: 'GPT-6 Luna (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'global.openai.gpt-6-sol',
+    provider: 'amazon-bedrock',
+    name: 'GPT-6 Sol (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'global.xai.grok-4.6',
+    provider: 'amazon-bedrock',
+    name: 'Grok 4.6 (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+  },
+  {
+    id: 'global.xai.grok-4.7',
+    provider: 'amazon-bedrock',
+    name: 'Grok 4.7 (Global)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+  },
+  {
+    id: 'google.gemma-3-12b-it',
+    provider: 'amazon-bedrock',
+    name: 'Gemma 3 12B IT',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.09, output: 0.29, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 8192,
+  },
+  {
+    id: 'google.gemma-3-27b-it',
+    provider: 'amazon-bedrock',
+    name: 'Gemma 3 27B IT',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.23, output: 0.38, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 8192,
+  },
+  {
+    id: 'google.gemma-3-4b-it',
+    provider: 'amazon-bedrock',
+    name: 'Gemma 3 4B IT',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.04, output: 0.08, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 4096,
+  },
+  {
+    id: 'google.gemma-4-26b-a4b',
+    provider: 'amazon-bedrock',
+    name: 'Gemma 4 26B A4B IT',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.13, output: 0.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+  },
+  {
+    id: 'google.gemma-4-31b',
+    provider: 'amazon-bedrock',
+    name: 'Gemma 4 31B IT',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.14, output: 0.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+  },
+  {
+    id: 'google.gemma-4-e2b',
+    provider: 'amazon-bedrock',
+    name: 'Gemma 4 E2B IT',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.04, output: 0.08, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 8192,
+  },
+  {
+    id: 'in.openai.gpt-5.6-luna',
+    provider: 'amazon-bedrock',
+    name: 'GPT-5.6 Luna (India)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.22, output: 1.32, cacheRead: 0.022, cacheWrite: 0.275 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'in.openai.gpt-5.6-terra',
+    provider: 'amazon-bedrock',
+    name: 'GPT-5.6 Terra (India)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2.2, output: 13.2, cacheRead: 0.22, cacheWrite: 2.75 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'jp.amazon.nova-2-lite-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova 2 Lite (JP)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.396, output: 3.311, cacheRead: 0.099, cacheWrite: 0.396 },
+    contextWindow: 1000000,
+    maxTokens: 65535,
+  },
+  {
+    id: 'jp.anthropic.claude-haiku-4-5-20251001-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Haiku 4.5 (JP)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 1.1, output: 5.5, cacheRead: 0.11, cacheWrite: 1.375 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'jp.anthropic.claude-opus-4-7',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.7 (JP)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'jp.anthropic.claude-opus-4-8',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.8 (JP)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'jp.anthropic.claude-opus-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 5 (JP)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'jp.anthropic.claude-opus-5-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 5.5 (JP)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4.4, output: 22, cacheRead: 0.22, cacheWrite: 5.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'jp.anthropic.claude-sonnet-4-5-20250929-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 4.5 (JP)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 3.3, output: 16.5, cacheRead: 0.33, cacheWrite: 4.125 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'jp.anthropic.claude-sonnet-4-6',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 4.6 (JP)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 3.3, output: 16.5, cacheRead: 0.33, cacheWrite: 4.125 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'jp.anthropic.claude-sonnet-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 5 (JP)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2.2, output: 11, cacheRead: 0.22, cacheWrite: 2.75 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'meta.llama3-1-70b-instruct-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Llama 3.1 70B Instruct',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.72, output: 0.72, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'meta.llama3-1-8b-instruct-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Llama 3.1 8B Instruct',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.22, output: 0.22, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'meta.llama3-3-70b-instruct-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Llama 3.3 70B Instruct',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.72, output: 0.72, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'meta.llama4-maverick-17b-instruct-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Llama 4 Maverick 17B Instruct',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.24, output: 0.97, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'meta.llama4-scout-17b-instruct-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Llama 4 Scout 17B Instruct',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.17, output: 0.66, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 10000000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'minimax.minimax-m2',
+    provider: 'amazon-bedrock',
+    name: 'MiniMax-M2',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 204608,
+    maxTokens: 128000,
+  },
+  {
+    id: 'minimax.minimax-m2.1',
+    provider: 'amazon-bedrock',
+    name: 'MiniMax-M2.1',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 196608,
+    maxTokens: 131072,
+  },
+  {
+    id: 'minimax.minimax-m2.5',
+    provider: 'amazon-bedrock',
+    name: 'MiniMax-M2.5',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 196608,
+    maxTokens: 98304,
+  },
+  {
+    id: 'mistral.devstral-2-123b',
+    provider: 'amazon-bedrock',
+    name: 'Devstral 2 123B',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.4, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 8192,
+  },
+  {
+    id: 'mistral.magistral-small-2509',
+    provider: 'amazon-bedrock',
+    name: 'Magistral Small 1.2',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.5, output: 1.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 40000,
+  },
+  {
+    id: 'mistral.ministral-3-14b-instruct',
+    provider: 'amazon-bedrock',
+    name: 'Ministral 14B 3.0',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.2, output: 0.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'mistral.ministral-3-3b-instruct',
+    provider: 'amazon-bedrock',
+    name: 'Ministral 3 3B',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.1, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'mistral.ministral-3-8b-instruct',
+    provider: 'amazon-bedrock',
+    name: 'Ministral 3 8B',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0.15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'mistral.mistral-large-3-675b-instruct',
+    provider: 'amazon-bedrock',
+    name: 'Mistral Large 3',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.5, output: 1.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 8192,
+  },
+  {
+    id: 'mistral.pixtral-large-2502-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Pixtral Large (25.02)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 2, output: 6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'mistral.voxtral-mini-3b-2507',
+    provider: 'amazon-bedrock',
+    name: 'Voxtral Mini 3B 2507',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'audio'],
+    reasoning: false,
+    cost: { input: 0.04, output: 0.04, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 4096,
+  },
+  {
+    id: 'mistral.voxtral-small-24b-2507',
+    provider: 'amazon-bedrock',
+    name: 'Voxtral Small 24B 2507',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'audio'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 8192,
+  },
+  {
+    id: 'moonshot.kimi-k2-thinking',
+    provider: 'amazon-bedrock',
+    name: 'Kimi K2 Thinking',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.6, output: 2.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 16000,
+  },
+  {
+    id: 'moonshotai.kimi-k2.5',
+    provider: 'amazon-bedrock',
+    name: 'Kimi K2.5',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 16384,
+  },
+  {
+    id: 'nvidia.nemotron-nano-12b-v2',
+    provider: 'amazon-bedrock',
+    name: 'NVIDIA Nemotron Nano 12B v2 VL BF16',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.2, output: 0.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 8192,
+  },
+  {
+    id: 'nvidia.nemotron-nano-3-30b',
+    provider: 'amazon-bedrock',
+    name: 'NVIDIA Nemotron Nano 3 30B',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.06, output: 0.24, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 8192,
+  },
+  {
+    id: 'nvidia.nemotron-nano-9b-v2',
+    provider: 'amazon-bedrock',
+    name: 'NVIDIA Nemotron Nano 9B v2',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.06, output: 0.23, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 8192,
+  },
+  {
+    id: 'nvidia.nemotron-super-3-120b',
+    provider: 'amazon-bedrock',
+    name: 'NVIDIA Nemotron 3 Super 120B A12B',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.15, output: 0.65, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+  },
+  {
+    id: 'openai.gpt-5.4',
+    provider: 'amazon-bedrock',
+    name: 'GPT-5.4',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2.75, output: 16.5, cacheRead: 0.275, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'openai.gpt-5.5',
+    provider: 'amazon-bedrock',
+    name: 'GPT-5.5',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 5.5, output: 33, cacheRead: 0.55, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'openai.gpt-5.6-luna',
+    provider: 'amazon-bedrock',
+    name: 'GPT-5.6 Luna',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.22, output: 1.32, cacheRead: 0.022, cacheWrite: 0.275 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'openai.gpt-5.6-sol',
+    provider: 'amazon-bedrock',
+    name: 'GPT-5.6 Sol',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4.4, output: 22, cacheRead: 0.44, cacheWrite: 5.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'openai.gpt-5.6-terra',
+    provider: 'amazon-bedrock',
+    name: 'GPT-5.6 Terra',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2.2, output: 13.2, cacheRead: 0.22, cacheWrite: 2.75 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'openai.gpt-6-astra',
+    provider: 'amazon-bedrock',
+    name: 'GPT-6 Astra',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 11, output: 55, cacheRead: 1.1, cacheWrite: 13.75 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'openai.gpt-6-luna',
+    provider: 'amazon-bedrock',
+    name: 'GPT-6 Luna',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.11, output: 0.55, cacheRead: 0.011, cacheWrite: 0.1375 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'openai.gpt-6-sol',
+    provider: 'amazon-bedrock',
+    name: 'GPT-6 Sol',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2.2, output: 11, cacheRead: 0.22, cacheWrite: 2.75 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'openai.gpt-oss-120b',
+    provider: 'amazon-bedrock',
+    name: 'gpt-oss-120b',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+  },
+  {
+    id: 'openai.gpt-oss-120b-1:0',
+    provider: 'amazon-bedrock',
+    name: 'gpt-oss-120b',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 128000,
+  },
+  {
+    id: 'openai.gpt-oss-20b',
+    provider: 'amazon-bedrock',
+    name: 'gpt-oss-20b',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.07, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+  },
+  {
+    id: 'openai.gpt-oss-20b-1:0',
+    provider: 'amazon-bedrock',
+    name: 'gpt-oss-20b',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.07, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 128000,
+  },
+  {
+    id: 'openai.gpt-oss-safeguard-120b',
+    provider: 'amazon-bedrock',
+    name: 'GPT OSS Safeguard 120B',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+  },
+  {
+    id: 'openai.gpt-oss-safeguard-20b',
+    provider: 'amazon-bedrock',
+    name: 'GPT OSS Safeguard 20B',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.07, output: 0.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+  },
+  {
+    id: 'qwen.qwen3-235b-a22b-2507-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Qwen3 235B-A22B Instruct 2507',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.22, output: 0.88, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+  },
+  {
+    id: 'qwen.qwen3-32b-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Qwen3 32B',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 16384,
+  },
+  {
+    id: 'qwen.qwen3-coder-30b-a3b-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Qwen3-Coder 30B-A3B Instruct',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+  },
+  {
+    id: 'qwen.qwen3-coder-480b-a35b-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Qwen3-Coder 480B-A35B Instruct',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.45, output: 1.8, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 65536,
+  },
+  {
+    id: 'qwen.qwen3-coder-next',
+    provider: 'amazon-bedrock',
+    name: 'Qwen3 Coder Next',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.5, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+  },
+  {
+    id: 'qwen.qwen3-next-80b-a3b',
+    provider: 'amazon-bedrock',
+    name: 'Qwen3-Next 80B-A3B Instruct',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.15, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262000,
+  },
+  {
+    id: 'qwen.qwen3-vl-235b-a22b',
+    provider: 'amazon-bedrock',
+    name: 'Qwen3 VL 235B A22B Instruct',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.53, output: 2.66, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262000,
+  },
+  {
+    id: 'us-gov.openai.gpt-oss-120b-1:0',
+    provider: 'amazon-bedrock',
+    name: 'gpt-oss-120b (GovCloud)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.18, output: 0.72, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+  },
+  {
+    id: 'us-gov.openai.gpt-oss-20b-1:0',
+    provider: 'amazon-bedrock',
+    name: 'gpt-oss-20b (GovCloud)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.084, output: 0.36, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+  },
+  {
+    id: 'us.amazon.nova-2-lite-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova 2 Lite (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.33, output: 2.75, cacheRead: 0.0825, cacheWrite: 0.33 },
+    contextWindow: 1000000,
+    maxTokens: 65535,
+  },
+  {
+    id: 'us.amazon.nova-lite-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova Lite (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: false,
+    cost: { input: 0.06, output: 0.24, cacheRead: 0.015, cacheWrite: 0.06 },
+    contextWindow: 300000,
+    maxTokens: 10000,
+  },
+  {
+    id: 'us.amazon.nova-micro-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova Micro (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.035, output: 0.14, cacheRead: 0.00875, cacheWrite: 0.035 },
+    contextWindow: 128000,
+    maxTokens: 10000,
+  },
+  {
+    id: 'us.amazon.nova-premier-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova Premier (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: false,
+    cost: { input: 2.5, output: 12.5, cacheRead: 0.625, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 10000,
+  },
+  {
+    id: 'us.amazon.nova-pro-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Nova Pro (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: false,
+    cost: { input: 0.8, output: 3.2, cacheRead: 0.2, cacheWrite: 0.8 },
+    contextWindow: 300000,
+    maxTokens: 10000,
+  },
+  {
+    id: 'us.anthropic.claude-fable-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Fable 5 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 11, output: 55, cacheRead: 1.1, cacheWrite: 13.75 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'us.anthropic.claude-fable-5-1',
+    provider: 'amazon-bedrock',
+    name: 'Claude Fable 5.1 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 11, output: 55, cacheRead: 0.275, cacheWrite: 13.75 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'us.anthropic.claude-haiku-4-5-20251001-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Haiku 4.5 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 1.1, output: 5.5, cacheRead: 0.11, cacheWrite: 1.375 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'us.anthropic.claude-opus-4-1-20250805-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.1 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+    contextWindow: 200000,
+    maxTokens: 32000,
+  },
+  {
+    id: 'us.anthropic.claude-opus-4-5-20251101-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.5 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'us.anthropic.claude-opus-4-6-v1',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.6 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'us.anthropic.claude-opus-4-7',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.7 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'us.anthropic.claude-opus-4-8',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 4.8 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'us.anthropic.claude-opus-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 5 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5.5, output: 27.5, cacheRead: 0.55, cacheWrite: 6.875 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'us.anthropic.claude-opus-5-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Opus 5.5 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4.4, output: 22, cacheRead: 0.22, cacheWrite: 5.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'us.anthropic.claude-sonnet-4-20250514-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 4 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'us.anthropic.claude-sonnet-4-5-20250929-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 4.5 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 3.3, output: 16.5, cacheRead: 0.33, cacheWrite: 4.125 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'us.anthropic.claude-sonnet-4-6',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 4.6 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 3.3, output: 16.5, cacheRead: 0.33, cacheWrite: 4.125 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'us.anthropic.claude-sonnet-5',
+    provider: 'amazon-bedrock',
+    name: 'Claude Sonnet 5 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2.2, output: 11, cacheRead: 0.22, cacheWrite: 2.75 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'us.deepseek.r1-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'DeepSeek-R1 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 1.35, output: 5.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 32768,
+  },
+  {
+    id: 'us.meta.llama3-1-70b-instruct-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Llama 3.1 70B Instruct (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.72, output: 0.72, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'us.meta.llama3-1-8b-instruct-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Llama 3.1 8B Instruct (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.22, output: 0.22, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'us.meta.llama3-3-70b-instruct-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Llama 3.3 70B Instruct (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.72, output: 0.72, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'us.meta.llama4-maverick-17b-instruct-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Llama 4 Maverick 17B Instruct (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.24, output: 0.97, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'us.meta.llama4-scout-17b-instruct-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Llama 4 Scout 17B Instruct (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.17, output: 0.66, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 10000000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'us.mistral.pixtral-large-2502-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Pixtral Large (25.02) (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 2, output: 6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'us.moonshotai.kimi-k3',
+    provider: 'amazon-bedrock',
+    name: 'Kimi K3 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 3.3, output: 16.5, cacheRead: 0.33, cacheWrite: 4.125 },
+    contextWindow: 1048576,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'us.openai.gpt-5.6-luna',
+    provider: 'amazon-bedrock',
+    name: 'GPT-5.6 Luna (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.22, output: 1.32, cacheRead: 0.022, cacheWrite: 0.275 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'us.openai.gpt-5.6-sol',
+    provider: 'amazon-bedrock',
+    name: 'GPT-5.6 Sol (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4.4, output: 22, cacheRead: 0.44, cacheWrite: 5.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'us.openai.gpt-5.6-terra',
+    provider: 'amazon-bedrock',
+    name: 'GPT-5.6 Terra (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2.2, output: 13.2, cacheRead: 0.22, cacheWrite: 2.75 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'us.openai.gpt-6-astra',
+    provider: 'amazon-bedrock',
+    name: 'GPT-6 Astra (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 11, output: 55, cacheRead: 1.1, cacheWrite: 13.75 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'us.openai.gpt-6-luna',
+    provider: 'amazon-bedrock',
+    name: 'GPT-6 Luna (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.11, output: 0.55, cacheRead: 0.011, cacheWrite: 0.1375 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'us.openai.gpt-6-sol',
+    provider: 'amazon-bedrock',
+    name: 'GPT-6 Sol (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2.2, output: 11, cacheRead: 0.22, cacheWrite: 2.75 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'us.writer.palmyra-x4-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Palmyra X4 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 2.5, output: 10, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 122880,
+    maxTokens: 8192,
+  },
+  {
+    id: 'us.writer.palmyra-x5-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Palmyra X5 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.6, output: 6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1040000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'us.xai.grok-4.6',
+    provider: 'amazon-bedrock',
+    name: 'Grok 4.6 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2.2, output: 6.6, cacheRead: 0.55, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+  },
+  {
+    id: 'us.xai.grok-4.7',
+    provider: 'amazon-bedrock',
+    name: 'Grok 4.7 (US)',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2.2, output: 6.6, cacheRead: 0.55, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+  },
+  {
+    id: 'writer.palmyra-x4-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Palmyra X4',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 2.5, output: 10, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 122880,
+    maxTokens: 8192,
+  },
+  {
+    id: 'writer.palmyra-x5-v1:0',
+    provider: 'amazon-bedrock',
+    name: 'Palmyra X5',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.6, output: 6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1040000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'xai.grok-4.3',
+    provider: 'amazon-bedrock',
+    name: 'Grok 4.3',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+  },
+  {
+    id: 'xai.grok-4.6',
+    provider: 'amazon-bedrock',
+    name: 'Grok 4.6',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2.2, output: 6.6, cacheRead: 0.55, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+  },
+  {
+    id: 'zai.glm-4.7',
+    provider: 'amazon-bedrock',
+    name: 'GLM-4.7',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 2.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 202752,
+    maxTokens: 131072,
+  },
+  {
+    id: 'zai.glm-4.7-flash',
+    provider: 'amazon-bedrock',
+    name: 'GLM-4.7-Flash',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.07, output: 0.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 202752,
+    maxTokens: 131072,
+  },
+  {
+    id: 'zai.glm-5',
+    provider: 'amazon-bedrock',
+    name: 'GLM-5',
+    api: 'bedrock-converse-stream',
+    baseUrl: 'https://bedrock-runtime.us-east-1.amazonaws.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1, output: 3.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 202752,
+    maxTokens: 131072,
+  },
+]
diff --git a/packages/ai-models/src/providers/ant-ling.ts b/packages/ai-models/src/providers/ant-ling.ts
new file mode 100644
index 0000000000..431d292f7c
--- /dev/null
+++ b/packages/ai-models/src/providers/ant-ling.ts
@@ -0,0 +1,81 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Ant Ling. */
+export const provider: ProviderRecord = {
+  id: 'ant-ling',
+  name: 'Ant Ling',
+  baseUrl: 'https://api.ant-ling.com/v1',
+  apis: ['openai-completions'],
+  env: [['ANT_LING_API_KEY']],
+}
+
+/** Every Ant Ling model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'Ling-2.6-1T',
+    provider: 'ant-ling',
+    name: 'Ling-2.6-1T',
+    api: 'openai-completions',
+    baseUrl: 'https://api.ant-ling.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.3, output: 2.5, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'ant-ling',
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+    },
+    borrowedFrom: 'novita-ai/inclusionai/ling-2.6-1t',
+  },
+  {
+    id: 'Ling-2.6-flash',
+    provider: 'ant-ling',
+    name: 'Ling-2.6-flash',
+    api: 'openai-completions',
+    baseUrl: 'https://api.ant-ling.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.3, cacheRead: 0.02, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'ant-ling',
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+    },
+    borrowedFrom: 'novita-ai/inclusionai/ling-2.6-flash',
+  },
+  {
+    id: 'Ring-2.6-1T',
+    provider: 'ant-ling',
+    name: 'Ring-2.6-1T',
+    api: 'openai-completions',
+    baseUrl: 'https://api.ant-ling.com/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 2.5, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'ant-ling',
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+    },
+    borrowedFrom: 'novita-ai/inclusionai/ring-2.6-1t',
+  },
+]
diff --git a/packages/ai-models/src/providers/anthropic.ts b/packages/ai-models/src/providers/anthropic.ts
new file mode 100644
index 0000000000..4897f09e36
--- /dev/null
+++ b/packages/ai-models/src/providers/anthropic.ts
@@ -0,0 +1,375 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Anthropic. */
+export const provider: ProviderRecord = {
+  id: 'anthropic',
+  name: 'Anthropic',
+  baseUrl: 'https://api.anthropic.com',
+  apis: ['anthropic-messages'],
+  env: [
+    ['ANTHROPIC_API_KEY'],
+    ['ANTHROPIC_OAUTH_TOKEN'],
+    ['ANTHROPIC_AUTH_TOKEN'],
+  ],
+}
+
+/** Every Anthropic model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'claude-fable-5',
+    provider: 'anthropic',
+    name: 'Claude Fable 5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.anthropic.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      supportsStrictTools: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'claude-fable-5-1',
+    provider: 'anthropic',
+    name: 'Claude Fable 5.1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.anthropic.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 0.25, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      supportsStrictTools: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'claude-haiku-4-5',
+    provider: 'anthropic',
+    name: 'Claude Haiku 4.5 (latest)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.anthropic.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+    compat: { supportsStrictTools: true },
+  },
+  {
+    id: 'claude-haiku-4-5-20251001',
+    provider: 'anthropic',
+    name: 'Claude Haiku 4.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.anthropic.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+    compat: { supportsStrictTools: true },
+  },
+  {
+    id: 'claude-opus-4-5',
+    provider: 'anthropic',
+    name: 'Claude Opus 4.5 (latest)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.anthropic.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+    compat: { supportsStrictTools: true },
+  },
+  {
+    id: 'claude-opus-4-5-20251101',
+    provider: 'anthropic',
+    name: 'Claude Opus 4.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.anthropic.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+    compat: { supportsStrictTools: true },
+  },
+  {
+    id: 'claude-opus-4-6',
+    provider: 'anthropic',
+    name: 'Claude Opus 4.6',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.anthropic.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsStrictTools: true },
+  },
+  {
+    id: 'claude-opus-4-7',
+    provider: 'anthropic',
+    name: 'Claude Opus 4.7',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.anthropic.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      supportsStrictTools: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'claude-opus-4-8',
+    provider: 'anthropic',
+    name: 'Claude Opus 4.8',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.anthropic.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      supportsStrictTools: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'claude-opus-5',
+    provider: 'anthropic',
+    name: 'Claude Opus 5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.anthropic.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      supportsStrictTools: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'claude-opus-5-5',
+    provider: 'anthropic',
+    name: 'Claude Opus 5.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.anthropic.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.2, cacheWrite: 5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      supportsStrictTools: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'claude-sonnet-4-5',
+    provider: 'anthropic',
+    name: 'Claude Sonnet 4.5 (latest)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.anthropic.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+    compat: { supportsStrictTools: true },
+  },
+  {
+    id: 'claude-sonnet-4-5-20250929',
+    provider: 'anthropic',
+    name: 'Claude Sonnet 4.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.anthropic.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+    compat: { supportsStrictTools: true },
+  },
+  {
+    id: 'claude-sonnet-4-6',
+    provider: 'anthropic',
+    name: 'Claude Sonnet 4.6',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.anthropic.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsStrictTools: true },
+  },
+  {
+    id: 'claude-sonnet-5',
+    provider: 'anthropic',
+    name: 'Claude Sonnet 5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.anthropic.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      supportsStrictTools: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'claude-sonnet-5-5',
+    provider: 'anthropic',
+    name: 'Claude Sonnet 5.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.anthropic.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      supportsStrictTools: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/azure-openai-responses.ts b/packages/ai-models/src/providers/azure-openai-responses.ts
new file mode 100644
index 0000000000..575fa35151
--- /dev/null
+++ b/packages/ai-models/src/providers/azure-openai-responses.ts
@@ -0,0 +1,1782 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Azure OpenAI. */
+export const provider: ProviderRecord = {
+  id: 'azure-openai-responses',
+  name: 'Azure OpenAI',
+  baseUrl: '',
+  apis: ['azure-openai-responses'],
+  env: [['AZURE_OPENAI_API_KEY']],
+}
+
+/** Every Azure OpenAI model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'claude-fable-5',
+    provider: 'azure-openai-responses',
+    name: 'Claude Fable 5',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'claude-fable-5-1',
+    provider: 'azure-openai-responses',
+    name: 'Claude Fable 5.1',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 0.25, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'claude-haiku-4-5',
+    provider: 'azure-openai-responses',
+    name: 'Claude Haiku 4.5',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'claude-mythos-5',
+    provider: 'azure-openai-responses',
+    name: 'Claude Mythos 5',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'claude-opus-4-1',
+    provider: 'azure-openai-responses',
+    name: 'Claude Opus 4.1',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+    contextWindow: 200000,
+    maxTokens: 32000,
+  },
+  {
+    id: 'claude-opus-4-5',
+    provider: 'azure-openai-responses',
+    name: 'Claude Opus 4.5',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'claude-opus-4-6',
+    provider: 'azure-openai-responses',
+    name: 'Claude Opus 4.6',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'claude-opus-4-7',
+    provider: 'azure-openai-responses',
+    name: 'Claude Opus 4.7',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'claude-opus-4-8',
+    provider: 'azure-openai-responses',
+    name: 'Claude Opus 4.8',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'claude-opus-5',
+    provider: 'azure-openai-responses',
+    name: 'Claude Opus 5',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'claude-opus-5-5',
+    provider: 'azure-openai-responses',
+    name: 'Claude Opus 5.5',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.2, cacheWrite: 5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'claude-sonnet-4-5',
+    provider: 'azure-openai-responses',
+    name: 'Claude Sonnet 4.5',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'claude-sonnet-4-6',
+    provider: 'azure-openai-responses',
+    name: 'Claude Sonnet 4.6',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'claude-sonnet-5',
+    provider: 'azure-openai-responses',
+    name: 'Claude Sonnet 5',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'claude-sonnet-5-5',
+    provider: 'azure-openai-responses',
+    name: 'Claude Sonnet 5.5',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'codestral-2501',
+    provider: 'azure-openai-responses',
+    name: 'Codestral 25.01',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.3, output: 0.9, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 256000,
+  },
+  {
+    id: 'codex-mini',
+    provider: 'azure-openai-responses',
+    name: 'Codex Mini',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.5, output: 6, cacheRead: 0.375, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'cohere-command-a',
+    provider: 'azure-openai-responses',
+    name: 'Command A',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 2.5, output: 10, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 8192,
+  },
+  {
+    id: 'cohere-embed-v-4-0',
+    provider: 'azure-openai-responses',
+    name: 'Embed v4',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.12, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 1536,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'cohere-embed-v3-english',
+    provider: 'azure-openai-responses',
+    name: 'Embed v3 English',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 512,
+    maxTokens: 1024,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'cohere-embed-v3-multilingual',
+    provider: 'azure-openai-responses',
+    name: 'Embed v3 Multilingual',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 512,
+    maxTokens: 1024,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'deepseek-r1',
+    provider: 'azure-openai-responses',
+    name: 'DeepSeek-R1',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 1.35, output: 5.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 163840,
+  },
+  {
+    id: 'deepseek-v3.2',
+    provider: 'azure-openai-responses',
+    name: 'DeepSeek-V3.2',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.58, output: 1.68, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'deepseek-v3.2-speciale',
+    provider: 'azure-openai-responses',
+    name: 'DeepSeek-V3.2-Speciale',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.58, output: 1.68, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'deepseek-v4-flash',
+    provider: 'azure-openai-responses',
+    name: 'DeepSeek-V4-Flash',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.19, output: 0.51, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+  },
+  {
+    id: 'deepseek-v4-pro',
+    provider: 'azure-openai-responses',
+    name: 'DeepSeek-V4-Pro',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 1.74, output: 3.48, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+  },
+  {
+    id: 'gpt-3.5-turbo-0125',
+    provider: 'azure-openai-responses',
+    name: 'GPT-3.5 Turbo 0125',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.5, output: 1.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 16384,
+    maxTokens: 4096,
+  },
+  {
+    id: 'gpt-3.5-turbo-1106',
+    provider: 'azure-openai-responses',
+    name: 'GPT-3.5 Turbo 1106',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 1, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 16384,
+    maxTokens: 4096,
+  },
+  {
+    id: 'gpt-3.5-turbo-instruct',
+    provider: 'azure-openai-responses',
+    name: 'GPT-3.5 Turbo Instruct',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 1.5, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 4096,
+    maxTokens: 4096,
+  },
+  {
+    id: 'gpt-4',
+    provider: 'azure-openai-responses',
+    name: 'GPT-4',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 30, output: 60, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 8192,
+    borrowedFrom: 'openai/gpt-4',
+  },
+  {
+    id: 'gpt-4-turbo',
+    provider: 'azure-openai-responses',
+    name: 'GPT-4 Turbo',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 10, output: 30, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'gpt-4-turbo-vision',
+    provider: 'azure-openai-responses',
+    name: 'GPT-4 Turbo Vision',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 10, output: 30, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'gpt-4.1',
+    provider: 'azure-openai-responses',
+    name: 'GPT-4.1',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 2, output: 8, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+  },
+  {
+    id: 'gpt-4.1-mini',
+    provider: 'azure-openai-responses',
+    name: 'GPT-4.1 mini',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.4, output: 1.6, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+  },
+  {
+    id: 'gpt-4.1-nano',
+    provider: 'azure-openai-responses',
+    name: 'GPT-4.1 nano',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.4, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+  },
+  {
+    id: 'gpt-4o',
+    provider: 'azure-openai-responses',
+    name: 'GPT-4o',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 2.5, output: 10, cacheRead: 1.25, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+  },
+  {
+    id: 'gpt-4o-2024-05-13',
+    provider: 'azure-openai-responses',
+    name: 'GPT-4o (2024-05-13)',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 5, output: 15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    borrowedFrom: 'openai/gpt-4o-2024-05-13',
+  },
+  {
+    id: 'gpt-4o-2024-08-06',
+    provider: 'azure-openai-responses',
+    name: 'GPT-4o (2024-08-06)',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 2.5, output: 10, cacheRead: 1.25, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    borrowedFrom: 'openai/gpt-4o-2024-08-06',
+  },
+  {
+    id: 'gpt-4o-2024-11-20',
+    provider: 'azure-openai-responses',
+    name: 'GPT-4o (2024-11-20)',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 2.5, output: 10, cacheRead: 1.25, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    borrowedFrom: 'openai/gpt-4o-2024-11-20',
+  },
+  {
+    id: 'gpt-4o-mini',
+    provider: 'azure-openai-responses',
+    name: 'GPT-4o mini',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+  },
+  {
+    id: 'gpt-5',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.13, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5-chat-latest',
+    provider: 'azure-openai-responses',
+    name: 'gpt-5-chat-latest',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 1.125, output: 9, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    borrowedFrom: 'jiekou/gpt-5-chat-latest',
+  },
+  {
+    id: 'gpt-5-codex',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5-Codex',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.13, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5-mini',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5 Mini',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 2, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5-nano',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5 Nano',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.05, output: 0.4, cacheRead: 0.01, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5-pro',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5 Pro',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 15, output: 120, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.1',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.1',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'audio'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.1-codex',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.1 Codex',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'audio'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.1-codex-max',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.1 Codex Max',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.1-codex-mini',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.1 Codex Mini',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 2, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.2',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.2',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.2-chat-latest',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.2 Chat',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: null,
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: { supportsTemperature: false },
+    borrowedFrom: 'openai/gpt-5.2-chat-latest',
+  },
+  {
+    id: 'gpt-5.2-codex',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.2 Codex',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.2-pro',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.2 Pro',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 21, output: 168, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+    borrowedFrom: 'openai/gpt-5.2-pro',
+  },
+  {
+    id: 'gpt-5.3-chat-latest',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.3 Chat (latest)',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    borrowedFrom: 'openai/gpt-5.3-chat-latest',
+  },
+  {
+    id: 'gpt-5.3-codex',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.3 Codex',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.3-codex-spark',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.3 Codex Spark',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 32000,
+    compat: { supportsTemperature: false },
+    borrowedFrom: 'openai/gpt-5.3-codex-spark',
+  },
+  {
+    id: 'gpt-5.4',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.4',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'gpt-5.4-mini',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.4 Mini',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.75, output: 4.5, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'gpt-5.4-nano',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.4 Nano',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.2, output: 1.25, cacheRead: 0.02, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'gpt-5.4-pro',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.4 Pro',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.5',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.5',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.5-pro',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.5 Pro',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+    borrowedFrom: 'openai/gpt-5.5-pro',
+  },
+  {
+    id: 'gpt-5.6-luna',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.6 Luna',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.6-sol',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.6 Sol',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.6-terra',
+    provider: 'azure-openai-responses',
+    name: 'GPT-5.6 Terra',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-6-astra',
+    provider: 'azure-openai-responses',
+    name: 'GPT-6 Astra',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-6-luna',
+    provider: 'azure-openai-responses',
+    name: 'GPT-6 Luna',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-6-sol',
+    provider: 'azure-openai-responses',
+    name: 'GPT-6 Sol',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-6.1-sol',
+    provider: 'azure-openai-responses',
+    name: 'GPT-6.1 Sol',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-chat-latest',
+    provider: 'azure-openai-responses',
+    name: 'GPT Chat Latest',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-image-1.5',
+    provider: 'azure-openai-responses',
+    name: 'GPT-Image-1.5',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 5, output: 32, cacheRead: 1.25, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gpt-realtime-2.1',
+    provider: 'azure-openai-responses',
+    name: 'GPT-Realtime-2.1',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'audio'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 4, output: 24, cacheRead: 0.4, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 32000,
+    compat: { supportsTemperature: false },
+    borrowedFrom: 'openai/gpt-realtime-2.1',
+  },
+  {
+    id: 'grok-4-1-fast-non-reasoning',
+    provider: 'azure-openai-responses',
+    name: 'Grok 4.1 Fast (Non-Reasoning)',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.2, output: 0.5, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'grok-4-1-fast-reasoning',
+    provider: 'azure-openai-responses',
+    name: 'Grok 4.1 Fast (Reasoning)',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.2, output: 0.5, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'grok-4-20-non-reasoning',
+    provider: 'azure-openai-responses',
+    name: 'Grok 4.20 (Non-Reasoning)',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 2, output: 6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'grok-4-20-reasoning',
+    provider: 'azure-openai-responses',
+    name: 'Grok 4.20 (Reasoning)',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 2, output: 6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'grok-4.6',
+    provider: 'azure-openai-responses',
+    name: 'Grok 4.6',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'kimi-k2.5',
+    provider: 'azure-openai-responses',
+    name: 'Kimi K2.5',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+  },
+  {
+    id: 'kimi-k2.6',
+    provider: 'azure-openai-responses',
+    name: 'Kimi K2.6',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.95, output: 4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+  },
+  {
+    id: 'kimi-k2.7-code',
+    provider: 'azure-openai-responses',
+    name: 'Kimi K2.7 Code',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.95, output: 4, cacheRead: 0.19, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'llama-3.3-70b-instruct',
+    provider: 'azure-openai-responses',
+    name: 'Llama-3.3-70B-Instruct',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.71, output: 0.71, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 32768,
+  },
+  {
+    id: 'llama-4-maverick-17b-128e-instruct-fp8',
+    provider: 'azure-openai-responses',
+    name: 'Llama 4 Maverick 17B 128E Instruct FP8',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.25, output: 1, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 16384,
+  },
+  {
+    id: 'llama-4-scout-17b-16e-instruct',
+    provider: 'azure-openai-responses',
+    name: 'Llama 4 Scout 17B 16E Instruct',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.2, output: 0.78, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'ministral-3b',
+    provider: 'azure-openai-responses',
+    name: 'Ministral 3B',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.04, output: 0.04, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'mistral-medium-2505',
+    provider: 'azure-openai-responses',
+    name: 'Mistral Medium 3',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.4, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'mistral-small-2503',
+    provider: 'azure-openai-responses',
+    name: 'Mistral Small 3.1',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 32768,
+  },
+  {
+    id: 'model-router',
+    provider: 'azure-openai-responses',
+    name: 'Model Router',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.14, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 16384,
+  },
+  {
+    id: 'o1',
+    provider: 'azure-openai-responses',
+    name: 'o1',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 15, output: 60, cacheRead: 7.5, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'o1-pro',
+    provider: 'azure-openai-responses',
+    name: 'o1-pro',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 150, output: 600, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: { supportsTemperature: false },
+    borrowedFrom: 'openai/o1-pro',
+  },
+  {
+    id: 'o3',
+    provider: 'azure-openai-responses',
+    name: 'o3',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 8, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'o3-mini',
+    provider: 'azure-openai-responses',
+    name: 'o3-mini',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.1, output: 4.4, cacheRead: 0.55, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'o3-pro',
+    provider: 'azure-openai-responses',
+    name: 'o3-pro',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 20, output: 80, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: { supportsTemperature: false },
+    borrowedFrom: 'openai/o3-pro',
+  },
+  {
+    id: 'o4-mini',
+    provider: 'azure-openai-responses',
+    name: 'o4-mini',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.1, output: 4.4, cacheRead: 0.275, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'phi-4',
+    provider: 'azure-openai-responses',
+    name: 'Phi-4',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.125, output: 0.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'phi-4-mini',
+    provider: 'azure-openai-responses',
+    name: 'Phi-4-mini',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.075, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'phi-4-mini-reasoning',
+    provider: 'azure-openai-responses',
+    name: 'Phi-4-mini-reasoning',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.075, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'phi-4-multimodal',
+    provider: 'azure-openai-responses',
+    name: 'Phi-4-multimodal',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text', 'image', 'audio'],
+    reasoning: false,
+    cost: { input: 0.08, output: 0.32, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'phi-4-reasoning',
+    provider: 'azure-openai-responses',
+    name: 'Phi-4-reasoning',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.125, output: 0.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'phi-4-reasoning-plus',
+    provider: 'azure-openai-responses',
+    name: 'Phi-4-reasoning-plus',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.125, output: 0.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'text-embedding-3-large',
+    provider: 'azure-openai-responses',
+    name: 'text-embedding-3-large',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.13, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 3072,
+  },
+  {
+    id: 'text-embedding-3-small',
+    provider: 'azure-openai-responses',
+    name: 'text-embedding-3-small',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.02, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+  },
+  {
+    id: 'text-embedding-ada-002',
+    provider: 'azure-openai-responses',
+    name: 'text-embedding-ada-002',
+    api: 'azure-openai-responses',
+    baseUrl: '',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+  },
+]
diff --git a/packages/ai-models/src/providers/baseten.ts b/packages/ai-models/src/providers/baseten.ts
new file mode 100644
index 0000000000..65524c60ec
--- /dev/null
+++ b/packages/ai-models/src/providers/baseten.ts
@@ -0,0 +1,748 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Baseten. */
+export const provider: ProviderRecord = {
+  id: 'baseten',
+  name: 'Baseten',
+  baseUrl: 'https://inference.baseten.co/v1',
+  apis: ['openai-completions'],
+  env: [['BASETEN_API_KEY']],
+}
+
+/** Every Baseten model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'deepseek-ai/DeepSeek-V3.1',
+    provider: 'baseten',
+    name: 'DeepSeek V3.1',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.5, output: 1.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 164000,
+    maxTokens: 131000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V4-Flash-0731',
+    provider: 'baseten',
+    name: 'DeepSeek V4 Flash 0731',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.13, output: 0.26, cacheRead: 0.028, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V4-Pro',
+    provider: 'baseten',
+    name: 'DeepSeek V4 Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1.74, output: 3.48, cacheRead: 0.145, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V4-Pro-0813',
+    provider: 'baseten',
+    name: 'DeepSeek V4 Pro 0813',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.32, output: 3.96, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V4.1-Flash',
+    provider: 'baseten',
+    name: 'DeepSeek V4.1 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V4.1-Flash-Fast',
+    provider: 'baseten',
+    name: 'deepseek-ai/DeepSeek-V4.1-Flash-Fast',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.6, output: 2.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'MiniMaxAI/MiniMax-M2.5',
+    provider: 'baseten',
+    name: 'MiniMax-M2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 204000,
+    maxTokens: 204000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'moonshotai/Kimi-K2.5',
+    provider: 'baseten',
+    name: 'Kimi K2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 3, cacheRead: 0.12, cacheWrite: 0 },
+    contextWindow: 262000,
+    maxTokens: 262000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'moonshotai/Kimi-K2.6',
+    provider: 'baseten',
+    name: 'Kimi K2.6',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
+    contextWindow: 262000,
+    maxTokens: 262000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'moonshotai/Kimi-K2.7-Code',
+    provider: 'baseten',
+    name: 'Kimi K2.7 Code',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
+    contextWindow: 262000,
+    maxTokens: 262000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'moonshotai/Kimi-K3',
+    provider: 'baseten',
+    name: 'Kimi K3',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 3, output: 15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'nvidia/Nemotron-120B-A12B',
+    provider: 'baseten',
+    name: 'Nemotron Super',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.3, output: 0.75, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 202800,
+    maxTokens: 202800,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B',
+    provider: 'baseten',
+    name: 'Nemotron Ultra',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 },
+    contextWindow: 202800,
+    maxTokens: 202800,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'openai/gpt-oss-120b',
+    provider: 'baseten',
+    name: 'OpenAI GPT 120B',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.1, output: 0.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128072,
+    maxTokens: 128072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'thinkingmachines/inkling',
+    provider: 'baseten',
+    name: 'Inkling',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1, output: 4.05, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'thinkingmachines/inkling-small',
+    provider: 'baseten',
+    name: 'Inkling Small',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.5, output: 1.2, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'zai-org/GLM-4.7',
+    provider: 'baseten',
+    name: 'GLM 4.7',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 2.2, cacheRead: 0.12, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 200000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'zai-org/GLM-5',
+    provider: 'baseten',
+    name: 'GLM 5',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.95, output: 3.15, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 202800,
+    maxTokens: 202800,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'zai-org/GLM-5.1',
+    provider: 'baseten',
+    name: 'GLM 5.1',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.3, output: 4.3, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 202800,
+    maxTokens: 202800,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'zai-org/GLM-5.2',
+    provider: 'baseten',
+    name: 'GLM 5.2',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'zai-org/GLM-5.2-Fast',
+    provider: 'baseten',
+    name: 'GLM 5.2 Fast',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 2.1, output: 6.6, cacheRead: 0.21, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'zai-org/GLM-5.3',
+    provider: 'baseten',
+    name: 'GLM 5.3',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.14, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'zai-org/GLM-5.3-Fast',
+    provider: 'baseten',
+    name: 'GLM 5.3 Fast',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 2.1, output: 6.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'zai-org/GLM-5.3-Flash',
+    provider: 'baseten',
+    name: 'GLM 5.3 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://inference.baseten.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsUsageInStreaming: true,
+      maxTokensField: 'max_tokens',
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/cerebras.ts b/packages/ai-models/src/providers/cerebras.ts
new file mode 100644
index 0000000000..e6f4574726
--- /dev/null
+++ b/packages/ai-models/src/providers/cerebras.ts
@@ -0,0 +1,59 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Cerebras. */
+export const provider: ProviderRecord = {
+  id: 'cerebras',
+  name: 'Cerebras',
+  baseUrl: 'https://api.cerebras.ai/v1',
+  apis: ['openai-completions'],
+  env: [['CEREBRAS_API_KEY']],
+}
+
+/** Every Cerebras model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'gpt-oss-120b',
+    provider: 'cerebras',
+    name: 'GPT OSS 120B',
+    api: 'openai-completions',
+    baseUrl: 'https://api.cerebras.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.35, output: 0.75, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 40960,
+    compat: { supportsStore: false, supportsDeveloperRole: false },
+  },
+  {
+    id: 'qwen-3.8-27b',
+    provider: 'cerebras',
+    name: 'Qwen3.8 27B',
+    api: 'openai-completions',
+    baseUrl: 'https://api.cerebras.ai/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.99, output: 1.49, cacheRead: 0.99, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 40960,
+    compat: { supportsStore: false, supportsDeveloperRole: false },
+  },
+]
diff --git a/packages/ai-models/src/providers/cloudflare-ai-gateway.ts b/packages/ai-models/src/providers/cloudflare-ai-gateway.ts
new file mode 100644
index 0000000000..332590ca8c
--- /dev/null
+++ b/packages/ai-models/src/providers/cloudflare-ai-gateway.ts
@@ -0,0 +1,1772 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Cloudflare AI Gateway. */
+export const provider: ProviderRecord = {
+  id: 'cloudflare-ai-gateway',
+  name: 'Cloudflare AI Gateway',
+  baseUrl:
+    'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+  apis: ['anthropic-messages', 'openai-completions', 'openai-responses'],
+  env: [['CLOUDFLARE_API_KEY']],
+}
+
+/** Every Cloudflare AI Gateway model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'alibaba/qwen3-max',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Qwen3 Max',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 1.2, output: 6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+  },
+  {
+    id: 'alibaba/qwen3.5-397b-a17b',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Qwen3.5 397B-A17B',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.6, output: 3.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+  },
+  {
+    id: 'alibaba/qwen3.7-max',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Qwen3.7 Max',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 1.25, output: 3.75, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+  },
+  {
+    id: 'alibaba/qwen3.7-plus',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Qwen3.7 Plus',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.32, output: 1.28, cacheRead: 0.064, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+  },
+  {
+    id: 'alibaba/qwen3.8-max',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Qwen3.8 Max',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'claude-fable-5',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Claude Fable 5',
+    api: 'anthropic-messages',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/anthropic',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'claude-fable-5.1',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Claude Fable 5.1',
+    api: 'anthropic-messages',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/anthropic',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 0.25, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'claude-haiku-4.5',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Claude Haiku 4.5 (latest)',
+    api: 'anthropic-messages',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/anthropic',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+    compat: { sendSessionAffinityHeaders: true },
+  },
+  {
+    id: 'claude-opus-4.5',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Claude Opus 4.5 (latest)',
+    api: 'anthropic-messages',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/anthropic',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+    compat: { sendSessionAffinityHeaders: true },
+  },
+  {
+    id: 'claude-opus-4.6',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Claude Opus 4.6',
+    api: 'anthropic-messages',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/anthropic',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { sendSessionAffinityHeaders: true },
+  },
+  {
+    id: 'claude-opus-4.7',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Claude Opus 4.7',
+    api: 'anthropic-messages',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/anthropic',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'claude-opus-4.8',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Claude Opus 4.8',
+    api: 'anthropic-messages',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/anthropic',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'claude-opus-5',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Claude Opus 5',
+    api: 'anthropic-messages',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/anthropic',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'claude-opus-5.5',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Claude Opus 5.5',
+    api: 'anthropic-messages',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/anthropic',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.2, cacheWrite: 5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'claude-sonnet-4.5',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Claude Sonnet 4.5 (latest)',
+    api: 'anthropic-messages',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/anthropic',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+    compat: { sendSessionAffinityHeaders: true },
+  },
+  {
+    id: 'claude-sonnet-4.6',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Claude Sonnet 4.6',
+    api: 'anthropic-messages',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/anthropic',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { sendSessionAffinityHeaders: true },
+  },
+  {
+    id: 'claude-sonnet-5',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Claude Sonnet 5',
+    api: 'anthropic-messages',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/anthropic',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'deepseek/deepseek-v4-pro',
+    provider: 'cloudflare-ai-gateway',
+    name: 'DeepSeek V4 Pro',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.74, output: 3.48, cacheRead: 0.145, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 384000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'gpt-4.1',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-4.1',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 2, output: 8, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+    compat: { sendSessionAffinityHeaders: false, supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-4.1-mini',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-4.1 mini',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.4, output: 1.6, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+    compat: { sendSessionAffinityHeaders: false, supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-4.1-nano',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-4.1 nano',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.4, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 32768,
+    compat: { sendSessionAffinityHeaders: false, supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-4o',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-4o',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 1.25, output: 5, cacheRead: 0.625, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: { sendSessionAffinityHeaders: false, supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-4o-mini',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-4o mini',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.075, output: 0.3, cacheRead: 0.0375, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: { sendSessionAffinityHeaders: false, supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-5',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-5',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: false,
+      supportsStrictMode: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5-mini',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-5 Mini',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 2, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: false,
+      supportsStrictMode: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5-nano',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-5 Nano',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.05, output: 0.4, cacheRead: 0.005, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: false,
+      supportsStrictMode: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.1',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-5.1',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+    compat: { sendSessionAffinityHeaders: false, supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-5.4',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-5.4',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { sendSessionAffinityHeaders: false, supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-5.4-mini',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-5.4 mini',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.75, output: 4.5, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+    compat: { sendSessionAffinityHeaders: false, supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-5.4-nano',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-5.4 nano',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.2, output: 1.25, cacheRead: 0.02, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+    compat: { sendSessionAffinityHeaders: false, supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-5.4-pro',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-5.4 Pro',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: false,
+      supportsStrictMode: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.5',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-5.5',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 5, output: 30, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: false,
+      supportsStrictMode: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.5-pro',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-5.5 Pro',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: false,
+      supportsStrictMode: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.6-luna',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-5.6 Luna',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: false,
+      supportsStrictMode: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.6-sol',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-5.6 Sol',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.25, cacheWrite: 3.125 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: false,
+      supportsStrictMode: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.6-terra',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-5.6 Terra',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: false,
+      supportsStrictMode: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-6-astra',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-6 Astra',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: false,
+      supportsStrictMode: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-6-luna',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-6 Luna',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: false,
+      supportsStrictMode: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-6-sol',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT-6 Sol',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: false,
+      supportsStrictMode: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'moonshotai/kimi-k3',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Kimi K3',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'o3',
+    provider: 'cloudflare-ai-gateway',
+    name: 'o3',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 8, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      sendSessionAffinityHeaders: false,
+      supportsStrictMode: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'o3-mini',
+    provider: 'cloudflare-ai-gateway',
+    name: 'o3-mini',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.1, output: 4.4, cacheRead: 0.55, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      sendSessionAffinityHeaders: false,
+      supportsStrictMode: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'o4-mini',
+    provider: 'cloudflare-ai-gateway',
+    name: 'o4-mini',
+    api: 'openai-responses',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.1, output: 4.4, cacheRead: 0.275, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      sendSessionAffinityHeaders: false,
+      supportsStrictMode: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'unbiased/pareto',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Pareto',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 2.5, output: 7.5, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+  },
+  {
+    id: 'workers-ai/@cf/deepseek-ai/deepseek-v4-flash-0731',
+    provider: 'cloudflare-ai-gateway',
+    name: 'DeepSeek V4 Flash 0731',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.44, output: 1.32, cacheRead: 0.014, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+    borrowedFrom:
+      'cloudflare-workers-ai/@cf/deepseek-ai/deepseek-v4-flash-0731',
+  },
+  {
+    id: 'workers-ai/@cf/deepseek-ai/deepseek-v4-pro-0813',
+    provider: 'cloudflare-ai-gateway',
+    name: 'DeepSeek V4 Pro 0813',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.32, output: 3.96, cacheRead: 0.044, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+    borrowedFrom: 'cloudflare-workers-ai/@cf/deepseek-ai/deepseek-v4-pro-0813',
+  },
+  {
+    id: 'workers-ai/@cf/google/gemma-4-26b-a4b-it',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Gemma 4 26B A4B IT',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.1, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 16384,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+    borrowedFrom: 'cloudflare-workers-ai/@cf/google/gemma-4-26b-a4b-it',
+  },
+  {
+    id: 'workers-ai/@cf/ibm-granite/granite-4.0-h-micro',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Granite 4.0 H Micro',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.017, output: 0.112, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131000,
+    maxTokens: 131000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+    borrowedFrom: 'cloudflare-workers-ai/@cf/ibm-granite/granite-4.0-h-micro',
+  },
+  {
+    id: 'workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Llama 3.3 70B Instruct fp8 Fast',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.293, output: 2.253, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 24000,
+    maxTokens: 24000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+    borrowedFrom:
+      'cloudflare-workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast',
+  },
+  {
+    id: 'workers-ai/@cf/meta/llama-4-scout-17b-16e-instruct',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Llama 4 Scout 17B 16E Instruct',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.27, output: 0.85, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131000,
+    maxTokens: 16384,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+    borrowedFrom:
+      'cloudflare-workers-ai/@cf/meta/llama-4-scout-17b-16e-instruct',
+  },
+  {
+    id: 'workers-ai/@cf/mistralai/mistral-small-3.1-24b-instruct',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Mistral Small 3.1 24B Instruct',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.351, output: 0.555, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+    borrowedFrom:
+      'cloudflare-workers-ai/@cf/mistralai/mistral-small-3.1-24b-instruct',
+  },
+  {
+    id: 'workers-ai/@cf/moonshotai/kimi-k2.6',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Kimi K2.6',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 256000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+    borrowedFrom: 'cloudflare-workers-ai/@cf/moonshotai/kimi-k2.6',
+  },
+  {
+    id: 'workers-ai/@cf/moonshotai/kimi-k2.7-code',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Kimi K2.7 Code',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.95, output: 4, cacheRead: 0.19, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+    borrowedFrom: 'cloudflare-workers-ai/@cf/moonshotai/kimi-k2.7-code',
+  },
+  {
+    id: 'workers-ai/@cf/nvidia/nemotron-3-120b-a12b',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Nemotron 3 Super 120B',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.5, output: 1.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 256000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+    borrowedFrom: 'cloudflare-workers-ai/@cf/nvidia/nemotron-3-120b-a12b',
+  },
+  {
+    id: 'workers-ai/@cf/openai/gpt-oss-120b',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT OSS 120B',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.35, output: 0.75, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+    borrowedFrom: 'cloudflare-workers-ai/@cf/openai/gpt-oss-120b',
+  },
+  {
+    id: 'workers-ai/@cf/openai/gpt-oss-20b',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GPT OSS 20B',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.2, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+    borrowedFrom: 'cloudflare-workers-ai/@cf/openai/gpt-oss-20b',
+  },
+  {
+    id: 'workers-ai/@cf/qwen/qwen3-30b-a3b-fp8',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Qwen3 30B A3b fp8',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.0509, output: 0.335, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 32768,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+    borrowedFrom: 'cloudflare-workers-ai/@cf/qwen/qwen3-30b-a3b-fp8',
+  },
+  {
+    id: 'workers-ai/@cf/qwen/qwen3.8-27b',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Qwen3.8 27B',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.45, output: 3.2, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+    borrowedFrom: 'cloudflare-workers-ai/@cf/qwen/qwen3.8-27b',
+  },
+  {
+    id: 'workers-ai/@cf/zai-org/glm-4.7-flash',
+    provider: 'cloudflare-ai-gateway',
+    name: 'GLM-4.7-Flash',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.0605, output: 0.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+    borrowedFrom: 'cloudflare-workers-ai/@cf/zai-org/glm-4.7-flash',
+  },
+  {
+    id: 'workers-ai/@cf/zai-org/glm-5.2',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Glm 5.2',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 256000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+    borrowedFrom: 'cloudflare-workers-ai/@cf/zai-org/glm-5.2',
+  },
+  {
+    id: 'workers-ai/@cf/zai-org/glm-5.3',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Glm 5.3',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+    borrowedFrom: 'cloudflare-workers-ai/@cf/zai-org/glm-5.3',
+  },
+  {
+    id: 'workers-ai/@cf/zai-org/glm-5.3-flash',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Glm 5.3 Flash',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+    borrowedFrom: 'cloudflare-workers-ai/@cf/zai-org/glm-5.3-flash',
+  },
+  {
+    id: 'xai/grok-4.20-0309-non-reasoning',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Grok 4.20 (Non-Reasoning)',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 2, output: 6, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 2000000,
+    maxTokens: 30000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+  },
+  {
+    id: 'xai/grok-4.20-0309-reasoning',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Grok 4.20 (Reasoning)',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    cost: { input: 2, output: 6, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 2000000,
+    maxTokens: 30000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+  },
+  {
+    id: 'xai/grok-4.3',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Grok 4.3',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 30000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+  },
+  {
+    id: 'xai/grok-4.5',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Grok 4.5',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+  },
+  {
+    id: 'xai/grok-4.6',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Grok 4.6',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+  },
+  {
+    id: 'xai/grok-4.7',
+    provider: 'cloudflare-ai-gateway',
+    name: 'Grok 4.7',
+    api: 'openai-completions',
+    baseUrl:
+      'https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/compat',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/cloudflare-workers-ai.ts b/packages/ai-models/src/providers/cloudflare-workers-ai.ts
new file mode 100644
index 0000000000..2387bd7a66
--- /dev/null
+++ b/packages/ai-models/src/providers/cloudflare-workers-ai.ts
@@ -0,0 +1,670 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Cloudflare Workers AI. */
+export const provider: ProviderRecord = {
+  id: 'cloudflare-workers-ai',
+  name: 'Cloudflare Workers AI',
+  baseUrl:
+    'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+  apis: ['openai-completions'],
+  env: [['CLOUDFLARE_API_KEY']],
+}
+
+/** Every Cloudflare Workers AI model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: '@cf/aisingapore/gemma-sea-lion-v4-27b-it',
+    provider: 'cloudflare-workers-ai',
+    name: 'Gemma Sea Lion V4 27B It',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.351, output: 0.555, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/deepseek-ai/deepseek-r1-distill-qwen-32b',
+    provider: 'cloudflare-workers-ai',
+    name: 'Deepseek R1 Distill Qwen 32B',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.497, output: 4.881, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 80000,
+    maxTokens: 80000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: '@cf/deepseek-ai/deepseek-v4-flash-0731',
+    provider: 'cloudflare-workers-ai',
+    name: 'DeepSeek V4 Flash 0731',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.44, output: 1.32, cacheRead: 0.014, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: '@cf/deepseek-ai/deepseek-v4-pro-0813',
+    provider: 'cloudflare-workers-ai',
+    name: 'DeepSeek V4 Pro 0813',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.32, output: 3.96, cacheRead: 0.044, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: '@cf/google/gemma-4-26b-a4b-it',
+    provider: 'cloudflare-workers-ai',
+    name: 'Gemma 4 26B A4B IT',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.1, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 16384,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/ibm-granite/granite-4.0-h-micro',
+    provider: 'cloudflare-workers-ai',
+    name: 'Granite 4.0 H Micro',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.017, output: 0.112, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131000,
+    maxTokens: 131000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/meta/llama-3.1-8b-instruct-fp8',
+    provider: 'cloudflare-workers-ai',
+    name: 'Llama 3.1 8B Instruct fp8',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.152, output: 0.287, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 32000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/meta/llama-3.2-11b-vision-instruct',
+    provider: 'cloudflare-workers-ai',
+    name: 'Llama 3.2 11B Vision Instruct',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.0485, output: 0.676, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/meta/llama-3.2-1b-instruct',
+    provider: 'cloudflare-workers-ai',
+    name: 'Llama 3.2 1B Instruct',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.027, output: 0.201, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 60000,
+    maxTokens: 60000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/meta/llama-3.2-3b-instruct',
+    provider: 'cloudflare-workers-ai',
+    name: 'Llama 3.2 3B Instruct',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.0509, output: 0.335, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 80000,
+    maxTokens: 80000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/meta/llama-3.3-70b-instruct-fp8-fast',
+    provider: 'cloudflare-workers-ai',
+    name: 'Llama 3.3 70B Instruct fp8 Fast',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.293, output: 2.253, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 24000,
+    maxTokens: 24000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/meta/llama-4-scout-17b-16e-instruct',
+    provider: 'cloudflare-workers-ai',
+    name: 'Llama 4 Scout 17B 16E Instruct',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.27, output: 0.85, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131000,
+    maxTokens: 16384,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/meta/llama-guard-3-8b',
+    provider: 'cloudflare-workers-ai',
+    name: 'Llama Guard 3 8B',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.484, output: 0.03, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/mistralai/mistral-small-3.1-24b-instruct',
+    provider: 'cloudflare-workers-ai',
+    name: 'Mistral Small 3.1 24B Instruct',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.351, output: 0.555, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/moonshotai/kimi-k2.6',
+    provider: 'cloudflare-workers-ai',
+    name: 'Kimi K2.6',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 256000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: '@cf/moonshotai/kimi-k2.7-code',
+    provider: 'cloudflare-workers-ai',
+    name: 'Kimi K2.7 Code',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.95, output: 4, cacheRead: 0.19, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/nvidia/nemotron-3-120b-a12b',
+    provider: 'cloudflare-workers-ai',
+    name: 'Nemotron 3 Super 120B',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.5, output: 1.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 256000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/openai/gpt-oss-120b',
+    provider: 'cloudflare-workers-ai',
+    name: 'GPT OSS 120B',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.35, output: 0.75, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/openai/gpt-oss-20b',
+    provider: 'cloudflare-workers-ai',
+    name: 'GPT OSS 20B',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.2, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/qwen/qwen2.5-coder-32b-instruct',
+    provider: 'cloudflare-workers-ai',
+    name: 'Qwen2.5 Coder 32B Instruct',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.66, output: 1, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/qwen/qwen3-30b-a3b-fp8',
+    provider: 'cloudflare-workers-ai',
+    name: 'Qwen3 30B A3b fp8',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.0509, output: 0.335, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/qwen/qwen3.8-27b',
+    provider: 'cloudflare-workers-ai',
+    name: 'Qwen3.8 27B',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.45, output: 3.2, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/qwen/qwq-32b',
+    provider: 'cloudflare-workers-ai',
+    name: 'Qwq 32B',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.66, output: 1, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 24000,
+    maxTokens: 24000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/zai-org/glm-4.7-flash',
+    provider: 'cloudflare-workers-ai',
+    name: 'GLM-4.7-Flash',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.0605, output: 0.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: '@cf/zai-org/glm-5.2',
+    provider: 'cloudflare-workers-ai',
+    name: 'Glm 5.2',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 256000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/zai-org/glm-5.3',
+    provider: 'cloudflare-workers-ai',
+    name: 'Glm 5.3',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+  {
+    id: '@cf/zai-org/glm-5.3-flash',
+    provider: 'cloudflare-workers-ai',
+    name: 'Glm 5.3 Flash',
+    api: 'openai-completions',
+    baseUrl:
+      'https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      supportsLongCacheRetention: false,
+      sendSessionAffinityHeaders: true,
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/deepseek.ts b/packages/ai-models/src/providers/deepseek.ts
new file mode 100644
index 0000000000..ae7737491b
--- /dev/null
+++ b/packages/ai-models/src/providers/deepseek.ts
@@ -0,0 +1,131 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** DeepSeek. */
+export const provider: ProviderRecord = {
+  id: 'deepseek',
+  name: 'DeepSeek',
+  baseUrl: 'https://api.deepseek.com',
+  apis: ['openai-completions'],
+  env: [['DEEPSEEK_API_KEY']],
+}
+
+/** Every DeepSeek model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'deepseek-flash',
+    provider: 'deepseek',
+    name: 'DeepSeek V4.1 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://api.deepseek.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.003, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 393216,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+      supportsStrictMode: true,
+    },
+  },
+  {
+    id: 'deepseek-v4-flash',
+    provider: 'deepseek',
+    name: 'DeepSeek V4 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://api.deepseek.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.003, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 393216,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+      supportsStrictMode: true,
+    },
+  },
+  {
+    id: 'deepseek-v4-flash-vision-exp',
+    provider: 'deepseek',
+    name: 'DeepSeek V4 Flash Vision Exp',
+    api: 'openai-completions',
+    baseUrl: 'https://api.deepseek.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.003, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 393216,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+      supportsStrictMode: true,
+    },
+  },
+  {
+    id: 'deepseek-v4-pro',
+    provider: 'deepseek',
+    name: 'DeepSeek V4 Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://api.deepseek.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.003625, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 393216,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+      supportsStrictMode: true,
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/fireworks.ts b/packages/ai-models/src/providers/fireworks.ts
new file mode 100644
index 0000000000..b50dc03b2f
--- /dev/null
+++ b/packages/ai-models/src/providers/fireworks.ts
@@ -0,0 +1,971 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Fireworks AI. */
+export const provider: ProviderRecord = {
+  id: 'fireworks',
+  name: 'Fireworks AI',
+  baseUrl: 'https://api.fireworks.ai/inference/v1',
+  apis: ['anthropic-messages', 'openai-completions'],
+  env: [['FIREWORKS_API_KEY']],
+}
+
+/** Every Fireworks AI model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'accounts/fireworks/models/deepseek-v4-flash-0731',
+    provider: 'fireworks',
+    name: 'DeepSeek V4 Flash 0731',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.06, output: 0.18, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 384000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+    },
+    borrowedFrom: 'deepinfra/deepseek-ai/DeepSeek-V4-Flash-0731',
+  },
+  {
+    id: 'accounts/fireworks/models/deepseek-v4-flash-vision-exp',
+    provider: 'fireworks',
+    name: 'DeepSeek V4 Flash Vision Exp',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.003, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 393216,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+      forceAdaptiveThinking: true,
+    },
+    borrowedFrom: 'deepseek/deepseek-v4-flash-vision-exp',
+  },
+  {
+    id: 'accounts/fireworks/models/deepseek-v4-pro',
+    provider: 'fireworks',
+    name: 'DeepSeek V4 Pro',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.003625, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 393216,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+      forceAdaptiveThinking: true,
+    },
+    borrowedFrom: 'deepseek/deepseek-v4-pro',
+  },
+  {
+    id: 'accounts/fireworks/models/deepseek-v4-pro-0813',
+    provider: 'fireworks',
+    name: 'DeepSeek V4 Pro 0813',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.3, output: 2.6, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 384000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+      forceAdaptiveThinking: true,
+    },
+    borrowedFrom: 'deepinfra/deepseek-ai/DeepSeek-V4-Pro-0813',
+  },
+  {
+    id: 'accounts/fireworks/models/deepseek-v4p1-flash',
+    provider: 'fireworks',
+    name: 'DeepSeek V4.1 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.22, output: 0.66, cacheRead: 0.007, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'accounts/fireworks/models/ember-1',
+    provider: 'fireworks',
+    name: 'Ember-1',
+    api: 'openai-completions',
+    baseUrl: 'https://api.fireworks.ai/inference/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'accounts/fireworks/models/glm-5p2',
+    provider: 'fireworks',
+    name: 'GLM-5.2',
+    api: 'openai-completions',
+    baseUrl: 'https://api.fireworks.ai/inference/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+    borrowedFrom: 'zai/glm-5.2',
+  },
+  {
+    id: 'accounts/fireworks/models/glm-5p3',
+    provider: 'fireworks',
+    name: 'GLM 5.3',
+    api: 'openai-completions',
+    baseUrl: 'https://api.fireworks.ai/inference/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1048573,
+    maxTokens: 262144,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'accounts/fireworks/models/glm-5p3-flash',
+    provider: 'fireworks',
+    name: 'GLM 5.3 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://api.fireworks.ai/inference/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1048573,
+    maxTokens: 131072,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'accounts/fireworks/models/gpt-oss-120b',
+    provider: 'fireworks',
+    name: 'GPT OSS 120B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'accounts/fireworks/models/inkling',
+    provider: 'fireworks',
+    name: 'Inkling',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text', 'image', 'audio'],
+    reasoning: true,
+    cost: { input: 1, output: 4.05, cacheRead: 0.17, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+    },
+  },
+  {
+    id: 'accounts/fireworks/models/kimi-k2p6',
+    provider: 'fireworks',
+    name: 'Kimi K2.6',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+    },
+    borrowedFrom: 'moonshotai/kimi-k2.6',
+  },
+  {
+    id: 'accounts/fireworks/models/kimi-k2p7-code',
+    provider: 'fireworks',
+    name: 'Kimi K2.7 Code',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    cost: { input: 0.95, output: 4, cacheRead: 0.19, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+      supportsTemperature: false,
+    },
+    borrowedFrom: 'moonshotai/kimi-k2.7-code',
+  },
+  {
+    id: 'accounts/fireworks/models/kimi-k3',
+    provider: 'fireworks',
+    name: 'Kimi K3',
+    api: 'openai-completions',
+    baseUrl: 'https://api.fireworks.ai/inference/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'accounts/fireworks/models/minimax-m2p7',
+    provider: 'fireworks',
+    name: 'MiniMax-M2.7',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+    },
+    borrowedFrom: 'minimax/MiniMax-M2.7',
+  },
+  {
+    id: 'accounts/fireworks/models/minimax-m3',
+    provider: 'fireworks',
+    name: 'MiniMax-M3',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 512000,
+    maxTokens: 512000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'accounts/fireworks/models/muse-glimmer-30b',
+    provider: 'fireworks',
+    name: 'Muse Glimmer 30B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.2, output: 0.8, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+      forceAdaptiveThinking: true,
+    },
+    borrowedFrom: 'empiriolabs/muse-glimmer-30b',
+  },
+  {
+    id: 'accounts/fireworks/models/nemotron-3-ultra-nvfp4',
+    provider: 'fireworks',
+    name: 'Nemotron 3 Ultra 550B A55B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 128000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+    },
+  },
+  {
+    id: 'accounts/fireworks/models/nemotron-lightning-3p5-30b-a3b',
+    provider: 'fireworks',
+    name: 'Nemotron 3.5 Lightning 30B A3B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.05, output: 0.2, cacheRead: 0.01, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+    },
+  },
+  {
+    id: 'accounts/fireworks/models/qwen3p7-plus',
+    provider: 'fireworks',
+    name: 'Qwen3.7 Plus',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.4, output: 1.6, cacheRead: 0.04, cacheWrite: 0.5 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+    },
+    borrowedFrom: 'alibaba/qwen3.7-plus',
+  },
+  {
+    id: 'accounts/fireworks/models/qwen3p8-2p4t-a95b',
+    provider: 'fireworks',
+    name: 'Qwen3.8 2.4T A95B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'accounts/fireworks/models/qwen3p8-max',
+    provider: 'fireworks',
+    name: 'Qwen3.8 Max',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+    },
+  },
+  {
+    id: 'accounts/fireworks/routers/deepseek-flash-latest',
+    provider: 'fireworks',
+    name: 'DeepSeek Flash Latest',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.22, output: 0.66, cacheRead: 0.007, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'accounts/fireworks/routers/deepseek-pro-latest',
+    provider: 'fireworks',
+    name: 'DeepSeek: DeepSeek Pro Latest',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.123, output: 3.5, cacheRead: 0.123, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 393216,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+      forceAdaptiveThinking: true,
+    },
+    borrowedFrom: 'kilo/~deepseek/deepseek-pro-latest',
+  },
+  {
+    id: 'accounts/fireworks/routers/glm-5p2-fast',
+    provider: 'fireworks',
+    name: 'GLM 5.2 Fast',
+    api: 'openai-completions',
+    baseUrl: 'https://api.fireworks.ai/inference/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 2.1, output: 6.6, cacheRead: 0.21, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 262144,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+    borrowedFrom: 'baseten/zai-org/GLM-5.2-Fast',
+  },
+  {
+    id: 'accounts/fireworks/routers/glm-5p3-fast',
+    provider: 'fireworks',
+    name: 'GLM 5.3 Fast',
+    api: 'openai-completions',
+    baseUrl: 'https://api.fireworks.ai/inference/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 2.1, output: 6.6, cacheRead: 0.39, cacheWrite: 0 },
+    contextWindow: 1048572,
+    maxTokens: 262144,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'accounts/fireworks/routers/glm-fast-latest',
+    provider: 'fireworks',
+    name: 'GLM 5.3 Fast (Latest)',
+    api: 'openai-completions',
+    baseUrl: 'https://api.fireworks.ai/inference/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 2.1, output: 6.6, cacheRead: 0.39, cacheWrite: 0 },
+    contextWindow: 1048572,
+    maxTokens: 262144,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'accounts/fireworks/routers/glm-flash-latest',
+    provider: 'fireworks',
+    name: 'GLM Flash Latest (GLM 5.3 Flash)',
+    api: 'openai-completions',
+    baseUrl: 'https://api.fireworks.ai/inference/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1048573,
+    maxTokens: 131072,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'accounts/fireworks/routers/glm-latest',
+    provider: 'fireworks',
+    name: 'GLM Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://api.fireworks.ai/inference/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1048573,
+    maxTokens: 262144,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'accounts/fireworks/routers/kimi-fast-latest',
+    provider: 'fireworks',
+    name: 'Kimi Fast Latest',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 4.5, output: 22.5, cacheRead: 0.45, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'accounts/fireworks/routers/kimi-k3-fast',
+    provider: 'fireworks',
+    name: 'Kimi K3 Fast',
+    api: 'openai-completions',
+    baseUrl: 'https://api.fireworks.ai/inference/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 4.5, output: 22.5, cacheRead: 0.45, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'accounts/fireworks/routers/kimi-latest',
+    provider: 'fireworks',
+    name: 'Kimi Latest',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'accounts/fireworks/routers/minimax-latest',
+    provider: 'fireworks',
+    name: 'MiniMax Latest',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 512000,
+    maxTokens: 512000,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'accounts/fireworks/routers/qwen-max-latest',
+    provider: 'fireworks',
+    name: 'Qwen Max Latest (Qwen3.8 Max)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.fireworks.ai/inference',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: {
+      sendSessionAffinityHeaders: true,
+      supportsLongCacheRetention: false,
+      allowEmptySignature: true,
+      supportsEagerToolInputStreaming: false,
+      supportsCacheControlOnTools: false,
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/google-vertex.ts b/packages/ai-models/src/providers/google-vertex.ts
new file mode 100644
index 0000000000..8b8c4e3311
--- /dev/null
+++ b/packages/ai-models/src/providers/google-vertex.ts
@@ -0,0 +1,940 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Google Vertex AI. */
+export const provider: ProviderRecord = {
+  id: 'google-vertex',
+  name: 'Google Vertex AI',
+  baseUrl: 'https://{location}-aiplatform.googleapis.com',
+  apis: ['google-vertex'],
+  env: [
+    ['GOOGLE_CLOUD_API_KEY'],
+    [
+      'GOOGLE_APPLICATION_CREDENTIALS',
+      'GOOGLE_CLOUD_PROJECT',
+      'GOOGLE_CLOUD_LOCATION',
+    ],
+    [
+      'GOOGLE_APPLICATION_CREDENTIALS',
+      'GCLOUD_PROJECT',
+      'GOOGLE_CLOUD_LOCATION',
+    ],
+  ],
+}
+
+/** Every Google Vertex AI model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'claude-fable-5-1@default',
+    provider: 'google-vertex',
+    name: 'Claude Fable 5.1',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 0.25, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'claude-fable-5@default',
+    provider: 'google-vertex',
+    name: 'Claude Fable 5',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'claude-haiku-4-5@20251001',
+    provider: 'google-vertex',
+    name: 'Claude Haiku 4.5',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'claude-opus-4-1@20250805',
+    provider: 'google-vertex',
+    name: 'Claude Opus 4.1',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+    contextWindow: 200000,
+    maxTokens: 32000,
+  },
+  {
+    id: 'claude-opus-4-5@20251101',
+    provider: 'google-vertex',
+    name: 'Claude Opus 4.5',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'claude-opus-4-6@default',
+    provider: 'google-vertex',
+    name: 'Claude Opus 4.6',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'claude-opus-4-7@default',
+    provider: 'google-vertex',
+    name: 'Claude Opus 4.7',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'claude-opus-4-8@default',
+    provider: 'google-vertex',
+    name: 'Claude Opus 4.8',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'claude-opus-4@20250514',
+    provider: 'google-vertex',
+    name: 'Claude Opus 4',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+    contextWindow: 200000,
+    maxTokens: 32000,
+  },
+  {
+    id: 'claude-opus-5-5@default',
+    provider: 'google-vertex',
+    name: 'Claude Opus 5.5',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.2, cacheWrite: 5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'claude-opus-5@default',
+    provider: 'google-vertex',
+    name: 'Claude Opus 5',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'claude-sonnet-4-5@20250929',
+    provider: 'google-vertex',
+    name: 'Claude Sonnet 4.5',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'claude-sonnet-4-6@default',
+    provider: 'google-vertex',
+    name: 'Claude Sonnet 4.6',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'claude-sonnet-4@20250514',
+    provider: 'google-vertex',
+    name: 'Claude Sonnet 4',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'claude-sonnet-5-5@default',
+    provider: 'google-vertex',
+    name: 'Claude Sonnet 5.5',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'claude-sonnet-5@default',
+    provider: 'google-vertex',
+    name: 'Claude Sonnet 5',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'deepseek-ai/deepseek-v3.1-maas',
+    provider: 'google-vertex',
+    name: 'DeepSeek V3.1',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'document'],
+    reasoning: true,
+    cost: { input: 0.6, output: 1.7, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 32768,
+  },
+  {
+    id: 'deepseek-ai/deepseek-v3.2-maas',
+    provider: 'google-vertex',
+    name: 'DeepSeek V3.2',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'document'],
+    reasoning: true,
+    cost: { input: 0.56, output: 1.68, cacheRead: 0.056, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-2.5-flash',
+    provider: 'google-vertex',
+    name: 'Gemini 2.5 Flash',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.3, output: 2.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-2.5-flash-image',
+    provider: 'google-vertex',
+    name: 'Nano Banana',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.3, output: 30, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 32768,
+  },
+  {
+    id: 'gemini-2.5-flash-lite',
+    provider: 'google-vertex',
+    name: 'Gemini 2.5 Flash-Lite',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.1, output: 0.4, cacheRead: 0.01, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65535,
+  },
+  {
+    id: 'gemini-2.5-pro',
+    provider: 'google-vertex',
+    name: 'Gemini 2.5 Pro',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3-flash-preview',
+    provider: 'google-vertex',
+    name: 'Gemini 3 Flash Preview',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3-pro-image',
+    provider: 'google-vertex',
+    name: 'Nano Banana Pro',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 2, output: 120, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 65536,
+    maxTokens: 32768,
+  },
+  {
+    id: 'gemini-3.1-flash-image',
+    provider: 'google-vertex',
+    name: 'Nano Banana 2',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.5, output: 60, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+  },
+  {
+    id: 'gemini-3.1-flash-lite',
+    provider: 'google-vertex',
+    name: 'Gemini 3.1 Flash Lite',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 1.5, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.1-flash-lite-preview',
+    provider: 'google-vertex',
+    name: 'Gemini 3.1 Flash Lite Preview',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 1.5, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.1-pro-preview',
+    provider: 'google-vertex',
+    name: 'Gemini 3.1 Pro Preview',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.1-pro-preview-customtools',
+    provider: 'google-vertex',
+    name: 'Gemini 3.1 Pro Preview Custom Tools',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.5-flash',
+    provider: 'google-vertex',
+    name: 'Gemini 3.5 Flash',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.5, output: 9, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.5-flash-lite',
+    provider: 'google-vertex',
+    name: 'Gemini 3.5 Flash Lite',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.3, output: 2.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.6-flash',
+    provider: 'google-vertex',
+    name: 'Gemini 3.6 Flash',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.7-flash',
+    provider: 'google-vertex',
+    name: 'Gemini 3.7 Flash',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.8-flash',
+    provider: 'google-vertex',
+    name: 'Gemini 3.8 Flash',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-embedding-001',
+    provider: 'google-vertex',
+    name: 'Gemini Embedding 001',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 2048,
+    maxTokens: 1,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gemini-flash-latest',
+    provider: 'google-vertex',
+    name: 'Gemini Flash Latest',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.5, output: 9, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-flash-lite-latest',
+    provider: 'google-vertex',
+    name: 'Gemini Flash-Lite Latest',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 1.5, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'meta/llama-3.3-70b-instruct-maas',
+    provider: 'google-vertex',
+    name: 'Llama 3.3 70B Instruct',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.72, output: 0.72, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'meta/llama-4-maverick-17b-128e-instruct-maas',
+    provider: 'google-vertex',
+    name: 'Llama 4 Maverick 17B 128E Instruct',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.35, output: 1.15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 524288,
+    maxTokens: 8192,
+  },
+  {
+    id: 'moonshotai/kimi-k2-thinking-maas',
+    provider: 'google-vertex',
+    name: 'Kimi K2 Thinking',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.6, output: 2.5, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+  },
+  {
+    id: 'openai/gpt-oss-120b-maas',
+    provider: 'google-vertex',
+    name: 'GPT OSS 120B',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.09, output: 0.36, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+  },
+  {
+    id: 'openai/gpt-oss-20b-maas',
+    provider: 'google-vertex',
+    name: 'GPT OSS 20B',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.07, output: 0.25, cacheRead: 0.007, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+  },
+  {
+    id: 'qwen/qwen3-235b-a22b-instruct-2507-maas',
+    provider: 'google-vertex',
+    name: 'Qwen3 235B A22B Instruct',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.22, output: 0.88, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 16384,
+  },
+  {
+    id: 'xai/grok-4.1-fast-non-reasoning',
+    provider: 'google-vertex',
+    name: 'Grok 4.1 Fast',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.2, output: 0.5, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 30000,
+  },
+  {
+    id: 'xai/grok-4.1-fast-reasoning',
+    provider: 'google-vertex',
+    name: 'Grok 4.1 Fast (Reasoning)',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.2, output: 0.5, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 30000,
+  },
+  {
+    id: 'xai/grok-4.20-non-reasoning',
+    provider: 'google-vertex',
+    name: 'Grok 4.20 (Non-Reasoning)',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 2000000,
+    maxTokens: 30000,
+  },
+  {
+    id: 'xai/grok-4.20-reasoning',
+    provider: 'google-vertex',
+    name: 'Grok 4.20 (Reasoning)',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 2000000,
+    maxTokens: 30000,
+  },
+  {
+    id: 'xai/grok-4.3',
+    provider: 'google-vertex',
+    name: 'Grok 4.3',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 30000,
+  },
+  {
+    id: 'xai/grok-4.6',
+    provider: 'google-vertex',
+    name: 'Grok 4.6',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 524288,
+    maxTokens: 500000,
+  },
+  {
+    id: 'zai-org/glm-4.7-maas',
+    provider: 'google-vertex',
+    name: 'GLM-4.7',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 2.2, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'zai-org/glm-5-maas',
+    provider: 'google-vertex',
+    name: 'GLM-5',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1, output: 3.2, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'zai-org/glm-5.2-maas',
+    provider: 'google-vertex',
+    name: 'GLM-5.2',
+    api: 'google-vertex',
+    baseUrl: 'https://{location}-aiplatform.googleapis.com',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.14, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+  },
+]
diff --git a/packages/ai-models/src/providers/google.ts b/packages/ai-models/src/providers/google.ts
new file mode 100644
index 0000000000..6b88b186c4
--- /dev/null
+++ b/packages/ai-models/src/providers/google.ts
@@ -0,0 +1,585 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Google. */
+export const provider: ProviderRecord = {
+  id: 'google',
+  name: 'Google',
+  baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+  apis: ['google-generative-ai'],
+  env: [['GEMINI_API_KEY']],
+}
+
+/** Every Google model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'deep-research-max-preview-04-2026',
+    provider: 'google',
+    name: 'Deep Research Max Preview (Apr-21-2026)',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 65536,
+  },
+  {
+    id: 'deep-research-preview-04-2026',
+    provider: 'google',
+    name: 'Deep Research Preview (Apr-21-2026)',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-2.5-computer-use-preview-10-2025',
+    provider: 'google',
+    name: 'Gemini 2.5 Computer Use Preview 10-2025',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 1.25, output: 10, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'gemini-2.5-flash',
+    provider: 'google',
+    name: 'Gemini 2.5 Flash',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.3, output: 2.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-2.5-flash-image',
+    provider: 'google',
+    name: 'Nano Banana',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.3, output: 30, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 32768,
+  },
+  {
+    id: 'gemini-2.5-flash-lite',
+    provider: 'google',
+    name: 'Gemini 2.5 Flash-Lite',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.1, output: 0.4, cacheRead: 0.01, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-2.5-pro',
+    provider: 'google',
+    name: 'Gemini 2.5 Pro',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3-flash-preview',
+    provider: 'google',
+    name: 'Gemini 3 Flash Preview',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3-pro-image',
+    provider: 'google',
+    name: 'Nano Banana Pro',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 120, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 65536,
+    maxTokens: 32768,
+  },
+  {
+    id: 'gemini-3-pro-image-preview',
+    provider: 'google',
+    name: 'Nano Banana Pro',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 2, output: 120, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+  },
+  {
+    id: 'gemini-3.1-flash-image',
+    provider: 'google',
+    name: 'Nano Banana 2',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.5, output: 60, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+  },
+  {
+    id: 'gemini-3.1-flash-image-preview',
+    provider: 'google',
+    name: 'Nano Banana 2',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.5, output: 60, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 65536,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.1-flash-lite',
+    provider: 'google',
+    name: 'Gemini 3.1 Flash Lite',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 1.5, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.1-flash-lite-image',
+    provider: 'google',
+    name: 'Nano Banana 2 Lite',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 30, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 65536,
+    maxTokens: 4096,
+  },
+  {
+    id: 'gemini-3.1-flash-lite-preview',
+    provider: 'google',
+    name: 'Gemini 3.1 Flash Lite Preview',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 1.5, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.1-flash-live-preview',
+    provider: 'google',
+    name: 'Gemini 3.1 Flash Live Preview',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.75, output: 4.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.1-pro-preview',
+    provider: 'google',
+    name: 'Gemini 3.1 Pro Preview',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.1-pro-preview-customtools',
+    provider: 'google',
+    name: 'Gemini 3.1 Pro Preview Custom Tools',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.5-flash',
+    provider: 'google',
+    name: 'Gemini 3.5 Flash',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.5, output: 9, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.5-flash-lite',
+    provider: 'google',
+    name: 'Gemini 3.5 Flash Lite',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.3, output: 2.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.5-live-translate-preview',
+    provider: 'google',
+    name: 'Gemini 3.5 Live Translate Preview',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['audio'],
+    reasoning: false,
+    cost: { input: 3.5, output: 21, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 16384,
+    maxTokens: 32768,
+  },
+  {
+    id: 'gemini-3.6-flash',
+    provider: 'google',
+    name: 'Gemini 3.6 Flash',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.7-flash',
+    provider: 'google',
+    name: 'Gemini 3.7 Flash',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.8-flash',
+    provider: 'google',
+    name: 'Gemini 3.8 Flash',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-embedding-001',
+    provider: 'google',
+    name: 'Gemini Embedding 001',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 2048,
+    maxTokens: 1,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gemini-embedding-2',
+    provider: 'google',
+    name: 'Gemini Embedding 2',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: false,
+    cost: { input: 0.2, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'gemini-flash-latest',
+    provider: 'google',
+    name: 'Gemini Flash Latest',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-flash-lite-latest',
+    provider: 'google',
+    name: 'Gemini Flash-Lite Latest',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.3, output: 2.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemma-4-26b-a4b-it',
+    provider: 'google',
+    name: 'Gemma 4 26B A4B IT',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+  },
+  {
+    id: 'gemma-4-31b-it',
+    provider: 'google',
+    name: 'Gemma 4 31B IT',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+  },
+  {
+    id: 'lyria-3-clip-preview',
+    provider: 'google',
+    name: 'Lyria 3 Clip Preview',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'lyria-3-pro-preview',
+    provider: 'google',
+    name: 'Lyria 3 Pro Preview',
+    api: 'google-generative-ai',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+]
diff --git a/packages/ai-models/src/providers/groq.ts b/packages/ai-models/src/providers/groq.ts
new file mode 100644
index 0000000000..45dd08b3f3
--- /dev/null
+++ b/packages/ai-models/src/providers/groq.ts
@@ -0,0 +1,242 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Groq. */
+export const provider: ProviderRecord = {
+  id: 'groq',
+  name: 'Groq',
+  baseUrl: 'https://api.groq.com/openai/v1',
+  apis: ['openai-completions'],
+  env: [['GROQ_API_KEY']],
+}
+
+/** Every Groq model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'allam-2-7b',
+    provider: 'groq',
+    name: 'ALLaM-2-7b',
+    api: 'openai-completions',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 4096,
+    maxTokens: 4096,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'groq/compound',
+    provider: 'groq',
+    name: 'Compound',
+    api: 'openai-completions',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 8192,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'groq/compound-mini',
+    provider: 'groq',
+    name: 'Compound Mini',
+    api: 'openai-completions',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 8192,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'llama-3.1-8b-instant',
+    provider: 'groq',
+    name: 'Llama 3.1 8B',
+    api: 'openai-completions',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.05, output: 0.08, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'llama-3.3-70b-versatile',
+    provider: 'groq',
+    name: 'Llama 3.3 70B',
+    api: 'openai-completions',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.59, output: 0.79, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'meta-llama/llama-prompt-guard-2-22m',
+    provider: 'groq',
+    name: 'Llama Prompt Guard 2 22M',
+    api: 'openai-completions',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.03, output: 0.03, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 512,
+    maxTokens: 512,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'meta-llama/llama-prompt-guard-2-86m',
+    provider: 'groq',
+    name: 'Prompt Guard 2 86M',
+    api: 'openai-completions',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.04, output: 0.04, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 512,
+    maxTokens: 512,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'openai/gpt-oss-120b',
+    provider: 'groq',
+    name: 'GPT OSS 120B',
+    api: 'openai-completions',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 65536,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'openai/gpt-oss-20b',
+    provider: 'groq',
+    name: 'GPT OSS 20B',
+    api: 'openai-completions',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.075, output: 0.3, cacheRead: 0.0375, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 65536,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'openai/gpt-oss-safeguard-20b',
+    provider: 'groq',
+    name: 'Safety GPT OSS 20B',
+    api: 'openai-completions',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.075, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 65536,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'qwen/qwen3.6-27b',
+    provider: 'groq',
+    name: 'Qwen3.6 27B',
+    api: 'openai-completions',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: null,
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.6, output: 3, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'qwen/qwen3.8-27b',
+    provider: 'groq',
+    name: 'Qwen3.8 27B',
+    api: 'openai-completions',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.8, output: 4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131042,
+    maxTokens: 16384,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'whisper-large-v3',
+    provider: 'groq',
+    name: 'Whisper',
+    api: 'openai-completions',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    input: ['audio'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'whisper-large-v3-turbo',
+    provider: 'groq',
+    name: 'Whisper Large V3 Turbo',
+    api: 'openai-completions',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    input: ['audio'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { supportsStrictMode: true },
+  },
+]
diff --git a/packages/ai-models/src/providers/huggingface.ts b/packages/ai-models/src/providers/huggingface.ts
new file mode 100644
index 0000000000..7d74b578a1
--- /dev/null
+++ b/packages/ai-models/src/providers/huggingface.ts
@@ -0,0 +1,1284 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Hugging Face. */
+export const provider: ProviderRecord = {
+  id: 'huggingface',
+  name: 'Hugging Face',
+  baseUrl: 'https://router.huggingface.co/v1',
+  apis: ['openai-completions'],
+  env: [['HF_TOKEN']],
+}
+
+/** Every Hugging Face model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'deepseek-ai/DeepSeek-R1',
+    provider: 'huggingface',
+    name: 'DeepSeek-R1',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.7, output: 2.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 64000,
+    maxTokens: 32768,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-R1-0528',
+    provider: 'huggingface',
+    name: 'DeepSeek-R1-0528',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 3, output: 5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 163840,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V3',
+    provider: 'huggingface',
+    name: 'DeepSeek-V3',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.4, output: 1.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 64000,
+    maxTokens: 8192,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V3-0324',
+    provider: 'huggingface',
+    name: 'DeepSeek V3 0324',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.27, output: 1.12, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 163840,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V3.1',
+    provider: 'huggingface',
+    name: 'DeepSeek-V3.1',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.27, output: 1, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 8192,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V3.2',
+    provider: 'huggingface',
+    name: 'DeepSeek-V3.2',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.28, output: 0.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 65536,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V4-Flash',
+    provider: 'huggingface',
+    name: 'DeepSeek V4 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.14, output: 0.28, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 384000,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V4-Flash-0731',
+    provider: 'huggingface',
+    name: 'DeepSeek V4 Flash 0731',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 384000,
+    compat: {
+      supportsStrictMode: true,
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V4-Flash-Vision-Exp',
+    provider: 'huggingface',
+    name: 'DeepSeek V4 Flash Vision Exp',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.44, output: 1.32, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 384000,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V4-Pro',
+    provider: 'huggingface',
+    name: 'DeepSeek V4 Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.003625, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 393216,
+    compat: {
+      supportsStrictMode: true,
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V4-Pro-0813',
+    provider: 'huggingface',
+    name: 'DeepSeek V4 Pro 0813',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.32, output: 3.96, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V4.1-Flash',
+    provider: 'huggingface',
+    name: 'DeepSeek V4.1 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.3, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 384000,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'google/gemma-3-12b-it',
+    provider: 'huggingface',
+    name: 'Gemma 3 12B IT',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.05, output: 0.15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'google/gemma-3-27b-it',
+    provider: 'huggingface',
+    name: 'Gemma 3 27B IT',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.08, output: 0.16, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'google/gemma-3-4b-it',
+    provider: 'huggingface',
+    name: 'Gemma 3 4B IT',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.05, output: 0.1, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'google/gemma-4-26B-A4B-it',
+    provider: 'huggingface',
+    name: 'Gemma 4 26B A4B IT',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.13, output: 0.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'google/gemma-4-31B-it',
+    provider: 'huggingface',
+    name: 'Gemma 4 31B IT',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.14, output: 0.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'meta-llama/Llama-3.1-8B-Instruct',
+    provider: 'huggingface',
+    name: 'Llama-3.1-8B-Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.06, output: 0.06, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 4096,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'meta-llama/Llama-3.3-70B-Instruct',
+    provider: 'huggingface',
+    name: 'Llama-3.3-70B-Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.59, output: 0.79, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 4096,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'MiniMaxAI/MiniMax-M2',
+    provider: 'huggingface',
+    name: 'MiniMax-M2',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'MiniMaxAI/MiniMax-M2.1',
+    provider: 'huggingface',
+    name: 'MiniMax-M2.1',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'MiniMaxAI/MiniMax-M2.5',
+    provider: 'huggingface',
+    name: 'MiniMax-M2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'MiniMaxAI/MiniMax-M2.7',
+    provider: 'huggingface',
+    name: 'MiniMax-M2.7',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'MiniMaxAI/MiniMax-M3',
+    provider: 'huggingface',
+    name: 'MiniMax-M3',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 524288,
+    maxTokens: 512000,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'moonshotai/Kimi-K2-Instruct',
+    provider: 'huggingface',
+    name: 'Kimi-K2-Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 1, output: 3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'moonshotai/Kimi-K2-Instruct-0905',
+    provider: 'huggingface',
+    name: 'Kimi-K2-Instruct-0905',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 1, output: 3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 16384,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'moonshotai/Kimi-K2-Thinking',
+    provider: 'huggingface',
+    name: 'Kimi-K2-Thinking',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.6, output: 2.5, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStrictMode: true,
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'moonshotai/Kimi-K2.5',
+    provider: 'huggingface',
+    name: 'Kimi-K2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    cost: { input: 0.6, output: 3, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStrictMode: true,
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'moonshotai/Kimi-K2.6',
+    provider: 'huggingface',
+    name: 'Kimi-K2.6',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStrictMode: true,
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'moonshotai/Kimi-K2.7-Code',
+    provider: 'huggingface',
+    name: 'Kimi K2.7 Code',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.95, output: 4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStrictMode: true,
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'moonshotai/Kimi-K3',
+    provider: 'huggingface',
+    name: 'Kimi K3',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 3, output: 15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-oss-120b',
+    provider: 'huggingface',
+    name: 'GPT OSS 120B',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 0.69, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'openai/gpt-oss-20b',
+    provider: 'huggingface',
+    name: 'GPT OSS 20B',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.1, output: 0.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen2.5-Coder-32B-Instruct',
+    provider: 'huggingface',
+    name: 'Qwen2.5-Coder-32B-Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.06, output: 0.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 8192,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3-235B-A22B',
+    provider: 'huggingface',
+    name: 'Qwen3 235B-A22B',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.2, output: 0.8, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 40960,
+    maxTokens: 16384,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3-235B-A22B-Instruct-2507',
+    provider: 'huggingface',
+    name: 'Qwen3 235B-A22B Instruct 2507',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.855, output: 2.565, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 16384,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3-235B-A22B-Thinking-2507',
+    provider: 'huggingface',
+    name: 'Qwen3-235B-A22B-Thinking-2507',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3-30B-A3B',
+    provider: 'huggingface',
+    name: 'Qwen3 30B A3B',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.12, output: 0.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 40960,
+    maxTokens: 16384,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3-32B',
+    provider: 'huggingface',
+    name: 'Qwen3 32B',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.29, output: 0.59, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3-Coder-30B-A3B-Instruct',
+    provider: 'huggingface',
+    name: 'Qwen3-Coder 30B-A3B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.07, output: 0.26, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3-Coder-480B-A35B-Instruct',
+    provider: 'huggingface',
+    name: 'Qwen3-Coder-480B-A35B-Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 2, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 66536,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3-Coder-Next',
+    provider: 'huggingface',
+    name: 'Qwen3-Coder-Next',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.2, output: 1.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3-Embedding-4B',
+    provider: 'huggingface',
+    name: 'Qwen 3 Embedding 4B',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.01, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 2048,
+    compat: {
+      supportsStrictMode: true,
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'Qwen/Qwen3-Embedding-8B',
+    provider: 'huggingface',
+    name: 'Qwen 3 Embedding 8B',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.01, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 4096,
+    compat: {
+      supportsStrictMode: true,
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'Qwen/Qwen3-Next-80B-A3B-Instruct',
+    provider: 'huggingface',
+    name: 'Qwen3-Next-80B-A3B-Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.25, output: 1, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 66536,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3-Next-80B-A3B-Thinking',
+    provider: 'huggingface',
+    name: 'Qwen3-Next-80B-A3B-Thinking',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.3, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3-VL-235B-A22B-Instruct',
+    provider: 'huggingface',
+    name: 'Qwen3 VL 235B A22B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.3, output: 1.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3-VL-235B-A22B-Thinking',
+    provider: 'huggingface',
+    name: 'Qwen3 VL 235B A22B Thinking',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.98, output: 3.95, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3.5-122B-A10B',
+    provider: 'huggingface',
+    name: 'Qwen3.5 122B-A10B',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.4, output: 3.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3.5-27B',
+    provider: 'huggingface',
+    name: 'Qwen3.5 27B',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.3, output: 2.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3.5-35B-A3B',
+    provider: 'huggingface',
+    name: 'Qwen3.5 35B-A3B',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.25, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3.5-397B-A17B',
+    provider: 'huggingface',
+    name: 'Qwen3.5-397B-A17B',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.6, output: 3.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      supportsStrictMode: true,
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'Qwen/Qwen3.5-9B',
+    provider: 'huggingface',
+    name: 'Qwen3.5 9B',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.17, output: 0.25, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3.6-27B',
+    provider: 'huggingface',
+    name: 'Qwen3.6 27B',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.47, output: 3.19, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3.6-35B-A3B',
+    provider: 'huggingface',
+    name: 'Qwen3.6 35B-A3B',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.15, output: 0.95, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3.8-2.4T-A95B',
+    provider: 'huggingface',
+    name: 'Qwen3.8 2.4T A95B',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2.5, output: 6.25, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'Qwen/Qwen3.8-27B',
+    provider: 'huggingface',
+    name: 'Qwen3.8 27B',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.4, output: 3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'stepfun-ai/Step-3.5-Flash',
+    provider: 'huggingface',
+    name: 'Step 3.5 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.1, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 256000,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'stepfun-ai/Step-3.7-Flash',
+    provider: 'huggingface',
+    name: 'Step 3.7 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.2, output: 1.15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 256000,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'tencent/Hy3',
+    provider: 'huggingface',
+    name: 'Hy3',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.14, output: 0.58, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'tencent/Hy4-preview',
+    provider: 'huggingface',
+    name: 'Hy4 preview',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.834, output: 2.501, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'thinkingmachines/Inkling',
+    provider: 'huggingface',
+    name: 'Inkling',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1, output: 4.05, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'thinkingmachines/Inkling-Small',
+    provider: 'huggingface',
+    name: 'Inkling Small',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.5, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 524288,
+    maxTokens: 1048576,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'XiaomiMiMo/MiMo-V2-Flash',
+    provider: 'huggingface',
+    name: 'MiMo-V2-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.1, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 4096,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'XiaomiMiMo/MiMo-V2.5',
+    provider: 'huggingface',
+    name: 'MiMo-V2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.4, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'XiaomiMiMo/MiMo-V2.5-Pro',
+    provider: 'huggingface',
+    name: 'MiMo-V2.5-Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1, output: 3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'zai-org/GLM-4.5',
+    provider: 'huggingface',
+    name: 'GLM-4.5',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.6, output: 2.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 98304,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'zai-org/GLM-4.5-Air',
+    provider: 'huggingface',
+    name: 'GLM-4.5-Air',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.13, output: 0.85, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 98304,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'zai-org/GLM-4.5V',
+    provider: 'huggingface',
+    name: 'GLM-4.5V',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.6, output: 1.8, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 65536,
+    maxTokens: 16384,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'zai-org/GLM-4.6',
+    provider: 'huggingface',
+    name: 'GLM-4.6',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.55, output: 2.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'zai-org/GLM-4.6V-Flash',
+    provider: 'huggingface',
+    name: 'GLM-4.6V-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.3, output: 0.9, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'zai-org/GLM-4.7',
+    provider: 'huggingface',
+    name: 'GLM-4.7',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.6, output: 2.2, cacheRead: 0.11, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'zai-org/GLM-4.7-Flash',
+    provider: 'huggingface',
+    name: 'GLM-4.7-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 128000,
+    compat: {
+      supportsStrictMode: true,
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'zai-org/GLM-5',
+    provider: 'huggingface',
+    name: 'GLM-5',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 1, output: 3.2, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 202752,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'zai-org/GLM-5.1',
+    provider: 'huggingface',
+    name: 'GLM-5.1',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 1, output: 3.2, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 202752,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'zai-org/GLM-5.2',
+    provider: 'huggingface',
+    name: 'GLM-5.2',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 1.4, output: 4.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'zai-org/GLM-5.3',
+    provider: 'huggingface',
+    name: 'GLM-5.3',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+  {
+    id: 'zai-org/GLM-5.3-Flash',
+    provider: 'huggingface',
+    name: 'GLM-5.3-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://router.huggingface.co/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: { supportsStrictMode: true, supportsDeveloperRole: false },
+  },
+]
diff --git a/packages/ai-models/src/providers/kimi-coding.ts b/packages/ai-models/src/providers/kimi-coding.ts
new file mode 100644
index 0000000000..5f0d1b43b4
--- /dev/null
+++ b/packages/ai-models/src/providers/kimi-coding.ts
@@ -0,0 +1,94 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Kimi For Coding. */
+export const provider: ProviderRecord = {
+  id: 'kimi-coding',
+  name: 'Kimi For Coding',
+  baseUrl: 'https://api.kimi.com/coding',
+  apis: ['anthropic-messages'],
+  env: [['KIMI_API_KEY']],
+}
+
+/** Every Kimi For Coding model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'k3',
+    provider: 'kimi-coding',
+    name: 'Kimi K3',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.kimi.com/coding',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: { forceAdaptiveThinking: true, supportsTemperature: false },
+  },
+  {
+    id: 'k3-256k',
+    provider: 'kimi-coding',
+    name: 'Kimi K3-256K',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.kimi.com/coding',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: { forceAdaptiveThinking: true, supportsTemperature: false },
+  },
+  {
+    id: 'kimi-for-coding',
+    provider: 'kimi-coding',
+    name: 'kimi-for-coding',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.kimi.com/coding',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 32768,
+    compat: { forceAdaptiveThinking: true },
+  },
+  {
+    id: 'kimi-for-coding-highspeed',
+    provider: 'kimi-coding',
+    name: 'Kimi For Coding HighSpeed',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.kimi.com/coding',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: { forceAdaptiveThinking: true, supportsTemperature: false },
+  },
+]
diff --git a/packages/ai-models/src/providers/meta.ts b/packages/ai-models/src/providers/meta.ts
new file mode 100644
index 0000000000..ac1b03f17a
--- /dev/null
+++ b/packages/ai-models/src/providers/meta.ts
@@ -0,0 +1,120 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Meta. */
+export const provider: ProviderRecord = {
+  id: 'meta',
+  name: 'Meta',
+  baseUrl: 'https://api.meta.ai/v1',
+  apis: ['openai-responses'],
+  env: [['META_API_KEY']],
+}
+
+/** Every Meta model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'muse-spark-1.1',
+    provider: 'meta',
+    name: 'Muse Spark 1.1',
+    api: 'openai-responses',
+    baseUrl: 'https://api.meta.ai/v1',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+  },
+  {
+    id: 'muse-spark-1.2',
+    provider: 'meta',
+    name: 'Muse Spark 1.2',
+    api: 'openai-responses',
+    baseUrl: 'https://api.meta.ai/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+  },
+  {
+    id: 'muse-spark-1.2-contributor',
+    provider: 'meta',
+    name: 'Muse Spark 1.2 Contributor',
+    api: 'openai-responses',
+    baseUrl: 'https://api.meta.ai/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.1, output: 0.2, cacheRead: 0.002, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+  },
+  {
+    id: 'muse-spark-1.3',
+    provider: 'meta',
+    name: 'Muse Spark 1.3',
+    api: 'openai-responses',
+    baseUrl: 'https://api.meta.ai/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+  },
+  {
+    id: 'muse-spark-1.3-contributor',
+    provider: 'meta',
+    name: 'Muse Spark 1.3 Contributor',
+    api: 'openai-responses',
+    baseUrl: 'https://api.meta.ai/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.1, output: 0.2, cacheRead: 0.002, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+  },
+]
diff --git a/packages/ai-models/src/providers/minimax-cn.ts b/packages/ai-models/src/providers/minimax-cn.ts
new file mode 100644
index 0000000000..40ca0864e9
--- /dev/null
+++ b/packages/ai-models/src/providers/minimax-cn.ts
@@ -0,0 +1,106 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** MiniMax (China). */
+export const provider: ProviderRecord = {
+  id: 'minimax-cn',
+  name: 'MiniMax (China)',
+  baseUrl: 'https://api.minimaxi.com/anthropic',
+  apis: ['anthropic-messages'],
+  env: [['MINIMAX_CN_API_KEY']],
+}
+
+/** Every MiniMax (China) model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'MiniMax-M2',
+    provider: 'minimax-cn',
+    name: 'MiniMax-M2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.minimaxi.com/anthropic',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+  },
+  {
+    id: 'MiniMax-M2.1',
+    provider: 'minimax-cn',
+    name: 'MiniMax-M2.1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.minimaxi.com/anthropic',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+  },
+  {
+    id: 'MiniMax-M2.5',
+    provider: 'minimax-cn',
+    name: 'MiniMax-M2.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.minimaxi.com/anthropic',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+  },
+  {
+    id: 'MiniMax-M2.5-highspeed',
+    provider: 'minimax-cn',
+    name: 'MiniMax-M2.5-highspeed',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.minimaxi.com/anthropic',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.6, output: 2.4, cacheRead: 0.06, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+  },
+  {
+    id: 'MiniMax-M2.7',
+    provider: 'minimax-cn',
+    name: 'MiniMax-M2.7',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.minimaxi.com/anthropic',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+  },
+  {
+    id: 'MiniMax-M2.7-highspeed',
+    provider: 'minimax-cn',
+    name: 'MiniMax-M2.7-highspeed',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.minimaxi.com/anthropic',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.6, output: 2.4, cacheRead: 0.06, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+  },
+  {
+    id: 'MiniMax-M3',
+    provider: 'minimax-cn',
+    name: 'MiniMax-M3',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.minimaxi.com/anthropic',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 512000,
+  },
+]
diff --git a/packages/ai-models/src/providers/minimax.ts b/packages/ai-models/src/providers/minimax.ts
new file mode 100644
index 0000000000..7d15652390
--- /dev/null
+++ b/packages/ai-models/src/providers/minimax.ts
@@ -0,0 +1,106 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** MiniMax. */
+export const provider: ProviderRecord = {
+  id: 'minimax',
+  name: 'MiniMax',
+  baseUrl: 'https://api.minimax.io/anthropic',
+  apis: ['anthropic-messages'],
+  env: [['MINIMAX_API_KEY']],
+}
+
+/** Every MiniMax model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'MiniMax-M2',
+    provider: 'minimax',
+    name: 'MiniMax-M2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.minimax.io/anthropic',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+  },
+  {
+    id: 'MiniMax-M2.1',
+    provider: 'minimax',
+    name: 'MiniMax-M2.1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.minimax.io/anthropic',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+  },
+  {
+    id: 'MiniMax-M2.5',
+    provider: 'minimax',
+    name: 'MiniMax-M2.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.minimax.io/anthropic',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+  },
+  {
+    id: 'MiniMax-M2.5-highspeed',
+    provider: 'minimax',
+    name: 'MiniMax-M2.5-highspeed',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.minimax.io/anthropic',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.6, output: 2.4, cacheRead: 0.06, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+  },
+  {
+    id: 'MiniMax-M2.7',
+    provider: 'minimax',
+    name: 'MiniMax-M2.7',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.minimax.io/anthropic',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+  },
+  {
+    id: 'MiniMax-M2.7-highspeed',
+    provider: 'minimax',
+    name: 'MiniMax-M2.7-highspeed',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.minimax.io/anthropic',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.6, output: 2.4, cacheRead: 0.06, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+  },
+  {
+    id: 'MiniMax-M3',
+    provider: 'minimax',
+    name: 'MiniMax-M3',
+    api: 'anthropic-messages',
+    baseUrl: 'https://api.minimax.io/anthropic',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 512000,
+  },
+]
diff --git a/packages/ai-models/src/providers/mistral.ts b/packages/ai-models/src/providers/mistral.ts
new file mode 100644
index 0000000000..41212bb69b
--- /dev/null
+++ b/packages/ai-models/src/providers/mistral.ts
@@ -0,0 +1,501 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Mistral. */
+export const provider: ProviderRecord = {
+  id: 'mistral',
+  name: 'Mistral',
+  baseUrl: 'https://api.mistral.ai',
+  apis: ['mistral-conversations'],
+  env: [['MISTRAL_API_KEY']],
+}
+
+/** Every Mistral model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'codestral-latest',
+    provider: 'mistral',
+    name: 'Codestral (latest)',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.3, output: 0.9, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'devstral-2512',
+    provider: 'mistral',
+    name: 'Devstral 2',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.4, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+  },
+  {
+    id: 'devstral-latest',
+    provider: 'mistral',
+    name: 'Devstral 2',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.4, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+  },
+  {
+    id: 'devstral-medium-2507',
+    provider: 'mistral',
+    name: 'Devstral Medium',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.4, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'devstral-medium-latest',
+    provider: 'mistral',
+    name: 'Devstral 2 (latest)',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.4, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+  },
+  {
+    id: 'devstral-small-2505',
+    provider: 'mistral',
+    name: 'Devstral Small 2505',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'devstral-small-2507',
+    provider: 'mistral',
+    name: 'Devstral Small',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'labs-devstral-small-2512',
+    provider: 'mistral',
+    name: 'Devstral Small 2',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 256000,
+  },
+  {
+    id: 'magistral-medium-latest',
+    provider: 'mistral',
+    name: 'Magistral Medium (latest)',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 2, output: 5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+  },
+  {
+    provider: 'mistral',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    id: 'magistral-small',
+    name: 'Magistral Small',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.5, output: 1.5, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'ministral-3b-latest',
+    provider: 'mistral',
+    name: 'Ministral 3B (latest)',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.04, output: 0.04, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'ministral-8b-latest',
+    provider: 'mistral',
+    name: 'Ministral 8B (latest)',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.1, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'mistral-embed',
+    provider: 'mistral',
+    name: 'Mistral Embed',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8000,
+    maxTokens: 3072,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'mistral-large-2411',
+    provider: 'mistral',
+    name: 'Mistral Large 2.1',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 2, output: 6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+  },
+  {
+    id: 'mistral-large-2512',
+    provider: 'mistral',
+    name: 'Mistral Large 3',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.5, output: 1.5, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+  },
+  {
+    id: 'mistral-large-latest',
+    provider: 'mistral',
+    name: 'Mistral Large (latest)',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.5, output: 1.5, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+  },
+  {
+    id: 'mistral-medium-2505',
+    provider: 'mistral',
+    name: 'Mistral Medium 3',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.4, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+  },
+  {
+    id: 'mistral-medium-2508',
+    provider: 'mistral',
+    name: 'Mistral Medium 3.1',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.4, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+  },
+  {
+    id: 'mistral-medium-2604',
+    provider: 'mistral',
+    name: 'Mistral Medium 3.5',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.5, output: 7.5, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+  },
+  {
+    id: 'mistral-medium-3.5',
+    provider: 'mistral',
+    name: 'Mistral Medium 3.5',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.5, output: 7.5, cacheRead: 0.75, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 32768,
+    borrowedFrom: 'nano-gpt/mistralai/mistral-medium-3.5',
+  },
+  {
+    id: 'mistral-medium-latest',
+    provider: 'mistral',
+    name: 'Mistral Medium (latest)',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.5, output: 7.5, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+  },
+  {
+    id: 'mistral-nemo',
+    provider: 'mistral',
+    name: 'Mistral Nemo',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0.15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'mistral-small-2506',
+    provider: 'mistral',
+    name: 'Mistral Small 3.2',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+  },
+  {
+    id: 'mistral-small-2603',
+    provider: 'mistral',
+    name: 'Mistral Small 4',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 256000,
+  },
+  {
+    id: 'mistral-small-latest',
+    provider: 'mistral',
+    name: 'Mistral Small (latest)',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 256000,
+  },
+  {
+    id: 'open-mistral-7b',
+    provider: 'mistral',
+    name: 'Mistral 7B',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.25, output: 0.25, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8000,
+    maxTokens: 8000,
+  },
+  {
+    id: 'open-mistral-nemo',
+    provider: 'mistral',
+    name: 'Open Mistral Nemo',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0.15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'open-mixtral-8x22b',
+    provider: 'mistral',
+    name: 'Mixtral 8x22B',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 2, output: 6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 64000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'open-mixtral-8x7b',
+    provider: 'mistral',
+    name: 'Mixtral 8x7B',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.7, output: 0.7, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 32000,
+  },
+  {
+    id: 'pixtral-12b',
+    provider: 'mistral',
+    name: 'Pixtral 12B',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0.15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'pixtral-large-latest',
+    provider: 'mistral',
+    name: 'Pixtral Large (latest)',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 2, output: 6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'voxtral-mini-latest',
+    provider: 'mistral',
+    name: 'Voxtral Mini (latest)',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['audio'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { supportsTemperature: false },
+  },
+  {
+    id: 'voxtral-small-latest',
+    provider: 'mistral',
+    name: 'Voxtral Small (latest)',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text', 'audio'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 32000,
+  },
+  {
+    id: 'zai-glm-5-2',
+    provider: 'mistral',
+    name: 'GLM-5.2',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.14, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+  },
+  {
+    id: 'zai-glm-5-3',
+    provider: 'mistral',
+    name: 'GLM-5.3',
+    api: 'mistral-conversations',
+    baseUrl: 'https://api.mistral.ai',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.14, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+  },
+]
diff --git a/packages/ai-models/src/providers/moonshotai-cn.ts b/packages/ai-models/src/providers/moonshotai-cn.ts
new file mode 100644
index 0000000000..6d4300f2be
--- /dev/null
+++ b/packages/ai-models/src/providers/moonshotai-cn.ts
@@ -0,0 +1,122 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Moonshot AI (China). */
+export const provider: ProviderRecord = {
+  id: 'moonshotai-cn',
+  name: 'Moonshot AI (China)',
+  baseUrl: 'https://api.moonshot.cn/v1',
+  apis: ['openai-completions'],
+  env: [['MOONSHOT_API_KEY']],
+}
+
+/** Every Moonshot AI (China) model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'kimi-k2.6',
+    provider: 'moonshotai-cn',
+    name: 'Kimi K2.6',
+    api: 'openai-completions',
+    baseUrl: 'https://api.moonshot.cn/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      supportsStrictMode: false,
+      supportsMidConvoSystemMessages: true,
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'kimi-k2.7-code',
+    provider: 'moonshotai-cn',
+    name: 'Kimi K2.7 Code',
+    api: 'openai-completions',
+    baseUrl: 'https://api.moonshot.cn/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    cost: { input: 0.95, output: 4, cacheRead: 0.19, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      supportsStrictMode: false,
+      supportsMidConvoSystemMessages: true,
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'kimi-k2.7-code-highspeed',
+    provider: 'moonshotai-cn',
+    name: 'Kimi K2.7 Code HighSpeed',
+    api: 'openai-completions',
+    baseUrl: 'https://api.moonshot.cn/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    cost: { input: 1.9, output: 8, cacheRead: 0.38, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      supportsStrictMode: false,
+      supportsMidConvoSystemMessages: true,
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'kimi-k3',
+    provider: 'moonshotai-cn',
+    name: 'Kimi K3',
+    api: 'openai-completions',
+    baseUrl: 'https://api.moonshot.cn/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      supportsStrictMode: false,
+      supportsMidConvoSystemMessages: true,
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+      supportsReasoningEffort: true,
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/moonshotai.ts b/packages/ai-models/src/providers/moonshotai.ts
new file mode 100644
index 0000000000..6c91d0dfff
--- /dev/null
+++ b/packages/ai-models/src/providers/moonshotai.ts
@@ -0,0 +1,122 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Moonshot AI. */
+export const provider: ProviderRecord = {
+  id: 'moonshotai',
+  name: 'Moonshot AI',
+  baseUrl: 'https://api.moonshot.ai/v1',
+  apis: ['openai-completions'],
+  env: [['MOONSHOT_API_KEY']],
+}
+
+/** Every Moonshot AI model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'kimi-k2.6',
+    provider: 'moonshotai',
+    name: 'Kimi K2.6',
+    api: 'openai-completions',
+    baseUrl: 'https://api.moonshot.ai/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      supportsStrictMode: false,
+      supportsMidConvoSystemMessages: true,
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'kimi-k2.7-code',
+    provider: 'moonshotai',
+    name: 'Kimi K2.7 Code',
+    api: 'openai-completions',
+    baseUrl: 'https://api.moonshot.ai/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    cost: { input: 0.95, output: 4, cacheRead: 0.19, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      supportsStrictMode: false,
+      supportsMidConvoSystemMessages: true,
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'kimi-k2.7-code-highspeed',
+    provider: 'moonshotai',
+    name: 'Kimi K2.7 Code HighSpeed',
+    api: 'openai-completions',
+    baseUrl: 'https://api.moonshot.ai/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    cost: { input: 1.9, output: 8, cacheRead: 0.38, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      supportsStrictMode: false,
+      supportsMidConvoSystemMessages: true,
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'kimi-k3',
+    provider: 'moonshotai',
+    name: 'Kimi K3',
+    api: 'openai-completions',
+    baseUrl: 'https://api.moonshot.ai/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      supportsStrictMode: false,
+      supportsMidConvoSystemMessages: true,
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+      supportsReasoningEffort: true,
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/nvidia.ts b/packages/ai-models/src/providers/nvidia.ts
new file mode 100644
index 0000000000..d5a058c4f3
--- /dev/null
+++ b/packages/ai-models/src/providers/nvidia.ts
@@ -0,0 +1,2225 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** NVIDIA. */
+export const provider: ProviderRecord = {
+  id: 'nvidia',
+  name: 'NVIDIA',
+  baseUrl: 'https://integrate.api.nvidia.com/v1',
+  apis: ['openai-completions'],
+  env: [['NVIDIA_API_KEY']],
+}
+
+/** Every NVIDIA model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'abacusai/dracarys-llama-3.1-70b-instruct',
+    provider: 'nvidia',
+    name: 'dracarys-llama-3.1-70b-instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'baai/bge-m3',
+    provider: 'nvidia',
+    name: 'BGE M3',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1024,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'bytedance/seed-oss-36b-instruct',
+    provider: 'nvidia',
+    name: 'ByteDance-Seed/Seed-OSS-36B-Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262000,
+    maxTokens: 262000,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'deepseek-ai/deepseek-v4-flash',
+    provider: 'nvidia',
+    name: 'DeepSeek V4 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 393216,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'deepseek-ai/deepseek-v4-flash-0731',
+    provider: 'nvidia',
+    name: 'DeepSeek V4 Flash 0731',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'deepseek-ai/deepseek-v4-pro',
+    provider: 'nvidia',
+    name: 'DeepSeek V4 Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.003625, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 393216,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'deepseek-ai/deepseek-v4-pro-0813',
+    provider: 'nvidia',
+    name: 'DeepSeek V4 Pro 0813',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'google/gemma-2-2b-it',
+    provider: 'nvidia',
+    name: 'Gemma 2 2b It',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'google/gemma-3-12b-it',
+    provider: 'nvidia',
+    name: 'Gemma 3 12B IT',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'google/gemma-3-4b-it',
+    provider: 'nvidia',
+    name: 'Gemma 3 4B IT',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'google/gemma-3n-e2b-it',
+    provider: 'nvidia',
+    name: 'Gemma 3n E2b It',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'google/gemma-3n-e4b-it',
+    provider: 'nvidia',
+    name: 'Gemma 3n E4b It',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'google/gemma-4-31b-it',
+    provider: 'nvidia',
+    name: 'Gemma-4-31B-IT',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 16384,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'google/google-paligemma',
+    provider: 'nvidia',
+    name: 'paligemma',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'meta/esm2-650m',
+    provider: 'nvidia',
+    name: 'esm2-650m',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'meta/esmfold',
+    provider: 'nvidia',
+    name: 'esmfold',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'meta/llama-3.1-70b-instruct',
+    provider: 'nvidia',
+    name: 'Llama 3.1 70b Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'meta/llama-3.1-8b-instruct',
+    provider: 'nvidia',
+    name: 'Llama 3.1 8B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 16000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'meta/llama-3.2-11b-vision-instruct',
+    provider: 'nvidia',
+    name: 'Llama 3.2 11b Vision Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'meta/llama-3.2-1b-instruct',
+    provider: 'nvidia',
+    name: 'Llama 3.2 1b Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'meta/llama-3.2-3b-instruct',
+    provider: 'nvidia',
+    name: 'Llama 3.2 3B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 32000,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'meta/llama-3.2-90b-vision-instruct',
+    provider: 'nvidia',
+    name: 'Llama-3.2-90B-Vision-Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'meta/llama-3.3-70b-instruct',
+    provider: 'nvidia',
+    name: 'Llama 3.3 70b Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'meta/llama-4-maverick-17b-128e-instruct',
+    provider: 'nvidia',
+    name: 'Llama 4 Maverick 17b 128e Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'meta/llama-guard-4-12b',
+    provider: 'nvidia',
+    name: 'Llama Guard 4 12B',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'meta/muse-glimmer-30b',
+    provider: 'nvidia',
+    name: 'Muse Glimmer 30B',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'microsoft/phi-4-mini-instruct',
+    provider: 'nvidia',
+    name: 'Phi-4-Mini',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'microsoft/phi-4-multimodal-instruct',
+    provider: 'nvidia',
+    name: 'Phi 4 Multimodal',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'minimaxai/minimax-m2.7',
+    provider: 'nvidia',
+    name: 'MiniMax-M2.7',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'minimaxai/minimax-m3',
+    provider: 'nvidia',
+    name: 'MiniMax-M3',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 16384,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'mistralai/magistral-small-2506',
+    provider: 'nvidia',
+    name: 'Magistral Small 2506',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 32768,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'mistralai/ministral-14b-instruct-2512',
+    provider: 'nvidia',
+    name: 'Ministral 3 14B Instruct 2512',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 16384,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-7b-instruct-v0.3',
+    provider: 'nvidia',
+    name: 'Mistral-7B-Instruct-v0.3',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 65536,
+    maxTokens: 65536,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-large-3-675b-instruct-2512',
+    provider: 'nvidia',
+    name: 'Mistral Large 3 675B Instruct 2512',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-medium-3-instruct',
+    provider: 'nvidia',
+    name: 'Mistral Medium 3',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-medium-3.5-128b',
+    provider: 'nvidia',
+    name: 'Mistral Medium 3.5',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-nemotron',
+    provider: 'nvidia',
+    name: 'mistral-nemotron',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-small-4-119b-2603',
+    provider: 'nvidia',
+    name: 'mistral-small-4-119b-2603',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'mistralai/mixtral-8x22b-instruct',
+    provider: 'nvidia',
+    name: 'Mistral: Mixtral 8x22B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 65536,
+    maxTokens: 13108,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'mistralai/mixtral-8x7b-instruct',
+    provider: 'nvidia',
+    name: 'Mistral: Mixtral 8x7B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 16384,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'moonshotai/kimi-k2.6',
+    provider: 'nvidia',
+    name: 'Kimi K2.6',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'moonshotai/kimi-k3',
+    provider: 'nvidia',
+    name: 'Kimi K3',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'nvidia/active-speaker-detection',
+    provider: 'nvidia',
+    name: 'Active Speaker Detection',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['video'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'nvidia/bevformer',
+    provider: 'nvidia',
+    name: 'bevformer',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['video'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/cosmos-reason2-8b',
+    provider: 'nvidia',
+    name: 'Cosmos Reason2 8B',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/gliner-pii',
+    provider: 'nvidia',
+    name: 'gliner-pii',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/llama-3_2-nemoretriever-300m-embed-v1',
+    provider: 'nvidia',
+    name: 'llama-3_2-nemoretriever-300m-embed-v1',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 2048,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'nvidia/llama-3.1-nemotron-70b-instruct',
+    provider: 'nvidia',
+    name: 'Llama 3.1 Nemotron 70B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/llama-3.1-nemotron-nano-8b-v1',
+    provider: 'nvidia',
+    name: 'Llama 3.1 Nemotron Nano 8B v1',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/llama-3.1-nemotron-nano-vl-8b-v1',
+    provider: 'nvidia',
+    name: 'Llama 3.1 Nemotron Nano VL 8B v1',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 16384,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/llama-3.1-nemotron-safety-guard-8b-v3',
+    provider: 'nvidia',
+    name: 'llama-3.1-nemotron-safety-guard-8b-v3',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'nvidia/llama-3.1-nemotron-ultra-253b-v1',
+    provider: 'nvidia',
+    name: 'Llama 3.1 Nemotron Ultra 253B',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/llama-3.3-nemotron-super-49b-v1',
+    provider: 'nvidia',
+    name: 'Llama 3.3 Nemotron Super 49B v1',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 65536,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/llama-3.3-nemotron-super-49b-v1.5',
+    provider: 'nvidia',
+    name: 'Llama 3.3 Nemotron Super 49B v1.5',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 65536,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/llama-nemotron-embed-vl-1b-v2',
+    provider: 'nvidia',
+    name: 'llama-nemotron-embed-vl-1b-v2',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 2048,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'nvidia/llama-nemotron-rerank-vl-1b-v2',
+    provider: 'nvidia',
+    name: 'llama-nemotron-rerank-vl-1b-v2',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-3-content-safety',
+    provider: 'nvidia',
+    name: 'nemotron-3-content-safety',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-3-nano-30b-a3b',
+    provider: 'nvidia',
+    name: 'nemotron-3-nano-30b-a3b',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning',
+    provider: 'nvidia',
+    name: 'Nemotron 3 Nano Omni',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 65536,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-3-super-120b-a12b',
+    provider: 'nvidia',
+    name: 'Nemotron 3 Super',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.2, output: 0.8, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-3-ultra-550b-a55b',
+    provider: 'nvidia',
+    name: 'Nemotron 3 Ultra 550B A55B',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.5, output: 2.5, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-3.5-lightning-30b-a3b',
+    provider: 'nvidia',
+    name: 'Nemotron 3.5 Lightning 30B A3B',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-content-safety-reasoning-4b',
+    provider: 'nvidia',
+    name: 'nemotron-content-safety-reasoning-4b',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-mini-4b-instruct',
+    provider: 'nvidia',
+    name: 'nemotron-mini-4b-instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-nano-12b-v2-vl',
+    provider: 'nvidia',
+    name: 'Nemotron Nano 12B v2 VL',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-voicechat',
+    provider: 'nvidia',
+    name: 'nemotron-voicechat',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'audio'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/nv-embed-v1',
+    provider: 'nvidia',
+    name: 'nv-embed-v1',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 2048,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'nvidia/nv-embedcode-7b-v1',
+    provider: 'nvidia',
+    name: 'nv-embedcode-7b-v1',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 2048,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'nvidia/nvidia-nemotron-nano-9b-v2',
+    provider: 'nvidia',
+    name: 'nvidia-nemotron-nano-9b-v2',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/rerank-qa-mistral-4b',
+    provider: 'nvidia',
+    name: 'rerank-qa-mistral-4b',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'nvidia/riva-translate-4b-instruct-v1.1',
+    provider: 'nvidia',
+    name: 'riva-translate-4b-instruct-v1_1',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'nvidia/sparsedrive',
+    provider: 'nvidia',
+    name: 'sparsedrive',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['video'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/streampetr',
+    provider: 'nvidia',
+    name: 'streampetr',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['video'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/studiovoice',
+    provider: 'nvidia',
+    name: 'studiovoice',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/synthetic-video-detector',
+    provider: 'nvidia',
+    name: 'synthetic-video-detector',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['video'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/usdcode',
+    provider: 'nvidia',
+    name: 'usdcode',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'nvidia/usdvalidate',
+    provider: 'nvidia',
+    name: 'usdvalidate',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-oss-20b',
+    provider: 'nvidia',
+    name: 'GPT OSS 20B',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'openai/whisper-large-v3',
+    provider: 'nvidia',
+    name: 'Whisper Large v3',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['audio'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'poolside/laguna-xs-2.1',
+    provider: 'nvidia',
+    name: 'Laguna XS 2.1',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 16384,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'qwen/qwen2.5-coder-32b-instruct',
+    provider: 'nvidia',
+    name: 'Qwen2.5 Coder 32b Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-coder-480b-a35b-instruct',
+    provider: 'nvidia',
+    name: 'Qwen3 Coder 480B A35B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 66536,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-next-80b-a3b-instruct',
+    provider: 'nvidia',
+    name: 'Qwen3-Next-80B-A3B-Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 16384,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.5-122b-a10b',
+    provider: 'nvidia',
+    name: 'Qwen3.5 122B-A10B',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.5-397b-a17b',
+    provider: 'nvidia',
+    name: 'Qwen3.5-397B-A17B',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'sarvamai/sarvam-m',
+    provider: 'nvidia',
+    name: 'sarvam-m',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'stepfun-ai/step-3.5-flash',
+    provider: 'nvidia',
+    name: 'Step 3.5 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 16384,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'stepfun-ai/step-3.7-flash',
+    provider: 'nvidia',
+    name: 'Step 3.7 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 16384,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'thinkingmachines/inkling',
+    provider: 'nvidia',
+    name: 'Inkling',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image', 'audio'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 16384,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'upstage/solar-10.7b-instruct',
+    provider: 'nvidia',
+    name: 'solar-10.7b-instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+    },
+  },
+  {
+    id: 'z-ai/glm-5.2',
+    provider: 'nvidia',
+    name: 'GLM-5.2',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'z-ai/glm-5.3',
+    provider: 'nvidia',
+    name: 'GLM-5.3',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'z-ai/glm-5.3-flash',
+    provider: 'nvidia',
+    name: 'GLM-5.3-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    headers: { 'NVCF-POLL-SECONDS': '3600' },
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/openai.ts b/packages/ai-models/src/providers/openai.ts
new file mode 100644
index 0000000000..a60ce516c2
--- /dev/null
+++ b/packages/ai-models/src/providers/openai.ts
@@ -0,0 +1,989 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** OpenAI. */
+export const provider: ProviderRecord = {
+  id: 'openai',
+  name: 'OpenAI',
+  baseUrl: 'https://api.openai.com/v1',
+  apis: ['openai-responses'],
+  env: [['OPENAI_API_KEY']],
+}
+
+/** Every OpenAI model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'chatgpt-image-latest',
+    provider: 'openai',
+    name: 'chatgpt-image-latest',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-3.5-turbo',
+    provider: 'openai',
+    name: 'GPT-3.5-turbo',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.5, output: 1.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 16385,
+    maxTokens: 4096,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-4',
+    provider: 'openai',
+    name: 'GPT-4',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 30, output: 60, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 8192,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-4-turbo',
+    provider: 'openai',
+    name: 'GPT-4 Turbo',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 10, output: 30, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-4.1',
+    provider: 'openai',
+    name: 'GPT-4.1',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 2, output: 8, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-4.1-mini',
+    provider: 'openai',
+    name: 'GPT-4.1 mini',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.4, output: 1.6, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-4.1-nano',
+    provider: 'openai',
+    name: 'GPT-4.1 nano',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.4, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-4o',
+    provider: 'openai',
+    name: 'GPT-4o',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 2.5, output: 10, cacheRead: 1.25, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-4o-2024-05-13',
+    provider: 'openai',
+    name: 'GPT-4o (2024-05-13)',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 5, output: 15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-4o-2024-08-06',
+    provider: 'openai',
+    name: 'GPT-4o (2024-08-06)',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 2.5, output: 10, cacheRead: 1.25, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-4o-2024-11-20',
+    provider: 'openai',
+    name: 'GPT-4o (2024-11-20)',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 2.5, output: 10, cacheRead: 1.25, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-4o-mini',
+    provider: 'openai',
+    name: 'GPT-4o mini',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-5',
+    provider: 'openai',
+    name: 'GPT-5',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5-chat-latest',
+    provider: 'openai',
+    name: 'gpt-5-chat-latest',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 1.125, output: 9, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true },
+    borrowedFrom: 'jiekou/gpt-5-chat-latest',
+  },
+  {
+    id: 'gpt-5-mini',
+    provider: 'openai',
+    name: 'GPT-5 Mini',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 2, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5-nano',
+    provider: 'openai',
+    name: 'GPT-5 Nano',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.05, output: 0.4, cacheRead: 0.005, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5-pro',
+    provider: 'openai',
+    name: 'GPT-5 Pro',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 15, output: 120, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 272000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.1',
+    provider: 'openai',
+    name: 'GPT-5.1',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-5.2',
+    provider: 'openai',
+    name: 'GPT-5.2',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-5.2-chat-latest',
+    provider: 'openai',
+    name: 'GPT-5.2 Chat',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: null,
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.2-pro',
+    provider: 'openai',
+    name: 'GPT-5.2 Pro',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 21, output: 168, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.3-chat-latest',
+    provider: 'openai',
+    name: 'GPT-5.3 Chat (latest)',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-5.3-codex',
+    provider: 'openai',
+    name: 'GPT-5.3 Codex',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-5.3-codex-spark',
+    provider: 'openai',
+    name: 'GPT-5.3 Codex Spark',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 32000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.4',
+    provider: 'openai',
+    name: 'GPT-5.4',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-5.4-mini',
+    provider: 'openai',
+    name: 'GPT-5.4 mini',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.75, output: 4.5, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-5.4-nano',
+    provider: 'openai',
+    name: 'GPT-5.4 nano',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.2, output: 1.25, cacheRead: 0.02, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true },
+  },
+  {
+    id: 'gpt-5.4-pro',
+    provider: 'openai',
+    name: 'GPT-5.4 Pro',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.5',
+    provider: 'openai',
+    name: 'GPT-5.5',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.5-pro',
+    provider: 'openai',
+    name: 'GPT-5.5 Pro',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.6',
+    provider: 'openai',
+    name: 'GPT-5.6',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.6-luna',
+    provider: 'openai',
+    name: 'GPT-5.6 Luna',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.6-sol',
+    provider: 'openai',
+    name: 'GPT-5.6 Sol',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-5.6-terra',
+    provider: 'openai',
+    name: 'GPT-5.6 Terra',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-6-astra',
+    provider: 'openai',
+    name: 'GPT-6 Astra',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-6-luna',
+    provider: 'openai',
+    name: 'GPT-6 Luna',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-6-sol',
+    provider: 'openai',
+    name: 'GPT-6 Sol',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-6.1-sol',
+    provider: 'openai',
+    name: 'GPT-6.1 Sol',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-daybreak-blue-latest',
+    provider: 'openai',
+    name: 'Daybreak Blue',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-daybreak-red-latest',
+    provider: 'openai',
+    name: 'Daybreak Red',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 12.5, output: 75, cacheRead: 1.25, cacheWrite: 15.625 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-image-1-mini',
+    provider: 'openai',
+    name: 'gpt-image-1-mini',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-image-1.5',
+    provider: 'openai',
+    name: 'gpt-image-1.5',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'gpt-realtime-2.1',
+    provider: 'openai',
+    name: 'GPT-Realtime-2.1',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'audio'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 4, output: 24, cacheRead: 0.4, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 32000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'o1',
+    provider: 'openai',
+    name: 'o1',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 15, output: 60, cacheRead: 7.5, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'o1-pro',
+    provider: 'openai',
+    name: 'o1-pro',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 150, output: 600, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'o3',
+    provider: 'openai',
+    name: 'o3',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 8, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'o3-mini',
+    provider: 'openai',
+    name: 'o3-mini',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.1, output: 4.4, cacheRead: 0.55, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'o3-pro',
+    provider: 'openai',
+    name: 'o3-pro',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 20, output: 80, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'o4-mini',
+    provider: 'openai',
+    name: 'o4-mini',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.1, output: 4.4, cacheRead: 0.275, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'text-embedding-3-large',
+    provider: 'openai',
+    name: 'text-embedding-3-large',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.13, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8191,
+    maxTokens: 3072,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'text-embedding-3-small',
+    provider: 'openai',
+    name: 'text-embedding-3-small',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.02, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8191,
+    maxTokens: 1536,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+  {
+    id: 'text-embedding-ada-002',
+    provider: 'openai',
+    name: 'text-embedding-ada-002',
+    api: 'openai-responses',
+    baseUrl: 'https://api.openai.com/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+    compat: { supportsStrictMode: true, supportsTemperature: false },
+  },
+]
diff --git a/packages/ai-models/src/providers/opencode-go.ts b/packages/ai-models/src/providers/opencode-go.ts
new file mode 100644
index 0000000000..a1118d8e4e
--- /dev/null
+++ b/packages/ai-models/src/providers/opencode-go.ts
@@ -0,0 +1,839 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** OpenCode Go. */
+export const provider: ProviderRecord = {
+  id: 'opencode-go',
+  name: 'OpenCode Go',
+  baseUrl: 'https://opencode.ai/zen/go/v1',
+  apis: ['anthropic-messages', 'openai-completions', 'openai-responses'],
+  env: [['OPENCODE_API_KEY']],
+}
+
+/** Every OpenCode Go model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'deepseek-v4-flash',
+    provider: 'opencode-go',
+    name: 'DeepSeek V4 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.003, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'deepseek-v4-flash-vision-exp',
+    provider: 'opencode-go',
+    name: 'DeepSeek V4 Flash Vision Exp',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.003, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'deepseek-v4-pro',
+    provider: 'opencode-go',
+    name: 'DeepSeek V4 Pro (New)',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.66, output: 1.98, cacheRead: 0.022, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'deepseek-v4.1-flash',
+    provider: 'opencode-go',
+    name: 'DeepSeek V4.1 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.003, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'glm-5.1',
+    provider: 'opencode-go',
+    name: 'GLM-5.1',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+    borrowedFrom: 'zai/glm-5.1',
+  },
+  {
+    id: 'glm-5.2',
+    provider: 'opencode-go',
+    name: 'GLM-5.2',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'glm-5.3',
+    provider: 'opencode-go',
+    name: 'GLM-5.3',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'glm-5.3-flash',
+    provider: 'opencode-go',
+    name: 'GLM-5.3-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'gpt-5.6-luna',
+    provider: 'opencode-go',
+    name: 'GPT-5.6 Luna',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-6-luna',
+    provider: 'opencode-go',
+    name: 'GPT-6 Luna',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'grok-4.5',
+    provider: 'opencode-go',
+    name: 'Grok 4.5',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+    compat: { sessionAffinityFormat: 'openai-nosession' },
+  },
+  {
+    id: 'grok-4.6',
+    provider: 'opencode-go',
+    name: 'Grok 4.6',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+    compat: { sessionAffinityFormat: 'openai-nosession' },
+  },
+  {
+    id: 'grok-4.7',
+    provider: 'opencode-go',
+    name: 'Grok 4.7',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+    compat: { sessionAffinityFormat: 'openai-nosession' },
+  },
+  {
+    id: 'hy3',
+    provider: 'opencode-go',
+    name: 'Hy3',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.14, output: 0.58, cacheRead: 0.035, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 128000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'hy4-preview',
+    provider: 'opencode-go',
+    name: 'Hy4 preview',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.834, output: 2.501, cacheRead: 0.042, cacheWrite: 0 },
+    contextWindow: 1024000,
+    maxTokens: 64000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'kimi-k2.6',
+    provider: 'opencode-go',
+    name: 'Kimi K2.6',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'kimi-k2.7-code',
+    provider: 'opencode-go',
+    name: 'Kimi K2.7 Code',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    cost: { input: 0.95, output: 4, cacheRead: 0.19, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'kimi-k3',
+    provider: 'opencode-go',
+    name: 'Kimi K3',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: null,
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'longcat-2.0',
+    provider: 'opencode-go',
+    name: 'LongCat-2.0',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.006, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'longcat-2.5-preview-free',
+    provider: 'opencode-go',
+    name: 'LongCat 2.5 Preview Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'mimo-v2.5',
+    provider: 'opencode-go',
+    name: 'MiMo V2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'mimo-v2.5-pro',
+    provider: 'opencode-go',
+    name: 'MiMo V2.5 Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.003625, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 128000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'mimo-v2.6-flash',
+    provider: 'opencode-go',
+    name: 'MiMo-V2.6-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'mimo-v2.6-pro',
+    provider: 'opencode-go',
+    name: 'MiMo-V2.6-Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.003625, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'minimax-m2.7',
+    provider: 'opencode-go',
+    name: 'MiniMax-M2.7',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen/go',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+  },
+  {
+    id: 'minimax-m3',
+    provider: 'opencode-go',
+    name: 'MiniMax-M3',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen/go',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+  },
+  {
+    id: 'muse-spark-1.2-contributor',
+    provider: 'opencode-go',
+    name: 'Muse Spark 1.2 Contributor',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.1, output: 0.2, cacheRead: 0.002, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: { sessionAffinityFormat: 'openai-nosession' },
+  },
+  {
+    id: 'muse-spark-1.3-contributor',
+    provider: 'opencode-go',
+    name: 'Muse Spark 1.3 Contributor',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.1, output: 0.2, cacheRead: 0.002, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: { sessionAffinityFormat: 'openai-nosession' },
+  },
+  {
+    id: 'qwen3.6-plus',
+    provider: 'opencode-go',
+    name: 'Qwen3.6 Plus',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0.625 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'qwen3.7-max',
+    provider: 'opencode-go',
+    name: 'Qwen3.7 Max',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 2.5, output: 7.5, cacheRead: 0.5, cacheWrite: 3.125 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'qwen3.7-plus',
+    provider: 'opencode-go',
+    name: 'Qwen3.7 Plus',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.4, output: 1.6, cacheRead: 0.04, cacheWrite: 0.5 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'qwen3.8-flash',
+    provider: 'opencode-go',
+    name: 'Qwen3.8 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen/go',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 0.15, output: 0.47, cacheRead: 0.016, cacheWrite: 0.2 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+  },
+  {
+    id: 'qwen3.8-max',
+    provider: 'opencode-go',
+    name: 'Qwen3.8 Max',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'space-bunny-free',
+    provider: 'opencode-go',
+    name: 'Space Bunny Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/go/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 524288,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/opencode.ts b/packages/ai-models/src/providers/opencode.ts
new file mode 100644
index 0000000000..d56c44577a
--- /dev/null
+++ b/packages/ai-models/src/providers/opencode.ts
@@ -0,0 +1,2573 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** OpenCode Zen. */
+export const provider: ProviderRecord = {
+  id: 'opencode',
+  name: 'OpenCode Zen',
+  baseUrl: 'https://opencode.ai/zen/v1',
+  apis: [
+    'anthropic-messages',
+    'google-generative-ai',
+    'openai-completions',
+    'openai-responses',
+  ],
+  env: [['OPENCODE_API_KEY']],
+}
+
+/** Every OpenCode Zen model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'big-pickle',
+    provider: 'opencode',
+    name: 'Big Pickle',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 32000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'claude-3-5-haiku',
+    provider: 'opencode',
+    name: 'Claude Haiku 3.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.8, output: 4, cacheRead: 0.08, cacheWrite: 1 },
+    contextWindow: 200000,
+    maxTokens: 8192,
+  },
+  {
+    id: 'claude-fable-5',
+    provider: 'opencode',
+    name: 'Claude Fable 5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'claude-fable-5-1',
+    provider: 'opencode',
+    name: 'Claude Fable 5.1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 0.25, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'claude-haiku-4-5',
+    provider: 'opencode',
+    name: 'Claude Haiku 4.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'claude-opus-4-1',
+    provider: 'opencode',
+    name: 'Claude Opus 4.1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+    contextWindow: 200000,
+    maxTokens: 32000,
+  },
+  {
+    id: 'claude-opus-4-5',
+    provider: 'opencode',
+    name: 'Claude Opus 4.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'claude-opus-4-6',
+    provider: 'opencode',
+    name: 'Claude Opus 4.6',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'claude-opus-4-7',
+    provider: 'opencode',
+    name: 'Claude Opus 4.7',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'claude-opus-4-8',
+    provider: 'opencode',
+    name: 'Claude Opus 4.8',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'claude-opus-5',
+    provider: 'opencode',
+    name: 'Claude Opus 5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'claude-opus-5-5',
+    provider: 'opencode',
+    name: 'Claude Opus 5.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.2, cacheWrite: 5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'claude-sonnet-4',
+    provider: 'opencode',
+    name: 'Claude Sonnet 4',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'claude-sonnet-4-5',
+    provider: 'opencode',
+    name: 'Claude Sonnet 4.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'claude-sonnet-4-6',
+    provider: 'opencode',
+    name: 'Claude Sonnet 4.6',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+  },
+  {
+    id: 'claude-sonnet-5',
+    provider: 'opencode',
+    name: 'Claude Sonnet 5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'claude-sonnet-5-5',
+    provider: 'opencode',
+    name: 'Claude Sonnet 5.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { supportsTemperature: false, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'deepseek-v4-flash',
+    provider: 'opencode',
+    name: 'DeepSeek V4 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.028, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'deepseek-v4-flash-free',
+    provider: 'opencode',
+    name: 'DeepSeek V4 Flash Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 128000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'deepseek-v4-flash-vision-exp',
+    provider: 'opencode',
+    name: 'DeepSeek V4 Flash Vision Exp',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.028, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'deepseek-v4-pro',
+    provider: 'opencode',
+    name: 'DeepSeek V4 Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.74, output: 3.84, cacheRead: 0.145, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'deepseek-v4.1-flash',
+    provider: 'opencode',
+    name: 'DeepSeek V4.1 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.006, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'deepseek',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'gemini-3-flash',
+    provider: 'opencode',
+    name: 'Gemini 3 Flash',
+    api: 'google-generative-ai',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3-pro',
+    provider: 'opencode',
+    name: 'Gemini 3 Pro',
+    api: 'google-generative-ai',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.1-pro',
+    provider: 'opencode',
+    name: 'Gemini 3.1 Pro Preview',
+    api: 'google-generative-ai',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.5-flash',
+    provider: 'opencode',
+    name: 'Gemini 3.5 Flash',
+    api: 'google-generative-ai',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.5, output: 9, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.5-flash-lite',
+    provider: 'opencode',
+    name: 'Gemini 3.5 Flash Lite',
+    api: 'google-generative-ai',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.3, output: 2.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.6-flash',
+    provider: 'opencode',
+    name: 'Gemini 3.6 Flash',
+    api: 'google-generative-ai',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.5, output: 7.5, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.7-flash',
+    provider: 'opencode',
+    name: 'Gemini 3.7 Flash',
+    api: 'google-generative-ai',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.5, output: 7.5, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'gemini-3.8-flash',
+    provider: 'opencode',
+    name: 'Gemini 3.8 Flash',
+    api: 'google-generative-ai',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.5, output: 7.5, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+  },
+  {
+    id: 'glm-4.6',
+    provider: 'opencode',
+    name: 'GLM-4.6',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 2.2, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'glm-4.7',
+    provider: 'opencode',
+    name: 'GLM-4.7',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 2.2, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'glm-4.7-free',
+    provider: 'opencode',
+    name: 'GLM-4.7 Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'glm-5',
+    provider: 'opencode',
+    name: 'GLM-5',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1, output: 3.2, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'glm-5-free',
+    provider: 'opencode',
+    name: 'GLM-5 Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'glm-5.1',
+    provider: 'opencode',
+    name: 'GLM-5.1',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'glm-5.2',
+    provider: 'opencode',
+    name: 'GLM-5.2',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'glm-5.3',
+    provider: 'opencode',
+    name: 'GLM-5.3',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'glm-5.3-flash',
+    provider: 'opencode',
+    name: 'GLM-5.3-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'gpt-5',
+    provider: 'opencode',
+    name: 'GPT-5',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.07, output: 8.5, cacheRead: 0.107, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5-codex',
+    provider: 'opencode',
+    name: 'GPT-5 Codex',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.07, output: 8.5, cacheRead: 0.107, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5-nano',
+    provider: 'opencode',
+    name: 'GPT-5 Nano',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.05, output: 0.4, cacheRead: 0.005, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.1',
+    provider: 'opencode',
+    name: 'GPT-5.1',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.07, output: 8.5, cacheRead: 0.107, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.1-codex',
+    provider: 'opencode',
+    name: 'GPT-5.1 Codex',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.07, output: 8.5, cacheRead: 0.107, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.1-codex-max',
+    provider: 'opencode',
+    name: 'GPT-5.1 Codex Max',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.1-codex-mini',
+    provider: 'opencode',
+    name: 'GPT-5.1 Codex Mini',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 2, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.2',
+    provider: 'opencode',
+    name: 'GPT-5.2',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.2-codex',
+    provider: 'opencode',
+    name: 'GPT-5.2 Codex',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.3-codex',
+    provider: 'opencode',
+    name: 'GPT-5.3 Codex',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.3-codex-spark',
+    provider: 'opencode',
+    name: 'GPT-5.3 Codex Spark',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.4',
+    provider: 'opencode',
+    name: 'GPT-5.4',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { sessionAffinityFormat: 'openai-nosession' },
+  },
+  {
+    id: 'gpt-5.4-mini',
+    provider: 'opencode',
+    name: 'GPT-5.4 Mini',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.75, output: 4.5, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.4-nano',
+    provider: 'opencode',
+    name: 'GPT-5.4 Nano',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.2, output: 1.25, cacheRead: 0.02, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.4-pro',
+    provider: 'opencode',
+    name: 'GPT-5.4 Pro',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 30, output: 180, cacheRead: 30, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.5',
+    provider: 'opencode',
+    name: 'GPT-5.5',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.5-pro',
+    provider: 'opencode',
+    name: 'GPT-5.5 Pro',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 30, output: 180, cacheRead: 30, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.6-luna',
+    provider: 'opencode',
+    name: 'GPT-5.6 Luna',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.6-sol',
+    provider: 'opencode',
+    name: 'GPT-5.6 Sol',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-5.6-terra',
+    provider: 'opencode',
+    name: 'GPT-5.6 Terra',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 3.125 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-6-astra',
+    provider: 'opencode',
+    name: 'GPT-6 Astra',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-6-luna',
+    provider: 'opencode',
+    name: 'GPT-6 Luna',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-6-sol',
+    provider: 'opencode',
+    name: 'GPT-6 Sol',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'gpt-6.1-sol',
+    provider: 'opencode',
+    name: 'GPT-6.1 Sol',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      sessionAffinityFormat: 'openai-nosession',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'grok-4.5',
+    provider: 'opencode',
+    name: 'Grok 4.5',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+    compat: { sessionAffinityFormat: 'openai-nosession' },
+  },
+  {
+    id: 'grok-4.6',
+    provider: 'opencode',
+    name: 'Grok 4.6',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+    compat: { sessionAffinityFormat: 'openai-nosession' },
+  },
+  {
+    id: 'grok-4.7',
+    provider: 'opencode',
+    name: 'Grok 4.7',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+    compat: { sessionAffinityFormat: 'openai-nosession' },
+  },
+  {
+    id: 'grok-build-0.1',
+    provider: 'opencode',
+    name: 'Grok Build 0.1',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    cost: { input: 1, output: 2, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 256000,
+    compat: { sessionAffinityFormat: 'openai-nosession' },
+  },
+  {
+    id: 'grok-code',
+    provider: 'opencode',
+    name: 'Grok Code Fast 1',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 256000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'hy3-free',
+    provider: 'opencode',
+    name: 'Hy3 Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 190000,
+    maxTokens: 64000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'hy3-preview-free',
+    provider: 'opencode',
+    name: 'Hy3 preview Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 64000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'kimi-k2',
+    provider: 'opencode',
+    name: 'Kimi K2',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.4, output: 2.5, cacheRead: 0.4, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'kimi-k2-thinking',
+    provider: 'opencode',
+    name: 'Kimi K2 Thinking',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.4, output: 2.5, cacheRead: 0.4, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'kimi-k2.5',
+    provider: 'opencode',
+    name: 'Kimi K2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 3, cacheRead: 0.08, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'kimi-k2.5-free',
+    provider: 'opencode',
+    name: 'Kimi K2.5 Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'kimi-k2.6',
+    provider: 'opencode',
+    name: 'Kimi K2.6',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'kimi-k2.7-code',
+    provider: 'opencode',
+    name: 'Kimi K2.7 Code',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    cost: { input: 0.95, output: 4, cacheRead: 0.19, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'kimi-k3',
+    provider: 'opencode',
+    name: 'Kimi K3',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: null,
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'laguna-s-2.1-free',
+    provider: 'opencode',
+    name: 'Laguna S 2.1 Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 32000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'ling-2.6-flash-free',
+    provider: 'opencode',
+    name: 'Ling 2.6 Flash Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262100,
+    maxTokens: 32800,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'ling-3.0-flash-fin-free',
+    provider: 'opencode',
+    name: 'Ling 3.0 Flash Fin Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'ling-3.0-flash-free',
+    provider: 'opencode',
+    name: 'Ling-3.0-flash Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'ling-3.0-tiny-free',
+    provider: 'opencode',
+    name: 'Ling-3.0-tiny Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'longcat-2.0-free',
+    provider: 'opencode',
+    name: 'LongCat-2.0 Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'longcat-2.5-preview-free',
+    provider: 'opencode',
+    name: 'LongCat 2.5 Preview Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'mimo-v2-flash-free',
+    provider: 'opencode',
+    name: 'MiMo V2 Flash Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'mimo-v2-omni-free',
+    provider: 'opencode',
+    name: 'MiMo V2 Omni Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'audio', 'document'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 64000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'mimo-v2-pro-free',
+    provider: 'opencode',
+    name: 'MiMo V2 Pro Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 64000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'mimo-v2.5-free',
+    provider: 'opencode',
+    name: 'MiMo V2.5 Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 32000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'mimo-v2.6-flash-free',
+    provider: 'opencode',
+    name: 'MiMo-V2.6-Flash Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 32000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'minimax-m2.1',
+    provider: 'opencode',
+    name: 'MiniMax-M2.1',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'minimax-m2.1-free',
+    provider: 'opencode',
+    name: 'MiniMax-M2.1 Free',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+  },
+  {
+    id: 'minimax-m2.5',
+    provider: 'opencode',
+    name: 'MiniMax-M2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'minimax-m2.5-free',
+    provider: 'opencode',
+    name: 'MiniMax-M2.5 Free',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+  },
+  {
+    id: 'minimax-m2.7',
+    provider: 'opencode',
+    name: 'MiniMax-M2.7',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'minimax-m3',
+    provider: 'opencode',
+    name: 'MiniMax-M3',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 512000,
+    maxTokens: 128000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'minimax-m3-free',
+    provider: 'opencode',
+    name: 'MiniMax-M3 Free',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 32000,
+  },
+  {
+    id: 'muse-spark-1.2',
+    provider: 'opencode',
+    name: 'Muse Spark 1.2',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: { sessionAffinityFormat: 'openai-nosession' },
+  },
+  {
+    id: 'muse-spark-1.2-contributor-free',
+    provider: 'opencode',
+    name: 'Muse Spark 1.2 Free',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: { sessionAffinityFormat: 'openai-nosession' },
+  },
+  {
+    id: 'muse-spark-1.3',
+    provider: 'opencode',
+    name: 'Muse Spark 1.3',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: { sessionAffinityFormat: 'openai-nosession' },
+  },
+  {
+    id: 'muse-spark-1.3-contributor-free',
+    provider: 'opencode',
+    name: 'Muse Spark 1.3 Free',
+    api: 'openai-responses',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: { sessionAffinityFormat: 'openai-nosession' },
+  },
+  {
+    id: 'nemotron-3-super-free',
+    provider: 'opencode',
+    name: 'Nemotron 3 Super Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 128000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'nemotron-3-ultra-free',
+    provider: 'opencode',
+    name: 'Nemotron 3 Ultra Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'nemotron-3.5-lightning-free',
+    provider: 'opencode',
+    name: 'Nemotron 3.5 Lightning Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'north-mini-code-free',
+    provider: 'opencode',
+    name: 'North Mini Code Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 64000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'qwen3-coder',
+    provider: 'opencode',
+    name: 'Qwen3 Coder',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.45, output: 1.8, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'qwen3.5-plus',
+    provider: 'opencode',
+    name: 'Qwen3.5 Plus',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+  },
+  {
+    id: 'qwen3.6-plus',
+    provider: 'opencode',
+    name: 'Qwen3.6 Plus',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0.625 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+  },
+  {
+    id: 'qwen3.6-plus-free',
+    provider: 'opencode',
+    name: 'Qwen3.6 Plus Free',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+  },
+  {
+    id: 'qwen3.8-flash',
+    provider: 'opencode',
+    name: 'Qwen3.8 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://opencode.ai/zen',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 0.15, output: 0.47, cacheRead: 0.016, cacheWrite: 0.2 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+  },
+  {
+    id: 'qwen3.8-max',
+    provider: 'opencode',
+    name: 'Qwen3.8 Max',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 2.5 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'ring-2.6-1t-free',
+    provider: 'opencode',
+    name: 'Ring 2.6 1T Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262000,
+    maxTokens: 66000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'space-bunny-free',
+    provider: 'opencode',
+    name: 'Space Bunny Free',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 524288,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'trinity-large-preview-free',
+    provider: 'opencode',
+    name: 'Trinity Large Preview',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+    },
+  },
+  {
+    id: 'x-preview-f-free',
+    provider: 'opencode',
+    name: 'Ox Alpha Free (Unlimited)',
+    api: 'openai-completions',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      maxTokensField: 'max_tokens',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/openrouter.ts b/packages/ai-models/src/providers/openrouter.ts
new file mode 100644
index 0000000000..7323a6f6c2
--- /dev/null
+++ b/packages/ai-models/src/providers/openrouter.ts
@@ -0,0 +1,11572 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** OpenRouter. */
+export const provider: ProviderRecord = {
+  id: 'openrouter',
+  name: 'OpenRouter',
+  baseUrl: 'https://openrouter.ai/api/v1',
+  apis: ['anthropic-messages', 'openai-completions'],
+  env: [['OPENROUTER_API_KEY']],
+}
+
+/** Every OpenRouter model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: '~anthropic/claude-fable-latest',
+    provider: 'openrouter',
+    name: 'Claude Fable Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 0.25, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: '~anthropic/claude-haiku-latest',
+    provider: 'openrouter',
+    name: 'Claude Haiku Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: '~anthropic/claude-opus-latest',
+    provider: 'openrouter',
+    name: 'Claude Opus Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.2, cacheWrite: 5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: '~anthropic/claude-sonnet-latest',
+    provider: 'openrouter',
+    name: 'Claude Sonnet Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: '~deepseek/deepseek-flash-latest',
+    provider: 'openrouter',
+    name: 'DeepSeek Flash Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.0198, output: 0.396, cacheRead: 0.00291, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 943718,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: '~deepseek/deepseek-pro-latest',
+    provider: 'openrouter',
+    name: 'DeepSeek Pro Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.123, output: 3.5, cacheRead: 0.123, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 393216,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: '~deepseek/deepseek-v4-flash-latest',
+    provider: 'openrouter',
+    name: 'DeepSeek V4 Flash Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: {
+      input: 0.0099,
+      output: 0.13068,
+      cacheRead: 0.001386,
+      cacheWrite: 0,
+    },
+    contextWindow: 1048576,
+    maxTokens: 943718,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: '~google/gemini-flash-latest',
+    provider: 'openrouter',
+    name: 'Gemini Flash Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0.041667 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: '~google/gemini-pro-latest',
+    provider: 'openrouter',
+    name: 'Gemini Pro Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0.375 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: '~moonshotai/kimi-latest',
+    provider: 'openrouter',
+    name: 'Kimi Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.3654, output: 9.1343, cacheRead: 0.4, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 943718,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: '~openai/gpt-astra-latest',
+    provider: 'openrouter',
+    name: 'GPT Astra Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: '~openai/gpt-luna-latest',
+    provider: 'openrouter',
+    name: 'GPT Luna Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: '~openai/gpt-mini-latest',
+    provider: 'openrouter',
+    name: 'GPT Mini Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.75, output: 4.5, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: '~openai/gpt-sol-latest',
+    provider: 'openrouter',
+    name: 'GPT Sol Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: '~openai/gpt-terra-latest',
+    provider: 'openrouter',
+    name: 'GPT Terra Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: '~x-ai/grok-latest',
+    provider: 'openrouter',
+    name: 'Grok Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 450000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: '~z-ai/glm-flash-latest',
+    provider: 'openrouter',
+    name: 'GLM Flash Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.02, output: 0.2475, cacheRead: 0.01, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 943718,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: '~z-ai/glm-latest',
+    provider: 'openrouter',
+    name: 'GLM Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.13, output: 4, cacheRead: 0.13, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'aion-labs/aion-2.0',
+    provider: 'openrouter',
+    name: 'Aion-2.0',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.8, output: 1.6, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'aion-labs/aion-3.0',
+    provider: 'openrouter',
+    name: 'Aion-3.0',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 3, output: 6, cacheRead: 0.75, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'aion-labs/aion-3.0-mini',
+    provider: 'openrouter',
+    name: 'Aion-3.0-Mini',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.7, output: 1.4, cacheRead: 0.18, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'aion-labs/aion-3.5',
+    provider: 'openrouter',
+    name: 'Aion 3.5',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 3, output: 6, cacheRead: 0.75, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'aion-labs/aion-3.5-mini',
+    provider: 'openrouter',
+    name: 'Aion 3.5 Mini',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.7, output: 1.4, cacheRead: 0.18, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'aion-labs/aion-rp-llama-3.1-8b',
+    provider: 'openrouter',
+    name: 'Aion-RP 1.0 (8B)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.8, output: 1.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 29491,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'amazon/nova-2-lite-v1',
+    provider: 'openrouter',
+    name: 'Nova 2 Lite',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.3, output: 2.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 65535,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'amazon/nova-lite-v1',
+    provider: 'openrouter',
+    name: 'Nova Lite 1.0',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.06, output: 0.24, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 300000,
+    maxTokens: 5120,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'amazon/nova-micro-v1',
+    provider: 'openrouter',
+    name: 'Nova Micro 1.0',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.035, output: 0.14, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 5120,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'amazon/nova-premier-v1',
+    provider: 'openrouter',
+    name: 'Nova Premier 1.0',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 2.5, output: 12.5, cacheRead: 0.625, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 32000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'amazon/nova-pro-v1',
+    provider: 'openrouter',
+    name: 'Nova Pro 1.0',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.8, output: 3.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 300000,
+    maxTokens: 5120,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'anthracite-org/magnum-v4-72b',
+    provider: 'openrouter',
+    name: 'Magnum v4 72B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 2.5, output: 5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 4096,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'anthropic/claude-3-haiku',
+    provider: 'openrouter',
+    name: 'Claude Haiku 3',
+    api: 'anthropic-messages',
+    baseUrl: 'https://openrouter.ai/api',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.25, output: 1.25, cacheRead: 0.03, cacheWrite: 0.3 },
+    contextWindow: 200000,
+    maxTokens: 4096,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+    },
+    borrowedFrom: 'vercel/anthropic/claude-3-haiku',
+  },
+  {
+    id: 'anthropic/claude-fable-5',
+    provider: 'openrouter',
+    name: 'Claude Fable 5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://openrouter.ai/api',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'anthropic/claude-fable-5:batch',
+    provider: 'openrouter',
+    name: 'Anthropic: Claude Fable 5 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'anthropic/claude-fable-5.1',
+    provider: 'openrouter',
+    name: 'Claude Fable 5.1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://openrouter.ai/api',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 0.25, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'anthropic/claude-fable-5.1:batch',
+    provider: 'openrouter',
+    name: 'Anthropic: Claude Fable 5.1 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.125, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'anthropic/claude-haiku-4.5',
+    provider: 'openrouter',
+    name: 'Claude Haiku 4.5 (latest)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://openrouter.ai/api',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+    },
+  },
+  {
+    id: 'anthropic/claude-haiku-4.5:batch',
+    provider: 'openrouter',
+    name: 'Anthropic: Claude Haiku 4.5 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    cost: { input: 0.5, output: 2.5, cacheRead: 0.05, cacheWrite: 0.625 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+    },
+  },
+  {
+    id: 'anthropic/claude-opus-4.1',
+    provider: 'openrouter',
+    name: 'Claude Opus 4.1 (latest)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://openrouter.ai/api',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+    contextWindow: 200000,
+    maxTokens: 32000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+    },
+  },
+  {
+    id: 'anthropic/claude-opus-4.1:batch',
+    provider: 'openrouter',
+    name: 'Anthropic: Claude Opus 4.1 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    cost: { input: 7.5, output: 37.5, cacheRead: 0.75, cacheWrite: 9.375 },
+    contextWindow: 200000,
+    maxTokens: 32000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+    },
+  },
+  {
+    id: 'anthropic/claude-opus-4.5',
+    provider: 'openrouter',
+    name: 'Claude Opus 4.5 (latest)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://openrouter.ai/api',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+    },
+  },
+  {
+    id: 'anthropic/claude-opus-4.5:batch',
+    provider: 'openrouter',
+    name: 'Anthropic: Claude Opus 4.5 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    cost: { input: 2.5, output: 12.5, cacheRead: 0.25, cacheWrite: 3.125 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+    },
+  },
+  {
+    id: 'anthropic/claude-opus-4.6',
+    provider: 'openrouter',
+    name: 'Claude Opus 4.6',
+    api: 'anthropic-messages',
+    baseUrl: 'https://openrouter.ai/api',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+    },
+  },
+  {
+    id: 'anthropic/claude-opus-4.6:batch',
+    provider: 'openrouter',
+    name: 'Anthropic: Claude Opus 4.6 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 2.5, output: 12.5, cacheRead: 0.25, cacheWrite: 3.125 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+    },
+  },
+  {
+    id: 'anthropic/claude-opus-4.7',
+    provider: 'openrouter',
+    name: 'Claude Opus 4.7',
+    api: 'anthropic-messages',
+    baseUrl: 'https://openrouter.ai/api',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'anthropic/claude-opus-4.7:batch',
+    provider: 'openrouter',
+    name: 'Anthropic: Claude Opus 4.7 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2.5, output: 12.5, cacheRead: 0.25, cacheWrite: 3.125 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'anthropic/claude-opus-4.8',
+    provider: 'openrouter',
+    name: 'Claude Opus 4.8',
+    api: 'anthropic-messages',
+    baseUrl: 'https://openrouter.ai/api',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'anthropic/claude-opus-4.8:batch',
+    provider: 'openrouter',
+    name: 'Anthropic: Claude Opus 4.8 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2.5, output: 12.5, cacheRead: 0.25, cacheWrite: 3.125 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'anthropic/claude-opus-5',
+    provider: 'openrouter',
+    name: 'Claude Opus 5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://openrouter.ai/api',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'anthropic/claude-opus-5:batch',
+    provider: 'openrouter',
+    name: 'Anthropic: Claude Opus 5 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2.5, output: 12.5, cacheRead: 0.25, cacheWrite: 3.125 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'anthropic/claude-opus-5.5',
+    provider: 'openrouter',
+    name: 'Claude Opus 5.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://openrouter.ai/api',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.2, cacheWrite: 5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'anthropic/claude-opus-5.5:batch',
+    provider: 'openrouter',
+    name: 'Anthropic: Claude Opus 5.5 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'anthropic/claude-sonnet-4',
+    provider: 'openrouter',
+    name: 'Claude Sonnet 4',
+    api: 'anthropic-messages',
+    baseUrl: 'https://openrouter.ai/api',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+    },
+  },
+  {
+    id: 'anthropic/claude-sonnet-4.5',
+    provider: 'openrouter',
+    name: 'Claude Sonnet 4.5 (latest)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://openrouter.ai/api',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+    },
+  },
+  {
+    id: 'anthropic/claude-sonnet-4.5:batch',
+    provider: 'openrouter',
+    name: 'Anthropic: Claude Sonnet 4.5 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    cost: { input: 1.5, output: 7.5, cacheRead: 0.15, cacheWrite: 1.875 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+    },
+  },
+  {
+    id: 'anthropic/claude-sonnet-4.6',
+    provider: 'openrouter',
+    name: 'Claude Sonnet 4.6',
+    api: 'anthropic-messages',
+    baseUrl: 'https://openrouter.ai/api',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'anthropic/claude-sonnet-4.6:batch',
+    provider: 'openrouter',
+    name: 'Anthropic: Claude Sonnet 4.6 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.5, output: 7.5, cacheRead: 0.15, cacheWrite: 1.875 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+    },
+  },
+  {
+    id: 'anthropic/claude-sonnet-5',
+    provider: 'openrouter',
+    name: 'Claude Sonnet 5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://openrouter.ai/api',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'anthropic/claude-sonnet-5:batch',
+    provider: 'openrouter',
+    name: 'Anthropic: Claude Sonnet 5 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'anthropic/claude-sonnet-5.5',
+    provider: 'openrouter',
+    name: 'Claude Sonnet 5.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://openrouter.ai/api',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'anthropic/claude-sonnet-5.5:batch',
+    provider: 'openrouter',
+    name: 'Anthropic: Claude Sonnet 5.5 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      cacheControlFormat: 'anthropic',
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'arcee-ai/trinity-large-thinking',
+    provider: 'openrouter',
+    name: 'Trinity Large Thinking',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.25, output: 0.8, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 80000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'auto',
+    provider: 'openrouter',
+    name: 'Auto Router',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 2000000,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+    borrowedFrom: 'kilo/openrouter/auto',
+  },
+  {
+    id: 'baidu/ernie-4.5-vl-424b-a47b',
+    provider: 'openrouter',
+    name: 'ERNIE 4.5 VL 424B A47B ',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.42, output: 1.25, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 123000,
+    maxTokens: 16000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'bytedance-seed/seed-1.6',
+    provider: 'openrouter',
+    name: 'Seed 1.6',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.25, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'bytedance-seed/seed-1.6-flash',
+    provider: 'openrouter',
+    name: 'Seed 1.6 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.075, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'bytedance-seed/seed-2-1-turbo',
+    provider: 'openrouter',
+    name: 'Seed 2.1 Turbo',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.5, output: 2.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'bytedance-seed/seed-2.0-code',
+    provider: 'openrouter',
+    name: 'Seed 2.0 Code',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.5, output: 3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'bytedance-seed/seed-2.0-lite',
+    provider: 'openrouter',
+    name: 'Seed 2.0 Lite',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'bytedance-seed/seed-2.0-mini',
+    provider: 'openrouter',
+    name: 'Seed 2.0 Mini',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.1, output: 0.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'bytedance/ui-tars-1.5-7b',
+    provider: 'openrouter',
+    name: 'UI-TARS 7B ',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.2, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 2048,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'cognitivecomputations/dolphin-mistral-24b-venice-edition',
+    provider: 'openrouter',
+    name: 'Uncensored',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.2, output: 0.9, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'cohere/command-a',
+    provider: 'openrouter',
+    name: 'Command A',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 2.5, output: 10, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 8192,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'cohere/command-a-plus',
+    provider: 'openrouter',
+    name: 'Command A+',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.3, output: 1.5, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 192000,
+    maxTokens: 64000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'cohere/command-r-08-2024',
+    provider: 'openrouter',
+    name: 'Command R',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'cohere/command-r-plus-08-2024',
+    provider: 'openrouter',
+    name: 'Command R+',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 2.5, output: 10, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'cohere/command-r7b-12-2024',
+    provider: 'openrouter',
+    name: 'Command R7B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.0375, output: 0.15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'cohere/north-mini-code:free',
+    provider: 'openrouter',
+    name: 'North Mini Code (free)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 64000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'deepseek/deepseek-chat',
+    provider: 'openrouter',
+    name: 'DeepSeek Chat',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.2574, output: 1.0287, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 16000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'deepseek/deepseek-chat-v3-0324',
+    provider: 'openrouter',
+    name: 'DeepSeek V3 0324',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.29, output: 1.14, cacheRead: 0.11, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 147456,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'deepseek/deepseek-chat-v3.1',
+    provider: 'openrouter',
+    name: 'DeepSeek V3.1',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.25, output: 0.95, cacheRead: 0.13, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'deepseek/deepseek-r1',
+    provider: 'openrouter',
+    name: 'DeepSeek-R1',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.7, output: 2.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 64000,
+    maxTokens: 16000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'deepseek/deepseek-r1-0528',
+    provider: 'openrouter',
+    name: 'R1 0528',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.5, output: 2.15, cacheRead: 0.35, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'deepseek/deepseek-v3.1-terminus',
+    provider: 'openrouter',
+    name: 'DeepSeek V3.1 Terminus',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.3, output: 1, cacheRead: 0.135, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'deepseek/deepseek-v3.2',
+    provider: 'openrouter',
+    name: 'DeepSeek V3.2',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.28, output: 0.42, cacheRead: 0.028, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'deepseek/deepseek-v3.2-exp',
+    provider: 'openrouter',
+    name: 'DeepSeek V3.2 Exp',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.27, output: 0.41, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 147456,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'deepseek/deepseek-v4-flash',
+    provider: 'openrouter',
+    name: 'DeepSeek V4 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.028, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'deepseek/deepseek-v4-flash-0731',
+    provider: 'openrouter',
+    name: 'DeepSeek V4 Flash 0731',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.01, output: 1.28, cacheRead: 0.01, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 943718,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'deepseek/deepseek-v4-flash-vision-exp',
+    provider: 'openrouter',
+    name: 'DeepSeek V4 Flash Vision Exp',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.2156, output: 0.6468, cacheRead: 0.00686, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 262144,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'deepseek/deepseek-v4-pro',
+    provider: 'openrouter',
+    name: 'DeepSeek V4 Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.783, output: 1.566, cacheRead: 0.06525, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 384000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'deepseek/deepseek-v4-pro-0813',
+    provider: 'openrouter',
+    name: 'DeepSeek V4 Pro 0813',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.66, output: 1.98, cacheRead: 0.022, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 393216,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'deepseek/deepseek-v4.1-flash',
+    provider: 'openrouter',
+    name: 'DeepSeek V4.1 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.0198, output: 0.396, cacheRead: 0.00291, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 943718,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'deepseek/deepseek-v4.1-flash:batch',
+    provider: 'openrouter',
+    name: 'DeepSeek: DeepSeek V4.1 Flash (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.112, output: 0.336, cacheRead: 0.00336, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'dots-studio/dots-3-note-preview:free',
+    provider: 'openrouter',
+    name: 'Dots3-Note Preview (free)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 512000,
+    maxTokens: 460800,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'fireworks/ember-1',
+    provider: 'openrouter',
+    name: 'Ember-1',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 943718,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-2.5-flash',
+    provider: 'openrouter',
+    name: 'Gemini 2.5 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.3, output: 2.5, cacheRead: 0.03, cacheWrite: 0.083333 },
+    contextWindow: 1048576,
+    maxTokens: 65535,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-2.5-flash-image',
+    provider: 'openrouter',
+    name: 'Nano Banana',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.3, output: 2.5, cacheRead: 0.03, cacheWrite: 0.083333 },
+    contextWindow: 32768,
+    maxTokens: 8192,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-2.5-flash-lite',
+    provider: 'openrouter',
+    name: 'Gemini 2.5 Flash-Lite',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.1, output: 0.4, cacheRead: 0.01, cacheWrite: 0.083333 },
+    contextWindow: 1048576,
+    maxTokens: 65535,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-2.5-flash-lite:batch',
+    provider: 'openrouter',
+    name: 'Google: Gemini 2.5 Flash Lite (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    cost: { input: 0.05, output: 0.2, cacheRead: 0.01, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65535,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-2.5-flash:batch',
+    provider: 'openrouter',
+    name: 'Google: Gemini 2.5 Flash (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    cost: { input: 0.15, output: 1.25, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65535,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-2.5-pro',
+    provider: 'openrouter',
+    name: 'Gemini 2.5 Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0.375 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-2.5-pro-preview',
+    provider: 'openrouter',
+    name: 'Gemini 2.5 Pro Preview 06-05',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0.375 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-2.5-pro:batch',
+    provider: 'openrouter',
+    name: 'Google: Gemini 2.5 Pro (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    cost: { input: 0.625, output: 5, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3-flash-preview',
+    provider: 'openrouter',
+    name: 'Gemini 3 Flash Preview',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0.083333 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3-flash-preview:batch',
+    provider: 'openrouter',
+    name: 'Google: Gemini 3 Flash Preview (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 1.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3-pro-image',
+    provider: 'openrouter',
+    name: 'Nano Banana Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0.375 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3-pro-image-preview',
+    provider: 'openrouter',
+    name: 'Nano Banana Pro Preview',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0.375 },
+    contextWindow: 65536,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.1-flash-image',
+    provider: 'openrouter',
+    name: 'Nano Banana 2',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.5, output: 3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.1-flash-image-preview',
+    provider: 'openrouter',
+    name: 'Nano Banana 2 Preview',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.5, output: 3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 65536,
+    maxTokens: 58982,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.1-flash-lite',
+    provider: 'openrouter',
+    name: 'Gemini 3.1 Flash Lite',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 1.5, cacheRead: 0.025, cacheWrite: 0.083333 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.1-flash-lite-image',
+    provider: 'openrouter',
+    name: 'Nano Banana 2 Lite',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 1.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 65536,
+    maxTokens: 58982,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.1-flash-lite-preview',
+    provider: 'openrouter',
+    name: 'Gemini 3.1 Flash Lite Preview',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 1.5, cacheRead: 0.025, cacheWrite: 0.083333 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.1-flash-lite:batch',
+    provider: 'openrouter',
+    name: 'Google: Gemini 3.1 Flash Lite (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.125, output: 0.75, cacheRead: 0.0125, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.1-pro-preview',
+    provider: 'openrouter',
+    name: 'Gemini 3.1 Pro Preview',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0.375 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.1-pro-preview-customtools',
+    provider: 'openrouter',
+    name: 'Gemini 3.1 Pro Preview Custom Tools',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0.375 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.1-pro-preview:batch',
+    provider: 'openrouter',
+    name: 'Google: Gemini 3.1 Pro Preview (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1, output: 6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.5-flash',
+    provider: 'openrouter',
+    name: 'Gemini 3.5 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.5, output: 9, cacheRead: 0.15, cacheWrite: 0.083333 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.5-flash-lite',
+    provider: 'openrouter',
+    name: 'Gemini 3.5 Flash Lite',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.3, output: 2.5, cacheRead: 0.03, cacheWrite: 0.083333 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.5-flash-lite:batch',
+    provider: 'openrouter',
+    name: 'Google: Gemini 3.5 Flash Lite (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.15, output: 1.25, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.5-flash:batch',
+    provider: 'openrouter',
+    name: 'Google: Gemini 3.5 Flash (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.75, output: 4.5, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.6-flash',
+    provider: 'openrouter',
+    name: 'Gemini 3.6 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0.041667 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.6-flash:batch',
+    provider: 'openrouter',
+    name: 'Google: Gemini 3.6 Flash (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: {
+      input: 0.375,
+      output: 1.875,
+      cacheRead: 0.0375,
+      cacheWrite: 0.041667,
+    },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.7-flash',
+    provider: 'openrouter',
+    name: 'Gemini 3.7 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0.041667 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.7-flash:batch',
+    provider: 'openrouter',
+    name: 'Google: Gemini 3.7 Flash (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: {
+      input: 0.375,
+      output: 1.875,
+      cacheRead: 0.0375,
+      cacheWrite: 0.041667,
+    },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.8-flash',
+    provider: 'openrouter',
+    name: 'Gemini 3.8 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0.041667 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemini-3.8-flash:batch',
+    provider: 'openrouter',
+    name: 'Google: Gemini 3.8 Flash (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: {
+      input: 0.375,
+      output: 1.875,
+      cacheRead: 0.0375,
+      cacheWrite: 0.041667,
+    },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'google/gemma-2-27b-it',
+    provider: 'openrouter',
+    name: 'Gemma 2 27B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.65, output: 0.65, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 2048,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemma-3-12b-it',
+    provider: 'openrouter',
+    name: 'Gemma 3 12B IT',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.05, output: 0.15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemma-3-27b-it',
+    provider: 'openrouter',
+    name: 'Gemma 3 27B IT',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.08, output: 0.45, cacheRead: 0.04, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 117964,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemma-3-4b-it',
+    provider: 'openrouter',
+    name: 'Gemma 3 4B IT',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.05, output: 0.1, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemma-4-26b-a4b-it',
+    provider: 'openrouter',
+    name: 'Gemma 4 26B A4B IT',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.09, output: 0.3, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemma-4-26b-a4b-it:free',
+    provider: 'openrouter',
+    name: 'Gemma 4 26B A4B  (free)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemma-4-31b-it',
+    provider: 'openrouter',
+    name: 'Gemma 4 31B IT',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.09, output: 0.34, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/gemma-4-31b-it:free',
+    provider: 'openrouter',
+    name: 'Gemma 4 31B (free)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/lyria-3-clip-preview',
+    provider: 'openrouter',
+    name: 'Lyria 3 Clip Preview',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'google/lyria-3-pro-preview',
+    provider: 'openrouter',
+    name: 'Lyria 3 Pro Preview',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'gryphe/mythomax-l2-13b',
+    provider: 'openrouter',
+    name: 'MythoMax 13B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.08, output: 0.11, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 3686,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'ibm-granite/granite-4.0-h-micro',
+    provider: 'openrouter',
+    name: 'Granite 4.0 Micro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.017, output: 0.112, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131000,
+    maxTokens: 117900,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'ibm-granite/granite-4.2-8b',
+    provider: 'openrouter',
+    name: 'Granite 4.2 8B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.06, output: 0.25, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 117964,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'inception/mercury-2',
+    provider: 'openrouter',
+    name: 'Mercury 2',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 0.75, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 50000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'inception/mercury-2.5',
+    provider: 'openrouter',
+    name: 'Mercury 2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.04, output: 0.15, cacheRead: 0.004, cacheWrite: 0 },
+    contextWindow: 260000,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'inclusionai/ling-3.0-flash',
+    provider: 'openrouter',
+    name: 'Ling 3.0 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.021, output: 0.063, cacheRead: 0.0042, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'inclusionai/ling-3.0-flash-fin',
+    provider: 'openrouter',
+    name: 'Ling 3.0 Flash Fin',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.06, output: 0.18, cacheRead: 0.012, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'inclusionai/ling-3.0-flash-fin:free',
+    provider: 'openrouter',
+    name: 'inclusionAI: Ling 3.0 Flash Fin',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.075, output: 0.22, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+    borrowedFrom: 'kilo/inclusionai/ling-3.0-flash-fin',
+  },
+  {
+    id: 'inclusionai/ling-3.0-flash-sante:free',
+    provider: 'openrouter',
+    name: 'Ling 3.0 Flash Sante (free)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'inclusionai/ling-3.0-flash-vl',
+    provider: 'openrouter',
+    name: 'Ling 3.0 Flash VL',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.021, output: 0.0616, cacheRead: 0.0042, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'inclusionai/ling-3.0-flash-vl:free',
+    provider: 'openrouter',
+    name: 'Ling 3.0 Flash VL',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.06, output: 0.18, cacheRead: 0.012, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+    borrowedFrom: 'nano-gpt/inclusionai/ling-3.0-flash-vl',
+  },
+  {
+    id: 'inference-net/schematron-v2-small',
+    provider: 'openrouter',
+    name: 'Schematron V2 Small',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.05, output: 0.23, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'inference-net/schematron-v2-turbo',
+    provider: 'openrouter',
+    name: 'Schematron V2 Turbo',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.03, output: 0.15, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'kwaipilot/kat-coder-pro-v2.5',
+    provider: 'openrouter',
+    name: 'KAT-Coder-Pro V2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.74, output: 2.96, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'liquid/lfm-2.5-2.6b:free',
+    provider: 'openrouter',
+    name: 'LFM2.5-2.6B (free)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 65536,
+    maxTokens: 8192,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mancer/weaver',
+    provider: 'openrouter',
+    name: 'Weaver (alpha)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.4, output: 0.75, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8000,
+    maxTokens: 6000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'meituan/longcat-2.0',
+    provider: 'openrouter',
+    name: 'LongCat 2.0',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.006, cacheWrite: 0 },
+    contextWindow: 1048756,
+    maxTokens: 262144,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'meta-llama/llama-3.1-70b-instruct',
+    provider: 'openrouter',
+    name: 'Llama-3.1-70B-Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.4, output: 0.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'meta-llama/llama-3.1-8b-instruct',
+    provider: 'openrouter',
+    name: 'Llama-3.1-8B-Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.05, output: 0.08, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 117964,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'meta-llama/llama-3.2-1b-instruct',
+    provider: 'openrouter',
+    name: 'Llama 3.2 1B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.027, output: 0.201, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 60000,
+    maxTokens: 54000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'meta-llama/llama-3.2-3b-instruct',
+    provider: 'openrouter',
+    name: 'Llama 3.2 3B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.05, output: 0.33, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 117964,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'meta-llama/llama-3.3-70b-instruct',
+    provider: 'openrouter',
+    name: 'Llama-3.3-70B-Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.32, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'meta-llama/llama-4-maverick',
+    provider: 'openrouter',
+    name: 'Llama 4 Maverick',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.1875, output: 0.6525, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'meta-llama/llama-4-scout',
+    provider: 'openrouter',
+    name: 'Llama 4 Scout',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1310720,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'meta-llama/llama-guard-4-12b',
+    provider: 'openrouter',
+    name: 'Llama Guard 4 12B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.18, output: 0.18, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'meta/muse-glimmer-30b',
+    provider: 'openrouter',
+    name: 'Muse Glimmer 30B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.35, output: 1.5, cacheRead: 0.04, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 117964,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'meta/muse-spark-1.1',
+    provider: 'openrouter',
+    name: 'Muse Spark 1.1',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 943718,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'meta/muse-spark-1.2',
+    provider: 'openrouter',
+    name: 'Muse Spark 1.2',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 943718,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'meta/muse-spark-1.2-contributor',
+    provider: 'openrouter',
+    name: 'Muse Spark 1.2 Contributor',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.1, output: 0.2, cacheRead: 0.002, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 943718,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'meta/muse-spark-1.3',
+    provider: 'openrouter',
+    name: 'Muse Spark 1.3',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 943718,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'meta/muse-spark-1.3-contributor',
+    provider: 'openrouter',
+    name: 'Muse Spark 1.3 Contributor',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.1, output: 0.2, cacheRead: 0.002, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 943718,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'microsoft/phi-4',
+    provider: 'openrouter',
+    name: 'Phi 4',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.07, output: 0.14, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 16384,
+    maxTokens: 14745,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'microsoft/wizardlm-2-8x22b',
+    provider: 'openrouter',
+    name: 'WizardLM-2 8x22B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.62, output: 0.62, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 65535,
+    maxTokens: 8000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'minimax/minimax-01',
+    provider: 'openrouter',
+    name: 'MiniMax-01',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.2, output: 1.1, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000192,
+    maxTokens: 40000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'minimax/minimax-m1',
+    provider: 'openrouter',
+    name: 'MiniMax M1',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.4, output: 2.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 40000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'minimax/minimax-m2',
+    provider: 'openrouter',
+    name: 'MiniMax-M2',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 176947,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'minimax/minimax-m2-her',
+    provider: 'openrouter',
+    name: 'MiniMax-M2 Her',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 65536,
+    maxTokens: 2048,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'minimax/minimax-m2.1',
+    provider: 'openrouter',
+    name: 'MiniMax-M2.1',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'minimax/minimax-m2.5',
+    provider: 'openrouter',
+    name: 'MiniMax-M2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.27, output: 1.08, cacheRead: 0.027, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'minimax/minimax-m2.7',
+    provider: 'openrouter',
+    name: 'MiniMax-M2.7',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.21, output: 0.84, cacheRead: 0.042, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 176947,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'minimax/minimax-m3',
+    provider: 'openrouter',
+    name: 'MiniMax-M3',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 512000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/codestral-2508',
+    provider: 'openrouter',
+    name: 'Codestral 2508',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'document'],
+    reasoning: false,
+    cost: { input: 0.3, output: 0.9, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 204800,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/codestral-2508:batch',
+    provider: 'openrouter',
+    name: 'Mistral: Codestral 2508 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'document'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0.45, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 204800,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/devstral-2512',
+    provider: 'openrouter',
+    name: 'Devstral 2',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'document'],
+    reasoning: false,
+    cost: { input: 0.4, output: 2, cacheRead: 0.04, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 209715,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/ministral-14b-2512',
+    provider: 'openrouter',
+    name: 'Ministral 3 14B 2512',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.2, output: 0.2, cacheRead: 0.02, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 209715,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/ministral-3b-2512',
+    provider: 'openrouter',
+    name: 'Ministral 3 3B 2512',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.1, cacheRead: 0.01, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 104857,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/ministral-8b-2512',
+    provider: 'openrouter',
+    name: 'Ministral 3 8B 2512',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0.15, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 209715,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/ministral-8b-2512:batch',
+    provider: 'openrouter',
+    name: 'Mistral: Ministral 3 8B 2512 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.075, output: 0.075, cacheRead: 0.0075, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 209715,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-large',
+    provider: 'openrouter',
+    name: 'Mistral Large',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'document'],
+    reasoning: false,
+    cost: { input: 2, output: 6, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 102400,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-large-2407',
+    provider: 'openrouter',
+    name: 'Mistral Large 2407',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'document'],
+    reasoning: false,
+    cost: { input: 2, output: 6, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 104857,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-large-2512',
+    provider: 'openrouter',
+    name: 'Mistral Large 3',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.5, output: 1.5, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 209715,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-large-2512:batch',
+    provider: 'openrouter',
+    name: 'Mistral: Mistral Large 3 2512 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.25, output: 0.75, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 209715,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-medium-3',
+    provider: 'openrouter',
+    name: 'Mistral Medium 3',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.4, output: 2, cacheRead: 0.04, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 104857,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-medium-3-5',
+    provider: 'openrouter',
+    name: 'Mistral Medium 3.5',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.5, output: 7.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 209715,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-medium-3-5:batch',
+    provider: 'openrouter',
+    name: 'Mistral: Mistral Medium 3.5 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.75, output: 3.75, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 209715,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-medium-3.1',
+    provider: 'openrouter',
+    name: 'Mistral Medium 3.1',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.4, output: 2, cacheRead: 0.04, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 104857,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-medium-3.1:batch',
+    provider: 'openrouter',
+    name: 'Mistral: Mistral Medium 3.1 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.2, output: 1, cacheRead: 0.02, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 104857,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-nemo',
+    provider: 'openrouter',
+    name: 'Mistral Nemo',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.019, output: 0.03, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-saba',
+    provider: 'openrouter',
+    name: 'Saba',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'document'],
+    reasoning: false,
+    cost: { input: 0.2, output: 0.6, cacheRead: 0.02, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 26214,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-small-24b-instruct-2501',
+    provider: 'openrouter',
+    name: 'Mistral Small 3',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.05, output: 0.08, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-small-2603',
+    provider: 'openrouter',
+    name: 'Mistral Small 4',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 209715,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-small-2603:batch',
+    provider: 'openrouter',
+    name: 'Mistral: Mistral Small 4 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.075, output: 0.3, cacheRead: 0.0075, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 209715,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-small-3.1-24b-instruct',
+    provider: 'openrouter',
+    name: 'Mistral Small 3.1 24B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.351, output: 0.555, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 102400,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/mistral-small-3.2-24b-instruct',
+    provider: 'openrouter',
+    name: 'Mistral Small 3.2 24B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.09375, output: 0.25, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/mixtral-8x22b-instruct',
+    provider: 'openrouter',
+    name: 'Mixtral 8x22B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'document'],
+    reasoning: false,
+    cost: { input: 2, output: 6, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 65536,
+    maxTokens: 52428,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'mistralai/voxtral-small-24b-2507',
+    provider: 'openrouter',
+    name: 'Voxtral Small 24B 2507',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'audio', 'document'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.3, cacheRead: 0.01, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 26214,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'moonshotai/kimi-k2',
+    provider: 'openrouter',
+    name: 'Kimi K2 0711',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.57, output: 2.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 98304,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'moonshotai/kimi-k2-0905',
+    provider: 'openrouter',
+    name: 'Kimi K2 0905',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.6, output: 2.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 98304,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'moonshotai/kimi-k2-thinking',
+    provider: 'openrouter',
+    name: 'Kimi K2 Thinking',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.6, output: 2.5, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 98304,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'moonshotai/kimi-k2.5',
+    provider: 'openrouter',
+    name: 'Kimi K2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.45, output: 2.25, cacheRead: 0.07, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'moonshotai/kimi-k2.6',
+    provider: 'openrouter',
+    name: 'Kimi K2.6',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.65, output: 3.41, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'moonshotai/kimi-k2.7-code',
+    provider: 'openrouter',
+    name: 'Kimi K2.7 Code',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.6712, output: 3.35, cacheRead: 0.18, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'moonshotai/kimi-k3',
+    provider: 'openrouter',
+    name: 'Kimi K3',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 943718,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'moonshotai/kimi-k3:batch',
+    provider: 'openrouter',
+    name: 'MoonshotAI: Kimi K3 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 2.28, output: 11.4, cacheRead: 0.228, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'morph/morph-v3-fast',
+    provider: 'openrouter',
+    name: 'Morph V3 Fast',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.8, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 81920,
+    maxTokens: 38000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'morph/morph-v3-large',
+    provider: 'openrouter',
+    name: 'Morph V3 Large',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.9, output: 1.9, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'nex-agi/nex-n2.5-mini',
+    provider: 'openrouter',
+    name: 'Nex-N2.5-Mini',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.025, output: 0.1, cacheRead: 0.0025, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'nex-agi/nex-n2.5-mini:free',
+    provider: 'openrouter',
+    name: 'Nex AGI: Nex-N2.5-Mini',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.025, output: 0.1, cacheRead: 0.0025, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+    borrowedFrom: 'kilo/nex-agi/nex-n2.5-mini',
+  },
+  {
+    id: 'nex-agi/nex-n2.5-pro',
+    provider: 'openrouter',
+    name: 'Nex-N2.5-Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.075, output: 0.25, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'nex-agi/nex-n2.5-pro:free',
+    provider: 'openrouter',
+    name: 'Nex AGI: Nex-N2.5-Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.075, output: 0.25, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+    borrowedFrom: 'kilo/nex-agi/nex-n2.5-pro',
+  },
+  {
+    id: 'nousresearch/hermes-3-llama-3.1-405b',
+    provider: 'openrouter',
+    name: 'Hermes 3 405B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'nousresearch/hermes-3-llama-3.1-70b',
+    provider: 'openrouter',
+    name: 'Hermes 3 70B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.7, output: 0.7, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'nousresearch/hermes-4-405b',
+    provider: 'openrouter',
+    name: 'Hermes 4 405B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1, output: 3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 117964,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-3-nano-30b-a3b',
+    provider: 'openrouter',
+    name: 'Nemotron 3 Nano 30B A3B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.05, output: 0.2, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free',
+    provider: 'openrouter',
+    name: 'Nemotron 3 Nano Omni (free)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-3-super-120b-a12b',
+    provider: 'openrouter',
+    name: 'Nemotron 3 Super 120B A12B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: null,
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 0.08, output: 0.45, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-3-super-120b-a12b:free',
+    provider: 'openrouter',
+    name: 'Nemotron 3 Super (free)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: null,
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-3-ultra-550b-a55b',
+    provider: 'openrouter',
+    name: 'Nemotron 3 Ultra 550B A55B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 182520,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-3-ultra-550b-a55b:free',
+    provider: 'openrouter',
+    name: 'Nemotron 3 Ultra (free)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-3.5-content-safety',
+    provider: 'openrouter',
+    name: 'Nemotron 3.5 Content Safety',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.2, output: 0.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 117964,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-3.5-content-safety:free',
+    provider: 'openrouter',
+    name: 'Nemotron 3.5 Content Safety (free)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-3.5-lightning',
+    provider: 'openrouter',
+    name: 'Nemotron 3.5 Lightning 30B A3B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.06, output: 0.16, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-3.5-lightning:free',
+    provider: 'openrouter',
+    name: 'Nemotron 3.5 Lightning (free)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'openai/gpt-3.5-turbo',
+    provider: 'openrouter',
+    name: 'GPT-3.5-turbo',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.5, output: 1.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 16385,
+    maxTokens: 4096,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-3.5-turbo-0613',
+    provider: 'openrouter',
+    name: 'GPT-3.5 Turbo (older v0613)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 1, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 4095,
+    maxTokens: 3685,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-3.5-turbo-16k',
+    provider: 'openrouter',
+    name: 'GPT-3.5 Turbo 16k',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 3, output: 4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 16385,
+    maxTokens: 4096,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-3.5-turbo-instruct',
+    provider: 'openrouter',
+    name: 'GPT-3.5 Turbo Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 1.5, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 4095,
+    maxTokens: 3685,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-3.5-turbo:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-3.5 Turbo (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.25, output: 0.75, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 16385,
+    maxTokens: 4096,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-4',
+    provider: 'openrouter',
+    name: 'GPT-4',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 30, output: 60, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8191,
+    maxTokens: 4096,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-4-turbo',
+    provider: 'openrouter',
+    name: 'GPT-4 Turbo',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 10, output: 30, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-4-turbo:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-4 Turbo (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 5, output: 15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-4.1',
+    provider: 'openrouter',
+    name: 'GPT-4.1',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 2, output: 8, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-4.1-mini',
+    provider: 'openrouter',
+    name: 'GPT-4.1 mini',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.4, output: 1.6, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-4.1-mini:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-4.1 Mini (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.2, output: 0.8, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-4.1-nano',
+    provider: 'openrouter',
+    name: 'GPT-4.1 nano',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.4, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-4.1-nano:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-4.1 Nano (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.05, output: 0.2, cacheRead: 0.0125, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-4.1:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-4.1 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 1, output: 4, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-4o',
+    provider: 'openrouter',
+    name: 'GPT-4o',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 2.5, output: 10, cacheRead: 1.25, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-4o-2024-05-13',
+    provider: 'openrouter',
+    name: 'GPT-4o (2024-05-13)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 5, output: 15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-4o-2024-08-06',
+    provider: 'openrouter',
+    name: 'GPT-4o (2024-08-06)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 2.5, output: 10, cacheRead: 1.25, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-4o-2024-11-20',
+    provider: 'openrouter',
+    name: 'GPT-4o (2024-11-20)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 2.5, output: 10, cacheRead: 1.25, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-4o-mini',
+    provider: 'openrouter',
+    name: 'GPT-4o mini',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-4o-mini-2024-07-18',
+    provider: 'openrouter',
+    name: 'GPT-4o-mini (2024-07-18)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-4o-mini:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-4o-mini (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.075, output: 0.3, cacheRead: 0.0375, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-4o:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-4o (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 1.25, output: 5, cacheRead: 0.625, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-5',
+    provider: 'openrouter',
+    name: 'GPT-5',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5-image',
+    provider: 'openrouter',
+    name: 'GPT-5 Image',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    cost: { input: 10, output: 10, cacheRead: 1.25, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-5-image-mini',
+    provider: 'openrouter',
+    name: 'GPT-5 Image Mini',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    cost: { input: 2.5, output: 2, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-5-mini',
+    provider: 'openrouter',
+    name: 'GPT-5 Mini',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 2, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5-mini:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5 Mini (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.125, output: 1, cacheRead: 0.0125, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5-nano',
+    provider: 'openrouter',
+    name: 'GPT-5 Nano',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.05, output: 0.4, cacheRead: 0.005, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5-nano:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5 Nano (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.025, output: 0.2, cacheRead: 0.0025, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5-pro',
+    provider: 'openrouter',
+    name: 'GPT-5 Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 15, output: 120, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5-pro:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5 Pro (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 7.5, output: 60, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.625, output: 5, cacheRead: 0.0625, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.1',
+    provider: 'openrouter',
+    name: 'GPT-5.1',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.1-codex',
+    provider: 'openrouter',
+    name: 'GPT-5.1 Codex',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.13, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.1-codex-max',
+    provider: 'openrouter',
+    name: 'GPT-5.1 Codex Max',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.1-codex-mini',
+    provider: 'openrouter',
+    name: 'GPT-5.1 Codex mini',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 2, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.1:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5.1 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.625, output: 5, cacheRead: 0.0625, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.2',
+    provider: 'openrouter',
+    name: 'GPT-5.2',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.2-chat',
+    provider: 'openrouter',
+    name: 'GPT-5.2 Chat',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 32000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.2-codex',
+    provider: 'openrouter',
+    name: 'GPT-5.2 Codex',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.2-pro',
+    provider: 'openrouter',
+    name: 'GPT-5.2 Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 21, output: 168, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.2-pro:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5.2 Pro (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 10.5, output: 84, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.2:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5.2 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.875, output: 7, cacheRead: 0.0875, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.3-codex',
+    provider: 'openrouter',
+    name: 'GPT-5.3 Codex',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.4',
+    provider: 'openrouter',
+    name: 'GPT-5.4',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.4-image-2',
+    provider: 'openrouter',
+    name: 'GPT-5.4 Image 2',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 8, output: 15, cacheRead: 2, cacheWrite: 0 },
+    contextWindow: 272000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.4-mini',
+    provider: 'openrouter',
+    name: 'GPT-5.4 mini',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.75, output: 4.5, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.4-mini:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5.4 Mini (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.375, output: 2.25, cacheRead: 0.0375, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.4-nano',
+    provider: 'openrouter',
+    name: 'GPT-5.4 nano',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.2, output: 1.25, cacheRead: 0.02, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.4-nano:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5.4 Nano (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.1, output: 0.625, cacheRead: 0.01, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.4-pro',
+    provider: 'openrouter',
+    name: 'GPT-5.4 Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.4-pro:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5.4 Pro (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 15, output: 90, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.4:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5.4 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.25, output: 7.5, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.5',
+    provider: 'openrouter',
+    name: 'GPT-5.5',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.5-pro',
+    provider: 'openrouter',
+    name: 'GPT-5.5 Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.5-pro:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5.5 Pro (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 15, output: 90, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.5:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5.5 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.6-luna',
+    provider: 'openrouter',
+    name: 'GPT-5.6 Luna',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.6-luna-pro',
+    provider: 'openrouter',
+    name: 'GPT-5.6 Luna Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.6-luna-pro:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5.6 Luna Pro (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.1, output: 0.6, cacheRead: 0.01, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.6-luna:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5.6 Luna (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.1, output: 0.6, cacheRead: 0.01, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.6-sol',
+    provider: 'openrouter',
+    name: 'GPT-5.6 Sol',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.6-sol-pro',
+    provider: 'openrouter',
+    name: 'GPT-5.6 Sol Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.6-sol-pro:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5.6 Sol Pro (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.6-sol:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5.6 Sol (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.6-terra',
+    provider: 'openrouter',
+    name: 'GPT-5.6 Terra',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.6-terra-pro',
+    provider: 'openrouter',
+    name: 'GPT-5.6 Terra Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.6-terra-pro:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5.6 Terra Pro (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1, output: 6, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-5.6-terra:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-5.6 Terra (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1, output: 6, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-6-astra',
+    provider: 'openrouter',
+    name: 'GPT-6 Astra',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-6-astra-pro',
+    provider: 'openrouter',
+    name: 'GPT-6 Astra Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-6-astra-pro:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-6 Astra Pro (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-6-astra:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-6 Astra (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-6-luna',
+    provider: 'openrouter',
+    name: 'GPT-6 Luna',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-6-luna-pro',
+    provider: 'openrouter',
+    name: 'GPT-6 Luna Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-6-luna-pro:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-6 Luna Pro (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.05, output: 0.25, cacheRead: 0.005, cacheWrite: 0.0625 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-6-luna:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-6 Luna (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.05, output: 0.25, cacheRead: 0.005, cacheWrite: 0.0625 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-6-sol',
+    provider: 'openrouter',
+    name: 'GPT-6 Sol',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-6-sol-pro',
+    provider: 'openrouter',
+    name: 'GPT-6 Sol Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-6-sol-pro:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-6 Sol Pro (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-6-sol:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-6 Sol (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-6.1-sol',
+    provider: 'openrouter',
+    name: 'GPT-6.1 Sol',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-6.1-sol-pro',
+    provider: 'openrouter',
+    name: 'GPT-6.1 Sol Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-6.1-sol-pro:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-6.1 Sol Pro (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1, output: 5, cacheRead: 0.05, cacheWrite: 1.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-6.1-sol:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: GPT-6.1 Sol (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1, output: 5, cacheRead: 0.05, cacheWrite: 1.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-audio',
+    provider: 'openrouter',
+    name: 'GPT Audio',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'audio'],
+    reasoning: false,
+    cost: { input: 2.5, output: 10, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-audio-mini',
+    provider: 'openrouter',
+    name: 'GPT Audio Mini',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'audio'],
+    reasoning: false,
+    cost: { input: 0.6, output: 2.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-chat-latest',
+    provider: 'openrouter',
+    name: 'GPT Chat Latest',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/gpt-oss-120b',
+    provider: 'openrouter',
+    name: 'GPT OSS 120B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.037, output: 0.17, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 117964,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-oss-120b:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: gpt-oss-120b (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.0296, output: 0.136, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 117964,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-oss-20b',
+    provider: 'openrouter',
+    name: 'GPT OSS 20B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.018, output: 0.09, cacheRead: 0.009, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-oss-20b:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: gpt-oss-20b (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.024, output: 0.112, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 117964,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/gpt-oss-safeguard-20b',
+    provider: 'openrouter',
+    name: 'GPT OSS Safeguard 20B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.075, output: 0.3, cacheRead: 0.0375, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+    },
+  },
+  {
+    id: 'openai/o1',
+    provider: 'openrouter',
+    name: 'o1',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 15, output: 60, cacheRead: 7.5, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/o1-pro',
+    provider: 'openrouter',
+    name: 'o1-pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 150, output: 600, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/o3',
+    provider: 'openrouter',
+    name: 'o3',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 2, output: 8, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/o3-mini',
+    provider: 'openrouter',
+    name: 'o3-mini',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.1, output: 4.4, cacheRead: 0.55, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/o3-mini-high',
+    provider: 'openrouter',
+    name: 'o3 Mini High',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.1, output: 4.4, cacheRead: 0.55, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/o3-mini:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: o3 Mini (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'document'],
+    reasoning: true,
+    cost: { input: 0.55, output: 2.2, cacheRead: 0.275, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/o3-pro',
+    provider: 'openrouter',
+    name: 'o3-pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 20, output: 80, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/o3:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: o3 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    cost: { input: 1, output: 4, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/o4-mini',
+    provider: 'openrouter',
+    name: 'o4-mini',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.1, output: 4.4, cacheRead: 0.275, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/o4-mini-high',
+    provider: 'openrouter',
+    name: 'o4 Mini High',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.1, output: 4.4, cacheRead: 0.275, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openai/o4-mini:batch',
+    provider: 'openrouter',
+    name: 'OpenAI: o4 Mini (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    cost: { input: 0.55, output: 2.2, cacheRead: 0.1375, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openrouter/auto',
+    provider: 'openrouter',
+    name: 'Auto Router',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 2000000,
+    maxTokens: 2000000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    provider: 'openrouter',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    id: 'openrouter/auto-beta',
+    name: 'Auto Router (Beta)',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 2000000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'openrouter/bodybuilder',
+    provider: 'openrouter',
+    name: 'Body Builder (beta)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openrouter/free',
+    provider: 'openrouter',
+    name: 'Free Models Router',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 8000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'openrouter/fusion',
+    provider: 'openrouter',
+    name: 'Fusion',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'openrouter/pareto-code',
+    provider: 'openrouter',
+    name: 'Pareto Code Router',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 2000000,
+    maxTokens: 200000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'perceptron/perceptron-mk1',
+    provider: 'openrouter',
+    name: 'Perceptron Mk1',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.15, output: 1.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 8192,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'perceptron/perceptron-mk1.5',
+    provider: 'openrouter',
+    name: 'Perceptron Mk1.5',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.15, output: 1.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 36864,
+    maxTokens: 8192,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'perplexity/sonar',
+    provider: 'openrouter',
+    name: 'Sonar',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 127072,
+    maxTokens: 114364,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'perplexity/sonar-deep-research',
+    provider: 'openrouter',
+    name: 'Sonar Deep Research',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 2, output: 8, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 115200,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'perplexity/sonar-pro',
+    provider: 'openrouter',
+    name: 'Sonar Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 3, output: 15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 8000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'perplexity/sonar-pro-search',
+    provider: 'openrouter',
+    name: 'Sonar Pro Search',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 3, output: 15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 8000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'perplexity/sonar-reasoning-pro',
+    provider: 'openrouter',
+    name: 'Sonar Reasoning Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 2, output: 8, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 115200,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'poolside/laguna-s-2.1',
+    provider: 'openrouter',
+    name: 'Laguna S 2.1',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.09, output: 0.18, cacheRead: 0.009, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'poolside/laguna-s-2.1:free',
+    provider: 'openrouter',
+    name: 'Laguna S 2.1 (free)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'poolside/laguna-xs-2.1',
+    provider: 'openrouter',
+    name: 'Laguna XS 2.1',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.06, output: 0.12, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'poolside/laguna-xs-2.1:free',
+    provider: 'openrouter',
+    name: 'Laguna XS 2.1 (free)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'prism-ml/ternary-bonsai-2-27b',
+    provider: 'openrouter',
+    name: 'Ternary Bonsai 2 27B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.075, output: 0.5, cacheRead: 0.0375, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen-2.5-72b-instruct',
+    provider: 'openrouter',
+    name: 'Qwen2.5 72B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.36, output: 0.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen-2.5-7b-instruct',
+    provider: 'openrouter',
+    name: 'Qwen2.5 7B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 29491,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen-2.5-coder-32b-instruct',
+    provider: 'openrouter',
+    name: 'Qwen2.5 Coder 32B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.66, output: 1, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 29491,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen-plus',
+    provider: 'openrouter',
+    name: 'Qwen Plus',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.26, output: 0.78, cacheRead: 0.052, cacheWrite: 0.325 },
+    contextWindow: 1000000,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen-plus-2025-07-28',
+    provider: 'openrouter',
+    name: 'Qwen Plus 0728',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.26, output: 0.78, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen2.5-vl-72b-instruct',
+    provider: 'openrouter',
+    name: 'Qwen2.5 VL 72B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.8, output: 1, cacheRead: 0.4, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 115200,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-14b',
+    provider: 'openrouter',
+    name: 'Qwen3 14B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.12, output: 0.24, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-235b-a22b',
+    provider: 'openrouter',
+    name: 'Qwen3 235B-A22B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.455, output: 1.82, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 8192,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-235b-a22b-2507',
+    provider: 'openrouter',
+    name: 'Qwen3 235B A22B Instruct 2507',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.0875, output: 0.35, cacheRead: 0.0175, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-235b-a22b-thinking-2507',
+    provider: 'openrouter',
+    name: 'Qwen3 235B A22B Thinking 2507',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.23, output: 2.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 117964,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-30b-a3b',
+    provider: 'openrouter',
+    name: 'Qwen3 30B A3B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.13, output: 0.52, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 8192,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-30b-a3b-instruct-2507',
+    provider: 'openrouter',
+    name: 'Qwen3 30B A3B Instruct 2507',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.04815, output: 0.19305, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-30b-a3b-thinking-2507',
+    provider: 'openrouter',
+    name: 'Qwen3 30B A3B Thinking 2507',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.2, output: 2.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 81920,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-32b',
+    provider: 'openrouter',
+    name: 'Qwen3 32B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.08, output: 0.28, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-8b',
+    provider: 'openrouter',
+    name: 'Qwen3 8B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.117, output: 0.455, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 8192,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-coder',
+    provider: 'openrouter',
+    name: 'Qwen3 Coder 480B A35B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.3, output: 1, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-coder-30b-a3b-instruct',
+    provider: 'openrouter',
+    name: 'Qwen3-Coder 30B-A3B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.07, output: 0.28, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-coder-flash',
+    provider: 'openrouter',
+    name: 'Qwen3 Coder Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: {
+      input: 0.195,
+      output: 0.975,
+      cacheRead: 0.039,
+      cacheWrite: 0.24375,
+    },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-coder-next',
+    provider: 'openrouter',
+    name: 'Qwen3 Coder Next',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.12, output: 0.8, cacheRead: 0.07, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-coder-plus',
+    provider: 'openrouter',
+    name: 'Qwen3 Coder Plus',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.65, output: 3.25, cacheRead: 0.13, cacheWrite: 0.8125 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-max',
+    provider: 'openrouter',
+    name: 'Qwen3 Max',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.78, output: 3.9, cacheRead: 0.156, cacheWrite: 0.975 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-max-thinking',
+    provider: 'openrouter',
+    name: 'Qwen3 Max Thinking',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.78, output: 3.9, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-next-80b-a3b-instruct',
+    provider: 'openrouter',
+    name: 'Qwen3-Next 80B-A3B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.1, output: 1.1, cacheRead: 0.07, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-next-80b-a3b-thinking',
+    provider: 'openrouter',
+    name: 'Qwen3-Next 80B-A3B (Thinking)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.15, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-vl-235b-a22b-instruct',
+    provider: 'openrouter',
+    name: 'Qwen3 VL 235B A22B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.21, output: 1.9, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-vl-235b-a22b-thinking',
+    provider: 'openrouter',
+    name: 'Qwen3 VL 235B A22B Thinking',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.4, output: 4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-vl-30b-a3b-instruct',
+    provider: 'openrouter',
+    name: 'Qwen3 VL 30B A3B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-vl-30b-a3b-thinking',
+    provider: 'openrouter',
+    name: 'Qwen3 VL 30B A3B Thinking',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.2, output: 2.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-vl-32b-instruct',
+    provider: 'openrouter',
+    name: 'Qwen3 VL 32B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.104, output: 0.416, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-vl-8b-instruct',
+    provider: 'openrouter',
+    name: 'Qwen3 VL 8B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.117, output: 0.455, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3-vl-8b-thinking',
+    provider: 'openrouter',
+    name: 'Qwen3 VL 8B Thinking',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.18, output: 2.1, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.5-122b-a10b',
+    provider: 'openrouter',
+    name: 'Qwen3.5 122B-A10B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.26, output: 2.08, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.5-27b',
+    provider: 'openrouter',
+    name: 'Qwen3.5 27B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.195, output: 1.56, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.5-35b-a3b',
+    provider: 'openrouter',
+    name: 'Qwen3.5 35B-A3B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.1625, output: 1.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.5-397b-a17b',
+    provider: 'openrouter',
+    name: 'Qwen3.5 397B-A17B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.55, output: 3.5, cacheRead: 0.225, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.5-9b',
+    provider: 'openrouter',
+    name: 'Qwen3.5 9B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.1, output: 0.15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.5-flash-02-23',
+    provider: 'openrouter',
+    name: 'Qwen3.5-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.065, output: 0.26, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.5-plus-02-15',
+    provider: 'openrouter',
+    name: 'Qwen3.5 Plus 2026-02-15',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.26, output: 1.56, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.5-plus-20260420',
+    provider: 'openrouter',
+    name: 'Qwen3.5 Plus 2026-04-20',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.3, output: 1.8, cacheRead: 0, cacheWrite: 0.375 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.6-27b',
+    provider: 'openrouter',
+    name: 'Qwen3.6 27B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.32, output: 3.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 81920,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.6-35b-a3b',
+    provider: 'openrouter',
+    name: 'Qwen3.6 35B-A3B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.15, output: 1, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.6-flash',
+    provider: 'openrouter',
+    name: 'Qwen3.6 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.1875, output: 1.125, cacheRead: 0, cacheWrite: 0.234375 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.6-max-preview',
+    provider: 'openrouter',
+    name: 'Qwen3.6 Max Preview',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.027, output: 6.162, cacheRead: 0, cacheWrite: 1.28375 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.6-plus',
+    provider: 'openrouter',
+    name: 'Qwen3.6 Plus',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.325, output: 1.95, cacheRead: 0, cacheWrite: 0.40625 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.7-flash',
+    provider: 'openrouter',
+    name: 'Qwen3.7 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.03, output: 0.13, cacheRead: 0.006, cacheWrite: 0.038 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.7-max',
+    provider: 'openrouter',
+    name: 'Qwen3.7 Max',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: {
+      input: 1.475,
+      output: 4.425,
+      cacheRead: 0.295,
+      cacheWrite: 1.84375,
+    },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.7-plus',
+    provider: 'openrouter',
+    name: 'Qwen3.7 Plus',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.32, output: 1.28, cacheRead: 0.064, cacheWrite: 0.4 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.8-2.4t-a95b',
+    provider: 'openrouter',
+    name: 'Qwen3.8 2.4T A95B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.8-27b',
+    provider: 'openrouter',
+    name: 'Qwen3.8 27B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.0249, output: 4.35, cacheRead: 0.0199, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.8-27b:free',
+    provider: 'openrouter',
+    name: 'Qwen3.8 27B (free)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.8-flash',
+    provider: 'openrouter',
+    name: 'Qwen3.8 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.15, output: 0.47, cacheRead: 0.016, cacheWrite: 0.2 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.8-max-0902',
+    provider: 'openrouter',
+    name: 'Qwen3.8 Max 0902',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.8-max-prime',
+    provider: 'openrouter',
+    name: 'Qwen 3.8 Max Prime',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 4, output: 12, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'qwen/qwen3.8-omni-flash',
+    provider: 'openrouter',
+    name: 'Qwen3.8 Omni Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.15, output: 0.47, cacheRead: 0.016, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'rekaai/reka-edge',
+    provider: 'openrouter',
+    name: 'Reka Edge',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.1, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 16384,
+    maxTokens: 14745,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'rekaai/reka-flash-3',
+    provider: 'openrouter',
+    name: 'Reka Flash 3',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.1, output: 0.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 65536,
+    maxTokens: 58982,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'relace/relace-apply-3',
+    provider: 'openrouter',
+    name: 'Relace Apply 3',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.85, output: 1.25, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'relace/relace-search',
+    provider: 'openrouter',
+    name: 'Relace Search',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 1, output: 3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'sakana/fugu-max',
+    provider: 'openrouter',
+    name: 'Fugu Max',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'sakana/fugu-ultra',
+    provider: 'openrouter',
+    name: 'Fugu Ultra',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'sakana/fugu-ultra-v2',
+    provider: 'openrouter',
+    name: 'Fugu Ultra v2',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'sakana/sakana-namazu',
+    provider: 'openrouter',
+    name: 'Sakana Namazu',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.95, output: 4, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'sao10k/l3-lunaris-8b',
+    provider: 'openrouter',
+    name: 'Llama 3 8B Lunaris',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.04, output: 0.05, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 7372,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'sao10k/l3.1-euryale-70b',
+    provider: 'openrouter',
+    name: 'Llama 3.1 Euryale 70B v2.2',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.85, output: 0.85, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'sao10k/l3.3-euryale-70b',
+    provider: 'openrouter',
+    name: 'Llama 3.3 Euryale 70B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.65, output: 0.75, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'stealth/space-bunny-alpha',
+    provider: 'openrouter',
+    name: 'Space Bunny Alpha',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 524288,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'stepfun/step-3.5-flash',
+    provider: 'openrouter',
+    name: 'Step 3.5 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.1, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'stepfun/step-3.7-flash',
+    provider: 'openrouter',
+    name: 'Step 3.7 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.2, output: 1.15, cacheRead: 0.04, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 230400,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'tencent/hunyuan-a13b-instruct',
+    provider: 'openrouter',
+    name: 'Hunyuan A13B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.14, output: 0.57, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 117964,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'tencent/hy-mt2-1.8b',
+    provider: 'openrouter',
+    name: 'Hy-MT2-1.8B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.044, output: 0.177, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 4096,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'tencent/hy-mt2-30b-a3b',
+    provider: 'openrouter',
+    name: 'Hy-MT2-30B-A3B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.074, output: 0.295, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 4096,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'tencent/hy-mt2-7b',
+    provider: 'openrouter',
+    name: 'Hy-MT2-7B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.074, output: 0.295, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 4096,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'tencent/hy3',
+    provider: 'openrouter',
+    name: 'Hy3',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.132, output: 0.528, cacheRead: 0.033, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'tencent/hy3-preview',
+    provider: 'openrouter',
+    name: 'Hy3 preview',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.18, output: 0.6, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'tencent/hy4-preview',
+    provider: 'openrouter',
+    name: 'Hy4 preview',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.834, output: 2.501, cacheRead: 0.042, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 64000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'thedrummer/cydonia-24b-v4.1',
+    provider: 'openrouter',
+    name: 'Cydonia 24B V4.1',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.3, output: 0.5, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 117964,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'thedrummer/skyfall-36b-v2',
+    provider: 'openrouter',
+    name: 'Skyfall 36B V2',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.55, output: 0.8, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 29491,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'thedrummer/unslopnemo-12b',
+    provider: 'openrouter',
+    name: 'UnslopNemo 12B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.4, output: 0.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1024000,
+    maxTokens: 819200,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'thinkingmachines/inkling',
+    provider: 'openrouter',
+    name: 'Inkling',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1, output: 4.05, cacheRead: 0.17, cacheWrite: 0 },
+    contextWindow: 524288,
+    maxTokens: 471859,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'thinkingmachines/inkling-small',
+    provider: 'openrouter',
+    name: 'Inkling Small',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.45, output: 1.2, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 524288,
+    maxTokens: 262144,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'thinkingmachines/inkling-small:free',
+    provider: 'openrouter',
+    name: 'Inkling Small (free)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 262144,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'thinkingmachines/inkling:free',
+    provider: 'openrouter',
+    name: 'Inkling (free)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 262144,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'unbiased/pareto',
+    provider: 'openrouter',
+    name: 'Pareto',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 2.5, output: 7.5, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'undi95/remm-slerp-l2-13b',
+    provider: 'openrouter',
+    name: 'ReMM SLERP 13B',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.35, output: 0.65, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 6144,
+    maxTokens: 5529,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'upstage/solar-mini4',
+    provider: 'openrouter',
+    name: 'Solar Mini 4',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.05, output: 0.2, cacheRead: 0.005, cacheWrite: 0 },
+    contextWindow: 524288,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'upstage/solar-pro-3',
+    provider: 'openrouter',
+    name: 'Solar Pro 3',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 117964,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'upstage/solar-pro4',
+    provider: 'openrouter',
+    name: 'Solar Pro 4',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.09, output: 0.36, cacheRead: 0.018, cacheWrite: 0 },
+    contextWindow: 524288,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'writer/palmyra-x5',
+    provider: 'openrouter',
+    name: 'Palmyra X5',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.6, output: 6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1040000,
+    maxTokens: 8192,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'x-ai/grok-4.20',
+    provider: 'openrouter',
+    name: 'Grok 4.20',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 2000000,
+    maxTokens: 1800000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'x-ai/grok-4.20-multi-agent',
+    provider: 'openrouter',
+    name: 'Grok 4.20 Multi-Agent',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 2000000,
+    maxTokens: 1800000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'x-ai/grok-4.3',
+    provider: 'openrouter',
+    name: 'Grok 4.3',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 900000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'x-ai/grok-4.3:batch',
+    provider: 'openrouter',
+    name: 'SpaceXAI: Grok 4.3 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1, output: 2, cacheRead: 0.16, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 900000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'x-ai/grok-4.5',
+    provider: 'openrouter',
+    name: 'Grok 4.5',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 450000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'x-ai/grok-4.6',
+    provider: 'openrouter',
+    name: 'Grok 4.6',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 450000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'x-ai/grok-4.7',
+    provider: 'openrouter',
+    name: 'Grok 4.7',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 450000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'x-ai/grok-build-0.1',
+    provider: 'openrouter',
+    name: 'Grok Build 0.1',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    cost: { input: 1, output: 2, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 230400,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'xiaomi/mimo-v2.5',
+    provider: 'openrouter',
+    name: 'MiMo-V2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'xiaomi/mimo-v2.5-pro',
+    provider: 'openrouter',
+    name: 'MiMo-V2.5-Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.0036, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'xiaomi/mimo-v2.6-flash',
+    provider: 'openrouter',
+    name: 'MiMo-V2.6-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'xiaomi/mimo-v2.6-pro',
+    provider: 'openrouter',
+    name: 'MiMo-V2.6-Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.0036, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'xiaomi/mimo-v2.6-pro-ultraspeed',
+    provider: 'openrouter',
+    name: 'MiMo-V2.6-Pro-UltraSpeed',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 4.35, output: 8.7, cacheRead: 0.036, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'z-ai/glm-4.5',
+    provider: 'openrouter',
+    name: 'GLM-4.5',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 2.2, cacheRead: 0.11, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 98304,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'z-ai/glm-4.5-air',
+    provider: 'openrouter',
+    name: 'GLM-4.5-Air',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.13, output: 0.85, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 98304,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'z-ai/glm-4.5v',
+    provider: 'openrouter',
+    name: 'GLM-4.5V',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 1.8, cacheRead: 0.11, cacheWrite: 0 },
+    contextWindow: 65536,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'z-ai/glm-4.6',
+    provider: 'openrouter',
+    name: 'GLM-4.6',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.43, output: 1.75, cacheRead: 0.08, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 16384,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'z-ai/glm-4.6v',
+    provider: 'openrouter',
+    name: 'GLM-4.6V',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.3, output: 0.9, cacheRead: 0.055, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'z-ai/glm-4.7',
+    provider: 'openrouter',
+    name: 'GLM-4.7',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 2.2, cacheRead: 0.11, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'z-ai/glm-4.7-flash',
+    provider: 'openrouter',
+    name: 'GLM-4.7-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.0605, output: 0.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 117964,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'z-ai/glm-5',
+    provider: 'openrouter',
+    name: 'GLM-5',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 1.92, cacheRead: 0.12, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 128000,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'z-ai/glm-5-turbo',
+    provider: 'openrouter',
+    name: 'GLM-5-Turbo',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.2, output: 4, cacheRead: 0.24, cacheWrite: 0 },
+    contextWindow: 202752,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'z-ai/glm-5.1',
+    provider: 'openrouter',
+    name: 'GLM-5.1',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'z-ai/glm-5.2',
+    provider: 'openrouter',
+    name: 'GLM-5.2',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.41, output: 3.99, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 943718,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'z-ai/glm-5.3',
+    provider: 'openrouter',
+    name: 'GLM-5.3',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 943717,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'z-ai/glm-5.3-flash',
+    provider: 'openrouter',
+    name: 'GLM-5.3-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 943717,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'z-ai/glm-5.3-flash:batch',
+    provider: 'openrouter',
+    name: 'Z.ai: GLM 5.3 Flash (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.06, output: 0.2, cacheRead: 0.012, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'z-ai/glm-5.3-flashx',
+    provider: 'openrouter',
+    name: 'GLM 5.3 FlashX',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.37, output: 1.25, cacheRead: 0.09, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'z-ai/glm-5.3-prime',
+    provider: 'openrouter',
+    name: 'GLM 5.3 Prime',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 2.8, output: 8.8, cacheRead: 0.56, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'z-ai/glm-5.3:batch',
+    provider: 'openrouter',
+    name: 'Z.ai: GLM 5.3 (batch)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.45, output: 2, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+  {
+    id: 'z-ai/glm-5v-turbo',
+    provider: 'openrouter',
+    name: 'GLM-5V-Turbo',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.2, output: 4, cacheRead: 0.24, cacheWrite: 0 },
+    contextWindow: 202752,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/qwen-token-plan-cn.ts b/packages/ai-models/src/providers/qwen-token-plan-cn.ts
new file mode 100644
index 0000000000..26b9ca002e
--- /dev/null
+++ b/packages/ai-models/src/providers/qwen-token-plan-cn.ts
@@ -0,0 +1,592 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Qwen Token Plan (China). */
+export const provider: ProviderRecord = {
+  id: 'qwen-token-plan-cn',
+  name: 'Qwen Token Plan (China)',
+  baseUrl: 'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+  apis: ['openai-completions'],
+  env: [['QWEN_TOKEN_PLAN_CN_API_KEY']],
+}
+
+/** Every Qwen Token Plan (China) model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'deepseek-v3.2',
+    provider: 'qwen-token-plan-cn',
+    name: 'DeepSeek-V3.2',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.26, output: 0.38, cacheRead: 0.13, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 64000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+    borrowedFrom: 'deepinfra/deepseek-ai/DeepSeek-V3.2',
+  },
+  {
+    id: 'deepseek-v4-flash',
+    provider: 'qwen-token-plan-cn',
+    name: 'DeepSeek V4 Flash',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'deepseek-v4-flash-0731',
+    provider: 'qwen-token-plan-cn',
+    name: 'DeepSeek V4 Flash 0731',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.06, output: 0.18, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      supportsReasoningEffort: false,
+    },
+    borrowedFrom: 'deepinfra/deepseek-ai/DeepSeek-V4-Flash-0731',
+  },
+  {
+    id: 'deepseek-v4-pro',
+    provider: 'qwen-token-plan-cn',
+    name: 'DeepSeek V4 Pro',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.003625, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'deepseek-v4-pro-0813',
+    provider: 'qwen-token-plan-cn',
+    name: 'DeepSeek V4 Pro 0813',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.3, output: 2.6, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      supportsReasoningEffort: true,
+    },
+    borrowedFrom: 'deepinfra/deepseek-ai/DeepSeek-V4-Pro-0813',
+  },
+  {
+    id: 'deepseek-v4.1-flash',
+    provider: 'qwen-token-plan-cn',
+    name: 'DeepSeek V4.1 Flash',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: {
+      input: 0.29754,
+      output: 1.19015,
+      cacheRead: 0.01488,
+      cacheWrite: 0,
+    },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'glm-5',
+    provider: 'qwen-token-plan-cn',
+    name: 'GLM-5',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.573, output: 2.58, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 202752,
+    maxTokens: 16384,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-5.1',
+    provider: 'qwen-token-plan-cn',
+    name: 'GLM-5.1',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.825, output: 3.301, cacheRead: 0.17, cacheWrite: 0 },
+    contextWindow: 202752,
+    maxTokens: 128000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-5.2',
+    provider: 'qwen-token-plan-cn',
+    name: 'GLM-5.2',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 1.1, output: 3.851, cacheRead: 0.275, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-5.3',
+    provider: 'qwen-token-plan-cn',
+    name: 'GLM-5.3',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.1, output: 3.851, cacheRead: 0.275, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'kimi-k2.5',
+    provider: 'qwen-token-plan-cn',
+    name: 'Moonshot Kimi K2.5',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.574, output: 2.411, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'kimi-k2.6',
+    provider: 'qwen-token-plan-cn',
+    name: 'Moonshot Kimi K2.6',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.929, output: 3.858, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 16384,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'kimi-k2.7-code',
+    provider: 'qwen-token-plan-cn',
+    name: 'Kimi K2.7 Code',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    cost: { input: 0.95, output: 4, cacheRead: 0.19, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+      supportsReasoningEffort: false,
+    },
+    borrowedFrom: 'moonshotai/kimi-k2.7-code',
+  },
+  {
+    id: 'MiniMax-M2.5',
+    provider: 'qwen-token-plan-cn',
+    name: 'MiniMax-M2.5',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'qwen3.6-flash',
+    provider: 'qwen-token-plan-cn',
+    name: 'Qwen3.6 Flash',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.1875, output: 1.125, cacheRead: 0, cacheWrite: 0.234375 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'qwen3.6-plus',
+    provider: 'qwen-token-plan-cn',
+    name: 'Qwen3.6 Plus',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0.625 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'qwen3.7-max',
+    provider: 'qwen-token-plan-cn',
+    name: 'Qwen3.7 Max',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 2.5, output: 7.5, cacheRead: 0.5, cacheWrite: 3.125 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'qwen3.7-plus',
+    provider: 'qwen-token-plan-cn',
+    name: 'Qwen3.7 Plus',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0.625 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'qwen3.8-flash',
+    provider: 'qwen-token-plan-cn',
+    name: 'Qwen3.8 Flash',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: {
+      input: 0.11875,
+      output: 0.40073,
+      cacheRead: 0.01187,
+      cacheWrite: 0.14844,
+    },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'qwen3.8-max',
+    provider: 'qwen-token-plan-cn',
+    name: 'Qwen3.8 Max',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: {
+      input: 1.77744,
+      output: 5.33231,
+      cacheRead: 0.22218,
+      cacheWrite: 2.22179,
+    },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/qwen-token-plan-individual.ts b/packages/ai-models/src/providers/qwen-token-plan-individual.ts
new file mode 100644
index 0000000000..0a2be8dcb4
--- /dev/null
+++ b/packages/ai-models/src/providers/qwen-token-plan-individual.ts
@@ -0,0 +1,284 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Qwen Token Plan (Individual). */
+export const provider: ProviderRecord = {
+  id: 'qwen-token-plan-individual',
+  name: 'Qwen Token Plan (Individual)',
+  baseUrl:
+    'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+  apis: ['openai-completions'],
+  env: [['QWEN_TOKEN_PLAN_API_KEY']],
+}
+
+/** Every Qwen Token Plan (Individual) model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'deepseek-v4-flash-0731',
+    provider: 'qwen-token-plan-individual',
+    name: 'DeepSeek V4 Flash 0731',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.2, output: 0.4, cacheRead: 0.04, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'deepseek-v4-pro',
+    provider: 'qwen-token-plan-individual',
+    name: 'DeepSeek V4 Pro',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.003625, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 393216,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+    borrowedFrom: 'deepseek/deepseek-v4-pro',
+  },
+  {
+    id: 'deepseek-v4-pro-0813',
+    provider: 'qwen-token-plan-individual',
+    name: 'DeepSeek V4 Pro 0813',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.3, output: 2.6, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      supportsReasoningEffort: true,
+    },
+    borrowedFrom: 'deepinfra/deepseek-ai/DeepSeek-V4-Pro-0813',
+  },
+  {
+    id: 'glm-5.2',
+    provider: 'qwen-token-plan-individual',
+    name: 'GLM-5.2',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.28, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'qwen3.6-flash',
+    provider: 'qwen-token-plan-individual',
+    name: 'Qwen3.6 Flash',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.1875, output: 1.125, cacheRead: 0, cacheWrite: 0.234375 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'qwen3.7-max',
+    provider: 'qwen-token-plan-individual',
+    name: 'Qwen3.7 Max',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 2.5, output: 7.5, cacheRead: 0.5, cacheWrite: 3.125 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'qwen3.7-plus',
+    provider: 'qwen-token-plan-individual',
+    name: 'Qwen3.7 Plus',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.4, output: 1.6, cacheRead: 0.04, cacheWrite: 0.5 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'qwen3.8-flash',
+    provider: 'qwen-token-plan-individual',
+    name: 'Qwen3.8 Flash',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 0.15, output: 0.47, cacheRead: 0.016, cacheWrite: 0.2 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'qwen3.8-max',
+    provider: 'qwen-token-plan-individual',
+    name: 'Qwen3.8 Max',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/qwen-token-plan.ts b/packages/ai-models/src/providers/qwen-token-plan.ts
new file mode 100644
index 0000000000..a478fbbdc0
--- /dev/null
+++ b/packages/ai-models/src/providers/qwen-token-plan.ts
@@ -0,0 +1,593 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Qwen Token Plan. */
+export const provider: ProviderRecord = {
+  id: 'qwen-token-plan',
+  name: 'Qwen Token Plan',
+  baseUrl:
+    'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+  apis: ['openai-completions'],
+  env: [['QWEN_TOKEN_PLAN_API_KEY']],
+}
+
+/** Every Qwen Token Plan model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'deepseek-v3.2',
+    provider: 'qwen-token-plan',
+    name: 'DeepSeek-V3.2',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.26, output: 0.38, cacheRead: 0.13, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 64000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+    borrowedFrom: 'deepinfra/deepseek-ai/DeepSeek-V3.2',
+  },
+  {
+    id: 'deepseek-v4-flash',
+    provider: 'qwen-token-plan',
+    name: 'DeepSeek V4 Flash',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.003, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 393216,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+    borrowedFrom: 'deepseek/deepseek-v4-flash',
+  },
+  {
+    id: 'deepseek-v4-flash-0731',
+    provider: 'qwen-token-plan',
+    name: 'DeepSeek V4 Flash 0731',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.2, output: 0.4, cacheRead: 0.04, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'deepseek-v4-pro',
+    provider: 'qwen-token-plan',
+    name: 'DeepSeek V4 Pro',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.003625, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 393216,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+    borrowedFrom: 'deepseek/deepseek-v4-pro',
+  },
+  {
+    id: 'deepseek-v4-pro-0813',
+    provider: 'qwen-token-plan',
+    name: 'DeepSeek V4 Pro 0813',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.3, output: 2.6, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      supportsReasoningEffort: true,
+    },
+    borrowedFrom: 'deepinfra/deepseek-ai/DeepSeek-V4-Pro-0813',
+  },
+  {
+    id: 'deepseek-v4.1-flash',
+    provider: 'qwen-token-plan',
+    name: 'DeepSeek V4.1 Flash',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.2, output: 0.6, cacheRead: 0.006, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      supportsReasoningEffort: true,
+    },
+    borrowedFrom: 'deepinfra/deepseek-ai/DeepSeek-V4.1-Flash',
+  },
+  {
+    id: 'glm-5',
+    provider: 'qwen-token-plan',
+    name: 'GLM-5',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1, output: 3.2, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+    borrowedFrom: 'zai/glm-5',
+  },
+  {
+    id: 'glm-5.1',
+    provider: 'qwen-token-plan',
+    name: 'GLM-5.1',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+    borrowedFrom: 'zai/glm-5.1',
+  },
+  {
+    id: 'glm-5.2',
+    provider: 'qwen-token-plan',
+    name: 'GLM-5.2',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.28, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'glm-5.3',
+    provider: 'qwen-token-plan',
+    name: 'GLM-5.3',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+    borrowedFrom: 'zai/glm-5.3',
+  },
+  {
+    id: 'kimi-k2.5',
+    provider: 'qwen-token-plan',
+    name: 'Kimi K2.5',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.45, output: 2.25, cacheRead: 0.07, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+    borrowedFrom: 'deepinfra/moonshotai/Kimi-K2.5',
+  },
+  {
+    id: 'kimi-k2.6',
+    provider: 'qwen-token-plan',
+    name: 'Kimi K2.6',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+    borrowedFrom: 'moonshotai/kimi-k2.6',
+  },
+  {
+    id: 'kimi-k2.7-code',
+    provider: 'qwen-token-plan',
+    name: 'Kimi K2.7 Code',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    cost: { input: 0.95, output: 4, cacheRead: 0.19, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+      supportsReasoningEffort: false,
+    },
+    borrowedFrom: 'moonshotai/kimi-k2.7-code',
+  },
+  {
+    id: 'MiniMax-M2.5',
+    provider: 'qwen-token-plan',
+    name: 'MiniMax-M2.5',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      supportsReasoningEffort: false,
+    },
+    borrowedFrom: 'minimax/MiniMax-M2.5',
+  },
+  {
+    id: 'qwen3.6-flash',
+    provider: 'qwen-token-plan',
+    name: 'Qwen3.6 Flash',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.1875, output: 1.125, cacheRead: 0, cacheWrite: 0.234375 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'qwen3.6-plus',
+    provider: 'qwen-token-plan',
+    name: 'Qwen3.6 Plus',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0.625 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'qwen3.7-max',
+    provider: 'qwen-token-plan',
+    name: 'Qwen3.7 Max',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 2.5, output: 7.5, cacheRead: 0.5, cacheWrite: 3.125 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'qwen3.7-plus',
+    provider: 'qwen-token-plan',
+    name: 'Qwen3.7 Plus',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.4, output: 1.6, cacheRead: 0.04, cacheWrite: 0.5 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'qwen3.8-flash',
+    provider: 'qwen-token-plan',
+    name: 'Qwen3.8 Flash',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 0.15, output: 0.47, cacheRead: 0.016, cacheWrite: 0.2 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'qwen3.8-max',
+    provider: 'qwen-token-plan',
+    name: 'Qwen3.8 Max',
+    api: 'openai-completions',
+    baseUrl:
+      'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsStrictMode: true,
+      thinkingFormat: 'qwen',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/together.ts b/packages/ai-models/src/providers/together.ts
new file mode 100644
index 0000000000..100448865c
--- /dev/null
+++ b/packages/ai-models/src/providers/together.ts
@@ -0,0 +1,990 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Together AI. */
+export const provider: ProviderRecord = {
+  id: 'together',
+  name: 'Together AI',
+  baseUrl: 'https://api.together.ai/v1',
+  apis: ['openai-completions'],
+  env: [['TOGETHER_API_KEY']],
+}
+
+/** Every Together AI model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'deepcogito/cogito-v2-1-671b',
+    provider: 'together',
+    name: 'Cogito v2.1 671B',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.25, output: 1.25, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 163840,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-R1',
+    provider: 'together',
+    name: 'DeepSeek-R1',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 3, output: 7, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 163839,
+    maxTokens: 163839,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V3',
+    provider: 'together',
+    name: 'DeepSeek-V3',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 1.25, output: 1.25, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V3-1',
+    provider: 'together',
+    name: 'DeepSeek V3.1',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 1.7, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V4-Flash-0731',
+    provider: 'together',
+    name: 'DeepSeek V4 Flash 0731',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V4-Pro',
+    provider: 'together',
+    name: 'DeepSeek V4 Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.74, output: 3.48, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 512000,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V4-Pro-0813',
+    provider: 'together',
+    name: 'DeepSeek V4 Pro 0813',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.32, output: 3.96, cacheRead: 0.13, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'deepseek-ai/DeepSeek-V4.1-Flash',
+    provider: 'together',
+    name: 'DeepSeek V4.1 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.006, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 384000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'essentialai/Rnj-1-Instruct',
+    provider: 'together',
+    name: 'Rnj-1 Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0.15, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'google/gemma-3n-E4B-it',
+    provider: 'together',
+    name: 'Gemma 3N E4B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.06, output: 0.12, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'google/gemma-4-31B-it',
+    provider: 'together',
+    name: 'Gemma 4 31B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.39, output: 0.97, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'LiquidAI/LFM2-24B-A2B',
+    provider: 'together',
+    name: 'LFM2-24B-A2B',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.03, output: 0.12, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'meta-llama/Llama-3.3-70B-Instruct-Turbo',
+    provider: 'together',
+    name: 'Llama 3.3 70B',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 1.04, output: 1.04, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'meta-llama/Meta-Llama-3-8B-Instruct-Lite',
+    provider: 'together',
+    name: 'Meta Llama 3 8B Instruct Lite',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.14, output: 0.14, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 8192,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'MiniMaxAI/MiniMax-M2.5',
+    provider: 'together',
+    name: 'MiniMax-M2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'MiniMaxAI/MiniMax-M2.7',
+    provider: 'together',
+    name: 'MiniMax-M2.7',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 196608,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'MiniMaxAI/MiniMax-M3',
+    provider: 'together',
+    name: 'MiniMax-M3',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 524288,
+    maxTokens: 250000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'moonshotai/Kimi-K2.6',
+    provider: 'together',
+    name: 'Kimi K2.6',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+    borrowedFrom: 'moonshotai/kimi-k2.6',
+  },
+  {
+    id: 'moonshotai/Kimi-K2.7-Code',
+    provider: 'together',
+    name: 'Kimi K2.7 Code',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    cost: { input: 0.95, output: 4, cacheRead: 0.19, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+    },
+    borrowedFrom: 'moonshotai/kimi-k2.7-code',
+  },
+  {
+    id: 'moonshotai/Kimi-K3',
+    provider: 'together',
+    name: 'Kimi K3',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsTemperature: false,
+    },
+  },
+  {
+    id: 'nvidia/nemotron-3-ultra-550b-a55b',
+    provider: 'together',
+    name: 'Nemotron 3 Ultra 550B A55B',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 3.6, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 512300,
+    maxTokens: 512300,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'openai/gpt-oss-120b',
+    provider: 'together',
+    name: 'GPT OSS 120B',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'openai/gpt-oss-20b',
+    provider: 'together',
+    name: 'GPT OSS 20B',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.05, output: 0.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'pearl-ai/gemma-4-31b-it',
+    provider: 'together',
+    name: 'Pearl AI Gemma 4 31B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.28, output: 0.86, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 32000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'Qwen/Qwen2.5-7B-Instruct-Turbo',
+    provider: 'together',
+    name: 'Qwen 2.5 7B Instruct Turbo',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.3, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'Qwen/Qwen3-235B-A22B-Instruct-2507-tput',
+    provider: 'together',
+    name: 'Qwen3 235B A22B Instruct 2507 FP8',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.2, output: 0.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8',
+    provider: 'together',
+    name: 'Qwen3 Coder 480B A35B Instruct',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 2, output: 2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'Qwen/Qwen3-Coder-Next-FP8',
+    provider: 'together',
+    name: 'Qwen3 Coder Next FP8',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.5, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'Qwen/Qwen3.5-397B-A17B',
+    provider: 'together',
+    name: 'Qwen3.5 397B A17B',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 3.6, cacheRead: 0.35, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 130000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'Qwen/Qwen3.5-9B',
+    provider: 'together',
+    name: 'Qwen3.5 9B',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.17, output: 0.25, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'Qwen/Qwen3.6-Plus',
+    provider: 'together',
+    name: 'Qwen3.6 Plus',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.5, output: 3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 500000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'Qwen/Qwen3.7-Max',
+    provider: 'together',
+    name: 'Qwen3.7 Max',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 1.25, output: 3.75, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 500000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'thinkingmachines/Inkling',
+    provider: 'together',
+    name: 'Inkling',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text', 'image', 'audio'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1, output: 4.05, cacheRead: 0.17, cacheWrite: 0 },
+    contextWindow: 524288,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'zai-org/GLM-5',
+    provider: 'together',
+    name: 'GLM-5',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1, output: 3.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 202752,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'zai-org/GLM-5.1',
+    provider: 'together',
+    name: 'GLM-5.1',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 202752,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+    },
+  },
+  {
+    id: 'zai-org/GLM-5.2',
+    provider: 'together',
+    name: 'GLM-5.2',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1048575,
+    maxTokens: 164000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'zai-org/GLM-5.3',
+    provider: 'together',
+    name: 'GLM-5.3',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 262144,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+  {
+    id: 'zai-org/GLM-5.3-Flash',
+    provider: 'together',
+    name: 'GLM-5.3-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://api.together.ai/v1',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1048575,
+    maxTokens: 400000,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      maxTokensField: 'max_tokens',
+      supportsLongCacheRetention: false,
+      supportsStrictMode: false,
+      thinkingFormat: 'together',
+      requiresReasoningContentOnAssistantMessages: true,
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/vercel-ai-gateway.ts b/packages/ai-models/src/providers/vercel-ai-gateway.ts
new file mode 100644
index 0000000000..bd294db333
--- /dev/null
+++ b/packages/ai-models/src/providers/vercel-ai-gateway.ts
@@ -0,0 +1,6055 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Vercel AI Gateway. */
+export const provider: ProviderRecord = {
+  id: 'vercel-ai-gateway',
+  name: 'Vercel AI Gateway',
+  baseUrl: 'https://ai-gateway.vercel.sh',
+  apis: ['anthropic-messages'],
+  env: [['AI_GATEWAY_API_KEY']],
+}
+
+/** Every Vercel AI Gateway model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'alibaba/qwen-3-14b',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3-14B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.12, output: 0.24, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 40960,
+    maxTokens: 16384,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen-3-235b',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3 235B A22B Instruct 2507',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.22, output: 0.88, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 16384,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'alibaba/qwen-3-30b',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3-30B-A3B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.12, output: 0.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 40960,
+    maxTokens: 16384,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen-3-32b',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen 3.32B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.16, output: 0.64, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen-3.6-max-preview',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen 3.6 Max Preview',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 1.3, output: 7.8, cacheRead: 0.13, cacheWrite: 1.625 },
+    contextWindow: 240000,
+    maxTokens: 64000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3-235b-a22b-thinking',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3 235B A22B Thinking 2507',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 0.4, output: 4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3-coder',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3 Coder 480B A35B Instruct',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 1.5, output: 7.5, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3-coder-30b-a3b',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen 3 Coder 30B A3B Instruct',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.15, output: 0.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 8192,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3-coder-next',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3 Coder Next',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0.5, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 256000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3-coder-plus',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3 Coder Plus',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 1, output: 5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 65536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3-embedding-0.6b',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3 Embedding 0.6B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3-embedding-4b',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3 Embedding 4B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3-embedding-8b',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3 Embedding 8B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3-max',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3 Max',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 1.2, output: 6, cacheRead: 0.24, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3-max-preview',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3 Max Preview',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 1.2, output: 6, cacheRead: 0.24, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3-max-thinking',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen 3 Max Thinking',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 1.2, output: 6, cacheRead: 0.24, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 65536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3-next-80b-a3b-instruct',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3 Next 80B A3B Instruct',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.15, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262114,
+    maxTokens: 262114,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3-next-80b-a3b-thinking',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3 Next 80B A3B Thinking',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 0.15, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3-vl-235b-a22b-instruct',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3 VL 235B A22B Instruct',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.4, output: 1.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 129024,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3-vl-instruct',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3 VL Instruct',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.4, output: 1.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 129024,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3-vl-thinking',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3 VL Thinking',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 0.4, output: 4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3.5-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen 3.5 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.1, output: 0.4, cacheRead: 0.01, cacheWrite: 0.125 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3.5-plus',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen 3.5 Plus',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.4, output: 2.4, cacheRead: 0.04, cacheWrite: 0.5 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3.6-27b',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen 3.6 27B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.6, output: 3.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 65536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3.6-plus',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen 3.6 Plus',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0.625 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3.7-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen 3.7 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.03, output: 0.13, cacheRead: 0.006, cacheWrite: 0.038 },
+    contextWindow: 991000,
+    maxTokens: 64000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3.7-max',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen 3.7 Max',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 2.5, output: 7.5, cacheRead: 0.5, cacheWrite: 3.125 },
+    contextWindow: 991000,
+    maxTokens: 64000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3.7-plus',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen 3.7 Plus',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.4, output: 1.6, cacheRead: 0.08, cacheWrite: 0.5 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3.8-2.4t-a95b',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3.8 2.4T A95B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'alibaba/qwen3.8-27b',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3.8 27B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.5, output: 3, cacheRead: 0.1, cacheWrite: 0.625 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'alibaba/qwen3.8-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen 3.8 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 0.15, output: 0.47, cacheRead: 0.016, cacheWrite: 0.2 },
+    contextWindow: 991000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3.8-max',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen 3.8 Max',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3.8-max-0902',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen3.8 Max 0902',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 2.5 },
+    contextWindow: 991000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3.8-max-prime',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen 3.8 Max Prime',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 4, output: 12, cacheRead: 0.5, cacheWrite: 5 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'alibaba/qwen3.8-omni-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'Qwen 3.8 Omni Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.15, output: 0.47, cacheRead: 0.016, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'amazon/nova-2-lite',
+    provider: 'vercel-ai-gateway',
+    name: 'Nova 2 Lite',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.3, output: 2.5, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 65535,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'amazon/nova-lite',
+    provider: 'vercel-ai-gateway',
+    name: 'Nova Lite',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: false,
+    cost: { input: 0.06, output: 0.24, cacheRead: 0.015, cacheWrite: 0.06 },
+    contextWindow: 300000,
+    maxTokens: 10000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'amazon/nova-micro',
+    provider: 'vercel-ai-gateway',
+    name: 'Nova Micro',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.035, output: 0.14, cacheRead: 0.00875, cacheWrite: 0.035 },
+    contextWindow: 128000,
+    maxTokens: 10000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'amazon/nova-pro',
+    provider: 'vercel-ai-gateway',
+    name: 'Nova Pro',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: false,
+    cost: { input: 0.8, output: 3.2, cacheRead: 0.2, cacheWrite: 0.8 },
+    contextWindow: 300000,
+    maxTokens: 10000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'amazon/titan-embed-text-v2',
+    provider: 'vercel-ai-gateway',
+    name: 'Titan Text Embeddings V2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'anthropic/claude-3-haiku',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Haiku 3',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.25, output: 1.25, cacheRead: 0.03, cacheWrite: 0.3 },
+    contextWindow: 200000,
+    maxTokens: 4096,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'anthropic/claude-fable-5',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Fable 5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, supportsTemperature: false },
+  },
+  {
+    id: 'anthropic/claude-fable-5.1',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Fable 5.1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 10, output: 50, cacheRead: 0.25, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, supportsTemperature: false },
+  },
+  {
+    id: 'anthropic/claude-haiku-4.5',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Haiku 4.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'anthropic/claude-opus-4',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Opus 4',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+    contextWindow: 200000,
+    maxTokens: 32000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'anthropic/claude-opus-4.5',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Opus 4.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 200000,
+    maxTokens: 64000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'anthropic/claude-opus-4.6',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Opus 4.6',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'anthropic/claude-opus-4.7',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Opus 4.7',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'anthropic/claude-opus-4.8',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Opus 4.8',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'anthropic/claude-opus-4.8-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Opus 4.8 (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'anthropic/claude-opus-5',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Opus 5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, supportsTemperature: false },
+  },
+  {
+    id: 'anthropic/claude-opus-5-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Opus 5 (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, supportsTemperature: false },
+  },
+  {
+    id: 'anthropic/claude-opus-5.5',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Opus 5.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.2, cacheWrite: 5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'anthropic/claude-opus-5.5-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Opus 5.5 (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 8, output: 40, cacheRead: 0.4, cacheWrite: 10 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'anthropic/claude-sonnet-4',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Sonnet 4',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'anthropic/claude-sonnet-4.5',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Sonnet 4.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'anthropic/claude-sonnet-4.6',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Sonnet 4.6',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'anthropic/claude-sonnet-5',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Sonnet 5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    reasoningBudget: true,
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, supportsTemperature: false },
+  },
+  {
+    id: 'anthropic/claude-sonnet-5.5',
+    provider: 'vercel-ai-gateway',
+    name: 'Claude Sonnet 5.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'arcee-ai/trinity-large-thinking',
+    provider: 'vercel-ai-gateway',
+    name: 'Trinity Large Thinking',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 0.9, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262100,
+    maxTokens: 80000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'bytedance/seed-1.6',
+    provider: 'vercel-ai-gateway',
+    name: 'Seed 1.6',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.25, output: 2, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 32000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'bytedance/seed-1.8',
+    provider: 'vercel-ai-gateway',
+    name: 'Seed 1.8',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 2, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'bytedance/seed-2.1-turbo',
+    provider: 'vercel-ai-gateway',
+    name: 'Seed 2.1 Turbo',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.5, output: 2.5, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'cohere/command-a',
+    provider: 'vercel-ai-gateway',
+    name: 'Command A',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 2.5, output: 10, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 8000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'cohere/embed-v4.0',
+    provider: 'vercel-ai-gateway',
+    name: 'Embed v4.0',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 1536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'cohere/rerank-v3.5',
+    provider: 'vercel-ai-gateway',
+    name: 'Cohere Rerank 3.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 4096,
+    maxTokens: 4096,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'cohere/rerank-v4-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'Cohere Rerank 4 Fast',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 32000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'cohere/rerank-v4-pro',
+    provider: 'vercel-ai-gateway',
+    name: 'Cohere Rerank 4 Pro',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 32000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'deepseek/deepseek-r1',
+    provider: 'vercel-ai-gateway',
+    name: 'DeepSeek-R1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 1.35, output: 5.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'deepseek/deepseek-v3.1',
+    provider: 'vercel-ai-gateway',
+    name: 'DeepSeek-V3.1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 0.95, cacheRead: 0.13, cacheWrite: 0 },
+    contextWindow: 163840,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'deepseek/deepseek-v3.1-terminus',
+    provider: 'vercel-ai-gateway',
+    name: 'DeepSeek V3.1 Terminus',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.27, output: 1, cacheRead: 0.135, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'deepseek/deepseek-v3.2',
+    provider: 'vercel-ai-gateway',
+    name: 'DeepSeek V3.2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.62, output: 1.85, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'deepseek/deepseek-v3.2-thinking',
+    provider: 'vercel-ai-gateway',
+    name: 'DeepSeek V3.2 Thinking',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.62, output: 1.85, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'deepseek/deepseek-v4-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'DeepSeek V4 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.13, output: 0.26, cacheRead: 0.028, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'deepseek/deepseek-v4-flash-0731',
+    provider: 'vercel-ai-gateway',
+    name: 'DeepSeek V4 Flash 0731',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.076, output: 0.153, cacheRead: 0.014, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'deepseek/deepseek-v4-flash-vision-exp',
+    provider: 'vercel-ai-gateway',
+    name: 'DeepSeek V4 Flash Vision Exp',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.2156, output: 0.6468, cacheRead: 0.0068, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'deepseek/deepseek-v4-pro',
+    provider: 'vercel-ai-gateway',
+    name: 'DeepSeek V4 Pro',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.66, output: 1.98, cacheRead: 0.022, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'deepseek/deepseek-v4-pro-0813',
+    provider: 'vercel-ai-gateway',
+    name: 'DeepSeek V4 Pro 0813',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.66, output: 1.98, cacheRead: 0.066, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 384000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'deepseek/deepseek-v4.1-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'DeepSeek V4.1 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.007, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'fireworks/ember-1',
+    provider: 'vercel-ai-gateway',
+    name: 'Ember-1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'fish-audio/transcribe-1',
+    provider: 'vercel-ai-gateway',
+    name: 'Transcribe-1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['audio'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'google/gemini-2.5-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini 2.5 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.3, output: 2.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'google/gemini-2.5-flash-image',
+    provider: 'vercel-ai-gateway',
+    name: 'Nano Banana (Gemini 2.5 Flash Image)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.3, output: 2.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 32768,
+    maxTokens: 65535,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'google/gemini-2.5-flash-lite',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini 2.5 Flash Lite',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    reasoningBudget: true,
+    cost: { input: 0.1, output: 0.4, cacheRead: 0.01, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65535,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'google/gemini-2.5-pro',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini 2.5 Pro',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 65536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'google/gemini-3-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini 3 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 65000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'google/gemini-3-pro-image',
+    provider: 'vercel-ai-gateway',
+    name: 'Nano Banana Pro',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 65536,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'google/gemini-3.1-flash-image',
+    provider: 'vercel-ai-gateway',
+    name: 'Nano Banana 2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'google/gemini-3.1-flash-image-preview',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini 3.1 Flash Image Preview (Nano Banana 2)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'google/gemini-3.1-flash-lite',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini 3.1 Flash Lite',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 1.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 65000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'google/gemini-3.1-flash-lite-image',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini 3.1 Flash Lite Image (Nano Banana 2 Lite)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 1.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 65536,
+    maxTokens: 4096,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'google/gemini-3.1-pro-preview',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini 3.1 Pro Preview',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'google/gemini-3.5-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini 3.5 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.5, output: 9, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'google/gemini-3.5-flash-lite',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini 3.5 Flash Lite',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.3, output: 2.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 65000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'google/gemini-3.5-transcribe',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini 3.5 Transcribe',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['audio'],
+    reasoning: false,
+    cost: { input: 2, output: 12, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'google/gemini-3.5-transcribe-live',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini 3.5 Transcribe Live',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['audio'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'google/gemini-3.6-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini 3.6 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 64000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'google/gemini-3.7-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini 3.7 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 65535,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'google/gemini-3.8-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini 3.8 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 65535,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'google/gemini-3.8-live',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini 3.8 Live',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'audio'],
+    reasoning: false,
+    cost: { input: 0.75, output: 4.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'google/gemini-3.8-live-extended-thinking',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini 3.8 Live Extended Thinking',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'audio'],
+    reasoning: false,
+    cost: { input: 0.75, output: 4.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'google/gemini-embedding-001',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini Embedding 001',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'google/gemini-embedding-2',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini Embedding 2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'google/gemini-omni-flash-preview',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemini Omni Flash Preview',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.5, output: 9, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 57920,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'google/gemma-4-26b-a4b-it',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemma 4 26B A4B IT',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'google/gemma-4-31b-it',
+    provider: 'vercel-ai-gateway',
+    name: 'Gemma 4 31B IT',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.14, output: 0.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'google/text-embedding-005',
+    provider: 'vercel-ai-gateway',
+    name: 'Text Embedding 005',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'google/text-multilingual-embedding-002',
+    provider: 'vercel-ai-gateway',
+    name: 'Text Multilingual Embedding 002',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'inception/mercury-2',
+    provider: 'vercel-ai-gateway',
+    name: 'Mercury 2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: {
+      input: 0.25,
+      output: 0.75,
+      cacheRead: 0.024999999999999998,
+      cacheWrite: 0,
+    },
+    contextWindow: 128000,
+    maxTokens: 50000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'inception/mercury-2.5',
+    provider: 'vercel-ai-gateway',
+    name: 'Mercury 2.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.04, output: 0.15, cacheRead: 0.004, cacheWrite: 0 },
+    contextWindow: 260000,
+    maxTokens: 65536,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'inception/mercury-coder-small',
+    provider: 'vercel-ai-gateway',
+    name: 'Mercury Coder Small Beta',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.25, output: 1, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 16384,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'inclusionai/ling-3.0-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'Ling 3.0 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.021, output: 0.063, cacheRead: 0.0042, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 32000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'inclusionai/ling-3.0-flash-fin',
+    provider: 'vercel-ai-gateway',
+    name: 'Ling 3.0 Flash Fin',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.075, output: 0.22, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 32000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'inclusionai/ling-3.0-flash-fin-free',
+    provider: 'vercel-ai-gateway',
+    name: 'inclusionAI: Ling 3.0 Flash Fin',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.075, output: 0.22, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    borrowedFrom: 'kilo/inclusionai/ling-3.0-flash-fin',
+  },
+  {
+    id: 'inclusionai/ling-3.0-flash-sante',
+    provider: 'vercel-ai-gateway',
+    name: 'Ling 3.0 Flash Sante',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 32000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'inclusionai/ling-3.0-flash-sante-free',
+    provider: 'vercel-ai-gateway',
+    name: 'Ling 3.0 Flash Sante (Free)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 32000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'inclusionai/ling-3.0-flash-vl',
+    provider: 'vercel-ai-gateway',
+    name: 'Ling 3.0 Flash VL',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.075, output: 0.22, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 32000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'inclusionai/ling-3.0-flash-vl-free',
+    provider: 'vercel-ai-gateway',
+    name: 'Ling 3.0 Flash VL',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.06, output: 0.18, cacheRead: 0.012, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    borrowedFrom: 'nano-gpt/inclusionai/ling-3.0-flash-vl',
+  },
+  {
+    id: 'inclusionai/ling-3.1-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'Ling 3.1 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'inclusionai/ling-3.1-flash-free',
+    provider: 'vercel-ai-gateway',
+    name: 'Ling 3.1 Flash (Free)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'inference-net/schematron-v2-small',
+    provider: 'vercel-ai-gateway',
+    name: 'Schematron V2 Small',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.05, output: 0.23, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'inference-net/schematron-v2-turbo',
+    provider: 'vercel-ai-gateway',
+    name: 'Schematron V2 Turbo',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.03, output: 0.15, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'interfaze/interfaze-beta',
+    provider: 'vercel-ai-gateway',
+    name: 'Interfaze Beta',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.5, output: 3.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 32000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'liquid/d1',
+    provider: 'vercel-ai-gateway',
+    name: 'Liquid d1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'meituan/longcat-2.5-preview',
+    provider: 'vercel-ai-gateway',
+    name: 'LongCat 2.5 Preview',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.006, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'meta/llama-3.1-70b',
+    provider: 'vercel-ai-gateway',
+    name: 'Llama 3.1 70B Instruct',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.72, output: 0.72, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'meta/llama-3.1-8b',
+    provider: 'vercel-ai-gateway',
+    name: 'Llama 3.1 8B Instruct',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.22, output: 0.22, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'meta/llama-3.3-70b',
+    provider: 'vercel-ai-gateway',
+    name: 'Llama-3.3-70B-Instruct',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'meta/llama-4-maverick',
+    provider: 'vercel-ai-gateway',
+    name: 'Llama-4-Maverick-17B-128E-Instruct-FP8',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'meta/llama-4-scout',
+    provider: 'vercel-ai-gateway',
+    name: 'Llama-4-Scout-17B-16E-Instruct-FP8',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'meta/muse-glimmer-30b',
+    provider: 'vercel-ai-gateway',
+    name: 'Muse Glimmer 30B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.35, output: 1.5, cacheRead: 0.04, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'meta/muse-spark-1.1',
+    provider: 'vercel-ai-gateway',
+    name: 'Muse Spark 1.1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'meta/muse-spark-1.2',
+    provider: 'vercel-ai-gateway',
+    name: 'Muse Spark 1.2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'meta/muse-spark-1.2-contributor',
+    provider: 'vercel-ai-gateway',
+    name: 'Muse Spark 1.2 Contributor',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.1, output: 0.2, cacheRead: 0.002, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'meta/muse-spark-1.3',
+    provider: 'vercel-ai-gateway',
+    name: 'Muse Spark 1.3',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'meta/muse-spark-1.3-contributor',
+    provider: 'vercel-ai-gateway',
+    name: 'Muse Spark 1.3 Contributor',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.1, output: 0.2, cacheRead: 0.002, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1048576,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'minimax/minimax-m2',
+    provider: 'vercel-ai-gateway',
+    name: 'MiniMax M2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.375 },
+    contextWindow: 205000,
+    maxTokens: 196608,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'minimax/minimax-m2.1',
+    provider: 'vercel-ai-gateway',
+    name: 'MiniMax M2.1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'minimax/minimax-m2.1-lightning',
+    provider: 'vercel-ai-gateway',
+    name: 'MiniMax M2.1 Lightning',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 0.3, output: 2.4, cacheRead: 0.03, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'minimax/minimax-m2.5',
+    provider: 'vercel-ai-gateway',
+    name: 'MiniMax M2.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'minimax/minimax-m2.5-highspeed',
+    provider: 'vercel-ai-gateway',
+    name: 'MiniMax M2.5 High Speed',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 0.6, output: 2.4, cacheRead: 0.03, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'minimax/minimax-m2.7',
+    provider: 'vercel-ai-gateway',
+    name: 'Minimax M2.7',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'minimax/minimax-m2.7-highspeed',
+    provider: 'vercel-ai-gateway',
+    name: 'MiniMax M2.7 High Speed',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 0.6, output: 2.4, cacheRead: 0.06, cacheWrite: 0.375 },
+    contextWindow: 204800,
+    maxTokens: 131100,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'minimax/minimax-m3',
+    provider: 'vercel-ai-gateway',
+    name: 'MiniMax M3',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningBudget: true,
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 512000,
+    maxTokens: 512000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'mistral/codestral',
+    provider: 'vercel-ai-gateway',
+    name: 'Codestral (latest)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.3, output: 0.9, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 4096,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'mistral/codestral-embed',
+    provider: 'vercel-ai-gateway',
+    name: 'Codestral Embed',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'mistral/ministral-14b',
+    provider: 'vercel-ai-gateway',
+    name: 'Ministral 14B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.2, output: 0.2, cacheRead: 0.02, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 256000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'mistral/ministral-3b',
+    provider: 'vercel-ai-gateway',
+    name: 'Ministral 3B (latest)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.04, output: 0.04, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'mistral/ministral-8b',
+    provider: 'vercel-ai-gateway',
+    name: 'Ministral 8B (latest)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.1, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'mistral/mistral-embed',
+    provider: 'vercel-ai-gateway',
+    name: 'Mistral Embed',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'mistral/mistral-large-3',
+    provider: 'vercel-ai-gateway',
+    name: 'Mistral Large 3',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.5, output: 1.5, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 256000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'mistral/mistral-medium-3.5',
+    provider: 'vercel-ai-gateway',
+    name: 'Mistral Medium Latest',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.5, output: 7.5, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 256000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'mistral/mistral-nemo',
+    provider: 'vercel-ai-gateway',
+    name: 'Mistral Nemo',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.04, output: 0.17, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 60288,
+    maxTokens: 16000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'mistral/mistral-small',
+    provider: 'vercel-ai-gateway',
+    name: 'Mistral Small (latest)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.015, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 4000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'mixedbread/toast-1',
+    provider: 'vercel-ai-gateway',
+    name: 'Toast 1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.3, output: 0.72, cacheRead: 0.036, cacheWrite: 0 },
+    contextWindow: 131000,
+    maxTokens: 4000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'moonshotai/kimi-k2',
+    provider: 'vercel-ai-gateway',
+    name: 'Kimi K2 Instruct',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.57, output: 2.3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'moonshotai/kimi-k2-thinking',
+    provider: 'vercel-ai-gateway',
+    name: 'Kimi K2 Thinking',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.47, output: 2, cacheRead: 0.141, cacheWrite: 0 },
+    contextWindow: 216144,
+    maxTokens: 216144,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'moonshotai/kimi-k2.5',
+    provider: 'vercel-ai-gateway',
+    name: 'Kimi K2.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 3, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 256000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'moonshotai/kimi-k2.6',
+    provider: 'vercel-ai-gateway',
+    name: 'Kimi K2.6',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
+    contextWindow: 262000,
+    maxTokens: 262000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'moonshotai/kimi-k2.7-code',
+    provider: 'vercel-ai-gateway',
+    name: 'Kimi K2.7 Code',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.95, output: 4, cacheRead: 0.19, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'moonshotai/kimi-k2.7-code-highspeed',
+    provider: 'vercel-ai-gateway',
+    name: 'Kimi K2.7 Code High Speed',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.9, output: 8, cacheRead: 0.38, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'moonshotai/kimi-k3',
+    provider: 'vercel-ai-gateway',
+    name: 'Kimi K3',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'moonshotai/kimi-k3-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'Kimi K3 Fast',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 4.5, output: 22.5, cacheRead: 0.45, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'morph/morph-v3-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'Morph v3 Fast',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.8, output: 1.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 16000,
+    maxTokens: 16000,
+    compat: { allowEmptySignature: true, supportsTemperature: false },
+  },
+  {
+    id: 'morph/morph-v3-large',
+    provider: 'vercel-ai-gateway',
+    name: 'Morph v3 Large',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.9, output: 1.9, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 32000,
+    compat: { allowEmptySignature: true, supportsTemperature: false },
+  },
+  {
+    id: 'nvidia/nemotron-3-nano-30b-a3b',
+    provider: 'vercel-ai-gateway',
+    name: 'Nemotron 3 Nano 30B A3B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.05, output: 0.2, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'nvidia/nemotron-3-super-120b-a12b',
+    provider: 'vercel-ai-gateway',
+    name: 'NVIDIA Nemotron 3 Super 120B A12B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.15, output: 0.65, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 32000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'nvidia/nemotron-3-ultra-550b-a55b',
+    provider: 'vercel-ai-gateway',
+    name: 'Nemotron 3 Ultra',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 65000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'nvidia/nemotron-3.5-lightning',
+    provider: 'vercel-ai-gateway',
+    name: 'Nemotron 3.5 Lightning 30B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    reasoningBudget: true,
+    cost: { input: 0.05, output: 0.2, cacheRead: 0.01, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'nvidia/nemotron-nano-12b-v2-vl',
+    provider: 'vercel-ai-gateway',
+    name: 'Nvidia Nemotron Nano 12B V2 VL',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.2, output: 0.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'nvidia/nemotron-nano-9b-v2',
+    provider: 'vercel-ai-gateway',
+    name: 'Nvidia Nemotron Nano 9B V2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.06, output: 0.23, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-3.5-turbo',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-3.5 Turbo',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.5, output: 1.5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 16385,
+    maxTokens: 4096,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-4-turbo',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-4 Turbo',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 10, output: 30, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-4.1',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-4.1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 2, output: 8, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-4.1-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-4.1 (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 3.5, output: 14, cacheRead: 0.875, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-4.1-mini',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-4.1 mini',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.4, output: 1.6, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-4.1-mini-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-4.1 mini (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.7, output: 2.8, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-4.1-nano',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-4.1 nano',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.1, output: 0.4, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-4.1-nano-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-4.1 nano (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.2, output: 0.8, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 1047576,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-4o',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-4o',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 2.5, output: 10, cacheRead: 1.25, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-4o-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-4o (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 4.25, output: 17, cacheRead: 2.125, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-4o-mini',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-4o mini',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.15, output: 0.6, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-4o-mini-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-4o mini (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.25, output: 1, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-4o-mini-transcribe',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-4o mini Transcribe',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['audio'],
+    reasoning: false,
+    cost: { input: 1.25, output: 5, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-4o-transcribe',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-4o Transcribe',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['audio'],
+    reasoning: false,
+    cost: { input: 2.5, output: 10, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-5',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-5-codex',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-5-Codex',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.13, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-5-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-5 (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2.5, output: 20, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-5-mini',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-5 Mini',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 2, cacheRead: 0.025, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-5-mini-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-5 mini (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.45, output: 3.6, cacheRead: 0.045, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-5-nano',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-5 Nano',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.05, output: 0.4, cacheRead: 0.005, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-5-pro',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-5 pro',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 15, output: 120, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 272000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.1-codex',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-5.1-Codex',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.13, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.1-codex-max',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.1 Codex Max',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.1-codex-mini',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-5.1 Codex mini',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.25, output: 2, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.1-thinking',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.1 Thinking',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.1-thinking-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.1 Thinking (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2.5, output: 20, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.2',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-5.2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.2-codex',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-5.2-Codex',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.2-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.2 (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 3.5, output: 28, cacheRead: 0.35, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.2-pro',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.2 ',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 21, output: 168, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.3-codex',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.3 Codex',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.3-codex-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.3 Codex (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 3.5, output: 28, cacheRead: 0.35, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.4',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.4',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.4-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.4 (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.4-mini',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.4 Mini',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.75, output: 4.5, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.4-mini-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.4 Mini (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.5, output: 9, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.4-nano',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.4 Nano',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0.2, output: 1.25, cacheRead: 0.02, cacheWrite: 0 },
+    contextWindow: 400000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.4-pro',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.4 Pro',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.5',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.5-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.5 (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 12.5, output: 75, cacheRead: 1.25, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-5.5-pro',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.5 Pro',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.6-luna',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.6 Luna',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.6-luna-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.6 Luna (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.4, output: 2.4, cacheRead: 0.04, cacheWrite: 0.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-5.6-sol',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.6 Sol',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.6-sol-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.6 Sol (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 8, output: 40, cacheRead: 0.8, cacheWrite: 10 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-5.6-terra',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.6 Terra',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-5.6-terra-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT 5.6 Terra (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 24, cacheRead: 0.4, cacheWrite: 5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-6-astra',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-6 Astra',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-6-astra-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-6 Astra (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 20, output: 100, cacheRead: 2, cacheWrite: 25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-6-luna',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-6 Luna',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-6-luna-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-6 Luna (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.2, output: 1, cacheRead: 0.02, cacheWrite: 0.25 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-6-sol',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-6 Sol',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-6-sol-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-6 Sol (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-6.1-sol',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-6.1 Sol',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-6.1-sol-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-6.1 Sol (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.2, cacheWrite: 5 },
+    contextWindow: 1050000,
+    maxTokens: 128000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/gpt-live-1',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-Live 1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'audio'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-oss-120b',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT OSS 120B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.1, output: 0.5, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-oss-20b',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT OSS 20B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.03, output: 0.14, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 8192,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-oss-safeguard-120b',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT OSS Safeguard 120B',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.15, output: 0.6, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-oss-safeguard-20b',
+    provider: 'vercel-ai-gateway',
+    name: 'gpt-oss-safeguard-20b',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.07, output: 0.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-realtime-1.5',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-Realtime-1.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'audio'],
+    reasoning: false,
+    cost: { input: 4, output: 16, cacheRead: 0.4, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-realtime-2',
+    provider: 'vercel-ai-gateway',
+    name: 'gpt-realtime-2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'audio'],
+    reasoning: false,
+    cost: { input: 4, output: 24, cacheRead: 0.4, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-realtime-2.1',
+    provider: 'vercel-ai-gateway',
+    name: 'gpt-realtime-2.1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'audio'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 4, output: 24, cacheRead: 0.4, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 32000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/gpt-realtime-mini',
+    provider: 'vercel-ai-gateway',
+    name: 'GPT-Realtime mini',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'audio'],
+    reasoning: false,
+    cost: { input: 0.6, output: 2.4, cacheRead: 0.06, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/gpt-realtime-whisper',
+    provider: 'vercel-ai-gateway',
+    name: 'gpt-realtime-whisper',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['audio'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/o1',
+    provider: 'vercel-ai-gateway',
+    name: 'o1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 15, output: 60, cacheRead: 7.5, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/o3',
+    provider: 'vercel-ai-gateway',
+    name: 'o3',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 8, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/o3-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'o3 (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 3.5, output: 14, cacheRead: 0.875, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/o3-mini',
+    provider: 'vercel-ai-gateway',
+    name: 'o3-mini',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.1, output: 4.4, cacheRead: 0.55, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/o3-pro',
+    provider: 'vercel-ai-gateway',
+    name: 'o3 Pro',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 20, output: 80, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'openai/o4-mini',
+    provider: 'vercel-ai-gateway',
+    name: 'o4-mini',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.1, output: 4.4, cacheRead: 0.275, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/o4-mini-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'o4-mini (Fast)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 8, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 100000,
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
+  },
+  {
+    id: 'openai/text-embedding-3-large',
+    provider: 'vercel-ai-gateway',
+    name: 'text-embedding-3-large',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/text-embedding-3-small',
+    provider: 'vercel-ai-gateway',
+    name: 'text-embedding-3-small',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/text-embedding-ada-002',
+    provider: 'vercel-ai-gateway',
+    name: 'text-embedding-ada-002',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'openai/whisper-1',
+    provider: 'vercel-ai-gateway',
+    name: 'Whisper',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['audio'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'perplexity/pplx-embed-v1-0.6b',
+    provider: 'vercel-ai-gateway',
+    name: 'Embed v1 0.6b',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'perplexity/pplx-embed-v1-4b',
+    provider: 'vercel-ai-gateway',
+    name: 'Embed v1 4b',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'perplexity/sonar',
+    provider: 'vercel-ai-gateway',
+    name: 'Sonar',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.25, output: 2.5, cacheRead: 0, cacheWrite: 0.0625 },
+    contextWindow: 127000,
+    maxTokens: 8000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'poolside/laguna-s-2.1',
+    provider: 'vercel-ai-gateway',
+    name: 'Laguna S 2.1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.1, output: 0.2, cacheRead: 0.01, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'poolside/laguna-s-2.1-free',
+    provider: 'vercel-ai-gateway',
+    name: 'Laguna S 2.1 Free',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 32768,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'quiverai/arrow-2',
+    provider: 'vercel-ai-gateway',
+    name: 'Arrow 2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
+    contextWindow: 131072,
+    maxTokens: 65536,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'quiverai/arrow-2-telos',
+    provider: 'vercel-ai-gateway',
+    name: 'Arrow 2 Telos',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 6, output: 30, cacheRead: 0.6, cacheWrite: 7.5 },
+    contextWindow: 131072,
+    maxTokens: 65536,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'sakana/fugu-max',
+    provider: 'vercel-ai-gateway',
+    name: 'Fugu Max',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 1000000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'sakana/fugu-ultra',
+    provider: 'vercel-ai-gateway',
+    name: 'Fugu Ultra',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 1000000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'sakana/fugu-ultra-v2',
+    provider: 'vercel-ai-gateway',
+    name: 'Fugu Ultra v2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 1000000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'sakana/namazu',
+    provider: 'vercel-ai-gateway',
+    name: 'Sakana Namazu',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.95, output: 4, cacheRead: 0.15, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 256000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'spacexai/grok-4.1-fast-non-reasoning',
+    provider: 'vercel-ai-gateway',
+    name: 'Grok 4.1 Fast Non-Reasoning',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 0.2, output: 0.5, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 1000000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'spacexai/grok-4.1-fast-reasoning',
+    provider: 'vercel-ai-gateway',
+    name: 'Grok 4.1 Fast Reasoning',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.2, output: 0.5, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 1000000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'spacexai/grok-4.20-multi-agent',
+    provider: 'vercel-ai-gateway',
+    name: 'Grok 4.20 Multi-Agent',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 2000000,
+    maxTokens: 2000000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'spacexai/grok-4.20-multi-agent-beta',
+    provider: 'vercel-ai-gateway',
+    name: 'Grok 4.20 Multi Agent Beta',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 2000000,
+    maxTokens: 2000000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'spacexai/grok-4.20-non-reasoning',
+    provider: 'vercel-ai-gateway',
+    name: 'Grok 4.20 Non-Reasoning',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 2000000,
+    maxTokens: 2000000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'spacexai/grok-4.20-non-reasoning-beta',
+    provider: 'vercel-ai-gateway',
+    name: 'Grok 4.20 Beta Non-Reasoning',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.4, cacheWrite: 0 },
+    contextWindow: 2000000,
+    maxTokens: 2000000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'spacexai/grok-4.20-reasoning',
+    provider: 'vercel-ai-gateway',
+    name: 'Grok 4.20 Reasoning',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 2000000,
+    maxTokens: 2000000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'spacexai/grok-4.20-reasoning-beta',
+    provider: 'vercel-ai-gateway',
+    name: 'Grok 4.20 Beta Reasoning',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 2000000,
+    maxTokens: 2000000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'spacexai/grok-4.3',
+    provider: 'vercel-ai-gateway',
+    name: 'Grok 4.3',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 1000000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'spacexai/grok-4.5',
+    provider: 'vercel-ai-gateway',
+    name: 'Grok 4.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'spacexai/grok-4.6',
+    provider: 'vercel-ai-gateway',
+    name: 'Grok 4.6',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'spacexai/grok-4.7',
+    provider: 'vercel-ai-gateway',
+    name: 'Grok 4.7',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'spacexai/grok-build-0.1',
+    provider: 'vercel-ai-gateway',
+    name: 'Grok Build 0.1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1, output: 2, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 256000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'spacexai/grok-stt',
+    provider: 'vercel-ai-gateway',
+    name: 'Grok STT',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['audio'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'spacexai/grok-voice-think-fast-1.0',
+    provider: 'vercel-ai-gateway',
+    name: 'Grok Voice Think Fast 1.0',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'audio'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'spacexai/grok-voice-think-fast-2.0',
+    provider: 'vercel-ai-gateway',
+    name: 'Grok Voice Think Fast 2.0',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'audio'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'stealth/pixel-canary',
+    provider: 'vercel-ai-gateway',
+    name: 'Pixel Canary',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'stepfun/step-3.5-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'StepFun 3.5 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.09, output: 0.3, cacheRead: 0.02, cacheWrite: 0 },
+    contextWindow: 262114,
+    maxTokens: 262114,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'stepfun/step-3.7-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'Step 3.7 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.2, output: 1.15, cacheRead: 0.04, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 256000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'stepfun/step-5-preview',
+    provider: 'vercel-ai-gateway',
+    name: 'Step 5 Preview',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 1, output: 2.7, cacheRead: 0.05, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 1000000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'tencent/hy-mt2-lite',
+    provider: 'vercel-ai-gateway',
+    name: 'Tencent Hy-MT2-Lite',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.044, output: 0.177, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8000,
+    maxTokens: 4000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'tencent/hy-mt2-plus',
+    provider: 'vercel-ai-gateway',
+    name: 'Tencent Hy-MT2-Plus',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.074, output: 0.295, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8000,
+    maxTokens: 4000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'tencent/hy-mt2-pro',
+    provider: 'vercel-ai-gateway',
+    name: 'Tencent Hy-MT2-Pro',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.074, output: 0.295, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8000,
+    maxTokens: 4000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'tencent/hy3',
+    provider: 'vercel-ai-gateway',
+    name: 'Hy3',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.14, output: 0.58, cacheRead: 0.035, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 262144,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'tencent/hy4-preview',
+    provider: 'vercel-ai-gateway',
+    name: 'Tencent Hy4 Preview',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.834, output: 2.501, cacheRead: 0.042, cacheWrite: 0 },
+    contextWindow: 1024000,
+    maxTokens: 64000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'thinkingmachines/inkling',
+    provider: 'vercel-ai-gateway',
+    name: 'Inkling',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 1, output: 4.05, cacheRead: 0.17, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 256000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'thinkingmachines/inkling-small',
+    provider: 'vercel-ai-gateway',
+    name: 'Inkling Small',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    cost: { input: 0.45, output: 1.2, cacheRead: 0.1, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 1000000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'typesafe-ai/jev',
+    provider: 'vercel-ai-gateway',
+    name: 'Jev',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.042, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'voyage/rerank-2.5',
+    provider: 'vercel-ai-gateway',
+    name: 'Voyage Rerank 2.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 32000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'voyage/rerank-2.5-lite',
+    provider: 'vercel-ai-gateway',
+    name: 'Voyage Rerank 2.5 Lite',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 32000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'voyage/voyage-3-large',
+    provider: 'vercel-ai-gateway',
+    name: 'voyage-3-large',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'voyage/voyage-3.5',
+    provider: 'vercel-ai-gateway',
+    name: 'voyage-3.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'voyage/voyage-3.5-lite',
+    provider: 'vercel-ai-gateway',
+    name: 'voyage-3.5-lite',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'voyage/voyage-4',
+    provider: 'vercel-ai-gateway',
+    name: 'voyage-4',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'voyage/voyage-4-large',
+    provider: 'vercel-ai-gateway',
+    name: 'voyage-4-large',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'voyage/voyage-4-lite',
+    provider: 'vercel-ai-gateway',
+    name: 'voyage-4-lite',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'voyage/voyage-code-2',
+    provider: 'vercel-ai-gateway',
+    name: 'voyage-code-2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'voyage/voyage-code-3',
+    provider: 'vercel-ai-gateway',
+    name: 'voyage-code-3',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'voyage/voyage-finance-2',
+    provider: 'vercel-ai-gateway',
+    name: 'voyage-finance-2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'voyage/voyage-law-2',
+    provider: 'vercel-ai-gateway',
+    name: 'voyage-law-2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 1536,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'xiaomi/mimo-v2.5',
+    provider: 'vercel-ai-gateway',
+    name: 'MiMo M2.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 131100,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'xiaomi/mimo-v2.5-pro',
+    provider: 'vercel-ai-gateway',
+    name: 'MiMo V2.5 Pro',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.0036, cacheWrite: 0 },
+    contextWindow: 1050000,
+    maxTokens: 131000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'xiaomi/mimo-v2.6-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'MiMo V2.6 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'xiaomi/mimo-v2.6-pro',
+    provider: 'vercel-ai-gateway',
+    name: 'MiMo V2.6 Pro',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.0036, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'xiaomi/mimo-v2.6-pro-ultraspeed',
+    provider: 'vercel-ai-gateway',
+    name: 'MiMo V2.6 Pro UltraSpeed',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 4.35, output: 8.7, cacheRead: 0.036, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'zai/glm-4.5',
+    provider: 'vercel-ai-gateway',
+    name: 'GLM 4.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 2.2, cacheRead: 0.11, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 96000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'zai/glm-4.5-air',
+    provider: 'vercel-ai-gateway',
+    name: 'GLM 4.5 Air',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.2, output: 1.1, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 96000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'zai/glm-4.5v',
+    provider: 'vercel-ai-gateway',
+    name: 'GLM 4.5V',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 1.8, cacheRead: 0.11, cacheWrite: 0 },
+    contextWindow: 66000,
+    maxTokens: 16000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'zai/glm-4.6',
+    provider: 'vercel-ai-gateway',
+    name: 'GLM 4.6',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 2.2, cacheRead: 0.11, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 96000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'zai/glm-4.7',
+    provider: 'vercel-ai-gateway',
+    name: 'GLM 4.7',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 2.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 120000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'zai/glm-4.7-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'GLM 4.7 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.07, output: 0.4, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 131000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'zai/glm-4.7-flashx',
+    provider: 'vercel-ai-gateway',
+    name: 'GLM 4.7 FlashX',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.06, output: 0.4, cacheRead: 0.01, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'zai/glm-5',
+    provider: 'vercel-ai-gateway',
+    name: 'GLM-5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1, output: 3.2, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 202800,
+    maxTokens: 131100,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'zai/glm-5-turbo',
+    provider: 'vercel-ai-gateway',
+    name: 'GLM 5 Turbo',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.2, output: 4, cacheRead: 0.24, cacheWrite: 0 },
+    contextWindow: 202800,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'zai/glm-5.1',
+    provider: 'vercel-ai-gateway',
+    name: 'GLM 5.1',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 202800,
+    maxTokens: 64000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'zai/glm-5.2',
+    provider: 'vercel-ai-gateway',
+    name: 'GLM 5.2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.8, output: 2.55, cacheRead: 0.16, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'zai/glm-5.2-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GLM 5.2 Fast',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2.8, output: 8.8, cacheRead: 0.56, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'zai/glm-5.3',
+    provider: 'vercel-ai-gateway',
+    name: 'GLM 5.3',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.14, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 1000000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'zai/glm-5.3-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'GLM 5.3 Fast',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2.1, output: 6.6, cacheRead: 0.21, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 262144,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'zai/glm-5.3-flash',
+    provider: 'vercel-ai-gateway',
+    name: 'GLM 5.3 Flash',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'zai/glm-5.3-flashx',
+    provider: 'vercel-ai-gateway',
+    name: 'GLM 5.3 FlashX',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.37, output: 1.25, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
+  {
+    id: 'zai/glm-5v-turbo',
+    provider: 'vercel-ai-gateway',
+    name: 'GLM 5V Turbo',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.2, output: 4, cacheRead: 0.24, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 128000,
+    compat: { allowEmptySignature: true },
+  },
+]
diff --git a/packages/ai-models/src/providers/xai.ts b/packages/ai-models/src/providers/xai.ts
new file mode 100644
index 0000000000..4f46780d50
--- /dev/null
+++ b/packages/ai-models/src/providers/xai.ts
@@ -0,0 +1,164 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** xAI. */
+export const provider: ProviderRecord = {
+  id: 'xai',
+  name: 'xAI',
+  baseUrl: 'https://api.x.ai/v1',
+  apis: ['openai-responses'],
+  env: [['XAI_API_KEY']],
+}
+
+/** Every xAI model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'grok-4.20-0309-non-reasoning',
+    provider: 'xai',
+    name: 'Grok 4.20 (Non-Reasoning)',
+    api: 'openai-responses',
+    baseUrl: 'https://api.x.ai/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: false,
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 30000,
+    compat: { supportsLongCacheRetention: false },
+  },
+  {
+    id: 'grok-4.20-0309-reasoning',
+    provider: 'xai',
+    name: 'Grok 4.20 (Reasoning)',
+    api: 'openai-responses',
+    baseUrl: 'https://api.x.ai/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 30000,
+    compat: { supportsLongCacheRetention: false },
+  },
+  {
+    id: 'grok-4.20-multi-agent-0309',
+    provider: 'xai',
+    name: 'Grok 4.20 Multi-Agent',
+    api: 'openai-responses',
+    baseUrl: 'https://api.x.ai/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 30000,
+    compat: { supportsLongCacheRetention: false },
+  },
+  {
+    id: 'grok-4.3',
+    provider: 'xai',
+    name: 'Grok 4.3',
+    api: 'openai-responses',
+    baseUrl: 'https://api.x.ai/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 30000,
+    compat: { supportsLongCacheRetention: false },
+  },
+  {
+    id: 'grok-4.5',
+    provider: 'xai',
+    name: 'Grok 4.5',
+    api: 'openai-responses',
+    baseUrl: 'https://api.x.ai/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.3, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+    compat: { supportsLongCacheRetention: false },
+  },
+  {
+    id: 'grok-4.6',
+    provider: 'xai',
+    name: 'Grok 4.6',
+    api: 'openai-responses',
+    baseUrl: 'https://api.x.ai/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+    compat: { supportsLongCacheRetention: false },
+  },
+  {
+    id: 'grok-4.7',
+    provider: 'xai',
+    name: 'Grok 4.7',
+    api: 'openai-responses',
+    baseUrl: 'https://api.x.ai/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    contextWindow: 500000,
+    maxTokens: 500000,
+    compat: { supportsLongCacheRetention: false },
+  },
+  {
+    id: 'grok-build-0.1',
+    provider: 'xai',
+    name: 'Grok Build 0.1',
+    api: 'openai-responses',
+    baseUrl: 'https://api.x.ai/v1',
+    input: ['text', 'image', 'document'],
+    reasoning: true,
+    cost: { input: 1, output: 2, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 256000,
+    compat: { supportsLongCacheRetention: false },
+  },
+]
diff --git a/packages/ai-models/src/providers/xiaomi-token-plan-ams.ts b/packages/ai-models/src/providers/xiaomi-token-plan-ams.ts
new file mode 100644
index 0000000000..86d47c9943
--- /dev/null
+++ b/packages/ai-models/src/providers/xiaomi-token-plan-ams.ts
@@ -0,0 +1,111 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Xiaomi MiMo Token Plan (Amsterdam). */
+export const provider: ProviderRecord = {
+  id: 'xiaomi-token-plan-ams',
+  name: 'Xiaomi MiMo Token Plan (Amsterdam)',
+  baseUrl: 'https://token-plan-ams.xiaomimimo.com/v1',
+  apis: ['openai-completions'],
+  env: [['XIAOMI_TOKEN_PLAN_AMS_API_KEY']],
+}
+
+/** Every Xiaomi MiMo Token Plan (Amsterdam) model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'mimo-v2.5',
+    provider: 'xiaomi-token-plan-ams',
+    name: 'MiMo-V2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://token-plan-ams.xiaomimimo.com/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+  {
+    id: 'mimo-v2.5-pro',
+    provider: 'xiaomi-token-plan-ams',
+    name: 'MiMo-V2.5-Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://token-plan-ams.xiaomimimo.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.0036, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+  {
+    id: 'mimo-v2.6-flash',
+    provider: 'xiaomi-token-plan-ams',
+    name: 'MiMo-V2.6-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://token-plan-ams.xiaomimimo.com/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+  {
+    id: 'mimo-v2.6-pro',
+    provider: 'xiaomi-token-plan-ams',
+    name: 'MiMo-V2.6-Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://token-plan-ams.xiaomimimo.com/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.0036, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/xiaomi-token-plan-cn.ts b/packages/ai-models/src/providers/xiaomi-token-plan-cn.ts
new file mode 100644
index 0000000000..8596b9dedb
--- /dev/null
+++ b/packages/ai-models/src/providers/xiaomi-token-plan-cn.ts
@@ -0,0 +1,111 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Xiaomi MiMo Token Plan (China). */
+export const provider: ProviderRecord = {
+  id: 'xiaomi-token-plan-cn',
+  name: 'Xiaomi MiMo Token Plan (China)',
+  baseUrl: 'https://token-plan-cn.xiaomimimo.com/v1',
+  apis: ['openai-completions'],
+  env: [['XIAOMI_TOKEN_PLAN_CN_API_KEY']],
+}
+
+/** Every Xiaomi MiMo Token Plan (China) model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'mimo-v2.5',
+    provider: 'xiaomi-token-plan-cn',
+    name: 'MiMo-V2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://token-plan-cn.xiaomimimo.com/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+  {
+    id: 'mimo-v2.5-pro',
+    provider: 'xiaomi-token-plan-cn',
+    name: 'MiMo-V2.5-Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://token-plan-cn.xiaomimimo.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.0036, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+  {
+    id: 'mimo-v2.6-flash',
+    provider: 'xiaomi-token-plan-cn',
+    name: 'MiMo-V2.6-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://token-plan-cn.xiaomimimo.com/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+  {
+    id: 'mimo-v2.6-pro',
+    provider: 'xiaomi-token-plan-cn',
+    name: 'MiMo-V2.6-Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://token-plan-cn.xiaomimimo.com/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.0036, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/xiaomi-token-plan-sgp.ts b/packages/ai-models/src/providers/xiaomi-token-plan-sgp.ts
new file mode 100644
index 0000000000..2a0df0e6aa
--- /dev/null
+++ b/packages/ai-models/src/providers/xiaomi-token-plan-sgp.ts
@@ -0,0 +1,111 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Xiaomi MiMo Token Plan (Singapore). */
+export const provider: ProviderRecord = {
+  id: 'xiaomi-token-plan-sgp',
+  name: 'Xiaomi MiMo Token Plan (Singapore)',
+  baseUrl: 'https://token-plan-sgp.xiaomimimo.com/v1',
+  apis: ['openai-completions'],
+  env: [['XIAOMI_TOKEN_PLAN_SGP_API_KEY']],
+}
+
+/** Every Xiaomi MiMo Token Plan (Singapore) model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'mimo-v2.5',
+    provider: 'xiaomi-token-plan-sgp',
+    name: 'MiMo-V2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://token-plan-sgp.xiaomimimo.com/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+  {
+    id: 'mimo-v2.5-pro',
+    provider: 'xiaomi-token-plan-sgp',
+    name: 'MiMo-V2.5-Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://token-plan-sgp.xiaomimimo.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.0036, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+  {
+    id: 'mimo-v2.6-flash',
+    provider: 'xiaomi-token-plan-sgp',
+    name: 'MiMo-V2.6-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://token-plan-sgp.xiaomimimo.com/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+  {
+    id: 'mimo-v2.6-pro',
+    provider: 'xiaomi-token-plan-sgp',
+    name: 'MiMo-V2.6-Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://token-plan-sgp.xiaomimimo.com/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.0036, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/xiaomi.ts b/packages/ai-models/src/providers/xiaomi.ts
new file mode 100644
index 0000000000..defed12b6e
--- /dev/null
+++ b/packages/ai-models/src/providers/xiaomi.ts
@@ -0,0 +1,231 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Xiaomi MiMo. */
+export const provider: ProviderRecord = {
+  id: 'xiaomi',
+  name: 'Xiaomi MiMo',
+  baseUrl: 'https://api.xiaomimimo.com/v1',
+  apis: ['openai-completions'],
+  env: [['XIAOMI_API_KEY']],
+}
+
+/** Every Xiaomi MiMo model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'mimo-v2-flash',
+    provider: 'xiaomi',
+    name: 'MiMo-V2-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://api.xiaomimimo.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 65536,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+  {
+    id: 'mimo-v2-omni',
+    provider: 'xiaomi',
+    name: 'MiMo-V2-Omni',
+    api: 'openai-completions',
+    baseUrl: 'https://api.xiaomimimo.com/v1',
+    input: ['text', 'image', 'audio', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+  {
+    id: 'mimo-v2-pro',
+    provider: 'xiaomi',
+    name: 'MiMo-V2-Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://api.xiaomimimo.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.0036, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+  {
+    id: 'mimo-v2.5',
+    provider: 'xiaomi',
+    name: 'MiMo-V2.5',
+    api: 'openai-completions',
+    baseUrl: 'https://api.xiaomimimo.com/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+  {
+    id: 'mimo-v2.5-pro',
+    provider: 'xiaomi',
+    name: 'MiMo-V2.5-Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://api.xiaomimimo.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.0036, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+  {
+    id: 'mimo-v2.5-pro-ultraspeed',
+    provider: 'xiaomi',
+    name: 'MiMo-V2.5-Pro-UltraSpeed',
+    api: 'openai-completions',
+    baseUrl: 'https://api.xiaomimimo.com/v1',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.305, output: 2.61, cacheRead: 0.0108, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+  {
+    id: 'mimo-v2.6-flash',
+    provider: 'xiaomi',
+    name: 'MiMo-V2.6-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://api.xiaomimimo.com/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+  {
+    id: 'mimo-v2.6-pro',
+    provider: 'xiaomi',
+    name: 'MiMo-V2.6-Pro',
+    api: 'openai-completions',
+    baseUrl: 'https://api.xiaomimimo.com/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.435, output: 0.87, cacheRead: 0.0036, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+  {
+    id: 'mimo-v2.6-pro-ultraspeed',
+    provider: 'xiaomi',
+    name: 'MiMo-V2.6-Pro-UltraSpeed',
+    api: 'openai-completions',
+    baseUrl: 'https://api.xiaomimimo.com/v1',
+    input: ['text', 'image', 'audio', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 4.35, output: 8.7, cacheRead: 0.036, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      supportsStrictMode: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      thinkingFormat: 'deepseek',
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/zai-coding-cn.ts b/packages/ai-models/src/providers/zai-coding-cn.ts
new file mode 100644
index 0000000000..5d11ffa513
--- /dev/null
+++ b/packages/ai-models/src/providers/zai-coding-cn.ts
@@ -0,0 +1,256 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Zhipu AI Coding Plan. */
+export const provider: ProviderRecord = {
+  id: 'zai-coding-cn',
+  name: 'Zhipu AI Coding Plan',
+  baseUrl: 'https://open.bigmodel.cn/api/coding/paas/v4',
+  apis: ['openai-completions'],
+  env: [['ZAI_CODING_CN_API_KEY']],
+}
+
+/** Every Zhipu AI Coding Plan model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'glm-4.6v',
+    provider: 'zai-coding-cn',
+    name: 'GLM-4.6V',
+    api: 'openai-completions',
+    baseUrl: 'https://open.bigmodel.cn/api/coding/paas/v4',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.3, output: 0.9, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-4.7',
+    provider: 'zai-coding-cn',
+    name: 'GLM-4.7',
+    api: 'openai-completions',
+    baseUrl: 'https://open.bigmodel.cn/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-5-turbo',
+    provider: 'zai-coding-cn',
+    name: 'GLM-5-Turbo',
+    api: 'openai-completions',
+    baseUrl: 'https://open.bigmodel.cn/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-5.2',
+    provider: 'zai-coding-cn',
+    name: 'GLM-5.2',
+    api: 'openai-completions',
+    baseUrl: 'https://open.bigmodel.cn/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'glm-5.2-highspeed',
+    provider: 'zai-coding-cn',
+    name: 'GLM-5.2 Highspeed',
+    api: 'openai-completions',
+    baseUrl: 'https://open.bigmodel.cn/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'glm-5.3',
+    provider: 'zai-coding-cn',
+    name: 'GLM-5.3',
+    api: 'openai-completions',
+    baseUrl: 'https://open.bigmodel.cn/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'glm-5.3-flash',
+    provider: 'zai-coding-cn',
+    name: 'GLM-5.3-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://open.bigmodel.cn/api/coding/paas/v4',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'glm-5.3-highspeed',
+    provider: 'zai-coding-cn',
+    name: 'GLM-5.3 Highspeed',
+    api: 'openai-completions',
+    baseUrl: 'https://open.bigmodel.cn/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+]
diff --git a/packages/ai-models/src/providers/zai.ts b/packages/ai-models/src/providers/zai.ts
new file mode 100644
index 0000000000..94d64f676d
--- /dev/null
+++ b/packages/ai-models/src/providers/zai.ts
@@ -0,0 +1,600 @@
+// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.
+import type { ModelRecord, ProviderRecord } from '../types'
+
+/** Z.AI. */
+export const provider: ProviderRecord = {
+  id: 'zai',
+  name: 'Z.AI',
+  baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+  apis: ['openai-completions'],
+  env: [['ZAI_API_KEY']],
+}
+
+/** Every Z.AI model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = [
+  {
+    id: 'glm-4.5',
+    provider: 'zai',
+    name: 'GLM-4.5',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 2.2, cacheRead: 0.11, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 98304,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-4.5-air',
+    provider: 'zai',
+    name: 'GLM-4.5-Air',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.2, output: 1.1, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 98304,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-4.5-flash',
+    provider: 'zai',
+    name: 'GLM-4.5-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 131072,
+    maxTokens: 98304,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-4.5v',
+    provider: 'zai',
+    name: 'GLM-4.5V',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 1.8, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 64000,
+    maxTokens: 16384,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-4.6',
+    provider: 'zai',
+    name: 'GLM-4.6',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 2.2, cacheRead: 0.11, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-4.6v',
+    provider: 'zai',
+    name: 'GLM-4.6V',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.3, output: 0.9, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-4.6v-flash',
+    provider: 'zai',
+    name: 'GLM-4.6V-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text', 'image', 'video'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 32768,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-4.7',
+    provider: 'zai',
+    name: 'GLM-4.7',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.6, output: 2.2, cacheRead: 0.11, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-4.7-flash',
+    provider: 'zai',
+    name: 'GLM-4.7-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-4.7-flashx',
+    provider: 'zai',
+    name: 'GLM-4.7-FlashX',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 0.07, output: 0.4, cacheRead: 0.01, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-5',
+    provider: 'zai',
+    name: 'GLM-5',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1, output: 3.2, cacheRead: 0.2, cacheWrite: 0 },
+    contextWindow: 204800,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-5-turbo',
+    provider: 'zai',
+    name: 'GLM-5-Turbo',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.2, output: 4, cacheRead: 0.24, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-5.1',
+    provider: 'zai',
+    name: 'GLM-5.1',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+  {
+    id: 'glm-5.2',
+    provider: 'zai',
+    name: 'GLM-5.2',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'glm-5.2-highspeed',
+    provider: 'zai',
+    name: 'GLM-5.2 Highspeed',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+    borrowedFrom: 'zai-coding-plan/glm-5.2-highspeed',
+  },
+  {
+    id: 'glm-5.3',
+    provider: 'zai',
+    name: 'GLM-5.3',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'glm-5.3-flash',
+    provider: 'zai',
+    name: 'GLM-5.3-Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.15, output: 0.5, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'glm-5.3-flashx',
+    provider: 'zai',
+    name: 'GLM-5.3-FlashX',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0.37, output: 1.25, cacheRead: 0.075, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+  },
+  {
+    id: 'glm-5.3-highspeed',
+    provider: 'zai',
+    name: 'GLM-5.3 Highspeed',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text'],
+    reasoning: true,
+    reasoningMap: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 1000000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: true,
+    },
+    borrowedFrom: 'zhipuai-coding-plan/glm-5.3-highspeed',
+  },
+  {
+    id: 'glm-5v-turbo',
+    provider: 'zai',
+    name: 'GLM-5V-Turbo',
+    api: 'openai-completions',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    input: ['text', 'image', 'video', 'document'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    },
+    cost: { input: 1.2, output: 4, cacheRead: 0.24, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 131072,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      maxTokensField: 'max_tokens',
+      thinkingFormat: 'zai',
+      supportsStrictMode: true,
+      zaiToolStream: true,
+      requiresReasoningContentOnAssistantMessages: true,
+      supportsReasoningEffort: false,
+    },
+  },
+]
diff --git a/packages/ai-models/src/reasoning.ts b/packages/ai-models/src/reasoning.ts
new file mode 100644
index 0000000000..4f0dcf8eda
--- /dev/null
+++ b/packages/ai-models/src/reasoning.ts
@@ -0,0 +1,53 @@
+import type { ModelRecord, ReasoningLevel } from './types'
+
+// ponytail: the same rules as `supportedReasoningLevels` and
+// `clampReasoningLevel` in `@tanstack/ai` (pi's rules). They are copied so
+// this package has no dependencies. A test runs both on the same table.
+const LEVELS: ReadonlyArray<ReasoningLevel> = [
+  'off',
+  'minimal',
+  'low',
+  'medium',
+  'high',
+  'xhigh',
+  'max',
+]
+
+/**
+ * The levels a model supports: only `off` for a model that does not reason.
+ * Otherwise every level except the ones mapped to `null`, and `xhigh` and
+ * `max` only when the map has a value for them.
+ */
+export function supportedReasoningLevels(
+  model: Pick<ModelRecord, 'reasoning' | 'reasoningMap'>,
+): ReadonlyArray<ReasoningLevel> {
+  if (!model.reasoning) return ['off']
+  const map = model.reasoningMap
+  return LEVELS.filter((level) => {
+    const mapped = map?.[level]
+    if (mapped === null) return false
+    if (level === 'xhigh' || level === 'max') return mapped !== undefined
+    return true
+  })
+}
+
+/**
+ * The level to use: `level` when the model supports it, else the nearest
+ * supported level above it, else the nearest below it, else `off`.
+ */
+export function clampReasoningLevel(
+  model: Pick<ModelRecord, 'reasoning' | 'reasoningMap'>,
+  level: ReasoningLevel,
+): ReasoningLevel {
+  const supported = supportedReasoningLevels(model)
+  if (supported.includes(level)) return level
+  const index = LEVELS.indexOf(level)
+  const above = LEVELS.slice(index + 1).find((candidate) =>
+    supported.includes(candidate),
+  )
+  if (above) return above
+  const below = LEVELS.slice(0, index)
+    .reverse()
+    .find((candidate) => supported.includes(candidate))
+  return below ?? supported[0] ?? 'off'
+}
diff --git a/packages/ai-models/src/types.ts b/packages/ai-models/src/types.ts
new file mode 100644
index 0000000000..e71b507e9d
--- /dev/null
+++ b/packages/ai-models/src/types.ts
@@ -0,0 +1,152 @@
+/**
+ * How hard a model thinks. The same levels as `chat({ reasoning })` in
+ * `@tanstack/ai`, declared here too so this package has no dependencies.
+ */
+export type ReasoningLevel =
+  | 'off'
+  | 'minimal'
+  | 'low'
+  | 'medium'
+  | 'high'
+  | 'xhigh'
+  | 'max'
+
+/**
+ * The provider value to send for each level, or `null` when the model does
+ * not support the level. A level with no entry passes as its own name (except
+ * `xhigh` and `max`, which need an entry). `off: null` means "send nothing".
+ */
+export type ReasoningMap = Partial<Record<ReasoningLevel, string | null>>
+
+/** The wire protocol of a model. It picks the adapter. */
+export type WireApi =
+  | 'anthropic-messages'
+  | 'openai-completions'
+  | 'openai-responses'
+  | 'azure-openai-responses'
+  | 'google-generative-ai'
+  | 'google-vertex'
+  | 'bedrock-converse-stream'
+  | 'mistral-conversations'
+
+/** The input kinds a model reads. */
+export type InputModality = 'text' | 'image' | 'audio' | 'video' | 'document'
+
+/** How a Chat Completions request asks for thinking. */
+export type ThinkingFormat =
+  | 'openai'
+  | 'deepseek'
+  | 'zai'
+  | 'qwen'
+  | 'qwen-chat-template'
+  | 'chat-template'
+  | 'baseten'
+  | 'openrouter'
+  | 'together'
+  | 'string-thinking'
+  | 'ant-ling'
+
+/**
+ * Wire quirks of a model: the provider rule merged with the model's own
+ * hints (the model wins). An absent field means "the adapter default".
+ * The Chat Completions fields follow pi's `OpenAICompletionsCompat`.
+ */
+export interface ModelCompat {
+  // Chat Completions request shape.
+  thinkingFormat?: ThinkingFormat
+  supportsReasoningEffort?: boolean
+  supportsDeveloperRole?: boolean
+  maxTokensField?: 'max_completion_tokens' | 'max_tokens'
+  requiresReasoningContentOnAssistantMessages?: boolean
+  supportsStore?: boolean
+  supportsStrictMode?: boolean
+  supportsUsageInStreaming?: boolean
+  zaiToolStream?: boolean
+  sendSessionAffinityHeaders?: boolean
+  sessionAffinityFormat?: 'openai' | 'openrouter' | 'openai-nosession'
+  cacheControlFormat?: 'anthropic'
+  supportsLongCacheRetention?: boolean
+  thinkingTokenBudgetField?: string
+  chatTemplateKwargs?: Record<string, unknown>
+  chatTemplateArgs?: Record<string, unknown>
+  supportsTemperature?: boolean
+  // Anthropic Messages.
+  forceAdaptiveThinking?: boolean
+  supportsMidConvoSystemMessages?: boolean
+  supportsStrictTools?: boolean
+  allowEmptySignature?: boolean
+  supportsEagerToolInputStreaming?: boolean
+  supportsCacheControlOnTools?: boolean
+  // OpenAI Responses.
+  supportsAdditionalTools?: boolean
+  supportsToolSearch?: boolean
+  supportsOpenAIGrammarTools?: boolean
+}
+
+/** Prices in USD per 1M tokens. */
+export interface ModelCostRates {
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+}
+
+/** One model of one provider. */
+export interface ModelRecord {
+  /** The model id to send. Flue and pi use the same ids. */
+  id: string
+  /** The provider id, for example `'deepseek'`. */
+  provider: string
+  name: string
+  api: WireApi
+  /** The default endpoint. `{VAR}` parts come from the environment. */
+  baseUrl: string
+  input: ReadonlyArray<InputModality>
+  /** `false`: the model does not think, and supports only `off`. */
+  reasoning: boolean
+  /** The level map. None: every level up to `high` passes as its own name. */
+  reasoningMap?: ReasoningMap
+  /** `true`: the provider takes a thinking token budget. */
+  reasoningBudget?: boolean
+  cost: ModelCostRates
+  /** Tokens. `0` means not known. */
+  contextWindow: number
+  /** The most output tokens. `0` means not known. */
+  maxTokens: number
+  headers?: Readonly<Record<string, string>>
+  compat?: ModelCompat
+  /** The data came from the same model at another provider, for example `'anthropic/claude-sonnet-4-5'`. */
+  borrowedFrom?: string
+}
+
+/** One provider. */
+export interface ProviderRecord {
+  id: string
+  name: string
+  /** The default endpoint. A model can have its own `baseUrl`. */
+  baseUrl: string
+  apis: ReadonlyArray<WireApi>
+  /**
+   * Where the credentials come from: a list of alternatives. Each one is a
+   * set of environment variables that must all be set, for example
+   * `[['AWS_PROFILE'], ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY']]`.
+   */
+  env: ReadonlyArray<ReadonlyArray<string>>
+}
+
+/** Token counts of one call. */
+export interface TokenCounts {
+  input: number
+  output: number
+  cacheRead?: number
+  cacheWrite?: number
+}
+
+/** What a call cost, in USD. */
+export interface Cost {
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+  total: number
+}
diff --git a/packages/ai-models/tests/catalog.test.ts b/packages/ai-models/tests/catalog.test.ts
new file mode 100644
index 0000000000..9f46039ce7
--- /dev/null
+++ b/packages/ai-models/tests/catalog.test.ts
@@ -0,0 +1,123 @@
+import { describe, expect, it } from 'vitest'
+import {
+  clampReasoningLevel as coreClamp,
+  supportedReasoningLevels as coreSupported,
+} from '@tanstack/ai'
+import {
+  clampReasoningLevel,
+  generatedAt,
+  getModel,
+  getModels,
+  getProviders,
+  modelCost,
+  supportedReasoningLevels,
+} from '../src'
+import * as deepseek from '../src/providers/deepseek'
+import type { ModelRecord, ReasoningLevel, ReasoningMap } from '../src'
+
+describe('the catalog', () => {
+  it('has one module per provider, and the root lists them all', () => {
+    expect(getProviders()).toHaveLength(38)
+    expect(getModels('deepseek')).toBe(deepseek.models)
+    expect(getModels('unknown')).toEqual([])
+    expect(generatedAt).toMatch(/^\d{4}-\d{2}-\d{2}$/)
+  })
+
+  it('finds a model and gives its quirks (DeepSeek replays reasoning)', () => {
+    const model = getModel('deepseek', 'deepseek-v4-flash')
+    expect(model).toMatchObject({
+      provider: 'deepseek',
+      api: 'openai-completions',
+      baseUrl: 'https://api.deepseek.com',
+      reasoning: true,
+      compat: {
+        thinkingFormat: 'deepseek',
+        maxTokensField: 'max_tokens',
+        requiresReasoningContentOnAssistantMessages: true,
+      },
+    })
+    expect(model?.contextWindow).toBeGreaterThan(0)
+    expect(getModel('deepseek', 'no-such-model')).toBeUndefined()
+  })
+
+  it('serves OpenRouter Claude on the Anthropic wire, and the rest on completions', () => {
+    expect(getModel('openrouter', 'anthropic/claude-opus-4.5')).toMatchObject({
+      api: 'anthropic-messages',
+      baseUrl: 'https://openrouter.ai/api',
+      compat: { cacheControlFormat: 'anthropic', supportsDeveloperRole: true },
+    })
+    expect(
+      getModels('openrouter').find((model) => model.id.startsWith('z-ai/')),
+    ).toMatchObject({
+      api: 'openai-completions',
+      compat: { thinkingFormat: 'openrouter', supportsDeveloperRole: false },
+    })
+  })
+
+  it('lists credential alternatives, each a set of variables', () => {
+    const bedrock = getProviders().find((p) => p.id === 'amazon-bedrock')
+    expect(bedrock?.env).toContainEqual([
+      'AWS_ACCESS_KEY_ID',
+      'AWS_SECRET_ACCESS_KEY',
+    ])
+    const vertex = getProviders().find((p) => p.id === 'google-vertex')
+    expect(vertex?.env[0]).toEqual(['GOOGLE_CLOUD_API_KEY'])
+  })
+
+  it('marks a model whose data came from another provider', () => {
+    expect(
+      getModel('cloudflare-ai-gateway', 'workers-ai/@cf/openai/gpt-oss-120b')
+        ?.borrowedFrom,
+    ).toBe('cloudflare-workers-ai/@cf/openai/gpt-oss-120b')
+  })
+})
+
+describe('modelCost', () => {
+  it('prices each part per 1M tokens', () => {
+    const cost = modelCost(
+      { cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 } },
+      { input: 1_000_000, output: 100_000, cacheRead: 500_000 },
+    )
+    expect(cost).toEqual({
+      input: 3,
+      output: 1.5,
+      cacheRead: 0.15,
+      cacheWrite: 0,
+      total: 4.65,
+    })
+  })
+})
+
+describe('reasoning helpers match @tanstack/ai', () => {
+  const maps: ReadonlyArray<ReasoningMap | undefined> = [
+    undefined,
+    { off: 'none', low: 'low', high: 'high', xhigh: 'xhigh' },
+    { off: null, minimal: null, medium: null, max: 'max' },
+    { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+  ]
+  const levels: ReadonlyArray<ReasoningLevel> = [
+    'off',
+    'minimal',
+    'low',
+    'medium',
+    'high',
+    'xhigh',
+    'max',
+  ]
+
+  it.each(maps)('gives the same levels and clamps for %j', (map) => {
+    const model: Pick<ModelRecord, 'reasoning' | 'reasoningMap'> = {
+      reasoning: true,
+      ...(map ? { reasoningMap: map } : {}),
+    }
+    const core = { budget: false, ...(map ? { map } : {}) }
+    expect(supportedReasoningLevels(model)).toEqual(coreSupported(core))
+    for (const level of levels)
+      expect(clampReasoningLevel(model, level)).toBe(coreClamp(core, level))
+  })
+
+  it('supports only off on a model that does not reason', () => {
+    expect(supportedReasoningLevels({ reasoning: false })).toEqual(['off'])
+    expect(clampReasoningLevel({ reasoning: false }, 'max')).toBe('off')
+  })
+})
diff --git a/packages/ai-models/tests/drift.test.ts b/packages/ai-models/tests/drift.test.ts
new file mode 100644
index 0000000000..6ed4cbf135
--- /dev/null
+++ b/packages/ai-models/tests/drift.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import { getModels, getProviders } from '../src'
+import { BORROW, ONLY } from '../scripts/known-ids'
+import { EXTRA_MODELS, MODEL_OVERRIDES } from '../scripts/overrides'
+import { PROVIDERS } from '../scripts/providers'
+
+const rowIds = new Set(PROVIDERS.map((row) => row.id))
+
+describe('drift', () => {
+  it('every generated provider has a rule row, and every row was generated', () => {
+    expect(new Set(getProviders().map((provider) => provider.id))).toEqual(
+      rowIds,
+    )
+  })
+
+  it('every generated model belongs to a provider with a rule row', () => {
+    for (const provider of getProviders())
+      for (const model of getModels(provider.id))
+        expect(rowIds.has(model.provider), model.id).toBe(true)
+  })
+
+  it('every hand-kept list names a provider with a rule row', () => {
+    for (const list of [BORROW, ONLY, EXTRA_MODELS, MODEL_OVERRIDES])
+      for (const id of Object.keys(list)) expect(rowIds.has(id), id).toBe(true)
+  })
+
+  it('every provider has at least one model', () => {
+    for (const provider of getProviders())
+      expect(getModels(provider.id).length, provider.id).toBeGreaterThan(0)
+  })
+})
diff --git a/packages/ai-models/tests/parity.test.ts b/packages/ai-models/tests/parity.test.ts
new file mode 100644
index 0000000000..80df367c0f
--- /dev/null
+++ b/packages/ai-models/tests/parity.test.ts
@@ -0,0 +1,64 @@
+import { readFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+import { getModel } from '../src'
+
+// Parity with pi's built-in catalog (what Flue users write today). The pi
+// snapshot is never committed. Point PI_CATALOG_SNAPSHOT at the JSON file to
+// run this test. It fails on a missing id, and prints the fields that differ.
+const snapshotPath = process.env.PI_CATALOG_SNAPSHOT
+
+interface PiModel {
+  id: string
+  api: string
+  baseUrl: string
+  reasoning: boolean
+  input: Array<string>
+  contextWindow: number
+  maxTokens: number
+  cost: { input: number; output: number }
+}
+
+// Providers with no TanStack path (see the handoff): not in the catalog.
+const NOT_COVERED = new Set(['openai-codex', 'radius', 'github-copilot'])
+
+describe.skipIf(!snapshotPath)('parity with pi', () => {
+  it('resolves every model id of every covered provider', () => {
+    const snapshot: {
+      providers: Record<string, { models: Array<PiModel> }>
+    } = JSON.parse(readFileSync(snapshotPath ?? '', 'utf8'))
+    const missing: Array<string> = []
+    const differs: Record<string, number> = {}
+    let total = 0
+    for (const [providerId, provider] of Object.entries(snapshot.providers)) {
+      if (NOT_COVERED.has(providerId)) continue
+      for (const piModel of provider.models) {
+        total++
+        const model = getModel(providerId, piModel.id)
+        if (!model) {
+          missing.push(`${providerId}/${piModel.id}`)
+          continue
+        }
+        const checks: Record<string, boolean> = {
+          api: model.api === piModel.api,
+          baseUrl: model.baseUrl === piModel.baseUrl,
+          reasoning: model.reasoning === piModel.reasoning,
+          input: piModel.input.every((kind) =>
+            model.input.includes(kind as never),
+          ),
+          contextWindow: model.contextWindow === piModel.contextWindow,
+          maxTokens: model.maxTokens === piModel.maxTokens,
+          cost:
+            model.cost.input === piModel.cost.input &&
+            model.cost.output === piModel.cost.output,
+        }
+        for (const [field, same] of Object.entries(checks))
+          if (!same) differs[field] = (differs[field] ?? 0) + 1
+      }
+    }
+    console.log(
+      `pi parity: ${total - missing.length}/${total} resolve. Fields that differ (newer models.dev data is fine):`,
+      differs,
+    )
+    expect(missing).toEqual([])
+  })
+})
diff --git a/packages/ai-models/tests/rules.test.ts b/packages/ai-models/tests/rules.test.ts
new file mode 100644
index 0000000000..a5d22f9edb
--- /dev/null
+++ b/packages/ai-models/tests/rules.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest'
+import {
+  inputModalities,
+  modelHints,
+  normalizeModelId,
+  reasoningMapFrom,
+  takesBudget,
+} from '../scripts/rules'
+
+const completions = { api: 'openai-completions', baseUrl: 'x' } as const
+const messages = { api: 'anthropic-messages', baseUrl: 'x' } as const
+
+describe('reasoningMapFrom (models.dev reasoning_options to a level map)', () => {
+  it('maps effort values to their levels, and none to off', () => {
+    expect(
+      reasoningMapFrom([
+        { type: 'effort', values: ['none', 'low', 'medium', 'high', 'xhigh'] },
+      ]),
+    ).toEqual({
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    })
+  })
+
+  it('cannot turn thinking off when effort has no none and there is no toggle', () => {
+    expect(
+      reasoningMapFrom([{ type: 'effort', values: ['low', 'high', 'max'] }]),
+    ).toMatchObject({ off: null, medium: null, max: 'max' })
+  })
+
+  it('a toggle next to effort gives the none off value (DeepSeek V4)', () => {
+    expect(
+      reasoningMapFrom([
+        { type: 'toggle' },
+        { type: 'effort', values: ['low', 'high', 'max'] },
+      ]),
+    ).toMatchObject({ off: 'none', low: 'low', high: 'high', max: 'max' })
+  })
+
+  it('a toggle alone gives only off and high', () => {
+    expect(reasoningMapFrom([{ type: 'toggle' }])).toEqual({
+      off: 'off',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+    })
+  })
+
+  it('a token budget or no options gives no map', () => {
+    expect(
+      reasoningMapFrom([{ type: 'budget_tokens', min: 1024 }]),
+    ).toBeUndefined()
+    expect(reasoningMapFrom([])).toBeUndefined()
+    expect(reasoningMapFrom(undefined)).toBeUndefined()
+    expect(takesBudget([{ type: 'toggle' }, { type: 'budget_tokens' }])).toBe(
+      true,
+    )
+  })
+})
+
+describe('modelHints', () => {
+  it('asks for reasoning_content replay when the model interleaves it', () => {
+    expect(
+      modelHints(
+        { id: 'm', interleaved: { field: 'reasoning_content' } },
+        completions,
+        false,
+      ),
+    ).toEqual({ requiresReasoningContentOnAssistantMessages: true })
+  })
+
+  it('reads temperature support and adaptive-only Claude thinking', () => {
+    expect(
+      modelHints(
+        {
+          id: 'claude',
+          temperature: false,
+          reasoning_options: [{ type: 'effort', values: ['low', 'high'] }],
+        },
+        messages,
+        false,
+      ),
+    ).toEqual({ supportsTemperature: false, forceAdaptiveThinking: true })
+  })
+
+  it('follows the effort option for reasoning_effort when the row asks for it', () => {
+    const effort = {
+      id: 'm',
+      reasoning_options: [{ type: 'effort', values: ['low'] }],
+    }
+    expect(modelHints(effort, completions, true)).toEqual({
+      supportsReasoningEffort: true,
+    })
+    expect(modelHints({ id: 'm' }, completions, true)).toEqual({
+      supportsReasoningEffort: false,
+    })
+  })
+})
+
+describe('ids and inputs', () => {
+  it('normalizes ids so the same model matches across providers', () => {
+    expect(normalizeModelId('anthropic/claude-opus-4.5')).toBe(
+      'claude-opus-4-5',
+    )
+    expect(normalizeModelId('accounts/fireworks/models/kimi-k2p6')).toBe(
+      'kimi-k2-6',
+    )
+    expect(normalizeModelId('openai/gpt-5:batch')).toBe('gpt-5')
+  })
+
+  it('maps input kinds and keeps text as the fallback', () => {
+    expect(inputModalities(['text', 'image', 'pdf'])).toEqual([
+      'text',
+      'image',
+      'document',
+    ])
+    expect(inputModalities(['weird'])).toEqual(['text'])
+  })
+})
diff --git a/packages/ai-models/tsconfig.json b/packages/ai-models/tsconfig.json
new file mode 100644
index 0000000000..f27905e257
--- /dev/null
+++ b/packages/ai-models/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src", "tests", "scripts"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/ai-models/vite.config.ts b/packages/ai-models/vite.config.ts
new file mode 100644
index 0000000000..5f7506e7bb
--- /dev/null
+++ b/packages/ai-models/vite.config.ts
@@ -0,0 +1,43 @@
+import { readdirSync } from 'node:fs'
+import { defineConfig, mergeConfig } from 'vitest/config'
+import { tanstackViteConfig } from '@tanstack/vite-config'
+import packageJson from './package.json'
+
+// One entry per provider file, so each one is its own subpath export.
+const providerEntries = readdirSync('./src/providers')
+  .filter((file) => file.endsWith('.ts'))
+  .map((file) => `./src/providers/${file}`)
+
+const config = defineConfig({
+  test: {
+    name: packageJson.name,
+    dir: './',
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'lcov'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        'tests/',
+        'scripts/',
+        '**/*.test.ts',
+        '**/*.config.ts',
+        '**/types.ts',
+      ],
+      include: ['src/**/*.ts'],
+    },
+  },
+})
+
+export default mergeConfig(
+  config,
+  tanstackViteConfig({
+    entry: ['./src/index.ts', ...providerEntries],
+    srcDir: './src',
+    cjs: false,
+  }),
+)
diff --git a/packages/ai-ollama/src/model-reasoning.ts b/packages/ai-ollama/src/model-reasoning.ts
new file mode 100644
index 0000000000..c3e404fec3
--- /dev/null
+++ b/packages/ai-ollama/src/model-reasoning.ts
@@ -0,0 +1,445 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type OllamaModelReasoningByName = {
+  'deepseek-r1:latest': { levels: 'off' | 'high'; budget: false }
+  'deepseek-r1:1.5b': { levels: 'off' | 'high'; budget: false }
+  'deepseek-r1:7b': { levels: 'off' | 'high'; budget: false }
+  'deepseek-r1:8b': { levels: 'off' | 'high'; budget: false }
+  'deepseek-r1:32b': { levels: 'off' | 'high'; budget: false }
+  'deepseek-r1:70b': { levels: 'off' | 'high'; budget: false }
+  'deepseek-r1:671b': { levels: 'off' | 'high'; budget: false }
+  'deepseek-v3.1:latest': { levels: 'off' | 'high'; budget: false }
+  'deepseek-v3.1:671b': { levels: 'off' | 'high'; budget: false }
+  'deepseek-v3.1:671b-cloud': { levels: 'off' | 'high'; budget: false }
+  'gpt-oss:latest': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'gpt-oss:20b': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'gpt-oss:120b': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'qwen3:latest': { levels: 'off' | 'high'; budget: false }
+  'qwen3:0.6b': { levels: 'off' | 'high'; budget: false }
+  'qwen3:1.7b': { levels: 'off' | 'high'; budget: false }
+  'qwen3:4b': { levels: 'off' | 'high'; budget: false }
+  'qwen3:8b': { levels: 'off' | 'high'; budget: false }
+  'qwen3:14b': { levels: 'off' | 'high'; budget: false }
+  'qwen3:30b': { levels: 'off' | 'high'; budget: false }
+  'qwen3:32b': { levels: 'off' | 'high'; budget: false }
+  'qwen3:235b': { levels: 'off' | 'high'; budget: false }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const OLLAMA_MODEL_REASONING: Readonly<Record<string, ModelReasoning>> =
+  {
+    'athene-v2:latest': false,
+    'athene-v2:72b': false,
+    'aya:latest': false,
+    'aya:8b': false,
+    'aya:35b': false,
+    'codegemma:latest': false,
+    'codegemma:2b': false,
+    'codegemma:7b': false,
+    'codellama:latest': false,
+    'codellama:7b': false,
+    'codellama:13b': false,
+    'codellama:34b': false,
+    'codellama:70b': false,
+    'command-r-plus:latest': false,
+    'command-r-plus:104b': false,
+    'command-r:latest': false,
+    'command-r:35b': false,
+    'command-r7b:latest': false,
+    'command-r7b:7b': false,
+    'deepseek-coder-v2:latest': false,
+    'deepseek-coder-v2:16b': false,
+    'deepseek-coder-v2:236b': false,
+    'deepseek-ocr:latest': false,
+    'deepseek-ocr:3b': false,
+    'deepseek-r1:latest': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'deepseek-r1:1.5b': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'deepseek-r1:7b': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'deepseek-r1:8b': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'deepseek-r1:32b': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'deepseek-r1:70b': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'deepseek-r1:671b': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'deepseek-v3.1:latest': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'deepseek-v3.1:671b': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'deepseek-v3.1:671b-cloud': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'devstral:latest': false,
+    'devstral:24b': false,
+    'dolphin3:latest': false,
+    'dolphin3:8b': false,
+    'exaone3.5:latest': false,
+    'exaone3.5:2.4b': false,
+    'exaone3.5:7.8b': false,
+    'exaone3.5:32b': false,
+    'falcon2:latest': false,
+    'falcon2:11b': false,
+    'falcon3:latest': false,
+    'falcon3:1b': false,
+    'falcon3:3b': false,
+    'falcon3:7b': false,
+    'falcon3:10b': false,
+    'firefunction-v2:latest': false,
+    'firefunction-v2:70b': false,
+    'gemma:latest': false,
+    'gemma:2b': false,
+    'gemma:7b': false,
+    'gemma2:latest': false,
+    'gemma2:2b': false,
+    'gemma2:9b': false,
+    'gemma2:27b': false,
+    'gemma3:latest': false,
+    'gemma3:270m': false,
+    'gemma3:1b': false,
+    'gemma3:4b': false,
+    'gemma3:12b': false,
+    'gemma3:27b': false,
+    'gpt-oss:latest': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+      },
+      budget: false,
+    },
+    'gpt-oss:20b': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+      },
+      budget: false,
+    },
+    'gpt-oss:120b': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+      },
+      budget: false,
+    },
+    'granite3-dense:latest': false,
+    'granite3-dense:2b': false,
+    'granite3-dense:8b': false,
+    'granite3-guardian:latest': false,
+    'granite3-guardian:2b': false,
+    'granite3-guardian:8b': false,
+    'granite3-moe:latest': false,
+    'granite3-moe:1b': false,
+    'granite3-moe:3b': false,
+    'granite3.1-dense:latest': false,
+    'granite3.1-dense:2b': false,
+    'granite3.1-dense:8b': false,
+    'granite3.1-moe:latest': false,
+    'granite3.1-moe:1b': false,
+    'granite3.1-moe:3b': false,
+    'llama-guard3:latest': false,
+    'llama-guard3:1b': false,
+    'llama-guard3:8b': false,
+    'llama2:latest': false,
+    'llama2:7b': false,
+    'llama2:13b': false,
+    'llama2:70b': false,
+    'llama3-chatqa:latest': false,
+    'llama3-chatqa:8b': false,
+    'llama3-chatqa:70b': false,
+    'llama3-gradient:latest': false,
+    'llama3-gradient:8b': false,
+    'llama3-gradient:70b': false,
+    'llama3.1:latest': false,
+    'llama3.1:8b': false,
+    'llama3.1:70b': false,
+    'llama3.1:405b': false,
+    'llama3.2:latest': false,
+    'llama3.2:1b': false,
+    'llama3.2:3b': false,
+    'llama3.2:11b': false,
+    'llama3.2:90b': false,
+    'llama3.3:latest': false,
+    'llama3.3:70b': false,
+    'llama3:latest': false,
+    'llama3:8b': false,
+    'llama3:70b': false,
+    'llama4:latest': false,
+    'llama4:16x17b': false,
+    'llama4:128x17b': false,
+    'llava-llama3:latest': false,
+    'llava-llama3:8b': false,
+    'llava-phi3:latest': false,
+    'llava-phi3:8b': false,
+    'llava:latest': false,
+    'llava:7b': false,
+    'llava:13b': false,
+    'llava:34b': false,
+    'marco-o1:latest': false,
+    'marco-o1:7b': false,
+    'mistral-large:latest': false,
+    'mistral-large:123b': false,
+    'mistral-nemo:latest': false,
+    'mistral-nemo:12b': false,
+    'mistral-small:latest': false,
+    'mistral-small:22b': false,
+    'mistral-small:24b': false,
+    'mistral:latest': false,
+    'mistral:7b': false,
+    'mixtral:latest': false,
+    'mixtral:8x7b': false,
+    'mixtral:8x22b': false,
+    'moondream:latest': false,
+    'moondream:1.8b': false,
+    'nemotron-mini:latest': false,
+    'nemotron-mini:4b': false,
+    'nemotron:latest': false,
+    'nemotron:70b': false,
+    'olmo2:latest': false,
+    'olmo2:7b': false,
+    'olmo2:13b': false,
+    'opencoder:latest': false,
+    'opencoder:1.5b': false,
+    'opencoder:8b': false,
+    'openhermes:latest': false,
+    'openhermes:v2': false,
+    'openhermes:v2.5': false,
+    'phi3:latest': false,
+    'phi3:8b': false,
+    'phi3:14b': false,
+    'phi4:latest': false,
+    'phi4:14b': false,
+    'qwen:latest': false,
+    'qwen:0.5b': false,
+    'qwen:1.8b': false,
+    'qwen:4b': false,
+    'qwen:7b': false,
+    'qwen:14b': false,
+    'qwen:32b': false,
+    'qwen:72b': false,
+    'qwen:110b': false,
+    'qwen2.5-coder:latest': false,
+    'qwen2.5-coder:0.5b': false,
+    'qwen2.5-coder:1.5b': false,
+    'qwen2.5-coder:3b': false,
+    'qwen2.5-coder:7b': false,
+    'qwen2.5-coder:14b': false,
+    'qwen2.5-coder:32b': false,
+    'qwen2.5:latest': false,
+    'qwen2.5:0.5b': false,
+    'qwen2.5:1.5b': false,
+    'qwen2.5:3b': false,
+    'qwen2.5:7b': false,
+    'qwen2.5:32b': false,
+    'qwen2.5:72b': false,
+    'qwen2:latest': false,
+    'qwen2:0.5b': false,
+    'qwen2:1.5b': false,
+    'qwen2:7b': false,
+    'qwen2:72b': false,
+    'qwen3:latest': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'qwen3:0.6b': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'qwen3:1.7b': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'qwen3:4b': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'qwen3:8b': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'qwen3:14b': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'qwen3:30b': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'qwen3:32b': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'qwen3:235b': {
+      map: {
+        off: 'false',
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'true',
+      },
+      budget: false,
+    },
+    'qwq:latest': false,
+    'qwq:32b': false,
+    'sailor2:latest': false,
+    'sailor2:8b': false,
+    'sailor2:20b': false,
+    'shieldgemma:latest': false,
+    'shieldgemma:2b': false,
+    'shieldgemma:9b': false,
+    'shieldgemma:27b': false,
+    'smalltinker:latest': false,
+    'smalltinker:3b': false,
+    'smollm:latest': false,
+    'smollm:135m': false,
+    'smollm:360m': false,
+    'smollm:1.7b': false,
+    'tinyllama:latest': false,
+    'tinyllama:1.1b': false,
+    'tulu3:latest': false,
+    'tulu3:8b': false,
+    'tulu3:70b': false,
+  }
diff --git a/packages/ai-openai/src/model-reasoning.ts b/packages/ai-openai/src/model-reasoning.ts
new file mode 100644
index 0000000000..ff96f6cb87
--- /dev/null
+++ b/packages/ai-openai/src/model-reasoning.ts
@@ -0,0 +1,579 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type OpenAIModelReasoningByName = {
+  'gpt-6.1-sol': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'gpt-6.1-sol-pro': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'gpt-6-luna': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'gpt-6-luna-pro': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'gpt-6-sol': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'gpt-6-sol-pro': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'gpt-6-astra': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'gpt-6-astra-pro': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'gpt-5.6-luna-pro': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'gpt-5.6-sol-pro': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'gpt-5.6-terra-pro': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'gpt-5.2': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'gpt-5.2-pro': { levels: 'medium' | 'high' | 'xhigh'; budget: false }
+  'gpt-5.2-chat-latest': { levels: 'medium'; budget: false }
+  'gpt-5.1': { levels: 'off' | 'low' | 'medium' | 'high'; budget: false }
+  'gpt-5.1-codex': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'gpt-5': { levels: 'minimal' | 'low' | 'medium' | 'high'; budget: false }
+  'gpt-5-mini': { levels: 'minimal' | 'low' | 'medium' | 'high'; budget: false }
+  'gpt-5-nano': { levels: 'minimal' | 'low' | 'medium' | 'high'; budget: false }
+  'gpt-5-pro': { levels: 'high'; budget: false }
+  'gpt-5-codex': { levels: 'low' | 'medium' | 'high'; budget: false }
+  o3: { levels: 'low' | 'medium' | 'high'; budget: false }
+  'o3-pro': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'o3-mini': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'o4-mini': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'gpt-5.1-codex-mini': { levels: 'low' | 'medium' | 'high'; budget: false }
+  o1: { levels: 'low' | 'medium' | 'high'; budget: false }
+  'o1-pro': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'gpt-5.6': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'gpt-5.6-sol': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'gpt-5.6-terra': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'gpt-5.6-luna': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'gpt-5.5': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'gpt-5.5-pro': { levels: 'medium' | 'high' | 'xhigh'; budget: false }
+  'gpt-5.4-mini': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'gpt-5.4-nano': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'gpt-5.4-image-2': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'gpt-chat-latest': { levels: 'low' | 'medium' | 'high'; budget: false }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const OPENAI_MODEL_REASONING: Readonly<Record<string, ModelReasoning>> =
+  {
+    'gpt-6.1-sol': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'gpt-6.1-sol-pro': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'gpt-6-luna': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'gpt-6-luna-pro': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'gpt-6-sol': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'gpt-6-sol-pro': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'gpt-6-astra': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'gpt-6-astra-pro': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'gpt-5.6-luna-pro': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'gpt-5.6-sol-pro': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'gpt-5.6-terra-pro': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'gpt-5.2': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: null,
+      },
+      budget: false,
+    },
+    'gpt-5.2-pro': {
+      map: {
+        off: null,
+        minimal: null,
+        low: null,
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: null,
+      },
+      budget: false,
+    },
+    'gpt-5.2-chat-latest': {
+      map: {
+        off: null,
+        minimal: null,
+        low: null,
+        medium: 'medium',
+        high: null,
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gpt-5.1': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gpt-5.1-codex': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gpt-5': {
+      map: {
+        off: null,
+        minimal: 'minimal',
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gpt-5-mini': {
+      map: {
+        off: null,
+        minimal: 'minimal',
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gpt-5-nano': {
+      map: {
+        off: null,
+        minimal: 'minimal',
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gpt-5-pro': {
+      map: {
+        off: null,
+        minimal: null,
+        low: null,
+        medium: null,
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gpt-5-codex': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    o3: {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'o3-pro': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'o3-mini': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'o4-mini': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gpt-4.1': false,
+    'gpt-4.1-mini': false,
+    'gpt-4.1-nano': false,
+    'gpt-4': false,
+    'gpt-4-turbo': false,
+    'gpt-4o': false,
+    'gpt-4o-mini': false,
+    'gpt-3.5-turbo': false,
+    'gpt-audio': false,
+    'gpt-audio-mini': false,
+    'gpt-5-chat-latest': false,
+    'gpt-5.1-codex-mini': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    o1: {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'o1-pro': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+    'gpt-5.6': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'gpt-5.6-sol': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'gpt-5.6-terra': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'gpt-5.6-luna': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: 'max',
+      },
+      budget: false,
+    },
+    'gpt-5.5': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: null,
+      },
+      budget: false,
+    },
+    'gpt-5.5-pro': {
+      map: {
+        off: null,
+        minimal: null,
+        low: null,
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: null,
+      },
+      budget: false,
+    },
+    'gpt-5.4-mini': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: null,
+      },
+      budget: false,
+    },
+    'gpt-5.4-nano': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: null,
+      },
+      budget: false,
+    },
+    'gpt-5.4-image-2': {
+      map: {
+        off: 'none',
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: 'xhigh',
+        max: null,
+      },
+      budget: false,
+    },
+    'gpt-chat-latest': {
+      map: {
+        off: null,
+        minimal: null,
+        low: 'low',
+        medium: 'medium',
+        high: 'high',
+        xhigh: null,
+        max: null,
+      },
+      budget: false,
+    },
+  }
diff --git a/packages/ai-opencode/src/model-reasoning.ts b/packages/ai-opencode/src/model-reasoning.ts
new file mode 100644
index 0000000000..901394e3bf
--- /dev/null
+++ b/packages/ai-opencode/src/model-reasoning.ts
@@ -0,0 +1,83 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type OpenCodeModelReasoningByName = {
+  'anthropic/claude-opus-4-5': {
+    levels: 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'anthropic/claude-sonnet-4-5': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'openai/gpt-5.2': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.1-codex': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'opencode/claude-sonnet-4-5': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'opencode/gpt-5.1-codex': { levels: 'low' | 'medium' | 'high'; budget: false }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const OPENCODE_MODEL_REASONING: Readonly<
+  Record<string, ModelReasoning>
+> = {
+  'anthropic/claude-opus-4-5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: true,
+  },
+  'anthropic/claude-sonnet-4-5': { budget: true },
+  'openai/gpt-5.2': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.1-codex': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'opencode/claude-sonnet-4-5': { budget: true },
+  'opencode/gpt-5.1-codex': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+}
diff --git a/packages/ai-openrouter/src/model-reasoning.ts b/packages/ai-openrouter/src/model-reasoning.ts
new file mode 100644
index 0000000000..c652ce7de6
--- /dev/null
+++ b/packages/ai-openrouter/src/model-reasoning.ts
@@ -0,0 +1,3840 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type OpenRouterModelReasoningByName = {
+  '~anthropic/claude-fable-latest': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  '~anthropic/claude-haiku-latest': { levels: 'off' | 'high'; budget: false }
+  '~anthropic/claude-opus-latest': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  '~anthropic/claude-sonnet-latest': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  '~deepseek/deepseek-flash-latest': {
+    levels: 'off' | 'low' | 'high' | 'max'
+    budget: false
+  }
+  '~deepseek/deepseek-pro-latest': {
+    levels: 'off' | 'low' | 'high' | 'max'
+    budget: false
+  }
+  '~deepseek/deepseek-v4-flash-latest': {
+    levels: 'off' | 'low' | 'high' | 'max'
+    budget: false
+  }
+  '~google/gemini-flash-latest': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  '~google/gemini-pro-latest': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  '~moonshotai/kimi-latest': {
+    levels: 'off' | 'low' | 'high' | 'max'
+    budget: false
+  }
+  '~openai/gpt-astra-latest': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  '~openai/gpt-luna-latest': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  '~openai/gpt-mini-latest': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  '~openai/gpt-sol-latest': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  '~openai/gpt-terra-latest': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  '~x-ai/grok-latest': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  '~z-ai/glm-flash-latest': { levels: 'low' | 'high' | 'max'; budget: false }
+  '~z-ai/glm-latest': { levels: 'low' | 'high' | 'max'; budget: false }
+  'aion-labs/aion-2.0': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'aion-labs/aion-3.0': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'aion-labs/aion-3.0-mini': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'aion-labs/aion-3.5': { levels: 'low' | 'high' | 'max'; budget: false }
+  'aion-labs/aion-3.5-mini': { levels: 'low' | 'high' | 'max'; budget: false }
+  'amazon/nova-2-lite-v1': { levels: 'off' | 'high'; budget: false }
+  'anthropic/claude-fable-5': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'anthropic/claude-fable-5:batch': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'anthropic/claude-fable-5.1': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'anthropic/claude-fable-5.1:batch': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'anthropic/claude-haiku-4.5': { levels: 'off' | 'high'; budget: false }
+  'anthropic/claude-haiku-4.5:batch': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'anthropic/claude-opus-4.1': { levels: 'off' | 'high'; budget: false }
+  'anthropic/claude-opus-4.1:batch': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'anthropic/claude-opus-4.5': { levels: 'off' | 'high'; budget: false }
+  'anthropic/claude-opus-4.5:batch': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'anthropic/claude-opus-4.6': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'max'
+    budget: true
+  }
+  'anthropic/claude-opus-4.6:batch': {
+    levels: 'low' | 'medium' | 'high' | 'max'
+    budget: false
+  }
+  'anthropic/claude-opus-4.7': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'anthropic/claude-opus-4.7:batch': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'anthropic/claude-opus-4.8': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'anthropic/claude-opus-4.8:batch': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'anthropic/claude-opus-5': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'anthropic/claude-opus-5:batch': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'anthropic/claude-opus-5.5': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'anthropic/claude-opus-5.5:batch': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'anthropic/claude-sonnet-4': { levels: 'off' | 'high'; budget: false }
+  'anthropic/claude-sonnet-4.5': { levels: 'off' | 'high'; budget: false }
+  'anthropic/claude-sonnet-4.5:batch': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'anthropic/claude-sonnet-4.6': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'max'
+    budget: false
+  }
+  'anthropic/claude-sonnet-4.6:batch': {
+    levels: 'low' | 'medium' | 'high' | 'max'
+    budget: false
+  }
+  'anthropic/claude-sonnet-5': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'anthropic/claude-sonnet-5:batch': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'anthropic/claude-sonnet-5.5': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'anthropic/claude-sonnet-5.5:batch': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'arcee-ai/trinity-large-thinking': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'baidu/ernie-4.5-vl-424b-a47b': { levels: 'off' | 'high'; budget: false }
+  'bytedance-seed/seed-1.6': { levels: 'off' | 'high'; budget: false }
+  'bytedance-seed/seed-1.6-flash': { levels: 'off' | 'high'; budget: false }
+  'bytedance-seed/seed-2-1-turbo': { levels: 'off' | 'high'; budget: false }
+  'bytedance-seed/seed-2.0-code': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'bytedance-seed/seed-2.0-lite': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'bytedance-seed/seed-2.0-mini': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'cohere/command-a-plus': { levels: 'off' | 'high'; budget: false }
+  'cohere/north-mini-code:free': { levels: 'off' | 'high'; budget: false }
+  'deepseek/deepseek-chat-v3.1': { levels: 'off' | 'high'; budget: false }
+  'deepseek/deepseek-r1': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'deepseek/deepseek-r1-0528': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'deepseek/deepseek-v3.1-terminus': { levels: 'off' | 'high'; budget: false }
+  'deepseek/deepseek-v3.2': { levels: 'off' | 'high'; budget: false }
+  'deepseek/deepseek-v3.2-exp': { levels: 'off' | 'high'; budget: false }
+  'deepseek/deepseek-v4-flash': {
+    levels: 'off' | 'high' | 'xhigh'
+    budget: false
+  }
+  'deepseek/deepseek-v4-flash-0731': {
+    levels: 'off' | 'low' | 'high' | 'max'
+    budget: false
+  }
+  'deepseek/deepseek-v4-flash-vision-exp': {
+    levels: 'off' | 'low' | 'high' | 'max'
+    budget: false
+  }
+  'deepseek/deepseek-v4-pro': {
+    levels: 'off' | 'high' | 'xhigh'
+    budget: false
+  }
+  'deepseek/deepseek-v4-pro-0813': {
+    levels: 'off' | 'low' | 'high' | 'max'
+    budget: false
+  }
+  'deepseek/deepseek-v4.1-flash': {
+    levels: 'off' | 'low' | 'high' | 'max'
+    budget: false
+  }
+  'deepseek/deepseek-v4.1-flash:batch': {
+    levels: 'low' | 'high' | 'max'
+    budget: false
+  }
+  'dots-studio/dots-3-note-preview:free': {
+    levels: 'off' | 'high'
+    budget: false
+  }
+  'fireworks/ember-1': { levels: 'off' | 'low' | 'high' | 'max'; budget: false }
+  'google/gemini-2.5-flash': { levels: 'off' | 'high'; budget: false }
+  'google/gemini-2.5-flash-lite': { levels: 'off' | 'high'; budget: false }
+  'google/gemini-2.5-flash-lite:batch': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-2.5-flash:batch': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-2.5-pro': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'google/gemini-2.5-pro-preview': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'google/gemini-2.5-pro:batch': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3-flash-preview': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3-flash-preview:batch': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3-pro-image': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3-pro-image-preview': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.1-flash-image': {
+    levels: 'off' | 'minimal' | 'high'
+    budget: false
+  }
+  'google/gemini-3.1-flash-image-preview': {
+    levels: 'off' | 'minimal' | 'high'
+    budget: false
+  }
+  'google/gemini-3.1-flash-lite': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.1-flash-lite-image': {
+    levels: 'off' | 'minimal' | 'high'
+    budget: false
+  }
+  'google/gemini-3.1-flash-lite-preview': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.1-flash-lite:batch': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.1-pro-preview': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.1-pro-preview-customtools': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.1-pro-preview:batch': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.5-flash': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.5-flash-lite': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.5-flash-lite:batch': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.5-flash:batch': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.6-flash': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.6-flash:batch': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.7-flash': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.7-flash:batch': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.8-flash': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemini-3.8-flash:batch': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemma-4-26b-a4b-it': { levels: 'off' | 'high'; budget: false }
+  'google/gemma-4-26b-a4b-it:free': { levels: 'off' | 'high'; budget: false }
+  'google/gemma-4-31b-it': { levels: 'off' | 'high'; budget: false }
+  'google/gemma-4-31b-it:free': { levels: 'off' | 'high'; budget: false }
+  'ibm-granite/granite-4.2-8b': {
+    levels: 'off' | 'low' | 'high'
+    budget: false
+  }
+  'inception/mercury-2': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'inception/mercury-2.5': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'inclusionai/ling-3.0-flash': { levels: 'off' | 'high'; budget: false }
+  'inclusionai/ling-3.0-flash-fin': { levels: 'off' | 'high'; budget: false }
+  'inclusionai/ling-3.0-flash-sante:free': {
+    levels: 'off' | 'high'
+    budget: false
+  }
+  'inclusionai/ling-3.0-flash-vl': { levels: 'off' | 'high'; budget: false }
+  'liquid/lfm-2.5-2.6b:free': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'meituan/longcat-2.0': { levels: 'off' | 'high'; budget: true }
+  'meta/muse-glimmer-30b': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'meta/muse-spark-1.1': {
+    levels: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'meta/muse-spark-1.2': {
+    levels: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'meta/muse-spark-1.2-contributor': {
+    levels: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'meta/muse-spark-1.3': {
+    levels: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'meta/muse-spark-1.3-contributor': {
+    levels: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'minimax/minimax-m1': { levels: 'off' | 'high'; budget: false }
+  'minimax/minimax-m2': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'minimax/minimax-m2.1': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'minimax/minimax-m2.5': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'minimax/minimax-m2.7': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'minimax/minimax-m3': { levels: 'off' | 'high'; budget: false }
+  'mistralai/mistral-medium-3-5': { levels: 'off' | 'high'; budget: false }
+  'mistralai/mistral-medium-3-5:batch': {
+    levels: 'off' | 'high'
+    budget: false
+  }
+  'mistralai/mistral-small-2603': { levels: 'off' | 'high'; budget: false }
+  'mistralai/mistral-small-2603:batch': {
+    levels: 'off' | 'high'
+    budget: false
+  }
+  'moonshotai/kimi-k2-thinking': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'moonshotai/kimi-k2.5': { levels: 'off' | 'high'; budget: false }
+  'moonshotai/kimi-k2.6': { levels: 'off' | 'high'; budget: false }
+  'moonshotai/kimi-k2.7-code': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'moonshotai/kimi-k3': {
+    levels: 'off' | 'low' | 'high' | 'max'
+    budget: false
+  }
+  'moonshotai/kimi-k3:batch': { levels: 'low' | 'high' | 'max'; budget: false }
+  'nex-agi/nex-n2.5-mini': { levels: 'off' | 'medium' | 'high'; budget: false }
+  'nex-agi/nex-n2.5-pro': { levels: 'off' | 'medium' | 'high'; budget: false }
+  'nousresearch/hermes-4-405b': { levels: 'off' | 'high'; budget: false }
+  'nvidia/nemotron-3-nano-30b-a3b': { levels: 'off' | 'high'; budget: false }
+  'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free': {
+    levels: 'off' | 'high'
+    budget: true
+  }
+  'nvidia/nemotron-3-super-120b-a12b': {
+    levels: 'off' | 'low' | 'medium'
+    budget: true
+  }
+  'nvidia/nemotron-3-super-120b-a12b:free': {
+    levels: 'off' | 'low' | 'medium'
+    budget: true
+  }
+  'nvidia/nemotron-3-ultra-550b-a55b': {
+    levels: 'off' | 'medium' | 'high'
+    budget: true
+  }
+  'nvidia/nemotron-3-ultra-550b-a55b:free': {
+    levels: 'off' | 'medium' | 'high'
+    budget: true
+  }
+  'nvidia/nemotron-3.5-content-safety': {
+    levels: 'off' | 'high'
+    budget: false
+  }
+  'nvidia/nemotron-3.5-content-safety:free': {
+    levels: 'off' | 'high'
+    budget: false
+  }
+  'nvidia/nemotron-3.5-lightning': { levels: 'off' | 'high'; budget: false }
+  'nvidia/nemotron-3.5-lightning:free': {
+    levels: 'off' | 'high'
+    budget: false
+  }
+  'openai/gpt-5': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5-image': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5-image-mini': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5-mini': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5-mini:batch': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5-nano': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5-nano:batch': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5-pro': { levels: 'high'; budget: false }
+  'openai/gpt-5-pro:batch': { levels: 'high'; budget: false }
+  'openai/gpt-5:batch': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5.1': { levels: 'off' | 'low' | 'medium' | 'high'; budget: false }
+  'openai/gpt-5.1-codex': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'openai/gpt-5.1-codex-max': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.1-codex-mini': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5.1:batch': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5.2': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.2-codex': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.2-pro': { levels: 'medium' | 'high' | 'xhigh'; budget: false }
+  'openai/gpt-5.2-pro:batch': {
+    levels: 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.2:batch': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.3-codex': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.4': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.4-image-2': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.4-mini': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.4-mini:batch': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.4-nano': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.4-nano:batch': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.4-pro': { levels: 'medium' | 'high' | 'xhigh'; budget: false }
+  'openai/gpt-5.4-pro:batch': {
+    levels: 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.4:batch': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.5': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.5-pro': { levels: 'medium' | 'high' | 'xhigh'; budget: false }
+  'openai/gpt-5.5-pro:batch': {
+    levels: 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.5:batch': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.6-luna': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-luna-pro': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-luna-pro:batch': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-luna:batch': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-sol': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-sol-pro': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-sol-pro:batch': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-sol:batch': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-terra': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-terra-pro': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-terra-pro:batch': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-terra:batch': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-astra': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-astra-pro': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-astra-pro:batch': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-astra:batch': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-luna': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-luna-pro': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-luna-pro:batch': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-luna:batch': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-sol': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-sol-pro': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-sol-pro:batch': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-sol:batch': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6.1-sol': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6.1-sol-pro': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6.1-sol-pro:batch': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6.1-sol:batch': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-oss-120b': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'openai/gpt-oss-120b:batch': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-oss-20b': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'openai/gpt-oss-20b:batch': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-oss-safeguard-20b': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/o1': { levels: 'off' | 'high'; budget: false }
+  'openai/o1-pro': { levels: 'off' | 'high'; budget: false }
+  'openai/o3': { levels: 'off' | 'high'; budget: false }
+  'openai/o3-mini': { levels: 'off' | 'high'; budget: false }
+  'openai/o3-mini-high': { levels: 'high'; budget: false }
+  'openai/o3-mini:batch': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/o3-pro': { levels: 'off' | 'high'; budget: false }
+  'openai/o3:batch': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/o4-mini': { levels: 'off' | 'high'; budget: false }
+  'openai/o4-mini-high': { levels: 'high'; budget: false }
+  'openai/o4-mini:batch': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'perceptron/perceptron-mk1': { levels: 'off' | 'high'; budget: false }
+  'perceptron/perceptron-mk1.5': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'perplexity/sonar-deep-research': { levels: 'off' | 'high'; budget: false }
+  'perplexity/sonar-pro-search': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'perplexity/sonar-reasoning-pro': { levels: 'off' | 'high'; budget: false }
+  'poolside/laguna-s-2.1': { levels: 'off' | 'high'; budget: false }
+  'poolside/laguna-s-2.1:free': { levels: 'off' | 'high'; budget: false }
+  'poolside/laguna-xs-2.1': { levels: 'off' | 'high'; budget: false }
+  'poolside/laguna-xs-2.1:free': { levels: 'off' | 'high'; budget: false }
+  'prism-ml/ternary-bonsai-2-27b': {
+    levels: 'off' | 'medium' | 'xhigh'
+    budget: false
+  }
+  'qwen/qwen3-14b': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3-235b-a22b': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3-235b-a22b-thinking-2507': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'qwen/qwen3-30b-a3b': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3-30b-a3b-thinking-2507': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'qwen/qwen3-32b': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3-8b': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3-max-thinking': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3-next-80b-a3b-thinking': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'qwen/qwen3-vl-235b-a22b-thinking': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'qwen/qwen3-vl-30b-a3b-thinking': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'qwen/qwen3-vl-8b-thinking': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'qwen/qwen3.5-122b-a10b': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3.5-27b': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3.5-35b-a3b': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3.5-397b-a17b': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3.5-9b': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3.5-flash-02-23': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3.5-plus-02-15': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3.5-plus-20260420': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3.6-27b': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3.6-35b-a3b': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3.6-flash': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3.6-max-preview': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3.6-plus': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3.7-flash': { levels: 'off' | 'high'; budget: true }
+  'qwen/qwen3.7-max': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3.7-plus': { levels: 'off' | 'high'; budget: false }
+  'qwen/qwen3.8-2.4t-a95b': {
+    levels: 'low' | 'medium' | 'xhigh'
+    budget: false
+  }
+  'qwen/qwen3.8-27b': {
+    levels: 'off' | 'low' | 'medium' | 'xhigh'
+    budget: false
+  }
+  'qwen/qwen3.8-27b:free': {
+    levels: 'off' | 'low' | 'medium' | 'xhigh'
+    budget: false
+  }
+  'qwen/qwen3.8-flash': { levels: 'off' | 'high'; budget: true }
+  'qwen/qwen3.8-max-0902': {
+    levels: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'qwen/qwen3.8-max-prime': {
+    levels: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'qwen/qwen3.8-omni-flash': { levels: 'off' | 'high'; budget: true }
+  'rekaai/reka-flash-3': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'sakana/fugu-max': { levels: 'high' | 'xhigh' | 'max'; budget: false }
+  'sakana/fugu-ultra': { levels: 'high' | 'xhigh' | 'max'; budget: false }
+  'sakana/fugu-ultra-v2': { levels: 'high' | 'xhigh' | 'max'; budget: false }
+  'sakana/sakana-namazu': { levels: 'off' | 'high'; budget: false }
+  'stealth/space-bunny-alpha': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'stepfun/step-3.5-flash': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'stepfun/step-3.7-flash': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'tencent/hunyuan-a13b-instruct': { levels: 'off' | 'high'; budget: false }
+  'tencent/hy3': { levels: 'off' | 'low' | 'high'; budget: false }
+  'tencent/hy3-preview': { levels: 'off' | 'low' | 'high'; budget: false }
+  'tencent/hy4-preview': { levels: 'off' | 'low' | 'high'; budget: false }
+  'thinkingmachines/inkling': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'max'
+    budget: false
+  }
+  'thinkingmachines/inkling-small': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'max'
+    budget: false
+  }
+  'thinkingmachines/inkling-small:free': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'max'
+    budget: false
+  }
+  'thinkingmachines/inkling:free': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'max'
+    budget: false
+  }
+  'upstage/solar-mini4': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'upstage/solar-pro-3': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'upstage/solar-pro4': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'x-ai/grok-4.20': { levels: 'off' | 'high'; budget: false }
+  'x-ai/grok-4.20-multi-agent': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'x-ai/grok-4.3': { levels: 'off' | 'low' | 'medium' | 'high'; budget: false }
+  'x-ai/grok-4.3:batch': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'x-ai/grok-4.5': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'x-ai/grok-4.6': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'x-ai/grok-4.7': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'x-ai/grok-build-0.1': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'xiaomi/mimo-v2.5': { levels: 'off' | 'high'; budget: false }
+  'xiaomi/mimo-v2.5-pro': { levels: 'off' | 'high'; budget: false }
+  'xiaomi/mimo-v2.6-flash': { levels: 'off' | 'high'; budget: false }
+  'xiaomi/mimo-v2.6-pro': { levels: 'off' | 'high'; budget: false }
+  'xiaomi/mimo-v2.6-pro-ultraspeed': { levels: 'off' | 'high'; budget: false }
+  'z-ai/glm-4.5': { levels: 'off' | 'high'; budget: false }
+  'z-ai/glm-4.5-air': { levels: 'off' | 'high'; budget: false }
+  'z-ai/glm-4.5v': { levels: 'off' | 'high'; budget: false }
+  'z-ai/glm-4.6': { levels: 'off' | 'high'; budget: false }
+  'z-ai/glm-4.6v': { levels: 'off' | 'high'; budget: false }
+  'z-ai/glm-4.7': { levels: 'off' | 'high'; budget: false }
+  'z-ai/glm-4.7-flash': { levels: 'off' | 'high'; budget: false }
+  'z-ai/glm-5': { levels: 'off' | 'high'; budget: false }
+  'z-ai/glm-5-turbo': { levels: 'off' | 'high'; budget: false }
+  'z-ai/glm-5.1': { levels: 'off' | 'high'; budget: false }
+  'z-ai/glm-5.2': { levels: 'off' | 'high' | 'xhigh'; budget: false }
+  'z-ai/glm-5.3': { levels: 'low' | 'high' | 'max'; budget: false }
+  'z-ai/glm-5.3-flash': { levels: 'low' | 'high' | 'max'; budget: false }
+  'z-ai/glm-5.3-flash:batch': { levels: 'low' | 'high' | 'max'; budget: false }
+  'z-ai/glm-5.3-flashx': { levels: 'low' | 'high' | 'max'; budget: false }
+  'z-ai/glm-5.3-prime': { levels: 'low' | 'high' | 'max'; budget: false }
+  'z-ai/glm-5.3:batch': { levels: 'low' | 'high' | 'max'; budget: false }
+  'z-ai/glm-5v-turbo': { levels: 'off' | 'high'; budget: false }
+  'openrouter/auto': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const OPENROUTER_MODEL_REASONING: Readonly<
+  Record<string, ModelReasoning>
+> = {
+  '~anthropic/claude-fable-latest': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  '~anthropic/claude-haiku-latest': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  '~anthropic/claude-opus-latest': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  '~anthropic/claude-sonnet-latest': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  '~deepseek/deepseek-flash-latest': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  '~deepseek/deepseek-pro-latest': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  '~deepseek/deepseek-v4-flash-latest': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  '~google/gemini-flash-latest': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  '~google/gemini-pro-latest': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  '~moonshotai/kimi-latest': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  '~openai/gpt-astra-latest': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  '~openai/gpt-luna-latest': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  '~openai/gpt-mini-latest': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  '~openai/gpt-sol-latest': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  '~openai/gpt-terra-latest': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  '~x-ai/grok-latest': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  '~z-ai/glm-flash-latest': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  '~z-ai/glm-latest': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'aion-labs/aion-2.0': { budget: false },
+  'aion-labs/aion-3.0': { budget: false },
+  'aion-labs/aion-3.0-mini': { budget: false },
+  'aion-labs/aion-3.5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'aion-labs/aion-3.5-mini': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'aion-labs/aion-rp-llama-3.1-8b': false,
+  'amazon/nova-2-lite-v1': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'amazon/nova-lite-v1': false,
+  'amazon/nova-micro-v1': false,
+  'amazon/nova-premier-v1': false,
+  'amazon/nova-pro-v1': false,
+  'anthracite-org/magnum-v4-72b': false,
+  'anthropic/claude-fable-5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-fable-5:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-fable-5.1': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-fable-5.1:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-haiku-4.5': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'anthropic/claude-haiku-4.5:batch': { budget: false },
+  'anthropic/claude-opus-4.1': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'anthropic/claude-opus-4.1:batch': { budget: false },
+  'anthropic/claude-opus-4.5': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'anthropic/claude-opus-4.5:batch': { budget: false },
+  'anthropic/claude-opus-4.6': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: true,
+  },
+  'anthropic/claude-opus-4.6:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-opus-4.7': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-opus-4.7:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-opus-4.8': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-opus-4.8:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-opus-5': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-opus-5:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-opus-5.5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-opus-5.5:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-sonnet-4': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'anthropic/claude-sonnet-4.5': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'anthropic/claude-sonnet-4.5:batch': { budget: false },
+  'anthropic/claude-sonnet-4.6': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-sonnet-4.6:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-sonnet-5': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-sonnet-5:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-sonnet-5.5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-sonnet-5.5:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'arcee-ai/trinity-large-thinking': { budget: false },
+  'baidu/ernie-4.5-vl-424b-a47b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'bytedance-seed/seed-1.6': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'bytedance-seed/seed-1.6-flash': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'bytedance-seed/seed-2-1-turbo': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'bytedance-seed/seed-2.0-code': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'bytedance-seed/seed-2.0-lite': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'bytedance-seed/seed-2.0-mini': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'bytedance/ui-tars-1.5-7b': false,
+  'cognitivecomputations/dolphin-mistral-24b-venice-edition': false,
+  'cohere/command-a': false,
+  'cohere/command-a-plus': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'cohere/command-r-08-2024': false,
+  'cohere/command-r-plus-08-2024': false,
+  'cohere/command-r7b-12-2024': false,
+  'cohere/north-mini-code:free': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'deepseek/deepseek-chat': false,
+  'deepseek/deepseek-chat-v3-0324': false,
+  'deepseek/deepseek-chat-v3.1': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'deepseek/deepseek-r1': { budget: false },
+  'deepseek/deepseek-r1-0528': { budget: false },
+  'deepseek/deepseek-v3.1-terminus': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'deepseek/deepseek-v3.2': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'deepseek/deepseek-v3.2-exp': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'deepseek/deepseek-v4-flash': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'deepseek/deepseek-v4-flash-0731': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'deepseek/deepseek-v4-flash-vision-exp': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'deepseek/deepseek-v4-pro': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'deepseek/deepseek-v4-pro-0813': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'deepseek/deepseek-v4.1-flash': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'deepseek/deepseek-v4.1-flash:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'dots-studio/dots-3-note-preview:free': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'fireworks/ember-1': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'google/gemini-2.5-flash': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'google/gemini-2.5-flash-image': false,
+  'google/gemini-2.5-flash-lite': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'google/gemini-2.5-flash-lite:batch': { budget: false },
+  'google/gemini-2.5-flash:batch': { budget: false },
+  'google/gemini-2.5-pro': { budget: true },
+  'google/gemini-2.5-pro-preview': { budget: true },
+  'google/gemini-2.5-pro:batch': { budget: false },
+  'google/gemini-3-flash-preview': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3-flash-preview:batch': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3-pro-image': { budget: false },
+  'google/gemini-3-pro-image-preview': { budget: false },
+  'google/gemini-3.1-flash-image': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.1-flash-image-preview': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.1-flash-lite': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.1-flash-lite-image': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.1-flash-lite-preview': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.1-flash-lite:batch': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.1-pro-preview': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.1-pro-preview-customtools': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.1-pro-preview:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.5-flash': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.5-flash-lite': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.5-flash-lite:batch': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.5-flash:batch': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.6-flash': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.6-flash:batch': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.7-flash': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.7-flash:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.8-flash': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.8-flash:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemma-2-27b-it': false,
+  'google/gemma-3-12b-it': false,
+  'google/gemma-3-27b-it': false,
+  'google/gemma-3-4b-it': false,
+  'google/gemma-4-26b-a4b-it': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'google/gemma-4-26b-a4b-it:free': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'google/gemma-4-31b-it': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'google/gemma-4-31b-it:free': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'gryphe/mythomax-l2-13b': false,
+  'ibm-granite/granite-4.0-h-micro': false,
+  'ibm-granite/granite-4.2-8b': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'inception/mercury-2': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'inception/mercury-2.5': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'inclusionai/ling-3.0-flash': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'inclusionai/ling-3.0-flash-fin': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'inclusionai/ling-3.0-flash-sante:free': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'inclusionai/ling-3.0-flash-vl': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'inference-net/schematron-v2-small': false,
+  'inference-net/schematron-v2-turbo': false,
+  'kwaipilot/kat-coder-pro-v2.5': false,
+  'liquid/lfm-2.5-2.6b:free': { budget: false },
+  'mancer/weaver': false,
+  'meituan/longcat-2.0': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: true,
+  },
+  'meta-llama/llama-3.1-70b-instruct': false,
+  'meta-llama/llama-3.1-8b-instruct': false,
+  'meta-llama/llama-3.2-1b-instruct': false,
+  'meta-llama/llama-3.2-3b-instruct': false,
+  'meta-llama/llama-3.3-70b-instruct': false,
+  'meta-llama/llama-4-maverick': false,
+  'meta-llama/llama-4-scout': false,
+  'meta-llama/llama-guard-4-12b': false,
+  'meta/muse-glimmer-30b': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'meta/muse-spark-1.1': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'meta/muse-spark-1.2': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'meta/muse-spark-1.2-contributor': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'meta/muse-spark-1.3': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'meta/muse-spark-1.3-contributor': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'microsoft/phi-4': false,
+  'microsoft/wizardlm-2-8x22b': false,
+  'minimax/minimax-01': false,
+  'minimax/minimax-m1': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'minimax/minimax-m2': { budget: false },
+  'minimax/minimax-m2-her': false,
+  'minimax/minimax-m2.1': { budget: false },
+  'minimax/minimax-m2.5': { budget: false },
+  'minimax/minimax-m2.7': { budget: false },
+  'minimax/minimax-m3': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'mistralai/codestral-2508': false,
+  'mistralai/codestral-2508:batch': false,
+  'mistralai/devstral-2512': false,
+  'mistralai/ministral-14b-2512': false,
+  'mistralai/ministral-3b-2512': false,
+  'mistralai/ministral-8b-2512': false,
+  'mistralai/ministral-8b-2512:batch': false,
+  'mistralai/mistral-large': false,
+  'mistralai/mistral-large-2407': false,
+  'mistralai/mistral-large-2512': false,
+  'mistralai/mistral-large-2512:batch': false,
+  'mistralai/mistral-medium-3': false,
+  'mistralai/mistral-medium-3-5': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'mistralai/mistral-medium-3-5:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'mistralai/mistral-medium-3.1': false,
+  'mistralai/mistral-medium-3.1:batch': false,
+  'mistralai/mistral-nemo': false,
+  'mistralai/mistral-saba': false,
+  'mistralai/mistral-small-24b-instruct-2501': false,
+  'mistralai/mistral-small-2603': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'mistralai/mistral-small-2603:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'mistralai/mistral-small-3.1-24b-instruct': false,
+  'mistralai/mistral-small-3.2-24b-instruct': false,
+  'mistralai/mixtral-8x22b-instruct': false,
+  'mistralai/voxtral-small-24b-2507': false,
+  'moonshotai/kimi-k2': false,
+  'moonshotai/kimi-k2-0905': false,
+  'moonshotai/kimi-k2-thinking': { budget: false },
+  'moonshotai/kimi-k2.5': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'moonshotai/kimi-k2.6': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'moonshotai/kimi-k2.7-code': { budget: false },
+  'moonshotai/kimi-k3': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'moonshotai/kimi-k3:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'morph/morph-v3-fast': false,
+  'morph/morph-v3-large': false,
+  'nex-agi/nex-n2.5-mini': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'nex-agi/nex-n2.5-pro': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'nousresearch/hermes-3-llama-3.1-405b': false,
+  'nousresearch/hermes-3-llama-3.1-70b': false,
+  'nousresearch/hermes-4-405b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'nvidia/nemotron-3-nano-30b-a3b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: true,
+  },
+  'nvidia/nemotron-3-super-120b-a12b': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: null,
+      max: null,
+    },
+    budget: true,
+  },
+  'nvidia/nemotron-3-super-120b-a12b:free': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: null,
+      max: null,
+    },
+    budget: true,
+  },
+  'nvidia/nemotron-3-ultra-550b-a55b': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: true,
+  },
+  'nvidia/nemotron-3-ultra-550b-a55b:free': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: true,
+  },
+  'nvidia/nemotron-3.5-content-safety': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'nvidia/nemotron-3.5-content-safety:free': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'nvidia/nemotron-3.5-lightning': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'nvidia/nemotron-3.5-lightning:free': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'openai/gpt-3.5-turbo': false,
+  'openai/gpt-3.5-turbo-0613': false,
+  'openai/gpt-3.5-turbo-16k': false,
+  'openai/gpt-3.5-turbo-instruct': false,
+  'openai/gpt-3.5-turbo:batch': false,
+  'openai/gpt-4': false,
+  'openai/gpt-4-turbo': false,
+  'openai/gpt-4-turbo:batch': false,
+  'openai/gpt-4.1': false,
+  'openai/gpt-4.1-mini': false,
+  'openai/gpt-4.1-mini:batch': false,
+  'openai/gpt-4.1-nano': false,
+  'openai/gpt-4.1-nano:batch': false,
+  'openai/gpt-4.1:batch': false,
+  'openai/gpt-4o': false,
+  'openai/gpt-4o-2024-05-13': false,
+  'openai/gpt-4o-2024-08-06': false,
+  'openai/gpt-4o-2024-11-20': false,
+  'openai/gpt-4o-mini': false,
+  'openai/gpt-4o-mini-2024-07-18': false,
+  'openai/gpt-4o-mini:batch': false,
+  'openai/gpt-4o:batch': false,
+  'openai/gpt-5': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5-image': { budget: false },
+  'openai/gpt-5-image-mini': { budget: false },
+  'openai/gpt-5-mini': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5-mini:batch': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5-nano': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5-nano:batch': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5-pro': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5-pro:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5:batch': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.1': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.1-codex': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.1-codex-max': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.1-codex-mini': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.1:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.2': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.2-chat': false,
+  'openai/gpt-5.2-codex': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.2-pro': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.2-pro:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.2:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.3-codex': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.4': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.4-image-2': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.4-mini': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.4-mini:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.4-nano': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.4-nano:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.4-pro': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.4-pro:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.4:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.5': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.5-pro': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.5-pro:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.5:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-luna': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-luna-pro': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-luna-pro:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-luna:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-sol': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-sol-pro': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-sol-pro:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-sol:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-terra': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-terra-pro': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-terra-pro:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-terra:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-astra': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-astra-pro': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-astra-pro:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-astra:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-luna': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-luna-pro': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-luna-pro:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-luna:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-sol': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-sol-pro': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-sol-pro:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-sol:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6.1-sol': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6.1-sol-pro': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6.1-sol-pro:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6.1-sol:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-audio': false,
+  'openai/gpt-audio-mini': false,
+  'openai/gpt-chat-latest': false,
+  'openai/gpt-oss-120b': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-oss-120b:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-oss-20b': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-oss-20b:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-oss-safeguard-20b': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/o1': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'openai/o1-pro': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'openai/o3': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'openai/o3-mini': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'openai/o3-mini-high': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/o3-mini:batch': { budget: false },
+  'openai/o3-pro': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'openai/o3:batch': { budget: false },
+  'openai/o4-mini': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'openai/o4-mini-high': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/o4-mini:batch': { budget: false },
+  'perceptron/perceptron-mk1': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'perceptron/perceptron-mk1.5': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'perplexity/sonar': false,
+  'perplexity/sonar-deep-research': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'perplexity/sonar-pro': false,
+  'perplexity/sonar-pro-search': { budget: false },
+  'perplexity/sonar-reasoning-pro': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'poolside/laguna-s-2.1': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'poolside/laguna-s-2.1:free': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'poolside/laguna-xs-2.1': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'poolside/laguna-xs-2.1:free': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'prism-ml/ternary-bonsai-2-27b': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'qwen/qwen-2.5-72b-instruct': false,
+  'qwen/qwen-2.5-7b-instruct': false,
+  'qwen/qwen-2.5-coder-32b-instruct': false,
+  'qwen/qwen-plus': false,
+  'qwen/qwen-plus-2025-07-28': false,
+  'qwen/qwen2.5-vl-72b-instruct': false,
+  'qwen/qwen3-14b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3-235b-a22b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3-235b-a22b-2507': false,
+  'qwen/qwen3-235b-a22b-thinking-2507': { budget: false },
+  'qwen/qwen3-30b-a3b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3-30b-a3b-instruct-2507': false,
+  'qwen/qwen3-30b-a3b-thinking-2507': { budget: false },
+  'qwen/qwen3-32b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3-8b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3-coder': false,
+  'qwen/qwen3-coder-30b-a3b-instruct': false,
+  'qwen/qwen3-coder-flash': false,
+  'qwen/qwen3-coder-next': false,
+  'qwen/qwen3-coder-plus': false,
+  'qwen/qwen3-max': false,
+  'qwen/qwen3-max-thinking': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3-next-80b-a3b-instruct': false,
+  'qwen/qwen3-next-80b-a3b-thinking': { budget: false },
+  'qwen/qwen3-vl-235b-a22b-instruct': false,
+  'qwen/qwen3-vl-235b-a22b-thinking': { budget: false },
+  'qwen/qwen3-vl-30b-a3b-instruct': false,
+  'qwen/qwen3-vl-30b-a3b-thinking': { budget: false },
+  'qwen/qwen3-vl-32b-instruct': false,
+  'qwen/qwen3-vl-8b-instruct': false,
+  'qwen/qwen3-vl-8b-thinking': { budget: false },
+  'qwen/qwen3.5-122b-a10b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3.5-27b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3.5-35b-a3b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3.5-397b-a17b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3.5-9b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3.5-flash-02-23': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3.5-plus-02-15': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3.5-plus-20260420': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3.6-27b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3.6-35b-a3b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3.6-flash': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3.6-max-preview': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3.6-plus': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3.7-flash': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: true,
+  },
+  'qwen/qwen3.7-max': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3.7-plus': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'qwen/qwen3.8-2.4t-a95b': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'qwen/qwen3.8-27b': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'qwen/qwen3.8-27b:free': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'qwen/qwen3.8-flash': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: true,
+  },
+  'qwen/qwen3.8-max-0902': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'qwen/qwen3.8-max-prime': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'qwen/qwen3.8-omni-flash': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: true,
+  },
+  'rekaai/reka-edge': false,
+  'rekaai/reka-flash-3': { budget: false },
+  'relace/relace-apply-3': false,
+  'relace/relace-search': false,
+  'sakana/fugu-max': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'sakana/fugu-ultra': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'sakana/fugu-ultra-v2': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'sakana/sakana-namazu': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'sao10k/l3-lunaris-8b': false,
+  'sao10k/l3.1-euryale-70b': false,
+  'sao10k/l3.3-euryale-70b': false,
+  'stealth/space-bunny-alpha': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'stepfun/step-3.5-flash': { budget: false },
+  'stepfun/step-3.7-flash': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'tencent/hunyuan-a13b-instruct': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'tencent/hy-mt2-1.8b': false,
+  'tencent/hy-mt2-30b-a3b': false,
+  'tencent/hy-mt2-7b': false,
+  'tencent/hy3': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'tencent/hy3-preview': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'tencent/hy4-preview': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'thedrummer/cydonia-24b-v4.1': false,
+  'thedrummer/skyfall-36b-v2': false,
+  'thedrummer/unslopnemo-12b': false,
+  'thinkingmachines/inkling': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'thinkingmachines/inkling-small': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'thinkingmachines/inkling-small:free': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'thinkingmachines/inkling:free': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'unbiased/pareto': false,
+  'undi95/remm-slerp-l2-13b': false,
+  'upstage/solar-mini4': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'upstage/solar-pro-3': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'upstage/solar-pro4': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'writer/palmyra-x5': false,
+  'x-ai/grok-4.20': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'x-ai/grok-4.20-multi-agent': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'x-ai/grok-4.3': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'x-ai/grok-4.3:batch': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'x-ai/grok-4.5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'x-ai/grok-4.6': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'x-ai/grok-4.7': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'x-ai/grok-build-0.1': { budget: false },
+  'xiaomi/mimo-v2.5': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'xiaomi/mimo-v2.5-pro': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'xiaomi/mimo-v2.6-flash': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'xiaomi/mimo-v2.6-pro': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'xiaomi/mimo-v2.6-pro-ultraspeed': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'z-ai/glm-4.5': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'z-ai/glm-4.5-air': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'z-ai/glm-4.5v': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'z-ai/glm-4.6': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'z-ai/glm-4.6v': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'z-ai/glm-4.7': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'z-ai/glm-4.7-flash': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'z-ai/glm-5': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'z-ai/glm-5-turbo': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'z-ai/glm-5.1': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'z-ai/glm-5.2': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'z-ai/glm-5.3': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'z-ai/glm-5.3-flash': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'z-ai/glm-5.3-flash:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'z-ai/glm-5.3-flashx': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'z-ai/glm-5.3-prime': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'z-ai/glm-5.3:batch': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'z-ai/glm-5v-turbo': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'openrouter/auto': { budget: false },
+}
diff --git a/packages/ai-vercel-gateway/src/model-reasoning.ts b/packages/ai-vercel-gateway/src/model-reasoning.ts
new file mode 100644
index 0000000000..2bb3e3dec4
--- /dev/null
+++ b/packages/ai-vercel-gateway/src/model-reasoning.ts
@@ -0,0 +1,2824 @@
+// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * `chat({ reasoning })`. A model that is not here does not reason.
+ */
+export type VercelGatewayModelReasoningByName = {
+  'alibaba/qwen-3-14b': { levels: 'off' | 'high'; budget: false }
+  'alibaba/qwen-3-235b': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'alibaba/qwen-3-30b': { levels: 'off' | 'high'; budget: false }
+  'alibaba/qwen-3-32b': { levels: 'off' | 'high'; budget: true }
+  'alibaba/qwen-3.6-max-preview': { levels: 'off' | 'high'; budget: true }
+  'alibaba/qwen3-235b-a22b-thinking': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'alibaba/qwen3-coder': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'alibaba/qwen3-coder-30b-a3b': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'alibaba/qwen3-coder-next': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'alibaba/qwen3-max-thinking': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'alibaba/qwen3-next-80b-a3b-thinking': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'alibaba/qwen3-vl-thinking': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'alibaba/qwen3.5-flash': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: true
+  }
+  'alibaba/qwen3.5-plus': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: true
+  }
+  'alibaba/qwen3.6-27b': { levels: 'off' | 'high'; budget: true }
+  'alibaba/qwen3.6-plus': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: true
+  }
+  'alibaba/qwen3.7-flash': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: true
+  }
+  'alibaba/qwen3.7-max': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: true
+  }
+  'alibaba/qwen3.7-plus': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: true
+  }
+  'alibaba/qwen3.8-2.4t-a95b': {
+    levels: 'low' | 'medium' | 'xhigh'
+    budget: false
+  }
+  'alibaba/qwen3.8-27b': {
+    levels: 'off' | 'low' | 'medium' | 'xhigh'
+    budget: false
+  }
+  'alibaba/qwen3.8-flash': {
+    levels: 'off' | 'low' | 'medium' | 'xhigh'
+    budget: true
+  }
+  'alibaba/qwen3.8-max': {
+    levels: 'off' | 'low' | 'medium' | 'xhigh'
+    budget: true
+  }
+  'alibaba/qwen3.8-max-0902': {
+    levels: 'off' | 'low' | 'medium' | 'xhigh'
+    budget: true
+  }
+  'alibaba/qwen3.8-max-prime': {
+    levels: 'off' | 'low' | 'medium' | 'xhigh'
+    budget: true
+  }
+  'alibaba/qwen3.8-omni-flash': {
+    levels: 'off' | 'low' | 'medium' | 'xhigh'
+    budget: false
+  }
+  'amazon/nova-2-lite': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'anthropic/claude-fable-5': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: true
+  }
+  'anthropic/claude-fable-5.1': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: true
+  }
+  'anthropic/claude-haiku-4.5': { levels: 'off' | 'high'; budget: true }
+  'anthropic/claude-opus-4': { levels: 'off' | 'high'; budget: true }
+  'anthropic/claude-opus-4.5': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'anthropic/claude-opus-4.6': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'max'
+    budget: true
+  }
+  'anthropic/claude-opus-4.7': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: true
+  }
+  'anthropic/claude-opus-4.8': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: true
+  }
+  'anthropic/claude-opus-4.8-fast': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: true
+  }
+  'anthropic/claude-opus-5': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: true
+  }
+  'anthropic/claude-opus-5-fast': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: true
+  }
+  'anthropic/claude-opus-5.5': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'anthropic/claude-opus-5.5-fast': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'anthropic/claude-sonnet-4': { levels: 'off' | 'high'; budget: true }
+  'anthropic/claude-sonnet-4.5': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'anthropic/claude-sonnet-4.6': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'max'
+    budget: true
+  }
+  'anthropic/claude-sonnet-5': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: true
+  }
+  'anthropic/claude-sonnet-5.5': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'arcee-ai/trinity-large-thinking': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'bytedance/seed-1.6': { levels: 'off' | 'high'; budget: false }
+  'bytedance/seed-1.8': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'bytedance/seed-2.1-turbo': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'deepseek/deepseek-r1': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'deepseek/deepseek-v3.1': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'deepseek/deepseek-v3.1-terminus': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'deepseek/deepseek-v3.2-thinking': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'deepseek/deepseek-v4-flash': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'deepseek/deepseek-v4-flash-0731': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'deepseek/deepseek-v4-flash-vision-exp': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'deepseek/deepseek-v4-pro': { levels: 'off' | 'high' | 'max'; budget: false }
+  'deepseek/deepseek-v4-pro-0813': {
+    levels: 'off' | 'high' | 'max'
+    budget: false
+  }
+  'deepseek/deepseek-v4.1-flash': {
+    levels: 'off' | 'high' | 'max'
+    budget: false
+  }
+  'fireworks/ember-1': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'google/gemini-2.5-flash': { levels: 'off' | 'high'; budget: true }
+  'google/gemini-2.5-flash-lite': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'google/gemini-2.5-pro': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'google/gemini-3-flash': { levels: 'low' | 'high'; budget: false }
+  'google/gemini-3.1-flash-image': { levels: 'low' | 'high'; budget: false }
+  'google/gemini-3.1-flash-image-preview': {
+    levels: 'low' | 'high'
+    budget: false
+  }
+  'google/gemini-3.1-flash-lite': { levels: 'low' | 'high'; budget: false }
+  'google/gemini-3.1-flash-lite-image': {
+    levels: 'low' | 'high'
+    budget: false
+  }
+  'google/gemini-3.1-pro-preview': { levels: 'low' | 'high'; budget: false }
+  'google/gemini-3.5-flash': { levels: 'low' | 'high'; budget: false }
+  'google/gemini-3.5-flash-lite': { levels: 'low' | 'high'; budget: false }
+  'google/gemini-3.6-flash': { levels: 'low' | 'high'; budget: false }
+  'google/gemini-3.7-flash': { levels: 'low' | 'high'; budget: false }
+  'google/gemini-3.8-flash': { levels: 'low' | 'high'; budget: false }
+  'google/gemini-omni-flash-preview': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'google/gemma-4-26b-a4b-it': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'inception/mercury-2': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'inception/mercury-2.5': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'inclusionai/ling-3.0-flash': { levels: 'off' | 'high'; budget: false }
+  'inclusionai/ling-3.0-flash-fin': { levels: 'off' | 'high'; budget: false }
+  'inclusionai/ling-3.0-flash-sante': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'inclusionai/ling-3.0-flash-sante-free': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'inclusionai/ling-3.0-flash-vl': { levels: 'off' | 'high'; budget: false }
+  'inclusionai/ling-3.1-flash': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'inclusionai/ling-3.1-flash-free': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'interfaze/interfaze-beta': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'meituan/longcat-2.5-preview': { levels: 'off' | 'high'; budget: false }
+  'meta/muse-glimmer-30b': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'meta/muse-spark-1.1': {
+    levels: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'meta/muse-spark-1.2': {
+    levels: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'meta/muse-spark-1.2-contributor': {
+    levels: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'meta/muse-spark-1.3': {
+    levels: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'meta/muse-spark-1.3-contributor': {
+    levels: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'minimax/minimax-m2': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'minimax/minimax-m2.1': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'minimax/minimax-m2.1-lightning': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'minimax/minimax-m2.5': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'minimax/minimax-m2.5-highspeed': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'minimax/minimax-m2.7': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'minimax/minimax-m2.7-highspeed': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'minimax/minimax-m3': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: true
+  }
+  'mistral/mistral-medium-3.5': { levels: 'off' | 'high'; budget: false }
+  'moonshotai/kimi-k2-thinking': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'moonshotai/kimi-k2.5': { levels: 'off' | 'high'; budget: false }
+  'moonshotai/kimi-k2.6': { levels: 'off' | 'high'; budget: false }
+  'moonshotai/kimi-k2.7-code': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'moonshotai/kimi-k2.7-code-highspeed': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'moonshotai/kimi-k3': {
+    levels: 'off' | 'low' | 'high' | 'max'
+    budget: false
+  }
+  'moonshotai/kimi-k3-fast': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'max'
+    budget: false
+  }
+  'nvidia/nemotron-3-nano-30b-a3b': { levels: 'off' | 'high'; budget: false }
+  'nvidia/nemotron-3-super-120b-a12b': {
+    levels: 'off' | 'low' | 'high'
+    budget: false
+  }
+  'nvidia/nemotron-3-ultra-550b-a55b': {
+    levels: 'off' | 'medium' | 'high'
+    budget: false
+  }
+  'nvidia/nemotron-3.5-lightning': { levels: 'off' | 'high'; budget: true }
+  'nvidia/nemotron-nano-12b-v2-vl': { levels: 'off' | 'high'; budget: false }
+  'nvidia/nemotron-nano-9b-v2': { levels: 'off' | 'high'; budget: false }
+  'openai/gpt-5': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5-codex': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'openai/gpt-5-fast': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5-mini': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5-mini-fast': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5-nano': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5-pro': { levels: 'high'; budget: false }
+  'openai/gpt-5.1-codex': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5.1-codex-max': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5.1-codex-mini': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5.1-thinking': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.1-thinking-fast': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.2': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.2-codex': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-5.2-fast': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.2-pro': { levels: 'medium' | 'high' | 'xhigh'; budget: false }
+  'openai/gpt-5.3-codex': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.3-codex-fast': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.4': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.4-fast': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.4-mini': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.4-mini-fast': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.4-nano': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.4-pro': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.5': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.5-fast': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/gpt-5.5-pro': { levels: 'medium' | 'high' | 'xhigh'; budget: false }
+  'openai/gpt-5.6-luna': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-luna-fast': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-sol': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-sol-fast': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-terra': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-5.6-terra-fast': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-astra': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-astra-fast': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-luna': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-luna-fast': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-sol': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6-sol-fast': {
+    levels: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6.1-sol': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-6.1-sol-fast': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'openai/gpt-oss-120b': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'openai/gpt-oss-20b': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'openai/gpt-oss-safeguard-120b': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-oss-safeguard-20b': {
+    levels: 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'openai/gpt-realtime-2.1': {
+    levels: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'openai/o1': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'openai/o3': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'openai/o3-fast': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'openai/o3-mini': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'openai/o3-pro': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'openai/o4-mini': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'openai/o4-mini-fast': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'poolside/laguna-s-2.1': { levels: 'off' | 'high'; budget: false }
+  'poolside/laguna-s-2.1-free': { levels: 'off' | 'high'; budget: false }
+  'quiverai/arrow-2': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'quiverai/arrow-2-telos': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'sakana/fugu-max': { levels: 'high' | 'xhigh'; budget: false }
+  'sakana/fugu-ultra': { levels: 'high' | 'xhigh'; budget: false }
+  'sakana/fugu-ultra-v2': { levels: 'high' | 'xhigh'; budget: false }
+  'sakana/namazu': { levels: 'off' | 'low' | 'medium' | 'high'; budget: false }
+  'spacexai/grok-4.1-fast-reasoning': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'spacexai/grok-4.20-multi-agent': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'spacexai/grok-4.20-multi-agent-beta': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'spacexai/grok-4.20-reasoning': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'spacexai/grok-4.20-reasoning-beta': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'spacexai/grok-4.3': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'spacexai/grok-4.5': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'spacexai/grok-4.6': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'spacexai/grok-4.7': {
+    levels: 'low' | 'medium' | 'high' | 'xhigh'
+    budget: false
+  }
+  'spacexai/grok-build-0.1': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'stealth/pixel-canary': {
+    levels: 'off' | 'low' | 'medium' | 'xhigh'
+    budget: false
+  }
+  'stepfun/step-3.5-flash': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'stepfun/step-3.7-flash': { levels: 'low' | 'medium' | 'high'; budget: false }
+  'tencent/hy3': { levels: 'off' | 'low' | 'high'; budget: false }
+  'tencent/hy4-preview': { levels: 'off' | 'high'; budget: false }
+  'thinkingmachines/inkling': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'thinkingmachines/inkling-small': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    budget: false
+  }
+  'xiaomi/mimo-v2.5': { levels: 'off' | 'high'; budget: false }
+  'xiaomi/mimo-v2.5-pro': { levels: 'off' | 'high'; budget: false }
+  'xiaomi/mimo-v2.6-flash': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'xiaomi/mimo-v2.6-pro': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'xiaomi/mimo-v2.6-pro-ultraspeed': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'zai/glm-4.5': { levels: 'off' | 'high'; budget: false }
+  'zai/glm-4.5-air': { levels: 'off' | 'high'; budget: false }
+  'zai/glm-4.5v': { levels: 'off' | 'high'; budget: false }
+  'zai/glm-4.6': { levels: 'off' | 'high'; budget: false }
+  'zai/glm-4.7': { levels: 'off' | 'high'; budget: false }
+  'zai/glm-4.7-flash': { levels: 'off' | 'high'; budget: false }
+  'zai/glm-4.7-flashx': { levels: 'off' | 'high'; budget: false }
+  'zai/glm-5': { levels: 'off' | 'high'; budget: false }
+  'zai/glm-5-turbo': { levels: 'off' | 'high'; budget: false }
+  'zai/glm-5.1': { levels: 'off' | 'high'; budget: false }
+  'zai/glm-5.2': { levels: 'off' | 'high' | 'max'; budget: false }
+  'zai/glm-5.2-fast': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'zai/glm-5.3': { levels: 'low' | 'high' | 'max'; budget: false }
+  'zai/glm-5.3-fast': {
+    levels: 'off' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'zai/glm-5.3-flash': { levels: 'low' | 'high' | 'max'; budget: false }
+  'zai/glm-5.3-flashx': { levels: 'low' | 'high' | 'max'; budget: false }
+  'zai/glm-5v-turbo': { levels: 'off' | 'high'; budget: false }
+}
+
+/** The same data at runtime. `false`: the model does not reason. */
+export const VERCEL_GATEWAY_MODEL_REASONING: Readonly<
+  Record<string, ModelReasoning>
+> = {
+  'alibaba/qwen-3-14b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'alibaba/qwen-3-235b': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'alibaba/qwen-3-30b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'alibaba/qwen-3-32b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: true,
+  },
+  'alibaba/qwen-3.6-max-preview': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: true,
+  },
+  'alibaba/qwen3-235b-a22b-thinking': { budget: true },
+  'alibaba/qwen3-coder': { budget: false },
+  'alibaba/qwen3-coder-30b-a3b': { budget: false },
+  'alibaba/qwen3-coder-next': { budget: false },
+  'alibaba/qwen3-coder-plus': false,
+  'alibaba/qwen3-max': false,
+  'alibaba/qwen3-max-preview': false,
+  'alibaba/qwen3-max-thinking': { budget: true },
+  'alibaba/qwen3-next-80b-a3b-instruct': false,
+  'alibaba/qwen3-next-80b-a3b-thinking': { budget: true },
+  'alibaba/qwen3-vl-235b-a22b-instruct': false,
+  'alibaba/qwen3-vl-instruct': false,
+  'alibaba/qwen3-vl-thinking': { budget: true },
+  'alibaba/qwen3.5-flash': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: true,
+  },
+  'alibaba/qwen3.5-plus': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: true,
+  },
+  'alibaba/qwen3.6-27b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: true,
+  },
+  'alibaba/qwen3.6-plus': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: true,
+  },
+  'alibaba/qwen3.7-flash': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: true,
+  },
+  'alibaba/qwen3.7-max': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: true,
+  },
+  'alibaba/qwen3.7-plus': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: true,
+  },
+  'alibaba/qwen3.8-2.4t-a95b': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'alibaba/qwen3.8-27b': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'alibaba/qwen3.8-flash': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: true,
+  },
+  'alibaba/qwen3.8-max': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: true,
+  },
+  'alibaba/qwen3.8-max-0902': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: true,
+  },
+  'alibaba/qwen3.8-max-prime': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: true,
+  },
+  'alibaba/qwen3.8-omni-flash': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'amazon/nova-2-lite': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'amazon/nova-lite': false,
+  'amazon/nova-micro': false,
+  'amazon/nova-pro': false,
+  'anthropic/claude-3-haiku': false,
+  'anthropic/claude-fable-5': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: true,
+  },
+  'anthropic/claude-fable-5.1': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: true,
+  },
+  'anthropic/claude-haiku-4.5': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: true,
+  },
+  'anthropic/claude-opus-4': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: true,
+  },
+  'anthropic/claude-opus-4.5': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: true,
+  },
+  'anthropic/claude-opus-4.6': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: true,
+  },
+  'anthropic/claude-opus-4.7': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: true,
+  },
+  'anthropic/claude-opus-4.8': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: true,
+  },
+  'anthropic/claude-opus-4.8-fast': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: true,
+  },
+  'anthropic/claude-opus-5': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: true,
+  },
+  'anthropic/claude-opus-5-fast': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: true,
+  },
+  'anthropic/claude-opus-5.5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-opus-5.5-fast': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'anthropic/claude-sonnet-4': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: true,
+  },
+  'anthropic/claude-sonnet-4.5': { budget: true },
+  'anthropic/claude-sonnet-4.6': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: true,
+  },
+  'anthropic/claude-sonnet-5': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: true,
+  },
+  'anthropic/claude-sonnet-5.5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'arcee-ai/trinity-large-thinking': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'bytedance/seed-1.6': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'bytedance/seed-1.8': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'bytedance/seed-2.1-turbo': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'cohere/command-a': false,
+  'deepseek/deepseek-r1': { budget: false },
+  'deepseek/deepseek-v3.1': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'deepseek/deepseek-v3.1-terminus': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'deepseek/deepseek-v3.2': false,
+  'deepseek/deepseek-v3.2-thinking': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'deepseek/deepseek-v4-flash': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'deepseek/deepseek-v4-flash-0731': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'deepseek/deepseek-v4-flash-vision-exp': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'deepseek/deepseek-v4-pro': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'deepseek/deepseek-v4-pro-0813': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'deepseek/deepseek-v4.1-flash': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'fireworks/ember-1': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: true,
+  },
+  'fish-audio/s1': false,
+  'fish-audio/s2-pro': false,
+  'fish-audio/s2.1-pro': false,
+  'fish-audio/transcribe-1': false,
+  'google/gemini-2.5-flash': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: true,
+  },
+  'google/gemini-2.5-flash-image': false,
+  'google/gemini-2.5-flash-lite': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: true,
+  },
+  'google/gemini-2.5-pro': { budget: true },
+  'google/gemini-3-flash': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3-pro-image': false,
+  'google/gemini-3.1-flash-image': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.1-flash-image-preview': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.1-flash-lite': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.1-flash-lite-image': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.1-pro-preview': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.5-flash': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.5-flash-lite': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.5-transcribe': false,
+  'google/gemini-3.5-transcribe-live': false,
+  'google/gemini-3.6-flash': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.7-flash': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.8-flash': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemini-3.8-flash-lite-tts': false,
+  'google/gemini-3.8-flash-tts': false,
+  'google/gemini-3.8-live': false,
+  'google/gemini-3.8-live-extended-thinking': false,
+  'google/gemini-omni-flash-preview': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'google/gemma-4-26b-a4b-it': { budget: false },
+  'google/gemma-4-31b-it': false,
+  'inception/mercury-2': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'inception/mercury-2.5': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'inception/mercury-coder-small': false,
+  'inclusionai/ling-3.0-flash': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'inclusionai/ling-3.0-flash-fin': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'inclusionai/ling-3.0-flash-sante': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'inclusionai/ling-3.0-flash-sante-free': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'inclusionai/ling-3.0-flash-vl': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'inclusionai/ling-3.1-flash': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'inclusionai/ling-3.1-flash-free': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'inference-net/schematron-v2-small': false,
+  'inference-net/schematron-v2-turbo': false,
+  'interfaze/interfaze-beta': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'liquid/d1': false,
+  'meituan/longcat-2.5-preview': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'meta/llama-3.1-70b': false,
+  'meta/llama-3.1-8b': false,
+  'meta/llama-3.3-70b': false,
+  'meta/llama-4-maverick': false,
+  'meta/llama-4-scout': false,
+  'meta/muse-glimmer-30b': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'meta/muse-spark-1.1': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'meta/muse-spark-1.2': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'meta/muse-spark-1.2-contributor': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'meta/muse-spark-1.3': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'meta/muse-spark-1.3-contributor': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'minimax/minimax-m2': { budget: true },
+  'minimax/minimax-m2.1': { budget: true },
+  'minimax/minimax-m2.1-lightning': { budget: true },
+  'minimax/minimax-m2.5': { budget: true },
+  'minimax/minimax-m2.5-highspeed': { budget: true },
+  'minimax/minimax-m2.7': { budget: true },
+  'minimax/minimax-m2.7-highspeed': { budget: true },
+  'minimax/minimax-m3': { budget: true },
+  'mistral/codestral': false,
+  'mistral/ministral-14b': false,
+  'mistral/ministral-3b': false,
+  'mistral/ministral-8b': false,
+  'mistral/mistral-large-3': false,
+  'mistral/mistral-medium-3.5': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'mistral/mistral-nemo': false,
+  'mistral/mistral-small': false,
+  'mixedbread/toast-1': false,
+  'moonshotai/kimi-k2': false,
+  'moonshotai/kimi-k2-thinking': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'moonshotai/kimi-k2.5': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'moonshotai/kimi-k2.6': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'moonshotai/kimi-k2.7-code': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'moonshotai/kimi-k2.7-code-highspeed': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'moonshotai/kimi-k3': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'moonshotai/kimi-k3-fast': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'morph/morph-v3-fast': false,
+  'morph/morph-v3-large': false,
+  'nvidia/nemotron-3-nano-30b-a3b': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'nvidia/nemotron-3-super-120b-a12b': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'nvidia/nemotron-3-ultra-550b-a55b': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'nvidia/nemotron-3.5-lightning': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: true,
+  },
+  'nvidia/nemotron-nano-12b-v2-vl': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'nvidia/nemotron-nano-9b-v2': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'openai/gpt-3.5-turbo': false,
+  'openai/gpt-4-turbo': false,
+  'openai/gpt-4.1': false,
+  'openai/gpt-4.1-fast': false,
+  'openai/gpt-4.1-mini': false,
+  'openai/gpt-4.1-mini-fast': false,
+  'openai/gpt-4.1-nano': false,
+  'openai/gpt-4.1-nano-fast': false,
+  'openai/gpt-4o': false,
+  'openai/gpt-4o-fast': false,
+  'openai/gpt-4o-mini': false,
+  'openai/gpt-4o-mini-fast': false,
+  'openai/gpt-4o-mini-transcribe': false,
+  'openai/gpt-4o-transcribe': false,
+  'openai/gpt-5': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5-codex': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5-fast': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5-mini': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5-mini-fast': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5-nano': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5-pro': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.1-codex': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.1-codex-max': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.1-codex-mini': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.1-thinking': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.1-thinking-fast': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.2': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.2-codex': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.2-fast': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.2-pro': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.3-codex': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.3-codex-fast': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.4': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.4-fast': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.4-mini': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.4-mini-fast': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.4-nano': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.4-pro': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.5': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.5-fast': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.5-pro': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-luna': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-luna-fast': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-sol': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-sol-fast': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-terra': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-5.6-terra-fast': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-astra': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-astra-fast': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-luna': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-luna-fast': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-sol': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6-sol-fast': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6.1-sol': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-6.1-sol-fast': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'openai/gpt-live-1': false,
+  'openai/gpt-oss-120b': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-oss-20b': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-oss-safeguard-120b': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-oss-safeguard-20b': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-realtime-1.5': false,
+  'openai/gpt-realtime-2': false,
+  'openai/gpt-realtime-2.1': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/gpt-realtime-mini': false,
+  'openai/gpt-realtime-whisper': false,
+  'openai/o1': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/o3': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/o3-fast': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/o3-mini': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/o3-pro': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/o4-mini': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/o4-mini-fast': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'openai/tts-1': false,
+  'openai/tts-1-hd': false,
+  'openai/whisper-1': false,
+  'perplexity/sonar': false,
+  'poolside/laguna-s-2.1': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'poolside/laguna-s-2.1-free': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'quiverai/arrow-2': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'quiverai/arrow-2-telos': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'sakana/fugu-max': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'sakana/fugu-ultra': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'sakana/fugu-ultra-v2': {
+    map: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'sakana/namazu': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'spacexai/grok-4.1-fast-non-reasoning': false,
+  'spacexai/grok-4.1-fast-reasoning': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'spacexai/grok-4.20-multi-agent': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'spacexai/grok-4.20-multi-agent-beta': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'spacexai/grok-4.20-non-reasoning': false,
+  'spacexai/grok-4.20-non-reasoning-beta': false,
+  'spacexai/grok-4.20-reasoning': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'spacexai/grok-4.20-reasoning-beta': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'spacexai/grok-4.3': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'spacexai/grok-4.5': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'spacexai/grok-4.6': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'spacexai/grok-4.7': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'spacexai/grok-build-0.1': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'spacexai/grok-stt': false,
+  'spacexai/grok-tts': false,
+  'spacexai/grok-voice-think-fast-1.0': false,
+  'spacexai/grok-voice-think-fast-2.0': false,
+  'stealth/pixel-canary': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
+    },
+    budget: false,
+  },
+  'stepfun/step-3.5-flash': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'stepfun/step-3.7-flash': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'stepfun/step-5-preview': false,
+  'tencent/hy-mt2-lite': false,
+  'tencent/hy-mt2-plus': false,
+  'tencent/hy-mt2-pro': false,
+  'tencent/hy3': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'tencent/hy4-preview': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'thinkingmachines/inkling': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'thinkingmachines/inkling-small': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: 'xhigh',
+      max: 'max',
+    },
+    budget: false,
+  },
+  'typesafe-ai/jev': false,
+  'xiaomi/mimo-v2.5': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'xiaomi/mimo-v2.5-pro': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'xiaomi/mimo-v2.6-flash': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'xiaomi/mimo-v2.6-pro': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'xiaomi/mimo-v2.6-pro-ultraspeed': {
+    map: {
+      off: 'none',
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'zai/glm-4.5': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'zai/glm-4.5-air': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'zai/glm-4.5v': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'zai/glm-4.6': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'zai/glm-4.7': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'zai/glm-4.7-flash': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'zai/glm-4.7-flashx': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'zai/glm-5': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'zai/glm-5-turbo': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'zai/glm-5.1': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+  'zai/glm-5.2': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'zai/glm-5.2-fast': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'zai/glm-5.3': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'zai/glm-5.3-fast': {
+    map: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'zai/glm-5.3-flash': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'zai/glm-5.3-flashx': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'zai/glm-5v-turbo': {
+    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  },
+}
diff --git a/packages/ai/src/activities/chat/adapter.ts b/packages/ai/src/activities/chat/adapter.ts
index c4c92c2fef..03b2342dd5 100644
--- a/packages/ai/src/activities/chat/adapter.ts
+++ b/packages/ai/src/activities/chat/adapter.ts
@@ -7,6 +7,7 @@ import type {
 } from '../../types'
 import type { AdapterYieldChunk } from '../../utilities/adapter-yield-chunk'
 import type { CapabilityHandle } from './middleware/capabilities'
+import type { ReasoningCapability } from '../../reasoning'
 
 /**
  * Configuration for adapter instances
@@ -72,6 +73,7 @@ export interface TextAdapter<
   TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,
   TToolCallMetadata = unknown,
   TSystemPromptMetadata = never,
+  TReasoning extends ReasoningCapability = never,
 > {
   /** Discriminator for adapter kind */
   readonly kind: 'text'
@@ -115,6 +117,13 @@ export interface TextAdapter<
     toolCapabilities: TToolCapabilities
     toolCallMetadata: TToolCallMetadata
     systemPromptMetadata: TSystemPromptMetadata
+    /**
+     * The model's reasoning levels, for `chat({ reasoning })`. `never`: the
+     * model does not reason (or the adapter does not map `reasoning`), and
+     * the option is a type error. Optional, so an adapter written before this
+     * key existed still type-checks (and gets no `reasoning` option).
+     */
+    reasoning?: TReasoning
   }
 
   /**
@@ -196,7 +205,16 @@ export interface TextAdapter<
  * A TextAdapter with any/unknown type parameters.
  * Useful as a constraint in generic functions and interfaces.
  */
-export type AnyTextAdapter = TextAdapter<any, any, any, any, any, any, any>
+export type AnyTextAdapter = TextAdapter<
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any
+>
 
 /**
  * Abstract base class for text adapters.
@@ -212,6 +230,7 @@ export abstract class BaseTextAdapter<
   TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,
   TToolCallMetadata = unknown,
   TSystemPromptMetadata = never,
+  TReasoning extends ReasoningCapability = never,
 > implements TextAdapter<
   TModel,
   TProviderOptions,
@@ -219,7 +238,8 @@ export abstract class BaseTextAdapter<
   TMessageMetadataByModality,
   TToolCapabilities,
   TToolCallMetadata,
-  TSystemPromptMetadata
+  TSystemPromptMetadata,
+  TReasoning
 > {
   readonly kind = 'text' as const
   abstract readonly name: string
@@ -240,6 +260,7 @@ export abstract class BaseTextAdapter<
     toolCapabilities: TToolCapabilities
     toolCallMetadata: TToolCallMetadata
     systemPromptMetadata: TSystemPromptMetadata
+    reasoning: TReasoning
   }
 
   protected config: TextAdapterConfig
diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index 8d6ce12aed..d6bbfa9d74 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -8,6 +8,7 @@
 import { devtoolsMiddleware } from '@tanstack/ai-event-client'
 import { undoNullWidening } from '@tanstack/ai-utils'
 import { streamToText } from '../../stream-to-response.js'
+import { normalizeReasoning } from '../../reasoning'
 import { resolveDebugOption } from '../../logger/resolve'
 import { EventType } from '../../types'
 import {
@@ -176,6 +177,11 @@ import type {
   UnionToIntersection,
 } from './runtime-context-types'
 import type { ChatMCPOptions } from './mcp/types'
+import type {
+  AdapterReasoning,
+  ReasoningOption,
+  ReasoningOptionFor,
+} from '../../reasoning'
 
 /** One entry of the per-iteration arrival order (see `turnParts`). */
 type TurnPart =
@@ -519,6 +525,13 @@ export interface TextActivityOptions<
   metadata?: TextOptions['metadata']
   /** Model-specific provider options (type comes from adapter) */
   modelOptions?: TAdapter['~types']['providerOptions']
+  /**
+   * How hard the model thinks: a level (`'low'`, `'high'`, ...) or
+   * `{ level, summary?, budgetTokens? }`. The types allow only the model's own
+   * levels. Not set: the provider default applies. `'off'` turns thinking off.
+   * A level the model does not support at runtime moves to the nearest one.
+   */
+  reasoning?: ReasoningOptionFor<AdapterReasoning<TAdapter>>
   /** AbortController for cancellation */
   abortController?: TextOptions['abortController']
   /** Strategy for controlling the agent loop */
@@ -989,7 +1002,13 @@ class TextEngine<
       ).map((definition) => [definition.id, definition]),
     )
     this.finalStructuredOutput = config.finalStructuredOutput
-    this.params = config.params
+    this.params = {
+      ...config.params,
+      // `chat()` takes a level or an object. Adapters read one shape.
+      reasoning: normalizeReasoning(
+        config.params.reasoning as ReasoningOption | undefined,
+      ),
+    }
     this.systemPrompts = config.params.systemPrompts || []
     this.loopStrategy =
       config.params.agentLoopStrategy || maxIterationsStrategy(5)
@@ -1546,7 +1565,7 @@ class TextEngine<
   }
 
   private async *streamModelResponse(): AsyncGenerator<StreamChunk> {
-    const { metadata, modelOptions } = this.params
+    const { metadata, modelOptions, reasoning } = this.params
     const tools = this.tools
 
     // Convert tool schemas to JSON Schema before passing to adapter
@@ -1609,6 +1628,7 @@ class TextEngine<
       metadata,
       request: this.effectiveRequest,
       modelOptions,
+      ...(reasoning ? { reasoning } : {}),
       systemPrompts: this.systemPrompts,
       logger: this.logger,
       threadId: this.threadId,
@@ -3890,6 +3910,9 @@ class TextEngine<
         messages: this.providerMessages,
         metadata: postOnConfig.metadata,
         modelOptions: postOnConfig.modelOptions,
+        ...(postOnConfig.reasoning
+          ? { reasoning: postOnConfig.reasoning }
+          : {}),
         systemPrompts: postOnConfig.systemPrompts,
         logger: this.logger,
         threadId: this.threadId,
@@ -4394,6 +4417,7 @@ class TextEngine<
       },
       metadata: this.params.metadata,
       modelOptions: this.params.modelOptions,
+      reasoning: this.params.reasoning,
     }
   }
 
@@ -4862,6 +4886,7 @@ class TextEngine<
       ...this.params,
       metadata: config.metadata,
       modelOptions: config.modelOptions,
+      reasoning: config.reasoning,
     }
 
     // Sync context fields that depend on config
diff --git a/packages/ai/src/activities/chat/middleware/types.ts b/packages/ai/src/activities/chat/middleware/types.ts
index 50d177d1f0..808d6ab2de 100644
--- a/packages/ai/src/activities/chat/middleware/types.ts
+++ b/packages/ai/src/activities/chat/middleware/types.ts
@@ -17,6 +17,7 @@ import type {
 } from '../../../types'
 import type { SystemPrompt } from '../../../system-prompts'
 import type { ToolApprovalResolution } from '../../../interrupts'
+import type { ReasoningRequest } from '../../../reasoning'
 import type {
   GenericInterruptRequest,
   InterruptDefinition,
@@ -338,6 +339,8 @@ export interface ChatMiddlewareConfig {
   resumeToolState?: ChatResumeToolState | undefined
   metadata?: Record<string, unknown> | undefined
   modelOptions?: Record<string, unknown> | undefined
+  /** How hard the model thinks at this call. A middleware can set or change it. */
+  reasoning?: ReasoningRequest | undefined
 }
 
 /**
diff --git a/packages/ai/src/adapter-internals.ts b/packages/ai/src/adapter-internals.ts
index fb274dfce6..1bb1ab127d 100644
--- a/packages/ai/src/adapter-internals.ts
+++ b/packages/ai/src/adapter-internals.ts
@@ -3,6 +3,11 @@
 // logger plumbing without leaking those symbols to end users.
 
 export type { ResolvedCategories } from './logger/internal-logger'
+export {
+  DEFAULT_REASONING_BUDGETS,
+  reasoningBudget,
+  reasoningValue,
+} from './reasoning'
 export { InternalLogger } from './logger/internal-logger'
 export type { Logger } from './logger/types'
 export { resolveDebugOption } from './logger/resolve'
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index eac7cd1387..cc62273d57 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -439,6 +439,23 @@ export type {
 // All types
 export * from './types'
 
+// One reasoning option for every provider: `chat({ reasoning })`.
+export {
+  REASONING_LEVELS,
+  clampReasoningLevel,
+  supportedReasoningLevels,
+} from './reasoning'
+export type {
+  AdapterReasoning,
+  ModelReasoning,
+  ReasoningCapability,
+  ReasoningLevel,
+  ReasoningMap,
+  ReasoningOption,
+  ReasoningOptionFor,
+  ReasoningRequest,
+} from './reasoning'
+
 // Shared identity/isolation scope for the persistence + memory subsystems
 export type { Scope } from './scope'
 
diff --git a/packages/ai/src/reasoning.ts b/packages/ai/src/reasoning.ts
new file mode 100644
index 0000000000..05f7c894be
--- /dev/null
+++ b/packages/ai/src/reasoning.ts
@@ -0,0 +1,174 @@
+/**
+ * How hard a model thinks. `off` asks for no thinking. The levels are ordered
+ * from least to most, and the clamp rule walks this order.
+ */
+export type ReasoningLevel =
+  | 'off'
+  | 'minimal'
+  | 'low'
+  | 'medium'
+  | 'high'
+  | 'xhigh'
+  | 'max'
+
+/** Every level, from least to most thinking. */
+export const REASONING_LEVELS: ReadonlyArray<ReasoningLevel> = [
+  'off',
+  'minimal',
+  'low',
+  'medium',
+  'high',
+  'xhigh',
+  'max',
+]
+
+/**
+ * A model's level map: the provider value to send for a level, or `null` when
+ * the model does not support that level. A level with no entry passes as its
+ * own name (except `xhigh` and `max`, which need an entry). `off: null` means
+ * "send nothing" for no thinking.
+ */
+export type ReasoningMap = Partial<Record<ReasoningLevel, string | null>>
+
+/**
+ * What a model supports, at the type level. Adapters declare it per model in
+ * `'~types'.reasoning`. `levels` is a union of the model's levels. `budget`
+ * says whether the model takes a thinking token budget.
+ */
+export interface ReasoningCapability {
+  levels: ReasoningLevel
+  budget: boolean
+}
+
+/**
+ * The `reasoning` option of `chat()`: a level, or an object. `summary` asks
+ * the provider to stream the thinking text (default `true`). `budgetTokens`
+ * sets an exact thinking budget, on models that take one.
+ */
+export type ReasoningOption<
+  TCapability extends ReasoningCapability = ReasoningCapability,
+> =
+  | TCapability['levels']
+  | ({ level: TCapability['levels']; summary?: boolean } & (true extends TCapability['budget']
+      ? { budgetTokens?: number }
+      : { budgetTokens?: never }))
+
+/** The reasoning capability an adapter declares in `'~types'`, or `never`. */
+export type AdapterReasoning<TAdapter> = TAdapter extends {
+  '~types': { reasoning?: infer TCapability }
+}
+  ? TCapability
+  : never
+
+/** The `reasoning` option a model's capability allows. `never` for a model that does not reason. */
+export type ReasoningOptionFor<TCapability> = [TCapability] extends [never]
+  ? never
+  : TCapability extends ReasoningCapability
+    ? ReasoningOption<TCapability>
+    : never
+
+/** The `reasoning` an adapter gets in `TextOptions`, after `chat()` normalized it. */
+export interface ReasoningRequest {
+  level: ReasoningLevel
+  summary: boolean
+  budgetTokens?: number
+}
+
+/**
+ * A model's reasoning data at runtime. `false`: the model does not reason.
+ * Otherwise its level map (none means every level up to `high` passes as its
+ * own name) and whether it takes a token budget.
+ */
+export type ModelReasoning = false | { map?: ReasoningMap; budget: boolean }
+
+/** A level or an object, as the user passed it, into the one shape adapters read. */
+export function normalizeReasoning(
+  option: ReasoningOption | undefined,
+): ReasoningRequest | undefined {
+  if (option === undefined) return undefined
+  if (typeof option === 'string') return { level: option, summary: true }
+  return {
+    level: option.level,
+    summary: option.summary ?? true,
+    ...(option.budgetTokens !== undefined
+      ? { budgetTokens: option.budgetTokens }
+      : {}),
+  }
+}
+
+/**
+ * The levels a model supports, with pi's rules:
+ * - a model that does not reason supports only `off`
+ * - a level whose map value is `null` is not supported
+ * - `xhigh` and `max` are supported only when the map has a value for them
+ * - every other level is supported
+ *
+ * `undefined` (a model with no data) counts as a reasoning model with no map.
+ */
+export function supportedReasoningLevels(
+  reasoning: ModelReasoning | undefined,
+): ReadonlyArray<ReasoningLevel> {
+  if (reasoning === false) return ['off']
+  const map = reasoning?.map
+  return REASONING_LEVELS.filter((level) => {
+    const mapped = map?.[level]
+    if (mapped === null) return false
+    if (level === 'xhigh' || level === 'max') return mapped !== undefined
+    return true
+  })
+}
+
+/**
+ * A level the model supports: the level itself, else the nearest supported
+ * level above it, else the nearest below it, else `off`. The same rule as pi.
+ */
+export function clampReasoningLevel(
+  reasoning: ModelReasoning | undefined,
+  level: ReasoningLevel,
+): ReasoningLevel {
+  const supported = supportedReasoningLevels(reasoning)
+  if (supported.includes(level)) return level
+  const index = REASONING_LEVELS.indexOf(level)
+  const above = REASONING_LEVELS.slice(index + 1).find((candidate) =>
+    supported.includes(candidate),
+  )
+  if (above) return above
+  const below = REASONING_LEVELS.slice(0, index)
+    .reverse()
+    .find((candidate) => supported.includes(candidate))
+  return below ?? supported[0] ?? 'off'
+}
+
+/**
+ * The provider value for a supported `level`: the map value, else the level's
+ * own name. `null` means "send nothing" (only `off` can map to `null` here,
+ * because a `null` on any other level makes it unsupported).
+ */
+export function reasoningValue(
+  reasoning: ModelReasoning | undefined,
+  level: ReasoningLevel,
+): string | null {
+  const mapped = reasoning === false ? undefined : reasoning?.map?.[level]
+  return mapped === undefined ? level : mapped
+}
+
+/**
+ * pi's thinking budgets for budget-based models. `xhigh` and `max` get the
+ * `high` budget: budget-based models have no higher level.
+ */
+export const DEFAULT_REASONING_BUDGETS: Readonly<
+  Record<Exclude<ReasoningLevel, 'off'>, number>
+> = {
+  minimal: 1024,
+  low: 2048,
+  medium: 8192,
+  high: 16384,
+  xhigh: 16384,
+  max: 16384,
+}
+
+/** The thinking budget for a request: `budgetTokens`, else pi's table. `0` for `off`. */
+export function reasoningBudget(request: ReasoningRequest): number {
+  if (request.budgetTokens !== undefined) return request.budgetTokens
+  return request.level === 'off' ? 0 : DEFAULT_REASONING_BUDGETS[request.level]
+}
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index 4dd0d51aab..69ec8f9ccf 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -6,6 +6,7 @@ import type { InternalLogger } from './logger/internal-logger'
 import type { SystemPrompt } from './system-prompts'
 import type { CapabilityContext } from './activities/chat/middleware/capabilities'
 import type { InterruptSubmissionError } from './interrupts'
+import type { ReasoningRequest } from './reasoning'
 // The canonical usage types live in the leaf `@tanstack/ai-event-client`
 // package (which `@tanstack/ai` already depends on) so there is a single source
 // of truth without a dependency cycle. They are re-exported below.
@@ -1113,6 +1114,13 @@ export interface TextOptions<
    */
   metadata?: Record<string, any> | undefined
   modelOptions?: TProviderOptionsForModel
+  /**
+   * How hard the model thinks, normalized by `chat()`. `undefined`: the user
+   * did not ask, so the adapter sends nothing and the provider default applies.
+   * The adapter clamps the level to the model's levels and writes its own
+   * wire field.
+   */
+  reasoning?: ReasoningRequest
   request?: Request | RequestInit
 
   /**
diff --git a/packages/ai/tests/reasoning-types.test-d.ts b/packages/ai/tests/reasoning-types.test-d.ts
new file mode 100644
index 0000000000..1ac79527e2
--- /dev/null
+++ b/packages/ai/tests/reasoning-types.test-d.ts
@@ -0,0 +1,46 @@
+import { chat } from '../src'
+import type { TextAdapter } from '../src/activities/chat/adapter'
+import type { DefaultMessageMetadataByModality } from '../src/types'
+
+type Adapter<TReasoning extends { levels: any; budget: boolean }> =
+  TextAdapter<
+    'm',
+    Record<string, never>,
+    readonly ['text'],
+    DefaultMessageMetadataByModality,
+    ReadonlyArray<string>,
+    unknown,
+    never,
+    TReasoning
+  >
+
+declare const effortModel: Adapter<{ levels: 'off' | 'low' | 'high'; budget: false }>
+declare const budgetModel: Adapter<{ levels: 'off' | 'low' | 'medium' | 'high'; budget: true }>
+declare const plainModel: TextAdapter<
+  'm',
+  Record<string, never>,
+  readonly ['text'],
+  DefaultMessageMetadataByModality
+>
+
+const messages = [{ role: 'user' as const, content: 'hi' }]
+
+// A model's own levels, as a string or in the object form.
+chat({ adapter: effortModel, messages, reasoning: 'low' })
+chat({ adapter: effortModel, messages, reasoning: 'off' })
+chat({ adapter: effortModel, messages, reasoning: { level: 'high', summary: false } })
+
+// @ts-expect-error `medium` is not one of this model's levels
+chat({ adapter: effortModel, messages, reasoning: 'medium' })
+
+// @ts-expect-error budgetTokens needs a budget-based model
+chat({ adapter: effortModel, messages, reasoning: { level: 'low', budgetTokens: 1000 } })
+
+// A budget-based model takes budgetTokens.
+chat({ adapter: budgetModel, messages, reasoning: { level: 'medium', budgetTokens: 4000 } })
+
+// @ts-expect-error an adapter that declares no reasoning takes no reasoning option
+chat({ adapter: plainModel, messages, reasoning: 'low' })
+
+// Not passing it is always fine.
+chat({ adapter: plainModel, messages })
diff --git a/packages/ai/tests/reasoning.test.ts b/packages/ai/tests/reasoning.test.ts
new file mode 100644
index 0000000000..873668e7b9
--- /dev/null
+++ b/packages/ai/tests/reasoning.test.ts
@@ -0,0 +1,147 @@
+import { describe, expect, it } from 'vitest'
+import { chat } from '../src'
+import {
+  clampReasoningLevel,
+  normalizeReasoning,
+  reasoningBudget,
+  reasoningValue,
+  supportedReasoningLevels,
+} from '../src/reasoning'
+import { createMockAdapter, ev } from './test-utils'
+import type { ModelReasoning, ReasoningLevel } from '../src/reasoning'
+
+describe('supportedReasoningLevels (pi rules)', () => {
+  it('a model that does not reason supports only off', () => {
+    expect(supportedReasoningLevels(false)).toEqual(['off'])
+  })
+
+  it('a reasoning model with no map supports off to high, not xhigh or max', () => {
+    expect(supportedReasoningLevels({ budget: false })).toEqual([
+      'off',
+      'minimal',
+      'low',
+      'medium',
+      'high',
+    ])
+    expect(supportedReasoningLevels(undefined)).toEqual(
+      supportedReasoningLevels({ budget: false }),
+    )
+  })
+
+  it('drops a level mapped to null, and needs an entry for xhigh and max', () => {
+    const reasoning: ModelReasoning = {
+      budget: false,
+      map: { off: null, minimal: null, medium: null, xhigh: 'xhigh' },
+    }
+    expect(supportedReasoningLevels(reasoning)).toEqual(['low', 'high', 'xhigh'])
+  })
+})
+
+describe('clampReasoningLevel (pi rules)', () => {
+  const lowHighMax: ModelReasoning = {
+    budget: false,
+    map: { off: null, minimal: null, low: 'low', medium: null, high: 'high', max: 'max' },
+  }
+
+  it.each<[ReasoningLevel, ReasoningLevel]>([
+    ['low', 'low'],
+    // Not supported: the nearest level above it.
+    ['medium', 'high'],
+    ['xhigh', 'max'],
+    ['off', 'low'],
+    ['minimal', 'low'],
+  ])('clamps %s to %s', (requested, expected) => {
+    expect(clampReasoningLevel(lowHighMax, requested)).toBe(expected)
+  })
+
+  it('goes below when there is nothing above', () => {
+    expect(clampReasoningLevel({ budget: false }, 'max')).toBe('high')
+    expect(clampReasoningLevel({ budget: false }, 'xhigh')).toBe('high')
+  })
+
+  it('gives off for a model that does not reason', () => {
+    expect(clampReasoningLevel(false, 'high')).toBe('off')
+  })
+})
+
+describe('reasoningValue and reasoningBudget', () => {
+  it('sends the map value, else the level name, and null for "send nothing"', () => {
+    const reasoning: ModelReasoning = {
+      budget: false,
+      map: { off: 'none', high: 'HIGH' },
+    }
+    expect(reasoningValue(reasoning, 'off')).toBe('none')
+    expect(reasoningValue(reasoning, 'high')).toBe('HIGH')
+    expect(reasoningValue(reasoning, 'low')).toBe('low')
+    expect(reasoningValue({ budget: false, map: { off: null } }, 'off')).toBe(
+      null,
+    )
+  })
+
+  it("uses pi's budget table unless budgetTokens is set", () => {
+    expect(reasoningBudget({ level: 'minimal', summary: true })).toBe(1024)
+    expect(reasoningBudget({ level: 'medium', summary: true })).toBe(8192)
+    expect(reasoningBudget({ level: 'max', summary: true })).toBe(16384)
+    expect(reasoningBudget({ level: 'off', summary: true })).toBe(0)
+    expect(
+      reasoningBudget({ level: 'low', summary: true, budgetTokens: 3000 }),
+    ).toBe(3000)
+  })
+})
+
+describe('normalizeReasoning', () => {
+  it('turns a level into a request that asks for the thinking text', () => {
+    expect(normalizeReasoning('high')).toEqual({ level: 'high', summary: true })
+    expect(normalizeReasoning(undefined)).toBeUndefined()
+  })
+
+  it('keeps summary and budgetTokens from the object form', () => {
+    expect(
+      normalizeReasoning({ level: 'low', summary: false, budgetTokens: 500 }),
+    ).toEqual({ level: 'low', summary: false, budgetTokens: 500 })
+  })
+})
+
+describe('chat({ reasoning })', () => {
+  const done = [ev.runStarted(), ev.runFinished('stop')]
+
+  it('passes the normalized request to the adapter', async () => {
+    const { adapter, calls } = createMockAdapter({ iterations: [done] })
+    await chat({
+      adapter,
+      reasoning: 'high',
+      messages: [{ role: 'user', content: 'hi' }],
+      stream: false,
+    })
+    expect(calls[0]?.reasoning).toEqual({ level: 'high', summary: true })
+  })
+
+  it('sends no reasoning when the option is not set', async () => {
+    const { adapter, calls } = createMockAdapter({ iterations: [done] })
+    await chat({
+      adapter,
+      messages: [{ role: 'user', content: 'hi' }],
+      stream: false,
+    })
+    expect(calls[0]).not.toHaveProperty('reasoning')
+  })
+
+  it('lets a middleware change it in onConfig', async () => {
+    const { adapter, calls } = createMockAdapter({ iterations: [done] })
+    await chat({
+      adapter,
+      reasoning: 'low',
+      middleware: [
+        {
+          name: 'more-thinking',
+          onConfig: (_ctx, config) => ({
+            reasoning: { ...config.reasoning, level: 'max', summary: false },
+          }),
+        },
+      ],
+      messages: [{ role: 'user', content: 'hi' }],
+      stream: false,
+    })
+    expect(calls[0]?.reasoning).toEqual({ level: 'max', summary: false })
+  })
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 00ca7fc3a6..7006577049 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2949,6 +2949,21 @@ importers:
         specifier: ^8.2.1
         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-models:
+    devDependencies:
+      '@tanstack/ai':
+        specifier: workspace:*
+        version: link:../ai
+      '@types/node':
+        specifier: ^24.10.1
+        version: 24.13.6
+      '@vitest/coverage-v8':
+        specifier: 4.1.10
+        version: 4.1.10(vitest@4.1.11)
+      vite:
+        specifier: ^8.2.1
+        version: 8.3.0(@types/node@24.13.6)(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-octane:
     dependencies:
       '@tanstack/ai-client':
diff --git a/scripts/fetch-models-dev.ts b/scripts/fetch-models-dev.ts
new file mode 100644
index 0000000000..1fe77a9e04
--- /dev/null
+++ b/scripts/fetch-models-dev.ts
@@ -0,0 +1,137 @@
+/**
+ * Fetches the models.dev catalog and writes the part `@tanstack/ai-models`
+ * and the reasoning sync read to `models-dev.models.json`: the providers in
+ * `packages/ai-models/scripts/providers.ts` and
+ * `scripts/model-sync/reasoning-targets.ts`, the models the borrow list
+ * takes, and only the fields the generators use.
+ *
+ * Usage:
+ *   pnpm tsx scripts/fetch-models-dev.ts
+ *
+ * The output is plain JSON, so an upstream response cannot put code in the
+ * build.
+ */
+
+import { writeFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { PROVIDERS } from '../packages/ai-models/scripts/providers'
+import { BORROW } from '../packages/ai-models/scripts/known-ids'
+import { REASONING_SOURCES } from './model-sync/reasoning-targets'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const OUTPUT_PATH = resolve(__dirname, 'models-dev.models.json')
+const API_URL = 'https://models.dev/api.json'
+
+interface ApiModel {
+  id: string
+  name?: string
+  reasoning?: boolean
+  reasoning_options?: Array<unknown>
+  interleaved?: unknown
+  temperature?: boolean
+  modalities?: { input?: Array<string>; output?: Array<string> }
+  cost?: {
+    input?: number
+    output?: number
+    cache_read?: number
+    cache_write?: number
+  }
+  limit?: { context?: number; output?: number }
+  provider?: { npm?: string; api?: string }
+  canonical_model_id?: string
+  status?: string
+}
+
+interface ApiProvider {
+  id: string
+  name?: string
+  env?: Array<string>
+  npm?: string
+  api?: string
+  models?: Record<string, ApiModel>
+}
+
+const trimModel = (model: ApiModel) => ({
+  id: model.id,
+  name: model.name,
+  reasoning: model.reasoning,
+  reasoning_options: model.reasoning_options,
+  interleaved: model.interleaved,
+  temperature: model.temperature,
+  modalities: model.modalities,
+  cost: model.cost && {
+    input: model.cost.input,
+    output: model.cost.output,
+    cache_read: model.cost.cache_read,
+    cache_write: model.cost.cache_write,
+  },
+  limit: model.limit && {
+    context: model.limit.context,
+    output: model.limit.output,
+  },
+  provider: model.provider && {
+    npm: model.provider.npm,
+    api: model.provider.api,
+  },
+  canonical_model_id: model.canonical_model_id,
+  status: model.status,
+})
+
+async function main() {
+  const response = await fetch(API_URL)
+  if (!response.ok)
+    throw new Error(
+      `models.dev answered ${response.status} ${response.statusText}`,
+    )
+  const catalog = (await response.json()) as Record<string, ApiProvider>
+
+  // Every model of a catalog provider. From the other providers, only the
+  // models the borrow list takes. It names `provider/model`, and model ids
+  // can hold `/` too, so the provider is the part before the first one.
+  // The reasoning sync (`sync-model-reasoning.ts`) reads the provider
+  // packages' own models.dev lists too.
+  const whole = new Set([
+    ...PROVIDERS.flatMap((row) => row.sources),
+    ...REASONING_SOURCES,
+  ])
+  const borrowed = new Map<string, Set<string>>()
+  for (const entries of Object.values(BORROW))
+    for (const source of Object.values(entries)) {
+      const slash = source.indexOf('/')
+      const provider = source.slice(0, slash)
+      if (whole.has(provider)) continue
+      borrowed.set(
+        provider,
+        (borrowed.get(provider) ?? new Set()).add(source.slice(slash + 1)),
+      )
+    }
+
+  const trimmed: Record<string, unknown> = {}
+  for (const id of [...whole, ...borrowed.keys()].sort()) {
+    const provider = catalog[id]
+    if (!provider) {
+      console.warn(`  Warning: models.dev has no provider '${id}'`)
+      continue
+    }
+    const keep = borrowed.get(id)
+    trimmed[id] = {
+      id: provider.id,
+      name: provider.name,
+      env: provider.env,
+      npm: provider.npm,
+      api: provider.api,
+      models: Object.fromEntries(
+        Object.entries(provider.models ?? {})
+          .filter(([key]) => !keep || keep.has(key))
+          .map(([key, model]) => [key, trimModel(model)]),
+      ),
+    }
+  }
+  await writeFile(OUTPUT_PATH, `${JSON.stringify(trimmed, null, 2)}\n`)
+  console.log(
+    `Wrote ${Object.keys(trimmed).length} providers to ${OUTPUT_PATH}`,
+  )
+}
+
+await main()
diff --git a/scripts/generate-ai-models.ts b/scripts/generate-ai-models.ts
new file mode 100644
index 0000000000..babc8712ea
--- /dev/null
+++ b/scripts/generate-ai-models.ts
@@ -0,0 +1,105 @@
+/**
+ * Writes the catalog of `@tanstack/ai-models`:
+ * - `src/providers/<id>.ts`: one file per provider (a subpath export each)
+ * - `src/catalog.ts`: every provider, and the `generatedAt` date
+ * - the `exports` of `package.json`
+ *
+ * Input: `scripts/models-dev.models.json` (from `scripts/fetch-models-dev.ts`)
+ * and the OpenRouter and Vercel lists of the existing fetchers.
+ *
+ * Usage:
+ *   pnpm tsx scripts/generate-ai-models.ts
+ */
+
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { models as openrouterModels } from './openrouter.models'
+import { models as vercelModels } from './vercel-gateway.models'
+import {
+  buildModels,
+  buildProvider,
+} from '../packages/ai-models/scripts/catalog'
+import { PROVIDERS } from '../packages/ai-models/scripts/providers'
+import { fromOpenRouter, fromVercel } from './model-sync/gateway-models'
+import type { DevCatalog } from '../packages/ai-models/scripts/catalog'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const packageDir = resolve(here, '../packages/ai-models')
+const providersDir = resolve(packageDir, 'src/providers')
+
+/** `qwen-token-plan-cn` as `qwenTokenPlanCn`. */
+const identifier = (id: string) =>
+  id.replace(/-([a-z0-9])/g, (_match, char: string) => char.toUpperCase())
+
+const HEADER =
+  '// Generated by scripts/generate-ai-models.ts from models.dev. Do not edit.\n'
+
+async function main() {
+  const dev: DevCatalog = JSON.parse(
+    await readFile(resolve(here, 'models-dev.models.json'), 'utf8'),
+  )
+  const gateways = {
+    openrouter: openrouterModels.map(fromOpenRouter),
+    'vercel-ai-gateway': vercelModels.map(fromVercel),
+  }
+
+  await rm(providersDir, { recursive: true, force: true })
+  await mkdir(providersDir, { recursive: true })
+  let total = 0
+  for (const row of PROVIDERS) {
+    const models = buildModels(row, { dev, gateways })
+    const provider = buildProvider(row, models)
+    total += models.length
+    await writeFile(
+      resolve(providersDir, `${row.id}.ts`),
+      `${HEADER}import type { ModelRecord, ProviderRecord } from '../types'
+
+/** ${row.name}. */
+export const provider: ProviderRecord = ${JSON.stringify(provider)}
+
+/** Every ${row.name} model, sorted by id. */
+export const models: ReadonlyArray<ModelRecord> = ${JSON.stringify(models)}
+`,
+    )
+  }
+
+  const ids = PROVIDERS.map((row) => row.id)
+  const generatedAt = new Date().toISOString().slice(0, 10)
+  await writeFile(
+    resolve(packageDir, 'src/catalog.ts'),
+    `${HEADER}${ids
+      .map((id) => `import * as ${identifier(id)} from './providers/${id}'`)
+      .join('\n')}
+
+/** The day the catalog was generated, as \`YYYY-MM-DD\`. */
+export const generatedAt = '${generatedAt}'
+
+/** Every provider module, in id order. */
+export const providerModules = [${ids.map(identifier).join(', ')}]
+`,
+  )
+
+  // One subpath per provider, so a build ships only the providers it uses.
+  const packageJsonPath = resolve(packageDir, 'package.json')
+  const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8'))
+  packageJson.exports = {
+    '.': {
+      types: './dist/esm/index.d.ts',
+      import: './dist/esm/index.js',
+    },
+    ...Object.fromEntries(
+      ids.map((id) => [
+        `./${id}`,
+        {
+          types: `./dist/esm/providers/${id}.d.ts`,
+          import: `./dist/esm/providers/${id}.js`,
+        },
+      ]),
+    ),
+  }
+  await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`)
+  console.log(`Wrote ${ids.length} providers and ${total} models.`)
+}
+
+await main()
diff --git a/scripts/model-sync/gateway-models.ts b/scripts/model-sync/gateway-models.ts
new file mode 100644
index 0000000000..e05c030114
--- /dev/null
+++ b/scripts/model-sync/gateway-models.ts
@@ -0,0 +1,87 @@
+/**
+ * The OpenRouter and Vercel AI Gateway model lists, in models.dev's shape, so
+ * the model-catalog and reasoning generators read one format.
+ */
+
+import type { OpenRouterModel } from '../openrouter.models'
+import type { VercelGatewayCatalogModel } from '../vercel-gateway.models'
+import type {
+  DevModel,
+  ReasoningOptionEntry,
+} from '../../packages/ai-models/scripts/rules'
+
+/** A price per token (a string) as USD per 1M tokens. */
+function perMillion(price: unknown): number | undefined {
+  const value = typeof price === 'string' ? Number(price) : undefined
+  if (value === undefined || !Number.isFinite(value) || value < 0)
+    return undefined
+  return Math.round(value * 1e12) / 1e6
+}
+
+const inputKind = (kind: string) => (kind === 'file' ? 'pdf' : kind)
+
+/** An OpenRouter API model in models.dev's shape. */
+export function fromOpenRouter(model: OpenRouterModel): DevModel {
+  const params = model.supported_parameters ?? []
+  const efforts = model.reasoning?.supported_efforts
+  return {
+    id: model.id,
+    name: model.name,
+    reasoning: params.includes('reasoning'),
+    ...(efforts?.length
+      ? { reasoning_options: [{ type: 'effort', values: efforts }] }
+      : {}),
+    temperature: params.includes('temperature'),
+    modalities: {
+      input: model.architecture.input_modalities.map(inputKind),
+      output: model.architecture.output_modalities,
+    },
+    cost: {
+      input: perMillion(model.pricing.prompt),
+      output: perMillion(model.pricing.completion),
+      cache_read: perMillion(model.pricing.input_cache_read),
+      cache_write: perMillion(model.pricing.input_cache_write),
+    },
+    limit: {
+      context: model.context_length,
+      output: model.top_provider.max_completion_tokens ?? undefined,
+    },
+  }
+}
+
+/** A Vercel AI Gateway model in models.dev's shape. */
+export function fromVercel(model: VercelGatewayCatalogModel): DevModel {
+  const pricing =
+    typeof model.pricing === 'object' && model.pricing !== null
+      ? (model.pricing as Record<string, unknown>)
+      : {}
+  const options = Array.isArray(model.reasoning_options)
+    ? (model.reasoning_options as ReadonlyArray<ReasoningOptionEntry>)
+    : undefined
+  const params = model.supported_parameters ?? []
+  return {
+    id: model.id,
+    name: typeof model.name === 'string' ? model.name : model.id,
+    reasoning:
+      params.includes('reasoning') || (model.tags ?? []).includes('reasoning'),
+    ...(options ? { reasoning_options: options } : {}),
+    ...(typeof model.temperature === 'boolean'
+      ? { temperature: model.temperature }
+      : {}),
+    modalities: {
+      input: (model.modalities?.input ?? ['text']).map(inputKind),
+      output: model.modalities?.output ?? ['text'],
+    },
+    cost: {
+      input: perMillion(pricing.input),
+      output: perMillion(pricing.output),
+      cache_read: perMillion(pricing.input_cache_read),
+      cache_write: perMillion(pricing.input_cache_write),
+    },
+    limit: {
+      context:
+        typeof model.context_window === 'number' ? model.context_window : 0,
+      output: typeof model.max_tokens === 'number' ? model.max_tokens : 0,
+    },
+  }
+}
diff --git a/scripts/model-sync/reasoning-drift.test.ts b/scripts/model-sync/reasoning-drift.test.ts
new file mode 100644
index 0000000000..7be608ef30
--- /dev/null
+++ b/scripts/model-sync/reasoning-drift.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest'
+import { getModel } from '../../packages/ai-models/src'
+import { ANTHROPIC_MODEL_REASONING } from '../../packages/ai-anthropic/src/model-reasoning'
+import { BEDROCK_MODEL_REASONING } from '../../packages/ai-bedrock/src/model-reasoning'
+import { CLOUDFLARE_MODEL_REASONING } from '../../packages/ai-cloudflare/src/model-reasoning'
+import { GEMINI_MODEL_REASONING } from '../../packages/ai-gemini/src/model-reasoning'
+import { GROK_MODEL_REASONING } from '../../packages/ai-grok/src/model-reasoning'
+import { GROQ_MODEL_REASONING } from '../../packages/ai-groq/src/model-reasoning'
+import { MISTRAL_MODEL_REASONING } from '../../packages/ai-mistral/src/model-reasoning'
+import { OPENAI_MODEL_REASONING } from '../../packages/ai-openai/src/model-reasoning'
+import { OPENROUTER_MODEL_REASONING } from '../../packages/ai-openrouter/src/model-reasoning'
+import { VERCEL_GATEWAY_MODEL_REASONING } from '../../packages/ai-vercel-gateway/src/model-reasoning'
+import type { ModelReasoning } from '../../packages/ai/src/reasoning'
+
+// A provider package and the catalog read the same models.dev data. For a
+// model that is in both, the reasoning levels must be the same.
+const PAIRS: ReadonlyArray<
+  readonly [string, string, Readonly<Record<string, ModelReasoning>>]
+> = [
+  ['ai-openai', 'openai', OPENAI_MODEL_REASONING],
+  ['ai-anthropic', 'anthropic', ANTHROPIC_MODEL_REASONING],
+  ['ai-gemini', 'google', GEMINI_MODEL_REASONING],
+  ['ai-grok', 'xai', GROK_MODEL_REASONING],
+  ['ai-groq', 'groq', GROQ_MODEL_REASONING],
+  ['ai-openrouter', 'openrouter', OPENROUTER_MODEL_REASONING],
+  ['ai-bedrock', 'amazon-bedrock', BEDROCK_MODEL_REASONING],
+  ['ai-mistral', 'mistral', MISTRAL_MODEL_REASONING],
+  ['ai-vercel-gateway', 'vercel-ai-gateway', VERCEL_GATEWAY_MODEL_REASONING],
+  ['ai-cloudflare', 'cloudflare-workers-ai', CLOUDFLARE_MODEL_REASONING],
+]
+
+describe('reasoning drift between provider packages and @tanstack/ai-models', () => {
+  it.each(PAIRS)('%s matches the %s catalog', (_pkg, provider, reasoning) => {
+    let compared = 0
+    for (const [id, own] of Object.entries(reasoning)) {
+      const record = getModel(provider, id)
+      if (!record) continue
+      compared++
+      const fromCatalog: ModelReasoning = record.reasoning
+        ? {
+            ...(record.reasoningMap ? { map: record.reasoningMap } : {}),
+            budget: record.reasoningBudget === true,
+          }
+        : false
+      expect(own, `${provider}/${id}`).toEqual(fromCatalog)
+    }
+    expect(compared).toBeGreaterThan(0)
+  })
+})
diff --git a/scripts/model-sync/reasoning-targets.ts b/scripts/model-sync/reasoning-targets.ts
new file mode 100644
index 0000000000..8e4fe1bd9b
--- /dev/null
+++ b/scripts/model-sync/reasoning-targets.ts
@@ -0,0 +1,180 @@
+/**
+ * The provider packages whose `src/model-reasoning.ts` the reasoning sync
+ * writes, and where it finds each package's models on models.dev.
+ */
+export interface ReasoningTarget {
+  /** The folder under `packages/`. */
+  pkg: string
+  /**
+   * The module (under the package's `src/`) and the arrays in it that list
+   * the chat models. `undefined`: use every model of the first source.
+   */
+  models?: { module: string; lists: ReadonlyArray<string> }
+  /** `${typePrefix}ModelReasoningByName` and `${constPrefix}_MODEL_REASONING`. */
+  typePrefix: string
+  constPrefix: string
+  /** models.dev providers to look in first, by the exact model id. */
+  sources: ReadonlyArray<string>
+  /** A gateway list to look in by the exact model id. */
+  gateway?: 'openrouter' | 'vercel'
+  /** Model ids that name another model, as `provider/model`. */
+  aliases?: Readonly<Record<string, string>>
+}
+
+export const REASONING_TARGETS: ReadonlyArray<ReasoningTarget> = [
+  {
+    pkg: 'ai-openai',
+    models: { module: 'model-meta', lists: ['OPENAI_CHAT_MODELS'] },
+    typePrefix: 'OpenAI',
+    constPrefix: 'OPENAI',
+    sources: ['openai'],
+  },
+  {
+    pkg: 'ai-anthropic',
+    models: {
+      module: 'model-meta',
+      lists: ['ANTHROPIC_MODELS', 'ANTHROPIC_VERTEX_CHAT_MODELS'],
+    },
+    typePrefix: 'Anthropic',
+    constPrefix: 'ANTHROPIC',
+    sources: ['anthropic', 'google-vertex-anthropic'],
+  },
+  {
+    pkg: 'ai-gemini',
+    models: { module: 'model-meta', lists: ['GEMINI_MODELS'] },
+    typePrefix: 'Gemini',
+    constPrefix: 'GEMINI',
+    sources: ['google', 'google-vertex'],
+  },
+  {
+    pkg: 'ai-grok',
+    models: {
+      module: 'model-meta',
+      lists: ['GROK_CHAT_MODELS', 'GROK_VERTEX_CHAT_MODELS'],
+    },
+    typePrefix: 'Grok',
+    constPrefix: 'GROK',
+    sources: ['xai'],
+  },
+  {
+    pkg: 'ai-grok-build',
+    models: { module: 'model-meta', lists: ['GROK_BUILD_MODELS'] },
+    typePrefix: 'GrokBuild',
+    constPrefix: 'GROK_BUILD',
+    sources: ['xai'],
+    aliases: { 'grok-build': 'xai/grok-build-0.1' },
+  },
+  {
+    pkg: 'ai-groq',
+    models: { module: 'model-meta', lists: ['GROQ_CHAT_MODELS'] },
+    typePrefix: 'Groq',
+    constPrefix: 'GROQ',
+    sources: ['groq'],
+  },
+  {
+    pkg: 'ai-openrouter',
+    models: { module: 'model-meta', lists: ['OPENROUTER_CHAT_MODELS'] },
+    typePrefix: 'OpenRouter',
+    constPrefix: 'OPENROUTER',
+    sources: ['openrouter'],
+    gateway: 'openrouter',
+  },
+  {
+    pkg: 'ai-bedrock',
+    models: {
+      module: 'model-meta',
+      lists: [
+        'BEDROCK_CONVERSE_MODELS',
+        'BEDROCK_CHAT_MODELS',
+        'BEDROCK_RESPONSES_MODELS',
+      ],
+    },
+    typePrefix: 'Bedrock',
+    constPrefix: 'BEDROCK',
+    sources: ['amazon-bedrock'],
+  },
+  {
+    pkg: 'ai-mistral',
+    models: {
+      module: 'model-meta',
+      lists: ['MISTRAL_CHAT_MODELS', 'MISTRAL_VERTEX_CHAT_MODELS'],
+    },
+    typePrefix: 'Mistral',
+    constPrefix: 'MISTRAL',
+    sources: ['mistral'],
+  },
+  {
+    pkg: 'ai-ollama',
+    models: { module: 'model-meta', lists: ['OLLAMA_TEXT_MODELS'] },
+    typePrefix: 'Ollama',
+    constPrefix: 'OLLAMA',
+    sources: ['ollama-cloud'],
+  },
+  {
+    pkg: 'ai-byteplus',
+    models: { module: 'model-meta', lists: ['BYTEPLUS_CHAT_MODELS'] },
+    typePrefix: 'BytePlus',
+    constPrefix: 'BYTEPLUS',
+    sources: ['volcengine'],
+  },
+  {
+    pkg: 'ai-llmgateway',
+    models: { module: 'model-meta', lists: ['LLMGATEWAY_CHAT_MODELS'] },
+    typePrefix: 'LLMGateway',
+    constPrefix: 'LLMGATEWAY',
+    sources: ['llmgateway'],
+  },
+  {
+    pkg: 'ai-lovable',
+    models: { module: 'model-meta', lists: ['LOVABLE_CHAT_MODELS'] },
+    typePrefix: 'Lovable',
+    constPrefix: 'LOVABLE',
+    sources: [],
+  },
+  {
+    pkg: 'ai-opencode',
+    models: { module: 'model-meta', lists: ['OPENCODE_MODELS'] },
+    typePrefix: 'OpenCode',
+    constPrefix: 'OPENCODE',
+    sources: ['opencode'],
+  },
+  {
+    pkg: 'ai-vercel-gateway',
+    models: { module: 'model-meta', lists: ['VERCEL_GATEWAY_CHAT_MODELS'] },
+    typePrefix: 'VercelGateway',
+    constPrefix: 'VERCEL_GATEWAY',
+    sources: ['vercel'],
+    gateway: 'vercel',
+  },
+  {
+    pkg: 'ai-claude-code',
+    models: { module: 'model-meta', lists: ['CLAUDE_CODE_MODELS'] },
+    typePrefix: 'ClaudeCode',
+    constPrefix: 'CLAUDE_CODE',
+    sources: ['anthropic'],
+    // The CLI aliases pick its newest model of each family.
+    aliases: {
+      opus: 'anthropic/claude-opus-4-8',
+      sonnet: 'anthropic/claude-sonnet-4-6',
+      haiku: 'anthropic/claude-haiku-4-5',
+    },
+  },
+  {
+    pkg: 'ai-codex',
+    models: { module: 'model-meta', lists: ['CODEX_MODELS'] },
+    typePrefix: 'Codex',
+    constPrefix: 'CODEX',
+    sources: ['openai'],
+  },
+  {
+    pkg: 'ai-cloudflare',
+    typePrefix: 'Cloudflare',
+    constPrefix: 'CLOUDFLARE',
+    sources: ['cloudflare-workers-ai'],
+  },
+]
+
+/** The models.dev providers the reasoning sync reads. */
+export const REASONING_SOURCES: ReadonlyArray<string> = [
+  ...new Set(REASONING_TARGETS.flatMap((target) => target.sources)),
+]
diff --git a/scripts/models-dev.models.json b/scripts/models-dev.models.json
new file mode 100644
index 0000000000..5ffe45aa3f
--- /dev/null
+++ b/scripts/models-dev.models.json
@@ -0,0 +1,55292 @@
+{
+  "alibaba": {
+    "id": "alibaba",
+    "name": "Alibaba",
+    "env": ["DASHSCOPE_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
+    "models": {
+      "qwen-flash": {
+        "id": "qwen-flash",
+        "name": "Qwen Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.4
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 32768
+        }
+      },
+      "qwen3.5-flash": {
+        "id": "qwen3.5-flash",
+        "name": "Qwen3.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 81920
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.4,
+          "cache_read": 0.01,
+          "cache_write": 0.125
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.5-flash"
+      },
+      "qwen3.7-max": {
+        "id": "qwen3.7-max",
+        "name": "Qwen3.7 Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 7.5,
+          "cache_read": 0.5,
+          "cache_write": 3.125
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        }
+      },
+      "qwen2-5-32b-instruct": {
+        "id": "qwen2-5-32b-instruct",
+        "name": "Qwen2.5 32B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.7,
+          "output": 2.8
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwq-plus": {
+        "id": "qwq-plus",
+        "name": "QwQ Plus",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.8,
+          "output": 2.4
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen2-5-vl-72b-instruct": {
+        "id": "qwen2-5-vl-72b-instruct",
+        "name": "Qwen2.5-VL 72B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.8,
+          "output": 8.4
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen3-vl-plus": {
+        "id": "qwen3-vl-plus",
+        "name": "Qwen3-VL Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.6
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "qwen3.5-27b": {
+        "id": "qwen3.5-27b",
+        "name": "Qwen3.5 27B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.4
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "deepseek-v4-flash-0731": {
+        "id": "deepseek-v4-flash-0731",
+        "name": "DeepSeek V4 Flash 0731",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.4,
+          "cache_read": 0.04
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-0731"
+      },
+      "qwen-max": {
+        "id": "qwen-max",
+        "name": "Qwen Max",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.6,
+          "output": 6.4
+        },
+        "limit": {
+          "context": 32768,
+          "output": 8192
+        }
+      },
+      "qwen3-next-80b-a3b-thinking": {
+        "id": "qwen3-next-80b-a3b-thinking",
+        "name": "Qwen3-Next 80B-A3B (Thinking)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 6
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "qwen3.8-max": {
+        "id": "qwen3.8-max",
+        "name": "Qwen3.8 Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 0,
+            "max": 262144
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.25,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-max"
+      },
+      "kimi-k3": {
+        "id": "kimi-k3",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "qwen-plus-character-ja": {
+        "id": "qwen-plus-character-ja",
+        "name": "Qwen Plus Character (Japanese)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.4
+        },
+        "limit": {
+          "context": 8192,
+          "output": 512
+        }
+      },
+      "qwen3.5-plus": {
+        "id": "qwen3.5-plus",
+        "name": "Qwen3.5 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2.4
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        }
+      },
+      "qwen3-livetranslate-flash-realtime": {
+        "id": "qwen3-livetranslate-flash-realtime",
+        "name": "Qwen3-LiveTranslate Flash Realtime",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 10
+        },
+        "limit": {
+          "context": 53248,
+          "output": 4096
+        }
+      },
+      "qwen2-5-72b-instruct": {
+        "id": "qwen2-5-72b-instruct",
+        "name": "Qwen2.5 72B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 5.6
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen3-32b": {
+        "id": "qwen3-32b",
+        "name": "Qwen3 32B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.7,
+          "output": 2.8
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        }
+      },
+      "qwen-plus": {
+        "id": "qwen-plus",
+        "name": "Qwen Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 32768
+        }
+      },
+      "qwen3.7-flash": {
+        "id": "qwen3.7-flash",
+        "name": "Qwen3.7 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 262144
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.03,
+          "output": 0.13,
+          "cache_read": 0.003,
+          "cache_write": 0.0375
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.7-flash"
+      },
+      "qwen3-max": {
+        "id": "qwen3-max",
+        "name": "Qwen3 Max",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.2,
+          "output": 6
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "qwen-omni-turbo-realtime": {
+        "id": "qwen-omni-turbo-realtime",
+        "name": "Qwen-Omni Turbo Realtime",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0.27,
+          "output": 1.07
+        },
+        "limit": {
+          "context": 32768,
+          "output": 2048
+        }
+      },
+      "qwen3-coder-480b-a35b-instruct": {
+        "id": "qwen3-coder-480b-a35b-instruct",
+        "name": "Qwen3-Coder 480B-A35B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 7.5
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "qwen-turbo": {
+        "id": "qwen-turbo",
+        "name": "Qwen Turbo",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 16384
+        }
+      },
+      "qwen3-coder-30b-a3b-instruct": {
+        "id": "qwen3-coder-30b-a3b-instruct",
+        "name": "Qwen3-Coder 30B-A3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.45,
+          "output": 2.25
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "qwen3.8-omni-flash": {
+        "id": "qwen3.8-omni-flash",
+        "name": "Qwen3.8 Omni Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "xhigh"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.47,
+          "cache_read": 0.016
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-omni-flash"
+      },
+      "qvq-max": {
+        "id": "qvq-max",
+        "name": "QVQ Max",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.2,
+          "output": 4.8
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen2-5-7b-instruct": {
+        "id": "qwen2-5-7b-instruct",
+        "name": "Qwen2.5 7B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.175,
+          "output": 0.7
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen3-omni-flash": {
+        "id": "qwen3-omni-flash",
+        "name": "Qwen3-Omni Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0.43,
+          "output": 1.66
+        },
+        "limit": {
+          "context": 65536,
+          "output": 16384
+        }
+      },
+      "qwen-vl-max": {
+        "id": "qwen-vl-max",
+        "name": "Qwen-VL Max",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.8,
+          "output": 3.2
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen3-235b-a22b": {
+        "id": "qwen3-235b-a22b",
+        "name": "Qwen3 235B-A22B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.7,
+          "output": 2.8
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        }
+      },
+      "qwen3-vl-30b-a3b": {
+        "id": "qwen3-vl-30b-a3b",
+        "name": "Qwen3-VL 30B-A3B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.8
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "qwen3.5-122b-a10b": {
+        "id": "qwen3.5-122b-a10b",
+        "name": "Qwen3.5 122B-A10B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 3.2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "qwen3.6-35b-a3b": {
+        "id": "qwen3.6-35b-a3b",
+        "name": "Qwen3.6 35B-A3B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.248,
+          "output": 1.485
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "qwen3-next-80b-a3b-instruct": {
+        "id": "qwen3-next-80b-a3b-instruct",
+        "name": "Qwen3-Next 80B-A3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 2
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "qwen-vl-plus": {
+        "id": "qwen-vl-plus",
+        "name": "Qwen-VL Plus",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.21,
+          "output": 0.63
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen3.6-flash": {
+        "id": "qwen3.6-flash",
+        "name": "Qwen3.6 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1875,
+          "output": 1.125,
+          "cache_write": 0.234375
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        }
+      },
+      "qwen3-coder-flash": {
+        "id": "qwen3-coder-flash",
+        "name": "Qwen3 Coder Flash",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        }
+      },
+      "qwen2-5-omni-7b": {
+        "id": "qwen2-5-omni-7b",
+        "name": "Qwen2.5-Omni 7B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.4
+        },
+        "limit": {
+          "context": 32768,
+          "output": 2048
+        }
+      },
+      "qwen-mt-plus": {
+        "id": "qwen-mt-plus",
+        "name": "Qwen-MT Plus",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.46,
+          "output": 7.37
+        },
+        "limit": {
+          "context": 16384,
+          "output": 8192
+        }
+      },
+      "qwen3-vl-235b-a22b": {
+        "id": "qwen3-vl-235b-a22b",
+        "name": "Qwen3-VL 235B-A22B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.7,
+          "output": 2.8
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "qwen3-coder-plus": {
+        "id": "qwen3-coder-plus",
+        "name": "Qwen3 Coder Plus",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 5
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        }
+      },
+      "qwen2-5-14b-instruct": {
+        "id": "qwen2-5-14b-instruct",
+        "name": "Qwen2.5 14B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.35,
+          "output": 1.4
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen3.8-flash": {
+        "id": "qwen3.8-flash",
+        "name": "Qwen3.8 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          },
+          {
+            "type": "budget_tokens",
+            "max": 262144
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.47,
+          "cache_read": 0.016,
+          "cache_write": 0.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-flash"
+      },
+      "qwen2-5-vl-7b-instruct": {
+        "id": "qwen2-5-vl-7b-instruct",
+        "name": "Qwen2.5-VL 7B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.35,
+          "output": 1.05
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen3.5-35b-a3b": {
+        "id": "qwen3.5-35b-a3b",
+        "name": "Qwen3.5 35B-A3B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "qwen3.6-max-preview": {
+        "id": "qwen3.6-max-preview",
+        "name": "Qwen3.6 Max Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.3,
+          "output": 7.8,
+          "cache_read": 0.13,
+          "cache_write": 1.625
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "qwen-mt-turbo": {
+        "id": "qwen-mt-turbo",
+        "name": "Qwen-MT Turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.16,
+          "output": 0.49
+        },
+        "limit": {
+          "context": 16384,
+          "output": 8192
+        }
+      },
+      "qwen3.5-397b-a17b": {
+        "id": "qwen3.5-397b-a17b",
+        "name": "Qwen3.5 397B-A17B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3.6
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "qwen3-8b": {
+        "id": "qwen3-8b",
+        "name": "Qwen3 8B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.18,
+          "output": 0.7
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "glm-5.2": {
+        "id": "glm-5.2",
+        "name": "GLM-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.28,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "qwen-omni-turbo": {
+        "id": "qwen-omni-turbo",
+        "name": "Qwen-Omni Turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.27
+        },
+        "limit": {
+          "context": 32768,
+          "output": 2048
+        }
+      },
+      "qwen3-omni-flash-realtime": {
+        "id": "qwen3-omni-flash-realtime",
+        "name": "Qwen3-Omni Flash Realtime",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0.52,
+          "output": 1.99
+        },
+        "limit": {
+          "context": 65536,
+          "output": 16384
+        }
+      },
+      "qwen3-asr-flash": {
+        "id": "qwen3-asr-flash",
+        "name": "Qwen3-ASR Flash",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.035,
+          "output": 0.035
+        },
+        "limit": {
+          "context": 53248,
+          "output": 4096
+        }
+      },
+      "qwen3.6-27b": {
+        "id": "qwen3.6-27b",
+        "name": "Qwen3.6 27B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3.6
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "qwen3.6-plus": {
+        "id": "qwen3.6-plus",
+        "name": "Qwen3.6 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.05,
+          "cache_write": 0.625
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        }
+      },
+      "qwen3-14b": {
+        "id": "qwen3-14b",
+        "name": "Qwen3 14B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.35,
+          "output": 1.4
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen3.7-plus": {
+        "id": "qwen3.7-plus",
+        "name": "Qwen3.7 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 1.6,
+          "cache_read": 0.04,
+          "cache_write": 0.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        }
+      },
+      "qwen-vl-ocr": {
+        "id": "qwen-vl-ocr",
+        "name": "Qwen-VL OCR",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.72,
+          "output": 0.72
+        },
+        "limit": {
+          "context": 34096,
+          "output": 4096
+        }
+      }
+    }
+  },
+  "alibaba-cn": {
+    "id": "alibaba-cn",
+    "name": "Alibaba (China)",
+    "env": ["DASHSCOPE_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+    "models": {
+      "qwen-flash": {
+        "id": "qwen-flash",
+        "name": "Qwen Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 81920
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.022,
+          "output": 0.216
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 32768
+        }
+      },
+      "qwen3.5-flash": {
+        "id": "qwen3.5-flash",
+        "name": "Qwen3.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 81920
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.029,
+          "output": 0.287
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        }
+      },
+      "qwen2-5-coder-32b-instruct": {
+        "id": "qwen2-5-coder-32b-instruct",
+        "name": "Qwen2.5-Coder 32B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.287,
+          "output": 0.861
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "deepseek-v3-2-exp": {
+        "id": "deepseek-v3-2-exp",
+        "name": "DeepSeek V3.2 Exp",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.287,
+          "output": 0.431
+        },
+        "limit": {
+          "context": 131072,
+          "output": 65536
+        }
+      },
+      "deepseek-r1-distill-qwen-14b": {
+        "id": "deepseek-r1-distill-qwen-14b",
+        "name": "DeepSeek R1 Distill Qwen 14B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.144,
+          "output": 0.431
+        },
+        "limit": {
+          "context": 32768,
+          "output": 16384
+        }
+      },
+      "qwen-math-plus": {
+        "id": "qwen-math-plus",
+        "name": "Qwen Math Plus",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.574,
+          "output": 1.721
+        },
+        "limit": {
+          "context": 4096,
+          "output": 3072
+        }
+      },
+      "qwen-deep-research": {
+        "id": "qwen-deep-research",
+        "name": "Qwen Deep Research",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 7.742,
+          "output": 23.367
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 32768
+        }
+      },
+      "qwen3.7-max": {
+        "id": "qwen3.7-max",
+        "name": "Qwen3.7 Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 262144
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 7.5,
+          "cache_read": 0.5,
+          "cache_write": 3.125
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.7-max"
+      },
+      "qwen2-5-32b-instruct": {
+        "id": "qwen2-5-32b-instruct",
+        "name": "Qwen2.5 32B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.287,
+          "output": 0.861
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwq-plus": {
+        "id": "qwq-plus",
+        "name": "QwQ Plus",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.23,
+          "output": 0.574
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwq-32b": {
+        "id": "qwq-32b",
+        "name": "QwQ 32B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.287,
+          "output": 0.861
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen2-5-vl-72b-instruct": {
+        "id": "qwen2-5-vl-72b-instruct",
+        "name": "Qwen2.5-VL 72B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.294,
+          "output": 6.881
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "deepseek-v3-1": {
+        "id": "deepseek-v3-1",
+        "name": "DeepSeek V3.1",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.574,
+          "output": 1.721
+        },
+        "limit": {
+          "context": 131072,
+          "output": 65536
+        }
+      },
+      "qwen3-vl-plus": {
+        "id": "qwen3-vl-plus",
+        "name": "Qwen3-VL Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 81920
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.143353,
+          "output": 1.433525
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "qwen-plus-character": {
+        "id": "qwen-plus-character",
+        "name": "Qwen Plus Character",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.115,
+          "output": 0.287
+        },
+        "limit": {
+          "context": 32768,
+          "output": 4096
+        }
+      },
+      "qwen-max": {
+        "id": "qwen-max",
+        "name": "Qwen Max",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.345,
+          "output": 1.377
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen3-next-80b-a3b-thinking": {
+        "id": "qwen3-next-80b-a3b-thinking",
+        "name": "Qwen3-Next 80B-A3B (Thinking)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.144,
+          "output": 1.434
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "qwen3.8-max": {
+        "id": "qwen3.8-max",
+        "name": "Qwen3.8 Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 0,
+            "max": 262144
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.77744,
+          "output": 5.33231,
+          "cache_read": 0.22218,
+          "cache_write": 2.22179
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-max"
+      },
+      "kimi-k3": {
+        "id": "kimi-k3",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.827,
+          "output": 14.133,
+          "cache_read": 0.283
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "qwen2-5-math-7b-instruct": {
+        "id": "qwen2-5-math-7b-instruct",
+        "name": "Qwen2.5-Math 7B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.144,
+          "output": 0.287
+        },
+        "limit": {
+          "context": 4096,
+          "output": 3072
+        }
+      },
+      "qwen3.5-plus": {
+        "id": "qwen3.5-plus",
+        "name": "Qwen3.5 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 81920
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.115,
+          "output": 0.688
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        }
+      },
+      "qwen2-5-72b-instruct": {
+        "id": "qwen2-5-72b-instruct",
+        "name": "Qwen2.5 72B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.574,
+          "output": 1.721
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "glm-5": {
+        "id": "glm-5",
+        "name": "GLM-5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 32768
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.573,
+          "output": 2.58
+        },
+        "limit": {
+          "context": 202752,
+          "output": 16384
+        }
+      },
+      "deepseek-v4.1-flash": {
+        "id": "deepseek-v4.1-flash",
+        "name": "DeepSeek V4.1 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.29754,
+          "output": 1.19015,
+          "cache_read": 0.01488
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4.1-flash"
+      },
+      "deepseek-r1-distill-llama-8b": {
+        "id": "deepseek-r1-distill-llama-8b",
+        "name": "DeepSeek R1 Distill Llama 8B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 32768,
+          "output": 16384
+        }
+      },
+      "qwen3-32b": {
+        "id": "qwen3-32b",
+        "name": "Qwen3 32B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 38912
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.287,
+          "output": 1.147
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        }
+      },
+      "qwen2-5-coder-7b-instruct": {
+        "id": "qwen2-5-coder-7b-instruct",
+        "name": "Qwen2.5-Coder 7B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.144,
+          "output": 0.287
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen-plus": {
+        "id": "qwen-plus",
+        "name": "Qwen Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 81920
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.115,
+          "output": 0.287,
+          "cache_read": 0.012,
+          "cache_write": 0.144
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 32768
+        }
+      },
+      "qwen3.7-flash": {
+        "id": "qwen3.7-flash",
+        "name": "Qwen3.7 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 262144
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.02962,
+          "output": 0.1185,
+          "cache_read": 0.002962,
+          "cache_write": 0.03703
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.7-flash"
+      },
+      "kimi-k2.6": {
+        "id": "kimi-k2.6",
+        "name": "Moonshot Kimi K2.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 81920
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.929,
+          "output": 3.858
+        },
+        "limit": {
+          "context": 262144,
+          "output": 16384
+        }
+      },
+      "qwen3-max": {
+        "id": "qwen3-max",
+        "name": "Qwen3 Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 81920
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.359,
+          "output": 1.434
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "qwen-omni-turbo-realtime": {
+        "id": "qwen-omni-turbo-realtime",
+        "name": "Qwen-Omni Turbo Realtime",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0.23,
+          "output": 0.918
+        },
+        "limit": {
+          "context": 32768,
+          "output": 2048
+        }
+      },
+      "deepseek-v3": {
+        "id": "deepseek-v3",
+        "name": "DeepSeek V3",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.287,
+          "output": 1.147
+        },
+        "limit": {
+          "context": 65536,
+          "output": 8192
+        }
+      },
+      "deepseek-r1-distill-llama-70b": {
+        "id": "deepseek-r1-distill-llama-70b",
+        "name": "DeepSeek R1 Distill Llama 70B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.287,
+          "output": 0.861
+        },
+        "limit": {
+          "context": 32768,
+          "output": 16384
+        }
+      },
+      "qwen3-coder-480b-a35b-instruct": {
+        "id": "qwen3-coder-480b-a35b-instruct",
+        "name": "Qwen3-Coder 480B-A35B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.861,
+          "output": 3.441
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "qwen-turbo": {
+        "id": "qwen-turbo",
+        "name": "Qwen Turbo",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 38912
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.044,
+          "output": 0.087
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 16384
+        }
+      },
+      "deepseek-r1-distill-qwen-7b": {
+        "id": "deepseek-r1-distill-qwen-7b",
+        "name": "DeepSeek R1 Distill Qwen 7B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.072,
+          "output": 0.144
+        },
+        "limit": {
+          "context": 32768,
+          "output": 16384
+        }
+      },
+      "qwen2-5-math-72b-instruct": {
+        "id": "qwen2-5-math-72b-instruct",
+        "name": "Qwen2.5-Math 72B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.574,
+          "output": 1.721
+        },
+        "limit": {
+          "context": 4096,
+          "output": 3072
+        }
+      },
+      "qwen3-coder-30b-a3b-instruct": {
+        "id": "qwen3-coder-30b-a3b-instruct",
+        "name": "Qwen3-Coder 30B-A3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.216,
+          "output": 0.861
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "qwen-doc-turbo": {
+        "id": "qwen-doc-turbo",
+        "name": "Qwen Doc Turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.087,
+          "output": 0.144
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "kimi-k2-thinking": {
+        "id": "kimi-k2-thinking",
+        "name": "Moonshot Kimi K2 Thinking",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.574,
+          "output": 2.294
+        },
+        "limit": {
+          "context": 262144,
+          "output": 16384
+        }
+      },
+      "qwen3.8-omni-flash": {
+        "id": "qwen3.8-omni-flash",
+        "name": "Qwen3.8 Omni Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "xhigh"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.113,
+          "output": 0.382,
+          "cache_read": 0.014
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-omni-flash"
+      },
+      "qvq-max": {
+        "id": "qvq-max",
+        "name": "QVQ Max",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.147,
+          "output": 4.588
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen2-5-7b-instruct": {
+        "id": "qwen2-5-7b-instruct",
+        "name": "Qwen2.5 7B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.072,
+          "output": 0.144
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen3-omni-flash": {
+        "id": "qwen3-omni-flash",
+        "name": "Qwen3-Omni Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0.058,
+          "output": 0.23
+        },
+        "limit": {
+          "context": 65536,
+          "output": 16384
+        }
+      },
+      "qwen-vl-max": {
+        "id": "qwen-vl-max",
+        "name": "Qwen-VL Max",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.23,
+          "output": 0.574
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen3-235b-a22b": {
+        "id": "qwen3-235b-a22b",
+        "name": "Qwen3 235B-A22B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 38912
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.287,
+          "output": 1.147
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        }
+      },
+      "qwen3-vl-30b-a3b": {
+        "id": "qwen3-vl-30b-a3b",
+        "name": "Qwen3-VL 30B-A3B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.108,
+          "output": 0.431
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "kimi-k2.5": {
+        "id": "kimi-k2.5",
+        "name": "Moonshot Kimi K2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 81920
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.574,
+          "output": 2.411
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "qwen3-next-80b-a3b-instruct": {
+        "id": "qwen3-next-80b-a3b-instruct",
+        "name": "Qwen3-Next 80B-A3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.144,
+          "output": 0.574
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "qwen-vl-plus": {
+        "id": "qwen-vl-plus",
+        "name": "Qwen-VL Plus",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.115,
+          "output": 0.287
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "deepseek-r1-distill-qwen-1-5b": {
+        "id": "deepseek-r1-distill-qwen-1-5b",
+        "name": "DeepSeek R1 Distill Qwen 1.5B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 32768,
+          "output": 16384
+        }
+      },
+      "qwen3.6-flash": {
+        "id": "qwen3.6-flash",
+        "name": "Qwen3.6 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 131072
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1875,
+          "output": 1.125,
+          "cache_write": 0.234375
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.6-flash"
+      },
+      "qwen3-coder-flash": {
+        "id": "qwen3-coder-flash",
+        "name": "Qwen3 Coder Flash",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.144,
+          "output": 0.574
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        }
+      },
+      "qwen2-5-omni-7b": {
+        "id": "qwen2-5-omni-7b",
+        "name": "Qwen2.5-Omni 7B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0.087,
+          "output": 0.345
+        },
+        "limit": {
+          "context": 32768,
+          "output": 2048
+        }
+      },
+      "qwen-mt-plus": {
+        "id": "qwen-mt-plus",
+        "name": "Qwen-MT Plus",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.259,
+          "output": 0.775
+        },
+        "limit": {
+          "context": 16384,
+          "output": 8192
+        }
+      },
+      "tongyi-intent-detect-v3": {
+        "id": "tongyi-intent-detect-v3",
+        "name": "Tongyi Intent Detect V3",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.058,
+          "output": 0.144
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1024
+        }
+      },
+      "qwen3-vl-235b-a22b": {
+        "id": "qwen3-vl-235b-a22b",
+        "name": "Qwen3-VL 235B-A22B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.286705,
+          "output": 1.14682
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "qwen3-coder-plus": {
+        "id": "qwen3-coder-plus",
+        "name": "Qwen3 Coder Plus",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.574,
+          "output": 2.296
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        }
+      },
+      "moonshot-kimi-k2-instruct": {
+        "id": "moonshot-kimi-k2-instruct",
+        "name": "Moonshot Kimi K2 Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.574,
+          "output": 2.294
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "MiniMax-M2.5": {
+        "id": "MiniMax-M2.5",
+        "name": "MiniMax-M2.5",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "qwen2-5-14b-instruct": {
+        "id": "qwen2-5-14b-instruct",
+        "name": "Qwen2.5 14B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.144,
+          "output": 0.431
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen3.8-flash": {
+        "id": "qwen3.8-flash",
+        "name": "Qwen3.8 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          },
+          {
+            "type": "budget_tokens",
+            "max": 262144
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.11875,
+          "output": 0.40073,
+          "cache_read": 0.01187,
+          "cache_write": 0.14844
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-flash"
+      },
+      "qwen2-5-vl-7b-instruct": {
+        "id": "qwen2-5-vl-7b-instruct",
+        "name": "Qwen2.5-VL 7B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.287,
+          "output": 0.717
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen-math-turbo": {
+        "id": "qwen-math-turbo",
+        "name": "Qwen Math Turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.287,
+          "output": 0.861
+        },
+        "limit": {
+          "context": 4096,
+          "output": 3072
+        }
+      },
+      "qwen-long": {
+        "id": "qwen-long",
+        "name": "Qwen Long",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.072,
+          "output": 0.287
+        },
+        "limit": {
+          "context": 10000000,
+          "output": 8192
+        }
+      },
+      "qwen3.6-max-preview": {
+        "id": "qwen3.6-max-preview",
+        "name": "Qwen3.6 Max Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 131072
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.32,
+          "output": 7.9,
+          "cache_read": 0.132
+        },
+        "limit": {
+          "context": 245800,
+          "output": 65536
+        }
+      },
+      "qwen-mt-turbo": {
+        "id": "qwen-mt-turbo",
+        "name": "Qwen-MT Turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.101,
+          "output": 0.28
+        },
+        "limit": {
+          "context": 16384,
+          "output": 8192
+        }
+      },
+      "qwen3.5-397b-a17b": {
+        "id": "qwen3.5-397b-a17b",
+        "name": "Qwen3.5 397B-A17B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 81920
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.172,
+          "output": 1.032
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "qwen3-8b": {
+        "id": "qwen3-8b",
+        "name": "Qwen3 8B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 38912
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.072,
+          "output": 0.287
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "glm-5.2": {
+        "id": "glm-5.2",
+        "name": "GLM-5.2",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 3.851,
+          "cache_read": 0.275,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "qwen-omni-turbo": {
+        "id": "qwen-omni-turbo",
+        "name": "Qwen-Omni Turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0.058,
+          "output": 0.23
+        },
+        "limit": {
+          "context": 32768,
+          "output": 2048
+        }
+      },
+      "glm-5.1": {
+        "id": "glm-5.1",
+        "name": "GLM-5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 131072
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.825,
+          "output": 3.301,
+          "cache_read": 0.17
+        },
+        "limit": {
+          "context": 202752,
+          "output": 128000
+        }
+      },
+      "qwen3-omni-flash-realtime": {
+        "id": "qwen3-omni-flash-realtime",
+        "name": "Qwen3-Omni Flash Realtime",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0.23,
+          "output": 0.918
+        },
+        "limit": {
+          "context": 65536,
+          "output": 16384
+        }
+      },
+      "qwen3-asr-flash": {
+        "id": "qwen3-asr-flash",
+        "name": "Qwen3-ASR Flash",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.032,
+          "output": 0.032
+        },
+        "limit": {
+          "context": 53248,
+          "output": 4096
+        }
+      },
+      "deepseek-r1-distill-qwen-32b": {
+        "id": "deepseek-r1-distill-qwen-32b",
+        "name": "DeepSeek R1 Distill Qwen 32B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.287,
+          "output": 0.861
+        },
+        "limit": {
+          "context": 32768,
+          "output": 16384
+        }
+      },
+      "deepseek-r1": {
+        "id": "deepseek-r1",
+        "name": "DeepSeek R1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.574,
+          "output": 2.294
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        }
+      },
+      "deepseek-v4-pro": {
+        "id": "deepseek-v4-pro",
+        "name": "DeepSeek V4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.435,
+          "output": 0.87,
+          "cache_read": 0.003625
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro"
+      },
+      "deepseek-r1-0528": {
+        "id": "deepseek-r1-0528",
+        "name": "DeepSeek R1 0528",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.574,
+          "output": 2.294
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        }
+      },
+      "qwen3.6-plus": {
+        "id": "qwen3.6-plus",
+        "name": "Qwen3.6 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 81920
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.05,
+          "cache_write": 0.625
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        }
+      },
+      "qwen3-14b": {
+        "id": "qwen3-14b",
+        "name": "Qwen3 14B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 38912
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.144,
+          "output": 0.574
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "glm-5.3": {
+        "id": "glm-5.3",
+        "name": "GLM-5.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 3.851,
+          "cache_read": 0.275,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "qwen3.7-plus": {
+        "id": "qwen3.7-plus",
+        "name": "Qwen3.7 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 262144
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.05,
+          "cache_write": 0.625
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "canonical_model_id": "alibaba/qwen3.7-plus"
+      },
+      "deepseek-v4-flash": {
+        "id": "deepseek-v4-flash",
+        "name": "DeepSeek V4 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.0028
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash"
+      },
+      "qwen-vl-ocr": {
+        "id": "qwen-vl-ocr",
+        "name": "Qwen-VL OCR",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.043,
+          "output": 0.072
+        },
+        "limit": {
+          "context": 34096,
+          "output": 4096
+        }
+      },
+      "siliconflow/deepseek-v3-0324": {
+        "id": "siliconflow/deepseek-v3-0324",
+        "name": "siliconflow/deepseek-v3-0324",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1
+        },
+        "limit": {
+          "context": 163840,
+          "output": 163840
+        }
+      },
+      "siliconflow/deepseek-v3.1-terminus": {
+        "id": "siliconflow/deepseek-v3.1-terminus",
+        "name": "siliconflow/deepseek-v3.1-terminus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.27,
+          "output": 1
+        },
+        "limit": {
+          "context": 163840,
+          "output": 65536
+        }
+      },
+      "siliconflow/deepseek-r1-0528": {
+        "id": "siliconflow/deepseek-r1-0528",
+        "name": "siliconflow/deepseek-r1-0528",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 2.18
+        },
+        "limit": {
+          "context": 163840,
+          "output": 32768
+        }
+      },
+      "siliconflow/deepseek-v3.2": {
+        "id": "siliconflow/deepseek-v3.2",
+        "name": "siliconflow/deepseek-v3.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.27,
+          "output": 0.42
+        },
+        "limit": {
+          "context": 163840,
+          "output": 65536
+        }
+      },
+      "kimi/kimi-k2.5": {
+        "id": "kimi/kimi-k2.5",
+        "name": "kimi/kimi-k2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "MiniMax/MiniMax-M2.7": {
+        "id": "MiniMax/MiniMax-M2.7",
+        "name": "MiniMax-M2.7",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      }
+    }
+  },
+  "amazon-bedrock": {
+    "id": "amazon-bedrock",
+    "name": "Amazon Bedrock",
+    "env": [
+      "AWS_ACCESS_KEY_ID",
+      "AWS_SECRET_ACCESS_KEY",
+      "AWS_REGION",
+      "AWS_BEARER_TOKEN_BEDROCK"
+    ],
+    "npm": "@ai-sdk/amazon-bedrock",
+    "models": {
+      "google.gemma-3-12b-it": {
+        "id": "google.gemma-3-12b-it",
+        "name": "Gemma 3 12B IT",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.09,
+          "output": 0.29
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        },
+        "canonical_model_id": "google/gemma-3-12b-it"
+      },
+      "google.gemma-3-4b-it": {
+        "id": "google.gemma-3-4b-it",
+        "name": "Gemma 3 4B IT",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.04,
+          "output": 0.08
+        },
+        "limit": {
+          "context": 131072,
+          "output": 4096
+        },
+        "canonical_model_id": "google/gemma-3-4b-it"
+      },
+      "eu.anthropic.claude-fable-5": {
+        "id": "eu.anthropic.claude-fable-5",
+        "name": "Claude Fable 5 (EU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 11,
+          "output": 55,
+          "cache_read": 1.1,
+          "cache_write": 13.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-fable-5"
+      },
+      "qwen.qwen3-coder-480b-a35b-v1:0": {
+        "id": "qwen.qwen3-coder-480b-a35b-v1:0",
+        "name": "Qwen3-Coder 480B-A35B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.45,
+          "output": 1.8
+        },
+        "limit": {
+          "context": 131072,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3-coder-480b-a35b-instruct"
+      },
+      "google.gemma-4-31b": {
+        "id": "google.gemma-4-31b",
+        "name": "Gemma 4 31B IT",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.4
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "provider": {
+          "npm": "@ai-sdk/amazon-bedrock/mantle",
+          "api": "https://bedrock-mantle.${AWS_REGION}.api.aws/openai/v1"
+        },
+        "canonical_model_id": "google/gemma-4-31b-it"
+      },
+      "us.writer.palmyra-x5-v1:0": {
+        "id": "us.writer.palmyra-x5-v1:0",
+        "name": "Palmyra X5 (US)",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 6
+        },
+        "limit": {
+          "context": 1040000,
+          "output": 8192
+        },
+        "canonical_model_id": "writer/palmyra-x5"
+      },
+      "google.gemma-4-e2b": {
+        "id": "google.gemma-4-e2b",
+        "name": "Gemma 4 E2B IT",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.04,
+          "output": 0.08
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        },
+        "provider": {
+          "npm": "@ai-sdk/amazon-bedrock/mantle",
+          "api": "https://bedrock-mantle.${AWS_REGION}.api.aws/openai/v1"
+        },
+        "canonical_model_id": "google/gemma-4-E2B-it"
+      },
+      "us.anthropic.claude-opus-4-7": {
+        "id": "us.anthropic.claude-opus-4-7",
+        "name": "Claude Opus 4.7 (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-7"
+      },
+      "global.openai.gpt-6-astra": {
+        "id": "global.openai.gpt-6-astra",
+        "name": "GPT-6 Astra (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-astra"
+      },
+      "eu.amazon.nova-lite-v1:0": {
+        "id": "eu.amazon.nova-lite-v1:0",
+        "name": "Nova Lite (EU)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.069,
+          "output": 0.276,
+          "cache_read": 0.01725,
+          "cache_write": 0.069
+        },
+        "limit": {
+          "context": 300000,
+          "output": 10000
+        },
+        "canonical_model_id": "amazon/nova-lite"
+      },
+      "global.anthropic.claude-opus-5-5": {
+        "id": "global.anthropic.claude-opus-5-5",
+        "name": "Claude Opus 5.5 (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.2,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5-5"
+      },
+      "deepseek.r1-v1:0": {
+        "id": "deepseek.r1-v1:0",
+        "name": "DeepSeek-R1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.35,
+          "output": 5.4
+        },
+        "limit": {
+          "context": 128000,
+          "output": 32768
+        },
+        "canonical_model_id": "deepseek/deepseek-r1"
+      },
+      "openai.gpt-oss-safeguard-20b": {
+        "id": "openai.gpt-oss-safeguard-20b",
+        "name": "GPT OSS Safeguard 20B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.2
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "openai/gpt-oss-safeguard-20b"
+      },
+      "anthropic.claude-opus-5-5": {
+        "id": "anthropic.claude-opus-5-5",
+        "name": "Claude Opus 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.2,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5-5"
+      },
+      "global.anthropic.claude-haiku-4-5-20251001-v1:0": {
+        "id": "global.anthropic.claude-haiku-4-5-20251001-v1:0",
+        "name": "Claude Haiku 4.5 (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 5,
+          "cache_read": 0.1,
+          "cache_write": 1.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-haiku-4-5-20251001"
+      },
+      "eu.amazon.nova-2-lite-v1:0": {
+        "id": "eu.amazon.nova-2-lite-v1:0",
+        "name": "Nova 2 Lite (EU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.374,
+          "output": 3.157,
+          "cache_read": 0.0935,
+          "cache_write": 0.374
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65535
+        },
+        "canonical_model_id": "amazon/nova-2-lite"
+      },
+      "us.amazon.nova-pro-v1:0": {
+        "id": "us.amazon.nova-pro-v1:0",
+        "name": "Nova Pro (US)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.8,
+          "output": 3.2,
+          "cache_read": 0.2,
+          "cache_write": 0.8
+        },
+        "limit": {
+          "context": 300000,
+          "output": 10000
+        },
+        "canonical_model_id": "amazon/nova-pro"
+      },
+      "jp.anthropic.claude-opus-5-5": {
+        "id": "jp.anthropic.claude-opus-5-5",
+        "name": "Claude Opus 5.5 (JP)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4.4,
+          "output": 22,
+          "cache_read": 0.22,
+          "cache_write": 5.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5-5"
+      },
+      "anthropic.claude-sonnet-5-5": {
+        "id": "anthropic.claude-sonnet-5-5",
+        "name": "Claude Sonnet 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5-5"
+      },
+      "global.anthropic.claude-sonnet-5-5": {
+        "id": "global.anthropic.claude-sonnet-5-5",
+        "name": "Claude Sonnet 5.5 (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5-5"
+      },
+      "openai.gpt-5.6-luna": {
+        "id": "openai.gpt-5.6-luna",
+        "name": "GPT-5.6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.22,
+          "output": 1.32,
+          "cache_read": 0.022,
+          "cache_write": 0.275
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/amazon-bedrock/mantle",
+          "api": "https://bedrock-mantle.${AWS_REGION}.api.aws/openai/v1"
+        },
+        "canonical_model_id": "openai/gpt-5.6-luna"
+      },
+      "us.meta.llama4-maverick-17b-instruct-v1:0": {
+        "id": "us.meta.llama4-maverick-17b-instruct-v1:0",
+        "name": "Llama 4 Maverick 17B Instruct (US)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.24,
+          "output": 0.97
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 8192
+        },
+        "canonical_model_id": "meta/llama-4-maverick-17b-instruct"
+      },
+      "apac.amazon.nova-micro-v1:0": {
+        "id": "apac.amazon.nova-micro-v1:0",
+        "name": "Nova Micro (APAC)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.037,
+          "output": 0.148,
+          "cache_read": 0.00925,
+          "cache_write": 0.037
+        },
+        "limit": {
+          "context": 128000,
+          "output": 10000
+        },
+        "canonical_model_id": "amazon/nova-micro"
+      },
+      "eu.anthropic.claude-sonnet-4-20250514-v1:0": {
+        "id": "eu.anthropic.claude-sonnet-4-20250514-v1:0",
+        "name": "Claude Sonnet 4 (EU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-20250514",
+        "status": "deprecated"
+      },
+      "eu.anthropic.claude-opus-4-5-20251101-v1:0": {
+        "id": "eu.anthropic.claude-opus-4-5-20251101-v1:0",
+        "name": "Claude Opus 4.5 (EU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-5-20251101"
+      },
+      "global.openai.gpt-6-sol": {
+        "id": "global.openai.gpt-6-sol",
+        "name": "GPT-6 Sol (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-sol"
+      },
+      "qwen.qwen3-coder-30b-a3b-v1:0": {
+        "id": "qwen.qwen3-coder-30b-a3b-v1:0",
+        "name": "Qwen3-Coder 30B-A3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3-coder-30b-a3b-instruct"
+      },
+      "us.amazon.nova-premier-v1:0": {
+        "id": "us.amazon.nova-premier-v1:0",
+        "name": "Nova Premier (US)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 12.5,
+          "cache_read": 0.625,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 10000
+        },
+        "canonical_model_id": "amazon/nova-premier",
+        "status": "deprecated"
+      },
+      "anthropic.claude-sonnet-4-6": {
+        "id": "anthropic.claude-sonnet-4-6",
+        "name": "Claude Sonnet 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3.3,
+          "output": 16.5,
+          "cache_read": 0.33,
+          "cache_write": 4.125
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-6"
+      },
+      "meta.llama3-1-70b-instruct-v1:0": {
+        "id": "meta.llama3-1-70b-instruct-v1:0",
+        "name": "Llama 3.1 70B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.72,
+          "output": 0.72
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "canonical_model_id": "meta/llama-3.1-70b-instruct"
+      },
+      "us.writer.palmyra-x4-v1:0": {
+        "id": "us.writer.palmyra-x4-v1:0",
+        "name": "Palmyra X4 (US)",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10
+        },
+        "limit": {
+          "context": 122880,
+          "output": 8192
+        },
+        "canonical_model_id": "writer/palmyra-x4"
+      },
+      "apac.amazon.nova-pro-v1:0": {
+        "id": "apac.amazon.nova-pro-v1:0",
+        "name": "Nova Pro (APAC)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.84,
+          "output": 3.36,
+          "cache_read": 0.21,
+          "cache_write": 0.84
+        },
+        "limit": {
+          "context": 300000,
+          "output": 10000
+        },
+        "canonical_model_id": "amazon/nova-pro"
+      },
+      "global.anthropic.claude-fable-5-1": {
+        "id": "global.anthropic.claude-fable-5-1",
+        "name": "Claude Fable 5.1 (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 0.25,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-fable-5-1"
+      },
+      "us.anthropic.claude-sonnet-5": {
+        "id": "us.anthropic.claude-sonnet-5",
+        "name": "Claude Sonnet 5 (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.2,
+          "output": 11,
+          "cache_read": 0.22,
+          "cache_write": 2.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5"
+      },
+      "amazon.nova-micro-v1:0": {
+        "id": "amazon.nova-micro-v1:0",
+        "name": "Nova Micro",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.035,
+          "output": 0.14,
+          "cache_read": 0.00875,
+          "cache_write": 0.035
+        },
+        "limit": {
+          "context": 128000,
+          "output": 10000
+        },
+        "canonical_model_id": "amazon/nova-micro"
+      },
+      "minimax.minimax-m2.5": {
+        "id": "minimax.minimax-m2.5",
+        "name": "MiniMax-M2.5",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 196608,
+          "output": 98304
+        },
+        "canonical_model_id": "minimax/MiniMax-M2.5"
+      },
+      "xai.grok-4.3": {
+        "id": "xai.grok-4.3",
+        "name": "Grok 4.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "provider": {
+          "npm": "@ai-sdk/amazon-bedrock/mantle",
+          "api": "https://bedrock-mantle.${AWS_REGION}.api.aws/openai/v1"
+        },
+        "canonical_model_id": "xai/grok-4.3"
+      },
+      "us.amazon.nova-lite-v1:0": {
+        "id": "us.amazon.nova-lite-v1:0",
+        "name": "Nova Lite (US)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.24,
+          "cache_read": 0.015,
+          "cache_write": 0.06
+        },
+        "limit": {
+          "context": 300000,
+          "output": 10000
+        },
+        "canonical_model_id": "amazon/nova-lite"
+      },
+      "amazon.nova-pro-v1:0": {
+        "id": "amazon.nova-pro-v1:0",
+        "name": "Nova Pro",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.8,
+          "output": 3.2,
+          "cache_read": 0.2,
+          "cache_write": 0.8
+        },
+        "limit": {
+          "context": 300000,
+          "output": 10000
+        },
+        "canonical_model_id": "amazon/nova-pro"
+      },
+      "qwen.qwen3-32b-v1:0": {
+        "id": "qwen.qwen3-32b-v1:0",
+        "name": "Qwen3 32B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6
+        },
+        "limit": {
+          "context": 32768,
+          "output": 16384
+        },
+        "canonical_model_id": "alibaba/qwen3-32b"
+      },
+      "openai.gpt-5.5": {
+        "id": "openai.gpt-5.5",
+        "name": "GPT-5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 33,
+          "cache_read": 0.55
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/amazon-bedrock/mantle",
+          "api": "https://bedrock-mantle.${AWS_REGION}.api.aws/openai/v1"
+        },
+        "canonical_model_id": "openai/gpt-5.5"
+      },
+      "mistral.voxtral-small-24b-2507": {
+        "id": "mistral.voxtral-small-24b-2507",
+        "name": "Voxtral Small 24B 2507",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 32768,
+          "output": 8192
+        },
+        "canonical_model_id": "mistral/voxtral-small-24b-2507"
+      },
+      "global.amazon.nova-2-lite-v1:0": {
+        "id": "global.amazon.nova-2-lite-v1:0",
+        "name": "Nova 2 Lite (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.075,
+          "cache_write": 0.3
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65535
+        },
+        "canonical_model_id": "amazon/nova-2-lite"
+      },
+      "us.openai.gpt-5.6-terra": {
+        "id": "us.openai.gpt-5.6-terra",
+        "name": "GPT-5.6 Terra (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.2,
+          "output": 13.2,
+          "cache_read": 0.22,
+          "cache_write": 2.75
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-terra"
+      },
+      "mistral.devstral-2-123b": {
+        "id": "mistral.devstral-2-123b",
+        "name": "Devstral 2 123B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 8192
+        },
+        "canonical_model_id": "mistral/devstral-2512"
+      },
+      "us.xai.grok-4.6": {
+        "id": "us.xai.grok-4.6",
+        "name": "Grok 4.6 (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.2,
+          "output": 6.6,
+          "cache_read": 0.55
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "canonical_model_id": "xai/grok-4.6"
+      },
+      "jp.anthropic.claude-sonnet-4-5-20250929-v1:0": {
+        "id": "jp.anthropic.claude-sonnet-4-5-20250929-v1:0",
+        "name": "Claude Sonnet 4.5 (JP)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3.3,
+          "output": 16.5,
+          "cache_read": 0.33,
+          "cache_write": 4.125
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-5-20250929"
+      },
+      "anthropic.claude-fable-5": {
+        "id": "anthropic.claude-fable-5",
+        "name": "Claude Fable 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-fable-5"
+      },
+      "anthropic.claude-sonnet-4-5-20250929-v1:0": {
+        "id": "anthropic.claude-sonnet-4-5-20250929-v1:0",
+        "name": "Claude Sonnet 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-5-20250929"
+      },
+      "jp.anthropic.claude-opus-4-8": {
+        "id": "jp.anthropic.claude-opus-4-8",
+        "name": "Claude Opus 4.8 (JP)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-8"
+      },
+      "us.openai.gpt-5.6-luna": {
+        "id": "us.openai.gpt-5.6-luna",
+        "name": "GPT-5.6 Luna (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.22,
+          "output": 1.32,
+          "cache_read": 0.022,
+          "cache_write": 0.275
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-luna"
+      },
+      "us.anthropic.claude-sonnet-4-5-20250929-v1:0": {
+        "id": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
+        "name": "Claude Sonnet 4.5 (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3.3,
+          "output": 16.5,
+          "cache_read": 0.33,
+          "cache_write": 4.125
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-5-20250929"
+      },
+      "au.anthropic.claude-opus-5": {
+        "id": "au.anthropic.claude-opus-5",
+        "name": "Claude Opus 5 (AU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5"
+      },
+      "nvidia.nemotron-nano-12b-v2": {
+        "id": "nvidia.nemotron-nano-12b-v2",
+        "name": "NVIDIA Nemotron Nano 12B v2 VL BF16",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.6
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        },
+        "canonical_model_id": "nvidia/nemotron-nano-12b-v2-vl"
+      },
+      "us.amazon.nova-2-lite-v1:0": {
+        "id": "us.amazon.nova-2-lite-v1:0",
+        "name": "Nova 2 Lite (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.33,
+          "output": 2.75,
+          "cache_read": 0.0825,
+          "cache_write": 0.33
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65535
+        },
+        "canonical_model_id": "amazon/nova-2-lite"
+      },
+      "us.openai.gpt-6-astra": {
+        "id": "us.openai.gpt-6-astra",
+        "name": "GPT-6 Astra (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 11,
+          "output": 55,
+          "cache_read": 1.1,
+          "cache_write": 13.75
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-astra"
+      },
+      "openai.gpt-5.6-terra": {
+        "id": "openai.gpt-5.6-terra",
+        "name": "GPT-5.6 Terra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.2,
+          "output": 13.2,
+          "cache_read": 0.22,
+          "cache_write": 2.75
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/amazon-bedrock/mantle",
+          "api": "https://bedrock-mantle.${AWS_REGION}.api.aws/openai/v1"
+        },
+        "canonical_model_id": "openai/gpt-5.6-terra"
+      },
+      "anthropic.claude-opus-4-6-v1": {
+        "id": "anthropic.claude-opus-4-6-v1",
+        "name": "Claude Opus 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-6"
+      },
+      "us.anthropic.claude-opus-4-1-20250805-v1:0": {
+        "id": "us.anthropic.claude-opus-4-1-20250805-v1:0",
+        "name": "Claude Opus 4.1 (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 75,
+          "cache_read": 1.5,
+          "cache_write": 18.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 32000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-1-20250805",
+        "status": "deprecated"
+      },
+      "us.meta.llama3-1-8b-instruct-v1:0": {
+        "id": "us.meta.llama3-1-8b-instruct-v1:0",
+        "name": "Llama 3.1 8B Instruct (US)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.22,
+          "output": 0.22
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "canonical_model_id": "meta/llama-3.1-8b-instruct"
+      },
+      "eu.anthropic.claude-haiku-4-5-20251001-v1:0": {
+        "id": "eu.anthropic.claude-haiku-4-5-20251001-v1:0",
+        "name": "Claude Haiku 4.5 (EU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 5.5,
+          "cache_read": 0.11,
+          "cache_write": 1.375
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-haiku-4-5-20251001"
+      },
+      "global.anthropic.claude-opus-4-7": {
+        "id": "global.anthropic.claude-opus-4-7",
+        "name": "Claude Opus 4.7 (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-7"
+      },
+      "apac.anthropic.claude-sonnet-4-20250514-v1:0": {
+        "id": "apac.anthropic.claude-sonnet-4-20250514-v1:0",
+        "name": "Claude Sonnet 4 (APAC)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-20250514",
+        "status": "deprecated"
+      },
+      "deepseek.v3.2": {
+        "id": "deepseek.v3.2",
+        "name": "DeepSeek V3.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.62,
+          "output": 1.85
+        },
+        "limit": {
+          "context": 163840,
+          "output": 81920
+        },
+        "canonical_model_id": "deepseek/deepseek-v3.2"
+      },
+      "qwen.qwen3-235b-a22b-2507-v1:0": {
+        "id": "qwen.qwen3-235b-a22b-2507-v1:0",
+        "name": "Qwen3 235B-A22B Instruct 2507",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.22,
+          "output": 0.88
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3-235b-a22b-instruct-2507"
+      },
+      "amazon.nova-lite-v1:0": {
+        "id": "amazon.nova-lite-v1:0",
+        "name": "Nova Lite",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.24,
+          "cache_read": 0.015,
+          "cache_write": 0.06
+        },
+        "limit": {
+          "context": 300000,
+          "output": 10000
+        },
+        "canonical_model_id": "amazon/nova-lite"
+      },
+      "global.anthropic.claude-opus-5": {
+        "id": "global.anthropic.claude-opus-5",
+        "name": "Claude Opus 5 (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5"
+      },
+      "openai.gpt-oss-20b-1:0": {
+        "id": "openai.gpt-oss-20b-1:0",
+        "name": "gpt-oss-20b",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 131072,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-oss-20b"
+      },
+      "anthropic.claude-opus-5": {
+        "id": "anthropic.claude-opus-5",
+        "name": "Claude Opus 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5"
+      },
+      "meta.llama3-3-70b-instruct-v1:0": {
+        "id": "meta.llama3-3-70b-instruct-v1:0",
+        "name": "Llama 3.3 70B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.72,
+          "output": 0.72
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "canonical_model_id": "meta/llama-3.3-70b-instruct"
+      },
+      "minimax.minimax-m2": {
+        "id": "minimax.minimax-m2",
+        "name": "MiniMax-M2",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 204608,
+          "output": 128000
+        },
+        "canonical_model_id": "minimax/MiniMax-M2"
+      },
+      "mistral.mistral-large-3-675b-instruct": {
+        "id": "mistral.mistral-large-3-675b-instruct",
+        "name": "Mistral Large 3",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.5
+        },
+        "limit": {
+          "context": 262144,
+          "output": 8192
+        },
+        "canonical_model_id": "mistral/mistral-large-2512"
+      },
+      "in.openai.gpt-5.6-luna": {
+        "id": "in.openai.gpt-5.6-luna",
+        "name": "GPT-5.6 Luna (India)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.22,
+          "output": 1.32,
+          "cache_read": 0.022,
+          "cache_write": 0.275
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-luna"
+      },
+      "eu.anthropic.claude-opus-4-8": {
+        "id": "eu.anthropic.claude-opus-4-8",
+        "name": "Claude Opus 4.8 (EU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-8"
+      },
+      "global.anthropic.claude-sonnet-4-5-20250929-v1:0": {
+        "id": "global.anthropic.claude-sonnet-4-5-20250929-v1:0",
+        "name": "Claude Sonnet 4.5 (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-5-20250929"
+      },
+      "zai.glm-4.7": {
+        "id": "zai.glm-4.7",
+        "name": "GLM-4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.2
+        },
+        "limit": {
+          "context": 202752,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-4.7"
+      },
+      "au.anthropic.claude-sonnet-4-5-20250929-v1:0": {
+        "id": "au.anthropic.claude-sonnet-4-5-20250929-v1:0",
+        "name": "Claude Sonnet 4.5 (AU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3.3,
+          "output": 16.5,
+          "cache_read": 0.33,
+          "cache_write": 4.125
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-5-20250929"
+      },
+      "eu.anthropic.claude-opus-5-5": {
+        "id": "eu.anthropic.claude-opus-5-5",
+        "name": "Claude Opus 5.5 (EU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4.4,
+          "output": 22,
+          "cache_read": 0.22,
+          "cache_write": 5.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5-5"
+      },
+      "global.anthropic.claude-sonnet-4-6": {
+        "id": "global.anthropic.claude-sonnet-4-6",
+        "name": "Claude Sonnet 4.6 (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-6"
+      },
+      "jp.anthropic.claude-sonnet-4-6": {
+        "id": "jp.anthropic.claude-sonnet-4-6",
+        "name": "Claude Sonnet 4.6 (JP)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3.3,
+          "output": 16.5,
+          "cache_read": 0.33,
+          "cache_write": 4.125
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-6"
+      },
+      "google.gemma-3-27b-it": {
+        "id": "google.gemma-3-27b-it",
+        "name": "Gemma 3 27B IT",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.23,
+          "output": 0.38
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        },
+        "canonical_model_id": "google/gemma-3-27b-it"
+      },
+      "eu.anthropic.claude-opus-4-6-v1": {
+        "id": "eu.anthropic.claude-opus-4-6-v1",
+        "name": "Claude Opus 4.6 (EU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-6"
+      },
+      "us.anthropic.claude-opus-5-5": {
+        "id": "us.anthropic.claude-opus-5-5",
+        "name": "Claude Opus 5.5 (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4.4,
+          "output": 22,
+          "cache_read": 0.22,
+          "cache_write": 5.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5-5"
+      },
+      "us.anthropic.claude-opus-5": {
+        "id": "us.anthropic.claude-opus-5",
+        "name": "Claude Opus 5 (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5"
+      },
+      "global.xai.grok-4.7": {
+        "id": "global.xai.grok-4.7",
+        "name": "Grok 4.7 (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "canonical_model_id": "xai/grok-4.7"
+      },
+      "us.openai.gpt-5.6-sol": {
+        "id": "us.openai.gpt-5.6-sol",
+        "name": "GPT-5.6 Sol (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4.4,
+          "output": 22,
+          "cache_read": 0.44,
+          "cache_write": 5.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-sol"
+      },
+      "us.moonshotai.kimi-k3": {
+        "id": "us.moonshotai.kimi-k3",
+        "name": "Kimi K3 (US)",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": true,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3.3,
+          "output": 16.5,
+          "cache_read": 0.33,
+          "cache_write": 4.125
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 128000
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "anthropic.claude-sonnet-5": {
+        "id": "anthropic.claude-sonnet-5",
+        "name": "Claude Sonnet 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5"
+      },
+      "mistral.magistral-small-2509": {
+        "id": "mistral.magistral-small-2509",
+        "name": "Magistral Small 1.2",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.5
+        },
+        "limit": {
+          "context": 128000,
+          "output": 40000
+        },
+        "canonical_model_id": "mistral/magistral-small-2509"
+      },
+      "mistral.pixtral-large-2502-v1:0": {
+        "id": "mistral.pixtral-large-2502-v1:0",
+        "name": "Pixtral Large (25.02)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        },
+        "canonical_model_id": "mistral/pixtral-large-2502"
+      },
+      "anthropic.claude-opus-4-5-20251101-v1:0": {
+        "id": "anthropic.claude-opus-4-5-20251101-v1:0",
+        "name": "Claude Opus 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-5-20251101"
+      },
+      "nvidia.nemotron-nano-9b-v2": {
+        "id": "nvidia.nemotron-nano-9b-v2",
+        "name": "NVIDIA Nemotron Nano 9B v2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.23
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        },
+        "canonical_model_id": "nvidia/nemotron-nano-9b-v2"
+      },
+      "eu.amazon.nova-micro-v1:0": {
+        "id": "eu.amazon.nova-micro-v1:0",
+        "name": "Nova Micro (EU)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.04,
+          "output": 0.16,
+          "cache_read": 0.01,
+          "cache_write": 0.04
+        },
+        "limit": {
+          "context": 128000,
+          "output": 10000
+        },
+        "canonical_model_id": "amazon/nova-micro"
+      },
+      "zai.glm-5": {
+        "id": "zai.glm-5",
+        "name": "GLM-5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 3.2
+        },
+        "limit": {
+          "context": 202752,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5"
+      },
+      "us.meta.llama3-1-70b-instruct-v1:0": {
+        "id": "us.meta.llama3-1-70b-instruct-v1:0",
+        "name": "Llama 3.1 70B Instruct (US)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.72,
+          "output": 0.72
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "canonical_model_id": "meta/llama-3.1-70b-instruct"
+      },
+      "jp.anthropic.claude-haiku-4-5-20251001-v1:0": {
+        "id": "jp.anthropic.claude-haiku-4-5-20251001-v1:0",
+        "name": "Claude Haiku 4.5 (JP)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 5.5,
+          "cache_read": 0.11,
+          "cache_write": 1.375
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-haiku-4-5-20251001"
+      },
+      "nvidia.nemotron-nano-3-30b": {
+        "id": "nvidia.nemotron-nano-3-30b",
+        "name": "NVIDIA Nemotron Nano 3 30B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.24
+        },
+        "limit": {
+          "context": 262144,
+          "output": 8192
+        },
+        "canonical_model_id": "nvidia/nemotron-3-nano-30b-a3b"
+      },
+      "mistral.ministral-3-3b-instruct": {
+        "id": "mistral.ministral-3-3b-instruct",
+        "name": "Ministral 3 3B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.1
+        },
+        "limit": {
+          "context": 256000,
+          "output": 8192
+        },
+        "canonical_model_id": "mistral/ministral-3-3b-instruct-2512"
+      },
+      "us.xai.grok-4.7": {
+        "id": "us.xai.grok-4.7",
+        "name": "Grok 4.7 (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.2,
+          "output": 6.6,
+          "cache_read": 0.55
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "canonical_model_id": "xai/grok-4.7"
+      },
+      "us.openai.gpt-6-luna": {
+        "id": "us.openai.gpt-6-luna",
+        "name": "GPT-6 Luna (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.11,
+          "output": 0.55,
+          "cache_read": 0.011,
+          "cache_write": 0.1375
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-luna"
+      },
+      "global.openai.gpt-5.6-sol": {
+        "id": "global.openai.gpt-5.6-sol",
+        "name": "GPT-5.6 Sol (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.4,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-sol"
+      },
+      "google.gemma-4-26b-a4b": {
+        "id": "google.gemma-4-26b-a4b",
+        "name": "Gemma 4 26B A4B IT",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.13,
+          "output": 0.4
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "provider": {
+          "npm": "@ai-sdk/amazon-bedrock/mantle",
+          "api": "https://bedrock-mantle.${AWS_REGION}.api.aws/openai/v1"
+        },
+        "canonical_model_id": "google/gemma-4-26b-a4b-it"
+      },
+      "xai.grok-4.6": {
+        "id": "xai.grok-4.6",
+        "name": "Grok 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.2,
+          "output": 6.6,
+          "cache_read": 0.55
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "provider": {
+          "npm": "@ai-sdk/amazon-bedrock/mantle",
+          "api": "https://bedrock-mantle.${AWS_REGION}.api.aws/openai/v1"
+        },
+        "canonical_model_id": "xai/grok-4.6"
+      },
+      "global.xai.grok-4.6": {
+        "id": "global.xai.grok-4.6",
+        "name": "Grok 4.6 (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "canonical_model_id": "xai/grok-4.6"
+      },
+      "au.anthropic.claude-opus-4-6-v1": {
+        "id": "au.anthropic.claude-opus-4-6-v1",
+        "name": "AU Anthropic Claude Opus 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-6"
+      },
+      "qwen.qwen3-vl-235b-a22b": {
+        "id": "qwen.qwen3-vl-235b-a22b",
+        "name": "Qwen3 VL 235B A22B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.53,
+          "output": 2.66
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262000
+        },
+        "canonical_model_id": "alibaba/qwen3-vl-235b-a22b-instruct"
+      },
+      "anthropic.claude-fable-5-1": {
+        "id": "anthropic.claude-fable-5-1",
+        "name": "Claude Fable 5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 0.25,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-fable-5-1"
+      },
+      "jp.anthropic.claude-sonnet-5": {
+        "id": "jp.anthropic.claude-sonnet-5",
+        "name": "Claude Sonnet 5 (JP)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.2,
+          "output": 11,
+          "cache_read": 0.22,
+          "cache_write": 2.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5"
+      },
+      "qwen.qwen3-coder-next": {
+        "id": "qwen.qwen3-coder-next",
+        "name": "Qwen3 Coder Next",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3-coder-next"
+      },
+      "anthropic.claude-opus-4-8": {
+        "id": "anthropic.claude-opus-4-8",
+        "name": "Claude Opus 4.8",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-8"
+      },
+      "au.anthropic.claude-sonnet-5": {
+        "id": "au.anthropic.claude-sonnet-5",
+        "name": "Claude Sonnet 5 (AU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.2,
+          "output": 11,
+          "cache_read": 0.22,
+          "cache_write": 2.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5"
+      },
+      "meta.llama4-scout-17b-instruct-v1:0": {
+        "id": "meta.llama4-scout-17b-instruct-v1:0",
+        "name": "Llama 4 Scout 17B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.17,
+          "output": 0.66
+        },
+        "limit": {
+          "context": 10000000,
+          "output": 8192
+        },
+        "canonical_model_id": "meta/llama-4-scout-17b-instruct"
+      },
+      "openai.gpt-oss-safeguard-120b": {
+        "id": "openai.gpt-oss-safeguard-120b",
+        "name": "GPT OSS Safeguard 120B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "openai/gpt-oss-safeguard-120b"
+      },
+      "us.meta.llama3-3-70b-instruct-v1:0": {
+        "id": "us.meta.llama3-3-70b-instruct-v1:0",
+        "name": "Llama 3.3 70B Instruct (US)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.72,
+          "output": 0.72
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "canonical_model_id": "meta/llama-3.3-70b-instruct"
+      },
+      "global.openai.gpt-5.6-luna": {
+        "id": "global.openai.gpt-5.6-luna",
+        "name": "GPT-5.6 Luna (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.2,
+          "cache_read": 0.02,
+          "cache_write": 0.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-luna"
+      },
+      "au.anthropic.claude-sonnet-4-6": {
+        "id": "au.anthropic.claude-sonnet-4-6",
+        "name": "AU Anthropic Claude Sonnet 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3.3,
+          "output": 16.5,
+          "cache_read": 0.33,
+          "cache_write": 4.125
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-6"
+      },
+      "openai.gpt-oss-120b": {
+        "id": "openai.gpt-oss-120b",
+        "name": "gpt-oss-120b",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "provider": {
+          "npm": "@ai-sdk/amazon-bedrock/mantle",
+          "api": "https://bedrock-mantle.${AWS_REGION}.api.aws/v1"
+        },
+        "canonical_model_id": "openai/gpt-oss-120b"
+      },
+      "deepseek.v3-v1:0": {
+        "id": "deepseek.v3-v1:0",
+        "name": "DeepSeek-V3.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.58,
+          "output": 1.68
+        },
+        "limit": {
+          "context": 163840,
+          "output": 81920
+        },
+        "canonical_model_id": "deepseek/deepseek-v3.1"
+      },
+      "moonshotai.kimi-k2.5": {
+        "id": "moonshotai.kimi-k2.5",
+        "name": "Kimi K2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3
+        },
+        "limit": {
+          "context": 262144,
+          "output": 16384
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.5"
+      },
+      "eu.anthropic.claude-sonnet-4-6": {
+        "id": "eu.anthropic.claude-sonnet-4-6",
+        "name": "Claude Sonnet 4.6 (EU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3.3,
+          "output": 16.5,
+          "cache_read": 0.33,
+          "cache_write": 4.125
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-6"
+      },
+      "us-gov.openai.gpt-oss-120b-1:0": {
+        "id": "us-gov.openai.gpt-oss-120b-1:0",
+        "name": "gpt-oss-120b (GovCloud)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.18,
+          "output": 0.72
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "openai/gpt-oss-120b"
+      },
+      "us.anthropic.claude-fable-5": {
+        "id": "us.anthropic.claude-fable-5",
+        "name": "Claude Fable 5 (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 11,
+          "output": 55,
+          "cache_read": 1.1,
+          "cache_write": 13.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-fable-5"
+      },
+      "openai.gpt-6-sol": {
+        "id": "openai.gpt-6-sol",
+        "name": "GPT-6 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.2,
+          "output": 11,
+          "cache_read": 0.22,
+          "cache_write": 2.75
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/amazon-bedrock/mantle",
+          "api": "https://bedrock-mantle.${AWS_REGION}.api.aws/openai/v1"
+        },
+        "canonical_model_id": "openai/gpt-6-sol"
+      },
+      "us.deepseek.r1-v1:0": {
+        "id": "us.deepseek.r1-v1:0",
+        "name": "DeepSeek-R1 (US)",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.35,
+          "output": 5.4
+        },
+        "limit": {
+          "context": 128000,
+          "output": 32768
+        },
+        "canonical_model_id": "deepseek/deepseek-r1"
+      },
+      "eu.anthropic.claude-opus-5": {
+        "id": "eu.anthropic.claude-opus-5",
+        "name": "Claude Opus 5 (EU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5"
+      },
+      "ca.amazon.nova-lite-v1:0": {
+        "id": "ca.amazon.nova-lite-v1:0",
+        "name": "Nova Lite (CA)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.064,
+          "output": 0.256,
+          "cache_read": 0.016,
+          "cache_write": 0.064
+        },
+        "limit": {
+          "context": 300000,
+          "output": 10000
+        },
+        "canonical_model_id": "amazon/nova-lite"
+      },
+      "us.openai.gpt-6-sol": {
+        "id": "us.openai.gpt-6-sol",
+        "name": "GPT-6 Sol (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.2,
+          "output": 11,
+          "cache_read": 0.22,
+          "cache_write": 2.75
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-sol"
+      },
+      "au.anthropic.claude-opus-4-7": {
+        "id": "au.anthropic.claude-opus-4-7",
+        "name": "Claude Opus 4.7 (AU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-7"
+      },
+      "us.meta.llama4-scout-17b-instruct-v1:0": {
+        "id": "us.meta.llama4-scout-17b-instruct-v1:0",
+        "name": "Llama 4 Scout 17B Instruct (US)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.17,
+          "output": 0.66
+        },
+        "limit": {
+          "context": 10000000,
+          "output": 8192
+        },
+        "canonical_model_id": "meta/llama-4-scout-17b-instruct"
+      },
+      "global.anthropic.claude-sonnet-5": {
+        "id": "global.anthropic.claude-sonnet-5",
+        "name": "Claude Sonnet 5 (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5"
+      },
+      "global.anthropic.claude-fable-5": {
+        "id": "global.anthropic.claude-fable-5",
+        "name": "Claude Fable 5 (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-fable-5"
+      },
+      "apac.amazon.nova-lite-v1:0": {
+        "id": "apac.amazon.nova-lite-v1:0",
+        "name": "Nova Lite (APAC)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.063,
+          "output": 0.252,
+          "cache_read": 0.01575,
+          "cache_write": 0.063
+        },
+        "limit": {
+          "context": 300000,
+          "output": 10000
+        },
+        "canonical_model_id": "amazon/nova-lite"
+      },
+      "us.anthropic.claude-opus-4-8": {
+        "id": "us.anthropic.claude-opus-4-8",
+        "name": "Claude Opus 4.8 (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-8"
+      },
+      "nvidia.nemotron-super-3-120b": {
+        "id": "nvidia.nemotron-super-3-120b",
+        "name": "NVIDIA Nemotron 3 Super 120B A12B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.65
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "nvidia/nemotron-3-super-120b-a12b"
+      },
+      "global.openai.gpt-6-luna": {
+        "id": "global.openai.gpt-6-luna",
+        "name": "GPT-6 Luna (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.5,
+          "cache_read": 0.01,
+          "cache_write": 0.125
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-luna"
+      },
+      "us-gov.openai.gpt-oss-20b-1:0": {
+        "id": "us-gov.openai.gpt-oss-20b-1:0",
+        "name": "gpt-oss-20b (GovCloud)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.084,
+          "output": 0.36
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "openai/gpt-oss-20b"
+      },
+      "us.anthropic.claude-opus-4-6-v1": {
+        "id": "us.anthropic.claude-opus-4-6-v1",
+        "name": "Claude Opus 4.6 (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-6"
+      },
+      "meta.llama3-1-8b-instruct-v1:0": {
+        "id": "meta.llama3-1-8b-instruct-v1:0",
+        "name": "Llama 3.1 8B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.22,
+          "output": 0.22
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "canonical_model_id": "meta/llama-3.1-8b-instruct"
+      },
+      "writer.palmyra-x5-v1:0": {
+        "id": "writer.palmyra-x5-v1:0",
+        "name": "Palmyra X5",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 6
+        },
+        "limit": {
+          "context": 1040000,
+          "output": 8192
+        },
+        "canonical_model_id": "writer/palmyra-x5"
+      },
+      "anthropic.claude-opus-4-1-20250805-v1:0": {
+        "id": "anthropic.claude-opus-4-1-20250805-v1:0",
+        "name": "Claude Opus 4.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 75,
+          "cache_read": 1.5,
+          "cache_write": 18.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 32000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-1-20250805",
+        "status": "deprecated"
+      },
+      "us.anthropic.claude-sonnet-4-6": {
+        "id": "us.anthropic.claude-sonnet-4-6",
+        "name": "Claude Sonnet 4.6 (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3.3,
+          "output": 16.5,
+          "cache_read": 0.33,
+          "cache_write": 4.125
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-6"
+      },
+      "global.anthropic.claude-opus-4-6-v1": {
+        "id": "global.anthropic.claude-opus-4-6-v1",
+        "name": "Claude Opus 4.6 (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-6"
+      },
+      "eu.anthropic.claude-sonnet-4-5-20250929-v1:0": {
+        "id": "eu.anthropic.claude-sonnet-4-5-20250929-v1:0",
+        "name": "Claude Sonnet 4.5 (EU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3.3,
+          "output": 16.5,
+          "cache_read": 0.33,
+          "cache_write": 4.125
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-5-20250929"
+      },
+      "jp.anthropic.claude-opus-4-7": {
+        "id": "jp.anthropic.claude-opus-4-7",
+        "name": "Claude Opus 4.7 (JP)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-7"
+      },
+      "au.anthropic.claude-opus-5-5": {
+        "id": "au.anthropic.claude-opus-5-5",
+        "name": "Claude Opus 5.5 (AU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4.4,
+          "output": 22,
+          "cache_read": 0.22,
+          "cache_write": 5.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5-5"
+      },
+      "openai.gpt-6-luna": {
+        "id": "openai.gpt-6-luna",
+        "name": "GPT-6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.11,
+          "output": 0.55,
+          "cache_read": 0.011,
+          "cache_write": 0.1375
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/amazon-bedrock/mantle",
+          "api": "https://bedrock-mantle.${AWS_REGION}.api.aws/openai/v1"
+        },
+        "canonical_model_id": "openai/gpt-6-luna"
+      },
+      "writer.palmyra-x4-v1:0": {
+        "id": "writer.palmyra-x4-v1:0",
+        "name": "Palmyra X4",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10
+        },
+        "limit": {
+          "context": 122880,
+          "output": 8192
+        },
+        "canonical_model_id": "writer/palmyra-x4"
+      },
+      "global.anthropic.claude-opus-4-5-20251101-v1:0": {
+        "id": "global.anthropic.claude-opus-4-5-20251101-v1:0",
+        "name": "Claude Opus 4.5 (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-5-20251101"
+      },
+      "anthropic.claude-opus-4-7": {
+        "id": "anthropic.claude-opus-4-7",
+        "name": "Claude Opus 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-7"
+      },
+      "us.anthropic.claude-sonnet-4-20250514-v1:0": {
+        "id": "us.anthropic.claude-sonnet-4-20250514-v1:0",
+        "name": "Claude Sonnet 4 (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-20250514",
+        "status": "deprecated"
+      },
+      "anthropic.claude-haiku-4-5-20251001-v1:0": {
+        "id": "anthropic.claude-haiku-4-5-20251001-v1:0",
+        "name": "Claude Haiku 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 5,
+          "cache_read": 0.1,
+          "cache_write": 1.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-haiku-4-5-20251001"
+      },
+      "eu.anthropic.claude-sonnet-5": {
+        "id": "eu.anthropic.claude-sonnet-5",
+        "name": "Claude Sonnet 5 (EU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.2,
+          "output": 11,
+          "cache_read": 0.22,
+          "cache_write": 2.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5"
+      },
+      "zai.glm-4.7-flash": {
+        "id": "zai.glm-4.7-flash",
+        "name": "GLM-4.7-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.4
+        },
+        "limit": {
+          "context": 202752,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-4.7-flash"
+      },
+      "moonshot.kimi-k2-thinking": {
+        "id": "moonshot.kimi-k2-thinking",
+        "name": "Kimi K2 Thinking",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.5
+        },
+        "limit": {
+          "context": 262144,
+          "output": 16000
+        },
+        "canonical_model_id": "moonshotai/kimi-k2-thinking"
+      },
+      "eu.amazon.nova-pro-v1:0": {
+        "id": "eu.amazon.nova-pro-v1:0",
+        "name": "Nova Pro (EU)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.92,
+          "output": 3.68,
+          "cache_read": 0.23,
+          "cache_write": 0.92
+        },
+        "limit": {
+          "context": 300000,
+          "output": 10000
+        },
+        "canonical_model_id": "amazon/nova-pro"
+      },
+      "global.openai.gpt-5.6-terra": {
+        "id": "global.openai.gpt-5.6-terra",
+        "name": "GPT-5.6 Terra (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-terra"
+      },
+      "openai.gpt-6-astra": {
+        "id": "openai.gpt-6-astra",
+        "name": "GPT-6 Astra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 11,
+          "output": 55,
+          "cache_read": 1.1,
+          "cache_write": 13.75
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/amazon-bedrock/mantle",
+          "api": "https://bedrock-mantle.${AWS_REGION}.api.aws/openai/v1"
+        },
+        "canonical_model_id": "openai/gpt-6-astra"
+      },
+      "us.anthropic.claude-haiku-4-5-20251001-v1:0": {
+        "id": "us.anthropic.claude-haiku-4-5-20251001-v1:0",
+        "name": "Claude Haiku 4.5 (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 5.5,
+          "cache_read": 0.11,
+          "cache_write": 1.375
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-haiku-4-5-20251001"
+      },
+      "meta.llama4-maverick-17b-instruct-v1:0": {
+        "id": "meta.llama4-maverick-17b-instruct-v1:0",
+        "name": "Llama 4 Maverick 17B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.24,
+          "output": 0.97
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 8192
+        },
+        "canonical_model_id": "meta/llama-4-maverick-17b-instruct"
+      },
+      "qwen.qwen3-next-80b-a3b": {
+        "id": "qwen.qwen3-next-80b-a3b",
+        "name": "Qwen3-Next 80B-A3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262000
+        },
+        "canonical_model_id": "alibaba/qwen3-next-80b-a3b-instruct"
+      },
+      "eu.mistral.pixtral-large-2502-v1:0": {
+        "id": "eu.mistral.pixtral-large-2502-v1:0",
+        "name": "Pixtral Large (25.02) (EU)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        },
+        "canonical_model_id": "mistral/pixtral-large-2502"
+      },
+      "au.anthropic.claude-opus-4-8": {
+        "id": "au.anthropic.claude-opus-4-8",
+        "name": "Claude Opus 4.8 (AU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-8"
+      },
+      "us.anthropic.claude-fable-5-1": {
+        "id": "us.anthropic.claude-fable-5-1",
+        "name": "Claude Fable 5.1 (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 11,
+          "output": 55,
+          "cache_read": 0.275,
+          "cache_write": 13.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-fable-5-1"
+      },
+      "global.moonshotai.kimi-k3": {
+        "id": "global.moonshotai.kimi-k3",
+        "name": "Kimi K3 (Global)",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": true,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 128000
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "in.openai.gpt-5.6-terra": {
+        "id": "in.openai.gpt-5.6-terra",
+        "name": "GPT-5.6 Terra (India)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.2,
+          "output": 13.2,
+          "cache_read": 0.22,
+          "cache_write": 2.75
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-terra"
+      },
+      "openai.gpt-oss-20b": {
+        "id": "openai.gpt-oss-20b",
+        "name": "gpt-oss-20b",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "provider": {
+          "npm": "@ai-sdk/amazon-bedrock/mantle",
+          "api": "https://bedrock-mantle.${AWS_REGION}.api.aws/v1"
+        },
+        "canonical_model_id": "openai/gpt-oss-20b"
+      },
+      "mistral.ministral-3-14b-instruct": {
+        "id": "mistral.ministral-3-14b-instruct",
+        "name": "Ministral 14B 3.0",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.2
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "canonical_model_id": "mistral/ministral-3-14b-instruct-2512"
+      },
+      "au.anthropic.claude-haiku-4-5-20251001-v1:0": {
+        "id": "au.anthropic.claude-haiku-4-5-20251001-v1:0",
+        "name": "Claude Haiku 4.5 (AU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 5.5,
+          "cache_read": 0.11,
+          "cache_write": 1.375
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-haiku-4-5-20251001"
+      },
+      "openai.gpt-5.6-sol": {
+        "id": "openai.gpt-5.6-sol",
+        "name": "GPT-5.6 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4.4,
+          "output": 22,
+          "cache_read": 0.44,
+          "cache_write": 5.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/amazon-bedrock/mantle",
+          "api": "https://bedrock-mantle.${AWS_REGION}.api.aws/openai/v1"
+        },
+        "canonical_model_id": "openai/gpt-5.6-sol"
+      },
+      "minimax.minimax-m2.1": {
+        "id": "minimax.minimax-m2.1",
+        "name": "MiniMax-M2.1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 196608,
+          "output": 131072
+        },
+        "canonical_model_id": "minimax/MiniMax-M2.1"
+      },
+      "us.anthropic.claude-opus-4-5-20251101-v1:0": {
+        "id": "us.anthropic.claude-opus-4-5-20251101-v1:0",
+        "name": "Claude Opus 4.5 (US)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-5-20251101"
+      },
+      "eu.anthropic.claude-opus-4-7": {
+        "id": "eu.anthropic.claude-opus-4-7",
+        "name": "Claude Opus 4.7 (EU)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-7"
+      },
+      "jp.amazon.nova-2-lite-v1:0": {
+        "id": "jp.amazon.nova-2-lite-v1:0",
+        "name": "Nova 2 Lite (JP)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.396,
+          "output": 3.311,
+          "cache_read": 0.099,
+          "cache_write": 0.396
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65535
+        },
+        "canonical_model_id": "amazon/nova-2-lite"
+      },
+      "us.mistral.pixtral-large-2502-v1:0": {
+        "id": "us.mistral.pixtral-large-2502-v1:0",
+        "name": "Pixtral Large (25.02) (US)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        },
+        "canonical_model_id": "mistral/pixtral-large-2502"
+      },
+      "jp.anthropic.claude-opus-5": {
+        "id": "jp.anthropic.claude-opus-5",
+        "name": "Claude Opus 5 (JP)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5.5,
+          "output": 27.5,
+          "cache_read": 0.55,
+          "cache_write": 6.875
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5"
+      },
+      "global.anthropic.claude-sonnet-4-20250514-v1:0": {
+        "id": "global.anthropic.claude-sonnet-4-20250514-v1:0",
+        "name": "Claude Sonnet 4 (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-20250514",
+        "status": "deprecated"
+      },
+      "global.anthropic.claude-opus-4-8": {
+        "id": "global.anthropic.claude-opus-4-8",
+        "name": "Claude Opus 4.8 (Global)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-8"
+      },
+      "openai.gpt-5.4": {
+        "id": "openai.gpt-5.4",
+        "name": "GPT-5.4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.75,
+          "output": 16.5,
+          "cache_read": 0.275
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/amazon-bedrock/mantle",
+          "api": "https://bedrock-mantle.${AWS_REGION}.api.aws/openai/v1"
+        },
+        "canonical_model_id": "openai/gpt-5.4"
+      },
+      "mistral.voxtral-mini-3b-2507": {
+        "id": "mistral.voxtral-mini-3b-2507",
+        "name": "Voxtral Mini 3B 2507",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.04,
+          "output": 0.04
+        },
+        "limit": {
+          "context": 32768,
+          "output": 4096
+        },
+        "canonical_model_id": "mistral/voxtral-mini-3b-2507"
+      },
+      "openai.gpt-oss-120b-1:0": {
+        "id": "openai.gpt-oss-120b-1:0",
+        "name": "gpt-oss-120b",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6
+        },
+        "limit": {
+          "context": 131072,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-oss-120b"
+      },
+      "amazon.nova-2-lite-v1:0": {
+        "id": "amazon.nova-2-lite-v1:0",
+        "name": "Nova 2 Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.33,
+          "output": 2.75,
+          "cache_read": 0.0825,
+          "cache_write": 0.33
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65535
+        },
+        "canonical_model_id": "amazon/nova-2-lite"
+      },
+      "us.amazon.nova-micro-v1:0": {
+        "id": "us.amazon.nova-micro-v1:0",
+        "name": "Nova Micro (US)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.035,
+          "output": 0.14,
+          "cache_read": 0.00875,
+          "cache_write": 0.035
+        },
+        "limit": {
+          "context": 128000,
+          "output": 10000
+        },
+        "canonical_model_id": "amazon/nova-micro"
+      },
+      "mistral.ministral-3-8b-instruct": {
+        "id": "mistral.ministral-3-8b-instruct",
+        "name": "Ministral 3 8B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.15
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "canonical_model_id": "mistral/ministral-3-8b-instruct-2512"
+      }
+    }
+  },
+  "anthropic": {
+    "id": "anthropic",
+    "name": "Anthropic",
+    "env": ["ANTHROPIC_API_KEY"],
+    "npm": "@ai-sdk/anthropic",
+    "models": {
+      "claude-haiku-4-5": {
+        "id": "claude-haiku-4-5",
+        "name": "Claude Haiku 4.5 (latest)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 5,
+          "cache_read": 0.1,
+          "cache_write": 1.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-haiku-4-5"
+      },
+      "claude-opus-4-5": {
+        "id": "claude-opus-4-5",
+        "name": "Claude Opus 4.5 (latest)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-5"
+      },
+      "claude-sonnet-4-5": {
+        "id": "claude-sonnet-4-5",
+        "name": "Claude Sonnet 4.5 (latest)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-5"
+      },
+      "claude-opus-5-5": {
+        "id": "claude-opus-5-5",
+        "name": "Claude Opus 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.2,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5-5"
+      },
+      "claude-fable-5-1": {
+        "id": "claude-fable-5-1",
+        "name": "Claude Fable 5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 0.25,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-fable-5-1"
+      },
+      "claude-opus-4-5-20251101": {
+        "id": "claude-opus-4-5-20251101",
+        "name": "Claude Opus 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        }
+      },
+      "claude-opus-5": {
+        "id": "claude-opus-5",
+        "name": "Claude Opus 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5"
+      },
+      "claude-fable-5": {
+        "id": "claude-fable-5",
+        "name": "Claude Fable 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        }
+      },
+      "claude-opus-4-8": {
+        "id": "claude-opus-4-8",
+        "name": "Claude Opus 4.8",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        }
+      },
+      "claude-sonnet-4-5-20250929": {
+        "id": "claude-sonnet-4-5-20250929",
+        "name": "Claude Sonnet 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        }
+      },
+      "claude-sonnet-5": {
+        "id": "claude-sonnet-5",
+        "name": "Claude Sonnet 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        }
+      },
+      "claude-opus-4-6": {
+        "id": "claude-opus-4-6",
+        "name": "Claude Opus 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        }
+      },
+      "claude-haiku-4-5-20251001": {
+        "id": "claude-haiku-4-5-20251001",
+        "name": "Claude Haiku 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 5,
+          "cache_read": 0.1,
+          "cache_write": 1.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        }
+      },
+      "claude-sonnet-4-6": {
+        "id": "claude-sonnet-4-6",
+        "name": "Claude Sonnet 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        }
+      },
+      "claude-sonnet-5-5": {
+        "id": "claude-sonnet-5-5",
+        "name": "Claude Sonnet 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5-5"
+      },
+      "claude-opus-4-7": {
+        "id": "claude-opus-4-7",
+        "name": "Claude Opus 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        }
+      }
+    }
+  },
+  "azure": {
+    "id": "azure",
+    "name": "Azure",
+    "env": ["AZURE_RESOURCE_NAME", "AZURE_API_KEY"],
+    "npm": "@ai-sdk/azure",
+    "models": {
+      "grok-4-1-fast-reasoning": {
+        "id": "grok-4-1-fast-reasoning",
+        "name": "Grok 4.1 Fast (Reasoning)",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.5,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "gpt-5.4": {
+        "id": "gpt-5.4",
+        "name": "GPT-5.4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 15,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4"
+      },
+      "deepseek-v3.2-speciale": {
+        "id": "deepseek-v3.2-speciale",
+        "name": "DeepSeek-V3.2-Speciale",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.58,
+          "output": 1.68
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        }
+      },
+      "claude-haiku-4-5": {
+        "id": "claude-haiku-4-5",
+        "name": "Claude Haiku 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 5,
+          "cache_read": 0.1,
+          "cache_write": 1.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/anthropic/v1"
+        }
+      },
+      "gpt-5.4-pro": {
+        "id": "gpt-5.4-pro",
+        "name": "GPT-5.4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 30,
+          "output": 180
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4-pro"
+      },
+      "grok-4-1-fast-non-reasoning": {
+        "id": "grok-4-1-fast-non-reasoning",
+        "name": "Grok 4.1 Fast (Non-Reasoning)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.5,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "phi-4-reasoning": {
+        "id": "phi-4-reasoning",
+        "name": "Phi-4-reasoning",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.125,
+          "output": 0.5
+        },
+        "limit": {
+          "context": 32000,
+          "output": 4096
+        }
+      },
+      "text-embedding-3-small": {
+        "id": "text-embedding-3-small",
+        "name": "text-embedding-3-small",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.02,
+          "output": 0
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "gpt-5.4-nano": {
+        "id": "gpt-5.4-nano",
+        "name": "GPT-5.4 Nano",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.25,
+          "cache_read": 0.02
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4-nano"
+      },
+      "gpt-5.2-codex": {
+        "id": "gpt-5.2-codex",
+        "name": "GPT-5.2 Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "gpt-5.1-codex": {
+        "id": "gpt-5.1-codex",
+        "name": "GPT-5.1 Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "audio"],
+          "output": ["text", "image", "audio"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "gpt-4o": {
+        "id": "gpt-4o",
+        "name": "GPT-4o",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "openai/gpt-4o",
+        "status": "deprecated"
+      },
+      "ministral-3b": {
+        "id": "ministral-3b",
+        "name": "Ministral 3B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.04,
+          "output": 0.04
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "gpt-chat-latest": {
+        "id": "gpt-chat-latest",
+        "name": "GPT Chat Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.5-instant",
+        "status": "beta"
+      },
+      "gpt-5-codex": {
+        "id": "gpt-5-codex",
+        "name": "GPT-5-Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.13
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "gpt-5-mini": {
+        "id": "gpt-5-mini",
+        "name": "GPT-5 Mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "gpt-image-2": {
+        "id": "gpt-image-2",
+        "name": "GPT-Image-2",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["image"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "openai/gpt-image-2"
+      },
+      "o4-mini": {
+        "id": "o4-mini",
+        "name": "o4-mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 4.4,
+          "cache_read": 0.275
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "canonical_model_id": "openai/o4-mini",
+        "status": "deprecated"
+      },
+      "llama-4-maverick-17b-128e-instruct-fp8": {
+        "id": "llama-4-maverick-17b-128e-instruct-fp8",
+        "name": "Llama 4 Maverick 17B 128E Instruct FP8",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 16384
+        }
+      },
+      "o3-mini": {
+        "id": "o3-mini",
+        "name": "o3-mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 4.4,
+          "cache_read": 0.55
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "canonical_model_id": "openai/o3-mini",
+        "status": "deprecated"
+      },
+      "claude-opus-4-5": {
+        "id": "claude-opus-4-5",
+        "name": "Claude Opus 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/anthropic/v1"
+        }
+      },
+      "text-embedding-ada-002": {
+        "id": "text-embedding-ada-002",
+        "name": "text-embedding-ada-002",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "gpt-5.3-codex": {
+        "id": "gpt-5.3-codex",
+        "name": "GPT-5.3 Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "gpt-4.1-nano": {
+        "id": "gpt-4.1-nano",
+        "name": "GPT-4.1 nano",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.4,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 1047576,
+          "output": 32768
+        },
+        "canonical_model_id": "openai/gpt-4.1-nano",
+        "status": "deprecated"
+      },
+      "gpt-5-nano": {
+        "id": "gpt-5-nano",
+        "name": "GPT-5 Nano",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.4,
+          "cache_read": 0.01
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "phi-4-multimodal": {
+        "id": "phi-4-multimodal",
+        "name": "Phi-4-multimodal",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.08,
+          "output": 0.32
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        }
+      },
+      "kimi-k2.6": {
+        "id": "kimi-k2.6",
+        "name": "Kimi K2.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/models"
+        }
+      },
+      "claude-sonnet-4-5": {
+        "id": "claude-sonnet-4-5",
+        "name": "Claude Sonnet 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/anthropic/v1"
+        }
+      },
+      "claude-opus-5-5": {
+        "id": "claude-opus-5-5",
+        "name": "Claude Opus 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.2,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/anthropic/v1"
+        },
+        "canonical_model_id": "anthropic/claude-opus-5-5"
+      },
+      "gpt-image-2.5-flare": {
+        "id": "gpt-image-2.5-flare",
+        "name": "GPT Image 2.5 Flare",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["image"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "openai/gpt-image-2.5-flare"
+      },
+      "claude-fable-5-1": {
+        "id": "claude-fable-5-1",
+        "name": "Claude Fable 5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 0.25,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/anthropic/v1"
+        },
+        "canonical_model_id": "anthropic/claude-fable-5-1"
+      },
+      "mistral-medium-2505": {
+        "id": "mistral-medium-2505",
+        "name": "Mistral Medium 3",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        }
+      },
+      "cohere-embed-v3-multilingual": {
+        "id": "cohere-embed-v3-multilingual",
+        "name": "Embed v3 Multilingual",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0
+        },
+        "limit": {
+          "context": 512,
+          "output": 1024
+        }
+      },
+      "o1": {
+        "id": "o1",
+        "name": "o1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 60,
+          "cache_read": 7.5
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "status": "deprecated"
+      },
+      "codex-mini": {
+        "id": "codex-mini",
+        "name": "Codex Mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 6,
+          "cache_read": 0.375
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "status": "deprecated"
+      },
+      "phi-4-reasoning-plus": {
+        "id": "phi-4-reasoning-plus",
+        "name": "Phi-4-reasoning-plus",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.125,
+          "output": 0.5
+        },
+        "limit": {
+          "context": 32000,
+          "output": 4096
+        }
+      },
+      "claude-mythos-5": {
+        "id": "claude-mythos-5",
+        "name": "Claude Mythos 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/anthropic/v1"
+        },
+        "canonical_model_id": "anthropic/claude-mythos-5",
+        "status": "beta"
+      },
+      "gpt-5-pro": {
+        "id": "gpt-5-pro",
+        "name": "GPT-5 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 120
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5-pro"
+      },
+      "gpt-3.5-turbo-instruct": {
+        "id": "gpt-3.5-turbo-instruct",
+        "name": "GPT-3.5 Turbo Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 2
+        },
+        "limit": {
+          "context": 4096,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "gpt-3.5-turbo-0125": {
+        "id": "gpt-3.5-turbo-0125",
+        "name": "GPT-3.5 Turbo 0125",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.5
+        },
+        "limit": {
+          "context": 16384,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "gpt-6.1-sol": {
+        "id": "gpt-6.1-sol",
+        "name": "GPT-6.1 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.1,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6.1-sol"
+      },
+      "text-embedding-3-large": {
+        "id": "text-embedding-3-large",
+        "name": "text-embedding-3-large",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.13,
+          "output": 0
+        },
+        "limit": {
+          "context": 8192,
+          "output": 3072
+        }
+      },
+      "claude-opus-4-1": {
+        "id": "claude-opus-4-1",
+        "name": "Claude Opus 4.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 75,
+          "cache_read": 1.5,
+          "cache_write": 18.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 32000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/anthropic/v1"
+        }
+      },
+      "cohere-embed-v-4-0": {
+        "id": "cohere-embed-v-4-0",
+        "name": "Embed v4",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.12,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 1536
+        }
+      },
+      "gpt-6-astra": {
+        "id": "gpt-6-astra",
+        "name": "GPT-6 Astra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-astra"
+      },
+      "codestral-2501": {
+        "id": "codestral-2501",
+        "name": "Codestral 25.01",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 0.9
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        }
+      },
+      "kimi-k2.5": {
+        "id": "kimi-k2.5",
+        "name": "Kimi K2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/models"
+        }
+      },
+      "gpt-5.1": {
+        "id": "gpt-5.1",
+        "name": "GPT-5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "audio"],
+          "output": ["text", "image", "audio"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "claude-opus-5": {
+        "id": "claude-opus-5",
+        "name": "Claude Opus 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/anthropic/v1"
+        },
+        "canonical_model_id": "anthropic/claude-opus-5"
+      },
+      "llama-3.3-70b-instruct": {
+        "id": "llama-3.3-70b-instruct",
+        "name": "Llama-3.3-70B-Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.71,
+          "output": 0.71
+        },
+        "limit": {
+          "context": 128000,
+          "output": 32768
+        }
+      },
+      "gpt-4o-mini": {
+        "id": "gpt-4o-mini",
+        "name": "GPT-4o mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "openai/gpt-4o-mini",
+        "status": "deprecated"
+      },
+      "cohere-command-a": {
+        "id": "cohere-command-a",
+        "name": "Command A",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "cohere-embed-v3-english": {
+        "id": "cohere-embed-v3-english",
+        "name": "Embed v3 English",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0
+        },
+        "limit": {
+          "context": 512,
+          "output": 1024
+        }
+      },
+      "model-router": {
+        "id": "model-router",
+        "name": "Model Router",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0
+        },
+        "limit": {
+          "context": 200000,
+          "output": 16384
+        }
+      },
+      "gpt-image-2.5-sunburst": {
+        "id": "gpt-image-2.5-sunburst",
+        "name": "GPT Image 2.5 Sunburst",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["image"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "openai/gpt-image-2.5-sunburst"
+      },
+      "claude-fable-5": {
+        "id": "claude-fable-5",
+        "name": "Claude Fable 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/anthropic/v1"
+        },
+        "canonical_model_id": "anthropic/claude-fable-5",
+        "status": "beta"
+      },
+      "gpt-image-1": {
+        "id": "gpt-image-1",
+        "name": "GPT-Image-1",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["image"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 40,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "openai/gpt-image-1"
+      },
+      "gpt-5.4-mini": {
+        "id": "gpt-5.4-mini",
+        "name": "GPT-5.4 Mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 4.5,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4-mini"
+      },
+      "gpt-5.6-luna": {
+        "id": "gpt-5.6-luna",
+        "name": "GPT-5.6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.2,
+          "cache_read": 0.02,
+          "cache_write": 0.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-luna"
+      },
+      "gpt-5.1-codex-max": {
+        "id": "gpt-5.1-codex-max",
+        "name": "GPT-5.1 Codex Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.1-codex-max"
+      },
+      "gpt-5.2": {
+        "id": "gpt-5.2",
+        "name": "GPT-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "claude-opus-4-8": {
+        "id": "claude-opus-4-8",
+        "name": "Claude Opus 4.8",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/anthropic/v1"
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-8"
+      },
+      "phi-4": {
+        "id": "phi-4",
+        "name": "Phi-4",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.125,
+          "output": 0.5
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        }
+      },
+      "gpt-5.5": {
+        "id": "gpt-5.5",
+        "name": "GPT-5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.5"
+      },
+      "mistral-small-2503": {
+        "id": "mistral-small-2503",
+        "name": "Mistral Small 3.1",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 128000,
+          "output": 32768
+        }
+      },
+      "phi-4-mini-reasoning": {
+        "id": "phi-4-mini-reasoning",
+        "name": "Phi-4-mini-reasoning",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.075,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        }
+      },
+      "gpt-4.1": {
+        "id": "gpt-4.1",
+        "name": "GPT-4.1",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 8,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1047576,
+          "output": 32768
+        },
+        "canonical_model_id": "openai/gpt-4.1",
+        "status": "deprecated"
+      },
+      "claude-sonnet-5": {
+        "id": "claude-sonnet-5",
+        "name": "Claude Sonnet 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/anthropic/v1"
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5"
+      },
+      "claude-opus-4-6": {
+        "id": "claude-opus-4-6",
+        "name": "Claude Opus 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/anthropic/v1"
+        }
+      },
+      "gpt-4-turbo-vision": {
+        "id": "gpt-4-turbo-vision",
+        "name": "GPT-4 Turbo Vision",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 30
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "grok-4-20-non-reasoning": {
+        "id": "grok-4-20-non-reasoning",
+        "name": "Grok 4.20 (Non-Reasoning)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6
+        },
+        "limit": {
+          "context": 262000,
+          "output": 8192
+        },
+        "status": "beta"
+      },
+      "gpt-3.5-turbo-1106": {
+        "id": "gpt-3.5-turbo-1106",
+        "name": "GPT-3.5 Turbo 1106",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 2
+        },
+        "limit": {
+          "context": 16384,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "gpt-4.1-mini": {
+        "id": "gpt-4.1-mini",
+        "name": "GPT-4.1 mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 1.6,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 1047576,
+          "output": 32768
+        },
+        "canonical_model_id": "openai/gpt-4.1-mini",
+        "status": "deprecated"
+      },
+      "gpt-6-luna": {
+        "id": "gpt-6-luna",
+        "name": "GPT-6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.5,
+          "cache_read": 0.01,
+          "cache_write": 0.125
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-luna"
+      },
+      "deepseek-r1": {
+        "id": "deepseek-r1",
+        "name": "DeepSeek-R1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.35,
+          "output": 5.4
+        },
+        "limit": {
+          "context": 163840,
+          "output": 163840
+        },
+        "status": "deprecated"
+      },
+      "deepseek-v4-pro": {
+        "id": "deepseek-v4-pro",
+        "name": "DeepSeek-V4-Pro",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.74,
+          "output": 3.48
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/models"
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro"
+      },
+      "claude-sonnet-4-6": {
+        "id": "claude-sonnet-4-6",
+        "name": "Claude Sonnet 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/anthropic/v1"
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-6"
+      },
+      "llama-4-scout-17b-16e-instruct": {
+        "id": "llama-4-scout-17b-16e-instruct",
+        "name": "Llama 4 Scout 17B 16E Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.78
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "claude-sonnet-5-5": {
+        "id": "claude-sonnet-5-5",
+        "name": "Claude Sonnet 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/anthropic/v1"
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5-5"
+      },
+      "gpt-image-1.5": {
+        "id": "gpt-image-1.5",
+        "name": "GPT-Image-1.5",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 32,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "openai/gpt-image-1.5"
+      },
+      "grok-4-20-reasoning": {
+        "id": "grok-4-20-reasoning",
+        "name": "Grok 4.20 (Reasoning)",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6
+        },
+        "limit": {
+          "context": 262000,
+          "output": 8192
+        },
+        "status": "beta"
+      },
+      "gpt-5.6-terra": {
+        "id": "gpt-5.6-terra",
+        "name": "GPT-5.6 Terra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-terra"
+      },
+      "deepseek-v3.2": {
+        "id": "deepseek-v3.2",
+        "name": "DeepSeek-V3.2",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.58,
+          "output": 1.68
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        }
+      },
+      "gpt-4-turbo": {
+        "id": "gpt-4-turbo",
+        "name": "GPT-4 Turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 30
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "canonical_model_id": "openai/gpt-4-turbo",
+        "status": "deprecated"
+      },
+      "gpt-5.1-codex-mini": {
+        "id": "gpt-5.1-codex-mini",
+        "name": "GPT-5.1 Codex Mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "o3": {
+        "id": "o3",
+        "name": "o3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 8,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "canonical_model_id": "openai/o3"
+      },
+      "claude-opus-4-7": {
+        "id": "claude-opus-4-7",
+        "name": "Claude Opus 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/anthropic/v1"
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-7"
+      },
+      "kimi-k2.7-code": {
+        "id": "kimi-k2.7-code",
+        "name": "Kimi K2.7 Code",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.19
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/models"
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code"
+      },
+      "gpt-5": {
+        "id": "gpt-5",
+        "name": "GPT-5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.13
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "grok-4.6": {
+        "id": "grok-4.6",
+        "name": "Grok 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 200000,
+          "output": 128000
+        },
+        "canonical_model_id": "xai/grok-4.6",
+        "status": "beta"
+      },
+      "gpt-5.6-sol": {
+        "id": "gpt-5.6-sol",
+        "name": "GPT-5.6 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-sol"
+      },
+      "phi-4-mini": {
+        "id": "phi-4-mini",
+        "name": "Phi-4-mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.075,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        }
+      },
+      "deepseek-v4-flash": {
+        "id": "deepseek-v4-flash",
+        "name": "DeepSeek-V4-Flash",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.19,
+          "output": 0.51
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${AZURE_RESOURCE_NAME}.services.ai.azure.com/models"
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash"
+      },
+      "gpt-6-sol": {
+        "id": "gpt-6-sol",
+        "name": "GPT-6 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-sol"
+      }
+    }
+  },
+  "baseten": {
+    "id": "baseten",
+    "name": "Baseten",
+    "env": ["BASETEN_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://inference.baseten.co/v1",
+    "models": {
+      "thinkingmachines/inkling-small": {
+        "id": "thinkingmachines/inkling-small",
+        "name": "Inkling Small",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.2,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 32768
+        },
+        "canonical_model_id": "thinkingmachines/inkling-small"
+      },
+      "thinkingmachines/inkling": {
+        "id": "thinkingmachines/inkling",
+        "name": "Inkling",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 4.05
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 32768
+        },
+        "canonical_model_id": "thinkingmachines/inkling"
+      },
+      "deepseek-ai/DeepSeek-V3.1": {
+        "id": "deepseek-ai/DeepSeek-V3.1",
+        "name": "DeepSeek V3.1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.5
+        },
+        "limit": {
+          "context": 164000,
+          "output": 131000
+        },
+        "status": "deprecated"
+      },
+      "deepseek-ai/DeepSeek-V4-Flash-0731": {
+        "id": "deepseek-ai/DeepSeek-V4-Flash-0731",
+        "name": "DeepSeek V4 Flash 0731",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.13,
+          "output": 0.26,
+          "cache_read": 0.028
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-0731"
+      },
+      "deepseek-ai/DeepSeek-V4-Pro-0813": {
+        "id": "deepseek-ai/DeepSeek-V4-Pro-0813",
+        "name": "DeepSeek V4 Pro 0813",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.32,
+          "output": 3.96
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 262144
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro-0813"
+      },
+      "deepseek-ai/DeepSeek-V4.1-Flash": {
+        "id": "deepseek-ai/DeepSeek-V4.1-Flash",
+        "name": "DeepSeek V4.1 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 32768
+        },
+        "canonical_model_id": "deepseek/deepseek-v4.1-flash"
+      },
+      "deepseek-ai/DeepSeek-V4.1-Flash-Fast": {
+        "id": "deepseek-ai/DeepSeek-V4.1-Flash-Fast",
+        "name": "deepseek-ai/DeepSeek-V4.1-Flash-Fast",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.4
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 32768
+        },
+        "canonical_model_id": "deepseek/deepseek-v4.1-flash"
+      },
+      "deepseek-ai/DeepSeek-V4-Pro": {
+        "id": "deepseek-ai/DeepSeek-V4-Pro",
+        "name": "DeepSeek V4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.74,
+          "output": 3.48,
+          "cache_read": 0.145
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 262144
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro"
+      },
+      "MiniMaxAI/MiniMax-M2.5": {
+        "id": "MiniMaxAI/MiniMax-M2.5",
+        "name": "MiniMax-M2.5",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 204000,
+          "output": 204000
+        },
+        "status": "deprecated"
+      },
+      "moonshotai/Kimi-K2.6": {
+        "id": "moonshotai/Kimi-K2.6",
+        "name": "Kimi K2.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.16
+        },
+        "limit": {
+          "context": 262000,
+          "output": 262000
+        }
+      },
+      "moonshotai/Kimi-K3": {
+        "id": "moonshotai/Kimi-K3",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 262144
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "moonshotai/Kimi-K2.7-Code": {
+        "id": "moonshotai/Kimi-K2.7-Code",
+        "name": "Kimi K2.7 Code",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.16
+        },
+        "limit": {
+          "context": 262000,
+          "output": 262000
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code"
+      },
+      "moonshotai/Kimi-K2.5": {
+        "id": "moonshotai/Kimi-K2.5",
+        "name": "Kimi K2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3,
+          "cache_read": 0.12
+        },
+        "limit": {
+          "context": 262000,
+          "output": 262000
+        }
+      },
+      "zai-org/GLM-5.1": {
+        "id": "zai-org/GLM-5.1",
+        "name": "GLM 5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.3,
+          "output": 4.3,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 202800,
+          "output": 202800
+        },
+        "canonical_model_id": "zhipuai/glm-5.1"
+      },
+      "zai-org/GLM-5.2": {
+        "id": "zai-org/GLM-5.2",
+        "name": "GLM 5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 262144
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "zai-org/GLM-4.7": {
+        "id": "zai-org/GLM-4.7",
+        "name": "GLM 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.2,
+          "cache_read": 0.12
+        },
+        "limit": {
+          "context": 200000,
+          "output": 200000
+        }
+      },
+      "zai-org/GLM-5.2-Fast": {
+        "id": "zai-org/GLM-5.2-Fast",
+        "name": "GLM 5.2 Fast",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.1,
+          "output": 6.6,
+          "cache_read": 0.21
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 262144
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "zai-org/GLM-5.3-Fast": {
+        "id": "zai-org/GLM-5.3-Fast",
+        "name": "GLM 5.3 Fast",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.1,
+          "output": 6.6
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 262144
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "zai-org/GLM-5": {
+        "id": "zai-org/GLM-5",
+        "name": "GLM 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 3.15,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 202800,
+          "output": 202800
+        }
+      },
+      "zai-org/GLM-5.3-Flash": {
+        "id": "zai-org/GLM-5.3-Flash",
+        "name": "GLM 5.3 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.5
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "zai-org/GLM-5.3": {
+        "id": "zai-org/GLM-5.3",
+        "name": "GLM 5.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.14
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 262144
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "nvidia/Nemotron-120B-A12B": {
+        "id": "nvidia/Nemotron-120B-A12B",
+        "name": "Nemotron Super",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 0.75,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 202800,
+          "output": 202800
+        },
+        "canonical_model_id": "nvidia/nemotron-3-super-120b-a12b"
+      },
+      "nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B": {
+        "id": "nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B",
+        "name": "Nemotron Ultra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.4,
+          "cache_read": 0.12
+        },
+        "limit": {
+          "context": 202800,
+          "output": 202800
+        },
+        "canonical_model_id": "nvidia/nemotron-3-ultra-550b-a55b"
+      },
+      "openai/gpt-oss-120b": {
+        "id": "openai/gpt-oss-120b",
+        "name": "OpenAI GPT 120B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.5
+        },
+        "limit": {
+          "context": 128072,
+          "output": 128072
+        }
+      }
+    }
+  },
+  "cerebras": {
+    "id": "cerebras",
+    "name": "Cerebras",
+    "env": ["CEREBRAS_API_KEY"],
+    "npm": "@ai-sdk/cerebras",
+    "models": {
+      "qwen-3.8-27b": {
+        "id": "qwen-3.8-27b",
+        "name": "Qwen3.8 27B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.99,
+          "output": 1.49,
+          "cache_read": 0.99
+        },
+        "limit": {
+          "context": 131072,
+          "output": 40960
+        },
+        "canonical_model_id": "alibaba/qwen3.8-27b"
+      },
+      "gpt-oss-120b": {
+        "id": "gpt-oss-120b",
+        "name": "GPT OSS 120B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.35,
+          "output": 0.75
+        },
+        "limit": {
+          "context": 131072,
+          "output": 40960
+        },
+        "canonical_model_id": "openai/gpt-oss-120b"
+      }
+    }
+  },
+  "cloudflare-ai-gateway": {
+    "id": "cloudflare-ai-gateway",
+    "name": "Cloudflare AI Gateway",
+    "env": [
+      "CLOUDFLARE_API_TOKEN",
+      "CLOUDFLARE_ACCOUNT_ID",
+      "CLOUDFLARE_GATEWAY_ID"
+    ],
+    "npm": "ai-gateway-provider",
+    "models": {
+      "anthropic/claude-opus-4.5": {
+        "id": "anthropic/claude-opus-4.5",
+        "name": "Claude Opus 4.5 (latest)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-5"
+      },
+      "anthropic/claude-opus-4.6": {
+        "id": "anthropic/claude-opus-4.6",
+        "name": "Claude Opus 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-6"
+      },
+      "anthropic/claude-opus-4.7": {
+        "id": "anthropic/claude-opus-4.7",
+        "name": "Claude Opus 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-7"
+      },
+      "anthropic/claude-opus-4.8": {
+        "id": "anthropic/claude-opus-4.8",
+        "name": "Claude Opus 4.8",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-8"
+      },
+      "anthropic/claude-haiku-4.5": {
+        "id": "anthropic/claude-haiku-4.5",
+        "name": "Claude Haiku 4.5 (latest)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 5,
+          "cache_read": 0.1,
+          "cache_write": 1.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-haiku-4-5"
+      },
+      "anthropic/claude-opus-5": {
+        "id": "anthropic/claude-opus-5",
+        "name": "Claude Opus 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-5"
+      },
+      "anthropic/claude-fable-5.1": {
+        "id": "anthropic/claude-fable-5.1",
+        "name": "Claude Fable 5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 0.25,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-fable-5-1"
+      },
+      "anthropic/claude-sonnet-4.5": {
+        "id": "anthropic/claude-sonnet-4.5",
+        "name": "Claude Sonnet 4.5 (latest)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-5"
+      },
+      "anthropic/claude-fable-5": {
+        "id": "anthropic/claude-fable-5",
+        "name": "Claude Fable 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-fable-5"
+      },
+      "anthropic/claude-sonnet-5": {
+        "id": "anthropic/claude-sonnet-5",
+        "name": "Claude Sonnet 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5"
+      },
+      "anthropic/claude-sonnet-4.6": {
+        "id": "anthropic/claude-sonnet-4.6",
+        "name": "Claude Sonnet 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-6"
+      },
+      "anthropic/claude-opus-5.5": {
+        "id": "anthropic/claude-opus-5.5",
+        "name": "Claude Opus 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.2,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-5-5"
+      },
+      "deepseek/deepseek-v4-pro": {
+        "id": "deepseek/deepseek-v4-pro",
+        "name": "DeepSeek V4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.74,
+          "output": 3.48,
+          "cache_read": 0.145
+        },
+        "limit": {
+          "context": 131072,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro"
+      },
+      "unbiased/pareto": {
+        "id": "unbiased/pareto",
+        "name": "Pareto",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 7.5,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "unbiased/pareto"
+      },
+      "alibaba/qwen3.7-max": {
+        "id": "alibaba/qwen3.7-max",
+        "name": "Qwen3.7 Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 3.75,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.7-max"
+      },
+      "alibaba/qwen3.8-max": {
+        "id": "alibaba/qwen3.8-max",
+        "name": "Qwen3.8 Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 0,
+            "max": 262144
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-max"
+      },
+      "alibaba/qwen3-max": {
+        "id": "alibaba/qwen3-max",
+        "name": "Qwen3 Max",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.2,
+          "output": 6
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3-max"
+      },
+      "alibaba/qwen3.5-397b-a17b": {
+        "id": "alibaba/qwen3.5-397b-a17b",
+        "name": "Qwen3.5 397B-A17B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3.6
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.5-397b-a17b"
+      },
+      "alibaba/qwen3.7-plus": {
+        "id": "alibaba/qwen3.7-plus",
+        "name": "Qwen3.7 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.32,
+          "output": 1.28,
+          "cache_read": 0.064
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "canonical_model_id": "alibaba/qwen3.7-plus"
+      },
+      "xai/grok-4.7": {
+        "id": "xai/grok-4.7",
+        "name": "Grok 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "canonical_model_id": "xai/grok-4.7"
+      },
+      "xai/grok-4.3": {
+        "id": "xai/grok-4.3",
+        "name": "Grok 4.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 30000
+        },
+        "canonical_model_id": "xai/grok-4.3"
+      },
+      "xai/grok-4.20-0309-reasoning": {
+        "id": "xai/grok-4.20-0309-reasoning",
+        "name": "Grok 4.20 (Reasoning)",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 30000
+        },
+        "canonical_model_id": "xai/grok-4.20-0309-reasoning"
+      },
+      "xai/grok-4.5": {
+        "id": "xai/grok-4.5",
+        "name": "Grok 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "canonical_model_id": "xai/grok-4.5"
+      },
+      "xai/grok-4.20-0309-non-reasoning": {
+        "id": "xai/grok-4.20-0309-non-reasoning",
+        "name": "Grok 4.20 (Non-Reasoning)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 30000
+        },
+        "canonical_model_id": "xai/grok-4.20-0309-non-reasoning"
+      },
+      "xai/grok-4.6": {
+        "id": "xai/grok-4.6",
+        "name": "Grok 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "canonical_model_id": "xai/grok-4.6"
+      },
+      "moonshotai/kimi-k3": {
+        "id": "moonshotai/kimi-k3",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "openai/gpt-5.4": {
+        "id": "openai/gpt-5.4",
+        "name": "GPT-5.4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 15,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5.4"
+      },
+      "openai/gpt-5.4-pro": {
+        "id": "openai/gpt-5.4-pro",
+        "name": "GPT-5.4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 30,
+          "output": 180
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5.4-pro"
+      },
+      "openai/gpt-5.5-pro": {
+        "id": "openai/gpt-5.5-pro",
+        "name": "GPT-5.5 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 30,
+          "output": 180
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5.5-pro"
+      },
+      "openai/gpt-5.4-nano": {
+        "id": "openai/gpt-5.4-nano",
+        "name": "GPT-5.4 nano",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.25,
+          "cache_read": 0.02
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5.4-nano"
+      },
+      "openai/gpt-4o": {
+        "id": "openai/gpt-4o",
+        "name": "GPT-4o",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 5,
+          "cache_read": 0.625
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-4o"
+      },
+      "openai/gpt-5-mini": {
+        "id": "openai/gpt-5-mini",
+        "name": "GPT-5 Mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5-mini"
+      },
+      "openai/o4-mini": {
+        "id": "openai/o4-mini",
+        "name": "o4-mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 4.4,
+          "cache_read": 0.275
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/o4-mini"
+      },
+      "openai/o3-mini": {
+        "id": "openai/o3-mini",
+        "name": "o3-mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 4.4,
+          "cache_read": 0.55
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/o3-mini"
+      },
+      "openai/gpt-4.1-nano": {
+        "id": "openai/gpt-4.1-nano",
+        "name": "GPT-4.1 nano",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.4,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 32768
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-4.1-nano"
+      },
+      "openai/gpt-5-nano": {
+        "id": "openai/gpt-5-nano",
+        "name": "GPT-5 Nano",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.4,
+          "cache_read": 0.005
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5-nano"
+      },
+      "openai/gpt-6-astra": {
+        "id": "openai/gpt-6-astra",
+        "name": "GPT-6 Astra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-6-astra"
+      },
+      "openai/gpt-5.1": {
+        "id": "openai/gpt-5.1",
+        "name": "GPT-5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5.1"
+      },
+      "openai/gpt-4o-mini": {
+        "id": "openai/gpt-4o-mini",
+        "name": "GPT-4o mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.075,
+          "output": 0.3,
+          "cache_read": 0.0375
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-4o-mini"
+      },
+      "openai/gpt-5.4-mini": {
+        "id": "openai/gpt-5.4-mini",
+        "name": "GPT-5.4 mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 4.5,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5.4-mini"
+      },
+      "openai/gpt-5.6-luna": {
+        "id": "openai/gpt-5.6-luna",
+        "name": "GPT-5.6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.2,
+          "cache_read": 0.02,
+          "cache_write": 0.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5.6-luna"
+      },
+      "openai/gpt-5.5": {
+        "id": "openai/gpt-5.5",
+        "name": "GPT-5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5.5"
+      },
+      "openai/gpt-4.1": {
+        "id": "openai/gpt-4.1",
+        "name": "GPT-4.1",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 8,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1047576,
+          "output": 32768
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-4.1"
+      },
+      "openai/gpt-4.1-mini": {
+        "id": "openai/gpt-4.1-mini",
+        "name": "GPT-4.1 mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 1.6,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 1047576,
+          "output": 32768
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-4.1-mini"
+      },
+      "openai/gpt-6-luna": {
+        "id": "openai/gpt-6-luna",
+        "name": "GPT-6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.5,
+          "cache_read": 0.01,
+          "cache_write": 0.125
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-6-luna"
+      },
+      "openai/gpt-5.6-terra": {
+        "id": "openai/gpt-5.6-terra",
+        "name": "GPT-5.6 Terra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5.6-terra"
+      },
+      "openai/o3": {
+        "id": "openai/o3",
+        "name": "o3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 8,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/o3"
+      },
+      "openai/gpt-5": {
+        "id": "openai/gpt-5",
+        "name": "GPT-5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5"
+      },
+      "openai/gpt-5.6-sol": {
+        "id": "openai/gpt-5.6-sol",
+        "name": "GPT-5.6 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.25,
+          "cache_write": 3.125
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5.6-sol"
+      },
+      "openai/gpt-6-sol": {
+        "id": "openai/gpt-6-sol",
+        "name": "GPT-6 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-6-sol"
+      }
+    }
+  },
+  "cloudflare-workers-ai": {
+    "id": "cloudflare-workers-ai",
+    "name": "Cloudflare Workers AI",
+    "env": ["CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/ai/v1",
+    "models": {
+      "@cf/meta/llama-3.3-70b-instruct-fp8-fast": {
+        "id": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+        "name": "Llama 3.3 70B Instruct fp8 Fast",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.293,
+          "output": 2.253
+        },
+        "limit": {
+          "context": 24000,
+          "output": 24000
+        },
+        "canonical_model_id": "meta/llama-3.3-70b-instruct"
+      },
+      "@cf/meta/llama-guard-3-8b": {
+        "id": "@cf/meta/llama-guard-3-8b",
+        "name": "Llama Guard 3 8B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.484,
+          "output": 0.03
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "canonical_model_id": "meta/llama-guard-3-8b"
+      },
+      "@cf/meta/llama-3.1-8b-instruct-fp8": {
+        "id": "@cf/meta/llama-3.1-8b-instruct-fp8",
+        "name": "Llama 3.1 8B Instruct fp8",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.152,
+          "output": 0.287
+        },
+        "limit": {
+          "context": 32000,
+          "output": 32000
+        },
+        "canonical_model_id": "meta/llama-3.1-8b-instruct"
+      },
+      "@cf/meta/llama-3.2-11b-vision-instruct": {
+        "id": "@cf/meta/llama-3.2-11b-vision-instruct",
+        "name": "Llama 3.2 11B Vision Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.0485,
+          "output": 0.676
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        },
+        "canonical_model_id": "meta/llama-3.2-11b-vision-instruct"
+      },
+      "@cf/meta/llama-3.2-1b-instruct": {
+        "id": "@cf/meta/llama-3.2-1b-instruct",
+        "name": "Llama 3.2 1B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.027,
+          "output": 0.201
+        },
+        "limit": {
+          "context": 60000,
+          "output": 60000
+        },
+        "canonical_model_id": "meta/llama-3.2-1b"
+      },
+      "@cf/meta/llama-4-scout-17b-16e-instruct": {
+        "id": "@cf/meta/llama-4-scout-17b-16e-instruct",
+        "name": "Llama 4 Scout 17B 16E Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.27,
+          "output": 0.85
+        },
+        "limit": {
+          "context": 131000,
+          "output": 16384
+        },
+        "canonical_model_id": "meta/llama-4-scout-17b-instruct"
+      },
+      "@cf/meta/llama-3.2-3b-instruct": {
+        "id": "@cf/meta/llama-3.2-3b-instruct",
+        "name": "Llama 3.2 3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.0509,
+          "output": 0.335
+        },
+        "limit": {
+          "context": 80000,
+          "output": 80000
+        },
+        "canonical_model_id": "meta/llama-3.2-3b"
+      },
+      "@cf/google/gemma-4-26b-a4b-it": {
+        "id": "@cf/google/gemma-4-26b-a4b-it",
+        "name": "Gemma 4 26B A4B IT",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 256000,
+          "output": 16384
+        },
+        "canonical_model_id": "google/gemma-4-26b-a4b-it"
+      },
+      "@cf/aisingapore/gemma-sea-lion-v4-27b-it": {
+        "id": "@cf/aisingapore/gemma-sea-lion-v4-27b-it",
+        "name": "Gemma Sea Lion V4 27B It",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.351,
+          "output": 0.555
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        },
+        "canonical_model_id": "aisingapore/gemma-sea-lion-v4-27b-it"
+      },
+      "@cf/ibm-granite/granite-4.0-h-micro": {
+        "id": "@cf/ibm-granite/granite-4.0-h-micro",
+        "name": "Granite 4.0 H Micro",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.017,
+          "output": 0.112
+        },
+        "limit": {
+          "context": 131000,
+          "output": 131000
+        },
+        "canonical_model_id": "ibm/granite-4-h-micro"
+      },
+      "@cf/deepseek-ai/deepseek-v4-flash-0731": {
+        "id": "@cf/deepseek-ai/deepseek-v4-flash-0731",
+        "name": "DeepSeek V4 Flash 0731",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.44,
+          "output": 1.32,
+          "cache_read": 0.014
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-0731"
+      },
+      "@cf/deepseek-ai/deepseek-v4-pro-0813": {
+        "id": "@cf/deepseek-ai/deepseek-v4-pro-0813",
+        "name": "DeepSeek V4 Pro 0813",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.32,
+          "output": 3.96,
+          "cache_read": 0.044
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro-0813"
+      },
+      "@cf/deepseek-ai/deepseek-r1-distill-qwen-32b": {
+        "id": "@cf/deepseek-ai/deepseek-r1-distill-qwen-32b",
+        "name": "Deepseek R1 Distill Qwen 32B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.497,
+          "output": 4.881
+        },
+        "limit": {
+          "context": 80000,
+          "output": 80000
+        },
+        "canonical_model_id": "deepseek/deepseek-r1"
+      },
+      "@cf/mistralai/mistral-small-3.1-24b-instruct": {
+        "id": "@cf/mistralai/mistral-small-3.1-24b-instruct",
+        "name": "Mistral Small 3.1 24B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.351,
+          "output": 0.555
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        },
+        "canonical_model_id": "mistral/mistral-small-3-1-24b-instruct-2503"
+      },
+      "@cf/moonshotai/kimi-k2.6": {
+        "id": "@cf/moonshotai/kimi-k2.6",
+        "name": "Kimi K2.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.16
+        },
+        "limit": {
+          "context": 262144,
+          "output": 256000
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.6"
+      },
+      "@cf/moonshotai/kimi-k2.7-code": {
+        "id": "@cf/moonshotai/kimi-k2.7-code",
+        "name": "Kimi K2.7 Code",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.19
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code"
+      },
+      "@cf/zai-org/glm-5.3-flash": {
+        "id": "@cf/zai-org/glm-5.3-flash",
+        "name": "Glm 5.3 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "@cf/zai-org/glm-4.7-flash": {
+        "id": "@cf/zai-org/glm-4.7-flash",
+        "name": "GLM-4.7-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.0605,
+          "output": 0.4
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-4.7-flash"
+      },
+      "@cf/zai-org/glm-5.2": {
+        "id": "@cf/zai-org/glm-5.2",
+        "name": "Glm 5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 262144,
+          "output": 256000
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "@cf/zai-org/glm-5.3": {
+        "id": "@cf/zai-org/glm-5.3",
+        "name": "Glm 5.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "@cf/nvidia/nemotron-3-120b-a12b": {
+        "id": "@cf/nvidia/nemotron-3-120b-a12b",
+        "name": "Nemotron 3 Super 120B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.5
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        },
+        "canonical_model_id": "nvidia/nemotron-3-super-120b-a12b"
+      },
+      "@cf/qwen/qwen3.8-27b": {
+        "id": "@cf/qwen/qwen3.8-27b",
+        "name": "Qwen3.8 27B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.45,
+          "output": 3.2,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "alibaba/qwen3.8-27b"
+      },
+      "@cf/qwen/qwq-32b": {
+        "id": "@cf/qwen/qwq-32b",
+        "name": "Qwq 32B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.66,
+          "output": 1
+        },
+        "limit": {
+          "context": 24000,
+          "output": 24000
+        },
+        "canonical_model_id": "alibaba/qwq-32b"
+      },
+      "@cf/qwen/qwen3-30b-a3b-fp8": {
+        "id": "@cf/qwen/qwen3-30b-a3b-fp8",
+        "name": "Qwen3 30B A3b fp8",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.0509,
+          "output": 0.335
+        },
+        "limit": {
+          "context": 32768,
+          "output": 32768
+        },
+        "canonical_model_id": "alibaba/qwen3-30b-a3b"
+      },
+      "@cf/qwen/qwen2.5-coder-32b-instruct": {
+        "id": "@cf/qwen/qwen2.5-coder-32b-instruct",
+        "name": "Qwen2.5 Coder 32B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.66,
+          "output": 1
+        },
+        "limit": {
+          "context": 32768,
+          "output": 32768
+        },
+        "canonical_model_id": "alibaba/qwen2.5-coder-32b-instruct"
+      },
+      "@cf/openai/gpt-oss-20b": {
+        "id": "@cf/openai/gpt-oss-20b",
+        "name": "GPT OSS 20B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "openai/gpt-oss-20b"
+      },
+      "@cf/openai/gpt-oss-120b": {
+        "id": "@cf/openai/gpt-oss-120b",
+        "name": "GPT OSS 120B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.35,
+          "output": 0.75
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "openai/gpt-oss-120b"
+      }
+    }
+  },
+  "deepinfra": {
+    "id": "deepinfra",
+    "name": "Deep Infra",
+    "env": ["DEEPINFRA_API_KEY"],
+    "npm": "@ai-sdk/deepinfra",
+    "models": {
+      "deepseek-ai/DeepSeek-V4-Flash-0731": {
+        "id": "deepseek-ai/DeepSeek-V4-Flash-0731",
+        "name": "DeepSeek V4 Flash 0731",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.18,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-0731"
+      },
+      "deepseek-ai/DeepSeek-V4-Pro-0813": {
+        "id": "deepseek-ai/DeepSeek-V4-Pro-0813",
+        "name": "DeepSeek V4 Pro 0813",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.3,
+          "output": 2.6,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro-0813"
+      },
+      "deepseek-ai/DeepSeek-V4.1-Flash": {
+        "id": "deepseek-ai/DeepSeek-V4.1-Flash",
+        "name": "DeepSeek V4.1 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.6,
+          "cache_read": 0.006
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4.1-flash"
+      },
+      "deepseek-ai/DeepSeek-V3.2": {
+        "id": "deepseek-ai/DeepSeek-V3.2",
+        "name": "DeepSeek-V3.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.26,
+          "output": 0.38,
+          "cache_read": 0.13
+        },
+        "limit": {
+          "context": 163840,
+          "output": 64000
+        }
+      },
+      "moonshotai/Kimi-K2.5": {
+        "id": "moonshotai/Kimi-K2.5",
+        "name": "Kimi K2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.45,
+          "output": 2.25,
+          "cache_read": 0.07
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "status": "deprecated"
+      }
+    }
+  },
+  "deepseek": {
+    "id": "deepseek",
+    "name": "DeepSeek",
+    "env": ["DEEPSEEK_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://api.deepseek.com",
+    "models": {
+      "deepseek-v4-flash-vision-exp": {
+        "id": "deepseek-v4-flash-vision-exp",
+        "name": "DeepSeek V4 Flash Vision Exp",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.003
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 393216
+        },
+        "canonical_model_id": "deepseek/deepseek-v4.1-flash",
+        "status": "deprecated"
+      },
+      "deepseek-flash": {
+        "id": "deepseek-flash",
+        "name": "DeepSeek V4.1 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.003
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 393216
+        },
+        "canonical_model_id": "deepseek/deepseek-v4.1-flash"
+      },
+      "deepseek-v4-pro": {
+        "id": "deepseek-v4-pro",
+        "name": "DeepSeek V4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.435,
+          "output": 0.87,
+          "cache_read": 0.003625
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 393216
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro-0813"
+      },
+      "deepseek-v4-flash": {
+        "id": "deepseek-v4-flash",
+        "name": "DeepSeek V4 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.003
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 393216
+        },
+        "canonical_model_id": "deepseek/deepseek-v4.1-flash",
+        "status": "deprecated"
+      }
+    }
+  },
+  "empiriolabs": {
+    "id": "empiriolabs",
+    "name": "EmpirioLabs AI",
+    "env": ["EMPIRIOLABS_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://api.empiriolabs.ai/v1",
+    "models": {
+      "muse-glimmer-30b": {
+        "id": "muse-glimmer-30b",
+        "name": "Muse Glimmer 30B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.8,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "meta/muse-glimmer-30b"
+      }
+    }
+  },
+  "fireworks-ai": {
+    "id": "fireworks-ai",
+    "name": "Fireworks AI",
+    "env": ["FIREWORKS_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://api.fireworks.ai/inference/v1/",
+    "models": {
+      "accounts/fireworks/models/nemotron-3-ultra-nvfp4": {
+        "id": "accounts/fireworks/models/nemotron-3-ultra-nvfp4",
+        "name": "Nemotron 3 Ultra 550B A55B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.4,
+          "cache_read": 0.12
+        },
+        "limit": {
+          "context": 262144,
+          "output": 128000
+        },
+        "canonical_model_id": "nvidia/nemotron-3-ultra-550b-a55b"
+      },
+      "accounts/fireworks/models/kimi-k3": {
+        "id": "accounts/fireworks/models/kimi-k3",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "accounts/fireworks/models/qwen3p8-2p4t-a95b": {
+        "id": "accounts/fireworks/models/qwen3p8-2p4t-a95b",
+        "name": "Qwen3.8 2.4T A95B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-2.4t-a95b"
+      },
+      "accounts/fireworks/models/ember-1": {
+        "id": "accounts/fireworks/models/ember-1",
+        "name": "Ember-1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        }
+      },
+      "accounts/fireworks/models/deepseek-v4p1-flash": {
+        "id": "accounts/fireworks/models/deepseek-v4p1-flash",
+        "name": "DeepSeek V4.1 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.22,
+          "output": 0.66,
+          "cache_read": 0.007
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4.1-flash"
+      },
+      "accounts/fireworks/models/glm-5p3": {
+        "id": "accounts/fireworks/models/glm-5p3",
+        "name": "GLM 5.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 1048573,
+          "output": 262144
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "accounts/fireworks/models/nemotron-lightning-3p5-30b-a3b": {
+        "id": "accounts/fireworks/models/nemotron-lightning-3p5-30b-a3b",
+        "name": "Nemotron 3.5 Lightning 30B A3B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.2,
+          "cache_read": 0.01
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "nvidia/nemotron-3.5-lightning"
+      },
+      "accounts/fireworks/models/inkling": {
+        "id": "accounts/fireworks/models/inkling",
+        "name": "Inkling",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 4.05,
+          "cache_read": 0.17
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        },
+        "canonical_model_id": "thinkingmachines/inkling"
+      },
+      "accounts/fireworks/models/minimax-m3": {
+        "id": "accounts/fireworks/models/minimax-m3",
+        "name": "MiniMax-M3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 512000,
+          "output": 512000
+        }
+      },
+      "accounts/fireworks/models/glm-5p3-flash": {
+        "id": "accounts/fireworks/models/glm-5p3-flash",
+        "name": "GLM 5.3 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1048573,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "accounts/fireworks/models/gpt-oss-120b": {
+        "id": "accounts/fireworks/models/gpt-oss-120b",
+        "name": "GPT OSS 120B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "accounts/fireworks/models/qwen3p8-max": {
+        "id": "accounts/fireworks/models/qwen3p8-max",
+        "name": "Qwen3.8 Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-max"
+      },
+      "accounts/fireworks/routers/minimax-latest": {
+        "id": "accounts/fireworks/routers/minimax-latest",
+        "name": "MiniMax Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 512000,
+          "output": 512000
+        },
+        "canonical_model_id": "minimax/MiniMax-M3"
+      },
+      "accounts/fireworks/routers/glm-flash-latest": {
+        "id": "accounts/fireworks/routers/glm-flash-latest",
+        "name": "GLM Flash Latest (GLM 5.3 Flash)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1048573,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "accounts/fireworks/routers/glm-fast-latest": {
+        "id": "accounts/fireworks/routers/glm-fast-latest",
+        "name": "GLM 5.3 Fast (Latest)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.1,
+          "output": 6.6,
+          "cache_read": 0.39
+        },
+        "limit": {
+          "context": 1048572,
+          "output": 262144
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "accounts/fireworks/routers/kimi-k3-fast": {
+        "id": "accounts/fireworks/routers/kimi-k3-fast",
+        "name": "Kimi K3 Fast",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4.5,
+          "output": 22.5,
+          "cache_read": 0.45
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "accounts/fireworks/routers/glm-5p3-fast": {
+        "id": "accounts/fireworks/routers/glm-5p3-fast",
+        "name": "GLM 5.3 Fast",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.1,
+          "output": 6.6,
+          "cache_read": 0.39
+        },
+        "limit": {
+          "context": 1048572,
+          "output": 262144
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "accounts/fireworks/routers/kimi-fast-latest": {
+        "id": "accounts/fireworks/routers/kimi-fast-latest",
+        "name": "Kimi Fast Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4.5,
+          "output": 22.5,
+          "cache_read": 0.45
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "accounts/fireworks/routers/qwen-max-latest": {
+        "id": "accounts/fireworks/routers/qwen-max-latest",
+        "name": "Qwen Max Latest (Qwen3.8 Max)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-max"
+      },
+      "accounts/fireworks/routers/kimi-latest": {
+        "id": "accounts/fireworks/routers/kimi-latest",
+        "name": "Kimi Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "accounts/fireworks/routers/deepseek-flash-latest": {
+        "id": "accounts/fireworks/routers/deepseek-flash-latest",
+        "name": "DeepSeek Flash Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.22,
+          "output": 0.66,
+          "cache_read": 0.007
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4.1-flash"
+      },
+      "accounts/fireworks/routers/glm-latest": {
+        "id": "accounts/fireworks/routers/glm-latest",
+        "name": "GLM Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 1048573,
+          "output": 262144
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      }
+    }
+  },
+  "google": {
+    "id": "google",
+    "name": "Google",
+    "env": ["GOOGLE_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY", "GEMINI_API_KEY"],
+    "npm": "@ai-sdk/google",
+    "models": {
+      "gemini-flash-latest": {
+        "id": "gemini-flash-latest",
+        "name": "Gemini Flash Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 3.75,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        }
+      },
+      "gemma-4-31b-it": {
+        "id": "gemma-4-31b-it",
+        "name": "Gemma 4 31B IT",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "gemini-omni-flash-preview": {
+        "id": "gemini-omni-flash-preview",
+        "name": "Gemini Omni Flash Preview",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["video"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 17.5
+        },
+        "limit": {
+          "context": 131072,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-omni-flash-preview"
+      },
+      "gemini-3.1-flash-image-preview": {
+        "id": "gemini-3.1-flash-image-preview",
+        "name": "Nano Banana 2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 60
+        },
+        "limit": {
+          "context": 65536,
+          "output": 65536
+        }
+      },
+      "veo-3.1-lite-generate-preview": {
+        "id": "veo-3.1-lite-generate-preview",
+        "name": "Veo 3.1 lite",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 480,
+          "output": 8192
+        },
+        "canonical_model_id": "google/veo-3.1-lite-generate-preview"
+      },
+      "lyria-3-pro-preview": {
+        "id": "lyria-3-pro-preview",
+        "name": "Lyria 3 Pro Preview",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/lyria-3-pro-preview"
+      },
+      "gemini-3.1-flash-tts-preview": {
+        "id": "gemini-3.1-flash-tts-preview",
+        "name": "Gemini 3.1 Flash TTS Preview",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["audio"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 20
+        },
+        "limit": {
+          "context": 8192,
+          "output": 16384
+        },
+        "canonical_model_id": "google/gemini-3.1-flash-tts-preview"
+      },
+      "gemini-2.5-flash-image": {
+        "id": "gemini-2.5-flash-image",
+        "name": "Nano Banana",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 30,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 32768,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemini-2.5-flash-image"
+      },
+      "gemini-flash-lite-latest": {
+        "id": "gemini-flash-lite-latest",
+        "name": "Gemini Flash-Lite Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        }
+      },
+      "gemini-embedding-2": {
+        "id": "gemini-embedding-2",
+        "name": "Gemini Embedding 2",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "audio", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1
+        },
+        "canonical_model_id": "google/gemini-embedding-2"
+      },
+      "gemini-3.6-flash": {
+        "id": "gemini-3.6-flash",
+        "name": "Gemini 3.6 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 3.75,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.6-flash"
+      },
+      "gemma-4-26b-a4b-it": {
+        "id": "gemma-4-26b-a4b-it",
+        "name": "Gemma 4 26B A4B IT",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "gemini-3-pro-image-preview": {
+        "id": "gemini-3-pro-image-preview",
+        "name": "Nano Banana Pro",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 120
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemini-3-pro-image-preview"
+      },
+      "gemini-2.5-pro-preview-tts": {
+        "id": "gemini-2.5-pro-preview-tts",
+        "name": "Gemini 2.5 Pro Preview TTS",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["audio"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 20
+        },
+        "limit": {
+          "context": 8192,
+          "output": 16384
+        }
+      },
+      "gemini-3.5-flash-lite": {
+        "id": "gemini-3.5-flash-lite",
+        "name": "Gemini 3.5 Flash Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.5-flash-lite"
+      },
+      "gemini-3.1-flash-image": {
+        "id": "gemini-3.1-flash-image",
+        "name": "Nano Banana 2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 60
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemini-3.1-flash-image"
+      },
+      "lyria-3-clip-preview": {
+        "id": "lyria-3-clip-preview",
+        "name": "Lyria 3 Clip Preview",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/lyria-3-clip-preview"
+      },
+      "gemini-3.1-pro-preview": {
+        "id": "gemini-3.1-pro-preview",
+        "name": "Gemini 3.1 Pro Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        }
+      },
+      "gemini-2.5-computer-use-preview-10-2025": {
+        "id": "gemini-2.5-computer-use-preview-10-2025",
+        "name": "Gemini 2.5 Computer Use Preview 10-2025",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10
+        },
+        "limit": {
+          "context": 128000,
+          "output": 64000
+        },
+        "canonical_model_id": "google/gemini-2.5-computer-use-preview-10-2025"
+      },
+      "gemini-3.5-flash": {
+        "id": "gemini-3.5-flash",
+        "name": "Gemini 3.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 9,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        }
+      },
+      "gemini-2.5-pro": {
+        "id": "gemini-2.5-pro",
+        "name": "Gemini 2.5 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 128,
+            "max": 32768
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-2.5-pro"
+      },
+      "gemini-3-pro-image": {
+        "id": "gemini-3-pro-image",
+        "name": "Nano Banana Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 120
+        },
+        "limit": {
+          "context": 65536,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemini-3-pro-image"
+      },
+      "gemini-2.5-flash": {
+        "id": "gemini-2.5-flash",
+        "name": "Gemini 2.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 0,
+            "max": 24576
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-2.5-flash"
+      },
+      "gemini-2.5-flash-preview-tts": {
+        "id": "gemini-2.5-flash-preview-tts",
+        "name": "Gemini 2.5 Flash Preview TTS",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["audio"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 10
+        },
+        "limit": {
+          "context": 8192,
+          "output": 16384
+        }
+      },
+      "gemini-3.1-flash-lite-image": {
+        "id": "gemini-3.1-flash-lite-image",
+        "name": "Nano Banana 2 Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 30
+        },
+        "limit": {
+          "context": 65536,
+          "output": 4096
+        },
+        "canonical_model_id": "google/gemini-3.1-flash-lite-image"
+      },
+      "deep-research-preview-04-2026": {
+        "id": "deep-research-preview-04-2026",
+        "name": "Deep Research Preview (Apr-21-2026)",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 131072,
+          "output": 65536
+        },
+        "canonical_model_id": "google/deep-research-preview-04-2026"
+      },
+      "deep-research-max-preview-04-2026": {
+        "id": "deep-research-max-preview-04-2026",
+        "name": "Deep Research Max Preview (Apr-21-2026)",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 131072,
+          "output": 65536
+        },
+        "canonical_model_id": "google/deep-research-max-preview-04-2026"
+      },
+      "veo-3.1-fast-generate-preview": {
+        "id": "veo-3.1-fast-generate-preview",
+        "name": "Veo 3.1 fast",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 480,
+          "output": 8192
+        },
+        "canonical_model_id": "google/veo-3.1-fast-generate-preview"
+      },
+      "gemini-3.7-flash": {
+        "id": "gemini-3.7-flash",
+        "name": "Gemini 3.7 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 3.75,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.7-flash"
+      },
+      "veo-3.1-generate-preview": {
+        "id": "veo-3.1-generate-preview",
+        "name": "Veo 3.1",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 480,
+          "output": 8192
+        },
+        "canonical_model_id": "google/veo-3.1-generate-preview",
+        "status": "beta"
+      },
+      "gemini-3.1-pro-preview-customtools": {
+        "id": "gemini-3.1-pro-preview-customtools",
+        "name": "Gemini 3.1 Pro Preview Custom Tools",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        }
+      },
+      "gemini-3-flash-preview": {
+        "id": "gemini-3-flash-preview",
+        "name": "Gemini 3 Flash Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        }
+      },
+      "gemini-3.8-flash": {
+        "id": "gemini-3.8-flash",
+        "name": "Gemini 3.8 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 3.75,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.8-flash"
+      },
+      "gemini-3.5-live-translate-preview": {
+        "id": "gemini-3.5-live-translate-preview",
+        "name": "Gemini 3.5 Live Translate Preview",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["audio"],
+          "output": ["audio", "text"]
+        },
+        "cost": {
+          "input": 3.5,
+          "output": 21
+        },
+        "limit": {
+          "context": 16384,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemini-3.5-live-translate-preview"
+      },
+      "gemini-2.5-flash-lite": {
+        "id": "gemini-2.5-flash-lite",
+        "name": "Gemini 2.5 Flash-Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 512,
+            "max": 24576
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.4,
+          "cache_read": 0.01
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        }
+      },
+      "gemini-embedding-001": {
+        "id": "gemini-embedding-001",
+        "name": "Gemini Embedding 001",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0
+        },
+        "limit": {
+          "context": 2048,
+          "output": 1
+        }
+      },
+      "gemini-3.1-flash-lite-preview": {
+        "id": "gemini-3.1-flash-lite-preview",
+        "name": "Gemini 3.1 Flash Lite Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1.5,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "status": "deprecated"
+      },
+      "gemini-3.1-flash-live-preview": {
+        "id": "gemini-3.1-flash-live-preview",
+        "name": "Gemini 3.1 Flash Live Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 4.5
+        },
+        "limit": {
+          "context": 131072,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.1-flash-live-preview"
+      },
+      "gemini-3.1-flash-lite": {
+        "id": "gemini-3.1-flash-lite",
+        "name": "Gemini 3.1 Flash Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1.5,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        }
+      }
+    }
+  },
+  "google-vertex": {
+    "id": "google-vertex",
+    "name": "Vertex",
+    "env": [
+      "GOOGLE_VERTEX_PROJECT",
+      "GOOGLE_VERTEX_LOCATION",
+      "GOOGLE_APPLICATION_CREDENTIALS"
+    ],
+    "npm": "@ai-sdk/google-vertex",
+    "models": {
+      "claude-opus-4-8@default": {
+        "id": "claude-opus-4-8@default",
+        "name": "Claude Opus 4.8",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/google-vertex/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-8"
+      },
+      "gemini-2.5-flash-tts": {
+        "id": "gemini-2.5-flash-tts",
+        "name": "Gemini 2.5 Flash TTS",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["audio"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 10
+        },
+        "limit": {
+          "context": 32768,
+          "output": 16384
+        },
+        "canonical_model_id": "google/gemini-2.5-flash-tts"
+      },
+      "gemini-flash-latest": {
+        "id": "gemini-flash-latest",
+        "name": "Gemini Flash Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 9,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-flash-latest"
+      },
+      "claude-sonnet-4-5@20250929": {
+        "id": "claude-sonnet-4-5@20250929",
+        "name": "Claude Sonnet 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "provider": {
+          "npm": "@ai-sdk/google-vertex/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-5-20250929"
+      },
+      "gemini-2.5-flash-image": {
+        "id": "gemini-2.5-flash-image",
+        "name": "Nano Banana",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 30
+        },
+        "limit": {
+          "context": 32768,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemini-2.5-flash-image"
+      },
+      "claude-opus-4-6@default": {
+        "id": "claude-opus-4-6@default",
+        "name": "Claude Opus 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/google-vertex/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-6"
+      },
+      "claude-opus-4@20250514": {
+        "id": "claude-opus-4@20250514",
+        "name": "Claude Opus 4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 75,
+          "cache_read": 1.5,
+          "cache_write": 18.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 32000
+        },
+        "provider": {
+          "npm": "@ai-sdk/google-vertex/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-20250514",
+        "status": "deprecated"
+      },
+      "gemini-flash-lite-latest": {
+        "id": "gemini-flash-lite-latest",
+        "name": "Gemini Flash-Lite Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1.5,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-flash-lite-latest"
+      },
+      "claude-sonnet-5-5@default": {
+        "id": "claude-sonnet-5-5@default",
+        "name": "Claude Sonnet 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/google-vertex/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5-5"
+      },
+      "claude-opus-5-5@default": {
+        "id": "claude-opus-5-5@default",
+        "name": "Claude Opus 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.2,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/google-vertex/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-5-5"
+      },
+      "gemini-3.6-flash": {
+        "id": "gemini-3.6-flash",
+        "name": "Gemini 3.6 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 3.75,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.6-flash"
+      },
+      "claude-opus-5@default": {
+        "id": "claude-opus-5@default",
+        "name": "Claude Opus 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/google-vertex/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-5"
+      },
+      "claude-sonnet-4-6@default": {
+        "id": "claude-sonnet-4-6@default",
+        "name": "Claude Sonnet 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/google-vertex/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-6"
+      },
+      "claude-haiku-4-5@20251001": {
+        "id": "claude-haiku-4-5@20251001",
+        "name": "Claude Haiku 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 5,
+          "cache_read": 0.1,
+          "cache_write": 1.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "provider": {
+          "npm": "@ai-sdk/google-vertex/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-haiku-4-5-20251001"
+      },
+      "gemini-3.5-flash-lite": {
+        "id": "gemini-3.5-flash-lite",
+        "name": "Gemini 3.5 Flash Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.5-flash-lite"
+      },
+      "gemini-3.1-flash-image": {
+        "id": "gemini-3.1-flash-image",
+        "name": "Nano Banana 2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 60,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemini-3.1-flash-image"
+      },
+      "gemini-3.1-pro-preview": {
+        "id": "gemini-3.1-pro-preview",
+        "name": "Gemini 3.1 Pro Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.1-pro-preview"
+      },
+      "claude-opus-4-1@20250805": {
+        "id": "claude-opus-4-1@20250805",
+        "name": "Claude Opus 4.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 75,
+          "cache_read": 1.5,
+          "cache_write": 18.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 32000
+        },
+        "provider": {
+          "npm": "@ai-sdk/google-vertex/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-1-20250805",
+        "status": "deprecated"
+      },
+      "claude-opus-4-5@20251101": {
+        "id": "claude-opus-4-5@20251101",
+        "name": "Claude Opus 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "provider": {
+          "npm": "@ai-sdk/google-vertex/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-5-20251101"
+      },
+      "claude-opus-4-7@default": {
+        "id": "claude-opus-4-7@default",
+        "name": "Claude Opus 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/google-vertex/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-7"
+      },
+      "gemini-3.5-flash": {
+        "id": "gemini-3.5-flash",
+        "name": "Gemini 3.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 9,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.5-flash"
+      },
+      "gemini-2.5-pro": {
+        "id": "gemini-2.5-pro",
+        "name": "Gemini 2.5 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 128,
+            "max": 32768
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-2.5-pro"
+      },
+      "gemini-3-pro-image": {
+        "id": "gemini-3-pro-image",
+        "name": "Nano Banana Pro",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 120,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 65536,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemini-3-pro-image"
+      },
+      "gemini-2.5-flash": {
+        "id": "gemini-2.5-flash",
+        "name": "Gemini 2.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 0,
+            "max": 24576
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        }
+      },
+      "claude-fable-5-1@default": {
+        "id": "claude-fable-5-1@default",
+        "name": "Claude Fable 5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 0.25,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/google-vertex/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-fable-5-1"
+      },
+      "gemini-3.7-flash": {
+        "id": "gemini-3.7-flash",
+        "name": "Gemini 3.7 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 3.75,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.7-flash"
+      },
+      "gemini-3.1-pro-preview-customtools": {
+        "id": "gemini-3.1-pro-preview-customtools",
+        "name": "Gemini 3.1 Pro Preview Custom Tools",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.1-pro-preview-customtools"
+      },
+      "gemini-3-flash-preview": {
+        "id": "gemini-3-flash-preview",
+        "name": "Gemini 3 Flash Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3-flash-preview"
+      },
+      "claude-fable-5@default": {
+        "id": "claude-fable-5@default",
+        "name": "Claude Fable 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/google-vertex/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-fable-5"
+      },
+      "gemini-3.8-flash": {
+        "id": "gemini-3.8-flash",
+        "name": "Gemini 3.8 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 3.75,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.8-flash"
+      },
+      "gemini-2.5-flash-lite": {
+        "id": "gemini-2.5-flash-lite",
+        "name": "Gemini 2.5 Flash-Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 512,
+            "max": 24576
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.4,
+          "cache_read": 0.01
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65535
+        },
+        "canonical_model_id": "google/gemini-2.5-flash-lite"
+      },
+      "gemini-2.5-pro-tts": {
+        "id": "gemini-2.5-pro-tts",
+        "name": "Gemini 2.5 Pro TTS",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["audio"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 20
+        },
+        "limit": {
+          "context": 32768,
+          "output": 16384
+        },
+        "canonical_model_id": "google/gemini-2.5-pro-tts"
+      },
+      "gemini-embedding-001": {
+        "id": "gemini-embedding-001",
+        "name": "Gemini Embedding 001",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0
+        },
+        "limit": {
+          "context": 2048,
+          "output": 1
+        },
+        "canonical_model_id": "google/gemini-embedding-001"
+      },
+      "claude-sonnet-4@20250514": {
+        "id": "claude-sonnet-4@20250514",
+        "name": "Claude Sonnet 4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "provider": {
+          "npm": "@ai-sdk/google-vertex/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-20250514",
+        "status": "deprecated"
+      },
+      "gemini-3.1-flash-lite-preview": {
+        "id": "gemini-3.1-flash-lite-preview",
+        "name": "Gemini 3.1 Flash Lite Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1.5,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.1-flash-lite-preview",
+        "status": "deprecated"
+      },
+      "claude-sonnet-5@default": {
+        "id": "claude-sonnet-5@default",
+        "name": "Claude Sonnet 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/google-vertex/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5"
+      },
+      "gemini-3.1-flash-lite": {
+        "id": "gemini-3.1-flash-lite",
+        "name": "Gemini 3.1 Flash Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1.5,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.1-flash-lite"
+      },
+      "meta/llama-4-maverick-17b-128e-instruct-maas": {
+        "id": "meta/llama-4-maverick-17b-128e-instruct-maas",
+        "name": "Llama 4 Maverick 17B 128E Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.35,
+          "output": 1.15
+        },
+        "limit": {
+          "context": 524288,
+          "output": 8192
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${GOOGLE_VERTEX_ENDPOINT}/v1/projects/${GOOGLE_VERTEX_PROJECT}/locations/${GOOGLE_VERTEX_LOCATION}/endpoints/openapi"
+        }
+      },
+      "meta/llama-3.3-70b-instruct-maas": {
+        "id": "meta/llama-3.3-70b-instruct-maas",
+        "name": "Llama 3.3 70B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.72,
+          "output": 0.72
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${GOOGLE_VERTEX_ENDPOINT}/v1/projects/${GOOGLE_VERTEX_PROJECT}/locations/${GOOGLE_VERTEX_LOCATION}/endpoints/openapi"
+        },
+        "status": "deprecated"
+      },
+      "xai/grok-4.20-reasoning": {
+        "id": "xai/grok-4.20-reasoning",
+        "name": "Grok 4.20 (Reasoning)",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 30000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${GOOGLE_VERTEX_ENDPOINT}/v1/projects/${GOOGLE_VERTEX_PROJECT}/locations/${GOOGLE_VERTEX_LOCATION}/endpoints/openapi"
+        },
+        "canonical_model_id": "xai/grok-4.20-0309-reasoning"
+      },
+      "xai/grok-4.20-non-reasoning": {
+        "id": "xai/grok-4.20-non-reasoning",
+        "name": "Grok 4.20 (Non-Reasoning)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 30000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${GOOGLE_VERTEX_ENDPOINT}/v1/projects/${GOOGLE_VERTEX_PROJECT}/locations/${GOOGLE_VERTEX_LOCATION}/endpoints/openapi"
+        },
+        "canonical_model_id": "xai/grok-4.20-0309-non-reasoning"
+      },
+      "xai/grok-4.1-fast-reasoning": {
+        "id": "xai/grok-4.1-fast-reasoning",
+        "name": "Grok 4.1 Fast (Reasoning)",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.5,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 128000,
+          "output": 30000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${GOOGLE_VERTEX_ENDPOINT}/v1/projects/${GOOGLE_VERTEX_PROJECT}/locations/${GOOGLE_VERTEX_LOCATION}/endpoints/openapi"
+        },
+        "canonical_model_id": "xai/grok-4.1-fast-reasoning",
+        "status": "deprecated"
+      },
+      "xai/grok-4.3": {
+        "id": "xai/grok-4.3",
+        "name": "Grok 4.3",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 200000,
+          "output": 30000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${GOOGLE_VERTEX_ENDPOINT}/v1/projects/${GOOGLE_VERTEX_PROJECT}/locations/${GOOGLE_VERTEX_LOCATION}/endpoints/openapi"
+        },
+        "canonical_model_id": "xai/grok-4.3",
+        "status": "beta"
+      },
+      "xai/grok-4.1-fast-non-reasoning": {
+        "id": "xai/grok-4.1-fast-non-reasoning",
+        "name": "Grok 4.1 Fast",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.5,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 128000,
+          "output": 30000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${GOOGLE_VERTEX_ENDPOINT}/v1/projects/${GOOGLE_VERTEX_PROJECT}/locations/${GOOGLE_VERTEX_LOCATION}/endpoints/openapi"
+        },
+        "canonical_model_id": "xai/grok-4.1-fast",
+        "status": "deprecated"
+      },
+      "xai/grok-4.6": {
+        "id": "xai/grok-4.6",
+        "name": "Grok 4.6",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 524288,
+          "output": 500000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${GOOGLE_VERTEX_ENDPOINT}/v1/projects/${GOOGLE_VERTEX_PROJECT}/locations/${GOOGLE_VERTEX_LOCATION}/endpoints/openapi"
+        },
+        "canonical_model_id": "xai/grok-4.6",
+        "status": "beta"
+      },
+      "deepseek-ai/deepseek-v3.1-maas": {
+        "id": "deepseek-ai/deepseek-v3.1-maas",
+        "name": "DeepSeek V3.1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 1.7,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 163840,
+          "output": 32768
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${GOOGLE_VERTEX_ENDPOINT}/v1/projects/${GOOGLE_VERTEX_PROJECT}/locations/${GOOGLE_VERTEX_LOCATION}/endpoints/openapi"
+        },
+        "status": "deprecated"
+      },
+      "deepseek-ai/deepseek-v3.2-maas": {
+        "id": "deepseek-ai/deepseek-v3.2-maas",
+        "name": "DeepSeek V3.2",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.56,
+          "output": 1.68,
+          "cache_read": 0.056
+        },
+        "limit": {
+          "context": 163840,
+          "output": 65536
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${GOOGLE_VERTEX_ENDPOINT}/v1/projects/${GOOGLE_VERTEX_PROJECT}/locations/${GOOGLE_VERTEX_LOCATION}/endpoints/openapi"
+        },
+        "status": "deprecated"
+      },
+      "moonshotai/kimi-k2-thinking-maas": {
+        "id": "moonshotai/kimi-k2-thinking-maas",
+        "name": "Kimi K2 Thinking",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.5,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${GOOGLE_VERTEX_ENDPOINT}/v1/projects/${GOOGLE_VERTEX_PROJECT}/locations/${GOOGLE_VERTEX_LOCATION}/endpoints/openapi"
+        },
+        "status": "deprecated"
+      },
+      "zai-org/glm-5-maas": {
+        "id": "zai-org/glm-5-maas",
+        "name": "GLM-5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 3.2,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 200000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${GOOGLE_VERTEX_ENDPOINT}/v1/projects/${GOOGLE_VERTEX_PROJECT}/locations/${GOOGLE_VERTEX_LOCATION}/endpoints/openapi"
+        },
+        "canonical_model_id": "zhipuai/glm-5",
+        "status": "deprecated"
+      },
+      "zai-org/glm-4.7-maas": {
+        "id": "zai-org/glm-4.7-maas",
+        "name": "GLM-4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.2,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 200000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${GOOGLE_VERTEX_ENDPOINT}/v1/projects/${GOOGLE_VERTEX_PROJECT}/locations/${GOOGLE_VERTEX_LOCATION}/endpoints/openapi"
+        },
+        "status": "deprecated"
+      },
+      "zai-org/glm-5.2-maas": {
+        "id": "zai-org/glm-5.2-maas",
+        "name": "GLM-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.14
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${GOOGLE_VERTEX_ENDPOINT}/v1/projects/${GOOGLE_VERTEX_PROJECT}/locations/${GOOGLE_VERTEX_LOCATION}/endpoints/openapi"
+        },
+        "canonical_model_id": "zhipuai/glm-5.2",
+        "status": "beta"
+      },
+      "qwen/qwen3-235b-a22b-instruct-2507-maas": {
+        "id": "qwen/qwen3-235b-a22b-instruct-2507-maas",
+        "name": "Qwen3 235B A22B Instruct",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.22,
+          "output": 0.88
+        },
+        "limit": {
+          "context": 262144,
+          "output": 16384
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${GOOGLE_VERTEX_ENDPOINT}/v1/projects/${GOOGLE_VERTEX_PROJECT}/locations/${GOOGLE_VERTEX_LOCATION}/endpoints/openapi"
+        },
+        "status": "deprecated"
+      },
+      "openai/gpt-oss-20b-maas": {
+        "id": "openai/gpt-oss-20b-maas",
+        "name": "GPT OSS 20B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.25,
+          "cache_read": 0.007
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${GOOGLE_VERTEX_ENDPOINT}/v1/projects/${GOOGLE_VERTEX_PROJECT}/locations/${GOOGLE_VERTEX_LOCATION}/endpoints/openapi"
+        },
+        "status": "deprecated"
+      },
+      "openai/gpt-oss-120b-maas": {
+        "id": "openai/gpt-oss-120b-maas",
+        "name": "GPT OSS 120B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.09,
+          "output": 0.36
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai-compatible",
+          "api": "https://${GOOGLE_VERTEX_ENDPOINT}/v1/projects/${GOOGLE_VERTEX_PROJECT}/locations/${GOOGLE_VERTEX_LOCATION}/endpoints/openapi"
+        },
+        "canonical_model_id": "openai/gpt-oss-120b"
+      }
+    }
+  },
+  "google-vertex-anthropic": {
+    "id": "google-vertex-anthropic",
+    "name": "Vertex (Anthropic)",
+    "env": [
+      "GOOGLE_VERTEX_PROJECT",
+      "GOOGLE_VERTEX_LOCATION",
+      "GOOGLE_APPLICATION_CREDENTIALS"
+    ],
+    "npm": "@ai-sdk/google-vertex/anthropic",
+    "models": {
+      "claude-opus-4-8@default": {
+        "id": "claude-opus-4-8@default",
+        "name": "Claude Opus 4.8",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-8"
+      },
+      "claude-sonnet-4-5@20250929": {
+        "id": "claude-sonnet-4-5@20250929",
+        "name": "Claude Sonnet 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-5-20250929"
+      },
+      "claude-opus-4-6@default": {
+        "id": "claude-opus-4-6@default",
+        "name": "Claude Opus 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-6"
+      },
+      "claude-opus-4@20250514": {
+        "id": "claude-opus-4@20250514",
+        "name": "Claude Opus 4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 75,
+          "cache_read": 1.5,
+          "cache_write": 18.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 32000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-20250514",
+        "status": "deprecated"
+      },
+      "claude-sonnet-5-5@default": {
+        "id": "claude-sonnet-5-5@default",
+        "name": "Claude Sonnet 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5-5"
+      },
+      "claude-opus-5-5@default": {
+        "id": "claude-opus-5-5@default",
+        "name": "Claude Opus 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.2,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5-5"
+      },
+      "claude-opus-5@default": {
+        "id": "claude-opus-5@default",
+        "name": "Claude Opus 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5"
+      },
+      "claude-sonnet-4-6@default": {
+        "id": "claude-sonnet-4-6@default",
+        "name": "Claude Sonnet 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-6"
+      },
+      "claude-haiku-4-5@20251001": {
+        "id": "claude-haiku-4-5@20251001",
+        "name": "Claude Haiku 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 5,
+          "cache_read": 0.1,
+          "cache_write": 1.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-haiku-4-5-20251001"
+      },
+      "claude-opus-4-1@20250805": {
+        "id": "claude-opus-4-1@20250805",
+        "name": "Claude Opus 4.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 75,
+          "cache_read": 1.5,
+          "cache_write": 18.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 32000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-1-20250805",
+        "status": "deprecated"
+      },
+      "claude-opus-4-5@20251101": {
+        "id": "claude-opus-4-5@20251101",
+        "name": "Claude Opus 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-5-20251101"
+      },
+      "claude-opus-4-7@default": {
+        "id": "claude-opus-4-7@default",
+        "name": "Claude Opus 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-7"
+      },
+      "claude-fable-5-1@default": {
+        "id": "claude-fable-5-1@default",
+        "name": "Claude Fable 5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 0.25,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-fable-5-1"
+      },
+      "claude-fable-5@default": {
+        "id": "claude-fable-5@default",
+        "name": "Claude Fable 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-fable-5"
+      },
+      "claude-sonnet-4@20250514": {
+        "id": "claude-sonnet-4@20250514",
+        "name": "Claude Sonnet 4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-20250514",
+        "status": "deprecated"
+      },
+      "claude-sonnet-5@default": {
+        "id": "claude-sonnet-5@default",
+        "name": "Claude Sonnet 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5"
+      }
+    }
+  },
+  "groq": {
+    "id": "groq",
+    "name": "Groq",
+    "env": ["GROQ_API_KEY"],
+    "npm": "@ai-sdk/groq",
+    "models": {
+      "whisper-large-v3": {
+        "id": "whisper-large-v3",
+        "name": "Whisper",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["audio"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "llama-3.3-70b-versatile": {
+        "id": "llama-3.3-70b-versatile",
+        "name": "Llama 3.3 70B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.59,
+          "output": 0.79
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "allam-2-7b": {
+        "id": "allam-2-7b",
+        "name": "ALLaM-2-7b",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 4096,
+          "output": 4096
+        },
+        "canonical_model_id": "sdaia/allam-2-7b"
+      },
+      "whisper-large-v3-turbo": {
+        "id": "whisper-large-v3-turbo",
+        "name": "Whisper Large V3 Turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["audio"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "llama-3.1-8b-instant": {
+        "id": "llama-3.1-8b-instant",
+        "name": "Llama 3.1 8B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.08
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        }
+      },
+      "groq/compound-mini": {
+        "id": "groq/compound-mini",
+        "name": "Compound Mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "groq/compound": {
+        "id": "groq/compound",
+        "name": "Compound",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "meta-llama/llama-prompt-guard-2-86m": {
+        "id": "meta-llama/llama-prompt-guard-2-86m",
+        "name": "Prompt Guard 2 86M",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.04,
+          "output": 0.04
+        },
+        "limit": {
+          "context": 512,
+          "output": 512
+        },
+        "status": "beta"
+      },
+      "meta-llama/llama-prompt-guard-2-22m": {
+        "id": "meta-llama/llama-prompt-guard-2-22m",
+        "name": "Llama Prompt Guard 2 22M",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.03,
+          "output": 0.03
+        },
+        "limit": {
+          "context": 512,
+          "output": 512
+        },
+        "status": "beta"
+      },
+      "canopylabs/orpheus-v1-english": {
+        "id": "canopylabs/orpheus-v1-english",
+        "name": "Canopy Labs Orpheus V1 English",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["audio"]
+        },
+        "limit": {
+          "context": 4000,
+          "output": 50000
+        },
+        "status": "beta"
+      },
+      "canopylabs/orpheus-arabic-saudi": {
+        "id": "canopylabs/orpheus-arabic-saudi",
+        "name": "Canopy Labs Orpheus Arabic Saudi",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["audio"]
+        },
+        "limit": {
+          "context": 4000,
+          "output": 50000
+        },
+        "status": "beta"
+      },
+      "qwen/qwen3.8-27b": {
+        "id": "qwen/qwen3.8-27b",
+        "name": "Qwen3.8 27B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "default", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.8,
+          "output": 4
+        },
+        "limit": {
+          "context": 131042,
+          "output": 16384
+        },
+        "canonical_model_id": "alibaba/qwen3.8-27b"
+      },
+      "qwen/qwen3.6-27b": {
+        "id": "qwen/qwen3.6-27b",
+        "name": "Qwen3.6 27B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "default"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        },
+        "canonical_model_id": "alibaba/qwen3.6-27b"
+      },
+      "openai/gpt-oss-20b": {
+        "id": "openai/gpt-oss-20b",
+        "name": "GPT OSS 20B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.075,
+          "output": 0.3,
+          "cache_read": 0.0375
+        },
+        "limit": {
+          "context": 131072,
+          "output": 65536
+        }
+      },
+      "openai/gpt-oss-safeguard-20b": {
+        "id": "openai/gpt-oss-safeguard-20b",
+        "name": "Safety GPT OSS 20B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.075,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 131072,
+          "output": 65536
+        },
+        "status": "beta"
+      },
+      "openai/gpt-oss-120b": {
+        "id": "openai/gpt-oss-120b",
+        "name": "GPT OSS 120B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 131072,
+          "output": 65536
+        },
+        "canonical_model_id": "openai/gpt-oss-120b"
+      }
+    }
+  },
+  "huggingface": {
+    "id": "huggingface",
+    "name": "Hugging Face",
+    "env": ["HF_TOKEN"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://router.huggingface.co/v1",
+    "models": {
+      "tencent/Hy3": {
+        "id": "tencent/Hy3",
+        "name": "Hy3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.58
+        },
+        "limit": {
+          "context": 262144,
+          "output": 128000
+        },
+        "canonical_model_id": "tencent/hy3"
+      },
+      "tencent/Hy4-preview": {
+        "id": "tencent/Hy4-preview",
+        "name": "Hy4 preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.834,
+          "output": 2.501
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "canonical_model_id": "tencent/hy4-preview"
+      },
+      "meta-llama/Llama-3.1-8B-Instruct": {
+        "id": "meta-llama/Llama-3.1-8B-Instruct",
+        "name": "Llama-3.1-8B-Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.06
+        },
+        "limit": {
+          "context": 131072,
+          "output": 4096
+        },
+        "canonical_model_id": "meta/llama-3.1-8b-instruct"
+      },
+      "meta-llama/Llama-3.3-70B-Instruct": {
+        "id": "meta-llama/Llama-3.3-70B-Instruct",
+        "name": "Llama-3.3-70B-Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.59,
+          "output": 0.79
+        },
+        "limit": {
+          "context": 131072,
+          "output": 4096
+        },
+        "canonical_model_id": "meta/llama-3.3-70b-instruct"
+      },
+      "XiaomiMiMo/MiMo-V2-Flash": {
+        "id": "XiaomiMiMo/MiMo-V2-Flash",
+        "name": "MiMo-V2-Flash",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 262144,
+          "output": 4096
+        }
+      },
+      "XiaomiMiMo/MiMo-V2.5-Pro": {
+        "id": "XiaomiMiMo/MiMo-V2.5-Pro",
+        "name": "MiMo-V2.5-Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 3
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.5-pro"
+      },
+      "XiaomiMiMo/MiMo-V2.5": {
+        "id": "XiaomiMiMo/MiMo-V2.5",
+        "name": "MiMo-V2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.5"
+      },
+      "thinkingmachines/Inkling-Small": {
+        "id": "thinkingmachines/Inkling-Small",
+        "name": "Inkling Small",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 524288,
+          "output": 1048576
+        },
+        "canonical_model_id": "thinkingmachines/inkling-small"
+      },
+      "thinkingmachines/Inkling": {
+        "id": "thinkingmachines/Inkling",
+        "name": "Inkling",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 4.05
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        },
+        "canonical_model_id": "thinkingmachines/inkling"
+      },
+      "google/gemma-3-27b-it": {
+        "id": "google/gemma-3-27b-it",
+        "name": "Gemma 3 27B IT",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.08,
+          "output": 0.16
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "canonical_model_id": "google/gemma-3-27b-it"
+      },
+      "google/gemma-3-12b-it": {
+        "id": "google/gemma-3-12b-it",
+        "name": "Gemma 3 12B IT",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.15
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "canonical_model_id": "google/gemma-3-12b-it"
+      },
+      "google/gemma-3-4b-it": {
+        "id": "google/gemma-3-4b-it",
+        "name": "Gemma 3 4B IT",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.1
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "canonical_model_id": "google/gemma-3-4b-it"
+      },
+      "google/gemma-4-31B-it": {
+        "id": "google/gemma-4-31B-it",
+        "name": "Gemma 4 31B IT",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.4
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemma-4-31b-it"
+      },
+      "google/gemma-4-26B-A4B-it": {
+        "id": "google/gemma-4-26B-A4B-it",
+        "name": "Gemma 4 26B A4B IT",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.13,
+          "output": 0.4
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemma-4-26b-a4b-it"
+      },
+      "Qwen/Qwen3-VL-235B-A22B-Instruct": {
+        "id": "Qwen/Qwen3-VL-235B-A22B-Instruct",
+        "name": "Qwen3 VL 235B A22B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.5
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "alibaba/qwen3-vl-235b-a22b-instruct"
+      },
+      "Qwen/Qwen3.8-27B": {
+        "id": "Qwen/Qwen3.8-27B",
+        "name": "Qwen3.8 27B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 3
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "alibaba/qwen3.8-27b"
+      },
+      "Qwen/Qwen3-Next-80B-A3B-Instruct": {
+        "id": "Qwen/Qwen3-Next-80B-A3B-Instruct",
+        "name": "Qwen3-Next-80B-A3B-Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1
+        },
+        "limit": {
+          "context": 262144,
+          "output": 66536
+        }
+      },
+      "Qwen/Qwen2.5-Coder-32B-Instruct": {
+        "id": "Qwen/Qwen2.5-Coder-32B-Instruct",
+        "name": "Qwen2.5-Coder-32B-Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.2
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        },
+        "canonical_model_id": "alibaba/qwen2.5-coder-32b-instruct"
+      },
+      "Qwen/Qwen3-Coder-Next": {
+        "id": "Qwen/Qwen3-Coder-Next",
+        "name": "Qwen3-Coder-Next",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.5
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "Qwen/Qwen3-VL-235B-A22B-Thinking": {
+        "id": "Qwen/Qwen3-VL-235B-A22B-Thinking",
+        "name": "Qwen3 VL 235B A22B Thinking",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.98,
+          "output": 3.95
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "alibaba/qwen3-vl-235b-a22b-thinking"
+      },
+      "Qwen/Qwen3.5-27B": {
+        "id": "Qwen/Qwen3.5-27B",
+        "name": "Qwen3.5 27B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.4
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.5-27b"
+      },
+      "Qwen/Qwen3-Next-80B-A3B-Thinking": {
+        "id": "Qwen/Qwen3-Next-80B-A3B-Thinking",
+        "name": "Qwen3-Next-80B-A3B-Thinking",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        }
+      },
+      "Qwen/Qwen3.6-35B-A3B": {
+        "id": "Qwen/Qwen3.6-35B-A3B",
+        "name": "Qwen3.6 35B-A3B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.95
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.6-35b-a3b"
+      },
+      "Qwen/Qwen3-235B-A22B-Thinking-2507": {
+        "id": "Qwen/Qwen3-235B-A22B-Thinking-2507",
+        "name": "Qwen3-235B-A22B-Thinking-2507",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 3
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        }
+      },
+      "Qwen/Qwen3-235B-A22B-Instruct-2507": {
+        "id": "Qwen/Qwen3-235B-A22B-Instruct-2507",
+        "name": "Qwen3 235B-A22B Instruct 2507",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.855,
+          "output": 2.565
+        },
+        "limit": {
+          "context": 262144,
+          "output": 16384
+        },
+        "canonical_model_id": "alibaba/qwen3-235b-a22b-instruct-2507"
+      },
+      "Qwen/Qwen3-235B-A22B": {
+        "id": "Qwen/Qwen3-235B-A22B",
+        "name": "Qwen3 235B-A22B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.8
+        },
+        "limit": {
+          "context": 40960,
+          "output": 16384
+        },
+        "canonical_model_id": "alibaba/qwen3-235b-a22b"
+      },
+      "Qwen/Qwen3-32B": {
+        "id": "Qwen/Qwen3-32B",
+        "name": "Qwen3 32B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.29,
+          "output": 0.59
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        },
+        "canonical_model_id": "alibaba/qwen3-32b"
+      },
+      "Qwen/Qwen3-Coder-30B-A3B-Instruct": {
+        "id": "Qwen/Qwen3-Coder-30B-A3B-Instruct",
+        "name": "Qwen3-Coder 30B-A3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.26
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3-coder-30b-a3b-instruct"
+      },
+      "Qwen/Qwen3-Embedding-8B": {
+        "id": "Qwen/Qwen3-Embedding-8B",
+        "name": "Qwen 3 Embedding 8B",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.01,
+          "output": 0
+        },
+        "limit": {
+          "context": 32000,
+          "output": 4096
+        }
+      },
+      "Qwen/Qwen3.5-35B-A3B": {
+        "id": "Qwen/Qwen3.5-35B-A3B",
+        "name": "Qwen3.5 35B-A3B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.5-35b-a3b"
+      },
+      "Qwen/Qwen3.5-122B-A10B": {
+        "id": "Qwen/Qwen3.5-122B-A10B",
+        "name": "Qwen3.5 122B-A10B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 3.2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.5-122b-a10b"
+      },
+      "Qwen/Qwen3.5-9B": {
+        "id": "Qwen/Qwen3.5-9B",
+        "name": "Qwen3.5 9B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.17,
+          "output": 0.25
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.5-9b"
+      },
+      "Qwen/Qwen3.5-397B-A17B": {
+        "id": "Qwen/Qwen3.5-397B-A17B",
+        "name": "Qwen3.5-397B-A17B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3.6
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "Qwen/Qwen3-Embedding-4B": {
+        "id": "Qwen/Qwen3-Embedding-4B",
+        "name": "Qwen 3 Embedding 4B",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.01,
+          "output": 0
+        },
+        "limit": {
+          "context": 32000,
+          "output": 2048
+        }
+      },
+      "Qwen/Qwen3.8-2.4T-A95B": {
+        "id": "Qwen/Qwen3.8-2.4T-A95B",
+        "name": "Qwen3.8 2.4T A95B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 6.25
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-2.4t-a95b"
+      },
+      "Qwen/Qwen3-30B-A3B": {
+        "id": "Qwen/Qwen3-30B-A3B",
+        "name": "Qwen3 30B A3B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.12,
+          "output": 0.5
+        },
+        "limit": {
+          "context": 40960,
+          "output": 16384
+        },
+        "canonical_model_id": "alibaba/qwen3-30b-a3b"
+      },
+      "Qwen/Qwen3-Coder-480B-A35B-Instruct": {
+        "id": "Qwen/Qwen3-Coder-480B-A35B-Instruct",
+        "name": "Qwen3-Coder-480B-A35B-Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 66536
+        }
+      },
+      "Qwen/Qwen3.6-27B": {
+        "id": "Qwen/Qwen3.6-27B",
+        "name": "Qwen3.6 27B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.47,
+          "output": 3.19
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.6-27b"
+      },
+      "deepseek-ai/DeepSeek-V3.1": {
+        "id": "deepseek-ai/DeepSeek-V3.1",
+        "name": "DeepSeek-V3.1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.27,
+          "output": 1
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        },
+        "canonical_model_id": "deepseek/deepseek-v3.1"
+      },
+      "deepseek-ai/DeepSeek-V4-Flash-0731": {
+        "id": "deepseek-ai/DeepSeek-V4-Flash-0731",
+        "name": "DeepSeek V4 Flash 0731",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-0731"
+      },
+      "deepseek-ai/DeepSeek-R1": {
+        "id": "deepseek-ai/DeepSeek-R1",
+        "name": "DeepSeek-R1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.7,
+          "output": 2.5
+        },
+        "limit": {
+          "context": 64000,
+          "output": 32768
+        },
+        "canonical_model_id": "deepseek/deepseek-r1"
+      },
+      "deepseek-ai/DeepSeek-V4-Pro-0813": {
+        "id": "deepseek-ai/DeepSeek-V4-Pro-0813",
+        "name": "DeepSeek V4 Pro 0813",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.32,
+          "output": 3.96
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro-0813"
+      },
+      "deepseek-ai/DeepSeek-V4.1-Flash": {
+        "id": "deepseek-ai/DeepSeek-V4.1-Flash",
+        "name": "DeepSeek V4.1 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4.1-flash"
+      },
+      "deepseek-ai/DeepSeek-V4-Flash": {
+        "id": "deepseek-ai/DeepSeek-V4-Flash",
+        "name": "DeepSeek V4 Flash",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash"
+      },
+      "deepseek-ai/DeepSeek-V4-Pro": {
+        "id": "deepseek-ai/DeepSeek-V4-Pro",
+        "name": "DeepSeek V4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.435,
+          "output": 0.87,
+          "cache_read": 0.003625
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 393216
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro"
+      },
+      "deepseek-ai/DeepSeek-V3.2": {
+        "id": "deepseek-ai/DeepSeek-V3.2",
+        "name": "DeepSeek-V3.2",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.28,
+          "output": 0.4
+        },
+        "limit": {
+          "context": 163840,
+          "output": 65536
+        }
+      },
+      "deepseek-ai/DeepSeek-R1-0528": {
+        "id": "deepseek-ai/DeepSeek-R1-0528",
+        "name": "DeepSeek-R1-0528",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 5
+        },
+        "limit": {
+          "context": 163840,
+          "output": 163840
+        }
+      },
+      "deepseek-ai/DeepSeek-V3": {
+        "id": "deepseek-ai/DeepSeek-V3",
+        "name": "DeepSeek-V3",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 1.3
+        },
+        "limit": {
+          "context": 64000,
+          "output": 8192
+        },
+        "canonical_model_id": "deepseek/deepseek-v3"
+      },
+      "deepseek-ai/DeepSeek-V3-0324": {
+        "id": "deepseek-ai/DeepSeek-V3-0324",
+        "name": "DeepSeek V3 0324",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.27,
+          "output": 1.12
+        },
+        "limit": {
+          "context": 163840,
+          "output": 163840
+        },
+        "canonical_model_id": "deepseek/deepseek-v3-0324"
+      },
+      "deepseek-ai/DeepSeek-V4-Flash-Vision-Exp": {
+        "id": "deepseek-ai/DeepSeek-V4-Flash-Vision-Exp",
+        "name": "DeepSeek V4 Flash Vision Exp",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.44,
+          "output": 1.32
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-vision-exp"
+      },
+      "stepfun-ai/Step-3.7-Flash": {
+        "id": "stepfun-ai/Step-3.7-Flash",
+        "name": "Step 3.7 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.15
+        },
+        "limit": {
+          "context": 262144,
+          "output": 256000
+        },
+        "canonical_model_id": "stepfun/step-3.7-flash"
+      },
+      "stepfun-ai/Step-3.5-Flash": {
+        "id": "stepfun-ai/Step-3.5-Flash",
+        "name": "Step 3.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 262144,
+          "output": 256000
+        },
+        "canonical_model_id": "stepfun/step-3.5-flash"
+      },
+      "MiniMaxAI/MiniMax-M3": {
+        "id": "MiniMaxAI/MiniMax-M3",
+        "name": "MiniMax-M3",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 524288,
+          "output": 512000
+        },
+        "canonical_model_id": "minimax/MiniMax-M3"
+      },
+      "MiniMaxAI/MiniMax-M2.1": {
+        "id": "MiniMaxAI/MiniMax-M2.1",
+        "name": "MiniMax-M2.1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "MiniMaxAI/MiniMax-M2.5": {
+        "id": "MiniMaxAI/MiniMax-M2.5",
+        "name": "MiniMax-M2.5",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "MiniMaxAI/MiniMax-M2.7": {
+        "id": "MiniMaxAI/MiniMax-M2.7",
+        "name": "MiniMax-M2.7",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "MiniMaxAI/MiniMax-M2": {
+        "id": "MiniMaxAI/MiniMax-M2",
+        "name": "MiniMax-M2",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "canonical_model_id": "minimax/MiniMax-M2"
+      },
+      "moonshotai/Kimi-K2.6": {
+        "id": "moonshotai/Kimi-K2.6",
+        "name": "Kimi-K2.6",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.16
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "moonshotai/Kimi-K3": {
+        "id": "moonshotai/Kimi-K3",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "moonshotai/Kimi-K2-Instruct": {
+        "id": "moonshotai/Kimi-K2-Instruct",
+        "name": "Kimi-K2-Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 3
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        }
+      },
+      "moonshotai/Kimi-K2.7-Code": {
+        "id": "moonshotai/Kimi-K2.7-Code",
+        "name": "Kimi K2.7 Code",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code"
+      },
+      "moonshotai/Kimi-K2.5": {
+        "id": "moonshotai/Kimi-K2.5",
+        "name": "Kimi-K2.5",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "moonshotai/Kimi-K2-Thinking": {
+        "id": "moonshotai/Kimi-K2-Thinking",
+        "name": "Kimi-K2-Thinking",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.5,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "moonshotai/Kimi-K2-Instruct-0905": {
+        "id": "moonshotai/Kimi-K2-Instruct-0905",
+        "name": "Kimi-K2-Instruct-0905",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 3
+        },
+        "limit": {
+          "context": 262144,
+          "output": 16384
+        }
+      },
+      "zai-org/GLM-4.6V-Flash": {
+        "id": "zai-org/GLM-4.6V-Flash",
+        "name": "GLM-4.6V-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 0.9
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "zhipuai/glm-4.6v-flash"
+      },
+      "zai-org/GLM-5.1": {
+        "id": "zai-org/GLM-5.1",
+        "name": "GLM-5.1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 3.2,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 202752,
+          "output": 131072
+        }
+      },
+      "zai-org/GLM-5.2": {
+        "id": "zai-org/GLM-5.2",
+        "name": "GLM-5.2",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "zai-org/GLM-4.5-Air": {
+        "id": "zai-org/GLM-4.5-Air",
+        "name": "GLM-4.5-Air",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.13,
+          "output": 0.85
+        },
+        "limit": {
+          "context": 131072,
+          "output": 98304
+        },
+        "canonical_model_id": "zhipuai/glm-4.5-air"
+      },
+      "zai-org/GLM-4.7": {
+        "id": "zai-org/GLM-4.7",
+        "name": "GLM-4.7",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.2,
+          "cache_read": 0.11
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "zai-org/GLM-5": {
+        "id": "zai-org/GLM-5",
+        "name": "GLM-5",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 3.2,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 202752,
+          "output": 131072
+        }
+      },
+      "zai-org/GLM-5.3-Flash": {
+        "id": "zai-org/GLM-5.3-Flash",
+        "name": "GLM-5.3-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.5
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "zai-org/GLM-4.5V": {
+        "id": "zai-org/GLM-4.5V",
+        "name": "GLM-4.5V",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 1.8
+        },
+        "limit": {
+          "context": 65536,
+          "output": 16384
+        },
+        "canonical_model_id": "zhipuai/glm-4.5v"
+      },
+      "zai-org/GLM-4.6": {
+        "id": "zai-org/GLM-4.6",
+        "name": "GLM-4.6",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.55,
+          "output": 2.2
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-4.6"
+      },
+      "zai-org/GLM-4.7-Flash": {
+        "id": "zai-org/GLM-4.7-Flash",
+        "name": "GLM-4.7-Flash",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 200000,
+          "output": 128000
+        }
+      },
+      "zai-org/GLM-5.3": {
+        "id": "zai-org/GLM-5.3",
+        "name": "GLM-5.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "zai-org/GLM-4.5": {
+        "id": "zai-org/GLM-4.5",
+        "name": "GLM-4.5",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.2
+        },
+        "limit": {
+          "context": 131072,
+          "output": 98304
+        },
+        "canonical_model_id": "zhipuai/glm-4.5"
+      },
+      "openai/gpt-oss-20b": {
+        "id": "openai/gpt-oss-20b",
+        "name": "GPT OSS 20B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.5
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "openai/gpt-oss-20b"
+      },
+      "openai/gpt-oss-120b": {
+        "id": "openai/gpt-oss-120b",
+        "name": "GPT OSS 120B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 0.69
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "openai/gpt-oss-120b"
+      }
+    }
+  },
+  "jiekou": {
+    "id": "jiekou",
+    "name": "Jiekou.AI",
+    "env": ["JIEKOU_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://api.jiekou.ai/openai",
+    "models": {
+      "gpt-5-chat-latest": {
+        "id": "gpt-5-chat-latest",
+        "name": "gpt-5-chat-latest",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.125,
+          "output": 9
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      }
+    }
+  },
+  "kilo": {
+    "id": "kilo",
+    "name": "Kilo Gateway",
+    "env": ["KILO_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://api.kilo.ai/api/gateway",
+    "models": {
+      "nex-agi/nex-n2.5-mini": {
+        "id": "nex-agi/nex-n2.5-mini",
+        "name": "Nex AGI: Nex-N2.5-Mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.025,
+          "output": 0.1,
+          "cache_read": 0.0025
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        }
+      },
+      "nex-agi/nex-n2.5-pro": {
+        "id": "nex-agi/nex-n2.5-pro",
+        "name": "Nex AGI: Nex-N2.5-Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.075,
+          "output": 0.25,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        }
+      },
+      "openrouter/auto": {
+        "id": "openrouter/auto",
+        "name": "Auto Router",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["audio", "image", "pdf", "text", "video"],
+          "output": ["image", "text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 32768
+        }
+      },
+      "~deepseek/deepseek-pro-latest": {
+        "id": "~deepseek/deepseek-pro-latest",
+        "name": "DeepSeek: DeepSeek Pro Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.123,
+          "output": 3.5,
+          "cache_read": 0.123
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 393216
+        }
+      },
+      "inclusionai/ling-3.0-flash-fin": {
+        "id": "inclusionai/ling-3.0-flash-fin",
+        "name": "inclusionAI: Ling 3.0 Flash Fin",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.075,
+          "output": 0.22,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        }
+      }
+    }
+  },
+  "kimi-code-plan-cn": {
+    "id": "kimi-code-plan-cn",
+    "name": "Kimi For Coding (kimi.com)",
+    "env": ["KIMI_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://api.kimi.com/coding/v1",
+    "models": {
+      "kimi-for-coding-highspeed": {
+        "id": "kimi-for-coding-highspeed",
+        "name": "Kimi For Coding HighSpeed",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code-highspeed"
+      },
+      "kimi-for-coding": {
+        "id": "kimi-for-coding",
+        "name": "kimi-for-coding",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 32768
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.8-preview"
+      },
+      "k3-256k": {
+        "id": "k3-256k",
+        "name": "Kimi K3-256K",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "k3": {
+        "id": "k3",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      }
+    }
+  },
+  "kimi-code-plan-global": {
+    "id": "kimi-code-plan-global",
+    "name": "Kimi For Coding (kimi.ai)",
+    "env": ["KIMI_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://api.kimi.ai/coding/v1",
+    "models": {
+      "kimi-for-coding-highspeed": {
+        "id": "kimi-for-coding-highspeed",
+        "name": "Kimi For Coding HighSpeed",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code-highspeed"
+      },
+      "kimi-for-coding": {
+        "id": "kimi-for-coding",
+        "name": "kimi-for-coding",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 32768
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.8-preview"
+      },
+      "k3-256k": {
+        "id": "k3-256k",
+        "name": "Kimi K3-256K",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "k3": {
+        "id": "k3",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      }
+    }
+  },
+  "llmgateway": {
+    "id": "llmgateway",
+    "name": "DevPass (LLM Gateway)",
+    "env": ["LLMGATEWAY_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://api.llmgateway.io/v1",
+    "models": {
+      "grok-4-1-fast-reasoning": {
+        "id": "grok-4-1-fast-reasoning",
+        "name": "Grok 4.1 Fast Reasoning",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.5,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 30000
+        }
+      },
+      "glm-4.6v": {
+        "id": "glm-4.6v",
+        "name": "GLM-4.6V",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 0.9,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "zhipuai/glm-4.6v"
+      },
+      "qwen-flash": {
+        "id": "qwen-flash",
+        "name": "Qwen Flash",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.4,
+          "cache_read": 0.01,
+          "cache_write": 0.0625
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 32768
+        },
+        "canonical_model_id": "alibaba/qwen-flash"
+      },
+      "gpt-5.4": {
+        "id": "gpt-5.4",
+        "name": "GPT-5.4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 15,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4"
+      },
+      "glm-4.5": {
+        "id": "glm-4.5",
+        "name": "GLM-4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.2,
+          "cache_read": 0.11,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 131000,
+          "output": 98304
+        },
+        "canonical_model_id": "zhipuai/glm-4.5"
+      },
+      "claude-haiku-4-5": {
+        "id": "claude-haiku-4-5",
+        "name": "Claude Haiku 4.5 (latest)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 5,
+          "cache_read": 0.1,
+          "cache_write": 1.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-haiku-4-5"
+      },
+      "gpt-5.4-pro": {
+        "id": "gpt-5.4-pro",
+        "name": "GPT-5.4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 30,
+          "output": 180
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4-pro"
+      },
+      "mimo-v2.6-pro": {
+        "id": "mimo-v2.6-pro",
+        "name": "MiMo-V2.6-Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.435,
+          "output": 0.87,
+          "cache_read": 0.0036
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.6-pro"
+      },
+      "gemma-4-31b-it": {
+        "id": "gemma-4-31b-it",
+        "name": "Gemma 4 31B IT",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.25,
+          "cache_read": 0.01
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemma-4-31b-it"
+      },
+      "grok-4-5": {
+        "id": "grok-4-5",
+        "name": "Grok 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        }
+      },
+      "gpt-3.5-turbo": {
+        "id": "gpt-3.5-turbo",
+        "name": "GPT-3.5-turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.5,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 16385,
+          "output": 4096
+        },
+        "canonical_model_id": "openai/gpt-3.5-turbo"
+      },
+      "grok-4-1-fast-non-reasoning": {
+        "id": "grok-4-1-fast-non-reasoning",
+        "name": "Grok 4.1 Fast Non-Reasoning",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.5,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 2000000
+        }
+      },
+      "qwen3-vl-235b-a22b-instruct": {
+        "id": "qwen3-vl-235b-a22b-instruct",
+        "name": "Qwen3 VL 235B A22B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.88,
+          "cache_read": 0.11
+        },
+        "limit": {
+          "context": 262144,
+          "output": 8192
+        }
+      },
+      "seed-1-6-flash-250715": {
+        "id": "seed-1-6-flash-250715",
+        "name": "Seed 1.6 Flash (250715)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.3,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 256000,
+          "output": 8192
+        }
+      },
+      "qwen3.7-max": {
+        "id": "qwen3.7-max",
+        "name": "Qwen3.7 Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 3.75,
+          "cache_read": 0.25,
+          "cache_write": 3.125
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.7-max"
+      },
+      "muse-spark-1.3": {
+        "id": "muse-spark-1.3",
+        "name": "Muse Spark 1.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 4.25,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "meta/muse-spark-1.3"
+      },
+      "Qwen3.8-27B": {
+        "id": "Qwen3.8-27B",
+        "name": "Qwen3.8 27B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.08,
+          "output": 0.35,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 32768,
+          "output": 32768
+        }
+      },
+      "gpt-4o-transcribe": {
+        "id": "gpt-4o-transcribe",
+        "name": "GPT-4o Transcribe",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10
+        },
+        "limit": {
+          "context": 16000,
+          "output": 16000
+        }
+      },
+      "mimo-v2.5": {
+        "id": "mimo-v2.5",
+        "name": "MiMo-V2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.0028
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.5"
+      },
+      "gpt-5.5-pro": {
+        "id": "gpt-5.5-pro",
+        "name": "GPT-5.5 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 30,
+          "output": 180
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.5-pro"
+      },
+      "gpt-5.4-nano": {
+        "id": "gpt-5.4-nano",
+        "name": "GPT-5.4 nano",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.25,
+          "cache_read": 0.02
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4-nano"
+      },
+      "mistral-large-latest": {
+        "id": "mistral-large-latest",
+        "name": "Mistral Large (latest)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 12
+        },
+        "limit": {
+          "context": 128000,
+          "output": 262144
+        },
+        "canonical_model_id": "mistral/mistral-large-latest"
+      },
+      "seed-2-0-code-preview-260328": {
+        "id": "seed-2-0-code-preview-260328",
+        "name": "Seed 2.0 Code Preview (260328)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "qwen3-vl-235b-a22b-thinking": {
+        "id": "qwen3-vl-235b-a22b-thinking",
+        "name": "Qwen3 VL 235B A22B Thinking",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.98,
+          "output": 3.95
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen3.8-2.4t-a95b": {
+        "id": "qwen3.8-2.4t-a95b",
+        "name": "Qwen3.8 2.4T A95B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 1010000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-2.4t-a95b"
+      },
+      "gpt-5.2-codex": {
+        "id": "gpt-5.2-codex",
+        "name": "GPT-5.2 Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.2-codex"
+      },
+      "gpt-5.1-codex": {
+        "id": "gpt-5.1-codex",
+        "name": "GPT-5.1 Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.1-codex"
+      },
+      "qwen-coder-plus": {
+        "id": "qwen-coder-plus",
+        "name": "Qwen Coder Plus",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.502,
+          "output": 1.004
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "glm-5v-turbo": {
+        "id": "glm-5v-turbo",
+        "name": "GLM-5V-Turbo",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.2,
+          "output": 4,
+          "cache_read": 0.24
+        },
+        "limit": {
+          "context": 200000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5v-turbo"
+      },
+      "gpt-4o": {
+        "id": "gpt-4o",
+        "name": "GPT-4o",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "openai/gpt-4o"
+      },
+      "qwen3-vl-plus": {
+        "id": "qwen3-vl-plus",
+        "name": "Qwen3-VL Plus",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.6,
+          "cache_read": 0.04,
+          "cache_write": 0.25
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "alibaba/qwen3-vl-plus"
+      },
+      "glm-5.3-flash": {
+        "id": "glm-5.3-flash",
+        "name": "GLM-5.3-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.088,
+          "output": 0.25,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "fugu-max": {
+        "id": "fugu-max",
+        "name": "Fugu Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 1000000
+        }
+      },
+      "ministral-8b-2512": {
+        "id": "ministral-8b-2512",
+        "name": "Ministral 8B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.15
+        },
+        "limit": {
+          "context": 262144,
+          "output": 8192
+        }
+      },
+      "qwen3.5-27b": {
+        "id": "qwen3.5-27b",
+        "name": "Qwen3.5 27B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.4
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.5-27b"
+      },
+      "glm-4.6": {
+        "id": "glm-4.6",
+        "name": "GLM-4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.55,
+          "output": 2.2,
+          "cache_read": 0.11,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-4.6"
+      },
+      "glm-5.2-fast": {
+        "id": "glm-5.2-fast",
+        "name": "GLM-5.2",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.2,
+          "output": 6.5,
+          "cache_read": 0.45
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "muse-glimmer-30b": {
+        "id": "muse-glimmer-30b",
+        "name": "Muse Glimmer 30B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.04
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "canonical_model_id": "meta/muse-glimmer-30b"
+      },
+      "grok-build-0-1": {
+        "id": "grok-build-0-1",
+        "name": "Grok Build 0.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 2,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        },
+        "canonical_model_id": "xai/grok-build-0.1"
+      },
+      "qwen3-235b-a22b-instruct-2507": {
+        "id": "qwen3-235b-a22b-instruct-2507",
+        "name": "Qwen3 235B A22B Instruct (2507)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.09,
+          "output": 0.58
+        },
+        "limit": {
+          "context": 262144,
+          "output": 8192
+        }
+      },
+      "qwen-max": {
+        "id": "qwen-max",
+        "name": "Qwen Max",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.6,
+          "output": 6.4
+        },
+        "limit": {
+          "context": 32768,
+          "output": 8192
+        },
+        "canonical_model_id": "alibaba/qwen-max"
+      },
+      "qwen3-next-80b-a3b-thinking": {
+        "id": "qwen3-next-80b-a3b-thinking",
+        "name": "Qwen3-Next 80B-A3B (Thinking)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "alibaba/qwen3-next-80b-a3b-thinking"
+      },
+      "qwen3.8-max": {
+        "id": "qwen3.8-max",
+        "name": "Qwen3.8 Max Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.25,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 1000000
+        },
+        "canonical_model_id": "alibaba/qwen3.8-max-preview"
+      },
+      "kimi-k3": {
+        "id": "kimi-k3",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "qwen3-coder-next": {
+        "id": "qwen3-coder-next",
+        "name": "Qwen3 Coder Next",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.108,
+          "output": 0.675,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "glm-4.5-x": {
+        "id": "glm-4.5-x",
+        "name": "GLM-4.5 X",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.2,
+          "output": 8.9,
+          "cache_read": 0.45
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "status": "beta"
+      },
+      "grok-4": {
+        "id": "grok-4",
+        "name": "Grok 4",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.75
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        }
+      },
+      "gpt-5-mini": {
+        "id": "gpt-5-mini",
+        "name": "GPT-5 Mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5-mini"
+      },
+      "llama-4-maverick-17b-instruct": {
+        "id": "llama-4-maverick-17b-instruct",
+        "name": "Llama 4 Maverick 17B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.27,
+          "output": 0.85
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 2048
+        }
+      },
+      "gpt-5.2-pro": {
+        "id": "gpt-5.2-pro",
+        "name": "GPT-5.2 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 21,
+          "output": 168
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.2-pro"
+      },
+      "o4-mini": {
+        "id": "o4-mini",
+        "name": "o4-mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 4.4,
+          "cache_read": 0.275
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "canonical_model_id": "openai/o4-mini"
+      },
+      "o3-mini": {
+        "id": "o3-mini",
+        "name": "o3-mini",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 4.4,
+          "cache_read": 0.55
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "canonical_model_id": "openai/o3-mini"
+      },
+      "glm-5": {
+        "id": "glm-5",
+        "name": "GLM-5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.72,
+          "output": 2.3,
+          "cache_read": 0.144,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 203000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5"
+      },
+      "fugu-ultra-v2.0": {
+        "id": "fugu-ultra-v2.0",
+        "name": "Fugu Ultra v2.0",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 1000000
+        }
+      },
+      "gpt-4": {
+        "id": "gpt-4",
+        "name": "GPT-4",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 30,
+          "output": 60
+        },
+        "limit": {
+          "context": 8192,
+          "output": 8192
+        },
+        "canonical_model_id": "openai/gpt-4"
+      },
+      "deepseek-v4.1-flash": {
+        "id": "deepseek-v4.1-flash",
+        "name": "DeepSeek V4.1 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.003
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4.1-flash"
+      },
+      "gpt-5.3-codex": {
+        "id": "gpt-5.3-codex",
+        "name": "GPT-5.3 Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.3-codex"
+      },
+      "gpt-4.1-nano": {
+        "id": "gpt-4.1-nano",
+        "name": "GPT-4.1 nano",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.4,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 32768
+        },
+        "canonical_model_id": "openai/gpt-4.1-nano"
+      },
+      "minimax-m2.5": {
+        "id": "minimax-m2.5",
+        "name": "MiniMax-M2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.03,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 228700,
+          "output": 131072
+        },
+        "canonical_model_id": "minimax/MiniMax-M2.5"
+      },
+      "kimi-k3-fast": {
+        "id": "kimi-k3-fast",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4.5,
+          "output": 22.5,
+          "cache_read": 0.45
+        },
+        "limit": {
+          "context": 1040384,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "qwen3-32b": {
+        "id": "qwen3-32b",
+        "name": "Qwen3 32B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.36,
+          "output": 0.87
+        },
+        "limit": {
+          "context": 40960,
+          "output": 16384
+        },
+        "canonical_model_id": "alibaba/qwen3-32b"
+      },
+      "muse-spark-1.1": {
+        "id": "muse-spark-1.1",
+        "name": "Muse Spark 1.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 4.25,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "meta/muse-spark-1.1"
+      },
+      "gpt-5-nano": {
+        "id": "gpt-5-nano",
+        "name": "GPT-5 Nano",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.4,
+          "cache_read": 0.005
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5-nano"
+      },
+      "qwen-plus": {
+        "id": "qwen-plus",
+        "name": "Qwen Plus",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 1.2,
+          "cache_read": 0.08,
+          "cache_write": 0.5
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "alibaba/qwen-plus"
+      },
+      "kimi-k2.7-code-highspeed": {
+        "id": "kimi-k2.7-code-highspeed",
+        "name": "Kimi K2.7 Code Highspeed",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.9,
+          "output": 8,
+          "cache_read": 0.38
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code-highspeed"
+      },
+      "qwen3.7-flash": {
+        "id": "qwen3.7-flash",
+        "name": "Qwen3.7 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.03,
+          "output": 0.13,
+          "cache_read": 0.006,
+          "cache_write": 0.0375
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 1000000
+        }
+      },
+      "kimi-k2.6": {
+        "id": "kimi-k2.6",
+        "name": "Kimi K2.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3.05,
+          "cache_read": 0.13
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.6"
+      },
+      "minimax-m2.1-lightning": {
+        "id": "minimax-m2.1-lightning",
+        "name": "MiniMax M2.1 Lightning",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.12,
+          "output": 0.48
+        },
+        "limit": {
+          "context": 196608,
+          "output": 131072
+        }
+      },
+      "claude-sonnet-4-5": {
+        "id": "claude-sonnet-4-5",
+        "name": "Claude Sonnet 4.5 (latest)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024,
+            "max": 63999
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-5"
+      },
+      "qwen3-max": {
+        "id": "qwen3-max",
+        "name": "Qwen3 Max",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.845,
+          "output": 3.38,
+          "cache_read": 0.6,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3-max"
+      },
+      "claude-opus-5-5": {
+        "id": "claude-opus-5-5",
+        "name": "Claude Opus 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.2,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5-5"
+      },
+      "glm-4.5-airx": {
+        "id": "glm-4.5-airx",
+        "name": "GLM-4.5 AirX",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 4.5,
+          "cache_read": 0.22
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        }
+      },
+      "glm-4.5v": {
+        "id": "glm-4.5v",
+        "name": "GLM-4.5V",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 1.8,
+          "cache_read": 0.11
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "zhipuai/glm-4.5v"
+      },
+      "claude-fable-5-1": {
+        "id": "claude-fable-5-1",
+        "name": "Claude Fable 5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 0.25,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-fable-5-1"
+      },
+      "devstral-2512": {
+        "id": "devstral-2512",
+        "name": "Devstral 2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "mistral/devstral-2512",
+        "status": "deprecated"
+      },
+      "llama-4-scout-17b-instruct": {
+        "id": "llama-4-scout-17b-instruct",
+        "name": "Llama 4 Scout 17B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.18,
+          "output": 0.59
+        },
+        "limit": {
+          "context": 131072,
+          "output": 2048
+        }
+      },
+      "gemini-3.6-flash": {
+        "id": "gemini-3.6-flash",
+        "name": "Gemini 3.6 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 3.75,
+          "cache_read": 0.075,
+          "cache_write": 0.08333
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.6-flash"
+      },
+      "qwen3-235b-a22b-fp8": {
+        "id": "qwen3-235b-a22b-fp8",
+        "name": "Qwen3 235B A22B FP8",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.8
+        },
+        "limit": {
+          "context": 40960,
+          "output": 8192
+        }
+      },
+      "o1": {
+        "id": "o1",
+        "name": "o1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 60,
+          "cache_read": 7.5
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "canonical_model_id": "openai/o1"
+      },
+      "glm-4-32b-0414-128k": {
+        "id": "glm-4-32b-0414-128k",
+        "name": "GLM-4 32B (0414-128k)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.1
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        }
+      },
+      "qwen3-coder-480b-a35b-instruct": {
+        "id": "qwen3-coder-480b-a35b-instruct",
+        "name": "Qwen3-Coder 480B-A35B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.38,
+          "output": 1.55
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3-coder-480b-a35b-instruct"
+      },
+      "qwen3-coder-30b-a3b-instruct": {
+        "id": "qwen3-coder-30b-a3b-instruct",
+        "name": "Qwen3-Coder 30B-A3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.27
+        },
+        "limit": {
+          "context": 262000,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3-coder-30b-a3b-instruct"
+      },
+      "mistral-medium-3-5": {
+        "id": "mistral-medium-3-5",
+        "name": "Mistral Medium 3.5",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 7.5
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "ling-3.0-flash": {
+        "id": "ling-3.0-flash",
+        "name": "InclusionAI Ling 3.0 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.18,
+          "cache_read": 0.012
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "kimi-k2-thinking": {
+        "id": "kimi-k2-thinking",
+        "name": "Kimi K2 Thinking",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.5,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "moonshotai/kimi-k2-thinking"
+      },
+      "claude-opus-4-1-20250805": {
+        "id": "claude-opus-4-1-20250805",
+        "name": "Claude Opus 4.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024,
+            "max": 31999
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 75,
+          "cache_read": 1.5,
+          "cache_write": 18.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 32000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-1-20250805"
+      },
+      "gpt-5-pro": {
+        "id": "gpt-5-pro",
+        "name": "GPT-5 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 120
+        },
+        "limit": {
+          "context": 400000,
+          "output": 272000
+        },
+        "canonical_model_id": "openai/gpt-5-pro"
+      },
+      "qwen3-vl-30b-a3b-instruct": {
+        "id": "qwen3-vl-30b-a3b-instruct",
+        "name": "Qwen3 VL 30B A3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6
+        },
+        "limit": {
+          "context": 262144,
+          "output": 8192
+        }
+      },
+      "gpt-6.1-sol": {
+        "id": "gpt-6.1-sol",
+        "name": "GPT-6.1 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.1,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6.1-sol"
+      },
+      "seed-1-6-250915": {
+        "id": "seed-1-6-250915",
+        "name": "Seed 1.6 (250915)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 256000,
+          "output": 8192
+        }
+      },
+      "seed-2-0-mini-260428": {
+        "id": "seed-2-0-mini-260428",
+        "name": "Seed 2.0 Mini (260428)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.4,
+          "cache_read": 0.02
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "gemma-4-26b-a4b-it": {
+        "id": "gemma-4-26b-a4b-it",
+        "name": "Gemma 4 26B A4B IT",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.34
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemma-4-26b-a4b-it"
+      },
+      "claude-opus-4-5-20251101": {
+        "id": "claude-opus-4-5-20251101",
+        "name": "Claude Opus 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024,
+            "max": 31999
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-5-20251101"
+      },
+      "gemini-3.5-flash-lite": {
+        "id": "gemini-3.5-flash-lite",
+        "name": "Gemini 3.5 Flash Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.03,
+          "cache_write": 0.08333
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.5-flash-lite"
+      },
+      "llama-3-70b-instruct": {
+        "id": "llama-3-70b-instruct",
+        "name": "Llama 3 70B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.51,
+          "output": 0.74
+        },
+        "limit": {
+          "context": 8192,
+          "output": 8000
+        }
+      },
+      "qwen3-vl-flash": {
+        "id": "qwen3-vl-flash",
+        "name": "Qwen3 VL Flash",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.4,
+          "cache_read": 0.01
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32000
+        }
+      },
+      "seed-2-0-pro-260328": {
+        "id": "seed-2-0-pro-260328",
+        "name": "Seed 2.0 Pro (260328)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "ling-3.0-flash-vl": {
+        "id": "ling-3.0-flash-vl",
+        "name": "Ling 3.0 Flash VL",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.18,
+          "cache_read": 0.012
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        }
+      },
+      "qwen3-235b-a22b-thinking-2507": {
+        "id": "qwen3-235b-a22b-thinking-2507",
+        "name": "Qwen3 235B A22B Thinking (2507)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 3
+        },
+        "limit": {
+          "context": 262000,
+          "output": 8192
+        }
+      },
+      "gpt-6-astra": {
+        "id": "gpt-6-astra",
+        "name": "GPT-6 Astra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 1050000
+        }
+      },
+      "minimax-text-01": {
+        "id": "minimax-text-01",
+        "name": "MiniMax Text 01",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.1
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        }
+      },
+      "gemini-3.1-pro-preview": {
+        "id": "gemini-3.1-pro-preview",
+        "name": "Gemini 3.1 Pro Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.1-pro-preview"
+      },
+      "glm-4.6v-flashx": {
+        "id": "glm-4.6v-flashx",
+        "name": "GLM-4.6V FlashX",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.04,
+          "output": 0.4,
+          "cache_read": 0.004
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16000
+        }
+      },
+      "qwen3.5-122b-a10b": {
+        "id": "qwen3.5-122b-a10b",
+        "name": "Qwen3.5 122B-A10B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 3.2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.5-122b-a10b"
+      },
+      "grok-4-20-beta-0309-non-reasoning": {
+        "id": "grok-4-20-beta-0309-non-reasoning",
+        "name": "Grok 4.20 (Non-Reasoning)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 30000
+        },
+        "canonical_model_id": "xai/grok-4.20-0309-non-reasoning"
+      },
+      "kimi-k2.5": {
+        "id": "kimi-k2.5",
+        "name": "Kimi K2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.405,
+          "output": 1.98,
+          "cache_read": 0.225
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.5"
+      },
+      "gpt-5.1": {
+        "id": "gpt-5.1",
+        "name": "GPT-5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.1"
+      },
+      "claude-opus-5": {
+        "id": "claude-opus-5",
+        "name": "Claude Opus 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5"
+      },
+      "llama-3.3-70b-instruct": {
+        "id": "llama-3.3-70b-instruct",
+        "name": "Llama-3.3-70B-Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.135,
+          "output": 0.4
+        },
+        "limit": {
+          "context": 131072,
+          "output": 4096
+        },
+        "canonical_model_id": "meta/llama-3.3-70b-instruct"
+      },
+      "gpt-4o-mini": {
+        "id": "gpt-4o-mini",
+        "name": "GPT-4o mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "openai/gpt-4o-mini"
+      },
+      "qwen3.6-35b-a3b": {
+        "id": "qwen3.6-35b-a3b",
+        "name": "Qwen3.6 35B-A3B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.248,
+          "output": 1.485
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.6-35b-a3b"
+      },
+      "qwen3-next-80b-a3b-instruct": {
+        "id": "qwen3-next-80b-a3b-instruct",
+        "name": "Qwen3-Next 80B-A3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "alibaba/qwen3-next-80b-a3b-instruct"
+      },
+      "granite-4.2-8b": {
+        "id": "granite-4.2-8b",
+        "name": "Granite 4.2 8B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.25,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        }
+      },
+      "fugu-ultra": {
+        "id": "fugu-ultra",
+        "name": "Fugu Ultra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 1000000
+        }
+      },
+      "gpt-oss-20b": {
+        "id": "gpt-oss-20b",
+        "name": "GPT OSS 20B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.04,
+          "output": 0.19,
+          "cache_read": 0.01
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32766
+        }
+      },
+      "minimax-m2.7": {
+        "id": "minimax-m2.7",
+        "name": "MiniMax-M2.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.08,
+          "output": 0.32,
+          "cache_read": 0.017,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "canonical_model_id": "minimax/MiniMax-M2.7"
+      },
+      "gemini-3.5-flash": {
+        "id": "gemini-3.5-flash",
+        "name": "Gemini 3.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 9,
+          "cache_read": 0.15,
+          "cache_write": 0.08333
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.5-flash"
+      },
+      "gemini-2.5-pro": {
+        "id": "gemini-2.5-pro",
+        "name": "Gemini 2.5 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 128,
+            "max": 32768
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-2.5-pro"
+      },
+      "qwen3.6-flash": {
+        "id": "qwen3.6-flash",
+        "name": "Qwen3.6 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1.5,
+          "cache_read": 0.05,
+          "cache_write": 0.3125
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.6-flash"
+      },
+      "gemini-2.5-flash": {
+        "id": "gemini-2.5-flash",
+        "name": "Gemini 2.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1,
+            "max": 24576
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-2.5-flash"
+      },
+      "qwen3-coder-flash": {
+        "id": "qwen3-coder-flash",
+        "name": "Qwen3 Coder Flash",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.5,
+          "cache_read": 0.06,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3-coder-flash"
+      },
+      "nemotron-3-ultra-550b": {
+        "id": "nemotron-3-ultra-550b",
+        "name": "Nemotron 3 Ultra 550B A55B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 2.2,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 128000
+        },
+        "canonical_model_id": "nvidia/nemotron-3-ultra-550b-a55b"
+      },
+      "llama-3.2-11b-instruct": {
+        "id": "llama-3.2-11b-instruct",
+        "name": "Llama 3.2 11B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.33
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "claude-fable-5": {
+        "id": "claude-fable-5",
+        "name": "Claude Fable 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-fable-5"
+      },
+      "mimo-v2.5-pro": {
+        "id": "mimo-v2.5-pro",
+        "name": "MiMo-V2.5-Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.435,
+          "output": 0.87,
+          "cache_read": 0.0036
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.5-pro"
+      },
+      "qwen3-coder-plus": {
+        "id": "qwen3-coder-plus",
+        "name": "Qwen3 Coder Plus",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 5,
+          "cache_read": 0.2,
+          "cache_write": 1.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3-coder-plus"
+      },
+      "glm-4.7-flash": {
+        "id": "glm-4.7-flash",
+        "name": "GLM-4.7-Flash",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.4,
+          "cache_read": 0.01,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 200000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-4.7-flash"
+      },
+      "qwen3.5-9b": {
+        "id": "qwen3.5-9b",
+        "name": "Qwen3.5 9B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.15
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.5-9b"
+      },
+      "inkling": {
+        "id": "inkling",
+        "name": "Inkling",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4.05,
+          "cache_read": 0.16
+        },
+        "limit": {
+          "context": 524288,
+          "output": 1048576
+        },
+        "canonical_model_id": "thinkingmachines/inkling"
+      },
+      "muse-spark-1.2": {
+        "id": "muse-spark-1.2",
+        "name": "Muse Spark 1.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 4.25,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "meta/muse-spark-1.2"
+      },
+      "mimo-v2.6-flash": {
+        "id": "mimo-v2.6-flash",
+        "name": "MiMo-V2.6-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.0028
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.6-flash"
+      },
+      "gpt-5.4-mini": {
+        "id": "gpt-5.4-mini",
+        "name": "GPT-5.4 mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 4.5,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4-mini"
+      },
+      "seed-1-8-251228": {
+        "id": "seed-1-8-251228",
+        "name": "Seed 1.8 (251228)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 256000,
+          "output": 8192
+        }
+      },
+      "glm-4.7": {
+        "id": "glm-4.7",
+        "name": "GLM-4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.38,
+          "output": 1.98,
+          "cache_read": 0.19,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-4.7"
+      },
+      "minimax-m3": {
+        "id": "minimax-m3",
+        "name": "MiniMax-M3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 512000
+        },
+        "canonical_model_id": "minimax/MiniMax-M3"
+      },
+      "gpt-5.6-luna": {
+        "id": "gpt-5.6-luna",
+        "name": "GPT-5.6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.2,
+          "cache_read": 0.02,
+          "cache_write": 0.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-luna"
+      },
+      "qwen3.8-flash": {
+        "id": "qwen3.8-flash",
+        "name": "Qwen3.8 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.47,
+          "cache_read": 0.016,
+          "cache_write": 0.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-flash"
+      },
+      "mistral-small-2603": {
+        "id": "mistral-small-2603",
+        "name": "Mistral Small 4",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6
+        },
+        "limit": {
+          "context": 262144,
+          "output": 256000
+        },
+        "canonical_model_id": "mistral/mistral-small-2603"
+      },
+      "gpt-5.2": {
+        "id": "gpt-5.2",
+        "name": "GPT-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.2"
+      },
+      "claude-opus-4-8": {
+        "id": "claude-opus-4-8",
+        "name": "Claude Opus 4.8",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-8"
+      },
+      "seed-1-6-250615": {
+        "id": "seed-1-6-250615",
+        "name": "Seed 1.6 (250615)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 256000,
+          "output": 8192
+        }
+      },
+      "gpt-5.5": {
+        "id": "gpt-5.5",
+        "name": "GPT-5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.5"
+      },
+      "claude-sonnet-4-5-20250929": {
+        "id": "claude-sonnet-4-5-20250929",
+        "name": "Claude Sonnet 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024,
+            "max": 63999
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-5-20250929"
+      },
+      "qwen35-397b-a17b": {
+        "id": "qwen35-397b-a17b",
+        "name": "Qwen3.5 397B-A17B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3.6
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.5-397b-a17b"
+      },
+      "gpt-4.1": {
+        "id": "gpt-4.1",
+        "name": "GPT-4.1",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 8,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 32768
+        },
+        "canonical_model_id": "openai/gpt-4.1"
+      },
+      "claude-sonnet-5": {
+        "id": "claude-sonnet-5",
+        "name": "Claude Sonnet 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 1000000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5"
+      },
+      "qwen3.5-35b-a3b": {
+        "id": "qwen3.5-35b-a3b",
+        "name": "Qwen3.5 35B-A3B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.5-35b-a3b"
+      },
+      "qwen3.6-max-preview": {
+        "id": "qwen3.6-max-preview",
+        "name": "Qwen3.6 Max Preview",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.3,
+          "output": 7.8,
+          "cache_read": 0.13,
+          "cache_write": 1.625
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.6-max-preview"
+      },
+      "claude-opus-4-6": {
+        "id": "claude-opus-4-6",
+        "name": "Claude Opus 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-6"
+      },
+      "gemini-3.7-flash": {
+        "id": "gemini-3.7-flash",
+        "name": "Gemini 3.7 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 3.75,
+          "cache_read": 0.075,
+          "cache_write": 0.08333
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.7-flash"
+      },
+      "glm-5.2": {
+        "id": "glm-5.2",
+        "name": "GLM-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.8,
+          "output": 2.55,
+          "cache_read": 0.16,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "ernie-4.5-vl-424b-a47b": {
+        "id": "ernie-4.5-vl-424b-a47b",
+        "name": "ERNIE 4.5 VL 424B A47B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.42,
+          "output": 1.25
+        },
+        "limit": {
+          "context": 123000,
+          "output": 123000
+        }
+      },
+      "hy3": {
+        "id": "hy3",
+        "name": "Hy3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.132,
+          "output": 0.528,
+          "cache_read": 0.033
+        },
+        "limit": {
+          "context": 262144,
+          "output": 128000
+        },
+        "canonical_model_id": "tencent/hy3"
+      },
+      "seed-2-0-lite-260428": {
+        "id": "seed-2-0-lite-260428",
+        "name": "Seed 2.0 Lite (260428)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "kimi-k2": {
+        "id": "kimi-k2",
+        "name": "Kimi K2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.57,
+          "output": 2.3,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 256000,
+          "output": 16384
+        }
+      },
+      "qwen-omni-turbo": {
+        "id": "qwen-omni-turbo",
+        "name": "Qwen-Omni Turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.8
+        },
+        "limit": {
+          "context": 32768,
+          "output": 2048
+        },
+        "canonical_model_id": "alibaba/qwen-omni-turbo"
+      },
+      "hy-mt2-plus": {
+        "id": "hy-mt2-plus",
+        "name": "Hy-MT2 Plus",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.074,
+          "output": 0.295
+        },
+        "limit": {
+          "context": 8192,
+          "output": 8192
+        }
+      },
+      "grok-4-3": {
+        "id": "grok-4-3",
+        "name": "Grok 4.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 30000
+        },
+        "canonical_model_id": "xai/grok-4.3"
+      },
+      "glm-5.1": {
+        "id": "glm-5.1",
+        "name": "GLM-5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.931,
+          "output": 2.93,
+          "cache_read": 0.173,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.1"
+      },
+      "grok-4-20-non-reasoning": {
+        "id": "grok-4-20-non-reasoning",
+        "name": "Grok 4.20 (Non-Reasoning)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 30000
+        },
+        "canonical_model_id": "xai/grok-4.20-0309-non-reasoning"
+      },
+      "gemini-3-flash-preview": {
+        "id": "gemini-3-flash-preview",
+        "name": "Gemini 3 Flash Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3-flash-preview"
+      },
+      "grok-4-20-beta-0309-reasoning": {
+        "id": "grok-4-20-beta-0309-reasoning",
+        "name": "Grok 4.20 (Reasoning)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 30000
+        },
+        "canonical_model_id": "xai/grok-4.20-0309-reasoning"
+      },
+      "minimax-m2.7-highspeed": {
+        "id": "minimax-m2.7-highspeed",
+        "name": "MiniMax-M2.7-highspeed",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.4,
+          "cache_read": 0.06,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "canonical_model_id": "minimax/MiniMax-M2.7-highspeed"
+      },
+      "claude-haiku-4-5-20251001": {
+        "id": "claude-haiku-4-5-20251001",
+        "name": "Claude Haiku 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 5,
+          "cache_read": 0.1,
+          "cache_write": 1.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-haiku-4-5-20251001"
+      },
+      "glm-4.7-flashx": {
+        "id": "glm-4.7-flashx",
+        "name": "GLM-4.7-FlashX",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.4,
+          "cache_read": 0.01,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 200000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-4.7-flashx"
+      },
+      "muse-spark-1.2-contributor": {
+        "id": "muse-spark-1.2-contributor",
+        "name": "Muse Spark 1.2 Contributor",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.2,
+          "cache_read": 0.002
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        }
+      },
+      "sonar": {
+        "id": "sonar",
+        "name": "Sonar",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2.5,
+          "cache_write": 0.25
+        },
+        "limit": {
+          "context": 130000,
+          "output": 4096
+        },
+        "canonical_model_id": "perplexity/sonar"
+      },
+      "mistral-large-2512": {
+        "id": "mistral-large-2512",
+        "name": "Mistral Large 3",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.5
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "mistral/mistral-large-2512"
+      },
+      "grok-4-6": {
+        "id": "grok-4-6",
+        "name": "Grok 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "canonical_model_id": "xai/grok-4.6"
+      },
+      "gemini-pro-latest": {
+        "id": "gemini-pro-latest",
+        "name": "Gemini Pro Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        }
+      },
+      "gpt-4.1-mini": {
+        "id": "gpt-4.1-mini",
+        "name": "GPT-4.1 mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 1.6,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 32768
+        },
+        "canonical_model_id": "openai/gpt-4.1-mini"
+      },
+      "minimax-m2.5-highspeed": {
+        "id": "minimax-m2.5-highspeed",
+        "name": "MiniMax-M2.5-highspeed",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.4,
+          "cache_read": 0.03,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "canonical_model_id": "minimax/MiniMax-M2.5-highspeed"
+      },
+      "gemini-3.8-flash": {
+        "id": "gemini-3.8-flash",
+        "name": "Gemini 3.8 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 3.75,
+          "cache_read": 0.075,
+          "cache_write": 0.08333
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        }
+      },
+      "ministral-14b-2512": {
+        "id": "ministral-14b-2512",
+        "name": "Ministral 14B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 8192
+        }
+      },
+      "glm-5-turbo": {
+        "id": "glm-5-turbo",
+        "name": "GLM-5-Turbo",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.2,
+          "output": 4,
+          "cache_read": 0.24
+        },
+        "limit": {
+          "context": 200000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5-turbo"
+      },
+      "gpt-6-luna": {
+        "id": "gpt-6-luna",
+        "name": "GPT-6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.5,
+          "cache_read": 0.01,
+          "cache_write": 0.125
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-luna"
+      },
+      "deepseek-v4-pro": {
+        "id": "deepseek-v4-pro",
+        "name": "DeepSeek V4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.435,
+          "output": 0.87,
+          "cache_read": 0.003625
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro"
+      },
+      "step-3.7-flash": {
+        "id": "step-3.7-flash",
+        "name": "Step 3.7 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.15,
+          "cache_read": 0.04
+        },
+        "limit": {
+          "context": 262144,
+          "output": 256000
+        },
+        "canonical_model_id": "stepfun/step-3.7-flash"
+      },
+      "gemini-2.5-flash-lite": {
+        "id": "gemini-2.5-flash-lite",
+        "name": "Gemini 2.5 Flash-Lite",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.4,
+          "cache_read": 0.01
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-2.5-flash-lite"
+      },
+      "claude-sonnet-4-6": {
+        "id": "claude-sonnet-4-6",
+        "name": "Claude Sonnet 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024,
+            "max": 63999
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-6"
+      },
+      "claude-sonnet-5-5": {
+        "id": "claude-sonnet-5-5",
+        "name": "Claude Sonnet 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5-5"
+      },
+      "gpt-4o-mini-transcribe": {
+        "id": "gpt-4o-mini-transcribe",
+        "name": "GPT-4o Mini Transcribe",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 5
+        },
+        "limit": {
+          "context": 16000,
+          "output": 16000
+        }
+      },
+      "llama-3.2-3b-instruct": {
+        "id": "llama-3.2-3b-instruct",
+        "name": "Llama 3.2 3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.03,
+          "output": 0.05
+        },
+        "limit": {
+          "context": 32768,
+          "output": 32000
+        }
+      },
+      "qwen3.6-plus": {
+        "id": "qwen3.6-plus",
+        "name": "Qwen3.6 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.05,
+          "cache_write": 0.625
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.6-plus"
+      },
+      "mistral-small-2506": {
+        "id": "mistral-small-2506",
+        "name": "Mistral Small 3.2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "mistral/mistral-small-2506"
+      },
+      "grok-4-20-reasoning": {
+        "id": "grok-4-20-reasoning",
+        "name": "Grok 4.20 (Reasoning)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 30000
+        },
+        "canonical_model_id": "xai/grok-4.20-0309-reasoning"
+      },
+      "grok-4-7": {
+        "id": "grok-4-7",
+        "name": "Grok 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        }
+      },
+      "gpt-5.6-terra": {
+        "id": "gpt-5.6-terra",
+        "name": "GPT-5.6 Terra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-terra"
+      },
+      "deepseek-v3.2": {
+        "id": "deepseek-v3.2",
+        "name": "DeepSeek V3.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.26,
+          "output": 0.38,
+          "cache_read": 0.13
+        },
+        "limit": {
+          "context": 163840,
+          "output": 16384
+        }
+      },
+      "gpt-4-turbo": {
+        "id": "gpt-4-turbo",
+        "name": "GPT-4 Turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 30
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "canonical_model_id": "openai/gpt-4-turbo"
+      },
+      "atria-dawn-preview": {
+        "id": "atria-dawn-preview",
+        "name": "Atria Dawn Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "hy4-preview": {
+        "id": "hy4-preview",
+        "name": "Hy4 preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.834,
+          "output": 2.501,
+          "cache_read": 0.042
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "canonical_model_id": "tencent/hy4-preview"
+      },
+      "muse-spark-1.3-contributor": {
+        "id": "muse-spark-1.3-contributor",
+        "name": "Muse Spark 1.3 Contributor",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.2,
+          "cache_read": 0.002
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        }
+      },
+      "glm-4.5-air": {
+        "id": "glm-4.5-air",
+        "name": "GLM-4.5-Air",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.13,
+          "output": 0.85,
+          "cache_read": 0.025,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 131000,
+          "output": 98304
+        },
+        "canonical_model_id": "zhipuai/glm-4.5-air"
+      },
+      "qwen-plus-latest": {
+        "id": "qwen-plus-latest",
+        "name": "Qwen Plus Latest",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 1.2,
+          "cache_read": 0.08,
+          "cache_write": 0.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 8192
+        }
+      },
+      "gpt-oss-120b": {
+        "id": "gpt-oss-120b",
+        "name": "GPT OSS 120B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.032,
+          "output": 0.14,
+          "cache_read": 0.032
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32766
+        }
+      },
+      "gpt-5.1-codex-mini": {
+        "id": "gpt-5.1-codex-mini",
+        "name": "GPT-5.1 Codex mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.1-codex-mini"
+      },
+      "ministral-3b-2512": {
+        "id": "ministral-3b-2512",
+        "name": "Ministral 3B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.1
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "o3": {
+        "id": "o3",
+        "name": "o3",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 8,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "canonical_model_id": "openai/o3"
+      },
+      "glm-5.3": {
+        "id": "glm-5.3",
+        "name": "GLM-5.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.9,
+          "output": 3,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "claude-opus-4-7": {
+        "id": "claude-opus-4-7",
+        "name": "Claude Opus 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-7"
+      },
+      "kimi-k2.7-code": {
+        "id": "kimi-k2.7-code",
+        "name": "Kimi K2.7 Code",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.19
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code"
+      },
+      "gpt-5": {
+        "id": "gpt-5",
+        "name": "GPT-5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5"
+      },
+      "qwen3.7-plus": {
+        "id": "qwen3.7-plus",
+        "name": "Qwen3.7 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 1.6,
+          "cache_read": 0.08,
+          "cache_write": 0.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "canonical_model_id": "alibaba/qwen3.7-plus"
+      },
+      "minimax-m2.1": {
+        "id": "minimax-m2.1",
+        "name": "MiniMax-M2.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.27,
+          "output": 1.1
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "canonical_model_id": "minimax/MiniMax-M2.1"
+      },
+      "gpt-5.6-sol": {
+        "id": "gpt-5.6-sol",
+        "name": "GPT-5.6 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.4,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-sol"
+      },
+      "auto": {
+        "id": "auto",
+        "name": "Auto Route",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        }
+      },
+      "llama-3.1-70b-instruct": {
+        "id": "llama-3.1-70b-instruct",
+        "name": "Llama 3.1 70B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.72,
+          "output": 0.72
+        },
+        "limit": {
+          "context": 128000,
+          "output": 2048
+        },
+        "status": "beta"
+      },
+      "minimax-m2": {
+        "id": "minimax-m2",
+        "name": "MiniMax-M2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 196608,
+          "output": 131072
+        },
+        "canonical_model_id": "minimax/MiniMax-M2"
+      },
+      "custom": {
+        "id": "custom",
+        "name": "Custom Model",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        }
+      },
+      "codestral-2508": {
+        "id": "codestral-2508",
+        "name": "Codestral",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 0.9
+        },
+        "limit": {
+          "context": 256000,
+          "output": 16384
+        }
+      },
+      "deepseek-v4-flash": {
+        "id": "deepseek-v4-flash",
+        "name": "DeepSeek V4 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.065,
+          "output": 0.116,
+          "cache_read": 0.012
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash"
+      },
+      "gpt-6-sol": {
+        "id": "gpt-6-sol",
+        "name": "GPT-6 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-sol"
+      },
+      "gemini-3.1-flash-lite": {
+        "id": "gemini-3.1-flash-lite",
+        "name": "Gemini 3.1 Flash Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1.5,
+          "cache_read": 0.025,
+          "cache_write": 0.08333
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.1-flash-lite"
+      }
+    }
+  },
+  "meta": {
+    "id": "meta",
+    "name": "Meta",
+    "env": ["META_MODEL_API_KEY"],
+    "npm": "@ai-sdk/openai",
+    "api": "https://api.meta.ai/v1",
+    "models": {
+      "muse-spark-1.3": {
+        "id": "muse-spark-1.3",
+        "name": "Muse Spark 1.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 4.25,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "meta/muse-spark-1.3"
+      },
+      "muse-spark-1.1": {
+        "id": "muse-spark-1.1",
+        "name": "Muse Spark 1.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 4.25,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "meta/muse-spark-1.1"
+      },
+      "muse-spark-1.2": {
+        "id": "muse-spark-1.2",
+        "name": "Muse Spark 1.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 4.25,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "meta/muse-spark-1.2"
+      },
+      "muse-spark-1.2-contributor": {
+        "id": "muse-spark-1.2-contributor",
+        "name": "Muse Spark 1.2 Contributor",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.2,
+          "cache_read": 0.002
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "meta/muse-spark-1.2"
+      },
+      "muse-spark-1.3-contributor": {
+        "id": "muse-spark-1.3-contributor",
+        "name": "Muse Spark 1.3 Contributor",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.2,
+          "cache_read": 0.002
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "meta/muse-spark-1.3"
+      }
+    }
+  },
+  "minimax": {
+    "id": "minimax",
+    "name": "MiniMax (minimax.io)",
+    "env": ["MINIMAX_API_KEY"],
+    "npm": "@ai-sdk/anthropic",
+    "api": "https://api.minimax.io/anthropic/v1",
+    "models": {
+      "MiniMax-M3": {
+        "id": "MiniMax-M3",
+        "name": "MiniMax-M3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 512000
+        }
+      },
+      "MiniMax-M2.1": {
+        "id": "MiniMax-M2.1",
+        "name": "MiniMax-M2.1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.03,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "MiniMax-M2.5": {
+        "id": "MiniMax-M2.5",
+        "name": "MiniMax-M2.5",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.03,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "MiniMax-M2.7": {
+        "id": "MiniMax-M2.7",
+        "name": "MiniMax-M2.7",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "MiniMax-M2.7-highspeed": {
+        "id": "MiniMax-M2.7-highspeed",
+        "name": "MiniMax-M2.7-highspeed",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.4,
+          "cache_read": 0.06,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "MiniMax-M2": {
+        "id": "MiniMax-M2",
+        "name": "MiniMax-M2",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "MiniMax-M2.5-highspeed": {
+        "id": "MiniMax-M2.5-highspeed",
+        "name": "MiniMax-M2.5-highspeed",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.4,
+          "cache_read": 0.06,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      }
+    }
+  },
+  "minimax-cn": {
+    "id": "minimax-cn",
+    "name": "MiniMax (minimax.cn)",
+    "env": ["MINIMAX_API_KEY"],
+    "npm": "@ai-sdk/anthropic",
+    "api": "https://api.minimax.cn/anthropic/v1",
+    "models": {
+      "MiniMax-M3": {
+        "id": "MiniMax-M3",
+        "name": "MiniMax-M3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 512000
+        }
+      },
+      "MiniMax-M2.1": {
+        "id": "MiniMax-M2.1",
+        "name": "MiniMax-M2.1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.03,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "MiniMax-M2.5": {
+        "id": "MiniMax-M2.5",
+        "name": "MiniMax-M2.5",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.03,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "MiniMax-M2.7": {
+        "id": "MiniMax-M2.7",
+        "name": "MiniMax-M2.7",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "MiniMax-M2.7-highspeed": {
+        "id": "MiniMax-M2.7-highspeed",
+        "name": "MiniMax-M2.7-highspeed",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.4,
+          "cache_read": 0.06,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "MiniMax-M2": {
+        "id": "MiniMax-M2",
+        "name": "MiniMax-M2",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "MiniMax-M2.5-highspeed": {
+        "id": "MiniMax-M2.5-highspeed",
+        "name": "MiniMax-M2.5-highspeed",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.4,
+          "cache_read": 0.06,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      }
+    }
+  },
+  "mistral": {
+    "id": "mistral",
+    "name": "Mistral",
+    "env": ["MISTRAL_API_KEY"],
+    "npm": "@ai-sdk/mistral",
+    "models": {
+      "open-mistral-nemo": {
+        "id": "open-mistral-nemo",
+        "name": "Open Mistral Nemo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.15
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        },
+        "status": "deprecated"
+      },
+      "codestral-latest": {
+        "id": "codestral-latest",
+        "name": "Codestral (latest)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 0.9,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 256000,
+          "output": 4096
+        }
+      },
+      "mistral-large-2411": {
+        "id": "mistral-large-2411",
+        "name": "Mistral Large 2.1",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        },
+        "canonical_model_id": "mistral/mistral-large-2411"
+      },
+      "mistral-nemo": {
+        "id": "mistral-nemo",
+        "name": "Mistral Nemo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.15
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        }
+      },
+      "voxtral-mini-tts-latest": {
+        "id": "voxtral-mini-tts-latest",
+        "name": "Voxtral Mini TTS (latest)",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["audio"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "mistral-medium-2508": {
+        "id": "mistral-medium-2508",
+        "name": "Mistral Medium 3.1",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "mistral-large-latest": {
+        "id": "mistral-large-latest",
+        "name": "Mistral Large (latest)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.5,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "mistral-small-latest": {
+        "id": "mistral-small-latest",
+        "name": "Mistral Small (latest)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        }
+      },
+      "zai-glm-5-2": {
+        "id": "zai-glm-5-2",
+        "name": "GLM-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.14
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.2",
+        "status": "beta"
+      },
+      "ministral-8b-latest": {
+        "id": "ministral-8b-latest",
+        "name": "Ministral 8B (latest)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.1
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        }
+      },
+      "devstral-medium-latest": {
+        "id": "devstral-medium-latest",
+        "name": "Devstral 2 (latest)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "status": "deprecated"
+      },
+      "open-mixtral-8x22b": {
+        "id": "open-mixtral-8x22b",
+        "name": "Mixtral 8x22B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6
+        },
+        "limit": {
+          "context": 64000,
+          "output": 64000
+        }
+      },
+      "devstral-2512": {
+        "id": "devstral-2512",
+        "name": "Devstral 2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "status": "deprecated"
+      },
+      "mistral-medium-2505": {
+        "id": "mistral-medium-2505",
+        "name": "Mistral Medium 3",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        }
+      },
+      "magistral-medium-latest": {
+        "id": "magistral-medium-latest",
+        "name": "Magistral Medium (latest)",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 5
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        }
+      },
+      "pixtral-12b": {
+        "id": "pixtral-12b",
+        "name": "Pixtral 12B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.15
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        }
+      },
+      "mistral-embed": {
+        "id": "mistral-embed",
+        "name": "Mistral Embed",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0
+        },
+        "limit": {
+          "context": 8000,
+          "output": 3072
+        }
+      },
+      "devstral-small-2505": {
+        "id": "devstral-small-2505",
+        "name": "Devstral Small 2505",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        },
+        "status": "deprecated"
+      },
+      "mistral-small-2603": {
+        "id": "mistral-small-2603",
+        "name": "Mistral Small 4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        }
+      },
+      "devstral-medium-2507": {
+        "id": "devstral-medium-2507",
+        "name": "Devstral Medium",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        },
+        "status": "deprecated"
+      },
+      "voxtral-mini-latest": {
+        "id": "voxtral-mini-latest",
+        "name": "Voxtral Mini (latest)",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["audio"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "labs-devstral-small-2512": {
+        "id": "labs-devstral-small-2512",
+        "name": "Devstral Small 2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        },
+        "status": "deprecated"
+      },
+      "mistral-large-2512": {
+        "id": "mistral-large-2512",
+        "name": "Mistral Large 3",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.5,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "devstral-latest": {
+        "id": "devstral-latest",
+        "name": "Devstral 2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "status": "deprecated"
+      },
+      "devstral-small-2507": {
+        "id": "devstral-small-2507",
+        "name": "Devstral Small",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        },
+        "status": "deprecated"
+      },
+      "pixtral-large-latest": {
+        "id": "pixtral-large-latest",
+        "name": "Pixtral Large (latest)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        }
+      },
+      "voxtral-small-latest": {
+        "id": "voxtral-small-latest",
+        "name": "Voxtral Small (latest)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 32000,
+          "output": 32000
+        }
+      },
+      "open-mixtral-8x7b": {
+        "id": "open-mixtral-8x7b",
+        "name": "Mixtral 8x7B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.7,
+          "output": 0.7
+        },
+        "limit": {
+          "context": 32000,
+          "output": 32000
+        }
+      },
+      "mistral-small-2506": {
+        "id": "mistral-small-2506",
+        "name": "Mistral Small 3.2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        }
+      },
+      "zai-glm-5-3": {
+        "id": "zai-glm-5-3",
+        "name": "GLM-5.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.14
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "mistral-medium-2604": {
+        "id": "mistral-medium-2604",
+        "name": "Mistral Medium 3.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 7.5,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "open-mistral-7b": {
+        "id": "open-mistral-7b",
+        "name": "Mistral 7B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 0.25
+        },
+        "limit": {
+          "context": 8000,
+          "output": 8000
+        }
+      },
+      "ministral-3b-latest": {
+        "id": "ministral-3b-latest",
+        "name": "Ministral 3B (latest)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.04,
+          "output": 0.04
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        }
+      },
+      "mistral-medium-latest": {
+        "id": "mistral-medium-latest",
+        "name": "Mistral Medium (latest)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 7.5,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "mistral/mistral-medium-latest"
+      }
+    }
+  },
+  "moonshotai": {
+    "id": "moonshotai",
+    "name": "Moonshot AI",
+    "env": ["MOONSHOT_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://api.moonshot.ai/v1",
+    "models": {
+      "kimi-k3": {
+        "id": "kimi-k3",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "kimi-k2.7-code-highspeed": {
+        "id": "kimi-k2.7-code-highspeed",
+        "name": "Kimi K2.7 Code HighSpeed",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.9,
+          "output": 8,
+          "cache_read": 0.38
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code"
+      },
+      "kimi-k2.6": {
+        "id": "kimi-k2.6",
+        "name": "Kimi K2.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.16
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "kimi-k2.7-code": {
+        "id": "kimi-k2.7-code",
+        "name": "Kimi K2.7 Code",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.19
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code"
+      }
+    }
+  },
+  "moonshotai-cn": {
+    "id": "moonshotai-cn",
+    "name": "Moonshot AI (China)",
+    "env": ["MOONSHOT_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://api.moonshot.cn/v1",
+    "models": {
+      "kimi-k2.7-code": {
+        "id": "kimi-k2.7-code",
+        "name": "Kimi K2.7 Code",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.19
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code"
+      },
+      "kimi-k2.6": {
+        "id": "kimi-k2.6",
+        "name": "Kimi K2.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.16
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "kimi-k2.7-code-highspeed": {
+        "id": "kimi-k2.7-code-highspeed",
+        "name": "Kimi K2.7 Code HighSpeed",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.9,
+          "output": 8,
+          "cache_read": 0.38
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code"
+      },
+      "kimi-k3": {
+        "id": "kimi-k3",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      }
+    }
+  },
+  "nano-gpt": {
+    "id": "nano-gpt",
+    "name": "NanoGPT",
+    "env": ["NANO_GPT_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://nano-gpt.com/api/v1",
+    "models": {
+      "mistralai/mistral-medium-3.5": {
+        "id": "mistralai/mistral-medium-3.5",
+        "name": "Mistral Medium 3.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 7.5,
+          "cache_read": 0.75
+        },
+        "limit": {
+          "context": 256000,
+          "output": 32768
+        }
+      },
+      "inclusionai/ling-3.0-flash-vl": {
+        "id": "inclusionai/ling-3.0-flash-vl",
+        "name": "Ling 3.0 Flash VL",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.18,
+          "cache_read": 0.012
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      }
+    }
+  },
+  "novita-ai": {
+    "id": "novita-ai",
+    "name": "NovitaAI",
+    "env": ["NOVITA_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://api.novita.ai/openai",
+    "models": {
+      "inclusionai/ring-2.6-1t": {
+        "id": "inclusionai/ring-2.6-1t",
+        "name": "Ring-2.6-1T",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "inclusionai/ling-2.6-1t": {
+        "id": "inclusionai/ling-2.6-1t",
+        "name": "Ling-2.6-1T",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "inclusionai/ling-2.6-flash": {
+        "id": "inclusionai/ling-2.6-flash",
+        "name": "Ling-2.6-flash",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.3,
+          "cache_read": 0.02
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      }
+    }
+  },
+  "nvidia": {
+    "id": "nvidia",
+    "name": "Nvidia",
+    "env": ["NVIDIA_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://integrate.api.nvidia.com/v1",
+    "models": {
+      "baai/bge-m3": {
+        "id": "baai/bge-m3",
+        "name": "BGE M3",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1024
+        }
+      },
+      "poolside/laguna-xs-2.1": {
+        "id": "poolside/laguna-xs-2.1",
+        "name": "Laguna XS 2.1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 16384
+        },
+        "canonical_model_id": "poolside/laguna-xs-2.1"
+      },
+      "abacusai/dracarys-llama-3.1-70b-instruct": {
+        "id": "abacusai/dracarys-llama-3.1-70b-instruct",
+        "name": "dracarys-llama-3.1-70b-instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        },
+        "status": "deprecated"
+      },
+      "z-ai/glm-5.3-flash": {
+        "id": "z-ai/glm-5.3-flash",
+        "name": "GLM-5.3-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "z-ai/glm-5.2": {
+        "id": "z-ai/glm-5.2",
+        "name": "GLM-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.2",
+        "status": "deprecated"
+      },
+      "z-ai/glm-5.3": {
+        "id": "z-ai/glm-5.3",
+        "name": "GLM-5.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "thinkingmachines/inkling": {
+        "id": "thinkingmachines/inkling",
+        "name": "Inkling",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 16384
+        },
+        "canonical_model_id": "thinkingmachines/inkling",
+        "status": "deprecated"
+      },
+      "black-forest-labs/flux_1-schnell": {
+        "id": "black-forest-labs/flux_1-schnell",
+        "name": "FLUX.1-schnell",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 77,
+          "output": 0
+        }
+      },
+      "black-forest-labs/flux.1-dev": {
+        "id": "black-forest-labs/flux.1-dev",
+        "name": "FLUX.1-dev",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 4096,
+          "output": 0
+        }
+      },
+      "black-forest-labs/flux_1-kontext-dev": {
+        "id": "black-forest-labs/flux_1-kontext-dev",
+        "name": "FLUX.1-Kontext-dev",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["image"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 40960,
+          "output": 40960
+        }
+      },
+      "black-forest-labs/flux_2-klein-4b": {
+        "id": "black-forest-labs/flux_2-klein-4b",
+        "name": "FLUX.2 Klein 4B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text"],
+          "output": ["image"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 40960,
+          "output": 40960
+        }
+      },
+      "meta/llama-guard-4-12b": {
+        "id": "meta/llama-guard-4-12b",
+        "name": "Llama Guard 4 12B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        }
+      },
+      "meta/muse-glimmer-30b": {
+        "id": "meta/muse-glimmer-30b",
+        "name": "Muse Glimmer 30B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "canonical_model_id": "meta/muse-glimmer-30b"
+      },
+      "meta/esmfold": {
+        "id": "meta/esmfold",
+        "name": "esmfold",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "meta/llama-3.3-70b-instruct": {
+        "id": "meta/llama-3.3-70b-instruct",
+        "name": "Llama 3.3 70b Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "meta/llama-3.2-90b-vision-instruct": {
+        "id": "meta/llama-3.2-90b-vision-instruct",
+        "name": "Llama-3.2-90B-Vision-Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "meta/llama-4-maverick-17b-128e-instruct": {
+        "id": "meta/llama-4-maverick-17b-128e-instruct",
+        "name": "Llama 4 Maverick 17b 128e Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "meta/llama-3.1-8b-instruct": {
+        "id": "meta/llama-3.1-8b-instruct",
+        "name": "Llama 3.1 8B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 16000,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "meta/llama-3.2-11b-vision-instruct": {
+        "id": "meta/llama-3.2-11b-vision-instruct",
+        "name": "Llama 3.2 11b Vision Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        }
+      },
+      "meta/llama-3.2-1b-instruct": {
+        "id": "meta/llama-3.2-1b-instruct",
+        "name": "Llama 3.2 1b Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "meta/llama-3.2-3b-instruct": {
+        "id": "meta/llama-3.2-3b-instruct",
+        "name": "Llama 3.2 3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 32768,
+          "output": 32000
+        },
+        "status": "deprecated"
+      },
+      "meta/llama-3.1-70b-instruct": {
+        "id": "meta/llama-3.1-70b-instruct",
+        "name": "Llama 3.1 70b Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "meta/esm2-650m": {
+        "id": "meta/esm2-650m",
+        "name": "esm2-650m",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "upstage/solar-10.7b-instruct": {
+        "id": "upstage/solar-10.7b-instruct",
+        "name": "solar-10.7b-instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        },
+        "status": "deprecated"
+      },
+      "bytedance/seed-oss-36b-instruct": {
+        "id": "bytedance/seed-oss-36b-instruct",
+        "name": "ByteDance-Seed/Seed-OSS-36B-Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262000,
+          "output": 262000
+        },
+        "status": "deprecated"
+      },
+      "google/gemma-4-31b-it": {
+        "id": "google/gemma-4-31b-it",
+        "name": "Gemma-4-31B-IT",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 256000,
+          "output": 16384
+        }
+      },
+      "google/gemma-2-2b-it": {
+        "id": "google/gemma-2-2b-it",
+        "name": "Gemma 2 2b It",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "google/gemma-3-12b-it": {
+        "id": "google/gemma-3-12b-it",
+        "name": "Gemma 3 12B IT",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        }
+      },
+      "google/gemma-3n-e2b-it": {
+        "id": "google/gemma-3n-e2b-it",
+        "name": "Gemma 3n E2b It",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "google/google-paligemma": {
+        "id": "google/google-paligemma",
+        "name": "paligemma",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "google/gemma-3n-e4b-it": {
+        "id": "google/gemma-3n-e4b-it",
+        "name": "Gemma 3n E4b It",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "google/gemma-3-4b-it": {
+        "id": "google/gemma-3-4b-it",
+        "name": "Gemma 3 4B IT",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        }
+      },
+      "minimaxai/minimax-m2.7": {
+        "id": "minimaxai/minimax-m2.7",
+        "name": "MiniMax-M2.7",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "status": "deprecated"
+      },
+      "minimaxai/minimax-m3": {
+        "id": "minimaxai/minimax-m3",
+        "name": "MiniMax-M3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 16384
+        },
+        "canonical_model_id": "minimax/MiniMax-M3",
+        "status": "deprecated"
+      },
+      "deepseek-ai/deepseek-v4-flash-0731": {
+        "id": "deepseek-ai/deepseek-v4-flash-0731",
+        "name": "DeepSeek V4 Flash 0731",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-0731",
+        "status": "deprecated"
+      },
+      "deepseek-ai/deepseek-v4-pro-0813": {
+        "id": "deepseek-ai/deepseek-v4-pro-0813",
+        "name": "DeepSeek V4 Pro 0813",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro-0813",
+        "status": "deprecated"
+      },
+      "deepseek-ai/deepseek-v4-pro": {
+        "id": "deepseek-ai/deepseek-v4-pro",
+        "name": "DeepSeek V4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.435,
+          "output": 0.87,
+          "cache_read": 0.003625
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 393216
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro",
+        "status": "deprecated"
+      },
+      "deepseek-ai/deepseek-v4-flash": {
+        "id": "deepseek-ai/deepseek-v4-flash",
+        "name": "DeepSeek V4 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.0028
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 393216
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash",
+        "status": "deprecated"
+      },
+      "stepfun-ai/step-3.5-flash": {
+        "id": "stepfun-ai/step-3.5-flash",
+        "name": "Step 3.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 256000,
+          "output": 16384
+        },
+        "status": "deprecated"
+      },
+      "stepfun-ai/step-3.7-flash": {
+        "id": "stepfun-ai/step-3.7-flash",
+        "name": "Step 3.7 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 256000,
+          "output": 16384
+        },
+        "status": "deprecated"
+      },
+      "mistralai/mistral-nemotron": {
+        "id": "mistralai/mistral-nemotron",
+        "name": "mistral-nemotron",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        },
+        "canonical_model_id": "nvidia/mistral-nemotron"
+      },
+      "mistralai/mistral-7b-instruct-v0.3": {
+        "id": "mistralai/mistral-7b-instruct-v0.3",
+        "name": "Mistral-7B-Instruct-v0.3",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 65536,
+          "output": 65536
+        }
+      },
+      "mistralai/mistral-large-3-675b-instruct-2512": {
+        "id": "mistralai/mistral-large-3-675b-instruct-2512",
+        "name": "Mistral Large 3 675B Instruct 2512",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "status": "deprecated"
+      },
+      "mistralai/magistral-small-2506": {
+        "id": "mistralai/magistral-small-2506",
+        "name": "Magistral Small 2506",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 32768,
+          "output": 32768
+        }
+      },
+      "mistralai/mistral-small-4-119b-2603": {
+        "id": "mistralai/mistral-small-4-119b-2603",
+        "name": "mistral-small-4-119b-2603",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        },
+        "status": "deprecated"
+      },
+      "mistralai/mixtral-8x7b-instruct": {
+        "id": "mistralai/mixtral-8x7b-instruct",
+        "name": "Mistral: Mixtral 8x7B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 32768,
+          "output": 16384
+        }
+      },
+      "mistralai/mistral-medium-3.5-128b": {
+        "id": "mistralai/mistral-medium-3.5-128b",
+        "name": "Mistral Medium 3.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "mistral/mistral-medium-2604",
+        "status": "deprecated"
+      },
+      "mistralai/ministral-14b-instruct-2512": {
+        "id": "mistralai/ministral-14b-instruct-2512",
+        "name": "Ministral 3 14B Instruct 2512",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 16384
+        },
+        "status": "deprecated"
+      },
+      "mistralai/mixtral-8x22b-instruct": {
+        "id": "mistralai/mixtral-8x22b-instruct",
+        "name": "Mistral: Mixtral 8x22B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 65536,
+          "output": 13108
+        }
+      },
+      "mistralai/mistral-medium-3-instruct": {
+        "id": "mistralai/mistral-medium-3-instruct",
+        "name": "Mistral Medium 3",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "moonshotai/kimi-k3": {
+        "id": "moonshotai/kimi-k3",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "moonshotai/kimi-k2.6": {
+        "id": "moonshotai/kimi-k2.6",
+        "name": "Kimi K2.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "status": "deprecated"
+      },
+      "sarvamai/sarvam-m": {
+        "id": "sarvamai/sarvam-m",
+        "name": "sarvam-m",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        },
+        "status": "deprecated"
+      },
+      "nvidia/nvidia-nemotron-nano-9b-v2": {
+        "id": "nvidia/nvidia-nemotron-nano-9b-v2",
+        "name": "nvidia-nemotron-nano-9b-v2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "canonical_model_id": "nvidia/nemotron-nano-9b-v2",
+        "status": "deprecated"
+      },
+      "nvidia/llama-3.1-nemotron-ultra-253b-v1": {
+        "id": "nvidia/llama-3.1-nemotron-ultra-253b-v1",
+        "name": "Llama 3.1 Nemotron Ultra 253B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "nvidia/llama-3.1-nemotron-ultra-253b"
+      },
+      "nvidia/sparsedrive": {
+        "id": "nvidia/sparsedrive",
+        "name": "sparsedrive",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "nvidia/nemotron-3-nano-30b-a3b": {
+        "id": "nvidia/nemotron-3-nano-30b-a3b",
+        "name": "nemotron-3-nano-30b-a3b",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "canonical_model_id": "nvidia/nemotron-3-nano-30b-a3b",
+        "status": "deprecated"
+      },
+      "nvidia/nemotron-3.5-lightning-30b-a3b": {
+        "id": "nvidia/nemotron-3.5-lightning-30b-a3b",
+        "name": "Nemotron 3.5 Lightning 30B A3B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "nvidia/nemotron-3.5-lightning"
+      },
+      "nvidia/llama-nemotron-embed-vl-1b-v2": {
+        "id": "nvidia/llama-nemotron-embed-vl-1b-v2",
+        "name": "llama-nemotron-embed-vl-1b-v2",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 32768,
+          "output": 2048
+        },
+        "canonical_model_id": "nvidia/llama-nemotron-embed-vl-1b-v2"
+      },
+      "nvidia/nv-embedcode-7b-v1": {
+        "id": "nvidia/nv-embedcode-7b-v1",
+        "name": "nv-embedcode-7b-v1",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 32768,
+          "output": 2048
+        }
+      },
+      "nvidia/nemotron-voicechat": {
+        "id": "nvidia/nemotron-voicechat",
+        "name": "nemotron-voicechat",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        },
+        "canonical_model_id": "nvidia/nemotron-voicechat"
+      },
+      "nvidia/bevformer": {
+        "id": "nvidia/bevformer",
+        "name": "bevformer",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "nvidia/cosmos-transfer1-7b": {
+        "id": "nvidia/cosmos-transfer1-7b",
+        "name": "cosmos-transfer1-7b",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["video"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 0,
+          "output": 4096
+        }
+      },
+      "nvidia/cosmos-predict1-5b": {
+        "id": "nvidia/cosmos-predict1-5b",
+        "name": "cosmos-predict1-5b",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["video"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 0,
+          "output": 4096
+        }
+      },
+      "nvidia/llama-3.1-nemotron-nano-vl-8b-v1": {
+        "id": "nvidia/llama-3.1-nemotron-nano-vl-8b-v1",
+        "name": "Llama 3.1 Nemotron Nano VL 8B v1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 32768,
+          "output": 16384
+        },
+        "status": "deprecated"
+      },
+      "nvidia/nemotron-3-super-120b-a12b": {
+        "id": "nvidia/nemotron-3-super-120b-a12b",
+        "name": "Nemotron 3 Super",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.8
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "nvidia/nemotron-3-super-120b-a12b"
+      },
+      "nvidia/studiovoice": {
+        "id": "nvidia/studiovoice",
+        "name": "studiovoice",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "nvidia/nemotron-content-safety-reasoning-4b": {
+        "id": "nvidia/nemotron-content-safety-reasoning-4b",
+        "name": "nemotron-content-safety-reasoning-4b",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "canonical_model_id": "nvidia/nemotron-content-safety-reasoning-4b",
+        "status": "deprecated"
+      },
+      "nvidia/llama-3.1-nemotron-safety-guard-8b-v3": {
+        "id": "nvidia/llama-3.1-nemotron-safety-guard-8b-v3",
+        "name": "llama-3.1-nemotron-safety-guard-8b-v3",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "canonical_model_id": "nvidia/llama-3.1-nemotron-safety-guard-8b-v3"
+      },
+      "nvidia/nv-embed-v1": {
+        "id": "nvidia/nv-embed-v1",
+        "name": "nv-embed-v1",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 32768,
+          "output": 2048
+        }
+      },
+      "nvidia/synthetic-video-detector": {
+        "id": "nvidia/synthetic-video-detector",
+        "name": "synthetic-video-detector",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 0,
+          "output": 4096
+        }
+      },
+      "nvidia/cosmos-transfer2_5-2b": {
+        "id": "nvidia/cosmos-transfer2_5-2b",
+        "name": "cosmos-transfer2.5-2b",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["video"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 0,
+          "output": 4096
+        }
+      },
+      "nvidia/nemotron-3-ultra-550b-a55b": {
+        "id": "nvidia/nemotron-3-ultra-550b-a55b",
+        "name": "Nemotron 3 Ultra 550B A55B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 2.5,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "nvidia/nemotron-3-ultra-550b-a55b"
+      },
+      "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning": {
+        "id": "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning",
+        "name": "Nemotron 3 Nano Omni",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": -1,
+            "max": 32768
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 256000,
+          "output": 65536
+        },
+        "canonical_model_id": "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning"
+      },
+      "nvidia/llama-3.1-nemotron-nano-8b-v1": {
+        "id": "nvidia/llama-3.1-nemotron-nano-8b-v1",
+        "name": "Llama 3.1 Nemotron Nano 8B v1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        },
+        "status": "deprecated"
+      },
+      "nvidia/active-speaker-detection": {
+        "id": "nvidia/active-speaker-detection",
+        "name": "Active Speaker Detection",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 0,
+          "output": 4096
+        }
+      },
+      "nvidia/streampetr": {
+        "id": "nvidia/streampetr",
+        "name": "streampetr",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "nvidia/llama-nemotron-rerank-vl-1b-v2": {
+        "id": "nvidia/llama-nemotron-rerank-vl-1b-v2",
+        "name": "llama-nemotron-rerank-vl-1b-v2",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "canonical_model_id": "nvidia/llama-nemotron-rerank-vl-1b-v2"
+      },
+      "nvidia/nemotron-mini-4b-instruct": {
+        "id": "nvidia/nemotron-mini-4b-instruct",
+        "name": "nemotron-mini-4b-instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        },
+        "canonical_model_id": "nvidia/nemotron-mini-4b-instruct",
+        "status": "deprecated"
+      },
+      "nvidia/cosmos-reason2-8b": {
+        "id": "nvidia/cosmos-reason2-8b",
+        "name": "Cosmos Reason2 8B",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        }
+      },
+      "nvidia/nemotron-3-content-safety": {
+        "id": "nvidia/nemotron-3-content-safety",
+        "name": "nemotron-3-content-safety",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "canonical_model_id": "nvidia/nemotron-3-content-safety",
+        "status": "deprecated"
+      },
+      "nvidia/llama-3.3-nemotron-super-49b-v1": {
+        "id": "nvidia/llama-3.3-nemotron-super-49b-v1",
+        "name": "Llama 3.3 Nemotron Super 49B v1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 131072,
+          "output": 65536
+        },
+        "canonical_model_id": "nvidia/llama-3.3-nemotron-super-49b-v1",
+        "status": "deprecated"
+      },
+      "nvidia/magpie-tts-zeroshot": {
+        "id": "nvidia/magpie-tts-zeroshot",
+        "name": "magpie-tts-zeroshot",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["audio"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 0,
+          "output": 4096
+        }
+      },
+      "nvidia/riva-translate-4b-instruct-v1.1": {
+        "id": "nvidia/riva-translate-4b-instruct-v1.1",
+        "name": "riva-translate-4b-instruct-v1_1",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        }
+      },
+      "nvidia/nemotron-nano-12b-v2-vl": {
+        "id": "nvidia/nemotron-nano-12b-v2-vl",
+        "name": "Nemotron Nano 12B v2 VL",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        },
+        "canonical_model_id": "nvidia/nemotron-nano-12b-v2-vl",
+        "status": "deprecated"
+      },
+      "nvidia/llama-3.3-nemotron-super-49b-v1.5": {
+        "id": "nvidia/llama-3.3-nemotron-super-49b-v1.5",
+        "name": "Llama 3.3 Nemotron Super 49B v1.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 131072,
+          "output": 65536
+        },
+        "canonical_model_id": "nvidia/llama-3.3-nemotron-super-49b-v1.5",
+        "status": "deprecated"
+      },
+      "nvidia/llama-3_2-nemoretriever-300m-embed-v1": {
+        "id": "nvidia/llama-3_2-nemoretriever-300m-embed-v1",
+        "name": "llama-3_2-nemoretriever-300m-embed-v1",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 32768,
+          "output": 2048
+        }
+      },
+      "nvidia/gliner-pii": {
+        "id": "nvidia/gliner-pii",
+        "name": "gliner-pii",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "nvidia/usdcode": {
+        "id": "nvidia/usdcode",
+        "name": "usdcode",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        }
+      },
+      "nvidia/usdvalidate": {
+        "id": "nvidia/usdvalidate",
+        "name": "usdvalidate",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 0,
+          "output": 4096
+        }
+      },
+      "nvidia/llama-3.1-nemotron-70b-instruct": {
+        "id": "nvidia/llama-3.1-nemotron-70b-instruct",
+        "name": "Llama 3.1 Nemotron 70B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        },
+        "canonical_model_id": "nvidia/llama-3.1-nemotron-70b-instruct"
+      },
+      "nvidia/rerank-qa-mistral-4b": {
+        "id": "nvidia/rerank-qa-mistral-4b",
+        "name": "rerank-qa-mistral-4b",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        }
+      },
+      "qwen/qwen-image-edit": {
+        "id": "qwen/qwen-image-edit",
+        "name": "Qwen Image Edit",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["image"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "qwen/qwen3-coder-480b-a35b-instruct": {
+        "id": "qwen/qwen3-coder-480b-a35b-instruct",
+        "name": "Qwen3 Coder 480B A35B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 66536
+        },
+        "status": "deprecated"
+      },
+      "qwen/qwen3.5-122b-a10b": {
+        "id": "qwen/qwen3.5-122b-a10b",
+        "name": "Qwen3.5 122B-A10B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "status": "deprecated"
+      },
+      "qwen/qwen3-next-80b-a3b-instruct": {
+        "id": "qwen/qwen3-next-80b-a3b-instruct",
+        "name": "Qwen3-Next-80B-A3B-Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 16384
+        },
+        "status": "deprecated"
+      },
+      "qwen/qwen3.5-397b-a17b": {
+        "id": "qwen/qwen3.5-397b-a17b",
+        "name": "Qwen3.5-397B-A17B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 8192
+        },
+        "status": "deprecated"
+      },
+      "qwen/qwen2.5-coder-32b-instruct": {
+        "id": "qwen/qwen2.5-coder-32b-instruct",
+        "name": "Qwen2.5 Coder 32b Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "qwen/qwen-image": {
+        "id": "qwen/qwen-image",
+        "name": "Qwen Image",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["image"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "openai/whisper-large-v3": {
+        "id": "openai/whisper-large-v3",
+        "name": "Whisper Large v3",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 0,
+          "output": 4096
+        }
+      },
+      "openai/gpt-oss-20b": {
+        "id": "openai/gpt-oss-20b",
+        "name": "GPT OSS 20B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "microsoft/phi-4-mini-instruct": {
+        "id": "microsoft/phi-4-mini-instruct",
+        "name": "Phi-4-Mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        },
+        "status": "deprecated"
+      },
+      "microsoft/phi-4-multimodal-instruct": {
+        "id": "microsoft/phi-4-multimodal-instruct",
+        "name": "Phi 4 Multimodal",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "status": "deprecated"
+      }
+    }
+  },
+  "ollama-cloud": {
+    "id": "ollama-cloud",
+    "name": "Ollama Cloud",
+    "env": ["OLLAMA_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://ollama.com/v1",
+    "models": {
+      "glm-5.3-flash": {
+        "id": "glm-5.3-flash",
+        "name": "GLM-5.3-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "nemotron-3-ultra": {
+        "id": "nemotron-3-ultra",
+        "name": "nemotron-3-ultra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 3,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 262144,
+          "output": 128000
+        },
+        "canonical_model_id": "nvidia/nemotron-3-ultra-550b-a55b"
+      },
+      "kimi-k3": {
+        "id": "kimi-k3",
+        "name": "kimi-k3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "deepseek-v4.1-flash": {
+        "id": "deepseek-v4.1-flash",
+        "name": "DeepSeek V4.1 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.003
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4.1-flash"
+      },
+      "minimax-m2.5": {
+        "id": "minimax-m2.5",
+        "name": "minimax-m2.5",
+        "reasoning": true,
+        "reasoning_options": [],
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "kimi-k2.6": {
+        "id": "kimi-k2.6",
+        "name": "kimi-k2.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.16
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "qwen3.5:397b": {
+        "id": "qwen3.5:397b",
+        "name": "qwen3.5:397b",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_details"
+        },
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3.6
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "gpt-oss:20b": {
+        "id": "gpt-oss:20b",
+        "name": "gpt-oss:20b",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.3,
+          "cache_read": 0.035
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "gpt-oss:120b": {
+        "id": "gpt-oss:120b",
+        "name": "gpt-oss:120b",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.014
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "nemotron-3-nano:30b": {
+        "id": "nemotron-3-nano:30b",
+        "name": "nemotron-3-nano:30b",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.24
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "nvidia/nemotron-3-nano-30b-a3b"
+      },
+      "kimi-k2.5": {
+        "id": "kimi-k2.5",
+        "name": "kimi-k2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "mistral-large-3:675b": {
+        "id": "mistral-large-3:675b",
+        "name": "mistral-large-3:675b",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.5
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "minimax-m2.7": {
+        "id": "minimax-m2.7",
+        "name": "minimax-m2.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 196608,
+          "output": 196608
+        }
+      },
+      "deepseek-v4-pro:0813": {
+        "id": "deepseek-v4-pro:0813",
+        "name": "DeepSeek V4 Pro 0813",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.66,
+          "output": 1.98,
+          "cache_read": 0.022
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro-0813"
+      },
+      "minimax-m3": {
+        "id": "minimax-m3",
+        "name": "minimax-m3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.4,
+          "cache_read": 0.12
+        },
+        "limit": {
+          "context": 512000,
+          "output": 131072
+        }
+      },
+      "deepseek-v4-flash:0731": {
+        "id": "deepseek-v4-flash:0731",
+        "name": "DeepSeek V4 Flash 0731",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.22,
+          "output": 0.66,
+          "cache_read": 0.007
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-0731"
+      },
+      "gemma4:31b": {
+        "id": "gemma4:31b",
+        "name": "gemma4:31b",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.4,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "glm-5.2": {
+        "id": "glm-5.2",
+        "name": "GLM-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 976000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "glm-5.1": {
+        "id": "glm-5.1",
+        "name": "glm-5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 3.2,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 202752,
+          "output": 131072
+        }
+      },
+      "deepseek-v4-pro": {
+        "id": "deepseek-v4-pro",
+        "name": "deepseek-v4-pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.66,
+          "output": 1.98,
+          "cache_read": 0.022
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        }
+      },
+      "glm-5.3": {
+        "id": "glm-5.3",
+        "name": "GLM-5.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "kimi-k2.7-code": {
+        "id": "kimi-k2.7-code",
+        "name": "kimi-k2.7-code",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.19
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code"
+      },
+      "nemotron-3-super": {
+        "id": "nemotron-3-super",
+        "name": "nemotron-3-super",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.015,
+          "output": 0.6,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "nvidia/nemotron-3-super-120b-a12b"
+      },
+      "deepseek-v4-flash": {
+        "id": "deepseek-v4-flash",
+        "name": "deepseek-v4-flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.22,
+          "output": 0.66,
+          "cache_read": 0.007
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        }
+      }
+    }
+  },
+  "openai": {
+    "id": "openai",
+    "name": "OpenAI",
+    "env": ["OPENAI_API_KEY"],
+    "npm": "@ai-sdk/openai",
+    "models": {
+      "chatgpt-image-latest": {
+        "id": "chatgpt-image-latest",
+        "name": "chatgpt-image-latest",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "gpt-5.4": {
+        "id": "gpt-5.4",
+        "name": "GPT-5.4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 15,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        }
+      },
+      "gpt-5.4-pro": {
+        "id": "gpt-5.4-pro",
+        "name": "GPT-5.4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 30,
+          "output": 180
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        }
+      },
+      "gpt-3.5-turbo": {
+        "id": "gpt-3.5-turbo",
+        "name": "GPT-3.5-turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.5,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 16385,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "gpt-5.5-pro": {
+        "id": "gpt-5.5-pro",
+        "name": "GPT-5.5 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 30,
+          "output": 180
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        }
+      },
+      "text-embedding-3-small": {
+        "id": "text-embedding-3-small",
+        "name": "text-embedding-3-small",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.02,
+          "output": 0
+        },
+        "limit": {
+          "context": 8191,
+          "output": 1536
+        }
+      },
+      "gpt-5.4-nano": {
+        "id": "gpt-5.4-nano",
+        "name": "GPT-5.4 nano",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.25,
+          "cache_read": 0.02
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "gpt-realtime-2.1": {
+        "id": "gpt-realtime-2.1",
+        "name": "GPT-Realtime-2.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "audio", "image"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 24,
+          "cache_read": 0.4
+        },
+        "limit": {
+          "context": 128000,
+          "output": 32000
+        },
+        "canonical_model_id": "openai/gpt-realtime-2.1"
+      },
+      "gpt-4o-2024-05-13": {
+        "id": "gpt-4o-2024-05-13",
+        "name": "GPT-4o (2024-05-13)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 15
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "gpt-4o": {
+        "id": "gpt-4o",
+        "name": "GPT-4o",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        }
+      },
+      "gpt-5-mini": {
+        "id": "gpt-5-mini",
+        "name": "GPT-5 Mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "gpt-image-2": {
+        "id": "gpt-image-2",
+        "name": "gpt-image-2",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["image"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "openai/gpt-image-2"
+      },
+      "gpt-5.2-pro": {
+        "id": "gpt-5.2-pro",
+        "name": "GPT-5.2 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 21,
+          "output": 168
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "o4-mini": {
+        "id": "o4-mini",
+        "name": "o4-mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 4.4,
+          "cache_read": 0.275
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "status": "deprecated"
+      },
+      "o3-mini": {
+        "id": "o3-mini",
+        "name": "o3-mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 4.4,
+          "cache_read": 0.55
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "status": "deprecated"
+      },
+      "text-embedding-ada-002": {
+        "id": "text-embedding-ada-002",
+        "name": "text-embedding-ada-002",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "gpt-4": {
+        "id": "gpt-4",
+        "name": "GPT-4",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 30,
+          "output": 60
+        },
+        "limit": {
+          "context": 8192,
+          "output": 8192
+        },
+        "status": "deprecated"
+      },
+      "gpt-5.3-codex": {
+        "id": "gpt-5.3-codex",
+        "name": "GPT-5.3 Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "gpt-4.1-nano": {
+        "id": "gpt-4.1-nano",
+        "name": "GPT-4.1 nano",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.4,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 1047576,
+          "output": 32768
+        },
+        "status": "deprecated"
+      },
+      "gpt-5-nano": {
+        "id": "gpt-5-nano",
+        "name": "GPT-5 Nano",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.4,
+          "cache_read": 0.005
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "gpt-5.6": {
+        "id": "gpt-5.6",
+        "name": "GPT-5.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.4,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-sol"
+      },
+      "gpt-5.2-chat-latest": {
+        "id": "gpt-5.2-chat-latest",
+        "name": "GPT-5.2 Chat",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["medium"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "status": "deprecated"
+      },
+      "o1": {
+        "id": "o1",
+        "name": "o1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 60,
+          "cache_read": 7.5
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "status": "deprecated"
+      },
+      "gpt-5-pro": {
+        "id": "gpt-5-pro",
+        "name": "GPT-5 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 120
+        },
+        "limit": {
+          "context": 400000,
+          "output": 272000
+        }
+      },
+      "gpt-5.3-codex-spark": {
+        "id": "gpt-5.3-codex-spark",
+        "name": "GPT-5.3 Codex Spark",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 128000,
+          "output": 32000
+        }
+      },
+      "gpt-6.1-sol": {
+        "id": "gpt-6.1-sol",
+        "name": "GPT-6.1 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.1,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6.1-sol"
+      },
+      "text-embedding-3-large": {
+        "id": "text-embedding-3-large",
+        "name": "text-embedding-3-large",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.13,
+          "output": 0
+        },
+        "limit": {
+          "context": 8191,
+          "output": 3072
+        }
+      },
+      "gpt-4o-2024-08-06": {
+        "id": "gpt-4o-2024-08-06",
+        "name": "GPT-4o (2024-08-06)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        }
+      },
+      "gpt-6-astra": {
+        "id": "gpt-6-astra",
+        "name": "GPT-6 Astra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-astra"
+      },
+      "gpt-5.1": {
+        "id": "gpt-5.1",
+        "name": "GPT-5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "gpt-4o-mini": {
+        "id": "gpt-4o-mini",
+        "name": "GPT-4o mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        }
+      },
+      "o3-pro": {
+        "id": "o3-pro",
+        "name": "o3-pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 20,
+          "output": 80
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        }
+      },
+      "gpt-image-1": {
+        "id": "gpt-image-1",
+        "name": "gpt-image-1",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "openai/gpt-image-1",
+        "status": "deprecated"
+      },
+      "gpt-daybreak-blue-latest": {
+        "id": "gpt-daybreak-blue-latest",
+        "name": "Daybreak Blue",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.4,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-sol"
+      },
+      "gpt-5.4-mini": {
+        "id": "gpt-5.4-mini",
+        "name": "GPT-5.4 mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 4.5,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "gpt-5.6-luna": {
+        "id": "gpt-5.6-luna",
+        "name": "GPT-5.6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.2,
+          "cache_read": 0.02,
+          "cache_write": 0.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-luna"
+      },
+      "gpt-5.2": {
+        "id": "gpt-5.2",
+        "name": "GPT-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "gpt-5.5": {
+        "id": "gpt-5.5",
+        "name": "GPT-5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        }
+      },
+      "gpt-4.1": {
+        "id": "gpt-4.1",
+        "name": "GPT-4.1",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 8,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1047576,
+          "output": 32768
+        }
+      },
+      "gpt-4o-2024-11-20": {
+        "id": "gpt-4o-2024-11-20",
+        "name": "GPT-4o (2024-11-20)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        }
+      },
+      "gpt-4.1-mini": {
+        "id": "gpt-4.1-mini",
+        "name": "GPT-4.1 mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 1.6,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 1047576,
+          "output": 32768
+        }
+      },
+      "gpt-6-luna": {
+        "id": "gpt-6-luna",
+        "name": "GPT-6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.5,
+          "cache_read": 0.01,
+          "cache_write": 0.125
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-luna"
+      },
+      "gpt-5.3-chat-latest": {
+        "id": "gpt-5.3-chat-latest",
+        "name": "GPT-5.3 Chat (latest)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "status": "deprecated"
+      },
+      "gpt-image-1-mini": {
+        "id": "gpt-image-1-mini",
+        "name": "gpt-image-1-mini",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "gpt-image-1.5": {
+        "id": "gpt-image-1.5",
+        "name": "gpt-image-1.5",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "openai/gpt-image-1.5"
+      },
+      "gpt-5.6-terra": {
+        "id": "gpt-5.6-terra",
+        "name": "GPT-5.6 Terra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-terra"
+      },
+      "gpt-4-turbo": {
+        "id": "gpt-4-turbo",
+        "name": "GPT-4 Turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 30
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "gpt-daybreak-red-latest": {
+        "id": "gpt-daybreak-red-latest",
+        "name": "Daybreak Red",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 12.5,
+          "output": 75,
+          "cache_read": 1.25,
+          "cache_write": 15.625
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-cyber"
+      },
+      "o3": {
+        "id": "o3",
+        "name": "o3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 8,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        }
+      },
+      "gpt-5": {
+        "id": "gpt-5",
+        "name": "GPT-5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5"
+      },
+      "gpt-5.6-sol": {
+        "id": "gpt-5.6-sol",
+        "name": "GPT-5.6 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.4,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-sol"
+      },
+      "gpt-6-sol": {
+        "id": "gpt-6-sol",
+        "name": "GPT-6 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-sol"
+      },
+      "o1-pro": {
+        "id": "o1-pro",
+        "name": "o1-pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 150,
+          "output": 600
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "status": "deprecated"
+      }
+    }
+  },
+  "opencode": {
+    "id": "opencode",
+    "name": "OpenCode Zen",
+    "env": ["OPENCODE_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://opencode.ai/zen/v1",
+    "models": {
+      "ling-3.0-flash-fin-free": {
+        "id": "ling-3.0-flash-fin-free",
+        "name": "Ling 3.0 Flash Fin Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "inclusionai/ling-3.0-flash-fin"
+      },
+      "gpt-5.4": {
+        "id": "gpt-5.4",
+        "name": "GPT-5.4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 15,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5.4"
+      },
+      "qwen3.6-plus-free": {
+        "id": "qwen3.6-plus-free",
+        "name": "Qwen3.6 Plus Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 81920
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "status": "deprecated"
+      },
+      "claude-haiku-4-5": {
+        "id": "claude-haiku-4-5",
+        "name": "Claude Haiku 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 5,
+          "cache_read": 0.1,
+          "cache_write": 1.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        }
+      },
+      "gpt-5.4-pro": {
+        "id": "gpt-5.4-pro",
+        "name": "GPT-5.4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 30,
+          "output": 180,
+          "cache_read": 30
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        }
+      },
+      "mimo-v2-pro-free": {
+        "id": "mimo-v2-pro-free",
+        "name": "MiMo V2 Pro Free",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 64000
+        },
+        "status": "deprecated"
+      },
+      "muse-spark-1.2-contributor-free": {
+        "id": "muse-spark-1.2-contributor-free",
+        "name": "Muse Spark 1.2 Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "meta/muse-spark-1.2",
+        "status": "deprecated"
+      },
+      "muse-spark-1.3": {
+        "id": "muse-spark-1.3",
+        "name": "Muse Spark 1.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 4.25,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "meta/muse-spark-1.3"
+      },
+      "glm-5-free": {
+        "id": "glm-5-free",
+        "name": "GLM-5 Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "status": "deprecated"
+      },
+      "trinity-large-preview-free": {
+        "id": "trinity-large-preview-free",
+        "name": "Trinity Large Preview",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "canonical_model_id": "arcee-ai/trinity-large-preview",
+        "status": "deprecated"
+      },
+      "gpt-5.5-pro": {
+        "id": "gpt-5.5-pro",
+        "name": "GPT-5.5 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 30,
+          "output": 180,
+          "cache_read": 30
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        }
+      },
+      "grok-4.7": {
+        "id": "grok-4.7",
+        "name": "Grok 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "xai/grok-4.7"
+      },
+      "longcat-2.5-preview-free": {
+        "id": "longcat-2.5-preview-free",
+        "name": "LongCat 2.5 Preview Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "meituan/longcat-2.5-preview"
+      },
+      "gpt-5.4-nano": {
+        "id": "gpt-5.4-nano",
+        "name": "GPT-5.4 Nano",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.25,
+          "cache_read": 0.02
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        }
+      },
+      "gpt-5.2-codex": {
+        "id": "gpt-5.2-codex",
+        "name": "GPT-5.2 Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        }
+      },
+      "ling-3.0-tiny-free": {
+        "id": "ling-3.0-tiny-free",
+        "name": "Ling-3.0-tiny Free",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "status": "deprecated"
+      },
+      "gpt-5.1-codex": {
+        "id": "gpt-5.1-codex",
+        "name": "GPT-5.1 Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.07,
+          "output": 8.5,
+          "cache_read": 0.107
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        }
+      },
+      "glm-5.3-flash": {
+        "id": "glm-5.3-flash",
+        "name": "GLM-5.3-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "kimi-k2.5-free": {
+        "id": "kimi-k2.5-free",
+        "name": "Kimi K2.5 Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "status": "deprecated"
+      },
+      "glm-4.7-free": {
+        "id": "glm-4.7-free",
+        "name": "GLM-4.7 Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "status": "deprecated"
+      },
+      "glm-4.6": {
+        "id": "glm-4.6",
+        "name": "GLM-4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.2,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "status": "deprecated"
+      },
+      "laguna-s-2.1-free": {
+        "id": "laguna-s-2.1-free",
+        "name": "Laguna S 2.1 Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 256000,
+          "output": 32000
+        },
+        "canonical_model_id": "poolside/laguna-s-2.1",
+        "status": "deprecated"
+      },
+      "qwen3.8-max": {
+        "id": "qwen3.8-max",
+        "name": "Qwen3.8 Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.25,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-max"
+      },
+      "kimi-k3": {
+        "id": "kimi-k3",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "gpt-5-codex": {
+        "id": "gpt-5-codex",
+        "name": "GPT-5 Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.07,
+          "output": 8.5,
+          "cache_read": 0.107
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        }
+      },
+      "qwen3-coder": {
+        "id": "qwen3-coder",
+        "name": "Qwen3 Coder",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.45,
+          "output": 1.8
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "status": "deprecated"
+      },
+      "minimax-m3-free": {
+        "id": "minimax-m3-free",
+        "name": "MiniMax-M3 Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 200000,
+          "output": 32000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "status": "deprecated"
+      },
+      "qwen3.5-plus": {
+        "id": "qwen3.5-plus",
+        "name": "Qwen3.5 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 81920
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.2,
+          "cache_read": 0.02,
+          "cache_write": 0.25
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        }
+      },
+      "claude-opus-4-5": {
+        "id": "claude-opus-4-5",
+        "name": "Claude Opus 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        }
+      },
+      "glm-5": {
+        "id": "glm-5",
+        "name": "GLM-5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 3.2,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "deepseek-v4.1-flash": {
+        "id": "deepseek-v4.1-flash",
+        "name": "DeepSeek V4.1 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.006
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4.1-flash"
+      },
+      "gpt-5.3-codex": {
+        "id": "gpt-5.3-codex",
+        "name": "GPT-5.3 Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        }
+      },
+      "minimax-m2.5": {
+        "id": "minimax-m2.5",
+        "name": "MiniMax-M2.5",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "gpt-5-nano": {
+        "id": "gpt-5-nano",
+        "name": "GPT-5 Nano",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.4,
+          "cache_read": 0.005
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        }
+      },
+      "deepseek-v4-flash-vision-exp": {
+        "id": "deepseek-v4-flash-vision-exp",
+        "name": "DeepSeek V4 Flash Vision Exp",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.028
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-vision-exp"
+      },
+      "kimi-k2.6": {
+        "id": "kimi-k2.6",
+        "name": "Kimi K2.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.16
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "claude-sonnet-4-5": {
+        "id": "claude-sonnet-4-5",
+        "name": "Claude Sonnet 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        }
+      },
+      "claude-opus-5-5": {
+        "id": "claude-opus-5-5",
+        "name": "Claude Opus 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.2,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-5-5"
+      },
+      "claude-fable-5-1": {
+        "id": "claude-fable-5-1",
+        "name": "Claude Fable 5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 0.25,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-fable-5-1"
+      },
+      "gemini-3.6-flash": {
+        "id": "gemini-3.6-flash",
+        "name": "Gemini 3.6 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 7.5,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "provider": {
+          "npm": "@ai-sdk/google"
+        },
+        "canonical_model_id": "google/gemini-3.6-flash"
+      },
+      "kimi-k2-thinking": {
+        "id": "kimi-k2-thinking",
+        "name": "Kimi K2 Thinking",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2.5,
+          "cache_read": 0.4
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "status": "deprecated"
+      },
+      "minimax-m2.5-free": {
+        "id": "minimax-m2.5-free",
+        "name": "MiniMax-M2.5 Free",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "status": "deprecated"
+      },
+      "gpt-5.3-codex-spark": {
+        "id": "gpt-5.3-codex-spark",
+        "name": "GPT-5.3 Codex Spark",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        }
+      },
+      "gpt-6.1-sol": {
+        "id": "gpt-6.1-sol",
+        "name": "GPT-6.1 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.1,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-6.1-sol"
+      },
+      "gemini-3.5-flash-lite": {
+        "id": "gemini-3.5-flash-lite",
+        "name": "Gemini 3.5 Flash Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "provider": {
+          "npm": "@ai-sdk/google"
+        },
+        "canonical_model_id": "google/gemini-3.5-flash-lite"
+      },
+      "claude-opus-4-1": {
+        "id": "claude-opus-4-1",
+        "name": "Claude Opus 4.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 75,
+          "cache_read": 1.5,
+          "cache_write": 18.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 32000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "status": "deprecated"
+      },
+      "gpt-6-astra": {
+        "id": "gpt-6-astra",
+        "name": "GPT-6 Astra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-6-astra"
+      },
+      "grok-4.5": {
+        "id": "grok-4.5",
+        "name": "Grok 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "xai/grok-4.5"
+      },
+      "ring-2.6-1t-free": {
+        "id": "ring-2.6-1t-free",
+        "name": "Ring 2.6 1T Free",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262000,
+          "output": 66000
+        },
+        "status": "deprecated"
+      },
+      "kimi-k2.5": {
+        "id": "kimi-k2.5",
+        "name": "Kimi K2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3,
+          "cache_read": 0.08
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "longcat-2.0-free": {
+        "id": "longcat-2.0-free",
+        "name": "LongCat-2.0 Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "meituan/longcat-2.0",
+        "status": "deprecated"
+      },
+      "gpt-5.1": {
+        "id": "gpt-5.1",
+        "name": "GPT-5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.07,
+          "output": 8.5,
+          "cache_read": 0.107
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        }
+      },
+      "claude-opus-5": {
+        "id": "claude-opus-5",
+        "name": "Claude Opus 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-5"
+      },
+      "claude-3-5-haiku": {
+        "id": "claude-3-5-haiku",
+        "name": "Claude Haiku 3.5",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.8,
+          "output": 4,
+          "cache_read": 0.08,
+          "cache_write": 1
+        },
+        "limit": {
+          "context": 200000,
+          "output": 8192
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "status": "deprecated"
+      },
+      "hy3-preview-free": {
+        "id": "hy3-preview-free",
+        "name": "Hy3 preview Free",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 256000,
+          "output": 64000
+        },
+        "status": "deprecated"
+      },
+      "gemini-3-flash": {
+        "id": "gemini-3-flash",
+        "name": "Gemini 3 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "provider": {
+          "npm": "@ai-sdk/google"
+        }
+      },
+      "minimax-m2.7": {
+        "id": "minimax-m2.7",
+        "name": "MiniMax-M2.7",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "gemini-3.5-flash": {
+        "id": "gemini-3.5-flash",
+        "name": "Gemini 3.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 9,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "provider": {
+          "npm": "@ai-sdk/google"
+        }
+      },
+      "space-bunny-free": {
+        "id": "space-bunny-free",
+        "name": "Space Bunny Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 524288
+        }
+      },
+      "claude-fable-5": {
+        "id": "claude-fable-5",
+        "name": "Claude Fable 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-fable-5"
+      },
+      "nemotron-3-super-free": {
+        "id": "nemotron-3-super-free",
+        "name": "Nemotron 3 Super Free",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 204800,
+          "output": 128000
+        },
+        "canonical_model_id": "nvidia/nemotron-3-super-120b-a12b",
+        "status": "deprecated"
+      },
+      "minimax-m2.1-free": {
+        "id": "minimax-m2.1-free",
+        "name": "MiniMax-M2.1 Free",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "status": "deprecated"
+      },
+      "mimo-v2.6-flash-free": {
+        "id": "mimo-v2.6-flash-free",
+        "name": "MiMo-V2.6-Flash Free",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 200000,
+          "output": 32000
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.6-flash"
+      },
+      "gemini-3-pro": {
+        "id": "gemini-3-pro",
+        "name": "Gemini 3 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "provider": {
+          "npm": "@ai-sdk/google"
+        },
+        "status": "deprecated"
+      },
+      "nemotron-3-ultra-free": {
+        "id": "nemotron-3-ultra-free",
+        "name": "Nemotron 3 Ultra Free",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "nvidia/nemotron-3-ultra-550b-a55b"
+      },
+      "claude-sonnet-4": {
+        "id": "claude-sonnet-4",
+        "name": "Claude Sonnet 4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        }
+      },
+      "muse-spark-1.2": {
+        "id": "muse-spark-1.2",
+        "name": "Muse Spark 1.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 4.25,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "meta/muse-spark-1.2"
+      },
+      "gpt-5.4-mini": {
+        "id": "gpt-5.4-mini",
+        "name": "GPT-5.4 Mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 4.5,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        }
+      },
+      "glm-4.7": {
+        "id": "glm-4.7",
+        "name": "GLM-4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.2,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "status": "deprecated"
+      },
+      "minimax-m3": {
+        "id": "minimax-m3",
+        "name": "MiniMax-M3",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 512000,
+          "output": 128000
+        },
+        "canonical_model_id": "minimax/MiniMax-M3"
+      },
+      "gpt-5.6-luna": {
+        "id": "gpt-5.6-luna",
+        "name": "GPT-5.6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.2,
+          "cache_read": 0.02,
+          "cache_write": 0.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5.6-luna"
+      },
+      "qwen3.8-flash": {
+        "id": "qwen3.8-flash",
+        "name": "Qwen3.8 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.47,
+          "cache_read": 0.016,
+          "cache_write": 0.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "alibaba/qwen3.8-flash"
+      },
+      "gpt-5.1-codex-max": {
+        "id": "gpt-5.1-codex-max",
+        "name": "GPT-5.1 Codex Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        }
+      },
+      "mimo-v2.5-free": {
+        "id": "mimo-v2.5-free",
+        "name": "MiMo V2.5 Free",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 200000,
+          "output": 32000
+        },
+        "status": "deprecated"
+      },
+      "grok-code": {
+        "id": "grok-code",
+        "name": "Grok Code Fast 1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        },
+        "status": "deprecated"
+      },
+      "gpt-5.2": {
+        "id": "gpt-5.2",
+        "name": "GPT-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        }
+      },
+      "claude-opus-4-8": {
+        "id": "claude-opus-4-8",
+        "name": "Claude Opus 4.8",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-8"
+      },
+      "gpt-5.5": {
+        "id": "gpt-5.5",
+        "name": "GPT-5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5.5"
+      },
+      "ling-2.6-flash-free": {
+        "id": "ling-2.6-flash-free",
+        "name": "Ling 2.6 Flash Free",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262100,
+          "output": 32800
+        },
+        "status": "deprecated"
+      },
+      "claude-sonnet-5": {
+        "id": "claude-sonnet-5",
+        "name": "Claude Sonnet 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5"
+      },
+      "deepseek-v4-flash-free": {
+        "id": "deepseek-v4-flash-free",
+        "name": "DeepSeek V4 Flash Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 200000,
+          "output": 128000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-0731",
+        "status": "deprecated"
+      },
+      "hy3-free": {
+        "id": "hy3-free",
+        "name": "Hy3 Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 190000,
+          "output": 64000
+        },
+        "canonical_model_id": "tencent/hy3",
+        "status": "deprecated"
+      },
+      "nemotron-3.5-lightning-free": {
+        "id": "nemotron-3.5-lightning-free",
+        "name": "Nemotron 3.5 Lightning Free",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "nvidia/nemotron-3.5-lightning"
+      },
+      "claude-opus-4-6": {
+        "id": "claude-opus-4-6",
+        "name": "Claude Opus 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-6"
+      },
+      "gemini-3.7-flash": {
+        "id": "gemini-3.7-flash",
+        "name": "Gemini 3.7 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 7.5,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "provider": {
+          "npm": "@ai-sdk/google"
+        },
+        "canonical_model_id": "google/gemini-3.7-flash"
+      },
+      "glm-5.2": {
+        "id": "glm-5.2",
+        "name": "GLM-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "kimi-k2": {
+        "id": "kimi-k2",
+        "name": "Kimi K2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2.5,
+          "cache_read": 0.4
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "status": "deprecated"
+      },
+      "glm-5.1": {
+        "id": "glm-5.1",
+        "name": "GLM-5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "mimo-v2-omni-free": {
+        "id": "mimo-v2-omni-free",
+        "name": "MiMo V2 Omni Free",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 64000
+        },
+        "status": "deprecated"
+      },
+      "grok-build-0.1": {
+        "id": "grok-build-0.1",
+        "name": "Grok Build 0.1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 2,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "xai/grok-build-0.1"
+      },
+      "ling-3.0-flash-free": {
+        "id": "ling-3.0-flash-free",
+        "name": "Ling-3.0-flash Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "status": "deprecated"
+      },
+      "gemini-3.8-flash": {
+        "id": "gemini-3.8-flash",
+        "name": "Gemini 3.8 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 7.5,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "provider": {
+          "npm": "@ai-sdk/google"
+        },
+        "canonical_model_id": "google/gemini-3.8-flash"
+      },
+      "north-mini-code-free": {
+        "id": "north-mini-code-free",
+        "name": "North Mini Code Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 256000,
+          "output": 64000
+        },
+        "canonical_model_id": "cohere/north-mini-code-1-0",
+        "status": "deprecated"
+      },
+      "gpt-6-luna": {
+        "id": "gpt-6-luna",
+        "name": "GPT-6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.5,
+          "cache_read": 0.01,
+          "cache_write": 0.125
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-6-luna"
+      },
+      "deepseek-v4-pro": {
+        "id": "deepseek-v4-pro",
+        "name": "DeepSeek V4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.74,
+          "output": 3.84,
+          "cache_read": 0.145
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro"
+      },
+      "claude-sonnet-4-6": {
+        "id": "claude-sonnet-4-6",
+        "name": "Claude Sonnet 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        }
+      },
+      "big-pickle": {
+        "id": "big-pickle",
+        "name": "Big Pickle",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 200000,
+          "output": 32000
+        }
+      },
+      "claude-sonnet-5-5": {
+        "id": "claude-sonnet-5-5",
+        "name": "Claude Sonnet 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5-5"
+      },
+      "qwen3.6-plus": {
+        "id": "qwen3.6-plus",
+        "name": "Qwen3.6 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 81920
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.05,
+          "cache_write": 0.625
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        }
+      },
+      "gpt-5.6-terra": {
+        "id": "gpt-5.6-terra",
+        "name": "GPT-5.6 Terra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 15,
+          "cache_read": 0.25,
+          "cache_write": 3.125
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5.6-terra"
+      },
+      "mimo-v2-flash-free": {
+        "id": "mimo-v2-flash-free",
+        "name": "MiMo V2 Flash Free",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "status": "deprecated"
+      },
+      "gpt-5.1-codex-mini": {
+        "id": "gpt-5.1-codex-mini",
+        "name": "GPT-5.1 Codex Mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        }
+      },
+      "glm-5.3": {
+        "id": "glm-5.3",
+        "name": "GLM-5.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "claude-opus-4-7": {
+        "id": "claude-opus-4-7",
+        "name": "Claude Opus 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        }
+      },
+      "kimi-k2.7-code": {
+        "id": "kimi-k2.7-code",
+        "name": "Kimi K2.7 Code",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.19
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code"
+      },
+      "gpt-5": {
+        "id": "gpt-5",
+        "name": "GPT-5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.07,
+          "output": 8.5,
+          "cache_read": 0.107
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        }
+      },
+      "grok-4.6": {
+        "id": "grok-4.6",
+        "name": "Grok 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "xai/grok-4.6"
+      },
+      "gemini-3.1-pro": {
+        "id": "gemini-3.1-pro",
+        "name": "Gemini 3.1 Pro Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "provider": {
+          "npm": "@ai-sdk/google"
+        }
+      },
+      "minimax-m2.1": {
+        "id": "minimax-m2.1",
+        "name": "MiniMax-M2.1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "status": "deprecated"
+      },
+      "gpt-5.6-sol": {
+        "id": "gpt-5.6-sol",
+        "name": "GPT-5.6 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.4,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5.6-sol"
+      },
+      "x-preview-f-free": {
+        "id": "x-preview-f-free",
+        "name": "Ox Alpha Free (Unlimited)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "status": "deprecated"
+      },
+      "muse-spark-1.3-contributor-free": {
+        "id": "muse-spark-1.3-contributor-free",
+        "name": "Muse Spark 1.3 Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        }
+      },
+      "deepseek-v4-flash": {
+        "id": "deepseek-v4-flash",
+        "name": "DeepSeek V4 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.028
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-0731"
+      },
+      "gpt-6-sol": {
+        "id": "gpt-6-sol",
+        "name": "GPT-6 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-6-sol"
+      }
+    }
+  },
+  "opencode-go": {
+    "id": "opencode-go",
+    "name": "OpenCode Go",
+    "env": ["OPENCODE_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://opencode.ai/zen/go/v1",
+    "models": {
+      "mimo-v2.6-pro": {
+        "id": "mimo-v2.6-pro",
+        "name": "MiMo-V2.6-Pro",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.435,
+          "output": 0.87,
+          "cache_read": 0.003625
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.6-pro"
+      },
+      "qwen3.7-max": {
+        "id": "qwen3.7-max",
+        "name": "Qwen3.7 Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 262144
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 7.5,
+          "cache_read": 0.5,
+          "cache_write": 3.125
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "status": "deprecated"
+      },
+      "mimo-v2.5": {
+        "id": "mimo-v2.5",
+        "name": "MiMo V2.5",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.0028
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        }
+      },
+      "grok-4.7": {
+        "id": "grok-4.7",
+        "name": "Grok 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "xai/grok-4.7"
+      },
+      "longcat-2.5-preview-free": {
+        "id": "longcat-2.5-preview-free",
+        "name": "LongCat 2.5 Preview Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "meituan/longcat-2.5-preview"
+      },
+      "glm-5.3-flash": {
+        "id": "glm-5.3-flash",
+        "name": "GLM-5.3-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "qwen3.8-max": {
+        "id": "qwen3.8-max",
+        "name": "Qwen3.8 Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          },
+          {
+            "type": "budget_tokens",
+            "max": 262144
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.25,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-max"
+      },
+      "kimi-k3": {
+        "id": "kimi-k3",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "deepseek-v4.1-flash": {
+        "id": "deepseek-v4.1-flash",
+        "name": "DeepSeek V4.1 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.003
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4.1-flash"
+      },
+      "deepseek-v4-flash-vision-exp": {
+        "id": "deepseek-v4-flash-vision-exp",
+        "name": "DeepSeek V4 Flash Vision Exp",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.003
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-vision-exp"
+      },
+      "kimi-k2.6": {
+        "id": "kimi-k2.6",
+        "name": "Kimi K2.6",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.16
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "status": "deprecated"
+      },
+      "longcat-2.0": {
+        "id": "longcat-2.0",
+        "name": "LongCat-2.0",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.006
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "meituan/longcat-2.0"
+      },
+      "grok-4.5": {
+        "id": "grok-4.5",
+        "name": "Grok 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "xai/grok-4.5",
+        "status": "deprecated"
+      },
+      "minimax-m2.7": {
+        "id": "minimax-m2.7",
+        "name": "MiniMax-M2.7",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        }
+      },
+      "space-bunny-free": {
+        "id": "space-bunny-free",
+        "name": "Space Bunny Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 524288
+        }
+      },
+      "mimo-v2.5-pro": {
+        "id": "mimo-v2.5-pro",
+        "name": "MiMo V2.5 Pro",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.435,
+          "output": 0.87,
+          "cache_read": 0.003625
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 128000
+        }
+      },
+      "mimo-v2.6-flash": {
+        "id": "mimo-v2.6-flash",
+        "name": "MiMo-V2.6-Flash",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.0028
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.6-flash"
+      },
+      "minimax-m3": {
+        "id": "minimax-m3",
+        "name": "MiniMax-M3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        }
+      },
+      "gpt-5.6-luna": {
+        "id": "gpt-5.6-luna",
+        "name": "GPT-5.6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.2,
+          "cache_read": 0.02,
+          "cache_write": 0.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-5.6-luna"
+      },
+      "qwen3.8-flash": {
+        "id": "qwen3.8-flash",
+        "name": "Qwen3.8 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.47,
+          "cache_read": 0.016,
+          "cache_write": 0.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "provider": {
+          "npm": "@ai-sdk/anthropic"
+        },
+        "canonical_model_id": "alibaba/qwen3.8-flash"
+      },
+      "glm-5.2": {
+        "id": "glm-5.2",
+        "name": "GLM-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "hy3": {
+        "id": "hy3",
+        "name": "Hy3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.58,
+          "cache_read": 0.035
+        },
+        "limit": {
+          "context": 256000,
+          "output": 128000
+        },
+        "canonical_model_id": "tencent/hy3"
+      },
+      "muse-spark-1.2-contributor": {
+        "id": "muse-spark-1.2-contributor",
+        "name": "Muse Spark 1.2 Contributor",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.2,
+          "cache_read": 0.002
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "meta/muse-spark-1.2"
+      },
+      "gpt-6-luna": {
+        "id": "gpt-6-luna",
+        "name": "GPT-6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.5,
+          "cache_read": 0.01,
+          "cache_write": 0.125
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "openai/gpt-6-luna"
+      },
+      "deepseek-v4-pro": {
+        "id": "deepseek-v4-pro",
+        "name": "DeepSeek V4 Pro (New)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.66,
+          "output": 1.98,
+          "cache_read": 0.022
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        }
+      },
+      "qwen3.6-plus": {
+        "id": "qwen3.6-plus",
+        "name": "Qwen3.6 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 81920
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.05,
+          "cache_write": 0.625
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "status": "deprecated"
+      },
+      "hy4-preview": {
+        "id": "hy4-preview",
+        "name": "Hy4 preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.834,
+          "output": 2.501,
+          "cache_read": 0.042
+        },
+        "limit": {
+          "context": 1024000,
+          "output": 64000
+        },
+        "canonical_model_id": "tencent/hy4-preview"
+      },
+      "muse-spark-1.3-contributor": {
+        "id": "muse-spark-1.3-contributor",
+        "name": "Muse Spark 1.3 Contributor",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.2,
+          "cache_read": 0.002
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        }
+      },
+      "glm-5.3": {
+        "id": "glm-5.3",
+        "name": "GLM-5.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "kimi-k2.7-code": {
+        "id": "kimi-k2.7-code",
+        "name": "Kimi K2.7 Code",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.19
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code"
+      },
+      "grok-4.6": {
+        "id": "grok-4.6",
+        "name": "Grok 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "provider": {
+          "npm": "@ai-sdk/openai"
+        },
+        "canonical_model_id": "xai/grok-4.6"
+      },
+      "qwen3.7-plus": {
+        "id": "qwen3.7-plus",
+        "name": "Qwen3.7 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "max": 262144
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 1.6,
+          "cache_read": 0.04,
+          "cache_write": 0.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        }
+      },
+      "deepseek-v4-flash": {
+        "id": "deepseek-v4-flash",
+        "name": "DeepSeek V4 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.003
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-0731"
+      }
+    }
+  },
+  "openrouter": {
+    "id": "openrouter",
+    "name": "OpenRouter",
+    "env": ["OPENROUTER_API_KEY"],
+    "npm": "@openrouter/ai-sdk-provider",
+    "api": "https://openrouter.ai/api/v1",
+    "models": {
+      "sao10k/l3-lunaris-8b": {
+        "id": "sao10k/l3-lunaris-8b",
+        "name": "Llama 3 8B Lunaris",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.04,
+          "output": 0.05
+        },
+        "limit": {
+          "context": 8192,
+          "output": 7372
+        }
+      },
+      "sao10k/l3.3-euryale-70b": {
+        "id": "sao10k/l3.3-euryale-70b",
+        "name": "Llama 3.3 Euryale 70B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.65,
+          "output": 0.75
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        }
+      },
+      "sao10k/l3.1-euryale-70b": {
+        "id": "sao10k/l3.1-euryale-70b",
+        "name": "Llama 3.1 Euryale 70B v2.2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.85,
+          "output": 0.85
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        }
+      },
+      "kwaipilot/kat-coder-pro-v2.5": {
+        "id": "kwaipilot/kat-coder-pro-v2.5",
+        "name": "KAT-Coder-Pro V2.5",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.74,
+          "output": 2.96,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        }
+      },
+      "stealth/space-bunny-alpha": {
+        "id": "stealth/space-bunny-alpha",
+        "name": "Space Bunny Alpha",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 524288
+        }
+      },
+      "bytedance-seed/seed-1.6-flash": {
+        "id": "bytedance-seed/seed-1.6-flash",
+        "name": "Seed 1.6 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.075,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "bytedance-seed/seed-2.0-lite": {
+        "id": "bytedance-seed/seed-2.0-lite",
+        "name": "Seed 2.0 Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "bytedance-seed/seed-2.0-lite"
+      },
+      "bytedance-seed/seed-2-1-turbo": {
+        "id": "bytedance-seed/seed-2-1-turbo",
+        "name": "Seed 2.1 Turbo",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 2.5
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        }
+      },
+      "bytedance-seed/seed-2.0-mini": {
+        "id": "bytedance-seed/seed-2.0-mini",
+        "name": "Seed 2.0 Mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.4
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "bytedance-seed/seed-2.0-mini"
+      },
+      "bytedance-seed/seed-2.0-code": {
+        "id": "bytedance-seed/seed-2.0-code",
+        "name": "Seed 2.0 Code",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "bytedance-seed/seed-2.0-code"
+      },
+      "bytedance-seed/seed-1.6": {
+        "id": "bytedance-seed/seed-1.6",
+        "name": "Seed 1.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "~moonshotai/kimi-latest": {
+        "id": "~moonshotai/kimi-latest",
+        "name": "Kimi Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3654,
+          "output": 9.1343,
+          "cache_read": 0.4
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 943718
+        }
+      },
+      "poolside/laguna-s-2.1:free": {
+        "id": "poolside/laguna-s-2.1:free",
+        "name": "Laguna S 2.1 (free)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "poolside/laguna-s-2.1": {
+        "id": "poolside/laguna-s-2.1",
+        "name": "Laguna S 2.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.09,
+          "output": 0.18,
+          "cache_read": 0.009
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        }
+      },
+      "poolside/laguna-xs-2.1:free": {
+        "id": "poolside/laguna-xs-2.1:free",
+        "name": "Laguna XS 2.1 (free)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "poolside/laguna-xs-2.1"
+      },
+      "poolside/laguna-xs-2.1": {
+        "id": "poolside/laguna-xs-2.1",
+        "name": "Laguna XS 2.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.12,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "poolside/laguna-xs-2.1"
+      },
+      "prism-ml/ternary-bonsai-2-27b": {
+        "id": "prism-ml/ternary-bonsai-2-27b",
+        "name": "Ternary Bonsai 2 27B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["medium", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.075,
+          "output": 0.5,
+          "cache_read": 0.0375
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "anthropic/claude-opus-4.1": {
+        "id": "anthropic/claude-opus-4.1",
+        "name": "Claude Opus 4.1 (latest)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 75,
+          "cache_read": 1.5,
+          "cache_write": 18.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 32000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-1"
+      },
+      "anthropic/claude-opus-4.5": {
+        "id": "anthropic/claude-opus-4.5",
+        "name": "Claude Opus 4.5 (latest)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-5"
+      },
+      "anthropic/claude-opus-4.6": {
+        "id": "anthropic/claude-opus-4.6",
+        "name": "Claude Opus 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-6"
+      },
+      "anthropic/claude-opus-4.7": {
+        "id": "anthropic/claude-opus-4.7",
+        "name": "Claude Opus 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-7"
+      },
+      "anthropic/claude-opus-4.8": {
+        "id": "anthropic/claude-opus-4.8",
+        "name": "Claude Opus 4.8",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-8"
+      },
+      "anthropic/claude-haiku-4.5": {
+        "id": "anthropic/claude-haiku-4.5",
+        "name": "Claude Haiku 4.5 (latest)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 5,
+          "cache_read": 0.1,
+          "cache_write": 1.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-haiku-4-5"
+      },
+      "anthropic/claude-opus-5": {
+        "id": "anthropic/claude-opus-5",
+        "name": "Claude Opus 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5"
+      },
+      "anthropic/claude-sonnet-5.5": {
+        "id": "anthropic/claude-sonnet-5.5",
+        "name": "Claude Sonnet 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5-5"
+      },
+      "anthropic/claude-fable-5.1": {
+        "id": "anthropic/claude-fable-5.1",
+        "name": "Claude Fable 5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 0.25,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-fable-5-1"
+      },
+      "anthropic/claude-sonnet-4.5": {
+        "id": "anthropic/claude-sonnet-4.5",
+        "name": "Claude Sonnet 4.5 (latest)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-5"
+      },
+      "anthropic/claude-fable-5": {
+        "id": "anthropic/claude-fable-5",
+        "name": "Claude Fable 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-fable-5"
+      },
+      "anthropic/claude-sonnet-4": {
+        "id": "anthropic/claude-sonnet-4",
+        "name": "Claude Sonnet 4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        }
+      },
+      "anthropic/claude-sonnet-5": {
+        "id": "anthropic/claude-sonnet-5",
+        "name": "Claude Sonnet 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5"
+      },
+      "anthropic/claude-sonnet-4.6": {
+        "id": "anthropic/claude-sonnet-4.6",
+        "name": "Claude Sonnet 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-6"
+      },
+      "anthropic/claude-opus-5.5": {
+        "id": "anthropic/claude-opus-5.5",
+        "name": "Claude Opus 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.2,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5-5"
+      },
+      "nex-agi/nex-n2.5-mini": {
+        "id": "nex-agi/nex-n2.5-mini",
+        "name": "Nex-N2.5-Mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.025,
+          "output": 0.1,
+          "cache_read": 0.0025
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        }
+      },
+      "nex-agi/nex-n2.5-pro": {
+        "id": "nex-agi/nex-n2.5-pro",
+        "name": "Nex-N2.5-Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.075,
+          "output": 0.25,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        }
+      },
+      "cohere/command-r-08-2024": {
+        "id": "cohere/command-r-08-2024",
+        "name": "Command R",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4000
+        },
+        "canonical_model_id": "cohere/command-r-08-2024"
+      },
+      "cohere/command-a-plus": {
+        "id": "cohere/command-a-plus",
+        "name": "Command A+",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.5,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 192000,
+          "output": 64000
+        }
+      },
+      "cohere/command-a": {
+        "id": "cohere/command-a",
+        "name": "Command A",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10
+        },
+        "limit": {
+          "context": 256000,
+          "output": 8192
+        }
+      },
+      "cohere/north-mini-code:free": {
+        "id": "cohere/north-mini-code:free",
+        "name": "North Mini Code (free)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 256000,
+          "output": 64000
+        }
+      },
+      "cohere/command-r7b-12-2024": {
+        "id": "cohere/command-r7b-12-2024",
+        "name": "Command R7B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.0375,
+          "output": 0.15
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4000
+        },
+        "canonical_model_id": "cohere/command-r7b-12-2024"
+      },
+      "cohere/command-r-plus-08-2024": {
+        "id": "cohere/command-r-plus-08-2024",
+        "name": "Command R+",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4000
+        },
+        "canonical_model_id": "cohere/command-r-plus-08-2024"
+      },
+      "deepseek/deepseek-chat-v3.1": {
+        "id": "deepseek/deepseek-chat-v3.1",
+        "name": "DeepSeek V3.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 0.95,
+          "cache_read": 0.13
+        },
+        "limit": {
+          "context": 163840,
+          "output": 32768
+        }
+      },
+      "deepseek/deepseek-v4-flash-0731": {
+        "id": "deepseek/deepseek-v4-flash-0731",
+        "name": "DeepSeek V4 Flash 0731",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.01,
+          "output": 1.28,
+          "cache_read": 0.01
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 943718
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-0731"
+      },
+      "deepseek/deepseek-v4.1-flash": {
+        "id": "deepseek/deepseek-v4.1-flash",
+        "name": "DeepSeek V4.1 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.0198,
+          "output": 0.396,
+          "cache_read": 0.00291
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 943718
+        },
+        "canonical_model_id": "deepseek/deepseek-v4.1-flash"
+      },
+      "deepseek/deepseek-v4-flash-vision-exp": {
+        "id": "deepseek/deepseek-v4-flash-vision-exp",
+        "name": "DeepSeek V4 Flash Vision Exp",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2156,
+          "output": 0.6468,
+          "cache_read": 0.00686
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 262144
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-vision-exp"
+      },
+      "deepseek/deepseek-v3.1-terminus": {
+        "id": "deepseek/deepseek-v3.1-terminus",
+        "name": "DeepSeek V3.1 Terminus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1,
+          "cache_read": 0.135
+        },
+        "limit": {
+          "context": 163840,
+          "output": 65536
+        }
+      },
+      "deepseek/deepseek-chat": {
+        "id": "deepseek/deepseek-chat",
+        "name": "DeepSeek Chat",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2574,
+          "output": 1.0287
+        },
+        "limit": {
+          "context": 163840,
+          "output": 16000
+        },
+        "canonical_model_id": "deepseek/deepseek-chat"
+      },
+      "deepseek/deepseek-v4-pro-0813": {
+        "id": "deepseek/deepseek-v4-pro-0813",
+        "name": "DeepSeek V4 Pro 0813",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.66,
+          "output": 1.98,
+          "cache_read": 0.022
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 393216
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro-0813"
+      },
+      "deepseek/deepseek-v3.2-exp": {
+        "id": "deepseek/deepseek-v3.2-exp",
+        "name": "DeepSeek V3.2 Exp",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.27,
+          "output": 0.41
+        },
+        "limit": {
+          "context": 163840,
+          "output": 147456
+        }
+      },
+      "deepseek/deepseek-chat-v3-0324": {
+        "id": "deepseek/deepseek-chat-v3-0324",
+        "name": "DeepSeek V3 0324",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.29,
+          "output": 1.14,
+          "cache_read": 0.11
+        },
+        "limit": {
+          "context": 163840,
+          "output": 147456
+        }
+      },
+      "deepseek/deepseek-r1": {
+        "id": "deepseek/deepseek-r1",
+        "name": "DeepSeek-R1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.7,
+          "output": 2.5
+        },
+        "limit": {
+          "context": 64000,
+          "output": 16000
+        },
+        "canonical_model_id": "deepseek/deepseek-r1"
+      },
+      "deepseek/deepseek-v4-pro": {
+        "id": "deepseek/deepseek-v4-pro",
+        "name": "DeepSeek V4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["high", "xhigh"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.783,
+          "output": 1.566,
+          "cache_read": 0.06525
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro"
+      },
+      "deepseek/deepseek-r1-0528": {
+        "id": "deepseek/deepseek-r1-0528",
+        "name": "R1 0528",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 2.15,
+          "cache_read": 0.35
+        },
+        "limit": {
+          "context": 163840,
+          "output": 32768
+        }
+      },
+      "deepseek/deepseek-v3.2": {
+        "id": "deepseek/deepseek-v3.2",
+        "name": "DeepSeek V3.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.28,
+          "output": 0.42,
+          "cache_read": 0.028
+        },
+        "limit": {
+          "context": 163840,
+          "output": 65536
+        },
+        "canonical_model_id": "deepseek/deepseek-v3.2"
+      },
+      "deepseek/deepseek-v4-flash": {
+        "id": "deepseek/deepseek-v4-flash",
+        "name": "DeepSeek V4 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["high", "xhigh"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.028
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash"
+      },
+      "unbiased/pareto": {
+        "id": "unbiased/pareto",
+        "name": "Pareto",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 7.5,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "unbiased/pareto"
+      },
+      "tencent/hy3-preview": {
+        "id": "tencent/hy3-preview",
+        "name": "Hy3 preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.18,
+          "output": 0.6,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        },
+        "canonical_model_id": "tencent/hy3-preview"
+      },
+      "tencent/hunyuan-a13b-instruct": {
+        "id": "tencent/hunyuan-a13b-instruct",
+        "name": "Hunyuan A13B Instruct",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.57
+        },
+        "limit": {
+          "context": 131072,
+          "output": 117964
+        }
+      },
+      "tencent/hy-mt2-30b-a3b": {
+        "id": "tencent/hy-mt2-30b-a3b",
+        "name": "Hy-MT2-30B-A3B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.074,
+          "output": 0.295
+        },
+        "limit": {
+          "context": 8192,
+          "output": 4096
+        }
+      },
+      "tencent/hy-mt2-1.8b": {
+        "id": "tencent/hy-mt2-1.8b",
+        "name": "Hy-MT2-1.8B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.044,
+          "output": 0.177
+        },
+        "limit": {
+          "context": 8192,
+          "output": 4096
+        }
+      },
+      "tencent/hy3": {
+        "id": "tencent/hy3",
+        "name": "Hy3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.132,
+          "output": 0.528,
+          "cache_read": 0.033
+        },
+        "limit": {
+          "context": 262144,
+          "output": 128000
+        },
+        "canonical_model_id": "tencent/hy3"
+      },
+      "tencent/hy-mt2-7b": {
+        "id": "tencent/hy-mt2-7b",
+        "name": "Hy-MT2-7B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.074,
+          "output": 0.295
+        },
+        "limit": {
+          "context": 8192,
+          "output": 4096
+        }
+      },
+      "tencent/hy4-preview": {
+        "id": "tencent/hy4-preview",
+        "name": "Hy4 preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.834,
+          "output": 2.501,
+          "cache_read": 0.042
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 64000
+        },
+        "canonical_model_id": "tencent/hy4-preview"
+      },
+      "anthracite-org/magnum-v4-72b": {
+        "id": "anthracite-org/magnum-v4-72b",
+        "name": "Magnum v4 72B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 5
+        },
+        "limit": {
+          "context": 32768,
+          "output": 4096
+        }
+      },
+      "meta-llama/llama-4-scout": {
+        "id": "meta-llama/llama-4-scout",
+        "name": "Llama 4 Scout",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 1310720,
+          "output": 16384
+        }
+      },
+      "meta-llama/llama-guard-4-12b": {
+        "id": "meta-llama/llama-guard-4-12b",
+        "name": "Llama Guard 4 12B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.18,
+          "output": 0.18
+        },
+        "limit": {
+          "context": 163840,
+          "output": 16384
+        }
+      },
+      "meta-llama/llama-4-maverick": {
+        "id": "meta-llama/llama-4-maverick",
+        "name": "Llama 4 Maverick",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1875,
+          "output": 0.6525
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 16384
+        }
+      },
+      "meta-llama/llama-3.3-70b-instruct": {
+        "id": "meta-llama/llama-3.3-70b-instruct",
+        "name": "Llama-3.3-70B-Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.32
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        },
+        "canonical_model_id": "meta/llama-3.3-70b-instruct"
+      },
+      "meta-llama/llama-3.1-8b-instruct": {
+        "id": "meta-llama/llama-3.1-8b-instruct",
+        "name": "Llama-3.1-8B-Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.08,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 131072,
+          "output": 117964
+        },
+        "canonical_model_id": "meta/llama-3.1-8b-instruct"
+      },
+      "meta-llama/llama-3.2-1b-instruct": {
+        "id": "meta-llama/llama-3.2-1b-instruct",
+        "name": "Llama 3.2 1B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.027,
+          "output": 0.201
+        },
+        "limit": {
+          "context": 60000,
+          "output": 54000
+        }
+      },
+      "meta-llama/llama-3.2-3b-instruct": {
+        "id": "meta-llama/llama-3.2-3b-instruct",
+        "name": "Llama 3.2 3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.33
+        },
+        "limit": {
+          "context": 131072,
+          "output": 117964
+        }
+      },
+      "meta-llama/llama-3.1-70b-instruct": {
+        "id": "meta-llama/llama-3.1-70b-instruct",
+        "name": "Llama-3.1-70B-Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 0.4
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        },
+        "canonical_model_id": "meta/llama-3.1-70b-instruct"
+      },
+      "~google/gemini-flash-latest": {
+        "id": "~google/gemini-flash-latest",
+        "name": "Gemini Flash Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 3.75,
+          "cache_read": 0.075,
+          "cache_write": 0.041667
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        }
+      },
+      "~google/gemini-pro-latest": {
+        "id": "~google/gemini-pro-latest",
+        "name": "Gemini Pro Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["audio", "pdf", "image", "text", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        }
+      },
+      "perceptron/perceptron-mk1": {
+        "id": "perceptron/perceptron-mk1",
+        "name": "Perceptron Mk1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 1.5
+        },
+        "limit": {
+          "context": 32768,
+          "output": 8192
+        }
+      },
+      "perceptron/perceptron-mk1.5": {
+        "id": "perceptron/perceptron-mk1.5",
+        "name": "Perceptron Mk1.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 1.5
+        },
+        "limit": {
+          "context": 36864,
+          "output": 8192
+        }
+      },
+      "z-ai/glm-4.6v": {
+        "id": "z-ai/glm-4.6v",
+        "name": "GLM-4.6V",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 0.9,
+          "cache_read": 0.055
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "zhipuai/glm-4.6v"
+      },
+      "z-ai/glm-4.5": {
+        "id": "z-ai/glm-4.5",
+        "name": "GLM-4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.2,
+          "cache_read": 0.11
+        },
+        "limit": {
+          "context": 131072,
+          "output": 98304
+        },
+        "canonical_model_id": "zhipuai/glm-4.5"
+      },
+      "z-ai/glm-5.3-prime": {
+        "id": "z-ai/glm-5.3-prime",
+        "name": "GLM 5.3 Prime",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.8,
+          "output": 8.8,
+          "cache_read": 0.56
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        }
+      },
+      "z-ai/glm-5v-turbo": {
+        "id": "z-ai/glm-5v-turbo",
+        "name": "GLM-5V-Turbo",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.2,
+          "output": 4,
+          "cache_read": 0.24
+        },
+        "limit": {
+          "context": 202752,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5v-turbo"
+      },
+      "z-ai/glm-5.3-flash": {
+        "id": "z-ai/glm-5.3-flash",
+        "name": "GLM-5.3-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 943717
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "z-ai/glm-4.6": {
+        "id": "z-ai/glm-4.6",
+        "name": "GLM-4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.43,
+          "output": 1.75,
+          "cache_read": 0.08
+        },
+        "limit": {
+          "context": 204800,
+          "output": 16384
+        },
+        "canonical_model_id": "zhipuai/glm-4.6"
+      },
+      "z-ai/glm-5": {
+        "id": "z-ai/glm-5",
+        "name": "GLM-5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 1.92,
+          "cache_read": 0.12
+        },
+        "limit": {
+          "context": 204800,
+          "output": 128000
+        },
+        "canonical_model_id": "zhipuai/glm-5"
+      },
+      "z-ai/glm-4.5v": {
+        "id": "z-ai/glm-4.5v",
+        "name": "GLM-4.5V",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 1.8,
+          "cache_read": 0.11
+        },
+        "limit": {
+          "context": 65536,
+          "output": 16384
+        },
+        "canonical_model_id": "zhipuai/glm-4.5v"
+      },
+      "z-ai/glm-5.3-flashx": {
+        "id": "z-ai/glm-5.3-flashx",
+        "name": "GLM 5.3 FlashX",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.37,
+          "output": 1.25,
+          "cache_read": 0.09
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        }
+      },
+      "z-ai/glm-4.7-flash": {
+        "id": "z-ai/glm-4.7-flash",
+        "name": "GLM-4.7-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_details"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.0605,
+          "output": 0.4
+        },
+        "limit": {
+          "context": 200000,
+          "output": 117964
+        },
+        "canonical_model_id": "zhipuai/glm-4.7-flash"
+      },
+      "z-ai/glm-4.7": {
+        "id": "z-ai/glm-4.7",
+        "name": "GLM-4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_details"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.2,
+          "cache_read": 0.11
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-4.7"
+      },
+      "z-ai/glm-5.2": {
+        "id": "z-ai/glm-5.2",
+        "name": "GLM-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["high", "xhigh"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.41,
+          "output": 3.99,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 943718
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "z-ai/glm-5.1": {
+        "id": "z-ai/glm-5.1",
+        "name": "GLM-5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.1"
+      },
+      "z-ai/glm-5-turbo": {
+        "id": "z-ai/glm-5-turbo",
+        "name": "GLM-5-Turbo",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.2,
+          "output": 4,
+          "cache_read": 0.24
+        },
+        "limit": {
+          "context": 202752,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5-turbo"
+      },
+      "z-ai/glm-4.5-air": {
+        "id": "z-ai/glm-4.5-air",
+        "name": "GLM-4.5-Air",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.13,
+          "output": 0.85,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 131072,
+          "output": 98304
+        },
+        "canonical_model_id": "zhipuai/glm-4.5-air"
+      },
+      "z-ai/glm-5.3": {
+        "id": "z-ai/glm-5.3",
+        "name": "GLM-5.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 943717
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "inference-net/schematron-v2-small": {
+        "id": "inference-net/schematron-v2-small",
+        "name": "Schematron V2 Small",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.23,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        }
+      },
+      "inference-net/schematron-v2-turbo": {
+        "id": "inference-net/schematron-v2-turbo",
+        "name": "Schematron V2 Turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.03,
+          "output": 0.15,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "thinkingmachines/inkling-small:free": {
+        "id": "thinkingmachines/inkling-small:free",
+        "name": "Inkling Small (free)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 262144
+        },
+        "canonical_model_id": "thinkingmachines/inkling-small"
+      },
+      "thinkingmachines/inkling-small": {
+        "id": "thinkingmachines/inkling-small",
+        "name": "Inkling Small",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.45,
+          "output": 1.2,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 524288,
+          "output": 262144
+        },
+        "canonical_model_id": "thinkingmachines/inkling-small"
+      },
+      "thinkingmachines/inkling:free": {
+        "id": "thinkingmachines/inkling:free",
+        "name": "Inkling (free)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 262144
+        },
+        "canonical_model_id": "thinkingmachines/inkling"
+      },
+      "thinkingmachines/inkling": {
+        "id": "thinkingmachines/inkling",
+        "name": "Inkling",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 4.05,
+          "cache_read": 0.17
+        },
+        "limit": {
+          "context": 524288,
+          "output": 471859
+        },
+        "canonical_model_id": "thinkingmachines/inkling"
+      },
+      "meituan/longcat-2.0": {
+        "id": "meituan/longcat-2.0",
+        "name": "LongCat 2.0",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.006
+        },
+        "limit": {
+          "context": 1048756,
+          "output": 262144
+        }
+      },
+      "openrouter/bodybuilder": {
+        "id": "openrouter/bodybuilder",
+        "name": "Body Builder (beta)",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        }
+      },
+      "openrouter/free": {
+        "id": "openrouter/free",
+        "name": "Free Models Router",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 200000,
+          "output": 8000
+        }
+      },
+      "openrouter/pareto-code": {
+        "id": "openrouter/pareto-code",
+        "name": "Pareto Code Router",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 200000
+        }
+      },
+      "openrouter/fusion": {
+        "id": "openrouter/fusion",
+        "name": "Fusion",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        }
+      },
+      "openrouter/auto": {
+        "id": "openrouter/auto",
+        "name": "Auto Router",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "pdf", "video"],
+          "output": ["text", "image"]
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 2000000
+        }
+      },
+      "perplexity/sonar-pro": {
+        "id": "perplexity/sonar-pro",
+        "name": "Sonar Pro",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15
+        },
+        "limit": {
+          "context": 200000,
+          "output": 8000
+        }
+      },
+      "perplexity/sonar-deep-research": {
+        "id": "perplexity/sonar-deep-research",
+        "name": "Sonar Deep Research",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 8
+        },
+        "limit": {
+          "context": 128000,
+          "output": 115200
+        }
+      },
+      "perplexity/sonar": {
+        "id": "perplexity/sonar",
+        "name": "Sonar",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 1
+        },
+        "limit": {
+          "context": 127072,
+          "output": 114364
+        }
+      },
+      "perplexity/sonar-reasoning-pro": {
+        "id": "perplexity/sonar-reasoning-pro",
+        "name": "Sonar Reasoning Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 8
+        },
+        "limit": {
+          "context": 128000,
+          "output": 115200
+        }
+      },
+      "perplexity/sonar-pro-search": {
+        "id": "perplexity/sonar-pro-search",
+        "name": "Sonar Pro Search",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15
+        },
+        "limit": {
+          "context": 200000,
+          "output": 8000
+        }
+      },
+      "meta/muse-spark-1.3": {
+        "id": "meta/muse-spark-1.3",
+        "name": "Muse Spark 1.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 4.25,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 943718
+        },
+        "canonical_model_id": "meta/muse-spark-1.3"
+      },
+      "meta/muse-glimmer-30b": {
+        "id": "meta/muse-glimmer-30b",
+        "name": "Muse Glimmer 30B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.35,
+          "output": 1.5,
+          "cache_read": 0.04
+        },
+        "limit": {
+          "context": 131072,
+          "output": 117964
+        },
+        "canonical_model_id": "meta/muse-glimmer-30b"
+      },
+      "meta/muse-spark-1.1": {
+        "id": "meta/muse-spark-1.1",
+        "name": "Muse Spark 1.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 4.25,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 943718
+        },
+        "canonical_model_id": "meta/muse-spark-1.1"
+      },
+      "meta/muse-spark-1.2": {
+        "id": "meta/muse-spark-1.2",
+        "name": "Muse Spark 1.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 4.25,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 943718
+        },
+        "canonical_model_id": "meta/muse-spark-1.2"
+      },
+      "meta/muse-spark-1.2-contributor": {
+        "id": "meta/muse-spark-1.2-contributor",
+        "name": "Muse Spark 1.2 Contributor",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.2,
+          "cache_read": 0.002
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 943718
+        }
+      },
+      "meta/muse-spark-1.3-contributor": {
+        "id": "meta/muse-spark-1.3-contributor",
+        "name": "Muse Spark 1.3 Contributor",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.2,
+          "cache_read": 0.002
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 943718
+        }
+      },
+      "nousresearch/hermes-3-llama-3.1-70b": {
+        "id": "nousresearch/hermes-3-llama-3.1-70b",
+        "name": "Hermes 3 70B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.7,
+          "output": 0.7
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        }
+      },
+      "nousresearch/hermes-3-llama-3.1-405b": {
+        "id": "nousresearch/hermes-3-llama-3.1-405b",
+        "name": "Hermes 3 405B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 1
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        }
+      },
+      "nousresearch/hermes-4-405b": {
+        "id": "nousresearch/hermes-4-405b",
+        "name": "Hermes 4 405B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 3
+        },
+        "limit": {
+          "context": 131072,
+          "output": 117964
+        }
+      },
+      "~z-ai/glm-flash-latest": {
+        "id": "~z-ai/glm-flash-latest",
+        "name": "GLM Flash Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.02,
+          "output": 0.2475,
+          "cache_read": 0.01
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 943718
+        }
+      },
+      "~z-ai/glm-latest": {
+        "id": "~z-ai/glm-latest",
+        "name": "GLM Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.13,
+          "output": 4,
+          "cache_read": 0.13
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        }
+      },
+      "arcee-ai/trinity-large-thinking": {
+        "id": "arcee-ai/trinity-large-thinking",
+        "name": "Trinity Large Thinking",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 0.8,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 262144,
+          "output": 80000
+        },
+        "canonical_model_id": "arcee-ai/trinity-large-thinking"
+      },
+      "~openai/gpt-terra-latest": {
+        "id": "~openai/gpt-terra-latest",
+        "name": "GPT Terra Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["pdf", "image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        }
+      },
+      "~openai/gpt-luna-latest": {
+        "id": "~openai/gpt-luna-latest",
+        "name": "GPT Luna Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["pdf", "image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.5,
+          "cache_read": 0.01,
+          "cache_write": 0.125
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        }
+      },
+      "~openai/gpt-sol-latest": {
+        "id": "~openai/gpt-sol-latest",
+        "name": "GPT Sol Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["pdf", "image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.1,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        }
+      },
+      "~openai/gpt-astra-latest": {
+        "id": "~openai/gpt-astra-latest",
+        "name": "GPT Astra Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["pdf", "image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        }
+      },
+      "~openai/gpt-mini-latest": {
+        "id": "~openai/gpt-mini-latest",
+        "name": "GPT Mini Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["pdf", "image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 4.5,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "cognitivecomputations/dolphin-mistral-24b-venice-edition": {
+        "id": "cognitivecomputations/dolphin-mistral-24b-venice-edition",
+        "name": "Uncensored",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.9
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "thedrummer/skyfall-36b-v2": {
+        "id": "thedrummer/skyfall-36b-v2",
+        "name": "Skyfall 36B V2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.55,
+          "output": 0.8,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 32768,
+          "output": 29491
+        }
+      },
+      "thedrummer/unslopnemo-12b": {
+        "id": "thedrummer/unslopnemo-12b",
+        "name": "UnslopNemo 12B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 0.4
+        },
+        "limit": {
+          "context": 1024000,
+          "output": 819200
+        }
+      },
+      "thedrummer/cydonia-24b-v4.1": {
+        "id": "thedrummer/cydonia-24b-v4.1",
+        "name": "Cydonia 24B V4.1",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 0.5,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 131072,
+          "output": 117964
+        }
+      },
+      "baidu/ernie-4.5-vl-424b-a47b": {
+        "id": "baidu/ernie-4.5-vl-424b-a47b",
+        "name": "ERNIE 4.5 VL 424B A47B ",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.42,
+          "output": 1.25
+        },
+        "limit": {
+          "context": 123000,
+          "output": 16000
+        }
+      },
+      "x-ai/grok-4.20-multi-agent": {
+        "id": "x-ai/grok-4.20-multi-agent",
+        "name": "Grok 4.20 Multi-Agent",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 1800000
+        }
+      },
+      "x-ai/grok-4.7": {
+        "id": "x-ai/grok-4.7",
+        "name": "Grok 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 500000,
+          "output": 450000
+        },
+        "canonical_model_id": "xai/grok-4.7"
+      },
+      "x-ai/grok-4.3": {
+        "id": "x-ai/grok-4.3",
+        "name": "Grok 4.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 900000
+        },
+        "canonical_model_id": "xai/grok-4.3"
+      },
+      "x-ai/grok-4.5": {
+        "id": "x-ai/grok-4.5",
+        "name": "Grok 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 500000,
+          "output": 450000
+        },
+        "canonical_model_id": "xai/grok-4.5"
+      },
+      "x-ai/grok-build-0.1": {
+        "id": "x-ai/grok-build-0.1",
+        "name": "Grok Build 0.1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 2,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 256000,
+          "output": 230400
+        },
+        "canonical_model_id": "xai/grok-build-0.1"
+      },
+      "x-ai/grok-4.20": {
+        "id": "x-ai/grok-4.20",
+        "name": "Grok 4.20",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 1800000
+        }
+      },
+      "x-ai/grok-4.6": {
+        "id": "x-ai/grok-4.6",
+        "name": "Grok 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 500000,
+          "output": 450000
+        },
+        "canonical_model_id": "xai/grok-4.6"
+      },
+      "~anthropic/claude-opus-latest": {
+        "id": "~anthropic/claude-opus-latest",
+        "name": "Claude Opus Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.2,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        }
+      },
+      "~anthropic/claude-haiku-latest": {
+        "id": "~anthropic/claude-haiku-latest",
+        "name": "Claude Haiku Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 5,
+          "cache_read": 0.1,
+          "cache_write": 1.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        }
+      },
+      "~anthropic/claude-sonnet-latest": {
+        "id": "~anthropic/claude-sonnet-latest",
+        "name": "Claude Sonnet Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        }
+      },
+      "~anthropic/claude-fable-latest": {
+        "id": "~anthropic/claude-fable-latest",
+        "name": "Claude Fable Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 0.25,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        }
+      },
+      "upstage/solar-pro-3": {
+        "id": "upstage/solar-pro-3",
+        "name": "Solar Pro 3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 131072,
+          "output": 117964
+        }
+      },
+      "upstage/solar-pro4": {
+        "id": "upstage/solar-pro4",
+        "name": "Solar Pro 4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.09,
+          "output": 0.36,
+          "cache_read": 0.018
+        },
+        "limit": {
+          "context": 524288,
+          "output": 131072
+        }
+      },
+      "upstage/solar-mini4": {
+        "id": "upstage/solar-mini4",
+        "name": "Solar Mini 4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.2,
+          "cache_read": 0.005
+        },
+        "limit": {
+          "context": 524288,
+          "output": 131072
+        }
+      },
+      "~deepseek/deepseek-flash-latest": {
+        "id": "~deepseek/deepseek-flash-latest",
+        "name": "DeepSeek Flash Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.0198,
+          "output": 0.396,
+          "cache_read": 0.00291
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 943718
+        }
+      },
+      "~deepseek/deepseek-pro-latest": {
+        "id": "~deepseek/deepseek-pro-latest",
+        "name": "DeepSeek Pro Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.123,
+          "output": 3.5,
+          "cache_read": 0.123
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 393216
+        }
+      },
+      "~deepseek/deepseek-v4-flash-latest": {
+        "id": "~deepseek/deepseek-v4-flash-latest",
+        "name": "DeepSeek V4 Flash Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.0099,
+          "output": 0.13068,
+          "cache_read": 0.001386
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 943718
+        }
+      },
+      "~x-ai/grok-latest": {
+        "id": "~x-ai/grok-latest",
+        "name": "Grok Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 500000,
+          "output": 450000
+        }
+      },
+      "bytedance/ui-tars-1.5-7b": {
+        "id": "bytedance/ui-tars-1.5-7b",
+        "name": "UI-TARS 7B ",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.2,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 128000,
+          "output": 2048
+        }
+      },
+      "liquid/lfm-2.5-2.6b:free": {
+        "id": "liquid/lfm-2.5-2.6b:free",
+        "name": "LFM2.5-2.6B (free)",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 65536,
+          "output": 8192
+        }
+      },
+      "google/gemma-4-31b-it": {
+        "id": "google/gemma-4-31b-it",
+        "name": "Gemma 4 31B IT",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.09,
+          "output": 0.34,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 262144,
+          "output": 16384
+        },
+        "canonical_model_id": "google/gemma-4-31b-it"
+      },
+      "google/gemini-3.1-flash-image-preview": {
+        "id": "google/gemini-3.1-flash-image-preview",
+        "name": "Nano Banana 2 Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["minimal", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3
+        },
+        "limit": {
+          "context": 65536,
+          "output": 58982
+        },
+        "canonical_model_id": "google/gemini-3.1-flash-image-preview"
+      },
+      "google/lyria-3-pro-preview": {
+        "id": "google/lyria-3-pro-preview",
+        "name": "Lyria 3 Pro Preview",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/lyria-3-pro-preview"
+      },
+      "google/gemma-3-27b-it": {
+        "id": "google/gemma-3-27b-it",
+        "name": "Gemma 3 27B IT",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.08,
+          "output": 0.45,
+          "cache_read": 0.04
+        },
+        "limit": {
+          "context": 131072,
+          "output": 117964
+        },
+        "canonical_model_id": "google/gemma-3-27b-it"
+      },
+      "google/gemma-4-31b-it:free": {
+        "id": "google/gemma-4-31b-it:free",
+        "name": "Gemma 4 31B (free)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemma-4-31b-it"
+      },
+      "google/gemini-2.5-flash-image": {
+        "id": "google/gemini-2.5-flash-image",
+        "name": "Nano Banana",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.03,
+          "cache_write": 0.083333
+        },
+        "limit": {
+          "context": 32768,
+          "output": 8192
+        },
+        "canonical_model_id": "google/gemini-2.5-flash-image"
+      },
+      "google/gemma-4-26b-a4b-it:free": {
+        "id": "google/gemma-4-26b-a4b-it:free",
+        "name": "Gemma 4 26B A4B  (free)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemma-4-26b-a4b-it"
+      },
+      "google/gemma-2-27b-it": {
+        "id": "google/gemma-2-27b-it",
+        "name": "Gemma 2 27B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.65,
+          "output": 0.65
+        },
+        "limit": {
+          "context": 8192,
+          "output": 2048
+        }
+      },
+      "google/gemini-3.6-flash": {
+        "id": "google/gemini-3.6-flash",
+        "name": "Gemini 3.6 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 3.75,
+          "cache_read": 0.075,
+          "cache_write": 0.041667
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.6-flash"
+      },
+      "google/gemma-4-26b-a4b-it": {
+        "id": "google/gemma-4-26b-a4b-it",
+        "name": "Gemma 4 26B A4B IT",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.09,
+          "output": 0.3,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        },
+        "canonical_model_id": "google/gemma-4-26b-a4b-it"
+      },
+      "google/gemini-3-pro-image-preview": {
+        "id": "google/gemini-3-pro-image-preview",
+        "name": "Nano Banana Pro Preview",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 65536,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemini-3-pro-image-preview"
+      },
+      "google/gemini-3.5-flash-lite": {
+        "id": "google/gemini-3.5-flash-lite",
+        "name": "Gemini 3.5 Flash Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.03,
+          "cache_write": 0.083333
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.5-flash-lite"
+      },
+      "google/gemini-3.1-flash-image": {
+        "id": "google/gemini-3.1-flash-image",
+        "name": "Nano Banana 2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["minimal", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemini-3.1-flash-image"
+      },
+      "google/lyria-3-clip-preview": {
+        "id": "google/lyria-3-clip-preview",
+        "name": "Lyria 3 Clip Preview",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/lyria-3-clip-preview"
+      },
+      "google/gemini-3.1-pro-preview": {
+        "id": "google/gemini-3.1-pro-preview",
+        "name": "Gemini 3.1 Pro Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_details"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.1-pro-preview"
+      },
+      "google/gemma-3-12b-it": {
+        "id": "google/gemma-3-12b-it",
+        "name": "Gemma 3 12B IT",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.15
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        },
+        "canonical_model_id": "google/gemma-3-12b-it"
+      },
+      "google/gemini-3.5-flash": {
+        "id": "google/gemini-3.5-flash",
+        "name": "Gemini 3.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 9,
+          "cache_read": 0.15,
+          "cache_write": 0.083333
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.5-flash"
+      },
+      "google/gemini-2.5-pro": {
+        "id": "google/gemini-2.5-pro",
+        "name": "Gemini 2.5 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 128,
+            "max": 32768
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-2.5-pro"
+      },
+      "google/gemini-3-pro-image": {
+        "id": "google/gemini-3-pro-image",
+        "name": "Nano Banana Pro",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemini-3-pro-image"
+      },
+      "google/gemini-2.5-flash": {
+        "id": "google/gemini-2.5-flash",
+        "name": "Gemini 2.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.03,
+          "cache_write": 0.083333
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65535
+        },
+        "canonical_model_id": "google/gemini-2.5-flash"
+      },
+      "google/gemini-3.1-flash-lite-image": {
+        "id": "google/gemini-3.1-flash-lite-image",
+        "name": "Nano Banana 2 Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["minimal", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1.5
+        },
+        "limit": {
+          "context": 65536,
+          "output": 58982
+        },
+        "canonical_model_id": "google/gemini-3.1-flash-lite-image"
+      },
+      "google/gemini-3.7-flash": {
+        "id": "google/gemini-3.7-flash",
+        "name": "Gemini 3.7 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 3.75,
+          "cache_read": 0.075,
+          "cache_write": 0.041667
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.7-flash"
+      },
+      "google/gemini-3.1-pro-preview-customtools": {
+        "id": "google/gemini-3.1-pro-preview-customtools",
+        "name": "Gemini 3.1 Pro Preview Custom Tools",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_details"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.1-pro-preview-customtools"
+      },
+      "google/gemini-3-flash-preview": {
+        "id": "google/gemini-3-flash-preview",
+        "name": "Gemini 3 Flash Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_details"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.05,
+          "cache_write": 0.083333
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3-flash-preview"
+      },
+      "google/gemini-3.8-flash": {
+        "id": "google/gemini-3.8-flash",
+        "name": "Gemini 3.8 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 3.75,
+          "cache_read": 0.075,
+          "cache_write": 0.041667
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.8-flash"
+      },
+      "google/gemma-3-4b-it": {
+        "id": "google/gemma-3-4b-it",
+        "name": "Gemma 3 4B IT",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.1
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        },
+        "canonical_model_id": "google/gemma-3-4b-it"
+      },
+      "google/gemini-2.5-flash-lite": {
+        "id": "google/gemini-2.5-flash-lite",
+        "name": "Gemini 2.5 Flash-Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.4,
+          "cache_read": 0.01,
+          "cache_write": 0.083333
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65535
+        },
+        "canonical_model_id": "google/gemini-2.5-flash-lite"
+      },
+      "google/gemini-2.5-pro-preview": {
+        "id": "google/gemini-2.5-pro-preview",
+        "name": "Gemini 2.5 Pro Preview 06-05",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 128,
+            "max": 32768
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["pdf", "image", "text", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        }
+      },
+      "google/gemini-3.1-flash-lite-preview": {
+        "id": "google/gemini-3.1-flash-lite-preview",
+        "name": "Gemini 3.1 Flash Lite Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1.5,
+          "cache_read": 0.025,
+          "cache_write": 0.083333
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.1-flash-lite-preview"
+      },
+      "google/gemini-3.1-flash-lite": {
+        "id": "google/gemini-3.1-flash-lite",
+        "name": "Gemini 3.1 Flash Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1.5,
+          "cache_read": 0.025,
+          "cache_write": 0.083333
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-3.1-flash-lite"
+      },
+      "writer/palmyra-x5": {
+        "id": "writer/palmyra-x5",
+        "name": "Palmyra X5",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 6
+        },
+        "limit": {
+          "context": 1040000,
+          "output": 8192
+        }
+      },
+      "ibm-granite/granite-4.0-h-micro": {
+        "id": "ibm-granite/granite-4.0-h-micro",
+        "name": "Granite 4.0 Micro",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.017,
+          "output": 0.112
+        },
+        "limit": {
+          "context": 131000,
+          "output": 117900
+        }
+      },
+      "ibm-granite/granite-4.2-8b": {
+        "id": "ibm-granite/granite-4.2-8b",
+        "name": "Granite 4.2 8B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.25,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 131072,
+          "output": 117964
+        }
+      },
+      "fireworks/ember-1": {
+        "id": "fireworks/ember-1",
+        "name": "Ember-1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 943718
+        }
+      },
+      "mistralai/mistral-nemo": {
+        "id": "mistralai/mistral-nemo",
+        "name": "Mistral Nemo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.019,
+          "output": 0.03
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        },
+        "canonical_model_id": "mistral/mistral-nemo"
+      },
+      "mistralai/ministral-8b-2512": {
+        "id": "mistralai/ministral-8b-2512",
+        "name": "Ministral 3 8B 2512",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.15,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 262144,
+          "output": 209715
+        }
+      },
+      "mistralai/mistral-small-24b-instruct-2501": {
+        "id": "mistralai/mistral-small-24b-instruct-2501",
+        "name": "Mistral Small 3",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.08
+        },
+        "limit": {
+          "context": 32768,
+          "output": 16384
+        }
+      },
+      "mistralai/devstral-2512": {
+        "id": "mistralai/devstral-2512",
+        "name": "Devstral 2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2,
+          "cache_read": 0.04
+        },
+        "limit": {
+          "context": 262144,
+          "output": 209715
+        },
+        "canonical_model_id": "mistral/devstral-2512"
+      },
+      "mistralai/mistral-saba": {
+        "id": "mistralai/mistral-saba",
+        "name": "Saba",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.6,
+          "cache_read": 0.02
+        },
+        "limit": {
+          "context": 32768,
+          "output": 26214
+        }
+      },
+      "mistralai/mistral-medium-3-5": {
+        "id": "mistralai/mistral-medium-3-5",
+        "name": "Mistral Medium 3.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 7.5
+        },
+        "limit": {
+          "context": 262144,
+          "output": 209715
+        }
+      },
+      "mistralai/mistral-medium-3.1": {
+        "id": "mistralai/mistral-medium-3.1",
+        "name": "Mistral Medium 3.1",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2,
+          "cache_read": 0.04
+        },
+        "limit": {
+          "context": 131072,
+          "output": 104857
+        }
+      },
+      "mistralai/mistral-small-3.2-24b-instruct": {
+        "id": "mistralai/mistral-small-3.2-24b-instruct",
+        "name": "Mistral Small 3.2 24B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.09375,
+          "output": 0.25
+        },
+        "limit": {
+          "context": 256000,
+          "output": 16384
+        }
+      },
+      "mistralai/mistral-large": {
+        "id": "mistralai/mistral-large",
+        "name": "Mistral Large",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 128000,
+          "output": 102400
+        }
+      },
+      "mistralai/mistral-small-2603": {
+        "id": "mistralai/mistral-small-2603",
+        "name": "Mistral Small 4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 262144,
+          "output": 209715
+        },
+        "canonical_model_id": "mistral/mistral-small-2603"
+      },
+      "mistralai/mistral-medium-3": {
+        "id": "mistralai/mistral-medium-3",
+        "name": "Mistral Medium 3",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2,
+          "cache_read": 0.04
+        },
+        "limit": {
+          "context": 131072,
+          "output": 104857
+        }
+      },
+      "mistralai/voxtral-small-24b-2507": {
+        "id": "mistralai/voxtral-small-24b-2507",
+        "name": "Voxtral Small 24B 2507",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "audio", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.3,
+          "cache_read": 0.01
+        },
+        "limit": {
+          "context": 32768,
+          "output": 26214
+        },
+        "canonical_model_id": "mistral/voxtral-small-24b-2507"
+      },
+      "mistralai/mistral-large-2512": {
+        "id": "mistralai/mistral-large-2512",
+        "name": "Mistral Large 3",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.5,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 262144,
+          "output": 209715
+        },
+        "canonical_model_id": "mistral/mistral-large-2512"
+      },
+      "mistralai/mistral-large-2407": {
+        "id": "mistralai/mistral-large-2407",
+        "name": "Mistral Large 2407",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 131072,
+          "output": 104857
+        }
+      },
+      "mistralai/ministral-14b-2512": {
+        "id": "mistralai/ministral-14b-2512",
+        "name": "Ministral 3 14B 2512",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.2,
+          "cache_read": 0.02
+        },
+        "limit": {
+          "context": 262144,
+          "output": 209715
+        }
+      },
+      "mistralai/mistral-small-3.1-24b-instruct": {
+        "id": "mistralai/mistral-small-3.1-24b-instruct",
+        "name": "Mistral Small 3.1 24B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.351,
+          "output": 0.555
+        },
+        "limit": {
+          "context": 128000,
+          "output": 102400
+        }
+      },
+      "mistralai/ministral-3b-2512": {
+        "id": "mistralai/ministral-3b-2512",
+        "name": "Ministral 3 3B 2512",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.1,
+          "cache_read": 0.01
+        },
+        "limit": {
+          "context": 131072,
+          "output": 104857
+        }
+      },
+      "mistralai/mixtral-8x22b-instruct": {
+        "id": "mistralai/mixtral-8x22b-instruct",
+        "name": "Mixtral 8x22B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 65536,
+          "output": 52428
+        }
+      },
+      "mistralai/codestral-2508": {
+        "id": "mistralai/codestral-2508",
+        "name": "Codestral 2508",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 0.9,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 256000,
+          "output": 204800
+        }
+      },
+      "sakana/fugu-max": {
+        "id": "sakana/fugu-max",
+        "name": "Fugu Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        }
+      },
+      "sakana/fugu-ultra-v2": {
+        "id": "sakana/fugu-ultra-v2",
+        "name": "Fugu Ultra v2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        }
+      },
+      "sakana/fugu-ultra": {
+        "id": "sakana/fugu-ultra",
+        "name": "Fugu Ultra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "sakana/fugu-ultra"
+      },
+      "sakana/sakana-namazu": {
+        "id": "sakana/sakana-namazu",
+        "name": "Sakana Namazu",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "sakana/sakana-namazu"
+      },
+      "inclusionai/ling-3.0-flash-sante:free": {
+        "id": "inclusionai/ling-3.0-flash-sante:free",
+        "name": "Ling 3.0 Flash Sante (free)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "inclusionai/ling-3.0-flash": {
+        "id": "inclusionai/ling-3.0-flash",
+        "name": "Ling 3.0 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.021,
+          "output": 0.063,
+          "cache_read": 0.0042
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "inclusionai/ling-3.0-flash-vl": {
+        "id": "inclusionai/ling-3.0-flash-vl",
+        "name": "Ling 3.0 Flash VL",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.021,
+          "output": 0.0616,
+          "cache_read": 0.0042
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "inclusionai/ling-3.0-flash-fin": {
+        "id": "inclusionai/ling-3.0-flash-fin",
+        "name": "Ling 3.0 Flash Fin",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.18,
+          "cache_read": 0.012
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        }
+      },
+      "moonshotai/kimi-k3": {
+        "id": "moonshotai/kimi-k3",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 943718
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "moonshotai/kimi-k2.6": {
+        "id": "moonshotai/kimi-k2.6",
+        "name": "Kimi K2.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_details"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.65,
+          "output": 3.41,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.6"
+      },
+      "moonshotai/kimi-k2-thinking": {
+        "id": "moonshotai/kimi-k2-thinking",
+        "name": "Kimi K2 Thinking",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_details"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.5,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 262144,
+          "output": 98304
+        },
+        "canonical_model_id": "moonshotai/kimi-k2-thinking"
+      },
+      "moonshotai/kimi-k2.5": {
+        "id": "moonshotai/kimi-k2.5",
+        "name": "Kimi K2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_details"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.45,
+          "output": 2.25,
+          "cache_read": 0.07
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.5"
+      },
+      "moonshotai/kimi-k2-0905": {
+        "id": "moonshotai/kimi-k2-0905",
+        "name": "Kimi K2 0905",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.5
+        },
+        "limit": {
+          "context": 262144,
+          "output": 98304
+        }
+      },
+      "moonshotai/kimi-k2": {
+        "id": "moonshotai/kimi-k2",
+        "name": "Kimi K2 0711",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.57,
+          "output": 2.3
+        },
+        "limit": {
+          "context": 131072,
+          "output": 98304
+        }
+      },
+      "moonshotai/kimi-k2.7-code": {
+        "id": "moonshotai/kimi-k2.7-code",
+        "name": "Kimi K2.7 Code",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6712,
+          "output": 3.35,
+          "cache_read": 0.18
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code"
+      },
+      "rekaai/reka-flash-3": {
+        "id": "rekaai/reka-flash-3",
+        "name": "Reka Flash 3",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.2
+        },
+        "limit": {
+          "context": 65536,
+          "output": 58982
+        }
+      },
+      "rekaai/reka-edge": {
+        "id": "rekaai/reka-edge",
+        "name": "Reka Edge",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.1
+        },
+        "limit": {
+          "context": 16384,
+          "output": 14745
+        }
+      },
+      "nvidia/nemotron-3-nano-30b-a3b": {
+        "id": "nvidia/nemotron-3-nano-30b-a3b",
+        "name": "Nemotron 3 Nano 30B A3B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.2,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        },
+        "canonical_model_id": "nvidia/nemotron-3-nano-30b-a3b"
+      },
+      "nvidia/nemotron-3.5-content-safety:free": {
+        "id": "nvidia/nemotron-3.5-content-safety:free",
+        "name": "Nemotron 3.5 Content Safety (free)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        },
+        "canonical_model_id": "nvidia/nemotron-3.5-content-safety"
+      },
+      "nvidia/nemotron-3.5-lightning": {
+        "id": "nvidia/nemotron-3.5-lightning",
+        "name": "Nemotron 3.5 Lightning 30B A3B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.16,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "nvidia/nemotron-3.5-lightning"
+      },
+      "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free": {
+        "id": "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free",
+        "name": "Nemotron 3 Nano Omni (free)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 256000,
+          "output": 65536
+        },
+        "canonical_model_id": "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning"
+      },
+      "nvidia/nemotron-3-super-120b-a12b": {
+        "id": "nvidia/nemotron-3-super-120b-a12b",
+        "name": "Nemotron 3 Super 120B A12B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.08,
+          "output": 0.45
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        },
+        "canonical_model_id": "nvidia/nemotron-3-super-120b-a12b"
+      },
+      "nvidia/nemotron-3-ultra-550b-a55b:free": {
+        "id": "nvidia/nemotron-3-ultra-550b-a55b:free",
+        "name": "Nemotron 3 Ultra (free)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["medium", "high"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "nvidia/nemotron-3-ultra-550b-a55b"
+      },
+      "nvidia/nemotron-3-ultra-550b-a55b": {
+        "id": "nvidia/nemotron-3-ultra-550b-a55b",
+        "name": "Nemotron 3 Ultra 550B A55B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["medium", "high"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.4,
+          "cache_read": 0.12
+        },
+        "limit": {
+          "context": 262144,
+          "output": 182520
+        },
+        "canonical_model_id": "nvidia/nemotron-3-ultra-550b-a55b"
+      },
+      "nvidia/nemotron-3-super-120b-a12b:free": {
+        "id": "nvidia/nemotron-3-super-120b-a12b:free",
+        "name": "Nemotron 3 Super (free)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        },
+        "canonical_model_id": "nvidia/nemotron-3-super-120b-a12b"
+      },
+      "nvidia/nemotron-3.5-content-safety": {
+        "id": "nvidia/nemotron-3.5-content-safety",
+        "name": "Nemotron 3.5 Content Safety",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.2
+        },
+        "limit": {
+          "context": 131072,
+          "output": 117964
+        },
+        "canonical_model_id": "nvidia/nemotron-3.5-content-safety"
+      },
+      "nvidia/nemotron-3.5-lightning:free": {
+        "id": "nvidia/nemotron-3.5-lightning:free",
+        "name": "Nemotron 3.5 Lightning (free)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "nvidia/nemotron-3.5-lightning"
+      },
+      "xiaomi/mimo-v2.6-pro": {
+        "id": "xiaomi/mimo-v2.6-pro",
+        "name": "MiMo-V2.6-Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.435,
+          "output": 0.87,
+          "cache_read": 0.0036
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 131072
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.6-pro"
+      },
+      "xiaomi/mimo-v2.5": {
+        "id": "xiaomi/mimo-v2.5",
+        "name": "MiMo-V2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_details"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.0028
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 131072
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.5"
+      },
+      "xiaomi/mimo-v2.6-pro-ultraspeed": {
+        "id": "xiaomi/mimo-v2.6-pro-ultraspeed",
+        "name": "MiMo-V2.6-Pro-UltraSpeed",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4.35,
+          "output": 8.7,
+          "cache_read": 0.036
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.6-pro-ultraspeed"
+      },
+      "xiaomi/mimo-v2.5-pro": {
+        "id": "xiaomi/mimo-v2.5-pro",
+        "name": "MiMo-V2.5-Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.435,
+          "output": 0.87,
+          "cache_read": 0.0036
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 131072
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.5-pro"
+      },
+      "xiaomi/mimo-v2.6-flash": {
+        "id": "xiaomi/mimo-v2.6-flash",
+        "name": "MiMo-V2.6-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.0028
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 131072
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.6-flash"
+      },
+      "undi95/remm-slerp-l2-13b": {
+        "id": "undi95/remm-slerp-l2-13b",
+        "name": "ReMM SLERP 13B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.35,
+          "output": 0.65
+        },
+        "limit": {
+          "context": 6144,
+          "output": 5529
+        }
+      },
+      "gryphe/mythomax-l2-13b": {
+        "id": "gryphe/mythomax-l2-13b",
+        "name": "MythoMax 13B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.08,
+          "output": 0.11
+        },
+        "limit": {
+          "context": 8192,
+          "output": 3686
+        }
+      },
+      "minimax/minimax-m2.5": {
+        "id": "minimax/minimax-m2.5",
+        "name": "MiniMax-M2.5",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_details"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.27,
+          "output": 1.08,
+          "cache_read": 0.027
+        },
+        "limit": {
+          "context": 204800,
+          "output": 128000
+        },
+        "canonical_model_id": "minimax/MiniMax-M2.5"
+      },
+      "minimax/minimax-01": {
+        "id": "minimax/minimax-01",
+        "name": "MiniMax-01",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.1
+        },
+        "limit": {
+          "context": 1000192,
+          "output": 40000
+        }
+      },
+      "minimax/minimax-m2-her": {
+        "id": "minimax/minimax-m2-her",
+        "name": "MiniMax-M2 Her",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 65536,
+          "output": 2048
+        },
+        "canonical_model_id": "minimax/MiniMax-M2-Her"
+      },
+      "minimax/minimax-m2.7": {
+        "id": "minimax/minimax-m2.7",
+        "name": "MiniMax-M2.7",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.21,
+          "output": 0.84,
+          "cache_read": 0.042
+        },
+        "limit": {
+          "context": 204800,
+          "output": 176947
+        },
+        "canonical_model_id": "minimax/MiniMax-M2.7"
+      },
+      "minimax/minimax-m1": {
+        "id": "minimax/minimax-m1",
+        "name": "MiniMax M1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 40000
+        }
+      },
+      "minimax/minimax-m3": {
+        "id": "minimax/minimax-m3",
+        "name": "MiniMax-M3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 512000
+        },
+        "canonical_model_id": "minimax/MiniMax-M3"
+      },
+      "minimax/minimax-m2.1": {
+        "id": "minimax/minimax-m2.1",
+        "name": "MiniMax-M2.1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_details"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "canonical_model_id": "minimax/MiniMax-M2.1"
+      },
+      "minimax/minimax-m2": {
+        "id": "minimax/minimax-m2",
+        "name": "MiniMax-M2",
+        "reasoning": true,
+        "reasoning_options": [],
+        "interleaved": {
+          "field": "reasoning_details"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 204800,
+          "output": 176947
+        },
+        "canonical_model_id": "minimax/MiniMax-M2"
+      },
+      "mancer/weaver": {
+        "id": "mancer/weaver",
+        "name": "Weaver (alpha)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 0.75
+        },
+        "limit": {
+          "context": 8000,
+          "output": 6000
+        }
+      },
+      "stepfun/step-3.5-flash": {
+        "id": "stepfun/step-3.5-flash",
+        "name": "Step 3.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "stepfun/step-3.5-flash"
+      },
+      "stepfun/step-3.7-flash": {
+        "id": "stepfun/step-3.7-flash",
+        "name": "Step 3.7 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.15,
+          "cache_read": 0.04
+        },
+        "limit": {
+          "context": 262144,
+          "output": 230400
+        },
+        "canonical_model_id": "stepfun/step-3.7-flash"
+      },
+      "dots-studio/dots-3-note-preview:free": {
+        "id": "dots-studio/dots-3-note-preview:free",
+        "name": "Dots3-Note Preview (free)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 512000,
+          "output": 460800
+        }
+      },
+      "inception/mercury-2.5": {
+        "id": "inception/mercury-2.5",
+        "name": "Mercury 2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.04,
+          "output": 0.15,
+          "cache_read": 0.004
+        },
+        "limit": {
+          "context": 260000,
+          "output": 65536
+        }
+      },
+      "inception/mercury-2": {
+        "id": "inception/mercury-2",
+        "name": "Mercury 2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 0.75,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 128000,
+          "output": 50000
+        }
+      },
+      "amazon/nova-lite-v1": {
+        "id": "amazon/nova-lite-v1",
+        "name": "Nova Lite 1.0",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.24
+        },
+        "limit": {
+          "context": 300000,
+          "output": 5120
+        }
+      },
+      "amazon/nova-2-lite-v1": {
+        "id": "amazon/nova-2-lite-v1",
+        "name": "Nova 2 Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65535
+        }
+      },
+      "amazon/nova-pro-v1": {
+        "id": "amazon/nova-pro-v1",
+        "name": "Nova Pro 1.0",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.8,
+          "output": 3.2
+        },
+        "limit": {
+          "context": 300000,
+          "output": 5120
+        }
+      },
+      "amazon/nova-premier-v1": {
+        "id": "amazon/nova-premier-v1",
+        "name": "Nova Premier 1.0",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 12.5,
+          "cache_read": 0.625
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 32000
+        }
+      },
+      "amazon/nova-micro-v1": {
+        "id": "amazon/nova-micro-v1",
+        "name": "Nova Micro 1.0",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.035,
+          "output": 0.14
+        },
+        "limit": {
+          "context": 128000,
+          "output": 5120
+        }
+      },
+      "relace/relace-search": {
+        "id": "relace/relace-search",
+        "name": "Relace Search",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 3
+        },
+        "limit": {
+          "context": 256000,
+          "output": 128000
+        }
+      },
+      "relace/relace-apply-3": {
+        "id": "relace/relace-apply-3",
+        "name": "Relace Apply 3",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.85,
+          "output": 1.25
+        },
+        "limit": {
+          "context": 256000,
+          "output": 128000
+        }
+      },
+      "aion-labs/aion-2.0": {
+        "id": "aion-labs/aion-2.0",
+        "name": "Aion-2.0",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.8,
+          "output": 1.6,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "aion-labs/aion-rp-llama-3.1-8b": {
+        "id": "aion-labs/aion-rp-llama-3.1-8b",
+        "name": "Aion-RP 1.0 (8B)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.8,
+          "output": 1.6
+        },
+        "limit": {
+          "context": 32768,
+          "output": 29491
+        }
+      },
+      "aion-labs/aion-3.0": {
+        "id": "aion-labs/aion-3.0",
+        "name": "Aion-3.0",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 6,
+          "cache_read": 0.75
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "aion-labs/aion-3.5": {
+        "id": "aion-labs/aion-3.5",
+        "name": "Aion 3.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 6,
+          "cache_read": 0.75
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "aion-labs/aion-3.5-mini": {
+        "id": "aion-labs/aion-3.5-mini",
+        "name": "Aion 3.5 Mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.7,
+          "output": 1.4,
+          "cache_read": 0.18
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "aion-labs/aion-3.0-mini": {
+        "id": "aion-labs/aion-3.0-mini",
+        "name": "Aion-3.0-Mini",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.7,
+          "output": 1.4,
+          "cache_read": 0.18
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "qwen/qwen3-235b-a22b-2507": {
+        "id": "qwen/qwen3-235b-a22b-2507",
+        "name": "Qwen3 235B A22B Instruct 2507",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.0875,
+          "output": 0.35,
+          "cache_read": 0.0175
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        }
+      },
+      "qwen/qwen3-vl-235b-a22b-instruct": {
+        "id": "qwen/qwen3-vl-235b-a22b-instruct",
+        "name": "Qwen3 VL 235B A22B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.21,
+          "output": 1.9,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "alibaba/qwen3-vl-235b-a22b-instruct"
+      },
+      "qwen/qwen3.7-max": {
+        "id": "qwen/qwen3.7-max",
+        "name": "Qwen3.7 Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.475,
+          "output": 4.425,
+          "cache_read": 0.295,
+          "cache_write": 1.84375
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.7-max"
+      },
+      "qwen/qwen3.8-27b": {
+        "id": "qwen/qwen3.8-27b",
+        "name": "Qwen3.8 27B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.0249,
+          "output": 4.35,
+          "cache_read": 0.0199
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 235929
+        },
+        "canonical_model_id": "alibaba/qwen3.8-27b"
+      },
+      "qwen/qwen3-vl-235b-a22b-thinking": {
+        "id": "qwen/qwen3-vl-235b-a22b-thinking",
+        "name": "Qwen3 VL 235B A22B Thinking",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 4
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "alibaba/qwen3-vl-235b-a22b-thinking"
+      },
+      "qwen/qwen3.8-2.4t-a95b": {
+        "id": "qwen/qwen3.8-2.4t-a95b",
+        "name": "Qwen3.8 2.4T A95B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-2.4t-a95b"
+      },
+      "qwen/qwen3.5-27b": {
+        "id": "qwen/qwen3.5-27b",
+        "name": "Qwen3.5 27B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.195,
+          "output": 1.56
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.5-27b"
+      },
+      "qwen/qwen3-next-80b-a3b-thinking": {
+        "id": "qwen/qwen3-next-80b-a3b-thinking",
+        "name": "Qwen3-Next 80B-A3B (Thinking)",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        },
+        "canonical_model_id": "alibaba/qwen3-next-80b-a3b-thinking"
+      },
+      "qwen/qwen3-coder-next": {
+        "id": "qwen/qwen3-coder-next",
+        "name": "Qwen3 Coder Next",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.12,
+          "output": 0.8,
+          "cache_read": 0.07
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        },
+        "canonical_model_id": "alibaba/qwen3-coder-next"
+      },
+      "qwen/qwen3-coder": {
+        "id": "qwen/qwen3-coder",
+        "name": "Qwen3 Coder 480B A35B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "qwen/qwen3-32b": {
+        "id": "qwen/qwen3-32b",
+        "name": "Qwen3 32B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.08,
+          "output": 0.28
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        },
+        "canonical_model_id": "alibaba/qwen3-32b"
+      },
+      "qwen/qwen-plus": {
+        "id": "qwen/qwen-plus",
+        "name": "Qwen Plus",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.26,
+          "output": 0.78,
+          "cache_read": 0.052,
+          "cache_write": 0.325
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 32768
+        },
+        "canonical_model_id": "alibaba/qwen-plus"
+      },
+      "qwen/qwen3.7-flash": {
+        "id": "qwen/qwen3.7-flash",
+        "name": "Qwen3.7 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.03,
+          "output": 0.13,
+          "cache_read": 0.006,
+          "cache_write": 0.038
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.7-flash"
+      },
+      "qwen/qwen3-max": {
+        "id": "qwen/qwen3-max",
+        "name": "Qwen3 Max",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.78,
+          "output": 3.9,
+          "cache_read": 0.156,
+          "cache_write": 0.975
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3-max"
+      },
+      "qwen/qwen3-coder-30b-a3b-instruct": {
+        "id": "qwen/qwen3-coder-30b-a3b-instruct",
+        "name": "Qwen3-Coder 30B-A3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.28
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        },
+        "canonical_model_id": "alibaba/qwen3-coder-30b-a3b-instruct"
+      },
+      "qwen/qwen3.8-omni-flash": {
+        "id": "qwen/qwen3.8-omni-flash",
+        "name": "Qwen3.8 Omni Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.47,
+          "cache_read": 0.016
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-omni-flash"
+      },
+      "qwen/qwen3-vl-30b-a3b-instruct": {
+        "id": "qwen/qwen3-vl-30b-a3b-instruct",
+        "name": "Qwen3 VL 30B A3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6
+        },
+        "limit": {
+          "context": 262144,
+          "output": 16384
+        }
+      },
+      "qwen/qwen3-235b-a22b-thinking-2507": {
+        "id": "qwen/qwen3-235b-a22b-thinking-2507",
+        "name": "Qwen3 235B A22B Thinking 2507",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.23,
+          "output": 2.3
+        },
+        "limit": {
+          "context": 131072,
+          "output": 117964
+        }
+      },
+      "qwen/qwen3-235b-a22b": {
+        "id": "qwen/qwen3-235b-a22b",
+        "name": "Qwen3 235B-A22B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.455,
+          "output": 1.82
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        },
+        "canonical_model_id": "alibaba/qwen3-235b-a22b"
+      },
+      "qwen/qwen3.5-122b-a10b": {
+        "id": "qwen/qwen3.5-122b-a10b",
+        "name": "Qwen3.5 122B-A10B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.26,
+          "output": 2.08
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.5-122b-a10b"
+      },
+      "qwen/qwen-plus-2025-07-28": {
+        "id": "qwen/qwen-plus-2025-07-28",
+        "name": "Qwen Plus 0728",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.26,
+          "output": 0.78
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 32768
+        }
+      },
+      "qwen/qwen3.6-35b-a3b": {
+        "id": "qwen/qwen3.6-35b-a3b",
+        "name": "Qwen3.6 35B-A3B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 1,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        },
+        "canonical_model_id": "alibaba/qwen3.6-35b-a3b"
+      },
+      "qwen/qwen3-next-80b-a3b-instruct": {
+        "id": "qwen/qwen3-next-80b-a3b-instruct",
+        "name": "Qwen3-Next 80B-A3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 1.1,
+          "cache_read": 0.07
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        },
+        "canonical_model_id": "alibaba/qwen3-next-80b-a3b-instruct"
+      },
+      "qwen/qwen3-vl-30b-a3b-thinking": {
+        "id": "qwen/qwen3-vl-30b-a3b-thinking",
+        "name": "Qwen3 VL 30B A3B Thinking",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 2.4
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "qwen/qwen3.6-flash": {
+        "id": "qwen/qwen3.6-flash",
+        "name": "Qwen3.6 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1875,
+          "output": 1.125,
+          "cache_write": 0.234375
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.6-flash"
+      },
+      "qwen/qwen3-coder-flash": {
+        "id": "qwen/qwen3-coder-flash",
+        "name": "Qwen3 Coder Flash",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.195,
+          "output": 0.975,
+          "cache_read": 0.039,
+          "cache_write": 0.24375
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3-coder-flash"
+      },
+      "qwen/qwen-2.5-coder-32b-instruct": {
+        "id": "qwen/qwen-2.5-coder-32b-instruct",
+        "name": "Qwen2.5 Coder 32B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.66,
+          "output": 1
+        },
+        "limit": {
+          "context": 32768,
+          "output": 29491
+        }
+      },
+      "qwen/qwen3.5-flash-02-23": {
+        "id": "qwen/qwen3.5-flash-02-23",
+        "name": "Qwen3.5-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.065,
+          "output": 0.26
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        }
+      },
+      "qwen/qwen3-max-thinking": {
+        "id": "qwen/qwen3-max-thinking",
+        "name": "Qwen3 Max Thinking",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.78,
+          "output": 3.9
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "qwen/qwen3-coder-plus": {
+        "id": "qwen/qwen3-coder-plus",
+        "name": "Qwen3 Coder Plus",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.65,
+          "output": 3.25,
+          "cache_read": 0.13,
+          "cache_write": 0.8125
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3-coder-plus"
+      },
+      "qwen/qwen3.5-9b": {
+        "id": "qwen/qwen3.5-9b",
+        "name": "Qwen3.5 9B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.15
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "alibaba/qwen3.5-9b"
+      },
+      "qwen/qwen3.8-max-prime": {
+        "id": "qwen/qwen3.8-max-prime",
+        "name": "Qwen 3.8 Max Prime",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 12,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-max-prime"
+      },
+      "qwen/qwen3.5-plus-20260420": {
+        "id": "qwen/qwen3.5-plus-20260420",
+        "name": "Qwen3.5 Plus 2026-04-20",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.8,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        }
+      },
+      "qwen/qwen3.8-flash": {
+        "id": "qwen/qwen3.8-flash",
+        "name": "Qwen3.8 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.47,
+          "cache_read": 0.016,
+          "cache_write": 0.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-flash"
+      },
+      "qwen/qwen3.5-35b-a3b": {
+        "id": "qwen/qwen3.5-35b-a3b",
+        "name": "Qwen3.5 35B-A3B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1625,
+          "output": 1.3
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.5-35b-a3b"
+      },
+      "qwen/qwen3.6-max-preview": {
+        "id": "qwen/qwen3.6-max-preview",
+        "name": "Qwen3.6 Max Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.027,
+          "output": 6.162,
+          "cache_write": 1.28375
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.6-max-preview"
+      },
+      "qwen/qwen3-30b-a3b": {
+        "id": "qwen/qwen3-30b-a3b",
+        "name": "Qwen3 30B A3B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.13,
+          "output": 0.52
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        },
+        "canonical_model_id": "alibaba/qwen3-30b-a3b"
+      },
+      "qwen/qwen3.5-397b-a17b": {
+        "id": "qwen/qwen3.5-397b-a17b",
+        "name": "Qwen3.5 397B-A17B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.55,
+          "output": 3.5,
+          "cache_read": 0.225
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        },
+        "canonical_model_id": "alibaba/qwen3.5-397b-a17b"
+      },
+      "qwen/qwen3-8b": {
+        "id": "qwen/qwen3-8b",
+        "name": "Qwen3 8B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.117,
+          "output": 0.455
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        }
+      },
+      "qwen/qwen3-vl-32b-instruct": {
+        "id": "qwen/qwen3-vl-32b-instruct",
+        "name": "Qwen3 VL 32B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.104,
+          "output": 0.416
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "qwen/qwen3-vl-8b-instruct": {
+        "id": "qwen/qwen3-vl-8b-instruct",
+        "name": "Qwen3 VL 8B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.117,
+          "output": 0.455
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "qwen/qwen3-30b-a3b-instruct-2507": {
+        "id": "qwen/qwen3-30b-a3b-instruct-2507",
+        "name": "Qwen3 30B A3B Instruct 2507",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.04815,
+          "output": 0.19305
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32000
+        }
+      },
+      "qwen/qwen2.5-vl-72b-instruct": {
+        "id": "qwen/qwen2.5-vl-72b-instruct",
+        "name": "Qwen2.5 VL 72B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.8,
+          "output": 1,
+          "cache_read": 0.4
+        },
+        "limit": {
+          "context": 128000,
+          "output": 115200
+        }
+      },
+      "qwen/qwen-2.5-7b-instruct": {
+        "id": "qwen/qwen-2.5-7b-instruct",
+        "name": "Qwen2.5 7B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.2
+        },
+        "limit": {
+          "context": 32768,
+          "output": 29491
+        }
+      },
+      "qwen/qwen3.5-plus-02-15": {
+        "id": "qwen/qwen3.5-plus-02-15",
+        "name": "Qwen3.5 Plus 2026-02-15",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.26,
+          "output": 1.56
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        }
+      },
+      "qwen/qwen-2.5-72b-instruct": {
+        "id": "qwen/qwen-2.5-72b-instruct",
+        "name": "Qwen2.5 72B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.36,
+          "output": 0.4
+        },
+        "limit": {
+          "context": 32768,
+          "output": 16384
+        }
+      },
+      "qwen/qwen3-30b-a3b-thinking-2507": {
+        "id": "qwen/qwen3-30b-a3b-thinking-2507",
+        "name": "Qwen3 30B A3B Thinking 2507",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 2.4
+        },
+        "limit": {
+          "context": 81920,
+          "output": 32768
+        }
+      },
+      "qwen/qwen3.6-27b": {
+        "id": "qwen/qwen3.6-27b",
+        "name": "Qwen3.6 27B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.32,
+          "output": 3.2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 81920
+        },
+        "canonical_model_id": "alibaba/qwen3.6-27b"
+      },
+      "qwen/qwen3.6-plus": {
+        "id": "qwen/qwen3.6-plus",
+        "name": "Qwen3.6 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.325,
+          "output": 1.95,
+          "cache_write": 0.40625
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.6-plus"
+      },
+      "qwen/qwen3-14b": {
+        "id": "qwen/qwen3-14b",
+        "name": "Qwen3 14B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.12,
+          "output": 0.24
+        },
+        "limit": {
+          "context": 131072,
+          "output": 16384
+        }
+      },
+      "qwen/qwen3-vl-8b-thinking": {
+        "id": "qwen/qwen3-vl-8b-thinking",
+        "name": "Qwen3 VL 8B Thinking",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.18,
+          "output": 2.1
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "qwen/qwen3.7-plus": {
+        "id": "qwen/qwen3.7-plus",
+        "name": "Qwen3.7 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.32,
+          "output": 1.28,
+          "cache_read": 0.064,
+          "cache_write": 0.4
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.7-plus"
+      },
+      "qwen/qwen3.8-27b:free": {
+        "id": "qwen/qwen3.8-27b:free",
+        "name": "Qwen3.8 27B (free)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 235929
+        },
+        "canonical_model_id": "alibaba/qwen3.8-27b"
+      },
+      "qwen/qwen3.8-max-0902": {
+        "id": "qwen/qwen3.8-max-0902",
+        "name": "Qwen3.8 Max 0902",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.25,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-max-0902"
+      },
+      "morph/morph-v3-large": {
+        "id": "morph/morph-v3-large",
+        "name": "Morph V3 Large",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.9,
+          "output": 1.9
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        }
+      },
+      "morph/morph-v3-fast": {
+        "id": "morph/morph-v3-fast",
+        "name": "Morph V3 Fast",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.8,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 81920,
+          "output": 38000
+        }
+      },
+      "openai/gpt-5.4": {
+        "id": "openai/gpt-5.4",
+        "name": "GPT-5.4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 15,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4"
+      },
+      "openai/gpt-5.4-image-2": {
+        "id": "openai/gpt-5.4-image-2",
+        "name": "GPT-5.4 Image 2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["image", "text", "pdf"],
+          "output": ["image", "text"]
+        },
+        "cost": {
+          "input": 8,
+          "output": 15,
+          "cache_read": 2
+        },
+        "limit": {
+          "context": 272000,
+          "output": 128000
+        }
+      },
+      "openai/gpt-5.4-pro": {
+        "id": "openai/gpt-5.4-pro",
+        "name": "GPT-5.4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 30,
+          "output": 180
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4-pro"
+      },
+      "openai/gpt-audio": {
+        "id": "openai/gpt-audio",
+        "name": "GPT Audio",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        }
+      },
+      "openai/gpt-3.5-turbo": {
+        "id": "openai/gpt-3.5-turbo",
+        "name": "GPT-3.5-turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.5
+        },
+        "limit": {
+          "context": 16385,
+          "output": 4096
+        },
+        "canonical_model_id": "openai/gpt-3.5-turbo"
+      },
+      "openai/gpt-6-astra-pro": {
+        "id": "openai/gpt-6-astra-pro",
+        "name": "GPT-6 Astra Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["pdf", "image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        }
+      },
+      "openai/gpt-5.5-pro": {
+        "id": "openai/gpt-5.5-pro",
+        "name": "GPT-5.5 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 30,
+          "output": 180
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.5-pro"
+      },
+      "openai/gpt-5.4-nano": {
+        "id": "openai/gpt-5.4-nano",
+        "name": "GPT-5.4 nano",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["pdf", "image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.25,
+          "cache_read": 0.02
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4-nano"
+      },
+      "openai/gpt-4o-2024-05-13": {
+        "id": "openai/gpt-4o-2024-05-13",
+        "name": "GPT-4o (2024-05-13)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 15
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "canonical_model_id": "openai/gpt-4o-2024-05-13"
+      },
+      "openai/gpt-4o-mini-2024-07-18": {
+        "id": "openai/gpt-4o-mini-2024-07-18",
+        "name": "GPT-4o-mini (2024-07-18)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        }
+      },
+      "openai/gpt-5.2-codex": {
+        "id": "openai/gpt-5.2-codex",
+        "name": "GPT-5.2 Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.2-codex"
+      },
+      "openai/gpt-5.1-codex": {
+        "id": "openai/gpt-5.1-codex",
+        "name": "GPT-5.1 Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.13
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.1-codex"
+      },
+      "openai/gpt-4o": {
+        "id": "openai/gpt-4o",
+        "name": "GPT-4o",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "openai/gpt-4o"
+      },
+      "openai/gpt-chat-latest": {
+        "id": "openai/gpt-chat-latest",
+        "name": "GPT Chat Latest",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "openai/gpt-audio-mini": {
+        "id": "openai/gpt-audio-mini",
+        "name": "GPT Audio Mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.4
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        }
+      },
+      "openai/gpt-5.6-sol-pro": {
+        "id": "openai/gpt-5.6-sol-pro",
+        "name": "GPT-5.6 Sol Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.4,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-sol"
+      },
+      "openai/gpt-5-mini": {
+        "id": "openai/gpt-5-mini",
+        "name": "GPT-5 Mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5-mini"
+      },
+      "openai/gpt-5.2-pro": {
+        "id": "openai/gpt-5.2-pro",
+        "name": "GPT-5.2 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["image", "text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 21,
+          "output": 168
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.2-pro"
+      },
+      "openai/o4-mini": {
+        "id": "openai/o4-mini",
+        "name": "o4-mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["image", "text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 4.4,
+          "cache_read": 0.275
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "canonical_model_id": "openai/o4-mini"
+      },
+      "openai/o3-mini": {
+        "id": "openai/o3-mini",
+        "name": "o3-mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 4.4,
+          "cache_read": 0.55
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "canonical_model_id": "openai/o3-mini"
+      },
+      "openai/gpt-4": {
+        "id": "openai/gpt-4",
+        "name": "GPT-4",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 30,
+          "output": 60
+        },
+        "limit": {
+          "context": 8191,
+          "output": 4096
+        },
+        "canonical_model_id": "openai/gpt-4"
+      },
+      "openai/gpt-5.3-codex": {
+        "id": "openai/gpt-5.3-codex",
+        "name": "GPT-5.3 Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.3-codex"
+      },
+      "openai/gpt-4.1-nano": {
+        "id": "openai/gpt-4.1-nano",
+        "name": "GPT-4.1 nano",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.4,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 1047576,
+          "output": 32768
+        },
+        "canonical_model_id": "openai/gpt-4.1-nano"
+      },
+      "openai/gpt-5-nano": {
+        "id": "openai/gpt-5-nano",
+        "name": "GPT-5 Nano",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.4,
+          "cache_read": 0.005
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5-nano"
+      },
+      "openai/o1": {
+        "id": "openai/o1",
+        "name": "o1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 60,
+          "cache_read": 7.5
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "canonical_model_id": "openai/o1"
+      },
+      "openai/gpt-5-pro": {
+        "id": "openai/gpt-5-pro",
+        "name": "GPT-5 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["image", "text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 120
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5-pro"
+      },
+      "openai/gpt-3.5-turbo-instruct": {
+        "id": "openai/gpt-3.5-turbo-instruct",
+        "name": "GPT-3.5 Turbo Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 2
+        },
+        "limit": {
+          "context": 4095,
+          "output": 3685
+        }
+      },
+      "openai/gpt-6.1-sol": {
+        "id": "openai/gpt-6.1-sol",
+        "name": "GPT-6.1 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.1,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6.1-sol"
+      },
+      "openai/gpt-4o-2024-08-06": {
+        "id": "openai/gpt-4o-2024-08-06",
+        "name": "GPT-4o (2024-08-06)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "openai/gpt-4o-2024-08-06"
+      },
+      "openai/gpt-6-astra": {
+        "id": "openai/gpt-6-astra",
+        "name": "GPT-6 Astra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-astra"
+      },
+      "openai/gpt-5.6-luna-pro": {
+        "id": "openai/gpt-5.6-luna-pro",
+        "name": "GPT-5.6 Luna Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.2,
+          "cache_read": 0.02,
+          "cache_write": 0.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-luna"
+      },
+      "openai/gpt-5.1": {
+        "id": "openai/gpt-5.1",
+        "name": "GPT-5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["image", "text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.1"
+      },
+      "openai/gpt-5-image-mini": {
+        "id": "openai/gpt-5-image-mini",
+        "name": "GPT-5 Image Mini",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["pdf", "image", "text"],
+          "output": ["image", "text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 2,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "openai/gpt-4o-mini": {
+        "id": "openai/gpt-4o-mini",
+        "name": "GPT-4o mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "openai/gpt-4o-mini"
+      },
+      "openai/o3-pro": {
+        "id": "openai/o3-pro",
+        "name": "o3-pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "pdf", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 20,
+          "output": 80
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "canonical_model_id": "openai/o3-pro"
+      },
+      "openai/gpt-oss-20b": {
+        "id": "openai/gpt-oss-20b",
+        "name": "GPT OSS 20B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.018,
+          "output": 0.09,
+          "cache_read": 0.009
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "openai/gpt-oss-20b"
+      },
+      "openai/gpt-oss-safeguard-20b": {
+        "id": "openai/gpt-oss-safeguard-20b",
+        "name": "GPT OSS Safeguard 20B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.075,
+          "output": 0.3,
+          "cache_read": 0.0375
+        },
+        "limit": {
+          "context": 131072,
+          "output": 65536
+        },
+        "canonical_model_id": "openai/gpt-oss-safeguard-20b"
+      },
+      "openai/o3-mini-high": {
+        "id": "openai/o3-mini-high",
+        "name": "o3 Mini High",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 4.4,
+          "cache_read": 0.55
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        }
+      },
+      "openai/gpt-3.5-turbo-16k": {
+        "id": "openai/gpt-3.5-turbo-16k",
+        "name": "GPT-3.5 Turbo 16k",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 4
+        },
+        "limit": {
+          "context": 16385,
+          "output": 4096
+        }
+      },
+      "openai/gpt-5.2-chat": {
+        "id": "openai/gpt-5.2-chat",
+        "name": "GPT-5.2 Chat",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["pdf", "image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 128000,
+          "output": 32000
+        }
+      },
+      "openai/gpt-6-sol-pro": {
+        "id": "openai/gpt-6-sol-pro",
+        "name": "GPT-6 Sol Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["pdf", "image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        }
+      },
+      "openai/gpt-5-image": {
+        "id": "openai/gpt-5-image",
+        "name": "GPT-5 Image",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["image", "text", "pdf"],
+          "output": ["image", "text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 10,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "openai/gpt-5.4-mini": {
+        "id": "openai/gpt-5.4-mini",
+        "name": "GPT-5.4 mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["pdf", "image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 4.5,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4-mini"
+      },
+      "openai/gpt-5.6-luna": {
+        "id": "openai/gpt-5.6-luna",
+        "name": "GPT-5.6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.2,
+          "cache_read": 0.02,
+          "cache_write": 0.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-luna"
+      },
+      "openai/gpt-5.1-codex-max": {
+        "id": "openai/gpt-5.1-codex-max",
+        "name": "GPT-5.1 Codex Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.1-codex-max"
+      },
+      "openai/gpt-5.2": {
+        "id": "openai/gpt-5.2",
+        "name": "GPT-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["pdf", "image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.2"
+      },
+      "openai/gpt-5.5": {
+        "id": "openai/gpt-5.5",
+        "name": "GPT-5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.5"
+      },
+      "openai/gpt-4.1": {
+        "id": "openai/gpt-4.1",
+        "name": "GPT-4.1",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 8,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1047576,
+          "output": 32768
+        },
+        "canonical_model_id": "openai/gpt-4.1"
+      },
+      "openai/gpt-4o-2024-11-20": {
+        "id": "openai/gpt-4o-2024-11-20",
+        "name": "GPT-4o (2024-11-20)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "openai/gpt-4o-2024-11-20"
+      },
+      "openai/gpt-3.5-turbo-0613": {
+        "id": "openai/gpt-3.5-turbo-0613",
+        "name": "GPT-3.5 Turbo (older v0613)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 2
+        },
+        "limit": {
+          "context": 4095,
+          "output": 3685
+        }
+      },
+      "openai/gpt-4.1-mini": {
+        "id": "openai/gpt-4.1-mini",
+        "name": "GPT-4.1 mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 1.6,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 1047576,
+          "output": 32768
+        },
+        "canonical_model_id": "openai/gpt-4.1-mini"
+      },
+      "openai/gpt-5.6-terra-pro": {
+        "id": "openai/gpt-5.6-terra-pro",
+        "name": "GPT-5.6 Terra Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-terra"
+      },
+      "openai/gpt-6-luna": {
+        "id": "openai/gpt-6-luna",
+        "name": "GPT-6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.5,
+          "cache_read": 0.01,
+          "cache_write": 0.125
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-luna"
+      },
+      "openai/gpt-6.1-sol-pro": {
+        "id": "openai/gpt-6.1-sol-pro",
+        "name": "GPT-6.1 Sol Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["pdf", "image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.1,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        }
+      },
+      "openai/o4-mini-high": {
+        "id": "openai/o4-mini-high",
+        "name": "o4 Mini High",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["image", "text", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 4.4,
+          "cache_read": 0.275
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        }
+      },
+      "openai/gpt-6-luna-pro": {
+        "id": "openai/gpt-6-luna-pro",
+        "name": "GPT-6 Luna Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["pdf", "image", "text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.5,
+          "cache_read": 0.01,
+          "cache_write": 0.125
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        }
+      },
+      "openai/gpt-5.6-terra": {
+        "id": "openai/gpt-5.6-terra",
+        "name": "GPT-5.6 Terra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-terra"
+      },
+      "openai/gpt-4-turbo": {
+        "id": "openai/gpt-4-turbo",
+        "name": "GPT-4 Turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 30
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "canonical_model_id": "openai/gpt-4-turbo"
+      },
+      "openai/gpt-oss-120b": {
+        "id": "openai/gpt-oss-120b",
+        "name": "GPT OSS 120B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.037,
+          "output": 0.17
+        },
+        "limit": {
+          "context": 131072,
+          "output": 117964
+        },
+        "canonical_model_id": "openai/gpt-oss-120b"
+      },
+      "openai/gpt-5.1-codex-mini": {
+        "id": "openai/gpt-5.1-codex-mini",
+        "name": "GPT-5.1 Codex mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.1-codex-mini"
+      },
+      "openai/o3": {
+        "id": "openai/o3",
+        "name": "o3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 8,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "canonical_model_id": "openai/o3"
+      },
+      "openai/gpt-5": {
+        "id": "openai/gpt-5",
+        "name": "GPT-5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5"
+      },
+      "openai/gpt-5.6-sol": {
+        "id": "openai/gpt-5.6-sol",
+        "name": "GPT-5.6 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-sol"
+      },
+      "openai/gpt-6-sol": {
+        "id": "openai/gpt-6-sol",
+        "name": "GPT-6 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-sol"
+      },
+      "openai/o1-pro": {
+        "id": "openai/o1-pro",
+        "name": "o1-pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 150,
+          "output": 600
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "canonical_model_id": "openai/o1-pro"
+      },
+      "microsoft/phi-4": {
+        "id": "microsoft/phi-4",
+        "name": "Phi 4",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.14
+        },
+        "limit": {
+          "context": 16384,
+          "output": 14745
+        }
+      },
+      "microsoft/wizardlm-2-8x22b": {
+        "id": "microsoft/wizardlm-2-8x22b",
+        "name": "WizardLM-2 8x22B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.62,
+          "output": 0.62
+        },
+        "limit": {
+          "context": 65535,
+          "output": 8000
+        }
+      }
+    }
+  },
+  "togetherai": {
+    "id": "togetherai",
+    "name": "Together AI",
+    "env": ["TOGETHER_API_KEY"],
+    "npm": "@ai-sdk/togetherai",
+    "models": {
+      "meta-llama/Llama-3.3-70B-Instruct-Turbo": {
+        "id": "meta-llama/Llama-3.3-70B-Instruct-Turbo",
+        "name": "Llama 3.3 70B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.04,
+          "output": 1.04
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        }
+      },
+      "meta-llama/Meta-Llama-3-8B-Instruct-Lite": {
+        "id": "meta-llama/Meta-Llama-3-8B-Instruct-Lite",
+        "name": "Meta Llama 3 8B Instruct Lite",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.14
+        },
+        "limit": {
+          "context": 8192,
+          "output": 8192
+        }
+      },
+      "pearl-ai/gemma-4-31b-it": {
+        "id": "pearl-ai/gemma-4-31b-it",
+        "name": "Pearl AI Gemma 4 31B Instruct",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.28,
+          "output": 0.86
+        },
+        "limit": {
+          "context": 32000,
+          "output": 32000
+        }
+      },
+      "deepcogito/cogito-v2-1-671b": {
+        "id": "deepcogito/cogito-v2-1-671b",
+        "name": "Cogito v2.1 671B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 1.25
+        },
+        "limit": {
+          "context": 163840,
+          "output": 163840
+        }
+      },
+      "thinkingmachines/Inkling": {
+        "id": "thinkingmachines/Inkling",
+        "name": "Inkling",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["max", "xhigh", "high", "medium", "low", "none"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 4.05,
+          "cache_read": 0.17
+        },
+        "limit": {
+          "context": 524288,
+          "output": 131072
+        },
+        "canonical_model_id": "thinkingmachines/inkling"
+      },
+      "essentialai/Rnj-1-Instruct": {
+        "id": "essentialai/Rnj-1-Instruct",
+        "name": "Rnj-1 Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.15
+        },
+        "limit": {
+          "context": 32768,
+          "output": 32768
+        },
+        "status": "deprecated"
+      },
+      "google/gemma-3n-E4B-it": {
+        "id": "google/gemma-3n-E4B-it",
+        "name": "Gemma 3N E4B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.12
+        },
+        "limit": {
+          "context": 32768,
+          "output": 32768
+        }
+      },
+      "google/gemma-4-31B-it": {
+        "id": "google/gemma-4-31B-it",
+        "name": "Gemma 4 31B Instruct",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.39,
+          "output": 0.97
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        }
+      },
+      "Qwen/Qwen3.7-Max": {
+        "id": "Qwen/Qwen3.7-Max",
+        "name": "Qwen3.7 Max",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 3.75,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 500000
+        }
+      },
+      "Qwen/Qwen2.5-7B-Instruct-Turbo": {
+        "id": "Qwen/Qwen2.5-7B-Instruct-Turbo",
+        "name": "Qwen 2.5 7B Instruct Turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 0.3
+        },
+        "limit": {
+          "context": 32768,
+          "output": 32768
+        }
+      },
+      "Qwen/Qwen3-Coder-Next-FP8": {
+        "id": "Qwen/Qwen3-Coder-Next-FP8",
+        "name": "Qwen3 Coder Next FP8",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "status": "deprecated"
+      },
+      "Qwen/Qwen3-235B-A22B-Instruct-2507-tput": {
+        "id": "Qwen/Qwen3-235B-A22B-Instruct-2507-tput",
+        "name": "Qwen3 235B A22B Instruct 2507 FP8",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.6
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "status": "deprecated"
+      },
+      "Qwen/Qwen3.5-9B": {
+        "id": "Qwen/Qwen3.5-9B",
+        "name": "Qwen3.5 9B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.17,
+          "output": 0.25
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "Qwen/Qwen3.5-397B-A17B": {
+        "id": "Qwen/Qwen3.5-397B-A17B",
+        "name": "Qwen3.5 397B A17B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3.6,
+          "cache_read": 0.35
+        },
+        "limit": {
+          "context": 262144,
+          "output": 130000
+        },
+        "status": "deprecated"
+      },
+      "Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8": {
+        "id": "Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8",
+        "name": "Qwen3 Coder 480B A35B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "status": "deprecated"
+      },
+      "Qwen/Qwen3.6-Plus": {
+        "id": "Qwen/Qwen3.6-Plus",
+        "name": "Qwen3.6 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 500000
+        }
+      },
+      "LiquidAI/LFM2-24B-A2B": {
+        "id": "LiquidAI/LFM2-24B-A2B",
+        "name": "LFM2-24B-A2B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.03,
+          "output": 0.12
+        },
+        "limit": {
+          "context": 32768,
+          "output": 32768
+        }
+      },
+      "deepseek-ai/DeepSeek-V4-Flash-0731": {
+        "id": "deepseek-ai/DeepSeek-V4-Flash-0731",
+        "name": "DeepSeek V4 Flash 0731",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-0731"
+      },
+      "deepseek-ai/DeepSeek-R1": {
+        "id": "deepseek-ai/DeepSeek-R1",
+        "name": "DeepSeek-R1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 7
+        },
+        "limit": {
+          "context": 163839,
+          "output": 163839
+        },
+        "status": "deprecated"
+      },
+      "deepseek-ai/DeepSeek-V4-Pro-0813": {
+        "id": "deepseek-ai/DeepSeek-V4-Pro-0813",
+        "name": "DeepSeek V4 Pro 0813",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.32,
+          "output": 3.96,
+          "cache_read": 0.13
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro-0813"
+      },
+      "deepseek-ai/DeepSeek-V4.1-Flash": {
+        "id": "deepseek-ai/DeepSeek-V4.1-Flash",
+        "name": "DeepSeek V4.1 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.006
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4.1-flash"
+      },
+      "deepseek-ai/DeepSeek-V3-1": {
+        "id": "deepseek-ai/DeepSeek-V3-1",
+        "name": "DeepSeek V3.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 1.7
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "status": "deprecated"
+      },
+      "deepseek-ai/DeepSeek-V4-Pro": {
+        "id": "deepseek-ai/DeepSeek-V4-Pro",
+        "name": "DeepSeek V4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.74,
+          "output": 3.48,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 512000,
+          "output": 384000
+        }
+      },
+      "deepseek-ai/DeepSeek-V3": {
+        "id": "deepseek-ai/DeepSeek-V3",
+        "name": "DeepSeek-V3",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 1.25
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "status": "deprecated"
+      },
+      "MiniMaxAI/MiniMax-M3": {
+        "id": "MiniMaxAI/MiniMax-M3",
+        "name": "MiniMax-M3",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 524288,
+          "output": 250000
+        }
+      },
+      "MiniMaxAI/MiniMax-M2.5": {
+        "id": "MiniMaxAI/MiniMax-M2.5",
+        "name": "MiniMax-M2.5",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "status": "deprecated"
+      },
+      "MiniMaxAI/MiniMax-M2.7": {
+        "id": "MiniMaxAI/MiniMax-M2.7",
+        "name": "MiniMax-M2.7",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 196608,
+          "output": 131072
+        },
+        "canonical_model_id": "minimax/MiniMax-M2.7"
+      },
+      "moonshotai/Kimi-K3": {
+        "id": "moonshotai/Kimi-K3",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "zai-org/GLM-5.1": {
+        "id": "zai-org/GLM-5.1",
+        "name": "GLM-5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 202752,
+          "output": 131072
+        },
+        "status": "deprecated"
+      },
+      "zai-org/GLM-5.2": {
+        "id": "zai-org/GLM-5.2",
+        "name": "GLM-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 1048575,
+          "output": 164000
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "zai-org/GLM-5": {
+        "id": "zai-org/GLM-5",
+        "name": "GLM-5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 3.2
+        },
+        "limit": {
+          "context": 202752,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5",
+        "status": "deprecated"
+      },
+      "zai-org/GLM-5.3-Flash": {
+        "id": "zai-org/GLM-5.3-Flash",
+        "name": "GLM-5.3-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1048575,
+          "output": 400000
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "zai-org/GLM-5.3": {
+        "id": "zai-org/GLM-5.3",
+        "name": "GLM-5.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 262144
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "nvidia/nemotron-3-ultra-550b-a55b": {
+        "id": "nvidia/nemotron-3-ultra-550b-a55b",
+        "name": "Nemotron 3 Ultra 550B A55B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3.6,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 512300,
+          "output": 512300
+        },
+        "canonical_model_id": "nvidia/nemotron-3-ultra-550b-a55b"
+      },
+      "openai/gpt-oss-20b": {
+        "id": "openai/gpt-oss-20b",
+        "name": "GPT OSS 20B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.2
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        }
+      },
+      "openai/gpt-oss-120b": {
+        "id": "openai/gpt-oss-120b",
+        "name": "GPT OSS 120B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        }
+      }
+    }
+  },
+  "vercel": {
+    "id": "vercel",
+    "name": "Vercel AI Gateway",
+    "env": ["AI_GATEWAY_API_KEY"],
+    "npm": "@ai-sdk/gateway",
+    "models": {
+      "voyage/voyage-law-2": {
+        "id": "voyage/voyage-law-2",
+        "name": "voyage-law-2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "voyage/rerank-2.5-lite": {
+        "id": "voyage/rerank-2.5-lite",
+        "name": "Voyage Rerank 2.5 Lite",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 32000,
+          "output": 32000
+        }
+      },
+      "voyage/voyage-3.5": {
+        "id": "voyage/voyage-3.5",
+        "name": "voyage-3.5",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "voyage/voyage-finance-2": {
+        "id": "voyage/voyage-finance-2",
+        "name": "voyage-finance-2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "voyage/voyage-4-large": {
+        "id": "voyage/voyage-4-large",
+        "name": "voyage-4-large",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 32000,
+          "output": 0
+        }
+      },
+      "voyage/voyage-3.5-lite": {
+        "id": "voyage/voyage-3.5-lite",
+        "name": "voyage-3.5-lite",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "voyage/voyage-4": {
+        "id": "voyage/voyage-4",
+        "name": "voyage-4",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 32000,
+          "output": 0
+        }
+      },
+      "voyage/voyage-3-large": {
+        "id": "voyage/voyage-3-large",
+        "name": "voyage-3-large",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "voyage/voyage-code-2": {
+        "id": "voyage/voyage-code-2",
+        "name": "voyage-code-2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "voyage/voyage-code-3": {
+        "id": "voyage/voyage-code-3",
+        "name": "voyage-code-3",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "voyage/rerank-2.5": {
+        "id": "voyage/rerank-2.5",
+        "name": "Voyage Rerank 2.5",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 32000,
+          "output": 32000
+        }
+      },
+      "voyage/voyage-4-lite": {
+        "id": "voyage/voyage-4-lite",
+        "name": "voyage-4-lite",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 32000,
+          "output": 0
+        }
+      },
+      "interfaze/interfaze-beta": {
+        "id": "interfaze/interfaze-beta",
+        "name": "Interfaze Beta",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 3.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 32000
+        }
+      },
+      "stealth/pixel-canary": {
+        "id": "stealth/pixel-canary",
+        "name": "Pixel Canary",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "xhigh"]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        }
+      },
+      "zai/glm-4.5": {
+        "id": "zai/glm-4.5",
+        "name": "GLM 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.2,
+          "cache_read": 0.11
+        },
+        "limit": {
+          "context": 128000,
+          "output": 96000
+        },
+        "canonical_model_id": "zhipuai/glm-4.5"
+      },
+      "zai/glm-5v-turbo": {
+        "id": "zai/glm-5v-turbo",
+        "name": "GLM 5V Turbo",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.2,
+          "output": 4,
+          "cache_read": 0.24
+        },
+        "limit": {
+          "context": 200000,
+          "output": 128000
+        },
+        "canonical_model_id": "zhipuai/glm-5v-turbo"
+      },
+      "zai/glm-5.3-flash": {
+        "id": "zai/glm-5.3-flash",
+        "name": "GLM 5.3 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131000
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "zai/glm-4.6": {
+        "id": "zai/glm-4.6",
+        "name": "GLM 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.2,
+          "cache_read": 0.11
+        },
+        "limit": {
+          "context": 200000,
+          "output": 96000
+        },
+        "canonical_model_id": "zhipuai/glm-4.6"
+      },
+      "zai/glm-5.2-fast": {
+        "id": "zai/glm-5.2-fast",
+        "name": "GLM 5.2 Fast",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.8,
+          "output": 8.8,
+          "cache_read": 0.56
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "zai/glm-5": {
+        "id": "zai/glm-5",
+        "name": "GLM-5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 3.2
+        },
+        "limit": {
+          "context": 202800,
+          "output": 131100
+        },
+        "canonical_model_id": "zhipuai/glm-5"
+      },
+      "zai/glm-4.5v": {
+        "id": "zai/glm-4.5v",
+        "name": "GLM 4.5V",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 1.8,
+          "cache_read": 0.11
+        },
+        "limit": {
+          "context": 66000,
+          "output": 16000
+        },
+        "canonical_model_id": "zhipuai/glm-4.5v"
+      },
+      "zai/glm-5.3-flashx": {
+        "id": "zai/glm-5.3-flashx",
+        "name": "GLM 5.3 FlashX",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.37,
+          "output": 1.25,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "zai/glm-4.7-flash": {
+        "id": "zai/glm-4.7-flash",
+        "name": "GLM 4.7 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.4
+        },
+        "limit": {
+          "context": 200000,
+          "output": 131000
+        },
+        "canonical_model_id": "zhipuai/glm-4.7-flash"
+      },
+      "zai/glm-4.7": {
+        "id": "zai/glm-4.7",
+        "name": "GLM 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.2
+        },
+        "limit": {
+          "context": 200000,
+          "output": 120000
+        },
+        "canonical_model_id": "zhipuai/glm-4.7"
+      },
+      "zai/glm-5.2": {
+        "id": "zai/glm-5.2",
+        "name": "GLM 5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.8,
+          "output": 2.55,
+          "cache_read": 0.16
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "zai/glm-5.1": {
+        "id": "zai/glm-5.1",
+        "name": "GLM 5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26
+        },
+        "limit": {
+          "context": 202800,
+          "output": 64000
+        },
+        "canonical_model_id": "zhipuai/glm-5.1"
+      },
+      "zai/glm-4.7-flashx": {
+        "id": "zai/glm-4.7-flashx",
+        "name": "GLM 4.7 FlashX",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.4,
+          "cache_read": 0.01
+        },
+        "limit": {
+          "context": 200000,
+          "output": 128000
+        },
+        "canonical_model_id": "zhipuai/glm-4.7-flashx"
+      },
+      "zai/glm-5-turbo": {
+        "id": "zai/glm-5-turbo",
+        "name": "GLM 5 Turbo",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.2,
+          "output": 4,
+          "cache_read": 0.24
+        },
+        "limit": {
+          "context": 202800,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5-turbo"
+      },
+      "zai/glm-4.5-air": {
+        "id": "zai/glm-4.5-air",
+        "name": "GLM 4.5 Air",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.1,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 128000,
+          "output": 96000
+        },
+        "canonical_model_id": "zhipuai/glm-4.5-air"
+      },
+      "zai/glm-5.3": {
+        "id": "zai/glm-5.3",
+        "name": "GLM 5.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.14
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 1000000
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "zai/glm-5.3-fast": {
+        "id": "zai/glm-5.3-fast",
+        "name": "GLM 5.3 Fast",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.1,
+          "output": 6.6,
+          "cache_read": 0.21
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 262144
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "spacexai/grok-4.20-multi-agent": {
+        "id": "spacexai/grok-4.20-multi-agent",
+        "name": "Grok 4.20 Multi-Agent",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 2000000
+        }
+      },
+      "spacexai/grok-tts": {
+        "id": "spacexai/grok-tts",
+        "name": "Grok TTS",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["audio"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "spacexai/grok-4.20-reasoning": {
+        "id": "spacexai/grok-4.20-reasoning",
+        "name": "Grok 4.20 Reasoning",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 2000000
+        }
+      },
+      "spacexai/grok-4.7": {
+        "id": "spacexai/grok-4.7",
+        "name": "Grok 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "canonical_model_id": "xai/grok-4.7"
+      },
+      "spacexai/grok-voice-think-fast-1.0": {
+        "id": "spacexai/grok-voice-think-fast-1.0",
+        "name": "Grok Voice Think Fast 1.0",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["text", "audio"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "spacexai/grok-4.20-non-reasoning": {
+        "id": "spacexai/grok-4.20-non-reasoning",
+        "name": "Grok 4.20 Non-Reasoning",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 2000000
+        }
+      },
+      "spacexai/grok-stt": {
+        "id": "spacexai/grok-stt",
+        "name": "Grok STT",
+        "reasoning": false,
+        "modalities": {
+          "input": ["audio"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "spacexai/grok-imagine-image": {
+        "id": "spacexai/grok-imagine-image",
+        "name": "Grok Imagine Image",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "spacexai/grok-imagine-video": {
+        "id": "spacexai/grok-imagine-video",
+        "name": "Grok Imagine",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "spacexai/grok-4.1-fast-reasoning": {
+        "id": "spacexai/grok-4.1-fast-reasoning",
+        "name": "Grok 4.1 Fast Reasoning",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.5,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 1000000
+        },
+        "canonical_model_id": "xai/grok-4.1-fast-reasoning"
+      },
+      "spacexai/grok-4.3": {
+        "id": "spacexai/grok-4.3",
+        "name": "Grok 4.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 1000000
+        },
+        "canonical_model_id": "xai/grok-4.3"
+      },
+      "spacexai/grok-imagine-video-1.5": {
+        "id": "spacexai/grok-imagine-video-1.5",
+        "name": "Grok Imagine Video 1.5",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "xai/grok-imagine-video-1.5"
+      },
+      "spacexai/grok-4.5": {
+        "id": "spacexai/grok-4.5",
+        "name": "Grok 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "canonical_model_id": "xai/grok-4.5"
+      },
+      "spacexai/grok-voice-think-fast-2.0": {
+        "id": "spacexai/grok-voice-think-fast-2.0",
+        "name": "Grok Voice Think Fast 2.0",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["text", "audio"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "spacexai/grok-imagine-image-2.0": {
+        "id": "spacexai/grok-imagine-image-2.0",
+        "name": "Grok Imagine Image 2.0",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "xai/grok-imagine-image-2.0"
+      },
+      "spacexai/grok-4.20-multi-agent-beta": {
+        "id": "spacexai/grok-4.20-multi-agent-beta",
+        "name": "Grok 4.20 Multi Agent Beta",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 2000000
+        }
+      },
+      "spacexai/grok-4.20-non-reasoning-beta": {
+        "id": "spacexai/grok-4.20-non-reasoning-beta",
+        "name": "Grok 4.20 Beta Non-Reasoning",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.4
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 2000000
+        }
+      },
+      "spacexai/grok-build-0.1": {
+        "id": "spacexai/grok-build-0.1",
+        "name": "Grok Build 0.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 2,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        },
+        "canonical_model_id": "xai/grok-build-0.1"
+      },
+      "spacexai/grok-4.1-fast-non-reasoning": {
+        "id": "spacexai/grok-4.1-fast-non-reasoning",
+        "name": "Grok 4.1 Fast Non-Reasoning",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.5,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 1000000
+        }
+      },
+      "spacexai/grok-4.20-reasoning-beta": {
+        "id": "spacexai/grok-4.20-reasoning-beta",
+        "name": "Grok 4.20 Beta Reasoning",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 2000000,
+          "output": 2000000
+        }
+      },
+      "spacexai/grok-4.6": {
+        "id": "spacexai/grok-4.6",
+        "name": "Grok 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "canonical_model_id": "xai/grok-4.6"
+      },
+      "prodia/flux-fast-schnell": {
+        "id": "prodia/flux-fast-schnell",
+        "name": "Flux Schnell",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 512,
+          "output": 0
+        }
+      },
+      "recraft/recraft-v2": {
+        "id": "recraft/recraft-v2",
+        "name": "Recraft V2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 512,
+          "output": 0
+        }
+      },
+      "recraft/recraft-v4-pro": {
+        "id": "recraft/recraft-v4-pro",
+        "name": "Recraft V4 Pro",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "recraft/recraft-v4.1-utility": {
+        "id": "recraft/recraft-v4.1-utility",
+        "name": "Recraft V4.1 Utility",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "recraft/recraft-v4.1-pro": {
+        "id": "recraft/recraft-v4.1-pro",
+        "name": "Recraft V4.1 Pro",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "recraft/recraft-v3": {
+        "id": "recraft/recraft-v3",
+        "name": "Recraft V3",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 512,
+          "output": 0
+        }
+      },
+      "recraft/recraft-v4.1": {
+        "id": "recraft/recraft-v4.1",
+        "name": "Recraft V4.1",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "recraft/recraft-v4.1-flash": {
+        "id": "recraft/recraft-v4.1-flash",
+        "name": "Recraft V4.1 Flash",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "recraft/recraft-v4.1-utility-pro": {
+        "id": "recraft/recraft-v4.1-utility-pro",
+        "name": "Recraft V4.1 Utility Pro",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "recraft/recraft-v4": {
+        "id": "recraft/recraft-v4",
+        "name": "Recraft V4",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "poolside/laguna-s-2.1-free": {
+        "id": "poolside/laguna-s-2.1-free",
+        "name": "Laguna S 2.1 Free",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 256000,
+          "output": 32768
+        },
+        "canonical_model_id": "poolside/laguna-s-2.1"
+      },
+      "poolside/laguna-s-2.1": {
+        "id": "poolside/laguna-s-2.1",
+        "name": "Laguna S 2.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.2,
+          "cache_read": 0.01
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "poolside/laguna-s-2.1"
+      },
+      "anthropic/claude-opus-4.5": {
+        "id": "anthropic/claude-opus-4.5",
+        "name": "Claude Opus 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-5"
+      },
+      "anthropic/claude-opus-4.6": {
+        "id": "anthropic/claude-opus-4.6",
+        "name": "Claude Opus 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-6"
+      },
+      "anthropic/claude-opus-4.7": {
+        "id": "anthropic/claude-opus-4.7",
+        "name": "Claude Opus 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-7"
+      },
+      "anthropic/claude-3-haiku": {
+        "id": "anthropic/claude-3-haiku",
+        "name": "Claude Haiku 3",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1.25,
+          "cache_read": 0.03,
+          "cache_write": 0.3
+        },
+        "limit": {
+          "context": 200000,
+          "output": 4096
+        },
+        "canonical_model_id": "anthropic/claude-3-haiku-20240307"
+      },
+      "anthropic/claude-opus-4.8": {
+        "id": "anthropic/claude-opus-4.8",
+        "name": "Claude Opus 4.8",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-8"
+      },
+      "anthropic/claude-opus-5.5-fast": {
+        "id": "anthropic/claude-opus-5.5-fast",
+        "name": "Claude Opus 5.5 (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 8,
+          "output": 40,
+          "cache_read": 0.4,
+          "cache_write": 10
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5-5"
+      },
+      "anthropic/claude-haiku-4.5": {
+        "id": "anthropic/claude-haiku-4.5",
+        "name": "Claude Haiku 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 5,
+          "cache_read": 0.1,
+          "cache_write": 1.25
+        },
+        "limit": {
+          "context": 200000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-haiku-4-5"
+      },
+      "anthropic/claude-opus-5": {
+        "id": "anthropic/claude-opus-5",
+        "name": "Claude Opus 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 25,
+          "cache_read": 0.5,
+          "cache_write": 6.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5"
+      },
+      "anthropic/claude-sonnet-5.5": {
+        "id": "anthropic/claude-sonnet-5.5",
+        "name": "Claude Sonnet 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5-5"
+      },
+      "anthropic/claude-fable-5.1": {
+        "id": "anthropic/claude-fable-5.1",
+        "name": "Claude Fable 5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 0.25,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-fable-5-1"
+      },
+      "anthropic/claude-fable-5": {
+        "id": "anthropic/claude-fable-5",
+        "name": "Claude Fable 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-fable-5"
+      },
+      "anthropic/claude-opus-4.8-fast": {
+        "id": "anthropic/claude-opus-4.8-fast",
+        "name": "Claude Opus 4.8 (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-8"
+      },
+      "anthropic/claude-sonnet-4": {
+        "id": "anthropic/claude-sonnet-4",
+        "name": "Claude Sonnet 4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-20250514"
+      },
+      "anthropic/claude-sonnet-5": {
+        "id": "anthropic/claude-sonnet-5",
+        "name": "Claude Sonnet 5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-5"
+      },
+      "anthropic/claude-sonnet-4.6": {
+        "id": "anthropic/claude-sonnet-4.6",
+        "name": "Claude Sonnet 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "max"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-sonnet-4-6"
+      },
+      "anthropic/claude-opus-5.5": {
+        "id": "anthropic/claude-opus-5.5",
+        "name": "Claude Opus 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.2,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5-5"
+      },
+      "anthropic/claude-opus-5-fast": {
+        "id": "anthropic/claude-opus-5-fast",
+        "name": "Claude Opus 5 (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "anthropic/claude-opus-5"
+      },
+      "anthropic/claude-opus-4": {
+        "id": "anthropic/claude-opus-4",
+        "name": "Claude Opus 4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 75,
+          "cache_read": 1.5,
+          "cache_write": 18.75
+        },
+        "limit": {
+          "context": 200000,
+          "output": 32000
+        },
+        "canonical_model_id": "anthropic/claude-opus-4-20250514"
+      },
+      "anthropic/claude-sonnet-4.5": {
+        "id": "anthropic/claude-sonnet-4.5",
+        "name": "Claude Sonnet 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3,
+          "cache_write": 3.75
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        }
+      },
+      "cohere/rerank-v4-fast": {
+        "id": "cohere/rerank-v4-fast",
+        "name": "Cohere Rerank 4 Fast",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 32000,
+          "output": 32000
+        }
+      },
+      "cohere/rerank-v4-pro": {
+        "id": "cohere/rerank-v4-pro",
+        "name": "Cohere Rerank 4 Pro",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 32000,
+          "output": 32000
+        }
+      },
+      "cohere/command-a": {
+        "id": "cohere/command-a",
+        "name": "Command A",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10
+        },
+        "limit": {
+          "context": 256000,
+          "output": 8000
+        }
+      },
+      "cohere/embed-v4.0": {
+        "id": "cohere/embed-v4.0",
+        "name": "Embed v4.0",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 128000,
+          "output": 1536
+        }
+      },
+      "cohere/rerank-v3.5": {
+        "id": "cohere/rerank-v3.5",
+        "name": "Cohere Rerank 3.5",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 4096,
+          "output": 4096
+        }
+      },
+      "deepseek/deepseek-v4-flash-0731": {
+        "id": "deepseek/deepseek-v4-flash-0731",
+        "name": "DeepSeek V4 Flash 0731",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.076,
+          "output": 0.153,
+          "cache_read": 0.014
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-0731"
+      },
+      "deepseek/deepseek-v4.1-flash": {
+        "id": "deepseek/deepseek-v4.1-flash",
+        "name": "DeepSeek V4.1 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.007
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 32768
+        },
+        "canonical_model_id": "deepseek/deepseek-v4.1-flash"
+      },
+      "deepseek/deepseek-v4-flash-vision-exp": {
+        "id": "deepseek/deepseek-v4-flash-vision-exp",
+        "name": "DeepSeek V4 Flash Vision Exp",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2156,
+          "output": 0.6468,
+          "cache_read": 0.0068
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-vision-exp"
+      },
+      "deepseek/deepseek-v3.1-terminus": {
+        "id": "deepseek/deepseek-v3.1-terminus",
+        "name": "DeepSeek V3.1 Terminus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.27,
+          "output": 1,
+          "cache_read": 0.135
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "deepseek/deepseek-v4-pro-0813": {
+        "id": "deepseek/deepseek-v4-pro-0813",
+        "name": "DeepSeek V4 Pro 0813",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.66,
+          "output": 1.98,
+          "cache_read": 0.066
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro-0813"
+      },
+      "deepseek/deepseek-v3.2-thinking": {
+        "id": "deepseek/deepseek-v3.2-thinking",
+        "name": "DeepSeek V3.2 Thinking",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.62,
+          "output": 1.85
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8000
+        }
+      },
+      "deepseek/deepseek-v3.1": {
+        "id": "deepseek/deepseek-v3.1",
+        "name": "DeepSeek-V3.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 0.95,
+          "cache_read": 0.13
+        },
+        "limit": {
+          "context": 163840,
+          "output": 128000
+        },
+        "canonical_model_id": "deepseek/deepseek-v3.1"
+      },
+      "deepseek/deepseek-v4-pro": {
+        "id": "deepseek/deepseek-v4-pro",
+        "name": "DeepSeek V4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.66,
+          "output": 1.98,
+          "cache_read": 0.022
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro"
+      },
+      "deepseek/deepseek-v3.2": {
+        "id": "deepseek/deepseek-v3.2",
+        "name": "DeepSeek V3.2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.62,
+          "output": 1.85
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8000
+        },
+        "canonical_model_id": "deepseek/deepseek-v3.2"
+      },
+      "deepseek/deepseek-v4-flash": {
+        "id": "deepseek/deepseek-v4-flash",
+        "name": "DeepSeek V4 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.13,
+          "output": 0.26,
+          "cache_read": 0.028
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash"
+      },
+      "deepseek/deepseek-r1": {
+        "id": "deepseek/deepseek-r1",
+        "name": "DeepSeek-R1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.35,
+          "output": 5.4
+        },
+        "limit": {
+          "context": 128000,
+          "output": 32768
+        },
+        "canonical_model_id": "deepseek/deepseek-r1"
+      },
+      "quiverai/arrow-1.1": {
+        "id": "quiverai/arrow-1.1",
+        "name": "Arrow 1.1",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        }
+      },
+      "quiverai/arrow-2": {
+        "id": "quiverai/arrow-2",
+        "name": "Arrow 2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.4,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 131072,
+          "output": 65536
+        },
+        "canonical_model_id": "quiverai/arrow-2"
+      },
+      "quiverai/arrow-2-telos": {
+        "id": "quiverai/arrow-2-telos",
+        "name": "Arrow 2 Telos",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 6,
+          "output": 30,
+          "cache_read": 0.6,
+          "cache_write": 7.5
+        },
+        "limit": {
+          "context": 131072,
+          "output": 65536
+        },
+        "canonical_model_id": "quiverai/arrow-2-telos"
+      },
+      "bfl/flux-kontext-max": {
+        "id": "bfl/flux-kontext-max",
+        "name": "FLUX.1 Kontext Max",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 512,
+          "output": 0
+        }
+      },
+      "bfl/flux-pro-1.1-ultra": {
+        "id": "bfl/flux-pro-1.1-ultra",
+        "name": "FLUX1.1 [pro] Ultra",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 512,
+          "output": 0
+        }
+      },
+      "bfl/flux-3-video": {
+        "id": "bfl/flux-3-video",
+        "name": "Flux 3",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "bfl/flux-2-flex": {
+        "id": "bfl/flux-2-flex",
+        "name": "FLUX.2 [flex]",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "bfl/flux-2-klein-4b": {
+        "id": "bfl/flux-2-klein-4b",
+        "name": "FLUX.2 [klein] 4B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "bfl/flux-pro-1.0-fill": {
+        "id": "bfl/flux-pro-1.0-fill",
+        "name": "FLUX.1 Fill [pro]",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 512,
+          "output": 0
+        }
+      },
+      "bfl/flux-2-klein-9b": {
+        "id": "bfl/flux-2-klein-9b",
+        "name": "FLUX.2 [klein] 9B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "bfl/flux-2-pro": {
+        "id": "bfl/flux-2-pro",
+        "name": "FLUX.2 [pro]",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 67300,
+          "output": 67300
+        }
+      },
+      "bfl/flux-2-max": {
+        "id": "bfl/flux-2-max",
+        "name": "FLUX.2 [max]",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 67300,
+          "output": 67300
+        }
+      },
+      "bfl/flux-pro-1.1": {
+        "id": "bfl/flux-pro-1.1",
+        "name": "FLUX1.1 [pro]",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 512,
+          "output": 0
+        }
+      },
+      "bfl/flux-kontext-pro": {
+        "id": "bfl/flux-kontext-pro",
+        "name": "FLUX.1 Kontext Pro",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 512,
+          "output": 0
+        }
+      },
+      "tencent/hy-mt2-lite": {
+        "id": "tencent/hy-mt2-lite",
+        "name": "Tencent Hy-MT2-Lite",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.044,
+          "output": 0.177
+        },
+        "limit": {
+          "context": 8000,
+          "output": 4000
+        }
+      },
+      "tencent/hy3": {
+        "id": "tencent/hy3",
+        "name": "Hy3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.58,
+          "cache_read": 0.035
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "tencent/hy3"
+      },
+      "tencent/hy-mt2-plus": {
+        "id": "tencent/hy-mt2-plus",
+        "name": "Tencent Hy-MT2-Plus",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.074,
+          "output": 0.295
+        },
+        "limit": {
+          "context": 8000,
+          "output": 4000
+        }
+      },
+      "tencent/hy-mt2-pro": {
+        "id": "tencent/hy-mt2-pro",
+        "name": "Tencent Hy-MT2-Pro",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.074,
+          "output": 0.295
+        },
+        "limit": {
+          "context": 8000,
+          "output": 4000
+        }
+      },
+      "tencent/hy4-preview": {
+        "id": "tencent/hy4-preview",
+        "name": "Tencent Hy4 Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.834,
+          "output": 2.501,
+          "cache_read": 0.042
+        },
+        "limit": {
+          "context": 1024000,
+          "output": 64000
+        },
+        "canonical_model_id": "tencent/hy4-preview"
+      },
+      "inference-net/schematron-v2-small": {
+        "id": "inference-net/schematron-v2-small",
+        "name": "Schematron V2 Small",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.23,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        }
+      },
+      "inference-net/schematron-v2-turbo": {
+        "id": "inference-net/schematron-v2-turbo",
+        "name": "Schematron V2 Turbo",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.03,
+          "output": 0.15,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "thinkingmachines/inkling-small": {
+        "id": "thinkingmachines/inkling-small",
+        "name": "Inkling Small",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.45,
+          "output": 1.2,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 1000000
+        },
+        "canonical_model_id": "thinkingmachines/inkling-small"
+      },
+      "thinkingmachines/inkling": {
+        "id": "thinkingmachines/inkling",
+        "name": "Inkling",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 4.05,
+          "cache_read": 0.17
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        },
+        "canonical_model_id": "thinkingmachines/inkling"
+      },
+      "meituan/longcat-2.5-preview": {
+        "id": "meituan/longcat-2.5-preview",
+        "name": "LongCat 2.5 Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.006
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        }
+      },
+      "perplexity/pplx-embed-v1-4b": {
+        "id": "perplexity/pplx-embed-v1-4b",
+        "name": "Embed v1 4b",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 32000,
+          "output": 0
+        }
+      },
+      "perplexity/pplx-embed-v1-0.6b": {
+        "id": "perplexity/pplx-embed-v1-0.6b",
+        "name": "Embed v1 0.6b",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 32000,
+          "output": 0
+        }
+      },
+      "perplexity/sonar": {
+        "id": "perplexity/sonar",
+        "name": "Sonar",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2.5,
+          "cache_write": 0.0625
+        },
+        "limit": {
+          "context": 127000,
+          "output": 8000
+        }
+      },
+      "meta/muse-spark-1.3": {
+        "id": "meta/muse-spark-1.3",
+        "name": "Muse Spark 1.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 4.25,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        },
+        "canonical_model_id": "meta/muse-spark-1.3"
+      },
+      "meta/muse-glimmer-30b": {
+        "id": "meta/muse-glimmer-30b",
+        "name": "Muse Glimmer 30B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.35,
+          "output": 1.5,
+          "cache_read": 0.04
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "canonical_model_id": "meta/muse-glimmer-30b"
+      },
+      "meta/muse-spark-1.1": {
+        "id": "meta/muse-spark-1.1",
+        "name": "Muse Spark 1.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 4.25,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        },
+        "canonical_model_id": "meta/muse-spark-1.1"
+      },
+      "meta/llama-3.1-8b": {
+        "id": "meta/llama-3.1-8b",
+        "name": "Llama 3.1 8B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.22,
+          "output": 0.22
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "meta/llama-3.1-70b": {
+        "id": "meta/llama-3.1-70b",
+        "name": "Llama 3.1 70B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.72,
+          "output": 0.72
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "meta/muse-spark-1.2": {
+        "id": "meta/muse-spark-1.2",
+        "name": "Muse Spark 1.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 4.25,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        },
+        "canonical_model_id": "meta/muse-spark-1.2"
+      },
+      "meta/muse-image-1.0": {
+        "id": "meta/muse-image-1.0",
+        "name": "Muse Image 1.0",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "meta/muse-spark-1.2-contributor": {
+        "id": "meta/muse-spark-1.2-contributor",
+        "name": "Muse Spark 1.2 Contributor",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.2,
+          "cache_read": 0.002
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        }
+      },
+      "meta/muse-spark-1.3-contributor": {
+        "id": "meta/muse-spark-1.3-contributor",
+        "name": "Muse Spark 1.3 Contributor",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.2,
+          "cache_read": 0.002
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        }
+      },
+      "meta/llama-3.3-70b": {
+        "id": "meta/llama-3.3-70b",
+        "name": "Llama-3.3-70B-Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        }
+      },
+      "meta/llama-4-maverick": {
+        "id": "meta/llama-4-maverick",
+        "name": "Llama-4-Maverick-17B-128E-Instruct-FP8",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        }
+      },
+      "meta/llama-4-scout": {
+        "id": "meta/llama-4-scout",
+        "name": "Llama-4-Scout-17B-16E-Instruct-FP8",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        }
+      },
+      "arcee-ai/trinity-large-thinking": {
+        "id": "arcee-ai/trinity-large-thinking",
+        "name": "Trinity Large Thinking",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 0.9
+        },
+        "limit": {
+          "context": 262100,
+          "output": 80000
+        },
+        "canonical_model_id": "arcee-ai/trinity-large-thinking"
+      },
+      "alibaba/qwen3.5-flash": {
+        "id": "alibaba/qwen3.5-flash",
+        "name": "Qwen 3.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1,
+            "max": 81920
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.4,
+          "cache_read": 0.01,
+          "cache_write": 0.125
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "canonical_model_id": "alibaba/qwen3.5-flash"
+      },
+      "alibaba/qwen-3-32b": {
+        "id": "alibaba/qwen-3-32b",
+        "name": "Qwen 3.32B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1,
+            "max": 38912
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.16,
+          "output": 0.64
+        },
+        "limit": {
+          "context": 128000,
+          "output": 8192
+        }
+      },
+      "alibaba/wan-v2.6-t2v": {
+        "id": "alibaba/wan-v2.6-t2v",
+        "name": "Wan v2.6 Text-to-Video",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "alibaba/qwen3-vl-235b-a22b-instruct": {
+        "id": "alibaba/qwen3-vl-235b-a22b-instruct",
+        "name": "Qwen3 VL 235B A22B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 1.6
+        },
+        "limit": {
+          "context": 131072,
+          "output": 129024
+        },
+        "canonical_model_id": "alibaba/qwen3-vl-235b-a22b-instruct"
+      },
+      "alibaba/qwen3.7-max": {
+        "id": "alibaba/qwen3.7-max",
+        "name": "Qwen 3.7 Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1,
+            "max": 262144
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 7.5,
+          "cache_read": 0.5,
+          "cache_write": 3.125
+        },
+        "limit": {
+          "context": 991000,
+          "output": 64000
+        },
+        "canonical_model_id": "alibaba/qwen3.7-max"
+      },
+      "alibaba/qwen3.8-27b": {
+        "id": "alibaba/qwen3.8-27b",
+        "name": "Qwen3.8 27B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.1,
+          "cache_write": 0.625
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-27b"
+      },
+      "alibaba/qwen3-vl-thinking": {
+        "id": "alibaba/qwen3-vl-thinking",
+        "name": "Qwen3 VL Thinking",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1,
+            "max": 81920
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 4
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "alibaba/qwen3.8-2.4t-a95b": {
+        "id": "alibaba/qwen3.8-2.4t-a95b",
+        "name": "Qwen3.8 2.4T A95B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 262144,
+          "output": 128000
+        },
+        "canonical_model_id": "alibaba/qwen3.8-2.4t-a95b"
+      },
+      "alibaba/qwen3-next-80b-a3b-thinking": {
+        "id": "alibaba/qwen3-next-80b-a3b-thinking",
+        "name": "Qwen3 Next 80B A3B Thinking",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "alibaba/qwen3-next-80b-a3b-thinking"
+      },
+      "alibaba/qwen3.8-max": {
+        "id": "alibaba/qwen3.8-max",
+        "name": "Qwen 3.8 Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 0,
+            "max": 262144
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 262144,
+          "output": 128000
+        },
+        "canonical_model_id": "alibaba/qwen3.8-max-preview"
+      },
+      "alibaba/qwen3-coder-next": {
+        "id": "alibaba/qwen3-coder-next",
+        "name": "Qwen3 Coder Next",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        },
+        "canonical_model_id": "alibaba/qwen3-coder-next"
+      },
+      "alibaba/qwen3-vl-instruct": {
+        "id": "alibaba/qwen3-vl-instruct",
+        "name": "Qwen3 VL Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 1.6
+        },
+        "limit": {
+          "context": 131072,
+          "output": 129024
+        }
+      },
+      "alibaba/qwen3-coder": {
+        "id": "alibaba/qwen3-coder",
+        "name": "Qwen3 Coder 480B A35B Instruct",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 7.5,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        }
+      },
+      "alibaba/qwen3.5-plus": {
+        "id": "alibaba/qwen3.5-plus",
+        "name": "Qwen 3.5 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1,
+            "max": 81920
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2.4,
+          "cache_read": 0.04,
+          "cache_write": 0.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "canonical_model_id": "alibaba/qwen3.5-plus"
+      },
+      "alibaba/qwen-3.6-max-preview": {
+        "id": "alibaba/qwen-3.6-max-preview",
+        "name": "Qwen 3.6 Max Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1,
+            "max": 131072
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.3,
+          "output": 7.8,
+          "cache_read": 0.13,
+          "cache_write": 1.625
+        },
+        "limit": {
+          "context": 240000,
+          "output": 64000
+        }
+      },
+      "alibaba/wan-v2.6-i2v-flash": {
+        "id": "alibaba/wan-v2.6-i2v-flash",
+        "name": "Wan v2.6 Image-to-Video Flash",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "alibaba/wan-v2.6-r2v-flash": {
+        "id": "alibaba/wan-v2.6-r2v-flash",
+        "name": "Wan v2.6 Reference-to-Video Flash",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "alibaba/qwen-3-14b": {
+        "id": "alibaba/qwen-3-14b",
+        "name": "Qwen3-14B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.12,
+          "output": 0.24
+        },
+        "limit": {
+          "context": 40960,
+          "output": 16384
+        }
+      },
+      "alibaba/qwen3.7-flash": {
+        "id": "alibaba/qwen3.7-flash",
+        "name": "Qwen 3.7 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.03,
+          "output": 0.13,
+          "cache_read": 0.006,
+          "cache_write": 0.038
+        },
+        "limit": {
+          "context": 991000,
+          "output": 64000
+        },
+        "canonical_model_id": "alibaba/qwen3.7-flash"
+      },
+      "alibaba/qwen3-max": {
+        "id": "alibaba/qwen3-max",
+        "name": "Qwen3 Max",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.2,
+          "output": 6,
+          "cache_read": 0.24
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "alibaba/qwen3-max"
+      },
+      "alibaba/qwen3-embedding-0.6b": {
+        "id": "alibaba/qwen3-embedding-0.6b",
+        "name": "Qwen3 Embedding 0.6B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 32768,
+          "output": 32768
+        }
+      },
+      "alibaba/qwen-3-30b": {
+        "id": "alibaba/qwen-3-30b",
+        "name": "Qwen3-30B-A3B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.12,
+          "output": 0.5
+        },
+        "limit": {
+          "context": 40960,
+          "output": 16384
+        }
+      },
+      "alibaba/qwen3.8-omni-flash": {
+        "id": "alibaba/qwen3.8-omni-flash",
+        "name": "Qwen 3.8 Omni Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "xhigh"]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.47,
+          "cache_read": 0.016
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-omni-flash"
+      },
+      "alibaba/qwen3-coder-30b-a3b": {
+        "id": "alibaba/qwen3-coder-30b-a3b",
+        "name": "Qwen 3 Coder 30B A3B Instruct",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6
+        },
+        "limit": {
+          "context": 262144,
+          "output": 8192
+        }
+      },
+      "alibaba/qwen3-embedding-4b": {
+        "id": "alibaba/qwen3-embedding-4b",
+        "name": "Qwen3 Embedding 4B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 32768,
+          "output": 32768
+        }
+      },
+      "alibaba/qwen3-max-preview": {
+        "id": "alibaba/qwen3-max-preview",
+        "name": "Qwen3 Max Preview",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.2,
+          "output": 6,
+          "cache_read": 0.24
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        }
+      },
+      "alibaba/wan-v2.6-i2v": {
+        "id": "alibaba/wan-v2.6-i2v",
+        "name": "Wan v2.6 Image-to-Video",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "alibaba/qwen3-next-80b-a3b-instruct": {
+        "id": "alibaba/qwen3-next-80b-a3b-instruct",
+        "name": "Qwen3 Next 80B A3B Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 262114,
+          "output": 262114
+        },
+        "canonical_model_id": "alibaba/qwen3-next-80b-a3b-instruct"
+      },
+      "alibaba/wan-v2.5-t2v-preview": {
+        "id": "alibaba/wan-v2.5-t2v-preview",
+        "name": "Wan v2.5 Text-to-Video Preview",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "alibaba/qwen3-max-thinking": {
+        "id": "alibaba/qwen3-max-thinking",
+        "name": "Qwen 3 Max Thinking",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1,
+            "max": 81920
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.2,
+          "output": 6,
+          "cache_read": 0.24
+        },
+        "limit": {
+          "context": 256000,
+          "output": 65536
+        }
+      },
+      "alibaba/qwen3-coder-plus": {
+        "id": "alibaba/qwen3-coder-plus",
+        "name": "Qwen3 Coder Plus",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3-coder-plus"
+      },
+      "alibaba/qwen3.8-max-prime": {
+        "id": "alibaba/qwen3.8-max-prime",
+        "name": "Qwen 3.8 Max Prime",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 0,
+            "max": 262144
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 12,
+          "cache_read": 0.5,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "alibaba/qwen3.8-max-prime"
+      },
+      "alibaba/qwen3-235b-a22b-thinking": {
+        "id": "alibaba/qwen3-235b-a22b-thinking",
+        "name": "Qwen3 235B A22B Thinking 2507",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 1,
+            "max": 81920
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 4
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        }
+      },
+      "alibaba/qwen3.8-flash": {
+        "id": "alibaba/qwen3.8-flash",
+        "name": "Qwen 3.8 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.47,
+          "cache_read": 0.016,
+          "cache_write": 0.2
+        },
+        "limit": {
+          "context": 991000,
+          "output": 128000
+        },
+        "canonical_model_id": "alibaba/qwen3.8-flash"
+      },
+      "alibaba/qwen3-embedding-8b": {
+        "id": "alibaba/qwen3-embedding-8b",
+        "name": "Qwen3 Embedding 8B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 32768,
+          "output": 32768
+        }
+      },
+      "alibaba/wan-v3.0-video": {
+        "id": "alibaba/wan-v3.0-video",
+        "name": "Wan v3.0 Video",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "alibaba/wan-v2.7-r2v": {
+        "id": "alibaba/wan-v2.7-r2v",
+        "name": "Wan v2.7 Reference-to-Video",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "alibaba/wan-v3.0-video-prime": {
+        "id": "alibaba/wan-v3.0-video-prime",
+        "name": "Wan v3.0 Video Prime",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "alibaba/qwen3.6-27b": {
+        "id": "alibaba/qwen3.6-27b",
+        "name": "Qwen 3.6 27B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1,
+            "max": 131072
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3.6
+        },
+        "limit": {
+          "context": 256000,
+          "output": 65536
+        },
+        "canonical_model_id": "alibaba/qwen3.6-27b"
+      },
+      "alibaba/qwen-3-235b": {
+        "id": "alibaba/qwen-3-235b",
+        "name": "Qwen3 235B A22B Instruct 2507",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.22,
+          "output": 0.88
+        },
+        "limit": {
+          "context": 262144,
+          "output": 16384
+        }
+      },
+      "alibaba/qwen3.6-plus": {
+        "id": "alibaba/qwen3.6-plus",
+        "name": "Qwen 3.6 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1,
+            "max": 131072
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.05,
+          "cache_write": 0.625
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "canonical_model_id": "alibaba/qwen3.6-plus"
+      },
+      "alibaba/qwen3.7-plus": {
+        "id": "alibaba/qwen3.7-plus",
+        "name": "Qwen 3.7 Plus",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1,
+            "max": 262144
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 1.6,
+          "cache_read": 0.08,
+          "cache_write": 0.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "canonical_model_id": "alibaba/qwen3.7-plus"
+      },
+      "alibaba/wan-v2.6-r2v": {
+        "id": "alibaba/wan-v2.6-r2v",
+        "name": "Wan v2.6 Reference-to-Video",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "alibaba/qwen3.8-max-0902": {
+        "id": "alibaba/qwen3.8-max-0902",
+        "name": "Qwen3.8 Max 0902",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "xhigh"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 0,
+            "max": 262144
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.25,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 991000,
+          "output": 128000
+        },
+        "canonical_model_id": "alibaba/qwen3.8-max-0902"
+      },
+      "alibaba/wan-v2.7-t2v": {
+        "id": "alibaba/wan-v2.7-t2v",
+        "name": "Wan v2.7 Text-to-Video",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "mixedbread/toast-1": {
+        "id": "mixedbread/toast-1",
+        "name": "Toast 1",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 0.72,
+          "cache_read": 0.036
+        },
+        "limit": {
+          "context": 131000,
+          "output": 4000
+        },
+        "canonical_model_id": "mixedbread/toast-1"
+      },
+      "klingai/kling-v2.6-t2v": {
+        "id": "klingai/kling-v2.6-t2v",
+        "name": "Kling v2.6 Text-to-Video",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "klingai/kling-v2.6-i2v": {
+        "id": "klingai/kling-v2.6-i2v",
+        "name": "Kling v2.6 Image-to-Video",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "klingai/kling-v2.5-turbo-t2v": {
+        "id": "klingai/kling-v2.5-turbo-t2v",
+        "name": "Kling v2.5 Turbo Text-to-Video",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "klingai/kling-v3.0-i2v": {
+        "id": "klingai/kling-v3.0-i2v",
+        "name": "Kling v3.0 Image-to-Video",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "klingai/kling-v3.0-motion-control": {
+        "id": "klingai/kling-v3.0-motion-control",
+        "name": "Kling v3.0 Motion Control",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "klingai/kling-v3.0-t2v": {
+        "id": "klingai/kling-v3.0-t2v",
+        "name": "Kling v3.0 Text-to-Video",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "klingai/kling-v2.6-motion-control": {
+        "id": "klingai/kling-v2.6-motion-control",
+        "name": "Kling v2.6 Motion Control",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "klingai/kling-v2.5-turbo-i2v": {
+        "id": "klingai/kling-v2.5-turbo-i2v",
+        "name": "Kling v2.5 Turbo Image-to-Video",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "bytedance/seedream-5.0-lite": {
+        "id": "bytedance/seedream-5.0-lite",
+        "name": "Seedream 5.0 Lite",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "bytedance/seedream-4.5": {
+        "id": "bytedance/seedream-4.5",
+        "name": "Seedream 4.5",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "bytedance/seed-1.8": {
+        "id": "bytedance/seed-1.8",
+        "name": "Seed 1.8",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 256000,
+          "output": 32768
+        }
+      },
+      "bytedance/seed-2.1-turbo": {
+        "id": "bytedance/seed-2.1-turbo",
+        "name": "Seed 2.1 Turbo",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 2.5,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        }
+      },
+      "bytedance/seedream-4.0": {
+        "id": "bytedance/seedream-4.0",
+        "name": "Seedream 4.0",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "bytedance/seedance-v1.0-pro": {
+        "id": "bytedance/seedance-v1.0-pro",
+        "name": "Seedance v1.0 Pro",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "bytedance/seedance-2.0": {
+        "id": "bytedance/seedance-2.0",
+        "name": "Seedance 2.0",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "bytedance/seedance-2.0-fast": {
+        "id": "bytedance/seedance-2.0-fast",
+        "name": "Seedance 2.0 Fast",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "bytedance/seedance-v1.5-pro": {
+        "id": "bytedance/seedance-v1.5-pro",
+        "name": "Seedance v1.5 Pro",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "bytedance/seedance-2.0-mini": {
+        "id": "bytedance/seedance-2.0-mini",
+        "name": "Seedance 2.0 Mini",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "bytedance/seedance-2.5": {
+        "id": "bytedance/seedance-2.5",
+        "name": "Seedance 2.5",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "bytedance/seedance-v1.0-pro-fast": {
+        "id": "bytedance/seedance-v1.0-pro-fast",
+        "name": "Seedance v1.0 Pro Fast",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "bytedance/seedream-5.0-pro": {
+        "id": "bytedance/seedream-5.0-pro",
+        "name": "Seedream 5.0 Pro",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "bytedance/seed-1.6": {
+        "id": "bytedance/seed-1.6",
+        "name": "Seed 1.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 256000,
+          "output": 32000
+        }
+      },
+      "liquid/d1": {
+        "id": "liquid/d1",
+        "name": "Liquid d1",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 32000,
+          "output": 0
+        }
+      },
+      "google/gemma-4-31b-it": {
+        "id": "google/gemma-4-31b-it",
+        "name": "Gemma 4 31B IT",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.4
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "google/gemma-4-31b-it"
+      },
+      "google/gemini-omni-flash-preview": {
+        "id": "google/gemini-omni-flash-preview",
+        "name": "Gemini Omni Flash Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 9
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 57920
+        },
+        "canonical_model_id": "google/gemini-omni-flash-preview"
+      },
+      "google/gemini-3.1-flash-image-preview": {
+        "id": "google/gemini-3.1-flash-image-preview",
+        "name": "Gemini 3.1 Flash Image Preview (Nano Banana 2)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemini-3.1-flash-image-preview"
+      },
+      "google/gemini-3.5-transcribe-live": {
+        "id": "google/gemini-3.5-transcribe-live",
+        "name": "Gemini 3.5 Transcribe Live",
+        "reasoning": false,
+        "modalities": {
+          "input": ["audio"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "google/gemini-3.5-transcribe-live"
+      },
+      "google/gemini-2.5-flash-image": {
+        "id": "google/gemini-2.5-flash-image",
+        "name": "Nano Banana (Gemini 2.5 Flash Image)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 32768,
+          "output": 65535
+        },
+        "canonical_model_id": "google/gemini-2.5-flash-image"
+      },
+      "google/gemini-3.8-flash-lite-tts": {
+        "id": "google/gemini-3.8-flash-lite-tts",
+        "name": "Gemini 3.8 Flash-Lite TTS",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["audio"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 6,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "google/text-multilingual-embedding-002": {
+        "id": "google/text-multilingual-embedding-002",
+        "name": "Text Multilingual Embedding 002",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "google/gemini-embedding-2": {
+        "id": "google/gemini-embedding-2",
+        "name": "Gemini Embedding 2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "google/gemini-embedding-2"
+      },
+      "google/gemini-3.6-flash": {
+        "id": "google/gemini-3.6-flash",
+        "name": "Gemini 3.6 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 3.75,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "canonical_model_id": "google/gemini-3.6-flash"
+      },
+      "google/veo-3.1-lite-generate-001": {
+        "id": "google/veo-3.1-lite-generate-001",
+        "name": "Veo 3.1 Lite Generate",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "google/gemma-4-26b-a4b-it": {
+        "id": "google/gemma-4-26b-a4b-it",
+        "name": "Gemma 4 26B A4B IT",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "google/gemma-4-26b-a4b-it"
+      },
+      "google/gemini-3.5-flash-lite": {
+        "id": "google/gemini-3.5-flash-lite",
+        "name": "Gemini 3.5 Flash Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65000
+        },
+        "canonical_model_id": "google/gemini-3.5-flash-lite"
+      },
+      "google/gemini-3.1-flash-image": {
+        "id": "google/gemini-3.1-flash-image",
+        "name": "Nano Banana 2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 131072,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemini-3.1-flash-image"
+      },
+      "google/gemini-3.1-pro-preview": {
+        "id": "google/gemini-3.1-pro-preview",
+        "name": "Gemini 3.1 Pro Preview",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "canonical_model_id": "google/gemini-3.1-pro-preview"
+      },
+      "google/veo-3.1-fast-generate-001": {
+        "id": "google/veo-3.1-fast-generate-001",
+        "name": "Veo 3.1 Fast Generate",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "google/gemini-3-flash": {
+        "id": "google/gemini-3-flash",
+        "name": "Gemini 3 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 3,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65000
+        }
+      },
+      "google/gemini-3.5-flash": {
+        "id": "google/gemini-3.5-flash",
+        "name": "Gemini 3.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 9,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 64000
+        },
+        "canonical_model_id": "google/gemini-3.5-flash"
+      },
+      "google/gemini-3-pro-image": {
+        "id": "google/gemini-3-pro-image",
+        "name": "Nano Banana Pro",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 65536,
+          "output": 32768
+        },
+        "canonical_model_id": "google/gemini-3-pro-image"
+      },
+      "google/veo-3.0-fast-generate-001": {
+        "id": "google/veo-3.0-fast-generate-001",
+        "name": "Veo 3.0 Fast Generate",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "google/gemini-3.8-live": {
+        "id": "google/gemini-3.8-live",
+        "name": "Gemini 3.8 Live",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 4.5
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "google/veo-3.1-generate-001": {
+        "id": "google/veo-3.1-generate-001",
+        "name": "Veo 3.1",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "google/gemini-3.1-flash-lite-image": {
+        "id": "google/gemini-3.1-flash-lite-image",
+        "name": "Gemini 3.1 Flash Lite Image (Nano Banana 2 Lite)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text", "image"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 65536,
+          "output": 4096
+        },
+        "canonical_model_id": "google/gemini-3.1-flash-lite-image"
+      },
+      "google/gemini-3.7-flash": {
+        "id": "google/gemini-3.7-flash",
+        "name": "Gemini 3.7 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 3.75,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65535
+        },
+        "canonical_model_id": "google/gemini-3.7-flash"
+      },
+      "google/text-embedding-005": {
+        "id": "google/text-embedding-005",
+        "name": "Text Embedding 005",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "google/gemini-3.5-transcribe": {
+        "id": "google/gemini-3.5-transcribe",
+        "name": "Gemini 3.5 Transcribe",
+        "reasoning": false,
+        "modalities": {
+          "input": ["audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "google/gemini-3.8-flash": {
+        "id": "google/gemini-3.8-flash",
+        "name": "Gemini 3.8 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 3.75,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65535
+        },
+        "canonical_model_id": "google/gemini-3.8-flash"
+      },
+      "google/gemini-2.5-flash-lite": {
+        "id": "google/gemini-2.5-flash-lite",
+        "name": "Gemini 2.5 Flash Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          },
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.4,
+          "cache_read": 0.01
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65535
+        },
+        "canonical_model_id": "google/gemini-2.5-flash-lite"
+      },
+      "google/gemini-embedding-001": {
+        "id": "google/gemini-embedding-001",
+        "name": "Gemini Embedding 001",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        },
+        "canonical_model_id": "google/gemini-embedding-001"
+      },
+      "google/gemini-3.8-flash-tts": {
+        "id": "google/gemini-3.8-flash-tts",
+        "name": "Gemini 3.8 Flash TTS",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["audio"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 9,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "google/gemini-3.8-live-extended-thinking": {
+        "id": "google/gemini-3.8-live-extended-thinking",
+        "name": "Gemini 3.8 Live Extended Thinking",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 4.5
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "google/veo-3.0-generate-001": {
+        "id": "google/veo-3.0-generate-001",
+        "name": "Veo 3.0",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "google/gemini-3.1-flash-lite": {
+        "id": "google/gemini-3.1-flash-lite",
+        "name": "Gemini 3.1 Flash Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65000
+        },
+        "canonical_model_id": "google/gemini-3.1-flash-lite"
+      },
+      "google/gemini-2.5-flash": {
+        "id": "google/gemini-2.5-flash",
+        "name": "Gemini 2.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 0,
+            "max": 24576
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-2.5-flash"
+      },
+      "google/gemini-2.5-pro": {
+        "id": "google/gemini-2.5-pro",
+        "name": "Gemini 2.5 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens",
+            "min": 128,
+            "max": 32768
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 65536
+        },
+        "canonical_model_id": "google/gemini-2.5-pro"
+      },
+      "fireworks/ember-1": {
+        "id": "fireworks/ember-1",
+        "name": "Ember-1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1024
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 1048576
+        }
+      },
+      "sakana/fugu-max": {
+        "id": "sakana/fugu-max",
+        "name": "Fugu Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high", "xhigh"]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 1000000
+        }
+      },
+      "sakana/fugu-ultra-v2": {
+        "id": "sakana/fugu-ultra-v2",
+        "name": "Fugu Ultra v2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high", "xhigh"]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 1000000
+        }
+      },
+      "sakana/namazu": {
+        "id": "sakana/namazu",
+        "name": "Sakana Namazu",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        }
+      },
+      "sakana/fugu-ultra": {
+        "id": "sakana/fugu-ultra",
+        "name": "Fugu Ultra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 1000000
+        },
+        "canonical_model_id": "sakana/fugu-ultra"
+      },
+      "inclusionai/ling-3.1-flash-free": {
+        "id": "inclusionai/ling-3.1-flash-free",
+        "name": "Ling 3.1 Flash (Free)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "inclusionai/ling-3.1-flash"
+      },
+      "inclusionai/ling-3.0-flash": {
+        "id": "inclusionai/ling-3.0-flash",
+        "name": "Ling 3.0 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.021,
+          "output": 0.063,
+          "cache_read": 0.0042
+        },
+        "limit": {
+          "context": 256000,
+          "output": 32000
+        }
+      },
+      "inclusionai/ling-3.1-flash": {
+        "id": "inclusionai/ling-3.1-flash",
+        "name": "Ling 3.1 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "inclusionai/ling-3.1-flash"
+      },
+      "inclusionai/ling-3.0-flash-sante": {
+        "id": "inclusionai/ling-3.0-flash-sante",
+        "name": "Ling 3.0 Flash Sante",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 256000,
+          "output": 32000
+        }
+      },
+      "inclusionai/ling-3.0-flash-vl": {
+        "id": "inclusionai/ling-3.0-flash-vl",
+        "name": "Ling 3.0 Flash VL",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.075,
+          "output": 0.22,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 256000,
+          "output": 32000
+        }
+      },
+      "inclusionai/ling-3.0-flash-fin": {
+        "id": "inclusionai/ling-3.0-flash-fin",
+        "name": "Ling 3.0 Flash Fin",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.075,
+          "output": 0.22,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 256000,
+          "output": 32000
+        },
+        "canonical_model_id": "inclusionai/ling-3.0-flash-fin"
+      },
+      "inclusionai/ling-3.0-flash-sante-free": {
+        "id": "inclusionai/ling-3.0-flash-sante-free",
+        "name": "Ling 3.0 Flash Sante (Free)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0
+        },
+        "limit": {
+          "context": 256000,
+          "output": 32000
+        }
+      },
+      "moonshotai/kimi-k3": {
+        "id": "moonshotai/kimi-k3",
+        "name": "Kimi K3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3,
+          "output": 15,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "moonshotai/kimi-k3-fast": {
+        "id": "moonshotai/kimi-k3-fast",
+        "name": "Kimi K3 Fast",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4.5,
+          "output": 22.5,
+          "cache_read": 0.45
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "moonshotai/kimi-k3"
+      },
+      "moonshotai/kimi-k2.7-code-highspeed": {
+        "id": "moonshotai/kimi-k2.7-code-highspeed",
+        "name": "Kimi K2.7 Code High Speed",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.9,
+          "output": 8,
+          "cache_read": 0.38
+        },
+        "limit": {
+          "context": 262144,
+          "output": 32768
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code-highspeed"
+      },
+      "moonshotai/kimi-k2.6": {
+        "id": "moonshotai/kimi-k2.6",
+        "name": "Kimi K2.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.16
+        },
+        "limit": {
+          "context": 262000,
+          "output": 262000
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.6"
+      },
+      "moonshotai/kimi-k2-thinking": {
+        "id": "moonshotai/kimi-k2-thinking",
+        "name": "Kimi K2 Thinking",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.47,
+          "output": 2,
+          "cache_read": 0.141
+        },
+        "limit": {
+          "context": 216144,
+          "output": 216144
+        },
+        "canonical_model_id": "moonshotai/kimi-k2-thinking"
+      },
+      "moonshotai/kimi-k2.5": {
+        "id": "moonshotai/kimi-k2.5",
+        "name": "Kimi K2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 3
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.5"
+      },
+      "moonshotai/kimi-k2": {
+        "id": "moonshotai/kimi-k2",
+        "name": "Kimi K2 Instruct",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.57,
+          "output": 2.3
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        }
+      },
+      "moonshotai/kimi-k2.7-code": {
+        "id": "moonshotai/kimi-k2.7-code",
+        "name": "Kimi K2.7 Code",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.95,
+          "output": 4,
+          "cache_read": 0.19
+        },
+        "limit": {
+          "context": 256000,
+          "output": 32768
+        },
+        "canonical_model_id": "moonshotai/kimi-k2.7-code"
+      },
+      "nvidia/nemotron-3-nano-30b-a3b": {
+        "id": "nvidia/nemotron-3-nano-30b-a3b",
+        "name": "Nemotron 3 Nano 30B A3B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.2,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 262144,
+          "output": 262144
+        },
+        "canonical_model_id": "nvidia/nemotron-3-nano-30b-a3b"
+      },
+      "nvidia/nemotron-3.5-lightning": {
+        "id": "nvidia/nemotron-3.5-lightning",
+        "name": "Nemotron 3.5 Lightning 30B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "budget_tokens",
+            "min": 1,
+            "max": 32768
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.2,
+          "cache_read": 0.01
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "nvidia/nemotron-3.5-lightning"
+      },
+      "nvidia/nemotron-nano-9b-v2": {
+        "id": "nvidia/nemotron-nano-9b-v2",
+        "name": "Nvidia Nemotron Nano 9B V2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.23
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "canonical_model_id": "nvidia/nemotron-nano-9b-v2"
+      },
+      "nvidia/nemotron-3-super-120b-a12b": {
+        "id": "nvidia/nemotron-3-super-120b-a12b",
+        "name": "NVIDIA Nemotron 3 Super 120B A12B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.65
+        },
+        "limit": {
+          "context": 256000,
+          "output": 32000
+        },
+        "canonical_model_id": "nvidia/nemotron-3-super-120b-a12b"
+      },
+      "nvidia/nemotron-3-ultra-550b-a55b": {
+        "id": "nvidia/nemotron-3-ultra-550b-a55b",
+        "name": "Nemotron 3 Ultra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.4,
+          "cache_read": 0.12
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65000
+        },
+        "canonical_model_id": "nvidia/nemotron-3-ultra-550b-a55b"
+      },
+      "nvidia/nemotron-nano-12b-v2-vl": {
+        "id": "nvidia/nemotron-nano-12b-v2-vl",
+        "name": "Nvidia Nemotron Nano 12B V2 VL",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.6
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "canonical_model_id": "nvidia/nemotron-nano-12b-v2-vl"
+      },
+      "xiaomi/mimo-v2.6-pro": {
+        "id": "xiaomi/mimo-v2.6-pro",
+        "name": "MiMo V2.6 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.435,
+          "output": 0.87,
+          "cache_read": 0.0036
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.6-pro"
+      },
+      "xiaomi/mimo-v2.5": {
+        "id": "xiaomi/mimo-v2.5",
+        "name": "MiMo M2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.0028
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 131100
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.5"
+      },
+      "xiaomi/mimo-v2.6-pro-ultraspeed": {
+        "id": "xiaomi/mimo-v2.6-pro-ultraspeed",
+        "name": "MiMo V2.6 Pro UltraSpeed",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4.35,
+          "output": 8.7,
+          "cache_read": 0.036
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.6-pro-ultraspeed"
+      },
+      "xiaomi/mimo-v2.5-pro": {
+        "id": "xiaomi/mimo-v2.5-pro",
+        "name": "MiMo V2.5 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.435,
+          "output": 0.87,
+          "cache_read": 0.0036
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 131000
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.5-pro"
+      },
+      "xiaomi/mimo-v2.6-flash": {
+        "id": "xiaomi/mimo-v2.6-flash",
+        "name": "MiMo V2.6 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.0028
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "canonical_model_id": "xiaomi/mimo-v2.6-flash"
+      },
+      "minimax/minimax-m2.5": {
+        "id": "minimax/minimax-m2.5",
+        "name": "MiniMax M2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.03,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131000
+        },
+        "canonical_model_id": "minimax/MiniMax-M2.5"
+      },
+      "minimax/minimax-m2.1-lightning": {
+        "id": "minimax/minimax-m2.1-lightning",
+        "name": "MiniMax M2.1 Lightning",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.4,
+          "cache_read": 0.03,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "minimax/minimax-h3": {
+        "id": "minimax/minimax-h3",
+        "name": "MiniMax H3",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "minimax/minimax-m2.7": {
+        "id": "minimax/minimax-m2.7",
+        "name": "Minimax M2.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131000
+        },
+        "canonical_model_id": "minimax/MiniMax-M2.7"
+      },
+      "minimax/minimax-h3-max": {
+        "id": "minimax/minimax-h3-max",
+        "name": "MiniMax H3 Max",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "minimax/minimax-m3": {
+        "id": "minimax/minimax-m3",
+        "name": "MiniMax M3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 512000,
+          "output": 512000
+        },
+        "canonical_model_id": "minimax/MiniMax-M3"
+      },
+      "minimax/minimax-m2.7-highspeed": {
+        "id": "minimax/minimax-m2.7-highspeed",
+        "name": "MiniMax M2.7 High Speed",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.4,
+          "cache_read": 0.06,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131100
+        },
+        "canonical_model_id": "minimax/MiniMax-M2.7-highspeed"
+      },
+      "minimax/minimax-m2.5-highspeed": {
+        "id": "minimax/minimax-m2.5-highspeed",
+        "name": "MiniMax M2.5 High Speed",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.4,
+          "cache_read": 0.03,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131000
+        },
+        "canonical_model_id": "minimax/MiniMax-M2.5-highspeed"
+      },
+      "minimax/minimax-m2.1": {
+        "id": "minimax/minimax-m2.1",
+        "name": "MiniMax M2.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.03,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "canonical_model_id": "minimax/MiniMax-M2.1"
+      },
+      "minimax/minimax-m2": {
+        "id": "minimax/minimax-m2",
+        "name": "MiniMax M2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "budget_tokens"
+          }
+        ],
+        "interleaved": true,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 1.2,
+          "cache_read": 0.03,
+          "cache_write": 0.375
+        },
+        "limit": {
+          "context": 205000,
+          "output": 196608
+        },
+        "canonical_model_id": "minimax/MiniMax-M2"
+      },
+      "stepfun/step-5-preview": {
+        "id": "stepfun/step-5-preview",
+        "name": "Step 5 Preview",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 2.7,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 1000000
+        },
+        "canonical_model_id": "stepfun/step-5-preview"
+      },
+      "stepfun/step-3.5-flash": {
+        "id": "stepfun/step-3.5-flash",
+        "name": "StepFun 3.5 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.09,
+          "output": 0.3,
+          "cache_read": 0.02
+        },
+        "limit": {
+          "context": 262114,
+          "output": 262114
+        },
+        "canonical_model_id": "stepfun/step-3.5-flash"
+      },
+      "stepfun/step-3.7-flash": {
+        "id": "stepfun/step-3.7-flash",
+        "name": "Step 3.7 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.15,
+          "cache_read": 0.04
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        },
+        "canonical_model_id": "stepfun/step-3.7-flash"
+      },
+      "inception/mercury-coder-small": {
+        "id": "inception/mercury-coder-small",
+        "name": "Mercury Coder Small Beta",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1
+        },
+        "limit": {
+          "context": 32000,
+          "output": 16384
+        }
+      },
+      "inception/mercury-2.5": {
+        "id": "inception/mercury-2.5",
+        "name": "Mercury 2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.04,
+          "output": 0.15,
+          "cache_read": 0.004
+        },
+        "limit": {
+          "context": 260000,
+          "output": 65536
+        }
+      },
+      "inception/mercury-2": {
+        "id": "inception/mercury-2",
+        "name": "Mercury 2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 0.75,
+          "cache_read": 0.024999999999999998
+        },
+        "limit": {
+          "context": 128000,
+          "output": 50000
+        }
+      },
+      "amazon/titan-embed-text-v2": {
+        "id": "amazon/titan-embed-text-v2",
+        "name": "Titan Text Embeddings V2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "amazon/nova-2-lite": {
+        "id": "amazon/nova-2-lite",
+        "name": "Nova 2 Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 2.5,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 65535
+        }
+      },
+      "amazon/nova-lite": {
+        "id": "amazon/nova-lite",
+        "name": "Nova Lite",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.06,
+          "output": 0.24,
+          "cache_read": 0.015,
+          "cache_write": 0.06
+        },
+        "limit": {
+          "context": 300000,
+          "output": 10000
+        },
+        "canonical_model_id": "amazon/nova-lite"
+      },
+      "amazon/nova-pro": {
+        "id": "amazon/nova-pro",
+        "name": "Nova Pro",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.8,
+          "output": 3.2,
+          "cache_read": 0.2,
+          "cache_write": 0.8
+        },
+        "limit": {
+          "context": 300000,
+          "output": 10000
+        },
+        "canonical_model_id": "amazon/nova-pro"
+      },
+      "amazon/nova-micro": {
+        "id": "amazon/nova-micro",
+        "name": "Nova Micro",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.035,
+          "output": 0.14,
+          "cache_read": 0.00875,
+          "cache_write": 0.035
+        },
+        "limit": {
+          "context": 128000,
+          "output": 10000
+        },
+        "canonical_model_id": "amazon/nova-micro"
+      },
+      "mistral/codestral-embed": {
+        "id": "mistral/codestral-embed",
+        "name": "Codestral Embed",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "mistral/mistral-nemo": {
+        "id": "mistral/mistral-nemo",
+        "name": "Mistral Nemo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.04,
+          "output": 0.17
+        },
+        "limit": {
+          "context": 60288,
+          "output": 16000
+        }
+      },
+      "mistral/mistral-medium-3.5": {
+        "id": "mistral/mistral-medium-3.5",
+        "name": "Mistral Medium Latest",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 7.5,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 262144,
+          "output": 256000
+        }
+      },
+      "mistral/mistral-small": {
+        "id": "mistral/mistral-small",
+        "name": "Mistral Small (latest)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.015
+        },
+        "limit": {
+          "context": 262144,
+          "output": 4000
+        }
+      },
+      "mistral/mistral-large-3": {
+        "id": "mistral/mistral-large-3",
+        "name": "Mistral Large 3",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.5,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 262144,
+          "output": 256000
+        }
+      },
+      "mistral/mistral-embed": {
+        "id": "mistral/mistral-embed",
+        "name": "Mistral Embed",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "mistral/ministral-14b": {
+        "id": "mistral/ministral-14b",
+        "name": "Ministral 14B",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.2,
+          "cache_read": 0.02
+        },
+        "limit": {
+          "context": 262144,
+          "output": 256000
+        }
+      },
+      "mistral/codestral": {
+        "id": "mistral/codestral",
+        "name": "Codestral (latest)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 0.9,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 256000,
+          "output": 4096
+        }
+      },
+      "mistral/ministral-8b": {
+        "id": "mistral/ministral-8b",
+        "name": "Ministral 8B (latest)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.1
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        }
+      },
+      "mistral/ministral-3b": {
+        "id": "mistral/ministral-3b",
+        "name": "Ministral 3B (latest)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.04,
+          "output": 0.04
+        },
+        "limit": {
+          "context": 128000,
+          "output": 128000
+        }
+      },
+      "fish-audio/s2.1-pro": {
+        "id": "fish-audio/s2.1-pro",
+        "name": "S2.1 Pro",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["audio"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "fish-audio/s1": {
+        "id": "fish-audio/s1",
+        "name": "S1",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["audio"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "fish-audio/transcribe-1": {
+        "id": "fish-audio/transcribe-1",
+        "name": "Transcribe-1",
+        "reasoning": false,
+        "modalities": {
+          "input": ["audio"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "fish-audio/s2-pro": {
+        "id": "fish-audio/s2-pro",
+        "name": "S2 Pro",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["audio"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "morph/morph-v3-fast": {
+        "id": "morph/morph-v3-fast",
+        "name": "Morph v3 Fast",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.8,
+          "output": 1.2
+        },
+        "limit": {
+          "context": 16000,
+          "output": 16000
+        }
+      },
+      "morph/morph-v3-large": {
+        "id": "morph/morph-v3-large",
+        "name": "Morph v3 Large",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.9,
+          "output": 1.9
+        },
+        "limit": {
+          "context": 32000,
+          "output": 32000
+        }
+      },
+      "openai/gpt-4.1-mini-fast": {
+        "id": "openai/gpt-4.1-mini-fast",
+        "name": "GPT-4.1 mini (Fast)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.7,
+          "output": 2.8,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 1047576,
+          "output": 32768
+        },
+        "canonical_model_id": "openai/gpt-4.1-mini"
+      },
+      "openai/o3-fast": {
+        "id": "openai/o3-fast",
+        "name": "o3 (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3.5,
+          "output": 14,
+          "cache_read": 0.875
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "canonical_model_id": "openai/o3"
+      },
+      "openai/gpt-5.4": {
+        "id": "openai/gpt-5.4",
+        "name": "GPT 5.4",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 15,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4"
+      },
+      "openai/gpt-5.4-pro": {
+        "id": "openai/gpt-5.4-pro",
+        "name": "GPT 5.4 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 30,
+          "output": 180
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4-pro"
+      },
+      "openai/gpt-oss-safeguard-120b": {
+        "id": "openai/gpt-oss-safeguard-120b",
+        "name": "GPT OSS Safeguard 120B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16000
+        },
+        "canonical_model_id": "openai/gpt-oss-safeguard-120b"
+      },
+      "openai/gpt-3.5-turbo": {
+        "id": "openai/gpt-3.5-turbo",
+        "name": "GPT-3.5 Turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.5,
+          "output": 1.5
+        },
+        "limit": {
+          "context": 16385,
+          "output": 4096
+        },
+        "canonical_model_id": "openai/gpt-3.5-turbo"
+      },
+      "openai/gpt-5.2-fast": {
+        "id": "openai/gpt-5.2-fast",
+        "name": "GPT 5.2 (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3.5,
+          "output": 28,
+          "cache_read": 0.35
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.2"
+      },
+      "openai/gpt-4o-transcribe": {
+        "id": "openai/gpt-4o-transcribe",
+        "name": "GPT-4o Transcribe",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "openai/gpt-5.5-pro": {
+        "id": "openai/gpt-5.5-pro",
+        "name": "GPT 5.5 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 30,
+          "output": 180
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.5-pro"
+      },
+      "openai/text-embedding-3-small": {
+        "id": "openai/text-embedding-3-small",
+        "name": "text-embedding-3-small",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "openai/gpt-5.4-nano": {
+        "id": "openai/gpt-5.4-nano",
+        "name": "GPT 5.4 Nano",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.25,
+          "cache_read": 0.02
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4-nano"
+      },
+      "openai/gpt-realtime-2.1": {
+        "id": "openai/gpt-realtime-2.1",
+        "name": "gpt-realtime-2.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 24,
+          "cache_read": 0.4
+        },
+        "limit": {
+          "context": 128000,
+          "output": 32000
+        },
+        "canonical_model_id": "openai/gpt-realtime-2.1"
+      },
+      "openai/gpt-5.2-codex": {
+        "id": "openai/gpt-5.2-codex",
+        "name": "GPT-5.2-Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.2-codex"
+      },
+      "openai/gpt-4o-fast": {
+        "id": "openai/gpt-4o-fast",
+        "name": "GPT-4o (Fast)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4.25,
+          "output": 17,
+          "cache_read": 2.125
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "openai/gpt-4o"
+      },
+      "openai/gpt-5.1-codex": {
+        "id": "openai/gpt-5.1-codex",
+        "name": "GPT-5.1-Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.13
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.1-codex"
+      },
+      "openai/gpt-6.1-sol-fast": {
+        "id": "openai/gpt-6.1-sol-fast",
+        "name": "GPT-6.1 Sol (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.2,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6.1-sol"
+      },
+      "openai/gpt-live-1": {
+        "id": "openai/gpt-live-1",
+        "name": "GPT-Live 1",
+        "reasoning": false,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["text", "audio"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "openai/gpt-realtime-1.5": {
+        "id": "openai/gpt-realtime-1.5",
+        "name": "GPT-Realtime-1.5",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 16,
+          "cache_read": 0.4
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "openai/gpt-4.1-nano-fast": {
+        "id": "openai/gpt-4.1-nano-fast",
+        "name": "GPT-4.1 nano (Fast)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 0.8,
+          "cache_read": 0.05
+        },
+        "limit": {
+          "context": 1047576,
+          "output": 32768
+        },
+        "canonical_model_id": "openai/gpt-4.1-nano"
+      },
+      "openai/gpt-5-codex": {
+        "id": "openai/gpt-5-codex",
+        "name": "GPT-5-Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.13
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5-codex"
+      },
+      "openai/gpt-image-2": {
+        "id": "openai/gpt-image-2",
+        "name": "GPT Image 2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "openai/gpt-image-2"
+      },
+      "openai/gpt-5.6-luna-fast": {
+        "id": "openai/gpt-5.6-luna-fast",
+        "name": "GPT 5.6 Luna (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 2.4,
+          "cache_read": 0.04,
+          "cache_write": 0.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-luna"
+      },
+      "openai/gpt-6-astra-fast": {
+        "id": "openai/gpt-6-astra-fast",
+        "name": "GPT-6 Astra (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 20,
+          "output": 100,
+          "cache_read": 2,
+          "cache_write": 25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-astra-fast"
+      },
+      "openai/gpt-5.2-pro": {
+        "id": "openai/gpt-5.2-pro",
+        "name": "GPT 5.2 ",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 21,
+          "output": 168
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.2-pro"
+      },
+      "openai/gpt-5.1-thinking-fast": {
+        "id": "openai/gpt-5.1-thinking-fast",
+        "name": "GPT 5.1 Thinking (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 20,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "openai/text-embedding-ada-002": {
+        "id": "openai/text-embedding-ada-002",
+        "name": "text-embedding-ada-002",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "openai/gpt-5.3-codex": {
+        "id": "openai/gpt-5.3-codex",
+        "name": "GPT 5.3 Codex",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.3-codex"
+      },
+      "openai/whisper-1": {
+        "id": "openai/whisper-1",
+        "name": "Whisper",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["audio"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "openai/gpt-5.3-codex-fast": {
+        "id": "openai/gpt-5.3-codex-fast",
+        "name": "GPT 5.3 Codex (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3.5,
+          "output": 28,
+          "cache_read": 0.35
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.3-codex"
+      },
+      "openai/gpt-5.5-fast": {
+        "id": "openai/gpt-5.5-fast",
+        "name": "GPT 5.5 (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 12.5,
+          "output": 75,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.5"
+      },
+      "openai/gpt-image-2.5-flare": {
+        "id": "openai/gpt-image-2.5-flare",
+        "name": "GPT Image 2.5 Flare",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "openai/gpt-image-2.5-flare"
+      },
+      "openai/gpt-5.4-fast": {
+        "id": "openai/gpt-5.4-fast",
+        "name": "GPT 5.4 (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4"
+      },
+      "openai/gpt-5.6-sol-fast": {
+        "id": "openai/gpt-5.6-sol-fast",
+        "name": "GPT 5.6 Sol (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 8,
+          "output": 40,
+          "cache_read": 0.8,
+          "cache_write": 10
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-sol"
+      },
+      "openai/o4-mini-fast": {
+        "id": "openai/o4-mini-fast",
+        "name": "o4-mini (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 8,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "canonical_model_id": "openai/o4-mini"
+      },
+      "openai/gpt-5-pro": {
+        "id": "openai/gpt-5-pro",
+        "name": "GPT-5 pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 120
+        },
+        "limit": {
+          "context": 400000,
+          "output": 272000
+        },
+        "canonical_model_id": "openai/gpt-5-pro"
+      },
+      "openai/gpt-6.1-sol": {
+        "id": "openai/gpt-6.1-sol",
+        "name": "GPT-6.1 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.1,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6.1-sol"
+      },
+      "openai/gpt-5.1-thinking": {
+        "id": "openai/gpt-5.1-thinking",
+        "name": "GPT 5.1 Thinking",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "openai/text-embedding-3-large": {
+        "id": "openai/text-embedding-3-large",
+        "name": "text-embedding-3-large",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 8192,
+          "output": 1536
+        }
+      },
+      "openai/gpt-6-astra": {
+        "id": "openai/gpt-6-astra",
+        "name": "GPT-6 Astra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 50,
+          "cache_read": 1,
+          "cache_write": 12.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-astra"
+      },
+      "openai/gpt-5.4-mini-fast": {
+        "id": "openai/gpt-5.4-mini-fast",
+        "name": "GPT 5.4 Mini (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.5,
+          "output": 9,
+          "cache_read": 0.15
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4-mini"
+      },
+      "openai/gpt-realtime-mini": {
+        "id": "openai/gpt-realtime-mini",
+        "name": "GPT-Realtime mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.4,
+          "cache_read": 0.06
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "openai/gpt-5-mini-fast": {
+        "id": "openai/gpt-5-mini-fast",
+        "name": "GPT-5 mini (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.45,
+          "output": 3.6,
+          "cache_read": 0.045
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5-mini"
+      },
+      "openai/o3-pro": {
+        "id": "openai/o3-pro",
+        "name": "o3 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 20,
+          "output": 80
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "canonical_model_id": "openai/o3-pro"
+      },
+      "openai/gpt-oss-20b": {
+        "id": "openai/gpt-oss-20b",
+        "name": "GPT OSS 20B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.03,
+          "output": 0.14
+        },
+        "limit": {
+          "context": 131072,
+          "output": 8192
+        },
+        "canonical_model_id": "openai/gpt-oss-20b"
+      },
+      "openai/gpt-oss-safeguard-20b": {
+        "id": "openai/gpt-oss-safeguard-20b",
+        "name": "gpt-oss-safeguard-20b",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.2
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16000
+        },
+        "canonical_model_id": "openai/gpt-oss-safeguard-20b"
+      },
+      "openai/gpt-image-2.5-sunburst": {
+        "id": "openai/gpt-image-2.5-sunburst",
+        "name": "GPT Image 2.5 Sunburst",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "openai/gpt-image-2.5-sunburst"
+      },
+      "openai/gpt-5.6-terra-fast": {
+        "id": "openai/gpt-5.6-terra-fast",
+        "name": "GPT 5.6 Terra (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 24,
+          "cache_read": 0.4,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-terra"
+      },
+      "openai/gpt-image-1": {
+        "id": "openai/gpt-image-1",
+        "name": "GPT Image 1",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 40,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "openai/gpt-image-1"
+      },
+      "openai/gpt-5.4-mini": {
+        "id": "openai/gpt-5.4-mini",
+        "name": "GPT 5.4 Mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.75,
+          "output": 4.5,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.4-mini"
+      },
+      "openai/gpt-5.6-luna": {
+        "id": "openai/gpt-5.6-luna",
+        "name": "GPT 5.6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.2,
+          "cache_read": 0.02,
+          "cache_write": 0.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-luna"
+      },
+      "openai/gpt-5.1-codex-max": {
+        "id": "openai/gpt-5.1-codex-max",
+        "name": "GPT 5.1 Codex Max",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.1-codex-max"
+      },
+      "openai/gpt-5.2": {
+        "id": "openai/gpt-5.2",
+        "name": "GPT-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.75,
+          "output": 14,
+          "cache_read": 0.175
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.2"
+      },
+      "openai/gpt-5.5": {
+        "id": "openai/gpt-5.5",
+        "name": "GPT 5.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "minimal", "low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.5"
+      },
+      "openai/gpt-6-sol-fast": {
+        "id": "openai/gpt-6-sol-fast",
+        "name": "GPT-6 Sol (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.4,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-sol"
+      },
+      "openai/tts-1": {
+        "id": "openai/tts-1",
+        "name": "TTS-1",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["audio"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "openai/gpt-6-luna-fast": {
+        "id": "openai/gpt-6-luna-fast",
+        "name": "GPT-6 Luna (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1,
+          "cache_read": 0.02,
+          "cache_write": 0.25
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-luna"
+      },
+      "openai/gpt-5-fast": {
+        "id": "openai/gpt-5-fast",
+        "name": "GPT-5 (Fast)",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 20,
+          "cache_read": 0.25
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5"
+      },
+      "openai/gpt-realtime-2": {
+        "id": "openai/gpt-realtime-2",
+        "name": "gpt-realtime-2",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "audio"],
+          "output": ["text", "audio"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 24,
+          "cache_read": 0.4
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "openai/gpt-4.1-fast": {
+        "id": "openai/gpt-4.1-fast",
+        "name": "GPT-4.1 (Fast)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 3.5,
+          "output": 14,
+          "cache_read": 0.875
+        },
+        "limit": {
+          "context": 1047576,
+          "output": 32768
+        },
+        "canonical_model_id": "openai/gpt-4.1"
+      },
+      "openai/gpt-6-luna": {
+        "id": "openai/gpt-6-luna",
+        "name": "GPT-6 Luna",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.5,
+          "cache_read": 0.01,
+          "cache_write": 0.125
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-luna"
+      },
+      "openai/gpt-image-1-mini": {
+        "id": "openai/gpt-image-1-mini",
+        "name": "GPT Image 1 Mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 8,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "openai/gpt-4o-mini-transcribe": {
+        "id": "openai/gpt-4o-mini-transcribe",
+        "name": "GPT-4o mini Transcribe",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["audio"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 5
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "openai/gpt-image-1.5": {
+        "id": "openai/gpt-image-1.5",
+        "name": "GPT Image 1.5",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["image"]
+        },
+        "cost": {
+          "input": 5,
+          "output": 32,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "openai/gpt-image-1.5"
+      },
+      "openai/gpt-5.6-terra": {
+        "id": "openai/gpt-5.6-terra",
+        "name": "GPT 5.6 Terra",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 12,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-terra"
+      },
+      "openai/gpt-oss-120b": {
+        "id": "openai/gpt-oss-120b",
+        "name": "GPT OSS 120B",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.5,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 131072,
+          "output": 131072
+        },
+        "canonical_model_id": "openai/gpt-oss-120b"
+      },
+      "openai/gpt-5.1-codex-mini": {
+        "id": "openai/gpt-5.1-codex-mini",
+        "name": "GPT-5.1 Codex mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2,
+          "cache_read": 0.03
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.1-codex-mini"
+      },
+      "openai/gpt-5.6-sol": {
+        "id": "openai/gpt-5.6-sol",
+        "name": "GPT 5.6 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4,
+          "output": 20,
+          "cache_read": 0.4,
+          "cache_write": 5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5.6-sol"
+      },
+      "openai/gpt-4o-mini-fast": {
+        "id": "openai/gpt-4o-mini-fast",
+        "name": "GPT-4o mini (Fast)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 1,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        },
+        "canonical_model_id": "openai/gpt-4o-mini"
+      },
+      "openai/gpt-realtime-whisper": {
+        "id": "openai/gpt-realtime-whisper",
+        "name": "gpt-realtime-whisper",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["audio"],
+          "output": ["text"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        },
+        "canonical_model_id": "openai/gpt-realtime-whisper"
+      },
+      "openai/gpt-6-sol": {
+        "id": "openai/gpt-6-sol",
+        "name": "GPT-6 Sol",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high", "xhigh", "max"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 10,
+          "cache_read": 0.2,
+          "cache_write": 2.5
+        },
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-6-sol"
+      },
+      "openai/tts-1-hd": {
+        "id": "openai/tts-1-hd",
+        "name": "TTS-1 HD",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["audio"]
+        },
+        "limit": {
+          "context": 0,
+          "output": 0
+        }
+      },
+      "openai/gpt-5": {
+        "id": "openai/gpt-5",
+        "name": "GPT-5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 10,
+          "cache_read": 0.125
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        },
+        "canonical_model_id": "openai/gpt-5"
+      },
+      "openai/o3": {
+        "id": "openai/o3",
+        "name": "o3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 8,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        }
+      },
+      "openai/gpt-4-turbo": {
+        "id": "openai/gpt-4-turbo",
+        "name": "GPT-4 Turbo",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 10,
+          "output": 30
+        },
+        "limit": {
+          "context": 128000,
+          "output": 4096
+        },
+        "status": "deprecated"
+      },
+      "openai/gpt-4.1-mini": {
+        "id": "openai/gpt-4.1-mini",
+        "name": "GPT-4.1 mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4,
+          "output": 1.6,
+          "cache_read": 0.1
+        },
+        "limit": {
+          "context": 1047576,
+          "output": 32768
+        }
+      },
+      "openai/gpt-4.1": {
+        "id": "openai/gpt-4.1",
+        "name": "GPT-4.1",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 8,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 1047576,
+          "output": 32768
+        }
+      },
+      "openai/gpt-4o-mini": {
+        "id": "openai/gpt-4o-mini",
+        "name": "GPT-4o mini",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.6,
+          "cache_read": 0.075
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        }
+      },
+      "openai/o1": {
+        "id": "openai/o1",
+        "name": "o1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 15,
+          "output": 60,
+          "cache_read": 7.5
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "status": "deprecated"
+      },
+      "openai/gpt-5-nano": {
+        "id": "openai/gpt-5-nano",
+        "name": "GPT-5 Nano",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.05,
+          "output": 0.4,
+          "cache_read": 0.005
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "openai/gpt-4.1-nano": {
+        "id": "openai/gpt-4.1-nano",
+        "name": "GPT-4.1 nano",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.1,
+          "output": 0.4,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 1047576,
+          "output": 32768
+        },
+        "status": "deprecated"
+      },
+      "openai/o3-mini": {
+        "id": "openai/o3-mini",
+        "name": "o3-mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 4.4,
+          "cache_read": 0.55
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "status": "deprecated"
+      },
+      "openai/o4-mini": {
+        "id": "openai/o4-mini",
+        "name": "o4-mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.1,
+          "output": 4.4,
+          "cache_read": 0.275
+        },
+        "limit": {
+          "context": 200000,
+          "output": 100000
+        },
+        "status": "deprecated"
+      },
+      "openai/gpt-5-mini": {
+        "id": "openai/gpt-5-mini",
+        "name": "GPT-5 Mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.25,
+          "output": 2,
+          "cache_read": 0.025
+        },
+        "limit": {
+          "context": 400000,
+          "output": 128000
+        }
+      },
+      "openai/gpt-4o": {
+        "id": "openai/gpt-4o",
+        "name": "GPT-4o",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 10,
+          "cache_read": 1.25
+        },
+        "limit": {
+          "context": 128000,
+          "output": 16384
+        }
+      }
+    }
+  },
+  "volcengine": {
+    "id": "volcengine",
+    "name": "Volcengine Ark",
+    "env": ["ARK_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://ark.cn-beijing.volces.com/api/v3",
+    "models": {
+      "glm-5-3-flash-260828": {
+        "id": "glm-5-3-flash-260828",
+        "name": "GLM-5.3-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.11875,
+          "output": 0.41563,
+          "cache_read": 0.03414
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "doubao-seed-1-6-251015": {
+        "id": "doubao-seed-1-6-251015",
+        "name": "Seed 1.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.11875,
+          "output": 1.18747,
+          "cache_read": 0.02375
+        },
+        "limit": {
+          "context": 256000,
+          "output": 64000
+        },
+        "canonical_model_id": "bytedance-seed/seed-1-6"
+      },
+      "doubao-seed-2-0-pro-260215": {
+        "id": "doubao-seed-2-0-pro-260215",
+        "name": "Seed 2.0 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.47499,
+          "output": 2.37494,
+          "cache_read": 0.095
+        },
+        "limit": {
+          "context": 256000,
+          "output": 128000
+        },
+        "canonical_model_id": "bytedance-seed/seed-2.0-pro"
+      },
+      "doubao-seed-2-0-lite-260428": {
+        "id": "doubao-seed-2-0-lite-260428",
+        "name": "Seed 2.0 Lite",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.08906,
+          "output": 0.53436,
+          "cache_read": 0.01781
+        },
+        "limit": {
+          "context": 256000,
+          "output": 131072
+        },
+        "canonical_model_id": "bytedance-seed/seed-2.0-lite"
+      },
+      "doubao-seed-2-1-pro-260628": {
+        "id": "doubao-seed-2-1-pro-260628",
+        "name": "Seed 2.1 Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.8906,
+          "output": 4.45301,
+          "cache_read": 0.17812
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        },
+        "canonical_model_id": "bytedance-seed/seed-2.1-pro"
+      },
+      "doubao-seed-1-6-vision-250815": {
+        "id": "doubao-seed-1-6-vision-250815",
+        "name": "Seed 1.6 Vision",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.11875,
+          "output": 1.18747,
+          "cache_read": 0.02375
+        },
+        "limit": {
+          "context": 256000,
+          "output": 32000
+        },
+        "canonical_model_id": "bytedance-seed/seed-1-6-vision"
+      },
+      "doubao-seed-2-0-mini-260428": {
+        "id": "doubao-seed-2-0-mini-260428",
+        "name": "Seed 2.0 Mini",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.02969,
+          "output": 0.29687,
+          "cache_read": 0.00594
+        },
+        "limit": {
+          "context": 256000,
+          "output": 131072
+        },
+        "canonical_model_id": "bytedance-seed/seed-2.0-mini"
+      },
+      "doubao-seed-2-0-code-preview-260215": {
+        "id": "doubao-seed-2-0-code-preview-260215",
+        "name": "Seed 2.0 Code",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.47499,
+          "output": 2.37494,
+          "cache_read": 0.095
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "canonical_model_id": "bytedance-seed/seed-2.0-code"
+      },
+      "doubao-seed-2-1-turbo-260628": {
+        "id": "doubao-seed-2-1-turbo-260628",
+        "name": "Seed 2.1 Turbo",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4453,
+          "output": 2.22651,
+          "cache_read": 0.08906
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        },
+        "canonical_model_id": "bytedance-seed/seed-2.1-turbo"
+      },
+      "glm-5-2-260617": {
+        "id": "glm-5-2-260617",
+        "name": "GLM-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.18747,
+          "output": 4.15615,
+          "cache_read": 0.29687
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "doubao-seed-1-8-251228": {
+        "id": "doubao-seed-1-8-251228",
+        "name": "Seed 1.8",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.11875,
+          "output": 1.18747,
+          "cache_read": 0.02375
+        },
+        "limit": {
+          "context": 256000,
+          "output": 64000
+        },
+        "canonical_model_id": "bytedance-seed/seed-1-8"
+      },
+      "doubao-seed-evolving": {
+        "id": "doubao-seed-evolving",
+        "name": "Seed Evolving",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "minimal",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.8906,
+          "output": 4.45301,
+          "cache_read": 0.17812
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        },
+        "canonical_model_id": "bytedance-seed/seed-evolving"
+      },
+      "doubao-seed-1-6-flash-250828": {
+        "id": "doubao-seed-1-6-flash-250828",
+        "name": "Seed 1.6 Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.02227,
+          "output": 0.22265,
+          "cache_read": 0.00445
+        },
+        "limit": {
+          "context": 256000,
+          "output": 32000
+        },
+        "canonical_model_id": "bytedance-seed/seed-1-6-flash"
+      },
+      "doubao-seed-character-260628": {
+        "id": "doubao-seed-character-260628",
+        "name": "Seed Character",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "high"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.11875,
+          "output": 0.29687,
+          "cache_read": 0.02375
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        },
+        "canonical_model_id": "bytedance-seed/seed-character"
+      },
+      "deepseek-v4-pro-ga-260813": {
+        "id": "deepseek-v4-pro-ga-260813",
+        "name": "DeepSeek V4 Pro 0813",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.3359,
+          "output": 4.00771,
+          "cache_read": 0.04453
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-pro-0813"
+      },
+      "deepseek-v4-flash-ga-260731": {
+        "id": "deepseek-v4-flash-ga-260731",
+        "name": "DeepSeek V4 Flash 0731",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          },
+          {
+            "type": "effort",
+            "values": ["minimal", "low", "medium", "high"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.4453,
+          "output": 1.3359,
+          "cache_read": 0.01484
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 384000
+        },
+        "canonical_model_id": "deepseek/deepseek-v4-flash-0731"
+      }
+    }
+  },
+  "xai": {
+    "id": "xai",
+    "name": "xAI",
+    "env": ["XAI_API_KEY"],
+    "npm": "@ai-sdk/xai",
+    "models": {
+      "grok-4.7": {
+        "id": "grok-4.7",
+        "name": "Grok 4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "canonical_model_id": "xai/grok-4.7"
+      },
+      "grok-imagine-image": {
+        "id": "grok-imagine-image",
+        "name": "Grok Imagine Image",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["image", "pdf"]
+        },
+        "limit": {
+          "context": 16000,
+          "output": 0
+        }
+      },
+      "grok-imagine-video": {
+        "id": "grok-imagine-video",
+        "name": "Grok Imagine Video",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 1024,
+          "output": 0
+        }
+      },
+      "grok-4.3": {
+        "id": "grok-4.3",
+        "name": "Grok 4.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["none", "low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 30000
+        }
+      },
+      "grok-4.20-0309-reasoning": {
+        "id": "grok-4.20-0309-reasoning",
+        "name": "Grok 4.20 (Reasoning)",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 30000
+        }
+      },
+      "grok-imagine-video-1.5": {
+        "id": "grok-imagine-video-1.5",
+        "name": "Grok Imagine Video 1.5",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "audio", "pdf"],
+          "output": ["video"]
+        },
+        "limit": {
+          "context": 1024,
+          "output": 0
+        },
+        "canonical_model_id": "xai/grok-imagine-video-1.5"
+      },
+      "grok-4.5": {
+        "id": "grok-4.5",
+        "name": "Grok 4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.3
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "canonical_model_id": "xai/grok-4.5"
+      },
+      "grok-4.20-0309-non-reasoning": {
+        "id": "grok-4.20-0309-non-reasoning",
+        "name": "Grok 4.20 (Non-Reasoning)",
+        "reasoning": false,
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 30000
+        }
+      },
+      "grok-imagine-image-quality": {
+        "id": "grok-imagine-image-quality",
+        "name": "Grok Imagine Image Quality",
+        "reasoning": false,
+        "temperature": false,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["image", "pdf"]
+        },
+        "limit": {
+          "context": 16000,
+          "output": 0
+        },
+        "canonical_model_id": "xai/grok-imagine-image-quality"
+      },
+      "grok-build-0.1": {
+        "id": "grok-build-0.1",
+        "name": "Grok Build 0.1",
+        "reasoning": true,
+        "reasoning_options": [],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 2,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 256000,
+          "output": 256000
+        }
+      },
+      "grok-4.20-multi-agent-0309": {
+        "id": "grok-4.20-multi-agent-0309",
+        "name": "Grok 4.20 Multi-Agent",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.25,
+          "output": 2.5,
+          "cache_read": 0.2
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 30000
+        }
+      },
+      "grok-4.6": {
+        "id": "grok-4.6",
+        "name": "Grok 4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "medium", "high", "xhigh"]
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 2,
+          "output": 6,
+          "cache_read": 0.5
+        },
+        "limit": {
+          "context": 500000,
+          "output": 500000
+        },
+        "canonical_model_id": "xai/grok-4.6"
+      }
+    }
+  },
+  "xiaomi": {
+    "id": "xiaomi",
+    "name": "Xiaomi",
+    "env": ["XIAOMI_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://api.xiaomimimo.com/v1",
+    "models": {
+      "mimo-v2.6-pro": {
+        "id": "mimo-v2.6-pro",
+        "name": "MiMo-V2.6-Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.435,
+          "output": 0.87,
+          "cache_read": 0.0036
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        }
+      },
+      "mimo-v2-flash": {
+        "id": "mimo-v2-flash",
+        "name": "MiMo-V2-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.0028
+        },
+        "limit": {
+          "context": 262144,
+          "output": 65536
+        },
+        "status": "deprecated"
+      },
+      "mimo-v2.5": {
+        "id": "mimo-v2.5",
+        "name": "MiMo-V2.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.0028
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        }
+      },
+      "mimo-v2-omni": {
+        "id": "mimo-v2-omni",
+        "name": "MiMo-V2-Omni",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.0028
+        },
+        "limit": {
+          "context": 262144,
+          "output": 131072
+        },
+        "status": "deprecated"
+      },
+      "mimo-v2.6-pro-ultraspeed": {
+        "id": "mimo-v2.6-pro-ultraspeed",
+        "name": "MiMo-V2.6-Pro-UltraSpeed",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 4.35,
+          "output": 8.7,
+          "cache_read": 0.036
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        }
+      },
+      "mimo-v2-pro": {
+        "id": "mimo-v2-pro",
+        "name": "MiMo-V2-Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.435,
+          "output": 0.87,
+          "cache_read": 0.0036
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "status": "deprecated"
+      },
+      "mimo-v2.5-pro": {
+        "id": "mimo-v2.5-pro",
+        "name": "MiMo-V2.5-Pro",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.435,
+          "output": 0.87,
+          "cache_read": 0.0036
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        }
+      },
+      "mimo-v2.6-flash": {
+        "id": "mimo-v2.6-flash",
+        "name": "MiMo-V2.6-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "audio", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.14,
+          "output": 0.28,
+          "cache_read": 0.0028
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        }
+      },
+      "mimo-v2.5-pro-ultraspeed": {
+        "id": "mimo-v2.5-pro-ultraspeed",
+        "name": "MiMo-V2.5-Pro-UltraSpeed",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.305,
+          "output": 2.61,
+          "cache_read": 0.0108
+        },
+        "limit": {
+          "context": 1048576,
+          "output": 131072
+        },
+        "status": "beta"
+      }
+    }
+  },
+  "zai": {
+    "id": "zai",
+    "name": "Z.AI",
+    "env": ["ZHIPU_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://api.z.ai/api/paas/v4",
+    "models": {
+      "glm-4.6v": {
+        "id": "glm-4.6v",
+        "name": "GLM-4.6V",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 0.9
+        },
+        "limit": {
+          "context": 128000,
+          "output": 32768
+        }
+      },
+      "glm-4.5": {
+        "id": "glm-4.5",
+        "name": "GLM-4.5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.2,
+          "cache_read": 0.11,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 131072,
+          "output": 98304
+        }
+      },
+      "glm-5v-turbo": {
+        "id": "glm-5v-turbo",
+        "name": "GLM-5V-Turbo",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.2,
+          "output": 4,
+          "cache_read": 0.24,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 200000,
+          "output": 131072
+        }
+      },
+      "glm-5.3-flash": {
+        "id": "glm-5.3-flash",
+        "name": "GLM-5.3-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.15,
+          "output": 0.5,
+          "cache_read": 0.03,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "glm-4.6": {
+        "id": "glm-4.6",
+        "name": "GLM-4.6",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.2,
+          "cache_read": 0.11,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "glm-5": {
+        "id": "glm-5",
+        "name": "GLM-5",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1,
+          "output": 3.2,
+          "cache_read": 0.2,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5"
+      },
+      "glm-4.6v-flash": {
+        "id": "glm-4.6v-flash",
+        "name": "GLM-4.6V-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 128000,
+          "output": 32768
+        },
+        "canonical_model_id": "zhipuai/glm-4.6v-flash"
+      },
+      "glm-4.5v": {
+        "id": "glm-4.5v",
+        "name": "GLM-4.5V",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 1.8
+        },
+        "limit": {
+          "context": 64000,
+          "output": 16384
+        }
+      },
+      "glm-5.3-flashx": {
+        "id": "glm-5.3-flashx",
+        "name": "GLM-5.3-FlashX",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.37,
+          "output": 1.25,
+          "cache_read": 0.075,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "glm-4.7-flash": {
+        "id": "glm-4.7-flash",
+        "name": "GLM-4.7-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 200000,
+          "output": 131072
+        }
+      },
+      "glm-4.7": {
+        "id": "glm-4.7",
+        "name": "GLM-4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.6,
+          "output": 2.2,
+          "cache_read": 0.11,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "glm-4.5-flash": {
+        "id": "glm-4.5-flash",
+        "name": "GLM-4.5-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 131072,
+          "output": 98304
+        }
+      },
+      "glm-5.2": {
+        "id": "glm-5.2",
+        "name": "GLM-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "glm-5.1": {
+        "id": "glm-5.1",
+        "name": "GLM-5.1",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 200000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.1"
+      },
+      "glm-4.7-flashx": {
+        "id": "glm-4.7-flashx",
+        "name": "GLM-4.7-FlashX",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.07,
+          "output": 0.4,
+          "cache_read": 0.01,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 200000,
+          "output": 131072
+        }
+      },
+      "glm-5-turbo": {
+        "id": "glm-5-turbo",
+        "name": "GLM-5-Turbo",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.2,
+          "output": 4,
+          "cache_read": 0.24,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 200000,
+          "output": 131072
+        }
+      },
+      "glm-4.5-air": {
+        "id": "glm-4.5-air",
+        "name": "GLM-4.5-Air",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.2,
+          "output": 1.1,
+          "cache_read": 0.03,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 131072,
+          "output": 98304
+        }
+      },
+      "glm-5.3": {
+        "id": "glm-5.3",
+        "name": "GLM-5.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 1.4,
+          "output": 4.4,
+          "cache_read": 0.26,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      }
+    }
+  },
+  "zai-coding-plan": {
+    "id": "zai-coding-plan",
+    "name": "Z.AI Coding Plan",
+    "env": ["ZHIPU_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://api.z.ai/api/coding/paas/v4",
+    "models": {
+      "glm-5.3-flash": {
+        "id": "glm-5.3-flash",
+        "name": "GLM-5.3-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "glm-5.3-highspeed": {
+        "id": "glm-5.3-highspeed",
+        "name": "GLM-5.3 Highspeed",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "glm-5.2-highspeed": {
+        "id": "glm-5.2-highspeed",
+        "name": "GLM-5.2 Highspeed",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "glm-4.7": {
+        "id": "glm-4.7",
+        "name": "GLM-4.7",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 204800,
+          "output": 131072
+        }
+      },
+      "glm-5.2": {
+        "id": "glm-5.2",
+        "name": "GLM-5.2",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.2"
+      },
+      "glm-5-turbo": {
+        "id": "glm-5-turbo",
+        "name": "GLM-5-Turbo",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 200000,
+          "output": 131072
+        }
+      },
+      "glm-5.3": {
+        "id": "glm-5.3",
+        "name": "GLM-5.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      }
+    }
+  },
+  "zhipuai-coding-plan": {
+    "id": "zhipuai-coding-plan",
+    "name": "Zhipu AI Coding Plan",
+    "env": ["ZHIPU_API_KEY"],
+    "npm": "@ai-sdk/openai-compatible",
+    "api": "https://open.bigmodel.cn/api/coding/paas/v4",
+    "models": {
+      "glm-5.3-flash": {
+        "id": "glm-5.3-flash",
+        "name": "GLM-5.3-Flash",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video", "pdf"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3-flash"
+      },
+      "glm-5.3-highspeed": {
+        "id": "glm-5.3-highspeed",
+        "name": "GLM-5.3 Highspeed",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "glm-5.3": {
+        "id": "glm-5.3",
+        "name": "GLM-5.3",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": ["low", "high", "max"]
+          }
+        ],
+        "interleaved": {
+          "field": "reasoning_content"
+        },
+        "temperature": true,
+        "modalities": {
+          "input": ["text"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0,
+          "output": 0,
+          "cache_read": 0,
+          "cache_write": 0
+        },
+        "limit": {
+          "context": 1000000,
+          "output": 131072
+        },
+        "canonical_model_id": "zhipuai/glm-5.3"
+      },
+      "glm-4.6v": {
+        "id": "glm-4.6v",
+        "name": "GLM-4.6V",
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "toggle"
+          }
+        ],
+        "temperature": true,
+        "modalities": {
+          "input": ["text", "image", "video"],
+          "output": ["text"]
+        },
+        "cost": {
+          "input": 0.3,
+          "output": 0.9
+        },
+        "limit": {
+          "context": 128000,
+          "output": 32768
+        }
+      }
+    }
+  }
+}
diff --git a/scripts/sync-model-reasoning.ts b/scripts/sync-model-reasoning.ts
new file mode 100644
index 0000000000..d26e860eb3
--- /dev/null
+++ b/scripts/sync-model-reasoning.ts
@@ -0,0 +1,212 @@
+/**
+ * Writes `src/model-reasoning.ts` in each provider package: each chat model's
+ * reasoning levels, as a type map for `chat({ reasoning })` and as a runtime
+ * map the adapter clamps with.
+ *
+ * The data is models.dev (`scripts/models-dev.models.json`) with the same
+ * level rule as `@tanstack/ai-models`. A model is looked up at the package's
+ * own provider first, then in the gateway list, then as the same model at
+ * another provider.
+ *
+ * Usage:
+ *   pnpm tsx scripts/sync-model-reasoning.ts
+ */
+
+import { readFile, readdir, writeFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { supportedReasoningLevels } from '../packages/ai/src/reasoning'
+import {
+  findSameModel,
+  reasoningMapFrom,
+  takesBudget,
+} from '../packages/ai-models/scripts/rules'
+import { models as openrouterModels } from './openrouter.models'
+import { models as vercelModels } from './vercel-gateway.models'
+import { fromOpenRouter, fromVercel } from './model-sync/gateway-models'
+import { REASONING_TARGETS } from './model-sync/reasoning-targets'
+import type { ModelReasoning } from '../packages/ai/src/reasoning'
+import type { DevModel } from '../packages/ai-models/scripts/rules'
+import type { ReasoningTarget } from './model-sync/reasoning-targets'
+
+const here = dirname(fileURLToPath(import.meta.url))
+type DevCatalog = Record<string, { models: Record<string, DevModel> }>
+
+/** The chat model ids of a target, in their list order. */
+async function modelIds(
+  target: ReasoningTarget,
+  dev: DevCatalog,
+): Promise<ReadonlyArray<string>> {
+  if (!target.models)
+    return Object.keys(dev[target.sources[0] ?? '']?.models ?? {})
+  const path = resolve(
+    here,
+    `../packages/${target.pkg}/src/${target.models.module}.ts`,
+  )
+  const module: Record<string, unknown> = await import(pathToFileURL(path).href)
+  const ids: Array<string> = []
+  for (const list of target.models.lists) {
+    const values = module[list]
+    if (!Array.isArray(values))
+      throw new Error(`${target.pkg}: ${list} is not an array`)
+    for (const value of values)
+      if (typeof value === 'string' && !ids.includes(value)) ids.push(value)
+  }
+  return ids
+}
+
+/** Where a target's model is on models.dev, or `undefined`. */
+function lookup(
+  target: ReasoningTarget,
+  id: string,
+  dev: DevCatalog,
+  gateways: Record<string, Map<string, DevModel>>,
+): DevModel | undefined {
+  const alias = target.aliases?.[id]
+  if (alias) {
+    const slash = alias.indexOf('/')
+    return dev[alias.slice(0, slash)]?.models[alias.slice(slash + 1)]
+  }
+  for (const source of target.sources) {
+    const model = dev[source]?.models[id]
+    if (model) return model
+  }
+  const gateway = target.gateway ? gateways[target.gateway]?.get(id) : undefined
+  return gateway ?? findSameModel(dev, id)?.model
+}
+
+/**
+ * Ollama's models are local, so models.dev does not list them. Its own model
+ * metadata marks thinking models with a `thinking` capability: gpt-oss takes
+ * the levels `low`, `medium`, and `high`, and the others turn thinking on or
+ * off.
+ */
+async function ollamaReasoning(): Promise<Map<string, ModelReasoning>> {
+  const dir = resolve(here, '../packages/ai-ollama/src/meta')
+  const found = new Map<string, ModelReasoning>()
+  for (const file of await readdir(dir)) {
+    if (!file.startsWith('model-meta-')) continue
+    const source = await readFile(resolve(dir, file), 'utf8')
+    const blocks = source.split(/\nconst [A-Za-z0-9_]+ = \{/).slice(1)
+    for (const block of blocks) {
+      const name = /name: '([^']+)'/.exec(block)?.[1]
+      if (!name) continue
+      const capabilities = /capabilities: \[([^\]]*)\]/.exec(block)?.[1] ?? ''
+      if (!capabilities.includes("'thinking'")) {
+        found.set(name, false)
+        continue
+      }
+      found.set(
+        name,
+        block.includes('OllamaChatRequestThinking_OpenAI')
+          ? {
+              map: {
+                off: null,
+                minimal: null,
+                low: 'low',
+                medium: 'medium',
+                high: 'high',
+              },
+              budget: false,
+            }
+          : {
+              map: {
+                off: 'false',
+                minimal: null,
+                low: null,
+                medium: null,
+                high: 'true',
+              },
+              budget: false,
+            },
+      )
+    }
+  }
+  return found
+}
+
+/** One model's runtime reasoning data. */
+function reasoningOf(model: DevModel): ModelReasoning {
+  if (model.reasoning !== true) return false
+  const map = reasoningMapFrom(model.reasoning_options)
+  return {
+    ...(map ? { map } : {}),
+    budget: takesBudget(model.reasoning_options),
+  }
+}
+
+const quote = (value: string) => `'${value.replace(/'/g, "\\'")}'`
+
+function fileFor(
+  target: ReasoningTarget,
+  entries: ReadonlyArray<[string, ModelReasoning]>,
+): string {
+  const typeName = `${target.typePrefix}ModelReasoningByName`
+  const constName = `${target.constPrefix}_MODEL_REASONING`
+  const typeRows = entries.flatMap(([id, reasoning]) =>
+    reasoning === false
+      ? []
+      : [
+          `  ${quote(id)}: { levels: ${supportedReasoningLevels(reasoning).map(quote).join(' | ')}; budget: ${reasoning.budget} }`,
+        ],
+  )
+  const runtimeRows = entries.map(
+    ([id, reasoning]) => `  ${quote(id)}: ${JSON.stringify(reasoning)},`,
+  )
+  return `// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
+import type { ModelReasoning } from '@tanstack/ai'
+
+/**
+ * Each model's reasoning levels, and whether it takes a token budget, for
+ * \`chat({ reasoning })\`. A model that is not here does not reason.
+ */
+export type ${typeName} = {
+${typeRows.join('\n')}
+}
+
+/** The same data at runtime. \`false\`: the model does not reason. */
+export const ${constName}: Readonly<Record<string, ModelReasoning>> = {
+${runtimeRows.join('\n')}
+}
+`
+}
+
+async function main() {
+  const dev: DevCatalog = JSON.parse(
+    await readFile(resolve(here, 'models-dev.models.json'), 'utf8'),
+  )
+  const gateways = {
+    openrouter: new Map(
+      openrouterModels.map((model) => [model.id, fromOpenRouter(model)]),
+    ),
+    vercel: new Map(vercelModels.map((model) => [model.id, fromVercel(model)])),
+  }
+  const ollama = await ollamaReasoning()
+  for (const target of REASONING_TARGETS) {
+    const entries: Array<[string, ModelReasoning]> = []
+    let missing = 0
+    for (const id of await modelIds(target, dev)) {
+      const local = target.pkg === 'ai-ollama' ? ollama.get(id) : undefined
+      if (local !== undefined) {
+        entries.push([id, local])
+        continue
+      }
+      const model = lookup(target, id, dev, gateways)
+      if (!model) {
+        missing++
+        continue
+      }
+      entries.push([id, reasoningOf(model)])
+    }
+    await writeFile(
+      resolve(here, `../packages/${target.pkg}/src/model-reasoning.ts`),
+      fileFor(target, entries),
+    )
+    const reasoning = entries.filter(([, value]) => value !== false).length
+    console.log(
+      `${target.pkg}: ${entries.length} models (${reasoning} reason), ${missing} not found`,
+    )
+  }
+}
+
+await main()

From ba8cc2bc0e4b93a6059311cc08da8debd3dafa95 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 14:08:43 +0200
Subject: [PATCH 087/286] feat(ai-openai, openai-base)!: chat({ reasoning })
 and openaiCompatible quirks

- openaiText maps `reasoning` to `reasoning.effort` (the model's value for
  the level, clamped with pi's rule) and asks for a summary. BREAKING: the
  `reasoning` field is gone from modelOptions (OpenAIReasoningOptions and
  OpenAIReasoningOptionsWithConcise are removed).
- openaiCompatible takes `compat` on the provider and on each `models`
  entry, plus a `reasoning` level map per model. The request follows pi's
  buildParams: the 11 thinking formats, the developer role, the token
  field, reasoning_content replay, store, strict tools, tool_stream, cache
  markers, and session headers. Without compat, the request is as before.
- openai-base: two protected hooks, includeUsageInStream() and
  requestHeaders(), and a TReasoning type parameter.
- @tanstack/ai adapter-internals: resolveReasoning() clamps a request and
  gives its provider value.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-openai/src/adapters/text.ts       |  30 +-
 packages/ai-openai/src/compatible/adapter.ts  | 103 ++++-
 packages/ai-openai/src/compatible/index.ts    |  64 ++-
 packages/ai-openai/src/compatible/quirks.ts   | 330 ++++++++++++++++
 packages/ai-openai/src/compatible/types.ts    |  91 ++++-
 packages/ai-openai/src/model-meta.ts          | 116 +-----
 .../src/text/text-provider-options.ts         |  56 ---
 .../tests/chat-per-model-type-safety.test.ts  |  43 +-
 .../ai-openai/tests/compatible-quirks.test.ts | 373 ++++++++++++++++++
 .../compatible-reasoning-types.test-d.ts      |  38 ++
 packages/ai-openai/tests/model-meta.test.ts   |  86 ++--
 .../ai-openai/tests/reasoning-request.test.ts |  82 ++++
 packages/ai/src/activities/chat/adapter.ts    |  11 +-
 packages/ai/src/adapter-internals.ts          |   2 +
 packages/ai/src/reasoning.ts                  |  35 +-
 packages/ai/tests/reasoning-types.test-d.ts   |  51 ++-
 packages/ai/tests/reasoning.test.ts           |  37 +-
 .../src/adapters/chat-completions-text.ts     |  45 ++-
 .../src/adapters/responses-text.ts            |   6 +-
 scripts/sync-provider-models.ts               |   4 +-
 20 files changed, 1323 insertions(+), 280 deletions(-)
 create mode 100644 packages/ai-openai/src/compatible/quirks.ts
 create mode 100644 packages/ai-openai/tests/compatible-quirks.test.ts
 create mode 100644 packages/ai-openai/tests/compatible-reasoning-types.test-d.ts
 create mode 100644 packages/ai-openai/tests/reasoning-request.test.ts

diff --git a/packages/ai-openai/src/adapters/text.ts b/packages/ai-openai/src/adapters/text.ts
index 75a90a6688..94a207732a 100644
--- a/packages/ai-openai/src/adapters/text.ts
+++ b/packages/ai-openai/src/adapters/text.ts
@@ -1,8 +1,10 @@
 import OpenAI from 'openai'
+import { resolveReasoning } from '@tanstack/ai/adapter-internals'
 import {
   OpenAIBaseResponsesTextAdapter,
   warnStrictFallback,
 } from '@tanstack/openai-base'
+import { OPENAI_MODEL_REASONING } from '../model-reasoning'
 import { validateTextProviderOptions } from '../text/text-provider-options'
 import { convertToolsToProviderFormat } from '../tools'
 import { getOpenAIApiKeyFromEnv } from '../utils/client'
@@ -19,6 +21,7 @@ import type {
 } from '../model-meta'
 import type { ResponseCreateParams } from 'openai/resources/responses/responses'
 import type { Modality, TextOptions } from '@tanstack/ai'
+import type { OpenAIModelReasoningByName } from '../model-reasoning'
 import type {
   ExternalTextProviderOptions,
   InternalTextProviderOptions,
@@ -55,6 +58,12 @@ type ResolveProviderOptions<TModel extends string> =
  * Resolve input modalities for a specific model.
  * If the model has explicit modalities in the map, use those; otherwise use all modalities.
  */
+/** The reasoning levels of a model, for `chat({ reasoning })`. `never`: none. */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof OpenAIModelReasoningByName
+    ? OpenAIModelReasoningByName[TModel]
+    : never
+
 type ResolveInputModalities<TModel extends string> =
   TModel extends keyof OpenAIModelInputModalitiesByName
     ? OpenAIModelInputModalitiesByName[TModel]
@@ -96,7 +105,8 @@ export class OpenAITextAdapter<
   TProviderOptions,
   TInputModalities,
   OpenAIMessageMetadataByModality,
-  TToolCapabilities
+  TToolCapabilities,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   override readonly name = 'openai' as const
@@ -156,6 +166,24 @@ export class OpenAITextAdapter<
       ...(tools && tools.length > 0 && { tools }),
     }
 
+    // `chat({ reasoning })`: the model's effort for the level, and a summary
+    // so the thinking text streams back. The SDK type has no `max` yet, so
+    // the field goes on with Object.assign.
+    const reasoning = resolveReasoning(
+      options.reasoning,
+      OPENAI_MODEL_REASONING[options.model],
+    )
+    if (reasoning?.value) {
+      Object.assign(request, {
+        reasoning: {
+          effort: reasoning.value,
+          ...(reasoning.summary && reasoning.level !== 'off'
+            ? { summary: 'auto' }
+            : {}),
+        },
+      })
+    }
+
     // Reasoning models 400 on `temperature`/`top_p`. Callers (and the summarize
     // adapter's low-temperature default) can't know a given model rejects them,
     // so drop the pair here — stripping only ever averts a guaranteed 400, never
diff --git a/packages/ai-openai/src/compatible/adapter.ts b/packages/ai-openai/src/compatible/adapter.ts
index ea41af0660..ba8a6f2ba4 100644
--- a/packages/ai-openai/src/compatible/adapter.ts
+++ b/packages/ai-openai/src/compatible/adapter.ts
@@ -2,10 +2,46 @@ import {
   OpenAIBaseChatCompletionsTextAdapter,
   OpenAIBaseResponsesTextAdapter,
 } from '@tanstack/openai-base'
+import {
+  applyRequestQuirks,
+  applyThinking,
+  replayReasoning,
+  sessionHeaders,
+} from './quirks'
 import type OpenAI from 'openai'
-import type { Modality } from '@tanstack/ai'
+import type {
+  ChatCompletionCreateParamsStreaming,
+  ChatCompletionMessageParam,
+} from 'openai/resources/chat/completions/completions'
+import type {
+  Modality,
+  ModelMessage,
+  ModelReasoning,
+  ReasoningCapability,
+  ReasoningMap,
+  TextOptions,
+} from '@tanstack/ai'
 import type { OpenAIMessageMetadataByModality } from '../message-types'
 import type { OpenAIBaseTextAdapterOptions } from '@tanstack/openai-base'
+import type { OpenAICompatibleCompat } from './quirks'
+
+/** One model's reasoning and request quirks, from its `models` entry and the provider. */
+export interface CompatibleModelConfig {
+  /** `false`: the model does not reason. `true`: no level map. Or its level map. */
+  reasoning?: boolean | ReasoningMap
+  compat?: OpenAICompatibleCompat
+}
+
+/** The runtime reasoning data of a `models` entry. `undefined`: not declared. */
+function modelReasoning(
+  reasoning: boolean | ReasoningMap | undefined,
+): ModelReasoning | undefined {
+  if (reasoning === undefined) return undefined
+  if (reasoning === false) return false
+  return reasoning === true
+    ? { budget: false }
+    : { map: reasoning, budget: false }
+}
 
 /**
  * Generic OpenAI-compatible adapter over the Chat Completions API
@@ -17,23 +53,86 @@ export class OpenAICompatibleChatAdapter<
   TProviderOptions extends Record<string, any> = Record<string, any>,
   TInputModalities extends ReadonlyArray<Modality> = ReadonlyArray<Modality>,
   TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,
+  TReasoning extends ReasoningCapability = never,
 > extends OpenAIBaseChatCompletionsTextAdapter<
   TModel,
   TProviderOptions,
   TInputModalities,
   OpenAIMessageMetadataByModality,
-  TToolCapabilities
+  TToolCapabilities,
+  TReasoning
 > {
   override readonly kind = 'text' as const
   readonly maxTokensKey = 'max_tokens'
+  private readonly compat: OpenAICompatibleCompat | undefined
+  private readonly reasoning: ModelReasoning | undefined
 
   constructor(
     client: OpenAI,
     model: TModel,
     name: string,
     options?: OpenAIBaseTextAdapterOptions,
+    config: CompatibleModelConfig = {},
   ) {
     super(model, name, client, options)
+    this.compat = config.compat
+    this.reasoning = modelReasoning(config.reasoning)
+  }
+
+  /**
+   * The request, then the provider's quirks: the thinking fields for
+   * `reasoning`, and (with `compat`) the instruction role, the token field,
+   * `store`, strict tools, `tool_stream`, and cache markers.
+   */
+  protected override mapOptionsToRequest(
+    options: TextOptions,
+  ): ChatCompletionCreateParamsStreaming {
+    const params = super.mapOptionsToRequest(options)
+    if (!options.reasoning && !this.compat) return params
+    // The quirks edit loose JSON. The OpenAI SDK type has no field for
+    // `thinking` or `enable_thinking`, so the result goes back on `params`.
+    const body: Record<string, unknown> = { ...params }
+    if (options.reasoning)
+      applyThinking(body, options.reasoning, this.reasoning, this.compat ?? {})
+    if (this.compat)
+      applyRequestQuirks(
+        body,
+        this.compat,
+        this.reasoning !== undefined && this.reasoning !== false,
+      )
+    for (const key of Object.keys(params))
+      if (!(key in body)) Reflect.deleteProperty(params, key)
+    return Object.assign(params, body)
+  }
+
+  /**
+   * An assistant message carries its thinking back as `reasoning_content`
+   * when the provider needs it (DeepSeek fails the second turn without it).
+   */
+  protected override convertMessage(
+    message: ModelMessage,
+  ): ChatCompletionMessageParam {
+    const converted = super.convertMessage(message)
+    const replay =
+      message.role === 'assistant' &&
+      this.compat?.requiresReasoningContentOnAssistantMessages === true &&
+      this.reasoning !== false
+    if (!replay) return converted
+    return Object.assign(converted, {
+      reasoning_content: replayReasoning(message.thinking),
+    })
+  }
+
+  protected override includeUsageInStream(): boolean {
+    return this.compat?.supportsUsageInStreaming !== false
+  }
+
+  protected override requestHeaders(
+    options: TextOptions,
+  ): Record<string, string> | undefined {
+    return this.compat
+      ? sessionHeaders(this.compat, options.conversationId ?? options.threadId)
+      : undefined
   }
 
   /**
diff --git a/packages/ai-openai/src/compatible/index.ts b/packages/ai-openai/src/compatible/index.ts
index 5154df2130..2e60bcd33b 100644
--- a/packages/ai-openai/src/compatible/index.ts
+++ b/packages/ai-openai/src/compatible/index.ts
@@ -1,4 +1,5 @@
 import OpenAI from 'openai'
+import type { Modality, ReasoningLevel } from '@tanstack/ai'
 import {
   OpenAICompatibleChatAdapter,
   OpenAICompatibleResponsesAdapter,
@@ -10,8 +11,10 @@ import type {
   OpenAICompatibleTextConfig,
   ResolveCompatInput,
   ResolveCompatOptions,
+  ResolveCompatReasoning,
   ResolveCompatTools,
 } from './types'
+import type { CompatibleModelConfig } from './adapter'
 
 export {
   OpenAICompatibleChatAdapter,
@@ -19,11 +22,37 @@ export {
 } from './adapter'
 export type {
   CompatibleApi,
+  CompatibleModelEntry,
   CompatibleModelInput,
+  LevelsOfMap,
   ModelNameOf,
   OpenAICompatibleConfig,
   OpenAICompatibleTextConfig,
 } from './types'
+export type {
+  OpenAICompatibleCompat,
+  OpenAICompatibleThinkingFormat,
+} from './quirks'
+
+/** One model's reasoning and quirks: its `models` entry over the provider's `compat`. */
+function modelConfig(
+  models: ReadonlyArray<CompatibleModelInput>,
+  model: string,
+  compat: OpenAICompatibleConfig<ReadonlyArray<CompatibleModelInput>>['compat'],
+): CompatibleModelConfig {
+  const entry = models.find(
+    (item) => typeof item !== 'string' && item.name === model,
+  )
+  const own =
+    typeof entry === 'object' && 'reasoning' in entry ? entry : undefined
+  const ownCompat =
+    typeof entry === 'object' && 'compat' in entry ? entry.compat : undefined
+  const merged = compat || ownCompat ? { ...compat, ...ownCompat } : undefined
+  return {
+    ...(own?.reasoning !== undefined ? { reasoning: own.reasoning } : {}),
+    ...(merged ? { compat: merged } : {}),
+  }
+}
 
 const DEFAULT_NAME = 'openai-compatible'
 
@@ -48,9 +77,10 @@ export function openaiCompatible<
   // (incl. the required `apiKey` / `baseURL`) is OpenAI SDK ClientOptions.
   const {
     name = DEFAULT_NAME,
-    models: _models,
+    models,
     api = 'chat-completions',
     strictFallbackWarning,
+    compat,
     ...clientOptions
   } = config
   const client = new OpenAI(clientOptions)
@@ -68,8 +98,15 @@ export function openaiCompatible<
       TModelName,
       ResolveCompatOptions<TModels, TModelName>,
       ResolveCompatInput<TModels, TModelName>,
-      ResolveCompatTools<TModels, TModelName>
-    >(client, model, name, { strictFallbackWarning })
+      ResolveCompatTools<TModels, TModelName>,
+      ResolveCompatReasoning<TModels, TModelName>
+    >(
+      client,
+      model,
+      name,
+      { strictFallbackWarning },
+      modelConfig(models, model, compat),
+    )
   }
 }
 
@@ -95,6 +132,8 @@ export function openaiCompatibleText<const TModelName extends string>(
     name = DEFAULT_NAME,
     api = 'chat-completions',
     strictFallbackWarning,
+    compat,
+    reasoning,
     ...clientOptions
   } = config
   const client = new OpenAI(clientOptions)
@@ -106,7 +145,20 @@ export function openaiCompatibleText<const TModelName extends string>(
       { strictFallbackWarning },
     )
   }
-  return new OpenAICompatibleChatAdapter<TModelName>(client, model, name, {
-    strictFallbackWarning,
-  })
+  return new OpenAICompatibleChatAdapter<
+    TModelName,
+    Record<string, any>,
+    ReadonlyArray<Modality>,
+    ReadonlyArray<string>,
+    { levels: Exclude<ReasoningLevel, 'xhigh' | 'max'>; budget: false }
+  >(
+    client,
+    model,
+    name,
+    { strictFallbackWarning },
+    {
+      ...(reasoning !== undefined ? { reasoning } : {}),
+      ...(compat ? { compat } : {}),
+    },
+  )
 }
diff --git a/packages/ai-openai/src/compatible/quirks.ts b/packages/ai-openai/src/compatible/quirks.ts
new file mode 100644
index 0000000000..a17d844fb3
--- /dev/null
+++ b/packages/ai-openai/src/compatible/quirks.ts
@@ -0,0 +1,330 @@
+import { clampReasoningLevel } from '@tanstack/ai'
+import { reasoningBudget, reasoningValue } from '@tanstack/ai/adapter-internals'
+import type {
+  ModelReasoning,
+  ReasoningLevel,
+  ReasoningMap,
+  ReasoningRequest,
+} from '@tanstack/ai'
+
+/** How a Chat Completions request asks for thinking. */
+export type OpenAICompatibleThinkingFormat =
+  | 'openai'
+  | 'deepseek'
+  | 'zai'
+  | 'qwen'
+  | 'qwen-chat-template'
+  | 'chat-template'
+  | 'baseten'
+  | 'openrouter'
+  | 'together'
+  | 'string-thinking'
+  | 'ant-ling'
+
+/**
+ * The request quirks of an OpenAI-compatible provider or model. The same
+ * fields as pi's `OpenAICompletionsCompat` and as `ModelCompat` in
+ * `@tanstack/ai-models`, so a catalog record's `compat` drops in. An absent
+ * field keeps today's request.
+ */
+export interface OpenAICompatibleCompat {
+  /** How to ask for thinking. Default `'openai'` (`reasoning_effort`). */
+  thinkingFormat?: OpenAICompatibleThinkingFormat
+  /** `false`: the provider takes no `reasoning_effort`. Default `true`. */
+  supportsReasoningEffort?: boolean
+  /** `false`: send instructions as `system`, not `developer`. Default `true`. */
+  supportsDeveloperRole?: boolean
+  /** The field for the output token limit. Set only to rename it. */
+  maxTokensField?: 'max_completion_tokens' | 'max_tokens'
+  /** `true`: every earlier assistant message carries `reasoning_content` (DeepSeek). */
+  requiresReasoningContentOnAssistantMessages?: boolean
+  /** `false`: the provider rejects `store`, so it is dropped. */
+  supportsStore?: boolean
+  /** `false`: tools are sent with `strict: false`. */
+  supportsStrictMode?: boolean
+  /** `false`: no `stream_options: { include_usage }`. */
+  supportsUsageInStreaming?: boolean
+  /** `true`: send `tool_stream: true` with tools (Z.AI). */
+  zaiToolStream?: boolean
+  /** `true`: send the conversation id as session headers. */
+  sendSessionAffinityHeaders?: boolean
+  sessionAffinityFormat?: 'openai' | 'openrouter' | 'openai-nosession'
+  /** `'anthropic'`: add Anthropic cache markers (Claude through OpenRouter). */
+  cacheControlFormat?: 'anthropic'
+  supportsLongCacheRetention?: boolean
+  /** A top-level field for the thinking token budget, for example `thinking_token_budget`. */
+  thinkingTokenBudgetField?: string
+  /** Values for `chat_template_kwargs` (the `chat-template` format). */
+  chatTemplateKwargs?: Record<string, unknown>
+  /** Values for `chat_template_args` (the `baseten` format). */
+  chatTemplateArgs?: Record<string, unknown>
+  supportsTemperature?: boolean
+}
+
+/** A Chat Completions request body, as loose JSON. */
+type Params = Record<string, unknown>
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+/** The objects of an array field, for example `messages` or `tools`. */
+const records = (value: unknown): Array<Record<string, unknown>> =>
+  Array.isArray(value) ? value.filter(isRecord) : []
+
+/** pi: at least this many tokens stay for the answer under a shared ceiling. */
+const MIN_ANSWER_TOKENS = 1024
+
+/**
+ * A chat template value: a fixed value, or `{ $var: 'thinking.enabled' }`,
+ * `{ $var: 'thinking.budget' }`, or `{ omitWhenOff: true }` (pi's shapes).
+ */
+function templateValues(
+  values: Record<string, unknown> | undefined,
+  reasoning: ModelReasoning | undefined,
+  effort: ReasoningLevel | undefined,
+  budget: number | undefined,
+): Record<string, unknown> | undefined {
+  const resolved: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(values ?? {})) {
+    if (typeof value !== 'object' || value === null) {
+      resolved[key] = value
+      continue
+    }
+    if (!effort && 'omitWhenOff' in value && value.omitWhenOff) continue
+    const variable = '$var' in value ? value.$var : undefined
+    if (variable === 'thinking.enabled') resolved[key] = !!effort
+    else if (variable === 'thinking.budget') {
+      if (budget !== undefined) resolved[key] = budget
+    } else {
+      const mapped = reasoningValue(reasoning, effort ?? 'off')
+      if (typeof mapped === 'string') resolved[key] = mapped
+    }
+  }
+  return Object.keys(resolved).length > 0 ? resolved : undefined
+}
+
+/**
+ * Write the thinking fields of `request` into `params`, the way pi's
+ * `buildParams` does for each `thinkingFormat`. `reasoning: false` (a model
+ * that does not reason) gets nothing.
+ */
+export function applyThinking(
+  params: Params,
+  request: ReasoningRequest,
+  reasoning: ModelReasoning | undefined,
+  compat: OpenAICompatibleCompat,
+  modelMaxTokens?: number,
+): void {
+  if (reasoning === false) return
+  const level = clampReasoningLevel(reasoning, request.level)
+  // pi's `reasoningEffort`: undefined means thinking off.
+  const effort = level === 'off' ? undefined : level
+  const on = effort !== undefined
+  const value = (target: ReasoningLevel) => reasoningValue(reasoning, target)
+  const map: ReasoningMap | undefined = reasoning?.map
+  const effortAllowed = compat.supportsReasoningEffort !== false
+  const ceiling =
+    (typeof params.max_tokens === 'number' ? params.max_tokens : undefined) ??
+    (typeof params.max_completion_tokens === 'number'
+      ? params.max_completion_tokens
+      : undefined) ??
+    modelMaxTokens
+  const budget = on
+    ? ceiling === undefined
+      ? reasoningBudget(request)
+      : Math.min(
+          reasoningBudget(request),
+          Math.max(0, ceiling - MIN_ANSWER_TOKENS),
+        )
+    : undefined
+
+  switch (compat.thinkingFormat ?? 'openai') {
+    case 'zai': {
+      params.thinking = on
+        ? { type: 'enabled', clear_thinking: false }
+        : { type: 'disabled' }
+      const mapped = on && effortAllowed ? value(effort) : null
+      if (typeof mapped === 'string') params.reasoning_effort = mapped
+      break
+    }
+    case 'qwen': {
+      params.enable_thinking = on
+      const mapped = on && effortAllowed ? value(effort) : null
+      if (typeof mapped === 'string') params.reasoning_effort = mapped
+      break
+    }
+    case 'qwen-chat-template':
+      params.chat_template_kwargs = {
+        enable_thinking: on,
+        preserve_thinking: true,
+      }
+      break
+    case 'chat-template': {
+      const kwargs = templateValues(
+        compat.chatTemplateKwargs,
+        reasoning,
+        effort,
+        budget,
+      )
+      if (kwargs) params.chat_template_kwargs = kwargs
+      break
+    }
+    case 'baseten': {
+      const args = templateValues(
+        compat.chatTemplateArgs,
+        reasoning,
+        effort,
+        budget,
+      )
+      if (args) params.chat_template_args = args
+      if (effortAllowed) {
+        const mapped = value(effort ?? 'off')
+        if (typeof mapped === 'string') params.reasoning_effort = mapped
+      }
+      break
+    }
+    case 'deepseek':
+      if (on) params.thinking = { type: 'enabled' }
+      else if (map?.off !== null) params.thinking = { type: 'disabled' }
+      if (on && effortAllowed) params.reasoning_effort = value(effort) ?? effort
+      break
+    case 'openrouter':
+      if (on) params.reasoning = { effort: value(effort) ?? effort }
+      else if (map?.off !== null)
+        params.reasoning = { effort: map?.off ?? 'none' }
+      break
+    case 'ant-ling': {
+      const mapped = on ? map?.[effort] : undefined
+      if (typeof mapped === 'string') params.reasoning = { effort: mapped }
+      break
+    }
+    case 'together':
+      params.reasoning = { enabled: on }
+      if (on && effortAllowed) params.reasoning_effort = value(effort) ?? effort
+      break
+    case 'string-thinking':
+      if (on) params.thinking = value(effort) ?? effort
+      else if (map?.off !== null) params.thinking = map?.off ?? 'none'
+      break
+    case 'openai':
+      if (effortAllowed) {
+        const mapped = value(effort ?? 'off')
+        // `off` maps to nothing unless the model has an off value, like `none`.
+        if (typeof mapped === 'string' && (on || map?.off !== undefined))
+          params.reasoning_effort = mapped
+      }
+      break
+  }
+
+  if (compat.thinkingTokenBudgetField && budget !== undefined && budget > 0)
+    params[compat.thinkingTokenBudgetField] = budget
+}
+
+const EPHEMERAL = { type: 'ephemeral' } as const
+
+/** Put an Anthropic cache marker on the last text part of a message. */
+function markMessage(message: Record<string, unknown>): boolean {
+  const content = message.content
+  if (typeof content === 'string') {
+    if (content.length === 0) return false
+    message.content = [
+      { type: 'text', text: content, cache_control: EPHEMERAL },
+    ]
+    return true
+  }
+  if (!Array.isArray(content)) return false
+  for (let index = content.length - 1; index >= 0; index--) {
+    const part: unknown = content[index]
+    if (isRecord(part) && part.type === 'text') {
+      content[index] = { ...part, cache_control: EPHEMERAL }
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * The quirks that are not about thinking: the instruction role, the token
+ * field name, `store`, strict tools, `tool_stream`, and cache markers.
+ */
+export function applyRequestQuirks(
+  params: Params,
+  compat: OpenAICompatibleCompat,
+  reasons: boolean,
+): void {
+  const messages = records(params.messages)
+  const instructions = messages.find((message) => message.role === 'system')
+  if (instructions && reasons && compat.supportsDeveloperRole !== false)
+    instructions.role = 'developer'
+
+  const rename = (from: string, to: string) => {
+    if (params[from] === undefined) return
+    params[to] = params[from]
+    delete params[from]
+  }
+  if (compat.maxTokensField === 'max_tokens')
+    rename('max_completion_tokens', 'max_tokens')
+  if (compat.maxTokensField === 'max_completion_tokens')
+    rename('max_tokens', 'max_completion_tokens')
+
+  if (compat.supportsStore === false) delete params.store
+  if (compat.supportsTemperature === false) delete params.temperature
+
+  const tools = records(params.tools)
+  if (tools.length > 0) {
+    if (compat.supportsStrictMode === false)
+      for (const tool of tools)
+        if (isRecord(tool.function))
+          tool.function = { ...tool.function, strict: false }
+    if (compat.zaiToolStream) params.tool_stream = true
+  }
+
+  if (compat.cacheControlFormat === 'anthropic') {
+    const system = messages.find(
+      (message) => message.role === 'system' || message.role === 'developer',
+    )
+    if (system) markMessage(system)
+    const lastTool = tools.at(-1)
+    if (lastTool) lastTool.cache_control = EPHEMERAL
+    for (let index = messages.length - 1; index >= 0; index--) {
+      const message = messages[index]
+      if (
+        message &&
+        ['user', 'assistant', 'tool'].includes(String(message.role)) &&
+        markMessage(message)
+      )
+        break
+    }
+  }
+}
+
+/**
+ * The thinking of an earlier assistant turn, sent back as
+ * `reasoning_content`. Some providers (DeepSeek) refuse the next turn without
+ * it, so it is `''` when the turn had no thinking.
+ */
+export function replayReasoning(
+  thinking: ReadonlyArray<{ content: string }> | undefined,
+): string {
+  return (thinking ?? [])
+    .map((part) => part.content)
+    .filter((content) => content.trim().length > 0)
+    .join('\n')
+}
+
+/** The session headers for `sendSessionAffinityHeaders`, as pi sends them. */
+export function sessionHeaders(
+  compat: OpenAICompatibleCompat,
+  sessionId: string | undefined,
+): Record<string, string> | undefined {
+  if (!sessionId || !compat.sendSessionAffinityHeaders) return undefined
+  if (compat.sessionAffinityFormat === 'openrouter')
+    return { 'x-session-id': sessionId }
+  return {
+    ...((compat.sessionAffinityFormat ?? 'openai') === 'openai'
+      ? { session_id: sessionId }
+      : {}),
+    'x-client-request-id': sessionId,
+    'x-session-affinity': sessionId,
+  }
+}
diff --git a/packages/ai-openai/src/compatible/types.ts b/packages/ai-openai/src/compatible/types.ts
index 9f24d4907b..f0b869d3da 100644
--- a/packages/ai-openai/src/compatible/types.ts
+++ b/packages/ai-openai/src/compatible/types.ts
@@ -1,9 +1,33 @@
-import type { ExtendedModelDef } from '@tanstack/ai'
+import type {
+  ExtendedModelDef,
+  Modality,
+  ReasoningLevel,
+  ReasoningMap,
+} from '@tanstack/ai'
 import type { ClientOptions } from 'openai'
 import type { OpenAIBaseTextAdapterOptions } from '@tanstack/openai-base'
+import type { OpenAICompatibleCompat } from './quirks'
 
-/** A model entry: either a bare id string or a rich createModel() def. */
-export type CompatibleModelInput = string | ExtendedModelDef
+/**
+ * A model with its reasoning levels and request quirks. `reasoning`: `false`
+ * for a model that does not reason, `true` for one with no level map (every
+ * level up to `high` passes), or its level map. A catalog record of
+ * `@tanstack/ai-models` fits: `{ name: record.id, input: record.input,
+ * reasoning: record.reasoning && (record.reasoningMap ?? true), compat: record.compat }`.
+ */
+export interface CompatibleModelEntry<TName extends string = string> {
+  name: TName
+  input?: ReadonlyArray<Modality>
+  reasoning?: boolean | ReasoningMap
+  /** Wins over the provider's `compat`, field by field. */
+  compat?: OpenAICompatibleCompat
+}
+
+/** A model entry: a bare id string, a createModel() def, or a model entry. */
+export type CompatibleModelInput =
+  | string
+  | ExtendedModelDef
+  | CompatibleModelEntry
 
 /**
  * Optimistic default input modalities for bare-string models. (Function
@@ -17,11 +41,52 @@ export type DefaultCompatInput = readonly ['text', 'image']
 export type ModelNameOf<TModels extends ReadonlyArray<CompatibleModelInput>> = {
   [I in keyof TModels]: TModels[I] extends string
     ? TModels[I]
-    : TModels[I] extends ExtendedModelDef<infer TName>
+    : TModels[I] extends { name: infer TName extends string }
       ? TName
       : never
 }[number]
 
+/** The entry (a def or a model entry) for model `M`, or `never`. */
+type FindEntry<
+  TModels extends ReadonlyArray<CompatibleModelInput>,
+  TModelName extends string,
+> = Extract<Exclude<TModels[number], string>, { name: TModelName }>
+
+/**
+ * The levels a level map supports, with pi's rules: a level mapped to `null`
+ * is not supported, `xhigh` and `max` need a value, and every other level
+ * passes.
+ */
+export type LevelsOfMap<TMap> = {
+  [L in ReasoningLevel]: L extends keyof TMap
+    ? TMap[L] extends null
+      ? never
+      : L
+    : L extends 'xhigh' | 'max'
+      ? never
+      : L
+}[ReasoningLevel]
+
+/** Up to `high`: the levels of a reasoning model with no level map. */
+type DefaultLevels = Exclude<ReasoningLevel, 'xhigh' | 'max'>
+
+/**
+ * The reasoning capability of model `M`, for `chat({ reasoning })`. A bare
+ * string or a def: every level up to `high`. `reasoning: false`: none.
+ */
+export type ResolveCompatReasoning<
+  TModels extends ReadonlyArray<CompatibleModelInput>,
+  TModelName extends string,
+> = [FindEntry<TModels, TModelName>] extends [never]
+  ? { levels: DefaultLevels; budget: false }
+  : FindEntry<TModels, TModelName> extends { reasoning: infer TReasoning }
+    ? TReasoning extends false
+      ? never
+      : TReasoning extends ReasoningMap
+        ? { levels: LevelsOfMap<TReasoning>; budget: false }
+        : { levels: DefaultLevels; budget: false }
+    : { levels: DefaultLevels; budget: false }
+
 /** Extract the rich def (if any) for model name `M`. */
 type FindDef<
   TModels extends ReadonlyArray<CompatibleModelInput>,
@@ -33,7 +98,13 @@ export type ResolveCompatInput<
   TModels extends ReadonlyArray<CompatibleModelInput>,
   TModelName extends string,
 > = [FindDef<TModels, TModelName>] extends [never]
-  ? DefaultCompatInput
+  ? [FindEntry<TModels, TModelName>] extends [never]
+    ? DefaultCompatInput
+    : FindEntry<TModels, TModelName> extends {
+          input: infer TInput extends ReadonlyArray<Modality>
+        }
+      ? TInput
+      : DefaultCompatInput
   : FindDef<TModels, TModelName> extends ExtendedModelDef<any, infer TInput>
     ? TInput
     : DefaultCompatInput
@@ -85,6 +156,12 @@ export interface OpenAICompatibleConfig<
   apiKey: NonNullable<ClientOptions['apiKey']>
   models: TModels
   api?: CompatibleApi
+  /**
+   * The provider's request quirks (thinking format, token field, replay).
+   * A model entry's `compat` wins, field by field. Without it, the request is
+   * the plain OpenAI shape.
+   */
+  compat?: OpenAICompatibleCompat
 }
 
 /** One-shot helper configuration (single model). */
@@ -96,4 +173,8 @@ export interface OpenAICompatibleTextConfig
   baseURL: string
   apiKey: NonNullable<ClientOptions['apiKey']>
   api?: CompatibleApi
+  /** The model's request quirks. See {@link OpenAICompatibleConfig.compat}. */
+  compat?: OpenAICompatibleCompat
+  /** The model's reasoning: `false`, `true` (no level map), or its level map. */
+  reasoning?: boolean | ReasoningMap
 }
diff --git a/packages/ai-openai/src/model-meta.ts b/packages/ai-openai/src/model-meta.ts
index d911c0ec67..0225cd8c97 100644
--- a/packages/ai-openai/src/model-meta.ts
+++ b/packages/ai-openai/src/model-meta.ts
@@ -2,8 +2,6 @@ import type { Modality } from '@tanstack/ai'
 import type {
   OpenAIBaseOptions,
   OpenAIMetadataOptions,
-  OpenAIReasoningOptions,
-  OpenAIReasoningOptionsWithConcise,
   OpenAIStreamingOptions,
   OpenAIStructuredOutputOptions,
   OpenAIToolsOptions,
@@ -109,7 +107,6 @@ const GPT5_2 = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -148,7 +145,6 @@ const GPT5_2_PRO = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
@@ -184,7 +180,6 @@ const GPT5_2_CHAT = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -229,7 +224,6 @@ const GPT5_1 = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -266,7 +260,6 @@ const GPT5_1_CODEX = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -312,7 +305,6 @@ const GPT5 = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -353,7 +345,6 @@ const GPT5_MINI = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -394,7 +385,6 @@ const GPT5_NANO = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -434,7 +424,6 @@ const GPT5_PRO = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -471,7 +460,6 @@ const GPT5_CODEX = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -671,10 +659,7 @@ const O3_DEEP_RESEARCH = {
     ],
   },
 } as const satisfies ModelMeta<
-  OpenAIBaseOptions &
-    OpenAIReasoningOptions &
-    OpenAIStreamingOptions &
-    OpenAIMetadataOptions
+  OpenAIBaseOptions & OpenAIStreamingOptions & OpenAIMetadataOptions
 >
 
 const O4_MINI_DEEP_RESEARCH = {
@@ -710,10 +695,7 @@ const O4_MINI_DEEP_RESEARCH = {
     ],
   },
 } as const satisfies ModelMeta<
-  OpenAIBaseOptions &
-    OpenAIReasoningOptions &
-    OpenAIStreamingOptions &
-    OpenAIMetadataOptions
+  OpenAIBaseOptions & OpenAIStreamingOptions & OpenAIMetadataOptions
 >
 
 const O3_PRO = {
@@ -749,7 +731,6 @@ const O3_PRO = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -902,7 +883,6 @@ const O3 = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -1000,7 +980,6 @@ const GPT4_1 = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -1132,7 +1111,6 @@ const O1_PRO = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -1161,7 +1139,6 @@ const COMPUTER_USE_PREVIEW = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptionsWithConcise &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
@@ -1249,7 +1226,6 @@ const O3_MINI = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -1335,7 +1311,6 @@ const O1 = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -1404,7 +1379,6 @@ const GPT_4O = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -1602,7 +1576,6 @@ const GPT_5_1_CODEX_MINI = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -1639,7 +1612,6 @@ const CODEX_MINI_LATEST = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -1865,7 +1837,6 @@ const GPT_5_1_CHAT = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -1902,7 +1873,6 @@ const GPT_5_CHAT = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -1990,7 +1960,6 @@ const GPT_5_4_MINI = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2035,7 +2004,6 @@ const GPT_5_4_NANO = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2080,7 +2048,6 @@ const GPT_5_4_IMAGE_2 = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2126,7 +2093,6 @@ const GPT_5_6 = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2172,7 +2138,6 @@ const GPT_5_6_SOL = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2218,7 +2183,6 @@ const GPT_5_6_TERRA = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2264,7 +2228,6 @@ const GPT_5_6_LUNA = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2309,7 +2272,6 @@ const GPT_5_5 = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2353,7 +2315,6 @@ const GPT_5_5_PRO = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2398,7 +2359,6 @@ const GPT_CHAT_LATEST = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2427,7 +2387,6 @@ const GPT_5_6_LUNA_PRO = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2456,7 +2415,6 @@ const GPT_5_6_SOL_PRO = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2485,7 +2443,6 @@ const GPT_5_6_TERRA_PRO = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2523,7 +2480,6 @@ const GPT_6_ASTRA = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2552,7 +2508,6 @@ const GPT_6_ASTRA_PRO = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2590,7 +2545,6 @@ const GPT_6_LUNA = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2619,7 +2573,6 @@ const GPT_6_LUNA_PRO = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2657,7 +2610,6 @@ const GPT_6_SOL = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2686,7 +2638,6 @@ const GPT_6_SOL_PRO = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2726,7 +2677,6 @@ const GPT_6_1_SOL = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2766,7 +2716,6 @@ const GPT_6_1_SOL_PRO = {
   },
 } as const satisfies ModelMeta<
   OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -2970,54 +2919,45 @@ export type OpenAIEmbeddingModelInputModalitiesByName = {
  */
 export type OpenAIChatModelProviderOptionsByName = {
   [GPT5_2.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT5_2_CHAT.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT5_2_PRO.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT5_1.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT5_1_CODEX.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT5.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT5_MINI.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT5_NANO.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT5_PRO.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -3069,26 +3009,14 @@ export type OpenAIChatModelProviderOptionsByName = {
   [CHATGPT_40.name]: OpenAIBaseOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
-  [O3.name]: OpenAIBaseOptions & OpenAIReasoningOptions & OpenAIMetadataOptions
-  [O3_PRO.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
-    OpenAIMetadataOptions
-  [O3_MINI.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
-    OpenAIMetadataOptions
-  [O4_MINI.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
-    OpenAIMetadataOptions
-  [O3_DEEP_RESEARCH.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
-    OpenAIMetadataOptions
-  [O4_MINI_DEEP_RESEARCH.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
-    OpenAIMetadataOptions
-  [O1.name]: OpenAIBaseOptions & OpenAIReasoningOptions & OpenAIMetadataOptions
-  [O1_PRO.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
-    OpenAIMetadataOptions
+  [O3.name]: OpenAIBaseOptions & OpenAIMetadataOptions
+  [O3_PRO.name]: OpenAIBaseOptions & OpenAIMetadataOptions
+  [O3_MINI.name]: OpenAIBaseOptions & OpenAIMetadataOptions
+  [O4_MINI.name]: OpenAIBaseOptions & OpenAIMetadataOptions
+  [O3_DEEP_RESEARCH.name]: OpenAIBaseOptions & OpenAIMetadataOptions
+  [O4_MINI_DEEP_RESEARCH.name]: OpenAIBaseOptions & OpenAIMetadataOptions
+  [O1.name]: OpenAIBaseOptions & OpenAIMetadataOptions
+  [O1_PRO.name]: OpenAIBaseOptions & OpenAIMetadataOptions
 
   // Audio models
   [GPT_AUDIO.name]: OpenAIBaseOptions &
@@ -3106,11 +3034,9 @@ export type OpenAIChatModelProviderOptionsByName = {
 
   // Chat-only models
   [GPT_5_1_CHAT.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIMetadataOptions
   [GPT_5_CHAT.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIMetadataOptions
 
@@ -3140,132 +3066,110 @@ export type OpenAIChatModelProviderOptionsByName = {
 
   // Special models
   [COMPUTER_USE_PREVIEW.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptionsWithConcise &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_5_4_MINI.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_5_4_NANO.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_5_4_IMAGE_2.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_5_6.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_5_6_SOL.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_5_6_TERRA.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_5_6_LUNA.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_5_5.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_5_5_PRO.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_CHAT_LATEST.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_5_6_LUNA_PRO.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_5_6_SOL_PRO.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_5_6_TERRA_PRO.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_6_ASTRA.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_6_ASTRA_PRO.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_6_LUNA.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_6_LUNA_PRO.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_6_SOL.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_6_SOL_PRO.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_6_1_SOL.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT_6_1_SOL_PRO.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
diff --git a/packages/ai-openai/src/text/text-provider-options.ts b/packages/ai-openai/src/text/text-provider-options.ts
index bab75aef33..3e938f8ed9 100644
--- a/packages/ai-openai/src/text/text-provider-options.ts
+++ b/packages/ai-openai/src/text/text-provider-options.ts
@@ -147,61 +147,6 @@ https://platform.openai.com/docs/api-reference/responses/create#responses_create
 
 // Feature fragments that can be stitched per-model
 
-// Shared base types for reasoning options
-type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high'
-type ReasoningSummary = 'auto' | 'detailed'
-
-/**
- * Reasoning options for most models (excludes 'concise' summary).
- */
-export interface OpenAIReasoningOptions {
-  /**
-   * Reasoning controls for models that support it.
-   * Lets you guide how much chain-of-thought computation to spend.
-   * https://platform.openai.com/docs/api-reference/responses/create#responses_create-reasoning
-   * https://platform.openai.com/docs/guides/reasoning
-   */
-  reasoning?: {
-    /**
-     * gpt-5.1 defaults to none, which does not perform reasoning. The supported reasoning values for gpt-5.1 are none, low, medium, and high. Tool calls are supported for all reasoning values in gpt-5.1.
-     * All models before gpt-5.1 default to medium reasoning effort, and do not support none.
-     * The gpt-5-pro model defaults to (and only supports) high reasoning effort.
-     */
-    effort?: ReasoningEffort
-    /**
-     * A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process.
-     * https://platform.openai.com/docs/api-reference/responses/create#responses_create-reasoning-summary
-     */
-    summary?: ReasoningSummary
-  }
-}
-
-/**
- * Reasoning options for computer-use-preview model (includes 'concise' summary).
- */
-export interface OpenAIReasoningOptionsWithConcise {
-  /**
-   * Reasoning controls for models that support it.
-   * Lets you guide how much chain-of-thought computation to spend.
-   * https://platform.openai.com/docs/api-reference/responses/create#responses_create-reasoning
-   * https://platform.openai.com/docs/guides/reasoning
-   */
-  reasoning?: {
-    /**
-     * gpt-5.1 defaults to none, which does not perform reasoning. The supported reasoning values for gpt-5.1 are none, low, medium, and high. Tool calls are supported for all reasoning values in gpt-5.1.
-     * All models before gpt-5.1 default to medium reasoning effort, and do not support none.
-     * The gpt-5-pro model defaults to (and only supports) high reasoning effort.
-     */
-    effort?: ReasoningEffort
-    /**
-     * A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process.
-     * `concise` is only supported for `computer-use-preview` models.
-     * https://platform.openai.com/docs/api-reference/responses/create#responses_create-reasoning-summary
-     */
-    summary?: ReasoningSummary | 'concise'
-  }
-}
-
 export interface OpenAIStructuredOutputOptions {
   /**
    * Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more:
@@ -256,7 +201,6 @@ https://platform.openai.com/docs/api-reference/responses/create#responses_create
 }
 
 export type ExternalTextProviderOptions = OpenAIBaseOptions &
-  OpenAIReasoningOptions &
   OpenAIStructuredOutputOptions &
   OpenAIToolsOptions &
   OpenAIStreamingOptions &
diff --git a/packages/ai-openai/tests/chat-per-model-type-safety.test.ts b/packages/ai-openai/tests/chat-per-model-type-safety.test.ts
index 521b56eb64..b5f3730fff 100644
--- a/packages/ai-openai/tests/chat-per-model-type-safety.test.ts
+++ b/packages/ai-openai/tests/chat-per-model-type-safety.test.ts
@@ -24,11 +24,11 @@ describe('OpenAI per-model chat modelOptions gating', () => {
       chat({
         adapter: openaiText('gpt-5.2'),
         messages: [{ role: 'user', content: 'hi' }],
+        reasoning: { level: 'medium', summary: true },
         modelOptions: {
           background: false,
           service_tier: 'auto',
           verbosity: 'medium',
-          reasoning: { effort: 'medium', summary: 'auto' },
           text: { format: { type: 'text' } },
           tool_choice: 'auto',
           max_tool_calls: 5,
@@ -39,19 +39,26 @@ describe('OpenAI per-model chat modelOptions gating', () => {
       })
     })
 
-    it('rejects the computer-use-preview-only "concise" summary', () => {
+    it('takes reasoning only as the chat() option, not in modelOptions', () => {
       chat({
         adapter: openaiText('gpt-5.2'),
         messages: [{ role: 'user', content: 'hi' }],
         modelOptions: {
-          reasoning: {
-            // @ts-expect-error - 'concise' is only valid on computer-use-preview
-            summary: 'concise',
-          },
+          // @ts-expect-error - reasoning is the top-level `reasoning` option now
+          reasoning: { effort: 'low' },
         },
       })
     })
 
+    it('rejects a level the model does not have', () => {
+      chat({
+        adapter: openaiText('gpt-5.2'),
+        messages: [{ role: 'user', content: 'hi' }],
+        // @ts-expect-error - gpt-5.2 has no `max` level
+        reasoning: 'max',
+      })
+    })
+
     it('rejects unknown options', () => {
       chat({
         adapter: openaiText('gpt-5.2'),
@@ -69,8 +76,8 @@ describe('OpenAI per-model chat modelOptions gating', () => {
       chat({
         adapter: openaiText('gpt-5.2-pro'),
         messages: [{ role: 'user', content: 'hi' }],
+        reasoning: 'high',
         modelOptions: {
-          reasoning: { effort: 'high' },
           tool_choice: 'required',
           stream_options: { include_obfuscation: true },
           metadata: { run: '1' },
@@ -156,8 +163,8 @@ describe('OpenAI per-model chat modelOptions gating', () => {
       chat({
         adapter: openaiText('o3'),
         messages: [{ role: 'user', content: 'hi' }],
+        reasoning: 'high',
         modelOptions: {
-          reasoning: { effort: 'high', summary: 'auto' },
           metadata: { case: 'reasoning-only' },
         },
       })
@@ -197,18 +204,6 @@ describe('OpenAI per-model chat modelOptions gating', () => {
     })
   })
 
-  describe('computer-use-preview — accepts "concise" reasoning summary', () => {
-    it('accepts the concise summary value', () => {
-      chat({
-        adapter: openaiText('computer-use-preview'),
-        messages: [{ role: 'user', content: 'hi' }],
-        modelOptions: {
-          reasoning: { summary: 'concise' },
-        },
-      })
-    })
-  })
-
   describe('chatgpt-4o-latest — base + streaming + metadata only', () => {
     it('rejects tools options', () => {
       chat({
@@ -245,8 +240,8 @@ describe('OpenAI provider options shape assertions', () => {
   describe('gpt-5.2 — full feature set', () => {
     type Options = OpenAIChatModelProviderOptionsByName['gpt-5.2']
 
-    it('has reasoning', () => {
-      expectTypeOf<Options>().toHaveProperty('reasoning')
+    it('has no reasoning (it is the chat() option now)', () => {
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
     })
     it('has text (structured output)', () => {
       expectTypeOf<Options>().toHaveProperty('text')
@@ -265,8 +260,8 @@ describe('OpenAI provider options shape assertions', () => {
   describe('o3 — reasoning + metadata only', () => {
     type Options = OpenAIChatModelProviderOptionsByName['o3']
 
-    it('has reasoning', () => {
-      expectTypeOf<Options>().toHaveProperty('reasoning')
+    it('has no reasoning (it is the chat() option now)', () => {
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
     })
     it('has metadata', () => {
       expectTypeOf<Options>().toHaveProperty('metadata')
diff --git a/packages/ai-openai/tests/compatible-quirks.test.ts b/packages/ai-openai/tests/compatible-quirks.test.ts
new file mode 100644
index 0000000000..00e6328e78
--- /dev/null
+++ b/packages/ai-openai/tests/compatible-quirks.test.ts
@@ -0,0 +1,373 @@
+import { describe, expect, it, vi } from 'vitest'
+import OpenAI from 'openai'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { OpenAICompatibleChatAdapter } from '../src/compatible/adapter'
+import type { ModelMessage, ReasoningMap, ReasoningRequest } from '@tanstack/ai'
+import type { CompatibleModelConfig } from '../src/compatible/adapter'
+
+const logger = resolveDebugOption(false)
+
+async function* noChunks() {}
+
+/** Run one call and return the request body and request options it sent. */
+async function send(
+  config: CompatibleModelConfig,
+  options: {
+    reasoning?: ReasoningRequest
+    messages?: Array<ModelMessage>
+    systemPrompts?: Array<string>
+    modelOptions?: Record<string, unknown>
+    tools?: boolean
+    conversationId?: string
+  } = {},
+) {
+  const client = new OpenAI({ apiKey: 'test' })
+  const create = vi.fn().mockResolvedValue(noChunks())
+  client.chat.completions.create =
+    create as typeof client.chat.completions.create
+  const adapter = new OpenAICompatibleChatAdapter(
+    client,
+    'm',
+    'test',
+    {},
+    config,
+  )
+  for await (const _chunk of adapter.chatStream({
+    logger,
+    model: 'm',
+    messages: options.messages ?? [{ role: 'user', content: 'hi' }],
+    ...(options.systemPrompts ? { systemPrompts: options.systemPrompts } : {}),
+    ...(options.reasoning ? { reasoning: options.reasoning } : {}),
+    ...(options.modelOptions ? { modelOptions: options.modelOptions } : {}),
+    ...(options.conversationId
+      ? { conversationId: options.conversationId }
+      : {}),
+    ...(options.tools
+      ? {
+          tools: [
+            {
+              name: 'lookup',
+              description: 'Look up a word',
+              inputSchema: {
+                type: 'object',
+                properties: { word: { type: 'string' } },
+                required: ['word'],
+              },
+            },
+          ],
+        }
+      : {}),
+  })) {
+    // Drain the stream.
+  }
+  const [body, requestOptions] = create.mock.calls[0] ?? []
+  return {
+    body: body as Record<string, any>,
+    requestOptions: requestOptions as Record<string, any>,
+  }
+}
+
+const on = (level: ReasoningRequest['level']): ReasoningRequest => ({
+  level,
+  summary: true,
+})
+const DEEPSEEK_MAP: ReasoningMap = {
+  off: 'none',
+  minimal: null,
+  low: 'low',
+  medium: null,
+  high: 'high',
+  xhigh: null,
+  max: 'max',
+}
+
+describe('openaiCompatible thinking formats (pi buildParams)', () => {
+  it('openai: reasoning_effort, and the off value when the model has one', async () => {
+    const high = await send(
+      { reasoning: { off: 'none' } },
+      { reasoning: on('high') },
+    )
+    expect(high.body.reasoning_effort).toBe('high')
+    const off = await send(
+      { reasoning: { off: 'none' } },
+      { reasoning: on('off') },
+    )
+    expect(off.body.reasoning_effort).toBe('none')
+    const noOffValue = await send({ reasoning: true }, { reasoning: on('off') })
+    expect(noOffValue.body).not.toHaveProperty('reasoning_effort')
+  })
+
+  it('deepseek: thinking enabled with the mapped effort, disabled for off', async () => {
+    const compat = { thinkingFormat: 'deepseek' as const }
+    const max = await send(
+      { reasoning: DEEPSEEK_MAP, compat },
+      { reasoning: on('max') },
+    )
+    expect(max.body).toMatchObject({
+      thinking: { type: 'enabled' },
+      reasoning_effort: 'max',
+    })
+    // `medium` is not a DeepSeek level: it clamps up to `high`.
+    const medium = await send(
+      { reasoning: DEEPSEEK_MAP, compat },
+      { reasoning: on('medium') },
+    )
+    expect(medium.body.reasoning_effort).toBe('high')
+    const off = await send(
+      { reasoning: DEEPSEEK_MAP, compat },
+      { reasoning: on('off') },
+    )
+    expect(off.body.thinking).toEqual({ type: 'disabled' })
+    expect(off.body).not.toHaveProperty('reasoning_effort')
+  })
+
+  it('zai: thinking with clear_thinking false, and disabled for off', async () => {
+    const compat = { thinkingFormat: 'zai' as const }
+    const high = await send(
+      { reasoning: true, compat },
+      { reasoning: on('high') },
+    )
+    expect(high.body).toMatchObject({
+      thinking: { type: 'enabled', clear_thinking: false },
+      reasoning_effort: 'high',
+    })
+    const off = await send(
+      { reasoning: true, compat },
+      { reasoning: on('off') },
+    )
+    expect(off.body.thinking).toEqual({ type: 'disabled' })
+  })
+
+  it('qwen and qwen-chat-template: enable_thinking', async () => {
+    const qwen = await send(
+      {
+        reasoning: true,
+        compat: { thinkingFormat: 'qwen', supportsReasoningEffort: false },
+      },
+      { reasoning: on('low') },
+    )
+    expect(qwen.body.enable_thinking).toBe(true)
+    expect(qwen.body).not.toHaveProperty('reasoning_effort')
+    const template = await send(
+      { reasoning: true, compat: { thinkingFormat: 'qwen-chat-template' } },
+      { reasoning: on('off') },
+    )
+    expect(template.body.chat_template_kwargs).toEqual({
+      enable_thinking: false,
+      preserve_thinking: true,
+    })
+  })
+
+  it('chat-template and baseten: template values from the compat', async () => {
+    const template = await send(
+      {
+        reasoning: true,
+        compat: {
+          thinkingFormat: 'chat-template',
+          chatTemplateKwargs: { enable_thinking: { $var: 'thinking.enabled' } },
+        },
+      },
+      { reasoning: on('high') },
+    )
+    expect(template.body.chat_template_kwargs).toEqual({
+      enable_thinking: true,
+    })
+    const baseten = await send(
+      {
+        reasoning: true,
+        compat: {
+          thinkingFormat: 'baseten',
+          chatTemplateArgs: { enable_thinking: { $var: 'thinking.enabled' } },
+        },
+      },
+      { reasoning: on('off') },
+    )
+    expect(baseten.body.chat_template_args).toEqual({ enable_thinking: false })
+  })
+
+  it('openrouter: reasoning.effort, and none for off', async () => {
+    const compat = { thinkingFormat: 'openrouter' as const }
+    const high = await send(
+      { reasoning: true, compat },
+      { reasoning: on('high') },
+    )
+    expect(high.body.reasoning).toEqual({ effort: 'high' })
+    const off = await send(
+      { reasoning: true, compat },
+      { reasoning: on('off') },
+    )
+    expect(off.body.reasoning).toEqual({ effort: 'none' })
+  })
+
+  it('together: reasoning.enabled', async () => {
+    const compat = {
+      thinkingFormat: 'together' as const,
+      supportsReasoningEffort: false,
+    }
+    const high = await send(
+      { reasoning: true, compat },
+      { reasoning: on('high') },
+    )
+    expect(high.body.reasoning).toEqual({ enabled: true })
+    expect(high.body).not.toHaveProperty('reasoning_effort')
+  })
+
+  it('string-thinking and ant-ling', async () => {
+    const thinking = await send(
+      { reasoning: true, compat: { thinkingFormat: 'string-thinking' } },
+      { reasoning: on('off') },
+    )
+    expect(thinking.body.thinking).toBe('none')
+    const antLing = await send(
+      {
+        reasoning: { off: null, high: 'high' },
+        compat: { thinkingFormat: 'ant-ling' },
+      },
+      { reasoning: on('high') },
+    )
+    expect(antLing.body.reasoning).toEqual({ effort: 'high' })
+  })
+
+  it('sends no thinking for a model that does not reason', async () => {
+    const { body } = await send({ reasoning: false }, { reasoning: on('high') })
+    expect(body).not.toHaveProperty('reasoning_effort')
+    expect(body).not.toHaveProperty('thinking')
+  })
+
+  it('adds the thinking token budget field when set', async () => {
+    const { body } = await send(
+      {
+        reasoning: true,
+        compat: { thinkingTokenBudgetField: 'thinking_token_budget' },
+      },
+      { reasoning: on('low'), modelOptions: { max_tokens: 10_000 } },
+    )
+    expect(body.thinking_token_budget).toBe(2048)
+  })
+})
+
+describe('openaiCompatible request quirks', () => {
+  it('keeps the request as today without compat or reasoning', async () => {
+    const { body } = await send({}, { systemPrompts: ['Be brief.'] })
+    expect(body.messages[0]).toEqual({ role: 'system', content: 'Be brief.' })
+    expect(body.stream_options).toEqual({ include_usage: true })
+    expect(Object.keys(body).sort()).toEqual(
+      ['messages', 'model', 'stream', 'stream_options'].sort(),
+    )
+  })
+
+  it('sends developer only for a reasoning model with supportsDeveloperRole', async () => {
+    const reasoning = await send(
+      { reasoning: true, compat: { supportsDeveloperRole: true } },
+      { systemPrompts: ['Be brief.'] },
+    )
+    expect(reasoning.body.messages[0].role).toBe('developer')
+    const plain = await send(
+      { reasoning: false, compat: { supportsDeveloperRole: true } },
+      { systemPrompts: ['Be brief.'] },
+    )
+    expect(plain.body.messages[0].role).toBe('system')
+    const refused = await send(
+      { reasoning: true, compat: { supportsDeveloperRole: false } },
+      { systemPrompts: ['Be brief.'] },
+    )
+    expect(refused.body.messages[0].role).toBe('system')
+  })
+
+  it('renames the token limit to maxTokensField', async () => {
+    const { body } = await send(
+      { compat: { maxTokensField: 'max_tokens' } },
+      { modelOptions: { max_completion_tokens: 500 } },
+    )
+    expect(body.max_tokens).toBe(500)
+    expect(body).not.toHaveProperty('max_completion_tokens')
+  })
+
+  it('replays reasoning_content on the second DeepSeek turn', async () => {
+    const { body } = await send(
+      {
+        reasoning: DEEPSEEK_MAP,
+        compat: {
+          thinkingFormat: 'deepseek',
+          requiresReasoningContentOnAssistantMessages: true,
+        },
+      },
+      {
+        reasoning: on('high'),
+        messages: [
+          { role: 'user', content: 'What is 2 + 2?' },
+          {
+            role: 'assistant',
+            content: '4',
+            thinking: [{ content: 'Two plus two is four.' }],
+          },
+          { role: 'user', content: 'And 3 + 3?' },
+          { role: 'assistant', content: '6' },
+          { role: 'user', content: 'Thanks' },
+        ],
+      },
+    )
+    const assistants = body.messages.filter((m: any) => m.role === 'assistant')
+    expect(assistants[0].reasoning_content).toBe('Two plus two is four.')
+    // A turn with no thinking still carries the field, or DeepSeek refuses it.
+    expect(assistants[1].reasoning_content).toBe('')
+  })
+
+  it('drops store, sends non-strict tools, and adds tool_stream', async () => {
+    const { body } = await send(
+      {
+        compat: {
+          supportsStore: false,
+          supportsStrictMode: false,
+          zaiToolStream: true,
+        },
+      },
+      { modelOptions: { store: true }, tools: true },
+    )
+    expect(body).not.toHaveProperty('store')
+    expect(body.tools[0].function.strict).toBe(false)
+    expect(body.tool_stream).toBe(true)
+  })
+
+  it('adds Anthropic cache markers for Claude through OpenRouter', async () => {
+    const { body } = await send(
+      { compat: { cacheControlFormat: 'anthropic' } },
+      { systemPrompts: ['Be brief.'], tools: true },
+    )
+    expect(body.messages[0].content).toEqual([
+      { type: 'text', text: 'Be brief.', cache_control: { type: 'ephemeral' } },
+    ])
+    expect(body.messages.at(-1).content[0].cache_control).toEqual({
+      type: 'ephemeral',
+    })
+    expect(body.tools.at(-1).cache_control).toEqual({ type: 'ephemeral' })
+  })
+
+  it('sends session headers, and leaves out streaming usage when refused', async () => {
+    const openrouter = await send(
+      {
+        compat: {
+          sendSessionAffinityHeaders: true,
+          sessionAffinityFormat: 'openrouter',
+        },
+      },
+      { conversationId: 'c1' },
+    )
+    expect(openrouter.requestOptions.headers).toEqual({ 'x-session-id': 'c1' })
+    const openai = await send(
+      {
+        compat: {
+          sendSessionAffinityHeaders: true,
+          supportsUsageInStreaming: false,
+        },
+      },
+      { conversationId: 'c1' },
+    )
+    expect(openai.requestOptions.headers).toEqual({
+      session_id: 'c1',
+      'x-client-request-id': 'c1',
+      'x-session-affinity': 'c1',
+    })
+    expect(openai.body).not.toHaveProperty('stream_options')
+  })
+})
diff --git a/packages/ai-openai/tests/compatible-reasoning-types.test-d.ts b/packages/ai-openai/tests/compatible-reasoning-types.test-d.ts
new file mode 100644
index 0000000000..e7a531aa96
--- /dev/null
+++ b/packages/ai-openai/tests/compatible-reasoning-types.test-d.ts
@@ -0,0 +1,38 @@
+import { chat } from '@tanstack/ai'
+import { openaiCompatible } from '../src/compatible'
+
+const deepseek = openaiCompatible({
+  name: 'deepseek',
+  baseURL: 'https://api.deepseek.com',
+  apiKey: 'test',
+  compat: { thinkingFormat: 'deepseek' },
+  models: [
+    {
+      name: 'deepseek-v4-flash',
+      reasoning: {
+        off: 'none',
+        minimal: null,
+        medium: null,
+        high: 'high',
+        max: 'max',
+      },
+    },
+    { name: 'deepseek-chat', reasoning: false },
+    'deepseek-other',
+  ],
+})
+const messages = [{ role: 'user' as const, content: 'hi' }]
+
+// A level map allows only its levels.
+chat({ adapter: deepseek('deepseek-v4-flash'), messages, reasoning: 'max' })
+chat({ adapter: deepseek('deepseek-v4-flash'), messages, reasoning: 'off' })
+// @ts-expect-error `medium` is null in the map
+chat({ adapter: deepseek('deepseek-v4-flash'), messages, reasoning: 'medium' })
+
+// @ts-expect-error a model with `reasoning: false` takes no reasoning option
+chat({ adapter: deepseek('deepseek-chat'), messages, reasoning: 'low' })
+
+// A bare string follows pi's rule: every level up to `high`.
+chat({ adapter: deepseek('deepseek-other'), messages, reasoning: 'high' })
+// @ts-expect-error `max` needs a level map
+chat({ adapter: deepseek('deepseek-other'), messages, reasoning: 'max' })
diff --git a/packages/ai-openai/tests/model-meta.test.ts b/packages/ai-openai/tests/model-meta.test.ts
index 0c98618e1a..fb4a499e81 100644
--- a/packages/ai-openai/tests/model-meta.test.ts
+++ b/packages/ai-openai/tests/model-meta.test.ts
@@ -5,8 +5,6 @@ import type {
 } from '../src/model-meta'
 import type {
   OpenAIBaseOptions,
-  OpenAIReasoningOptions,
-  OpenAIReasoningOptionsWithConcise,
   OpenAIStructuredOutputOptions,
   OpenAIToolsOptions,
   OpenAIStreamingOptions,
@@ -36,8 +34,9 @@ type MakeInputModalitiesTypes<TModalities extends ReadonlyArray<Modality>> = {
  * Type assertion tests for OpenAI model provider options.
  *
  * These tests verify that:
- * 1. Models with reasoning support have OpenAIReasoningOptions in their provider options
- * 2. Models without reasoning support do NOT have OpenAIReasoningOptions
+ * 1. No model has `reasoning` in its provider options: it is the top-level
+ *    `chat({ reasoning })` option, typed by `OpenAIModelReasoningByName`
+ * 2. The reasoning levels per model come from `OpenAIModelReasoningByName`
  * 3. Models with structured output support have OpenAIStructuredOutputOptions
  * 4. Models without structured output support do NOT have OpenAIStructuredOutputOptions
  * 5. Models with tools support have OpenAIToolsOptions
@@ -49,7 +48,6 @@ type BaseOptions = OpenAIBaseOptions & OpenAIMetadataOptions
 
 // Full featured model options (reasoning + structured output + tools + streaming)
 type FullFeaturedOptions = BaseOptions &
-  OpenAIReasoningOptions &
   OpenAIStructuredOutputOptions &
   OpenAIToolsOptions &
   OpenAIStreamingOptions
@@ -61,7 +59,7 @@ type StandardOptions = BaseOptions &
   OpenAIStreamingOptions
 
 // Reasoning-only model options (reasoning but no tools/structured output streaming)
-type ReasoningOnlyOptions = BaseOptions & OpenAIReasoningOptions
+type ReasoningOnlyOptions = BaseOptions
 
 describe('OpenAI Chat Model Provider Options Type Assertions', () => {
   describe('Models WITH reasoning AND structured output AND tools support (Full Featured)', () => {
@@ -69,7 +67,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-5.1']
 
       // Should have reasoning options
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
 
       // Should have structured output options
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
@@ -84,7 +82,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
       expectTypeOf<Options>().toExtend<BaseOptions>()
 
       // Verify specific properties exist
-      expectTypeOf<Options>().toHaveProperty('reasoning')
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().toHaveProperty('text')
       expectTypeOf<Options>().toHaveProperty('tool_choice')
       expectTypeOf<Options>().toHaveProperty('stream_options')
@@ -95,7 +93,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-5.1-codex should support all features', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-5.1-codex']
 
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -105,7 +103,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-5 should support all features', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-5']
 
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -115,7 +113,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-5-pro should support all features', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-5-pro']
 
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -125,7 +123,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-5.6 should support all features', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-5.6']
 
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -135,7 +133,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-5.6-sol should support all features', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-5.6-sol']
 
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -145,7 +143,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-5.6-terra should support all features', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-5.6-terra']
 
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -155,7 +153,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-5.6-luna should support all features', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-5.6-luna']
 
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -168,7 +166,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-5-mini']
 
       // Should have reasoning options
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
 
       // Should have structured output options
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
@@ -186,7 +184,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-5-nano should have reasoning, structured output and tools', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-5-nano']
 
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -198,7 +196,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-5-codex should have structured output and tools but NOT reasoning', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-5-codex']
 
-      expectTypeOf<Options>().not.toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -208,7 +206,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-4.1 should have structured output and tools but NOT reasoning', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-4.1']
 
-      expectTypeOf<Options>().not.toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -218,7 +216,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-4.1-mini should have structured output and tools but NOT reasoning', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-4.1-mini']
 
-      expectTypeOf<Options>().not.toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -228,7 +226,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-4.1-nano should have structured output and tools but NOT reasoning', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-4.1-nano']
 
-      expectTypeOf<Options>().not.toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -238,7 +236,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-4o should have structured output and tools but NOT reasoning', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-4o']
 
-      expectTypeOf<Options>().not.toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -248,7 +246,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-4o-mini should have structured output and tools but NOT reasoning', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-4o-mini']
 
-      expectTypeOf<Options>().not.toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -261,7 +259,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
       type Options = OpenAIChatModelProviderOptionsByName['o3']
 
       // Should have reasoning options
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
 
       // Should NOT have structured output options
       expectTypeOf<Options>().not.toExtend<OpenAIStructuredOutputOptions>()
@@ -279,7 +277,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('o3-pro should have reasoning but NOT structured output or tools', () => {
       type Options = OpenAIChatModelProviderOptionsByName['o3-pro']
 
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().not.toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIStreamingOptions>()
@@ -289,7 +287,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('o3-mini should have reasoning but NOT structured output or tools', () => {
       type Options = OpenAIChatModelProviderOptionsByName['o3-mini']
 
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().not.toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIStreamingOptions>()
@@ -299,7 +297,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('o4-mini should have reasoning but NOT structured output or tools', () => {
       type Options = OpenAIChatModelProviderOptionsByName['o4-mini']
 
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().not.toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIStreamingOptions>()
@@ -309,7 +307,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('o3-deep-research should have reasoning but NOT structured output or tools', () => {
       type Options = OpenAIChatModelProviderOptionsByName['o3-deep-research']
 
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().not.toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIStreamingOptions>()
@@ -320,7 +318,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
       type Options =
         OpenAIChatModelProviderOptionsByName['o4-mini-deep-research']
 
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().not.toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIStreamingOptions>()
@@ -330,7 +328,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('o1 should have reasoning but NOT structured output or tools', () => {
       type Options = OpenAIChatModelProviderOptionsByName['o1']
 
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().not.toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIStreamingOptions>()
@@ -340,7 +338,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('o1-pro should have reasoning but NOT structured output or tools', () => {
       type Options = OpenAIChatModelProviderOptionsByName['o1-pro']
 
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().not.toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIStreamingOptions>()
@@ -352,7 +350,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-4 should have tools and streaming but NOT reasoning or structured output', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-4']
 
-      expectTypeOf<Options>().not.toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().not.toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -362,7 +360,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-4-turbo should have tools and streaming but NOT reasoning or structured output', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-4-turbo']
 
-      expectTypeOf<Options>().not.toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().not.toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -372,7 +370,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-3.5-turbo should have tools and streaming but NOT reasoning or structured output', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-3.5-turbo']
 
-      expectTypeOf<Options>().not.toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().not.toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -384,7 +382,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('chatgpt-4o-latest should only have streaming and base options', () => {
       type Options = OpenAIChatModelProviderOptionsByName['chatgpt-4o-latest']
 
-      expectTypeOf<Options>().not.toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().not.toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -394,7 +392,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-audio should only have streaming and base options', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-audio']
 
-      expectTypeOf<Options>().not.toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().not.toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -404,7 +402,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-audio-mini should only have streaming and base options', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-audio-mini']
 
-      expectTypeOf<Options>().not.toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().not.toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -414,7 +412,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-4o-audio should only have streaming and base options', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-4o-audio']
 
-      expectTypeOf<Options>().not.toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().not.toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -424,7 +422,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-4o-mini-audio should only have streaming and base options', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-4o-mini-audio']
 
-      expectTypeOf<Options>().not.toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().not.toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -436,7 +434,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-5.1-chat should have reasoning and structured output but NOT tools', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-5.1-chat-latest']
 
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIStreamingOptions>()
@@ -446,7 +444,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
     it('gpt-5-chat should have reasoning and structured output but NOT tools', () => {
       type Options = OpenAIChatModelProviderOptionsByName['gpt-5-chat-latest']
 
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().not.toExtend<OpenAIStreamingOptions>()
@@ -498,7 +496,7 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
         OpenAIChatModelProviderOptionsByName['computer-use-preview']
 
       // Should have reasoning options with 'concise' summary support
-      expectTypeOf<Options>().toExtend<OpenAIReasoningOptionsWithConcise>()
+      expectTypeOf<Options>().not.toHaveProperty('reasoning')
       expectTypeOf<Options>().not.toExtend<OpenAIStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<OpenAIToolsOptions>()
       expectTypeOf<Options>().toExtend<OpenAIStreamingOptions>()
@@ -783,10 +781,10 @@ describe('OpenAI Chat Model Provider Options Type Assertions', () => {
       // Verify these do NOT extend reasoning options (discrimination already tested above)
       expectTypeOf<
         OpenAIChatModelProviderOptionsByName['gpt-4.1']
-      >().not.toExtend<OpenAIReasoningOptions>()
+      >().not.toHaveProperty('reasoning')
       expectTypeOf<
         OpenAIChatModelProviderOptionsByName['gpt-4o']
-      >().not.toExtend<OpenAIReasoningOptions>()
+      >().not.toHaveProperty('reasoning')
     })
 
     it('reasoning-only models should extend reasoning options but NOT structured output or tools', () => {
diff --git a/packages/ai-openai/tests/reasoning-request.test.ts b/packages/ai-openai/tests/reasoning-request.test.ts
new file mode 100644
index 0000000000..1b2a056229
--- /dev/null
+++ b/packages/ai-openai/tests/reasoning-request.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it, vi } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { OpenAITextAdapter } from '../src/adapters/text'
+import type { OpenAIChatModel } from '../src/model-meta'
+import type { ReasoningRequest } from '@tanstack/ai'
+
+const logger = resolveDebugOption(false)
+
+/** The adapter, with its SDK client in reach, so a test can stub it. */
+class TestAdapter<
+  TModel extends OpenAIChatModel,
+> extends OpenAITextAdapter<TModel> {
+  get sdk() {
+    return this.client
+  }
+}
+
+async function* noEvents() {}
+
+/** The `reasoning` field of the Responses request for one call. */
+async function reasoningFor(
+  model: OpenAIChatModel,
+  reasoning: ReasoningRequest | undefined,
+) {
+  const adapter = new TestAdapter({ apiKey: 'test' }, model)
+  const create = vi.fn().mockResolvedValue(noEvents())
+  adapter.sdk.responses.create = create as typeof adapter.sdk.responses.create
+  for await (const _chunk of adapter.chatStream({
+    logger,
+    model,
+    messages: [{ role: 'user', content: 'hi' }],
+    ...(reasoning ? { reasoning } : {}),
+  })) {
+    // Drain the stream.
+  }
+  const [body] = create.mock.calls[0] ?? []
+  return (body as Record<string, unknown>).reasoning
+}
+
+describe('OpenAI chat({ reasoning })', () => {
+  it('sends the effort and asks for a summary', async () => {
+    expect(
+      await reasoningFor('gpt-5.2', { level: 'high', summary: true }),
+    ).toEqual({
+      effort: 'high',
+      summary: 'auto',
+    })
+  })
+
+  it('sends no summary when summary is false', async () => {
+    expect(
+      await reasoningFor('gpt-5.2', { level: 'low', summary: false }),
+    ).toEqual({
+      effort: 'low',
+    })
+  })
+
+  it('sends none for off, on a model that can stop thinking', async () => {
+    expect(
+      await reasoningFor('gpt-5.2', { level: 'off', summary: true }),
+    ).toEqual({
+      effort: 'none',
+    })
+  })
+
+  it('clamps a level the model does not have', async () => {
+    // gpt-5.2 tops out at xhigh.
+    expect(
+      await reasoningFor('gpt-5.2', { level: 'max', summary: true }),
+    ).toEqual({
+      effort: 'xhigh',
+      summary: 'auto',
+    })
+  })
+
+  it('sends nothing without the option, or for a model that does not reason', async () => {
+    expect(await reasoningFor('gpt-5.2', undefined)).toBeUndefined()
+    expect(
+      await reasoningFor('gpt-4.1', { level: 'high', summary: true }),
+    ).toBeUndefined()
+  })
+})
diff --git a/packages/ai/src/activities/chat/adapter.ts b/packages/ai/src/activities/chat/adapter.ts
index 03b2342dd5..c30087cb51 100644
--- a/packages/ai/src/activities/chat/adapter.ts
+++ b/packages/ai/src/activities/chat/adapter.ts
@@ -205,16 +205,7 @@ export interface TextAdapter<
  * A TextAdapter with any/unknown type parameters.
  * Useful as a constraint in generic functions and interfaces.
  */
-export type AnyTextAdapter = TextAdapter<
-  any,
-  any,
-  any,
-  any,
-  any,
-  any,
-  any,
-  any
->
+export type AnyTextAdapter = TextAdapter<any, any, any, any, any, any, any, any>
 
 /**
  * Abstract base class for text adapters.
diff --git a/packages/ai/src/adapter-internals.ts b/packages/ai/src/adapter-internals.ts
index 1bb1ab127d..5a0a21090d 100644
--- a/packages/ai/src/adapter-internals.ts
+++ b/packages/ai/src/adapter-internals.ts
@@ -7,7 +7,9 @@ export {
   DEFAULT_REASONING_BUDGETS,
   reasoningBudget,
   reasoningValue,
+  resolveReasoning,
 } from './reasoning'
+export type { ResolvedReasoning } from './reasoning'
 export { InternalLogger } from './logger/internal-logger'
 export type { Logger } from './logger/types'
 export { resolveDebugOption } from './logger/resolve'
diff --git a/packages/ai/src/reasoning.ts b/packages/ai/src/reasoning.ts
index 05f7c894be..72055aef10 100644
--- a/packages/ai/src/reasoning.ts
+++ b/packages/ai/src/reasoning.ts
@@ -49,7 +49,10 @@ export type ReasoningOption<
   TCapability extends ReasoningCapability = ReasoningCapability,
 > =
   | TCapability['levels']
-  | ({ level: TCapability['levels']; summary?: boolean } & (true extends TCapability['budget']
+  | ({
+      level: TCapability['levels']
+      summary?: boolean
+    } & (true extends TCapability['budget']
       ? { budgetTokens?: number }
       : { budgetTokens?: never }))
 
@@ -172,3 +175,33 @@ export function reasoningBudget(request: ReasoningRequest): number {
   if (request.budgetTokens !== undefined) return request.budgetTokens
   return request.level === 'off' ? 0 : DEFAULT_REASONING_BUDGETS[request.level]
 }
+
+/** A request resolved for one model: the clamped level and its provider value. */
+export interface ResolvedReasoning {
+  level: ReasoningLevel
+  /** The value to send for `level`. `null`: send nothing. */
+  value: string | null
+  summary: boolean
+  budgetTokens?: number
+}
+
+/**
+ * Resolve `request` for a model: clamp the level to the model's levels, and
+ * look up its provider value. `undefined` when there is nothing to send: no
+ * request, or a model that does not reason or has no reasoning data.
+ */
+export function resolveReasoning(
+  request: ReasoningRequest | undefined,
+  reasoning: ModelReasoning | undefined,
+): ResolvedReasoning | undefined {
+  if (!request || !reasoning) return undefined
+  const level = clampReasoningLevel(reasoning, request.level)
+  return {
+    level,
+    value: reasoningValue(reasoning, level),
+    summary: request.summary,
+    ...(request.budgetTokens !== undefined
+      ? { budgetTokens: request.budgetTokens }
+      : {}),
+  }
+}
diff --git a/packages/ai/tests/reasoning-types.test-d.ts b/packages/ai/tests/reasoning-types.test-d.ts
index 1ac79527e2..12aecd301f 100644
--- a/packages/ai/tests/reasoning-types.test-d.ts
+++ b/packages/ai/tests/reasoning-types.test-d.ts
@@ -2,20 +2,25 @@ import { chat } from '../src'
 import type { TextAdapter } from '../src/activities/chat/adapter'
 import type { DefaultMessageMetadataByModality } from '../src/types'
 
-type Adapter<TReasoning extends { levels: any; budget: boolean }> =
-  TextAdapter<
-    'm',
-    Record<string, never>,
-    readonly ['text'],
-    DefaultMessageMetadataByModality,
-    ReadonlyArray<string>,
-    unknown,
-    never,
-    TReasoning
-  >
-
-declare const effortModel: Adapter<{ levels: 'off' | 'low' | 'high'; budget: false }>
-declare const budgetModel: Adapter<{ levels: 'off' | 'low' | 'medium' | 'high'; budget: true }>
+type Adapter<TReasoning extends { levels: any; budget: boolean }> = TextAdapter<
+  'm',
+  Record<string, never>,
+  readonly ['text'],
+  DefaultMessageMetadataByModality,
+  ReadonlyArray<string>,
+  unknown,
+  never,
+  TReasoning
+>
+
+declare const effortModel: Adapter<{
+  levels: 'off' | 'low' | 'high'
+  budget: false
+}>
+declare const budgetModel: Adapter<{
+  levels: 'off' | 'low' | 'medium' | 'high'
+  budget: true
+}>
 declare const plainModel: TextAdapter<
   'm',
   Record<string, never>,
@@ -28,16 +33,28 @@ const messages = [{ role: 'user' as const, content: 'hi' }]
 // A model's own levels, as a string or in the object form.
 chat({ adapter: effortModel, messages, reasoning: 'low' })
 chat({ adapter: effortModel, messages, reasoning: 'off' })
-chat({ adapter: effortModel, messages, reasoning: { level: 'high', summary: false } })
+chat({
+  adapter: effortModel,
+  messages,
+  reasoning: { level: 'high', summary: false },
+})
 
 // @ts-expect-error `medium` is not one of this model's levels
 chat({ adapter: effortModel, messages, reasoning: 'medium' })
 
 // @ts-expect-error budgetTokens needs a budget-based model
-chat({ adapter: effortModel, messages, reasoning: { level: 'low', budgetTokens: 1000 } })
+chat({
+  adapter: effortModel,
+  messages,
+  reasoning: { level: 'low', budgetTokens: 1000 },
+})
 
 // A budget-based model takes budgetTokens.
-chat({ adapter: budgetModel, messages, reasoning: { level: 'medium', budgetTokens: 4000 } })
+chat({
+  adapter: budgetModel,
+  messages,
+  reasoning: { level: 'medium', budgetTokens: 4000 },
+})
 
 // @ts-expect-error an adapter that declares no reasoning takes no reasoning option
 chat({ adapter: plainModel, messages, reasoning: 'low' })
diff --git a/packages/ai/tests/reasoning.test.ts b/packages/ai/tests/reasoning.test.ts
index 873668e7b9..02f313576c 100644
--- a/packages/ai/tests/reasoning.test.ts
+++ b/packages/ai/tests/reasoning.test.ts
@@ -5,6 +5,7 @@ import {
   normalizeReasoning,
   reasoningBudget,
   reasoningValue,
+  resolveReasoning,
   supportedReasoningLevels,
 } from '../src/reasoning'
 import { createMockAdapter, ev } from './test-utils'
@@ -33,14 +34,25 @@ describe('supportedReasoningLevels (pi rules)', () => {
       budget: false,
       map: { off: null, minimal: null, medium: null, xhigh: 'xhigh' },
     }
-    expect(supportedReasoningLevels(reasoning)).toEqual(['low', 'high', 'xhigh'])
+    expect(supportedReasoningLevels(reasoning)).toEqual([
+      'low',
+      'high',
+      'xhigh',
+    ])
   })
 })
 
 describe('clampReasoningLevel (pi rules)', () => {
   const lowHighMax: ModelReasoning = {
     budget: false,
-    map: { off: null, minimal: null, low: 'low', medium: null, high: 'high', max: 'max' },
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: null,
+      high: 'high',
+      max: 'max',
+    },
   }
 
   it.each<[ReasoningLevel, ReasoningLevel]>([
@@ -145,3 +157,24 @@ describe('chat({ reasoning })', () => {
     expect(calls[0]?.reasoning).toEqual({ level: 'max', summary: false })
   })
 })
+
+describe('resolveReasoning', () => {
+  it('clamps the level and gives its value', () => {
+    expect(
+      resolveReasoning(
+        { level: 'medium', summary: true },
+        { budget: false, map: { medium: null, high: 'HIGH' } },
+      ),
+    ).toEqual({ level: 'high', value: 'HIGH', summary: true })
+  })
+
+  it('gives nothing to send without a request or for a model that does not reason', () => {
+    expect(resolveReasoning(undefined, { budget: false })).toBeUndefined()
+    expect(
+      resolveReasoning({ level: 'high', summary: true }, false),
+    ).toBeUndefined()
+    expect(
+      resolveReasoning({ level: 'high', summary: true }, undefined),
+    ).toBeUndefined()
+  })
+})
diff --git a/packages/openai-base/src/adapters/chat-completions-text.ts b/packages/openai-base/src/adapters/chat-completions-text.ts
index ab6c48093a..c4ac9d1ecd 100644
--- a/packages/openai-base/src/adapters/chat-completions-text.ts
+++ b/packages/openai-base/src/adapters/chat-completions-text.ts
@@ -39,6 +39,7 @@ import type {
   Modality,
   ModelMessage,
   AdapterYieldChunk,
+  ReasoningCapability,
   TextOptions,
 } from '@tanstack/ai'
 
@@ -62,12 +63,16 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
   TMessageMetadata extends DefaultMessageMetadataByModality =
     DefaultMessageMetadataByModality,
   TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,
+  TReasoning extends ReasoningCapability = never,
 > extends BaseTextAdapter<
   TModel,
   TProviderOptions,
   TInputModalities,
   TMessageMetadata,
-  TToolCapabilities
+  TToolCapabilities,
+  unknown,
+  never,
+  TReasoning
 > {
   override readonly kind = 'text' as const
   readonly name: string
@@ -115,9 +120,11 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
         {
           ...requestParams,
           stream: true,
-          stream_options: { include_usage: true },
+          ...(this.includeUsageInStream()
+            ? { stream_options: { include_usage: true } }
+            : {}),
         },
-        extractRequestOptions(options.request),
+        this.requestOptionsFor(options),
       )
 
       yield* this.processStreamChunks(stream, options, aguiState)
@@ -1228,6 +1235,38 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
     }
   }
 
+  /**
+   * Whether a streaming request asks for usage with
+   * `stream_options: { include_usage: true }`. Override for a provider that
+   * rejects the field.
+   */
+  protected includeUsageInStream(): boolean {
+    return true
+  }
+
+  /**
+   * Extra headers for one call, for example session headers. They go on top
+   * of the headers of `options.request`.
+   */
+  protected requestHeaders(
+    _options: TextOptions,
+  ): Record<string, string> | undefined {
+    return undefined
+  }
+
+  private requestOptionsFor(options: TextOptions) {
+    const base = extractRequestOptions(options.request)
+    const extra = this.requestHeaders(options)
+    if (!extra) return base
+    return {
+      ...base,
+      headers: {
+        ...Object.fromEntries(new Headers(base.headers).entries()),
+        ...extra,
+      },
+    }
+  }
+
   /**
    * Maps common TextOptions to Chat Completions API request format.
    * Override this in subclasses to add provider-specific options.
diff --git a/packages/openai-base/src/adapters/responses-text.ts b/packages/openai-base/src/adapters/responses-text.ts
index b9d3961f40..d80f4c16ea 100644
--- a/packages/openai-base/src/adapters/responses-text.ts
+++ b/packages/openai-base/src/adapters/responses-text.ts
@@ -54,6 +54,7 @@ import type {
   AdapterYieldChunk,
   ProviderExecutedToolMetadata,
   ProviderExecutedToolSource,
+  ReasoningCapability,
   TextOptions,
 } from '@tanstack/ai'
 
@@ -235,13 +236,16 @@ export abstract class OpenAIBaseResponsesTextAdapter<
   TMessageMetadata extends DefaultMessageMetadataByModality =
     DefaultMessageMetadataByModality,
   TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,
+  TReasoning extends ReasoningCapability = never,
 > extends BaseTextAdapter<
   TModel,
   TProviderOptions,
   TInputModalities,
   TMessageMetadata,
   TToolCapabilities,
-  OpenAIResponsesToolCallMetadata
+  OpenAIResponsesToolCallMetadata,
+  never,
+  TReasoning
 > {
   override readonly kind = 'text' as const
   readonly name: string
diff --git a/scripts/sync-provider-models.ts b/scripts/sync-provider-models.ts
index a562576cc4..c97dc1e14d 100644
--- a/scripts/sync-provider-models.ts
+++ b/scripts/sync-provider-models.ts
@@ -128,9 +128,9 @@ const PROVIDER_MAP: Record<string, ProviderConfig> = {
     validInputModalities: ['text', 'image', 'audio', 'video'],
     kind: 'openai',
     referenceSatisfies:
-      'ModelMeta<OpenAIBaseOptions & OpenAIReasoningOptions & OpenAIStructuredOutputOptions & OpenAIToolsOptions & OpenAIStreamingOptions & OpenAIMetadataOptions>',
+      'ModelMeta<OpenAIBaseOptions & OpenAIStructuredOutputOptions & OpenAIToolsOptions & OpenAIStreamingOptions & OpenAIMetadataOptions>',
     referenceProviderOptionsEntry:
-      'OpenAIBaseOptions & OpenAIReasoningOptions & OpenAIStructuredOutputOptions & OpenAIToolsOptions & OpenAIStreamingOptions & OpenAIMetadataOptions',
+      'OpenAIBaseOptions & OpenAIStructuredOutputOptions & OpenAIToolsOptions & OpenAIStreamingOptions & OpenAIMetadataOptions',
     hasBothNameAndId: false,
     providerOptionsIsMappedType: false,
     skipPatterns: [

From 7788856c12c2e975dcbdb91b2607eee9d278af81 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 14:23:05 +0200
Subject: [PATCH 088/286] feat(ai-anthropic)!: map chat({ reasoning }) to
 Claude thinking

Thinking, effort, and output_config.effort leave modelOptions. The
adapter reads the generated model-reasoning map and sends:

- off: thinking disabled
- budget models, or a request with budgetTokens: enabled thinking with
  the budget (pi's level table when none is set)
- other models: adaptive thinking with the effort, as top-level
  `effort` on Claude 4.6 and `output_config.effort` on 4.7 and later

The interleaved-thinking beta now reads the built request, so it turns
on when `reasoning` enables budget thinking. The model sync stops
writing the removed thinking option types.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-anthropic/src/adapters/text.ts    |  58 +++--
 packages/ai-anthropic/src/model-meta.ts       |  77 ++-----
 packages/ai-anthropic/src/text/reasoning.ts   |  72 ++++++
 .../src/text/text-provider-options.ts         | 157 +------------
 .../tests/anthropic-adapter.test.ts           |  16 +-
 .../tests/chat-per-model-type-safety.test.ts  | 208 ++++++------------
 .../ai-anthropic/tests/model-meta.test.ts     |  89 +++-----
 .../tests/reasoning-request.test.ts           | 157 +++++++++++++
 scripts/model-sync/native-insert.test.ts      |   4 +-
 scripts/model-sync/provider-supports.test.ts  |  35 +--
 scripts/model-sync/provider-supports.ts       |  39 +---
 scripts/sync-provider-models.ts               |   5 +-
 12 files changed, 415 insertions(+), 502 deletions(-)
 create mode 100644 packages/ai-anthropic/src/text/reasoning.ts
 create mode 100644 packages/ai-anthropic/tests/reasoning-request.test.ts

diff --git a/packages/ai-anthropic/src/adapters/text.ts b/packages/ai-anthropic/src/adapters/text.ts
index 706a2df013..f8a1da9595 100644
--- a/packages/ai-anthropic/src/adapters/text.ts
+++ b/packages/ai-anthropic/src/adapters/text.ts
@@ -13,6 +13,9 @@ import {
   readCodeExecutionSkills,
 } from '../tools/code-execution-tool'
 import { validateTextProviderOptions } from '../text/text-provider-options'
+import { anthropicThinking } from '../text/reasoning'
+import { ANTHROPIC_MODEL_REASONING } from '../model-reasoning'
+import type { AnthropicModelReasoningByName } from '../model-reasoning'
 import { buildAnthropicUsage } from '../usage'
 import {
   createAnthropicClient,
@@ -286,6 +289,12 @@ type ResolveInputModalities<TModel extends string> =
     ? AnthropicModelInputModalitiesByName[TModel]
     : readonly ['text', 'image', 'document']
 
+/** The reasoning levels of a model, for `chat({ reasoning })`. `never`: none. */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof AnthropicModelReasoningByName
+    ? AnthropicModelReasoningByName[TModel]
+    : never
+
 type ResolveToolCapabilities<TModel extends string> =
   TModel extends keyof AnthropicChatModelToolCapabilitiesByName
     ? NonNullable<AnthropicChatModelToolCapabilitiesByName[TModel]>
@@ -336,7 +345,8 @@ export class AnthropicTextAdapter<
   unknown,
   // TSystemPromptMetadata — narrows `systemPrompts[i].metadata` at the
   // chat() call site so users get `cache_control` autocomplete.
-  AnthropicSystemPromptMetadata
+  AnthropicSystemPromptMetadata,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   readonly name = 'anthropic' as const
@@ -369,9 +379,11 @@ export class AnthropicTextAdapter<
 
       // `betas` is attached at the call site rather than in the shared mapper
       // because the beta set depends on both the tools and the modelOptions.
+      // The request, not modelOptions: `reasoning` can turn budget
+      // thinking (and so the interleaved-thinking beta) on.
       const betas = computeAnthropicBetas(
         options.tools,
-        options.modelOptions,
+        requestParams,
         messagesHaveFileSource(options.messages),
       )
 
@@ -462,7 +474,7 @@ export class AnthropicTextAdapter<
       )
       const betas = computeAnthropicBetas(
         chatOptions.tools,
-        chatOptions.modelOptions,
+        requestParams,
         messagesHaveFileSource(chatOptions.messages),
       )
       // Make non-streaming request with tool_choice forced to our structured output tool
@@ -545,12 +557,9 @@ export class AnthropicTextAdapter<
         'cache_control',
         'container',
         'context_management',
-        'effort',
         'mcp_servers',
-        'output_config',
         'service_tier',
         'stop_sequences',
-        'thinking',
         'tool_choice',
         'top_k',
         'temperature',
@@ -596,9 +605,16 @@ export class AnthropicTextAdapter<
       }
     }
 
+    // `chat({ reasoning })`, as this model's thinking fields.
+    const { output_config: reasoningOutputConfig, ...thinkingFields } =
+      anthropicThinking(
+        this.model,
+        options.reasoning,
+        ANTHROPIC_MODEL_REASONING[this.model],
+      )
     const thinkingBudget =
-      validProviderOptions.thinking?.type === 'enabled'
-        ? validProviderOptions.thinking.budget_tokens
+      thinkingFields.thinking?.type === 'enabled'
+        ? thinkingFields.thinking.budget_tokens
         : undefined
     // Anthropic's Messages API *requires* `max_tokens`, so we must always send a
     // value. When the caller doesn't specify one, default to the resolved
@@ -644,17 +660,22 @@ export class AnthropicTextAdapter<
     const combinedSchema = options.outputSchema as
       | Record<string, unknown>
       | undefined
-    const outputConfig = combinedSchema
-      ? {
-          output_config: {
-            ...(validProviderOptions.output_config ?? {}),
-            format: {
-              type: 'json_schema' as const,
-              schema: combinedSchema,
+    const outputConfig =
+      combinedSchema || reasoningOutputConfig
+        ? {
+            output_config: {
+              ...reasoningOutputConfig,
+              ...(combinedSchema
+                ? {
+                    format: {
+                      type: 'json_schema' as const,
+                      schema: combinedSchema,
+                    },
+                  }
+                : {}),
             },
-          },
-        }
-      : undefined
+          }
+        : undefined
 
     // Lift skills attached to a `code_execution` tool into the top-level
     // `container.skills` request param (Anthropic's required shape). Preserve any
@@ -687,6 +708,7 @@ export class AnthropicTextAdapter<
       ...(systemBlocks !== undefined && { system: systemBlocks }),
       ...(tools !== undefined && { tools }),
       ...validProviderOptions,
+      ...thinkingFields,
       ...(outputConfig ?? {}),
     }
     validateTextProviderOptions(requestParams)
diff --git a/packages/ai-anthropic/src/model-meta.ts b/packages/ai-anthropic/src/model-meta.ts
index 462f6299d1..fbc0a67027 100644
--- a/packages/ai-anthropic/src/model-meta.ts
+++ b/packages/ai-anthropic/src/model-meta.ts
@@ -1,18 +1,13 @@
 import type { Modality } from '@tanstack/ai'
 import type {
-  AnthropicAdaptiveOnlyThinkingOptions,
-  AnthropicAdaptiveOrDisabledThinkingOptions,
-  AnthropicAdaptiveThinkingOptions,
   AnthropicCacheControlOptions,
   AnthropicContainerOptions,
   AnthropicContextManagementOptions,
   AnthropicMCPOptions,
   AnthropicMaxTokensOptions,
-  AnthropicOutputConfigOptions,
   AnthropicSamplingOptions,
   AnthropicServiceTierOptions,
   AnthropicStopSequencesOptions,
-  AnthropicThinkingOptions,
   AnthropicToolChoiceOptions,
 } from './text/text-provider-options'
 
@@ -102,7 +97,6 @@ const CLAUDE_OPUS_4_6 = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveThinkingOptions &
     AnthropicToolChoiceOptions &
     AnthropicSamplingOptions
 >
@@ -142,7 +136,6 @@ const CLAUDE_OPUS_4_5 = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicThinkingOptions &
     AnthropicToolChoiceOptions &
     AnthropicSamplingOptions
 >
@@ -185,7 +178,6 @@ const CLAUDE_SONNET_4_6 = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveThinkingOptions &
     AnthropicToolChoiceOptions &
     AnthropicSamplingOptions
 >
@@ -225,7 +217,6 @@ const CLAUDE_SONNET_4_5 = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicThinkingOptions &
     AnthropicToolChoiceOptions &
     AnthropicSamplingOptions
 >
@@ -265,7 +256,6 @@ const CLAUDE_HAIKU_4_5 = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicThinkingOptions &
     AnthropicToolChoiceOptions &
     AnthropicSamplingOptions
 >
@@ -305,7 +295,6 @@ const CLAUDE_OPUS_4_1 = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicThinkingOptions &
     AnthropicToolChoiceOptions &
     AnthropicSamplingOptions
 >
@@ -349,10 +338,8 @@ const CLAUDE_OPUS_4_7 = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveOrDisabledThinkingOptions &
     AnthropicToolChoiceOptions &
-    AnthropicMaxTokensOptions &
-    AnthropicOutputConfigOptions
+    AnthropicMaxTokensOptions
 >
 
 // Claude Opus 4.8 keeps the same request surface as Opus 4.7: adaptive
@@ -393,10 +380,8 @@ const CLAUDE_OPUS_4_8 = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveOrDisabledThinkingOptions &
     AnthropicToolChoiceOptions &
-    AnthropicMaxTokensOptions &
-    AnthropicOutputConfigOptions
+    AnthropicMaxTokensOptions
 >
 
 // Claude Fable 5: thinking is always on — the only accepted explicit
@@ -440,10 +425,8 @@ const CLAUDE_FABLE_5 = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveOnlyThinkingOptions &
     AnthropicToolChoiceOptions &
-    AnthropicMaxTokensOptions &
-    AnthropicOutputConfigOptions
+    AnthropicMaxTokensOptions
 >
 
 // Claude Sonnet 5: adaptive thinking is the default (omitting `thinking`
@@ -488,10 +471,8 @@ const CLAUDE_SONNET_5 = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveOrDisabledThinkingOptions &
     AnthropicToolChoiceOptions &
-    AnthropicMaxTokensOptions &
-    AnthropicOutputConfigOptions
+    AnthropicMaxTokensOptions
 >
 
 /**
@@ -535,10 +516,8 @@ const CLAUDE_OPUS_5 = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicThinkingOptions &
     AnthropicToolChoiceOptions &
-    AnthropicSamplingOptions &
-    AnthropicOutputConfigOptions
+    AnthropicSamplingOptions
 >
 
 const CLAUDE_OPUS_5_FAST = {
@@ -565,7 +544,6 @@ const CLAUDE_OPUS_5_FAST = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicThinkingOptions &
     AnthropicToolChoiceOptions &
     AnthropicSamplingOptions
 >
@@ -603,10 +581,8 @@ const CLAUDE_FABLE_5_1 = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveOnlyThinkingOptions &
     AnthropicToolChoiceOptions &
-    AnthropicMaxTokensOptions &
-    AnthropicOutputConfigOptions
+    AnthropicMaxTokensOptions
 >
 
 const CLAUDE_OPUS_5_5 = {
@@ -643,10 +619,8 @@ const CLAUDE_OPUS_5_5 = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveOnlyThinkingOptions &
     AnthropicToolChoiceOptions &
-    AnthropicSamplingOptions &
-    AnthropicOutputConfigOptions
+    AnthropicSamplingOptions
 >
 
 const CLAUDE_SONNET_5_5 = {
@@ -685,7 +659,6 @@ const CLAUDE_SONNET_5_5 = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveOnlyThinkingOptions &
     AnthropicToolChoiceOptions &
     AnthropicSamplingOptions
 >
@@ -853,7 +826,6 @@ export type AnthropicChatModelProviderOptionsByName = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveThinkingOptions &
     AnthropicToolChoiceOptions &
     AnthropicSamplingOptions
   [CLAUDE_SONNET_4_6.id]: AnthropicCacheControlOptions &
@@ -862,7 +834,6 @@ export type AnthropicChatModelProviderOptionsByName = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveThinkingOptions &
     AnthropicToolChoiceOptions &
     AnthropicSamplingOptions
 
@@ -873,7 +844,6 @@ export type AnthropicChatModelProviderOptionsByName = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicThinkingOptions &
     AnthropicToolChoiceOptions &
     AnthropicSamplingOptions
   [CLAUDE_SONNET_4_5.id]: AnthropicCacheControlOptions &
@@ -882,7 +852,6 @@ export type AnthropicChatModelProviderOptionsByName = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicThinkingOptions &
     AnthropicToolChoiceOptions &
     AnthropicSamplingOptions
   [CLAUDE_HAIKU_4_5.id]: AnthropicCacheControlOptions &
@@ -891,7 +860,6 @@ export type AnthropicChatModelProviderOptionsByName = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicThinkingOptions &
     AnthropicToolChoiceOptions &
     AnthropicSamplingOptions
   [CLAUDE_OPUS_4_1.id]: AnthropicCacheControlOptions &
@@ -900,7 +868,6 @@ export type AnthropicChatModelProviderOptionsByName = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicThinkingOptions &
     AnthropicToolChoiceOptions &
     AnthropicSamplingOptions
 
@@ -912,20 +879,16 @@ export type AnthropicChatModelProviderOptionsByName = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveOrDisabledThinkingOptions &
     AnthropicToolChoiceOptions &
-    AnthropicMaxTokensOptions &
-    AnthropicOutputConfigOptions
+    AnthropicMaxTokensOptions
   [CLAUDE_OPUS_4_8.id]: AnthropicCacheControlOptions &
     AnthropicContainerOptions &
     AnthropicContextManagementOptions &
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveOrDisabledThinkingOptions &
     AnthropicToolChoiceOptions &
-    AnthropicMaxTokensOptions &
-    AnthropicOutputConfigOptions
+    AnthropicMaxTokensOptions
 
   // Claude Fable 5: thinking always on (adaptive-only config); sampling
   // parameters removed — see the CLAUDE_FABLE_5 constant above.
@@ -935,10 +898,8 @@ export type AnthropicChatModelProviderOptionsByName = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveOnlyThinkingOptions &
     AnthropicToolChoiceOptions &
-    AnthropicMaxTokensOptions &
-    AnthropicOutputConfigOptions
+    AnthropicMaxTokensOptions
   // Claude Sonnet 5: adaptive thinking by default, explicit disable
   // allowed; no budget_tokens, no sampling parameters — see the
   // CLAUDE_SONNET_5 constant above.
@@ -948,25 +909,20 @@ export type AnthropicChatModelProviderOptionsByName = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveOrDisabledThinkingOptions &
     AnthropicToolChoiceOptions &
-    AnthropicMaxTokensOptions &
-    AnthropicOutputConfigOptions
+    AnthropicMaxTokensOptions
   [CLAUDE_OPUS_5.id]: AnthropicContainerOptions &
     AnthropicContextManagementOptions &
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicThinkingOptions &
     AnthropicToolChoiceOptions &
-    AnthropicSamplingOptions &
-    AnthropicOutputConfigOptions
+    AnthropicSamplingOptions
   [CLAUDE_OPUS_5_FAST.id]: AnthropicContainerOptions &
     AnthropicContextManagementOptions &
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicThinkingOptions &
     AnthropicToolChoiceOptions &
     AnthropicSamplingOptions
   [CLAUDE_FABLE_5_1.id]: AnthropicCacheControlOptions &
@@ -975,27 +931,22 @@ export type AnthropicChatModelProviderOptionsByName = {
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveOnlyThinkingOptions &
     AnthropicToolChoiceOptions &
-    AnthropicMaxTokensOptions &
-    AnthropicOutputConfigOptions
+    AnthropicMaxTokensOptions
   [CLAUDE_OPUS_5_5.id]: AnthropicCacheControlOptions &
     AnthropicContainerOptions &
     AnthropicContextManagementOptions &
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveOnlyThinkingOptions &
     AnthropicToolChoiceOptions &
-    AnthropicSamplingOptions &
-    AnthropicOutputConfigOptions
+    AnthropicSamplingOptions
   [CLAUDE_SONNET_5_5.id]: AnthropicCacheControlOptions &
     AnthropicContainerOptions &
     AnthropicContextManagementOptions &
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
-    AnthropicAdaptiveOnlyThinkingOptions &
     AnthropicToolChoiceOptions &
     AnthropicSamplingOptions
 }
diff --git a/packages/ai-anthropic/src/text/reasoning.ts b/packages/ai-anthropic/src/text/reasoning.ts
new file mode 100644
index 0000000000..2dd83536dd
--- /dev/null
+++ b/packages/ai-anthropic/src/text/reasoning.ts
@@ -0,0 +1,72 @@
+import {
+  reasoningBudget,
+  resolveReasoning,
+} from '@tanstack/ai/adapter-internals'
+import type { ModelReasoning, ReasoningRequest } from '@tanstack/ai'
+
+type AnthropicEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+
+const EFFORTS: ReadonlyArray<string> = ['low', 'medium', 'high', 'xhigh', 'max']
+const isEffort = (value: string): value is AnthropicEffort =>
+  EFFORTS.includes(value)
+
+/**
+ * Claude 4.6 takes the effort as the top-level `effort` field. Claude 4.7 and
+ * later take `output_config.effort`.
+ */
+const TOP_LEVEL_EFFORT = new Set(['claude-opus-4-6', 'claude-sonnet-4-6'])
+
+/** The Messages API thinking fields for one request. */
+export interface AnthropicThinkingFields {
+  thinking?:
+    | { type: 'adaptive'; display: 'summarized' | 'omitted' }
+    | { type: 'enabled'; budget_tokens: number }
+    | { type: 'disabled' }
+  effort?: AnthropicEffort
+  output_config?: { effort: AnthropicEffort }
+}
+
+/**
+ * The thinking fields for `chat({ reasoning })`:
+ * - `off`: thinking disabled. A model that cannot stop thinking never gets
+ *   here, because the clamp moves `off` to its lowest level.
+ * - a model with a token budget and no effort levels, or a request with
+ *   `budgetTokens`: `thinking.type: 'enabled'` with the budget (pi's table
+ *   when the request sets none).
+ * - otherwise adaptive thinking with the model's effort for the level.
+ *   `summary` picks whether the thinking text streams back.
+ */
+export function anthropicThinking(
+  model: string,
+  request: ReasoningRequest | undefined,
+  reasoning: ModelReasoning | undefined,
+): AnthropicThinkingFields {
+  const resolved = resolveReasoning(request, reasoning)
+  if (!resolved || !reasoning) return {}
+  if (resolved.level === 'off') return { thinking: { type: 'disabled' } }
+  const budgetOnly =
+    reasoning.budget && (resolved.budgetTokens !== undefined || !reasoning.map)
+  if (budgetOnly)
+    return {
+      thinking: {
+        type: 'enabled',
+        budget_tokens: reasoningBudget({
+          level: resolved.level,
+          summary: resolved.summary,
+          ...(resolved.budgetTokens !== undefined
+            ? { budgetTokens: resolved.budgetTokens }
+            : {}),
+        }),
+      },
+    }
+  const thinking = {
+    type: 'adaptive' as const,
+    display: resolved.summary ? ('summarized' as const) : ('omitted' as const),
+  }
+  const effort = resolved.value
+  if (!reasoning.map || effort === null || !isEffort(effort))
+    return { thinking }
+  return TOP_LEVEL_EFFORT.has(model)
+    ? { thinking, effort }
+    : { thinking, output_config: { effort } }
+}
diff --git a/packages/ai-anthropic/src/text/text-provider-options.ts b/packages/ai-anthropic/src/text/text-provider-options.ts
index c69900896f..a0df6127d8 100644
--- a/packages/ai-anthropic/src/text/text-provider-options.ts
+++ b/packages/ai-anthropic/src/text/text-provider-options.ts
@@ -1,3 +1,4 @@
+import type { AnthropicThinkingFields } from './reasoning'
 import type {
   BetaContextManagementConfig,
   BetaMessageParam,
@@ -109,115 +110,6 @@ If you want the model to stop generating when it encounters custom strings of te
   stop_sequences?: Array<string>
 }
 
-export interface AnthropicThinkingOptions {
-  /**
-     * Configuration for enabling Claude's extended thinking.
-
-When enabled, responses include thinking content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your max_tokens limit.
-     */
-  thinking?:
-    | {
-        /**
-* Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality.
-
-Must be ≥1024 and less than max_tokens
-*/
-        budget_tokens: number
-
-        type: 'enabled'
-      }
-    | {
-        type: 'disabled'
-      }
-}
-
-export interface AnthropicAdaptiveThinkingOptions {
-  /**
-   * Configuration for Claude's adaptive thinking (Opus 4.6+).
-   *
-   * In adaptive mode, Claude dynamically decides when and how much to think.
-   * Use the effort parameter to control thinking depth.
-   * `thinking: {type: "enabled"}` with `budget_tokens` is deprecated on Opus 4.6.
-   */
-  thinking?:
-    | {
-        type: 'adaptive'
-        /**
-         * Controls what (if any) thinking content is streamed back.
-         *
-         * - `'summarized'`: stream summarized thinking via `thinking_delta`
-         *   events (the user-visible reasoning text).
-         * - `'omitted'`: stream the thinking block's `signature_delta` only
-         *   (no reasoning text reaches the client).
-         *
-         * On Claude Opus 4.6 the default is `'summarized'`. On
-         * Claude Opus 4.7 the default flipped to `'omitted'` — callers
-         * must set `'summarized'` explicitly to get the reasoning text.
-         */
-        display?: 'summarized' | 'omitted'
-      }
-    | {
-        /**
-         * @deprecated Use `type: 'adaptive'` with the effort parameter on Opus 4.6+.
-         */
-        budget_tokens: number
-        type: 'enabled'
-      }
-    | {
-        type: 'disabled'
-      }
-}
-
-/**
- * Thinking configuration for models where thinking is always on
- * (e.g. Claude Fable 5).
- *
- * On these models the only accepted explicit configuration is
- * `{type: 'adaptive'}` — both `{type: 'disabled'}` and
- * `{type: 'enabled', budget_tokens}` are rejected with a 400. Omitting the
- * `thinking` field entirely also runs adaptive thinking.
- */
-export interface AnthropicAdaptiveOnlyThinkingOptions {
-  thinking?: {
-    type: 'adaptive'
-    /**
-     * Controls what (if any) thinking content is streamed back.
-     *
-     * - `'summarized'`: stream summarized thinking via `thinking_delta`
-     *   events (the user-visible reasoning text).
-     * - `'omitted'` (default): stream the thinking block's
-     *   `signature_delta` only (no reasoning text reaches the client).
-     */
-    display?: 'summarized' | 'omitted'
-  }
-}
-
-/**
- * Thinking configuration for models that accept adaptive thinking or an
- * explicit opt-out, but no manual token budget (e.g. Claude Sonnet 5,
- * Claude Opus 4.7/4.8).
- *
- * `{type: 'enabled', budget_tokens}` is rejected with a 400 on these
- * models. On Claude Sonnet 5, omitting the `thinking` field runs adaptive
- * thinking by default; on Opus 4.7/4.8 it runs without thinking — set
- * `{type: 'adaptive'}` explicitly there.
- */
-export interface AnthropicAdaptiveOrDisabledThinkingOptions {
-  thinking?:
-    | {
-        type: 'adaptive'
-        /**
-         * Controls what (if any) thinking content is streamed back.
-         * Defaults to `'omitted'` — set `'summarized'` to receive the
-         * reasoning text.
-         */
-        display?: 'summarized' | 'omitted'
-      }
-    | {
-        type: 'disabled'
-      }
-}
-
 /**
  * `max_tokens` on its own, for models that reject the sampling parameters
  * (`temperature`, `top_p`, `top_k`) — e.g. Claude Fable 5 and Claude Opus
@@ -232,42 +124,6 @@ export interface AnthropicMaxTokensOptions {
   max_tokens?: number
 }
 
-export interface AnthropicEffortOptions {
-  /**
-   * Controls the thinking depth for adaptive thinking mode (Opus 4.6+).
-   *
-   * - `max`: Absolute highest capability
-   * - `high`: Default - Claude will almost always think
-   * - `medium`: Balanced cost-quality
-   * - `low`: May skip thinking for simpler problems
-   */
-  effort?: 'max' | 'high' | 'medium' | 'low'
-}
-
-export interface AnthropicOutputConfigOptions {
-  /**
-   * Output configuration for the model's response.
-   *
-   * On Claude 4.7+ the top-level `effort` field was relocated under
-   * `output_config.effort`, and `thinking: { type: 'enabled', budget_tokens }`
-   * was replaced by `thinking: { type: 'adaptive' }` paired with
-   * `output_config.effort`. Earlier models continue to accept the legacy
-   * top-level `effort` / `thinking.type: 'enabled'` shape.
-   *
-   * The engine also writes `output_config.format` here when the caller
-   * passes `outputSchema` to a Claude 4.5+ adapter (issue #605 native
-   * combined mode). Both fields coexist: user-supplied `effort` is
-   * preserved when the engine adds `format`.
-   */
-  output_config?: {
-    /**
-     * `'xhigh'` is accepted on Claude Opus 4.7+, Claude Sonnet 5, and
-     * Claude Fable 5; older models support `'low'`–`'max'` only.
-     */
-    effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null
-  }
-}
-
 export interface AnthropicToolChoiceOptions {
   tool_choice?: BetaToolChoiceAny | BetaToolChoiceTool | BetaToolChoiceAuto
 }
@@ -308,14 +164,13 @@ export type ExternalTextProviderOptions = AnthropicCacheControlOptions &
   AnthropicMCPOptions &
   AnthropicServiceTierOptions &
   AnthropicStopSequencesOptions &
-  AnthropicThinkingOptions &
   AnthropicToolChoiceOptions &
-  AnthropicSamplingOptions &
-  Partial<AnthropicAdaptiveThinkingOptions> &
-  Partial<AnthropicEffortOptions> &
-  Partial<AnthropicOutputConfigOptions>
+  AnthropicSamplingOptions
 
-export interface InternalTextProviderOptions extends ExternalTextProviderOptions {
+export interface InternalTextProviderOptions
+  extends
+    ExternalTextProviderOptions,
+    Omit<AnthropicThinkingFields, 'output_config'> {
   model: string
 
   messages: Array<BetaMessageParam>
diff --git a/packages/ai-anthropic/tests/anthropic-adapter.test.ts b/packages/ai-anthropic/tests/anthropic-adapter.test.ts
index b13ef7bec8..63fc322ef8 100644
--- a/packages/ai-anthropic/tests/anthropic-adapter.test.ts
+++ b/packages/ai-anthropic/tests/anthropic-adapter.test.ts
@@ -420,7 +420,6 @@ describe('Anthropic adapter option mapping', () => {
       ],
       service_tier: 'standard_only',
       stop_sequences: ['</done>'],
-      thinking: { type: 'enabled', budget_tokens: 1500 },
       top_k: 5,
       max_tokens: 3000,
       temperature: 0.4,
@@ -449,6 +448,7 @@ describe('Anthropic adapter option mapping', () => {
       ],
       tools: [weatherTool],
       modelOptions: providerOptions,
+      reasoning: { level: 'low', budgetTokens: 1500 },
     })) {
       chunks.push(chunk)
     }
@@ -464,7 +464,7 @@ describe('Anthropic adapter option mapping', () => {
       mcp_servers: providerOptions.mcp_servers,
       service_tier: providerOptions.service_tier,
       stop_sequences: providerOptions.stop_sequences,
-      thinking: providerOptions.thinking,
+      thinking: { type: 'enabled', budget_tokens: 1500 },
       top_k: providerOptions.top_k,
     })
     expect(payload.stream).toBe(true)
@@ -1125,9 +1125,7 @@ describe('Anthropic adapter option mapping', () => {
         { role: 'user', content: 'What should I wear?' },
       ],
       tools: [weatherTool],
-      modelOptions: {
-        thinking: { type: 'enabled', budget_tokens: 1024 },
-      } satisfies AnthropicTextProviderOptions,
+      reasoning: { level: 'minimal', budgetTokens: 1024 },
     })) {
       chunks.push(chunk)
     }
@@ -1175,9 +1173,7 @@ describe('Anthropic adapter option mapping', () => {
         },
         { role: 'user', content: 'Continue.' },
       ],
-      modelOptions: {
-        thinking: { type: 'enabled', budget_tokens: 1024 },
-      } satisfies AnthropicTextProviderOptions,
+      reasoning: { level: 'minimal', budgetTokens: 1024 },
     })) {
       chunks.push(chunk)
     }
@@ -1276,9 +1272,7 @@ describe('Anthropic adapter option mapping', () => {
         },
       ],
       tools: [createBlockTool],
-      modelOptions: {
-        thinking: { type: 'enabled', budget_tokens: 1024 },
-      } satisfies AnthropicTextProviderOptions,
+      reasoning: { level: 'minimal', budgetTokens: 1024 },
     })) {
       // consume
     }
diff --git a/packages/ai-anthropic/tests/chat-per-model-type-safety.test.ts b/packages/ai-anthropic/tests/chat-per-model-type-safety.test.ts
index 4675d38896..22c45706a5 100644
--- a/packages/ai-anthropic/tests/chat-per-model-type-safety.test.ts
+++ b/packages/ai-anthropic/tests/chat-per-model-type-safety.test.ts
@@ -1,5 +1,6 @@
 /**
- * Per-model type-safety tests for Anthropic chat() modelOptions.
+ * Per-model type-safety tests for Anthropic chat() modelOptions and
+ * `reasoning`.
  *
  * Positive cases: each supported (model, option) pair compiles cleanly.
  * Negative cases: each unsupported option produces a `@ts-expect-error`.
@@ -19,7 +20,7 @@ beforeAll(() => {
 })
 
 describe('Anthropic per-model chat modelOptions gating', () => {
-  describe('claude-opus-4-6 — full superset (thinking + priority tier + all option groups)', () => {
+  describe('claude-opus-4-6 — priority tier + all option groups', () => {
     it('accepts every option group', () => {
       chat({
         adapter: anthropicText('claude-opus-4-6'),
@@ -30,42 +31,41 @@ describe('Anthropic per-model chat modelOptions gating', () => {
           mcp_servers: [],
           service_tier: 'auto',
           stop_sequences: ['STOP'],
-          thinking: { type: 'enabled', budget_tokens: 2048 },
           tool_choice: { type: 'auto' },
           top_k: 5,
         },
       })
     })
 
-    it('accepts adaptive thinking (supported alongside the deprecated budget shape)', () => {
+    it('rejects unknown options', () => {
       chat({
         adapter: anthropicText('claude-opus-4-6'),
         messages: [{ role: 'user', content: 'hi' }],
         modelOptions: {
-          thinking: { type: 'adaptive', display: 'summarized' },
+          // @ts-expect-error - 'unknownOption' does not exist
+          unknownOption: true,
         },
       })
     })
 
-    it('rejects unknown options', () => {
+    it('rejects thinking in modelOptions (chat({ reasoning }) owns it)', () => {
       chat({
         adapter: anthropicText('claude-opus-4-6'),
         messages: [{ role: 'user', content: 'hi' }],
         modelOptions: {
-          // @ts-expect-error - 'unknownOption' does not exist
-          unknownOption: true,
+          // @ts-expect-error - thinking is set with `reasoning`
+          thinking: { type: 'enabled', budget_tokens: 2048 },
         },
       })
     })
   })
 
-  describe('claude-haiku-4-5 — thinking + priority tier', () => {
-    it('accepts thinking + service_tier + tools options', () => {
+  describe('claude-haiku-4-5 — priority tier', () => {
+    it('accepts service_tier + tools options', () => {
       chat({
         adapter: anthropicText('claude-haiku-4-5'),
         messages: [{ role: 'user', content: 'hi' }],
         modelOptions: {
-          thinking: { type: 'enabled', budget_tokens: 1024 },
           service_tier: 'standard_only',
           tool_choice: { type: 'auto' },
         },
@@ -73,14 +73,12 @@ describe('Anthropic per-model chat modelOptions gating', () => {
     })
   })
 
-  describe('claude-opus-4-8 — adaptive thinking, no budget_tokens, no sampling', () => {
-    it('accepts adaptive thinking + output_config effort (incl. xhigh) + base options', () => {
+  describe('claude-opus-4-8 — no sampling', () => {
+    it('accepts the base options', () => {
       chat({
         adapter: anthropicText('claude-opus-4-8'),
         messages: [{ role: 'user', content: 'hi' }],
         modelOptions: {
-          thinking: { type: 'adaptive', display: 'summarized' },
-          output_config: { effort: 'xhigh' },
           service_tier: 'auto',
           stop_sequences: ['STOP'],
           tool_choice: { type: 'auto' },
@@ -89,17 +87,6 @@ describe('Anthropic per-model chat modelOptions gating', () => {
       })
     })
 
-    it('rejects manual `budget_tokens` thinking', () => {
-      chat({
-        adapter: anthropicText('claude-opus-4-8'),
-        messages: [{ role: 'user', content: 'hi' }],
-        modelOptions: {
-          // @ts-expect-error - budget_tokens thinking returns a 400 on claude-opus-4-8
-          thinking: { type: 'enabled', budget_tokens: 2048 },
-        },
-      })
-    })
-
     it('rejects sampling parameters', () => {
       chat({
         adapter: anthropicText('claude-opus-4-8'),
@@ -112,43 +99,7 @@ describe('Anthropic per-model chat modelOptions gating', () => {
     })
   })
 
-  describe('claude-sonnet-5 — adaptive thinking, no budget_tokens, no sampling', () => {
-    it('accepts adaptive thinking + output_config effort (incl. xhigh) + base options', () => {
-      chat({
-        adapter: anthropicText('claude-sonnet-5'),
-        messages: [{ role: 'user', content: 'hi' }],
-        modelOptions: {
-          thinking: { type: 'adaptive', display: 'summarized' },
-          output_config: { effort: 'xhigh' },
-          service_tier: 'auto',
-          stop_sequences: ['STOP'],
-          tool_choice: { type: 'auto' },
-          max_tokens: 2048,
-        },
-      })
-    })
-
-    it('accepts explicit thinking opt-out', () => {
-      chat({
-        adapter: anthropicText('claude-sonnet-5'),
-        messages: [{ role: 'user', content: 'hi' }],
-        modelOptions: {
-          thinking: { type: 'disabled' },
-        },
-      })
-    })
-
-    it('rejects manual `budget_tokens` thinking', () => {
-      chat({
-        adapter: anthropicText('claude-sonnet-5'),
-        messages: [{ role: 'user', content: 'hi' }],
-        modelOptions: {
-          // @ts-expect-error - budget_tokens thinking returns a 400 on claude-sonnet-5
-          thinking: { type: 'enabled', budget_tokens: 2048 },
-        },
-      })
-    })
-
+  describe('claude-sonnet-5 — no sampling', () => {
     it('rejects sampling parameters', () => {
       chat({
         adapter: anthropicText('claude-sonnet-5'),
@@ -169,44 +120,7 @@ describe('Anthropic per-model chat modelOptions gating', () => {
     })
   })
 
-  describe('claude-fable-5 — thinking always on (adaptive-only), no sampling', () => {
-    it('accepts adaptive thinking + output_config effort (incl. xhigh) + base options', () => {
-      chat({
-        adapter: anthropicText('claude-fable-5'),
-        messages: [{ role: 'user', content: 'hi' }],
-        modelOptions: {
-          thinking: { type: 'adaptive', display: 'summarized' },
-          output_config: { effort: 'xhigh' },
-          service_tier: 'auto',
-          stop_sequences: ['STOP'],
-          tool_choice: { type: 'auto' },
-          max_tokens: 2048,
-        },
-      })
-    })
-
-    it('rejects explicit thinking opt-out (400 on claude-fable-5)', () => {
-      chat({
-        adapter: anthropicText('claude-fable-5'),
-        messages: [{ role: 'user', content: 'hi' }],
-        modelOptions: {
-          // @ts-expect-error - thinking cannot be disabled on claude-fable-5
-          thinking: { type: 'disabled' },
-        },
-      })
-    })
-
-    it('rejects manual `budget_tokens` thinking', () => {
-      chat({
-        adapter: anthropicText('claude-fable-5'),
-        messages: [{ role: 'user', content: 'hi' }],
-        modelOptions: {
-          // @ts-expect-error - budget_tokens thinking returns a 400 on claude-fable-5
-          thinking: { type: 'enabled', budget_tokens: 2048 },
-        },
-      })
-    })
-
+  describe('claude-fable-5 — no sampling', () => {
     it('rejects sampling parameters', () => {
       chat({
         adapter: anthropicText('claude-fable-5'),
@@ -227,20 +141,6 @@ describe('Anthropic per-model chat modelOptions gating', () => {
     })
   })
 
-  describe('claude-opus-5 — output_config effort', () => {
-    // The adapter writes `output_config.format` for this model and merges it
-    // over any caller-supplied `output_config`, so `effort` has to type-check.
-    it('accepts output_config effort', () => {
-      chat({
-        adapter: anthropicText('claude-opus-5'),
-        messages: [{ role: 'user', content: 'hi' }],
-        modelOptions: {
-          output_config: { effort: 'high' },
-        },
-      })
-    })
-  })
-
   describe('Model name type safety', () => {
     it('rejects unknown model names at the factory', () => {
       // @ts-expect-error - 'claude-fake-9000' is not a valid Anthropic chat model
@@ -249,13 +149,57 @@ describe('Anthropic per-model chat modelOptions gating', () => {
   })
 })
 
+describe('Anthropic per-model chat reasoning gating', () => {
+  it('budget models take a level, off, and budgetTokens', () => {
+    chat({
+      adapter: anthropicText('claude-haiku-4-5'),
+      messages: [{ role: 'user', content: 'hi' }],
+      reasoning: { level: 'low', budgetTokens: 2048, summary: true },
+    })
+    chat({
+      adapter: anthropicText('claude-haiku-4-5'),
+      messages: [{ role: 'user', content: 'hi' }],
+      reasoning: 'off',
+    })
+  })
+
+  it('adaptive-era models take effort levels up to max', () => {
+    chat({
+      adapter: anthropicText('claude-opus-4-8'),
+      messages: [{ role: 'user', content: 'hi' }],
+      reasoning: 'xhigh',
+    })
+    chat({
+      adapter: anthropicText('claude-opus-4-8'),
+      messages: [{ role: 'user', content: 'hi' }],
+      // @ts-expect-error - claude-opus-4-8 takes no token budget
+      reasoning: { level: 'high', budgetTokens: 2048 },
+    })
+  })
+
+  it('budget models stop at high', () => {
+    chat({
+      adapter: anthropicText('claude-haiku-4-5'),
+      messages: [{ role: 'user', content: 'hi' }],
+      // @ts-expect-error - claude-haiku-4-5 has no max level
+      reasoning: 'max',
+    })
+  })
+
+  it('claude-fable-5 cannot turn thinking off', () => {
+    chat({
+      adapter: anthropicText('claude-fable-5'),
+      messages: [{ role: 'user', content: 'hi' }],
+      // @ts-expect-error - thinking cannot be disabled on claude-fable-5
+      reasoning: 'off',
+    })
+  })
+})
+
 describe('Anthropic provider options shape assertions', () => {
   describe('claude-opus-4-6 — full feature set', () => {
     type Options = AnthropicChatModelProviderOptionsByName['claude-opus-4-6']
 
-    it('has thinking', () => {
-      expectTypeOf<Options>().toHaveProperty('thinking')
-    })
     it('has service_tier', () => {
       expectTypeOf<Options>().toHaveProperty('service_tier')
     })
@@ -271,15 +215,14 @@ describe('Anthropic provider options shape assertions', () => {
     it('has mcp_servers', () => {
       expectTypeOf<Options>().toHaveProperty('mcp_servers')
     })
+    it('has no thinking', () => {
+      expectTypeOf<Options>().not.toHaveProperty('thinking')
+    })
   })
 
-  describe('claude-sonnet-5 — adaptive thinking without sampling', () => {
+  describe('claude-sonnet-5 — no sampling', () => {
     type Options = AnthropicChatModelProviderOptionsByName['claude-sonnet-5']
 
-    it('has thinking and output_config', () => {
-      expectTypeOf<Options>().toHaveProperty('thinking')
-      expectTypeOf<Options>().toHaveProperty('output_config')
-    })
     it('has max_tokens but NOT temperature/top_p/top_k', () => {
       expectTypeOf<Options>().toHaveProperty('max_tokens')
       expectTypeOf<Options>().not.toHaveProperty('temperature')
@@ -288,26 +231,9 @@ describe('Anthropic provider options shape assertions', () => {
     })
   })
 
-  describe('claude-opus-5 — output_config alongside the schema', () => {
-    type Options = AnthropicChatModelProviderOptionsByName['claude-opus-5']
-
-    it('has output_config', () => {
-      expectTypeOf<Options>().toHaveProperty('output_config')
-    })
-  })
-
-  describe('claude-fable-5 — adaptive-only thinking without sampling', () => {
+  describe('claude-fable-5 — no sampling', () => {
     type Options = AnthropicChatModelProviderOptionsByName['claude-fable-5']
 
-    it('has thinking and output_config', () => {
-      expectTypeOf<Options>().toHaveProperty('thinking')
-      expectTypeOf<Options>().toHaveProperty('output_config')
-    })
-    it('thinking accepts only the adaptive shape', () => {
-      expectTypeOf<
-        NonNullable<Options['thinking']>['type']
-      >().toEqualTypeOf<'adaptive'>()
-    })
     it('has max_tokens but NOT temperature/top_p/top_k', () => {
       expectTypeOf<Options>().toHaveProperty('max_tokens')
       expectTypeOf<Options>().not.toHaveProperty('temperature')
diff --git a/packages/ai-anthropic/tests/model-meta.test.ts b/packages/ai-anthropic/tests/model-meta.test.ts
index 8b8023ffbc..065dea26c2 100644
--- a/packages/ai-anthropic/tests/model-meta.test.ts
+++ b/packages/ai-anthropic/tests/model-meta.test.ts
@@ -11,18 +11,14 @@ import type {
   AnthropicModelInputModalitiesByName,
 } from '../src/model-meta'
 import type { AnthropicMessageMetadataByModality } from '../src/message-types'
+import type { AnthropicModelReasoningByName } from '../src/model-reasoning'
 import type {
-  AnthropicAdaptiveOnlyThinkingOptions,
-  AnthropicAdaptiveOrDisabledThinkingOptions,
-  AnthropicAdaptiveThinkingOptions,
   AnthropicContainerOptions,
   AnthropicContextManagementOptions,
   AnthropicMCPOptions,
-  AnthropicOutputConfigOptions,
   AnthropicSamplingOptions,
   AnthropicServiceTierOptions,
   AnthropicStopSequencesOptions,
-  AnthropicThinkingOptions,
   AnthropicToolChoiceOptions,
 } from '../src/text/text-provider-options'
 import type {
@@ -48,10 +44,10 @@ type MakeInputModalitiesTypes<TModalities extends ReadonlyArray<Modality>> = {
  * Type assertion tests for Anthropic model provider options.
  *
  * These tests verify that:
- * 1. Pre-4.6 models expose budget-based extended thinking + sampling options
- * 2. 4.6-generation models additionally expose the adaptive thinking shape
- * 3. Opus 4.7/4.8 and the 5-generation models expose ONLY adaptive-era
- *    options (no budget_tokens, no sampling parameters)
+ * 1. Pre-4.7 models expose sampling options
+ * 2. Opus 4.7/4.8 and the 5-generation models do not (they reject sampling)
+ * 3. No model takes thinking in modelOptions: `chat({ reasoning })` owns it,
+ *    with the levels from the generated reasoning map
  * 4. All models have base options (container, context management, MCP,
  *    stop sequences, tool choice) and the provider-options map covers
  *    every registered model
@@ -77,11 +73,8 @@ type AdaptiveEraModel =
   | 'claude-sonnet-5'
 
 describe('Anthropic Model Provider Options Type Assertions', () => {
-  describe('Pre-4.6 models — budget-based extended thinking + sampling', () => {
-    it('expose thinking, service_tier, sampling, and base options', () => {
-      expectTypeOf<
-        AnthropicChatModelProviderOptionsByName[BudgetThinkingModel]
-      >().toExtend<AnthropicThinkingOptions>()
+  describe('Pre-4.6 models — sampling options', () => {
+    it('expose service_tier, sampling, and base options', () => {
       expectTypeOf<
         AnthropicChatModelProviderOptionsByName[BudgetThinkingModel]
       >().toExtend<AnthropicServiceTierOptions>()
@@ -95,7 +88,6 @@ describe('Anthropic Model Provider Options Type Assertions', () => {
 
     it('expose the individual base properties', () => {
       type Options = AnthropicChatModelProviderOptionsByName['claude-opus-4-5']
-      expectTypeOf<Options>().toHaveProperty('thinking')
       expectTypeOf<Options>().toHaveProperty('service_tier')
       expectTypeOf<Options>().toHaveProperty('container')
       expectTypeOf<Options>().toHaveProperty('context_management')
@@ -106,40 +98,21 @@ describe('Anthropic Model Provider Options Type Assertions', () => {
     })
   })
 
-  describe('4.6-generation models — adaptive + deprecated budget thinking', () => {
-    it('claude-opus-4-6 exposes the adaptive thinking union and sampling', () => {
-      type Options = AnthropicChatModelProviderOptionsByName['claude-opus-4-6']
-      expectTypeOf<Options>().toExtend<AnthropicAdaptiveThinkingOptions>()
-      expectTypeOf<Options>().toExtend<AnthropicServiceTierOptions>()
-      expectTypeOf<Options>().toExtend<AnthropicSamplingOptions>()
-      expectTypeOf<Options>().toExtend<BaseOptions>()
-    })
-
-    it('claude-sonnet-4-6 exposes the adaptive thinking union and sampling', () => {
-      type Options =
-        AnthropicChatModelProviderOptionsByName['claude-sonnet-4-6']
-      expectTypeOf<Options>().toExtend<AnthropicAdaptiveThinkingOptions>()
+  describe('4.6-generation models — sampling options', () => {
+    it('claude-opus-4-6 and claude-sonnet-4-6 expose sampling', () => {
+      type Options = AnthropicChatModelProviderOptionsByName[
+        | 'claude-opus-4-6'
+        | 'claude-sonnet-4-6']
       expectTypeOf<Options>().toExtend<AnthropicServiceTierOptions>()
       expectTypeOf<Options>().toExtend<AnthropicSamplingOptions>()
       expectTypeOf<Options>().toExtend<BaseOptions>()
     })
   })
 
-  describe('Adaptive-era models (Opus 4.7/4.8, Sonnet 5) — no budget thinking, no sampling', () => {
-    it('expose adaptive-or-disabled thinking, output_config, and base options', () => {
-      expectTypeOf<
-        AnthropicChatModelProviderOptionsByName[AdaptiveEraModel]
-      >().toExtend<AnthropicAdaptiveOrDisabledThinkingOptions>()
-      expectTypeOf<
-        AnthropicChatModelProviderOptionsByName[AdaptiveEraModel]
-      >().toExtend<AnthropicOutputConfigOptions>()
-      expectTypeOf<
-        AnthropicChatModelProviderOptionsByName[AdaptiveEraModel]
-      >().toExtend<BaseOptions>()
-    })
-
+  describe('Adaptive-era models (Opus 4.7/4.8, Sonnet 5) — no sampling', () => {
     it('have max_tokens but NOT temperature/top_p/top_k', () => {
       type Options = AnthropicChatModelProviderOptionsByName[AdaptiveEraModel]
+      expectTypeOf<Options>().toExtend<BaseOptions>()
       expectTypeOf<Options>().toHaveProperty('max_tokens')
       expectTypeOf<Options>().not.toHaveProperty('temperature')
       expectTypeOf<Options>().not.toHaveProperty('top_p')
@@ -147,26 +120,30 @@ describe('Anthropic Model Provider Options Type Assertions', () => {
     })
   })
 
-  describe('claude-fable-5 — thinking always on (adaptive-only)', () => {
-    type Options = AnthropicChatModelProviderOptionsByName['claude-fable-5']
+  describe('thinking lives on chat({ reasoning }), not modelOptions', () => {
+    it('no model takes thinking, effort, or output_config in modelOptions', () => {
+      type Options =
+        AnthropicChatModelProviderOptionsByName[keyof AnthropicChatModelProviderOptionsByName]
+      expectTypeOf<Options>().not.toHaveProperty('thinking')
+      expectTypeOf<Options>().not.toHaveProperty('effort')
+      expectTypeOf<Options>().not.toHaveProperty('output_config')
+    })
 
-    it('exposes adaptive-only thinking, output_config, and base options', () => {
-      expectTypeOf<Options>().toExtend<AnthropicAdaptiveOnlyThinkingOptions>()
-      expectTypeOf<Options>().toExtend<AnthropicOutputConfigOptions>()
-      expectTypeOf<Options>().toExtend<BaseOptions>()
+    it('budget models take a token budget and can turn thinking off', () => {
+      type Reasoning = AnthropicModelReasoningByName['claude-haiku-4-5']
+      expectTypeOf<Reasoning['budget']>().toEqualTypeOf<true>()
+      expectTypeOf<'off'>().toExtend<Reasoning['levels']>()
     })
 
-    it('thinking accepts only the adaptive shape', () => {
-      expectTypeOf<
-        NonNullable<Options['thinking']>['type']
-      >().toEqualTypeOf<'adaptive'>()
+    it('adaptive-era models take effort levels up to max, with no budget', () => {
+      type Reasoning = AnthropicModelReasoningByName['claude-opus-4-8']
+      expectTypeOf<Reasoning['budget']>().toEqualTypeOf<false>()
+      expectTypeOf<'max'>().toExtend<Reasoning['levels']>()
     })
 
-    it('has max_tokens but NOT temperature/top_p/top_k', () => {
-      expectTypeOf<Options>().toHaveProperty('max_tokens')
-      expectTypeOf<Options>().not.toHaveProperty('temperature')
-      expectTypeOf<Options>().not.toHaveProperty('top_p')
-      expectTypeOf<Options>().not.toHaveProperty('top_k')
+    it('claude-fable-5 always thinks: off is not a level', () => {
+      type Levels = AnthropicModelReasoningByName['claude-fable-5']['levels']
+      expectTypeOf<'off'>().not.toExtend<Levels>()
     })
   })
 
diff --git a/packages/ai-anthropic/tests/reasoning-request.test.ts b/packages/ai-anthropic/tests/reasoning-request.test.ts
new file mode 100644
index 0000000000..f350cbbeb8
--- /dev/null
+++ b/packages/ai-anthropic/tests/reasoning-request.test.ts
@@ -0,0 +1,157 @@
+import { describe, expect, it, vi } from 'vitest'
+import { chat } from '@tanstack/ai'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { z } from 'zod'
+import { createAnthropicChatWithClient } from '../src'
+import type { ReasoningRequest, Tool } from '@tanstack/ai'
+import type { AnthropicChatModel } from '../src/model-meta'
+
+const logger = resolveDebugOption(false)
+
+function textStream(text: string) {
+  return (async function* () {
+    yield {
+      type: 'content_block_start',
+      index: 0,
+      content_block: { type: 'text', text: '' },
+    }
+    yield {
+      type: 'content_block_delta',
+      index: 0,
+      delta: { type: 'text_delta', text },
+    }
+    yield { type: 'content_block_stop', index: 0 }
+    yield {
+      type: 'message_delta',
+      delta: { stop_reason: 'end_turn' },
+      usage: { output_tokens: 5 },
+    }
+    yield { type: 'message_stop' }
+  })()
+}
+
+const lookup: Tool = {
+  name: 'lookup',
+  description: 'Look up a word',
+  inputSchema: z.object({ word: z.string() }),
+}
+
+/** Run one call and return the request body it sent. */
+async function send(
+  model: AnthropicChatModel,
+  reasoning: ReasoningRequest | undefined,
+  extra: { tools?: Array<Tool>; modelOptions?: Record<string, unknown> } = {},
+) {
+  const create = vi.fn().mockResolvedValue(textStream('ok'))
+  const adapter = createAnthropicChatWithClient(model, {
+    beta: { messages: { create } },
+  })
+  for await (const _chunk of adapter.chatStream({
+    logger,
+    model,
+    messages: [{ role: 'user', content: 'hi' }],
+    ...(reasoning ? { reasoning } : {}),
+    ...(extra.tools ? { tools: extra.tools } : {}),
+    ...(extra.modelOptions ? { modelOptions: extra.modelOptions } : {}),
+  })) {
+    // Drain the stream.
+  }
+  const [body] = create.mock.calls[0] ?? []
+  return body as Record<string, any>
+}
+
+const on = (level: ReasoningRequest['level']): ReasoningRequest => ({
+  level,
+  summary: true,
+})
+
+describe('Anthropic chat({ reasoning }) request shape', () => {
+  it('sends no thinking fields without a reasoning request', async () => {
+    const body = await send('claude-opus-5-5', undefined)
+    expect(body).not.toHaveProperty('thinking')
+    expect(body).not.toHaveProperty('effort')
+    expect(body).not.toHaveProperty('output_config')
+  })
+
+  it('adaptive models: adaptive thinking with output_config.effort', async () => {
+    const body = await send('claude-opus-5-5', on('xhigh'))
+    expect(body.thinking).toEqual({ type: 'adaptive', display: 'summarized' })
+    expect(body.output_config).toEqual({ effort: 'xhigh' })
+    expect(body).not.toHaveProperty('effort')
+  })
+
+  it('omits the thinking text when summary is false', async () => {
+    const body = await send('claude-opus-5-5', {
+      level: 'high',
+      summary: false,
+    })
+    expect(body.thinking).toEqual({ type: 'adaptive', display: 'omitted' })
+  })
+
+  it('Claude 4.6: the effort is a top-level field', async () => {
+    const body = await send('claude-opus-4-6', on('max'))
+    expect(body.thinking).toEqual({ type: 'adaptive', display: 'summarized' })
+    expect(body.effort).toBe('max')
+    expect(body).not.toHaveProperty('output_config')
+  })
+
+  it('Claude 4.6 with budgetTokens: budget thinking', async () => {
+    const body = await send('claude-opus-4-6', {
+      level: 'high',
+      summary: true,
+      budgetTokens: 5000,
+    })
+    expect(body.thinking).toEqual({ type: 'enabled', budget_tokens: 5000 })
+    expect(body).not.toHaveProperty('effort')
+  })
+
+  it('budget models: the level picks the budget, and max_tokens grows past it', async () => {
+    const body = await send('claude-haiku-4-5', on('medium'), {
+      modelOptions: { max_tokens: 4000 },
+    })
+    expect(body.thinking).toEqual({ type: 'enabled', budget_tokens: 8192 })
+    expect(body.max_tokens).toBe(8193)
+  })
+
+  it('budget thinking with tools turns on the interleaved-thinking beta', async () => {
+    const body = await send('claude-haiku-4-5', on('low'), { tools: [lookup] })
+    expect(body.thinking).toEqual({ type: 'enabled', budget_tokens: 2048 })
+    expect(body.betas).toContain('interleaved-thinking-2025-05-14')
+  })
+
+  it('off disables thinking', async () => {
+    const body = await send('claude-sonnet-5', on('off'))
+    expect(body.thinking).toEqual({ type: 'disabled' })
+    expect(body).not.toHaveProperty('output_config')
+  })
+
+  it('clamps a level the model does not have', async () => {
+    // claude-opus-4-8 has no `minimal`: it clamps up to `low`.
+    const minimal = await send('claude-opus-4-8', on('minimal'))
+    expect(minimal.output_config).toEqual({ effort: 'low' })
+    // claude-fable-5 cannot stop thinking: `off` clamps up to `low`.
+    const off = await send('claude-fable-5', on('off'))
+    expect(off.thinking).toEqual({ type: 'adaptive', display: 'summarized' })
+    expect(off.output_config).toEqual({ effort: 'low' })
+  })
+
+  it('keeps the effort beside the structured-output format', async () => {
+    const create = vi
+      .fn()
+      .mockResolvedValue(textStream(JSON.stringify({ word: 'hi' })))
+    const result = await chat({
+      adapter: createAnthropicChatWithClient('claude-opus-5-5', {
+        beta: { messages: { create } },
+      }),
+      messages: [{ role: 'user', content: 'hi' }],
+      outputSchema: z.object({ word: z.string() }),
+      reasoning: 'high',
+    })
+    expect(result).toEqual({ word: 'hi' })
+    const [body] = create.mock.calls[0] ?? []
+    expect(body.output_config).toMatchObject({
+      effort: 'high',
+      format: { type: 'json_schema' },
+    })
+  })
+})
diff --git a/scripts/model-sync/native-insert.test.ts b/scripts/model-sync/native-insert.test.ts
index 0e7a0a32db..7dfb17627c 100644
--- a/scripts/model-sync/native-insert.test.ts
+++ b/scripts/model-sync/native-insert.test.ts
@@ -52,7 +52,7 @@ const ANTHROPIC_CONFIG = {
 const FABLE_5_1 = {
   constName: 'CLAUDE_FABLE_5_1',
   providerOptionsEntry:
-    'AnthropicAdaptiveOnlyThinkingOptions & AnthropicMaxTokensOptions',
+    'AnthropicToolChoiceOptions & AnthropicMaxTokensOptions',
   hasMaxOutputTokens: true,
   acceptsCombinedToolsAndSchema: true,
 }
@@ -104,7 +104,7 @@ describe('applyChatModelCatalogInserts', () => {
       '[CLAUDE_FABLE_5_1.id]: typeof CLAUDE_FABLE_5_1.supports.input',
     )
     expect(result).toContain(
-      '[CLAUDE_FABLE_5_1.id]: AnthropicAdaptiveOnlyThinkingOptions & AnthropicMaxTokensOptions',
+      '[CLAUDE_FABLE_5_1.id]: AnthropicToolChoiceOptions & AnthropicMaxTokensOptions',
     )
     expect(result).toContain(
       '[CLAUDE_FABLE_5_1.id]: CLAUDE_FABLE_5_1.max_output_tokens,',
diff --git a/scripts/model-sync/provider-supports.test.ts b/scripts/model-sync/provider-supports.test.ts
index c2151b00c5..355c75eae4 100644
--- a/scripts/model-sync/provider-supports.test.ts
+++ b/scripts/model-sync/provider-supports.test.ts
@@ -82,45 +82,28 @@ describe('buildProviderSupportsBody', () => {
 })
 
 describe('buildAnthropicProviderOptionsType', () => {
-  it('uses adaptive-only thinking and no sampling when reasoning is mandatory', () => {
+  it('uses max_tokens and no sampling when sampling is not listed', () => {
     const type = buildAnthropicProviderOptionsType({
-      supportedParameters: [
-        'max_tokens',
-        'reasoning',
-        'tools',
-        'include_reasoning',
-        'reasoning_effort',
-      ],
-      reasoningMandatory: true,
+      supportedParameters: ['max_tokens', 'reasoning', 'tools'],
       hasCachedPricing: true,
     })
     expect(type).toContain('AnthropicCacheControlOptions')
-    expect(type).toContain('AnthropicAdaptiveOnlyThinkingOptions')
     expect(type).toContain('AnthropicMaxTokensOptions')
-    expect(type).toContain('AnthropicOutputConfigOptions')
     expect(type).not.toContain('AnthropicSamplingOptions')
-    expect(type).not.toContain('AnthropicThinkingOptions &')
-    expect(type).not.toContain('AnthropicAdaptiveThinkingOptions')
-    expect(type).not.toContain('AnthropicAdaptiveOrDisabledThinkingOptions')
   })
 
-  it('uses adaptive-or-disabled thinking when reasoning is listed without sampling', () => {
+  it('keeps sampling when temperature is listed', () => {
     const type = buildAnthropicProviderOptionsType({
-      supportedParameters: ['max_tokens', 'reasoning', 'stop'],
-      reasoningMandatory: false,
+      supportedParameters: ['temperature', 'top_p', 'top_k', 'max_tokens'],
     })
-    expect(type).toContain('AnthropicAdaptiveOrDisabledThinkingOptions')
-    expect(type).toContain('AnthropicMaxTokensOptions')
-    expect(type).not.toContain('AnthropicSamplingOptions')
+    expect(type).toContain('AnthropicSamplingOptions')
+    expect(type).not.toContain('AnthropicMaxTokensOptions')
   })
 
-  it('keeps sampling plus budget thinking when temperature is listed and reasoning is not', () => {
+  it('never emits thinking types: chat({ reasoning }) owns thinking', () => {
     const type = buildAnthropicProviderOptionsType({
-      supportedParameters: ['temperature', 'top_p', 'top_k', 'max_tokens'],
+      supportedParameters: ['max_tokens', 'reasoning', 'reasoning_effort'],
     })
-    expect(type).toContain('AnthropicThinkingOptions')
-    expect(type).toContain('AnthropicSamplingOptions')
-    expect(type).not.toContain('AnthropicMaxTokensOptions')
-    expect(type).not.toContain('AnthropicAdaptiveOnlyThinkingOptions')
+    expect(type).not.toMatch(/Thinking|OutputConfig|Effort/)
   })
 })
diff --git a/scripts/model-sync/provider-supports.ts b/scripts/model-sync/provider-supports.ts
index a1e8a478c1..1f1fbee733 100644
--- a/scripts/model-sync/provider-supports.ts
+++ b/scripts/model-sync/provider-supports.ts
@@ -64,7 +64,6 @@ function quoteList(values: Array<string>): string {
 
 interface AnthropicProviderOptionsInput {
   supportedParameters?: Array<string>
-  reasoningMandatory?: boolean
   hasCachedPricing?: boolean
 }
 
@@ -78,50 +77,28 @@ const ANTHROPIC_BASE_OPTIONS = [
 
 /**
  * Per-model Anthropic provider-options intersection, inferred from the
- * OpenRouter catalog. Does not copy another model's tool list.
+ * OpenRouter catalog. Does not copy another model's tool list. Thinking is
+ * not here: `chat({ reasoning })` sets it, with the levels that
+ * `sync-model-reasoning.ts` writes to `model-reasoning.ts`.
  *
- * - `reasoning.mandatory` → adaptive-only thinking (Fable 5 / 5.1).
- * - reasoning params without sampling → adaptive-or-disabled (Sonnet 5,
- *   Opus 4.7+).
- * - reasoning + sampling → adaptive union plus sampling (Opus/Sonnet 4.6).
- * - no reasoning → budget-based thinking plus sampling when listed.
+ * - sampling listed → sampling options.
+ * - no sampling (Sonnet 5, Opus 4.7+, Fable 5) → `max_tokens` only.
  */
 export function buildAnthropicProviderOptionsType(
   input: AnthropicProviderOptionsInput,
 ): string {
   const params = input.supportedParameters ?? []
   const hasSampling = hasParam(params, ['temperature', 'top_p', 'top_k'])
-  const hasReasoning = hasParam(params, [
-    'include_reasoning',
-    'reasoning',
-    'reasoning_effort',
-  ])
 
   const parts: Array<string> = [...ANTHROPIC_BASE_OPTIONS]
   if (input.hasCachedPricing) {
     parts.unshift('AnthropicCacheControlOptions')
   }
 
-  if (input.reasoningMandatory) {
-    parts.push('AnthropicAdaptiveOnlyThinkingOptions')
-  } else if (hasReasoning && hasSampling) {
-    parts.push('AnthropicAdaptiveThinkingOptions')
-  } else if (hasReasoning) {
-    parts.push('AnthropicAdaptiveOrDisabledThinkingOptions')
-  } else {
-    parts.push('AnthropicThinkingOptions')
-  }
-
   parts.push('AnthropicToolChoiceOptions')
-
-  if (hasSampling) {
-    parts.push('AnthropicSamplingOptions')
-  } else {
-    parts.push('AnthropicMaxTokensOptions')
-    if (hasReasoning || input.reasoningMandatory) {
-      parts.push('AnthropicOutputConfigOptions')
-    }
-  }
+  parts.push(
+    hasSampling ? 'AnthropicSamplingOptions' : 'AnthropicMaxTokensOptions',
+  )
 
   return parts.join(' & ')
 }
diff --git a/scripts/sync-provider-models.ts b/scripts/sync-provider-models.ts
index c97dc1e14d..c38b0e6652 100644
--- a/scripts/sync-provider-models.ts
+++ b/scripts/sync-provider-models.ts
@@ -155,9 +155,9 @@ const PROVIDER_MAP: Record<string, ProviderConfig> = {
     validInputModalities: ['text', 'image', 'audio', 'video', 'document'],
     kind: 'anthropic',
     referenceSatisfies:
-      'ModelMeta<AnthropicContainerOptions & AnthropicContextManagementOptions & AnthropicMCPOptions & AnthropicServiceTierOptions & AnthropicStopSequencesOptions & AnthropicThinkingOptions & AnthropicToolChoiceOptions & AnthropicSamplingOptions>',
+      'ModelMeta<AnthropicContainerOptions & AnthropicContextManagementOptions & AnthropicMCPOptions & AnthropicServiceTierOptions & AnthropicStopSequencesOptions & AnthropicToolChoiceOptions & AnthropicSamplingOptions>',
     referenceProviderOptionsEntry:
-      'AnthropicContainerOptions & AnthropicContextManagementOptions & AnthropicMCPOptions & AnthropicServiceTierOptions & AnthropicStopSequencesOptions & AnthropicThinkingOptions & AnthropicToolChoiceOptions & AnthropicSamplingOptions',
+      'AnthropicContainerOptions & AnthropicContextManagementOptions & AnthropicMCPOptions & AnthropicServiceTierOptions & AnthropicStopSequencesOptions & AnthropicToolChoiceOptions & AnthropicSamplingOptions',
     hasBothNameAndId: true,
     providerOptionsIsMappedType: false,
     skipPatterns: [],
@@ -251,7 +251,6 @@ function convertPrice(priceStr: string | undefined): number {
 function anthropicOptionsType(model: OpenRouterModel): string {
   return buildAnthropicProviderOptionsType({
     supportedParameters: model.supported_parameters,
-    reasoningMandatory: model.reasoning?.mandatory === true,
     hasCachedPricing: convertPrice(model.pricing.input_cache_read) > 0,
   })
 }

From dcf6f7e73fd8872e234d750aed093befe26e0c22 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 14:32:01 +0200
Subject: [PATCH 089/286] feat(ai-gemini)!: map chat({ reasoning }) to Gemini
 thinking

`thinkingConfig` leaves the chat modelOptions, and GeminiThinkingOptions
is removed. The adapter reads the generated model-reasoning map:

- Gemini 3 models: `thinkingLevel` from the level
- Gemini 2.5 models: `thinkingBudget` from `budgetTokens`, or pi's
  per-model table
- `off`: `thinkingBudget: 0`
- `summary` sets `includeThoughts`

The experimental Interactions adapter takes `reasoning` too, and sends
`thinking_level` and `thinking_summaries`. Image generation keeps its
own `thinkingConfig`.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-gemini/src/adapters/text.ts       |  46 +++----
 .../experimental/text-interactions/adapter.ts |  48 +++----
 packages/ai-gemini/src/index.ts               |   5 +-
 packages/ai-gemini/src/model-meta.ts          |  91 +++++--------
 packages/ai-gemini/src/text/reasoning.ts      |  68 ++++++++++
 .../src/text/text-provider-options.ts         |  35 -----
 .../tests/chat-per-model-type-safety.test.ts  |  84 +++++++-----
 .../ai-gemini/tests/gemini-adapter.test.ts    |  17 +--
 packages/ai-gemini/tests/model-meta.test.ts   | 114 ++++++++--------
 .../ai-gemini/tests/reasoning-request.test.ts | 122 ++++++++++++++++++
 scripts/sync-provider-models.ts               |   4 +-
 11 files changed, 380 insertions(+), 254 deletions(-)
 create mode 100644 packages/ai-gemini/src/text/reasoning.ts
 create mode 100644 packages/ai-gemini/tests/reasoning-request.test.ts

diff --git a/packages/ai-gemini/src/adapters/text.ts b/packages/ai-gemini/src/adapters/text.ts
index 28ffc9c3cb..bb10caf19b 100644
--- a/packages/ai-gemini/src/adapters/text.ts
+++ b/packages/ai-gemini/src/adapters/text.ts
@@ -9,6 +9,9 @@ import { toRunErrorRawEvent } from '@tanstack/ai/adapter-internals'
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
 import { convertToolsToProviderFormat } from '../tools/tool-converter'
 import { buildGeminiUsage } from '../usage'
+import { geminiThinkingConfig } from '../text/reasoning'
+import { GEMINI_MODEL_REASONING } from '../model-reasoning'
+import type { GeminiModelReasoningByName } from '../model-reasoning'
 import {
   createGeminiClient,
   generateId,
@@ -36,7 +39,6 @@ import type {
   GoogleGenAI,
   GroundingMetadata,
   Part,
-  ThinkingLevel,
   VideoMetadata,
 } from '@google/genai'
 import type {
@@ -217,6 +219,12 @@ type ResolveInputModalities<TModel extends string> =
  * Resolve tool capabilities for a specific model.
  * If the model has explicit tools in the map, use those; otherwise use empty tuple.
  */
+/** The reasoning levels of a model, for `chat({ reasoning })`. `never`: none. */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof GeminiModelReasoningByName
+    ? GeminiModelReasoningByName[TModel]
+    : never
+
 type ResolveToolCapabilities<TModel extends string> =
   TModel extends keyof GeminiChatModelToolCapabilitiesByName
     ? NonNullable<GeminiChatModelToolCapabilitiesByName[TModel]>
@@ -245,7 +253,9 @@ export class GeminiTextAdapter<
   TInputModalities,
   GeminiMessageMetadataByModality,
   TToolCapabilities,
-  GeminiToolCallMetadata
+  GeminiToolCallMetadata,
+  never,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   readonly name = 'gemini' as const
@@ -1254,31 +1264,13 @@ export class GeminiTextAdapter<
   private mapCommonOptionsToGemini(
     options: TextOptions<GeminiTextProviderOptions>,
   ) {
-    // Separate `thinkingConfig` from the other model options so the loose
-    // local `thinkingLevel?: keyof typeof ThinkingLevel` type doesn't leak
-    // into the SDK config object via the `...modelOpts` spread — we re-add a
-    // properly-typed `ThinkingConfig` below.
-    const { thinkingConfig, ...modelOpts } = options.modelOptions ?? {}
-    // Build the thinkingConfig payload only when the caller actually supplied
-    // one. Our local `thinkingLevel` is typed as `keyof typeof ThinkingLevel`
-    // (string union) so users can pass plain strings; the SDK target is the
-    // `ThinkingLevel` enum, and every field is `field?: T` under EOPT — so we
-    // re-emit fields via conditional spreads.
-    const mappedThinkingConfig = thinkingConfig
-      ? {
-          ...(thinkingConfig.includeThoughts !== undefined && {
-            includeThoughts: thinkingConfig.includeThoughts,
-          }),
-          ...(thinkingConfig.thinkingBudget !== undefined && {
-            thinkingBudget: thinkingConfig.thinkingBudget,
-          }),
-          ...(thinkingConfig.thinkingLevel
-            ? {
-                thinkingLevel: thinkingConfig.thinkingLevel as ThinkingLevel,
-              }
-            : {}),
-        }
-      : undefined
+    const modelOpts = options.modelOptions ?? {}
+    // `chat({ reasoning })`, as this model's thinking config.
+    const mappedThinkingConfig = geminiThinkingConfig(
+      options.model,
+      options.reasoning,
+      GEMINI_MODEL_REASONING[options.model],
+    )
 
     const normalizedPrompts = normalizeSystemPrompts(options.systemPrompts)
     const systemInstruction =
diff --git a/packages/ai-gemini/src/experimental/text-interactions/adapter.ts b/packages/ai-gemini/src/experimental/text-interactions/adapter.ts
index 4323868829..09bf491c1e 100644
--- a/packages/ai-gemini/src/experimental/text-interactions/adapter.ts
+++ b/packages/ai-gemini/src/experimental/text-interactions/adapter.ts
@@ -11,9 +11,11 @@ import {
   getGeminiProviderToolMetadata,
 } from '../../tools/gemini-provider-tool'
 import { assertUniqueToolNames } from '@tanstack/ai/adapter-internals'
+import { interactionsThinking } from '../../text/reasoning'
+import { GEMINI_MODEL_REASONING } from '../../model-reasoning'
+import type { GeminiModelReasoningByName } from '../../model-reasoning'
 import type { InternalLogger } from '@tanstack/ai/adapter-internals'
 import type {
-  GeminiChatModelProviderOptionsByName,
   GeminiChatModelToolCapabilitiesByName,
   GeminiModelInputModalitiesByName,
   GeminiModels,
@@ -105,32 +107,25 @@ type ToolCallState = {
 // ===========================
 
 /**
- * Resolve provider options for a specific model. Reuses the chat-model
- * options map from `model-meta.ts` so a model's allowed thinking levels are
- * declared once: the Interactions API takes the same levels as
- * `generateContent` but lowercased (`low`, not `LOW`). Models whose chat
- * options carry no `thinkingConfig` resolve to `never`, so `thinking_level`
- * can't be set on them. Everything else falls through to the flat SDK shape.
+ * Resolve provider options for a specific model. Thinking is not here:
+ * `chat({ reasoning })` sets `thinking_level` and `thinking_summaries`.
  */
-type InteractionsThinkingLevel<TModel> =
-  TModel extends keyof GeminiChatModelProviderOptionsByName
-    ? GeminiChatModelProviderOptionsByName[TModel] extends {
-        thinkingConfig?: { thinkingLevel?: infer L extends string }
-      }
-      ? Lowercase<L>
-      : never
-    : never
-
-type ResolveProviderOptions<TModel extends GeminiModels> = Omit<
+type ResolveProviderOptions = Omit<
   GeminiTextInteractionsProviderOptions,
   'generation_config'
 > & {
   generation_config?: Omit<
     NonNullable<GeminiTextInteractionsProviderOptions['generation_config']>,
-    'thinking_level'
-  > & { thinking_level?: InteractionsThinkingLevel<TModel> }
+    'thinking_level' | 'thinking_summaries'
+  >
 }
 
+/** The reasoning levels of a model, for `chat({ reasoning })`. `never`: none. */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof GeminiModelReasoningByName
+    ? GeminiModelReasoningByName[TModel]
+    : never
+
 /**
  * Resolve input modalities for a specific model. Reuses the chat-model
  * modality map from `model-meta.ts`: passing a `document` content block
@@ -186,7 +181,7 @@ type ResolveToolCapabilities<TModel extends string> =
  */
 export class GeminiTextInteractionsAdapter<
   TModel extends GeminiModels,
-  TProviderOptions extends Record<string, any> = ResolveProviderOptions<TModel>,
+  TProviderOptions extends Record<string, any> = ResolveProviderOptions,
   TInputModalities extends ReadonlyArray<Modality> =
     ResolveInputModalities<TModel>,
   TToolCapabilities extends ReadonlyArray<string> =
@@ -196,7 +191,10 @@ export class GeminiTextInteractionsAdapter<
   TProviderOptions,
   TInputModalities,
   GeminiMessageMetadataByModality,
-  TToolCapabilities
+  TToolCapabilities,
+  unknown,
+  never,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   override readonly name = 'gemini-text-interactions' as const
@@ -632,7 +630,7 @@ export function createGeminiTextInteractions<TModel extends GeminiModels>(
   config?: Omit<GeminiTextInteractionsConfig, 'apiKey'>,
 ): GeminiTextInteractionsAdapter<
   TModel,
-  ResolveProviderOptions<TModel>,
+  ResolveProviderOptions,
   ResolveInputModalities<TModel>,
   ResolveToolCapabilities<TModel>
 > {
@@ -645,7 +643,7 @@ export function geminiTextInteractions<TModel extends GeminiModels>(
   config?: Omit<GeminiTextInteractionsConfig, 'apiKey'>,
 ): GeminiTextInteractionsAdapter<
   TModel,
-  ResolveProviderOptions<TModel>,
+  ResolveProviderOptions,
   ResolveInputModalities<TModel>,
   ResolveToolCapabilities<TModel>
 > {
@@ -663,6 +661,10 @@ function buildInteractionsRequest(
 
   const generationConfig: Interactions.GenerationConfig = {
     ...modelOpts?.generation_config,
+    ...interactionsThinking(
+      options.reasoning,
+      GEMINI_MODEL_REASONING[options.model],
+    ),
   }
 
   const hasGenerationConfig = Object.keys(generationConfig).length > 0
diff --git a/packages/ai-gemini/src/index.ts b/packages/ai-gemini/src/index.ts
index 2c246e90ba..11f8f7a151 100644
--- a/packages/ai-gemini/src/index.ts
+++ b/packages/ai-gemini/src/index.ts
@@ -174,10 +174,7 @@ export type {
   GeminiEmbeddingModelProviderOptionsByName,
   GeminiEmbeddingModelInputModalitiesByName,
 } from './model-meta'
-export type {
-  GeminiStructuredOutputOptions,
-  GeminiThinkingOptions,
-} from './text/text-provider-options'
+export type { GeminiStructuredOutputOptions } from './text/text-provider-options'
 export type { GoogleGeminiTool } from './tools/index'
 export type {
   GeminiTextMetadata,
diff --git a/packages/ai-gemini/src/model-meta.ts b/packages/ai-gemini/src/model-meta.ts
index 6a673c8049..07ef8e3c6e 100644
--- a/packages/ai-gemini/src/model-meta.ts
+++ b/packages/ai-gemini/src/model-meta.ts
@@ -4,7 +4,6 @@ import type {
   GeminiCommonConfigOptions,
   GeminiSafetyOptions,
   GeminiStructuredOutputOptions,
-  GeminiThinkingOptions,
   GeminiToolConfigOptions,
 } from './text/text-provider-options'
 import type { GeminiEmbeddingProviderOptions } from './embedding/embedding-provider-options'
@@ -82,8 +81,7 @@ const GEMINI_3_1_PRO = {
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
 >
 
 const GEMINI_3_FLASH = {
@@ -116,8 +114,7 @@ const GEMINI_3_FLASH = {
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
 >
 
 /**
@@ -149,8 +146,7 @@ const GEMINI_3_PRO_IMAGE = {
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
 >
 
 /**
@@ -183,8 +179,7 @@ const GEMINI_3_PRO_IMAGE_PREVIEW = {
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
 >
 
 /**
@@ -216,8 +211,7 @@ const GEMINI_3_1_FLASH_IMAGE = {
   GeminiToolConfigOptions &
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
-    GeminiCachedContentOptions &
-    GeminiThinkingOptions
+    GeminiCachedContentOptions
 >
 
 /**
@@ -250,8 +244,7 @@ const GEMINI_3_1_FLASH_IMAGE_PREVIEW = {
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
 >
 
 /**
@@ -282,8 +275,7 @@ const GEMINI_3_1_FLASH_LITE_IMAGE = {
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
 >
 
 const GEMINI_3_1_FLASH_LITE = {
@@ -316,8 +308,7 @@ const GEMINI_3_1_FLASH_LITE = {
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
 >
 
 const GEMINI_3_1_FLASH_LITE_PREVIEW = {
@@ -350,8 +341,7 @@ const GEMINI_3_1_FLASH_LITE_PREVIEW = {
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
 >
 
 const GEMINI_2_5_PRO = {
@@ -390,8 +380,7 @@ const GEMINI_2_5_PRO = {
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
 >
 
 const GEMINI_2_5_PRO_TTS = {
@@ -455,8 +444,7 @@ const GEMINI_2_5_FLASH = {
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
 >
 
 /**
@@ -526,8 +514,7 @@ const GEMINI_2_5_FLASH_LIVE = {
   GeminiToolConfigOptions &
   GeminiSafetyOptions &
   GeminiGenerationConfigOptions &
-  GeminiCachedContentOptions &
-  GeminiThinkingOptions
+  GeminiCachedContentOptions
 >
 */
 const GEMINI_2_5_FLASH_TTS = {
@@ -661,8 +648,7 @@ const GEMINI_2_5_FLASH_LITE = {
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
 >
 
 const IMAGEN_4_GENERATE = {
@@ -911,8 +897,7 @@ const GEMINI_3_8_FLASH = {
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions<'LOW' | 'MEDIUM' | 'HIGH'>
+    GeminiStructuredOutputOptions
 >
 
 const GEMINI_3_7_FLASH = {
@@ -956,8 +941,7 @@ const GEMINI_3_7_FLASH = {
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
 >
 
 const GEMINI_3_6_FLASH = {
@@ -999,8 +983,7 @@ const GEMINI_3_6_FLASH = {
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
 >
 
 const GEMINI_3_5_FLASH = {
@@ -1040,8 +1023,7 @@ const GEMINI_3_5_FLASH = {
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
 >
 
 const GEMINI_3_5_FLASH_LITE = {
@@ -1082,8 +1064,7 @@ const GEMINI_3_5_FLASH_LITE = {
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
 >
 
 export const GEMINI_MODELS = [
@@ -1271,74 +1252,62 @@ export type GeminiChatModelProviderOptionsByName = {
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions<'LOW' | 'MEDIUM' | 'HIGH'>
+    GeminiStructuredOutputOptions
   [GEMINI_3_7_FLASH.name]: GeminiToolConfigOptions &
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
   [GEMINI_3_6_FLASH.name]: GeminiToolConfigOptions &
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
   [GEMINI_3_5_FLASH.name]: GeminiToolConfigOptions &
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
   [GEMINI_3_5_FLASH_LITE.name]: GeminiToolConfigOptions &
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
   [GEMINI_3_1_PRO.name]: GeminiToolConfigOptions &
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
   [GEMINI_3_FLASH.name]: GeminiToolConfigOptions &
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
   [GEMINI_3_1_FLASH_LITE.name]: GeminiToolConfigOptions &
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
   [GEMINI_3_1_FLASH_LITE_PREVIEW.name]: GeminiToolConfigOptions &
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
   [GEMINI_2_5_PRO.name]: GeminiToolConfigOptions &
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
   [GEMINI_2_5_FLASH.name]: GeminiToolConfigOptions &
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
   [GEMINI_2_5_FLASH_LITE.name]: GeminiToolConfigOptions &
     GeminiSafetyOptions &
     GeminiCommonConfigOptions &
     GeminiCachedContentOptions &
-    GeminiStructuredOutputOptions &
-    GeminiThinkingOptions
+    GeminiStructuredOutputOptions
 }
 
 /**
diff --git a/packages/ai-gemini/src/text/reasoning.ts b/packages/ai-gemini/src/text/reasoning.ts
new file mode 100644
index 0000000000..fdf7d6a82b
--- /dev/null
+++ b/packages/ai-gemini/src/text/reasoning.ts
@@ -0,0 +1,68 @@
+import { resolveReasoning } from '@tanstack/ai/adapter-internals'
+import type { ThinkingConfig, ThinkingLevel } from '@google/genai'
+import type { ModelReasoning, ReasoningRequest } from '@tanstack/ai'
+
+/**
+ * pi's thinking budgets for the Gemini 2.5 models. `-1` asks Gemini for a
+ * dynamic budget.
+ */
+function budgetFor(model: string, level: string): number {
+  const high = model.includes('2.5-pro')
+    ? 32768
+    : model.includes('2.5-flash')
+      ? 24576
+      : undefined
+  if (high === undefined) return -1
+  const minimal = model.includes('2.5-flash-lite') ? 512 : 128
+  const budgets: Record<string, number> = {
+    minimal,
+    low: 2048,
+    medium: 8192,
+    high,
+  }
+  return budgets[level] ?? high
+}
+
+/**
+ * The `thinkingConfig` for `chat({ reasoning })`:
+ * - `off`: a zero thinking budget. A model that cannot stop thinking never
+ *   gets here, because the clamp moves `off` to its lowest level.
+ * - a model with effort levels (Gemini 3): `thinkingLevel`.
+ * - a budget model (Gemini 2.5): `thinkingBudget`, from `budgetTokens` or
+ *   pi's table.
+ * `summary` turns `includeThoughts` on.
+ */
+export function geminiThinkingConfig(
+  model: string,
+  request: ReasoningRequest | undefined,
+  reasoning: ModelReasoning | undefined,
+): ThinkingConfig | undefined {
+  const resolved = resolveReasoning(request, reasoning)
+  if (!resolved || !reasoning) return undefined
+  if (resolved.level === 'off') return { thinkingBudget: 0 }
+  const includeThoughts = resolved.summary
+  if (!reasoning.budget && resolved.value !== null) {
+    return {
+      includeThoughts,
+      // The map values are the lowercase names of the SDK enum values.
+      thinkingLevel: resolved.value.toUpperCase() as ThinkingLevel,
+    }
+  }
+  return {
+    includeThoughts,
+    thinkingBudget: resolved.budgetTokens ?? budgetFor(model, resolved.level),
+  }
+}
+
+/** The Interactions API thinking fields for `chat({ reasoning })`. */
+export function interactionsThinking(
+  request: ReasoningRequest | undefined,
+  reasoning: ModelReasoning | undefined,
+): { thinking_level?: string; thinking_summaries?: 'auto' | 'none' } {
+  const resolved = resolveReasoning(request, reasoning)
+  if (!resolved || resolved.level === 'off') return {}
+  return {
+    thinking_level: resolved.value ?? resolved.level,
+    thinking_summaries: resolved.summary ? 'auto' : 'none',
+  }
+}
diff --git a/packages/ai-gemini/src/text/text-provider-options.ts b/packages/ai-gemini/src/text/text-provider-options.ts
index ac62b7e73c..a84a07ea26 100644
--- a/packages/ai-gemini/src/text/text-provider-options.ts
+++ b/packages/ai-gemini/src/text/text-provider-options.ts
@@ -2,7 +2,6 @@ import type {
   MediaResolution,
   SafetySetting,
   Schema,
-  ThinkingLevel,
   ToolConfig,
 } from '@google/genai'
 
@@ -222,42 +221,8 @@ Cyclic references are unrolled to a limited degree and, as such, may only be use
   responseJsonSchema?: Schema
 }
 
-export interface GeminiThinkingOptions<
-  TThinkingLevel extends keyof typeof ThinkingLevel =
-    keyof typeof ThinkingLevel,
-> {
-  /**
-   * Config for thinking features. An error will be returned if this field is
-   * set for models that don't support thinking.
-   *
-   * All fields are optional so the same shape can be used for both budget-based
-   * thinking (Gemini 2.x: `includeThoughts` + `thinkingBudget`) and the newer
-   * level-based thinking (Gemini 3.x: `thinkingLevel`). The adapter reads
-   * whichever fields are present at runtime.
-   */
-  thinkingConfig?: {
-    /**
-     * Indicates whether to include thoughts in the response. If true, thoughts
-     * are returned only when available.
-     */
-    includeThoughts?: boolean
-
-    /**
-     * The number of thoughts tokens that the model should generate.
-     */
-    thinkingBudget?: number
-
-    /**
-     * The level of thoughts tokens that the model should generate
-     * (Gemini 3.x and later).
-     */
-    thinkingLevel?: TThinkingLevel
-  }
-}
-
 export type ExternalTextProviderOptions = GeminiToolConfigOptions &
   GeminiSafetyOptions &
   GeminiCommonConfigOptions &
   GeminiCachedContentOptions &
-  GeminiThinkingOptions &
   GeminiStructuredOutputOptions
diff --git a/packages/ai-gemini/tests/chat-per-model-type-safety.test.ts b/packages/ai-gemini/tests/chat-per-model-type-safety.test.ts
index 4ec94085a2..0e9e05d39d 100644
--- a/packages/ai-gemini/tests/chat-per-model-type-safety.test.ts
+++ b/packages/ai-gemini/tests/chat-per-model-type-safety.test.ts
@@ -33,41 +33,34 @@ describe('Gemini per-model chat modelOptions gating', () => {
           responseLogprobs: false,
           cachedContent: 'cachedContents/abc',
           responseMimeType: 'application/json',
-          thinkingConfig: {
-            includeThoughts: true,
-            thinkingBudget: 1024,
-          },
         },
       })
     })
 
-    it('rejects unknown options', () => {
+    it('rejects thinkingConfig in modelOptions (chat({ reasoning }) owns it)', () => {
       chat({
         adapter: geminiText('gemini-3.1-pro-preview'),
         messages: [{ role: 'user', content: 'hi' }],
         modelOptions: {
-          // @ts-expect-error - 'unknownOption' does not exist
-          unknownOption: true,
+          // @ts-expect-error - thinking is set with `reasoning`
+          thinkingConfig: { includeThoughts: true },
         },
       })
     })
-  })
 
-  describe('gemini-3.1-flash-lite-preview — thinking (basic) + structured output, NO advanced thinking', () => {
-    it('accepts basic thinkingConfig (includeThoughts + thinkingBudget)', () => {
+    it('rejects unknown options', () => {
       chat({
-        adapter: geminiText('gemini-3.1-flash-lite-preview'),
+        adapter: geminiText('gemini-3.1-pro-preview'),
         messages: [{ role: 'user', content: 'hi' }],
         modelOptions: {
-          thinkingConfig: {
-            includeThoughts: true,
-            thinkingBudget: 512,
-          },
-          responseMimeType: 'application/json',
+          // @ts-expect-error - 'unknownOption' does not exist
+          unknownOption: true,
         },
       })
     })
+  })
 
+  describe('gemini-3.1-flash-lite-preview — structured output', () => {
     it('accepts structured-output schema', () => {
       chat({
         adapter: geminiText('gemini-3.1-flash-lite-preview'),
@@ -79,8 +72,8 @@ describe('Gemini per-model chat modelOptions gating', () => {
     })
   })
 
-  describe('gemini-3.1-flash-lite — stable id, thinking + structured output', () => {
-    it('accepts base + thinking + structured-output options', () => {
+  describe('gemini-3.1-flash-lite — stable id, structured output', () => {
+    it('accepts base + structured-output options', () => {
       chat({
         adapter: geminiText('gemini-3.1-flash-lite'),
         messages: [{ role: 'user', content: 'hi' }],
@@ -89,10 +82,6 @@ describe('Gemini per-model chat modelOptions gating', () => {
           topK: 5,
           cachedContent: 'cachedContents/abc',
           responseMimeType: 'application/json',
-          thinkingConfig: {
-            includeThoughts: true,
-            thinkingBudget: 512,
-          },
         },
       })
     })
@@ -111,6 +100,41 @@ describe('Gemini per-model chat modelOptions gating', () => {
     })
   })
 
+  describe('reasoning gating', () => {
+    it('Gemini 3 models take their thinking levels, with no budget', () => {
+      chat({
+        adapter: geminiText('gemini-3.1-pro-preview'),
+        messages: [{ role: 'user', content: 'hi' }],
+        reasoning: 'high',
+      })
+      chat({
+        adapter: geminiText('gemini-3.1-pro-preview'),
+        messages: [{ role: 'user', content: 'hi' }],
+        // @ts-expect-error - gemini-3.1-pro-preview has no minimal level
+        reasoning: 'minimal',
+      })
+      chat({
+        adapter: geminiText('gemini-3.1-pro-preview'),
+        messages: [{ role: 'user', content: 'hi' }],
+        // @ts-expect-error - gemini-3.1-pro-preview takes no token budget
+        reasoning: { level: 'low', budgetTokens: 1024 },
+      })
+    })
+
+    it('Gemini 2.5 models take off and a token budget', () => {
+      chat({
+        adapter: geminiText('gemini-2.5-pro'),
+        messages: [{ role: 'user', content: 'hi' }],
+        reasoning: { level: 'medium', budgetTokens: 4096 },
+      })
+      chat({
+        adapter: geminiText('gemini-2.5-flash'),
+        messages: [{ role: 'user', content: 'hi' }],
+        reasoning: 'off',
+      })
+    })
+  })
+
   describe('Model name type safety', () => {
     it('rejects unknown model names at the factory', () => {
       // @ts-expect-error - 'gemini-fake-9000' is not a valid Gemini chat model
@@ -129,12 +153,12 @@ describe('Gemini per-model chat modelOptions gating', () => {
 })
 
 describe('Gemini provider options shape assertions', () => {
-  describe('gemini-3.1-pro-preview — full feature set with thinking', () => {
+  describe('gemini-3.1-pro-preview — full feature set', () => {
     type Options =
       GeminiChatModelProviderOptionsByName['gemini-3.1-pro-preview']
 
-    it('has thinkingConfig', () => {
-      expectTypeOf<Options>().toHaveProperty('thinkingConfig')
+    it('has no thinkingConfig', () => {
+      expectTypeOf<Options>().not.toHaveProperty('thinkingConfig')
     })
     it('has responseMimeType (structured output)', () => {
       expectTypeOf<Options>().toHaveProperty('responseMimeType')
@@ -153,12 +177,12 @@ describe('Gemini provider options shape assertions', () => {
     })
   })
 
-  describe('gemini-3.1-flash-lite-preview — basic thinking only', () => {
+  describe('gemini-3.1-flash-lite-preview — structured output', () => {
     type Options =
       GeminiChatModelProviderOptionsByName['gemini-3.1-flash-lite-preview']
 
-    it('has thinkingConfig', () => {
-      expectTypeOf<Options>().toHaveProperty('thinkingConfig')
+    it('has no thinkingConfig', () => {
+      expectTypeOf<Options>().not.toHaveProperty('thinkingConfig')
     })
     it('has responseMimeType', () => {
       expectTypeOf<Options>().toHaveProperty('responseMimeType')
@@ -168,8 +192,8 @@ describe('Gemini provider options shape assertions', () => {
   describe('gemini-3.1-flash-lite — stable id mirrors the preview feature set', () => {
     type Options = GeminiChatModelProviderOptionsByName['gemini-3.1-flash-lite']
 
-    it('has thinkingConfig', () => {
-      expectTypeOf<Options>().toHaveProperty('thinkingConfig')
+    it('has no thinkingConfig', () => {
+      expectTypeOf<Options>().not.toHaveProperty('thinkingConfig')
     })
     it('has responseMimeType (structured output)', () => {
       expectTypeOf<Options>().toHaveProperty('responseMimeType')
diff --git a/packages/ai-gemini/tests/gemini-adapter.test.ts b/packages/ai-gemini/tests/gemini-adapter.test.ts
index 3cebcec628..e687b76f3b 100644
--- a/packages/ai-gemini/tests/gemini-adapter.test.ts
+++ b/packages/ai-gemini/tests/gemini-adapter.test.ts
@@ -374,10 +374,6 @@ describe('GeminiAdapter through AI', () => {
           },
         },
       },
-      thinkingConfig: {
-        includeThoughts: true,
-        thinkingBudget: 128,
-      },
       imageConfig: {
         aspectRatio: '1:1',
       },
@@ -392,6 +388,7 @@ describe('GeminiAdapter through AI', () => {
       messages: [{ role: 'user', content: 'Provide structured response' }],
       systemPrompts: ['Stay concise', 'Return JSON'],
       modelOptions: providerOptions,
+      reasoning: { level: 'minimal', budgetTokens: 128 },
     })) {
       /* consume stream */
     }
@@ -425,7 +422,10 @@ describe('GeminiAdapter through AI', () => {
       providerOptions?.enableEnhancedCivicAnswers,
     )
     expect(config.speechConfig).toEqual(providerOptions?.speechConfig)
-    expect(config.thinkingConfig).toEqual(providerOptions?.thinkingConfig)
+    expect(config.thinkingConfig).toEqual({
+      includeThoughts: true,
+      thinkingBudget: 128,
+    })
     expect(config.imageConfig).toEqual(providerOptions?.imageConfig)
   })
 
@@ -1088,12 +1088,7 @@ describe('GeminiAdapter through AI', () => {
       adapter,
       tools: [sumTool],
       messages: [{ role: 'user', content: 'What is 1 + 2 + 5?' }],
-      modelOptions: {
-        thinkingConfig: {
-          includeThoughts: true,
-          thinkingLevel: 'LOW',
-        },
-      },
+      reasoning: 'low',
     })) {
       /* consume stream */
     }
diff --git a/packages/ai-gemini/tests/model-meta.test.ts b/packages/ai-gemini/tests/model-meta.test.ts
index 853adae671..0c69b6355a 100644
--- a/packages/ai-gemini/tests/model-meta.test.ts
+++ b/packages/ai-gemini/tests/model-meta.test.ts
@@ -7,7 +7,6 @@ import type {
   GeminiModelInputModalitiesByName,
 } from '../src/model-meta'
 import type {
-  GeminiThinkingOptions,
   GeminiStructuredOutputOptions,
   GeminiToolConfigOptions,
   GeminiSafetyOptions,
@@ -15,7 +14,7 @@ import type {
   GeminiCachedContentOptions,
 } from '../src/text/text-provider-options'
 import type { GeminiMessageMetadataByModality } from '../src/message-types'
-import type { InferTextProviderOptions } from '@tanstack/ai/adapters'
+import type { AdapterReasoning } from '@tanstack/ai'
 import type {
   AudioPart,
   ConstrainedModelMessage,
@@ -38,7 +37,8 @@ type MakeInputModalitiesTypes<TModalities extends ReadonlyArray<Modality>> = {
  * Type assertion tests for Gemini model provider options.
  *
  * These tests verify that:
- * 1. Models with thinking support have GeminiThinkingOptions in their provider options
+ * 1. No model takes thinkingConfig in modelOptions: `chat({ reasoning })` owns
+ *    it, with the levels from the generated reasoning map
  * 2. Models with structured output support have GeminiStructuredOutputOptions
  * 3. All models have base options (tool config, safety, generation config, cached content)
  *
@@ -60,11 +60,7 @@ describe('Gemini Model Provider Options Type Assertions', () => {
     expect(adapter.supportsCombinedToolsAndSchema()).toBe(true)
     expectTypeOf<
       GeminiChatModelProviderOptionsByName['gemini-3.8-flash']
-    >().toEqualTypeOf<
-      BaseOptions &
-        GeminiThinkingOptions<'LOW' | 'MEDIUM' | 'HIGH'> &
-        GeminiStructuredOutputOptions
-    >()
+    >().toEqualTypeOf<BaseOptions & GeminiStructuredOutputOptions>()
     expectTypeOf<
       GeminiModelInputModalitiesByName['gemini-3.8-flash'][number]
     >().toEqualTypeOf<'text' | 'image' | 'video' | 'audio' | 'document'>()
@@ -76,23 +72,21 @@ describe('Gemini Model Provider Options Type Assertions', () => {
       'gemini-3.8-flash',
       'test-key',
     )
-    type Options = InferTextProviderOptions<typeof adapter>
-    type InteractionsOptions = InferTextProviderOptions<typeof interactions>
-    expectTypeOf<
-      NonNullable<Options['thinkingConfig']>['thinkingLevel']
-    >().toEqualTypeOf<'LOW' | 'MEDIUM' | 'HIGH' | undefined>()
+    expectTypeOf<AdapterReasoning<typeof adapter>['levels']>().toEqualTypeOf<
+      'low' | 'medium' | 'high'
+    >()
     expectTypeOf<
-      NonNullable<InteractionsOptions['generation_config']>['thinking_level']
-    >().toEqualTypeOf<'low' | 'medium' | 'high' | undefined>()
+      AdapterReasoning<typeof interactions>['levels']
+    >().toEqualTypeOf<'low' | 'medium' | 'high'>()
   })
 
   describe('Models WITH thinking support', () => {
-    it('gemini-3.1-pro-preview should support thinking options', () => {
+    it('gemini-3.1-pro-preview should support its options', () => {
       type Model = 'gemini-3.1-pro-preview'
       type Options = GeminiChatModelProviderOptionsByName[Model]
 
-      // Should have thinking options
-      expectTypeOf<Options>().toExtend<GeminiThinkingOptions>()
+      // Thinking is set with `reasoning`, not modelOptions
+      expectTypeOf<Options>().not.toHaveProperty('thinkingConfig')
 
       // Should have structured output options
       expectTypeOf<Options>().toExtend<GeminiStructuredOutputOptions>()
@@ -109,12 +103,12 @@ describe('Gemini Model Provider Options Type Assertions', () => {
       expectTypeOf<Options>().toHaveProperty('responseSchema')
     })
 
-    it('gemini-3-flash-preview should support thinking options', () => {
+    it('gemini-3-flash-preview should support its options', () => {
       type Model = 'gemini-3-flash-preview'
       type Options = GeminiChatModelProviderOptionsByName[Model]
 
-      // Should have thinking options
-      expectTypeOf<Options>().toExtend<GeminiThinkingOptions>()
+      // Thinking is set with `reasoning`, not modelOptions
+      expectTypeOf<Options>().not.toHaveProperty('thinkingConfig')
 
       // Should have structured output options
       expectTypeOf<Options>().toExtend<GeminiStructuredOutputOptions>()
@@ -131,12 +125,12 @@ describe('Gemini Model Provider Options Type Assertions', () => {
       expectTypeOf<Options>().toHaveProperty('responseSchema')
     })
 
-    it('gemini-2.5-pro should support thinking options', () => {
+    it('gemini-2.5-pro should support its options', () => {
       type Model = 'gemini-2.5-pro'
       type Options = GeminiChatModelProviderOptionsByName[Model]
 
-      // Should have thinking options
-      expectTypeOf<Options>().toExtend<GeminiThinkingOptions>()
+      // Thinking is set with `reasoning`, not modelOptions
+      expectTypeOf<Options>().not.toHaveProperty('thinkingConfig')
 
       // Should have structured output options
       expectTypeOf<Options>().toExtend<GeminiStructuredOutputOptions>()
@@ -145,12 +139,12 @@ describe('Gemini Model Provider Options Type Assertions', () => {
       expectTypeOf<Options>().toExtend<BaseOptions>()
     })
 
-    it('gemini-2.5-flash should support thinking options', () => {
+    it('gemini-2.5-flash should support its options', () => {
       type Model = 'gemini-2.5-flash'
       type Options = GeminiChatModelProviderOptionsByName[Model]
 
-      // Should have thinking options
-      expectTypeOf<Options>().toExtend<GeminiThinkingOptions>()
+      // Thinking is set with `reasoning`, not modelOptions
+      expectTypeOf<Options>().not.toHaveProperty('thinkingConfig')
 
       // Should have structured output options
       expectTypeOf<Options>().toExtend<GeminiStructuredOutputOptions>()
@@ -159,12 +153,12 @@ describe('Gemini Model Provider Options Type Assertions', () => {
       expectTypeOf<Options>().toExtend<BaseOptions>()
     })
 
-    it('gemini-2.5-flash-lite should support thinking options', () => {
+    it('gemini-2.5-flash-lite should support its options', () => {
       type Model = 'gemini-2.5-flash-lite'
       type Options = GeminiChatModelProviderOptionsByName[Model]
 
-      // Should have thinking options
-      expectTypeOf<Options>().toExtend<GeminiThinkingOptions>()
+      // Thinking is set with `reasoning`, not modelOptions
+      expectTypeOf<Options>().not.toHaveProperty('thinkingConfig')
 
       // Should have structured output options
       expectTypeOf<Options>().toExtend<GeminiStructuredOutputOptions>()
@@ -173,12 +167,12 @@ describe('Gemini Model Provider Options Type Assertions', () => {
       expectTypeOf<Options>().toExtend<BaseOptions>()
     })
 
-    it('gemini-3.1-flash-lite should support thinking options', () => {
+    it('gemini-3.1-flash-lite should support its options', () => {
       type Model = 'gemini-3.1-flash-lite'
       type Options = GeminiChatModelProviderOptionsByName[Model]
 
-      // Should have thinking options
-      expectTypeOf<Options>().toExtend<GeminiThinkingOptions>()
+      // Thinking is set with `reasoning`, not modelOptions
+      expectTypeOf<Options>().not.toHaveProperty('thinkingConfig')
 
       // Should have structured output options
       expectTypeOf<Options>().toExtend<GeminiStructuredOutputOptions>()
@@ -195,12 +189,12 @@ describe('Gemini Model Provider Options Type Assertions', () => {
       expectTypeOf<Options>().toHaveProperty('responseSchema')
     })
 
-    it('gemini-3.1-flash-lite-preview should support thinking options', () => {
+    it('gemini-3.1-flash-lite-preview should support its options', () => {
       type Model = 'gemini-3.1-flash-lite-preview'
       type Options = GeminiChatModelProviderOptionsByName[Model]
 
-      // Should have thinking options
-      expectTypeOf<Options>().toExtend<GeminiThinkingOptions>()
+      // Thinking is set with `reasoning`, not modelOptions
+      expectTypeOf<Options>().not.toHaveProperty('thinkingConfig')
 
       // Should have structured output options
       expectTypeOf<Options>().toExtend<GeminiStructuredOutputOptions>()
@@ -217,12 +211,12 @@ describe('Gemini Model Provider Options Type Assertions', () => {
       expectTypeOf<Options>().toHaveProperty('responseSchema')
     })
 
-    it('gemini-3.5-flash should support thinking options', () => {
+    it('gemini-3.5-flash should support its options', () => {
       type Model = 'gemini-3.5-flash'
       type Options = GeminiChatModelProviderOptionsByName[Model]
 
-      // Should have thinking options
-      expectTypeOf<Options>().toExtend<GeminiThinkingOptions>()
+      // Thinking is set with `reasoning`, not modelOptions
+      expectTypeOf<Options>().not.toHaveProperty('thinkingConfig')
 
       // Should have structured output options
       expectTypeOf<Options>().toExtend<GeminiStructuredOutputOptions>()
@@ -231,29 +225,29 @@ describe('Gemini Model Provider Options Type Assertions', () => {
       expectTypeOf<Options>().toExtend<BaseOptions>()
     })
 
-    it('gemini-3.7-flash should support thinking options', () => {
+    it('gemini-3.7-flash should support its options', () => {
       type Model = 'gemini-3.7-flash'
       type Options = GeminiChatModelProviderOptionsByName[Model]
 
-      expectTypeOf<Options>().toExtend<GeminiThinkingOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('thinkingConfig')
       expectTypeOf<Options>().toExtend<GeminiStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<BaseOptions>()
     })
 
-    it('gemini-3.6-flash should support thinking options', () => {
+    it('gemini-3.6-flash should support its options', () => {
       type Model = 'gemini-3.6-flash'
       type Options = GeminiChatModelProviderOptionsByName[Model]
 
-      expectTypeOf<Options>().toExtend<GeminiThinkingOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('thinkingConfig')
       expectTypeOf<Options>().toExtend<GeminiStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<BaseOptions>()
     })
 
-    it('gemini-3.5-flash-lite should support thinking options', () => {
+    it('gemini-3.5-flash-lite should support its options', () => {
       type Model = 'gemini-3.5-flash-lite'
       type Options = GeminiChatModelProviderOptionsByName[Model]
 
-      expectTypeOf<Options>().toExtend<GeminiThinkingOptions>()
+      expectTypeOf<Options>().not.toHaveProperty('thinkingConfig')
       expectTypeOf<Options>().toExtend<GeminiStructuredOutputOptions>()
       expectTypeOf<Options>().toExtend<BaseOptions>()
     })
@@ -289,12 +283,10 @@ describe('Gemini Model Provider Options Type Assertions', () => {
   })
 
   describe('Detailed property type assertions', () => {
-    it('thinking models should allow thinkingConfig', () => {
+    it('thinking models take thinking through reasoning, not thinkingConfig', () => {
       type Options = GeminiChatModelProviderOptionsByName['gemini-2.5-pro']
 
-      // gemini-2.5-pro supports thinking, so its provider options should
-      // include thinkingConfig from GeminiThinkingOptions.
-      expectTypeOf<Options>().toHaveProperty('thinkingConfig')
+      expectTypeOf<Options>().not.toHaveProperty('thinkingConfig')
     })
 
     it('structured output options should have responseMimeType and responseSchema', () => {
@@ -415,40 +407,40 @@ describe('Gemini Model Provider Options Type Assertions', () => {
   })
 
   describe('Type discrimination between model categories', () => {
-    it('models with thinking should extend GeminiThinkingOptions', () => {
+    it('no model takes thinkingConfig in modelOptions', () => {
       expectTypeOf<
         GeminiChatModelProviderOptionsByName['gemini-3.7-flash']
-      >().toExtend<GeminiThinkingOptions>()
+      >().not.toHaveProperty('thinkingConfig')
       expectTypeOf<
         GeminiChatModelProviderOptionsByName['gemini-3.6-flash']
-      >().toExtend<GeminiThinkingOptions>()
+      >().not.toHaveProperty('thinkingConfig')
       expectTypeOf<
         GeminiChatModelProviderOptionsByName['gemini-3.5-flash']
-      >().toExtend<GeminiThinkingOptions>()
+      >().not.toHaveProperty('thinkingConfig')
       expectTypeOf<
         GeminiChatModelProviderOptionsByName['gemini-3.5-flash-lite']
-      >().toExtend<GeminiThinkingOptions>()
+      >().not.toHaveProperty('thinkingConfig')
       expectTypeOf<
         GeminiChatModelProviderOptionsByName['gemini-3.1-pro-preview']
-      >().toExtend<GeminiThinkingOptions>()
+      >().not.toHaveProperty('thinkingConfig')
       expectTypeOf<
         GeminiChatModelProviderOptionsByName['gemini-3-flash-preview']
-      >().toExtend<GeminiThinkingOptions>()
+      >().not.toHaveProperty('thinkingConfig')
       expectTypeOf<
         GeminiChatModelProviderOptionsByName['gemini-3.1-flash-lite']
-      >().toExtend<GeminiThinkingOptions>()
+      >().not.toHaveProperty('thinkingConfig')
       expectTypeOf<
         GeminiChatModelProviderOptionsByName['gemini-3.1-flash-lite-preview']
-      >().toExtend<GeminiThinkingOptions>()
+      >().not.toHaveProperty('thinkingConfig')
       expectTypeOf<
         GeminiChatModelProviderOptionsByName['gemini-2.5-pro']
-      >().toExtend<GeminiThinkingOptions>()
+      >().not.toHaveProperty('thinkingConfig')
       expectTypeOf<
         GeminiChatModelProviderOptionsByName['gemini-2.5-flash']
-      >().toExtend<GeminiThinkingOptions>()
+      >().not.toHaveProperty('thinkingConfig')
       expectTypeOf<
         GeminiChatModelProviderOptionsByName['gemini-2.5-flash-lite']
-      >().toExtend<GeminiThinkingOptions>()
+      >().not.toHaveProperty('thinkingConfig')
     })
 
     it('all models should extend GeminiStructuredOutputOptions', () => {
diff --git a/packages/ai-gemini/tests/reasoning-request.test.ts b/packages/ai-gemini/tests/reasoning-request.test.ts
new file mode 100644
index 0000000000..e655e65991
--- /dev/null
+++ b/packages/ai-gemini/tests/reasoning-request.test.ts
@@ -0,0 +1,122 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { GeminiTextAdapter } from '../src/adapters/text'
+import { GeminiTextInteractionsAdapter } from '../src/experimental/text-interactions/adapter'
+import type { ReasoningRequest } from '@tanstack/ai'
+import type { GeminiModels } from '../src/model-meta'
+
+const mocks = vi.hoisted(() => ({
+  generateContentStream: vi.fn(),
+  interactionsCreate: vi.fn(),
+}))
+
+vi.mock('@google/genai', async () => {
+  const actual = await vi.importActual<any>('@google/genai')
+  class MockGoogleGenAI {
+    models = { generateContentStream: mocks.generateContentStream }
+    get interactions() {
+      return { create: mocks.interactionsCreate }
+    }
+  }
+  return { ...actual, GoogleGenAI: MockGoogleGenAI }
+})
+
+const logger = resolveDebugOption(false)
+
+async function* noChunks() {}
+
+/** Run one call and return the `thinkingConfig` it sent. */
+async function thinkingConfig(
+  model: GeminiModels,
+  reasoning: ReasoningRequest | undefined,
+) {
+  mocks.generateContentStream.mockResolvedValue(noChunks())
+  const adapter = new GeminiTextAdapter({ apiKey: 'test' }, model)
+  for await (const _chunk of adapter.chatStream({
+    logger,
+    model,
+    messages: [{ role: 'user', content: 'hi' }],
+    ...(reasoning ? { reasoning } : {}),
+  })) {
+    // Drain the stream.
+  }
+  const [payload] = mocks.generateContentStream.mock.calls.at(-1) ?? []
+  return payload.config.thinkingConfig
+}
+
+const on = (level: ReasoningRequest['level']): ReasoningRequest => ({
+  level,
+  summary: true,
+})
+
+describe('Gemini chat({ reasoning }) request shape', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('sends no thinkingConfig without a reasoning request', async () => {
+    expect(await thinkingConfig('gemini-3.1-pro-preview', undefined)).toBe(
+      undefined,
+    )
+  })
+
+  it('Gemini 3: thinkingLevel from the level', async () => {
+    expect(
+      await thinkingConfig('gemini-3-flash-preview', on('minimal')),
+    ).toEqual({ includeThoughts: true, thinkingLevel: 'MINIMAL' })
+    // gemini-3.1-pro-preview has no minimal: it clamps up to LOW.
+    expect(
+      await thinkingConfig('gemini-3.1-pro-preview', {
+        level: 'minimal',
+        summary: false,
+      }),
+    ).toEqual({ includeThoughts: false, thinkingLevel: 'LOW' })
+  })
+
+  it('Gemini 2.5: thinkingBudget from pi table, or budgetTokens', async () => {
+    expect(await thinkingConfig('gemini-2.5-pro', on('high'))).toEqual({
+      includeThoughts: true,
+      thinkingBudget: 32768,
+    })
+    expect(await thinkingConfig('gemini-2.5-flash', on('high'))).toEqual({
+      includeThoughts: true,
+      thinkingBudget: 24576,
+    })
+    expect(
+      await thinkingConfig('gemini-2.5-pro', {
+        level: 'low',
+        summary: true,
+        budgetTokens: 3000,
+      }),
+    ).toEqual({ includeThoughts: true, thinkingBudget: 3000 })
+  })
+
+  it('off: a zero budget', async () => {
+    expect(await thinkingConfig('gemini-2.5-flash', on('off'))).toEqual({
+      thinkingBudget: 0,
+    })
+  })
+})
+
+describe('Gemini Interactions chat({ reasoning }) request shape', () => {
+  it('sends thinking_level and thinking_summaries', async () => {
+    mocks.interactionsCreate.mockResolvedValue(noChunks())
+    const adapter = new GeminiTextInteractionsAdapter(
+      { apiKey: 'test' },
+      'gemini-3.8-flash',
+    )
+    for await (const _chunk of adapter.chatStream({
+      logger,
+      model: 'gemini-3.8-flash',
+      messages: [{ role: 'user', content: 'hi' }],
+      reasoning: { level: 'medium', summary: false },
+    })) {
+      // Drain the stream.
+    }
+    const [body] = mocks.interactionsCreate.mock.calls[0] ?? []
+    expect(body.generation_config).toEqual({
+      thinking_level: 'medium',
+      thinking_summaries: 'none',
+    })
+  })
+})
diff --git a/scripts/sync-provider-models.ts b/scripts/sync-provider-models.ts
index c38b0e6652..9be1587e79 100644
--- a/scripts/sync-provider-models.ts
+++ b/scripts/sync-provider-models.ts
@@ -174,9 +174,9 @@ const PROVIDER_MAP: Record<string, ProviderConfig> = {
     validInputModalities: ['text', 'image', 'audio', 'video', 'document'],
     kind: 'gemini',
     referenceSatisfies:
-      'ModelMeta<GeminiToolConfigOptions & GeminiSafetyOptions & GeminiCommonConfigOptions & GeminiCachedContentOptions & GeminiStructuredOutputOptions & GeminiThinkingOptions>',
+      'ModelMeta<GeminiToolConfigOptions & GeminiSafetyOptions & GeminiCommonConfigOptions & GeminiCachedContentOptions & GeminiStructuredOutputOptions>',
     referenceProviderOptionsEntry:
-      'GeminiToolConfigOptions & GeminiSafetyOptions & GeminiCommonConfigOptions & GeminiCachedContentOptions & GeminiStructuredOutputOptions & GeminiThinkingOptions',
+      'GeminiToolConfigOptions & GeminiSafetyOptions & GeminiCommonConfigOptions & GeminiCachedContentOptions & GeminiStructuredOutputOptions',
     hasBothNameAndId: false,
     providerOptionsIsMappedType: false,
     skipPatterns: [

From 253888d5a6c2f046babb15b1741a5105dd1787f8 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 14:39:55 +0200
Subject: [PATCH 090/286] feat(openai-base): send chat({ reasoning }) from a
 modelReasoning hook

The Chat Completions and Responses base adapters get a protected
`modelReasoning(model)` hook. When a subclass returns the model's
reasoning data, the base sends `reasoning_effort` (Chat Completions) or
`reasoning: { effort, summary }` (Responses). The default returns
nothing, so current subclasses send the same requests as before.

The OpenAI Responses adapter now uses the hook instead of its own copy.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-openai/src/adapters/text.ts       | 23 +++-----------
 .../src/adapters/chat-completions-text.ts     | 25 ++++++++++++++-
 .../src/adapters/responses-text.ts            | 31 ++++++++++++++++++-
 3 files changed, 58 insertions(+), 21 deletions(-)

diff --git a/packages/ai-openai/src/adapters/text.ts b/packages/ai-openai/src/adapters/text.ts
index 94a207732a..a418ce6a8a 100644
--- a/packages/ai-openai/src/adapters/text.ts
+++ b/packages/ai-openai/src/adapters/text.ts
@@ -1,5 +1,4 @@
 import OpenAI from 'openai'
-import { resolveReasoning } from '@tanstack/ai/adapter-internals'
 import {
   OpenAIBaseResponsesTextAdapter,
   warnStrictFallback,
@@ -121,6 +120,10 @@ export class OpenAITextAdapter<
     super(model, 'openai', new OpenAI(config), config)
   }
 
+  protected override modelReasoning(model: string) {
+    return OPENAI_MODEL_REASONING[model]
+  }
+
   /**
    * Maps common options to OpenAI-specific format.
    * Overrides the base class to use OpenAI's full tool converter
@@ -166,24 +169,6 @@ export class OpenAITextAdapter<
       ...(tools && tools.length > 0 && { tools }),
     }
 
-    // `chat({ reasoning })`: the model's effort for the level, and a summary
-    // so the thinking text streams back. The SDK type has no `max` yet, so
-    // the field goes on with Object.assign.
-    const reasoning = resolveReasoning(
-      options.reasoning,
-      OPENAI_MODEL_REASONING[options.model],
-    )
-    if (reasoning?.value) {
-      Object.assign(request, {
-        reasoning: {
-          effort: reasoning.value,
-          ...(reasoning.summary && reasoning.level !== 'off'
-            ? { summary: 'auto' }
-            : {}),
-        },
-      })
-    }
-
     // Reasoning models 400 on `temperature`/`top_p`. Callers (and the summarize
     // adapter's low-temperature default) can't know a given model rejects them,
     // so drop the pair here — stripping only ever averts a guaranteed 400, never
diff --git a/packages/openai-base/src/adapters/chat-completions-text.ts b/packages/openai-base/src/adapters/chat-completions-text.ts
index c4ac9d1ecd..448c204db2 100644
--- a/packages/openai-base/src/adapters/chat-completions-text.ts
+++ b/packages/openai-base/src/adapters/chat-completions-text.ts
@@ -6,6 +6,7 @@ import {
 } from '@tanstack/ai'
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
 import {
+  resolveReasoning,
   toRunErrorPayload,
   toRunErrorRawEvent,
 } from '@tanstack/ai/adapter-internals'
@@ -39,6 +40,7 @@ import type {
   Modality,
   ModelMessage,
   AdapterYieldChunk,
+  ModelReasoning,
   ReasoningCapability,
   TextOptions,
 } from '@tanstack/ai'
@@ -1244,6 +1246,15 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
     return true
   }
 
+  /**
+   * The model's reasoning data for `chat({ reasoning })`. The default is
+   * none, so the base sends no reasoning field. A subclass returns the
+   * model's entry from its generated `model-reasoning.ts` map.
+   */
+  protected modelReasoning(_model: string): ModelReasoning | undefined {
+    return undefined
+  }
+
   /**
    * Extra headers for one call, for example session headers. They go on top
    * of the headers of `options.request`.
@@ -1331,11 +1342,17 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
         }
       : undefined
 
+    // `chat({ reasoning })`: the model's effort for the level.
+    const reasoning = resolveReasoning(
+      options.reasoning,
+      this.modelReasoning(options.model),
+    )
+
     // `modelOptions` is the sole sampling surface: callers set provider-native
     // wire names (`temperature`, `top_p`, `max_tokens`/`max_completion_tokens`)
     // there and they flow through the spread below. The root
     // `temperature`/`topP`/`maxTokens` fields are intentionally NOT read here.
-    return {
+    const params: ChatCompletionCreateParamsStreaming = {
       ...modelOptions,
       model: options.model,
       messages,
@@ -1348,6 +1365,12 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
       ...(responseFormat ?? {}),
       stream: true,
     }
+    // The SDK type does not list every provider's effort values, so the
+    // field goes on with Object.assign.
+    if (reasoning?.value) {
+      Object.assign(params, { reasoning_effort: reasoning.value })
+    }
+    return params
   }
 
   /**
diff --git a/packages/openai-base/src/adapters/responses-text.ts b/packages/openai-base/src/adapters/responses-text.ts
index d80f4c16ea..8bf95dbfb7 100644
--- a/packages/openai-base/src/adapters/responses-text.ts
+++ b/packages/openai-base/src/adapters/responses-text.ts
@@ -7,6 +7,7 @@ import {
 } from '@tanstack/ai'
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
 import {
+  resolveReasoning,
   toRunErrorPayload,
   toRunErrorRawEvent,
 } from '@tanstack/ai/adapter-internals'
@@ -53,6 +54,7 @@ import type {
   ModelMessage,
   AdapterYieldChunk,
   ProviderExecutedToolMetadata,
+  ModelReasoning,
   ProviderExecutedToolSource,
   ReasoningCapability,
   TextOptions,
@@ -917,6 +919,15 @@ export abstract class OpenAIBaseResponsesTextAdapter<
     return parsed
   }
 
+  /**
+   * The model's reasoning data for `chat({ reasoning })`. The default is
+   * none, so the base sends no reasoning field. A subclass returns the
+   * model's entry from its generated `model-reasoning.ts` map.
+   */
+  protected modelReasoning(_model: string): ModelReasoning | undefined {
+    return undefined
+  }
+
   /**
    * Extract text content from a non-streaming Responses API response.
    * Override this in subclasses for provider-specific response shapes.
@@ -2205,7 +2216,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
     // `input`, `tools`, `textFormat`) are layered on top afterward so they
     // always win over any same-named key a caller happened to put in
     // `modelOptions`.
-    return {
+    const params: Omit<ResponseCreateParams, 'stream'> = {
       ...modelOptions,
       model: options.model,
       ...(options.metadata !== undefined && { metadata: options.metadata }),
@@ -2220,6 +2231,24 @@ export abstract class OpenAIBaseResponsesTextAdapter<
       ...(tools && tools.length > 0 && { tools }),
       ...(textFormat ?? {}),
     }
+    // `chat({ reasoning })`: the model's effort for the level, and a summary
+    // so the thinking text streams back. The SDK type does not list every
+    // provider's effort values, so the field goes on with Object.assign.
+    const reasoning = resolveReasoning(
+      options.reasoning,
+      this.modelReasoning(options.model),
+    )
+    if (reasoning?.value) {
+      Object.assign(params, {
+        reasoning: {
+          effort: reasoning.value,
+          ...(reasoning.summary && reasoning.level !== 'off'
+            ? { summary: 'auto' }
+            : {}),
+        },
+      })
+    }
+    return params
   }
 
   /**

From 4fcfaf65b4aba45a3287156f89be3735a5b3fb89 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 14:39:56 +0200
Subject: [PATCH 091/286] feat(ai-bedrock)!: map chat({ reasoning }) on all
 three Bedrock APIs

`reasoning_effort` (Chat Completions) and `reasoning` (Responses) leave
modelOptions. The adapters read the generated model-reasoning map:

- Chat Completions and Responses: the base hook sends the effort
- Converse, Claude only (pi's rule): budget thinking in
  `additionalModelRequestFields` with the interleaved-thinking beta, and
  `maxTokens` grows to leave room past the budget; a model with effort
  levels gets adaptive thinking with `output_config.effort`
- Converse `off`, and models that are not Claude, send no thinking

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .../ai-bedrock/src/adapters/converse-text.ts  |  27 ++++-
 .../ai-bedrock/src/adapters/responses-text.ts |  15 ++-
 packages/ai-bedrock/src/adapters/text.ts      |  15 ++-
 packages/ai-bedrock/src/converse/reasoning.ts |  63 ++++++++++
 .../src/text/responses-provider-options.ts    |   2 -
 .../src/text/text-provider-options.ts         |   6 +-
 .../tests/reasoning-request.test.ts           | 109 ++++++++++++++++++
 7 files changed, 227 insertions(+), 10 deletions(-)
 create mode 100644 packages/ai-bedrock/src/converse/reasoning.ts
 create mode 100644 packages/ai-bedrock/tests/reasoning-request.test.ts

diff --git a/packages/ai-bedrock/src/adapters/converse-text.ts b/packages/ai-bedrock/src/adapters/converse-text.ts
index fb176f08d0..ba96db42ed 100644
--- a/packages/ai-bedrock/src/adapters/converse-text.ts
+++ b/packages/ai-bedrock/src/adapters/converse-text.ts
@@ -9,6 +9,9 @@ import {
   throwIfConverseStreamError,
 } from '../converse/stream-processor'
 import { buildConverseUsage } from '../converse/usage'
+import { converseThinking } from '../converse/reasoning'
+import { BEDROCK_MODEL_REASONING } from '../model-reasoning'
+import type { BedrockModelReasoningByName } from '../model-reasoning'
 import {
   STRUCTURED_TOOL_NAME,
   buildStructuredToolConfig,
@@ -66,6 +69,12 @@ export interface BedrockConverseConfig extends BedrockClientConfig {}
  * so tests can subclass and inject canned Converse SDK shapes without a real
  * AWS request.
  */
+/** The reasoning levels of a model, for `chat({ reasoning })`. `never`: none. */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof BedrockModelReasoningByName
+    ? BedrockModelReasoningByName[TModel]
+    : never
+
 export class BedrockConverseTextAdapter<
   TModel extends BedrockConverseModels,
   // Constraint mirrors the chat adapter (text.ts): the base parameterises
@@ -90,7 +99,8 @@ export class BedrockConverseTextAdapter<
   unknown,
   // TSystemPromptMetadata — narrows `systemPrompts[i].metadata` at the chat()
   // call site so users get `cachePoint` autocomplete.
-  BedrockSystemPromptMetadata
+  BedrockSystemPromptMetadata,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   override readonly name = 'bedrock-converse' as const
@@ -567,7 +577,19 @@ export class BedrockConverseTextAdapter<
     const modelOptions = options.modelOptions
     const temperature = modelOptions?.temperature
     const topP = modelOptions?.top_p
-    const maxTokens = modelOptions?.max_completion_tokens
+    // `chat({ reasoning })`: Claude's thinking fields. Budget thinking needs
+    // `maxTokens` above the budget, so a smaller or missing value grows.
+    const { additionalModelRequestFields, minMaxTokens } = converseThinking(
+      this.model,
+      options.reasoning,
+      BEDROCK_MODEL_REASONING[this.model],
+    )
+    const requestedMaxTokens = modelOptions?.max_completion_tokens
+    const maxTokens =
+      minMaxTokens !== undefined &&
+      (requestedMaxTokens == null || requestedMaxTokens < minMaxTokens)
+        ? minMaxTokens
+        : requestedMaxTokens
     const stop = modelOptions?.stop
     const stopSequences =
       stop == null ? undefined : Array.isArray(stop) ? stop : [stop]
@@ -591,6 +613,7 @@ export class BedrockConverseTextAdapter<
       ...(system.length > 0 && { system }),
       ...(toolConfig && { toolConfig }),
       ...(inferenceConfig && { inferenceConfig }),
+      ...(additionalModelRequestFields && { additionalModelRequestFields }),
     }
   }
 }
diff --git a/packages/ai-bedrock/src/adapters/responses-text.ts b/packages/ai-bedrock/src/adapters/responses-text.ts
index a4dd10d1e1..7489ee4e6a 100644
--- a/packages/ai-bedrock/src/adapters/responses-text.ts
+++ b/packages/ai-bedrock/src/adapters/responses-text.ts
@@ -1,6 +1,8 @@
 import OpenAI from 'openai'
 import { OpenAIBaseResponsesTextAdapter } from '@tanstack/openai-base'
 import { withBedrockDefaults } from '../utils/client'
+import { BEDROCK_MODEL_REASONING } from '../model-reasoning'
+import type { BedrockModelReasoningByName } from '../model-reasoning'
 import type { Modality } from '@tanstack/ai'
 import type { BedrockClientConfig } from '../utils/client'
 import type { BedrockMessageMetadataByModality } from '../message-types'
@@ -17,6 +19,12 @@ export interface BedrockResponsesConfig
 
 export type { ExternalResponsesProviderOptions as BedrockResponsesProviderOptions } from '../text/responses-provider-options'
 
+/** The reasoning levels of a model, for `chat({ reasoning })`. `never`: none. */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof BedrockModelReasoningByName
+    ? BedrockModelReasoningByName[TModel]
+    : never
+
 type ResolveToolCapabilities<TModel extends string> =
   TModel extends keyof BedrockChatModelToolCapabilitiesByName
     ? NonNullable<BedrockChatModelToolCapabilitiesByName[TModel]>
@@ -47,7 +55,8 @@ export class BedrockResponsesTextAdapter<
   TProviderOptions,
   TInputModalities,
   BedrockMessageMetadataByModality,
-  TToolCapabilities
+  TToolCapabilities,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   override readonly name = 'bedrock-responses' as const
@@ -62,6 +71,10 @@ export class BedrockResponsesTextAdapter<
       config,
     )
   }
+
+  protected override modelReasoning(model: string) {
+    return BEDROCK_MODEL_REASONING[model]
+  }
 }
 
 /** Responses adapter with an explicit API key (low-level; the public branching factory delegates here). */
diff --git a/packages/ai-bedrock/src/adapters/text.ts b/packages/ai-bedrock/src/adapters/text.ts
index 80679c9db7..79c0483f71 100644
--- a/packages/ai-bedrock/src/adapters/text.ts
+++ b/packages/ai-bedrock/src/adapters/text.ts
@@ -1,6 +1,8 @@
 import OpenAI from 'openai'
 import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
 import { withBedrockDefaults } from '../utils/client'
+import { BEDROCK_MODEL_REASONING } from '../model-reasoning'
+import type { BedrockModelReasoningByName } from '../model-reasoning'
 import type { Modality } from '@tanstack/ai'
 import type { BedrockClientConfig } from '../utils/client'
 import type { BedrockMessageMetadataByModality } from '../message-types'
@@ -17,6 +19,12 @@ export interface BedrockTextConfig
 
 export type { ExternalTextProviderOptions as BedrockTextProviderOptions } from '../text/text-provider-options'
 
+/** The reasoning levels of a model, for `chat({ reasoning })`. `never`: none. */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof BedrockModelReasoningByName
+    ? BedrockModelReasoningByName[TModel]
+    : never
+
 type ResolveToolCapabilities<TModel extends string> =
   TModel extends keyof BedrockChatModelToolCapabilitiesByName
     ? NonNullable<BedrockChatModelToolCapabilitiesByName[TModel]>
@@ -47,7 +55,8 @@ export class BedrockTextAdapter<
   TProviderOptions,
   TInputModalities,
   BedrockMessageMetadataByModality,
-  TToolCapabilities
+  TToolCapabilities,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   override readonly name = 'bedrock' as const
@@ -62,6 +71,10 @@ export class BedrockTextAdapter<
     )
   }
 
+  protected override modelReasoning(model: string) {
+    return BEDROCK_MODEL_REASONING[model]
+  }
+
   /**
    * Surface reasoning deltas (gpt-oss / Claude reasoning) the OpenAI-compatible
    * way. Base types the chunk as `unknown`; narrow with runtime guards — no
diff --git a/packages/ai-bedrock/src/converse/reasoning.ts b/packages/ai-bedrock/src/converse/reasoning.ts
new file mode 100644
index 0000000000..a205c7942b
--- /dev/null
+++ b/packages/ai-bedrock/src/converse/reasoning.ts
@@ -0,0 +1,63 @@
+import {
+  reasoningBudget,
+  resolveReasoning,
+} from '@tanstack/ai/adapter-internals'
+import type { ModelReasoning, ReasoningRequest } from '@tanstack/ai'
+
+/** The answer room pi keeps next to a thinking budget. */
+const MIN_ANSWER_TOKENS = 1024
+
+export interface ConverseThinking {
+  additionalModelRequestFields?:
+    | {
+        thinking: { type: 'enabled'; budget_tokens: number }
+        anthropic_beta: Array<string>
+      }
+    | {
+        thinking: { type: 'adaptive' }
+        output_config: { effort: string }
+      }
+  /** The smallest `maxTokens` that leaves room for the thinking budget. */
+  minMaxTokens?: number
+}
+
+/**
+ * The Converse thinking fields for `chat({ reasoning })`. Only Claude takes
+ * them on Converse (pi's rule):
+ * - a budget model: enabled thinking with the budget (pi's table when the
+ *   request sets none), and the interleaved-thinking beta.
+ * - a model with effort levels: adaptive thinking with the effort.
+ * `off` sends nothing, because Claude does not think unless asked.
+ */
+export function converseThinking(
+  model: string,
+  request: ReasoningRequest | undefined,
+  reasoning: ModelReasoning | undefined,
+): ConverseThinking {
+  if (!model.includes('anthropic.claude')) return {}
+  const resolved = resolveReasoning(request, reasoning)
+  if (!resolved || !reasoning || resolved.level === 'off') return {}
+  if (reasoning.budget) {
+    const budget = reasoningBudget({
+      level: resolved.level,
+      summary: resolved.summary,
+      ...(resolved.budgetTokens !== undefined
+        ? { budgetTokens: resolved.budgetTokens }
+        : {}),
+    })
+    return {
+      additionalModelRequestFields: {
+        thinking: { type: 'enabled', budget_tokens: budget },
+        anthropic_beta: ['interleaved-thinking-2025-05-14'],
+      },
+      minMaxTokens: budget + MIN_ANSWER_TOKENS,
+    }
+  }
+  if (resolved.value === null) return {}
+  return {
+    additionalModelRequestFields: {
+      thinking: { type: 'adaptive' },
+      output_config: { effort: resolved.value },
+    },
+  }
+}
diff --git a/packages/ai-bedrock/src/text/responses-provider-options.ts b/packages/ai-bedrock/src/text/responses-provider-options.ts
index a2f0c28a7b..0766004872 100644
--- a/packages/ai-bedrock/src/text/responses-provider-options.ts
+++ b/packages/ai-bedrock/src/text/responses-provider-options.ts
@@ -20,8 +20,6 @@ export interface BedrockResponsesProviderOptions {
     | 'required'
     | { type: 'function'; name: string }
     | null
-  /** Reasoning controls for reasoning-capable models. */
-  reasoning?: { effort?: 'low' | 'medium' | 'high' } | null
   user?: string | null
 }
 
diff --git a/packages/ai-bedrock/src/text/text-provider-options.ts b/packages/ai-bedrock/src/text/text-provider-options.ts
index ef7edcdf3a..1d8f2ed82c 100644
--- a/packages/ai-bedrock/src/text/text-provider-options.ts
+++ b/packages/ai-bedrock/src/text/text-provider-options.ts
@@ -1,7 +1,7 @@
 /**
  * Bedrock Chat Completions provider options. Bedrock accepts the standard
- * OpenAI Chat Completions request fields; we surface the commonly-used ones
- * plus `reasoning_effort` (supported by gpt-oss and reasoning models).
+ * OpenAI Chat Completions request fields; we surface the commonly-used ones.
+ * Reasoning effort is set with `chat({ reasoning })`.
  *
  * @see https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-openai.html
  */
@@ -15,8 +15,6 @@ export interface BedrockTextProviderOptions {
   metadata?: { [key: string]: string } | null
   n?: number | null
   parallel_tool_calls?: boolean | null
-  /** gpt-oss / reasoning models: 'low' | 'medium' (default) | 'high'. */
-  reasoning_effort?: 'low' | 'medium' | 'high' | null
   seed?: number | null
   stop?: string | Array<string> | null
   temperature?: number | null
diff --git a/packages/ai-bedrock/tests/reasoning-request.test.ts b/packages/ai-bedrock/tests/reasoning-request.test.ts
new file mode 100644
index 0000000000..a9431336dd
--- /dev/null
+++ b/packages/ai-bedrock/tests/reasoning-request.test.ts
@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { BedrockTextAdapter } from '../src/adapters/text'
+import { BedrockResponsesTextAdapter } from '../src/adapters/responses-text'
+import { BedrockConverseTextAdapter } from '../src/adapters/converse-text'
+import type { ReasoningRequest, TextOptions } from '@tanstack/ai'
+import type { BedrockConverseModels } from '../src/model-meta'
+import type { BedrockConverseProviderOptions } from '../src/converse/provider-options'
+
+const logger = resolveDebugOption(false)
+const config = { apiKey: 'k', region: 'us-east-1' }
+
+function options(
+  model: string,
+  reasoning: ReasoningRequest | undefined,
+): TextOptions {
+  return {
+    model,
+    logger,
+    messages: [{ role: 'user', content: 'hi' }],
+    ...(reasoning ? { reasoning } : {}),
+  }
+}
+
+class ChatProbe extends BedrockTextAdapter<'openai.gpt-oss-120b-1:0'> {
+  request(reasoning: ReasoningRequest | undefined) {
+    return this.mapOptionsToRequest(options(this.model, reasoning))
+  }
+}
+
+class ResponsesProbe extends BedrockResponsesTextAdapter<'openai.gpt-oss-120b-1:0'> {
+  request(reasoning: ReasoningRequest | undefined) {
+    return this.mapOptionsToRequest(options(this.model, reasoning))
+  }
+}
+
+class ConverseProbe<
+  TModel extends BedrockConverseModels,
+> extends BedrockConverseTextAdapter<TModel, BedrockConverseProviderOptions> {
+  request(
+    reasoning: ReasoningRequest | undefined,
+    modelOptions?: BedrockConverseProviderOptions,
+  ) {
+    return this.buildInput({
+      ...options(this.model, reasoning),
+      ...(modelOptions ? { modelOptions } : {}),
+    })
+  }
+}
+
+const on = (level: ReasoningRequest['level']): ReasoningRequest => ({
+  level,
+  summary: true,
+})
+
+describe('Bedrock chat({ reasoning }) request shape', () => {
+  it('Chat Completions: reasoning_effort', () => {
+    const adapter = new ChatProbe(config, 'openai.gpt-oss-120b-1:0')
+    expect(adapter.request(on('high'))).toMatchObject({
+      reasoning_effort: 'high',
+    })
+    expect(adapter.request(undefined)).not.toHaveProperty('reasoning_effort')
+    // gpt-oss has no minimal: it clamps up to low.
+    expect(adapter.request(on('minimal'))).toMatchObject({
+      reasoning_effort: 'low',
+    })
+  })
+
+  it('Responses: reasoning.effort and a summary', () => {
+    const adapter = new ResponsesProbe(config, 'openai.gpt-oss-120b-1:0')
+    expect(adapter.request(on('medium'))).toMatchObject({
+      reasoning: { effort: 'medium', summary: 'auto' },
+    })
+    expect(adapter.request({ level: 'low', summary: false }).reasoning).toEqual(
+      { effort: 'low' },
+    )
+  })
+
+  it('Converse Claude: budget thinking, the beta, and room in maxTokens', () => {
+    const adapter = new ConverseProbe(
+      config,
+      'us.anthropic.claude-haiku-4-5-20251001-v1:0',
+    )
+    const input = adapter.request(on('high'), { max_completion_tokens: 4000 })
+    expect(input.additionalModelRequestFields).toEqual({
+      thinking: { type: 'enabled', budget_tokens: 16384 },
+      anthropic_beta: ['interleaved-thinking-2025-05-14'],
+    })
+    expect(input.inferenceConfig?.maxTokens).toBe(17408)
+    expect(
+      adapter.request({ level: 'high', summary: true, budgetTokens: 2000 })
+        .additionalModelRequestFields,
+    ).toMatchObject({ thinking: { budget_tokens: 2000 } })
+  })
+
+  it('Converse: off, and models that are not Claude, send no thinking', () => {
+    const claude = new ConverseProbe(
+      config,
+      'us.anthropic.claude-haiku-4-5-20251001-v1:0',
+    )
+    expect(claude.request(on('off'))).not.toHaveProperty(
+      'additionalModelRequestFields',
+    )
+    const gptOss = new ConverseProbe(config, 'openai.gpt-oss-120b-1:0')
+    expect(gptOss.request(on('high'))).not.toHaveProperty(
+      'additionalModelRequestFields',
+    )
+  })
+})

From 428bbad481619545894411b9d8cfd9c67309f9e4 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 14:43:54 +0200
Subject: [PATCH 092/286] feat(ai-mistral): map chat({ reasoning }) to Mistral
 reasoning fields

The adapter reads the generated model-reasoning map, by pi's rule:

- Mistral Small and Medium: `reasoning_effort` with the level's value,
  `none` for `off`
- Magistral: `prompt_mode: 'reasoning'`, and nothing for `off`

The streaming wire body now sends both fields in snake_case.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-mistral/src/adapters/text.ts      | 52 +++++++++++++-
 .../tests/reasoning-request.test.ts           | 70 +++++++++++++++++++
 2 files changed, 120 insertions(+), 2 deletions(-)
 create mode 100644 packages/ai-mistral/tests/reasoning-request.test.ts

diff --git a/packages/ai-mistral/src/adapters/text.ts b/packages/ai-mistral/src/adapters/text.ts
index 981ebed464..53dbcd0d61 100644
--- a/packages/ai-mistral/src/adapters/text.ts
+++ b/packages/ai-mistral/src/adapters/text.ts
@@ -10,11 +10,16 @@ import {
 import { makeMistralStructuredOutputCompatibleWithMap } from '../utils/schema-converter'
 import { createToolInputNormalizer } from '../utils/tool-input-normalizer'
 import { MISTRAL_MODEL_INPUT_MODALITIES } from '../model-meta'
+import { MISTRAL_MODEL_REASONING } from '../model-reasoning'
+import { resolveReasoning } from '@tanstack/ai/adapter-internals'
+import type { MistralModelReasoningByName } from '../model-reasoning'
 import type {
   ContentPart,
   Modality,
   ModelMessage,
   AdapterYieldChunk,
+  ModelReasoning,
+  ReasoningRequest,
   TextOptions,
 } from '@tanstack/ai'
 import type {
@@ -28,7 +33,10 @@ import type {
   StructuredOutputResult,
 } from '@tanstack/ai/adapters'
 import type { Mistral } from '@mistralai/mistralai'
-import type { ChatCompletionStreamRequest } from '@mistralai/mistralai/models/components'
+import type {
+  ChatCompletionStreamRequest,
+  ReasoningEffort,
+} from '@mistralai/mistralai/models/components'
 import type {
   ExternalTextProviderOptions,
   InternalTextProviderOptions,
@@ -93,6 +101,34 @@ type ResolveProviderOptions<TModel extends string> =
     ? MistralChatModelProviderOptionsByName[TModel]
     : MistralTextProviderOptions
 
+/** The reasoning levels of a model, for `chat({ reasoning })`. `never`: none. */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof MistralModelReasoningByName
+    ? MistralModelReasoningByName[TModel]
+    : never
+
+/**
+ * The Mistral reasoning fields for `chat({ reasoning })`, by pi's rule:
+ * - a model with effort levels (Mistral Small, Mistral Medium):
+ *   `reasoningEffort` with the level's value, `none` for `off`.
+ * - another reasoning model (Magistral): `promptMode: 'reasoning'`, and
+ *   nothing for `off`.
+ */
+function mistralReasoning(
+  request: ReasoningRequest | undefined,
+  reasoning: ModelReasoning | undefined,
+): Pick<ChatCompletionStreamRequest, 'promptMode' | 'reasoningEffort'> {
+  const resolved = resolveReasoning(request, reasoning)
+  if (!resolved || !reasoning) return {}
+  if (reasoning.map) {
+    // `ReasoningEffort` is an open enum, so a newer value still goes out.
+    return resolved.value === null
+      ? {}
+      : { reasoningEffort: resolved.value as ReasoningEffort }
+  }
+  return resolved.level === 'off' ? {} : { promptMode: 'reasoning' }
+}
+
 type ResolveInputModalities<TModel extends string> =
   TModel extends keyof MistralModelInputModalitiesByName
     ? MistralModelInputModalitiesByName[TModel]
@@ -174,7 +210,11 @@ export class MistralTextAdapter<
   TModel,
   TProviderOptions,
   TInputModalities,
-  MistralMessageMetadataByModality
+  MistralMessageMetadataByModality,
+  ReadonlyArray<string>,
+  unknown,
+  never,
+  ResolveReasoning<TModel>
 > {
   readonly name = 'mistral' as const
   override readonly inputModalities = MISTRAL_MODEL_INPUT_MODALITIES[this.model]
@@ -843,6 +883,8 @@ export class MistralTextAdapter<
       frequencyPenalty,
       presencePenalty,
       safePrompt,
+      reasoningEffort,
+      promptMode,
       stream: _stream,
       ...rest
     } = params
@@ -864,6 +906,8 @@ export class MistralTextAdapter<
       ...(frequencyPenalty != null && { frequency_penalty: frequencyPenalty }),
       ...(presencePenalty != null && { presence_penalty: presencePenalty }),
       ...(safePrompt != null && { safe_prompt: safePrompt }),
+      ...(reasoningEffort != null && { reasoning_effort: reasoningEffort }),
+      ...(promptMode != null && { prompt_mode: promptMode }),
     }
   }
 
@@ -940,6 +984,10 @@ export class MistralTextAdapter<
       topP: modelOptions?.top_p ?? undefined,
       tools: tools as ChatCompletionStreamRequest['tools'],
       stream: true,
+      ...mistralReasoning(
+        options.reasoning,
+        MISTRAL_MODEL_REASONING[options.model],
+      ),
       ...(modelOptions && {
         ...(modelOptions.stop != null && { stop: modelOptions.stop }),
         ...(modelOptions.random_seed != null && {
diff --git a/packages/ai-mistral/tests/reasoning-request.test.ts b/packages/ai-mistral/tests/reasoning-request.test.ts
new file mode 100644
index 0000000000..82a080531b
--- /dev/null
+++ b/packages/ai-mistral/tests/reasoning-request.test.ts
@@ -0,0 +1,70 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { createMistralText } from '../src/adapters/text'
+import type { ReasoningRequest } from '@tanstack/ai'
+import type { MISTRAL_CHAT_MODELS } from '../src/model-meta'
+
+const logger = resolveDebugOption(false)
+
+/** Run one streaming call and return the JSON body it sent. */
+async function send(
+  model: (typeof MISTRAL_CHAT_MODELS)[number],
+  reasoning: ReasoningRequest | undefined,
+) {
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    status: 200,
+    body: new ReadableStream({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode('data: [DONE]\n\n'))
+        controller.close()
+      },
+    }),
+  })
+  vi.stubGlobal('fetch', fetchMock)
+  const adapter = createMistralText(model, 'test-key')
+  for await (const _chunk of adapter.chatStream({
+    logger,
+    model,
+    messages: [{ role: 'user', content: 'hi' }],
+    ...(reasoning ? { reasoning } : {}),
+  })) {
+    // Drain the stream.
+  }
+  const [, init] = fetchMock.mock.calls[0] ?? []
+  return JSON.parse(init.body) as Record<string, unknown>
+}
+
+const on = (level: ReasoningRequest['level']): ReasoningRequest => ({
+  level,
+  summary: true,
+})
+
+describe('Mistral chat({ reasoning }) request shape', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('effort models: reasoning_effort, and none for off', async () => {
+    expect(await send('mistral-small-latest', on('high'))).toMatchObject({
+      reasoning_effort: 'high',
+    })
+    expect(await send('mistral-small-latest', on('off'))).toMatchObject({
+      reasoning_effort: 'none',
+    })
+  })
+
+  it('Magistral: prompt_mode reasoning, and nothing for off', async () => {
+    const high = await send('magistral-medium-latest', on('medium'))
+    expect(high.prompt_mode).toBe('reasoning')
+    expect(high).not.toHaveProperty('reasoning_effort')
+    const off = await send('magistral-medium-latest', on('off'))
+    expect(off).not.toHaveProperty('prompt_mode')
+  })
+
+  it('sends no reasoning fields without a request', async () => {
+    const body = await send('mistral-small-latest', undefined)
+    expect(body).not.toHaveProperty('reasoning_effort')
+    expect(body).not.toHaveProperty('prompt_mode')
+  })
+})

From 49d15df48946a3e804d06b11aaeb5bbdfa168c97 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 14:49:31 +0200
Subject: [PATCH 093/286] feat(ai-grok)!: map chat({ reasoning }) to xAI
 reasoning.effort

`reasoning` leaves the Grok modelOptions, with GrokReasoning and
GrokReasoningEffort. The adapter uses the Responses base hook, so a
model's level becomes `reasoning.effort` with a summary.

The reasoning sync gets per-package overrides. ai-grok sets
grok-build-0.1 to no reasoning, because the xAI API refuses the field
for it. The drift test skips overridden models.

ai-grok-build loses its generated reasoning map: the Grok Build CLI has
no effort control, so it keeps no `reasoning` option.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-grok-build/src/model-reasoning.ts | 25 --------
 packages/ai-grok/src/adapters/text.ts         | 21 ++++---
 packages/ai-grok/src/model-meta.ts            |  7 +--
 packages/ai-grok/src/model-reasoning.ts       |  6 +-
 .../ai-grok/src/text/text-provider-options.ts | 20 -------
 packages/ai-grok/tests/grok-adapter.test.ts   | 60 +++++++++++--------
 .../ai-grok/tests/reasoning-types.test-d.ts   | 25 ++++++++
 scripts/model-sync/reasoning-drift.test.ts    | 10 +++-
 scripts/model-sync/reasoning-targets.ts       | 17 +++---
 scripts/sync-model-reasoning.ts               |  5 ++
 10 files changed, 99 insertions(+), 97 deletions(-)
 delete mode 100644 packages/ai-grok-build/src/model-reasoning.ts
 create mode 100644 packages/ai-grok/tests/reasoning-types.test-d.ts

diff --git a/packages/ai-grok-build/src/model-reasoning.ts b/packages/ai-grok-build/src/model-reasoning.ts
deleted file mode 100644
index 82f8f78ff1..0000000000
--- a/packages/ai-grok-build/src/model-reasoning.ts
+++ /dev/null
@@ -1,25 +0,0 @@
-// Generated by scripts/sync-model-reasoning.ts from models.dev. Do not edit.
-import type { ModelReasoning } from '@tanstack/ai'
-
-/**
- * Each model's reasoning levels, and whether it takes a token budget, for
- * `chat({ reasoning })`. A model that is not here does not reason.
- */
-export type GrokBuildModelReasoningByName = {
-  'grok-build': {
-    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
-    budget: false
-  }
-  'grok-build-0.1': {
-    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
-    budget: false
-  }
-}
-
-/** The same data at runtime. `false`: the model does not reason. */
-export const GROK_BUILD_MODEL_REASONING: Readonly<
-  Record<string, ModelReasoning>
-> = {
-  'grok-build': { budget: false },
-  'grok-build-0.1': { budget: false },
-}
diff --git a/packages/ai-grok/src/adapters/text.ts b/packages/ai-grok/src/adapters/text.ts
index 0f36af0510..be59738582 100644
--- a/packages/ai-grok/src/adapters/text.ts
+++ b/packages/ai-grok/src/adapters/text.ts
@@ -2,6 +2,8 @@ import OpenAI from 'openai'
 import { fileReferenceFor, isFileSource } from '@tanstack/ai'
 import { OpenAIBaseResponsesTextAdapter } from '@tanstack/openai-base'
 import { GROK_MODEL_INPUT_MODALITIES } from '../model-meta'
+import { GROK_MODEL_REASONING } from '../model-reasoning'
+import type { GrokModelReasoningByName } from '../model-reasoning'
 import { getGrokApiKeyFromEnv, withGrokDefaults } from '../utils/client'
 import { convertToolsToProviderFormat } from '../tools'
 import type {
@@ -22,6 +24,12 @@ import type {
 /**
  * Resolve tool capabilities for a specific Grok model.
  */
+/** The reasoning levels of a model, for `chat({ reasoning })`. `never`: none. */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof GrokModelReasoningByName
+    ? GrokModelReasoningByName[TModel]
+    : never
+
 type ResolveToolCapabilities<TModel extends string> =
   TModel extends keyof GrokChatModelToolCapabilitiesByName
     ? NonNullable<GrokChatModelToolCapabilitiesByName[TModel]>
@@ -63,7 +71,8 @@ export class GrokTextAdapter<
   TProviderOptions,
   TInputModalities,
   GrokMessageMetadataByModality,
-  TToolCapabilities
+  TToolCapabilities,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   override readonly name = 'grok' as const
@@ -77,6 +86,10 @@ export class GrokTextAdapter<
     super(model, 'grok', new OpenAI(withGrokDefaults(config)))
   }
 
+  protected override modelReasoning(model: string) {
+    return GROK_MODEL_REASONING[model]
+  }
+
   /**
    * Route a `{ type: 'file' }` source to xAI's URL-shaped fields rather than
    * the `file_id` the OpenAI Responses base emits.
@@ -115,12 +128,6 @@ export class GrokTextAdapter<
     })
     void _baseTools
 
-    if (this.model === 'grok-build-0.1' && request.reasoning !== undefined) {
-      throw new Error(
-        'grok-build-0.1 does not support reasoning modelOptions; omit reasoning for this model.',
-      )
-    }
-
     const tools = options.tools
       ? convertToolsToProviderFormat(options.tools)
       : undefined
diff --git a/packages/ai-grok/src/model-meta.ts b/packages/ai-grok/src/model-meta.ts
index 21a0817a88..922488003c 100644
--- a/packages/ai-grok/src/model-meta.ts
+++ b/packages/ai-grok/src/model-meta.ts
@@ -2,10 +2,7 @@
  * Model metadata interface for documentation and type inference
  */
 import type { Modality } from '@tanstack/ai'
-import type {
-  GrokBuildProviderOptions,
-  GrokTextProviderOptions,
-} from './text/text-provider-options'
+import type { GrokTextProviderOptions } from './text/text-provider-options'
 
 interface ModelMeta {
   name: string
@@ -479,7 +476,7 @@ export type GrokProviderOptions = GrokTextProviderOptions
  */
 export type GrokChatModelProviderOptionsByName = {
   [GROK_4_3.name]: GrokProviderOptions
-  [GROK_BUILD_0_1.name]: GrokBuildProviderOptions
+  [GROK_BUILD_0_1.name]: GrokProviderOptions
   [GROK_4_20_REASONING.name]: GrokProviderOptions
   [GROK_4_20_NON_REASONING.name]: GrokProviderOptions
   [GROK_4_1_FAST_REASONING.name]: GrokProviderOptions
diff --git a/packages/ai-grok/src/model-reasoning.ts b/packages/ai-grok/src/model-reasoning.ts
index 556ec3b704..4685f84483 100644
--- a/packages/ai-grok/src/model-reasoning.ts
+++ b/packages/ai-grok/src/model-reasoning.ts
@@ -9,10 +9,6 @@ export type GrokModelReasoningByName = {
   'grok-4.7': { levels: 'low' | 'medium' | 'high' | 'xhigh'; budget: false }
   'grok-4.5': { levels: 'low' | 'medium' | 'high'; budget: false }
   'grok-4.6': { levels: 'low' | 'medium' | 'high' | 'xhigh'; budget: false }
-  'grok-build-0.1': {
-    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
-    budget: false
-  }
   'grok-4.3': { levels: 'off' | 'low' | 'medium' | 'high'; budget: false }
   'grok-4.20-reasoning': {
     levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
@@ -62,7 +58,7 @@ export const GROK_MODEL_REASONING: Readonly<Record<string, ModelReasoning>> = {
     },
     budget: false,
   },
-  'grok-build-0.1': { budget: false },
+  'grok-build-0.1': false,
   'grok-4.3': {
     map: {
       off: 'none',
diff --git a/packages/ai-grok/src/text/text-provider-options.ts b/packages/ai-grok/src/text/text-provider-options.ts
index dd430ac96d..abd5166ea4 100644
--- a/packages/ai-grok/src/text/text-provider-options.ts
+++ b/packages/ai-grok/src/text/text-provider-options.ts
@@ -8,15 +8,6 @@
 
 import type { ResponseCreateParams } from 'openai/resources/responses/responses'
 
-export type GrokReasoningEffort = 'none' | 'low' | 'medium' | 'high'
-
-export type GrokReasoning = Omit<
-  NonNullable<ResponseCreateParams['reasoning']>,
-  'effort'
-> & {
-  effort?: GrokReasoningEffort
-}
-
 /**
  * Base provider options for Grok text/chat models
  */
@@ -54,10 +45,6 @@ export interface GrokSamplingOptions {
    * Additional response fields to include. Defaults to encrypted reasoning.
    */
   include?: ResponseCreateParams['include']
-  /**
-   * xAI/OpenAI-compatible reasoning controls for reasoning-capable models.
-   */
-  reasoning?: GrokReasoning
 }
 
 /**
@@ -75,13 +62,6 @@ export interface GrokSamplingOptions {
  */
 export type GrokTextProviderOptions = GrokBaseOptions & GrokSamplingOptions
 
-export type GrokBuildProviderOptions = Omit<
-  GrokTextProviderOptions,
-  'reasoning'
-> & {
-  reasoning?: never
-}
-
 /**
  * External provider options (what users pass in)
  */
diff --git a/packages/ai-grok/tests/grok-adapter.test.ts b/packages/ai-grok/tests/grok-adapter.test.ts
index a88bb7a216..4ceae64146 100644
--- a/packages/ai-grok/tests/grok-adapter.test.ts
+++ b/packages/ai-grok/tests/grok-adapter.test.ts
@@ -208,34 +208,46 @@ describe('Grok adapters', () => {
       })
     })
 
-    it('rejects reasoning options locally for grok-build-0.1', async () => {
-      const adapter = createGrokText('grok-build-0.1', 'test-api-key')
-      const mockCreate = injectMockResponsesClient(adapter, [])
-
-      const chunks: Array<AdapterYieldChunk> = []
-      for await (const chunk of adapter.chatStream({
-        model: 'grok-build-0.1',
-        messages: [{ role: 'user', content: 'Hello' }],
-        modelOptions: {
-          reasoning: { effort: 'high' },
-        } as any,
-        logger: testLogger,
-      })) {
-        chunks.push(chunk)
-      }
+    it('sends reasoning.effort from chat({ reasoning })', async () => {
+      const adapter = createGrokText('grok-4.3', 'test-api-key')
+      const mockCreate = injectMockResponsesClient(adapter, [
+        responseCreated,
+        responseCompleted,
+      ])
 
-      expect(mockCreate).not.toHaveBeenCalled()
-      expect(chunks.some((chunk) => chunk.type === EventType.RUN_ERROR)).toBe(
-        true,
+      await consume(
+        adapter.chatStream({
+          model: 'grok-4.3',
+          messages: [{ role: 'user', content: 'Hello' }],
+          reasoning: { level: 'high', summary: true },
+          logger: testLogger,
+        }),
       )
-      expect(
-        chunks.find((chunk) => chunk.type === EventType.RUN_ERROR),
-      ).toMatchObject({
-        message:
-          'grok-build-0.1 does not support reasoning modelOptions; omit reasoning for this model.',
+
+      expect(mockCreate.mock.calls[0]?.[0]).toMatchObject({
+        reasoning: { effort: 'high', summary: 'auto' },
       })
     })
 
+    it('sends no reasoning for grok-build-0.1, which refuses it', async () => {
+      const adapter = createGrokText('grok-build-0.1', 'test-api-key')
+      const mockCreate = injectMockResponsesClient(adapter, [
+        responseCreated,
+        responseCompleted,
+      ])
+
+      await consume(
+        adapter.chatStream({
+          model: 'grok-build-0.1',
+          messages: [{ role: 'user', content: 'Hello' }],
+          reasoning: { level: 'high', summary: true },
+          logger: testLogger,
+        }),
+      )
+
+      expect(mockCreate.mock.calls[0]?.[0]).not.toHaveProperty('reasoning')
+    })
+
     it('converts function tools to Responses API tools', async () => {
       const adapter = createGrokText('grok-build-0.1', 'test-api-key')
       const mockCreate = injectMockResponsesClient(adapter, [
@@ -569,7 +581,7 @@ describe('Grok adapters', () => {
       // Type-level regression guard: the SummarizeAdapter constraint only
       // instantiates at the summarize() call site, so constructing the adapter
       // (covered above) is not enough. This closure is type-checked but never
-      // executed — passing CI's test:types is the assertion.
+      // executed — passing CI's test:types is the assertion.
       const _typeCheck = () => {
         void summarize({ adapter: grokSummarize('grok-4.3'), text: '' })
         void summarize({ adapter: grokSummarize('grok-build-0.1'), text: '' })
diff --git a/packages/ai-grok/tests/reasoning-types.test-d.ts b/packages/ai-grok/tests/reasoning-types.test-d.ts
new file mode 100644
index 0000000000..c6e261e1d3
--- /dev/null
+++ b/packages/ai-grok/tests/reasoning-types.test-d.ts
@@ -0,0 +1,25 @@
+import { chat } from '@tanstack/ai'
+import { createGrokText } from '../src/adapters/text'
+
+const messages = [{ role: 'user' as const, content: 'hi' }]
+
+// A model's own levels.
+chat({ adapter: createGrokText('grok-4.7', 'k'), messages, reasoning: 'xhigh' })
+chat({ adapter: createGrokText('grok-4.3', 'k'), messages, reasoning: 'off' })
+
+// @ts-expect-error grok-4.7 has no off level
+chat({ adapter: createGrokText('grok-4.7', 'k'), messages, reasoning: 'off' })
+
+chat({
+  adapter: createGrokText('grok-build-0.1', 'k'),
+  messages,
+  // @ts-expect-error the xAI API refuses reasoning for grok-build-0.1
+  reasoning: 'high',
+})
+
+chat({
+  adapter: createGrokText('grok-4.3', 'k'),
+  messages,
+  // @ts-expect-error reasoning lives on chat({ reasoning }), not modelOptions
+  modelOptions: { reasoning: { effort: 'high' } },
+})
diff --git a/scripts/model-sync/reasoning-drift.test.ts b/scripts/model-sync/reasoning-drift.test.ts
index 7be608ef30..42835b652f 100644
--- a/scripts/model-sync/reasoning-drift.test.ts
+++ b/scripts/model-sync/reasoning-drift.test.ts
@@ -10,10 +10,12 @@ import { MISTRAL_MODEL_REASONING } from '../../packages/ai-mistral/src/model-rea
 import { OPENAI_MODEL_REASONING } from '../../packages/ai-openai/src/model-reasoning'
 import { OPENROUTER_MODEL_REASONING } from '../../packages/ai-openrouter/src/model-reasoning'
 import { VERCEL_GATEWAY_MODEL_REASONING } from '../../packages/ai-vercel-gateway/src/model-reasoning'
+import { REASONING_TARGETS } from './reasoning-targets'
 import type { ModelReasoning } from '../../packages/ai/src/reasoning'
 
 // A provider package and the catalog read the same models.dev data. For a
-// model that is in both, the reasoning levels must be the same.
+// model that is in both, the reasoning levels must be the same, unless the
+// package's sync target overrides that model on purpose.
 const PAIRS: ReadonlyArray<
   readonly [string, string, Readonly<Record<string, ModelReasoning>>]
 > = [
@@ -30,11 +32,13 @@ const PAIRS: ReadonlyArray<
 ]
 
 describe('reasoning drift between provider packages and @tanstack/ai-models', () => {
-  it.each(PAIRS)('%s matches the %s catalog', (_pkg, provider, reasoning) => {
+  it.each(PAIRS)('%s matches the %s catalog', (pkg, provider, reasoning) => {
+    const overrides =
+      REASONING_TARGETS.find((target) => target.pkg === pkg)?.overrides ?? {}
     let compared = 0
     for (const [id, own] of Object.entries(reasoning)) {
       const record = getModel(provider, id)
-      if (!record) continue
+      if (!record || id in overrides) continue
       compared++
       const fromCatalog: ModelReasoning = record.reasoning
         ? {
diff --git a/scripts/model-sync/reasoning-targets.ts b/scripts/model-sync/reasoning-targets.ts
index 8e4fe1bd9b..1d9f4fcffc 100644
--- a/scripts/model-sync/reasoning-targets.ts
+++ b/scripts/model-sync/reasoning-targets.ts
@@ -1,3 +1,5 @@
+import type { ModelReasoning } from '../../packages/ai/src/reasoning'
+
 /**
  * The provider packages whose `src/model-reasoning.ts` the reasoning sync
  * writes, and where it finds each package's models on models.dev.
@@ -19,6 +21,11 @@ export interface ReasoningTarget {
   gateway?: 'openrouter' | 'vercel'
   /** Model ids that name another model, as `provider/model`. */
   aliases?: Readonly<Record<string, string>>
+  /**
+   * Corrections that win over models.dev, for one package's API. Keep a
+   * comment on each one that says why.
+   */
+  overrides?: Readonly<Record<string, ModelReasoning>>
 }
 
 export const REASONING_TARGETS: ReadonlyArray<ReasoningTarget> = [
@@ -55,14 +62,8 @@ export const REASONING_TARGETS: ReadonlyArray<ReasoningTarget> = [
     typePrefix: 'Grok',
     constPrefix: 'GROK',
     sources: ['xai'],
-  },
-  {
-    pkg: 'ai-grok-build',
-    models: { module: 'model-meta', lists: ['GROK_BUILD_MODELS'] },
-    typePrefix: 'GrokBuild',
-    constPrefix: 'GROK_BUILD',
-    sources: ['xai'],
-    aliases: { 'grok-build': 'xai/grok-build-0.1' },
+    // The xAI Responses API refuses a reasoning field for grok-build-0.1.
+    overrides: { 'grok-build-0.1': false },
   },
   {
     pkg: 'ai-groq',
diff --git a/scripts/sync-model-reasoning.ts b/scripts/sync-model-reasoning.ts
index d26e860eb3..962caf7cdc 100644
--- a/scripts/sync-model-reasoning.ts
+++ b/scripts/sync-model-reasoning.ts
@@ -186,6 +186,11 @@ async function main() {
     const entries: Array<[string, ModelReasoning]> = []
     let missing = 0
     for (const id of await modelIds(target, dev)) {
+      const override = target.overrides?.[id]
+      if (override !== undefined) {
+        entries.push([id, override])
+        continue
+      }
       const local = target.pkg === 'ai-ollama' ? ollama.get(id) : undefined
       if (local !== undefined) {
         entries.push([id, local])

From 31233686d6d7ea5cd71fd97003801026e6dfb857 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 14:58:13 +0200
Subject: [PATCH 094/286] feat(ai-openrouter)!: map chat({ reasoning }) to
 OpenRouter reasoning

`reasoning` leaves the OpenRouter modelOptions on both adapters, and the
ReasoningOptions type is removed. The adapters read the generated
model-reasoning map:

- chat: `reasoning.effort`, `none` for `off` (pi's rule). The chat
  request schema has no budget field, so the type takes no
  `budgetTokens`.
- Responses: `reasoning.effort`, `summary: 'auto'` when the summary is
  on, and `maxTokens` when the request sets `budgetTokens`.

The OpenRouter model sync stops picking `reasoning` into the per-model
options.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .../src/adapters/responses-text.ts            |  37 +-
 packages/ai-openrouter/src/adapters/text.ts   |  49 +-
 packages/ai-openrouter/src/index.ts           |   1 -
 .../ai-openrouter/src/internal/reasoning.ts   |  14 +
 packages/ai-openrouter/src/model-meta.ts      | 688 ++----------------
 .../src/text/responses-provider-options.ts    |   1 -
 .../src/text/text-provider-options.ts         |  15 +-
 .../tests/openrouter-adapter.test.ts          |  31 +-
 .../openrouter-responses-adapter.test.ts      |  29 +
 .../tests/reasoning-types.test-d.ts           |  32 +
 scripts/convert-openrouter-models.ts          |   3 +-
 11 files changed, 239 insertions(+), 661 deletions(-)
 create mode 100644 packages/ai-openrouter/src/internal/reasoning.ts
 create mode 100644 packages/ai-openrouter/tests/reasoning-types.test-d.ts

diff --git a/packages/ai-openrouter/src/adapters/responses-text.ts b/packages/ai-openrouter/src/adapters/responses-text.ts
index 0824b08d5d..10d5d8fd39 100644
--- a/packages/ai-openrouter/src/adapters/responses-text.ts
+++ b/packages/ai-openrouter/src/adapters/responses-text.ts
@@ -7,6 +7,7 @@ import {
 } from '@tanstack/ai'
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
 import {
+  resolveReasoning,
   toRunErrorPayload,
   toRunErrorRawEvent,
 } from '@tanstack/ai/adapter-internals'
@@ -16,6 +17,8 @@ import { openRouterSupportsCombinedToolsAndSchema } from '../internal/combined-t
 import { makeStructuredOutputCompatible } from '../internal/schema-converter'
 import { convertFunctionToolToResponsesFormat } from '../internal/responses-tool-converter'
 import { OPENROUTER_MODEL_INPUT_MODALITIES } from '../model-meta'
+import { OPENROUTER_MODEL_REASONING } from '../model-reasoning'
+import { openRouterEffort } from '../internal/reasoning'
 import { isWebSearchTool } from '../tools/web-search-tool'
 import { isWebFetchTool } from '../tools/web-fetch-tool'
 import { getOpenRouterApiKeyFromEnv } from '../utils'
@@ -27,6 +30,7 @@ import type {
   InputsUnion,
   OpenResponsesResult,
   OutputItems,
+  ReasoningEffort,
   ResponsesRequest,
   StreamEvents,
 } from '@openrouter/sdk/models'
@@ -42,6 +46,7 @@ import type {
   TextOptions,
 } from '@tanstack/ai'
 import type { ExternalResponsesProviderOptions } from '../text/responses-provider-options'
+import type { OpenRouterModelReasoningByName } from '../model-reasoning'
 import type {
   OPENROUTER_CHAT_MODELS,
   OpenRouterChatModelToolCapabilitiesByName,
@@ -76,6 +81,12 @@ export type OpenRouterResponsesTextModels =
 export type OpenRouterResponsesTextProviderOptions =
   ExternalResponsesProviderOptions
 
+/** The reasoning levels of a model, for `chat({ reasoning })`. `never`: none. */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof OpenRouterModelReasoningByName
+    ? OpenRouterModelReasoningByName[TModel]
+    : never
+
 type ResolveInputModalities<TModel extends string> =
   TModel extends keyof OpenRouterModelInputModalitiesByName
     ? OpenRouterModelInputModalitiesByName[TModel]
@@ -113,7 +124,9 @@ export class OpenRouterResponsesTextAdapter<
   ResolveInputModalities<TModel>,
   OpenRouterMessageMetadataByModality,
   TToolCapabilities,
-  OpenRouterResponsesToolCallMetadata
+  OpenRouterResponsesToolCallMetadata,
+  never,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   readonly name = 'openrouter-responses' as const
@@ -1730,6 +1743,15 @@ export class OpenRouterResponsesTextAdapter<
           )
         : undefined
 
+    // `chat({ reasoning })`: the effort, a summary so the thinking text
+    // streams back, and the token budget when the request sets one.
+    // `ReasoningEffort` is an open enum, so a newer value still goes out.
+    const resolved = resolveReasoning(
+      options.reasoning,
+      OPENROUTER_MODEL_REASONING[this.model],
+    )
+    const effort = openRouterEffort(resolved)
+
     const built: Pick<
       ResponsesRequest,
       | 'model'
@@ -1743,6 +1765,7 @@ export class OpenRouterResponsesTextAdapter<
       | 'toolChoice'
       | 'parallelToolCalls'
       | 'text'
+      | 'reasoning'
     > = {
       ...modelOptions,
       model: options.model + variantSuffix,
@@ -1761,6 +1784,18 @@ export class OpenRouterResponsesTextAdapter<
         tools.length > 0 && {
           tools,
         }),
+      ...(resolved &&
+        effort && {
+          reasoning: {
+            effort: effort as ReasoningEffort,
+            ...(resolved.summary && resolved.level !== 'off'
+              ? { summary: 'auto' as const }
+              : {}),
+            ...(resolved.budgetTokens !== undefined
+              ? { maxTokens: resolved.budgetTokens }
+              : {}),
+          },
+        }),
       ...(combinedSchema && {
         // Merge onto any caller-supplied `text` (spread above via
         // `...modelOptions`) so sibling fields like `text.verbosity` survive;
diff --git a/packages/ai-openrouter/src/adapters/text.ts b/packages/ai-openrouter/src/adapters/text.ts
index ca3d910f12..9debe41cea 100644
--- a/packages/ai-openrouter/src/adapters/text.ts
+++ b/packages/ai-openrouter/src/adapters/text.ts
@@ -7,6 +7,7 @@ import {
 } from '@tanstack/ai'
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
 import {
+  resolveReasoning,
   toRunErrorPayload,
   toRunErrorRawEvent,
 } from '@tanstack/ai/adapter-internals'
@@ -15,6 +16,8 @@ import { extractRequestOptions } from '../internal/request-options'
 import { makeStructuredOutputCompatible } from '../internal/schema-converter'
 import { openRouterSupportsCombinedToolsAndSchema } from '../internal/combined-tools-and-schema'
 import { OPENROUTER_MODEL_INPUT_MODALITIES } from '../model-meta'
+import { OPENROUTER_MODEL_REASONING } from '../model-reasoning'
+import { openRouterEffort } from '../internal/reasoning'
 import { convertToolsToProviderFormat } from '../tools'
 import { getOpenRouterApiKeyFromEnv } from '../utils'
 import { buildOpenRouterUsage } from '../usage'
@@ -25,6 +28,7 @@ import type {
   ChatContentText,
   ChatMessages,
   ChatRequest,
+  ChatRequestEffort,
   ChatStreamChoice,
   ChatStreamChunk,
 } from '@openrouter/sdk/models'
@@ -48,8 +52,8 @@ import type {
 import type {
   ExternalTextProviderOptions,
   OpenRouterSystemPromptMetadata,
-  ReasoningOptions,
 } from '../text/text-provider-options'
+import type { OpenRouterModelReasoningByName } from '../model-reasoning'
 import type {
   OpenRouterImageMetadata,
   OpenRouterMessageMetadataByModality,
@@ -82,21 +86,18 @@ type ResolveToolCapabilities<TModel extends string> =
     ? NonNullable<OpenRouterChatModelToolCapabilitiesByName[TModel]>
     : readonly []
 
-function normalizeReasoningOptions(
-  reasoning: ReasoningOptions | undefined,
-): ChatRequest['reasoning'] | undefined {
-  if (!reasoning) return undefined
-
-  const { enabled, ...sdkReasoning } = reasoning
-  const normalized =
-    enabled === false
-      ? { ...sdkReasoning, effort: 'none' as const }
-      : sdkReasoning
-
-  return Object.values(normalized).some((value) => value !== undefined)
-    ? normalized
-    : undefined
-}
+/**
+ * The reasoning levels of a model, for `chat({ reasoning })`. The chat
+ * request schema has no token budget field, so no model takes
+ * `budgetTokens` here. `never`: the model does not reason.
+ */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof OpenRouterModelReasoningByName
+    ? {
+        levels: OpenRouterModelReasoningByName[TModel]['levels']
+        budget: false
+      }
+    : never
 
 /**
  * OpenRouter Text (Chat) Adapter — standalone implementation that talks to
@@ -135,7 +136,8 @@ export class OpenRouterTextAdapter<
   unknown,
   // TSystemPromptMetadata — narrows `systemPrompts[i].metadata` at the chat()
   // call site so users get `cache_control` autocomplete.
-  OpenRouterSystemPromptMetadata
+  OpenRouterSystemPromptMetadata,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   readonly name = 'openrouter' as const
@@ -1255,10 +1257,17 @@ export class OpenRouterTextAdapter<
     // `variant` is OpenRouter metadata used only to build the `:variant` model
     // suffix — it must NOT be spread into the request body. Destructure it out
     // so the remaining sampling/provider options flow through `...restModelOptions`.
-    const { variant, reasoning, ...restModelOptions } = (options.modelOptions ??
+    const { variant, ...restModelOptions } = (options.modelOptions ??
       {}) as ExternalTextProviderOptions
     const variantSuffix = variant ? `:${variant}` : ''
-    const normalizedReasoning = normalizeReasoningOptions(reasoning)
+    // `chat({ reasoning })`. `ChatRequestEffort` is an open enum, so a newer
+    // effort value still goes out.
+    const effort = openRouterEffort(
+      resolveReasoning(
+        options.reasoning,
+        OPENROUTER_MODEL_REASONING[options.model],
+      ),
+    )
 
     const messages: Array<ChatMessages> = []
     const systemPrompts =
@@ -1321,7 +1330,7 @@ export class OpenRouterTextAdapter<
     // SDK validates `chatRequest.metadata` as `Record<string, string>` (#735).
     const request: Omit<ChatRequest, 'stream'> = {
       ...restModelOptions,
-      ...(normalizedReasoning && { reasoning: normalizedReasoning }),
+      ...(effort && { reasoning: { effort: effort as ChatRequestEffort } }),
       model: options.model + variantSuffix,
       messages,
       ...(tools && tools.length > 0 && { tools }),
diff --git a/packages/ai-openrouter/src/index.ts b/packages/ai-openrouter/src/index.ts
index 55ad8c3347..c1ad22aa01 100644
--- a/packages/ai-openrouter/src/index.ts
+++ b/packages/ai-openrouter/src/index.ts
@@ -113,7 +113,6 @@ export type {
   PluginAutoRouter,
   Plugin,
   ProviderPreferences,
-  ReasoningOptions,
   StreamOptions,
   ImageConfig,
   OpenRouterSystemPromptMetadata,
diff --git a/packages/ai-openrouter/src/internal/reasoning.ts b/packages/ai-openrouter/src/internal/reasoning.ts
new file mode 100644
index 0000000000..f363f356b1
--- /dev/null
+++ b/packages/ai-openrouter/src/internal/reasoning.ts
@@ -0,0 +1,14 @@
+import type { ResolvedReasoning } from '@tanstack/ai/adapter-internals'
+
+/**
+ * The OpenRouter `reasoning.effort` for a resolved `chat({ reasoning })`.
+ * `off` is always `none` on OpenRouter, whatever the model's own off value
+ * is (pi's rule). A model without effort values sends the level name.
+ */
+export function openRouterEffort(
+  resolved: ResolvedReasoning | undefined,
+): string | undefined {
+  if (!resolved) return undefined
+  if (resolved.level === 'off') return 'none'
+  return resolved.value ?? resolved.level
+}
diff --git a/packages/ai-openrouter/src/model-meta.ts b/packages/ai-openrouter/src/model-meta.ts
index abf515ce46..c223b2e7f8 100644
--- a/packages/ai-openrouter/src/model-meta.ts
+++ b/packages/ai-openrouter/src/model-meta.ts
@@ -14791,7 +14791,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'toolChoice'
@@ -14801,7 +14800,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -14813,7 +14811,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -14824,7 +14821,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -14838,7 +14834,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -14855,7 +14850,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -14873,7 +14867,6 @@ export type OpenRouterModelOptionsByName = {
       | 'maxCompletionTokens'
       | 'parallelToolCalls'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -14886,7 +14879,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -14898,7 +14890,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -14914,7 +14905,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -14928,7 +14918,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -14938,7 +14927,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -14948,7 +14936,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -14958,7 +14945,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -14968,7 +14954,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -14978,7 +14963,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'logprobs'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'temperature'
@@ -14995,7 +14979,6 @@ export type OpenRouterModelOptionsByName = {
       | 'maxCompletionTokens'
       | 'parallelToolCalls'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15013,7 +14996,6 @@ export type OpenRouterModelOptionsByName = {
       | 'maxCompletionTokens'
       | 'parallelToolCalls'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15026,7 +15008,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -15036,7 +15017,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -15046,7 +15026,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -15056,7 +15035,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -15066,7 +15044,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -15077,12 +15054,7 @@ export type OpenRouterModelOptionsByName = {
   [AMAZON_NOVA_2_LITE_V1.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'stop'
-      | 'temperature'
-      | 'toolChoice'
-      | 'topP'
+      'maxCompletionTokens' | 'stop' | 'temperature' | 'toolChoice' | 'topP'
     >
   [AMAZON_NOVA_LITE_V1.id]: OpenRouterCommonOptions &
     Pick<
@@ -15124,7 +15096,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'toolChoice'
@@ -15132,18 +15103,13 @@ export type OpenRouterModelOptionsByName = {
   [ANTHROPIC_CLAUDE_FABLE_5_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'stop'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'stop' | 'toolChoice'
     >
   [ANTHROPIC_CLAUDE_FABLE_5_1.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'toolChoice'
@@ -15151,18 +15117,13 @@ export type OpenRouterModelOptionsByName = {
   [ANTHROPIC_CLAUDE_FABLE_5_1_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'stop'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'stop' | 'toolChoice'
     >
   [ANTHROPIC_CLAUDE_HAIKU_4_5.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15173,7 +15134,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15183,18 +15143,12 @@ export type OpenRouterModelOptionsByName = {
   [ANTHROPIC_CLAUDE_OPUS_4_1.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'stop'
-      | 'temperature'
-      | 'toolChoice'
-      | 'topP'
+      'maxCompletionTokens' | 'stop' | 'temperature' | 'toolChoice' | 'topP'
     >
   [ANTHROPIC_CLAUDE_OPUS_4_1_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15205,7 +15159,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15215,7 +15168,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15226,7 +15178,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15237,7 +15188,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15249,7 +15199,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'toolChoice'
@@ -15257,18 +15206,13 @@ export type OpenRouterModelOptionsByName = {
   [ANTHROPIC_CLAUDE_OPUS_4_7_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'stop'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'stop' | 'toolChoice'
     >
   [ANTHROPIC_CLAUDE_OPUS_4_8.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15277,18 +15221,13 @@ export type OpenRouterModelOptionsByName = {
   [ANTHROPIC_CLAUDE_OPUS_4_8_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'stop'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'stop' | 'toolChoice'
     >
   [ANTHROPIC_CLAUDE_OPUS_5.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15297,18 +15236,13 @@ export type OpenRouterModelOptionsByName = {
   [ANTHROPIC_CLAUDE_OPUS_5_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'stop'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'stop' | 'toolChoice'
     >
   [ANTHROPIC_CLAUDE_OPUS_5_5.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15317,28 +15251,18 @@ export type OpenRouterModelOptionsByName = {
   [ANTHROPIC_CLAUDE_OPUS_5_5_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'stop'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'stop' | 'toolChoice'
     >
   [ANTHROPIC_CLAUDE_SONNET_4.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'stop'
-      | 'temperature'
-      | 'toolChoice'
-      | 'topP'
+      'maxCompletionTokens' | 'stop' | 'temperature' | 'toolChoice' | 'topP'
     >
   [ANTHROPIC_CLAUDE_SONNET_4_5.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15349,7 +15273,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15361,7 +15284,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15372,7 +15294,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15384,7 +15305,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'toolChoice'
@@ -15392,18 +15312,13 @@ export type OpenRouterModelOptionsByName = {
   [ANTHROPIC_CLAUDE_SONNET_5_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'stop'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'stop' | 'toolChoice'
     >
   [ANTHROPIC_CLAUDE_SONNET_5_5.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15412,20 +15327,12 @@ export type OpenRouterModelOptionsByName = {
   [ANTHROPIC_CLAUDE_SONNET_5_5_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'stop'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'stop' | 'toolChoice'
     >
   [ARCEE_AI_TRINITY_LARGE_THINKING.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'temperature'
-      | 'toolChoice'
-      | 'topP'
+      'maxCompletionTokens' | 'temperature' | 'toolChoice' | 'topP'
     >
   [BAIDU_ERNIE_4_5_VL_424B_A47B.id]: OpenRouterCommonOptions &
     Pick<
@@ -15433,7 +15340,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'seed'
       | 'stop'
       | 'temperature'
@@ -15444,7 +15350,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15456,7 +15361,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15468,7 +15372,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15480,7 +15383,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15492,7 +15394,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15504,7 +15405,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15554,7 +15454,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15605,7 +15504,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'seed'
       | 'stop'
       | 'temperature'
@@ -15647,7 +15545,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15662,7 +15559,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15678,7 +15574,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15694,7 +15589,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15710,7 +15604,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15727,7 +15620,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15745,7 +15637,6 @@ export type OpenRouterModelOptionsByName = {
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15763,7 +15654,6 @@ export type OpenRouterModelOptionsByName = {
       | 'maxCompletionTokens'
       | 'parallelToolCalls'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15780,7 +15670,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15798,7 +15687,6 @@ export type OpenRouterModelOptionsByName = {
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15815,7 +15703,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15832,7 +15719,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15848,7 +15734,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15860,7 +15745,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -15874,7 +15758,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -15886,7 +15769,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15908,7 +15790,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15920,7 +15801,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15932,7 +15812,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15944,7 +15823,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15956,7 +15834,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15968,7 +15845,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15980,7 +15856,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -15992,7 +15867,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16004,7 +15878,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16016,7 +15889,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16026,28 +15898,17 @@ export type OpenRouterModelOptionsByName = {
   [GOOGLE_GEMINI_3_1_FLASH_IMAGE.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'temperature'
-      | 'topP'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'temperature' | 'topP'
     >
   [GOOGLE_GEMINI_3_1_FLASH_IMAGE_PREVIEW.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'temperature'
-      | 'topP'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'temperature' | 'topP'
     >
   [GOOGLE_GEMINI_3_1_FLASH_LITE.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16058,18 +15919,12 @@ export type OpenRouterModelOptionsByName = {
   [GOOGLE_GEMINI_3_1_FLASH_LITE_IMAGE.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'temperature'
-      | 'topP'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'temperature' | 'topP'
     >
   [GOOGLE_GEMINI_3_1_FLASH_LITE_PREVIEW.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'temperature'
@@ -16080,7 +15935,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16092,7 +15946,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16104,7 +15957,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'temperature'
@@ -16115,7 +15967,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16127,7 +15978,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16139,7 +15989,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16150,18 +15999,12 @@ export type OpenRouterModelOptionsByName = {
   [GOOGLE_GEMINI_3_5_FLASH_LITE_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'stop'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'stop' | 'toolChoice'
     >
   [GOOGLE_GEMINI_3_5_FLASH_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16173,7 +16016,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16184,18 +16026,12 @@ export type OpenRouterModelOptionsByName = {
   [GOOGLE_GEMINI_3_6_FLASH_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'stop'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'stop' | 'toolChoice'
     >
   [GOOGLE_GEMINI_3_7_FLASH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16206,18 +16042,12 @@ export type OpenRouterModelOptionsByName = {
   [GOOGLE_GEMINI_3_7_FLASH_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'stop'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'stop' | 'toolChoice'
     >
   [GOOGLE_GEMINI_3_8_FLASH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16228,12 +16058,7 @@ export type OpenRouterModelOptionsByName = {
   [GOOGLE_GEMINI_3_8_FLASH_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'stop'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'stop' | 'toolChoice'
     >
   [GOOGLE_GEMMA_2_27B_IT.id]: OpenRouterCommonOptions &
     Pick<
@@ -16298,7 +16123,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16311,7 +16135,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'temperature'
@@ -16326,7 +16149,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16339,7 +16161,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'temperature'
@@ -16394,7 +16215,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16407,7 +16227,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -16417,7 +16236,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -16431,7 +16249,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16448,7 +16265,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'seed'
       | 'stop'
       | 'temperature'
@@ -16463,7 +16279,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'seed'
       | 'stop'
       | 'temperature'
@@ -16479,7 +16294,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16536,7 +16350,6 @@ export type OpenRouterModelOptionsByName = {
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16567,7 +16380,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'seed'
       | 'stop'
       | 'temperature'
@@ -16695,7 +16507,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16707,7 +16518,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -16717,7 +16527,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -16727,7 +16536,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -16737,7 +16545,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -16747,7 +16554,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -16786,7 +16592,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'seed'
       | 'stop'
       | 'temperature'
@@ -16800,7 +16605,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16817,7 +16621,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16833,7 +16636,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16850,7 +16652,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -16867,7 +16668,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -17038,7 +16838,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -17052,7 +16851,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -17134,7 +16932,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -17148,7 +16945,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -17245,7 +17041,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -17262,7 +17057,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -17280,7 +17074,6 @@ export type OpenRouterModelOptionsByName = {
       | 'maxCompletionTokens'
       | 'parallelToolCalls'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -17298,7 +17091,6 @@ export type OpenRouterModelOptionsByName = {
       | 'maxCompletionTokens'
       | 'parallelToolCalls'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -17315,7 +17107,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -17331,7 +17122,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -17356,7 +17146,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'logprobs'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'temperature'
       | 'topLogprobs'
       | 'topP'
@@ -17366,7 +17155,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'logprobs'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'temperature'
       | 'toolChoice'
       | 'topLogprobs'
@@ -17403,7 +17191,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'topP'
@@ -17416,7 +17203,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -17428,12 +17214,7 @@ export type OpenRouterModelOptionsByName = {
   [NVIDIA_NEMOTRON_3_NANO_OMNI_30B_A3B_REASONING_FREE.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'seed'
-      | 'temperature'
-      | 'toolChoice'
-      | 'topP'
+      'maxCompletionTokens' | 'seed' | 'temperature' | 'toolChoice' | 'topP'
     >
   [NVIDIA_NEMOTRON_3_SUPER_120B_A12B.id]: OpenRouterCommonOptions &
     Pick<
@@ -17443,7 +17224,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -17456,7 +17236,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'temperature'
@@ -17470,7 +17249,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -17481,12 +17259,7 @@ export type OpenRouterModelOptionsByName = {
   [NVIDIA_NEMOTRON_3_ULTRA_550B_A55B_FREE.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'seed'
-      | 'temperature'
-      | 'toolChoice'
-      | 'topP'
+      'maxCompletionTokens' | 'seed' | 'temperature' | 'toolChoice' | 'topP'
     >
   [NVIDIA_NEMOTRON_3_5_CONTENT_SAFETY.id]: OpenRouterCommonOptions &
     Pick<
@@ -17495,7 +17268,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'seed'
       | 'stop'
       | 'temperature'
@@ -17504,7 +17276,7 @@ export type OpenRouterModelOptionsByName = {
   [NVIDIA_NEMOTRON_3_5_CONTENT_SAFETY_FREE.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      'maxCompletionTokens' | 'reasoning' | 'seed' | 'temperature' | 'topP'
+      'maxCompletionTokens' | 'seed' | 'temperature' | 'topP'
     >
   [NVIDIA_NEMOTRON_3_5_LIGHTNING.id]: OpenRouterCommonOptions &
     Pick<
@@ -17514,7 +17286,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -17526,12 +17297,7 @@ export type OpenRouterModelOptionsByName = {
   [NVIDIA_NEMOTRON_3_5_LIGHTNING_FREE.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'seed'
-      | 'temperature'
-      | 'toolChoice'
-      | 'topP'
+      'maxCompletionTokens' | 'seed' | 'temperature' | 'toolChoice' | 'topP'
     >
   [OPENAI_GPT_3_5_TURBO.id]: OpenRouterCommonOptions &
     Pick<
@@ -17862,7 +17628,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -17875,7 +17640,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -17891,7 +17655,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -17904,7 +17667,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -17912,18 +17674,13 @@ export type OpenRouterModelOptionsByName = {
   [OPENAI_GPT_5_MINI_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_NANO.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -17931,45 +17688,28 @@ export type OpenRouterModelOptionsByName = {
   [OPENAI_GPT_5_NANO_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_PRO.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_PRO_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_1.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -17977,45 +17717,28 @@ export type OpenRouterModelOptionsByName = {
   [OPENAI_GPT_5_1_CODEX.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_1_CODEX_MAX.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_1_CODEX_MINI.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_1_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_2.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18028,45 +17751,28 @@ export type OpenRouterModelOptionsByName = {
   [OPENAI_GPT_5_2_CODEX.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_2_PRO.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_2_PRO_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_2_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_3_CODEX.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18076,7 +17782,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18089,7 +17794,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -18100,7 +17804,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18108,18 +17811,13 @@ export type OpenRouterModelOptionsByName = {
   [OPENAI_GPT_5_4_MINI_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_4_NANO.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18127,18 +17825,13 @@ export type OpenRouterModelOptionsByName = {
   [OPENAI_GPT_5_4_NANO_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_4_PRO.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18146,27 +17839,18 @@ export type OpenRouterModelOptionsByName = {
   [OPENAI_GPT_5_4_PRO_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_4_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_5.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18174,36 +17858,23 @@ export type OpenRouterModelOptionsByName = {
   [OPENAI_GPT_5_5_PRO.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_5_PRO_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_5_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_6_LUNA.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18213,7 +17884,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18221,27 +17891,18 @@ export type OpenRouterModelOptionsByName = {
   [OPENAI_GPT_5_6_LUNA_PRO_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_6_LUNA_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_6_SOL.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18251,7 +17912,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18259,27 +17919,18 @@ export type OpenRouterModelOptionsByName = {
   [OPENAI_GPT_5_6_SOL_PRO_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_6_SOL_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_6_TERRA.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18289,7 +17940,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18297,27 +17947,18 @@ export type OpenRouterModelOptionsByName = {
   [OPENAI_GPT_5_6_TERRA_PRO_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_5_6_TERRA_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_6_ASTRA.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18327,7 +17968,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18335,27 +17975,18 @@ export type OpenRouterModelOptionsByName = {
   [OPENAI_GPT_6_ASTRA_PRO_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_6_ASTRA_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_6_LUNA.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18365,7 +17996,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18373,27 +18003,18 @@ export type OpenRouterModelOptionsByName = {
   [OPENAI_GPT_6_LUNA_PRO_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_6_LUNA_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_6_SOL.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18403,7 +18024,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18411,27 +18031,18 @@ export type OpenRouterModelOptionsByName = {
   [OPENAI_GPT_6_SOL_PRO_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_6_SOL_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_6_1_SOL.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18441,7 +18052,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'toolChoice'
@@ -18449,20 +18059,12 @@ export type OpenRouterModelOptionsByName = {
   [OPENAI_GPT_6_1_SOL_PRO_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_6_1_SOL_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_GPT_AUDIO.id]: OpenRouterCommonOptions &
     Pick<
@@ -18509,7 +18111,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -18525,7 +18126,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -18541,7 +18141,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -18557,7 +18156,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -18569,7 +18167,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -18580,97 +18177,57 @@ export type OpenRouterModelOptionsByName = {
   [OPENAI_O1.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_O1_PRO.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      'maxCompletionTokens' | 'reasoning' | 'responseFormat' | 'seed'
+      'maxCompletionTokens' | 'responseFormat' | 'seed'
     >
   [OPENAI_O3.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_O3_MINI.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_O3_MINI_HIGH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_O3_MINI_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_O3_PRO.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_O3_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_O4_MINI.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_O4_MINI_HIGH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [OPENAI_O4_MINI_BATCH.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'responseFormat'
-      | 'seed'
-      | 'toolChoice'
+      'maxCompletionTokens' | 'responseFormat' | 'seed' | 'toolChoice'
     >
   [PERCEPTRON_PERCEPTRON_MK1.id]: OpenRouterCommonOptions &
     Pick<
@@ -18678,7 +18235,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'temperature'
       | 'topP'
     >
@@ -18688,7 +18244,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'temperature'
       | 'toolChoice'
       | 'topP'
@@ -18708,7 +18263,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'temperature'
       | 'topP'
     >
@@ -18727,7 +18281,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'temperature'
       | 'topP'
     >
@@ -18737,29 +18290,28 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'temperature'
       | 'topP'
     >
   [POOLSIDE_LAGUNA_S_2_1.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      'maxCompletionTokens' | 'reasoning' | 'temperature' | 'toolChoice'
+      'maxCompletionTokens' | 'temperature' | 'toolChoice'
     >
   [POOLSIDE_LAGUNA_S_2_1_FREE.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      'maxCompletionTokens' | 'reasoning' | 'temperature' | 'toolChoice'
+      'maxCompletionTokens' | 'temperature' | 'toolChoice'
     >
   [POOLSIDE_LAGUNA_XS_2_1.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      'maxCompletionTokens' | 'reasoning' | 'temperature' | 'toolChoice'
+      'maxCompletionTokens' | 'temperature' | 'toolChoice'
     >
   [POOLSIDE_LAGUNA_XS_2_1_FREE.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      'maxCompletionTokens' | 'reasoning' | 'temperature' | 'toolChoice'
+      'maxCompletionTokens' | 'temperature' | 'toolChoice'
     >
   [PRISM_ML_TERNARY_BONSAI_2_27B.id]: OpenRouterCommonOptions &
     Pick<
@@ -18768,7 +18320,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -18870,7 +18421,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -18885,7 +18435,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -18916,7 +18465,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -18932,7 +18480,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -18962,7 +18509,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -18977,7 +18523,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -18991,7 +18536,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19098,7 +18642,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19130,7 +18673,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19162,7 +18704,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19194,7 +18735,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19241,7 +18781,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19258,7 +18797,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19275,7 +18813,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19292,7 +18829,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19309,7 +18845,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19326,7 +18861,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19341,7 +18875,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19356,7 +18889,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19372,7 +18904,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19389,7 +18920,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19406,7 +18936,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19422,7 +18951,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19438,7 +18966,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19454,7 +18981,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19469,7 +18995,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'temperature'
@@ -19484,7 +19009,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19500,7 +19024,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19517,7 +19040,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19534,7 +19056,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19549,7 +19070,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'stop'
       | 'temperature'
       | 'toolChoice'
@@ -19562,7 +19082,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19578,7 +19097,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19594,7 +19112,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19610,7 +19127,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19640,7 +19156,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'seed'
       | 'stop'
       | 'temperature'
@@ -19661,13 +19176,13 @@ export type OpenRouterModelOptionsByName = {
       | 'topP'
     >
   [SAKANA_FUGU_MAX.id]: OpenRouterCommonOptions &
-    Pick<OpenRouterBaseOptions, 'reasoning' | 'toolChoice'>
+    Pick<OpenRouterBaseOptions, 'toolChoice'>
   [SAKANA_FUGU_ULTRA.id]: OpenRouterCommonOptions &
-    Pick<OpenRouterBaseOptions, 'reasoning' | 'toolChoice'>
+    Pick<OpenRouterBaseOptions, 'toolChoice'>
   [SAKANA_FUGU_ULTRA_V2.id]: OpenRouterCommonOptions &
-    Pick<OpenRouterBaseOptions, 'reasoning' | 'toolChoice'>
+    Pick<OpenRouterBaseOptions, 'toolChoice'>
   [SAKANA_SAKANA_NAMAZU.id]: OpenRouterCommonOptions &
-    Pick<OpenRouterBaseOptions, 'reasoning' | 'toolChoice'>
+    Pick<OpenRouterBaseOptions, 'toolChoice'>
   [SAO10K_L3_LUNARIS_8B.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
@@ -19714,7 +19229,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -19725,7 +19239,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'temperature'
       | 'toolChoice'
       | 'topP'
@@ -19738,7 +19251,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19752,7 +19264,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'topP'
@@ -19788,7 +19299,6 @@ export type OpenRouterModelOptionsByName = {
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19799,12 +19309,7 @@ export type OpenRouterModelOptionsByName = {
   [TENCENT_HY3_PREVIEW.id]: OpenRouterCommonOptions &
     Pick<
       OpenRouterBaseOptions,
-      | 'maxCompletionTokens'
-      | 'reasoning'
-      | 'seed'
-      | 'temperature'
-      | 'toolChoice'
-      | 'topP'
+      'maxCompletionTokens' | 'seed' | 'temperature' | 'toolChoice' | 'topP'
     >
   [TENCENT_HY4_PREVIEW.id]: OpenRouterCommonOptions &
     Pick<
@@ -19814,7 +19319,6 @@ export type OpenRouterModelOptionsByName = {
       | 'maxCompletionTokens'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -19873,7 +19377,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'seed'
       | 'stop'
       | 'temperature'
@@ -19887,7 +19390,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'seed'
       | 'stop'
       | 'temperature'
@@ -19900,7 +19402,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'seed'
       | 'stop'
       | 'temperature'
@@ -19912,7 +19413,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'seed'
       | 'stop'
       | 'temperature'
@@ -19949,7 +19449,6 @@ export type OpenRouterModelOptionsByName = {
       | 'maxCompletionTokens'
       | 'parallelToolCalls'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -19962,7 +19461,6 @@ export type OpenRouterModelOptionsByName = {
       | 'maxCompletionTokens'
       | 'parallelToolCalls'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -19975,7 +19473,6 @@ export type OpenRouterModelOptionsByName = {
       | 'maxCompletionTokens'
       | 'parallelToolCalls'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -19991,7 +19488,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'logprobs'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'temperature'
@@ -20004,7 +19500,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'logprobs'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'temperature'
@@ -20016,7 +19511,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'logprobs'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'temperature'
@@ -20029,7 +19523,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'logprobs'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'temperature'
@@ -20042,7 +19535,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'logprobs'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'temperature'
@@ -20055,7 +19547,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'logprobs'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20069,7 +19560,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'logprobs'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'temperature'
@@ -20082,7 +19572,6 @@ export type OpenRouterModelOptionsByName = {
       OpenRouterBaseOptions,
       | 'logprobs'
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'temperature'
@@ -20096,7 +19585,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20111,7 +19599,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20127,7 +19614,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20142,7 +19628,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20156,7 +19641,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'stop'
       | 'temperature'
@@ -20167,7 +19651,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -20179,7 +19662,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'seed'
       | 'stop'
       | 'temperature'
@@ -20192,7 +19674,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20207,7 +19688,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20221,7 +19701,6 @@ export type OpenRouterModelOptionsByName = {
       | 'frequencyPenalty'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20236,7 +19715,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20252,7 +19730,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20268,7 +19745,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20281,7 +19757,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -20295,7 +19770,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20313,7 +19787,6 @@ export type OpenRouterModelOptionsByName = {
       | 'maxCompletionTokens'
       | 'parallelToolCalls'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20331,7 +19804,6 @@ export type OpenRouterModelOptionsByName = {
       | 'maxCompletionTokens'
       | 'parallelToolCalls'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20349,7 +19821,6 @@ export type OpenRouterModelOptionsByName = {
       | 'maxCompletionTokens'
       | 'parallelToolCalls'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20365,7 +19836,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20377,7 +19847,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
@@ -20390,7 +19859,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logprobs'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20406,7 +19874,6 @@ export type OpenRouterModelOptionsByName = {
       | 'logitBias'
       | 'maxCompletionTokens'
       | 'presencePenalty'
-      | 'reasoning'
       | 'responseFormat'
       | 'seed'
       | 'stop'
@@ -20418,7 +19885,6 @@ export type OpenRouterModelOptionsByName = {
     Pick<
       OpenRouterBaseOptions,
       | 'maxCompletionTokens'
-      | 'reasoning'
       | 'responseFormat'
       | 'temperature'
       | 'toolChoice'
diff --git a/packages/ai-openrouter/src/text/responses-provider-options.ts b/packages/ai-openrouter/src/text/responses-provider-options.ts
index af4f9f8724..0d885992f1 100644
--- a/packages/ai-openrouter/src/text/responses-provider-options.ts
+++ b/packages/ai-openrouter/src/text/responses-provider-options.ts
@@ -46,7 +46,6 @@ export type OpenRouterResponsesBaseOptions = Pick<
   | 'topLogprobs'
   | 'frequencyPenalty'
   | 'presencePenalty'
-  | 'reasoning'
   | 'toolChoice'
   | 'parallelToolCalls'
   | 'text'
diff --git a/packages/ai-openrouter/src/text/text-provider-options.ts b/packages/ai-openrouter/src/text/text-provider-options.ts
index 9bf682c175..83604ddc49 100644
--- a/packages/ai-openrouter/src/text/text-provider-options.ts
+++ b/packages/ai-openrouter/src/text/text-provider-options.ts
@@ -26,17 +26,6 @@ export type PluginAutoRouter = Extract<Plugin, { id: 'auto-router' }>
 
 export type PdfParserOptions = NonNullable<PluginFileParser['pdf']>
 
-export type ReasoningOptions = NonNullable<ChatRequest['reasoning']> & {
-  /**
-   * Disable reasoning for this request.
-   *
-   * OpenRouter documents `enabled: false`, but the SDK's chat request schema
-   * currently strips that field. The adapter normalizes this explicit opt-out
-   * to `effort: 'none'`, which the SDK preserves on the wire.
-   */
-  enabled?: false
-}
-
 export type StreamOptions = NonNullable<ChatRequest['streamOptions']>
 
 // ---------------------------------------------------------------------------
@@ -95,9 +84,7 @@ export type OpenRouterBaseOptions = Pick<
   | 'responseFormat'
   | 'toolChoice'
   | 'parallelToolCalls'
-> & {
-  reasoning?: ReasoningOptions
-}
+>
 
 export type ExternalTextProviderOptions = OpenRouterCommonOptions &
   OpenRouterBaseOptions
diff --git a/packages/ai-openrouter/tests/openrouter-adapter.test.ts b/packages/ai-openrouter/tests/openrouter-adapter.test.ts
index 9ad0edf71b..0fc8b11231 100644
--- a/packages/ai-openrouter/tests/openrouter-adapter.test.ts
+++ b/packages/ai-openrouter/tests/openrouter-adapter.test.ts
@@ -1903,18 +1903,14 @@ describe('OpenRouter modelOptions pass-through', () => {
     expect(params.maxCompletionTokens).toBe(64)
   })
 
-  it('normalizes reasoning enabled false to effort none on the wire (#1006)', async () => {
+  it('sends effort none for reasoning off (#1006)', async () => {
     setupMockSdkClient(minimalStreamChunks)
-    const adapter = createAdapter()
-
-    const modelOptions: OpenRouterTextModelOptions = {
-      reasoning: { enabled: false },
-    }
+    const adapter = createOpenRouterText('deepseek/deepseek-r1', 'test-key')
 
     for await (const _ of chat({
       adapter,
       messages: [{ role: 'user', content: 'test' }],
-      modelOptions,
+      reasoning: 'off',
     })) {
       // consume
     }
@@ -1927,18 +1923,29 @@ describe('OpenRouter modelOptions pass-through', () => {
     expect(serialized.reasoning).toEqual({ effort: 'none' })
   })
 
-  it('omits an empty reasoning object from the SDK request (#1006)', async () => {
+  it('sends the level effort from chat({ reasoning })', async () => {
     setupMockSdkClient(minimalStreamChunks)
-    const adapter = createAdapter()
+    const adapter = createOpenRouterText('openai/gpt-5.5', 'test-key')
 
-    const modelOptions: OpenRouterTextModelOptions = {
-      reasoning: {},
+    for await (const _ of chat({
+      adapter,
+      messages: [{ role: 'user', content: 'test' }],
+      reasoning: 'xhigh',
+    })) {
+      // consume
     }
 
+    const [rawParams] = mockSend.mock.calls[0]!
+    expect(rawParams.chatRequest.reasoning).toEqual({ effort: 'xhigh' })
+  })
+
+  it('omits reasoning from the SDK request without a reasoning option (#1006)', async () => {
+    setupMockSdkClient(minimalStreamChunks)
+    const adapter = createAdapter()
+
     for await (const _ of chat({
       adapter,
       messages: [{ role: 'user', content: 'test' }],
-      modelOptions,
     })) {
       // consume
     }
diff --git a/packages/ai-openrouter/tests/openrouter-responses-adapter.test.ts b/packages/ai-openrouter/tests/openrouter-responses-adapter.test.ts
index e865a8142e..c6399b62c5 100644
--- a/packages/ai-openrouter/tests/openrouter-responses-adapter.test.ts
+++ b/packages/ai-openrouter/tests/openrouter-responses-adapter.test.ts
@@ -96,6 +96,35 @@ describe('OpenRouter responses adapter — request shape', () => {
     vi.clearAllMocks()
   })
 
+  it('sends reasoning effort, a summary, and the token budget', async () => {
+    setupMockSdkClient([])
+    const adapter = createOpenRouterResponsesText(
+      'google/gemini-2.5-pro',
+      'test-key',
+    )
+
+    for await (const _ of chat({
+      adapter,
+      messages: [{ role: 'user', content: 'test' }],
+      reasoning: { level: 'high', budgetTokens: 4000 },
+    })) {
+      // consume
+    }
+
+    const params = mockSend.mock.calls[0]![0].responsesRequest
+    expect(params.reasoning).toEqual({
+      effort: 'high',
+      summary: 'auto',
+      maxTokens: 4000,
+    })
+    const serialized = ResponsesRequest$outboundSchema.parse(params)
+    expect(serialized.reasoning).toEqual({
+      effort: 'high',
+      summary: 'auto',
+      max_tokens: 4000,
+    })
+  })
+
   it('maps options into the Responses API payload (snake → camel)', async () => {
     setupMockSdkClient([
       {
diff --git a/packages/ai-openrouter/tests/reasoning-types.test-d.ts b/packages/ai-openrouter/tests/reasoning-types.test-d.ts
new file mode 100644
index 0000000000..f7c20f4ad8
--- /dev/null
+++ b/packages/ai-openrouter/tests/reasoning-types.test-d.ts
@@ -0,0 +1,32 @@
+import { chat } from '@tanstack/ai'
+import { createOpenRouterText } from '../src/adapters/text'
+import { createOpenRouterResponsesText } from '../src/adapters/responses-text'
+
+const messages = [{ role: 'user' as const, content: 'hi' }]
+
+chat({
+  adapter: createOpenRouterText('openai/gpt-5.5', 'k'),
+  messages,
+  reasoning: 'xhigh',
+})
+
+chat({
+  adapter: createOpenRouterText('google/gemini-2.5-pro', 'k'),
+  messages,
+  // @ts-expect-error the chat request schema has no token budget field
+  reasoning: { level: 'high', budgetTokens: 4000 },
+})
+
+// The Responses API takes the budget.
+chat({
+  adapter: createOpenRouterResponsesText('google/gemini-2.5-pro', 'k'),
+  messages,
+  reasoning: { level: 'high', budgetTokens: 4000 },
+})
+
+chat({
+  adapter: createOpenRouterText('openai/gpt-5.5', 'k'),
+  messages,
+  // @ts-expect-error reasoning lives on chat({ reasoning }), not modelOptions
+  modelOptions: { reasoning: { effort: 'high' } },
+})
diff --git a/scripts/convert-openrouter-models.ts b/scripts/convert-openrouter-models.ts
index 1239398bdc..3f2ad0cf8b 100644
--- a/scripts/convert-openrouter-models.ts
+++ b/scripts/convert-openrouter-models.ts
@@ -358,7 +358,8 @@ function generateModelMetaString(model: OpenRouterModel): string {
   const supportedParams =
     model.supported_parameters
       ?.map((p) => {
-        if (excludedParams.has(p)) return ''
+        // `chat({ reasoning })` owns reasoning, so it is not a model option.
+        if (excludedParams.has(p) || p === 'reasoning') return ''
         const mapped = paramNameMap[p] ?? p
         return `'${mapped}'`
       })

From e437a7ba3ac2443d8d9268d65f0c00db283608d3 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 15:11:08 +0200
Subject: [PATCH 095/286] feat(gateways)!: map chat({ reasoning }) on the
 gateway adapters

Reasoning fields leave modelOptions on Vercel AI Gateway, Lovable, and
LLM Gateway. Each adapter reads its generated model-reasoning map:

- Vercel AI Gateway chat: its documented `reasoning` object:
  `{ effort }`, `{ enabled: false }` for `off`, `{ enabled: true,
  max_tokens }` for a budget, `exclude: true` when the summary is off
- Vercel AI Gateway Responses, Lovable (both APIs), LLM Gateway: the
  openai-base hook, so `reasoning_effort` or `reasoning.effort`; these
  types take no `budgetTokens`
- OpenCode: the per-model `options` in the server config, from its docs:
  `thinking` with a budget for Claude, `reasoningEffort` and
  `reasoningSummary` for other models

The Vercel model sync stops picking reasoning params into the per-model
options.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-llmgateway/src/adapters/text.ts   |  22 +-
 .../src/text/text-provider-options.ts         |  18 -
 .../tests/llmgateway-adapter.test.ts          |   4 +-
 .../ai-lovable/src/adapters/responses-text.ts |  19 +-
 packages/ai-lovable/src/adapters/text.ts      |  19 +-
 .../src/text/text-provider-options.ts         |   2 -
 .../tests/reasoning-request.test.ts           |  46 ++
 packages/ai-opencode/src/adapters/text.ts     |  96 ++-
 .../tests/reasoning-options.test.ts           |  50 ++
 .../src/adapters/responses-text.ts            |  22 +-
 .../ai-vercel-gateway/src/adapters/text.ts    |  35 +-
 packages/ai-vercel-gateway/src/model-meta.ts  | 674 ++----------------
 .../src/text/text-provider-options.ts         |   2 -
 .../tests/reasoning-request.test.ts           |  73 ++
 scripts/convert-vercel-gateway-models.ts      |  11 +-
 15 files changed, 414 insertions(+), 679 deletions(-)
 create mode 100644 packages/ai-lovable/tests/reasoning-request.test.ts
 create mode 100644 packages/ai-opencode/tests/reasoning-options.test.ts
 create mode 100644 packages/ai-vercel-gateway/tests/reasoning-request.test.ts

diff --git a/packages/ai-llmgateway/src/adapters/text.ts b/packages/ai-llmgateway/src/adapters/text.ts
index c7c04fe757..6a58358e58 100644
--- a/packages/ai-llmgateway/src/adapters/text.ts
+++ b/packages/ai-llmgateway/src/adapters/text.ts
@@ -1,6 +1,8 @@
 import OpenAI from 'openai'
 import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
 import { LLMGATEWAY_MODEL_INPUT_MODALITIES } from '../model-meta'
+import { LLMGATEWAY_MODEL_REASONING } from '../model-reasoning'
+import type { LLMGatewayModelReasoningByName } from '../model-reasoning'
 import {
   getLLMGatewayApiKeyFromEnv,
   withLLMGatewayDefaults,
@@ -16,6 +18,19 @@ import type { LLMGatewayMessageMetadataByModality } from '../message-types'
 import type { LLMGatewayClientConfig } from '../utils/client'
 import type { OpenAIBaseTextAdapterOptions } from '@tanstack/openai-base'
 
+/**
+ * The reasoning levels of a model, for `chat({ reasoning })`. This API has
+ * no token budget field, so no model takes `budgetTokens` here. `never`:
+ * the model does not reason.
+ */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof LLMGatewayModelReasoningByName
+    ? {
+        levels: LLMGatewayModelReasoningByName[TModel]['levels']
+        budget: false
+      }
+    : never
+
 type ResolveToolCapabilities<TModel extends string> =
   TModel extends keyof LLMGatewayChatModelToolCapabilitiesByName
     ? NonNullable<LLMGatewayChatModelToolCapabilitiesByName[TModel]>
@@ -58,7 +73,8 @@ export class LLMGatewayTextAdapter<
   TProviderOptions,
   TInputModalities,
   LLMGatewayMessageMetadataByModality,
-  TToolCapabilities
+  TToolCapabilities,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   override readonly name = 'llmgateway' as const
@@ -74,6 +90,10 @@ export class LLMGatewayTextAdapter<
     )
   }
 
+  protected override modelReasoning(model: string) {
+    return LLMGATEWAY_MODEL_REASONING[model]
+  }
+
   /**
    * Surfaces reasoning deltas during streaming. LLM Gateway normalizes
    * upstream reasoning output to `delta.reasoning_content` on the OpenAI
diff --git a/packages/ai-llmgateway/src/text/text-provider-options.ts b/packages/ai-llmgateway/src/text/text-provider-options.ts
index aaac987112..796f7a60b1 100644
--- a/packages/ai-llmgateway/src/text/text-provider-options.ts
+++ b/packages/ai-llmgateway/src/text/text-provider-options.ts
@@ -46,24 +46,6 @@ export interface LLMGatewayTextProviderOptions {
    */
   presence_penalty?: number | null
 
-  /**
-   * Controls reasoning effort for reasoning-capable models.
-   *
-   * The gateway accepts the extended effort scale in addition to OpenAI's
-   * `low` / `medium` / `high`; which tiers a given model honors depends on
-   * the model and the provider it is routed to. See the model's page on
-   * https://llmgateway.io/models for the tiers it supports.
-   */
-  reasoning_effort?:
-    | 'none'
-    | 'minimal'
-    | 'low'
-    | 'medium'
-    | 'high'
-    | 'xhigh'
-    | 'max'
-    | null
-
   /**
    * An object specifying the format that the model must output.
    *
diff --git a/packages/ai-llmgateway/tests/llmgateway-adapter.test.ts b/packages/ai-llmgateway/tests/llmgateway-adapter.test.ts
index 62f9f7f2aa..7800263128 100644
--- a/packages/ai-llmgateway/tests/llmgateway-adapter.test.ts
+++ b/packages/ai-llmgateway/tests/llmgateway-adapter.test.ts
@@ -174,7 +174,7 @@ describe('LLM Gateway adapters', () => {
       expect(adapter).toBeDefined()
     })
 
-    it('forwards sampling options from modelOptions', async () => {
+    it('forwards sampling options and chat({ reasoning }) as reasoning_effort', async () => {
       const streamChunks = [
         {
           id: 'chatcmpl-sampling',
@@ -191,13 +191,13 @@ describe('LLM Gateway adapters', () => {
         temperature: 0.5,
         top_p: 0.8,
         max_completion_tokens: 128,
-        reasoning_effort: 'high',
       }
 
       for await (const _ of adapter.chatStream({
         model: 'gpt-5.6-terra',
         messages: [{ role: 'user', content: 'Hello' }],
         modelOptions,
+        reasoning: { level: 'high', summary: true },
         logger: testLogger,
       })) {
         // consume stream
diff --git a/packages/ai-lovable/src/adapters/responses-text.ts b/packages/ai-lovable/src/adapters/responses-text.ts
index 53035bf8b2..51f9330ef9 100644
--- a/packages/ai-lovable/src/adapters/responses-text.ts
+++ b/packages/ai-lovable/src/adapters/responses-text.ts
@@ -1,5 +1,7 @@
 import OpenAI from 'openai'
 import { OpenAIBaseResponsesTextAdapter } from '@tanstack/openai-base'
+import { LOVABLE_MODEL_REASONING } from '../model-reasoning'
+import type { LovableModelReasoningByName } from '../model-reasoning'
 import { getLovableApiKeyFromEnv, withLovableDefaults } from '../utils/client'
 import type { Modality } from '@tanstack/ai'
 import type {
@@ -19,6 +21,16 @@ export interface LovableResponsesTextConfig
 export type LovableResponsesTextProviderOptions =
   ExternalResponsesProviderOptions
 
+/**
+ * The reasoning levels of a model, for `chat({ reasoning })`. This API has
+ * no token budget field, so no model takes `budgetTokens` here. `never`:
+ * the model does not reason.
+ */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof LovableModelReasoningByName
+    ? { levels: LovableModelReasoningByName[TModel]['levels']; budget: false }
+    : never
+
 type ResolveToolCapabilities<TModel extends string> =
   TModel extends keyof LovableChatModelToolCapabilitiesByName
     ? NonNullable<LovableChatModelToolCapabilitiesByName[TModel]>
@@ -42,7 +54,8 @@ export class LovableResponsesTextAdapter<
   TProviderOptions,
   TInputModalities,
   LovableMessageMetadataByModality,
-  TToolCapabilities
+  TToolCapabilities,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   override readonly name = 'lovable' as const
@@ -50,6 +63,10 @@ export class LovableResponsesTextAdapter<
   constructor(config: LovableResponsesTextConfig, model: TModel) {
     super(model, 'lovable', new OpenAI(withLovableDefaults(config)), config)
   }
+
+  protected override modelReasoning(model: string) {
+    return LOVABLE_MODEL_REASONING[model]
+  }
 }
 
 export function createLovableResponsesText<TModel extends LovableModelId>(
diff --git a/packages/ai-lovable/src/adapters/text.ts b/packages/ai-lovable/src/adapters/text.ts
index 2dfeb8e0cf..05840a98c7 100644
--- a/packages/ai-lovable/src/adapters/text.ts
+++ b/packages/ai-lovable/src/adapters/text.ts
@@ -1,5 +1,7 @@
 import OpenAI from 'openai'
 import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
+import { LOVABLE_MODEL_REASONING } from '../model-reasoning'
+import type { LovableModelReasoningByName } from '../model-reasoning'
 import { withLovableDefaults } from '../utils/client'
 import type { Modality } from '@tanstack/ai'
 import type {
@@ -12,6 +14,16 @@ import type { LovableMessageMetadataByModality } from '../message-types'
 import type { LovableClientConfig } from '../utils/client'
 import type { OpenAIBaseTextAdapterOptions } from '@tanstack/openai-base'
 
+/**
+ * The reasoning levels of a model, for `chat({ reasoning })`. This API has
+ * no token budget field, so no model takes `budgetTokens` here. `never`:
+ * the model does not reason.
+ */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof LovableModelReasoningByName
+    ? { levels: LovableModelReasoningByName[TModel]['levels']; budget: false }
+    : never
+
 type ResolveToolCapabilities<TModel extends string> =
   TModel extends keyof LovableChatModelToolCapabilitiesByName
     ? NonNullable<LovableChatModelToolCapabilitiesByName[TModel]>
@@ -40,7 +52,8 @@ export class LovableTextAdapter<
   TProviderOptions,
   TInputModalities,
   LovableMessageMetadataByModality,
-  TToolCapabilities
+  TToolCapabilities,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   override readonly name = 'lovable' as const
@@ -48,4 +61,8 @@ export class LovableTextAdapter<
   constructor(config: LovableTextConfig, model: TModel) {
     super(model, 'lovable', new OpenAI(withLovableDefaults(config)), config)
   }
+
+  protected override modelReasoning(model: string) {
+    return LOVABLE_MODEL_REASONING[model]
+  }
 }
diff --git a/packages/ai-lovable/src/text/text-provider-options.ts b/packages/ai-lovable/src/text/text-provider-options.ts
index c4acf9c189..646541ccdb 100644
--- a/packages/ai-lovable/src/text/text-provider-options.ts
+++ b/packages/ai-lovable/src/text/text-provider-options.ts
@@ -8,8 +8,6 @@ export interface LovableTextProviderOptions {
   presence_penalty?: number | null
   stop?: string | null | Array<string>
   seed?: number | null
-  reasoning?: boolean | Record<string, unknown> | null
-  include_reasoning?: boolean | null
   response_format?: unknown
   structured_outputs?: boolean | null
   user?: string | null
diff --git a/packages/ai-lovable/tests/reasoning-request.test.ts b/packages/ai-lovable/tests/reasoning-request.test.ts
new file mode 100644
index 0000000000..6b81405c5b
--- /dev/null
+++ b/packages/ai-lovable/tests/reasoning-request.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { LovableTextAdapter } from '../src/adapters/text'
+import { LovableResponsesTextAdapter } from '../src/adapters/responses-text'
+import type { ReasoningRequest, TextOptions } from '@tanstack/ai'
+
+const logger = resolveDebugOption(false)
+const model = 'google/gemini-3.6-flash'
+
+function options(reasoning: ReasoningRequest | undefined): TextOptions {
+  return {
+    model,
+    logger,
+    messages: [{ role: 'user', content: 'hi' }],
+    ...(reasoning ? { reasoning } : {}),
+  }
+}
+
+class ChatProbe extends LovableTextAdapter<typeof model> {
+  request(reasoning: ReasoningRequest | undefined) {
+    return this.mapOptionsToRequest(options(reasoning))
+  }
+}
+
+class ResponsesProbe extends LovableResponsesTextAdapter<typeof model> {
+  request(reasoning: ReasoningRequest | undefined) {
+    return this.mapOptionsToRequest(options(reasoning))
+  }
+}
+
+describe('Lovable chat({ reasoning }) request shape', () => {
+  it('chat: reasoning_effort', () => {
+    const chat = new ChatProbe({ apiKey: 'k' }, model)
+    expect(chat.request({ level: 'minimal', summary: true })).toMatchObject({
+      reasoning_effort: 'minimal',
+    })
+    expect(chat.request(undefined)).not.toHaveProperty('reasoning_effort')
+  })
+
+  it('Responses: reasoning.effort and a summary', () => {
+    const responses = new ResponsesProbe({ apiKey: 'k' }, model)
+    expect(responses.request({ level: 'high', summary: true })).toMatchObject({
+      reasoning: { effort: 'high', summary: 'auto' },
+    })
+  })
+})
diff --git a/packages/ai-opencode/src/adapters/text.ts b/packages/ai-opencode/src/adapters/text.ts
index ee6ee29530..90ac371a18 100644
--- a/packages/ai-opencode/src/adapters/text.ts
+++ b/packages/ai-opencode/src/adapters/text.ts
@@ -2,6 +2,8 @@ import { EventType, normalizeSystemPrompts } from '@tanstack/ai'
 import {
   appendOutputSchemaInstruction,
   parseJsonFromAssistantText,
+  reasoningBudget,
+  resolveReasoning,
   structuredOutputCompleteChunk,
   structuredOutputStartChunk,
   toRunErrorRawEvent,
@@ -27,6 +29,7 @@ import { resolveInteractivePermission } from '../process/permissions'
 import { AsyncQueue } from '../stream/queue'
 import { translateOpencodeStream } from '../stream/translate'
 import { projectOpencodeWorkspace } from './projection'
+import { OPENCODE_MODEL_REASONING } from '../model-reasoning'
 import type { HostToolBridge, SandboxHandle } from '@tanstack/ai-sandbox'
 import type {
   StructuredOutputOptions,
@@ -35,7 +38,9 @@ import type {
 import type {
   DefaultMessageMetadataByModality,
   Modality,
+  ModelReasoning,
   AdapterYieldChunk,
+  ReasoningRequest,
   TextOptions,
 } from '@tanstack/ai'
 import type { OpencodeSessionHandle } from '../process/server'
@@ -46,6 +51,7 @@ import type {
 import type { OpencodeStreamEvent } from '../stream/sdk-types'
 import type { OpencodeModel } from '../model-meta'
 import type { OpencodeTextProviderOptions } from '../provider-options'
+import type { OpenCodeModelReasoningByName } from '../model-reasoning'
 
 const DEFAULT_WORKDIR = '/workspace'
 const DEFAULT_PORT = 4096
@@ -82,6 +88,49 @@ function splitModel(model: string): { providerID: string; modelID: string } {
   return { providerID: model.slice(0, slash), modelID: model.slice(slash + 1) }
 }
 
+/** The reasoning levels of a model, for `chat({ reasoning })`. `never`: none. */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof OpenCodeModelReasoningByName
+    ? OpenCodeModelReasoningByName[TModel]
+    : never
+
+/**
+ * OpenCode's per-model `options` for `chat({ reasoning })`, as its config docs
+ * show them: Claude takes `thinking` with a token budget (pi's table when the
+ * request sets none), other models take `reasoningEffort` and
+ * `reasoningSummary`.
+ */
+export function opencodeReasoningOptions(
+  modelID: string,
+  request: ReasoningRequest | undefined,
+  reasoning: ModelReasoning | undefined,
+): Record<string, unknown> | undefined {
+  const resolved = resolveReasoning(request, reasoning)
+  if (!resolved) return undefined
+  if (modelID.includes('claude')) {
+    if (resolved.level === 'off') return { thinking: { type: 'disabled' } }
+    return {
+      thinking: {
+        type: 'enabled',
+        budgetTokens: reasoningBudget({
+          level: resolved.level,
+          summary: resolved.summary,
+          ...(resolved.budgetTokens !== undefined
+            ? { budgetTokens: resolved.budgetTokens }
+            : {}),
+        }),
+      },
+    }
+  }
+  if (resolved.value === null) return undefined
+  return {
+    reasoningEffort: resolved.value,
+    ...(resolved.summary && resolved.level !== 'off'
+      ? { reasoningSummary: 'auto' }
+      : {}),
+  }
+}
+
 export class OpencodeTextAdapter<
   TModel extends OpencodeModel,
 > extends BaseTextAdapter<
@@ -91,7 +140,8 @@ export class OpencodeTextAdapter<
   DefaultMessageMetadataByModality,
   ReadonlyArray<string>,
   unknown,
-  never
+  never,
+  ResolveReasoning<TModel>
 > {
   readonly name = 'opencode' as const
 
@@ -281,20 +331,36 @@ export class OpencodeTextAdapter<
         { provider: 'opencode', model: this.model },
       )
 
-      const serverEnv = bridge
-        ? {
-            OPENCODE_CONFIG_CONTENT: JSON.stringify({
-              mcp: {
-                [bridge.name]: {
-                  type: 'remote',
-                  url: bridge.url,
-                  enabled: true,
-                  headers: { Authorization: `Bearer ${bridge.token}` },
-                },
-              },
-            }),
-          }
-        : undefined
+      // `chat({ reasoning })` goes on the model's config entry.
+      const reasoningOptions = opencodeReasoningOptions(
+        modelID,
+        options.reasoning,
+        OPENCODE_MODEL_REASONING[this.model],
+      )
+      const serverEnv =
+        bridge || reasoningOptions
+          ? {
+              OPENCODE_CONFIG_CONTENT: JSON.stringify({
+                ...(bridge && {
+                  mcp: {
+                    [bridge.name]: {
+                      type: 'remote',
+                      url: bridge.url,
+                      enabled: true,
+                      headers: { Authorization: `Bearer ${bridge.token}` },
+                    },
+                  },
+                }),
+                ...(reasoningOptions && {
+                  provider: {
+                    [providerID]: {
+                      models: { [modelID]: { options: reasoningOptions } },
+                    },
+                  },
+                }),
+              }),
+            }
+          : undefined
 
       server = await startOpencodeServerInSandbox(sandbox, {
         port: this.adapterConfig.port ?? DEFAULT_PORT,
diff --git a/packages/ai-opencode/tests/reasoning-options.test.ts b/packages/ai-opencode/tests/reasoning-options.test.ts
new file mode 100644
index 0000000000..8f7ed0621f
--- /dev/null
+++ b/packages/ai-opencode/tests/reasoning-options.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+import { opencodeReasoningOptions } from '../src/adapters/text'
+import { OPENCODE_MODEL_REASONING } from '../src/model-reasoning'
+
+describe('OpenCode chat({ reasoning }) model options', () => {
+  it('Claude: thinking with a token budget, disabled for off', () => {
+    const reasoning = OPENCODE_MODEL_REASONING['anthropic/claude-sonnet-4-5']
+    expect(
+      opencodeReasoningOptions(
+        'claude-sonnet-4-5',
+        { level: 'medium', summary: true },
+        reasoning,
+      ),
+    ).toEqual({ thinking: { type: 'enabled', budgetTokens: 8192 } })
+    expect(
+      opencodeReasoningOptions(
+        'claude-sonnet-4-5',
+        { level: 'high', summary: true, budgetTokens: 3000 },
+        reasoning,
+      ),
+    ).toEqual({ thinking: { type: 'enabled', budgetTokens: 3000 } })
+    expect(
+      opencodeReasoningOptions(
+        'claude-sonnet-4-5',
+        { level: 'off', summary: true },
+        reasoning,
+      ),
+    ).toEqual({ thinking: { type: 'disabled' } })
+  })
+
+  it('other models: reasoningEffort and reasoningSummary', () => {
+    expect(
+      opencodeReasoningOptions(
+        'gpt-5.2',
+        { level: 'xhigh', summary: true },
+        OPENCODE_MODEL_REASONING['openai/gpt-5.2'],
+      ),
+    ).toEqual({ reasoningEffort: 'xhigh', reasoningSummary: 'auto' })
+  })
+
+  it('sends nothing without a request', () => {
+    expect(
+      opencodeReasoningOptions(
+        'gpt-5.2',
+        undefined,
+        OPENCODE_MODEL_REASONING['openai/gpt-5.2'],
+      ),
+    ).toBeUndefined()
+  })
+})
diff --git a/packages/ai-vercel-gateway/src/adapters/responses-text.ts b/packages/ai-vercel-gateway/src/adapters/responses-text.ts
index b658e37f54..66519a6d3a 100644
--- a/packages/ai-vercel-gateway/src/adapters/responses-text.ts
+++ b/packages/ai-vercel-gateway/src/adapters/responses-text.ts
@@ -5,6 +5,8 @@ import {
   withVercelGatewayDefaults,
 } from '../utils/client'
 import { mapGatewayModelOptions } from '../utils/map-gateway-options'
+import { VERCEL_GATEWAY_MODEL_REASONING } from '../model-reasoning'
+import type { VercelGatewayModelReasoningByName } from '../model-reasoning'
 import type { Modality, TextOptions } from '@tanstack/ai'
 import type { ResponseCreateParams } from 'openai/resources/responses/responses'
 import type {
@@ -24,6 +26,19 @@ export interface VercelGatewayResponsesTextConfig
 export type VercelGatewayResponsesTextProviderOptions =
   ExternalResponsesProviderOptions
 
+/**
+ * The reasoning levels of a model, for `chat({ reasoning })`. This API has
+ * no token budget field, so no model takes `budgetTokens` here. `never`:
+ * the model does not reason.
+ */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof VercelGatewayModelReasoningByName
+    ? {
+        levels: VercelGatewayModelReasoningByName[TModel]['levels']
+        budget: false
+      }
+    : never
+
 type ResolveToolCapabilities<TModel extends string> =
   TModel extends keyof VercelGatewayChatModelToolCapabilitiesByName
     ? NonNullable<VercelGatewayChatModelToolCapabilitiesByName[TModel]>
@@ -47,7 +62,8 @@ export class VercelGatewayResponsesTextAdapter<
   TProviderOptions,
   TInputModalities,
   VercelGatewayMessageMetadataByModality,
-  TToolCapabilities
+  TToolCapabilities,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   override readonly name = 'vercel-gateway' as const
@@ -61,6 +77,10 @@ export class VercelGatewayResponsesTextAdapter<
     )
   }
 
+  protected override modelReasoning(model: string) {
+    return VERCEL_GATEWAY_MODEL_REASONING[model]
+  }
+
   protected override mapOptionsToRequest(
     options: TextOptions<TProviderOptions>,
   ): Omit<ResponseCreateParams, 'stream'> {
diff --git a/packages/ai-vercel-gateway/src/adapters/text.ts b/packages/ai-vercel-gateway/src/adapters/text.ts
index 00394abe73..7b5b821d74 100644
--- a/packages/ai-vercel-gateway/src/adapters/text.ts
+++ b/packages/ai-vercel-gateway/src/adapters/text.ts
@@ -2,6 +2,10 @@ import OpenAI from 'openai'
 import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
 import { withVercelGatewayDefaults } from '../utils/client'
 import { mapGatewayModelOptions } from '../utils/map-gateway-options'
+import { VERCEL_GATEWAY_MODEL_REASONING } from '../model-reasoning'
+import { resolveReasoning } from '@tanstack/ai/adapter-internals'
+import type { ResolvedReasoning } from '@tanstack/ai/adapter-internals'
+import type { VercelGatewayModelReasoningByName } from '../model-reasoning'
 import type { Modality, TextOptions } from '@tanstack/ai'
 import type {
   VERCEL_GATEWAY_CHAT_MODELS,
@@ -13,6 +17,26 @@ import type { VercelGatewayMessageMetadataByModality } from '../message-types'
 import type { VercelGatewayClientConfig } from '../utils/client'
 import type { OpenAIBaseTextAdapterOptions } from '@tanstack/openai-base'
 
+/** The reasoning levels of a model, for `chat({ reasoning })`. `never`: none. */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof VercelGatewayModelReasoningByName
+    ? VercelGatewayModelReasoningByName[TModel]
+    : never
+
+/**
+ * AI Gateway's `reasoning` object for Chat Completions: `enabled: false` for
+ * `off`, a `max_tokens` budget when the request sets one (it cannot go with
+ * `effort`), or the effort. `exclude` hides the thinking text.
+ */
+function gatewayReasoning(resolved: ResolvedReasoning) {
+  if (resolved.level === 'off') return { enabled: false }
+  const exclude = resolved.summary ? {} : { exclude: true }
+  if (resolved.budgetTokens !== undefined) {
+    return { enabled: true, max_tokens: resolved.budgetTokens, ...exclude }
+  }
+  return { effort: resolved.value ?? resolved.level, ...exclude }
+}
+
 type ResolveToolCapabilities<TModel extends string> =
   TModel extends keyof VercelGatewayChatModelToolCapabilitiesByName
     ? NonNullable<VercelGatewayChatModelToolCapabilitiesByName[TModel]>
@@ -41,7 +65,8 @@ export class VercelGatewayTextAdapter<
   TProviderOptions,
   TInputModalities,
   VercelGatewayMessageMetadataByModality,
-  TToolCapabilities
+  TToolCapabilities,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   override readonly name = 'vercel-gateway' as const
@@ -66,6 +91,14 @@ export class VercelGatewayTextAdapter<
       gateway?: unknown
     }
     void _gateway
+    // `chat({ reasoning })`. The `reasoning` object is an AI Gateway field
+    // that the OpenAI SDK type does not list, so it goes on with
+    // Object.assign.
+    const resolved = resolveReasoning(
+      options.reasoning,
+      VERCEL_GATEWAY_MODEL_REASONING[options.model],
+    )
+    if (resolved) Object.assign(rest, { reasoning: gatewayReasoning(resolved) })
     return rest
   }
 }
diff --git a/packages/ai-vercel-gateway/src/model-meta.ts b/packages/ai-vercel-gateway/src/model-meta.ts
index d698783e20..a5df3b7955 100644
--- a/packages/ai-vercel-gateway/src/model-meta.ts
+++ b/packages/ai-vercel-gateway/src/model-meta.ts
@@ -460,8 +460,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -472,8 +470,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -484,8 +480,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -496,20 +490,13 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
   'alibaba/qwen-3.6-max-preview': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'alibaba/qwen3-235b-a22b-thinking': VercelGatewayCommonOptions &
     Pick<
@@ -518,8 +505,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -565,8 +550,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -587,8 +570,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -609,8 +590,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -632,52 +611,27 @@ export type VercelGatewayChatModelProviderOptionsByName = {
   'alibaba/qwen3-vl-thinking': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'alibaba/qwen3.5-flash': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'alibaba/qwen3.5-plus': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'alibaba/qwen3.6-27b': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'alibaba/qwen3.6-plus': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'alibaba/qwen3.7-flash': VercelGatewayCommonOptions &
     Pick<
@@ -686,8 +640,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -698,20 +650,13 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
   'alibaba/qwen3.7-plus': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'alibaba/qwen3.8-2.4t-a95b': VercelGatewayCommonOptions &
     Pick<
@@ -720,8 +665,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -732,8 +675,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -744,8 +685,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -756,8 +695,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -768,8 +705,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -780,8 +715,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -792,8 +725,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -804,8 +735,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -855,8 +784,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -867,8 +794,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -879,20 +804,13 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
   'anthropic/claude-opus-4': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'anthropic/claude-opus-4.5': VercelGatewayCommonOptions &
     Pick<
@@ -901,8 +819,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -913,8 +829,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -925,8 +839,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -937,8 +849,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -949,8 +859,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -960,8 +868,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -971,8 +877,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -982,8 +886,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -993,8 +895,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1005,8 +905,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1017,8 +915,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1029,8 +925,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1040,8 +934,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1051,8 +943,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1063,40 +953,23 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
   'bytedance/seed-1.6': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'bytedance/seed-1.8': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'bytedance/seed-2.1-turbo': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'cohere/command-a': VercelGatewayCommonOptions &
     Pick<
@@ -1111,12 +984,7 @@ export type VercelGatewayChatModelProviderOptionsByName = {
   'deepseek/deepseek-r1': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'deepseek/deepseek-v3.1': VercelGatewayCommonOptions &
     Pick<
@@ -1125,8 +993,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1137,30 +1003,18 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
   'deepseek/deepseek-v3.2': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'deepseek/deepseek-v3.2-thinking': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'deepseek/deepseek-v4-flash': VercelGatewayCommonOptions &
     Pick<
@@ -1169,8 +1023,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1181,8 +1033,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1193,8 +1043,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1205,8 +1053,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1217,8 +1063,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1229,20 +1073,13 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
   'fireworks/ember-1': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'fish-audio/s1': VercelGatewayCommonOptions
   'fish-audio/s2-pro': VercelGatewayCommonOptions
@@ -1255,20 +1092,13 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
   'google/gemini-2.5-flash-image': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'google/gemini-2.5-flash-lite': VercelGatewayCommonOptions &
     Pick<
@@ -1277,8 +1107,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1289,8 +1117,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1301,8 +1127,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1313,8 +1137,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1325,8 +1147,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1337,8 +1157,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1349,20 +1167,13 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
   'google/gemini-3.1-flash-lite-image': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'google/gemini-3.1-pro-preview': VercelGatewayCommonOptions &
     Pick<
@@ -1371,8 +1182,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1383,8 +1192,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1395,8 +1202,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1409,8 +1214,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1421,8 +1224,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1433,8 +1234,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1443,22 +1242,12 @@ export type VercelGatewayChatModelProviderOptionsByName = {
   'google/gemini-3.8-live': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'google/gemini-3.8-live-extended-thinking': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'google/gemini-omni-flash-preview': VercelGatewayCommonOptions &
     Pick<
@@ -1467,8 +1256,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1479,8 +1266,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1491,8 +1276,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1503,8 +1286,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1515,8 +1296,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1533,12 +1312,7 @@ export type VercelGatewayChatModelProviderOptionsByName = {
   'inclusionai/ling-3.0-flash': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'inclusionai/ling-3.0-flash-fin': VercelGatewayCommonOptions &
     Pick<
@@ -1547,60 +1321,33 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
   'inclusionai/ling-3.0-flash-sante': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'inclusionai/ling-3.0-flash-sante-free': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'inclusionai/ling-3.0-flash-vl': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'inclusionai/ling-3.1-flash': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'inclusionai/ling-3.1-flash-free': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'inference-net/schematron-v2-small': VercelGatewayCommonOptions &
     Pick<
@@ -1629,8 +1376,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1642,8 +1387,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1654,8 +1397,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1666,20 +1407,13 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
   'meta/llama-3.3-70b': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'meta/llama-4-maverick': VercelGatewayCommonOptions &
     Pick<
@@ -1688,8 +1422,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1700,8 +1432,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1712,8 +1442,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1724,8 +1452,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1736,8 +1462,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1748,8 +1472,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1760,8 +1482,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1772,8 +1492,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1784,8 +1502,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1796,8 +1512,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1808,8 +1522,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1820,8 +1532,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1832,8 +1542,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1844,8 +1552,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1856,8 +1562,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1868,8 +1572,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1925,8 +1627,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1972,8 +1672,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1984,8 +1682,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -1996,8 +1692,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2008,8 +1702,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2020,8 +1712,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2031,8 +1721,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2042,8 +1730,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2068,12 +1754,7 @@ export type VercelGatewayChatModelProviderOptionsByName = {
   'nvidia/nemotron-3-nano-30b-a3b': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'nvidia/nemotron-3-super-120b-a12b': VercelGatewayCommonOptions &
     Pick<
@@ -2082,8 +1763,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2094,8 +1773,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2106,8 +1783,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2118,20 +1793,13 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
   'nvidia/nemotron-nano-9b-v2': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'openai/gpt-3.5-turbo': VercelGatewayCommonOptions &
     Pick<
@@ -2251,8 +1919,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2262,8 +1928,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2273,8 +1937,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2284,8 +1946,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2295,8 +1955,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2306,20 +1964,13 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
   'openai/gpt-5-pro': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'openai/gpt-5.1-codex': VercelGatewayCommonOptions &
     Pick<
@@ -2328,8 +1979,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2340,8 +1989,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2352,8 +1999,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2364,8 +2009,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2376,8 +2019,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2388,8 +2029,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2400,8 +2039,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2412,8 +2049,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2424,8 +2059,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2436,8 +2069,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2448,8 +2079,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2460,8 +2089,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2472,8 +2099,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2484,8 +2109,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2496,8 +2119,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2508,8 +2129,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2520,8 +2139,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2532,8 +2149,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2543,8 +2158,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2555,8 +2168,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2567,8 +2178,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2578,8 +2187,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2590,8 +2197,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2601,8 +2206,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2613,8 +2216,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2624,8 +2225,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2635,8 +2234,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2646,8 +2243,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2658,8 +2253,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2670,8 +2263,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2682,8 +2273,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2694,8 +2283,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2706,8 +2293,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2718,8 +2303,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2735,8 +2318,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2747,8 +2328,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2759,8 +2338,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2771,8 +2348,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2784,22 +2359,12 @@ export type VercelGatewayChatModelProviderOptionsByName = {
   'openai/gpt-realtime-2': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'openai/gpt-realtime-2.1': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'openai/gpt-realtime-mini': VercelGatewayCommonOptions &
     Pick<
@@ -2813,8 +2378,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2824,8 +2387,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2835,8 +2396,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2846,8 +2405,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2858,8 +2415,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2869,8 +2424,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2880,8 +2433,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_tokens'
       | 'max_output_tokens'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2895,50 +2446,28 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
   'poolside/laguna-s-2.1': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'poolside/laguna-s-2.1-free': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'quiverai/arrow-2': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'quiverai/arrow-2-telos': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'sakana/fugu-max': VercelGatewayCommonOptions &
     Pick<
@@ -2947,8 +2476,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2959,8 +2486,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2971,8 +2496,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2983,8 +2506,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -2995,8 +2516,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3007,8 +2526,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3019,8 +2536,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3031,8 +2546,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3043,8 +2556,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3055,8 +2566,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3067,8 +2576,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3079,8 +2586,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3091,8 +2596,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3103,8 +2606,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3115,8 +2616,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3127,8 +2626,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3139,8 +2636,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3149,42 +2644,22 @@ export type VercelGatewayChatModelProviderOptionsByName = {
   'spacexai/grok-voice-think-fast-1.0': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'spacexai/grok-voice-think-fast-2.0': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'stealth/pixel-canary': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'stepfun/step-3.5-flash': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'stepfun/step-3.7-flash': VercelGatewayCommonOptions &
     Pick<
@@ -3193,8 +2668,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3205,8 +2678,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3242,20 +2713,13 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
   'tencent/hy4-preview': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'thinkingmachines/inkling': VercelGatewayCommonOptions &
     Pick<
@@ -3264,8 +2728,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3276,8 +2738,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3289,8 +2749,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3301,8 +2759,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3313,8 +2769,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3325,8 +2779,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3337,8 +2789,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3349,8 +2799,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3361,8 +2809,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3373,8 +2819,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3385,8 +2829,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3397,8 +2839,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3409,20 +2849,13 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
   'zai/glm-4.7-flashx': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'zai/glm-5': VercelGatewayCommonOptions &
     Pick<
@@ -3431,20 +2864,13 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
   'zai/glm-5-turbo': VercelGatewayCommonOptions &
     Pick<
       VercelGatewayBaseOptions,
-      | 'max_tokens'
-      | 'max_output_tokens'
-      | 'temperature'
-      | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
+      'max_tokens' | 'max_output_tokens' | 'temperature' | 'stop'
     >
   'zai/glm-5.1': VercelGatewayCommonOptions &
     Pick<
@@ -3453,8 +2879,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3465,8 +2889,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3477,8 +2899,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3489,8 +2909,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3501,8 +2919,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3513,8 +2929,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3525,8 +2939,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
@@ -3537,8 +2949,6 @@ export type VercelGatewayChatModelProviderOptionsByName = {
       | 'max_output_tokens'
       | 'temperature'
       | 'stop'
-      | 'reasoning'
-      | 'include_reasoning'
       | 'response_format'
       | 'structured_outputs'
     >
diff --git a/packages/ai-vercel-gateway/src/text/text-provider-options.ts b/packages/ai-vercel-gateway/src/text/text-provider-options.ts
index 80c7add77f..5eab88b2b1 100644
--- a/packages/ai-vercel-gateway/src/text/text-provider-options.ts
+++ b/packages/ai-vercel-gateway/src/text/text-provider-options.ts
@@ -35,8 +35,6 @@ export interface VercelGatewayBaseOptions {
   presence_penalty?: number | null
   stop?: string | null | Array<string>
   seed?: number | null
-  reasoning?: boolean | Record<string, unknown> | null
-  include_reasoning?: boolean | null
   response_format?: unknown
   structured_outputs?: boolean | null
 }
diff --git a/packages/ai-vercel-gateway/tests/reasoning-request.test.ts b/packages/ai-vercel-gateway/tests/reasoning-request.test.ts
new file mode 100644
index 0000000000..d2f8f432a2
--- /dev/null
+++ b/packages/ai-vercel-gateway/tests/reasoning-request.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { VercelGatewayTextAdapter } from '../src/adapters/text'
+import { VercelGatewayResponsesTextAdapter } from '../src/adapters/responses-text'
+import type { ReasoningRequest, TextOptions } from '@tanstack/ai'
+
+const logger = resolveDebugOption(false)
+
+function options(
+  model: string,
+  reasoning: ReasoningRequest | undefined,
+): TextOptions {
+  return {
+    model,
+    logger,
+    messages: [{ role: 'user', content: 'hi' }],
+    ...(reasoning ? { reasoning } : {}),
+  }
+}
+
+class ChatProbe extends VercelGatewayTextAdapter<'anthropic/claude-sonnet-4.5'> {
+  request(reasoning: ReasoningRequest | undefined) {
+    return this.mapOptionsToRequest(options(this.model, reasoning))
+  }
+}
+
+class ResponsesProbe extends VercelGatewayResponsesTextAdapter<'openai/gpt-5.5'> {
+  request(reasoning: ReasoningRequest | undefined) {
+    return this.mapOptionsToRequest(options(this.model, reasoning))
+  }
+}
+
+describe('Vercel AI Gateway chat({ reasoning }) request shape', () => {
+  const chat = new ChatProbe({ apiKey: 'k' }, 'anthropic/claude-sonnet-4.5')
+
+  it('chat: the reasoning object with the effort', () => {
+    expect(chat.request({ level: 'high', summary: true })).toMatchObject({
+      reasoning: { effort: 'high' },
+    })
+  })
+
+  it('chat: enabled false for off, and exclude when the summary is off', () => {
+    expect(chat.request({ level: 'off', summary: true })).toMatchObject({
+      reasoning: { enabled: false },
+    })
+    expect(chat.request({ level: 'low', summary: false })).toMatchObject({
+      reasoning: { effort: 'low', exclude: true },
+    })
+  })
+
+  it('chat: a token budget goes out as max_tokens, without effort', () => {
+    const request = chat.request({
+      level: 'high',
+      summary: true,
+      budgetTokens: 2000,
+    })
+    expect(request).toMatchObject({
+      reasoning: { enabled: true, max_tokens: 2000 },
+    })
+    expect(request).not.toHaveProperty('reasoning.effort')
+  })
+
+  it('chat: nothing without a reasoning request', () => {
+    expect(chat.request(undefined)).not.toHaveProperty('reasoning')
+  })
+
+  it('Responses: reasoning.effort and a summary', () => {
+    const responses = new ResponsesProbe({ apiKey: 'k' }, 'openai/gpt-5.5')
+    expect(responses.request({ level: 'xhigh', summary: true })).toMatchObject({
+      reasoning: { effort: 'xhigh', summary: 'auto' },
+    })
+  })
+})
diff --git a/scripts/convert-vercel-gateway-models.ts b/scripts/convert-vercel-gateway-models.ts
index 3c3bc23016..1c5c1da011 100644
--- a/scripts/convert-vercel-gateway-models.ts
+++ b/scripts/convert-vercel-gateway-models.ts
@@ -60,7 +60,14 @@ const INPUT_MODALITY_ORDER: Array<InputModality> = [
   'video',
 ]
 
-const EXCLUDED_PARAMS = new Set(['tools', 'tool_choice'])
+// `chat({ reasoning })` owns reasoning, so its params are not model options.
+const EXCLUDED_PARAMS = new Set([
+  'tools',
+  'tool_choice',
+  'reasoning',
+  'include_reasoning',
+  'reasoning_effort',
+])
 
 const PARAM_NAME_MAP: Record<string, Array<string>> = {
   max_tokens: ['max_tokens', 'max_output_tokens'],
@@ -71,8 +78,6 @@ const PARAM_NAME_MAP: Record<string, Array<string>> = {
   seed: ['seed'],
   frequency_penalty: ['frequency_penalty'],
   presence_penalty: ['presence_penalty'],
-  reasoning: ['reasoning'],
-  include_reasoning: ['include_reasoning'],
   response_format: ['response_format'],
   structured_outputs: ['structured_outputs'],
 }

From 1a973d9704bfa134c57a526b63f6778b3b663824 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 15:25:49 +0200
Subject: [PATCH 096/286] feat(adapters)!: map chat({ reasoning }) on Groq,
 Ollama, BytePlus, Claude Code, Codex, Cloudflare

Each adapter reads its generated model-reasoning map, and the reasoning
control leaves modelOptions:

- Groq: `reasoning_effort` through the base hook. A sync override gives
  Qwen 3 Groq's `none` and `default` values.
- Ollama: `think`, `true`/`false` for on/off models and the level for
  gpt-oss. A model name the package does not list gets the on/off
  toggle, so custom models keep a switch.
- BytePlus: `thinking.type`, plus `reasoning_effort` when the level has
  an effort value; `off` sends only `disabled`. Sync overrides cover the
  nine Ark reasoning models that models.dev lacks.
- Claude Code: `--effort` for effort models, `MAX_THINKING_TOKENS` for
  budget models (0 for `off`), as the CLI docs describe.
- Codex: `model_reasoning_effort`; the adapter config value stays as the
  default for calls without `reasoning`.
- Cloudflare: `reasoning_effort`, `null` for `off`.

Groq keeps `reasoning_format` and `include_reasoning`, and Cloudflare
keeps `chat_template_kwargs`: they pick the output format, not the
effort.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-byteplus/src/adapters/text.ts     |  44 +++++-
 packages/ai-byteplus/src/index.ts             |   2 -
 packages/ai-byteplus/src/model-reasoning.ts   | 129 ++++++++++++++++++
 .../src/text/text-provider-options.ts         |  44 +-----
 packages/ai-byteplus/tests/text.test.ts       |  41 +++++-
 packages/ai-claude-code/src/adapters/text.ts  |  47 ++++++-
 .../tests/reasoning-options.test.ts           |  33 +++++
 packages/ai-cloudflare/src/adapters/text.ts   |  49 ++++++-
 .../tests/reasoning-request.test.ts           |  38 ++++++
 packages/ai-codex/src/adapters/text.ts        |  43 +++++-
 packages/ai-codex/src/provider-options.ts     |   2 -
 .../ai-codex/tests/reasoning-effort.test.ts   |  34 +++++
 packages/ai-groq/src/adapters/text.ts         |  15 +-
 packages/ai-groq/src/model-reasoning.ts       |  14 +-
 .../ai-groq/src/text/text-provider-options.ts |   8 --
 .../ai-groq/tests/reasoning-request.test.ts   |  39 ++++++
 packages/ai-ollama/src/adapters/text.ts       |  75 ++++++++--
 .../src/meta/model-meta-deepseek-r1.ts        |  43 ++----
 .../src/meta/model-meta-deepseek-v3.1.ts      |  19 +--
 .../ai-ollama/src/meta/model-meta-gpt-oss.ts  |  19 +--
 .../ai-ollama/src/meta/model-meta-qwen3.ts    |  55 +++-----
 packages/ai-ollama/src/meta/models-meta.ts    |   8 --
 .../ai-ollama/tests/reasoning-types.test-d.ts |  26 ++++
 packages/ai-ollama/tests/text-adapter.test.ts |  38 +++++-
 scripts/model-sync/reasoning-targets.ts       |  64 +++++++++
 scripts/sync-model-reasoning.ts               |   2 +-
 26 files changed, 745 insertions(+), 186 deletions(-)
 create mode 100644 packages/ai-claude-code/tests/reasoning-options.test.ts
 create mode 100644 packages/ai-cloudflare/tests/reasoning-request.test.ts
 create mode 100644 packages/ai-codex/tests/reasoning-effort.test.ts
 create mode 100644 packages/ai-groq/tests/reasoning-request.test.ts
 create mode 100644 packages/ai-ollama/tests/reasoning-types.test-d.ts

diff --git a/packages/ai-byteplus/src/adapters/text.ts b/packages/ai-byteplus/src/adapters/text.ts
index 34ff423edc..937deb22dd 100644
--- a/packages/ai-byteplus/src/adapters/text.ts
+++ b/packages/ai-byteplus/src/adapters/text.ts
@@ -6,6 +6,10 @@ import {
 } from '@tanstack/ai'
 import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
 import { generateId } from '@tanstack/ai-utils'
+import { resolveReasoning } from '@tanstack/ai/adapter-internals'
+import { BYTEPLUS_MODEL_REASONING } from '../model-reasoning'
+import type { ResolvedReasoning } from '@tanstack/ai/adapter-internals'
+import type { BytePlusModelReasoningByName } from '../model-reasoning'
 import {
   BYTEPLUS_MODEL_INPUT_MODALITIES,
   BYTEPLUS_STRUCTURED_OUTPUT_CHAT_MODELS,
@@ -88,6 +92,26 @@ export type { BytePlusTextProviderOptions } from '../text/text-provider-options'
  *    ignores the schema), and Ark rejects `json_object` everywhere, so there
  *    is no JSON-mode fallback.
  */
+/** The reasoning levels of a model, for `chat({ reasoning })`. `never`: none. */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof BytePlusModelReasoningByName
+    ? BytePlusModelReasoningByName[TModel]
+    : never
+
+/**
+ * Ark's thinking fields for `chat({ reasoning })`: `thinking.type`, plus
+ * `reasoning_effort` when the level has an effort value. `off` sends only
+ * `disabled`, because Ark refuses an effort next to it.
+ */
+function arkThinking(resolved: ResolvedReasoning | undefined) {
+  if (!resolved) return {}
+  if (resolved.level === 'off') return { thinking: { type: 'disabled' } }
+  const effort = resolved.value
+  return effort === null || effort === 'enabled'
+    ? { thinking: { type: 'enabled' } }
+    : { thinking: { type: 'enabled' }, reasoning_effort: effort }
+}
+
 export class BytePlusTextAdapter<
   TModel extends (typeof BYTEPLUS_CHAT_MODELS)[number],
   // `Record<string, any>` (not `unknown`) mirrors the OpenAI/Groq/Grok text
@@ -104,7 +128,8 @@ export class BytePlusTextAdapter<
   TProviderOptions,
   TInputModalities,
   BytePlusMessageMetadataByModality,
-  TToolCapabilities
+  TToolCapabilities,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   override readonly name = 'byteplus' as const
@@ -120,6 +145,23 @@ export class BytePlusTextAdapter<
     )
   }
 
+  /**
+   * Adds Ark's thinking fields for `chat({ reasoning })`. They are Ark
+   * fields that the OpenAI SDK type does not list, so they go on with
+   * Object.assign.
+   */
+  protected override mapOptionsToRequest(options: TextOptions) {
+    return Object.assign(
+      super.mapOptionsToRequest(options),
+      arkThinking(
+        resolveReasoning(
+          options.reasoning,
+          BYTEPLUS_MODEL_REASONING[options.model],
+        ),
+      ),
+    )
+  }
+
   /**
    * Surfaces Ark's reasoning deltas. Thinking-enabled models stream the
    * reasoning trace as `delta.reasoning_content` (the OpenAI chunk shape has
diff --git a/packages/ai-byteplus/src/index.ts b/packages/ai-byteplus/src/index.ts
index 79b51f1ba6..ffc1251bad 100644
--- a/packages/ai-byteplus/src/index.ts
+++ b/packages/ai-byteplus/src/index.ts
@@ -168,10 +168,8 @@ export type { BytePlusArkConfig, BytePlusVoiceConfig } from './utils/client'
 
 export type {
   BytePlusNamedToolChoice,
-  BytePlusReasoningEffort,
   BytePlusServiceTier,
   BytePlusTextProviderOptions,
-  BytePlusThinkingOption,
   BytePlusToolChoice,
 } from './text/text-provider-options'
 
diff --git a/packages/ai-byteplus/src/model-reasoning.ts b/packages/ai-byteplus/src/model-reasoning.ts
index e603d06159..9d6251798c 100644
--- a/packages/ai-byteplus/src/model-reasoning.ts
+++ b/packages/ai-byteplus/src/model-reasoning.ts
@@ -6,6 +6,10 @@ import type { ModelReasoning } from '@tanstack/ai'
  * `chat({ reasoning })`. A model that is not here does not reason.
  */
 export type BytePlusModelReasoningByName = {
+  'dola-seed-2-1-turbo-260628': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
   'seed-2-0-lite-260428': {
     levels: 'minimal' | 'low' | 'medium' | 'high'
     budget: false
@@ -18,6 +22,14 @@ export type BytePlusModelReasoningByName = {
     levels: 'minimal' | 'low' | 'medium' | 'high'
     budget: false
   }
+  'seed-2-0-lite-260228': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
+  'seed-2-0-mini-260215': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
   'seed-2-0-code-preview-260328': {
     levels: 'minimal' | 'low' | 'medium' | 'high'
     budget: false
@@ -38,16 +50,37 @@ export type BytePlusModelReasoningByName = {
     levels: 'minimal' | 'low' | 'medium' | 'high'
     budget: false
   }
+  'seed-1-6-flash-250615': {
+    levels: 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
   'glm-5-2-260617': {
     levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
     budget: false
   }
+  'glm-4-7-251222': { levels: 'off' | 'high'; budget: false }
+  'deepseek-v4-pro-260425': { levels: 'off' | 'high' | 'max'; budget: false }
+  'deepseek-v4-flash-260425': { levels: 'off' | 'high' | 'max'; budget: false }
+  'deepseek-v3-2-251201': { levels: 'off' | 'high'; budget: false }
+  'gpt-oss-120b-250805': { levels: 'low' | 'medium' | 'high'; budget: false }
 }
 
 /** The same data at runtime. `false`: the model does not reason. */
 export const BYTEPLUS_MODEL_REASONING: Readonly<
   Record<string, ModelReasoning>
 > = {
+  'dola-seed-2-1-turbo-260628': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
   'seed-2-0-lite-260428': {
     map: {
       off: null,
@@ -84,6 +117,30 @@ export const BYTEPLUS_MODEL_REASONING: Readonly<
     },
     budget: false,
   },
+  'seed-2-0-lite-260228': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'seed-2-0-mini-260215': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
   'seed-2-0-code-preview-260328': {
     map: {
       off: null,
@@ -144,6 +201,18 @@ export const BYTEPLUS_MODEL_REASONING: Readonly<
     },
     budget: false,
   },
+  'seed-1-6-flash-250615': {
+    map: {
+      off: null,
+      minimal: 'minimal',
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
   'glm-5-2-260617': {
     map: {
       off: 'none',
@@ -156,4 +225,64 @@ export const BYTEPLUS_MODEL_REASONING: Readonly<
     },
     budget: false,
   },
+  'glm-4-7-251222': {
+    map: {
+      off: 'disabled',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'enabled',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'deepseek-v4-pro-260425': {
+    map: {
+      off: 'disabled',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'deepseek-v4-flash-260425': {
+    map: {
+      off: 'disabled',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'high',
+      xhigh: null,
+      max: 'max',
+    },
+    budget: false,
+  },
+  'deepseek-v3-2-251201': {
+    map: {
+      off: 'disabled',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'enabled',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
+  'gpt-oss-120b-250805': {
+    map: {
+      off: null,
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
+  },
 }
diff --git a/packages/ai-byteplus/src/text/text-provider-options.ts b/packages/ai-byteplus/src/text/text-provider-options.ts
index f4e77ebb97..a0a9898326 100644
--- a/packages/ai-byteplus/src/text/text-provider-options.ts
+++ b/packages/ai-byteplus/src/text/text-provider-options.ts
@@ -2,50 +2,20 @@
  * BytePlus ModelArk chat provider options.
  *
  * Ark's `/chat/completions` is OpenAI-compatible, so most of this is the
- * familiar sampling surface; `thinking`, `reasoning_effort`,
- * `repetition_penalty` and `service_tier` are the Ark-only additions.
+ * familiar sampling surface; `repetition_penalty` and `service_tier` are
+ * the Ark-only additions. Thinking is set with `chat({ reasoning })`.
  *
  * Every field below was accepted by a live request against
  * `https://ark.ap-southeast.bytepluses.com/api/v3` on 2026-07-31. Two probe
  * results are encoded as TSDoc warnings rather than types because they are
- * cross-field constraints TypeScript can't express: `max_tokens` and
- * `max_completion_tokens` are mutually exclusive, and `reasoning_effort`
- * combined with `thinking: {type: 'disabled'}` is a 400.
+ * cross-field constraint TypeScript can't express: `max_tokens` and
+ * `max_completion_tokens` are mutually exclusive.
  *
  * `response_format` is deliberately absent — the chat activity owns it via
  * `outputSchema` / structured output, and Ark rejects `json_object` outright
  * on every model.
  */
 
-/**
- * Reasoning ("deep thinking") switch.
- *
- * - `enabled` — the model reasons before answering (default on every model
- *   except `deepseek-v3-2-251201`, where reasoning defaults to off).
- * - `disabled` — skip reasoning.
- * - `auto` — let the model decide. Only accepted by `gpt-oss-120b-250805`.
- */
-export interface BytePlusThinkingOption {
-  type: 'enabled' | 'disabled' | 'auto'
-}
-
-/**
- * Reasoning budget hint. `none` and `xhigh` are only accepted by
- * `glm-5-2-260617`; `max` by `glm-5-2-260617` and the `deepseek-v4-*` models.
- *
- * Cannot be combined with `thinking: {type: 'disabled'}` — Ark rejects the
- * pair with `400 InvalidParameter` ("Invalid combination of reasoning_effort
- * and thinking type").
- */
-export type BytePlusReasoningEffort =
-  | 'none'
-  | 'minimal'
-  | 'low'
-  | 'medium'
-  | 'high'
-  | 'xhigh'
-  | 'max'
-
 /**
  * Request routing tier. `flex` routes to the batch queue at a lower price with
  * no latency guarantee; `default` is the standard online tier.
@@ -77,12 +47,6 @@ export interface BytePlusTextProviderOptions {
   // Ark-only
   // --------------------------------------------------------------------
 
-  /** Reasoning switch — see {@link BytePlusThinkingOption}. */
-  thinking?: BytePlusThinkingOption
-
-  /** Reasoning budget hint — see {@link BytePlusReasoningEffort}. */
-  reasoning_effort?: BytePlusReasoningEffort
-
   /**
    * Penalty applied to repeated tokens. Values above 1 discourage repetition.
    */
diff --git a/packages/ai-byteplus/tests/text.test.ts b/packages/ai-byteplus/tests/text.test.ts
index 9311d15328..39baa8b107 100644
--- a/packages/ai-byteplus/tests/text.test.ts
+++ b/packages/ai-byteplus/tests/text.test.ts
@@ -506,7 +506,7 @@ describe('BytePlus text adapter', () => {
   })
 
   describe('provider options', () => {
-    it('forwards Ark-only and sampling options into the request body', async () => {
+    it('forwards Ark-only options, sampling options, and chat({ reasoning })', async () => {
       const mockCreate = setupMockSdkClient([
         {
           id: 'chatcmpl-opts',
@@ -517,8 +517,6 @@ describe('BytePlus text adapter', () => {
       const adapter = createBytePlusText('seed-2-0-lite-260428', 'ark-test-key')
 
       const modelOptions: BytePlusTextProviderOptions = {
-        thinking: { type: 'enabled' },
-        reasoning_effort: 'high',
         repetition_penalty: 1.05,
         service_tier: 'flex',
         temperature: 0.4,
@@ -530,6 +528,7 @@ describe('BytePlus text adapter', () => {
           model: 'seed-2-0-lite-260428',
           messages: [{ role: 'user', content: 'Hello' }],
           modelOptions,
+          reasoning: { level: 'high', summary: true },
           logger: testLogger,
         }),
       )
@@ -547,6 +546,42 @@ describe('BytePlus text adapter', () => {
     })
   })
 
+  describe('chat({ reasoning })', () => {
+    async function requestFor(
+      model: 'glm-4-7-251222' | 'glm-5-2-260617',
+      level: 'off' | 'high',
+    ) {
+      const mockCreate = setupMockSdkClient([
+        {
+          id: 'chatcmpl-reasoning',
+          model,
+          choices: [{ index: 0, delta: {}, finish_reason: 'stop' }],
+        },
+      ])
+      await collect(
+        createBytePlusText(model, 'ark-test-key').chatStream({
+          model,
+          messages: [{ role: 'user', content: 'Hello' }],
+          reasoning: { level, summary: true },
+          logger: testLogger,
+        }),
+      )
+      return mockCreate.mock.calls[0]?.[0] as Record<string, unknown>
+    }
+
+    it('off sends thinking disabled and no effort', async () => {
+      const body = await requestFor('glm-5-2-260617', 'off')
+      expect(body.thinking).toEqual({ type: 'disabled' })
+      expect(body).not.toHaveProperty('reasoning_effort')
+    })
+
+    it('an on/off model sends thinking enabled and no effort', async () => {
+      const body = await requestFor('glm-4-7-251222', 'high')
+      expect(body.thinking).toEqual({ type: 'enabled' })
+      expect(body).not.toHaveProperty('reasoning_effort')
+    })
+  })
+
   describe('multimodal content parts', () => {
     async function contentPartsFor(parts: Array<ContentPart>): Promise<any> {
       const mockCreate = setupMockSdkClient([
diff --git a/packages/ai-claude-code/src/adapters/text.ts b/packages/ai-claude-code/src/adapters/text.ts
index c69b575b14..1653ff097f 100644
--- a/packages/ai-claude-code/src/adapters/text.ts
+++ b/packages/ai-claude-code/src/adapters/text.ts
@@ -1,6 +1,8 @@
 import { EventType, normalizeSystemPrompts } from '@tanstack/ai'
 import {
   appendOutputSchemaInstruction,
+  reasoningBudget,
+  resolveReasoning,
   toRunErrorRawEvent,
 } from '@tanstack/ai/adapter-internals'
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
@@ -29,6 +31,7 @@ import { buildPrompt } from '../messages/prompt'
 import { translateSdkStream } from '../stream/translate'
 import { mapPolicyToClaudeFlags } from './policy-map'
 import { projectClaudeWorkspace } from './projection'
+import { CLAUDE_CODE_MODEL_REASONING } from '../model-reasoning'
 import {
   CLAUDE_JSON_SCHEMA_PLACEHOLDER,
   CLAUDE_RUNNER_SOURCE,
@@ -50,9 +53,11 @@ import type {
   DefaultMessageMetadataByModality,
   Modality,
   AdapterYieldChunk,
+  ReasoningRequest,
   TextOptions,
 } from '@tanstack/ai'
 import type { ClaudeCodeModel } from '../model-meta'
+import type { ClaudeCodeModelReasoningByName } from '../model-reasoning'
 import type { ClaudeCodeTextProviderOptions } from '../provider-options'
 import type { AgentSdkMessage } from '../stream/sdk-types'
 
@@ -155,6 +160,43 @@ function bridgeToMcpConfig(bridge: HostToolBridge): string {
   })
 }
 
+/** The reasoning levels of a model, for `chat({ reasoning })`. `never`: none. */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof ClaudeCodeModelReasoningByName
+    ? ClaudeCodeModelReasoningByName[TModel]
+    : never
+
+/**
+ * The CLI settings for `chat({ reasoning })`, from the Claude Code docs:
+ * - a model with effort levels: `--effort <level>`.
+ * - a budget model (Haiku): `MAX_THINKING_TOKENS`, the budget (pi's table
+ *   when the request sets none), or `0` for `off`.
+ */
+export function claudeCodeReasoning(
+  model: string,
+  request: ReasoningRequest | undefined,
+): { args: Array<string>; env: Record<string, string> } {
+  const reasoning = CLAUDE_CODE_MODEL_REASONING[model]
+  const resolved = resolveReasoning(request, reasoning)
+  if (!resolved || !reasoning) return { args: [], env: {} }
+  if (reasoning.map) {
+    return resolved.value === null
+      ? { args: [], env: {} }
+      : { args: ['--effort', resolved.value], env: {} }
+  }
+  const budget =
+    resolved.level === 'off'
+      ? 0
+      : reasoningBudget({
+          level: resolved.level,
+          summary: resolved.summary,
+          ...(resolved.budgetTokens !== undefined
+            ? { budgetTokens: resolved.budgetTokens }
+            : {}),
+        })
+  return { args: [], env: { MAX_THINKING_TOKENS: String(budget) } }
+}
+
 export class ClaudeCodeTextAdapter<
   TModel extends ClaudeCodeModel,
 > extends BaseTextAdapter<
@@ -164,7 +206,8 @@ export class ClaudeCodeTextAdapter<
   DefaultMessageMetadataByModality,
   ReadonlyArray<string>,
   unknown,
-  never
+  never,
+  ResolveReasoning<TModel>
 > {
   readonly name = 'claude-code' as const
 
@@ -240,6 +283,7 @@ export class ClaudeCodeTextAdapter<
 
     if (config.streamPartials !== false) args.push('--include-partial-messages')
     if (resume !== undefined) args.push('--resume', resume)
+    args.push(...claudeCodeReasoning(this.model, options.reasoning).args)
 
     const permissionMode =
       modelOptions?.permissionMode ??
@@ -565,6 +609,7 @@ export class ClaudeCodeTextAdapter<
               }),
           ...(injectApiKey ? hostClaudeAuthEnv() : {}),
           ...localProcessHomeEnv(sandbox.provider),
+          ...claudeCodeReasoning(this.model, options.reasoning).env,
           ...this.adapterConfig.env,
         },
         ...(options.abortController?.signal
diff --git a/packages/ai-claude-code/tests/reasoning-options.test.ts b/packages/ai-claude-code/tests/reasoning-options.test.ts
new file mode 100644
index 0000000000..00bb34038b
--- /dev/null
+++ b/packages/ai-claude-code/tests/reasoning-options.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+import { claudeCodeReasoning } from '../src/adapters/text'
+
+describe('Claude Code chat({ reasoning }) CLI settings', () => {
+  it('effort models: --effort with the level', () => {
+    expect(
+      claudeCodeReasoning('claude-opus-4-8', { level: 'xhigh', summary: true }),
+    ).toEqual({ args: ['--effort', 'xhigh'], env: {} })
+    // claude-opus-4-8 has no minimal: it clamps up to low.
+    expect(
+      claudeCodeReasoning('opus', { level: 'minimal', summary: true }).args,
+    ).toEqual(['--effort', 'low'])
+  })
+
+  it('budget models: MAX_THINKING_TOKENS, 0 for off', () => {
+    expect(
+      claudeCodeReasoning('claude-haiku-4-5', {
+        level: 'medium',
+        summary: true,
+      }),
+    ).toEqual({ args: [], env: { MAX_THINKING_TOKENS: '8192' } })
+    expect(
+      claudeCodeReasoning('haiku', { level: 'off', summary: true }).env,
+    ).toEqual({ MAX_THINKING_TOKENS: '0' })
+  })
+
+  it('sends nothing without a request', () => {
+    expect(claudeCodeReasoning('opus', undefined)).toEqual({
+      args: [],
+      env: {},
+    })
+  })
+})
diff --git a/packages/ai-cloudflare/src/adapters/text.ts b/packages/ai-cloudflare/src/adapters/text.ts
index 4751f06ac3..4100ed7fc6 100644
--- a/packages/ai-cloudflare/src/adapters/text.ts
+++ b/packages/ai-cloudflare/src/adapters/text.ts
@@ -1,5 +1,7 @@
 import OpenAI from 'openai'
 import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
+import { resolveReasoning } from '@tanstack/ai/adapter-internals'
+import { CLOUDFLARE_MODEL_REASONING } from '../model-reasoning'
 import {
   gatewayHeaders,
   isBindingConfig,
@@ -17,12 +19,24 @@ import type {
   CloudflareTextRestConfig,
 } from '../utils/config'
 import type { CloudflareTextModel } from '../utils/models'
-import type { ModelMessage } from '@tanstack/ai'
+import type {
+  DefaultMessageMetadataByModality,
+  Modality,
+  ModelMessage,
+  TextOptions,
+} from '@tanstack/ai'
+import type { CloudflareModelReasoningByName } from '../model-reasoning'
+
+/** The reasoning levels of a model, for `chat({ reasoning })`. `never`: none. */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof CloudflareModelReasoningByName
+    ? CloudflareModelReasoningByName[TModel]
+    : never
 
 /**
  * Chat Completions parameters forwarded verbatim to Workers AI. Reasoning
- * models (GLM, Kimi, gpt-oss, QwQ) read `reasoning_effort` and
- * `chat_template_kwargs`; `null` for `reasoning_effort` turns reasoning off.
+ * effort is set with `chat({ reasoning })`; reasoning models (GLM, Kimi,
+ * gpt-oss, QwQ) also read `chat_template_kwargs`.
  */
 export interface CloudflareTextProviderOptions {
   temperature?: number
@@ -33,7 +47,6 @@ export interface CloudflareTextProviderOptions {
   repetition_penalty?: number
   frequency_penalty?: number
   presence_penalty?: number
-  reasoning_effort?: 'low' | 'medium' | 'high' | null
   chat_template_kwargs?: {
     enable_thinking?: boolean
     clear_thinking?: boolean
@@ -77,7 +90,14 @@ function createClient(config: CloudflareTextConfig): OpenAI {
 export class CloudflareTextAdapter<
   TModel extends CloudflareTextModel,
   TProviderOptions extends Record<string, any> = CloudflareTextProviderOptions,
-> extends OpenAIBaseChatCompletionsTextAdapter<TModel, TProviderOptions> {
+> extends OpenAIBaseChatCompletionsTextAdapter<
+  TModel,
+  TProviderOptions,
+  ReadonlyArray<Modality>,
+  DefaultMessageMetadataByModality,
+  ReadonlyArray<string>,
+  ResolveReasoning<TModel>
+> {
   override readonly kind = 'text' as const
   override readonly name = 'cloudflare' as const
 
@@ -85,6 +105,25 @@ export class CloudflareTextAdapter<
     super(model, 'cloudflare', createClient(config), config)
   }
 
+  /**
+   * `chat({ reasoning })` as `reasoning_effort`. Workers AI turns reasoning
+   * off with `null`, so `off` sends `null`, not the model's off value.
+   */
+  protected override mapOptionsToRequest(options: TextOptions) {
+    const request = super.mapOptionsToRequest(options)
+    const resolved = resolveReasoning(
+      options.reasoning,
+      CLOUDFLARE_MODEL_REASONING[options.model],
+    )
+    if (resolved) {
+      Object.assign(request, {
+        reasoning_effort:
+          resolved.level === 'off' ? null : (resolved.value ?? resolved.level),
+      })
+    }
+    return request
+  }
+
   /**
    * Workers AI validates `messages[].content` as a string, so a tool-call-only
    * assistant turn (which OpenAI accepts as `content: null`) is sent as `''`.
diff --git a/packages/ai-cloudflare/tests/reasoning-request.test.ts b/packages/ai-cloudflare/tests/reasoning-request.test.ts
new file mode 100644
index 0000000000..ed066cc4cd
--- /dev/null
+++ b/packages/ai-cloudflare/tests/reasoning-request.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { CloudflareTextAdapter } from '../src/adapters/text'
+import type { ReasoningRequest } from '@tanstack/ai'
+
+const logger = resolveDebugOption(false)
+const model = '@cf/deepseek-ai/deepseek-v4-flash-0731'
+
+class Probe extends CloudflareTextAdapter<typeof model> {
+  request(reasoning: ReasoningRequest | undefined) {
+    return this.mapOptionsToRequest({
+      model,
+      logger,
+      messages: [{ role: 'user', content: 'hi' }],
+      ...(reasoning ? { reasoning } : {}),
+    })
+  }
+}
+
+describe('Cloudflare chat({ reasoning }) request shape', () => {
+  const adapter = new Probe({ accountId: 'a', apiKey: 'k' }, model)
+
+  it('sends the level effort', () => {
+    expect(adapter.request({ level: 'max', summary: true })).toMatchObject({
+      reasoning_effort: 'max',
+    })
+  })
+
+  it('sends null for off', () => {
+    expect(
+      adapter.request({ level: 'off', summary: true }).reasoning_effort,
+    ).toBeNull()
+  })
+
+  it('sends nothing without a request', () => {
+    expect(adapter.request(undefined)).not.toHaveProperty('reasoning_effort')
+  })
+})
diff --git a/packages/ai-codex/src/adapters/text.ts b/packages/ai-codex/src/adapters/text.ts
index c5a9a3cac4..dfce320385 100644
--- a/packages/ai-codex/src/adapters/text.ts
+++ b/packages/ai-codex/src/adapters/text.ts
@@ -1,5 +1,8 @@
 import { EventType, normalizeSystemPrompts } from '@tanstack/ai'
-import { toRunErrorRawEvent } from '@tanstack/ai/adapter-internals'
+import {
+  resolveReasoning,
+  toRunErrorRawEvent,
+} from '@tanstack/ai/adapter-internals'
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
 import {
   SandboxCapability,
@@ -23,6 +26,7 @@ import { buildPrompt } from '../messages/prompt'
 import { translateThreadEvents } from '../stream/translate'
 import { projectCodexWorkspace } from './projection'
 import { mapPolicyToCodexFlags } from './policy-map'
+import { CODEX_MODEL_REASONING } from '../model-reasoning'
 import type { CodexPolicyFlags } from './policy-map'
 import type { HostToolBridge, SandboxHandle } from '@tanstack/ai-sandbox'
 import type {
@@ -33,9 +37,11 @@ import type {
   DefaultMessageMetadataByModality,
   Modality,
   AdapterYieldChunk,
+  ReasoningRequest,
   TextOptions,
 } from '@tanstack/ai'
 import type { CodexModel } from '../model-meta'
+import type { CodexModelReasoningByName } from '../model-reasoning'
 import type { CodexTextProviderOptions } from '../provider-options'
 import type { CodexThreadEvent } from '../stream/sdk-types'
 
@@ -77,7 +83,10 @@ export interface CodexTextConfig {
   sandboxMode?: CodexSandboxMode
   /** Codex approval policy (`--config approval_policy=`). Defaults to `'never'`. */
   approvalPolicy?: CodexApprovalMode
-  /** Model reasoning effort (`--config model_reasoning_effort=`). */
+  /**
+   * The default reasoning effort (`--config model_reasoning_effort=`) when a
+   * call sets no `chat({ reasoning })`.
+   */
   modelReasoningEffort?: 'minimal' | 'low' | 'medium' | 'high'
   /** Skip Codex's git-repo safety check (`--skip-git-repo-check`). Defaults to true. */
   skipGitRepoCheck?: boolean
@@ -104,6 +113,26 @@ function q(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`
 }
 
+/** The reasoning levels of a model, for `chat({ reasoning })`. `never`: none. */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof CodexModelReasoningByName
+    ? CodexModelReasoningByName[TModel]
+    : never
+
+/**
+ * Codex's `model_reasoning_effort` for `chat({ reasoning })`: the model's
+ * effort for the level, or `fallback` when the call sets none.
+ */
+export function codexReasoningEffort(
+  model: string,
+  request: ReasoningRequest | undefined,
+  fallback: string | undefined,
+): string | undefined {
+  return (
+    resolveReasoning(request, CODEX_MODEL_REASONING[model])?.value ?? fallback
+  )
+}
+
 export class CodexTextAdapter<
   TModel extends CodexModel,
 > extends BaseTextAdapter<
@@ -113,7 +142,8 @@ export class CodexTextAdapter<
   DefaultMessageMetadataByModality,
   ReadonlyArray<string>,
   unknown,
-  never
+  never,
+  ResolveReasoning<TModel>
 > {
   readonly name = 'codex' as const
 
@@ -182,8 +212,11 @@ export class CodexTextAdapter<
       'never'
     const networkAccessEnabled =
       config.networkAccessEnabled ?? policyFlags.networkAccessEnabled
-    const reasoning =
-      modelOptions?.modelReasoningEffort ?? config.modelReasoningEffort
+    const reasoning = codexReasoningEffort(
+      this.model,
+      options.reasoning,
+      config.modelReasoningEffort,
+    )
     const skipGitRepoCheck =
       modelOptions?.skipGitRepoCheck ?? config.skipGitRepoCheck
 
diff --git a/packages/ai-codex/src/provider-options.ts b/packages/ai-codex/src/provider-options.ts
index 54d82bfb2f..48c78472e5 100644
--- a/packages/ai-codex/src/provider-options.ts
+++ b/packages/ai-codex/src/provider-options.ts
@@ -14,8 +14,6 @@ export interface CodexTextProviderOptions {
   sandboxMode?: 'read-only' | 'workspace-write' | 'danger-full-access'
   /** Per-call override of the configured approval policy. */
   approvalPolicy?: 'never' | 'on-failure' | 'on-request' | 'untrusted'
-  /** Per-call override of the model reasoning effort. */
-  modelReasoningEffort?: 'minimal' | 'low' | 'medium' | 'high'
   /** Per-call override of the harness working directory. */
   workingDirectory?: string
   /** Per-call override of the git-repo safety check (defaults to skipping). */
diff --git a/packages/ai-codex/tests/reasoning-effort.test.ts b/packages/ai-codex/tests/reasoning-effort.test.ts
new file mode 100644
index 0000000000..98d69a88d5
--- /dev/null
+++ b/packages/ai-codex/tests/reasoning-effort.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import { codexReasoningEffort } from '../src/adapters/text'
+
+describe('Codex chat({ reasoning }) effort', () => {
+  it('uses the model effort for the level', () => {
+    expect(
+      codexReasoningEffort(
+        'gpt-5.2-codex',
+        { level: 'xhigh', summary: true },
+        undefined,
+      ),
+    ).toBe('xhigh')
+  })
+
+  it('clamps a level the model does not have', () => {
+    // gpt-5.1-codex has no minimal: it clamps up to low.
+    expect(
+      codexReasoningEffort(
+        'gpt-5.1-codex',
+        { level: 'minimal', summary: true },
+        undefined,
+      ),
+    ).toBe('low')
+  })
+
+  it('falls back to the adapter default without a request', () => {
+    expect(codexReasoningEffort('gpt-5.1-codex', undefined, 'high')).toBe(
+      'high',
+    )
+    expect(
+      codexReasoningEffort('gpt-5.1-codex', undefined, undefined),
+    ).toBeUndefined()
+  })
+})
diff --git a/packages/ai-groq/src/adapters/text.ts b/packages/ai-groq/src/adapters/text.ts
index 61affd3f9a..2bc769eec7 100644
--- a/packages/ai-groq/src/adapters/text.ts
+++ b/packages/ai-groq/src/adapters/text.ts
@@ -1,6 +1,8 @@
 import OpenAI from 'openai'
 import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
 import { GROQ_MODEL_INPUT_MODALITIES } from '../model-meta'
+import { GROQ_MODEL_REASONING } from '../model-reasoning'
+import type { GroqModelReasoningByName } from '../model-reasoning'
 import { getGroqApiKeyFromEnv, withGroqDefaults } from '../utils/client'
 import { makeGroqStructuredOutputCompatibleWithMap } from '../utils/schema-converter'
 import type { Modality, TextOptions } from '@tanstack/ai'
@@ -14,6 +16,12 @@ import type { GroqMessageMetadataByModality } from '../message-types'
 import type { GroqClientConfig } from '../utils/client'
 import type { OpenAIBaseTextAdapterOptions } from '@tanstack/openai-base'
 
+/** The reasoning levels of a model, for `chat({ reasoning })`. `never`: none. */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof GroqModelReasoningByName
+    ? GroqModelReasoningByName[TModel]
+    : never
+
 type ResolveToolCapabilities<TModel extends string> =
   TModel extends keyof GroqChatModelToolCapabilitiesByName
     ? NonNullable<GroqChatModelToolCapabilitiesByName[TModel]>
@@ -55,7 +63,8 @@ export class GroqTextAdapter<
   TProviderOptions,
   TInputModalities,
   GroqMessageMetadataByModality,
-  TToolCapabilities
+  TToolCapabilities,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   override readonly name = 'groq' as const
@@ -65,6 +74,10 @@ export class GroqTextAdapter<
     super(model, 'groq', new OpenAI(withGroqDefaults(config)), config)
   }
 
+  protected override modelReasoning(model: string) {
+    return GROQ_MODEL_REASONING[model]
+  }
+
   protected override extractRejectedToolCall(
     rawEvent: unknown,
     fallbackMessage: string,
diff --git a/packages/ai-groq/src/model-reasoning.ts b/packages/ai-groq/src/model-reasoning.ts
index b726235c80..ecaf5408c0 100644
--- a/packages/ai-groq/src/model-reasoning.ts
+++ b/packages/ai-groq/src/model-reasoning.ts
@@ -12,7 +12,7 @@ export type GroqModelReasoningByName = {
     levels: 'low' | 'medium' | 'high'
     budget: false
   }
-  'qwen/qwen3-32b': { levels: 'off' | 'high'; budget: true }
+  'qwen/qwen3-32b': { levels: 'off' | 'high'; budget: false }
 }
 
 /** The same data at runtime. `false`: the model does not reason. */
@@ -62,7 +62,15 @@ export const GROQ_MODEL_REASONING: Readonly<Record<string, ModelReasoning>> = {
   },
   'moonshotai/kimi-k2-instruct-0905': false,
   'qwen/qwen3-32b': {
-    map: { off: 'off', minimal: null, low: null, medium: null, high: 'high' },
-    budget: true,
+    map: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: 'default',
+      xhigh: null,
+      max: null,
+    },
+    budget: false,
   },
 }
diff --git a/packages/ai-groq/src/text/text-provider-options.ts b/packages/ai-groq/src/text/text-provider-options.ts
index 5fc9fc226c..b3c3083971 100644
--- a/packages/ai-groq/src/text/text-provider-options.ts
+++ b/packages/ai-groq/src/text/text-provider-options.ts
@@ -89,14 +89,6 @@ export interface GroqTextProviderOptions {
    */
   presence_penalty?: number | null
 
-  /**
-   * Controls reasoning effort for supported models.
-   *
-   * - qwen3 models: `'none'` to disable, `'default'` or null to enable
-   * - openai/gpt-oss models: `'low'`, `'medium'` (default), or `'high'`
-   */
-  reasoning_effort?: 'none' | 'default' | 'low' | 'medium' | 'high' | null
-
   /**
    * Specifies how to output reasoning tokens.
    * This field is mutually exclusive with `include_reasoning`.
diff --git a/packages/ai-groq/tests/reasoning-request.test.ts b/packages/ai-groq/tests/reasoning-request.test.ts
new file mode 100644
index 0000000000..80489fa04e
--- /dev/null
+++ b/packages/ai-groq/tests/reasoning-request.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { GroqTextAdapter } from '../src/adapters/text'
+import type { ReasoningRequest } from '@tanstack/ai'
+import type { GROQ_CHAT_MODELS } from '../src/model-meta'
+
+const logger = resolveDebugOption(false)
+
+class Probe<
+  TModel extends (typeof GROQ_CHAT_MODELS)[number],
+> extends GroqTextAdapter<TModel> {
+  request(reasoning: ReasoningRequest) {
+    return this.mapOptionsToRequest({
+      model: this.model,
+      logger,
+      messages: [{ role: 'user', content: 'hi' }],
+      reasoning,
+    })
+  }
+}
+
+describe('Groq chat({ reasoning }) request shape', () => {
+  it('gpt-oss: reasoning_effort from the level', () => {
+    const adapter = new Probe({ apiKey: 'k' }, 'openai/gpt-oss-120b')
+    expect(adapter.request({ level: 'medium', summary: true })).toMatchObject({
+      reasoning_effort: 'medium',
+    })
+  })
+
+  it('Qwen 3: default to think, none for off', () => {
+    const adapter = new Probe({ apiKey: 'k' }, 'qwen/qwen3-32b')
+    expect(adapter.request({ level: 'high', summary: true })).toMatchObject({
+      reasoning_effort: 'default',
+    })
+    expect(adapter.request({ level: 'off', summary: true })).toMatchObject({
+      reasoning_effort: 'none',
+    })
+  })
+})
diff --git a/packages/ai-ollama/src/adapters/text.ts b/packages/ai-ollama/src/adapters/text.ts
index 48a9c6a35f..84a238ad83 100644
--- a/packages/ai-ollama/src/adapters/text.ts
+++ b/packages/ai-ollama/src/adapters/text.ts
@@ -5,6 +5,7 @@ import {
   unsupportedFileSourceError,
 } from '@tanstack/ai'
 import {
+  resolveReasoning,
   toRunErrorPayload,
   toRunErrorRawEvent,
 } from '@tanstack/ai/adapter-internals'
@@ -12,6 +13,8 @@ import { BaseTextAdapter } from '@tanstack/ai/adapters'
 import { buildOllamaUsage } from '../usage'
 import { createOllamaClient, generateId, getOllamaHostFromEnv } from '../utils'
 import { convertToolsToProviderFormat } from '../tools/tool-converter'
+import { OLLAMA_MODEL_REASONING } from '../model-reasoning'
+import type { OllamaModelReasoningByName } from '../model-reasoning'
 import type { OllamaClientConfig } from '../utils/client'
 
 import type {
@@ -32,7 +35,13 @@ import type {
   Tool as OllamaTool,
   ToolCall,
 } from 'ollama'
-import type { AdapterYieldChunk, TextOptions, Tool } from '@tanstack/ai'
+import type {
+  AdapterYieldChunk,
+  ModelReasoning,
+  ReasoningRequest,
+  TextOptions,
+  Tool,
+} from '@tanstack/ai'
 
 export type OllamaTextModel =
   | (typeof OLLAMA_TEXT_MODELS)[number]
@@ -45,7 +54,53 @@ export type OllamaTextModel =
 type ResolveModelOptions<TModel extends string> =
   TModel extends keyof OllamaChatModelOptionsByName
     ? OllamaChatModelOptionsByName[TModel]
-    : ChatRequest
+    : Omit<ChatRequest, 'think'>
+
+/**
+ * The reasoning levels of a model, for `chat({ reasoning })`. A model name
+ * that this package does not list gets the common on/off toggle. `never`: a
+ * listed model that does not reason.
+ */
+type ResolveReasoning<TModel extends string> =
+  TModel extends keyof OllamaModelReasoningByName
+    ? OllamaModelReasoningByName[TModel]
+    : TModel extends keyof OllamaChatModelOptionsByName
+      ? never
+      : { levels: 'off' | 'high'; budget: false }
+
+/** The on/off toggle for a model name this package does not list. */
+const UNLISTED_MODEL_REASONING: ModelReasoning = {
+  map: {
+    off: 'false',
+    minimal: null,
+    low: null,
+    medium: null,
+    high: 'true',
+    xhigh: null,
+    max: null,
+  },
+  budget: false,
+}
+
+/**
+ * Ollama's `think` for `chat({ reasoning })`: `true` or `false` for a model
+ * with the on/off toggle, the level name for gpt-oss.
+ */
+function ollamaThink(
+  request: ReasoningRequest | undefined,
+  model: string,
+): { think?: boolean | 'low' | 'medium' | 'high' } {
+  const reasoning =
+    model in OLLAMA_MODEL_REASONING
+      ? OLLAMA_MODEL_REASONING[model]
+      : UNLISTED_MODEL_REASONING
+  const value = resolveReasoning(request, reasoning)?.value
+  if (value === 'true' || value === 'false') return { think: value === 'true' }
+  if (value === 'low' || value === 'medium' || value === 'high') {
+    return { think: value }
+  }
+  return {}
+}
 
 export interface OllamaTextAdapterOptions {
   model?: OllamaTextModel
@@ -79,7 +134,11 @@ export class OllamaTextAdapter<TModel extends string> extends BaseTextAdapter<
   TModel,
   ResolveModelOptions<TModel>,
   OllamaInputModalities,
-  OllamaMessageMetadataByModality
+  OllamaMessageMetadataByModality,
+  ReadonlyArray<string>,
+  unknown,
+  never,
+  ResolveReasoning<TModel>
 > {
   override readonly kind = 'text' as const
   readonly name = 'ollama' as const
@@ -557,10 +616,10 @@ export class OllamaTextAdapter<TModel extends string> extends BaseTextAdapter<
       // object avoids aliasing the caller's modelOptions.options.
       options: { ...modelOptions?.options },
       // Request-level fields the nested modelOptions surface exposes
-      // (OllamaChatRequest): format / keep_alive / logprobs / top_logprobs, plus
-      // `think` for models whose options type includes OllamaChatRequestThinking.
+      // (OllamaChatRequest): format / keep_alive / logprobs / top_logprobs.
       // Read structurally and only forwarded when present. `stream` is set by
       // the call sites (chatStream / structuredOutput), so it is not forwarded.
+      // `think` comes from `chat({ reasoning })`.
       ...(modelOptions?.format !== undefined && {
         format: modelOptions.format,
       }),
@@ -573,11 +632,7 @@ export class OllamaTextAdapter<TModel extends string> extends BaseTextAdapter<
       ...(modelOptions?.top_logprobs !== undefined && {
         top_logprobs: modelOptions.top_logprobs,
       }),
-      ...(modelOptions &&
-      'think' in modelOptions &&
-      modelOptions.think !== undefined
-        ? { think: modelOptions.think }
-        : {}),
+      ...ollamaThink(options.reasoning, model),
       ...(convertedTools !== undefined && { tools: convertedTools }),
     }
   }
diff --git a/packages/ai-ollama/src/meta/model-meta-deepseek-r1.ts b/packages/ai-ollama/src/meta/model-meta-deepseek-r1.ts
index 4c6c150e19..0e81b9c91c 100644
--- a/packages/ai-ollama/src/meta/model-meta-deepseek-r1.ts
+++ b/packages/ai-ollama/src/meta/model-meta-deepseek-r1.ts
@@ -1,7 +1,6 @@
 import type {
   OllamaChatRequest,
   OllamaChatRequestMessages,
-  OllamaChatRequestThinking,
   OllamaChatRequestTools,
   OllamaMessageThinking,
   OllamaMessageTools,
@@ -20,8 +19,7 @@ const DEEPSEEK_R1_LATEST = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 const DEEPSEEK_R1_1_5b = {
@@ -36,8 +34,7 @@ const DEEPSEEK_R1_1_5b = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 const DEEPSEEK_R1_7b = {
@@ -52,8 +49,7 @@ const DEEPSEEK_R1_7b = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 const DEEPSEEK_R1_8b = {
@@ -68,8 +64,7 @@ const DEEPSEEK_R1_8b = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 const DEEPSEEK_R1_32b = {
@@ -84,8 +79,7 @@ const DEEPSEEK_R1_32b = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 const DEEPSEEK_R1_70b = {
@@ -100,8 +94,7 @@ const DEEPSEEK_R1_70b = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 const DEEPSEEK_R1_671b = {
@@ -116,8 +109,7 @@ const DEEPSEEK_R1_671b = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 export const DEEPSEEK_R1_MODELS = [
@@ -145,32 +137,25 @@ export type DeepseekR1ChatModelProviderOptionsByName = {
   // Models with thinking and structured output support
   [DEEPSEEK_R1_LATEST.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
   [DEEPSEEK_R1_1_5b.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
   [DEEPSEEK_R1_7b.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
   [DEEPSEEK_R1_8b.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
   [DEEPSEEK_R1_32b.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
   [DEEPSEEK_R1_70b.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
   [DEEPSEEK_R1_671b.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 }
 
 export type DeepseekR1ModelInputModalitiesByName = {
diff --git a/packages/ai-ollama/src/meta/model-meta-deepseek-v3.1.ts b/packages/ai-ollama/src/meta/model-meta-deepseek-v3.1.ts
index 1c474c87a2..ab9b577d69 100644
--- a/packages/ai-ollama/src/meta/model-meta-deepseek-v3.1.ts
+++ b/packages/ai-ollama/src/meta/model-meta-deepseek-v3.1.ts
@@ -1,7 +1,6 @@
 import type {
   OllamaChatRequest,
   OllamaChatRequestMessages,
-  OllamaChatRequestThinking,
   OllamaChatRequestTools,
   OllamaMessageTools,
   OllamaModelMeta,
@@ -19,8 +18,7 @@ const DEEPSEEK_V3_1_LATEST = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 const DEEPSEEK_V3_1_671b = {
@@ -36,8 +34,7 @@ const DEEPSEEK_V3_1_671b = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 const DEEPSEEK_V3_1_671b_cloud = {
@@ -52,8 +49,7 @@ const DEEPSEEK_V3_1_671b_cloud = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 export const DEEPSEEK_V3_1_MODELS = [
@@ -77,16 +73,13 @@ export type Deepseekv3_1ChatModelProviderOptionsByName = {
   // Models with thinking and structured output support
   [DEEPSEEK_V3_1_LATEST.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
   [DEEPSEEK_V3_1_671b.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
   [DEEPSEEK_V3_1_671b_cloud.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 }
 
 export type Deepseekv3_1ModelInputModalitiesByName = {
diff --git a/packages/ai-ollama/src/meta/model-meta-gpt-oss.ts b/packages/ai-ollama/src/meta/model-meta-gpt-oss.ts
index 8c8cff1013..2c16137db8 100644
--- a/packages/ai-ollama/src/meta/model-meta-gpt-oss.ts
+++ b/packages/ai-ollama/src/meta/model-meta-gpt-oss.ts
@@ -1,7 +1,6 @@
 import type {
   OllamaChatRequest,
   OllamaChatRequestMessages,
-  OllamaChatRequestThinking_OpenAI,
   OllamaChatRequestTools,
   OllamaMessageThinking,
   OllamaMessageTools,
@@ -20,8 +19,7 @@ const OPT_OSS_LATEST = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking_OpenAI
+    OllamaChatRequestTools
 >
 
 const OPT_OSS_20b = {
@@ -36,8 +34,7 @@ const OPT_OSS_20b = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking_OpenAI
+    OllamaChatRequestTools
 >
 
 const OPT_OSS_120b = {
@@ -52,8 +49,7 @@ const OPT_OSS_120b = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking_OpenAI
+    OllamaChatRequestTools
 >
 
 export const GPT_OSS_MODELS = [
@@ -77,16 +73,13 @@ export type GptOssChatModelProviderOptionsByName = {
   // Models with thinking and structured output support
   [OPT_OSS_LATEST.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking_OpenAI
+    OllamaChatRequestTools
   [OPT_OSS_20b.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking_OpenAI
+    OllamaChatRequestTools
   [OPT_OSS_120b.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking_OpenAI
+    OllamaChatRequestTools
 }
 
 export type GptOssModelInputModalitiesByName = {
diff --git a/packages/ai-ollama/src/meta/model-meta-qwen3.ts b/packages/ai-ollama/src/meta/model-meta-qwen3.ts
index 95be176601..e9d4f3bb86 100644
--- a/packages/ai-ollama/src/meta/model-meta-qwen3.ts
+++ b/packages/ai-ollama/src/meta/model-meta-qwen3.ts
@@ -1,7 +1,6 @@
 import type {
   OllamaChatRequest,
   OllamaChatRequestMessages,
-  OllamaChatRequestThinking,
   OllamaChatRequestTools,
   OllamaMessageThinking,
   OllamaMessageTools,
@@ -20,8 +19,7 @@ const QWEN3_LATEST = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 const QWEN3_0_6b = {
@@ -36,8 +34,7 @@ const QWEN3_0_6b = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 const QWEN3_1_7b = {
@@ -52,8 +49,7 @@ const QWEN3_1_7b = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 const QWEN3_4b = {
@@ -68,8 +64,7 @@ const QWEN3_4b = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 const QWEN3_8b = {
@@ -84,8 +79,7 @@ const QWEN3_8b = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 const QWEN3_14b = {
@@ -100,8 +94,7 @@ const QWEN3_14b = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 const QWEN3_30b = {
@@ -116,8 +109,7 @@ const QWEN3_30b = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 const QWEN3_32b = {
@@ -132,8 +124,7 @@ const QWEN3_32b = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 const QWEN3_235b = {
@@ -148,8 +139,7 @@ const QWEN3_235b = {
 } as const satisfies OllamaModelMeta<
   OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 >
 
 export const QWEN3_MODELS = [
@@ -179,40 +169,31 @@ export type Qwen3ChatModelProviderOptionsByName = {
   // Models with thinking and structured output support
   [QWEN3_LATEST.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
   [QWEN3_0_6b.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
   [QWEN3_1_7b.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
   [QWEN3_4b.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
   [QWEN3_8b.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
   [QWEN3_14b.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
   [QWEN3_30b.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
   [QWEN3_32b.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
   [QWEN3_235b.name]: OllamaChatRequest &
     OllamaChatRequestMessages<OllamaMessageTools & OllamaMessageThinking> &
-    OllamaChatRequestTools &
-    OllamaChatRequestThinking
+    OllamaChatRequestTools
 }
 
 export type Qwen3ModelInputModalitiesByName = {
diff --git a/packages/ai-ollama/src/meta/models-meta.ts b/packages/ai-ollama/src/meta/models-meta.ts
index e27f44863a..148ca0712e 100644
--- a/packages/ai-ollama/src/meta/models-meta.ts
+++ b/packages/ai-ollama/src/meta/models-meta.ts
@@ -71,14 +71,6 @@ export interface OllamaChatRequest {
   options?: Partial<OllamaOptions>
 }
 
-export interface OllamaChatRequestThinking {
-  think?: boolean
-}
-
-export interface OllamaChatRequestThinking_OpenAI {
-  think?: 'low' | 'medium' | 'high'
-}
-
 export interface OllamaChatRequestTools {
   tools?: Array<Tool>
 }
diff --git a/packages/ai-ollama/tests/reasoning-types.test-d.ts b/packages/ai-ollama/tests/reasoning-types.test-d.ts
new file mode 100644
index 0000000000..233bf6a0c7
--- /dev/null
+++ b/packages/ai-ollama/tests/reasoning-types.test-d.ts
@@ -0,0 +1,26 @@
+import { chat } from '@tanstack/ai'
+import { createOllamaChat } from '../src/adapters/text'
+
+const messages = [{ role: 'user' as const, content: 'hi' }]
+
+chat({ adapter: createOllamaChat('gpt-oss:20b'), messages, reasoning: 'low' })
+chat({ adapter: createOllamaChat('qwen3:8b'), messages, reasoning: 'off' })
+// A model name this package does not list gets the on/off toggle.
+chat({ adapter: createOllamaChat('my-model'), messages, reasoning: 'high' })
+
+// @ts-expect-error qwen3 only turns thinking on or off
+chat({ adapter: createOllamaChat('qwen3:8b'), messages, reasoning: 'low' })
+
+chat({
+  adapter: createOllamaChat('athene-v2:latest'),
+  messages,
+  // @ts-expect-error a listed model that does not reason takes no reasoning
+  reasoning: 'high',
+})
+
+chat({
+  adapter: createOllamaChat('qwen3:8b'),
+  messages,
+  // @ts-expect-error think is set with chat({ reasoning })
+  modelOptions: { think: true },
+})
diff --git a/packages/ai-ollama/tests/text-adapter.test.ts b/packages/ai-ollama/tests/text-adapter.test.ts
index 11a450e8ee..803ddfe861 100644
--- a/packages/ai-ollama/tests/text-adapter.test.ts
+++ b/packages/ai-ollama/tests/text-adapter.test.ts
@@ -477,7 +477,7 @@ describe('OllamaTextAdapter modelOptions (nested options contract)', () => {
     expect(call.options).toEqual({})
   })
 
-  it('forwards request-level fields (format, keep_alive, think) outside of options', async () => {
+  it('forwards request-level fields (format, keep_alive) outside of options', async () => {
     chatMock.mockResolvedValueOnce(
       asyncIterable([
         {
@@ -497,7 +497,6 @@ describe('OllamaTextAdapter modelOptions (nested options contract)', () => {
         modelOptions: {
           options: { temperature: 0.3 },
           keep_alive: '10m',
-          think: true,
         },
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
       } as any),
@@ -506,13 +505,44 @@ describe('OllamaTextAdapter modelOptions (nested options contract)', () => {
     const call = chatMock.mock.calls[0]![0] as {
       options?: Record<string, unknown>
       keep_alive?: unknown
-      think?: unknown
     }
     expect(call.keep_alive).toBe('10m')
-    expect(call.think).toBe(true)
     // Request-level fields must not leak into the sampling options bag.
     expect(call.options).toEqual({ temperature: 0.3 })
   })
+
+  it.each([
+    ['qwen3:8b', 'high', true],
+    ['qwen3:8b', 'off', false],
+    ['gpt-oss:20b', 'medium', 'medium'],
+    // A model name this package does not list gets the on/off toggle.
+    ['my-custom-model', 'high', true],
+    // A listed model that does not reason gets no think field.
+    ['athene-v2:latest', 'high', undefined],
+  ] as const)(
+    'maps chat({ reasoning }) on %s at %s to think %s',
+    async (model, level, think) => {
+      chatMock.mockResolvedValueOnce(
+        asyncIterable([
+          {
+            message: { role: 'assistant', content: 'ok' },
+            done: true,
+            done_reason: 'stop',
+          },
+        ]),
+      )
+      await collectStream(
+        createOllamaChat(model).chatStream({
+          logger: testLogger,
+          model,
+          messages: [{ role: 'user', content: 'hi' }],
+          reasoning: { level, summary: true },
+        }),
+      )
+      const call = chatMock.mock.calls[0]![0] as { think?: unknown }
+      expect(call.think).toBe(think)
+    },
+  )
 })
 
 describe('OllamaTextAdapter system prompts', () => {
diff --git a/scripts/model-sync/reasoning-targets.ts b/scripts/model-sync/reasoning-targets.ts
index 1d9f4fcffc..1d4ca1b760 100644
--- a/scripts/model-sync/reasoning-targets.ts
+++ b/scripts/model-sync/reasoning-targets.ts
@@ -28,6 +28,37 @@ export interface ReasoningTarget {
   overrides?: Readonly<Record<string, ModelReasoning>>
 }
 
+const NO_LEVELS = {
+  off: null,
+  minimal: null,
+  low: null,
+  medium: null,
+  high: null,
+  xhigh: null,
+  max: null,
+} as const
+
+const ARK_SEED_LEVELS: ModelReasoning = {
+  map: {
+    ...NO_LEVELS,
+    minimal: 'minimal',
+    low: 'low',
+    medium: 'medium',
+    high: 'high',
+  },
+  budget: false,
+}
+
+const ARK_THINKING_SWITCH: ModelReasoning = {
+  map: { ...NO_LEVELS, off: 'disabled', high: 'enabled' },
+  budget: false,
+}
+
+const ARK_DEEPSEEK_V4: ModelReasoning = {
+  map: { ...NO_LEVELS, off: 'disabled', high: 'high', max: 'max' },
+  budget: false,
+}
+
 export const REASONING_TARGETS: ReadonlyArray<ReasoningTarget> = [
   {
     pkg: 'ai-openai',
@@ -71,6 +102,22 @@ export const REASONING_TARGETS: ReadonlyArray<ReasoningTarget> = [
     typePrefix: 'Groq',
     constPrefix: 'GROQ',
     sources: ['groq'],
+    overrides: {
+      // Groq's reasoning_effort for Qwen 3 is `none` or `default`, and it has
+      // no token budget field.
+      'qwen/qwen3-32b': {
+        map: {
+          off: 'none',
+          minimal: null,
+          low: null,
+          medium: null,
+          high: 'default',
+          xhigh: null,
+          max: null,
+        },
+        budget: false,
+      },
+    },
   },
   {
     pkg: 'ai-openrouter',
@@ -117,6 +164,23 @@ export const REASONING_TARGETS: ReadonlyArray<ReasoningTarget> = [
     typePrefix: 'BytePlus',
     constPrefix: 'BYTEPLUS',
     sources: ['volcengine'],
+    // Ark reasoning models that models.dev does not list. The Seed models
+    // take the levels of their listed siblings. `enabled` and `disabled`
+    // are Ark's `thinking.type` for a model with an on/off switch only.
+    overrides: {
+      'dola-seed-2-1-turbo-260628': ARK_SEED_LEVELS,
+      'seed-2-0-lite-260228': ARK_SEED_LEVELS,
+      'seed-2-0-mini-260215': ARK_SEED_LEVELS,
+      'seed-1-6-flash-250615': ARK_SEED_LEVELS,
+      'glm-4-7-251222': ARK_THINKING_SWITCH,
+      'deepseek-v3-2-251201': ARK_THINKING_SWITCH,
+      'deepseek-v4-pro-260425': ARK_DEEPSEEK_V4,
+      'deepseek-v4-flash-260425': ARK_DEEPSEEK_V4,
+      'gpt-oss-120b-250805': {
+        map: { ...NO_LEVELS, low: 'low', medium: 'medium', high: 'high' },
+        budget: false,
+      },
+    },
   },
   {
     pkg: 'ai-llmgateway',
diff --git a/scripts/sync-model-reasoning.ts b/scripts/sync-model-reasoning.ts
index 962caf7cdc..a8e28ffa7e 100644
--- a/scripts/sync-model-reasoning.ts
+++ b/scripts/sync-model-reasoning.ts
@@ -98,7 +98,7 @@ async function ollamaReasoning(): Promise<Map<string, ModelReasoning>> {
       }
       found.set(
         name,
-        block.includes('OllamaChatRequestThinking_OpenAI')
+        name.startsWith('gpt-oss')
           ? {
               map: {
                 off: null,

From 7c60206a176f0775aec0748f060718c45472a6f2 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 15:48:27 +0200
Subject: [PATCH 097/286] fix(ai-anthropic): use budget thinking on Claude
 before 4.6

Claude Opus 4.5 has effort levels in the model data, so the reasoning
mapping sent adaptive thinking, which only Claude 4.6 and later accept.
Adaptive thinking is now limited to pi's list of adaptive models; the
others think with a token budget.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-anthropic/src/text/reasoning.ts        | 14 ++++++++++++--
 .../ai-anthropic/tests/reasoning-request.test.ts   |  6 ++++++
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/packages/ai-anthropic/src/text/reasoning.ts b/packages/ai-anthropic/src/text/reasoning.ts
index 2dd83536dd..1767bb66b6 100644
--- a/packages/ai-anthropic/src/text/reasoning.ts
+++ b/packages/ai-anthropic/src/text/reasoning.ts
@@ -16,6 +16,13 @@ const isEffort = (value: string): value is AnthropicEffort =>
  */
 const TOP_LEVEL_EFFORT = new Set(['claude-opus-4-6', 'claude-sonnet-4-6'])
 
+/**
+ * The Claude models with adaptive thinking: 4.6 and later (pi's list). An
+ * older model with effort levels, such as Opus 4.5, still thinks with a
+ * token budget.
+ */
+const ADAPTIVE_THINKING = /opus-4-[6-9]|sonnet-4-[6-9]|opus-5|sonnet-5|fable-5/
+
 /** The Messages API thinking fields for one request. */
 export interface AnthropicThinkingFields {
   thinking?:
@@ -30,7 +37,7 @@ export interface AnthropicThinkingFields {
  * The thinking fields for `chat({ reasoning })`:
  * - `off`: thinking disabled. A model that cannot stop thinking never gets
  *   here, because the clamp moves `off` to its lowest level.
- * - a model with a token budget and no effort levels, or a request with
+ * - a budget model without adaptive thinking, or a request with
  *   `budgetTokens`: `thinking.type: 'enabled'` with the budget (pi's table
  *   when the request sets none).
  * - otherwise adaptive thinking with the model's effort for the level.
@@ -45,7 +52,10 @@ export function anthropicThinking(
   if (!resolved || !reasoning) return {}
   if (resolved.level === 'off') return { thinking: { type: 'disabled' } }
   const budgetOnly =
-    reasoning.budget && (resolved.budgetTokens !== undefined || !reasoning.map)
+    reasoning.budget &&
+    (resolved.budgetTokens !== undefined ||
+      !reasoning.map ||
+      !ADAPTIVE_THINKING.test(model))
   if (budgetOnly)
     return {
       thinking: {
diff --git a/packages/ai-anthropic/tests/reasoning-request.test.ts b/packages/ai-anthropic/tests/reasoning-request.test.ts
index f350cbbeb8..8198b8f054 100644
--- a/packages/ai-anthropic/tests/reasoning-request.test.ts
+++ b/packages/ai-anthropic/tests/reasoning-request.test.ts
@@ -105,6 +105,12 @@ describe('Anthropic chat({ reasoning }) request shape', () => {
     expect(body).not.toHaveProperty('effort')
   })
 
+  it('Claude Opus 4.5: effort levels but no adaptive thinking, so a budget', async () => {
+    const body = await send('claude-opus-4-5', on('medium'))
+    expect(body.thinking).toEqual({ type: 'enabled', budget_tokens: 8192 })
+    expect(body).not.toHaveProperty('output_config')
+  })
+
   it('budget models: the level picks the budget, and max_tokens grows past it', async () => {
     const body = await send('claude-haiku-4-5', on('medium'), {
       modelOptions: { max_tokens: 4000 },

From 1bc4177d562b93ea7ea61b7aeb5af82684822939 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 15:48:28 +0200
Subject: [PATCH 098/286] chore(examples): set reasoning with chat({ reasoning
 })

- harness-cli: `/effort` takes every level and sets `reasoning` in
  onConfig. Each adapter clamps it to the model, so the per-provider
  switch is gone, and Claude Haiku 4.5 can now think.
- ts-react-chat, ts-solid-chat, subagents-persisted, the e2e app, and
  the panel move their reasoning settings out of modelOptions. The e2e
  reasoning feature and the OpenRouter wire route use the new option.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 examples/harness-cli/README.md                |   2 +-
 examples/harness-cli/src/effort.ts            |  47 ++-----
 examples/harness-cli/src/harness.ts           |   8 +-
 .../subagents-persisted/src/lib/agents.ts     |   2 +-
 .../src/routes/api.persistent-chat.ts         |   4 +-
 .../src/routes/api.structured-output.ts       | 125 +++++++-----------
 .../ts-react-chat/src/routes/api.tanchat.ts   |  16 +--
 examples/ts-solid-chat/src/routes/api.chat.ts |   7 +-
 testing/e2e/src/lib/features.ts               |   6 +-
 testing/e2e/src/routes/api.chat.ts            |   4 +
 .../routes/api.openrouter-reasoning-wire.ts   |  15 +--
 testing/e2e/src/routes/api.subagents-test.ts  |   8 +-
 testing/panel/src/routes/api.chat.ts          |  13 +-
 13 files changed, 95 insertions(+), 162 deletions(-)

diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index e1a54627ec..dd8c5792ee 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -97,7 +97,7 @@ When `claude` and `codex` are on the PATH, the agent can call them. They work in
 ## Pick the model and the effort
 
 - `/model` opens a list of the models, with the provider and the context size of each. `/model gpt-6-luna` switches at once. The change applies at the next turn.
-- `/effort` sets how hard the model thinks: `default` (the model decides), `low`, `medium`, `high`, or `max`. `claude-haiku-4-5` has no effort setting.
+- `/effort` sets how hard the model thinks: `default` (the model decides), `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. It sets `chat({ reasoning })`, so a level the model does not have moves to the nearest one it has.
 - The footer shows the model, the effort, how full the context is, the tokens in and out, and the model calls.
 
 ## The screen
diff --git a/examples/harness-cli/src/effort.ts b/examples/harness-cli/src/effort.ts
index dd57671d45..8d7e3555bc 100644
--- a/examples/harness-cli/src/effort.ts
+++ b/examples/harness-cli/src/effort.ts
@@ -1,35 +1,16 @@
+import { REASONING_LEVELS } from '@tanstack/ai'
 import { configOption, defineCommand, definePlugin } from '@tanstack/ai-harness'
 
-export const EFFORTS = ['default', 'low', 'medium', 'high', 'max'] as const
+export const EFFORTS = ['default', ...REASONING_LEVELS] as const
 type Effort = (typeof EFFORTS)[number]
 
 /**
- * The model options that ask `provider` to think with `effort`. `max` is the
- * highest level each provider has. `default` sends nothing: the model decides.
+ * `/effort`: how hard the main model thinks at the next turn. It sets
+ * `chat({ reasoning })`, which every adapter maps to its own wire field and
+ * clamps to the levels the model has. `default` sends nothing: the model
+ * decides. `reasons` says whether the current model reasons at all.
  */
-function reasoningOptions(provider: string, effort: Effort) {
-  if (effort === 'default') return undefined
-  switch (provider) {
-    case 'anthropic':
-      return { output_config: { effort } }
-    case 'openrouter':
-      return { reasoning: { effort: effort === 'max' ? 'xhigh' : effort } }
-    case 'openai':
-    case 'grok':
-      return { reasoning: { effort: effort === 'max' ? 'high' : effort } }
-    default:
-      return undefined
-  }
-}
-
-/**
- * `/effort`: how hard the main model thinks at the next turn. It sets the
- * reasoning option of the current model's provider, for models where
- * `providerOf` gives a provider (a model without reasoning gives none).
- */
-export function effortPicker(options: {
-  providerOf: (model: string) => string | undefined
-}) {
+export function effortPicker(options: { reasons: (model: string) => boolean }) {
   return definePlugin({
     name: 'example/effort',
     setup: (ctx) => {
@@ -48,13 +29,13 @@ export function effortPicker(options: {
         middleware: [
           {
             name: 'example/effort',
-            onConfig: (_chat, config) => {
-              const provider = options.providerOf(
-                String(ctx.config.get('model')),
-              )
-              const extra = provider && reasoningOptions(provider, current())
-              if (!extra) return undefined
-              return { modelOptions: { ...config.modelOptions, ...extra } }
+            onConfig: () => {
+              const effort = current()
+              if (effort === 'default') return undefined
+              if (!options.reasons(String(ctx.config.get('model')))) {
+                return undefined
+              }
+              return { reasoning: { level: effort, summary: true } }
             },
           },
         ],
diff --git a/examples/harness-cli/src/harness.ts b/examples/harness-cli/src/harness.ts
index c8323cceef..b3ea1182a7 100644
--- a/examples/harness-cli/src/harness.ts
+++ b/examples/harness-cli/src/harness.ts
@@ -216,11 +216,10 @@ export const modelInfo: Record<
     contextWindow: 1_000_000,
     effort: true,
   },
-  // Haiku has no effort setting (output_config) in its model-meta.
   'claude-haiku-4-5': {
     provider: 'anthropic',
     contextWindow: 200_000,
-    effort: false,
+    effort: true,
   },
   'grok-4.7': { provider: 'grok', contextWindow: 500_000, effort: true },
   'grok-4.6': { provider: 'grok', contextWindow: 500_000, effort: true },
@@ -477,10 +476,7 @@ export const assistant = defineHarness({
     todos(),
     providerKeys({ providers: keyProviders }),
     modelPicker({ choices, default: startModel }),
-    effortPicker({
-      providerOf: (model) =>
-        modelInfo[model]?.effort ? modelInfo[model].provider : undefined,
-    }),
+    effortPicker({ reasons: (model) => modelInfo[model]?.effort === true }),
     projectInstructions({ root }),
     compact({ adapter: main }),
     usage(),
diff --git a/examples/react/subagents-persisted/src/lib/agents.ts b/examples/react/subagents-persisted/src/lib/agents.ts
index 04642007b7..e0093eab15 100644
--- a/examples/react/subagents-persisted/src/lib/agents.ts
+++ b/examples/react/subagents-persisted/src/lib/agents.ts
@@ -61,7 +61,7 @@ export function createBlogAgents(apiKey: string) {
     run: (ctx) =>
       chat({
         adapter: createOpenRouterText('openai/gpt-5.5', apiKey),
-        modelOptions: { reasoning: { effort: 'medium' } },
+        reasoning: 'medium',
         tools: [lookupWikipediaTool],
         messages: ctx.messages,
         threadId: ctx.threadId,
diff --git a/examples/ts-react-chat/src/routes/api.persistent-chat.ts b/examples/ts-react-chat/src/routes/api.persistent-chat.ts
index ef58beb99b..9e30b571e7 100644
--- a/examples/ts-react-chat/src/routes/api.persistent-chat.ts
+++ b/examples/ts-react-chat/src/routes/api.persistent-chat.ts
@@ -129,13 +129,13 @@ function startDetachedRun(
 
   const stream = chat({
     adapter: openaiText('gpt-5.5'),
-    // Reasoning on, effort "low" so it stays fast. `summary: 'auto'` asks OpenAI
+    // Reasoning on, effort "low" so it stays fast. The summary asks OpenAI
     // for a readable reasoning summary; when returned it streams as REASONING
     // events, is persisted, and reconstructs like text/tool calls (the pane
     // renders it as a "reasoning" block). NOTE: OpenAI only returns reasoning
     // summary text to organizations verified for it — unverified keys still
     // reason (you see reasoning tokens in usage) but get no summary to display.
-    modelOptions: { reasoning: { effort: 'low', summary: 'auto' } },
+    reasoning: { level: 'low', summary: true },
     // Snapshot streaming on: even the partial reply is persisted, so a reload
     // mid-generation (or a crash) still shows the story-so-far, and the detached
     // run below finishes and persists the rest.
diff --git a/examples/ts-react-chat/src/routes/api.structured-output.ts b/examples/ts-react-chat/src/routes/api.structured-output.ts
index b4e38d6985..cd85b4b06f 100644
--- a/examples/ts-react-chat/src/routes/api.structured-output.ts
+++ b/examples/ts-react-chat/src/routes/api.structured-output.ts
@@ -24,6 +24,7 @@ import type {
   AnyTextAdapter,
   ChatMiddleware,
   AdapterYieldChunk,
+  ReasoningRequest,
 } from '@tanstack/ai'
 import { EventType } from '@tanstack/ai'
 
@@ -187,77 +188,47 @@ function adapterFor(provider: Provider, model?: string): AnyTextAdapter {
   }
 }
 
-// Per-provider modelOptions to opt into reasoning surfacing. Without these,
-// reasoning models reason silently and the UI never sees REASONING_* events.
-function reasoningOptionsFor(
+// Per-provider reasoning, so reasoning models stream their thinking. Without
+// it, they reason silently and the UI never sees REASONING_* events.
+function reasoningFor(
   provider: Provider,
   model: string | undefined,
-): Record<string, unknown> | undefined {
+): ReasoningRequest | undefined {
   switch (provider) {
     case 'openai':
-      // Responses API: `reasoning.summary: 'auto'` is what makes the API emit
-      // `response.reasoning_summary_text.delta` events. Only valid on
-      // reasoning models (gpt-5.x, o-series); older models (gpt-4o) reject it.
+      // Only the reasoning models (gpt-5.x, o-series) take reasoning.
       if (
         model?.startsWith('gpt-5') ||
         model?.startsWith('o3') ||
         model?.startsWith('o4')
       ) {
-        return { reasoning: { summary: 'auto' } }
+        return { level: 'medium', summary: true }
       }
       return undefined
-    case 'openai-chat':
-      // Chat Completions API doesn't surface reasoning summaries the way
-      // Responses does. Reasoning models still reason silently; no opt-in
-      // option to inject here.
-      return undefined
     case 'anthropic': {
-      // Default: thinking OFF. Demo flows that just want streaming
-      // structured output shouldn't pay for reasoning tokens, and 4.7
-      // adaptive thinking can easily blow the default `max_tokens` budget
-      // before the schema-constrained JSON finishes — leaving the user
-      // staring at "response was cut off". The dropdown opts back in via
-      // the synthetic `:thinking-max` suffix.
+      // Default: thinking off. Demo flows that just want streaming
+      // structured output shouldn't pay for reasoning tokens, and adaptive
+      // thinking can easily use the default `max_tokens` before the JSON
+      // finishes. The dropdown opts in via the synthetic `:thinking-max`
+      // suffix.
       const baseModel = stripModelSuffix(model)
       if (
         !baseModel ||
-        !ANTHROPIC_COMBINED_TOOLS_AND_SCHEMA_MODELS.has(baseModel)
+        !ANTHROPIC_COMBINED_TOOLS_AND_SCHEMA_MODELS.has(baseModel) ||
+        model?.endsWith(':thinking-max') !== true
       ) {
         return undefined
       }
-      const wantsThinking = model?.endsWith(':thinking-max') === true
-      if (!wantsThinking) return undefined
-
-      // Three 4.7-specific quirks (only relevant on the thinking variant):
-      //   1. Manual extended thinking (`type: 'enabled'` + `budget_tokens`)
-      //      is rejected with HTTP 400 — adaptive is the only supported
-      //      mode.
-      //   2. The default for `display` flipped from `'summarized'` (4.6)
-      //      to `'omitted'` (4.7). Without `display: 'summarized'` the
-      //      API still streams a thinking content block but only emits
-      //      `signature_delta`, no `thinking_delta` — empty reasoning
-      //      panel even when the model IS thinking.
-      //   3. Adaptive thinking is non-deterministic. The model decides
-      //      based on prompt complexity. For short prompts like the demo
-      //      `'high'` still skipped thinking; only `'max'` reliably
-      //      engages it (and even that's not a hard guarantee).
-      if (baseModel.startsWith('claude-opus-4-7')) {
-        return {
-          thinking: { type: 'adaptive', display: 'summarized' },
-          output_config: { effort: 'max' },
-        }
-      }
-      // 4.5 / 4.6 / haiku 4.5 still accept the legacy
-      // `type: 'enabled' + budget_tokens` shape.
-      return { thinking: { type: 'enabled', budget_tokens: 1024 } }
+      // Adaptive thinking decides from the prompt. For the short demo
+      // prompt, only `max` reliably makes the model think. Budget models
+      // get a small fixed budget.
+      return baseModel.startsWith('claude-opus-4-7')
+        ? { level: 'max', summary: true }
+        : { level: 'low', summary: true, budgetTokens: 1024 }
     }
     case 'gemini': {
-      // Gemini 3.x surfaces reasoning via `thinkingLevel: 'HIGH'` —
-      // `includeThoughts: true` is what makes the API stream
-      // `parts[].thought` events that the adapter routes to REASONING_*
-      // chunks. Gemini 2.x uses the older budget-based shape and may
-      // reject `thinkingLevel`; gate strictly to the combined-mode set so
-      // we don't send an unsupported option on the legacy path.
+      // Only the Gemini 3.x combined-mode models, which take thinking
+      // levels.
       const baseModel = stripModelSuffix(model)
       if (
         !baseModel ||
@@ -265,37 +236,34 @@ function reasoningOptionsFor(
       ) {
         return undefined
       }
-      return {
-        thinkingConfig: {
-          includeThoughts: true,
-          thinkingLevel: 'HIGH',
-        },
-      }
+      return { level: 'high', summary: true }
     }
-    case 'groq':
-      // Groq's Chat Completions only streams `delta.reasoning` when
-      // `reasoning_format: 'parsed'`. Required for gpt-oss / qwen3 / kimi-k2
-      // to emit reasoning during structured output (json_schema mode).
-      if (
-        model?.startsWith('openai/gpt-oss') ||
-        model?.startsWith('qwen') ||
-        model?.startsWith('moonshotai/kimi')
-      ) {
-        return { reasoning_format: 'parsed' }
-      }
-      return undefined
     case 'openrouter':
     case 'openrouter-responses':
-      // OpenRouter normalises across providers. `reasoning.effort` triggers
-      // the upstream model's reasoning + surfaces the deltas. Same option on
-      // both the chat-completions and Responses-beta endpoints.
-      return { reasoning: { effort: 'medium' } }
-    case 'grok':
-      // The Grok Responses adapter includes encrypted reasoning by default.
+      return { level: 'medium', summary: true }
+    default:
       return undefined
   }
 }
 
+// Groq's Chat Completions only streams `delta.reasoning` when
+// `reasoning_format: 'parsed'`. Required for gpt-oss / qwen3 / kimi-k2 to
+// emit reasoning during structured output (json_schema mode).
+function groqReasoningFormat(
+  provider: Provider,
+  model: string | undefined,
+): Record<string, unknown> | undefined {
+  if (
+    provider === 'groq' &&
+    (model?.startsWith('openai/gpt-oss') ||
+      model?.startsWith('qwen') ||
+      model?.startsWith('moonshotai/kimi'))
+  ) {
+    return { reasoning_format: 'parsed' }
+  }
+  return undefined
+}
+
 async function* structuredOutputResultStream(args: {
   result: GuitarRecommendation
   phaseCounts: Record<string, number>
@@ -394,15 +362,19 @@ export const Route = createFileRoute('/api/structured-output')({
             resolvedProvider === 'anthropic' &&
             model?.endsWith(':thinking-max') === true
           const modelOptions = {
-            ...reasoningOptionsFor(resolvedProvider, model),
+            ...groqReasoningFormat(resolvedProvider, model),
             ...(wantsAnthropicMaxThinking && { max_tokens: 16_000 }),
           }
+          // The adapter is picked at runtime, so the per-model reasoning
+          // type can't be checked here.
+          const reasoning = reasoningFor(resolvedProvider, model) as never
           const counter = phaseCounterMiddleware()
 
           if (stream) {
             const streamIterable = chat({
               adapter,
               modelOptions: modelOptions as never,
+              reasoning,
               messages: params.messages,
               outputSchema: GuitarRecommendationSchema,
               stream: true,
@@ -424,6 +396,7 @@ export const Route = createFileRoute('/api/structured-output')({
           const result = await chat({
             adapter,
             modelOptions: modelOptions as never,
+            reasoning,
             messages: params.messages,
             outputSchema: GuitarRecommendationSchema,
             middleware: [counter.middleware],
diff --git a/examples/ts-react-chat/src/routes/api.tanchat.ts b/examples/ts-react-chat/src/routes/api.tanchat.ts
index 9e6f0c5367..8a3952fd37 100644
--- a/examples/ts-react-chat/src/routes/api.tanchat.ts
+++ b/examples/ts-react-chat/src/routes/api.tanchat.ts
@@ -364,21 +364,12 @@ export const Route = createFileRoute('/api/tanchat')({
             case 'openrouter':
               return createChatOptions({
                 adapter: createOpenRouterText(model, requireApiKey(apiKey)),
-                modelOptions: {
-                  reasoning: {
-                    effort: 'medium',
-                  },
-                },
+                reasoning: 'medium',
               })
             case 'gemini':
               return createChatOptions({
                 adapter: createGeminiChat(model, requireApiKey(apiKey)),
-                modelOptions: {
-                  thinkingConfig: {
-                    includeThoughts: true,
-                    thinkingBudget: 100,
-                  },
-                },
+                reasoning: 'high',
               })
             case 'gemini-interactions':
               return createChatOptions({
@@ -441,7 +432,8 @@ export const Route = createFileRoute('/api/tanchat')({
             case 'ollama':
               return createChatOptions({
                 adapter: ollamaText(model),
-                modelOptions: { think: 'low', options: { top_k: 1 } },
+                modelOptions: { options: { top_k: 1 } },
+                reasoning: 'low',
               })
             case 'openai':
               return createChatOptions({
diff --git a/examples/ts-solid-chat/src/routes/api.chat.ts b/examples/ts-solid-chat/src/routes/api.chat.ts
index 9a9b5d25e4..29bb834637 100644
--- a/examples/ts-solid-chat/src/routes/api.chat.ts
+++ b/examples/ts-solid-chat/src/routes/api.chat.ts
@@ -80,12 +80,7 @@ export const Route = createFileRoute('/api/chat')({
             messages: params.messages,
             threadId: params.threadId,
             runId: params.runId,
-            modelOptions: {
-              thinking: {
-                type: 'enabled',
-                budget_tokens: 10000,
-              },
-            },
+            reasoning: { level: 'high', budgetTokens: 10000 },
             abortController,
           })
 
diff --git a/testing/e2e/src/lib/features.ts b/testing/e2e/src/lib/features.ts
index a1ec89b012..4ed0ef03e5 100644
--- a/testing/e2e/src/lib/features.ts
+++ b/testing/e2e/src/lib/features.ts
@@ -1,9 +1,12 @@
+import type { ReasoningRequest } from '@tanstack/ai'
 import type { Feature, Provider } from '@/lib/types'
 import { getGuitars, compareGuitars, addToCart } from '@/lib/tools'
 
 interface FeatureConfig {
   tools: Array<any>
   modelOptions: Record<string, any>
+  /** `chat({ reasoning })` for the feature. */
+  reasoning?: ReasoningRequest
   modelOverrides?: Partial<Record<Provider, string>>
   dedicatedRoute?: string
   /**
@@ -39,7 +42,8 @@ export const featureConfigs: Record<Feature, FeatureConfig> = {
   },
   reasoning: {
     tools: [],
-    modelOptions: { reasoning: { effort: 'high' } },
+    modelOptions: {},
+    reasoning: { level: 'high', summary: true },
     modelOverrides: {
       openai: 'o3',
       anthropic: 'claude-sonnet-4-5',
diff --git a/testing/e2e/src/routes/api.chat.ts b/testing/e2e/src/routes/api.chat.ts
index f1ebf872c7..d3790bfe40 100644
--- a/testing/e2e/src/routes/api.chat.ts
+++ b/testing/e2e/src/routes/api.chat.ts
@@ -115,6 +115,7 @@ export const Route = createFileRoute('/api/chat')({
               ? chat({
                   ...adapterOptions,
                   modelOptions,
+                  ...(config.reasoning && { reasoning: config.reasoning }),
                   systemPrompts,
                   messages: params.messages,
                   threadId: params.threadId,
@@ -131,6 +132,7 @@ export const Route = createFileRoute('/api/chat')({
                 ? chat({
                     ...adapterOptions,
                     modelOptions,
+                    ...(config.reasoning && { reasoning: config.reasoning }),
                     systemPrompts,
                     messages: params.messages,
                     threadId: params.threadId,
@@ -148,6 +150,7 @@ export const Route = createFileRoute('/api/chat')({
                       ...adapterOptions,
                       tools: config.tools,
                       modelOptions,
+                      ...(config.reasoning && { reasoning: config.reasoning }),
                       systemPrompts,
                       agentLoopStrategy: maxIterations(5),
                       messages: params.messages,
@@ -165,6 +168,7 @@ export const Route = createFileRoute('/api/chat')({
                       ...adapterOptions,
                       tools: config.tools,
                       modelOptions,
+                      ...(config.reasoning && { reasoning: config.reasoning }),
                       systemPrompts,
                       agentLoopStrategy: maxIterations(5),
                       messages: params.messages,
diff --git a/testing/e2e/src/routes/api.openrouter-reasoning-wire.ts b/testing/e2e/src/routes/api.openrouter-reasoning-wire.ts
index df3653fa96..f8b5bd8823 100644
--- a/testing/e2e/src/routes/api.openrouter-reasoning-wire.ts
+++ b/testing/e2e/src/routes/api.openrouter-reasoning-wire.ts
@@ -7,10 +7,10 @@ const LLMOCK_DEFAULT_BASE = process.env.LLMOCK_URL || 'http://127.0.0.1:4010'
 const DUMMY_KEY = 'sk-e2e-test-dummy-key'
 
 /**
- * Drives the real OpenRouter SDK request path with its documented
- * `reasoning.enabled` opt-out or an empty reasoning object. The companion
- * spec inspects aimock's request journal to verify the adapter normalizes or
- * omits the option before the SDK serializes the request body.
+ * Drives the real OpenRouter SDK request path with `chat({ reasoning: 'off' })`
+ * or no reasoning at all. The companion spec inspects aimock's request journal
+ * to verify the adapter sends `effort: 'none'` or omits the field before the
+ * SDK serializes the request body.
  */
 export const Route = createFileRoute('/api/openrouter-reasoning-wire')({
   server: {
@@ -30,7 +30,7 @@ export const Route = createFileRoute('/api/openrouter-reasoning-wire')({
           })
         }
 
-        const adapter = createOpenRouterText('openai/gpt-5', DUMMY_KEY, {
+        const adapter = createOpenRouterText('openai/gpt-5.5', DUMMY_KEY, {
           serverURL: `${LLMOCK_DEFAULT_BASE}/v1`,
           httpClient,
         })
@@ -47,10 +47,7 @@ export const Route = createFileRoute('/api/openrouter-reasoning-wire')({
                     : '[reasoning-wire] disable reasoning',
               },
             ],
-            modelOptions:
-              scenario === 'empty'
-                ? { reasoning: {} }
-                : { reasoning: { enabled: false } },
+            ...(scenario === 'empty' ? {} : { reasoning: 'off' as const }),
           })) {
             // Drain the stream.
           }
diff --git a/testing/e2e/src/routes/api.subagents-test.ts b/testing/e2e/src/routes/api.subagents-test.ts
index 5f03bb403f..b6306745ce 100644
--- a/testing/e2e/src/routes/api.subagents-test.ts
+++ b/testing/e2e/src/routes/api.subagents-test.ts
@@ -7,7 +7,7 @@ import {
   toServerSentEventsResponse,
 } from '@tanstack/ai'
 import { z } from 'zod'
-import type { DefinedAgent, Tool } from '@tanstack/ai'
+import type { DefinedAgent, ReasoningRequest, Tool } from '@tanstack/ai'
 import { createTextAdapter } from '@/lib/providers'
 import {
   deleteLogs,
@@ -43,7 +43,7 @@ function subagentsFor(
     name: string,
     tools: Array<Tool>,
     model?: string,
-    modelOptions?: Record<string, unknown>,
+    reasoning?: ReasoningRequest,
   ) =>
     defineAgent({
       name,
@@ -58,7 +58,7 @@ function subagentsFor(
           subagentRunId: ctx.subagentRunId,
           resume: ctx.resume,
           tools,
-          ...(modelOptions ? { modelOptions } : {}),
+          ...(reasoning ? { reasoning } : {}),
           agentLoopStrategy: maxIterations(4),
         }),
     })
@@ -68,7 +68,7 @@ function subagentsFor(
       'researcher',
       [lookupFacts.server(({ topic }) => ({ topic, facts: ['three hearts'] }))],
       'o3',
-      { reasoning: { effort: 'high' } },
+      { level: 'high', summary: true },
     )
     return { agents: [researcher], router: () => 'researcher' }
   }
diff --git a/testing/panel/src/routes/api.chat.ts b/testing/panel/src/routes/api.chat.ts
index 82e2121b02..df0360e5e0 100644
--- a/testing/panel/src/routes/api.chat.ts
+++ b/testing/panel/src/routes/api.chat.ts
@@ -233,17 +233,8 @@ export const Route = createFileRoute('/api/chat')({
             systemPrompts: [SYSTEM_PROMPT],
             agentLoopStrategy: maxIterations(20),
             messages,
-            modelOptions: {
-              // Enable reasoning for OpenAI (gpt-5, o3 models):
-              // reasoning: {
-              //   effort: "medium", // or "low", "high", "minimal", "none" (for gpt-5.1)
-              // },
-              // Enable thinking for Anthropic:
-              /*   thinking: {
-                  type: "enabled",
-                  budget_tokens: 2048,
-                }, */
-            },
+            // Turn reasoning on for a reasoning model, for example:
+            // reasoning: 'medium',
             abortController,
           })
 

From 5d87fa1276d8e01801022b15570eca2ec6edc0f9 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 15:51:43 +0200
Subject: [PATCH 099/286] docs: chat({ reasoning }), the reasoning migration,
 and the model catalog

New pages:

- chat/reasoning: the levels, the per-model types, summary and
  budgetTokens, the clamp, middleware, and what each provider receives
- migration/reasoning-option: the old modelOptions fields by provider
  and the removed types
- models/catalog: @tanstack/ai-models lookups, reasoning levels, costs,
  and provider subpaths

The thinking page, the adapter pages, the OpenAI-compatible page (new
Reasoning Models section), extend-adapter (new section for adapter
authors), the community guide, typed options, the persisted-subagents
tutorial, the package READMEs, and the shipped agent skills move to the
new option. docs/config.json lists the new pages and dates.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 docs/adapters/anthropic.md                    |  58 ++-------
 docs/adapters/byteplus.md                     |  18 ++-
 docs/adapters/cloudflare.md                   |   7 +-
 docs/adapters/codex.md                        |   7 +-
 docs/adapters/gemini.md                       |  29 +++--
 docs/adapters/groq.md                         |  17 ++-
 docs/adapters/llmgateway.md                   |   4 +-
 docs/adapters/openai-compatible.md            |  40 ++++++
 docs/adapters/openai.md                       |  20 +--
 docs/adapters/openrouter.md                   |   8 +-
 docs/advanced/extend-adapter.md               |  51 ++++++++
 docs/advanced/typed-options.md                |   6 +-
 docs/chat/reasoning.md                        | 118 ++++++++++++++++++
 docs/chat/thinking-content.md                 |  57 +--------
 docs/community-adapters/guide.md              |   9 +-
 docs/config.json                              |  48 ++++---
 docs/migration/reasoning-option.md            |  90 +++++++++++++
 docs/models/catalog.md                        |  85 +++++++++++++
 docs/tutorials/subagents-persisted.md         |   2 +-
 packages/ai-anthropic/README.md               |  10 +-
 packages/ai-byteplus/README.md                |   3 +-
 .../ai-core/adapter-configuration/SKILL.md    |  44 +++----
 .../references/anthropic-adapter.md           |  37 ++----
 .../references/byteplus-adapter.md            |  12 +-
 .../references/gemini-adapter.md              |  15 +--
 .../references/grok-adapter.md                |   4 +-
 .../references/groq-adapter.md                |   9 +-
 .../references/openai-adapter.md              |   7 +-
 .../references/openrouter-adapter.md          |   8 +-
 .../skills/ai-core/chat-experience/SKILL.md   |   9 +-
 30 files changed, 553 insertions(+), 279 deletions(-)
 create mode 100644 docs/chat/reasoning.md
 create mode 100644 docs/migration/reasoning-option.md
 create mode 100644 docs/models/catalog.md

diff --git a/docs/adapters/anthropic.md b/docs/adapters/anthropic.md
index f9d63d9fb9..2352c327db 100644
--- a/docs/adapters/anthropic.md
+++ b/docs/adapters/anthropic.md
@@ -231,26 +231,9 @@ Anthropic's Messages API _requires_ `max_tokens` on every request, so the adapte
 
 One exception: structured output (`chat({ outputSchema })`) on models that use the non-streaming finalization path clamps this default to ~21K tokens. The Anthropic SDK rejects a non-streaming request whose `max_tokens` could exceed its 10-minute timeout, so the full ceiling can't be used there. Streaming chat is unaffected. To raise the structured-output ceiling toward a model's true max, stream the response.
 
-### Thinking (Extended Thinking)
+### Thinking
 
-Enable extended thinking with a token budget. This allows Claude to show its reasoning process, which is streamed as `thinking` chunks:
-
-```typescript ignore
-modelOptions: {
-  thinking: {
-    type: "enabled",
-    budget_tokens: 2048, // Maximum tokens for thinking
-  },
-}
-```
-
-**Note:** `budget_tokens` must be less than `modelOptions.max_tokens` — set `max_tokens` high enough to leave room for the visible response alongside the thinking budget, or the request is rejected.
-
-### Adaptive Thinking (Claude 4.6+, Sonnet 5, Fable 5)
-
-Newer Claude models use adaptive thinking — the model decides when and how
-much to think, and depth is tuned with `output_config.effort` instead of a
-token budget:
+Set how hard Claude thinks with `reasoning` on `chat()`. The adapter turns the level into the right thinking fields for the model:
 
 ```typescript
 import { chat } from "@tanstack/ai";
@@ -259,37 +242,18 @@ import { anthropicText } from "@tanstack/ai-anthropic";
 const stream = chat({
   adapter: anthropicText("claude-sonnet-5"),
   messages: [{ role: "user", content: "Plan a database migration." }],
-  modelOptions: {
-    thinking: { type: "adaptive", display: "summarized" },
-    output_config: { effort: "xhigh" },
-    max_tokens: 64_000,
-  },
+  reasoning: "xhigh",
 });
 ```
 
-Per-model rules (enforced by the adapter's types):
-
-- **`claude-sonnet-5`, `claude-opus-4-8`, `claude-opus-4-7`** — adaptive
-  thinking with an explicit `{ type: "disabled" }` opt-out. The manual
-  `{ type: "enabled", budget_tokens }` shape is rejected with a 400, and
-  the sampling parameters (`temperature`, `top_p`, `top_k`) are not
-  accepted (on Sonnet 5 the API rejects non-default values; on Opus
-  4.7/4.8 the parameters are removed entirely).
-- **`claude-fable-5`** — thinking is always on. The only accepted explicit
-  config is `{ type: "adaptive" }` (both `disabled` and `budget_tokens`
-  return a 400), and sampling parameters are rejected.
-- **`claude-opus-4-6` / `claude-sonnet-4-6`** — accept
-  `{ type: "adaptive" }` alongside the deprecated
-  `{ type: "enabled", budget_tokens }` shape, and still accept sampling
-  parameters.
-- **`display`** defaults to `"omitted"` on Opus 4.7+ and the 5-generation
-  models — set `"summarized"` to stream the reasoning text.
-- **`effort`** accepts `"low" | "medium" | "high" | "xhigh" | "max"`;
-  `"xhigh"` is available on Claude Opus 4.7+, Claude Sonnet 5, and
-  Claude Fable 5.
-- **`output_config`** is accepted on Claude Opus 4.7, Opus 4.8, Sonnet 5,
-  Fable 5, Opus 5, Fable 5.1 and Opus 5.5. When you also pass an `outputSchema`, the
-  adapter adds `output_config.format` and keeps the `effort` you set.
+What the adapter sends for each kind of model:
+
+- **Claude 4.7 and later, Sonnet 5, Fable 5**: adaptive thinking, with the level as `output_config.effort`.
+- **Claude Opus 4.6 and Sonnet 4.6**: adaptive thinking, with the level as `effort`.
+- **Haiku 4.5, Sonnet 4.5, Opus 4.5, Opus 4.1**: thinking with a token budget. Set it with `reasoning: { level: "high", budgetTokens: 8000 }`. The adapter raises `max_tokens` when it is below the budget.
+- **`off`**: thinking disabled. `claude-fable-5` always thinks, so its types do not take `off`.
+
+The thinking text streams back as thinking parts. Pass `summary: false` to keep it hidden: `reasoning: { level: "high", summary: false }`. See [Reasoning](../chat/reasoning) for the levels and how a level the model does not have moves to the nearest one.
 
 ### Prompt Caching
 
diff --git a/docs/adapters/byteplus.md b/docs/adapters/byteplus.md
index cea9c1d760..2c814c7787 100644
--- a/docs/adapters/byteplus.md
+++ b/docs/adapters/byteplus.md
@@ -142,7 +142,7 @@ export function Chat() {
 
 ### Model options
 
-Ark's chat endpoint is OpenAI-compatible, so sampling parameters keep their OpenAI snake_case names and live in `modelOptions`. `thinking`, `reasoning_effort`, `repetition_penalty` and `service_tier` are the Ark-only additions:
+Ark's chat endpoint is OpenAI-compatible, so sampling parameters keep their OpenAI snake_case names and live in `modelOptions`. `repetition_penalty` and `service_tier` are the Ark-only additions. The reasoning level goes in `reasoning`:
 
 ```typescript
 import { chat, toServerSentEventsResponse } from '@tanstack/ai'
@@ -158,25 +158,21 @@ export async function POST(request: Request) {
       temperature: 0.7,
       top_p: 0.9,
       max_tokens: 2048,
-      thinking: { type: 'enabled' },
-      reasoning_effort: 'medium',
     },
+    reasoning: 'medium',
   })
 
   return toServerSentEventsResponse(stream)
 }
 ```
 
-Two constraints the type system can't express, both live-verified as `400`s:
-
-- `max_tokens` and `max_completion_tokens` are mutually exclusive.
-- `reasoning_effort` cannot be combined with `thinking: { type: 'disabled' }`.
+`max_tokens` and `max_completion_tokens` are mutually exclusive. The type system can't express this, and Ark returns a `400` when you send both.
 
 `service_tier: 'flex'` routes the request to the cheaper offline batch queue with no latency guarantee.
 
 ## Reasoning and `encrypted_content`
 
-Seed models reason by default. Reasoning arrives as its own stream of `reasoning_content` deltas and is surfaced as reasoning content rather than answer text, so `useChat` renders it separately from the reply. Turn it off per request:
+Seed models reason by default. Reasoning arrives as its own stream of `reasoning_content` deltas and is surfaced as reasoning content rather than answer text, so `useChat` renders it separately from the reply. The adapter sends `reasoning` as Ark's `thinking.type`, plus `reasoning_effort` when the level has an effort. Turn reasoning off per request on a model that can stop thinking:
 
 ```typescript
 import { chat, toServerSentEventsResponse } from '@tanstack/ai'
@@ -186,16 +182,16 @@ export async function POST(request: Request) {
   const { messages } = await request.json()
 
   const stream = chat({
-    adapter: byteplusText('dola-seed-2-1-turbo-260628'),
+    adapter: byteplusText('glm-5-2-260617'),
     messages,
-    modelOptions: { thinking: { type: 'disabled' } },
+    reasoning: 'off',
   })
 
   return toServerSentEventsResponse(stream)
 }
 ```
 
-`disabled` works everywhere; `auto` is accepted only by `gpt-oss-120b-250805`. `deepseek-v3-2-251201` is the one model that defaults to reasoning *off*.
+`off` sends `thinking: { type: 'disabled' }` and no effort, because Ark rejects the pair. `deepseek-v3-2-251201` is the one model that defaults to reasoning *off*.
 
 The four "thinking summary" models — `dola-seed-2-1-turbo-260628`, `seed-2-0-lite-260428`, `seed-2-0-mini-260428` and `seed-2-0-pro-260328` — also emit an opaque `encrypted_content` blob alongside the reasoning trace. It is a signature over that trace, and BytePlus's docs ask for it back verbatim on the assistant message in the next turn.
 
diff --git a/docs/adapters/cloudflare.md b/docs/adapters/cloudflare.md
index f06a80fbce..bce766fbc0 100644
--- a/docs/adapters/cloudflare.md
+++ b/docs/adapters/cloudflare.md
@@ -250,7 +250,7 @@ export default {
 
 ## Model options
 
-Sampling and reasoning controls go in `modelOptions`. Reasoning models stream their thinking as `reasoning_content`, which shows up as `REASONING_*` events.
+Sampling controls go in `modelOptions`, and the reasoning level goes in `reasoning`. Reasoning models stream their thinking as `reasoning_content`, which shows up as `REASONING_*` events.
 
 ```typescript
 import { chat } from "@tanstack/ai";
@@ -262,12 +262,13 @@ const stream = chat({
   modelOptions: {
     temperature: 0.3,
     max_tokens: 512,
-    reasoning_effort: "low",
-    chat_template_kwargs: { enable_thinking: false },
   },
+  reasoning: "low",
 });
 ```
 
+`reasoning` goes out as `reasoning_effort`. `off` sends `null`, which turns reasoning off. Model template settings, such as `chat_template_kwargs`, stay in `modelOptions`.
+
 ## Evaluate
 
 Use `cloudflareDecider('typesafe/jev')` with `decide()`.
diff --git a/docs/adapters/codex.md b/docs/adapters/codex.md
index f838c3b9c6..56dd62d0e5 100644
--- a/docs/adapters/codex.md
+++ b/docs/adapters/codex.md
@@ -73,7 +73,7 @@ const stream = chat({
 | `cwd`                  | Working directory for the harness session. Defaults to `process.cwd()`.                                                                       |
 | `sandboxMode`          | Codex sandbox: `'read-only'`, `'workspace-write'`, or `'danger-full-access'`. Default is `'workspace-write'` on local-process and Docker. Default is `'danger-full-access'` on Daytona and Cloudflare, because those providers cannot create a nested bubblewrap namespace. Isolation is then the outer VM plus `defineSandboxPolicy`. |
 | `approvalPolicy`       | Codex approval policy. Defaults to `'never'` — headless runs have no approval UI, so anything else can stall a turn.                           |
-| `modelReasoningEffort` | `'minimal'` \| `'low'` \| `'medium'` \| `'high'` \| `'xhigh'`.                                                                                 |
+| `modelReasoningEffort` | The default effort when a call sets no `reasoning`: `'minimal'` \| `'low'` \| `'medium'` \| `'high'`.                                  |
 | `skipGitRepoCheck`     | Skip the harness's git-repo safety check. Defaults to `true` (server adapters routinely point at scratch directories).                         |
 | `networkAccessEnabled` | Allow network access inside the `workspace-write` sandbox.                                                                                     |
 | `webSearchMode`        | `'disabled'` \| `'cached'` \| `'live'`.                                                                                                        |
@@ -86,8 +86,9 @@ const stream = chat({
 | `config`               | Extra `--config key=value` overrides passed to the Codex CLI (e.g. additional `mcp_servers` entries).                                          |
 
 Per-call overrides go through `modelOptions`: `sessionId`, `sandboxMode`,
-`approvalPolicy`, `modelReasoningEffort`, `workingDirectory`,
-`skipGitRepoCheck`, and `authMode`.
+`approvalPolicy`, `workingDirectory`, `skipGitRepoCheck`, and `authMode`.
+Set the effort per call with `reasoning` on `chat()`; the adapter sends it as
+`model_reasoning_effort`.
 
 ## Stateful Sessions
 
diff --git a/docs/adapters/gemini.md b/docs/adapters/gemini.md
index 0980cec0a0..1ddb899649 100644
--- a/docs/adapters/gemini.md
+++ b/docs/adapters/gemini.md
@@ -39,8 +39,6 @@ Need Gemini on Vertex AI (regional endpoints and Google Cloud credentials)? Use
 
 Use `gemini-3.8-flash` for chat with multimodal input, thinking, and built-in tools. It also supports structured output and caching.
 
-For Gemini 3.8 Flash, set `modelOptions.thinkingConfig.thinkingLevel` to `LOW`, `MEDIUM`, or `HIGH`. The Interactions adapter uses `modelOptions.generation_config.thinking_level` with `low`, `medium`, or `high`. Gemini 3.8 Flash does not accept the `minimal` thinking level.
-
 ```typescript
 import { chat } from "@tanstack/ai";
 import { geminiText } from "@tanstack/ai-gemini";
@@ -359,13 +357,13 @@ const stream = chat({
 
     // snake_case generation config distinct from geminiText's camelCase one.
     generation_config: {
-      thinking_level: "low",
-      thinking_summaries: "auto",
       stop_sequences: ["<done>"],
     },
 
     response_modalities: ["text"],
   },
+  // Sent as generation_config.thinking_level and thinking_summaries.
+  reasoning: "low",
 });
 ```
 
@@ -424,16 +422,25 @@ const stream = chat({
 
 ### Thinking
 
-Enable thinking for models that support it:
+Set how hard Gemini thinks with `reasoning` on `chat()`:
 
-```typescript ignore
-modelOptions: {
-  thinking: {
-    includeThoughts: true,
-  },
-}
+```typescript
+import { chat } from "@tanstack/ai";
+import { geminiText } from "@tanstack/ai-gemini";
+
+const stream = chat({
+  adapter: geminiText("gemini-3.8-flash"),
+  messages: [{ role: "user", content: "Plan a trip to Kyoto." }],
+  reasoning: "high",
+});
 ```
 
+- **Gemini 3 models** take thinking levels. The adapter sends `thinkingConfig.thinkingLevel`. Gemini 3.8 Flash has `low`, `medium`, and `high`.
+- **Gemini 2.5 models** take a token budget. The adapter sends `thinkingConfig.thinkingBudget`, from `budgetTokens` or a default for the level. `off` sends a budget of `0`.
+- **The Interactions adapter** sends `generation_config.thinking_level`.
+
+The thinking text streams back as thinking parts. `summary: false` sets `includeThoughts: false`. See [Reasoning](../chat/reasoning).
+
 ### Structured Output
 
 Configure structured output format:
diff --git a/docs/adapters/groq.md b/docs/adapters/groq.md
index 0f65d10b83..006d59325f 100644
--- a/docs/adapters/groq.md
+++ b/docs/adapters/groq.md
@@ -170,14 +170,21 @@ const stream = chat({
 
 ### Reasoning
 
-Enable reasoning for models that support it (e.g., `openai/gpt-oss-120b`, `qwen/qwen3-32b`). This allows the model to show its reasoning process, which is streamed as `thinking` chunks:
+Set how hard a reasoning model (`openai/gpt-oss-120b`, `qwen/qwen3-32b`) thinks with `reasoning` on `chat()`:
 
-```typescript ignore
-modelOptions: {
-  reasoning_effort: "medium", // "none" | "default" | "low" | "medium" | "high"
-}
+```typescript
+import { chat } from "@tanstack/ai";
+import { groqText } from "@tanstack/ai-groq";
+
+const stream = chat({
+  adapter: groqText("openai/gpt-oss-120b"),
+  messages: [{ role: "user", content: "Hello!" }],
+  reasoning: "medium",
+});
 ```
 
+The adapter sends `reasoning_effort`. Qwen 3 only turns thinking on or off: `high` sends `default`, and `off` sends `none`. To pick how the reasoning text comes back, set `reasoning_format` in `modelOptions`. See [Reasoning](../chat/reasoning).
+
 ## Summarization
 
 Summarize long text content:
diff --git a/docs/adapters/llmgateway.md b/docs/adapters/llmgateway.md
index 017569959b..30297512b7 100644
--- a/docs/adapters/llmgateway.md
+++ b/docs/adapters/llmgateway.md
@@ -137,12 +137,12 @@ const stream = chat({
   modelOptions: {
     temperature: 0.7,
     max_completion_tokens: 4096,
-    reasoning_effort: "high",
   },
+  reasoning: "high",
 });
 ```
 
-`reasoning_effort` accepts the extended scale `none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max` in addition to OpenAI's standard tiers — which tiers a model honors depends on the model and provider it is routed to (see the model's page on [llmgateway.io/models](https://llmgateway.io/models)).
+`reasoning` goes out as `reasoning_effort`. The types list the levels each model has, from the model catalog. See [Reasoning](../chat/reasoning).
 
 Reasoning models stream their thinking as `reasoning_content` deltas, which the adapter surfaces as AG-UI `REASONING_*` events.
 
diff --git a/docs/adapters/openai-compatible.md b/docs/adapters/openai-compatible.md
index a9bdb1f3bb..1d490911df 100644
--- a/docs/adapters/openai-compatible.md
+++ b/docs/adapters/openai-compatible.md
@@ -108,6 +108,46 @@ const provider = openaiCompatible({
 
 > Capabilities are enforced at the type level. If a provider rejects a feature at runtime (e.g. tools on a model that doesn't support them), declare that model with `createModel` and omit the unsupported feature so the types stop you from calling it.
 
+## Reasoning Models
+
+Reasoning models on OpenAI-compatible endpoints do not agree on the wire format. DeepSeek wants `thinking: { type }`, Qwen wants `enable_thinking`, and some servers reject the `developer` role. Tell the adapter what the provider expects with `compat`, and give each reasoning model its levels:
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { openaiCompatible } from "@tanstack/ai-openai/compatible";
+
+const deepseek = openaiCompatible({
+  baseURL: "https://api.deepseek.com",
+  apiKey: process.env.DEEPSEEK_API_KEY!,
+  compat: {
+    thinkingFormat: "deepseek",
+    maxTokensField: "max_tokens",
+    requiresReasoningContentOnAssistantMessages: true,
+  },
+  models: [
+    {
+      name: "deepseek-v4-flash",
+      // Each level and the value the provider takes. `null`: no such level.
+      reasoning: { off: "none", minimal: null, medium: null, high: "high", max: "max" },
+    },
+    { name: "deepseek-chat", reasoning: false },
+  ],
+});
+
+const stream = chat({
+  adapter: deepseek("deepseek-v4-flash"),
+  messages: [{ role: "user", content: "Prove that the square root of 2 is irrational." }],
+  reasoning: "max",
+});
+```
+
+- `reasoning` on a model takes a level map, `true` for every level up to `high`, or `false` for a model that does not reason. The `reasoning` option on `chat()` is then typed to those levels.
+- `thinkingFormat` picks the request shape: `openai`, `deepseek`, `zai`, `qwen`, `qwen-chat-template`, `chat-template`, `baseten`, `openrouter`, `together`, `string-thinking`, or `ant-ling`.
+- `compat` on a model entry overrides the provider's `compat` for that model.
+- `requiresReasoningContentOnAssistantMessages` sends the earlier thinking back on each assistant turn, which DeepSeek needs.
+
+The [model catalog](../models/catalog) has the levels and `compat` for many providers, from the same data these fields use.
+
 ## Configuration
 
 `openaiCompatible` accepts every OpenAI SDK `ClientOptions` field besides `apiKey`/`baseURL` (which are required and promoted to the top level). The most useful are `defaultHeaders` and `defaultQuery`, for providers that need extra auth or routing parameters:
diff --git a/docs/adapters/openai.md b/docs/adapters/openai.md
index ab82f0d673..57088899ea 100644
--- a/docs/adapters/openai.md
+++ b/docs/adapters/openai.md
@@ -214,18 +214,20 @@ const stream = chat({
 
 ### Reasoning
 
-Enable reasoning for models that support it (e.g., GPT-5, O3). This allows the model to show its reasoning process, which is streamed as `thinking` chunks:
+Set how hard a reasoning model (GPT-5 and later, the o-series) thinks with `reasoning` on `chat()`:
 
-```typescript ignore
-modelOptions: {
-  reasoning: {
-    effort: "medium", // "none" | "minimal" | "low" | "medium" | "high"
-    summary: "detailed", // "auto" | "detailed" (optional)
-  },
-}
+```typescript
+import { chat } from "@tanstack/ai";
+import { openaiText } from "@tanstack/ai-openai";
+
+const stream = chat({
+  adapter: openaiText("gpt-5.5"),
+  messages: [{ role: "user", content: "Plan a database migration." }],
+  reasoning: "high",
+});
 ```
 
-When reasoning is enabled, the model's reasoning process is streamed separately from the response text and appears as a collapsible thinking section in the UI.
+The adapter sends the level as `reasoning.effort`, with `summary: "auto"` so the reasoning summary streams back as thinking parts. Pass `reasoning: { level: "high", summary: false }` to skip the summary. The types list only the levels the model has. See [Reasoning](../chat/reasoning).
 
 ## Summarization
 
diff --git a/docs/adapters/openrouter.md b/docs/adapters/openrouter.md
index 78c35fdbd4..e974559c46 100644
--- a/docs/adapters/openrouter.md
+++ b/docs/adapters/openrouter.md
@@ -387,7 +387,7 @@ Plugin ids include `web`, `file-parser`, `response-healing`, `moderation`, and `
 
 ### Reasoning
 
-`reasoning` is OpenRouter's unified reasoning configuration:
+Set how hard the routed model thinks with `reasoning` on `chat()`:
 
 ```typescript
 import { chat } from "@tanstack/ai";
@@ -396,13 +396,11 @@ import { openRouterText } from "@tanstack/ai-openrouter";
 const stream = chat({
   adapter: openRouterText("anthropic/claude-sonnet-5"),
   messages: [{ role: "user", content: "Hello!" }],
-  modelOptions: {
-    reasoning: { effort: "high" },
-  },
+  reasoning: "high",
 });
 ```
 
-`effort` accepts `"none"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, and `"max"`. To switch reasoning off for a request, pass `reasoning: { enabled: false }`; the adapter sends it as `effort: "none"` because the SDK's request schema drops `enabled`.
+The adapter sends the level as OpenRouter's `reasoning.effort`. `off` sends `effort: "none"`. The Responses adapter (`openRouterResponsesText`) also takes `budgetTokens` and sends it as `reasoning.max_tokens`. See [Reasoning](../chat/reasoning).
 
 ### Session and metadata
 
diff --git a/docs/advanced/extend-adapter.md b/docs/advanced/extend-adapter.md
index a2cf47db76..e974ccb9de 100644
--- a/docs/advanced/extend-adapter.md
+++ b/docs/advanced/extend-adapter.md
@@ -209,3 +209,54 @@ chat({
   messages: [{ role: 'user', content: 'Analyze this...' }]
 })
 ```
+
+## Add reasoning to your adapter
+
+`chat({ reasoning })` reaches an adapter as `options.reasoning`: a level, a `summary` flag, and an optional `budgetTokens`. To support it:
+
+1. Give each model its reasoning data as a `ModelReasoning`: a map from each level to the value your provider takes, and whether it takes a token budget.
+2. Declare the levels on the adapter type, so `chat()` checks them. The last type parameter of `BaseTextAdapter` and the `openai-base` adapters is `{ levels; budget }`.
+3. Turn the request into your provider's field. `resolveReasoning` clamps the level to the model and looks up the value.
+
+An adapter built on `@tanstack/openai-base` only needs `modelReasoning`. The base then sends `reasoning_effort` on Chat Completions, or `reasoning.effort` on Responses:
+
+```typescript
+import OpenAI from "openai";
+import { OpenAIBaseChatCompletionsTextAdapter } from "@tanstack/openai-base";
+import type {
+  DefaultMessageMetadataByModality,
+  Modality,
+  ModelReasoning,
+} from "@tanstack/ai";
+
+const MY_MODEL_REASONING: Record<string, ModelReasoning> = {
+  "my-model": {
+    map: { off: "none", minimal: null, low: "low", medium: "medium", high: "high" },
+    budget: false,
+  },
+};
+
+class MyTextAdapter extends OpenAIBaseChatCompletionsTextAdapter<
+  "my-model",
+  Record<string, unknown>,
+  ReadonlyArray<Modality>,
+  DefaultMessageMetadataByModality,
+  ReadonlyArray<string>,
+  { levels: "off" | "low" | "medium" | "high"; budget: false }
+> {
+  protected override modelReasoning(model: string) {
+    return MY_MODEL_REASONING[model];
+  }
+}
+
+export const myText = () =>
+  new MyTextAdapter(
+    "my-model",
+    "my-provider",
+    new OpenAI({ apiKey: process.env.MY_API_KEY, baseURL: "https://api.example.com/v1" }),
+  );
+```
+
+An adapter with another wire format calls `resolveReasoning` from `@tanstack/ai/adapter-internals` in its request code and sends the result its own way.
+
+Models added with `extendAdapter` take no `reasoning` option, because the adapter has no reasoning data for them.
diff --git a/docs/advanced/typed-options.md b/docs/advanced/typed-options.md
index f75efe5e22..b1a7f5f89c 100644
--- a/docs/advanced/typed-options.md
+++ b/docs/advanced/typed-options.md
@@ -34,8 +34,8 @@ const chatOptions = createChatOptions({
   // native key.
   modelOptions: {
     temperature: 0.3,
-    reasoning: { effort: 'medium' },
   },
+  reasoning: 'medium',
 })
 
 // Later, anywhere in your codebase:
@@ -96,9 +96,7 @@ export const supportChatOptions = createChatOptions({
   adapter: openaiText('gpt-5.5'),
   systemPrompts: ['You are a customer-support assistant for Acme Corp.'],
   tools: [lookupOrder],
-  modelOptions: {
-    reasoning: { effort: 'medium' },
-  },
+  reasoning: 'medium',
 })
 ```
 
diff --git a/docs/chat/reasoning.md b/docs/chat/reasoning.md
new file mode 100644
index 0000000000..0a35725704
--- /dev/null
+++ b/docs/chat/reasoning.md
@@ -0,0 +1,118 @@
+---
+title: Reasoning
+id: reasoning
+order: 6
+description: "Set how hard a reasoning model thinks with one reasoning option on chat(), the same on every provider, with per-model type checks."
+keywords:
+  - tanstack ai
+  - reasoning
+  - thinking
+  - reasoning effort
+  - extended thinking
+  - thinking budget
+---
+
+Every provider has its own switch for reasoning: `reasoning.effort` on OpenAI, `thinking` on Anthropic, `thinkingConfig` on Gemini, `think` on Ollama. The `reasoning` option on `chat()` is one switch for all of them. You pick a level, and the adapter sends what the model needs.
+
+## Set a level
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { openaiText } from "@tanstack/ai-openai";
+
+const stream = chat({
+  adapter: openaiText("gpt-5.5"),
+  messages: [{ role: "user", content: "Plan a database migration." }],
+  reasoning: "high",
+});
+```
+
+The levels, from least to most thinking, are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Leave `reasoning` out to keep the provider's default.
+
+## The types show the model's levels
+
+Each model has only some of the levels. The types take only the levels of the model you picked:
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+
+chat({
+  adapter: anthropicText("claude-opus-4-8"),
+  messages: [{ role: "user", content: "Hello" }],
+  reasoning: "max",
+});
+
+chat({
+  adapter: anthropicText("claude-haiku-4-5"),
+  messages: [{ role: "user", content: "Hello" }],
+  // @ts-expect-error claude-haiku-4-5 has no max level
+  reasoning: "max",
+});
+```
+
+A model that does not reason takes no `reasoning` option at all.
+
+## Hide the thinking text or set a budget
+
+Pass an object for more control:
+
+- `level`: the level.
+- `summary`: `false` keeps the thinking text out of the stream. The default is `true`.
+- `budgetTokens`: a thinking token budget. Only models that think with a budget take it, such as Claude Haiku 4.5 and Gemini 2.5.
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+
+const stream = chat({
+  adapter: anthropicText("claude-haiku-4-5"),
+  messages: [{ role: "user", content: "Check this proof." }],
+  reasoning: { level: "high", budgetTokens: 8000 },
+});
+```
+
+Without `budgetTokens`, a budget model gets a budget for the level: 1024 tokens for `minimal`, 2048 for `low`, 8192 for `medium`, and 16384 for `high`.
+
+## A level from the user
+
+A level from a settings menu may not be one the model has. The adapter moves it to the nearest level the model has: up first, then down. For example, `minimal` on `claude-opus-4-8` becomes `low`.
+
+To show only the levels a model has, read them from the [model catalog](../models/catalog):
+
+```typescript
+import { getModel, supportedReasoningLevels } from "@tanstack/ai-models";
+
+const model = getModel("anthropic", "claude-opus-4-8");
+const levels = model ? supportedReasoningLevels(model) : [];
+// ["low", "medium", "high", "xhigh", "max"]
+```
+
+## Change the level in middleware
+
+Middleware can set the level for a call, for example to lower it on a retry:
+
+```typescript
+import type { ChatMiddleware } from "@tanstack/ai";
+
+const lowEffort: ChatMiddleware = {
+  name: "low-effort",
+  onConfig: () => ({ reasoning: { level: "low", summary: true } }),
+};
+```
+
+## What each provider receives
+
+| Provider | Sent as |
+| --- | --- |
+| OpenAI, Grok, Bedrock Responses | `reasoning.effort`, with a summary |
+| Anthropic | adaptive thinking with the effort, or a thinking budget |
+| Gemini | `thinkingConfig.thinkingLevel` or `thinkingConfig.thinkingBudget` |
+| OpenRouter, Vercel AI Gateway | the gateway's `reasoning` object |
+| Groq, LLM Gateway, Lovable, Cloudflare, Bedrock chat | `reasoning_effort` |
+| Mistral | `reasoning_effort` or `prompt_mode` |
+| Ollama | `think` |
+| Claude Code, Codex | the CLI effort setting |
+| `openaiCompatible` | the model's `thinkingFormat`, see [OpenAI-Compatible](../adapters/openai-compatible#reasoning-models) |
+
+The thinking text streams back as thinking parts. See [Thinking & Reasoning](./thinking-content) to show it in your UI.
diff --git a/docs/chat/thinking-content.md b/docs/chat/thinking-content.md
index b610f08b8e..2157f1e802 100644
--- a/docs/chat/thinking-content.md
+++ b/docs/chat/thinking-content.md
@@ -35,11 +35,7 @@ The `ThinkingPart` appears in `UIMessage.parts` alongside `TextPart` and `ToolCa
 
 ## Enabling Thinking
 
-How you enable thinking depends on the provider.
-
-### Anthropic (Extended Thinking)
-
-Pass the `thinking` option in `modelOptions` with `type: "enabled"` and a `budget_tokens` (minimum 1024). Keep `budget_tokens` below `modelOptions.max_tokens` so there is room for the visible response in addition to the thinking budget:
+Turn thinking on with `reasoning` on `chat()`. It works the same on every provider:
 
 ```typescript
 import { chat, toServerSentEventsResponse } from "@tanstack/ai";
@@ -50,60 +46,13 @@ export async function POST(request: Request) {
   const stream = chat({
     adapter: anthropicText("claude-sonnet-4-6"),
     messages,
-    modelOptions: {
-      max_tokens: 32000,
-      // budget_tokens must be at least 1024 and below max_tokens
-      thinking: { type: "enabled", budget_tokens: 10000 },
-    },
+    reasoning: "high",
   });
   return toServerSentEventsResponse(stream);
 }
 ```
 
-### OpenAI (Reasoning Models)
-
-OpenAI o-series models (o1, o3, o3-mini, o3-pro) perform reasoning automatically. You can control the depth with the `reasoning` option:
-
-```typescript
-import { chat, toServerSentEventsResponse } from "@tanstack/ai";
-import { openaiText } from "@tanstack/ai-openai";
-
-export async function POST(request: Request) {
-  const { messages } = await request.json();
-  const stream = chat({
-    adapter: openaiText("o3-mini"),
-    messages,
-    modelOptions: {
-      reasoning: {
-        effort: "medium", // 'none' | 'minimal' | 'low' | 'medium' | 'high'
-        summary: "auto", // 'auto' | 'detailed'
-      },
-    },
-  });
-  return toServerSentEventsResponse(stream);
-}
-```
-
-When `reasoning.summary` is set, the adapter streams reasoning summary text as thinking content. Without it, reasoning tokens are still used internally but may not be surfaced depending on the model.
-
-GPT-5 and later models also support reasoning. Their `reasoning.effort` accepts `"none" | "minimal" | "low" | "medium" | "high"`, and reasoning activates on any non-`none` value:
-
-```typescript
-import { chat, toServerSentEventsResponse } from "@tanstack/ai";
-import { openaiText } from "@tanstack/ai-openai";
-
-export async function POST(request: Request) {
-  const { messages } = await request.json();
-  const stream = chat({
-    adapter: openaiText("gpt-5.5"),
-    messages,
-    modelOptions: {
-      reasoning: { effort: "high" },
-    },
-  });
-  return toServerSentEventsResponse(stream);
-}
-```
+The thinking text streams back as `ThinkingPart`s. Some models reason without returning any text; with those, the part stays empty. See [Reasoning](./reasoning) for the levels, token budgets, and hiding the thinking text.
 
 ## Rendering in React
 
diff --git a/docs/community-adapters/guide.md b/docs/community-adapters/guide.md
index e70d6f9d48..4123ed2f73 100644
--- a/docs/community-adapters/guide.md
+++ b/docs/community-adapters/guide.md
@@ -92,13 +92,11 @@ Example:
 ```typescript ignore
 export type OpenAIChatModelProviderOptionsByName = {
   [GPT5_2.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
     OpenAIMetadataOptions
   [GPT5_2_CHAT.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
@@ -109,6 +107,8 @@ export type OpenAIChatModelProviderOptionsByName = {
 ```
 This ensures strict type safety and feature correctness at compile time.
 
+Reasoning is not a provider option: `chat({ reasoning })` owns it. Declare each model's reasoning levels on the adapter instead. See [Add reasoning to your adapter](../advanced/extend-adapter#add-reasoning-to-your-adapter).
+
 ### 5. Define supported input modalities
 
 Models typically support different input modalities (e.g. text, images, audio). These must be defined per model to prevent invalid usage.
@@ -140,9 +140,9 @@ export interface OpenAIBaseOptions {
 // Feature fragments that can be stitched per-model 
 
 /**
- * Reasoning options for models  
+ * Tool options for models
  */
-export interface OpenAIReasoningOptions {
+export interface OpenAIToolsOptions {
    //...
 }
  
@@ -160,7 +160,6 @@ Models can then opt into only the features they support:
 ```typescript ignore
 export type OpenAIChatModelProviderOptionsByName = {
   [GPT5_2.name]: OpenAIBaseOptions &
-    OpenAIReasoningOptions &
     OpenAIStructuredOutputOptions &
     OpenAIToolsOptions &
     OpenAIStreamingOptions &
diff --git a/docs/config.json b/docs/config.json
index e51bc8931b..447ae89cfb 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -78,7 +78,8 @@
         {
           "label": "Persisted subagents",
           "to": "tutorials/subagents-persisted",
-          "addedAt": "2026-09-22"
+          "addedAt": "2026-09-22",
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "Build an MCP Server",
@@ -177,7 +178,12 @@
           "label": "Thinking & Reasoning",
           "to": "chat/thinking-content",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-08-21"
+          "updatedAt": "2026-09-30"
+        },
+        {
+          "label": "Reasoning",
+          "to": "chat/reasoning",
+          "addedAt": "2026-09-30"
         },
         {
           "label": "Message Queue",
@@ -1218,13 +1224,19 @@
         {
           "label": "Extend Adapter",
           "to": "advanced/extend-adapter",
-          "addedAt": "2026-04-15"
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-09-30"
+        },
+        {
+          "label": "Model Catalog",
+          "to": "models/catalog",
+          "addedAt": "2026-09-30"
         },
         {
           "label": "Typed Pre-Configured Options",
           "to": "advanced/typed-options",
           "addedAt": "2026-05-25",
-          "updatedAt": "2026-09-14"
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "Approval Flow Processing",
@@ -1242,19 +1254,19 @@
           "label": "OpenAI",
           "to": "adapters/openai",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-09-25"
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "Anthropic",
           "to": "adapters/anthropic",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-08-19"
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "Google Gemini",
           "to": "adapters/gemini",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-09-24"
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "Google Vertex AI",
@@ -1278,7 +1290,7 @@
           "label": "Groq",
           "to": "adapters/groq",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-08-07"
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "Mistral",
@@ -1330,7 +1342,7 @@
           "label": "OpenRouter Adapter",
           "to": "adapters/openrouter",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-09-25"
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "Perplexity Search",
@@ -1353,18 +1365,19 @@
           "label": "OpenAI-Compatible",
           "to": "adapters/openai-compatible",
           "addedAt": "2026-06-01",
-          "updatedAt": "2026-09-27"
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "LLM Gateway",
           "to": "adapters/llmgateway",
-          "addedAt": "2026-07-29"
+          "addedAt": "2026-07-29",
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "Cloudflare",
           "to": "adapters/cloudflare",
           "addedAt": "2026-09-03",
-          "updatedAt": "2026-09-18"
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "Claude Code",
@@ -1376,7 +1389,7 @@
           "label": "Codex",
           "to": "adapters/codex",
           "addedAt": "2026-06-12",
-          "updatedAt": "2026-08-18"
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "OpenCode",
@@ -1406,7 +1419,7 @@
           "label": "BytePlus",
           "to": "adapters/byteplus",
           "addedAt": "2026-08-04",
-          "updatedAt": "2026-09-16"
+          "updatedAt": "2026-09-30"
         }
       ],
       "tab": "adapters"
@@ -1419,7 +1432,7 @@
           "label": "Community Adapters Guide",
           "to": "community-adapters/guide",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-08-21"
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "Decart",
@@ -1481,6 +1494,11 @@
           "to": "migration/sampling-options-to-model-options",
           "addedAt": "2026-06-03"
         },
+        {
+          "label": "Reasoning option",
+          "to": "migration/reasoning-option",
+          "addedAt": "2026-09-30"
+        },
         {
           "label": "TextPart markdown",
           "to": "migration/text-part-markdown",
diff --git a/docs/migration/reasoning-option.md b/docs/migration/reasoning-option.md
new file mode 100644
index 0000000000..462ad8911d
--- /dev/null
+++ b/docs/migration/reasoning-option.md
@@ -0,0 +1,90 @@
+---
+title: Moving Reasoning into chat({ reasoning })
+description: "Move provider reasoning and thinking settings out of modelOptions and into the reasoning option on chat()."
+keywords:
+  - tanstack ai
+  - migration
+  - reasoning
+  - thinking
+  - modelOptions
+---
+
+> **TL;DR:** This is a **breaking change**. Reasoning and thinking settings are no longer in `modelOptions`. Set them with the `reasoning` option on `chat()`. It takes a level, `off` to `max`, or `{ level, summary, budgetTokens }`.
+
+## Move your code
+
+Find the reasoning field in your `modelOptions`, delete it, and set `reasoning` on `chat()`:
+
+```typescript ignore
+// Before
+chat({
+  adapter: openaiText("gpt-5.5"),
+  messages,
+  modelOptions: { reasoning: { effort: "high", summary: "auto" } },
+});
+```
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { openaiText } from "@tanstack/ai-openai";
+
+const messages = [{ role: "user" as const, content: "Hello" }];
+
+// After
+chat({
+  adapter: openaiText("gpt-5.5"),
+  messages,
+  reasoning: "high",
+});
+```
+
+The summary is on by default. Pass `reasoning: { level: "high", summary: false }` to turn it off.
+
+## The old fields, by provider
+
+| Provider | Old `modelOptions` field | Now |
+| --- | --- | --- |
+| OpenAI | `reasoning: { effort, summary }` | `reasoning: "high"` |
+| Anthropic | `thinking`, `effort`, `output_config.effort` | `reasoning: "high"`, or `{ level, budgetTokens }` on budget models |
+| Gemini | `thinkingConfig` | `reasoning: "high"`, or `{ level, budgetTokens }` on Gemini 2.5 |
+| Gemini Interactions | `generation_config.thinking_level` | `reasoning: "high"` |
+| Grok, OpenRouter | `reasoning: { effort }` | `reasoning: "high"` |
+| Vercel AI Gateway, Lovable | `reasoning`, `include_reasoning` | `reasoning: "high"` |
+| Bedrock | `reasoning_effort`, `reasoning` | `reasoning: "high"` |
+| Groq, LLM Gateway, Cloudflare | `reasoning_effort` | `reasoning: "high"` |
+| BytePlus | `thinking`, `reasoning_effort` | `reasoning: "high"`, or `"off"` |
+| Ollama | `think` | `reasoning: "high"`, or `"off"` |
+| Codex | `modelReasoningEffort` | `reasoning: "high"` |
+
+For Anthropic budget thinking, the budget moves to `budgetTokens`:
+
+```typescript ignore
+// Before
+modelOptions: { thinking: { type: "enabled", budget_tokens: 8000 } }
+```
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+
+const messages = [{ role: "user" as const, content: "Hello" }];
+
+// After
+chat({
+  adapter: anthropicText("claude-haiku-4-5"),
+  messages,
+  reasoning: { level: "high", budgetTokens: 8000 },
+});
+```
+
+## Removed types
+
+These types described the old fields and are gone:
+
+- `@tanstack/ai-openai`: `OpenAIReasoningOptions`, `OpenAIReasoningOptionsWithConcise`.
+- `@tanstack/ai-anthropic`: `AnthropicThinkingOptions` and the adaptive, effort, and output-config thinking option types.
+- `@tanstack/ai-gemini`: `GeminiThinkingOptions`.
+- `@tanstack/ai-grok`: `GrokReasoning`, `GrokReasoningEffort`.
+- `@tanstack/ai-openrouter`: `ReasoningOptions`. `@tanstack/ai-byteplus`: `BytePlusThinkingOption`, `BytePlusReasoningEffort`.
+
+See [Reasoning](../chat/reasoning) for the levels and what each provider receives.
diff --git a/docs/models/catalog.md b/docs/models/catalog.md
new file mode 100644
index 0000000000..a60239f7be
--- /dev/null
+++ b/docs/models/catalog.md
@@ -0,0 +1,85 @@
+---
+title: Model Catalog
+id: catalog
+description: "Look up models, reasoning levels, prices, and provider quirks at runtime with @tanstack/ai-models."
+keywords:
+  - tanstack ai
+  - model catalog
+  - models.dev
+  - model metadata
+  - reasoning levels
+  - model pricing
+---
+
+A model picker, a cost display, or a settings menu needs facts about models at runtime: which models a provider has, which reasoning levels a model takes, and what a call costs. `@tanstack/ai-models` is a catalog of that data for more than 1,900 models across 38 providers.
+
+## Install
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: @tanstack/ai-models
+vue: @tanstack/ai-models
+solid: @tanstack/ai-models
+svelte: @tanstack/ai-models
+preact: @tanstack/ai-models
+angular: @tanstack/ai-models
+vanilla: @tanstack/ai-models
+octane: @tanstack/ai-models
+
+<!-- ::end:tabs -->
+
+## Look up a model
+
+```typescript
+import { getModel, getModels, getProviders } from "@tanstack/ai-models";
+
+const providers = getProviders(); // every provider: id, name, baseUrl, env
+const deepseekModels = getModels("deepseek"); // every DeepSeek model
+const model = getModel("deepseek", "deepseek-v4-flash");
+
+console.log(model?.contextWindow, model?.maxTokens, model?.input);
+```
+
+Each record has the model's `id`, `name`, `input` modalities, `contextWindow`, `maxTokens`, prices, and reasoning data. `getModel` returns `undefined` for a model the catalog does not have.
+
+## Show the reasoning levels
+
+`supportedReasoningLevels` gives the levels a model takes. Use it to fill a menu:
+
+```typescript
+import { getModel, supportedReasoningLevels } from "@tanstack/ai-models";
+
+const model = getModel("deepseek", "deepseek-v4-flash");
+const levels = model ? supportedReasoningLevels(model) : [];
+// ["off", "low", "high", "max"]
+```
+
+`clampReasoningLevel(model, level)` gives the level an adapter uses for a level the model does not have. Pass the level to [`chat({ reasoning })`](../chat/reasoning).
+
+## Work out what a call cost
+
+Prices are in USD per million tokens. `modelCost` turns token counts into a cost:
+
+```typescript
+import { getModel, modelCost } from "@tanstack/ai-models";
+
+const model = getModel("openai", "gpt-5.5");
+if (model) {
+  const cost = modelCost(model, { input: 12_000, output: 800 });
+  console.log(cost.total.toFixed(4));
+}
+```
+
+## Load one provider only
+
+The root import has every provider. To load only one, import its subpath:
+
+```typescript
+import { models, provider } from "@tanstack/ai-models/deepseek";
+
+console.log(provider.baseUrl, models.length);
+```
+
+## Keep it up to date
+
+The catalog is generated from [models.dev](https://models.dev) and the OpenRouter and Vercel AI Gateway model lists. `generatedAt` is the time of the last update. A record with `borrowedFrom` took its data from the same model at another provider.
diff --git a/docs/tutorials/subagents-persisted.md b/docs/tutorials/subagents-persisted.md
index f3f06a90a6..3d8ace5769 100644
--- a/docs/tutorials/subagents-persisted.md
+++ b/docs/tutorials/subagents-persisted.md
@@ -284,7 +284,7 @@ A 404, or a page with no summary, returns `{ found: false }`. Any other HTTP sta
 In the researcher `chat()` call, add the tool and the reasoning option. Keep `subagentRunId: ctx.subagentRunId` on each child `chat()`. Tell the model to use the tool:
 
 ```ts ignore
-modelOptions: { reasoning: { effort: 'medium' } },
+reasoning: 'medium',
 tools: [lookupWikipediaTool],
 systemPrompts: [
   'You research for a blog desk. Call lookupWikipedia once for each topic before you reply. Then reply in Markdown with short notes, and give the Wikipedia URL as the source. Use a list. Do not write the full post.',
diff --git a/packages/ai-anthropic/README.md b/packages/ai-anthropic/README.md
index 7ae0bfe4f7..b0f815acc2 100644
--- a/packages/ai-anthropic/README.md
+++ b/packages/ai-anthropic/README.md
@@ -98,21 +98,17 @@ export async function POST(request: Request) {
 
 ### Thinking
 
-Newer Claude models use adaptive thinking — the model decides when and how much to think, and depth is tuned with `output_config.effort`:
+Set how hard Claude thinks with `reasoning` on `chat()`:
 
 ```typescript
 const stream = chat({
   adapter: anthropicText('claude-sonnet-5'),
   messages: [{ role: 'user', content: 'Plan a database migration.' }],
-  modelOptions: {
-    thinking: { type: 'adaptive', display: 'summarized' },
-    output_config: { effort: 'xhigh' },
-    max_tokens: 64_000,
-  },
+  reasoning: 'xhigh',
 })
 ```
 
-Claude 4.6 models also accept the manual `{ type: 'enabled', budget_tokens }` shape; `budget_tokens` must be less than `max_tokens`. Which shapes and sampling parameters each model accepts is enforced by the adapter's types — see the docs for the per-model rules.
+The adapter sends adaptive thinking with the effort on Claude 4.6 and later, and a thinking token budget on older models (`reasoning: { level: 'high', budgetTokens: 8000 }`). The types take only the levels each model has.
 
 ### Prompt Caching
 
diff --git a/packages/ai-byteplus/README.md b/packages/ai-byteplus/README.md
index 3aa5287d31..8b0a723d12 100644
--- a/packages/ai-byteplus/README.md
+++ b/packages/ai-byteplus/README.md
@@ -96,7 +96,8 @@ Drop `stream: false` to get the default streaming form, which yields
 
 Seed models reason by default. Reasoning arrives as a separate stream of
 `reasoning_content` deltas and is surfaced as reasoning content, not answer
-text. Pass `thinking: { type: 'disabled' }` in provider options to turn it off.
+text. Pass `reasoning: 'off'` to `chat()` to turn it off on a model that can
+stop thinking.
 
 ### Video (Seedance)
 
diff --git a/packages/ai/skills/ai-core/adapter-configuration/SKILL.md b/packages/ai/skills/ai-core/adapter-configuration/SKILL.md
index 51f493a628..8d56068bd4 100644
--- a/packages/ai/skills/ai-core/adapter-configuration/SKILL.md
+++ b/packages/ai/skills/ai-core/adapter-configuration/SKILL.md
@@ -187,29 +187,21 @@ const messages = [
   { role: 'user' as const, content: 'Plan a database migration.' },
 ]
 
-// OpenAI: reasoning with effort and summary
+// Reasoning is one option on chat() for every provider. The types list only
+// the levels the model has; a runtime level moves to the nearest one.
+// OpenAI: sent as reasoning.effort with a summary
 const openaiStream = chat({
   adapter: openaiText('gpt-5.2'),
   messages,
-  modelOptions: {
-    reasoning: {
-      effort: 'high',
-      summary: 'auto',
-    },
-  },
+  reasoning: 'high',
 })
 
-// Anthropic: extended thinking with budget_tokens
+// Anthropic budget models: a thinking token budget. The adapter raises
+// max_tokens past the budget when needed.
 const anthropicStream = chat({
-  adapter: anthropicText('claude-sonnet-4-6'),
+  adapter: anthropicText('claude-haiku-4-5'),
   messages,
-  modelOptions: {
-    max_tokens: 16000,
-    thinking: {
-      type: 'enabled',
-      budget_tokens: 8000, // must be >= 1024 and < max_tokens
-    },
-  },
+  reasoning: { level: 'high', budgetTokens: 8000 },
 })
 
 // Anthropic: adaptive thinking (Sonnet 5, Fable 5, Opus 4.7+) — depth is
@@ -217,26 +209,18 @@ const anthropicStream = chat({
 const adaptiveStream = chat({
   adapter: anthropicText('claude-sonnet-5'),
   messages,
-  modelOptions: {
-    max_tokens: 16000,
-    thinking: {
-      type: 'adaptive',
-      display: 'summarized', // stream the reasoning text (default 'omitted')
-    },
-    output_config: { effort: 'high' }, // 'low' | 'medium' | 'high' | 'xhigh' | 'max'
-  },
+  modelOptions: { max_tokens: 16000 },
+  // Sent as adaptive thinking with output_config.effort. `summary: false`
+  // hides the thinking text.
+  reasoning: 'xhigh',
 })
 
 // Gemini: thinking config with budget or level
 const geminiStream = chat({
   adapter: geminiText('gemini-2.5-pro'),
   messages,
-  modelOptions: {
-    thinkingConfig: {
-      includeThoughts: true,
-      thinkingBudget: 4096,
-    },
-  },
+  // Gemini 2.5 thinks with a budget; Gemini 3 takes thinking levels.
+  reasoning: { level: 'medium', budgetTokens: 4096 },
 })
 ```
 
diff --git a/packages/ai/skills/ai-core/adapter-configuration/references/anthropic-adapter.md b/packages/ai/skills/ai-core/adapter-configuration/references/anthropic-adapter.md
index eae98820e0..f3a1dde528 100644
--- a/packages/ai/skills/ai-core/adapter-configuration/references/anthropic-adapter.md
+++ b/packages/ai/skills/ai-core/adapter-configuration/references/anthropic-adapter.md
@@ -42,11 +42,10 @@ Retired models (Claude 3.x, Sonnet 3.7, Opus 4 / Sonnet 4) were removed —
 every registered id resolves against the first-party Anthropic API.
 `claude-opus-5-fast` is the only `-fast` id that remains.
 
-`output_config.effort` is typed only on the adaptive-era models
-(`claude-opus-4-7`, `claude-opus-4-8`, `claude-sonnet-5`, `claude-fable-5`,
-`claude-fable-5-1`). There is no top-level `effort` option on any model;
-`claude-opus-4-6` / `claude-sonnet-4-6` accept `thinking: { type: 'adaptive' }`
-but no effort knob.
+Thinking is set with `chat({ reasoning })`, not `modelOptions`. The adapter
+sends adaptive thinking with `output_config.effort` on Claude 4.7 and later,
+adaptive thinking with a top-level `effort` on `claude-opus-4-6` /
+`claude-sonnet-4-6`, and a thinking token budget on the older models.
 
 ## Provider-Specific modelOptions
 
@@ -64,15 +63,6 @@ chat({
     temperature: 0.7,
     // top_p: 0.9, // cannot be combined with temperature
     max_tokens: 16000,
-    // Extended thinking (budget-based)
-    thinking: {
-      type: 'enabled',
-      budget_tokens: 8000, // must be >= 1024 and < max_tokens
-    },
-    // Adaptive thinking (claude-sonnet-4-6, claude-opus-4-6+) — the
-    // alternative to the budget shape above; effort is tuned via
-    // output_config.effort on the adaptive-era models (see below)
-    // thinking: { type: 'adaptive' },
     // Service tier
     service_tier: 'auto', // 'auto' | 'standard_only'
     // Stop sequences
@@ -120,14 +110,10 @@ const messages = [{ role: 'user' as const, content: 'Hello' }]
 chat({
   adapter: anthropicText('claude-sonnet-5'), // or 'claude-fable-5', 'claude-opus-4-8'
   messages,
+  // Adaptive thinking with output_config.effort. 'xhigh' is a level on
+  // Opus 4.7+, Sonnet 5, and Fable 5. claude-fable-5 cannot turn thinking off.
+  reasoning: 'xhigh',
   modelOptions: {
-    // Adaptive thinking only — budget_tokens is rejected (400).
-    // On claude-fable-5, { type: 'disabled' } is also rejected;
-    // elsewhere it opts out of thinking.
-    thinking: { type: 'adaptive', display: 'summarized' },
-    // Effort lives under output_config; 'xhigh' is available on
-    // Opus 4.7+, Sonnet 5, and Fable 5.
-    output_config: { effort: 'xhigh' },
     max_tokens: 64_000,
     // NO temperature / top_p / top_k — the API rejects them on these models
   },
@@ -136,12 +122,11 @@ chat({
 
 ## Gotchas
 
-- `thinking.budget_tokens` must be >= 1024 AND less than `modelOptions.max_tokens`.
-  Failing either check throws a validation error.
+- A thinking budget (`reasoning: { level, budgetTokens }`) goes only to the
+  budget models. The adapter raises `max_tokens` above the budget.
 - Cannot set both `top_p` and `temperature` at the same time (throws error).
 - `claude-sonnet-5`, `claude-fable-5`, `claude-opus-4-8`, and
-  `claude-opus-4-7` do NOT accept `temperature`, `top_p`, `top_k`, or
-  `thinking: { type: 'enabled', budget_tokens }` — adaptive thinking +
-  `output_config.effort` replace them (typed per model).
+  `claude-opus-4-7` do NOT accept `temperature`, `top_p`, or `top_k`
+  (typed per model). Their `reasoning` levels go out as adaptive thinking.
 - System prompts support prompt caching via `cache_control` on `TextBlockParam[]`.
 - All Claude models accept `text`, `image`, and `document` (PDF) input.
diff --git a/packages/ai/skills/ai-core/adapter-configuration/references/byteplus-adapter.md b/packages/ai/skills/ai-core/adapter-configuration/references/byteplus-adapter.md
index 44415dec86..45fefa8c93 100644
--- a/packages/ai/skills/ai-core/adapter-configuration/references/byteplus-adapter.md
+++ b/packages/ai/skills/ai-core/adapter-configuration/references/byteplus-adapter.md
@@ -40,10 +40,10 @@ import { byteplusSpeech, byteplusTranscription } from '@tanstack/ai-byteplus'
 | `seed-2-0-pro-260328`        | 256K    | Structured output; thinking summary                                |
 | `seed-2-0-lite-260228`       | 256K    | Structured output — use instead of `-260428` for typed output      |
 | `seed-1-6-flash-250715`      | 256K    | Fast/cheap; structured output                                      |
-| `glm-5-2-260617`             | 1024K   | Structured output; `reasoning_effort` incl. `none`/`xhigh`/`max`   |
+| `glm-5-2-260617`             | 1024K   | Structured output; reasoning levels `off` to `max`                 |
 | `deepseek-v4-pro-260425`     | 1024K   | 384K output; no structured output                                  |
 | `deepseek-v3-2-251201`       | 128K    | Reasoning defaults **off**; no structured output                   |
-| `gpt-oss-120b-250805`        | 128K    | Only model accepting `thinking: { type: 'auto' }`                  |
+| `gpt-oss-120b-250805`        | 128K    | Reasoning levels `low`, `medium`, `high`                           |
 
 `BYTEPLUS_CHAT_MODELS` is the full list of 18 (also
 `seed-2-0-mini-260215`, `seed-2-0-code-preview-260328`, `seed-1-8-251228`,
@@ -72,8 +72,6 @@ chat({
   messages,
   modelOptions: {
     // Ark-only
-    thinking: { type: 'enabled' }, // 'enabled' | 'disabled' | 'auto' ('auto': gpt-oss-120b only)
-    reasoning_effort: 'medium', // 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
     repetition_penalty: 1.1,
     service_tier: 'default', // 'default' | 'flex' (flex = cheaper offline batch queue)
     // Sampling (OpenAI-compatible names)
@@ -122,8 +120,10 @@ BYTEPLUS_VOICE_API_KEY   # TTS + transcription — a DIFFERENT product key
   reject `json_object` too, so there is no JSON-mode fallback. `glm-4-7-251222`
   is excluded deliberately — it accepts the schema with `200` and then answers
   in prose. `seed-2-0-lite-260428` is _not_ on the list.
-- **`reasoning_effort` + `thinking: { type: 'disabled' }` is a 400.** So is
-  sending both `max_tokens` and `max_completion_tokens`.
+- **Thinking is `chat({ reasoning })`.** The adapter sends `thinking.type`
+  plus `reasoning_effort`, and only `disabled` for `off`, because Ark rejects
+  an effort next to it. Sending both `max_tokens` and `max_completion_tokens`
+  is a 400.
 - **`reasoning_effort` values are gated per model.** `minimal` / `low` /
   `medium` / `high` are general; `none` and `xhigh` are accepted only by
   `glm-5-2-260617`; `max` only by `glm-5-2-260617` and the two
diff --git a/packages/ai/skills/ai-core/adapter-configuration/references/gemini-adapter.md b/packages/ai/skills/ai-core/adapter-configuration/references/gemini-adapter.md
index e5a1b67626..8432ca5aa3 100644
--- a/packages/ai/skills/ai-core/adapter-configuration/references/gemini-adapter.md
+++ b/packages/ai/skills/ai-core/adapter-configuration/references/gemini-adapter.md
@@ -50,15 +50,9 @@ const messages = [{ role: 'user' as const, content: 'Hello' }]
 chat({
   adapter: geminiText('gemini-2.5-pro'),
   messages,
+  // Thinking: a budget on Gemini 2.5, a thinking level on Gemini 3
+  reasoning: { level: 'medium', budgetTokens: 4096 },
   modelOptions: {
-    // Thinking (budget-based)
-    thinkingConfig: {
-      includeThoughts: true,
-      thinkingBudget: 4096,
-    },
-    // Thinking (level-based, advanced models) — the alternative to the
-    // budget shape above:
-    // thinkingConfig: { thinkingLevel: 'THINKING_LEVEL_HIGH' },
     // Safety settings
     safetySettings: [
       {
@@ -108,6 +102,7 @@ Note: `GOOGLE_GENAI_API_KEY` does NOT work.
   `gemini-3.1-flash-image-preview` were shut down on 2026-06-25 and now 404;
   they remain in the type union only as deprecated aliases, so a call to them
   compiles and then fails at runtime.
-- `thinkingConfig.thinkingLevel` (level-based) and `thinkingConfig.thinkingBudget`
-  (budget-based) serve different models. Check which your model supports.
+- Set thinking with `chat({ reasoning })`. The adapter sends
+  `thinkingConfig.thinkingLevel` on Gemini 3 and `thinkingConfig.thinkingBudget`
+  on Gemini 2.5; `budgetTokens` is typed only on the budget models.
 - `cachedContent` must follow the format `cachedContents/{id}`.
diff --git a/packages/ai/skills/ai-core/adapter-configuration/references/grok-adapter.md b/packages/ai/skills/ai-core/adapter-configuration/references/grok-adapter.md
index cf44d06e6e..b54e24545f 100644
--- a/packages/ai/skills/ai-core/adapter-configuration/references/grok-adapter.md
+++ b/packages/ai/skills/ai-core/adapter-configuration/references/grok-adapter.md
@@ -48,13 +48,13 @@ const messages = [{ role: 'user' as const, content: 'Hello' }]
 chat({
   adapter: grokText('grok-4.6'),
   messages,
+  // Reasoning is a chat() option, sent as reasoning.effort
+  reasoning: 'high',
   modelOptions: {
     // Sampling (Responses API names)
     temperature: 0.7,
     top_p: 0.9,
     max_output_tokens: 4096,
-    // Reasoning (reasoning-capable models)
-    reasoning: { effort: 'high' }, // 'none' | 'low' | 'medium' | 'high'
     // Response storage (adapter default: false)
     store: false,
     // End-user id for abuse monitoring
diff --git a/packages/ai/skills/ai-core/adapter-configuration/references/groq-adapter.md b/packages/ai/skills/ai-core/adapter-configuration/references/groq-adapter.md
index a2726f4483..046b27a81f 100644
--- a/packages/ai/skills/ai-core/adapter-configuration/references/groq-adapter.md
+++ b/packages/ai/skills/ai-core/adapter-configuration/references/groq-adapter.md
@@ -47,8 +47,7 @@ chat({
   adapter: groqText('llama-3.3-70b-versatile'),
   messages,
   modelOptions: {
-    // Reasoning
-    reasoning_effort: 'medium', // 'none' | 'default' | 'low' | 'medium' | 'high'
+    // How reasoning text comes back
     reasoning_format: 'parsed', // 'hidden' | 'raw' | 'parsed' (mutually exclusive with include_reasoning)
     include_reasoning: true, // mutually exclusive with reasoning_format
     // Response format
@@ -96,9 +95,9 @@ GROQ_API_KEY
 
 ## Gotchas
 
-- `reasoning_effort` and `reasoning_format` behave differently per model:
-  - qwen3 models: `'none'` disables reasoning, `'default'` or null enables it
-  - openai/gpt-oss models: `'low'`, `'medium'` (default), or `'high'`
+- Set the effort with `chat({ reasoning })` on a reasoning model; it goes out
+  as `reasoning_effort`. qwen3 only turns thinking on (`high`) or off (`off`),
+  and openai/gpt-oss takes `low`, `medium`, or `high`.
 - `include_reasoning` and `reasoning_format` are mutually exclusive.
 - Most models have `max_completion_tokens` of 8K-65K, not unlimited.
 - Groq specializes in inference speed; model selection is more limited
diff --git a/packages/ai/skills/ai-core/adapter-configuration/references/openai-adapter.md b/packages/ai/skills/ai-core/adapter-configuration/references/openai-adapter.md
index 047e04d8fe..6c0cda8deb 100644
--- a/packages/ai/skills/ai-core/adapter-configuration/references/openai-adapter.md
+++ b/packages/ai/skills/ai-core/adapter-configuration/references/openai-adapter.md
@@ -53,16 +53,13 @@ const messages = [{ role: 'user' as const, content: 'Hello' }]
 chat({
   adapter: openaiText('gpt-5.5'),
   messages,
+  // Reasoning is a chat() option, sent as reasoning.effort with a summary
+  reasoning: 'high',
   modelOptions: {
     // Sampling
     temperature: 0.7,
     top_p: 0.9,
     max_output_tokens: 1000,
-    // Reasoning (effort levels: none, minimal, low, medium, high)
-    reasoning: {
-      effort: 'high',
-      summary: 'auto', // 'auto' | 'detailed'
-    },
     // Service tier
     service_tier: 'auto', // 'auto' | 'default' | 'flex' | 'priority'
     // Response storage
diff --git a/packages/ai/skills/ai-core/adapter-configuration/references/openrouter-adapter.md b/packages/ai/skills/ai-core/adapter-configuration/references/openrouter-adapter.md
index 36601058ba..ea8a25df8c 100644
--- a/packages/ai/skills/ai-core/adapter-configuration/references/openrouter-adapter.md
+++ b/packages/ai/skills/ai-core/adapter-configuration/references/openrouter-adapter.md
@@ -49,13 +49,9 @@ const messages = [{ role: 'user' as const, content: 'Hello' }]
 chat({
   adapter: openRouterText('deepseek/deepseek-v4-pro'),
   messages,
+  // Reasoning is a chat() option, sent as reasoning.effort
+  reasoning: 'high',
   modelOptions: {
-    // Reasoning
-    reasoning: {
-      effort: 'high', // 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
-      summary: 'auto',
-      // enabled: false — explicit opt-out (normalized to effort: 'none')
-    },
     // Sampling
     temperature: 0.7,
     topP: 0.9,
diff --git a/packages/ai/skills/ai-core/chat-experience/SKILL.md b/packages/ai/skills/ai-core/chat-experience/SKILL.md
index d3ae7ca5cb..9361e3468e 100644
--- a/packages/ai/skills/ai-core/chat-experience/SKILL.md
+++ b/packages/ai/skills/ai-core/chat-experience/SKILL.md
@@ -243,12 +243,9 @@ export async function POST(request: Request) {
   const stream = chat({
     adapter: geminiText('gemini-3.8-flash'),
     messages,
-    modelOptions: {
-      thinkingConfig: {
-        includeThoughts: true,
-        thinkingLevel: 'HIGH', // Gemini 3.x; Gemini 2.x uses thinkingBudget
-      },
-    },
+    // Every provider takes the same option; the adapter sends Gemini's
+    // thinkingConfig with the thinking text included.
+    reasoning: 'high',
   })
 
   return toServerSentEventsResponse(stream)

From 15aa37094c978ae47cbb85627472e5bfc4e93af2 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 16:04:05 +0200
Subject: [PATCH 100/286] chore: changesets for chat({ reasoning }) and
 @tanstack/ai-models

One changeset per changed package. The reasoning move out of
modelOptions is a breaking minor on each adapter package, and
@tanstack/ai-models is a new package.

Also:

- the ai-models vite config reads its providers folder next to the
  config file, so knip can load it from the repo root
- the core reasoning type test puts its @ts-expect-error on the line
  with the error

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/ai-models-catalog.md               | 5 +++++
 .changeset/reasoning-option-anthropic.md      | 5 +++++
 .changeset/reasoning-option-bedrock.md        | 5 +++++
 .changeset/reasoning-option-byteplus.md       | 5 +++++
 .changeset/reasoning-option-claude-code.md    | 5 +++++
 .changeset/reasoning-option-cloudflare.md     | 5 +++++
 .changeset/reasoning-option-codex.md          | 5 +++++
 .changeset/reasoning-option-core.md           | 7 +++++++
 .changeset/reasoning-option-gemini.md         | 5 +++++
 .changeset/reasoning-option-grok.md           | 5 +++++
 .changeset/reasoning-option-groq.md           | 5 +++++
 .changeset/reasoning-option-llmgateway.md     | 5 +++++
 .changeset/reasoning-option-lovable.md        | 5 +++++
 .changeset/reasoning-option-mistral.md        | 5 +++++
 .changeset/reasoning-option-ollama.md         | 5 +++++
 .changeset/reasoning-option-openai-base.md    | 5 +++++
 .changeset/reasoning-option-openai.md         | 7 +++++++
 .changeset/reasoning-option-opencode.md       | 5 +++++
 .changeset/reasoning-option-openrouter.md     | 5 +++++
 .changeset/reasoning-option-vercel-gateway.md | 5 +++++
 packages/ai-models/vite.config.ts             | 6 ++++--
 packages/ai/tests/reasoning-types.test-d.ts   | 2 +-
 22 files changed, 109 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/ai-models-catalog.md
 create mode 100644 .changeset/reasoning-option-anthropic.md
 create mode 100644 .changeset/reasoning-option-bedrock.md
 create mode 100644 .changeset/reasoning-option-byteplus.md
 create mode 100644 .changeset/reasoning-option-claude-code.md
 create mode 100644 .changeset/reasoning-option-cloudflare.md
 create mode 100644 .changeset/reasoning-option-codex.md
 create mode 100644 .changeset/reasoning-option-core.md
 create mode 100644 .changeset/reasoning-option-gemini.md
 create mode 100644 .changeset/reasoning-option-grok.md
 create mode 100644 .changeset/reasoning-option-groq.md
 create mode 100644 .changeset/reasoning-option-llmgateway.md
 create mode 100644 .changeset/reasoning-option-lovable.md
 create mode 100644 .changeset/reasoning-option-mistral.md
 create mode 100644 .changeset/reasoning-option-ollama.md
 create mode 100644 .changeset/reasoning-option-openai-base.md
 create mode 100644 .changeset/reasoning-option-openai.md
 create mode 100644 .changeset/reasoning-option-opencode.md
 create mode 100644 .changeset/reasoning-option-openrouter.md
 create mode 100644 .changeset/reasoning-option-vercel-gateway.md

diff --git a/.changeset/ai-models-catalog.md b/.changeset/ai-models-catalog.md
new file mode 100644
index 0000000000..532cfc0717
--- /dev/null
+++ b/.changeset/ai-models-catalog.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-models': minor
+---
+
+New package: a runtime catalog of 1,932 models across 38 providers, generated from models.dev and the OpenRouter and Vercel AI Gateway model lists. `getProviders`, `getModels`, and `getModel` return each model's id, input modalities, context window, output limit, prices, reasoning levels, and request quirks (`compat`). `supportedReasoningLevels`, `clampReasoningLevel`, and `modelCost` work on a record, and `generatedAt` is the time of the data. Each provider also has its own subpath, for example `@tanstack/ai-models/deepseek`.
diff --git a/.changeset/reasoning-option-anthropic.md b/.changeset/reasoning-option-anthropic.md
new file mode 100644
index 0000000000..b1f737c01c
--- /dev/null
+++ b/.changeset/reasoning-option-anthropic.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-anthropic': minor
+---
+
+Breaking: set reasoning with `chat({ reasoning })`. `thinking`, `effort`, and `output_config.effort` leave `modelOptions`, with their option types. Claude 4.7 and later get adaptive thinking with `output_config.effort`, Claude 4.6 gets adaptive thinking with `effort`, older models get a thinking token budget, and `off` disables thinking.
diff --git a/.changeset/reasoning-option-bedrock.md b/.changeset/reasoning-option-bedrock.md
new file mode 100644
index 0000000000..a4b601e04a
--- /dev/null
+++ b/.changeset/reasoning-option-bedrock.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-bedrock': minor
+---
+
+Breaking: set reasoning with `chat({ reasoning })`. `reasoning_effort` (Chat Completions) and `reasoning` (Responses) leave `modelOptions`. On Converse, Claude gets budget thinking in `additionalModelRequestFields`.
diff --git a/.changeset/reasoning-option-byteplus.md b/.changeset/reasoning-option-byteplus.md
new file mode 100644
index 0000000000..2dee6d902e
--- /dev/null
+++ b/.changeset/reasoning-option-byteplus.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-byteplus': minor
+---
+
+Breaking: set reasoning with `chat({ reasoning })`. `thinking`, `reasoning_effort`, `BytePlusThinkingOption`, and `BytePlusReasoningEffort` are removed. The adapter sends `thinking.type`, plus `reasoning_effort` when the level has an effort.
diff --git a/.changeset/reasoning-option-claude-code.md b/.changeset/reasoning-option-claude-code.md
new file mode 100644
index 0000000000..834e9e3ac5
--- /dev/null
+++ b/.changeset/reasoning-option-claude-code.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-claude-code': minor
+---
+
+Add `chat({ reasoning })`: effort models get `--effort`, and budget models get `MAX_THINKING_TOKENS`.
diff --git a/.changeset/reasoning-option-cloudflare.md b/.changeset/reasoning-option-cloudflare.md
new file mode 100644
index 0000000000..2af64f90a5
--- /dev/null
+++ b/.changeset/reasoning-option-cloudflare.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-cloudflare': minor
+---
+
+Breaking: set reasoning with `chat({ reasoning })`. `modelOptions.reasoning_effort` is removed; `off` sends `null`. `chat_template_kwargs` stays in `modelOptions`.
diff --git a/.changeset/reasoning-option-codex.md b/.changeset/reasoning-option-codex.md
new file mode 100644
index 0000000000..fab04d0f9b
--- /dev/null
+++ b/.changeset/reasoning-option-codex.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-codex': minor
+---
+
+Breaking: set reasoning with `chat({ reasoning })`. `modelOptions.modelReasoningEffort` is removed. The adapter config's `modelReasoningEffort` stays as the default.
diff --git a/.changeset/reasoning-option-core.md b/.changeset/reasoning-option-core.md
new file mode 100644
index 0000000000..4352d9e063
--- /dev/null
+++ b/.changeset/reasoning-option-core.md
@@ -0,0 +1,7 @@
+---
+'@tanstack/ai': minor
+---
+
+Add `reasoning` to `chat()`: a level (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`) or `{ level, summary, budgetTokens }`. An adapter declares each model's levels, so the option is typed per model, and `budgetTokens` only goes to models that think with a token budget. Leaving it out keeps the provider default. Middleware can change it in `onConfig`.
+
+New exports: `REASONING_LEVELS`, `supportedReasoningLevels`, `clampReasoningLevel`, and the types `ReasoningLevel`, `ReasoningMap`, `ModelReasoning`, `ReasoningCapability`, `ReasoningOption`, `ReasoningOptionFor`, `ReasoningRequest`, and `AdapterReasoning`. Adapter authors get `resolveReasoning`, `reasoningValue`, `reasoningBudget`, and `DEFAULT_REASONING_BUDGETS` from `@tanstack/ai/adapter-internals`. `BaseTextAdapter` and `TextAdapter` take a new last type parameter for the reasoning levels.
diff --git a/.changeset/reasoning-option-gemini.md b/.changeset/reasoning-option-gemini.md
new file mode 100644
index 0000000000..2810d9e6a5
--- /dev/null
+++ b/.changeset/reasoning-option-gemini.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-gemini': minor
+---
+
+Breaking: set reasoning with `chat({ reasoning })`. `thinkingConfig` leaves the chat `modelOptions`, and `GeminiThinkingOptions` is removed. Gemini 3 gets `thinkingLevel`, Gemini 2.5 gets `thinkingBudget`, and the Interactions adapter gets `thinking_level`. Image generation keeps its own `thinkingConfig`.
diff --git a/.changeset/reasoning-option-grok.md b/.changeset/reasoning-option-grok.md
new file mode 100644
index 0000000000..0c53ee0b3b
--- /dev/null
+++ b/.changeset/reasoning-option-grok.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-grok': minor
+---
+
+Breaking: set reasoning with `chat({ reasoning })`. `modelOptions.reasoning`, `GrokReasoning`, and `GrokReasoningEffort` are removed. `grok-build-0.1` takes no reasoning, because the xAI API refuses it.
diff --git a/.changeset/reasoning-option-groq.md b/.changeset/reasoning-option-groq.md
new file mode 100644
index 0000000000..19c24e7bfe
--- /dev/null
+++ b/.changeset/reasoning-option-groq.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-groq': minor
+---
+
+Breaking: set reasoning with `chat({ reasoning })`. `modelOptions.reasoning_effort` is removed. Qwen 3 gets `default` or `none`. `reasoning_format` and `include_reasoning` stay in `modelOptions`.
diff --git a/.changeset/reasoning-option-llmgateway.md b/.changeset/reasoning-option-llmgateway.md
new file mode 100644
index 0000000000..e596e09258
--- /dev/null
+++ b/.changeset/reasoning-option-llmgateway.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-llmgateway': minor
+---
+
+Breaking: set reasoning with `chat({ reasoning })`. `modelOptions.reasoning_effort` is removed; the adapter sends the level as `reasoning_effort`.
diff --git a/.changeset/reasoning-option-lovable.md b/.changeset/reasoning-option-lovable.md
new file mode 100644
index 0000000000..a527404b68
--- /dev/null
+++ b/.changeset/reasoning-option-lovable.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-lovable': minor
+---
+
+Breaking: set reasoning with `chat({ reasoning })`. `reasoning` and `include_reasoning` leave `modelOptions`. The adapters send `reasoning_effort` or `reasoning.effort`.
diff --git a/.changeset/reasoning-option-mistral.md b/.changeset/reasoning-option-mistral.md
new file mode 100644
index 0000000000..a4fc441def
--- /dev/null
+++ b/.changeset/reasoning-option-mistral.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-mistral': minor
+---
+
+Add `chat({ reasoning })`: Mistral Small and Medium get `reasoning_effort`, and Magistral gets `prompt_mode: "reasoning"`.
diff --git a/.changeset/reasoning-option-ollama.md b/.changeset/reasoning-option-ollama.md
new file mode 100644
index 0000000000..c90a3eae0d
--- /dev/null
+++ b/.changeset/reasoning-option-ollama.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-ollama': minor
+---
+
+Breaking: set reasoning with `chat({ reasoning })`. `modelOptions.think` is removed. A model name that the package does not list gets the on/off toggle.
diff --git a/.changeset/reasoning-option-openai-base.md b/.changeset/reasoning-option-openai-base.md
new file mode 100644
index 0000000000..72f7b7e926
--- /dev/null
+++ b/.changeset/reasoning-option-openai-base.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/openai-base': minor
+---
+
+The Chat Completions and Responses base adapters take a reasoning type parameter and a protected `modelReasoning(model)` hook. When a subclass returns the model's reasoning data, the base sends `chat({ reasoning })` as `reasoning_effort` (Chat Completions) or `reasoning: { effort, summary }` (Responses). The Chat Completions base also gets `includeUsageInStream` and `requestHeaders` hooks.
diff --git a/.changeset/reasoning-option-openai.md b/.changeset/reasoning-option-openai.md
new file mode 100644
index 0000000000..1173446b2e
--- /dev/null
+++ b/.changeset/reasoning-option-openai.md
@@ -0,0 +1,7 @@
+---
+'@tanstack/ai-openai': minor
+---
+
+Breaking: set reasoning with `chat({ reasoning })`. `modelOptions.reasoning` and the `OpenAIReasoningOptions` types are removed; the adapter sends the level as `reasoning.effort` with a summary.
+
+`openaiCompatible` takes `compat` for a provider's request quirks (thinking format, developer role, `maxTokensField`, the DeepSeek `reasoning_content` replay, `store`, strict tools, session headers, and Anthropic cache markers), and each model entry takes `reasoning` (its level map) and its own `compat`.
diff --git a/.changeset/reasoning-option-opencode.md b/.changeset/reasoning-option-opencode.md
new file mode 100644
index 0000000000..4ff94d3f45
--- /dev/null
+++ b/.changeset/reasoning-option-opencode.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-opencode': minor
+---
+
+Add `chat({ reasoning })`: the adapter writes the model's reasoning options into the OpenCode server config.
diff --git a/.changeset/reasoning-option-openrouter.md b/.changeset/reasoning-option-openrouter.md
new file mode 100644
index 0000000000..20b6dfefcd
--- /dev/null
+++ b/.changeset/reasoning-option-openrouter.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-openrouter': minor
+---
+
+Breaking: set reasoning with `chat({ reasoning })`. `modelOptions.reasoning` and the `ReasoningOptions` type are removed. `off` goes out as `effort: "none"`. The Responses adapter also takes `budgetTokens`.
diff --git a/.changeset/reasoning-option-vercel-gateway.md b/.changeset/reasoning-option-vercel-gateway.md
new file mode 100644
index 0000000000..2cf6c1381f
--- /dev/null
+++ b/.changeset/reasoning-option-vercel-gateway.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-vercel-gateway': minor
+---
+
+Breaking: set reasoning with `chat({ reasoning })`. `reasoning` and `include_reasoning` leave `modelOptions`. Chat Completions gets AI Gateway's `reasoning` object, and Responses gets `reasoning.effort`.
diff --git a/packages/ai-models/vite.config.ts b/packages/ai-models/vite.config.ts
index 5f7506e7bb..6385a078d0 100644
--- a/packages/ai-models/vite.config.ts
+++ b/packages/ai-models/vite.config.ts
@@ -3,8 +3,10 @@ import { defineConfig, mergeConfig } from 'vitest/config'
 import { tanstackViteConfig } from '@tanstack/vite-config'
 import packageJson from './package.json'
 
-// One entry per provider file, so each one is its own subpath export.
-const providerEntries = readdirSync('./src/providers')
+// One entry per provider file, so each one is its own subpath export. The
+// folder is read next to this file, so tools that load the config from the
+// repo root (knip) find it too.
+const providerEntries = readdirSync(new URL('./src/providers', import.meta.url))
   .filter((file) => file.endsWith('.ts'))
   .map((file) => `./src/providers/${file}`)
 
diff --git a/packages/ai/tests/reasoning-types.test-d.ts b/packages/ai/tests/reasoning-types.test-d.ts
index 12aecd301f..ec6d62e4bd 100644
--- a/packages/ai/tests/reasoning-types.test-d.ts
+++ b/packages/ai/tests/reasoning-types.test-d.ts
@@ -42,10 +42,10 @@ chat({
 // @ts-expect-error `medium` is not one of this model's levels
 chat({ adapter: effortModel, messages, reasoning: 'medium' })
 
-// @ts-expect-error budgetTokens needs a budget-based model
 chat({
   adapter: effortModel,
   messages,
+  // @ts-expect-error budgetTokens needs a budget-based model
   reasoning: { level: 'low', budgetTokens: 1000 },
 })
 

From 7b612673191335d909c14865cc6a2312248f97fb Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 18:14:41 +0200
Subject: [PATCH 101/286] fix(ai): run the server tools of one model turn at
 the same time

chat() ran the server tools of a turn one after another, so a turn with several slow tools took the sum of their times. The docs already said they run in parallel.

Every call is still prepared in call order, then the server tools start together. onAfterToolCall fires as each tool finishes, and the results keep the call order. A tool that has not started when the run aborts gets the error result 'Operation aborted'.

chat({ toolExecution: 'sequential' }) and toolDefinition({ sequential: true }) keep the one-at-a-time order where tools depend on each other.

Fixes #1547
---
 .changeset/parallel-server-tools.md           |  10 +
 docs/advanced/middleware.md                   |  10 +
 docs/config.json                              |   6 +-
 docs/tools/tool-architecture.md               |   2 +
 docs/tools/tools.md                           |  44 ++++
 .../ai/src/activities/chat/agents/spawn.ts    |  33 +--
 packages/ai/src/activities/chat/index.ts      |   4 +
 .../src/activities/chat/tools/tool-calls.ts   |  82 ++++++-
 .../activities/chat/tools/tool-definition.ts  |   1 +
 packages/ai/src/types.ts                      |   9 +
 packages/ai/src/utilities/merge-streams.ts    |  34 +++
 packages/ai/tests/parallel-tools.test.ts      | 222 ++++++++++++++++++
 .../tools-test/parallel-server-timing.json    |  26 ++
 testing/e2e/src/lib/tools-test-tools.ts       |  27 +++
 .../tools-test/server-client-sequence.spec.ts |  34 +++
 15 files changed, 500 insertions(+), 44 deletions(-)
 create mode 100644 .changeset/parallel-server-tools.md
 create mode 100644 packages/ai/src/utilities/merge-streams.ts
 create mode 100644 packages/ai/tests/parallel-tools.test.ts
 create mode 100644 testing/e2e/fixtures/tools-test/parallel-server-timing.json

diff --git a/.changeset/parallel-server-tools.md b/.changeset/parallel-server-tools.md
new file mode 100644
index 0000000000..ad4ffec4b5
--- /dev/null
+++ b/.changeset/parallel-server-tools.md
@@ -0,0 +1,10 @@
+---
+'@tanstack/ai': minor
+---
+
+Run the server tools of one model turn at the same time. `chat()` used to run them one after another, so a turn with several slow tools took as long as all of them together.
+
+- Every call is still prepared in call order (argument parse, input schema check, approval check, `onBeforeToolCall`). Then the server tools start together.
+- `onAfterToolCall` fires for each tool when it finishes. The model still gets the results in the order of its calls.
+- A tool that has not started when the run aborts does not start. It gets the error result "Operation aborted".
+- Opt out per run with `chat({ toolExecution: 'sequential' })`, or per tool with `toolDefinition({ sequential: true })`. A turn that calls a `sequential` tool runs all of its tools one at a time.
diff --git a/docs/advanced/middleware.md b/docs/advanced/middleware.md
index f5a5a0ccfc..0c16cf232c 100644
--- a/docs/advanced/middleware.md
+++ b/docs/advanced/middleware.md
@@ -596,6 +596,16 @@ The `info` object provides:
 | `result` | `unknown` | Result (when `ok` is true) |
 | `error` | `unknown` | Error (when `ok` is false) |
 
+### Tool hook order in one turn
+
+When the model calls several server tools in one turn, the tools run at the same time:
+
+- `onBeforeToolCall` runs for each call in call order, before any tool starts.
+- `onAfterToolCall` runs for each tool when it finishes, so in finish order.
+- A tool that has not started when the run aborts does not run. `onAfterToolCall` gets `ok: false` with the error "Operation aborted".
+
+With `toolExecution: 'sequential'`, or a tool with `sequential: true` in the turn, each call finishes its `onBeforeToolCall`, its run, and its `onAfterToolCall` before the next call starts. See [Run tools one at a time](../tools/tools#run-tools-one-at-a-time).
+
 ### onUsage
 
 Called once per model iteration when the `RUN_FINISHED` chunk includes usage data. Receives the usage object directly.
diff --git a/docs/config.json b/docs/config.json
index aea1c76faa..786030f5cf 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -236,7 +236,7 @@
           "label": "Tools",
           "to": "tools/tools",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-08-21"
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "Server Tools",
@@ -289,7 +289,7 @@
           "label": "Tool Architecture",
           "to": "tools/tool-architecture",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-08-17"
+          "updatedAt": "2026-09-30"
         }
       ],
       "tab": "guides"
@@ -301,7 +301,7 @@
           "label": "Middleware",
           "to": "advanced/middleware",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-09-25"
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "Built-in Middleware",
diff --git a/docs/tools/tool-architecture.md b/docs/tools/tool-architecture.md
index a85306ade3..51c4fe66ef 100644
--- a/docs/tools/tool-architecture.md
+++ b/docs/tools/tool-architecture.md
@@ -403,6 +403,8 @@ LLM calls:
 All execute simultaneously, then LLM generates comparison.
 ```
 
+The server tools of one model turn start together, and the model gets their results in the order of its calls. To run them one at a time, see [Run tools one at a time](./tools#run-tools-one-at-a-time).
+
 ## Best Practices
 
 ### Tool Design
diff --git a/docs/tools/tools.md b/docs/tools/tools.md
index 68f0a59d02..7ab1fe31bb 100644
--- a/docs/tools/tools.md
+++ b/docs/tools/tools.md
@@ -397,6 +397,50 @@ function CartChat() {
 4. **Result is returned** - To the model as a tool result message
 5. **Model continues** - Uses the result to generate a response
 
+## Run tools one at a time
+
+When the model calls several server tools in one turn, they start at the same time, and the model gets the results in the order of its calls. Some tools depend on each other, for example a tool that writes a file and a tool that runs the tests. They must not overlap.
+
+Set `sequential: true` on such a tool. A turn that calls it runs all of its tools one at a time:
+
+```ts group=sequential-tools
+import { chat, toolDefinition } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+const writeFile = toolDefinition({
+  name: 'write_file',
+  description: 'Write a file',
+  inputSchema: z.object({ path: z.string(), content: z.string() }),
+}).server(async ({ path }) => ({ written: path }))
+
+const runTests = toolDefinition({
+  name: 'run_tests',
+  description: 'Run the test suite',
+  inputSchema: z.object({}),
+  sequential: true,
+}).server(async () => ({ passed: true }))
+
+const stream = chat({
+  adapter: openaiText('gpt-6.1-sol'),
+  messages: [{ role: 'user', content: 'Fix the bug, then run the tests.' }],
+  tools: [writeFile, runTests],
+})
+```
+
+To run every tool of every turn one at a time, set `toolExecution` on `chat()`:
+
+```ts group=sequential-tools
+const orderedStream = chat({
+  adapter: openaiText('gpt-6.1-sol'),
+  messages: [{ role: 'user', content: 'Fix the bug, then run the tests.' }],
+  tools: [writeFile, runTests],
+  toolExecution: 'sequential',
+})
+```
+
+Client tools do not change: the client runs them as their calls arrive.
+
 ## Progress Events and Runtime Context
 
 A server tool's `.server()` implementation receives a second argument, the `ToolExecutionContext` — `{ context, toolCallId, emitCustomEvent }`. Use `emitCustomEvent` to stream typed progress to the client while the tool runs, and `context` to read request-scoped dependencies (auth, DB clients, etc.):
diff --git a/packages/ai/src/activities/chat/agents/spawn.ts b/packages/ai/src/activities/chat/agents/spawn.ts
index 18e712007a..d2dd785cd3 100644
--- a/packages/ai/src/activities/chat/agents/spawn.ts
+++ b/packages/ai/src/activities/chat/agents/spawn.ts
@@ -9,6 +9,7 @@ import {
   tanstackMetadata,
   withTanstackMetadata,
 } from '../../../utilities/merge-metadata'
+import { mergeStreams } from '../../../utilities/merge-streams'
 import { INTERRUPT_BINDING_METADATA_KEY } from '../../../interrupt-resume'
 import { EMIT_STREAM_CHUNK, SUBAGENT_TOOL } from '../tools/tool-calls'
 import type { SubagentToolOutcome } from '../tools/tool-calls'
@@ -525,36 +526,6 @@ export async function* spawnAgentStream(
   }
 }
 
-async function* mergeAgentStreams(streams: Array<AsyncIterable<StreamChunk>>) {
-  const readers = streams.map((stream) => {
-    const iterator = stream[Symbol.asyncIterator]()
-    return {
-      iterator,
-      next: iterator.next(),
-    }
-  })
-
-  try {
-    while (readers.length > 0) {
-      const indexed = readers.map((reader, index) =>
-        reader.next.then((result) => ({ index, result, reader })),
-      )
-      const winner = await Promise.race(indexed)
-      if (winner.result.done) {
-        readers.splice(winner.index, 1)
-        continue
-      }
-      yield winner.result.value
-      winner.reader.next = winner.reader.iterator.next()
-    }
-  } finally {
-    // The reader stopped early. Close every child so its finally runs.
-    for (const reader of readers) {
-      void reader.iterator.return?.().catch(() => {})
-    }
-  }
-}
-
 /** True when a child in these chunks failed or stopped for outside input. */
 function stopsSequence(chunks: ReadonlyArray<StreamChunk>, id: string) {
   return chunks.some(
@@ -620,7 +591,7 @@ export async function* spawnNamedAgents(
       yield* onlyStream
       return
     }
-    yield* mergeAgentStreams(streams)
+    yield* mergeStreams(streams)
   } finally {
     group.controller.abort()
     group.dispose()
diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index a5bd865082..5b52331b0b 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -523,6 +523,8 @@ export interface TextActivityOptions<
   abortController?: TextOptions['abortController']
   /** Strategy for controlling the agent loop */
   agentLoopStrategy?: TextOptions['agentLoopStrategy']
+  /** How the server tools of one model turn run. Default `'parallel'`. */
+  toolExecution?: TextOptions['toolExecution']
   /**
    * Optional configuration for lazy-tool discovery (tools marked `lazy: true`).
    * Tunes how much of each lazy tool's description appears in the discovery
@@ -2202,6 +2204,7 @@ class TextEngine<
         cancelledToolCallIds: this.resumeCancelledToolCallIds,
         inputResponses: this.resumeInputResponses,
       },
+      this.params.toolExecution,
     )
 
     // Consume the async generator, yielding custom events and collecting the return value
@@ -2390,6 +2393,7 @@ class TextEngine<
         cancelledToolCallIds: this.resumeCancelledToolCallIds,
         inputResponses: this.resumeInputResponses,
       },
+      this.params.toolExecution,
     )
 
     // Consume the async generator, yielding custom events and collecting the return value
diff --git a/packages/ai/src/activities/chat/tools/tool-calls.ts b/packages/ai/src/activities/chat/tools/tool-calls.ts
index 4b24c60f35..2934128d8e 100644
--- a/packages/ai/src/activities/chat/tools/tool-calls.ts
+++ b/packages/ai/src/activities/chat/tools/tool-calls.ts
@@ -1,6 +1,7 @@
 import { normalizeToolResult } from '../../../utilities/tool-result'
 import { tanstackMetadata } from '../../../utilities/merge-metadata'
 import { isProviderExecutedToolCall } from '../../../utilities/provider-executed'
+import { mergeStreams } from '../../../utilities/merge-streams'
 import type { AdapterYieldChunk } from '../../../utilities/adapter-yield-chunk'
 import {
   StandardSchemaValidationError,
@@ -887,6 +888,10 @@ async function buildClientToolResult(
  * @param approvals - Map keyed by toolCallId (or `approval_${toolCallId}`) → ToolApprovalResolution
  * @param clientResults - Map of client-side execution results (toolCallId -> result)
  * @param createCustomEventChunk - Factory to create CustomEvent chunks (optional)
+ * @param toolExecution - `'parallel'` (default) prepares every call in call
+ *   order, then starts the server tools together. `'sequential'`, or a tool
+ *   with `sequential: true` in the batch, runs one call at a time. Results
+ *   come back in call order either way.
  */
 export async function* executeToolCalls<TContext = unknown>(
   toolCalls: Array<ToolCall>,
@@ -902,6 +907,7 @@ export async function* executeToolCalls<TContext = unknown>(
   userContext?: TContext,
   abortSignal?: AbortSignal,
   resumeState?: ToolResumeExecutionState,
+  toolExecution: 'parallel' | 'sequential' = 'parallel',
 ): AsyncGenerator<CustomEvent | StreamChunk, ExecuteToolCallsResult, void> {
   const results: Array<ToolResult> = []
   const needsApproval: Array<ApprovalRequest> = []
@@ -915,6 +921,56 @@ export async function* executeToolCalls<TContext = unknown>(
     toolMap.set(tool.name, tool)
   }
 
+  const runsInOrder =
+    toolExecution === 'sequential' ||
+    toolCalls.some((tc) => toolMap.get(tc.function.name)?.sequential)
+  // Parallel batches start their server tools here after every call is prepared.
+  const runs: Array<AsyncGenerator<CustomEvent | StreamChunk, void, void>> = []
+
+  // A tool that has not started when the run aborts never starts. It gets an
+  // error result, so every call of the batch still has a result.
+  async function* runServerTool(
+    toolCall: ToolCall,
+    tool: AnyTool,
+    toolName: string,
+    input: unknown,
+    context: ToolExecutionContext<TContext>,
+    pendingEvents: Array<CustomEvent | StreamChunk>,
+  ): AsyncGenerator<CustomEvent | StreamChunk, void, void> {
+    if (abortSignal?.aborted) {
+      results.push({
+        toolCallId: toolCall.id,
+        toolName,
+        result: { error: 'Operation aborted' },
+        input,
+        state: 'output-error',
+        duration: 0,
+      })
+      await middlewareHooks?.onAfterToolCall?.({
+        toolCall,
+        tool,
+        toolName,
+        toolCallId: toolCall.id,
+        ok: false,
+        duration: 0,
+        error: new Error('Operation aborted'),
+      })
+      return
+    }
+    yield* executeServerTool(
+      toolCall,
+      tool,
+      toolName,
+      input,
+      context,
+      pendingEvents,
+      results,
+      middlewareHooks,
+      inputRequired,
+      subagentInterrupts,
+    )
+  }
+
   // Batch gating: when any tool in the batch still needs an approval decision,
   // defer all execution so side effects don't happen before the user decides.
   const hasPendingApprovals = toolCalls.some((tc) => {
@@ -1148,18 +1204,16 @@ export async function* executeToolCalls<TContext = unknown>(
             input = decision.input
           }
 
-          yield* executeServerTool(
+          const run = runServerTool(
             toolCall,
             tool,
             toolName,
             input,
             context,
             pendingEvents,
-            results,
-            middlewareHooks,
-            inputRequired,
-            subagentInterrupts,
           )
+          if (runsInOrder) yield* run
+          else runs.push(run)
         } else {
           // User declined
           results.push({
@@ -1199,20 +1253,28 @@ export async function* executeToolCalls<TContext = unknown>(
       input = decision.input
     }
 
-    yield* executeServerTool(
+    const run = runServerTool(
       toolCall,
       tool,
       toolName,
       input,
       context,
       pendingEvents,
-      results,
-      middlewareHooks,
-      inputRequired,
-      subagentInterrupts,
     )
+    if (runsInOrder) yield* run
+    else runs.push(run)
   }
 
+  yield* mergeStreams(runs)
+
+  // Parallel tools finish in any order. The model gets the results in the
+  // order it made the calls.
+  const callOrder = new Map(toolCalls.map((tc, index) => [tc.id, index]))
+  results.sort(
+    (a, b) =>
+      (callOrder.get(a.toolCallId) ?? 0) - (callOrder.get(b.toolCallId) ?? 0),
+  )
+
   return {
     results,
     needsApproval,
diff --git a/packages/ai/src/activities/chat/tools/tool-definition.ts b/packages/ai/src/activities/chat/tools/tool-definition.ts
index 8c17ddfa63..7d1862fda4 100644
--- a/packages/ai/src/activities/chat/tools/tool-definition.ts
+++ b/packages/ai/src/activities/chat/tools/tool-definition.ts
@@ -223,6 +223,7 @@ export type ToolDefinitionConfig<
   inputSchema?: TInput
   outputSchema?: TOutput
   lazy?: boolean
+  sequential?: boolean
   metadata?: Record<string, unknown>
   execution?: 'task'
 } & ApprovalConfig<TNeedsApproval, TApprovalSchema>
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index 36bfaecb4c..00313a1de2 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -896,6 +896,9 @@ export interface Tool<
   /** If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools). */
   lazy?: boolean
 
+  /** If true, a batch of tool calls that contains this tool runs one call at a time, also when `toolExecution` is `'parallel'`. */
+  sequential?: boolean
+
   /** Additional metadata for adapters or custom extensions */
   metadata?: Record<string, any> | undefined
 }
@@ -1088,6 +1091,12 @@ export interface TextOptions<
    */
   systemPrompts?: Array<SystemPrompt>
   agentLoopStrategy?: AgentLoopStrategy
+  /**
+   * How the server tools of one model turn run. `'parallel'` (the default)
+   * starts them together, and `'sequential'` runs them one at a time. A tool
+   * with `sequential: true` makes its whole batch sequential.
+   */
+  toolExecution?: 'parallel' | 'sequential'
   /**
    * Optional configuration for lazy-tool discovery (tools marked `lazy: true`).
    * Tunes how much of each lazy tool's description appears in the discovery
diff --git a/packages/ai/src/utilities/merge-streams.ts b/packages/ai/src/utilities/merge-streams.ts
new file mode 100644
index 0000000000..885a368190
--- /dev/null
+++ b/packages/ai/src/utilities/merge-streams.ts
@@ -0,0 +1,34 @@
+/**
+ * Yield the items of several async streams as they arrive. If the reader
+ * stops early, every stream that is still open is closed, so its `finally`
+ * runs.
+ */
+export async function* mergeStreams<T>(streams: Array<AsyncIterable<T>>) {
+  const readers = streams.map((stream) => {
+    const iterator = stream[Symbol.asyncIterator]()
+    return {
+      iterator,
+      next: iterator.next(),
+    }
+  })
+
+  try {
+    while (readers.length > 0) {
+      const indexed = readers.map((reader, index) =>
+        reader.next.then((result) => ({ index, result, reader })),
+      )
+      const winner = await Promise.race(indexed)
+      if (winner.result.done) {
+        readers.splice(winner.index, 1)
+        continue
+      }
+      yield winner.result.value
+      winner.reader.next = winner.reader.iterator.next()
+    }
+  } finally {
+    // The reader stopped early. Close every stream so its finally runs.
+    for (const reader of readers) {
+      void reader.iterator.return?.().catch(() => {})
+    }
+  }
+}
diff --git a/packages/ai/tests/parallel-tools.test.ts b/packages/ai/tests/parallel-tools.test.ts
new file mode 100644
index 0000000000..200ac73a3f
--- /dev/null
+++ b/packages/ai/tests/parallel-tools.test.ts
@@ -0,0 +1,222 @@
+import { describe, expect, it } from 'vitest'
+import { chat } from '../src/activities/chat/index'
+import { executeToolCalls } from '../src/activities/chat/tools/tool-calls'
+import { EventType } from '../src/types'
+import { collectChunks, createMockAdapter, ev, serverTool } from './test-utils'
+import type { ChatMiddleware } from '../src/activities/chat/middleware/types'
+import type { StreamChunk, Tool, ToolCall } from '../src/types'
+
+/** A promise and the function that resolves it. */
+function gate() {
+  let open = () => {}
+  const opened = new Promise<void>((resolve) => {
+    open = resolve
+  })
+  return { opened, open }
+}
+
+/** `true` when `promise` settles within `ms`, else `false`. */
+function within(promise: Promise<void>, ms: number) {
+  return Promise.race([
+    promise.then(() => true),
+    new Promise<boolean>((resolve) => setTimeout(() => resolve(false), ms)),
+  ])
+}
+
+/** A tool that logs its start and end, and gives the event loop a turn between them. */
+function loggingTool(name: string, log: Array<string>, extra?: Partial<Tool>) {
+  return {
+    ...serverTool(name, async () => {
+      log.push(`${name} start`)
+      await new Promise((resolve) => setTimeout(resolve, 0))
+      log.push(`${name} end`)
+      return `${name} done`
+    }),
+    ...extra,
+  }
+}
+
+/** A model turn that calls `slow` and then `fast`, then a turn that answers. */
+function twoCallBatch() {
+  return createMockAdapter({
+    iterations: [
+      [
+        ev.runStarted(),
+        ev.toolStart('call-slow', 'slow'),
+        ev.toolArgs('call-slow', '{}'),
+        ev.toolEnd('call-slow'),
+        ev.toolStart('call-fast', 'fast'),
+        ev.toolArgs('call-fast', '{}'),
+        ev.toolEnd('call-fast'),
+        ev.runFinished('tool_calls'),
+      ],
+      [ev.runStarted(), ev.textContent('Done'), ev.runFinished('stop')],
+    ],
+  })
+}
+
+function runBatch(
+  tools: Array<Tool>,
+  options: {
+    toolExecution?: 'parallel' | 'sequential'
+    middleware?: Array<ChatMiddleware>
+  } = {},
+) {
+  const { adapter } = twoCallBatch()
+  return collectChunks(
+    chat({
+      adapter,
+      messages: [{ role: 'user', content: 'Go' }],
+      tools,
+      ...options,
+    }),
+  )
+}
+
+function resultOrder(chunks: Array<StreamChunk>) {
+  return chunks.flatMap((chunk) =>
+    chunk.type === EventType.TOOL_CALL_RESULT ? [chunk.toolCallId] : [],
+  )
+}
+
+function call(id: string, name: string): ToolCall {
+  return { id, type: 'function', function: { name, arguments: '{}' } }
+}
+
+async function drain(generator: ReturnType<typeof executeToolCalls>) {
+  let step = await generator.next()
+  while (!step.done) step = await generator.next()
+  return step.value.results.map((result) => [result.toolCallId, result.result])
+}
+
+describe('server tools of one batch', () => {
+  it('run at the same time, and the results keep the call order', async () => {
+    const fastStarted = gate()
+    let slowSawFast = false
+    const slow = serverTool('slow', async () => {
+      slowSawFast = await within(fastStarted.opened, 1_000)
+      return 'slow done'
+    })
+    const fast = serverTool('fast', () => {
+      fastStarted.open()
+      return 'fast done'
+    })
+
+    const chunks = await runBatch([slow, fast])
+
+    expect(slowSawFast).toBe(true)
+    expect(resultOrder(chunks)).toEqual(['call-slow', 'call-fast'])
+  })
+
+  it("run one at a time with toolExecution: 'sequential'", async () => {
+    const log: Array<string> = []
+
+    await runBatch([loggingTool('slow', log), loggingTool('fast', log)], {
+      toolExecution: 'sequential',
+    })
+
+    expect(log).toEqual(['slow start', 'slow end', 'fast start', 'fast end'])
+  })
+
+  it('run one at a time when a tool of the batch is sequential', async () => {
+    const log: Array<string> = []
+
+    await runBatch([
+      loggingTool('slow', log),
+      loggingTool('fast', log, { sequential: true }),
+    ])
+
+    expect(log).toEqual(['slow start', 'slow end', 'fast start', 'fast end'])
+  })
+
+  it('call onBeforeToolCall in call order and onAfterToolCall in finish order', async () => {
+    const hooks: Array<string> = []
+    const fastDone = gate()
+    const slow = serverTool('slow', async () => {
+      await fastDone.opened
+      return 'slow done'
+    })
+    const fast = serverTool('fast', () => 'fast done')
+    const order: ChatMiddleware = {
+      name: 'order',
+      onBeforeToolCall: (_ctx, hookCtx) => {
+        hooks.push(`before ${hookCtx.toolName}`)
+      },
+      onAfterToolCall: (_ctx, info) => {
+        hooks.push(`after ${info.toolName}`)
+        if (info.toolName === 'fast') fastDone.open()
+      },
+    }
+
+    await runBatch([slow, fast], { middleware: [order] })
+
+    expect(hooks).toEqual([
+      'before slow',
+      'before fast',
+      'after fast',
+      'after slow',
+    ])
+  })
+
+  it('do not start after the run aborts, and get "Operation aborted"', async () => {
+    const controller = new AbortController()
+    const ran: Array<string> = []
+    const tool = (name: string) =>
+      serverTool(name, () => {
+        ran.push(name)
+        return 'ok'
+      })
+
+    const results = await drain(
+      executeToolCalls(
+        [call('a', 'first'), call('b', 'second')],
+        [tool('first'), tool('second')],
+        new Map(),
+        new Map(),
+        undefined,
+        {
+          onBeforeToolCall: async (toolCall) => {
+            if (toolCall.id === 'b') controller.abort()
+          },
+        },
+        undefined,
+        controller.signal,
+      ),
+    )
+
+    expect(ran).toEqual([])
+    expect(results).toEqual([
+      ['a', { error: 'Operation aborted' }],
+      ['b', { error: 'Operation aborted' }],
+    ])
+  })
+
+  it('stop starting tools in sequential mode once the run aborts', async () => {
+    const controller = new AbortController()
+    const first = serverTool('first', () => {
+      controller.abort()
+      return 'ok'
+    })
+    const second = serverTool('second', () => 'ran')
+
+    const results = await drain(
+      executeToolCalls(
+        [call('a', 'first'), call('b', 'second')],
+        [first, second],
+        new Map(),
+        new Map(),
+        undefined,
+        undefined,
+        undefined,
+        controller.signal,
+        undefined,
+        'sequential',
+      ),
+    )
+
+    expect(results).toEqual([
+      ['a', 'ok'],
+      ['b', { error: 'Operation aborted' }],
+    ])
+  })
+})
diff --git a/testing/e2e/fixtures/tools-test/parallel-server-timing.json b/testing/e2e/fixtures/tools-test/parallel-server-timing.json
new file mode 100644
index 0000000000..cb1f8ffa09
--- /dev/null
+++ b/testing/e2e/fixtures/tools-test/parallel-server-timing.json
@@ -0,0 +1,26 @@
+{
+  "fixtures": [
+    {
+      "match": {
+        "userMessage": "[parallel-server-timing] run test",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "content": "Let me gather all the information at once.",
+        "toolCalls": [
+          { "name": "get_weather", "arguments": "{\"city\":\"NYC\"}" },
+          { "name": "get_time", "arguments": "{\"timezone\":\"EST\"}" }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[parallel-server-timing] run test",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Here is the weather and time for NYC."
+      }
+    }
+  ]
+}
diff --git a/testing/e2e/src/lib/tools-test-tools.ts b/testing/e2e/src/lib/tools-test-tools.ts
index b5d298dcaf..2ba7126ebe 100644
--- a/testing/e2e/src/lib/tools-test-tools.ts
+++ b/testing/e2e/src/lib/tools-test-tools.ts
@@ -117,6 +117,25 @@ export const serverTools = {
   }),
 }
 
+/** A server tool that waits 300 ms and returns when it started and ended. */
+function timedServerTool(name: string) {
+  return toolDefinition({
+    name,
+    description: `Timed ${name}`,
+    inputSchema: z.object({}).passthrough(),
+  }).server(async () => {
+    const startedAt = Date.now()
+    await new Promise((resolve) => setTimeout(resolve, 300))
+    return JSON.stringify({ startedAt, endedAt: Date.now() })
+  })
+}
+
+/** The calls of the `parallel-tools` fixture, as slow tools that report their timing. */
+export const timedServerTools = {
+  get_weather: timedServerTool('get_weather'),
+  get_time: timedServerTool('get_time'),
+}
+
 /**
  * Client-side tool definitions (tools that execute on the client)
  * These use .client() without an execute function - execution happens on client side
@@ -236,6 +255,11 @@ export const SCENARIO_LIST = [
     category: 'basic',
   },
   { id: 'parallel-tools', label: 'Parallel Tools', category: 'basic' },
+  {
+    id: 'parallel-server-timing',
+    label: 'Parallel Server Tool Timing',
+    category: 'basic',
+  },
   {
     id: 'lazy-tool-discovery',
     label: 'Lazy Tool Discovery',
@@ -384,6 +408,9 @@ export function getToolsForScenario(scenario: string) {
     case 'parallel-tools':
       return [serverTools.get_weather, serverTools.get_time]
 
+    case 'parallel-server-timing':
+      return [timedServerTools.get_weather, timedServerTools.get_time]
+
     // Race condition / event flow scenarios
     case 'sequential-client-tools':
       return [clientToolDefinitions.show_notification]
diff --git a/testing/e2e/tests/tools-test/server-client-sequence.spec.ts b/testing/e2e/tests/tools-test/server-client-sequence.spec.ts
index a7c64426cf..ed6d8c428a 100644
--- a/testing/e2e/tests/tools-test/server-client-sequence.spec.ts
+++ b/testing/e2e/tests/tools-test/server-client-sequence.spec.ts
@@ -211,6 +211,40 @@ test.describe('Server-Client Sequence E2E Tests', () => {
     expect(toolNames).toContain('get_time')
   })
 
+  test('parallel server tools run at the same time, results in call order', async ({
+    page,
+    testId,
+    aimockPort,
+  }) => {
+    await selectScenario(page, 'parallel-server-timing', testId, aimockPort)
+    await runTest(page)
+    await waitForTestComplete(page, 15000, 2)
+
+    const messages = await getMessages(page)
+    const results: Array<{ toolCallId: string; content: string }> = messages
+      .flatMap((message) => message.parts ?? [])
+      .filter((part) => part.type === 'tool-result')
+    const calls: Array<{ id: string; name: string }> = messages
+      .flatMap((message) => message.parts ?? [])
+      .filter((part) => part.type === 'tool-call')
+    const nameOf = (toolCallId: string) =>
+      calls.find((call) => call.id === toolCallId)?.name
+    const timing = (name: string) => {
+      const result = results.find((r) => nameOf(r.toolCallId) === name)
+      return JSON.parse(result?.content ?? '{}')
+    }
+
+    // Each tool waits 300 ms. Run one after another, they cannot overlap.
+    const weather = timing('get_weather')
+    const time = timing('get_time')
+    expect(weather.startedAt).toBeLessThan(time.endedAt)
+    expect(time.startedAt).toBeLessThan(weather.endedAt)
+    expect(results.map((result) => nameOf(result.toolCallId))).toEqual([
+      'get_weather',
+      'get_time',
+    ])
+  })
+
   test('single server tool completes', async ({ page, testId, aimockPort }) => {
     await selectScenario(page, 'server-tool-single', testId, aimockPort)
     await runTest(page)

From bbe77969c024cbff17096abd1f4cc529660728d2 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 18:49:47 +0200
Subject: [PATCH 102/286] fix(ai, ai-anthropic): send redacted thinking and
 tool errors back to Claude

The Anthropic adapter dropped a redacted_thinking block when it streamed in, so the next request did not send it back, and Claude can refuse a turn whose thinking blocks changed. A failed tool result also went out without is_error.

A redacted block now becomes a thinking part with redacted: true, an empty content, and its data in signature. The flag goes through the stream, the engine, the stream processor, the UI and wire converters, and interrupt snapshots, and the adapter sends it back as { type: 'redacted_thinking', data }. A tool message with error sends tool_result.is_error: true.
---
 .changeset/anthropic-thinking-replay.md       |  10 +
 docs/chat/thinking-content.md                 |   3 +
 docs/config.json                              |   2 +-
 packages/ai-anthropic/src/adapters/text.ts    |  31 +++
 .../tests/thinking-replay.test.ts             | 226 ++++++++++++++++
 packages/ai/src/activities/chat/index.ts      |  11 +-
 packages/ai/src/activities/chat/messages.ts   |  13 +-
 .../chat/stream/message-updaters.ts           |   3 +
 .../src/activities/chat/stream/processor.ts   |   8 +
 .../ai/src/activities/chat/stream/types.ts    |   2 +
 packages/ai/src/types.ts                      |  15 +-
 .../ai/src/utilities/adapter-yield-chunk.ts   |   2 +
 packages/ai/src/utilities/ag-ui-wire.ts       |   3 +
 .../src/utilities/normalize-stream-chunk.ts   |   1 +
 .../utilities/reasoning-encrypted-value.ts    |  10 +-
 packages/ai/tests/redacted-thinking.test.ts   |  68 +++++
 testing/e2e/src/routeTree.gen.ts              |  22 ++
 .../api.anthropic-redacted-thinking-wire.ts   | 241 ++++++++++++++++++
 .../anthropic-redacted-thinking-wire.spec.ts  |  40 +++
 19 files changed, 702 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/anthropic-thinking-replay.md
 create mode 100644 packages/ai-anthropic/tests/thinking-replay.test.ts
 create mode 100644 packages/ai/tests/redacted-thinking.test.ts
 create mode 100644 testing/e2e/src/routes/api.anthropic-redacted-thinking-wire.ts
 create mode 100644 testing/e2e/tests/anthropic-redacted-thinking-wire.spec.ts

diff --git a/.changeset/anthropic-thinking-replay.md b/.changeset/anthropic-thinking-replay.md
new file mode 100644
index 0000000000..495784e096
--- /dev/null
+++ b/.changeset/anthropic-thinking-replay.md
@@ -0,0 +1,10 @@
+---
+'@tanstack/ai': patch
+'@tanstack/ai-anthropic': patch
+---
+
+Send Claude's thinking and tool errors back the way Claude sent them.
+
+- A tool message with `error` now sends `tool_result.is_error: true`, so Claude sees that the tool failed.
+- A `redacted_thinking` block is no longer dropped. It becomes a thinking part with `redacted: true`, an empty `content`, and the encrypted data in `signature`. The flag survives the stream, the UI messages, the wire, and stored threads, and the next request sends the block back as `{ type: 'redacted_thinking', data }`.
+- `ThinkingPart` and `ModelMessage['thinking']` have the new optional `redacted` field.
diff --git a/docs/chat/thinking-content.md b/docs/chat/thinking-content.md
index b610f08b8e..b5af832a01 100644
--- a/docs/chat/thinking-content.md
+++ b/docs/chat/thinking-content.md
@@ -28,11 +28,14 @@ interface ThinkingPart {
   content: string;
   stepId?: string;
   signature?: string;
+  redacted?: boolean;
 }
 ```
 
 The `ThinkingPart` appears in `UIMessage.parts` alongside `TextPart` and `ToolCallPart` entries. As reasoning tokens arrive, its `content` accumulates token by token.
 
+Claude can also send a redacted thinking block. It is encrypted, so it has no text. It arrives as a `ThinkingPart` with `redacted: true`, an empty `content`, and the encrypted data in `signature`. Keep the part in your stored messages: the next request sends it back to Claude unchanged. In a UI, show a short placeholder such as "Thinking hidden" instead of the empty text.
+
 ## Enabling Thinking
 
 How you enable thinking depends on the provider.
diff --git a/docs/config.json b/docs/config.json
index aea1c76faa..06fdddb605 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -177,7 +177,7 @@
           "label": "Thinking & Reasoning",
           "to": "chat/thinking-content",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-08-21"
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "Message Queue",
diff --git a/packages/ai-anthropic/src/adapters/text.ts b/packages/ai-anthropic/src/adapters/text.ts
index b84a7a65c4..7beef02269 100644
--- a/packages/ai-anthropic/src/adapters/text.ts
+++ b/packages/ai-anthropic/src/adapters/text.ts
@@ -824,6 +824,7 @@ export class AnthropicTextAdapter<
                 : typeof toolContent === 'string'
                   ? toolContent
                   : '',
+              ...(message.error !== undefined && { is_error: true }),
             },
           ],
         })
@@ -952,6 +953,13 @@ export class AnthropicTextAdapter<
 
     for (const thinking of thinkingParts) {
       if (!thinking.signature) continue
+      if (thinking.redacted) {
+        contentBlocks.push({
+          type: 'redacted_thinking',
+          data: thinking.signature,
+        })
+        continue
+      }
       const block: ThinkingBlockParam = {
         type: 'thinking',
         thinking: thinking.content,
@@ -1214,6 +1222,29 @@ export class AnthropicTextAdapter<
               timestamp: Date.now(),
               stepType: 'thinking',
             }
+          } else if (event.content_block.type === 'redacted_thinking') {
+            // Encrypted thinking: no text, and its data must go back to
+            // Anthropic unchanged. It travels as the thinking step's signature.
+            const redactedStepId = genId()
+            yield {
+              type: EventType.STEP_STARTED,
+              stepName: redactedStepId,
+              stepId: redactedStepId,
+              model,
+              timestamp: Date.now(),
+              stepType: 'thinking',
+            }
+            yield {
+              type: EventType.STEP_FINISHED,
+              stepName: redactedStepId,
+              stepId: redactedStepId,
+              model,
+              timestamp: Date.now(),
+              delta: '',
+              content: '',
+              signature: event.content_block.data,
+              redacted: true,
+            }
           }
         } else if (event.type === 'content_block_delta') {
           if (event.delta.type === 'text_delta') {
diff --git a/packages/ai-anthropic/tests/thinking-replay.test.ts b/packages/ai-anthropic/tests/thinking-replay.test.ts
new file mode 100644
index 0000000000..5520f567ec
--- /dev/null
+++ b/packages/ai-anthropic/tests/thinking-replay.test.ts
@@ -0,0 +1,226 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { chat, StreamProcessor } from '@tanstack/ai'
+import { z } from 'zod'
+import { AnthropicTextAdapter } from '../src/adapters/text'
+import type { ModelMessage, Tool } from '@tanstack/ai'
+
+const mocks = vi.hoisted(() => {
+  const betaMessagesCreate = vi.fn()
+  const client = {
+    beta: { messages: { create: betaMessagesCreate } },
+    messages: { create: vi.fn() },
+  }
+  return { betaMessagesCreate, client }
+})
+
+vi.mock('@anthropic-ai/sdk', () => {
+  class MockAnthropic {
+    beta = mocks.client.beta
+    messages = mocks.client.messages
+    constructor(_: { apiKey: string }) {}
+  }
+  return { default: MockAnthropic }
+})
+
+type Block = { type: string } & Record<string, unknown>
+
+const adapter = () =>
+  new AnthropicTextAdapter({ apiKey: 'test-key' }, 'claude-opus-4-1')
+
+const weather: Tool = {
+  name: 'lookup_weather',
+  description: 'Return the weather for a city',
+  inputSchema: z.object({ location: z.string() }),
+  execute: () => 'sunny',
+}
+
+/** A stream of raw Anthropic events. */
+function stream(events: Array<Record<string, unknown>>) {
+  return (async function* () {
+    for (const event of events) yield event
+  })()
+}
+
+const redactedBlock = [
+  {
+    type: 'content_block_start',
+    index: 0,
+    content_block: { type: 'redacted_thinking', data: 'opaque-1' },
+  },
+  { type: 'content_block_stop', index: 0 },
+]
+
+function textEvents(index: number, text: string) {
+  return [
+    {
+      type: 'content_block_start',
+      index,
+      content_block: { type: 'text', text: '' },
+    },
+    {
+      type: 'content_block_delta',
+      index,
+      delta: { type: 'text_delta', text },
+    },
+    { type: 'content_block_stop', index },
+  ]
+}
+
+function end(stopReason: string) {
+  return [
+    {
+      type: 'message_delta',
+      delta: { stop_reason: stopReason },
+      usage: { output_tokens: 5 },
+    },
+    { type: 'message_stop' },
+  ]
+}
+
+/** The content blocks of the last assistant message in a request. */
+function assistantBlocks(call: number) {
+  const [payload] = mocks.betaMessagesCreate.mock.calls[call]!
+  const messages: Array<{ role: string; content: unknown }> = payload.messages
+  const assistant = messages.filter((m) => m.role === 'assistant').at(-1)
+  return Array.isArray(assistant?.content)
+    ? (assistant.content as Array<Block>)
+    : []
+}
+
+async function drain(iterable: AsyncIterable<unknown>) {
+  for await (const _ of iterable) {
+    // consume
+  }
+}
+
+describe('Anthropic replay', () => {
+  beforeEach(() => {
+    mocks.betaMessagesCreate.mockReset()
+  })
+
+  it('marks a failed tool result with is_error', async () => {
+    mocks.betaMessagesCreate.mockResolvedValueOnce(
+      stream([...textEvents(0, 'Sorry.'), ...end('end_turn')]),
+    )
+    const messages: Array<ModelMessage> = [
+      { role: 'user', content: 'Weather in Atlantis?' },
+      {
+        role: 'assistant',
+        content: null,
+        toolCalls: [
+          {
+            id: 'call-1',
+            type: 'function',
+            function: {
+              name: 'lookup_weather',
+              arguments: '{"location":"Atlantis"}',
+            },
+          },
+        ],
+      },
+      {
+        role: 'tool',
+        toolCallId: 'call-1',
+        content: '{"error":"City not found"}',
+        error: 'City not found',
+      },
+    ]
+
+    await drain(chat({ adapter: adapter(), messages }))
+
+    const [payload] = mocks.betaMessagesCreate.mock.calls[0]!
+    const blocks: Array<Block> = payload.messages.flatMap(
+      (m: { content: unknown }) => (Array.isArray(m.content) ? m.content : []),
+    )
+    expect(blocks.find((b) => b.type === 'tool_result')).toMatchObject({
+      tool_use_id: 'call-1',
+      is_error: true,
+    })
+  })
+
+  it('sends a redacted thinking block back in the same run', async () => {
+    mocks.betaMessagesCreate
+      .mockResolvedValueOnce(
+        stream([
+          ...redactedBlock,
+          {
+            type: 'content_block_start',
+            index: 1,
+            content_block: {
+              type: 'tool_use',
+              id: 'call-1',
+              name: 'lookup_weather',
+              input: {},
+            },
+          },
+          {
+            type: 'content_block_delta',
+            index: 1,
+            delta: {
+              type: 'input_json_delta',
+              partial_json: '{"location":"Berlin"}',
+            },
+          },
+          { type: 'content_block_stop', index: 1 },
+          ...end('tool_use'),
+        ]),
+      )
+      .mockResolvedValueOnce(
+        stream([...textEvents(0, 'It is sunny.'), ...end('end_turn')]),
+      )
+
+    await drain(
+      chat({
+        adapter: adapter(),
+        messages: [{ role: 'user', content: 'Weather in Berlin?' }],
+        tools: [weather],
+      }),
+    )
+
+    expect(mocks.betaMessagesCreate).toHaveBeenCalledTimes(2)
+    expect(assistantBlocks(1).map((b) => b.type)).toEqual([
+      'redacted_thinking',
+      'tool_use',
+    ])
+    expect(assistantBlocks(1)[0]).toEqual({
+      type: 'redacted_thinking',
+      data: 'opaque-1',
+    })
+  })
+
+  it('sends a redacted thinking block back on the next turn', async () => {
+    mocks.betaMessagesCreate
+      .mockResolvedValueOnce(
+        stream([
+          ...redactedBlock,
+          ...textEvents(1, 'Hello.'),
+          ...end('end_turn'),
+        ]),
+      )
+      .mockResolvedValueOnce(
+        stream([...textEvents(0, 'Again.'), ...end('end_turn')]),
+      )
+    const first: Array<ModelMessage> = [{ role: 'user', content: 'Hi' }]
+    const processor = new StreamProcessor()
+    processor.addUserMessage('Hi')
+    for await (const chunk of chat({ adapter: adapter(), messages: first })) {
+      processor.processChunk(chunk)
+    }
+    processor.finalizeStream()
+
+    await drain(
+      chat({
+        adapter: adapter(),
+        messages: [
+          ...processor.getMessages(),
+          { role: 'user', content: 'Say it again.' },
+        ],
+      }),
+    )
+
+    expect(assistantBlocks(1)).toEqual([
+      { type: 'redacted_thinking', data: 'opaque-1' },
+      { type: 'text', text: 'Hello.' },
+    ])
+  })
+})
diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index a5bd865082..d585a06112 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -853,8 +853,7 @@ class TextEngine<
   private currentMessageCreatedAt: Date | null = null
   private streamIdentityCaptured = false
   private accumulatedContent = ''
-  private accumulatedThinking: Array<{ content: string; signature?: string }> =
-    []
+  private accumulatedThinking: NonNullable<ModelMessage['thinking']> = []
   /**
    * Arrival order of this iteration's thinking steps, text and tool calls.
    * A ModelMessage keeps `thinking` apart from `content`/`toolCalls`, so a
@@ -866,6 +865,7 @@ class TextEngine<
   private turnParts: Array<TurnPart> | null = []
   private currentThinkingContent = ''
   private currentThinkingSignature = ''
+  private currentThinkingRedacted = false
   private eventOptions?: Record<string, unknown> | undefined
   private eventToolNames?: Array<string>
   private finishedEvent: RunFinishedEvent | null = null
@@ -1524,6 +1524,7 @@ class TextEngine<
     this.turnParts = []
     this.currentThinkingContent = ''
     this.currentThinkingSignature = ''
+    this.currentThinkingRedacted = false
 
     this.finishedEvent = null
     this.streamedToolErrorResults.clear()
@@ -1992,6 +1993,7 @@ class TextEngine<
         ...(this.currentThinkingSignature && {
           signature: this.currentThinkingSignature,
         }),
+        ...(this.currentThinkingRedacted && { redacted: true }),
       })
       if (this.turnParts) {
         const placeholder = [...this.turnParts]
@@ -2009,6 +2011,7 @@ class TextEngine<
       }
       this.currentThinkingContent = ''
       this.currentThinkingSignature = ''
+      this.currentThinkingRedacted = false
     }
   }
 
@@ -2036,6 +2039,7 @@ class TextEngine<
     if (typeof chunk.signature === 'string' && chunk.signature !== '') {
       this.noteThinkingStepPosition()
       this.currentThinkingSignature = chunk.signature
+      this.currentThinkingRedacted = chunk.redacted === true
     }
   }
 
@@ -2065,6 +2069,7 @@ class TextEngine<
     }
     this.noteThinkingStepPosition()
     this.currentThinkingSignature = chunk.encryptedValue
+    this.currentThinkingRedacted = tanstackMetadata(chunk)?.redacted === true
   }
 
   /**
@@ -2579,7 +2584,7 @@ class TextEngine<
       ),
     )
     type Segment = {
-      thinking: Array<{ content: string; signature?: string }>
+      thinking: NonNullable<ModelMessage['thinking']>
       text: string
       callIds: Array<string>
     }
diff --git a/packages/ai/src/activities/chat/messages.ts b/packages/ai/src/activities/chat/messages.ts
index 4a4bac88e1..5022867615 100644
--- a/packages/ai/src/activities/chat/messages.ts
+++ b/packages/ai/src/activities/chat/messages.ts
@@ -72,6 +72,11 @@ function encryptedValueFrom(value: object): string | undefined {
   return nonEmptyString(tanstackMetadata(value)?.signature)
 }
 
+/** `{ redacted: true }` when a reasoning message carries a redacted block. */
+function redactedFrom(value: object) {
+  return tanstackMetadata(value)?.redacted === true ? { redacted: true } : {}
+}
+
 function toolCallFromWire(toolCall: ToolCall, bag: unknown): ToolCall {
   const fromBag =
     bag != null && typeof bag === 'object' && !Array.isArray(bag)
@@ -246,7 +251,7 @@ function convertOwnMessages(
   }
 
   const modelMessages: Array<ModelMessage> = []
-  let pendingThinking: Array<{ content: string; signature?: string }> = []
+  let pendingThinking: NonNullable<ModelMessage['thinking']> = []
   for (const msg of messages) {
     if ('parts' in msg) {
       modelMessages.push(...uiMessageToModelMessages(msg))
@@ -273,6 +278,7 @@ function convertOwnMessages(
         pendingThinking.push({
           content: typeof content === 'string' ? content : '',
           ...(signature !== undefined ? { signature } : {}),
+          ...redactedFrom(msg),
         })
       }
       continue
@@ -663,7 +669,7 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
   // shared UI id on each one so persistence can retain the original identity.
   const messageList: Array<ModelMessage> = []
   let current = createSegment()
-  let pendingThinking: Array<{ content: string; signature?: string }> = []
+  let pendingThinking: NonNullable<ModelMessage['thinking']> = []
 
   // Track emitted tool result IDs to avoid duplicates.
   // A tool call can have BOTH an explicit tool-result part AND an output
@@ -764,6 +770,7 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
           pendingThinking.push({
             content: part.content,
             ...(part.signature && { signature: part.signature }),
+            ...(part.redacted && { redacted: true }),
           })
         }
         break
@@ -898,6 +905,7 @@ export function modelMessageToUIMessage(
         type: 'thinking',
         content: thinking.content,
         ...(thinking.signature && { signature: thinking.signature }),
+        ...(thinking.redacted && { redacted: true }),
       })
     }
   }
@@ -1121,6 +1129,7 @@ export function aguiSnapshotMessageToUIMessage(
                   type: 'thinking' as const,
                   content,
                   ...(signature !== undefined ? { signature } : {}),
+                  ...redactedFrom(message),
                 },
               ]
             : [],
diff --git a/packages/ai/src/activities/chat/stream/message-updaters.ts b/packages/ai/src/activities/chat/stream/message-updaters.ts
index 0b999e556c..1e20eb4066 100644
--- a/packages/ai/src/activities/chat/stream/message-updaters.ts
+++ b/packages/ai/src/activities/chat/stream/message-updaters.ts
@@ -451,6 +451,7 @@ export function updateThinkingPart(
   stepId: string,
   content: string,
   signature?: string,
+  redacted?: boolean,
 ): Array<UIMessage> {
   return messages.map((msg) => {
     if (msg.id !== messageId) {
@@ -483,12 +484,14 @@ export function updateThinkingPart(
     // not carry one; losing it would strip the provider's encrypted reasoning
     // from a message that is about to be sent back.
     const nextSignature = signature ?? adopted?.signature
+    const nextRedacted = redacted === true || adopted?.redacted === true
 
     const thinkingPart: ThinkingPart = {
       type: 'thinking',
       content,
       stepId,
       ...(nextSignature && { signature: nextSignature }),
+      ...(nextRedacted && { redacted: true }),
     }
 
     if (thinkingPartIndex >= 0) {
diff --git a/packages/ai/src/activities/chat/stream/processor.ts b/packages/ai/src/activities/chat/stream/processor.ts
index 04e72128ea..b7fbee32e0 100644
--- a/packages/ai/src/activities/chat/stream/processor.ts
+++ b/packages/ai/src/activities/chat/stream/processor.ts
@@ -786,6 +786,7 @@ export class StreamProcessor {
       hasSeenReasoningEvents: false,
       thinkingSteps: new Map(),
       thinkingStepSignatures: new Map(),
+      thinkingStepRedacted: new Set(),
       thinkingStepOrder: [],
       currentThinkingStepId: null,
       toolCalls: new Map(),
@@ -2356,12 +2357,14 @@ export class StreamProcessor {
     if (thinking === undefined) return
 
     state.thinkingStepSignatures.set(stepId, signature)
+    if (extra.redacted === true) state.thinkingStepRedacted.add(stepId)
     this.messages = updateThinkingPart(
       this.messages,
       messageId,
       stepId,
       thinking,
       signature,
+      state.thinkingStepRedacted.has(stepId),
     )
     this.emitMessagesChange()
   }
@@ -2400,6 +2403,7 @@ export class StreamProcessor {
       stepId,
       nextThinking,
       state.thinkingStepSignatures.get(stepId),
+      state.thinkingStepRedacted.has(stepId),
     )
     this.emitMessagesChange()
 
@@ -2427,6 +2431,9 @@ export class StreamProcessor {
     )
     const stepId = state.currentThinkingStepId ?? chunk.entityId
     state.thinkingStepSignatures.set(stepId, encryptedValue)
+    if (tanstackMetadata(chunk)?.redacted === true) {
+      state.thinkingStepRedacted.add(stepId)
+    }
     const content = state.thinkingSteps.get(stepId) ?? ''
     if (!state.thinkingSteps.has(stepId)) {
       state.thinkingSteps.set(stepId, content)
@@ -2438,6 +2445,7 @@ export class StreamProcessor {
       stepId,
       content,
       encryptedValue,
+      state.thinkingStepRedacted.has(stepId),
     )
     this.emitMessagesChange()
   }
diff --git a/packages/ai/src/activities/chat/stream/types.ts b/packages/ai/src/activities/chat/stream/types.ts
index cbdf333c3b..e4fb7f979e 100644
--- a/packages/ai/src/activities/chat/stream/types.ts
+++ b/packages/ai/src/activities/chat/stream/types.ts
@@ -64,6 +64,8 @@ export interface MessageStreamState {
   hasSeenReasoningEvents: boolean
   thinkingSteps: Map<string, string>
   thinkingStepSignatures: Map<string, string>
+  /** Thinking steps whose signature is a redacted block's data. */
+  thinkingStepRedacted: Set<string>
   thinkingStepOrder: Array<string>
   currentThinkingStepId: string | null
   toolCalls: Map<string, InternalToolCallState>
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index 36bfaecb4c..466152428c 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -381,7 +381,12 @@ export interface ModelMessage<
   name?: string
   toolCalls?: Array<ToolCall>
   toolCallId?: string
-  thinking?: Array<{ content: string; signature?: string }>
+  /**
+   * Signed thinking to send back to the provider. `redacted: true` marks a
+   * block the provider encrypted: `content` is empty and `signature` holds its
+   * opaque data.
+   */
+  thinking?: Array<{ content: string; signature?: string; redacted?: boolean }>
   /** Error reported by an AG-UI tool message. */
   error?: string
   /** Optional AG-UI message metadata. TanStack-owned fields live under `tanstack`. */
@@ -466,6 +471,12 @@ export interface ThinkingPart {
   content: string
   stepId?: string
   signature?: string
+  /**
+   * The provider encrypted this thinking block (Anthropic `redacted_thinking`).
+   * `content` is empty, and `signature` holds the opaque data that goes back
+   * to the provider unchanged.
+   */
+  redacted?: boolean
 }
 
 /**
@@ -584,6 +595,8 @@ export interface TanStackMessageMetadata {
   subagent?: SubagentWireInfo
   /** Thinking signature for a `role: 'reasoning'` fan-out message. */
   signature?: string
+  /** Set with `signature` when the provider redacted the thinking block. */
+  redacted?: boolean
   /** Per-tool-call provider metadata keyed by tool call id (e.g. Gemini thoughtSignature). */
   toolCallMetadata?: Record<string, unknown>
   toolResult?: {
diff --git a/packages/ai/src/utilities/adapter-yield-chunk.ts b/packages/ai/src/utilities/adapter-yield-chunk.ts
index d733c86984..7b4c752730 100644
--- a/packages/ai/src/utilities/adapter-yield-chunk.ts
+++ b/packages/ai/src/utilities/adapter-yield-chunk.ts
@@ -24,6 +24,8 @@ type AdapterExtras = {
   stepType?: string
   delta?: string | ReadonlyArray<unknown>
   signature?: string
+  /** With `signature`: the provider redacted this thinking block. */
+  redacted?: boolean
   error?: { message: string; code?: string }
   'tanstack:interruptErrors'?: ReadonlyArray<InterruptSubmissionError>
   threadId?: string
diff --git a/packages/ai/src/utilities/ag-ui-wire.ts b/packages/ai/src/utilities/ag-ui-wire.ts
index da2aac2bcc..24f8a921f5 100644
--- a/packages/ai/src/utilities/ag-ui-wire.ts
+++ b/packages/ai/src/utilities/ag-ui-wire.ts
@@ -225,6 +225,9 @@ export function uiMessagesToWire(
         if (part.signature) {
           reasoning.encryptedValue = part.signature
         }
+        if (part.redacted) {
+          reasoning.metadata = { tanstack: { redacted: true } }
+        }
         wire.push(reasoning)
       }
 
diff --git a/packages/ai/src/utilities/normalize-stream-chunk.ts b/packages/ai/src/utilities/normalize-stream-chunk.ts
index a706252269..34b8b58542 100644
--- a/packages/ai/src/utilities/normalize-stream-chunk.ts
+++ b/packages/ai/src/utilities/normalize-stream-chunk.ts
@@ -41,6 +41,7 @@ function encryptedValueExtras(chunk: AdapterYieldChunk): Array<StreamChunk> {
           entityId,
           encryptedValue: chunk.signature,
           timestamp,
+          redacted: chunk.redacted === true,
         }),
       )
     }
diff --git a/packages/ai/src/utilities/reasoning-encrypted-value.ts b/packages/ai/src/utilities/reasoning-encrypted-value.ts
index 1236a30234..919e50dad8 100644
--- a/packages/ai/src/utilities/reasoning-encrypted-value.ts
+++ b/packages/ai/src/utilities/reasoning-encrypted-value.ts
@@ -1,18 +1,24 @@
 import { EventType } from '../types'
+import { withTanstackMetadata } from './merge-metadata'
 import type { ReasoningEncryptedValueEvent } from '../types'
 
-/** Spec event that carries a provider thinking / tool-call signature blob. */
+/**
+ * Spec event that carries a provider thinking / tool-call signature blob.
+ * `redacted: true` marks a redacted thinking block, in `metadata.tanstack`.
+ */
 export function reasoningEncryptedValue(opts: {
   subtype: 'message' | 'tool-call'
   entityId: string
   encryptedValue: string
   timestamp?: number
+  redacted?: boolean
 }): ReasoningEncryptedValueEvent {
-  return {
+  const event: ReasoningEncryptedValueEvent = {
     type: EventType.REASONING_ENCRYPTED_VALUE,
     subtype: opts.subtype,
     entityId: opts.entityId,
     encryptedValue: opts.encryptedValue,
     ...(opts.timestamp !== undefined ? { timestamp: opts.timestamp } : {}),
   }
+  return opts.redacted ? withTanstackMetadata(event, { redacted: true }) : event
 }
diff --git a/packages/ai/tests/redacted-thinking.test.ts b/packages/ai/tests/redacted-thinking.test.ts
new file mode 100644
index 0000000000..99a57ab967
--- /dev/null
+++ b/packages/ai/tests/redacted-thinking.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest'
+import {
+  aguiSnapshotMessageToUIMessage,
+  convertMessagesToModelMessages,
+  modelMessagesToUIMessages,
+} from '../src/activities/chat/messages'
+import { uiMessagesToWire } from '../src/utilities/ag-ui-wire'
+import { chatParamsFromRequestBody } from '../src/utilities/chat-params'
+import type { ModelMessage } from '../src/types'
+
+const stored: Array<ModelMessage> = [
+  { role: 'user', content: 'Hi' },
+  {
+    role: 'assistant',
+    content: 'Hello.',
+    thinking: [
+      { content: '', signature: 'opaque-1', redacted: true },
+      { content: 'I greet back.', signature: 'sig-2' },
+    ],
+  },
+]
+
+function thinkingOf(messages: Array<ModelMessage>) {
+  return messages.find((message) => message.role === 'assistant')?.thinking
+}
+
+describe('redacted thinking', () => {
+  it('survives a stored thread that is loaded into the UI and sent back', () => {
+    const ui = modelMessagesToUIMessages(stored)
+
+    expect(thinkingOf(convertMessagesToModelMessages(ui))).toEqual([
+      { content: '', signature: 'opaque-1', redacted: true },
+      { content: 'I greet back.', signature: 'sig-2' },
+    ])
+  })
+
+  it('survives the wire from the client to the server', async () => {
+    const wire = uiMessagesToWire(modelMessagesToUIMessages(stored))
+    // `JSON.parse(JSON.stringify(...))` stands in for the HTTP hop.
+    const params = await chatParamsFromRequestBody({
+      threadId: 'thread-1',
+      runId: 'run-1',
+      messages: JSON.parse(JSON.stringify(wire)),
+      tools: [],
+      context: [],
+    })
+
+    expect(thinkingOf(convertMessagesToModelMessages(params.messages))).toEqual(
+      [
+        { content: '', signature: 'opaque-1', redacted: true },
+        { content: 'I greet back.', signature: 'sig-2' },
+      ],
+    )
+  })
+
+  it('survives an interrupt snapshot that the client loads', () => {
+    const wire = uiMessagesToWire(modelMessagesToUIMessages(stored))
+
+    const parts = wire
+      .filter((message) => message.role === 'reasoning')
+      .flatMap((message) => aguiSnapshotMessageToUIMessage(message).parts)
+
+    expect(parts).toEqual([
+      { type: 'thinking', content: '', signature: 'opaque-1', redacted: true },
+      { type: 'thinking', content: 'I greet back.', signature: 'sig-2' },
+    ])
+  })
+})
diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index 013e1601a1..439b88d192 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -123,6 +123,7 @@ import { Route as ApiArktypeToolWireRouteImport } from './routes/api.arktype-too
 import { Route as ApiAnthropicThinkingOrderWireRouteImport } from './routes/api.anthropic-thinking-order-wire'
 import { Route as ApiAnthropicStructuredUsageRouteImport } from './routes/api.anthropic-structured-usage'
 import { Route as ApiAnthropicSkillsWireRouteImport } from './routes/api.anthropic-skills-wire'
+import { Route as ApiAnthropicRedactedThinkingWireRouteImport } from './routes/api.anthropic-redacted-thinking-wire'
 import { Route as ApiAnthropicOpus5CombinedWireRouteImport } from './routes/api.anthropic-opus-5-combined-wire'
 import { Route as ApiAnthropicMultiTurnStructuredWireRouteImport } from './routes/api.anthropic-multi-turn-structured-wire'
 import { Route as ApiAnthropicBugTestRouteImport } from './routes/api.anthropic-bug-test'
@@ -727,6 +728,12 @@ const ApiAnthropicSkillsWireRoute = ApiAnthropicSkillsWireRouteImport.update({
   path: '/api/anthropic-skills-wire',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiAnthropicRedactedThinkingWireRoute =
+  ApiAnthropicRedactedThinkingWireRouteImport.update({
+    id: '/api/anthropic-redacted-thinking-wire',
+    path: '/api/anthropic-redacted-thinking-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
 const ApiAnthropicOpus5CombinedWireRoute =
   ApiAnthropicOpus5CombinedWireRouteImport.update({
     id: '/api/anthropic-opus-5-combined-wire',
@@ -811,6 +818,7 @@ export interface FileRoutesByFullPath {
   '/api/anthropic-bug-test': typeof ApiAnthropicBugTestRoute
   '/api/anthropic-multi-turn-structured-wire': typeof ApiAnthropicMultiTurnStructuredWireRoute
   '/api/anthropic-opus-5-combined-wire': typeof ApiAnthropicOpus5CombinedWireRoute
+  '/api/anthropic-redacted-thinking-wire': typeof ApiAnthropicRedactedThinkingWireRoute
   '/api/anthropic-skills-wire': typeof ApiAnthropicSkillsWireRoute
   '/api/anthropic-structured-usage': typeof ApiAnthropicStructuredUsageRoute
   '/api/anthropic-thinking-order-wire': typeof ApiAnthropicThinkingOrderWireRoute
@@ -936,6 +944,7 @@ export interface FileRoutesByTo {
   '/api/anthropic-bug-test': typeof ApiAnthropicBugTestRoute
   '/api/anthropic-multi-turn-structured-wire': typeof ApiAnthropicMultiTurnStructuredWireRoute
   '/api/anthropic-opus-5-combined-wire': typeof ApiAnthropicOpus5CombinedWireRoute
+  '/api/anthropic-redacted-thinking-wire': typeof ApiAnthropicRedactedThinkingWireRoute
   '/api/anthropic-skills-wire': typeof ApiAnthropicSkillsWireRoute
   '/api/anthropic-structured-usage': typeof ApiAnthropicStructuredUsageRoute
   '/api/anthropic-thinking-order-wire': typeof ApiAnthropicThinkingOrderWireRoute
@@ -1062,6 +1071,7 @@ export interface FileRoutesById {
   '/api/anthropic-bug-test': typeof ApiAnthropicBugTestRoute
   '/api/anthropic-multi-turn-structured-wire': typeof ApiAnthropicMultiTurnStructuredWireRoute
   '/api/anthropic-opus-5-combined-wire': typeof ApiAnthropicOpus5CombinedWireRoute
+  '/api/anthropic-redacted-thinking-wire': typeof ApiAnthropicRedactedThinkingWireRoute
   '/api/anthropic-skills-wire': typeof ApiAnthropicSkillsWireRoute
   '/api/anthropic-structured-usage': typeof ApiAnthropicStructuredUsageRoute
   '/api/anthropic-thinking-order-wire': typeof ApiAnthropicThinkingOrderWireRoute
@@ -1189,6 +1199,7 @@ export interface FileRouteTypes {
     | '/api/anthropic-bug-test'
     | '/api/anthropic-multi-turn-structured-wire'
     | '/api/anthropic-opus-5-combined-wire'
+    | '/api/anthropic-redacted-thinking-wire'
     | '/api/anthropic-skills-wire'
     | '/api/anthropic-structured-usage'
     | '/api/anthropic-thinking-order-wire'
@@ -1314,6 +1325,7 @@ export interface FileRouteTypes {
     | '/api/anthropic-bug-test'
     | '/api/anthropic-multi-turn-structured-wire'
     | '/api/anthropic-opus-5-combined-wire'
+    | '/api/anthropic-redacted-thinking-wire'
     | '/api/anthropic-skills-wire'
     | '/api/anthropic-structured-usage'
     | '/api/anthropic-thinking-order-wire'
@@ -1439,6 +1451,7 @@ export interface FileRouteTypes {
     | '/api/anthropic-bug-test'
     | '/api/anthropic-multi-turn-structured-wire'
     | '/api/anthropic-opus-5-combined-wire'
+    | '/api/anthropic-redacted-thinking-wire'
     | '/api/anthropic-skills-wire'
     | '/api/anthropic-structured-usage'
     | '/api/anthropic-thinking-order-wire'
@@ -1565,6 +1578,7 @@ export interface RootRouteChildren {
   ApiAnthropicBugTestRoute: typeof ApiAnthropicBugTestRoute
   ApiAnthropicMultiTurnStructuredWireRoute: typeof ApiAnthropicMultiTurnStructuredWireRoute
   ApiAnthropicOpus5CombinedWireRoute: typeof ApiAnthropicOpus5CombinedWireRoute
+  ApiAnthropicRedactedThinkingWireRoute: typeof ApiAnthropicRedactedThinkingWireRoute
   ApiAnthropicSkillsWireRoute: typeof ApiAnthropicSkillsWireRoute
   ApiAnthropicStructuredUsageRoute: typeof ApiAnthropicStructuredUsageRoute
   ApiAnthropicThinkingOrderWireRoute: typeof ApiAnthropicThinkingOrderWireRoute
@@ -2450,6 +2464,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiAnthropicSkillsWireRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/anthropic-redacted-thinking-wire': {
+      id: '/api/anthropic-redacted-thinking-wire'
+      path: '/api/anthropic-redacted-thinking-wire'
+      fullPath: '/api/anthropic-redacted-thinking-wire'
+      preLoaderRoute: typeof ApiAnthropicRedactedThinkingWireRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/anthropic-opus-5-combined-wire': {
       id: '/api/anthropic-opus-5-combined-wire'
       path: '/api/anthropic-opus-5-combined-wire'
@@ -2611,6 +2632,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiAnthropicMultiTurnStructuredWireRoute:
     ApiAnthropicMultiTurnStructuredWireRoute,
   ApiAnthropicOpus5CombinedWireRoute: ApiAnthropicOpus5CombinedWireRoute,
+  ApiAnthropicRedactedThinkingWireRoute: ApiAnthropicRedactedThinkingWireRoute,
   ApiAnthropicSkillsWireRoute: ApiAnthropicSkillsWireRoute,
   ApiAnthropicStructuredUsageRoute: ApiAnthropicStructuredUsageRoute,
   ApiAnthropicThinkingOrderWireRoute: ApiAnthropicThinkingOrderWireRoute,
diff --git a/testing/e2e/src/routes/api.anthropic-redacted-thinking-wire.ts b/testing/e2e/src/routes/api.anthropic-redacted-thinking-wire.ts
new file mode 100644
index 0000000000..d98acda142
--- /dev/null
+++ b/testing/e2e/src/routes/api.anthropic-redacted-thinking-wire.ts
@@ -0,0 +1,241 @@
+import { createFileRoute } from '@tanstack/react-router'
+import {
+  chat,
+  chatParamsFromRequestBody,
+  createChatOptions,
+} from '@tanstack/ai'
+import { StreamProcessor, uiMessagesToWire } from '@tanstack/ai/client'
+import { createAnthropicChat } from '@tanstack/ai-anthropic'
+
+const DUMMY_KEY = 'sk-ant-e2e-test-dummy-key'
+
+type SseEvent = Record<string, unknown> & { type: string }
+
+const messageStart: SseEvent = {
+  type: 'message_start',
+  message: {
+    id: 'msg_redacted',
+    type: 'message',
+    role: 'assistant',
+    content: [],
+    model: 'claude-sonnet-4-5',
+    stop_reason: null,
+    stop_sequence: null,
+    usage: { input_tokens: 5, output_tokens: 0 },
+  },
+}
+
+/** Claude sends a redacted block whole, on its start event. */
+function redacted(index: number, data: string) {
+  return [
+    {
+      type: 'content_block_start',
+      index,
+      content_block: { type: 'redacted_thinking', data },
+    },
+    { type: 'content_block_stop', index },
+  ]
+}
+
+function text(index: number, value: string) {
+  return [
+    {
+      type: 'content_block_start',
+      index,
+      content_block: { type: 'text', text: '' },
+    },
+    {
+      type: 'content_block_delta',
+      index,
+      delta: { type: 'text_delta', text: value },
+    },
+    { type: 'content_block_stop', index },
+  ]
+}
+
+function toolUse(index: number, name: string) {
+  return [
+    {
+      type: 'content_block_start',
+      index,
+      content_block: { type: 'tool_use', id: 'toolu_1', name, input: {} },
+    },
+    {
+      type: 'content_block_delta',
+      index,
+      delta: { type: 'input_json_delta', partial_json: '{}' },
+    },
+    { type: 'content_block_stop', index },
+  ]
+}
+
+function end(stopReason: string) {
+  return [
+    {
+      type: 'message_delta',
+      delta: { stop_reason: stopReason, stop_sequence: null },
+      usage: { output_tokens: 20 },
+    },
+    { type: 'message_stop' },
+  ]
+}
+
+function sse(events: Array<SseEvent>): Response {
+  return new Response(
+    events
+      .map(
+        (event) => `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`,
+      )
+      .join(''),
+    { status: 200, headers: { 'Content-Type': 'text/event-stream' } },
+  )
+}
+
+type Body = {
+  messages: Array<{ role: string; content: unknown }>
+}
+
+/** Answers each call with the next scripted stream and records its body. */
+function scriptedFetch(streams: Array<Array<SseEvent>>) {
+  const bodies: Array<Body> = []
+  const fetchImpl: typeof fetch = async (input, init) => {
+    const req = input instanceof Request ? input : new Request(input, init)
+    bodies.push(JSON.parse(await req.text()))
+    return sse(
+      streams[bodies.length - 1] ?? [
+        messageStart,
+        ...text(0, 'Done.'),
+        ...end('end_turn'),
+      ],
+    )
+  }
+  return { bodies, fetchImpl }
+}
+
+function blocks(body: Body | undefined, role: string) {
+  const message = body?.messages.filter((m) => m.role === role).at(-1)
+  return Array.isArray(message?.content)
+    ? (message.content as Array<Record<string, unknown>>)
+    : []
+}
+
+/**
+ * Three scripted runs, answered by a capturing `fetch`:
+ *
+ * - `nextTurn`: a redacted block and text, then a second turn through
+ *   `StreamProcessor`, `uiMessagesToWire`, and `chatParamsFromRequestBody`,
+ *   as a browser client and `/api/chat` do.
+ * - `sameRun`: a redacted block and a tool call. The run's second request
+ *   continues after the tool.
+ * - `toolError`: the tool throws. The run's second request carries the result.
+ */
+export const Route = createFileRoute('/api/anthropic-redacted-thinking-wire')({
+  server: {
+    handlers: {
+      POST: async () => {
+        try {
+          const nextTurn = scriptedFetch([
+            [
+              messageStart,
+              ...redacted(0, 'opaque-1'),
+              ...text(1, 'Hello.'),
+              ...end('end_turn'),
+            ],
+          ])
+          const adapter = createAnthropicChat('claude-sonnet-4-5', DUMMY_KEY, {
+            fetch: nextTurn.fetchImpl,
+          })
+          const client = new StreamProcessor({})
+          for (const [index, prompt] of ['Hi', 'Say it again'].entries()) {
+            client.addUserMessage(prompt)
+            const params = await chatParamsFromRequestBody({
+              threadId: 'redacted-thinking',
+              runId: `redacted-thinking-${index + 1}`,
+              // `JSON.parse(JSON.stringify(...))` stands in for the HTTP hop.
+              messages: JSON.parse(
+                JSON.stringify(uiMessagesToWire(client.getMessages())),
+              ),
+              tools: [],
+              context: [],
+            })
+            for await (const chunk of chat({
+              ...createChatOptions({ adapter }),
+              messages: params.messages,
+              stream: true,
+            })) {
+              client.processChunk(chunk)
+            }
+            client.finalizeStream()
+          }
+
+          const sameRun = scriptedFetch([
+            [
+              messageStart,
+              ...redacted(0, 'opaque-2'),
+              ...toolUse(1, 'check'),
+              ...end('tool_use'),
+            ],
+          ])
+          for await (const _ of chat({
+            ...createChatOptions({
+              adapter: createAnthropicChat('claude-sonnet-4-5', DUMMY_KEY, {
+                fetch: sameRun.fetchImpl,
+              }),
+            }),
+            messages: [{ role: 'user', content: 'Check it' }],
+            tools: [
+              {
+                name: 'check',
+                description: 'Check something.',
+                execute: () => 'ok',
+              },
+            ],
+            stream: true,
+          })) {
+            // consume
+          }
+
+          const toolError = scriptedFetch([
+            [messageStart, ...toolUse(0, 'fail'), ...end('tool_use')],
+          ])
+          for await (const _ of chat({
+            ...createChatOptions({
+              adapter: createAnthropicChat('claude-sonnet-4-5', DUMMY_KEY, {
+                fetch: toolError.fetchImpl,
+              }),
+            }),
+            messages: [{ role: 'user', content: 'Try it' }],
+            tools: [
+              {
+                name: 'fail',
+                description: 'Always fails.',
+                execute: () => {
+                  throw new Error('Tool broke')
+                },
+              },
+            ],
+            stream: true,
+          })) {
+            // consume
+          }
+
+          return Response.json({
+            ok: true,
+            nextTurnBlocks: blocks(nextTurn.bodies[1], 'assistant'),
+            sameRunBlocks: blocks(sameRun.bodies[1], 'assistant').map(
+              (block) => block.type,
+            ),
+            toolResult: blocks(toolError.bodies[1], 'user').find(
+              (block) => block.type === 'tool_result',
+            ),
+          })
+        } catch (error) {
+          return Response.json({
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+          })
+        }
+      },
+    },
+  },
+})
diff --git a/testing/e2e/tests/anthropic-redacted-thinking-wire.spec.ts b/testing/e2e/tests/anthropic-redacted-thinking-wire.spec.ts
new file mode 100644
index 0000000000..d203d57115
--- /dev/null
+++ b/testing/e2e/tests/anthropic-redacted-thinking-wire.spec.ts
@@ -0,0 +1,40 @@
+import { test, expect } from './fixtures'
+
+/**
+ * Claude encrypts some thinking as a `redacted_thinking` block with opaque
+ * `data`. The next request must send that block back unchanged, and a failed
+ * tool result must say `is_error: true`.
+ * `/api/anthropic-redacted-thinking-wire` scripts the responses and returns
+ * what the follow-up requests sent.
+ */
+test.describe('anthropic — redacted thinking and tool errors on the wire', () => {
+  test('the next turn, the same run, and a failed tool send them back', async ({
+    request,
+  }) => {
+    const response = await request.post('/api/anthropic-redacted-thinking-wire')
+    expect(response.ok()).toBe(true)
+    const result = (await response.json()) as {
+      ok: boolean
+      error?: string
+      nextTurnBlocks: Array<Record<string, unknown>>
+      sameRunBlocks: Array<string>
+      toolResult?: Record<string, unknown>
+    }
+    if (!result.ok) throw new Error(`Route failed: ${result.error}`)
+
+    // A new turn from the client history: the block crossed the wire.
+    expect(result.nextTurnBlocks).toEqual([
+      { type: 'redacted_thinking', data: 'opaque-1' },
+      { type: 'text', text: 'Hello.' },
+    ])
+
+    // The same run continues after the tool, with the block first.
+    expect(result.sameRunBlocks).toEqual(['redacted_thinking', 'tool_use'])
+
+    // The failed tool is marked as an error.
+    expect(result.toolResult).toMatchObject({
+      tool_use_id: 'toolu_1',
+      is_error: true,
+    })
+  })
+})

From d4f41e83b99e98cf3ea508653e12901819c77d2c Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 19:15:34 +0200
Subject: [PATCH 103/286] feat(ai): isContextOverflow finds context-window
 overflows across providers

It reads a RUN_ERROR, an Error, or a message against about 25 provider overflow messages, and skips rate limits and throttles. With contextWindow it also finds a silent overflow and a length stop with no output. The patterns follow pi's isContextOverflow (MIT).
---
 .changeset/context-overflow.md                |   8 +
 docs/advanced/compaction.md                   |  37 ++++
 packages/ai/src/index.ts                      |   4 +
 packages/ai/src/utilities/context-overflow.ts | 114 ++++++++++++
 packages/ai/tests/context-overflow.test.ts    | 172 ++++++++++++++++++
 5 files changed, 335 insertions(+)
 create mode 100644 .changeset/context-overflow.md
 create mode 100644 packages/ai/src/utilities/context-overflow.ts
 create mode 100644 packages/ai/tests/context-overflow.test.ts

diff --git a/.changeset/context-overflow.md b/.changeset/context-overflow.md
new file mode 100644
index 0000000000..6558114335
--- /dev/null
+++ b/.changeset/context-overflow.md
@@ -0,0 +1,8 @@
+---
+'@tanstack/ai': minor
+---
+
+Add `isContextOverflow({ error, usage, finishReason, contextWindow, provider })`. It tells you that a model call failed, or ended early, because the input did not fit in the model's context window, so you can compact the history and retry.
+
+- It knows the overflow error messages of about 25 providers (Anthropic, OpenAI, Gemini, Bedrock, Mistral, xAI, Groq, OpenRouter, Ollama, and more), and it ignores rate-limit and throttle errors.
+- With `contextWindow`, it also finds a silent overflow (the input is bigger than the window) and a length stop with no output and a full window.
diff --git a/docs/advanced/compaction.md b/docs/advanced/compaction.md
index 5b9ab3593b..14fb2554ed 100644
--- a/docs/advanced/compaction.md
+++ b/docs/advanced/compaction.md
@@ -193,6 +193,43 @@ The token count is a rough `characters / 4` estimate. It is good enough to trigg
 - **It runs before every model call.** Compaction skips `init`. It runs on `beforeModel` and `structuredOutput`. Each later call can compact again.
 - **The canonical transcript stays complete.** Compaction writes provider-only context. Persistence and other middleware still read `ctx.messages`.
 
+## Retry after an overflow
+
+The token count is an estimate, so a call can still pass the model's context limit and fail. `isContextOverflow` from `@tanstack/ai` tells you that a call failed for this reason. Compact harder, then call the model again:
+
+```ts group=compaction-overflow
+import { chat, isContextOverflow } from '@tanstack/ai'
+import type { ModelMessage } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { withCompaction } from '@tanstack/ai-compaction'
+
+async function answer(messages: Array<ModelMessage>) {
+  for (const maxTokens of [100_000, 50_000]) {
+    let text = ''
+    let overflow = false
+    for await (const chunk of chat({
+      adapter: openaiText('gpt-6.1-sol'),
+      messages,
+      middleware: [withCompaction({ maxTokens })],
+    })) {
+      if (chunk.type === 'TEXT_MESSAGE_CONTENT') text += chunk.delta
+      if (chunk.type === 'RUN_ERROR') {
+        if (!isContextOverflow({ error: chunk })) throw new Error(chunk.message)
+        overflow = true
+      }
+    }
+    if (!overflow) return text
+  }
+  throw new Error('The conversation is too long, even after compaction.')
+}
+```
+
+`isContextOverflow` knows the overflow errors of Anthropic, OpenAI, Gemini, Bedrock, Mistral, xAI, Groq, OpenRouter, Ollama, and more. It ignores rate-limit errors. It takes one object, and every field is optional:
+
+- `error`: a `RUN_ERROR` event, an `Error`, or a message string.
+- `usage`, `finishReason`, and `contextWindow`: some providers accept an overflow and cut the input without an error. With the model's `contextWindow`, a call counts as an overflow when its `usage.promptTokens` is more than the window, or when it stopped with `'length'`, wrote nothing, and its input fills the window.
+- `provider`: set `'cerebras'` for Cerebras, which answers an overflow with a bare `400` or `413`.
+
 ## DevTools
 
 After a compaction, the chat stream includes three CUSTOM events in order:
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index cc62273d57..5e2ebf53ee 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -467,6 +467,10 @@ export {
 // Usage utilities
 export { buildBaseUsage, type BaseUsageInput } from './utilities/usage'
 
+// Context overflow detection
+export { isContextOverflow } from './utilities/context-overflow'
+export type { ContextOverflowInput } from './utilities/context-overflow'
+
 // Media-generation prompt resolution (used by image / video adapters)
 export { resolveMediaPrompt } from './utilities/media-prompt'
 export type { ResolvedMediaPrompt } from './utilities/media-prompt'
diff --git a/packages/ai/src/utilities/context-overflow.ts b/packages/ai/src/utilities/context-overflow.ts
new file mode 100644
index 0000000000..32503d155a
--- /dev/null
+++ b/packages/ai/src/utilities/context-overflow.ts
@@ -0,0 +1,114 @@
+import type { TokenUsage } from '../types'
+
+// The patterns and the silent and length-stop rules follow pi's
+// `isContextOverflow` (`@earendil-works/pi-ai`, `dist/utils/overflow.js`, MIT).
+const OVERFLOW_PATTERNS = [
+  /prompt (?:is )?too long/i, // Anthropic, z.ai
+  /request_too_large/i, // Anthropic request size (HTTP 413)
+  /input is too long for requested model/i, // Amazon Bedrock
+  /exceeds the context window/i, // OpenAI Chat Completions and Responses
+  /exceeds (?:the )?(?:model'?s )?maximum context length(?: of [\d,]+ tokens?|\s*\([\d,]+\))/i, // OpenAI-compatible proxies (LiteLLM)
+  /input token count.*exceeds the maximum/i, // Google Gemini
+  /maximum prompt length is \d+/i, // xAI
+  /reduce the length of the messages/i, // Groq
+  /maximum context length is \d+ tokens/i, // OpenRouter
+  /exceeds (?:the )?maximum allowed input length of [\d,]+ tokens?/i, // OpenRouter / Poolside
+  /input \(\d+ tokens\) is longer than the model'?s context length \(\d+ tokens\)/i, // Together AI
+  /exceeds the limit of \d+/i, // GitHub Copilot
+  /exceeds the available context size/i, // llama.cpp
+  /greater than the context length/i, // LM Studio
+  /context window exceeds limit/i, // MiniMax
+  /exceeded model token limit/i, // Kimi For Coding
+  /too large for model with \d+ maximum context length/i, // Mistral
+  /prompt has [\d,]+ tokens?, but the configured context size is [\d,]+ tokens?/i, // DS4
+  /model_context_window_exceeded/i, // z.ai finish reason as error text
+  /prompt too long; exceeded (?:max )?context length/i, // Ollama
+  /range of input length should be/i, // DashScope / Qwen
+  /context[_ ]length[_ ]exceeded/i, // generic
+  /too many tokens/i, // generic
+  /token limit exceeded/i, // generic
+]
+
+// Throttling and rate limits can match a pattern above ("too many tokens").
+const NOT_OVERFLOW_PATTERNS = [
+  /^(Throttling error|Service unavailable):/i, // Amazon Bedrock
+  /rate limit/i,
+  /too many requests/i,
+]
+
+// Cerebras answers an overflow with a bare 400 or 413.
+const CEREBRAS_BODYLESS_ERROR = /^4(?:00|13)\s*(?:status code)?\s*\(no body\)/i
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+/** The message of a `RUN_ERROR` event, an `Error`, or a string. */
+function errorText(error: unknown) {
+  if (typeof error === 'string') return error
+  if (error instanceof Error) return error.message
+  if (!isRecord(error)) return undefined
+  if (typeof error.message === 'string' && error.message !== '') {
+    return error.message
+  }
+  const nested = error.error
+  return isRecord(nested) && typeof nested.message === 'string'
+    ? nested.message
+    : undefined
+}
+
+function isOverflowError(text: string, provider: string | undefined) {
+  if (NOT_OVERFLOW_PATTERNS.some((pattern) => pattern.test(text))) return false
+  if (OVERFLOW_PATTERNS.some((pattern) => pattern.test(text))) return true
+  return provider === 'cerebras' && CEREBRAS_BODYLESS_ERROR.test(text)
+}
+
+/** What {@link isContextOverflow} reads. Every field is optional. */
+export interface ContextOverflowInput {
+  /** A `RUN_ERROR` event, an `Error`, or an error message. */
+  error?: unknown
+  /** The call's token usage, from `RUN_FINISHED`. */
+  usage?: Pick<TokenUsage, 'promptTokens' | 'completionTokens'>
+  /** The call's finish reason, from `RUN_FINISHED`. */
+  finishReason?: string | null
+  /** The model's context window in tokens. Needed for the silent and length-stop checks. */
+  contextWindow?: number
+  /** The provider id. Only `'cerebras'` changes the result: Cerebras answers an overflow with a 400 or 413 and no body. */
+  provider?: string
+}
+
+/**
+ * Whether a model call failed, or ended early, because the input did not fit
+ * in the model's context window. Use it to compact the history and retry.
+ *
+ * - An error counts when its message matches a known overflow message of a
+ *   provider (Anthropic, OpenAI, Gemini, Bedrock, xAI, Groq, OpenRouter,
+ *   Mistral, Ollama, and more), and it is not a rate limit or a throttle.
+ * - With `contextWindow`, a call that finished with `'stop'` counts when
+ *   `usage.promptTokens` is more than the window. Some providers accept an
+ *   overflow and cut the input without an error.
+ * - With `contextWindow`, a call that finished with `'length'` counts when it
+ *   wrote no tokens and its input fills 99% of the window.
+ *
+ * @example
+ * ```ts
+ * for await (const chunk of chat({ adapter, messages })) {
+ *   if (chunk.type === 'RUN_ERROR' && isContextOverflow({ error: chunk })) {
+ *     // compact `messages`, then call chat() again
+ *   }
+ * }
+ * ```
+ */
+export function isContextOverflow(input: ContextOverflowInput) {
+  const text = errorText(input.error)
+  if (text !== undefined && isOverflowError(text, input.provider)) return true
+
+  const { usage, finishReason, contextWindow } = input
+  if (!usage || !contextWindow) return false
+  if (finishReason === 'stop') return usage.promptTokens > contextWindow
+  return (
+    finishReason === 'length' &&
+    usage.completionTokens === 0 &&
+    usage.promptTokens >= contextWindow * 0.99
+  )
+}
diff --git a/packages/ai/tests/context-overflow.test.ts b/packages/ai/tests/context-overflow.test.ts
new file mode 100644
index 0000000000..0a3ddf7958
--- /dev/null
+++ b/packages/ai/tests/context-overflow.test.ts
@@ -0,0 +1,172 @@
+import { describe, expect, it } from 'vitest'
+import { isContextOverflow } from '../src/utilities/context-overflow'
+import { EventType } from '../src/types'
+import type { RunErrorEvent } from '../src/types'
+
+// One real overflow message per pattern. Most are the examples in pi's
+// `overflow.js` header.
+const OVERFLOW_MESSAGES: Array<[string, string]> = [
+  ['Anthropic', 'prompt is too long: 213462 tokens > 200000 maximum'],
+  [
+    'Anthropic request size',
+    '413 {"error":{"type":"request_too_large","message":"Request exceeds the maximum size"}}',
+  ],
+  ['Amazon Bedrock', 'Input is too long for requested model.'],
+  ['OpenAI', 'Your input exceeds the context window of this model'],
+  [
+    'OpenAI / LiteLLM',
+    "Requested token count exceeds the model's maximum context length of 131072 tokens",
+  ],
+  [
+    'OpenAI-compatible',
+    "Input length (265330) exceeds model's maximum context length (262144).",
+  ],
+  [
+    'Google',
+    'The input token count (1196265) exceeds the maximum number of tokens allowed (1048575)',
+  ],
+  [
+    'xAI',
+    "This model's maximum prompt length is 131072 but the request contains 537812 tokens",
+  ],
+  ['Groq', 'Please reduce the length of the messages or completion'],
+  [
+    'OpenRouter',
+    "This endpoint's maximum context length is 128000 tokens. However, you requested about 140000 tokens",
+  ],
+  [
+    'OpenRouter / Poolside',
+    'Input length 300000 exceeds the maximum allowed input length of 262144 tokens.',
+  ],
+  [
+    'Together AI',
+    "The input (140000 tokens) is longer than the model's context length (131072 tokens).",
+  ],
+  [
+    'GitHub Copilot',
+    'prompt token count of 140000 exceeds the limit of 128000',
+  ],
+  [
+    'llama.cpp',
+    'the request exceeds the available context size, try increasing it',
+  ],
+  [
+    'LM Studio',
+    'tokens to keep from the initial prompt is greater than the context length',
+  ],
+  ['MiniMax', 'invalid params, context window exceeds limit'],
+  [
+    'Kimi For Coding',
+    'Your request exceeded model token limit: 262144 (requested: 300000)',
+  ],
+  [
+    'Mistral',
+    'Prompt contains 140000 tokens and 0 draft tokens, too large for model with 131072 maximum context length',
+  ],
+  [
+    'DS4',
+    'Prompt has 140000 tokens, but the configured context size is 131072 tokens',
+  ],
+  ['z.ai', '{"code":"1261","message":"Prompt too long"}'],
+  ['z.ai finish reason', 'model_context_window_exceeded'],
+  ['Ollama', 'prompt too long; exceeded max context length by 1200 tokens'],
+  ['DashScope / Qwen', 'Range of input length should be [1, 129024]'],
+  ['generic context_length_exceeded', 'context_length_exceeded'],
+  ['generic too many tokens', 'Too many tokens in the request'],
+  ['generic token limit', 'Token limit exceeded for this model'],
+]
+
+const NOT_OVERFLOW_MESSAGES: Array<[string, string]> = [
+  [
+    'Bedrock throttling',
+    'Throttling error: Too many tokens, please wait before trying again.',
+  ],
+  ['Bedrock service', 'Service unavailable: too many tokens in flight'],
+  ['rate limit', 'Rate limit reached: too many tokens per minute'],
+  ['HTTP 429', '429 Too Many Requests: token limit exceeded'],
+  ['other 400', '400 Invalid tool schema'],
+]
+
+describe('isContextOverflow', () => {
+  it.each(OVERFLOW_MESSAGES)(
+    'detects the %s overflow message',
+    (_, message) => {
+      expect(isContextOverflow({ error: message })).toBe(true)
+    },
+  )
+
+  it.each(NOT_OVERFLOW_MESSAGES)('ignores %s', (_, message) => {
+    expect(isContextOverflow({ error: message })).toBe(false)
+  })
+
+  it("counts Cerebras' bodyless 400 and 413 only for Cerebras", () => {
+    expect(
+      isContextOverflow({
+        error: '400 status code (no body)',
+        provider: 'cerebras',
+      }),
+    ).toBe(true)
+    expect(
+      isContextOverflow({ error: '413 (no body)', provider: 'cerebras' }),
+    ).toBe(true)
+    expect(isContextOverflow({ error: '400 status code (no body)' })).toBe(
+      false,
+    )
+  })
+
+  it('reads a RUN_ERROR event, an Error, and a nested error message', () => {
+    const runError: RunErrorEvent = {
+      type: EventType.RUN_ERROR,
+      message: 'prompt is too long: 213462 tokens > 200000 maximum',
+      timestamp: 0,
+    }
+
+    expect(isContextOverflow({ error: runError })).toBe(true)
+    expect(
+      isContextOverflow({
+        error: new Error('Input is too long for requested model'),
+      }),
+    ).toBe(true)
+    expect(
+      isContextOverflow({
+        error: { error: { message: 'maximum context length is 8192 tokens' } },
+      }),
+    ).toBe(true)
+  })
+
+  it('detects a silent overflow: a stop with more input than the window', () => {
+    const usage = { promptTokens: 9_000, completionTokens: 40 }
+
+    expect(
+      isContextOverflow({ usage, finishReason: 'stop', contextWindow: 8_000 }),
+    ).toBe(true)
+    expect(
+      isContextOverflow({ usage, finishReason: 'stop', contextWindow: 10_000 }),
+    ).toBe(false)
+    expect(isContextOverflow({ usage, finishReason: 'stop' })).toBe(false)
+  })
+
+  it('detects a length stop with no output and a full window', () => {
+    expect(
+      isContextOverflow({
+        usage: { promptTokens: 7_950, completionTokens: 0 },
+        finishReason: 'length',
+        contextWindow: 8_000,
+      }),
+    ).toBe(true)
+    expect(
+      isContextOverflow({
+        usage: { promptTokens: 7_950, completionTokens: 12 },
+        finishReason: 'length',
+        contextWindow: 8_000,
+      }),
+    ).toBe(false)
+    expect(
+      isContextOverflow({
+        usage: { promptTokens: 4_000, completionTokens: 0 },
+        finishReason: 'length',
+        contextWindow: 8_000,
+      }),
+    ).toBe(false)
+  })
+})

From 1b0a5d20f8076b6f161fef57375b2329fb39e3df Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 19:15:37 +0200
Subject: [PATCH 104/286] feat(ai): fakeText scripted adapter at
 @tanstack/ai/testing

A text adapter that answers from a queue of scripted responses or factories, for tests with no network. It estimates usage as ceil(characters / 4), can estimate cache reads per thread, paces the stream, and stops on abort.
---
 .changeset/fake-text-adapter.md      |   9 +
 docs/advanced/testing.md             | 127 +++++++++
 packages/ai/package.json             |   4 +
 packages/ai/src/testing.ts           |   8 +
 packages/ai/src/testing/fake-text.ts | 368 +++++++++++++++++++++++++++
 packages/ai/tests/fake-text.test.ts  | 256 +++++++++++++++++++
 packages/ai/vite.config.ts           |   1 +
 7 files changed, 773 insertions(+)
 create mode 100644 .changeset/fake-text-adapter.md
 create mode 100644 docs/advanced/testing.md
 create mode 100644 packages/ai/src/testing.ts
 create mode 100644 packages/ai/src/testing/fake-text.ts
 create mode 100644 packages/ai/tests/fake-text.test.ts

diff --git a/.changeset/fake-text-adapter.md b/.changeset/fake-text-adapter.md
new file mode 100644
index 0000000000..fdd7fe623f
--- /dev/null
+++ b/.changeset/fake-text-adapter.md
@@ -0,0 +1,9 @@
+---
+'@tanstack/ai': minor
+---
+
+Add `fakeText()` at the new `@tanstack/ai/testing` subpath: a text adapter that answers from a script, for tests of `chat()`, tools, and middleware with no network and no API key.
+
+- Queue answers with `setResponses` and `appendResponses`. An answer is `{ text?, thinking?, toolCalls?, finishReason?, error? }`, or a function that gets `{ request, state }`. An empty queue fails with "No more fake responses queued".
+- Token usage is estimated as `ceil(characters / 4)`. With `cache: true`, the part of a request that matches the thread's previous request counts as cached tokens.
+- Options: `model`, `input` (the adapter's input modalities), `contextWindow`, and `tokensPerSecond` for stream pacing. The stream stops when the request aborts.
diff --git a/docs/advanced/testing.md b/docs/advanced/testing.md
new file mode 100644
index 0000000000..ca31a868ec
--- /dev/null
+++ b/docs/advanced/testing.md
@@ -0,0 +1,127 @@
+---
+title: Test with a Fake Model
+id: testing
+order: 16
+description: "Test chat(), tools, and middleware with no network and no API key. fakeText() from @tanstack/ai/testing answers from a script and estimates token usage."
+keywords:
+  - tanstack ai
+  - testing
+  - fake adapter
+  - mock model
+  - unit tests
+  - fakeText
+---
+
+A test that calls a real model is slow, costs money, needs an API key, and can get a different answer each time. `fakeText()` from `@tanstack/ai/testing` is a text adapter that answers from a script you write. Pass it to `chat()` like any other adapter.
+
+## Answer a prompt
+
+Queue the answers, then run `chat()`:
+
+```ts group=testing
+import { chat } from '@tanstack/ai'
+import { fakeText } from '@tanstack/ai/testing'
+
+const fake = fakeText()
+fake.setResponses([{ text: 'Hello!' }])
+
+let answer = ''
+for await (const chunk of chat({
+  adapter: fake,
+  messages: [{ role: 'user', content: 'Hi' }],
+})) {
+  if (chunk.type === 'TEXT_MESSAGE_CONTENT') answer += chunk.delta
+}
+console.log(answer) // 'Hello!'
+```
+
+- Each model call takes the next answer from the queue.
+- An empty queue ends the call with a `RUN_ERROR`: "No more fake responses queued".
+- `appendResponses` adds answers to the queue, and `pendingResponses()` counts what is left.
+
+## Test a tool
+
+An answer with `toolCalls` makes `chat()` run your tools. Queue the answer that comes after the tool results too:
+
+```ts group=testing
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+
+const getWeather = toolDefinition({
+  name: 'get_weather',
+  description: 'Get the weather in a city',
+  inputSchema: z.object({ city: z.string() }),
+}).server(async ({ city }) => ({ city, sky: 'sunny' }))
+
+const weatherFake = fakeText()
+weatherFake.setResponses([
+  { toolCalls: [{ name: 'get_weather', input: { city: 'Oslo' } }] },
+  { text: 'It is sunny in Oslo.' },
+])
+
+for await (const chunk of chat({
+  adapter: weatherFake,
+  messages: [{ role: 'user', content: 'Weather in Oslo?' }],
+  tools: [getWeather],
+})) {
+  if (chunk.type === 'TOOL_CALL_RESULT') console.log(chunk.content)
+}
+console.log(weatherFake.state.callCount) // 2
+```
+
+## Answer from the request
+
+A function in the queue builds its answer when the call arrives. It gets one object with the `request` and the `state`:
+
+```ts group=testing
+const echo = fakeText()
+echo.setResponses([
+  ({ request, state }) => ({
+    text: `Call ${state.callCount} saw ${request.messages.length} messages.`,
+  }),
+])
+```
+
+## Test errors and overflow
+
+An answer with `error` fails the call. With [`isContextOverflow`](./compaction#retry-after-an-overflow), test the code that compacts and retries:
+
+```ts group=testing
+import { isContextOverflow } from '@tanstack/ai'
+
+const small = fakeText({ contextWindow: 1_000 })
+small.setResponses([{ error: 'prompt is too long: 2000 tokens > 1000 maximum' }])
+
+for await (const chunk of chat({
+  adapter: small,
+  messages: [{ role: 'user', content: 'A very long question' }],
+})) {
+  if (chunk.type === 'RUN_ERROR') {
+    console.log(isContextOverflow({ error: chunk })) // true
+  }
+}
+```
+
+The fake also reports token usage on each call: `ceil(characters / 4)` over the request and the answer. So a long message is many tokens, like with a real model.
+
+## Options
+
+| Option | What it does |
+|---|---|
+| `model` | The model id. Default `'fake-model'`. |
+| `input` | The input kinds the model reads, for example `['text', 'image']`. |
+| `contextWindow` | The context window in tokens. Read it back as `fake.contextWindow`. |
+| `tokensPerSecond` | Stream the text at this pace, 4 characters per token. |
+| `cache` | With a `threadId`, count the part of the request that matches the thread's previous request as cached tokens. |
+
+## Answer fields
+
+| Field | What it does |
+|---|---|
+| `text` | The visible answer. |
+| `thinking` | Thinking text, streamed before the answer. |
+| `toolCalls` | `{ name, input?, id? }` calls for `chat()` to run. |
+| `finishReason` | `'stop'`, `'length'`, `'content_filter'`, or `'tool_calls'`. Default `'tool_calls'` with tool calls, else `'stop'`. |
+| `error` | Fail the call with a `RUN_ERROR` that has this message. |
+
+Your tests now run with no network and no key, and they get the same answers every time.
diff --git a/packages/ai/package.json b/packages/ai/package.json
index 296badc283..0a8c8810f2 100644
--- a/packages/ai/package.json
+++ b/packages/ai/package.json
@@ -49,6 +49,10 @@
       "types": "./dist/esm/adapter-internals.d.ts",
       "import": "./dist/esm/adapter-internals.js"
     },
+    "./testing": {
+      "types": "./dist/esm/testing.d.ts",
+      "import": "./dist/esm/testing.js"
+    },
     "./byok": {
       "types": "./dist/esm/byok.d.ts",
       "import": "./dist/esm/byok.js"
diff --git a/packages/ai/src/testing.ts b/packages/ai/src/testing.ts
new file mode 100644
index 0000000000..f714d1bc93
--- /dev/null
+++ b/packages/ai/src/testing.ts
@@ -0,0 +1,8 @@
+// Test helpers for `@tanstack/ai`. Import from `@tanstack/ai/testing`.
+export { fakeText, FakeTextAdapter } from './testing/fake-text'
+export type {
+  FakeResponse,
+  FakeResponseStep,
+  FakeTextOptions,
+  FakeTextState,
+} from './testing/fake-text'
diff --git a/packages/ai/src/testing/fake-text.ts b/packages/ai/src/testing/fake-text.ts
new file mode 100644
index 0000000000..ccd0081ca2
--- /dev/null
+++ b/packages/ai/src/testing/fake-text.ts
@@ -0,0 +1,368 @@
+import { BaseTextAdapter } from '../activities/chat/adapter'
+import { EventType } from '../types'
+import type {
+  StructuredOutputOptions,
+  StructuredOutputResult,
+} from '../activities/chat/adapter'
+import type { AdapterYieldChunk } from '../utilities/adapter-yield-chunk'
+import type {
+  ContentPart,
+  DefaultMessageMetadataByModality,
+  Modality,
+  ModelMessage,
+  TextOptions,
+  TokenUsage,
+} from '../types'
+
+/** One scripted answer of the fake model. */
+export interface FakeResponse {
+  /** The visible text. */
+  text?: string
+  /** Thinking text, streamed before the answer. */
+  thinking?: string
+  /** Tool calls. `id` defaults to `fake-call-<n>`. */
+  toolCalls?: Array<{ name: string; input?: unknown; id?: string }>
+  /** Default: `'tool_calls'` when there are tool calls, else `'stop'`. */
+  finishReason?: 'stop' | 'length' | 'content_filter' | 'tool_calls'
+  /** Fail the call with a `RUN_ERROR` that has this message. */
+  error?: string
+}
+
+/** Counters of a fake adapter. */
+export interface FakeTextState {
+  /** How many model calls the fake answered. */
+  callCount: number
+}
+
+/** A scripted answer, or a function that builds one from the request. */
+export type FakeResponseStep =
+  | FakeResponse
+  | ((call: {
+      request: TextOptions
+      state: FakeTextState
+    }) => FakeResponse | Promise<FakeResponse>)
+
+export interface FakeTextOptions<
+  TModel extends string,
+  TInput extends ReadonlyArray<Modality>,
+> {
+  /** The model id. Default `'fake-model'`. */
+  model?: TModel
+  /** The input kinds the model reads. Sets the adapter's `inputModalities`. */
+  input?: TInput
+  /** The model's context window in tokens. Data for the caller. */
+  contextWindow?: number
+  /** Stream the text at this many tokens (4 characters each) per second. */
+  tokensPerSecond?: number
+  /**
+   * Estimate prompt caching per `threadId`: the part of the request that
+   * matches the thread's previous request counts as cached.
+   */
+  cache?: boolean
+}
+
+const EMPTY_QUEUE = 'No more fake responses queued'
+const CHARS_PER_TOKEN = 4
+
+function estimateTokens(text: string) {
+  return Math.ceil(text.length / CHARS_PER_TOKEN)
+}
+
+function partText(part: ContentPart) {
+  if (part.type === 'text') return part.content
+  const source = part.source
+  const mime = 'mimeType' in source ? source.mimeType : 'unknown'
+  return `[${part.type}:${mime}:${source.value.length}]`
+}
+
+function messageText(message: ModelMessage) {
+  const content =
+    typeof message.content === 'string'
+      ? message.content
+      : (message.content ?? []).map(partText).join('')
+  const calls = (message.toolCalls ?? []).map(
+    (call) => `${call.function.name}:${call.function.arguments}`,
+  )
+  return [`${message.role}:${content}`, ...calls].join('\n')
+}
+
+/** pi's serialized request form: the system prompts, then `role:text` per message. */
+function serializeRequest(request: TextOptions) {
+  const system = (request.systemPrompts ?? []).map(
+    (prompt) =>
+      `system:${typeof prompt === 'string' ? prompt : prompt.content}`,
+  )
+  return [...system, ...request.messages.map(messageText)].join('\n')
+}
+
+function serializeResponse(response: FakeResponse) {
+  const calls = (response.toolCalls ?? []).map(
+    (call) => `${call.name}:${JSON.stringify(call.input ?? {})}`,
+  )
+  return [response.thinking ?? '', response.text ?? '', ...calls]
+    .filter((part) => part !== '')
+    .join('\n')
+}
+
+function commonPrefixLength(a: string, b: string) {
+  const max = Math.min(a.length, b.length)
+  let index = 0
+  while (index < max && a[index] === b[index]) index++
+  return index
+}
+
+function chunksOf(text: string) {
+  const chunks: Array<string> = []
+  for (let index = 0; index < text.length; index += CHARS_PER_TOKEN) {
+    chunks.push(text.slice(index, index + CHARS_PER_TOKEN))
+  }
+  return chunks
+}
+
+/**
+ * A text adapter that answers from a script. Use it to test `chat()`, tools,
+ * and middleware with no network and no API key. Create it with `fakeText()`.
+ */
+export class FakeTextAdapter<
+  TModel extends string,
+  TInput extends ReadonlyArray<Modality>,
+> extends BaseTextAdapter<
+  TModel,
+  Record<string, unknown>,
+  TInput,
+  DefaultMessageMetadataByModality
+> {
+  readonly name = 'fake'
+  override readonly inputModalities: ReadonlyArray<Modality> | undefined
+  /** The context window from the options. */
+  readonly contextWindow: number | undefined
+  readonly state: FakeTextState = { callCount: 0 }
+
+  private queue: Array<FakeResponseStep> = []
+  private readonly previousRequests = new Map<string, string>()
+  private readonly options: FakeTextOptions<TModel, TInput>
+
+  constructor(model: TModel, options: FakeTextOptions<TModel, TInput>) {
+    super({}, model)
+    this.options = options
+    this.inputModalities = options.input
+    this.contextWindow = options.contextWindow
+  }
+
+  /** Replace the queue of answers. */
+  setResponses(responses: Array<FakeResponseStep>) {
+    this.queue = [...responses]
+  }
+
+  /** Add answers to the end of the queue. */
+  appendResponses(responses: Array<FakeResponseStep>) {
+    this.queue.push(...responses)
+  }
+
+  /** How many answers are still queued. */
+  pendingResponses() {
+    return this.queue.length
+  }
+
+  private async nextResponse(request: TextOptions) {
+    const step = this.queue.shift()
+    this.state.callCount++
+    if (step === undefined) return { error: EMPTY_QUEUE }
+    return typeof step === 'function'
+      ? await step({ request, state: this.state })
+      : step
+  }
+
+  private usage(request: TextOptions, response: FakeResponse) {
+    const serialized = serializeRequest(request)
+    const promptTokens = estimateTokens(serialized)
+    const completionTokens = estimateTokens(serializeResponse(response))
+    const usage: TokenUsage = {
+      promptTokens,
+      completionTokens,
+      totalTokens: promptTokens + completionTokens,
+    }
+    const thread = request.threadId
+    if (!this.options.cache || thread === undefined) return usage
+    const previous = this.previousRequests.get(thread) ?? ''
+    this.previousRequests.set(thread, serialized)
+    const cachedTokens = Math.floor(
+      commonPrefixLength(previous, serialized) / CHARS_PER_TOKEN,
+    )
+    return {
+      ...usage,
+      promptTokensDetails: {
+        cachedTokens,
+        cacheWriteTokens: promptTokens - cachedTokens,
+      },
+    }
+  }
+
+  private async pace(signal: AbortSignal | undefined) {
+    const perSecond = this.options.tokensPerSecond
+    if (!perSecond) return !signal?.aborted
+    await new Promise((resolve) => setTimeout(resolve, 1000 / perSecond))
+    return !signal?.aborted
+  }
+
+  async *chatStream(options: TextOptions): AsyncIterable<AdapterYieldChunk> {
+    const signal = options.abortController?.signal
+    const runId = options.runId ?? `fake-run-${this.state.callCount + 1}`
+    const threadId = options.threadId ?? 'fake-thread'
+    const model = this.model
+    const response = await this.nextResponse(options)
+    yield {
+      type: EventType.RUN_STARTED,
+      runId,
+      threadId,
+      model,
+      timestamp: Date.now(),
+    }
+    if (response.error !== undefined) {
+      yield {
+        type: EventType.RUN_ERROR,
+        model,
+        timestamp: Date.now(),
+        message: response.error,
+        error: { message: response.error },
+      }
+      return
+    }
+
+    if (response.thinking) {
+      const messageId = `${runId}-thinking`
+      yield {
+        type: EventType.REASONING_START,
+        messageId,
+        timestamp: Date.now(),
+      }
+      yield {
+        type: EventType.REASONING_MESSAGE_START,
+        messageId,
+        role: 'reasoning',
+        timestamp: Date.now(),
+      }
+      for (const delta of chunksOf(response.thinking)) {
+        if (!(await this.pace(signal))) return
+        yield {
+          type: EventType.REASONING_MESSAGE_CONTENT,
+          messageId,
+          delta,
+          timestamp: Date.now(),
+        }
+      }
+      yield {
+        type: EventType.REASONING_MESSAGE_END,
+        messageId,
+        timestamp: Date.now(),
+      }
+      yield { type: EventType.REASONING_END, messageId, timestamp: Date.now() }
+    }
+
+    if (response.text) {
+      const messageId = `${runId}-text`
+      yield {
+        type: EventType.TEXT_MESSAGE_START,
+        messageId,
+        role: 'assistant',
+        model,
+        timestamp: Date.now(),
+      }
+      for (const delta of chunksOf(response.text)) {
+        if (!(await this.pace(signal))) return
+        yield {
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          messageId,
+          delta,
+          model,
+          timestamp: Date.now(),
+        }
+      }
+      yield {
+        type: EventType.TEXT_MESSAGE_END,
+        messageId,
+        model,
+        timestamp: Date.now(),
+      }
+    }
+
+    const toolCalls = response.toolCalls ?? []
+    for (const [index, call] of toolCalls.entries()) {
+      const toolCallId = call.id ?? `fake-call-${this.state.callCount}-${index}`
+      yield {
+        type: EventType.TOOL_CALL_START,
+        toolCallId,
+        toolCallName: call.name,
+        toolName: call.name,
+        model,
+        timestamp: Date.now(),
+        index,
+      }
+      yield {
+        type: EventType.TOOL_CALL_ARGS,
+        toolCallId,
+        delta: JSON.stringify(call.input ?? {}),
+        model,
+        timestamp: Date.now(),
+      }
+      yield {
+        type: EventType.TOOL_CALL_END,
+        toolCallId,
+        model,
+        timestamp: Date.now(),
+      }
+    }
+
+    yield {
+      type: EventType.RUN_FINISHED,
+      runId,
+      threadId,
+      model,
+      timestamp: Date.now(),
+      finishReason:
+        response.finishReason ?? (toolCalls.length > 0 ? 'tool_calls' : 'stop'),
+      usage: this.usage(options, response),
+    }
+  }
+
+  /** Answers with the next queued response. Its `text` must be JSON. */
+  async structuredOutput(
+    options: StructuredOutputOptions<Record<string, unknown>>,
+  ): Promise<StructuredOutputResult<unknown>> {
+    const response = await this.nextResponse(options.chatOptions)
+    if (response.error !== undefined) throw new Error(response.error)
+    const rawText = response.text ?? ''
+    return {
+      data: JSON.parse(rawText),
+      rawText,
+      usage: this.usage(options.chatOptions, response),
+    }
+  }
+}
+
+/**
+ * Create a scripted fake text adapter for tests. Queue answers with
+ * `setResponses`, then pass the fake to `chat()` as its adapter.
+ *
+ * - An empty queue answers with a `RUN_ERROR`: "No more fake responses queued".
+ * - Usage is estimated as `ceil(characters / 4)` over the request and the
+ *   answer, so a long message can overflow a small `contextWindow`.
+ *
+ * @example
+ * ```ts
+ * const fake = fakeText()
+ * fake.setResponses([{ text: 'Hello' }])
+ * for await (const chunk of chat({ adapter: fake, messages })) {
+ *   // ...
+ * }
+ * ```
+ */
+export function fakeText<
+  const TModel extends string = 'fake-model',
+  const TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>,
+>(options: FakeTextOptions<TModel, TInput> = {}) {
+  const model = options.model ?? 'fake-model'
+  // `options.model` is `TModel` when set. The default only applies when the
+  // caller left it out, and then `TModel` is the default `'fake-model'`.
+  return new FakeTextAdapter(model as TModel, options)
+}
diff --git a/packages/ai/tests/fake-text.test.ts b/packages/ai/tests/fake-text.test.ts
new file mode 100644
index 0000000000..69e697c849
--- /dev/null
+++ b/packages/ai/tests/fake-text.test.ts
@@ -0,0 +1,256 @@
+import { describe, expect, it } from 'vitest'
+import { chat } from '../src/activities/chat/index'
+import { EventType } from '../src/types'
+import { fakeText } from '../src/testing'
+import { resolveDebugOption } from '../src/logger/resolve'
+import { collectChunks, serverTool } from './test-utils'
+import type { AdapterYieldChunk } from '../src/utilities/adapter-yield-chunk'
+import type { ModelMessage, StreamChunk, TextOptions } from '../src/types'
+
+function textOf(chunks: Array<StreamChunk>) {
+  return chunks
+    .flatMap((chunk) =>
+      chunk.type === EventType.TEXT_MESSAGE_CONTENT ? [chunk.delta] : [],
+    )
+    .join('')
+}
+
+function runError(chunks: Array<StreamChunk>) {
+  return chunks.find((chunk) => chunk.type === EventType.RUN_ERROR)
+}
+
+const logger = resolveDebugOption(false)
+
+function request(
+  messages: Array<ModelMessage>,
+  extra: Omit<TextOptions, 'model' | 'messages' | 'logger'> = {},
+) {
+  const options: TextOptions = {
+    model: 'fake-model',
+    messages,
+    logger,
+    ...extra,
+  }
+  return options
+}
+
+/** The adapter's own events, before `chat()` normalizes them. */
+async function adapterEvents(
+  fake: ReturnType<typeof fakeText>,
+  options: TextOptions,
+) {
+  const events: Array<AdapterYieldChunk> = []
+  for await (const event of fake.chatStream(options)) events.push(event)
+  return events
+}
+
+function finished(events: Array<AdapterYieldChunk>) {
+  return events.find((event) => event.type === EventType.RUN_FINISHED)
+}
+
+const hi: Array<ModelMessage> = [{ role: 'user', content: 'Hi' }]
+
+describe('fakeText', () => {
+  it('answers chat() from the queue', async () => {
+    const fake = fakeText()
+    fake.setResponses([{ text: 'Hello there' }])
+
+    const chunks = await collectChunks(chat({ adapter: fake, messages: hi }))
+
+    expect(textOf(chunks)).toBe('Hello there')
+    expect(fake.state.callCount).toBe(1)
+    expect(fake.pendingResponses()).toBe(0)
+  })
+
+  it('builds an answer with a factory that gets the request and the state', async () => {
+    const fake = fakeText()
+    fake.setResponses([
+      ({ request, state }) => ({
+        text: `${request.messages.length} messages, call ${state.callCount}`,
+      }),
+    ])
+
+    const chunks = await collectChunks(chat({ adapter: fake, messages: hi }))
+
+    expect(textOf(chunks)).toBe('1 messages, call 1')
+  })
+
+  it('calls tools, then answers with the next response', async () => {
+    const fake = fakeText()
+    let seen: unknown
+    const weather = serverTool('weather', (input) => {
+      seen = input
+      return 'sunny'
+    })
+    fake.setResponses([
+      { toolCalls: [{ name: 'weather', input: { city: 'Oslo' } }] },
+      { text: 'It is sunny.' },
+    ])
+
+    const chunks = await collectChunks(
+      chat({ adapter: fake, messages: hi, tools: [weather] }),
+    )
+
+    expect(seen).toEqual({ city: 'Oslo' })
+    expect(textOf(chunks)).toBe('It is sunny.')
+    expect(fake.state.callCount).toBe(2)
+  })
+
+  it('fails with a RUN_ERROR when the queue is empty or a response is an error', async () => {
+    const empty = fakeText()
+    const failing = fakeText()
+    failing.setResponses([{ error: 'prompt is too long' }])
+
+    const emptyChunks = await collectChunks(
+      chat({ adapter: empty, messages: hi }),
+    )
+    const failingChunks = await collectChunks(
+      chat({ adapter: failing, messages: hi }),
+    )
+
+    expect(runError(emptyChunks)).toMatchObject({
+      message: 'No more fake responses queued',
+    })
+    expect(runError(failingChunks)).toMatchObject({
+      message: 'prompt is too long',
+    })
+  })
+
+  it('replaces the queue with setResponses and extends it with appendResponses', () => {
+    const fake = fakeText()
+    fake.setResponses([{ text: 'a' }, { text: 'b' }])
+    fake.setResponses([{ text: 'c' }])
+    fake.appendResponses([{ text: 'd' }])
+
+    expect(fake.pendingResponses()).toBe(2)
+  })
+
+  it('estimates usage as ceil(characters / 4) over the request and the answer', async () => {
+    const fake = fakeText()
+    fake.setResponses([{ text: 'Hello' }])
+
+    const events = await adapterEvents(
+      fake,
+      request([{ role: 'user', content: 'abcd' }], {
+        systemPrompts: ['Be brief.'],
+      }),
+    )
+
+    // "system:Be brief.\nuser:abcd" is 26 characters, "Hello" is 5.
+    expect(finished(events)).toMatchObject({
+      finishReason: 'stop',
+      usage: { promptTokens: 7, completionTokens: 2, totalTokens: 9 },
+    })
+  })
+
+  it('counts an image by its kind, type, and size', async () => {
+    const fake = fakeText({ input: ['text', 'image'] })
+    fake.setResponses([{ text: 'A cat.' }])
+
+    const events = await adapterEvents(
+      fake,
+      request([
+        {
+          role: 'user',
+          content: [
+            {
+              type: 'image',
+              source: {
+                type: 'data',
+                value: 'aGVsbG8=',
+                mimeType: 'image/png',
+              },
+            },
+          ],
+        },
+      ]),
+    )
+
+    // "user:[image:image/png:8]" is 24 characters.
+    expect(finished(events)).toMatchObject({ usage: { promptTokens: 6 } })
+    expect(fake.inputModalities).toEqual(['text', 'image'])
+  })
+
+  it('estimates cache reads from the previous request of the same thread', async () => {
+    const fake = fakeText({ cache: true })
+    fake.setResponses([{ text: 'One' }, { text: 'Two' }])
+    const first: Array<ModelMessage> = [{ role: 'user', content: 'abcdefgh' }]
+    const second: Array<ModelMessage> = [
+      ...first,
+      { role: 'assistant', content: 'One' },
+      { role: 'user', content: 'ijkl' },
+    ]
+
+    const firstRun = await adapterEvents(
+      fake,
+      request(first, { threadId: 't' }),
+    )
+    const secondRun = await adapterEvents(
+      fake,
+      request(second, { threadId: 't' }),
+    )
+
+    // The second request is 37 characters (10 tokens). Its first 13
+    // characters, "user:abcdefgh", match the first request: 3 cached tokens.
+    expect(finished(firstRun)).toMatchObject({
+      usage: { promptTokensDetails: { cachedTokens: 0, cacheWriteTokens: 4 } },
+    })
+    expect(finished(secondRun)).toMatchObject({
+      usage: {
+        promptTokens: 10,
+        promptTokensDetails: { cachedTokens: 3, cacheWriteTokens: 7 },
+      },
+    })
+  })
+
+  it('streams text in 4-character chunks, at tokensPerSecond', async () => {
+    const fake = fakeText({ tokensPerSecond: 50 })
+    fake.setResponses([{ text: 'abcdefgh' }])
+
+    const started = Date.now()
+    const events = await adapterEvents(fake, request(hi))
+
+    const deltas = events.flatMap((event) =>
+      event.type === EventType.TEXT_MESSAGE_CONTENT ? [event.delta] : [],
+    )
+    expect(deltas).toEqual(['abcd', 'efgh'])
+    expect(Date.now() - started).toBeGreaterThanOrEqual(35)
+  })
+
+  it('stops streaming when the request aborts', async () => {
+    const fake = fakeText({ tokensPerSecond: 100 })
+    fake.setResponses([{ text: 'abcdefghijkl' }])
+    const abortController = new AbortController()
+
+    const deltas: Array<string> = []
+    for await (const event of fake.chatStream(
+      request(hi, { abortController }),
+    )) {
+      if (event.type === EventType.TEXT_MESSAGE_CONTENT) {
+        deltas.push(event.delta)
+        abortController.abort()
+      }
+    }
+
+    expect(deltas).toEqual(['abcd'])
+  })
+
+  it('answers structured output with the next response as JSON', async () => {
+    const fake = fakeText()
+    fake.setResponses([{ text: '{"city":"Oslo"}' }])
+
+    const result = await fake.structuredOutput({
+      chatOptions: request(hi),
+      outputSchema: { type: 'object' },
+    })
+
+    expect(result.data).toEqual({ city: 'Oslo' })
+  })
+
+  it('keeps the model id and the context window', () => {
+    const fake = fakeText({ model: 'tiny', contextWindow: 8_000 })
+
+    expect(fake.model).toBe('tiny')
+    expect(fake.contextWindow).toBe(8_000)
+  })
+})
diff --git a/packages/ai/vite.config.ts b/packages/ai/vite.config.ts
index 4b0c49f007..b62cf0e722 100644
--- a/packages/ai/vite.config.ts
+++ b/packages/ai/vite.config.ts
@@ -37,6 +37,7 @@ export default mergeConfig(
       './src/middlewares/index.ts',
       './src/middlewares/otel.ts',
       './src/adapter-internals.ts',
+      './src/testing.ts',
       './src/byok.ts',
       './src/byok/server.ts',
     ],

From ca2a9dfd2fcd5957993e57755352b4e7e664e8a1 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 19:15:39 +0200
Subject: [PATCH 105/286] feat(ai-cloudflare): cloudflareBindingFetch for
 anthropic/ and openai/ gateway models

A fetch for anthropicText and openaiText that sends their requests through env.AI.run to the AI Gateway anthropic/ and openai/ models, with request headers such as anthropic-beta as extraHeaders.
---
 .changeset/cloudflare-binding-fetch.md        |   9 +
 docs/adapters/cloudflare.md                   |  39 ++++
 packages/ai-cloudflare/src/index.ts           |   5 +
 packages/ai-cloudflare/src/utils/fetch.ts     |  83 ++++++++
 .../tests/cloudflare-adapter.test.ts          | 120 +++++++++++
 .../src/routes/api.cloudflare-binding-wire.ts | 200 ++++++++++++++++++
 .../e2e/tests/cloudflare-binding-wire.spec.ts |  56 +++++
 7 files changed, 512 insertions(+)
 create mode 100644 .changeset/cloudflare-binding-fetch.md
 create mode 100644 testing/e2e/src/routes/api.cloudflare-binding-wire.ts
 create mode 100644 testing/e2e/tests/cloudflare-binding-wire.spec.ts

diff --git a/.changeset/cloudflare-binding-fetch.md b/.changeset/cloudflare-binding-fetch.md
new file mode 100644
index 0000000000..3800e255f7
--- /dev/null
+++ b/.changeset/cloudflare-binding-fetch.md
@@ -0,0 +1,9 @@
+---
+'@tanstack/ai-cloudflare': minor
+---
+
+Add `cloudflareBindingFetch({ binding, vendor, gateway })`. It sends the requests of `anthropicText` or `openaiText` through the Workers AI binding (`env.AI.run`) to the AI Gateway `anthropic/...` and `openai/...` models, so a Worker can use Claude and GPT with no provider key.
+
+- `vendor: 'anthropic'` carries Anthropic Messages requests, and `vendor: 'openai'` carries OpenAI Responses requests.
+- The request body goes to `env.AI.run('<vendor>/<model>', body)`. Headers such as `anthropic-beta` go along as `extraHeaders`, and the SDK's auth and transport headers are dropped.
+- A Cloudflare error body is rewrapped so the SDK reports its message.
diff --git a/docs/adapters/cloudflare.md b/docs/adapters/cloudflare.md
index bce766fbc0..ae500a5e66 100644
--- a/docs/adapters/cloudflare.md
+++ b/docs/adapters/cloudflare.md
@@ -151,6 +151,45 @@ The first argument is the provider slug from your gateway dashboard (`openai`, `
 
 The `ts-react-chat` example does this. Set `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_API_TOKEN`, and `CLOUDFLARE_AI_GATEWAY_ID` in its `.env`, and the Cloudflare, OpenAI, Anthropic, and Groq models in its picker all go through your gateway.
 
+### Claude and GPT from a Worker
+
+Inside a Worker, the AI Gateway `anthropic/...` and `openai/...` models use their provider's own API, not Chat Completions. Keep the provider adapter, and give it `cloudflareBindingFetch` as its `fetch`. The binding signs the requests, so the Worker needs no provider key:
+
+```typescript
+import { chat, toServerSentEventsResponse } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+import { cloudflareBindingFetch } from "@tanstack/ai-cloudflare";
+import type { Ai } from "@cloudflare/workers-types";
+
+interface Env {
+  AI: Ai;
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const { messages } = await request.json();
+
+    const adapter = anthropicText("claude-opus-5-5", {
+      // The SDK needs a value here. The binding does not use it.
+      apiKey: "cloudflare-binding",
+      fetch: cloudflareBindingFetch({
+        binding: env.AI,
+        vendor: "anthropic",
+        gateway: { id: "default" },
+      }),
+    });
+
+    const stream = chat({ adapter, messages, reasoning: "high" });
+    return toServerSentEventsResponse(stream);
+  },
+};
+```
+
+- `vendor: "anthropic"` sends Anthropic Messages requests to `anthropic/<model>`. Use it with `anthropicText`.
+- `vendor: "openai"` sends OpenAI Responses requests to `openai/<model>`. Use it with `openaiText`.
+- The adapter keeps all of its options: `chat({ reasoning })`, tools, `cache_control` for prompt caching, and Anthropic betas, which go out as the `anthropic-beta` header.
+- For `@cf/...` models and other gateway vendors, keep `createCloudflareText` with `binding: env.AI`.
+
 ## Bring your own key
 
 Two different things go by this name. Both work.
diff --git a/packages/ai-cloudflare/src/index.ts b/packages/ai-cloudflare/src/index.ts
index ed2986deea..396680687d 100644
--- a/packages/ai-cloudflare/src/index.ts
+++ b/packages/ai-cloudflare/src/index.ts
@@ -55,6 +55,11 @@ export {
 
 export { cloudflareGateway, type CloudflareGatewayTarget } from './gateway'
 
+export {
+  cloudflareBindingFetch,
+  type CloudflareBindingFetchOptions,
+} from './utils/fetch'
+
 export type {
   CloudflareBindingConfig,
   CloudflareConfig,
diff --git a/packages/ai-cloudflare/src/utils/fetch.ts b/packages/ai-cloudflare/src/utils/fetch.ts
index b1b3e95678..494fd942fb 100644
--- a/packages/ai-cloudflare/src/utils/fetch.ts
+++ b/packages/ai-cloudflare/src/utils/fetch.ts
@@ -123,6 +123,89 @@ export function createBindingFetch(
   }
 }
 
+/** Options of {@link cloudflareBindingFetch}. */
+export interface CloudflareBindingFetchOptions {
+  /** The Workers AI binding, `env.AI`. */
+  binding: Ai
+  /**
+   * The AI Gateway vendor of the model. `'anthropic'` carries Anthropic
+   * Messages requests (`anthropicText`), and `'openai'` carries OpenAI
+   * Responses requests (`openaiText`).
+   */
+  vendor: 'anthropic' | 'openai'
+  /** AI Gateway options, passed to `env.AI.run`. */
+  gateway?: CloudflareGatewayOptions
+}
+
+// The SDK's transport and auth headers. The binding authenticates by itself.
+const SDK_HEADERS = new Set([
+  'x-api-key',
+  'authorization',
+  'anthropic-version',
+  'user-agent',
+  'content-type',
+  'accept',
+  'content-length',
+])
+
+function forwardedHeaders(headers: HeadersInit | undefined) {
+  const forwarded: Record<string, string> = {}
+  for (const [name, value] of new Headers(headers)) {
+    if (!SDK_HEADERS.has(name) && !name.startsWith('x-stainless-')) {
+      forwarded[name] = value
+    }
+  }
+  return forwarded
+}
+
+/**
+ * A `fetch` that sends the requests of the Anthropic or OpenAI SDK through the
+ * Workers AI binding, to the AI Gateway `anthropic/…` or `openai/…` models.
+ * Pass it as `fetch` to `anthropicText` or `openaiText`. No provider API key
+ * is needed: the binding authenticates.
+ *
+ * The request body goes to `env.AI.run('<vendor>/<model>', body)`. Headers
+ * such as `anthropic-beta` go along as `extraHeaders`.
+ *
+ * @example
+ * ```ts
+ * const adapter = anthropicText('claude-opus-5-5', {
+ *   apiKey: 'cloudflare-binding',
+ *   fetch: cloudflareBindingFetch({ binding: env.AI, vendor: 'anthropic' }),
+ * })
+ * ```
+ */
+export function cloudflareBindingFetch(
+  options: CloudflareBindingFetchOptions,
+): FetchLike {
+  const { binding, vendor, gateway } = options
+  // `Ai` is typed against the bundled catalog; gateway ids are outside it.
+  const run = binding.run.bind(binding) as (
+    model: string,
+    inputs: Record<string, unknown>,
+    options: Record<string, unknown>,
+  ) => Promise<unknown>
+  const prefix = `${vendor}/`
+  return async (_input, init) => {
+    const { model, ...body } = JSON.parse(
+      typeof init?.body === 'string' ? init.body : '{}',
+    ) as { model?: string } & Record<string, unknown>
+    const id = model ?? ''
+    const extraHeaders = forwardedHeaders(init?.headers)
+    const response = (await run(
+      id.startsWith(prefix) ? id : prefix + id,
+      body,
+      {
+        returnRawResponse: true,
+        ...(gateway && { gateway }),
+        ...(Object.keys(extraHeaders).length > 0 && { extraHeaders }),
+        ...(init?.signal && { signal: init.signal }),
+      },
+    )) as Response
+    return response.ok ? response : await normalizeErrorResponse(response)
+  }
+}
+
 /** Wraps a REST fetch so responses get the same error and trailer fixes. */
 export function createRestFetch(baseFetch: FetchLike | undefined): FetchLike {
   const fetchImpl = baseFetch ?? fetch
diff --git a/packages/ai-cloudflare/tests/cloudflare-adapter.test.ts b/packages/ai-cloudflare/tests/cloudflare-adapter.test.ts
index 37336ff53b..60cc0ec6f1 100644
--- a/packages/ai-cloudflare/tests/cloudflare-adapter.test.ts
+++ b/packages/ai-cloudflare/tests/cloudflare-adapter.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
 import {
+  cloudflareBindingFetch,
   cloudflareGateway,
   createCloudflareEmbedding,
   createCloudflareImage,
@@ -569,3 +570,122 @@ describe('cloudflareGateway', () => {
     )
   })
 })
+
+describe('cloudflareBindingFetch', () => {
+  /** A request the way the Anthropic and OpenAI SDKs send it. */
+  function sdkRequest(model: string, headers: Record<string, string> = {}) {
+    return {
+      method: 'POST',
+      headers: {
+        'x-api-key': 'cloudflare-binding',
+        authorization: 'Bearer cloudflare-binding',
+        'anthropic-version': '2023-06-01',
+        'content-type': 'application/json',
+        accept: 'application/json',
+        'user-agent': 'Anthropic/JS',
+        'x-stainless-os': 'Windows',
+        ...headers,
+      },
+      body: JSON.stringify({
+        model,
+        stream: true,
+        system: 'Be brief.',
+        messages: [{ role: 'user', content: 'Hi' }],
+        tools: [{ name: 'lookup' }],
+      }),
+    }
+  }
+
+  it('sends an anthropic/ request through env.AI.run with its betas as a header', async () => {
+    const answer = sse(['[DONE]'])
+    const { binding, run } = fakeBinding(() => answer)
+    const fetchImpl = cloudflareBindingFetch({
+      binding,
+      vendor: 'anthropic',
+      gateway: { id: 'gw' },
+    })
+
+    const response = await fetchImpl(
+      'https://api.anthropic.com/v1/messages',
+      sdkRequest('claude-opus-5-5', {
+        'anthropic-beta':
+          'interleaved-thinking-2025-05-14,files-api-2025-04-14',
+      }),
+    )
+
+    expect(response).toBe(answer)
+    expect(run.mock.calls[0]).toEqual([
+      'anthropic/claude-opus-5-5',
+      {
+        stream: true,
+        system: 'Be brief.',
+        messages: [{ role: 'user', content: 'Hi' }],
+        tools: [{ name: 'lookup' }],
+      },
+      {
+        returnRawResponse: true,
+        gateway: { id: 'gw' },
+        extraHeaders: {
+          'anthropic-beta':
+            'interleaved-thinking-2025-05-14,files-api-2025-04-14',
+        },
+      },
+    ])
+  })
+
+  it('keeps a model id that already has the vendor prefix, and passes the signal', async () => {
+    const { binding, run } = fakeBinding(() => sse(['[DONE]']))
+    const fetchImpl = cloudflareBindingFetch({ binding, vendor: 'openai' })
+    const controller = new AbortController()
+
+    await fetchImpl('https://api.openai.com/v1/responses', {
+      ...sdkRequest('openai/gpt-6.1-sol'),
+      signal: controller.signal,
+    })
+
+    const [model, , options] = run.mock.calls[0]!
+    expect(model).toBe('openai/gpt-6.1-sol')
+    expect(options).toEqual({
+      returnRawResponse: true,
+      signal: controller.signal,
+    })
+  })
+
+  it('rewraps a Cloudflare error body so the SDK can read it', async () => {
+    const { binding } = fakeBinding(
+      () =>
+        new Response(
+          JSON.stringify({
+            errors: [{ code: 5007, message: 'No such model' }],
+          }),
+          { status: 400, headers: { 'content-type': 'application/json' } },
+        ),
+    )
+    const fetchImpl = cloudflareBindingFetch({ binding, vendor: 'anthropic' })
+
+    const response = await fetchImpl(
+      'https://api.anthropic.com/v1/messages',
+      sdkRequest('claude-nope'),
+    )
+
+    expect(response.status).toBe(400)
+    expect(await response.json()).toEqual({
+      error: { message: 'No such model', type: 'cloudflare_error', code: 5007 },
+    })
+  })
+
+  it('leaves any @cf/ model id on cloudflareText, with no model metadata', async () => {
+    const { binding, run } = fakeBinding(() => sse(chatStreamEvents))
+    const adapter = createCloudflareText('@cf/acme/unlisted-model', { binding })
+
+    await collect(
+      adapter.chatStream({
+        model: '@cf/acme/unlisted-model',
+        messages: [{ role: 'user', content: 'Hi' }],
+        logger,
+      }),
+    )
+
+    expect(run.mock.calls[0]?.[0]).toBe('@cf/acme/unlisted-model')
+  })
+})
diff --git a/testing/e2e/src/routes/api.cloudflare-binding-wire.ts b/testing/e2e/src/routes/api.cloudflare-binding-wire.ts
new file mode 100644
index 0000000000..638bdf8d20
--- /dev/null
+++ b/testing/e2e/src/routes/api.cloudflare-binding-wire.ts
@@ -0,0 +1,200 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toolDefinition } from '@tanstack/ai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+import { cloudflareBindingFetch } from '@tanstack/ai-cloudflare'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+type RunCall = {
+  model: string
+  inputs: Record<string, unknown>
+  options: Record<string, unknown>
+}
+
+function sse(events: Array<Record<string, unknown>>) {
+  return new Response(
+    events
+      .map(
+        (event) => `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`,
+      )
+      .join(''),
+    { status: 200, headers: { 'Content-Type': 'text/event-stream' } },
+  )
+}
+
+/** A Claude answer, as Anthropic Messages streams it. */
+const claudeAnswer = [
+  {
+    type: 'message_start',
+    message: {
+      id: 'msg_binding',
+      type: 'message',
+      role: 'assistant',
+      content: [],
+      model: 'claude-opus-5-5',
+      stop_reason: null,
+      stop_sequence: null,
+      usage: { input_tokens: 5, output_tokens: 0 },
+    },
+  },
+  {
+    type: 'content_block_start',
+    index: 0,
+    content_block: { type: 'text', text: '' },
+  },
+  {
+    type: 'content_block_delta',
+    index: 0,
+    delta: { type: 'text_delta', text: 'Hi from Claude.' },
+  },
+  { type: 'content_block_stop', index: 0 },
+  {
+    type: 'message_delta',
+    delta: { stop_reason: 'end_turn', stop_sequence: null },
+    usage: { output_tokens: 4 },
+  },
+  { type: 'message_stop' },
+]
+
+/** A GPT answer, as OpenAI Responses streams it. */
+const gptAnswer = [
+  {
+    type: 'response.created',
+    response: {
+      id: 'resp_binding',
+      object: 'response',
+      status: 'in_progress',
+      model: 'gpt-6.1-sol',
+      output: [],
+    },
+  },
+  {
+    type: 'response.completed',
+    response: {
+      id: 'resp_binding',
+      object: 'response',
+      status: 'completed',
+      model: 'gpt-6.1-sol',
+      output: [
+        {
+          id: 'msg_binding',
+          type: 'message',
+          role: 'assistant',
+          status: 'completed',
+          content: [
+            { type: 'output_text', text: 'Hi from GPT.', annotations: [] },
+          ],
+        },
+      ],
+      usage: { input_tokens: 5, output_tokens: 4, total_tokens: 9 },
+    },
+  },
+]
+
+/** A stand-in for `env.AI` that records each `run` call. */
+function fakeWorkersAi() {
+  const calls: Array<RunCall> = []
+  const binding = {
+    run: async (
+      model: string,
+      inputs: Record<string, unknown>,
+      options: Record<string, unknown>,
+    ) => {
+      calls.push({ model, inputs, options })
+      return model.startsWith('anthropic/') ? sse(claudeAnswer) : sse(gptAnswer)
+    },
+  }
+  return { calls, binding }
+}
+
+const lookup = toolDefinition({
+  name: 'lookup',
+  description: 'Look something up',
+  inputSchema: z.object({ query: z.string() }),
+})
+
+async function answerText(stream: AsyncIterable<{ type: string }>) {
+  let text = ''
+  for await (const chunk of stream) {
+    if (chunk.type === 'TEXT_MESSAGE_CONTENT' && 'delta' in chunk) {
+      text += String(chunk.delta)
+    }
+  }
+  return text
+}
+
+/**
+ * The real Anthropic and OpenAI adapters, sending through
+ * `cloudflareBindingFetch` to a fake `env.AI`. Returns what each `run` call
+ * got and the streamed answers.
+ */
+export const Route = createFileRoute('/api/cloudflare-binding-wire')({
+  server: {
+    handlers: {
+      POST: async () => {
+        try {
+          const workersAi = fakeWorkersAi()
+          // The real binding exists only inside a Worker. The stand-in has the
+          // one method the fetch calls.
+          const binding = workersAi.binding as unknown as Parameters<
+            typeof cloudflareBindingFetch
+          >[0]['binding']
+
+          const claudeText = await answerText(
+            chat({
+              adapter: anthropicText('claude-opus-5-5', {
+                apiKey: 'cloudflare-binding',
+                fetch: cloudflareBindingFetch({
+                  binding,
+                  vendor: 'anthropic',
+                  gateway: { id: 'e2e-gateway' },
+                }),
+              }),
+              systemPrompts: ['Be brief.'],
+              messages: [{ role: 'user', content: 'Hi' }],
+              tools: [lookup],
+              reasoning: 'high',
+            }),
+          )
+
+          const gptText = await answerText(
+            chat({
+              adapter: openaiText('gpt-6.1-sol', {
+                apiKey: 'cloudflare-binding',
+                fetch: cloudflareBindingFetch({ binding, vendor: 'openai' }),
+              }),
+              systemPrompts: ['Be brief.'],
+              messages: [{ role: 'user', content: 'Hi' }],
+              tools: [lookup],
+              reasoning: 'high',
+            }),
+          )
+
+          return Response.json({
+            ok: true,
+            claudeText,
+            gptText,
+            calls: workersAi.calls.map((call) => ({
+              model: call.model,
+              modelInBody: 'model' in call.inputs,
+              betasInBody: 'betas' in call.inputs,
+              systemSent: JSON.stringify(call.inputs).includes('Be brief.'),
+              toolNames: Array.isArray(call.inputs.tools)
+                ? call.inputs.tools.map((tool: { name?: string }) => tool.name)
+                : [],
+              outputConfig: call.inputs.output_config,
+              reasoning: call.inputs.reasoning,
+              returnRawResponse: call.options.returnRawResponse,
+              gateway: call.options.gateway,
+            })),
+          })
+        } catch (error) {
+          return Response.json({
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+          })
+        }
+      },
+    },
+  },
+})
diff --git a/testing/e2e/tests/cloudflare-binding-wire.spec.ts b/testing/e2e/tests/cloudflare-binding-wire.spec.ts
new file mode 100644
index 0000000000..bba60f7037
--- /dev/null
+++ b/testing/e2e/tests/cloudflare-binding-wire.spec.ts
@@ -0,0 +1,56 @@
+import { test, expect } from './fixtures'
+
+/**
+ * Inside a Worker, `cloudflareBindingFetch` sends the requests of the real
+ * Anthropic and OpenAI adapters through `env.AI.run` to the AI Gateway
+ * `anthropic/…` and `openai/…` models. `/api/cloudflare-binding-wire` uses a
+ * fake `env.AI` and returns what each `run` call got.
+ */
+test.describe('cloudflare — gateway models through the Workers AI binding', () => {
+  test('Claude and GPT stream through env.AI.run', async ({ request }) => {
+    const response = await request.post('/api/cloudflare-binding-wire')
+    expect(response.ok()).toBe(true)
+    const result = (await response.json()) as {
+      ok: boolean
+      error?: string
+      claudeText: string
+      gptText: string
+      calls: Array<{
+        model: string
+        modelInBody: boolean
+        betasInBody: boolean
+        systemSent: boolean
+        toolNames: Array<string>
+        outputConfig?: { effort?: string }
+        reasoning?: { effort?: string }
+        returnRawResponse: boolean
+        gateway?: { id: string }
+      }>
+    }
+    if (!result.ok) throw new Error(`Route failed: ${result.error}`)
+
+    expect(result.claudeText).toBe('Hi from Claude.')
+    expect(result.gptText).toBe('Hi from GPT.')
+
+    const [claude, gpt] = result.calls
+    // The gateway id names the vendor. The body keeps the provider's own shape.
+    expect(claude).toMatchObject({
+      model: 'anthropic/claude-opus-5-5',
+      modelInBody: false,
+      betasInBody: false,
+      systemSent: true,
+      toolNames: ['lookup'],
+      outputConfig: { effort: 'high' },
+      returnRawResponse: true,
+      gateway: { id: 'e2e-gateway' },
+    })
+    expect(gpt).toMatchObject({
+      model: 'openai/gpt-6.1-sol',
+      modelInBody: false,
+      systemSent: true,
+      toolNames: ['lookup'],
+      reasoning: { effort: 'high' },
+      returnRawResponse: true,
+    })
+  })
+})

From 4b5e1660e374ee1bd2d34e57cb0d31fa7bdd52d9 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 19:15:42 +0200
Subject: [PATCH 106/286] docs: stop the agent loop from a tool, and the new
 testing page in the nav

---
 docs/chat/agentic-cycle.md | 53 ++++++++++++++++++++++++++++++++++++++
 docs/config.json           |  9 +++++--
 2 files changed, 60 insertions(+), 2 deletions(-)

diff --git a/docs/chat/agentic-cycle.md b/docs/chat/agentic-cycle.md
index 14e52b84ff..2fd6945d02 100644
--- a/docs/chat/agentic-cycle.md
+++ b/docs/chat/agentic-cycle.md
@@ -264,3 +264,56 @@ export async function POST(request: Request) {
 ```
 
 Place this **before** `toolCacheMiddleware` so over-budget skips win over cache hits. See [`onShouldContinue`](../advanced/middleware#onshouldcontinue) for the hook contract.
+
+### Stop the loop from a tool (middleware recipe)
+
+Some tools end the work, for example a `final_answer` tool. After the model calls it, the model must not get another turn. Stop the loop with middleware:
+
+- **`onToolPhaseComplete`** sees every result of the turn.
+- **`onShouldContinue`** returns `false` to stop after the tool results.
+
+```typescript
+import {
+  chat,
+  toolDefinition,
+  toServerSentEventsResponse,
+  type ChatMiddleware,
+} from "@tanstack/ai";
+import { openaiText } from "@tanstack/ai-openai";
+import { z } from "zod";
+
+const finalAnswer = toolDefinition({
+  name: "final_answer",
+  description: "Give the final answer to the user",
+  inputSchema: z.object({ answer: z.string() }),
+}).server(async ({ answer }) => ({ answer }));
+
+/** App-owned policy: stop when every result of a turn comes from a stop tool. */
+function stopAfter(toolNames: Array<string>): ChatMiddleware {
+  let stop = false;
+  return {
+    name: "stop-after-tool",
+    onToolPhaseComplete(_ctx, info) {
+      stop =
+        info.results.length > 0 &&
+        info.results.every((result) => toolNames.includes(result.toolName));
+    },
+    onShouldContinue() {
+      return stop ? false : undefined;
+    },
+  };
+}
+
+export async function POST(request: Request) {
+  const { messages } = await request.json();
+  const stream = chat({
+    adapter: openaiText("gpt-6.1-sol"),
+    messages,
+    tools: [finalAnswer],
+    middleware: [stopAfter(["final_answer"])],
+  });
+  return toServerSentEventsResponse(stream);
+}
+```
+
+A turn that also calls other tools goes on, so the model can still use their results.
diff --git a/docs/config.json b/docs/config.json
index 94dde2a568..9dde9c5eeb 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -172,7 +172,7 @@
           "label": "Agentic Cycle",
           "to": "chat/agentic-cycle",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-21"
+          "updatedAt": "2026-09-30"
         },
         {
           "label": "Thinking & Reasoning",
@@ -330,7 +330,7 @@
           "label": "Compaction",
           "to": "advanced/compaction",
           "addedAt": "2026-08-24",
-          "updatedAt": "2026-08-27"
+          "updatedAt": "2026-09-30"
         }
       ],
       "tab": "guides"
@@ -1254,6 +1254,11 @@
           "addedAt": "2026-05-25",
           "updatedAt": "2026-09-30"
         },
+        {
+          "label": "Test with a Fake Model",
+          "to": "advanced/testing",
+          "addedAt": "2026-09-30"
+        },
         {
           "label": "Approval Flow Processing",
           "to": "architecture/approval-flow-processing",

From 8a461decffbb43d69b2a8b9df64bb3f8d0a8d512 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 30 Sep 2026 19:30:54 +0200
Subject: [PATCH 107/286] fix(ai-cloudflare): show cloudflareBindingFetch with
 createAnthropicChat and createOpenaiChat

anthropicText and openaiText read the key from the environment only, so the binding examples use the factories that take a key argument. The E2E route for the binding now runs, and the route tree has it.
---
 .changeset/cloudflare-binding-fetch.md        |  2 +-
 docs/adapters/cloudflare.md                   | 11 ++++----
 packages/ai-cloudflare/src/utils/fetch.ts     | 11 ++++----
 testing/e2e/src/routeTree.gen.ts              | 22 ++++++++++++++++
 .../src/routes/api.cloudflare-binding-wire.ts | 26 ++++++++++---------
 5 files changed, 47 insertions(+), 25 deletions(-)

diff --git a/.changeset/cloudflare-binding-fetch.md b/.changeset/cloudflare-binding-fetch.md
index 3800e255f7..940b0b9262 100644
--- a/.changeset/cloudflare-binding-fetch.md
+++ b/.changeset/cloudflare-binding-fetch.md
@@ -2,7 +2,7 @@
 '@tanstack/ai-cloudflare': minor
 ---
 
-Add `cloudflareBindingFetch({ binding, vendor, gateway })`. It sends the requests of `anthropicText` or `openaiText` through the Workers AI binding (`env.AI.run`) to the AI Gateway `anthropic/...` and `openai/...` models, so a Worker can use Claude and GPT with no provider key.
+Add `cloudflareBindingFetch({ binding, vendor, gateway })`. It sends the requests of the Anthropic and OpenAI text adapters (`createAnthropicChat`, `createOpenaiChat`) through the Workers AI binding (`env.AI.run`) to the AI Gateway `anthropic/...` and `openai/...` models, so a Worker can use Claude and GPT with no provider key.
 
 - `vendor: 'anthropic'` carries Anthropic Messages requests, and `vendor: 'openai'` carries OpenAI Responses requests.
 - The request body goes to `env.AI.run('<vendor>/<model>', body)`. Headers such as `anthropic-beta` go along as `extraHeaders`, and the SDK's auth and transport headers are dropped.
diff --git a/docs/adapters/cloudflare.md b/docs/adapters/cloudflare.md
index ae500a5e66..cd892eeec3 100644
--- a/docs/adapters/cloudflare.md
+++ b/docs/adapters/cloudflare.md
@@ -157,7 +157,7 @@ Inside a Worker, the AI Gateway `anthropic/...` and `openai/...` models use thei
 
 ```typescript
 import { chat, toServerSentEventsResponse } from "@tanstack/ai";
-import { anthropicText } from "@tanstack/ai-anthropic";
+import { createAnthropicChat } from "@tanstack/ai-anthropic";
 import { cloudflareBindingFetch } from "@tanstack/ai-cloudflare";
 import type { Ai } from "@cloudflare/workers-types";
 
@@ -169,9 +169,8 @@ export default {
   async fetch(request: Request, env: Env) {
     const { messages } = await request.json();
 
-    const adapter = anthropicText("claude-opus-5-5", {
-      // The SDK needs a value here. The binding does not use it.
-      apiKey: "cloudflare-binding",
+    // The SDK needs a key value. The binding does not use it.
+    const adapter = createAnthropicChat("claude-opus-5-5", "cloudflare-binding", {
       fetch: cloudflareBindingFetch({
         binding: env.AI,
         vendor: "anthropic",
@@ -185,8 +184,8 @@ export default {
 };
 ```
 
-- `vendor: "anthropic"` sends Anthropic Messages requests to `anthropic/<model>`. Use it with `anthropicText`.
-- `vendor: "openai"` sends OpenAI Responses requests to `openai/<model>`. Use it with `openaiText`.
+- `vendor: "anthropic"` sends Anthropic Messages requests to `anthropic/<model>`. Use it with `createAnthropicChat`.
+- `vendor: "openai"` sends OpenAI Responses requests to `openai/<model>`. Use it with `createOpenaiChat`.
 - The adapter keeps all of its options: `chat({ reasoning })`, tools, `cache_control` for prompt caching, and Anthropic betas, which go out as the `anthropic-beta` header.
 - For `@cf/...` models and other gateway vendors, keep `createCloudflareText` with `binding: env.AI`.
 
diff --git a/packages/ai-cloudflare/src/utils/fetch.ts b/packages/ai-cloudflare/src/utils/fetch.ts
index 494fd942fb..2aa4540f88 100644
--- a/packages/ai-cloudflare/src/utils/fetch.ts
+++ b/packages/ai-cloudflare/src/utils/fetch.ts
@@ -129,8 +129,8 @@ export interface CloudflareBindingFetchOptions {
   binding: Ai
   /**
    * The AI Gateway vendor of the model. `'anthropic'` carries Anthropic
-   * Messages requests (`anthropicText`), and `'openai'` carries OpenAI
-   * Responses requests (`openaiText`).
+   * Messages requests (`createAnthropicChat`), and `'openai'` carries OpenAI
+   * Responses requests (`createOpenaiChat`).
    */
   vendor: 'anthropic' | 'openai'
   /** AI Gateway options, passed to `env.AI.run`. */
@@ -161,16 +161,15 @@ function forwardedHeaders(headers: HeadersInit | undefined) {
 /**
  * A `fetch` that sends the requests of the Anthropic or OpenAI SDK through the
  * Workers AI binding, to the AI Gateway `anthropic/…` or `openai/…` models.
- * Pass it as `fetch` to `anthropicText` or `openaiText`. No provider API key
- * is needed: the binding authenticates.
+ * Pass it as `fetch` to `createAnthropicChat` or `createOpenaiChat`. The
+ * binding authenticates, so the key argument can be any placeholder.
  *
  * The request body goes to `env.AI.run('<vendor>/<model>', body)`. Headers
  * such as `anthropic-beta` go along as `extraHeaders`.
  *
  * @example
  * ```ts
- * const adapter = anthropicText('claude-opus-5-5', {
- *   apiKey: 'cloudflare-binding',
+ * const adapter = createAnthropicChat('claude-opus-5-5', 'cloudflare-binding', {
  *   fetch: cloudflareBindingFetch({ binding: env.AI, vendor: 'anthropic' }),
  * })
  * ```
diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index f83151c464..be8bc8fd24 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -115,6 +115,7 @@ import { Route as ApiDurableTakeoverRouteImport } from './routes/api.durable-tak
 import { Route as ApiDurableDeliveryRouteImport } from './routes/api.durable-delivery'
 import { Route as ApiDevtoolsMemoryRouteImport } from './routes/api.devtools-memory'
 import { Route as ApiCompactionWireRouteImport } from './routes/api.compaction-wire'
+import { Route as ApiCloudflareBindingWireRouteImport } from './routes/api.cloudflare-binding-wire'
 import { Route as ApiChatRouteImport } from './routes/api.chat'
 import { Route as ApiByteplusSeedance1080pWireRouteImport } from './routes/api.byteplus-seedance-1080p-wire'
 import { Route as ApiByokChatRouteImport } from './routes/api.byok-chat'
@@ -687,6 +688,12 @@ const ApiCompactionWireRoute = ApiCompactionWireRouteImport.update({
   path: '/api/compaction-wire',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiCloudflareBindingWireRoute =
+  ApiCloudflareBindingWireRouteImport.update({
+    id: '/api/cloudflare-binding-wire',
+    path: '/api/cloudflare-binding-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
 const ApiChatRoute = ApiChatRouteImport.update({
   id: '/api/chat',
   path: '/api/chat',
@@ -840,6 +847,7 @@ export interface FileRoutesByFullPath {
   '/api/byok-chat': typeof ApiByokChatRoute
   '/api/byteplus-seedance-1080p-wire': typeof ApiByteplusSeedance1080pWireRoute
   '/api/chat': typeof ApiChatRoute
+  '/api/cloudflare-binding-wire': typeof ApiCloudflareBindingWireRoute
   '/api/compaction-wire': typeof ApiCompactionWireRoute
   '/api/devtools-memory': typeof ApiDevtoolsMemoryRoute
   '/api/durable-delivery': typeof ApiDurableDeliveryRoute
@@ -968,6 +976,7 @@ export interface FileRoutesByTo {
   '/api/byok-chat': typeof ApiByokChatRoute
   '/api/byteplus-seedance-1080p-wire': typeof ApiByteplusSeedance1080pWireRoute
   '/api/chat': typeof ApiChatRoute
+  '/api/cloudflare-binding-wire': typeof ApiCloudflareBindingWireRoute
   '/api/compaction-wire': typeof ApiCompactionWireRoute
   '/api/devtools-memory': typeof ApiDevtoolsMemoryRoute
   '/api/durable-delivery': typeof ApiDurableDeliveryRoute
@@ -1097,6 +1106,7 @@ export interface FileRoutesById {
   '/api/byok-chat': typeof ApiByokChatRoute
   '/api/byteplus-seedance-1080p-wire': typeof ApiByteplusSeedance1080pWireRoute
   '/api/chat': typeof ApiChatRoute
+  '/api/cloudflare-binding-wire': typeof ApiCloudflareBindingWireRoute
   '/api/compaction-wire': typeof ApiCompactionWireRoute
   '/api/devtools-memory': typeof ApiDevtoolsMemoryRoute
   '/api/durable-delivery': typeof ApiDurableDeliveryRoute
@@ -1227,6 +1237,7 @@ export interface FileRouteTypes {
     | '/api/byok-chat'
     | '/api/byteplus-seedance-1080p-wire'
     | '/api/chat'
+    | '/api/cloudflare-binding-wire'
     | '/api/compaction-wire'
     | '/api/devtools-memory'
     | '/api/durable-delivery'
@@ -1355,6 +1366,7 @@ export interface FileRouteTypes {
     | '/api/byok-chat'
     | '/api/byteplus-seedance-1080p-wire'
     | '/api/chat'
+    | '/api/cloudflare-binding-wire'
     | '/api/compaction-wire'
     | '/api/devtools-memory'
     | '/api/durable-delivery'
@@ -1483,6 +1495,7 @@ export interface FileRouteTypes {
     | '/api/byok-chat'
     | '/api/byteplus-seedance-1080p-wire'
     | '/api/chat'
+    | '/api/cloudflare-binding-wire'
     | '/api/compaction-wire'
     | '/api/devtools-memory'
     | '/api/durable-delivery'
@@ -1612,6 +1625,7 @@ export interface RootRouteChildren {
   ApiByokChatRoute: typeof ApiByokChatRoute
   ApiByteplusSeedance1080pWireRoute: typeof ApiByteplusSeedance1080pWireRoute
   ApiChatRoute: typeof ApiChatRoute
+  ApiCloudflareBindingWireRoute: typeof ApiCloudflareBindingWireRoute
   ApiCompactionWireRoute: typeof ApiCompactionWireRoute
   ApiDevtoolsMemoryRoute: typeof ApiDevtoolsMemoryRoute
   ApiDurableDeliveryRoute: typeof ApiDurableDeliveryRoute
@@ -2434,6 +2448,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiCompactionWireRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/cloudflare-binding-wire': {
+      id: '/api/cloudflare-binding-wire'
+      path: '/api/cloudflare-binding-wire'
+      fullPath: '/api/cloudflare-binding-wire'
+      preLoaderRoute: typeof ApiCloudflareBindingWireRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/chat': {
       id: '/api/chat'
       path: '/api/chat'
@@ -2682,6 +2703,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiByokChatRoute: ApiByokChatRoute,
   ApiByteplusSeedance1080pWireRoute: ApiByteplusSeedance1080pWireRoute,
   ApiChatRoute: ApiChatRoute,
+  ApiCloudflareBindingWireRoute: ApiCloudflareBindingWireRoute,
   ApiCompactionWireRoute: ApiCompactionWireRoute,
   ApiDevtoolsMemoryRoute: ApiDevtoolsMemoryRoute,
   ApiDurableDeliveryRoute: ApiDurableDeliveryRoute,
diff --git a/testing/e2e/src/routes/api.cloudflare-binding-wire.ts b/testing/e2e/src/routes/api.cloudflare-binding-wire.ts
index 638bdf8d20..3fdf370c01 100644
--- a/testing/e2e/src/routes/api.cloudflare-binding-wire.ts
+++ b/testing/e2e/src/routes/api.cloudflare-binding-wire.ts
@@ -1,8 +1,8 @@
 import { createFileRoute } from '@tanstack/react-router'
 import { chat, toolDefinition } from '@tanstack/ai'
-import { anthropicText } from '@tanstack/ai-anthropic'
+import { createAnthropicChat } from '@tanstack/ai-anthropic'
 import { cloudflareBindingFetch } from '@tanstack/ai-cloudflare'
-import { openaiText } from '@tanstack/ai-openai'
+import { createOpenaiChat } from '@tanstack/ai-openai'
 import { z } from 'zod'
 
 type RunCall = {
@@ -142,14 +142,17 @@ export const Route = createFileRoute('/api/cloudflare-binding-wire')({
 
           const claudeText = await answerText(
             chat({
-              adapter: anthropicText('claude-opus-5-5', {
-                apiKey: 'cloudflare-binding',
-                fetch: cloudflareBindingFetch({
-                  binding,
-                  vendor: 'anthropic',
-                  gateway: { id: 'e2e-gateway' },
-                }),
-              }),
+              adapter: createAnthropicChat(
+                'claude-opus-5-5',
+                'cloudflare-binding',
+                {
+                  fetch: cloudflareBindingFetch({
+                    binding,
+                    vendor: 'anthropic',
+                    gateway: { id: 'e2e-gateway' },
+                  }),
+                },
+              ),
               systemPrompts: ['Be brief.'],
               messages: [{ role: 'user', content: 'Hi' }],
               tools: [lookup],
@@ -159,8 +162,7 @@ export const Route = createFileRoute('/api/cloudflare-binding-wire')({
 
           const gptText = await answerText(
             chat({
-              adapter: openaiText('gpt-6.1-sol', {
-                apiKey: 'cloudflare-binding',
+              adapter: createOpenaiChat('gpt-6.1-sol', 'cloudflare-binding', {
                 fetch: cloudflareBindingFetch({ binding, vendor: 'openai' }),
               }),
               systemPrompts: ['Be brief.'],

From 71c19da6419941d527b6695dbd690abab423e0ae Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 11:05:36 +0200
Subject: [PATCH 108/286] Revert the draft parallel-tools and redacted-thinking
 commits

main has the reviewed versions of both fixes (#1578 and #1579). The
next merge brings them in. Reverting the earlier drafts first stops the
merge from keeping draft-only parts, such as the per-tool `sequential`
flag that the review removed. The harness stack's `replay` tool field
stays.

This reverts 7b6126731 and bbe77969c.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/anthropic-thinking-replay.md       |  10 -
 .changeset/parallel-server-tools.md           |  10 -
 docs/advanced/middleware.md                   |  10 -
 docs/chat/thinking-content.md                 |   3 -
 docs/config.json                              |   8 +-
 docs/tools/tool-architecture.md               |   2 -
 docs/tools/tools.md                           |  44 ----
 packages/ai-anthropic/src/adapters/text.ts    |  31 ---
 .../tests/thinking-replay.test.ts             | 226 ----------------
 .../ai/src/activities/chat/agents/spawn.ts    |  33 ++-
 packages/ai/src/activities/chat/index.ts      |  15 +-
 packages/ai/src/activities/chat/messages.ts   |  13 +-
 .../chat/stream/message-updaters.ts           |   3 -
 .../src/activities/chat/stream/processor.ts   |   8 -
 .../ai/src/activities/chat/stream/types.ts    |   2 -
 .../src/activities/chat/tools/tool-calls.ts   |  82 +-----
 .../activities/chat/tools/tool-definition.ts  |   1 -
 packages/ai/src/types.ts                      |  24 +-
 .../ai/src/utilities/adapter-yield-chunk.ts   |   2 -
 packages/ai/src/utilities/ag-ui-wire.ts       |   3 -
 packages/ai/src/utilities/merge-streams.ts    |  34 ---
 .../src/utilities/normalize-stream-chunk.ts   |   1 -
 .../utilities/reasoning-encrypted-value.ts    |  10 +-
 packages/ai/tests/parallel-tools.test.ts      | 222 ----------------
 packages/ai/tests/redacted-thinking.test.ts   |  68 -----
 .../tools-test/parallel-server-timing.json    |  26 --
 testing/e2e/src/lib/tools-test-tools.ts       |  27 --
 testing/e2e/src/routeTree.gen.ts              |  22 --
 .../api.anthropic-redacted-thinking-wire.ts   | 241 ------------------
 .../anthropic-redacted-thinking-wire.spec.ts  |  40 ---
 .../tools-test/server-client-sequence.spec.ts |  34 ---
 31 files changed, 53 insertions(+), 1202 deletions(-)
 delete mode 100644 .changeset/anthropic-thinking-replay.md
 delete mode 100644 .changeset/parallel-server-tools.md
 delete mode 100644 packages/ai-anthropic/tests/thinking-replay.test.ts
 delete mode 100644 packages/ai/src/utilities/merge-streams.ts
 delete mode 100644 packages/ai/tests/parallel-tools.test.ts
 delete mode 100644 packages/ai/tests/redacted-thinking.test.ts
 delete mode 100644 testing/e2e/fixtures/tools-test/parallel-server-timing.json
 delete mode 100644 testing/e2e/src/routes/api.anthropic-redacted-thinking-wire.ts
 delete mode 100644 testing/e2e/tests/anthropic-redacted-thinking-wire.spec.ts

diff --git a/.changeset/anthropic-thinking-replay.md b/.changeset/anthropic-thinking-replay.md
deleted file mode 100644
index 495784e096..0000000000
--- a/.changeset/anthropic-thinking-replay.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-'@tanstack/ai': patch
-'@tanstack/ai-anthropic': patch
----
-
-Send Claude's thinking and tool errors back the way Claude sent them.
-
-- A tool message with `error` now sends `tool_result.is_error: true`, so Claude sees that the tool failed.
-- A `redacted_thinking` block is no longer dropped. It becomes a thinking part with `redacted: true`, an empty `content`, and the encrypted data in `signature`. The flag survives the stream, the UI messages, the wire, and stored threads, and the next request sends the block back as `{ type: 'redacted_thinking', data }`.
-- `ThinkingPart` and `ModelMessage['thinking']` have the new optional `redacted` field.
diff --git a/.changeset/parallel-server-tools.md b/.changeset/parallel-server-tools.md
deleted file mode 100644
index ad4ffec4b5..0000000000
--- a/.changeset/parallel-server-tools.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-'@tanstack/ai': minor
----
-
-Run the server tools of one model turn at the same time. `chat()` used to run them one after another, so a turn with several slow tools took as long as all of them together.
-
-- Every call is still prepared in call order (argument parse, input schema check, approval check, `onBeforeToolCall`). Then the server tools start together.
-- `onAfterToolCall` fires for each tool when it finishes. The model still gets the results in the order of its calls.
-- A tool that has not started when the run aborts does not start. It gets the error result "Operation aborted".
-- Opt out per run with `chat({ toolExecution: 'sequential' })`, or per tool with `toolDefinition({ sequential: true })`. A turn that calls a `sequential` tool runs all of its tools one at a time.
diff --git a/docs/advanced/middleware.md b/docs/advanced/middleware.md
index 0c16cf232c..f5a5a0ccfc 100644
--- a/docs/advanced/middleware.md
+++ b/docs/advanced/middleware.md
@@ -596,16 +596,6 @@ The `info` object provides:
 | `result` | `unknown` | Result (when `ok` is true) |
 | `error` | `unknown` | Error (when `ok` is false) |
 
-### Tool hook order in one turn
-
-When the model calls several server tools in one turn, the tools run at the same time:
-
-- `onBeforeToolCall` runs for each call in call order, before any tool starts.
-- `onAfterToolCall` runs for each tool when it finishes, so in finish order.
-- A tool that has not started when the run aborts does not run. `onAfterToolCall` gets `ok: false` with the error "Operation aborted".
-
-With `toolExecution: 'sequential'`, or a tool with `sequential: true` in the turn, each call finishes its `onBeforeToolCall`, its run, and its `onAfterToolCall` before the next call starts. See [Run tools one at a time](../tools/tools#run-tools-one-at-a-time).
-
 ### onUsage
 
 Called once per model iteration when the `RUN_FINISHED` chunk includes usage data. Receives the usage object directly.
diff --git a/docs/chat/thinking-content.md b/docs/chat/thinking-content.md
index 54baf701b6..2157f1e802 100644
--- a/docs/chat/thinking-content.md
+++ b/docs/chat/thinking-content.md
@@ -28,14 +28,11 @@ interface ThinkingPart {
   content: string;
   stepId?: string;
   signature?: string;
-  redacted?: boolean;
 }
 ```
 
 The `ThinkingPart` appears in `UIMessage.parts` alongside `TextPart` and `ToolCallPart` entries. As reasoning tokens arrive, its `content` accumulates token by token.
 
-Claude can also send a redacted thinking block. It is encrypted, so it has no text. It arrives as a `ThinkingPart` with `redacted: true`, an empty `content`, and the encrypted data in `signature`. Keep the part in your stored messages: the next request sends it back to Claude unchanged. In a UI, show a short placeholder such as "Thinking hidden" instead of the empty text.
-
 ## Enabling Thinking
 
 Turn thinking on with `reasoning` on `chat()`. It works the same on every provider:
diff --git a/docs/config.json b/docs/config.json
index 5c1ab18001..b80c280fd3 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -178,7 +178,7 @@
           "label": "Thinking & Reasoning",
           "to": "chat/thinking-content",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-09-30"
+          "updatedAt": "2026-08-21"
         },
         {
           "label": "Reasoning",
@@ -242,7 +242,7 @@
           "label": "Tools",
           "to": "tools/tools",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-09-30"
+          "updatedAt": "2026-08-21"
         },
         {
           "label": "Server Tools",
@@ -295,7 +295,7 @@
           "label": "Tool Architecture",
           "to": "tools/tool-architecture",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-09-30"
+          "updatedAt": "2026-08-17"
         }
       ],
       "tab": "guides"
@@ -307,7 +307,7 @@
           "label": "Middleware",
           "to": "advanced/middleware",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-09-30"
+          "updatedAt": "2026-09-25"
         },
         {
           "label": "Built-in Middleware",
diff --git a/docs/tools/tool-architecture.md b/docs/tools/tool-architecture.md
index 51c4fe66ef..a85306ade3 100644
--- a/docs/tools/tool-architecture.md
+++ b/docs/tools/tool-architecture.md
@@ -403,8 +403,6 @@ LLM calls:
 All execute simultaneously, then LLM generates comparison.
 ```
 
-The server tools of one model turn start together, and the model gets their results in the order of its calls. To run them one at a time, see [Run tools one at a time](./tools#run-tools-one-at-a-time).
-
 ## Best Practices
 
 ### Tool Design
diff --git a/docs/tools/tools.md b/docs/tools/tools.md
index 7ab1fe31bb..68f0a59d02 100644
--- a/docs/tools/tools.md
+++ b/docs/tools/tools.md
@@ -397,50 +397,6 @@ function CartChat() {
 4. **Result is returned** - To the model as a tool result message
 5. **Model continues** - Uses the result to generate a response
 
-## Run tools one at a time
-
-When the model calls several server tools in one turn, they start at the same time, and the model gets the results in the order of its calls. Some tools depend on each other, for example a tool that writes a file and a tool that runs the tests. They must not overlap.
-
-Set `sequential: true` on such a tool. A turn that calls it runs all of its tools one at a time:
-
-```ts group=sequential-tools
-import { chat, toolDefinition } from '@tanstack/ai'
-import { openaiText } from '@tanstack/ai-openai'
-import { z } from 'zod'
-
-const writeFile = toolDefinition({
-  name: 'write_file',
-  description: 'Write a file',
-  inputSchema: z.object({ path: z.string(), content: z.string() }),
-}).server(async ({ path }) => ({ written: path }))
-
-const runTests = toolDefinition({
-  name: 'run_tests',
-  description: 'Run the test suite',
-  inputSchema: z.object({}),
-  sequential: true,
-}).server(async () => ({ passed: true }))
-
-const stream = chat({
-  adapter: openaiText('gpt-6.1-sol'),
-  messages: [{ role: 'user', content: 'Fix the bug, then run the tests.' }],
-  tools: [writeFile, runTests],
-})
-```
-
-To run every tool of every turn one at a time, set `toolExecution` on `chat()`:
-
-```ts group=sequential-tools
-const orderedStream = chat({
-  adapter: openaiText('gpt-6.1-sol'),
-  messages: [{ role: 'user', content: 'Fix the bug, then run the tests.' }],
-  tools: [writeFile, runTests],
-  toolExecution: 'sequential',
-})
-```
-
-Client tools do not change: the client runs them as their calls arrive.
-
 ## Progress Events and Runtime Context
 
 A server tool's `.server()` implementation receives a second argument, the `ToolExecutionContext` — `{ context, toolCallId, emitCustomEvent }`. Use `emitCustomEvent` to stream typed progress to the client while the tool runs, and `context` to read request-scoped dependencies (auth, DB clients, etc.):
diff --git a/packages/ai-anthropic/src/adapters/text.ts b/packages/ai-anthropic/src/adapters/text.ts
index 58eaccd0c4..f8a1da9595 100644
--- a/packages/ai-anthropic/src/adapters/text.ts
+++ b/packages/ai-anthropic/src/adapters/text.ts
@@ -849,7 +849,6 @@ export class AnthropicTextAdapter<
                 : typeof toolContent === 'string'
                   ? toolContent
                   : '',
-              ...(message.error !== undefined && { is_error: true }),
             },
           ],
         })
@@ -978,13 +977,6 @@ export class AnthropicTextAdapter<
 
     for (const thinking of thinkingParts) {
       if (!thinking.signature) continue
-      if (thinking.redacted) {
-        contentBlocks.push({
-          type: 'redacted_thinking',
-          data: thinking.signature,
-        })
-        continue
-      }
       const block: ThinkingBlockParam = {
         type: 'thinking',
         thinking: thinking.content,
@@ -1247,29 +1239,6 @@ export class AnthropicTextAdapter<
               timestamp: Date.now(),
               stepType: 'thinking',
             }
-          } else if (event.content_block.type === 'redacted_thinking') {
-            // Encrypted thinking: no text, and its data must go back to
-            // Anthropic unchanged. It travels as the thinking step's signature.
-            const redactedStepId = genId()
-            yield {
-              type: EventType.STEP_STARTED,
-              stepName: redactedStepId,
-              stepId: redactedStepId,
-              model,
-              timestamp: Date.now(),
-              stepType: 'thinking',
-            }
-            yield {
-              type: EventType.STEP_FINISHED,
-              stepName: redactedStepId,
-              stepId: redactedStepId,
-              model,
-              timestamp: Date.now(),
-              delta: '',
-              content: '',
-              signature: event.content_block.data,
-              redacted: true,
-            }
           }
         } else if (event.type === 'content_block_delta') {
           if (event.delta.type === 'text_delta') {
diff --git a/packages/ai-anthropic/tests/thinking-replay.test.ts b/packages/ai-anthropic/tests/thinking-replay.test.ts
deleted file mode 100644
index 5520f567ec..0000000000
--- a/packages/ai-anthropic/tests/thinking-replay.test.ts
+++ /dev/null
@@ -1,226 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { chat, StreamProcessor } from '@tanstack/ai'
-import { z } from 'zod'
-import { AnthropicTextAdapter } from '../src/adapters/text'
-import type { ModelMessage, Tool } from '@tanstack/ai'
-
-const mocks = vi.hoisted(() => {
-  const betaMessagesCreate = vi.fn()
-  const client = {
-    beta: { messages: { create: betaMessagesCreate } },
-    messages: { create: vi.fn() },
-  }
-  return { betaMessagesCreate, client }
-})
-
-vi.mock('@anthropic-ai/sdk', () => {
-  class MockAnthropic {
-    beta = mocks.client.beta
-    messages = mocks.client.messages
-    constructor(_: { apiKey: string }) {}
-  }
-  return { default: MockAnthropic }
-})
-
-type Block = { type: string } & Record<string, unknown>
-
-const adapter = () =>
-  new AnthropicTextAdapter({ apiKey: 'test-key' }, 'claude-opus-4-1')
-
-const weather: Tool = {
-  name: 'lookup_weather',
-  description: 'Return the weather for a city',
-  inputSchema: z.object({ location: z.string() }),
-  execute: () => 'sunny',
-}
-
-/** A stream of raw Anthropic events. */
-function stream(events: Array<Record<string, unknown>>) {
-  return (async function* () {
-    for (const event of events) yield event
-  })()
-}
-
-const redactedBlock = [
-  {
-    type: 'content_block_start',
-    index: 0,
-    content_block: { type: 'redacted_thinking', data: 'opaque-1' },
-  },
-  { type: 'content_block_stop', index: 0 },
-]
-
-function textEvents(index: number, text: string) {
-  return [
-    {
-      type: 'content_block_start',
-      index,
-      content_block: { type: 'text', text: '' },
-    },
-    {
-      type: 'content_block_delta',
-      index,
-      delta: { type: 'text_delta', text },
-    },
-    { type: 'content_block_stop', index },
-  ]
-}
-
-function end(stopReason: string) {
-  return [
-    {
-      type: 'message_delta',
-      delta: { stop_reason: stopReason },
-      usage: { output_tokens: 5 },
-    },
-    { type: 'message_stop' },
-  ]
-}
-
-/** The content blocks of the last assistant message in a request. */
-function assistantBlocks(call: number) {
-  const [payload] = mocks.betaMessagesCreate.mock.calls[call]!
-  const messages: Array<{ role: string; content: unknown }> = payload.messages
-  const assistant = messages.filter((m) => m.role === 'assistant').at(-1)
-  return Array.isArray(assistant?.content)
-    ? (assistant.content as Array<Block>)
-    : []
-}
-
-async function drain(iterable: AsyncIterable<unknown>) {
-  for await (const _ of iterable) {
-    // consume
-  }
-}
-
-describe('Anthropic replay', () => {
-  beforeEach(() => {
-    mocks.betaMessagesCreate.mockReset()
-  })
-
-  it('marks a failed tool result with is_error', async () => {
-    mocks.betaMessagesCreate.mockResolvedValueOnce(
-      stream([...textEvents(0, 'Sorry.'), ...end('end_turn')]),
-    )
-    const messages: Array<ModelMessage> = [
-      { role: 'user', content: 'Weather in Atlantis?' },
-      {
-        role: 'assistant',
-        content: null,
-        toolCalls: [
-          {
-            id: 'call-1',
-            type: 'function',
-            function: {
-              name: 'lookup_weather',
-              arguments: '{"location":"Atlantis"}',
-            },
-          },
-        ],
-      },
-      {
-        role: 'tool',
-        toolCallId: 'call-1',
-        content: '{"error":"City not found"}',
-        error: 'City not found',
-      },
-    ]
-
-    await drain(chat({ adapter: adapter(), messages }))
-
-    const [payload] = mocks.betaMessagesCreate.mock.calls[0]!
-    const blocks: Array<Block> = payload.messages.flatMap(
-      (m: { content: unknown }) => (Array.isArray(m.content) ? m.content : []),
-    )
-    expect(blocks.find((b) => b.type === 'tool_result')).toMatchObject({
-      tool_use_id: 'call-1',
-      is_error: true,
-    })
-  })
-
-  it('sends a redacted thinking block back in the same run', async () => {
-    mocks.betaMessagesCreate
-      .mockResolvedValueOnce(
-        stream([
-          ...redactedBlock,
-          {
-            type: 'content_block_start',
-            index: 1,
-            content_block: {
-              type: 'tool_use',
-              id: 'call-1',
-              name: 'lookup_weather',
-              input: {},
-            },
-          },
-          {
-            type: 'content_block_delta',
-            index: 1,
-            delta: {
-              type: 'input_json_delta',
-              partial_json: '{"location":"Berlin"}',
-            },
-          },
-          { type: 'content_block_stop', index: 1 },
-          ...end('tool_use'),
-        ]),
-      )
-      .mockResolvedValueOnce(
-        stream([...textEvents(0, 'It is sunny.'), ...end('end_turn')]),
-      )
-
-    await drain(
-      chat({
-        adapter: adapter(),
-        messages: [{ role: 'user', content: 'Weather in Berlin?' }],
-        tools: [weather],
-      }),
-    )
-
-    expect(mocks.betaMessagesCreate).toHaveBeenCalledTimes(2)
-    expect(assistantBlocks(1).map((b) => b.type)).toEqual([
-      'redacted_thinking',
-      'tool_use',
-    ])
-    expect(assistantBlocks(1)[0]).toEqual({
-      type: 'redacted_thinking',
-      data: 'opaque-1',
-    })
-  })
-
-  it('sends a redacted thinking block back on the next turn', async () => {
-    mocks.betaMessagesCreate
-      .mockResolvedValueOnce(
-        stream([
-          ...redactedBlock,
-          ...textEvents(1, 'Hello.'),
-          ...end('end_turn'),
-        ]),
-      )
-      .mockResolvedValueOnce(
-        stream([...textEvents(0, 'Again.'), ...end('end_turn')]),
-      )
-    const first: Array<ModelMessage> = [{ role: 'user', content: 'Hi' }]
-    const processor = new StreamProcessor()
-    processor.addUserMessage('Hi')
-    for await (const chunk of chat({ adapter: adapter(), messages: first })) {
-      processor.processChunk(chunk)
-    }
-    processor.finalizeStream()
-
-    await drain(
-      chat({
-        adapter: adapter(),
-        messages: [
-          ...processor.getMessages(),
-          { role: 'user', content: 'Say it again.' },
-        ],
-      }),
-    )
-
-    expect(assistantBlocks(1)).toEqual([
-      { type: 'redacted_thinking', data: 'opaque-1' },
-      { type: 'text', text: 'Hello.' },
-    ])
-  })
-})
diff --git a/packages/ai/src/activities/chat/agents/spawn.ts b/packages/ai/src/activities/chat/agents/spawn.ts
index b7cb092425..80a9732b28 100644
--- a/packages/ai/src/activities/chat/agents/spawn.ts
+++ b/packages/ai/src/activities/chat/agents/spawn.ts
@@ -9,7 +9,6 @@ import {
   tanstackMetadata,
   withTanstackMetadata,
 } from '../../../utilities/merge-metadata'
-import { mergeStreams } from '../../../utilities/merge-streams'
 import { INTERRUPT_BINDING_METADATA_KEY } from '../../../interrupt-resume'
 import { EMIT_STREAM_CHUNK, SUBAGENT_TOOL } from '../tools/tool-calls'
 import type { SubagentToolOutcome } from '../tools/tool-calls'
@@ -640,6 +639,36 @@ export async function* spawnAgentStream(
   }
 }
 
+async function* mergeAgentStreams(streams: Array<AsyncIterable<StreamChunk>>) {
+  const readers = streams.map((stream) => {
+    const iterator = stream[Symbol.asyncIterator]()
+    return {
+      iterator,
+      next: iterator.next(),
+    }
+  })
+
+  try {
+    while (readers.length > 0) {
+      const indexed = readers.map((reader, index) =>
+        reader.next.then((result) => ({ index, result, reader })),
+      )
+      const winner = await Promise.race(indexed)
+      if (winner.result.done) {
+        readers.splice(winner.index, 1)
+        continue
+      }
+      yield winner.result.value
+      winner.reader.next = winner.reader.iterator.next()
+    }
+  } finally {
+    // The reader stopped early. Close every child so its finally runs.
+    for (const reader of readers) {
+      void reader.iterator.return?.().catch(() => {})
+    }
+  }
+}
+
 /** True when a child in these chunks failed or stopped for outside input. */
 function stopsSequence(chunks: ReadonlyArray<StreamChunk>, id: string) {
   return chunks.some(
@@ -705,7 +734,7 @@ export async function* spawnNamedAgents(
       yield* onlyStream
       return
     }
-    yield* mergeStreams(streams)
+    yield* mergeAgentStreams(streams)
   } finally {
     group.controller.abort()
     group.dispose()
diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index f3b8aac05f..d6bbfa9d74 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -536,8 +536,6 @@ export interface TextActivityOptions<
   abortController?: TextOptions['abortController']
   /** Strategy for controlling the agent loop */
   agentLoopStrategy?: TextOptions['agentLoopStrategy']
-  /** How the server tools of one model turn run. Default `'parallel'`. */
-  toolExecution?: TextOptions['toolExecution']
   /**
    * Optional configuration for lazy-tool discovery (tools marked `lazy: true`).
    * Tunes how much of each lazy tool's description appears in the discovery
@@ -872,7 +870,8 @@ class TextEngine<
   private currentMessageCreatedAt: Date | null = null
   private streamIdentityCaptured = false
   private accumulatedContent = ''
-  private accumulatedThinking: NonNullable<ModelMessage['thinking']> = []
+  private accumulatedThinking: Array<{ content: string; signature?: string }> =
+    []
   /**
    * Arrival order of this iteration's thinking steps, text and tool calls.
    * A ModelMessage keeps `thinking` apart from `content`/`toolCalls`, so a
@@ -884,7 +883,6 @@ class TextEngine<
   private turnParts: Array<TurnPart> | null = []
   private currentThinkingContent = ''
   private currentThinkingSignature = ''
-  private currentThinkingRedacted = false
   private eventOptions?: Record<string, unknown> | undefined
   private eventToolNames?: Array<string>
   private finishedEvent: RunFinishedEvent | null = null
@@ -1551,7 +1549,6 @@ class TextEngine<
     this.turnParts = []
     this.currentThinkingContent = ''
     this.currentThinkingSignature = ''
-    this.currentThinkingRedacted = false
 
     this.finishedEvent = null
     this.streamedToolErrorResults.clear()
@@ -2021,7 +2018,6 @@ class TextEngine<
         ...(this.currentThinkingSignature && {
           signature: this.currentThinkingSignature,
         }),
-        ...(this.currentThinkingRedacted && { redacted: true }),
       })
       if (this.turnParts) {
         const placeholder = [...this.turnParts]
@@ -2039,7 +2035,6 @@ class TextEngine<
       }
       this.currentThinkingContent = ''
       this.currentThinkingSignature = ''
-      this.currentThinkingRedacted = false
     }
   }
 
@@ -2067,7 +2062,6 @@ class TextEngine<
     if (typeof chunk.signature === 'string' && chunk.signature !== '') {
       this.noteThinkingStepPosition()
       this.currentThinkingSignature = chunk.signature
-      this.currentThinkingRedacted = chunk.redacted === true
     }
   }
 
@@ -2097,7 +2091,6 @@ class TextEngine<
     }
     this.noteThinkingStepPosition()
     this.currentThinkingSignature = chunk.encryptedValue
-    this.currentThinkingRedacted = tanstackMetadata(chunk)?.redacted === true
   }
 
   /**
@@ -2235,7 +2228,6 @@ class TextEngine<
         cancelledToolCallIds: this.resumeCancelledToolCallIds,
         inputResponses: this.resumeInputResponses,
       },
-      this.params.toolExecution,
     )
 
     // Consume the async generator, yielding custom events and collecting the return value
@@ -2424,7 +2416,6 @@ class TextEngine<
         cancelledToolCallIds: this.resumeCancelledToolCallIds,
         inputResponses: this.resumeInputResponses,
       },
-      this.params.toolExecution,
     )
 
     // Consume the async generator, yielding custom events and collecting the return value
@@ -2614,7 +2605,7 @@ class TextEngine<
       ),
     )
     type Segment = {
-      thinking: NonNullable<ModelMessage['thinking']>
+      thinking: Array<{ content: string; signature?: string }>
       text: string
       callIds: Array<string>
     }
diff --git a/packages/ai/src/activities/chat/messages.ts b/packages/ai/src/activities/chat/messages.ts
index 5022867615..4a4bac88e1 100644
--- a/packages/ai/src/activities/chat/messages.ts
+++ b/packages/ai/src/activities/chat/messages.ts
@@ -72,11 +72,6 @@ function encryptedValueFrom(value: object): string | undefined {
   return nonEmptyString(tanstackMetadata(value)?.signature)
 }
 
-/** `{ redacted: true }` when a reasoning message carries a redacted block. */
-function redactedFrom(value: object) {
-  return tanstackMetadata(value)?.redacted === true ? { redacted: true } : {}
-}
-
 function toolCallFromWire(toolCall: ToolCall, bag: unknown): ToolCall {
   const fromBag =
     bag != null && typeof bag === 'object' && !Array.isArray(bag)
@@ -251,7 +246,7 @@ function convertOwnMessages(
   }
 
   const modelMessages: Array<ModelMessage> = []
-  let pendingThinking: NonNullable<ModelMessage['thinking']> = []
+  let pendingThinking: Array<{ content: string; signature?: string }> = []
   for (const msg of messages) {
     if ('parts' in msg) {
       modelMessages.push(...uiMessageToModelMessages(msg))
@@ -278,7 +273,6 @@ function convertOwnMessages(
         pendingThinking.push({
           content: typeof content === 'string' ? content : '',
           ...(signature !== undefined ? { signature } : {}),
-          ...redactedFrom(msg),
         })
       }
       continue
@@ -669,7 +663,7 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
   // shared UI id on each one so persistence can retain the original identity.
   const messageList: Array<ModelMessage> = []
   let current = createSegment()
-  let pendingThinking: NonNullable<ModelMessage['thinking']> = []
+  let pendingThinking: Array<{ content: string; signature?: string }> = []
 
   // Track emitted tool result IDs to avoid duplicates.
   // A tool call can have BOTH an explicit tool-result part AND an output
@@ -770,7 +764,6 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
           pendingThinking.push({
             content: part.content,
             ...(part.signature && { signature: part.signature }),
-            ...(part.redacted && { redacted: true }),
           })
         }
         break
@@ -905,7 +898,6 @@ export function modelMessageToUIMessage(
         type: 'thinking',
         content: thinking.content,
         ...(thinking.signature && { signature: thinking.signature }),
-        ...(thinking.redacted && { redacted: true }),
       })
     }
   }
@@ -1129,7 +1121,6 @@ export function aguiSnapshotMessageToUIMessage(
                   type: 'thinking' as const,
                   content,
                   ...(signature !== undefined ? { signature } : {}),
-                  ...redactedFrom(message),
                 },
               ]
             : [],
diff --git a/packages/ai/src/activities/chat/stream/message-updaters.ts b/packages/ai/src/activities/chat/stream/message-updaters.ts
index 1e20eb4066..0b999e556c 100644
--- a/packages/ai/src/activities/chat/stream/message-updaters.ts
+++ b/packages/ai/src/activities/chat/stream/message-updaters.ts
@@ -451,7 +451,6 @@ export function updateThinkingPart(
   stepId: string,
   content: string,
   signature?: string,
-  redacted?: boolean,
 ): Array<UIMessage> {
   return messages.map((msg) => {
     if (msg.id !== messageId) {
@@ -484,14 +483,12 @@ export function updateThinkingPart(
     // not carry one; losing it would strip the provider's encrypted reasoning
     // from a message that is about to be sent back.
     const nextSignature = signature ?? adopted?.signature
-    const nextRedacted = redacted === true || adopted?.redacted === true
 
     const thinkingPart: ThinkingPart = {
       type: 'thinking',
       content,
       stepId,
       ...(nextSignature && { signature: nextSignature }),
-      ...(nextRedacted && { redacted: true }),
     }
 
     if (thinkingPartIndex >= 0) {
diff --git a/packages/ai/src/activities/chat/stream/processor.ts b/packages/ai/src/activities/chat/stream/processor.ts
index b7fbee32e0..04e72128ea 100644
--- a/packages/ai/src/activities/chat/stream/processor.ts
+++ b/packages/ai/src/activities/chat/stream/processor.ts
@@ -786,7 +786,6 @@ export class StreamProcessor {
       hasSeenReasoningEvents: false,
       thinkingSteps: new Map(),
       thinkingStepSignatures: new Map(),
-      thinkingStepRedacted: new Set(),
       thinkingStepOrder: [],
       currentThinkingStepId: null,
       toolCalls: new Map(),
@@ -2357,14 +2356,12 @@ export class StreamProcessor {
     if (thinking === undefined) return
 
     state.thinkingStepSignatures.set(stepId, signature)
-    if (extra.redacted === true) state.thinkingStepRedacted.add(stepId)
     this.messages = updateThinkingPart(
       this.messages,
       messageId,
       stepId,
       thinking,
       signature,
-      state.thinkingStepRedacted.has(stepId),
     )
     this.emitMessagesChange()
   }
@@ -2403,7 +2400,6 @@ export class StreamProcessor {
       stepId,
       nextThinking,
       state.thinkingStepSignatures.get(stepId),
-      state.thinkingStepRedacted.has(stepId),
     )
     this.emitMessagesChange()
 
@@ -2431,9 +2427,6 @@ export class StreamProcessor {
     )
     const stepId = state.currentThinkingStepId ?? chunk.entityId
     state.thinkingStepSignatures.set(stepId, encryptedValue)
-    if (tanstackMetadata(chunk)?.redacted === true) {
-      state.thinkingStepRedacted.add(stepId)
-    }
     const content = state.thinkingSteps.get(stepId) ?? ''
     if (!state.thinkingSteps.has(stepId)) {
       state.thinkingSteps.set(stepId, content)
@@ -2445,7 +2438,6 @@ export class StreamProcessor {
       stepId,
       content,
       encryptedValue,
-      state.thinkingStepRedacted.has(stepId),
     )
     this.emitMessagesChange()
   }
diff --git a/packages/ai/src/activities/chat/stream/types.ts b/packages/ai/src/activities/chat/stream/types.ts
index e4fb7f979e..cbdf333c3b 100644
--- a/packages/ai/src/activities/chat/stream/types.ts
+++ b/packages/ai/src/activities/chat/stream/types.ts
@@ -64,8 +64,6 @@ export interface MessageStreamState {
   hasSeenReasoningEvents: boolean
   thinkingSteps: Map<string, string>
   thinkingStepSignatures: Map<string, string>
-  /** Thinking steps whose signature is a redacted block's data. */
-  thinkingStepRedacted: Set<string>
   thinkingStepOrder: Array<string>
   currentThinkingStepId: string | null
   toolCalls: Map<string, InternalToolCallState>
diff --git a/packages/ai/src/activities/chat/tools/tool-calls.ts b/packages/ai/src/activities/chat/tools/tool-calls.ts
index 43124a8eb2..2ee87be496 100644
--- a/packages/ai/src/activities/chat/tools/tool-calls.ts
+++ b/packages/ai/src/activities/chat/tools/tool-calls.ts
@@ -1,7 +1,6 @@
 import { normalizeToolResult } from '../../../utilities/tool-result'
 import { tanstackMetadata } from '../../../utilities/merge-metadata'
 import { isProviderExecutedToolCall } from '../../../utilities/provider-executed'
-import { mergeStreams } from '../../../utilities/merge-streams'
 import type { AdapterYieldChunk } from '../../../utilities/adapter-yield-chunk'
 import {
   StandardSchemaValidationError,
@@ -927,10 +926,6 @@ async function buildClientToolResult(
  * @param approvals - Map keyed by toolCallId (or `approval_${toolCallId}`) → ToolApprovalResolution
  * @param clientResults - Map of client-side execution results (toolCallId -> result)
  * @param createCustomEventChunk - Factory to create CustomEvent chunks (optional)
- * @param toolExecution - `'parallel'` (default) prepares every call in call
- *   order, then starts the server tools together. `'sequential'`, or a tool
- *   with `sequential: true` in the batch, runs one call at a time. Results
- *   come back in call order either way.
  */
 export async function* executeToolCalls<TContext = unknown>(
   toolCalls: Array<ToolCall>,
@@ -946,7 +941,6 @@ export async function* executeToolCalls<TContext = unknown>(
   userContext?: TContext,
   abortSignal?: AbortSignal,
   resumeState?: ToolResumeExecutionState,
-  toolExecution: 'parallel' | 'sequential' = 'parallel',
 ): AsyncGenerator<CustomEvent | StreamChunk, ExecuteToolCallsResult, void> {
   const results: Array<ToolResult> = []
   const needsApproval: Array<ApprovalRequest> = []
@@ -960,56 +954,6 @@ export async function* executeToolCalls<TContext = unknown>(
     toolMap.set(tool.name, tool)
   }
 
-  const runsInOrder =
-    toolExecution === 'sequential' ||
-    toolCalls.some((tc) => toolMap.get(tc.function.name)?.sequential)
-  // Parallel batches start their server tools here after every call is prepared.
-  const runs: Array<AsyncGenerator<CustomEvent | StreamChunk, void, void>> = []
-
-  // A tool that has not started when the run aborts never starts. It gets an
-  // error result, so every call of the batch still has a result.
-  async function* runServerTool(
-    toolCall: ToolCall,
-    tool: AnyTool,
-    toolName: string,
-    input: unknown,
-    context: ToolExecutionContext<TContext>,
-    pendingEvents: Array<CustomEvent | StreamChunk>,
-  ): AsyncGenerator<CustomEvent | StreamChunk, void, void> {
-    if (abortSignal?.aborted) {
-      results.push({
-        toolCallId: toolCall.id,
-        toolName,
-        result: { error: 'Operation aborted' },
-        input,
-        state: 'output-error',
-        duration: 0,
-      })
-      await middlewareHooks?.onAfterToolCall?.({
-        toolCall,
-        tool,
-        toolName,
-        toolCallId: toolCall.id,
-        ok: false,
-        duration: 0,
-        error: new Error('Operation aborted'),
-      })
-      return
-    }
-    yield* executeServerTool(
-      toolCall,
-      tool,
-      toolName,
-      input,
-      context,
-      pendingEvents,
-      results,
-      middlewareHooks,
-      inputRequired,
-      subagentInterrupts,
-    )
-  }
-
   // Batch gating: when any tool in the batch still needs an approval decision,
   // defer all execution so side effects don't happen before the user decides.
   const hasPendingApprovals = toolCalls.some((tc) => {
@@ -1243,16 +1187,18 @@ export async function* executeToolCalls<TContext = unknown>(
             input = decision.input
           }
 
-          const run = runServerTool(
+          yield* executeServerTool(
             toolCall,
             tool,
             toolName,
             input,
             context,
             pendingEvents,
+            results,
+            middlewareHooks,
+            inputRequired,
+            subagentInterrupts,
           )
-          if (runsInOrder) yield* run
-          else runs.push(run)
         } else {
           // User declined
           results.push({
@@ -1292,28 +1238,20 @@ export async function* executeToolCalls<TContext = unknown>(
       input = decision.input
     }
 
-    const run = runServerTool(
+    yield* executeServerTool(
       toolCall,
       tool,
       toolName,
       input,
       context,
       pendingEvents,
+      results,
+      middlewareHooks,
+      inputRequired,
+      subagentInterrupts,
     )
-    if (runsInOrder) yield* run
-    else runs.push(run)
   }
 
-  yield* mergeStreams(runs)
-
-  // Parallel tools finish in any order. The model gets the results in the
-  // order it made the calls.
-  const callOrder = new Map(toolCalls.map((tc, index) => [tc.id, index]))
-  results.sort(
-    (a, b) =>
-      (callOrder.get(a.toolCallId) ?? 0) - (callOrder.get(b.toolCallId) ?? 0),
-  )
-
   return {
     results,
     needsApproval,
diff --git a/packages/ai/src/activities/chat/tools/tool-definition.ts b/packages/ai/src/activities/chat/tools/tool-definition.ts
index 85cb9cc8c5..e63fa570ef 100644
--- a/packages/ai/src/activities/chat/tools/tool-definition.ts
+++ b/packages/ai/src/activities/chat/tools/tool-definition.ts
@@ -230,7 +230,6 @@ export type ToolDefinitionConfig<
    * (default) gives the model a note that the tool may or may not have run.
    */
   replay?: 'safe' | 'never'
-  sequential?: boolean
   metadata?: Record<string, unknown>
   execution?: 'task'
 } & ApprovalConfig<TNeedsApproval, TApprovalSchema>
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index 032601ab73..69ec8f9ccf 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -382,12 +382,7 @@ export interface ModelMessage<
   name?: string
   toolCalls?: Array<ToolCall>
   toolCallId?: string
-  /**
-   * Signed thinking to send back to the provider. `redacted: true` marks a
-   * block the provider encrypted: `content` is empty and `signature` holds its
-   * opaque data.
-   */
-  thinking?: Array<{ content: string; signature?: string; redacted?: boolean }>
+  thinking?: Array<{ content: string; signature?: string }>
   /** Error reported by an AG-UI tool message. */
   error?: string
   /** Optional AG-UI message metadata. TanStack-owned fields live under `tanstack`. */
@@ -472,12 +467,6 @@ export interface ThinkingPart {
   content: string
   stepId?: string
   signature?: string
-  /**
-   * The provider encrypted this thinking block (Anthropic `redacted_thinking`).
-   * `content` is empty, and `signature` holds the opaque data that goes back
-   * to the provider unchanged.
-   */
-  redacted?: boolean
 }
 
 /**
@@ -596,8 +585,6 @@ export interface TanStackMessageMetadata {
   subagent?: SubagentWireInfo
   /** Thinking signature for a `role: 'reasoning'` fan-out message. */
   signature?: string
-  /** Set with `signature` when the provider redacted the thinking block. */
-  redacted?: boolean
   /** Per-tool-call provider metadata keyed by tool call id (e.g. Gemini thoughtSignature). */
   toolCallMetadata?: Record<string, unknown>
   toolResult?: {
@@ -917,9 +904,6 @@ export interface Tool<
    */
   replay?: 'safe' | 'never'
 
-  /** If true, a batch of tool calls that contains this tool runs one call at a time, also when `toolExecution` is `'parallel'`. */
-  sequential?: boolean
-
   /** Additional metadata for adapters or custom extensions */
   metadata?: Record<string, any> | undefined
 }
@@ -1112,12 +1096,6 @@ export interface TextOptions<
    */
   systemPrompts?: Array<SystemPrompt>
   agentLoopStrategy?: AgentLoopStrategy
-  /**
-   * How the server tools of one model turn run. `'parallel'` (the default)
-   * starts them together, and `'sequential'` runs them one at a time. A tool
-   * with `sequential: true` makes its whole batch sequential.
-   */
-  toolExecution?: 'parallel' | 'sequential'
   /**
    * Optional configuration for lazy-tool discovery (tools marked `lazy: true`).
    * Tunes how much of each lazy tool's description appears in the discovery
diff --git a/packages/ai/src/utilities/adapter-yield-chunk.ts b/packages/ai/src/utilities/adapter-yield-chunk.ts
index 7b4c752730..d733c86984 100644
--- a/packages/ai/src/utilities/adapter-yield-chunk.ts
+++ b/packages/ai/src/utilities/adapter-yield-chunk.ts
@@ -24,8 +24,6 @@ type AdapterExtras = {
   stepType?: string
   delta?: string | ReadonlyArray<unknown>
   signature?: string
-  /** With `signature`: the provider redacted this thinking block. */
-  redacted?: boolean
   error?: { message: string; code?: string }
   'tanstack:interruptErrors'?: ReadonlyArray<InterruptSubmissionError>
   threadId?: string
diff --git a/packages/ai/src/utilities/ag-ui-wire.ts b/packages/ai/src/utilities/ag-ui-wire.ts
index 24f8a921f5..da2aac2bcc 100644
--- a/packages/ai/src/utilities/ag-ui-wire.ts
+++ b/packages/ai/src/utilities/ag-ui-wire.ts
@@ -225,9 +225,6 @@ export function uiMessagesToWire(
         if (part.signature) {
           reasoning.encryptedValue = part.signature
         }
-        if (part.redacted) {
-          reasoning.metadata = { tanstack: { redacted: true } }
-        }
         wire.push(reasoning)
       }
 
diff --git a/packages/ai/src/utilities/merge-streams.ts b/packages/ai/src/utilities/merge-streams.ts
deleted file mode 100644
index 885a368190..0000000000
--- a/packages/ai/src/utilities/merge-streams.ts
+++ /dev/null
@@ -1,34 +0,0 @@
-/**
- * Yield the items of several async streams as they arrive. If the reader
- * stops early, every stream that is still open is closed, so its `finally`
- * runs.
- */
-export async function* mergeStreams<T>(streams: Array<AsyncIterable<T>>) {
-  const readers = streams.map((stream) => {
-    const iterator = stream[Symbol.asyncIterator]()
-    return {
-      iterator,
-      next: iterator.next(),
-    }
-  })
-
-  try {
-    while (readers.length > 0) {
-      const indexed = readers.map((reader, index) =>
-        reader.next.then((result) => ({ index, result, reader })),
-      )
-      const winner = await Promise.race(indexed)
-      if (winner.result.done) {
-        readers.splice(winner.index, 1)
-        continue
-      }
-      yield winner.result.value
-      winner.reader.next = winner.reader.iterator.next()
-    }
-  } finally {
-    // The reader stopped early. Close every stream so its finally runs.
-    for (const reader of readers) {
-      void reader.iterator.return?.().catch(() => {})
-    }
-  }
-}
diff --git a/packages/ai/src/utilities/normalize-stream-chunk.ts b/packages/ai/src/utilities/normalize-stream-chunk.ts
index 34b8b58542..a706252269 100644
--- a/packages/ai/src/utilities/normalize-stream-chunk.ts
+++ b/packages/ai/src/utilities/normalize-stream-chunk.ts
@@ -41,7 +41,6 @@ function encryptedValueExtras(chunk: AdapterYieldChunk): Array<StreamChunk> {
           entityId,
           encryptedValue: chunk.signature,
           timestamp,
-          redacted: chunk.redacted === true,
         }),
       )
     }
diff --git a/packages/ai/src/utilities/reasoning-encrypted-value.ts b/packages/ai/src/utilities/reasoning-encrypted-value.ts
index 919e50dad8..1236a30234 100644
--- a/packages/ai/src/utilities/reasoning-encrypted-value.ts
+++ b/packages/ai/src/utilities/reasoning-encrypted-value.ts
@@ -1,24 +1,18 @@
 import { EventType } from '../types'
-import { withTanstackMetadata } from './merge-metadata'
 import type { ReasoningEncryptedValueEvent } from '../types'
 
-/**
- * Spec event that carries a provider thinking / tool-call signature blob.
- * `redacted: true` marks a redacted thinking block, in `metadata.tanstack`.
- */
+/** Spec event that carries a provider thinking / tool-call signature blob. */
 export function reasoningEncryptedValue(opts: {
   subtype: 'message' | 'tool-call'
   entityId: string
   encryptedValue: string
   timestamp?: number
-  redacted?: boolean
 }): ReasoningEncryptedValueEvent {
-  const event: ReasoningEncryptedValueEvent = {
+  return {
     type: EventType.REASONING_ENCRYPTED_VALUE,
     subtype: opts.subtype,
     entityId: opts.entityId,
     encryptedValue: opts.encryptedValue,
     ...(opts.timestamp !== undefined ? { timestamp: opts.timestamp } : {}),
   }
-  return opts.redacted ? withTanstackMetadata(event, { redacted: true }) : event
 }
diff --git a/packages/ai/tests/parallel-tools.test.ts b/packages/ai/tests/parallel-tools.test.ts
deleted file mode 100644
index 200ac73a3f..0000000000
--- a/packages/ai/tests/parallel-tools.test.ts
+++ /dev/null
@@ -1,222 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { chat } from '../src/activities/chat/index'
-import { executeToolCalls } from '../src/activities/chat/tools/tool-calls'
-import { EventType } from '../src/types'
-import { collectChunks, createMockAdapter, ev, serverTool } from './test-utils'
-import type { ChatMiddleware } from '../src/activities/chat/middleware/types'
-import type { StreamChunk, Tool, ToolCall } from '../src/types'
-
-/** A promise and the function that resolves it. */
-function gate() {
-  let open = () => {}
-  const opened = new Promise<void>((resolve) => {
-    open = resolve
-  })
-  return { opened, open }
-}
-
-/** `true` when `promise` settles within `ms`, else `false`. */
-function within(promise: Promise<void>, ms: number) {
-  return Promise.race([
-    promise.then(() => true),
-    new Promise<boolean>((resolve) => setTimeout(() => resolve(false), ms)),
-  ])
-}
-
-/** A tool that logs its start and end, and gives the event loop a turn between them. */
-function loggingTool(name: string, log: Array<string>, extra?: Partial<Tool>) {
-  return {
-    ...serverTool(name, async () => {
-      log.push(`${name} start`)
-      await new Promise((resolve) => setTimeout(resolve, 0))
-      log.push(`${name} end`)
-      return `${name} done`
-    }),
-    ...extra,
-  }
-}
-
-/** A model turn that calls `slow` and then `fast`, then a turn that answers. */
-function twoCallBatch() {
-  return createMockAdapter({
-    iterations: [
-      [
-        ev.runStarted(),
-        ev.toolStart('call-slow', 'slow'),
-        ev.toolArgs('call-slow', '{}'),
-        ev.toolEnd('call-slow'),
-        ev.toolStart('call-fast', 'fast'),
-        ev.toolArgs('call-fast', '{}'),
-        ev.toolEnd('call-fast'),
-        ev.runFinished('tool_calls'),
-      ],
-      [ev.runStarted(), ev.textContent('Done'), ev.runFinished('stop')],
-    ],
-  })
-}
-
-function runBatch(
-  tools: Array<Tool>,
-  options: {
-    toolExecution?: 'parallel' | 'sequential'
-    middleware?: Array<ChatMiddleware>
-  } = {},
-) {
-  const { adapter } = twoCallBatch()
-  return collectChunks(
-    chat({
-      adapter,
-      messages: [{ role: 'user', content: 'Go' }],
-      tools,
-      ...options,
-    }),
-  )
-}
-
-function resultOrder(chunks: Array<StreamChunk>) {
-  return chunks.flatMap((chunk) =>
-    chunk.type === EventType.TOOL_CALL_RESULT ? [chunk.toolCallId] : [],
-  )
-}
-
-function call(id: string, name: string): ToolCall {
-  return { id, type: 'function', function: { name, arguments: '{}' } }
-}
-
-async function drain(generator: ReturnType<typeof executeToolCalls>) {
-  let step = await generator.next()
-  while (!step.done) step = await generator.next()
-  return step.value.results.map((result) => [result.toolCallId, result.result])
-}
-
-describe('server tools of one batch', () => {
-  it('run at the same time, and the results keep the call order', async () => {
-    const fastStarted = gate()
-    let slowSawFast = false
-    const slow = serverTool('slow', async () => {
-      slowSawFast = await within(fastStarted.opened, 1_000)
-      return 'slow done'
-    })
-    const fast = serverTool('fast', () => {
-      fastStarted.open()
-      return 'fast done'
-    })
-
-    const chunks = await runBatch([slow, fast])
-
-    expect(slowSawFast).toBe(true)
-    expect(resultOrder(chunks)).toEqual(['call-slow', 'call-fast'])
-  })
-
-  it("run one at a time with toolExecution: 'sequential'", async () => {
-    const log: Array<string> = []
-
-    await runBatch([loggingTool('slow', log), loggingTool('fast', log)], {
-      toolExecution: 'sequential',
-    })
-
-    expect(log).toEqual(['slow start', 'slow end', 'fast start', 'fast end'])
-  })
-
-  it('run one at a time when a tool of the batch is sequential', async () => {
-    const log: Array<string> = []
-
-    await runBatch([
-      loggingTool('slow', log),
-      loggingTool('fast', log, { sequential: true }),
-    ])
-
-    expect(log).toEqual(['slow start', 'slow end', 'fast start', 'fast end'])
-  })
-
-  it('call onBeforeToolCall in call order and onAfterToolCall in finish order', async () => {
-    const hooks: Array<string> = []
-    const fastDone = gate()
-    const slow = serverTool('slow', async () => {
-      await fastDone.opened
-      return 'slow done'
-    })
-    const fast = serverTool('fast', () => 'fast done')
-    const order: ChatMiddleware = {
-      name: 'order',
-      onBeforeToolCall: (_ctx, hookCtx) => {
-        hooks.push(`before ${hookCtx.toolName}`)
-      },
-      onAfterToolCall: (_ctx, info) => {
-        hooks.push(`after ${info.toolName}`)
-        if (info.toolName === 'fast') fastDone.open()
-      },
-    }
-
-    await runBatch([slow, fast], { middleware: [order] })
-
-    expect(hooks).toEqual([
-      'before slow',
-      'before fast',
-      'after fast',
-      'after slow',
-    ])
-  })
-
-  it('do not start after the run aborts, and get "Operation aborted"', async () => {
-    const controller = new AbortController()
-    const ran: Array<string> = []
-    const tool = (name: string) =>
-      serverTool(name, () => {
-        ran.push(name)
-        return 'ok'
-      })
-
-    const results = await drain(
-      executeToolCalls(
-        [call('a', 'first'), call('b', 'second')],
-        [tool('first'), tool('second')],
-        new Map(),
-        new Map(),
-        undefined,
-        {
-          onBeforeToolCall: async (toolCall) => {
-            if (toolCall.id === 'b') controller.abort()
-          },
-        },
-        undefined,
-        controller.signal,
-      ),
-    )
-
-    expect(ran).toEqual([])
-    expect(results).toEqual([
-      ['a', { error: 'Operation aborted' }],
-      ['b', { error: 'Operation aborted' }],
-    ])
-  })
-
-  it('stop starting tools in sequential mode once the run aborts', async () => {
-    const controller = new AbortController()
-    const first = serverTool('first', () => {
-      controller.abort()
-      return 'ok'
-    })
-    const second = serverTool('second', () => 'ran')
-
-    const results = await drain(
-      executeToolCalls(
-        [call('a', 'first'), call('b', 'second')],
-        [first, second],
-        new Map(),
-        new Map(),
-        undefined,
-        undefined,
-        undefined,
-        controller.signal,
-        undefined,
-        'sequential',
-      ),
-    )
-
-    expect(results).toEqual([
-      ['a', 'ok'],
-      ['b', { error: 'Operation aborted' }],
-    ])
-  })
-})
diff --git a/packages/ai/tests/redacted-thinking.test.ts b/packages/ai/tests/redacted-thinking.test.ts
deleted file mode 100644
index 99a57ab967..0000000000
--- a/packages/ai/tests/redacted-thinking.test.ts
+++ /dev/null
@@ -1,68 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import {
-  aguiSnapshotMessageToUIMessage,
-  convertMessagesToModelMessages,
-  modelMessagesToUIMessages,
-} from '../src/activities/chat/messages'
-import { uiMessagesToWire } from '../src/utilities/ag-ui-wire'
-import { chatParamsFromRequestBody } from '../src/utilities/chat-params'
-import type { ModelMessage } from '../src/types'
-
-const stored: Array<ModelMessage> = [
-  { role: 'user', content: 'Hi' },
-  {
-    role: 'assistant',
-    content: 'Hello.',
-    thinking: [
-      { content: '', signature: 'opaque-1', redacted: true },
-      { content: 'I greet back.', signature: 'sig-2' },
-    ],
-  },
-]
-
-function thinkingOf(messages: Array<ModelMessage>) {
-  return messages.find((message) => message.role === 'assistant')?.thinking
-}
-
-describe('redacted thinking', () => {
-  it('survives a stored thread that is loaded into the UI and sent back', () => {
-    const ui = modelMessagesToUIMessages(stored)
-
-    expect(thinkingOf(convertMessagesToModelMessages(ui))).toEqual([
-      { content: '', signature: 'opaque-1', redacted: true },
-      { content: 'I greet back.', signature: 'sig-2' },
-    ])
-  })
-
-  it('survives the wire from the client to the server', async () => {
-    const wire = uiMessagesToWire(modelMessagesToUIMessages(stored))
-    // `JSON.parse(JSON.stringify(...))` stands in for the HTTP hop.
-    const params = await chatParamsFromRequestBody({
-      threadId: 'thread-1',
-      runId: 'run-1',
-      messages: JSON.parse(JSON.stringify(wire)),
-      tools: [],
-      context: [],
-    })
-
-    expect(thinkingOf(convertMessagesToModelMessages(params.messages))).toEqual(
-      [
-        { content: '', signature: 'opaque-1', redacted: true },
-        { content: 'I greet back.', signature: 'sig-2' },
-      ],
-    )
-  })
-
-  it('survives an interrupt snapshot that the client loads', () => {
-    const wire = uiMessagesToWire(modelMessagesToUIMessages(stored))
-
-    const parts = wire
-      .filter((message) => message.role === 'reasoning')
-      .flatMap((message) => aguiSnapshotMessageToUIMessage(message).parts)
-
-    expect(parts).toEqual([
-      { type: 'thinking', content: '', signature: 'opaque-1', redacted: true },
-      { type: 'thinking', content: 'I greet back.', signature: 'sig-2' },
-    ])
-  })
-})
diff --git a/testing/e2e/fixtures/tools-test/parallel-server-timing.json b/testing/e2e/fixtures/tools-test/parallel-server-timing.json
deleted file mode 100644
index cb1f8ffa09..0000000000
--- a/testing/e2e/fixtures/tools-test/parallel-server-timing.json
+++ /dev/null
@@ -1,26 +0,0 @@
-{
-  "fixtures": [
-    {
-      "match": {
-        "userMessage": "[parallel-server-timing] run test",
-        "sequenceIndex": 0
-      },
-      "response": {
-        "content": "Let me gather all the information at once.",
-        "toolCalls": [
-          { "name": "get_weather", "arguments": "{\"city\":\"NYC\"}" },
-          { "name": "get_time", "arguments": "{\"timezone\":\"EST\"}" }
-        ]
-      }
-    },
-    {
-      "match": {
-        "userMessage": "[parallel-server-timing] run test",
-        "sequenceIndex": 1
-      },
-      "response": {
-        "content": "Here is the weather and time for NYC."
-      }
-    }
-  ]
-}
diff --git a/testing/e2e/src/lib/tools-test-tools.ts b/testing/e2e/src/lib/tools-test-tools.ts
index 2ba7126ebe..b5d298dcaf 100644
--- a/testing/e2e/src/lib/tools-test-tools.ts
+++ b/testing/e2e/src/lib/tools-test-tools.ts
@@ -117,25 +117,6 @@ export const serverTools = {
   }),
 }
 
-/** A server tool that waits 300 ms and returns when it started and ended. */
-function timedServerTool(name: string) {
-  return toolDefinition({
-    name,
-    description: `Timed ${name}`,
-    inputSchema: z.object({}).passthrough(),
-  }).server(async () => {
-    const startedAt = Date.now()
-    await new Promise((resolve) => setTimeout(resolve, 300))
-    return JSON.stringify({ startedAt, endedAt: Date.now() })
-  })
-}
-
-/** The calls of the `parallel-tools` fixture, as slow tools that report their timing. */
-export const timedServerTools = {
-  get_weather: timedServerTool('get_weather'),
-  get_time: timedServerTool('get_time'),
-}
-
 /**
  * Client-side tool definitions (tools that execute on the client)
  * These use .client() without an execute function - execution happens on client side
@@ -255,11 +236,6 @@ export const SCENARIO_LIST = [
     category: 'basic',
   },
   { id: 'parallel-tools', label: 'Parallel Tools', category: 'basic' },
-  {
-    id: 'parallel-server-timing',
-    label: 'Parallel Server Tool Timing',
-    category: 'basic',
-  },
   {
     id: 'lazy-tool-discovery',
     label: 'Lazy Tool Discovery',
@@ -408,9 +384,6 @@ export function getToolsForScenario(scenario: string) {
     case 'parallel-tools':
       return [serverTools.get_weather, serverTools.get_time]
 
-    case 'parallel-server-timing':
-      return [timedServerTools.get_weather, timedServerTools.get_time]
-
     // Race condition / event flow scenarios
     case 'sequential-client-tools':
       return [clientToolDefinitions.show_notification]
diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index be8bc8fd24..07151625ec 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -125,7 +125,6 @@ import { Route as ApiArktypeToolWireRouteImport } from './routes/api.arktype-too
 import { Route as ApiAnthropicThinkingOrderWireRouteImport } from './routes/api.anthropic-thinking-order-wire'
 import { Route as ApiAnthropicStructuredUsageRouteImport } from './routes/api.anthropic-structured-usage'
 import { Route as ApiAnthropicSkillsWireRouteImport } from './routes/api.anthropic-skills-wire'
-import { Route as ApiAnthropicRedactedThinkingWireRouteImport } from './routes/api.anthropic-redacted-thinking-wire'
 import { Route as ApiAnthropicOpus5CombinedWireRouteImport } from './routes/api.anthropic-opus-5-combined-wire'
 import { Route as ApiAnthropicMultiTurnStructuredWireRouteImport } from './routes/api.anthropic-multi-turn-structured-wire'
 import { Route as ApiAnthropicBugTestRouteImport } from './routes/api.anthropic-bug-test'
@@ -742,12 +741,6 @@ const ApiAnthropicSkillsWireRoute = ApiAnthropicSkillsWireRouteImport.update({
   path: '/api/anthropic-skills-wire',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiAnthropicRedactedThinkingWireRoute =
-  ApiAnthropicRedactedThinkingWireRouteImport.update({
-    id: '/api/anthropic-redacted-thinking-wire',
-    path: '/api/anthropic-redacted-thinking-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
 const ApiAnthropicOpus5CombinedWireRoute =
   ApiAnthropicOpus5CombinedWireRouteImport.update({
     id: '/api/anthropic-opus-5-combined-wire',
@@ -837,7 +830,6 @@ export interface FileRoutesByFullPath {
   '/api/anthropic-bug-test': typeof ApiAnthropicBugTestRoute
   '/api/anthropic-multi-turn-structured-wire': typeof ApiAnthropicMultiTurnStructuredWireRoute
   '/api/anthropic-opus-5-combined-wire': typeof ApiAnthropicOpus5CombinedWireRoute
-  '/api/anthropic-redacted-thinking-wire': typeof ApiAnthropicRedactedThinkingWireRoute
   '/api/anthropic-skills-wire': typeof ApiAnthropicSkillsWireRoute
   '/api/anthropic-structured-usage': typeof ApiAnthropicStructuredUsageRoute
   '/api/anthropic-thinking-order-wire': typeof ApiAnthropicThinkingOrderWireRoute
@@ -966,7 +958,6 @@ export interface FileRoutesByTo {
   '/api/anthropic-bug-test': typeof ApiAnthropicBugTestRoute
   '/api/anthropic-multi-turn-structured-wire': typeof ApiAnthropicMultiTurnStructuredWireRoute
   '/api/anthropic-opus-5-combined-wire': typeof ApiAnthropicOpus5CombinedWireRoute
-  '/api/anthropic-redacted-thinking-wire': typeof ApiAnthropicRedactedThinkingWireRoute
   '/api/anthropic-skills-wire': typeof ApiAnthropicSkillsWireRoute
   '/api/anthropic-structured-usage': typeof ApiAnthropicStructuredUsageRoute
   '/api/anthropic-thinking-order-wire': typeof ApiAnthropicThinkingOrderWireRoute
@@ -1096,7 +1087,6 @@ export interface FileRoutesById {
   '/api/anthropic-bug-test': typeof ApiAnthropicBugTestRoute
   '/api/anthropic-multi-turn-structured-wire': typeof ApiAnthropicMultiTurnStructuredWireRoute
   '/api/anthropic-opus-5-combined-wire': typeof ApiAnthropicOpus5CombinedWireRoute
-  '/api/anthropic-redacted-thinking-wire': typeof ApiAnthropicRedactedThinkingWireRoute
   '/api/anthropic-skills-wire': typeof ApiAnthropicSkillsWireRoute
   '/api/anthropic-structured-usage': typeof ApiAnthropicStructuredUsageRoute
   '/api/anthropic-thinking-order-wire': typeof ApiAnthropicThinkingOrderWireRoute
@@ -1227,7 +1217,6 @@ export interface FileRouteTypes {
     | '/api/anthropic-bug-test'
     | '/api/anthropic-multi-turn-structured-wire'
     | '/api/anthropic-opus-5-combined-wire'
-    | '/api/anthropic-redacted-thinking-wire'
     | '/api/anthropic-skills-wire'
     | '/api/anthropic-structured-usage'
     | '/api/anthropic-thinking-order-wire'
@@ -1356,7 +1345,6 @@ export interface FileRouteTypes {
     | '/api/anthropic-bug-test'
     | '/api/anthropic-multi-turn-structured-wire'
     | '/api/anthropic-opus-5-combined-wire'
-    | '/api/anthropic-redacted-thinking-wire'
     | '/api/anthropic-skills-wire'
     | '/api/anthropic-structured-usage'
     | '/api/anthropic-thinking-order-wire'
@@ -1485,7 +1473,6 @@ export interface FileRouteTypes {
     | '/api/anthropic-bug-test'
     | '/api/anthropic-multi-turn-structured-wire'
     | '/api/anthropic-opus-5-combined-wire'
-    | '/api/anthropic-redacted-thinking-wire'
     | '/api/anthropic-skills-wire'
     | '/api/anthropic-structured-usage'
     | '/api/anthropic-thinking-order-wire'
@@ -1615,7 +1602,6 @@ export interface RootRouteChildren {
   ApiAnthropicBugTestRoute: typeof ApiAnthropicBugTestRoute
   ApiAnthropicMultiTurnStructuredWireRoute: typeof ApiAnthropicMultiTurnStructuredWireRoute
   ApiAnthropicOpus5CombinedWireRoute: typeof ApiAnthropicOpus5CombinedWireRoute
-  ApiAnthropicRedactedThinkingWireRoute: typeof ApiAnthropicRedactedThinkingWireRoute
   ApiAnthropicSkillsWireRoute: typeof ApiAnthropicSkillsWireRoute
   ApiAnthropicStructuredUsageRoute: typeof ApiAnthropicStructuredUsageRoute
   ApiAnthropicThinkingOrderWireRoute: typeof ApiAnthropicThinkingOrderWireRoute
@@ -2518,13 +2504,6 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiAnthropicSkillsWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/anthropic-redacted-thinking-wire': {
-      id: '/api/anthropic-redacted-thinking-wire'
-      path: '/api/anthropic-redacted-thinking-wire'
-      fullPath: '/api/anthropic-redacted-thinking-wire'
-      preLoaderRoute: typeof ApiAnthropicRedactedThinkingWireRouteImport
-      parentRoute: typeof rootRouteImport
-    }
     '/api/anthropic-opus-5-combined-wire': {
       id: '/api/anthropic-opus-5-combined-wire'
       path: '/api/anthropic-opus-5-combined-wire'
@@ -2693,7 +2672,6 @@ const rootRouteChildren: RootRouteChildren = {
   ApiAnthropicMultiTurnStructuredWireRoute:
     ApiAnthropicMultiTurnStructuredWireRoute,
   ApiAnthropicOpus5CombinedWireRoute: ApiAnthropicOpus5CombinedWireRoute,
-  ApiAnthropicRedactedThinkingWireRoute: ApiAnthropicRedactedThinkingWireRoute,
   ApiAnthropicSkillsWireRoute: ApiAnthropicSkillsWireRoute,
   ApiAnthropicStructuredUsageRoute: ApiAnthropicStructuredUsageRoute,
   ApiAnthropicThinkingOrderWireRoute: ApiAnthropicThinkingOrderWireRoute,
diff --git a/testing/e2e/src/routes/api.anthropic-redacted-thinking-wire.ts b/testing/e2e/src/routes/api.anthropic-redacted-thinking-wire.ts
deleted file mode 100644
index d98acda142..0000000000
--- a/testing/e2e/src/routes/api.anthropic-redacted-thinking-wire.ts
+++ /dev/null
@@ -1,241 +0,0 @@
-import { createFileRoute } from '@tanstack/react-router'
-import {
-  chat,
-  chatParamsFromRequestBody,
-  createChatOptions,
-} from '@tanstack/ai'
-import { StreamProcessor, uiMessagesToWire } from '@tanstack/ai/client'
-import { createAnthropicChat } from '@tanstack/ai-anthropic'
-
-const DUMMY_KEY = 'sk-ant-e2e-test-dummy-key'
-
-type SseEvent = Record<string, unknown> & { type: string }
-
-const messageStart: SseEvent = {
-  type: 'message_start',
-  message: {
-    id: 'msg_redacted',
-    type: 'message',
-    role: 'assistant',
-    content: [],
-    model: 'claude-sonnet-4-5',
-    stop_reason: null,
-    stop_sequence: null,
-    usage: { input_tokens: 5, output_tokens: 0 },
-  },
-}
-
-/** Claude sends a redacted block whole, on its start event. */
-function redacted(index: number, data: string) {
-  return [
-    {
-      type: 'content_block_start',
-      index,
-      content_block: { type: 'redacted_thinking', data },
-    },
-    { type: 'content_block_stop', index },
-  ]
-}
-
-function text(index: number, value: string) {
-  return [
-    {
-      type: 'content_block_start',
-      index,
-      content_block: { type: 'text', text: '' },
-    },
-    {
-      type: 'content_block_delta',
-      index,
-      delta: { type: 'text_delta', text: value },
-    },
-    { type: 'content_block_stop', index },
-  ]
-}
-
-function toolUse(index: number, name: string) {
-  return [
-    {
-      type: 'content_block_start',
-      index,
-      content_block: { type: 'tool_use', id: 'toolu_1', name, input: {} },
-    },
-    {
-      type: 'content_block_delta',
-      index,
-      delta: { type: 'input_json_delta', partial_json: '{}' },
-    },
-    { type: 'content_block_stop', index },
-  ]
-}
-
-function end(stopReason: string) {
-  return [
-    {
-      type: 'message_delta',
-      delta: { stop_reason: stopReason, stop_sequence: null },
-      usage: { output_tokens: 20 },
-    },
-    { type: 'message_stop' },
-  ]
-}
-
-function sse(events: Array<SseEvent>): Response {
-  return new Response(
-    events
-      .map(
-        (event) => `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`,
-      )
-      .join(''),
-    { status: 200, headers: { 'Content-Type': 'text/event-stream' } },
-  )
-}
-
-type Body = {
-  messages: Array<{ role: string; content: unknown }>
-}
-
-/** Answers each call with the next scripted stream and records its body. */
-function scriptedFetch(streams: Array<Array<SseEvent>>) {
-  const bodies: Array<Body> = []
-  const fetchImpl: typeof fetch = async (input, init) => {
-    const req = input instanceof Request ? input : new Request(input, init)
-    bodies.push(JSON.parse(await req.text()))
-    return sse(
-      streams[bodies.length - 1] ?? [
-        messageStart,
-        ...text(0, 'Done.'),
-        ...end('end_turn'),
-      ],
-    )
-  }
-  return { bodies, fetchImpl }
-}
-
-function blocks(body: Body | undefined, role: string) {
-  const message = body?.messages.filter((m) => m.role === role).at(-1)
-  return Array.isArray(message?.content)
-    ? (message.content as Array<Record<string, unknown>>)
-    : []
-}
-
-/**
- * Three scripted runs, answered by a capturing `fetch`:
- *
- * - `nextTurn`: a redacted block and text, then a second turn through
- *   `StreamProcessor`, `uiMessagesToWire`, and `chatParamsFromRequestBody`,
- *   as a browser client and `/api/chat` do.
- * - `sameRun`: a redacted block and a tool call. The run's second request
- *   continues after the tool.
- * - `toolError`: the tool throws. The run's second request carries the result.
- */
-export const Route = createFileRoute('/api/anthropic-redacted-thinking-wire')({
-  server: {
-    handlers: {
-      POST: async () => {
-        try {
-          const nextTurn = scriptedFetch([
-            [
-              messageStart,
-              ...redacted(0, 'opaque-1'),
-              ...text(1, 'Hello.'),
-              ...end('end_turn'),
-            ],
-          ])
-          const adapter = createAnthropicChat('claude-sonnet-4-5', DUMMY_KEY, {
-            fetch: nextTurn.fetchImpl,
-          })
-          const client = new StreamProcessor({})
-          for (const [index, prompt] of ['Hi', 'Say it again'].entries()) {
-            client.addUserMessage(prompt)
-            const params = await chatParamsFromRequestBody({
-              threadId: 'redacted-thinking',
-              runId: `redacted-thinking-${index + 1}`,
-              // `JSON.parse(JSON.stringify(...))` stands in for the HTTP hop.
-              messages: JSON.parse(
-                JSON.stringify(uiMessagesToWire(client.getMessages())),
-              ),
-              tools: [],
-              context: [],
-            })
-            for await (const chunk of chat({
-              ...createChatOptions({ adapter }),
-              messages: params.messages,
-              stream: true,
-            })) {
-              client.processChunk(chunk)
-            }
-            client.finalizeStream()
-          }
-
-          const sameRun = scriptedFetch([
-            [
-              messageStart,
-              ...redacted(0, 'opaque-2'),
-              ...toolUse(1, 'check'),
-              ...end('tool_use'),
-            ],
-          ])
-          for await (const _ of chat({
-            ...createChatOptions({
-              adapter: createAnthropicChat('claude-sonnet-4-5', DUMMY_KEY, {
-                fetch: sameRun.fetchImpl,
-              }),
-            }),
-            messages: [{ role: 'user', content: 'Check it' }],
-            tools: [
-              {
-                name: 'check',
-                description: 'Check something.',
-                execute: () => 'ok',
-              },
-            ],
-            stream: true,
-          })) {
-            // consume
-          }
-
-          const toolError = scriptedFetch([
-            [messageStart, ...toolUse(0, 'fail'), ...end('tool_use')],
-          ])
-          for await (const _ of chat({
-            ...createChatOptions({
-              adapter: createAnthropicChat('claude-sonnet-4-5', DUMMY_KEY, {
-                fetch: toolError.fetchImpl,
-              }),
-            }),
-            messages: [{ role: 'user', content: 'Try it' }],
-            tools: [
-              {
-                name: 'fail',
-                description: 'Always fails.',
-                execute: () => {
-                  throw new Error('Tool broke')
-                },
-              },
-            ],
-            stream: true,
-          })) {
-            // consume
-          }
-
-          return Response.json({
-            ok: true,
-            nextTurnBlocks: blocks(nextTurn.bodies[1], 'assistant'),
-            sameRunBlocks: blocks(sameRun.bodies[1], 'assistant').map(
-              (block) => block.type,
-            ),
-            toolResult: blocks(toolError.bodies[1], 'user').find(
-              (block) => block.type === 'tool_result',
-            ),
-          })
-        } catch (error) {
-          return Response.json({
-            ok: false,
-            error: error instanceof Error ? error.message : String(error),
-          })
-        }
-      },
-    },
-  },
-})
diff --git a/testing/e2e/tests/anthropic-redacted-thinking-wire.spec.ts b/testing/e2e/tests/anthropic-redacted-thinking-wire.spec.ts
deleted file mode 100644
index d203d57115..0000000000
--- a/testing/e2e/tests/anthropic-redacted-thinking-wire.spec.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-import { test, expect } from './fixtures'
-
-/**
- * Claude encrypts some thinking as a `redacted_thinking` block with opaque
- * `data`. The next request must send that block back unchanged, and a failed
- * tool result must say `is_error: true`.
- * `/api/anthropic-redacted-thinking-wire` scripts the responses and returns
- * what the follow-up requests sent.
- */
-test.describe('anthropic — redacted thinking and tool errors on the wire', () => {
-  test('the next turn, the same run, and a failed tool send them back', async ({
-    request,
-  }) => {
-    const response = await request.post('/api/anthropic-redacted-thinking-wire')
-    expect(response.ok()).toBe(true)
-    const result = (await response.json()) as {
-      ok: boolean
-      error?: string
-      nextTurnBlocks: Array<Record<string, unknown>>
-      sameRunBlocks: Array<string>
-      toolResult?: Record<string, unknown>
-    }
-    if (!result.ok) throw new Error(`Route failed: ${result.error}`)
-
-    // A new turn from the client history: the block crossed the wire.
-    expect(result.nextTurnBlocks).toEqual([
-      { type: 'redacted_thinking', data: 'opaque-1' },
-      { type: 'text', text: 'Hello.' },
-    ])
-
-    // The same run continues after the tool, with the block first.
-    expect(result.sameRunBlocks).toEqual(['redacted_thinking', 'tool_use'])
-
-    // The failed tool is marked as an error.
-    expect(result.toolResult).toMatchObject({
-      tool_use_id: 'toolu_1',
-      is_error: true,
-    })
-  })
-})
diff --git a/testing/e2e/tests/tools-test/server-client-sequence.spec.ts b/testing/e2e/tests/tools-test/server-client-sequence.spec.ts
index ed6d8c428a..a7c64426cf 100644
--- a/testing/e2e/tests/tools-test/server-client-sequence.spec.ts
+++ b/testing/e2e/tests/tools-test/server-client-sequence.spec.ts
@@ -211,40 +211,6 @@ test.describe('Server-Client Sequence E2E Tests', () => {
     expect(toolNames).toContain('get_time')
   })
 
-  test('parallel server tools run at the same time, results in call order', async ({
-    page,
-    testId,
-    aimockPort,
-  }) => {
-    await selectScenario(page, 'parallel-server-timing', testId, aimockPort)
-    await runTest(page)
-    await waitForTestComplete(page, 15000, 2)
-
-    const messages = await getMessages(page)
-    const results: Array<{ toolCallId: string; content: string }> = messages
-      .flatMap((message) => message.parts ?? [])
-      .filter((part) => part.type === 'tool-result')
-    const calls: Array<{ id: string; name: string }> = messages
-      .flatMap((message) => message.parts ?? [])
-      .filter((part) => part.type === 'tool-call')
-    const nameOf = (toolCallId: string) =>
-      calls.find((call) => call.id === toolCallId)?.name
-    const timing = (name: string) => {
-      const result = results.find((r) => nameOf(r.toolCallId) === name)
-      return JSON.parse(result?.content ?? '{}')
-    }
-
-    // Each tool waits 300 ms. Run one after another, they cannot overlap.
-    const weather = timing('get_weather')
-    const time = timing('get_time')
-    expect(weather.startedAt).toBeLessThan(time.endedAt)
-    expect(time.startedAt).toBeLessThan(weather.endedAt)
-    expect(results.map((result) => nameOf(result.toolCallId))).toEqual([
-      'get_weather',
-      'get_time',
-    ])
-  })
-
   test('single server tool completes', async ({ page, testId, aimockPort }) => {
     await selectScenario(page, 'server-tool-single', testId, aimockPort)
     await runTest(page)

From 97954de37e3367c47783cbbd6f0c0b83f82df75d Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 12:11:39 +0200
Subject: [PATCH 109/286] test(ai-sandbox): call at most 3 coding agents in one
 step in the plan-mode test

Tool calls in one step now run at the same time, and the harness runs at
most 3 subagents at once, so the 4th call got a limit error.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-sandbox/tests/coding-agents.test.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/ai-sandbox/tests/coding-agents.test.ts b/packages/ai-sandbox/tests/coding-agents.test.ts
index 3d9dfc1332..9b7e4287cc 100644
--- a/packages/ai-sandbox/tests/coding-agents.test.ts
+++ b/packages/ai-sandbox/tests/coding-agents.test.ts
@@ -344,13 +344,15 @@ describe('codingAgents', () => {
     const other = codingAgent('grok-build')
     const custom = codingAgent('acp')
     const { host, session } = await open({
+      // Two steps: tool calls in one step run at the same time, and the
+      // harness runs at most 3 subagents at once.
       leadSteps: [
         [
           ['claude_code', 'look'],
           ['codex', 'look'],
           ['grok', 'look'],
-          ['custom', 'look'],
         ],
+        [['custom', 'look']],
       ],
       agents: {
         claude_code: { adapter: claude.adapter },

From d996347a4cb030b13346e08030ee43ffa6a6ddfe Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 12:36:28 +0200
Subject: [PATCH 110/286] feat(examples): harness-cli model catalog, saved
 sessions, and a full-width header

- The header is as wide as the screen. It shows the session id, the
  features that are on, and the keys. The footer is one line of status.
- /model asks for the provider, then the model (OpenRouter asks for the
  vendor too). The models, context sizes, effort levels, and prices come
  from @tanstack/ai-models. /effort lists the levels the model has.
- Sessions are saved in ~/.tanstack-harness-example/sessions, with their
  model, effort, and plugin state. `--resume <id>` (or `--resume` for the
  newest) and /resume continue a session after a restart.
- A new session starts on the first provider with a saved or env key.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 examples/harness-cli/README.md             |  40 ++-
 examples/harness-cli/package.json          |   1 +
 examples/harness-cli/src/cli.ts            |  56 +++-
 examples/harness-cli/src/credentials.ts    |  56 ++--
 examples/harness-cli/src/harness.ts        | 214 +++++++-------
 examples/harness-cli/src/screen/footer.tsx |  55 ++--
 examples/harness-cli/src/screen/menu.tsx   |  10 +-
 examples/harness-cli/src/sessions.ts       | 171 ++++++++++++
 examples/harness-cli/src/store.ts          |  30 +-
 examples/harness-cli/src/tui.tsx           | 307 ++++++++++++++++++---
 pnpm-lock.yaml                             |   3 +
 11 files changed, 732 insertions(+), 211 deletions(-)
 create mode 100644 examples/harness-cli/src/sessions.ts

diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index dd8c5792ee..8be09a3f21 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -10,7 +10,7 @@ From the repo root:
 2. `pnpm build:all` (the example uses the local packages)
 3. `pnpm --filter harness-cli-example start`
 4. Type `/connect` and pick OpenRouter. It signs you in with the browser, with no key to paste.
-5. Type `/model` and pick `openai/gpt-6-astra`.
+5. Type `/model`, pick OpenRouter, then `openai`, then `openai/gpt-6-astra`.
 
 Now send a message.
 
@@ -23,24 +23,26 @@ You do not need a `.env` file. Type `/connect` and pick a provider from the list
 - `/connect openai` skips the list. `/keys` shows where each key comes from (saved, an env var, or missing).
 - `/disconnect` removes a saved key.
 
-The app saves the key in `~/.tanstack-harness-example/credentials.json`. It shows only the last 4 characters of a key. The footer shows which features are on, and it changes when you connect a provider.
+The app saves the key in `~/.tanstack-harness-example/credentials.json`, so you connect once. It shows only the last 4 characters of a key. The header shows which features are on, and it changes when you connect a provider.
 
-| Provider id  | Adds                                                                                                |
-| ------------ | --------------------------------------------------------------------------------------------------- |
-| `openai`     | `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna`, images, speech, Sora video, and voice input               |
-| `anthropic`  | `claude-opus-5-5`, `claude-fable-5-1`, `claude-sonnet-5`, `claude-haiku-4-5`                        |
-| `grok`       | `grok-4.7`, `grok-4.6`, video with Grok Imagine, and voice input                                    |
-| `fal`        | songs and sound effects                                                                             |
-| `openrouter` | `openai/gpt-6-astra`, `anthropic/claude-opus-5.5`, `google/gemini-3.1-pro-preview`, `x-ai/grok-4.7` |
+| Provider id  | Adds                                                                        |
+| ------------ | --------------------------------------------------------------------------- |
+| `openai`     | the OpenAI chat models, images, speech, Sora video, and voice input         |
+| `anthropic`  | the Claude models                                                           |
+| `grok`       | the xAI Grok models, video with Grok Imagine, and voice input               |
+| `fal`        | songs and sound effects                                                     |
+| `openrouter` | the OpenRouter models of every vendor (OpenAI, Anthropic, Google, and more) |
 
-If a provider has no key, its models and tools stop and tell you which `/connect` to run. If no key is set in the env, `/model demo` answers without a key.
+The model lists come from `@tanstack/ai-models`: each chat model that the provider's adapter knows and that the catalog has.
+
+If a provider has no key, its models and tools stop and tell you which `/connect` to run. With no key at all, `/model` lists a Demo model that answers without a key.
 
 ### Developer shortcut: a `.env` file
 
 1. Copy `.env.example` to `.env`.
 2. Set the keys that you have.
 
-An env var works when no key is saved. The first model with an env key starts. Audio files that you attach with `@file` become text only when `OPENAI_API_KEY` is set. Voice messages use the saved key.
+An env var works when no key is saved. A new session starts on the first provider that has a key, saved or from the env. Audio files that you attach with `@file` become text only when `OPENAI_API_KEY` is set. Voice messages use the saved key.
 
 ### Ship it to your users
 
@@ -96,10 +98,20 @@ When `claude` and `codex` are on the PATH, the agent can call them. They work in
 
 ## Pick the model and the effort
 
-- `/model` opens a list of the models, with the provider and the context size of each. `/model gpt-6-luna` switches at once. The change applies at the next turn.
-- `/effort` sets how hard the model thinks: `default` (the model decides), `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. It sets `chat({ reasoning })`, so a level the model does not have moves to the nearest one it has.
+- `/model` asks for the provider, then the model. OpenRouter asks for the vendor between them. Each model shows its context size, its effort levels, and its price, from `@tanstack/ai-models`. `/model gpt-6-luna` switches at once. The change applies at the next turn.
+- `/effort` lists the levels the current model has, and `default` (the model decides). It sets `chat({ reasoning })`. When you switch to a model that does not have the level, the nearest level it has is used, and the footer shows it.
 - The footer shows the model, the effort, how full the context is, the tokens in and out, and the model calls.
 
+## Continue a session
+
+Each start is a new session. The header shows its id, and when you quit, the screen prints the command to continue it.
+
+- `pnpm --filter harness-cli-example start --resume 3f2a9c1d` continues session `3f2a9c1d`.
+- `--resume` with no id continues the newest session.
+- `/resume` lists the saved sessions with what you said first. Pick one, and the screen opens it.
+
+A session keeps its messages, its model and effort, and its todos and usage. The sessions are in `~/.tanstack-harness-example/sessions/`, and their settings in `metadata.json` in the same folder. The media of a session is in memory only, and the files the screen saved stay in `example-coder-media`.
+
 ## The screen
 
 - Answers show as markdown: lists, tables, and highlighted code. A Mermaid block shows as a chart drawn in text. In demo mode, ask `draw me a chart`.
@@ -128,4 +140,4 @@ The screen is `src/tui.tsx` and its parts in `src/screen/`, plain example code o
 
 1. In one terminal: `pnpm --filter harness-cli-example dashboard`. It prints a sign-in link.
 2. In another: `pnpm --filter harness-cli-example start --dashboard http://127.0.0.1:8790`. It prints a pairing code.
-3. Open the sign-in link, approve the code, and open the `main` session. Messages you send there reach the agent.
+3. Open the sign-in link, approve the code, and open the session with the id that the header shows. Messages you send there reach the agent.
diff --git a/examples/harness-cli/package.json b/examples/harness-cli/package.json
index 5007fc9041..b9be10ab7a 100644
--- a/examples/harness-cli/package.json
+++ b/examples/harness-cli/package.json
@@ -22,6 +22,7 @@
     "@tanstack/ai-harness-cli": "workspace:*",
     "@tanstack/ai-isolate-quickjs": "workspace:*",
     "@tanstack/ai-mcp": "workspace:*",
+    "@tanstack/ai-models": "workspace:*",
     "@tanstack/ai-openai": "workspace:*",
     "@tanstack/ai-openrouter": "workspace:*",
     "@tanstack/ai-persistence": "workspace:*",
diff --git a/examples/harness-cli/src/cli.ts b/examples/harness-cli/src/cli.ts
index 24144390ca..0fd06a6d2a 100644
--- a/examples/harness-cli/src/cli.ts
+++ b/examples/harness-cli/src/cli.ts
@@ -1,7 +1,59 @@
 import { runCli } from '@tanstack/ai-harness-cli'
 import { assistant } from './harness'
+import { hasSession, listSessions, newSessionId } from './sessions'
 import { persistence } from './store'
-import { runTui } from './tui'
+import { runTui, takeNextSession } from './tui'
+
+/**
+ * The session to open first: `--resume <id>`, `--resume` alone for the
+ * newest saved session, `--thread <id>`, else a new session. The other
+ * options go to runCli.
+ */
+async function firstSession(argv: Array<string>) {
+  const at = argv.findIndex(
+    (arg) => arg === '--resume' || arg.startsWith('--resume='),
+  )
+  if (at === -1) {
+    const thread = argv.indexOf('--thread')
+    const given = thread === -1 ? undefined : argv[thread + 1]
+    return { argv, threadId: given ?? newSessionId() }
+  }
+  const [flag = ''] = argv.splice(at, 1)
+  const next = argv[at]
+  const id = flag.startsWith('--resume=')
+    ? flag.slice('--resume='.length)
+    : next !== undefined && !next.startsWith('-')
+      ? argv.splice(at, 1)[0]
+      : (await listSessions(1))[0]?.id
+  if (id === undefined || !(await hasSession(id))) {
+    process.stderr.write(
+      id === undefined
+        ? 'No saved session yet.\n'
+        : `No saved session ${id}.\n`,
+    )
+    process.exit(1)
+  }
+  return { argv, threadId: id }
+}
+
+const first = await firstSession(process.argv.slice(2))
+let threadId = first.threadId
 
 // A terminal shows the Ink screen from ./tui. Piped input uses line mode.
-process.exitCode = await runCli(assistant, { persistence, ui: runTui })
+// `/resume` closes the screen, and the loop opens the session it picked.
+for (;;) {
+  process.exitCode = await runCli(assistant, {
+    persistence,
+    ui: runTui,
+    // The last `--thread` wins.
+    argv: [...first.argv, '--thread', threadId],
+  })
+  const next = takeNextSession()
+  if (next === undefined) break
+  threadId = next
+}
+if (await hasSession(threadId)) {
+  process.stderr.write(
+    `Continue this session with: pnpm start --resume ${threadId}\n`,
+  )
+}
diff --git a/examples/harness-cli/src/credentials.ts b/examples/harness-cli/src/credentials.ts
index 76d30a3a2e..69d11ddb31 100644
--- a/examples/harness-cli/src/credentials.ts
+++ b/examples/harness-cli/src/credentials.ts
@@ -4,15 +4,17 @@ import { dirname, join } from 'node:path'
 import { defineCredentialStore } from '@tanstack/ai-persistence'
 import type { Credential } from '@tanstack/ai-persistence'
 
+/** The folder in your home folder where the example saves its files. */
+export const SAVE_DIR = join(homedir(), '.tanstack-harness-example')
+
 /**
- * Sign-ins (Notion, Linear) and model keys (`/connect openai`) saved in a
- * file in your home folder, so they survive a restart. The file is readable
- * by your user only. A production store would encrypt the values.
+ * Values in groups, saved as JSON in `file`. `load` gives `{}` for a missing
+ * or broken file. `update` changes the saved values. Updates run one after
+ * the other, so a second update never loses the first.
  */
-export function fileCredentials(
-  file = join(homedir(), '.tanstack-harness-example', 'credentials.json'),
-) {
-  type Saved = Record<string, Record<string, Credential>>
+export function jsonFile<TValue>(file: string) {
+  type Saved = Record<string, Record<string, TValue>>
+  let updating = Promise.resolve()
   const load = async (): Promise<Saved> => {
     try {
       const parsed: unknown = JSON.parse(await readFile(file, 'utf8'))
@@ -23,25 +25,39 @@ export function fileCredentials(
       return {}
     }
   }
-  const save = async (all: Saved) => {
-    await mkdir(dirname(file), { recursive: true })
-    await writeFile(file, JSON.stringify(all, null, 2), { mode: 0o600 })
+  const update = (change: (all: Saved) => void) => {
+    const run = updating.then(async () => {
+      const all = await load()
+      change(all)
+      await mkdir(dirname(file), { recursive: true })
+      await writeFile(file, JSON.stringify(all, null, 2), { mode: 0o600 })
+    })
+    updating = run.catch(() => {})
+    return run
   }
+  return { load, update }
+}
+
+/**
+ * Sign-ins (Notion, Linear) and model keys (`/connect openai`) saved in a
+ * file in your home folder, so they survive a restart. The file is readable
+ * by your user only. A production store would encrypt the values.
+ */
+export function fileCredentials(file = join(SAVE_DIR, 'credentials.json')) {
+  const { load, update } = jsonFile<Credential>(file)
   const owner = (scope: { userId?: string; tenantId?: string }) =>
     `${scope.tenantId ?? '-'}/${scope.userId ?? '-'}`
 
   return defineCredentialStore({
     get: async (scope, id) => (await load())[owner(scope)]?.[id] ?? null,
-    set: async (scope, id, credential) => {
-      const all = await load()
-      all[owner(scope)] = { ...all[owner(scope)], [id]: credential }
-      await save(all)
-    },
-    delete: async (scope, id) => {
-      const all = await load()
-      delete all[owner(scope)]?.[id]
-      await save(all)
-    },
+    set: (scope, id, credential) =>
+      update((all) => {
+        all[owner(scope)] = { ...all[owner(scope)], [id]: credential }
+      }),
+    delete: (scope, id) =>
+      update((all) => {
+        delete all[owner(scope)]?.[id]
+      }),
     list: async (scope) =>
       Object.entries((await load())[owner(scope)] ?? {}).map(
         ([id, credential]) => ({
diff --git a/examples/harness-cli/src/harness.ts b/examples/harness-cli/src/harness.ts
index b3ea1182a7..b9ec5f295f 100644
--- a/examples/harness-cli/src/harness.ts
+++ b/examples/harness-cli/src/harness.ts
@@ -15,20 +15,26 @@ import {
   usage,
   workspaceTools,
 } from '@tanstack/ai-harness/plugins'
-import { createAnthropicChat } from '@tanstack/ai-anthropic'
+import { ANTHROPIC_MODELS, createAnthropicChat } from '@tanstack/ai-anthropic'
 import { anthropicByok } from '@tanstack/ai-anthropic/byok'
 import { claudeCodeText } from '@tanstack/ai-claude-code'
 import { codeMode } from '@tanstack/ai-code-mode/harness'
 import { codexText } from '@tanstack/ai-codex'
 import { falByok } from '@tanstack/ai-fal/byok'
 import { mcpConnector } from '@tanstack/ai-mcp/connector'
-import { createGrokText } from '@tanstack/ai-grok'
+import { GROK_CHAT_MODELS, createGrokText } from '@tanstack/ai-grok'
 import { grokByok } from '@tanstack/ai-grok/byok'
 import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs'
-import { createOpenaiChat, openaiTranscription } from '@tanstack/ai-openai'
+import { getModel, supportedReasoningLevels } from '@tanstack/ai-models'
+import {
+  OPENAI_CHAT_MODELS,
+  createOpenaiChat,
+  openaiTranscription,
+} from '@tanstack/ai-openai'
 import { openaiByok } from '@tanstack/ai-openai/byok'
 import { createOpenRouterText } from '@tanstack/ai-openrouter'
 import { openrouterByok } from '@tanstack/ai-openrouter/byok'
+import { OPENROUTER_CHAT_MODELS } from '@tanstack/ai-openrouter/model-meta'
 import { openrouterSignIn } from '@tanstack/ai-openrouter/pkce'
 import {
   defineSandbox,
@@ -47,9 +53,10 @@ import {
   videoAgent,
 } from './media'
 import { effortPicker } from './effort'
-import { envKey } from './store'
+import { envKey, providerKey } from './store'
 import type { AnyTextAdapter, KeyedAdapter } from '@tanstack/ai'
-import type { ByokProvider, ProviderId } from '@tanstack/ai/byok'
+import type { ModelRecord } from '@tanstack/ai-models'
+import type { ByokProvider } from '@tanstack/ai/byok'
 
 // The agent works in ./playground, so it cannot touch the rest of your disk.
 const root = fileURLToPath(new URL('../playground', import.meta.url))
@@ -141,108 +148,127 @@ function demoModel(): AnyTextAdapter {
 }
 
 /** Is a key for `provider` in the environment (the `.env` shortcut)? */
-function hasEnvKey(provider: ByokProvider | ProviderId) {
-  return typeof provider !== 'string' && envKey(provider) !== null
+function hasEnvKey(provider: ByokProvider) {
+  return envKey(provider) !== null
 }
 
-const openai = (model: Parameters<typeof createOpenaiChat>[0]) =>
+const openai = (model: (typeof OPENAI_CHAT_MODELS)[number]) =>
   keyedAdapter(openaiByok, (key) => createOpenaiChat(model, key))
-const anthropic = (model: Parameters<typeof createAnthropicChat>[0]) =>
+const anthropic = (model: (typeof ANTHROPIC_MODELS)[number]) =>
   keyedAdapter(anthropicByok, (key) => createAnthropicChat(model, key))
-const grok = (model: Parameters<typeof createGrokText>[0]) =>
+const grok = (model: (typeof GROK_CHAT_MODELS)[number]) =>
   keyedAdapter(grokByok, (key) => createGrokText(model, key))
-const openrouter = (model: Parameters<typeof createOpenRouterText>[0]) =>
+const openrouter = (model: (typeof OPENROUTER_CHAT_MODELS)[number]) =>
   keyedAdapter(openrouterByok, (key) => createOpenRouterText(model, key))
 
+/** A model `/model` can pick. */
+export interface ModelEntry {
+  id: string
+  /** The key provider to connect, for example `openai` or `grok`. */
+  provider: string
+  record: ModelRecord
+  adapter: KeyedAdapter<AnyTextAdapter>
+}
+
 /**
- * The models `/model <name>` can switch to, by their real model id. Each one
- * is built for each turn with the user's own key: the key saved with
- * `/connect <provider>`, else the env var. A model without a key asks the
- * user to connect.
+ * The models of one provider: each chat model its adapter knows that the
+ * `@tanstack/ai-models` catalog has too. The catalog gives the context size,
+ * the reasoning levels, and the price. Sorted by id, the newest version of
+ * each family first (`claude-opus-5-5` before `claude-opus-4-8`).
  */
-const models = {
-  'gpt-6-astra': openai('gpt-6-astra'),
-  'gpt-6-sol': openai('gpt-6-sol'),
-  'gpt-6-luna': openai('gpt-6-luna'),
-  'claude-opus-5-5': anthropic('claude-opus-5-5'),
-  'claude-fable-5-1': anthropic('claude-fable-5-1'),
-  'claude-sonnet-5': anthropic('claude-sonnet-5'),
-  'claude-haiku-4-5': anthropic('claude-haiku-4-5'),
-  'grok-4.7': grok('grok-4.7'),
-  'grok-4.6': grok('grok-4.6'),
-  'openai/gpt-6-astra': openrouter('openai/gpt-6-astra'),
-  'anthropic/claude-opus-5.5': openrouter('anthropic/claude-opus-5.5'),
-  'google/gemini-3.1-pro-preview': openrouter('google/gemini-3.1-pro-preview'),
-  'x-ai/grok-4.7': openrouter('x-ai/grok-4.7'),
+function providerModels<TModel extends string>(
+  catalogId: string,
+  byok: ByokProvider,
+  ids: ReadonlyArray<TModel>,
+  adapter: (model: TModel) => KeyedAdapter<AnyTextAdapter>,
+  start: TModel,
+) {
+  const models = ids.flatMap((id): Array<ModelEntry> => {
+    const record = getModel(catalogId, id)
+    return record
+      ? [{ id, provider: byok.id, record, adapter: adapter(id) }]
+      : []
+  })
+  return {
+    id: byok.id,
+    label: byok.label,
+    byok,
+    start,
+    models: models.sort((a, b) =>
+      b.id.localeCompare(a.id, 'en', { numeric: true }),
+    ),
+  }
 }
 
-// The first model with an env key starts, so a `.env` works as before. The
-// saved keys belong to a session, so without an env key `gpt-6-astra`
-// starts, and the first message asks the user to run /connect.
-const envModel = Object.entries(models).find(([, model]) =>
-  hasEnvKey(model.provider),
-)
-const startModel = envModel?.[0] ?? 'gpt-6-astra'
-// Any of the models: the harness, /compact, and /goal take this common type.
-const main: KeyedAdapter<AnyTextAdapter> =
-  envModel?.[1] ?? models['gpt-6-astra']
-// With no env key at all, `/model demo` answers without a key.
-const choices = { ...models, ...(envModel ? {} : { demo: demoModel() }) }
+/**
+ * The models `/model` can switch to, by provider and by their real model id.
+ * Each one is built for each turn with the user's own key: the key saved
+ * with `/connect <provider>`, else the env var. A model without a key asks
+ * the user to connect.
+ */
+export const modelProviders = [
+  providerModels(
+    'openai',
+    openaiByok,
+    OPENAI_CHAT_MODELS,
+    openai,
+    'gpt-6-astra',
+  ),
+  providerModels(
+    'anthropic',
+    anthropicByok,
+    ANTHROPIC_MODELS,
+    anthropic,
+    'claude-opus-5-5',
+  ),
+  providerModels('xai', grokByok, GROK_CHAT_MODELS, grok, 'grok-4.7'),
+  providerModels(
+    'openrouter',
+    openrouterByok,
+    OPENROUTER_CHAT_MODELS,
+    openrouter,
+    'openai/gpt-6-astra',
+  ),
+]
 
 /**
- * What the screen shows for each model: the provider that must be connected,
- * the size of its context window (from each provider's model-meta), and
- * whether `/effort` can set how hard it thinks.
+ * Each model by its id: the provider that must be connected, its catalog
+ * record (context size, reasoning levels, price), and its adapter. The ids
+ * of the providers do not overlap: OpenRouter ids start with the vendor.
  */
-export const modelInfo: Record<
-  string,
-  { provider: string; contextWindow: number; effort: boolean }
-> = {
-  'gpt-6-astra': { provider: 'openai', contextWindow: 1_050_000, effort: true },
-  'gpt-6-sol': { provider: 'openai', contextWindow: 1_050_000, effort: true },
-  'gpt-6-luna': { provider: 'openai', contextWindow: 1_050_000, effort: true },
-  'claude-opus-5-5': {
-    provider: 'anthropic',
-    contextWindow: 1_000_000,
-    effort: true,
-  },
-  'claude-fable-5-1': {
-    provider: 'anthropic',
-    contextWindow: 1_000_000,
-    effort: true,
-  },
-  'claude-sonnet-5': {
-    provider: 'anthropic',
-    contextWindow: 1_000_000,
-    effort: true,
-  },
-  'claude-haiku-4-5': {
-    provider: 'anthropic',
-    contextWindow: 200_000,
-    effort: true,
-  },
-  'grok-4.7': { provider: 'grok', contextWindow: 500_000, effort: true },
-  'grok-4.6': { provider: 'grok', contextWindow: 500_000, effort: true },
-  'openai/gpt-6-astra': {
-    provider: 'openrouter',
-    contextWindow: 1_050_000,
-    effort: true,
-  },
-  'anthropic/claude-opus-5.5': {
-    provider: 'openrouter',
-    contextWindow: 1_000_000,
-    effort: true,
-  },
-  'google/gemini-3.1-pro-preview': {
-    provider: 'openrouter',
-    contextWindow: 1_048_576,
-    effort: true,
-  },
-  'x-ai/grok-4.7': {
-    provider: 'openrouter',
-    contextWindow: 500_000,
-    effort: true,
-  },
+export const modelInfo: Record<string, ModelEntry> = Object.fromEntries(
+  modelProviders.flatMap((provider) =>
+    provider.models.map((model) => [model.id, model]),
+  ),
+)
+
+// A new session starts on the first provider with a key: one saved with
+// /connect, or one in the env (a `.env` file). Without any key, `gpt-6-astra`
+// starts, and the first message asks the user to run /connect. A resumed
+// session keeps the model it had.
+const keyed = await Promise.all(
+  modelProviders.map(async (provider) =>
+    (await providerKey(provider.byok, 'startup')) === null ? [] : [provider],
+  ),
+)
+const startProvider = keyed.flat()[0]
+const startModel = startProvider?.start ?? 'gpt-6-astra'
+// The start model: the harness, /compact, /goal, and /agent haiku use it.
+const main: KeyedAdapter<AnyTextAdapter> = modelInfo[startModel].adapter
+// With no key at all, `/model demo` answers without a key.
+const choices = {
+  ...Object.fromEntries(
+    Object.values(modelInfo).map((model) => [model.id, model.adapter]),
+  ),
+  ...(startProvider ? {} : { demo: demoModel() }),
+}
+
+/** Does the model think, so `/effort` changes it? */
+export function reasons(model: string) {
+  const record = modelInfo[model]?.record
+  return record
+    ? supportedReasoningLevels(record).some((level) => level !== 'off')
+    : false
 }
 
 // `/connect openrouter` signs in with the browser: no key to paste, and one
@@ -476,7 +502,7 @@ export const assistant = defineHarness({
     todos(),
     providerKeys({ providers: keyProviders }),
     modelPicker({ choices, default: startModel }),
-    effortPicker({ reasons: (model) => modelInfo[model]?.effort === true }),
+    effortPicker({ reasons }),
     projectInstructions({ root }),
     compact({ adapter: main }),
     usage(),
diff --git a/examples/harness-cli/src/screen/footer.tsx b/examples/harness-cli/src/screen/footer.tsx
index 574933a9a2..89e1f0c0a9 100644
--- a/examples/harness-cli/src/screen/footer.tsx
+++ b/examples/harness-cli/src/screen/footer.tsx
@@ -1,7 +1,9 @@
-import { Box, Spacer, Text } from 'ink'
+import { Box, Text } from 'ink'
+import { REASONING_LEVELS } from '@tanstack/ai'
+import { clampReasoningLevel } from '@tanstack/ai-models'
 import { useSelector } from '@tanstack/react-store'
-import { features, modelInfo } from '../harness'
-import { PROVIDER_KEYS, USAGE, isOn, providerKeysIn, usageIn } from './keys'
+import { modelInfo, reasons } from '../harness'
+import { PROVIDER_KEYS, USAGE, providerKeysIn, usageIn } from './keys'
 import { ACCENT, compact } from './theme'
 import type { SessionView } from '@tanstack/ai-harness/view'
 
@@ -9,8 +11,8 @@ const BAR = 10
 
 /**
  * The status bar at the bottom: the model, how much of its context the
- * conversation fills, the tokens and model calls so far, and which features
- * are on. It follows the session live, so a `/connect` turns features on.
+ * conversation fills, and the tokens and model calls so far. It follows the
+ * session live. The features and the key hints are in the header.
  */
 export function Footer({ view }: { view: SessionView }) {
   const model = useSelector(view.store, (state) =>
@@ -29,24 +31,33 @@ export function Footer({ view }: { view: SessionView }) {
   const usage = usageIn(usageState)
   const keys = providerKeysIn(keysState)
   const info = modelInfo[model]
-  const window = info?.contextWindow
+  const window = info?.record.contextWindow
+  // The level the model gets: the adapter moves an effort the model does not
+  // have to the nearest one it has.
+  const level = REASONING_LEVELS.find((name) => name === effort)
+  const shownEffort =
+    info && level && reasons(model)
+      ? clampReasoningLevel(info.record, level)
+      : undefined
   const share = window ? Math.min(1, usage.contextTokens / window) : 0
   const filled = Math.round(share * BAR)
   const barColor = share > 0.8 ? 'red' : share > 0.5 ? 'yellow' : 'green'
   const needsKey =
     info !== undefined &&
     keys.find((key) => key.id === info.provider)?.state === 'missing'
+  // Each group keeps its width, and a group that does not fit goes to the
+  // next line.
   return (
-    <Box flexDirection="column">
-      <Box>
+    <Box flexWrap="wrap" columnGap={3}>
+      <Box flexShrink={0}>
         <Text color={needsKey ? 'red' : ACCENT} bold>{`◆ ${model}`}</Text>
         {needsKey ? (
           <Text color="red">{`  (run /connect ${info.provider})`}</Text>
         ) : null}
-        {typeof effort === 'string' && effort !== 'default' ? (
-          <Text dimColor>{`  effort ${effort}`}</Text>
-        ) : null}
-        <Text dimColor>{'   context '}</Text>
+        {shownEffort ? <Text dimColor>{`  effort ${shownEffort}`}</Text> : null}
+      </Box>
+      <Box flexShrink={0}>
+        <Text dimColor>{'context '}</Text>
         <Text>
           {compact(usage.contextTokens)}
           {window ? `/${compact(window)}` : ''}
@@ -59,26 +70,14 @@ export function Footer({ view }: { view: SessionView }) {
             <Text dimColor>{` ${Math.round(share * 100)}%`}</Text>
           </>
         ) : null}
-        <Text dimColor>{'   tokens in '}</Text>
+      </Box>
+      <Box flexShrink={0}>
+        <Text dimColor>{'tokens in '}</Text>
         <Text>{compact(usage.promptTokens)}</Text>
         <Text dimColor>{' out '}</Text>
         <Text>{compact(usage.completionTokens)}</Text>
-        <Text dimColor>{`   ${usage.turns} model calls`}</Text>
-      </Box>
-      <Box flexWrap="wrap">
-        {features.map((feature) => {
-          const on = isOn(feature, keys)
-          return (
-            <Text key={feature.name} color={on ? 'green' : 'gray'}>
-              {`${on ? '●' : '○'} ${feature.name}  `}
-            </Text>
-          )
-        })}
-        <Spacer />
-        <Text dimColor>
-          {'Ctrl+R talk   / commands   ↑↓ history   Esc cancel'}
-        </Text>
       </Box>
+      <Text dimColor>{`${usage.turns} model calls`}</Text>
     </Box>
   )
 }
diff --git a/examples/harness-cli/src/screen/menu.tsx b/examples/harness-cli/src/screen/menu.tsx
index de3c2e6bf1..4f222f96df 100644
--- a/examples/harness-cli/src/screen/menu.tsx
+++ b/examples/harness-cli/src/screen/menu.tsx
@@ -46,10 +46,12 @@ export function Menu({
         const isSelected = start + index === selected
         return (
           <Box key={item.id}>
-            <Text color={isSelected ? ACCENT : undefined} bold={isSelected}>
-              {`${isSelected ? '❯' : ' '} ${item.label.padEnd(width)}`}
-            </Text>
-            <Text color={item.current ? 'green' : 'gray'}>
+            <Box flexShrink={0}>
+              <Text color={isSelected ? ACCENT : undefined} bold={isSelected}>
+                {`${isSelected ? '❯' : ' '} ${item.label.padEnd(width)}`}
+              </Text>
+            </Box>
+            <Text color={item.current ? 'green' : 'gray'} wrap="truncate-end">
               {`  ${item.current ? '● ' : ''}${item.detail ?? ''}`}
             </Text>
           </Box>
diff --git a/examples/harness-cli/src/sessions.ts b/examples/harness-cli/src/sessions.ts
new file mode 100644
index 0000000000..435d941882
--- /dev/null
+++ b/examples/harness-cli/src/sessions.ts
@@ -0,0 +1,171 @@
+import { randomUUID } from 'node:crypto'
+import {
+  appendFile,
+  mkdir,
+  readFile,
+  readdir,
+  stat,
+  writeFile,
+} from 'node:fs/promises'
+import { join } from 'node:path'
+import { logMessageStore } from '@tanstack/ai-harness'
+import {
+  LogConflictError,
+  defineLogStore,
+  defineMetadataStore,
+} from '@tanstack/ai-persistence'
+import { SAVE_DIR, jsonFile } from './credentials'
+import type { ModelMessage } from '@tanstack/ai'
+import type { LogRecord } from '@tanstack/ai-persistence'
+
+/** One file for each session, in your home folder. */
+const SESSIONS_DIR = join(SAVE_DIR, 'sessions')
+const fileOf = (threadId: string) =>
+  join(SESSIONS_DIR, `${encodeURIComponent(threadId)}.jsonl`)
+
+/**
+ * The records of a session file. Each line is one batch of records. A crash
+ * while a line is written leaves a cut last line: it is removed with its
+ * batch, so a batch is in the file in full or not at all.
+ */
+async function readLog(file: string) {
+  const text = await readFile(file, 'utf8').catch(() => '')
+  const lines = text.split('\n').filter((line) => line !== '')
+  const records: Array<LogRecord> = []
+  for (const [index, line] of lines.entries()) {
+    try {
+      records.push(...(JSON.parse(line) as Array<LogRecord>))
+    } catch (error) {
+      if (index < lines.length - 1) throw error
+      await writeFile(file, lines.slice(0, -1).join('\n') + '\n')
+    }
+  }
+  return records
+}
+
+/**
+ * The session log, in files: the transcript, the inputs, and the events of
+ * each session, so a session survives a restart. It keeps each session in
+ * memory after the first read.
+ * ponytail: for one process. Two CLIs on one session need a store with
+ * locks, for example a database.
+ */
+function fileLog() {
+  const loaded = new Map<string, Promise<Array<LogRecord>>>()
+  const listeners = new Map<string, Set<() => void>>()
+  let appending = Promise.resolve()
+  const load = (threadId: string) => {
+    let log = loaded.get(threadId)
+    if (!log) {
+      log = readLog(fileOf(threadId))
+      loaded.set(threadId, log)
+    }
+    return log
+  }
+  return defineLogStore({
+    append: (threadId, seq, records) => {
+      const run = appending.then(async () => {
+        if (records.length === 0) return
+        const log = await load(threadId)
+        if (seq !== log.length + 1) throw new LogConflictError(threadId, seq)
+        const line = JSON.stringify(records)
+        await mkdir(SESSIONS_DIR, { recursive: true })
+        await appendFile(fileOf(threadId), `${line}\n`)
+        log.push(...(JSON.parse(line) as Array<LogRecord>))
+        for (const listener of [...(listeners.get(threadId) ?? [])]) {
+          listener()
+        }
+      })
+      appending = run.catch(() => {})
+      return run
+    },
+    read: async (threadId, options = {}) => {
+      const log = await load(threadId)
+      const after = options.after ?? 0
+      const end =
+        options.limit === undefined ? log.length : after + options.limit
+      return log.slice(after, end).map((record, index) => ({
+        seq: after + index + 1,
+        record: structuredClone(record),
+      }))
+    },
+    subscribe: (threadId, listener) => {
+      const set = listeners.get(threadId) ?? new Set()
+      listeners.set(threadId, set)
+      set.add(listener)
+      return () => {
+        set.delete(listener)
+      }
+    },
+  })
+}
+
+/** Each session's settings and plugin state (the model, the todos), in a file. */
+function fileMetadata() {
+  const { load, update } = jsonFile<unknown>(join(SAVE_DIR, 'metadata.json'))
+  return defineMetadataStore({
+    get: async (namespace, key) =>
+      structuredClone((await load())[namespace]?.[key] ?? null),
+    set: (namespace, key, value) =>
+      update((all) => {
+        all[namespace] = { ...all[namespace], [key]: value }
+      }),
+    delete: (namespace, key) =>
+      update((all) => {
+        delete all[namespace]?.[key]
+      }),
+  })
+}
+
+export const sessionLog = fileLog()
+export const sessionMetadata = fileMetadata()
+
+/** A new session id: short, so it is easy to type after `--resume`. */
+export const newSessionId = () => randomUUID().slice(0, 8)
+
+/** Is `threadId` a saved session? */
+export async function hasSession(threadId: string) {
+  return (await sessionLog.read(threadId, { limit: 1 })).length > 0
+}
+
+/** The first thing the user said in a session, on one line. */
+function titleOf(messages: ReadonlyArray<ModelMessage>) {
+  const content = messages.find((message) => message.role === 'user')?.content
+  const text =
+    typeof content === 'string'
+      ? content
+      : (content ?? []).flatMap((part) =>
+          part.type === 'text' ? [part.content] : [],
+        )
+  return [text].flat().join(' ').replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * The saved sessions, newest first, with what the user said first. A
+ * session with no message yet is left out. The threads of child agents
+ * (`<session>:<agent>`) are not sessions of their own.
+ * ponytail: it reads the files in full, newest first, until it has `limit`
+ * sessions. An index file is faster when there are many big sessions.
+ */
+export async function listSessions(limit = 20) {
+  const names = await readdir(SESSIONS_DIR).catch(() => [])
+  const files = await Promise.all(
+    names
+      .filter((name) => name.endsWith('.jsonl'))
+      .map(async (name) => ({
+        id: decodeURIComponent(name.slice(0, -'.jsonl'.length)),
+        updatedAt: (await stat(join(SESSIONS_DIR, name))).mtimeMs,
+      })),
+  )
+  const recent = files
+    .filter((file) => !file.id.includes(':'))
+    .sort((a, b) => b.updatedAt - a.updatedAt)
+  const messages = logMessageStore({ store: sessionLog })
+  const sessions: Array<{ id: string; updatedAt: number; title: string }> = []
+  for (const file of recent) {
+    if (sessions.length === limit) break
+    const title = titleOf(await messages.loadThread(file.id))
+    if (title !== '') sessions.push({ ...file, title })
+  }
+  return sessions
+}
diff --git a/examples/harness-cli/src/store.ts b/examples/harness-cli/src/store.ts
index 6e90175351..0e27cbd95b 100644
--- a/examples/harness-cli/src/store.ts
+++ b/examples/harness-cli/src/store.ts
@@ -1,21 +1,33 @@
 import {
-  composePersistence,
+  defineAIPersistence,
   memoryPersistence,
   retrieveBlob,
 } from '@tanstack/ai-persistence'
 import { fileCredentials } from './credentials'
+import { sessionLog, sessionMetadata } from './sessions'
 import type { ByokProvider } from '@tanstack/ai/byok'
 
 /** Sign-ins and the model keys you save with `/connect`, kept in a file. */
 const credentials = fileCredentials()
+const memory = memoryPersistence().stores
 
 /**
- * Everything in memory, except sign-ins and keys, which are kept in a file.
- * The memory stores also keep media: the files you send and the files agents
- * make.
+ * The sessions, their settings, and the sign-ins and keys are kept in files,
+ * so `--resume <id>` and `/resume` continue a session after a restart. The
+ * rest is in memory: the run records, the approvals, and the media (the
+ * files you send and the files agents make).
  */
-export const persistence = composePersistence(memoryPersistence(), {
-  overrides: { credentials },
+export const persistence = defineAIPersistence({
+  stores: {
+    log: sessionLog,
+    metadata: sessionMetadata,
+    credentials,
+    runs: memory.runs,
+    interrupts: memory.interrupts,
+    generationRuns: memory.generationRuns,
+    artifacts: memory.artifacts,
+    blobs: memory.blobs,
+  },
 })
 
 /** The bytes of a stored media file, or `undefined` when it is gone. */
@@ -32,9 +44,9 @@ export function envKey(provider: ByokProvider) {
 }
 
 /**
- * The key for `provider` that the session of `threadId` uses: the one you
- * saved with `/connect <id>`, else its env var, else `null`. The CLI opens
- * its session without a user, so the scope is the thread only.
+ * The key for `provider`: the one you saved with `/connect <id>`, else its
+ * env var, else `null`. The CLI opens its sessions without a user, so every
+ * session uses the same saved keys.
  */
 export async function providerKey(provider: ByokProvider, threadId: string) {
   const saved = await credentials.get({ threadId }, provider.id)
diff --git a/examples/harness-cli/src/tui.tsx b/examples/harness-cli/src/tui.tsx
index 96e8477164..16eea79f89 100644
--- a/examples/harness-cli/src/tui.tsx
+++ b/examples/harness-cli/src/tui.tsx
@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url'
 import { useEffect, useLayoutEffect, useReducer, useRef, useState } from 'react'
 import {
   Box,
+  Spacer,
   Static,
   Text,
   measureElement,
@@ -12,10 +13,20 @@ import {
   useBoxMetrics,
   useInput,
   usePaste,
+  useStdout,
   useWindowSize,
 } from 'ink'
 import { useSelector } from '@tanstack/react-store'
-import { assistant, features, keyProviders, modelInfo } from './harness'
+import { supportedReasoningLevels } from '@tanstack/ai-models'
+import {
+  assistant,
+  features,
+  keyProviders,
+  modelInfo,
+  modelProviders,
+  reasons,
+} from './harness'
+import { hasSession, listSessions } from './sessions'
 import {
   canTranscribe,
   chooseMicrophone,
@@ -36,6 +47,7 @@ import { Status } from './screen/status'
 import { ACCENT, compact } from './screen/theme'
 import type { ReactNode } from 'react'
 import type { DOMElement, RenderOptions } from 'ink'
+import type { ModelEntry } from './harness'
 import type { Recording, VoiceClip } from './voice'
 import type { Line } from './screen/editor'
 import type { MenuItem } from './screen/menu'
@@ -58,6 +70,7 @@ const SCREEN_COMMANDS = [
   { name: 'disconnect', description: 'Remove a key or a sign-in' },
   { name: 'model', description: 'Pick the model' },
   { name: 'effort', description: 'Pick how hard the model thinks' },
+  { name: 'resume', description: 'Continue a saved session' },
   { name: 'mic', description: 'Pick the microphone' },
   { name: 'open', description: 'Open a media file (default: the last one)' },
   { name: 'play', description: 'Play an audio or video file' },
@@ -142,51 +155,146 @@ function connectItems(state: SessionViewState): Array<MenuItem> {
   return [...providers, ...apps]
 }
 
-/** The rows of the `/model` picker, with the provider and the context size. */
-function modelItems(state: SessionViewState): Array<MenuItem> {
-  const entry = state.config.find((item) => item.key === 'model')
-  if (entry?.option.type !== 'select') return []
+const modelCount = (count: number) => `${count} model${count === 1 ? '' : 's'}`
+
+const currentModel = (state: SessionViewState) =>
+  String(state.config.find((item) => item.key === 'model')?.value ?? '')
+
+/** The context size, the effort levels, and the price of a model. */
+function modelDetail(model: ModelEntry) {
+  const { contextWindow, cost } = model.record
+  const levels = supportedReasoningLevels(model.record).filter(
+    (level) => level !== 'off',
+  )
+  return [
+    `${compact(contextWindow)} context`,
+    levels.length === 0
+      ? 'no effort setting'
+      : levels.length === 1
+        ? `effort ${levels[0]}`
+        : `effort ${levels[0]} to ${levels.at(-1)}`,
+    ...(cost.input > 0 ? [`$${cost.input}/$${cost.output} per 1M tokens`] : []),
+  ].join(', ')
+}
+
+/** The rows of a `/model` picker for these models. */
+function modelRows(
+  models: ReadonlyArray<ModelEntry>,
+  state: SessionViewState,
+): Array<MenuItem> {
+  const current = currentModel(state)
+  return models.map((model) => ({
+    id: model.id,
+    label: model.id,
+    current: model.id === current,
+    detail: modelDetail(model),
+  }))
+}
+
+/** The first `/model` step: the providers, then the demo model if it is on. */
+function providerItems(state: SessionViewState): Array<MenuItem> {
+  const current = currentModel(state)
   const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
-  return entry.option.options.map((name) => {
-    const info = modelInfo[name]
-    const missing = keys.some(
-      (key) => key.id === info?.provider && key.state === 'missing',
-    )
+  const rows = modelProviders.map((provider) => {
+    const missing =
+      keys.find((key) => key.id === provider.id)?.state === 'missing'
     return {
-      id: name,
-      label: name,
-      current: name === entry.value,
-      detail: info
-        ? `${info.provider}, ${compact(info.contextWindow)} context${missing ? `, needs /connect ${info.provider}` : ''}`
-        : 'no key needed',
+      id: provider.id,
+      label: provider.label,
+      current: modelInfo[current]?.provider === provider.id,
+      detail: `${modelCount(provider.models.length)}${missing ? `, needs /connect ${provider.id}` : ''}`,
     }
   })
+  const entry = state.config.find((item) => item.key === 'model')
+  const demo =
+    entry?.option.type === 'select' && entry.option.options.includes('demo')
+  return demo
+    ? [
+        ...rows,
+        {
+          id: 'demo',
+          label: 'Demo',
+          current: current === 'demo',
+          detail: 'answers without a key',
+        },
+      ]
+    : rows
+}
+
+/**
+ * The OpenRouter step between the provider and the model: the vendors. An
+ * alias vendor (`~anthropic`, its `latest` models) sorts after its vendor.
+ */
+function vendorItems(
+  models: ReadonlyArray<ModelEntry>,
+  state: SessionViewState,
+): Array<MenuItem> {
+  const current = currentModel(state)
+  const counts = new Map<string, number>()
+  for (const model of models) {
+    const [vendor = ''] = model.id.split('/')
+    counts.set(vendor, (counts.get(vendor) ?? 0) + 1)
+  }
+  return [...counts]
+    .sort(
+      ([a], [b]) =>
+        a.replace(/^~/, '').localeCompare(b.replace(/^~/, '')) ||
+        a.localeCompare(b),
+    )
+    .map(([vendor, count]) => ({
+      id: vendor,
+      label: vendor,
+      current: current.startsWith(`${vendor}/`),
+      detail: modelCount(count),
+    }))
 }
 
 const EFFORT_DETAIL: Record<string, string> = {
   default: 'the model decides',
-  low: 'fastest, fewest tokens',
+  off: 'no thinking',
+  minimal: 'the least thinking',
+  low: 'fast, few tokens',
   medium: 'balanced',
   high: 'thinks longer',
+  xhigh: 'thinks very long',
   max: 'the most the model can think',
 }
 
-/** The rows of the `/effort` picker, for the current model. */
+/** The rows of the `/effort` picker: the levels the current model has. */
 function effortItems(state: SessionViewState): Array<MenuItem> {
-  const entry = state.config.find((item) => item.key === 'effort')
-  if (entry?.option.type !== 'select') return []
-  const model = String(
-    state.config.find((item) => item.key === 'model')?.value ?? '',
-  )
-  const used = modelInfo[model]?.effort === true
-  return entry.option.options.map((name) => ({
+  const effort = state.config.find((item) => item.key === 'effort')?.value
+  const record = modelInfo[currentModel(state)]?.record
+  const levels = record ? supportedReasoningLevels(record) : []
+  return ['default', ...levels].map((name) => ({
     id: name,
     label: name,
-    current: name === entry.value,
-    detail: `${EFFORT_DETAIL[name] ?? ''}${used || name === 'default' ? '' : `, ${model} has no effort setting`}`,
+    current: name === effort,
+    detail: EFFORT_DETAIL[name] ?? '',
   }))
 }
 
+/** The rows of the `/resume` picker: the saved sessions, newest first. */
+async function sessionItems(state: SessionViewState): Promise<Array<MenuItem>> {
+  const sessions = await listSessions()
+  return sessions.map((session) => ({
+    id: session.id,
+    label: session.id,
+    current: session.id === state.threadId,
+    detail: `${new Date(session.updatedAt).toLocaleString(undefined, { dateStyle: 'short', timeStyle: 'short' })}  ${session.title.slice(0, 60)}`,
+  }))
+}
+
+// The session the user picked with /resume. The CLI opens it after the
+// screen closes.
+let nextSession: string | undefined
+
+/** The session `/resume` picked, once. `undefined` when the user quit. */
+export function takeNextSession() {
+  const next = nextSession
+  nextSession = undefined
+  return next
+}
+
 /** A list open over the input line, for example the `/connect` picker. */
 interface Picker {
   title: string
@@ -194,22 +302,74 @@ interface Picker {
   pick: (item: MenuItem) => unknown
 }
 
-function Header() {
+const HEADER_KEYS = 'Ctrl+R talk  / commands  ↑↓ history  Esc cancel'
+
+/**
+ * The header, as wide as the screen: the harness, the folder, which features
+ * are on, and the keys. It prints once, so the App prints the screen again
+ * when a feature turns on or off.
+ */
+function Header({ view, width }: { view: SessionView; width: number }) {
+  const keys = providerKeysIn(
+    useSelector(view.store, (state) => state.plugins[PROVIDER_KEYS]),
+  )
+  const threadId = useSelector(view.store, (state) => state.threadId)
+  const marks = features.map((feature) => {
+    const on = isOn(feature, keys)
+    return {
+      name: feature.name,
+      on,
+      text: `${on ? '●' : '○'} ${feature.name}  `,
+    }
+  })
+  // The border and the padding take 4 columns. The keys go next to the
+  // features when both fit, else on their own row.
+  const inner = width - 4
+  const marksWidth = marks.reduce((sum, mark) => sum + mark.text.length, 0)
+  const keysFit = marksWidth + HEADER_KEYS.length <= inner
   return (
     <Box
+      width={width}
       flexDirection="column"
       borderStyle="round"
       borderColor={ACCENT}
       paddingX={1}
     >
       <Box>
-        <Text color={ACCENT} bold>
-          ◆ TanStack AI
-        </Text>
-        <Text bold> harness</Text>
-        <Text dimColor>{`  ${assistant.name}`}</Text>
+        <Box flexShrink={0}>
+          <Text color={ACCENT} bold>
+            ◆ TanStack AI
+          </Text>
+          <Text bold> harness</Text>
+          <Text dimColor>{`  ${assistant.name}  session ${threadId}  `}</Text>
+        </Box>
+        <Spacer />
+        <Box flexShrink={1} minWidth={0}>
+          <Text dimColor wrap="truncate-start">
+            {process.cwd()}
+          </Text>
+        </Box>
       </Box>
-      <Text dimColor>{process.cwd()}</Text>
+      <Box>
+        <Box flexWrap="wrap" flexShrink={1}>
+          {marks.map((mark) => (
+            <Text key={mark.name} color={mark.on ? 'green' : 'gray'}>
+              {mark.text}
+            </Text>
+          ))}
+        </Box>
+        {keysFit && (
+          <>
+            <Spacer />
+            <Text dimColor>{HEADER_KEYS}</Text>
+          </>
+        )}
+      </Box>
+      {!keysFit && (
+        <Box justifyContent="flex-end">
+          <Text dimColor>{HEADER_KEYS}</Text>
+        </Box>
+      )}
     </Box>
   )
 }
@@ -288,10 +448,12 @@ function Measured({
 
 /** One printed row: the header, or a message that no longer changes. */
 function PrintedRow({
+  view,
   row,
   saved,
   width,
 }: {
+  view: SessionView
   row: Row
   saved: ReturnType<typeof useSavedMedia>['saved']
   width: number
@@ -299,7 +461,7 @@ function PrintedRow({
   return 'role' in row ? (
     <Message message={row} saved={saved} width={width} />
   ) : (
-    <Header />
+    <Header view={view} width={width} />
   )
 }
 
@@ -365,6 +527,23 @@ function App({ view }: { view: SessionView }) {
   const { height: liveHeight } = useBoxMetrics(live)
   const space = Math.max(0, screenRows - 1 - printedHeight - liveHeight)
 
+  // The header shows which features are on, but printed rows never change.
+  // So when a feature turns on or off (a /connect), clear the screen and
+  // print the header and the conversation again.
+  const { stdout } = useStdout()
+  const featureMarks = useSelector(view.store, (state) => {
+    const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
+    return features.map((feature) => (isOn(feature, keys) ? 1 : 0)).join('')
+  })
+  const shownMarks = useRef(featureMarks)
+  const [printRound, setPrintRound] = useState(0)
+  useEffect(() => {
+    if (featureMarks === shownMarks.current) return
+    shownMarks.current = featureMarks
+    if (stdout.isTTY) stdout.write('\x1b[2J\x1b[3J\x1b[H')
+    setPrintRound((round) => round + 1)
+  }, [featureMarks])
+
   const [voice, setVoiceState] = useState<VoiceState>('idle')
   // The phase in a ref too: key events come faster than React renders, and a
   // second Ctrl+R must see "starting" at once, or it starts a second recorder.
@@ -537,6 +716,43 @@ function App({ view }: { view: SessionView }) {
     })
   }
 
+  /** Pick a model of the provider `id`. OpenRouter asks for the vendor first. */
+  const pickModelOf = (id: string) => {
+    if (id === 'demo') return view.command('model', 'demo')
+    const provider = modelProviders.find((entry) => entry.id === id)
+    if (!provider) return
+    const state = view.store.get()
+    const pickModel = (title: string, models: ReadonlyArray<ModelEntry>) =>
+      openPicker({
+        title,
+        items: modelRows(models, state),
+        pick: (item) => view.command('model', item.id),
+      })
+    if (provider.id !== 'openrouter')
+      return pickModel(`${provider.label}: pick the model`, provider.models)
+    openPicker({
+      title: 'OpenRouter: pick the vendor',
+      items: vendorItems(provider.models, state),
+      pick: (vendor) =>
+        pickModel(
+          `OpenRouter: pick the ${vendor.id} model`,
+          provider.models.filter((model) =>
+            model.id.startsWith(`${vendor.id}/`),
+          ),
+        ),
+    })
+  }
+
+  /** Close the screen, and the CLI opens the saved session `id`. */
+  const resume = async (id: string) => {
+    if (id === view.store.get().threadId)
+      return view.notice('You are in this session.')
+    if (!(await hasSession(id)))
+      return view.notice(`No saved session ${id}. /resume lists them.`)
+    nextSession = id
+    exit()
+  }
+
   /** Enter: answer an approval or a question, run a screen command, or send. */
   const submit = async (line: Line) => {
     const text = line.text.trim()
@@ -608,17 +824,28 @@ function App({ view }: { view: SessionView }) {
       case '/model':
         if (arg) break
         return openPicker({
-          title: 'Pick the model',
-          items: modelItems(state),
-          pick: (item) => view.command('model', item.id),
+          title: 'Pick the provider',
+          items: providerItems(state),
+          pick: (item) => pickModelOf(item.id),
         })
       case '/effort':
         if (arg) break
+        if (!reasons(currentModel(state)))
+          return view.notice(
+            `${currentModel(state)} has no effort setting. Pick another model with /model.`,
+          )
         return openPicker({
           title: 'How hard should the model think?',
           items: effortItems(state),
           pick: (item) => view.command('effort', item.id),
         })
+      case '/resume':
+        if (arg) return resume(arg)
+        return openPicker({
+          title: 'Continue which session?',
+          items: await sessionItems(state),
+          pick: (item) => resume(item.id),
+        })
       case '/mic': {
         if (!arg) return pickMicrophone().catch(failVoice)
         const names = await listMicrophones().catch(() => [])
@@ -724,10 +951,10 @@ function App({ view }: { view: SessionView }) {
 
   return (
     <Box flexDirection="column">
-      <Static items={rows}>
+      <Static key={printRound} items={rows}>
         {(row) => (
           <Measured key={row.id} id={row.id} onHeight={onHeight}>
-            <PrintedRow row={row} saved={saved} width={columns} />
+            <PrintedRow view={view} row={row} saved={saved} width={columns} />
           </Measured>
         )}
       </Static>
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7006577049..8c6c082737 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -215,6 +215,9 @@ importers:
       '@tanstack/ai-mcp':
         specifier: workspace:*
         version: link:../../packages/ai-mcp
+      '@tanstack/ai-models':
+        specifier: workspace:*
+        version: link:../../packages/ai-models
       '@tanstack/ai-openai':
         specifier: workspace:*
         version: link:../../packages/ai-openai

From 988185fab49ebacb589fa01e8cf7bdf7ac49c959 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 12:47:20 +0200
Subject: [PATCH 111/286] feat(examples): harness-cli voice input fills the
 input line

The transcript goes into the input line, after what the user typed, so the
user can fix it before Enter sends it. Spoken file names become `@path`
there too. During a key question the words are not put in the line.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 examples/harness-cli/README.md   |  8 +++++---
 examples/harness-cli/src/tui.tsx | 14 ++++++++++++--
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index 8be09a3f21..12565d733d 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -50,9 +50,11 @@ An env var works when no key is saved. A new session starts on the first provide
 
 ## Talk to it
 
-Hold Ctrl+R while you talk, and let go to send. Or tap Ctrl+R, talk, and tap it again. The meter shows that the microphone hears you.
+Hold Ctrl+R while you talk, and let go. Or tap Ctrl+R, talk, and tap it again. The meter shows that the microphone hears you.
 
-- Name a file, and it is sent too: "describe fox dot png", "use cat.png as a reference".
+The words go into the input line. Fix them if needed, then press Enter to send. If you typed something before, the words go after it.
+
+- Name a file, and the line gets an `@path` for it, so the file is sent too: "describe fox dot png", "use cat.png as a reference".
 - Say "the last image" (or video, song) for the last file the agent made: "make a pencil sketch of the last image".
 - Say "Hey, run a Codex agent that adds a test": Codex runs in its own card, and the screen shows its output.
 
@@ -60,7 +62,7 @@ The first recording listens on every microphone, and keeps the one that heard yo
 
 - A silent recording (a muted microphone) is not sent.
 - Set `VOICE_LANGUAGE=en` (or your language) so the transcript is in that language.
-- `/voice note.m4a` sends a voice message that you recorded before.
+- `/voice note.m4a` puts the words of a voice message that you recorded before into the input line.
 
 Voice needs `ffmpeg` on the PATH, and an OpenAI or xAI key for the transcript (`/connect openai` or `/connect grok`).
 
diff --git a/examples/harness-cli/src/tui.tsx b/examples/harness-cli/src/tui.tsx
index 16eea79f89..8008e148ca 100644
--- a/examples/harness-cli/src/tui.tsx
+++ b/examples/harness-cli/src/tui.tsx
@@ -87,6 +87,7 @@ const TAKES_INPUT = new Set(['voice'])
 const HELP = [
   'Type / to see the commands. ↑ and ↓ go through the lines you sent.',
   'Voice: hold Ctrl+R and talk, then let go. Or tap Ctrl+R, talk, tap again.',
+  '  The words go into the input line. Fix them if needed, then press Enter.',
   '  Name a file ("use cat dot png") or say "the last image" to send it too.',
   '  The first recording listens on all microphones and keeps the loudest.',
 ]
@@ -569,7 +570,11 @@ function App({ view }: { view: SessionView }) {
       `Voice: ${error instanceof Error ? error.message : String(error)}`,
     )
 
-  /** A voice message: transcribe it, attach the files it names, and send it. */
+  /**
+   * A voice message: transcribe it, and put the words in the input line, with
+   * an `@path` for each file it names. The user fixes the line if needed,
+   * then presses Enter to send it.
+   */
   const hear = async (audio: Uint8Array, name: string, clip?: VoiceClip) => {
     setVoice('transcribing')
     try {
@@ -595,7 +600,12 @@ function App({ view }: { view: SessionView }) {
         [playground, mediaDir],
         recent,
       )
-      await view.send(message.text)
+      // A key question keeps its line for the key only.
+      if (asksSecret())
+        return view.notice('Voice: answer the key question first.')
+      // After what the user typed already, so nothing they typed is lost.
+      const typed = editor.line.text.trimEnd()
+      editor.set(typed === '' ? message.text : `${typed} ${message.text}`)
     } catch (error) {
       failVoice(error)
     } finally {

From 6f1c28ae8978f8a4023077ff0c19feba38562c61 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 12:50:59 +0200
Subject: [PATCH 112/286] feat(examples): harness-cli suggests files and
 folders after @

Typing `@` lists the files and folders of the working folder, where the CLI
finds the files it attaches. Tab or Enter fills the path. A folder stays
open for the next name, and a path with a space gets quotes.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 examples/harness-cli/README.md            |  1 +
 examples/harness-cli/src/screen/editor.ts |  4 +-
 examples/harness-cli/src/screen/paths.ts  | 72 +++++++++++++++++++++++
 examples/harness-cli/src/tui.tsx          | 60 +++++++++++++++----
 4 files changed, 125 insertions(+), 12 deletions(-)
 create mode 100644 examples/harness-cli/src/screen/paths.ts

diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index 12565d733d..2bbec4fdad 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -118,6 +118,7 @@ A session keeps its messages, its model and effort, and its todos and usage. The
 
 - Answers show as markdown: lists, tables, and highlighted code. A Mermaid block shows as a chart drawn in text. In demo mode, ask `draw me a chart`.
 - Type `/` for a list of the commands. The arrows move in it, Tab fills the command, and Enter runs it.
+- Type `@` for a list of the files and folders in the working folder. Tab or Enter fills the path. A folder opens, so you can go on to a file in it.
 - The up and down arrows go through the lines you sent, also after a restart. They are kept in `~/.tanstack-harness-example/history.json`. Keys are never kept.
 - The input stays at the bottom of the screen. `/help` lists every command.
 
diff --git a/examples/harness-cli/src/screen/editor.ts b/examples/harness-cli/src/screen/editor.ts
index d829d6dcff..b85c6fdd81 100644
--- a/examples/harness-cli/src/screen/editor.ts
+++ b/examples/harness-cli/src/screen/editor.ts
@@ -96,7 +96,9 @@ export function useLineEditor() {
         by === 'start' ? 0 : by === 'end' ? line.text.length : line.cursor + by
       show({ ...line, cursor: Math.max(0, Math.min(line.text.length, target)) })
     },
-    set: (text: string) => edit({ text, cursor: text.length, hidden: false }),
+    /** Replace the line. The cursor goes to `cursor`, or to the end. */
+    set: (text: string, cursor = text.length) =>
+      edit({ text, cursor, hidden: false }),
     clear: () => edit(empty),
     /** Keep a sent line for the up arrow. */
     remember: (text: string) => {
diff --git a/examples/harness-cli/src/screen/paths.ts b/examples/harness-cli/src/screen/paths.ts
new file mode 100644
index 0000000000..0f1bc779c2
--- /dev/null
+++ b/examples/harness-cli/src/screen/paths.ts
@@ -0,0 +1,72 @@
+import { readdirSync } from 'node:fs'
+import { resolve } from 'node:path'
+import type { Line } from './editor'
+import type { MenuItem } from './menu'
+
+/**
+ * An `@path` that is being typed, just before the cursor: an `@` at the
+ * start or after white space, then a quoted path that is not closed yet
+ * (`@"my ca`), or the text up to the cursor. runCli attaches the same tokens.
+ */
+const TYPING = /(^|\s)@(?:"([^"]*)|([^\s"]*))$/
+
+/** A file or a folder in the `@` list. `fill` replaces the typed token. */
+export interface PathItem extends MenuItem {
+  fill: string
+}
+
+/**
+ * The files and folders that the `@path` before the cursor can name, from
+ * the working folder, where runCli finds the files it attaches. Folders
+ * come first. Hidden files show only when the typed name starts with a dot.
+ * `start` is where the token starts in the line. `undefined` when no token
+ * is typed, nothing matches, or the token already names a file.
+ * ponytail: one folder read, at most 100 entries.
+ */
+export function pathSuggestions(line: Line, cwd = process.cwd()) {
+  const match = TYPING.exec(line.text.slice(0, line.cursor))
+  if (!match) return undefined
+  const quoted = match[2] !== undefined
+  const typed = match[2] ?? match[3] ?? ''
+  const dir = typed.slice(0, typed.lastIndexOf('/') + 1)
+  const name = typed.slice(dir.length).toLowerCase()
+  let entries
+  try {
+    entries = readdirSync(resolve(cwd, dir || '.'), { withFileTypes: true })
+  } catch {
+    return undefined
+  }
+  const items = entries
+    .filter(
+      (entry) =>
+        entry.name.toLowerCase().startsWith(name) &&
+        (name.startsWith('.') || !entry.name.startsWith('.')),
+    )
+    .sort(
+      (a, b) =>
+        Number(b.isDirectory()) - Number(a.isDirectory()) ||
+        a.name.localeCompare(b.name),
+    )
+    .slice(0, 100)
+    .map((entry): PathItem => {
+      const folder = entry.isDirectory()
+      const path = `${dir}${entry.name}${folder ? '/' : ''}`
+      // A path with a space needs quotes. A folder stays open, so the next
+      // name can follow it. A file ends the token with a space.
+      const fill =
+        quoted || /\s/.test(path)
+          ? `@"${path}${folder ? '' : '" '}`
+          : `@${path}${folder ? '' : ' '}`
+      return {
+        id: path,
+        label: path,
+        fill,
+        ...(folder ? { detail: 'folder' } : {}),
+      }
+    })
+  const [only] = items
+  if (items.length === 0 || (items.length === 1 && only?.id === typed)) {
+    return undefined
+  }
+  return { start: match.index + (match[1] ?? '').length, items }
+}
diff --git a/examples/harness-cli/src/tui.tsx b/examples/harness-cli/src/tui.tsx
index 8008e148ca..854645abad 100644
--- a/examples/harness-cli/src/tui.tsx
+++ b/examples/harness-cli/src/tui.tsx
@@ -1,7 +1,14 @@
 import { readFile } from 'node:fs/promises'
 import { basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { useEffect, useLayoutEffect, useReducer, useRef, useState } from 'react'
+import {
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+} from 'react'
 import {
   Box,
   Spacer,
@@ -42,6 +49,7 @@ import { Footer } from './screen/footer'
 import { PROVIDER_KEYS, isOn, providerKeysIn } from './screen/keys'
 import { mediaDir, openExternal, play, useSavedMedia } from './screen/media'
 import { Menu } from './screen/menu'
+import { pathSuggestions } from './screen/paths'
 import { Message, settledCount } from './screen/parts'
 import { Status } from './screen/status'
 import { ACCENT, compact } from './screen/theme'
@@ -51,6 +59,7 @@ import type { ModelEntry } from './harness'
 import type { Recording, VoiceClip } from './voice'
 import type { Line } from './screen/editor'
 import type { MenuItem } from './screen/menu'
+import type { PathItem } from './screen/paths'
 import type { VoiceState } from './screen/status'
 import type {
   SessionView,
@@ -86,6 +95,7 @@ const TAKES_INPUT = new Set(['voice'])
 
 const HELP = [
   'Type / to see the commands. ↑ and ↓ go through the lines you sent.',
+  'Type @ to pick a file or a folder to send. Tab or Enter fills the path.',
   'Voice: hold Ctrl+R and talk, then let go. Or tap Ctrl+R, talk, tap again.',
   '  The words go into the input line. Fix them if needed, then press Enter.',
   '  Name a file ("use cat dot png") or say "the last image" to send it too.',
@@ -487,11 +497,26 @@ function App({ view }: { view: SessionView }) {
   )
   const [picker, setPicker] = useState<Picker | undefined>(undefined)
   const [selected, setSelected] = useState(0)
-  const suggestions =
-    // A line from the history keeps the arrows for the history.
-    picker || waiting || editor.line.hidden || editor.browsing
-      ? []
-      : suggestionsFor(editor.line.text, commands)
+  // A line from the history keeps the arrows for the history.
+  const blocked = Boolean(
+    picker || waiting || editor.line.hidden || editor.browsing,
+  )
+  const commandItems = blocked ? [] : suggestionsFor(editor.line.text, commands)
+  // The files for an `@path`, read again only when the line changes.
+  const { text: lineText, cursor: lineCursor } = editor.line
+  const paths = useMemo(
+    () =>
+      blocked || commandItems.length > 0
+        ? undefined
+        : pathSuggestions({
+            text: lineText,
+            cursor: lineCursor,
+            hidden: false,
+          }),
+    [blocked, commandItems.length, lineText, lineCursor],
+  )
+  const suggestions: Array<(MenuItem & { takesInput: boolean }) | PathItem> =
+    commandItems.length > 0 ? commandItems : (paths?.items ?? [])
   const [suggested, setSuggested] = useState(0)
   useEffect(() => setSuggested(0), [editor.line.text])
 
@@ -936,10 +961,19 @@ function App({ view }: { view: SessionView }) {
       if (key.upArrow)
         return setSuggested((index) => (index - 1 + count) % count)
       if (key.downArrow) return setSuggested((index) => (index + 1) % count)
-      if (key.tab) return editor.set(`/${suggestion.id} `)
-      if (key.return) {
-        if (suggestion.takesInput) return editor.set(`/${suggestion.id} `)
-        return send({ text: `/${suggestion.id}`, cursor: 0, hidden: false })
+      if ('fill' in suggestion) {
+        // Put the path in place of the typed `@` token.
+        if (key.tab || key.return) {
+          const { text, cursor } = editor.line
+          const filled = text.slice(0, paths?.start ?? cursor) + suggestion.fill
+          return editor.set(filled + text.slice(cursor), filled.length)
+        }
+      } else {
+        if (key.tab) return editor.set(`/${suggestion.id} `)
+        if (key.return) {
+          if (suggestion.takesInput) return editor.set(`/${suggestion.id} `)
+          return send({ text: `/${suggestion.id}`, cursor: 0, hidden: false })
+        }
       }
     }
     if (key.upArrow) return editor.older()
@@ -997,7 +1031,11 @@ function App({ view }: { view: SessionView }) {
           <Menu
             items={suggestions}
             selected={Math.min(suggested, suggestions.length - 1)}
-            hint="↑↓ move   Tab fills   Enter runs"
+            hint={
+              commandItems.length > 0
+                ? '↑↓ move   Tab fills   Enter runs'
+                : '↑↓ move   Tab or Enter fills'
+            }
           />
         ) : null}
         <Footer view={view} />

From 55e5c9304e1e94161fbc8f200d2734e002470edf Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 12:54:50 +0200
Subject: [PATCH 113/286] feat(examples): harness-cli boot splash

At the first start, TANSTACK AI wipes in as block letters in the accent
color, a light sweeps over it, and AGENT HARNESS types in below. It takes
about 1.7 seconds, and a key skips it. A narrow screen gets one line.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 examples/harness-cli/README.md             |   1 +
 examples/harness-cli/src/screen/splash.tsx | 150 +++++++++++++++++++++
 examples/harness-cli/src/tui.tsx           |  19 ++-
 3 files changed, 167 insertions(+), 3 deletions(-)
 create mode 100644 examples/harness-cli/src/screen/splash.tsx

diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index 2bbec4fdad..ed4c52d89d 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -116,6 +116,7 @@ A session keeps its messages, its model and effort, and its todos and usage. The
 
 ## The screen
 
+- At the start, TanStack AI animates in block letters for about 2 seconds. A key skips it.
 - Answers show as markdown: lists, tables, and highlighted code. A Mermaid block shows as a chart drawn in text. In demo mode, ask `draw me a chart`.
 - Type `/` for a list of the commands. The arrows move in it, Tab fills the command, and Enter runs it.
 - Type `@` for a list of the files and folders in the working folder. Tab or Enter fills the path. A folder opens, so you can go on to a file in it.
diff --git a/examples/harness-cli/src/screen/splash.tsx b/examples/harness-cli/src/screen/splash.tsx
new file mode 100644
index 0000000000..0d2c46f62e
--- /dev/null
+++ b/examples/harness-cli/src/screen/splash.tsx
@@ -0,0 +1,150 @@
+import { useEffect, useState } from 'react'
+import { Box, Text, render, useApp, useInput, useWindowSize } from 'ink'
+import { ACCENT } from './theme'
+import type { RenderOptions } from 'ink'
+
+// The block letters, 6 rows each. All rows of a letter have one width.
+const LETTERS: Record<string, Array<string>> = {
+  T: [
+    '████████╗',
+    '╚══██╔══╝',
+    '   ██║   ',
+    '   ██║   ',
+    '   ██║   ',
+    '   ╚═╝   ',
+  ],
+  A: [' █████╗ ', '██╔══██╗', '███████║', '██╔══██║', '██║  ██║', '╚═╝  ╚═╝'],
+  N: [
+    '███╗   ██╗',
+    '████╗  ██║',
+    '██╔██╗ ██║',
+    '██║╚██╗██║',
+    '██║ ╚████║',
+    '╚═╝  ╚═══╝',
+  ],
+  S: ['███████╗', '██╔════╝', '███████╗', '╚════██║', '███████║', '╚══════╝'],
+  C: [' ██████╗', '██╔════╝', '██║     ', '██║     ', '╚██████╗', ' ╚═════╝'],
+  K: ['██╗  ██╗', '██║ ██╔╝', '█████╔╝ ', '██╔═██╗ ', '██║  ██╗', '╚═╝  ╚═╝'],
+  I: ['██╗', '██║', '██║', '██║', '██║', '╚═╝'],
+}
+
+/** "TANSTACK AI" in block letters, one string for each row. */
+const BIG = Array.from({ length: 6 }, (_, row) =>
+  ['TANSTACK', 'AI']
+    .map((word) =>
+      [...word].map((letter) => LETTERS[letter]?.[row] ?? '').join(''),
+    )
+    .join('   '),
+)
+const SMALL = ['◆ TanStack AI']
+const TAGLINE = 'A G E N T   H A R N E S S'
+
+const SHADOW = new Set([...'╗║╝═╔╚'])
+// The brand cream for the light, and a darker step of the accent for the
+// shadow of the letters.
+const CREAM = '#eeebd4'
+const DEEP = '#8a3a20'
+
+// The timeline, in milliseconds: the letters wipe in, a light sweeps over
+// them, and the tagline types in. Then the splash ends.
+const REVEAL = 600
+const SHINE = 500
+const END = 1700
+
+const easeOut = (x: number) => 1 - (1 - Math.min(1, Math.max(0, x))) ** 3
+
+/** One row of letters, cut into runs of one color. */
+function Row(props: {
+  text: string
+  shown: number
+  light: number
+  revealing: boolean
+}) {
+  const { text, shown, light, revealing } = props
+  const runs: Array<{ color: string | undefined; text: string }> = []
+  for (const [column, char] of [...text].entries()) {
+    const visible = column < shown && char !== ' '
+    const lit =
+      Math.abs(column - light) < 3 || (revealing && column >= shown - 2)
+    const color = !visible
+      ? undefined
+      : lit
+        ? CREAM
+        : SHADOW.has(char)
+          ? DEEP
+          : ACCENT
+    const shownChar = column < shown ? char : ' '
+    const last = runs.at(-1)
+    if (last && last.color === color) last.text += shownChar
+    else runs.push({ color, text: shownChar })
+  }
+  return (
+    <Text>
+      {runs.map((run, index) => (
+        <Text key={index} color={run.color}>
+          {run.text}
+        </Text>
+      ))}
+    </Text>
+  )
+}
+
+function Splash() {
+  const { exit } = useApp()
+  const { columns, rows } = useWindowSize()
+  const [elapsed, setElapsed] = useState(0)
+  useEffect(() => {
+    const start = Date.now()
+    const timer = setInterval(() => {
+      const now = Date.now() - start
+      setElapsed(now)
+      if (now >= END) exit()
+    }, 33)
+    return () => clearInterval(timer)
+  }, [])
+  // Any key skips the splash.
+  useInput(() => exit())
+
+  const lines = columns >= (BIG[0]?.length ?? 0) + 4 ? BIG : SMALL
+  const width = lines[0]?.length ?? 0
+  const shown = Math.ceil(width * easeOut(elapsed / REVEAL))
+  const light =
+    elapsed < REVEAL ? -10 : -6 + (width + 12) * ((elapsed - REVEAL) / SHINE)
+  const typed = Math.round(
+    TAGLINE.length * easeOut((elapsed - REVEAL * 0.8) / 500),
+  )
+  // One line shorter than the screen, so Ink does not redraw it all.
+  return (
+    <Box
+      width={columns}
+      height={Math.max(1, rows - 1)}
+      flexDirection="column"
+      alignItems="center"
+      justifyContent="center"
+    >
+      {lines.map((line, index) => (
+        <Row
+          key={index}
+          text={line}
+          shown={shown}
+          light={light}
+          revealing={elapsed < REVEAL}
+        />
+      ))}
+      <Box marginTop={1}>
+        <Text color={CREAM}>
+          {TAGLINE.slice(0, typed).padEnd(TAGLINE.length)}
+        </Text>
+      </Box>
+    </Box>
+  )
+}
+
+/**
+ * The boot animation: TanStack AI in block letters, for about 1.7 seconds.
+ * A key skips it. A narrow screen gets one line of text instead.
+ */
+export async function showSplash(io: RenderOptions = {}) {
+  const app = render(<Splash />, io)
+  await app.waitUntilExit()
+}
diff --git a/examples/harness-cli/src/tui.tsx b/examples/harness-cli/src/tui.tsx
index 854645abad..e7f4922023 100644
--- a/examples/harness-cli/src/tui.tsx
+++ b/examples/harness-cli/src/tui.tsx
@@ -50,6 +50,7 @@ import { PROVIDER_KEYS, isOn, providerKeysIn } from './screen/keys'
 import { mediaDir, openExternal, play, useSavedMedia } from './screen/media'
 import { Menu } from './screen/menu'
 import { pathSuggestions } from './screen/paths'
+import { showSplash } from './screen/splash'
 import { Message, settledCount } from './screen/parts'
 import { Status } from './screen/status'
 import { ACCENT, compact } from './screen/theme'
@@ -1044,6 +1045,9 @@ function App({ view }: { view: SessionView }) {
   )
 }
 
+// The boot splash shows once in a process.
+let splashShown = false
+
 /**
  * The Ink screen for `runCli({ ui })`. It clears the terminal, opens sign-in
  * links in the browser, records voice messages, saves the media the agents
@@ -1059,9 +1063,18 @@ export async function runTui(view: SessionView, io: RenderOptions = {}) {
     view.notice(
       'No model key yet. Type /connect and pick OpenRouter to sign in with the browser.',
     )
-  // Start on a clean terminal: clear the screen and the scrollback.
-  if (!io.stdout && process.stdout.isTTY)
-    process.stdout.write('\x1b[2J\x1b[3J\x1b[H')
+  // Start on a clean terminal: clear the screen and the scrollback. The
+  // splash shows once, at the first start, not again after a /resume.
+  const clear = () => {
+    if (!io.stdout && process.stdout.isTTY)
+      process.stdout.write('\x1b[2J\x1b[3J\x1b[H')
+  }
+  if (!splashShown && (io.stdout ?? process.stdout).isTTY) {
+    splashShown = true
+    clear()
+    await showSplash(io)
+  }
+  clear()
   const app = render(<App view={view} />, io)
   // ponytail: the SDK logs its warnings and errors on the console (the
   // message, then its details with console.dir), and the code highlighter

From d1a819bad8baa4b7c53403dcf9ab8ab7a5c46fe4 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 13:02:26 +0200
Subject: [PATCH 114/286] fix(examples): harness-cli start without the .env
 message, cursor in the input

- The CLI loads ./.env itself, so a missing file prints nothing. The tsx
  flag printed ".env not found. Continuing without it." twice.
- The terminal cursor sits where you type in the input box, not on the
  line under the screen.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 examples/harness-cli/package.json |  2 +-
 examples/harness-cli/src/cli.ts   |  1 +
 examples/harness-cli/src/env.ts   | 10 ++++++
 examples/harness-cli/src/tui.tsx  | 54 +++++++++++++++++++++++--------
 4 files changed, 53 insertions(+), 14 deletions(-)
 create mode 100644 examples/harness-cli/src/env.ts

diff --git a/examples/harness-cli/package.json b/examples/harness-cli/package.json
index b9be10ab7a..c0f8ec2517 100644
--- a/examples/harness-cli/package.json
+++ b/examples/harness-cli/package.json
@@ -4,7 +4,7 @@
   "type": "module",
   "description": "A small coding agent in the terminal, built with @tanstack/ai-harness",
   "scripts": {
-    "start": "tsx --env-file-if-exists=.env src/cli.ts",
+    "start": "tsx src/cli.ts",
     "dashboard": "tanstack-ai-dashboard",
     "test:types": "tsc --noEmit"
   },
diff --git a/examples/harness-cli/src/cli.ts b/examples/harness-cli/src/cli.ts
index 0fd06a6d2a..d19ebdbfdc 100644
--- a/examples/harness-cli/src/cli.ts
+++ b/examples/harness-cli/src/cli.ts
@@ -1,3 +1,4 @@
+import './env'
 import { runCli } from '@tanstack/ai-harness-cli'
 import { assistant } from './harness'
 import { hasSession, listSessions, newSessionId } from './sessions'
diff --git a/examples/harness-cli/src/env.ts b/examples/harness-cli/src/env.ts
new file mode 100644
index 0000000000..16b37bb24d
--- /dev/null
+++ b/examples/harness-cli/src/env.ts
@@ -0,0 +1,10 @@
+// The `.env` shortcut: the keys in ./.env, when the file is there. A missing
+// file is normal (the app needs none), so it says nothing. The CLI imports
+// this file first, so the keys are set before the harness reads them.
+try {
+  process.loadEnvFile()
+} catch (error) {
+  if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+    throw error
+  }
+}
diff --git a/examples/harness-cli/src/tui.tsx b/examples/harness-cli/src/tui.tsx
index e7f4922023..8c65c744f9 100644
--- a/examples/harness-cli/src/tui.tsx
+++ b/examples/harness-cli/src/tui.tsx
@@ -18,6 +18,7 @@ import {
   render,
   useApp,
   useBoxMetrics,
+  useCursor,
   useInput,
   usePaste,
   useStdout,
@@ -397,6 +398,7 @@ function InputBox({
   hidden: boolean
 }) {
   const shown = hidden ? '•'.repeat(line.text.length) : line.text
+  // The terminal cursor shows where you type (see `inputCursor`).
   return (
     <Box
       borderStyle="round"
@@ -411,7 +413,7 @@ function InputBox({
       {shown === '' ? (
         // The cursor goes before the hint, so the hint does not look typed.
         <Text>
-          <Text inverse> </Text>
+          {' '}
           <Text dimColor>
             {hidden
               ? ' Paste the key. It stays hidden.'
@@ -419,16 +421,29 @@ function InputBox({
           </Text>
         </Text>
       ) : (
-        <Text>
-          {shown.slice(0, line.cursor)}
-          <Text inverse>{shown[line.cursor] ?? ' '}</Text>
-          {shown.slice(line.cursor + 1)}
-        </Text>
+        // At any character, so `inputCursor` knows the row of each one.
+        <Text wrap="hard">{shown}</Text>
       )}
     </Box>
   )
 }
 
+/**
+ * Where the terminal cursor goes in the input box, which is `width` wide
+ * and starts at `top`: after the border, the padding, and the `❯ `, at the
+ * row and the column of the line's cursor.
+ * ponytail: one column for each character. A wide character (an emoji, CJK)
+ * puts the cursor a little to the left.
+ */
+function inputCursor(line: Line, width: number, top: number) {
+  const before = 4
+  const textWidth = Math.max(1, width - before - 2)
+  return {
+    x: before + (line.cursor % textWidth),
+    y: top + 1 + Math.floor(line.cursor / textWidth),
+  }
+}
+
 // A key held down repeats. Repeats closer than this are one press.
 const REPEAT_GAP = 1100
 // After the last repeat, the key is up when no repeat comes for this long.
@@ -554,6 +569,17 @@ function App({ view }: { view: SessionView }) {
   const { height: liveHeight } = useBoxMetrics(live)
   const space = Math.max(0, screenRows - 1 - printedHeight - liveHeight)
 
+  // The terminal cursor sits in the input box, not under the screen. The
+  // box is in the live area, which starts after the empty space.
+  const inputBox = useRef<DOMElement>(null)
+  const input = useBoxMetrics(inputBox)
+  const { setCursorPosition } = useCursor()
+  setCursorPosition(
+    input.hasMeasured
+      ? inputCursor(editor.line, input.width, space + input.top)
+      : undefined,
+  )
+
   // The header shows which features are on, but printed rows never change.
   // So when a feature turns on or off (a /connect), clear the screen and
   // print the header and the conversation again.
@@ -1014,13 +1040,15 @@ function App({ view }: { view: SessionView }) {
           />
         ))}
         <Status view={view} voice={voice} recording={recorder} />
-        <InputBox
-          line={editor.line}
-          voice={voice}
-          hidden={
-            secretAsked || (editor.line.hidden && editor.line.text !== '')
-          }
-        />
+        <Box ref={inputBox}>
+          <InputBox
+            line={editor.line}
+            voice={voice}
+            hidden={
+              secretAsked || (editor.line.hidden && editor.line.text !== '')
+            }
+          />
+        </Box>
         {picker ? (
           <Menu
             title={picker.title}

From eb13f8f57836cf02af39e71bd362d5348435a1b7 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 13:43:44 +0200
Subject: [PATCH 115/286] feat(ai-harness): a replay option on durableTool

durableTool(definition, execute, { replay: 'never' }) keeps step and append, and a call that a crash cut gives the model a tool error instead of running again. The default stays 'safe'.
---
 packages/ai-harness/src/durable-tool.ts       | 17 ++++-
 packages/ai-harness/src/index.ts              |  6 +-
 .../ai-harness/tests/durable-tools.test.ts    | 68 +++++++++++++++++++
 3 files changed, 88 insertions(+), 3 deletions(-)

diff --git a/packages/ai-harness/src/durable-tool.ts b/packages/ai-harness/src/durable-tool.ts
index f718e1ada6..b5cc499f01 100644
--- a/packages/ai-harness/src/durable-tool.ts
+++ b/packages/ai-harness/src/durable-tool.ts
@@ -80,11 +80,23 @@ const noLog = () => {
 
 const emptyContext: ToolExecutionContext = { emitCustomEvent: () => {} }
 
+/** Options for {@link durableTool}. */
+export interface DurableToolOptions {
+  /**
+   * What the harness does with a call that a crash cut:
+   * - `'safe'` (default): run it again. Finished steps return their stored
+   *   values.
+   * - `'never'`: give the model a tool error. The call does not run again.
+   */
+  replay?: 'safe' | 'never'
+}
+
 /**
  * Make a server tool whose side effects survive a crash. `execute` gets
  * `step` and `append` next to the normal tool context. Put each side effect
  * in `step.do(name, fn)`: when a crash makes the harness run the call again,
- * finished steps return their stored values. The tool has `replay: 'safe'`.
+ * finished steps return their stored values. The tool has `replay: 'safe'`
+ * unless `options.replay` says `'never'`.
  *
  * Outside a durable harness session (plain `chat()`, or a host without
  * `stores.log`), `step.do` runs `fn` each time and `append` throws.
@@ -118,6 +130,7 @@ export function durableTool<
     args: InferSchemaType<TInput>,
     context: DurableToolContext,
   ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
+  options: DurableToolOptions = {},
 ) {
   const tool = definition.server((args, context) =>
     execute(args, {
@@ -133,7 +146,7 @@ export function durableTool<
     value: execute,
     enumerable: true,
   })
-  return Object.assign(tool, { replay: 'safe' as const })
+  return Object.assign(tool, { replay: options.replay ?? 'safe' })
 }
 
 function isDurableTool(
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index 252d46f869..9e41b88b41 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -9,7 +9,11 @@ export type {
 } from './define'
 
 export { durableTool } from './durable-tool'
-export type { DurableToolContext, ToolStep } from './durable-tool'
+export type {
+  DurableToolContext,
+  DurableToolOptions,
+  ToolStep,
+} from './durable-tool'
 
 export { logMessageStore } from './log'
 export type { ProjectOptions, ProjectRecord } from './log'
diff --git a/packages/ai-harness/tests/durable-tools.test.ts b/packages/ai-harness/tests/durable-tools.test.ts
index a307fae198..527f930cd1 100644
--- a/packages/ai-harness/tests/durable-tools.test.ts
+++ b/packages/ai-harness/tests/durable-tools.test.ts
@@ -266,3 +266,71 @@ describe('host records of a tool batch', () => {
     await next.host.close().catch(() => {})
   })
 })
+
+describe('a durable tool with replay: never', () => {
+  it('lands its staged records with the batch', async () => {
+    const persistence = durablePersistence()
+    const note = durableTool(
+      toolDefinition({ name: 'note', description: 'Write a note' }),
+      async (_args, { append }) => {
+        append([{ type: 'app.state_write', name: 'x', value: 1 }])
+        return 'noted'
+      },
+      { replay: 'never' },
+    )
+    const { host, session } = await openDurable(
+      persistence,
+      [() => toolCall('note', {}, 'call-note'), () => text('done')],
+      [note],
+    )
+
+    await session.prompt('note it')
+
+    expect(note.replay).toBe('never')
+    expect(await recordsOf(persistence, 'app.state_write')).toEqual([
+      { type: 'app.state_write', name: 'x', value: 1 },
+    ])
+    await host.close()
+  })
+
+  it('gives the model the tool error after a crash, and does not run again', async () => {
+    const persistence = durablePersistence()
+    const send = vi.fn(async () => 'sent')
+    const started = gate()
+    let runs = 0
+    const mail = durableTool(
+      toolDefinition({ name: 'mail', description: 'Send a mail' }),
+      async (_args, { step, abortSignal }) => {
+        runs += 1
+        await step.do('send', send)
+        started.open()
+        // The first host stops here.
+        return untilAborted(abortSignal)
+      },
+      { replay: 'never' },
+    )
+    const first = await openDurable(
+      persistence,
+      [() => toolCall('mail', {}, 'call-mail')],
+      [mail],
+    )
+    const turn = first.session.prompt('mail it', { inputId: 'mail-1' })
+    await started.opened
+    await expireLease(persistence, turn.id)
+
+    const next = await openDurable(persistence, [() => text('checked')], [mail])
+    expect(await next.session.settled('mail-1')).toMatchObject({
+      outcome: 'completed',
+    })
+
+    const result = (await next.session.transcript()).find(
+      (message) =>
+        message.role === 'tool' && message.toolCallId === 'call-mail',
+    )
+    expect(result?.error).toBe(INTERRUPTED_TOOL_RESULT.note)
+    expect(send).toHaveBeenCalledTimes(1)
+    expect(runs).toBe(1)
+    await first.host.close().catch(() => {})
+    await next.host.close()
+  })
+})

From 4a7345601109a60fab0340afe88da54fd35bd130 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 13:45:04 +0200
Subject: [PATCH 116/286] feat(ai-harness, ai-code-mode): live plugin commands
 and lazy code-mode tools

- ai-harness: ctx.commands (has, set, delete, ready) lets a plugin add and
  remove its commands while the session runs. Each change publishes
  harness.commands.changed, and session views reload the command list.
- ai-code-mode: codeMode({ lazy: true }) makes each moved tool lazy. The
  prompt lists only the names, and discover_tools gives the signatures.
- harness-cli example: the screen command names are in their own module,
  and the / list shows skill: commands.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 examples/harness-cli/src/screen/commands.ts   |  23 +++
 examples/harness-cli/src/tui.tsx              |  29 +---
 packages/ai-code-mode/src/harness.ts          |  17 +-
 packages/ai-code-mode/tests/harness.test.ts   |  52 +++++-
 packages/ai-harness/src/index.ts              |   1 +
 packages/ai-harness/src/plugins.ts            |  53 ++++++
 packages/ai-harness/src/session.ts            |   5 +
 packages/ai-harness/src/types.ts              |   2 +
 packages/ai-harness/src/view/index.ts         |   5 +-
 .../ai-harness/tests/live-commands.test.ts    | 154 ++++++++++++++++++
 10 files changed, 307 insertions(+), 34 deletions(-)
 create mode 100644 examples/harness-cli/src/screen/commands.ts
 create mode 100644 packages/ai-harness/tests/live-commands.test.ts

diff --git a/examples/harness-cli/src/screen/commands.ts b/examples/harness-cli/src/screen/commands.ts
new file mode 100644
index 0000000000..99bce79ce1
--- /dev/null
+++ b/examples/harness-cli/src/screen/commands.ts
@@ -0,0 +1,23 @@
+/** The commands of the screen itself. The harness adds its own to the list. */
+export const SCREEN_COMMANDS = [
+  {
+    name: 'connect',
+    description: 'Connect a model provider, Notion, or Linear',
+  },
+  { name: 'disconnect', description: 'Remove a key or a sign-in' },
+  { name: 'model', description: 'Pick the model' },
+  { name: 'effort', description: 'Pick how hard the model thinks' },
+  { name: 'resume', description: 'Continue a saved session' },
+  { name: 'mic', description: 'Pick the microphone' },
+  { name: 'open', description: 'Open a media file (default: the last one)' },
+  { name: 'play', description: 'Play an audio or video file' },
+  {
+    name: 'voice',
+    description: 'Send a recorded voice message: /voice note.m4a',
+  },
+  { name: 'help', description: 'Show the commands and the voice tips' },
+  { name: 'exit', description: 'Quit' },
+]
+
+// Commands that need text after the name: Enter in the list fills the name.
+export const TAKES_INPUT = new Set(['voice'])
diff --git a/examples/harness-cli/src/tui.tsx b/examples/harness-cli/src/tui.tsx
index 8c65c744f9..fb16182b72 100644
--- a/examples/harness-cli/src/tui.tsx
+++ b/examples/harness-cli/src/tui.tsx
@@ -49,6 +49,7 @@ import { useLineEditor } from './screen/editor'
 import { Footer } from './screen/footer'
 import { PROVIDER_KEYS, isOn, providerKeysIn } from './screen/keys'
 import { mediaDir, openExternal, play, useSavedMedia } from './screen/media'
+import { SCREEN_COMMANDS, TAKES_INPUT } from './screen/commands'
 import { Menu } from './screen/menu'
 import { pathSuggestions } from './screen/paths'
 import { showSplash } from './screen/splash'
@@ -72,29 +73,6 @@ import type {
 
 const playground = fileURLToPath(new URL('../playground', import.meta.url))
 
-/** The commands of the screen itself. The harness adds its own to the list. */
-const SCREEN_COMMANDS = [
-  {
-    name: 'connect',
-    description: 'Connect a model provider, Notion, or Linear',
-  },
-  { name: 'disconnect', description: 'Remove a key or a sign-in' },
-  { name: 'model', description: 'Pick the model' },
-  { name: 'effort', description: 'Pick how hard the model thinks' },
-  { name: 'resume', description: 'Continue a saved session' },
-  { name: 'mic', description: 'Pick the microphone' },
-  { name: 'open', description: 'Open a media file (default: the last one)' },
-  { name: 'play', description: 'Play an audio or video file' },
-  {
-    name: 'voice',
-    description: 'Send a recorded voice message: /voice note.m4a',
-  },
-  { name: 'help', description: 'Show the commands and the voice tips' },
-  { name: 'exit', description: 'Quit' },
-]
-// Commands that need text after the name: Enter in the list fills the name.
-const TAKES_INPUT = new Set(['voice'])
-
 const HELP = [
   'Type / to see the commands. ↑ and ↓ go through the lines you sent.',
   'Type @ to pick a file or a folder to send. Tab or Enter fills the path.',
@@ -117,9 +95,12 @@ function suggestionsFor(text: string, commands: ReadonlyArray<ViewCommand>) {
       takesInput: TAKES_INPUT.has(command.name),
     })),
     // `connect:openai` and the like are in the `/connect` picker instead.
+    // `skill:<name>` (a skill whose name was taken) shows here.
     ...commands
       .filter(
-        (command) => !command.name.includes(':') && !own.has(command.name),
+        (command) =>
+          (!command.name.includes(':') || command.name.startsWith('skill:')) &&
+          !own.has(command.name),
       )
       .map((command) => ({
         id: command.name,
diff --git a/packages/ai-code-mode/src/harness.ts b/packages/ai-code-mode/src/harness.ts
index 392959b55c..5f9fb6f376 100644
--- a/packages/ai-code-mode/src/harness.ts
+++ b/packages/ai-code-mode/src/harness.ts
@@ -17,6 +17,14 @@ export interface CodeModePluginOptions extends Omit<
    * no edits, no commands, nothing that asks first).
    */
   include?: (tool: CodeModeTool) => boolean
+  /**
+   * Make each tool that moves into code mode lazy. The prompt then lists only
+   * the tool names, and `lazyToolsConfig.includeDescription` adds part of
+   * each description. The model calls `discover_tools` for the signatures of
+   * the tools it needs, then calls them in `execute_typescript`. This saves
+   * tokens on each turn when there are many tools. Default `false`.
+   */
+  lazy?: boolean
 }
 
 /**
@@ -43,7 +51,8 @@ function isServerTool(tool: AnyTool): tool is CodeModeTool {
  *
  * Calls inside the isolate do not stop for approval, so by default only
  * tools that are safe to run without a question move into code mode. The
- * other tools stay normal tool calls.
+ * other tools stay normal tool calls. With `lazy: true`, the model gets only
+ * the names of the moved tools and asks `discover_tools` for the signatures.
  *
  * @example
  * ```ts
@@ -58,7 +67,7 @@ function isServerTool(tool: AnyTool): tool is CodeModeTool {
  * ```
  */
 export function codeMode(options: CodeModePluginOptions) {
-  const { include, ...config } = options
+  const { include, lazy = false, ...config } = options
   return definePlugin({
     name: 'tanstack/code-mode',
     setup: (ctx) => {
@@ -86,7 +95,9 @@ export function codeMode(options: CodeModePluginOptions) {
           const created = createCodeMode({
             ...config,
             tools: [...byIdentifier].map(([identifier, tool]) =>
-              identifier === tool.name ? tool : { ...tool, name: identifier },
+              identifier === tool.name && !lazy
+                ? tool
+                : { ...tool, name: identifier, ...(lazy ? { lazy } : {}) },
             ),
           })
           prompt = created.systemPrompt
diff --git a/packages/ai-code-mode/tests/harness.test.ts b/packages/ai-code-mode/tests/harness.test.ts
index 8266bbf402..5f1a85aaac 100644
--- a/packages/ai-code-mode/tests/harness.test.ts
+++ b/packages/ai-code-mode/tests/harness.test.ts
@@ -71,21 +71,26 @@ const textTurn = (content: string): Array<StreamChunk> => [
   },
 ]
 
-const codeTurn = (code: string): Array<StreamChunk> => [
+/** A model turn that calls one tool with `args`. */
+const callTurn = (toolName: string, args: unknown): Array<StreamChunk> => [
   { type: EventType.RUN_STARTED, runId: 'r', threadId: 't', timestamp: now() },
   {
     type: EventType.TOOL_CALL_START,
-    toolCallId: 'call-code',
-    toolCallName: 'execute_typescript',
+    toolCallId: `call-${toolName}`,
+    toolCallName: toolName,
     timestamp: now(),
   },
   {
     type: EventType.TOOL_CALL_ARGS,
-    toolCallId: 'call-code',
-    delta: JSON.stringify({ typescriptCode: code }),
+    toolCallId: `call-${toolName}`,
+    delta: JSON.stringify(args),
+    timestamp: now(),
+  },
+  {
+    type: EventType.TOOL_CALL_END,
+    toolCallId: `call-${toolName}`,
     timestamp: now(),
   },
-  { type: EventType.TOOL_CALL_END, toolCallId: 'call-code', timestamp: now() },
   {
     type: EventType.RUN_FINISHED,
     runId: 'r',
@@ -95,6 +100,9 @@ const codeTurn = (code: string): Array<StreamChunk> => [
   },
 ]
 
+const codeTurn = (code: string) =>
+  callTurn('execute_typescript', { typescriptCode: code })
+
 /**
  * A stand-in isolate: it records the bindings it got and, for any program,
  * calls `external_lookup` and `external_notion_search` and returns both
@@ -253,6 +261,38 @@ describe('codeMode', () => {
     await host.close()
   })
 
+  it('with lazy, lists only the tool names and gives signatures on discover_tools', async () => {
+    const { driver } = fakeDriver()
+    const { adapter, calls } = scripted([
+      callTurn('discover_tools', { toolNames: ['external_lookup'] }),
+      textTurn('found it'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/code-mode-lazy',
+        adapter,
+        tools: [tools.lookup, tools.remove],
+        plugins: () => [codeMode({ driver, lazy: true })],
+      }),
+      { threadId: 't' },
+    )
+    expect((await session.prompt('what can you call?')).text).toBe('found it')
+
+    expect(calls[0].tools.map((tool: { name: string }) => tool.name)).toEqual([
+      'remove',
+      'execute_typescript',
+      'discover_tools',
+    ])
+    // The prompt names the tool, but its input shape comes from discovery.
+    const prompts = JSON.stringify(calls[0].systemPrompts)
+    expect(prompts).toContain('Discoverable APIs')
+    expect(prompts).toContain('external_lookup')
+    expect(prompts).not.toContain('q: string')
+    expect(JSON.stringify(calls[1].messages)).toContain('q: string')
+    await host.close()
+  })
+
   it('gives tools with names that are not identifiers a safe name', async () => {
     const seen: Array<Array<string>> = []
     const driver: IsolateDriver = {
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index 252d46f869..e2234858d6 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -24,6 +24,7 @@ export type {
   PluginPrompt,
   AgentGroup,
   PluginAgentActions,
+  PluginCommands,
   PluginSetupContext,
   PluginState,
 } from './plugins'
diff --git a/packages/ai-harness/src/plugins.ts b/packages/ai-harness/src/plugins.ts
index f94a30e066..86bb1c5177 100644
--- a/packages/ai-harness/src/plugins.ts
+++ b/packages/ai-harness/src/plugins.ts
@@ -166,6 +166,31 @@ export interface PluginServices {
   keys: ProviderKeys
   session: PluginSessionApi
   agents: PluginAgentActions
+  /** Called after `ctx.commands` adds or removes a command. */
+  commandsChanged?: () => void
+}
+
+/**
+ * The commands of the session, for a plugin that adds and removes its own
+ * commands while the session runs, for example one command for each file in
+ * a folder. Commands that never change go in the `commands` of `setup`.
+ */
+export interface PluginCommands {
+  /** Is `name` a command of any plugin of this session? */
+  has: (name: string) => boolean
+  /**
+   * Add this plugin's command `name`, or replace it. A name that another
+   * plugin owns throws. Session views get the new list at once.
+   */
+  set: (name: string, command: AnyCommand) => void
+  /** Remove this plugin's command `name`. Another plugin's name does nothing. */
+  delete: (name: string) => void
+  /**
+   * Resolves when every plugin of the session is set up. Wait for it before
+   * `has` or `set`: during `setup`, the plugins after this one have not
+   * added their commands yet.
+   */
+  ready: Promise<void>
 }
 
 /** What a plugin's `setup` receives. */
@@ -213,6 +238,8 @@ export interface PluginSetupContext {
    */
   keys: ProviderKeys
   session: PluginSessionApi
+  /** Add and remove this plugin's commands while the session runs. */
+  commands: PluginCommands
 }
 
 export interface PluginDefinition {
@@ -480,6 +507,12 @@ export async function mountPlugins(
   const preparers: MountedPlugins['preparers'] = []
   const subagents: Array<AnyAgent> = []
   const services = env.services ?? NO_SERVICES
+  // `ctx.commands.ready`: resolves after the last plugin is set up. A failed
+  // mount leaves it pending, so no plugin acts on a session that never opens.
+  let markReady = () => {}
+  const ready = new Promise<void>((resolve) => (markReady = resolve))
+  const ownerOf = (name: string) =>
+    commands.get(name)?.owner ?? env.takenCommands?.get(name)?.owner
 
   try {
     for (const plugin of plugins) {
@@ -551,6 +584,25 @@ export async function mountPlugins(
         credentials: services.credentials,
         keys: services.keys,
         session: services.session,
+        commands: {
+          has: (name) => ownerOf(name) !== undefined,
+          set: (name, command) => {
+            const owner = ownerOf(name)
+            if (owner !== undefined && owner !== plugin.name) {
+              throw new Error(
+                `Command "${name}" belongs to ${owner}. ${plugin.name} cannot replace it.`,
+              )
+            }
+            commands.set(name, { command, owner: plugin.name })
+            services.commandsChanged?.()
+          },
+          delete: (name) => {
+            if (commands.get(name)?.owner !== plugin.name) return
+            commands.delete(name)
+            services.commandsChanged?.()
+          },
+          ready,
+        },
       })
       for (const handle of plugin.provides ?? []) {
         if (!provided.has(handle)) {
@@ -667,6 +719,7 @@ export async function mountPlugins(
         }
       : undefined
 
+  markReady()
   let disposed: Promise<void> | undefined
   return {
     tools: tools
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index c9473d5e86..f3da1d687f 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -461,6 +461,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           )) as PluginAgentActions['start'],
         group: (options, body) => this.agentGroup(options, body),
       },
+      commandsChanged: () =>
+        this.feed.publish(
+          'session',
+          customEvent(HARNESS_EVENTS.commandsChanged, {}),
+        ),
     }
     this.registry = this.agentRegistry
     for (const agent of this.harness.agents ?? []) {
diff --git a/packages/ai-harness/src/types.ts b/packages/ai-harness/src/types.ts
index f941a60ea7..c3ecf562b2 100644
--- a/packages/ai-harness/src/types.ts
+++ b/packages/ai-harness/src/types.ts
@@ -171,6 +171,8 @@ export const HARNESS_EVENTS = {
   operationFinished: 'harness.operation.finished',
   operationResumed: 'harness.operation.resumed',
   configChanged: 'harness.config.changed',
+  /** A plugin added or removed a command with `ctx.commands`. */
+  commandsChanged: 'harness.commands.changed',
   question: 'harness.question',
   questionAnswered: 'harness.question.answered',
   pluginEvent: 'harness.plugin.event',
diff --git a/packages/ai-harness/src/view/index.ts b/packages/ai-harness/src/view/index.ts
index 50f7cb4ac6..90d327d9b7 100644
--- a/packages/ai-harness/src/view/index.ts
+++ b/packages/ai-harness/src/view/index.ts
@@ -458,7 +458,10 @@ export function createSessionView(source: SessionViewSource) {
         event.name === HARNESS_EVENTS.operationFinished &&
         chatTurns.delete(operationId)
       if (isTurnEnd) emit('turnEnd', { operationId })
-      if (event.name === HARNESS_EVENTS.configChanged) refreshDescription()
+      const isDescriptionChange =
+        event.name === HARNESS_EVENTS.configChanged ||
+        event.name === HARNESS_EVENTS.commandsChanged
+      if (isDescriptionChange) refreshDescription()
     }
     for (const signIn of after.signIns)
       if (!before.signIns.includes(signIn)) emit('signIn', signIn)
diff --git a/packages/ai-harness/tests/live-commands.test.ts b/packages/ai-harness/tests/live-commands.test.ts
new file mode 100644
index 0000000000..3b34e53b5a
--- /dev/null
+++ b/packages/ai-harness/tests/live-commands.test.ts
@@ -0,0 +1,154 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { EventType } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  HARNESS_EVENTS,
+  createHarnessHost,
+  defineCommand,
+  defineHarness,
+  definePlugin,
+} from '../src'
+import { createSessionView } from '../src/view'
+import { mockAdapter } from './helpers'
+import type {
+  HarnessHost,
+  HarnessPlugin,
+  PluginCommands,
+  SessionEvent,
+} from '../src'
+
+const hosts: Array<HarnessHost> = []
+afterEach(async () => {
+  await Promise.all(hosts.splice(0).map((host) => host.close()))
+})
+
+/** A command that answers `text`. */
+const say = (text: string) =>
+  defineCommand({ description: `Says ${text}`, run: () => text })
+
+/**
+ * A plugin that keeps its `ctx.commands` for the test, with one command from
+ * its setup result when `fixed` is set.
+ */
+function capture(name: string, fixed?: string) {
+  let commands: PluginCommands | undefined
+  const plugin = definePlugin({
+    name,
+    setup: (ctx) => {
+      commands = ctx.commands
+      return fixed ? { commands: { [fixed]: say(`${name} ran`) } } : {}
+    },
+  })
+  const live = () => {
+    if (!commands) throw new Error(`${name} is not set up`)
+    return commands
+  }
+  return { plugin, live }
+}
+
+async function open(...plugins: Array<HarnessPlugin>) {
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  hosts.push(host)
+  const session = await host.open(
+    defineHarness({
+      name: 'test/live-commands',
+      adapter: mockAdapter([]).adapter,
+      plugins: () => plugins,
+    }),
+    { threadId: 't' },
+  )
+  const names = () => session.commands().map((command) => command.name)
+  return { session, names }
+}
+
+describe('ctx.commands', () => {
+  it('adds a command that the session lists and runs, then removes it', async () => {
+    const live = capture('test/live')
+    const { session, names } = await open(live.plugin)
+
+    live.live().set('hello', say('hi'))
+    expect(names()).toContain('hello')
+    expect(
+      session.describe().commands.find((command) => command.name === 'hello'),
+    ).toMatchObject({ owner: 'test/live', description: 'Says hi' })
+    expect(await session.command('hello')).toBe('hi')
+
+    live.live().delete('hello')
+    expect(names()).not.toContain('hello')
+    await expect(session.command('hello')).rejects.toThrow(
+      'Unknown command: hello',
+    )
+  })
+
+  it('keeps the commands of other plugins', async () => {
+    const other = capture('test/other', 'model')
+    const live = capture('test/live')
+    const { session } = await open(other.plugin, live.plugin)
+
+    expect(live.live().has('model')).toBe(true)
+    expect(() => live.live().set('model', say('taken'))).toThrow(
+      'Command "model" belongs to test/other. test/live cannot replace it.',
+    )
+    live.live().delete('model')
+    expect(await session.command('model')).toBe('test/other ran')
+  })
+
+  it('is ready after the plugins that come later are set up', async () => {
+    const seen: { atSetup?: boolean; atReady?: boolean } = {}
+    const early = definePlugin({
+      name: 'test/early',
+      setup: (ctx) => {
+        seen.atSetup = ctx.commands.has('later')
+        void ctx.commands.ready.then(() => {
+          seen.atReady = ctx.commands.has('later')
+        })
+      },
+    })
+    await open(early, capture('test/later', 'later').plugin)
+
+    await vi.waitFor(() => expect(seen.atReady).toBe(true))
+    expect(seen.atSetup).toBe(false)
+  })
+
+  it('tells the session feed when the commands change', async () => {
+    const live = capture('test/live')
+    const { session } = await open(live.plugin)
+    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)
+    })()
+
+    live.live().set('hello', say('hi'))
+    await vi.waitFor(() =>
+      expect(
+        seen.some(
+          (entry) =>
+            entry.event.type === EventType.CUSTOM &&
+            entry.event.name === HARNESS_EVENTS.commandsChanged,
+        ),
+      ).toBe(true),
+    )
+    controller.abort()
+    await reading
+  })
+
+  it('updates a session view when a command comes and goes', async () => {
+    const live = capture('test/live')
+    const { session } = await open(live.plugin)
+    const view = createSessionView(session)
+    await view.ready
+    const viewNames = () =>
+      view.store.get().commands.map((command) => command.name)
+
+    live.live().set('hello', say('hi'))
+    await vi.waitFor(() => expect(viewNames()).toContain('hello'))
+    live.live().delete('hello')
+    await vi.waitFor(() => expect(viewNames()).not.toContain('hello'))
+    view.dispose()
+  })
+})

From 0ef10280ca64b58b094fd66df0113b21e6eef961 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 13:54:21 +0200
Subject: [PATCH 117/286] test(ai-sandbox): call the plan-mode delegates in two
 model steps

Parallel tools start the 4 delegate calls of one model step at the same time. The default subagent limit runs 3 at a time, so the 4th call got 'subagent limit reached' and the test read an empty call list.
---
 packages/ai-sandbox/tests/coding-agents.test.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/ai-sandbox/tests/coding-agents.test.ts b/packages/ai-sandbox/tests/coding-agents.test.ts
index 3d9dfc1332..7c4998f9c4 100644
--- a/packages/ai-sandbox/tests/coding-agents.test.ts
+++ b/packages/ai-sandbox/tests/coding-agents.test.ts
@@ -344,10 +344,14 @@ describe('codingAgents', () => {
     const other = codingAgent('grok-build')
     const custom = codingAgent('acp')
     const { host, session } = await open({
+      // Two calls per step: parallel tools start the calls of one step at
+      // once, and the default subagent limit runs 3 at a time.
       leadSteps: [
         [
           ['claude_code', 'look'],
           ['codex', 'look'],
+        ],
+        [
           ['grok', 'look'],
           ['custom', 'look'],
         ],

From a22ceac7f2869623e57320ee865b29e8931b3e43 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 13:54:25 +0200
Subject: [PATCH 118/286] fix(ai-harness): bind durable tools that a middleware
 returns

A middleware can give the model new tools from onConfig. The session now binds the durable tools of each model call, so a swapped-in durable tool gets step and append. A tool is bound once per session, so a middleware wrapper around a bound tool stays.
---
 packages/ai-harness/src/durable-tool.ts       |  36 +++--
 packages/ai-harness/src/session.ts            |  43 ++++--
 .../ai-harness/tests/durable-tools.test.ts    | 124 +++++++++++++++++-
 3 files changed, 184 insertions(+), 19 deletions(-)

diff --git a/packages/ai-harness/src/durable-tool.ts b/packages/ai-harness/src/durable-tool.ts
index b5cc499f01..364fa454d1 100644
--- a/packages/ai-harness/src/durable-tool.ts
+++ b/packages/ai-harness/src/durable-tool.ts
@@ -155,22 +155,33 @@ function isDurableTool(
   return typeof Reflect.get(tool, DURABLE_EXECUTE) === 'function'
 }
 
+/**
+ * The binder that bound a durable tool. An own enumerable symbol key, so a
+ * spread copy (a middleware wrapper) stays bound.
+ */
+const DURABLE_BINDER: unique symbol = Symbol(
+  'tanstack.ai-harness.durable-binder',
+)
+
+/** @internal */
+export type DurableBind = (toolCallId: string) => {
+  step: ToolStep
+  append: DurableToolContext['append']
+}
+
 /**
  * Give a {@link durableTool} the `step` and `append` of a durable session.
- * `bind` gets the id of each call. Another tool comes back as it is.
+ * `bind` gets the id of each call. Another tool, and a tool that `bind`
+ * already bound, comes back as it is.
  *
  * @internal
  */
-export function bindDurable(
-  tool: AnyTool,
-  bind: (toolCallId: string) => {
-    step: ToolStep
-    append: DurableToolContext['append']
-  },
-) {
-  if (!isDurableTool(tool)) return tool
+export function bindDurable(tool: AnyTool, bind: DurableBind) {
+  if (!isDurableTool(tool) || Reflect.get(tool, DURABLE_BINDER) === bind) {
+    return tool
+  }
   const execute = tool[DURABLE_EXECUTE]
-  return {
+  const bound = {
     ...tool,
     execute: (args: unknown, context?: ToolExecutionContext) => {
       const base = context ?? emptyContext
@@ -180,4 +191,9 @@ export function bindDurable(
       return execute(args, { ...base, ...bind(base.toolCallId) })
     },
   }
+  Object.defineProperty(bound, DURABLE_BINDER, {
+    value: bind,
+    enumerable: true,
+  })
+  return bound
 }
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index c9473d5e86..a214ef6a8d 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -65,6 +65,7 @@ import type {
 import type { AuthRequiredError, CredentialsAccess } from './auth'
 import type { EventFeed } from './feed'
 import type { ProjectOptions } from './log'
+import type { DurableBind } from './durable-tool'
 import type { LeaseOptions } from './resume'
 import type { MediaStore } from './media'
 import type { PluginSessionApi, Question } from './commands'
@@ -368,6 +369,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   private closing: Promise<void> | undefined
   private readonly onClose: () => void
   private checkpoint: AnyChatMiddleware | undefined
+  /** Gives each durable tool call its steps in the log. One per session. */
+  private bindTool: DurableBind | undefined
   private readonly hostId: string
   private readonly lease: LeaseOptions | undefined
   private readonly listeners = new Map<string, Set<(value: unknown) => void>>()
@@ -588,6 +591,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           }
         : {}),
     })
+    if (writer) {
+      this.bindTool = (toolCallId) => this.durableBinding(writer, toolCallId)
+    }
   }
 
   /**
@@ -1462,6 +1468,27 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     )
   }
 
+  /**
+   * Middleware that binds the durable tools of each model call: a
+   * middleware can return new tools from `onConfig`, and the engine runs the
+   * tools of that list.
+   */
+  private durableTools(): AnyChatMiddleware | undefined {
+    const { bindTool } = this
+    if (!bindTool) return undefined
+    return {
+      name: 'harness:durable-tools',
+      onConfig: (ctx, config) => {
+        if (ctx.phase !== 'init' && ctx.phase !== 'beforeModel') return
+        const tools = config.tools.map((tool) => bindDurable(tool, bindTool))
+        const isSame = tools.every(
+          (tool, index) => tool === config.tools[index],
+        )
+        return isSame ? undefined : { tools }
+      },
+    }
+  }
+
   /**
    * Middleware that runs before each model call. Queued steers join the
    * running turn in admission order. On a durable host, one append commits
@@ -1744,14 +1771,12 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         [...staticTools, ...discovered],
         operation,
       )
-      // A durable host gives each durableTool call its steps in the log.
-      const { writer } = this
-      const tools = writer
-        ? prepared.map((tool) =>
-            bindDurable(tool, (toolCallId) =>
-              this.durableBinding(writer, toolCallId),
-            ),
-          )
+      // A durable host gives each durableTool call its steps in the log. The
+      // tools are bound here, so a middleware wrapper wraps the bound tool,
+      // and again at each model call, for tools that a middleware returns.
+      const { bindTool } = this
+      const tools = bindTool
+        ? prepared.map((tool) => bindDurable(tool, bindTool))
         : prepared
       // A keyed adapter is built for this turn with the user's key. A
       // missing key publishes `auth_required` and fails the turn.
@@ -1768,6 +1793,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       if (!chatPersistence || !checkpoint) {
         throw new Error('The session is not open yet.')
       }
+      const durableTools = this.durableTools()
       // One chat() run, and one more each time steers wait after a final
       // answer: a late join gets its answer in this turn.
       for (;;) {
@@ -1788,6 +1814,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             ...(this.harness.middleware ?? []),
             ...(session?.middleware ?? []),
             ...(runPlugins?.middleware ?? []),
+            ...(durableTools ? [durableTools] : []),
             this.steering(),
             // Last, because a later middleware that returns `messages` (as
             // steering does) resets what the model gets.
diff --git a/packages/ai-harness/tests/durable-tools.test.ts b/packages/ai-harness/tests/durable-tools.test.ts
index 527f930cd1..990c2a9328 100644
--- a/packages/ai-harness/tests/durable-tools.test.ts
+++ b/packages/ai-harness/tests/durable-tools.test.ts
@@ -5,7 +5,7 @@ import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness, durableTool } from '../src'
 import { INTERRUPTED_TOOL_RESULT } from '../src/resume'
 import { gate, mockAdapter, text, toolCall } from './helpers'
-import type { AnyTool, StreamChunk } from '@tanstack/ai'
+import type { AnyChatMiddleware, AnyTool, StreamChunk } from '@tanstack/ai'
 import type { Reply } from './helpers'
 
 const THREAD = 't1'
@@ -334,3 +334,125 @@ describe('a durable tool with replay: never', () => {
     await next.host.close()
   })
 })
+
+describe('durable tools that middleware returns', () => {
+  it('binds a durable tool that onConfig swaps in during the turn', async () => {
+    const persistence = durablePersistence()
+    const charge = vi.fn(async () => 'c-1')
+    const charged = gate()
+    const hostStops = gate()
+    let isFirstRun = true
+    const pay = durableTool(
+      toolDefinition({ name: 'pay', description: 'Pay the order' }),
+      async (_args, { step, append }) => {
+        const payment = await step.do('charge', charge)
+        append([{ type: 'app.paid', payment }])
+        if (isFirstRun) {
+          isFirstRun = false
+          charged.open()
+          // The first host stops here.
+          await hostStops.opened
+        }
+        return payment
+      },
+    )
+    const look = toolDefinition({ name: 'look', description: 'Look' }).server(
+      async () => 'seen',
+    )
+    // After `look` answered, the model gets `pay` in place of `look`, like
+    // a framework that renders its tools from the state.
+    const swap: AnyChatMiddleware = {
+      name: 'swap',
+      onConfig: (ctx, config) => {
+        if (ctx.phase !== 'init' && ctx.phase !== 'beforeModel') return
+        const looked = config.messages.some(
+          (message) =>
+            message.role === 'tool' && message.toolCallId === 'call-look',
+        )
+        return looked ? { tools: [pay] } : undefined
+      },
+    }
+    const open = async (replies: Array<Reply>) => {
+      const { adapter, calls } = mockAdapter(replies)
+      const host = createHarnessHost({ persistence })
+      const session = await host.open(
+        defineHarness({
+          name: 'test/durable-tools',
+          adapter,
+          tools: [look],
+          middleware: [swap],
+        }),
+        { threadId: THREAD },
+      )
+      return { host, session, calls }
+    }
+    const first = await open([
+      () => toolCall('look', {}, 'call-look'),
+      () => toolCall('pay', {}, 'call-pay'),
+    ])
+    const turn = first.session.prompt('pay', { inputId: 'pay-1' })
+    await charged.opened
+    await vi.waitFor(async () =>
+      expect(await recordsOf(persistence, 'harness.tool.step')).toHaveLength(1),
+    )
+    await expireLease(persistence, turn.id)
+
+    const next = await open([() => text('paid')])
+    expect(await next.session.settled('pay-1')).toMatchObject({
+      outcome: 'completed',
+    })
+
+    expect(charge).toHaveBeenCalledTimes(1)
+    expect(await recordsOf(persistence, 'app.paid')).toEqual([
+      { type: 'app.paid', payment: 'c-1' },
+    ])
+    hostStops.open()
+    await Promise.resolve(turn).catch(() => {})
+    await first.host.close().catch(() => {})
+    await next.host.close()
+  })
+
+  it('keeps a middleware wrapper around a bound durable tool', async () => {
+    const persistence = durablePersistence()
+    const wrapped: Array<string> = []
+    const note = durableTool(
+      toolDefinition({ name: 'note', description: 'Write a note' }),
+      async (_args, { step }) => step.do('write', async () => 'noted'),
+    )
+    const wrap: AnyChatMiddleware = {
+      name: 'wrap',
+      onConfig: (ctx, config) => {
+        if (ctx.phase !== 'init') return
+        return {
+          tools: config.tools.map((tool) => ({
+            ...tool,
+            execute: async (args: unknown, context: any) => {
+              wrapped.push(tool.name)
+              return tool.execute?.(args, context)
+            },
+          })),
+        }
+      },
+    }
+    const { adapter } = mockAdapter([
+      () => toolCall('note', {}, 'call-note'),
+      () => text('done'),
+    ])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/durable-tools',
+        adapter,
+        tools: [note],
+        middleware: [wrap],
+      }),
+      { threadId: THREAD },
+    )
+
+    await session.prompt('note it')
+
+    expect(wrapped).toEqual(['note'])
+    expect(await recordsOf(persistence, 'harness.tool.step')).toHaveLength(1)
+    await host.close()
+  })
+})

From b0a8a738e646d42d38e4a0a043c37c59e6ea747a Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 14:08:19 +0200
Subject: [PATCH 119/286] feat(ai-skills): skills() harness plugin with live
 slash commands

- @tanstack/ai-skills/harness: skills({ dirs, reserved }) gives the model
  the skills of a list of folders (short entries, earlier folders first
  under the token cap, called skills always kept) and makes each skill a
  /<name> command that starts a turn with it. A taken name is
  /skill:<name>. /skills lists them. The plugin watches the folders (and
  the parent of a folder that does not exist yet) and lists them at each
  turn start, so new and removed skills change the commands at once.
- harness-cli example: skills from ./.agents/skills, ./.claude/skills,
  and ~/.tanstack-harness-example/skills; lazy code-mode tools; the input
  box keeps the full width again.
- Docs: the new harness skills page, ctx.commands in the plugins page,
  lazy tools in the code-mode page. Changeset for the three packages.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/harness-skills.md             |  11 +
 docs/config.json                         |  12 +-
 docs/harness/code-mode.md                |  21 ++
 docs/harness/plugins.md                  |  51 ++++
 docs/harness/skills.md                   | 101 ++++++++
 docs/skills/agent-skills.md              |   2 +
 examples/harness-cli/README.md           |  12 +
 examples/harness-cli/package.json        |   1 +
 examples/harness-cli/src/harness.ts      |  23 +-
 examples/harness-cli/src/tui.tsx         |   3 +-
 packages/ai-skills/package.json          |   9 +
 packages/ai-skills/src/harness.ts        | 315 +++++++++++++++++++++++
 packages/ai-skills/src/middleware.ts     |   2 +-
 packages/ai-skills/tests/harness.test.ts | 237 +++++++++++++++++
 packages/ai-skills/vite.config.ts        |   1 +
 pnpm-lock.yaml                           |   6 +
 16 files changed, 799 insertions(+), 8 deletions(-)
 create mode 100644 .changeset/harness-skills.md
 create mode 100644 docs/harness/skills.md
 create mode 100644 packages/ai-skills/src/harness.ts
 create mode 100644 packages/ai-skills/tests/harness.test.ts

diff --git a/.changeset/harness-skills.md b/.changeset/harness-skills.md
new file mode 100644
index 0000000000..b0c9ebd23c
--- /dev/null
+++ b/.changeset/harness-skills.md
@@ -0,0 +1,11 @@
+---
+'@tanstack/ai-harness': minor
+'@tanstack/ai-skills': minor
+'@tanstack/ai-code-mode': minor
+---
+
+Skills in a harness, live commands, and lazy code-mode tools.
+
+- `@tanstack/ai-skills/harness`: the new `skills({ dirs })` plugin gives the harness model the skills of a list of folders, and makes each skill a `/<name>` command that starts a turn with that skill. A skill with the name of another command is `/skill:<name>`, and `/skills` lists them. The plugin watches the folders, so a skill that you add or remove while the session runs changes the commands at once.
+- `@tanstack/ai-harness`: `ctx.commands` (`has`, `set`, `delete`, `ready`) lets a plugin add and remove its commands while the session runs. Each change sends a `harness.commands.changed` event, and session views read the command list again.
+- `@tanstack/ai-code-mode`: `codeMode({ lazy: true })` makes each tool that moves into code mode lazy. The prompt lists only the tool names, and the model asks `discover_tools` for the signatures before it calls them.
diff --git a/docs/config.json b/docs/config.json
index d3862cf980..655315e6a7 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -584,7 +584,7 @@
           "label": "Portable Agent Skills",
           "to": "skills/agent-skills",
           "addedAt": "2026-08-22",
-          "updatedAt": "2026-08-23"
+          "updatedAt": "2026-10-01"
         },
         {
           "label": "Skill Sources",
@@ -922,7 +922,7 @@
           "label": "Write a plugin",
           "to": "harness/plugins",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-09-28"
+          "updatedAt": "2026-10-01"
         },
         {
           "label": "Build a coding agent",
@@ -956,7 +956,13 @@
         {
           "label": "Code mode in a harness",
           "to": "harness/code-mode",
-          "addedAt": "2026-09-26"
+          "addedAt": "2026-09-26",
+          "updatedAt": "2026-10-01"
+        },
+        {
+          "label": "Add skills",
+          "to": "harness/skills",
+          "addedAt": "2026-10-01"
         },
         {
           "label": "Delegate to coding agents",
diff --git a/docs/harness/code-mode.md b/docs/harness/code-mode.md
index a73963b6f5..8f93c89e93 100644
--- a/docs/harness/code-mode.md
+++ b/docs/harness/code-mode.md
@@ -85,6 +85,26 @@ export const onlyLinear = codeMode({
 
 The other options of `createCodeMode` pass through: `timeout`, `memoryLimit`, `lazyToolsConfig`, and more.
 
+## 4. Send only the tool names
+
+The prompt of code mode lists each moved tool with its full TypeScript type. With 100 tools, that is a lot of tokens on every turn, and most turns use a few tools. Set `lazy: true`, and the prompt lists only the names:
+
+```ts group=harness-code-mode
+export const lazyCodeMode = codeMode({
+  driver: createQuickJSIsolateDriver(),
+  lazy: true,
+  lazyToolsConfig: { includeDescription: 'first-sentence' },
+})
+```
+
+The model then works in three steps:
+
+1. It reads the tool names in the prompt.
+2. It calls `discover_tools` with the names it needs, and gets their TypeScript signatures.
+3. It calls those tools in `execute_typescript`.
+
+`includeDescription` sets what the prompt shows with each name: `'none'` (the default, the name only), `'first-sentence'`, or `'full'`. Tools that stay outside code mode keep their full schema.
+
 ## Tools that appear after sign-in
 
 The plugin chooses the tools again before every turn. When the user runs `/connect linear`, the read-only Linear tools move into code mode on the next turn. A plugin can do the same with its own tool changes: return the new list from `prepareTools`. [Use MCP servers](./mcp) shows `discoverTools`, which adds the tools first.
@@ -92,5 +112,6 @@ The plugin chooses the tools again before every turn. When the user runs `/conne
 ## What you have now
 
 - One `execute_typescript` tool in place of many read-only tools.
+- With `lazy: true`, a prompt that lists only the tool names.
 - Programs that run in the isolate you choose.
 - Approvals kept for every tool that can change something.
diff --git a/docs/harness/plugins.md b/docs/harness/plugins.md
index 9efa2dd835..c6845cb957 100644
--- a/docs/harness/plugins.md
+++ b/docs/harness/plugins.md
@@ -76,6 +76,57 @@ export const greeter = definePlugin({
 - `session.setConfig('tone', 'warm')` changes the setting. A value the option does not accept is rejected.
 - `ask` waits for `session.answer(questionId, value)`. The question shows up in `session.snapshot().pendingQuestions`, and the CLI prompts for it.
 
+## Change commands while the session runs
+
+Some commands come from data that changes: a folder of skills, saved shortcuts, a list from a server. `ctx.commands` adds and removes them while the session runs. Here `/macro` saves a new command that sends a message:
+
+```ts group=harness-plugins
+export const macros = definePlugin({
+  name: 'acme/macros',
+  setup: (ctx) => ({
+    commands: {
+      macro: defineCommand({
+        description: 'Save a command that sends a message: /macro <name> <message>',
+        run: (input: unknown) => {
+          const [name = '', ...words] = String(input ?? '').trim().split(' ')
+          if (ctx.commands.has(name)) return `/${name} is taken.`
+          ctx.commands.set(
+            name,
+            defineCommand({
+              description: `Send: ${words.join(' ')}`,
+              run: () => {
+                void ctx.session.prompt(words.join(' '))
+              },
+            }),
+          )
+          return `Saved /${name}.`
+        },
+      }),
+    },
+  }),
+})
+```
+
+- `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.
+- Session views (`createSessionView`) get the new list at once, so the command shows in the `/` list of a CLI.
+- 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
+export const greetings = definePlugin({
+  name: 'acme/greetings',
+  setup: (ctx) => {
+    void ctx.commands.ready.then(() => {
+      if (!ctx.commands.has('hi')) {
+        ctx.commands.set('hi', defineCommand({ description: 'Say hi', run: () => 'Hi!' }))
+      }
+    })
+  },
+})
+```
+
+The [skills plugin](./skills) works this way: one command for each skill in a folder.
+
 ## Keep state
 
 `ctx.state(initial)` gives a plugin its own state, saved in the metadata store. Clients see each change as an AG-UI `STATE_SNAPSHOT` event.
diff --git a/docs/harness/skills.md b/docs/harness/skills.md
new file mode 100644
index 0000000000..189228ffe5
--- /dev/null
+++ b/docs/harness/skills.md
@@ -0,0 +1,101 @@
+---
+title: Add skills to a harness
+id: harness-skills
+order: 10
+description: "Give the harness model the skills in a list of folders, and make each skill a slash command. A skill that you add while the session runs works at once."
+keywords:
+  - tanstack ai
+  - harness
+  - skills
+  - SKILL.md
+  - slash commands
+---
+
+Your users keep skills as `SKILL.md` folders, in the repo and in their home folder, and they want to call them from your agent like any other command. The skills plugin reads those folders, gives the model the list of skills, and makes each skill a `/<name>` command. A skill that a user adds while the session runs works at once.
+
+## 1. Add the plugin
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: @tanstack/ai-skills
+vue: @tanstack/ai-skills
+solid: @tanstack/ai-skills
+svelte: @tanstack/ai-skills
+preact: @tanstack/ai-skills
+angular: @tanstack/ai-skills
+octane: @tanstack/ai-skills
+vanilla: @tanstack/ai-skills
+
+<!-- ::end:tabs -->
+
+```ts group=harness-skills
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { defineHarness } from '@tanstack/ai-harness'
+import { openaiText } from '@tanstack/ai-openai'
+import { skills } from '@tanstack/ai-skills/harness'
+
+export const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-5.6'),
+  plugins: () => [
+    skills({
+      dirs: ['./.agents/skills', join(homedir(), '.acme', 'skills')],
+    }),
+  ],
+})
+```
+
+- `dirs` lists the skill folders. Each one holds skill folders with a `SKILL.md`.
+- When two folders have a skill with the same name, the first folder wins. Put the repo folder first, so a project can replace a user's skill.
+- A folder that does not exist yet is fine. Its skills show once the user makes it.
+
+## 2. Call a skill
+
+`/release-notes write them for v2` starts a turn with "Use the release-notes skill: write them for v2". The model loads the skill with `load_skill`, then does the task. `/release-notes` alone asks for the skill with no task.
+
+The model also sees the list of skills, so it can load one on its own when a task matches.
+
+## Names that are taken
+
+A skill with the name of another command gets a prefix: a `model` skill is `/skill:model`, and `/model` stays the model picker. Pass `reserved` with the names that your UI handles itself:
+
+```ts group=harness-skills
+export const cliSkills = skills({
+  dirs: ['./.agents/skills'],
+  reserved: ['help', 'exit'],
+})
+```
+
+`/skills` lists every skill, its folder, and its command.
+
+## Skills that change while the session runs
+
+The plugin watches the folders, and it lists them again at the start of each turn:
+
+- A new `SKILL.md` adds its command.
+- A removed skill takes its command away.
+- An edited description updates the command.
+- A broken `SKILL.md` is left out until it is fixed.
+
+A UI built on `createSessionView` shows each change in its command list at once.
+
+## Many skills
+
+The model's list has one line for each skill: the name and the first sentence of the description. When the list is longer than `maxCatalogTokens` (default 4000), the skills of the earlier folders stay, and the rest leave the model's list. A skill that the user calls with its command always stays in it.
+
+The other options of `withSkills` pass through, for example `maxCatalogTokens` and `requireApproval`:
+
+```ts group=harness-skills
+export const manySkills = skills({
+  dirs: ['./.agents/skills'],
+  maxCatalogTokens: 8000,
+})
+```
+
+## What you have now
+
+- The skills of your folders, in the model's list and as `/<name>` commands.
+- New and changed skills that work in a running session, with no restart.
+
+Next: [Agent Skills](../skills/agent-skills) has the `SKILL.md` format, and [Write a harness plugin](./plugins#change-commands-while-the-session-runs) shows the `ctx.commands` API that the plugin uses.
diff --git a/docs/skills/agent-skills.md b/docs/skills/agent-skills.md
index 889ee7a6cc..33253b7ea2 100644
--- a/docs/skills/agent-skills.md
+++ b/docs/skills/agent-skills.md
@@ -243,3 +243,5 @@ skills that run in a provider's own sandbox instead, see
   or a registry, and prove it with the conformance suite.
 - [Provider Skills](../tools/provider-skills) — hosted skills that run in a
   provider sandbox, and when to use them instead.
+- [Add skills to a harness](../harness/skills): give a harness the skills of a
+  list of folders, each one as a slash command.
diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index ed4c52d89d..acc76011db 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -97,6 +97,18 @@ When `claude` and `codex` are on the PATH, the agent can call them. They work in
 
 - Sign-ins are kept in `~/.tanstack-harness-example/credentials.json`, so you sign in once. `/disconnect notion` deletes one.
 - Code mode is on: read-only tools (file reads, read-only Notion and Linear tools) are functions in one `execute_typescript` program, which runs in a QuickJS isolate.
+- The code-mode tools are lazy: the model gets only their names, and asks `discover_tools` for the signatures it needs.
+
+## Use skills
+
+1. Make a folder with a `SKILL.md` in one of the skill folders, for example `./.agents/skills/release-notes/SKILL.md`.
+2. Type `/release-notes write them for v2`. The model loads the skill and does the task.
+
+- The skill folders, in order: `./.agents/skills` and `./.claude/skills` in the folder where you run the app, then `~/.tanstack-harness-example/skills` for skills in every project. When two folders have a skill with the same name, the first folder wins.
+- A skill you add while the app runs shows in the `/` list at once. No restart.
+- A skill with the name of a command, for example `help`, is `/skill:help`.
+- `/skills` lists every skill, its folder, and its command.
+- The model also sees the list of skills, with the first sentence of each description, and can load one on its own.
 
 ## Pick the model and the effort
 
diff --git a/examples/harness-cli/package.json b/examples/harness-cli/package.json
index c0f8ec2517..acb8397f3a 100644
--- a/examples/harness-cli/package.json
+++ b/examples/harness-cli/package.json
@@ -28,6 +28,7 @@
     "@tanstack/ai-persistence": "workspace:*",
     "@tanstack/ai-sandbox": "workspace:*",
     "@tanstack/ai-sandbox-local-process": "workspace:*",
+    "@tanstack/ai-skills": "workspace:*",
     "@tanstack/react-store": "^0.11.1",
     "beautiful-mermaid": "^1.1.3",
     "ink": "^7.1.1",
diff --git a/examples/harness-cli/src/harness.ts b/examples/harness-cli/src/harness.ts
index b9ec5f295f..dffc61a982 100644
--- a/examples/harness-cli/src/harness.ts
+++ b/examples/harness-cli/src/harness.ts
@@ -44,6 +44,7 @@ import {
 import { codingAgents } from '@tanstack/ai-sandbox/harness'
 import type { CodingAgentConfig } from '@tanstack/ai-sandbox/harness'
 import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'
+import { skills } from '@tanstack/ai-skills/harness'
 import { z } from 'zod'
 import {
   imageAgent,
@@ -53,6 +54,8 @@ import {
   videoAgent,
 } from './media'
 import { effortPicker } from './effort'
+import { SAVE_DIR } from './credentials'
+import { SCREEN_COMMANDS } from './screen/commands'
 import { envKey, providerKey } from './store'
 import type { AnyTextAdapter, KeyedAdapter } from '@tanstack/ai'
 import type { ModelRecord } from '@tanstack/ai-models'
@@ -508,11 +511,25 @@ export const assistant = defineHarness({
     usage(),
     // /goal keeps the agent working until the main model says the goal is met.
     goal({ judge: main }),
+    // Skills: each folder holds skill folders with a SKILL.md. Each skill is a
+    // /<name> command, and the model sees the list. A skill you add while the
+    // app runs shows at once. The repo folders (where you run the app) win
+    // over the global one. A skill named like a screen command is
+    // /skill:<name>.
+    skills({
+      dirs: ['./.agents/skills', './.claude/skills', join(SAVE_DIR, 'skills')],
+      reserved: SCREEN_COMMANDS.map((command) => command.name),
+    }),
     // Read-only tools (file reads, read-only Notion and Linear tools) move
     // behind execute_typescript, so the model can call several in one program.
-    // The program runs in a QuickJS isolate. Any @tanstack/ai-isolate-* driver
-    // works here.
-    codeMode({ driver: createQuickJSIsolateDriver() }),
+    // The tools are lazy: the model gets their names, asks discover_tools for
+    // the signatures it needs, then calls them in the program. The program
+    // runs in a QuickJS isolate. Any @tanstack/ai-isolate-* driver works here.
+    codeMode({
+      driver: createQuickJSIsolateDriver(),
+      lazy: true,
+      lazyToolsConfig: { includeDescription: 'first-sentence' },
+    }),
     ...coding,
   ],
 })
diff --git a/examples/harness-cli/src/tui.tsx b/examples/harness-cli/src/tui.tsx
index fb16182b72..76ae0d0817 100644
--- a/examples/harness-cli/src/tui.tsx
+++ b/examples/harness-cli/src/tui.tsx
@@ -1021,7 +1021,8 @@ function App({ view }: { view: SessionView }) {
           />
         ))}
         <Status view={view} voice={voice} recording={recorder} />
-        <Box ref={inputBox}>
+        {/* A column, so the input box keeps the full width. */}
+        <Box ref={inputBox} flexDirection="column">
           <InputBox
             line={editor.line}
             voice={voice}
diff --git a/packages/ai-skills/package.json b/packages/ai-skills/package.json
index a5c578f0af..d9d9fd21f0 100644
--- a/packages/ai-skills/package.json
+++ b/packages/ai-skills/package.json
@@ -25,6 +25,10 @@
       "types": "./dist/esm/index.d.ts",
       "import": "./dist/esm/index.js"
     },
+    "./harness": {
+      "types": "./dist/esm/harness.d.ts",
+      "import": "./dist/esm/harness.js"
+    },
     "./node": {
       "types": "./dist/esm/node/index.d.ts",
       "import": "./dist/esm/node/index.js"
@@ -75,15 +79,20 @@
   },
   "peerDependencies": {
     "@tanstack/ai": "workspace:^",
+    "@tanstack/ai-harness": "workspace:^",
     "vitest": "^4.1.10",
     "zod": "^3.0.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
+    "@tanstack/ai-harness": {
+      "optional": true
+    },
     "vitest": {
       "optional": true
     }
   },
   "devDependencies": {
+    "@tanstack/ai-harness": "workspace:*",
     "@vitest/coverage-v8": "4.1.10",
     "vitest": "^4.1.10",
     "zod": "^4.2.0"
diff --git a/packages/ai-skills/src/harness.ts b/packages/ai-skills/src/harness.ts
new file mode 100644
index 0000000000..143c55491a
--- /dev/null
+++ b/packages/ai-skills/src/harness.ts
@@ -0,0 +1,315 @@
+import { watch } from 'node:fs'
+import { dirname } from 'node:path'
+import { firstSentence } from '@tanstack/ai'
+import { defineCommand, definePlugin } from '@tanstack/ai-harness'
+import { renderCatalog } from './catalog'
+import { estimateTokens, withSkills } from './middleware'
+import { skillDirectory } from './node'
+import type { FSWatcher } from 'node:fs'
+import type { AnyChatMiddleware } from '@tanstack/ai'
+import type { SkillsOptions } from './middleware'
+import type { ModelFamily, SkillMetadata, SkillSource } from './types'
+
+export interface SkillsPluginOptions extends SkillsOptions {
+  /**
+   * The skill folders. Each folder holds skill folders with a `SKILL.md`.
+   * When two folders have a skill with the same name, the first folder wins.
+   * A folder that does not exist yet is used once it exists.
+   */
+  dirs: ReadonlyArray<string>
+  /**
+   * Names that a UI handles itself, for example its own `/help`. A skill
+   * with one of these names gets the command `/skill:<name>`.
+   */
+  reserved?: ReadonlyArray<string>
+}
+
+/** A skill, and the folder it comes from. */
+interface FoundSkill {
+  skill: SkillMetadata
+  dir: string
+}
+
+/**
+ * The skills of `dirs`, by name, in folder order. The first folder wins a
+ * name. A folder that is missing or cannot be read gives no skills, and a
+ * broken `SKILL.md` is left out.
+ */
+async function scan(dirs: ReadonlyArray<string>) {
+  const found = new Map<string, FoundSkill>()
+  for (const dir of dirs) {
+    const listed = await skillDirectory(dir, { strict: false })
+      .list()
+      .catch(() => [])
+    for (const skill of listed) {
+      if (!found.has(skill.name)) found.set(skill.name, { skill, dir })
+    }
+  }
+  return found
+}
+
+/** The catalog with only the first sentence of each description. */
+function shortCatalog(listed: Array<SkillMetadata>, family: ModelFamily) {
+  return renderCatalog(
+    listed.map((skill) => ({
+      ...skill,
+      description: firstSentence(skill.description),
+    })),
+    family,
+  )
+}
+
+/** The text of the turn that `/<name> [task]` starts. */
+function skillPrompt(name: string, input: unknown) {
+  const task = typeof input === 'string' ? input.trim() : ''
+  return task === ''
+    ? `Use the ${name} skill.`
+    : `Use the ${name} skill: ${task}`
+}
+
+/**
+ * A harness plugin that gives the model the skills of `dirs`, and makes each
+ * skill a command: `/<name> [task]` starts a turn that tells the model to use
+ * the skill. A skill whose name another command has is `/skill:<name>`.
+ * `/skills` lists every skill, its folder, and its command.
+ *
+ * The plugin watches the folders, and it lists them again at the start of
+ * each turn. A skill that you add, change, or remove while the session runs
+ * changes the commands at once, with no restart.
+ *
+ * The model's skill list has one line for each skill: its name and the first
+ * sentence of its description. When the list is longer than
+ * `maxCatalogTokens`, the skills of the earlier folders stay in it, and a
+ * skill that you called with its command always stays.
+ *
+ * @param options.dirs - The skill folders, the first one wins on a name.
+ * @param options.reserved - Command names a UI handles itself.
+ *
+ * @example
+ * ```ts
+ * import { homedir } from 'node:os'
+ * import { join } from 'node:path'
+ * import { skills } from '@tanstack/ai-skills/harness'
+ *
+ * defineHarness({
+ *   name: 'acme/agent',
+ *   adapter,
+ *   plugins: () => [
+ *     skills({ dirs: ['./.agents/skills', join(homedir(), '.acme', 'skills')] }),
+ *   ],
+ * })
+ * ```
+ */
+export function skills(options: SkillsPluginOptions) {
+  const { dirs, reserved = [], ...skillsOptions } = options
+  // `skills` is this plugin's own command, so a skill named `skills` gets
+  // the prefix too.
+  const taken = new Set(['skills', ...reserved])
+
+  return definePlugin({
+    name: 'tanstack/skills',
+    setup: async (ctx) => {
+      // The skill commands of this plugin: command name to skill name and
+      // the description the command has.
+      const mine = new Map<string, { name: string; description: string }>()
+      // Skills called with their command stay in the model's list.
+      const called = new Set<string>()
+      let found = new Map<string, FoundSkill>()
+      const watchers = await ctx.resources.acquire(
+        () => new Map<string, FSWatcher>(),
+        (open) => {
+          for (const watcher of open.values()) watcher.close()
+          open.clear()
+        },
+      )
+      const closed = () => ctx.resources.signal.aborted
+
+      const skillCommand = (name: string, description: string) =>
+        defineCommand({
+          description: `Skill: ${firstSentence(description)}`,
+          input: {
+            type: 'string',
+            description: 'What the skill should do. Optional.',
+          },
+          run: (input: unknown) => {
+            called.add(name)
+            void ctx.session.prompt(skillPrompt(name, input))
+          },
+        })
+
+      /** Watch `path` under `key`. `false` when `path` does not exist. */
+      const tryWatch = (key: string, path: string, recursive: boolean) => {
+        try {
+          const watcher = watch(path, { recursive, persistent: false }, soon)
+          watcher.on('error', () => {
+            watcher.close()
+            watchers.delete(key)
+          })
+          watchers.set(key, watcher)
+          return true
+        } catch {
+          return false
+        }
+      }
+
+      /**
+       * Watch each skill folder. While a folder does not exist, watch its
+       * parent folder, so the skills show as soon as you make the folder.
+       */
+      const watchFolders = () => {
+        for (const dir of dirs) {
+          if (watchers.has(dir)) continue
+          const parentKey = `${dir} (parent)`
+          if (tryWatch(dir, dir, true)) {
+            watchers.get(parentKey)?.close()
+            watchers.delete(parentKey)
+          } else if (!watchers.has(parentKey)) {
+            tryWatch(parentKey, dirname(dir), false)
+          }
+        }
+      }
+
+      /** Make the commands match the skills in the folders now. */
+      const update = async () => {
+        if (closed()) return
+        found = await scan(dirs)
+        if (closed()) return
+        watchFolders()
+        const next = new Map<string, { name: string; description: string }>()
+        for (const { skill } of found.values()) {
+          const isFree =
+            !taken.has(skill.name) &&
+            (mine.has(skill.name) || !ctx.commands.has(skill.name))
+          next.set(isFree ? skill.name : `skill:${skill.name}`, {
+            name: skill.name,
+            description: skill.description,
+          })
+        }
+        for (const [command, entry] of mine) {
+          if (next.get(command)?.name === entry.name) continue
+          ctx.commands.delete(command)
+          mine.delete(command)
+        }
+        for (const [command, entry] of next) {
+          const isSame = mine.get(command)?.description === entry.description
+          if (isSame) continue
+          try {
+            ctx.commands.set(
+              command,
+              skillCommand(entry.name, entry.description),
+            )
+            mine.set(command, entry)
+          } catch {
+            // Another plugin took `skill:<name>` too. The skill stays in the
+            // model's list, with no command.
+          }
+        }
+      }
+      // Updates run one after the other.
+      let updating = Promise.resolve()
+      const sync = () => {
+        updating = updating.then(update).catch(() => {})
+        return updating
+      }
+
+      // A save often fires several watch events: wait until they stop.
+      let timer: ReturnType<typeof setTimeout> | undefined
+      function soon() {
+        clearTimeout(timer)
+        timer = setTimeout(() => void sync(), 200)
+        timer.unref?.()
+      }
+      ctx.resources.signal.addEventListener('abort', () => clearTimeout(timer))
+
+      // Commands of the plugins after this one exist only once all are set
+      // up, so the first sync waits for that.
+      void ctx.commands.ready.then(sync)
+
+      const source: SkillSource = {
+        list: async () =>
+          [...(await scan(dirs)).values()].map((entry) => entry.skill),
+        load: async (name) => (await folderOf(name)).load(name),
+        listResources: async (name) =>
+          (await (await folderOf(name)).listResources?.(name)) ?? [],
+        listScripts: async (name) =>
+          (await (await folderOf(name)).listScripts?.(name)) ?? [],
+        readResource: async (name, path) => {
+          const folder = await folderOf(name)
+          if (!folder.readResource) {
+            throw new Error(`Skill "${name}" has no resource files.`)
+          }
+          return folder.readResource(name, path)
+        },
+      }
+      /** The source of the folder that has the skill `name` now. */
+      async function folderOf(name: string) {
+        const entry = (await scan(dirs)).get(name)
+        if (!entry)
+          throw new Error(`No skill named "${name}" in ${dirs.join(', ')}.`)
+        return skillDirectory(entry.dir, { strict: false })
+      }
+
+      /**
+       * Over the token cap: the called skills first, then the folder order,
+       * until the list is full. The XML list of Anthropic models is the
+       * longest form, so the count uses it.
+       */
+      const keepEarlier = (listed: Array<SkillMetadata>, limit: number) => {
+        const ordered = [
+          ...listed.filter((skill) => called.has(skill.name)),
+          ...listed.filter((skill) => !called.has(skill.name)),
+        ]
+        const kept: Array<SkillMetadata> = []
+        for (const skill of ordered) {
+          const tooLong =
+            estimateTokens(shortCatalog([...kept, skill], 'anthropic')) > limit
+          if (tooLong) break
+          kept.push(skill)
+        }
+        return kept
+      }
+
+      const hasOwnCatalog =
+        skillsOptions.renderCatalog !== undefined ||
+        skillsOptions.instructionTemplate !== undefined
+      // The sync runs first, so the commands match the folders at the start
+      // of each turn.
+      const middleware: Array<AnyChatMiddleware> = [
+        { name: 'tanstack/skills:sync', setup: () => sync() },
+        withSkills(source, {
+          ...(hasOwnCatalog ? {} : { renderCatalog: shortCatalog }),
+          onLimitExceeded: keepEarlier,
+          ...skillsOptions,
+        }),
+      ]
+
+      return {
+        middleware,
+        commands: {
+          skills: defineCommand({
+            description: 'List the skills, their folders, and their commands',
+            run: async () => {
+              await sync()
+              if (found.size === 0) {
+                return `No skills yet. Add a folder with a SKILL.md to one of: ${dirs.join(', ')}`
+              }
+              const commandOf = new Map(
+                [...mine].map(([command, entry]) => [entry.name, command]),
+              )
+              const lines = [...found.values()].map(({ skill, dir }) => {
+                const command = commandOf.get(skill.name)
+                const name = command ? `/${command}` : skill.name
+                const note =
+                  command && command !== skill.name
+                    ? ` (/${skill.name} is taken)`
+                    : ''
+                return `${name}  ${dir}${note}`
+              })
+              return lines.join('\n')
+            },
+          }),
+        },
+      }
+    },
+  })
+}
diff --git a/packages/ai-skills/src/middleware.ts b/packages/ai-skills/src/middleware.ts
index 7a290c51e6..67e682d1ae 100644
--- a/packages/ai-skills/src/middleware.ts
+++ b/packages/ai-skills/src/middleware.ts
@@ -59,7 +59,7 @@ interface SkillsRuntime {
 const SkillsCapability = createCapability<SkillsRuntime>()('skills')
 
 /** ~4 chars/token — good enough to guard a runaway catalog. */
-const estimateTokens = (s: string) => Math.ceil(s.length / 4)
+export const estimateTokens = (s: string) => Math.ceil(s.length / 4)
 
 function fillTemplate(template: string, catalog: string): string {
   // Escape `{{`/`}}` to sentinels, substitute `{skills}`, then restore braces.
diff --git a/packages/ai-skills/tests/harness.test.ts b/packages/ai-skills/tests/harness.test.ts
new file mode 100644
index 0000000000..6c69582f48
--- /dev/null
+++ b/packages/ai-skills/tests/harness.test.ts
@@ -0,0 +1,237 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { fakeText } from '@tanstack/ai/testing'
+import {
+  createHarnessHost,
+  defineCommand,
+  defineHarness,
+  definePlugin,
+} from '@tanstack/ai-harness'
+import { skills } from '../src/harness'
+import type { TextOptions } from '@tanstack/ai'
+import type { HarnessHost, HarnessPlugin } from '@tanstack/ai-harness'
+import type { SkillsPluginOptions } from '../src/harness'
+
+const temps: Array<string> = []
+const hosts: Array<HarnessHost> = []
+afterEach(async () => {
+  await Promise.all(hosts.splice(0).map((host) => host.close()))
+  await Promise.all(
+    temps.splice(0).map((dir) => rm(dir, { recursive: true, force: true })),
+  )
+})
+
+async function tempDir() {
+  const dir = await mkdtemp(join(tmpdir(), 'skills-harness-'))
+  temps.push(dir)
+  return dir
+}
+
+/** Write the skill `name` into `root`, with a two-sentence description. */
+async function addSkill(root: string, name: string, about = name) {
+  await mkdir(join(root, name), { recursive: true })
+  await writeFile(
+    join(root, name, 'SKILL.md'),
+    `---\nname: ${name}\ndescription: Helps with ${about}. Second sentence here.\n---\n\nDo ${about}.\n`,
+  )
+}
+
+/**
+ * A session with the skills plugin and `others` after it. The model answers
+ * "ok" and keeps each request.
+ */
+async function open(
+  options: SkillsPluginOptions,
+  others: Array<HarnessPlugin> = [],
+) {
+  const requests: Array<TextOptions> = []
+  const fake = fakeText()
+  fake.setResponses(
+    Array.from(
+      { length: 10 },
+      () =>
+        ({ request }: { request: TextOptions }) => {
+          requests.push(request)
+          return { text: 'ok' }
+        },
+    ),
+  )
+  const host = createHarnessHost()
+  hosts.push(host)
+  const session = await host.open(
+    defineHarness({
+      name: 'test/skills',
+      adapter: fake,
+      plugins: () => [skills(options), ...others],
+    }),
+    { threadId: 't' },
+  )
+  const names = () => session.commands().map((command) => command.name)
+  // `/skills` syncs the commands with the folders first, so a test needs
+  // no watch event.
+  const list = async () => String(await session.command('skills'))
+  return { session, names, list, requests }
+}
+
+/** The system prompt text of a model request. */
+const promptOf = (request: TextOptions | undefined) =>
+  JSON.stringify(request?.systemPrompts ?? [])
+
+describe('skills()', () => {
+  it('makes a command for each skill, from the first folder that has it', async () => {
+    const first = await tempDir()
+    const second = await tempDir()
+    await addSkill(first, 'alpha')
+    await addSkill(first, 'shared', 'the first folder')
+    await addSkill(second, 'beta')
+    await addSkill(second, 'shared', 'the second folder')
+    const { session, names, list } = await open({
+      dirs: [first, join(first, 'missing'), second],
+    })
+
+    const listed = await list()
+    expect(names()).toEqual(
+      expect.arrayContaining(['skills', 'alpha', 'beta', 'shared']),
+    )
+    expect(
+      session.commands().find((command) => command.name === 'shared')
+        ?.description,
+    ).toBe('Skill: Helps with the first folder.')
+    expect(listed).toContain(`/shared  ${first}`)
+    expect(listed).toContain(`/beta  ${second}`)
+  })
+
+  it('prefixes a skill whose name another command has', async () => {
+    const dir = await tempDir()
+    await addSkill(dir, 'model')
+    await addSkill(dir, 'help')
+    await addSkill(dir, 'alpha')
+    const picker = definePlugin({
+      name: 'test/picker',
+      setup: () => ({
+        commands: {
+          model: defineCommand({ description: 'Pick', run: () => 'picked' }),
+        },
+      }),
+    })
+    const { session, names, list } = await open(
+      { dirs: [dir], reserved: ['help'] },
+      [picker],
+    )
+
+    const listed = await list()
+    expect(names()).toEqual(
+      expect.arrayContaining(['skill:model', 'skill:help', 'alpha']),
+    )
+    expect(names()).not.toContain('help')
+    expect(await session.command('model')).toBe('picked')
+    expect(listed).toContain(`/skill:model  ${dir} (/model is taken)`)
+  })
+
+  it('starts a turn that asks for the skill, with or without a task', async () => {
+    const dir = await tempDir()
+    await addSkill(dir, 'alpha')
+    const { session, list, requests } = await open({ dirs: [dir] })
+    await list()
+
+    await session.command('alpha', 'make a banner')
+    await vi.waitFor(() => expect(requests).toHaveLength(1))
+    expect(JSON.stringify(requests[0]?.messages)).toContain(
+      'Use the alpha skill: make a banner',
+    )
+    expect(promptOf(requests[0])).toContain('Helps with alpha.')
+    expect(promptOf(requests[0])).not.toContain('Second sentence here.')
+
+    await session.command('alpha')
+    await vi.waitFor(() => expect(requests).toHaveLength(2))
+    expect(JSON.stringify(requests[1]?.messages)).toContain(
+      'Use the alpha skill.',
+    )
+  })
+
+  it('follows skills that come and go while the session runs', async () => {
+    const dir = await tempDir()
+    await addSkill(dir, 'alpha')
+    const { names } = await open({ dirs: [dir] })
+    await vi.waitFor(() => expect(names()).toContain('alpha'))
+
+    await addSkill(dir, 'gamma')
+    await vi.waitFor(() => expect(names()).toContain('gamma'), {
+      timeout: 5000,
+    })
+    await rm(join(dir, 'alpha'), { recursive: true, force: true })
+    await vi.waitFor(() => expect(names()).not.toContain('alpha'), {
+      timeout: 5000,
+    })
+  })
+
+  it('shows the skills of a folder made after the start', async () => {
+    const root = await tempDir()
+    const { names } = await open({ dirs: [join(root, 'later')] })
+
+    await addSkill(join(root, 'later'), 'alpha')
+    await vi.waitFor(() => expect(names()).toContain('alpha'), {
+      timeout: 5000,
+    })
+  })
+
+  it('uses a folder made after the start, from the next turn', async () => {
+    const root = await tempDir()
+    const later = join(root, 'later')
+    const { session, names } = await open({ dirs: [later] })
+    expect(names()).not.toContain('alpha')
+
+    await addSkill(later, 'alpha')
+    await session.prompt('hi')
+    expect(names()).toContain('alpha')
+  })
+
+  it('leaves out a broken SKILL.md until it is fixed', async () => {
+    const dir = await tempDir()
+    await mkdir(join(dir, 'alpha'))
+    await writeFile(join(dir, 'alpha', 'SKILL.md'), '---\nname: alpha\n')
+    const { names, list } = await open({ dirs: [dir] })
+
+    expect(await list()).toContain('No skills yet.')
+    expect(names()).not.toContain('alpha')
+    await addSkill(dir, 'alpha')
+    await list()
+    expect(names()).toContain('alpha')
+  })
+
+  it('keeps the earlier folders, and the called skills, when the list is too long', async () => {
+    const first = await tempDir()
+    const second = await tempDir()
+    // With this description, one skill fits in 36 tokens and two do not.
+    const about = 'a topic with a long and wordy name for the test'
+    await addSkill(first, 'alpha', about)
+    await addSkill(second, 'zeta', about)
+    const { session, list, requests } = await open({
+      dirs: [first, second],
+      maxCatalogTokens: 36,
+    })
+    await list()
+
+    await session.prompt('hi')
+    expect(promptOf(requests[0])).toContain('alpha')
+    expect(promptOf(requests[0])).not.toContain('zeta')
+
+    await session.command('zeta')
+    await vi.waitFor(() => expect(requests).toHaveLength(2))
+    expect(promptOf(requests[1])).toContain('zeta')
+  })
+
+  it('stops following the folders when the session closes', async () => {
+    const dir = await tempDir()
+    await addSkill(dir, 'alpha')
+    const opened = await open({ dirs: [dir] })
+    await opened.list()
+    await Promise.all(hosts.splice(0).map((host) => host.close()))
+
+    await addSkill(dir, 'gamma')
+    await new Promise((resolve) => setTimeout(resolve, 500))
+    expect(opened.names()).not.toContain('gamma')
+  })
+})
diff --git a/packages/ai-skills/vite.config.ts b/packages/ai-skills/vite.config.ts
index c02dcd7697..836a48d7b4 100644
--- a/packages/ai-skills/vite.config.ts
+++ b/packages/ai-skills/vite.config.ts
@@ -31,6 +31,7 @@ export default mergeConfig(
   tanstackViteConfig({
     entry: [
       './src/index.ts',
+      './src/harness.ts',
       './src/node/index.ts',
       './src/static/index.ts',
       './src/testing/index.ts',
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8c6c082737..f0e8e9e116 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -233,6 +233,9 @@ importers:
       '@tanstack/ai-sandbox-local-process':
         specifier: workspace:*
         version: link:../../packages/ai-sandbox-local-process
+      '@tanstack/ai-skills':
+        specifier: workspace:*
+        version: link:../../packages/ai-skills
       '@tanstack/react-store':
         specifier: ^0.11.1
         version: 0.11.1(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
@@ -3431,6 +3434,9 @@ importers:
         specifier: workspace:^
         version: link:../ai
     devDependencies:
+      '@tanstack/ai-harness':
+        specifier: workspace:*
+        version: link:../ai-harness
       '@vitest/coverage-v8':
         specifier: 4.1.10
         version: 4.1.10(vitest@4.1.10)

From a47f4f9690a988e6c4be34e22ebef47ac23095c4 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 14:08:34 +0200
Subject: [PATCH 120/286] refactor(ai-harness): one log writer per log, with
 one fold per session

A shared log keeps a fold for each session (the record field thread) and a
reduce fold for the whole log. A session gets a view of it. The records of
the log's own session have no thread field, so a log with one session is
the same as before. Fold checkpoints move to format 2, keyed by log id.
---
 packages/ai-harness/src/host.ts               |  57 +-
 packages/ai-harness/src/log.ts                | 489 +++++++++++++-----
 packages/ai-harness/src/session.ts            |  50 +-
 .../ai-harness/tests/durable-session.test.ts  |  28 +-
 packages/ai-harness/tests/log.test.ts         | 189 +++++--
 5 files changed, 599 insertions(+), 214 deletions(-)

diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
index f8fb449cae..6cbbc3af9a 100644
--- a/packages/ai-harness/src/host.ts
+++ b/packages/ai-harness/src/host.ts
@@ -1,4 +1,5 @@
 import { memoryPersistence } from '@tanstack/ai-persistence'
+import { SharedLog, loadLogState } from './log'
 import { HarnessSession } from './session'
 import type { RunStore } from '@tanstack/ai'
 import type {
@@ -150,13 +151,38 @@ export function createHarnessHost(
         persistence.stores.generationRuns ?? memory.generationRuns,
     },
   }
-  const log = persistence.stores.log
-    ? {
-        store: persistence.stores.log,
-        coalesceMs: options.coalesceMs ?? 100,
-        ...(options.project ? { project: options.project } : {}),
-      }
-    : undefined
+  const logStore = persistence.stores.log
+  const { metadata } = persistence.stores
+  const coalesceMs = options.coalesceMs ?? 100
+  /** The shared log of each log id with an open session, by log id. */
+  const logs = new Map<string, Promise<SharedLog>>()
+  const sharedLog = (store: LogStore, logId: string) => {
+    const open = logs.get(logId)
+    if (open) return open
+    const loaded = loadLogState({
+      store,
+      logId,
+      ...(metadata ? { metadata } : {}),
+      ...(options.project ? { project: options.project } : {}),
+    }).then(
+      (state) =>
+        new SharedLog({
+          store,
+          logId,
+          state,
+          coalesceMs,
+          ...(options.project ? { project: options.project } : {}),
+          ...(metadata ? { metadata } : {}),
+          // The next open folds the log again.
+          onIdle: () => {
+            if (logs.get(logId) === loaded) logs.delete(logId)
+          },
+        }),
+    )
+    loaded.catch(() => logs.delete(logId))
+    logs.set(logId, loaded)
+    return loaded
+  }
   const sessions = new Map<string, Promise<HarnessSession>>()
   const hostId = `host-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`
 
@@ -165,15 +191,30 @@ export function createHarnessHost(
       const key = `${harness.name}\u0000${threadId}`
       let session = sessions.get(key)
       if (!session) {
+        // ponytail: each thread is its own log until `open` takes a `logId`.
+        const logId = threadId
         const created = new HarnessSession({
           harness,
           threadId,
+          logId,
           persistence,
           inbox,
           credentials,
           media,
           hostId,
-          ...(log ? { log } : {}),
+          ...(logStore
+            ? {
+                log: {
+                  store: logStore,
+                  ...(options.project ? { project: options.project } : {}),
+                  open: async (sessionThread, onFailure) =>
+                    (await sharedLog(logStore, logId)).view(
+                      sessionThread,
+                      onFailure,
+                    ),
+                },
+              }
+            : {}),
           ...(options.lease ? { lease: options.lease } : {}),
           ...(principal ? { principal } : {}),
           onClose: () => sessions.delete(key),
diff --git a/packages/ai-harness/src/log.ts b/packages/ai-harness/src/log.ts
index 832704e1eb..715f33a4c1 100644
--- a/packages/ai-harness/src/log.ts
+++ b/packages/ai-harness/src/log.ts
@@ -274,6 +274,78 @@ export function foldEntry(
   }
 }
 
+/** A fold of every host record of a log, across its sessions, in log order. */
+export interface ReduceOptions<TState> {
+  /** The state of an empty log. JSON. */
+  initial: TState
+  /** Pure. Return the next state, or the same state for no change. */
+  record: (args: { state: TState; record: LogRecord }) => TState
+  /** A fold checkpoint with another version is ignored. */
+  version?: string
+}
+
+/** The fold of a whole log: one state per session, and the reduce state. */
+export interface SharedLogState<TState = unknown> {
+  /** The position of the last folded record. */
+  seq: number
+  /** By thread id. */
+  sessions: Map<string, LogState>
+  reduced: TState | undefined
+}
+
+export function emptySharedLogState<TState = unknown>(
+  reduce?: ReduceOptions<TState>,
+) {
+  const state: SharedLogState<TState> = {
+    seq: 0,
+    sessions: new Map(),
+    reduced: reduce ? normalize(reduce.initial) : undefined,
+  }
+  return state
+}
+
+/** The fold of session `thread`. A session with no records yet gets an empty one. */
+export function sessionOf(state: SharedLogState<unknown>, thread: string) {
+  let session = state.sessions.get(thread)
+  if (!session) {
+    session = emptyLogState()
+    state.sessions.set(thread, session)
+  }
+  return session
+}
+
+/** The session of a record: its `thread`, or the session whose thread id is the log id. */
+export const threadOf = (record: LogRecord, logId: string) =>
+  typeof record.thread === 'string' ? record.thread : logId
+
+interface FoldOptions<TState> {
+  logId: string
+  project?: ProjectRecord
+  reduce?: ReduceOptions<TState>
+}
+
+/** Fold one entry of a shared log. */
+export function foldLogEntry<TState>(
+  state: SharedLogState<TState>,
+  entry: LogEntry,
+  options: FoldOptions<TState>,
+) {
+  state.seq = entry.seq
+  const { record } = entry
+  const { reduce } = options
+  if (reduce && !record.type.startsWith('harness.')) {
+    state.reduced = reduce.record({
+      state: state.reduced ?? reduce.initial,
+      record,
+    })
+  }
+  foldEntry(
+    sessionOf(state, threadOf(record, options.logId)),
+    entry,
+    options.project,
+  )
+}
+
 const CHECKPOINT_NAMESPACE = 'harness:log-checkpoint'
 // ponytail: a checkpoint every 50 appends. Tune it when a cold fold is slow.
 const CHECKPOINT_EVERY = 50
@@ -282,28 +354,33 @@ const READ_PAGE = 500
 // from the store.
 const MAX_TAIL = 10_000
 
-function serialize(state: LogState, version: string | undefined) {
+interface CheckpointVersions {
+  version?: string
+  reduceVersion?: string
+}
+
+function serialize(state: SharedLogState, versions: CheckpointVersions) {
   return {
-    v: 1,
+    v: 2,
     seq: state.seq,
-    ...(version !== undefined ? { version } : {}),
-    state: {
-      messages: state.messages,
-      inputs: [...state.inputs.values()],
-      toolResults: [...state.toolResults.entries()],
-      steps: [...state.steps.entries()],
-    },
+    ...versions,
+    sessions: [...state.sessions].map(([thread, session]) => [
+      thread,
+      {
+        messages: session.messages,
+        inputs: [...session.inputs.values()],
+        toolResults: [...session.toolResults.entries()],
+        steps: [...session.steps.entries()],
+      },
+    ]),
+    reduced: state.reduced ?? null,
   }
 }
 
-/** A checkpoint that the harness wrote with `version`, or `undefined`. */
-function parseCheckpoint(value: unknown, version: string | undefined) {
-  if (!isRecord(value) || value.v !== 1) return undefined
-  if (typeof value.seq !== 'number' || value.version !== version)
-    return undefined
-  const saved = value.state
-  if (!isRecord(saved)) return undefined
-  const { messages, inputs, toolResults, steps } = saved
+/** One session of a checkpoint at `seq`, or `undefined` when it is not shaped. */
+function parseSession(value: unknown, seq: number) {
+  if (!isRecord(value)) return undefined
+  const { messages, inputs, toolResults, steps } = value
   const isShaped =
     Array.isArray(messages) &&
     Array.isArray(inputs) &&
@@ -311,8 +388,8 @@ function parseCheckpoint(value: unknown, version: string | undefined) {
     Array.isArray(steps)
   if (!isShaped) return undefined
   // The harness wrote these arrays with `serialize`.
-  const state: LogState = {
-    seq: value.seq,
+  const session: LogState = {
+    seq,
     messages: (messages as Array<ModelMessage>).map(revive),
     inputs: new Map(
       (inputs as Array<InputState>).map((input) => [input.inputId, input]),
@@ -320,38 +397,81 @@ function parseCheckpoint(value: unknown, version: string | undefined) {
     toolResults: new Map(toolResults as Array<[string, ModelMessage]>),
     steps: new Map(steps as Array<[string, unknown]>),
   }
-  return state
+  return session
+}
+
+/** A checkpoint that the harness wrote with `versions`, or `undefined`. */
+function parseCheckpoint<TState>(
+  value: unknown,
+  versions: CheckpointVersions,
+): SharedLogState<TState> | undefined {
+  if (!isRecord(value) || value.v !== 2 || typeof value.seq !== 'number') {
+    return undefined
+  }
+  if (
+    value.version !== versions.version ||
+    value.reduceVersion !== versions.reduceVersion ||
+    !Array.isArray(value.sessions)
+  ) {
+    return undefined
+  }
+  const sessions = new Map<string, LogState>()
+  for (const item of value.sessions) {
+    if (!Array.isArray(item) || typeof item[0] !== 'string') return undefined
+    const session = parseSession(item[1], value.seq)
+    if (!session) return undefined
+    sessions.set(item[0], session)
+  }
+  return {
+    seq: value.seq,
+    sessions,
+    // The harness wrote this value with `serialize`, from `reduce`.
+    reduced: (value.reduced ?? undefined) as TState | undefined,
+  }
 }
 
+const versionsOf = (
+  project: ProjectOptions | undefined,
+  reduce: { version?: string } | undefined,
+): CheckpointVersions => ({
+  ...(project?.version !== undefined ? { version: project.version } : {}),
+  ...(reduce?.version !== undefined ? { reduceVersion: reduce.version } : {}),
+})
+
 /**
- * Fold the log of `threadId`. With `metadata`, start from the newest fold
- * checkpoint when it is valid for this log and this `project.version`.
+ * Fold the log `logId`. With `metadata`, start from the newest fold
+ * checkpoint when it is valid for this log and these versions.
  */
-export async function loadLogState(options: {
+export async function loadLogState<TState = unknown>(options: {
   store: LogStore
-  threadId: string
+  logId: string
   metadata?: MetadataStore
   project?: ProjectOptions
+  reduce?: ReduceOptions<TState>
 }) {
-  const { store, threadId, metadata, project } = options
+  const { store, logId, metadata, project, reduce } = options
   const saved = metadata
-    ? await metadata.get(CHECKPOINT_NAMESPACE, threadId).catch(() => null)
+    ? await metadata.get(CHECKPOINT_NAMESPACE, logId).catch(() => null)
     : null
-  let state = parseCheckpoint(saved, project?.version) ?? emptyLogState()
+  let state =
+    parseCheckpoint<TState>(saved, versionsOf(project, reduce)) ??
+    emptySharedLogState(reduce)
   if (state.seq > 0) {
     // A checkpoint past the end of the log belongs to another log.
-    const [atCheckpoint] = await store.read(threadId, {
+    const [atCheckpoint] = await store.read(logId, {
       after: state.seq - 1,
       limit: 1,
     })
-    if (!atCheckpoint) state = emptyLogState()
+    if (!atCheckpoint) state = emptySharedLogState(reduce)
+  }
+  const fold: FoldOptions<TState> = {
+    logId,
+    ...(project ? { project: project.record } : {}),
+    ...(reduce ? { reduce } : {}),
   }
   for (;;) {
-    const page = await store.read(threadId, {
-      after: state.seq,
-      limit: READ_PAGE,
-    })
-    for (const entry of page) foldEntry(state, entry, project?.record)
+    const page = await store.read(logId, { after: state.seq, limit: READ_PAGE })
+    for (const entry of page) foldLogEntry(state, entry, fold)
     if (page.length < READ_PAGE) return state
   }
 }
@@ -363,43 +483,66 @@ const DELTA_TYPES = new Set<string>([
 ])
 
 /** The fields of a delta event that must match for a merge. */
-function deltaKey(operationId: string, event: StreamChunk) {
+function deltaKey(thread: string, operationId: string, event: StreamChunk) {
   if (!DELTA_TYPES.has(event.type) || !('delta' in event)) return undefined
   const { delta: _delta, timestamp: _timestamp, ...rest } = event
-  return JSON.stringify([operationId, rest])
+  return JSON.stringify([thread, operationId, rest])
+}
+
+/** A session's view of its log. It is also the session's {@link EventFeed}. */
+export interface LogWriter extends EventFeed {
+  readonly threadId: string
+  readonly logId: string
+  /** The fold of this session. */
+  readonly state: LogState
+  /** Append `records` after the pending events, in one batch. */
+  append: (records: ReadonlyArray<LogRecord>) => Promise<void>
+  /** Hold `records` until the next transcript commit of this session. */
+  stage: (records: ReadonlyArray<LogRecord>) => void
+  /**
+   * One batch: the pending events, the transcript change to `messages` (if
+   * any), the staged records of this session, then `records`.
+   */
+  commit: (options: {
+    messages: ReadonlyArray<ModelMessage>
+    records?: ReadonlyArray<LogRecord>
+  }) => Promise<void>
+  /** Append the pending events now. */
+  flush: () => Promise<void>
 }
 
 /**
- * Writes a session log and keeps its fold. It is also the session's
- * {@link EventFeed}: every reader reads the log.
- *
+ * Writes one log for every session that shares it, and keeps its fold.
  * All writes run one after another. Each batch goes at the next position.
  * When a write fails (another writer took the position, or the store failed
- * twice), the writer calls `onFailure`, and every later write rejects.
+ * twice), every session of the log gets `onFailure`, and every later write
+ * rejects.
  */
-export class LogWriter implements EventFeed {
-  readonly threadId: string
-  readonly state: LogState
+export class SharedLog<TState = unknown> {
+  readonly logId: string
+  readonly state: SharedLogState<TState>
   private readonly store: LogStore
-  private readonly project: ProjectOptions | undefined
+  private readonly fold: FoldOptions<TState>
+  private readonly versions: CheckpointVersions
   private readonly metadata: MetadataStore | undefined
   private readonly coalesceMs: number
-  private readonly onFailure: (error: unknown) => void
+  private readonly onIdle: () => void
+  private readonly failureListeners = new Set<(error: unknown) => void>()
   /** Events and host records that wait for the next append. */
   private readonly pending: Array<LogRecord> = []
   /** The merge key of the last pending record, when it is a delta event. */
   private pendingKey: string | undefined
-  /** Host records that wait for the next transcript commit. */
-  private readonly staged: Array<LogRecord> = []
+  /** Host records that wait for the next transcript commit, by thread. */
+  private readonly staged = new Map<string, Array<LogRecord>>()
   private timer: ReturnType<typeof setTimeout> | undefined
   private scheduled = false
   private chain: Promise<void> = Promise.resolve()
   private failure: unknown
-  private readonly tail: Array<SessionEvent> = []
+  private readonly tail: Array<{ thread: string; entry: SessionEvent }> = []
   /** Every event after this position is in `tail`. */
   private tailFrom: number
   private readonly waiters = new Set<() => void>()
-  private closed = false
+  private views = 0
   private writing = false
   private hasWritten = false
   private writesSinceCheckpoint = 0
@@ -407,39 +550,92 @@ export class LogWriter implements EventFeed {
 
   constructor(options: {
     store: LogStore
-    threadId: string
-    state: LogState
+    logId: string
+    state: SharedLogState<TState>
+    coalesceMs: number
     project?: ProjectOptions
+    reduce?: ReduceOptions<TState>
     metadata?: MetadataStore
-    coalesceMs: number
-    onFailure: (error: unknown) => void
+    /** Called when the last session closes, or when a write fails. */
+    onIdle?: () => void
   }) {
     this.store = options.store
-    this.threadId = options.threadId
+    this.logId = options.logId
     this.state = options.state
-    this.project = options.project
     this.metadata = options.metadata
     this.coalesceMs = options.coalesceMs
-    this.onFailure = options.onFailure
+    this.onIdle = options.onIdle ?? (() => {})
+    this.fold = {
+      logId: options.logId,
+      ...(options.project ? { project: options.project.record } : {}),
+      ...(options.reduce ? { reduce: options.reduce } : {}),
+    }
+    this.versions = versionsOf(options.project, options.reduce)
     this.tailFrom = options.state.seq
     // Records from another writer (this host only reads) join the fold. A
     // call during this writer's own append is its own records.
-    this.unsubscribe = options.store.subscribe(options.threadId, () => {
+    this.unsubscribe = options.store.subscribe(options.logId, () => {
       if (!this.writing) void this.enqueue(() => this.catchUp())
     })
   }
 
+  /** The view of session `threadId`. Close it when the session closes. */
+  view(threadId: string, onFailure: (error: unknown) => void): LogWriter {
+    this.views += 1
+    // Its own function, so two views with the same `onFailure` both count.
+    const listener = (error: unknown) => onFailure(error)
+    this.failureListeners.add(listener)
+    const shared = this.state
+    let closed = false
+    return {
+      threadId,
+      logId: this.logId,
+      get state() {
+        return sessionOf(shared, threadId)
+      },
+      publish: (operationId, event) =>
+        this.publish(threadId, operationId, event),
+      append: (records) => this.append(threadId, records),
+      stage: (records) => this.stage(threadId, records),
+      commit: (options) => this.commit(threadId, options),
+      flush: () => this.flush(),
+      head: () => this.head(),
+      read: (options) =>
+        this.read(threadId, { ...options, isClosed: () => closed }),
+      close: () => {
+        if (closed) return
+        closed = true
+        this.release(listener)
+      },
+    }
+  }
+
+  private release(listener: (error: unknown) => void) {
+    this.failureListeners.delete(listener)
+    this.views -= 1
+    void this.flush().catch(() => {})
+    // The readers of the closed view end. The others wait again.
+    this.wake()
+    if (this.views > 0) return
+    this.unsubscribe()
+    this.onIdle()
+  }
+
+  /** Stamp a record with its session, unless it names one or the session is the log's own. */
+  private stamp(record: LogRecord, thread: string): LogRecord {
+    if (typeof record.thread === 'string' || thread === this.logId) {
+      return record
+    }
+    return { ...record, thread }
+  }
+
   // ===========================
   // Writes
   // ===========================
 
-  publish(operationId: string, event: StreamChunk): void {
-    const record: HarnessRecord = {
-      type: 'harness.event',
-      operationId,
-      event: normalize(event),
-    }
-    const key = deltaKey(operationId, record.event)
+  private publish(thread: string, operationId: string, event: StreamChunk) {
+    const normalized = normalize(event)
+    const key = deltaKey(thread, operationId, normalized)
     const last = this.pending.at(-1)
     const isSameDelta =
       key !== undefined &&
@@ -447,8 +643,15 @@ export class LogWriter implements EventFeed {
       last !== undefined &&
       isHarnessRecord(last) &&
       last.type === 'harness.event'
-    if (isSameDelta) last.event = mergeDelta(last.event, record.event)
-    else this.pending.push(record)
+    if (isSameDelta) last.event = mergeDelta(last.event, normalized)
+    else {
+      this.pending.push(
+        this.stamp(
+          { type: 'harness.event', operationId, event: normalized },
+          thread,
+        ),
+      )
+    }
     this.pendingKey = key
     if (key === undefined) {
       void this.flush().catch(() => {})
@@ -457,33 +660,41 @@ export class LogWriter implements EventFeed {
     this.schedule()
   }
 
-  /** Append `records` after the pending events, in one batch. */
-  append(records: ReadonlyArray<LogRecord>): Promise<void> {
-    this.pending.push(...records.map(normalize))
+  private append(thread: string, records: ReadonlyArray<LogRecord>) {
+    this.pending.push(
+      ...records.map((record) => normalize(this.stamp(record, thread))),
+    )
     this.pendingKey = undefined
     return this.flush()
   }
 
-  /** Hold `records` until the next transcript commit. */
-  stage(records: ReadonlyArray<LogRecord>): void {
-    this.staged.push(...records.map(normalize))
+  private stage(thread: string, records: ReadonlyArray<LogRecord>) {
+    const staged = this.staged.get(thread) ?? []
+    staged.push(
+      ...records.map((record) => normalize(this.stamp(record, thread))),
+    )
+    this.staged.set(thread, staged)
   }
 
-  /**
-   * One batch: the pending events, the transcript change to `messages` (if
-   * any), the staged records, then `records`.
-   */
-  commit(options: {
-    messages: ReadonlyArray<ModelMessage>
-    records?: ReadonlyArray<LogRecord>
-  }): Promise<void> {
+  private commit(
+    thread: string,
+    options: {
+      messages: ReadonlyArray<ModelMessage>
+      records?: ReadonlyArray<LogRecord>
+    },
+  ) {
     const events = this.takePending()
-    const staged = this.staged.splice(0)
-    const records = (options.records ?? []).map(normalize)
+    const staged = this.staged.get(thread)?.splice(0) ?? []
+    const records = (options.records ?? []).map((record) =>
+      normalize(this.stamp(record, thread)),
+    )
     return this.enqueue(() =>
       this.write([
         ...events,
-        ...transcriptRecord(this.state.messages, options.messages),
+        ...transcriptRecord(
+          sessionOf(this.state, thread).messages,
+          options.messages,
+        ).map((record) => this.stamp(record, thread)),
         ...staged,
         ...records,
       ]),
@@ -535,8 +746,7 @@ export class LogWriter implements EventFeed {
     try {
       await this.appendOnce(seq, batch)
     } catch (error) {
-      this.failure = error
-      this.onFailure(error)
+      this.fail(error)
       throw error
     } finally {
       this.writing = false
@@ -550,14 +760,21 @@ export class LogWriter implements EventFeed {
       void this.metadata
         ?.set(
           CHECKPOINT_NAMESPACE,
-          this.threadId,
-          normalize(serialize(this.state, this.project?.version)),
+          this.logId,
+          normalize(serialize(this.state, this.versions)),
         )
         .catch(() => {})
     }
     this.wake()
   }
 
+  /** Stop every session of the log. The host drops it, so the next open folds again. */
+  private fail(error: unknown) {
+    this.failure = error
+    for (const listener of [...this.failureListeners]) listener(error)
+    this.onIdle()
+  }
+
   /**
    * Append once. After an error, read back: the batch may have landed before
    * the error. When it did not land, a conflict fails at once, and another
@@ -565,14 +782,14 @@ export class LogWriter implements EventFeed {
    */
   private async appendOnce(seq: number, batch: ReadonlyArray<LogRecord>) {
     try {
-      await this.store.append(this.threadId, seq, batch)
+      await this.store.append(this.logId, seq, batch)
       return
     } catch (error) {
       if (await this.landed(seq, batch)) return
       if (error instanceof LogConflictError) throw error
     }
     try {
-      await this.store.append(this.threadId, seq, batch)
+      await this.store.append(this.logId, seq, batch)
     } catch (error) {
       if (await this.landed(seq, batch)) return
       throw error
@@ -581,7 +798,7 @@ export class LogWriter implements EventFeed {
 
   private async landed(seq: number, batch: ReadonlyArray<LogRecord>) {
     try {
-      const entries = await this.store.read(this.threadId, {
+      const entries = await this.store.read(this.logId, {
         after: seq - 1,
         limit: batch.length,
       })
@@ -601,13 +818,12 @@ export class LogWriter implements EventFeed {
    */
   private async catchUp() {
     if (this.failure !== undefined) return
-    const entries = await this.store.read(this.threadId, {
+    const entries = await this.store.read(this.logId, {
       after: this.state.seq,
     })
     const [first] = entries
     if (first && this.hasWritten) {
-      this.failure = new LogConflictError(this.threadId, first.seq)
-      this.onFailure(this.failure)
+      this.fail(new LogConflictError(this.logId, first.seq))
       return
     }
     for (const entry of entries) this.apply(entry)
@@ -615,17 +831,13 @@ export class LogWriter implements EventFeed {
   }
 
   private apply(entry: LogEntry) {
-    foldEntry(this.state, entry, this.project?.record)
-    const { record } = entry
-    if (!isHarnessRecord(record) || record.type !== 'harness.event') return
-    this.tail.push({
-      cursor: String(entry.seq),
-      operationId: record.operationId,
-      event: record.event,
-    })
+    foldLogEntry(this.state, entry, this.fold)
+    const event = sessionEventOf(entry)
+    if (!event) return
+    this.tail.push({ thread: threadOf(entry.record, this.logId), entry: event })
     if (this.tail.length > MAX_TAIL) {
       const dropped = this.tail.shift()
-      if (dropped) this.tailFrom = Number(dropped.cursor)
+      if (dropped) this.tailFrom = Number(dropped.entry.cursor)
     }
   }
 
@@ -637,14 +849,25 @@ export class LogWriter implements EventFeed {
     return String(this.state.seq)
   }
 
-  async *read(options: {
-    from?: Cursor
-    signal?: AbortSignal
-    filter?: (entry: SessionEvent) => boolean
-    until?: () => boolean
-  }): AsyncIterable<SessionEvent> {
-    const { signal, filter, until } = options
+  /** The events of session `thread`. A cursor is a position in the log. */
+  private async *read(
+    thread: string,
+    options: {
+      from?: Cursor
+      signal?: AbortSignal
+      filter?: (entry: SessionEvent) => boolean
+      until?: () => boolean
+      isClosed: () => boolean
+    },
+  ): AsyncIterable<SessionEvent> {
+    const { signal, filter, until, isClosed } = options
     const accepts = (entry: SessionEvent) => (filter ? filter(entry) : true)
+    /** The events of this session in the tail after `after`. */
+    const ownAfter = (after: number) =>
+      this.tail
+        .filter((item) => item.thread === thread)
+        .map((item) => item.entry)
+        .filter((entry) => Number(entry.cursor) > after && accepts(entry))
     let after = Number(options.from ?? '0')
     if (!Number.isFinite(after)) after = 0
     for (;;) {
@@ -652,7 +875,7 @@ export class LogWriter implements EventFeed {
       if (after < this.tailFrom) {
         // Older than the in-memory tail: page it from the store.
         const upTo = this.tailFrom
-        const page = await this.store.read(this.threadId, {
+        const page = await this.store.read(this.logId, {
           after,
           limit: READ_PAGE,
         })
@@ -660,25 +883,23 @@ export class LogWriter implements EventFeed {
           if (entry.seq > upTo || signal?.aborted) break
           after = entry.seq
           const event = sessionEventOf(entry)
-          if (event && accepts(event)) yield event
+          const isOwn = threadOf(entry.record, this.logId) === thread
+          if (event && isOwn && accepts(event)) yield event
         }
         if (page.length === 0) after = upTo
         continue
       }
-      const next = this.tail.filter(
-        (entry) => Number(entry.cursor) > after && accepts(entry),
-      )
+      const next = ownAfter(after)
       for (const entry of next) {
         if (signal?.aborted) return
         after = Number(entry.cursor)
         yield entry
       }
-      // Skip past records that are not events or that the filter rejected.
+      // Skip past records that are not this session's events, or that the
+      // filter rejected.
       if (next.length === 0) after = Math.max(after, this.state.seq)
-      if (this.closed || until?.()) {
-        for (const entry of this.tail) {
-          if (Number(entry.cursor) > after && accepts(entry)) yield entry
-        }
+      if (isClosed() || until?.()) {
+        yield* ownAfter(after)
         return
       }
       // A write while the reader handled `next` woke nobody: scan again.
@@ -687,13 +908,6 @@ export class LogWriter implements EventFeed {
     }
   }
 
-  close(): void {
-    void this.flush().catch(() => {})
-    this.closed = true
-    this.unsubscribe()
-    this.wake()
-  }
-
   private wake() {
     const waiters = [...this.waiters]
     this.waiters.clear()
@@ -864,21 +1078,36 @@ export function engineMessageStore(options: {
 export function logMessageStore(options: {
   store: LogStore
   project?: ProjectOptions
+  /** Read the threads of this log. Default: each thread is its own log. */
+  logId?: string
 }) {
   const { store, project } = options
+  const logOf = (threadId: string) => options.logId ?? threadId
   const load = (threadId: string) =>
-    loadLogState({ store, threadId, ...(project ? { project } : {}) })
+    loadLogState({
+      store,
+      logId: logOf(threadId),
+      ...(project ? { project } : {}),
+    })
   const messages: MessageStore = {
-    loadThread: async (threadId: string) => (await load(threadId)).messages,
+    loadThread: async (threadId: string) =>
+      sessionOf(await load(threadId), threadId).messages,
     saveThread: async (threadId, list) => {
       // ponytail: one retry after a conflict. The loser of a real race
       // reloads, so a second conflict is an error.
       for (let attempt = 1; ; attempt += 1) {
         const state = await load(threadId)
-        const records = transcriptRecord(state.messages, list)
+        const records = transcriptRecord(
+          sessionOf(state, threadId).messages,
+          list,
+        ).map((record) =>
+          logOf(threadId) === threadId
+            ? record
+            : { ...record, thread: threadId },
+        )
         if (records.length === 0) return
         try {
-          await store.append(threadId, state.seq + 1, records)
+          await store.append(logOf(threadId), state.seq + 1, records)
           return
         } catch (error) {
           if (!(error instanceof LogConflictError) || attempt === 2) throw error
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index a214ef6a8d..083abe71e6 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -17,13 +17,7 @@ import { AgentRegistry } from './agents'
 import { SessionFeed } from './feed'
 import { isRecord } from './utils'
 import { bindDurable, createToolStep } from './durable-tool'
-import {
-  LogWriter,
-  engineMessageStore,
-  loadLogState,
-  sessionMessageStore,
-  stepKey,
-} from './log'
+import { engineMessageStore, sessionMessageStore, stepKey } from './log'
 import { createMediaStore, mediaCapture, mediaMiddleware } from './media'
 import { mediaIdOf, mediaOfMessage } from './media-ref'
 import { OperationImpl } from './operation'
@@ -64,7 +58,7 @@ import type {
 } from '@tanstack/ai-persistence'
 import type { AuthRequiredError, CredentialsAccess } from './auth'
 import type { EventFeed } from './feed'
-import type { ProjectOptions } from './log'
+import type { LogWriter, ProjectOptions } from './log'
 import type { DurableBind } from './durable-tool'
 import type { LeaseOptions } from './resume'
 import type { MediaStore } from './media'
@@ -214,7 +208,17 @@ export interface SessionDependencies {
   /** Identifies this host on run leases. */
   hostId: string
   /** The session log of a durable host. */
-  log?: { store: LogStore; coalesceMs: number; project?: ProjectOptions }
+  log?: {
+    store: LogStore
+    project?: ProjectOptions
+    /** The view of this session in its shared log. */
+    open: (
+      threadId: string,
+      onFailure: (error: unknown) => void,
+    ) => Promise<LogWriter>
+  }
+  /** The log of the session. Default: the thread id. */
+  logId: string
   lease?: LeaseOptions
   onClose: () => void
 }
@@ -312,6 +316,8 @@ const notOpenMessages: MessageStore = {
  */
 export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   readonly threadId: string
+  /** The log of this session. Sessions with the same log id share one log. */
+  readonly logId: string
   readonly agents: AgentHandles<THarness>
   /** The agents this session can run, for discovery. */
   readonly registry: AgentRegistryView
@@ -399,6 +405,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   constructor(deps: SessionDependencies) {
     this.harness = deps.harness as THarness
     this.threadId = deps.threadId
+    this.logId = deps.logId
     this.persistence = deps.persistence
     this.inbox = deps.inbox
     this.media = deps.media
@@ -533,29 +540,18 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   }
 
   /**
-   * A durable host folds the thread's log and writes through it: the log is
-   * the event feed and the transcript. Then both modes build the stores that
+   * A durable host gives the session its view of the log, and the session
+   * writes through it: the log is the event feed and the transcript. Then
+   * both modes build the stores that
    * `withPersistence` and the checkpoints get.
    */
   private async openLog(): Promise<void> {
     const { stores } = this.persistence
     if (this.log) {
-      const { store, project, coalesceMs } = this.log
-      const state = await loadLogState({
-        store,
-        threadId: this.threadId,
-        ...(stores.metadata ? { metadata: stores.metadata } : {}),
-        ...(project ? { project } : {}),
-      })
-      this.writer = new LogWriter({
-        store,
-        threadId: this.threadId,
-        state,
-        coalesceMs,
-        ...(project ? { project } : {}),
-        ...(stores.metadata ? { metadata: stores.metadata } : {}),
-        onFailure: (error) => this.stopOnLogFailure(error),
-      })
+      const { store, project } = this.log
+      this.writer = await this.log.open(this.threadId, (error) =>
+        this.stopOnLogFailure(error),
+      )
       this.feed = this.writer
       const view = {
         writer: this.writer,
diff --git a/packages/ai-harness/tests/durable-session.test.ts b/packages/ai-harness/tests/durable-session.test.ts
index bc54f6232a..10d33d6fe3 100644
--- a/packages/ai-harness/tests/durable-session.test.ts
+++ b/packages/ai-harness/tests/durable-session.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { EventType, toolDefinition } from '@tanstack/ai'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness } from '../src'
-import { loadLogState } from '../src/log'
+import { loadLogState, sessionOf } from '../src/log'
 import { gate, messageTexts, mockAdapter, text, toolCall } from './helpers'
 import type { StreamChunk } from '@tanstack/ai'
 import type { LogStore } from '@tanstack/ai-persistence'
@@ -274,11 +274,14 @@ describe('durable session log', () => {
       'checked',
       '[signal] tests failed',
     ])
-    const rebuilt = await loadLogState({
-      store: persistence.stores.log,
-      threadId: THREAD,
-      project,
-    })
+    const rebuilt = sessionOf(
+      await loadLogState({
+        store: persistence.stores.log,
+        logId: THREAD,
+        project,
+      }),
+      THREAD,
+    )
     expect(await session.transcript()).toEqual(rebuilt.messages)
     expect(rebuilt.messages.map((message) => message.content).at(-1)).toBe(
       'second answer',
@@ -312,11 +315,14 @@ describe('durable session log', () => {
       'a2',
       'q3',
     ])
-    const rebuilt = await loadLogState({
-      store: persistence.stores.log,
-      threadId: THREAD,
-      project,
-    })
+    const rebuilt = sessionOf(
+      await loadLogState({
+        store: persistence.stores.log,
+        logId: THREAD,
+        project,
+      }),
+      THREAD,
+    )
     expect(rebuilt.messages.map((message) => message.content)).toEqual([
       'Earlier: q1 and a1.',
       'q2',
diff --git a/packages/ai-harness/tests/log.test.ts b/packages/ai-harness/tests/log.test.ts
index 7900248625..7494685cfd 100644
--- a/packages/ai-harness/tests/log.test.ts
+++ b/packages/ai-harness/tests/log.test.ts
@@ -6,12 +6,13 @@ import {
   memoryPersistence,
 } from '@tanstack/ai-persistence'
 import {
-  LogWriter,
-  emptyLogState,
+  SharedLog,
+  emptySharedLogState,
   engineMessageStore,
   loadLogState,
   logMessageStore,
   sessionMessageStore,
+  sessionOf,
 } from '../src/log'
 import type { ModelMessage, StreamChunk } from '@tanstack/ai'
 import type {
@@ -31,20 +32,25 @@ function newWriter(
     project?: ProjectOptions
     metadata?: MetadataStore
     onFailure?: (error: unknown) => void
-    state?: ReturnType<typeof emptyLogState>
+    state?: ReturnType<typeof emptySharedLogState>
   } = {},
 ) {
-  return new LogWriter({
+  const log = new SharedLog({
     store,
-    threadId: THREAD,
-    state: options.state ?? emptyLogState(),
+    logId: THREAD,
+    state: options.state ?? emptySharedLogState(),
     coalesceMs: options.coalesceMs ?? 0,
-    onFailure: options.onFailure ?? (() => {}),
     ...(options.project ? { project: options.project } : {}),
     ...(options.metadata ? { metadata: options.metadata } : {}),
   })
+  return log.view(THREAD, options.onFailure ?? (() => {}))
 }
 
+/** The fold of the session `THREAD`. */
+const loadSession = async (
+  options: Omit<Parameters<typeof loadLogState>[0], 'logId'>,
+) => sessionOf(await loadLogState({ ...options, logId: THREAD }), THREAD)
+
 /** A store that records the record types of each append batch. */
 function recordingStore(inner: LogStore = memoryLogStore()) {
   const batches: Array<Array<string>> = []
@@ -142,9 +148,7 @@ describe('transcript fold', () => {
       { type: 'harness.transcript', keep: 1, add: [] },
     ])
     expect(writer.state.messages).toEqual([u1])
-    expect((await loadLogState({ store, threadId: THREAD })).messages).toEqual([
-      u1,
-    ])
+    expect((await loadSession({ store })).messages).toEqual([u1])
   })
 
   it('folds host records through the projection, live and after a reload', async () => {
@@ -180,7 +184,7 @@ describe('transcript fold', () => {
       add: [a2],
     })
 
-    const reloaded = await loadLogState({ store, threadId: THREAD, project })
+    const reloaded = await loadSession({ store, project })
     expect(reloaded.messages).toEqual([...compacted, a2])
   })
 
@@ -205,9 +209,7 @@ describe('transcript fold', () => {
       { id: 'u1', role: 'user', content: 'hi', createdAt, metadata: {} },
     ]
     expect(writer.state.messages).toEqual(expected)
-    expect((await loadLogState({ store, threadId: THREAD })).messages).toEqual(
-      expected,
-    )
+    expect((await loadSession({ store })).messages).toEqual(expected)
   })
 })
 
@@ -278,7 +280,7 @@ describe('events and batches', () => {
     first.close()
 
     // A new session: the first events are only in the store.
-    const state = await loadLogState({ store, threadId: THREAD })
+    const state = await loadLogState({ store, logId: THREAD })
     const writer = newWriter(store, { state })
     let done = false
     const seen: Array<SessionEvent> = []
@@ -325,7 +327,7 @@ describe('write failures', () => {
     const failures: Array<unknown> = []
     const first = newWriter(store, { onFailure: (e) => failures.push(e) })
     await first.append([{ type: 'app.mine' }])
-    const state = await loadLogState({ store, threadId: THREAD })
+    const state = await loadLogState({ store, logId: THREAD })
     const next = newWriter(store, { state })
 
     // The newer host writes. The first host is notified and stops.
@@ -419,15 +421,21 @@ describe('fold checkpoints', () => {
   }
 
   const checkpoint = (overrides: Record<string, unknown>) => ({
-    v: 1,
+    v: 2,
     seq: 1,
     version: 'v1',
-    state: {
-      messages: [user('marker', 'from the checkpoint')],
-      inputs: [],
-      toolResults: [],
-      steps: [],
-    },
+    sessions: [
+      [
+        THREAD,
+        {
+          messages: [user('marker', 'from the checkpoint')],
+          inputs: [],
+          toolResults: [],
+          steps: [],
+        },
+      ],
+    ],
+    reduced: null,
     ...overrides,
   })
 
@@ -437,12 +445,7 @@ describe('fold checkpoints', () => {
     const { metadata } = memoryPersistence().stores
     await metadata.set(NAMESPACE, THREAD, checkpoint({}))
 
-    const state = await loadLogState({
-      store,
-      threadId: THREAD,
-      metadata,
-      project,
-    })
+    const state = await loadSession({ store, metadata, project })
 
     // Record 2 folds on top of the checkpoint (keep 1, add u2).
     expect(state.messages).toEqual([
@@ -453,22 +456,17 @@ describe('fold checkpoints', () => {
 
   it.each([
     ['not an object', 'garbage'],
-    ['another format', checkpoint({ v: 2 })],
+    ['another format', checkpoint({ v: 1 })],
     ['another projection version', checkpoint({ version: 'v0' })],
     ['a position past the end of the log', checkpoint({ seq: 99 })],
-    ['a state that is not shaped', checkpoint({ state: { messages: 'x' } })],
+    ['a state that is not shaped', checkpoint({ sessions: 'x' })],
   ])('ignores a checkpoint with %s', async (_name, value) => {
     const store = memoryLogStore()
     await seedLog(store)
     const { metadata } = memoryPersistence().stores
     await metadata.set(NAMESPACE, THREAD, value)
 
-    const state = await loadLogState({
-      store,
-      threadId: THREAD,
-      metadata,
-      project,
-    })
+    const state = await loadSession({ store, metadata, project })
 
     expect(state.messages).toEqual([user('u1', 'one'), user('u2', 'two')])
   })
@@ -484,7 +482,7 @@ describe('fold checkpoints', () => {
 
     await expect
       .poll(() => metadata.get(NAMESPACE, THREAD))
-      .toMatchObject({ v: 1, seq: 50, version: 'v1' })
+      .toMatchObject({ v: 2, seq: 50, version: 'v1' })
   })
 })
 
@@ -658,3 +656,118 @@ describe('message stores', () => {
     expect(child).toHaveLength(1)
   })
 })
+
+describe('a log shared by sessions', () => {
+  const sharedWriter = (store: LogStore) => {
+    const log = new SharedLog({
+      store,
+      logId: 'log-1',
+      state: emptySharedLogState(),
+      coalesceMs: 0,
+    })
+    return {
+      log,
+      root: log.view('log-1', () => {}),
+      child: log.view('child', () => {}),
+    }
+  }
+
+  it('writes no thread field for the log own session', async () => {
+    const store = memoryLogStore()
+    const { root } = sharedWriter(store)
+
+    await root.append([{ type: 'app.note', text: 'one' }])
+
+    expect((await store.read('log-1')).map((entry) => entry.record)).toEqual([
+      { type: 'app.note', text: 'one' },
+    ])
+  })
+
+  it('stamps the records of another session, and keeps a named thread', async () => {
+    const store = memoryLogStore()
+    const { root, child } = sharedWriter(store)
+
+    await child.append([{ type: 'app.note', text: 'from the child' }])
+    await root.append([
+      { type: 'app.child_created', thread: 'child' },
+      { type: 'app.child_linked', child: 'child' },
+    ])
+
+    expect((await store.read('log-1')).map((entry) => entry.record)).toEqual([
+      { type: 'app.note', text: 'from the child', thread: 'child' },
+      { type: 'app.child_created', thread: 'child' },
+      { type: 'app.child_linked', child: 'child' },
+    ])
+  })
+
+  it('folds each session on its own', async () => {
+    const store = memoryLogStore()
+    const { root, child } = sharedWriter(store)
+
+    await root.commit({ messages: [user('r1', 'root message')] })
+    await child.commit({ messages: [user('c1', 'child message')] })
+
+    expect(root.state.messages).toEqual([user('r1', 'root message')])
+    expect(child.state.messages).toEqual([user('c1', 'child message')])
+    const state = await loadLogState({ store, logId: 'log-1' })
+    expect(sessionOf(state, 'child').messages).toEqual([
+      user('c1', 'child message'),
+    ])
+  })
+
+  it('folds every host record of the log with reduce, in log order', async () => {
+    const store = memoryLogStore()
+    const reduce = {
+      initial: {} as Record<string, unknown>,
+      record: ({
+        state,
+        record,
+      }: {
+        state: Record<string, unknown>
+        record: LogRecord
+      }) =>
+        record.type === 'app.state_write' && typeof record.name === 'string'
+          ? { ...state, [record.name]: record.value }
+          : state,
+    }
+    const log = new SharedLog({
+      store,
+      logId: 'log-1',
+      state: emptySharedLogState(reduce),
+      coalesceMs: 0,
+      reduce,
+    })
+    const root = log.view('log-1', () => {})
+    const child = log.view('child', () => {})
+
+    await root.append([{ type: 'app.state_write', name: 'x', value: 1 }])
+    await child.append([{ type: 'app.state_write', name: 'x', value: 2 }])
+
+    expect(log.state.reduced).toEqual({ x: 2 })
+    expect(
+      (await loadLogState({ store, logId: 'log-1', reduce })).reduced,
+    ).toEqual({
+      x: 2,
+    })
+  })
+
+  it('reads only the events of its own session', async () => {
+    const store = memoryLogStore()
+    const { root, child } = sharedWriter(store)
+    const chunk = (delta: string): StreamChunk => ({
+      type: EventType.CUSTOM,
+      name: 'app.ping',
+      value: { delta },
+      timestamp: 1,
+    })
+
+    root.publish('op-root', chunk('root'))
+    child.publish('op-child', chunk('child'))
+    await root.flush()
+    child.close()
+
+    const seen: Array<string> = []
+    for await (const entry of child.read({})) seen.push(entry.operationId)
+    expect(seen).toEqual(['op-child'])
+  })
+})

From 4a7e44dfac7e4ec10c6057c055bafbe8217b7ca9 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 14:31:04 +0200
Subject: [PATCH 121/286] feat(ai-harness): workspaceTools asks before a path
 outside the workspace

- workspaceTools({ root, outside: 'ask' }): a path outside root asks the
  user first, and a yes allows that folder (and the folders in it) for the
  rest of the session. Calls at the same time share one question, and the
  bypass mode skips it. list_files and grep take an optional path. The
  check is in the tools, so calls from code mode ask too. The default
  stays 'deny'.
- harness-cli example: the workspace is the folder where you start the
  app (pnpm's INIT_CWD), and paths outside it ask first.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/workspace-outside.md               |   5 +
 docs/config.json                              |   2 +-
 docs/harness/coding-agent.md                  |  18 +-
 examples/harness-cli/README.md                |  18 +-
 examples/harness-cli/src/cli.ts               |   1 +
 examples/harness-cli/src/harness.ts           |  18 +-
 examples/harness-cli/src/tui.tsx              |   5 +-
 examples/harness-cli/src/workdir.ts           |   6 +
 packages/ai-harness/src/first-party/index.ts  |   1 +
 .../ai-harness/src/first-party/permissions.ts |   9 +-
 .../ai-harness/src/first-party/workspace.ts   | 231 +++++++++++++-----
 .../ai-harness/tests/workspace-tools.test.ts  | 121 ++++++++-
 12 files changed, 345 insertions(+), 90 deletions(-)
 create mode 100644 .changeset/workspace-outside.md
 create mode 100644 examples/harness-cli/src/workdir.ts

diff --git a/.changeset/workspace-outside.md b/.changeset/workspace-outside.md
new file mode 100644
index 0000000000..1a41e367b1
--- /dev/null
+++ b/.changeset/workspace-outside.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-harness': minor
+---
+
+`workspaceTools({ root, outside: 'ask' })`: a path outside the workspace asks the user first, and a yes allows that folder for the rest of the session. The `bypass` mode allows it without a question. `list_files` and `grep` take an optional `path`, so the agent can search an allowed folder. Without the option, a path outside the workspace is refused, as before.
diff --git a/docs/config.json b/docs/config.json
index 655315e6a7..eca2fff56d 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -928,7 +928,7 @@
           "label": "Build a coding agent",
           "to": "harness/coding-agent",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-09-30"
+          "updatedAt": "2026-10-01"
         },
         {
           "label": "Connect model providers",
diff --git a/docs/harness/coding-agent.md b/docs/harness/coding-agent.md
index 134613bfce..dd72795107 100644
--- a/docs/harness/coding-agent.md
+++ b/docs/harness/coding-agent.md
@@ -62,7 +62,7 @@ Run the file with `npx tsx coder.ts`. Ask for a change. The agent reads files fr
 | Plugin | Adds |
 |---|---|
 | `permissions()` | Asks before risky tool calls. `/mode` switches between `default`, `plan` (read-only), `acceptEdits` (edits run without asking), and `bypass`. |
-| `workspaceTools({ root })` | `read_file`, `write_file`, `edit_file`, `list_files`, `grep`, and `bash`, confined to `root`. |
+| `workspaceTools({ root })` | `read_file`, `write_file`, `edit_file`, `list_files`, `grep`, and `bash`, in `root`. A path outside `root` is refused, or asks first with `outside: 'ask'`. |
 | `todos()` | A `todo_write` tool the model uses for multi-step work, and `/todos`. |
 | `modelPicker({ choices })` | `/model <name>` switches the model at the next turn. |
 | `projectInstructions({ root })` | Adds `AGENTS.md` and `CLAUDE.md` to the system prompt. |
@@ -91,6 +91,22 @@ A trailing `*` matches every tool that starts with the text. The last matching r
 
 The workspace tools run on your machine with your permissions. Run code you do not trust in a sandbox.
 
+## Ask before the agent goes outside the workspace
+
+Now and then the agent needs a file from another project, but you do not want to open the whole disk. Pass `outside: 'ask'`:
+
+```ts group=harness-coding-agent
+export const askOutside = workspaceTools({
+  root: process.cwd(),
+  outside: 'ask',
+})
+```
+
+- A path outside `root` asks the user first. A yes allows that folder, and the folders in it, until the session ends.
+- `list_files` and `grep` take a `path`, so the agent can search an allowed folder.
+- `/mode bypass` allows every path without a question.
+- Without the option, a path outside `root` is refused.
+
 ## Hand work to Claude Code or Codex
 
 Your agent can also give tasks to coding agents you already use. [Delegate to coding agents](./coding-agents) shows how.
diff --git a/examples/harness-cli/README.md b/examples/harness-cli/README.md
index acc76011db..0430d88b40 100644
--- a/examples/harness-cli/README.md
+++ b/examples/harness-cli/README.md
@@ -1,6 +1,6 @@
 # Harness CLI example
 
-A coding agent in your terminal, built with `@tanstack/ai-harness`. Talk to it or type. It edits files in `./playground`, makes images, video, speech, songs, and sound effects, reads Notion and Linear, and hands coding work to your local Claude Code and Codex.
+A coding agent in your terminal, built with `@tanstack/ai-harness`. Talk to it or type. It works in the folder where you start it, makes images, video, speech, songs, and sound effects, reads Notion and Linear, and hands coding work to your local Claude Code and Codex.
 
 ## Run it
 
@@ -14,6 +14,18 @@ From the repo root:
 
 Now send a message.
 
+## Your files
+
+The agent works in the folder where you run the command: that folder is the workspace. To work on another project, run the app from that project's folder:
+
+```sh
+pnpm -C <path to examples/harness-cli> start
+```
+
+- The agent reads files in the workspace without asking. A change to a file asks you first.
+- A path outside the workspace asks you first. A yes allows that folder, and the folders in it, until the session ends. `/mode bypass` allows every path without a question.
+- `bash` asks you before each command. A command can reach any file your user can, so read it before you say yes.
+
 ## Connect your models
 
 You do not need a `.env` file. Type `/connect` and pick a provider from the list:
@@ -71,7 +83,7 @@ Voice needs `ffmpeg` on the PATH, and an OpenAI or xAI key for the transcript (`
 Ask in words. The agent picks the tool:
 
 - `make an image of a red fox in the snow`
-- `make a watercolor version of @./playground/fox.png`: the image tool uses the images you send as references.
+- `make a watercolor version of @./fox.png`: the image tool uses the images you send as references.
 - `read this aloud with the nova voice: hello`
 - `compose a 30 second synth-pop song about foxes, with the lyrics "fox in the snow"`
 - `make a 5 second sound effect of rain on a window`
@@ -83,7 +95,7 @@ The harness keeps each file, and the screen saves it in `example-coder-media` wi
 
 ## Hand work to Claude Code and Codex
 
-When `claude` and `codex` are on the PATH, the agent can call them. They work in `./playground` with your own `claude login` and `codex login`, and the API keys are removed from their processes.
+When `claude` and `codex` are on the PATH, the agent can call them. They work in the folder where you started the app, with your own `claude login` and `codex login`, and the API keys are removed from their processes.
 
 - Ask: `have codex create notes.md with one line, then have claude code add a second line`.
 - The screen shows each agent with its status, its tool calls, and its output. When it ends, the last lines of its answer stay.
diff --git a/examples/harness-cli/src/cli.ts b/examples/harness-cli/src/cli.ts
index d19ebdbfdc..85b0304bed 100644
--- a/examples/harness-cli/src/cli.ts
+++ b/examples/harness-cli/src/cli.ts
@@ -1,4 +1,5 @@
 import './env'
+import './workdir'
 import { runCli } from '@tanstack/ai-harness-cli'
 import { assistant } from './harness'
 import { hasSession, listSessions, newSessionId } from './sessions'
diff --git a/examples/harness-cli/src/harness.ts b/examples/harness-cli/src/harness.ts
index dffc61a982..64105ec0d3 100644
--- a/examples/harness-cli/src/harness.ts
+++ b/examples/harness-cli/src/harness.ts
@@ -1,7 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { delimiter, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
 import { EventType, defineAgent, keyedAdapter } from '@tanstack/ai'
 import { defineHarness } from '@tanstack/ai-harness'
 import {
@@ -61,8 +60,9 @@ import type { AnyTextAdapter, KeyedAdapter } from '@tanstack/ai'
 import type { ModelRecord } from '@tanstack/ai-models'
 import type { ByokProvider } from '@tanstack/ai/byok'
 
-// The agent works in ./playground, so it cannot touch the rest of your disk.
-const root = fileURLToPath(new URL('../playground', import.meta.url))
+// The agent works in the folder where you started the app (src/workdir.ts).
+// A path outside it asks you first.
+const root = process.cwd()
 
 /**
  * The demo model's answer, in markdown, so the screen shows how it renders
@@ -371,7 +371,7 @@ const linear = mcpConnector({
 
 // The lead model can hand coding work to your local Claude Code and Codex.
 // Each one turns on when its CLI is on the PATH (CODING_AGENTS=0 turns both
-// off). They work in ./playground with your own `claude login` and
+// off). They work in your folder with your own `claude login` and
 // `codex login`, so the API keys are removed from their processes.
 const useCodingAgents = process.env.CODING_AGENTS !== '0'
 const codingAgentList: Record<string, CodingAgentConfig> = {}
@@ -382,7 +382,7 @@ if (useCodingAgents && onPath('claude')) {
       permissionMode: 'acceptEdits',
     }),
     description:
-      'Claude Code, the local coding agent. Larger changes, refactors, and reviews in ./playground.',
+      'Claude Code, the local coding agent. Larger changes, refactors, and reviews in the workspace.',
   }
 }
 if (useCodingAgents && onPath('codex')) {
@@ -399,7 +399,7 @@ if (useCodingAgents && onPath('codex')) {
       },
     ),
     description:
-      'Codex, the local coding agent. Quick fixes, scripts, and tests in ./playground.',
+      'Codex, the local coding agent. Quick fixes, scripts, and tests in the workspace.',
   }
 }
 const coding =
@@ -407,7 +407,7 @@ const coding =
     ? [
         codingAgents({
           sandbox: defineSandbox({
-            id: 'playground',
+            id: 'workspace',
             provider: localProcessSandbox({
               dir: root,
               scrubEnv: ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY'],
@@ -482,7 +482,7 @@ export const assistant = defineHarness({
     'A coding agent in the terminal: files, voice, media, Notion, Linear, and local coding agents',
   adapter: main,
   systemPrompts: [
-    'You are a careful coding agent that works in ./playground. Read files before you edit them. Keep answers short.',
+    'You are a careful coding agent that works in the workspace, the folder where the user started you. Read files before you edit them. Keep answers short.',
     `Your agent tools: ${tools.join(', ') || 'none'}. The user gets each file a media tool makes, so do not paste file contents or links.`,
     'When the user asks to run Codex or Claude Code (by voice too: "run a Codex agent"), call that tool with a clear task, then give its answer back in a few lines.',
     'The user can send files and voice messages. When they send an image and ask for a new version, a style, or an edit of it, call the image tool with useAttachedImages.',
@@ -501,7 +501,7 @@ export const assistant = defineHarness({
     notion,
     linear,
     permissions(),
-    workspaceTools({ root }),
+    workspaceTools({ root, outside: 'ask' }),
     todos(),
     providerKeys({ providers: keyProviders }),
     modelPicker({ choices, default: startModel }),
diff --git a/examples/harness-cli/src/tui.tsx b/examples/harness-cli/src/tui.tsx
index 76ae0d0817..c9d50ac64a 100644
--- a/examples/harness-cli/src/tui.tsx
+++ b/examples/harness-cli/src/tui.tsx
@@ -1,6 +1,5 @@
 import { readFile } from 'node:fs/promises'
 import { basename } from 'node:path'
-import { fileURLToPath } from 'node:url'
 import {
   useEffect,
   useLayoutEffect,
@@ -71,8 +70,6 @@ import type {
   ViewMessage,
 } from '@tanstack/ai-harness/view'
 
-const playground = fileURLToPath(new URL('../playground', import.meta.url))
-
 const HELP = [
   'Type / to see the commands. ↑ and ↓ go through the lines you sent.',
   'Type @ to pick a file or a folder to send. Tab or Enter fills the path.',
@@ -630,7 +627,7 @@ function App({ view }: { view: SessionView }) {
       )
       const message = await withSpokenFiles(
         text,
-        [playground, mediaDir],
+        [process.cwd(), mediaDir],
         recent,
       )
       // A key question keeps its line for the key only.
diff --git a/examples/harness-cli/src/workdir.ts b/examples/harness-cli/src/workdir.ts
new file mode 100644
index 0000000000..581ee50c10
--- /dev/null
+++ b/examples/harness-cli/src/workdir.ts
@@ -0,0 +1,6 @@
+// Work in the folder where you started the app. `pnpm start` runs the
+// script in this example's folder, and keeps your folder in INIT_CWD. The
+// CLI imports this file after ./env (the .env file is in this example's
+// folder) and before the harness, which reads the folder.
+const started = process.env.INIT_CWD
+if (started) process.chdir(started)
diff --git a/packages/ai-harness/src/first-party/index.ts b/packages/ai-harness/src/first-party/index.ts
index 19f0ca70e5..b7c14acbbb 100644
--- a/packages/ai-harness/src/first-party/index.ts
+++ b/packages/ai-harness/src/first-party/index.ts
@@ -13,6 +13,7 @@ export type {
   PermissionRule,
 } from './permissions'
 export { globToRegExp, workspaceTools } from './workspace'
+export type { WorkspaceToolsOptions } from './workspace'
 export { formatTodos, todos } from './todos'
 export type { Todo } from './todos'
 export { fileCommands, projectInstructions } from './files'
diff --git a/packages/ai-harness/src/first-party/permissions.ts b/packages/ai-harness/src/first-party/permissions.ts
index 8f77eee0ed..d358e97c86 100644
--- a/packages/ai-harness/src/first-party/permissions.ts
+++ b/packages/ai-harness/src/first-party/permissions.ts
@@ -26,6 +26,11 @@ export const PERMISSION_MODES = [
 ] as const
 export type PermissionMode = (typeof PERMISSION_MODES)[number]
 
+/** Is the user's answer a yes: `true`, `y`, or `yes`? */
+export function isYes(answer: unknown) {
+  return answer === true || /^y(es)?$/i.test(String(answer).trim())
+}
+
 function matches(rule: PermissionRule, tool: string): boolean {
   return rule.tool.endsWith('*')
     ? tool.startsWith(rule.tool.slice(0, -1))
@@ -127,9 +132,7 @@ export function permissions(
                 const answer: unknown = await ctx.session.ask({
                   message: `Allow ${hook.toolName} ${preview}? (y/n)`,
                 })
-                const allowed =
-                  answer === true || /^y(es)?$/i.test(String(answer).trim())
-                if (allowed) return undefined
+                if (isYes(answer)) return undefined
               }
               return {
                 type: 'skip',
diff --git a/packages/ai-harness/src/first-party/workspace.ts b/packages/ai-harness/src/first-party/workspace.ts
index 98d9cb13aa..46b99b990d 100644
--- a/packages/ai-harness/src/first-party/workspace.ts
+++ b/packages/ai-harness/src/first-party/workspace.ts
@@ -3,7 +3,7 @@ import { readFile, readdir, stat, writeFile, mkdir } from 'node:fs/promises'
 import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
 import { toolDefinition } from '@tanstack/ai'
 import { definePlugin } from '../plugins'
-import { PermissionRules } from './permissions'
+import { PermissionRules, isYes } from './permissions'
 
 const MAX_OUTPUT = 20_000
 const MAX_READ_LINES = 2000
@@ -45,29 +45,92 @@ export function globToRegExp(glob: string): RegExp {
   return new RegExp(`^${pattern}$`)
 }
 
-/**
- * File and shell tools for a coding agent, confined to `root`: `read_file`,
- * `write_file`, `edit_file`, `list_files`, `grep`, and `bash`. Edits and
- * `bash` ask for approval through `permissions()`.
- *
- * These tools run on this machine with the host's authority. Use a sandbox
- * for code you do not trust.
- */
-export function workspaceTools(options: {
+export interface WorkspaceToolsOptions {
   root: string
   bashTimeoutMs?: number
-}) {
+  /**
+   * A path outside `root`. `'deny'` (default) refuses it. `'ask'` asks the
+   * user first, and a yes allows that folder, and the folders in it, for the
+   * rest of the session. The `bypass` mode of `permissions()` allows it
+   * without a question.
+   */
+  outside?: 'deny' | 'ask'
+}
+
+/** What the tools need from the session for a path outside the workspace. */
+export interface OutsideAccess {
+  /** Ask the user a question, and resolve with the answer. */
+  ask: (message: string) => Promise<unknown>
+  /** The permission mode of the session, for example `'bypass'`. */
+  mode: () => unknown
+}
+
+/** Is `full` the folder `dir`, or a path in it? */
+function within(dir: string, full: string) {
+  return full === dir || full.startsWith(dir.endsWith(sep) ? dir : dir + sep)
+}
+
+/**
+ * The tools of {@link workspaceTools} for one session. `access` asks the user
+ * about a path outside the workspace when `options.outside` is `'ask'`.
+ */
+export function createWorkspaceTools(
+  options: WorkspaceToolsOptions,
+  access?: OutsideAccess,
+) {
   const root = resolve(options.root)
+  // The outside folders the user allowed in this session, and the questions
+  // that wait for an answer, by folder, so parallel calls ask once.
+  const allowed: Array<string> = []
+  const asking = new Map<string, Promise<boolean>>()
+
+  /** Ask once about `folder`. A yes allows it for the session. */
+  const allow = (folder: string, message: string) => {
+    let answer = asking.get(folder)
+    if (!answer) {
+      answer = Promise.resolve(access?.ask(message)).then((reply) => {
+        asking.delete(folder)
+        if (isYes(reply)) allowed.push(folder)
+        return isYes(reply)
+      })
+      asking.set(folder, answer)
+    }
+    return answer
+  }
 
-  const inRoot = (path: string): string => {
+  /**
+   * The full path of `path`, a file or a folder. A path outside the
+   * workspace is refused, or needs the user's yes for its folder.
+   */
+  const reach = async (path: string, tool: string, kind: 'file' | 'folder') => {
     const full = isAbsolute(path) ? resolve(path) : resolve(root, path)
-    if (full !== root && !full.startsWith(root + sep)) {
+    const isAllowed = [root, ...allowed].some((dir) => within(dir, full))
+    if (isAllowed) return full
+    if (options.outside !== 'ask' || !access) {
       throw new Error(`Path "${path}" is outside the workspace.`)
     }
+    if (access.mode() === 'bypass') return full
+    const folder = kind === 'folder' ? full : dirname(full)
+    const yes = await allow(
+      folder,
+      `${tool} wants ${full}, outside the workspace (${root}). Allow ${folder} for this session? (y/n)`,
+    )
+    if (!yes) {
+      throw new Error(
+        `The user did not allow ${full}. It is outside the workspace.`,
+      )
+    }
     return full
   }
+  /** A path for the model: from the workspace, or the full path outside it. */
   const shown = (full: string) =>
-    relative(root, full).split(sep).join('/') || '.'
+    (within(root, full) ? relative(root, full) || '.' : full)
+      .split(sep)
+      .join('/')
+
+  /** The path of `file` from the folder `base`, with `/`, for a glob. */
+  const fromBase = (base: string, file: string) =>
+    relative(base, file).split(sep).join('/')
 
   async function walk(dir: string, out: Array<string>): Promise<void> {
     for (const entry of await readdir(dir, { withFileTypes: true })) {
@@ -95,7 +158,7 @@ export function workspaceTools(options: {
       },
       replay: 'safe',
     }).server(async (args: unknown) => {
-      const full = inRoot(stringArg(args, 'path'))
+      const full = await reach(stringArg(args, 'path'), 'read_file', 'file')
       const lines = (await readFile(full, 'utf8')).split('\n')
       const offset =
         isRecord(args) && typeof args.offset === 'number'
@@ -121,7 +184,7 @@ export function workspaceTools(options: {
         required: ['path', 'content'],
       },
     }).server(async (args: unknown) => {
-      const full = inRoot(stringArg(args, 'path'))
+      const full = await reach(stringArg(args, 'path'), 'write_file', 'file')
       await mkdir(dirname(full), { recursive: true })
       await writeFile(full, stringArg(args, 'content'), 'utf8')
       return `Wrote ${shown(full)}.`
@@ -141,7 +204,7 @@ export function workspaceTools(options: {
         required: ['path', 'old', 'new'],
       },
     }).server(async (args: unknown) => {
-      const full = inRoot(stringArg(args, 'path'))
+      const full = await reach(stringArg(args, 'path'), 'edit_file', 'file')
       const before = await readFile(full, 'utf8')
       const oldText = stringArg(args, 'old')
       const newText = stringArg(args, 'new')
@@ -159,41 +222,64 @@ export function workspaceTools(options: {
     toolDefinition({
       name: 'list_files',
       description:
-        'List files in the workspace, optionally matching a glob like `src/**/*.ts`.',
+        'List files in a folder (default: the workspace), optionally matching a glob like `src/**/*.ts`. The glob is from that folder.',
       inputSchema: {
         type: 'object',
-        properties: { pattern: { type: 'string' } },
+        properties: {
+          pattern: { type: 'string' },
+          path: {
+            type: 'string',
+            description: 'The folder. Default: the workspace',
+          },
+        },
       },
       replay: 'safe',
     }).server(async (args: unknown) => {
+      const base = await reach(
+        optionalString(args, 'path') ?? '.',
+        'list_files',
+        'folder',
+      )
       const pattern = optionalString(args, 'pattern')
       const files: Array<string> = []
-      await walk(root, files)
+      await walk(base, files)
       const regex = pattern ? globToRegExp(pattern) : undefined
       const listed = files
+        .filter((file) => !regex || regex.test(fromBase(base, file)))
         .map(shown)
-        .filter((file) => !regex || regex.test(file))
       return clip(listed.slice(0, 1000).join('\n') || 'No files.')
     }),
     toolDefinition({
       name: 'grep',
       description:
-        'Search file contents with a regular expression. Returns `file:line: text`.',
+        'Search file contents in a folder (default: the workspace) with a regular expression. Returns `file:line: text`.',
       inputSchema: {
         type: 'object',
-        properties: { pattern: { type: 'string' }, glob: { type: 'string' } },
+        properties: {
+          pattern: { type: 'string' },
+          glob: { type: 'string' },
+          path: {
+            type: 'string',
+            description: 'The folder. Default: the workspace',
+          },
+        },
         required: ['pattern'],
       },
       replay: 'safe',
     }).server(async (args: unknown) => {
       const regex = new RegExp(stringArg(args, 'pattern'))
+      const base = await reach(
+        optionalString(args, 'path') ?? '.',
+        'grep',
+        'folder',
+      )
       const glob = optionalString(args, 'glob')
       const fileFilter = glob ? globToRegExp(glob) : undefined
       const files: Array<string> = []
-      await walk(root, files)
+      await walk(base, files)
       const hits: Array<string> = []
       for (const file of files) {
-        if (fileFilter && !fileFilter.test(shown(file))) continue
+        if (fileFilter && !fileFilter.test(fromBase(base, file))) continue
         if ((await stat(file)).size > 1_000_000) continue
         const lines = (await readFile(file, 'utf8')).split('\n')
         lines.forEach((line, index) => {
@@ -236,40 +322,71 @@ export function workspaceTools(options: {
         }),
     ),
   ]
+  const prompt =
+    options.outside === 'ask'
+      ? `Your workspace is ${root}. Paths are relative to it. A path outside it asks the user first.`
+      : `Your workspace is ${root}. Paths are relative to it.`
+  return { tools, prompt }
+}
 
+/**
+ * File and shell tools for a coding agent, in `root`: `read_file`,
+ * `write_file`, `edit_file`, `list_files`, `grep`, and `bash`. Edits and
+ * `bash` ask for approval through `permissions()`. A path outside `root` is
+ * refused, or with `outside: 'ask'` the user is asked first.
+ *
+ * These tools run on this machine with the host's authority. Use a sandbox
+ * for code you do not trust.
+ *
+ * @example
+ * ```ts
+ * workspaceTools({ root: process.cwd(), outside: 'ask' })
+ * ```
+ */
+export function workspaceTools(options: WorkspaceToolsOptions) {
   return definePlugin({
     name: 'tanstack/workspace-tools',
-    setup: () => ({
-      tools,
-      prompts: [`Your workspace is ${root}. Paths are relative to it.`],
-      contribute: [
-        PermissionRules.item({
-          tool: 'read_file',
-          decision: 'allow',
-          kind: 'read',
-        }),
-        PermissionRules.item({
-          tool: 'list_files',
-          decision: 'allow',
-          kind: 'read',
-        }),
-        PermissionRules.item({ tool: 'grep', decision: 'allow', kind: 'read' }),
-        PermissionRules.item({
-          tool: 'write_file',
-          decision: 'ask',
-          kind: 'edit',
-        }),
-        PermissionRules.item({
-          tool: 'edit_file',
-          decision: 'ask',
-          kind: 'edit',
-        }),
-        PermissionRules.item({
-          tool: 'bash',
-          decision: 'ask',
-          kind: 'execute',
-        }),
-      ],
-    }),
+    setup: (ctx) => {
+      const { tools, prompt } = createWorkspaceTools(options, {
+        ask: (message) => ctx.session.ask({ message }),
+        mode: () => ctx.config.get('mode'),
+      })
+      return {
+        tools,
+        prompts: [prompt],
+        contribute: [
+          PermissionRules.item({
+            tool: 'read_file',
+            decision: 'allow',
+            kind: 'read',
+          }),
+          PermissionRules.item({
+            tool: 'list_files',
+            decision: 'allow',
+            kind: 'read',
+          }),
+          PermissionRules.item({
+            tool: 'grep',
+            decision: 'allow',
+            kind: 'read',
+          }),
+          PermissionRules.item({
+            tool: 'write_file',
+            decision: 'ask',
+            kind: 'edit',
+          }),
+          PermissionRules.item({
+            tool: 'edit_file',
+            decision: 'ask',
+            kind: 'edit',
+          }),
+          PermissionRules.item({
+            tool: 'bash',
+            decision: 'ask',
+            kind: 'execute',
+          }),
+        ],
+      }
+    },
   })
 }
diff --git a/packages/ai-harness/tests/workspace-tools.test.ts b/packages/ai-harness/tests/workspace-tools.test.ts
index c3e1f71f7f..edebb29eca 100644
--- a/packages/ai-harness/tests/workspace-tools.test.ts
+++ b/packages/ai-harness/tests/workspace-tools.test.ts
@@ -1,18 +1,36 @@
 import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { join, sep } from 'node:path'
 import { afterAll, beforeAll, describe, expect, it } from 'vitest'
-import { workspaceTools } from '../src/first-party'
+import { createWorkspaceTools } from '../src/first-party/workspace'
 import type { AnyTool } from '@tanstack/ai'
+import type {
+  OutsideAccess,
+  WorkspaceToolsOptions,
+} from '../src/first-party/workspace'
 
 let root: string
 let tools: Map<string, AnyTool>
 
-const run = (name: string, args: unknown): Promise<string> => {
-  const tool = tools.get(name)
+/** The tools by name, for `options` and the user's `access`. */
+function toolsOf(options: WorkspaceToolsOptions, access?: OutsideAccess) {
+  return new Map(
+    createWorkspaceTools(options, access).tools.map(
+      (tool): [string, AnyTool] => [tool.name, tool],
+    ),
+  )
+}
+
+const runIn = (
+  set: Map<string, AnyTool>,
+  name: string,
+  args: unknown,
+): Promise<string> => {
+  const tool = set.get(name)
   if (!tool?.execute) throw new Error(`No tool ${name}`)
   return Promise.resolve(tool.execute(args))
 }
+const run = (name: string, args: unknown) => runIn(tools, name, args)
 
 beforeAll(async () => {
   root = await mkdtemp(join(tmpdir(), 'harness-workspace-'))
@@ -23,14 +41,7 @@ beforeAll(async () => {
   await writeFile(join(root, 'notes.md'), 'two words\n')
   await writeFile(join(root, 'node_modules', 'pkg', 'index.js'), 'two\n')
   await writeFile(join(root, 'big.txt'), `two\n${'x'.repeat(1_100_000)}`)
-  const plugin = workspaceTools({ root, bashTimeoutMs: 20_000 })
-  const contributions = await plugin.setup()
-  tools = new Map(
-    (contributions.tools ?? []).map((tool): [string, AnyTool] => [
-      tool.name,
-      tool,
-    ]),
-  )
+  tools = toolsOf({ root, bashTimeoutMs: 20_000 })
 })
 
 afterAll(async () => {
@@ -139,3 +150,89 @@ describe('bash', () => {
     expect(failed).toMatch(/^exit code: 3/)
   })
 })
+
+describe('outside the workspace', () => {
+  let outside: string
+  beforeAll(async () => {
+    outside = await mkdtemp(join(tmpdir(), 'harness-outside-'))
+    await mkdir(join(outside, 'docs'), { recursive: true })
+    await writeFile(join(outside, 'docs', 'a.md'), 'alpha')
+    await writeFile(join(outside, 'docs', 'b.md'), 'beta')
+    await writeFile(join(outside, 'top.md'), 'top')
+  })
+  afterAll(async () => {
+    await rm(outside, { recursive: true, force: true })
+  })
+
+  /** Tools that ask about outside paths. The user answers from `answers`. */
+  function asking(answers: Array<unknown>, mode = 'default') {
+    const questions: Array<string> = []
+    const set = toolsOf(
+      { root, outside: 'ask' },
+      {
+        ask: async (message) => {
+          questions.push(message)
+          return answers.shift()
+        },
+        mode: () => mode,
+      },
+    )
+    return { set, questions }
+  }
+
+  it('refuses outside paths without the outside option', async () => {
+    await expect(
+      run('read_file', { path: join(outside, 'top.md') }),
+    ).rejects.toThrow('outside the workspace')
+  })
+
+  it('asks once for a folder, then allows it for the session', async () => {
+    const { set, questions } = asking([true])
+    expect(
+      await runIn(set, 'read_file', { path: join(outside, 'docs', 'a.md') }),
+    ).toBe('1\talpha')
+    expect(
+      await runIn(set, 'read_file', { path: join(outside, 'docs', 'b.md') }),
+    ).toBe('1\tbeta')
+    expect(questions).toHaveLength(1)
+    expect(questions[0]).toContain(`Allow ${join(outside, 'docs')}`)
+  })
+
+  it('asks again for another folder, and refuses after a no', async () => {
+    const { set, questions } = asking([true, 'n'])
+    await runIn(set, 'read_file', { path: join(outside, 'docs', 'a.md') })
+    await expect(
+      runIn(set, 'read_file', { path: join(outside, 'top.md') }),
+    ).rejects.toThrow('The user did not allow')
+    expect(questions).toHaveLength(2)
+  })
+
+  it('asks one question for calls at the same time', async () => {
+    const { set, questions } = asking([true])
+    await Promise.all([
+      runIn(set, 'read_file', { path: join(outside, 'docs', 'a.md') }),
+      runIn(set, 'read_file', { path: join(outside, 'docs', 'b.md') }),
+    ])
+    expect(questions).toHaveLength(1)
+  })
+
+  it('lists and searches an allowed outside folder with full paths', async () => {
+    const { set } = asking([true])
+    const folder = join(outside, 'docs')
+    const shown = folder.split(sep).join('/')
+    expect(await runIn(set, 'list_files', { path: folder })).toBe(
+      `${shown}/a.md\n${shown}/b.md`,
+    )
+    expect(await runIn(set, 'grep', { pattern: 'beta', path: folder })).toBe(
+      `${shown}/b.md:1: beta`,
+    )
+  })
+
+  it('does not ask in bypass mode', async () => {
+    const { set, questions } = asking([], 'bypass')
+    expect(
+      await runIn(set, 'read_file', { path: join(outside, 'top.md') }),
+    ).toBe('1\ttop')
+    expect(questions).toHaveLength(0)
+  })
+})

From 95893b00f99d43d7a1cf1a2c9131918fcaca8903 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 14:33:53 +0200
Subject: [PATCH 122/286] fix(ai-harness): close, failure, and checkpoint rules
 of a shared log

A checkpoint records whether it has a reduce or project fold, so a host never starts from a fold that does not match. The host never hands out a log that closed or failed. One thread has one open session per log. The staged records of a closed session do not land later.
---
 packages/ai-harness/src/host.ts       |  12 +-
 packages/ai-harness/src/log.ts        |  44 ++++++--
 packages/ai-harness/src/session.ts    |   4 +-
 packages/ai-harness/tests/log.test.ts | 152 +++++++++++++++++++++++++-
 4 files changed, 194 insertions(+), 18 deletions(-)

diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
index 6cbbc3af9a..ff4184f880 100644
--- a/packages/ai-harness/src/host.ts
+++ b/packages/ai-harness/src/host.ts
@@ -207,11 +207,13 @@ export function createHarnessHost(
                 log: {
                   store: logStore,
                   ...(options.project ? { project: options.project } : {}),
-                  open: async (sessionThread, onFailure) =>
-                    (await sharedLog(logStore, logId)).view(
-                      sessionThread,
-                      onFailure,
-                    ),
+                  open: async (sessionThread, onFailure) => {
+                    let log = await sharedLog(logStore, logId)
+                    // The log closed while this open waited, and the host
+                    // dropped it.
+                    while (!log.isOpen) log = await sharedLog(logStore, logId)
+                    return log.view(sessionThread, onFailure)
+                  },
                 },
               }
             : {}),
diff --git a/packages/ai-harness/src/log.ts b/packages/ai-harness/src/log.ts
index 715f33a4c1..71020c56d9 100644
--- a/packages/ai-harness/src/log.ts
+++ b/packages/ai-harness/src/log.ts
@@ -434,8 +434,9 @@ const versionsOf = (
   project: ProjectOptions | undefined,
   reduce: { version?: string } | undefined,
 ): CheckpointVersions => ({
-  ...(project?.version !== undefined ? { version: project.version } : {}),
-  ...(reduce?.version !== undefined ? { reduceVersion: reduce.version } : {}),
+  ...(project ? { version: project.version ?? '' } : {}),
+  // A checkpoint with a reduce fold never loads without reduce, or the reverse.
+  ...(reduce ? { reduceVersion: reduce.version ?? '' } : {}),
 })
 
 /**
@@ -493,7 +494,10 @@ function deltaKey(thread: string, operationId: string, event: StreamChunk) {
 export interface LogWriter extends EventFeed {
   readonly threadId: string
   readonly logId: string
-  /** The fold of this session. */
+  /**
+   * The fold of this session. In a shared log, `seq` is this session's last
+   * folded record. `head()` is the log position.
+   */
   readonly state: LogState
   /** Append `records` after the pending events, in one batch. */
   append: (records: ReadonlyArray<LogRecord>) => Promise<void>
@@ -542,7 +546,9 @@ export class SharedLog<TState = unknown> {
   /** Every event after this position is in `tail`. */
   private tailFrom: number
   private readonly waiters = new Set<() => void>()
-  private views = 0
+  /** The threads with an open view. */
+  private readonly threads = new Set<string>()
+  private idle = false
   private writing = false
   private hasWritten = false
   private writesSinceCheckpoint = 0
@@ -579,9 +585,25 @@ export class SharedLog<TState = unknown> {
     })
   }
 
+  /**
+   * False after the last view closed or a write failed. The host then opens
+   * a new log.
+   */
+  get isOpen() {
+    return !this.idle
+  }
+
   /** The view of session `threadId`. Close it when the session closes. */
   view(threadId: string, onFailure: (error: unknown) => void): LogWriter {
-    this.views += 1
+    if (this.idle) {
+      throw new Error(`The log ${JSON.stringify(this.logId)} is closed.`)
+    }
+    if (this.threads.has(threadId)) {
+      throw new Error(
+        `The thread ${JSON.stringify(threadId)} already has an open session on this log. Two harnesses cannot open one thread on a durable host.`,
+      )
+    }
+    this.threads.add(threadId)
     // Its own function, so two views with the same `onFailure` both count.
     const listener = (error: unknown) => onFailure(error)
     this.failureListeners.add(listener)
@@ -605,18 +627,21 @@ export class SharedLog<TState = unknown> {
       close: () => {
         if (closed) return
         closed = true
-        this.release(listener)
+        this.release(threadId, listener)
       },
     }
   }
 
-  private release(listener: (error: unknown) => void) {
+  private release(threadId: string, listener: (error: unknown) => void) {
     this.failureListeners.delete(listener)
-    this.views -= 1
+    this.threads.delete(threadId)
+    // Like a crash: the records of a cut tool batch do not land later.
+    this.staged.delete(threadId)
     void this.flush().catch(() => {})
     // The readers of the closed view end. The others wait again.
     this.wake()
-    if (this.views > 0) return
+    if (this.threads.size > 0) return
+    this.idle = true
     this.unsubscribe()
     this.onIdle()
   }
@@ -771,6 +796,7 @@ export class SharedLog<TState = unknown> {
   /** Stop every session of the log. The host drops it, so the next open folds again. */
   private fail(error: unknown) {
     this.failure = error
+    this.idle = true
     for (const listener of [...this.failureListeners]) listener(error)
     this.onIdle()
   }
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 083abe71e6..052ac75eed 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -542,8 +542,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   /**
    * A durable host gives the session its view of the log, and the session
    * writes through it: the log is the event feed and the transcript. Then
-   * both modes build the stores that
-   * `withPersistence` and the checkpoints get.
+   * both modes build the stores that `withPersistence` and the checkpoints
+   * get.
    */
   private async openLog(): Promise<void> {
     const { stores } = this.persistence
diff --git a/packages/ai-harness/tests/log.test.ts b/packages/ai-harness/tests/log.test.ts
index 7494685cfd..6fee58c221 100644
--- a/packages/ai-harness/tests/log.test.ts
+++ b/packages/ai-harness/tests/log.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { EventType } from '@tanstack/ai'
 import {
   LogConflictError,
@@ -20,7 +20,7 @@ import type {
   LogStore,
   MetadataStore,
 } from '@tanstack/ai-persistence'
-import type { ProjectOptions } from '../src/log'
+import type { ProjectOptions, ReduceOptions } from '../src/log'
 import type { SessionEvent } from '../src/types'
 
 const THREAD = 't1'
@@ -484,6 +484,77 @@ describe('fold checkpoints', () => {
       .poll(() => metadata.get(NAMESPACE, THREAD))
       .toMatchObject({ v: 2, seq: 50, version: 'v1' })
   })
+
+  /** Counts the host records of the log. */
+  const countRecords: ReduceOptions<number> = {
+    initial: 0,
+    record: ({ state }) => state + 1,
+  }
+
+  it.each([
+    ['no reduce fold', checkpoint({}), countRecords],
+    [
+      'another reduce version',
+      checkpoint({ reduceVersion: 'r0' }),
+      { ...countRecords, version: 'r1' },
+    ],
+  ])(
+    'ignores a checkpoint with %s for a load with reduce',
+    async (_name, value, reduce) => {
+      const store = memoryLogStore()
+      await store.append(THREAD, 1, [{ type: 'app.tick' }])
+      await store.append(THREAD, 2, [{ type: 'app.tick' }])
+      const { metadata } = memoryPersistence().stores
+      await metadata.set(NAMESPACE, THREAD, value)
+
+      const state = await loadLogState({
+        store,
+        logId: THREAD,
+        metadata,
+        project,
+        reduce,
+      })
+
+      // The count includes record 1: the fold did not start at the checkpoint.
+      expect(state.reduced).toBe(2)
+    },
+  )
+
+  it('starts a reduce fold from the checkpoint that a shared log wrote', async () => {
+    const store = memoryLogStore()
+    const { metadata } = memoryPersistence().stores
+    let calls = 0
+    const reduce: ReduceOptions<number> = {
+      initial: 0,
+      record: ({ state }) => {
+        calls += 1
+        return state + 1
+      },
+    }
+    const log = new SharedLog({
+      store,
+      logId: THREAD,
+      state: emptySharedLogState(reduce),
+      coalesceMs: 0,
+      reduce,
+      metadata,
+    })
+    const writer = log.view(THREAD, () => {})
+    for (let index = 0; index < 50; index += 1) {
+      await writer.append([{ type: 'app.tick', index }])
+    }
+    await expect
+      .poll(() => metadata.get(NAMESPACE, THREAD))
+      .toMatchObject({ seq: 50, reduceVersion: '' })
+    calls = 0
+
+    const state = await loadLogState({ store, logId: THREAD, metadata, reduce })
+
+    expect(state.reduced).toBe(50)
+    expect(state.reduced).toEqual(log.state.reduced)
+    // The fold started at the checkpoint: no record folded again.
+    expect(calls).toBe(0)
+  })
 })
 
 describe('engine message store', () => {
@@ -770,4 +841,81 @@ describe('a log shared by sessions', () => {
     for await (const entry of child.read({})) seen.push(entry.operationId)
     expect(seen).toEqual(['op-child'])
   })
+
+  it('closes after the last view closes, and opens no view after that', () => {
+    const { log, root, child } = sharedWriter(memoryLogStore())
+
+    root.close()
+    expect(log.isOpen).toBe(true)
+    child.close()
+
+    expect(log.isOpen).toBe(false)
+    expect(() => log.view('log-1', () => {})).toThrow(
+      'The log "log-1" is closed.',
+    )
+  })
+
+  it('stops every view and closes when another writer appends', async () => {
+    const store = memoryLogStore()
+    const onIdle = vi.fn()
+    const log = new SharedLog({
+      store,
+      logId: 'log-1',
+      state: emptySharedLogState(),
+      coalesceMs: 0,
+      onIdle,
+    })
+    const rootFailure = vi.fn()
+    const childFailure = vi.fn()
+    const root = log.view('log-1', rootFailure)
+    const child = log.view('child', childFailure)
+    await root.append([{ type: 'app.mine' }])
+
+    // Another writer takes the next position.
+    await store.append('log-1', 2, [{ type: 'app.other' }])
+    await expect(root.append([{ type: 'app.late' }])).rejects.toBeInstanceOf(
+      LogConflictError,
+    )
+
+    expect(rootFailure).toHaveBeenCalledTimes(1)
+    expect(childFailure).toHaveBeenCalledTimes(1)
+    expect(onIdle).toHaveBeenCalled()
+    expect(log.isOpen).toBe(false)
+    await expect(root.append([{ type: 'app.x' }])).rejects.toBeInstanceOf(
+      LogConflictError,
+    )
+    await expect(child.append([{ type: 'app.x' }])).rejects.toBeInstanceOf(
+      LogConflictError,
+    )
+  })
+
+  it('opens one view per thread at a time', async () => {
+    const store = memoryLogStore()
+    const { log, root } = sharedWriter(store)
+
+    expect(() => log.view('log-1', () => {})).toThrow(
+      'The thread "log-1" already has an open session on this log.',
+    )
+    root.close()
+
+    // The child view keeps the log open, so the thread opens again.
+    const again = log.view('log-1', () => {})
+    await again.append([{ type: 'app.note' }])
+    expect(await records(store, 'log-1')).toEqual([{ type: 'app.note' }])
+  })
+
+  it('drops the staged records of a closed view', async () => {
+    const store = memoryLogStore()
+    // The root view keeps the log open.
+    const { log, child } = sharedWriter(store)
+
+    child.stage([{ type: 'app.x' }])
+    child.close()
+    const next = log.view('child', () => {})
+    await next.commit({ messages: [user('c1', 'hi')] })
+
+    expect(
+      (await records(store, 'log-1')).map((record) => record.type),
+    ).toEqual(['harness.transcript'])
+  })
 })

From 5ecb7f601cc21a4ad95e5d9ae6066c9708342133 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 14:41:26 +0200
Subject: [PATCH 123/286] fix(ai-harness): give the log view back when a
 session fails to open

A session that fails to open (a plugin setup error, a store error) closes its log view. Without that, its thread stayed open on the shared log and could not open again until a restart.
---
 packages/ai-harness/src/log.ts                |  2 +-
 packages/ai-harness/src/session.ts            | 49 +++++++++++--------
 .../ai-harness/tests/durable-session.test.ts  | 27 +++++++++-
 3 files changed, 55 insertions(+), 23 deletions(-)

diff --git a/packages/ai-harness/src/log.ts b/packages/ai-harness/src/log.ts
index 71020c56d9..8095fbf42a 100644
--- a/packages/ai-harness/src/log.ts
+++ b/packages/ai-harness/src/log.ts
@@ -435,7 +435,7 @@ const versionsOf = (
   reduce: { version?: string } | undefined,
 ): CheckpointVersions => ({
   ...(project ? { version: project.version ?? '' } : {}),
-  // A checkpoint with a reduce fold never loads without reduce, or the reverse.
+  // A checkpoint folded with reduce or project never loads without it, or the reverse.
   ...(reduce ? { reduceVersion: reduce.version ?? '' } : {}),
 })
 
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 052ac75eed..47b626a019 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -514,29 +514,36 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   async open(): Promise<void> {
     // First: plugins publish events while they mount.
     await this.openLog()
-    this.plugins = this.harness.plugins?.() ?? []
-    this.sessionPlugins = await mountPlugins(
-      this.plugins.filter(
-        (plugin) => (plugin.lifetime ?? 'session') === 'session',
-      ),
-      {
-        threadId: this.threadId,
-        registry: this.agentRegistry,
-        harnessTools: this.harness.tools ?? [],
-        harnessProvides: (this.harness.middleware ?? []).flatMap(
-          (middleware) => middleware.provides ?? [],
+    try {
+      this.plugins = this.harness.plugins?.() ?? []
+      this.sessionPlugins = await mountPlugins(
+        this.plugins.filter(
+          (plugin) => (plugin.lifetime ?? 'session') === 'session',
         ),
-        services: this.services,
-      },
-    )
-    await this.loadConfig()
-    await this.loadPluginState()
-    if (this.writer) {
-      await this.recoverFromLog(this.writer)
-      return
+        {
+          threadId: this.threadId,
+          registry: this.agentRegistry,
+          harnessTools: this.harness.tools ?? [],
+          harnessProvides: (this.harness.middleware ?? []).flatMap(
+            (middleware) => middleware.provides ?? [],
+          ),
+          services: this.services,
+        },
+      )
+      await this.loadConfig()
+      await this.loadPluginState()
+      if (this.writer) {
+        await this.recoverFromLog(this.writer)
+        return
+      }
+      await this.recoverCrashedTurn()
+      await this.recoverInbox()
+    } catch (error) {
+      // A session that fails to open gives its log view back, so the thread
+      // can open again.
+      this.feed.close()
+      throw error
     }
-    await this.recoverCrashedTurn()
-    await this.recoverInbox()
   }
 
   /**
diff --git a/packages/ai-harness/tests/durable-session.test.ts b/packages/ai-harness/tests/durable-session.test.ts
index 10d33d6fe3..45693829e8 100644
--- a/packages/ai-harness/tests/durable-session.test.ts
+++ b/packages/ai-harness/tests/durable-session.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 import { EventType, toolDefinition } from '@tanstack/ai'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
-import { createHarnessHost, defineHarness } from '../src'
+import { createHarnessHost, defineHarness, definePlugin } from '../src'
 import { loadLogState, sessionOf } from '../src/log'
 import { gate, messageTexts, mockAdapter, text, toolCall } from './helpers'
 import type { StreamChunk } from '@tanstack/ai'
@@ -144,6 +144,31 @@ describe('durable host stores', () => {
 })
 
 describe('durable session log', () => {
+  it('opens the thread again after a session fails to open', async () => {
+    let fail = true
+    const { adapter } = mockAdapter([])
+    const harness = defineHarness({
+      name: 'test/flaky-open',
+      adapter,
+      plugins: () => [
+        definePlugin({
+          name: 'test/flaky',
+          setup: () => {
+            if (fail) throw new Error('setup failed')
+          },
+        }),
+      ],
+    })
+    const host = createHarnessHost({ persistence: durablePersistence() })
+
+    await expect(host.open(harness, { threadId: THREAD })).rejects.toThrow(
+      'setup failed',
+    )
+    fail = false
+    await expect(host.open(harness, { threadId: THREAD })).resolves.toBeTruthy()
+    await host.close()
+  })
+
   it('keeps a streamed text block when the host stops in the middle', async () => {
     const persistence = durablePersistence()
     const release = gate()

From ae1d023f3b0f7c43fabae0b87c5db14ef4a56dc3 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 14:54:55 +0200
Subject: [PATCH 124/286] feat(ai-harness): sessions that share one log

host.open(harness, { threadId, logId }) puts the session in a shared log. A record can name another session of the log with thread, so one append can create a child and link it in the parent. createHarnessHost({ reduce }) folds every host record of a log, and host.logState(logId) reads it.
---
 packages/ai-harness/src/host.ts              |  73 ++++--
 packages/ai-harness/src/index.ts             |   2 +-
 packages/ai-harness/src/session.ts           |  40 +--
 packages/ai-harness/tests/shared-log.test.ts | 260 +++++++++++++++++++
 4 files changed, 331 insertions(+), 44 deletions(-)
 create mode 100644 packages/ai-harness/tests/shared-log.test.ts

diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
index ff4184f880..77d60f8aa2 100644
--- a/packages/ai-harness/src/host.ts
+++ b/packages/ai-harness/src/host.ts
@@ -15,7 +15,7 @@ import type {
   MetadataStore,
 } from '@tanstack/ai-persistence'
 import type { AnyHarness } from './define'
-import type { ProjectOptions } from './log'
+import type { ProjectOptions, ReduceOptions } from './log'
 import type { LeaseOptions } from './resume'
 import type { Principal } from './types'
 
@@ -53,7 +53,7 @@ export type HarnessPersistence =
       } & SharedStores
     >
 
-export interface HarnessHostOptions {
+export interface HarnessHostOptions<TLogState = undefined> {
   /** Where sessions keep their state. Default: in memory, lost on restart. */
   persistence?: HarnessPersistence
   /**
@@ -61,6 +61,12 @@ export interface HarnessHostOptions {
    * Only a host with `stores.log` reads it.
    */
   project?: ProjectOptions
+  /**
+   * A fold of every host record of a log, across all its sessions, in log
+   * order. Read it with `host.logState(logId)`. Only a host with
+   * `stores.log` reads it.
+   */
+  reduce?: ReduceOptions<TLogState>
   /**
    * How long a durable host merges streamed text before it appends it to the
    * log, in milliseconds. Boundaries (a message start or end, a tool call, a
@@ -76,10 +82,16 @@ export interface OpenSessionOptions {
   threadId: string
   /** Who opened the session. Stored on inputs and run records. */
   principal?: Principal
+  /**
+   * The log of the session, on a durable host. Sessions with the same log id
+   * share one log and one writer: one append can hold records for several of
+   * them. Default: `threadId`.
+   */
+  logId?: string
 }
 
 /** Runs sessions for one or more harnesses in this process. */
-export interface HarnessHost {
+export interface HarnessHost<TLogState = undefined> {
   /**
    * Open a session, or return the live one for this harness and thread.
    * Session plugins are set up here, so a plugin error rejects the promise.
@@ -90,6 +102,11 @@ export interface HarnessHost {
   ) => Promise<HarnessSession<THarness>>
   /** Close every live session. */
   close: () => Promise<void>
+  /**
+   * The `reduce` fold of a log that has an open session in this host, or
+   * `undefined`.
+   */
+  logState: (logId: string) => TLogState | undefined
 }
 
 let warned = false
@@ -120,9 +137,9 @@ function checkDurableStores(persistence: HarnessPersistence) {
  * const turn = await session.prompt('Write a haiku about the sea.')
  * ```
  */
-export function createHarnessHost(
-  options: HarnessHostOptions = {},
-): HarnessHost {
+export function createHarnessHost<TLogState = undefined>(
+  options: HarnessHostOptions<TLogState> = {},
+): HarnessHost<TLogState> {
   if (!options.persistence && !warned) {
     warned = true
     console.warn(
@@ -155,7 +172,9 @@ export function createHarnessHost(
   const { metadata } = persistence.stores
   const coalesceMs = options.coalesceMs ?? 100
   /** The shared log of each log id with an open session, by log id. */
-  const logs = new Map<string, Promise<SharedLog>>()
+  const logs = new Map<string, Promise<SharedLog<TLogState>>>()
+  /** The resolved shared logs, for `logState`. */
+  const resolved = new Map<string, SharedLog<TLogState>>()
   const sharedLog = (store: LogStore, logId: string) => {
     const open = logs.get(logId)
     if (open) return open
@@ -164,21 +183,25 @@ export function createHarnessHost(
       logId,
       ...(metadata ? { metadata } : {}),
       ...(options.project ? { project: options.project } : {}),
-    }).then(
-      (state) =>
-        new SharedLog({
-          store,
-          logId,
-          state,
-          coalesceMs,
-          ...(options.project ? { project: options.project } : {}),
-          ...(metadata ? { metadata } : {}),
-          // The next open folds the log again.
-          onIdle: () => {
-            if (logs.get(logId) === loaded) logs.delete(logId)
-          },
-        }),
-    )
+      ...(options.reduce ? { reduce: options.reduce } : {}),
+    }).then((state) => {
+      const log = new SharedLog<TLogState>({
+        store,
+        logId,
+        state,
+        coalesceMs,
+        ...(options.project ? { project: options.project } : {}),
+        ...(options.reduce ? { reduce: options.reduce } : {}),
+        ...(metadata ? { metadata } : {}),
+        // The next open folds the log again.
+        onIdle: () => {
+          if (logs.get(logId) === loaded) logs.delete(logId)
+          if (resolved.get(logId) === log) resolved.delete(logId)
+        },
+      })
+      resolved.set(logId, log)
+      return log
+    })
     loaded.catch(() => logs.delete(logId))
     logs.set(logId, loaded)
     return loaded
@@ -187,12 +210,11 @@ export function createHarnessHost(
   const hostId = `host-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`
 
   return {
-    open(harness, { threadId, principal }) {
+    open(harness, { threadId, principal, logId: openLogId }) {
       const key = `${harness.name}\u0000${threadId}`
       let session = sessions.get(key)
       if (!session) {
-        // ponytail: each thread is its own log until `open` takes a `logId`.
-        const logId = threadId
+        const logId = openLogId ?? threadId
         const created = new HarnessSession({
           harness,
           threadId,
@@ -240,5 +262,6 @@ export function createHarnessHost(
           .map((entry) => entry.value.close()),
       )
     },
+    logState: (logId) => resolved.get(logId)?.state.reduced,
   }
 }
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index 9e41b88b41..8b2aa7ef9b 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -16,7 +16,7 @@ export type {
 } from './durable-tool'
 
 export { logMessageStore } from './log'
-export type { ProjectOptions, ProjectRecord } from './log'
+export type { ProjectOptions, ProjectRecord, ReduceOptions } from './log'
 export type { LeaseOptions } from './resume'
 
 export { definePlugin } from './plugins'
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 47b626a019..f2c6703dfb 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -302,6 +302,22 @@ function hasFinalAnswer(
   )
 }
 
+/** Throw for a record that a host may not write. */
+function checkHostRecords(records: ReadonlyArray<LogRecord>) {
+  for (const record of records) {
+    if (record.type.startsWith('harness.')) {
+      throw new Error(
+        `The record type ${JSON.stringify(record.type)} is reserved for the harness.`,
+      )
+    }
+    if (record.thread !== undefined && typeof record.thread !== 'string') {
+      throw new Error(
+        'The thread field of a log record must be a string: the thread id of a session of the same log.',
+      )
+    }
+  }
+}
+
 const notOpen = () => Promise.reject(new Error('The session is not open yet.'))
 
 /** The message store of a durable session before `open()` reads its log. */
@@ -617,21 +633,14 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         writer.append([{ type: 'harness.tool.step', toolCallId, name, value }]),
     })
     const append = (records: ReadonlyArray<LogRecord>) => {
-      const reserved = records.find((record) =>
-        record.type.startsWith('harness.'),
-      )
-      if (reserved) {
-        throw new Error(
-          `The record type ${JSON.stringify(reserved.type)} is reserved for the harness.`,
-        )
-      }
+      checkHostRecords(records)
       writer.stage(records)
     }
     return { step, append }
   }
 
   /**
-   * The log refused a write: another host wrote to this thread, or the store
+   * The log refused a write: another host wrote to this log, or the store
    * failed. The state of this session is not known any more, so it stops.
    * The next `host.open` folds the log again.
    */
@@ -639,7 +648,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     if (this.logFailure) return
     this.logFailure = new Error(
       error instanceof LogConflictError
-        ? 'Another host wrote to this thread, so this session stopped. Open the thread again.'
+        ? 'Another host wrote to this log, so this session stopped. Open the thread again.'
         : `The session log failed, so this session stopped: ${error instanceof Error ? error.message : String(error)}`,
     )
     for (const operation of this.operations.values()) {
@@ -653,6 +662,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
    * Append host records to the session log, in one batch after the events
    * that wait. Only a durable host (with `stores.log`) has a log. A `type`
    * that starts with `harness.` is refused: the harness owns those.
+   * A record can name another session of the same log with `thread`. The
+   * append is all or nothing.
    *
    * With `project` on the host, a record can change the model context. The
    * running turn sees the change at its next model call.
@@ -668,14 +679,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         'session.append needs a durable host (a host with stores.log).',
       )
     }
-    const reserved = records.find((record) =>
-      record.type.startsWith('harness.'),
-    )
-    if (reserved) {
-      throw new Error(
-        `The record type ${JSON.stringify(reserved.type)} is reserved for the harness.`,
-      )
-    }
+    checkHostRecords(records)
     await this.writer.append(records)
   }
 
diff --git a/packages/ai-harness/tests/shared-log.test.ts b/packages/ai-harness/tests/shared-log.test.ts
new file mode 100644
index 0000000000..76648f6109
--- /dev/null
+++ b/packages/ai-harness/tests/shared-log.test.ts
@@ -0,0 +1,260 @@
+import { describe, expect, it, vi } from 'vitest'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness, logMessageStore } from '../src'
+import { gate, messageTexts, mockAdapter, text, untilAborted } from './helpers'
+import type { LogRecord, LogStore } from '@tanstack/ai-persistence'
+import type { ReduceOptions } from '../src'
+import type { Reply } from './helpers'
+
+const LOG = 'agent-1'
+
+function durablePersistence(log: LogStore = memoryLogStore()) {
+  const { runs, metadata } = memoryPersistence().stores
+  return { stores: { log, runs, metadata } }
+}
+
+type Durable = ReturnType<typeof durablePersistence>
+
+/** Host state: the last value of each name, across the whole log. */
+const reduce: ReduceOptions<Record<string, unknown>> = {
+  initial: {},
+  record: ({ state, record }) =>
+    record.type === 'app.state_write' && typeof record.name === 'string'
+      ? { ...state, [record.name]: record.value }
+      : state,
+}
+
+function hostFor(persistence: Durable) {
+  return createHarnessHost({ persistence, reduce })
+}
+
+const harnessWith = (replies: Array<Reply>) => {
+  const { adapter, calls } = mockAdapter(replies)
+  return { harness: defineHarness({ name: 'test/shared', adapter }), calls }
+}
+
+const expireLease = (persistence: Durable, runId: string) =>
+  persistence.stores.runs.update(runId, { leaseExpiresAt: Date.now() - 1 })
+
+describe('sessions that share one log', () => {
+  it('run turns at the same time and each rebuilds its own transcript after a crash', async () => {
+    const persistence = durablePersistence()
+    const release = gate()
+    const host = hostFor(persistence)
+    const rootModel = harnessWith([
+      () =>
+        (async function* () {
+          await release.opened
+          yield* text('root answer')
+        })(),
+    ])
+    const childModel = harnessWith([() => text('child answer'), untilAborted()])
+    const root = await host.open(rootModel.harness, { threadId: LOG })
+    const child = await host.open(childModel.harness, {
+      threadId: 'task-1',
+      logId: LOG,
+    })
+
+    const rootTurn = root.prompt('root question', { inputId: 'root-1' })
+    // The child answers while the root turn still waits.
+    expect(await child.prompt('child question')).toEqual({
+      text: 'child answer',
+    })
+    release.open()
+    expect(await rootTurn).toEqual({ text: 'root answer' })
+    const childTurn = child.prompt('second child question', {
+      inputId: 'child-2',
+    })
+    await vi.waitFor(() => expect(childModel.calls).toHaveLength(2))
+    await expireLease(persistence, childTurn.id)
+
+    const next = hostFor(persistence)
+    const rootAgain = await next.open(harnessWith([]).harness, {
+      threadId: LOG,
+    })
+    const childNext = harnessWith([() => text('child recovered')])
+    const childAgain = await next.open(childNext.harness, {
+      threadId: 'task-1',
+      logId: LOG,
+    })
+
+    expect(
+      (await rootAgain.transcript()).map((message) => message.content),
+    ).toEqual(['root question', 'root answer'])
+    expect(await childAgain.settled('child-2')).toMatchObject({
+      outcome: 'completed',
+    })
+    expect(messageTexts(childNext.calls[0])).toEqual([
+      'child question',
+      'child answer',
+      'second child question',
+    ])
+    expect(await persistence.stores.log.read('task-1')).toEqual([])
+    await host.close().catch(() => {})
+    await next.close()
+  })
+
+  it('lands a child record and a parent record in one append, or neither', async () => {
+    const inner = memoryLogStore()
+    let failNext = false
+    const log: LogStore = {
+      append: async (logId, seq, records) => {
+        if (failNext) {
+          failNext = false
+          throw new Error('store down')
+        }
+        await inner.append(logId, seq, records)
+      },
+      read: (logId, options) => inner.read(logId, options),
+      subscribe: (logId, listener) => inner.subscribe(logId, listener),
+    }
+    const persistence = durablePersistence(log)
+    const host = hostFor(persistence)
+    const root = await host.open(harnessWith([]).harness, { threadId: LOG })
+    const pair: Array<LogRecord> = [
+      { type: 'app.child_created', thread: 'task-1', task: 'research' },
+      { type: 'app.child_linked', child: 'task-1' },
+    ]
+
+    await root.append(pair)
+    const types = async () =>
+      (await inner.read(LOG)).map((entry) => entry.record.type)
+    expect(await types()).toEqual(['app.child_created', 'app.child_linked'])
+
+    failNext = true
+    // The writer tries twice, so both tries fail.
+    const original = log.append
+    log.append = async () => {
+      throw new Error('store down')
+    }
+    await expect(root.append(pair)).rejects.toThrow('store down')
+    log.append = original
+    expect(await types()).toEqual(['app.child_created', 'app.child_linked'])
+    await host.close().catch(() => {})
+  })
+
+  it('folds state writes from two sessions in log order, also after a rebuild', async () => {
+    const persistence = durablePersistence()
+    const host = hostFor(persistence)
+    const root = await host.open(harnessWith([]).harness, { threadId: LOG })
+    const child = await host.open(harnessWith([]).harness, {
+      threadId: 'task-1',
+      logId: LOG,
+    })
+
+    await root.append([{ type: 'app.state_write', name: 'plan', value: 'a' }])
+    await child.append([{ type: 'app.state_write', name: 'plan', value: 'b' }])
+    await root.append([{ type: 'app.state_write', name: 'done', value: true }])
+
+    expect(host.logState(LOG)).toEqual({ plan: 'b', done: true })
+    await host.close()
+    const next = hostFor(persistence)
+    await next.open(harnessWith([]).harness, { threadId: 'task-1', logId: LOG })
+    expect(next.logState(LOG)).toEqual({ plan: 'b', done: true })
+    expect(next.logState('another-log')).toBeUndefined()
+    await next.close()
+  })
+
+  it('gives project only the records of its own session', async () => {
+    const persistence = durablePersistence()
+    const seen: Array<string> = []
+    const host = createHarnessHost({
+      persistence,
+      project: {
+        record: ({ record }) => {
+          seen.push(`${record.type}:${String(record.thread ?? LOG)}`)
+          return undefined
+        },
+      },
+    })
+    const root = await host.open(harnessWith([]).harness, { threadId: LOG })
+    await root.append([
+      { type: 'app.signal', thread: 'task-1' },
+      { type: 'app.signal' },
+    ])
+
+    // One fold for the whole log: each record reaches project once.
+    expect(seen).toEqual([`app.signal:task-1`, `app.signal:${LOG}`])
+    // The task-1 record does not change the transcript of the root session.
+    expect(await root.transcript()).toEqual([])
+    await host.close()
+  })
+
+  it('stops both sessions of the log when another host writes to it', async () => {
+    const persistence = durablePersistence()
+    const host = hostFor(persistence)
+    const root = await host.open(harnessWith([]).harness, { threadId: LOG })
+    const child = await host.open(harnessWith([]).harness, {
+      threadId: 'task-1',
+      logId: LOG,
+    })
+    await root.append([{ type: 'app.signal' }])
+
+    // Another writer takes the next position of the log.
+    const written = await persistence.stores.log.read(LOG)
+    await persistence.stores.log.append(LOG, written.length + 1, [
+      { type: 'app.other' },
+    ])
+
+    await expect(root.append([{ type: 'app.signal' }])).rejects.toThrow(
+      'Log conflict',
+    )
+    await expect(child.append([{ type: 'app.signal' }])).rejects.toThrow(
+      'Log conflict',
+    )
+    await host.close().catch(() => {})
+  })
+
+  it('keeps the other session running when one closes', async () => {
+    const persistence = durablePersistence()
+    const host = hostFor(persistence)
+    const root = await host.open(
+      harnessWith([() => text('still here')]).harness,
+      {
+        threadId: LOG,
+      },
+    )
+    const child = await host.open(harnessWith([]).harness, {
+      threadId: 'task-1',
+      logId: LOG,
+    })
+
+    await child.close()
+
+    expect(await root.prompt('are you there?')).toEqual({ text: 'still here' })
+    await host.close()
+  })
+
+  it('reads one thread of a shared log with logMessageStore', async () => {
+    const persistence = durablePersistence()
+    const host = hostFor(persistence)
+    const child = await host.open(
+      harnessWith([() => text('child answer')]).harness,
+      {
+        threadId: 'task-1',
+        logId: LOG,
+      },
+    )
+    await child.prompt('child question')
+
+    const messages = logMessageStore({
+      store: persistence.stores.log,
+      logId: LOG,
+    })
+    expect((await messages.loadThread('task-1')).map((m) => m.content)).toEqual(
+      ['child question', 'child answer'],
+    )
+    expect(await messages.loadThread(LOG)).toEqual([])
+    await host.close()
+  })
+
+  it('refuses a record whose thread field is not a string', async () => {
+    const host = hostFor(durablePersistence())
+    const root = await host.open(harnessWith([]).harness, { threadId: LOG })
+
+    await expect(
+      root.append([{ type: 'app.signal', thread: 7 }]),
+    ).rejects.toThrow('thread')
+    await host.close()
+  })
+})

From 2bff4d31f723d6e065ad071c6f3905dc336121d6 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 15:01:55 +0200
Subject: [PATCH 125/286] feat(ai-persistence): a LeaseStore type and the
 stores.leases key

A harness host can take turn leases from a system that already has them. AIPersistenceStores gets an optional leases key, with the LeaseStore, TurnLease, and TurnLeaseKey types.
---
 packages/ai-persistence/src/index.ts |  4 ++++
 packages/ai-persistence/src/types.ts | 36 ++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/packages/ai-persistence/src/index.ts b/packages/ai-persistence/src/index.ts
index 87683d10e7..6c1855ec76 100644
--- a/packages/ai-persistence/src/index.ts
+++ b/packages/ai-persistence/src/index.ts
@@ -40,6 +40,10 @@ export type {
   LogEntry,
   LogRecord,
   LogStore,
+  // Harness turn leases
+  LeaseStore,
+  TurnLease,
+  TurnLeaseKey,
   // Named product shapes (prefer these over a sparse bag)
   ChatTranscriptStores,
   ChatPersistenceStores,
diff --git a/packages/ai-persistence/src/types.ts b/packages/ai-persistence/src/types.ts
index 4a043069ca..7e5086cb42 100644
--- a/packages/ai-persistence/src/types.ts
+++ b/packages/ai-persistence/src/types.ts
@@ -781,6 +781,39 @@ export interface BlobStore {
   list: (options?: BlobListOptions) => Promise<BlobListPage>
 }
 
+/** The id of one attempt of a harness turn. */
+export interface TurnLeaseKey {
+  threadId: string
+  inputId: string
+  /** The operation that runs the attempt. Also the AG-UI run id. */
+  operationId: string
+  /** 1 for the first run of the input, then 1 more after each crash. */
+  attempt: number
+}
+
+/** A lease on one attempt of a harness turn. */
+export interface TurnLease extends TurnLeaseKey {
+  /** The host that runs the attempt. */
+  ownerId: string
+  /** Epoch milliseconds. */
+  expiresAt: number
+}
+
+/**
+ * Leases for harness turns, from a system that already has them (a job
+ * queue, a submission table). A durable harness host takes a lease when an
+ * attempt starts, renews it while the attempt runs, and releases it when the
+ * attempt ends. After a crash, a host asks `isAlive` to find the attempts
+ * that nobody runs any more.
+ */
+export interface LeaseStore {
+  acquire: (lease: TurnLease) => Promise<void>
+  renew: (lease: TurnLease) => Promise<void>
+  release: (lease: TurnLease) => Promise<void>
+  /** True while another host still runs the attempt. */
+  isAlive: (key: TurnLeaseKey) => Promise<boolean>
+}
+
 /**
  * Sparse bag of **state** store keys — composition / validation only.
  *
@@ -806,6 +839,8 @@ export interface AIPersistenceStores {
   credentials?: CredentialStore
   /** The harness session log. Optional: only durable harness hosts read it. */
   log?: LogStore
+  /** Turn leases. Optional: only durable harness hosts read it. */
+  leases?: LeaseStore
 }
 
 /**
@@ -984,6 +1019,7 @@ const storeKeys = [
   'inbox',
   'credentials',
   'log',
+  'leases',
 ] satisfies Array<StoreKey>
 
 const storeKeySet = new Set<string>(storeKeys)

From 96d33e9809f514941a7ca346235c05d308de413f Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 15:22:42 +0200
Subject: [PATCH 126/286] fix(ai-harness): a host with reduce fits every
 HarnessHost parameter

HarnessHost defaults its log state type to unknown, so a host made with reduce can go to createHarnessHandler and the other entry points. The shared-log tests now prove that host records reach only their own session, and that a conflict stops both sessions.
---
 packages/ai-harness/src/host.ts              |  2 +-
 packages/ai-harness/tests/shared-log.test.ts | 63 ++++++++++++--------
 2 files changed, 40 insertions(+), 25 deletions(-)

diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
index 77d60f8aa2..943db6616d 100644
--- a/packages/ai-harness/src/host.ts
+++ b/packages/ai-harness/src/host.ts
@@ -91,7 +91,7 @@ export interface OpenSessionOptions {
 }
 
 /** Runs sessions for one or more harnesses in this process. */
-export interface HarnessHost<TLogState = undefined> {
+export interface HarnessHost<TLogState = unknown> {
   /**
    * Open a session, or return the live one for this harness and thread.
    * Session plugins are set up here, so a plugin error rejects the promise.
diff --git a/packages/ai-harness/tests/shared-log.test.ts b/packages/ai-harness/tests/shared-log.test.ts
index 76648f6109..4175b3ad96 100644
--- a/packages/ai-harness/tests/shared-log.test.ts
+++ b/packages/ai-harness/tests/shared-log.test.ts
@@ -1,9 +1,9 @@
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, expectTypeOf, it, vi } from 'vitest'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness, logMessageStore } from '../src'
 import { gate, messageTexts, mockAdapter, text, untilAborted } from './helpers'
 import type { LogRecord, LogStore } from '@tanstack/ai-persistence'
-import type { ReduceOptions } from '../src'
+import type { HarnessHost, ReduceOptions } from '../src'
 import type { Reply } from './helpers'
 
 const LOG = 'agent-1'
@@ -96,15 +96,8 @@ describe('sessions that share one log', () => {
 
   it('lands a child record and a parent record in one append, or neither', async () => {
     const inner = memoryLogStore()
-    let failNext = false
     const log: LogStore = {
-      append: async (logId, seq, records) => {
-        if (failNext) {
-          failNext = false
-          throw new Error('store down')
-        }
-        await inner.append(logId, seq, records)
-      },
+      append: (logId, seq, records) => inner.append(logId, seq, records),
       read: (logId, options) => inner.read(logId, options),
       subscribe: (logId, listener) => inner.subscribe(logId, listener),
     }
@@ -121,7 +114,6 @@ describe('sessions that share one log', () => {
       (await inner.read(LOG)).map((entry) => entry.record.type)
     expect(await types()).toEqual(['app.child_created', 'app.child_linked'])
 
-    failNext = true
     // The writer tries twice, so both tries fail.
     const original = log.append
     log.append = async () => {
@@ -147,6 +139,10 @@ describe('sessions that share one log', () => {
     await root.append([{ type: 'app.state_write', name: 'done', value: true }])
 
     expect(host.logState(LOG)).toEqual({ plan: 'b', done: true })
+    expectTypeOf(host).toExtend<HarnessHost>()
+    expectTypeOf(
+      createHarnessHost({ persistence: durablePersistence() }).logState('x'),
+    ).toEqualTypeOf<undefined>()
     await host.close()
     const next = hostFor(persistence)
     await next.open(harnessWith([]).harness, { threadId: 'task-1', logId: LOG })
@@ -156,27 +152,31 @@ describe('sessions that share one log', () => {
   })
 
   it('gives project only the records of its own session', async () => {
-    const persistence = durablePersistence()
-    const seen: Array<string> = []
     const host = createHarnessHost({
-      persistence,
+      persistence: durablePersistence(),
       project: {
-        record: ({ record }) => {
-          seen.push(`${record.type}:${String(record.thread ?? LOG)}`)
-          return undefined
-        },
+        record: ({ messages, record }) =>
+          record.type === 'app.signal' && typeof record.text === 'string'
+            ? [...messages, { role: 'user', content: record.text }]
+            : undefined,
       },
     })
     const root = await host.open(harnessWith([]).harness, { threadId: LOG })
+    const child = await host.open(harnessWith([]).harness, {
+      threadId: 'task-1',
+      logId: LOG,
+    })
     await root.append([
-      { type: 'app.signal', thread: 'task-1' },
-      { type: 'app.signal' },
+      { type: 'app.signal', thread: 'task-1', text: 'for the child' },
+      { type: 'app.signal', text: 'for the root' },
     ])
 
-    // One fold for the whole log: each record reaches project once.
-    expect(seen).toEqual([`app.signal:task-1`, `app.signal:${LOG}`])
-    // The task-1 record does not change the transcript of the root session.
-    expect(await root.transcript()).toEqual([])
+    expect((await root.transcript()).map((m) => m.content)).toEqual([
+      'for the root',
+    ])
+    expect((await child.transcript()).map((m) => m.content)).toEqual([
+      'for the child',
+    ])
     await host.close()
   })
 
@@ -202,6 +202,21 @@ describe('sessions that share one log', () => {
     await expect(child.append([{ type: 'app.signal' }])).rejects.toThrow(
       'Log conflict',
     )
+
+    // The host replaces a stopped session on the next open.
+    await vi.waitFor(async () =>
+      expect(
+        await host.open(harnessWith([]).harness, { threadId: LOG }),
+      ).not.toBe(root),
+    )
+    await vi.waitFor(async () =>
+      expect(
+        await host.open(harnessWith([]).harness, {
+          threadId: 'task-1',
+          logId: LOG,
+        }),
+      ).not.toBe(child),
+    )
     await host.close().catch(() => {})
   })
 

From 36e4c0d662440cba1eaefa398989004d481a6929 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 15:31:30 +0200
Subject: [PATCH 127/286] refactor(ai-harness): repairTranscript takes the
 pending tool calls

It took a run record. It now takes the thread id and the pending calls, so a host without a run store can repair a cut batch from the log.
---
 packages/ai-harness/src/resume.ts             | 15 ++++----
 packages/ai-harness/src/session.ts            |  9 +++--
 .../ai-harness/tests/resume-edges.test.ts     |  9 ++---
 packages/ai-harness/tests/resume.test.ts      | 34 +++++--------------
 4 files changed, 25 insertions(+), 42 deletions(-)

diff --git a/packages/ai-harness/src/resume.ts b/packages/ai-harness/src/resume.ts
index ad55779dff..002c521c43 100644
--- a/packages/ai-harness/src/resume.ts
+++ b/packages/ai-harness/src/resume.ts
@@ -24,7 +24,7 @@ export const INTERRUPTED_TOOL_RESULT = {
   note: 'The tool may or may not have run. Check before you retry.',
 }
 
-type PendingTool = {
+export type PendingTool = {
   toolCallId: string
   name: string
   replay: 'safe' | 'never'
@@ -153,7 +153,7 @@ export async function findCrashedRuns(
 }
 
 /**
- * Prepare the transcript of a crashed run for a new run. It walks the tool
+ * Prepare the transcript of a crashed thread for a new run. It walks the tool
  * calls of the batch (the last assistant message with tool calls) in order:
  *
  * - A call in `finished` gets its finished tool message. It does not run
@@ -165,14 +165,15 @@ export async function findCrashedRuns(
  */
 export async function repairTranscript(options: {
   messages: MessageStore
-  crashed: RunRecord
+  threadId: string
+  /** The tool calls that started and have no result. */
+  pending: ReadonlyArray<PendingTool>
   /** Tool messages of calls that finished before the crash, by toolCallId. */
   finished?: ReadonlyMap<string, ModelMessage>
 }): Promise<void> {
-  const { messages, crashed, finished } = options
-  const pending = crashed.checkpoint?.pendingTools ?? []
+  const { messages, threadId, pending, finished } = options
   if (pending.length === 0 && (finished?.size ?? 0) === 0) return
-  const history = await messages.loadThread(crashed.threadId)
+  const history = await messages.loadThread(threadId)
   const answered = new Set(
     history.flatMap((message) =>
       message.role === 'tool' && message.toolCallId ? [message.toolCallId] : [],
@@ -205,6 +206,6 @@ export async function repairTranscript(options: {
       ]
     })
   if (added.length > 0) {
-    await messages.saveThread(crashed.threadId, [...history, ...added])
+    await messages.saveThread(threadId, [...history, ...added])
   }
 }
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index f2c6703dfb..5ecf4768c4 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -2534,7 +2534,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       })
     }
     if (!newest) return
-    await repairTranscript({ messages: this.messages, crashed: newest })
+    await repairTranscript({
+      messages: this.messages,
+      threadId: newest.threadId,
+      pending: newest.checkpoint?.pendingTools ?? [],
+    })
     const operation = this.createTurnOperation()
     this.feed.publish(
       operation.id,
@@ -2651,7 +2655,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         if (run) {
           await repairTranscript({
             messages: this.messages,
-            crashed: run,
+            threadId: this.threadId,
+            pending: run.checkpoint?.pendingTools ?? [],
             finished: writer.state.toolResults,
           })
         }
diff --git a/packages/ai-harness/tests/resume-edges.test.ts b/packages/ai-harness/tests/resume-edges.test.ts
index 7dc1f4e805..ae738820ab 100644
--- a/packages/ai-harness/tests/resume-edges.test.ts
+++ b/packages/ai-harness/tests/resume-edges.test.ts
@@ -101,13 +101,8 @@ describe('crash recovery edges', () => {
     const repair = (checkpoint?: RunRecord['checkpoint']) =>
       repairTranscript({
         messages: persistence.stores.messages,
-        crashed: {
-          runId: 'r',
-          threadId: 't1',
-          status: 'running',
-          startedAt: 1,
-          ...(checkpoint ? { checkpoint } : {}),
-        },
+        threadId: 't1',
+        pending: checkpoint?.pendingTools ?? [],
       })
 
     // Only safe tools pending: nothing to note.
diff --git a/packages/ai-harness/tests/resume.test.ts b/packages/ai-harness/tests/resume.test.ts
index f4d6d893e7..efcfec3e7b 100644
--- a/packages/ai-harness/tests/resume.test.ts
+++ b/packages/ai-harness/tests/resume.test.ts
@@ -226,19 +226,11 @@ describe('crash resume', () => {
 
     await repairTranscript({
       messages: stores.messages,
-      crashed: {
-        runId: 'crashed',
-        threadId: 't1',
-        status: 'running',
-        startedAt: 1,
-        checkpoint: {
-          at: 1,
-          pendingTools: [
-            { toolCallId: 'call-charge', name: 'charge', replay: 'never' },
-            { toolCallId: 'call-mail', name: 'mail', replay: 'never' },
-          ],
-        },
-      },
+      threadId: 't1',
+      pending: [
+        { toolCallId: 'call-charge', name: 'charge', replay: 'never' },
+        { toolCallId: 'call-mail', name: 'mail', replay: 'never' },
+      ],
       finished: new Map([['call-charge', finished]]),
     })
 
@@ -281,19 +273,9 @@ describe('crash resume', () => {
 
     await repairTranscript({
       messages: stores.messages,
-      crashed: {
-        runId: 'crashed',
-        threadId: 't1',
-        status: 'running',
-        startedAt: 1,
-        // The charge ended, so only the mail is still pending.
-        checkpoint: {
-          at: 1,
-          pendingTools: [
-            { toolCallId: 'call-mail', name: 'mail', replay: 'never' },
-          ],
-        },
-      },
+      threadId: 't1',
+      // The charge ended, so only the mail is still pending.
+      pending: [{ toolCallId: 'call-mail', name: 'mail', replay: 'never' }],
       finished: new Map([
         [
           'call-charge',

From fc035aa3787f80b3deb028aea5ef9fd39997c020 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 15:43:09 +0200
Subject: [PATCH 128/286] feat(ai-harness): turn leases from a host lease store

A durable host can take stores.leases in place of stores.runs. The harness takes the lease of each turn attempt, renews it, and releases it, and recovery asks isAlive.
---
 packages/ai-harness/src/host.ts               |  22 ++-
 packages/ai-harness/src/index.ts              |   5 +
 packages/ai-harness/src/session.ts            |  68 +++++++-
 packages/ai-harness/tests/leases.test.ts      | 146 ++++++++++++++++++
 .../tests/persistence-validation.test.ts      |  13 +-
 5 files changed, 244 insertions(+), 10 deletions(-)
 create mode 100644 packages/ai-harness/tests/leases.test.ts

diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
index 943db6616d..175b7d8ad5 100644
--- a/packages/ai-harness/src/host.ts
+++ b/packages/ai-harness/src/host.ts
@@ -11,6 +11,7 @@ import type {
   GenerationRunStore,
   InboxStore,
   InterruptStore,
+  LeaseStore,
   LogStore,
   MetadataStore,
 } from '@tanstack/ai-persistence'
@@ -26,13 +27,18 @@ type SharedStores = {
   generationRuns?: GenerationRunStore
 }
 
+/** A durable host needs run leases, host leases, or both. */
+type DurableLeases =
+  | { runs: RunStore; leases?: LeaseStore }
+  | { runs?: RunStore; leases: LeaseStore }
+
 /**
  * The stores a host needs. Two shapes:
  *
  * - A message store, plus any of runs, interrupts, metadata, and inbox.
  *   Without an inbox, inputs are kept in memory and a restart loses the ones
  *   not yet applied.
- * - Durable mode: a `log` and `runs`. The log holds the events, transcript,
+ * - Durable mode: a `log`, and `runs` or `leases`. The log holds the events, transcript,
  *   inputs, and tool steps of each thread, so this shape has no `messages`
  *   and no `inbox`.
  *
@@ -40,17 +46,21 @@ type SharedStores = {
  */
 export type HarnessPersistence =
   | AIPersistence<
-      ChatTranscriptStores & { inbox?: InboxStore; log?: never } & SharedStores
+      ChatTranscriptStores & {
+        inbox?: InboxStore
+        log?: never
+        leases?: never
+      } & SharedStores
     >
   | AIPersistence<
       {
         log: LogStore
-        runs: RunStore
         interrupts?: InterruptStore
         metadata?: MetadataStore
         messages?: never
         inbox?: never
-      } & SharedStores
+      } & DurableLeases &
+        SharedStores
     >
 
 export interface HarnessHostOptions<TLogState = undefined> {
@@ -115,9 +125,9 @@ let warned = false
 function checkDurableStores(persistence: HarnessPersistence) {
   const { stores } = persistence
   if (stores.log === undefined) return
-  if (stores.runs === undefined) {
+  if (stores.runs === undefined && stores.leases === undefined) {
     throw new Error(
-      'A durable host (stores.log) needs stores.runs: run leases find a crashed host.',
+      'A durable host (stores.log) needs stores.runs or stores.leases: a lease finds a crashed host.',
     )
   }
   if (stores.messages !== undefined || stores.inbox !== undefined) {
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index 8b2aa7ef9b..37a9e46040 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -18,6 +18,11 @@ export type {
 export { logMessageStore } from './log'
 export type { ProjectOptions, ProjectRecord, ReduceOptions } from './log'
 export type { LeaseOptions } from './resume'
+export type {
+  LeaseStore,
+  TurnLease,
+  TurnLeaseKey,
+} from '@tanstack/ai-persistence'
 
 export { definePlugin } from './plugins'
 export type {
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 5ecf4768c4..f8c33a0200 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -23,6 +23,7 @@ import { mediaIdOf, mediaOfMessage } from './media-ref'
 import { OperationImpl } from './operation'
 import { mountPlugins } from './plugins'
 import {
+  LEASE,
   checkpointMiddleware,
   findCrashedRuns,
   repairTranscript,
@@ -1696,6 +1697,47 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     return () => clearTimeout(timer)
   }
 
+  /**
+   * Hold the lease of a turn attempt in `stores.leases` while it runs.
+   * Returns the function that releases it. Without a lease store (or
+   * without a log), it returns nothing: the run lease of the checkpoint
+   * middleware decides.
+   */
+  private async holdLease(
+    inputId: string | undefined,
+    operation: OperationImpl<ChatTurnResult>,
+  ): Promise<(() => Promise<void>) | undefined> {
+    const leases = this.persistence.stores.leases
+    const attempt =
+      inputId === undefined
+        ? undefined
+        : this.writer?.state.inputs.get(inputId)?.attempt
+    if (!leases || inputId === undefined || attempt === undefined) {
+      return undefined
+    }
+    const ttlMs = this.lease?.ttlMs ?? LEASE.ttlMs
+    const renewMs = this.lease?.renewMs ?? LEASE.renewMs
+    const lease = () => ({
+      threadId: this.threadId,
+      inputId,
+      operationId: operation.id,
+      attempt,
+      ownerId: this.hostId,
+      expiresAt: Date.now() + ttlMs,
+    })
+    await leases.acquire(lease())
+    const timer = setInterval(
+      () => void leases.renew(lease()).catch(() => {}),
+      renewMs,
+    )
+    // A lease timer must not keep a CLI or a test process alive.
+    if (typeof timer === 'object' && 'unref' in timer) timer.unref()
+    return async () => {
+      clearInterval(timer)
+      await leases.release(lease()).catch(() => {})
+    }
+  }
+
   private async runTurn(turn: QueuedTurn): Promise<void> {
     const { operation } = turn
     operation.setStatus('running')
@@ -1709,6 +1751,14 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         return
       }
     }
+    let releaseLease: (() => Promise<void>) | undefined
+    try {
+      releaseLease = await this.holdLease(turn.inputId, operation)
+    } catch (error) {
+      operation.fail('failed', error)
+      this.publishFinished(operation)
+      return
+    }
     const stopTimer = this.startTimeout(turn.inputId, operation)
     this.publishStarted(operation)
 
@@ -1970,6 +2020,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       operation.finish('completed', { text })
     }
     this.publishFinished(operation)
+    // Release after the settlement: a crash in between leaves a settled input.
+    // No await without a lease: an extra tick would delay the status change.
+    if (releaseLease) await releaseLease()
     // Steers the turn never reached run next, before other queued turns.
     this.queue.unshift(
       ...this.steerQueue.splice(0).map((steer) => {
@@ -2605,12 +2658,21 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         continue
       }
       if (input.status !== 'applied' || !isChat) continue
+      const leases = this.persistence.stores.leases
       const run = input.operationId ? await runs?.get(input.operationId) : null
       const now = Date.now()
+      // A host lease store decides when there is one. Else the run lease does.
       const isAlive =
-        run?.status === 'running' &&
-        run.leaseExpiresAt !== undefined &&
-        run.leaseExpiresAt >= now
+        leases && input.operationId
+          ? await leases.isAlive({
+              threadId: this.threadId,
+              inputId: input.inputId,
+              operationId: input.operationId,
+              attempt: input.attempt,
+            })
+          : run?.status === 'running' &&
+            run.leaseExpiresAt !== undefined &&
+            run.leaseExpiresAt >= now
       // Another host still drives this turn.
       if (isAlive) continue
       if (run?.status === 'running') {
diff --git a/packages/ai-harness/tests/leases.test.ts b/packages/ai-harness/tests/leases.test.ts
new file mode 100644
index 0000000000..c7a94401a1
--- /dev/null
+++ b/packages/ai-harness/tests/leases.test.ts
@@ -0,0 +1,146 @@
+import { describe, expect, it, vi } from 'vitest'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '../src'
+import { mockAdapter, text } from './helpers'
+import type { AnyTool, StreamChunk } from '@tanstack/ai'
+import { EventType } from '@tanstack/ai'
+import type {
+  LeaseStore,
+  TurnLease,
+  TurnLeaseKey,
+} from '@tanstack/ai-persistence'
+import type { Reply } from './helpers'
+
+const THREAD = 't1'
+
+/** A lease store in memory, like a job queue's leases. */
+function memoryLeases() {
+  const leases = new Map<string, TurnLease>()
+  const calls: Array<string> = []
+  const keyOf = (key: TurnLeaseKey) => `${key.inputId}:${key.attempt}`
+  const store: LeaseStore = {
+    acquire: async (lease) => {
+      calls.push(`acquire ${keyOf(lease)}`)
+      leases.set(keyOf(lease), lease)
+    },
+    renew: async (lease) => {
+      leases.set(keyOf(lease), lease)
+    },
+    release: async (lease) => {
+      calls.push(`release ${keyOf(lease)}`)
+      leases.delete(keyOf(lease))
+    },
+    isAlive: async (key) => {
+      const lease = leases.get(keyOf(key))
+      return lease !== undefined && lease.expiresAt >= Date.now()
+    },
+  }
+  const expire = () => {
+    for (const lease of leases.values()) lease.expiresAt = Date.now() - 1
+  }
+  return { store, calls, leases, expire }
+}
+
+function leasedPersistence(leases: LeaseStore) {
+  return { stores: { log: memoryLogStore(), leases } }
+}
+
+async function openLeased(
+  persistence: ReturnType<typeof leasedPersistence>,
+  replies: Array<Reply>,
+  tools: Array<AnyTool> = [],
+) {
+  const { adapter, calls } = mockAdapter(replies)
+  const host = createHarnessHost({ persistence })
+  const session = await host.open(
+    defineHarness({ name: 'test/leases', adapter, tools }),
+    { threadId: THREAD },
+  )
+  return { host, session, calls }
+}
+
+/** A model call that waits until the call is aborted, like a host that stopped. */
+const hangs: Reply = (options: any) =>
+  (async function* (): AsyncGenerator<StreamChunk> {
+    yield {
+      type: EventType.RUN_STARTED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: 1,
+    }
+    await new Promise<void>((resolve) =>
+      options.request?.signal?.addEventListener('abort', () => resolve(), {
+        once: true,
+      }),
+    )
+  })()
+
+describe('a durable host with a lease store and no run store', () => {
+  it('takes, renews, and releases the lease of a turn', async () => {
+    const leases = memoryLeases()
+    const { host, session } = await openLeased(
+      leasedPersistence(leases.store),
+      [() => text('done')],
+    )
+
+    await session.prompt('go', { inputId: 'in-1' })
+
+    expect(leases.calls).toEqual(['acquire in-1:1', 'release in-1:1'])
+    await host.close()
+  })
+
+  it('keeps a turn with a live lease, and runs one with an expired lease again', async () => {
+    const leases = memoryLeases()
+    const persistence = leasedPersistence(leases.store)
+    const first = await openLeased(persistence, [hangs])
+    first.session.prompt('go', { inputId: 'in-1' })
+    await vi.waitFor(() => expect(leases.leases.size).toBe(1))
+
+    // A second host while the lease is alive: it leaves the turn alone.
+    const watcher = await openLeased(persistence, [() => text('never')])
+    expect(watcher.calls).toHaveLength(0)
+    await watcher.host.close()
+
+    leases.expire()
+    const next = await openLeased(persistence, [() => text('recovered')])
+    expect(await next.session.settled('in-1')).toMatchObject({
+      outcome: 'completed',
+    })
+    expect(next.calls).toHaveLength(1)
+    await first.host.close().catch(() => {})
+    await next.host.close()
+  })
+
+  it('throws a clear error for a durable host with neither runs nor leases', () => {
+    expect(() =>
+      createHarnessHost({
+        persistence: { stores: { log: memoryLogStore() } } as never,
+      }),
+    ).toThrow('stores.runs or stores.leases')
+  })
+})
+
+describe('a durable host with runs and leases', () => {
+  it('asks the lease store, and still writes run records', async () => {
+    const leases = memoryLeases()
+    const { runs } = memoryPersistence().stores
+    const persistence = {
+      stores: { log: memoryLogStore(), runs, leases: leases.store },
+    }
+    const { adapter } = mockAdapter([() => text('done')])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({ name: 'test/leases', adapter }),
+      {
+        threadId: THREAD,
+      },
+    )
+
+    const turn = session.prompt('go', { inputId: 'in-1' })
+    await turn
+
+    expect(leases.calls).toEqual(['acquire in-1:1', 'release in-1:1'])
+    expect((await runs.get(turn.id))?.status).toBe('completed')
+    await host.close()
+  })
+})
diff --git a/packages/ai-persistence/tests/persistence-validation.test.ts b/packages/ai-persistence/tests/persistence-validation.test.ts
index 7c669775dd..24c7614c63 100644
--- a/packages/ai-persistence/tests/persistence-validation.test.ts
+++ b/packages/ai-persistence/tests/persistence-validation.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { withGenerationPersistence, withPersistence } from '../src/middleware'
 import { reconstructChat } from '../src/reconstruct'
 import { defineAIPersistence } from '../src/types'
-import type { ChatTranscriptPersistence } from '../src/types'
+import type { ChatTranscriptPersistence, LeaseStore } from '../src/types'
 import {
   createGenerationRunStore,
   createInterruptStore,
@@ -96,4 +96,15 @@ describe('persistence store dependency validation', () => {
       ),
     ).rejects.toThrow(/requires stores\.messages/i)
   })
+
+  it('accepts a lease store', () => {
+    const leases: LeaseStore = {
+      acquire: async () => {},
+      renew: async () => {},
+      release: async () => {},
+      isAlive: async () => false,
+    }
+
+    expect(() => defineAIPersistence({ stores: { leases } })).not.toThrow()
+  })
 })

From 627776ce218cb1c1f42abdd30b891107733df216 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 15:55:18 +0200
Subject: [PATCH 129/286] fix(ai-harness): release the turn lease before the
 turn ends

The lease of a turn is released after its settlement and before the operation ends, so a caller can answer an interrupted turn at once on a lease host. Tests now check the renewal, and a steer that waits when the lease cannot be taken runs as its own turn.
---
 packages/ai-harness/src/host.ts          |  6 +--
 packages/ai-harness/src/session.ts       | 38 ++++++++------
 packages/ai-harness/tests/leases.test.ts | 66 +++++++++++++++++++++++-
 3 files changed, 90 insertions(+), 20 deletions(-)

diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
index 175b7d8ad5..e1657b08ef 100644
--- a/packages/ai-harness/src/host.ts
+++ b/packages/ai-harness/src/host.ts
@@ -38,9 +38,9 @@ type DurableLeases =
  * - A message store, plus any of runs, interrupts, metadata, and inbox.
  *   Without an inbox, inputs are kept in memory and a restart loses the ones
  *   not yet applied.
- * - Durable mode: a `log`, and `runs` or `leases`. The log holds the events, transcript,
- *   inputs, and tool steps of each thread, so this shape has no `messages`
- *   and no `inbox`.
+ * - Durable mode: a `log`, and `runs` or `leases`. The log holds the events,
+ *   transcript, inputs, and tool steps of each thread, so this shape has no
+ *   `messages` and no `inbox`.
  *
  * Without `artifacts`, `blobs`, and `generationRuns`, media is kept in memory.
  */
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index f8c33a0200..da15fc192f 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -1757,6 +1757,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     } catch (error) {
       operation.fail('failed', error)
       this.publishFinished(operation)
+      this.requeueWaitingSteers()
       return
     }
     const stopTimer = this.startTimeout(turn.inputId, operation)
@@ -1984,19 +1985,25 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       ...this.joinedInputs(operation.id, inputId),
     ]
     this.turnJoins.delete(operation.id)
-    const settleTurn = (
+    const settleTurn = async (
       settlement: Omit<InputSettlement, 'inputId' | 'operationId'>,
-    ) =>
-      settled.length === 0 || this.logFailure
-        ? Promise.resolve()
-        : this.settle(
-            ...settled.map((id) => ({
-              inputId: id,
-              operationId: operation.id,
-              ...settlement,
-            })),
-          ).catch(() => {})
+    ) => {
+      if (settled.length > 0 && !this.logFailure) {
+        await this.settle(
+          ...settled.map((id) => ({
+            inputId: id,
+            operationId: operation.id,
+            ...settlement,
+          })),
+        ).catch(() => {})
+      }
+      // Release after the settlement, so a crash in between leaves a settled
+      // input. Release before the operation ends, so the caller can act at
+      // once.
+      if (releaseLease) await releaseLease()
+    }
     if (this.logFailure) {
+      if (releaseLease) await releaseLease()
       operation.fail('failed', this.logFailure)
     } else if (timedOut) {
       const message = 'The input passed its time limit.'
@@ -2020,10 +2027,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       operation.finish('completed', { text })
     }
     this.publishFinished(operation)
-    // Release after the settlement: a crash in between leaves a settled input.
-    // No await without a lease: an extra tick would delay the status change.
-    if (releaseLease) await releaseLease()
-    // Steers the turn never reached run next, before other queued turns.
+    this.requeueWaitingSteers()
+  }
+
+  /** Steers a turn never reached run next, before other queued turns. */
+  private requeueWaitingSteers(): void {
     this.queue.unshift(
       ...this.steerQueue.splice(0).map((steer) => {
         const next = steer.operation ?? this.createTurnOperation()
diff --git a/packages/ai-harness/tests/leases.test.ts b/packages/ai-harness/tests/leases.test.ts
index c7a94401a1..0fb59813f1 100644
--- a/packages/ai-harness/tests/leases.test.ts
+++ b/packages/ai-harness/tests/leases.test.ts
@@ -1,7 +1,9 @@
 import { describe, expect, it, vi } from 'vitest'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness } from '../src'
-import { mockAdapter, text } from './helpers'
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+import { after, gate, mockAdapter, text, toolCall } from './helpers'
 import type { AnyTool, StreamChunk } from '@tanstack/ai'
 import { EventType } from '@tanstack/ai'
 import type {
@@ -24,6 +26,7 @@ function memoryLeases() {
       leases.set(keyOf(lease), lease)
     },
     renew: async (lease) => {
+      calls.push(`renew ${keyOf(lease)}`)
       leases.set(keyOf(lease), lease)
     },
     release: async (lease) => {
@@ -49,9 +52,10 @@ async function openLeased(
   persistence: ReturnType<typeof leasedPersistence>,
   replies: Array<Reply>,
   tools: Array<AnyTool> = [],
+  lease?: { renewMs?: number; ttlMs?: number },
 ) {
   const { adapter, calls } = mockAdapter(replies)
-  const host = createHarnessHost({ persistence })
+  const host = createHarnessHost({ persistence, lease })
   const session = await host.open(
     defineHarness({ name: 'test/leases', adapter, tools }),
     { threadId: THREAD },
@@ -89,6 +93,63 @@ describe('a durable host with a lease store and no run store', () => {
     await host.close()
   })
 
+  it('renews the lease while a turn runs, and stops at the release', async () => {
+    const leases = memoryLeases()
+    const hold = gate()
+    const { host, session } = await openLeased(
+      leasedPersistence(leases.store),
+      [after(hold.opened, 'done')],
+      [],
+      { renewMs: 5, ttlMs: 50 },
+    )
+
+    const turn = session.prompt('go', { inputId: 'in-1' })
+    await vi.waitFor(() => expect(leases.calls).toContain('renew in-1:1'))
+    hold.open()
+    await turn
+
+    const release = leases.calls.indexOf('release in-1:1')
+    expect(release).toBeGreaterThan(-1)
+    expect(leases.calls.slice(release)).not.toContain('renew in-1:1')
+    await host.close()
+  })
+
+  it('lets the caller answer an interrupted turn as soon as it ends', async () => {
+    const leases = memoryLeases()
+    // A store that releases after a timer, like one over the network.
+    const slow: LeaseStore = {
+      ...leases.store,
+      release: async (lease) => {
+        await new Promise((resolve) => setTimeout(resolve, 5))
+        await leases.store.release(lease)
+      },
+    }
+    const remove = toolDefinition({
+      name: 'remove',
+      description: 'Remove a file',
+      needsApproval: true,
+      inputSchema: z.object({ path: z.string() }),
+    }).server(async () => ({ ok: true }))
+    const { host, session } = await openLeased(
+      leasedPersistence(slow),
+      [
+        () => toolCall('remove', { path: 'a.txt' }, 'call_1'),
+        () => text('removed'),
+      ],
+      [remove],
+    )
+
+    const turn = await session.prompt('remove a.txt')
+    const interrupt = turn.interrupts?.[0]
+    if (!interrupt) throw new Error('The turn did not stop for approval.')
+    expect(session.snapshot().status).toBe('requires_action')
+    const receipt = await session.resolve([
+      { interruptId: interrupt.id, status: 'resolved', payload: true },
+    ])
+    expect(receipt.status).toBe('accepted')
+    await host.close()
+  })
+
   it('keeps a turn with a live lease, and runs one with an expired lease again', async () => {
     const leases = memoryLeases()
     const persistence = leasedPersistence(leases.store)
@@ -99,6 +160,7 @@ describe('a durable host with a lease store and no run store', () => {
     // A second host while the lease is alive: it leaves the turn alone.
     const watcher = await openLeased(persistence, [() => text('never')])
     expect(watcher.calls).toHaveLength(0)
+    expect(watcher.session.snapshot().status).toBe('idle')
     await watcher.host.close()
 
     leases.expire()

From 562f88a0645b326188d21395fc44326053c1baf7 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 15:55:40 +0200
Subject: [PATCH 130/286] feat(examples): harness CLI on Cloudflare

A copy of the harness CLI example that keeps its state in one Cloudflare
Worker: a Durable Object for each session log, an Account Durable Object
for the settings, the encrypted keys, the media records, and the session
list, R2 for the media bytes, and code mode in a Dynamic Worker isolate.
The models go through AI Gateway with the Cloudflare adapter, and images,
speech, and voice use Workers AI. A session continues on another PC with
the same Worker URL and secret.

The Worker tests run in workerd and pass the persistence conformance
suite through the same HTTP stores that the CLI uses.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 examples/harness-cli-cloudflare/.env.example  |   21 +
 examples/harness-cli-cloudflare/.gitignore    |    6 +
 examples/harness-cli-cloudflare/README.md     |  134 ++
 examples/harness-cli-cloudflare/package.json  |   46 +
 examples/harness-cli-cloudflare/src/cli.ts    |  122 ++
 .../src/cloudflare-connect.ts                 |  185 +++
 .../src/cloudflare-stores.ts                  |  299 +++++
 examples/harness-cli-cloudflare/src/effort.ts |   59 +
 examples/harness-cli-cloudflare/src/env.ts    |   10 +
 .../harness-cli-cloudflare/src/harness.ts     |  479 +++++++
 .../src/marked-terminal.d.ts                  |   10 +
 examples/harness-cli-cloudflare/src/media.ts  |   69 +
 .../src/screen/commands.ts                    |   23 +
 .../src/screen/editor.ts                      |  133 ++
 .../src/screen/footer.tsx                     |   83 ++
 .../harness-cli-cloudflare/src/screen/keys.ts |   81 ++
 .../src/screen/markdown.ts                    |   64 +
 .../src/screen/media.ts                       |  125 ++
 .../src/screen/menu.tsx                       |   66 +
 .../src/screen/parts.tsx                      |  290 +++++
 .../src/screen/paths.ts                       |   72 ++
 .../src/screen/splash.tsx                     |  150 +++
 .../src/screen/status.tsx                     |   99 ++
 .../src/screen/theme.ts                       |   18 +
 .../harness-cli-cloudflare/src/sessions.ts    |   20 +
 examples/harness-cli-cloudflare/src/store.ts  |   45 +
 examples/harness-cli-cloudflare/src/tui.tsx   | 1108 +++++++++++++++++
 examples/harness-cli-cloudflare/src/voice.ts  |  433 +++++++
 .../harness-cli-cloudflare/src/workdir.ts     |    6 +
 .../src/worker-config.ts                      |   64 +
 examples/harness-cli-cloudflare/tsconfig.json |   14 +
 .../harness-cli-cloudflare/vitest.config.ts   |   11 +
 .../worker/src/account.ts                     |  187 +++
 .../worker/src/crypto.ts                      |   46 +
 .../harness-cli-cloudflare/worker/src/env.ts  |   16 +
 .../worker/src/index.ts                       |  313 +++++
 .../worker/src/session-log.ts                 |   58 +
 .../worker/tests/conformance.test.ts          |   32 +
 .../worker/tests/crypto.test.ts               |   23 +
 .../worker/tests/routes.test.ts               |  158 +++
 .../worker/tsconfig.json                      |   14 +
 .../worker/wrangler.jsonc                     |   31 +
 pnpm-lock.yaml                                |   90 +-
 43 files changed, 5312 insertions(+), 1 deletion(-)
 create mode 100644 examples/harness-cli-cloudflare/.env.example
 create mode 100644 examples/harness-cli-cloudflare/.gitignore
 create mode 100644 examples/harness-cli-cloudflare/README.md
 create mode 100644 examples/harness-cli-cloudflare/package.json
 create mode 100644 examples/harness-cli-cloudflare/src/cli.ts
 create mode 100644 examples/harness-cli-cloudflare/src/cloudflare-connect.ts
 create mode 100644 examples/harness-cli-cloudflare/src/cloudflare-stores.ts
 create mode 100644 examples/harness-cli-cloudflare/src/effort.ts
 create mode 100644 examples/harness-cli-cloudflare/src/env.ts
 create mode 100644 examples/harness-cli-cloudflare/src/harness.ts
 create mode 100644 examples/harness-cli-cloudflare/src/marked-terminal.d.ts
 create mode 100644 examples/harness-cli-cloudflare/src/media.ts
 create mode 100644 examples/harness-cli-cloudflare/src/screen/commands.ts
 create mode 100644 examples/harness-cli-cloudflare/src/screen/editor.ts
 create mode 100644 examples/harness-cli-cloudflare/src/screen/footer.tsx
 create mode 100644 examples/harness-cli-cloudflare/src/screen/keys.ts
 create mode 100644 examples/harness-cli-cloudflare/src/screen/markdown.ts
 create mode 100644 examples/harness-cli-cloudflare/src/screen/media.ts
 create mode 100644 examples/harness-cli-cloudflare/src/screen/menu.tsx
 create mode 100644 examples/harness-cli-cloudflare/src/screen/parts.tsx
 create mode 100644 examples/harness-cli-cloudflare/src/screen/paths.ts
 create mode 100644 examples/harness-cli-cloudflare/src/screen/splash.tsx
 create mode 100644 examples/harness-cli-cloudflare/src/screen/status.tsx
 create mode 100644 examples/harness-cli-cloudflare/src/screen/theme.ts
 create mode 100644 examples/harness-cli-cloudflare/src/sessions.ts
 create mode 100644 examples/harness-cli-cloudflare/src/store.ts
 create mode 100644 examples/harness-cli-cloudflare/src/tui.tsx
 create mode 100644 examples/harness-cli-cloudflare/src/voice.ts
 create mode 100644 examples/harness-cli-cloudflare/src/workdir.ts
 create mode 100644 examples/harness-cli-cloudflare/src/worker-config.ts
 create mode 100644 examples/harness-cli-cloudflare/tsconfig.json
 create mode 100644 examples/harness-cli-cloudflare/vitest.config.ts
 create mode 100644 examples/harness-cli-cloudflare/worker/src/account.ts
 create mode 100644 examples/harness-cli-cloudflare/worker/src/crypto.ts
 create mode 100644 examples/harness-cli-cloudflare/worker/src/env.ts
 create mode 100644 examples/harness-cli-cloudflare/worker/src/index.ts
 create mode 100644 examples/harness-cli-cloudflare/worker/src/session-log.ts
 create mode 100644 examples/harness-cli-cloudflare/worker/tests/conformance.test.ts
 create mode 100644 examples/harness-cli-cloudflare/worker/tests/crypto.test.ts
 create mode 100644 examples/harness-cli-cloudflare/worker/tests/routes.test.ts
 create mode 100644 examples/harness-cli-cloudflare/worker/tsconfig.json
 create mode 100644 examples/harness-cli-cloudflare/worker/wrangler.jsonc

diff --git a/examples/harness-cli-cloudflare/.env.example b/examples/harness-cli-cloudflare/.env.example
new file mode 100644
index 0000000000..1b10feb8d6
--- /dev/null
+++ b/examples/harness-cli-cloudflare/.env.example
@@ -0,0 +1,21 @@
+# Optional. The app needs no .env file: run /connect cloudflare inside the
+# app. This file is a shortcut for development. Copy it to .env. The env vars
+# work when no token is saved with /connect cloudflare.
+# A Cloudflare API token with the Workers AI and AI Gateway permissions.
+CLOUDFLARE_API_TOKEN=
+CLOUDFLARE_ACCOUNT_ID=
+# The AI Gateway that the models go through. Empty means `default`.
+CLOUDFLARE_AI_GATEWAY_ID=
+# Claude Code and Codex turn on when `claude` and `codex` are on the PATH.
+# They use your own `claude login` and `codex login`. Set 0 to turn them off.
+CODING_AGENTS=
+# Codex uses the model and sandbox_mode of ~/.codex/config.toml. These win.
+CODEX_MODEL=
+CODEX_SANDBOX_MODE=
+# Voice input records the microphone with ffmpeg. The first recording picks
+# the microphone. VOICE_DEVICE names one instead. VOICE_LANGUAGE (for example
+# en) is the language you talk in.
+FFMPEG_PATH=
+VOICE_DEVICE=
+VOICE_LANGUAGE=
+VOICE_MIN_LOUDNESS=
diff --git a/examples/harness-cli-cloudflare/.gitignore b/examples/harness-cli-cloudflare/.gitignore
new file mode 100644
index 0000000000..c42e3fa9ee
--- /dev/null
+++ b/examples/harness-cli-cloudflare/.gitignore
@@ -0,0 +1,6 @@
+.env
+# Media the CLI saves (the default --media-dir).
+example-coder-media/
+# Local Worker state of wrangler dev and the tests, and its local secrets.
+worker/.wrangler/
+worker/.dev.vars
diff --git a/examples/harness-cli-cloudflare/README.md b/examples/harness-cli-cloudflare/README.md
new file mode 100644
index 0000000000..629eda3d56
--- /dev/null
+++ b/examples/harness-cli-cloudflare/README.md
@@ -0,0 +1,134 @@
+# Harness CLI on Cloudflare
+
+A coding agent in your terminal, with its state in your Cloudflare account. The agent runs on your PC and works on your files. The sessions, the keys, the media, and code mode run in one Worker. The models go through your AI Gateway.
+
+Because the state is in the Worker, you can start a session on one PC and continue it on another.
+
+## Run it
+
+From the repo root:
+
+1. `pnpm install`
+2. `pnpm build:all` (the example uses the local packages)
+3. Deploy the Worker (see [Deploy the Worker](#deploy-the-worker)). To try it first, run it on your PC (see [Run the Worker on your PC](#run-the-worker-on-your-pc)).
+4. `pnpm --filter harness-cli-cloudflare-example start`. The first start asks for the Worker URL and the secret.
+5. Type `/connect cloudflare`, and paste a Cloudflare API token.
+
+Now send a message.
+
+## Deploy the Worker
+
+Run these commands in `examples/harness-cli-cloudflare`:
+
+1. `pnpm exec wrangler login`
+2. `pnpm exec wrangler r2 bucket create tanstack-harness-media`
+3. `pnpm exec wrangler secret put HARNESS_SECRET -c worker/wrangler.jsonc`. Type a long random string. The CLI sends it with each request.
+4. `pnpm exec wrangler secret put ENCRYPTION_KEY -c worker/wrangler.jsonc`. Type a different long random string. The Worker encrypts the saved keys with it.
+5. `pnpm worker:deploy`. The output shows the Worker URL.
+
+Code mode runs each program in a new isolate (Dynamic Workers). A deploy with code mode needs the Workers Paid plan.
+
+### Run the Worker on your PC
+
+`wrangler dev` runs the same Worker on your PC, also on the Free plan:
+
+1. Make the file `worker/.dev.vars` with two lines:
+
+   ```sh
+   HARNESS_SECRET=any-long-random-string
+   ENCRYPTION_KEY=another-long-random-string
+   ```
+
+2. `pnpm worker:dev`. The Worker is at `http://localhost:8787`.
+3. Start the CLI, and give `http://localhost:8787` and the `HARNESS_SECRET` value.
+
+The local Worker keeps its data in `worker/.wrangler/`.
+
+## What runs where
+
+| Part                                                       | Where                                       |
+| ---------------------------------------------------------- | ------------------------------------------- |
+| The messages, the inputs, and the events of a session      | one Durable Object for each session         |
+| The settings, the plugin state, the keys, and the sign-ins | the Account Durable Object (keys encrypted) |
+| The list of sessions and the media records                 | the Account Durable Object                  |
+| The bytes of the media                                     | R2                                          |
+| The code mode programs                                     | a new isolate in the Worker                 |
+| The models                                                 | Workers AI and your AI Gateway              |
+| Images, speech, and voice transcripts                      | Workers AI, through your AI Gateway         |
+| The agent, your files, `bash`, Claude Code, and Codex      | your PC                                     |
+
+The CLI keeps the Worker URL and the secret in `~/.tanstack-harness-cloudflare/worker.json`. The file is readable by your user only.
+
+## Connect Cloudflare
+
+1. Type `/connect cloudflare`. The page to make an API token opens in the browser.
+2. Make a token with the Workers AI and AI Gateway permissions. Paste it. The input shows dots, not the token.
+3. If the token has more than one account, pick the account.
+4. Type your AI Gateway ID, or press Enter for `default`.
+
+The Worker keeps the token encrypted, so you connect once, on every PC. `/disconnect cloudflare` deletes it.
+
+The Workers AI models need only the token. The AI Gateway models (Claude, GPT, Grok, and more) also need a payment for that provider in the gateway: your provider keys in the gateway, or Unified Billing.
+
+### Developer shortcut: a `.env` file
+
+1. Copy `.env.example` to `.env`.
+2. Set `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID`. `CLOUDFLARE_AI_GATEWAY_ID` is `default` when you do not set it.
+
+The env vars work when no token is saved with `/connect cloudflare`.
+
+## Pick the model and the effort
+
+- `/model` asks for Workers AI or AI Gateway, then the model. AI Gateway asks for the vendor between them.
+- Each model shows its context size, its effort levels, and its price, from `@tanstack/ai-models`.
+- A new session starts on `anthropic/claude-sonnet-5` through your gateway. If the gateway cannot pay for Anthropic, pick a Workers AI model.
+- `/model demo` answers without a token.
+- `/effort` lists the levels of the current model. It sets `chat({ reasoning })`.
+
+## Continue on another PC
+
+1. On the other PC, clone the repo, then do steps 1 and 2 of [Run it](#run-it).
+2. Start the CLI, and give the same Worker URL and secret.
+3. Run `pnpm --filter harness-cli-cloudflare-example start --resume <id>`, or type `/resume` and pick the session.
+
+These come along: the messages, the model and the effort, the todos and the usage, the keys and the sign-ins, and the media.
+
+These stay on each PC:
+
+- Your files. Clone the project on the other PC too.
+- The sessions of Claude Code and Codex.
+- The line history, the microphone choice, and the skills in `~/.tanstack-harness-cloudflare/skills`.
+
+An approval that waits when you close the CLI is gone. Two PCs on the same session at the same time do not work: the second PC gets an error.
+
+## Change the Worker
+
+Type `/connect worker`. The screen closes and asks for the new URL and secret. Then it opens the same session id in the new Worker.
+
+## Talk to it
+
+Hold Ctrl+R while you talk, and let go. The words go into the input line. Fix them if needed, then press Enter.
+
+Voice needs `ffmpeg` on the PATH and `/connect cloudflare`. The transcript comes from Whisper on Workers AI. Set `VOICE_LANGUAGE=en` (or your language) for the language you talk in.
+
+## Make media
+
+Ask in words. The agent picks the tool:
+
+- `make an image of a red fox in the snow` (FLUX.1 schnell)
+- `read this aloud with the orion voice: hello` (Deepgram Aura 2)
+
+The R2 bucket keeps each file. The screen also saves it in `example-coder-media` with a number. `/open 2` opens file 2, and `/play` plays the last speech.
+
+## Everything else
+
+The rest works as in the [harness CLI example](../harness-cli/README.md): your files and the workspace, Claude Code and Codex, Notion and Linear, skills, the screen, the other modes, and the dashboard.
+
+- Use `harness-cli-cloudflare-example` in the `pnpm --filter` commands.
+- The files in your home folder are in `~/.tanstack-harness-cloudflare`, not `~/.tanstack-harness-example`.
+- The Notion and Linear sign-ins are in the Worker, encrypted.
+- Code mode runs in your Worker (`/code-mode`), not in a QuickJS isolate. The tool calls of a program come back to your PC to run.
+
+## Test the Worker
+
+`pnpm --filter harness-cli-cloudflare-example test` runs the Worker in `workerd` on your PC. The tests run the persistence conformance suite of `@tanstack/ai-persistence` against it, through the same HTTP stores that the CLI uses.
diff --git a/examples/harness-cli-cloudflare/package.json b/examples/harness-cli-cloudflare/package.json
new file mode 100644
index 0000000000..4d40482302
--- /dev/null
+++ b/examples/harness-cli-cloudflare/package.json
@@ -0,0 +1,46 @@
+{
+  "name": "harness-cli-cloudflare-example",
+  "private": true,
+  "type": "module",
+  "description": "The harness CLI example with its state, keys, media, and code mode in a Cloudflare Worker, and every model through AI Gateway",
+  "scripts": {
+    "start": "tsx src/cli.ts",
+    "dashboard": "tanstack-ai-dashboard",
+    "worker:dev": "wrangler dev -c worker/wrangler.jsonc",
+    "worker:deploy": "wrangler deploy -c worker/wrangler.jsonc",
+    "test": "vitest run",
+    "test:types": "tsc --noEmit && tsc -p worker/tsconfig.json"
+  },
+  "dependencies": {
+    "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-acp": "workspace:*",
+    "@tanstack/ai-claude-code": "workspace:*",
+    "@tanstack/ai-cloudflare": "workspace:*",
+    "@tanstack/ai-code-mode": "workspace:*",
+    "@tanstack/ai-codex": "workspace:*",
+    "@tanstack/ai-dashboard": "workspace:*",
+    "@tanstack/ai-harness": "workspace:*",
+    "@tanstack/ai-harness-cli": "workspace:*",
+    "@tanstack/ai-isolate-cloudflare": "workspace:*",
+    "@tanstack/ai-mcp": "workspace:*",
+    "@tanstack/ai-models": "workspace:*",
+    "@tanstack/ai-persistence": "workspace:*",
+    "@tanstack/ai-sandbox": "workspace:*",
+    "@tanstack/ai-sandbox-local-process": "workspace:*",
+    "@tanstack/ai-skills": "workspace:*",
+    "@tanstack/react-store": "^0.11.1",
+    "beautiful-mermaid": "^1.1.3",
+    "ink": "^7.1.1",
+    "marked": "^15.0.6",
+    "marked-terminal": "^7.3.0",
+    "react": "^19.2.3",
+    "zod": "^4.2.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260317.1",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "tsx": "^4.23.12",
+    "wrangler": "^4.103.0"
+  }
+}
diff --git a/examples/harness-cli-cloudflare/src/cli.ts b/examples/harness-cli-cloudflare/src/cli.ts
new file mode 100644
index 0000000000..8ff1a41805
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/cli.ts
@@ -0,0 +1,122 @@
+import './env'
+import './workdir'
+import { Writable } from 'node:stream'
+import { createInterface } from 'node:readline/promises'
+import { runCli } from '@tanstack/ai-harness-cli'
+import { checkWorker } from './cloudflare-stores'
+import { assistant } from './harness'
+import { hasSession, listSessions, newSessionId } from './sessions'
+import { workerPersistence } from './store'
+import { runTui, takeNext } from './tui'
+import { loadWorker, saveWorker, setCurrentWorker } from './worker-config'
+
+/**
+ * Ask for the Worker URL and secret until the Worker answers, then save
+ * them. The secret does not show as you type.
+ */
+async function askWorker() {
+  let muted = false
+  const output = new Writable({
+    write: (chunk, _encoding, done) => {
+      if (!muted) process.stdout.write(chunk)
+      done()
+    },
+  })
+  const lines = createInterface({
+    input: process.stdin,
+    output,
+    terminal: true,
+  })
+  try {
+    process.stdout.write('Connect your Worker (see the README to deploy it).\n')
+    for (;;) {
+      const url = (
+        await lines.question(
+          'Worker URL, for example https://tanstack-harness.you.workers.dev: ',
+        )
+      )
+        .trim()
+        .replace(/\/+$/, '')
+      process.stdout.write('Worker secret (HARNESS_SECRET): ')
+      muted = true
+      const secret = (await lines.question('')).trim()
+      muted = false
+      process.stdout.write('\n')
+      const worker = { url, secret }
+      const problem = await checkWorker(worker)
+      if (problem === undefined) {
+        await saveWorker(worker)
+        return worker
+      }
+      process.stdout.write(`${problem} Try again.\n`)
+    }
+  } finally {
+    lines.close()
+  }
+}
+
+/**
+ * The session to open first: `--resume <id>`, `--resume` alone for the
+ * newest saved session, `--thread <id>`, else a new session. The other
+ * options go to runCli.
+ */
+async function firstSession(argv: Array<string>) {
+  const at = argv.findIndex(
+    (arg) => arg === '--resume' || arg.startsWith('--resume='),
+  )
+  if (at === -1) {
+    const thread = argv.indexOf('--thread')
+    const given = thread === -1 ? undefined : argv[thread + 1]
+    return { argv, threadId: given ?? newSessionId() }
+  }
+  const [flag = ''] = argv.splice(at, 1)
+  const next = argv[at]
+  const id = flag.startsWith('--resume=')
+    ? flag.slice('--resume='.length)
+    : next !== undefined && !next.startsWith('-')
+      ? argv.splice(at, 1)[0]
+      : (await listSessions(1))[0]?.id
+  if (id === undefined || !(await hasSession(id))) {
+    process.stderr.write(
+      id === undefined
+        ? 'No saved session yet.\n'
+        : `No saved session ${id}.\n`,
+    )
+    process.exit(1)
+  }
+  return { argv, threadId: id }
+}
+
+// The first start asks for the Worker. Piped input cannot answer, so it
+// needs a start in a terminal first.
+const saved = await loadWorker()
+if (!saved && !process.stdin.isTTY) {
+  process.stderr.write('No Worker yet. Run pnpm start in a terminal first.\n')
+  process.exit(1)
+}
+setCurrentWorker(saved ?? (await askWorker()))
+
+const first = await firstSession(process.argv.slice(2))
+let threadId = first.threadId
+
+// A terminal shows the Ink screen from ./tui. Piped input uses line mode.
+// `/resume` closes the screen, and the loop opens the session it picked.
+// `/connect worker` closes it too, asks for the new Worker, and opens the
+// session again, in the new Worker.
+for (;;) {
+  process.exitCode = await runCli(assistant, {
+    persistence: workerPersistence(),
+    ui: runTui,
+    // The last `--thread` wins.
+    argv: [...first.argv, '--thread', threadId],
+  })
+  const next = takeNext()
+  if (next === undefined) break
+  if (next.askWorker) setCurrentWorker(await askWorker())
+  threadId = next.threadId
+}
+if (await hasSession(threadId)) {
+  process.stderr.write(
+    `Continue this session here or on another PC with: pnpm start --resume ${threadId}\n`,
+  )
+}
diff --git a/examples/harness-cli-cloudflare/src/cloudflare-connect.ts b/examples/harness-cli-cloudflare/src/cloudflare-connect.ts
new file mode 100644
index 0000000000..727091aa14
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/cloudflare-connect.ts
@@ -0,0 +1,185 @@
+import { maskKey } from '@tanstack/ai/byok'
+import { defineCommand, definePlugin } from '@tanstack/ai-harness'
+
+/** The plugin's name. The screen reads its state, like a provider-keys state. */
+export const CLOUDFLARE = 'example/cloudflare'
+
+// The credential with the account id and the gateway id, next to the
+// `cloudflare` credential that holds the API token.
+const ACCOUNT_ID = 'cloudflare-account'
+const TOKEN_PAGE = 'https://dash.cloudflare.com/profile/api-tokens'
+
+/** The Cloudflare account and AI Gateway that the models use. */
+export interface CloudflareAccount {
+  accountId: string
+  gatewayId: string
+}
+
+// The account the adapters read when they are made, just before each call.
+// ponytail: one account for the process, so the CLI serves one user.
+let current: CloudflareAccount | undefined
+
+/** The account from the env vars, the shortcut without /connect. */
+function envAccount() {
+  const accountId = process.env.CLOUDFLARE_ACCOUNT_ID
+  if (!accountId) return undefined
+  return {
+    accountId,
+    gatewayId: process.env.CLOUDFLARE_AI_GATEWAY_ID || 'default',
+  }
+}
+
+/** The account the models use. Throws with the command to run when none. */
+export function cloudflareAccount() {
+  const account = current ?? envAccount()
+  if (!account) {
+    throw new Error(
+      'No Cloudflare account yet. Run /connect cloudflare to connect it.',
+    )
+  }
+  return account
+}
+
+/**
+ * The REST config of a Cloudflare adapter: the user's token, and the
+ * connected account and AI Gateway, so each call goes through the gateway.
+ */
+export function cloudflareRest(token: string) {
+  const { accountId, gatewayId } = cloudflareAccount()
+  return { accountId, apiKey: token, gateway: { id: gatewayId } }
+}
+
+function isAccount(value: unknown): value is CloudflareAccount {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'accountId' in value &&
+    typeof value.accountId === 'string' &&
+    'gatewayId' in value &&
+    typeof value.gatewayId === 'string'
+  )
+}
+
+/** The accounts the token can use, from the Cloudflare API. */
+async function accountsOf(token: string) {
+  const response = await fetch(
+    'https://api.cloudflare.com/client/v4/accounts?per_page=50',
+    { headers: { Authorization: `Bearer ${token}` } },
+  )
+  if (!response.ok) {
+    throw new Error(
+      `Cloudflare refused the token (${response.status}). Make one with Workers AI and AI Gateway permissions.`,
+    )
+  }
+  const body: { result?: Array<{ id: string; name: string }> } =
+    await response.json()
+  return body.result ?? []
+}
+
+/**
+ * `/connect cloudflare` and `/disconnect cloudflare`: the API token, the
+ * account, and the AI Gateway of the models. They are saved in the
+ * session's credential store (the Worker, encrypted). The env vars
+ * `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, and
+ * `CLOUDFLARE_AI_GATEWAY_ID` work when nothing is saved.
+ */
+export function cloudflareConnect() {
+  return definePlugin({
+    name: CLOUDFLARE,
+    setup: async (ctx) => {
+      const state = ctx.state<{
+        providers: Array<{ id: string; label: string; state: string }>
+      }>({ providers: [] })
+
+      /** Read the saved account, and tell the screen where the token comes from. */
+      const refresh = async () => {
+        const [token, saved] = await Promise.all([
+          ctx.credentials.get('cloudflare'),
+          ctx.credentials.get(ACCOUNT_ID),
+        ])
+        const parsed: unknown =
+          saved?.type === 'api_key' ? JSON.parse(saved.value) : undefined
+        current = isAccount(parsed) ? parsed : undefined
+        const where =
+          token?.type === 'api_key'
+            ? 'connected'
+            : process.env.CLOUDFLARE_API_TOKEN
+              ? 'env'
+              : 'missing'
+        await state.update(() => ({
+          providers: [{ id: 'cloudflare', label: 'Cloudflare', state: where }],
+        }))
+      }
+      await refresh()
+
+      /** Ask a question, and give back the answer as trimmed text. */
+      const ask = async (message: string, secret = false) =>
+        String((await ctx.session.ask({ message, secret })) ?? '').trim()
+
+      /** The account for `token`: the only one, or the one the user picks. */
+      const pickAccount = async (token: string) => {
+        const accounts = await accountsOf(token)
+        const [only] = accounts
+        if (accounts.length === 1 && only) return only
+        if (accounts.length === 0) {
+          const id = await ask('Paste your Cloudflare account ID')
+          return { id, name: id }
+        }
+        const list = accounts
+          .map((account, index) => `${index + 1}. ${account.name}`)
+          .join('\n')
+        const answer = await ask(`Which Cloudflare account?\n${list}`)
+        const picked = accounts[Number(answer) - 1]
+        if (!picked) throw new Error(`No account ${answer}. Nothing was saved.`)
+        return picked
+      }
+
+      return {
+        commands: {
+          'connect:cloudflare': defineCommand({
+            description:
+              'Connect your Cloudflare account for Workers AI and AI Gateway',
+            run: async () => {
+              ctx.session.authRequired({
+                connector: 'cloudflare',
+                url: TOKEN_PAGE,
+              })
+              const token = await ask(
+                'Paste a Cloudflare API token with Workers AI and AI Gateway permissions. The page to make one is open in your browser.',
+                true,
+              )
+              if (token === '') {
+                throw new Error(
+                  'No Cloudflare token was given. Nothing was saved.',
+                )
+              }
+              const account = await pickAccount(token)
+              const gatewayId =
+                (await ask('Your AI Gateway ID (press Enter for "default")')) ||
+                'default'
+              await ctx.credentials.set('cloudflare', {
+                type: 'api_key',
+                value: token,
+              })
+              await ctx.credentials.set(ACCOUNT_ID, {
+                type: 'api_key',
+                value: JSON.stringify({ accountId: account.id, gatewayId }),
+              })
+              await refresh()
+              return `Connected to Cloudflare: ${account.name}, gateway ${gatewayId}, token ...${maskKey(token)}.`
+            },
+          }),
+          'disconnect:cloudflare': defineCommand({
+            description: 'Remove your Cloudflare token and account',
+            run: async () => {
+              await ctx.credentials.delete('cloudflare')
+              await ctx.credentials.delete(ACCOUNT_ID)
+              await refresh()
+              return 'Disconnected from Cloudflare.'
+            },
+          }),
+        },
+      }
+    },
+  })
+}
diff --git a/examples/harness-cli-cloudflare/src/cloudflare-stores.ts b/examples/harness-cli-cloudflare/src/cloudflare-stores.ts
new file mode 100644
index 0000000000..bb5696cc54
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/cloudflare-stores.ts
@@ -0,0 +1,299 @@
+import {
+  LogConflictError,
+  defineArtifactStore,
+  defineBlobStore,
+  defineCredentialStore,
+  defineLogStore,
+  defineMetadataStore,
+} from '@tanstack/ai-persistence'
+import type {
+  ArtifactRecord,
+  BlobBody,
+  BlobRecord,
+  Credential,
+  LogEntry,
+} from '@tanstack/ai-persistence'
+
+/** How the CLI reaches its Worker. */
+export interface WorkerConnection {
+  /** The Worker URL, for example `https://tanstack-harness.acme.workers.dev`. */
+  url: string
+  /** The Worker secret (`HARNESS_SECRET`). */
+  secret: string
+  /** The fetch to use. Default: the global `fetch`. */
+  fetch?: typeof fetch
+}
+
+/** A request to the Worker. A status that is not OK throws, except 404 and 409. */
+function caller(connection: WorkerConnection) {
+  const send = connection.fetch ?? fetch
+  const base = connection.url.replace(/\/+$/, '')
+  return async (path: string, init: RequestInit = {}) => {
+    const response = await send(`${base}${path}`, {
+      ...init,
+      headers: {
+        Authorization: `Bearer ${connection.secret}`,
+        ...init.headers,
+      },
+    })
+    const isExpected =
+      response.ok || response.status === 404 || response.status === 409
+    if (!isExpected) {
+      throw new Error(
+        `The Worker answered ${response.status} for ${path}: ${await response.text()}`,
+      )
+    }
+    return response
+  }
+}
+
+/** A path part, safe for the Worker's router. */
+const part = (value: string) => encodeURIComponent(value)
+
+/** The JSON body for a request. */
+const jsonBody = (value: unknown) => ({
+  body: JSON.stringify(value),
+  headers: { 'Content-Type': 'application/json' },
+})
+
+/**
+ * The session log in the Worker: one Durable Object for each session. The
+ * Worker refuses a position that is taken (`409`), as the contract needs.
+ * Listeners hear the appends of this process only.
+ */
+function workerLog(call: ReturnType<typeof caller>) {
+  const listeners = new Map<string, Set<() => void>>()
+  return defineLogStore({
+    append: async (threadId, seq, records) => {
+      if (records.length === 0) return
+      const response = await call(`/sessions/${part(threadId)}/log`, {
+        method: 'POST',
+        ...jsonBody({ seq, records }),
+      })
+      if (response.status === 409) throw new LogConflictError(threadId, seq)
+      for (const listener of [...(listeners.get(threadId) ?? [])]) listener()
+    },
+    read: async (threadId, options = {}) => {
+      if (options.limit === 0) return []
+      const query = new URLSearchParams({ after: String(options.after ?? 0) })
+      if (options.limit !== undefined) query.set('limit', String(options.limit))
+      const response = await call(`/sessions/${part(threadId)}/log?${query}`)
+      const body: { entries: Array<LogEntry> } = await response.json()
+      return body.entries
+    },
+    subscribe: (threadId, listener) => {
+      const set = listeners.get(threadId) ?? new Set()
+      listeners.set(threadId, set)
+      set.add(listener)
+      return () => {
+        set.delete(listener)
+      }
+    },
+  })
+}
+
+function workerMetadata(call: ReturnType<typeof caller>) {
+  const path = (namespace: string, key: string) =>
+    `/metadata/${part(namespace)}/${part(key)}`
+  return defineMetadataStore({
+    get: async (namespace, key) => {
+      const body: { value: unknown } = await (
+        await call(path(namespace, key))
+      ).json()
+      return body.value
+    },
+    set: async (namespace, key, value) => {
+      await call(path(namespace, key), {
+        method: 'PUT',
+        ...jsonBody({ value }),
+      })
+    },
+    delete: async (namespace, key) => {
+      await call(path(namespace, key), { method: 'DELETE' })
+    },
+  })
+}
+
+/** The keys in the Worker, encrypted at rest there. One owner per user. */
+function workerCredentials(call: ReturnType<typeof caller>) {
+  const owner = (scope: { userId?: string; tenantId?: string }) =>
+    part(`${scope.tenantId ?? '-'}/${scope.userId ?? '-'}`)
+  return defineCredentialStore({
+    get: async (scope, id) => {
+      const body: { credential: Credential | null } = await (
+        await call(`/credentials/${owner(scope)}/${part(id)}`)
+      ).json()
+      return body.credential
+    },
+    set: async (scope, id, credential) => {
+      await call(`/credentials/${owner(scope)}/${part(id)}`, {
+        method: 'PUT',
+        ...jsonBody({ credential }),
+      })
+    },
+    delete: async (scope, id) => {
+      await call(`/credentials/${owner(scope)}/${part(id)}`, {
+        method: 'DELETE',
+      })
+    },
+    list: async (scope) => {
+      const body: { items: Array<{ id: string; type: Credential['type'] }> } =
+        await (await call(`/credentials/${owner(scope)}`)).json()
+      return body.items
+    },
+  })
+}
+
+function workerArtifacts(call: ReturnType<typeof caller>) {
+  const records = async (query: string) => {
+    const body: { records: Array<ArtifactRecord> } = await (
+      await call(`/artifacts?${query}`)
+    ).json()
+    return body.records
+  }
+  return defineArtifactStore({
+    save: async (record) => {
+      await call(`/artifacts/${part(record.artifactId)}`, {
+        method: 'PUT',
+        ...jsonBody({ record }),
+      })
+    },
+    get: async (artifactId) => {
+      const body: { record: ArtifactRecord | null } = await (
+        await call(`/artifacts/${part(artifactId)}`)
+      ).json()
+      return body.record
+    },
+    list: (runId) => records(new URLSearchParams({ runId }).toString()),
+    listForThread: (threadId) =>
+      records(new URLSearchParams({ threadId }).toString()),
+    delete: async (artifactId) => {
+      await call(`/artifacts/${part(artifactId)}`, { method: 'DELETE' })
+    },
+    deleteForRun: async (runId) => {
+      await call(`/artifacts?${new URLSearchParams({ runId })}`, {
+        method: 'DELETE',
+      })
+    },
+  })
+}
+
+/** A blob body as something `fetch` can send. */
+async function bytesOf(body: BlobBody) {
+  if (typeof body === 'string') return new TextEncoder().encode(body)
+  if (body instanceof Blob) return new Uint8Array(await body.arrayBuffer())
+  if (body instanceof ArrayBuffer) return new Uint8Array(body)
+  if (ArrayBuffer.isView(body)) {
+    // A copy, so the body owns a plain ArrayBuffer.
+    return new Uint8Array(body.buffer, body.byteOffset, body.byteLength).slice()
+  }
+  return new Uint8Array(await new Response(body).arrayBuffer())
+}
+
+/** The media bytes in R2, through the Worker. */
+function workerBlobs(call: ReturnType<typeof caller>) {
+  const path = (key: string) => `/blobs/${part(key)}`
+  return defineBlobStore({
+    put: async (key, body, options = {}) => {
+      const response = await call(path(key), {
+        method: 'PUT',
+        // ponytail: the body is read into memory first, so `fetch` gets a
+        // length. A stream with `duplex: 'half'` avoids that for big files.
+        body: await bytesOf(body),
+        headers: {
+          ...(options.contentType
+            ? { 'Content-Type': options.contentType }
+            : {}),
+          'x-blob-metadata': JSON.stringify(options.customMetadata ?? {}),
+        },
+      })
+      const record: BlobRecord = await response.json()
+      return record
+    },
+    get: async (key, options = {}) => {
+      const query = new URLSearchParams()
+      if (options.range) {
+        query.set('offset', String(options.range.offset))
+        if (options.range.length !== undefined) {
+          query.set('length', String(options.range.length))
+        }
+      }
+      const response = await call(`${path(key)}?${query}`)
+      if (response.status === 404) return null
+      const record: BlobRecord = JSON.parse(
+        response.headers.get('x-blob-record') ?? '{}',
+      )
+      const range = response.headers.get('x-blob-range')
+      const bytes = new Uint8Array(await response.arrayBuffer())
+      return {
+        ...record,
+        ...(range ? { range: JSON.parse(range) } : {}),
+        arrayBuffer: async () => bytes.slice().buffer,
+        text: async () => new TextDecoder().decode(bytes),
+        body: new Response(bytes).body ?? undefined,
+      }
+    },
+    head: async (key) => {
+      const body: { record: BlobRecord | null } = await (
+        await call(`${path(key)}?head=1`)
+      ).json()
+      return body.record
+    },
+    delete: async (key) => {
+      await call(path(key), { method: 'DELETE' })
+    },
+    list: async (options = {}) => {
+      const query = new URLSearchParams()
+      if (options.prefix !== undefined) query.set('prefix', options.prefix)
+      if (options.cursor !== undefined) query.set('cursor', options.cursor)
+      if (options.limit !== undefined) query.set('limit', String(options.limit))
+      const body: {
+        objects: Array<BlobRecord>
+        cursor?: string
+        truncated?: boolean
+      } = await (await call(`/blobs?${query}`)).json()
+      return body
+    },
+  })
+}
+
+/**
+ * The stores of the CLI that live in the Worker: the session log, the
+ * settings and plugin state, the keys, and the media.
+ */
+export function workerStores(connection: WorkerConnection) {
+  const call = caller(connection)
+  return {
+    log: workerLog(call),
+    metadata: workerMetadata(call),
+    credentials: workerCredentials(call),
+    artifacts: workerArtifacts(call),
+    blobs: workerBlobs(call),
+  }
+}
+
+/** The newest sessions in the Worker, with what the user said first. */
+export async function workerSessions(connection: WorkerConnection, limit = 20) {
+  const body: {
+    sessions: Array<{ id: string; title: string; updatedAt: number }>
+  } = await (await caller(connection)(`/sessions?limit=${limit}`)).json()
+  return body.sessions
+}
+
+/** Does the Worker answer with this URL and secret? The reason when not. */
+export async function checkWorker(connection: WorkerConnection) {
+  try {
+    const send = connection.fetch ?? fetch
+    const response = await send(
+      `${connection.url.replace(/\/+$/, '')}/health`,
+      {
+        headers: { Authorization: `Bearer ${connection.secret}` },
+      },
+    )
+    if (response.status === 401) return 'The Worker refused the secret.'
+    if (!response.ok) return `The Worker answered ${response.status}.`
+    return undefined
+  } catch (error) {
+    return `No answer from ${connection.url}: ${error instanceof Error ? error.message : String(error)}`
+  }
+}
diff --git a/examples/harness-cli-cloudflare/src/effort.ts b/examples/harness-cli-cloudflare/src/effort.ts
new file mode 100644
index 0000000000..8d7e3555bc
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/effort.ts
@@ -0,0 +1,59 @@
+import { REASONING_LEVELS } from '@tanstack/ai'
+import { configOption, defineCommand, definePlugin } from '@tanstack/ai-harness'
+
+export const EFFORTS = ['default', ...REASONING_LEVELS] as const
+type Effort = (typeof EFFORTS)[number]
+
+/**
+ * `/effort`: how hard the main model thinks at the next turn. It sets
+ * `chat({ reasoning })`, which every adapter maps to its own wire field and
+ * clamps to the levels the model has. `default` sends nothing: the model
+ * decides. `reasons` says whether the current model reasons at all.
+ */
+export function effortPicker(options: { reasons: (model: string) => boolean }) {
+  return definePlugin({
+    name: 'example/effort',
+    setup: (ctx) => {
+      const current = (): Effort =>
+        EFFORTS.find((effort) => effort === ctx.config.get('effort')) ??
+        'default'
+      return {
+        config: {
+          effort: configOption.select({
+            options: EFFORTS,
+            default: 'default',
+            category: 'thought_level',
+            description: 'How hard the model thinks',
+          }),
+        },
+        middleware: [
+          {
+            name: 'example/effort',
+            onConfig: () => {
+              const effort = current()
+              if (effort === 'default') return undefined
+              if (!options.reasons(String(ctx.config.get('model')))) {
+                return undefined
+              }
+              return { reasoning: { level: effort, summary: true } }
+            },
+          },
+        ],
+        commands: {
+          effort: defineCommand({
+            description: `Show or set how hard the model thinks (${EFFORTS.join(', ')})`,
+            run: async (input: unknown) => {
+              const name = typeof input === 'string' ? input.trim() : ''
+              if (name === '') return `Effort: ${current()}.`
+              const effort = EFFORTS.find((item) => item === name)
+              if (!effort)
+                return `Unknown effort "${name}". Choices: ${EFFORTS.join(', ')}.`
+              await ctx.session.setConfig('effort', effort)
+              return `Effort: ${effort}. It applies at the next turn.`
+            },
+          }),
+        },
+      }
+    },
+  })
+}
diff --git a/examples/harness-cli-cloudflare/src/env.ts b/examples/harness-cli-cloudflare/src/env.ts
new file mode 100644
index 0000000000..16b37bb24d
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/env.ts
@@ -0,0 +1,10 @@
+// The `.env` shortcut: the keys in ./.env, when the file is there. A missing
+// file is normal (the app needs none), so it says nothing. The CLI imports
+// this file first, so the keys are set before the harness reads them.
+try {
+  process.loadEnvFile()
+} catch (error) {
+  if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+    throw error
+  }
+}
diff --git a/examples/harness-cli-cloudflare/src/harness.ts b/examples/harness-cli-cloudflare/src/harness.ts
new file mode 100644
index 0000000000..de6b582358
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/harness.ts
@@ -0,0 +1,479 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { delimiter, join } from 'node:path'
+import { EventType, defineAgent, keyedAdapter } from '@tanstack/ai'
+import { defineHarness } from '@tanstack/ai-harness'
+import {
+  compact,
+  goal,
+  modelPicker,
+  permissions,
+  projectInstructions,
+  todos,
+  usage,
+  workspaceTools,
+} from '@tanstack/ai-harness/plugins'
+import { claudeCodeText } from '@tanstack/ai-claude-code'
+import { createCloudflareText } from '@tanstack/ai-cloudflare'
+import { cloudflareByok } from '@tanstack/ai-cloudflare/byok'
+import { codeMode } from '@tanstack/ai-code-mode/harness'
+import { codexText } from '@tanstack/ai-codex'
+import { createCloudflareIsolateDriver } from '@tanstack/ai-isolate-cloudflare'
+import { mcpConnector } from '@tanstack/ai-mcp/connector'
+import { getModels, supportedReasoningLevels } from '@tanstack/ai-models'
+import {
+  defineSandbox,
+  defineWorkspace,
+  localSource,
+} from '@tanstack/ai-sandbox'
+import { codingAgents } from '@tanstack/ai-sandbox/harness'
+import type { CodingAgentConfig } from '@tanstack/ai-sandbox/harness'
+import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'
+import { skills } from '@tanstack/ai-skills/harness'
+import { z } from 'zod'
+import { cloudflareConnect, cloudflareRest } from './cloudflare-connect'
+import { imageAgent, speechAgent } from './media'
+import { effortPicker } from './effort'
+import { SAVE_DIR, currentWorker } from './worker-config'
+import { SCREEN_COMMANDS } from './screen/commands'
+import { envKey } from './store'
+import type { AnyTextAdapter, KeyedAdapter } from '@tanstack/ai'
+import type { ModelRecord } from '@tanstack/ai-models'
+import type { ByokProvider } from '@tanstack/ai/byok'
+
+// The agent works in the folder where you started the app (src/workdir.ts).
+// A path outside it asks you first.
+const root = process.cwd()
+
+/**
+ * The demo model's answer, in markdown, so the screen shows how it renders
+ * markdown. Ask it for a chart, and it draws one in Mermaid.
+ */
+function demoReply(said: string) {
+  const chart = /chart|mermaid|diagram/i.test(said)
+    ? '\n\n```mermaid\ngraph LR\n  You --> Harness --> Model\n  Harness --> Tools\n```'
+    : ''
+  return (
+    [
+      `**(demo model)** You said: "${said}".`,
+      '',
+      '- Type `/connect` to connect a provider.',
+      '- Type `/model` to pick a real model.',
+    ].join('\n') + chart
+  )
+}
+
+/** Without any model key, a stand-in model that explains how to add one. */
+function demoModel(): AnyTextAdapter {
+  let calls = 0
+  return {
+    kind: 'text',
+    name: 'demo',
+    model: 'demo',
+    '~types': {
+      providerOptions: {},
+      inputModalities: ['text'],
+      messageMetadataByModality: {
+        text: undefined,
+        image: undefined,
+        audio: undefined,
+        video: undefined,
+        document: undefined,
+      },
+      toolCapabilities: [],
+      toolCallMetadata: undefined,
+      systemPromptMetadata: undefined as never,
+    },
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+    chatStream: (options) =>
+      (async function* () {
+        calls += 1
+        const messageId = `demo-${calls}`
+        const last = options.messages.at(-1)
+        const said = typeof last?.content === 'string' ? last.content : ''
+        const now = Date.now()
+        yield {
+          type: EventType.RUN_STARTED,
+          runId: 'demo',
+          threadId: 'demo',
+          timestamp: now,
+        }
+        yield {
+          type: EventType.TEXT_MESSAGE_START,
+          messageId,
+          role: 'assistant',
+          timestamp: now,
+        }
+        yield {
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          messageId,
+          delta: demoReply(said),
+          timestamp: now,
+        }
+        yield { type: EventType.TEXT_MESSAGE_END, messageId, timestamp: now }
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId: 'demo',
+          threadId: 'demo',
+          timestamp: now,
+          // ponytail: about 4 characters a token, so the footer counts in demo mode too.
+          usage: {
+            promptTokens: Math.ceil(
+              JSON.stringify(options.messages).length / 4,
+            ),
+            completionTokens: 30,
+            totalTokens:
+              Math.ceil(JSON.stringify(options.messages).length / 4) + 30,
+          },
+          metadata: { tanstack: { finishReason: 'stop' } },
+        }
+      })(),
+  }
+}
+
+/** Is a key for `provider` in the environment (the `.env` shortcut)? */
+function hasEnvKey(provider: ByokProvider) {
+  return envKey(provider) !== null
+}
+
+/** A model `/model` can pick. */
+export interface ModelEntry {
+  /** The id the Cloudflare adapter takes, for example `anthropic/claude-sonnet-5`. */
+  id: string
+  /** The key provider to connect: `cloudflare` for every model here. */
+  provider: string
+  record: ModelRecord
+  adapter: KeyedAdapter<AnyTextAdapter>
+}
+
+/**
+ * A Cloudflare model, built just before each call with your token and the
+ * connected account, so every call goes through your AI Gateway.
+ */
+function cloudflareModel(id: string, record: ModelRecord): ModelEntry {
+  return {
+    id,
+    provider: cloudflareByok.id,
+    record,
+    adapter: keyedAdapter(cloudflareByok, (token) =>
+      createCloudflareText(id, cloudflareRest(token)),
+    ),
+  }
+}
+
+/**
+ * The id that `createCloudflareText` takes for an AI Gateway catalog model:
+ * `anthropic/...` and `openai/...` for the models without a vendor, the
+ * catalog id for the rest.
+ */
+function gatewayId(record: ModelRecord) {
+  if (record.id.includes('/')) return record.id
+  return record.api === 'anthropic-messages'
+    ? `anthropic/${record.id}`
+    : `openai/${record.id}`
+}
+
+/** Sorted by id, the newest version of each family first. */
+const newestFirst = (a: ModelEntry, b: ModelEntry) =>
+  b.id.localeCompare(a.id, 'en', { numeric: true })
+
+/**
+ * The models `/model` can switch to, from the `@tanstack/ai-models` catalog:
+ * the Workers AI models, and the AI Gateway models (Claude, GPT, Grok, Qwen,
+ * and more). The catalog gives the context size, the reasoning levels, and
+ * the price. The gateway models are by vendor in the picker.
+ */
+export const modelProviders = [
+  {
+    id: 'workers-ai',
+    label: 'Workers AI',
+    byVendor: false,
+    models: getModels('cloudflare-workers-ai')
+      .map((record) => cloudflareModel(record.id, record))
+      .sort(newestFirst),
+  },
+  {
+    id: 'ai-gateway',
+    label: 'AI Gateway',
+    byVendor: true,
+    // The `workers-ai/...` routes are the Workers AI models again.
+    models: getModels('cloudflare-ai-gateway')
+      .filter((record) => !record.id.startsWith('workers-ai/'))
+      .map((record) => cloudflareModel(gatewayId(record), record))
+      .sort(newestFirst),
+  },
+]
+
+/** Each model by its id: its catalog record and its adapter. */
+export const modelInfo: Record<string, ModelEntry> = Object.fromEntries(
+  modelProviders.flatMap((provider) =>
+    provider.models.map((model) => [model.id, model]),
+  ),
+)
+
+// A new session starts on Claude Sonnet through the gateway. A resumed session
+// keeps the model it had. `/model demo` answers without any key.
+const startModel = 'anthropic/claude-sonnet-5'
+// The start model: the harness, /compact, /goal, and /agent haiku use it.
+const main: KeyedAdapter<AnyTextAdapter> = modelInfo[startModel].adapter
+const choices = {
+  ...Object.fromEntries(
+    Object.values(modelInfo).map((model) => [model.id, model.adapter]),
+  ),
+  demo: demoModel(),
+}
+
+/** Does the model think, so `/effort` changes it? */
+export function reasons(model: string) {
+  const record = modelInfo[model]?.record
+  return record
+    ? supportedReasoningLevels(record).some((level) => level !== 'off')
+    : false
+}
+
+// `/connect cloudflare` opens the page to make a token, then asks for it (the
+// screen hides it as you type), finds your account, and asks for the gateway.
+export const keyProviders = [cloudflareByok]
+
+/** Is `command` on the PATH? Checks the Windows extensions too. */
+function onPath(command: string) {
+  const extensions =
+    process.platform === 'win32'
+      ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';')
+      : ['']
+  return (process.env.PATH ?? '')
+    .split(delimiter)
+    .some((dir) =>
+      extensions.some((extension) =>
+        existsSync(join(dir, `${command}${extension.toLowerCase()}`)),
+      ),
+    )
+}
+
+/**
+ * A top-level setting of your ~/.codex/config.toml (the lines before the
+ * first `[section]`), so the example runs Codex the way you set it up.
+ */
+function codexSetting(key: string) {
+  const config = join(homedir(), '.codex', 'config.toml')
+  if (!existsSync(config)) return undefined
+  const [topLevel = ''] = readFileSync(config, 'utf8').split(/^\s*\[/m)
+  return new RegExp(`^\\s*${key}\\s*=\\s*"([^"]+)"`, 'm').exec(topLevel)?.[1]
+}
+
+const CODEX_SANDBOX_MODES = [
+  'read-only',
+  'workspace-write',
+  'danger-full-access',
+] as const
+
+/**
+ * The Codex sandbox: CODEX_SANDBOX_MODE, else `sandbox_mode` in your Codex
+ * config, else workspace-write. On Windows, workspace-write can block the
+ * folder (Access is denied).
+ */
+function codexSandbox() {
+  const mode = process.env.CODEX_SANDBOX_MODE ?? codexSetting('sandbox_mode')
+  return (
+    CODEX_SANDBOX_MODES.find((known) => known === mode) ?? 'workspace-write'
+  )
+}
+
+/** A typed agent you can run with `/agent haiku {"topic":"rain"}`. */
+const haiku = defineAgent({
+  name: 'haiku',
+  description: 'Writes a haiku about a topic',
+  inputSchema: z.object({ topic: z.string() }),
+  run: async (ctx) =>
+    ctx.chat({
+      adapter: await ctx.keys.adapter(main),
+      messages: [
+        {
+          role: 'user',
+          content: `Write one haiku about ${ctx.input.topic}. Only the haiku.`,
+        },
+      ],
+      stream: false,
+    }),
+})
+
+// The model calls the media agents as tools, and the harness keeps each file
+// they make: images and speech with Workers AI, through your gateway.
+const media = [imageAgent, speechAgent]
+
+// Notion and Linear through their MCP servers. `/connect notion` signs in
+// through the browser. No app setup or API key is needed.
+const notion = mcpConnector({
+  id: 'notion',
+  label: 'Notion',
+  url: 'https://mcp.notion.com/mcp',
+})
+const linear = mcpConnector({
+  id: 'linear',
+  label: 'Linear',
+  url: 'https://mcp.linear.app/mcp',
+})
+
+// The lead model can hand coding work to your local Claude Code and Codex.
+// Each one turns on when its CLI is on the PATH (CODING_AGENTS=0 turns both
+// off). They work in your folder with your own `claude login` and
+// `codex login`, so the API keys are removed from their processes.
+const useCodingAgents = process.env.CODING_AGENTS !== '0'
+const codingAgentList: Record<string, CodingAgentConfig> = {}
+if (useCodingAgents && onPath('claude')) {
+  codingAgentList.claude_code = {
+    adapter: claudeCodeText('claude-opus-4-8', {
+      authMode: 'host',
+      permissionMode: 'acceptEdits',
+    }),
+    description:
+      'Claude Code, the local coding agent. Larger changes, refactors, and reviews in the workspace.',
+  }
+}
+if (useCodingAgents && onPath('codex')) {
+  codingAgentList.codex = {
+    // A ChatGPT login supports only some models, so the model and the sandbox
+    // come from your Codex config unless CODEX_MODEL or CODEX_SANDBOX_MODE is
+    // set.
+    adapter: codexText(
+      process.env.CODEX_MODEL ?? codexSetting('model') ?? 'gpt-5.3-codex',
+      {
+        authMode: 'host',
+        sandboxMode: codexSandbox(),
+        approvalPolicy: 'never',
+      },
+    ),
+    description:
+      'Codex, the local coding agent. Quick fixes, scripts, and tests in the workspace.',
+  }
+}
+const coding =
+  Object.keys(codingAgentList).length > 0
+    ? [
+        codingAgents({
+          sandbox: defineSandbox({
+            id: 'workspace',
+            provider: localProcessSandbox({
+              dir: root,
+              scrubEnv: ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY'],
+            }),
+            workspace: defineWorkspace({ source: localSource(root) }),
+          }),
+          agents: codingAgentList,
+        }),
+      ]
+    : []
+
+const tools = [
+  ...media.map((agent) => agent.name),
+  ...Object.keys(codingAgentList),
+]
+
+/**
+ * A feature that a key for any one of `providers` turns on. `on` is the
+ * state at startup, from the env vars only. The screen follows the saved
+ * keys live.
+ */
+function keyFeature(
+  name: string,
+  providers: Array<ByokProvider>,
+  needs: string,
+) {
+  return {
+    name,
+    on: providers.some(hasEnvKey),
+    needs,
+    providers: providers.map((provider) => provider.id),
+  }
+}
+
+/**
+ * What this session can do, and what turns each one on, for the screen.
+ * `providers` are the ids of the key providers a feature needs (any one).
+ */
+export const features = [
+  keyFeature(
+    'voice',
+    [cloudflareByok],
+    'your Cloudflare account (/connect cloudflare), and ffmpeg',
+  ),
+  keyFeature(
+    'images',
+    [cloudflareByok],
+    'your Cloudflare account (/connect cloudflare)',
+  ),
+  keyFeature(
+    'speech',
+    [cloudflareByok],
+    'your Cloudflare account (/connect cloudflare)',
+  ),
+  {
+    name: 'claude code',
+    on: 'claude_code' in codingAgentList,
+    needs: '`claude` on the PATH',
+    providers: [],
+  },
+  {
+    name: 'codex',
+    on: 'codex' in codingAgentList,
+    needs: '`codex` on the PATH',
+    providers: [],
+  },
+  { name: 'notion', on: true, needs: '', providers: [] },
+  { name: 'linear', on: true, needs: '', providers: [] },
+]
+
+export const assistant = defineHarness({
+  name: 'example/coder',
+  description:
+    'A coding agent in the terminal, on Cloudflare: files, voice, media, Notion, Linear, and local coding agents',
+  adapter: main,
+  systemPrompts: [
+    'You are a careful coding agent that works in the workspace, the folder where the user started you. Read files before you edit them. Keep answers short.',
+    `Your agent tools: ${tools.join(', ') || 'none'}. The user gets each file a media tool makes, so do not paste file contents or links.`,
+    'When the user asks to run Codex or Claude Code (by voice too: "run a Codex agent"), call that tool with a clear task, then give its answer back in a few lines.',
+    'The user can send files and voice messages.',
+    'You can read Notion and Linear when they are connected. If a tool says to sign in or that a key is missing, tell the user the /connect command it names, for example /connect notion or /connect cloudflare.',
+  ],
+  agents: [haiku],
+  subagents: { agents: media },
+  plugins: () => [
+    notion,
+    linear,
+    permissions(),
+    workspaceTools({ root, outside: 'ask' }),
+    todos(),
+    cloudflareConnect(),
+    modelPicker({ choices, default: startModel }),
+    effortPicker({ reasons }),
+    projectInstructions({ root }),
+    compact({ adapter: main }),
+    usage(),
+    // /goal keeps the agent working until the main model says the goal is met.
+    goal({ judge: main }),
+    // Skills: each folder holds skill folders with a SKILL.md. Each skill is a
+    // /<name> command, and the model sees the list. A skill you add while the
+    // app runs shows at once. The repo folders (where you run the app) win
+    // over the global one. A skill named like a screen command is
+    // /skill:<name>.
+    skills({
+      dirs: ['./.agents/skills', './.claude/skills', join(SAVE_DIR, 'skills')],
+      reserved: SCREEN_COMMANDS.map((command) => command.name),
+    }),
+    // Read-only tools (file reads, read-only Notion and Linear tools) move
+    // behind execute_typescript, so the model can call several in one program.
+    // The tools are lazy: the model gets their names, asks discover_tools for
+    // the signatures it needs, then calls them in the program. The program
+    // runs in a new isolate in your Worker (/code-mode), and its tool calls
+    // come back here to run.
+    codeMode({
+      driver: createCloudflareIsolateDriver({
+        workerUrl: `${currentWorker().url.replace(/\/+$/, '')}/code-mode`,
+        authorization: `Bearer ${currentWorker().secret}`,
+      }),
+      lazy: true,
+      lazyToolsConfig: { includeDescription: 'first-sentence' },
+    }),
+    ...coding,
+  ],
+})
diff --git a/examples/harness-cli-cloudflare/src/marked-terminal.d.ts b/examples/harness-cli-cloudflare/src/marked-terminal.d.ts
new file mode 100644
index 0000000000..aa3a2469a8
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/marked-terminal.d.ts
@@ -0,0 +1,10 @@
+// marked-terminal has no types of its own. This is the one function the
+// screen uses.
+declare module 'marked-terminal' {
+  import type { MarkedExtension } from 'marked'
+
+  export function markedTerminal(
+    options?: Record<string, unknown>,
+    highlightOptions?: Record<string, unknown>,
+  ): MarkedExtension
+}
diff --git a/examples/harness-cli-cloudflare/src/media.ts b/examples/harness-cli-cloudflare/src/media.ts
new file mode 100644
index 0000000000..46019edbb3
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/media.ts
@@ -0,0 +1,69 @@
+import { defineAgent, keyedAdapter } from '@tanstack/ai'
+import {
+  createCloudflareImage,
+  createCloudflareTTS,
+} from '@tanstack/ai-cloudflare'
+import { cloudflareByok } from '@tanstack/ai-cloudflare/byok'
+import { z } from 'zod'
+import { cloudflareRest } from './cloudflare-connect'
+
+// Every agent here returns a short text. The harness keeps each file it makes
+// and publishes a `harness.media` event, so the screen can show and save it.
+//
+// Each agent builds its Workers AI model just before the call, with your
+// Cloudflare token and account, through your AI Gateway. Without them, the
+// call stops, and the screen says to run /connect cloudflare.
+const flux = keyedAdapter(cloudflareByok, (token) =>
+  createCloudflareImage(
+    '@cf/black-forest-labs/flux-1-schnell',
+    cloudflareRest(token),
+  ),
+)
+const aura = keyedAdapter(cloudflareByok, (token) =>
+  createCloudflareTTS('@cf/deepgram/aura-2-en', cloudflareRest(token)),
+)
+
+/** Makes an image with Workers AI (FLUX.1 schnell). */
+export const imageAgent = defineAgent({
+  name: 'image',
+  description:
+    'Generates one image from a detailed visual prompt. The user gets the image.',
+  produces: 'image',
+  inputSchema: z.object({
+    prompt: z.string().describe('A detailed description of the image'),
+  }),
+  run: async (ctx) => {
+    const result = await ctx.generateImage({
+      adapter: await ctx.keys.adapter(flux),
+      prompt: ctx.input.prompt,
+    })
+    if (result.images.length === 0)
+      throw new Error('The image model returned no image.')
+    return `Made the image with ${result.model}. The user has it.`
+  },
+})
+
+/** Reads a text aloud with Workers AI (Deepgram Aura 2). */
+export const speechAgent = defineAgent({
+  name: 'speech',
+  description:
+    'Reads a text aloud and makes an audio file of it (text to speech). The user gets the audio.',
+  produces: 'speech',
+  inputSchema: z.object({
+    text: z.string().describe('The exact words to say'),
+    voice: z
+      .string()
+      .optional()
+      .describe(
+        'An Aura voice, for example luna, orion, or thalia. Default: luna',
+      ),
+  }),
+  run: async (ctx) => {
+    const result = await ctx.generateSpeech({
+      adapter: await ctx.keys.adapter(aura),
+      text: ctx.input.text,
+      voice: ctx.input.voice ?? 'luna',
+    })
+    return `Read the text aloud with ${result.model}. The user has the audio.`
+  },
+})
diff --git a/examples/harness-cli-cloudflare/src/screen/commands.ts b/examples/harness-cli-cloudflare/src/screen/commands.ts
new file mode 100644
index 0000000000..a60f9f5270
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/screen/commands.ts
@@ -0,0 +1,23 @@
+/** The commands of the screen itself. The harness adds its own to the list. */
+export const SCREEN_COMMANDS = [
+  {
+    name: 'connect',
+    description: 'Connect Cloudflare, Notion, Linear, or a new Worker',
+  },
+  { name: 'disconnect', description: 'Remove a key or a sign-in' },
+  { name: 'model', description: 'Pick the model' },
+  { name: 'effort', description: 'Pick how hard the model thinks' },
+  { name: 'resume', description: 'Continue a saved session' },
+  { name: 'mic', description: 'Pick the microphone' },
+  { name: 'open', description: 'Open a media file (default: the last one)' },
+  { name: 'play', description: 'Play an audio or video file' },
+  {
+    name: 'voice',
+    description: 'Send a recorded voice message: /voice note.m4a',
+  },
+  { name: 'help', description: 'Show the commands and the voice tips' },
+  { name: 'exit', description: 'Quit' },
+]
+
+// Commands that need text after the name: Enter in the list fills the name.
+export const TAKES_INPUT = new Set(['voice'])
diff --git a/examples/harness-cli-cloudflare/src/screen/editor.ts b/examples/harness-cli-cloudflare/src/screen/editor.ts
new file mode 100644
index 0000000000..50c033b608
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/screen/editor.ts
@@ -0,0 +1,133 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { useReducer, useRef } from 'react'
+import { SAVE_DIR } from '../worker-config'
+
+// The lines you sent, for the up and down arrows. They stay on this PC.
+const historyFile = join(SAVE_DIR, 'history.json')
+const HISTORY_SIZE = 200
+
+function loadHistory() {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(historyFile, 'utf8'))
+    return Array.isArray(parsed)
+      ? parsed.filter((item) => typeof item === 'string')
+      : []
+  } catch {
+    return []
+  }
+}
+
+function saveHistory(lines: ReadonlyArray<string>) {
+  try {
+    mkdirSync(dirname(historyFile), { recursive: true })
+    writeFileSync(historyFile, JSON.stringify(lines.slice(-HISTORY_SIZE)))
+  } catch {
+    // ponytail: history is a convenience. A failed write loses it, no more.
+  }
+}
+
+/** The input line. `hidden`: it holds a secret (a key), shown as dots. */
+export interface Line {
+  text: string
+  cursor: number
+  hidden: boolean
+}
+
+const empty: Line = { text: '', cursor: 0, hidden: false }
+
+/**
+ * The input line of the screen: typing at the cursor, the arrow keys, and
+ * the history of sent lines. The line is in a ref, so a key that comes
+ * before React renders still sees the keys before it.
+ */
+export function useLineEditor() {
+  const current = useRef<Line>(empty)
+  const [, render] = useReducer((count: number) => count + 1, 0)
+  const history = useRef<Array<string>>(loadHistory())
+  // While you go through the history: where you are, and the line you had.
+  const browsing = useRef<{ index: number; draft: string } | undefined>(
+    undefined,
+  )
+  const show = (line: Line) => {
+    current.current = line
+    render()
+  }
+  const edit = (line: Line) => {
+    browsing.current = undefined
+    show(line)
+  }
+  const showText = (text: string) =>
+    show({ text, cursor: text.length, hidden: false })
+
+  return {
+    get line() {
+      return current.current
+    },
+    /** The line came from the history (the arrows), not from typing. */
+    get browsing() {
+      return browsing.current !== undefined
+    },
+    /** Type or paste at the cursor. A hidden line stays hidden until it is empty. */
+    insert: (text: string, hidden = false) => {
+      const line = current.current
+      edit({
+        text:
+          line.text.slice(0, line.cursor) + text + line.text.slice(line.cursor),
+        cursor: line.cursor + text.length,
+        hidden: hidden || (line.hidden && line.text !== ''),
+      })
+    },
+    /** Delete the character before the cursor. */
+    backspace: () => {
+      const line = current.current
+      if (line.cursor === 0) return
+      edit({
+        ...line,
+        text:
+          line.text.slice(0, line.cursor - 1) + line.text.slice(line.cursor),
+        cursor: line.cursor - 1,
+      })
+    },
+    /** Move the cursor by `by` characters, or to the start or the end. */
+    move: (by: number | 'start' | 'end') => {
+      const line = current.current
+      const target =
+        by === 'start' ? 0 : by === 'end' ? line.text.length : line.cursor + by
+      show({ ...line, cursor: Math.max(0, Math.min(line.text.length, target)) })
+    },
+    /** Replace the line. The cursor goes to `cursor`, or to the end. */
+    set: (text: string, cursor = text.length) =>
+      edit({ text, cursor, hidden: false }),
+    clear: () => edit(empty),
+    /** Keep a sent line for the up arrow. */
+    remember: (text: string) => {
+      const trimmed = text.trim()
+      if (trimmed === '' || history.current.at(-1) === trimmed) return
+      history.current.push(trimmed)
+      saveHistory(history.current)
+    },
+    /** The up arrow: the sent line before the one shown. */
+    older: () => {
+      const lines = history.current
+      if (lines.length === 0) return
+      const at = browsing.current
+      const index = at ? Math.max(0, at.index - 1) : lines.length - 1
+      browsing.current = { index, draft: at?.draft ?? current.current.text }
+      showText(lines[index] ?? '')
+    },
+    /** The down arrow: the next sent line, then the line you had typed. */
+    newer: () => {
+      const at = browsing.current
+      if (!at) return
+      if (at.index >= history.current.length - 1) {
+        browsing.current = undefined
+        showText(at.draft)
+        return
+      }
+      const index = at.index + 1
+      browsing.current = { ...at, index }
+      showText(history.current[index] ?? '')
+    },
+  }
+}
diff --git a/examples/harness-cli-cloudflare/src/screen/footer.tsx b/examples/harness-cli-cloudflare/src/screen/footer.tsx
new file mode 100644
index 0000000000..89e1f0c0a9
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/screen/footer.tsx
@@ -0,0 +1,83 @@
+import { Box, Text } from 'ink'
+import { REASONING_LEVELS } from '@tanstack/ai'
+import { clampReasoningLevel } from '@tanstack/ai-models'
+import { useSelector } from '@tanstack/react-store'
+import { modelInfo, reasons } from '../harness'
+import { PROVIDER_KEYS, USAGE, providerKeysIn, usageIn } from './keys'
+import { ACCENT, compact } from './theme'
+import type { SessionView } from '@tanstack/ai-harness/view'
+
+const BAR = 10
+
+/**
+ * The status bar at the bottom: the model, how much of its context the
+ * conversation fills, and the tokens and model calls so far. It follows the
+ * session live. The features and the key hints are in the header.
+ */
+export function Footer({ view }: { view: SessionView }) {
+  const model = useSelector(view.store, (state) =>
+    String(state.config.find((entry) => entry.key === 'model')?.value ?? '?'),
+  )
+  const effort = useSelector(
+    view.store,
+    (state) => state.config.find((entry) => entry.key === 'effort')?.value,
+  )
+  // The plugin states themselves, so the bar renders only when they change.
+  const usageState = useSelector(view.store, (state) => state.plugins[USAGE])
+  const keysState = useSelector(
+    view.store,
+    (state) => state.plugins[PROVIDER_KEYS],
+  )
+  const usage = usageIn(usageState)
+  const keys = providerKeysIn(keysState)
+  const info = modelInfo[model]
+  const window = info?.record.contextWindow
+  // The level the model gets: the adapter moves an effort the model does not
+  // have to the nearest one it has.
+  const level = REASONING_LEVELS.find((name) => name === effort)
+  const shownEffort =
+    info && level && reasons(model)
+      ? clampReasoningLevel(info.record, level)
+      : undefined
+  const share = window ? Math.min(1, usage.contextTokens / window) : 0
+  const filled = Math.round(share * BAR)
+  const barColor = share > 0.8 ? 'red' : share > 0.5 ? 'yellow' : 'green'
+  const needsKey =
+    info !== undefined &&
+    keys.find((key) => key.id === info.provider)?.state === 'missing'
+  // Each group keeps its width, and a group that does not fit goes to the
+  // next line.
+  return (
+    <Box flexWrap="wrap" columnGap={3}>
+      <Box flexShrink={0}>
+        <Text color={needsKey ? 'red' : ACCENT} bold>{`◆ ${model}`}</Text>
+        {needsKey ? (
+          <Text color="red">{`  (run /connect ${info.provider})`}</Text>
+        ) : null}
+        {shownEffort ? <Text dimColor>{`  effort ${shownEffort}`}</Text> : null}
+      </Box>
+      <Box flexShrink={0}>
+        <Text dimColor>{'context '}</Text>
+        <Text>
+          {compact(usage.contextTokens)}
+          {window ? `/${compact(window)}` : ''}
+        </Text>
+        {window ? (
+          <>
+            <Text> </Text>
+            <Text color={barColor}>{'▰'.repeat(filled)}</Text>
+            <Text dimColor>{'▱'.repeat(BAR - filled)}</Text>
+            <Text dimColor>{` ${Math.round(share * 100)}%`}</Text>
+          </>
+        ) : null}
+      </Box>
+      <Box flexShrink={0}>
+        <Text dimColor>{'tokens in '}</Text>
+        <Text>{compact(usage.promptTokens)}</Text>
+        <Text dimColor>{' out '}</Text>
+        <Text>{compact(usage.completionTokens)}</Text>
+      </Box>
+      <Text dimColor>{`${usage.turns} model calls`}</Text>
+    </Box>
+  )
+}
diff --git a/examples/harness-cli-cloudflare/src/screen/keys.ts b/examples/harness-cli-cloudflare/src/screen/keys.ts
new file mode 100644
index 0000000000..e47e758b8b
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/screen/keys.ts
@@ -0,0 +1,81 @@
+import { CLOUDFLARE } from '../cloudflare-connect'
+import type { features } from '../harness'
+
+// The names of the `cloudflareConnect()` and `usage()` plugins: their state is
+// in the view's `state.plugins`. The Cloudflare state has the shape of a
+// `providerKeys()` state, with one provider: `cloudflare`.
+export const PROVIDER_KEYS = CLOUDFLARE
+export const USAGE = 'tanstack/usage'
+
+/** A key provider, and where its key comes from. */
+export interface ProviderKey {
+  id: string
+  label: string
+  state: 'connected' | 'env' | 'missing'
+}
+
+function isProviderKey(value: unknown): value is ProviderKey {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'id' in value &&
+    typeof value.id === 'string' &&
+    'label' in value &&
+    typeof value.label === 'string' &&
+    'state' in value &&
+    (value.state === 'connected' ||
+      value.state === 'env' ||
+      value.state === 'missing')
+  )
+}
+
+/**
+ * The providers in `saved`, the state of the Cloudflare plugin.
+ * `/connect` and `/disconnect` update it, so the screen shows the keys live.
+ * Empty before the plugin reports.
+ */
+export function providerKeysIn(saved: unknown) {
+  const isState =
+    typeof saved === 'object' && saved !== null && 'providers' in saved
+  if (!isState) return []
+  const { providers } = saved
+  return Array.isArray(providers) ? providers.filter(isProviderKey) : []
+}
+
+/**
+ * Is `feature` on? A feature that needs a key follows the saved keys: any
+ * one of its providers with a key turns it on. The rest stay as at startup.
+ */
+export function isOn(
+  feature: (typeof features)[number],
+  keys: ReadonlyArray<ProviderKey>,
+) {
+  const followsKeys = feature.providers.length > 0 && keys.length > 0
+  if (!followsKeys) return feature.on
+  return keys.some(
+    (key) => feature.providers.includes(key.id) && key.state !== 'missing',
+  )
+}
+
+/** The totals of the usage plugin. */
+export interface Usage {
+  turns: number
+  promptTokens: number
+  completionTokens: number
+  contextTokens: number
+}
+
+/** The usage plugin state in `saved`, with 0 for anything it has not counted. */
+export function usageIn(saved: unknown): Usage {
+  const read = (key: string) => {
+    if (typeof saved !== 'object' || saved === null || !(key in saved)) return 0
+    const value: unknown = Reflect.get(saved, key)
+    return typeof value === 'number' ? value : 0
+  }
+  return {
+    turns: read('turns'),
+    promptTokens: read('promptTokens'),
+    completionTokens: read('completionTokens'),
+    contextTokens: read('contextTokens'),
+  }
+}
diff --git a/examples/harness-cli-cloudflare/src/screen/markdown.ts b/examples/harness-cli-cloudflare/src/screen/markdown.ts
new file mode 100644
index 0000000000..dbc0772205
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/screen/markdown.ts
@@ -0,0 +1,64 @@
+import { renderMermaidASCII } from 'beautiful-mermaid'
+import { Marked } from 'marked'
+import { markedTerminal } from 'marked-terminal'
+
+// A closed ```mermaid block. An open one (still streaming) stays code.
+const MERMAID = /```mermaid[^\n]*\n([\s\S]*?)```/g
+
+// One parser for each width: marked-terminal wraps text to the width.
+const parsers = new Map<number, Marked>()
+function parserFor(width: number) {
+  let parser = parsers.get(width)
+  if (!parser) {
+    parser = new Marked(
+      markedTerminal({
+        width,
+        reflowText: true,
+        tab: 2,
+        emoji: false,
+        showSectionPrefix: false,
+      }),
+      {
+        renderer: {
+          // ponytail: marked-terminal 7 prints the text of a list item as it
+          // is, so `**bold**` in a list stays raw. This parses it.
+          text(token) {
+            return 'tokens' in token && token.tokens
+              ? this.parser.parseInline(token.tokens)
+              : token.text
+          },
+        },
+      },
+    )
+    parsers.set(width, parser)
+  }
+  return parser
+}
+
+/**
+ * Markdown as terminal text, `width` columns wide: headings, lists, tables,
+ * links, and highlighted code. A Mermaid block becomes a chart drawn in text.
+ * A chart that does not parse stays a code block.
+ */
+export function renderMarkdown(text: string, width: number) {
+  const charts: Array<string> = []
+  const source = text.replace(MERMAID, (block, code: string) => {
+    try {
+      charts.push(renderMermaidASCII(code))
+      // A plain word marked-terminal keeps as it is, in its own paragraph.
+      return `\n\nMERMAIDCHART${charts.length - 1}\n\n`
+    } catch {
+      return block
+    }
+  })
+  return (
+    parserFor(Math.max(20, width))
+      // An open (still streaming) Mermaid block shows as plain code.
+      .parse(source.replace(/```mermaid/g, '```'), { async: false })
+      .replace(
+        /MERMAIDCHART(\d+)/g,
+        (_match, index: string) => charts[Number(index)] ?? '',
+      )
+      .trimEnd()
+  )
+}
diff --git a/examples/harness-cli-cloudflare/src/screen/media.ts b/examples/harness-cli-cloudflare/src/screen/media.ts
new file mode 100644
index 0000000000..6222ed8a3c
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/screen/media.ts
@@ -0,0 +1,125 @@
+import { spawn } from 'node:child_process'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { basename, join, resolve } from 'node:path'
+import { useEffect, useState } from 'react'
+import { assistant } from '../harness'
+import type {
+  MediaPart,
+  SessionView,
+  ViewMessage,
+  ViewPart,
+} from '@tanstack/ai-harness/view'
+
+// ponytail: the CLI's default media folder, `./<harness-name>-media`. A custom
+// ui gets no `--media-dir`, and the CLI does not export `defaultMediaDir`, so
+// this copies its rule. The media id in front of the name keeps names unique.
+export const mediaDir = `${assistant.name.replace(/[^\w.-]+/g, '-').replace(/^[-.]+|-+$/g, '')}-media`
+
+/** A media file the screen saved. `number` is what `/open` and `/play` take. */
+export interface Saved {
+  id: string
+  number: number
+  kind: string
+  name: string
+  path?: string
+  error?: string
+}
+
+/** Write the bytes of a media file into `mediaDir`, and return the path. */
+async function saveMedia(part: MediaPart) {
+  await mkdir(mediaDir, { recursive: true })
+  const path = join(mediaDir, `${part.id}-${basename(part.name)}`)
+  await writeFile(path, await part.load())
+  return path
+}
+
+/** Add the media parts of `parts` to `into`, also the ones of child agents. */
+function collectMedia(parts: ReadonlyArray<ViewPart>, into: Array<MediaPart>) {
+  for (const part of parts) {
+    if (part.type === 'media') into.push(part)
+    if (part.type === 'agent') collectMedia(part.parts, into)
+  }
+}
+
+/** The media files that the agents made, from the assistant messages. */
+function generatedMedia(messages: ReadonlyArray<ViewMessage>) {
+  const media: Array<MediaPart> = []
+  for (const message of messages) {
+    if (message.role === 'assistant') collectMedia(message.parts, media)
+  }
+  return media
+}
+
+/**
+ * Save each new media file once, and number it. Files in the history when
+ * the screen opens are not saved again. `saving(id)`: is that file new, and
+ * neither saved nor failed yet?
+ */
+export function useSavedMedia(view: SessionView, messages: Array<ViewMessage>) {
+  const [saved, setSaved] = useState<ReadonlyArray<Saved>>([])
+  const [seen] = useState(
+    () =>
+      new Set(generatedMedia(view.store.get().messages).map((part) => part.id)),
+  )
+  useEffect(() => {
+    for (const part of generatedMedia(messages)) {
+      if (seen.has(part.id)) continue
+      seen.add(part.id)
+      const number = seen.size
+      const update = (change: Partial<Saved>) =>
+        setSaved((current) =>
+          current.map((item) =>
+            item.id === part.id ? { ...item, ...change } : item,
+          ),
+        )
+      setSaved((current) => [
+        ...current,
+        { id: part.id, number, kind: part.kind, name: part.name },
+      ])
+      saveMedia(part).then(
+        (path) => update({ path }),
+        (error: unknown) =>
+          update({
+            error: error instanceof Error ? error.message : String(error),
+          }),
+      )
+    }
+  }, [messages, seen])
+  const saving = (id: string) => {
+    if (!seen.has(id)) return true
+    const item = saved.find((entry) => entry.id === id)
+    return item !== undefined && !item.path && !item.error
+  }
+  return { saved, saving }
+}
+
+/** Start a program without a shell. The screen still shows the path on error. */
+function launch(command: string, args: Array<string>) {
+  const child = spawn(command, args, { stdio: 'ignore', detached: true })
+  child.on('error', () => {})
+  child.unref()
+}
+
+/** Open a link or a file with the default app. No shell is involved. */
+export function openExternal(target: string) {
+  if (process.platform === 'win32') {
+    // Not `cmd /c start`: cmd would read `&` in a URL as a command separator.
+    if (/^https?:\/\//.test(target))
+      launch('rundll32', ['url.dll,FileProtocolHandler', target])
+    else launch('explorer', [resolve(target)])
+    return
+  }
+  launch(process.platform === 'darwin' ? 'open' : 'xdg-open', [target])
+}
+
+/** Play audio or video with ffplay, which comes with ffmpeg. */
+export function play(item: Saved & { path: string }) {
+  const window = item.kind === 'video' ? [] : ['-nodisp']
+  launch(process.env.FFPLAY_PATH || 'ffplay', [
+    ...window,
+    '-autoexit',
+    '-loglevel',
+    'quiet',
+    item.path,
+  ])
+}
diff --git a/examples/harness-cli-cloudflare/src/screen/menu.tsx b/examples/harness-cli-cloudflare/src/screen/menu.tsx
new file mode 100644
index 0000000000..4f222f96df
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/screen/menu.tsx
@@ -0,0 +1,66 @@
+import { Box, Text } from 'ink'
+import { ACCENT } from './theme'
+
+/** One row of the command list or of a picker. */
+export interface MenuItem {
+  id: string
+  label: string
+  detail?: string
+  /** The current choice, for example the model in use. */
+  current?: boolean
+}
+
+const VISIBLE = 8
+
+/**
+ * A list you move through with the arrow keys: the `/` command list, or a
+ * picker such as `/connect` or `/model`. It shows at most 8 rows around the
+ * selected one.
+ */
+export function Menu({
+  title,
+  items,
+  selected,
+  hint,
+}: {
+  title?: string
+  items: ReadonlyArray<MenuItem>
+  selected: number
+  hint: string
+}) {
+  const start = Math.max(
+    0,
+    Math.min(selected - Math.floor(VISIBLE / 2), items.length - VISIBLE),
+  )
+  const shown = items.slice(start, start + VISIBLE)
+  const width = Math.max(...items.map((item) => item.label.length), 8)
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor="gray"
+      paddingX={1}
+    >
+      {title ? <Text bold>{title}</Text> : null}
+      {shown.map((item, index) => {
+        const isSelected = start + index === selected
+        return (
+          <Box key={item.id}>
+            <Box flexShrink={0}>
+              <Text color={isSelected ? ACCENT : undefined} bold={isSelected}>
+                {`${isSelected ? '❯' : ' '} ${item.label.padEnd(width)}`}
+              </Text>
+            </Box>
+            <Text color={item.current ? 'green' : 'gray'} wrap="truncate-end">
+              {`  ${item.current ? '● ' : ''}${item.detail ?? ''}`}
+            </Text>
+          </Box>
+        )
+      })}
+      {items.length > VISIBLE ? (
+        <Text dimColor>{`  ${selected + 1} of ${items.length}`}</Text>
+      ) : null}
+      <Text dimColor>{hint}</Text>
+    </Box>
+  )
+}
diff --git a/examples/harness-cli-cloudflare/src/screen/parts.tsx b/examples/harness-cli-cloudflare/src/screen/parts.tsx
new file mode 100644
index 0000000000..7c805be797
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/screen/parts.tsx
@@ -0,0 +1,290 @@
+import { basename } from 'node:path'
+import { useMemo } from 'react'
+import { Box, Spacer, Text, useAnimation } from 'ink'
+import { renderMarkdown } from './markdown'
+import { ACCENT, KIND_COLOR, SPINNER } from './theme'
+import type {
+  AgentPart,
+  MediaPart,
+  ToolCallPart,
+  ViewMessage,
+  ViewPart,
+} from '@tanstack/ai-harness/view'
+import type { Saved } from './media'
+
+export function Spinner({ color = 'yellow' }: { color?: string }) {
+  const { frame } = useAnimation({ interval: 90 })
+  return <Text color={color}>{SPINNER[frame % SPINNER.length]}</Text>
+}
+
+function textOf(parts: ReadonlyArray<ViewPart>) {
+  return parts.map((part) => (part.type === 'text' ? part.text : '')).join('')
+}
+
+/** A short one-line view of tool arguments. */
+function argsPreview(call: ToolCallPart) {
+  const text =
+    typeof call.args === 'object' && call.args !== null
+      ? Object.values(call.args)
+          .filter((value) => typeof value === 'string')
+          .join(', ')
+      : ''
+  const line = text.replace(/\s+/g, ' ').trim()
+  return line.length > 70 ? `${line.slice(0, 70)}...` : line
+}
+
+function ToolLine({
+  call,
+  indent = 2,
+}: {
+  call: ToolCallPart
+  indent?: number
+}) {
+  const icon =
+    call.status === 'running' ? (
+      <Spinner />
+    ) : call.status === 'done' ? (
+      <Text color="green">✓</Text>
+    ) : call.status === 'failed' ? (
+      <Text color="red">✗</Text>
+    ) : (
+      <Text color="magenta">?</Text>
+    )
+  const preview = argsPreview(call)
+  return (
+    <Box marginLeft={indent}>
+      {icon}
+      <Text color="yellow">{` ${call.name}`}</Text>
+      {preview ? <Text dimColor>{`  ${preview}`}</Text> : null}
+      {call.status === 'needs-approval' ? (
+        <Text color="magenta"> waits for your approval</Text>
+      ) : null}
+    </Box>
+  )
+}
+
+function MediaLine({
+  part,
+  saved,
+  indent = 2,
+}: {
+  part: MediaPart
+  saved: ReadonlyArray<Saved>
+  indent?: number
+}) {
+  const item = saved.find((entry) => entry.id === part.id)
+  const color = KIND_COLOR[part.kind] ?? 'white'
+  return (
+    <Box marginLeft={indent}>
+      <Text color={color} bold>
+        {`▣ ${item ? `${item.number} ` : ''}${part.kind}`}
+      </Text>
+      <Text>{`  ${part.name}`}</Text>
+      {item?.path ? <Text dimColor>{`  -> ${item.path}`}</Text> : null}
+      {item?.error ? (
+        <Text color="red">{`  not saved: ${item.error}`}</Text>
+      ) : null}
+      {item && !item.path && !item.error ? (
+        <Text dimColor> saving...</Text>
+      ) : null}
+    </Box>
+  )
+}
+
+/**
+ * A child agent, for example Codex or Claude Code, in its own card: its
+ * status, its last tool calls, its media, and its output. While it runs, the
+ * last 4 lines show. When it ends, the last 15 lines of its answer stay.
+ */
+function Agent({
+  part,
+  saved,
+}: {
+  part: AgentPart
+  saved: ReadonlyArray<Saved>
+}) {
+  const lines = textOf(part.parts)
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim() !== '')
+  const running = part.status === 'running'
+  const output = running ? lines.slice(-4) : lines.slice(-15)
+  const calls = part.parts.flatMap((inner) =>
+    inner.type === 'tool-call' ? [inner] : [],
+  )
+  const media = part.parts.flatMap((inner) =>
+    inner.type === 'media' ? [inner] : [],
+  )
+  const color = part.status === 'failed' ? 'red' : running ? 'yellow' : 'green'
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={color}
+      paddingX={1}
+      marginLeft={2}
+    >
+      <Box>
+        {running ? (
+          <Spinner color={color} />
+        ) : (
+          <Text color={color}>{part.status === 'done' ? '✓' : '✗'}</Text>
+        )}
+        <Text bold>{` ${part.name}`}</Text>
+        <Spacer />
+        <Text color={color}>{part.status}</Text>
+      </Box>
+      {calls.slice(-4).map((call) => (
+        <ToolLine key={call.id} call={call} indent={0} />
+      ))}
+      {media.map((inner) => (
+        <MediaLine key={inner.id} part={inner} saved={saved} indent={0} />
+      ))}
+      {output.map((line, index) => (
+        <Text key={`line-${index}`} dimColor={running}>
+          {line}
+        </Text>
+      ))}
+      {part.error ? <Text color="red">{part.error}</Text> : null}
+    </Box>
+  )
+}
+
+/** The model's text as markdown, `width` columns wide. */
+function Markdown({ text, width }: { text: string; width: number }) {
+  const shown = useMemo(() => renderMarkdown(text, width), [text, width])
+  return (
+    <Box marginLeft={2}>
+      <Text>{shown}</Text>
+    </Box>
+  )
+}
+
+function Part({
+  part,
+  saved,
+  width,
+}: {
+  part: ViewPart
+  saved: ReadonlyArray<Saved>
+  width: number
+}) {
+  switch (part.type) {
+    case 'text':
+      return <Markdown text={part.text} width={width - 2} />
+    case 'reasoning':
+      return (
+        <Box marginLeft={2}>
+          <Text dimColor italic>
+            {part.text}
+          </Text>
+        </Box>
+      )
+    case 'tool-call':
+      return <ToolLine call={part} />
+    case 'agent':
+      return <Agent part={part} saved={saved} />
+    case 'media':
+      return <MediaLine part={part} saved={saved} />
+  }
+}
+
+export function Message({
+  message,
+  saved,
+  width,
+}: {
+  message: ViewMessage
+  saved: ReadonlyArray<Saved>
+  /** The terminal width, for the markdown of the model's text. */
+  width: number
+}) {
+  switch (message.role) {
+    case 'user': {
+      // A voice message names its files as `@"path"`, shown as a file badge.
+      const named: Array<string> = []
+      const text = message.text
+        .replace(/@"([^"]+)"/g, (_match, path: string) => {
+          named.push(basename(path))
+          return ''
+        })
+        .trim()
+      const files = [
+        ...(message.media ?? []).map((part) => `${part.kind} ${part.name}`),
+        ...named,
+      ]
+      return (
+        <Box marginTop={1} flexWrap="wrap">
+          <Text bold>
+            <Text color={ACCENT}>❯ </Text>
+            {text}
+            {files.length > 0 ? ' ' : ''}
+          </Text>
+          {files.map((file) => (
+            <Text key={file} color="black" backgroundColor={ACCENT}>
+              {` ${file} `}
+            </Text>
+          ))}
+        </Box>
+      )
+    }
+    case 'notice': {
+      const isError = message.kind === 'error'
+      // A command's answer, for example "Connected to Notion.", stands out.
+      const done =
+        message.kind === 'command' &&
+        /^(Connected|Disconnected|Model|Effort)\b/.test(message.text)
+      return (
+        <Box marginLeft={2}>
+          <Text color={isError ? 'red' : done ? 'green' : 'gray'} bold={done}>
+            {`${isError ? '✗' : done ? '✓' : '·'} ${message.text}`}
+          </Text>
+        </Box>
+      )
+    }
+    case 'assistant':
+      return (
+        <Box flexDirection="column" marginTop={1}>
+          {message.parts.map((part, index) => (
+            <Part key={index} part={part} saved={saved} width={width} />
+          ))}
+        </Box>
+      )
+  }
+}
+
+/** Does a part still change: a running tool or agent, or media still saving? */
+function isLivePart(part: ViewPart, saving: (id: string) => boolean): boolean {
+  if (part.type === 'tool-call')
+    return part.status === 'running' || part.status === 'needs-approval'
+  if (part.type === 'agent')
+    return (
+      part.status === 'running' ||
+      part.parts.some((inner) => isLivePart(inner, saving))
+    )
+  return part.type === 'media' && saving(part.id)
+}
+
+/**
+ * How many messages from the start no longer change. The screen prints them
+ * once, above the live area, so a long conversation does not redraw.
+ * `running`: a turn streams now, so the last assistant message can still
+ * grow. The screen never takes back a printed message, so holding the one of
+ * the turn before costs nothing.
+ */
+export function settledCount(
+  messages: ReadonlyArray<ViewMessage>,
+  saving: (id: string) => boolean,
+  running: boolean,
+) {
+  const lastAssistant = messages
+    .map((message) => message.role)
+    .lastIndexOf('assistant')
+  for (const [index, message] of messages.entries()) {
+    if (message.role !== 'assistant') continue
+    const streaming = running && index === lastAssistant
+    if (streaming || message.parts.some((part) => isLivePart(part, saving)))
+      return index
+  }
+  return messages.length
+}
diff --git a/examples/harness-cli-cloudflare/src/screen/paths.ts b/examples/harness-cli-cloudflare/src/screen/paths.ts
new file mode 100644
index 0000000000..0f1bc779c2
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/screen/paths.ts
@@ -0,0 +1,72 @@
+import { readdirSync } from 'node:fs'
+import { resolve } from 'node:path'
+import type { Line } from './editor'
+import type { MenuItem } from './menu'
+
+/**
+ * An `@path` that is being typed, just before the cursor: an `@` at the
+ * start or after white space, then a quoted path that is not closed yet
+ * (`@"my ca`), or the text up to the cursor. runCli attaches the same tokens.
+ */
+const TYPING = /(^|\s)@(?:"([^"]*)|([^\s"]*))$/
+
+/** A file or a folder in the `@` list. `fill` replaces the typed token. */
+export interface PathItem extends MenuItem {
+  fill: string
+}
+
+/**
+ * The files and folders that the `@path` before the cursor can name, from
+ * the working folder, where runCli finds the files it attaches. Folders
+ * come first. Hidden files show only when the typed name starts with a dot.
+ * `start` is where the token starts in the line. `undefined` when no token
+ * is typed, nothing matches, or the token already names a file.
+ * ponytail: one folder read, at most 100 entries.
+ */
+export function pathSuggestions(line: Line, cwd = process.cwd()) {
+  const match = TYPING.exec(line.text.slice(0, line.cursor))
+  if (!match) return undefined
+  const quoted = match[2] !== undefined
+  const typed = match[2] ?? match[3] ?? ''
+  const dir = typed.slice(0, typed.lastIndexOf('/') + 1)
+  const name = typed.slice(dir.length).toLowerCase()
+  let entries
+  try {
+    entries = readdirSync(resolve(cwd, dir || '.'), { withFileTypes: true })
+  } catch {
+    return undefined
+  }
+  const items = entries
+    .filter(
+      (entry) =>
+        entry.name.toLowerCase().startsWith(name) &&
+        (name.startsWith('.') || !entry.name.startsWith('.')),
+    )
+    .sort(
+      (a, b) =>
+        Number(b.isDirectory()) - Number(a.isDirectory()) ||
+        a.name.localeCompare(b.name),
+    )
+    .slice(0, 100)
+    .map((entry): PathItem => {
+      const folder = entry.isDirectory()
+      const path = `${dir}${entry.name}${folder ? '/' : ''}`
+      // A path with a space needs quotes. A folder stays open, so the next
+      // name can follow it. A file ends the token with a space.
+      const fill =
+        quoted || /\s/.test(path)
+          ? `@"${path}${folder ? '' : '" '}`
+          : `@${path}${folder ? '' : ' '}`
+      return {
+        id: path,
+        label: path,
+        fill,
+        ...(folder ? { detail: 'folder' } : {}),
+      }
+    })
+  const [only] = items
+  if (items.length === 0 || (items.length === 1 && only?.id === typed)) {
+    return undefined
+  }
+  return { start: match.index + (match[1] ?? '').length, items }
+}
diff --git a/examples/harness-cli-cloudflare/src/screen/splash.tsx b/examples/harness-cli-cloudflare/src/screen/splash.tsx
new file mode 100644
index 0000000000..8d059e28a2
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/screen/splash.tsx
@@ -0,0 +1,150 @@
+import { useEffect, useState } from 'react'
+import { Box, Text, render, useApp, useInput, useWindowSize } from 'ink'
+import { ACCENT } from './theme'
+import type { RenderOptions } from 'ink'
+
+// The block letters, 6 rows each. All rows of a letter have one width.
+const LETTERS: Record<string, Array<string>> = {
+  T: [
+    '████████╗',
+    '╚══██╔══╝',
+    '   ██║   ',
+    '   ██║   ',
+    '   ██║   ',
+    '   ╚═╝   ',
+  ],
+  A: [' █████╗ ', '██╔══██╗', '███████║', '██╔══██║', '██║  ██║', '╚═╝  ╚═╝'],
+  N: [
+    '███╗   ██╗',
+    '████╗  ██║',
+    '██╔██╗ ██║',
+    '██║╚██╗██║',
+    '██║ ╚████║',
+    '╚═╝  ╚═══╝',
+  ],
+  S: ['███████╗', '██╔════╝', '███████╗', '╚════██║', '███████║', '╚══════╝'],
+  C: [' ██████╗', '██╔════╝', '██║     ', '██║     ', '╚██████╗', ' ╚═════╝'],
+  K: ['██╗  ██╗', '██║ ██╔╝', '█████╔╝ ', '██╔═██╗ ', '██║  ██╗', '╚═╝  ╚═╝'],
+  I: ['██╗', '██║', '██║', '██║', '██║', '╚═╝'],
+}
+
+/** "TANSTACK AI" in block letters, one string for each row. */
+const BIG = Array.from({ length: 6 }, (_, row) =>
+  ['TANSTACK', 'AI']
+    .map((word) =>
+      [...word].map((letter) => LETTERS[letter]?.[row] ?? '').join(''),
+    )
+    .join('   '),
+)
+const SMALL = ['◆ TanStack AI']
+const TAGLINE = 'H A R N E S S   O N   C L O U D F L A R E'
+
+const SHADOW = new Set([...'╗║╝═╔╚'])
+// The cream for the light, and a darker step of the orange for the shadow of
+// the letters.
+const CREAM = '#eeebd4'
+const DEEP = '#8a4510'
+
+// The timeline, in milliseconds: the letters wipe in, a light sweeps over
+// them, and the tagline types in. Then the splash ends.
+const REVEAL = 600
+const SHINE = 500
+const END = 1700
+
+const easeOut = (x: number) => 1 - (1 - Math.min(1, Math.max(0, x))) ** 3
+
+/** One row of letters, cut into runs of one color. */
+function Row(props: {
+  text: string
+  shown: number
+  light: number
+  revealing: boolean
+}) {
+  const { text, shown, light, revealing } = props
+  const runs: Array<{ color: string | undefined; text: string }> = []
+  for (const [column, char] of [...text].entries()) {
+    const visible = column < shown && char !== ' '
+    const lit =
+      Math.abs(column - light) < 3 || (revealing && column >= shown - 2)
+    const color = !visible
+      ? undefined
+      : lit
+        ? CREAM
+        : SHADOW.has(char)
+          ? DEEP
+          : ACCENT
+    const shownChar = column < shown ? char : ' '
+    const last = runs.at(-1)
+    if (last && last.color === color) last.text += shownChar
+    else runs.push({ color, text: shownChar })
+  }
+  return (
+    <Text>
+      {runs.map((run, index) => (
+        <Text key={index} color={run.color}>
+          {run.text}
+        </Text>
+      ))}
+    </Text>
+  )
+}
+
+function Splash() {
+  const { exit } = useApp()
+  const { columns, rows } = useWindowSize()
+  const [elapsed, setElapsed] = useState(0)
+  useEffect(() => {
+    const start = Date.now()
+    const timer = setInterval(() => {
+      const now = Date.now() - start
+      setElapsed(now)
+      if (now >= END) exit()
+    }, 33)
+    return () => clearInterval(timer)
+  }, [])
+  // Any key skips the splash.
+  useInput(() => exit())
+
+  const lines = columns >= (BIG[0]?.length ?? 0) + 4 ? BIG : SMALL
+  const width = lines[0]?.length ?? 0
+  const shown = Math.ceil(width * easeOut(elapsed / REVEAL))
+  const light =
+    elapsed < REVEAL ? -10 : -6 + (width + 12) * ((elapsed - REVEAL) / SHINE)
+  const typed = Math.round(
+    TAGLINE.length * easeOut((elapsed - REVEAL * 0.8) / 500),
+  )
+  // One line shorter than the screen, so Ink does not redraw it all.
+  return (
+    <Box
+      width={columns}
+      height={Math.max(1, rows - 1)}
+      flexDirection="column"
+      alignItems="center"
+      justifyContent="center"
+    >
+      {lines.map((line, index) => (
+        <Row
+          key={index}
+          text={line}
+          shown={shown}
+          light={light}
+          revealing={elapsed < REVEAL}
+        />
+      ))}
+      <Box marginTop={1}>
+        <Text color={CREAM}>
+          {TAGLINE.slice(0, typed).padEnd(TAGLINE.length)}
+        </Text>
+      </Box>
+    </Box>
+  )
+}
+
+/**
+ * The boot animation: TanStack AI in block letters, for about 1.7 seconds.
+ * A key skips it. A narrow screen gets one line of text instead.
+ */
+export async function showSplash(io: RenderOptions = {}) {
+  const app = render(<Splash />, io)
+  await app.waitUntilExit()
+}
diff --git a/examples/harness-cli-cloudflare/src/screen/status.tsx b/examples/harness-cli-cloudflare/src/screen/status.tsx
new file mode 100644
index 0000000000..cd2fca880b
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/screen/status.tsx
@@ -0,0 +1,99 @@
+import { Box, Text, useAnimation } from 'ink'
+import { useSelector } from '@tanstack/react-store'
+import { selectGoal } from '@tanstack/ai-harness/plugins'
+import { Spinner } from './parts'
+import type { SessionView } from '@tanstack/ai-harness/view'
+import type { Recording } from '../voice'
+
+export type VoiceState = 'idle' | 'starting' | 'recording' | 'transcribing'
+
+/** A live level meter from the microphone loudness (0 to 32768). */
+function LevelMeter({ recording }: { recording: Recording }) {
+  const { time } = useAnimation({ interval: 80 })
+  const level = recording.level()
+  // Map loudness to 0..1 on a log scale: -60 dB is empty, 0 dB is full.
+  const decibels = 20 * Math.log10(Math.max(level, 1) / 32768)
+  const filled = Math.round(Math.min(1, Math.max(0, (decibels + 60) / 60)) * 16)
+  const seconds = Math.floor(time / 1000)
+  const clock = `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`
+  return (
+    <Box>
+      <Text color="red" bold>{`● REC ${clock}  `}</Text>
+      <Text color={filled > 9 ? 'green' : filled > 4 ? 'yellow' : 'gray'}>
+        {'▮'.repeat(filled)}
+      </Text>
+      <Text dimColor>{'▯'.repeat(16 - filled)}</Text>
+      <Text dimColor>{`  ${recording.microphone}`}</Text>
+    </Box>
+  )
+}
+
+/** What waits for the user or runs now: sign-ins, approvals, voice, the turn. */
+export function Status({
+  view,
+  voice,
+  recording,
+}: {
+  view: SessionView
+  voice: VoiceState
+  recording: Recording | undefined
+}) {
+  const status = useSelector(view.store, (state) => state.status)
+  const approvals = useSelector(view.store, (state) => state.approvals)
+  const question = useSelector(view.store, (state) => state.questions.at(0))
+  const signIns = useSelector(view.store, (state) => state.signIns)
+  const goal = useSelector(view.store, selectGoal)
+  return (
+    <Box flexDirection="column" marginTop={1}>
+      {/* A key question says itself that the page is open, so it waits alone. */}
+      {question
+        ? null
+        : signIns.map((signIn) => (
+            <Box key={signIn.connector} flexDirection="column">
+              <Box>
+                <Spinner color="magenta" />
+                <Text color="magenta">
+                  {` Waiting for you to sign in to ${signIn.connector} in your browser${signIn.userCode ? ` (code ${signIn.userCode})` : ''}.`}
+                </Text>
+              </Box>
+              {signIn.url ? (
+                <Text dimColor>{`  No tab opened? Open ${signIn.url}`}</Text>
+              ) : null}
+            </Box>
+          ))}
+      {approvals.length > 0 ? (
+        <Text color="magenta" bold>
+          {`◇ Approve ${approvals.map((item) => item.tool).join(', ')}? Type y or n.`}
+        </Text>
+      ) : null}
+      {question ? <Text color="magenta">{`◇ ${question.message}`}</Text> : null}
+      {goal ? (
+        <Text color="green">{`◎ Goal: ${goal.text} (${goal.status}, round ${goal.round})`}</Text>
+      ) : null}
+      {voice === 'recording' && recording ? (
+        <Box flexDirection="column">
+          <LevelMeter recording={recording} />
+          <Text dimColor>
+            Let go of Ctrl+R (or tap it again) to send. Esc drops it.
+          </Text>
+        </Box>
+      ) : voice === 'starting' ? (
+        <Box>
+          <Spinner color="red" />
+          <Text color="red"> opening the microphone...</Text>
+        </Box>
+      ) : voice === 'transcribing' ? (
+        <Box>
+          <Spinner color="cyan" />
+          <Text color="cyan"> listening to your voice message...</Text>
+        </Box>
+      ) : status === 'running' ? (
+        <Box>
+          <Spinner />
+          <Text color="yellow"> working</Text>
+          <Text dimColor> Esc cancels, typing steers</Text>
+        </Box>
+      ) : null}
+    </Box>
+  )
+}
diff --git a/examples/harness-cli-cloudflare/src/screen/theme.ts b/examples/harness-cli-cloudflare/src/screen/theme.ts
new file mode 100644
index 0000000000..96444b2931
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/screen/theme.ts
@@ -0,0 +1,18 @@
+// Cloudflare orange.
+export const ACCENT = '#F38020'
+
+export const KIND_COLOR: Record<string, string> = {
+  image: 'magenta',
+  audio: 'cyan',
+  video: 'blue',
+  document: 'white',
+}
+
+export const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+
+/** 12400 is "12.4k", 1050000 is "1.05M". */
+export function compact(count: number) {
+  if (count >= 1_000_000) return `${Number((count / 1_000_000).toFixed(2))}M`
+  if (count >= 1_000) return `${Number((count / 1_000).toFixed(1))}k`
+  return String(count)
+}
diff --git a/examples/harness-cli-cloudflare/src/sessions.ts b/examples/harness-cli-cloudflare/src/sessions.ts
new file mode 100644
index 0000000000..d5253a73da
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/sessions.ts
@@ -0,0 +1,20 @@
+import { randomUUID } from 'node:crypto'
+import { workerSessions, workerStores } from './cloudflare-stores'
+import { currentWorker } from './worker-config'
+
+/** A new session id: short, so it is easy to type after `--resume`. */
+export const newSessionId = () => randomUUID().slice(0, 8)
+
+/** Is `threadId` a saved session in your Worker? */
+export async function hasSession(threadId: string) {
+  const { log } = workerStores(currentWorker())
+  return (await log.read(threadId, { limit: 1 })).length > 0
+}
+
+/**
+ * The saved sessions in your Worker, newest first, with what the user said
+ * first. A session with no message yet is left out.
+ */
+export function listSessions(limit = 20) {
+  return workerSessions(currentWorker(), limit)
+}
diff --git a/examples/harness-cli-cloudflare/src/store.ts b/examples/harness-cli-cloudflare/src/store.ts
new file mode 100644
index 0000000000..8e855e9113
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/store.ts
@@ -0,0 +1,45 @@
+import {
+  defineAIPersistence,
+  memoryPersistence,
+} from '@tanstack/ai-persistence'
+import { workerStores } from './cloudflare-stores'
+import { currentWorker } from './worker-config'
+import type { ByokProvider } from '@tanstack/ai/byok'
+
+const memory = memoryPersistence().stores
+
+/**
+ * The stores of a session. Your Worker keeps the session log, the settings
+ * and plugin state, the sign-ins and keys (encrypted), and the media, so
+ * `--resume <id>` and `/resume` continue a session after a restart, and on
+ * another PC. The run records and the approvals stay in memory.
+ */
+export function workerPersistence() {
+  return defineAIPersistence({
+    stores: {
+      ...workerStores(currentWorker()),
+      runs: memory.runs,
+      interrupts: memory.interrupts,
+      generationRuns: memory.generationRuns,
+    },
+  })
+}
+
+/** The value of the first env var of `provider` that is set, or `null`. */
+export function envKey(provider: ByokProvider) {
+  const names = provider.env ?? []
+  const name = names.find((env) => Boolean(process.env[env]))
+  return name ? (process.env[name] ?? null) : null
+}
+
+/**
+ * The key for `provider`: the one you saved with `/connect <id>`, else its
+ * env var, else `null`. The CLI opens its sessions without a user, so every
+ * session uses the same saved keys.
+ */
+export async function providerKey(provider: ByokProvider, threadId: string) {
+  const { credentials } = workerStores(currentWorker())
+  const saved = await credentials.get({ threadId }, provider.id)
+  if (saved?.type === 'api_key') return saved.value
+  return envKey(provider)
+}
diff --git a/examples/harness-cli-cloudflare/src/tui.tsx b/examples/harness-cli-cloudflare/src/tui.tsx
new file mode 100644
index 0000000000..6cc65cd926
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/tui.tsx
@@ -0,0 +1,1108 @@
+import { readFile } from 'node:fs/promises'
+import { basename } from 'node:path'
+import {
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+} from 'react'
+import {
+  Box,
+  Spacer,
+  Static,
+  Text,
+  measureElement,
+  render,
+  useApp,
+  useBoxMetrics,
+  useCursor,
+  useInput,
+  usePaste,
+  useStdout,
+  useWindowSize,
+} from 'ink'
+import { useSelector } from '@tanstack/react-store'
+import { supportedReasoningLevels } from '@tanstack/ai-models'
+import { features, modelInfo, modelProviders, reasons } from './harness'
+import { hasSession, listSessions } from './sessions'
+import {
+  canTranscribe,
+  chooseMicrophone,
+  currentMicrophone,
+  isSilent,
+  listMicrophones,
+  startRecording,
+  transcribe,
+  withSpokenFiles,
+} from './voice'
+import { useLineEditor } from './screen/editor'
+import { Footer } from './screen/footer'
+import { PROVIDER_KEYS, isOn, providerKeysIn } from './screen/keys'
+import { mediaDir, openExternal, play, useSavedMedia } from './screen/media'
+import { SCREEN_COMMANDS, TAKES_INPUT } from './screen/commands'
+import { Menu } from './screen/menu'
+import { pathSuggestions } from './screen/paths'
+import { showSplash } from './screen/splash'
+import { Message, settledCount } from './screen/parts'
+import { Status } from './screen/status'
+import { ACCENT, compact } from './screen/theme'
+import { currentWorker, workerHost } from './worker-config'
+import type { ReactNode } from 'react'
+import type { DOMElement, RenderOptions } from 'ink'
+import type { ModelEntry } from './harness'
+import type { Recording, VoiceClip } from './voice'
+import type { Line } from './screen/editor'
+import type { MenuItem } from './screen/menu'
+import type { PathItem } from './screen/paths'
+import type { VoiceState } from './screen/status'
+import type {
+  SessionView,
+  SessionViewState,
+  ViewCommand,
+  ViewMessage,
+} from '@tanstack/ai-harness/view'
+
+const HELP = [
+  'Type / to see the commands. ↑ and ↓ go through the lines you sent.',
+  'Type @ to pick a file or a folder to send. Tab or Enter fills the path.',
+  'Voice: hold Ctrl+R and talk, then let go. Or tap Ctrl+R, talk, tap again.',
+  '  The words go into the input line. Fix them if needed, then press Enter.',
+  '  Name a file ("use cat dot png") or say "the last image" to send it too.',
+  '  The first recording listens on all microphones and keeps the loudest.',
+]
+
+/** The `/` commands that start with (or contain) what you typed after `/`. */
+function suggestionsFor(text: string, commands: ReadonlyArray<ViewCommand>) {
+  if (!/^\/\S*$/.test(text)) return []
+  const query = text.slice(1).toLowerCase()
+  const own = new Set(SCREEN_COMMANDS.map((command) => command.name))
+  const all: Array<MenuItem & { takesInput: boolean }> = [
+    ...SCREEN_COMMANDS.map((command) => ({
+      id: command.name,
+      label: `/${command.name}`,
+      detail: command.description,
+      takesInput: TAKES_INPUT.has(command.name),
+    })),
+    // `connect:cloudflare` and the like are in the `/connect` picker instead.
+    // `skill:<name>` (a skill whose name was taken) shows here.
+    ...commands
+      .filter(
+        (command) =>
+          (!command.name.includes(':') || command.name.startsWith('skill:')) &&
+          !own.has(command.name),
+      )
+      .map((command) => ({
+        id: command.name,
+        label: `/${command.name}`,
+        detail: command.description,
+        takesInput: command.input !== undefined,
+      })),
+  ]
+  return [
+    ...all.filter((item) => item.id.startsWith(query)),
+    ...all.filter(
+      (item) => !item.id.startsWith(query) && item.id.includes(query),
+    ),
+  ]
+}
+
+/** The rows of the `/connect` picker: Cloudflare, then the apps. */
+function connectItems(state: SessionViewState): Array<MenuItem> {
+  const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
+  const providers = keys.map((key) => ({
+    id: key.id,
+    label: key.label,
+    current: key.state !== 'missing',
+    detail:
+      key.state === 'connected'
+        ? 'connected'
+        : key.state === 'env'
+          ? 'token from the environment'
+          : 'opens the page to make a token, then you paste it',
+  }))
+  const apps = state.commands.flatMap((command) => {
+    const id = command.name.slice('connect:'.length)
+    const isApp =
+      command.name.startsWith('connect:') && !keys.some((key) => key.id === id)
+    return isApp ? [{ id, label: id, detail: command.description }] : []
+  })
+  return [...providers, ...apps]
+}
+
+/** The `/connect` row of the Worker: it is on this PC, not in the session. */
+const workerItem = (): MenuItem => ({
+  id: 'worker',
+  label: 'worker',
+  current: true,
+  detail: `${workerHost(currentWorker())}, change the Worker URL and secret`,
+})
+
+const modelCount = (count: number) => `${count} model${count === 1 ? '' : 's'}`
+
+const currentModel = (state: SessionViewState) =>
+  String(state.config.find((item) => item.key === 'model')?.value ?? '')
+
+/** The context size, the effort levels, and the price of a model. */
+function modelDetail(model: ModelEntry) {
+  const { contextWindow, cost } = model.record
+  const levels = supportedReasoningLevels(model.record).filter(
+    (level) => level !== 'off',
+  )
+  return [
+    `${compact(contextWindow)} context`,
+    levels.length === 0
+      ? 'no effort setting'
+      : levels.length === 1
+        ? `effort ${levels[0]}`
+        : `effort ${levels[0]} to ${levels.at(-1)}`,
+    ...(cost.input > 0 ? [`$${cost.input}/$${cost.output} per 1M tokens`] : []),
+  ].join(', ')
+}
+
+/** The rows of a `/model` picker for these models. */
+function modelRows(
+  models: ReadonlyArray<ModelEntry>,
+  state: SessionViewState,
+): Array<MenuItem> {
+  const current = currentModel(state)
+  return models.map((model) => ({
+    id: model.id,
+    label: model.id,
+    current: model.id === current,
+    detail: modelDetail(model),
+  }))
+}
+
+/** The first `/model` step: the providers, then the demo model if it is on. */
+function providerItems(state: SessionViewState): Array<MenuItem> {
+  const current = currentModel(state)
+  const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
+  const missing = keys.some((key) => key.state === 'missing')
+  const rows = modelProviders.map((provider) => ({
+    id: provider.id,
+    label: provider.label,
+    current: provider.models.some((model) => model.id === current),
+    detail: `${modelCount(provider.models.length)}${missing ? ', needs /connect cloudflare' : ''}`,
+  }))
+  const entry = state.config.find((item) => item.key === 'model')
+  const demo =
+    entry?.option.type === 'select' && entry.option.options.includes('demo')
+  return demo
+    ? [
+        ...rows,
+        {
+          id: 'demo',
+          label: 'Demo',
+          current: current === 'demo',
+          detail: 'answers without a key',
+        },
+      ]
+    : rows
+}
+
+/** The AI Gateway step between the provider and the model: the vendors. */
+function vendorItems(
+  models: ReadonlyArray<ModelEntry>,
+  state: SessionViewState,
+): Array<MenuItem> {
+  const current = currentModel(state)
+  const counts = new Map<string, number>()
+  for (const model of models) {
+    const [vendor = ''] = model.id.split('/')
+    counts.set(vendor, (counts.get(vendor) ?? 0) + 1)
+  }
+  return [...counts]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([vendor, count]) => ({
+      id: vendor,
+      label: vendor,
+      current: current.startsWith(`${vendor}/`),
+      detail: modelCount(count),
+    }))
+}
+
+const EFFORT_DETAIL: Record<string, string> = {
+  default: 'the model decides',
+  off: 'no thinking',
+  minimal: 'the least thinking',
+  low: 'fast, few tokens',
+  medium: 'balanced',
+  high: 'thinks longer',
+  xhigh: 'thinks very long',
+  max: 'the most the model can think',
+}
+
+/** The rows of the `/effort` picker: the levels the current model has. */
+function effortItems(state: SessionViewState): Array<MenuItem> {
+  const effort = state.config.find((item) => item.key === 'effort')?.value
+  const record = modelInfo[currentModel(state)]?.record
+  const levels = record ? supportedReasoningLevels(record) : []
+  return ['default', ...levels].map((name) => ({
+    id: name,
+    label: name,
+    current: name === effort,
+    detail: EFFORT_DETAIL[name] ?? '',
+  }))
+}
+
+/** The rows of the `/resume` picker: the saved sessions, newest first. */
+async function sessionItems(state: SessionViewState): Promise<Array<MenuItem>> {
+  const sessions = await listSessions()
+  return sessions.map((session) => ({
+    id: session.id,
+    label: session.id,
+    current: session.id === state.threadId,
+    detail: `${new Date(session.updatedAt).toLocaleString(undefined, { dateStyle: 'short', timeStyle: 'short' })}  ${session.title.slice(0, 60)}`,
+  }))
+}
+
+// What the CLI does after the screen closes: open the session /resume
+// picked, or ask for a new Worker first (/connect worker).
+let afterExit: { threadId: string; askWorker: boolean } | undefined
+
+/** What `/resume` or `/connect worker` asked for, once. `undefined` on quit. */
+export function takeNext() {
+  const next = afterExit
+  afterExit = undefined
+  return next
+}
+
+/** A list open over the input line, for example the `/connect` picker. */
+interface Picker {
+  title: string
+  items: Array<MenuItem>
+  pick: (item: MenuItem) => unknown
+}
+
+const HEADER_KEYS = 'Ctrl+R talk  / commands  ↑↓ history  Esc cancel'
+
+/**
+ * The header, as wide as the screen: the harness, the Worker, the folder,
+ * which features are on, and the keys. It prints once, so the App prints the screen again
+ * when a feature turns on or off.
+ */
+function Header({ view, width }: { view: SessionView; width: number }) {
+  const keys = providerKeysIn(
+    useSelector(view.store, (state) => state.plugins[PROVIDER_KEYS]),
+  )
+  const threadId = useSelector(view.store, (state) => state.threadId)
+  const marks = features.map((feature) => {
+    const on = isOn(feature, keys)
+    return {
+      name: feature.name,
+      on,
+      text: `${on ? '●' : '○'} ${feature.name}  `,
+    }
+  })
+  // The border and the padding take 4 columns. The keys go next to the
+  // features when both fit, else on their own row.
+  const inner = width - 4
+  const marksWidth = marks.reduce((sum, mark) => sum + mark.text.length, 0)
+  const keysFit = marksWidth + HEADER_KEYS.length <= inner
+  return (
+    <Box
+      width={width}
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={ACCENT}
+      paddingX={1}
+    >
+      <Box>
+        <Box flexShrink={0}>
+          <Text color={ACCENT} bold>
+            ◆ TanStack AI
+          </Text>
+          <Text bold> harness on Cloudflare</Text>
+          <Text
+            dimColor
+          >{`  ${workerHost(currentWorker())}  session ${threadId}  `}</Text>
+        </Box>
+        <Spacer />
+        <Box flexShrink={1} minWidth={0}>
+          <Text dimColor wrap="truncate-start">
+            {process.cwd()}
+          </Text>
+        </Box>
+      </Box>
+      <Box>
+        <Box flexWrap="wrap" flexShrink={1}>
+          {marks.map((mark) => (
+            <Text key={mark.name} color={mark.on ? 'green' : 'gray'}>
+              {mark.text}
+            </Text>
+          ))}
+        </Box>
+        {keysFit && (
+          <>
+            <Spacer />
+            <Text dimColor>{HEADER_KEYS}</Text>
+          </>
+        )}
+      </Box>
+      {!keysFit && (
+        <Box justifyContent="flex-end">
+          <Text dimColor>{HEADER_KEYS}</Text>
+        </Box>
+      )}
+    </Box>
+  )
+}
+
+function InputBox({
+  line,
+  voice,
+  hidden,
+}: {
+  line: Line
+  voice: VoiceState
+  /** The input is a secret (a key): show a dot for each character. */
+  hidden: boolean
+}) {
+  const shown = hidden ? '•'.repeat(line.text.length) : line.text
+  // The terminal cursor shows where you type (see `inputCursor`).
+  return (
+    <Box
+      borderStyle="round"
+      borderColor={
+        voice === 'recording' ? 'red' : voice === 'idle' ? ACCENT : 'gray'
+      }
+      paddingX={1}
+    >
+      <Text color={ACCENT} bold>
+        {'❯ '}
+      </Text>
+      {shown === '' ? (
+        // The cursor goes before the hint, so the hint does not look typed.
+        <Text>
+          {' '}
+          <Text dimColor>
+            {hidden
+              ? ' Paste the key. It stays hidden.'
+              : ' Type a message, / for commands, @file to attach, or hold Ctrl+R to talk'}
+          </Text>
+        </Text>
+      ) : (
+        // At any character, so `inputCursor` knows the row of each one.
+        <Text wrap="hard">{shown}</Text>
+      )}
+    </Box>
+  )
+}
+
+/**
+ * Where the terminal cursor goes in the input box, which is `width` wide
+ * and starts at `top`: after the border, the padding, and the `❯ `, at the
+ * row and the column of the line's cursor.
+ * ponytail: one column for each character. A wide character (an emoji, CJK)
+ * puts the cursor a little to the left.
+ */
+function inputCursor(line: Line, width: number, top: number) {
+  const before = 4
+  const textWidth = Math.max(1, width - before - 2)
+  return {
+    x: before + (line.cursor % textWidth),
+    y: top + 1 + Math.floor(line.cursor / textWidth),
+  }
+}
+
+// A key held down repeats. Repeats closer than this are one press.
+const REPEAT_GAP = 1100
+// After the last repeat, the key is up when no repeat comes for this long.
+const RELEASE_WAIT = 450
+
+type Row = { id: 'header' } | ViewMessage
+
+/** Reports its height once, when Ink prints it (Static prints a row once). */
+function Measured({
+  id,
+  onHeight,
+  children,
+}: {
+  id: string
+  onHeight: (id: string, height: number) => void
+  children: ReactNode
+}) {
+  const ref = useRef<DOMElement>(null)
+  // Ink lays out the frame before layout effects run, so the height is there.
+  useLayoutEffect(() => {
+    if (ref.current) onHeight(id, measureElement(ref.current).height)
+  }, [])
+  return (
+    <Box ref={ref} flexDirection="column">
+      {children}
+    </Box>
+  )
+}
+
+/** One printed row: the header, or a message that no longer changes. */
+function PrintedRow({
+  view,
+  row,
+  saved,
+  width,
+}: {
+  view: SessionView
+  row: Row
+  saved: ReturnType<typeof useSavedMedia>['saved']
+  width: number
+}) {
+  return 'role' in row ? (
+    <Message message={row} saved={saved} width={width} />
+  ) : (
+    <Header view={view} width={width} />
+  )
+}
+
+function App({ view }: { view: SessionView }) {
+  const { exit } = useApp()
+  const messages = useSelector(view.store, (state) => state.messages)
+  const running = useSelector(view.store, (state) => state.status === 'running')
+  const { saved, saving } = useSavedMedia(view, messages)
+  // The input line. A line typed while a question asks for a key stays hidden
+  // until it is sent or deleted, also when the question ends first, so a key
+  // never shows or goes out as a message.
+  const editor = useLineEditor()
+  const secretAsked = useSelector(
+    view.store,
+    (state) => state.questions.at(0)?.secret === true,
+  )
+  const asksSecret = () => view.store.get().questions.at(0)?.secret === true
+  const commands = useSelector(view.store, (state) => state.commands)
+  const waiting = useSelector(
+    view.store,
+    (state) => state.questions.length > 0 || state.approvals.length > 0,
+  )
+  const [picker, setPicker] = useState<Picker | undefined>(undefined)
+  const [selected, setSelected] = useState(0)
+  // A line from the history keeps the arrows for the history.
+  const blocked = Boolean(
+    picker || waiting || editor.line.hidden || editor.browsing,
+  )
+  const commandItems = blocked ? [] : suggestionsFor(editor.line.text, commands)
+  // The files for an `@path`, read again only when the line changes.
+  const { text: lineText, cursor: lineCursor } = editor.line
+  const paths = useMemo(
+    () =>
+      blocked || commandItems.length > 0
+        ? undefined
+        : pathSuggestions({
+            text: lineText,
+            cursor: lineCursor,
+            hidden: false,
+          }),
+    [blocked, commandItems.length, lineText, lineCursor],
+  )
+  const suggestions: Array<(MenuItem & { takesInput: boolean }) | PathItem> =
+    commandItems.length > 0 ? commandItems : (paths?.items ?? [])
+  const [suggested, setSuggested] = useState(0)
+  useEffect(() => setSuggested(0), [editor.line.text])
+
+  // Messages that no longer change print once, above the live area. The
+  // count only grows: a printed message is never printed again.
+  const printed = useRef(0)
+  printed.current = Math.max(
+    printed.current,
+    settledCount(messages, saving, running),
+  )
+  const rows: Array<Row> = [
+    { id: 'header' },
+    ...messages.slice(0, printed.current),
+  ]
+
+  // The input sits at the bottom of the screen: until the printed rows fill
+  // the screen, empty space above the live area fills the rest. Each row
+  // measures itself when it prints. Ink redraws the whole screen for a frame
+  // as tall as the screen, so the frame stays one line shorter.
+  // ponytail: the heights are from the width at print time. A resize makes
+  // the space a little off until the screen is full.
+  const { columns, rows: screenRows } = useWindowSize()
+  const heights = useRef(new Map<string, number>())
+  const [, remeasure] = useReducer((count: number) => count + 1, 0)
+  const onHeight = (id: string, height: number) => {
+    heights.current.set(id, height)
+    remeasure()
+  }
+  const printedHeight = rows.reduce(
+    (sum, row) => sum + (heights.current.get(row.id) ?? 0),
+    0,
+  )
+  const live = useRef<DOMElement>(null)
+  const { height: liveHeight } = useBoxMetrics(live)
+  const space = Math.max(0, screenRows - 1 - printedHeight - liveHeight)
+
+  // The terminal cursor sits in the input box, not under the screen. The
+  // box is in the live area, which starts after the empty space.
+  const inputBox = useRef<DOMElement>(null)
+  const input = useBoxMetrics(inputBox)
+  const { setCursorPosition } = useCursor()
+  setCursorPosition(
+    input.hasMeasured
+      ? inputCursor(editor.line, input.width, space + input.top)
+      : undefined,
+  )
+
+  // The header shows which features are on, but printed rows never change.
+  // So when a feature turns on or off (a /connect), clear the screen and
+  // print the header and the conversation again.
+  const { stdout } = useStdout()
+  const featureMarks = useSelector(view.store, (state) => {
+    const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
+    return features.map((feature) => (isOn(feature, keys) ? 1 : 0)).join('')
+  })
+  const shownMarks = useRef(featureMarks)
+  const [printRound, setPrintRound] = useState(0)
+  useEffect(() => {
+    if (featureMarks === shownMarks.current) return
+    shownMarks.current = featureMarks
+    if (stdout.isTTY) stdout.write('\x1b[2J\x1b[3J\x1b[H')
+    setPrintRound((round) => round + 1)
+  }, [featureMarks])
+
+  const [voice, setVoiceState] = useState<VoiceState>('idle')
+  // The phase in a ref too: key events come faster than React renders, and a
+  // second Ctrl+R must see "starting" at once, or it starts a second recorder.
+  const phase = useRef<VoiceState>('idle')
+  const setVoice = (next: VoiceState) => {
+    phase.current = next
+    setVoiceState(next)
+  }
+  const recording = useRef<Recording | undefined>(undefined)
+  const [recorder, setRecorder] = useState<Recording | undefined>(undefined)
+  const talk = useRef({
+    last: 0,
+    holding: false,
+    stopWanted: false,
+    cancelWanted: false,
+  })
+  const release = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+
+  const fail = (error: unknown) =>
+    view.notice(error instanceof Error ? error.message : String(error))
+  const failVoice = (error: unknown) =>
+    view.notice(
+      `Voice: ${error instanceof Error ? error.message : String(error)}`,
+    )
+
+  /**
+   * A voice message: transcribe it, and put the words in the input line, with
+   * an `@path` for each file it names. The user fixes the line if needed,
+   * then presses Enter to send it.
+   */
+  const hear = async (audio: Uint8Array, name: string, clip?: VoiceClip) => {
+    setVoice('transcribing')
+    try {
+      if (clip?.pickedMicrophone)
+        view.notice(
+          `Voice: using "${clip.microphone}" from now on. /mic changes it.`,
+        )
+      // Transcription models make up words for silence, so it is not sent.
+      if (clip && isSilent(clip))
+        return view.notice(
+          `Voice: only silence from "${clip.microphone}". Hold Ctrl+R while you talk, or pick another microphone with /mic.`,
+        )
+      const text = await transcribe(audio, {
+        name,
+        threadId: view.store.get().threadId,
+      })
+      if (text === '') return view.notice('Voice: no speech heard.')
+      const recent = saved.flatMap((item) =>
+        item.path ? [{ kind: item.kind, path: item.path }] : [],
+      )
+      const message = await withSpokenFiles(
+        text,
+        [process.cwd(), mediaDir],
+        recent,
+      )
+      // A key question keeps its line for the key only.
+      if (asksSecret())
+        return view.notice('Voice: answer the key question first.')
+      // After what the user typed already, so nothing they typed is lost.
+      const typed = editor.line.text.trimEnd()
+      editor.set(typed === '' ? message.text : `${typed} ${message.text}`)
+    } catch (error) {
+      failVoice(error)
+    } finally {
+      setVoice('idle')
+    }
+  }
+
+  const stopTalking = async () => {
+    clearTimeout(release.current)
+    const current = recording.current
+    if (!current) {
+      // Still opening: stop as soon as it is open.
+      talk.current.stopWanted = true
+      return
+    }
+    recording.current = undefined
+    setRecorder(undefined)
+    await current
+      .stop()
+      .then((clip) => hear(clip.audio, 'voice.wav', clip), failVoice)
+  }
+
+  const startTalking = async () => {
+    talk.current = {
+      last: Date.now(),
+      holding: false,
+      stopWanted: false,
+      cancelWanted: false,
+    }
+    // "starting" before the key check, so a repeated Ctrl+R starts nothing.
+    setVoice('starting')
+    try {
+      if (!(await canTranscribe(view.store.get().threadId))) {
+        setVoice('idle')
+        return view.notice('Voice: run /connect cloudflare to turn voice on.')
+      }
+      const started = await startRecording()
+      if (talk.current.cancelWanted) {
+        started.cancel()
+        setVoice('idle')
+        return
+      }
+      recording.current = started
+      setRecorder(started)
+      setVoice('recording')
+      if (talk.current.stopWanted) await stopTalking()
+    } catch (error) {
+      setVoice('idle')
+      failVoice(error)
+    }
+  }
+
+  /**
+   * Ctrl+R. A terminal sends no key-up, only repeats while a key is held. So
+   * repeats mean "held": the recording stops when they stop. A single press
+   * starts, and the next single press stops.
+   */
+  const onTalkKey = () => {
+    const now = Date.now()
+    const gap = now - talk.current.last
+    talk.current.last = now
+    if (phase.current === 'transcribing') return
+    if (phase.current === 'idle') return void startTalking()
+    if (gap < REPEAT_GAP) {
+      talk.current.holding = true
+      clearTimeout(release.current)
+      release.current = setTimeout(() => void stopTalking(), RELEASE_WAIT)
+      return
+    }
+    if (!talk.current.holding) void stopTalking()
+  }
+
+  /** The saved media file `/open 2` or `/play` names. */
+  const pick = (arg: string | undefined) => {
+    const ready = saved.filter((item) => item.path !== undefined)
+    const item = arg
+      ? ready.find((entry) => entry.number === Number(arg))
+      : ready.at(-1)
+    if (!item?.path) {
+      view.notice(arg ? `No saved media file ${arg}.` : 'No media file yet.')
+      return undefined
+    }
+    return { ...item, path: item.path }
+  }
+
+  const openPicker = (next: Picker) => {
+    if (next.items.length === 0)
+      return view.notice(`${next.title}: nothing to pick.`)
+    setSelected(
+      Math.max(
+        0,
+        next.items.findIndex((item) => item.current),
+      ),
+    )
+    setPicker(next)
+  }
+
+  const pickMicrophone = async () => {
+    const names = await listMicrophones()
+    const current = await currentMicrophone()
+    if (names.length === 0)
+      return view.notice(
+        `Recording from the default input${current ? ` (${current})` : ''}.`,
+      )
+    openPicker({
+      title: 'Record from which microphone?',
+      items: names.map((name) => ({
+        id: name,
+        label: name,
+        current: name === current,
+      })),
+      pick: async (item) => {
+        await chooseMicrophone(item.id)
+        view.notice(`Voice: recording from "${item.id}".`)
+      },
+    })
+  }
+
+  /** Pick a model of the provider `id`. AI Gateway asks for the vendor first. */
+  const pickModelOf = (id: string) => {
+    if (id === 'demo') return view.command('model', 'demo')
+    const provider = modelProviders.find((entry) => entry.id === id)
+    if (!provider) return
+    const state = view.store.get()
+    const pickModel = (title: string, models: ReadonlyArray<ModelEntry>) =>
+      openPicker({
+        title,
+        items: modelRows(models, state),
+        pick: (item) => view.command('model', item.id),
+      })
+    if (!provider.byVendor)
+      return pickModel(`${provider.label}: pick the model`, provider.models)
+    openPicker({
+      title: `${provider.label}: pick the vendor`,
+      items: vendorItems(provider.models, state),
+      pick: (vendor) =>
+        pickModel(
+          `${provider.label}: pick the ${vendor.id} model`,
+          provider.models.filter((model) =>
+            model.id.startsWith(`${vendor.id}/`),
+          ),
+        ),
+    })
+  }
+
+  /** Close the screen, and the CLI opens the saved session `id`. */
+  const resume = async (id: string) => {
+    if (id === view.store.get().threadId)
+      return view.notice('You are in this session.')
+    if (!(await hasSession(id)))
+      return view.notice(`No saved session ${id}. /resume lists them.`)
+    afterExit = { threadId: id, askWorker: false }
+    exit()
+  }
+
+  /** Close the screen. The CLI asks for the new Worker, then opens this session. */
+  const changeWorker = () => {
+    afterExit = { threadId: view.store.get().threadId, askWorker: true }
+    exit()
+  }
+
+  /** Enter: answer an approval or a question, run a screen command, or send. */
+  const submit = async (line: Line) => {
+    const text = line.text.trim()
+    const state = view.store.get()
+    const [question] = state.questions
+    if (question?.secret) {
+      // The key goes as it is. The screen does not show it anywhere.
+      await question.answer(text)
+      return
+    }
+    if (line.hidden) {
+      // The question ended before Enter: drop the key, do not send it.
+      view.notice('The key question ended, so the key was not used.')
+      return
+    }
+    if (state.approvals.length > 0) {
+      if (/^y(es)?$/i.test(text)) view.approveAll()
+      else view.rejectAll()
+      return
+    }
+    if (question) {
+      const answer = /^y(es)?$/i.test(text)
+        ? true
+        : /^no?$/i.test(text)
+          ? false
+          : text
+      await question.answer(answer)
+      return
+    }
+    const [command, ...rest] = text.split(' ')
+    const arg = rest.join(' ').trim() || undefined
+    switch (command) {
+      case '/exit':
+        return exit()
+      case '/help': {
+        const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
+        const off = features
+          .filter((feature) => !isOn(feature, keys))
+          .map(
+            (feature) => `  ${feature.name} is off: it needs ${feature.needs}.`,
+          )
+        const list = suggestionsFor('/', state.commands).map(
+          (item) => `${item.label.padEnd(14)}${item.detail ?? ''}`,
+        )
+        return view.notice([...HELP, ...off, ...list].join('\n'))
+      }
+      case '/connect':
+        if (arg === 'worker') return changeWorker()
+        if (arg) return view.command(`connect:${arg}`)
+        return openPicker({
+          title: 'Connect to what?',
+          items: [...connectItems(state), workerItem()],
+          pick: (item) =>
+            item.id === 'worker'
+              ? changeWorker()
+              : view.command(`connect:${item.id}`),
+        })
+      case '/disconnect': {
+        if (arg) return view.command(`disconnect:${arg}`)
+        // A key from the environment cannot be removed here, so it is not listed.
+        const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
+        return openPicker({
+          title: 'Remove which key or sign-in?',
+          items: connectItems(state).filter(
+            (item) =>
+              !keys.some(
+                (key) => key.id === item.id && key.state !== 'connected',
+              ),
+          ),
+          pick: (item) => view.command(`disconnect:${item.id}`),
+        })
+      }
+      case '/model':
+        if (arg) break
+        return openPicker({
+          title: 'Pick the provider',
+          items: providerItems(state),
+          pick: (item) => pickModelOf(item.id),
+        })
+      case '/effort':
+        if (arg) break
+        if (!reasons(currentModel(state)))
+          return view.notice(
+            `${currentModel(state)} has no effort setting. Pick another model with /model.`,
+          )
+        return openPicker({
+          title: 'How hard should the model think?',
+          items: effortItems(state),
+          pick: (item) => view.command('effort', item.id),
+        })
+      case '/resume':
+        if (arg) return resume(arg)
+        return openPicker({
+          title: 'Continue which session?',
+          items: await sessionItems(state),
+          pick: (item) => resume(item.id),
+        })
+      case '/mic': {
+        if (!arg) return pickMicrophone().catch(failVoice)
+        const names = await listMicrophones().catch(() => [])
+        const chosen = names[Number(arg) - 1]
+        if (!chosen)
+          return view.notice(`No microphone ${arg}. /mic lists them.`)
+        await chooseMicrophone(chosen)
+        return view.notice(`Voice: recording from "${chosen}".`)
+      }
+      case '/voice': {
+        if (!arg) return view.notice('Give an audio file: /voice note.m4a')
+        const path = arg.replace(/^@|^"|"$/g, '')
+        const audio = await readFile(path).catch(failVoice)
+        if (audio) await hear(new Uint8Array(audio), basename(path))
+        return
+      }
+      case '/open':
+      case '/play': {
+        const item = pick(arg)
+        if (!item) return
+        if (command === '/play' && item.kind !== 'image') play(item)
+        else openExternal(item.path)
+        return
+      }
+    }
+    await view.send(text)
+  }
+
+  /** Send a line and keep it for the up arrow, unless it is a key or an answer. */
+  const send = (line: Line) => {
+    const state = view.store.get()
+    const isAnswer = state.questions.length > 0 || state.approvals.length > 0
+    if (!line.hidden && !isAnswer) editor.remember(line.text)
+    editor.clear()
+    submit(line).catch(fail)
+  }
+
+  usePaste((text) => editor.insert(text, asksSecret()))
+
+  useInput((character, key) => {
+    if (key.ctrl && character === 'r') return onTalkKey()
+    if (picker) {
+      const count = picker.items.length
+      const number = Number(character)
+      const chosen = key.return
+        ? picker.items[selected]
+        : Number.isInteger(number) && number >= 1
+          ? picker.items[number - 1]
+          : undefined
+      if (key.escape || chosen) setPicker(undefined)
+      if (chosen) Promise.resolve(picker.pick(chosen)).catch(fail)
+      if (key.upArrow) setSelected((index) => (index - 1 + count) % count)
+      if (key.downArrow) setSelected((index) => (index + 1) % count)
+      return
+    }
+    if (key.escape) {
+      clearTimeout(release.current)
+      if (phase.current === 'starting') {
+        // Drop the recording as soon as the microphone is open.
+        talk.current.cancelWanted = true
+        return
+      }
+      const current = recording.current
+      if (current) {
+        recording.current = undefined
+        setRecorder(undefined)
+        current.cancel()
+        setVoice('idle')
+        return
+      }
+      if (view.store.get().status === 'running') void view.cancel()
+      else editor.clear()
+      return
+    }
+    const suggestion = suggestions[Math.min(suggested, suggestions.length - 1)]
+    if (suggestion) {
+      const count = suggestions.length
+      if (key.upArrow)
+        return setSuggested((index) => (index - 1 + count) % count)
+      if (key.downArrow) return setSuggested((index) => (index + 1) % count)
+      if ('fill' in suggestion) {
+        // Put the path in place of the typed `@` token.
+        if (key.tab || key.return) {
+          const { text, cursor } = editor.line
+          const filled = text.slice(0, paths?.start ?? cursor) + suggestion.fill
+          return editor.set(filled + text.slice(cursor), filled.length)
+        }
+      } else {
+        if (key.tab) return editor.set(`/${suggestion.id} `)
+        if (key.return) {
+          if (suggestion.takesInput) return editor.set(`/${suggestion.id} `)
+          return send({ text: `/${suggestion.id}`, cursor: 0, hidden: false })
+        }
+      }
+    }
+    if (key.upArrow) return editor.older()
+    if (key.downArrow) return editor.newer()
+    if (key.leftArrow) return editor.move(-1)
+    if (key.rightArrow) return editor.move(1)
+    if (key.home) return editor.move('start')
+    if (key.end) return editor.move('end')
+    if (key.return) {
+      if (phase.current === 'recording' || phase.current === 'starting')
+        return void stopTalking()
+      return send(editor.line)
+    }
+    // Most terminals send Backspace as the delete key.
+    if (key.backspace || key.delete) return editor.backspace()
+    if (!key.ctrl && !key.meta && !key.tab && character)
+      editor.insert(character, asksSecret())
+  })
+
+  return (
+    <Box flexDirection="column">
+      <Static key={printRound} items={rows}>
+        {(row) => (
+          <Measured key={row.id} id={row.id} onHeight={onHeight}>
+            <PrintedRow view={view} row={row} saved={saved} width={columns} />
+          </Measured>
+        )}
+      </Static>
+      {space > 0 ? <Box height={space} /> : null}
+      <Box ref={live} flexDirection="column">
+        {messages.slice(printed.current).map((message) => (
+          <Message
+            key={message.id}
+            message={message}
+            saved={saved}
+            width={columns}
+          />
+        ))}
+        <Status view={view} voice={voice} recording={recorder} />
+        {/* A column, so the input box keeps the full width. */}
+        <Box ref={inputBox} flexDirection="column">
+          <InputBox
+            line={editor.line}
+            voice={voice}
+            hidden={
+              secretAsked || (editor.line.hidden && editor.line.text !== '')
+            }
+          />
+        </Box>
+        {picker ? (
+          <Menu
+            title={picker.title}
+            items={picker.items}
+            selected={selected}
+            hint="↑↓ move   Enter or a number picks   Esc closes"
+          />
+        ) : suggestions.length > 0 ? (
+          <Menu
+            items={suggestions}
+            selected={Math.min(suggested, suggestions.length - 1)}
+            hint={
+              commandItems.length > 0
+                ? '↑↓ move   Tab fills   Enter runs'
+                : '↑↓ move   Tab or Enter fills'
+            }
+          />
+        ) : null}
+        <Footer view={view} />
+      </Box>
+    </Box>
+  )
+}
+
+// The boot splash shows once in a process.
+let splashShown = false
+
+/**
+ * The Ink screen for `runCli({ ui })`. It clears the terminal, opens sign-in
+ * links in the browser, records voice messages, saves the media the agents
+ * make into `./<harness-name>-media`, and resolves when the user types /exit
+ * or presses Ctrl+C. `io` replaces the terminal, for a test.
+ */
+export async function runTui(view: SessionView, io: RenderOptions = {}) {
+  view.on('signIn', (signIn) => {
+    if (signIn.url) openExternal(signIn.url)
+  })
+  const keys = providerKeysIn(view.store.get().plugins[PROVIDER_KEYS])
+  if (keys.every((key) => key.state === 'missing'))
+    view.notice(
+      'No Cloudflare account yet. Type /connect cloudflare to connect it.',
+    )
+  // Start on a clean terminal: clear the screen and the scrollback. The
+  // splash shows once, at the first start, not again after a /resume.
+  const clear = () => {
+    if (!io.stdout && process.stdout.isTTY)
+      process.stdout.write('\x1b[2J\x1b[3J\x1b[H')
+  }
+  if (!splashShown && (io.stdout ?? process.stdout).isTTY) {
+    splashShown = true
+    clear()
+    await showSplash(io)
+  }
+  clear()
+  const app = render(<App view={view} />, io)
+  // ponytail: the SDK logs its warnings and errors on the console (the
+  // message, then its details with console.dir), and the code highlighter
+  // warns about languages it does not know. Ink prints console output above
+  // the screen, and the screen shows the errors itself, so it drops them.
+  // This wraps the console after render(), because render() replaces it.
+  const before = { warn: console.warn, error: console.error, dir: console.dir }
+  let dropDetails = false
+  const quiet =
+    (log: (...args: Array<unknown>) => void) =>
+    (...args: Array<unknown>) => {
+      const text = typeof args[0] === 'string' ? args[0] : ''
+      dropDetails =
+        /\[tanstack-ai:(warn|errors)\]|Could not find the language/.test(text)
+      if (!dropDetails) log(...args)
+    }
+  const quietWarn = quiet(before.warn)
+  console.warn = quietWarn
+  console.error = quiet(before.error)
+  console.dir = (...args: Parameters<typeof console.dir>) => {
+    if (dropDetails) dropDetails = false
+    else before.dir(...args)
+  }
+  try {
+    await app.waitUntilExit()
+  } finally {
+    // Ink puts the first console back when it stops. Without its console
+    // (`patchConsole: false`), the screen puts it back itself.
+    if (console.warn === quietWarn) Object.assign(console, before)
+  }
+}
diff --git a/examples/harness-cli-cloudflare/src/voice.ts b/examples/harness-cli-cloudflare/src/voice.ts
new file mode 100644
index 0000000000..f6990e9cf6
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/voice.ts
@@ -0,0 +1,433 @@
+import { execFile, spawn } from 'node:child_process'
+import type { ChildProcess } from 'node:child_process'
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
+import { basename, dirname, extname, join, relative } from 'node:path'
+import { generateTranscription } from '@tanstack/ai'
+import { createCloudflareTranscription } from '@tanstack/ai-cloudflare'
+import { cloudflareByok } from '@tanstack/ai-cloudflare/byok'
+import { cloudflareRest } from './cloudflare-connect'
+import { SAVE_DIR } from './worker-config'
+import { providerKey } from './store'
+
+// Voice input for the terminal: ffmpeg records the microphone, a
+// transcription model turns it into text, and spoken file names become
+// `@path` attachments that the CLI sends with the message.
+
+const ffmpeg = process.env.FFMPEG_PATH || 'ffmpeg'
+const RATE = 16000
+// The microphone you picked, kept next to the sign-ins.
+const saved = join(SAVE_DIR, 'voice.json')
+
+/**
+ * Can the session of `threadId` turn speech into text? It needs the
+ * Cloudflare token: saved with `/connect cloudflare`, or in the env.
+ */
+export async function canTranscribe(threadId: string) {
+  return (await providerKey(cloudflareByok, threadId)) !== null
+}
+
+/**
+ * The audio inputs ffmpeg can record on Windows (DirectShow). Other systems
+ * record the default input, so this is empty there.
+ */
+export function listMicrophones() {
+  if (process.platform !== 'win32') return Promise.resolve<Array<string>>([])
+  return new Promise<Array<string>>((resolve, reject) => {
+    execFile(
+      ffmpeg,
+      ['-hide_banner', '-list_devices', 'true', '-f', 'dshow', '-i', 'dummy'],
+      (error, _stdout, stderr) => {
+        if (error?.code === 'ENOENT')
+          return reject(
+            new Error('Voice needs ffmpeg on the PATH (or FFMPEG_PATH).'),
+          )
+        resolve(
+          [...stderr.matchAll(/"([^"]+)" \(audio\)/g)].map(
+            (match) => match[1] ?? '',
+          ),
+        )
+      },
+    )
+  })
+}
+
+// The microphone `/mic <n>` picked, or the first recording found.
+let picked: string | undefined
+
+/** Record from this microphone from now on, also after a restart. */
+export async function chooseMicrophone(name: string) {
+  picked = name
+  await mkdir(dirname(saved), { recursive: true })
+  await writeFile(saved, JSON.stringify({ microphone: name }, null, 2))
+}
+
+/** The microphone to record from, when one is set: VOICE_DEVICE, then yours. */
+export async function currentMicrophone() {
+  if (process.env.VOICE_DEVICE) return process.env.VOICE_DEVICE
+  if (picked) return picked
+  try {
+    const parsed: unknown = JSON.parse(await readFile(saved, 'utf8'))
+    if (
+      typeof parsed === 'object' &&
+      parsed !== null &&
+      'microphone' in parsed &&
+      typeof parsed.microphone === 'string'
+    )
+      picked = parsed.microphone
+  } catch {
+    // No saved microphone yet.
+  }
+  return picked
+}
+
+/**
+ * The inputs a first recording listens on: every microphone, without capture
+ * cards and virtual inputs (they are often silent).
+ */
+async function candidateMicrophones() {
+  const names = await listMicrophones()
+  const real = names.filter(
+    (name) => !/hdmi|cam link|virtual|stereo mix|line in/i.test(name),
+  )
+  return real.length > 0 ? real : names
+}
+
+/** The ffmpeg input arguments for one microphone. */
+function microphoneInput(name: string | undefined) {
+  if (process.platform === 'win32')
+    return ['-f', 'dshow', '-i', `audio=${name}`]
+  if (process.platform === 'darwin')
+    return ['-f', 'avfoundation', '-i', `:${name ?? '0'}`]
+  return ['-f', 'pulse', '-i', name ?? 'default']
+}
+
+/** The root mean square of 16-bit samples, without a constant offset. */
+function rms(samples: Int16Array) {
+  if (samples.length === 0) return 0
+  let sum = 0
+  let squares = 0
+  for (const sample of samples) {
+    sum += sample
+    squares += sample * sample
+  }
+  const mean = sum / samples.length
+  return Math.sqrt(Math.max(0, squares / samples.length - mean * mean))
+}
+
+function samplesOf(pcm: Uint8Array) {
+  return new Int16Array(
+    pcm.buffer.slice(pcm.byteOffset, pcm.byteOffset + (pcm.byteLength & ~1)),
+  )
+}
+
+/**
+ * How much speech a clip holds, from its 100 ms windows:
+ * - `peak`: the loudness of the loud part (90th percentile), 0 to 32768.
+ * - `floor`: the loudness of the quiet part (20th percentile), the noise.
+ * Speech makes the peak much louder than the floor. Steady noise and a few
+ * clicks do not, so they read as silence.
+ */
+export function speechStats(pcm: Uint8Array) {
+  const samples = samplesOf(pcm)
+  const size = RATE / 10
+  const windows: Array<number> = []
+  for (let start = 0; start + size <= samples.length; start += size)
+    windows.push(rms(samples.subarray(start, start + size)))
+  windows.sort((a, b) => a - b)
+  const at = (share: number) =>
+    windows[Math.min(windows.length - 1, Math.floor(windows.length * share))] ??
+    0
+  return { peak: at(0.9), floor: at(0.2) }
+}
+
+/** How clearly a clip holds speech: the peak over the noise floor. */
+function speechScore(stats: { peak: number; floor: number }) {
+  return stats.peak / Math.max(stats.floor, 30)
+}
+
+/** A 16 kHz mono 16-bit WAV file for raw samples. */
+function wavFile(pcm: Uint8Array) {
+  const header = new DataView(new ArrayBuffer(44))
+  const text = (offset: number, value: string) => {
+    for (let index = 0; index < 4; index++)
+      header.setUint8(offset + index, value.charCodeAt(index))
+  }
+  text(0, 'RIFF')
+  header.setUint32(4, 36 + pcm.byteLength, true)
+  text(8, 'WAVE')
+  text(12, 'fmt ')
+  header.setUint32(16, 16, true)
+  header.setUint16(20, 1, true)
+  header.setUint16(22, 1, true)
+  header.setUint32(24, RATE, true)
+  header.setUint32(28, RATE * 2, true)
+  header.setUint16(32, 2, true)
+  header.setUint16(34, 16, true)
+  text(36, 'data')
+  header.setUint32(40, pcm.byteLength, true)
+  const file = new Uint8Array(44 + pcm.byteLength)
+  file.set(new Uint8Array(header.buffer))
+  file.set(pcm, 44)
+  return file
+}
+
+// Every ffmpeg recorder that runs. They are stopped when the app exits, so no
+// recorder keeps the microphone open after it.
+const recorders = new Set<ChildProcess>()
+process.once('exit', () => {
+  for (const child of recorders) child.kill()
+})
+
+/** One ffmpeg process that streams raw samples from one microphone. */
+function capture(name: string | undefined) {
+  const child = spawn(
+    ffmpeg,
+    [
+      '-hide_banner',
+      '-loglevel',
+      'error',
+      ...microphoneInput(name),
+      '-ac',
+      '1',
+      '-ar',
+      String(RATE),
+      '-f',
+      's16le',
+      'pipe:1',
+    ],
+    { stdio: ['pipe', 'pipe', 'pipe'] },
+  )
+  recorders.add(child)
+  child.on('exit', () => recorders.delete(child))
+  const chunks: Array<Buffer> = []
+  let level = 0
+  let errors = ''
+  child.stdout.on('data', (chunk: Buffer) => {
+    chunks.push(chunk)
+    level = rms(samplesOf(chunk))
+  })
+  child.stderr.on('data', (chunk: Buffer) => (errors += chunk.toString()))
+  const exited = new Promise<void>((resolve, reject) => {
+    child.on('error', (error: NodeJS.ErrnoException) =>
+      reject(
+        error.code === 'ENOENT'
+          ? new Error('Voice needs ffmpeg on the PATH (or FFMPEG_PATH).')
+          : error,
+      ),
+    )
+    child.on('exit', () => resolve())
+  })
+  let running = true
+  void exited.then(
+    () => (running = false),
+    () => (running = false),
+  )
+  return {
+    name: name ?? 'the default input',
+    exited,
+    isRunning: () => running,
+    errors: () => errors.trim(),
+    level: () => level,
+    pcm: () => new Uint8Array(Buffer.concat(chunks)),
+    stop: async () => {
+      // `q` makes ffmpeg stop cleanly. Kill it if it does not.
+      child.stdin.end('q')
+      const timer = setTimeout(() => child.kill(), 2000)
+      await exited.catch(() => {})
+      clearTimeout(timer)
+    },
+    kill: () => child.kill(),
+  }
+}
+
+/** A voice message from the microphone. */
+export interface VoiceClip {
+  /** 16 kHz mono WAV. */
+  audio: Uint8Array
+  /** The loud part and the noise floor, from 0 to 32768. */
+  peak: number
+  floor: number
+  microphone: string
+  /** True when this recording picked the microphone (the clearest one). */
+  pickedMicrophone: boolean
+}
+
+export interface Recording {
+  /** The microphone, or "all microphones" while the first recording picks one. */
+  microphone: string
+  /** The loudness right now, from 0 to 32768, for a level meter. */
+  level: () => number
+  /** Stop, and give the voice message. */
+  stop: () => Promise<VoiceClip>
+  /** Stop and drop the audio. */
+  cancel: () => void
+}
+
+/**
+ * Start recording until `stop` or `cancel`. With no microphone set yet, it
+ * listens on every microphone, keeps the one that heard speech the clearest,
+ * and remembers it.
+ */
+export async function startRecording(): Promise<Recording> {
+  const chosen = await currentMicrophone()
+  const names =
+    chosen !== undefined || process.platform !== 'win32'
+      ? [chosen]
+      : await candidateMicrophones()
+  if (names.length === 0)
+    throw new Error('No microphone found. Set VOICE_DEVICE to its name.')
+  const captures = names.map(capture)
+  // ffmpeg stops at once when a device does not open.
+  await new Promise((resolve) => setTimeout(resolve, 400))
+  const live = captures.filter((item) => item.isRunning())
+  if (live.length === 0) {
+    const errors = captures.map((item) => item.errors()).filter(Boolean)
+    throw new Error(`The microphone did not open. ${errors.join(' ')}`.trim())
+  }
+  const picking = chosen === undefined && live.length > 1
+  return {
+    microphone: picking ? 'all microphones' : (live[0]?.name ?? ''),
+    level: () => Math.max(...live.map((item) => item.level())),
+    stop: async () => {
+      await Promise.all(live.map((item) => item.stop()))
+      const clips = live.map((item) => {
+        const pcm = item.pcm()
+        return { name: item.name, pcm, ...speechStats(pcm) }
+      })
+      const best = clips.reduce((clearest, clip) =>
+        speechScore(clip) > speechScore(clearest) ? clip : clearest,
+      )
+      const clip: VoiceClip = {
+        audio: wavFile(best.pcm),
+        peak: best.peak,
+        floor: best.floor,
+        microphone: best.name,
+        pickedMicrophone: false,
+      }
+      // Keep that microphone only when it heard speech: in silence, the
+      // clearest one means nothing.
+      if (picking && !isSilent(clip)) {
+        await chooseMicrophone(best.name)
+        clip.pickedMicrophone = true
+      }
+      return clip
+    },
+    cancel: () => {
+      for (const item of live) item.kill()
+    },
+  }
+}
+
+/**
+ * Is a clip silent? Transcription models make up words for silence, so a
+ * silent clip is not sent. A clip is silent when its loud part is under
+ * VOICE_MIN_LOUDNESS (default 300), for example a muted microphone.
+ */
+export function isSilent(clip: Pick<VoiceClip, 'peak'>) {
+  return clip.peak < Number(process.env.VOICE_MIN_LOUDNESS || 300)
+}
+
+/**
+ * The words in `audio`, with Workers AI Whisper through your AI Gateway.
+ * The token is the one the session of `threadId` uses: saved with
+ * `/connect cloudflare`, else the env var. `name` gives the format, for
+ * example `voice.wav`. VOICE_LANGUAGE (an ISO-639-1 code such as `en`) tells
+ * the model which language to expect.
+ */
+export async function transcribe(
+  audio: Uint8Array,
+  options: { name: string; threadId: string },
+) {
+  const token = await providerKey(cloudflareByok, options.threadId)
+  if (token === null) {
+    throw new Error(
+      'Voice needs your Cloudflare account. Run /connect cloudflare.',
+    )
+  }
+  const result = await generateTranscription({
+    adapter: createCloudflareTranscription(
+      '@cf/openai/whisper-large-v3-turbo',
+      cloudflareRest(token),
+    ),
+    audio: new File([audio.slice()], options.name),
+    ...(process.env.VOICE_LANGUAGE
+      ? { language: process.env.VOICE_LANGUAGE }
+      : {}),
+  })
+  return result.text.trim()
+}
+
+const SKIP = new Set(['node_modules', '.git', 'dist'])
+
+/** The files in `dir` and its folders, 3 levels deep. */
+async function filesIn(dir: string, depth = 0): Promise<Array<string>> {
+  if (depth > 3) return []
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => [])
+  const files: Array<string> = []
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') || SKIP.has(entry.name)) continue
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) files.push(...(await filesIn(path, depth + 1)))
+    else files.push(path)
+  }
+  return files
+}
+
+/** Spoken text in a form that file names match: "cat dot png" is "cat.png". */
+function normalize(text: string) {
+  return text
+    .toLowerCase()
+    .replace(/\s+dot\s+/g, '.')
+    .replace(/\s*\.\s*(?=[a-z0-9]{2,4}\b)/g, '.')
+}
+
+/** The media a turn made, newest last, for "the last image" and the like. */
+export interface RecentMedia {
+  kind: string
+  path: string
+}
+
+const RECENT =
+  /\b(last|latest|previous|that|this|the)\s+(image|picture|photo|video|clip|song|track|audio|sound)\b/
+
+const KIND_OF_WORD: Record<string, string> = {
+  image: 'image',
+  picture: 'image',
+  photo: 'image',
+  video: 'video',
+  clip: 'video',
+  song: 'audio',
+  track: 'audio',
+  audio: 'audio',
+  sound: 'audio',
+}
+
+/**
+ * Turn the files a user names in a voice message into `@path` attachments.
+ * A file counts when its name is in the text ("use cat dot png as a
+ * reference"), or when the text says "the last image" and the screen saved
+ * one. The CLI reads each `@path` and sends the file with the message.
+ */
+export async function withSpokenFiles(
+  text: string,
+  roots: ReadonlyArray<string>,
+  recent: ReadonlyArray<RecentMedia> = [],
+) {
+  const spoken = normalize(text)
+  const found = new Set<string>()
+  for (const root of roots) {
+    for (const file of await filesIn(root)) {
+      const name = basename(file).toLowerCase()
+      if (extname(name) !== '' && spoken.includes(name)) found.add(file)
+    }
+  }
+  const match = RECENT.exec(spoken)
+  const kind = match ? KIND_OF_WORD[match[2] ?? ''] : undefined
+  const latest = kind
+    ? [...recent].reverse().find((media) => media.kind === kind)
+    : undefined
+  if (latest) found.add(latest.path)
+  const files = [...found].map((file) => relative(process.cwd(), file))
+  const refs = files.map((file) => `@"${file}"`)
+  return { text: [text, ...refs].join(' '), files }
+}
diff --git a/examples/harness-cli-cloudflare/src/workdir.ts b/examples/harness-cli-cloudflare/src/workdir.ts
new file mode 100644
index 0000000000..581ee50c10
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/workdir.ts
@@ -0,0 +1,6 @@
+// Work in the folder where you started the app. `pnpm start` runs the
+// script in this example's folder, and keeps your folder in INIT_CWD. The
+// CLI imports this file after ./env (the .env file is in this example's
+// folder) and before the harness, which reads the folder.
+const started = process.env.INIT_CWD
+if (started) process.chdir(started)
diff --git a/examples/harness-cli-cloudflare/src/worker-config.ts b/examples/harness-cli-cloudflare/src/worker-config.ts
new file mode 100644
index 0000000000..886abb2814
--- /dev/null
+++ b/examples/harness-cli-cloudflare/src/worker-config.ts
@@ -0,0 +1,64 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import type { WorkerConnection } from './cloudflare-stores'
+
+/** The folder in your home folder for what stays on this PC. */
+export const SAVE_DIR = join(homedir(), '.tanstack-harness-cloudflare')
+
+// The Worker URL and secret stay on your PC: they are how the CLI reaches
+// everything else, which lives in the Worker.
+const FILE = join(SAVE_DIR, 'worker.json')
+
+/** The saved Worker, or `undefined` before the first start. */
+export async function loadWorker() {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(FILE, 'utf8'))
+    if (
+      typeof parsed !== 'object' ||
+      parsed === null ||
+      !('url' in parsed) ||
+      typeof parsed.url !== 'string' ||
+      !('secret' in parsed) ||
+      typeof parsed.secret !== 'string'
+    ) {
+      return undefined
+    }
+    return { url: parsed.url, secret: parsed.secret }
+  } catch {
+    return undefined
+  }
+}
+
+/** Save the Worker. The file is readable by your user only. */
+export async function saveWorker(worker: WorkerConnection) {
+  await mkdir(dirname(FILE), { recursive: true })
+  await writeFile(
+    FILE,
+    JSON.stringify({ url: worker.url, secret: worker.secret }, null, 2),
+    { mode: 0o600 },
+  )
+}
+
+// The Worker of this process. The CLI sets it before it opens a session.
+let current: WorkerConnection | undefined
+
+/** Use `worker` from now on, for the stores, code mode, and the header. */
+export function setCurrentWorker(worker: WorkerConnection) {
+  current = worker
+}
+
+/** The Worker of this process. Throws before the CLI set it. */
+export function currentWorker() {
+  if (!current) throw new Error('No Worker yet. Start the CLI to set it up.')
+  return current
+}
+
+/** The Worker's host, for the header: `tanstack-harness.acme.workers.dev`. */
+export function workerHost(worker: WorkerConnection) {
+  try {
+    return new URL(worker.url).host
+  } catch {
+    return worker.url
+  }
+}
diff --git a/examples/harness-cli-cloudflare/tsconfig.json b/examples/harness-cli-cloudflare/tsconfig.json
new file mode 100644
index 0000000000..95ef0f53d6
--- /dev/null
+++ b/examples/harness-cli-cloudflare/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "esModuleInterop": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src", "worker/tests", "vitest.config.ts"]
+}
diff --git a/examples/harness-cli-cloudflare/vitest.config.ts b/examples/harness-cli-cloudflare/vitest.config.ts
new file mode 100644
index 0000000000..e93b6395b7
--- /dev/null
+++ b/examples/harness-cli-cloudflare/vitest.config.ts
@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config'
+
+// The Worker tests start the Worker in local workerd (wrangler's test
+// harness), so the first start can take a while.
+export default defineConfig({
+  test: {
+    include: ['worker/tests/**/*.test.ts'],
+    testTimeout: 60_000,
+    hookTimeout: 180_000,
+  },
+})
diff --git a/examples/harness-cli-cloudflare/worker/src/account.ts b/examples/harness-cli-cloudflare/worker/src/account.ts
new file mode 100644
index 0000000000..0af992d5ea
--- /dev/null
+++ b/examples/harness-cli-cloudflare/worker/src/account.ts
@@ -0,0 +1,187 @@
+import { DurableObject } from 'cloudflare:workers'
+import type { Env } from './env'
+
+/** A stored row: the JSON of a value. */
+type Row = { value: string }
+
+/**
+ * The account of the CLI, in one Durable Object's SQLite storage: the
+ * settings and plugin state, the keys (encrypted by the Worker before they
+ * get here), the media records, and the list of sessions.
+ */
+export class Account extends DurableObject<Env> {
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env)
+    const sql = ctx.storage.sql
+    sql.exec(
+      'CREATE TABLE IF NOT EXISTS metadata (namespace TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, PRIMARY KEY (namespace, key))',
+    )
+    sql.exec(
+      'CREATE TABLE IF NOT EXISTS credentials (owner TEXT NOT NULL, id TEXT NOT NULL, type TEXT NOT NULL, expires_at INTEGER, value TEXT NOT NULL, PRIMARY KEY (owner, id))',
+    )
+    sql.exec(
+      'CREATE TABLE IF NOT EXISTS artifacts (id TEXT PRIMARY KEY, run_id TEXT NOT NULL, thread_id TEXT NOT NULL, created_at INTEGER NOT NULL, value TEXT NOT NULL)',
+    )
+    sql.exec(
+      'CREATE TABLE IF NOT EXISTS sessions (id TEXT PRIMARY KEY, title TEXT NOT NULL, updated_at INTEGER NOT NULL)',
+    )
+  }
+
+  private get sql() {
+    return this.ctx.storage.sql
+  }
+
+  /** The JSON of each row's value, parsed. */
+  private values(cursor: SqlStorageCursor<Row>) {
+    return cursor.toArray().map((row): unknown => JSON.parse(row.value))
+  }
+
+  getMetadata(namespace: string, key: string) {
+    const [value] = this.values(
+      this.sql.exec<Row>(
+        'SELECT value FROM metadata WHERE namespace = ? AND key = ?',
+        namespace,
+        key,
+      ),
+    )
+    return value ?? null
+  }
+
+  setMetadata(namespace: string, key: string, value: unknown) {
+    this.sql.exec(
+      'INSERT INTO metadata (namespace, key, value) VALUES (?, ?, ?) ON CONFLICT (namespace, key) DO UPDATE SET value = excluded.value',
+      namespace,
+      key,
+      JSON.stringify(value),
+    )
+  }
+
+  deleteMetadata(namespace: string, key: string) {
+    this.sql.exec(
+      'DELETE FROM metadata WHERE namespace = ? AND key = ?',
+      namespace,
+      key,
+    )
+  }
+
+  /** The sealed credential `id` of `owner`, or `null`. */
+  getCredential(owner: string, id: string) {
+    const [row] = this.sql
+      .exec<Row>(
+        'SELECT value FROM credentials WHERE owner = ? AND id = ?',
+        owner,
+        id,
+      )
+      .toArray()
+    return row?.value ?? null
+  }
+
+  /** Save a sealed credential. `expiresAt` is not secret: `list` shows it. */
+  setCredential(
+    owner: string,
+    id: string,
+    type: string,
+    expiresAt: number | null,
+    sealed: string,
+  ) {
+    this.sql.exec(
+      'INSERT INTO credentials (owner, id, type, expires_at, value) VALUES (?, ?, ?, ?, ?) ON CONFLICT (owner, id) DO UPDATE SET type = excluded.type, expires_at = excluded.expires_at, value = excluded.value',
+      owner,
+      id,
+      type,
+      expiresAt,
+      sealed,
+    )
+  }
+
+  deleteCredential(owner: string, id: string) {
+    this.sql.exec(
+      'DELETE FROM credentials WHERE owner = ? AND id = ?',
+      owner,
+      id,
+    )
+  }
+
+  /** The ids, types, and expiry times of `owner`'s keys. No values. */
+  listCredentials(owner: string) {
+    return this.sql
+      .exec<{ id: string; type: string; expiresAt: number | null }>(
+        'SELECT id, type, expires_at AS expiresAt FROM credentials WHERE owner = ? ORDER BY id',
+        owner,
+      )
+      .toArray()
+      .map(({ expiresAt, ...item }) =>
+        expiresAt === null ? item : { ...item, expiresAt },
+      )
+  }
+
+  saveArtifact(
+    id: string,
+    runId: string,
+    threadId: string,
+    createdAt: number,
+    record: unknown,
+  ) {
+    this.sql.exec(
+      'INSERT INTO artifacts (id, run_id, thread_id, created_at, value) VALUES (?, ?, ?, ?, ?) ON CONFLICT (id) DO UPDATE SET run_id = excluded.run_id, thread_id = excluded.thread_id, created_at = excluded.created_at, value = excluded.value',
+      id,
+      runId,
+      threadId,
+      createdAt,
+      JSON.stringify(record),
+    )
+  }
+
+  getArtifact(id: string) {
+    const [record] = this.values(
+      this.sql.exec<Row>('SELECT value FROM artifacts WHERE id = ?', id),
+    )
+    return record ?? null
+  }
+
+  /**
+   * The records of a run or a thread, by `createdAt`, then by id. SQLite
+   * compares TEXT as UTF-8 bytes, the order the contract asks for.
+   */
+  listArtifacts(column: 'run_id' | 'thread_id', id: string) {
+    return this.values(
+      this.sql.exec<Row>(
+        `SELECT value FROM artifacts WHERE ${column} = ? ORDER BY created_at, id`,
+        id,
+      ),
+    )
+  }
+
+  deleteArtifact(id: string) {
+    this.sql.exec('DELETE FROM artifacts WHERE id = ?', id)
+  }
+
+  deleteArtifactsForRun(runId: string) {
+    this.sql.exec('DELETE FROM artifacts WHERE run_id = ?', runId)
+  }
+
+  /**
+   * Mark session `id` as changed at `at`. Its title is what the user said
+   * first, kept from the first append that has it.
+   */
+  touchSession(id: string, title: string | undefined, at: number) {
+    this.sql.exec(
+      `INSERT INTO sessions (id, title, updated_at) VALUES (?, ?, ?)
+       ON CONFLICT (id) DO UPDATE SET updated_at = excluded.updated_at,
+         title = CASE WHEN sessions.title = '' THEN excluded.title ELSE sessions.title END`,
+      id,
+      title ?? '',
+      at,
+    )
+  }
+
+  /** The newest sessions that have a title, at most `limit`. */
+  listSessions(limit: number) {
+    return this.sql
+      .exec<{ id: string; title: string; updatedAt: number }>(
+        "SELECT id, title, updated_at AS updatedAt FROM sessions WHERE title != '' ORDER BY updated_at DESC LIMIT ?",
+        limit,
+      )
+      .toArray()
+  }
+}
diff --git a/examples/harness-cli-cloudflare/worker/src/crypto.ts b/examples/harness-cli-cloudflare/worker/src/crypto.ts
new file mode 100644
index 0000000000..e72f3d8259
--- /dev/null
+++ b/examples/harness-cli-cloudflare/worker/src/crypto.ts
@@ -0,0 +1,46 @@
+// Keys at rest: AES-GCM with a key made from the ENCRYPTION_KEY secret.
+
+const keys = new Map<string, Promise<CryptoKey>>()
+
+/** The AES key for `secret`: the SHA-256 of the secret. */
+function keyFor(secret: string) {
+  let key = keys.get(secret)
+  if (!key) {
+    key = crypto.subtle
+      .digest('SHA-256', new TextEncoder().encode(secret))
+      .then((bytes) =>
+        crypto.subtle.importKey('raw', bytes, 'AES-GCM', false, [
+          'encrypt',
+          'decrypt',
+        ]),
+      )
+    keys.set(secret, key)
+  }
+  return key
+}
+
+const toBase64 = (bytes: Uint8Array) => btoa(String.fromCharCode(...bytes))
+const fromBase64 = (text: string) =>
+  Uint8Array.from(atob(text), (char) => char.charCodeAt(0))
+
+/** Encrypt `text`. The result is `<iv>.<ciphertext>`, both base64. */
+export async function seal(secret: string, text: string) {
+  const iv = crypto.getRandomValues(new Uint8Array(12))
+  const data = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv },
+    await keyFor(secret),
+    new TextEncoder().encode(text),
+  )
+  return `${toBase64(iv)}.${toBase64(new Uint8Array(data))}`
+}
+
+/** Decrypt what {@link seal} made. A wrong secret throws. */
+export async function unseal(secret: string, sealed: string) {
+  const [iv = '', data = ''] = sealed.split('.')
+  const text = await crypto.subtle.decrypt(
+    { name: 'AES-GCM', iv: fromBase64(iv) },
+    await keyFor(secret),
+    fromBase64(data),
+  )
+  return new TextDecoder().decode(text)
+}
diff --git a/examples/harness-cli-cloudflare/worker/src/env.ts b/examples/harness-cli-cloudflare/worker/src/env.ts
new file mode 100644
index 0000000000..13a188ea1b
--- /dev/null
+++ b/examples/harness-cli-cloudflare/worker/src/env.ts
@@ -0,0 +1,16 @@
+import type codeMode from '@tanstack/ai-isolate-cloudflare/worker'
+import type { Account } from './account'
+import type { SessionLog } from './session-log'
+
+/** The bindings and secrets of the Worker (see wrangler.jsonc). */
+export interface Env {
+  SESSIONS: DurableObjectNamespace<SessionLog>
+  ACCOUNT: DurableObjectNamespace<Account>
+  MEDIA: R2Bucket
+  /** The Dynamic Workers binding that code mode runs programs with. */
+  LOADER?: Parameters<(typeof codeMode)['fetch']>[1]['LOADER']
+  /** The CLI sends it as `Authorization: Bearer <secret>`. */
+  HARNESS_SECRET: string
+  /** Encrypts the keys at rest. */
+  ENCRYPTION_KEY: string
+}
diff --git a/examples/harness-cli-cloudflare/worker/src/index.ts b/examples/harness-cli-cloudflare/worker/src/index.ts
new file mode 100644
index 0000000000..8867507833
--- /dev/null
+++ b/examples/harness-cli-cloudflare/worker/src/index.ts
@@ -0,0 +1,313 @@
+import codeMode from '@tanstack/ai-isolate-cloudflare/worker'
+import { seal, unseal } from './crypto'
+import type { Env } from './env'
+
+export { Account } from './account'
+export { SessionLog } from './session-log'
+
+const json = (value: unknown, status = 200) => Response.json(value, { status })
+const notFound = () => json({ error: 'Not found' }, 404)
+
+/** Is the request's bearer token the Worker secret? */
+function isAllowed(request: Request, env: Env) {
+  const sent = request.headers.get('Authorization') ?? ''
+  const expected = `Bearer ${env.HARNESS_SECRET}`
+  const a = new TextEncoder().encode(sent)
+  const b = new TextEncoder().encode(expected)
+  return (
+    env.HARNESS_SECRET !== '' &&
+    a.byteLength === b.byteLength &&
+    crypto.subtle.timingSafeEqual(a, b)
+  )
+}
+
+const account = (env: Env) => env.ACCOUNT.getByName('account')
+
+/** What the user said first in these log records, if a record has it. */
+function titleOf(records: Array<unknown>) {
+  for (const record of records) {
+    if (typeof record !== 'object' || record === null) continue
+    if (!('type' in record) || record.type !== 'harness.transcript') continue
+    if (!('add' in record) || !Array.isArray(record.add)) continue
+    for (const message of record.add) {
+      const isUser =
+        typeof message === 'object' &&
+        message !== null &&
+        message.role === 'user'
+      if (!isUser) continue
+      const content: unknown = message.content
+      const text =
+        typeof content === 'string'
+          ? content
+          : Array.isArray(content)
+            ? content
+                .map((part: unknown) =>
+                  typeof part === 'object' &&
+                  part !== null &&
+                  'type' in part &&
+                  part.type === 'text' &&
+                  'content' in part &&
+                  typeof part.content === 'string'
+                    ? part.content
+                    : '',
+                )
+                .join(' ')
+            : ''
+      const line = text.replace(/\s+/g, ' ').trim()
+      if (line !== '') return line.slice(0, 200)
+    }
+  }
+  return undefined
+}
+
+/** The metadata of an R2 object, in the shape of a `BlobRecord`. */
+function blobRecord(object: R2Object) {
+  const created = Number(object.customMetadata?.['x-created-at'])
+  const { 'x-created-at': _created, ...customMetadata } =
+    object.customMetadata ?? {}
+  return {
+    key: object.key,
+    size: object.size,
+    etag: object.etag,
+    ...(object.httpMetadata?.contentType
+      ? { contentType: object.httpMetadata.contentType }
+      : {}),
+    customMetadata,
+    createdAt: Number.isFinite(created) ? created : object.uploaded.getTime(),
+    updatedAt: object.uploaded.getTime(),
+  }
+}
+
+async function sessions(request: Request, env: Env, parts: Array<string>) {
+  const url = new URL(request.url)
+  const [threadId, what] = parts
+  if (threadId === undefined) {
+    const limit = Number(url.searchParams.get('limit') ?? 20)
+    return json({ sessions: await account(env).listSessions(limit) })
+  }
+  if (what !== 'log') return notFound()
+  const log = env.SESSIONS.getByName(threadId)
+  if (request.method === 'GET') {
+    const after = Number(url.searchParams.get('after') ?? 0)
+    const limit = url.searchParams.get('limit')
+    return json({
+      entries: await log.read(
+        after,
+        limit === null ? undefined : Number(limit),
+      ),
+    })
+  }
+  if (request.method !== 'POST') return notFound()
+  const body: { seq: number; records: Array<unknown> } = await request.json()
+  const written = await log.append(body.seq, body.records)
+  if (!written) return json({ error: 'conflict', seq: body.seq }, 409)
+  // Child agents (`<session>:<agent>`) are not sessions of their own.
+  if (body.records.length > 0 && !threadId.includes(':')) {
+    await account(env).touchSession(threadId, titleOf(body.records), Date.now())
+  }
+  return json({ ok: true })
+}
+
+async function metadata(request: Request, env: Env, parts: Array<string>) {
+  const [namespace, key] = parts
+  if (namespace === undefined || key === undefined) return notFound()
+  const store = account(env)
+  if (request.method === 'GET') {
+    return json({ value: await store.getMetadata(namespace, key) })
+  }
+  if (request.method === 'PUT') {
+    const body: { value: unknown } = await request.json()
+    await store.setMetadata(namespace, key, body.value)
+    return json({ ok: true })
+  }
+  if (request.method === 'DELETE') {
+    await store.deleteMetadata(namespace, key)
+    return json({ ok: true })
+  }
+  return notFound()
+}
+
+async function credentials(request: Request, env: Env, parts: Array<string>) {
+  const [owner, id] = parts
+  if (owner === undefined) return notFound()
+  const store = account(env)
+  if (id === undefined) {
+    return json({ items: await store.listCredentials(owner) })
+  }
+  if (request.method === 'GET') {
+    const sealed = await store.getCredential(owner, id)
+    const credential: unknown =
+      sealed === null
+        ? null
+        : JSON.parse(await unseal(env.ENCRYPTION_KEY, sealed))
+    return json({ credential })
+  }
+  if (request.method === 'PUT') {
+    const body: { credential: { type: string; expiresAt?: number } } =
+      await request.json()
+    const sealed = await seal(
+      env.ENCRYPTION_KEY,
+      JSON.stringify(body.credential),
+    )
+    await store.setCredential(
+      owner,
+      id,
+      body.credential.type,
+      body.credential.expiresAt ?? null,
+      sealed,
+    )
+    return json({ ok: true })
+  }
+  if (request.method === 'DELETE') {
+    await store.deleteCredential(owner, id)
+    return json({ ok: true })
+  }
+  return notFound()
+}
+
+async function artifacts(request: Request, env: Env, parts: Array<string>) {
+  const url = new URL(request.url)
+  const [id] = parts
+  const store = account(env)
+  if (id === undefined) {
+    const runId = url.searchParams.get('runId')
+    const threadId = url.searchParams.get('threadId')
+    if (request.method === 'DELETE' && runId !== null) {
+      await store.deleteArtifactsForRun(runId)
+      return json({ ok: true })
+    }
+    if (runId !== null)
+      return json({ records: await store.listArtifacts('run_id', runId) })
+    if (threadId !== null)
+      return json({ records: await store.listArtifacts('thread_id', threadId) })
+    return notFound()
+  }
+  if (request.method === 'GET') {
+    return json({ record: await store.getArtifact(id) })
+  }
+  if (request.method === 'PUT') {
+    const body: {
+      record: { runId: string; threadId: string; createdAt: number }
+    } = await request.json()
+    await store.saveArtifact(
+      id,
+      body.record.runId,
+      body.record.threadId,
+      body.record.createdAt,
+      body.record,
+    )
+    return json({ ok: true })
+  }
+  if (request.method === 'DELETE') {
+    await store.deleteArtifact(id)
+    return json({ ok: true })
+  }
+  return notFound()
+}
+
+async function blobs(request: Request, env: Env, parts: Array<string>) {
+  const url = new URL(request.url)
+  const [key] = parts
+  if (key === undefined) {
+    const limit = url.searchParams.get('limit')
+    if (limit === '0') return json({ objects: [] })
+    const prefix = url.searchParams.get('prefix')
+    const cursor = url.searchParams.get('cursor')
+    // The cursor is the last key of the page: the next page starts after it.
+    const page = await env.MEDIA.list({
+      ...(prefix ? { prefix } : {}),
+      ...(cursor ? { startAfter: cursor } : {}),
+      ...(limit ? { limit: Number(limit) } : {}),
+      include: ['httpMetadata', 'customMetadata'],
+    })
+    const last = page.objects.at(-1)
+    return json({
+      objects: page.objects.map(blobRecord),
+      ...(page.truncated && last ? { truncated: true, cursor: last.key } : {}),
+    })
+  }
+  if (request.method === 'PUT') {
+    const before = await env.MEDIA.head(key)
+    const createdAt =
+      before?.customMetadata?.['x-created-at'] ?? String(Date.now())
+    const customMetadata: Record<string, string> = JSON.parse(
+      request.headers.get('x-blob-metadata') ?? '{}',
+    )
+    const contentType = request.headers.get('Content-Type')
+    const object = await env.MEDIA.put(key, request.body, {
+      ...(contentType ? { httpMetadata: { contentType } } : {}),
+      customMetadata: { ...customMetadata, 'x-created-at': createdAt },
+    })
+    return json(blobRecord(object))
+  }
+  if (request.method === 'DELETE') {
+    await env.MEDIA.delete(key)
+    return json({ ok: true })
+  }
+  if (url.searchParams.get('head') === '1') {
+    const object = await env.MEDIA.head(key)
+    return json({ record: object ? blobRecord(object) : null })
+  }
+  const offset = url.searchParams.get('offset')
+  const length = url.searchParams.get('length')
+  const object = await env.MEDIA.get(key, {
+    ...(offset === null
+      ? {}
+      : {
+          range: {
+            offset: Number(offset),
+            ...(length === null ? {} : { length: Number(length) }),
+          },
+        }),
+  })
+  if (object === null) return notFound()
+  const served =
+    offset === null
+      ? undefined
+      : {
+          offset: Number(offset),
+          length: Math.min(
+            length === null ? object.size : Number(length),
+            object.size - Number(offset),
+          ),
+        }
+  return new Response(object.body, {
+    headers: {
+      'x-blob-record': JSON.stringify(blobRecord(object)),
+      ...(served ? { 'x-blob-range': JSON.stringify(served) } : {}),
+    },
+  })
+}
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    if (!isAllowed(request, env)) {
+      return json(
+        { error: 'Send the Worker secret: Authorization: Bearer <secret>' },
+        401,
+      )
+    }
+    const [route, ...parts] = new URL(request.url).pathname
+      .split('/')
+      .filter((part) => part !== '')
+      .map((part) => decodeURIComponent(part))
+    switch (route) {
+      case 'health':
+        return json({ ok: true, name: 'tanstack-harness' })
+      case 'sessions':
+        return sessions(request, env, parts)
+      case 'metadata':
+        return metadata(request, env, parts)
+      case 'credentials':
+        return credentials(request, env, parts)
+      case 'artifacts':
+        return artifacts(request, env, parts)
+      case 'blobs':
+        return blobs(request, env, parts)
+      case 'code-mode':
+        return codeMode.fetch(request, env, ctx)
+      default:
+        return notFound()
+    }
+  },
+} satisfies ExportedHandler<Env>
diff --git a/examples/harness-cli-cloudflare/worker/src/session-log.ts b/examples/harness-cli-cloudflare/worker/src/session-log.ts
new file mode 100644
index 0000000000..0f80db14fe
--- /dev/null
+++ b/examples/harness-cli-cloudflare/worker/src/session-log.ts
@@ -0,0 +1,58 @@
+import { DurableObject } from 'cloudflare:workers'
+import type { Env } from './env'
+
+/**
+ * The log of one session, in this Durable Object's SQLite storage. A
+ * Durable Object runs one request at a time, and the check and the writes
+ * of an append run with no await between them, so two appends never mix.
+ */
+export class SessionLog extends DurableObject<Env> {
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env)
+    ctx.storage.sql.exec(
+      'CREATE TABLE IF NOT EXISTS log (seq INTEGER PRIMARY KEY, record TEXT NOT NULL)',
+    )
+  }
+
+  /** The last position, or 0 for an empty log. */
+  private last() {
+    const row = this.ctx.storage.sql
+      .exec<{ last: number }>('SELECT COALESCE(MAX(seq), 0) AS last FROM log')
+      .one()
+    return row.last
+  }
+
+  /**
+   * Write `records` at `seq`, `seq + 1`, and so on, all or none. `false`
+   * when `seq` is not the next free position.
+   */
+  append(seq: number, records: Array<unknown>) {
+    if (records.length === 0) return true
+    if (seq !== this.last() + 1) return false
+    this.ctx.storage.transactionSync(() => {
+      for (const [index, record] of records.entries()) {
+        this.ctx.storage.sql.exec(
+          'INSERT INTO log (seq, record) VALUES (?, ?)',
+          seq + index,
+          JSON.stringify(record),
+        )
+      }
+    })
+    return true
+  }
+
+  /** The entries after `after`, at most `limit` of them. */
+  read(after: number, limit?: number) {
+    const rows = this.ctx.storage.sql
+      .exec<{ seq: number; record: string }>(
+        'SELECT seq, record FROM log WHERE seq > ? ORDER BY seq LIMIT ?',
+        after,
+        limit ?? -1,
+      )
+      .toArray()
+    return rows.map((row) => {
+      const record: unknown = JSON.parse(row.record)
+      return { seq: row.seq, record }
+    })
+  }
+}
diff --git a/examples/harness-cli-cloudflare/worker/tests/conformance.test.ts b/examples/harness-cli-cloudflare/worker/tests/conformance.test.ts
new file mode 100644
index 0000000000..eae9569b16
--- /dev/null
+++ b/examples/harness-cli-cloudflare/worker/tests/conformance.test.ts
@@ -0,0 +1,32 @@
+import { fileURLToPath } from 'node:url'
+import { afterAll } from 'vitest'
+import { defineAIPersistence } from '@tanstack/ai-persistence'
+import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
+import { createTestHarness } from 'wrangler'
+import { workerStores } from '../../src/cloudflare-stores'
+
+// The CLI's stores, against the real Worker in local workerd. The runs,
+// approvals, inputs, and generation runs stay in the CLI's memory, so the
+// Worker does not have them.
+const SECRET = 'conformance-secret'
+const server = createTestHarness({
+  root: fileURLToPath(new URL('..', import.meta.url)),
+  workers: [
+    {
+      configPath: 'wrangler.jsonc',
+      secrets: { HARNESS_SECRET: SECRET, ENCRYPTION_KEY: 'conformance-key' },
+    },
+  ],
+})
+afterAll(() => server.close())
+
+runPersistenceConformance(
+  'the Cloudflare Worker',
+  async () => {
+    const { url } = await server.listen()
+    return defineAIPersistence({
+      stores: workerStores({ url: url.toString(), secret: SECRET }),
+    })
+  },
+  { skip: ['messages', 'runs', 'interrupts', 'generationRuns', 'inbox'] },
+)
diff --git a/examples/harness-cli-cloudflare/worker/tests/crypto.test.ts b/examples/harness-cli-cloudflare/worker/tests/crypto.test.ts
new file mode 100644
index 0000000000..9efef15cf1
--- /dev/null
+++ b/examples/harness-cli-cloudflare/worker/tests/crypto.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+import { seal, unseal } from '../src/crypto'
+
+describe('seal', () => {
+  it('gives back the text with the same secret, and hides it at rest', async () => {
+    const sealed = await seal('secret-a', '{"type":"api_key","value":"sk-123"}')
+    expect(sealed).not.toContain('sk-123')
+    expect(await unseal('secret-a', sealed)).toBe(
+      '{"type":"api_key","value":"sk-123"}',
+    )
+  })
+
+  it('makes a new ciphertext each time', async () => {
+    expect(await seal('secret-a', 'same')).not.toBe(
+      await seal('secret-a', 'same'),
+    )
+  })
+
+  it('refuses another secret', async () => {
+    const sealed = await seal('secret-a', 'value')
+    await expect(unseal('secret-b', sealed)).rejects.toThrow()
+  })
+})
diff --git a/examples/harness-cli-cloudflare/worker/tests/routes.test.ts b/examples/harness-cli-cloudflare/worker/tests/routes.test.ts
new file mode 100644
index 0000000000..fdd1edeb0c
--- /dev/null
+++ b/examples/harness-cli-cloudflare/worker/tests/routes.test.ts
@@ -0,0 +1,158 @@
+import { fileURLToPath } from 'node:url'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { createTestHarness } from 'wrangler'
+
+const SECRET = 'test-secret'
+const server = createTestHarness({
+  root: fileURLToPath(new URL('..', import.meta.url)),
+  workers: [
+    {
+      configPath: 'wrangler.jsonc',
+      secrets: { HARNESS_SECRET: SECRET, ENCRYPTION_KEY: 'test-key' },
+    },
+  ],
+})
+let base: URL
+beforeAll(async () => {
+  base = (await server.listen()).url
+})
+afterAll(() => server.close())
+
+/** A request to the Worker, with the secret unless another one is given. */
+function call(path: string, init: RequestInit = {}, secret = SECRET) {
+  return fetch(new URL(path, base), {
+    ...init,
+    headers: { Authorization: `Bearer ${secret}`, ...init.headers },
+  })
+}
+
+/** A JSON request to the Worker. */
+const send = (path: string, method: string, body: unknown) =>
+  call(path, {
+    method,
+    body: JSON.stringify(body),
+    headers: { 'Content-Type': 'application/json' },
+  })
+
+/** A transcript record with one user message, as the harness writes it. */
+const userTurn = (content: string) => ({
+  type: 'harness.transcript',
+  keep: 0,
+  add: [{ role: 'user', content }],
+})
+
+describe('the Worker', () => {
+  it('refuses a request without the secret', async () => {
+    expect((await call('/health', {}, '')).status).toBe(401)
+    expect((await call('/health', {}, 'wrong')).status).toBe(401)
+    expect(
+      (await call('/code-mode', { method: 'POST', body: '{}' }, 'wrong'))
+        .status,
+    ).toBe(401)
+    expect(await (await call('/health')).json()).toEqual({
+      ok: true,
+      name: 'tanstack-harness',
+    })
+  })
+
+  it('appends in order, and refuses a position that is taken or skipped', async () => {
+    const log = '/sessions/append-test/log'
+    expect(
+      (await send(log, 'POST', { seq: 1, records: ['a', 'b'] })).status,
+    ).toBe(200)
+    expect((await send(log, 'POST', { seq: 2, records: ['x'] })).status).toBe(
+      409,
+    )
+    expect((await send(log, 'POST', { seq: 5, records: ['x'] })).status).toBe(
+      409,
+    )
+    expect((await send(log, 'POST', { seq: 3, records: ['c'] })).status).toBe(
+      200,
+    )
+
+    expect(await (await call(`${log}?after=0`)).json()).toEqual({
+      entries: [
+        { seq: 1, record: 'a' },
+        { seq: 2, record: 'b' },
+        { seq: 3, record: 'c' },
+      ],
+    })
+    expect(await (await call(`${log}?after=1&limit=1`)).json()).toEqual({
+      entries: [{ seq: 2, record: 'b' }],
+    })
+  })
+
+  it('lists sessions by what the user said first, newest first', async () => {
+    await send('/sessions/list-old/log', 'POST', {
+      seq: 1,
+      records: [userTurn('write the release notes')],
+    })
+    await send('/sessions/list-new/log', 'POST', {
+      seq: 1,
+      records: [userTurn('fix the  failing\ntest')],
+    })
+    await send('/sessions/list-new/log', 'POST', {
+      seq: 2,
+      records: [userTurn('and then lint')],
+    })
+    await send(
+      `/sessions/${encodeURIComponent('list-new:codex')}/log`,
+      'POST',
+      {
+        seq: 1,
+        records: [userTurn('a child agent')],
+      },
+    )
+
+    const { sessions } = await (await call('/sessions?limit=10')).json()
+    const listed = sessions.filter((session: { id: string }) =>
+      session.id.startsWith('list-'),
+    )
+    expect(
+      listed.map((session: { id: string; title: string }) => [
+        session.id,
+        session.title,
+      ]),
+    ).toEqual([
+      ['list-new', 'fix the failing test'],
+      ['list-old', 'write the release notes'],
+    ])
+  })
+
+  it('keeps a key and gives it back', async () => {
+    const credential = { type: 'api_key', value: 'cf-token-123' }
+    await send('/credentials/-%2F-/cloudflare', 'PUT', { credential })
+    expect(await (await call('/credentials/-%2F-/cloudflare')).json()).toEqual({
+      credential,
+    })
+    expect(await (await call('/credentials/-%2F-')).json()).toEqual({
+      items: [{ id: 'cloudflare', type: 'api_key' }],
+    })
+    await call('/credentials/-%2F-/cloudflare', { method: 'DELETE' })
+    expect(await (await call('/credentials/-%2F-/cloudflare')).json()).toEqual({
+      credential: null,
+    })
+  })
+
+  it('serves a slice of a blob, with the whole size', async () => {
+    const put = await call('/blobs/media%2Fclip.txt', {
+      method: 'PUT',
+      body: '0123456789',
+      headers: { 'Content-Type': 'text/plain' },
+    })
+    expect(await put.json()).toMatchObject({ key: 'media/clip.txt', size: 10 })
+
+    const slice = await call('/blobs/media%2Fclip.txt?offset=2&length=3')
+    expect(await slice.text()).toBe('234')
+    expect(
+      JSON.parse(slice.headers.get('x-blob-record') ?? '{}'),
+    ).toMatchObject({
+      size: 10,
+      contentType: 'text/plain',
+    })
+    expect(JSON.parse(slice.headers.get('x-blob-range') ?? '{}')).toEqual({
+      offset: 2,
+      length: 3,
+    })
+  })
+})
diff --git a/examples/harness-cli-cloudflare/worker/tsconfig.json b/examples/harness-cli-cloudflare/worker/tsconfig.json
new file mode 100644
index 0000000000..61652e5f16
--- /dev/null
+++ b/examples/harness-cli-cloudflare/worker/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "types": ["@cloudflare/workers-types/2023-07-01"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}
diff --git a/examples/harness-cli-cloudflare/worker/wrangler.jsonc b/examples/harness-cli-cloudflare/worker/wrangler.jsonc
new file mode 100644
index 0000000000..56950dacf2
--- /dev/null
+++ b/examples/harness-cli-cloudflare/worker/wrangler.jsonc
@@ -0,0 +1,31 @@
+{
+  "$schema": "../node_modules/wrangler/config-schema.json",
+  // The Worker of the Cloudflare harness CLI: the sessions, the settings,
+  // the keys, and the media, plus code mode at /code-mode.
+  "name": "tanstack-harness",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-05-01",
+  "compatibility_flags": ["nodejs_compat"],
+  "durable_objects": {
+    "bindings": [
+      // One Durable Object for each session log.
+      { "name": "SESSIONS", "class_name": "SessionLog" },
+      // One Durable Object for the settings, the keys, the media records,
+      // and the session list.
+      { "name": "ACCOUNT", "class_name": "Account" },
+    ],
+  },
+  "migrations": [
+    { "tag": "v1", "new_sqlite_classes": ["SessionLog", "Account"] },
+  ],
+  // The bytes of the files you send and the files agents make.
+  "r2_buckets": [
+    { "binding": "MEDIA", "bucket_name": "tanstack-harness-media" },
+  ],
+  // Code mode runs each program in a new isolate (Dynamic Workers). A deploy
+  // needs the Workers Paid plan. `wrangler dev` works on the Free plan.
+  "worker_loaders": [{ "binding": "LOADER" }],
+  // Secrets: HARNESS_SECRET (the CLI sends it on every request) and
+  // ENCRYPTION_KEY (encrypts the keys at rest). Set them with
+  // `wrangler secret put`, or in .dev.vars for `wrangler dev`.
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f0e8e9e116..bc2539dfdb 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -268,6 +268,94 @@ importers:
         specifier: ^4.23.12
         version: 4.23.12
 
+  examples/harness-cli-cloudflare:
+    dependencies:
+      '@tanstack/ai':
+        specifier: workspace:*
+        version: link:../../packages/ai
+      '@tanstack/ai-acp':
+        specifier: workspace:*
+        version: link:../../packages/ai-acp
+      '@tanstack/ai-claude-code':
+        specifier: workspace:*
+        version: link:../../packages/ai-claude-code
+      '@tanstack/ai-cloudflare':
+        specifier: workspace:*
+        version: link:../../packages/ai-cloudflare
+      '@tanstack/ai-code-mode':
+        specifier: workspace:*
+        version: link:../../packages/ai-code-mode
+      '@tanstack/ai-codex':
+        specifier: workspace:*
+        version: link:../../packages/ai-codex
+      '@tanstack/ai-dashboard':
+        specifier: workspace:*
+        version: link:../../packages/ai-dashboard
+      '@tanstack/ai-harness':
+        specifier: workspace:*
+        version: link:../../packages/ai-harness
+      '@tanstack/ai-harness-cli':
+        specifier: workspace:*
+        version: link:../../packages/ai-harness-cli
+      '@tanstack/ai-isolate-cloudflare':
+        specifier: workspace:*
+        version: link:../../packages/ai-isolate-cloudflare
+      '@tanstack/ai-mcp':
+        specifier: workspace:*
+        version: link:../../packages/ai-mcp
+      '@tanstack/ai-models':
+        specifier: workspace:*
+        version: link:../../packages/ai-models
+      '@tanstack/ai-persistence':
+        specifier: workspace:*
+        version: link:../../packages/ai-persistence
+      '@tanstack/ai-sandbox':
+        specifier: workspace:*
+        version: link:../../packages/ai-sandbox
+      '@tanstack/ai-sandbox-local-process':
+        specifier: workspace:*
+        version: link:../../packages/ai-sandbox-local-process
+      '@tanstack/ai-skills':
+        specifier: workspace:*
+        version: link:../../packages/ai-skills
+      '@tanstack/react-store':
+        specifier: ^0.11.1
+        version: 0.11.1(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      beautiful-mermaid:
+        specifier: ^1.1.3
+        version: 1.1.3
+      ink:
+        specifier: ^7.1.1
+        version: 7.1.1(@types/react@19.3.0)(react-devtools-core@6.1.5)(react@19.2.3)
+      marked:
+        specifier: ^15.0.6
+        version: 15.0.12
+      marked-terminal:
+        specifier: ^7.3.0
+        version: 7.3.0(marked@15.0.12)
+      react:
+        specifier: ^19.2.3
+        version: 19.2.3
+      zod:
+        specifier: ^4.2.0
+        version: 4.3.6
+    devDependencies:
+      '@cloudflare/workers-types':
+        specifier: ^4.20260317.1
+        version: 4.20260317.1
+      '@types/node':
+        specifier: ^24.10.1
+        version: 24.13.6
+      '@types/react':
+        specifier: ^19.2.7
+        version: 19.3.0
+      tsx:
+        specifier: ^4.23.12
+        version: 4.23.12
+      wrangler:
+        specifier: ^4.103.0
+        version: 4.103.0(@cloudflare/workers-types@4.20260317.1)
+
   examples/react/basic-chat:
     dependencies:
       '@tailwindcss/vite':
@@ -30872,7 +30960,7 @@ snapshots:
       parse5: 7.3.0
       parse5-htmlparser2-tree-adapter: 7.1.0
       parse5-parser-stream: 7.1.2
-      undici: 7.29.0
+      undici: 7.29.1
       whatwg-mimetype: 4.0.0
 
   chokidar@3.6.0:

From 7770101c59b176d872fec0d4111deb5e1eac74e1 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 16:06:12 +0200
Subject: [PATCH 131/286] feat(ai-harness): keep started tool calls in the log

The log keeps the tool calls that started (harness.tool.started), so batch repair works without a run store. A finished call keeps its result, a replay: 'never' call gets the tool error, and a safe call runs again.
---
 packages/ai-harness/src/log.ts           | 25 +++++++
 packages/ai-harness/src/resume.ts        | 11 +++
 packages/ai-harness/src/session.ts       | 21 ++++--
 packages/ai-harness/tests/leases.test.ts | 95 ++++++++++++++++++++++++
 4 files changed, 144 insertions(+), 8 deletions(-)

diff --git a/packages/ai-harness/src/log.ts b/packages/ai-harness/src/log.ts
index 8095fbf42a..5b232f06ac 100644
--- a/packages/ai-harness/src/log.ts
+++ b/packages/ai-harness/src/log.ts
@@ -46,6 +46,12 @@ export type HarnessRecord =
       error?: InputSettlement['error']
     }
   | { type: 'harness.tool.result'; toolCallId: string; message: ModelMessage }
+  | {
+      type: 'harness.tool.started'
+      toolCallId: string
+      name: string
+      replay: 'safe' | 'never'
+    }
   | {
       type: 'harness.tool.step'
       toolCallId: string
@@ -63,6 +69,7 @@ const HARNESS_RECORD_TYPES = new Set<string>([
   'harness.input.abort',
   'harness.input.settled',
   'harness.tool.result',
+  'harness.tool.started',
   'harness.tool.step',
 ])
 
@@ -118,6 +125,8 @@ export interface LogState {
   /** In admission order. */
   inputs: Map<string, InputState>
   toolResults: Map<string, ModelMessage>
+  /** Tool calls that started, by toolCallId. Batch repair reads them. */
+  started: Map<string, { name: string; replay: 'safe' | 'never' }>
   /** By {@link stepKey}. */
   steps: Map<string, unknown>
 }
@@ -128,6 +137,7 @@ export function emptyLogState() {
     messages: [],
     inputs: new Map(),
     toolResults: new Map(),
+    started: new Map(),
     steps: new Map(),
   }
   return state
@@ -268,6 +278,12 @@ export function foldEntry(
     case 'harness.tool.result':
       state.toolResults.set(record.toolCallId, record.message)
       return
+    case 'harness.tool.started':
+      state.started.set(record.toolCallId, {
+        name: record.name,
+        replay: record.replay,
+      })
+      return
     case 'harness.tool.step':
       state.steps.set(stepKey(record.toolCallId, record.name), record.value)
       return
@@ -370,6 +386,7 @@ function serialize(state: SharedLogState, versions: CheckpointVersions) {
         messages: session.messages,
         inputs: [...session.inputs.values()],
         toolResults: [...session.toolResults.entries()],
+        started: [...session.started.entries()],
         steps: [...session.steps.entries()],
       },
     ]),
@@ -395,6 +412,14 @@ function parseSession(value: unknown, seq: number) {
       (inputs as Array<InputState>).map((input) => [input.inputId, input]),
     ),
     toolResults: new Map(toolResults as Array<[string, ModelMessage]>),
+    // A checkpoint from before `started` has none.
+    started: new Map(
+      Array.isArray(value.started)
+        ? (value.started as Array<
+            [string, { name: string; replay: 'safe' | 'never' }]
+          >)
+        : [],
+    ),
     steps: new Map(steps as Array<[string, unknown]>),
   }
   return session
diff --git a/packages/ai-harness/src/resume.ts b/packages/ai-harness/src/resume.ts
index 002c521c43..6d55f78ea0 100644
--- a/packages/ai-harness/src/resume.ts
+++ b/packages/ai-harness/src/resume.ts
@@ -46,6 +46,12 @@ export function checkpointMiddleware(options: {
   messages: MessageStore
   hostId: string
   lease?: LeaseOptions
+  /** Called before each tool call runs, after its checkpoint is saved. */
+  onToolStart?: (info: {
+    toolCallId: string
+    name: string
+    replay: 'safe' | 'never'
+  }) => void | Promise<void>
   /** Called after each tool call ends, with the tool message the model gets. */
   onToolResult?: (info: {
     toolCallId: string
@@ -99,6 +105,11 @@ export function checkpointMiddleware(options: {
         replay: hook.tool?.replay ?? 'never',
       })
       await saveCheckpoint(ctx.runId, entry.pending)
+      await options.onToolStart?.({
+        toolCallId: hook.toolCallId,
+        name: hook.toolName,
+        replay: hook.tool?.replay ?? 'never',
+      })
     },
     async onAfterToolCall(ctx, info) {
       const entry = state.get(ctx)
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index da15fc192f..48d8b27317 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -604,6 +604,10 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       // the batch does not lose it.
       ...(writer
         ? {
+            onToolStart: ({ toolCallId, name, replay }) =>
+              writer.append([
+                { type: 'harness.tool.started', toolCallId, name, replay },
+              ]),
             onToolResult: ({ toolCallId, message }) =>
               writer.append([
                 { type: 'harness.tool.result', toolCallId, message },
@@ -2722,14 +2726,15 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       } else if (hasFinalAnswer(writer.state.messages, input.appliedAt ?? 0)) {
         await ended({ outcome: 'completed' })
       } else {
-        if (run) {
-          await repairTranscript({
-            messages: this.messages,
-            threadId: this.threadId,
-            pending: run.checkpoint?.pendingTools ?? [],
-            finished: writer.state.toolResults,
-          })
-        }
+        const started = [...writer.state.started]
+          .filter(([toolCallId]) => !writer.state.toolResults.has(toolCallId))
+          .map(([toolCallId, tool]) => ({ toolCallId, ...tool }))
+        await repairTranscript({
+          messages: this.messages,
+          threadId: this.threadId,
+          pending: [...(run?.checkpoint?.pendingTools ?? []), ...started],
+          finished: writer.state.toolResults,
+        })
         const operation = this.createTurnOperation()
         this.bindTurn(input.inputId, operation)
         this.feed.publish(
diff --git a/packages/ai-harness/tests/leases.test.ts b/packages/ai-harness/tests/leases.test.ts
index 0fb59813f1..e8f23df31f 100644
--- a/packages/ai-harness/tests/leases.test.ts
+++ b/packages/ai-harness/tests/leases.test.ts
@@ -3,6 +3,7 @@ import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness } from '../src'
 import { toolDefinition } from '@tanstack/ai'
 import { z } from 'zod'
+import { INTERRUPTED_TOOL_RESULT } from '../src/resume'
 import { after, gate, mockAdapter, text, toolCall } from './helpers'
 import type { AnyTool, StreamChunk } from '@tanstack/ai'
 import { EventType } from '@tanstack/ai'
@@ -107,6 +108,8 @@ describe('a durable host with a lease store and no run store', () => {
     await vi.waitFor(() => expect(leases.calls).toContain('renew in-1:1'))
     hold.open()
     await turn
+    // A timer that the release did not stop would renew again in this time.
+    await new Promise((resolve) => setTimeout(resolve, 30))
 
     const release = leases.calls.indexOf('release in-1:1')
     expect(release).toBeGreaterThan(-1)
@@ -173,6 +176,98 @@ describe('a durable host with a lease store and no run store', () => {
     await next.host.close()
   })
 
+  it('repairs a cut batch from the log', async () => {
+    const leases = memoryLeases()
+    const persistence = leasedPersistence(leases.store)
+    const mailStarted = gate()
+    const charge = vi.fn(async () => 'charged')
+    const tools = [
+      toolDefinition({ name: 'charge', description: 'Charge' }).server(charge),
+      toolDefinition({ name: 'mail', description: 'Mail' }).server(
+        async (_args, context) => {
+          mailStarted.open()
+          // Wait like a host that stopped, until the call is aborted at close.
+          return new Promise<never>((_resolve, reject) => {
+            context?.abortSignal?.addEventListener(
+              'abort',
+              () => reject(new Error('stopped')),
+              { once: true },
+            )
+          })
+        },
+      ),
+    ]
+    const twoCalls: Reply = () => {
+      const now = Date.now()
+      return [
+        {
+          type: EventType.RUN_STARTED,
+          runId: 'r',
+          threadId: 't',
+          timestamp: now,
+        },
+        ...['charge', 'mail'].flatMap(
+          (name): Array<StreamChunk> => [
+            {
+              type: EventType.TOOL_CALL_START,
+              toolCallId: `call-${name}`,
+              toolCallName: name,
+              timestamp: now,
+            },
+            {
+              type: EventType.TOOL_CALL_ARGS,
+              toolCallId: `call-${name}`,
+              delta: '{}',
+              timestamp: now,
+            },
+            {
+              type: EventType.TOOL_CALL_END,
+              toolCallId: `call-${name}`,
+              timestamp: now,
+            },
+          ],
+        ),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: 'r',
+          threadId: 't',
+          timestamp: now,
+          metadata: { tanstack: { finishReason: 'tool_calls' } },
+        },
+      ]
+    }
+    const first = await openLeased(persistence, [twoCalls], tools)
+    first.session.prompt('charge and mail', { inputId: 'batch-1' })
+    await mailStarted.opened
+    await vi.waitFor(async () =>
+      expect(
+        (await persistence.stores.log.read(THREAD)).filter(
+          (entry) => entry.record.type === 'harness.tool.result',
+        ),
+      ).toHaveLength(1),
+    )
+    leases.expire()
+
+    const next = await openLeased(persistence, [() => text('done')], tools)
+    await next.session.settled('batch-1')
+
+    const results = (await next.session.transcript()).filter(
+      (message) => message.role === 'tool',
+    )
+    expect(results).toEqual([
+      { role: 'tool', toolCallId: 'call-charge', content: 'charged' },
+      {
+        role: 'tool',
+        toolCallId: 'call-mail',
+        content: JSON.stringify(INTERRUPTED_TOOL_RESULT),
+        error: INTERRUPTED_TOOL_RESULT.note,
+      },
+    ])
+    expect(charge).toHaveBeenCalledTimes(1)
+    await first.host.close().catch(() => {})
+    await next.host.close()
+  })
+
   it('throws a clear error for a durable host with neither runs nor leases', () => {
     expect(() =>
       createHarnessHost({

From a7f238834d43924ddca1cd36052adc19b3827e49 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 16:14:38 +0200
Subject: [PATCH 132/286] feat(ai-harness): types for the turn hooks

src/turn.ts has the types of the recover, model error, finish, and join hooks, and defineHarness takes turn options. The next commits call the hooks.
---
 packages/ai-harness/src/define.ts |   3 +
 packages/ai-harness/src/index.ts  |  12 ++++
 packages/ai-harness/src/turn.ts   | 111 ++++++++++++++++++++++++++++++
 3 files changed, 126 insertions(+)
 create mode 100644 packages/ai-harness/src/turn.ts

diff --git a/packages/ai-harness/src/define.ts b/packages/ai-harness/src/define.ts
index 66b371c939..14237d6506 100644
--- a/packages/ai-harness/src/define.ts
+++ b/packages/ai-harness/src/define.ts
@@ -11,6 +11,7 @@ import type {
 import type { AnyAgent } from './agents'
 import type { MediaOptions } from './media'
 import type { HarnessPlugin } from './plugins'
+import type { HarnessTurnOptions } from './turn'
 import type { BusyPolicy } from './types'
 
 /** The `subagents` option: the same as `chat({ subagents })`. */
@@ -82,6 +83,8 @@ export interface HarnessConfig<
   busy?: BusyPolicy
   /** Attempt and time limits for each input on a durable host. */
   durability?: HarnessDurability
+  /** Hooks that control a chat turn: retries, joins, and the end of a turn. */
+  turn?: HarnessTurnOptions
   /**
    * Files sent to a turn, and media agents make: the size limit, the kinds a
    * user can send, the kinds the model reads, and an optional transcriber for
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index 37a9e46040..038d6448f4 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -91,6 +91,18 @@ export type {
   SessionSnapshot,
 } from './session'
 
+export type {
+  FinishContext,
+  HarnessTurnOptions,
+  JoinCandidate,
+  JoinContext,
+  ModelErrorContext,
+  RecoverContext,
+  RecoverDecision,
+  RecoverHook,
+  TurnAdditions,
+} from './turn'
+
 export { HARNESS_EVENTS, InputRejectedError } from './types'
 export type {
   BusyPolicy,
diff --git a/packages/ai-harness/src/turn.ts b/packages/ai-harness/src/turn.ts
new file mode 100644
index 0000000000..d547f4a544
--- /dev/null
+++ b/packages/ai-harness/src/turn.ts
@@ -0,0 +1,111 @@
+import type { ModelMessage } from '@tanstack/ai'
+import type { LogRecord } from '@tanstack/ai-persistence'
+import type { HarnessSession } from './session'
+import type { HarnessInput, UserInput } from './types'
+
+/** What recovery does with one input. */
+export type RecoverDecision =
+  | { action: 'run' }
+  | {
+      action: 'settle'
+      outcome: 'completed' | 'failed' | 'aborted'
+      error?: { message: string; code?: string }
+    }
+
+/** What `durability.recover` gets for one input. */
+export interface RecoverContext {
+  session: HarnessSession
+  input: {
+    inputId: string
+    input: HarnessInput
+    attempt: number
+    timeoutAt?: number
+    abortRequested: boolean
+    operationId?: string
+  }
+  /** The transcript of the session, from the log. */
+  messages: ReadonlyArray<ModelMessage>
+  /** What the harness does when the hook returns `undefined`. */
+  decision: RecoverDecision
+}
+
+/** Decide how an input that a crashed host left recovers. */
+export type RecoverHook = (
+  ctx: RecoverContext,
+) => RecoverDecision | undefined | Promise<RecoverDecision | undefined>
+
+/** Messages and host records that a turn hook adds, in one append. */
+export interface TurnAdditions {
+  /** Messages after the transcript, for the next model call. */
+  messages?: Array<ModelMessage>
+  /** Host records in the same append. A durable host only. */
+  records?: ReadonlyArray<LogRecord>
+}
+
+/** What `turn.onModelError` gets. */
+export interface ModelErrorContext {
+  session: HarnessSession
+  operationId: string
+  inputId?: string
+  error: { message: string; code?: string }
+  /** Retries since the last finished tool phase of this operation. */
+  retries: number
+  /** Aborted when the turn is cancelled. */
+  signal: AbortSignal
+}
+
+/** What `turn.beforeFinish` gets. */
+export interface FinishContext {
+  session: HarnessSession
+  operationId: string
+  inputId?: string
+  /** How many times this hook continued the turn so far. */
+  cycle: number
+  messages: ReadonlyArray<ModelMessage>
+  signal: AbortSignal
+}
+
+/** An input that waits to join the running turn. */
+export interface JoinCandidate {
+  inputId: string
+  message: UserInput
+}
+
+/** What `turn.onJoin` gets. */
+export interface JoinContext {
+  session: HarnessSession
+  operationId: string
+  /** The inputs that join now, in admission order. */
+  inputs: ReadonlyArray<JoinCandidate>
+  signal: AbortSignal
+}
+
+/** Hooks that control a chat turn. */
+export interface HarnessTurnOptions {
+  /**
+   * A run of the turn failed (a `RUN_ERROR`, or an error thrown by the run).
+   * Return `'retry'` to run the model again in the same operation, after any
+   * work (a backoff, a compaction record). See `retryTransientErrors`.
+   */
+  onModelError?: (
+    ctx: ModelErrorContext,
+  ) => 'retry' | undefined | Promise<'retry' | undefined>
+  /**
+   * The model stopped calling tools and the turn would end. Return messages
+   * or records to send the model back to work in the same turn.
+   */
+  beforeFinish?: (
+    ctx: FinishContext,
+  ) => TurnAdditions | undefined | Promise<TurnAdditions | undefined>
+  /** How many times `beforeFinish` can continue one turn. Default 32. */
+  maxFinishCycles?: number
+  /**
+   * Whether a waiting input joins the running turn now. A refused input
+   * stops the join: it and the inputs after it wait.
+   */
+  canJoin?: (candidate: JoinCandidate) => boolean | Promise<boolean>
+  /** Runs before the model call that the joined inputs reach. */
+  onJoin?: (
+    ctx: JoinContext,
+  ) => TurnAdditions | undefined | Promise<TurnAdditions | undefined>
+}

From ce14a533b4d0842489d66bceda8102010ca71ea3 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 16:35:15 +0200
Subject: [PATCH 133/286] feat(ai-harness): a recover hook for durable inputs

defineHarness({ durability: { recover } }) decides how an input that a crashed host left recovers. The hook gets the decision the harness takes by default (abort, attempts, time limit, final answer, next attempt) and can settle the input or run it.
---
 packages/ai-harness/src/define.ts             |   8 +-
 packages/ai-harness/src/session.ts            | 141 ++++++++++++------
 .../ai-harness/tests/durable-inputs.test.ts   |  83 +++++++++++
 packages/ai-harness/tests/types.test-d.ts     |   4 +-
 4 files changed, 187 insertions(+), 49 deletions(-)

diff --git a/packages/ai-harness/src/define.ts b/packages/ai-harness/src/define.ts
index 14237d6506..959b116d06 100644
--- a/packages/ai-harness/src/define.ts
+++ b/packages/ai-harness/src/define.ts
@@ -11,7 +11,7 @@ import type {
 import type { AnyAgent } from './agents'
 import type { MediaOptions } from './media'
 import type { HarnessPlugin } from './plugins'
-import type { HarnessTurnOptions } from './turn'
+import type { HarnessTurnOptions, RecoverHook } from './turn'
 import type { BusyPolicy } from './types'
 
 /** The `subagents` option: the same as `chat({ subagents })`. */
@@ -37,6 +37,12 @@ export interface HarnessDurability {
    * timeout.
    */
   timeoutMs?: number
+  /**
+   * Decide how an input that a crashed host left recovers: an input that
+   * never ran, and a turn whose lease expired. The context has the decision
+   * the harness takes by default. Return `undefined` to keep it.
+   */
+  recover?: RecoverHook
 }
 
 /**
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 48d8b27317..9bdac5e1c9 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -59,7 +59,7 @@ import type {
 } from '@tanstack/ai-persistence'
 import type { AuthRequiredError, CredentialsAccess } from './auth'
 import type { EventFeed } from './feed'
-import type { LogWriter, ProjectOptions } from './log'
+import type { InputState, LogWriter, ProjectOptions } from './log'
 import type { DurableBind } from './durable-tool'
 import type { LeaseOptions } from './resume'
 import type { MediaStore } from './media'
@@ -72,6 +72,7 @@ import type {
   AnyAgent,
 } from './agents'
 import type { AnyHarness, HarnessAgentsOf } from './define'
+import type { RecoverDecision } from './turn'
 import type { HarnessPersistence } from './host'
 import type {
   AgentGroup,
@@ -2641,6 +2642,32 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }
   }
 
+  /** The recovery decision for `input`: the hook's, or `decision`. */
+  private async recoverDecision(
+    writer: LogWriter,
+    input: InputState,
+    decision: RecoverDecision,
+  ): Promise<RecoverDecision> {
+    const recover = this.harness.durability?.recover
+    if (!recover) return decision
+    const answer = await recover({
+      session: this,
+      input: {
+        inputId: input.inputId,
+        input: input.input,
+        attempt: input.attempt,
+        ...(input.timeoutAt !== undefined
+          ? { timeoutAt: input.timeoutAt }
+          : {}),
+        abortRequested: input.abortRequested,
+        ...(input.operationId ? { operationId: input.operationId } : {}),
+      },
+      messages: [...writer.state.messages],
+      decision,
+    })
+    return answer ?? decision
+  }
+
   /**
    * Recover a durable session from its log, input by input, in admission
    * order. A chat turn whose host stopped (its run lease expired) settles
@@ -2656,17 +2683,28 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     for (const input of inputs) {
       const isChat = CHAT_OPS.has(input.input.op)
       if (input.status === 'pending') {
-        if (isChat && 'message' in input.input) {
-          const operation = this.createTurnOperation()
-          this.bindTurn(input.inputId, operation)
-          this.enqueueTurn({
-            operation,
-            message: input.input.message,
+        if (!(isChat && 'message' in input.input)) {
+          this.reject(input.inputId, 'expired_on_restart')
+          continue
+        }
+        const decision = await this.recoverDecision(writer, input, {
+          action: 'run',
+        })
+        if (decision.action === 'settle') {
+          await this.settle({
             inputId: input.inputId,
+            outcome: decision.outcome,
+            ...(decision.error ? { error: decision.error } : {}),
           })
-        } else {
-          this.reject(input.inputId, 'expired_on_restart')
+          continue
         }
+        const operation = this.createTurnOperation()
+        this.bindTurn(input.inputId, operation)
+        this.enqueueTurn({
+          operation,
+          message: input.input.message,
+          inputId: input.inputId,
+        })
         continue
       }
       if (input.status !== 'applied' || !isChat) continue
@@ -2705,47 +2743,56 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             ...settlement,
           })),
         )
-      if (input.abortRequested) {
-        await ended({ outcome: 'aborted' })
-      } else if (input.attempt >= maxAttempts) {
+      const fallback: RecoverDecision = input.abortRequested
+        ? { action: 'settle', outcome: 'aborted' }
+        : input.attempt >= maxAttempts
+          ? {
+              action: 'settle',
+              outcome: 'failed',
+              error: {
+                message: `The input stopped the host ${input.attempt} times.`,
+                code: 'attempts_exhausted',
+              },
+            }
+          : input.timeoutAt !== undefined && now >= input.timeoutAt
+            ? {
+                action: 'settle',
+                outcome: 'failed',
+                error: {
+                  message: 'The input passed its time limit.',
+                  code: 'timeout',
+                },
+              }
+            : hasFinalAnswer(writer.state.messages, input.appliedAt ?? 0)
+              ? { action: 'settle', outcome: 'completed' }
+              : { action: 'run' }
+      const decision = await this.recoverDecision(writer, input, fallback)
+      if (decision.action === 'settle') {
         await ended({
-          outcome: 'failed',
-          error: {
-            message: `The input stopped the host ${input.attempt} times.`,
-            code: 'attempts_exhausted',
-          },
+          outcome: decision.outcome,
+          ...(decision.error ? { error: decision.error } : {}),
         })
-      } else if (input.timeoutAt !== undefined && now >= input.timeoutAt) {
-        await ended({
-          outcome: 'failed',
-          error: {
-            message: 'The input passed its time limit.',
-            code: 'timeout',
-          },
-        })
-      } else if (hasFinalAnswer(writer.state.messages, input.appliedAt ?? 0)) {
-        await ended({ outcome: 'completed' })
-      } else {
-        const started = [...writer.state.started]
-          .filter(([toolCallId]) => !writer.state.toolResults.has(toolCallId))
-          .map(([toolCallId, tool]) => ({ toolCallId, ...tool }))
-        await repairTranscript({
-          messages: this.messages,
-          threadId: this.threadId,
-          pending: [...(run?.checkpoint?.pendingTools ?? []), ...started],
-          finished: writer.state.toolResults,
-        })
-        const operation = this.createTurnOperation()
-        this.bindTurn(input.inputId, operation)
-        this.feed.publish(
-          operation.id,
-          customEvent(HARNESS_EVENTS.operationResumed, {
-            operationId: operation.id,
-            ...(operationId ? { resumedFrom: operationId } : {}),
-          }),
-        )
-        this.enqueueTurn({ operation, inputId: input.inputId })
+        continue
       }
+      const started = [...writer.state.started]
+        .filter(([toolCallId]) => !writer.state.toolResults.has(toolCallId))
+        .map(([toolCallId, tool]) => ({ toolCallId, ...tool }))
+      await repairTranscript({
+        messages: this.messages,
+        threadId: this.threadId,
+        pending: [...(run?.checkpoint?.pendingTools ?? []), ...started],
+        finished: writer.state.toolResults,
+      })
+      const operation = this.createTurnOperation()
+      this.bindTurn(input.inputId, operation)
+      this.feed.publish(
+        operation.id,
+        customEvent(HARNESS_EVENTS.operationResumed, {
+          operationId: operation.id,
+          ...(operationId ? { resumedFrom: operationId } : {}),
+        }),
+      )
+      this.enqueueTurn({ operation, inputId: input.inputId })
     }
   }
 }
diff --git a/packages/ai-harness/tests/durable-inputs.test.ts b/packages/ai-harness/tests/durable-inputs.test.ts
index 5e891bf9ac..f2217238e6 100644
--- a/packages/ai-harness/tests/durable-inputs.test.ts
+++ b/packages/ai-harness/tests/durable-inputs.test.ts
@@ -189,6 +189,89 @@ describe('recovery of a durable input', () => {
     expect(calls).toHaveLength(0)
     await host.close()
   })
+
+  it('settles an input with the recover hook that the default would run again', async () => {
+    const persistence = durablePersistence()
+    await seedStoppedTurn(persistence, { attempt: 1 })
+    const seen: Array<unknown> = []
+
+    const { host, session, calls } = await openDurable({
+      persistence,
+      replies: [() => text('never')],
+      durability: {
+        recover: ({ input, decision }) => {
+          seen.push({
+            inputId: input.inputId,
+            attempt: input.attempt,
+            decision,
+          })
+          return {
+            action: 'settle',
+            outcome: 'failed',
+            error: { message: 'The host gave up.', code: 'host_rule' },
+          }
+        },
+      },
+    })
+
+    expect(await session.settled('in-1')).toEqual({
+      inputId: 'in-1',
+      outcome: 'failed',
+      operationId: 'op-stopped',
+      error: { message: 'The host gave up.', code: 'host_rule' },
+    })
+    expect(seen).toEqual([
+      { inputId: 'in-1', attempt: 1, decision: { action: 'run' } },
+    ])
+    expect(calls).toHaveLength(0)
+    await host.close()
+  })
+
+  it('runs an input with the recover hook that the default would settle', async () => {
+    const persistence = durablePersistence()
+    await seedStoppedTurn(persistence, { attempt: 1, answer: 'old answer' })
+
+    const { host, session, calls } = await openDurable({
+      persistence,
+      replies: [() => text('new answer')],
+      durability: {
+        recover: ({ decision }) =>
+          decision.action === 'settle' && decision.outcome === 'completed'
+            ? { action: 'run' }
+            : undefined,
+      },
+    })
+
+    expect(await session.settled('in-1')).toMatchObject({
+      outcome: 'completed',
+    })
+    expect(calls).toHaveLength(1)
+    await host.close()
+  })
+
+  it('asks the recover hook about an input that never ran', async () => {
+    const persistence = durablePersistence()
+    await persistence.stores.log.append(THREAD, 1, [
+      {
+        type: 'harness.input',
+        inputId: 'in-new',
+        input: { op: 'prompt', message: 'later', busy: 'queue' },
+        at: 1,
+      },
+    ])
+
+    const { host, session, calls } = await openDurable({
+      persistence,
+      replies: [() => text('never')],
+      durability: { recover: () => ({ action: 'settle', outcome: 'aborted' }) },
+    })
+
+    expect(await session.settled('in-new')).toMatchObject({
+      outcome: 'aborted',
+    })
+    expect(calls).toHaveLength(0)
+    await host.close()
+  })
 })
 
 describe('durable input limits while a turn runs', () => {
diff --git a/packages/ai-harness/tests/types.test-d.ts b/packages/ai-harness/tests/types.test-d.ts
index 4650ac1577..084c7eb9e7 100644
--- a/packages/ai-harness/tests/types.test-d.ts
+++ b/packages/ai-harness/tests/types.test-d.ts
@@ -9,6 +9,7 @@ import type {
   HarnessSession,
   Operation,
   Receipt,
+  RecoverHook,
 } from '../src'
 import type { InputSettlement } from '../src/types'
 
@@ -76,6 +77,7 @@ it('describes how an input ended', () => {
 
 it('takes attempt and time limits on the harness', () => {
   expectTypeOf<HarnessConfig['durability']>().toEqualTypeOf<
-    { maxAttempts?: number; timeoutMs?: number } | undefined
+    | { maxAttempts?: number; timeoutMs?: number; recover?: RecoverHook }
+    | undefined
   >()
 })

From efc4e59938b3583a2ba9c0f6534834bf0b23dd1e Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 16:35:15 +0200
Subject: [PATCH 134/286] feat(ai-harness): retryTransientErrors and
 isTransientModelError

A ready turn.onModelError policy. It retries 429, 5xx, overloaded, network errors, and timeouts, with a 2 s exponential backoff and jitter.
---
 packages/ai-harness/src/index.ts              |   1 +
 packages/ai-harness/src/turn.ts               |  65 ++++++++++
 .../ai-harness/tests/transient-errors.test.ts | 116 ++++++++++++++++++
 3 files changed, 182 insertions(+)
 create mode 100644 packages/ai-harness/tests/transient-errors.test.ts

diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index 038d6448f4..d9918b95e9 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -102,6 +102,7 @@ export type {
   RecoverHook,
   TurnAdditions,
 } from './turn'
+export { isTransientModelError, retryTransientErrors } from './turn'
 
 export { HARNESS_EVENTS, InputRejectedError } from './types'
 export type {
diff --git a/packages/ai-harness/src/turn.ts b/packages/ai-harness/src/turn.ts
index d547f4a544..85a973e927 100644
--- a/packages/ai-harness/src/turn.ts
+++ b/packages/ai-harness/src/turn.ts
@@ -109,3 +109,68 @@ export interface HarnessTurnOptions {
     ctx: JoinContext,
   ) => TurnAdditions | undefined | Promise<TurnAdditions | undefined>
 }
+
+// ponytail: the patterns of Flue's isRetryableModelError. A qualified finish
+// reason (error_quota, content_filter) stays terminal. The status codes need
+// word boundaries, or the 500 in "250000 tokens" would match.
+const TRANSIENT_ERROR =
+  /overloaded|rate.?limit|too many requests|\b(?:429|500|502|503|504)\b|service.?unavailable|server.?error|network.?error|connection.?(?:reset|refused|lost|error)|socket hang up|fetch failed|timed? out|timeout|terminated|provider finish_reason:\s*error(?![-\w])/i
+
+/**
+ * True for a model error that can pass when you try again: overloaded, rate
+ * limits, 429 and 5xx, network and connection errors, timeouts, and a
+ * provider `finish_reason: error`.
+ */
+export function isTransientModelError(error: {
+  message: string
+  code?: string
+}): boolean {
+  return (
+    TRANSIENT_ERROR.test(error.message) ||
+    (error.code !== undefined && TRANSIENT_ERROR.test(error.code))
+  )
+}
+
+/** Resolve after `ms`, or at once when `signal` aborts. */
+function wait(ms: number, signal: AbortSignal) {
+  return new Promise<void>((resolve) => {
+    if (signal.aborted) return resolve()
+    const done = () => {
+      clearTimeout(timer)
+      signal.removeEventListener('abort', done)
+      resolve()
+    }
+    const timer = setTimeout(done, ms)
+    signal.addEventListener('abort', done, { once: true })
+  })
+}
+
+/**
+ * A `turn.onModelError` policy: retry a transient model error after a
+ * backoff of `baseDelayMs * 2^retries`, times a jitter from 0.75 to 1.0.
+ *
+ * @example
+ * ```ts
+ * defineHarness({ ..., turn: { onModelError: retryTransientErrors() } })
+ * ```
+ */
+export function retryTransientErrors(
+  options: {
+    /** Retries after the last finished tool phase. Default 3. */
+    maxRetries?: number
+    /** The first delay, in milliseconds. Default 2000. */
+    baseDelayMs?: number
+    /** Default {@link isTransientModelError}. */
+    isTransient?: (error: { message: string; code?: string }) => boolean
+  } = {},
+) {
+  const maxRetries = options.maxRetries ?? 3
+  const baseDelayMs = options.baseDelayMs ?? 2_000
+  const isTransient = options.isTransient ?? isTransientModelError
+  return async (ctx: ModelErrorContext): Promise<'retry' | undefined> => {
+    if (ctx.retries >= maxRetries || !isTransient(ctx.error)) return undefined
+    const jitter = 0.75 + Math.random() * 0.25
+    await wait(Math.round(baseDelayMs * 2 ** ctx.retries * jitter), ctx.signal)
+    return ctx.signal.aborted ? undefined : 'retry'
+  }
+}
diff --git a/packages/ai-harness/tests/transient-errors.test.ts b/packages/ai-harness/tests/transient-errors.test.ts
new file mode 100644
index 0000000000..ff603cc639
--- /dev/null
+++ b/packages/ai-harness/tests/transient-errors.test.ts
@@ -0,0 +1,116 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { isTransientModelError, retryTransientErrors } from '../src'
+import type { ModelErrorContext } from '../src'
+
+afterEach(() => {
+  vi.useRealTimers()
+  vi.restoreAllMocks()
+})
+
+const context = (message: string, retries = 0): ModelErrorContext => ({
+  // The policy reads only the error, the retries, and the signal.
+  session: undefined as never,
+  operationId: 'op-1',
+  error: { message },
+  retries,
+  signal: new AbortController().signal,
+})
+
+describe('isTransientModelError', () => {
+  it.each([
+    'Overloaded',
+    'Rate limit exceeded',
+    'Too Many Requests',
+    '429 status code',
+    '500 Internal Server Error',
+    '502 Bad Gateway',
+    '503 Service Unavailable',
+    '504 Gateway Timeout',
+    'network error',
+    'connection reset by peer',
+    'socket hang up',
+    'fetch failed',
+    'request timed out',
+    'terminated',
+    'Provider finish_reason: error',
+  ])('treats "%s" as transient', (message) => {
+    expect(isTransientModelError({ message })).toBe(true)
+  })
+
+  it.each([
+    'prompt is too long: 250000 tokens > 200000 maximum',
+    'Invalid API key',
+    'Provider finish_reason: error_quota',
+    'Provider finish_reason: content_filter',
+  ])('treats "%s" as terminal', (message) => {
+    expect(isTransientModelError({ message })).toBe(false)
+  })
+
+  it('reads the error code too', () => {
+    expect(
+      isTransientModelError({ message: 'failed', code: 'rate_limit_exceeded' }),
+    ).toBe(true)
+  })
+})
+
+describe('retryTransientErrors', () => {
+  it('waits base * 2^retries, times the jitter, then retries', async () => {
+    vi.useFakeTimers()
+    vi.spyOn(Math, 'random').mockReturnValue(1)
+    const policy = retryTransientErrors({ maxRetries: 3, baseDelayMs: 1_000 })
+
+    let answer: string | undefined = 'pending'
+    void policy(context('503 Service Unavailable', 1)).then((value) => {
+      answer = value
+    })
+    await vi.advanceTimersByTimeAsync(1_999)
+    expect(answer).toBe('pending')
+    await vi.advanceTimersByTimeAsync(1)
+    expect(answer).toBe('retry')
+  })
+
+  it('uses the smallest jitter of 0.75', async () => {
+    vi.useFakeTimers()
+    vi.spyOn(Math, 'random').mockReturnValue(0)
+    const policy = retryTransientErrors({ baseDelayMs: 2_000 })
+
+    let answer: string | undefined = 'pending'
+    void policy(context('overloaded')).then((value) => {
+      answer = value
+    })
+    await vi.advanceTimersByTimeAsync(1_499)
+    expect(answer).toBe('pending')
+    await vi.advanceTimersByTimeAsync(1)
+    expect(answer).toBe('retry')
+  })
+
+  it('gives up after maxRetries, and at once for a terminal error', async () => {
+    const policy = retryTransientErrors({ maxRetries: 2, baseDelayMs: 1 })
+
+    expect(await policy(context('overloaded', 2))).toBeUndefined()
+    expect(await policy(context('Invalid API key'))).toBeUndefined()
+  })
+
+  it('stops the wait when the turn is cancelled', async () => {
+    const policy = retryTransientErrors({ baseDelayMs: 60_000 })
+    const controller = new AbortController()
+    const answer = policy({
+      ...context('overloaded'),
+      signal: controller.signal,
+    })
+
+    controller.abort()
+
+    expect(await answer).toBeUndefined()
+  })
+
+  it('takes its own transient check', async () => {
+    const policy = retryTransientErrors({
+      baseDelayMs: 1,
+      isTransient: (error) => error.message.includes('[retry-me]'),
+    })
+
+    expect(await policy(context('boom [retry-me]'))).toBe('retry')
+    expect(await policy(context('overloaded'))).toBeUndefined()
+  })
+})

From 467e77ab1076c8bb8821b3629cb49ba791193225 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 16:56:43 +0200
Subject: [PATCH 135/286] feat(ai-harness): retry a failed model call in the
 same turn

defineHarness({ turn: { onModelError } }) can answer 'retry' after a failed run: the error event is held back and chat() runs again in the same operation.
---
 packages/ai-harness/src/session.ts            | 229 ++++++++++++------
 packages/ai-harness/src/types.ts              |   2 +
 .../ai-harness/tests/turn-control.test.ts     | 186 ++++++++++++++
 3 files changed, 342 insertions(+), 75 deletions(-)
 create mode 100644 packages/ai-harness/tests/turn-control.test.ts

diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 9bdac5e1c9..bd8e65525e 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -255,6 +255,9 @@ function customEvent(
   return { type: EventType.CUSTOM, name, value, timestamp: Date.now() }
 }
 
+const errorText = (error: unknown) =>
+  error instanceof Error ? error.message : String(error)
+
 /** A short transcript note about an agent result, for the next turn. */
 function referenceNote(agent: string, result: unknown): string {
   const body =
@@ -1857,85 +1860,161 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         throw new Error('The session is not open yet.')
       }
       const durableTools = this.durableTools()
+      const turnHooks = this.harness.turn
+      const signal = operation.abortController.signal
+      /** Retries since the last finished tool phase. */
+      let retries = 0
       // One chat() run, and one more each time steers wait after a final
-      // answer: a late join gets its answer in this turn.
+      // answer: a late join gets its answer in this turn. A run that failed
+      // runs again when `turn.onModelError` answers 'retry'.
       for (;;) {
-        const stream = chat({
-          adapter,
-          messages: message ? [message] : [],
-          systemPrompts: [
-            ...(this.harness.systemPrompts ?? []),
-            ...[...(session?.prompts ?? []), ...(runPlugins?.prompts ?? [])]
-              .map(resolvePrompt)
-              .filter((prompt) => prompt !== ''),
-          ],
-          tools,
-          middleware: [
-            ...bridges,
-            withPersistence(chatPersistence),
-            checkpoint,
-            ...(this.harness.middleware ?? []),
-            ...(session?.middleware ?? []),
-            ...(runPlugins?.middleware ?? []),
-            ...(durableTools ? [durableTools] : []),
-            this.steering(),
-            // Last, because a later middleware that returns `messages` (as
-            // steering does) resets what the model gets.
-            mediaMiddleware({
-              store: this.mediaStore,
-              accepted: acceptedKinds(
-                adapter.inputModalities,
-                this.harness.media?.accepts,
-              ),
-              transcribe: this.harness.media?.transcribe,
-            }),
-          ],
-          ...(subagentList.length > 0
-            ? {
-                subagents: {
-                  ...this.harness.subagents,
-                  agents: subagentList,
-                  limits: this.limits(),
-                  binding: this.binding(operation, captured, runPlugins),
-                },
+        const textBefore = text
+        let runError: { message: string; code?: string } | undefined
+        let heldError: StreamChunk | undefined
+        try {
+          const stream = chat({
+            adapter,
+            messages: message ? [message] : [],
+            systemPrompts: [
+              ...(this.harness.systemPrompts ?? []),
+              ...[...(session?.prompts ?? []), ...(runPlugins?.prompts ?? [])]
+                .map(resolvePrompt)
+                .filter((prompt) => prompt !== ''),
+            ],
+            tools,
+            middleware: [
+              ...bridges,
+              withPersistence(chatPersistence),
+              checkpoint,
+              ...(this.harness.middleware ?? []),
+              ...(session?.middleware ?? []),
+              ...(runPlugins?.middleware ?? []),
+              ...(durableTools ? [durableTools] : []),
+              this.steering(),
+              // Last, because a later middleware that returns `messages` (as
+              // steering does) resets what the model gets.
+              mediaMiddleware({
+                store: this.mediaStore,
+                accepted: acceptedKinds(
+                  adapter.inputModalities,
+                  this.harness.media?.accepts,
+                ),
+                transcribe: this.harness.media?.transcribe,
+              }),
+            ],
+            ...(subagentList.length > 0
+              ? {
+                  subagents: {
+                    ...this.harness.subagents,
+                    agents: subagentList,
+                    limits: this.limits(),
+                    binding: this.binding(operation, captured, runPlugins),
+                  },
+                }
+              : {}),
+            // chat() stops after 5 model calls by default. An agent that
+            // reads, searches, and calls tools needs more before it can answer.
+            agentLoopStrategy:
+              this.harness.agentLoopStrategy ?? maxIterations(50),
+            ...(this.harness.modelOptions !== undefined
+              ? { modelOptions: this.harness.modelOptions }
+              : {}),
+            ...(this.harness.interrupts
+              ? { interrupts: this.harness.interrupts }
+              : {}),
+            ...(this.harness.context !== undefined
+              ? { context: this.harness.context }
+              : {}),
+            threadId: this.threadId,
+            runId: operation.id,
+            ...(parentRunId ? { parentRunId } : {}),
+            ...(resume ? { resume } : {}),
+            abortController: operation.abortController,
+            stream: true,
+          } as never) as AsyncIterable<StreamChunk>
+
+          for await (const chunk of stream) {
+            if (
+              chunk.type === EventType.RUN_ERROR &&
+              turnHooks?.onModelError &&
+              runError === undefined
+            ) {
+              // Held until the hook answers: a retried call shows no error.
+              runError = {
+                message: chunk.message,
+                ...(chunk.code !== undefined ? { code: chunk.code } : {}),
               }
-            : {}),
-          // chat() stops after 5 model calls by default. An agent that reads,
-          // searches, and calls tools needs more before it can answer.
-          agentLoopStrategy:
-            this.harness.agentLoopStrategy ?? maxIterations(50),
-          ...(this.harness.modelOptions !== undefined
-            ? { modelOptions: this.harness.modelOptions }
-            : {}),
-          ...(this.harness.interrupts
-            ? { interrupts: this.harness.interrupts }
-            : {}),
-          ...(this.harness.context !== undefined
-            ? { context: this.harness.context }
-            : {}),
-          threadId: this.threadId,
-          runId: operation.id,
-          ...(parentRunId ? { parentRunId } : {}),
-          ...(resume ? { resume } : {}),
-          abortController: operation.abortController,
-          stream: true,
-        } as never) as AsyncIterable<StreamChunk>
-
-        for await (const chunk of stream) {
-          operation.publish(chunk)
-          if (
-            chunk.type === EventType.TEXT_MESSAGE_CONTENT &&
-            !('subagentRunId' in chunk && chunk.subagentRunId)
-          ) {
-            text += chunk.delta
+              heldError = chunk
+              continue
+            }
+            operation.publish(chunk)
+            if (
+              chunk.type === EventType.TEXT_MESSAGE_CONTENT &&
+              !('subagentRunId' in chunk && chunk.subagentRunId)
+            ) {
+              text += chunk.delta
+            }
+            if (
+              chunk.type === EventType.RUN_FINISHED &&
+              chunk.outcome?.type === 'interrupt'
+            ) {
+              interrupts = chunk.outcome.interrupts
+            }
+            if (chunk.type === EventType.RUN_ERROR) failure = chunk.message
+            // A finished tool phase resets the retries. Streamed text does
+            // not, so a call that fails after some text still counts.
+            if (chunk.type === EventType.TOOL_CALL_RESULT) retries = 0
           }
-          if (
-            chunk.type === EventType.RUN_FINISHED &&
-            chunk.outcome?.type === 'interrupt'
-          ) {
-            interrupts = chunk.outcome.interrupts
+        } catch (error) {
+          // The outer catch handles a cancelled turn, a log failure, and a
+          // harness without the hook, as before.
+          if (signal.aborted || this.logFailure || !turnHooks?.onModelError) {
+            throw error
           }
-          if (chunk.type === EventType.RUN_ERROR) failure = chunk.message
+          runError = { message: errorText(error) }
+        }
+        if (runError && turnHooks?.onModelError) {
+          const answer =
+            signal.aborted || this.logFailure
+              ? undefined
+              : await turnHooks.onModelError({
+                  session: this,
+                  operationId: operation.id,
+                  ...(turn.inputId ? { inputId: turn.inputId } : {}),
+                  error: runError,
+                  retries,
+                  signal,
+                })
+          if (answer === 'retry' && !signal.aborted) {
+            retries += 1
+            // The turn result has only the text of the calls that counted.
+            text = textBefore
+            operation.publish(
+              customEvent(HARNESS_EVENTS.turnRetry, {
+                operationId: operation.id,
+                retries,
+                error: runError,
+              }),
+            )
+            message = undefined
+            resume = undefined
+            parentRunId = undefined
+            // withPersistence failed the run. It runs again, for the retry.
+            await this.persistence.stores.runs?.update(operation.id, {
+              status: 'running',
+            })
+            continue
+          }
+          // Here, and not in the outer catch, for an error the run threw.
+          operation.publish(
+            heldError ?? {
+              type: EventType.RUN_ERROR,
+              message: runError.message,
+              timestamp: Date.now(),
+            },
+          )
+          failure = runError.message
+          break
         }
         const hasLateJoin =
           this.steerQueue.length > 0 &&
@@ -1952,7 +2031,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         })
       }
     } catch (error) {
-      failure = error instanceof Error ? error.message : String(error)
+      failure = errorText(error)
       if (!operation.abortController.signal.aborted) {
         operation.publish({
           type: EventType.RUN_ERROR,
diff --git a/packages/ai-harness/src/types.ts b/packages/ai-harness/src/types.ts
index f941a60ea7..fc79e8113c 100644
--- a/packages/ai-harness/src/types.ts
+++ b/packages/ai-harness/src/types.ts
@@ -182,4 +182,6 @@ export const HARNESS_EVENTS = {
   inputSettled: 'harness.input.settled',
   /** A media file was stored. The value is a `MediaRecord`. */
   media: 'harness.media',
+  /** A turn runs the model again after an error. The value has `retries` and `error`. */
+  turnRetry: 'harness.turn.retry',
 } as const
diff --git a/packages/ai-harness/tests/turn-control.test.ts b/packages/ai-harness/tests/turn-control.test.ts
new file mode 100644
index 0000000000..57f794d1b1
--- /dev/null
+++ b/packages/ai-harness/tests/turn-control.test.ts
@@ -0,0 +1,186 @@
+import { describe, expect, it } from 'vitest'
+import { EventType, isContextOverflow } from '@tanstack/ai'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness, retryTransientErrors } from '../src'
+import { messageTexts, mockAdapter, text } from './helpers'
+import type { StreamChunk } from '@tanstack/ai'
+import type { HarnessTurnOptions, ProjectOptions } from '../src'
+import type { Reply } from './helpers'
+
+const THREAD = 't1'
+
+/** A model call that ends with a RUN_ERROR. */
+const failsWith =
+  (message: string, partial?: string): Reply =>
+  () => [
+    {
+      type: EventType.RUN_STARTED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: Date.now(),
+    },
+    ...(partial
+      ? ([
+          {
+            type: EventType.TEXT_MESSAGE_START,
+            messageId: 'p',
+            role: 'assistant',
+            timestamp: Date.now(),
+          },
+          {
+            type: EventType.TEXT_MESSAGE_CONTENT,
+            messageId: 'p',
+            delta: partial,
+            timestamp: Date.now(),
+          },
+        ] satisfies Array<StreamChunk>)
+      : []),
+    { type: EventType.RUN_ERROR, message, timestamp: Date.now() },
+  ]
+
+/** A model call whose adapter throws. */
+const throws =
+  (message: string): Reply =>
+  () =>
+    (async function* (): AsyncGenerator<StreamChunk> {
+      yield {
+        type: EventType.RUN_STARTED,
+        runId: 'r',
+        threadId: 't',
+        timestamp: Date.now(),
+      }
+      throw new Error(message)
+    })()
+
+/** Compaction: the summary replaces the whole transcript. */
+const project: ProjectOptions = {
+  record: ({ record }) =>
+    record.type === 'app.compaction' && typeof record.summary === 'string'
+      ? [{ role: 'user', content: record.summary }]
+      : undefined,
+}
+
+async function open(options: {
+  replies: Array<Reply> | Reply
+  turn: HarnessTurnOptions
+  durable?: boolean
+}) {
+  const { adapter, calls } = mockAdapter(options.replies)
+  const { runs, metadata } = memoryPersistence().stores
+  const host = options.durable
+    ? createHarnessHost({
+        persistence: { stores: { log: memoryLogStore(), runs, metadata } },
+        project,
+      })
+    : createHarnessHost({ persistence: memoryPersistence() })
+  const session = await host.open(
+    defineHarness({ name: 'test/turn-control', adapter, turn: options.turn }),
+    { threadId: THREAD },
+  )
+  return { host, session, calls }
+}
+
+/** The events of one operation, as `type` or `type:name`. */
+async function eventsOf(
+  session: Awaited<ReturnType<typeof open>>['session'],
+  operationId: string,
+) {
+  const seen: Array<string> = []
+  for await (const entry of session.events({
+    signal: AbortSignal.timeout(200),
+  })) {
+    if (entry.operationId !== operationId) continue
+    seen.push(
+      entry.event.type === EventType.CUSTOM
+        ? `CUSTOM:${entry.event.name}`
+        : entry.event.type,
+    )
+  }
+  return seen
+}
+
+describe('turn.onModelError', () => {
+  it('compacts after an overflow, retries once, and succeeds', async () => {
+    const { host, session, calls } = await open({
+      durable: true,
+      replies: [
+        failsWith('prompt is too long: 250000 tokens > 200000 maximum'),
+        () => text('fits now'),
+      ],
+      turn: {
+        onModelError: async ({ session: current, error, retries }) => {
+          if (retries > 0 || !isContextOverflow({ error: error.message }))
+            return
+          await current.append([
+            { type: 'app.compaction', summary: 'summary of the chat' },
+          ])
+          return 'retry'
+        },
+      },
+    })
+
+    expect(await session.prompt('a very long chat')).toEqual({
+      text: 'fits now',
+    })
+    expect(calls).toHaveLength(2)
+    expect(messageTexts(calls[1])).toEqual(['summary of the chat'])
+    await host.close()
+  })
+
+  it('retries a transient error with the backoff, then fails after the limit', async () => {
+    const { host, session, calls } = await open({
+      replies: failsWith('503 Service Unavailable'),
+      turn: {
+        onModelError: retryTransientErrors({ maxRetries: 2, baseDelayMs: 1 }),
+      },
+    })
+
+    const turn = session.prompt('go')
+    await expect(turn).rejects.toThrow('503 Service Unavailable')
+
+    expect(calls).toHaveLength(3)
+    const events = await eventsOf(session, turn.id)
+    expect(
+      events.filter((type) => type === 'CUSTOM:harness.turn.retry'),
+    ).toHaveLength(2)
+    expect(events.filter((type) => type === EventType.RUN_ERROR)).toHaveLength(
+      1,
+    )
+    await host.close()
+  })
+
+  it('stops at the limit when each failed call streamed text', async () => {
+    const { host, session, calls } = await open({
+      replies: failsWith('overloaded', 'partial '),
+      turn: {
+        onModelError: retryTransientErrors({ maxRetries: 2, baseDelayMs: 1 }),
+      },
+    })
+
+    await expect(session.prompt('go')).rejects.toThrow('overloaded')
+
+    expect(calls).toHaveLength(3)
+    await host.close()
+  })
+
+  it('retries an error that the adapter throws, and drops the failed text', async () => {
+    const { host, session } = await open({
+      replies: [throws('fetch failed'), () => text('second try')],
+      turn: { onModelError: retryTransientErrors({ baseDelayMs: 1 }) },
+    })
+
+    expect(await session.prompt('go')).toEqual({ text: 'second try' })
+    await host.close()
+  })
+
+  it('keeps today behavior without the hook', async () => {
+    const { host, session, calls } = await open({
+      replies: [failsWith('overloaded'), () => text('never')],
+      turn: {},
+    })
+
+    await expect(session.prompt('go')).rejects.toThrow('overloaded')
+    expect(calls).toHaveLength(1)
+    await host.close()
+  })
+})

From 7b64428fb103031d79bee69c40f433ad0dea9481 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 18:19:42 +0200
Subject: [PATCH 136/286] fix(ai-harness): retry keeps the resume, the steer,
 and the earlier text

A retried model call keeps the resume of an approval turn, and a host without a log saves the transcript before each model call when the harness can retry, so a joined steer and a tool result reach the retry. The turn result keeps the text of earlier model calls. An abort during the backoff ends the turn without the held error, and the run record drops the old error after a successful retry.
---
 packages/ai-harness/src/session.ts            |  32 ++-
 packages/ai-harness/src/types.ts              |   5 +-
 .../ai-harness/tests/turn-control.test.ts     | 224 +++++++++++++++---
 3 files changed, 225 insertions(+), 36 deletions(-)

diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index bd8e65525e..fe3cddec12 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -10,6 +10,7 @@ import {
   runAgentStream,
   validateWithStandardSchema,
 } from '@tanstack/ai'
+import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
 import { credentialsFor, providerKeysFor } from './auth'
 import { checkConfigValue } from './config'
 import { LogConflictError, withPersistence } from '@tanstack/ai-persistence'
@@ -1535,6 +1536,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           : []
         const list = [...config.messages, ...added]
         const synced = await this.engine?.beforeModel(list, joins)
+        // A retried call loads the saved transcript, so a host without a log
+        // saves it before each model call when the harness can retry.
+        if (!this.engine && this.harness.turn?.onModelError) {
+          await this.messages.saveThread(this.threadId, list)
+        }
         for (const steer of steers) this.join(ctx.runId, steer)
         if (steers.length === 0 && !synced) return undefined
         return { messages: synced ?? list }
@@ -1868,7 +1874,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       // answer: a late join gets its answer in this turn. A run that failed
       // runs again when `turn.onModelError` answers 'retry'.
       for (;;) {
-        const textBefore = text
+        let textBefore = text
         let runError: { message: string; code?: string } | undefined
         let heldError: StreamChunk | undefined
         try {
@@ -1961,9 +1967,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
               interrupts = chunk.outcome.interrupts
             }
             if (chunk.type === EventType.RUN_ERROR) failure = chunk.message
-            // A finished tool phase resets the retries. Streamed text does
-            // not, so a call that fails after some text still counts.
-            if (chunk.type === EventType.TOOL_CALL_RESULT) retries = 0
+            // A finished tool phase resets the retries, and its text stays in
+            // the result. Streamed text does not reset them, so a call that
+            // fails after some text still counts.
+            if (chunk.type === EventType.TOOL_CALL_RESULT) {
+              retries = 0
+              textBefore = text
+            }
           }
         } catch (error) {
           // The outer catch handles a cancelled turn, a log failure, and a
@@ -1971,7 +1981,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           if (signal.aborted || this.logFailure || !turnHooks?.onModelError) {
             throw error
           }
-          runError = { message: errorText(error) }
+          const { code } = toRunErrorPayload(error)
+          runError = {
+            message: errorText(error),
+            ...(code !== undefined ? { code } : {}),
+          }
         }
         if (runError && turnHooks?.onModelError) {
           const answer =
@@ -1996,15 +2010,19 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
                 error: runError,
               }),
             )
+            // The resume stays: withPersistence commits it only when a call
+            // succeeds, so its interrupts are still open.
             message = undefined
-            resume = undefined
-            parentRunId = undefined
             // withPersistence failed the run. It runs again, for the retry.
             await this.persistence.stores.runs?.update(operation.id, {
               status: 'running',
+              finishedAt: undefined,
+              error: undefined,
             })
             continue
           }
+          // A cancel or a log failure ends the turn without the held error.
+          if (signal.aborted) break
           // Here, and not in the outer catch, for an error the run threw.
           operation.publish(
             heldError ?? {
diff --git a/packages/ai-harness/src/types.ts b/packages/ai-harness/src/types.ts
index fc79e8113c..a0c21c70f8 100644
--- a/packages/ai-harness/src/types.ts
+++ b/packages/ai-harness/src/types.ts
@@ -182,6 +182,9 @@ export const HARNESS_EVENTS = {
   inputSettled: 'harness.input.settled',
   /** A media file was stored. The value is a `MediaRecord`. */
   media: 'harness.media',
-  /** A turn runs the model again after an error. The value has `retries` and `error`. */
+  /**
+   * A turn runs the model again after an error. The value has `operationId`,
+   * `retries`, and `error`.
+   */
   turnRetry: 'harness.turn.retry',
 } as const
diff --git a/packages/ai-harness/tests/turn-control.test.ts b/packages/ai-harness/tests/turn-control.test.ts
index 57f794d1b1..5bbcfe7a39 100644
--- a/packages/ai-harness/tests/turn-control.test.ts
+++ b/packages/ai-harness/tests/turn-control.test.ts
@@ -1,14 +1,31 @@
-import { describe, expect, it } from 'vitest'
-import { EventType, isContextOverflow } from '@tanstack/ai'
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { EventType, isContextOverflow, toolDefinition } from '@tanstack/ai'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness, retryTransientErrors } from '../src'
-import { messageTexts, mockAdapter, text } from './helpers'
-import type { StreamChunk } from '@tanstack/ai'
+import { gate, messageTexts, mockAdapter, text, toolCall } from './helpers'
+import type { AnyTool, StreamChunk } from '@tanstack/ai'
 import type { HarnessTurnOptions, ProjectOptions } from '../src'
 import type { Reply } from './helpers'
 
 const THREAD = 't1'
 
+/** The start of an assistant message that streamed `delta`. */
+const partialText = (delta: string): Array<StreamChunk> => [
+  {
+    type: EventType.TEXT_MESSAGE_START,
+    messageId: 'p',
+    role: 'assistant',
+    timestamp: Date.now(),
+  },
+  {
+    type: EventType.TEXT_MESSAGE_CONTENT,
+    messageId: 'p',
+    delta,
+    timestamp: Date.now(),
+  },
+]
+
 /** A model call that ends with a RUN_ERROR. */
 const failsWith =
   (message: string, partial?: string): Reply =>
@@ -19,28 +36,13 @@ const failsWith =
       threadId: 't',
       timestamp: Date.now(),
     },
-    ...(partial
-      ? ([
-          {
-            type: EventType.TEXT_MESSAGE_START,
-            messageId: 'p',
-            role: 'assistant',
-            timestamp: Date.now(),
-          },
-          {
-            type: EventType.TEXT_MESSAGE_CONTENT,
-            messageId: 'p',
-            delta: partial,
-            timestamp: Date.now(),
-          },
-        ] satisfies Array<StreamChunk>)
-      : []),
+    ...(partial ? partialText(partial) : []),
     { type: EventType.RUN_ERROR, message, timestamp: Date.now() },
   ]
 
-/** A model call whose adapter throws. */
+/** A model call whose adapter throws after some text. */
 const throws =
-  (message: string): Reply =>
+  (message: string, code?: string): Reply =>
   () =>
     (async function* (): AsyncGenerator<StreamChunk> {
       yield {
@@ -49,9 +51,26 @@ const throws =
         threadId: 't',
         timestamp: Date.now(),
       }
-      throw new Error(message)
+      yield* partialText('partial ')
+      throw Object.assign(new Error(message), { code })
     })()
 
+/** A model call that says `say`, then calls `lookup`. */
+const textThenLookup =
+  (say: string): Reply =>
+  () => [...text(say).slice(0, -1), ...toolCall('lookup', { q: 'x' }).slice(1)]
+
+/** A tool that runs `during`, then finds something. */
+const lookup = (during?: () => Promise<void>) =>
+  toolDefinition({
+    name: 'lookup',
+    description: 'Look something up',
+    inputSchema: z.object({ q: z.string() }),
+  }).server(async () => {
+    await during?.()
+    return { found: true }
+  })
+
 /** Compaction: the summary replaces the whole transcript. */
 const project: ProjectOptions = {
   record: ({ record }) =>
@@ -63,21 +82,30 @@ const project: ProjectOptions = {
 async function open(options: {
   replies: Array<Reply> | Reply
   turn: HarnessTurnOptions
+  tools?: Array<AnyTool>
   durable?: boolean
 }) {
   const { adapter, calls } = mockAdapter(options.replies)
-  const { runs, metadata } = memoryPersistence().stores
+  const persistence = memoryPersistence()
+  const { runs, metadata, interrupts } = persistence.stores
   const host = options.durable
     ? createHarnessHost({
-        persistence: { stores: { log: memoryLogStore(), runs, metadata } },
+        persistence: {
+          stores: { log: memoryLogStore(), runs, metadata, interrupts },
+        },
         project,
       })
-    : createHarnessHost({ persistence: memoryPersistence() })
+    : createHarnessHost({ persistence })
   const session = await host.open(
-    defineHarness({ name: 'test/turn-control', adapter, turn: options.turn }),
+    defineHarness({
+      name: 'test/turn-control',
+      adapter,
+      tools: options.tools,
+      turn: options.turn,
+    }),
     { threadId: THREAD },
   )
-  return { host, session, calls }
+  return { host, session, calls, runs }
 }
 
 /** The events of one operation, as `type` or `type:name`. */
@@ -173,6 +201,146 @@ describe('turn.onModelError', () => {
     await host.close()
   })
 
+  it('gives the hook the code of an error that the adapter throws', async () => {
+    const seen: Array<unknown> = []
+    const { host, session } = await open({
+      replies: throws('boom', 'overloaded_error'),
+      turn: {
+        onModelError: ({ error }) => {
+          seen.push(error)
+          return undefined
+        },
+      },
+    })
+
+    await expect(session.prompt('go')).rejects.toThrow('boom')
+    expect(seen).toEqual([{ message: 'boom', code: 'overloaded_error' }])
+    await host.close()
+  })
+
+  it('keeps the text of the model calls before the failed one', async () => {
+    const { host, session } = await open({
+      tools: [lookup()],
+      replies: [
+        textThenLookup('Let me check. '),
+        failsWith('503 Service Unavailable'),
+        () => text('It is sunny.'),
+      ],
+      turn: { onModelError: retryTransientErrors({ baseDelayMs: 1 }) },
+    })
+
+    expect(await session.prompt('weather?')).toEqual({
+      text: 'Let me check. It is sunny.',
+    })
+    await host.close()
+  })
+
+  it.each([false, true])(
+    'retries a resumed turn and runs the approved tool once (durable: %s)',
+    async (durable) => {
+      const execute = vi.fn(async () => ({ ok: true }))
+      const remove = toolDefinition({
+        name: 'remove',
+        description: 'Remove a file',
+        needsApproval: true,
+        inputSchema: z.object({ path: z.string() }),
+      }).server(execute)
+      const { host, session } = await open({
+        durable,
+        tools: [remove],
+        replies: [
+          () => toolCall('remove', { path: 'a.txt' }, 'call_1'),
+          failsWith('503 Service Unavailable'),
+          () => text('removed'),
+        ],
+        turn: { onModelError: retryTransientErrors({ baseDelayMs: 1 }) },
+      })
+
+      const first = await session.prompt('remove a.txt')
+      const receipt = await session.resolve([
+        {
+          interruptId: first.interrupts![0]!.id,
+          status: 'resolved',
+          payload: true,
+        },
+      ])
+
+      expect(await session.operation(receipt.operationId!)).toEqual({
+        text: 'removed',
+      })
+      expect(execute).toHaveBeenCalledTimes(1)
+      await host.close()
+    },
+  )
+
+  it('gives the retry a steer that joined the failed call, on a host without a log', async () => {
+    const started = gate()
+    const release = gate()
+    const { host, session, calls } = await open({
+      tools: [
+        lookup(async () => {
+          started.open()
+          await release.opened
+        }),
+      ],
+      replies: [
+        () => toolCall('lookup', { q: 'x' }),
+        failsWith('503 Service Unavailable'),
+        () => text('done'),
+      ],
+      turn: { onModelError: retryTransientErrors({ baseDelayMs: 1 }) },
+    })
+
+    const turn = session.prompt('find x')
+    await started.opened
+    await session.steer('also check y')
+    release.open()
+
+    expect(await turn).toEqual({ text: 'done' })
+    expect(messageTexts(calls[2]).at(-1)).toBe('also check y')
+    await host.close()
+  })
+
+  it('ends a turn cancelled during the hook without the held error', async () => {
+    const waiting = gate()
+    const { host, session } = await open({
+      replies: failsWith('503 Service Unavailable'),
+      turn: {
+        onModelError: async ({ signal }) => {
+          waiting.open()
+          await new Promise((resolve) =>
+            signal.addEventListener('abort', resolve, { once: true }),
+          )
+          return 'retry' as const
+        },
+      },
+    })
+
+    const turn = session.prompt('go')
+    await waiting.opened
+    await turn.cancel()
+
+    await expect(turn).rejects.toThrow('Cancelled.')
+    expect(turn.status()).toBe('cancelled')
+    expect(await eventsOf(session, turn.id)).not.toContain(EventType.RUN_ERROR)
+    await host.close()
+  })
+
+  it('clears the error of the run record after a successful retry', async () => {
+    const { host, session, runs } = await open({
+      replies: [failsWith('503 Service Unavailable'), () => text('ok')],
+      turn: { onModelError: retryTransientErrors({ baseDelayMs: 1 }) },
+    })
+
+    const turn = session.prompt('go')
+    await turn
+
+    const record = await runs.get(turn.id)
+    expect(record?.status).toBe('completed')
+    expect(record?.error).toBeUndefined()
+    await host.close()
+  })
+
   it('keeps today behavior without the hook', async () => {
     const { host, session, calls } = await open({
       replies: [failsWith('overloaded'), () => text('never')],

From ab68c7b05cf85b7dc2cf5b94b43d0ecd80472569 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 18:33:37 +0200
Subject: [PATCH 137/286] feat(ai-harness): a beforeFinish hook that keeps the
 turn going

defineHarness({ turn: { beforeFinish } }) runs when the model stops calling tools. Messages and records that it returns land in one append. When they change the transcript, the model runs again in the same operation. maxFinishCycles (default 32) stops a hook that never gives up.
---
 packages/ai-harness/src/session.ts            | 103 ++++++++++--
 .../ai-harness/tests/turn-control.test.ts     | 154 +++++++++++++++++-
 2 files changed, 246 insertions(+), 11 deletions(-)

diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index fe3cddec12..f305e40d8f 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -18,7 +18,12 @@ import { AgentRegistry } from './agents'
 import { SessionFeed } from './feed'
 import { isRecord } from './utils'
 import { bindDurable, createToolStep } from './durable-tool'
-import { engineMessageStore, sessionMessageStore, stepKey } from './log'
+import {
+  commonPrefix,
+  engineMessageStore,
+  sessionMessageStore,
+  stepKey,
+} from './log'
 import { createMediaStore, mediaCapture, mediaMiddleware } from './media'
 import { mediaIdOf, mediaOfMessage } from './media-ref'
 import { OperationImpl } from './operation'
@@ -73,7 +78,7 @@ import type {
   AnyAgent,
 } from './agents'
 import type { AnyHarness, HarnessAgentsOf } from './define'
-import type { RecoverDecision } from './turn'
+import type { RecoverDecision, TurnAdditions } from './turn'
 import type { HarnessPersistence } from './host'
 import type {
   AgentGroup,
@@ -1870,9 +1875,12 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       const signal = operation.abortController.signal
       /** Retries since the last finished tool phase. */
       let retries = 0
+      /** How many times `turn.beforeFinish` continued this turn. */
+      let cycle = 0
       // One chat() run, and one more each time steers wait after a final
       // answer: a late join gets its answer in this turn. A run that failed
-      // runs again when `turn.onModelError` answers 'retry'.
+      // runs again when `turn.onModelError` answers 'retry'. A final answer
+      // runs again when `turn.beforeFinish` adds to the transcript.
       for (;;) {
         let textBefore = text
         let runError: { message: string; code?: string } | undefined
@@ -2034,18 +2042,29 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           failure = runError.message
           break
         }
-        const hasLateJoin =
-          this.steerQueue.length > 0 &&
-          failure === undefined &&
-          (interrupts?.length ?? 0) === 0 &&
-          !operation.abortController.signal.aborted
-        if (!hasLateJoin) break
+        const isFinished =
+          failure !== undefined ||
+          (interrupts?.length ?? 0) > 0 ||
+          signal.aborted
+        if (isFinished) break
+        const hasLateJoin = this.steerQueue.length > 0
+        if (!hasLateJoin) {
+          if (
+            !(await this.continueBeforeFinish(operation, turn.inputId, cycle))
+          ) {
+            break
+          }
+          cycle += 1
+        }
         message = undefined
         resume = undefined
         parentRunId = undefined
-        // withPersistence finished the run. It runs again, for the join.
+        // withPersistence finished the run. It runs again, for the join or
+        // the hook's additions.
         await this.persistence.stores.runs?.update(operation.id, {
           status: 'running',
+          finishedAt: undefined,
+          error: undefined,
         })
       }
     } catch (error) {
@@ -2147,6 +2166,70 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     )
   }
 
+  /**
+   * Add hook messages and host records to the transcript, in one append.
+   * Returns true when the transcript changed.
+   */
+  private async addToTurn(added: TurnAdditions): Promise<boolean> {
+    const records = added.records ?? []
+    const messages = (added.messages ?? []).map(
+      (message): ModelMessage =>
+        message.id ? message : { ...message, id: createMessageId() },
+    )
+    checkHostRecords(records)
+    if (!this.writer) {
+      if (records.length > 0) {
+        throw new Error(
+          'Records from a turn hook need a durable host (a host with stores.log).',
+        )
+      }
+      if (messages.length === 0) return false
+      const history = await this.messages.loadThread(this.threadId)
+      await this.messages.saveThread(this.threadId, [...history, ...messages])
+      return true
+    }
+    const before = this.writer.state.messages
+    await this.writer.commit({ messages: [...before, ...messages], records })
+    const after = this.writer.state.messages
+    return (
+      after.length !== before.length ||
+      commonPrefix(before, after) !== before.length
+    )
+  }
+
+  /**
+   * Ask `turn.beforeFinish` whether the turn goes on. True when it added to
+   * the transcript, so the turn runs the model again.
+   */
+  private async continueBeforeFinish(
+    operation: OperationImpl<ChatTurnResult>,
+    inputId: string | undefined,
+    cycle: number,
+  ): Promise<boolean> {
+    const hooks = this.harness.turn
+    if (!hooks?.beforeFinish) return false
+    const added = await hooks.beforeFinish({
+      session: this,
+      operationId: operation.id,
+      ...(inputId ? { inputId } : {}),
+      cycle,
+      messages: await this.messages.loadThread(this.threadId),
+      signal: operation.abortController.signal,
+    })
+    const isEmpty =
+      !added ||
+      ((added.messages?.length ?? 0) === 0 &&
+        (added.records?.length ?? 0) === 0)
+    if (isEmpty) return false
+    const max = hooks.maxFinishCycles ?? 32
+    if (cycle >= max) {
+      throw new Error(
+        `beforeFinish continued the turn ${max} times. Return nothing from the hook when the work is done.`,
+      )
+    }
+    return this.addToTurn(added)
+  }
+
   // ===========================
   // Agents
   // ===========================
diff --git a/packages/ai-harness/tests/turn-control.test.ts b/packages/ai-harness/tests/turn-control.test.ts
index 5bbcfe7a39..a86ae3a39e 100644
--- a/packages/ai-harness/tests/turn-control.test.ts
+++ b/packages/ai-harness/tests/turn-control.test.ts
@@ -3,7 +3,14 @@ import { z } from 'zod'
 import { EventType, isContextOverflow, toolDefinition } from '@tanstack/ai'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness, retryTransientErrors } from '../src'
-import { gate, messageTexts, mockAdapter, text, toolCall } from './helpers'
+import {
+  gate,
+  messageTexts,
+  mockAdapter,
+  text,
+  toolCall,
+  untilAborted,
+} from './helpers'
 import type { AnyTool, StreamChunk } from '@tanstack/ai'
 import type { HarnessTurnOptions, ProjectOptions } from '../src'
 import type { Reply } from './helpers'
@@ -352,3 +359,148 @@ describe('turn.onModelError', () => {
     await host.close()
   })
 })
+
+describe('turn.beforeFinish', () => {
+  const REMINDER = 'You did not post the answer. Post it now.'
+
+  it('sends the model back to work in the same operation', async () => {
+    const { host, session, calls } = await open({
+      replies: [() => text('draft'), () => text('posted')],
+      turn: {
+        beforeFinish: ({ messages }) =>
+          messages.some((message) => message.content === REMINDER)
+            ? undefined
+            : { messages: [{ role: 'user', content: REMINDER }] },
+      },
+    })
+
+    const turn = session.prompt('answer the user')
+    expect(await turn).toEqual({ text: 'draftposted' })
+
+    expect(calls).toHaveLength(2)
+    expect(messageTexts(calls[1]).at(-1)).toBe(REMINDER)
+    const started = (await eventsOf(session, turn.id)).filter(
+      (type) => type === 'CUSTOM:harness.operation.started',
+    )
+    expect(started).toHaveLength(1)
+    await host.close()
+  })
+
+  it('continues for a record that projects to a message', async () => {
+    const signalProject: ProjectOptions = {
+      record: ({ messages, record }) =>
+        record.type === 'app.signal' && typeof record.text === 'string'
+          ? [...messages, { role: 'user', content: record.text }]
+          : undefined,
+    }
+    const { adapter, calls } = mockAdapter([
+      () => text('one'),
+      () => text('two'),
+    ])
+    const { runs } = memoryPersistence().stores
+    const host = createHarnessHost({
+      persistence: { stores: { log: memoryLogStore(), runs } },
+      project: signalProject,
+    })
+    let cycles = 0
+    const session = await host.open(
+      defineHarness({
+        name: 'test/turn-control',
+        adapter,
+        turn: {
+          beforeFinish: ({ cycle }) => {
+            cycles = cycle
+            return cycle === 0
+              ? { records: [{ type: 'app.signal', text: 'check the result' }] }
+              : undefined
+          },
+        },
+      }),
+      { threadId: THREAD },
+    )
+
+    expect(await session.prompt('go')).toEqual({ text: 'onetwo' })
+    expect(messageTexts(calls[1]).at(-1)).toBe('check the result')
+    expect(cycles).toBe(1)
+    await host.close()
+  })
+
+  it('completes for a record that changes no message', async () => {
+    const { host, session, calls } = await open({
+      durable: true,
+      replies: [() => text('done'), () => text('never')],
+      turn: {
+        beforeFinish: ({ cycle }) =>
+          cycle === 0
+            ? { records: [{ type: 'app.state_write', name: 'x', value: 1 }] }
+            : undefined,
+      },
+    })
+
+    expect(await session.prompt('go')).toEqual({ text: 'done' })
+    expect(calls).toHaveLength(1)
+    await host.close()
+  })
+
+  it('fails the turn at the cycle limit', async () => {
+    const { host, session, calls } = await open({
+      replies: () => text('again'),
+      turn: {
+        maxFinishCycles: 2,
+        beforeFinish: () => ({
+          messages: [{ role: 'user', content: 'once more' }],
+        }),
+      },
+    })
+
+    await expect(session.prompt('go')).rejects.toThrow('2 times')
+    expect(calls).toHaveLength(3)
+    await host.close()
+  })
+
+  it('refuses records without a log', async () => {
+    const { host, session } = await open({
+      replies: [() => text('done')],
+      turn: { beforeFinish: () => ({ records: [{ type: 'app.note' }] }) },
+    })
+
+    await expect(session.prompt('go')).rejects.toThrow('durable host')
+    await host.close()
+  })
+
+  it('answers the added message after a crash before the next model call', async () => {
+    const { runs, metadata } = memoryPersistence().stores
+    const persistence = { stores: { log: memoryLogStore(), runs, metadata } }
+    const beforeFinish: HarnessTurnOptions['beforeFinish'] = ({ messages }) =>
+      messages.some((message) => message.content === REMINDER)
+        ? undefined
+        : { messages: [{ role: 'user', content: REMINDER }] }
+    const openOn = async (replies: Array<Reply>) => {
+      const { adapter, calls } = mockAdapter(replies)
+      const host = createHarnessHost({ persistence })
+      const session = await host.open(
+        defineHarness({
+          name: 'test/turn-control',
+          adapter,
+          turn: { beforeFinish },
+        }),
+        { threadId: THREAD },
+      )
+      return { host, session, calls }
+    }
+    const first = await openOn([() => text('draft'), untilAborted()])
+    const turn = first.session.prompt('answer the user', { inputId: 'in-1' })
+    await vi.waitFor(() => expect(first.calls).toHaveLength(2))
+    await runs.update(turn.id, { leaseExpiresAt: Date.now() - 1 })
+
+    const next = await openOn([() => text('posted')])
+
+    expect(await next.session.settled('in-1')).toMatchObject({
+      outcome: 'completed',
+    })
+    expect(next.calls).toHaveLength(1)
+    expect(messageTexts(next.calls[0]).at(-1)).toBe(REMINDER)
+    await first.host.close().catch(() => {})
+    await next.host.close()
+  })
+})

From f049329c9768000dff97a4ceae3cd157b68f3083 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 18:42:22 +0200
Subject: [PATCH 138/286] fix(ai-harness): a cancelled turn adds nothing from
 beforeFinish

When the turn is cancelled while beforeFinish runs, its messages and records are dropped, so the next turn does not get a message the cancelled turn never answered. The record-only test now checks that the record lands in the log.
---
 packages/ai-harness/src/session.ts            |  2 +
 packages/ai-harness/src/turn.ts               |  6 ++-
 .../ai-harness/tests/turn-control.test.ts     | 44 +++++++++++++++++--
 3 files changed, 48 insertions(+), 4 deletions(-)

diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index f305e40d8f..c8d04e0642 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -2216,6 +2216,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       messages: await this.messages.loadThread(this.threadId),
       signal: operation.abortController.signal,
     })
+    // A cancelled turn adds nothing.
+    if (operation.abortController.signal.aborted) return false
     const isEmpty =
       !added ||
       ((added.messages?.length ?? 0) === 0 &&
diff --git a/packages/ai-harness/src/turn.ts b/packages/ai-harness/src/turn.ts
index 85a973e927..b2e26ec340 100644
--- a/packages/ai-harness/src/turn.ts
+++ b/packages/ai-harness/src/turn.ts
@@ -97,7 +97,11 @@ export interface HarnessTurnOptions {
   beforeFinish?: (
     ctx: FinishContext,
   ) => TurnAdditions | undefined | Promise<TurnAdditions | undefined>
-  /** How many times `beforeFinish` can continue one turn. Default 32. */
+  /**
+   * How many times `beforeFinish` can continue one turn. Default 32. At the
+   * limit, a hook that still returns messages or records fails the turn
+   * (records alone count too).
+   */
   maxFinishCycles?: number
   /**
    * Whether a waiting input joins the running turn now. A refused input
diff --git a/packages/ai-harness/tests/turn-control.test.ts b/packages/ai-harness/tests/turn-control.test.ts
index a86ae3a39e..924a9ebca4 100644
--- a/packages/ai-harness/tests/turn-control.test.ts
+++ b/packages/ai-harness/tests/turn-control.test.ts
@@ -95,10 +95,11 @@ async function open(options: {
   const { adapter, calls } = mockAdapter(options.replies)
   const persistence = memoryPersistence()
   const { runs, metadata, interrupts } = persistence.stores
+  const log = memoryLogStore()
   const host = options.durable
     ? createHarnessHost({
         persistence: {
-          stores: { log: memoryLogStore(), runs, metadata, interrupts },
+          stores: { log, runs, metadata, interrupts },
         },
         project,
       })
@@ -112,7 +113,7 @@ async function open(options: {
     }),
     { threadId: THREAD },
   )
-  return { host, session, calls, runs }
+  return { host, session, calls, runs, log }
 }
 
 /** The events of one operation, as `type` or `type:name`. */
@@ -426,7 +427,7 @@ describe('turn.beforeFinish', () => {
   })
 
   it('completes for a record that changes no message', async () => {
-    const { host, session, calls } = await open({
+    const { host, session, calls, log } = await open({
       durable: true,
       replies: [() => text('done'), () => text('never')],
       turn: {
@@ -439,9 +440,46 @@ describe('turn.beforeFinish', () => {
 
     expect(await session.prompt('go')).toEqual({ text: 'done' })
     expect(calls).toHaveLength(1)
+    expect(
+      (await log.read(THREAD)).map((entry) => entry.record.type),
+    ).toContain('app.state_write')
     await host.close()
   })
 
+  it.each([false, true])(
+    'adds nothing when the turn is cancelled during the hook (durable: %s)',
+    async (durable) => {
+      const waiting = gate()
+      const { host, session, calls } = await open({
+        durable,
+        replies: [() => text('done'), () => text('never')],
+        turn: {
+          beforeFinish: async ({ signal }) => {
+            waiting.open()
+            await new Promise((resolve) =>
+              signal.addEventListener('abort', resolve, { once: true }),
+            )
+            return { messages: [{ role: 'user', content: REMINDER }] }
+          },
+        },
+      })
+
+      const turn = session.prompt('go')
+      await waiting.opened
+      await turn.cancel()
+
+      await expect(turn).rejects.toThrow('Cancelled.')
+      expect(turn.status()).toBe('cancelled')
+      expect(calls).toHaveLength(1)
+      expect(
+        (await session.transcript()).some(
+          (message) => message.content === REMINDER,
+        ),
+      ).toBe(false)
+      await host.close()
+    },
+  )
+
   it('fails the turn at the cycle limit', async () => {
     const { host, session, calls } = await open({
       replies: () => text('again'),

From 2d49b76e91865cb78ab91482085446473f3f44c3 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 18:47:55 +0200
Subject: [PATCH 139/286] docs(harness): turn control, shared logs, leases,
 recover, and the replay option

---
 docs/config.json                    |  23 +++-
 docs/harness/durable-sessions.md    |  93 +++++++++++++++-
 docs/harness/durable-tools.md       |  30 +++++
 docs/harness/inputs.md              |   7 ++
 docs/harness/session-log.md         |   1 +
 docs/harness/shared-logs.md         | 128 ++++++++++++++++++++++
 docs/harness/turn-control.md        | 163 ++++++++++++++++++++++++++++
 docs/persistence/store-reference.md |  82 +++++++++++++-
 8 files changed, 519 insertions(+), 8 deletions(-)
 create mode 100644 docs/harness/shared-logs.md
 create mode 100644 docs/harness/turn-control.md

diff --git a/docs/config.json b/docs/config.json
index d3862cf980..0204f9700a 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -712,7 +712,7 @@
           "label": "Store Reference",
           "to": "persistence/store-reference",
           "addedAt": "2026-08-04",
-          "updatedAt": "2026-09-30"
+          "updatedAt": "2026-10-01"
         },
         {
           "label": "How Persistence Works",
@@ -901,22 +901,35 @@
           "label": "Durable sessions",
           "to": "harness/durable-sessions",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-09-30"
+          "updatedAt": "2026-10-01"
         },
         {
           "label": "Send inputs safely",
           "to": "harness/inputs",
-          "addedAt": "2026-09-30"
+          "addedAt": "2026-09-30",
+          "updatedAt": "2026-10-01"
         },
         {
           "label": "Run side effects once",
           "to": "harness/durable-tools",
-          "addedAt": "2026-09-30"
+          "addedAt": "2026-09-30",
+          "updatedAt": "2026-10-01"
         },
         {
           "label": "Build on the session log",
           "to": "harness/session-log",
-          "addedAt": "2026-09-30"
+          "addedAt": "2026-09-30",
+          "updatedAt": "2026-10-01"
+        },
+        {
+          "label": "Control how a turn ends",
+          "to": "harness/turn-control",
+          "addedAt": "2026-10-01"
+        },
+        {
+          "label": "Share one log between sessions",
+          "to": "harness/shared-logs",
+          "addedAt": "2026-10-01"
         },
         {
           "label": "Write a plugin",
diff --git a/docs/harness/durable-sessions.md b/docs/harness/durable-sessions.md
index 6c925d6a17..aaac2e1e54 100644
--- a/docs/harness/durable-sessions.md
+++ b/docs/harness/durable-sessions.md
@@ -19,7 +19,7 @@ A long agent turn can outlive the process that started it: a deploy restarts the
 A durable host takes two stores:
 
 - `log`: one append-only log per thread. It keeps the events, the transcript, the inputs, and the tool steps.
-- `runs`: run records with leases. A lease tells the next host that the last one stopped.
+- `runs` or `leases`: a lease tells the next host that the last one stopped. `runs` keeps run records with leases. `leases` is a store that you wire to your own lease system. See [Use your own leases](#use-your-own-leases).
 
 ```ts group=harness-durable
 import { createHarnessHost } from '@tanstack/ai-harness'
@@ -67,6 +67,56 @@ When a host opens the thread and finds a turn whose lease expired, it checks the
 
 An input that was stored but never ran, runs now. See [Send inputs safely](./inputs) to read how an input ended.
 
+## Retry model errors
+
+A model call can fail for a short time: a 429, a 5xx, an overloaded provider, or a network error. Add `retryTransientErrors()` to run the model again in the same turn, after a backoff:
+
+```ts group=harness-durable
+import { retryTransientErrors } from '@tanstack/ai-harness'
+
+const resilient = defineHarness({
+  name: 'acme/resilient',
+  adapter: openaiText('gpt-5.6'),
+  turn: { onModelError: retryTransientErrors() },
+})
+```
+
+Other errors fail the turn. To set the limits, see [Control how a turn ends](./turn-control#retry-model-errors).
+
+## Decide recovery yourself
+
+The steps above are the default. To change them for one input, add `durability.recover`. It runs for each input that a crashed host left. It gets `{ session, input, messages, decision }`:
+
+- `input`: the input, with `inputId`, `attempt`, `timeoutAt`, and `abortRequested`.
+- `messages`: the transcript from the log.
+- `decision`: what the harness does by default. It is one of the 5 steps above, or `run` for an input that never ran.
+
+Return `undefined` to keep the decision. Or return one of these:
+
+- `{ action: 'run' }`: run the input now.
+- `{ action: 'settle', outcome, error? }`: end the input as `'completed'`, `'failed'`, or `'aborted'`. Without a model call.
+
+This example fails an input with your own error code after 2 runs:
+
+```ts group=harness-durable
+const guarded = defineHarness({
+  name: 'acme/guarded',
+  adapter: openaiText('gpt-5.6'),
+  durability: {
+    recover: ({ input, decision }) => {
+      if (decision.action === 'run' && input.attempt >= 2) {
+        return {
+          action: 'settle',
+          outcome: 'failed',
+          error: { message: 'This request crashed the host twice.', code: 'poison_input' },
+        }
+      }
+      return undefined
+    },
+  },
+})
+```
+
 ## Mark tools that are safe to run again
 
 A crash can stop a run after a tool started but before its result was stored. Tell the harness what to do with `replay`:
@@ -101,8 +151,49 @@ const leasedHost = createHarnessHost({
 })
 ```
 
+## Use your own leases
+
+You may already have leases in a job queue or a submission table. Give the host a `LeaseStore` as `stores.leases`, and it uses your system to find a crashed host. Each call gets the `threadId`, `inputId`, `operationId`, and `attempt` of one turn attempt:
+
+- `acquire`: the host takes the lease when the attempt starts. It also gets `ownerId` and `expiresAt`.
+- `renew`: the host extends the lease while the attempt runs. It also gets `ownerId` and `expiresAt`.
+- `release`: the host gives the lease back when the attempt ends. It also gets `ownerId` and `expiresAt`.
+- `isAlive`: after a crash, the host asks if another host still runs the attempt.
+
+A host with `leases` does not need `runs`. If you give both, `leases` decides. The `lease` option sets the timing, as in the section above.
+
+```ts group=harness-durable
+import type { LeaseStore, TurnLease, TurnLeaseKey } from '@tanstack/ai-persistence'
+
+const held = new Map<string, TurnLease>()
+const keyOf = (k: TurnLeaseKey) =>
+  `${k.threadId}:${k.inputId}:${k.operationId}:${k.attempt}`
+
+// Swap the Map for your queue or table.
+const leases: LeaseStore = {
+  acquire: async (lease) => {
+    held.set(keyOf(lease), lease)
+  },
+  renew: async (lease) => {
+    held.set(keyOf(lease), lease)
+  },
+  release: async (lease) => {
+    held.delete(keyOf(lease))
+  },
+  isAlive: async (key) => (held.get(keyOf(key))?.expiresAt ?? 0) > Date.now(),
+}
+
+const leasedByYou = createHarnessHost({
+  persistence: { stores: { log: memoryLogStore(), leases } },
+})
+```
+
+For the full contract, see [`LeaseStore`](../persistence/store-reference#leasestore).
+
 ## What you have now
 
 - Turns that continue after a crash or a deploy, from the session log.
 - A turn that stops after `maxAttempts` or `timeoutMs`, with a clear error code.
 - Tools that either run again safely or tell the model to check first.
+- A turn that retries a short model error by itself.
+- Your own rule for how a crashed input recovers, and your own leases if you have them.
diff --git a/docs/harness/durable-tools.md b/docs/harness/durable-tools.md
index cc0a7da867..28b34dbe14 100644
--- a/docs/harness/durable-tools.md
+++ b/docs/harness/durable-tools.md
@@ -57,6 +57,36 @@ Add it to `tools` in `defineHarness`, as any other tool. On a [durable host](./d
 
 `durableTool` sets `replay: 'safe'`, so the harness runs the tool again after a crash.
 
+## Never run a tool twice
+
+Some tools must not run again, for example a tool that sends an email. Pass `{ replay: 'never' }` as the third argument:
+
+```ts group=harness-durable-tools
+declare const mailer: {
+  send: (to: string, body: string) => Promise<{ id: string }>
+}
+
+export const notify = durableTool(
+  toolDefinition({
+    name: 'notify',
+    description: 'Email a customer',
+    inputSchema: z.object({ to: z.string(), body: z.string() }),
+  }),
+  async ({ to, body }, { step }) => {
+    const mail = await step.do(`send:${to}`, () => mailer.send(to, body))
+    return { mailId: mail.id }
+  },
+  { replay: 'never' },
+)
+```
+
+After a crash that cuts the call:
+
+- `'safe'` (the default): the call runs again. Finished steps return their stored values.
+- `'never'`: the model gets a tool error, because nobody knows if the tool finished. The call does not run again. `step` and `append` still work, so the steps and records of the first run stay in the log.
+
+The `replay` option of `durableTool` decides this. A `replay` on the tool definition is not read.
+
 ## Add records with the tool batch
 
 `append` adds your own records to the session log. They land when the tool phase completes, in the same append as the batch commit. If a crash cuts the batch, the records never happened.
diff --git a/docs/harness/inputs.md b/docs/harness/inputs.md
index c546591534..8808dd5f3e 100644
--- a/docs/harness/inputs.md
+++ b/docs/harness/inputs.md
@@ -107,6 +107,13 @@ console.log((await session.settled('req-44')).operationId === running.id) // tru
 
 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.
+
+- To stop a waiting steer, call `session.cancel(operationId)` with its operation id. It does not join, and it settles `aborted` when the running turn ends.
+- 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).
+
 ## What you have now
 
 - Retries that never run a prompt twice.
diff --git a/docs/harness/session-log.md b/docs/harness/session-log.md
index cada620bf8..a2be7251f7 100644
--- a/docs/harness/session-log.md
+++ b/docs/harness/session-log.md
@@ -38,6 +38,7 @@ await session.append([{ type: 'app.signal', text: 'The build failed.' }])
 
 - A record is JSON with a `type`. Types that start with `harness.` belong to the harness, so `append` refuses them.
 - `append` resolves when the records are in the log.
+- To share one log between a parent and its child sessions, see [Share one log between sessions](./shared-logs).
 - In a tool, use `append` from [`durableTool`](./durable-tools), so the records land with the tool batch.
 
 ## Fold records into the model context
diff --git a/docs/harness/shared-logs.md b/docs/harness/shared-logs.md
new file mode 100644
index 0000000000..d21b9f17b3
--- /dev/null
+++ b/docs/harness/shared-logs.md
@@ -0,0 +1,128 @@
+---
+title: Share one log between sessions
+id: harness-shared-logs
+order: 4
+description: 'Put a parent session and its child sessions in one durable log, append to several sessions at once, and keep state for the whole log.'
+keywords:
+  - tanstack ai
+  - harness
+  - shared log
+  - logId
+  - reduce
+  - logState
+  - child sessions
+---
+
+Your framework runs one agent instance with a parent conversation and child tasks. Each conversation in its own log means two problems. A record for the child and a record for the parent can land one without the other after a crash. And no one place holds the state of the whole instance. Open all the sessions on one log. They share the order of the log, its atomic appends, and one state fold.
+
+## Open two sessions on one log
+
+Pass the same `logId` to `host.open`. Each `threadId` is one session:
+
+```ts group=harness-shared-logs
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { openaiText } from '@tanstack/ai-openai'
+
+const log = memoryLogStore()
+const { runs, metadata } = memoryPersistence().stores
+const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-5.6'),
+})
+const host = createHarnessHost({
+  persistence: { stores: { log, runs, metadata } },
+})
+
+const parent = await host.open(assistant, { threadId: 'agent-1' })
+const child = await host.open(assistant, {
+  threadId: 'task-1',
+  logId: 'agent-1',
+})
+
+console.log(parent.logId, child.logId)
+```
+
+- `logId` defaults to `threadId`. The parent above has the log id `agent-1`, the same as its thread id.
+- Each session folds only its own transcript, inputs, and events from the log. The child never sees the messages of the parent.
+- The sessions run turns at the same time. A slow parent turn does not block a child turn.
+- `session.logId` tells you which log a session writes to.
+
+## Write to several sessions in one append
+
+`session.append` stamps the records with this session. A record with `thread: '<other threadId>'` belongs to that session of the same log. The whole append is all or nothing:
+
+```ts group=harness-shared-logs
+await parent.append([
+  { type: 'app.child_created', thread: 'task-1', task: 'research' },
+  { type: 'app.child_linked', child: 'task-1' },
+])
+```
+
+Here the child record and the link in the parent land together, or not at all.
+
+- `thread` must be a string. Any other value makes `append` throw.
+- The session whose thread id equals the log id (the parent above) writes no `thread` field. A record without `thread` belongs to it.
+
+## Keep state for the whole log
+
+Give the host a `reduce` option. It folds every host record of the log, from all sessions, in log order. Then `host.logState` reads the result:
+
+```ts group=harness-shared-logs
+import type { ReduceOptions } from '@tanstack/ai-harness'
+
+interface Children {
+  tasks: Array<string>
+}
+
+const reduce: ReduceOptions<Children> = {
+  initial: { tasks: [] },
+  version: 'v1',
+  record: ({ state, record }) =>
+    record.type === 'app.child_created' && typeof record.thread === 'string'
+      ? { tasks: [...state.tasks, record.thread] }
+      : state,
+}
+
+const trackedHost = createHarnessHost({
+  persistence: { stores: { log, runs, metadata } },
+  reduce,
+})
+const tracked = await trackedHost.open(assistant, { threadId: 'agent-2' })
+await tracked.append([
+  { type: 'app.child_created', thread: 'task-2', task: 'research' },
+])
+
+console.log(trackedHost.logState('agent-2')?.tasks)
+```
+
+- `record` must be pure. It returns the next state, or the same state for no change.
+- `host.logState(logId)` works for a log that has an open session in this host. Otherwise it returns `undefined`.
+- The type of the state flows from `initial` and `record`. Here `logState` returns `Children | undefined`.
+- Change `version` when you change `record`. A fold checkpoint with another version is ignored.
+- `project` still works. It folds a host record into the messages of its own session only.
+
+## One writer per log
+
+Only one host writes a log at a time. When another host writes to it:
+
+1. Every session of that log in this host stops. Their next `append` throws a log conflict.
+2. The next `host.open` for that log folds the log again and gives you a new session.
+
+One thread can have one open session per log. A second harness on the same thread and log throws.
+
+To read one thread of a shared log outside a session, pass `logId` to `logMessageStore`:
+
+```ts group=harness-shared-logs
+import { logMessageStore } from '@tanstack/ai-harness'
+
+const messages = logMessageStore({ store: log, logId: 'agent-1' })
+console.log(await messages.loadThread('task-1'))
+```
+
+## What you have now
+
+- Many sessions in one durable log, each with its own transcript.
+- Appends that reach several sessions and land all together or not at all.
+- One state for the whole log, from `reduce`, that you read with `host.logState`.
+- A clear rule for conflicts: one writer, and a fresh fold on the next open.
diff --git a/docs/harness/turn-control.md b/docs/harness/turn-control.md
new file mode 100644
index 0000000000..d04bf55c8a
--- /dev/null
+++ b/docs/harness/turn-control.md
@@ -0,0 +1,163 @@
+---
+title: Control how a turn ends
+id: harness-turn-control
+order: 4
+description: "Send the model back to work when it stops too soon, retry model errors, and choose which waiting messages join a running turn."
+keywords:
+  - tanstack ai
+  - harness
+  - beforeFinish
+  - onModelError
+  - retry
+  - canJoin
+  - onJoin
+  - steer
+---
+
+A model can stop before the job is done: it writes a nice answer and forgets to call `post_message`. A provider can answer 503 in the middle of a turn. A user can send three messages while the agent works, and one of them must not join. The `turn` options of the harness give you a hook for each case.
+
+## Send the model back to work
+
+The `beforeFinish` hook runs when the model stops calling tools. Check the transcript. If the job is not done, return a message. The model runs again in the same operation.
+
+```ts group=harness-turn-control
+import { defineHarness } from '@tanstack/ai-harness'
+import { openaiText } from '@tanstack/ai-openai'
+
+const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-5.6'),
+  turn: {
+    beforeFinish: ({ messages }) => {
+      const posted = messages.some((message) =>
+        message.toolCalls?.some((call) => call.function.name === 'post_message'),
+      )
+      if (posted) return undefined
+      return {
+        messages: [
+          {
+            role: 'user',
+            content: 'You have not called post_message yet. Call it now.',
+          },
+        ],
+      }
+    },
+  },
+})
+```
+
+- The hook returns `{ messages?, records? }`. Return nothing when the work is done, and the turn ends.
+- When the return changes the transcript, the model runs again. The hook runs again at the next stop.
+- Always check `messages`. A hook that returns the same reminder every time never stops.
+- `maxFinishCycles` (default 32) is the limit. A hook that still asks for more at the limit fails the turn.
+- `records` are host records in the same append. They need a durable host. See [Append your own records](./session-log#append-your-own-records).
+
+## Retry model errors
+
+A model call can fail for a reason that passes in a few seconds: an overloaded provider, a rate limit, a dropped connection. Set `onModelError` to `retryTransientErrors()`. The harness runs the failed call again in the same operation.
+
+```ts group=harness-turn-control
+import { retryTransientErrors } from '@tanstack/ai-harness'
+
+const resilient = defineHarness({
+  name: 'acme/resilient',
+  adapter: openaiText('gpt-5.6'),
+  turn: { onModelError: retryTransientErrors() },
+})
+```
+
+The defaults:
+
+- `maxRetries`: 3 retries since the last finished tool phase.
+- `baseDelayMs`: 2000. The delay doubles with each retry. Each delay is then multiplied by a random jitter from 0.75 to 1.0.
+- `isTransient`: `isTransientModelError`. It is true for 429, 5xx, overloaded, rate limit, network and connection errors, and timeouts.
+
+Pass your own check when you know more about your provider:
+
+```ts group=harness-turn-control
+import { isTransientModelError } from '@tanstack/ai-harness'
+
+const picky = defineHarness({
+  name: 'acme/picky',
+  adapter: openaiText('gpt-5.6'),
+  turn: {
+    onModelError: retryTransientErrors({
+      maxRetries: 5,
+      baseDelayMs: 500,
+      isTransient: (error) =>
+        error.code === 'upstream_busy' || isTransientModelError(error),
+    }),
+  },
+})
+```
+
+Clients get a `harness.turn.retry` event for each retry. The text of the failed call is not in the turn result.
+
+### Compact after a context overflow
+
+`onModelError` is a plain function, so you can write your own policy. This one handles a context overflow: it appends a compaction record, then retries once. Your host must have a `project` function that folds `app.compaction` records into the messages. See [Fold records into the model context](./session-log#fold-records-into-the-model-context).
+
+```ts group=harness-turn-control
+import { isContextOverflow } from '@tanstack/ai'
+
+const compacting = defineHarness({
+  name: 'acme/compacting',
+  adapter: openaiText('gpt-5.6'),
+  turn: {
+    onModelError: async ({ session, error, retries }) => {
+      if (retries > 0 || !isContextOverflow({ error: error.message })) {
+        return undefined
+      }
+      await session.append([
+        {
+          type: 'app.compaction',
+          summary: 'Earlier messages were removed to fit the context.',
+          firstKept: -6,
+        },
+      ])
+      return 'retry'
+    },
+  },
+})
+```
+
+Here `firstKept: -6` keeps the last six messages. The `project` function in the linked page reads it with `messages.slice(record.firstKept)`, and `slice` counts a negative number from the end.
+
+## Choose which messages join a turn
+
+A message with `busy: 'steer'` waits while a turn runs. Before each model call, the waiting messages join the turn as a prefix, in the order they arrived.
+
+The join stops at the first message that:
+
+- has an abort request (`session.cancel(operationId)` on it), or
+- `turn.canJoin` refuses.
+
+That message and the ones after it run as their own turns later. A cancelled one settles `aborted`.
+
+`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.
+
+```ts group=harness-turn-control
+const selective = defineHarness({
+  name: 'acme/selective',
+  adapter: openaiText('gpt-5.6'),
+  turn: {
+    canJoin: ({ message }) =>
+      typeof message === 'string' && message.length <= 500,
+    onJoin: ({ inputs }) => ({
+      messages: [
+        {
+          role: 'user',
+          content: `${inputs.length} new message(s) arrived. Answer them before you continue.`,
+        },
+      ],
+      records: [{ type: 'app.join', count: inputs.length }],
+    }),
+  },
+})
+```
+
+## What you have now
+
+- A turn that goes back to work until the job is done, with a limit.
+- Model errors that retry with a backoff, and a policy of your own for a context overflow.
+- Waiting messages that join a turn only when you allow it.
diff --git a/docs/persistence/store-reference.md b/docs/persistence/store-reference.md
index ec9ce032ba..377b76ef35 100644
--- a/docs/persistence/store-reference.md
+++ b/docs/persistence/store-reference.md
@@ -16,7 +16,8 @@ there is no separate enable list.
 | `generationRuns` | Generation run status and result metadata, keyed by its own `runId`. | `withGenerationPersistence`, required |
 | `artifacts` | File metadata. Needs `blobs`. | `withGenerationPersistence`, portable snapshots |
 | `blobs` | File bytes. Needs `artifacts`. | `withGenerationPersistence`, portable snapshots |
-| `log` | Append-only session log per thread. | Durable harness hosts, with `runs` |
+| `log` | Append-only session log per thread. | Durable harness hosts, with `runs` or `leases` |
+| `leases` | Leases for harness turns, from a system that already has them. | Durable harness hosts, instead of `runs` |
 
 Named groupings of the chat stores (`ChatTranscriptStores`, `ChatPersistenceStores`,
 `ChatWithInterruptsStores`) are covered in [Controls](./controls).
@@ -602,6 +603,83 @@ Each record is JSON. Store it as text or as a JSON column. The harness writes th
 record types that start with `harness.`, and a host adds its own types. The store does
 not read them.
 
+## LeaseStore
+
+You may already have leases: a job queue, or a submission table that says which
+worker owns a job. `LeaseStore` lets the harness use them. A durable harness host
+(`stores.log`) needs `stores.runs` or `stores.leases`.
+
+With `leases`, the harness does four things:
+
+- It takes a lease when a turn attempt starts.
+- It renews the lease while the attempt runs. It renews every `lease.renewMs`,
+  and each renewal makes the lease last `lease.ttlMs`.
+- It releases the lease after the attempt settles.
+- After a crash, it calls `isAlive` to find attempts that nobody runs any more.
+
+```ts
+interface TurnLeaseKey {
+  threadId: string
+  inputId: string
+  operationId: string // the operation that runs the attempt, also the AG-UI run id
+  attempt: number // 1 for the first run of the input, then 1 more after each crash
+}
+
+interface TurnLease extends TurnLeaseKey {
+  ownerId: string // the host that runs the attempt
+  expiresAt: number // epoch ms
+}
+
+interface LeaseStore {
+  acquire(lease: TurnLease): Promise<void>
+  renew(lease: TurnLease): Promise<void>
+  release(lease: TurnLease): Promise<void>
+  isAlive(key: TurnLeaseKey): Promise<boolean>
+}
+```
+
+Rules for an implementation:
+
+- `isAlive` returns `true` while another host still runs the attempt. That means a
+  lease exists and has not expired.
+- `renew` and `release` for a lease you do not hold can do nothing.
+- The harness keys a lease by input id and attempt. Two attempts of one input are
+  two leases.
+
+This store keeps leases in a `Map`:
+
+```ts
+import type {
+  LeaseStore,
+  TurnLease,
+  TurnLeaseKey,
+} from '@tanstack/ai-persistence'
+
+function createMemoryLeases(): LeaseStore {
+  const leases = new Map<string, TurnLease>()
+  const keyOf = (key: TurnLeaseKey) => `${key.inputId}:${key.attempt}`
+
+  return {
+    acquire: async (lease) => {
+      leases.set(keyOf(lease), lease)
+    },
+    renew: async (lease) => {
+      leases.set(keyOf(lease), lease)
+    },
+    release: async (lease) => {
+      leases.delete(keyOf(lease))
+    },
+    isAlive: async (key) => {
+      const lease = leases.get(keyOf(key))
+      return lease !== undefined && lease.expiresAt >= Date.now()
+    },
+  }
+}
+```
+
+To wire `leases` into a host, and to set `lease.renewMs` and `lease.ttlMs`, see
+[Use your own leases](../harness/durable-sessions#use-your-own-leases).
+
 ## How the records relate
 
 The thread is not a table of its own: it exists as the `thread_id` the other records
@@ -664,7 +742,7 @@ Each store has a `define*Store` helper (`defineMessageStore`, `defineRunStore`,
 on `persistence.stores`, and reading one you did not pass is a compile error.
 
 The keys in the table at the top are the only ones `stores` accepts, together with the
-harness keys `inbox` and `credentials`. Anything else throws
+harness keys `inbox`, `credentials`, `log`, and `leases`. Anything else throws
 `Unknown AIPersistence store key` at construction.
 
 To annotate the value instead, use a named shape:

From 9dfe29dab750f389778b3dfb229660f6cda8ddd1 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 18:53:13 +0200
Subject: [PATCH 140/286] feat(ai-harness): stop a join at an aborted or
 refused steer

Waiting steers join as a contiguous prefix in admission order. The join stops at the first steer with an abort request, or that turn.canJoin refuses. A cancelled waiting steer now settles aborted.
---
 packages/ai-harness/src/session.ts            | 76 ++++++++++++++--
 .../ai-harness/tests/durable-joins.test.ts    | 88 +++++++++++++++++++
 packages/ai-harness/tests/session.test.ts     | 41 +++++++++
 3 files changed, 197 insertions(+), 8 deletions(-)

diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index c8d04e0642..d818c5ee41 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -392,6 +392,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     message: UserInput
     operation?: OperationImpl<ChatTurnResult>
   }> = []
+  /** Waiting steers with an abort request, on a host without a log. */
+  private readonly abortedSteers = new Set<string>()
   private readonly pendingNotes: Array<string> = []
   private activeTurn: OperationImpl<ChatTurnResult> | undefined
   private interrupted:
@@ -853,6 +855,16 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         { type: 'harness.input.abort', inputId: targetInput },
       ])
     }
+    const waitingSteer = this.steerQueue.find(
+      (steer) => steer.operation === target,
+    )
+    if (waitingSteer) {
+      // It never joins now, and settles when the running turn ends. A
+      // durable host has the abort request in the log already.
+      if (!this.writer) this.abortedSteers.add(waitingSteer.inputId)
+      await this.markApplied(inputId, target.id)
+      return { inputId, status: 'accepted', operationId: target.id }
+    }
     const queued = this.queue.findIndex((turn) => turn.operation === target)
     if (queued >= 0) {
       this.queue.splice(queued, 1)
@@ -1511,19 +1523,42 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }
   }
 
+  private isAbortRequested(inputId: string) {
+    return (
+      this.writer?.state.inputs.get(inputId)?.abortRequested === true ||
+      this.abortedSteers.has(inputId)
+    )
+  }
+
+  /**
+   * How many waiting steers join now: the prefix up to the first one that
+   * has an abort request, or that `turn.canJoin` refuses.
+   */
+  private async joinableCount() {
+    const canJoin = this.harness.turn?.canJoin
+    let count = 0
+    for (const steer of this.steerQueue) {
+      if (this.isAbortRequested(steer.inputId)) break
+      const candidate = { inputId: steer.inputId, message: steer.message }
+      if (canJoin && !(await canJoin(candidate))) break
+      count += 1
+    }
+    return count
+  }
+
   /**
    * Middleware that runs before each model call. Queued steers join the
-   * running turn in admission order. On a durable host, one append commits
-   * the engine's messages, the steer messages, and the join records, so a
-   * crash never splits a join. The model gets the folded log when a host
-   * record changed the context.
+   * running turn in admission order, as far as `joinableCount` lets them.
+   * On a durable host, one append commits the engine's messages, the steer
+   * messages, and the join records, so a crash never splits a join. The
+   * model gets the folded log when a host record changed the context.
    */
   private steering(): AnyChatMiddleware {
     return {
       name: 'harness:steering',
       onConfig: async (ctx, config) => {
         if (ctx.phase !== 'beforeModel') return undefined
-        const steers = this.steerQueue.splice(0)
+        const steers = this.steerQueue.splice(0, await this.joinableCount())
         const added = steers.map(
           (steer): ModelMessage => ({
             id: createMessageId(),
@@ -2047,7 +2082,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           (interrupts?.length ?? 0) > 0 ||
           signal.aborted
         if (isFinished) break
-        const hasLateJoin = this.steerQueue.length > 0
+        const hasLateJoin = (await this.joinableCount()) > 0
         if (!hasLateJoin) {
           if (
             !(await this.continueBeforeFinish(operation, turn.inputId, cycle))
@@ -2151,10 +2186,35 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     this.requeueWaitingSteers()
   }
 
-  /** Steers a turn never reached run next, before other queued turns. */
+  /**
+   * Steers a turn never reached run next, before other queued turns. A
+   * steer with an abort request settles `aborted` instead.
+   */
   private requeueWaitingSteers(): void {
+    const waiting = this.steerQueue.splice(0)
+    const aborted = waiting.filter((steer) =>
+      this.isAbortRequested(steer.inputId),
+    )
+    const rest = waiting.filter((steer) => !aborted.includes(steer))
+    for (const steer of aborted) {
+      this.abortedSteers.delete(steer.inputId)
+      const { operation } = steer
+      // Not awaited: the session goes on to the next turn at once. The
+      // settlement lands before the operation ends.
+      void this.settle({
+        inputId: steer.inputId,
+        outcome: 'aborted',
+        ...(operation ? { operationId: operation.id } : {}),
+      })
+        .catch(() => {})
+        .then(() => {
+          if (!operation) return
+          operation.fail('cancelled', new Error('Cancelled before it started.'))
+          this.publishFinished(operation)
+        })
+    }
     this.queue.unshift(
-      ...this.steerQueue.splice(0).map((steer) => {
+      ...rest.map((steer) => {
         const next = steer.operation ?? this.createTurnOperation()
         this.bindTurn(steer.inputId, next)
         return {
diff --git a/packages/ai-harness/tests/durable-joins.test.ts b/packages/ai-harness/tests/durable-joins.test.ts
index 8872be9888..342727262d 100644
--- a/packages/ai-harness/tests/durable-joins.test.ts
+++ b/packages/ai-harness/tests/durable-joins.test.ts
@@ -252,3 +252,91 @@ describe('recovery of durable joins', () => {
     await host.close()
   })
 })
+
+describe('the join rule', () => {
+  const waitTool = () => {
+    const started = gate()
+    const done = gate()
+    const tool = toolDefinition({ name: 'wait', description: 'Wait' }).server(
+      async () => {
+        started.open()
+        await done.opened
+        return 'waited'
+      },
+    )
+    return { tool, started, done }
+  }
+
+  it('joins A, stops at B with an abort request, and runs C as its own turn', async () => {
+    const { persistence } = durablePersistence()
+    const wait = waitTool()
+    const { host, session, calls } = await openDurable(
+      persistence,
+      [
+        () => toolCall('wait', {}),
+        () => text('answer a'),
+        () => text('answer c'),
+      ],
+      [wait.tool],
+    )
+
+    const turn = session.prompt('start', { inputId: 'host' })
+    await wait.started.opened
+    const steer = (name: string) =>
+      session.prompt(name, { busy: 'steer', inputId: `join-${name}` })
+    const a = steer('a')
+    const b = steer('b')
+    const c = steer('c')
+    await Promise.all([a, b, c].map((join) => join.receipt))
+    await session.cancel(b.id)
+    wait.done.open()
+
+    await turn
+    expect(messageTexts(calls[1]).at(-1)).toBe('a')
+    expect(await session.settled('join-a')).toMatchObject({
+      outcome: 'completed',
+      operationId: turn.id,
+    })
+    expect(await session.settled('join-b')).toMatchObject({
+      outcome: 'aborted',
+    })
+    await expect(b).rejects.toThrow()
+    const ownTurn = await session.settled('join-c')
+    expect(ownTurn).toMatchObject({ outcome: 'completed' })
+    expect(ownTurn.operationId).not.toBe(turn.id)
+    expect(messageTexts(calls[2]).at(-1)).toBe('c')
+    await host.close()
+  })
+
+  it('runs an input that canJoin refuses as its own turn later', async () => {
+    const { persistence } = durablePersistence()
+    const wait = waitTool()
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('wait', {}),
+      () => text('host answer'),
+      () => text('later answer'),
+    ])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/joins',
+        adapter,
+        tools: [wait.tool],
+        turn: { canJoin: ({ message }) => message !== 'later' },
+      }),
+      { threadId: THREAD },
+    )
+
+    const turn = session.prompt('start', { inputId: 'host' })
+    await wait.started.opened
+    const later = session.prompt('later', { busy: 'steer', inputId: 'later' })
+    await later.receipt
+    wait.done.open()
+
+    await turn
+    expect(messageTexts(calls[1])).not.toContain('later')
+    expect(await later).toEqual({ text: 'later answer' })
+    expect((await session.settled('later')).operationId).not.toBe(turn.id)
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/session.test.ts b/packages/ai-harness/tests/session.test.ts
index 9fba1f4c7f..689755ff4c 100644
--- a/packages/ai-harness/tests/session.test.ts
+++ b/packages/ai-harness/tests/session.test.ts
@@ -502,3 +502,44 @@ describe('plugins', () => {
     )
   })
 })
+
+describe('a waiting steer with an abort request, without a log', () => {
+  it('does not join, and settles aborted', async () => {
+    const started = gate()
+    const done = gate()
+    const wait = toolDefinition({ name: 'wait', description: 'Wait' }).server(
+      async () => {
+        started.open()
+        await done.opened
+        return 'waited'
+      },
+    )
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('wait', {}),
+      () => text('host answer'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({ name: 'test/steer-abort', adapter, tools: [wait] }),
+      { threadId: 't-abort' },
+    )
+
+    const turn = session.prompt('start')
+    await started.opened
+    const steer = session.prompt('stop me', {
+      busy: 'steer',
+      inputId: 'steer-1',
+    })
+    await steer.receipt
+    await session.cancel(steer.id)
+    done.open()
+
+    expect(await turn).toEqual({ text: 'host answer' })
+    expect(messageTexts(calls[1])).not.toContain('stop me')
+    expect(await session.settled('steer-1')).toMatchObject({
+      outcome: 'aborted',
+    })
+    expect(calls).toHaveLength(2)
+    await host.close()
+  })
+})

From 9b60dba13488982088a0b5dd15b76ff2a9e8bee6 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 18:55:24 +0200
Subject: [PATCH 141/286] test(e2e): a retried 503 and a beforeFinish turn over
 the harness protocol

---
 testing/e2e/fixtures/harness-turn/basic.json  | 29 ++++++++
 .../e2e/src/routes/api.harness-protocol.$.ts  | 29 +++++++-
 testing/e2e/tests/harness-protocol.spec.ts    | 74 +++++++++++++++++++
 3 files changed, 131 insertions(+), 1 deletion(-)
 create mode 100644 testing/e2e/fixtures/harness-turn/basic.json

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/src/routes/api.harness-protocol.$.ts b/testing/e2e/src/routes/api.harness-protocol.$.ts
index 660bb755ae..2e0880d4a0 100644
--- a/testing/e2e/src/routes/api.harness-protocol.$.ts
+++ b/testing/e2e/src/routes/api.harness-protocol.$.ts
@@ -1,6 +1,9 @@
 import { createFileRoute } from '@tanstack/react-router'
 import { defineAgent } from '@tanstack/ai'
+import { createOpenaiChat } from '@tanstack/ai-openai'
 import {
+  type FinishContext,
+  retryTransientErrors,
   configOption,
   createHarnessHandler,
   createHarnessHost,
@@ -47,9 +50,33 @@ function handlerFor(request: Request) {
       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 }] },
+          }
+        : 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
   const harness = defineHarness({
     name: 'e2e/protocol',
-    adapter: createTextAdapter('openai', undefined, port, testId).adapter,
+    adapter,
+    ...(turn ? { turn } : {}),
     subagents: { agents: [painter] },
     agents: [
       defineAgent({
diff --git a/testing/e2e/tests/harness-protocol.spec.ts b/testing/e2e/tests/harness-protocol.spec.ts
index 0bfdc3d9e9..4e2e4ecec1 100644
--- a/testing/e2e/tests/harness-protocol.spec.ts
+++ b/testing/e2e/tests/harness-protocol.spec.ts
@@ -132,6 +132,80 @@ test.describe('harness protocol', () => {
     ).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('takes a control input and returns a receipt', async ({
     request,
     testId,

From 5d3b4064af307d5e6eafa703831dd3ad686f8863 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 18:57:21 +0200
Subject: [PATCH 142/286] feat(ai-harness): an onJoin hook for joined inputs

turn.onJoin runs before the model call that the joined inputs reach. Its messages come after the joined messages, and its records land in the append of the join.
---
 packages/ai-harness/src/session.ts            | 67 ++++++++++++---
 .../ai-harness/tests/durable-joins.test.ts    | 82 +++++++++++++++++++
 2 files changed, 136 insertions(+), 13 deletions(-)

diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index d818c5ee41..df0fde3bc0 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -1549,8 +1549,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   /**
    * Middleware that runs before each model call. Queued steers join the
    * running turn in admission order, as far as `joinableCount` lets them.
-   * On a durable host, one append commits the engine's messages, the steer
-   * messages, and the join records, so a crash never splits a join. The
+   * `turn.onJoin` adds its messages after theirs. On a durable host, one
+   * append commits the engine's messages, the steer messages, the join
+   * records, and the `onJoin` records, so a crash never splits a join. The
    * model gets the folded log when a host record changed the context.
    */
   private steering(): AnyChatMiddleware {
@@ -1558,14 +1559,29 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       name: 'harness:steering',
       onConfig: async (ctx, config) => {
         if (ctx.phase !== 'beforeModel') return undefined
-        const steers = this.steerQueue.splice(0, await this.joinableCount())
-        const added = steers.map(
-          (steer): ModelMessage => ({
-            id: createMessageId(),
-            role: 'user',
-            content: steer.message,
-          }),
-        )
+        const count = await this.joinableCount()
+        const steers = this.steerQueue.slice(0, count)
+        const operation = this.operations.get(ctx.runId)
+        const onJoin = this.harness.turn?.onJoin
+        const added =
+          steers.length > 0 && onJoin && operation
+            ? await onJoin({
+                session: this,
+                operationId: ctx.runId,
+                inputs: steers.map((steer) => ({
+                  inputId: steer.inputId,
+                  message: steer.message,
+                })),
+                signal: operation.abortController.signal,
+              })
+            : undefined
+        const records = added?.records ?? []
+        checkHostRecords(records)
+        if (records.length > 0 && !this.engine) {
+          throw new Error(
+            'Records from a turn hook need a durable host (a host with stores.log).',
+          )
+        }
         const hostInput = this.operationInputs.get(ctx.runId)
         const joins = hostInput
           ? steers.map((steer) => ({
@@ -1574,15 +1590,33 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
               into: hostInput,
             }))
           : []
-        const list = [...config.messages, ...added]
-        const synced = await this.engine?.beforeModel(list, joins)
+        const list = [
+          ...config.messages,
+          ...steers.map(
+            (steer): ModelMessage => ({
+              id: createMessageId(),
+              role: 'user',
+              content: steer.message,
+            }),
+          ),
+          ...(added?.messages ?? []).map(
+            (message): ModelMessage =>
+              message.id ? message : { ...message, id: createMessageId() },
+          ),
+        ]
+        const synced = await this.engine?.beforeModel(list, [
+          ...joins,
+          ...records,
+        ])
         // A retried call loads the saved transcript, so a host without a log
         // saves it before each model call when the harness can retry.
         if (!this.engine && this.harness.turn?.onModelError) {
           await this.messages.saveThread(this.threadId, list)
         }
+        // Only now, so a hook or an append that fails leaves them waiting.
+        this.steerQueue.splice(0, count)
         for (const steer of steers) this.join(ctx.runId, steer)
-        if (steers.length === 0 && !synced) return undefined
+        if (list.length === config.messages.length && !synced) return undefined
         return { messages: synced ?? list }
       },
     }
@@ -2213,6 +2247,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           this.publishFinished(operation)
         })
     }
+    if (this.closing) {
+      // close() ended the queued turns already. These end the same way.
+      for (const steer of rest) {
+        steer.operation?.fail('cancelled', new Error('Session closed.'))
+      }
+      return
+    }
     this.queue.unshift(
       ...rest.map((steer) => {
         const next = steer.operation ?? this.createTurnOperation()
diff --git a/packages/ai-harness/tests/durable-joins.test.ts b/packages/ai-harness/tests/durable-joins.test.ts
index 342727262d..6175feae4a 100644
--- a/packages/ai-harness/tests/durable-joins.test.ts
+++ b/packages/ai-harness/tests/durable-joins.test.ts
@@ -339,4 +339,86 @@ describe('the join rule', () => {
     expect((await session.settled('later')).operationId).not.toBe(turn.id)
     await host.close()
   })
+
+  it('lands the onJoin records in the append of the join', async () => {
+    const { persistence, batches } = durablePersistence()
+    const wait = waitTool()
+    const { adapter } = mockAdapter([
+      () => toolCall('wait', {}),
+      () => text('done'),
+    ])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/joins',
+        adapter,
+        tools: [wait.tool],
+        turn: {
+          onJoin: ({ inputs }) => ({
+            records: inputs.map((input) => ({
+              type: 'app.start_hook',
+              inputId: input.inputId,
+            })),
+          }),
+        },
+      }),
+      { threadId: THREAD },
+    )
+
+    const turn = session.prompt('start', { inputId: 'host' })
+    await wait.started.opened
+    await session.prompt('more', { busy: 'steer', inputId: 'join-1' }).receipt
+    wait.done.open()
+    await turn
+
+    const joinBatch = batches.find((batch) =>
+      batch.includes('harness.input.joined'),
+    )
+    expect(joinBatch).toContain('app.start_hook')
+    await host.close()
+  })
+
+  it('leaves neither the join nor the onJoin records when that append fails', async () => {
+    const inner = memoryLogStore()
+    const log: LogStore = {
+      append: async (threadId, seq, records) => {
+        if (records.some((record) => record.type === 'harness.input.joined')) {
+          throw new Error('store down')
+        }
+        await inner.append(threadId, seq, records)
+      },
+      read: (threadId, options) => inner.read(threadId, options),
+      subscribe: (threadId, listener) => inner.subscribe(threadId, listener),
+    }
+    const { runs, metadata } = memoryPersistence().stores
+    const persistence = { stores: { log, runs, metadata } }
+    const wait = waitTool()
+    const { adapter } = mockAdapter([
+      () => toolCall('wait', {}),
+      () => text('never'),
+    ])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/joins',
+        adapter,
+        tools: [wait.tool],
+        turn: {
+          onJoin: () => ({ records: [{ type: 'app.start_hook' }] }),
+        },
+      }),
+      { threadId: THREAD },
+    )
+
+    const turn = session.prompt('start', { inputId: 'host' })
+    await wait.started.opened
+    await session.prompt('more', { busy: 'steer', inputId: 'join-1' }).receipt
+    wait.done.open()
+    await expect(turn).rejects.toThrow()
+
+    const types = (await inner.read(THREAD)).map((entry) => entry.record.type)
+    expect(types).not.toContain('harness.input.joined')
+    expect(types).not.toContain('app.start_hook')
+    await host.close().catch(() => {})
+  })
 })

From e6cb8afb95c8ee5b080d594d78bc91a26411c8c3 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 19:00:06 +0200
Subject: [PATCH 143/286] fix(ai-harness): recovery settles a cancelled input
 that never ran

A waiting steer that a user cancelled is still pending when the host crashes. Recovery now settles it aborted instead of running it. The recover hook still gets this default and can change it.
---
 packages/ai-harness/src/session.ts            | 11 +++++++---
 .../ai-harness/tests/durable-inputs.test.ts   | 22 +++++++++++++++++++
 2 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index df0fde3bc0..8f6d774e9b 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -2970,9 +2970,14 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           this.reject(input.inputId, 'expired_on_restart')
           continue
         }
-        const decision = await this.recoverDecision(writer, input, {
-          action: 'run',
-        })
+        // An input that was cancelled before it ran settles aborted.
+        const decision = await this.recoverDecision(
+          writer,
+          input,
+          input.abortRequested
+            ? { action: 'settle', outcome: 'aborted' }
+            : { action: 'run' },
+        )
         if (decision.action === 'settle') {
           await this.settle({
             inputId: input.inputId,
diff --git a/packages/ai-harness/tests/durable-inputs.test.ts b/packages/ai-harness/tests/durable-inputs.test.ts
index f2217238e6..1f80adff09 100644
--- a/packages/ai-harness/tests/durable-inputs.test.ts
+++ b/packages/ai-harness/tests/durable-inputs.test.ts
@@ -174,6 +174,28 @@ describe('recovery of a durable input', () => {
     await host.close()
   })
 
+  it('settles aborted a pending input that was cancelled before it ran', async () => {
+    const persistence = durablePersistence()
+    await persistence.stores.log.append(THREAD, 1, [
+      {
+        type: 'harness.input',
+        inputId: 'in-1',
+        input: { op: 'prompt', message: 'go', busy: 'queue' },
+        at: 1,
+      },
+      { type: 'harness.input.abort', inputId: 'in-1' },
+    ])
+
+    const { host, session, calls } = await openDurable({
+      persistence,
+      replies: [() => text('never')],
+    })
+
+    expect(await session.settled('in-1')).toMatchObject({ outcome: 'aborted' })
+    expect(calls).toHaveLength(0)
+    await host.close()
+  })
+
   it('settles completed when the log already has the final answer', async () => {
     const persistence = durablePersistence()
     await seedStoppedTurn(persistence, { attempt: 1, answer: 'done before' })

From 8c9e2d371bd6b92ff76023130ab41bbd23fcaf7b Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 19:16:05 +0200
Subject: [PATCH 144/286] chore: changeset for the generic harness host
 features

---
 .changeset/harness-host-generic.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 .changeset/harness-host-generic.md

diff --git a/.changeset/harness-host-generic.md b/.changeset/harness-host-generic.md
new file mode 100644
index 0000000000..6b303e426c
--- /dev/null
+++ b/.changeset/harness-host-generic.md
@@ -0,0 +1,13 @@
+---
+'@tanstack/ai-harness': minor
+'@tanstack/ai-persistence': minor
+---
+
+Harness host features for frameworks that build on the harness:
+
+- `host.open(harness, { threadId, logId })`: sessions that share one log. A record can name another session with `thread`, and `createHarnessHost({ reduce })` folds every host record of a log (`host.logState(logId)`).
+- `durableTool(definition, execute, { replay: 'never' })`.
+- `defineHarness({ turn: { onModelError, beforeFinish, maxFinishCycles, canJoin, onJoin } })`, `durability.recover`, `retryTransientErrors()`, and `isTransientModelError()`.
+- `stores.leases` (`LeaseStore`): turn leases from your own system, in place of `stores.runs`.
+- Durable tools that a middleware returns from `onConfig` get `step` and `append`.
+- A waiting steer stops the join when it has an abort request, and `cancel` on it settles it `aborted`.

From 7b157642484331b2b6f7328f84c40dd719f4c064 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 19:33:11 +0200
Subject: [PATCH 145/286] fix(ai-harness): a join claims its steers, and a late
 cancel is refused

A join claims the waiting steers it takes, so a cancel that lands during canJoin, onJoin, or the late-join check is refused (not_running) instead of returning accepted for a steer that then joins. A cancel during onJoin adds nothing from the hook. A failed apply no longer leaves a waiting steer that blocks close. The docs say how to cancel a waiting steer and when canJoin runs.
---
 docs/harness/inputs.md                        |   4 +-
 docs/harness/turn-control.md                  |   5 +-
 packages/ai-harness/src/session.ts            | 181 ++++++++------
 .../ai-harness/tests/durable-joins.test.ts    | 233 +++++++++++++++---
 packages/ai-harness/tests/session.test.ts     | 179 +++++++++++++-
 5 files changed, 493 insertions(+), 109 deletions(-)

diff --git a/docs/harness/inputs.md b/docs/harness/inputs.md
index 8808dd5f3e..98fdaaf374 100644
--- a/docs/harness/inputs.md
+++ b/docs/harness/inputs.md
@@ -109,7 +109,9 @@ A message that arrives while the model writes its final answer still gets an ans
 
 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.
 
-- To stop a waiting steer, call `session.cancel(operationId)` with its operation id. It does not join, and it settles `aborted` when the running turn ends.
+- A `busy: 'steer'` prompt has its own operation. 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.
+- A `session.steer` input has no operation of its own. The `operationId` of its receipt is the running turn, so a cancel with that id cancels the turn.
+- 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).
diff --git a/docs/harness/turn-control.md b/docs/harness/turn-control.md
index d04bf55c8a..58313d5a07 100644
--- a/docs/harness/turn-control.md
+++ b/docs/harness/turn-control.md
@@ -132,10 +132,13 @@ The join stops at the first message that:
 - has an abort request (`session.cancel(operationId)` on it), or
 - `turn.canJoin` refuses.
 
-That message and the ones after it run as their own turns later. A cancelled one settles `aborted`.
+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.
 
 `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.
 
+- If `onJoin` throws, the turn fails, and those messages run as their own turns.
+- If you cancel the turn while `onJoin` runs, the hook adds nothing to it, and those messages run as their own turns.
+
 ```ts group=harness-turn-control
 const selective = defineHarness({
   name: 'acme/selective',
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 8f6d774e9b..03ccb2af4c 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -392,8 +392,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     message: UserInput
     operation?: OperationImpl<ChatTurnResult>
   }> = []
-  /** Waiting steers with an abort request, on a host without a log. */
+  /**
+   * Waiting steers with an abort request. An id lands here before the abort
+   * append, so a join that runs during that append skips the steer.
+   */
   private readonly abortedSteers = new Set<string>()
+  /** The ids of the waiting steers that a join took. A cancel of one is refused. */
+  private readonly joining = new Set<string>()
   private readonly pendingNotes: Array<string> = []
   private activeTurn: OperationImpl<ChatTurnResult> | undefined
   private interrupted:
@@ -849,19 +854,23 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       this.reject(inputId, 'not_running')
       return { inputId, status: 'rejected', reason: 'not_running' }
     }
+    const waitingSteer = this.steerQueue.find(
+      (steer) => steer.operation === target,
+    )
+    // A join took it, so it ends with the running turn, as a joined steer.
+    if (waitingSteer && this.joining.has(waitingSteer.inputId)) {
+      this.reject(inputId, 'not_running')
+      return { inputId, status: 'rejected', reason: 'not_running' }
+    }
+    // It never joins now, and settles when the running turn ends.
+    if (waitingSteer) this.abortedSteers.add(waitingSteer.inputId)
     const targetInput = this.operationInputs.get(target.id)
     if (this.writer && targetInput) {
       await this.writer.append([
         { type: 'harness.input.abort', inputId: targetInput },
       ])
     }
-    const waitingSteer = this.steerQueue.find(
-      (steer) => steer.operation === target,
-    )
     if (waitingSteer) {
-      // It never joins now, and settles when the running turn ends. A
-      // durable host has the abort request in the log already.
-      if (!this.writer) this.abortedSteers.add(waitingSteer.inputId)
       await this.markApplied(inputId, target.id)
       return { inputId, status: 'accepted', operationId: target.id }
     }
@@ -1531,24 +1540,36 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   }
 
   /**
-   * How many waiting steers join now: the prefix up to the first one that
-   * has an abort request, or that `turn.canJoin` refuses.
+   * Take the waiting steers that join now: the prefix up to the first one
+   * that has an abort request, or that `turn.canJoin` refuses. A steer that
+   * a join took already stays in, with no new check. Returns how many.
    */
-  private async joinableCount() {
+  private async claimJoins() {
     const canJoin = this.harness.turn?.canJoin
     let count = 0
     for (const steer of this.steerQueue) {
-      if (this.isAbortRequested(steer.inputId)) break
-      const candidate = { inputId: steer.inputId, message: steer.message }
-      if (canJoin && !(await canJoin(candidate))) break
+      if (!this.joining.has(steer.inputId)) {
+        if (this.isAbortRequested(steer.inputId)) break
+        const candidate = { inputId: steer.inputId, message: steer.message }
+        if (canJoin && !(await canJoin(candidate))) break
+      }
       count += 1
     }
-    return count
+    // A cancel can land while canJoin runs. No await from here to the claim.
+    const steers = this.steerQueue.slice(0, count)
+    const late = steers.findIndex(
+      (steer) =>
+        !this.joining.has(steer.inputId) &&
+        this.isAbortRequested(steer.inputId),
+    )
+    const taken = late >= 0 ? steers.slice(0, late) : steers
+    for (const steer of taken) this.joining.add(steer.inputId)
+    return taken.length
   }
 
   /**
    * Middleware that runs before each model call. Queued steers join the
-   * running turn in admission order, as far as `joinableCount` lets them.
+   * running turn in admission order, as far as `claimJoins` lets them.
    * `turn.onJoin` adds its messages after theirs. On a durable host, one
    * append commits the engine's messages, the steer messages, the join
    * records, and the `onJoin` records, so a crash never splits a join. The
@@ -1559,65 +1580,75 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       name: 'harness:steering',
       onConfig: async (ctx, config) => {
         if (ctx.phase !== 'beforeModel') return undefined
-        const count = await this.joinableCount()
+        const count = await this.claimJoins()
         const steers = this.steerQueue.slice(0, count)
-        const operation = this.operations.get(ctx.runId)
-        const onJoin = this.harness.turn?.onJoin
-        const added =
-          steers.length > 0 && onJoin && operation
-            ? await onJoin({
-                session: this,
-                operationId: ctx.runId,
-                inputs: steers.map((steer) => ({
-                  inputId: steer.inputId,
-                  message: steer.message,
-                })),
-                signal: operation.abortController.signal,
-              })
-            : undefined
-        const records = added?.records ?? []
-        checkHostRecords(records)
-        if (records.length > 0 && !this.engine) {
-          throw new Error(
-            'Records from a turn hook need a durable host (a host with stores.log).',
-          )
-        }
-        const hostInput = this.operationInputs.get(ctx.runId)
-        const joins = hostInput
-          ? steers.map((steer) => ({
-              type: 'harness.input.joined',
-              inputId: steer.inputId,
-              into: hostInput,
-            }))
-          : []
-        const list = [
-          ...config.messages,
-          ...steers.map(
-            (steer): ModelMessage => ({
-              id: createMessageId(),
-              role: 'user',
-              content: steer.message,
-            }),
-          ),
-          ...(added?.messages ?? []).map(
-            (message): ModelMessage =>
-              message.id ? message : { ...message, id: createMessageId() },
-          ),
-        ]
-        const synced = await this.engine?.beforeModel(list, [
-          ...joins,
-          ...records,
-        ])
-        // A retried call loads the saved transcript, so a host without a log
-        // saves it before each model call when the harness can retry.
-        if (!this.engine && this.harness.turn?.onModelError) {
-          await this.messages.saveThread(this.threadId, list)
+        try {
+          const running =
+            this.activeTurn?.id === ctx.runId ? this.activeTurn : undefined
+          const onJoin = this.harness.turn?.onJoin
+          let added: TurnAdditions | undefined
+          if (steers.length > 0 && onJoin && running) {
+            added = await onJoin({
+              session: this,
+              operationId: ctx.runId,
+              inputs: steers.map((steer) => ({
+                inputId: steer.inputId,
+                message: steer.message,
+              })),
+              signal: running.abortController.signal,
+            })
+            // A cancelled turn gets nothing from the hook. Its steers run as
+            // their own turns.
+            if (running.abortController.signal.aborted) return undefined
+          }
+          const records = added?.records ?? []
+          checkHostRecords(records)
+          if (records.length > 0 && !this.engine) {
+            throw new Error(
+              'Records from a turn hook need a durable host (a host with stores.log).',
+            )
+          }
+          const hostInput = this.operationInputs.get(ctx.runId)
+          const joins = hostInput
+            ? steers.map((steer) => ({
+                type: 'harness.input.joined',
+                inputId: steer.inputId,
+                into: hostInput,
+              }))
+            : []
+          const list = [
+            ...config.messages,
+            ...steers.map(
+              (steer): ModelMessage => ({
+                id: createMessageId(),
+                role: 'user',
+                content: steer.message,
+              }),
+            ),
+            ...(added?.messages ?? []).map(
+              (message): ModelMessage =>
+                message.id ? message : { ...message, id: createMessageId() },
+            ),
+          ]
+          const synced = await this.engine?.beforeModel(list, [
+            ...joins,
+            ...records,
+          ])
+          // A retried call loads the saved transcript, so a host without a
+          // log saves it before each model call when the harness can retry.
+          if (!this.engine && this.harness.turn?.onModelError) {
+            await this.messages.saveThread(this.threadId, list)
+          }
+          // Only now, so a hook or an append that fails leaves them waiting.
+          this.steerQueue.splice(0, count)
+          for (const steer of steers) this.join(ctx.runId, steer)
+          if (list.length === config.messages.length && !synced) {
+            return undefined
+          }
+          return { messages: synced ?? list }
+        } finally {
+          for (const steer of steers) this.joining.delete(steer.inputId)
         }
-        // Only now, so a hook or an append that fails leaves them waiting.
-        this.steerQueue.splice(0, count)
-        for (const steer of steers) this.join(ctx.runId, steer)
-        if (list.length === config.messages.length && !synced) return undefined
-        return { messages: synced ?? list }
       },
     }
   }
@@ -1836,6 +1867,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         // The log refused the write, so the session stops.
         operation.fail('failed', this.logFailure ?? error)
         this.publishFinished(operation)
+        this.requeueWaitingSteers()
         return
       }
     }
@@ -2116,7 +2148,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           (interrupts?.length ?? 0) > 0 ||
           signal.aborted
         if (isFinished) break
-        const hasLateJoin = (await this.joinableCount()) > 0
+        // Claimed, so a cancel after this check cannot leave a run with no
+        // new input.
+        const hasLateJoin = (await this.claimJoins()) > 0
         if (!hasLateJoin) {
           if (
             !(await this.continueBeforeFinish(operation, turn.inputId, cycle))
@@ -2225,6 +2259,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
    * steer with an abort request settles `aborted` instead.
    */
   private requeueWaitingSteers(): void {
+    this.joining.clear()
     const waiting = this.steerQueue.splice(0)
     const aborted = waiting.filter((steer) =>
       this.isAbortRequested(steer.inputId),
diff --git a/packages/ai-harness/tests/durable-joins.test.ts b/packages/ai-harness/tests/durable-joins.test.ts
index 6175feae4a..ac714e6e41 100644
--- a/packages/ai-harness/tests/durable-joins.test.ts
+++ b/packages/ai-harness/tests/durable-joins.test.ts
@@ -12,16 +12,23 @@ import {
 } from './helpers'
 import type { AnyTool, ModelMessage, StreamChunk } from '@tanstack/ai'
 import type { LogRecord, LogStore } from '@tanstack/ai-persistence'
+import type { HarnessTurnOptions } from '../src'
 import type { Reply } from './helpers'
 
 const THREAD = 't1'
 
-/** A durable store set. `batches` has the record types of each append. */
-function durablePersistence() {
+/**
+ * A durable store set. `batches` has the record types of each append.
+ * `before` runs before each append, so it can hold or refuse the append.
+ */
+function durablePersistence(
+  before?: (records: ReadonlyArray<LogRecord>) => void | Promise<void>,
+) {
   const inner = memoryLogStore()
   const batches: Array<Array<string>> = []
   const log: LogStore = {
     append: async (threadId, seq, records) => {
+      await before?.(records)
       await inner.append(threadId, seq, records)
       batches.push(records.map((record) => record.type))
     },
@@ -29,7 +36,7 @@ function durablePersistence() {
     subscribe: (threadId, listener) => inner.subscribe(threadId, listener),
   }
   const { runs, metadata } = memoryPersistence().stores
-  return { persistence: { stores: { log, runs, metadata } }, batches }
+  return { persistence: { stores: { log, runs, metadata } }, batches, inner }
 }
 
 type Durable = ReturnType<typeof durablePersistence>['persistence']
@@ -38,11 +45,17 @@ async function openDurable(
   persistence: Durable,
   replies: Array<Reply>,
   tools: Array<AnyTool> = [],
+  turn?: HarnessTurnOptions,
 ) {
   const { adapter, calls } = mockAdapter(replies)
   const host = createHarnessHost({ persistence })
   const session = await host.open(
-    defineHarness({ name: 'test/joins', adapter, tools }),
+    defineHarness({
+      name: 'test/joins',
+      adapter,
+      tools,
+      ...(turn ? { turn } : {}),
+    }),
     { threadId: THREAD },
   )
   return { host, session, calls }
@@ -379,46 +392,200 @@ describe('the join rule', () => {
   })
 
   it('leaves neither the join nor the onJoin records when that append fails', async () => {
-    const inner = memoryLogStore()
-    const log: LogStore = {
-      append: async (threadId, seq, records) => {
-        if (records.some((record) => record.type === 'harness.input.joined')) {
-          throw new Error('store down')
-        }
-        await inner.append(threadId, seq, records)
-      },
-      read: (threadId, options) => inner.read(threadId, options),
-      subscribe: (threadId, listener) => inner.subscribe(threadId, listener),
-    }
-    const { runs, metadata } = memoryPersistence().stores
-    const persistence = { stores: { log, runs, metadata } }
+    const { persistence, inner } = durablePersistence((records) => {
+      if (records.some((record) => record.type === 'harness.input.joined')) {
+        throw new Error('store down')
+      }
+    })
     const wait = waitTool()
-    const { adapter } = mockAdapter([
-      () => toolCall('wait', {}),
-      () => text('never'),
-    ])
-    const host = createHarnessHost({ persistence })
-    const session = await host.open(
-      defineHarness({
-        name: 'test/joins',
-        adapter,
-        tools: [wait.tool],
-        turn: {
-          onJoin: () => ({ records: [{ type: 'app.start_hook' }] }),
-        },
-      }),
-      { threadId: THREAD },
+    const { host, session } = await openDurable(
+      persistence,
+      [() => toolCall('wait', {}), () => text('never')],
+      [wait.tool],
+      { onJoin: () => ({ records: [{ type: 'app.start_hook' }] }) },
     )
 
     const turn = session.prompt('start', { inputId: 'host' })
     await wait.started.opened
-    await session.prompt('more', { busy: 'steer', inputId: 'join-1' }).receipt
+    const join = session.prompt('more', { busy: 'steer', inputId: 'join-1' })
+    await join.receipt
     wait.done.open()
     await expect(turn).rejects.toThrow()
+    // It did not join, so it ends with the session that stopped.
+    await expect(join).rejects.toThrow('Session closed.')
 
     const types = (await inner.read(THREAD)).map((entry) => entry.record.type)
     expect(types).not.toContain('harness.input.joined')
     expect(types).not.toContain('app.start_hook')
     await host.close().catch(() => {})
+
+    // The next host runs it as its own turn.
+    const next = await openDurable(
+      { stores: { ...persistence.stores, log: inner } },
+      [() => text('host answer'), () => text('join answer')],
+    )
+    const settled = await next.session.settled('join-1')
+    expect(settled.outcome).toBe('completed')
+    expect(settled.operationId).not.toBe(turn.id)
+    await next.host.close()
+  })
+
+  it('stops the join at a refused input, so the inputs after it wait too', async () => {
+    const { persistence } = durablePersistence()
+    const wait = waitTool()
+    const { host, session, calls } = await openDurable(
+      persistence,
+      [
+        () => toolCall('wait', {}),
+        () => text('host answer'),
+        () => text('answer x'),
+        () => text('answer y'),
+      ],
+      [wait.tool],
+      { canJoin: ({ message }) => message !== 'x' },
+    )
+
+    const turn = session.prompt('start', { inputId: 'host' })
+    await wait.started.opened
+    const x = session.prompt('x', { busy: 'steer', inputId: 'x' })
+    const y = session.prompt('y', { busy: 'steer', inputId: 'y' })
+    await Promise.all([x.receipt, y.receipt])
+    wait.done.open()
+
+    await turn
+    expect(messageTexts(calls[1])).not.toContain('y')
+    expect(await x).toEqual({ text: 'answer x' })
+    expect(await y).toEqual({ text: 'answer y' })
+    expect(messageTexts(calls[2]).at(-1)).toBe('x')
+    expect(messageTexts(calls[3]).at(-1)).toBe('y')
+    await host.close()
+  })
+
+  it('adds the onJoin messages after the joined ones', async () => {
+    const { persistence } = durablePersistence()
+    const wait = waitTool()
+    const { host, session, calls } = await openDurable(
+      persistence,
+      [() => toolCall('wait', {}), () => text('done')],
+      [wait.tool],
+      { onJoin: () => ({ messages: [{ role: 'user', content: 'hook' }] }) },
+    )
+
+    const turn = session.prompt('start', { inputId: 'host' })
+    await wait.started.opened
+    await session.prompt('more', { busy: 'steer', inputId: 'join-1' }).receipt
+    wait.done.open()
+
+    await turn
+    expect(messageTexts(calls[1]).slice(-2)).toEqual(['more', 'hook'])
+    await host.close()
+  })
+
+  it('refuses a cancel that lands while onJoin runs, and logs no abort for it', async () => {
+    const { persistence, inner } = durablePersistence()
+    const wait = waitTool()
+    const inJoin = gate()
+    const releaseJoin = gate()
+    const { host, session, calls } = await openDurable(
+      persistence,
+      [() => toolCall('wait', {}), () => text('host answer')],
+      [wait.tool],
+      {
+        onJoin: async () => {
+          inJoin.open()
+          await releaseJoin.opened
+          return undefined
+        },
+      },
+    )
+
+    const turn = session.prompt('start', { inputId: 'host' })
+    await wait.started.opened
+    const steer = session.prompt('stop me', { busy: 'steer', inputId: 's1' })
+    await steer.receipt
+    wait.done.open()
+    await inJoin.opened
+    const receipt = await session.cancel(steer.id)
+    releaseJoin.open()
+
+    expect(receipt).toMatchObject({ status: 'rejected', reason: 'not_running' })
+    expect(await steer).toEqual(await turn)
+    expect(messageTexts(calls[1]).at(-1)).toBe('stop me')
+    expect(await session.settled('s1')).toMatchObject({
+      outcome: 'completed',
+      operationId: turn.id,
+    })
+    const types = (await inner.read(THREAD))
+      .map((entry) => entry.record)
+      .filter((record) => record.inputId === 's1')
+      .map((record) => record.type)
+    expect(types).not.toContain('harness.input.abort')
+    await host.close()
+  })
+
+  it('does not join a steer while its abort append is in flight', async () => {
+    const inAbort = gate()
+    const releaseAbort = gate()
+    const { persistence } = durablePersistence(async (records) => {
+      if (records.some((record) => record.type === 'harness.input.abort')) {
+        inAbort.open()
+        await releaseAbort.opened
+      }
+    })
+    const wait = waitTool()
+    let cancelled: Promise<unknown> | undefined
+    const { host, session, calls } = await openDurable(
+      persistence,
+      [() => toolCall('wait', {}), () => text('answer a')],
+      [wait.tool],
+      {
+        // The cancel of s1 lands while the join runs, and its append waits.
+        canJoin: async ({ inputId }) => {
+          if (inputId === 'join-a') {
+            cancelled = session.cancel(steer.id)
+            await inAbort.opened
+          }
+          return true
+        },
+      },
+    )
+
+    const turn = session.prompt('start', { inputId: 'host' })
+    await wait.started.opened
+    const a = session.prompt('a', { busy: 'steer', inputId: 'join-a' })
+    const steer = session.prompt('stop me', { busy: 'steer', inputId: 's1' })
+    await Promise.all([a.receipt, steer.receipt])
+    wait.done.open()
+    await vi.waitFor(() => expect(cancelled).toBeDefined())
+    releaseAbort.open()
+
+    expect(await cancelled).toMatchObject({ status: 'accepted' })
+    await turn
+    expect(messageTexts(calls[1])).not.toContain('stop me')
+    expect(messageTexts(calls[1]).at(-1)).toBe('a')
+    expect(await session.settled('s1')).toMatchObject({ outcome: 'aborted' })
+    await expect(steer).rejects.toThrow()
+    expect(calls).toHaveLength(2)
+    await host.close()
+  })
+
+  it('ends a waiting steer when the apply of the turn fails, so close resolves', async () => {
+    const { persistence } = durablePersistence((records) => {
+      const isHostApply = records.some(
+        (record) =>
+          record.type === 'harness.input.applied' && record.inputId === 'host',
+      )
+      if (isHostApply) throw new Error('store down')
+    })
+    const { host, session } = await openDurable(persistence, [
+      () => text('never'),
+    ])
+
+    const turn = session.prompt('start', { inputId: 'host' })
+    const steer = session.prompt('more', { busy: 'steer', inputId: 's1' })
+    await expect(turn).rejects.toThrow('store down')
+    await expect(steer).rejects.toThrow('Session closed.')
+    await session.close()
+    await host.close()
   })
 })
diff --git a/packages/ai-harness/tests/session.test.ts b/packages/ai-harness/tests/session.test.ts
index 689755ff4c..9f13f25483 100644
--- a/packages/ai-harness/tests/session.test.ts
+++ b/packages/ai-harness/tests/session.test.ts
@@ -23,7 +23,8 @@ import {
   untilAborted,
 } from './helpers'
 import type { StreamChunk } from '@tanstack/ai'
-import type { SessionEvent } from '../src'
+import type { HarnessTurnOptions, SessionEvent } from '../src'
+import type { Reply } from './helpers'
 
 function setup() {
   const persistence = memoryPersistence()
@@ -543,3 +544,179 @@ describe('a waiting steer with an abort request, without a log', () => {
     await host.close()
   })
 })
+
+describe('joins without a log', () => {
+  /** A session whose `wait` tool runs until `wait.done` opens. */
+  async function openJoins(
+    replies: Array<Reply>,
+    turn: HarnessTurnOptions,
+    persistence = memoryPersistence(),
+  ) {
+    const started = gate()
+    const done = gate()
+    const tool = toolDefinition({ name: 'wait', description: 'Wait' }).server(
+      async () => {
+        started.open()
+        await done.opened
+        return 'waited'
+      },
+    )
+    const { adapter, calls } = mockAdapter(replies)
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({ name: 'test/joins', adapter, tools: [tool], turn }),
+      { threadId: 't-joins' },
+    )
+    return { host, session, calls, wait: { started, done } }
+  }
+
+  it('refuses a cancel that lands while onJoin runs, and the steer joins', async () => {
+    const inJoin = gate()
+    const releaseJoin = gate()
+    const { host, session, calls, wait } = await openJoins(
+      [() => toolCall('wait', {}), () => text('host answer')],
+      {
+        onJoin: async () => {
+          inJoin.open()
+          await releaseJoin.opened
+          return undefined
+        },
+      },
+    )
+
+    const turn = session.prompt('start')
+    await wait.started.opened
+    const steer = session.prompt('stop me', { busy: 'steer', inputId: 's1' })
+    await steer.receipt
+    wait.done.open()
+    await inJoin.opened
+    const receipt = await session.cancel(steer.id)
+    releaseJoin.open()
+
+    expect(receipt).toMatchObject({ status: 'rejected', reason: 'not_running' })
+    expect(await steer).toEqual(await turn)
+    expect(messageTexts(calls[1]).at(-1)).toBe('stop me')
+    expect(await session.settled('s1')).toMatchObject({
+      outcome: 'completed',
+      operationId: turn.id,
+    })
+    await host.close()
+  })
+
+  it('refuses a cancel that lands after the late-join check', async () => {
+    const persistence = memoryPersistence()
+    const { runs } = persistence.stores
+    const inUpdate = gate()
+    const releaseUpdate = gate()
+    let isArmed = false
+    const update = runs.update.bind(runs)
+    runs.update = async (...args: Parameters<typeof runs.update>) => {
+      if (isArmed && args[1].status === 'running') {
+        isArmed = false
+        inUpdate.open()
+        await releaseUpdate.opened
+      }
+      return update(...args)
+    }
+    const release = gate()
+    const { host, session, calls } = await openJoins(
+      [after(release.opened, 'first answer'), () => text('late answer')],
+      {},
+      persistence,
+    )
+
+    const turn = session.prompt('first')
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    const late = session.prompt('late', { busy: 'steer', inputId: 'late' })
+    await late.receipt
+    isArmed = true
+    release.open()
+    // The turn decided to run the model again for the late steer.
+    await inUpdate.opened
+    const receipt = await session.cancel(late.id)
+    releaseUpdate.open()
+
+    expect(receipt).toMatchObject({ status: 'rejected', reason: 'not_running' })
+    expect(await turn).toEqual({ text: 'first answerlate answer' })
+    expect(calls).toHaveLength(2)
+    expect(messageTexts(calls[1]).at(-1)).toBe('late')
+    await host.close()
+  })
+
+  it('adds the onJoin messages after the joined ones, also when it saves before each call', async () => {
+    const { host, session, calls, wait } = await openJoins(
+      [() => toolCall('wait', {}), () => text('done')],
+      {
+        onModelError: () => undefined,
+        onJoin: () => ({ messages: [{ role: 'user', content: 'hook' }] }),
+      },
+    )
+
+    const turn = session.prompt('start')
+    await wait.started.opened
+    await session.prompt('more', { busy: 'steer' }).receipt
+    wait.done.open()
+
+    await turn
+    expect(messageTexts(calls[1]).slice(-2)).toEqual(['more', 'hook'])
+    await host.close()
+  })
+
+  it('fails the turn when onJoin throws, and runs the steer as its own turn', async () => {
+    const { host, session, calls, wait } = await openJoins(
+      [() => toolCall('wait', {}), () => text('steer answer')],
+      {
+        onJoin: () => {
+          throw new Error('hook broke')
+        },
+      },
+    )
+
+    const turn = session.prompt('start')
+    await wait.started.opened
+    const steer = session.prompt('more', { busy: 'steer', inputId: 's1' })
+    await steer.receipt
+    wait.done.open()
+
+    await expect(turn).rejects.toThrow('hook broke')
+    expect(await steer).toEqual({ text: 'steer answer' })
+    expect(messageTexts(calls[1])).toContain('more')
+    expect((await session.settled('s1')).operationId).not.toBe(turn.id)
+    await host.close()
+  })
+
+  it('adds nothing from onJoin to a turn cancelled while the hook runs', async () => {
+    const inJoin = gate()
+    const releaseJoin = gate()
+    const { host, session, calls, wait } = await openJoins(
+      [
+        () => toolCall('wait', {}),
+        () => text('cancelled answer'),
+        () => text('steer answer'),
+      ],
+      {
+        onJoin: async () => {
+          inJoin.open()
+          await releaseJoin.opened
+          return { messages: [{ role: 'user', content: 'hook' }] }
+        },
+      },
+    )
+
+    const turn = session.prompt('start')
+    await wait.started.opened
+    const steer = session.prompt('more', { busy: 'steer', inputId: 's1' })
+    await steer.receipt
+    wait.done.open()
+    await inJoin.opened
+    await turn.cancel()
+    releaseJoin.open()
+
+    await expect(turn).rejects.toThrow('Cancelled')
+    expect(await steer).toEqual({ text: 'steer answer' })
+    for (const call of calls) expect(messageTexts(call)).not.toContain('hook')
+    expect(messageTexts(calls.at(-1))).toContain('more')
+    expect((await session.settled('s1')).operationId).not.toBe(turn.id)
+    await host.close()
+  })
+})

From 8e3c4d9d444f782a60c82273868e4d00aecc3d72 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Thu, 1 Oct 2026 19:41:48 +0200
Subject: [PATCH 146/286] test(ai-harness): a join stops at a steer cancelled
 while canJoin runs

---
 packages/ai-harness/tests/session.test.ts | 41 ++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/packages/ai-harness/tests/session.test.ts b/packages/ai-harness/tests/session.test.ts
index 9f13f25483..537de86f7c 100644
--- a/packages/ai-harness/tests/session.test.ts
+++ b/packages/ai-harness/tests/session.test.ts
@@ -23,7 +23,7 @@ import {
   untilAborted,
 } from './helpers'
 import type { StreamChunk } from '@tanstack/ai'
-import type { HarnessTurnOptions, SessionEvent } from '../src'
+import type { HarnessTurnOptions, Receipt, SessionEvent } from '../src'
 import type { Reply } from './helpers'
 
 function setup() {
@@ -719,4 +719,43 @@ describe('joins without a log', () => {
     expect((await session.settled('s1')).operationId).not.toBe(turn.id)
     await host.close()
   })
+
+  it('stops at a steer that a cancel reaches while canJoin runs', async () => {
+    let cancelled: Receipt | undefined
+    let aId = ''
+    let session: Awaited<ReturnType<typeof openJoins>>['session'] | undefined
+    const joins = await openJoins(
+      [
+        () => toolCall('wait', {}),
+        () => text('host answer'),
+        () => text('b answer'),
+      ],
+      {
+        canJoin: async ({ inputId }) => {
+          // The cancel of the earlier steer lands while canJoin runs for `b`.
+          if (inputId === 'b' && !cancelled) {
+            cancelled = await session?.cancel(aId)
+          }
+          return true
+        },
+      },
+    )
+    session = joins.session
+    const { host, calls, wait } = joins
+
+    const turn = session.prompt('start')
+    await wait.started.opened
+    const a = session.prompt('a', { busy: 'steer', inputId: 'a' })
+    aId = a.id
+    const b = session.prompt('b', { busy: 'steer', inputId: 'b' })
+    await Promise.all([a.receipt, b.receipt])
+    wait.done.open()
+    await turn
+
+    expect(cancelled?.status).toBe('accepted')
+    expect(messageTexts(calls[1])).not.toContain('a')
+    expect(await session.settled('a')).toMatchObject({ outcome: 'aborted' })
+    expect(await b).toEqual({ text: 'b answer' })
+    await host.close()
+  })
 })

From 40bce96759cc290f23c9bca5b887f5067f601eaa Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 10:19:10 +0200
Subject: [PATCH 147/286] fix(ai-harness): fail a background agent that a
 stopped host left running

A background agent run held no lease, and restart recovery skipped it.
After a crash, its run stayed `running`, its input never settled, and the
thread never woke.

- The agent run now holds the run lease and the turn lease, like a chat turn.
- When the lease expired, the next host ends the run `failed`, sends
  RUN_ERROR and operationFinished, and adds a note to the transcript. On a
  durable host, it also settles the input and wakes the thread for
  `wake: true`. The agent does not run again: it has no checkpoints.
- An agent input now settles in the log when the agent ends.
- A background agent that fails also writes a note and wakes the thread.
- After a log failure, a host does not write the run record or the log, so
  a stopped host cannot overwrite the status that the next host wrote.
---
 .changeset/harness-agent-restart.md           |   7 +
 docs/config.json                              |   6 +-
 docs/harness/durable-sessions.md              |   8 +
 docs/harness/overview.md                      |   4 +-
 docs/harness/subagents.md                     |   2 +-
 packages/ai-harness/src/resume.ts             |  55 +++--
 packages/ai-harness/src/session.ts            | 194 ++++++++++++++----
 .../ai-harness/tests/durable-inputs.test.ts   |  58 +++++-
 packages/ai-harness/tests/leases.test.ts      |  85 +++++++-
 packages/ai-harness/tests/resume.test.ts      | 103 +++++++++-
 packages/ai-harness/tests/session.test.ts     |  27 +++
 testing/e2e/fixtures/harness/basic.json       |   8 +
 testing/e2e/src/routes/api.harness-test.ts    |  61 +++++-
 testing/e2e/tests/harness.spec.ts             |  14 ++
 14 files changed, 559 insertions(+), 73 deletions(-)
 create mode 100644 .changeset/harness-agent-restart.md

diff --git a/.changeset/harness-agent-restart.md b/.changeset/harness-agent-restart.md
new file mode 100644
index 0000000000..20704cb450
--- /dev/null
+++ b/.changeset/harness-agent-restart.md
@@ -0,0 +1,7 @@
+---
+'@tanstack/ai-harness': patch
+---
+
+A background agent run no longer stays `running` after its host stops. The agent run now holds a lease, like a chat turn. When the lease expires, the next host ends the run `failed` and adds a note to the transcript. On a durable host, it also settles the input and, for `start(input, { wake: true })`, starts a new turn. The run does not run again, because it has no checkpoints.
+
+A background agent that fails now also writes a note, and with `wake: true` it starts a new turn, the same as an agent that finishes.
diff --git a/docs/config.json b/docs/config.json
index 48c94fcf57..61e044986d 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -878,7 +878,7 @@
           "label": "Build your first harness",
           "to": "harness/overview",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-09-29"
+          "updatedAt": "2026-10-02"
         },
         {
           "label": "Connect clients",
@@ -901,7 +901,7 @@
           "label": "Durable sessions",
           "to": "harness/durable-sessions",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-10-01"
+          "updatedAt": "2026-10-02"
         },
         {
           "label": "Send inputs safely",
@@ -997,7 +997,7 @@
           "label": "Run agents from a harness",
           "to": "harness/subagents",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-09-29"
+          "updatedAt": "2026-10-02"
         },
         {
           "label": "Deploy a harness",
diff --git a/docs/harness/durable-sessions.md b/docs/harness/durable-sessions.md
index aaac2e1e54..f32d307629 100644
--- a/docs/harness/durable-sessions.md
+++ b/docs/harness/durable-sessions.md
@@ -67,6 +67,14 @@ When a host opens the thread and finds a turn whose lease expired, it checks the
 
 An input that was stored but never ran, runs now. See [Send inputs safely](./inputs) to read how an input ended.
 
+A background agent does not run again, because it has no checkpoints. When its lease expired, the next host:
+
+1. Ends the run `failed`, with the message `The host stopped during this agent run.`
+2. Adds a note about the failure to the transcript.
+3. Starts a new turn, if you started the agent with `{ wake: true }`.
+
+`durability.recover` does not run for background agents.
+
 ## Retry model errors
 
 A model call can fail for a short time: a 429, a 5xx, an overloaded provider, or a network error. Add `retryTransientErrors()` to run the model again in the same turn, after a backoff:
diff --git a/docs/harness/overview.md b/docs/harness/overview.md
index 45d9cd8aad..7872363f34 100644
--- a/docs/harness/overview.md
+++ b/docs/harness/overview.md
@@ -124,7 +124,7 @@ const price = await session.agents.pricer.run({ vendor: 'acme' })
 console.log(price.cents)
 ```
 
-The session adds a short note about the result to the transcript. The model sees it on the next turn. To run the agent in the background and start a new turn when it is done, use `start`:
+The session adds a short note about the result, or the error, to the transcript. The model sees it on the next turn. To run the agent in the background and start a new turn when it finishes or fails, use `start`:
 
 ```ts group=harness-first
 session.agents.pricer.start({ vendor: 'globex' }, { wake: true })
@@ -167,7 +167,7 @@ If two plugins add a tool with the same name, `host.open` fails and names both p
 The host takes the same stores as `withPersistence`. Add an `inbox` store and the session also keeps the messages it accepted but did not start yet. When the session opens again, it runs them.
 
 - `messages`: the transcript. Required.
-- `runs`: the record of every turn and agent run.
+- `runs`: the record of every turn and agent run. When the host stops during a background agent run, the next session ends that run `failed` and notes it in the transcript.
 - `interrupts`: approvals that wait for a user.
 - `inbox`: accepted messages that did not run yet.
 
diff --git a/docs/harness/subagents.md b/docs/harness/subagents.md
index adb79e6170..d13f537e6f 100644
--- a/docs/harness/subagents.md
+++ b/docs/harness/subagents.md
@@ -59,7 +59,7 @@ export const review = definePlugin({
 ```
 
 - `ctx.agents.run(agent, input)` runs one agent and resolves with its result.
-- `ctx.agents.start(agent, input, { wake: true })` runs it in the background and starts a turn when it is done.
+- `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.
 
 To track usage or apply a policy in each of these runs, see [Middleware in every agent](./plugins#middleware-in-every-agent).
diff --git a/packages/ai-harness/src/resume.ts b/packages/ai-harness/src/resume.ts
index 6d55f78ea0..174adf0197 100644
--- a/packages/ai-harness/src/resume.ts
+++ b/packages/ai-harness/src/resume.ts
@@ -33,6 +33,31 @@ export type PendingTool = {
 const errorText = (error: unknown) =>
   error instanceof Error ? error.message : String(error)
 
+/**
+ * Hold the lease on run `runId` and renew it. Returns the function that stops
+ * the renewal. A host that stops lets the lease expire, so recovery can tell
+ * the run is dead.
+ */
+export async function holdRunLease(
+  runs: RunStore | undefined,
+  runId: string,
+  hostId: string,
+  lease?: LeaseOptions,
+): Promise<() => void> {
+  if (!runs) return () => {}
+  const ttlMs = lease?.ttlMs ?? LEASE.ttlMs
+  const renew = () =>
+    runs.update(runId, {
+      leaseOwner: hostId,
+      leaseExpiresAt: Date.now() + ttlMs,
+    })
+  await renew()
+  const timer = setInterval(() => void renew(), lease?.renewMs ?? LEASE.renewMs)
+  // A lease timer must not keep a CLI or a test process alive.
+  if (typeof timer === 'object' && 'unref' in timer) timer.unref()
+  return () => clearInterval(timer)
+}
+
 /**
  * Chat middleware that makes a turn resumable after a crash:
  *
@@ -59,11 +84,9 @@ export function checkpointMiddleware(options: {
   }) => void | Promise<void>
 }): AnyChatMiddleware {
   const { runs, messages, hostId, onToolResult } = options
-  const ttlMs = options.lease?.ttlMs ?? LEASE.ttlMs
-  const renewMs = options.lease?.renewMs ?? LEASE.renewMs
   const state = new WeakMap<
     object,
-    { timer: ReturnType<typeof setInterval>; pending: Array<PendingTool> }
+    { stopLease: () => void; pending: Array<PendingTool> }
   >()
 
   const saveCheckpoint = async (runId: string, pending: Array<PendingTool>) => {
@@ -72,24 +95,20 @@ export function checkpointMiddleware(options: {
     })
   }
   const stop = (ctx: object) => {
-    const entry = state.get(ctx)
-    if (entry) clearInterval(entry.timer)
+    state.get(ctx)?.stopLease()
     state.delete(ctx)
   }
 
   return {
     name: 'harness:checkpoint',
     async onStart(ctx) {
-      const renew = () =>
-        runs?.update(ctx.runId, {
-          leaseOwner: hostId,
-          leaseExpiresAt: Date.now() + ttlMs,
-        })
-      await renew()
-      const timer = setInterval(() => void renew(), renewMs)
-      // A lease timer must not keep a CLI or a test process alive.
-      if (typeof timer === 'object' && 'unref' in timer) timer.unref()
-      state.set(ctx, { timer, pending: [] })
+      const stopLease = await holdRunLease(
+        runs,
+        ctx.runId,
+        hostId,
+        options.lease,
+      )
+      state.set(ctx, { stopLease, pending: [] })
     },
     async onBeforeToolCall(ctx, hook) {
       const entry = state.get(ctx)
@@ -146,7 +165,7 @@ export function checkpointMiddleware(options: {
   }
 }
 
-/** Chat runs of this thread that a crashed host left `running`. */
+/** Chat and agent runs of this thread that a crashed host left `running`. */
 export async function findCrashedRuns(
   runs: RunStore | undefined,
   threadId: string,
@@ -157,7 +176,9 @@ export async function findCrashedRuns(
   return records.filter(
     (record) =>
       record.status === 'running' &&
-      (record.kind === undefined || record.kind === 'chat') &&
+      (record.kind === undefined ||
+        record.kind === 'chat' ||
+        record.kind === 'agent') &&
       record.leaseExpiresAt !== undefined &&
       record.leaseExpiresAt < now,
   )
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 261b4f9970..d3ad1cb7a2 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -32,6 +32,7 @@ import {
   LEASE,
   checkpointMiddleware,
   findCrashedRuns,
+  holdRunLease,
   repairTranscript,
 } from './resume'
 import { HARNESS_EVENTS, InputRejectedError } from './types'
@@ -44,6 +45,7 @@ import type {
   ModelMessage,
   ProviderKeys,
   RunAgentResumeItem,
+  RunRecord,
   SchemaInput,
   StreamChunk,
   SubagentBinding,
@@ -106,16 +108,20 @@ import type {
 /** Options for running an agent from code. */
 export interface AgentRunOptions {
   /**
-   * How the main model learns about the result on its next turn:
-   * `'reference'` (default) adds a short note to the transcript, `'none'` adds
-   * nothing.
+   * How the main model learns about the result or the error on its next
+   * turn: `'reference'` (default) adds a short note to the transcript,
+   * `'none'` adds nothing.
    */
   attach?: 'reference' | 'none'
 }
 
 /** Options for starting an agent in the background. */
 export interface AgentStartOptions extends AgentRunOptions {
-  /** When the agent finishes, start a new chat turn with its result. */
+  /**
+   * When the agent finishes or fails, start a new chat turn with its result
+   * or its error. On a durable host, this also occurs when the host stopped
+   * during the run.
+   */
   wake?: boolean
 }
 
@@ -264,16 +270,23 @@ function customEvent(
 const errorText = (error: unknown) =>
   error instanceof Error ? error.message : String(error)
 
-/** A short transcript note about an agent result, for the next turn. */
-function referenceNote(agent: string, result: unknown): string {
+/** A short transcript note about how an agent ended, for the next turn. */
+function referenceNote(
+  agent: string,
+  result: unknown,
+  ended: 'finished' | 'failed' = 'finished',
+): string {
   const body =
     typeof result === 'string'
       ? result
       : JSON.stringify(compactForModel(result))
   const clipped = body.length > 2000 ? `${body.slice(0, 2000)}...` : body
-  return `[${agent} finished] ${clipped}`
+  return `[${agent} ${ended}] ${clipped}`
 }
 
+/** Why recovery fails an agent run whose host stopped. */
+const AGENT_STOPPED = 'The host stopped during this agent run.'
+
 /**
  * The kinds a model reads: the adapter's input list, narrowed by
  * `media.accepts`. Either one alone when only one is known, and `undefined`
@@ -288,7 +301,7 @@ export function acceptedKinds(
   return accepts.filter((kind) => modalities.includes(kind))
 }
 
-/** The inputs that run as chat turns, and settle. */
+/** The inputs that run as chat turns. They settle, and so do agent inputs. */
 const CHAT_OPS = new Set<string>(['prompt', 'steer', 'followUp', 'resolve'])
 
 /** Why a turn stops when its input passes its time limit. */
@@ -1822,14 +1835,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   }
 
   /**
-   * Hold the lease of a turn attempt in `stores.leases` while it runs.
-   * Returns the function that releases it. Without a lease store (or
-   * without a log), it returns nothing: the run lease of the checkpoint
-   * middleware decides.
+   * Hold the lease of a turn or agent attempt in `stores.leases` while it
+   * runs. Returns the function that releases it. Without a lease store (or
+   * without a log), it returns nothing: the run lease decides.
    */
   private async holdLease(
     inputId: string | undefined,
-    operation: OperationImpl<ChatTurnResult>,
+    operation: OperationImpl<unknown> | OperationImpl<ChatTurnResult>,
   ): Promise<(() => Promise<void>) | undefined> {
     const leases = this.persistence.stores.leases
     const attempt =
@@ -2500,7 +2512,17 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     let result: unknown
     let failure: string | undefined
     let subagentRunId = ''
+    let stopRunLease = () => {}
+    let releaseLease: (() => Promise<void>) | undefined
     try {
+      // A host that stops lets these leases expire. Then recovery fails the run.
+      stopRunLease = await holdRunLease(
+        runs,
+        operation.id,
+        this.hostId,
+        this.lease,
+      )
+      releaseLease = await this.holdLease(inputId, operation)
       const messages = await this.messages.loadThread(this.threadId)
       subagentRunId = createSubagentId()
       const stream = runAgentStream(
@@ -2549,6 +2571,23 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }
 
     const value = result !== undefined ? result : text
+    // The run record and the log keep how the agent ended, so recovery
+    // leaves it alone. After a log failure, another host owns the thread and
+    // decides how the run ended, so this host writes neither.
+    const end = async (
+      run: Pick<RunRecord, 'status'> &
+        Partial<Pick<RunRecord, 'error' | 'result'>>,
+      settlement: Pick<InputSettlement, 'outcome' | 'error'>,
+    ) => {
+      if (this.logFailure) return
+      await runs?.update(operation.id, { ...run, finishedAt: Date.now() })
+      // A refused append stops the session. The operation still ends.
+      await this.settle({
+        inputId,
+        operationId: operation.id,
+        ...settlement,
+      }).catch(() => {})
+    }
     if (operation.abortController.signal.aborted) {
       operation.publish({
         type: EventType.RUN_FINISHED,
@@ -2557,10 +2596,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         outcome: { type: 'cancelled' },
         timestamp: Date.now(),
       } as StreamChunk)
-      await runs?.update(operation.id, {
-        status: 'aborted',
-        finishedAt: Date.now(),
-      })
+      await end({ status: 'aborted' }, { outcome: 'aborted' })
       operation.fail('cancelled', new Error('Cancelled.'))
     } else if (failure !== undefined) {
       operation.publish({
@@ -2568,11 +2604,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         message: failure,
         timestamp: Date.now(),
       })
-      await runs?.update(operation.id, {
-        status: 'failed',
-        finishedAt: Date.now(),
-        error: { message: failure },
-      })
+      const error = { message: failure }
+      await end({ status: 'failed', error }, { outcome: 'failed', error })
+      await this.noteAgentEnd(name, 'failed', failure, options)
       operation.fail('failed', new Error(failure))
     } else {
       operation.publish({
@@ -2582,25 +2616,81 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         result: value,
         timestamp: Date.now(),
       } as StreamChunk)
-      await runs?.update(operation.id, {
-        status: 'completed',
-        finishedAt: Date.now(),
-        result: compactForModel(value),
-      })
-      if ((options.attach ?? 'reference') === 'reference') {
-        this.pendingNotes.push(referenceNote(name, value))
-        if (!this.activeTurn) await this.flushNotes()
-      }
+      await end(
+        { status: 'completed', result: compactForModel(value) },
+        { outcome: 'completed' },
+      )
+      await this.noteAgentEnd(name, 'finished', value, options)
       operation.finish('completed', value)
-      if (options.wake) {
-        void this.followUp(
-          `Background agent ${name} finished: ${referenceNote(name, value)}`,
-        )
-      }
     }
+    stopRunLease()
+    await releaseLease?.()
     this.publishFinished(operation)
   }
 
+  /**
+   * Tell the main model how an agent ended: a transcript note (unless
+   * `attach: 'none'`), and a new chat turn when `wake` is set.
+   */
+  private async noteAgentEnd(
+    name: string,
+    ended: 'finished' | 'failed',
+    result: unknown,
+    options: AgentStartOptions,
+  ): Promise<void> {
+    const note = referenceNote(name, result, ended)
+    if ((options.attach ?? 'reference') === 'reference') {
+      this.pendingNotes.push(note)
+      if (!this.activeTurn) await this.flushNotes()
+    }
+    if (options.wake) {
+      void this.followUp(`Background agent ${name} ${ended}: ${note}`)
+    }
+  }
+
+  /**
+   * Fail an agent run whose host stopped. Its events end the operation for
+   * views, and the main model gets a note.
+   */
+  // ponytail: `wake` comes from the log. Without a log there is no wake, only
+  // the note. Keep `wake` on the run record if a host without a log needs it.
+  private async failStoppedAgent(stopped: {
+    operationId: string
+    agent: string
+    inputId?: string
+    wake?: boolean
+  }): Promise<void> {
+    const { operationId, inputId } = stopped
+    await this.persistence.stores.runs?.update(operationId, {
+      status: 'failed',
+      finishedAt: Date.now(),
+      error: { message: AGENT_STOPPED },
+    })
+    if (inputId) {
+      await this.settle({
+        inputId,
+        operationId,
+        outcome: 'failed',
+        error: { message: AGENT_STOPPED },
+      })
+    }
+    this.feed.publish(operationId, {
+      type: EventType.RUN_ERROR,
+      message: AGENT_STOPPED,
+      timestamp: Date.now(),
+    })
+    this.feed.publish(
+      operationId,
+      customEvent(HARNESS_EVENTS.operationFinished, {
+        operationId,
+        status: 'failed',
+      }),
+    )
+    await this.noteAgentEnd(stopped.agent, 'failed', AGENT_STOPPED, {
+      wake: stopped.wake === true,
+    })
+  }
+
   /** Write queued agent notes to the transcript while no turn is writing it. */
   private async flushNotes(): Promise<void> {
     const messages = this.messages
@@ -2902,13 +2992,20 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
 
   /**
    * Continue the newest chat turn that a crashed host left running. Older
-   * crashed turns are marked failed.
+   * crashed turns are marked failed, and so are crashed agent runs.
    */
   private async recoverCrashedTurn(): Promise<void> {
-    const crashed = await findCrashedRuns(
+    const runs = await findCrashedRuns(
       this.persistence.stores.runs,
       this.threadId,
     )
+    for (const run of runs.filter((record) => record.kind === 'agent')) {
+      await this.failStoppedAgent({
+        operationId: run.runId,
+        agent: run.agent ?? 'agent',
+      })
+    }
+    const crashed = runs.filter((record) => record.kind !== 'agent')
     const newest = crashed.sort((a, b) => b.startedAt - a.startedAt)[0]
     for (const record of crashed) {
       await this.persistence.stores.runs?.update(record.runId, {
@@ -2996,8 +3093,10 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
    * order. A chat turn whose host stopped (its run lease expired) settles
    * `aborted` when an abort was asked, settles `failed` when no attempt or no
    * time is left, settles `completed` when the log already has its final
-   * answer, and else runs again as the next attempt. An input that never ran
-   * runs now. Other inputs are rejected with `expired_on_restart`.
+   * answer, and else runs again as the next attempt. An agent run whose host
+   * stopped settles `failed` and does not run again: it has no checkpoints.
+   * An input that never ran runs now. Other inputs are rejected with
+   * `expired_on_restart`.
    */
   private async recoverFromLog(writer: LogWriter): Promise<void> {
     const runs = this.persistence.stores.runs
@@ -3035,7 +3134,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         })
         continue
       }
-      if (input.status !== 'applied' || !isChat) continue
+      const isAgent = input.input.op === 'agent'
+      if (input.status !== 'applied' || !(isChat || isAgent)) continue
       const leases = this.persistence.stores.leases
       const run = input.operationId ? await runs?.get(input.operationId) : null
       const now = Date.now()
@@ -3053,6 +3153,18 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             run.leaseExpiresAt >= now
       // Another host still drives this turn.
       if (isAlive) continue
+      if (input.input.op === 'agent') {
+        // A run that ended before its settle record landed did not stop.
+        if (!run || run.status === 'running') {
+          await this.failStoppedAgent({
+            operationId: input.operationId ?? '',
+            agent: input.input.agent,
+            inputId: input.inputId,
+            wake: input.input.detached,
+          })
+        }
+        continue
+      }
       if (run?.status === 'running') {
         await runs?.update(run.runId, {
           status: 'failed',
diff --git a/packages/ai-harness/tests/durable-inputs.test.ts b/packages/ai-harness/tests/durable-inputs.test.ts
index 1f80adff09..ff67af2a3f 100644
--- a/packages/ai-harness/tests/durable-inputs.test.ts
+++ b/packages/ai-harness/tests/durable-inputs.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { InputRejectedError, createHarnessHost, defineHarness } from '../src'
-import { gate, mockAdapter, text, untilAborted } from './helpers'
+import { gate, messageTexts, mockAdapter, text, untilAborted } from './helpers'
 import type { ModelMessage } from '@tanstack/ai'
 import type { LogRecord } from '@tanstack/ai-persistence'
 import type { HarnessDurability } from '../src'
@@ -212,6 +212,62 @@ describe('recovery of a durable input', () => {
     await host.close()
   })
 
+  it('fails a background agent whose host stopped, and wakes the thread', async () => {
+    const persistence = durablePersistence()
+    await persistence.stores.log.append(THREAD, 1, [
+      {
+        type: 'harness.input',
+        inputId: 'in-agent',
+        input: { op: 'agent', agent: 'waiter', detached: true },
+        at: 1,
+      },
+      {
+        type: 'harness.input.applied',
+        inputId: 'in-agent',
+        operationId: 'op-agent',
+        attempt: 1,
+      },
+    ])
+    await persistence.stores.runs.createOrResume({
+      runId: 'op-agent',
+      threadId: THREAD,
+      startedAt: Date.now() - 60_000,
+      kind: 'agent',
+      agent: 'waiter',
+    })
+    await persistence.stores.runs.update('op-agent', {
+      leaseOwner: 'host-gone',
+      leaseExpiresAt: Date.now() - 1_000,
+    })
+
+    const { host, calls } = await openDurable({
+      persistence,
+      replies: [() => text('noted')],
+    })
+
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    expect(messageTexts(calls[0]).slice(-2)).toEqual([
+      '[waiter failed] The host stopped during this agent run.',
+      'Background agent waiter failed: [waiter failed] The host stopped during this agent run.',
+    ])
+    expect((await persistence.stores.runs.get('op-agent'))?.status).toBe(
+      'failed',
+    )
+    const settled = (await persistence.stores.log.read(THREAD))
+      .map((entry) => entry.record)
+      .find(
+        (record) =>
+          record.type === 'harness.input.settled' &&
+          record.inputId === 'in-agent',
+      )
+    expect(settled).toMatchObject({
+      operationId: 'op-agent',
+      outcome: 'failed',
+      error: { message: 'The host stopped during this agent run.' },
+    })
+    await host.close()
+  })
+
   it('settles an input with the recover hook that the default would run again', async () => {
     const persistence = durablePersistence()
     await seedStoppedTurn(persistence, { attempt: 1 })
diff --git a/packages/ai-harness/tests/leases.test.ts b/packages/ai-harness/tests/leases.test.ts
index e8f23df31f..2b505d545d 100644
--- a/packages/ai-harness/tests/leases.test.ts
+++ b/packages/ai-harness/tests/leases.test.ts
@@ -1,10 +1,17 @@
 import { describe, expect, it, vi } from 'vitest'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness } from '../src'
-import { toolDefinition } from '@tanstack/ai'
+import { defineAgent, toolDefinition } from '@tanstack/ai'
 import { z } from 'zod'
 import { INTERRUPTED_TOOL_RESULT } from '../src/resume'
-import { after, gate, mockAdapter, text, toolCall } from './helpers'
+import {
+  after,
+  gate,
+  messageTexts,
+  mockAdapter,
+  text,
+  toolCall,
+} from './helpers'
 import type { AnyTool, StreamChunk } from '@tanstack/ai'
 import { EventType } from '@tanstack/ai'
 import type {
@@ -16,6 +23,16 @@ import type { Reply } from './helpers'
 
 const THREAD = 't1'
 
+/** A background agent that runs until it is cancelled. */
+const waiter = defineAgent({
+  name: 'waiter',
+  description: 'Waits until it is cancelled',
+  run: (ctx) =>
+    new Promise<string>((resolve) =>
+      ctx.abortSignal?.addEventListener('abort', () => resolve('stopped')),
+    ),
+})
+
 /** A lease store in memory, like a job queue's leases. */
 function memoryLeases() {
   const leases = new Map<string, TurnLease>()
@@ -176,6 +193,41 @@ describe('a durable host with a lease store and no run store', () => {
     await next.host.close()
   })
 
+  it('fails a background agent with an expired lease, and keeps a finished one', async () => {
+    const leases = memoryLeases()
+    const persistence = leasedPersistence(leases.store)
+    const pricer = defineAgent({
+      name: 'pricer',
+      description: 'Prices',
+      run: async () => 'priced',
+    })
+    const first = createHarnessHost({ persistence })
+    const session = await first.open(
+      defineHarness({
+        name: 'test/leases',
+        adapter: mockAdapter([]).adapter,
+        agents: [pricer, waiter],
+      }),
+      { threadId: THREAD },
+    )
+    await session.agents.pricer.run()
+    session.agents.waiter.start(undefined, { wake: true })
+    await vi.waitFor(() => expect(leases.leases.size).toBe(1))
+
+    leases.expire()
+    const next = await openLeased(persistence, [() => text('noted')])
+    await vi.waitFor(() => expect(next.calls).toHaveLength(1))
+    await vi.waitFor(() => expect(next.session.snapshot().status).toBe('idle'))
+
+    // One wake, for the agent that stopped. The finished agent stays settled.
+    expect(next.calls).toHaveLength(1)
+    expect(messageTexts(next.calls[0]).at(-1)).toBe(
+      'Background agent waiter failed: [waiter failed] The host stopped during this agent run.',
+    )
+    await first.close().catch(() => {})
+    await next.host.close()
+  })
+
   it('repairs a cut batch from the log', async () => {
     const leases = memoryLeases()
     const persistence = leasedPersistence(leases.store)
@@ -300,4 +352,33 @@ describe('a durable host with runs and leases', () => {
     expect((await runs.get(turn.id))?.status).toBe('completed')
     await host.close()
   })
+
+  it('keeps the failed run when the stopped host ends its agent later', async () => {
+    const leases = memoryLeases()
+    const { runs } = memoryPersistence().stores
+    const persistence = {
+      stores: { log: memoryLogStore(), runs, leases: leases.store },
+    }
+    const harness = defineHarness({
+      name: 'test/leases',
+      adapter: mockAdapter([]).adapter,
+      agents: [waiter],
+    })
+    const first = createHarnessHost({ persistence })
+    const run = (
+      await first.open(harness, { threadId: THREAD })
+    ).agents.waiter.start()
+    await vi.waitFor(() => expect(leases.leases.size).toBe(1))
+
+    leases.expire()
+    const next = createHarnessHost({ persistence })
+    await next.open(harness, { threadId: THREAD })
+    // The first host sees the writes of the second host, so it stops and
+    // cancels its agent.
+    await expect(Promise.resolve(run)).rejects.toThrow('Cancelled.')
+
+    expect((await runs.get(run.id))?.status).toBe('failed')
+    await first.close().catch(() => {})
+    await next.close()
+  })
 })
diff --git a/packages/ai-harness/tests/resume.test.ts b/packages/ai-harness/tests/resume.test.ts
index efcfec3e7b..defd9e5cb7 100644
--- a/packages/ai-harness/tests/resume.test.ts
+++ b/packages/ai-harness/tests/resume.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 import { z } from 'zod'
-import { EventType, chat, toolDefinition } from '@tanstack/ai'
+import { EventType, chat, defineAgent, toolDefinition } from '@tanstack/ai'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { HARNESS_EVENTS, createHarnessHost, defineHarness } from '../src'
 import {
@@ -43,6 +43,30 @@ async function runWithCheckpoint(options: {
   return stores
 }
 
+/** A background agent that runs until it is cancelled. */
+const waiter = defineAgent({
+  name: 'waiter',
+  description: 'Waits until it is cancelled',
+  run: (ctx) =>
+    new Promise<string>((resolve) =>
+      ctx.abortSignal?.addEventListener('abort', () => resolve('stopped')),
+    ),
+})
+
+/** The event names of `operationId`, up to its `operationFinished` event. */
+async function operationEvents(
+  events: AsyncIterable<SessionEvent>,
+  operationId: string,
+) {
+  const names: Array<string> = []
+  for await (const { event, operationId: id } of events) {
+    if (id !== operationId) continue
+    names.push(event.type === EventType.CUSTOM ? event.name : event.type)
+    if (names.at(-1) === HARNESS_EVENTS.operationFinished) return names
+  }
+  return names
+}
+
 describe('checkpoints and leases', () => {
   it('holds a lease and records the running tool with its replay mode', async () => {
     const persistence = memoryPersistence()
@@ -89,6 +113,27 @@ describe('checkpoints and leases', () => {
     expect(finished?.checkpoint?.pendingTools).toEqual([])
     await host.close()
   })
+
+  it('holds a lease on a background agent run', async () => {
+    const persistence = memoryPersistence()
+    const host = createHarnessHost({ persistence })
+    const { adapter } = mockAdapter([])
+    const session = await host.open(
+      defineHarness({ name: 'test/agent-lease', adapter, agents: [waiter] }),
+      { threadId: 't1' },
+    )
+
+    const run = session.agents.waiter.start()
+    await vi.waitFor(async () =>
+      expect(
+        (await persistence.stores.runs.get(run.id))?.leaseExpiresAt,
+      ).toBeGreaterThan(Date.now()),
+    )
+    expect((await persistence.stores.runs.get(run.id))?.leaseOwner).toMatch(
+      /^host-/,
+    )
+    await host.close()
+  })
 })
 
 describe('crash resume', () => {
@@ -294,17 +339,62 @@ describe('crash resume', () => {
     expect(tools[0]?.content).toBe('charged')
   })
 
-  it('leaves a run alone while its lease is still valid', async () => {
+  it('fails a background agent that a crashed host left running, and notes it', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.runs.createOrResume({
+      runId: 'crashed-agent',
+      threadId: 't1',
+      startedAt: Date.now() - 60_000,
+      kind: 'agent',
+      agent: 'waiter',
+    })
+    await persistence.stores.runs.update('crashed-agent', {
+      leaseOwner: 'host-gone',
+      leaseExpiresAt: Date.now() - 1_000,
+    })
+    const { adapter, calls } = mockAdapter([])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({ name: 'test/agent-crash', adapter, agents: [waiter] }),
+      { threadId: 't1' },
+    )
+
+    expect(
+      await operationEvents(session.events({ from: '0' }), 'crashed-agent'),
+    ).toEqual([EventType.RUN_ERROR, HARNESS_EVENTS.operationFinished])
+    expect(await persistence.stores.runs.get('crashed-agent')).toMatchObject({
+      status: 'failed',
+      error: { message: 'The host stopped during this agent run.' },
+    })
+    const transcript = await persistence.stores.messages.loadThread('t1')
+    expect(transcript.at(-1)?.content).toBe(
+      '[waiter failed] The host stopped during this agent run.',
+    )
+    // Without a log, the session does not know if the agent was to wake it.
+    expect(calls).toHaveLength(0)
+    await host.close()
+  })
+
+  it('leaves a turn and an agent alone while their leases are still valid', async () => {
     const persistence = memoryPersistence()
     await persistence.stores.runs.createOrResume({
       runId: 'live-run',
       threadId: 't1',
       startedAt: Date.now(),
     })
-    await persistence.stores.runs.update('live-run', {
-      leaseOwner: 'host-other',
-      leaseExpiresAt: Date.now() + 20_000,
+    await persistence.stores.runs.createOrResume({
+      runId: 'live-agent',
+      threadId: 't1',
+      startedAt: Date.now(),
+      kind: 'agent',
+      agent: 'waiter',
     })
+    for (const runId of ['live-run', 'live-agent']) {
+      await persistence.stores.runs.update(runId, {
+        leaseOwner: 'host-other',
+        leaseExpiresAt: Date.now() + 20_000,
+      })
+    }
     const { adapter, calls } = mockAdapter([])
     const host = createHarnessHost({ persistence })
     const session = await host.open(
@@ -318,6 +408,9 @@ describe('crash resume', () => {
     expect((await persistence.stores.runs.get('live-run'))?.status).toBe(
       'running',
     )
+    expect((await persistence.stores.runs.get('live-agent'))?.status).toBe(
+      'running',
+    )
     await host.close()
   })
 })
diff --git a/packages/ai-harness/tests/session.test.ts b/packages/ai-harness/tests/session.test.ts
index 537de86f7c..1425dce9a9 100644
--- a/packages/ai-harness/tests/session.test.ts
+++ b/packages/ai-harness/tests/session.test.ts
@@ -358,6 +358,33 @@ describe('agents', () => {
     await vi.waitFor(() => expect(session.snapshot().status).toBe('idle'))
     await host.close()
   })
+
+  it('notes a failed background agent and wakes the session', async () => {
+    const failing = defineAgent({
+      name: 'failing',
+      description: 'Fails',
+      run: async () => {
+        throw new Error('no vendor')
+      },
+    })
+    const { host } = setup()
+    const { adapter, calls } = mockAdapter([() => text('sorry')])
+    const session = await host.open(
+      defineHarness({ name: 'test/wake-failed', adapter, agents: [failing] }),
+      { threadId: 't1' },
+    )
+
+    await expect(
+      session.agents.failing.start(undefined, { wake: true }),
+    ).rejects.toThrow('no vendor')
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    expect(messageTexts(calls[0]).slice(-2)).toEqual([
+      '[failing failed] no vendor',
+      'Background agent failing failed: [failing failed] no vendor',
+    ])
+    await vi.waitFor(() => expect(session.snapshot().status).toBe('idle'))
+    await host.close()
+  })
 })
 
 describe('inbox', () => {
diff --git a/testing/e2e/fixtures/harness/basic.json b/testing/e2e/fixtures/harness/basic.json
index bf217db275..dffde59aef 100644
--- a/testing/e2e/fixtures/harness/basic.json
+++ b/testing/e2e/fixtures/harness/basic.json
@@ -32,6 +32,14 @@
         "content": "It cost 12 dollars."
       }
     },
+    {
+      "match": {
+        "userMessage": "Background agent waiter failed: [waiter failed] The host stopped during this agent run."
+      },
+      "response": {
+        "content": "The waiter stopped before it finished."
+      }
+    },
     {
       "match": {
         "userMessage": "[harness-protocol] hello"
diff --git a/testing/e2e/src/routes/api.harness-test.ts b/testing/e2e/src/routes/api.harness-test.ts
index ff75aba9b1..110d03f755 100644
--- a/testing/e2e/src/routes/api.harness-test.ts
+++ b/testing/e2e/src/routes/api.harness-test.ts
@@ -1,14 +1,68 @@
 import { createFileRoute } from '@tanstack/react-router'
 import { chat, defineAgent } from '@tanstack/ai'
 import {
+  HARNESS_EVENTS,
   createHarnessHost,
   defineHarness,
   harnessText,
 } from '@tanstack/ai-harness'
-import { memoryPersistence } from '@tanstack/ai-persistence'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { z } from 'zod'
 import { createTextAdapter } from '@/lib/providers'
 
+/**
+ * Start a background agent on a durable host, and let that host stop: its
+ * short lease is not renewed in time. A second host opens the same log. It
+ * fails the run, and the wake turn answers. Returns the run status and the
+ * text of the wake turn.
+ */
+async function agentRestart(
+  openai: () => ReturnType<typeof createTextAdapter>['adapter'],
+) {
+  const { runs, metadata } = memoryPersistence().stores
+  const persistence = { stores: { log: memoryLogStore(), runs, metadata } }
+  const waiter = defineAgent({
+    name: 'waiter',
+    description: 'Waits until it is cancelled',
+    run: (ctx) =>
+      new Promise<string>((resolve) =>
+        ctx.abortSignal?.addEventListener('abort', () => resolve('stopped')),
+      ),
+  })
+  const harness = defineHarness({
+    name: 'e2e/harness-restart',
+    adapter: openai(),
+    agents: [waiter],
+  })
+  const stopped = createHarnessHost({
+    persistence,
+    lease: { ttlMs: 50, renewMs: 60_000 },
+  })
+  const next = createHarnessHost({ persistence })
+  try {
+    const first = await stopped.open(harness, { threadId: 'e2e-restart' })
+    const run = first.agents.waiter.start(undefined, { wake: true })
+    await new Promise((resolve) => setTimeout(resolve, 200))
+
+    const session = await next.open(harness, { threadId: 'e2e-restart' })
+    let text = ''
+    for await (const { event, operationId } of session.events({ from: '0' })) {
+      if (operationId === run.id) continue
+      if (event.type === 'TEXT_MESSAGE_CONTENT') text += event.delta
+      if (
+        event.type === 'CUSTOM' &&
+        event.name === HARNESS_EVENTS.operationFinished
+      )
+        break
+    }
+    return { status: (await runs.get(run.id))?.status, text }
+  } finally {
+    await next.close()
+    // The first host sees the writes of the second host, and stops.
+    await stopped.close().catch(() => {})
+  }
+}
+
 /**
  * Harness session. The main model and the agent are real OpenAI adapters
  * against aimock.
@@ -17,6 +71,8 @@ import { createTextAdapter } from '@/lib/providers'
  *   then runs with the first turn in its history.
  * - `agent`: `pricer` runs from code with typed input. Its result goes into
  *   the transcript, then a prompt runs.
+ * - `agent-restart`: a background agent runs on a durable host that stops.
+ *   The next host fails the run and wakes the thread.
  */
 export const Route = createFileRoute('/api/harness-test')({
   server: {
@@ -93,6 +149,9 @@ export const Route = createFileRoute('/api/harness-test')({
             )
             return Response.json({ workerRuns, text: turn.text })
           }
+          if (body.scenario === 'agent-restart') {
+            return Response.json(await agentRestart(openai))
+          }
           if (body.scenario === 'agent') {
             const result = await session.agents.pricer.run({
               task: '[harness-agent] price vendor a',
diff --git a/testing/e2e/tests/harness.spec.ts b/testing/e2e/tests/harness.spec.ts
index 667f53389d..be9c767f78 100644
--- a/testing/e2e/tests/harness.spec.ts
+++ b/testing/e2e/tests/harness.spec.ts
@@ -56,4 +56,18 @@ test.describe('harness session', () => {
     expect(body.result).toBe('Vendor A costs 12 dollars.')
     expect(body.text).toBe('It cost 12 dollars.')
   })
+
+  test('a background agent that a stopped host left running fails and wakes the thread', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'agent-restart', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    const body = await response.json()
+    expect(body.status).toBe('failed')
+    expect(body.text).toBe('The waiter stopped before it finished.')
+  })
 })

From ce2c04c8ade8edb426432ecb32ba8b2b1c4ebba2 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 10:26:28 +0200
Subject: [PATCH 148/286] fix(ai-claude-code): count cache tokens in
 promptTokens

promptTokens is now the total input: uncached input plus cache reads and cache writes. The cache parts stay in promptTokensDetails.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .../ai-claude-code/src/stream/translate.ts    |  8 +++--
 .../ai-claude-code/tests/translate.test.ts    | 30 +++++++++++++++++--
 2 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/packages/ai-claude-code/src/stream/translate.ts b/packages/ai-claude-code/src/stream/translate.ts
index 3a0543a73d..dfbb61de84 100644
--- a/packages/ai-claude-code/src/stream/translate.ts
+++ b/packages/ai-claude-code/src/stream/translate.ts
@@ -89,15 +89,17 @@ function buildUsage(
   totalCostUsd: number | undefined,
 ): TokenUsage<ClaudeCodeProviderUsageDetails> | undefined {
   if (!usage) return undefined
-  const promptTokens = usage.input_tokens ?? 0
+  const cacheWrite = usage.cache_creation_input_tokens ?? 0
+  const cacheRead = usage.cache_read_input_tokens ?? 0
+  // `input_tokens` counts only the uncached input. Add the cache reads and
+  // writes so promptTokens is the total input, the same as other providers.
+  const promptTokens = (usage.input_tokens ?? 0) + cacheRead + cacheWrite
   const completionTokens = usage.output_tokens ?? 0
   const result = buildBaseUsage<ClaudeCodeProviderUsageDetails>({
     promptTokens,
     completionTokens,
     totalTokens: promptTokens + completionTokens,
   })
-  const cacheWrite = usage.cache_creation_input_tokens
-  const cacheRead = usage.cache_read_input_tokens
   const promptTokensDetails = {
     ...(cacheWrite ? { cacheWriteTokens: cacheWrite } : {}),
     ...(cacheRead ? { cachedTokens: cacheRead } : {}),
diff --git a/packages/ai-claude-code/tests/translate.test.ts b/packages/ai-claude-code/tests/translate.test.ts
index 30432462a9..cd50055d57 100644
--- a/packages/ai-claude-code/tests/translate.test.ts
+++ b/packages/ai-claude-code/tests/translate.test.ts
@@ -181,19 +181,41 @@ describe('translateSdkStream', () => {
     expect(custom).toMatchObject({ value: { skills: [] } })
   })
 
-  it('maps usage onto RUN_FINISHED including cache token details', async () => {
+  it('maps usage onto RUN_FINISHED with promptTokens as uncached + cache read + cache write', async () => {
     const chunks = await collect([init, assistantText('hi'), resultSuccess])
     const finished = chunks.find((c) => c.type === 'RUN_FINISHED')
     expect(finished).toMatchObject({
       usage: {
-        promptTokens: 100,
+        promptTokens: 115,
         completionTokens: 50,
-        totalTokens: 150,
+        totalTokens: 165,
         promptTokensDetails: { cachedTokens: 10, cacheWriteTokens: 5 },
       },
     })
   })
 
+  it('counts cache reads in promptTokens when the SDK omits input_tokens', async () => {
+    const chunks = await collect([
+      init,
+      assistantText('hi'),
+      {
+        type: 'result',
+        subtype: 'success',
+        result: 'done',
+        usage: { output_tokens: 7, cache_read_input_tokens: 40 },
+      },
+    ])
+    const finished = chunks.find((c) => c.type === 'RUN_FINISHED')
+    expect(finished).toMatchObject({
+      usage: {
+        promptTokens: 40,
+        completionTokens: 7,
+        totalTokens: 47,
+        promptTokensDetails: { cachedTokens: 40 },
+      },
+    })
+  })
+
   it('emits resolved TOOL_CALL_* quadruples for harness tool activity and never finishes with tool_calls', async () => {
     const messages: Array<AgentSdkMessage> = [
       init,
@@ -640,6 +662,8 @@ describe('translateSdkStream', () => {
   it('ignores unknown SDK message types', async () => {
     const chunks = await collect([
       init,
+      // The cast is on purpose: this message type is not in the
+      // AgentSdkMessage union, and the test checks that the runtime skips it.
       {
         type: 'system',
         subtype: 'status',

From 2e4184adf89d40c550bda54b04ba9623957e0e58 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 10:27:09 +0200
Subject: [PATCH 149/286] fix(ai-bedrock): count cache tokens in promptTokens

Converse inputTokens is only the uncached input. promptTokens is now the total input with the cache reads and writes added. totalTokens is never less than the sum of the parts.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-bedrock/src/converse/usage.ts     | 33 ++++++-----
 .../ai-bedrock/tests/converse/adapter.test.ts |  4 +-
 .../tests/converse/stream-processor.test.ts   | 57 +++++++++++++------
 3 files changed, 62 insertions(+), 32 deletions(-)

diff --git a/packages/ai-bedrock/src/converse/usage.ts b/packages/ai-bedrock/src/converse/usage.ts
index 4287e2348c..7229c0cedb 100644
--- a/packages/ai-bedrock/src/converse/usage.ts
+++ b/packages/ai-bedrock/src/converse/usage.ts
@@ -1,25 +1,32 @@
 import { buildBaseUsage } from '@tanstack/ai'
-import type { TokenUsage } from '@tanstack/ai'
 import type { TokenUsage as ConverseTokenUsage } from '@aws-sdk/client-bedrock-runtime'
 
 /**
- * Build normalized {@link TokenUsage} from a Converse `usage` object.
+ * Build normalized `TokenUsage` from a Converse `usage` object.
  *
- * `inputTokens` is the uncached part of the input only. Cache reads and writes
- * come as separate fields and go on `promptTokensDetails`, same as the Anthropic
- * and OpenAI builders. Zero is kept, unlike those builders. Bedrock leaves the
- * fields out when no checkpoint applied and sends 0 when one did (a served
- * checkpoint writes 0), so absent and zero are different results.
+ * `promptTokens` is the total input. Converse `inputTokens` is only the
+ * uncached part, so the cache reads and cache writes are added to it. The two
+ * cache parts also go on `promptTokensDetails`. Zero is kept, unlike the
+ * Anthropic and OpenAI builders. Bedrock leaves the fields out when no
+ * checkpoint applied and sends 0 when one did (a served checkpoint writes 0),
+ * so absent and zero are different results.
  */
-export function buildConverseUsage(usage: ConverseTokenUsage): TokenUsage {
+export function buildConverseUsage(usage: ConverseTokenUsage) {
+  const cachedTokens = usage.cacheReadInputTokens
+  const cacheWriteTokens = usage.cacheWriteInputTokens
+  const promptTokens =
+    (usage.inputTokens ?? 0) + (cachedTokens ?? 0) + (cacheWriteTokens ?? 0)
+  const completionTokens = usage.outputTokens ?? 0
   const result = buildBaseUsage({
-    promptTokens: usage.inputTokens ?? 0,
-    completionTokens: usage.outputTokens ?? 0,
-    totalTokens: usage.totalTokens ?? 0,
+    promptTokens,
+    completionTokens,
+    // The provider total must not be lower than the sum of the parts.
+    totalTokens: Math.max(
+      usage.totalTokens ?? 0,
+      promptTokens + completionTokens,
+    ),
   })
 
-  const cachedTokens = usage.cacheReadInputTokens
-  const cacheWriteTokens = usage.cacheWriteInputTokens
   const promptTokensDetails = {
     ...(cachedTokens !== undefined ? { cachedTokens } : {}),
     ...(cacheWriteTokens !== undefined ? { cacheWriteTokens } : {}),
diff --git a/packages/ai-bedrock/tests/converse/adapter.test.ts b/packages/ai-bedrock/tests/converse/adapter.test.ts
index 2fa8ccd20c..30d8f1c936 100644
--- a/packages/ai-bedrock/tests/converse/adapter.test.ts
+++ b/packages/ai-bedrock/tests/converse/adapter.test.ts
@@ -229,7 +229,7 @@ describe('BedrockConverseTextAdapter', () => {
       outputSchema: { type: 'object', properties: { n: { type: 'number' } } },
     })
     expect(res.usage).toEqual({
-      promptTokens: 3,
+      promptTokens: 8412,
       completionTokens: 4,
       totalTokens: 8416,
       promptTokensDetails: { cachedTokens: 8409, cacheWriteTokens: 0 },
@@ -367,7 +367,7 @@ describe('BedrockConverseTextAdapter', () => {
     }
     const finished = events.find((e) => e.type === EventType.RUN_FINISHED)
     expect((finished as { usage?: unknown }).usage).toEqual({
-      promptTokens: 3,
+      promptTokens: 8412,
       completionTokens: 4,
       totalTokens: 8416,
       promptTokensDetails: { cachedTokens: 8409, cacheWriteTokens: 0 },
diff --git a/packages/ai-bedrock/tests/converse/stream-processor.test.ts b/packages/ai-bedrock/tests/converse/stream-processor.test.ts
index 4f8d1a93e5..620b304d45 100644
--- a/packages/ai-bedrock/tests/converse/stream-processor.test.ts
+++ b/packages/ai-bedrock/tests/converse/stream-processor.test.ts
@@ -2,7 +2,10 @@ import { describe, expect, it } from 'vitest'
 import { EventType } from '@tanstack/ai'
 import type { AdapterYieldChunk } from '@tanstack/ai'
 import { processConverseStream } from '../../src/converse/stream-processor'
-import type { ConverseStreamOutput } from '@aws-sdk/client-bedrock-runtime'
+import type {
+  ConverseStreamOutput,
+  TokenUsage as ConverseTokenUsage,
+} from '@aws-sdk/client-bedrock-runtime'
 
 // Test fixtures use the minimal field subset the processor reads. Cast at the
 // generator boundary to the SDK union type — the SDK marks every field as
@@ -175,27 +178,30 @@ describe('processConverseStream', () => {
     }
   })
 
-  it('forwards cache read/write counts as promptTokensDetails', async () => {
+  // Run one text turn with this metadata usage and return the usage on the
+  // terminal RUN_FINISHED.
+  async function finishedUsage(usage: ConverseTokenUsage) {
     const events = await collect(
       { contentBlockDelta: { delta: { text: 'hi' }, contentBlockIndex: 0 } },
       { messageStop: { stopReason: 'end_turn' } },
-      {
-        metadata: {
-          // inputTokens is the uncached part only; the cached prefix comes as
-          // its own fields.
-          usage: {
-            inputTokens: 3,
-            outputTokens: 4,
-            totalTokens: 8416,
-            cacheReadInputTokens: 0,
-            cacheWriteInputTokens: 8409,
-          },
-        },
-      },
+      { metadata: { usage } },
     )
     const finished = events.find((e) => e.type === EventType.RUN_FINISHED)
-    expect((finished as { usage?: unknown }).usage).toEqual({
-      promptTokens: 3,
+    return (finished as { usage?: unknown }).usage
+  }
+
+  it('forwards cache read/write counts as promptTokensDetails', async () => {
+    // inputTokens is the uncached part only; the cached prefix comes as its
+    // own fields. promptTokens is the total input: 3 + 0 + 8409.
+    const usage = await finishedUsage({
+      inputTokens: 3,
+      outputTokens: 4,
+      totalTokens: 8416,
+      cacheReadInputTokens: 0,
+      cacheWriteInputTokens: 8409,
+    })
+    expect(usage).toEqual({
+      promptTokens: 8412,
       completionTokens: 4,
       totalTokens: 8416,
       // Zero is a real value here. The checkpoint was served, not missing.
@@ -203,6 +209,23 @@ describe('processConverseStream', () => {
     })
   })
 
+  it('adds uncached, cache read, and cache write into promptTokens', async () => {
+    // No provider total here, so the total comes from the parts.
+    const usage = await finishedUsage({
+      inputTokens: 5,
+      outputTokens: 7,
+      totalTokens: undefined,
+      cacheReadInputTokens: 100,
+      cacheWriteInputTokens: 20,
+    })
+    expect(usage).toEqual({
+      promptTokens: 125,
+      completionTokens: 7,
+      totalTokens: 132,
+      promptTokensDetails: { cachedTokens: 100, cacheWriteTokens: 20 },
+    })
+  })
+
   it('drains a tool call that never received contentBlockStop (truncated stream)', async () => {
     const events = await collect(
       {

From 583d78caeeddd26651a69452fc1ab544d5670355 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 10:28:04 +0200
Subject: [PATCH 150/286] fix(ai-anthropic): count cache tokens in promptTokens

Anthropic input_tokens is only the uncached input. promptTokens is now the total input with the cache reads and writes added, as the TokenUsage type says.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-anthropic/src/usage.ts            |  28 +-
 .../tests/usage-extraction.test.ts            | 365 +++++-------------
 2 files changed, 115 insertions(+), 278 deletions(-)

diff --git a/packages/ai-anthropic/src/usage.ts b/packages/ai-anthropic/src/usage.ts
index 066d27c5df..ac37fff21d 100644
--- a/packages/ai-anthropic/src/usage.ts
+++ b/packages/ai-anthropic/src/usage.ts
@@ -21,9 +21,16 @@ export type AnthropicProviderUsageDetails = {
 
 /**
  * Build normalized TokenUsage from Anthropic's usage object.
- * Handles cache tokens and server tool use metrics. Returns `undefined` when
- * the provider reported no usage object, so callers omit the field rather than
- * fabricating zeroed totals.
+ *
+ * `promptTokens` is the total input: uncached + cache read + cache write.
+ * Anthropic's `input_tokens` counts only the uncached part, so this function
+ * adds the cache parts. The cache parts are also in `promptTokensDetails`:
+ * `cachedTokens` (read) and `cacheWriteTokens` (write). `totalTokens` is
+ * `promptTokens + completionTokens`.
+ *
+ * Also handles server tool use metrics. Returns `undefined` when the provider
+ * reported no usage object, so callers omit the field rather than fabricating
+ * zeroed totals.
  */
 export function buildAnthropicUsage(
   usage:
@@ -39,21 +46,24 @@ export function buildAnthropicUsage(
   // against a runtime-absent count without tripping no-unnecessary-condition
   // (the SDK types output_tokens as a required number).
   const outputTokens = usage.output_tokens || 0
+  // The SDK types these as `number | null`.
+  const cacheWrite = usage.cache_creation_input_tokens ?? 0
+  const cacheRead = usage.cache_read_input_tokens ?? 0
+  // `input_tokens` is only the uncached part. Add the cache parts so
+  // promptTokens is the total input, the same as the other adapters.
+  const promptTokens = inputTokens + cacheRead + cacheWrite
 
   const result = buildBaseUsage<AnthropicProviderUsageDetails>({
-    promptTokens: inputTokens,
+    promptTokens,
     completionTokens: outputTokens,
-    totalTokens: inputTokens + outputTokens,
+    totalTokens: promptTokens + outputTokens,
   })
 
   // Add prompt token details for cache tokens. Only attach the details object
   // when at least one field is present so we don't emit an empty `{}` (every
   // other adapter guards with the same Object.keys check).
-  const cacheCreation = usage.cache_creation_input_tokens
-  const cacheRead = usage.cache_read_input_tokens
-
   const promptTokensDetails = {
-    ...(cacheCreation ? { cacheWriteTokens: cacheCreation } : {}),
+    ...(cacheWrite ? { cacheWriteTokens: cacheWrite } : {}),
     ...(cacheRead ? { cachedTokens: cacheRead } : {}),
   }
   if (Object.keys(promptTokensDetails).length > 0) {
diff --git a/packages/ai-anthropic/tests/usage-extraction.test.ts b/packages/ai-anthropic/tests/usage-extraction.test.ts
index 312f39fd92..35ef73e112 100644
--- a/packages/ai-anthropic/tests/usage-extraction.test.ts
+++ b/packages/ai-anthropic/tests/usage-extraction.test.ts
@@ -1,25 +1,8 @@
-import type { TokenUsage } from '@tanstack/ai'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { chat } from '@tanstack/ai'
 import { AnthropicTextAdapter } from '../src/adapters/text'
 import type { AdapterYieldChunk } from '@tanstack/ai'
-
-/** `chat()` restores a TokenUsage object on RUN_FINISHED. */
-function tokenUsageOf(chunk: unknown): TokenUsage | undefined {
-  if (typeof chunk !== 'object' || chunk === null || !('usage' in chunk)) {
-    return undefined
-  }
-  const usage = chunk.usage
-  if (
-    typeof usage !== 'object' ||
-    usage === null ||
-    Array.isArray(usage) ||
-    !('promptTokens' in usage)
-  ) {
-    return undefined
-  }
-  return usage as TokenUsage
-}
+import type Anthropic_SDK from '@anthropic-ai/sdk'
 
 const mocks = vi.hoisted(() => {
   const betaMessagesCreate = vi.fn()
@@ -63,13 +46,15 @@ function createMockStream(
   }
 }
 
-describe('Anthropic usage extraction', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  it('extracts basic token usage from message_delta', async () => {
-    const mockStream = createMockStream([
+/**
+ * Stream one text reply. The final `message_delta` carries `deltaUsage`.
+ * Returns the usage that `chat()` puts on RUN_FINISHED.
+ */
+async function runFinishedUsage(
+  deltaUsage: Partial<Anthropic_SDK.Beta.BetaMessageDeltaUsage>,
+) {
+  mocks.betaMessagesCreate.mockResolvedValueOnce(
+    createMockStream([
       {
         type: 'message_start',
         message: {
@@ -78,10 +63,7 @@ describe('Anthropic usage extraction', () => {
           role: 'assistant',
           content: [],
           model: 'claude-opus-4-1',
-          usage: {
-            input_tokens: 100,
-            output_tokens: 0,
-          },
+          usage: { input_tokens: 100, output_tokens: 0 },
         },
       },
       {
@@ -97,270 +79,115 @@ describe('Anthropic usage extraction', () => {
       {
         type: 'message_delta',
         delta: { stop_reason: 'end_turn' },
-        usage: {
-          input_tokens: 100,
-          output_tokens: 50,
-        },
-      },
-      {
-        type: 'message_stop',
-      },
-    ])
+        usage: deltaUsage,
+      },
+      { type: 'message_stop' },
+    ]),
+  )
+
+  const chunks: Array<AdapterYieldChunk> = []
+  for await (const chunk of chat({
+    adapter: createAdapter(),
+    messages: [{ role: 'user', content: 'Hello' }],
+  })) {
+    chunks.push(chunk)
+  }
 
-    mocks.betaMessagesCreate.mockResolvedValueOnce(mockStream)
+  const doneChunk = chunks.find((c) => c.type === 'RUN_FINISHED')
+  // `unknown` so the loose chunk `usage` type does not leak into the tests.
+  const usage: unknown = doneChunk?.usage
+  return usage
+}
 
-    const chunks: Array<AdapterYieldChunk> = []
-    for await (const chunk of chat({
-      adapter: createAdapter(),
-      messages: [{ role: 'user', content: 'Hello' }],
-    })) {
-      chunks.push(chunk)
-    }
+describe('Anthropic usage extraction', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
 
-    const doneChunk = chunks.find((c) => c.type === 'RUN_FINISHED')
-    expect(doneChunk).toBeDefined()
-    expect(doneChunk?.usage).toMatchObject({
+  it('uses input_tokens as promptTokens when there are no cache fields', async () => {
+    const usage = await runFinishedUsage({
+      input_tokens: 100,
+      output_tokens: 50,
+    })
+
+    // No cache tokens and no server tool use: the detail objects must be
+    // omitted entirely rather than emitted as empty `{}` (matches every other
+    // adapter's guarded behavior).
+    expect(usage).toEqual({
       promptTokens: 100,
       completionTokens: 50,
       totalTokens: 150,
     })
   })
 
-  it('extracts cache token details', async () => {
-    const mockStream = createMockStream([
-      {
-        type: 'message_start',
-        message: {
-          id: 'msg_123',
-          type: 'message',
-          role: 'assistant',
-          content: [],
-          model: 'claude-opus-4-1',
-          usage: {
-            input_tokens: 100,
-            output_tokens: 0,
-            cache_creation_input_tokens: 50,
-            cache_read_input_tokens: 25,
-          },
-        },
-      },
-      {
-        type: 'content_block_start',
-        index: 0,
-        content_block: { type: 'text', text: '' },
-      },
-      {
-        type: 'content_block_delta',
-        index: 0,
-        delta: { type: 'text_delta', text: 'Hello world' },
-      },
-      {
-        type: 'message_delta',
-        delta: { stop_reason: 'end_turn' },
-        usage: {
-          input_tokens: 100,
-          output_tokens: 50,
-          cache_creation_input_tokens: 50,
-          cache_read_input_tokens: 25,
-        },
-      },
-      {
-        type: 'message_stop',
-      },
-    ])
+  it('adds cache read and cache write tokens to promptTokens', async () => {
+    const usage = await runFinishedUsage({
+      input_tokens: 100,
+      output_tokens: 50,
+      cache_creation_input_tokens: 50,
+      cache_read_input_tokens: 25,
+    })
 
-    mocks.betaMessagesCreate.mockResolvedValueOnce(mockStream)
+    // promptTokens = 100 uncached + 25 read + 50 write.
+    expect(usage).toEqual({
+      promptTokens: 175,
+      completionTokens: 50,
+      totalTokens: 225,
+      promptTokensDetails: {
+        cacheWriteTokens: 50,
+        cachedTokens: 25,
+      },
+    })
+  })
 
-    const chunks: Array<AdapterYieldChunk> = []
-    for await (const chunk of chat({
-      adapter: createAdapter(),
-      messages: [{ role: 'user', content: 'Hello' }],
-    })) {
-      chunks.push(chunk)
-    }
+  it('counts a cache hit with a null cache write field', async () => {
+    // The SDK types the cache fields as `number | null`.
+    const usage = await runFinishedUsage({
+      input_tokens: 12,
+      output_tokens: 40,
+      cache_creation_input_tokens: null,
+      cache_read_input_tokens: 1800,
+    })
 
-    const doneChunk = chunks.find((c) => c.type === 'RUN_FINISHED')
-    expect(doneChunk).toBeDefined()
-    expect(tokenUsageOf(doneChunk)?.promptTokensDetails).toEqual({
-      cacheWriteTokens: 50,
-      cachedTokens: 25,
+    expect(usage).toEqual({
+      promptTokens: 1812,
+      completionTokens: 40,
+      totalTokens: 1852,
+      promptTokensDetails: { cachedTokens: 1800 },
     })
   })
 
   it('extracts server tool use metrics', async () => {
-    const mockStream = createMockStream([
-      {
-        type: 'message_start',
-        message: {
-          id: 'msg_123',
-          type: 'message',
-          role: 'assistant',
-          content: [],
-          model: 'claude-opus-4-1',
-          usage: {
-            input_tokens: 100,
-            output_tokens: 0,
-          },
-        },
-      },
-      {
-        type: 'content_block_start',
-        index: 0,
-        content_block: { type: 'text', text: '' },
-      },
-      {
-        type: 'content_block_delta',
-        index: 0,
-        delta: { type: 'text_delta', text: 'Hello world' },
-      },
-      {
-        type: 'message_delta',
-        delta: { stop_reason: 'end_turn' },
-        usage: {
-          input_tokens: 100,
-          output_tokens: 50,
-          server_tool_use: {
-            web_search_requests: 3,
-            web_fetch_requests: 2,
-          },
-        },
-      },
-      {
-        type: 'message_stop',
-      },
-    ])
-
-    mocks.betaMessagesCreate.mockResolvedValueOnce(mockStream)
-
-    const chunks: Array<AdapterYieldChunk> = []
-    for await (const chunk of chat({
-      adapter: createAdapter(),
-      messages: [{ role: 'user', content: 'Hello' }],
-    })) {
-      chunks.push(chunk)
-    }
-
-    const doneChunk = chunks.find((c) => c.type === 'RUN_FINISHED')
-    expect(doneChunk).toBeDefined()
-    expect(tokenUsageOf(doneChunk)?.providerUsageDetails).toMatchObject({
-      serverToolUse: {
-        webSearchRequests: 3,
-        webFetchRequests: 2,
+    const usage = await runFinishedUsage({
+      input_tokens: 100,
+      output_tokens: 50,
+      server_tool_use: {
+        web_search_requests: 3,
+        web_fetch_requests: 2,
       },
     })
-  })
 
-  it('handles response with no cache tokens', async () => {
-    const mockStream = createMockStream([
-      {
-        type: 'message_start',
-        message: {
-          id: 'msg_123',
-          type: 'message',
-          role: 'assistant',
-          content: [],
-          model: 'claude-opus-4-1',
-          usage: {
-            input_tokens: 100,
-            output_tokens: 0,
-          },
-        },
-      },
-      {
-        type: 'content_block_start',
-        index: 0,
-        content_block: { type: 'text', text: '' },
-      },
-      {
-        type: 'content_block_delta',
-        index: 0,
-        delta: { type: 'text_delta', text: 'Hello world' },
-      },
-      {
-        type: 'message_delta',
-        delta: { stop_reason: 'end_turn' },
-        usage: {
-          input_tokens: 100,
-          output_tokens: 50,
+    expect(usage).toEqual({
+      promptTokens: 100,
+      completionTokens: 50,
+      totalTokens: 150,
+      providerUsageDetails: {
+        serverToolUse: {
+          webSearchRequests: 3,
+          webFetchRequests: 2,
         },
       },
-      {
-        type: 'message_stop',
-      },
-    ])
-
-    mocks.betaMessagesCreate.mockResolvedValueOnce(mockStream)
-
-    const chunks: Array<AdapterYieldChunk> = []
-    for await (const chunk of chat({
-      adapter: createAdapter(),
-      messages: [{ role: 'user', content: 'Hello' }],
-    })) {
-      chunks.push(chunk)
-    }
-
-    const doneChunk = chunks.find((c) => c.type === 'RUN_FINISHED')
-    expect(doneChunk).toBeDefined()
-    // No cache tokens and no server tool use: the detail objects must be
-    // omitted entirely rather than emitted as empty `{}` (matches every other
-    // adapter's guarded behavior).
-    expect(tokenUsageOf(doneChunk)?.promptTokensDetails).toBeUndefined()
-    expect(tokenUsageOf(doneChunk)?.providerUsageDetails).toBeUndefined()
+    })
   })
 
   it('defaults missing output_tokens to 0 instead of NaN', async () => {
-    const mockStream = createMockStream([
-      {
-        type: 'message_start',
-        message: {
-          id: 'msg_123',
-          type: 'message',
-          role: 'assistant',
-          content: [],
-          model: 'claude-opus-4-1',
-          usage: {
-            input_tokens: 100,
-            output_tokens: 0,
-          },
-        },
-      },
-      {
-        type: 'content_block_start',
-        index: 0,
-        content_block: { type: 'text', text: '' },
-      },
-      {
-        type: 'content_block_delta',
-        index: 0,
-        delta: { type: 'text_delta', text: 'Hello world' },
-      },
-      {
-        type: 'message_delta',
-        delta: { stop_reason: 'end_turn' },
-        // output_tokens intentionally omitted to exercise the `?? 0` guard.
-        usage: {
-          input_tokens: 100,
-        },
-      },
-      {
-        type: 'message_stop',
-      },
-    ])
+    // output_tokens intentionally omitted to exercise the `|| 0` guard.
+    const usage = await runFinishedUsage({ input_tokens: 100 })
 
-    mocks.betaMessagesCreate.mockResolvedValueOnce(mockStream)
-
-    const chunks: Array<AdapterYieldChunk> = []
-    for await (const chunk of chat({
-      adapter: createAdapter(),
-      messages: [{ role: 'user', content: 'Hello' }],
-    })) {
-      chunks.push(chunk)
-    }
-
-    const doneChunk = chunks.find((c) => c.type === 'RUN_FINISHED')
-    expect(doneChunk).toBeDefined()
-    expect(tokenUsageOf(doneChunk)?.completionTokens).toBe(0)
-    expect(tokenUsageOf(doneChunk)?.totalTokens).toBe(100)
-    expect(Number.isNaN(tokenUsageOf(doneChunk)?.totalTokens)).toBe(false)
+    expect(usage).toEqual({
+      promptTokens: 100,
+      completionTokens: 0,
+      totalTokens: 100,
+    })
   })
 })

From 52ea90bcdf6e202fee355f035acabe4d8eb8b03d Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 10:30:16 +0200
Subject: [PATCH 151/286] fix(ai-openrouter): report cache-read tokens on the
 Responses adapter

The Responses adapter now maps inputTokensDetails.cachedTokens to promptTokensDetails.cachedTokens at all three usage sites, and the raw fallback path keeps the field.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .../src/adapters/responses-text.ts            |  66 +--
 .../tests/usage-extraction.test.ts            | 443 +++++++-----------
 2 files changed, 209 insertions(+), 300 deletions(-)

diff --git a/packages/ai-openrouter/src/adapters/responses-text.ts b/packages/ai-openrouter/src/adapters/responses-text.ts
index 10d5d8fd39..b0e779adeb 100644
--- a/packages/ai-openrouter/src/adapters/responses-text.ts
+++ b/packages/ai-openrouter/src/adapters/responses-text.ts
@@ -1,6 +1,7 @@
 import { OpenRouter } from '@openrouter/sdk'
 import {
   EventType,
+  buildBaseUsage,
   isFileSource,
   normalizeSystemPrompts,
   unsupportedFileSourceError,
@@ -33,6 +34,7 @@ import type {
   ReasoningEffort,
   ResponsesRequest,
   StreamEvents,
+  Usage,
 } from '@openrouter/sdk/models'
 import type {
   StructuredOutputOptions,
@@ -285,10 +287,8 @@ export class OpenRouterResponsesTextAdapter<
       // OpenRouter override: pass nulls through unchanged.
       const transformed = this.transformStructuredOutput(parsed)
 
-      // Responses API reports usage as inputTokens/outputTokens (not the
-      // chat-completions promptTokens/completionTokens shape). Map to
-      // TokenUsage and attach OpenRouter cost when present — same contract
-      // as structuredOutputStream / processStreamChunks. Cost-only usage
+      // Same TokenUsage contract as structuredOutputStream /
+      // processStreamChunks (see buildResponsesUsage). Cost-only usage
       // (finite cost, no token fields) still forwards with zeroed tokens.
       const usage = response.usage
       const cost = extractUsageCost(usage)
@@ -301,14 +301,7 @@ export class OpenRouterResponsesTextAdapter<
       return {
         data: transformed,
         rawText,
-        ...(hasUsage && {
-          usage: {
-            promptTokens: usage.inputTokens ?? 0,
-            completionTokens: usage.outputTokens ?? 0,
-            totalTokens: usage.totalTokens ?? 0,
-            ...cost,
-          },
-        }),
+        ...(hasUsage && { usage: buildResponsesUsage(usage) }),
       }
     } catch (error: unknown) {
       chatOptions.logger.errors(`${this.name}.structuredOutput fatal`, {
@@ -358,13 +351,7 @@ export class OpenRouterResponsesTextAdapter<
     let stepId: string | undefined
     let hasClosedReasoning = false
     let model: string = chatOptions.model
-    let usage:
-      | {
-          inputTokens?: number
-          outputTokens?: number
-          totalTokens?: number
-        }
-      | undefined
+    let usage: Usage | undefined
     let responseCompleted = false
 
     const closeReasoning = function* (this: {
@@ -695,14 +682,7 @@ export class OpenRouterResponsesTextAdapter<
         model,
         timestamp: Date.now(),
         finishReason: 'stop',
-        ...(usage && {
-          usage: {
-            promptTokens: usage.inputTokens ?? 0,
-            completionTokens: usage.outputTokens ?? 0,
-            totalTokens: usage.totalTokens ?? 0,
-            ...extractUsageCost(usage),
-          },
-        }),
+        ...(usage && { usage: buildResponsesUsage(usage) }),
       }
     } catch (error: unknown) {
       if (!aguiState.hasEmittedRunStarted) {
@@ -1605,12 +1585,7 @@ export class OpenRouterResponsesTextAdapter<
             threadId: aguiState.threadId,
             model: model || options.model,
             timestamp: Date.now(),
-            usage: {
-              promptTokens: responseObj.usage?.inputTokens || 0,
-              completionTokens: responseObj.usage?.outputTokens || 0,
-              totalTokens: responseObj.usage?.totalTokens || 0,
-              ...extractUsageCost(responseObj.usage),
-            },
+            usage: buildResponsesUsage(responseObj.usage ?? {}),
             finishReason,
           }
           runFinishedEmitted = true
@@ -2118,11 +2093,19 @@ function camelCaseResponseShape(
   }
   if (src.usage && typeof src.usage === 'object') {
     const u = src.usage as Record<string, unknown>
+    const inputDetails = u.input_tokens_details
+    const hasRawCachedTokens =
+      typeof inputDetails === 'object' &&
+      inputDetails !== null &&
+      'cached_tokens' in inputDetails
     out.usage = {
       ...u,
       ...('input_tokens' in u && { inputTokens: u.input_tokens }),
       ...('output_tokens' in u && { outputTokens: u.output_tokens }),
       ...('total_tokens' in u && { totalTokens: u.total_tokens }),
+      ...(hasRawCachedTokens && {
+        inputTokensDetails: { cachedTokens: inputDetails.cached_tokens },
+      }),
     }
   }
   if (Array.isArray(src.output)) {
@@ -2144,6 +2127,23 @@ function camelCaseOutputItem(
   return out
 }
 
+/**
+ * Map Responses API usage to TokenUsage, plus OpenRouter cost when present.
+ * `inputTokens` already includes cached tokens, so promptTokens stays the
+ * full input count. The fields are optional because the raw (UNKNOWN) stream
+ * fallback can leave them out.
+ */
+function buildResponsesUsage(usage: Partial<Usage>) {
+  const result = buildBaseUsage({
+    promptTokens: usage.inputTokens ?? 0,
+    completionTokens: usage.outputTokens ?? 0,
+    totalTokens: usage.totalTokens ?? 0,
+  })
+  const cachedTokens = usage.inputTokensDetails?.cachedTokens ?? 0
+  if (cachedTokens > 0) result.promptTokensDetails = { cachedTokens }
+  return { ...result, ...extractUsageCost(usage) }
+}
+
 /** Normalize an `error.code` to the string slot our RUN_ERROR event reads. */
 function normalizeCode(code: unknown): string | undefined {
   if (typeof code === 'string') return code
diff --git a/packages/ai-openrouter/tests/usage-extraction.test.ts b/packages/ai-openrouter/tests/usage-extraction.test.ts
index dad3cd0969..c6cf6f7453 100644
--- a/packages/ai-openrouter/tests/usage-extraction.test.ts
+++ b/packages/ai-openrouter/tests/usage-extraction.test.ts
@@ -1,26 +1,10 @@
-import type { TokenUsage } from '@tanstack/ai'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { chat } from '@tanstack/ai'
+import { EventType, chat } from '@tanstack/ai'
 import { createOpenRouterText } from '../src/adapters/text'
+import { createOpenRouterResponsesText } from '../src/adapters/responses-text'
 import type { Mock } from 'vitest'
 import type { AdapterYieldChunk } from '@tanstack/ai'
-
-/** `chat()` restores a TokenUsage object on RUN_FINISHED. */
-function tokenUsageOf(chunk: unknown): TokenUsage | undefined {
-  if (typeof chunk !== 'object' || chunk === null || !('usage' in chunk)) {
-    return undefined
-  }
-  const usage = chunk.usage
-  if (
-    typeof usage !== 'object' ||
-    usage === null ||
-    Array.isArray(usage) ||
-    !('promptTokens' in usage)
-  ) {
-    return undefined
-  }
-  return usage as TokenUsage
-}
+import type { ChatUsage, Usage } from '@openrouter/sdk/models'
 
 let mockSend: Mock
 
@@ -32,17 +16,18 @@ let mockSend: Mock
 vi.mock('@openrouter/sdk', () => {
   function OpenRouter(this: {
     chat: { send: (...args: Array<unknown>) => unknown }
+    beta: { responses: { send: (...args: Array<unknown>) => unknown } }
   }) {
     this.chat = {
       send: (...args: Array<unknown>) => mockSend(...args),
     }
+    this.beta = {
+      responses: { send: (...args: Array<unknown>) => mockSend(...args) },
+    }
   }
   return { OpenRouter }
 })
 
-const createAdapter = () =>
-  createOpenRouterText('openai/gpt-4o-mini', 'test-key')
-
 function createAsyncIterable<T>(chunks: Array<T>): AsyncIterable<T> {
   return {
     [Symbol.asyncIterator]() {
@@ -60,6 +45,69 @@ function createAsyncIterable<T>(chunks: Array<T>): AsyncIterable<T> {
   }
 }
 
+async function collect(stream: AsyncIterable<AdapterYieldChunk>) {
+  const chunks: Array<AdapterYieldChunk> = []
+  for await (const chunk of stream) {
+    chunks.push(chunk)
+  }
+  return chunks
+}
+
+/** Usage on RUN_FINISHED. `chat()` restores it as a TokenUsage object. */
+function finishedUsage(chunks: Array<AdapterYieldChunk>) {
+  for (const chunk of chunks) {
+    if (chunk.type !== EventType.RUN_FINISHED) continue
+    if (Array.isArray(chunk.usage)) {
+      throw new Error('expected TokenUsage on RUN_FINISHED, got a usage array')
+    }
+    return chunk.usage
+  }
+  throw new Error('stream had no RUN_FINISHED chunk')
+}
+
+/** Chat Completions stream: one text delta, then a stop chunk with `usage`. */
+function runChatCompletions(usage?: ChatUsage) {
+  const streamChunks = [
+    {
+      id: 'chatcmpl-123',
+      model: 'openai/gpt-4o-mini',
+      choices: [{ delta: { content: 'Hello world' }, finishReason: null }],
+    },
+    {
+      id: 'chatcmpl-123',
+      model: 'openai/gpt-4o-mini',
+      choices: [{ delta: {}, finishReason: 'stop' }],
+      ...(usage && { usage }),
+    },
+  ]
+  mockSend.mockResolvedValue(createAsyncIterable(streamChunks))
+  return collect(
+    chat({
+      adapter: createOpenRouterText('openai/gpt-4o-mini', 'test-key'),
+      messages: [{ role: 'user', content: 'Hello' }],
+    }),
+  )
+}
+
+/** Responses stream that ends with one `response.completed` event. */
+function runResponses<T>(completedEvent: T) {
+  mockSend.mockResolvedValue(createAsyncIterable([completedEvent]))
+  return collect(
+    chat({
+      adapter: createOpenRouterResponsesText('openai/gpt-4o-mini', 'test-key'),
+      messages: [{ role: 'user', content: 'Hello' }],
+    }),
+  )
+}
+
+function responseCompleted(usage: Partial<Usage>) {
+  return {
+    type: 'response.completed',
+    sequenceNumber: 1,
+    response: { model: 'openai/gpt-4o-mini', output: [], usage },
+  }
+}
+
 describe('OpenRouter usage extraction', () => {
   beforeEach(() => {
     vi.clearAllMocks()
@@ -67,277 +115,138 @@ describe('OpenRouter usage extraction', () => {
   })
 
   it('extracts basic token usage from stream', async () => {
-    const streamChunks = [
-      {
-        id: 'chatcmpl-123',
-        model: 'openai/gpt-4o-mini',
-        choices: [
-          {
-            delta: { content: 'Hello world' },
-            finishReason: null,
-          },
-        ],
-      },
-      {
-        id: 'chatcmpl-123',
-        model: 'openai/gpt-4o-mini',
-        choices: [
-          {
-            delta: {},
-            finishReason: 'stop',
-          },
-        ],
-        usage: {
-          promptTokens: 100,
-          completionTokens: 50,
-          totalTokens: 150,
-        },
-      },
-    ]
-
-    mockSend.mockImplementation((params) => {
-      if (params.chatRequest?.stream) {
-        return Promise.resolve(createAsyncIterable(streamChunks))
-      }
-      return Promise.resolve({})
+    const chunks = await runChatCompletions({
+      promptTokens: 100,
+      completionTokens: 50,
+      totalTokens: 150,
     })
 
-    const chunks: Array<AdapterYieldChunk> = []
-    for await (const chunk of chat({
-      adapter: createAdapter(),
-      messages: [{ role: 'user', content: 'Hello' }],
-    })) {
-      chunks.push(chunk)
-    }
-
-    const doneChunk = chunks.find((c) => c.type === 'RUN_FINISHED')
-    expect(doneChunk).toBeDefined()
-    if (doneChunk?.type === 'RUN_FINISHED') {
-      expect(doneChunk.usage).toMatchObject({
-        promptTokens: 100,
-        completionTokens: 50,
-        totalTokens: 150,
-      })
-    }
+    expect(finishedUsage(chunks)).toMatchObject({
+      promptTokens: 100,
+      completionTokens: 50,
+      totalTokens: 150,
+    })
   })
 
   it('extracts prompt tokens details', async () => {
-    const streamChunks = [
-      {
-        id: 'chatcmpl-123',
-        model: 'openai/gpt-4o-mini',
-        choices: [
-          {
-            delta: { content: 'Hello world' },
-            finishReason: null,
-          },
-        ],
-      },
-      {
-        id: 'chatcmpl-123',
-        model: 'openai/gpt-4o-mini',
-        choices: [
-          {
-            delta: {},
-            finishReason: 'stop',
-          },
-        ],
-        usage: {
-          promptTokens: 100,
-          completionTokens: 50,
-          totalTokens: 150,
-          promptTokensDetails: {
-            cachedTokens: 25,
-          },
-        },
-      },
-    ]
+    const chunks = await runChatCompletions({
+      promptTokens: 100,
+      completionTokens: 50,
+      totalTokens: 150,
+      promptTokensDetails: { cachedTokens: 25 },
+    })
 
-    mockSend.mockImplementation((params) => {
-      if (params.chatRequest?.stream) {
-        return Promise.resolve(createAsyncIterable(streamChunks))
-      }
-      return Promise.resolve({})
+    expect(finishedUsage(chunks)?.promptTokensDetails).toEqual({
+      cachedTokens: 25,
     })
+  })
 
-    const chunks: Array<AdapterYieldChunk> = []
-    for await (const chunk of chat({
-      adapter: createAdapter(),
-      messages: [{ role: 'user', content: 'Hello' }],
-    })) {
-      chunks.push(chunk)
-    }
+  it('extracts completion tokens details with reasoning tokens', async () => {
+    const chunks = await runChatCompletions({
+      promptTokens: 100,
+      completionTokens: 50,
+      totalTokens: 150,
+      completionTokensDetails: { reasoningTokens: 30 },
+    })
 
-    const doneChunk = chunks.find((c) => c.type === 'RUN_FINISHED')
-    expect(doneChunk).toBeDefined()
-    if (doneChunk?.type === 'RUN_FINISHED') {
-      expect(tokenUsageOf(doneChunk)?.promptTokensDetails).toEqual({
-        cachedTokens: 25,
-      })
-    }
+    expect(finishedUsage(chunks)?.completionTokensDetails).toEqual({
+      reasoningTokens: 30,
+    })
   })
 
-  it('extracts completion tokens details with reasoning tokens', async () => {
-    const streamChunks = [
-      {
-        id: 'chatcmpl-123',
-        model: 'openai/gpt-4o-mini',
-        choices: [
-          {
-            delta: { content: 'Hello world' },
-            finishReason: null,
-          },
-        ],
-      },
-      {
-        id: 'chatcmpl-123',
-        model: 'openai/gpt-4o-mini',
-        choices: [
-          {
-            delta: {},
-            finishReason: 'stop',
-          },
-        ],
-        usage: {
-          promptTokens: 100,
-          completionTokens: 50,
-          totalTokens: 150,
-          completionTokensDetails: {
-            reasoningTokens: 30,
-          },
-        },
+  it('extracts completion tokens details with prediction tokens', async () => {
+    const chunks = await runChatCompletions({
+      promptTokens: 100,
+      completionTokens: 50,
+      totalTokens: 150,
+      completionTokensDetails: {
+        acceptedPredictionTokens: 20,
+        rejectedPredictionTokens: 5,
       },
-    ]
+    })
 
-    mockSend.mockImplementation((params) => {
-      if (params.chatRequest?.stream) {
-        return Promise.resolve(createAsyncIterable(streamChunks))
-      }
-      return Promise.resolve({})
+    // Prediction tokens are OpenRouter-specific, so they go in providerUsageDetails
+    expect(finishedUsage(chunks)?.providerUsageDetails).toEqual({
+      acceptedPredictionTokens: 20,
+      rejectedPredictionTokens: 5,
     })
+  })
 
-    const chunks: Array<AdapterYieldChunk> = []
-    for await (const chunk of chat({
-      adapter: createAdapter(),
-      messages: [{ role: 'user', content: 'Hello' }],
-    })) {
-      chunks.push(chunk)
-    }
+  it('leaves usage undefined when the provider sends no usage data', async () => {
+    // AG-UI RUN_FINISHED is always emitted on successful stream completion,
+    // but its usage field should be undefined when the provider doesn't
+    // include usage data.
+    const chunks = await runChatCompletions()
 
-    const doneChunk = chunks.find((c) => c.type === 'RUN_FINISHED')
-    expect(doneChunk).toBeDefined()
-    if (doneChunk?.type === 'RUN_FINISHED') {
-      expect(tokenUsageOf(doneChunk)?.completionTokensDetails).toEqual({
-        reasoningTokens: 30,
-      })
-    }
+    expect(finishedUsage(chunks)).toBeUndefined()
   })
+})
 
-  it('extracts completion tokens details with prediction tokens', async () => {
-    const streamChunks = [
-      {
-        id: 'chatcmpl-123',
-        model: 'openai/gpt-4o-mini',
-        choices: [
-          {
-            delta: { content: 'Hello world' },
-            finishReason: null,
-          },
-        ],
-      },
-      {
-        id: 'chatcmpl-123',
-        model: 'openai/gpt-4o-mini',
-        choices: [
-          {
-            delta: {},
-            finishReason: 'stop',
-          },
-        ],
-        usage: {
-          promptTokens: 100,
-          completionTokens: 50,
-          totalTokens: 150,
-          completionTokensDetails: {
-            acceptedPredictionTokens: 20,
-            rejectedPredictionTokens: 5,
-          },
-        },
-      },
-    ]
+describe('OpenRouter Responses usage extraction', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockSend = vi.fn()
+  })
 
-    mockSend.mockImplementation((params) => {
-      if (params.chatRequest?.stream) {
-        return Promise.resolve(createAsyncIterable(streamChunks))
-      }
-      return Promise.resolve({})
+  it('maps cached input tokens to promptTokensDetails.cachedTokens', async () => {
+    const chunks = await runResponses(
+      responseCompleted({
+        inputTokens: 100,
+        outputTokens: 50,
+        totalTokens: 150,
+        inputTokensDetails: { cachedTokens: 40 },
+      }),
+    )
+
+    // promptTokens stays the full input count; cached tokens are a part of it.
+    expect(finishedUsage(chunks)).toEqual({
+      promptTokens: 100,
+      completionTokens: 50,
+      totalTokens: 150,
+      promptTokensDetails: { cachedTokens: 40 },
     })
+  })
 
-    const chunks: Array<AdapterYieldChunk> = []
-    for await (const chunk of chat({
-      adapter: createAdapter(),
-      messages: [{ role: 'user', content: 'Hello' }],
-    })) {
-      chunks.push(chunk)
-    }
-
-    const doneChunk = chunks.find((c) => c.type === 'RUN_FINISHED')
-    expect(doneChunk).toBeDefined()
-    // Prediction tokens are OpenRouter-specific, so they go in providerUsageDetails
-    if (doneChunk?.type === 'RUN_FINISHED') {
-      expect(tokenUsageOf(doneChunk)?.providerUsageDetails).toEqual({
-        acceptedPredictionTokens: 20,
-        rejectedPredictionTokens: 5,
-      })
-    }
+  it('omits promptTokensDetails when no input tokens were cached', async () => {
+    const chunks = await runResponses(
+      responseCompleted({
+        inputTokens: 100,
+        outputTokens: 50,
+        totalTokens: 150,
+        inputTokensDetails: { cachedTokens: 0 },
+      }),
+    )
+
+    expect(finishedUsage(chunks)).toEqual({
+      promptTokens: 100,
+      completionTokens: 50,
+      totalTokens: 150,
+    })
   })
 
-  it('handles response with no usage data - no done chunk emitted', async () => {
-    const streamChunks = [
-      {
-        id: 'chatcmpl-123',
-        model: 'openai/gpt-4o-mini',
-        choices: [
-          {
-            delta: { content: 'Hello world' },
-            finishReason: null,
+  it('maps snake_case cached_tokens from the raw stream fallback', async () => {
+    // The SDK falls back to `{ isUnknown, raw }` with the snake_case wire
+    // payload when an event fails its strict schema.
+    const chunks = await runResponses({
+      isUnknown: true,
+      raw: {
+        type: 'response.completed',
+        sequence_number: 1,
+        response: {
+          model: 'openai/gpt-4o-mini',
+          output: [],
+          usage: {
+            input_tokens: 100,
+            output_tokens: 50,
+            total_tokens: 150,
+            input_tokens_details: { cached_tokens: 40 },
           },
-        ],
-      },
-      {
-        id: 'chatcmpl-123',
-        model: 'openai/gpt-4o-mini',
-        choices: [
-          {
-            delta: {},
-            finishReason: 'stop',
-          },
-        ],
-        // No usage field
+        },
       },
-    ]
-
-    mockSend.mockImplementation((params) => {
-      if (params.chatRequest?.stream) {
-        return Promise.resolve(createAsyncIterable(streamChunks))
-      }
-      return Promise.resolve({})
     })
 
-    const chunks: Array<AdapterYieldChunk> = []
-    for await (const chunk of chat({
-      adapter: createAdapter(),
-      messages: [{ role: 'user', content: 'Hello' }],
-    })) {
-      chunks.push(chunk)
-    }
-
-    // AG-UI RUN_FINISHED is always emitted on successful stream completion,
-    // but its usage field should be undefined when the provider doesn't
-    // include usage data.
-    const doneChunk = chunks.find((c) => c.type === 'RUN_FINISHED')
-    if (doneChunk?.type === 'RUN_FINISHED') {
-      expect(doneChunk.usage).toBeUndefined()
-    }
+    expect(finishedUsage(chunks)?.promptTokensDetails).toEqual({
+      cachedTokens: 40,
+    })
   })
 })

From 24f899ca0c2bab128731f5144c62f7c57f42b9fb Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 10:33:29 +0200
Subject: [PATCH 152/286] feat(ai): add the promptCache option to chat()

chat() now asks every adapter for automatic prompt caching, 'short' by default. promptCache takes 'none' | 'short' | 'long', or { retention, key }. The key is the option key, else the threadId or conversationId that the caller gives. A made-up threadId is never the key. Adapters get the resolved value as TextOptions.promptCache. Subagents inherit the retention through the binding and ctx.forward.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .../ai/src/activities/chat/agents/bound.ts    |  10 +-
 .../ai/src/activities/chat/agents/spawn.ts    |   1 +
 packages/ai/src/activities/chat/index.ts      |  53 +++++-
 packages/ai/src/types.ts                      |  25 +++
 packages/ai/tests/prompt-cache.test.ts        | 157 ++++++++++++++++++
 5 files changed, 242 insertions(+), 4 deletions(-)
 create mode 100644 packages/ai/tests/prompt-cache.test.ts

diff --git a/packages/ai/src/activities/chat/agents/bound.ts b/packages/ai/src/activities/chat/agents/bound.ts
index 8566325366..c73117bc3e 100644
--- a/packages/ai/src/activities/chat/agents/bound.ts
+++ b/packages/ai/src/activities/chat/agents/bound.ts
@@ -13,7 +13,7 @@ import { rerank } from '../../rerank/index'
 import { decide } from '../../evaluate/index'
 import type { GenerationMiddleware } from '../../middleware/types'
 import type { AnyChatMiddleware } from '../middleware/types'
-import type { RunAgentResumeItem } from '../../../types'
+import type { PromptCacheRetention, RunAgentResumeItem } from '../../../types'
 import type { SubagentRunInput } from './define-agent'
 import type { SubagentBudget } from './limits'
 import type { ProviderKeys } from '../../../byok/keyed'
@@ -30,6 +30,8 @@ export interface SubagentForward {
   resume?: Array<RunAgentResumeItem>
   /** Aborts when the parent run or the subagent group stops. */
   abortController: AbortController
+  /** The prompt cache retention of the parent call, when it has one. */
+  promptCache?: PromptCacheRetention
 }
 
 /**
@@ -59,6 +61,11 @@ export interface SubagentBinding {
    * them, `ctx.keys` reads each provider's `env` names.
    */
   keys?: ProviderKeys
+  /**
+   * The prompt cache retention of the parent call. A child's `ctx.chat()`
+   * uses it when the call gives no `promptCache`.
+   */
+  promptCache?: PromptCacheRetention
 }
 
 /**
@@ -129,6 +136,7 @@ export function createBoundActivities(
         subagentName: agentName,
         parentSubagentRunId: input.parentSubagentRunId,
         ...(input.resume ? { resume: input.resume } : {}),
+        ...(binding?.promptCache ? { promptCache: binding.promptCache } : {}),
         abortController,
         ...options,
         // Nested children get the host middleware before their own, share
diff --git a/packages/ai/src/activities/chat/agents/spawn.ts b/packages/ai/src/activities/chat/agents/spawn.ts
index b7cb092425..be48f1bca4 100644
--- a/packages/ai/src/activities/chat/agents/spawn.ts
+++ b/packages/ai/src/activities/chat/agents/spawn.ts
@@ -499,6 +499,7 @@ function runContext(
       subagentRunId: input.subagentRunId,
       ...(input.resume ? { resume: input.resume } : {}),
       abortController,
+      ...(binding?.promptCache ? { promptCache: binding.promptCache } : {}),
     },
     keys: binding?.keys ?? envProviderKeys,
     ...createBoundActivities(agentName, input, abortController, binding),
diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index 130186740f..c2d2d91afa 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -136,7 +136,9 @@ import type {
   JSONSchema,
   LazyToolsConfig,
   ModelMessage,
+  PromptCacheOptions,
   ProviderTool,
+  ResolvedPromptCache,
   RunFinishedEvent,
   SchemaInput,
   StreamChunk,
@@ -549,6 +551,17 @@ export interface TextActivityOptions<
   conversationId?: TextOptions['conversationId']
   /** Thread/conversation ID for AG-UI protocol. Auto-generated if not provided. */
   threadId?: TextOptions['threadId']
+  /**
+   * Automatic prompt caching. Default `'short'`. `'none'` turns it off.
+   * The key defaults to the `threadId` or `conversationId` that you give.
+   *
+   * @example
+   * ```ts
+   * chat({ adapter, messages, threadId, promptCache: 'long' })
+   * chat({ adapter, messages, promptCache: { retention: 'long', key: 'k-1' } })
+   * ```
+   */
+  promptCache?: PromptCacheOptions
   /** Run ID override for AG-UI protocol. Auto-generated by adapter if not provided. */
   runId?: TextOptions['runId']
   /** Parent run ID for AG-UI protocol nested run correlation. */
@@ -1636,6 +1649,7 @@ class TextEngine<
       systemPrompts: this.systemPrompts,
       logger: this.logger,
       threadId: this.threadId,
+      promptCache: this.params.promptCache,
       runId: this.runIdOverride,
       parentRunId: this.parentRunIdOverride,
       // Expose provided capabilities (e.g. sandbox) to harness adapters.
@@ -3926,6 +3940,7 @@ class TextEngine<
         systemPrompts: postOnConfig.systemPrompts,
         logger: this.logger,
         threadId: this.threadId,
+        promptCache: this.params.promptCache,
         runId: this.runIdOverride,
         parentRunId: this.parentRunIdOverride,
         ...(this.effectiveRequest ? { request: this.effectiveRequest } : {}),
@@ -5231,9 +5246,32 @@ type RuntimeTextActivityOptions<
   TStream extends boolean,
 > = Omit<
   TextActivityOptions<TAdapter, TSchema, TStream, any, any>,
-  'middleware'
+  'middleware' | 'promptCache'
 > & {
   middleware?: Array<AnyChatMiddleware>
+  promptCache: ResolvedPromptCache
+}
+
+/**
+ * Resolve the `promptCache` option once, before chat() makes up any ids. The
+ * key is the option key, else the caller's threadId or conversationId. A
+ * made-up threadId is never the key: a random key splits OpenAI cache routing.
+ */
+function resolvePromptCache(options: {
+  promptCache?: PromptCacheOptions
+  threadId?: string
+  conversationId?: string
+}) {
+  const option: Exclude<PromptCacheOptions, string> | undefined =
+    typeof options.promptCache === 'string'
+      ? { retention: options.promptCache }
+      : options.promptCache
+  // `||` on purpose: an empty string is no key.
+  const key = option?.key || options.threadId || options.conversationId
+  return {
+    retention: option?.retention ?? 'short',
+    ...(key ? { key } : {}),
+  }
 }
 
 function readRuntimeMiddleware(
@@ -5279,6 +5317,7 @@ function toRuntimeTextActivityOptions<
   return {
     ...rest,
     ...overrides,
+    promptCache: resolvePromptCache(rest),
     ...(middleware === undefined
       ? {}
       : { middleware: readRuntimeMiddleware(middleware) }),
@@ -5408,10 +5447,18 @@ async function* streamTextChunks(
   options: RuntimeTextActivityOptions<AnyTextAdapter, undefined, boolean>,
   engineRef: DeliveryEngineRef,
 ): AsyncIterable<StreamChunk> {
-  const bag = options.subagents
+  // Children inherit the retention of this call. Their key is their own
+  // threadId.
+  const bag = options.subagents && {
+    ...options.subagents,
+    binding: {
+      ...options.subagents.binding,
+      promptCache: options.promptCache.retention,
+    },
+  }
   const agents = bag?.agents ?? []
   if (bag && agents.length > 0 && bag.router) {
-    yield* runRoutedSubagents(options, engineRef)
+    yield* runRoutedSubagents({ ...options, subagents: bag }, engineRef)
     return
   }
   if (bag && agents.length > 0) {
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index 222f0538f2..05404d12ca 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -1082,6 +1082,26 @@ export interface AgentLoopState {
  */
 export type AgentLoopStrategy = (state: AgentLoopState) => boolean
 
+/**
+ * How long the provider keeps the cached start of a request.
+ * `'none'` turns automatic prompt caching off.
+ */
+export type PromptCacheRetention = 'none' | 'short' | 'long'
+
+/**
+ * The `promptCache` option of `chat()`: a retention, or an object with a
+ * retention and a cache key.
+ */
+export type PromptCacheOptions =
+  | PromptCacheRetention
+  | { retention?: PromptCacheRetention; key?: string }
+
+/** What chat() gives the adapter. */
+export interface ResolvedPromptCache {
+  retention: PromptCacheRetention
+  key?: string
+}
+
 /**
  * Options passed into the SDK and further piped to the AI provider.
  */
@@ -1211,6 +1231,11 @@ export interface TextOptions<
    * When provided, this will be used in RunStartedEvent and RunFinishedEvent.
    */
   threadId?: string
+  /**
+   * Automatic prompt caching for this request. `chat()` sets it. When it is
+   * absent, the adapter adds no automatic cache fields.
+   */
+  promptCache?: ResolvedPromptCache
   /**
    * Run ID for AG-UI protocol run correlation.
    * When provided, this will be used in RunStartedEvent and RunFinishedEvent.
diff --git a/packages/ai/tests/prompt-cache.test.ts b/packages/ai/tests/prompt-cache.test.ts
new file mode 100644
index 0000000000..d55e59a772
--- /dev/null
+++ b/packages/ai/tests/prompt-cache.test.ts
@@ -0,0 +1,157 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { chat } from '../src'
+import { defineAgent } from '../src/activities/chat/agents/define-agent'
+import { createMockAdapter, ev } from './test-utils'
+import type { PromptCacheOptions, ResolvedPromptCache } from '../src'
+
+const done = [ev.runStarted(), ev.runFinished('stop')]
+
+interface CallerIds {
+  promptCache?: PromptCacheOptions
+  threadId?: string
+  conversationId?: string
+}
+
+/** Run one chat() call and give back the first adapter call. */
+async function firstAdapterCall(ids: CallerIds) {
+  const { adapter, calls } = createMockAdapter({ iterations: [done] })
+  await chat({
+    adapter,
+    messages: [{ role: 'user', content: 'hi' }],
+    stream: false,
+    ...ids,
+  })
+  return calls[0]
+}
+
+describe('chat({ promptCache })', () => {
+  it('sends short and no key when the caller gives no threadId', async () => {
+    const call = await firstAdapterCall({})
+    // chat() made up a threadId. It is not the key.
+    expect(call?.threadId).toMatch(/.+/)
+    expect(call?.promptCache).toStrictEqual({ retention: 'short' })
+  })
+
+  it.each<[string, CallerIds, ResolvedPromptCache]>([
+    [
+      'a threadId is the key',
+      { threadId: 't1' },
+      { retention: 'short', key: 't1' },
+    ],
+    [
+      'a conversationId alone is the key',
+      { conversationId: 'c1' },
+      { retention: 'short', key: 'c1' },
+    ],
+    ['an empty threadId is no key', { threadId: '' }, { retention: 'short' }],
+    [
+      "'none' keeps the key",
+      { promptCache: 'none', threadId: 't1' },
+      { retention: 'none', key: 't1' },
+    ],
+    ["'long' with no threadId", { promptCache: 'long' }, { retention: 'long' }],
+    [
+      'an object key wins over the threadId',
+      { threadId: 't1', promptCache: { retention: 'long', key: 'k-1' } },
+      { retention: 'long', key: 'k-1' },
+    ],
+    [
+      'an object with only a key is short',
+      { promptCache: { key: 'k-1' } },
+      { retention: 'short', key: 'k-1' },
+    ],
+  ])('%s', async (_name, ids, expected) => {
+    const call = await firstAdapterCall(ids)
+    expect(call?.promptCache).toStrictEqual(expected)
+  })
+
+  it('reaches structuredOutput when there is an outputSchema and no tools', async () => {
+    let seen: ResolvedPromptCache | undefined
+    const { adapter } = createMockAdapter({
+      structuredOutput: async (options) => {
+        seen = options.chatOptions.promptCache
+        return { data: { name: 'Ada' }, rawText: '{"name":"Ada"}' }
+      },
+    })
+    const result = await chat({
+      adapter,
+      messages: [{ role: 'user', content: 'Who?' }],
+      threadId: 't1',
+      promptCache: 'long',
+      outputSchema: z.object({ name: z.string() }),
+    })
+    expect(result).toEqual({ name: 'Ada' })
+    expect(seen).toStrictEqual({ retention: 'long', key: 't1' })
+  })
+})
+
+describe('chat({ promptCache }) with subagents', () => {
+  it("gives a ctx.chat() child the parent's retention and the child threadId as key", async () => {
+    const child = createMockAdapter({ iterations: [done] })
+    const helper = defineAgent({
+      name: 'helper',
+      description: 'Uses ctx.chat',
+      run: (ctx) => ctx.chat({ adapter: child.adapter }),
+    })
+    await chat({
+      adapter: createMockAdapter({ iterations: [] }).adapter,
+      messages: [{ role: 'user', content: 'Go' }],
+      threadId: 't1',
+      promptCache: 'none',
+      stream: false,
+      subagents: { agents: [helper], router: () => 'helper' },
+    })
+    expect(child.calls[0]?.promptCache).toStrictEqual({
+      retention: 'none',
+      key: 't1:helper',
+    })
+  })
+
+  it("gives a plain chat({ ...ctx.forward }) child the parent's retention", async () => {
+    const child = createMockAdapter({ iterations: [done] })
+    const helper = defineAgent({
+      name: 'helper',
+      description: 'Uses plain chat()',
+      run: (ctx) =>
+        chat({
+          adapter: child.adapter,
+          messages: ctx.messages,
+          stream: false,
+          ...ctx.forward,
+        }),
+    })
+    await chat({
+      adapter: createMockAdapter({ iterations: [] }).adapter,
+      messages: [{ role: 'user', content: 'Go' }],
+      threadId: 't1',
+      promptCache: 'none',
+      stream: false,
+      subagents: { agents: [helper], router: () => 'helper' },
+    })
+    expect(child.calls[0]?.promptCache).toStrictEqual({
+      retention: 'none',
+      key: 't1:helper',
+    })
+  })
+
+  it('keeps the made-up threadId of a subagent parent out of the key', async () => {
+    const parent = createMockAdapter({ iterations: [done] })
+    await chat({
+      adapter: parent.adapter,
+      messages: [{ role: 'user', content: 'Go' }],
+      stream: false,
+      subagents: {
+        agents: [
+          defineAgent({
+            name: 'helper',
+            description: 'Idle',
+            run: async function* () {},
+          }),
+        ],
+      },
+    })
+    expect(parent.calls[0]?.threadId).toMatch(/^thread-/)
+    expect(parent.calls[0]?.promptCache).toStrictEqual({ retention: 'short' })
+  })
+})

From 121ae8297c995c4571dd05e784780549f42cbbc4 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 10:41:48 +0200
Subject: [PATCH 153/286] feat(ai-bedrock): add automatic cache points for
 Claude models

With chat({ promptCache }), Claude models on Converse get a cache point after the system prompt and at the end of the last user message. 'long' asks for the 1-hour TTL. A manual cachePoint anywhere in the request turns the automatic points off. Other models do not change.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .../ai-bedrock/src/adapters/converse-text.ts  |   4 +-
 .../ai-bedrock/src/converse/prompt-cache.ts   |  53 ++++++
 .../tests/converse/prompt-cache.test.ts       | 159 ++++++++++++++++++
 3 files changed, 215 insertions(+), 1 deletion(-)
 create mode 100644 packages/ai-bedrock/src/converse/prompt-cache.ts
 create mode 100644 packages/ai-bedrock/tests/converse/prompt-cache.test.ts

diff --git a/packages/ai-bedrock/src/adapters/converse-text.ts b/packages/ai-bedrock/src/adapters/converse-text.ts
index ba96db42ed..a786e8d764 100644
--- a/packages/ai-bedrock/src/adapters/converse-text.ts
+++ b/packages/ai-bedrock/src/adapters/converse-text.ts
@@ -10,6 +10,7 @@ import {
 } from '../converse/stream-processor'
 import { buildConverseUsage } from '../converse/usage'
 import { converseThinking } from '../converse/reasoning'
+import { addPromptCachePoints } from '../converse/prompt-cache'
 import { BEDROCK_MODEL_REASONING } from '../model-reasoning'
 import type { BedrockModelReasoningByName } from '../model-reasoning'
 import {
@@ -607,7 +608,7 @@ export class BedrockConverseTextAdapter<
           }
         : undefined
 
-    return {
+    const input: ConverseCommandInput = {
       modelId: this.model,
       messages,
       ...(system.length > 0 && { system }),
@@ -615,6 +616,7 @@ export class BedrockConverseTextAdapter<
       ...(inferenceConfig && { inferenceConfig }),
       ...(additionalModelRequestFields && { additionalModelRequestFields }),
     }
+    return addPromptCachePoints(this.model, input, options.promptCache)
   }
 }
 
diff --git a/packages/ai-bedrock/src/converse/prompt-cache.ts b/packages/ai-bedrock/src/converse/prompt-cache.ts
new file mode 100644
index 0000000000..d6a231db20
--- /dev/null
+++ b/packages/ai-bedrock/src/converse/prompt-cache.ts
@@ -0,0 +1,53 @@
+import type { ConverseCommandInput } from '@aws-sdk/client-bedrock-runtime'
+import type { ResolvedPromptCache } from '@tanstack/ai'
+import type { BedrockCachePoint } from '../message-types'
+
+/** True when one of the blocks is a cache point. */
+function hasCachePoint(
+  blocks: ReadonlyArray<{ cachePoint?: unknown }> | undefined,
+) {
+  return blocks?.some((block) => block.cachePoint !== undefined) ?? false
+}
+
+/**
+ * Add the automatic Bedrock cache points for `chat({ promptCache })` (pi's
+ * rule). Only Claude models get them. When the request already has a manual
+ * cache point (system, message, or tool), the caller owns caching and the
+ * request does not change. Otherwise:
+ * - one cache point goes at the end of `system`, when there is a system prompt.
+ * - one cache point goes at the end of the last message, when its role is
+ *   `user`.
+ *
+ * `'long'` asks for the 1-hour TTL. Bedrock has no cache key, so `key` is not
+ * used. The function returns a new input and does not change the arrays of
+ * `input`.
+ */
+export function addPromptCachePoints(
+  model: string,
+  input: ConverseCommandInput,
+  promptCache: ResolvedPromptCache | undefined,
+) {
+  const retention = promptCache?.retention ?? 'none'
+  const system = input.system ?? []
+  const messages = input.messages ?? []
+  const hasManualCachePoint =
+    hasCachePoint(system) ||
+    hasCachePoint(input.toolConfig?.tools) ||
+    messages.some((message) => hasCachePoint(message.content))
+  const isClaude = /claude/i.test(model)
+  if (retention === 'none' || !isClaude || hasManualCachePoint) return input
+
+  const cachePoint: BedrockCachePoint =
+    retention === 'long' ? { type: 'default', ttl: '1h' } : { type: 'default' }
+  const last = messages.at(-1)
+  return {
+    ...input,
+    ...(system.length > 0 && { system: [...system, { cachePoint }] }),
+    ...(last?.role === 'user' && {
+      messages: [
+        ...messages.slice(0, -1),
+        { ...last, content: [...(last.content ?? []), { cachePoint }] },
+      ],
+    }),
+  }
+}
diff --git a/packages/ai-bedrock/tests/converse/prompt-cache.test.ts b/packages/ai-bedrock/tests/converse/prompt-cache.test.ts
new file mode 100644
index 0000000000..53bb9fbf61
--- /dev/null
+++ b/packages/ai-bedrock/tests/converse/prompt-cache.test.ts
@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { BedrockConverseTextAdapter } from '../../src/adapters/converse-text'
+import type {
+  ConverseStreamCommandInput,
+  ConverseStreamOutput,
+} from '@aws-sdk/client-bedrock-runtime'
+import type { TextOptions, Tool } from '@tanstack/ai'
+import type { BedrockConverseModels } from '../../src/model-meta'
+
+const CLAUDE = 'us.anthropic.claude-sonnet-4-5-20250929-v1:0'
+const NOVA = 'us.amazon.nova-pro-v1:0'
+const point = { cachePoint: { type: 'default' } }
+const longPoint = { cachePoint: { type: 'default', ttl: '1h' } }
+const testLogger = resolveDebugOption(false)
+
+/** Keeps the Converse input the adapter sends, with no real AWS call. */
+class StubAdapter extends BedrockConverseTextAdapter<BedrockConverseModels> {
+  capturedInput?: ConverseStreamCommandInput
+
+  protected override async sendStream(
+    input: ConverseStreamCommandInput,
+  ): Promise<AsyncIterable<ConverseStreamOutput>> {
+    this.capturedInput = input
+    const events: Array<ConverseStreamOutput> = [
+      { messageStop: { stopReason: 'end_turn' } },
+    ]
+    return (async function* () {
+      for (const event of events) yield event
+    })()
+  }
+}
+
+/**
+ * Run one chat request and return the Converse input that was sent. The
+ * default request has one system prompt and one user message.
+ */
+async function sentInput(
+  model: BedrockConverseModels,
+  overrides: Partial<TextOptions>,
+) {
+  const adapter = new StubAdapter({ apiKey: 'k' }, model)
+  const options: TextOptions = {
+    model,
+    messages: [{ role: 'user', content: 'hi' }],
+    systemPrompts: [{ content: 'stable' }],
+    logger: testLogger,
+    ...overrides,
+  }
+  for await (const _chunk of adapter.chatStream(options)) {
+    // drain
+  }
+  return adapter.capturedInput
+}
+
+/** All cache point blocks in the system, the messages, and the tools. */
+function cachePointCount(input: ConverseStreamCommandInput | undefined) {
+  const blocks = [
+    ...(input?.system ?? []),
+    ...(input?.messages ?? []).flatMap((message) => message.content ?? []),
+    ...(input?.toolConfig?.tools ?? []),
+  ]
+  return blocks.filter((block) => block.cachePoint !== undefined).length
+}
+
+const short = { promptCache: { retention: 'short' } } as const
+const manualPoint = { cachePoint: { type: 'default' } } as const
+const cachedTool: Tool = {
+  name: 'lookup',
+  description: 'd',
+  inputSchema: { type: 'object', properties: {} },
+  metadata: manualPoint,
+}
+
+describe('Converse automatic prompt cache points', () => {
+  it("adds a point to the system prompt and the last user message for Claude with 'short'", async () => {
+    const input = await sentInput(CLAUDE, short)
+
+    expect(input?.system).toEqual([{ text: 'stable' }, point])
+    expect(input?.messages).toEqual([
+      { role: 'user', content: [{ text: 'hi' }, point] },
+    ])
+  })
+
+  it("adds the 1-hour TTL on both points with 'long'", async () => {
+    const input = await sentInput(CLAUDE, {
+      promptCache: { retention: 'long' },
+    })
+
+    expect(input?.system).toEqual([{ text: 'stable' }, longPoint])
+    expect(input?.messages).toEqual([
+      { role: 'user', content: [{ text: 'hi' }, longPoint] },
+    ])
+  })
+
+  it.each<[string, BedrockConverseModels, Partial<TextOptions>]>([
+    ["'none' on Claude", CLAUDE, { promptCache: { retention: 'none' } }],
+    ['no promptCache on Claude', CLAUDE, {}],
+    ["'short' on a non-Claude model", NOVA, short],
+  ])('adds no point with %s', async (_name, model, overrides) => {
+    const input = await sentInput(model, overrides)
+
+    expect(input?.system).toEqual([{ text: 'stable' }])
+    expect(input?.messages).toEqual([
+      { role: 'user', content: [{ text: 'hi' }] },
+    ])
+  })
+
+  it.each<[string, Partial<TextOptions>]>([
+    [
+      'a system prompt',
+      { systemPrompts: [{ content: 'stable', metadata: manualPoint }] },
+    ],
+    [
+      'a message',
+      {
+        messages: [
+          {
+            role: 'user',
+            content: [{ type: 'text', content: 'hi', metadata: manualPoint }],
+          },
+        ],
+      },
+    ],
+    ['a tool', { tools: [cachedTool] }],
+  ])(
+    'adds no point when %s has a manual cache point',
+    async (_name, overrides) => {
+      const input = await sentInput(CLAUDE, { ...short, ...overrides })
+
+      expect(cachePointCount(input)).toBe(1)
+    },
+  )
+
+  it('adds only the system point when the last message is from the assistant', async () => {
+    const input = await sentInput(CLAUDE, {
+      ...short,
+      messages: [
+        { role: 'user', content: 'hi' },
+        { role: 'assistant', content: 'hello' },
+      ],
+    })
+
+    expect(input?.system).toEqual([{ text: 'stable' }, point])
+    expect(input?.messages).toEqual([
+      { role: 'user', content: [{ text: 'hi' }] },
+      { role: 'assistant', content: [{ text: 'hello' }] },
+    ])
+  })
+
+  it('adds only the message point when there is no system prompt', async () => {
+    const input = await sentInput(CLAUDE, { ...short, systemPrompts: [] })
+
+    expect(input?.system).toBeUndefined()
+    expect(input?.messages).toEqual([
+      { role: 'user', content: [{ text: 'hi' }, point] },
+    ])
+  })
+})

From c548cb494d6fd40732e3a1e1464af86684873bd9 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 10:45:16 +0200
Subject: [PATCH 154/286] feat(ai-openai): send prompt cache fields on
 Responses and Chat Completions

With chat({ promptCache }), Responses gets prompt_cache_key (cut to 64 characters), prompt_cache_retention '24h' for 'long', and prompt_cache_options on gpt-5.6 and later. Chat Completions sends the key to api.openai.com, or with 'long'. A value in modelOptions wins.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .../src/adapters/text-chat-completions.ts     |  16 +-
 packages/ai-openai/src/adapters/text.ts       |   9 +
 packages/ai-openai/src/model-meta.ts          |  15 +
 packages/ai-openai/src/prompt-cache.ts        |  56 +++
 packages/ai-openai/tests/prompt-cache.test.ts | 351 ++++++++++++++++++
 5 files changed, 446 insertions(+), 1 deletion(-)
 create mode 100644 packages/ai-openai/src/prompt-cache.ts
 create mode 100644 packages/ai-openai/tests/prompt-cache.test.ts

diff --git a/packages/ai-openai/src/adapters/text-chat-completions.ts b/packages/ai-openai/src/adapters/text-chat-completions.ts
index e0964e96b6..a13de37ee7 100644
--- a/packages/ai-openai/src/adapters/text-chat-completions.ts
+++ b/packages/ai-openai/src/adapters/text-chat-completions.ts
@@ -2,6 +2,7 @@ import OpenAI from 'openai'
 import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
 import { getOpenAIApiKeyFromEnv } from '../utils/client'
 import { OPENAI_MODEL_INPUT_MODALITIES } from '../model-meta'
+import { chatPromptCacheFields } from '../prompt-cache'
 import type {
   OPENAI_CHAT_MODELS,
   OpenAIChatModel,
@@ -9,7 +10,7 @@ import type {
   OpenAIChatModelToolCapabilitiesByName,
   OpenAIModelInputModalitiesByName,
 } from '../model-meta'
-import type { Modality } from '@tanstack/ai'
+import type { Modality, TextOptions } from '@tanstack/ai'
 import type { OpenAIMessageMetadataByModality } from '../message-types'
 import type { OpenAIClientConfig } from '../utils/client'
 import type { ExternalTextProviderOptions } from '../text/text-provider-options'
@@ -71,6 +72,19 @@ export class OpenAIChatCompletionsTextAdapter<
   constructor(config: OpenAIChatCompletionsConfig, model: TModel) {
     super(model, 'openai-chat', new OpenAI(config), config)
   }
+
+  /** The request, plus the prompt cache fields for `chat({ promptCache })`. */
+  protected override mapOptionsToRequest(options: TextOptions) {
+    // The cache fields go first, so a value the caller set in `modelOptions`
+    // (already on the base request) wins.
+    return {
+      ...chatPromptCacheFields(options.promptCache, {
+        baseURL: this.client.baseURL ?? '',
+        longRetention: true,
+      }),
+      ...super.mapOptionsToRequest(options),
+    }
+  }
 }
 
 export function createOpenaiChatCompletions<
diff --git a/packages/ai-openai/src/adapters/text.ts b/packages/ai-openai/src/adapters/text.ts
index a418ce6a8a..66b87f7f11 100644
--- a/packages/ai-openai/src/adapters/text.ts
+++ b/packages/ai-openai/src/adapters/text.ts
@@ -10,7 +10,9 @@ import { getOpenAIApiKeyFromEnv } from '../utils/client'
 import {
   OPENAI_MODEL_INPUT_MODALITIES,
   openAIModelRejectsSamplingParams,
+  openAIModelUsesExplicitPromptCache,
 } from '../model-meta'
+import { responsesPromptCacheFields } from '../prompt-cache'
 import type {
   OPENAI_CHAT_MODELS,
   OpenAIChatModel,
@@ -164,7 +166,14 @@ export class OpenAITextAdapter<
       ? convertToolsToProviderFormat(options.tools)
       : undefined
 
+    // `chat({ promptCache })` fields go first, so a value the caller set in
+    // `modelOptions` (already on `baseRequest`) wins.
+    const promptCacheFields = responsesPromptCacheFields(options.promptCache, {
+      explicitMode: openAIModelUsesExplicitPromptCache(options.model),
+      longRetention: true,
+    })
     const request: Omit<ResponseCreateParams, 'stream'> = {
+      ...promptCacheFields,
       ...baseRequest,
       ...(tools && tools.length > 0 && { tools }),
     }
diff --git a/packages/ai-openai/src/model-meta.ts b/packages/ai-openai/src/model-meta.ts
index 0225cd8c97..96bdf07198 100644
--- a/packages/ai-openai/src/model-meta.ts
+++ b/packages/ai-openai/src/model-meta.ts
@@ -2814,6 +2814,21 @@ export function openAIModelRejectsSamplingParams(model: string): boolean {
   return false
 }
 
+/**
+ * Whether a model takes OpenAI's explicit prompt cache controls
+ * (`prompt_cache_options`) in place of `prompt_cache_retention`.
+ * This is true for gpt-5.6 and later, and for gpt-6 and later.
+ */
+export function openAIModelUsesExplicitPromptCache(model: string) {
+  // ponytail: name match on the version number. If OpenAI ships a model that
+  // breaks this pattern, add a per-model flag to the model meta.
+  const match = /^gpt-(\d+)(?:\.(\d+))?/.exec(model)
+  if (!match) return false
+  const major = Number(match[1])
+  const minor = Number(match[2] ?? 0)
+  return major > 5 || (major === 5 && minor >= 6)
+}
+
 // Image generation models (based on endpoints: "image-generation" or "image-edit")
 export const OPENAI_IMAGE_MODELS = [
   GPT_IMAGE_2_5_FLARE.name,
diff --git a/packages/ai-openai/src/prompt-cache.ts b/packages/ai-openai/src/prompt-cache.ts
new file mode 100644
index 0000000000..546c7d3af4
--- /dev/null
+++ b/packages/ai-openai/src/prompt-cache.ts
@@ -0,0 +1,56 @@
+import type { ResolvedPromptCache } from '@tanstack/ai'
+
+/**
+ * Cut a cache key to 64 characters, the most OpenAI accepts. It counts code
+ * points, so an emoji or a CJK character is never cut in half.
+ */
+export function clampPromptCacheKey(key: string | undefined) {
+  return key === undefined ? undefined : Array.from(key).slice(0, 64).join('')
+}
+
+/**
+ * The prompt cache fields of a Responses request.
+ *
+ * - `explicitMode`: the model takes `prompt_cache_options` in place of
+ *   `prompt_cache_retention` (see `openAIModelUsesExplicitPromptCache`).
+ * - `longRetention`: the endpoint keeps a cache for longer than a few minutes.
+ */
+export function responsesPromptCacheFields(
+  promptCache: ResolvedPromptCache | undefined,
+  flags: { explicitMode: boolean; longRetention: boolean },
+) {
+  const fields: Record<string, unknown> = {}
+  if (!promptCache) return fields
+  const { retention } = promptCache
+  const key = clampPromptCacheKey(promptCache.key)
+  const isLong = retention === 'long' && flags.longRetention
+  if (retention !== 'none' && key) fields.prompt_cache_key = key
+  if (!flags.explicitMode) {
+    if (isLong) fields.prompt_cache_retention = '24h'
+    return fields
+  }
+  if (retention === 'none') fields.prompt_cache_options = { mode: 'explicit' }
+  else if (isLong) fields.prompt_cache_options = { ttl: '30m' }
+  return fields
+}
+
+/**
+ * The prompt cache fields of a Chat Completions request.
+ *
+ * A short retention sends the key only to `api.openai.com`, because another
+ * server can reject a field it does not know. A long retention sends the key
+ * and `24h` when `longRetention` is true.
+ */
+export function chatPromptCacheFields(
+  promptCache: ResolvedPromptCache | undefined,
+  flags: { baseURL: string; longRetention: boolean },
+) {
+  const fields: Record<string, unknown> = {}
+  if (!promptCache || promptCache.retention === 'none') return fields
+  const key = clampPromptCacheKey(promptCache.key)
+  const isLong = promptCache.retention === 'long' && flags.longRetention
+  const sendsKey = isLong || flags.baseURL.includes('api.openai.com')
+  if (key && sendsKey) fields.prompt_cache_key = key
+  if (isLong) fields.prompt_cache_retention = '24h'
+  return fields
+}
diff --git a/packages/ai-openai/tests/prompt-cache.test.ts b/packages/ai-openai/tests/prompt-cache.test.ts
new file mode 100644
index 0000000000..08393c2ad8
--- /dev/null
+++ b/packages/ai-openai/tests/prompt-cache.test.ts
@@ -0,0 +1,351 @@
+import { describe, expect, it, vi } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { OpenAITextAdapter } from '../src/adapters/text'
+import { OpenAIChatCompletionsTextAdapter } from '../src/adapters/text-chat-completions'
+import { openAIModelUsesExplicitPromptCache } from '../src/model-meta'
+import {
+  chatPromptCacheFields,
+  clampPromptCacheKey,
+  responsesPromptCacheFields,
+} from '../src/prompt-cache'
+import type { ResolvedPromptCache } from '@tanstack/ai'
+import type { OpenAITextProviderOptions } from '../src/adapters/text'
+import type { OpenAIChatModel } from '../src/model-meta'
+
+const logger = resolveDebugOption(false)
+const messages = [{ role: 'user' as const, content: 'hi' }]
+const CUSTOM_URL = 'https://llm.example.com/v1'
+
+async function* noEvents() {}
+
+/** The Responses adapter, with its SDK client in reach so a test can stub it. */
+class ResponsesAdapter<
+  TModel extends OpenAIChatModel,
+> extends OpenAITextAdapter<TModel> {
+  get sdk() {
+    return this.client
+  }
+}
+
+/** The Chat Completions adapter, with its SDK client in reach. */
+class ChatAdapter<
+  TModel extends OpenAIChatModel,
+> extends OpenAIChatCompletionsTextAdapter<TModel> {
+  get sdk() {
+    return this.client
+  }
+}
+
+async function drain(stream: AsyncIterable<unknown>) {
+  for await (const _chunk of stream) {
+    // Drain the stream.
+  }
+}
+
+/** Only the `prompt_cache*` fields of a request body. */
+function promptCacheFieldsOf(body: object) {
+  return Object.fromEntries(
+    Object.entries(body).filter(([key]) => key.startsWith('prompt_cache')),
+  )
+}
+
+/** Run one Responses call and return the cache fields it sent. */
+async function sendResponses(
+  model: OpenAIChatModel,
+  promptCache: ResolvedPromptCache | undefined,
+  modelOptions?: OpenAITextProviderOptions,
+) {
+  const adapter = new ResponsesAdapter({ apiKey: 'test' }, model)
+  // The SDK `create` returns an APIPromise, which a mock cannot build.
+  const create = vi.fn().mockResolvedValue(noEvents())
+  adapter.sdk.responses.create = create as typeof adapter.sdk.responses.create
+  await drain(
+    adapter.chatStream({
+      logger,
+      model,
+      messages,
+      ...(promptCache ? { promptCache } : {}),
+      ...(modelOptions ? { modelOptions } : {}),
+    }),
+  )
+  return promptCacheFieldsOf(create.mock.calls[0]?.[0])
+}
+
+/** Run one Chat Completions call and return the cache fields it sent. */
+async function sendChat(
+  promptCache: ResolvedPromptCache | undefined,
+  options: { baseURL?: string; modelOptions?: OpenAITextProviderOptions } = {},
+) {
+  const adapter = new ChatAdapter(
+    {
+      apiKey: 'test',
+      ...(options.baseURL ? { baseURL: options.baseURL } : {}),
+    },
+    'gpt-4.1',
+  )
+  // The SDK `create` returns an APIPromise, which a mock cannot build.
+  const create = vi.fn().mockResolvedValue(noEvents())
+  adapter.sdk.chat.completions.create =
+    create as typeof adapter.sdk.chat.completions.create
+  await drain(
+    adapter.chatStream({
+      logger,
+      model: 'gpt-4.1',
+      messages,
+      ...(promptCache ? { promptCache } : {}),
+      ...(options.modelOptions ? { modelOptions: options.modelOptions } : {}),
+    }),
+  )
+  return promptCacheFieldsOf(create.mock.calls[0]?.[0])
+}
+
+describe('clampPromptCacheKey', () => {
+  it('keeps a short key as it is', () => {
+    expect(clampPromptCacheKey('thread-1')).toBe('thread-1')
+  })
+
+  it('keeps no key as no key', () => {
+    expect(clampPromptCacheKey(undefined)).toBeUndefined()
+  })
+
+  it('cuts at 64 characters and never splits an emoji or a CJK character', () => {
+    // 2 + 20 + 60 = 82 characters. A cut by UTF-16 units splits the emoji run.
+    const key = `k-${'缓存'.repeat(10)}${'😀'.repeat(60)}`
+
+    expect(clampPromptCacheKey(key)).toBe(
+      `k-${'缓存'.repeat(10)}${'😀'.repeat(42)}`,
+    )
+  })
+})
+
+describe('openAIModelUsesExplicitPromptCache', () => {
+  it('is true for gpt-5.6 and later, and for gpt-6 and later', () => {
+    for (const model of [
+      'gpt-5.6',
+      'gpt-5.6-sol',
+      'gpt-5.6-luna-pro',
+      'gpt-5.10',
+      'gpt-6-sol',
+      'gpt-6.1-sol',
+    ]) {
+      expect(openAIModelUsesExplicitPromptCache(model), model).toBe(true)
+    }
+  })
+
+  it('is false for older models', () => {
+    for (const model of [
+      'gpt-5.5',
+      'gpt-5.5-pro',
+      'gpt-5.2',
+      'gpt-5',
+      'gpt-4.1',
+      'gpt-4o',
+      'o3',
+      'gpt-chat-latest',
+    ]) {
+      expect(openAIModelUsesExplicitPromptCache(model), model).toBe(false)
+    }
+  })
+})
+
+describe('responsesPromptCacheFields', () => {
+  const classic = { explicitMode: false, longRetention: true }
+  const explicit = { explicitMode: true, longRetention: true }
+
+  it('sends nothing without the option', () => {
+    expect(responsesPromptCacheFields(undefined, explicit)).toEqual({})
+  })
+
+  it('sends the key for a short retention', () => {
+    expect(
+      responsesPromptCacheFields({ retention: 'short', key: 'k-1' }, classic),
+    ).toEqual({ prompt_cache_key: 'k-1' })
+  })
+
+  it('sends no key when there is none', () => {
+    expect(responsesPromptCacheFields({ retention: 'short' }, classic)).toEqual(
+      {},
+    )
+  })
+
+  it('sends nothing for none on an older model', () => {
+    expect(
+      responsesPromptCacheFields({ retention: 'none', key: 'k-1' }, classic),
+    ).toEqual({})
+  })
+
+  it('sends 24h for a long retention on an older model', () => {
+    expect(
+      responsesPromptCacheFields({ retention: 'long', key: 'k-1' }, classic),
+    ).toEqual({ prompt_cache_key: 'k-1', prompt_cache_retention: '24h' })
+  })
+
+  it('sends no 24h when the endpoint has no long retention', () => {
+    expect(
+      responsesPromptCacheFields(
+        { retention: 'long', key: 'k-1' },
+        { explicitMode: false, longRetention: false },
+      ),
+    ).toEqual({ prompt_cache_key: 'k-1' })
+  })
+
+  it('turns automatic caching off for none on an explicit-mode model', () => {
+    expect(
+      responsesPromptCacheFields({ retention: 'none', key: 'k-1' }, explicit),
+    ).toEqual({ prompt_cache_options: { mode: 'explicit' } })
+  })
+
+  it('sends a 30m ttl, not 24h, for a long retention on an explicit-mode model', () => {
+    expect(
+      responsesPromptCacheFields({ retention: 'long', key: 'k-1' }, explicit),
+    ).toEqual({ prompt_cache_key: 'k-1', prompt_cache_options: { ttl: '30m' } })
+  })
+
+  it('sends only the key for a short retention on an explicit-mode model', () => {
+    expect(
+      responsesPromptCacheFields({ retention: 'short', key: 'k-1' }, explicit),
+    ).toEqual({ prompt_cache_key: 'k-1' })
+  })
+})
+
+describe('chatPromptCacheFields', () => {
+  const openai = { baseURL: 'https://api.openai.com/v1', longRetention: true }
+  const custom = { baseURL: CUSTOM_URL, longRetention: true }
+
+  it('sends nothing without the option, or for none', () => {
+    expect(chatPromptCacheFields(undefined, openai)).toEqual({})
+    expect(
+      chatPromptCacheFields({ retention: 'none', key: 'k-1' }, openai),
+    ).toEqual({})
+  })
+
+  it('sends the key to api.openai.com for a short retention', () => {
+    expect(
+      chatPromptCacheFields({ retention: 'short', key: 'k-1' }, openai),
+    ).toEqual({ prompt_cache_key: 'k-1' })
+  })
+
+  it('sends no key to another server for a short retention', () => {
+    expect(
+      chatPromptCacheFields({ retention: 'short', key: 'k-1' }, custom),
+    ).toEqual({})
+  })
+
+  it('sends the key and 24h to another server for a long retention', () => {
+    expect(
+      chatPromptCacheFields({ retention: 'long', key: 'k-1' }, custom),
+    ).toEqual({ prompt_cache_key: 'k-1', prompt_cache_retention: '24h' })
+  })
+
+  it('sends 24h but no key when there is none', () => {
+    expect(chatPromptCacheFields({ retention: 'long' }, custom)).toEqual({
+      prompt_cache_retention: '24h',
+    })
+  })
+
+  it('sends nothing to another server when it has no long retention', () => {
+    expect(
+      chatPromptCacheFields(
+        { retention: 'long', key: 'k-1' },
+        { baseURL: CUSTOM_URL, longRetention: false },
+      ),
+    ).toEqual({})
+  })
+})
+
+describe('OpenAI Responses adapter: chat({ promptCache })', () => {
+  it('sends the clamped key and 24h on an older model', async () => {
+    expect(
+      await sendResponses('gpt-5.5', {
+        retention: 'long',
+        key: `k-${'😀'.repeat(70)}`,
+      }),
+    ).toStrictEqual({
+      prompt_cache_key: `k-${'😀'.repeat(62)}`,
+      prompt_cache_retention: '24h',
+    })
+  })
+
+  it('turns automatic caching off for none on gpt-5.6', async () => {
+    expect(
+      await sendResponses('gpt-5.6', { retention: 'none', key: 'k-1' }),
+    ).toStrictEqual({ prompt_cache_options: { mode: 'explicit' } })
+  })
+
+  it('sends a 30m ttl and no prompt_cache_retention for long on gpt-6-sol', async () => {
+    expect(
+      await sendResponses('gpt-6-sol', { retention: 'long', key: 'k-1' }),
+    ).toStrictEqual({
+      prompt_cache_key: 'k-1',
+      prompt_cache_options: { ttl: '30m' },
+    })
+  })
+
+  it('keeps the values the caller set in modelOptions', async () => {
+    // `prompt_cache_options` is not in the typed options, so it comes in as a
+    // plain object, the way a JavaScript caller sends it.
+    const callerOptions = {
+      prompt_cache_key: 'caller-key',
+      prompt_cache_options: { ttl: '5m' },
+    }
+
+    expect(
+      await sendResponses(
+        'gpt-5.6',
+        { retention: 'long', key: 'k-1' },
+        callerOptions,
+      ),
+    ).toStrictEqual({
+      prompt_cache_key: 'caller-key',
+      prompt_cache_options: { ttl: '5m' },
+    })
+  })
+
+  it('sends no cache field without the option', async () => {
+    expect(await sendResponses('gpt-5.6', undefined)).toStrictEqual({})
+  })
+})
+
+describe('OpenAI Chat Completions adapter: chat({ promptCache })', () => {
+  it('sends the key to api.openai.com for a short retention', async () => {
+    // The base URL is set here, so an OPENAI_BASE_URL env value cannot
+    // change the result.
+    expect(
+      await sendChat(
+        { retention: 'short', key: 'k-1' },
+        { baseURL: 'https://api.openai.com/v1' },
+      ),
+    ).toStrictEqual({ prompt_cache_key: 'k-1' })
+  })
+
+  it('sends no key to a custom base URL for a short retention', async () => {
+    expect(
+      await sendChat(
+        { retention: 'short', key: 'k-1' },
+        { baseURL: CUSTOM_URL },
+      ),
+    ).toStrictEqual({})
+  })
+
+  it('sends the key and 24h to a custom base URL for a long retention', async () => {
+    expect(
+      await sendChat(
+        { retention: 'long', key: 'k-1' },
+        { baseURL: CUSTOM_URL },
+      ),
+    ).toStrictEqual({ prompt_cache_key: 'k-1', prompt_cache_retention: '24h' })
+  })
+
+  it('keeps the key the caller set in modelOptions', async () => {
+    expect(
+      await sendChat(
+        { retention: 'short', key: 'k-1' },
+        { modelOptions: { prompt_cache_key: 'caller-key' } },
+      ),
+    ).toStrictEqual({ prompt_cache_key: 'caller-key' })
+  })
+
+  it('sends no cache field without the option', async () => {
+    expect(await sendChat(undefined)).toStrictEqual({})
+  })
+})

From 608636c05031b4bd35dbb70fdef7b07a917758a9 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 10:45:17 +0200
Subject: [PATCH 155/286] feat(ai-mistral): send the prompt cache key and
 report cache reads

The stream path sends prompt_cache_key when chat({ promptCache }) has a key and the retention is not 'none'. Usage reports cachedTokens from prompt_tokens_details.cached_tokens or num_cached_tokens.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-mistral/src/adapters/text.ts      |  46 +++++-
 .../ai-mistral/tests/prompt-cache.test.ts     | 148 ++++++++++++++++++
 2 files changed, 191 insertions(+), 3 deletions(-)
 create mode 100644 packages/ai-mistral/tests/prompt-cache.test.ts

diff --git a/packages/ai-mistral/src/adapters/text.ts b/packages/ai-mistral/src/adapters/text.ts
index 53dbcd0d61..600b824e55 100644
--- a/packages/ai-mistral/src/adapters/text.ts
+++ b/packages/ai-mistral/src/adapters/text.ts
@@ -20,6 +20,7 @@ import type {
   AdapterYieldChunk,
   ModelReasoning,
   ReasoningRequest,
+  ResolvedPromptCache,
   TextOptions,
 } from '@tanstack/ai'
 import type {
@@ -129,6 +130,37 @@ function mistralReasoning(
   return resolved.level === 'off' ? {} : { promptMode: 'reasoning' }
 }
 
+/**
+ * The Mistral wire field for `chat({ promptCache })`, by pi's rule. Mistral
+ * caches without a flag, so only the key goes out. There is no key for
+ * `'none'`. The SDK request type has no cache key field, so only the raw
+ * stream path sends it.
+ */
+function mistralPromptCacheKey(promptCache: ResolvedPromptCache | undefined) {
+  if (!promptCache?.key || promptCache.retention === 'none') return {}
+  return { prompt_cache_key: promptCache.key }
+}
+
+/**
+ * `promptTokensDetails.cachedTokens` when Mistral read prompt tokens from the
+ * cache. Mistral sends the count in `prompt_tokens_details.cached_tokens` or
+ * in `num_cached_tokens`. The SDK keeps these raw keys on `usage` with no
+ * types, so the values are checked here.
+ */
+function mistralCachedTokens(usage: Record<string, unknown>) {
+  const details = usage.prompt_tokens_details
+  const hasDetailsCount =
+    typeof details === 'object' &&
+    details !== null &&
+    'cached_tokens' in details
+  const cachedTokens = hasDetailsCount
+    ? details.cached_tokens
+    : usage.num_cached_tokens
+  return typeof cachedTokens === 'number' && cachedTokens > 0
+    ? { promptTokensDetails: { cachedTokens } }
+    : {}
+}
+
 type ResolveInputModalities<TModel extends string> =
   TModel extends keyof MistralModelInputModalitiesByName
     ? MistralModelInputModalitiesByName[TModel]
@@ -189,6 +221,9 @@ interface MistralRawChunk {
     prompt_tokens?: number
     completion_tokens?: number
     total_tokens?: number
+    // Cache reads. Mistral sends one of these two.
+    prompt_tokens_details?: { cached_tokens?: number } | null
+    num_cached_tokens?: number | null
   }
 }
 
@@ -246,7 +281,11 @@ export class MistralTextAdapter<
     }
 
     try {
-      const stream = this.fetchRawMistralStream(requestParams, this.rawConfig)
+      const body = {
+        ...this.toWireBody(requestParams),
+        ...mistralPromptCacheKey(options.promptCache),
+      }
+      const stream = this.fetchRawMistralStream(body, this.rawConfig)
       yield* this.processMistralStreamChunks(stream, options, aguiState)
     } catch (error: unknown) {
       const err = error as Error & { code?: string }
@@ -331,6 +370,7 @@ export class MistralTextAdapter<
           promptTokens: usage.promptTokens ?? 0,
           completionTokens: usage.completionTokens ?? 0,
           totalTokens: usage.totalTokens ?? 0,
+          ...mistralCachedTokens(usage),
         },
       }),
     }
@@ -633,6 +673,7 @@ export class MistralTextAdapter<
                   promptTokens: usage.prompt_tokens || 0,
                   completionTokens: usage.completion_tokens || 0,
                   totalTokens: usage.total_tokens || 0,
+                  ...mistralCachedTokens(usage),
                 }
               : undefined,
             finishReason: computedFinishReason,
@@ -760,7 +801,7 @@ export class MistralTextAdapter<
    * rejects streaming tool call chunks that omit `name` in argument deltas.
    */
   private async *fetchRawMistralStream(
-    params: ChatCompletionStreamRequest,
+    body: Record<string, unknown>,
     config: MistralClientConfig,
   ): AsyncGenerator<MistralRawChunk> {
     const serverURL = (
@@ -773,7 +814,6 @@ export class MistralTextAdapter<
     const url =
       config.resolveRequestUrl?.(true) ?? `${serverURL}/v1/chat/completions`
 
-    const body = this.toWireBody(params)
     const accessToken =
       config.getAccessToken === undefined
         ? config.apiKey
diff --git a/packages/ai-mistral/tests/prompt-cache.test.ts b/packages/ai-mistral/tests/prompt-cache.test.ts
new file mode 100644
index 0000000000..9bd130cf2b
--- /dev/null
+++ b/packages/ai-mistral/tests/prompt-cache.test.ts
@@ -0,0 +1,148 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { createMistralText } from '../src/adapters/text'
+import type { ResolvedPromptCache } from '@tanstack/ai'
+
+const logger = resolveDebugOption(false)
+const model = 'mistral-large-latest'
+const messages = [{ role: 'user' as const, content: 'hi' }]
+
+/** Mistral `usage` as it comes on the wire. */
+interface WireUsage {
+  prompt_tokens: number
+  completion_tokens: number
+  total_tokens: number
+  prompt_tokens_details?: { cached_tokens: number }
+  num_cached_tokens?: number
+}
+
+const baseUsage = {
+  prompt_tokens: 100,
+  completion_tokens: 5,
+  total_tokens: 105,
+}
+
+/** Stub fetch so the next request gets `response`. */
+function stubFetch(response: Response) {
+  const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(response)
+  vi.stubGlobal('fetch', fetchMock)
+  return fetchMock
+}
+
+/**
+ * Run one streaming call. Return the JSON body it sent and the usage on
+ * RUN_FINISHED. The stream has one chunk that finishes with `usage`.
+ */
+async function stream(options: {
+  promptCache?: ResolvedPromptCache
+  usage?: WireUsage
+}) {
+  const chunk = {
+    id: 'cmpl-1',
+    model,
+    choices: [{ index: 0, delta: { content: 'ok' }, finish_reason: 'stop' }],
+    usage: options.usage,
+  }
+  const fetchMock = stubFetch(
+    new Response(`data: ${JSON.stringify(chunk)}\n\ndata: [DONE]\n\n`),
+  )
+  const adapter = createMistralText(model, 'test-key')
+  let usage: unknown
+  for await (const event of adapter.chatStream({
+    logger,
+    model,
+    messages,
+    promptCache: options.promptCache,
+  })) {
+    if (event.type === 'RUN_FINISHED') usage = event.usage
+  }
+  const [, init] = fetchMock.mock.calls[0] ?? []
+  return { body: JSON.parse(String(init?.body)), usage }
+}
+
+describe('Mistral chat({ promptCache }) cache key', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('sends prompt_cache_key for a retention with a key', async () => {
+    const { body } = await stream({
+      promptCache: { retention: 'short', key: 'k-1' },
+    })
+    expect(body.prompt_cache_key).toBe('k-1')
+  })
+
+  it.each<[string, ResolvedPromptCache | undefined]>([
+    ["'none'", { retention: 'none', key: 'k-1' }],
+    ['no key', { retention: 'long' }],
+    ['no promptCache', undefined],
+  ])('sends no prompt_cache_key for %s', async (_name, promptCache) => {
+    const { body } = await stream({ promptCache })
+    expect(body).not.toHaveProperty('prompt_cache_key')
+  })
+})
+
+describe('Mistral cache-read usage', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it.each<[string, WireUsage]>([
+    [
+      'prompt_tokens_details.cached_tokens',
+      { ...baseUsage, prompt_tokens_details: { cached_tokens: 80 } },
+    ],
+    ['num_cached_tokens', { ...baseUsage, num_cached_tokens: 80 }],
+  ])('stream reads cachedTokens from %s', async (_name, usage) => {
+    expect((await stream({ usage })).usage).toStrictEqual({
+      promptTokens: 100,
+      completionTokens: 5,
+      totalTokens: 105,
+      promptTokensDetails: { cachedTokens: 80 },
+    })
+  })
+
+  it.each<[string, WireUsage]>([
+    ['no cache fields', baseUsage],
+    [
+      'zero cached tokens',
+      { ...baseUsage, prompt_tokens_details: { cached_tokens: 0 } },
+    ],
+  ])('stream adds no promptTokensDetails for %s', async (_name, usage) => {
+    expect((await stream({ usage })).usage).toStrictEqual({
+      promptTokens: 100,
+      completionTokens: 5,
+      totalTokens: 105,
+    })
+  })
+
+  it('structured output reads cachedTokens through the SDK', async () => {
+    stubFetch(
+      Response.json({
+        id: 'cmpl-1',
+        object: 'chat.completion',
+        model,
+        created: 0,
+        choices: [
+          {
+            index: 0,
+            message: { role: 'assistant', content: '{}' },
+            finish_reason: 'stop',
+          },
+        ],
+        usage: { ...baseUsage, prompt_tokens_details: { cached_tokens: 80 } },
+      }),
+    )
+    const adapter = createMistralText(model, 'test-key')
+    const result = await adapter.structuredOutput({
+      chatOptions: { logger, model, messages },
+      outputSchema: { type: 'object', properties: {}, required: [] },
+    })
+    expect(result.usage).toStrictEqual({
+      promptTokens: 100,
+      completionTokens: 5,
+      totalTokens: 105,
+      promptTokensDetails: { cachedTokens: 80 },
+    })
+  })
+})

From 988d8875b09c6d312dbef746c463000fd2cb940b Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 10:45:17 +0200
Subject: [PATCH 156/286] feat(ai-harness): cache prompts in every session by
 default

HarnessConfig.promptCache sets the default for all sessions ('short'). OpenSessionOptions.promptCache overrides it for one session. The key is the session value, else the harness value, else the threadId. Agents inherit the retention. The usage() plugin also counts cache reads and writes.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-harness/src/define.ts             |  8 ++
 .../src/first-party/session-tools.ts          | 25 ++++++-
 packages/ai-harness/src/host.ts               | 11 ++-
 packages/ai-harness/src/session.ts            | 20 +++++
 packages/ai-harness/tests/first-party.test.ts | 12 ++-
 .../ai-harness/tests/prompt-cache.test.ts     | 75 +++++++++++++++++++
 6 files changed, 144 insertions(+), 7 deletions(-)
 create mode 100644 packages/ai-harness/tests/prompt-cache.test.ts

diff --git a/packages/ai-harness/src/define.ts b/packages/ai-harness/src/define.ts
index 959b116d06..1f225582e1 100644
--- a/packages/ai-harness/src/define.ts
+++ b/packages/ai-harness/src/define.ts
@@ -5,6 +5,7 @@ import type {
   AnyTool,
   InterruptDefinition,
   KeyedAdapter,
+  PromptCacheOptions,
   SubagentsBag,
   SystemPrompt,
 } from '@tanstack/ai'
@@ -70,6 +71,13 @@ export interface HarnessConfig<
   /** When a turn stops calling the model. Defaults to `maxIterations(50)`. */
   agentLoopStrategy?: AgentLoopStrategy
   modelOptions?: TAdapter['~types']['providerOptions']
+  /**
+   * Automatic prompt caching for every session, the same as
+   * `chat({ promptCache })`. Default `'short'`. `'none'` turns it off. A
+   * `key` here is shared by all sessions, so usually leave it out: then each
+   * session uses its threadId as the key.
+   */
+  promptCache?: PromptCacheOptions
   interrupts?: ReadonlyArray<InterruptDefinition<any, any, any, any>>
   /** Runtime context passed to middleware hooks and server tools. */
   context?: unknown
diff --git a/packages/ai-harness/src/first-party/session-tools.ts b/packages/ai-harness/src/first-party/session-tools.ts
index eba347d004..8e9a2c0c4e 100644
--- a/packages/ai-harness/src/first-party/session-tools.ts
+++ b/packages/ai-harness/src/first-party/session-tools.ts
@@ -82,6 +82,10 @@ interface UsageTotals {
   promptTokens: number
   completionTokens: number
   totalTokens: number
+  /** Input tokens the provider read from its prompt cache. */
+  cachedTokens: number
+  /** Input tokens the provider wrote to its prompt cache. */
+  cacheWriteTokens: number
   /**
    * The input tokens of the latest model call of the lead turn: how much of
    * the model's context the conversation fills now.
@@ -92,7 +96,8 @@ interface UsageTotals {
 /**
  * Count tokens across the session: the lead turn and every agent run
  * (subagents, background agents, and their children). `/usage` shows the
- * totals. The plugin state also has `contextTokens`, the size of the lead
+ * totals, with the input tokens read from and written to the prompt cache.
+ * The plugin state also has `contextTokens`, the size of the lead
  * model's context at its latest call, for a UI.
  */
 export function usage() {
@@ -104,10 +109,18 @@ export function usage() {
         promptTokens: 0,
         completionTokens: 0,
         totalTokens: 0,
+        cachedTokens: 0,
+        cacheWriteTokens: 0,
         contextTokens: 0,
       })
-      const show = (totals: UsageTotals) =>
-        `${totals.turns} model calls, ${totals.promptTokens} input tokens, ${totals.completionTokens} output tokens, ${totals.totalTokens} total.`
+      const show = (totals: UsageTotals) => {
+        // Only a provider that reports its prompt cache has these counts.
+        const hasCache = totals.cachedTokens > 0 || totals.cacheWriteTokens > 0
+        const cache = hasCache
+          ? ` (${totals.cachedTokens} cache read, ${totals.cacheWriteTokens} cache write)`
+          : ''
+        return `${totals.turns} model calls, ${totals.promptTokens} input tokens${cache}, ${totals.completionTokens} output tokens, ${totals.totalTokens} total.`
+      }
       const counter = (lead: boolean) =>
         ({
           name: 'tanstack/usage',
@@ -118,6 +131,12 @@ export function usage() {
               completionTokens:
                 totals.completionTokens + (info.completionTokens ?? 0),
               totalTokens: totals.totalTokens + (info.totalTokens ?? 0),
+              cachedTokens:
+                totals.cachedTokens +
+                (info.promptTokensDetails?.cachedTokens ?? 0),
+              cacheWriteTokens:
+                totals.cacheWriteTokens +
+                (info.promptTokensDetails?.cacheWriteTokens ?? 0),
               contextTokens: lead
                 ? (info.promptTokens ?? totals.contextTokens)
                 : totals.contextTokens,
diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
index e1657b08ef..a1048ae0e9 100644
--- a/packages/ai-harness/src/host.ts
+++ b/packages/ai-harness/src/host.ts
@@ -1,7 +1,7 @@
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { SharedLog, loadLogState } from './log'
 import { HarnessSession } from './session'
-import type { RunStore } from '@tanstack/ai'
+import type { PromptCacheOptions, RunStore } from '@tanstack/ai'
 import type {
   AIPersistence,
   ArtifactStore,
@@ -98,6 +98,12 @@ export interface OpenSessionOptions {
    * them. Default: `threadId`.
    */
   logId?: string
+  /**
+   * Prompt caching for this session. It overrides the harness `promptCache`,
+   * for example with a stable affinity key. Opening the same `threadId` again
+   * returns the live session, which keeps the value of the first open.
+   */
+  promptCache?: PromptCacheOptions
 }
 
 /** Runs sessions for one or more harnesses in this process. */
@@ -220,7 +226,7 @@ export function createHarnessHost<TLogState = undefined>(
   const hostId = `host-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`
 
   return {
-    open(harness, { threadId, principal, logId: openLogId }) {
+    open(harness, { threadId, principal, logId: openLogId, promptCache }) {
       const key = `${harness.name}\u0000${threadId}`
       let session = sessions.get(key)
       if (!session) {
@@ -251,6 +257,7 @@ export function createHarnessHost<TLogState = undefined>(
             : {}),
           ...(options.lease ? { lease: options.lease } : {}),
           ...(principal ? { principal } : {}),
+          ...(promptCache ? { promptCache } : {}),
           onClose: () => sessions.delete(key),
         })
         session = created.open().then(
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 261b4f9970..1c2410a6f4 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -42,7 +42,9 @@ import type {
   Interrupt,
   Modality,
   ModelMessage,
+  PromptCacheOptions,
   ProviderKeys,
+  ResolvedPromptCache,
   RunAgentResumeItem,
   SchemaInput,
   StreamChunk,
@@ -228,6 +230,8 @@ export interface SessionDependencies {
   /** The log of the session. Default: the thread id. */
   logId: string
   lease?: LeaseOptions
+  /** The `promptCache` of `host.open()`. It overrides the harness value. */
+  promptCache?: PromptCacheOptions
   onClose: () => void
 }
 
@@ -264,6 +268,10 @@ function customEvent(
 const errorText = (error: unknown) =>
   error instanceof Error ? error.message : String(error)
 
+/** A `promptCache` option as an object. A string is the retention alone. */
+const cacheObject = (option: PromptCacheOptions | undefined) =>
+  typeof option === 'string' ? { retention: option, key: undefined } : option
+
 /** A short transcript note about an agent result, for the next turn. */
 function referenceNote(agent: string, result: unknown): string {
   const body =
@@ -435,11 +443,20 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   private readonly services: PluginServices
   private readonly media: SessionDependencies['media']
   private readonly mediaStore: MediaStore
+  /** The prompt cache of every chat turn of this session. */
+  private readonly promptCache: ResolvedPromptCache
 
   constructor(deps: SessionDependencies) {
     this.harness = deps.harness as THarness
     this.threadId = deps.threadId
     this.logId = deps.logId
+    // The session value wins over the harness value, field by field.
+    const own = cacheObject(deps.promptCache)
+    const shared = cacheObject(this.harness.promptCache)
+    this.promptCache = {
+      retention: own?.retention ?? shared?.retention ?? 'short',
+      key: own?.key ?? shared?.key ?? deps.threadId,
+    }
     this.persistence = deps.persistence
     this.inbox = deps.inbox
     this.media = deps.media
@@ -1756,6 +1773,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         }),
       ],
       keys: this.keys,
+      // A child uses its own threadId as the key, so only the retention goes down.
+      promptCache: this.promptCache.retention,
     } satisfies SubagentBinding
   }
 
@@ -2045,6 +2064,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             ...(this.harness.context !== undefined
               ? { context: this.harness.context }
               : {}),
+            promptCache: this.promptCache,
             threadId: this.threadId,
             runId: operation.id,
             ...(parentRunId ? { parentRunId } : {}),
diff --git a/packages/ai-harness/tests/first-party.test.ts b/packages/ai-harness/tests/first-party.test.ts
index 2718939d76..5b48556d6b 100644
--- a/packages/ai-harness/tests/first-party.test.ts
+++ b/packages/ai-harness/tests/first-party.test.ts
@@ -193,7 +193,15 @@ describe('compact and usage', () => {
         chunk.type === 'RUN_FINISHED'
           ? {
               ...chunk,
-              usage: [{ inputTokens: 10, outputTokens: 5, totalTokens: 15 }],
+              usage: [
+                {
+                  inputTokens: 10,
+                  outputTokens: 5,
+                  totalTokens: 15,
+                  cachedInputTokens: 6,
+                  cacheWriteInputTokens: 2,
+                },
+              ],
             }
           : chunk,
       )
@@ -211,7 +219,7 @@ describe('compact and usage', () => {
     expect(transcript).toHaveLength(2)
     expect(transcript[0]?.content).toContain('We planned a trip.')
     expect(await session.command('usage')).toBe(
-      '2 model calls, 20 input tokens, 10 output tokens, 30 total.',
+      '2 model calls, 20 input tokens (12 cache read, 4 cache write), 10 output tokens, 30 total.',
     )
     await host.close()
   })
diff --git a/packages/ai-harness/tests/prompt-cache.test.ts b/packages/ai-harness/tests/prompt-cache.test.ts
new file mode 100644
index 0000000000..7148fd4daf
--- /dev/null
+++ b/packages/ai-harness/tests/prompt-cache.test.ts
@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest'
+import { defineAgent } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '../src'
+import { mockAdapter, text } from './helpers'
+import type { PromptCacheOptions } from '@tanstack/ai'
+
+/** Run one chat turn and return the `promptCache` the adapter got. */
+async function cacheOfTurn(
+  harnessCache?: PromptCacheOptions,
+  sessionCache?: PromptCacheOptions,
+) {
+  const { adapter, calls } = mockAdapter([() => text('ok')])
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const session = await host.open(
+    defineHarness({
+      name: 'test/prompt-cache',
+      adapter,
+      ...(harnessCache ? { promptCache: harnessCache } : {}),
+    }),
+    { threadId: 't', ...(sessionCache ? { promptCache: sessionCache } : {}) },
+  )
+  await session.prompt('hi')
+  await host.close()
+  return calls[0].promptCache
+}
+
+describe('prompt cache', () => {
+  it('caches short, keyed by the threadId, by default', async () => {
+    expect(await cacheOfTurn()).toEqual({ retention: 'short', key: 't' })
+  })
+
+  it('uses the harness retention', async () => {
+    expect(await cacheOfTurn('long')).toEqual({ retention: 'long', key: 't' })
+  })
+
+  it('takes the session key and keeps the harness retention', async () => {
+    expect(await cacheOfTurn('long', { key: 'aff-1' })).toEqual({
+      retention: 'long',
+      key: 'aff-1',
+    })
+  })
+
+  it('turns caching off for one session with none', async () => {
+    expect(await cacheOfTurn('long', 'none')).toEqual({
+      retention: 'none',
+      key: 't',
+    })
+  })
+
+  it('gives an agent run the session retention', async () => {
+    const child = mockAdapter([() => text('drafted')])
+    const writer = defineAgent({
+      name: 'writer',
+      description: 'Writes text',
+      run: (ctx) => ctx.chat({ adapter: child.adapter }),
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/prompt-cache-agent',
+        adapter: mockAdapter([]).adapter,
+        agents: [writer],
+      }),
+      { threadId: 't', promptCache: 'none' },
+    )
+    await session.agents.writer.run()
+    // The agent keeps its own thread as the key.
+    expect(child.calls[0].promptCache).toEqual({
+      retention: 'none',
+      key: 't:writer',
+    })
+    await host.close()
+  })
+})

From d4c8a3ef323a6b007f186835651135ebeb636a38 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 10:46:26 +0200
Subject: [PATCH 157/286] feat(ai-openrouter): add automatic cache markers for
 Claude models

With chat({ promptCache }), the cache key becomes sessionId on every model, so one session goes to one provider. anthropic/* models also get cache markers on the system message, the last function tool, and the last message. A manual marker or a caller sessionId wins.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-openrouter/src/adapters/text.ts   |   5 +-
 packages/ai-openrouter/src/prompt-cache.ts    | 120 +++++++
 .../ai-openrouter/tests/prompt-cache.test.ts  | 327 ++++++++++++++++++
 3 files changed, 451 insertions(+), 1 deletion(-)
 create mode 100644 packages/ai-openrouter/src/prompt-cache.ts
 create mode 100644 packages/ai-openrouter/tests/prompt-cache.test.ts

diff --git a/packages/ai-openrouter/src/adapters/text.ts b/packages/ai-openrouter/src/adapters/text.ts
index 9debe41cea..d21365d086 100644
--- a/packages/ai-openrouter/src/adapters/text.ts
+++ b/packages/ai-openrouter/src/adapters/text.ts
@@ -18,6 +18,7 @@ import { openRouterSupportsCombinedToolsAndSchema } from '../internal/combined-t
 import { OPENROUTER_MODEL_INPUT_MODALITIES } from '../model-meta'
 import { OPENROUTER_MODEL_REASONING } from '../model-reasoning'
 import { openRouterEffort } from '../internal/reasoning'
+import { addPromptCacheMarkers } from '../prompt-cache'
 import { convertToolsToProviderFormat } from '../tools'
 import { getOpenRouterApiKeyFromEnv } from '../utils'
 import { buildOpenRouterUsage } from '../usage'
@@ -1345,7 +1346,9 @@ export class OpenRouterTextAdapter<
         },
       }),
     }
-    return request
+    return options.promptCache
+      ? addPromptCacheMarkers(request, options.promptCache)
+      : request
   }
 
   /**
diff --git a/packages/ai-openrouter/src/prompt-cache.ts b/packages/ai-openrouter/src/prompt-cache.ts
new file mode 100644
index 0000000000..f47c483e3c
--- /dev/null
+++ b/packages/ai-openrouter/src/prompt-cache.ts
@@ -0,0 +1,120 @@
+import type { ResolvedPromptCache } from '@tanstack/ai'
+import type {
+  ChatContentCacheControl,
+  ChatMessages,
+  ChatRequest,
+} from '@openrouter/sdk/models'
+
+type OpenRouterChatRequest = Omit<ChatRequest, 'stream'>
+
+/** True when one of the items already has a cache marker. */
+function hasMarker(items: ReadonlyArray<object> | undefined) {
+  return items?.some((item) => 'cacheControl' in item) ?? false
+}
+
+/**
+ * Put the marker on the last text block that is not empty. A string becomes
+ * one text block. An empty string does not change.
+ */
+function markLastText<TPart extends { type: string }>(
+  content: string | Array<TPart>,
+  cacheControl: ChatContentCacheControl,
+) {
+  if (typeof content === 'string') {
+    return content === ''
+      ? content
+      : [{ type: 'text' as const, text: content, cacheControl }]
+  }
+  const index = content.findLastIndex(
+    (part) => part.type === 'text' && 'text' in part && part.text !== '',
+  )
+  return content.map((part, i) =>
+    i === index ? { ...part, cacheControl } : part,
+  )
+}
+
+/** Put the marker on the last text block of one message. */
+function markMessage(
+  message: ChatMessages,
+  cacheControl: ChatContentCacheControl,
+) {
+  switch (message.role) {
+    // A system message has its own case: it takes only text blocks.
+    case 'system':
+      return {
+        ...message,
+        content: markLastText(message.content, cacheControl),
+      }
+    case 'user':
+    case 'tool':
+      return {
+        ...message,
+        content: markLastText(message.content, cacheControl),
+      }
+    case 'assistant':
+      // The converter gives an assistant a string, or null when the message
+      // has only tool calls. Null has no text to mark.
+      return typeof message.content === 'string'
+        ? { ...message, content: markLastText(message.content, cacheControl) }
+        : message
+    case 'developer':
+      // The converter never makes a developer message.
+      return message
+  }
+}
+
+/**
+ * Add the automatic prompt cache fields for `chat({ promptCache })` to an
+ * OpenRouter chat request.
+ *
+ * - The cache key becomes `sessionId` on every model, so OpenRouter sends the
+ *   requests of one session to the same provider. A `sessionId` from
+ *   `modelOptions` wins.
+ * - Only `anthropic/*` models get cache markers, and only when the request
+ *   has no manual marker (system prompt, tool, or content block). Then the
+ *   system message, the last function tool, and the last message each get a
+ *   marker on their last text block.
+ *
+ * `'none'` returns the request with no change. `'long'` asks for the 1-hour
+ * TTL. The function returns a new request and does not change `request`.
+ */
+export function addPromptCacheMarkers(
+  request: OpenRouterChatRequest,
+  promptCache: ResolvedPromptCache,
+) {
+  if (promptCache.retention === 'none') return request
+  // OpenRouter accepts a session id of at most 256 characters.
+  const key =
+    promptCache.key && Array.from(promptCache.key).slice(0, 256).join('')
+  const sessionId = request.sessionId ?? key
+  const withSession = { ...request, ...(sessionId && { sessionId }) }
+
+  const isClaude = request.model?.startsWith('anthropic/') ?? false
+  const hasManualMarker =
+    hasMarker(request.tools) ||
+    request.messages.some(
+      (message) => Array.isArray(message.content) && hasMarker(message.content),
+    )
+  if (!isClaude || hasManualMarker) return withSession
+
+  const cacheControl: ChatContentCacheControl =
+    promptCache.retention === 'long'
+      ? { type: 'ephemeral', ttl: '1h' }
+      : { type: 'ephemeral' }
+  const lastMessage = request.messages.length - 1
+  const lastTool =
+    request.tools?.findLastIndex((tool) => tool.type === 'function') ?? -1
+  return {
+    ...withSession,
+    messages: request.messages.map((message, i) =>
+      message.role === 'system' || i === lastMessage
+        ? markMessage(message, cacheControl)
+        : message,
+    ),
+    ...(request.tools && {
+      tools: request.tools.map((tool, i) =>
+        i === lastTool ? { ...tool, cacheControl } : tool,
+      ),
+    }),
+  }
+}
diff --git a/packages/ai-openrouter/tests/prompt-cache.test.ts b/packages/ai-openrouter/tests/prompt-cache.test.ts
new file mode 100644
index 0000000000..acb7027fc8
--- /dev/null
+++ b/packages/ai-openrouter/tests/prompt-cache.test.ts
@@ -0,0 +1,327 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { ChatRequest$outboundSchema } from '@openrouter/sdk/models'
+import { createOpenRouterText } from '../src/adapters/text'
+import { webSearchTool } from '../src/tools'
+import type { ChatRequest } from '@openrouter/sdk/models'
+import type {
+  ModelMessage,
+  ResolvedPromptCache,
+  TextOptions,
+  Tool,
+} from '@tanstack/ai'
+
+// The SDK is the network boundary. The tests read the request it gets.
+const mockSend = vi.hoisted(() =>
+  vi.fn<(params: { chatRequest: ChatRequest }) => Promise<Array<never>>>(),
+)
+
+vi.mock('@openrouter/sdk', () => {
+  function OpenRouter(this: { chat: { send: typeof mockSend } }) {
+    this.chat = { send: mockSend }
+  }
+  return { OpenRouter }
+})
+
+const testLogger = resolveDebugOption(false)
+
+const weather: Tool = { name: 'get_weather', description: 'Get the weather' }
+const search: Tool = { name: 'search_docs', description: 'Search the docs' }
+
+const conversation: Array<ModelMessage> = [
+  { role: 'user', content: 'Weather in Berlin?' },
+  { role: 'assistant', content: 'Let me check.' },
+  { role: 'user', content: 'And Paris?' },
+]
+
+const toolCallTurn: ModelMessage = {
+  role: 'assistant',
+  content: null,
+  toolCalls: [
+    {
+      id: 'call-1',
+      type: 'function',
+      function: { name: 'get_weather', arguments: '{}' },
+    },
+  ],
+}
+
+const short: ResolvedPromptCache = { retention: 'short', key: 'thread-1' }
+
+/** Run one chatStream call and return the request the SDK got. */
+async function sentRequest({
+  model = 'anthropic/claude-sonnet-4.5',
+  messages = conversation,
+  systemPrompts = ['Be brief.'],
+  tools = [weather, search],
+  ...rest
+}: {
+  model?: 'anthropic/claude-sonnet-4.5' | 'openai/gpt-4o-mini'
+  messages?: Array<ModelMessage>
+  systemPrompts?: TextOptions['systemPrompts']
+  tools?: TextOptions['tools']
+  promptCache?: ResolvedPromptCache
+  modelOptions?: { sessionId: string }
+}) {
+  mockSend.mockResolvedValue([])
+  const adapter = createOpenRouterText(model, 'test-key')
+  for await (const _ of adapter.chatStream({
+    ...rest,
+    model,
+    messages,
+    systemPrompts,
+    tools,
+    logger: testLogger,
+  })) {
+    // drain
+  }
+  return mockSend.mock.calls[0]![0].chatRequest
+}
+
+function toolMarkers(request: ChatRequest) {
+  return request.tools?.map((tool) =>
+    'cacheControl' in tool ? tool.cacheControl : undefined,
+  )
+}
+
+describe('OpenRouter automatic prompt cache', () => {
+  beforeEach(() => {
+    mockSend.mockReset()
+  })
+
+  it.each([
+    ['short', { type: 'ephemeral' }],
+    ['long', { type: 'ephemeral', ttl: '1h' }],
+  ] as const)(
+    'marks the system message, the last tool, and the last message for a %s retention',
+    async (retention, marker) => {
+      const request = await sentRequest({
+        promptCache: { retention, key: 'thread-1' },
+      })
+
+      expect(request.messages).toEqual([
+        {
+          role: 'system',
+          content: [{ type: 'text', text: 'Be brief.', cacheControl: marker }],
+        },
+        { role: 'user', content: 'Weather in Berlin?' },
+        { role: 'assistant', content: 'Let me check.' },
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'And Paris?', cacheControl: marker }],
+        },
+      ])
+      expect(toolMarkers(request)).toEqual([undefined, marker])
+      expect(request.sessionId).toBe('thread-1')
+
+      // The SDK keeps the markers when it writes the snake_case wire body.
+      expect(ChatRequest$outboundSchema.parse(request)).toMatchObject({
+        messages: [
+          { role: 'system', content: [{ cache_control: marker }] },
+          {},
+          {},
+          { role: 'user', content: [{ cache_control: marker }] },
+        ],
+        tools: [{}, { cache_control: marker }],
+        session_id: 'thread-1',
+      })
+    },
+  )
+
+  it.each([
+    ['none', { retention: 'none', key: 'thread-1' }],
+    ['absent', undefined],
+  ] as const)(
+    'sends the request with no cache fields when promptCache is %s',
+    async (_label, promptCache) => {
+      const request = await sentRequest({ promptCache })
+
+      expect(request.messages).toEqual([
+        { role: 'system', content: 'Be brief.' },
+        { role: 'user', content: 'Weather in Berlin?' },
+        { role: 'assistant', content: 'Let me check.' },
+        { role: 'user', content: 'And Paris?' },
+      ])
+      expect(toolMarkers(request)).toEqual([undefined, undefined])
+      expect(request).not.toHaveProperty('sessionId')
+    },
+  )
+
+  it('sets only sessionId for a model that is not anthropic/*', async () => {
+    const request = await sentRequest({
+      model: 'openai/gpt-4o-mini',
+      promptCache: short,
+    })
+
+    expect(request.sessionId).toBe('thread-1')
+    expect(request.messages[0]).toEqual({
+      role: 'system',
+      content: 'Be brief.',
+    })
+    expect(request.messages[3]).toEqual({ role: 'user', content: 'And Paris?' })
+    expect(toolMarkers(request)).toEqual([undefined, undefined])
+  })
+
+  it('adds no marker when a system prompt has a manual cache_control', async () => {
+    const request = await sentRequest({
+      promptCache: short,
+      systemPrompts: [
+        {
+          content: 'Be brief.',
+          metadata: { cache_control: { type: 'ephemeral', ttl: '1h' } },
+        },
+      ],
+    })
+
+    expect(request.messages[0]).toEqual({
+      role: 'system',
+      content: [
+        {
+          type: 'text',
+          text: 'Be brief.',
+          cacheControl: { type: 'ephemeral', ttl: '1h' },
+        },
+      ],
+    })
+    expect(request.messages[3]).toEqual({ role: 'user', content: 'And Paris?' })
+    expect(toolMarkers(request)).toEqual([undefined, undefined])
+    expect(request.sessionId).toBe('thread-1')
+  })
+
+  it('adds no marker when a tool has a manual cacheControl', async () => {
+    const request = await sentRequest({
+      promptCache: short,
+      tools: [
+        { ...weather, metadata: { cacheControl: { type: 'ephemeral' } } },
+        search,
+      ],
+    })
+
+    expect(toolMarkers(request)).toEqual([{ type: 'ephemeral' }, undefined])
+    expect(request.messages[0]).toEqual({
+      role: 'system',
+      content: 'Be brief.',
+    })
+    expect(request.messages[3]).toEqual({ role: 'user', content: 'And Paris?' })
+  })
+
+  it('keeps the sessionId that the caller sets in modelOptions', async () => {
+    const request = await sentRequest({
+      promptCache: short,
+      modelOptions: { sessionId: 'caller-session' },
+    })
+
+    expect(request.sessionId).toBe('caller-session')
+  })
+
+  it('sends no sessionId when there is no cache key', async () => {
+    const request = await sentRequest({ promptCache: { retention: 'short' } })
+
+    expect(request).not.toHaveProperty('sessionId')
+    expect(request.messages[3]).toEqual({
+      role: 'user',
+      content: [
+        {
+          type: 'text',
+          text: 'And Paris?',
+          cacheControl: { type: 'ephemeral' },
+        },
+      ],
+    })
+  })
+
+  it('cuts a long cache key to the 256 characters OpenRouter accepts', async () => {
+    const request = await sentRequest({
+      promptCache: { retention: 'short', key: 'k'.repeat(300) },
+    })
+
+    expect(request.sessionId).toBe('k'.repeat(256))
+  })
+
+  it('marks a tool result when it is the last message', async () => {
+    const request = await sentRequest({
+      promptCache: short,
+      messages: [
+        { role: 'user', content: 'Weather in Berlin?' },
+        toolCallTurn,
+        { role: 'tool', content: 'Sunny', toolCallId: 'call-1' },
+      ],
+    })
+
+    expect(request.messages[3]).toEqual({
+      role: 'tool',
+      toolCallId: 'call-1',
+      content: [
+        { type: 'text', text: 'Sunny', cacheControl: { type: 'ephemeral' } },
+      ],
+    })
+  })
+
+  it('marks the text block of a last message that also has an image', async () => {
+    const request = await sentRequest({
+      promptCache: short,
+      messages: [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', content: 'What is this?' },
+            {
+              type: 'image',
+              source: { type: 'url', value: 'https://example.com/a.png' },
+            },
+          ],
+        },
+      ],
+    })
+
+    expect(request.messages[1]).toEqual({
+      role: 'user',
+      content: [
+        {
+          type: 'text',
+          text: 'What is this?',
+          cacheControl: { type: 'ephemeral' },
+        },
+        {
+          type: 'image_url',
+          imageUrl: { url: 'https://example.com/a.png', detail: 'auto' },
+        },
+      ],
+    })
+  })
+
+  const assistantLasts: Array<[string, ModelMessage, string | null]> = [
+    ['only tool calls', toolCallTurn, null],
+    ['empty text', { role: 'assistant', content: '' }, ''],
+  ]
+  it.each(assistantLasts)(
+    'does not mark a last assistant message with %s',
+    async (_label, last, content) => {
+      const request = await sentRequest({
+        promptCache: short,
+        messages: [{ role: 'user', content: 'hi' }, last],
+      })
+
+      expect(request.messages[2]).toMatchObject({ role: 'assistant', content })
+      expect(request.messages[0]).toEqual({
+        role: 'system',
+        content: [
+          {
+            type: 'text',
+            text: 'Be brief.',
+            cacheControl: { type: 'ephemeral' },
+          },
+        ],
+      })
+    },
+  )
+
+  it('marks the last function tool when a server tool comes after it', async () => {
+    const request = await sentRequest({
+      promptCache: short,
+      tools: [weather, webSearchTool()],
+    })
+
+    expect(toolMarkers(request)).toEqual([{ type: 'ephemeral' }, undefined])
+  })
+})

From 574daab1e62e23131f1a3f3c3c681b436c3f4a10 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 10:47:19 +0200
Subject: [PATCH 158/286] feat(ai-anthropic): add automatic prompt cache
 markers

With chat({ promptCache }), Claude requests get cache markers on the last tool, the last block of the last user message, and the system blocks from the end, with at most 4 markers. 'long' asks for the 1-hour TTL. A manual cache_control anywhere in the request turns the automatic markers off. ANTHROPIC_CACHEABLE_BLOCK_TYPES lists the block types that can take the last marker.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-anthropic/src/adapters/text.ts    |   4 +-
 packages/ai-anthropic/src/prompt-cache.ts     | 157 +++++++
 .../tests/anthropic-adapter.test.ts           |   6 +
 .../ai-anthropic/tests/prompt-cache.test.ts   | 437 ++++++++++++++++++
 4 files changed, 603 insertions(+), 1 deletion(-)
 create mode 100644 packages/ai-anthropic/src/prompt-cache.ts
 create mode 100644 packages/ai-anthropic/tests/prompt-cache.test.ts

diff --git a/packages/ai-anthropic/src/adapters/text.ts b/packages/ai-anthropic/src/adapters/text.ts
index 7748b86e54..46d808c0a4 100644
--- a/packages/ai-anthropic/src/adapters/text.ts
+++ b/packages/ai-anthropic/src/adapters/text.ts
@@ -16,6 +16,7 @@ import {
   readCodeExecutionSkills,
 } from '../tools/code-execution-tool'
 import { validateTextProviderOptions } from '../text/text-provider-options'
+import { applyAnthropicPromptCache } from '../prompt-cache'
 import { anthropicThinking } from '../text/reasoning'
 import { ANTHROPIC_MODEL_REASONING } from '../model-reasoning'
 import type { AnthropicModelReasoningByName } from '../model-reasoning'
@@ -715,7 +716,8 @@ export class AnthropicTextAdapter<
       ...(outputConfig ?? {}),
     }
     validateTextProviderOptions(requestParams)
-    return requestParams
+    // Last step: the merged messages decide which message is last.
+    return applyAnthropicPromptCache(requestParams, options.promptCache)
   }
 
   /**
diff --git a/packages/ai-anthropic/src/prompt-cache.ts b/packages/ai-anthropic/src/prompt-cache.ts
new file mode 100644
index 0000000000..9e9efa3942
--- /dev/null
+++ b/packages/ai-anthropic/src/prompt-cache.ts
@@ -0,0 +1,157 @@
+import type { ResolvedPromptCache } from '@tanstack/ai'
+import type {
+  BetaCacheControlEphemeral,
+  BetaContentBlockParam,
+  BetaMessageParam,
+} from '@anthropic-ai/sdk/resources/beta/messages'
+import type { TextBlockParam } from '@anthropic-ai/sdk/resources/messages'
+import type { InternalTextProviderOptions } from './text/text-provider-options'
+
+/**
+ * The block types that can take the automatic cache marker when they are
+ * the last block of the last user message.
+ * Later work adds the `tool_addition` and `tool_removal` blocks here.
+ */
+export const ANTHROPIC_CACHEABLE_BLOCK_TYPES: ReadonlySet<string> = new Set([
+  'text',
+  'image',
+  'document',
+  'tool_result',
+])
+
+// Anthropic rejects a request with more than 4 cache markers.
+const MAX_CACHE_MARKERS = 4
+
+// `null` and `undefined` are not markers: custom tools always send
+// `cache_control: null` when the caller set none.
+function hasCacheControl(item: object) {
+  return 'cache_control' in item && item.cache_control != null
+}
+
+function blockHasCacheControl(block: BetaContentBlockParam) {
+  // A marker inside a tool result also counts toward the limit of 4.
+  const isMarkedToolResult =
+    block.type === 'tool_result' &&
+    Array.isArray(block.content) &&
+    block.content.some(hasCacheControl)
+  return hasCacheControl(block) || isMarkedToolResult
+}
+
+function hasManualCacheControl(request: InternalTextProviderOptions) {
+  const systemBlocks = Array.isArray(request.system) ? request.system : []
+  const tools = request.tools ?? []
+  const hasMessageMarker = request.messages.some(
+    (message) =>
+      Array.isArray(message.content) &&
+      message.content.some(blockHasCacheControl),
+  )
+  return (
+    request.cache_control != null ||
+    systemBlocks.some(hasCacheControl) ||
+    tools.some(hasCacheControl) ||
+    hasMessageMarker
+  )
+}
+
+function withCacheControl<T extends object>(
+  item: T,
+  cacheControl: BetaCacheControlEphemeral,
+) {
+  return { ...item, cache_control: cacheControl }
+}
+
+/**
+ * The messages with a marker on the last block of the last message. Returns
+ * `null` when that message is not from the user or its last block cannot
+ * take a marker.
+ */
+function markLastUserMessage(
+  messages: Array<BetaMessageParam>,
+  cacheControl: BetaCacheControlEphemeral,
+) {
+  const last = messages.at(-1)
+  if (last === undefined || last.role !== 'user') return null
+  const blocks: Array<BetaContentBlockParam> =
+    typeof last.content !== 'string'
+      ? last.content
+      : last.content
+        ? [{ type: 'text', text: last.content }]
+        : []
+  const lastBlock = blocks.at(-1)
+  if (
+    lastBlock === undefined ||
+    !ANTHROPIC_CACHEABLE_BLOCK_TYPES.has(lastBlock.type)
+  ) {
+    return null
+  }
+  return [
+    ...messages.slice(0, -1),
+    {
+      ...last,
+      content: [
+        ...blocks.slice(0, -1),
+        withCacheControl(lastBlock, cacheControl),
+      ],
+    },
+  ]
+}
+
+/**
+ * Adds Anthropic cache markers to a Messages request, so a later request
+ * with the same start reads it from the cache.
+ *
+ * It adds nothing when `promptCache` is absent or `'none'`, or when the
+ * request already has a marker of the caller's (on a system block, a message
+ * block, a tool, or the top-level `cache_control`). Otherwise it marks, with
+ * at most 4 markers:
+ * 1. the last tool,
+ * 2. the last block of the last message, when it is a user message and the
+ *    block type is in {@link ANTHROPIC_CACHEABLE_BLOCK_TYPES},
+ * 3. the system blocks from the end, with the markers that are left.
+ *
+ * It does not change the request it gets. It returns a new request, or the
+ * same request when it adds nothing.
+ *
+ * @param request - The finished Messages request.
+ * @param promptCache - The `promptCache` that `chat()` resolved.
+ *
+ * @example
+ * const body = applyAnthropicPromptCache(request, { retention: 'short' })
+ */
+export function applyAnthropicPromptCache(
+  request: InternalTextProviderOptions,
+  promptCache: ResolvedPromptCache | undefined,
+) {
+  const retention = promptCache?.retention ?? 'none'
+  if (retention === 'none' || hasManualCacheControl(request)) return request
+
+  const cacheControl: BetaCacheControlEphemeral =
+    retention === 'long'
+      ? { type: 'ephemeral', ttl: '1h' }
+      : { type: 'ephemeral' }
+
+  const tools = request.tools?.map((tool, index, all) =>
+    index === all.length - 1 ? withCacheControl(tool, cacheControl) : tool,
+  )
+  const messages = markLastUserMessage(request.messages, cacheControl)
+
+  const usedMarkers = (tools?.length ? 1 : 0) + (messages ? 1 : 0)
+  const systemBlocks: Array<TextBlockParam> =
+    typeof request.system !== 'string'
+      ? (request.system ?? [])
+      : request.system
+        ? [{ type: 'text', text: request.system }]
+        : []
+  const firstMarkedSystem =
+    systemBlocks.length - (MAX_CACHE_MARKERS - usedMarkers)
+  const system = systemBlocks.map((block, index) =>
+    index >= firstMarkedSystem ? withCacheControl(block, cacheControl) : block,
+  )
+
+  return {
+    ...request,
+    ...(tools && { tools }),
+    ...(system.length > 0 && { system }),
+    ...(messages && { messages }),
+  }
+}
diff --git a/packages/ai-anthropic/tests/anthropic-adapter.test.ts b/packages/ai-anthropic/tests/anthropic-adapter.test.ts
index 63fc322ef8..aa5c2c9039 100644
--- a/packages/ai-anthropic/tests/anthropic-adapter.test.ts
+++ b/packages/ai-anthropic/tests/anthropic-adapter.test.ts
@@ -237,6 +237,7 @@ describe('Anthropic adapter option mapping', () => {
     const chunks: AdapterYieldChunk[] = []
     for await (const chunk of chat({
       adapter,
+      promptCache: 'none',
       messages: [{ role: 'user', content: 'Hi' }],
       systemPrompts: ['You are a helpful assistant.', 'Be concise.'],
     })) {
@@ -343,6 +344,7 @@ describe('Anthropic adapter option mapping', () => {
 
     for await (const _ of chat({
       adapter,
+      promptCache: 'none',
       messages: [{ role: 'user', content: 'Hi' }],
       systemPrompts: ['real system prompt'],
       modelOptions: {
@@ -431,6 +433,7 @@ describe('Anthropic adapter option mapping', () => {
     const chunks: AdapterYieldChunk[] = []
     for await (const chunk of chat({
       adapter,
+      promptCache: 'none',
       messages: [
         { role: 'user', content: 'What is the forecast?' },
         {
@@ -1030,6 +1033,7 @@ describe('Anthropic adapter option mapping', () => {
     const chunks: AdapterYieldChunk[] = []
     for await (const chunk of chat({
       adapter,
+      promptCache: 'none',
       messages: [
         { role: 'user', content: 'What is the weather in Berlin?' },
         {
@@ -1343,6 +1347,7 @@ describe('Anthropic adapter option mapping', () => {
     const chunks: AdapterYieldChunk[] = []
     for await (const chunk of chat({
       adapter,
+      promptCache: 'none',
       messages: [
         { role: 'user', content: 'Weather in Berlin and Paris?' },
         {
@@ -1571,6 +1576,7 @@ describe('Anthropic adapter option mapping', () => {
     const chunks: AdapterYieldChunk[] = []
     for await (const chunk of chat({
       adapter,
+      promptCache: 'none',
       messages: [
         { role: 'user', content: 'Hello' },
         { role: 'assistant', content: '' }, // Empty assistant from failed request
diff --git a/packages/ai-anthropic/tests/prompt-cache.test.ts b/packages/ai-anthropic/tests/prompt-cache.test.ts
new file mode 100644
index 0000000000..25d6f4638f
--- /dev/null
+++ b/packages/ai-anthropic/tests/prompt-cache.test.ts
@@ -0,0 +1,437 @@
+import { describe, expect, it, vi } from 'vitest'
+import { chat } from '@tanstack/ai'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { createAnthropicChatWithClient } from '../src'
+import { customTool } from '../src/tools/custom-tool'
+import type { JSONSchema, ModelMessage, TextOptions, Tool } from '@tanstack/ai'
+import type { MessageCreateParams } from '@anthropic-ai/sdk/resources/beta/messages'
+import type { AnthropicTextProviderOptions } from '../src/adapters/text'
+
+const MODEL = 'claude-opus-4-1'
+const logger = resolveDebugOption(false)
+
+const SHORT = { type: 'ephemeral' }
+const LONG = { type: 'ephemeral', ttl: '1h' }
+
+const wordSchema: JSONSchema = {
+  type: 'object',
+  properties: { word: { type: 'string' } },
+}
+const lookup: Tool = {
+  name: 'lookup',
+  description: 'Look up a word',
+  inputSchema: wordSchema,
+}
+const search: Tool = {
+  name: 'search',
+  description: 'Search the web',
+  inputSchema: { type: 'object', properties: { query: { type: 'string' } } },
+}
+
+const userHi: ModelMessage = { role: 'user', content: 'hi' }
+
+/** A user turn, an assistant tool call, and the tool result for it. */
+const toolTurn: Array<ModelMessage> = [
+  { role: 'user', content: 'Weather in Paris?' },
+  {
+    role: 'assistant',
+    content: '',
+    toolCalls: [
+      {
+        id: 'call_1',
+        type: 'function',
+        function: { name: 'lookup', arguments: '{"word":"Paris"}' },
+      },
+    ],
+  },
+  { role: 'tool', toolCallId: 'call_1', content: '{"temp":20}' },
+]
+
+function textStream() {
+  return (async function* () {
+    yield {
+      type: 'content_block_start',
+      index: 0,
+      content_block: { type: 'text', text: '' },
+    }
+    yield {
+      type: 'content_block_delta',
+      index: 0,
+      delta: { type: 'text_delta', text: 'ok' },
+    }
+    yield { type: 'content_block_stop', index: 0 }
+    yield {
+      type: 'message_delta',
+      delta: { stop_reason: 'end_turn' },
+      usage: { output_tokens: 1 },
+    }
+    yield { type: 'message_stop' }
+  })()
+}
+
+/** An adapter whose Messages client records each request body. */
+function createAdapter(response: unknown) {
+  const create = vi.fn((_body: MessageCreateParams) => response)
+  const adapter = createAnthropicChatWithClient(MODEL, {
+    beta: { messages: { create } },
+  })
+  return { adapter, create }
+}
+
+type SendOptions = Omit<
+  TextOptions<AnthropicTextProviderOptions>,
+  'model' | 'logger'
+>
+
+/** Sends one streaming request and returns the body on the wire. */
+async function send(options: SendOptions) {
+  const { adapter, create } = createAdapter(textStream())
+  for await (const _chunk of adapter.chatStream({
+    ...options,
+    model: MODEL,
+    logger,
+  })) {
+    // Drain the stream.
+  }
+  return create.mock.calls[0]![0]
+}
+
+/** Counts every cache marker in the body, at any depth. */
+function countMarkers(body: MessageCreateParams) {
+  return JSON.stringify(body).match(/"cache_control":\{/g)?.length ?? 0
+}
+
+describe('Anthropic automatic prompt cache markers', () => {
+  it.each([
+    ['absent', undefined],
+    ['none', { retention: 'none' } as const],
+  ])('adds no markers when promptCache is %s', async (_name, promptCache) => {
+    const body = await send({
+      messages: [userHi],
+      systemPrompts: ['Be brief.'],
+      tools: [lookup],
+      ...(promptCache && { promptCache }),
+    })
+    expect(countMarkers(body)).toBe(0)
+    expect(body.messages).toEqual([{ role: 'user', content: 'hi' }])
+  })
+
+  it('short: marks the last tool, the last system block, and the last user block', async () => {
+    const body = await send({
+      messages: [userHi],
+      systemPrompts: ['Be brief.'],
+      tools: [lookup, search],
+      promptCache: { retention: 'short' },
+    })
+    expect(body.tools?.[0]).toMatchObject({
+      name: 'lookup',
+      cache_control: null,
+    })
+    expect(body.tools?.[1]).toMatchObject({
+      name: 'search',
+      cache_control: SHORT,
+    })
+    expect(body.system).toEqual([
+      { type: 'text', text: 'Be brief.', cache_control: SHORT },
+    ])
+    // A string content becomes one marked text block.
+    expect(body.messages).toEqual([
+      {
+        role: 'user',
+        content: [{ type: 'text', text: 'hi', cache_control: SHORT }],
+      },
+    ])
+    expect(countMarkers(body)).toBe(3)
+  })
+
+  it('long: every marker has a 1h ttl', async () => {
+    const body = await send({
+      messages: [userHi],
+      systemPrompts: ['Be brief.'],
+      tools: [lookup],
+      promptCache: { retention: 'long' },
+    })
+    expect(body.tools?.[0]).toMatchObject({ cache_control: LONG })
+    expect(body.system).toEqual([
+      { type: 'text', text: 'Be brief.', cache_control: LONG },
+    ])
+    expect(body.messages).toEqual([
+      {
+        role: 'user',
+        content: [{ type: 'text', text: 'hi', cache_control: LONG }],
+      },
+    ])
+  })
+
+  it.each<[string, Array<ModelMessage>, unknown]>([
+    [
+      'text',
+      [{ role: 'user', content: [{ type: 'text', content: 'hi' }] }],
+      { type: 'text', text: 'hi', cache_control: SHORT },
+    ],
+    [
+      'image',
+      [
+        {
+          role: 'user',
+          content: [
+            {
+              type: 'image',
+              source: { type: 'url', value: 'https://example.com/a.png' },
+            },
+          ],
+        },
+      ],
+      {
+        type: 'image',
+        source: { type: 'url', url: 'https://example.com/a.png' },
+        cache_control: SHORT,
+      },
+    ],
+    [
+      'document',
+      [
+        {
+          role: 'user',
+          content: [
+            {
+              type: 'document',
+              source: { type: 'url', value: 'https://example.com/a.pdf' },
+            },
+          ],
+        },
+      ],
+      {
+        type: 'document',
+        source: { type: 'url', url: 'https://example.com/a.pdf' },
+        cache_control: SHORT,
+      },
+    ],
+    [
+      'tool_result',
+      toolTurn,
+      {
+        type: 'tool_result',
+        tool_use_id: 'call_1',
+        content: '{"temp":20}',
+        cache_control: SHORT,
+      },
+    ],
+  ])(
+    'marks a %s block at the end of the last user message',
+    async (_type, messages, lastBlock) => {
+      const body = await send({
+        messages,
+        promptCache: { retention: 'short' },
+      })
+      const last = body.messages.at(-1)
+      expect(last?.role).toBe('user')
+      expect(last?.content.at(-1)).toEqual(lastBlock)
+    },
+  )
+
+  it('does not mark an assistant last message', async () => {
+    const body = await send({
+      messages: [userHi, { role: 'assistant', content: 'hello' }],
+      systemPrompts: ['Be brief.'],
+      promptCache: { retention: 'short' },
+    })
+    expect(body.messages).toEqual([
+      { role: 'user', content: 'hi' },
+      { role: 'assistant', content: [{ type: 'text', text: 'hello' }] },
+    ])
+    // Only the system block takes a marker.
+    expect(countMarkers(body)).toBe(1)
+  })
+
+  it('does not mark an empty user string', async () => {
+    const body = await send({
+      messages: [{ role: 'user', content: '' }],
+      promptCache: { retention: 'short' },
+    })
+    expect(body.messages).toEqual([{ role: 'user', content: '' }])
+  })
+
+  it('uses at most 4 markers: system markers go on the last blocks', async () => {
+    const body = await send({
+      messages: [userHi],
+      systemPrompts: ['s1', 's2', 's3', 's4', 's5'],
+      tools: [lookup],
+      promptCache: { retention: 'short' },
+    })
+    expect(body.system).toEqual([
+      { type: 'text', text: 's1' },
+      { type: 'text', text: 's2' },
+      { type: 'text', text: 's3' },
+      { type: 'text', text: 's4', cache_control: SHORT },
+      { type: 'text', text: 's5', cache_control: SHORT },
+    ])
+    expect(countMarkers(body)).toBe(4)
+  })
+
+  it.each<[string, SendOptions]>([
+    [
+      'system prompt metadata',
+      {
+        messages: [userHi],
+        systemPrompts: [
+          { content: 's1', metadata: { cache_control: { type: 'ephemeral' } } },
+          's2',
+        ],
+        tools: [lookup],
+      },
+    ],
+    [
+      'content part metadata',
+      {
+        messages: [
+          {
+            role: 'user',
+            content: [
+              {
+                type: 'text',
+                content: 'hi',
+                metadata: { cache_control: { type: 'ephemeral' } },
+              },
+            ],
+          },
+        ],
+        systemPrompts: ['Be brief.'],
+        tools: [lookup],
+      },
+    ],
+    [
+      'a content part inside a tool result',
+      {
+        messages: [
+          ...toolTurn.slice(0, 2),
+          {
+            role: 'tool',
+            toolCallId: 'call_1',
+            content: [
+              {
+                type: 'text',
+                content: '{"temp":20}',
+                metadata: { cache_control: { type: 'ephemeral' } },
+              },
+            ],
+          },
+          userHi,
+        ],
+        systemPrompts: ['Be brief.'],
+        tools: [lookup],
+      },
+    ],
+    [
+      'tool metadata',
+      {
+        messages: [userHi],
+        systemPrompts: ['Be brief.'],
+        tools: [
+          {
+            ...lookup,
+            metadata: { cacheControl: { type: 'ephemeral', ttl: '5m' } },
+          },
+          search,
+        ],
+      },
+    ],
+    [
+      'top-level modelOptions.cache_control',
+      {
+        messages: [userHi],
+        systemPrompts: ['Be brief.'],
+        tools: [lookup],
+        modelOptions: { cache_control: { type: 'ephemeral' } },
+      },
+    ],
+  ])('a manual marker on %s wins: adds no markers', async (_name, options) => {
+    const body = await send({ ...options, promptCache: { retention: 'short' } })
+    expect(countMarkers(body)).toBe(1)
+  })
+
+  it('a custom tool with no cache metadata does not block automatic markers', async () => {
+    const body = await send({
+      messages: [userHi],
+      tools: [customTool('lookup', 'Look up a word', wordSchema)],
+      promptCache: { retention: 'short' },
+    })
+    expect(body.tools?.[0]).toMatchObject({
+      name: 'lookup',
+      cache_control: SHORT,
+    })
+    expect(countMarkers(body)).toBe(2)
+  })
+
+  it('marks the last block of a tool result merged with a user text', async () => {
+    const body = await send({
+      messages: [...toolTurn, { role: 'user', content: 'Thanks' }],
+      promptCache: { retention: 'short' },
+    })
+    expect(body.messages.at(-1)).toEqual({
+      role: 'user',
+      content: [
+        { type: 'tool_result', tool_use_id: 'call_1', content: '{"temp":20}' },
+        { type: 'text', text: 'Thanks', cache_control: SHORT },
+      ],
+    })
+  })
+
+  it('chat() sends markers by default', async () => {
+    const { adapter, create } = createAdapter(textStream())
+    for await (const _chunk of chat({
+      adapter,
+      messages: [userHi],
+      threadId: 't1',
+    })) {
+      // Drain the stream.
+    }
+    expect(create.mock.calls[0]![0].messages).toEqual([
+      {
+        role: 'user',
+        content: [{ type: 'text', text: 'hi', cache_control: SHORT }],
+      },
+    ])
+  })
+
+  it('structured output keeps the system and message markers', async () => {
+    const { adapter, create } = createAdapter({
+      content: [
+        {
+          type: 'tool_use',
+          id: 'toolu_1',
+          name: 'structured_output',
+          input: { word: 'hi' },
+        },
+      ],
+      usage: { input_tokens: 1, output_tokens: 1 },
+    })
+    await adapter.structuredOutput({
+      chatOptions: {
+        model: MODEL,
+        logger,
+        messages: [userHi],
+        systemPrompts: ['Be brief.'],
+        tools: [lookup],
+        promptCache: { retention: 'short' },
+      },
+      outputSchema: {
+        type: 'object',
+        properties: { word: { type: 'string' } },
+        required: ['word'],
+      },
+    })
+    const body = create.mock.calls[0]![0]
+    expect(body.system).toEqual([
+      { type: 'text', text: 'Be brief.', cache_control: SHORT },
+    ])
+    expect(body.messages).toEqual([
+      {
+        role: 'user',
+        content: [{ type: 'text', text: 'hi', cache_control: SHORT }],
+      },
+    ])
+    // The structured output tool replaces the marked tool.
+    expect(countMarkers(body)).toBe(2)
+  })
+})

From d067f6c8188bfc0c6614419002f4e6336121ab64 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 10:51:19 +0200
Subject: [PATCH 159/286] test(ai-cloudflare): prove the binding passes prompt
 cache fields through

cloudflareBindingFetch forwards Claude cache_control markers, the OpenAI prompt_cache_key and prompt_cache_retention, and the session headers to env.AI.run unchanged.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .../tests/prompt-cache-binding.test.ts        | 120 ++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 packages/ai-cloudflare/tests/prompt-cache-binding.test.ts

diff --git a/packages/ai-cloudflare/tests/prompt-cache-binding.test.ts b/packages/ai-cloudflare/tests/prompt-cache-binding.test.ts
new file mode 100644
index 0000000000..8f745ad117
--- /dev/null
+++ b/packages/ai-cloudflare/tests/prompt-cache-binding.test.ts
@@ -0,0 +1,120 @@
+import { describe, expect, it, vi } from 'vitest'
+import { cloudflareBindingFetch } from '../src/index'
+import type { CloudflareBindingFetchOptions } from '../src/index'
+import type { Ai } from '@cloudflare/workers-types'
+
+/**
+ * Sends one request through `cloudflareBindingFetch` and returns the
+ * arguments that `env.AI.run` got.
+ */
+async function runArgs(
+  vendor: CloudflareBindingFetchOptions['vendor'],
+  body: object,
+  headers: Record<string, string> = {},
+) {
+  const run = vi.fn((..._args: Array<unknown>) => new Response('{}'))
+  // `Ai` is a large abstract class with a generic, overloaded `run`. A fake
+  // that only records calls cannot match that type, so we cast it.
+  const binding = { run } as unknown as Ai
+  const fetchImpl = cloudflareBindingFetch({ binding, vendor })
+  await fetchImpl('https://api.example.com/v1/messages', {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+  })
+  return run.mock.calls[0]
+}
+
+// The parts of an Anthropic request that carry prompt cache markers.
+const anthropicCachedParts = {
+  stream: true,
+  system: [
+    {
+      type: 'text',
+      text: 'x',
+      cache_control: { type: 'ephemeral', ttl: '1h' },
+    },
+  ],
+  tools: [
+    {
+      name: 'lookup',
+      input_schema: { type: 'object' },
+      cache_control: { type: 'ephemeral' },
+    },
+  ],
+  messages: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'Hi' },
+        {
+          type: 'text',
+          text: 'What changed?',
+          cache_control: { type: 'ephemeral' },
+        },
+      ],
+    },
+  ],
+}
+
+describe('cloudflareBindingFetch prompt caching', () => {
+  it('passes Anthropic cache_control markers to env.AI.run unchanged', async () => {
+    const args = await runArgs('anthropic', {
+      model: 'claude-opus-5-5',
+      ...anthropicCachedParts,
+    })
+
+    expect(args).toStrictEqual([
+      'anthropic/claude-opus-5-5',
+      anthropicCachedParts,
+      { returnRawResponse: true },
+    ])
+  })
+
+  it('passes the OpenAI prompt cache key and retention to env.AI.run unchanged', async () => {
+    const args = await runArgs('openai', {
+      model: 'gpt-6.1-sol',
+      input: 'Hi',
+      prompt_cache_key: 'thread-1',
+      prompt_cache_retention: '24h',
+    })
+
+    expect(args).toStrictEqual([
+      'openai/gpt-6.1-sol',
+      {
+        input: 'Hi',
+        prompt_cache_key: 'thread-1',
+        prompt_cache_retention: '24h',
+      },
+      { returnRawResponse: true },
+    ])
+  })
+
+  it('forwards session headers as extraHeaders and drops the auth header', async () => {
+    const args = await runArgs(
+      'openai',
+      { model: 'gpt-6.1-sol', input: 'Hi' },
+      {
+        authorization: 'Bearer cloudflare-binding',
+        'content-type': 'application/json',
+        'x-stainless-os': 'Windows',
+        'x-session-affinity': 'thread-1',
+        'x-client-request-id': 'request-1',
+        session_id: 'thread-1',
+      },
+    )
+
+    expect(args).toStrictEqual([
+      'openai/gpt-6.1-sol',
+      { input: 'Hi' },
+      {
+        returnRawResponse: true,
+        extraHeaders: {
+          'x-session-affinity': 'thread-1',
+          'x-client-request-id': 'request-1',
+          session_id: 'thread-1',
+        },
+      },
+    ])
+  })
+})

From 819d22195b1bf1696c3c6a3762d750237534caff Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 10:56:36 +0200
Subject: [PATCH 160/286] feat(ai-openai): apply prompt cache rules to
 openaiCompatible

Chat Completions sends prompt_cache_key on api.openai.com or with 'long'. The cacheControlFormat 'anthropic' markers stop on 'none' and get ttl '1h' on 'long'. Session headers use the cache key. The Responses adapter now gets the model compat and sends the Responses cache fields. New compat field supportsExplicitPromptCacheMode, also on ModelCompat in ai-models.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-models/src/types.ts               |   2 +
 packages/ai-openai/src/compatible/adapter.ts  |  46 ++-
 packages/ai-openai/src/compatible/index.ts    |   9 +-
 packages/ai-openai/src/compatible/quirks.ts   |  38 +-
 .../ai-openai/tests/compatible-quirks.test.ts | 390 ++++++++++++++++--
 5 files changed, 433 insertions(+), 52 deletions(-)

diff --git a/packages/ai-models/src/types.ts b/packages/ai-models/src/types.ts
index e71b507e9d..57205e66bf 100644
--- a/packages/ai-models/src/types.ts
+++ b/packages/ai-models/src/types.ts
@@ -81,6 +81,8 @@ export interface ModelCompat {
   supportsAdditionalTools?: boolean
   supportsToolSearch?: boolean
   supportsOpenAIGrammarTools?: boolean
+  /** `true`: the model takes `prompt_cache_options` (OpenAI gpt-5.6 and later); older models reject it. */
+  supportsExplicitPromptCacheMode?: boolean
 }
 
 /** Prices in USD per 1M tokens. */
diff --git a/packages/ai-openai/src/compatible/adapter.ts b/packages/ai-openai/src/compatible/adapter.ts
index ba8a6f2ba4..f97e901d5a 100644
--- a/packages/ai-openai/src/compatible/adapter.ts
+++ b/packages/ai-openai/src/compatible/adapter.ts
@@ -8,6 +8,11 @@ import {
   replayReasoning,
   sessionHeaders,
 } from './quirks'
+import {
+  chatPromptCacheFields,
+  responsesPromptCacheFields,
+} from '../prompt-cache'
+import { openAIModelUsesExplicitPromptCache } from '../model-meta'
 import type OpenAI from 'openai'
 import type {
   ChatCompletionCreateParamsStreaming,
@@ -80,14 +85,23 @@ export class OpenAICompatibleChatAdapter<
   }
 
   /**
-   * The request, then the provider's quirks: the thinking fields for
+   * The request with the `chat({ promptCache })` fields, then the provider's
+   * quirks: the thinking fields for
    * `reasoning`, and (with `compat`) the instruction role, the token field,
    * `store`, strict tools, `tool_stream`, and cache markers.
    */
   protected override mapOptionsToRequest(
     options: TextOptions,
   ): ChatCompletionCreateParamsStreaming {
-    const params = super.mapOptionsToRequest(options)
+    // The cache fields go first, so a value the caller set in `modelOptions`
+    // (already on the base request) wins.
+    const params = {
+      ...chatPromptCacheFields(options.promptCache, {
+        baseURL: this.client.baseURL ?? '',
+        longRetention: this.compat?.supportsLongCacheRetention !== false,
+      }),
+      ...super.mapOptionsToRequest(options),
+    }
     if (!options.reasoning && !this.compat) return params
     // The quirks edit loose JSON. The OpenAI SDK type has no field for
     // `thinking` or `enable_thinking`, so the result goes back on `params`.
@@ -99,6 +113,7 @@ export class OpenAICompatibleChatAdapter<
         body,
         this.compat,
         this.reasoning !== undefined && this.reasoning !== false,
+        options.promptCache,
       )
     for (const key of Object.keys(params))
       if (!(key in body)) Reflect.deleteProperty(params, key)
@@ -131,7 +146,12 @@ export class OpenAICompatibleChatAdapter<
     options: TextOptions,
   ): Record<string, string> | undefined {
     return this.compat
-      ? sessionHeaders(this.compat, options.conversationId ?? options.threadId)
+      ? sessionHeaders(
+          this.compat,
+          options.promptCache?.key ??
+            options.conversationId ??
+            options.threadId,
+        )
       : undefined
   }
 
@@ -177,13 +197,33 @@ export class OpenAICompatibleResponsesAdapter<
 > {
   override readonly kind = 'text' as const
   readonly maxTokensKey = 'max_output_tokens'
+  private readonly compat: OpenAICompatibleCompat | undefined
 
   constructor(
     client: OpenAI,
     model: TModel,
     name: string,
     options?: OpenAIBaseTextAdapterOptions,
+    config: CompatibleModelConfig = {},
   ) {
     super(model, name, client, options)
+    this.compat = config.compat
+  }
+
+  /** The request, plus the prompt cache fields for `chat({ promptCache })`. */
+  protected override mapOptionsToRequest(
+    options: TextOptions<TProviderOptions>,
+  ) {
+    // The cache fields go first, so a value the caller set in `modelOptions`
+    // (already on the base request) wins.
+    return {
+      ...responsesPromptCacheFields(options.promptCache, {
+        explicitMode:
+          this.compat?.supportsExplicitPromptCacheMode ??
+          openAIModelUsesExplicitPromptCache(options.model),
+        longRetention: this.compat?.supportsLongCacheRetention !== false,
+      }),
+      ...super.mapOptionsToRequest(options),
+    }
   }
 }
diff --git a/packages/ai-openai/src/compatible/index.ts b/packages/ai-openai/src/compatible/index.ts
index 2e60bcd33b..bade28e02d 100644
--- a/packages/ai-openai/src/compatible/index.ts
+++ b/packages/ai-openai/src/compatible/index.ts
@@ -92,7 +92,13 @@ export function openaiCompatible<
         ResolveCompatOptions<TModels, TModelName>,
         ResolveCompatInput<TModels, TModelName>,
         ResolveCompatTools<TModels, TModelName>
-      >(client, model, name, { strictFallbackWarning })
+      >(
+        client,
+        model,
+        name,
+        { strictFallbackWarning },
+        modelConfig(models, model, compat),
+      )
     }
     return new OpenAICompatibleChatAdapter<
       TModelName,
@@ -143,6 +149,7 @@ export function openaiCompatibleText<const TModelName extends string>(
       model,
       name,
       { strictFallbackWarning },
+      compat ? { compat } : {},
     )
   }
   return new OpenAICompatibleChatAdapter<
diff --git a/packages/ai-openai/src/compatible/quirks.ts b/packages/ai-openai/src/compatible/quirks.ts
index a17d844fb3..4638d61067 100644
--- a/packages/ai-openai/src/compatible/quirks.ts
+++ b/packages/ai-openai/src/compatible/quirks.ts
@@ -5,6 +5,7 @@ import type {
   ReasoningLevel,
   ReasoningMap,
   ReasoningRequest,
+  ResolvedPromptCache,
 } from '@tanstack/ai'
 
 /** How a Chat Completions request asks for thinking. */
@@ -51,7 +52,10 @@ export interface OpenAICompatibleCompat {
   sessionAffinityFormat?: 'openai' | 'openrouter' | 'openai-nosession'
   /** `'anthropic'`: add Anthropic cache markers (Claude through OpenRouter). */
   cacheControlFormat?: 'anthropic'
+  /** `false`: the provider has no long cache, so a `'long'` retention acts as `'short'`. */
   supportsLongCacheRetention?: boolean
+  /** `true`: the model takes `prompt_cache_options` (OpenAI gpt-5.6 and later); older models reject it. */
+  supportsExplicitPromptCacheMode?: boolean
   /** A top-level field for the thinking token budget, for example `thinking_token_budget`. */
   thinkingTokenBudgetField?: string
   /** Values for `chat_template_kwargs` (the `chat-template` format). */
@@ -220,23 +224,25 @@ export function applyThinking(
     params[compat.thinkingTokenBudgetField] = budget
 }
 
-const EPHEMERAL = { type: 'ephemeral' } as const
+/** An Anthropic cache marker. `ttl: '1h'` keeps the cache for one hour. */
+type CacheMarker = { type: 'ephemeral'; ttl?: '1h' }
 
 /** Put an Anthropic cache marker on the last text part of a message. */
-function markMessage(message: Record<string, unknown>): boolean {
+function markMessage(
+  message: Record<string, unknown>,
+  marker: CacheMarker,
+): boolean {
   const content = message.content
   if (typeof content === 'string') {
     if (content.length === 0) return false
-    message.content = [
-      { type: 'text', text: content, cache_control: EPHEMERAL },
-    ]
+    message.content = [{ type: 'text', text: content, cache_control: marker }]
     return true
   }
   if (!Array.isArray(content)) return false
   for (let index = content.length - 1; index >= 0; index--) {
     const part: unknown = content[index]
     if (isRecord(part) && part.type === 'text') {
-      content[index] = { ...part, cache_control: EPHEMERAL }
+      content[index] = { ...part, cache_control: marker }
       return true
     }
   }
@@ -246,11 +252,14 @@ function markMessage(message: Record<string, unknown>): boolean {
 /**
  * The quirks that are not about thinking: the instruction role, the token
  * field name, `store`, strict tools, `tool_stream`, and cache markers.
+ * `promptCache` sets the cache markers. When it is absent, the markers stay
+ * as today.
  */
 export function applyRequestQuirks(
   params: Params,
   compat: OpenAICompatibleCompat,
   reasons: boolean,
+  promptCache: ResolvedPromptCache | undefined,
 ): void {
   const messages = records(params.messages)
   const instructions = messages.find((message) => message.role === 'system')
@@ -279,19 +288,28 @@ export function applyRequestQuirks(
     if (compat.zaiToolStream) params.tool_stream = true
   }
 
-  if (compat.cacheControlFormat === 'anthropic') {
+  const addsMarkers =
+    compat.cacheControlFormat === 'anthropic' &&
+    promptCache?.retention !== 'none'
+  if (addsMarkers) {
+    const isLong =
+      promptCache?.retention === 'long' &&
+      compat.supportsLongCacheRetention !== false
+    const marker: CacheMarker = isLong
+      ? { type: 'ephemeral', ttl: '1h' }
+      : { type: 'ephemeral' }
     const system = messages.find(
       (message) => message.role === 'system' || message.role === 'developer',
     )
-    if (system) markMessage(system)
+    if (system) markMessage(system, marker)
     const lastTool = tools.at(-1)
-    if (lastTool) lastTool.cache_control = EPHEMERAL
+    if (lastTool) lastTool.cache_control = marker
     for (let index = messages.length - 1; index >= 0; index--) {
       const message = messages[index]
       if (
         message &&
         ['user', 'assistant', 'tool'].includes(String(message.role)) &&
-        markMessage(message)
+        markMessage(message, marker)
       )
         break
     }
diff --git a/packages/ai-openai/tests/compatible-quirks.test.ts b/packages/ai-openai/tests/compatible-quirks.test.ts
index 00e6328e78..730c9c3ff3 100644
--- a/packages/ai-openai/tests/compatible-quirks.test.ts
+++ b/packages/ai-openai/tests/compatible-quirks.test.ts
@@ -1,14 +1,39 @@
 import { describe, expect, it, vi } from 'vitest'
 import OpenAI from 'openai'
 import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
-import { OpenAICompatibleChatAdapter } from '../src/compatible/adapter'
-import type { ModelMessage, ReasoningMap, ReasoningRequest } from '@tanstack/ai'
+import {
+  OpenAICompatibleChatAdapter,
+  OpenAICompatibleResponsesAdapter,
+} from '../src/compatible/adapter'
+import { openaiCompatible, openaiCompatibleText } from '../src/compatible'
+import type {
+  ModelMessage,
+  ReasoningMap,
+  ReasoningRequest,
+  ResolvedPromptCache,
+} from '@tanstack/ai'
 import type { CompatibleModelConfig } from '../src/compatible/adapter'
+import type { OpenAICompatibleCompat } from '../src/compatible/quirks'
 
 const logger = resolveDebugOption(false)
+const OPENAI_URL = 'https://api.openai.com/v1'
+const CUSTOM_URL = 'https://llm.example.com/v1'
 
 async function* noChunks() {}
 
+async function drain(stream: AsyncIterable<unknown>) {
+  for await (const _chunk of stream) {
+    // Drain the stream.
+  }
+}
+
+/** Only the `prompt_cache*` fields of a request body. */
+function promptCacheFieldsOf(body: object) {
+  return Object.fromEntries(
+    Object.entries(body).filter(([key]) => key.startsWith('prompt_cache')),
+  )
+}
+
 /** Run one call and return the request body and request options it sent. */
 async function send(
   config: CompatibleModelConfig,
@@ -19,9 +44,16 @@ async function send(
     modelOptions?: Record<string, unknown>
     tools?: boolean
     conversationId?: string
+    promptCache?: ResolvedPromptCache
+    baseURL?: string
   } = {},
 ) {
-  const client = new OpenAI({ apiKey: 'test' })
+  // The base URL is always set, so an OPENAI_BASE_URL env value cannot
+  // change the result.
+  const client = new OpenAI({
+    apiKey: 'test',
+    baseURL: options.baseURL ?? OPENAI_URL,
+  })
   const create = vi.fn().mockResolvedValue(noChunks())
   client.chat.completions.create =
     create as typeof client.chat.completions.create
@@ -32,34 +64,37 @@ async function send(
     {},
     config,
   )
-  for await (const _chunk of adapter.chatStream({
-    logger,
-    model: 'm',
-    messages: options.messages ?? [{ role: 'user', content: 'hi' }],
-    ...(options.systemPrompts ? { systemPrompts: options.systemPrompts } : {}),
-    ...(options.reasoning ? { reasoning: options.reasoning } : {}),
-    ...(options.modelOptions ? { modelOptions: options.modelOptions } : {}),
-    ...(options.conversationId
-      ? { conversationId: options.conversationId }
-      : {}),
-    ...(options.tools
-      ? {
-          tools: [
-            {
-              name: 'lookup',
-              description: 'Look up a word',
-              inputSchema: {
-                type: 'object',
-                properties: { word: { type: 'string' } },
-                required: ['word'],
+  await drain(
+    adapter.chatStream({
+      logger,
+      model: 'm',
+      messages: options.messages ?? [{ role: 'user', content: 'hi' }],
+      ...(options.systemPrompts
+        ? { systemPrompts: options.systemPrompts }
+        : {}),
+      ...(options.reasoning ? { reasoning: options.reasoning } : {}),
+      ...(options.modelOptions ? { modelOptions: options.modelOptions } : {}),
+      ...(options.conversationId
+        ? { conversationId: options.conversationId }
+        : {}),
+      ...(options.promptCache ? { promptCache: options.promptCache } : {}),
+      ...(options.tools
+        ? {
+            tools: [
+              {
+                name: 'lookup',
+                description: 'Look up a word',
+                inputSchema: {
+                  type: 'object',
+                  properties: { word: { type: 'string' } },
+                  required: ['word'],
+                },
               },
-            },
-          ],
-        }
-      : {}),
-  })) {
-    // Drain the stream.
-  }
+            ],
+          }
+        : {}),
+    }),
+  )
   const [body, requestOptions] = create.mock.calls[0] ?? []
   return {
     body: body as Record<string, any>,
@@ -67,6 +102,51 @@ async function send(
   }
 }
 
+/** Run one compatible Responses call and return the cache fields it sent. */
+async function sendResponses(
+  model: string,
+  config: CompatibleModelConfig,
+  promptCache: ResolvedPromptCache,
+  modelOptions?: Record<string, unknown>,
+) {
+  const client = new OpenAI({ apiKey: 'test', baseURL: CUSTOM_URL })
+  // The SDK `create` returns an APIPromise, which a mock cannot build.
+  const create = vi.fn().mockResolvedValue(noChunks())
+  client.responses.create = create as typeof client.responses.create
+  const adapter = new OpenAICompatibleResponsesAdapter(
+    client,
+    model,
+    'test',
+    {},
+    config,
+  )
+  await drain(
+    adapter.chatStream({
+      logger,
+      model,
+      messages: [{ role: 'user', content: 'hi' }],
+      promptCache,
+      ...(modelOptions ? { modelOptions } : {}),
+    }),
+  )
+  return promptCacheFieldsOf(create.mock.calls[0]?.[0])
+}
+
+/**
+ * A `fetch` for the OpenAI SDK that answers with an empty event stream and
+ * keeps each JSON request body.
+ */
+function recordingFetch() {
+  const bodies: Array<object> = []
+  const fetch = vi.fn(async (_url: RequestInfo | URL, init?: RequestInit) => {
+    bodies.push(JSON.parse(String(init?.body)))
+    return new Response('', {
+      headers: { 'content-type': 'text/event-stream' },
+    })
+  })
+  return { fetch, bodies }
+}
+
 const on = (level: ReasoningRequest['level']): ReasoningRequest => ({
   level,
   summary: true,
@@ -329,20 +409,101 @@ describe('openaiCompatible request quirks', () => {
     expect(body.tool_stream).toBe(true)
   })
 
-  it('adds Anthropic cache markers for Claude through OpenRouter', async () => {
+  const markerCases: Array<{
+    name: string
+    promptCache?: ResolvedPromptCache
+    compat?: OpenAICompatibleCompat
+    marker: { type: 'ephemeral'; ttl?: '1h' }
+  }> = [
+    { name: 'no promptCache', marker: { type: 'ephemeral' } },
+    {
+      name: 'short',
+      promptCache: { retention: 'short' },
+      marker: { type: 'ephemeral' },
+    },
+    {
+      name: 'long',
+      promptCache: { retention: 'long' },
+      marker: { type: 'ephemeral', ttl: '1h' },
+    },
+    {
+      name: 'long, provider without long retention',
+      promptCache: { retention: 'long' },
+      compat: { supportsLongCacheRetention: false },
+      marker: { type: 'ephemeral' },
+    },
+  ]
+
+  it.each(markerCases)(
+    'adds Anthropic cache markers for Claude through OpenRouter: $name',
+    async ({ promptCache, compat, marker }) => {
+      const { body } = await send(
+        { compat: { cacheControlFormat: 'anthropic', ...compat } },
+        {
+          systemPrompts: ['Be brief.'],
+          tools: true,
+          ...(promptCache ? { promptCache } : {}),
+        },
+      )
+      expect(body.messages[0].content).toEqual([
+        { type: 'text', text: 'Be brief.', cache_control: marker },
+      ])
+      expect(body.messages.at(-1).content).toEqual([
+        { type: 'text', text: 'hi', cache_control: marker },
+      ])
+      expect(body.tools.at(-1).cache_control).toEqual(marker)
+    },
+  )
+
+  it('adds no Anthropic cache markers for a none retention', async () => {
     const { body } = await send(
       { compat: { cacheControlFormat: 'anthropic' } },
-      { systemPrompts: ['Be brief.'], tools: true },
+      {
+        systemPrompts: ['Be brief.'],
+        tools: true,
+        promptCache: { retention: 'none' },
+      },
     )
-    expect(body.messages[0].content).toEqual([
-      { type: 'text', text: 'Be brief.', cache_control: { type: 'ephemeral' } },
+    expect(body.messages).toEqual([
+      { role: 'system', content: 'Be brief.' },
+      { role: 'user', content: 'hi' },
     ])
-    expect(body.messages.at(-1).content[0].cache_control).toEqual({
-      type: 'ephemeral',
-    })
-    expect(body.tools.at(-1).cache_control).toEqual({ type: 'ephemeral' })
+    expect(body.tools.at(-1)).not.toHaveProperty('cache_control')
   })
 
+  it.each([
+    { format: 'openrouter', headers: { 'x-session-id': 'k-1' } },
+    {
+      format: 'openai',
+      headers: {
+        session_id: 'k-1',
+        'x-client-request-id': 'k-1',
+        'x-session-affinity': 'k-1',
+      },
+    },
+    {
+      format: 'openai-nosession',
+      headers: { 'x-client-request-id': 'k-1', 'x-session-affinity': 'k-1' },
+    },
+  ] as const)(
+    'sends the promptCache key as $format session headers',
+    async ({ format, headers }) => {
+      const { requestOptions } = await send(
+        {
+          compat: {
+            sendSessionAffinityHeaders: true,
+            sessionAffinityFormat: format,
+          },
+        },
+        {
+          conversationId: 'c1',
+          promptCache: { retention: 'short', key: 'k-1' },
+        },
+      )
+      expect(requestOptions.headers).toEqual(headers)
+    },
+  )
+
   it('sends session headers, and leaves out streaming usage when refused', async () => {
     const openrouter = await send(
       {
@@ -371,3 +532,156 @@ describe('openaiCompatible request quirks', () => {
     expect(openai.body).not.toHaveProperty('stream_options')
   })
 })
+
+describe('openaiCompatible Chat Completions: chat({ promptCache })', () => {
+  /** Run one call through a provider compat and return its cache fields. */
+  async function chatCacheFields(
+    promptCache: ResolvedPromptCache,
+    options: {
+      baseURL?: string
+      compat?: OpenAICompatibleCompat
+      modelOptions?: Record<string, unknown>
+    } = {},
+  ) {
+    const { body } = await send(
+      { compat: options.compat ?? {} },
+      {
+        promptCache,
+        baseURL: options.baseURL ?? CUSTOM_URL,
+        ...(options.modelOptions ? { modelOptions: options.modelOptions } : {}),
+      },
+    )
+    return promptCacheFieldsOf(body)
+  }
+
+  it('sends the key to api.openai.com for a short retention', async () => {
+    expect(
+      await chatCacheFields(
+        { retention: 'short', key: 'k-1' },
+        { baseURL: OPENAI_URL },
+      ),
+    ).toStrictEqual({ prompt_cache_key: 'k-1' })
+  })
+
+  it('sends no key to another server for a short retention', async () => {
+    expect(
+      await chatCacheFields({ retention: 'short', key: 'k-1' }),
+    ).toStrictEqual({})
+  })
+
+  it('sends the key and 24h for a long retention', async () => {
+    expect(
+      await chatCacheFields({ retention: 'long', key: 'k-1' }),
+    ).toStrictEqual({ prompt_cache_key: 'k-1', prompt_cache_retention: '24h' })
+  })
+
+  it('sends nothing for a long retention when the provider has no long cache', async () => {
+    expect(
+      await chatCacheFields(
+        { retention: 'long', key: 'k-1' },
+        { compat: { supportsLongCacheRetention: false } },
+      ),
+    ).toStrictEqual({})
+  })
+
+  it('keeps the values the caller set in modelOptions', async () => {
+    expect(
+      await chatCacheFields(
+        { retention: 'long', key: 'k-1' },
+        {
+          modelOptions: {
+            prompt_cache_key: 'caller-key',
+            prompt_cache_retention: 'in_memory',
+          },
+        },
+      ),
+    ).toStrictEqual({
+      prompt_cache_key: 'caller-key',
+      prompt_cache_retention: 'in_memory',
+    })
+  })
+})
+
+describe('openaiCompatible Responses: chat({ promptCache })', () => {
+  it('turns automatic caching off for none with supportsExplicitPromptCacheMode', async () => {
+    expect(
+      await sendResponses(
+        'my-deployment',
+        { compat: { supportsExplicitPromptCacheMode: true } },
+        { retention: 'none', key: 'k-1' },
+      ),
+    ).toStrictEqual({ prompt_cache_options: { mode: 'explicit' } })
+  })
+
+  it('uses explicit mode for a gpt-5.6 deployment name without the flag', async () => {
+    expect(
+      await sendResponses('gpt-5.6', {}, { retention: 'none', key: 'k-1' }),
+    ).toStrictEqual({ prompt_cache_options: { mode: 'explicit' } })
+  })
+
+  it('sends the key and 24h for long on an older model', async () => {
+    expect(
+      await sendResponses(
+        'my-deployment',
+        {},
+        { retention: 'long', key: 'k-1' },
+      ),
+    ).toStrictEqual({ prompt_cache_key: 'k-1', prompt_cache_retention: '24h' })
+  })
+
+  it('sends only the key for long when the provider has no long cache', async () => {
+    expect(
+      await sendResponses(
+        'my-deployment',
+        { compat: { supportsLongCacheRetention: false } },
+        { retention: 'long', key: 'k-1' },
+      ),
+    ).toStrictEqual({ prompt_cache_key: 'k-1' })
+  })
+
+  it('keeps the values the caller set in modelOptions', async () => {
+    expect(
+      await sendResponses(
+        'gpt-5.6',
+        {},
+        { retention: 'long', key: 'k-1' },
+        { prompt_cache_key: 'caller-key', prompt_cache_options: { ttl: '5m' } },
+      ),
+    ).toStrictEqual({
+      prompt_cache_key: 'caller-key',
+      prompt_cache_options: { ttl: '5m' },
+    })
+  })
+
+  it('gets the provider compat from openaiCompatible and openaiCompatibleText', async () => {
+    const { fetch, bodies } = recordingFetch()
+    const clientConfig = {
+      baseURL: CUSTOM_URL,
+      apiKey: 'test',
+      api: 'responses',
+      compat: { supportsExplicitPromptCacheMode: true },
+      fetch,
+    } as const
+    const provider = openaiCompatible({
+      ...clientConfig,
+      models: ['my-deployment'],
+    })
+    const adapters = [
+      provider('my-deployment'),
+      openaiCompatibleText('my-deployment', clientConfig),
+    ]
+    for (const adapter of adapters)
+      await drain(
+        adapter.chatStream({
+          logger,
+          model: 'my-deployment',
+          messages: [{ role: 'user', content: 'hi' }],
+          promptCache: { retention: 'none' },
+        }),
+      )
+    expect(bodies.map(promptCacheFieldsOf)).toStrictEqual([
+      { prompt_cache_options: { mode: 'explicit' } },
+      { prompt_cache_options: { mode: 'explicit' } },
+    ])
+  })
+})

From cc0db80c729a3e955d9ebe173f9ccd99ca1c1875 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 11:01:25 +0200
Subject: [PATCH 161/286] docs: add the prompt caching guide

New page advanced/prompt-caching: the default, the retention values, the cache key, the cost on each provider, manual settings, and cache usage. The harness overview gets a prompt caching section. The Anthropic, Bedrock, and OpenAI pages say that manual settings win. Stream events document the cache usage fields.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 docs/adapters/anthropic.md      |   8 +-
 docs/adapters/bedrock.md        |   6 +-
 docs/adapters/openai.md         |  21 +++
 docs/advanced/prompt-caching.md | 229 ++++++++++++++++++++++++++++++++
 docs/chat/stream-events.md      |   2 +
 docs/config.json                |  15 ++-
 docs/harness/overview.md        |  23 ++++
 7 files changed, 295 insertions(+), 9 deletions(-)
 create mode 100644 docs/advanced/prompt-caching.md

diff --git a/docs/adapters/anthropic.md b/docs/adapters/anthropic.md
index 2352c327db..ac3ad86fcf 100644
--- a/docs/adapters/anthropic.md
+++ b/docs/adapters/anthropic.md
@@ -257,14 +257,16 @@ The thinking text streams back as thinking parts. Pass `summary: false` to keep
 
 ### Prompt Caching
 
-Cache prompts for better performance and reduced costs:
+`chat()` caches Claude prompts by default. It adds `cache_control` markers to the system prompt, the last tool, and the last user message. To send no markers, pass `promptCache: 'none'`. For the retention, the cache key, and the cost, see [Prompt Caching](../advanced/prompt-caching).
+
+To place a marker yourself, set `cache_control` in the `metadata` of a message part, a system prompt, or a tool. A marker of your own turns the automatic markers off for that request:
 
 ```typescript
 import { chat } from "@tanstack/ai";
 import { anthropicText } from "@tanstack/ai-anthropic";
 
 const stream = chat({
-  adapter: anthropicText("claude-sonnet-4-6"),
+  adapter: anthropicText("claude-sonnet-5-5"),
   messages: [
     {
       role: "user",
@@ -284,6 +286,8 @@ const stream = chat({
 });
 ```
 
+`modelOptions.cache_control` asks Anthropic to place one marker for the whole request. It also turns the automatic markers off.
+
 ## Summarization
 
 Anthropic supports text summarization:
diff --git a/docs/adapters/bedrock.md b/docs/adapters/bedrock.md
index df409a2961..6c4ce20215 100644
--- a/docs/adapters/bedrock.md
+++ b/docs/adapters/bedrock.md
@@ -179,7 +179,9 @@ const adapter = createBedrockText(
 
 ### Prompt caching
 
-Add a `cachePoint` to make a prompt prefix eligible for caching. Later requests can read matching tokens at the reduced cache rate. Bedrock bills cache misses at the standard input rate.
+`chat()` adds cache points for Claude models by default: one after the system prompt and one at the end of the last user message. Other models get no automatic cache point. To turn this off, pass `promptCache: 'none'`. For the retention and the cost, see [Prompt Caching](../advanced/prompt-caching).
+
+To choose the places yourself, set `metadata.cachePoint`. A cache point of your own turns the automatic cache points off for that request. Later requests can read matching tokens at the reduced cache rate. Bedrock bills cache misses at the standard input rate.
 
 Explicit prompt caching is model-dependent. Use `cachePoint` only with a model that AWS lists as supporting it. The minimum checkpoint size and the TTL options also vary by model.
 
@@ -229,7 +231,7 @@ Tools take the same metadata. Pass `metadata: { cachePoint: { type: 'default' }
 
 ### Token usage
 
-`onUsage` and `RUN_FINISHED.usage` report Bedrock's counts as `promptTokens`, `completionTokens`, and `totalTokens`. When a request hits or writes a prompt cache, the cache counts arrive on `promptTokensDetails.cachedTokens` and `promptTokensDetails.cacheWriteTokens`. Bedrock counts only the uncached part of the input in `promptTokens`, so add the two cache counts to it to get the full input size.
+`onUsage` and `RUN_FINISHED.usage` report Bedrock's counts as `promptTokens`, `completionTokens`, and `totalTokens`. `promptTokens` is the full input size, cached tokens included. When a request hits or writes a prompt cache, the cache counts arrive on `promptTokensDetails.cachedTokens` and `promptTokensDetails.cacheWriteTokens`.
 
 ## Chat Completions API (`api: 'chat'`)
 
diff --git a/docs/adapters/openai.md b/docs/adapters/openai.md
index 57088899ea..304daa39e8 100644
--- a/docs/adapters/openai.md
+++ b/docs/adapters/openai.md
@@ -229,6 +229,27 @@ const stream = chat({
 
 The adapter sends the level as `reasoning.effort`, with `summary: "auto"` so the reasoning summary streams back as thinking parts. Pass `reasoning: { level: "high", summary: false }` to skip the summary. The types list only the levels the model has. See [Reasoning](../chat/reasoning).
 
+### Prompt caching
+
+`chat()` sends `prompt_cache_key` by default, set to the `threadId` that you pass. OpenAI uses the key to send requests with the same start to the same cache. With `promptCache: 'long'`, `chat()` also asks for the long retention. See [Prompt Caching](../advanced/prompt-caching).
+
+To use your own key, set it in `modelOptions`. Your value wins over the automatic one:
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { openaiText } from "@tanstack/ai-openai";
+
+const stream = chat({
+  adapter: openaiText("gpt-6.1-sol"),
+  messages: [{ role: "user", content: "Hello!" }],
+  modelOptions: {
+    prompt_cache_key: "acme-support",
+  },
+});
+```
+
+`modelOptions.prompt_cache_retention` also wins over the automatic `prompt_cache_retention`.
+
 ## Summarization
 
 Summarize long text content:
diff --git a/docs/advanced/prompt-caching.md b/docs/advanced/prompt-caching.md
new file mode 100644
index 0000000000..34873c5c75
--- /dev/null
+++ b/docs/advanced/prompt-caching.md
@@ -0,0 +1,229 @@
+---
+title: Prompt Caching
+id: prompt-caching
+order: 4
+description: "chat() caches the stable start of each request by default, so a repeated system prompt, tool list, and history cost less and answer sooner. Pick the retention, set the cache key, or turn it off."
+keywords:
+  - tanstack ai
+  - prompt caching
+  - promptCache
+  - cache_control
+  - prompt_cache_key
+  - cached tokens
+  - token cost
+---
+
+An agent sends the same start with every request: the system prompt, the tools, and the earlier messages. You pay for those input tokens on every call, and the model reads them again before it answers.
+
+Prompt caching lets the provider keep that start. The next request with the same start reads it from the cache, so it costs less and the answer starts sooner. `chat()` turns it on by default.
+
+## Cache a conversation
+
+Pass the same `threadId` with every request of a conversation. `chat()` uses it as the cache key:
+
+```typescript
+import {
+  chat,
+  chatParamsFromRequest,
+  toServerSentEventsResponse,
+} from "@tanstack/ai";
+import { openaiText } from "@tanstack/ai-openai";
+
+export async function POST(request: Request) {
+  const { messages, threadId, runId } = await chatParamsFromRequest(request);
+
+  const stream = chat({
+    adapter: openaiText("gpt-6.1-sol"),
+    systemPrompts: ["You are a support agent for Acme."],
+    messages,
+    // The cache key. useChat sends one threadId for each conversation.
+    threadId,
+    runId,
+  });
+
+  return toServerSentEventsResponse(stream);
+}
+```
+
+From the second request on, the system prompt and the earlier turns come from the cache.
+
+The cache key is the first of these that you set:
+
+1. `promptCache.key`.
+2. The `threadId` or `conversationId` of the call.
+3. Nothing. Claude does not need a key. OpenAI routes requests by key, so a stable `threadId` gives a better hit rate.
+
+A request reads from the cache only when it starts the same way as an earlier request. Text that changes on every call, such as the current time in the system prompt, ends the match at that point.
+
+`summarize()` and direct adapter calls do not add cache fields.
+
+## Pick the retention
+
+Set `promptCache` on `chat()`:
+
+| Value | What it does |
+|---|---|
+| `'short'` | The default. The provider keeps the cache for a short time, 5 minutes on Claude. |
+| `'long'` | The provider keeps the cache longer, 1 hour on Claude. For other providers, see [What each provider gets](#what-each-provider-gets). |
+| `'none'` | No caching. |
+
+To set your own key too, pass an object:
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { openaiText } from "@tanstack/ai-openai";
+
+const stream = chat({
+  adapter: openaiText("gpt-6.1-sol"),
+  messages: [{ role: "user", content: "Where is my order?" }],
+  promptCache: { retention: "long", key: "acme-support" },
+});
+```
+
+Both fields are optional. Without `retention`, the retention is `'short'`. The types are exported from `@tanstack/ai`: `PromptCacheRetention`, `PromptCacheOptions`, and `ResolvedPromptCache`.
+
+In a harness, you set `promptCache` one time for every session. See [Build your first harness](../harness/overview#prompt-caching).
+
+## When to turn it off or keep it longer
+
+On OpenAI, Gemini, and Mistral, a cache write costs nothing extra and a cache read costs less. Keep the default there.
+
+Claude bills the cache write. This applies to Claude on Anthropic, Bedrock, Vertex, and OpenRouter:
+
+| Price, compared to normal input | `'short'` (5 minutes) | `'long'` (1 hour) |
+|---|---|---|
+| Cache write | about 1.25 times | about 2 times |
+| Cache read | about 0.1 times | about 0.1 times |
+
+The newest Claude models read from the cache for less. With `'short'`, the same start sent 2 times in 5 minutes already costs less than no cache. With `'long'`, it costs less from the third request.
+
+Two cases change the choice:
+
+- **A large prompt that you send one time.** For example, one long document per call that is never sent again. Nothing reads the cache, so the write is only extra cost. Use `'none'`.
+- **Long pauses.** The short Claude cache ends 5 minutes after its last read. If people often reply after more than 5 minutes, use `'long'`.
+
+```typescript
+import { chat } from "@tanstack/ai";
+import type { ModelMessage } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+
+// One long document per call, never sent again: skip the cache write.
+export function reviewDocument(document: string) {
+  return chat({
+    adapter: anthropicText("claude-sonnet-5-5"),
+    messages: [{ role: "user", content: `Review this contract:\n\n${document}` }],
+    promptCache: "none",
+  });
+}
+
+// People often reply after more than 5 minutes: keep the cache for 1 hour.
+export function reply(messages: Array<ModelMessage>, threadId: string) {
+  return chat({
+    adapter: anthropicText("claude-sonnet-5-5"),
+    messages,
+    threadId,
+    promptCache: "long",
+  });
+}
+```
+
+Claude caches a prompt start only when it is longer than a model minimum, from 512 to 4096 tokens. A shorter start is not cached and costs nothing extra.
+
+## What each provider gets
+
+Automatic caching adds these fields to the request.
+
+### Claude models
+
+| Adapter | `'short'` | `'long'` |
+|---|---|---|
+| `anthropicText`, Claude on Vertex | `cache_control: { type: 'ephemeral' }` on the system blocks, the last tool, and the last block of the last user message. At most 4 markers. | The same markers with `ttl: '1h'` |
+| `bedrockText` (Converse), Claude models only | A `cachePoint` after the system prompt and at the end of the last user message | Both with `ttl: '1h'` |
+| `openRouterText` with an `anthropic/*` model | `sessionId`, plus markers on the system prompt, the last tool, and the last message | The markers with `ttl: '1h'` |
+| `openaiCompatible` with `compat.cacheControlFormat: 'anthropic'` (Claude through a gateway) | Markers on the system prompt, the last tool, and the last message | The markers with `ttl: '1h'` |
+
+### Other providers
+
+| Adapter | `'short'` | `'long'` |
+|---|---|---|
+| `openaiText` (Responses) | `prompt_cache_key`, cut to 64 characters | Also `prompt_cache_retention: '24h'`. On gpt-5.6 and later, `prompt_cache_options: { ttl: '30m' }` in its place. |
+| `openaiChatCompletions`, `openaiCompatible` | `prompt_cache_key`, only to `api.openai.com` | The key and `prompt_cache_retention: '24h'`, when the provider supports it (`compat.supportsLongCacheRetention`) |
+| `openRouterText`, every model | `sessionId`, set to the cache key | The same |
+| `mistralText` | `prompt_cache_key` | The same |
+| Gemini, Vertex Gemini | Nothing. The provider caches by itself. | The same |
+
+On gpt-5.6 and later, `'none'` sends `prompt_cache_options: { mode: 'explicit' }`, so OpenAI caches nothing.
+
+The Workers AI binding (`cloudflareBindingFetch`) passes the cache fields through. To turn caching off there, pass `promptCache: 'none'`.
+
+## Set the cache yourself
+
+Your own cache settings win over the automatic ones:
+
+- **Anthropic**: `metadata.cache_control` on a system prompt, a message part, or a tool, or `modelOptions.cache_control`. Then `chat()` adds no markers to that request. See [Anthropic](../adapters/anthropic#prompt-caching).
+- **Bedrock**: `metadata.cachePoint` on a system prompt, a message part, or a tool. Then `chat()` adds no cache points to that request. See [Amazon Bedrock](../adapters/bedrock#prompt-caching).
+- **OpenAI**: `modelOptions.prompt_cache_key` and `modelOptions.prompt_cache_retention` replace the automatic values. See [OpenAI](../adapters/openai#prompt-caching).
+- **OpenRouter**: `modelOptions.sessionId` replaces the automatic `sessionId`.
+
+## Track cached tokens and cost
+
+`usage.promptTokens` is the full input on every adapter, cached tokens included. Two fields split it:
+
+- `usage.promptTokensDetails.cachedTokens`: the tokens read from the cache.
+- `usage.promptTokensDetails.cacheWriteTokens`: the tokens written to the cache. Claude reports this field.
+
+Read them in the [`onUsage`](./middleware#onusage) middleware hook. It runs one time for each model call:
+
+```typescript
+import { chat } from "@tanstack/ai";
+import type { ChatMiddleware } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+
+const cacheLog: ChatMiddleware = {
+  name: "cache-log",
+  onUsage: (ctx, usage) => {
+    const read = usage.promptTokensDetails?.cachedTokens ?? 0;
+    const written = usage.promptTokensDetails?.cacheWriteTokens ?? 0;
+    console.log(
+      `Call ${ctx.iteration}: ${usage.promptTokens} input, ${read} read from cache, ${written} written`,
+    );
+  },
+};
+
+const stream = chat({
+  adapter: anthropicText("claude-sonnet-5-5"),
+  messages: [{ role: "user", content: "Hello!" }],
+  threadId: "thread-1",
+  middleware: [cacheLog],
+});
+```
+
+The `RUN_FINISHED` event has the same `usage` object. See [Stream Events](../chat/stream-events).
+
+To get the input cost, price each part with its own rate:
+
+```typescript
+import type { TokenUsage } from "@tanstack/ai";
+
+// Prices per token, from the price list of your provider.
+interface InputPrices {
+  input: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+export function inputCost(usage: TokenUsage, prices: InputPrices) {
+  const cached = usage.promptTokensDetails?.cachedTokens ?? 0;
+  const written = usage.promptTokensDetails?.cacheWriteTokens ?? 0;
+  const uncached = usage.promptTokens - cached - written;
+  return (
+    uncached * prices.input +
+    cached * prices.cacheRead +
+    written * prices.cacheWrite
+  );
+}
+```
+
+To see cache reads in a test with no provider, use the `cache` option of the fake model. See [Test with a Fake Model](./testing).
+
+You now see how much of each request comes from the cache, and what its input costs.
diff --git a/docs/chat/stream-events.md b/docs/chat/stream-events.md
index 6d9320d671..c7a8b8309c 100644
--- a/docs/chat/stream-events.md
+++ b/docs/chat/stream-events.md
@@ -38,6 +38,8 @@ Later:
 
 On `RUN_FINISHED`, in-process `chat()` still uses TanStack `TokenUsage` (`promptTokens`). The SSE and HTTP wires use the spec `usage` array (`inputTokens`). Read `finishReason` from `metadata.tanstack.finishReason`. Custom servers: see [Event metadata](../protocol/metadata).
 
+`usage.promptTokens` is the full input, cached tokens included. Cache reads are on `usage.promptTokensDetails.cachedTokens`, and cache writes are on `usage.promptTokensDetails.cacheWriteTokens`. On the wire, they are `cachedInputTokens` and `cacheWriteInputTokens`. See [Prompt Caching](../advanced/prompt-caching#track-cached-tokens-and-cost).
+
 ```typescript
 import { chat } from "@tanstack/ai";
 import { openaiText } from "@tanstack/ai-openai";
diff --git a/docs/config.json b/docs/config.json
index 48c94fcf57..d23953992d 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -160,7 +160,7 @@
           "label": "Stream Events",
           "to": "chat/stream-events",
           "addedAt": "2026-08-26",
-          "updatedAt": "2026-09-23"
+          "updatedAt": "2026-10-02"
         },
         {
           "label": "Subagents",
@@ -331,6 +331,11 @@
           "to": "advanced/compaction",
           "addedAt": "2026-08-24",
           "updatedAt": "2026-09-30"
+        },
+        {
+          "label": "Prompt Caching",
+          "to": "advanced/prompt-caching",
+          "addedAt": "2026-10-02"
         }
       ],
       "tab": "guides"
@@ -878,7 +883,7 @@
           "label": "Build your first harness",
           "to": "harness/overview",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-09-29"
+          "updatedAt": "2026-10-02"
         },
         {
           "label": "Connect clients",
@@ -1294,13 +1299,13 @@
           "label": "OpenAI",
           "to": "adapters/openai",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-09-30"
+          "updatedAt": "2026-10-02"
         },
         {
           "label": "Anthropic",
           "to": "adapters/anthropic",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-09-30"
+          "updatedAt": "2026-10-02"
         },
         {
           "label": "Google Gemini",
@@ -1453,7 +1458,7 @@
           "label": "Amazon Bedrock",
           "to": "adapters/bedrock",
           "addedAt": "2026-06-25",
-          "updatedAt": "2026-09-25"
+          "updatedAt": "2026-10-02"
         },
         {
           "label": "BytePlus",
diff --git a/docs/harness/overview.md b/docs/harness/overview.md
index 45d9cd8aad..5f800fc39e 100644
--- a/docs/harness/overview.md
+++ b/docs/harness/overview.md
@@ -173,6 +173,29 @@ The host takes the same stores as `withPersistence`. Add an `inbox` store and th
 
 `memoryPersistence()` has every store, but it keeps them in memory only. Write your own stores to keep data in your database. See [Build your own adapter](../persistence/build-your-own-adapter).
 
+## Prompt caching
+
+Every session caches the stable start of its requests by default, with its `threadId` as the cache key. To change the default for every session, set `promptCache` on the harness:
+
+```ts group=harness-first
+export const longCache = defineHarness({
+  name: 'acme/long-cache',
+  adapter: openaiText('gpt-6.1-sol'),
+  promptCache: 'long',
+})
+```
+
+To change it for one session, pass `promptCache` to `host.open`. The session value wins over the harness value:
+
+```ts group=harness-first
+const support = await host.open(assistant, {
+  threadId: 'thread-2',
+  promptCache: { key: 'acme-support' },
+})
+```
+
+If the `threadId` already has a live session, `host.open` returns that session with its first `promptCache` value. Agents in the session use the same retention. The `/usage` command of the [`usage()` plugin](./coding-agent#what-each-plugin-adds) shows cache reads and writes. For the options and the cost, see [Prompt Caching](../advanced/prompt-caching).
+
 ## What you have now
 
 - A harness defined once, with the same options as `chat()`.

From efd2a185100e190186b6f9b5cbabc4917551c752 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 11:16:02 +0200
Subject: [PATCH 162/286] test(e2e): check the prompt cache fields on the wire

A new capturing-fetch route runs chat() on Anthropic and OpenAI Responses, by default and with promptCache 'none'. The spec checks the Claude markers and prompt_cache_key by default, and no cache field with 'none'. Two specs now expect promptTokens to be the total input.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 testing/e2e/src/routeTree.gen.ts              |  21 +++
 .../e2e/src/routes/api.prompt-cache-wire.ts   | 157 ++++++++++++++++++
 .../tests/anthropic-structured-usage.spec.ts  |   6 +-
 .../e2e/tests/bedrock-converse-cache.spec.ts  |   3 +-
 testing/e2e/tests/prompt-cache-wire.spec.ts   |  51 ++++++
 5 files changed, 235 insertions(+), 3 deletions(-)
 create mode 100644 testing/e2e/src/routes/api.prompt-cache-wire.ts
 create mode 100644 testing/e2e/tests/prompt-cache-wire.spec.ts

diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index be8bc8fd24..552ce72d32 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -60,6 +60,7 @@ import { Route as ApiSandboxFilePersistenceRouteImport } from './routes/api.sand
 import { Route as ApiSandboxDurabilityRouteImport } from './routes/api.sandbox-durability'
 import { Route as ApiProviderToolDispatchWireRouteImport } from './routes/api.provider-tool-dispatch-wire'
 import { Route as ApiProviderSearchMetadataWireRouteImport } from './routes/api.provider-search-metadata-wire'
+import { Route as ApiPromptCacheWireRouteImport } from './routes/api.prompt-cache-wire'
 import { Route as ApiPortableSkillsWireRouteImport } from './routes/api.portable-skills-wire'
 import { Route as ApiPersistenceDurabilityRouteImport } from './routes/api.persistence-durability'
 import { Route as ApiOtelUsageRouteImport } from './routes/api.otel-usage'
@@ -400,6 +401,11 @@ const ApiProviderSearchMetadataWireRoute =
     path: '/api/provider-search-metadata-wire',
     getParentRoute: () => rootRouteImport,
   } as any)
+const ApiPromptCacheWireRoute = ApiPromptCacheWireRouteImport.update({
+  id: '/api/prompt-cache-wire',
+  path: '/api/prompt-cache-wire',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiPortableSkillsWireRoute = ApiPortableSkillsWireRouteImport.update({
   id: '/api/portable-skills-wire',
   path: '/api/portable-skills-wire',
@@ -903,6 +909,7 @@ export interface FileRoutesByFullPath {
   '/api/otel-usage': typeof ApiOtelUsageRoute
   '/api/persistence-durability': typeof ApiPersistenceDurabilityRoute
   '/api/portable-skills-wire': typeof ApiPortableSkillsWireRoute
+  '/api/prompt-cache-wire': typeof ApiPromptCacheWireRoute
   '/api/provider-search-metadata-wire': typeof ApiProviderSearchMetadataWireRoute
   '/api/provider-tool-dispatch-wire': typeof ApiProviderToolDispatchWireRoute
   '/api/sandbox-durability': typeof ApiSandboxDurabilityRoute
@@ -1032,6 +1039,7 @@ export interface FileRoutesByTo {
   '/api/otel-usage': typeof ApiOtelUsageRoute
   '/api/persistence-durability': typeof ApiPersistenceDurabilityRoute
   '/api/portable-skills-wire': typeof ApiPortableSkillsWireRoute
+  '/api/prompt-cache-wire': typeof ApiPromptCacheWireRoute
   '/api/provider-search-metadata-wire': typeof ApiProviderSearchMetadataWireRoute
   '/api/provider-tool-dispatch-wire': typeof ApiProviderToolDispatchWireRoute
   '/api/sandbox-durability': typeof ApiSandboxDurabilityRoute
@@ -1162,6 +1170,7 @@ export interface FileRoutesById {
   '/api/otel-usage': typeof ApiOtelUsageRoute
   '/api/persistence-durability': typeof ApiPersistenceDurabilityRoute
   '/api/portable-skills-wire': typeof ApiPortableSkillsWireRoute
+  '/api/prompt-cache-wire': typeof ApiPromptCacheWireRoute
   '/api/provider-search-metadata-wire': typeof ApiProviderSearchMetadataWireRoute
   '/api/provider-tool-dispatch-wire': typeof ApiProviderToolDispatchWireRoute
   '/api/sandbox-durability': typeof ApiSandboxDurabilityRoute
@@ -1293,6 +1302,7 @@ export interface FileRouteTypes {
     | '/api/otel-usage'
     | '/api/persistence-durability'
     | '/api/portable-skills-wire'
+    | '/api/prompt-cache-wire'
     | '/api/provider-search-metadata-wire'
     | '/api/provider-tool-dispatch-wire'
     | '/api/sandbox-durability'
@@ -1422,6 +1432,7 @@ export interface FileRouteTypes {
     | '/api/otel-usage'
     | '/api/persistence-durability'
     | '/api/portable-skills-wire'
+    | '/api/prompt-cache-wire'
     | '/api/provider-search-metadata-wire'
     | '/api/provider-tool-dispatch-wire'
     | '/api/sandbox-durability'
@@ -1551,6 +1562,7 @@ export interface FileRouteTypes {
     | '/api/otel-usage'
     | '/api/persistence-durability'
     | '/api/portable-skills-wire'
+    | '/api/prompt-cache-wire'
     | '/api/provider-search-metadata-wire'
     | '/api/provider-tool-dispatch-wire'
     | '/api/sandbox-durability'
@@ -1681,6 +1693,7 @@ export interface RootRouteChildren {
   ApiOtelUsageRoute: typeof ApiOtelUsageRoute
   ApiPersistenceDurabilityRoute: typeof ApiPersistenceDurabilityRoute
   ApiPortableSkillsWireRoute: typeof ApiPortableSkillsWireRoute
+  ApiPromptCacheWireRoute: typeof ApiPromptCacheWireRoute
   ApiProviderSearchMetadataWireRoute: typeof ApiProviderSearchMetadataWireRoute
   ApiProviderToolDispatchWireRoute: typeof ApiProviderToolDispatchWireRoute
   ApiSandboxDurabilityRoute: typeof ApiSandboxDurabilityRoute
@@ -2063,6 +2076,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiProviderSearchMetadataWireRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/prompt-cache-wire': {
+      id: '/api/prompt-cache-wire'
+      path: '/api/prompt-cache-wire'
+      fullPath: '/api/prompt-cache-wire'
+      preLoaderRoute: typeof ApiPromptCacheWireRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/portable-skills-wire': {
       id: '/api/portable-skills-wire'
       path: '/api/portable-skills-wire'
@@ -2759,6 +2779,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiOtelUsageRoute: ApiOtelUsageRoute,
   ApiPersistenceDurabilityRoute: ApiPersistenceDurabilityRoute,
   ApiPortableSkillsWireRoute: ApiPortableSkillsWireRoute,
+  ApiPromptCacheWireRoute: ApiPromptCacheWireRoute,
   ApiProviderSearchMetadataWireRoute: ApiProviderSearchMetadataWireRoute,
   ApiProviderToolDispatchWireRoute: ApiProviderToolDispatchWireRoute,
   ApiSandboxDurabilityRoute: ApiSandboxDurabilityRoute,
diff --git a/testing/e2e/src/routes/api.prompt-cache-wire.ts b/testing/e2e/src/routes/api.prompt-cache-wire.ts
new file mode 100644
index 0000000000..e50c15ff1d
--- /dev/null
+++ b/testing/e2e/src/routes/api.prompt-cache-wire.ts
@@ -0,0 +1,157 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { chat } from '@tanstack/ai'
+import type { AnyTextAdapter, PromptCacheRetention, Tool } from '@tanstack/ai'
+import { createAnthropicChat } from '@tanstack/ai-anthropic'
+import { createOpenaiChat } from '@tanstack/ai-openai'
+
+/**
+ * Wire check for the `promptCache` option of `chat()`.
+ *
+ * The route runs one chat turn four times: Anthropic and OpenAI Responses,
+ * each once with the default `promptCache` and once with `'none'`. Every turn
+ * has a `threadId`, a system prompt, and a tool. A custom `fetch` records the
+ * request body and answers with a canned stream, so no aimock fixture is
+ * needed. The route returns the four request bodies for the spec to check.
+ */
+
+const THREAD_ID = 'thread-prompt-cache-wire'
+
+const getGuitarsTool = {
+  name: 'get_guitars',
+  description: 'List the guitars in stock',
+  inputSchema: { type: 'object', properties: {} },
+} satisfies Tool
+
+const ANTHROPIC_REPLY = [
+  {
+    type: 'message_start',
+    message: {
+      id: 'msg_prompt_cache_wire',
+      type: 'message',
+      role: 'assistant',
+      content: [],
+      model: 'claude-sonnet-4-6',
+      stop_reason: null,
+      stop_sequence: null,
+      usage: { input_tokens: 5, output_tokens: 0 },
+    },
+  },
+  {
+    type: 'content_block_start',
+    index: 0,
+    content_block: { type: 'text', text: '' },
+  },
+  {
+    type: 'content_block_delta',
+    index: 0,
+    delta: { type: 'text_delta', text: 'ok' },
+  },
+  { type: 'content_block_stop', index: 0 },
+  {
+    type: 'message_delta',
+    delta: { stop_reason: 'end_turn', stop_sequence: null },
+    usage: { output_tokens: 1 },
+  },
+  { type: 'message_stop' },
+]
+
+const OPENAI_REPLY = [
+  {
+    type: 'response.created',
+    response: {
+      id: 'resp_prompt_cache_wire',
+      status: 'in_progress',
+      output: [],
+    },
+  },
+  {
+    type: 'response.output_text.delta',
+    item_id: 'msg_prompt_cache_wire',
+    output_index: 0,
+    content_index: 0,
+    delta: 'ok',
+  },
+  {
+    type: 'response.completed',
+    response: {
+      id: 'resp_prompt_cache_wire',
+      status: 'completed',
+      output: [],
+      usage: { input_tokens: 5, output_tokens: 1, total_tokens: 6 },
+    },
+  },
+]
+
+/** Sends the events as one SSE body. Both SDKs read the `event:` line. */
+function sseResponse(events: Array<{ type: string }>) {
+  const body = events
+    .map((event) => `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`)
+    .join('')
+  return new Response(body, {
+    headers: { 'Content-Type': 'text/event-stream' },
+  })
+}
+
+/** Runs one chat turn to the end. No `promptCache` means the default. */
+async function runTurn(
+  adapter: AnyTextAdapter,
+  promptCache?: PromptCacheRetention,
+) {
+  for await (const _ of chat({
+    adapter,
+    messages: [
+      {
+        role: 'user',
+        content: '[prompt-cache-wire] which guitars are in stock?',
+      },
+    ],
+    systemPrompts: ['You help the customers of a guitar shop.'],
+    tools: [getGuitarsTool],
+    threadId: THREAD_ID,
+    ...(promptCache && { promptCache }),
+  })) {
+    // Drain the stream.
+  }
+}
+
+export const Route = createFileRoute('/api/prompt-cache-wire')({
+  server: {
+    handlers: {
+      POST: async () => {
+        const bodies: Array<unknown> = []
+        const fetchReplying =
+          (events: Array<{ type: string }>): typeof fetch =>
+          async (input, init) => {
+            bodies.push(await new Request(input, init).json())
+            return sseResponse(events)
+          }
+        const anthropic = createAnthropicChat(
+          'claude-sonnet-4-6',
+          'sk-ant-e2e-test-dummy-key',
+          { fetch: fetchReplying(ANTHROPIC_REPLY) },
+        )
+        const openai = createOpenaiChat('gpt-5.2', 'sk-e2e-test-dummy-key', {
+          fetch: fetchReplying(OPENAI_REPLY),
+        })
+
+        try {
+          await runTurn(anthropic)
+          await runTurn(anthropic, 'none')
+          await runTurn(openai)
+          await runTurn(openai, 'none')
+        } catch (error) {
+          return Response.json({
+            error: error instanceof Error ? error.message : String(error),
+          })
+        }
+
+        const [anthropicDefault, anthropicNone, openaiDefault, openaiNone] =
+          bodies
+        return Response.json({
+          anthropic: { default: anthropicDefault, none: anthropicNone },
+          openai: { default: openaiDefault, none: openaiNone },
+        })
+      },
+    },
+  },
+})
diff --git a/testing/e2e/tests/anthropic-structured-usage.spec.ts b/testing/e2e/tests/anthropic-structured-usage.spec.ts
index 44b77e4b5f..023230bfd2 100644
--- a/testing/e2e/tests/anthropic-structured-usage.spec.ts
+++ b/testing/e2e/tests/anthropic-structured-usage.spec.ts
@@ -38,10 +38,12 @@ test.describe('anthropic — structured-output fallback', () => {
 
     expect(error ?? null).toBeNull()
     expect(ok).toBe(true)
+    // promptTokens is the total input: 125 uncached + 5760 cache read. The
+    // mount sends no cache write.
     expect(usage).toMatchObject({
-      promptTokens: 125,
+      promptTokens: 5885,
       completionTokens: 1346,
-      totalTokens: 1471,
+      totalTokens: 7231,
       promptTokensDetails: { cachedTokens: 5760 },
     })
     expect(timestamps.structuredOutputStart).toBeGreaterThanOrEqual(
diff --git a/testing/e2e/tests/bedrock-converse-cache.spec.ts b/testing/e2e/tests/bedrock-converse-cache.spec.ts
index 29adfc299f..688ee5e36a 100644
--- a/testing/e2e/tests/bedrock-converse-cache.spec.ts
+++ b/testing/e2e/tests/bedrock-converse-cache.spec.ts
@@ -24,8 +24,9 @@ test.describe('bedrock-converse — prompt cache checkpoints', () => {
     expect(error ?? null).toBeNull()
     expect(ok).toBe(true)
     expect(observed).toEqual({ tools: true, system: true, lastMessage: true })
+    // promptTokens is the total input: 3 uncached + 8409 cache read + 0 write.
     expect(usage).toMatchObject({
-      promptTokens: 3,
+      promptTokens: 8412,
       promptTokensDetails: { cachedTokens: 8409, cacheWriteTokens: 0 },
     })
   })
diff --git a/testing/e2e/tests/prompt-cache-wire.spec.ts b/testing/e2e/tests/prompt-cache-wire.spec.ts
new file mode 100644
index 0000000000..bfd463b860
--- /dev/null
+++ b/testing/e2e/tests/prompt-cache-wire.spec.ts
@@ -0,0 +1,51 @@
+import { test, expect } from './fixtures'
+import type { APIRequestContext } from '@playwright/test'
+
+// The route runs each chat turn with this threadId. It is the default cache key.
+const THREAD_ID = 'thread-prompt-cache-wire'
+const EPHEMERAL = { type: 'ephemeral' }
+
+interface WireResult {
+  error?: string
+  anthropic: { default: unknown; none: unknown }
+  openai: { default: unknown; none: unknown }
+}
+
+/** Gets the request bodies that `/api/prompt-cache-wire` captured. */
+async function captureWire(request: APIRequestContext) {
+  const res = await request.post('/api/prompt-cache-wire')
+  expect(res.ok()).toBe(true)
+  const result: WireResult = await res.json()
+  expect(result.error ?? null).toBeNull()
+  return result
+}
+
+test.describe('prompt cache: request wire', () => {
+  test('the default promptCache adds the cache fields', async ({ request }) => {
+    const { anthropic, openai } = await captureWire(request)
+
+    expect(anthropic.default).toMatchObject({
+      system: [{ type: 'text', cache_control: EPHEMERAL }],
+      tools: [{ name: 'get_guitars', cache_control: EPHEMERAL }],
+      messages: [
+        {
+          role: 'user',
+          content: [{ type: 'text', cache_control: EPHEMERAL }],
+        },
+      ],
+    })
+    expect(openai.default).toMatchObject({ prompt_cache_key: THREAD_ID })
+  })
+
+  test("promptCache 'none' sends no cache field", async ({ request }) => {
+    const { anthropic, openai } = await captureWire(request)
+
+    // Both requests reached the fetch, with the tool on them.
+    expect(anthropic.none).toMatchObject({ tools: [{ name: 'get_guitars' }] })
+    expect(openai.none).toMatchObject({ tools: [{ name: 'get_guitars' }] })
+    // Custom tools always send `cache_control: null`, so look for a set
+    // marker only.
+    expect(JSON.stringify(anthropic.none)).not.toContain('"cache_control":{')
+    expect(JSON.stringify(openai.none)).not.toContain('prompt_cache')
+  })
+})

From 41e8abb0545c4773f371e8a03d7863a74e923ae3 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 11:19:44 +0200
Subject: [PATCH 163/286] chore: add the prompt caching changeset

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/prompt-caching-default.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
 create mode 100644 .changeset/prompt-caching-default.md

diff --git a/.changeset/prompt-caching-default.md b/.changeset/prompt-caching-default.md
new file mode 100644
index 0000000000..0567be4e64
--- /dev/null
+++ b/.changeset/prompt-caching-default.md
@@ -0,0 +1,26 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-harness': minor
+'@tanstack/ai-anthropic': minor
+'@tanstack/ai-bedrock': minor
+'@tanstack/ai-openai': minor
+'@tanstack/ai-models': minor
+'@tanstack/ai-openrouter': minor
+'@tanstack/ai-mistral': minor
+'@tanstack/ai-claude-code': minor
+---
+
+Prompt caching is now on by default. Each `chat()` call asks the provider to cache the stable start of the request (system prompt, tools, and earlier messages), so repeated requests cost less and answer sooner.
+
+- New `chat()` option `promptCache`: `'none' | 'short' | 'long'`, or `{ retention, key }`. The default is `'short'`. The key is `promptCache.key`, else the `threadId` or `conversationId` that you give.
+- To turn it off, pass `promptCache: 'none'`. Do this for a large prompt that you send to Claude one time only, because Claude bills the cache write.
+- Each adapter sends its own fields:
+  - Claude (Anthropic, Bedrock, OpenRouter) gets cache markers.
+  - OpenAI gets `prompt_cache_key`, and `prompt_cache_retention` or `prompt_cache_options` on `'long'`.
+  - Mistral gets `prompt_cache_key`.
+  - OpenRouter gets `sessionId`.
+- A manual `cache_control`, `cachePoint`, `prompt_cache_key`, or `sessionId` wins over the automatic value.
+- Harness sessions cache by default too. `defineHarness({ promptCache })` sets the default, and `host.open(harness, { threadId, promptCache })` overrides it for one session.
+- `usage.promptTokens` is now the total input on Anthropic, Bedrock, and Claude Code: the uncached tokens plus the cache reads and writes. Before, it was the uncached tokens only. The cache parts stay in `promptTokensDetails`.
+- New usage counts: cache reads on Mistral and on the OpenRouter Responses adapter. The harness `usage()` plugin also counts cache reads and writes.
+- New compat field `supportsExplicitPromptCacheMode` on `openaiCompatible` and on `ModelCompat`.

From a501c7b8dc9ed464599d39dbfbaa580c07e3be21 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 12:11:30 +0200
Subject: [PATCH 164/286] feat(ai, ai-harness): route a harness turn to root
 agents

A harness can now send a turn to its root agents, with the same picks as
`subagents.router`.

- `defineHarness({ routing: { router, order, strategy, limits, sandbox } })`.
  The router gets the chat() router fields plus `session`, `input`,
  `operationId`, `inputId`, and the turn's main `adapter`. It picks from
  the harness `agents` and the plugin `agents`, not from `subagents`.
- On 'main', the turn runs as before. On a pick, the routed path of chat()
  runs the plan. `handoff` runs the main model after the agents, with its
  subagent tools. `resolve` continues a routed plan without the router.
- In `@tanstack/ai`, a pick can give an agent its input as
  `{ name, input }`. The routed path checks it with the agent's
  `inputSchema`, and a resumed plan keeps it. `subagentRoute` adds
  `needsInput(result)` and `pick(result, { inputs })`.
- A routed turn of `subagents.router` now gets the full history, holds a
  run lease, and returns the agents' text.
---
 .changeset/harness-routing.md                 |   8 +
 docs/chat/subagents.md                        |  69 +-
 docs/config.json                              |   4 +-
 docs/harness/plugins.md                       |   2 +-
 docs/harness/subagents.md                     |  78 ++-
 packages/ai-harness/src/define.ts             |  61 +-
 packages/ai-harness/src/index.ts              |   2 +
 packages/ai-harness/src/plugins.ts            |   7 +-
 packages/ai-harness/src/session.ts            | 190 +++++-
 packages/ai-harness/src/types.ts              |   6 +-
 packages/ai-harness/tests/routing.test.ts     | 617 ++++++++++++++++++
 .../ai-harness/tests/subagent-router.test.ts  | 177 +++++
 .../activities/chat/agents/define-agent.ts    |  11 +-
 .../ai/src/activities/chat/agents/route.ts    |  96 ++-
 .../ai/src/activities/chat/agents/spawn.ts    |  75 ++-
 packages/ai/src/activities/chat/index.ts      | 103 ++-
 packages/ai/src/index.ts                      |   1 +
 packages/ai/tests/define-agent.test.ts        | 311 ++++++---
 packages/ai/tests/subagent-interrupts.test.ts |  82 +++
 .../ai/tests/subagent-route-types.test-d.ts   |  66 ++
 testing/e2e/fixtures/harness/basic.json       |  48 ++
 testing/e2e/src/routes/api.harness-test.ts    |  91 +++
 testing/e2e/tests/harness.spec.ts             |  18 +
 23 files changed, 1933 insertions(+), 190 deletions(-)
 create mode 100644 .changeset/harness-routing.md
 create mode 100644 packages/ai-harness/tests/routing.test.ts
 create mode 100644 packages/ai-harness/tests/subagent-router.test.ts
 create mode 100644 packages/ai/tests/subagent-route-types.test-d.ts

diff --git a/.changeset/harness-routing.md b/.changeset/harness-routing.md
new file mode 100644
index 0000000000..558b7c30ed
--- /dev/null
+++ b/.changeset/harness-routing.md
@@ -0,0 +1,8 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-harness': minor
+---
+
+`@tanstack/ai`: a router pick can give an agent its input. Anywhere a pick has a name, it can have `{ name, input }`, so `subagents.router` can start an agent with `inputSchema`. `chat()` checks the input against the schema, and `run` reads it as `ctx.input`. A resume keeps each input of the plan. `subagentRoute` gets `needsInput(result)`, which lists the picked agents with an `inputSchema`, and `pick(result, { inputs })`, which puts each input on its name. `inputs` is typed from each schema.
+
+`@tanstack/ai-harness`: `defineHarness` takes `routing: { router, order, strategy, limits, sandbox }`. The router runs at the start of each new turn. It sends the turn to the main model, or to root agents: the harness `agents` and the `agents` of plugins. Its context has the fields of the `subagents.router` context, plus `session`, `input`, `operationId`, `inputId`, and `adapter`. With `strategy: 'handoff'`, the main model answers after the agents, in the same turn. A resolve continues the routed plan without a new router call. A routed turn holds a run lease, and its text is the text of the agents. A `subagents.router` turn gets the same lease and text. `HarnessRouting` and `HarnessRouterContext` are exported.
diff --git a/docs/chat/subagents.md b/docs/chat/subagents.md
index 9da0c131fb..e34dd64678 100644
--- a/docs/chat/subagents.md
+++ b/docs/chat/subagents.md
@@ -90,6 +90,8 @@ The router can return:
 - `{ names, order }`
 - `{ steps }`
 
+Anywhere a name goes, `{ name, input }` can go too, for example `{ name: 'pricer', input: { vendor: 'Acme' } }`. An agent with `inputSchema` needs it.
+
 `subagents.order` is the default for an array. `parallel` starts the names together. `sequence` runs them one after another, and each later child reads the earlier child text. Omit `order` to get `parallel`.
 
 `subagentRoute` asks Jev for the order. Jev picks `parallel` when no agent must read text from another agent. The same topic is not a reason to wait. Jev picks `sequence` only when a later agent must read the earlier text, such as research notes and then a draft.
@@ -154,6 +156,69 @@ const stream = chat({
 })
 ```
 
+**Give a routed agent its input.** An agent with `inputSchema` gets its input from the router. `route.needsInput(result)` lists the picked agents that need one, each with its schema. Make each input. Then pass them to `route.pick(result, { inputs })`. Here the model writes each input, with the schema as `outputSchema`:
+
+```ts
+import { chat, decide, defineAgent, subagentRoute } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { typesafeDecider } from '@tanstack/ai-typesafe'
+import { z } from 'zod'
+
+const writer = defineAgent({
+  name: 'writer',
+  description: 'Writes the post',
+  run: async function* () {},
+})
+const pricer = defineAgent({
+  name: 'pricer',
+  description: 'Compares the plans and prices of one vendor',
+  inputSchema: z.object({ vendor: z.string() }),
+  run: (ctx) =>
+    ctx.chat({
+      adapter: openaiText('gpt-5.6'),
+      messages: [{ role: 'user', content: `Compare the plans of ${ctx.input.vendor}` }],
+      stream: false,
+    }),
+})
+const messages = [
+  { role: 'user' as const, content: 'What does Acme cost? Write a post about it.' },
+]
+
+const stream = chat({
+  adapter: openaiText('gpt-5.6'),
+  messages,
+  subagents: {
+    agents: [pricer, writer],
+    router: async ({ messages: turnMessages, agents }) => {
+      const route = subagentRoute(agents, { then: ['writer'] })
+      const result = await decide({
+        adapter: typesafeDecider('jev-latest'),
+        state: turnMessages,
+        questions: route.questions,
+      })
+      const inputs = Object.fromEntries(
+        await Promise.all(
+          route.needsInput(result).map(async ({ name, inputSchema }) => [
+            name,
+            await chat({
+              adapter: openaiText('gpt-5.6'),
+              messages: turnMessages,
+              outputSchema: inputSchema,
+            }),
+          ]),
+        ),
+      )
+      return route.pick(result, { inputs })
+    },
+  },
+})
+```
+
+- `inputs` is typed. Each key is the name of an agent with `inputSchema`, and the value has the type of that schema.
+- If a picked agent with a schema has no input, `pick` throws `Agent "pricer" needs input. Pass it in inputs.`
+- `chat()` checks each input against the schema before the child starts. If an input does not match, `chat()` throws, and the child does not start.
+- `run` reads the input as `ctx.input`. A resumed child gets the same input.
+
 **Without a router.** The library adds one synthetic server tool per agent. The main model calls that tool. The public stream still emits `SUBAGENT_STARTED` / `SUBAGENT_FINISHED` (or `SUBAGENT_ERROR`) and nested parts. The UI does not treat spawn as a normal tool card. The child's events stream while the tool runs, and the child's text becomes the tool result. The child reads the conversation as it is at that tool call.
 
 ## Let the model write the brief
@@ -202,7 +267,7 @@ const stream = chat({
 - If the input does not match the schema, the model gets a tool error and can call the tool again. The child does not start.
 - `ctx.messages` still holds the parent conversation. Add parts of it when the child needs more context.
 - A resumed child gets the same `ctx.input` as the first run.
-- `inputSchema` needs tool mode. If `subagents.router` is set and an agent has `inputSchema`, `chat()` throws.
+- With `subagents.router`, the router gives the input. See [Route, or let the model pick](#route-or-let-the-model-pick).
 
 To show the brief in the UI, see [Show the brief on a card](#show-the-brief-on-a-card).
 
@@ -655,7 +720,7 @@ function Briefs({ message }: { message: UIMessage }) {
 }
 ```
 
-A child that a router started has no `parentToolCallId`, so it has no brief.
+A child that a router started has no `parentToolCallId`, so `briefOf` finds no brief for it.
 
 ### Style one child's parts
 
diff --git a/docs/config.json b/docs/config.json
index 78a02c9505..21395527ab 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -166,7 +166,7 @@
           "label": "Subagents",
           "to": "chat/subagents",
           "addedAt": "2026-09-21",
-          "updatedAt": "2026-09-28"
+          "updatedAt": "2026-10-02"
         },
         {
           "label": "Agentic Cycle",
@@ -942,7 +942,7 @@
           "label": "Write a plugin",
           "to": "harness/plugins",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-10-01"
+          "updatedAt": "2026-10-02"
         },
         {
           "label": "Build a coding agent",
diff --git a/docs/harness/plugins.md b/docs/harness/plugins.md
index c6845cb957..6dec355cfa 100644
--- a/docs/harness/plugins.md
+++ b/docs/harness/plugins.md
@@ -32,7 +32,7 @@ Add it with `plugins: () => [today]` in `defineHarness`. `setup` runs once per s
 - `prompts`: text for the system prompt. A function runs for each turn, so it can show current state.
 - `middleware`: chat middleware for the lead turn, the same type as `chat({ middleware })`. `agentMiddleware` is for agent runs, see [Middleware in every agent](#middleware-in-every-agent).
 - `generationMiddleware`: middleware for the activities agents call.
-- `agents`: agents added to `session.agents`.
+- `agents`: agents added to `session.agents`. `routing.router` can send a turn to them too, see [Route a turn to an agent](./subagents#route-a-turn-to-an-agent).
 - `subagents`: agents the model can call as tools. They are also added to `session.agents`. [Delegate to coding agents](./coding-agents) uses them.
 - `commands`: user actions, see below.
 - `config`: session settings, see below.
diff --git a/docs/harness/subagents.md b/docs/harness/subagents.md
index d13f537e6f..eeb61d81e4 100644
--- a/docs/harness/subagents.md
+++ b/docs/harness/subagents.md
@@ -2,16 +2,17 @@
 title: Run agents from a harness
 id: harness-subagents
 order: 14
-description: "Start typed agents from commands and plugins, run them in groups, call a whole harness as a child, and keep the tree within limits."
+description: "Start typed agents from commands and plugins, run them in groups, route a turn to an agent, call a whole harness as a child, and keep the tree within limits."
 keywords:
   - tanstack ai
   - harness
   - subagents
   - agents
+  - routing
   - limits
 ---
 
-A review command needs an explorer to collect facts, then a reviewer to judge them. A research task needs three explorers at once. In a harness, plugins and commands start agents from code, and a whole harness can be a child of another one.
+A review command needs an explorer to collect facts, then a reviewer to judge them. A research task needs three explorers at once. In a harness, plugins and commands start agents from code, and a whole harness can be a child of another one. A router can also send a whole turn to an agent.
 
 ## Run agents from a plugin
 
@@ -66,6 +67,78 @@ To track usage or apply a policy in each of these runs, see [Middleware in every
 
 The harness saves the images, audio, and video that these agents make, and the UI shows them. See [Media that agents make](./media#media-that-agents-make).
 
+## Route a turn to an agent
+
+Your harness has a writer and a pricer, but the main model answers every turn. Add `routing.router` to send a turn to the agent that can answer it. The router runs at the start of each new turn: a `prompt`, a `followUp`, or the wake turn of a background agent.
+
+```ts
+import { chat, decide, defineAgent, subagentRoute } from '@tanstack/ai'
+import { defineHarness } from '@tanstack/ai-harness'
+import { openaiText } from '@tanstack/ai-openai'
+import { typesafeDecider } from '@tanstack/ai-typesafe'
+import { z } from 'zod'
+
+const writer = defineAgent({
+  name: 'writer',
+  description: 'Writes blog posts',
+  run: (ctx) => ctx.chat({ adapter: openaiText('gpt-5.6'), stream: false }),
+})
+
+const pricer = defineAgent({
+  name: 'pricer',
+  description: 'Compares the plans and prices of one vendor',
+  inputSchema: z.object({ vendor: z.string() }),
+  run: (ctx) =>
+    ctx.chat({
+      adapter: openaiText('gpt-5.6'),
+      messages: [{ role: 'user', content: `Compare the plans of ${ctx.input.vendor}` }],
+      stream: false,
+    }),
+})
+
+export const studio = defineHarness({
+  name: 'acme/studio',
+  adapter: openaiText('gpt-5.6'),
+  agents: [writer, pricer],
+  routing: {
+    router: async ({ agents, messages, adapter }) => {
+      const route = subagentRoute(agents)
+      const result = await decide({
+        adapter: typesafeDecider('jev-latest'),
+        state: messages,
+        questions: route.questions,
+      })
+      const inputs = Object.fromEntries(
+        await Promise.all(
+          route.needsInput(result).map(async ({ name, inputSchema }) => [
+            name,
+            await chat({ adapter, messages, outputSchema: inputSchema }),
+          ]),
+        ),
+      )
+      return route.pick(result, { inputs })
+    },
+  },
+})
+```
+
+- `agents` holds the root agents of the turn: the harness `agents` and the `agents` that plugins add. An agent that is only in `subagents` is not in this list.
+- `subagentRoute(agents)` makes one yes/no question for each agent, from its `description`. `decide()` answers them.
+- `route.needsInput(result)` lists the picked agents that have an `inputSchema`, each with its schema. Here the main model writes each input. `adapter` is the main adapter of the turn, with the user's keys.
+- `route.pick(result, { inputs })` gives each agent its input. If a picked agent with a schema has no input, `pick` throws.
+
+The router can also return a pick of its own: `'main'`, a name, a list of names, `{ names, order }`, or `{ steps }`. Anywhere a name goes, `{ name, input }` can go too, for example `{ name: 'pricer', input: { vendor: 'Acme' } }`. If a picked agent has an `inputSchema` and no input, the turn fails with `Agent "pricer" needs input. Return { name: 'pricer', input } from the router.` See [Route, or let the model pick](../chat/subagents#route-or-let-the-model-pick) for each pick.
+
+The router also gets `session`, the `input` of the turn as the user sent it, `operationId`, `inputId`, and `abortSignal`. Next to `router`, `routing` takes `order`, `strategy`, `limits`, and `sandbox`. They work the same as in `subagents`.
+
+What the turn does with the pick:
+
+- `'main'`: the main model answers, with its `subagents` as usual.
+- Agent names: only those agents run. The harness does not call the main model. The turn text is their answer as the transcript keeps it, for example `pricer:\n...`.
+- `strategy: 'handoff'`: the agents run first. Then the main model answers in the same turn. It reads their text and keeps its subagent tools.
+- An interrupt in a routed agent ends the turn. `session.resolve` continues the same plan, and it does not call the router again.
+- A steer that you send during a routed turn waits. It runs as its own turn, and the router picks for that turn too.
+
 ## Call a harness as a child
 
 `harnessAgent` turns a harness into an agent. Put it in `subagents.agents`, and the main model calls it as a tool. The child harness keeps its own tools, plugins, and history.
@@ -108,5 +181,6 @@ See [subagent limits](../chat/subagents) for what each limit does.
 ## What you have now
 
 - Commands and plugins that start typed agents, alone or in groups.
+- A router that sends each turn to the right agent, and gives each agent its input.
 - Harnesses that call other harnesses as tools.
 - A tree of children that stays within limits.
diff --git a/packages/ai-harness/src/define.ts b/packages/ai-harness/src/define.ts
index 1f225582e1..92019d9f36 100644
--- a/packages/ai-harness/src/define.ts
+++ b/packages/ai-harness/src/define.ts
@@ -5,15 +5,18 @@ import type {
   AnyTool,
   InterruptDefinition,
   KeyedAdapter,
+  ModelMessage,
   PromptCacheOptions,
+  SubagentRouterPick,
   SubagentsBag,
   SystemPrompt,
 } from '@tanstack/ai'
 import type { AnyAgent } from './agents'
 import type { MediaOptions } from './media'
 import type { HarnessPlugin } from './plugins'
+import type { HarnessSession } from './session'
 import type { HarnessTurnOptions, RecoverHook } from './turn'
-import type { BusyPolicy } from './types'
+import type { BusyPolicy, UserInput } from './types'
 
 /** The `subagents` option: the same as `chat({ subagents })`. */
 export type HarnessSubagents<TSubagents extends ReadonlyArray<AnyAgent>> = Omit<
@@ -21,6 +24,56 @@ export type HarnessSubagents<TSubagents extends ReadonlyArray<AnyAgent>> = Omit<
   'binding'
 >
 
+/**
+ * What `routing.router` gets: the fields of the `subagents.router` context,
+ * plus the harness fields of the turn.
+ */
+export interface HarnessRouterContext {
+  /** The model messages of the turn: the history, then the new user message. */
+  messages: Array<ModelMessage>
+  /**
+   * The root agents of this turn, in registration order: the harness
+   * `agents`, then the `agents` of session plugins, then of run plugins. An
+   * agent that is only in `subagents` is not in this list.
+   */
+  agents: ReadonlyArray<AnyAgent>
+  /** Aborted when the turn is cancelled. */
+  abortSignal?: AbortSignal
+  session: HarnessSession
+  /**
+   * The user input of the turn as sent: text, or content parts. `undefined`
+   * for a turn with no new user message.
+   */
+  input?: UserInput
+  /** The id of the turn operation. */
+  operationId: string
+  /** The id of the turn input, when the turn has one. */
+  inputId?: string
+  /** The main text adapter of the turn, with the user's keys bound. */
+  adapter: AnyTextAdapter
+}
+
+/**
+ * The `routing` option. The other fields mean the same as in `subagents`.
+ * `limits` defaults to `subagents.limits`. With `strategy: 'handoff'`, the
+ * main model answers after the agents, in the same turn, and it keeps its
+ * `subagents`.
+ */
+export interface HarnessRouting extends Pick<
+  SubagentsBag,
+  'order' | 'strategy' | 'limits' | 'sandbox'
+> {
+  /**
+   * Pick who answers the turn, with the picks of `subagents.router`:
+   * `'main'`, an agent name, a list of names, `{ names, order }`, or
+   * `{ steps }`. Give an agent with `inputSchema` its input with
+   * `{ name, input }`. A throw fails the turn.
+   */
+  router: (
+    ctx: HarnessRouterContext,
+  ) => SubagentRouterPick | Promise<SubagentRouterPick>
+}
+
 /**
  * Limits for one input on a durable host (a host with `stores.log`). A host
  * without a log does not read them.
@@ -91,6 +144,12 @@ export interface HarnessConfig<
    * They are also registered in `session.agents`.
    */
   subagents?: HarnessSubagents<TSubagents>
+  /**
+   * A router for each new turn. It sends the turn to the main model, or to
+   * root agents: the harness `agents` and the `agents` of plugins. A resolve
+   * continues the turn it answers, so it does not call the router.
+   */
+  routing?: HarnessRouting
   /** Called once per session, so every session gets fresh plugin instances. */
   plugins?: () => ReadonlyArray<HarnessPlugin>
   /** What a `prompt` does while a chat turn runs. Default `'queue'`. */
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index e79cba318f..c7e3d703bf 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -5,6 +5,8 @@ export type {
   HarnessConfig,
   HarnessDefinition,
   HarnessDurability,
+  HarnessRouterContext,
+  HarnessRouting,
   HarnessSubagents,
 } from './define'
 
diff --git a/packages/ai-harness/src/plugins.ts b/packages/ai-harness/src/plugins.ts
index 86bb1c5177..110c08efce 100644
--- a/packages/ai-harness/src/plugins.ts
+++ b/packages/ai-harness/src/plugins.ts
@@ -57,7 +57,7 @@ export interface PluginContributions {
   agentMiddleware?: ReadonlyArray<AnyChatMiddleware>
   /** Middleware for the activities agents call (`ctx.generateImage`, ...). */
   generationMiddleware?: ReadonlyArray<AnyGenerationMiddleware>
-  /** Agents added to `session.agents`. */
+  /** Agents added to `session.agents`. `routing.router` can pick them. */
   agents?: ReadonlyArray<AnyAgent>
   /**
    * Agents the main model can call as tools, merged into the turn's
@@ -311,6 +311,8 @@ export interface MountedPlugins {
     prepare: NonNullable<PluginContributions['prepareTools']>
     owner: string
   }>
+  /** The `agents` of the plugins, in plugin order: root agents for routing. */
+  agents: Array<AnyAgent>
   /** Agents plugins give the main model, in plugin order. */
   subagents: Array<AnyAgent>
   /** Who contributed what, for `session.inspect()`. */
@@ -505,6 +507,7 @@ export async function mountPlugins(
   const adapters: MountedPlugins['adapters'] = []
   const discoverers: MountedPlugins['discoverers'] = []
   const preparers: MountedPlugins['preparers'] = []
+  const agents: Array<AnyAgent> = []
   const subagents: Array<AnyAgent> = []
   const services = env.services ?? NO_SERVICES
   // `ctx.commands.ready`: resolves after the last plugin is set up. A failed
@@ -677,6 +680,7 @@ export async function mountPlugins(
       }
       for (const agent of contributions.agents ?? []) {
         env.registry.add(agent, plugin.name)
+        agents.push(agent)
       }
       for (const agent of contributions.subagents ?? []) {
         env.registry.add(agent, plugin.name)
@@ -735,6 +739,7 @@ export async function mountPlugins(
     adapters,
     discoverers,
     preparers,
+    agents,
     subagents,
     owners: {
       plugins: plugins.map((plugin) => ({
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index f9ea121fc1..e3ab719933 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -1,12 +1,14 @@
 import {
   EventType,
   RUN_CANCEL_REASON,
+  StreamProcessor,
   SubagentBudget,
   chat,
   compactForModel,
   convertSchemaToJsonSchema,
   createSubagentId,
   maxIterations,
+  modelMessagesToUIMessages,
   runAgentStream,
   validateWithStandardSchema,
 } from '@tanstack/ai'
@@ -51,6 +53,9 @@ import type {
   SchemaInput,
   StreamChunk,
   SubagentBinding,
+  SubagentRouterPick,
+  SubagentsBag,
+  UIMessage,
 } from '@tanstack/ai'
 import type {
   AIPersistence,
@@ -247,6 +252,11 @@ interface QueuedTurn {
   resume?: Array<RunAgentResumeItem>
   parentRunId?: string
   inputId?: string
+  /**
+   * A resolve of a turn that `routing` sent to root agents: the messages it
+   * continues from, with the agents' cards.
+   */
+  routed?: { messages: Array<UIMessage> }
 }
 
 /** Limits for a harness's children when `subagents.limits` is not set. */
@@ -315,12 +325,24 @@ const CHAT_OPS = new Set<string>(['prompt', 'steer', 'followUp', 'resolve'])
 /** Why a turn stops when its input passes its time limit. */
 const TIMEOUT_REASON = 'harness:input-timeout'
 
-/** The text of the last assistant message, for an operation rebuilt from the log. */
+/**
+ * The text of the last assistant message: the answer of an operation rebuilt
+ * from the log, or of a routed turn.
+ */
 function lastAssistantText(messages: ReadonlyArray<ModelMessage>) {
   const last = messages.findLast((message) => message.role === 'assistant')
   return typeof last?.content === 'string' ? last.content : ''
 }
 
+/**
+ * True when chat() runs its routed path for this bag: the router picks, and
+ * the engine does not run. So the middleware that gives the engine its
+ * history and its run lease does not run, and the turn does that work.
+ */
+function isRoutedBag(bag: Pick<SubagentsBag, 'agents' | 'router'> | undefined) {
+  return bag !== undefined && bag.agents.length > 0 && bag.router !== undefined
+}
+
 /** The turn has its final answer: an assistant message with no open tool call after it was applied. */
 function hasFinalAnswer(
   messages: ReadonlyArray<ModelMessage>,
@@ -422,8 +444,16 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   private readonly joining = new Set<string>()
   private readonly pendingNotes: Array<string> = []
   private activeTurn: OperationImpl<ChatTurnResult> | undefined
+  /**
+   * The last turn stopped for these interrupts. `routed`: the root agents of
+   * a routed turn stopped. The resolve continues their saved plan.
+   */
   private interrupted:
-    | { runId: string; interrupts: Array<Interrupt> }
+    | {
+        runId: string
+        interrupts: Array<Interrupt>
+        routed?: QueuedTurn['routed']
+      }
     | undefined
   private plugins: ReadonlyArray<HarnessPlugin> = []
   private sessionPlugins: MountedPlugins | undefined
@@ -866,11 +896,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       this.reject(inputId, 'busy')
       return { inputId, status: 'rejected', reason: 'busy' }
     }
-    const parentRunId = this.interrupted.runId
+    const { runId: parentRunId, routed } = this.interrupted
     this.interrupted = undefined
     const operation = this.createTurnOperation()
     this.bindTurn(inputId, operation)
-    this.enqueueTurn({ operation, resume, parentRunId, inputId })
+    this.enqueueTurn({ operation, resume, parentRunId, inputId, routed })
     return this.keep({ inputId, status: 'accepted', operationId: operation.id })
   }
 
@@ -1920,6 +1950,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     this.publishStarted(operation)
 
     let runPlugins: MountedPlugins | undefined
+    let stopRunLease = () => {}
+    /** The next chat() call runs the root agents that `routing` picked. */
+    let isRootPart = false
+    /** The messages of the root part, with the agents' cards. */
+    let cardMessages: Array<UIMessage> | undefined
     let text = ''
     let interrupts: Array<Interrupt> | undefined
     let failure: string | undefined
@@ -1960,6 +1995,19 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         ...(session?.subagents ?? []),
         ...(runPlugins?.subagents ?? []),
       ]
+      const subagents =
+        subagentList.length > 0
+          ? { ...this.harness.subagents, agents: subagentList }
+          : undefined
+      // Agents `routing` can pick: the harness's own, then the plugins'. An
+      // agent object counts once.
+      const rootAgents = [
+        ...new Set([
+          ...(this.harness.agents ?? []),
+          ...(session?.agents ?? []),
+          ...(runPlugins?.agents ?? []),
+        ]),
+      ]
       const picked = [
         ...(session?.adapters ?? []),
         ...(runPlugins?.adapters ?? []),
@@ -2008,8 +2056,68 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         throw new Error('The session is not open yet.')
       }
       const durableTools = this.durableTools()
-      const turnHooks = this.harness.turn
       const signal = operation.abortController.signal
+      const { routing } = this.harness
+      // A new turn asks the router once. A resolve does not: it continues the
+      // turn it answers, the main model or the saved plan of the root agents.
+      let pick: SubagentRouterPick | undefined
+      if (routing && rootAgents.length > 0 && turn.resume === undefined) {
+        const history = await this.messages.loadThread(this.threadId)
+        pick = await routing.router({
+          messages: [...history, ...(message ? [message] : [])],
+          agents: rootAgents,
+          abortSignal: signal,
+          session: this,
+          ...(turn.message !== undefined ? { input: turn.message } : {}),
+          operationId: operation.id,
+          ...(turn.inputId ? { inputId: turn.inputId } : {}),
+          adapter,
+        })
+      }
+      const isRootTurn =
+        turn.routed !== undefined || (pick ?? 'main') !== 'main'
+      const rootBag =
+        routing && isRootTurn
+          ? {
+              ...routing,
+              agents: rootAgents,
+              router: () => {
+                // A resolve has no pick. chat() continues its saved plan.
+                if (pick === undefined) {
+                  throw new Error('The routed turn has no saved plan.')
+                }
+                return pick
+              },
+              // The harness runs the handoff, so the main model keeps its
+              // subagents.
+              strategy: 'exclusive' as const,
+            }
+          : undefined
+      isRootPart = rootBag !== undefined
+      /** The subagents of the next chat() call. */
+      let bag = rootBag ?? subagents
+      let routed = isRoutedBag(bag)
+      if (routed) {
+        // The same record withPersistence opens, so its open resumes this one.
+        const { runs } = this.persistence.stores
+        await runs?.createOrResume({
+          runId: operation.id,
+          threadId: this.threadId,
+          startedAt: Date.now(),
+        })
+        stopRunLease = await holdRunLease(
+          runs,
+          operation.id,
+          this.hostId,
+          this.lease,
+        )
+      }
+      // ponytail: a routed turn runs no turn hooks (no retry, no joins, no
+      // beforeFinish), also in the main part of a handoff. A steer waits and
+      // runs as its own turn. Give the handoff part the hooks if apps need them.
+      const turnHooks = rootBag ? undefined : this.harness.turn
+      /** The messages a resolve of a routed turn continues from. */
+      let routedFrom = turn.routed?.messages
       /** Retries since the last finished tool phase. */
       let retries = 0
       /** How many times `turn.beforeFinish` continued this turn. */
@@ -2023,9 +2131,25 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         let runError: { message: string; code?: string } | undefined
         let heldError: StreamChunk | undefined
         try {
+          // The router and the routed agents get the full history. The
+          // stores merge by message id, so no message is saved twice.
+          const history =
+            routed && !routedFrom
+              ? await this.messages.loadThread(this.threadId)
+              : []
+          const turnMessages = [...history, ...(message ? [message] : [])]
+          // The store keeps each agent in its own thread, and chat() finds a
+          // stopped agent in the cards that a client sends back. So the
+          // harness keeps the cards of the root part, as a client does.
+          const cards = isRootPart
+            ? new StreamProcessor({
+                initialMessages:
+                  routedFrom ?? modelMessagesToUIMessages(turnMessages),
+              })
+            : undefined
           const stream = chat({
             adapter,
-            messages: message ? [message] : [],
+            messages: routedFrom ?? turnMessages,
             systemPrompts: [
               ...(this.harness.systemPrompts ?? []),
               ...[...(session?.prompts ?? []), ...(runPlugins?.prompts ?? [])]
@@ -2041,7 +2165,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
               ...(session?.middleware ?? []),
               ...(runPlugins?.middleware ?? []),
               ...(durableTools ? [durableTools] : []),
-              this.steering(),
+              ...(rootBag ? [] : [this.steering()]),
               // Last, because a later middleware that returns `messages` (as
               // steering does) resets what the model gets.
               mediaMiddleware({
@@ -2053,12 +2177,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
                 transcribe: this.harness.media?.transcribe,
               }),
             ],
-            ...(subagentList.length > 0
+            ...(bag
               ? {
                   subagents: {
-                    ...this.harness.subagents,
-                    agents: subagentList,
-                    limits: this.limits(),
+                    ...bag,
+                    limits: bag.limits ?? this.limits(),
                     binding: this.binding(operation, captured, runPlugins),
                   },
                 }
@@ -2085,7 +2208,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             stream: true,
           } as never) as AsyncIterable<StreamChunk>
 
+          routedFrom = undefined
           for await (const chunk of stream) {
+            cards?.processChunk(chunk)
             if (
               chunk.type === EventType.RUN_ERROR &&
               turnHooks?.onModelError &&
@@ -2121,6 +2246,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
               textBefore = text
             }
           }
+          cardMessages = cards?.getMessages()
         } catch (error) {
           // The outer catch handles a cancelled turn, a log failure, and a
           // harness without the hook, as before.
@@ -2185,16 +2311,26 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           (interrupts?.length ?? 0) > 0 ||
           signal.aborted
         if (isFinished) break
-        // Claimed, so a cancel after this check cannot leave a run with no
-        // new input.
-        const hasLateJoin = (await this.claimJoins()) > 0
-        if (!hasLateJoin) {
-          if (
-            !(await this.continueBeforeFinish(operation, turn.inputId, cycle))
-          ) {
-            break
+        if (rootBag) {
+          const isHandoff = isRootPart && routing?.strategy === 'handoff'
+          if (!isHandoff) break
+          // The agents answered. The main model answers next, with the
+          // transcript that has their answer.
+          isRootPart = false
+          bag = subagents
+          routed = isRoutedBag(bag)
+        } else {
+          // Claimed, so a cancel after this check cannot leave a run with no
+          // new input.
+          const hasLateJoin = (await this.claimJoins()) > 0
+          if (!hasLateJoin) {
+            if (
+              !(await this.continueBeforeFinish(operation, turn.inputId, cycle))
+            ) {
+              break
+            }
+            cycle += 1
           }
-          cycle += 1
         }
         message = undefined
         resume = undefined
@@ -2207,6 +2343,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           error: undefined,
         })
       }
+      // Routed agents stream their text with a subagentRunId, so the main
+      // model wrote none. The turn text is the answer the transcript keeps.
+      if (routed && text === '') {
+        text = lastAssistantText(await this.messages.loadThread(this.threadId))
+      }
     } catch (error) {
       failure = errorText(error)
       if (!operation.abortController.signal.aborted) {
@@ -2217,6 +2358,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         })
       }
     } finally {
+      stopRunLease()
       stopTimer()
       await runPlugins?.dispose().catch(() => {})
     }
@@ -2280,7 +2422,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       await settleTurn({ outcome: 'failed', error: { message: failure } })
       operation.fail('failed', new Error(failure))
     } else if (interrupts && interrupts.length > 0) {
-      this.interrupted = { runId: operation.id, interrupts }
+      this.interrupted = {
+        runId: operation.id,
+        interrupts,
+        ...(isRootPart && cardMessages
+          ? { routed: { messages: cardMessages } }
+          : {}),
+      }
       await settleTurn({ outcome: 'interrupted' })
       operation.finish('interrupted', { text, interrupts })
     } else {
diff --git a/packages/ai-harness/src/types.ts b/packages/ai-harness/src/types.ts
index 20442120b1..f05a4868a3 100644
--- a/packages/ai-harness/src/types.ts
+++ b/packages/ai-harness/src/types.ts
@@ -111,7 +111,11 @@ export interface Principal {
 
 /** What a chat turn operation resolves to. */
 export interface ChatTurnResult {
-  /** The main model's text for this turn (child agent text excluded). */
+  /**
+   * The main model's text for this turn, without the text of agents it
+   * called. When a router sends the turn to agents, it is their text, as the
+   * transcript keeps it.
+   */
   text: string
   /** Set when the turn stopped for outside input. */
   interrupts?: Array<Interrupt>
diff --git a/packages/ai-harness/tests/routing.test.ts b/packages/ai-harness/tests/routing.test.ts
new file mode 100644
index 0000000000..41fab4eead
--- /dev/null
+++ b/packages/ai-harness/tests/routing.test.ts
@@ -0,0 +1,617 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { EventType, defineAgent, toolDefinition } from '@tanstack/ai'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness, definePlugin } from '../src'
+import { gate, messageTexts, mockAdapter, text, toolCall } from './helpers'
+import type { AnyTool, SubagentRouterPick } from '@tanstack/ai'
+import type {
+  AnyAgent,
+  HarnessPlugin,
+  HarnessRouterContext,
+  HarnessRouting,
+  HarnessSession,
+  HarnessSubagents,
+  HarnessTurnOptions,
+  Operation,
+} from '../src'
+import type { Reply } from './helpers'
+
+const THREAD = 't1'
+
+/** An agent that answers `answer`, and keeps the messages of each run. */
+function textAgent(name: string, answer: string) {
+  const runs: Array<Array<string>> = []
+  const agent = defineAgent({
+    name,
+    description: `Answers ${answer}`,
+    run: async (ctx) => {
+      runs.push(messageTexts({ messages: ctx.messages }))
+      return answer
+    },
+  })
+  return { agent, runs }
+}
+
+const pricer = defineAgent({
+  name: 'pricer',
+  description: 'Prices a vendor',
+  inputSchema: z.object({ vendor: z.string() }),
+  run: async (ctx) => `Price for ${ctx.input.vendor}`,
+})
+
+/**
+ * A child model that asks approval to remove `a.txt`, then reports. `make`
+ * builds a new `cleaner` agent on the same child model, for a plugin that
+ * builds its agents in each `setup`.
+ */
+function cleaner() {
+  const execute = vi.fn(async () => ({ removed: true }))
+  const remove = toolDefinition({
+    name: 'remove',
+    description: 'Remove a file',
+    needsApproval: true,
+    inputSchema: z.object({ path: z.string() }),
+  }).server(execute)
+  const child = mockAdapter([
+    () => toolCall('remove', { path: 'a.txt' }, 'call_c'),
+    () => text('Removed a.txt'),
+  ])
+  const make = () =>
+    defineAgent({
+      name: 'cleaner',
+      description: 'Removes files',
+      run: (ctx) => ctx.chat({ adapter: child.adapter, tools: [remove] }),
+    })
+  return { make, execute }
+}
+
+/** A router that answers `picks` in order, and keeps the context of each call. */
+function scriptedRouter(...picks: Array<SubagentRouterPick>) {
+  const seen: Array<HarnessRouterContext> = []
+  const router = (ctx: HarnessRouterContext) => {
+    seen.push(ctx)
+    return picks[seen.length - 1] ?? 'main'
+  }
+  return { router, seen }
+}
+
+/** A session whose harness has `routing`. `durable` gives the host a log. */
+async function openRouting(options: {
+  durable?: boolean
+  router: HarnessRouting['router']
+  strategy?: HarnessRouting['strategy']
+  agents?: ReadonlyArray<AnyAgent>
+  subagents?: HarnessSubagents<ReadonlyArray<AnyAgent>>
+  plugins?: () => ReadonlyArray<HarnessPlugin>
+  tools?: ReadonlyArray<AnyTool>
+  turn?: HarnessTurnOptions
+  replies?: Array<Reply>
+}) {
+  const { stores } = memoryPersistence()
+  const { runs, metadata } = stores
+  const persistence = options.durable
+    ? { stores: { log: memoryLogStore(), runs, metadata } }
+    : { stores }
+  const main = mockAdapter(options.replies ?? [])
+  const host = createHarnessHost({ persistence })
+  const session = await host.open(
+    defineHarness({
+      name: 'test/routing',
+      adapter: main.adapter,
+      agents: options.agents ?? [],
+      ...(options.subagents ? { subagents: options.subagents } : {}),
+      ...(options.plugins ? { plugins: options.plugins } : {}),
+      ...(options.tools ? { tools: options.tools } : {}),
+      ...(options.turn ? { turn: options.turn } : {}),
+      routing: {
+        router: options.router,
+        ...(options.strategy ? { strategy: options.strategy } : {}),
+      },
+    }),
+    { threadId: THREAD },
+  )
+  return { host, session, runs, main }
+}
+
+async function transcriptTexts(session: HarnessSession) {
+  return messageTexts({ messages: await session.transcript() })
+}
+
+/** The turn that a receipt names, for a resolve or a steer. */
+function turnOf(session: HarnessSession, operationId: string | undefined) {
+  const operation = session.operation(operationId ?? '')
+  if (!operation) throw new Error(`No operation ${operationId}`)
+  return operation
+}
+
+/** Approve the first interrupt of `turn`, and wait for the turn that resumes. */
+async function approve(
+  session: HarnessSession,
+  turn: { interrupts?: Array<{ id: string }> },
+) {
+  const interrupt = turn.interrupts?.[0]
+  if (!interrupt) throw new Error('The turn has no interrupt.')
+  const receipt = await session.resolve([
+    { interruptId: interrupt.id, status: 'resolved', payload: true },
+  ])
+  return turnOf(session, receipt.operationId)
+}
+
+async function errorMessages(operation: Operation<unknown>) {
+  const messages: Array<string> = []
+  for await (const entry of operation.events({ from: '0' })) {
+    if (entry.event.type === EventType.RUN_ERROR) {
+      messages.push(entry.event.message)
+    }
+  }
+  return messages
+}
+
+describe('routing.router', () => {
+  it('runs only the picked root agent, and keeps its answer', async () => {
+    const writer = textAgent('writer', 'Draft')
+    const seo = textAgent('seo', 'Keywords')
+    const { host, session, main } = await openRouting({
+      router: () => 'writer',
+      agents: [writer.agent, seo.agent],
+    })
+
+    const turn = await session.prompt('write it')
+
+    expect(turn.text).toBe('writer:\nDraft')
+    expect(main.calls).toHaveLength(0)
+    expect(writer.runs).toEqual([['write it']])
+    expect(seo.runs).toEqual([])
+    expect(await transcriptTexts(session)).toEqual([
+      'write it',
+      'writer:\nDraft',
+    ])
+    await host.close()
+  })
+
+  it('gives a picked agent the input of { name, input }', async () => {
+    const { host, session } = await openRouting({
+      router: () => ({ name: 'pricer', input: { vendor: 'acme' } }),
+      agents: [pricer],
+    })
+
+    expect((await session.prompt('price acme')).text).toBe(
+      'pricer:\nPrice for acme',
+    )
+    await host.close()
+  })
+
+  it("runs the main model with its subagent tools on 'main'", async () => {
+    const writer = textAgent('writer', 'Draft')
+    const checker = textAgent('checker', 'Checked')
+    const { host, session, main } = await openRouting({
+      router: () => 'main',
+      agents: [writer.agent],
+      subagents: { agents: [checker.agent] },
+      replies: [() => text('Main answer')],
+    })
+
+    expect((await session.prompt('hello')).text).toBe('Main answer')
+    expect(
+      main.calls[0].tools.map((tool: { name: string }) => tool.name),
+    ).toContain('checker')
+    expect(writer.runs).toEqual([])
+    await host.close()
+  })
+
+  it("lets subagents.router route a turn that routing gives to 'main'", async () => {
+    const writer = textAgent('writer', 'Draft')
+    const checker = textAgent('checker', 'Checked')
+    const { host, session, main } = await openRouting({
+      router: () => 'main',
+      agents: [writer.agent],
+      subagents: { agents: [checker.agent], router: () => 'checker' },
+    })
+
+    expect((await session.prompt('check it')).text).toBe('checker:\nChecked')
+    expect(main.calls).toHaveLength(0)
+    expect(writer.runs).toEqual([])
+    await host.close()
+  })
+
+  it('picks session plugin agents and run plugin agents', async () => {
+    const writer = textAgent('writer', 'Draft')
+    const researcher = textAgent('researcher', 'Facts')
+    const seo = textAgent('seo', 'Keywords')
+    const { router, seen } = scriptedRouter('researcher', 'seo')
+    const { host, session } = await openRouting({
+      router,
+      agents: [writer.agent],
+      plugins: () => [
+        definePlugin({
+          name: 'test/session-agents',
+          setup: () => ({ agents: [researcher.agent] }),
+        }),
+        definePlugin({
+          name: 'test/run-agents',
+          lifetime: 'run',
+          setup: () => ({ agents: [seo.agent] }),
+        }),
+      ],
+    })
+
+    expect((await session.prompt('research')).text).toBe('researcher:\nFacts')
+    expect((await session.prompt('optimize')).text).toBe('seo:\nKeywords')
+    expect(seen.map((ctx) => ctx.agents.map((agent) => agent.name))).toEqual([
+      ['writer', 'researcher', 'seo'],
+      ['writer', 'researcher', 'seo'],
+    ])
+    await host.close()
+  })
+
+  it('cannot pick an agent that is only in subagents', async () => {
+    const writer = textAgent('writer', 'Draft')
+    const checker = textAgent('checker', 'Checked')
+    const helper = textAgent('helper', 'Helped')
+    const { router, seen } = scriptedRouter('checker')
+    const { host, session } = await openRouting({
+      router,
+      // In both lists, so it is a root agent once.
+      agents: [writer.agent, pricer],
+      subagents: { agents: [checker.agent, pricer] },
+      plugins: () => [
+        definePlugin({
+          name: 'test/plugin-subagents',
+          setup: () => ({ subagents: [helper.agent] }),
+        }),
+      ],
+    })
+
+    await expect(session.prompt('check it')).rejects.toThrow(
+      'Unknown subagent: checker. The router can pick: writer, pricer.',
+    )
+    expect(seen[0]?.agents.map((agent) => agent.name)).toEqual([
+      'writer',
+      'pricer',
+    ])
+    expect(checker.runs).toEqual([])
+    await host.close()
+  })
+
+  it('gives the router the session, the input as sent, the ids, the adapter, and the history', async () => {
+    const writer = textAgent('writer', 'Draft')
+    const { router, seen } = scriptedRouter('main', 'writer')
+    const { host, session, main } = await openRouting({
+      router,
+      agents: [writer.agent],
+      replies: [() => text('Main 1')],
+    })
+    const input = [{ type: 'text' as const, content: 'second' }]
+
+    await session.prompt('first')
+    const turn = session.prompt(input, { inputId: 'in-2' })
+    await turn
+
+    const ctx = seen[1]
+    expect(ctx?.session).toBe(session)
+    expect(ctx?.input).toEqual([{ type: 'text', content: 'second' }])
+    expect(ctx?.operationId).toBe(turn.id)
+    expect(ctx?.inputId).toBe('in-2')
+    expect(ctx?.adapter).toBe(main.adapter)
+    expect(ctx?.abortSignal?.aborted).toBe(false)
+    expect(messageTexts(ctx)).toEqual([
+      'first',
+      'Main 1',
+      JSON.stringify([{ type: 'text', content: 'second' }]),
+    ])
+    await host.close()
+  })
+
+  it('hands off to the main model after the agents, with its subagent tools', async () => {
+    const writer = textAgent('writer', 'Draft')
+    const checker = textAgent('checker', 'Checked')
+    const { host, session, main } = await openRouting({
+      router: () => 'writer',
+      strategy: 'handoff',
+      agents: [writer.agent],
+      subagents: { agents: [checker.agent] },
+      replies: [() => text('Edited draft')],
+    })
+
+    const turn = await session.prompt('write it')
+
+    expect(turn.text).toBe('Edited draft')
+    expect(main.calls).toHaveLength(1)
+    expect(messageTexts(main.calls[0])).toEqual(['write it', 'writer:\nDraft'])
+    expect(
+      main.calls[0].tools.map((tool: { name: string }) => tool.name),
+    ).toContain('checker')
+    expect((await transcriptTexts(session)).at(-1)).toBe('Edited draft')
+    await host.close()
+  })
+
+  it.each([
+    { strategy: 'exclusive', text: 'writer:\nDraft 1' },
+    { strategy: 'handoff', text: 'Main 1' },
+  ] as const)(
+    'runs a steer sent during a $strategy routed turn as its own routed turn',
+    async ({ strategy, text: firstText }) => {
+      const started = gate()
+      const release = gate()
+      const answers: Array<Array<string>> = []
+      const writer = defineAgent({
+        name: 'writer',
+        description: 'Writes',
+        run: async (ctx) => {
+          answers.push(messageTexts({ messages: ctx.messages }))
+          started.open()
+          await release.opened
+          return `Draft ${answers.length}`
+        },
+      })
+      const { router, seen } = scriptedRouter('writer', 'writer')
+      const { host, session, main } = await openRouting({
+        router,
+        strategy,
+        agents: [writer],
+        replies: [() => text('Main 1'), () => text('Main 2')],
+      })
+
+      const turn = session.prompt('first')
+      await started.opened
+      const receipt = await session.steer('second')
+      release.open()
+
+      expect((await turn).text).toBe(firstText)
+      const settled = await session.settled(receipt.inputId)
+      expect(settled.outcome).toBe('completed')
+      expect(settled.operationId).not.toBe(turn.id)
+      expect(seen.map((ctx) => ctx.input)).toEqual(['first', 'second'])
+      expect(answers[1]?.at(-1)).toBe('second')
+      // The main model of a handoff does not get the steer in the first turn.
+      expect(main.calls.slice(0, 1).flatMap(messageTexts)).not.toContain(
+        'second',
+      )
+      await host.close()
+    },
+  )
+
+  it('runs no turn hooks on a routed turn', async () => {
+    const writer = textAgent('writer', 'Draft')
+    const beforeFinish = vi.fn(() => ({
+      messages: [{ role: 'user' as const, content: 'one more' }],
+    }))
+    const onModelError = vi.fn(() => undefined)
+    const { router } = scriptedRouter('writer', 'ghost')
+    const { host, session } = await openRouting({
+      router,
+      agents: [writer.agent],
+      turn: { beforeFinish, onModelError },
+    })
+
+    expect((await session.prompt('write it')).text).toBe('writer:\nDraft')
+    await expect(session.prompt('again')).rejects.toThrow(
+      'Unknown subagent: ghost',
+    )
+    expect(writer.runs).toHaveLength(1)
+    expect(beforeFinish).not.toHaveBeenCalled()
+    expect(onModelError).not.toHaveBeenCalled()
+    await host.close()
+  })
+
+  it("does not call the router to resolve a main model's interrupt", async () => {
+    const writer = textAgent('writer', 'Draft')
+    const execute = vi.fn(async () => ({ removed: true }))
+    const removeAll = toolDefinition({
+      name: 'removeAll',
+      description: 'Remove every file',
+      needsApproval: true,
+    }).server(execute)
+    const { router, seen } = scriptedRouter('main')
+    const { host, session } = await openRouting({
+      router,
+      agents: [writer.agent],
+      tools: [removeAll],
+      replies: [() => toolCall('removeAll', {}, 'call_m'), () => text('Done')],
+    })
+
+    const turn = await session.prompt('remove everything')
+    const resumed = await approve(session, turn)
+
+    expect(await resumed).toEqual({ text: 'Done' })
+    expect(execute).toHaveBeenCalledTimes(1)
+    expect(seen).toHaveLength(1)
+    await host.close()
+  })
+
+  it('calls the router for the wake turn of a background agent, with its follow-up text', async () => {
+    const indexer = textAgent('indexer', 'Indexed')
+    const { router, seen } = scriptedRouter('main')
+    const { host, session, main } = await openRouting({
+      router,
+      agents: [indexer.agent],
+      replies: [() => text('Noted')],
+    })
+
+    const handle = session.agent('indexer')
+    if (!handle) throw new Error('No indexer agent.')
+    await handle.start(undefined, { wake: true })
+    await vi.waitFor(() => expect(main.calls).toHaveLength(1))
+    await vi.waitFor(() => expect(session.snapshot().status).toBe('idle'))
+
+    expect(seen.map((ctx) => ctx.input)).toEqual([
+      'Background agent indexer finished: [indexer finished] Indexed',
+    ])
+    await host.close()
+  })
+
+  it('continues a run plugin agent that stopped for an interrupt, in a later turn', async () => {
+    const { make, execute } = cleaner()
+    const { router, seen } = scriptedRouter('cleaner')
+    const { host, session } = await openRouting({
+      router,
+      plugins: () => [
+        definePlugin({
+          name: 'test/run-cleaner',
+          lifetime: 'run',
+          // A new agent object on each mount, with the same name.
+          setup: () => ({ agents: [make()] }),
+        }),
+      ],
+    })
+
+    const turn = await session.prompt('clean up')
+    expect(turn.interrupts).toHaveLength(1)
+    const resumed = await approve(session, turn)
+
+    expect(await resumed).toEqual({ text: 'cleaner:\nRemoved a.txt' })
+    expect(execute).toHaveBeenCalledWith({ path: 'a.txt' }, expect.anything())
+    expect(seen).toHaveLength(1)
+    await host.close()
+  })
+})
+
+describe.each([
+  { host: 'a host without a log', durable: false },
+  { host: 'a durable host', durable: true },
+])('routing on $host', ({ durable }) => {
+  it('holds a run lease while a routed agent runs', async () => {
+    const started = gate()
+    const release = gate()
+    const writer = defineAgent({
+      name: 'writer',
+      description: 'Writes',
+      run: async () => {
+        started.open()
+        await release.opened
+        return 'Done.'
+      },
+    })
+    const { host, session, runs } = await openRouting({
+      durable,
+      router: () => 'writer',
+      agents: [writer],
+    })
+
+    const turn = session.prompt('go')
+    await started.opened
+    expect((await runs.get(turn.id))?.leaseExpiresAt).toBeGreaterThan(
+      Date.now(),
+    )
+    release.open()
+    expect((await turn).text).toBe('writer:\nDone.')
+    await host.close()
+  })
+
+  it.each([{ pick: 'writer' }, { pick: 'main' }])(
+    'ends the turn aborted when cancelled while the router runs, and starts nothing for $pick',
+    async ({ pick }) => {
+      const writer = textAgent('writer', 'Draft')
+      const routerStarted = gate()
+      const releaseRouter = gate()
+      let signal: AbortSignal | undefined
+      const { host, session, main } = await openRouting({
+        durable,
+        router: async ({ abortSignal }) => {
+          signal = abortSignal
+          routerStarted.open()
+          // This router does not stop at the signal. The harness does.
+          await releaseRouter.opened
+          return pick
+        },
+        agents: [writer.agent],
+        replies: [() => text('Main answer')],
+      })
+
+      const turn = session.prompt('go', { inputId: 'in-1' })
+      await routerStarted.opened
+      await turn.cancel()
+      releaseRouter.open()
+
+      await expect(turn).rejects.toThrow('Cancelled')
+      expect(turn.status()).toBe('cancelled')
+      expect(signal?.aborted).toBe(true)
+      expect(writer.runs).toEqual([])
+      expect(main.calls).toHaveLength(0)
+      expect((await session.settled('in-1')).outcome).toBe('aborted')
+      await host.close()
+    },
+  )
+
+  it('continues the saved plan after resolve, and calls the router once', async () => {
+    const { make, execute } = cleaner()
+    const { router, seen } = scriptedRouter('cleaner')
+    const { host, session, main } = await openRouting({
+      durable,
+      router,
+      agents: [make()],
+    })
+
+    const turn = await session.prompt('clean up', { inputId: 'in-1' })
+    expect(turn.interrupts).toHaveLength(1)
+    expect(execute).not.toHaveBeenCalled()
+    expect((await session.settled('in-1')).outcome).toBe('interrupted')
+    const resumed = await approve(session, turn)
+
+    expect(await resumed).toEqual({ text: 'cleaner:\nRemoved a.txt' })
+    expect(execute).toHaveBeenCalledWith({ path: 'a.txt' }, expect.anything())
+    expect(seen).toHaveLength(1)
+    expect(main.calls).toHaveLength(0)
+    // The thread keeps one answer for the turn, and no rows of the agent.
+    expect(await transcriptTexts(session)).toEqual([
+      'clean up',
+      'cleaner:\nRemoved a.txt',
+    ])
+    await host.close()
+  })
+
+  it.each([
+    {
+      name: 'the router throws',
+      router: () => {
+        throw new Error('router broke')
+      },
+      error: 'router broke',
+    },
+    {
+      name: 'the pick names no root agent',
+      router: () => 'ghost',
+      error: 'Unknown subagent: ghost. The router can pick: writer, pricer.',
+    },
+    {
+      name: 'a picked agent with inputSchema has no input',
+      router: () => 'pricer',
+      error:
+        'Agent "pricer" needs input. Return { name: \'pricer\', input } from the router.',
+    },
+    {
+      name: 'the input does not match the schema',
+      router: () => ({ name: 'pricer', input: { vendor: 1 } }),
+      error: 'Input validation failed for agent pricer',
+    },
+    {
+      name: 'the pick is an empty list',
+      router: () => [],
+      error:
+        'subagents.router must return main, a name, a list of names, { names, order }, or { steps }.',
+    },
+  ] satisfies Array<{
+    name: string
+    router: HarnessRouting['router']
+    error: string
+  }>)('fails the turn when $name', async ({ router, error }) => {
+    const writer = textAgent('writer', 'Draft')
+    const { host, session } = await openRouting({
+      durable,
+      router,
+      agents: [writer.agent, pricer],
+    })
+
+    const turn = session.prompt('go', { inputId: 'in-1' })
+
+    await expect(turn).rejects.toThrow(error)
+    expect(turn.status()).toBe('failed')
+    expect(await errorMessages(turn)).toEqual([expect.stringContaining(error)])
+    const settled = await session.settled('in-1')
+    expect(settled.outcome).toBe('failed')
+    expect(settled.error?.message).toContain(error)
+    expect(writer.runs).toEqual([])
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/subagent-router.test.ts b/packages/ai-harness/tests/subagent-router.test.ts
new file mode 100644
index 0000000000..116b472e38
--- /dev/null
+++ b/packages/ai-harness/tests/subagent-router.test.ts
@@ -0,0 +1,177 @@
+import { describe, expect, it } from 'vitest'
+import { defineAgent } from '@tanstack/ai'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '../src'
+import { gate, messageTexts, mockAdapter, text } from './helpers'
+import type { SubagentRouterPick } from '@tanstack/ai'
+import type { AnyAgent } from '../src'
+import type { Reply } from './helpers'
+
+const THREAD = 't1'
+
+/** The writer agent. It keeps the messages of each run and answers `Draft <n>`. */
+function writerAgent() {
+  const seen: Array<Array<string>> = []
+  const agent = defineAgent({
+    name: 'writer',
+    description: 'Writes a draft',
+    run: async (ctx) => {
+      seen.push(messageTexts({ messages: ctx.messages }))
+      return `Draft ${seen.length}`
+    },
+  })
+  return { agent, seen }
+}
+
+/**
+ * A session whose `subagents.router` always returns `pick`. The router keeps
+ * the messages of each call. `durable` gives the host a log.
+ */
+async function openRouted(options: {
+  durable: boolean
+  agent: AnyAgent
+  pick: SubagentRouterPick
+  replies?: Array<Reply>
+  lease?: { renewMs?: number; ttlMs?: number }
+}) {
+  const { stores } = memoryPersistence()
+  const { runs, metadata } = stores
+  const persistence = options.durable
+    ? { stores: { log: memoryLogStore(), runs, metadata } }
+    : { stores }
+  const main = mockAdapter(options.replies ?? [])
+  const routerSaw: Array<Array<string>> = []
+  const host = createHarnessHost({
+    persistence,
+    ...(options.lease ? { lease: options.lease } : {}),
+  })
+  const session = await host.open(
+    defineHarness({
+      name: 'test/router',
+      adapter: main.adapter,
+      subagents: {
+        agents: [options.agent],
+        router: ({ messages }) => {
+          routerSaw.push(messageTexts({ messages }))
+          return options.pick
+        },
+      },
+    }),
+    { threadId: THREAD },
+  )
+  return { host, session, runs, routerSaw, calls: main.calls }
+}
+
+describe.each([
+  { host: 'a host without a log', durable: false },
+  { host: 'a durable host', durable: true },
+])('subagents.router on $host', ({ durable }) => {
+  it('gives the router the earlier turns', async () => {
+    const { agent } = writerAgent()
+    const { host, session, routerSaw } = await openRouted({
+      durable,
+      agent,
+      pick: 'writer',
+    })
+    await session.prompt('first')
+    await session.prompt('second')
+    expect(routerSaw).toEqual([
+      ['first'],
+      ['first', 'writer:\nDraft 1', 'second'],
+    ])
+    await host.close()
+  })
+
+  it('gives a routed agent the earlier turns, and saves each message once', async () => {
+    const { agent, seen } = writerAgent()
+    const { host, session } = await openRouted({
+      durable,
+      agent,
+      pick: 'writer',
+    })
+    await session.prompt('first')
+    await session.prompt('second')
+    expect(seen).toEqual([['first'], ['first', 'writer:\nDraft 1', 'second']])
+    expect(messageTexts({ messages: await session.transcript() })).toEqual([
+      'first',
+      'writer:\nDraft 1',
+      'second',
+      'writer:\nDraft 2',
+    ])
+    await host.close()
+  })
+
+  it('returns the text of the routed agent', async () => {
+    const { agent } = writerAgent()
+    const { host, session, calls } = await openRouted({
+      durable,
+      agent,
+      pick: 'writer',
+    })
+    const turn = await session.prompt('go')
+    expect(turn.text).toBe('writer:\nDraft 1')
+    expect(calls).toHaveLength(0)
+    await host.close()
+  })
+
+  it("runs the main model when the router returns 'main'", async () => {
+    const { agent, seen } = writerAgent()
+    const { host, session, calls } = await openRouted({
+      durable,
+      agent,
+      pick: 'main',
+      replies: [() => text('Main 1'), () => text('Main 2')],
+    })
+    expect((await session.prompt('first')).text).toBe('Main 1')
+    expect((await session.prompt('second')).text).toBe('Main 2')
+    // The main model gets each earlier message once.
+    expect(messageTexts(calls[1])).toEqual(['first', 'Main 1', 'second'])
+    expect(seen).toEqual([])
+    await host.close()
+  })
+
+  it('holds a run lease while a routed agent runs', async () => {
+    const started = gate()
+    const release = gate()
+    const agent = defineAgent({
+      name: 'writer',
+      description: 'Writes a draft',
+      run: async () => {
+        started.open()
+        await release.opened
+        return 'Done.'
+      },
+    })
+    const { host, session, runs } = await openRouted({
+      durable,
+      agent,
+      pick: 'writer',
+    })
+    const turn = session.prompt('go')
+    await started.opened
+    const running = await runs.get(turn.id)
+    expect(running?.leaseOwner).toMatch(/^host-/)
+    expect(running?.leaseExpiresAt).toBeGreaterThan(Date.now())
+    release.open()
+    expect((await turn).text).toBe('writer:\nDone.')
+    await host.close()
+  })
+
+  it('stops the run lease when the turn ends', async () => {
+    const { agent } = writerAgent()
+    const { host, session, runs } = await openRouted({
+      durable,
+      agent,
+      pick: 'writer',
+      lease: { renewMs: 5 },
+    })
+    const turn = session.prompt('go')
+    await turn
+    const ended = (await runs.get(turn.id))?.leaseExpiresAt
+    expect(ended).toBeTypeOf('number')
+    // A lease that still renews moves forward within a few renewals.
+    await new Promise((resolve) => setTimeout(resolve, 50))
+    expect((await runs.get(turn.id))?.leaseExpiresAt).toBe(ended)
+    await host.close()
+  })
+})
diff --git a/packages/ai/src/activities/chat/agents/define-agent.ts b/packages/ai/src/activities/chat/agents/define-agent.ts
index 0d20ba4303..5cbb5d24a6 100644
--- a/packages/ai/src/activities/chat/agents/define-agent.ts
+++ b/packages/ai/src/activities/chat/agents/define-agent.ts
@@ -21,8 +21,8 @@ export interface SubagentRunInput<
   TInput extends SchemaInput | undefined = any,
 > {
   /**
-   * The input the parent model wrote for this child, checked against
-   * `inputSchema`. `undefined` when the agent has no `inputSchema`.
+   * The input the parent model or the router gave this child, checked
+   * against `inputSchema`. `undefined` when the agent has no `inputSchema`.
    */
   input: TInput extends SchemaInput ? InferSchemaType<TInput> : undefined
   messages: Array<UIMessage | ModelMessage>
@@ -116,9 +116,10 @@ export interface DefinedAgent<
   /** What this agent makes. See {@link AgentProduces}. */
   produces?: TProduces
   /**
-   * The input the parent model writes when it calls this agent's tool, such
-   * as a short brief. `run` reads it as `ctx.input`. Tool mode only: a
-   * `subagents.router` cannot start an agent that has `inputSchema`.
+   * The input this agent needs, such as a short brief. `run` reads it as
+   * `ctx.input`. In tool mode, the parent model writes it when it calls this
+   * agent's tool. A `subagents.router` gives it in its pick as
+   * `{ name, input }`. The input is checked against this schema first.
    */
   inputSchema?: TInput
   tools?: TTools
diff --git a/packages/ai/src/activities/chat/agents/route.ts b/packages/ai/src/activities/chat/agents/route.ts
index b6efef536a..f3466bd90a 100644
--- a/packages/ai/src/activities/chat/agents/route.ts
+++ b/packages/ai/src/activities/chat/agents/route.ts
@@ -1,6 +1,7 @@
 import { boolean, choice } from '../../evaluate/index'
+import type { InferSchemaType, SchemaInput } from '../../../types'
 import type { DefinedAgent } from './define-agent'
-import type { SubagentOrder, SubagentRouterPick } from './spawn'
+import type { SubagentOrder } from './spawn'
 
 const ORDER_KEY = 'order'
 
@@ -38,6 +39,31 @@ type RouteAnswers<TAgents extends ReadonlyArray<DefinedAgent>> = {
   order: { value: SubagentOrder }
 }
 
+/** The name and the `inputSchema` of an agent that has one. Else `never`. */
+type InputNeed<TAgent> = TAgent extends {
+  name: infer TName
+  inputSchema?: infer TSchema
+}
+  ? TSchema extends SchemaInput
+    ? { name: TName; inputSchema: TSchema }
+    : never
+  : never
+
+/** One input for each agent with an `inputSchema`, typed from that schema. */
+type RouteInputs<TAgents extends ReadonlyArray<DefinedAgent>> = {
+  [TNeed in InputNeed<TAgents[number]> as TNeed['name']]?: InferSchemaType<
+    TNeed['inputSchema']
+  >
+}
+
+interface RoutePickOptions<TAgents extends ReadonlyArray<DefinedAgent>> {
+  /**
+   * The input of each picked agent that has an `inputSchema`. The key is the
+   * agent name. `needsInput` lists the agents that need one.
+   */
+  inputs?: RouteInputs<TAgents>
+}
+
 /**
  * Build `decide()` questions for a subagent router.
  *
@@ -49,6 +75,20 @@ type RouteAnswers<TAgents extends ReadonlyArray<DefinedAgent>> = {
  * starts together. The `then` agents then run one after another in list
  * order, and each reads the text so far. Used only when the router picks at
  * least one agent from each group. Otherwise `pick` returns `{ names, order }`.
+ *
+ * An agent with `inputSchema` needs input. `needsInput(result)` lists the
+ * picked agents that need it, with their schemas. Make each input, then pass
+ * them as `pick(result, { inputs })`. Each name with an input becomes
+ * `{ name, input }`. `pick` throws when a picked agent with a schema has no
+ * input.
+ *
+ * @example
+ * ```ts
+ * const route = subagentRoute(agents)
+ * const result = await decide({ adapter, state, questions: route.questions })
+ * const inputs = { pricer: { sku: 'A-1' } }
+ * return route.pick(result, { inputs })
+ * ```
  */
 export function subagentRoute<
   const TAgents extends ReadonlyArray<DefinedAgent>,
@@ -86,30 +126,62 @@ export function subagentRoute<
     })
   }
 
-  function pick(result: RouteAnswers<TAgents>): SubagentRouterPick {
-    const names = agents
-      .map((agent) => agent.name)
-      .filter((name) => result[name as TAgents[number]['name']].value)
+  /** The agents with a yes answer, in agent-list order. */
+  function picked(result: RouteAnswers<TAgents>) {
+    return agents.filter(
+      (agent) => result[agent.name as TAgents[number]['name']].value,
+    )
+  }
+
+  /**
+   * The picked agents that have an `inputSchema`, in agent-list order. Make
+   * an input for each one and pass it to `pick` in `inputs`.
+   */
+  function needsInput(result: RouteAnswers<TAgents>) {
+    const needs = picked(result).flatMap(({ name, inputSchema }) =>
+      inputSchema === undefined ? [] : [{ name, inputSchema }],
+    )
+    // At runtime, `agents` has the wide agent type. It loses the link between
+    // each name and its schema, so this names the entry type.
+    return needs as Array<InputNeed<TAgents[number]>>
+  }
+
+  function pick(
+    result: RouteAnswers<TAgents>,
+    pickOptions: RoutePickOptions<TAgents> = {},
+  ) {
+    const inputs: Readonly<Partial<Record<string, unknown>>> =
+      pickOptions.inputs ?? {}
+    const toPickName = ({ name, inputSchema }: DefinedAgent) => {
+      const input = inputs[name]
+      if (input !== undefined) return { name, input }
+      if (inputSchema !== undefined) {
+        throw new Error(`Agent "${name}" needs input. Pass it in inputs.`)
+      }
+      return name
+    }
+    const chosen = picked(result)
+    const names = chosen.map(toPickName)
     if (names.length === 0) return 'main'
     const only = names.length === 1 ? names[0] : undefined
     if (only !== undefined) return only
     const later = new Set(options?.then ?? [])
-    const lead = names.filter((name) => !later.has(name))
-    const tail = names.filter((name) => later.has(name))
+    const lead = chosen.filter((agent) => !later.has(agent.name))
+    const tail = chosen.filter((agent) => later.has(agent.name))
     if (lead.length === 0 || tail.length === 0) {
       return { names, order: result.order.value }
     }
     return {
       steps: [
         lead.length > 1
-          ? { names: lead, order: 'parallel' as const }
-          : { names: lead },
+          ? { names: lead.map(toPickName), order: 'parallel' as const }
+          : { names: lead.map(toPickName) },
         tail.length > 1
-          ? { names: tail, order: 'sequence' as const }
-          : { names: tail },
+          ? { names: tail.map(toPickName), order: 'sequence' as const }
+          : { names: tail.map(toPickName) },
       ],
     }
   }
 
-  return { questions: questions as RouteQuestions<TAgents>, pick }
+  return { questions: questions as RouteQuestions<TAgents>, pick, needsInput }
 }
diff --git a/packages/ai/src/activities/chat/agents/spawn.ts b/packages/ai/src/activities/chat/agents/spawn.ts
index be48f1bca4..af147aafa5 100644
--- a/packages/ai/src/activities/chat/agents/spawn.ts
+++ b/packages/ai/src/activities/chat/agents/spawn.ts
@@ -45,14 +45,21 @@ export const SUBAGENT_ERROR = EventType.SUBAGENT_ERROR
 
 export type SubagentOrder = 'parallel' | 'sequence'
 
+/**
+ * One agent in a router pick: its name, or its name and its input. An agent
+ * with `inputSchema` needs `{ name, input }`. The input is checked against
+ * the schema, and `run` reads it as `ctx.input`.
+ */
+export type SubagentPickName = string | { name: string; input?: unknown }
+
 export interface SubagentRouterPlan {
-  names: ReadonlyArray<string>
+  names: ReadonlyArray<SubagentPickName>
   /** Overrides `subagents.order` for this turn. */
   order?: SubagentOrder
 }
 
 export interface SubagentStep {
-  names: ReadonlyArray<string>
+  names: ReadonlyArray<SubagentPickName>
   /** Overrides `subagents.order` for this step. */
   order?: SubagentOrder
 }
@@ -63,11 +70,24 @@ export interface SubagentStepsPlan {
 
 export type SubagentRouterPick =
   | 'main'
-  | string
-  | ReadonlyArray<string>
+  | SubagentPickName
+  | ReadonlyArray<SubagentPickName>
   | SubagentRouterPlan
   | SubagentStepsPlan
 
+/**
+ * A router pick after `normalizeRouterPick`. Each step has plain names, and
+ * `inputs` holds the raw input of each name that has one. This is the plan
+ * on `SUBAGENT_STARTED` metadata.
+ */
+export interface RoutedPlan {
+  steps: ReadonlyArray<{
+    names: ReadonlyArray<string>
+    inputs?: Record<string, unknown>
+    order?: SubagentOrder
+  }>
+}
+
 export interface SubagentsBag<
   TAgents extends ReadonlyArray<DefinedAgent> = ReadonlyArray<DefinedAgent>,
 > {
@@ -115,7 +135,7 @@ export function createSubagentSink(): SubagentSink {
 /** One child to start, or a suspended child to continue. */
 export interface SpawnEntry {
   name: string
-  /** The checked tool input for an agent with `inputSchema`. */
+  /** The checked input of an agent with `inputSchema`, from a tool or a router. */
   input?: unknown
   resume?: {
     subagentRunId: string
@@ -241,7 +261,8 @@ function orAbort<T>(promise: Promise<T>, signal?: AbortSignal) {
 function agentByName(agents: ReadonlyArray<DefinedAgent>, name: string) {
   const agent = agents.find((entry) => entry.name === name)
   if (!agent) {
-    throw new Error(`Unknown subagent: ${name}`)
+    const names = agents.map((entry) => entry.name).join(', ')
+    throw new Error(`Unknown subagent: ${name}. The router can pick: ${names}.`)
   }
   return agent
 }
@@ -302,40 +323,56 @@ function assertOrder(order: SubagentOrder | undefined) {
   }
 }
 
+/** One step of a pick: plain names, plus the input of each name that has one. */
 function normalizeNames(
-  names: ReadonlyArray<string>,
+  picks: ReadonlyArray<SubagentPickName>,
   agents: ReadonlyArray<DefinedAgent>,
-): ReadonlyArray<string> {
-  if (names.length === 0) throw new Error(ROUTER_PICK_ERROR)
+) {
+  if (picks.length === 0) throw new Error(ROUTER_PICK_ERROR)
+  const names = picks.map((pick) =>
+    typeof pick === 'string' ? pick : pick.name,
+  )
   const hasMain = names.includes('main')
   if (hasMain && names.length > 1) {
     throw new Error('Do not mix main into a subagent list.')
   }
-  if (hasMain) return ['main']
+  if (hasMain) return { names: ['main'] }
   for (const name of names) agentByName(agents, name)
-  return [...names]
+  // ponytail: one input per name in a step. A name picked twice in one step
+  // keeps its last input. Key inputs by position if a router needs two.
+  let inputs: Record<string, unknown> | undefined
+  for (const pick of picks) {
+    if (typeof pick === 'string' || pick.input === undefined) continue
+    inputs = { ...inputs, [pick.name]: pick.input }
+  }
+  return inputs === undefined ? { names } : { names, inputs }
 }
 
-function isStringList(pick: SubagentRouterPick): pick is ReadonlyArray<string> {
+function isPickList(
+  pick: SubagentRouterPick,
+): pick is ReadonlyArray<SubagentPickName> {
   return Array.isArray(pick)
 }
 
 export function normalizeRouterPick(
   pick: SubagentRouterPick,
   agents: ReadonlyArray<DefinedAgent>,
-): { steps: ReadonlyArray<SubagentStep> } {
+) {
   if (pick === 'main' || typeof pick === 'string') {
-    return { steps: [{ names: normalizeNames([pick], agents) }] }
+    return { steps: [normalizeNames([pick], agents)] }
+  }
+  if (isPickList(pick)) {
+    return { steps: [normalizeNames(pick, agents)] }
   }
-  if (isStringList(pick)) {
-    return { steps: [{ names: normalizeNames(pick, agents) }] }
+  if ('name' in pick) {
+    return { steps: [normalizeNames([pick], agents)] }
   }
   if ('steps' in pick) {
     if (pick.steps.length === 0) throw new Error(ROUTER_PICK_ERROR)
     const steps = pick.steps.map((step) => {
       assertOrder(step.order)
       const names = normalizeNames(step.names, agents)
-      return step.order === undefined ? { names } : { names, order: step.order }
+      return step.order === undefined ? names : { ...names, order: step.order }
     })
     const flat = steps.flatMap((step) => step.names)
     if (flat.includes('main') && flat.length > 1) {
@@ -346,9 +383,7 @@ export function normalizeRouterPick(
   assertOrder(pick.order)
   const names = normalizeNames(pick.names, agents)
   return {
-    steps: [
-      pick.order === undefined ? { names } : { names, order: pick.order },
-    ],
+    steps: [pick.order === undefined ? names : { ...names, order: pick.order }],
   }
 }
 
diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index c2d2d91afa..c57d5f738c 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -66,10 +66,9 @@ import {
   withChildUsage,
 } from './agents/spawn'
 import type {
+  RoutedPlan,
   SpawnEntry,
   SubagentSink,
-  SubagentStep,
-  SubagentStepsPlan,
   SubagentsBag,
 } from './agents/spawn'
 import { SUBAGENT_PLAN_KEY, readSubagentTurn } from './agents/turn'
@@ -83,6 +82,7 @@ import {
   convertSchemaToJsonSchema,
   isStandardSchema,
   parseWithStandardSchema,
+  validateWithStandardSchema,
 } from './tools/schema-converter'
 import {
   hashSchemaInput,
@@ -5535,16 +5535,6 @@ async function* runRoutedSubagents(
     yield* runChatEngine(options, engineRef)
     return
   }
-  // ponytail: a router cannot write input yet. Add it to the router pick if
-  // someone needs it.
-  const withInput = bag.agents.find(
-    (agent: DefinedAgent) => agent.inputSchema !== undefined,
-  )
-  if (withInput) {
-    throw new Error(
-      `Subagent "${withInput.name}" has an inputSchema. inputSchema needs tool mode: remove subagents.router so the model writes the input.`,
-    )
-  }
   const threadId = options.threadId ?? `thread-${Date.now()}`
   const runId = options.runId ?? `run-${Date.now()}`
   const messages = options.messages ?? []
@@ -5595,6 +5585,9 @@ async function* runRoutedSubagents(
       await subagentPersistence?.abort({ threadId, runId, error })
       return
     }
+    // Check every input before a child starts, so a bad input in a later
+    // step fails the turn like a bad pick.
+    const checked = await checkRoutedInputs(plan, bag.agents)
     const onlyStep = plan.steps.length === 1 ? plan.steps[0] : undefined
     if (onlyStep?.names.length === 1 && onlyStep.names[0] === 'main') {
       // Earlier children own answers in this resume. Commit them first.
@@ -5630,7 +5623,7 @@ async function* runRoutedSubagents(
     let failure:
       | Extract<StreamChunk, { type: EventType.SUBAGENT_ERROR }>
       | undefined
-    for (const step of plan.steps) {
+    for (const step of checked.steps) {
       const entries: Array<SpawnEntry> = []
       const textByName = new Map<string, string>()
       for (const name of step.names) {
@@ -5639,19 +5632,20 @@ async function* runRoutedSubagents(
           textByName.set(name, prior.text)
           continue
         }
-        entries.push(
-          prior?.status === 'suspended'
-            ? {
-                name,
-                resume: {
-                  subagentRunId: prior.subagentRunId,
-                  messages: prior.messages,
-                  entries: prior.resume,
-                  text: prior.text,
-                },
-              }
-            : { name },
-        )
+        // A suspended child gets its input again, like a tool-mode child.
+        const input = step.inputs?.[name]
+        entries.push({
+          name,
+          ...(input !== undefined && { input }),
+          ...(prior?.status === 'suspended' && {
+            resume: {
+              subagentRunId: prior.subagentRunId,
+              messages: prior.messages,
+              entries: prior.resume,
+              text: prior.text,
+            },
+          }),
+        })
       }
       const stepChunks: Array<StreamChunk> = []
       if (entries.length > 0) {
@@ -5818,13 +5812,26 @@ function savedPlan(
     interruptedRunId: string
     interruptIds: ReadonlyArray<string>
   },
-): { steps: ReadonlyArray<SubagentStep> } | undefined {
+) {
   if (typeof plan !== 'object' || plan === null || !('steps' in plan)) {
     return undefined
   }
   try {
-    // The plan comes back from the client. Check it like a router pick.
-    return normalizeRouterPick(plan as SubagentStepsPlan, agents)
+    // The plan comes back from the client. Put each input back on its name
+    // and check it like a router pick.
+    const saved = plan as RoutedPlan
+    return normalizeRouterPick(
+      {
+        steps: saved.steps.map((step) => ({
+          names: step.names.map((name) => {
+            const input = step.inputs?.[name]
+            return input === undefined ? name : { name, input }
+          }),
+          order: step.order,
+        })),
+      },
+      agents,
+    )
   } catch (error) {
     throw new InterruptResumeValidationError([
       {
@@ -5844,11 +5851,41 @@ function savedPlan(
   }
 }
 
+/**
+ * Check the input of each picked agent that has `inputSchema`, and return the
+ * plan with the checked inputs. The saved plan keeps the raw inputs, so a
+ * resume checks the same values again.
+ */
+async function checkRoutedInputs(
+  plan: RoutedPlan,
+  agents: ReadonlyArray<DefinedAgent>,
+) {
+  const steps: Array<RoutedPlan['steps'][number]> = []
+  for (const step of plan.steps) {
+    const inputs: Record<string, unknown> = {}
+    for (const name of step.names) {
+      const schema = agents.find((agent) => agent.name === name)?.inputSchema
+      if (schema === undefined) continue
+      const input = step.inputs?.[name]
+      if (input === undefined) {
+        throw new Error(
+          `Agent "${name}" needs input. Return { name: '${name}', input } from the router.`,
+        )
+      }
+      const result = await validateWithStandardSchema(schema, input)
+      if (!result.success) {
+        const issues = result.issues.map((issue) => issue.message).join(', ')
+        throw new Error(`Input validation failed for agent ${name}: ${issues}`)
+      }
+      inputs[name] = result.data
+    }
+    steps.push({ ...step, inputs })
+  }
+  return { steps }
+}
+
 /** Put the router plan on a direct child's SUBAGENT_STARTED metadata. */
-function withPlan(
-  chunk: StreamChunk,
-  plan: { steps: ReadonlyArray<SubagentStep> },
-): StreamChunk {
+function withPlan(chunk: StreamChunk, plan: RoutedPlan): StreamChunk {
   if (
     chunk.type !== EventType.SUBAGENT_STARTED ||
     chunk.parentSubagentRunId !== undefined
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index 5e2ebf53ee..33dcd90098 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -115,6 +115,7 @@ export {
 } from './activities/chat/agents/route'
 export type {
   SubagentOrder,
+  SubagentPickName,
   SubagentRouterPick,
   SubagentRouterPlan,
   SubagentStep,
diff --git a/packages/ai/tests/define-agent.test.ts b/packages/ai/tests/define-agent.test.ts
index ba676a0549..1232f8d895 100644
--- a/packages/ai/tests/define-agent.test.ts
+++ b/packages/ai/tests/define-agent.test.ts
@@ -9,6 +9,7 @@ import { chat } from '../src/activities/chat'
 import { collectChunks, createMockAdapter, ev } from './test-utils'
 import { EventType } from '../src/types'
 import type { StreamChunk } from '../src/types'
+import type { SubagentRouterPick } from '../src/activities/chat/agents/spawn'
 
 function parentAdapter() {
   return createMockAdapter({
@@ -16,6 +17,20 @@ function parentAdapter() {
   })
 }
 
+/** Run one routed turn whose router returns `pick`. */
+function routeTo(
+  agents: ReadonlyArray<DefinedAgent>,
+  pick: SubagentRouterPick,
+) {
+  return collectChunks(
+    chat({
+      adapter: parentAdapter().adapter,
+      messages: [{ role: 'user', content: 'Go' }],
+      subagents: { agents, router: () => pick },
+    }),
+  )
+}
+
 function childTextAdapter(text: string) {
   return createMockAdapter({
     iterations: [
@@ -163,6 +178,101 @@ describe('subagentRoute', () => {
       ]),
     ).toThrow('subagentRoute cannot use an agent named "order"')
   })
+
+  const skuSchema = z.object({ sku: z.string() })
+  const topicSchema = z.object({ topic: z.string() })
+  const inputDesk = [
+    defineAgent({
+      name: 'researcher',
+      description: 'Looks up facts',
+      run: async function* () {},
+    }),
+    defineAgent({
+      name: 'pricer',
+      description: 'Prices one product',
+      inputSchema: skuSchema,
+      run: async function* () {},
+    }),
+    defineAgent({
+      name: 'writer',
+      description: 'Writes the post',
+      inputSchema: topicSchema,
+      run: async function* () {},
+    }),
+    defineAgent({
+      name: 'seo',
+      description: 'Suggests titles',
+      run: async function* () {},
+    }),
+  ] as const
+  const inputs = { pricer: { sku: 'A-1' }, writer: { topic: 'Pricing' } }
+
+  /** `decide()` answers where only the given agents say yes. */
+  function yesTo(...names: Array<(typeof inputDesk)[number]['name']>) {
+    return {
+      researcher: { value: names.includes('researcher') },
+      pricer: { value: names.includes('pricer') },
+      writer: { value: names.includes('writer') },
+      seo: { value: names.includes('seo') },
+      order: { value: 'parallel' as const },
+    }
+  }
+
+  it('lists the picked agents that need input, in agent-list order', () => {
+    const route = subagentRoute(inputDesk)
+
+    expect(route.needsInput(yesTo('researcher', 'pricer', 'seo'))).toEqual([
+      { name: 'pricer', inputSchema: skuSchema },
+    ])
+    expect(route.needsInput(yesTo('writer', 'pricer'))).toEqual([
+      { name: 'pricer', inputSchema: skuSchema },
+      { name: 'writer', inputSchema: topicSchema },
+    ])
+    expect(route.needsInput(yesTo('researcher', 'seo'))).toEqual([])
+  })
+
+  it('puts each input on its name in a single pick and in names', () => {
+    const route = subagentRoute(inputDesk)
+
+    expect(route.pick(yesTo('pricer'), { inputs })).toEqual({
+      name: 'pricer',
+      input: { sku: 'A-1' },
+    })
+    expect(
+      route.pick(yesTo('researcher', 'pricer', 'writer'), { inputs }),
+    ).toEqual({
+      names: [
+        'researcher',
+        { name: 'pricer', input: { sku: 'A-1' } },
+        { name: 'writer', input: { topic: 'Pricing' } },
+      ],
+      order: 'parallel',
+    })
+  })
+
+  it('puts each input on its name in each step', () => {
+    const route = subagentRoute(inputDesk, { then: ['writer'] })
+
+    expect(
+      route.pick(yesTo('researcher', 'pricer', 'writer'), { inputs }),
+    ).toEqual({
+      steps: [
+        {
+          names: ['researcher', { name: 'pricer', input: { sku: 'A-1' } }],
+          order: 'parallel',
+        },
+        { names: [{ name: 'writer', input: { topic: 'Pricing' } }] },
+      ],
+    })
+  })
+
+  it('throws when a picked agent with a schema has no input', () => {
+    const route = subagentRoute(inputDesk)
+
+    expect(() => route.pick(yesTo('researcher', 'pricer'))).toThrow(
+      'Agent "pricer" needs input. Pass it in inputs.',
+    )
+  })
 })
 
 describe('defineAgent', () => {
@@ -488,27 +598,14 @@ describe('chat({ subagents }) router spawn', () => {
   })
 
   it('does not start the next step after a subagent error', async () => {
-    const chunks = await collectChunks(
-      chat({
-        adapter: parentAdapter().adapter,
-        messages: [{ role: 'user', content: 'Go' }],
-        subagents: {
-          agents: [
-            defineAgent({
-              name: 'researcher',
-              description: 'Looks up facts',
-              run: async function* () {
-                throw new Error('lookup failed')
-              },
-            }),
-            namedAgent('writer'),
-          ],
-          strategy: 'exclusive',
-          router: () => ({
-            steps: [{ names: ['researcher'] }, { names: ['writer'] }],
-          }),
-        },
-      }) as AsyncIterable<StreamChunk>,
+    const chunks = await routeTo(
+      [
+        namedAgent('researcher', async function* () {
+          throw new Error('lookup failed')
+        }),
+        namedAgent('writer'),
+      ],
+      { steps: [{ names: ['researcher'] }, { names: ['writer'] }] },
     )
 
     expect(
@@ -548,32 +645,21 @@ describe('chat({ subagents }) router spawn', () => {
   })
 
   it("puts the failing child's own message and code on RUN_ERROR", async () => {
-    const chunks = await collectChunks(
-      chat({
-        adapter: parentAdapter().adapter,
-        messages: [{ role: 'user', content: 'Go' }],
-        subagents: {
-          agents: [
-            defineAgent({
-              name: 'researcher',
-              description: 'Looks up facts',
-              run: async function* () {
-                yield ev.runStarted('child-run', 'child-thread')
-                yield {
-                  type: EventType.RUN_ERROR,
-                  threadId: 'child-thread',
-                  runId: 'child-run',
-                  message: 'provider returned 500',
-                  code: 'upstream_error',
-                  timestamp: Date.now(),
-                }
-              },
-            }),
-          ],
-          strategy: 'exclusive',
-          router: () => ['researcher'],
-        },
-      }) as AsyncIterable<StreamChunk>,
+    const chunks = await routeTo(
+      [
+        namedAgent('researcher', async function* () {
+          yield ev.runStarted('child-run', 'child-thread')
+          yield {
+            type: EventType.RUN_ERROR,
+            threadId: 'child-thread',
+            runId: 'child-run',
+            message: 'provider returned 500',
+            code: 'upstream_error',
+            timestamp: Date.now(),
+          }
+        }),
+      ],
+      ['researcher'],
     )
 
     const error = chunks.find((chunk) => chunk.type === 'RUN_ERROR')
@@ -584,29 +670,22 @@ describe('chat({ subagents }) router spawn', () => {
   })
 
   it("keeps a finished sibling's usage on the failed turn", async () => {
-    const chunks = await collectChunks(
-      chat({
-        adapter: parentAdapter().adapter,
-        messages: [{ role: 'user', content: 'Go' }],
-        subagents: {
-          agents: [
-            namedAgent('writer', async function* () {
-              yield ev.runStarted('writer-run', 'writer-thread')
-              yield ev.runFinished(
-                'stop',
-                'writer-run',
-                { promptTokens: 11, completionTokens: 7, totalTokens: 18 },
-                'writer-thread',
-              )
-            }),
-            namedAgent('researcher', async function* () {
-              throw new Error('lookup failed')
-            }),
-          ],
-          strategy: 'exclusive',
-          router: () => ({ names: ['writer', 'researcher'] }),
-        },
-      }) as AsyncIterable<StreamChunk>,
+    const chunks = await routeTo(
+      [
+        namedAgent('writer', async function* () {
+          yield ev.runStarted('writer-run', 'writer-thread')
+          yield ev.runFinished(
+            'stop',
+            'writer-run',
+            { promptTokens: 11, completionTokens: 7, totalTokens: 18 },
+            'writer-thread',
+          )
+        }),
+        namedAgent('researcher', async function* () {
+          throw new Error('lookup failed')
+        }),
+      ],
+      { names: ['writer', 'researcher'] },
     )
 
     const error = chunks.find((chunk) => chunk.type === 'RUN_ERROR')
@@ -671,6 +750,24 @@ describe('chat({ subagents }) router spawn', () => {
       "subagents.sandbox 'inherit' cannot start two children in one turn",
     )
   })
+
+  it('lists the agents the router can pick when it picks an unknown one', async () => {
+    await expect(
+      routeTo([researcherAgent('ok'), namedAgent('writer')], 'pricer'),
+    ).rejects.toThrow(
+      'Unknown subagent: pricer. The router can pick: researcher, writer.',
+    )
+  })
+
+  const emptyPicks: Array<[string, SubagentRouterPick]> = [
+    ['an empty list', []],
+    ['empty steps', { steps: [] }],
+  ]
+  it.each(emptyPicks)('fails on %s', async (_label, pick) => {
+    await expect(routeTo([namedAgent('writer')], pick)).rejects.toThrow(
+      'subagents.router must return main, a name, a list of names, { names, order }, or { steps }.',
+    )
+  })
 })
 
 describe('chat({ subagents }) synthetic tools', () => {
@@ -712,7 +809,10 @@ describe('chat({ subagents }) synthetic tools', () => {
 })
 
 describe('defineAgent inputSchema', () => {
-  const briefSchema = z.object({ task: z.string() })
+  const briefSchema = z.object({
+    task: z.string({ error: 'task must be text' }),
+  })
+  const brief = { task: 'Price Vendor A' }
 
   /** A parent model that calls `researcher` once per args string, then stops. */
   function parentCalling(...args: Array<string>) {
@@ -875,26 +975,59 @@ describe('defineAgent inputSchema', () => {
     expect(inputs).toEqual([undefined])
   })
 
-  it('throws when a router meets an agent with inputSchema', async () => {
-    const { agent } = briefResearcher()
-    let routerCalls = 0
+  const routedPicks: Array<[string, SubagentRouterPick]> = [
+    ['a single pick', { name: 'researcher', input: brief }],
+    ['a list', ['writer', { name: 'researcher', input: brief }]],
+    [
+      'a names plan',
+      { names: [{ name: 'researcher', input: brief }], order: 'sequence' },
+    ],
+    [
+      'a later step',
+      {
+        steps: [
+          { names: ['writer'] },
+          { names: [{ name: 'researcher', input: brief }] },
+        ],
+      },
+    ],
+  ]
+  it.each(routedPicks)(
+    'passes the router input to run as ctx.input for %s',
+    async (_label, pick) => {
+      const { agent, inputs } = briefResearcher()
+      await routeTo([agent, namedAgent('writer')], pick)
+      expect(inputs).toEqual([{ task: 'Price Vendor A' }])
+    },
+  )
+
+  it('fails before any child starts when a picked agent has no input', async () => {
+    const { agent, inputs } = briefResearcher()
+    let writerRuns = 0
+    const writer = namedAgent('writer', async function* () {
+      writerRuns += 1
+    })
 
     await expect(
-      collectChunks(
-        chat({
-          adapter: parentAdapter().adapter,
-          messages: [{ role: 'user', content: 'Compare pricing' }],
-          subagents: {
-            agents: [agent],
-            router: () => {
-              routerCalls += 1
-              return 'main'
-            },
-          },
-        }) as AsyncIterable<StreamChunk>,
-      ),
-    ).rejects.toThrow('Subagent "researcher" has an inputSchema')
-    expect(routerCalls).toBe(0)
+      routeTo([agent, writer], {
+        steps: [{ names: ['writer'] }, { names: ['researcher'] }],
+      }),
+    ).rejects.toThrow(
+      `Agent "researcher" needs input. Return { name: 'researcher', input } from the router.`,
+    )
+    expect(writerRuns).toBe(0)
+    expect(inputs).toEqual([])
+  })
+
+  it('fails when the router input does not match the schema', async () => {
+    const { agent, inputs } = briefResearcher()
+
+    await expect(
+      routeTo([agent], { name: 'researcher', input: { task: 42 } }),
+    ).rejects.toThrow(
+      'Input validation failed for agent researcher: task must be text',
+    )
+    expect(inputs).toEqual([])
   })
 })
 
diff --git a/packages/ai/tests/subagent-interrupts.test.ts b/packages/ai/tests/subagent-interrupts.test.ts
index f7eb5408ee..c310394117 100644
--- a/packages/ai/tests/subagent-interrupts.test.ts
+++ b/packages/ai/tests/subagent-interrupts.test.ts
@@ -548,6 +548,88 @@ describe('subagent interrupts', () => {
     expect(inputs).toEqual([{ folder: 'old' }, { folder: 'old' }])
     expect(execute).toHaveBeenCalledTimes(1)
   })
+
+  it('keeps the router inputs of a steps plan across a resume', async () => {
+    const { run, execute } = cleanerChild()
+    const cleanerInputs: Array<{ folder: string }> = []
+    const pricerInputs: Array<{ vendor: string }> = []
+    const cleaner = defineAgent({
+      name: 'cleaner',
+      description: 'Deletes files',
+      inputSchema: z.object({ folder: z.string() }),
+      run: (ctx) => {
+        cleanerInputs.push(ctx.input)
+        return run(ctx)
+      },
+    })
+    const pricer = defineAgent({
+      name: 'pricer',
+      description: 'Prices a vendor',
+      inputSchema: z.object({ vendor: z.string() }),
+      run: async function* (ctx) {
+        pricerInputs.push(ctx.input)
+      },
+    })
+    const parent = createMockAdapter({ iterations: [] }).adapter
+    const router = vi.fn(() => ({
+      steps: [
+        { names: [{ name: 'cleaner', input: { folder: 'old' } }] },
+        { names: [{ name: 'pricer', input: { vendor: 'acme' } }] },
+      ],
+    }))
+    const subagents = { agents: [cleaner, pricer], router }
+
+    const first = await collectChunks(
+      chat({
+        adapter: parent,
+        threadId: 't',
+        runId: 'run-1',
+        messages: [user],
+        subagents,
+      }),
+    )
+    // The plan on the start event keeps each input for the resume.
+    expect(
+      first.find((chunk) => chunk.type === EventType.SUBAGENT_STARTED),
+    ).toMatchObject({
+      metadata: {
+        tanstack: {
+          subagentPlan: {
+            steps: [
+              { names: ['cleaner'], inputs: { cleaner: { folder: 'old' } } },
+              { names: ['pricer'], inputs: { pricer: { vendor: 'acme' } } },
+            ],
+          },
+        },
+      },
+    })
+    expect(pricerInputs).toEqual([])
+
+    const processor = new StreamProcessor({ initialMessages: [user] })
+    replay(processor, first)
+    processor.addToolApprovalResponse('approval_call_c', true)
+    const second = await collectChunks(
+      chat({
+        adapter: parent,
+        threadId: 't',
+        runId: 'run-2',
+        parentRunId: 'run-1',
+        messages: requestMessages(processor.getMessages()),
+        resume: [
+          { interruptId: 'approval_call_c', status: 'resolved', payload: true },
+        ],
+        subagents,
+      }),
+    )
+
+    expect(second.some((chunk) => chunk.type === EventType.RUN_ERROR)).toBe(
+      false,
+    )
+    expect(router).toHaveBeenCalledTimes(1)
+    expect(execute).toHaveBeenCalledTimes(1)
+    expect(cleanerInputs).toEqual([{ folder: 'old' }, { folder: 'old' }])
+    expect(pricerInputs).toEqual([{ vendor: 'acme' }])
+  })
 })
 
 describe('subagent cards', () => {
diff --git a/packages/ai/tests/subagent-route-types.test-d.ts b/packages/ai/tests/subagent-route-types.test-d.ts
new file mode 100644
index 0000000000..7c4804c1cd
--- /dev/null
+++ b/packages/ai/tests/subagent-route-types.test-d.ts
@@ -0,0 +1,66 @@
+import { expectTypeOf } from 'vitest'
+import { z } from 'zod'
+import { defineAgent, subagentRoute } from '../src'
+import type { DefinedAgent } from '../src'
+
+const skuSchema = z.object({ sku: z.string() })
+const topicSchema = z.object({ topic: z.string() })
+
+const agents = [
+  defineAgent({
+    name: 'researcher',
+    description: 'Looks up facts',
+    run: async function* () {},
+  }),
+  defineAgent({
+    name: 'pricer',
+    description: 'Prices one product',
+    inputSchema: skuSchema,
+    run: async function* () {},
+  }),
+  defineAgent({
+    name: 'writer',
+    description: 'Writes the post',
+    inputSchema: topicSchema,
+    run: async function* () {},
+  }),
+] as const
+
+const route = subagentRoute(agents)
+declare const result: Parameters<typeof route.pick>[0]
+
+// `needsInput` lists only agents with a schema, each with its own schema.
+type Need = ReturnType<typeof route.needsInput>[number]
+expectTypeOf<Need['name']>().toEqualTypeOf<'pricer' | 'writer'>()
+expectTypeOf<Extract<Need, { name: 'pricer' }>['inputSchema']>().toEqualTypeOf<
+  typeof skuSchema
+>()
+
+// `inputs` has one optional key for each agent with a schema.
+expectTypeOf<
+  NonNullable<NonNullable<Parameters<typeof route.pick>[1]>['inputs']>
+>().toEqualTypeOf<{ pricer?: { sku: string }; writer?: { topic: string } }>()
+
+route.pick(result, {
+  inputs: { pricer: { sku: 'A-1' }, writer: { topic: 'Pricing' } },
+})
+route.pick(result, { inputs: { pricer: { sku: 'A-1' } } })
+route.pick(result)
+
+route.pick(result, {
+  // @ts-expect-error researcher has no inputSchema, so it takes no input
+  inputs: { researcher: { sku: 'A-1' } },
+})
+
+route.pick(result, {
+  inputs: {
+    // @ts-expect-error the pricer input is { sku: string }
+    pricer: { topic: 'Pricing' },
+  },
+})
+
+// A list with the wide agent type takes an input for any name.
+declare const wideAgents: ReadonlyArray<DefinedAgent>
+const wideRoute = subagentRoute(wideAgents)
+declare const wideResult: Parameters<typeof wideRoute.pick>[0]
+wideRoute.pick(wideResult, { inputs: { pricer: { sku: 'A-1' } } })
diff --git a/testing/e2e/fixtures/harness/basic.json b/testing/e2e/fixtures/harness/basic.json
index dffde59aef..7f3a063c26 100644
--- a/testing/e2e/fixtures/harness/basic.json
+++ b/testing/e2e/fixtures/harness/basic.json
@@ -40,6 +40,54 @@
         "content": "The waiter stopped before it finished."
       }
     },
+    {
+      "match": {
+        "userMessage": "[harness-routing:writer] [harness-routing] write"
+      },
+      "response": {
+        "content": "Here is a short draft."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-routing] hello"
+      },
+      "response": {
+        "content": "Hello from the main model."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-routing:researcher] [harness-routing] article"
+      },
+      "response": {
+        "content": "Bees make honey."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-routing:seo] [harness-routing] article"
+      },
+      "response": {
+        "content": "Use the keyword honey."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-routing:writer] Bees make honey.\n\nUse the keyword honey."
+      },
+      "response": {
+        "content": "Bees make honey, so buy honey."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-routing:pricer] acme"
+      },
+      "response": {
+        "content": "Acme costs 30 dollars."
+      }
+    },
     {
       "match": {
         "userMessage": "[harness-protocol] hello"
diff --git a/testing/e2e/src/routes/api.harness-test.ts b/testing/e2e/src/routes/api.harness-test.ts
index 110d03f755..5759a8851d 100644
--- a/testing/e2e/src/routes/api.harness-test.ts
+++ b/testing/e2e/src/routes/api.harness-test.ts
@@ -8,8 +8,94 @@ import {
 } from '@tanstack/ai-harness'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { z } from 'zod'
+import type { ModelMessage, UIMessage } from '@tanstack/ai'
+import type { HarnessHost } from '@tanstack/ai-harness'
 import { createTextAdapter } from '@/lib/providers'
 
+/** The plain text of the last message, or '' when it has no plain text. */
+function lastText(messages: ReadonlyArray<UIMessage | ModelMessage>) {
+  const last = messages.at(-1)
+  if (last === undefined || !('content' in last)) return ''
+  return typeof last.content === 'string' ? last.content : ''
+}
+
+/**
+ * A harness with `routing`. The router reads the last user message and picks
+ * one root agent, the main model, a plan of two steps, or an agent with typed
+ * input. The four prompts run in order on one session. Returns the text of
+ * each turn.
+ */
+async function routingTurns(
+  host: HarnessHost,
+  openai: () => ReturnType<typeof createTextAdapter>['adapter'],
+) {
+  // The agent asks the model with its name and the text of the last message.
+  // In the second step of a plan, that message is the text of the first step.
+  const asker = (name: string) =>
+    defineAgent({
+      name,
+      description: `Answers as the ${name}`,
+      run: (ctx) =>
+        ctx.chat({
+          adapter: openai(),
+          messages: [
+            {
+              role: 'user',
+              content: `[harness-routing:${name}] ${lastText(ctx.messages)}`,
+            },
+          ],
+          stream: false,
+        }),
+    })
+  const pricer = defineAgent({
+    name: 'pricer',
+    description: 'Prices one vendor',
+    inputSchema: z.object({ vendor: z.string() }),
+    run: (ctx) =>
+      ctx.chat({
+        adapter: openai(),
+        messages: [
+          {
+            role: 'user',
+            content: `[harness-routing:pricer] ${ctx.input.vendor}`,
+          },
+        ],
+        stream: false,
+      }),
+  })
+  const harness = defineHarness({
+    name: 'e2e/harness-routing',
+    adapter: openai(),
+    agents: [asker('writer'), asker('researcher'), asker('seo'), pricer],
+    routing: {
+      router: ({ messages }) => {
+        switch (lastText(messages)) {
+          case '[harness-routing] write':
+            return 'writer'
+          case '[harness-routing] article':
+            return {
+              steps: [
+                { names: ['researcher', 'seo'], order: 'parallel' },
+                { names: ['writer'] },
+              ],
+            }
+          case '[harness-routing] price':
+            return { name: 'pricer', input: { vendor: 'acme' } }
+          default:
+            return 'main'
+        }
+      },
+    },
+  })
+  const session = await host.open(harness, { threadId: 'e2e-routing' })
+  const prompts = ['write', 'hello', 'article', 'price']
+  const texts: Array<string> = []
+  for (const prompt of prompts) {
+    texts.push((await session.prompt(`[harness-routing] ${prompt}`)).text)
+  }
+  return { texts }
+}
+
 /**
  * Start a background agent on a durable host, and let that host stop: its
  * short lease is not renewed in time. A second host opens the same log. It
@@ -73,6 +159,8 @@ async function agentRestart(
  *   the transcript, then a prompt runs.
  * - `agent-restart`: a background agent runs on a durable host that stops.
  *   The next host fails the run and wakes the thread.
+ * - `routing`: `routing.router` sends each of four turns to root agents or
+ *   to the main model.
  */
 export const Route = createFileRoute('/api/harness-test')({
   server: {
@@ -152,6 +240,9 @@ export const Route = createFileRoute('/api/harness-test')({
           if (body.scenario === 'agent-restart') {
             return Response.json(await agentRestart(openai))
           }
+          if (body.scenario === 'routing') {
+            return Response.json(await routingTurns(host, openai))
+          }
           if (body.scenario === 'agent') {
             const result = await session.agents.pricer.run({
               task: '[harness-agent] price vendor a',
diff --git a/testing/e2e/tests/harness.spec.ts b/testing/e2e/tests/harness.spec.ts
index be9c767f78..5529413bb5 100644
--- a/testing/e2e/tests/harness.spec.ts
+++ b/testing/e2e/tests/harness.spec.ts
@@ -70,4 +70,22 @@ test.describe('harness session', () => {
     expect(body.status).toBe('failed')
     expect(body.text).toBe('The waiter stopped before it finished.')
   })
+
+  test('routing.router sends each turn to the picked root agents or to the main model', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'routing', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    expect((await response.json()).texts).toEqual([
+      'writer:\nHere is a short draft.',
+      'Hello from the main model.',
+      // The writer of the second step answers the text of the first step.
+      'researcher:\nBees make honey.\n\nseo:\nUse the keyword honey.\n\nwriter:\nBees make honey, so buy honey.',
+      'pricer:\nAcme costs 30 dollars.',
+    ])
+  })
 })

From 5001eca81fd545d8bff0d26712ab7916d277c5e9 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 13:18:06 +0200
Subject: [PATCH 165/286] feat(ai): add the ModelMessage block order map and
 its helpers

ModelMessage.blockOrder lists the blocks of an assistant message in the order the model sent them. buildBlockOrder writes the map, and orderedAssistantBlocks reads it back or gives undefined for an invalid map.
---
 packages/ai/src/adapter-internals.ts     |   8 +
 packages/ai/src/index.ts                 |   2 +
 packages/ai/src/types.ts                 |  17 ++
 packages/ai/src/utilities/block-order.ts | 111 +++++++++
 packages/ai/tests/block-order.test.ts    | 278 +++++++++++++++++++++++
 5 files changed, 416 insertions(+)
 create mode 100644 packages/ai/src/utilities/block-order.ts
 create mode 100644 packages/ai/tests/block-order.test.ts

diff --git a/packages/ai/src/adapter-internals.ts b/packages/ai/src/adapter-internals.ts
index e0bd7f68c7..8e643f8e40 100644
--- a/packages/ai/src/adapter-internals.ts
+++ b/packages/ai/src/adapter-internals.ts
@@ -67,3 +67,11 @@ export {
 export { tanstackMetadata } from './utilities/merge-metadata'
 export { isSpecTopLevelKey } from './utilities/spec-event-keys'
 export { REDACTED_THINKING_ID_PREFIX } from './utilities/reasoning-encrypted-value'
+export {
+  buildBlockOrder,
+  orderedAssistantBlocks,
+} from './utilities/block-order'
+export type {
+  BlockOrderEntry,
+  OrderedAssistantBlock,
+} from './utilities/block-order'
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index 5e2ebf53ee..58be99d5e3 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -600,6 +600,8 @@ export {
   getProviderExecutedMetadata,
   isProviderExecutedToolCall,
 } from './utilities/provider-executed'
+export { orderedAssistantBlocks } from './utilities/block-order'
+export type { OrderedAssistantBlock } from './utilities/block-order'
 
 // Adapter extension utilities
 export { createModel, extendAdapter } from './extend-adapter'
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index 222f0538f2..f99191d68b 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -371,6 +371,15 @@ export type ConstrainedContent<
   | null
   | Array<ContentPartForInputModalitiesTypes<TInputModalitiesTypes>>
 
+/**
+ * One block of an assistant `ModelMessage`, in the order the model sent it.
+ * Each entry points into a field of the message. See `ModelMessage.blockOrder`.
+ */
+export type ModelMessageBlock =
+  | { type: 'thinking'; index: number }
+  | { type: 'text'; length: number }
+  | { type: 'tool-call'; id: string }
+
 export interface ModelMessage<
   TContent extends string | null | Array<ContentPart> =
     | string
@@ -388,6 +397,14 @@ export interface ModelMessage<
    * opaque data. See `ThinkingPart.signature` for the planned rename.
    */
   thinking?: Array<{ content: string; signature?: string; redacted?: boolean }>
+  /**
+   * The order of the blocks of an assistant message, when it is not the
+   * default order (all thinking, then the text, then the tool calls). Each
+   * entry points into `thinking`, into `content` (a string, by UTF-16 length),
+   * or into `toolCalls`. The library writes and reads this field. A reader
+   * that finds a map that does not match the message uses the default order.
+   */
+  blockOrder?: Array<ModelMessageBlock>
   /** Error reported by an AG-UI tool message. */
   error?: string
   /** Optional AG-UI message metadata. TanStack-owned fields live under `tanstack`. */
diff --git a/packages/ai/src/utilities/block-order.ts b/packages/ai/src/utilities/block-order.ts
new file mode 100644
index 0000000000..b2bf985389
--- /dev/null
+++ b/packages/ai/src/utilities/block-order.ts
@@ -0,0 +1,111 @@
+import type { ModelMessage, ModelMessageBlock, ToolCall } from '../types'
+
+/** One block of an assistant answer, in the order the model produced it. */
+export type BlockOrderEntry =
+  | { type: 'thinking' }
+  | { type: 'text'; text: string }
+  | { type: 'tool-call'; id: string }
+
+/**
+ * The order map for these entries in produced order, or undefined when they
+ * are in the default order (all thinking, then text, then tool calls).
+ * Adjacent text entries merge into one, and empty text is left out. The n-th
+ * thinking entry gets index n.
+ */
+export function buildBlockOrder(
+  entries: ReadonlyArray<BlockOrderEntry>,
+): Array<ModelMessageBlock> | undefined {
+  const blocks: Array<ModelMessageBlock> = []
+  let thinking = 0
+  let isDefault = true
+  for (const entry of entries) {
+    const last = blocks.at(-1)
+    if (entry.type === 'thinking') {
+      if (last !== undefined && last.type !== 'thinking') isDefault = false
+      blocks.push({ type: 'thinking', index: thinking++ })
+    } else if (entry.type === 'text') {
+      if (entry.text === '') continue
+      if (last?.type === 'text') {
+        last.length += entry.text.length
+        continue
+      }
+      if (last?.type === 'tool-call') isDefault = false
+      blocks.push({ type: 'text', length: entry.text.length })
+    } else {
+      blocks.push({ type: 'tool-call', id: entry.id })
+    }
+  }
+  return isDefault ? undefined : blocks
+}
+
+/** A block of an assistant message, resolved from its order map. */
+export type OrderedAssistantBlock =
+  | {
+      type: 'thinking'
+      thinking: NonNullable<ModelMessage['thinking']>[number]
+    }
+  | { type: 'text'; text: string }
+  | { type: 'tool-call'; toolCall: ToolCall }
+
+/**
+ * The blocks of an assistant message in map order, or undefined when the
+ * message has no map or the map does not match the message. A map matches
+ * when it uses each `thinking` entry and each `toolCalls` entry exactly once,
+ * and its text lengths add up to the length of the text content (`null`
+ * content counts as no text). Readers use the default order when this
+ * returns undefined.
+ */
+export function orderedAssistantBlocks(
+  message: ModelMessage,
+): Array<OrderedAssistantBlock> | undefined {
+  const order = message.blockOrder
+  if (!Array.isArray(order) || order.length === 0) return undefined
+  const content = message.content ?? ''
+  if (typeof content !== 'string') return undefined
+  const thinking = message.thinking ?? []
+  const toolCalls = message.toolCalls ?? []
+  const usedThinking = new Set<number>()
+  const usedCalls = new Set<string>()
+  const blocks: Array<OrderedAssistantBlock> = []
+  let offset = 0
+  for (const block of order) {
+    // Stored data can hold anything, so check each entry.
+    if (typeof block !== 'object' || block === null) return undefined
+    if (block.type === 'thinking') {
+      const entry = Number.isInteger(block.index)
+        ? thinking[block.index]
+        : undefined
+      if (entry === undefined || usedThinking.has(block.index)) {
+        return undefined
+      }
+      usedThinking.add(block.index)
+      blocks.push({ type: 'thinking', thinking: entry })
+    } else if (block.type === 'text') {
+      const end = offset + block.length
+      if (
+        !Number.isInteger(block.length) ||
+        block.length <= 0 ||
+        end > content.length
+      ) {
+        return undefined
+      }
+      blocks.push({ type: 'text', text: content.slice(offset, end) })
+      offset = end
+    } else if (block.type === 'tool-call') {
+      const toolCall = toolCalls.find((candidate) => candidate.id === block.id)
+      if (toolCall === undefined || usedCalls.has(block.id)) return undefined
+      usedCalls.add(block.id)
+      blocks.push({ type: 'tool-call', toolCall })
+    } else {
+      return undefined
+    }
+  }
+  if (
+    offset !== content.length ||
+    usedThinking.size !== thinking.length ||
+    usedCalls.size !== toolCalls.length
+  ) {
+    return undefined
+  }
+  return blocks
+}
diff --git a/packages/ai/tests/block-order.test.ts b/packages/ai/tests/block-order.test.ts
new file mode 100644
index 0000000000..af31475bcf
--- /dev/null
+++ b/packages/ai/tests/block-order.test.ts
@@ -0,0 +1,278 @@
+import { describe, expect, it } from 'vitest'
+import * as adapterInternals from '../src/adapter-internals'
+import * as ai from '../src/index'
+import {
+  buildBlockOrder,
+  orderedAssistantBlocks,
+} from '../src/utilities/block-order'
+import type { OrderedAssistantBlock } from '../src/utilities/block-order'
+import type { ModelMessage, ModelMessageBlock, ToolCall } from '../src/types'
+
+function call(id: string): ToolCall {
+  return {
+    id,
+    type: 'function',
+    function: { name: 'lookup', arguments: '{}' },
+  }
+}
+
+/** A short text form of resolved blocks, for readable assertions. */
+function describeBlocks(blocks: Array<OrderedAssistantBlock> | undefined) {
+  return blocks?.map((block) =>
+    block.type === 'thinking'
+      ? `thinking:${block.thinking.content}`
+      : block.type === 'text'
+        ? `text:${block.text}`
+        : `tool-call:${block.toolCall.id}`,
+  )
+}
+
+const thinking = [
+  { content: 'plan', signature: 'sig-a' },
+  { content: 'check', signature: 'sig-b' },
+]
+
+/** thinking, text "A", tool call, thinking, text "B" */
+const interleaved: ModelMessage = {
+  role: 'assistant',
+  content: 'AB',
+  thinking,
+  toolCalls: [call('call_1')],
+  blockOrder: [
+    { type: 'thinking', index: 0 },
+    { type: 'text', length: 1 },
+    { type: 'tool-call', id: 'call_1' },
+    { type: 'thinking', index: 1 },
+    { type: 'text', length: 1 },
+  ],
+}
+
+function withOrder(blockOrder: Array<ModelMessageBlock>): ModelMessage {
+  return { ...interleaved, blockOrder }
+}
+
+describe('buildBlockOrder', () => {
+  it('returns undefined for the default order', () => {
+    expect(
+      buildBlockOrder([
+        { type: 'thinking' },
+        { type: 'thinking' },
+        { type: 'text', text: 'Hel' },
+        { type: 'text', text: 'lo' },
+        { type: 'tool-call', id: 'call_1' },
+        { type: 'tool-call', id: 'call_2' },
+      ]),
+    ).toBeUndefined()
+    expect(buildBlockOrder([])).toBeUndefined()
+  })
+
+  it('maps thinking, tool call, thinking, tool call', () => {
+    expect(
+      buildBlockOrder([
+        { type: 'thinking' },
+        { type: 'tool-call', id: 'call_1' },
+        { type: 'thinking' },
+        { type: 'tool-call', id: 'call_2' },
+      ]),
+    ).toEqual([
+      { type: 'thinking', index: 0 },
+      { type: 'tool-call', id: 'call_1' },
+      { type: 'thinking', index: 1 },
+      { type: 'tool-call', id: 'call_2' },
+    ])
+  })
+
+  it('maps text after a tool call', () => {
+    expect(
+      buildBlockOrder([
+        { type: 'text', text: 'A' },
+        { type: 'tool-call', id: 'call_1' },
+        { type: 'text', text: 'B' },
+      ]),
+    ).toEqual([
+      { type: 'text', length: 1 },
+      { type: 'tool-call', id: 'call_1' },
+      { type: 'text', length: 1 },
+    ])
+  })
+
+  it('merges adjacent text and leaves out empty text', () => {
+    expect(
+      buildBlockOrder([
+        { type: 'thinking' },
+        { type: 'text', text: 'Hel' },
+        { type: 'text', text: 'lo' },
+        { type: 'thinking' },
+        { type: 'text', text: '' },
+        { type: 'text', text: 'B' },
+      ]),
+    ).toEqual([
+      { type: 'thinking', index: 0 },
+      { type: 'text', length: 5 },
+      { type: 'thinking', index: 1 },
+      { type: 'text', length: 1 },
+    ])
+  })
+
+  it('keeps an emoji text block whole', () => {
+    // "Done 👍" is 7 UTF-16 code units: the emoji is a surrogate pair.
+    const blockOrder = buildBlockOrder([
+      { type: 'thinking' },
+      { type: 'text', text: 'Done 👍' },
+      { type: 'thinking' },
+      { type: 'text', text: 'Next' },
+    ])
+    expect(blockOrder).toEqual([
+      { type: 'thinking', index: 0 },
+      { type: 'text', length: 7 },
+      { type: 'thinking', index: 1 },
+      { type: 'text', length: 4 },
+    ])
+
+    const blocks = orderedAssistantBlocks({
+      role: 'assistant',
+      content: 'Done 👍Next',
+      thinking,
+      blockOrder,
+    })
+    expect(describeBlocks(blocks)).toEqual([
+      'thinking:plan',
+      'text:Done 👍',
+      'thinking:check',
+      'text:Next',
+    ])
+  })
+})
+
+describe('orderedAssistantBlocks', () => {
+  it('returns undefined when the message has no map', () => {
+    expect(
+      orderedAssistantBlocks({ ...interleaved, blockOrder: undefined }),
+    ).toBeUndefined()
+  })
+
+  it('resolves the blocks in map order', () => {
+    expect(describeBlocks(orderedAssistantBlocks(interleaved))).toEqual([
+      'thinking:plan',
+      'text:A',
+      'tool-call:call_1',
+      'thinking:check',
+      'text:B',
+    ])
+  })
+
+  it.each([
+    { label: 'null', content: null },
+    { label: 'empty', content: '' },
+  ])(
+    'reads a map with no text on a message with $label content',
+    ({ content }) => {
+      const blocks = orderedAssistantBlocks({
+        role: 'assistant',
+        content,
+        thinking,
+        toolCalls: [call('call_1'), call('call_2')],
+        blockOrder: [
+          { type: 'thinking', index: 0 },
+          { type: 'tool-call', id: 'call_1' },
+          { type: 'thinking', index: 1 },
+          { type: 'tool-call', id: 'call_2' },
+        ],
+      })
+      expect(describeBlocks(blocks)).toEqual([
+        'thinking:plan',
+        'tool-call:call_1',
+        'thinking:check',
+        'tool-call:call_2',
+      ])
+    },
+  )
+
+  const invalid: Array<{ name: string; message: ModelMessage }> = [
+    {
+      name: 'a thinking index is out of range',
+      message: withOrder([
+        { type: 'thinking', index: 0 },
+        { type: 'text', length: 1 },
+        { type: 'tool-call', id: 'call_1' },
+        { type: 'thinking', index: 2 },
+        { type: 'text', length: 1 },
+      ]),
+    },
+    {
+      name: 'a thinking entry is used twice',
+      message: withOrder([
+        { type: 'thinking', index: 0 },
+        { type: 'text', length: 1 },
+        { type: 'tool-call', id: 'call_1' },
+        { type: 'thinking', index: 1 },
+        { type: 'thinking', index: 0 },
+        { type: 'text', length: 1 },
+      ]),
+    },
+    {
+      name: 'a thinking entry is left out',
+      message: withOrder([
+        { type: 'thinking', index: 0 },
+        { type: 'text', length: 2 },
+        { type: 'tool-call', id: 'call_1' },
+      ]),
+    },
+    {
+      name: 'a tool call id is not in toolCalls',
+      message: withOrder([
+        { type: 'thinking', index: 0 },
+        { type: 'text', length: 1 },
+        { type: 'tool-call', id: 'call_x' },
+        { type: 'thinking', index: 1 },
+        { type: 'text', length: 1 },
+      ]),
+    },
+    {
+      name: 'a tool call is used twice',
+      message: withOrder([
+        { type: 'thinking', index: 0 },
+        { type: 'text', length: 1 },
+        { type: 'tool-call', id: 'call_1' },
+        { type: 'thinking', index: 1 },
+        { type: 'tool-call', id: 'call_1' },
+        { type: 'text', length: 1 },
+      ]),
+    },
+    {
+      name: 'a tool call is left out',
+      message: withOrder([
+        { type: 'thinking', index: 0 },
+        { type: 'text', length: 1 },
+        { type: 'thinking', index: 1 },
+        { type: 'text', length: 1 },
+      ]),
+    },
+    {
+      name: 'the text lengths do not add up to the content length',
+      message: withOrder([
+        { type: 'thinking', index: 0 },
+        { type: 'text', length: 1 },
+        { type: 'tool-call', id: 'call_1' },
+        { type: 'thinking', index: 1 },
+        { type: 'text', length: 2 },
+      ]),
+    },
+    {
+      name: 'the content is a part array',
+      message: { ...interleaved, content: [{ type: 'text', content: 'AB' }] },
+    },
+  ]
+
+  it.each(invalid)('returns undefined when $name', ({ message }) => {
+    expect(orderedAssistantBlocks(message)).toBeUndefined()
+  })
+})
+
+describe('block order exports', () => {
+  it('reaches adapters from both entry points', () => {
+    expect(ai.orderedAssistantBlocks).toBe(orderedAssistantBlocks)
+    expect(adapterInternals.orderedAssistantBlocks).toBe(orderedAssistantBlocks)
+    expect(adapterInternals.buildBlockOrder).toBe(buildBlockOrder)
+  })
+})

From 6ef48471918b602399bc9c2dcbc2cf5232c091a4 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 13:18:06 +0200
Subject: [PATCH 166/286] fix(ai): text after a thinking block starts a new
 text part

With thinking, text A, thinking, text B, the second text part held AB. A thinking block that starts after text now ends the current text segment.
---
 .../src/activities/chat/stream/processor.ts   | 24 ++++++++
 packages/ai/tests/stream-processor.test.ts    | 56 +++++++++++++++++++
 2 files changed, 80 insertions(+)

diff --git a/packages/ai/src/activities/chat/stream/processor.ts b/packages/ai/src/activities/chat/stream/processor.ts
index 04e72128ea..92015fd37c 100644
--- a/packages/ai/src/activities/chat/stream/processor.ts
+++ b/packages/ai/src/activities/chat/stream/processor.ts
@@ -2394,6 +2394,30 @@ export class StreamProcessor {
     const nextThinking = (state.thinkingSteps.get(stepId) ?? '') + delta
     state.thinkingSteps.set(stepId, nextThinking)
 
+    // A new thinking block after text ends that text segment, so the text
+    // after the block starts its own part ("A", then "B", not "AB"). The part
+    // lookup is the one updateThinkingPart uses: a block that already has a
+    // part (this step, or a hydrated part with no stepId) is updated in
+    // place, and the text segment goes on.
+    // ponytail: only reasoning content ends the segment. A redacted block
+    // that sends only REASONING_ENCRYPTED_VALUE still joins the two texts.
+    if (
+      state.currentSegmentText !== '' &&
+      !this.messages
+        .find((message) => message.id === messageId)
+        ?.parts.some(
+          (part) =>
+            part.type === 'thinking' &&
+            (part.stepId === stepId || part.stepId === undefined),
+        )
+    ) {
+      if (state.currentSegmentText !== state.lastEmittedText) {
+        this.emitTextUpdateForMessage(messageId)
+      }
+      state.currentSegmentText = ''
+      state.lastEmittedText = ''
+    }
+
     this.messages = updateThinkingPart(
       this.messages,
       messageId,
diff --git a/packages/ai/tests/stream-processor.test.ts b/packages/ai/tests/stream-processor.test.ts
index fbd2c65aa6..141a067f20 100644
--- a/packages/ai/tests/stream-processor.test.ts
+++ b/packages/ai/tests/stream-processor.test.ts
@@ -1702,6 +1702,62 @@ describe('StreamProcessor', () => {
       expect((thinkingParts[0] as any).stepId).toBe('step-b')
       expect((thinkingParts[0] as any).content).toBe('contentB')
     })
+
+    it('starts a new text part for text after a second thinking block', () => {
+      const processor = new StreamProcessor()
+      processor.prepareAssistantMessage()
+
+      processor.processChunk(ev.runStarted())
+      processor.processChunk(ev.stepStarted('step-1'))
+      processor.processChunk(ev.reasoningContent('First thought'))
+      processor.processChunk(ev.textStart())
+      processor.processChunk(ev.textContent('A'))
+      processor.processChunk(ev.textEnd())
+      processor.processChunk(ev.stepStarted('step-2'))
+      processor.processChunk(ev.reasoningContent('Second thought'))
+      processor.processChunk(ev.textStart())
+      processor.processChunk(ev.textContent('B'))
+      processor.processChunk(ev.textEnd())
+      processor.processChunk(ev.runFinished('stop'))
+      processor.finalizeStream()
+
+      const parts = processor.getMessages()[0]!.parts
+      expect(
+        parts.map((part) =>
+          part.type === 'text' || part.type === 'thinking'
+            ? `${part.type}:${part.content}`
+            : part.type,
+        ),
+      ).toEqual([
+        'thinking:First thought',
+        'text:A',
+        'thinking:Second thought',
+        'text:B',
+      ])
+      expect(processor.getState().content).toBe('AB')
+    })
+
+    it('keeps one text part when reasoning of the same step arrives between text deltas', () => {
+      const processor = new StreamProcessor()
+      processor.prepareAssistantMessage()
+
+      processor.processChunk(ev.stepStarted('step-1'))
+      processor.processChunk(ev.reasoningContent('Thinking'))
+      processor.processChunk(ev.textStart())
+      processor.processChunk(ev.textContent('A'))
+      processor.processChunk(ev.reasoningContent(' more'))
+      processor.processChunk(ev.textContent('B'))
+      processor.processChunk(ev.textEnd())
+
+      const parts = processor.getMessages()[0]!.parts
+      expect(
+        parts.map((part) =>
+          part.type === 'text' || part.type === 'thinking'
+            ? `${part.type}:${part.content}`
+            : part.type,
+        ),
+      ).toEqual(['thinking:Thinking more', 'text:AB'])
+    })
   })
 
   // ==========================================================================

From 1241689cc84b0b2e3d1a6269e91772425e786ef7 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 13:18:06 +0200
Subject: [PATCH 167/286] fix(ai-anthropic): end each thinking block in the
 stream

A second thinking block got no REASONING_MESSAGE_END or REASONING_END, and a thinking block before a tool call ended only after that call. Each thinking block now ends when it stops.
---
 packages/ai-anthropic/src/adapters/text.ts    |  18 ++
 .../tests/anthropic-adapter.test.ts           | 159 ++++++++++++++++++
 2 files changed, 177 insertions(+)

diff --git a/packages/ai-anthropic/src/adapters/text.ts b/packages/ai-anthropic/src/adapters/text.ts
index 7748b86e54..73fe1fc47a 100644
--- a/packages/ai-anthropic/src/adapters/text.ts
+++ b/packages/ai-anthropic/src/adapters/text.ts
@@ -1222,6 +1222,7 @@ export class AnthropicTextAdapter<
           } else if (event.content_block.type === 'thinking') {
             accumulatedThinking = ''
             accumulatedSignature = ''
+            hasClosedReasoning = false
             // Emit REASONING and STEP_STARTED for thinking
             stepId = genId()
             reasoningMessageId = genId()
@@ -1447,6 +1448,23 @@ export class AnthropicTextAdapter<
                 timestamp: Date.now(),
               }
             }
+            // End this block's reasoning message here, so the next thinking
+            // block gets its own end events.
+            if (reasoningMessageId && !hasClosedReasoning) {
+              hasClosedReasoning = true
+              yield {
+                type: EventType.REASONING_MESSAGE_END,
+                messageId: reasoningMessageId,
+                model,
+                timestamp: Date.now(),
+              }
+              yield {
+                type: EventType.REASONING_END,
+                messageId: reasoningMessageId,
+                model,
+                timestamp: Date.now(),
+              }
+            }
           } else if (currentBlockType === 'tool_use') {
             const existing = toolCallsMap.get(currentToolIndex)
             if (existing) {
diff --git a/packages/ai-anthropic/tests/anthropic-adapter.test.ts b/packages/ai-anthropic/tests/anthropic-adapter.test.ts
index 63fc322ef8..d5a732d749 100644
--- a/packages/ai-anthropic/tests/anthropic-adapter.test.ts
+++ b/packages/ai-anthropic/tests/anthropic-adapter.test.ts
@@ -79,6 +79,92 @@ function createTextStream(text: string) {
   })()
 }
 
+/** The raw events of one signed Anthropic thinking block. */
+function thinkingBlockEvents(
+  index: number,
+  thinking: string,
+  signature: string,
+) {
+  return [
+    {
+      type: 'content_block_start',
+      index,
+      content_block: { type: 'thinking', thinking: '' },
+    },
+    {
+      type: 'content_block_delta',
+      index,
+      delta: { type: 'thinking_delta', thinking },
+    },
+    {
+      type: 'content_block_delta',
+      index,
+      delta: { type: 'signature_delta', signature },
+    },
+    { type: 'content_block_stop', index },
+  ]
+}
+
+/** The raw events of one Anthropic `tool_use` block for `lookup_weather`. */
+function toolUseBlockEvents(index: number, id: string, location: string) {
+  return [
+    {
+      type: 'content_block_start',
+      index,
+      content_block: { type: 'tool_use', id, name: 'lookup_weather' },
+    },
+    {
+      type: 'content_block_delta',
+      index,
+      delta: {
+        type: 'input_json_delta',
+        partial_json: JSON.stringify({ location }),
+      },
+    },
+    { type: 'content_block_stop', index },
+  ]
+}
+
+/** The raw events of one Anthropic text block. */
+function textBlockEvents(index: number, text: string) {
+  return [
+    {
+      type: 'content_block_start',
+      index,
+      content_block: { type: 'text', text: '' },
+    },
+    {
+      type: 'content_block_delta',
+      index,
+      delta: { type: 'text_delta', text },
+    },
+    { type: 'content_block_stop', index },
+  ]
+}
+
+/**
+ * The reasoning events and the block starts of a stream, as labels. A
+ * reasoning message is named by its position among the REASONING_START events.
+ */
+function reasoningLifecycle(chunks: Array<AdapterYieldChunk>) {
+  const ids: Array<string> = []
+  return chunks.flatMap((chunk) => {
+    if (chunk.type === 'REASONING_START') {
+      ids.push(chunk.messageId)
+      return [`reasoning start ${ids.length - 1}`]
+    }
+    if (chunk.type === 'REASONING_MESSAGE_END') {
+      return [`reasoning message end ${ids.indexOf(chunk.messageId)}`]
+    }
+    if (chunk.type === 'REASONING_END') {
+      return [`reasoning end ${ids.indexOf(chunk.messageId)}`]
+    }
+    if (chunk.type === 'TOOL_CALL_START') return [`tool ${chunk.toolCallId}`]
+    if (chunk.type === 'TEXT_MESSAGE_CONTENT') return [`text ${chunk.delta}`]
+    return []
+  })
+}
+
 describe('Anthropic client injection', () => {
   beforeEach(() => {
     vi.clearAllMocks()
@@ -2226,6 +2312,79 @@ describe('Anthropic stream processing', () => {
     expect(toolStart).toBeDefined()
     expect(toolStart?.parentMessageId).toBe(textStart?.messageId)
   })
+
+  it('ends each thinking block before the next tool call starts', async () => {
+    mocks.betaMessagesCreate.mockResolvedValueOnce(
+      (async function* () {
+        yield* thinkingBlockEvents(0, 'Check Berlin first.', 'sig-1')
+        yield* toolUseBlockEvents(1, 'tool_1', 'Berlin')
+        yield* thinkingBlockEvents(2, 'Now Paris.', 'sig-2')
+        yield* toolUseBlockEvents(3, 'tool_2', 'Paris')
+        yield {
+          type: 'message_delta',
+          delta: { stop_reason: 'tool_use' },
+          usage: { output_tokens: 10 },
+        }
+        yield { type: 'message_stop' }
+      })(),
+    )
+
+    const chunks: AdapterYieldChunk[] = []
+    for await (const chunk of chat({
+      adapter: createAdapter('claude-opus-4-1'),
+      messages: [{ role: 'user', content: 'Weather in Berlin and Paris?' }],
+      tools: [weatherTool],
+    })) {
+      chunks.push(chunk)
+    }
+
+    expect(reasoningLifecycle(chunks)).toEqual([
+      'reasoning start 0',
+      'reasoning message end 0',
+      'reasoning end 0',
+      'tool tool_1',
+      'reasoning start 1',
+      'reasoning message end 1',
+      'reasoning end 1',
+      'tool tool_2',
+    ])
+  })
+
+  it('ends each thinking block before the next text starts', async () => {
+    mocks.betaMessagesCreate.mockResolvedValueOnce(
+      (async function* () {
+        yield* thinkingBlockEvents(0, 'First thought.', 'sig-1')
+        yield* textBlockEvents(1, 'A')
+        yield* thinkingBlockEvents(2, 'Second thought.', 'sig-2')
+        yield* textBlockEvents(3, 'B')
+        yield {
+          type: 'message_delta',
+          delta: { stop_reason: 'end_turn' },
+          usage: { output_tokens: 10 },
+        }
+        yield { type: 'message_stop' }
+      })(),
+    )
+
+    const chunks: AdapterYieldChunk[] = []
+    for await (const chunk of chat({
+      adapter: createAdapter('claude-opus-4-1'),
+      messages: [{ role: 'user', content: 'Think twice.' }],
+    })) {
+      chunks.push(chunk)
+    }
+
+    expect(reasoningLifecycle(chunks)).toEqual([
+      'reasoning start 0',
+      'reasoning message end 0',
+      'reasoning end 0',
+      'text A',
+      'reasoning start 1',
+      'reasoning message end 1',
+      'reasoning end 1',
+      'text B',
+    ])
+  })
 })
 
 describe('Anthropic adapter error handling', () => {

From c5beabf87241091e5621bdfbbd267b5fe7b6f259 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 13:18:06 +0200
Subject: [PATCH 168/286] test(ai-skills): cover the skill source and the
 failure paths of the harness plugin

The model loads a skill with load_skill, a resource comes from the folder that has the skill now, a watcher error watches the folder again, an unreadable folder gives no skills, and a failed sync does not stop the next one.
---
 packages/ai-skills/tests/harness.test.ts | 151 ++++++++++++++++++++++-
 1 file changed, 147 insertions(+), 4 deletions(-)

diff --git a/packages/ai-skills/tests/harness.test.ts b/packages/ai-skills/tests/harness.test.ts
index 6c69582f48..0d484cf7f4 100644
--- a/packages/ai-skills/tests/harness.test.ts
+++ b/packages/ai-skills/tests/harness.test.ts
@@ -1,3 +1,4 @@
+import { watch } from 'node:fs'
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -11,8 +12,52 @@ import {
 } from '@tanstack/ai-harness'
 import { skills } from '../src/harness'
 import type { TextOptions } from '@tanstack/ai'
+import type { FakeResponse } from '@tanstack/ai/testing'
 import type { HarnessHost, HarnessPlugin } from '@tanstack/ai-harness'
 import type { SkillsPluginOptions } from '../src/harness'
+import type { SkillSource } from '../src/types'
+
+/** The sources that the plugin gives to `withSkills`, newest last. */
+const seen = vi.hoisted(() => ({ sources: new Array<SkillSource>() }))
+/** Folders whose source fails: `list` rejects, or `open` throws when it is made. */
+const failing = vi.hoisted(() => ({
+  list: new Set<string>(),
+  open: new Set<string>(),
+}))
+
+// Pass-through spies. The tests reach the plugin's watchers, its skill
+// source, and a failing folder through them. Everything else is unchanged.
+vi.mock('node:fs', async (importOriginal) => {
+  const original = await importOriginal<typeof import('node:fs')>()
+  return { ...original, watch: vi.fn(original.watch) }
+})
+vi.mock('../src/middleware', async (importOriginal) => {
+  const original = await importOriginal<typeof import('../src/middleware')>()
+  return {
+    ...original,
+    withSkills: (...args: Parameters<typeof original.withSkills>) => {
+      const [sources] = args
+      if (!Array.isArray(sources)) seen.sources.push(sources)
+      return original.withSkills(...args)
+    },
+  }
+})
+vi.mock('../src/node', async (importOriginal) => {
+  const original = await importOriginal<typeof import('../src/node')>()
+  return {
+    ...original,
+    skillDirectory: (...args: Parameters<typeof original.skillDirectory>) => {
+      const key = String(args[0])
+      if (failing.open.has(key)) throw new Error(`cannot open ${key}`)
+      const source = original.skillDirectory(...args)
+      if (!failing.list.has(key)) return source
+      return {
+        ...source,
+        list: () => Promise.reject(new Error(`cannot read ${key}`)),
+      }
+    },
+  }
+})
 
 const temps: Array<string> = []
 const hosts: Array<HarnessHost> = []
@@ -21,6 +66,10 @@ afterEach(async () => {
   await Promise.all(
     temps.splice(0).map((dir) => rm(dir, { recursive: true, force: true })),
   )
+  seen.sources.length = 0
+  failing.list.clear()
+  failing.open.clear()
+  vi.mocked(watch).mockClear()
 })
 
 async function tempDir() {
@@ -38,23 +87,38 @@ async function addSkill(root: string, name: string, about = name) {
   )
 }
 
+/** Write `references/guide.md` with `text` into the skill `name` of `root`. */
+async function addGuide(root: string, name: string, text: string) {
+  await mkdir(join(root, name, 'references'), { recursive: true })
+  await writeFile(join(root, name, 'references', 'guide.md'), text)
+}
+
+/** The watchers made for `path`, oldest first. */
+function watchersOf(path: string) {
+  const spy = vi.mocked(watch)
+  return spy.mock.results.filter(
+    (_, index) => spy.mock.calls[index]?.[0] === path,
+  )
+}
+
 /**
- * A session with the skills plugin and `others` after it. The model answers
- * "ok" and keeps each request.
+ * A session with the skills plugin and `others` after it. The model gives
+ * `answers` in order, then "ok", and keeps each request.
  */
 async function open(
   options: SkillsPluginOptions,
   others: Array<HarnessPlugin> = [],
+  answers: Array<FakeResponse> = [],
 ) {
   const requests: Array<TextOptions> = []
   const fake = fakeText()
   fake.setResponses(
     Array.from(
       { length: 10 },
-      () =>
+      (_, index) =>
         ({ request }: { request: TextOptions }) => {
           requests.push(request)
-          return { text: 'ok' }
+          return answers[index] ?? { text: 'ok' }
         },
     ),
   )
@@ -234,4 +298,83 @@ describe('skills()', () => {
     await new Promise((resolve) => setTimeout(resolve, 500))
     expect(opened.names()).not.toContain('gamma')
   })
+
+  it('loads a skill from its folder when the model calls load_skill', async () => {
+    const dir = await tempDir()
+    await addSkill(dir, 'alpha')
+    await addGuide(dir, 'alpha', 'guide')
+    await mkdir(join(dir, 'alpha', 'scripts'))
+    await writeFile(join(dir, 'alpha', 'scripts', 'run.sh'), 'echo hi')
+    const { session, requests } = await open(
+      { dirs: [dir] },
+      [],
+      [{ toolCalls: [{ name: 'load_skill', input: { name: 'alpha' } }] }],
+    )
+
+    await session.prompt('use alpha')
+    await vi.waitFor(() => expect(requests).toHaveLength(2))
+    const sent = JSON.stringify(requests[1]?.messages)
+    expect(sent).toContain('Do alpha.')
+    expect(sent).toContain('references/guide.md')
+    expect(sent).toContain('scripts/run.sh')
+  })
+
+  it('reads a resource from the folder that has the skill now', async () => {
+    const first = await tempDir()
+    const second = await tempDir()
+    await addSkill(second, 'alpha')
+    await addGuide(second, 'alpha', 'second guide')
+    await open({ dirs: [first, second] })
+    const source = seen.sources.at(-1)
+    const read = (name: string) =>
+      source?.readResource?.(name, 'references/guide.md')
+
+    expect(await read('alpha')).toBe('second guide')
+    // The first folder wins a name, also for a skill made after the start.
+    await addSkill(first, 'alpha')
+    await addGuide(first, 'alpha', 'first guide')
+    expect(await read('alpha')).toBe('first guide')
+    await expect(read('missing')).rejects.toThrow('No skill named "missing"')
+  })
+
+  it('watches a folder again after a watch error', async () => {
+    const dir = await tempDir()
+    await addSkill(dir, 'alpha')
+    const { names, list } = await open({ dirs: [dir] })
+    await list()
+    expect(watchersOf(dir)).toHaveLength(1)
+
+    watchersOf(dir)[0]?.value.emit('error', new Error('watch failed'))
+    await list()
+    expect(watchersOf(dir)).toHaveLength(2)
+    await addSkill(dir, 'gamma')
+    await vi.waitFor(() => expect(names()).toContain('gamma'), {
+      timeout: 5000,
+    })
+  })
+
+  it('skips a folder whose skills cannot be read', async () => {
+    const broken = await tempDir()
+    const dir = await tempDir()
+    await addSkill(broken, 'beta')
+    await addSkill(dir, 'alpha')
+    failing.list.add(broken)
+    const { names, list } = await open({ dirs: [broken, dir] })
+
+    expect(await list()).toContain(`/alpha  ${dir}`)
+    expect(names()).toContain('alpha')
+    expect(names()).not.toContain('beta')
+  })
+
+  it('syncs again after a sync that failed', async () => {
+    const dir = await tempDir()
+    await addSkill(dir, 'alpha')
+    failing.open.add(dir)
+    const { names, list } = await open({ dirs: [dir] })
+
+    expect(await list()).toContain('No skills yet.')
+    failing.open.delete(dir)
+    await list()
+    expect(names()).toContain('alpha')
+  })
 })

From 0bd0739c61adab2ac96a9e8a78e6df001e3e0e44 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 14:07:21 +0200
Subject: [PATCH 169/286] feat(ai): chat() writes blockOrder on assistant
 messages

Each assistant message that chat() builds from one model call carries blockOrder when its blocks leave the default order. The split at thinking after a provider-executed call stays, and each segment gets its own map.
---
 packages/ai/src/activities/chat/index.ts   |  65 ++++++-
 packages/ai/tests/chat-block-order.test.ts | 202 +++++++++++++++++++++
 2 files changed, 264 insertions(+), 3 deletions(-)
 create mode 100644 packages/ai/tests/chat-block-order.test.ts

diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index c57d5f738c..2d1a920a71 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -51,6 +51,8 @@ import {
   toolResultErrorText,
 } from '../../utilities/tool-result'
 import { isProviderExecutedToolCall } from '../../utilities/provider-executed'
+import { buildBlockOrder } from '../../utilities/block-order'
+import type { BlockOrderEntry } from '../../utilities/block-order'
 import { assertMessagesFileSourceSupport } from '../../utilities/content-source'
 import { LazyToolManager } from './tools/lazy-tool-manager'
 import { assertUniqueToolNames } from './tools/unique-tool-names'
@@ -136,6 +138,7 @@ import type {
   JSONSchema,
   LazyToolsConfig,
   ModelMessage,
+  ModelMessageBlock,
   PromptCacheOptions,
   ProviderTool,
   ResolvedPromptCache,
@@ -192,6 +195,25 @@ type TurnPart =
   | { type: 'text'; content: string }
   | { type: 'call'; id: string; providerExecuted: boolean }
 
+/**
+ * The order map for one assistant message built from `parts`. Calls that are
+ * not in `toolCalls` are left out, because the message does not carry them.
+ * Calls that the stream did not report go last, their default place.
+ */
+function turnBlockOrder(
+  parts: ReadonlyArray<TurnPart>,
+  toolCalls: ReadonlyArray<ToolCall>,
+): Array<ModelMessageBlock> | undefined {
+  const unplaced = new Set(toolCalls.map((toolCall) => toolCall.id))
+  const entries = parts.flatMap((part): Array<BlockOrderEntry> => {
+    if (part.type === 'thinking') return [{ type: 'thinking' }]
+    if (part.type === 'text') return [{ type: 'text', text: part.content }]
+    return unplaced.delete(part.id) ? [{ type: 'tool-call', id: part.id }] : []
+  })
+  for (const id of unplaced) entries.push({ type: 'tool-call', id })
+  return buildBlockOrder(entries)
+}
+
 // ===========================
 // Activity Kind
 // ===========================
@@ -2612,7 +2634,8 @@ class TextEngine<
    * Split this iteration into assistant ModelMessages that keep the provider's
    * block order: a new segment starts at every thinking step that follows a
    * provider-executed tool call (the rule buildAssistantMessages applies to
-   * UIMessages). Segments after the first get `${id}-segment-${n}` ids.
+   * UIMessages). Segments after the first get `${id}-segment-${n}` ids. A
+   * segment whose own blocks leave the default order gets a `blockOrder` map.
    * Returns null when no split is needed or the order could not be tracked,
    * so callers fall back to the single-message shape.
    */
@@ -2632,8 +2655,9 @@ class TextEngine<
       thinking: NonNullable<ModelMessage['thinking']>
       text: string
       callIds: Array<string>
+      parts: Array<TurnPart>
     }
-    let current: Segment = { thinking: [], text: '', callIds: [] }
+    let current: Segment = { thinking: [], text: '', callIds: [], parts: [] }
     const segments: Array<Segment> = [current]
     let split = false
     for (const part of parts) {
@@ -2641,7 +2665,7 @@ class TextEngine<
         const thinking = this.accumulatedThinking[part.index]
         if (!thinking) return null
         if (current.callIds.some((callId) => providerCallIds.has(callId))) {
-          current = { thinking: [thinking], text: '', callIds: [] }
+          current = { thinking: [thinking], text: '', callIds: [], parts: [] }
           segments.push(current)
           split = true
         } else {
@@ -2652,6 +2676,7 @@ class TextEngine<
       } else {
         current.callIds.push(part.id)
       }
+      current.parts.push(part)
     }
     if (!split) return null
     if (
@@ -2674,6 +2699,7 @@ class TextEngine<
       const segmentCalls = toolCalls.filter((toolCall) =>
         segment.callIds.includes(toolCall.id),
       )
+      const blockOrder = turnBlockOrder(segment.parts, segmentCalls)
       return {
         role: 'assistant',
         content: segment.text || null,
@@ -2686,10 +2712,40 @@ class TextEngine<
               : `${id}-segment-${index}`,
         createdAt,
         ...(segment.thinking.length > 0 && { thinking: segment.thinking }),
+        ...(blockOrder && { blockOrder }),
       }
     })
   }
 
+  /**
+   * `{ blockOrder }` for this iteration kept as one assistant message that
+   * carries `toolCalls`, or `{}` when the order is the default one or was not
+   * tracked. This is the fallback when `buildOrderedAssistantSegments` does
+   * not split, so it is the common client-tool case.
+   */
+  private singleMessageBlockOrder(toolCalls: ReadonlyArray<ToolCall>): {
+    blockOrder?: Array<ModelMessageBlock>
+  } {
+    const parts = this.turnParts
+    if (!parts) return {}
+    const thinking = parts.filter(
+      (part): part is Extract<TurnPart, { type: 'thinking' }> =>
+        part.type === 'thinking',
+    )
+    const text = parts
+      .map((part) => (part.type === 'text' ? part.content : ''))
+      .join('')
+    if (
+      text !== this.accumulatedContent ||
+      thinking.length !== this.accumulatedThinking.length ||
+      thinking.some((part, index) => part.index !== index)
+    ) {
+      return {}
+    }
+    const blockOrder = turnBlockOrder(parts, toolCalls)
+    return blockOrder ? { blockOrder } : {}
+  }
+
   private addAssistantToolCallMessage(toolCalls: Array<ToolCall>): void {
     this.finalizeCurrentThinkingStep()
 
@@ -2710,6 +2766,7 @@ class TextEngine<
           ...(this.accumulatedThinking.length > 0 && {
             thinking: this.accumulatedThinking,
           }),
+          ...this.singleMessageBlockOrder(toolCalls),
         },
       ]),
     ]
@@ -2804,6 +2861,8 @@ class TextEngine<
               id,
               createdAt,
               ...(thinking ? { thinking } : {}),
+              // This message carries no tool calls, so its map has none.
+              ...this.singleMessageBlockOrder([]),
             },
           ]),
         )
diff --git a/packages/ai/tests/chat-block-order.test.ts b/packages/ai/tests/chat-block-order.test.ts
new file mode 100644
index 0000000000..6ad3279029
--- /dev/null
+++ b/packages/ai/tests/chat-block-order.test.ts
@@ -0,0 +1,202 @@
+import { describe, expect, it } from 'vitest'
+import { chat } from '../src/activities/chat'
+import { EventType } from '../src/types'
+import {
+  chunk,
+  clientTool,
+  collectChunks,
+  createMockAdapter,
+  ev,
+  serverTool,
+} from './test-utils'
+import type { ChatMiddleware } from '../src/activities/chat/middleware/types'
+import type { AdapterYieldChunk } from '../src/utilities/adapter-yield-chunk'
+import type { ModelMessage, StreamChunk, Tool } from '../src/types'
+
+/** One signed thinking block, the way Anthropic streams it. */
+function reasoning(stepName: string, content: string, signature: string) {
+  return [
+    ev.stepStarted(stepName),
+    chunk(EventType.REASONING_MESSAGE_CONTENT, {
+      messageId: `${stepName}-reasoning`,
+      delta: content,
+    }),
+    { ...ev.stepFinished('', stepName), signature },
+  ]
+}
+
+function callTool(toolCallId: string, name: string) {
+  return [
+    ev.toolStart(toolCallId, name),
+    ev.toolArgs(toolCallId, '{}'),
+    ev.toolEnd(toolCallId),
+  ]
+}
+
+function text(content: string) {
+  return [ev.textStart(), ev.textContent(content), ev.textEnd()]
+}
+
+/** The history that the adapter gets on its second call. */
+async function historyAfter(
+  turn: Array<AdapterYieldChunk>,
+): Promise<Array<ModelMessage>> {
+  const { adapter, calls } = createMockAdapter({
+    iterations: [
+      turn,
+      [ev.runStarted(), ...text('Done.'), ev.runFinished('stop')],
+    ],
+  })
+  await collectChunks(
+    chat({
+      adapter,
+      messages: [{ role: 'user', content: 'Go' }],
+      tools: [serverTool('lookup', () => ({ found: true }))],
+    }) as AsyncIterable<StreamChunk>,
+  )
+  expect(calls).toHaveLength(2)
+  return calls[1]!.messages
+}
+
+/** The messages that chat() holds when the run ends. */
+async function messagesAtFinish(
+  turn: Array<AdapterYieldChunk>,
+  tools: Array<Tool> = [],
+): Promise<ReadonlyArray<ModelMessage>> {
+  let messages: ReadonlyArray<ModelMessage> = []
+  const capture: ChatMiddleware = {
+    name: 'capture',
+    onFinish: (ctx) => {
+      messages = ctx.messages
+    },
+  }
+  const { adapter } = createMockAdapter({ iterations: [turn] })
+  await collectChunks(
+    chat({
+      adapter,
+      messages: [{ role: 'user', content: 'Go' }],
+      tools,
+      middleware: [capture],
+    }) as AsyncIterable<StreamChunk>,
+  )
+  return messages
+}
+
+const interleavedCalls = [
+  { type: 'thinking', index: 0 },
+  { type: 'tool-call', id: 'call_1' },
+  { type: 'thinking', index: 1 },
+  { type: 'tool-call', id: 'call_2' },
+]
+
+describe('chat() block order', () => {
+  it('writes the map for a client-tool answer: thinking, tool, thinking, tool', async () => {
+    const messages = await messagesAtFinish(
+      [
+        ev.runStarted(),
+        ...reasoning('step-1', 'plan', 'sig-a'),
+        ...callTool('call_1', 'pick'),
+        ...reasoning('step-2', 'next', 'sig-b'),
+        ...callTool('call_2', 'pick'),
+        ev.runFinished('tool_calls'),
+      ],
+      [clientTool('pick')],
+    )
+
+    expect(
+      messages.filter((message) => message.role === 'assistant'),
+    ).toMatchObject([
+      {
+        content: null,
+        thinking: [
+          { content: 'plan', signature: 'sig-a' },
+          { content: 'next', signature: 'sig-b' },
+        ],
+        toolCalls: [{ id: 'call_1' }, { id: 'call_2' }],
+        blockOrder: interleavedCalls,
+      },
+    ])
+  })
+
+  it('sends the map to the adapter on the next call', async () => {
+    const history = await historyAfter([
+      ev.runStarted(),
+      ...reasoning('step-1', 'plan', 'sig-a'),
+      ...callTool('call_1', 'lookup'),
+      ...reasoning('step-2', 'next', 'sig-b'),
+      ...callTool('call_2', 'lookup'),
+      ev.runFinished('tool_calls'),
+    ])
+
+    expect(
+      history
+        .filter((message) => message.role === 'assistant')
+        .map((message) => message.blockOrder),
+    ).toEqual([interleavedCalls])
+  })
+
+  it('writes no map for an answer in the default order', async () => {
+    const history = await historyAfter([
+      ev.runStarted(),
+      ...reasoning('step-1', 'plan', 'sig-a'),
+      ...text('Checking.'),
+      ...callTool('call_1', 'lookup'),
+      ev.runFinished('tool_calls'),
+    ])
+
+    const assistant = history.find((message) => message.role === 'assistant')
+    expect(assistant?.content).toBe('Checking.')
+    expect(assistant).not.toHaveProperty('blockOrder')
+  })
+
+  it('keeps the split at thinking after a provider tool and maps inside the segment', async () => {
+    const history = await historyAfter([
+      ev.runStarted(),
+      ...reasoning('step-1', 'plan', 'sig-a'),
+      {
+        ...ev.toolStart('srvtoolu_1', 'web_search'),
+        metadata: { providerExecuted: true },
+      },
+      ev.toolEnd('srvtoolu_1'),
+      ...reasoning('step-2', 'refine', 'sig-b'),
+      ...callTool('call_1', 'lookup'),
+      ...reasoning('step-3', 'more', 'sig-c'),
+      ...callTool('call_2', 'lookup'),
+      ev.runFinished('tool_calls'),
+    ])
+
+    const assistants = history.filter((message) => message.role === 'assistant')
+    expect(
+      assistants.map((message) => ({
+        toolCalls: message.toolCalls?.map((toolCall) => toolCall.id),
+        blockOrder: message.blockOrder,
+      })),
+    ).toEqual([
+      { toolCalls: ['srvtoolu_1'], blockOrder: undefined },
+      { toolCalls: ['call_1', 'call_2'], blockOrder: interleavedCalls },
+    ])
+    expect(assistants[1]?.id).toBe(`${assistants[0]?.id}-segment-1`)
+  })
+
+  it('writes the map on a final answer: thinking, text, thinking, text', async () => {
+    const messages = await messagesAtFinish([
+      ev.runStarted(),
+      ...reasoning('step-1', 'plan', 'sig-a'),
+      ...text('A'),
+      ...reasoning('step-2', 'check', 'sig-b'),
+      ...text('B'),
+      ev.runFinished('stop'),
+    ])
+
+    expect(messages.at(-1)).toMatchObject({
+      role: 'assistant',
+      content: 'AB',
+      blockOrder: [
+        { type: 'thinking', index: 0 },
+        { type: 'text', length: 1 },
+        { type: 'thinking', index: 1 },
+        { type: 'text', length: 1 },
+      ],
+    })
+  })
+})

From 5cc000e22fbf3035f1505ed256c8efda83f040c2 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 14:08:23 +0200
Subject: [PATCH 170/286] fix(ai-harness): run turn hooks in a handoff, and
 resume a subagents.router child

Two bugs in routed turns:

- With `routing.strategy: 'handoff'`, the main model ran without the turn
  hooks. A 503 failed the turn instead of reaching `turn.onModelError`, and
  `turn.beforeFinish` never ran. The hooks are now off only while the root
  agents run.
- A `subagents.router` child that stopped for an interrupt could not resume:
  `resolve` failed with "Tool x is unavailable" (or "unknown interrupt" on a
  durable host), because the stored thread has no card for the child. The
  harness now keeps the cards of every routed run, as it did for root
  routing, and a resolve rebuilds the root bag only for a root-routed turn.
---
 .changeset/harness-routing.md                 |  2 +-
 packages/ai-harness/src/session.ts            | 42 ++++-----
 packages/ai-harness/tests/routing.test.ts     | 64 +++++++++++++
 .../ai-harness/tests/subagent-router.test.ts  | 91 +++++++++++++++++-
 testing/e2e/fixtures/harness/basic.json       | 42 +++++++++
 testing/e2e/src/routes/api.harness-test.ts    | 94 ++++++++++++++++++-
 testing/e2e/tests/harness.spec.ts             | 16 ++++
 7 files changed, 323 insertions(+), 28 deletions(-)

diff --git a/.changeset/harness-routing.md b/.changeset/harness-routing.md
index 558b7c30ed..768942ad57 100644
--- a/.changeset/harness-routing.md
+++ b/.changeset/harness-routing.md
@@ -5,4 +5,4 @@
 
 `@tanstack/ai`: a router pick can give an agent its input. Anywhere a pick has a name, it can have `{ name, input }`, so `subagents.router` can start an agent with `inputSchema`. `chat()` checks the input against the schema, and `run` reads it as `ctx.input`. A resume keeps each input of the plan. `subagentRoute` gets `needsInput(result)`, which lists the picked agents with an `inputSchema`, and `pick(result, { inputs })`, which puts each input on its name. `inputs` is typed from each schema.
 
-`@tanstack/ai-harness`: `defineHarness` takes `routing: { router, order, strategy, limits, sandbox }`. The router runs at the start of each new turn. It sends the turn to the main model, or to root agents: the harness `agents` and the `agents` of plugins. Its context has the fields of the `subagents.router` context, plus `session`, `input`, `operationId`, `inputId`, and `adapter`. With `strategy: 'handoff'`, the main model answers after the agents, in the same turn. A resolve continues the routed plan without a new router call. A routed turn holds a run lease, and its text is the text of the agents. A `subagents.router` turn gets the same lease and text. `HarnessRouting` and `HarnessRouterContext` are exported.
+`@tanstack/ai-harness`: `defineHarness` takes `routing: { router, order, strategy, limits, sandbox }`. The router runs at the start of each new turn. It sends the turn to the main model, or to root agents: the harness `agents` and the `agents` of plugins. Its context has the fields of the `subagents.router` context, plus `session`, `input`, `operationId`, `inputId`, and `adapter`. With `strategy: 'handoff'`, the main model answers after the agents, in the same turn, and the `turn` hooks run for it. A resolve continues the routed plan without a new router call. A routed turn holds a run lease, and its text is the text of the agents. A `subagents.router` turn gets the same lease and text, and a child that stops for an interrupt resumes on `resolve`. `HarnessRouting` and `HarnessRouterContext` are exported.
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index e3ab719933..a30d52e64a 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -253,10 +253,11 @@ interface QueuedTurn {
   parentRunId?: string
   inputId?: string
   /**
-   * A resolve of a turn that `routing` sent to root agents: the messages it
-   * continues from, with the agents' cards.
+   * A resolve of a routed turn: the messages it continues from, with the
+   * agents' cards. `root` is true when `routing` sent the turn to root
+   * agents, and false for `subagents.router`.
    */
-  routed?: { messages: Array<UIMessage> }
+  routed?: { messages: Array<UIMessage>; root: boolean }
 }
 
 /** Limits for a harness's children when `subagents.limits` is not set. */
@@ -445,8 +446,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   private readonly pendingNotes: Array<string> = []
   private activeTurn: OperationImpl<ChatTurnResult> | undefined
   /**
-   * The last turn stopped for these interrupts. `routed`: the root agents of
-   * a routed turn stopped. The resolve continues their saved plan.
+   * The last turn stopped for these interrupts. `routed`: a routed turn
+   * stopped. The resolve continues its saved plan.
    */
   private interrupted:
     | {
@@ -1953,7 +1954,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     let stopRunLease = () => {}
     /** The next chat() call runs the root agents that `routing` picked. */
     let isRootPart = false
-    /** The messages of the root part, with the agents' cards. */
+    /** The messages of the last run, with the agents' cards, when it was routed. */
     let cardMessages: Array<UIMessage> | undefined
     let text = ''
     let interrupts: Array<Interrupt> | undefined
@@ -2075,7 +2076,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         })
       }
       const isRootTurn =
-        turn.routed !== undefined || (pick ?? 'main') !== 'main'
+        turn.routed?.root === true || (pick ?? 'main') !== 'main'
       const rootBag =
         routing && isRootTurn
           ? {
@@ -2112,10 +2113,6 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           this.lease,
         )
       }
-      // ponytail: a routed turn runs no turn hooks (no retry, no joins, no
-      // beforeFinish), also in the main part of a handoff. A steer waits and
-      // runs as its own turn. Give the handoff part the hooks if apps need them.
-      const turnHooks = rootBag ? undefined : this.harness.turn
       /** The messages a resolve of a routed turn continues from. */
       let routedFrom = turn.routed?.messages
       /** Retries since the last finished tool phase. */
@@ -2127,6 +2124,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       // runs again when `turn.onModelError` answers 'retry'. A final answer
       // runs again when `turn.beforeFinish` adds to the transcript.
       for (;;) {
+        // The root agents of a routed turn run no turn hooks. The main model
+        // runs them, also in the main part of a handoff.
+        const turnHooks = isRootPart ? undefined : this.harness.turn
         let textBefore = text
         let runError: { message: string; code?: string } | undefined
         let heldError: StreamChunk | undefined
@@ -2140,8 +2140,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           const turnMessages = [...history, ...(message ? [message] : [])]
           // The store keeps each agent in its own thread, and chat() finds a
           // stopped agent in the cards that a client sends back. So the
-          // harness keeps the cards of the root part, as a client does.
-          const cards = isRootPart
+          // harness keeps the cards of a routed run, as a client does.
+          const cards = routed
             ? new StreamProcessor({
                 initialMessages:
                   routedFrom ?? modelMessagesToUIMessages(turnMessages),
@@ -2311,18 +2311,18 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           (interrupts?.length ?? 0) > 0 ||
           signal.aborted
         if (isFinished) break
-        if (rootBag) {
-          const isHandoff = isRootPart && routing?.strategy === 'handoff'
-          if (!isHandoff) break
+        if (isRootPart) {
+          if (routing?.strategy !== 'handoff') break
           // The agents answered. The main model answers next, with the
           // transcript that has their answer.
           isRootPart = false
           bag = subagents
           routed = isRoutedBag(bag)
         } else {
-          // Claimed, so a cancel after this check cannot leave a run with no
-          // new input.
-          const hasLateJoin = (await this.claimJoins()) > 0
+          // A steer does not join a turn that `routing` sent to root agents.
+          // It waits and runs as its own turn. Claimed, so a cancel after
+          // this check cannot leave a run with no new input.
+          const hasLateJoin = !rootBag && (await this.claimJoins()) > 0
           if (!hasLateJoin) {
             if (
               !(await this.continueBeforeFinish(operation, turn.inputId, cycle))
@@ -2425,8 +2425,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       this.interrupted = {
         runId: operation.id,
         interrupts,
-        ...(isRootPart && cardMessages
-          ? { routed: { messages: cardMessages } }
+        ...(cardMessages
+          ? { routed: { messages: cardMessages, root: isRootPart } }
           : {}),
       }
       await settleTurn({ outcome: 'interrupted' })
diff --git a/packages/ai-harness/tests/routing.test.ts b/packages/ai-harness/tests/routing.test.ts
index 41fab4eead..7958a8e709 100644
--- a/packages/ai-harness/tests/routing.test.ts
+++ b/packages/ai-harness/tests/routing.test.ts
@@ -66,6 +66,19 @@ function cleaner() {
   return { make, execute }
 }
 
+/** A model call that fails with `message`, like a provider error. */
+const failsWith =
+  (message: string): Reply =>
+  () => [
+    {
+      type: EventType.RUN_STARTED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: Date.now(),
+    },
+    { type: EventType.RUN_ERROR, message, timestamp: Date.now() },
+  ]
+
 /** A router that answers `picks` in order, and keeps the context of each call. */
 function scriptedRouter(...picks: Array<SubagentRouterPick>) {
   const seen: Array<HarnessRouterContext> = []
@@ -326,6 +339,57 @@ describe('routing.router', () => {
     await host.close()
   })
 
+  it('retries a model error in the main part of a handoff with turn.onModelError', async () => {
+    const writer = textAgent('writer', 'Draft')
+    const onModelError = vi.fn(
+      ({ retries }: { retries: number }): 'retry' | undefined =>
+        retries === 0 ? 'retry' : undefined,
+    )
+    const { host, session, main } = await openRouting({
+      router: () => 'writer',
+      strategy: 'handoff',
+      agents: [writer.agent],
+      turn: { onModelError },
+      replies: [
+        failsWith('503 Service Unavailable'),
+        () => text('Edited draft'),
+      ],
+    })
+
+    const turn = await session.prompt('write it')
+
+    expect(turn.text).toBe('Edited draft')
+    expect(onModelError).toHaveBeenCalledTimes(1)
+    expect(main.calls).toHaveLength(2)
+    // The agents ran once. The retry runs the main model only.
+    expect(writer.runs).toHaveLength(1)
+    await host.close()
+  })
+
+  it('runs turn.beforeFinish in the main part of a handoff', async () => {
+    const writer = textAgent('writer', 'Draft')
+    const beforeFinish = vi.fn(({ cycle }: { cycle: number }) =>
+      cycle === 0
+        ? { messages: [{ role: 'user' as const, content: 'one more' }] }
+        : undefined,
+    )
+    const { host, session, main } = await openRouting({
+      router: () => 'writer',
+      strategy: 'handoff',
+      agents: [writer.agent],
+      turn: { beforeFinish },
+      replies: [() => text('Edited draft'), () => text('Edited again')],
+    })
+
+    await session.prompt('write it')
+
+    expect(beforeFinish).toHaveBeenCalledTimes(2)
+    expect(main.calls).toHaveLength(2)
+    expect(messageTexts(main.calls[1]).at(-1)).toBe('one more')
+    expect(writer.runs).toHaveLength(1)
+    await host.close()
+  })
+
   it.each([
     { strategy: 'exclusive', text: 'writer:\nDraft 1' },
     { strategy: 'handoff', text: 'Main 1' },
diff --git a/packages/ai-harness/tests/subagent-router.test.ts b/packages/ai-harness/tests/subagent-router.test.ts
index 116b472e38..44528c085a 100644
--- a/packages/ai-harness/tests/subagent-router.test.ts
+++ b/packages/ai-harness/tests/subagent-router.test.ts
@@ -1,10 +1,11 @@
-import { describe, expect, it } from 'vitest'
-import { defineAgent } from '@tanstack/ai'
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { defineAgent, toolDefinition } from '@tanstack/ai'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness } from '../src'
-import { gate, messageTexts, mockAdapter, text } from './helpers'
-import type { SubagentRouterPick } from '@tanstack/ai'
-import type { AnyAgent } from '../src'
+import { gate, messageTexts, mockAdapter, text, toolCall } from './helpers'
+import type { AnyTool, SubagentRouterPick } from '@tanstack/ai'
+import type { AnyAgent, HarnessSession } from '../src'
 import type { Reply } from './helpers'
 
 const THREAD = 't1'
@@ -23,6 +24,33 @@ function writerAgent() {
   return { agent, seen }
 }
 
+/** A tool that asks approval before it removes a file. */
+function removeTool() {
+  const execute = vi.fn(async () => ({ removed: true }))
+  const tool = toolDefinition({
+    name: 'remove',
+    description: 'Remove a file',
+    needsApproval: true,
+    inputSchema: z.object({ path: z.string() }),
+  }).server(execute)
+  return { tool, execute }
+}
+
+/** Approve the first interrupt of `turn`, and wait for the turn that resumes. */
+async function approveFirst(
+  session: HarnessSession,
+  turn: { interrupts?: Array<{ id: string }> },
+) {
+  const interrupt = turn.interrupts?.[0]
+  if (!interrupt) throw new Error('The turn has no interrupt.')
+  const receipt = await session.resolve([
+    { interruptId: interrupt.id, status: 'resolved', payload: true },
+  ])
+  const resumed = session.operation(receipt.operationId ?? '')
+  if (!resumed) throw new Error('The resolve started no turn.')
+  return resumed
+}
+
 /**
  * A session whose `subagents.router` always returns `pick`. The router keeps
  * the messages of each call. `durable` gives the host a log.
@@ -33,6 +61,7 @@ async function openRouted(options: {
   pick: SubagentRouterPick
   replies?: Array<Reply>
   lease?: { renewMs?: number; ttlMs?: number }
+  tools?: ReadonlyArray<AnyTool>
 }) {
   const { stores } = memoryPersistence()
   const { runs, metadata } = stores
@@ -49,6 +78,7 @@ async function openRouted(options: {
     defineHarness({
       name: 'test/router',
       adapter: main.adapter,
+      ...(options.tools ? { tools: options.tools } : {}),
       subagents: {
         agents: [options.agent],
         router: ({ messages }) => {
@@ -174,4 +204,55 @@ describe.each([
     expect((await runs.get(turn.id))?.leaseExpiresAt).toBe(ended)
     await host.close()
   })
+
+  it('resumes a routed agent that stopped for an approval', async () => {
+    const remove = removeTool()
+    const child = mockAdapter([
+      () => toolCall('remove', { path: 'a.txt' }, 'call_c'),
+      () => text('Removed a.txt'),
+    ])
+    const agent = defineAgent({
+      name: 'cleaner',
+      description: 'Removes files',
+      run: (ctx) => ctx.chat({ adapter: child.adapter, tools: [remove.tool] }),
+    })
+    const { host, session, routerSaw, calls } = await openRouted({
+      durable,
+      agent,
+      pick: 'cleaner',
+    })
+
+    const turn = await session.prompt('clean up')
+    expect(remove.execute).not.toHaveBeenCalled()
+    const resumed = await approveFirst(session, turn)
+
+    expect(await resumed).toEqual({ text: 'cleaner:\nRemoved a.txt' })
+    expect(remove.execute).toHaveBeenCalledTimes(1)
+    expect(routerSaw).toHaveLength(1)
+    expect(calls).toHaveLength(0)
+    await host.close()
+  })
+
+  it("resumes the main model's approval when the router returns 'main'", async () => {
+    const remove = removeTool()
+    const { agent } = writerAgent()
+    const { host, session, calls } = await openRouted({
+      durable,
+      agent,
+      pick: 'main',
+      tools: [remove.tool],
+      replies: [
+        () => toolCall('remove', { path: 'b.txt' }, 'call_m'),
+        () => text('Removed b.txt'),
+      ],
+    })
+
+    const turn = await session.prompt('clean up')
+    const resumed = await approveFirst(session, turn)
+
+    expect(await resumed).toEqual({ text: 'Removed b.txt' })
+    expect(remove.execute).toHaveBeenCalledTimes(1)
+    expect(calls).toHaveLength(2)
+    await host.close()
+  })
 })
diff --git a/testing/e2e/fixtures/harness/basic.json b/testing/e2e/fixtures/harness/basic.json
index 7f3a063c26..63c7fe395e 100644
--- a/testing/e2e/fixtures/harness/basic.json
+++ b/testing/e2e/fixtures/harness/basic.json
@@ -88,6 +88,48 @@
         "content": "Acme costs 30 dollars."
       }
     },
+    {
+      "match": {
+        "userMessage": "[harness-routing-fix] edit the draft",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "error": { "message": "Service Unavailable", "type": "server_error" },
+        "status": 503
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-routing-fix] edit the draft",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Edited after a retry."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-routing-fix] clean up",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "remove",
+            "arguments": "{\"path\":\"a.txt\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-routing-fix] clean up",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Removed a.txt."
+      }
+    },
     {
       "match": {
         "userMessage": "[harness-protocol] hello"
diff --git a/testing/e2e/src/routes/api.harness-test.ts b/testing/e2e/src/routes/api.harness-test.ts
index 5759a8851d..08a14f0e88 100644
--- a/testing/e2e/src/routes/api.harness-test.ts
+++ b/testing/e2e/src/routes/api.harness-test.ts
@@ -1,11 +1,13 @@
 import { createFileRoute } from '@tanstack/react-router'
-import { chat, defineAgent } from '@tanstack/ai'
+import { chat, defineAgent, toolDefinition } from '@tanstack/ai'
 import {
   HARNESS_EVENTS,
   createHarnessHost,
   defineHarness,
   harnessText,
+  retryTransientErrors,
 } from '@tanstack/ai-harness'
+import { createOpenaiChat } from '@tanstack/ai-openai'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { z } from 'zod'
 import type { ModelMessage, UIMessage } from '@tanstack/ai'
@@ -96,6 +98,88 @@ async function routingTurns(
   return { texts }
 }
 
+/** The `text` of a finished turn, or '' when the value has none. */
+function turnText(value: unknown) {
+  return typeof value === 'object' &&
+    value !== null &&
+    'text' in value &&
+    typeof value.text === 'string'
+    ? value.text
+    : ''
+}
+
+/**
+ * Two routed turns that need a second model call. In a handoff, the main
+ * model fails once with a 503, and `retryTransientErrors` runs it again. A
+ * `subagents.router` child asks approval, and the resolve continues it.
+ * Returns the text of both turns and how many times the tool ran.
+ */
+async function routingResumes(
+  host: HarnessHost,
+  openai: () => ReturnType<typeof createTextAdapter>['adapter'],
+  aimock: { port?: number; testId?: string },
+) {
+  // The harness must see the 503, so the SDK does not retry it.
+  const noSdkRetry = createOpenaiChat('gpt-4o', 'sk-e2e-test-dummy-key', {
+    baseURL: `http://127.0.0.1:${aimock.port ?? 4010}/v1`,
+    ...(aimock.testId
+      ? { defaultHeaders: { 'X-Test-Id': aimock.testId } }
+      : {}),
+    maxRetries: 0,
+  })
+  const drafter = defineAgent({
+    name: 'drafter',
+    description: 'Writes a draft',
+    run: async () => 'Draft',
+  })
+  const handoff = defineHarness({
+    name: 'e2e/harness-routing-handoff',
+    adapter: noSdkRetry,
+    agents: [drafter],
+    routing: { router: () => 'drafter', strategy: 'handoff' },
+    turn: { onModelError: retryTransientErrors({ baseDelayMs: 1 }) },
+  })
+  const editing = await host.open(handoff, { threadId: 'e2e-routing-handoff' })
+  const handoffText = (
+    await editing.prompt('[harness-routing-fix] edit the draft')
+  ).text
+
+  let removed = 0
+  const remove = toolDefinition({
+    name: 'remove',
+    description: 'Remove a file',
+    needsApproval: true,
+    inputSchema: z.object({ path: z.string() }),
+  }).server(async () => {
+    removed += 1
+    return { removed: true }
+  })
+  // The child reads the turn's messages, so its model call matches the user
+  // message, and its resume keeps its own tool call.
+  const cleaner = defineAgent({
+    name: 'cleaner',
+    description: 'Removes files',
+    run: (ctx) => ctx.chat({ adapter: openai(), tools: [remove] }),
+  })
+  const approving = await host.open(
+    defineHarness({
+      name: 'e2e/harness-routing-approval',
+      adapter: openai(),
+      subagents: { agents: [cleaner], router: () => 'cleaner' },
+    }),
+    { threadId: 'e2e-routing-approval' },
+  )
+  const stopped = await approving.prompt('[harness-routing-fix] clean up')
+  const interrupt = stopped.interrupts?.[0]
+  if (!interrupt) throw new Error('The cleaner did not ask for approval.')
+  const receipt = await approving.resolve([
+    { interruptId: interrupt.id, status: 'resolved', payload: true },
+  ])
+  const resumed = approving.operation(receipt.operationId ?? '')
+  if (!resumed) throw new Error('The resolve started no turn.')
+  return { handoffText, approvalText: turnText(await resumed), removed }
+}
+
 /**
  * Start a background agent on a durable host, and let that host stop: its
  * short lease is not renewed in time. A second host opens the same log. It
@@ -237,6 +321,14 @@ export const Route = createFileRoute('/api/harness-test')({
             )
             return Response.json({ workerRuns, text: turn.text })
           }
+          if (body.scenario === 'routing-resume') {
+            return Response.json(
+              await routingResumes(host, openai, {
+                ...(aimockPort !== undefined ? { port: aimockPort } : {}),
+                ...(testId !== undefined ? { testId } : {}),
+              }),
+            )
+          }
           if (body.scenario === 'agent-restart') {
             return Response.json(await agentRestart(openai))
           }
diff --git a/testing/e2e/tests/harness.spec.ts b/testing/e2e/tests/harness.spec.ts
index 5529413bb5..9ac4e92398 100644
--- a/testing/e2e/tests/harness.spec.ts
+++ b/testing/e2e/tests/harness.spec.ts
@@ -88,4 +88,20 @@ test.describe('harness session', () => {
       'pricer:\nAcme costs 30 dollars.',
     ])
   })
+
+  test('a handoff retries a model error, and an approved routed agent resumes', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'routing-resume', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    expect(await response.json()).toEqual({
+      handoffText: 'Edited after a retry.',
+      approvalText: 'cleaner:\nRemoved a.txt.',
+      removed: 1,
+    })
+  })
 })

From 65289404b94c9ed6ec9aa25def0156a80bff7268 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 14:17:50 +0200
Subject: [PATCH 171/286] feat(ai): keep the block order between UIMessage and
 ModelMessage

uiMessageToModelMessages writes blockOrder when the parts of a segment leave the default order, and modelMessageToUIMessage builds the parts in map order. An invalid map gives today's order.
---
 packages/ai/src/activities/chat/messages.ts  | 106 ++++++++----
 packages/ai/tests/message-converters.test.ts | 161 ++++++++++++++++++-
 2 files changed, 238 insertions(+), 29 deletions(-)

diff --git a/packages/ai/src/activities/chat/messages.ts b/packages/ai/src/activities/chat/messages.ts
index 0c4759e70d..251771d0b3 100644
--- a/packages/ai/src/activities/chat/messages.ts
+++ b/packages/ai/src/activities/chat/messages.ts
@@ -12,6 +12,11 @@ import {
   withTanstackMetadata,
 } from '../../utilities/merge-metadata'
 import { isRedactedThinkingId } from '../../utilities/reasoning-encrypted-value'
+import {
+  buildBlockOrder,
+  orderedAssistantBlocks,
+} from '../../utilities/block-order'
+import type { BlockOrderEntry } from '../../utilities/block-order'
 import {
   splitSubagentWire,
   subagentWireText,
@@ -24,6 +29,7 @@ import type {
   StructuredOutputPart,
   TanStackMessageMetadata,
   TextPart,
+  ThinkingPart,
   ToolCall,
   ToolCallPart,
   SubagentPart,
@@ -641,10 +647,12 @@ interface AssistantSegment {
      * `TToolCallMetadata` generic. */
     metadata?: unknown
   }>
+  /** The blocks of this segment in parts order, for the order map. */
+  order: Array<BlockOrderEntry>
 }
 
 function createSegment(): AssistantSegment {
-  return { contentParts: [], toolCalls: [] }
+  return { contentParts: [], toolCalls: [], order: [] }
 }
 
 function isToolCallIncluded(part: ToolCallPart): boolean {
@@ -694,6 +702,10 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
     const hasContent = content !== null
     const hasToolCalls = current.toolCalls.length > 0
     const hasThinking = pendingThinking.length > 0
+    // A map can only point into string content.
+    const blockOrder = Array.isArray(content)
+      ? undefined
+      : buildBlockOrder(current.order)
 
     if (force || hasContent || hasToolCalls || hasThinking) {
       messageList.push({
@@ -705,6 +717,7 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
         ...(current.structuredOutput && {
           structuredOutput: current.structuredOutput,
         }),
+        ...(blockOrder && { blockOrder }),
       })
       pendingThinking = []
     }
@@ -714,6 +727,10 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
   for (const part of uiMessage.parts) {
     switch (part.type) {
       case 'text':
+        current.contentParts.push(part)
+        current.order.push({ type: 'text', text: part.content })
+        break
+
       case 'image':
       case 'audio':
       case 'video':
@@ -732,6 +749,7 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
             },
             ...(part.metadata !== undefined && { metadata: part.metadata }),
           })
+          current.order.push({ type: 'tool-call', id: part.id })
         }
         break
 
@@ -775,6 +793,7 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
             ...(part.signature && { signature: part.signature }),
             ...(part.redacted && { redacted: true }),
           })
+          current.order.push({ type: 'thinking' })
         }
         break
 
@@ -792,6 +811,7 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
                 : ''
           if (serialized !== '') {
             current.contentParts.push({ type: 'text', content: serialized })
+            current.order.push({ type: 'text', text: serialized })
             current.structuredOutput = part
           }
         }
@@ -810,10 +830,9 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
             : ''
         if (block !== '') {
           const prefix = current.contentParts.length > 0 ? '\n\n' : ''
-          current.contentParts.push({
-            type: 'text',
-            content: `${prefix}${block}`,
-          })
+          const text = `${prefix}${block}`
+          current.contentParts.push({ type: 'text', content: text })
+          current.order.push({ type: 'text', text })
         }
         break
       }
@@ -882,6 +901,37 @@ function buildAssistantMessages(uiMessage: UIMessage): Array<ModelMessage> {
   return messageList
 }
 
+function thinkingToPart(
+  thinking: NonNullable<ModelMessage['thinking']>[number],
+): ThinkingPart {
+  return {
+    type: 'thinking',
+    content: thinking.content,
+    ...(thinking.signature && { signature: thinking.signature }),
+    ...(thinking.redacted && { redacted: true }),
+  }
+}
+
+function toolCallToPart(toolCall: ToolCall): ToolCallPart {
+  // Model-message arguments are complete, so surface the parsed input.
+  // A malformed arguments string just leaves `input` undefined.
+  let input: unknown
+  try {
+    input = JSON.parse(toolCall.function.arguments)
+  } catch {
+    input = undefined
+  }
+  return {
+    type: 'tool-call',
+    id: toolCall.id,
+    name: toolCall.function.name,
+    arguments: toolCall.function.arguments,
+    state: 'input-complete', // Model messages have complete arguments
+    ...(input !== undefined && { input }),
+    ...(toolCall.metadata !== undefined && { metadata: toolCall.metadata }),
+  }
+}
+
 /**
  * Convert a ModelMessage to UIMessage
  *
@@ -904,12 +954,7 @@ export function modelMessageToUIMessage(
   if (modelMessage.role === 'assistant' && modelMessage.thinking?.length) {
     for (const thinking of modelMessage.thinking) {
       if (!thinking.content && !thinking.signature) continue
-      parts.push({
-        type: 'thinking',
-        content: thinking.content,
-        ...(thinking.signature && { signature: thinking.signature }),
-        ...(thinking.redacted && { redacted: true }),
-      })
+      parts.push(thinkingToPart(thinking))
     }
   }
 
@@ -975,26 +1020,31 @@ export function modelMessageToUIMessage(
   // Handle tool calls
   if (modelMessage.toolCalls && modelMessage.toolCalls.length > 0) {
     for (const toolCall of modelMessage.toolCalls) {
-      // Model-message arguments are complete, so surface the parsed input.
-      // A malformed arguments string just leaves `input` undefined.
-      let input: unknown
-      try {
-        input = JSON.parse(toolCall.function.arguments)
-      } catch {
-        input = undefined
-      }
-      parts.push({
-        type: 'tool-call',
-        id: toolCall.id,
-        name: toolCall.function.name,
-        arguments: toolCall.function.arguments,
-        state: 'input-complete', // Model messages have complete arguments
-        ...(input !== undefined && { input }),
-        ...(toolCall.metadata !== undefined && { metadata: toolCall.metadata }),
-      })
+      parts.push(toolCallToPart(toolCall))
     }
   }
 
+  // A valid order map puts the blocks back in the order the model sent them.
+  const ordered =
+    modelMessage.role === 'assistant' && structuredOutput === undefined
+      ? orderedAssistantBlocks(modelMessage)
+      : undefined
+  if (ordered) {
+    parts.splice(
+      0,
+      parts.length,
+      ...ordered.flatMap((block): Array<MessagePart> => {
+        if (block.type === 'text') {
+          return [{ type: 'text', content: block.text }]
+        }
+        if (block.type === 'tool-call') return [toolCallToPart(block.toolCall)]
+        return block.thinking.content || block.thinking.signature
+          ? [thinkingToPart(block.thinking)]
+          : []
+      }),
+    )
+  }
+
   const ui: UIMessage = {
     id: id || generateMessageId(),
     role: modelMessage.role === 'tool' ? 'assistant' : modelMessage.role,
diff --git a/packages/ai/tests/message-converters.test.ts b/packages/ai/tests/message-converters.test.ts
index b069ecea8e..7eba509136 100644
--- a/packages/ai/tests/message-converters.test.ts
+++ b/packages/ai/tests/message-converters.test.ts
@@ -6,7 +6,12 @@ import {
   normalizeToUIMessage,
   uiMessageToModelMessages,
 } from '../src/activities/chat/messages'
-import type { ContentPart, ModelMessage, UIMessage } from '../src/types'
+import type {
+  ContentPart,
+  ModelMessage,
+  ToolCallPart,
+  UIMessage,
+} from '../src/types'
 
 describe('Message Converters', () => {
   describe('uiMessageToModelMessages', () => {
@@ -513,6 +518,11 @@ describe('Message Converters', () => {
             },
           ],
           thinking: [{ content: 'Thinking between local tool calls' }],
+          blockOrder: [
+            { type: 'tool-call', id: 'tool-call-a' },
+            { type: 'thinking', index: 0 },
+            { type: 'tool-call', id: 'tool-call-b' },
+          ],
         },
         {
           role: 'tool',
@@ -2780,6 +2790,155 @@ describe('Message Converters', () => {
     })
   })
 
+  describe('block order', () => {
+    function callPart(id: string): ToolCallPart {
+      return {
+        type: 'tool-call',
+        id,
+        name: 'lookup',
+        arguments: '{}',
+        state: 'input-complete',
+      }
+    }
+
+    it('writes blockOrder when the parts leave the default order', () => {
+      const [message] = uiMessageToModelMessages({
+        id: 'a1',
+        role: 'assistant',
+        parts: [
+          { type: 'thinking', content: 'plan', signature: 'sig-a' },
+          callPart('call_1'),
+          { type: 'thinking', content: 'next', signature: 'sig-b' },
+          callPart('call_2'),
+        ],
+      })
+
+      expect(message).toEqual({
+        id: 'a1',
+        role: 'assistant',
+        content: null,
+        toolCalls: [
+          {
+            id: 'call_1',
+            type: 'function',
+            function: { name: 'lookup', arguments: '{}' },
+          },
+          {
+            id: 'call_2',
+            type: 'function',
+            function: { name: 'lookup', arguments: '{}' },
+          },
+        ],
+        thinking: [
+          { content: 'plan', signature: 'sig-a' },
+          { content: 'next', signature: 'sig-b' },
+        ],
+        blockOrder: [
+          { type: 'thinking', index: 0 },
+          { type: 'tool-call', id: 'call_1' },
+          { type: 'thinking', index: 1 },
+          { type: 'tool-call', id: 'call_2' },
+        ],
+      })
+    })
+
+    it('writes no blockOrder for parts in the default order', () => {
+      const [message] = uiMessageToModelMessages({
+        id: 'a1',
+        role: 'assistant',
+        parts: [
+          { type: 'thinking', content: 'plan', signature: 'sig-a' },
+          { type: 'text', content: 'Hello' },
+          callPart('call_1'),
+        ],
+      })
+
+      expect(message).not.toHaveProperty('blockOrder')
+    })
+
+    it('builds UIMessage parts in map order', () => {
+      const ui = modelMessageToUIMessage(
+        {
+          role: 'assistant',
+          content: 'AB',
+          thinking: [{ content: 'plan' }, { content: 'check' }],
+          blockOrder: [
+            { type: 'thinking', index: 0 },
+            { type: 'text', length: 1 },
+            { type: 'thinking', index: 1 },
+            { type: 'text', length: 1 },
+          ],
+        },
+        'a1',
+      )
+
+      expect(ui.parts).toEqual([
+        { type: 'thinking', content: 'plan' },
+        { type: 'text', content: 'A' },
+        { type: 'thinking', content: 'check' },
+        { type: 'text', content: 'B' },
+      ])
+    })
+
+    it('keeps the default order when the map does not match the message', () => {
+      const ui = modelMessageToUIMessage(
+        {
+          role: 'assistant',
+          content: 'AB',
+          thinking: [{ content: 'plan' }, { content: 'check' }],
+          // The text lengths add up to 1, not 2.
+          blockOrder: [
+            { type: 'thinking', index: 0 },
+            { type: 'text', length: 1 },
+            { type: 'thinking', index: 1 },
+          ],
+        },
+        'a1',
+      )
+
+      expect(ui.parts).toEqual([
+        { type: 'thinking', content: 'plan' },
+        { type: 'thinking', content: 'check' },
+        { type: 'text', content: 'AB' },
+      ])
+    })
+
+    it('keeps the order from UIMessage to ModelMessage and back', () => {
+      const original: UIMessage = {
+        id: 'a1',
+        role: 'assistant',
+        parts: [
+          { type: 'thinking', content: 'plan', signature: 'sig-a' },
+          { type: 'text', content: 'Let me look.' },
+          callPart('call_1'),
+          { type: 'thinking', content: 'next', signature: 'sig-b' },
+          { type: 'text', content: 'And again.' },
+          callPart('call_2'),
+        ],
+      }
+
+      const back = modelMessagesToUIMessages(uiMessageToModelMessages(original))
+
+      expect(back).toHaveLength(1)
+      expect(
+        back[0]?.parts.map((part) =>
+          part.type === 'tool-call'
+            ? `tool-call:${part.id}`
+            : part.type === 'text' || part.type === 'thinking'
+              ? `${part.type}:${part.content}`
+              : part.type,
+        ),
+      ).toEqual([
+        'thinking:plan',
+        'text:Let me look.',
+        'tool-call:call_1',
+        'thinking:next',
+        'text:And again.',
+        'tool-call:call_2',
+      ])
+    })
+  })
+
   it('preserves createdAt fields inside tool content and metadata', () => {
     const metadata = {
       createdAt: 'tool-metadata',

From 6c274892a500137b84bc70622e097bdca30761de Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 14:17:50 +0200
Subject: [PATCH 172/286] feat(ai): add mid-conversation change types and
 helpers

ModelMessage.midConversationChange, TextOptions.midConversationChanges, and TextAdapter.midConversationChannels are new optional fields. splitMidConversationChanges gives an adapter the start lists and the changes by message index.
---
 packages/ai/src/activities/chat/adapter.ts    |  14 ++
 packages/ai/src/adapter-internals.ts          |   1 +
 packages/ai/src/index.ts                      |   2 +
 packages/ai/src/types.ts                      |  58 ++++++++
 packages/ai/src/utilities/mid-conversation.ts |  71 ++++++++++
 packages/ai/tests/mid-conversation.test.ts    | 129 ++++++++++++++++++
 6 files changed, 275 insertions(+)
 create mode 100644 packages/ai/src/utilities/mid-conversation.ts
 create mode 100644 packages/ai/tests/mid-conversation.test.ts

diff --git a/packages/ai/src/activities/chat/adapter.ts b/packages/ai/src/activities/chat/adapter.ts
index c30087cb51..9997262a76 100644
--- a/packages/ai/src/activities/chat/adapter.ts
+++ b/packages/ai/src/activities/chat/adapter.ts
@@ -1,6 +1,7 @@
 import type {
   DefaultMessageMetadataByModality,
   JSONSchema,
+  MidConversationChannels,
   Modality,
   TextOptions,
   TokenUsage,
@@ -107,6 +108,14 @@ export interface TextAdapter<
    */
   readonly inputModalities?: ReadonlyArray<Modality>
 
+  /**
+   * The mid-conversation channels of the model: tools and system prompts
+   * added between model calls can go out with no change to the cached prompt
+   * prefix. `chat()` passes `TextOptions.midConversationChanges` only when a
+   * channel is on. `undefined` means no channels.
+   */
+  readonly midConversationChannels?: MidConversationChannels
+
   /**
    * @internal Type-only properties for inference. Not assigned at runtime.
    */
@@ -242,6 +251,11 @@ export abstract class BaseTextAdapter<
    * `override readonly inputModalities = INPUT_BY_MODEL[this.model]`.
    */
   readonly inputModalities?: ReadonlyArray<Modality> = undefined
+  /**
+   * Provider subclasses override this from their model metadata, the same
+   * way as `inputModalities`. No channels by default.
+   */
+  readonly midConversationChannels?: MidConversationChannels = undefined
 
   // Type-only property - never assigned at runtime
   declare '~types': {
diff --git a/packages/ai/src/adapter-internals.ts b/packages/ai/src/adapter-internals.ts
index 8e643f8e40..c5ecaf478d 100644
--- a/packages/ai/src/adapter-internals.ts
+++ b/packages/ai/src/adapter-internals.ts
@@ -75,3 +75,4 @@ export type {
   BlockOrderEntry,
   OrderedAssistantBlock,
 } from './utilities/block-order'
+export { splitMidConversationChanges } from './utilities/mid-conversation'
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index b663d4036a..542295554f 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -603,6 +603,8 @@ export {
 } from './utilities/provider-executed'
 export { orderedAssistantBlocks } from './utilities/block-order'
 export type { OrderedAssistantBlock } from './utilities/block-order'
+export { splitMidConversationChanges } from './utilities/mid-conversation'
+export type { MidConversationRequest } from './utilities/mid-conversation'
 
 // Adapter extension utilities
 export { createModel, extendAdapter } from './extend-adapter'
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index f7a23755b1..9cf05a8981 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -380,6 +380,50 @@ export type ModelMessageBlock =
   | { type: 'text'; length: number }
   | { type: 'tool-call'; id: string }
 
+/**
+ * The mid-conversation record that `chat()` saves on the first assistant
+ * message of a model call. It holds tool names and prompt hashes only, so it
+ * does not depend on a provider.
+ */
+export interface MidConversationChange {
+  /** A start point: the names of every tool. */
+  tools?: Array<string>
+  /** Tool names added since the last record. */
+  toolsAdded?: Array<string>
+  /** Short prompt hashes: every prompt on a start point, the added prompts otherwise. */
+  systemPrompts?: Array<string>
+}
+
+/**
+ * What changed in the tools and system prompts between model calls.
+ * `chat()` passes it in `TextOptions.midConversationChanges`.
+ */
+export interface MidConversationChanges {
+  /**
+   * The tool names of the start point, in start order, and how many entries
+   * at the front of `systemPrompts` belong to it.
+   */
+  start: { tools: Array<string>; systemPrompts: number }
+  /**
+   * Each change goes directly before `messages[before]`, or at the end when
+   * `before === messages.length`. `tools` are the added names.
+   * `systemPrompts` is how many of the next entries of `systemPrompts` it adds.
+   */
+  changes: Array<{
+    before: number
+    tools?: Array<string>
+    systemPrompts?: number
+  }>
+}
+
+/** The mid-conversation channels of a model. */
+export interface MidConversationChannels {
+  /** Added tools can go out without a change to the tools of the start point. */
+  tools: boolean
+  /** Added system prompts can go out as a message at their place. */
+  systemPrompts: boolean
+}
+
 export interface ModelMessage<
   TContent extends string | null | Array<ContentPart> =
     | string
@@ -407,6 +451,12 @@ export interface ModelMessage<
   blockOrder?: Array<ModelMessageBlock>
   /** Error reported by an AG-UI tool message. */
   error?: string
+  /**
+   * The tools and system prompts that changed before this assistant message.
+   * `chat()` writes it when the adapter has a mid-conversation channel.
+   * Providers ignore it: adapters read `TextOptions.midConversationChanges`.
+   */
+  midConversationChange?: MidConversationChange
   /** Optional AG-UI message metadata. TanStack-owned fields live under `tanstack`. */
   metadata?: Record<string, any>
   /**
@@ -1253,6 +1303,14 @@ export interface TextOptions<
    * absent, the adapter adds no automatic cache fields.
    */
   promptCache?: ResolvedPromptCache
+  /**
+   * The tools and system prompts that changed between model calls. The
+   * engine sets it only when `adapter.midConversationChannels` has a channel
+   * that is on. `tools` and `systemPrompts` stay the full current lists, so
+   * an adapter that ignores this field sends the same request as before.
+   * Adapters resolve it with `splitMidConversationChanges`.
+   */
+  midConversationChanges?: MidConversationChanges
   /**
    * Run ID for AG-UI protocol run correlation.
    * When provided, this will be used in RunStartedEvent and RunFinishedEvent.
diff --git a/packages/ai/src/utilities/mid-conversation.ts b/packages/ai/src/utilities/mid-conversation.ts
new file mode 100644
index 0000000000..1517080e0c
--- /dev/null
+++ b/packages/ai/src/utilities/mid-conversation.ts
@@ -0,0 +1,71 @@
+import type { MidConversationChanges } from '../types'
+
+export interface MidConversationRequest<TTool, TPrompt> {
+  startTools: Array<TTool>
+  startSystemPrompts: Array<TPrompt>
+  /** Every added tool, in change order. */
+  addedTools: Array<TTool>
+  /** The changes by message index (`before`). */
+  at: Map<number, { tools: Array<TTool>; systemPrompts: Array<TPrompt> }>
+}
+
+/**
+ * For adapters: resolve the names and counts of `changes` against the current
+ * `tools` and `systemPrompts`. Returns `undefined` when a name is missing, a
+ * name is used twice, or the counts do not add up. Then the adapter sends the
+ * request it sends today.
+ */
+export function splitMidConversationChanges<
+  TTool extends { name: string },
+  TPrompt,
+>(input: {
+  changes: MidConversationChanges
+  tools: ReadonlyArray<TTool>
+  systemPrompts: ReadonlyArray<TPrompt>
+}): MidConversationRequest<TTool, TPrompt> | undefined {
+  const { changes, tools, systemPrompts } = input
+  const byName = new Map(tools.map((tool) => [tool.name, tool] as const))
+  const used = new Set<string>()
+  const pick = (names: ReadonlyArray<string>) => {
+    const picked: Array<TTool> = []
+    for (const name of names) {
+      const tool = byName.get(name)
+      if (!tool || used.has(name)) return undefined
+      used.add(name)
+      picked.push(tool)
+    }
+    return picked
+  }
+
+  const startTools = pick(changes.start.tools)
+  let offset = changes.start.systemPrompts
+  if (!startTools || offset > systemPrompts.length) return undefined
+  const request: MidConversationRequest<TTool, TPrompt> = {
+    startTools,
+    startSystemPrompts: systemPrompts.slice(0, offset),
+    addedTools: [],
+    at: new Map(),
+  }
+  for (const change of changes.changes) {
+    const added = pick(change.tools ?? [])
+    const count = change.systemPrompts ?? 0
+    if (
+      !added ||
+      offset + count > systemPrompts.length ||
+      request.at.has(change.before)
+    ) {
+      return undefined
+    }
+    request.addedTools.push(...added)
+    request.at.set(change.before, {
+      tools: added,
+      systemPrompts: systemPrompts.slice(offset, offset + count),
+    })
+    offset += count
+  }
+  // Every current tool and prompt must have its place.
+  if (used.size !== tools.length || offset !== systemPrompts.length) {
+    return undefined
+  }
+  return request
+}
diff --git a/packages/ai/tests/mid-conversation.test.ts b/packages/ai/tests/mid-conversation.test.ts
new file mode 100644
index 0000000000..87052a90ef
--- /dev/null
+++ b/packages/ai/tests/mid-conversation.test.ts
@@ -0,0 +1,129 @@
+import { describe, expect, it } from 'vitest'
+import { splitMidConversationChanges } from '../src/utilities/mid-conversation'
+import * as adapterInternals from '../src/adapter-internals'
+import * as ai from '../src/index'
+import type { MidConversationChanges } from '../src/types'
+import type { SystemPrompt } from '../src/system-prompts'
+
+describe('splitMidConversationChanges', () => {
+  const a = { name: 'a' }
+  const b = { name: 'b' }
+  const c = { name: 'c' }
+
+  it('splits the current lists into the start and the changes', () => {
+    const result = splitMidConversationChanges({
+      changes: {
+        start: { tools: ['b', 'a'], systemPrompts: 1 },
+        changes: [
+          { before: 3, systemPrompts: 1 },
+          { before: 5, tools: ['c'] },
+        ],
+      },
+      tools: [a, b, c],
+      systemPrompts: ['A', 'B'],
+    })
+
+    expect(result).toEqual({
+      startTools: [b, a],
+      startSystemPrompts: ['A'],
+      addedTools: [c],
+      at: new Map([
+        [3, { tools: [], systemPrompts: ['B'] }],
+        [5, { tools: [c], systemPrompts: [] }],
+      ]),
+    })
+  })
+
+  it.each<[string, MidConversationChanges]>([
+    [
+      'a start tool is missing',
+      {
+        start: { tools: ['a', 'gone'], systemPrompts: 1 },
+        changes: [{ before: 1, tools: ['b', 'c'] }],
+      },
+    ],
+    [
+      'an added tool is missing',
+      {
+        start: { tools: ['a'], systemPrompts: 1 },
+        changes: [{ before: 1, tools: ['b', 'gone'] }],
+      },
+    ],
+    [
+      'a current tool has no place',
+      {
+        start: { tools: ['a'], systemPrompts: 1 },
+        changes: [{ before: 1, tools: ['b'] }],
+      },
+    ],
+    [
+      'a tool is named twice',
+      {
+        start: { tools: ['a', 'b'], systemPrompts: 1 },
+        changes: [{ before: 1, tools: ['b', 'c'] }],
+      },
+    ],
+    [
+      'the start has more prompts than the list',
+      { start: { tools: ['a', 'b', 'c'], systemPrompts: 2 }, changes: [] },
+    ],
+    [
+      'a change has more prompts than are left',
+      {
+        start: { tools: ['a', 'b', 'c'], systemPrompts: 0 },
+        changes: [{ before: 1, systemPrompts: 2 }],
+      },
+    ],
+    [
+      'a prompt has no place',
+      { start: { tools: ['a', 'b', 'c'], systemPrompts: 0 }, changes: [] },
+    ],
+    [
+      'two changes have the same place',
+      {
+        start: { tools: ['a'], systemPrompts: 0 },
+        changes: [
+          { before: 1, tools: ['b'] },
+          { before: 1, tools: ['c'], systemPrompts: 1 },
+        ],
+      },
+    ],
+  ])('returns undefined when %s', (_label, changes) => {
+    expect(
+      splitMidConversationChanges({
+        changes,
+        tools: [a, b, c],
+        systemPrompts: ['A'],
+      }),
+    ).toBeUndefined()
+  })
+
+  it('keeps the prompt objects, with their metadata', () => {
+    const cached: SystemPrompt = {
+      content: 'A',
+      metadata: { cache_control: { type: 'ephemeral' } },
+    }
+    const prompts: Array<SystemPrompt> = [cached, 'B']
+
+    const result = splitMidConversationChanges({
+      changes: {
+        start: { tools: ['a'], systemPrompts: 1 },
+        changes: [{ before: 2, systemPrompts: 1 }],
+      },
+      tools: [a],
+      systemPrompts: prompts,
+    })
+
+    expect(result?.startSystemPrompts[0]).toBe(cached)
+    expect(result?.at.get(2)?.systemPrompts).toEqual(['B'])
+  })
+})
+
+describe('mid-conversation exports', () => {
+  it('gives adapter authors the helpers', () => {
+    expect(adapterInternals.splitMidConversationChanges).toBe(
+      splitMidConversationChanges,
+    )
+    expect(ai.splitMidConversationChanges).toBe(splitMidConversationChanges)
+  })
+})

From d3f5790a15595d272d4dadc954176f5ea32e1bf5 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 14:36:34 +0200
Subject: [PATCH 173/286] fix(ai-harness): continue an interrupted turn after a
 restart

The interrupts that a turn waits on lived only in memory. After a restart,
the next host refused every resolve with `no_pending_interrupts`, for a
main-model approval and for a routed agent.

The session now keeps the interrupted turn in `stores.metadata` (namespace
`harness:interrupted`, key the thread id), with the agent cards of a
routed turn. `open()` reads it back, and a resolve removes it. A failed
write or delete is a warning event. Without a metadata store, the state
stays in memory, as before.
---
 .changeset/harness-interrupt-restart.md       |   5 +
 docs/harness/durable-sessions.md              |   2 +-
 docs/harness/overview.md                      |   1 +
 packages/ai-harness/src/session.ts            |  59 +++++-
 .../tests/interrupt-restart.test.ts           | 183 ++++++++++++++++++
 testing/e2e/fixtures/harness/basic.json       |  23 +++
 testing/e2e/src/routes/api.harness-test.ts    |  51 +++++
 testing/e2e/tests/harness.spec.ts             |  15 ++
 8 files changed, 330 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/harness-interrupt-restart.md
 create mode 100644 packages/ai-harness/tests/interrupt-restart.test.ts

diff --git a/.changeset/harness-interrupt-restart.md b/.changeset/harness-interrupt-restart.md
new file mode 100644
index 0000000000..f936d958de
--- /dev/null
+++ b/.changeset/harness-interrupt-restart.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-harness': patch
+---
+
+A resolve after a restart now continues the turn that stopped for an interrupt. Before, the waiting interrupts lived only in memory, so the next host refused the resolve with `no_pending_interrupts`. The session now keeps them in `stores.metadata`, with the agent cards of a routed turn, and the next host that opens the thread reads them back. A resolve removes the stored copy. Without a metadata store, the interrupts stay in memory, as before.
diff --git a/docs/harness/durable-sessions.md b/docs/harness/durable-sessions.md
index f32d307629..890f8e2328 100644
--- a/docs/harness/durable-sessions.md
+++ b/docs/harness/durable-sessions.md
@@ -33,7 +33,7 @@ const host = createHarnessHost({
 })
 ```
 
-`metadata` is optional. With it, the host keeps a fold checkpoint of each log, so a long thread opens faster. To store the log in your database, implement the [`LogStore` contract](../persistence/store-reference#logstore).
+`metadata` is optional. With it, the host keeps a fold checkpoint of each log, so a long thread opens faster. It also keeps the interrupts that the last turn waits on, so `session.resolve` continues that turn on the next host. To store the log in your database, implement the [`LogStore` contract](../persistence/store-reference#logstore).
 
 ## Limit attempts and time
 
diff --git a/docs/harness/overview.md b/docs/harness/overview.md
index b5cf4f7012..8e7c706ff4 100644
--- a/docs/harness/overview.md
+++ b/docs/harness/overview.md
@@ -170,6 +170,7 @@ The host takes the same stores as `withPersistence`. Add an `inbox` store and th
 - `runs`: the record of every turn and agent run. When the host stops during a background agent run, the next session ends that run `failed` and notes it in the transcript.
 - `interrupts`: approvals that wait for a user.
 - `inbox`: accepted messages that did not run yet.
+- `metadata`: the session config, plugin state, and the interrupts that the last turn waits on. With it, `session.resolve` continues that turn after a restart, also a turn that a router sent to agents.
 
 `memoryPersistence()` has every store, but it keeps them in memory only. Write your own stores to keep data in your database. See [Build your own adapter](../persistence/build-your-own-adapter).
 
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index a30d52e64a..d7ddcfca8d 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -260,6 +260,30 @@ interface QueuedTurn {
   routed?: { messages: Array<UIMessage>; root: boolean }
 }
 
+/** The interrupts the last turn stopped for, and how a resolve continues it. */
+interface InterruptedTurn {
+  runId: string
+  interrupts: Array<Interrupt>
+  routed?: QueuedTurn['routed']
+}
+
+/** Where `stores.metadata` keeps the interrupted turn of each thread. */
+const INTERRUPTED = 'harness:interrupted'
+
+/** True for an interrupted turn as `stores.metadata` gives it back. */
+function isInterruptedTurn(value: unknown): value is InterruptedTurn {
+  if (!isRecord(value) || typeof value.runId !== 'string') return false
+  if (!Array.isArray(value.interrupts)) return false
+  if (!value.interrupts.every((item) => isRecord(item))) return false
+  const { routed } = value
+  return (
+    routed === undefined ||
+    (isRecord(routed) &&
+      Array.isArray(routed.messages) &&
+      typeof routed.root === 'boolean')
+  )
+}
+
 /** Limits for a harness's children when `subagents.limits` is not set. */
 export const DEFAULT_SUBAGENT_LIMITS = {
   maxDepth: 2,
@@ -447,15 +471,10 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   private activeTurn: OperationImpl<ChatTurnResult> | undefined
   /**
    * The last turn stopped for these interrupts. `routed`: a routed turn
-   * stopped. The resolve continues its saved plan.
+   * stopped. The resolve continues its saved plan. `stores.metadata` keeps a
+   * copy, so a resolve after a restart continues the turn too.
    */
-  private interrupted:
-    | {
-        runId: string
-        interrupts: Array<Interrupt>
-        routed?: QueuedTurn['routed']
-      }
-    | undefined
+  private interrupted: InterruptedTurn | undefined
   private plugins: ReadonlyArray<HarnessPlugin> = []
   private sessionPlugins: MountedPlugins | undefined
   private closing: Promise<void> | undefined
@@ -632,6 +651,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       )
       await this.loadConfig()
       await this.loadPluginState()
+      await this.loadInterrupted()
       if (this.writer) {
         await this.recoverFromLog(this.writer)
         return
@@ -902,6 +922,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     const operation = this.createTurnOperation()
     this.bindTurn(inputId, operation)
     this.enqueueTurn({ operation, resume, parentRunId, inputId, routed })
+    // The stored copy goes too, so a restart does not offer this turn again.
+    // A failed delete is a warning: the resolve runs anyway.
+    await this.persistence.stores.metadata
+      ?.delete(INTERRUPTED, this.threadId)
+      .catch((error: unknown) =>
+        this.warn(operation, 'harness:interrupts', error),
+      )
     return this.keep({ inputId, status: 'accepted', operationId: operation.id })
   }
 
@@ -1267,6 +1294,15 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }
   }
 
+  /** Restore the interrupted turn that `stores.metadata` keeps for this thread. */
+  private async loadInterrupted(): Promise<void> {
+    const stored = await this.persistence.stores.metadata?.get(
+      INTERRUPTED,
+      this.threadId,
+    )
+    if (isInterruptedTurn(stored)) this.interrupted = stored
+  }
+
   /** Put each plugin's saved state in the snapshot before the first read. */
   private async loadPluginState() {
     for (const [plugin, load] of this.stateLoaders) {
@@ -2429,6 +2465,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           ? { routed: { messages: cardMessages, root: isRootPart } }
           : {}),
       }
+      // Kept before the turn ends, so a restart right after it can resolve.
+      // A failed write is a warning: the turn still ends interrupted.
+      await this.persistence.stores.metadata
+        ?.set(INTERRUPTED, this.threadId, this.interrupted)
+        .catch((error: unknown) =>
+          this.warn(operation, 'harness:interrupts', error),
+        )
       await settleTurn({ outcome: 'interrupted' })
       operation.finish('interrupted', { text, interrupts })
     } else {
diff --git a/packages/ai-harness/tests/interrupt-restart.test.ts b/packages/ai-harness/tests/interrupt-restart.test.ts
new file mode 100644
index 0000000000..615be15d84
--- /dev/null
+++ b/packages/ai-harness/tests/interrupt-restart.test.ts
@@ -0,0 +1,183 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { defineAgent, toolDefinition } from '@tanstack/ai'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '../src'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { AnyTool } from '@tanstack/ai'
+import type { AnyAgent, HarnessRouting, HarnessSubagents } from '../src'
+import type { Reply } from './helpers'
+
+const THREAD = 't1'
+
+/** A tool that asks approval before it removes a file. */
+function removeTool() {
+  const execute = vi.fn(async () => ({ removed: true }))
+  const tool = toolDefinition({
+    name: 'remove',
+    description: 'Remove a file',
+    needsApproval: true,
+    inputSchema: z.object({ path: z.string() }),
+  }).server(execute)
+  return { tool, execute }
+}
+
+/** An agent whose model asks approval to remove `a.txt`, then reports. */
+function cleanerAgent(tool: AnyTool) {
+  const child = mockAdapter([
+    () => toolCall('remove', { path: 'a.txt' }, 'call_c'),
+    () => text('Removed a.txt'),
+  ])
+  return defineAgent({
+    name: 'cleaner',
+    description: 'Removes files',
+    run: (ctx) => ctx.chat({ adapter: child.adapter, tools: [tool] }),
+  })
+}
+
+/**
+ * The stores of one thread, and a function that opens a new host on them,
+ * like a server that started again. `durable` gives the hosts a log.
+ */
+function restartable(durable: boolean) {
+  const { stores } = memoryPersistence()
+  const { runs, metadata } = stores
+  const log = memoryLogStore()
+  const persistence = durable ? { stores: { log, runs, metadata } } : { stores }
+  return (options: {
+    tools?: ReadonlyArray<AnyTool>
+    agents?: ReadonlyArray<AnyAgent>
+    subagents?: HarnessSubagents<ReadonlyArray<AnyAgent>>
+    routing?: HarnessRouting
+    replies?: Array<Reply>
+  }) => {
+    const main = mockAdapter(options.replies ?? [])
+    const host = createHarnessHost({ persistence })
+    const opened = host.open(
+      defineHarness({
+        name: 'test/interrupt-restart',
+        adapter: main.adapter,
+        ...(options.tools ? { tools: options.tools } : {}),
+        ...(options.agents ? { agents: options.agents } : {}),
+        ...(options.subagents ? { subagents: options.subagents } : {}),
+        ...(options.routing ? { routing: options.routing } : {}),
+      }),
+      { threadId: THREAD },
+    )
+    return opened.then((session) => ({ host, session, calls: main.calls }))
+  }
+}
+
+describe.each([
+  { host: 'a host without a log', durable: false },
+  { host: 'a durable host', durable: true },
+])('a resolve after a restart on $host', ({ durable }) => {
+  it("continues the main model's approval", async () => {
+    const open = restartable(durable)
+    const remove = removeTool()
+    const first = await open({
+      tools: [remove.tool],
+      replies: [() => toolCall('remove', { path: 'b.txt' }, 'call_m')],
+    })
+    const stopped = await first.session.prompt('clean up')
+    const interrupt = stopped.interrupts?.[0]
+    if (!interrupt) throw new Error('The turn did not stop for approval.')
+    await first.host.close()
+
+    const next = await open({
+      tools: [remove.tool],
+      replies: [() => text('Removed b.txt')],
+    })
+    expect(
+      next.session.snapshot().pendingInterrupts.map((item) => item.id),
+    ).toEqual([interrupt.id])
+    const receipt = await next.session.resolve([
+      { interruptId: interrupt.id, status: 'resolved', payload: true },
+    ])
+    expect(receipt.status).toBe('accepted')
+    expect(await next.session.operation(receipt.operationId ?? '')).toEqual({
+      text: 'Removed b.txt',
+    })
+    expect(remove.execute).toHaveBeenCalledTimes(1)
+    await next.host.close()
+  })
+
+  it('offers an interrupt once: after its resolve, a restart has none', async () => {
+    const open = restartable(durable)
+    const remove = removeTool()
+    const first = await open({
+      tools: [remove.tool],
+      replies: [
+        () => toolCall('remove', { path: 'b.txt' }, 'call_m'),
+        () => text('Removed b.txt'),
+      ],
+    })
+    const stopped = await first.session.prompt('clean up')
+    const interrupt = stopped.interrupts?.[0]
+    if (!interrupt) throw new Error('The turn did not stop for approval.')
+    const receipt = await first.session.resolve([
+      { interruptId: interrupt.id, status: 'resolved', payload: true },
+    ])
+    await first.session.operation(receipt.operationId ?? '')
+    await first.host.close()
+
+    const next = await open({ tools: [remove.tool] })
+    expect(next.session.snapshot().pendingInterrupts).toEqual([])
+    expect(
+      await next.session.resolve([
+        { interruptId: interrupt.id, status: 'resolved', payload: true },
+      ]),
+    ).toMatchObject({ status: 'rejected', reason: 'no_pending_interrupts' })
+    expect(remove.execute).toHaveBeenCalledTimes(1)
+    await next.host.close()
+  })
+
+  it('continues a subagents.router agent that stopped for approval', async () => {
+    const open = restartable(durable)
+    const remove = removeTool()
+    const cleaner = cleanerAgent(remove.tool)
+    const subagents = { agents: [cleaner], router: () => 'cleaner' }
+    const first = await open({ subagents })
+    const stopped = await first.session.prompt('clean up')
+    const interrupt = stopped.interrupts?.[0]
+    if (!interrupt) throw new Error('The turn did not stop for approval.')
+    await first.host.close()
+
+    const next = await open({ subagents })
+    const receipt = await next.session.resolve([
+      { interruptId: interrupt.id, status: 'resolved', payload: true },
+    ])
+    expect(receipt.status).toBe('accepted')
+    expect(await next.session.operation(receipt.operationId ?? '')).toEqual({
+      text: 'cleaner:\nRemoved a.txt',
+    })
+    expect(remove.execute).toHaveBeenCalledTimes(1)
+    expect(next.calls).toHaveLength(0)
+    await next.host.close()
+  })
+
+  it('continues the plan of a root agent that stopped for approval', async () => {
+    const open = restartable(durable)
+    const remove = removeTool()
+    const cleaner = cleanerAgent(remove.tool)
+    const router = vi.fn(() => 'cleaner')
+    const first = await open({ agents: [cleaner], routing: { router } })
+    const stopped = await first.session.prompt('clean up')
+    const interrupt = stopped.interrupts?.[0]
+    if (!interrupt) throw new Error('The turn did not stop for approval.')
+    await first.host.close()
+
+    const next = await open({ agents: [cleaner], routing: { router } })
+    const receipt = await next.session.resolve([
+      { interruptId: interrupt.id, status: 'resolved', payload: true },
+    ])
+    expect(receipt.status).toBe('accepted')
+    expect(await next.session.operation(receipt.operationId ?? '')).toEqual({
+      text: 'cleaner:\nRemoved a.txt',
+    })
+    expect(remove.execute).toHaveBeenCalledTimes(1)
+    // The resolve continues the saved plan. It does not ask the router again.
+    expect(router).toHaveBeenCalledTimes(1)
+    await next.host.close()
+  })
+})
diff --git a/testing/e2e/fixtures/harness/basic.json b/testing/e2e/fixtures/harness/basic.json
index 63c7fe395e..3a642d81df 100644
--- a/testing/e2e/fixtures/harness/basic.json
+++ b/testing/e2e/fixtures/harness/basic.json
@@ -107,6 +107,29 @@
         "content": "Edited after a retry."
       }
     },
+    {
+      "match": {
+        "userMessage": "[harness-restart-resolve] remove b.txt",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "remove",
+            "arguments": "{\"path\":\"b.txt\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-restart-resolve] remove b.txt",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Removed b.txt after the restart."
+      }
+    },
     {
       "match": {
         "userMessage": "[harness-routing-fix] clean up",
diff --git a/testing/e2e/src/routes/api.harness-test.ts b/testing/e2e/src/routes/api.harness-test.ts
index 08a14f0e88..ef94a1aec3 100644
--- a/testing/e2e/src/routes/api.harness-test.ts
+++ b/testing/e2e/src/routes/api.harness-test.ts
@@ -180,6 +180,54 @@ async function routingResumes(
   return { handoffText, approvalText: turnText(await resumed), removed }
 }
 
+/**
+ * A turn stops for approval, and its host closes. A second host opens the
+ * same stores and resolves the approval, like a server that started again.
+ * Returns the text of the resumed turn and how many times the tool ran.
+ */
+async function resolveAfterRestart(
+  openai: () => ReturnType<typeof createTextAdapter>['adapter'],
+) {
+  const persistence = memoryPersistence()
+  let removed = 0
+  const remove = toolDefinition({
+    name: 'remove',
+    description: 'Remove a file',
+    needsApproval: true,
+    inputSchema: z.object({ path: z.string() }),
+  }).server(async () => {
+    removed += 1
+    return { removed: true }
+  })
+  const harness = defineHarness({
+    name: 'e2e/harness-resolve-restart',
+    adapter: openai(),
+    tools: [remove],
+  })
+  const first = createHarnessHost({ persistence })
+  const stopped = await (
+    await first.open(harness, { threadId: 'e2e-resolve-restart' })
+  ).prompt('[harness-restart-resolve] remove b.txt')
+  const interrupt = stopped.interrupts?.[0]
+  await first.close()
+  if (!interrupt) throw new Error('The turn did not ask for approval.')
+
+  const next = createHarnessHost({ persistence })
+  try {
+    const session = await next.open(harness, {
+      threadId: 'e2e-resolve-restart',
+    })
+    const receipt = await session.resolve([
+      { interruptId: interrupt.id, status: 'resolved', payload: true },
+    ])
+    const resumed = session.operation(receipt.operationId ?? '')
+    if (!resumed) throw new Error(`The resolve was ${receipt.status}.`)
+    return { text: turnText(await resumed), removed }
+  } finally {
+    await next.close()
+  }
+}
+
 /**
  * Start a background agent on a durable host, and let that host stop: its
  * short lease is not renewed in time. A second host opens the same log. It
@@ -329,6 +377,9 @@ export const Route = createFileRoute('/api/harness-test')({
               }),
             )
           }
+          if (body.scenario === 'resolve-restart') {
+            return Response.json(await resolveAfterRestart(openai))
+          }
           if (body.scenario === 'agent-restart') {
             return Response.json(await agentRestart(openai))
           }
diff --git a/testing/e2e/tests/harness.spec.ts b/testing/e2e/tests/harness.spec.ts
index 9ac4e92398..bac6eb4d50 100644
--- a/testing/e2e/tests/harness.spec.ts
+++ b/testing/e2e/tests/harness.spec.ts
@@ -104,4 +104,19 @@ test.describe('harness session', () => {
       removed: 1,
     })
   })
+
+  test('a resolve on a new host continues the turn that stopped for approval', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'resolve-restart', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    expect(await response.json()).toEqual({
+      text: 'Removed b.txt after the restart.',
+      removed: 1,
+    })
+  })
 })

From 193ec947a33d8fe6d8be0b69ebaed7b8ad625f75 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 14:36:37 +0200
Subject: [PATCH 174/286] test(ai-skills): cover load_skill, a removed skill,
 and a failed watcher

The Coverage job failed: ai-skills function coverage dropped from 84.86%
to 83.42%. Five functions of the skills harness plugin had no test:
`source.load`, `listResources`, `listScripts`, `folderOf`, and the
watcher's error handler. Three tests now run them through the plugin.
---
 packages/ai-skills/tests/harness.test.ts | 106 ++++++++++++++++++++---
 1 file changed, 94 insertions(+), 12 deletions(-)

diff --git a/packages/ai-skills/tests/harness.test.ts b/packages/ai-skills/tests/harness.test.ts
index 6c69582f48..5c96a38efd 100644
--- a/packages/ai-skills/tests/harness.test.ts
+++ b/packages/ai-skills/tests/harness.test.ts
@@ -1,6 +1,8 @@
+import { watch } from 'node:fs'
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { fakeText } from '@tanstack/ai/testing'
 import {
@@ -10,10 +12,21 @@ import {
   definePlugin,
 } from '@tanstack/ai-harness'
 import { skills } from '../src/harness'
+import type * as NodeFs from 'node:fs'
 import type { TextOptions } from '@tanstack/ai'
+import type { FakeResponse } from '@tanstack/ai/testing'
 import type { HarnessHost, HarnessPlugin } from '@tanstack/ai-harness'
 import type { SkillsPluginOptions } from '../src/harness'
 
+// The real `watch`, in a mock, so that a test can get a watcher and make it
+// fail.
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal<typeof NodeFs>()
+  return { ...actual, watch: vi.fn(actual.watch) }
+})
+
+const fixtures = fileURLToPath(new URL('./fixtures/skills', import.meta.url))
+
 const temps: Array<string> = []
 const hosts: Array<HarnessHost> = []
 afterEach(async () => {
@@ -38,25 +51,29 @@ async function addSkill(root: string, name: string, about = name) {
   )
 }
 
+/** An answer of the fake model, or a function that makes it. */
+type Answer = FakeResponse | (() => Promise<FakeResponse>)
+
 /**
- * A session with the skills plugin and `others` after it. The model answers
- * "ok" and keeps each request.
+ * A session with the skills plugin and `others` after it. The model gives
+ * `answers` first and then answers "ok". It keeps each request.
  */
 async function open(
   options: SkillsPluginOptions,
-  others: Array<HarnessPlugin> = [],
+  {
+    others = [],
+    answers = [],
+  }: { others?: Array<HarnessPlugin>; answers?: Array<Answer> } = {},
 ) {
   const requests: Array<TextOptions> = []
   const fake = fakeText()
+  const ok: Answer = { text: 'ok' }
+  const steps = [...answers, ...Array.from({ length: 10 }, () => ok)]
   fake.setResponses(
-    Array.from(
-      { length: 10 },
-      () =>
-        ({ request }: { request: TextOptions }) => {
-          requests.push(request)
-          return { text: 'ok' }
-        },
-    ),
+    steps.map((answer) => async ({ request }: { request: TextOptions }) => {
+      requests.push(request)
+      return typeof answer === 'function' ? answer() : answer
+    }),
   )
   const host = createHarnessHost()
   hosts.push(host)
@@ -79,6 +96,15 @@ async function open(
 const promptOf = (request: TextOptions | undefined) =>
   JSON.stringify(request?.systemPrompts ?? [])
 
+/** The tool result text that a model request gives back to the model. */
+const toolResultOf = (request: TextOptions | undefined) =>
+  String(request?.messages.find((message) => message.role === 'tool')?.content)
+
+/** The model's call of the `load_skill` tool for `name`. */
+const loadSkill = (name: string): FakeResponse => ({
+  toolCalls: [{ name: 'load_skill', input: { name } }],
+})
+
 describe('skills()', () => {
   it('makes a command for each skill, from the first folder that has it', async () => {
     const first = await tempDir()
@@ -118,7 +144,7 @@ describe('skills()', () => {
     })
     const { session, names, list } = await open(
       { dirs: [dir], reserved: ['help'] },
-      [picker],
+      { others: [picker] },
     )
 
     const listed = await list()
@@ -177,6 +203,24 @@ describe('skills()', () => {
     })
   })
 
+  it('watches a folder again after its watcher fails', async () => {
+    const dir = await tempDir()
+    await addSkill(dir, 'alpha')
+    const { names, list } = await open({ dirs: [dir] })
+    await list()
+    const { calls, results } = vi.mocked(watch).mock
+    const watched = results[calls.findIndex(([path]) => path === dir)]
+    if (watched?.type !== 'return') throw new Error(`No watcher for ${dir}`)
+    // For example, Windows fails the watcher of a folder that you delete.
+    watched.value.emit('error', new Error('EPERM'))
+
+    await list()
+    await addSkill(dir, 'gamma')
+    await vi.waitFor(() => expect(names()).toContain('gamma'), {
+      timeout: 5000,
+    })
+  })
+
   it('uses a folder made after the start, from the next turn', async () => {
     const root = await tempDir()
     const later = join(root, 'later')
@@ -223,6 +267,44 @@ describe('skills()', () => {
     expect(promptOf(requests[1])).toContain('zeta')
   })
 
+  it('loads a skill, with its files, from the folder that has it', async () => {
+    const first = await tempDir()
+    await addSkill(first, 'beta')
+    const { session, requests } = await open(
+      { dirs: [first, fixtures] },
+      { answers: [loadSkill('alpha')] },
+    )
+
+    await session.prompt('use alpha')
+    expect(JSON.parse(toolResultOf(requests[1]))).toEqual({
+      skill: 'alpha',
+      content: '# Alpha\n\nDo the alpha thing.',
+      resources: ['references/note.md'],
+      scripts: [
+        { path: 'scripts/run.py', executable: false, reason: 'no-runtime' },
+      ],
+      compatibility: 'any runtime',
+    })
+  })
+
+  it('tells the model when a skill is gone before it loads', async () => {
+    const dir = await tempDir()
+    await addSkill(dir, 'alpha')
+    const removeThenLoad = async () => {
+      await rm(join(dir, 'alpha'), { recursive: true, force: true })
+      return loadSkill('alpha')
+    }
+    const { session, requests } = await open(
+      { dirs: [dir] },
+      { answers: [removeThenLoad] },
+    )
+
+    await session.prompt('use alpha')
+    expect(JSON.parse(toolResultOf(requests[1]))).toEqual({
+      error: `No skill named "alpha" in ${dir}.`,
+    })
+  })
+
   it('stops following the folders when the session closes', async () => {
     const dir = await tempDir()
     await addSkill(dir, 'alpha')

From 5c4f92a94061e9fc647a9c0541f43a3a89be002d Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 14:40:21 +0200
Subject: [PATCH 175/286] feat(ai): add the mid-conversation planner and prompt
 hash

planMidConversationChanges folds the midConversationChange records of a transcript, compares them with the tools and system prompts of the current call, and gives the changes for the adapter and the record to save. promptHash is FNV-1a over a prompt.
---
 packages/ai/src/adapter-internals.ts          |   6 +-
 packages/ai/src/utilities/mid-conversation.ts | 113 +++++++++-
 packages/ai/tests/mid-conversation.test.ts    | 212 +++++++++++++++++-
 3 files changed, 327 insertions(+), 4 deletions(-)

diff --git a/packages/ai/src/adapter-internals.ts b/packages/ai/src/adapter-internals.ts
index c5ecaf478d..04f748f9b6 100644
--- a/packages/ai/src/adapter-internals.ts
+++ b/packages/ai/src/adapter-internals.ts
@@ -75,4 +75,8 @@ export type {
   BlockOrderEntry,
   OrderedAssistantBlock,
 } from './utilities/block-order'
-export { splitMidConversationChanges } from './utilities/mid-conversation'
+export {
+  planMidConversationChanges,
+  promptHash,
+  splitMidConversationChanges,
+} from './utilities/mid-conversation'
diff --git a/packages/ai/src/utilities/mid-conversation.ts b/packages/ai/src/utilities/mid-conversation.ts
index 1517080e0c..8613258074 100644
--- a/packages/ai/src/utilities/mid-conversation.ts
+++ b/packages/ai/src/utilities/mid-conversation.ts
@@ -1,4 +1,115 @@
-import type { MidConversationChanges } from '../types'
+import type {
+  MidConversationChange,
+  MidConversationChanges,
+  ModelMessage,
+} from '../types'
+
+/**
+ * FNV-1a 32-bit over the UTF-16 code units of `content`, as 8 lowercase hex
+ * characters. A short, stable id for one system prompt.
+ */
+export function promptHash(content: string): string {
+  let hash = 0x811c9dc5
+  for (let index = 0; index < content.length; index++) {
+    hash ^= content.charCodeAt(index)
+    hash = Math.imul(hash, 0x01000193)
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0')
+}
+
+export interface MidConversationPlan {
+  changes: MidConversationChanges
+  /** The record to save on the first assistant message of this call, if any. */
+  record?: MidConversationChange
+}
+
+/** The state after the records: the changes, and every recorded name and hash. */
+interface FoldedRecords {
+  changes: MidConversationChanges
+  tools: Array<string>
+  prompts: Array<string>
+}
+
+function foldRecords(
+  messages: ReadonlyArray<ModelMessage>,
+): FoldedRecords | undefined {
+  let folded: FoldedRecords | undefined
+  for (let before = 0; before < messages.length; before++) {
+    const message = messages[before]
+    const record =
+      message?.role === 'assistant' ? message.midConversationChange : undefined
+    if (!record) continue
+    const prompts = record.systemPrompts ?? []
+    if (record.tools) {
+      folded = {
+        changes: {
+          start: { tools: [...record.tools], systemPrompts: prompts.length },
+          changes: [],
+        },
+        tools: [...record.tools],
+        prompts: [...prompts],
+      }
+      continue
+    }
+    // A change before any start point is ignored. Compaction can cause it.
+    if (!folded) continue
+    const added = record.toolsAdded ?? []
+    folded.tools.push(...added)
+    folded.prompts.push(...prompts)
+    folded.changes.changes.push({
+      before,
+      ...(added.length > 0 && { tools: [...added] }),
+      ...(prompts.length > 0 && { systemPrompts: prompts.length }),
+    })
+  }
+  return folded
+}
+
+/**
+ * Fold the records in `messages`, compare them with the tools and prompts of
+ * this call, and decide. A change is additive when every recorded tool is
+ * still there, the prompts start with the recorded prompts, and the start
+ * point has a tool or no tool was added. Anything else is a new start point.
+ * Pure.
+ */
+export function planMidConversationChanges(input: {
+  messages: ReadonlyArray<ModelMessage>
+  toolNames: ReadonlyArray<string>
+  /** The normalized content of each system prompt, in order. */
+  systemPrompts: ReadonlyArray<string>
+}): MidConversationPlan {
+  const tools = [...input.toolNames]
+  const prompts = input.systemPrompts.map((prompt) => promptHash(prompt))
+  const startPoint: MidConversationPlan = {
+    changes: { start: { tools, systemPrompts: prompts.length }, changes: [] },
+    record: { tools: [...tools], systemPrompts: prompts },
+  }
+  const folded = foldRecords(input.messages)
+  if (!folded) return startPoint
+
+  const toolsAdded = tools.filter((name) => !folded.tools.includes(name))
+  const promptsAdded = prompts.slice(folded.prompts.length)
+  const isAdditive =
+    folded.tools.every((name) => tools.includes(name)) &&
+    folded.prompts.every((hash, index) => prompts[index] === hash) &&
+    (folded.changes.start.tools.length > 0 || toolsAdded.length === 0)
+  if (!isAdditive) return startPoint
+  if (toolsAdded.length === 0 && promptsAdded.length === 0) {
+    return { changes: folded.changes }
+  }
+  folded.changes.changes.push({
+    before: input.messages.length,
+    ...(toolsAdded.length > 0 && { tools: toolsAdded }),
+    ...(promptsAdded.length > 0 && { systemPrompts: promptsAdded.length }),
+  })
+  return {
+    changes: folded.changes,
+    record: {
+      ...(toolsAdded.length > 0 && { toolsAdded: [...toolsAdded] }),
+      ...(promptsAdded.length > 0 && { systemPrompts: promptsAdded }),
+    },
+  }
+}
 
 export interface MidConversationRequest<TTool, TPrompt> {
   startTools: Array<TTool>
diff --git a/packages/ai/tests/mid-conversation.test.ts b/packages/ai/tests/mid-conversation.test.ts
index 87052a90ef..ed7c521787 100644
--- a/packages/ai/tests/mid-conversation.test.ts
+++ b/packages/ai/tests/mid-conversation.test.ts
@@ -1,10 +1,214 @@
 import { describe, expect, it } from 'vitest'
-import { splitMidConversationChanges } from '../src/utilities/mid-conversation'
+import {
+  planMidConversationChanges,
+  promptHash,
+  splitMidConversationChanges,
+} from '../src/utilities/mid-conversation'
 import * as adapterInternals from '../src/adapter-internals'
 import * as ai from '../src/index'
-import type { MidConversationChanges } from '../src/types'
+import type {
+  MidConversationChange,
+  MidConversationChanges,
+  ModelMessage,
+} from '../src/types'
 import type { SystemPrompt } from '../src/system-prompts'
 
+const user = (content: string): ModelMessage => ({ role: 'user', content })
+
+/** An assistant message, with `record` as its mid-conversation record. */
+const assistant = (record?: MidConversationChange): ModelMessage => ({
+  role: 'assistant',
+  content: 'ok',
+  ...(record ? { midConversationChange: record } : {}),
+})
+
+const plan = (
+  messages: Array<ModelMessage>,
+  toolNames: Array<string>,
+  systemPrompts: Array<string> = [],
+) => planMidConversationChanges({ messages, toolNames, systemPrompts })
+
+describe('promptHash', () => {
+  it('is FNV-1a 32-bit as 8 hex characters', () => {
+    expect(promptHash('')).toBe('811c9dc5')
+    expect(promptHash('a')).toBe('e40c292c')
+    expect(promptHash('foobar')).toBe('bf9cf968')
+  })
+
+  it('pads a short hash with zeros', () => {
+    expect(promptHash('p426')).toBe('01483fad')
+  })
+})
+
+describe('planMidConversationChanges', () => {
+  it('makes a start point when no assistant message has a record', () => {
+    // A record on a user message is not read.
+    const messages = [{ ...user('q'), midConversationChange: { tools: ['x'] } }]
+
+    expect(plan(messages, ['a', 'b'], ['A'])).toEqual({
+      changes: { start: { tools: ['a', 'b'], systemPrompts: 1 }, changes: [] },
+      record: { tools: ['a', 'b'], systemPrompts: [promptHash('A')] },
+    })
+  })
+
+  it('records an added tool as a change before the next message', () => {
+    const messages = [
+      user('q1'),
+      assistant({ tools: ['a'], systemPrompts: [] }),
+      user('q2'),
+    ]
+
+    expect(plan(messages, ['a', 'b'])).toEqual({
+      changes: {
+        start: { tools: ['a'], systemPrompts: 0 },
+        changes: [{ before: 3, tools: ['b'] }],
+      },
+      record: { toolsAdded: ['b'] },
+    })
+  })
+
+  it('records a prompt added at the end as a change', () => {
+    const messages = [
+      user('q1'),
+      assistant({ tools: ['a'], systemPrompts: [promptHash('A')] }),
+      user('q2'),
+    ]
+
+    expect(plan(messages, ['a'], ['A', 'B'])).toEqual({
+      changes: {
+        start: { tools: ['a'], systemPrompts: 1 },
+        changes: [{ before: 3, systemPrompts: 1 }],
+      },
+      record: { systemPrompts: [promptHash('B')] },
+    })
+  })
+
+  it('keeps the earlier changes and adds no record when nothing was added', () => {
+    const messages = [
+      user('q1'),
+      assistant({ tools: ['a'], systemPrompts: [promptHash('A')] }),
+      user('q2'),
+      assistant({ toolsAdded: ['b'], systemPrompts: [promptHash('B')] }),
+      user('q3'),
+    ]
+
+    const result = plan(messages, ['a', 'b'], ['A', 'B'])
+
+    expect(result.changes).toEqual({
+      start: { tools: ['a'], systemPrompts: 1 },
+      changes: [{ before: 3, tools: ['b'], systemPrompts: 1 }],
+    })
+    expect(result.record).toBeUndefined()
+  })
+
+  it('makes a start point when a recorded tool is gone', () => {
+    const messages = [
+      user('q1'),
+      assistant({ tools: ['a', 'b'], systemPrompts: [] }),
+      user('q2'),
+    ]
+
+    expect(plan(messages, ['a'])).toEqual({
+      changes: { start: { tools: ['a'], systemPrompts: 0 }, changes: [] },
+      record: { tools: ['a'], systemPrompts: [] },
+    })
+  })
+
+  it.each<[string, Array<string>]>([
+    ['edited', ['A2', 'B']],
+    ['reordered', ['B', 'A']],
+    ['removed', ['A']],
+  ])('makes a start point when a recorded prompt is %s', (_label, prompts) => {
+    const messages = [
+      user('q1'),
+      assistant({
+        tools: ['a'],
+        systemPrompts: [promptHash('A'), promptHash('B')],
+      }),
+      user('q2'),
+    ]
+
+    expect(plan(messages, ['a'], prompts)).toEqual({
+      changes: {
+        start: { tools: ['a'], systemPrompts: prompts.length },
+        changes: [],
+      },
+      record: {
+        tools: ['a'],
+        systemPrompts: prompts.map((prompt) => promptHash(prompt)),
+      },
+    })
+  })
+
+  it('makes a start point for the first tools after a start point with no tools', () => {
+    const messages = [
+      user('q1'),
+      assistant({ tools: [], systemPrompts: [] }),
+      user('q2'),
+    ]
+
+    expect(plan(messages, ['a'])).toEqual({
+      changes: { start: { tools: ['a'], systemPrompts: 0 }, changes: [] },
+      record: { tools: ['a'], systemPrompts: [] },
+    })
+  })
+
+  it('adds a prompt to a start point with no tools', () => {
+    const messages = [
+      user('q1'),
+      assistant({ tools: [], systemPrompts: [promptHash('A')] }),
+      user('q2'),
+    ]
+
+    expect(plan(messages, [], ['A', 'B'])).toEqual({
+      changes: {
+        start: { tools: [], systemPrompts: 1 },
+        changes: [{ before: 3, systemPrompts: 1 }],
+      },
+      record: { systemPrompts: [promptHash('B')] },
+    })
+  })
+
+  it('ignores a change before any start point', () => {
+    const messages = [
+      assistant({ toolsAdded: ['x'] }),
+      user('q1'),
+      assistant({ tools: ['a'], systemPrompts: [] }),
+      user('q2'),
+    ]
+
+    expect(plan(messages, ['a'])).toEqual({
+      changes: { start: { tools: ['a'], systemPrompts: 0 }, changes: [] },
+    })
+  })
+
+  it('makes a start point when the only record is a change', () => {
+    // Compaction can drop the start point and keep a later change.
+    const messages = [assistant({ toolsAdded: ['b'] }), user('q')]
+
+    expect(plan(messages, ['a', 'b'])).toEqual({
+      changes: { start: { tools: ['a', 'b'], systemPrompts: 0 }, changes: [] },
+      record: { tools: ['a', 'b'], systemPrompts: [] },
+    })
+  })
+
+  it('starts the changes again at a later start point', () => {
+    const messages = [
+      user('q1'),
+      assistant({ tools: ['a'], systemPrompts: [] }),
+      user('q2'),
+      assistant({ toolsAdded: ['b'] }),
+      user('q3'),
+      assistant({ tools: ['a', 'b'], systemPrompts: [] }),
+      user('q4'),
+    ]
+
+    expect(plan(messages, ['a', 'b'])).toEqual({
+      changes: { start: { tools: ['a', 'b'], systemPrompts: 0 }, changes: [] },
+    })
+  })
+})
+
 describe('splitMidConversationChanges', () => {
   const a = { name: 'a' }
   const b = { name: 'b' }
@@ -121,6 +325,10 @@ describe('splitMidConversationChanges', () => {
 
 describe('mid-conversation exports', () => {
   it('gives adapter authors the helpers', () => {
+    expect(adapterInternals.promptHash).toBe(promptHash)
+    expect(adapterInternals.planMidConversationChanges).toBe(
+      planMidConversationChanges,
+    )
     expect(adapterInternals.splitMidConversationChanges).toBe(
       splitMidConversationChanges,
     )

From 216faf4b0f6cb33dee4dcaeefe3cb779426936e5 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 14:40:22 +0200
Subject: [PATCH 176/286] feat(ai-anthropic): replay assistant blocks in their
 block order

With a valid blockOrder map, formatMessages sends the thinking, text, tool_use, and server tool blocks in the order Claude sent them. Unsigned thinking is still skipped at its place. A message without a valid map sends the same request as before.
---
 packages/ai-anthropic/src/adapters/text.ts    | 102 ++++--
 .../tests/thinking-replay.test.ts             | 324 ++++++++++++++++++
 2 files changed, 390 insertions(+), 36 deletions(-)

diff --git a/packages/ai-anthropic/src/adapters/text.ts b/packages/ai-anthropic/src/adapters/text.ts
index db59f8efbb..29288f2065 100644
--- a/packages/ai-anthropic/src/adapters/text.ts
+++ b/packages/ai-anthropic/src/adapters/text.ts
@@ -6,6 +6,7 @@ import {
 } from '@tanstack/ai'
 import {
   REDACTED_THINKING_ID_PREFIX,
+  orderedAssistantBlocks,
   toRunErrorRawEvent,
 } from '@tanstack/ai/adapter-internals'
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
@@ -71,6 +72,7 @@ import type {
   ModelMessage,
   AdapterYieldChunk,
   TextOptions,
+  ToolCall,
 } from '@tanstack/ai'
 import type {
   AnthropicSystemPromptMetadata,
@@ -861,6 +863,28 @@ export class AnthropicTextAdapter<
         continue
       }
 
+      // A valid block order map: send the blocks in the order the model
+      // sent them. Unsigned thinking is still skipped at its place.
+      const ordered =
+        role === 'assistant' ? orderedAssistantBlocks(message) : undefined
+      if (ordered) {
+        const contentBlocks: Array<BetaContentBlockParam> = []
+        for (const block of ordered) {
+          if (block.type === 'thinking') {
+            this.appendThinkingBlocks(contentBlocks, [block.thinking])
+          } else if (block.type === 'tool-call') {
+            this.appendToolCallBlocks(contentBlocks, block.toolCall)
+          } else {
+            contentBlocks.push({ type: 'text', text: block.text })
+          }
+        }
+        formattedMessages.push({
+          role: 'assistant',
+          content: contentBlocks.length > 0 ? contentBlocks : '',
+        })
+        continue
+      }
+
       if (role === 'assistant' && message.toolCalls?.length) {
         const contentBlocks: Array<BetaContentBlockParam> = []
 
@@ -877,42 +901,7 @@ export class AnthropicTextAdapter<
         }
 
         for (const toolCall of message.toolCalls) {
-          let parsedInput: unknown = {}
-          try {
-            const parsed = toolCall.function.arguments
-              ? JSON.parse(toolCall.function.arguments)
-              : {}
-            parsedInput = parsed && typeof parsed === 'object' ? parsed : {}
-          } catch {
-            parsedInput = toolCall.function.arguments
-          }
-
-          // Provider-executed server tools (e.g. web_search) replay as the
-          // original `server_tool_use` + result blocks so the model still sees
-          // the prior evidence. Their result was captured verbatim during
-          // streaming (see processAnthropicStream).
-          const serverMeta = readAnthropicServerToolMetadata(toolCall.metadata)
-          if (serverMeta) {
-            const serverToolUseBlock: ServerToolUseBlockParam = {
-              type: 'server_tool_use',
-              id: toolCall.id,
-              name: serverMeta.serverToolType,
-              input: parsedInput,
-            }
-            contentBlocks.push(serverToolUseBlock)
-            contentBlocks.push(
-              buildServerToolResultBlock(toolCall.id, serverMeta),
-            )
-            continue
-          }
-
-          const toolUseBlock: ToolUseBlockParam = {
-            type: 'tool_use',
-            id: toolCall.id,
-            name: toolCall.function.name,
-            input: parsedInput,
-          }
-          contentBlocks.push(toolUseBlock)
+          this.appendToolCallBlocks(contentBlocks, toolCall)
         }
 
         formattedMessages.push({
@@ -999,6 +988,47 @@ export class AnthropicTextAdapter<
     }
   }
 
+  /** A tool call as a `tool_use` block, or a server tool as its two blocks. */
+  private appendToolCallBlocks(
+    contentBlocks: Array<BetaContentBlockParam>,
+    toolCall: ToolCall,
+  ): void {
+    let parsedInput: unknown = {}
+    try {
+      const parsed = toolCall.function.arguments
+        ? JSON.parse(toolCall.function.arguments)
+        : {}
+      parsedInput = parsed && typeof parsed === 'object' ? parsed : {}
+    } catch {
+      parsedInput = toolCall.function.arguments
+    }
+
+    // Provider-executed server tools (e.g. web_search) replay as the
+    // original `server_tool_use` + result blocks so the model still sees
+    // the prior evidence. Their result was captured verbatim during
+    // streaming (see processAnthropicStream).
+    const serverMeta = readAnthropicServerToolMetadata(toolCall.metadata)
+    if (serverMeta) {
+      const serverToolUseBlock: ServerToolUseBlockParam = {
+        type: 'server_tool_use',
+        id: toolCall.id,
+        name: serverMeta.serverToolType,
+        input: parsedInput,
+      }
+      contentBlocks.push(serverToolUseBlock)
+      contentBlocks.push(buildServerToolResultBlock(toolCall.id, serverMeta))
+      return
+    }
+
+    const toolUseBlock: ToolUseBlockParam = {
+      type: 'tool_use',
+      id: toolCall.id,
+      name: toolCall.function.name,
+      input: parsedInput,
+    }
+    contentBlocks.push(toolUseBlock)
+  }
+
   /**
    * Merge consecutive messages of the same role into a single message.
    * Anthropic's API requires strictly alternating user/assistant roles.
diff --git a/packages/ai-anthropic/tests/thinking-replay.test.ts b/packages/ai-anthropic/tests/thinking-replay.test.ts
index 282e5b5a6e..c04f8e1eea 100644
--- a/packages/ai-anthropic/tests/thinking-replay.test.ts
+++ b/packages/ai-anthropic/tests/thinking-replay.test.ts
@@ -77,6 +77,78 @@ function end(stopReason: string) {
   ]
 }
 
+/** The raw events of one signed thinking block. */
+function thinkingEvents(index: number, thinking: string, signature: string) {
+  return [
+    {
+      type: 'content_block_start',
+      index,
+      content_block: { type: 'thinking', thinking: '' },
+    },
+    {
+      type: 'content_block_delta',
+      index,
+      delta: { type: 'thinking_delta', thinking },
+    },
+    {
+      type: 'content_block_delta',
+      index,
+      delta: { type: 'signature_delta', signature },
+    },
+    { type: 'content_block_stop', index },
+  ]
+}
+
+/** The raw events of one `lookup_weather` tool_use block. */
+function toolUseEvents(index: number, id: string, location: string) {
+  return [
+    {
+      type: 'content_block_start',
+      index,
+      content_block: {
+        type: 'tool_use',
+        id,
+        name: 'lookup_weather',
+        input: {},
+      },
+    },
+    {
+      type: 'content_block_delta',
+      index,
+      delta: {
+        type: 'input_json_delta',
+        partial_json: JSON.stringify({ location }),
+      },
+    },
+    { type: 'content_block_stop', index },
+  ]
+}
+
+/** A `lookup_weather` tool call of a ModelMessage. */
+const weatherCall = (id: string, location: string) => ({
+  id,
+  type: 'function' as const,
+  function: {
+    name: 'lookup_weather',
+    arguments: JSON.stringify({ location }),
+  },
+})
+
+/** The replayed tool_use block of `weatherCall(id, location)`. */
+const toolUse = (id: string, location: string) => ({
+  type: 'tool_use',
+  id,
+  name: 'lookup_weather',
+  input: { location },
+})
+
+/** A replayed signed thinking block. */
+const signed = (thinking: string, signature: string) => ({
+  type: 'thinking',
+  thinking,
+  signature,
+})
+
 /** The content blocks of the last assistant message in a request. */
 function assistantBlocks(call: number) {
   const [payload] = mocks.betaMessagesCreate.mock.calls[call]!
@@ -270,3 +342,255 @@ describe('Anthropic replay', () => {
     ])
   })
 })
+
+describe('Anthropic replay block order', () => {
+  beforeEach(() => {
+    mocks.betaMessagesCreate.mockReset()
+  })
+
+  it('sends thinking, tool_use, thinking, tool_use back in that order', async () => {
+    mocks.betaMessagesCreate
+      .mockResolvedValueOnce(
+        stream([
+          ...thinkingEvents(0, 'Check Berlin first.', 'sig-1'),
+          ...toolUseEvents(1, 'call-1', 'Berlin'),
+          ...thinkingEvents(2, 'Now Paris.', 'sig-2'),
+          ...toolUseEvents(3, 'call-2', 'Paris'),
+          ...end('tool_use'),
+        ]),
+      )
+      .mockResolvedValueOnce(
+        stream([...textEvents(0, 'Both are sunny.'), ...end('end_turn')]),
+      )
+
+    await drain(
+      chat({
+        adapter: adapter(),
+        messages: [{ role: 'user', content: 'Weather in Berlin and Paris?' }],
+        tools: [weather],
+      }),
+    )
+
+    expect(mocks.betaMessagesCreate).toHaveBeenCalledTimes(2)
+    expect(assistantBlocks(1)).toEqual([
+      signed('Check Berlin first.', 'sig-1'),
+      toolUse('call-1', 'Berlin'),
+      signed('Now Paris.', 'sig-2'),
+      toolUse('call-2', 'Paris'),
+    ])
+    // The automatic cache marker (promptCache defaults to 'short') still
+    // lands on the last block of the last user message.
+    const [payload] = mocks.betaMessagesCreate.mock.calls[1]!
+    expect(payload.messages.at(-1).content.at(-1)).toMatchObject({
+      type: 'tool_result',
+      cache_control: { type: 'ephemeral' },
+    })
+  })
+
+  it('keeps an emoji whole when thinking splits the text', async () => {
+    mocks.betaMessagesCreate
+      .mockResolvedValueOnce(
+        stream([
+          ...thinkingEvents(0, 'Think A.', 'sig-a'),
+          ...textEvents(1, 'Done 👍'),
+          ...thinkingEvents(2, 'Think B.', 'sig-b'),
+          ...textEvents(3, '👋 Bye'),
+          ...toolUseEvents(4, 'call-1', 'Berlin'),
+          ...end('tool_use'),
+        ]),
+      )
+      .mockResolvedValueOnce(
+        stream([...textEvents(0, 'Sunny.'), ...end('end_turn')]),
+      )
+
+    await drain(
+      chat({
+        adapter: adapter(),
+        messages: [{ role: 'user', content: 'Weather in Berlin?' }],
+        tools: [weather],
+      }),
+    )
+
+    // Text lengths count UTF-16 code units, so each emoji stays whole.
+    expect(assistantBlocks(1)).toEqual([
+      signed('Think A.', 'sig-a'),
+      { type: 'text', text: 'Done 👍' },
+      signed('Think B.', 'sig-b'),
+      { type: 'text', text: '👋 Bye' },
+      toolUse('call-1', 'Berlin'),
+    ])
+  })
+
+  it('sends thinking, text, thinking, text back in that order', async () => {
+    mocks.betaMessagesCreate.mockResolvedValueOnce(
+      stream([...textEvents(0, 'Next.'), ...end('end_turn')]),
+    )
+    const messages: Array<ModelMessage> = [
+      { role: 'user', content: 'Think twice.' },
+      {
+        role: 'assistant',
+        content: 'First.Second.',
+        thinking: [
+          { content: 'Think A.', signature: 'sig-a' },
+          { content: 'Think B.', signature: 'sig-b' },
+        ],
+        blockOrder: [
+          { type: 'thinking', index: 0 },
+          { type: 'text', length: 'First.'.length },
+          { type: 'thinking', index: 1 },
+          { type: 'text', length: 'Second.'.length },
+        ],
+      },
+      { role: 'user', content: 'Go on.' },
+    ]
+
+    await drain(chat({ adapter: adapter(), messages }))
+
+    expect(assistantBlocks(0)).toEqual([
+      signed('Think A.', 'sig-a'),
+      { type: 'text', text: 'First.' },
+      signed('Think B.', 'sig-b'),
+      { type: 'text', text: 'Second.' },
+    ])
+  })
+
+  it('skips unsigned thinking at its place and keeps the rest of the order', async () => {
+    mocks.betaMessagesCreate.mockResolvedValueOnce(
+      stream([...textEvents(0, 'Next.'), ...end('end_turn')]),
+    )
+    const messages: Array<ModelMessage> = [
+      { role: 'user', content: 'Weather in three cities?' },
+      {
+        role: 'assistant',
+        content: null,
+        thinking: [
+          { content: 'Check Berlin first.', signature: 'sig-1' },
+          // Another model wrote this one. It has no signature.
+          { content: 'Unsigned note.' },
+          { content: 'Then Rome.', signature: 'sig-3' },
+        ],
+        toolCalls: [
+          weatherCall('call-1', 'Berlin'),
+          weatherCall('call-2', 'Paris'),
+          weatherCall('call-3', 'Rome'),
+        ],
+        blockOrder: [
+          { type: 'thinking', index: 0 },
+          { type: 'tool-call', id: 'call-1' },
+          { type: 'thinking', index: 1 },
+          { type: 'tool-call', id: 'call-2' },
+          { type: 'thinking', index: 2 },
+          { type: 'tool-call', id: 'call-3' },
+        ],
+      },
+      { role: 'tool', toolCallId: 'call-1', content: 'sunny' },
+      { role: 'tool', toolCallId: 'call-2', content: 'rainy' },
+      { role: 'tool', toolCallId: 'call-3', content: 'windy' },
+    ]
+
+    await drain(chat({ adapter: adapter(), messages, tools: [weather] }))
+
+    expect(assistantBlocks(0)).toEqual([
+      signed('Check Berlin first.', 'sig-1'),
+      toolUse('call-1', 'Berlin'),
+      toolUse('call-2', 'Paris'),
+      signed('Then Rome.', 'sig-3'),
+      toolUse('call-3', 'Rome'),
+    ])
+  })
+
+  it("keeps today's order when the map does not fit the message", async () => {
+    mocks.betaMessagesCreate.mockResolvedValueOnce(
+      stream([...textEvents(0, 'Next.'), ...end('end_turn')]),
+    )
+    const messages: Array<ModelMessage> = [
+      { role: 'user', content: 'Weather in Berlin and Paris?' },
+      {
+        role: 'assistant',
+        content: null,
+        thinking: [
+          { content: 'Check Berlin first.', signature: 'sig-1' },
+          { content: 'Now Paris.', signature: 'sig-2' },
+        ],
+        toolCalls: [
+          weatherCall('call-1', 'Berlin'),
+          weatherCall('call-2', 'Paris'),
+        ],
+        // call-3 is not a tool call of this message, and call-2 is missing.
+        blockOrder: [
+          { type: 'thinking', index: 0 },
+          { type: 'tool-call', id: 'call-1' },
+          { type: 'thinking', index: 1 },
+          { type: 'tool-call', id: 'call-3' },
+        ],
+      },
+      { role: 'tool', toolCallId: 'call-1', content: 'sunny' },
+      { role: 'tool', toolCallId: 'call-2', content: 'rainy' },
+    ]
+
+    await drain(chat({ adapter: adapter(), messages, tools: [weather] }))
+
+    expect(assistantBlocks(0)).toEqual([
+      signed('Check Berlin first.', 'sig-1'),
+      signed('Now Paris.', 'sig-2'),
+      toolUse('call-1', 'Berlin'),
+      toolUse('call-2', 'Paris'),
+    ])
+  })
+
+  it('sends a message in the default order exactly as before', async () => {
+    mocks.betaMessagesCreate
+      .mockResolvedValueOnce(
+        stream([...textEvents(0, 'Next.'), ...end('end_turn')]),
+      )
+      .mockResolvedValueOnce(
+        stream([...textEvents(0, 'Next.'), ...end('end_turn')]),
+      )
+    const answer: ModelMessage = {
+      role: 'assistant',
+      content: 'Let me check.',
+      thinking: [{ content: 'Check Berlin.', signature: 'sig-1' }],
+      toolCalls: [weatherCall('call-1', 'Berlin')],
+    }
+    const history = (assistant: ModelMessage): Array<ModelMessage> => [
+      { role: 'user', content: 'Weather in Berlin?' },
+      assistant,
+      { role: 'tool', toolCallId: 'call-1', content: 'sunny' },
+    ]
+
+    await drain(
+      chat({ adapter: adapter(), messages: history(answer), tools: [weather] }),
+    )
+    await drain(
+      chat({
+        adapter: adapter(),
+        messages: history({
+          ...answer,
+          // The writers never set a map for the default order. A reader
+          // must still send the same request for one.
+          blockOrder: [
+            { type: 'thinking', index: 0 },
+            { type: 'text', length: 'Let me check.'.length },
+            { type: 'tool-call', id: 'call-1' },
+          ],
+        }),
+        tools: [weather],
+      }),
+    )
+
+    const [today] = mocks.betaMessagesCreate.mock.calls[0]!
+    const [withMap] = mocks.betaMessagesCreate.mock.calls[1]!
+    expect(today.messages[1].content).toEqual([
+      signed('Check Berlin.', 'sig-1'),
+      { type: 'text', text: 'Let me check.' },
+      toolUse('call-1', 'Berlin'),
+    ])
+    // Both requests have the default automatic markers, in the same places.
+    expect(today.messages.at(-1).content.at(-1)).toMatchObject({
+      type: 'tool_result',
+      tool_use_id: 'call-1',
+      cache_control: { type: 'ephemeral' },
+    })
+    expect(JSON.stringify(withMap)).toBe(JSON.stringify(today))
+  })
+})

From d67e2f0426803d3359d836aa0964a8bb0fd6d391 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 14:58:56 +0200
Subject: [PATCH 177/286] feat(openai-base): send mid-conversation changes in
 Responses requests

When the adapter has channels and the engine passes midConversationChanges, tools keeps the start set, an added tool goes out as an additional_tools item, and an added prompt goes out as a developer message at its place. A provider tool keeps the full tools list. A subclass can override convertTools to use its own tool converter. An adapter without channels sends the same request as before.
---
 .../src/adapters/responses-text.ts            |  89 ++++++-
 .../tests/responses-mid-conversation.test.ts  | 227 ++++++++++++++++++
 2 files changed, 309 insertions(+), 7 deletions(-)
 create mode 100644 packages/openai-base/tests/responses-mid-conversation.test.ts

diff --git a/packages/openai-base/src/adapters/responses-text.ts b/packages/openai-base/src/adapters/responses-text.ts
index 8bf95dbfb7..3f92514a8d 100644
--- a/packages/openai-base/src/adapters/responses-text.ts
+++ b/packages/openai-base/src/adapters/responses-text.ts
@@ -8,6 +8,7 @@ import {
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
 import {
   resolveReasoning,
+  splitMidConversationChanges,
   toRunErrorPayload,
   toRunErrorRawEvent,
 } from '@tanstack/ai/adapter-internals'
@@ -23,6 +24,7 @@ import type {
   StructuredOutputCompatibility,
 } from '../utils/schema-converter'
 import { buildResponsesUsage } from '../usage'
+import { getOpenAIProviderToolKind } from '../tools/openai-provider-tool'
 import { convertToolsToResponsesFormat } from './responses-tool-converter'
 import {
   hostedShellCallIds,
@@ -46,6 +48,7 @@ import type {
   ResponseOutputMessage,
   ResponseOutputText,
   ResponseStreamEvent,
+  Tool as ResponsesTool,
 } from 'openai/resources/responses/responses'
 import type {
   ContentPart,
@@ -58,6 +61,8 @@ import type {
   ProviderExecutedToolSource,
   ReasoningCapability,
   TextOptions,
+  AnyTool,
+  NormalizedSystemPrompt,
 } from '@tanstack/ai'
 
 // Base64 encoding of the '%PDF' file header — every PDF payload starts with
@@ -2169,16 +2174,14 @@ export abstract class OpenAIBaseResponsesTextAdapter<
   protected mapOptionsToRequest(
     options: TextOptions<TProviderOptions>,
   ): Omit<ResponseCreateParams, 'stream'> {
-    const input = this.convertMessagesToInput(options.messages)
+    const mid = this.midConversationRequest(options)
+    const input = this.convertMessagesToInput(options.messages, mid?.items)
 
     if (this.strictFallbackWarning) {
       warnStrictFallback(options.tools, options.logger)
     }
     const tools = options.tools
-      ? convertToolsToResponsesFormat(
-          options.tools,
-          this.makeStructuredOutputCompatible.bind(this),
-        )
+      ? this.convertTools(mid?.tools ?? options.tools)
       : undefined
 
     const modelOptions = options.modelOptions
@@ -2221,7 +2224,8 @@ export abstract class OpenAIBaseResponsesTextAdapter<
       model: options.model,
       ...(options.metadata !== undefined && { metadata: options.metadata }),
       ...(() => {
-        const prompts = normalizeSystemPrompts(options.systemPrompts)
+        const prompts =
+          mid?.systemPrompts ?? normalizeSystemPrompts(options.systemPrompts)
         if (prompts.length === 0) return {}
         return { instructions: prompts.map((p) => p.content).join('\n') }
       })(),
@@ -2251,6 +2255,73 @@ export abstract class OpenAIBaseResponsesTextAdapter<
     return params
   }
 
+  /**
+   * Converts the tools for the request. A subclass with its own tool
+   * converter overrides this, so the start set and the `additional_tools`
+   * items of a mid-conversation change use that converter too.
+   */
+  protected convertTools(tools: Array<AnyTool>): Array<ResponsesTool> {
+    return convertToolsToResponsesFormat(
+      tools,
+      this.makeStructuredOutputCompatible.bind(this),
+    )
+  }
+
+  /**
+   * Mid-conversation changes: the start tools for `tools`, the start prompts
+   * for `instructions`, and the input items of each change by message index.
+   * Undefined when the request stays as today: the adapter has no channels,
+   * the engine passed no changes, or the changes do not fit the current lists.
+   */
+  private midConversationRequest(options: TextOptions<TProviderOptions>):
+    | {
+        tools?: Array<AnyTool>
+        systemPrompts?: Array<NormalizedSystemPrompt>
+        items: Map<number, ResponseInput>
+      }
+    | undefined {
+    const channels = this.midConversationChannels
+    if (!channels || !options.midConversationChanges) return undefined
+    const split = splitMidConversationChanges({
+      changes: options.midConversationChanges,
+      tools: options.tools ?? [],
+      systemPrompts: normalizeSystemPrompts(options.systemPrompts),
+    })
+    if (!split) return undefined
+    // A provider tool (web search, MCP, ...) cannot go in `additional_tools`,
+    // so its request keeps the full `tools` list.
+    const toolChannel =
+      channels.tools &&
+      ![...split.startTools, ...split.addedTools].some(
+        (tool) => getOpenAIProviderToolKind(tool) !== undefined,
+      )
+    const items = new Map<number, ResponseInput>()
+    for (const [before, change] of split.at) {
+      const changeItems: ResponseInput = []
+      if (toolChannel && change.tools.length > 0) {
+        changeItems.push({
+          type: 'additional_tools',
+          role: 'developer',
+          tools: this.convertTools(change.tools),
+        })
+      }
+      if (channels.systemPrompts && change.systemPrompts.length > 0) {
+        changeItems.push({
+          role: 'developer',
+          content: change.systemPrompts.map((p) => p.content).join('\n'),
+        })
+      }
+      if (changeItems.length > 0) items.set(before, changeItems)
+    }
+    return {
+      ...(toolChannel && { tools: split.startTools }),
+      ...(channels.systemPrompts && {
+        systemPrompts: split.startSystemPrompts,
+      }),
+      items,
+    }
+  }
+
   /**
    * The OpenAI Responses API supports `tools` and `text.format: json_schema`
    * together in a single streaming request (per issue #605). Subclasses
@@ -2272,6 +2343,8 @@ export abstract class OpenAIBaseResponsesTextAdapter<
    */
   protected convertMessagesToInput(
     messages: Array<ModelMessage>,
+    /** Items to send directly before `messages[index]`, or at the end. */
+    insertBefore?: ReadonlyMap<number, ResponseInput>,
   ): ResponseInput {
     const result: ResponseInput = []
     // A reasoning item id may only appear once in `input`; replaying the same
@@ -2288,7 +2361,8 @@ export abstract class OpenAIBaseResponsesTextAdapter<
       }
     >()
 
-    for (const message of messages) {
+    for (const [index, message] of messages.entries()) {
+      result.push(...(insertBefore?.get(index) ?? []))
       // Handle tool messages - convert to FunctionToolCallOutput
       if (message.role === 'tool') {
         const owner = message.toolCallId
@@ -2463,6 +2537,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
       })
     }
 
+    result.push(...(insertBefore?.get(messages.length) ?? []))
     return result
   }
 
diff --git a/packages/openai-base/tests/responses-mid-conversation.test.ts b/packages/openai-base/tests/responses-mid-conversation.test.ts
new file mode 100644
index 0000000000..530f3e0abb
--- /dev/null
+++ b/packages/openai-base/tests/responses-mid-conversation.test.ts
@@ -0,0 +1,227 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { OpenAIBaseResponsesTextAdapter } from '../src/adapters/responses-text'
+import { webSearchTool } from '../src/tools/web-search-tool'
+import type OpenAI from 'openai'
+import type {
+  MidConversationChanges,
+  MidConversationChannels,
+  ModelMessage,
+  TextOptions,
+  Tool,
+} from '@tanstack/ai'
+
+const logger = resolveDebugOption(false)
+
+const create = vi.fn<(...args: Array<any>) => any>()
+
+/** A Responses adapter with the channels that a test picks. */
+class ChannelAdapter extends OpenAIBaseResponsesTextAdapter<string> {
+  override readonly midConversationChannels:
+    | MidConversationChannels
+    | undefined = undefined
+
+  constructor(channels: MidConversationChannels | undefined) {
+    super('test-model', 'openai-base-responses', {
+      responses: { create },
+    } as unknown as OpenAI)
+    this.midConversationChannels = channels
+  }
+}
+
+/** A Responses stream that completes at once. */
+function completedStream() {
+  return (async function* () {
+    yield {
+      type: 'response.created',
+      response: { id: 'resp-1', model: 'test-model', status: 'in_progress' },
+    }
+    yield {
+      type: 'response.completed',
+      response: {
+        id: 'resp-1',
+        model: 'test-model',
+        status: 'completed',
+        output: [],
+        usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
+      },
+    }
+  })()
+}
+
+/** Run one call and give back the request body that the client got. */
+async function send(
+  adapter: ChannelAdapter,
+  options: Pick<
+    TextOptions,
+    'messages' | 'tools' | 'systemPrompts' | 'midConversationChanges'
+  >,
+) {
+  create.mockClear()
+  for await (const chunk of adapter.chatStream({
+    logger,
+    model: 'test-model',
+    ...options,
+  })) {
+    if (chunk.type === 'RUN_ERROR') throw new Error(chunk.message)
+  }
+  return create.mock.calls[0]![0]
+}
+
+const both: MidConversationChannels = { tools: true, systemPrompts: true }
+const lookup: Tool = { name: 'lookup', description: 'Look a thing up' }
+const fetchPage: Tool = { name: 'fetch_page', description: 'Fetch a page' }
+const names = (tools: Array<{ name: string }>) => tools.map((tool) => tool.name)
+
+/** A user turn, an answer that called `lookup`, and the tool result. */
+const toolTurn: Array<ModelMessage> = [
+  { role: 'user', content: 'Find the page' },
+  {
+    role: 'assistant',
+    content: null,
+    toolCalls: [
+      {
+        id: 'call-1',
+        type: 'function',
+        function: { name: 'lookup', arguments: '{}' },
+      },
+    ],
+  },
+  { role: 'tool', toolCallId: 'call-1', content: 'https://example.com' },
+]
+
+/** After the tool result, `fetch_page` and a second prompt came. */
+const endChange: MidConversationChanges = {
+  start: { tools: ['lookup'], systemPrompts: 1 },
+  changes: [{ before: 3, tools: ['fetch_page'], systemPrompts: 1 }],
+}
+
+describe('Responses mid-conversation changes', () => {
+  beforeEach(() => {
+    create.mockReset()
+    create.mockImplementation(() => Promise.resolve(completedStream()))
+  })
+
+  it('sends added tools as additional_tools and keeps the start set in tools', async () => {
+    const body = await send(new ChannelAdapter(both), {
+      messages: toolTurn,
+      tools: [lookup, fetchPage],
+      systemPrompts: ['Be brief.', 'Cite sources.'],
+      midConversationChanges: endChange,
+    })
+
+    expect(names(body.tools)).toEqual(['lookup'])
+    expect(body.instructions).toBe('Be brief.')
+    expect(body.input).toHaveLength(5)
+    expect(body.input.slice(3)).toEqual([
+      {
+        type: 'additional_tools',
+        role: 'developer',
+        tools: [
+          expect.objectContaining({ type: 'function', name: 'fetch_page' }),
+        ],
+      },
+      { role: 'developer', content: 'Cite sources.' },
+    ])
+  })
+
+  it('sends added prompts as one developer message at their place', async () => {
+    const body = await send(new ChannelAdapter(both), {
+      messages: [
+        ...toolTurn,
+        { role: 'assistant', content: 'Here it is.' },
+        { role: 'user', content: 'Thanks' },
+      ],
+      tools: [lookup],
+      systemPrompts: ['Be brief.', 'Cite sources.', 'Use short words.'],
+      midConversationChanges: {
+        start: { tools: ['lookup'], systemPrompts: 1 },
+        changes: [{ before: 3, systemPrompts: 2 }],
+      },
+    })
+
+    expect(body.instructions).toBe('Be brief.')
+    expect(body.input).toHaveLength(6)
+    expect(body.input[3]).toEqual({
+      role: 'developer',
+      content: 'Cite sources.\nUse short words.',
+    })
+    expect(body.input[4]).toMatchObject({
+      type: 'message',
+      role: 'assistant',
+      content: 'Here it is.',
+    })
+  })
+
+  it('falls back to the full tools list when a provider tool takes part', async () => {
+    const body = await send(new ChannelAdapter(both), {
+      messages: toolTurn,
+      tools: [lookup, webSearchTool({ type: 'web_search' }), fetchPage],
+      systemPrompts: ['Be brief.', 'Cite sources.'],
+      midConversationChanges: {
+        start: { tools: ['lookup', 'web_search'], systemPrompts: 1 },
+        changes: [{ before: 3, tools: ['fetch_page'], systemPrompts: 1 }],
+      },
+    })
+
+    expect(names(body.tools)).toEqual(['lookup', 'web_search', 'fetch_page'])
+    // No additional_tools item. The prompt channel still works.
+    expect(body.input.slice(3)).toEqual([
+      { role: 'developer', content: 'Cite sources.' },
+    ])
+  })
+
+  it('sends the full tools list when the tool channel is off', async () => {
+    const body = await send(
+      new ChannelAdapter({ tools: false, systemPrompts: true }),
+      {
+        messages: toolTurn,
+        tools: [lookup, fetchPage],
+        systemPrompts: ['Be brief.', 'Cite sources.'],
+        midConversationChanges: endChange,
+      },
+    )
+
+    expect(names(body.tools)).toEqual(['lookup', 'fetch_page'])
+    expect(body.input.slice(3)).toEqual([
+      { role: 'developer', content: 'Cite sources.' },
+    ])
+  })
+
+  it("sends today's request without channels or without changes", async () => {
+    const options = {
+      messages: toolTurn,
+      tools: [lookup, fetchPage],
+      systemPrompts: ['Be brief.', 'Cite sources.'],
+    }
+    const today = await send(new ChannelAdapter(undefined), options)
+    const noChannels = await send(new ChannelAdapter(undefined), {
+      ...options,
+      midConversationChanges: endChange,
+    })
+    const noChanges = await send(new ChannelAdapter(both), options)
+
+    expect(names(today.tools)).toEqual(['lookup', 'fetch_page'])
+    expect(today.instructions).toBe('Be brief.\nCite sources.')
+    expect(JSON.stringify(noChannels)).toBe(JSON.stringify(today))
+    expect(JSON.stringify(noChanges)).toBe(JSON.stringify(today))
+  })
+
+  it("sends today's request when a change names a tool that is not there", async () => {
+    const options = {
+      messages: toolTurn,
+      tools: [lookup],
+      systemPrompts: ['Be brief.'],
+    }
+    const today = await send(new ChannelAdapter(both), options)
+    const body = await send(new ChannelAdapter(both), {
+      ...options,
+      midConversationChanges: {
+        start: { tools: ['gone_tool'], systemPrompts: 1 },
+        changes: [],
+      },
+    })
+
+    expect(JSON.stringify(body)).toBe(JSON.stringify(today))
+  })
+})

From ddc0b2c15c272f837e0708d9e1bd2531813f3641 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 15:03:25 +0200
Subject: [PATCH 178/286] feat(ai): send and save mid-conversation changes in
 chat()

For an adapter with mid-conversation channels, chat() compares the tools and system prompts of each model call with the records in the transcript, passes the change as TextOptions.midConversationChanges, and saves the record on the first assistant message of the call. An adapter without channels gets the same options as before, and no record is written.
---
 packages/ai/src/activities/chat/index.ts      |  52 +++
 .../ai/tests/chat-mid-conversation.test.ts    | 339 ++++++++++++++++++
 2 files changed, 391 insertions(+)
 create mode 100644 packages/ai/tests/chat-mid-conversation.test.ts

diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index 2d1a920a71..84890789ae 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -54,6 +54,8 @@ import { isProviderExecutedToolCall } from '../../utilities/provider-executed'
 import { buildBlockOrder } from '../../utilities/block-order'
 import type { BlockOrderEntry } from '../../utilities/block-order'
 import { assertMessagesFileSourceSupport } from '../../utilities/content-source'
+import { planMidConversationChanges } from '../../utilities/mid-conversation'
+import { normalizeSystemPrompts } from '../../system-prompts'
 import { LazyToolManager } from './tools/lazy-tool-manager'
 import { assertUniqueToolNames } from './tools/unique-tool-names'
 import type { DefinedAgent } from './agents/define-agent'
@@ -137,6 +139,7 @@ import type {
   Interrupt,
   JSONSchema,
   LazyToolsConfig,
+  MidConversationChange,
   ModelMessage,
   ModelMessageBlock,
   PromptCacheOptions,
@@ -918,6 +921,13 @@ class TextEngine<
    * the order could no longer be tracked (callers fall back to one message).
    */
   private turnParts: Array<TurnPart> | null = []
+  /**
+   * The mid-conversation record of the current model call. The first
+   * assistant message that the call produces takes it. A call that produces
+   * none (an error, an abort) saves nothing, and the next call plans again.
+   */
+  private pendingMidConversationChange: MidConversationChange | undefined =
+    undefined
   private currentThinkingContent = ''
   private currentThinkingSignature = ''
   private currentThinkingRedacted = false
@@ -1660,6 +1670,21 @@ class TextEngine<
     // covered too.
     assertMessagesFileSourceSupport(this.adapter, this.messages)
 
+    // Mid-conversation changes, only for an adapter with a channel that is
+    // on. Every other adapter gets today's request and no new field.
+    const channels = this.adapter.midConversationChannels
+    const midConversation =
+      channels?.tools || channels?.systemPrompts
+        ? planMidConversationChanges({
+            messages: this.providerMessages,
+            toolNames: tools.map((tool) => tool.name),
+            systemPrompts: normalizeSystemPrompts(this.systemPrompts).map(
+              (prompt) => prompt.content,
+            ),
+          })
+        : undefined
+    this.pendingMidConversationChange = midConversation?.record
+
     for await (const raw of this.adapter.chatStream({
       model: this.params.model,
       messages: this.providerMessages,
@@ -1672,6 +1697,9 @@ class TextEngine<
       logger: this.logger,
       threadId: this.threadId,
       promptCache: this.params.promptCache,
+      ...(midConversation
+        ? { midConversationChanges: midConversation.changes }
+        : {}),
       runId: this.runIdOverride,
       parentRunId: this.parentRunIdOverride,
       // Expose provided capabilities (e.g. sandbox) to harness adapters.
@@ -2748,6 +2776,7 @@ class TextEngine<
 
   private addAssistantToolCallMessage(toolCalls: Array<ToolCall>): void {
     this.finalizeCurrentThinkingStep()
+    const from = this.messages.length
 
     const segments = this.buildOrderedAssistantSegments(
       toolCalls,
@@ -2770,6 +2799,7 @@ class TextEngine<
         },
       ]),
     ]
+    this.saveMidConversationChange(from)
     this.middlewareCtx.messages = this.messages
   }
 
@@ -2883,6 +2913,7 @@ class TextEngine<
     }
 
     this.messages = messages
+    this.saveMidConversationChange(startedLength)
     this.middlewareCtx.messages = this.messages
   }
 
@@ -3413,13 +3444,34 @@ class TextEngine<
 
   private addAssistantTextMessageForInterrupt(): void {
     if (this.accumulatedContent.length === 0) return
+    const from = this.messages.length
     this.messages = [
       ...this.messages,
       { role: 'assistant', content: this.accumulatedContent },
     ]
+    this.saveMidConversationChange(from)
     this.middlewareCtx.messages = this.messages
   }
 
+  /**
+   * Save the pending mid-conversation record on the first assistant message
+   * at index `from` or later. The record is a field of the message, so it
+   * goes wherever the transcript goes: a message store, a harness log, a
+   * restart.
+   */
+  private saveMidConversationChange(from: number): void {
+    const record = this.pendingMidConversationChange
+    if (!record) return
+    const index = this.messages.findIndex(
+      (message, at) => at >= from && message.role === 'assistant',
+    )
+    if (index < 0) return
+    this.pendingMidConversationChange = undefined
+    this.messages = this.messages.map((message, at) =>
+      at === index ? { ...message, midConversationChange: record } : message,
+    )
+  }
+
   private getBoundaryActionableToolRequests(
     toolCalls: ReadonlyArray<ToolCall>,
   ): {
diff --git a/packages/ai/tests/chat-mid-conversation.test.ts b/packages/ai/tests/chat-mid-conversation.test.ts
new file mode 100644
index 0000000000..a0fbe7b832
--- /dev/null
+++ b/packages/ai/tests/chat-mid-conversation.test.ts
@@ -0,0 +1,339 @@
+import { describe, expect, it } from 'vitest'
+import { chat } from '../src/activities/chat/index'
+import { defineChatMiddleware } from '../src/activities/chat/middleware/define'
+import { DISCOVERY_TOOL_NAME } from '../src/activities/chat/tools/lazy-tool-manager'
+import { promptHash } from '../src/utilities/mid-conversation'
+import { collectChunks, createMockAdapter, ev, serverTool } from './test-utils'
+import type { AnyTextAdapter } from '../src/activities/chat/adapter'
+import type { ChatMiddlewareConfig } from '../src/activities/chat/middleware/types'
+import type {
+  MidConversationChannels,
+  ModelMessage,
+  StreamChunk,
+  Tool,
+} from '../src/types'
+import type { AdapterYieldChunk } from '../src/utilities/adapter-yield-chunk'
+
+const ON: MidConversationChannels = { tools: true, systemPrompts: true }
+
+/** A model call that calls tool `name` with `args`. */
+const toolBatch = (
+  id: string,
+  name = 'a',
+  args: object = {},
+): Array<AdapterYieldChunk> => [
+  ev.runStarted(),
+  ev.toolStart(id, name),
+  ev.toolArgs(id, JSON.stringify(args)),
+  ev.runFinished('tool_calls'),
+]
+
+/** A model call that answers `text`. */
+const answer = (text: string): Array<AdapterYieldChunk> => [
+  ev.runStarted(),
+  ev.textStart(),
+  ev.textContent(text),
+  ev.textEnd(),
+  ev.runFinished('stop'),
+]
+
+const lazyTool = (name: string): Tool => ({
+  name,
+  description: `Lazy tool: ${name}`,
+  execute: () => ({ ok: true }),
+  lazy: true,
+})
+
+/** The record of each message: `undefined` for a message without one. */
+const records = (messages: ReadonlyArray<ModelMessage>) =>
+  messages.map((message) => message.midConversationChange)
+
+/**
+ * One chat() run on the mock adapter, with `channels` on the adapter. `edit`
+ * changes the config before the model call of `iteration`.
+ */
+async function run(options: {
+  iterations: Array<Array<AdapterYieldChunk>>
+  tools: Array<Tool>
+  systemPrompts?: Array<string>
+  channels?: MidConversationChannels
+  edit?: (
+    config: ChatMiddlewareConfig,
+    iteration: number,
+  ) => Partial<ChatMiddlewareConfig> | undefined
+}) {
+  const mock = createMockAdapter({ iterations: options.iterations })
+  const adapter: AnyTextAdapter = options.channels
+    ? { ...mock.adapter, midConversationChannels: options.channels }
+    : mock.adapter
+  let messages: Array<ModelMessage> = []
+  await collectChunks(
+    chat({
+      adapter,
+      messages: [{ role: 'user', content: 'go' }],
+      tools: options.tools,
+      systemPrompts: options.systemPrompts,
+      middleware: [
+        defineChatMiddleware({
+          name: 'test/mid-conversation',
+          onConfig(ctx, config) {
+            if (ctx.phase !== 'beforeModel') return undefined
+            return options.edit?.(config, ctx.iteration)
+          },
+          onFinish(ctx) {
+            messages = [...ctx.messages]
+          },
+        }),
+      ],
+    }) as AsyncIterable<StreamChunk>,
+  )
+  return { calls: mock.calls, messages }
+}
+
+const addToolB = (config: ChatMiddlewareConfig, iteration: number) =>
+  iteration === 1
+    ? { tools: [...config.tools, serverTool('b', () => ({ ok: true }))] }
+    : undefined
+
+describe('chat() mid-conversation changes', () => {
+  it.each<[string, MidConversationChannels | undefined]>([
+    ['has no channels', undefined],
+    ['has both channels off', { tools: false, systemPrompts: false }],
+  ])(
+    'sends and saves nothing new when the adapter %s',
+    async (_label, channels) => {
+      const { calls, messages } = await run({
+        channels,
+        iterations: [toolBatch('c1'), answer('done')],
+        tools: [serverTool('a', () => ({ ok: true }))],
+        systemPrompts: ['A'],
+        edit: addToolB,
+      })
+
+      expect(calls).toHaveLength(2)
+      for (const call of calls) {
+        expect(call).not.toHaveProperty('midConversationChanges')
+      }
+      expect(messages).toHaveLength(4)
+      for (const message of messages) {
+        expect(message).not.toHaveProperty('midConversationChange')
+      }
+    },
+  )
+
+  it('writes a start point on the first call', async () => {
+    const { calls, messages } = await run({
+      channels: ON,
+      iterations: [answer('hi')],
+      tools: [serverTool('a', () => ({ ok: true }))],
+      systemPrompts: ['Be short.'],
+    })
+
+    expect(calls[0]?.midConversationChanges).toEqual({
+      start: { tools: ['a'], systemPrompts: 1 },
+      changes: [],
+    })
+    expect(records(messages)).toEqual([
+      undefined,
+      { tools: ['a'], systemPrompts: [promptHash('Be short.')] },
+    ])
+  })
+
+  it('sends a tool that onConfig adds after a tool batch as a change', async () => {
+    const { calls, messages } = await run({
+      channels: ON,
+      iterations: [toolBatch('c1'), toolBatch('c2'), answer('done')],
+      tools: [serverTool('a', () => ({ ok: true }))],
+      edit: addToolB,
+    })
+
+    const start = { tools: ['a'], systemPrompts: 0 }
+    // messages[3] is the assistant message of the second call.
+    const changes = [{ before: 3, tools: ['b'] }]
+    expect(calls.map((call) => call.midConversationChanges)).toEqual([
+      { start, changes: [] },
+      { start, changes },
+      // Nothing new: no new record, and the old change keeps its place.
+      { start, changes },
+    ])
+    // `tools` stays the full current list.
+    expect(calls[2]?.tools?.map((tool) => tool.name)).toEqual(['a', 'b'])
+    expect(records(messages)).toEqual([
+      undefined,
+      { tools: ['a'], systemPrompts: [] },
+      undefined,
+      { toolsAdded: ['b'] },
+      undefined,
+      undefined,
+    ])
+  })
+
+  it('sends a system prompt added at the end as a change', async () => {
+    const { calls, messages } = await run({
+      channels: ON,
+      iterations: [toolBatch('c1'), answer('done')],
+      tools: [serverTool('a', () => ({ ok: true }))],
+      systemPrompts: ['A'],
+      edit: (config, iteration) =>
+        iteration === 1
+          ? { systemPrompts: [...config.systemPrompts, 'B'] }
+          : undefined,
+    })
+
+    expect(calls[1]?.midConversationChanges).toEqual({
+      start: { tools: ['a'], systemPrompts: 1 },
+      changes: [{ before: 3, systemPrompts: 1 }],
+    })
+    expect(calls[1]?.systemPrompts).toEqual(['A', 'B'])
+    expect(records(messages)[3]).toEqual({ systemPrompts: [promptHash('B')] })
+  })
+
+  it('makes a new start point when a tool is removed', async () => {
+    const { calls, messages } = await run({
+      channels: ON,
+      iterations: [toolBatch('c1'), answer('done')],
+      tools: [
+        serverTool('a', () => ({ ok: true })),
+        serverTool('b', () => ({ ok: true })),
+      ],
+      edit: (config, iteration) =>
+        iteration === 1
+          ? { tools: config.tools.filter((tool) => tool.name !== 'b') }
+          : undefined,
+    })
+
+    expect(calls[1]?.midConversationChanges).toEqual({
+      start: { tools: ['a'], systemPrompts: 0 },
+      changes: [],
+    })
+    expect(records(messages)[3]).toEqual({ tools: ['a'], systemPrompts: [] })
+  })
+
+  it('makes a new start point when a prompt is edited', async () => {
+    const { calls, messages } = await run({
+      channels: ON,
+      iterations: [toolBatch('c1'), answer('done')],
+      tools: [serverTool('a', () => ({ ok: true }))],
+      systemPrompts: ['A'],
+      edit: (_config, iteration) =>
+        iteration === 1 ? { systemPrompts: ['A2'] } : undefined,
+    })
+
+    expect(calls[1]?.midConversationChanges).toEqual({
+      start: { tools: ['a'], systemPrompts: 1 },
+      changes: [],
+    })
+    expect(records(messages)[3]).toEqual({
+      tools: ['a'],
+      systemPrompts: [promptHash('A2')],
+    })
+  })
+
+  it('adds found lazy tools as a change, and starts again when the discovery tool drops out', async () => {
+    const { calls, messages } = await run({
+      channels: ON,
+      iterations: [
+        toolBatch('d1', DISCOVERY_TOOL_NAME, { toolNames: ['lazyA'] }),
+        toolBatch('d2', DISCOVERY_TOOL_NAME, { toolNames: ['lazyB'] }),
+        answer('ok'),
+      ],
+      tools: [lazyTool('lazyA'), lazyTool('lazyB')],
+    })
+
+    const discovery = { tools: [DISCOVERY_TOOL_NAME], systemPrompts: 0 }
+    expect(calls.map((call) => call.midConversationChanges)).toEqual([
+      { start: discovery, changes: [] },
+      { start: discovery, changes: [{ before: 3, tools: ['lazyA'] }] },
+      // Every lazy tool is found, so the discovery tool is gone.
+      { start: { tools: ['lazyA', 'lazyB'], systemPrompts: 0 }, changes: [] },
+    ])
+    expect(records(messages)).toEqual([
+      undefined,
+      { tools: [DISCOVERY_TOOL_NAME], systemPrompts: [] },
+      undefined,
+      { toolsAdded: ['lazyA'] },
+      undefined,
+      { tools: ['lazyA', 'lazyB'], systemPrompts: [] },
+    ])
+  })
+
+  it('saves no record for a call that fails, and the next run sends the same change', async () => {
+    const history: Array<ModelMessage> = [
+      { role: 'user', content: 'q1' },
+      {
+        role: 'assistant',
+        content: 'a1',
+        midConversationChange: { tools: ['a'], systemPrompts: [] },
+      },
+      { role: 'user', content: 'q2' },
+    ]
+    const mock = createMockAdapter({
+      iterations: [
+        [
+          ev.runStarted(),
+          ev.textStart(),
+          ev.textContent('par'),
+          ev.runError('provider down'),
+        ],
+        answer('a2'),
+      ],
+    })
+    const adapter: AnyTextAdapter = {
+      ...mock.adapter,
+      midConversationChannels: ON,
+    }
+    const tools = [
+      serverTool('a', () => ({ ok: true })),
+      serverTool('b', () => ({ ok: true })),
+    ]
+    let failed: Array<ModelMessage> = []
+    let finished: Array<ModelMessage> = []
+    const keep = defineChatMiddleware({
+      name: 'test/keep-messages',
+      onError(ctx) {
+        failed = [...ctx.messages]
+      },
+      onFinish(ctx) {
+        finished = [...ctx.messages]
+      },
+    })
+
+    await collectChunks(
+      chat({
+        adapter,
+        messages: history,
+        tools,
+        middleware: [keep],
+      }) as AsyncIterable<StreamChunk>,
+    )
+    await collectChunks(
+      chat({
+        adapter,
+        messages: history,
+        tools,
+        middleware: [keep],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    const changes = {
+      start: { tools: ['a'], systemPrompts: 0 },
+      changes: [{ before: 3, tools: ['b'] }],
+    }
+    expect(mock.calls.map((call) => call.midConversationChanges)).toEqual([
+      changes,
+      changes,
+    ])
+    // The failed call left no assistant message, so it saved no record.
+    expect(records(failed)).toEqual([
+      undefined,
+      { tools: ['a'], systemPrompts: [] },
+      undefined,
+    ])
+    expect(records(finished)).toEqual([
+      undefined,
+      { tools: ['a'], systemPrompts: [] },
+      undefined,
+      { toolsAdded: ['b'] },
+    ])
+  })
+})

From 2ae57b5be937a52a7d45562f260e6e1ee0d7e3bc Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 15:27:34 +0200
Subject: [PATCH 179/286] test(ai-harness): keep the block order through the
 log and a rebuild

An answer of thinking, tool call, thinking, tool call keeps its blockOrder in the next model call, the transcript, a fold of the log, and a second host.
---
 .../ai-harness/tests/durable-session.test.ts  | 128 +++++++++++++++++-
 1 file changed, 127 insertions(+), 1 deletion(-)

diff --git a/packages/ai-harness/tests/durable-session.test.ts b/packages/ai-harness/tests/durable-session.test.ts
index 45693829e8..b22e998870 100644
--- a/packages/ai-harness/tests/durable-session.test.ts
+++ b/packages/ai-harness/tests/durable-session.test.ts
@@ -4,7 +4,7 @@ import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness, definePlugin } from '../src'
 import { loadLogState, sessionOf } from '../src/log'
 import { gate, messageTexts, mockAdapter, text, toolCall } from './helpers'
-import type { StreamChunk } from '@tanstack/ai'
+import type { ModelMessage, StreamChunk } from '@tanstack/ai'
 import type { LogStore } from '@tanstack/ai-persistence'
 import type { HarnessSession, ProjectOptions, SessionEvent } from '../src'
 import type { Reply } from './helpers'
@@ -101,6 +101,77 @@ const deltasOf = (seen: Array<SessionEvent>, messageId: string) =>
     .map((event) => ('delta' in event ? event.delta : ''))
     .join('')
 
+/** One model call: signed thinking, a tool call, signed thinking, a tool call. */
+function thinkCallThinkCall(): Array<StreamChunk> {
+  const thinking = (
+    id: string,
+    content: string,
+    signature: string,
+  ): Array<StreamChunk> => [
+    { type: EventType.STEP_STARTED, stepName: id, timestamp: Date.now() },
+    { type: EventType.REASONING_START, messageId: id, timestamp: Date.now() },
+    {
+      type: EventType.REASONING_MESSAGE_START,
+      messageId: id,
+      role: 'reasoning',
+      timestamp: Date.now(),
+    },
+    {
+      type: EventType.REASONING_MESSAGE_CONTENT,
+      messageId: id,
+      delta: content,
+      timestamp: Date.now(),
+    },
+    {
+      type: EventType.REASONING_ENCRYPTED_VALUE,
+      subtype: 'message',
+      entityId: id,
+      encryptedValue: signature,
+      timestamp: Date.now(),
+    },
+    {
+      type: EventType.REASONING_MESSAGE_END,
+      messageId: id,
+      timestamp: Date.now(),
+    },
+    { type: EventType.REASONING_END, messageId: id, timestamp: Date.now() },
+  ]
+  const call = (id: string, city: string): Array<StreamChunk> => [
+    {
+      type: EventType.TOOL_CALL_START,
+      toolCallId: id,
+      toolCallName: 'lookup',
+      timestamp: Date.now(),
+    },
+    {
+      type: EventType.TOOL_CALL_ARGS,
+      toolCallId: id,
+      delta: JSON.stringify({ city }),
+      timestamp: Date.now(),
+    },
+    { type: EventType.TOOL_CALL_END, toolCallId: id, timestamp: Date.now() },
+  ]
+  return [
+    {
+      type: EventType.RUN_STARTED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: Date.now(),
+    },
+    ...thinking('think-1', 'Check Berlin.', 'sig-1'),
+    ...call('call-1', 'Berlin'),
+    ...thinking('think-2', 'Now Paris.', 'sig-2'),
+    ...call('call-2', 'Paris'),
+    {
+      type: EventType.RUN_FINISHED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: Date.now(),
+      metadata: { tanstack: { finishReason: 'tool_calls' } },
+    },
+  ]
+}
+
 // The types refuse these store sets. The runtime check is for JavaScript
 // callers and dynamic store bags, so these tests pass them with `as never`.
 describe('durable host stores', () => {
@@ -402,4 +473,59 @@ describe('durable session log', () => {
     await writer.close()
     await reader.close()
   })
+
+  it('keeps the block order of an answer in the log and after a rebuild', async () => {
+    const persistence = durablePersistence()
+    const lookup = toolDefinition({
+      name: 'lookup',
+      description: 'Look up the weather',
+    }).server(async () => 'sunny')
+    const { adapter, calls } = mockAdapter([
+      () => thinkCallThinkCall(),
+      () => text('Both are sunny.'),
+    ])
+    const harness = defineHarness({
+      name: 'test/block-order',
+      adapter,
+      tools: [lookup],
+    })
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(harness, { threadId: THREAD })
+
+    await session.prompt('Weather in Berlin and Paris?')
+
+    const order = [
+      { type: 'thinking', index: 0 },
+      { type: 'tool-call', id: 'call-1' },
+      { type: 'thinking', index: 1 },
+      { type: 'tool-call', id: 'call-2' },
+    ]
+    const answer = (messages: Array<ModelMessage>) =>
+      messages.find((message) => message.toolCalls?.length)
+    // The next model call of the turn gets the map.
+    expect(answer(calls[1].messages)?.blockOrder).toEqual(order)
+    const transcript = await session.transcript()
+    expect(answer(transcript)).toMatchObject({
+      thinking: [
+        { content: 'Check Berlin.', signature: 'sig-1' },
+        { content: 'Now Paris.', signature: 'sig-2' },
+      ],
+      blockOrder: order,
+    })
+
+    // A fold of the log gives the same messages.
+    const rebuilt = sessionOf(
+      await loadLogState({ store: persistence.stores.log, logId: THREAD }),
+      THREAD,
+    )
+    expect(rebuilt.messages).toEqual(transcript)
+
+    // The first host never closes, like a process that stopped. A second
+    // host that opens the thread gets the same messages.
+    const next = createHarnessHost({ persistence })
+    const reopened = await next.open(harness, { threadId: THREAD })
+    expect(await reopened.transcript()).toEqual(transcript)
+    await host.close().catch(() => {})
+    await next.close()
+  })
 })

From 5f392761778fc07d5c3d73bf66870f99f54eae63 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 15:27:35 +0200
Subject: [PATCH 180/286] test(ai-harness): keep the start tools across turns,
 a rebuild, and a steer

With an adapter that has mid-conversation channels, the start tool set of a harness session holds across turns and a rebuild, and a tool added next to a steer goes out as a change before the next answer.
---
 .../tests/mid-conversation-changes.test.ts    | 183 ++++++++++++++++++
 1 file changed, 183 insertions(+)
 create mode 100644 packages/ai-harness/tests/mid-conversation-changes.test.ts

diff --git a/packages/ai-harness/tests/mid-conversation-changes.test.ts b/packages/ai-harness/tests/mid-conversation-changes.test.ts
new file mode 100644
index 0000000000..7d91ae210d
--- /dev/null
+++ b/packages/ai-harness/tests/mid-conversation-changes.test.ts
@@ -0,0 +1,183 @@
+import { describe, expect, it } from 'vitest'
+import { toolDefinition } from '@tanstack/ai'
+import { promptHash } from '@tanstack/ai/adapter-internals'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '../src'
+import { gate, messageTexts, mockAdapter, text, toolCall } from './helpers'
+import type {
+  AnyChatMiddleware,
+  AnyTextAdapter,
+  AnyTool,
+  ModelMessage,
+  Tool,
+} from '@tanstack/ai'
+import type { Reply } from './helpers'
+
+const THREAD = 't1'
+
+/** The scripted adapter of `./helpers`, on a model with both channels. */
+function channelAdapter(replies: Array<Reply>) {
+  const { adapter, calls } = mockAdapter(replies)
+  const withChannels: AnyTextAdapter = {
+    ...adapter,
+    midConversationChannels: { tools: true, systemPrompts: true },
+  }
+  return { adapter: withChannels, calls }
+}
+
+/** The stores of a durable host: a log, runs, and metadata. */
+function durablePersistence() {
+  const { runs, metadata } = memoryPersistence().stores
+  return { stores: { log: memoryLogStore(), runs, metadata } }
+}
+
+const lookup = toolDefinition({
+  name: 'lookup',
+  description: 'Look something up',
+}).server(async () => 'found')
+
+/** A tool that a later deploy, or a connector, adds. */
+const extra: Tool = {
+  name: 'extra',
+  description: 'A tool added later',
+  execute: async () => 'extra',
+}
+
+/** The record of each message that has one. */
+const records = (messages: ReadonlyArray<ModelMessage>) =>
+  messages.flatMap((message) =>
+    message.midConversationChange ? [message.midConversationChange] : [],
+  )
+
+describe('mid-conversation changes in a harness', () => {
+  it('keeps the start tools across turns and a rebuild', async () => {
+    const persistence = durablePersistence()
+    const { adapter, calls } = channelAdapter([
+      () => text('first answer'),
+      () => text('second answer'),
+      () => text('third answer'),
+    ])
+    const harness = (tools: ReadonlyArray<AnyTool>) =>
+      defineHarness({
+        name: 'test/mid-conversation',
+        adapter,
+        systemPrompts: ['Be brief.'],
+        tools,
+      })
+    /** One turn on a new host. The host rebuilds the transcript from the log. */
+    const turnOnNewHost = async (
+      tools: ReadonlyArray<AnyTool>,
+      message: string,
+    ) => {
+      const host = createHarnessHost({ persistence })
+      const session = await host.open(harness(tools), { threadId: THREAD })
+      await session.prompt(message)
+      const transcript = await session.transcript()
+      await host.close()
+      return transcript
+    }
+
+    await turnOnNewHost([lookup], 'one')
+    // A deploy adds a tool between the turns.
+    await turnOnNewHost([lookup, extra], 'two')
+    const transcript = await turnOnNewHost([lookup, extra], 'three')
+
+    const start = { tools: ['lookup'], systemPrompts: 1 }
+    expect(calls[0].midConversationChanges).toEqual({ start, changes: [] })
+    // The change goes before the answer of turn two.
+    const change = { before: calls[1].messages.length, tools: ['extra'] }
+    expect(calls[1].midConversationChanges).toEqual({
+      start,
+      changes: [change],
+    })
+    expect(calls[2].midConversationChanges).toEqual({
+      start,
+      changes: [change],
+    })
+    expect(calls[2].messages[change.before]).toMatchObject({
+      role: 'assistant',
+      content: 'second answer',
+    })
+    // `tools` stays the full current list. The adapter splits it.
+    expect(calls[2].tools.map((tool: { name: string }) => tool.name)).toEqual([
+      'lookup',
+      'extra',
+    ])
+    expect(records(transcript)).toEqual([
+      { tools: ['lookup'], systemPrompts: [promptHash('Be brief.')] },
+      { toolsAdded: ['extra'] },
+    ])
+  })
+
+  it('a steer and a tool change in one turn', async () => {
+    const started = gate()
+    const release = gate()
+    let installed = false
+    const { adapter, calls } = channelAdapter([
+      () => toolCall('lookup', { q: 'x' }),
+      () => text('done'),
+      () => text('next turn'),
+    ])
+    // The tool call turns on `extra`, like a connector that a tool connects.
+    const installs = toolDefinition({
+      name: 'lookup',
+      description: 'Look something up',
+    }).server(async () => {
+      installed = true
+      started.open()
+      await release.opened
+      return 'found'
+    })
+    const addsExtra: AnyChatMiddleware = {
+      name: 'test/adds-extra',
+      onConfig: (ctx, config) =>
+        ctx.phase === 'beforeModel' &&
+        installed &&
+        !config.tools.some((tool) => tool.name === 'extra')
+          ? { tools: [...config.tools, extra] }
+          : undefined,
+    }
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/mid-conversation',
+        adapter,
+        tools: [installs],
+        middleware: [addsExtra],
+      }),
+      { threadId: THREAD },
+    )
+
+    const turn = session.prompt('find x')
+    await started.opened
+    await session.steer('also check y')
+    release.open()
+    expect(await turn).toEqual({ text: 'done' })
+    expect(await session.prompt('and now?')).toEqual({ text: 'next turn' })
+
+    const start = { tools: ['lookup'], systemPrompts: 0 }
+    expect(calls[0].midConversationChanges).toEqual({ start, changes: [] })
+    // The steer joined before the second model call, so the change goes
+    // after it: at the next assistant message.
+    expect(messageTexts(calls[1]).at(-1)).toBe('also check y')
+    const change = { before: calls[1].messages.length, tools: ['extra'] }
+    expect(calls[1].midConversationChanges).toEqual({
+      start,
+      changes: [change],
+    })
+    // The next turn keeps the start set and the change at its place.
+    expect(calls[2].midConversationChanges).toEqual({
+      start,
+      changes: [change],
+    })
+    expect(calls[2].messages[change.before - 1]).toMatchObject({
+      role: 'user',
+      content: 'also check y',
+    })
+    expect(calls[2].messages[change.before]).toMatchObject({
+      role: 'assistant',
+      content: 'done',
+    })
+    await host.close()
+  })
+})

From 7301f2f6bbc4d997f20f9562735391b6f27b8030 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 15:27:36 +0200
Subject: [PATCH 181/286] fix(ai-persistence): keep the stored mid-conversation
 record when a client sends the message again

A useChat client sends its history again on each turn without the engine's mid-conversation record. mergeStoredMessages now keeps the stored record when the incoming copy of the same message has none, so the prompt cache holds across turns with a message store.
---
 .changeset/persistence-keep-change-record.md  |  5 ++
 packages/ai-persistence/src/merge-stored.ts   | 21 +++++++-
 .../tests/with-persistence.test.ts            | 54 +++++++++++++++++++
 3 files changed, 78 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/persistence-keep-change-record.md

diff --git a/.changeset/persistence-keep-change-record.md b/.changeset/persistence-keep-change-record.md
new file mode 100644
index 0000000000..099c275f24
--- /dev/null
+++ b/.changeset/persistence-keep-change-record.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-persistence': patch
+---
+
+A message store now keeps the mid-conversation change record of an assistant message when a client sends the same message again without it. With `useChat`, the prompt cache then holds across turns on models that receive tool and prompt changes as changes.
diff --git a/packages/ai-persistence/src/merge-stored.ts b/packages/ai-persistence/src/merge-stored.ts
index 24b5e0aca0..4006332246 100644
--- a/packages/ai-persistence/src/merge-stored.ts
+++ b/packages/ai-persistence/src/merge-stored.ts
@@ -2,7 +2,8 @@ import type { ModelMessage } from '@tanstack/ai'
 
 // Empty incoming keeps stored. Non-empty: the last incoming id that already
 // exists in stored is a cutoff (reload drops the old assistant after that
-// user). Same id is replaced in place. New ids and messages with no id are
+// user). Same id is replaced in place, but a stored mid-conversation record
+// stays when the incoming copy has none. New ids and messages with no id are
 // appended.
 export function mergeStoredMessages(
   stored: ReadonlyArray<ModelMessage>,
@@ -36,7 +37,10 @@ export function mergeStoredMessages(
     const id = message.id
     if (id) {
       storedIds.add(id)
-      merged.push(incomingById.get(id) ?? message)
+      const replacement = incomingById.get(id)
+      merged.push(
+        replacement ? keepStoredRecord(replacement, message) : message,
+      )
       continue
     }
     merged.push(message)
@@ -65,3 +69,16 @@ export function mergeStoredMessages(
 
   return merged
 }
+
+// A client never sends the engine's mid-conversation record (UIMessages have
+// none), so keep the stored one. Without it, each turn starts a new start
+// point and the prompt cache breaks once per turn.
+function keepStoredRecord(
+  incoming: ModelMessage,
+  stored: ModelMessage,
+): ModelMessage {
+  if (incoming.midConversationChange || !stored.midConversationChange) {
+    return incoming
+  }
+  return { ...incoming, midConversationChange: stored.midConversationChange }
+}
diff --git a/packages/ai-persistence/tests/with-persistence.test.ts b/packages/ai-persistence/tests/with-persistence.test.ts
index f093eff971..6371b23761 100644
--- a/packages/ai-persistence/tests/with-persistence.test.ts
+++ b/packages/ai-persistence/tests/with-persistence.test.ts
@@ -1628,4 +1628,58 @@ describe('withPersistence (merge by id)', () => {
       expect.objectContaining({ role: 'assistant', content: 'hello' }),
     ])
   })
+
+  it('keeps the stored change record when the incoming copy has none', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.messages!.saveThread('t1', [
+      { role: 'user', content: 'ask', id: 'u1' },
+      {
+        role: 'assistant',
+        content: 'done',
+        id: 'a1',
+        midConversationChange: { tools: ['read'], systemPrompts: [] },
+      },
+    ])
+
+    const thread = await runPersistedChat(persistence, [
+      { role: 'user', content: 'ask', id: 'u1' },
+      { role: 'assistant', content: 'done', id: 'a1' },
+      { role: 'user', content: 'next', id: 'u2' },
+    ])
+
+    expect(thread.find((message) => message.id === 'a1')).toEqual({
+      role: 'assistant',
+      content: 'done',
+      id: 'a1',
+      midConversationChange: { tools: ['read'], systemPrompts: [] },
+    })
+  })
+
+  it('lets an incoming change record win', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.messages!.saveThread('t1', [
+      { role: 'user', content: 'ask', id: 'u1' },
+      {
+        role: 'assistant',
+        content: 'done',
+        id: 'a1',
+        midConversationChange: { tools: ['read'], systemPrompts: [] },
+      },
+    ])
+
+    const thread = await runPersistedChat(persistence, [
+      { role: 'user', content: 'ask', id: 'u1' },
+      {
+        role: 'assistant',
+        content: 'done',
+        id: 'a1',
+        midConversationChange: { toolsAdded: ['grep'] },
+      },
+      { role: 'user', content: 'next', id: 'u2' },
+    ])
+
+    expect(
+      thread.find((message) => message.id === 'a1')?.midConversationChange,
+    ).toEqual({ toolsAdded: ['grep'] })
+  })
 })

From d8c01659a09d73191d1df1c5364f2b831f07dc51 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 16:00:32 +0200
Subject: [PATCH 182/286] feat(ai): send assistant wire rows in block order and
 join them on the server

uiMessagesToWire sends an assistant message whose blocks leave the default order as ordered AG-UI rows: a tool result ends a row, and a row that exists only for the order carries metadata.tanstack.continues. The server joins those rows back into one message with a blockOrder map, and the snapshot fold-back puts them into one UIMessage. A message in the default order sends the same rows as before.
---
 packages/ai/src/activities/chat/messages.ts   |  96 ++++-
 .../src/activities/chat/stream/processor.ts   |  24 +-
 packages/ai/src/types.ts                      |   6 +
 packages/ai/src/utilities/ag-ui-wire.ts       | 236 +++++++-----
 packages/ai/tests/ag-ui-wire.test.ts          | 346 +++++++++++++++++-
 packages/ai/tests/chat-block-order.test.ts    |  70 ++++
 ...t-provider-executed-thinking-order.test.ts |  27 +-
 7 files changed, 708 insertions(+), 97 deletions(-)

diff --git a/packages/ai/src/activities/chat/messages.ts b/packages/ai/src/activities/chat/messages.ts
index 251771d0b3..46b13ceabe 100644
--- a/packages/ai/src/activities/chat/messages.ts
+++ b/packages/ai/src/activities/chat/messages.ts
@@ -206,9 +206,14 @@ export function convertMessagesToModelMessages(
     if (group.info.parentToolCallId !== undefined) continue
     const text = subagentWireText(group.messages)
     if (text === '') continue
+    // A `continues` row was joined into the row before it, so it is no host.
     const host = top
       .slice(0, group.hostIndex + 1)
-      .findLast((message) => message.role === 'assistant')
+      .findLast(
+        (message) =>
+          message.role === 'assistant' &&
+          tanstackMetadata(message)?.continues === undefined,
+      )
     const hostId = host && 'id' in host ? host.id : undefined
     blocks.set(hostId, [
       ...(blocks.get(hostId) ?? []),
@@ -229,6 +234,8 @@ export function convertMessagesToModelMessages(
       converted.push({ role: 'assistant', content: block })
       continue
     }
+    // ponytail: the added text makes a `blockOrder` map on the host invalid,
+    // so readers use the default order for that one message.
     converted[index] = {
       ...host,
       content:
@@ -261,6 +268,10 @@ function convertOwnMessages(
 
   const modelMessages: Array<ModelMessage> = []
   let pendingThinking: NonNullable<ModelMessage['thinking']> = []
+  // The last assistant row and the message it went into, for `continues`.
+  let lastAssistantRow:
+    | { id: string | undefined; message: ModelMessage }
+    | undefined
   for (const msg of messages) {
     if ('parts' in msg) {
       modelMessages.push(...uiMessageToModelMessages(msg))
@@ -351,7 +362,7 @@ function convertOwnMessages(
       const toolCalls = source.toolCalls?.map((toolCall) =>
         toolCallFromWire(toolCall, toolCallMetadata?.[toolCall.id]),
       )
-      modelMessages.push({
+      const row: ModelMessage = {
         ...source,
         ...(toolCalls !== undefined ? { toolCalls } : {}),
         ...(pendingThinking.length > 0
@@ -359,8 +370,23 @@ function convertOwnMessages(
               thinking: [...(source.thinking ?? []), ...pendingThinking],
             }
           : {}),
-      })
+      }
       pendingThinking = []
+      // A row that exists only for the block order joins the row before it.
+      const continues = tanstackMetadata(msg)?.continues
+      if (
+        lastAssistantRow !== undefined &&
+        modelMessages.at(-1) === lastAssistantRow.message &&
+        continues !== undefined &&
+        continues === lastAssistantRow.id
+      ) {
+        const joined = joinAssistantRows(lastAssistantRow.message, row)
+        modelMessages[modelMessages.length - 1] = joined
+        lastAssistantRow = { id: source.id, message: joined }
+      } else {
+        modelMessages.push(row)
+        lastAssistantRow = { id: source.id, message: row }
+      }
       continue
     }
 
@@ -369,6 +395,70 @@ function convertOwnMessages(
   return modelMessages
 }
 
+/**
+ * The blocks of an assistant message as order entries: in map order when
+ * the map is valid, else in the default order.
+ */
+function blockOrderEntries(message: ModelMessage): Array<BlockOrderEntry> {
+  const blocks = orderedAssistantBlocks(message)
+  if (blocks) {
+    return blocks.map((block): BlockOrderEntry => {
+      if (block.type === 'thinking') return { type: 'thinking' }
+      if (block.type === 'text') return { type: 'text', text: block.text }
+      return { type: 'tool-call', id: block.toolCall.id }
+    })
+  }
+  return [
+    ...(message.thinking ?? []).map(
+      (): BlockOrderEntry => ({ type: 'thinking' }),
+    ),
+    ...(typeof message.content === 'string'
+      ? [{ type: 'text' as const, text: message.content }]
+      : []),
+    ...(message.toolCalls ?? []).map(
+      (toolCall): BlockOrderEntry => ({ type: 'tool-call', id: toolCall.id }),
+    ),
+  ]
+}
+
+/**
+ * Join an assistant wire row marked `continues` into the message of the
+ * assistant row before it, and extend that message's order map. The message
+ * keeps the first row's id and metadata.
+ */
+function joinAssistantRows(
+  previous: ModelMessage,
+  row: ModelMessage,
+): ModelMessage {
+  const text = [previous.content, row.content]
+    .filter((content) => typeof content === 'string')
+    .join('')
+  const thinking = [...(previous.thinking ?? []), ...(row.thinking ?? [])]
+  const toolCalls = [...(previous.toolCalls ?? []), ...(row.toolCalls ?? [])]
+  const blockOrder = buildBlockOrder([
+    ...blockOrderEntries(previous),
+    ...blockOrderEntries(row),
+  ])
+  // Each row lists only its own ui resources. Keep them all.
+  const rowResources = tanstackMetadata(row)?.uiResources ?? []
+  const base =
+    rowResources.length > 0
+      ? withTanstackMetadata(previous, {
+          uiResources: [
+            ...(tanstackMetadata(previous)?.uiResources ?? []),
+            ...rowResources,
+          ],
+        })
+      : previous
+  return {
+    ...base,
+    ...(text !== '' && { content: text }),
+    ...(toolCalls.length > 0 && { toolCalls }),
+    ...(thinking.length > 0 && { thinking }),
+    ...(blockOrder && { blockOrder }),
+  }
+}
+
 function restoreModelMessageCreatedAt(message: ModelMessage): ModelMessage {
   const createdAt =
     coerceCreatedAt(message.createdAt) ?? createdAtFromMetadata(message)
diff --git a/packages/ai/src/activities/chat/stream/processor.ts b/packages/ai/src/activities/chat/stream/processor.ts
index 92015fd37c..0a9ccfda92 100644
--- a/packages/ai/src/activities/chat/stream/processor.ts
+++ b/packages/ai/src/activities/chat/stream/processor.ts
@@ -1518,6 +1518,8 @@ export class StreamProcessor {
    * message. Fold leading thinking-only messages into the next real
    * assistant. Do not fold into a tool-result-only message (`role: 'tool'`
    * on the wire). `reconcileSnapshotToolCalls` anchors those results.
+   * A `<id>-segment-<n>` row folds into its message, together with the
+   * tool-result rows between them (a tool result ends a wire segment).
    */
   private mergeReasoningFanOut(messages: Array<UIMessage>): Array<UIMessage> {
     const out: Array<UIMessage> = []
@@ -1557,13 +1559,27 @@ export class StreamProcessor {
       } else {
         flushPending()
       }
-      const prev = out.at(-1)
+      // Look back past tool-result rows to the message this segment is of.
+      let parentIndex = out.length - 1
+      while (parentIndex >= 0) {
+        const candidate = out[parentIndex]
+        if (!candidate || !isToolResultOnly(candidate)) break
+        parentIndex--
+      }
+      const parent = out[parentIndex]
       if (
-        prev?.role === 'assistant' &&
+        parent?.role === 'assistant' &&
         next.role === 'assistant' &&
-        isAssistantSegmentOf(next.id, prev.id)
+        isAssistantSegmentOf(next.id, parent.id)
       ) {
-        out[out.length - 1] = { ...prev, parts: [...prev.parts, ...next.parts] }
+        // The parent, the tool results after it, then the segment: row order.
+        const folded = out
+          .slice(parentIndex)
+          .flatMap((message) => message.parts)
+        out.splice(parentIndex, out.length - parentIndex, {
+          ...parent,
+          parts: [...folded, ...next.parts],
+        })
         continue
       }
       out.push(next)
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index 9cf05a8981..376cce9510 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -688,6 +688,12 @@ export interface TanStackMessageMetadata {
     errorMessage?: string
   }
   uiResources?: Array<UIResourcePart>
+  /**
+   * On an assistant wire row that exists only to keep the block order: the
+   * id of the assistant row before it. Our server joins the two rows into
+   * one message with a `blockOrder` map. See `uiMessagesToWire`.
+   */
+  continues?: string
 }
 
 /**
diff --git a/packages/ai/src/utilities/ag-ui-wire.ts b/packages/ai/src/utilities/ag-ui-wire.ts
index 0edeb0c37f..930f4ee9f7 100644
--- a/packages/ai/src/utilities/ag-ui-wire.ts
+++ b/packages/ai/src/utilities/ag-ui-wire.ts
@@ -87,7 +87,10 @@ export type WireMessage =
  * on assistant messages are additionally emitted as fan-out
  * `{role:'tool',...}` and `{role:'reasoning',...}` entries for strict AG-UI
  * server consumers. Set `includeSnapshotStructuredOutput` to retain complete
- * structured-output metadata for UI snapshots.
+ * structured-output metadata for UI snapshots. An assistant message whose
+ * parts leave the default block order goes out as several rows in the real
+ * order (see `TanStackMessageMetadata.continues`). A tool result also ends a
+ * row, and its tool row follows that row.
  */
 export function uiMessagesToWire(
   messages: Array<UIMessage | ModelMessage>,
@@ -193,29 +196,145 @@ export function uiMessagesToWire(
     // buildAssistantMessages applies, so the wire keeps the signed order.
     // Segments after the first get derived anchor ids; strict AG-UI consumers
     // still see plain anchors.
+    //
+    // A tool result also ends a segment, the same as in
+    // buildAssistantMessages: the parts after it come from the next model
+    // call. That segment's tool rows go out right after it, and the next
+    // segment becomes its own message on our server.
+    // ponytail: only thinking, text, or a tool call opens that next segment.
+    // Other parts after a tool result (ui-resource, structured output, media)
+    // stay on the ended segment, as today.
+    //
+    // Inside one model call, the message is also split where its parts leave
+    // the default order (all thinking, then text, then tool calls): at
+    // thinking after text or a tool call, and at text after a tool call.
+    // Those rows exist only for the order, so they carry
+    // `metadata.tanstack.continues` with the id of the assistant row before
+    // them. Our server joins them back into one message with a `blockOrder`
+    // map. A provider split keeps today's shape.
     type Segment = {
       thinking: Array<Extract<MessagePart, { type: 'thinking' }>>
       parts: Array<MessagePart>
+      continues: boolean
+      /** A tool result ended this segment. */
+      closed: boolean
     }
-    let current: Segment = { thinking: [], parts: [] }
+    const newSegment = (continues: boolean): Segment => ({
+      thinking: [],
+      parts: [],
+      continues,
+      closed: false,
+    })
+    let current = newSegment(false)
     const segments: Array<Segment> = [current]
     for (const part of parts) {
+      if (
+        current.closed &&
+        (part.type === 'thinking' ||
+          part.type === 'text' ||
+          part.type === 'tool-call')
+      ) {
+        current = newSegment(false)
+        segments.push(current)
+      }
+      const afterCall = current.parts.some((p) => p.type === 'tool-call')
       if (part.type === 'thinking') {
         if (
           current.parts.some(
             (p) => p.type === 'tool-call' && isProviderExecutedToolCall(p),
           )
         ) {
-          current = { thinking: [part], parts: [] }
+          current = newSegment(false)
+          segments.push(current)
+        } else if (afterCall || current.parts.some((p) => p.type === 'text')) {
+          current = newSegment(true)
           segments.push(current)
-        } else {
-          current.thinking.push(part)
         }
+        current.thinking.push(part)
+      } else if (part.type === 'text' && afterCall) {
+        current = newSegment(true)
+        segments.push(current)
+        current.parts.push(part)
       } else {
         current.parts.push(part)
+        if (part.type === 'tool-result') current.closed = true
       }
     }
 
+    const explicitToolResults = new Set(
+      parts.flatMap((part) =>
+        part.type === 'tool-result' ? [part.toolCallId] : [],
+      ),
+    )
+    // The tool rows for `rowParts`, in parts order.
+    const pushToolRows = (rowParts: ReadonlyArray<MessagePart>): void => {
+      for (const part of rowParts) {
+        if (part.type === 'tool-result') {
+          const id = uniqueToolWireId(
+            part.id ?? deriveToolMessageId(part.toolCallId),
+            usedWireIds,
+          )
+          const metadata = rebuiltToolMetadata(
+            part.metadata,
+            part.createdAt,
+            part.id,
+            part.content,
+            true,
+            part.outcome,
+          )
+          wire.push({
+            role: 'tool',
+            id,
+            toolCallId: part.toolCallId,
+            ...(part.name !== undefined && { name: part.name }),
+            content:
+              typeof part.content === 'string'
+                ? part.content
+                : JSON.stringify(part.content),
+            ...(part.error !== undefined && { error: part.error }),
+            ...(metadata !== undefined && { metadata }),
+          })
+        } else if (part.type === 'tool-call') {
+          const approved = part.approval?.approved
+          if (
+            explicitToolResults.has(part.id) ||
+            (part.output === undefined &&
+              (part.state !== 'approval-responded' || approved === undefined))
+          ) {
+            continue
+          }
+          const result =
+            part.output !== undefined
+              ? normalizeToolResult(part.output)
+              : JSON.stringify({
+                  approved,
+                  ...(approved && { pendingExecution: true }),
+                  message: approved
+                    ? 'User approved this action'
+                    : 'User denied this action',
+                })
+          const content =
+            typeof result === 'string' ? result : JSON.stringify(result)
+          wire.push({
+            role: 'tool',
+            id: uniqueToolWireId(deriveToolMessageId(part.id), usedWireIds),
+            toolCallId: part.id,
+            content,
+            metadata: rebuiltToolMetadata(
+              undefined,
+              undefined,
+              undefined,
+              result,
+              false,
+              part.approval?.approved === false ? 'denied' : undefined,
+            ),
+          })
+        }
+      }
+    }
+
+    let previousAnchorId = uiMessage.id
+    let toolParts: Array<MessagePart> = []
     segments.forEach((segment, index) => {
       for (const part of segment.thinking) {
         const reasoning: WireReasoningMessage = {
@@ -238,88 +357,37 @@ export function uiMessagesToWire(
               ...uiMessage,
               id: uniqueWireId(`${uiMessage.id}-segment-${index}`, usedWireIds),
             }
-      wire.push(
-        toAnchor(
-          anchorMessage,
-          'assistant',
-          {
-            ...(text !== '' && { content: text }),
-            ...(toolCalls && { toolCalls }),
-          },
-          segment.parts,
-          includeSnapshotStructuredOutput,
-        ),
+      const anchor = toAnchor(
+        anchorMessage,
+        'assistant',
+        {
+          ...(text !== '' && { content: text }),
+          ...(toolCalls && { toolCalls }),
+        },
+        segment.parts,
+        includeSnapshotStructuredOutput,
       )
-    })
-
-    const explicitToolResults = new Set(
-      parts.flatMap((part) =>
-        part.type === 'tool-result' ? [part.toolCallId] : [],
-      ),
-    )
-    for (const part of parts) {
-      if (part.type === 'tool-result') {
-        const id = uniqueToolWireId(
-          part.id ?? deriveToolMessageId(part.toolCallId),
-          usedWireIds,
-        )
-        const metadata = rebuiltToolMetadata(
-          part.metadata,
-          part.createdAt,
-          part.id,
-          part.content,
-          true,
-          part.outcome,
-        )
-        wire.push({
-          role: 'tool',
-          id,
-          toolCallId: part.toolCallId,
-          ...(part.name !== undefined && { name: part.name }),
-          content:
-            typeof part.content === 'string'
-              ? part.content
-              : JSON.stringify(part.content),
-          ...(part.error !== undefined && { error: part.error }),
-          ...(metadata !== undefined && { metadata }),
-        })
-      } else if (part.type === 'tool-call') {
-        const approved = part.approval?.approved
-        if (
-          explicitToolResults.has(part.id) ||
-          (part.output === undefined &&
-            (part.state !== 'approval-responded' || approved === undefined))
-        ) {
-          continue
+      if (segment.continues) {
+        const metadata = anchor.metadata ?? {}
+        anchor.metadata = {
+          ...metadata,
+          tanstack: {
+            ...(isRecord(metadata.tanstack) ? metadata.tanstack : {}),
+            continues: previousAnchorId,
+          },
         }
-        const result =
-          part.output !== undefined
-            ? normalizeToolResult(part.output)
-            : JSON.stringify({
-                approved,
-                ...(approved && { pendingExecution: true }),
-                message: approved
-                  ? 'User approved this action'
-                  : 'User denied this action',
-              })
-        const content =
-          typeof result === 'string' ? result : JSON.stringify(result)
-        wire.push({
-          role: 'tool',
-          id: uniqueToolWireId(deriveToolMessageId(part.id), usedWireIds),
-          toolCallId: part.id,
-          content,
-          metadata: rebuiltToolMetadata(
-            undefined,
-            undefined,
-            undefined,
-            result,
-            false,
-            part.approval?.approved === false ? 'denied' : undefined,
-          ),
-        })
       }
-    }
+      wire.push(anchor)
+      previousAnchorId = anchor.id
+
+      // A tool row never sits between the rows of one model call: it goes
+      // out after a segment that a tool result ended, or after the last one.
+      toolParts.push(...segment.parts)
+      if (segment.closed || index === segments.length - 1) {
+        pushToolRows(toolParts)
+        toolParts = []
+      }
+    })
 
     for (const part of parts) {
       if (part.type === 'subagent') wire.push(...subagentToWire(part, options))
diff --git a/packages/ai/tests/ag-ui-wire.test.ts b/packages/ai/tests/ag-ui-wire.test.ts
index ed6f78f21d..7f937f6247 100644
--- a/packages/ai/tests/ag-ui-wire.test.ts
+++ b/packages/ai/tests/ag-ui-wire.test.ts
@@ -3,9 +3,19 @@ import type { MessagesSnapshotEvent } from '@ag-ui/core'
 import {
   aguiSnapshotMessageToUIMessage,
   convertMessagesToModelMessages,
+  modelMessagesToUIMessages,
 } from '../src/activities/chat/messages'
+import { StreamProcessor } from '../src/activities/chat/stream/processor'
 import { uiMessagesToWire, type WireMessage } from '../src/utilities/ag-ui-wire'
-import type { ModelMessage, UIMessage } from '../src/types'
+import { tanstackMetadata } from '../src/utilities/merge-metadata'
+import { EventType } from '../src/types'
+import { chunk } from './test-utils'
+import type {
+  ModelMessage,
+  ToolCallPart,
+  UIMessage,
+  UIResourcePart,
+} from '../src/types'
 
 // @ts-expect-error system wire messages require content
 const systemWithoutContent: WireMessage = { id: 'system', role: 'system' }
@@ -1279,3 +1289,337 @@ describe('uiMessagesToWire', () => {
     ).toEqual([first.toISOString(), second.toISOString()])
   })
 })
+
+describe('ordered assistant rows', () => {
+  function callPart(id: string): ToolCallPart {
+    return {
+      type: 'tool-call',
+      id,
+      name: 'lookup',
+      arguments: '{}',
+      state: 'input-complete',
+    }
+  }
+
+  function resource(toolCallId: string): UIResourcePart {
+    return {
+      type: 'ui-resource',
+      resource: {
+        uri: `ui://${toolCallId}`,
+        mimeType: 'text/html',
+        text: '<p></p>',
+      },
+      toolCallId,
+      toolName: 'lookup',
+    }
+  }
+
+  /** The model messages that our server builds from the rows. */
+  function serverMessages(messages: Array<UIMessage>): Array<ModelMessage> {
+    // A request body carries the wire messages as parsed JSON.
+    const body: Array<ModelMessage> = JSON.parse(
+      JSON.stringify(uiMessagesToWire(messages)),
+    )
+    return convertMessagesToModelMessages(body)
+  }
+
+  function rowSummary(wire: Array<WireMessage>) {
+    return wire.map((message) => ({
+      role: message.role,
+      id: message.id,
+      ...(message.role === 'assistant' && {
+        content: message.content,
+        continues: message.metadata?.tanstack?.continues,
+      }),
+    }))
+  }
+
+  const thinkingAndText: UIMessage = {
+    id: 'm1',
+    role: 'assistant',
+    parts: [
+      { type: 'thinking', content: 'plan', signature: 'sig-a' },
+      { type: 'text', content: 'A' },
+      { type: 'thinking', content: 'check', signature: 'sig-b' },
+      { type: 'text', content: 'B' },
+    ],
+  }
+
+  it("keeps today's rows for a message in the default order", () => {
+    const wire = uiMessagesToWire([
+      {
+        id: 'm1',
+        role: 'assistant',
+        parts: [
+          { type: 'thinking', content: 'plan', signature: 'sig-a' },
+          { type: 'text', content: 'Hello' },
+          callPart('call_1'),
+        ],
+      },
+    ])
+
+    expect(wire).toEqual([
+      {
+        role: 'reasoning',
+        id: expect.any(String),
+        content: 'plan',
+        encryptedValue: 'sig-a',
+      },
+      {
+        id: 'm1',
+        role: 'assistant',
+        content: 'Hello',
+        toolCalls: [
+          {
+            id: 'call_1',
+            type: 'function',
+            function: { name: 'lookup', arguments: '{}' },
+          },
+        ],
+      },
+    ])
+  })
+
+  it('sends thinking, text, thinking, text as ordered rows', () => {
+    expect(rowSummary(uiMessagesToWire([thinkingAndText]))).toEqual([
+      { role: 'reasoning', id: expect.any(String) },
+      { role: 'assistant', id: 'm1', content: 'A', continues: undefined },
+      { role: 'reasoning', id: expect.any(String) },
+      { role: 'assistant', id: 'm1-segment-1', content: 'B', continues: 'm1' },
+    ])
+  })
+
+  it('starts a row at text after a tool call', () => {
+    const message: UIMessage = {
+      id: 'm1',
+      role: 'assistant',
+      parts: [
+        { type: 'text', content: 'Looking.' },
+        callPart('call_1'),
+        { type: 'text', content: 'Found it.' },
+      ],
+    }
+
+    expect(rowSummary(uiMessagesToWire([message]))).toEqual([
+      {
+        role: 'assistant',
+        id: 'm1',
+        content: 'Looking.',
+        continues: undefined,
+      },
+      {
+        role: 'assistant',
+        id: 'm1-segment-1',
+        content: 'Found it.',
+        continues: 'm1',
+      },
+    ])
+    expect(serverMessages([message])).toMatchObject([
+      {
+        content: 'Looking.Found it.',
+        toolCalls: [{ id: 'call_1' }],
+        blockOrder: [
+          { type: 'text', length: 8 },
+          { type: 'tool-call', id: 'call_1' },
+          { type: 'text', length: 9 },
+        ],
+      },
+    ])
+  })
+
+  it('ends a row at a tool result and keeps the next model call as its own message', () => {
+    // Two model calls in one UIMessage: thinking and a tool call, the tool
+    // result, then thinking and the answer.
+    const message: UIMessage = {
+      id: 'm1',
+      role: 'assistant',
+      parts: [
+        { type: 'thinking', content: 'plan', signature: 'sig-a' },
+        { ...callPart('call_1'), state: 'complete', output: { ok: true } },
+        {
+          type: 'tool-result',
+          toolCallId: 'call_1',
+          content: '{"ok":true}',
+          state: 'complete',
+        },
+        { type: 'thinking', content: 'answer', signature: 'sig-b' },
+        { type: 'text', content: 'It is ok.' },
+      ],
+    }
+    const wire = uiMessagesToWire([message])
+
+    // The tool row sits at its place. The second row does not continue the
+    // first, because a tool result is between them.
+    expect(rowSummary(wire)).toEqual([
+      { role: 'reasoning', id: expect.any(String) },
+      { role: 'assistant', id: 'm1', content: undefined, continues: undefined },
+      { role: 'tool', id: 'tool-call_1' },
+      { role: 'reasoning', id: expect.any(String) },
+      {
+        role: 'assistant',
+        id: 'm1-segment-1',
+        content: 'It is ok.',
+        continues: undefined,
+      },
+    ])
+
+    // Our server rebuilds the order Anthropic needs. No map is needed.
+    expect(
+      serverMessages([message]).map((model) => ({
+        role: model.role,
+        content: model.content,
+        thinking: model.thinking?.map((block) => block.content),
+        toolCalls: model.toolCalls?.map((toolCall) => toolCall.id),
+        blockOrder: model.blockOrder,
+      })),
+    ).toEqual([
+      {
+        role: 'assistant',
+        content: undefined,
+        thinking: ['plan'],
+        toolCalls: ['call_1'],
+        blockOrder: undefined,
+      },
+      {
+        role: 'tool',
+        content: '{"ok":true}',
+        thinking: undefined,
+        toolCalls: undefined,
+        blockOrder: undefined,
+      },
+      {
+        role: 'assistant',
+        content: 'It is ok.',
+        thinking: ['answer'],
+        toolCalls: undefined,
+        blockOrder: undefined,
+      },
+    ])
+
+    // Both fold-back paths give one UIMessage in the original order.
+    const order = ['thinking', 'tool-call', 'tool-result', 'thinking', 'text']
+    const [back] = modelMessagesToUIMessages(serverMessages([message]))
+    expect(back?.parts.map((part) => part.type)).toEqual(order)
+
+    const processor = new StreamProcessor({})
+    processor.processChunk(
+      chunk(EventType.MESSAGES_SNAPSHOT, { messages: wire }),
+    )
+    expect(
+      processor.getMessages().map((ui) => ui.parts.map((part) => part.type)),
+    ).toEqual([order])
+  })
+
+  it('joins the rows into the message that the converter writes', () => {
+    const joined = serverMessages([thinkingAndText])
+
+    expect(joined).toEqual(convertMessagesToModelMessages([thinkingAndText]))
+    expect(joined[0]?.blockOrder).toEqual([
+      { type: 'thinking', index: 0 },
+      { type: 'text', length: 1 },
+      { type: 'thinking', index: 1 },
+      { type: 'text', length: 1 },
+    ])
+  })
+
+  it('joins a client-tool answer into one assistant message', () => {
+    const answer: UIMessage = {
+      id: 'm1',
+      role: 'assistant',
+      parts: [
+        { type: 'thinking', content: 'plan', signature: 'sig-a' },
+        { ...callPart('call_1'), state: 'complete', output: { ok: true } },
+        { type: 'thinking', content: 'next', signature: 'sig-b' },
+        { ...callPart('call_2'), state: 'complete', output: { ok: true } },
+      ],
+    }
+
+    const messages = serverMessages([answer])
+
+    expect(messages.map((message) => message.role)).toEqual([
+      'assistant',
+      'tool',
+      'tool',
+    ])
+    expect(messages[0]).toMatchObject({
+      thinking: [
+        { content: 'plan', signature: 'sig-a' },
+        { content: 'next', signature: 'sig-b' },
+      ],
+      toolCalls: [{ id: 'call_1' }, { id: 'call_2' }],
+      blockOrder: [
+        { type: 'thinking', index: 0 },
+        { type: 'tool-call', id: 'call_1' },
+        { type: 'thinking', index: 1 },
+        { type: 'tool-call', id: 'call_2' },
+      ],
+    })
+  })
+
+  it('keeps the ui resources of every joined row', () => {
+    const answer: UIMessage = {
+      id: 'm1',
+      role: 'assistant',
+      parts: [
+        { type: 'text', content: 'First.' },
+        { ...callPart('call_1'), state: 'complete', output: { ok: true } },
+        resource('call_1'),
+        { type: 'text', content: 'Second.' },
+        { ...callPart('call_2'), state: 'complete', output: { ok: true } },
+        resource('call_2'),
+      ],
+    }
+
+    const assistant = serverMessages([answer]).find(
+      (message) => message.role === 'assistant',
+    )
+
+    expect(tanstackMetadata(assistant)?.uiResources).toEqual([
+      resource('call_1'),
+      resource('call_2'),
+    ])
+  })
+
+  it('keeps subagent text on a message that was sent as ordered rows', () => {
+    const message: UIMessage = {
+      id: 'a1',
+      role: 'assistant',
+      parts: [
+        { type: 'text', content: 'Looking.' },
+        { ...callPart('call_1'), state: 'complete', output: { ok: true } },
+        { type: 'text', content: 'Found it.' },
+        {
+          type: 'subagent',
+          subagent: {
+            id: 'run-researcher',
+            name: 'researcher',
+            status: 'finished',
+            messages: [
+              {
+                id: 'note',
+                role: 'assistant',
+                parts: [{ type: 'text', content: 'Squids have three hearts.' }],
+              },
+            ],
+          },
+        },
+      ],
+    }
+
+    const assistants = serverMessages([message]).filter(
+      (candidate) => candidate.role === 'assistant',
+    )
+
+    expect(assistants).toHaveLength(1)
+    expect(assistants[0]?.content).toBe(
+      'Looking.Found it.\n\nresearcher:\nSquids have three hearts.',
+    )
+  })
+
+  it('folds the joined message back into one UIMessage in order', () => {
+    const back = modelMessagesToUIMessages(serverMessages([thinkingAndText]))
+
+    expect(back).toHaveLength(1)
+    expect(back[0]?.parts).toEqual(thinkingAndText.parts)
+  })
+})
diff --git a/packages/ai/tests/chat-block-order.test.ts b/packages/ai/tests/chat-block-order.test.ts
index 6ad3279029..1e54a25e38 100644
--- a/packages/ai/tests/chat-block-order.test.ts
+++ b/packages/ai/tests/chat-block-order.test.ts
@@ -1,5 +1,8 @@
 import { describe, expect, it } from 'vitest'
 import { chat } from '../src/activities/chat'
+import { convertMessagesToModelMessages } from '../src/activities/chat/messages'
+import { StreamProcessor } from '../src/activities/chat/stream/processor'
+import { tanstackMetadata } from '../src/utilities/merge-metadata'
 import { EventType } from '../src/types'
 import {
   chunk,
@@ -199,4 +202,71 @@ describe('chat() block order', () => {
       ],
     })
   })
+
+  it('sends a client-tool answer as ordered rows that fold back into one message', async () => {
+    const { adapter } = createMockAdapter({
+      iterations: [
+        [
+          ev.runStarted(),
+          ...reasoning('step-1', 'plan', 'sig-a'),
+          ...callTool('call_1', 'pick'),
+          ...reasoning('step-2', 'next', 'sig-b'),
+          ...callTool('call_2', 'pick'),
+          ev.runFinished('tool_calls'),
+        ],
+      ],
+    })
+    const chunks = await collectChunks(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'Pick two' }],
+        tools: [clientTool('pick')],
+      }) as AsyncIterable<StreamChunk>,
+    )
+    const snapshot = chunks.find(
+      (candidate) => candidate.type === EventType.MESSAGES_SNAPSHOT,
+    )
+    if (snapshot?.type !== EventType.MESSAGES_SNAPSHOT) {
+      throw new Error('missing MESSAGES_SNAPSHOT')
+    }
+
+    // The wire keeps the real order. The second row continues the first.
+    const turn = snapshot.messages.filter((message) => message.role !== 'user')
+    expect(
+      turn.map((message) =>
+        message.role === 'assistant'
+          ? {
+              role: message.role,
+              toolCalls: message.toolCalls?.map((toolCall) => toolCall.id),
+              continues: tanstackMetadata(message)?.continues,
+            }
+          : { role: message.role },
+      ),
+    ).toEqual([
+      { role: 'reasoning' },
+      { role: 'assistant', toolCalls: ['call_1'], continues: undefined },
+      { role: 'reasoning' },
+      { role: 'assistant', toolCalls: ['call_2'], continues: turn[1]?.id },
+    ])
+
+    // The client shows one message in the real order.
+    const processor = new StreamProcessor({})
+    processor.processChunk(snapshot)
+    expect(
+      processor
+        .getMessages()
+        .filter((message) => message.role === 'assistant')
+        .map((message) => message.parts.map((part) => part.type)),
+    ).toEqual([['thinking', 'tool-call', 'thinking', 'tool-call']])
+
+    // Our server joins the rows back into the message that chat() stored.
+    const body: Array<ModelMessage> = JSON.parse(
+      JSON.stringify(snapshot.messages),
+    )
+    expect(
+      convertMessagesToModelMessages(body)
+        .filter((message) => message.role === 'assistant')
+        .map((message) => message.blockOrder),
+    ).toEqual([interleavedCalls])
+  })
 })
diff --git a/packages/ai/tests/chat-provider-executed-thinking-order.test.ts b/packages/ai/tests/chat-provider-executed-thinking-order.test.ts
index 8ad39f28d2..084c33c1d5 100644
--- a/packages/ai/tests/chat-provider-executed-thinking-order.test.ts
+++ b/packages/ai/tests/chat-provider-executed-thinking-order.test.ts
@@ -6,6 +6,7 @@ import {
 } from '../src/activities/chat/messages'
 import { StreamProcessor } from '../src/activities/chat/stream/processor'
 import { uiMessagesToWire } from '../src/utilities/ag-ui-wire'
+import { tanstackMetadata } from '../src/utilities/merge-metadata'
 import {
   chunk,
   clientTool,
@@ -122,9 +123,11 @@ describe('provider-executed tools interleaved with signed thinking', () => {
         {
           role: 'assistant',
           id: 'm1-segment-1',
-          content: 'Searching again.Done.',
+          content: 'Searching again.',
           toolCalls: ['srvtoolu_2'],
         },
+        // Text after a tool call gets its own row. Our server joins it back.
+        { role: 'assistant', id: 'm1-segment-2', content: 'Done.' },
       ])
 
       // Every anchor carries the metadata for its own tool calls.
@@ -135,7 +138,12 @@ describe('provider-executed tools interleaved with signed thinking', () => {
             (anchor.metadata as any)?.tanstack?.toolCallMetadata ?? {},
           ),
         ),
-      ).toEqual([['srvtoolu_1'], ['srvtoolu_2']])
+      ).toEqual([['srvtoolu_1'], ['srvtoolu_2'], []])
+      // Only the row split for the order continues a row. The row split for
+      // the provider tool keeps today's shape.
+      expect(
+        anchors.map((anchor) => tanstackMetadata(anchor)?.continues),
+      ).toEqual([undefined, undefined, 'm1-segment-1'])
 
       // The server-side converter attaches each reasoning message to the
       // anchor that follows it, so the model history keeps the signed order.
@@ -160,7 +168,7 @@ describe('provider-executed tools interleaved with signed thinking', () => {
       ])
     })
 
-    it('keeps a single anchor when thinking never follows a provider tool', () => {
+    it('starts an ordered row at thinking that follows a local tool call', () => {
       const uiMessage: UIMessage = {
         id: 'm1',
         role: 'assistant',
@@ -182,11 +190,20 @@ describe('provider-executed tools interleaved with signed thinking', () => {
 
       expect(wire.map((message) => message.role)).toEqual([
         'reasoning',
+        'assistant',
         'reasoning',
         'assistant',
       ])
-      expect(wire.filter((message) => message.role === 'assistant')).toEqual([
-        expect.objectContaining({ id: 'm1', content: 'Hello' }),
+      expect(
+        wire
+          .filter((message) => message.role === 'assistant')
+          .map((anchor) => ({
+            id: anchor.id,
+            continues: tanstackMetadata(anchor)?.continues,
+          })),
+      ).toEqual([
+        { id: 'm1', continues: undefined },
+        { id: 'm1-segment-1', continues: 'm1' },
       ])
     })
   })

From 723e2a52da1971938a19cf14ffd7d30e9da1e274 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 16:00:33 +0200
Subject: [PATCH 183/286] feat(ai-openai): use mid-conversation channels on the
 GPT models that have them

A new model map gives the 10 GPT models from pi both channels. They are on by default only for OpenAI's own API: a baseURL, a fetch, or OPENAI_BASE_URL turns the default off. The config option midConversationChannels turns them on (true) or off (false). The adapter overrides convertTools, so the start set and additional_tools use the OpenAI tool converter, and the prompt cache fields stay as they are. Other models and custom endpoints send the same request as before.
---
 packages/ai-openai/src/adapters/text.ts       |  93 ++++--
 packages/ai-openai/src/model-meta.ts          |  24 +-
 .../tests/mid-conversation-changes.test.ts    | 284 ++++++++++++++++++
 3 files changed, 370 insertions(+), 31 deletions(-)
 create mode 100644 packages/ai-openai/tests/mid-conversation-changes.test.ts

diff --git a/packages/ai-openai/src/adapters/text.ts b/packages/ai-openai/src/adapters/text.ts
index 66b87f7f11..090009d659 100644
--- a/packages/ai-openai/src/adapters/text.ts
+++ b/packages/ai-openai/src/adapters/text.ts
@@ -1,14 +1,12 @@
 import OpenAI from 'openai'
-import {
-  OpenAIBaseResponsesTextAdapter,
-  warnStrictFallback,
-} from '@tanstack/openai-base'
+import { OpenAIBaseResponsesTextAdapter } from '@tanstack/openai-base'
 import { OPENAI_MODEL_REASONING } from '../model-reasoning'
 import { validateTextProviderOptions } from '../text/text-provider-options'
 import { convertToolsToProviderFormat } from '../tools'
 import { getOpenAIApiKeyFromEnv } from '../utils/client'
 import {
   OPENAI_MODEL_INPUT_MODALITIES,
+  OPENAI_MODEL_MID_CONVERSATION_CHANNELS,
   openAIModelRejectsSamplingParams,
   openAIModelUsesExplicitPromptCache,
 } from '../model-meta'
@@ -20,8 +18,16 @@ import type {
   OpenAIChatModelToolCapabilitiesByName,
   OpenAIModelInputModalitiesByName,
 } from '../model-meta'
-import type { ResponseCreateParams } from 'openai/resources/responses/responses'
-import type { Modality, TextOptions } from '@tanstack/ai'
+import type {
+  ResponseCreateParams,
+  Tool as ResponsesTool,
+} from 'openai/resources/responses/responses'
+import type {
+  AnyTool,
+  MidConversationChannels,
+  Modality,
+  TextOptions,
+} from '@tanstack/ai'
 import type { OpenAIModelReasoningByName } from '../model-reasoning'
 import type {
   ExternalTextProviderOptions,
@@ -35,7 +41,18 @@ import type { OpenAIBaseTextAdapterOptions } from '@tanstack/openai-base'
  * Configuration for OpenAI text adapter
  */
 export interface OpenAITextConfig
-  extends OpenAIClientConfig, OpenAIBaseTextAdapterOptions {}
+  extends OpenAIClientConfig, OpenAIBaseTextAdapterOptions {
+  /**
+   * The mid-conversation channels (`additional_tools` and a mid-conversation
+   * `developer` message) of the models in
+   * `OPENAI_MODEL_MID_CONVERSATION_CHANNELS`. When absent, they are on only
+   * for OpenAI's own API: a `baseURL`, a `fetch`, or the SDK's
+   * `OPENAI_BASE_URL` env var turns the default off.
+   * `true` turns them on anyway, for a gateway that passes the changes.
+   * `false` turns them off, so every request is built as before.
+   */
+  midConversationChannels?: boolean
+}
 
 /**
  * Alias for TextProviderOptions
@@ -89,10 +106,10 @@ type ResolveToolCapabilities<TModel extends string> =
  * Tree-shakeable adapter for OpenAI chat/text completion functionality.
  * Delegates implementation to {@link OpenAIBaseResponsesTextAdapter} from
  * `@tanstack/openai-base`. The base calls `openai.responses.create`
- * directly; this subclass just hands it a configured client and overrides
- * `mapOptionsToRequest` to route through OpenAI's full tool converter
- * (supporting file_search, web_search, etc.) and to apply provider option
- * validation.
+ * directly; this subclass hands it a configured client, overrides
+ * `convertTools` to use OpenAI's full tool converter (supporting
+ * file_search, web_search, etc.), and overrides `mapOptionsToRequest` to
+ * apply provider option validation.
  */
 export class OpenAITextAdapter<
   TModel extends OpenAIChatModel,
@@ -117,20 +134,40 @@ export class OpenAITextAdapter<
   // — which have no such surface — fail closed in preflight.
   override readonly supportsFileSources = true
   override readonly inputModalities = OPENAI_MODEL_INPUT_MODALITIES[this.model]
+  /** Set from `OPENAI_MODEL_MID_CONVERSATION_CHANNELS` in the constructor. */
+  override readonly midConversationChannels:
+    | MidConversationChannels
+    | undefined = undefined
 
   constructor(config: OpenAITextConfig, model: TModel) {
     super(model, 'openai', new OpenAI(config), config)
+    // On by default only on OpenAI's own API: a proxy or a gateway (a
+    // `baseURL`, a `fetch`, or the SDK's OPENAI_BASE_URL env var) may not
+    // pass the changes. The option wins.
+    const envBaseURL =
+      typeof process !== 'undefined' && Boolean(process.env.OPENAI_BASE_URL)
+    if (
+      config.midConversationChannels ??
+      !(config.baseURL || config.fetch || envBaseURL)
+    ) {
+      this.midConversationChannels =
+        OPENAI_MODEL_MID_CONVERSATION_CHANNELS[model]
+    }
   }
 
   protected override modelReasoning(model: string) {
     return OPENAI_MODEL_REASONING[model]
   }
 
+  /** OpenAI's full tool converter (file_search, web_search, etc.). */
+  protected override convertTools(tools: Array<AnyTool>): Array<ResponsesTool> {
+    return convertToolsToProviderFormat(tools)
+  }
+
   /**
    * Maps common options to OpenAI-specific format.
-   * Overrides the base class to use OpenAI's full tool converter
-   * (supporting special tool types like file_search, web_search, etc.)
-   * and to apply OpenAI-specific provider option validation.
+   * Overrides the base class to apply OpenAI-specific provider option
+   * validation and request fields. The tools go through `convertTools`.
    */
   protected override mapOptionsToRequest(
     options: TextOptions<TProviderOptions>,
@@ -149,22 +186,18 @@ export class OpenAITextAdapter<
       })
     }
 
-    // Delegate to the base for input mapping, system prompts, modelOptions
-    // precedence, and native combined-mode `text.format` wiring (#605). We
-    // hand it a tools-less view of `options` so the base doesn't run its
-    // narrower tool converter — we re-run them through OpenAI's full
-    // converter (file_search, web_search, etc.) and layer the result on top.
-    const { tools: _baseTools, ...baseRequest } = super.mapOptionsToRequest({
-      ...options,
-      tools: undefined,
-    })
-
-    if (this.strictFallbackWarning) {
-      warnStrictFallback(options.tools, options.logger)
-    }
-    const tools = options.tools
-      ? convertToolsToProviderFormat(options.tools)
-      : undefined
+    // Delegate to the base for input mapping, system prompts, tools,
+    // modelOptions precedence, and native combined-mode `text.format` wiring
+    // (#605). The base converts the tools with `convertTools` (OpenAI's full
+    // converter), so a mid-conversation change sends the start set and its
+    // `additional_tools` items in this format too. The base also gives the
+    // strict-fallback warning.
+    const { tools: baseTools, ...baseRequest } = super.mapOptionsToRequest(
+      options,
+    )
+    // Only tools from `options.tools`, as before: the base also keeps a
+    // `modelOptions.tools`, which this adapter has never sent.
+    const tools = options.tools?.length ? baseTools : undefined
 
     // `chat({ promptCache })` fields go first, so a value the caller set in
     // `modelOptions` (already on `baseRequest`) wins.
diff --git a/packages/ai-openai/src/model-meta.ts b/packages/ai-openai/src/model-meta.ts
index 96bdf07198..6af58e0a1e 100644
--- a/packages/ai-openai/src/model-meta.ts
+++ b/packages/ai-openai/src/model-meta.ts
@@ -1,4 +1,4 @@
-import type { Modality } from '@tanstack/ai'
+import type { MidConversationChannels, Modality } from '@tanstack/ai'
 import type {
   OpenAIBaseOptions,
   OpenAIMetadataOptions,
@@ -3399,3 +3399,25 @@ export const OPENAI_MODEL_INPUT_MODALITIES: Readonly<
   [GPT_6_1_SOL.name]: GPT_6_1_SOL.supports.input,
   [GPT_6_1_SOL_PRO.name]: GPT_6_1_SOL_PRO.supports.input,
 } satisfies OpenAIModelInputModalitiesByName
+
+/**
+ * The mid-conversation channels of each Responses model (from pi 0.87.1):
+ * added tools go out as an `additional_tools` item, and added prompts as a
+ * mid-conversation `developer` message. An unknown name gives `undefined`,
+ * so the adapter has no channels. `gpt-5.4` and `gpt-5.4-pro` are on pi's
+ * list but not in {@link OPENAI_CHAT_MODELS} yet, so the keys are strings.
+ */
+export const OPENAI_MODEL_MID_CONVERSATION_CHANNELS: Readonly<
+  Record<string, MidConversationChannels>
+> = {
+  'gpt-5.4': { tools: true, systemPrompts: true },
+  [GPT_5_4_MINI.name]: { tools: true, systemPrompts: true },
+  'gpt-5.4-pro': { tools: true, systemPrompts: true },
+  [GPT_5_5.name]: { tools: true, systemPrompts: true },
+  [GPT_5_6_LUNA.name]: { tools: true, systemPrompts: true },
+  [GPT_5_6_SOL.name]: { tools: true, systemPrompts: true },
+  [GPT_5_6_TERRA.name]: { tools: true, systemPrompts: true },
+  [GPT_6_ASTRA.name]: { tools: true, systemPrompts: true },
+  [GPT_6_LUNA.name]: { tools: true, systemPrompts: true },
+  [GPT_6_SOL.name]: { tools: true, systemPrompts: true },
+}
diff --git a/packages/ai-openai/tests/mid-conversation-changes.test.ts b/packages/ai-openai/tests/mid-conversation-changes.test.ts
new file mode 100644
index 0000000000..b12fcb96b3
--- /dev/null
+++ b/packages/ai-openai/tests/mid-conversation-changes.test.ts
@@ -0,0 +1,284 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { OpenAITextAdapter, createOpenaiChat } from '../src/adapters/text'
+import { OPENAI_MODEL_MID_CONVERSATION_CHANNELS } from '../src/model-meta'
+import { convertToolsToProviderFormat, webSearchTool } from '../src/tools'
+import type {
+  MidConversationChanges,
+  ModelMessage,
+  TextOptions,
+  Tool,
+} from '@tanstack/ai'
+import type { OpenAITextConfig } from '../src/adapters/text'
+
+const logger = resolveDebugOption(false)
+// Constructing the SDK client makes no network call.
+const config = { apiKey: 'sk-test' }
+
+// A proxy in OPENAI_BASE_URL on this machine would turn the default off.
+// Clear it, so each test starts from OpenAI's own API.
+beforeEach(() => {
+  vi.stubEnv('OPENAI_BASE_URL', '')
+})
+afterEach(() => {
+  vi.unstubAllEnvs()
+})
+const both = { tools: true, systemPrompts: true }
+/** Configs that do not talk to OpenAI's own API. */
+const customEndpoints = [
+  { baseURL: 'https://gateway.example.com/v1' },
+  { fetch: vi.fn() },
+]
+
+/** A Responses stream that completes at once. */
+function completedStream() {
+  return (async function* () {
+    yield {
+      type: 'response.created',
+      response: { id: 'resp-1', model: 'gpt-5.5', status: 'in_progress' },
+    }
+    yield {
+      type: 'response.completed',
+      response: {
+        id: 'resp-1',
+        model: 'gpt-5.5',
+        status: 'completed',
+        output: [],
+        usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
+      },
+    }
+  })()
+}
+
+/** Run one call on a stub client and give back the request body. */
+async function send(
+  model: 'gpt-5.5' | 'gpt-4o',
+  options: Pick<
+    TextOptions,
+    | 'messages'
+    | 'tools'
+    | 'systemPrompts'
+    | 'midConversationChanges'
+    | 'promptCache'
+  >,
+  extra: Omit<OpenAITextConfig, 'apiKey'> = {},
+) {
+  const adapter = new OpenAITextAdapter({ ...config, ...extra }, model)
+  const create = vi.fn<(...args: Array<any>) => any>(() =>
+    Promise.resolve(completedStream()),
+  )
+  Object.assign(adapter, { client: { responses: { create } } })
+  for await (const chunk of adapter.chatStream({
+    logger,
+    model,
+    ...options,
+  })) {
+    if (chunk.type === 'RUN_ERROR') throw new Error(chunk.message)
+  }
+  return create.mock.calls[0]![0]
+}
+
+const lookup: Tool = { name: 'lookup', description: 'Look a thing up' }
+const fetchPage: Tool = { name: 'fetch_page', description: 'Fetch a page' }
+
+/** A user turn, an answer that called `lookup`, and the tool result. */
+const toolTurn: Array<ModelMessage> = [
+  { role: 'user', content: 'Find the page' },
+  {
+    role: 'assistant',
+    content: null,
+    toolCalls: [
+      {
+        id: 'call-1',
+        type: 'function',
+        function: { name: 'lookup', arguments: '{}' },
+      },
+    ],
+  },
+  { role: 'tool', toolCallId: 'call-1', content: 'https://example.com' },
+]
+
+/** After the tool result, `fetch_page` and a second prompt came. */
+const endChange: MidConversationChanges = {
+  start: { tools: ['lookup'], systemPrompts: 1 },
+  changes: [{ before: 3, tools: ['fetch_page'], systemPrompts: 1 }],
+}
+
+describe('OpenAI mid-conversation channels', () => {
+  it('lists the ten models from pi with both channels', () => {
+    expect(Object.keys(OPENAI_MODEL_MID_CONVERSATION_CHANNELS).sort()).toEqual(
+      [
+        'gpt-5.4',
+        'gpt-5.4-mini',
+        'gpt-5.4-pro',
+        'gpt-5.5',
+        'gpt-5.6-luna',
+        'gpt-5.6-sol',
+        'gpt-5.6-terra',
+        'gpt-6-astra',
+        'gpt-6-luna',
+        'gpt-6-sol',
+      ].sort(),
+    )
+    for (const channels of Object.values(
+      OPENAI_MODEL_MID_CONVERSATION_CHANNELS,
+    )) {
+      expect(channels).toEqual(both)
+    }
+  })
+
+  it('gives the adapter the channels of its model', () => {
+    expect(
+      new OpenAITextAdapter(config, 'gpt-5.5').midConversationChannels,
+    ).toEqual(both)
+    expect(
+      new OpenAITextAdapter(config, 'gpt-4o').midConversationChannels,
+    ).toBeUndefined()
+  })
+
+  it('is off by default with a custom baseURL or a custom fetch', () => {
+    for (const endpoint of customEndpoints) {
+      expect(
+        new OpenAITextAdapter({ ...config, ...endpoint }, 'gpt-5.5')
+          .midConversationChannels,
+      ).toBeUndefined()
+    }
+  })
+
+  it('is off by default when the SDK reads a proxy from OPENAI_BASE_URL', () => {
+    vi.stubEnv('OPENAI_BASE_URL', 'https://proxy.example.com/v1')
+    try {
+      expect(
+        new OpenAITextAdapter(config, 'gpt-5.5').midConversationChannels,
+      ).toBeUndefined()
+      expect(
+        new OpenAITextAdapter(
+          { ...config, midConversationChannels: true },
+          'gpt-5.5',
+        ).midConversationChannels,
+      ).toEqual(both)
+    } finally {
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it('turns on with midConversationChannels: true on a custom endpoint', () => {
+    for (const endpoint of customEndpoints) {
+      expect(
+        new OpenAITextAdapter(
+          { ...config, ...endpoint, midConversationChannels: true },
+          'gpt-5.5',
+        ).midConversationChannels,
+      ).toEqual(both)
+    }
+  })
+
+  it('is off with midConversationChannels: false, and outside the map even with true', () => {
+    expect(
+      new OpenAITextAdapter(
+        { ...config, midConversationChannels: false },
+        'gpt-5.5',
+      ).midConversationChannels,
+    ).toBeUndefined()
+    expect(
+      createOpenaiChat('gpt-5.5', 'sk-test', { midConversationChannels: false })
+        .midConversationChannels,
+    ).toBeUndefined()
+    expect(
+      new OpenAITextAdapter(
+        { ...config, midConversationChannels: true },
+        'gpt-4o',
+      ).midConversationChannels,
+    ).toBeUndefined()
+  })
+})
+
+describe('OpenAI mid-conversation request', () => {
+  it('converts the start set and additional_tools with the OpenAI tool converter', async () => {
+    const body = await send('gpt-5.5', {
+      messages: toolTurn,
+      tools: [lookup, fetchPage],
+      systemPrompts: ['Be brief.', 'Cite sources.'],
+      midConversationChanges: endChange,
+    })
+
+    expect(body.tools).toEqual(convertToolsToProviderFormat([lookup]))
+    expect(body.instructions).toBe('Be brief.')
+    expect(body.input.slice(3)).toEqual([
+      {
+        type: 'additional_tools',
+        role: 'developer',
+        tools: convertToolsToProviderFormat([fetchPage]),
+      },
+      { role: 'developer', content: 'Cite sources.' },
+    ])
+  })
+
+  it('keeps the full tools list and the web search include for a provider tool', async () => {
+    const webSearch = webSearchTool({ type: 'web_search' })
+    const body = await send('gpt-5.5', {
+      messages: toolTurn,
+      tools: [lookup, webSearch, fetchPage],
+      systemPrompts: ['Be brief.', 'Cite sources.'],
+      midConversationChanges: {
+        start: { tools: ['lookup', 'web_search'], systemPrompts: 1 },
+        changes: [{ before: 3, tools: ['fetch_page'], systemPrompts: 1 }],
+      },
+    })
+
+    expect(body.tools).toEqual(
+      convertToolsToProviderFormat([lookup, webSearch, fetchPage]),
+    )
+    expect(body.include).toContain('web_search_call.action.sources')
+    expect(body.input.slice(3)).toEqual([
+      { role: 'developer', content: 'Cite sources.' },
+    ])
+  })
+
+  it('keeps the prompt cache fields next to additional_tools', async () => {
+    const body = await send('gpt-5.5', {
+      messages: toolTurn,
+      tools: [lookup, fetchPage],
+      systemPrompts: ['Be brief.', 'Cite sources.'],
+      midConversationChanges: endChange,
+      promptCache: { retention: 'long', key: 'thread-1' },
+    })
+
+    expect(body.prompt_cache_key).toBe('thread-1')
+    expect(body.prompt_cache_retention).toBe('24h')
+    expect(body.tools).toEqual(convertToolsToProviderFormat([lookup]))
+    expect(body.input[3]).toEqual({
+      type: 'additional_tools',
+      role: 'developer',
+      tools: convertToolsToProviderFormat([fetchPage]),
+    })
+  })
+
+  it("sends today's request when off, on a custom endpoint, and outside the map", async () => {
+    const options = {
+      messages: toolTurn,
+      tools: [lookup, fetchPage],
+      systemPrompts: ['Be brief.', 'Cite sources.'],
+      promptCache: { retention: 'short' as const, key: 'thread-1' },
+    }
+    const cases = [
+      ['gpt-5.5', { midConversationChannels: false }],
+      ['gpt-5.5', { baseURL: 'https://gateway.example.com/v1' }],
+      ['gpt-4o', {}],
+    ] as const
+    for (const [model, extra] of cases) {
+      const today = await send(model, options, extra)
+      const body = await send(
+        model,
+        { ...options, midConversationChanges: endChange },
+        extra,
+      )
+
+      expect(JSON.stringify(body)).toBe(JSON.stringify(today))
+      expect(today.tools).toEqual(
+        convertToolsToProviderFormat([lookup, fetchPage]),
+      )
+      expect(today.prompt_cache_key).toBe('thread-1')
+    }
+  })
+})

From 017ac06a10be1090148d212554dcab1cce6b038f Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 16:00:33 +0200
Subject: [PATCH 184/286] feat(ai-anthropic): use mid-conversation channels on
 the Claude models that have them

A new model map gives the 5 Claude models from pi both channels. They are on by default only for Anthropic's own API: a baseURL, a fetch, ANTHROPIC_BASE_URL, or an injected client turns the default off. The config option midConversationChannels turns them on (true) or off (false). A change goes out as a system message before the next assistant message, or at the end. In tool mode the request gets the tool-change beta, a deferred placeholder tool, deferred added tools, and tool_addition blocks. The automatic tool cache marker goes on the last start tool, and a system message at the end takes the message marker. A provider tool keeps the full tools list. Other models, custom endpoints, and Vertex send the same request as before.
---
 packages/ai-anthropic/src/adapters/text.ts    | 195 ++++++-
 packages/ai-anthropic/src/model-meta.ts       |  18 +-
 packages/ai-anthropic/src/prompt-cache.ts     |  45 +-
 .../src/text/text-provider-options.ts         |   4 +-
 .../tests/mid-conversation-changes.test.ts    | 508 ++++++++++++++++++
 5 files changed, 749 insertions(+), 21 deletions(-)
 create mode 100644 packages/ai-anthropic/tests/mid-conversation-changes.test.ts

diff --git a/packages/ai-anthropic/src/adapters/text.ts b/packages/ai-anthropic/src/adapters/text.ts
index 29288f2065..91584265a7 100644
--- a/packages/ai-anthropic/src/adapters/text.ts
+++ b/packages/ai-anthropic/src/adapters/text.ts
@@ -7,6 +7,7 @@ import {
 import {
   REDACTED_THINKING_ID_PREFIX,
   orderedAssistantBlocks,
+  splitMidConversationChanges,
   toRunErrorRawEvent,
 } from '@tanstack/ai/adapter-internals'
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
@@ -17,7 +18,10 @@ import {
   readCodeExecutionSkills,
 } from '../tools/code-execution-tool'
 import { validateTextProviderOptions } from '../text/text-provider-options'
-import { applyAnthropicPromptCache } from '../prompt-cache'
+import {
+  ANTHROPIC_DEFERRED_TOOL_PLACEHOLDER_NAME,
+  applyAnthropicPromptCache,
+} from '../prompt-cache'
 import { anthropicThinking } from '../text/reasoning'
 import { ANTHROPIC_MODEL_REASONING } from '../model-reasoning'
 import type { AnthropicModelReasoningByName } from '../model-reasoning'
@@ -30,6 +34,7 @@ import {
 import {
   ANTHROPIC_COMBINED_TOOLS_AND_SCHEMA_MODELS,
   ANTHROPIC_MODEL_INPUT_MODALITIES,
+  ANTHROPIC_MODEL_MID_CONVERSATION_CHANNELS,
   getAnthropicDefaultMaxTokens,
 } from '../model-meta'
 import type {
@@ -58,8 +63,10 @@ import type {
   BetaFileDocumentSource,
   BetaFileImageSource,
   BetaImageBlockParam,
+  BetaMessageParam,
   BetaRequestDocumentBlock,
   BetaTextBlockParam,
+  BetaTool,
   BetaURLImageSource,
   BetaURLPDFSource,
 } from '@anthropic-ai/sdk/resources/beta/messages'
@@ -68,9 +75,11 @@ import type { AnthropicBeta } from '@anthropic-ai/sdk/resources/beta/beta'
 import type {
   AnyTool,
   ContentPart,
+  MidConversationChannels,
   Modality,
   ModelMessage,
   AdapterYieldChunk,
+  NormalizedSystemPrompt,
   TextOptions,
   ToolCall,
 } from '@tanstack/ai'
@@ -187,7 +196,8 @@ export function messagesHaveFileSource(messages: Array<ModelMessage>): boolean {
  * - `code-execution-2025-08-25` when a `code_execution` tool is present,
  * - `skills-2025-10-02` when that tool carries skills,
  * - `context-management-2025-06-27` when `context_management` is set,
- * - `files-api-2025-04-14` when a message references an uploaded file handle.
+ * - `files-api-2025-04-14` when a message references an uploaded file handle,
+ * - `mid-conversation-tool-changes-2026-07-01` in mid-conversation tool mode.
  * Returns `undefined` when none apply (so the call site omits `betas`).
  */
 export function computeAnthropicBetas(
@@ -203,10 +213,14 @@ export function computeAnthropicBetas(
       }
     | undefined,
   hasFileSource = false,
+  midConversationToolChanges = false,
 ): Array<AnthropicBeta> | undefined {
   const betas = new Set<AnthropicBeta>()
 
   if (hasFileSource) betas.add('files-api-2025-04-14')
+  if (midConversationToolChanges) {
+    betas.add('mid-conversation-tool-changes-2026-07-01')
+  }
 
   const useInterleavedThinking =
     modelOptions?.thinking?.type === 'enabled' &&
@@ -259,14 +273,55 @@ export function computeAnthropicBetas(
   return betas.size > 0 ? Array.from(betas) : undefined
 }
 
+/**
+ * The tool placeholder of mid-conversation tool mode, copied from pi 0.87.1.
+ * Anthropic adds hidden scaffolding once any tool has `defer_loading`. This
+ * deferred tool is in every tool-mode request, so that scaffolding stays in
+ * the cached prefix. The model never sees it.
+ */
+const DEFERRED_TOOL_PLACEHOLDER: BetaTool = {
+  name: ANTHROPIC_DEFERRED_TOOL_PLACEHOLDER_NAME,
+  description: 'Reserved placeholder. Never available. Never call this.',
+  input_schema: { type: 'object', properties: {}, required: [] },
+  defer_loading: true,
+}
+
+/**
+ * A mid-conversation `system` message. SDK 0.97.1 types only `user` and
+ * `assistant` messages and has no `tool_addition` block, so this type is local.
+ */
+interface AnthropicMidConversationSystemMessage {
+  role: 'system'
+  content: Array<
+    | TextBlockParam
+    | { type: 'tool_addition'; tool: { type: 'tool_reference'; name: string } }
+  >
+}
+
 /**
  * Configuration for Anthropic text adapter
  */
-export interface AnthropicTextConfig extends AnthropicClientConfig {}
+export interface AnthropicTextConfig extends AnthropicClientConfig {
+  /**
+   * The mid-conversation channels (the
+   * `mid-conversation-tool-changes-2026-07-01` beta and mid-conversation
+   * `system` messages) of the models in
+   * `ANTHROPIC_MODEL_MID_CONVERSATION_CHANNELS`. When absent, they are on
+   * only for Anthropic's own API: a `baseURL`, a `fetch`, an injected
+   * `client`, or the SDK's `ANTHROPIC_BASE_URL` env var turns the default off. `true` turns them on anyway, for a
+   * gateway that passes the changes. `false` turns them off, so every
+   * request is built as before.
+   */
+  midConversationChannels?: boolean
+}
 
 export type AnthropicTextAdapterConfig =
   | AnthropicTextConfig
-  | { client: AnthropicMessagesClient }
+  | {
+      client: AnthropicMessagesClient
+      /** See {@link AnthropicTextConfig.midConversationChannels}. */
+      midConversationChannels?: boolean
+    }
 
 /**
  * Anthropic-specific provider options for text/chat
@@ -360,6 +415,10 @@ export class AnthropicTextAdapter<
   override readonly supportsFileSources = true
   override readonly inputModalities =
     ANTHROPIC_MODEL_INPUT_MODALITIES[this.model]
+  /** Set from `ANTHROPIC_MODEL_MID_CONVERSATION_CHANNELS` in the constructor. */
+  override readonly midConversationChannels:
+    | MidConversationChannels
+    | undefined = undefined
 
   private readonly client: SdkAnthropicMessagesClient
 
@@ -369,6 +428,19 @@ export class AnthropicTextAdapter<
       'client' in config
         ? asSdkAnthropicMessagesClient(config.client)
         : createAnthropicClient(config)
+    // On by default only on Anthropic's own API: a proxy, a gateway, Vertex,
+    // or Bedrock (a `baseURL`, a `fetch`, an injected client, or the SDK's
+    // ANTHROPIC_BASE_URL env var) may not pass the changes. The option wins.
+    const envBaseURL =
+      typeof process !== 'undefined' && Boolean(process.env.ANTHROPIC_BASE_URL)
+    const customEndpoint =
+      'client' in config ||
+      Boolean(config.baseURL || config.fetch) ||
+      envBaseURL
+    if (config.midConversationChannels ?? !customEndpoint) {
+      this.midConversationChannels =
+        ANTHROPIC_MODEL_MID_CONVERSATION_CHANNELS[model]
+    }
   }
 
   async *chatStream(
@@ -391,6 +463,10 @@ export class AnthropicTextAdapter<
         options.tools,
         requestParams,
         messagesHaveFileSource(options.messages),
+        // Mid-conversation tool mode puts the deferred placeholder in `tools`.
+        requestParams.tools?.some(
+          (tool) => tool.name === DEFERRED_TOOL_PLACEHOLDER.name,
+        ),
       )
 
       // `client.beta.messages` is Anthropic's permanent staging surface, not a
@@ -552,9 +628,13 @@ export class AnthropicTextAdapter<
   ) {
     const modelOptions = options.modelOptions
 
-    const formattedMessages = this.formatMessages(options.messages)
+    const mid = this.midConversationRequest(options)
+    const formattedMessages = this.formatMessages(
+      options.messages,
+      mid?.systemMessages,
+    )
     const tools = options.tools
-      ? convertToolsToProviderFormat(options.tools)
+      ? (mid?.tools ?? convertToolsToProviderFormat(options.tools))
       : undefined
 
     const validProviderOptions: Partial<InternalTextProviderOptions> = {}
@@ -644,9 +724,13 @@ export class AnthropicTextAdapter<
     // outside the literal and spread it conditionally rather than
     // assigning `undefined` under exactOptionalPropertyTypes.
     const systemBlocks = ((): Array<TextBlockParam> | undefined => {
-      const normalized = normalizeSystemPrompts<AnthropicSystemPromptMetadata>(
-        options.systemPrompts,
-      )
+      // With a prompt channel, `system` holds only the start prompts. They
+      // keep their own `cache_control` metadata.
+      const normalized =
+        mid?.systemPrompts ??
+        normalizeSystemPrompts<AnthropicSystemPromptMetadata>(
+          options.systemPrompts,
+        )
       if (normalized.length === 0) return undefined
       return normalized.map(
         (p): TextBlockParam => ({
@@ -722,6 +806,82 @@ export class AnthropicTextAdapter<
     return applyAnthropicPromptCache(requestParams, options.promptCache)
   }
 
+  /**
+   * Mid-conversation changes: the start prompts for `system`, the tool-mode
+   * `tools`, and a `system` message for each change by message index.
+   * Undefined when the request stays as today: the adapter has no channels,
+   * the engine passed no changes, or the changes do not fit the current lists.
+   */
+  private midConversationRequest(
+    options: TextOptions<AnthropicTextProviderOptions>,
+  ):
+    | {
+        systemPrompts?: Array<
+          NormalizedSystemPrompt<AnthropicSystemPromptMetadata>
+        >
+        tools?: InternalTextProviderOptions['tools']
+        systemMessages: Map<number, BetaMessageParam>
+      }
+    | undefined {
+    const channels = this.midConversationChannels
+    if (!channels || !options.midConversationChanges) return undefined
+    const split = splitMidConversationChanges({
+      changes: options.midConversationChanges,
+      tools: options.tools ?? [],
+      systemPrompts: normalizeSystemPrompts<AnthropicSystemPromptMetadata>(
+        options.systemPrompts,
+      ),
+    })
+    if (!split) return undefined
+    // Tool mode needs a start tool (Anthropic rejects a list where every
+    // tool is deferred), and a provider tool cannot be deferred by name.
+    const toolMode =
+      channels.tools &&
+      split.startTools.length > 0 &&
+      ![...split.startTools, ...split.addedTools].some(
+        (tool) => getAnthropicProviderToolKind(tool) !== undefined,
+      )
+    const systemMessages = new Map<number, BetaMessageParam>()
+    for (const [before, change] of split.at) {
+      const content: AnthropicMidConversationSystemMessage['content'] = [
+        ...(channels.systemPrompts
+          ? change.systemPrompts.map(
+              (p): TextBlockParam => ({ type: 'text', text: p.content }),
+            )
+          : []),
+        ...(toolMode
+          ? change.tools.map((tool) => ({
+              type: 'tool_addition' as const,
+              tool: { type: 'tool_reference' as const, name: tool.name },
+            }))
+          : []),
+      ]
+      if (content.length === 0) continue
+      const message: AnthropicMidConversationSystemMessage = {
+        role: 'system',
+        content,
+      }
+      // oxlint-disable-next-line eslint-js/no-restricted-syntax -- SDK 0.97.1 types no `system` message in `messages`; the models in the channel map accept one (pi 0.87.1).
+      systemMessages.set(before, message as unknown as BetaMessageParam)
+    }
+    return {
+      ...(channels.systemPrompts && {
+        systemPrompts: split.startSystemPrompts,
+      }),
+      ...(toolMode && {
+        tools: [
+          ...convertToolsToProviderFormat(split.startTools),
+          DEFERRED_TOOL_PLACEHOLDER,
+          ...convertToolsToProviderFormat(split.addedTools).map((tool) => ({
+            ...tool,
+            defer_loading: true,
+          })),
+        ],
+      }),
+      systemMessages,
+    }
+  }
+
   /**
    * Anthropic supports `output_config.format` + `tools` in a single streaming
    * Messages request only for Claude 4.5+ (GA 2026-01-29). For 4.4 and
@@ -835,11 +995,21 @@ export class AnthropicTextAdapter<
 
   private formatMessages(
     messages: Array<ModelMessage>,
+    /** Mid-conversation `system` messages by message index (`before`). */
+    systemMessages?: ReadonlyMap<number, BetaMessageParam>,
   ): InternalTextProviderOptions['messages'] {
     const formattedMessages: InternalTextProviderOptions['messages'] = []
+    // A system message waits for the next assistant message (or the end),
+    // so a `tool_result` still follows its `tool_use` directly.
+    const pendingSystemMessages: InternalTextProviderOptions['messages'] = []
 
-    for (const message of messages) {
+    for (const [index, message] of messages.entries()) {
       const role = message.role
+      const systemMessage = systemMessages?.get(index)
+      if (systemMessage) pendingSystemMessages.push(systemMessage)
+      if (role === 'assistant') {
+        formattedMessages.push(...pendingSystemMessages.splice(0))
+      }
 
       if (role === 'tool' && message.toolCallId) {
         const toolContent = message.content
@@ -958,6 +1128,11 @@ export class AnthropicTextAdapter<
       })
     }
 
+    // A change with `before === messages.length` goes at the end.
+    const endSystemMessage = systemMessages?.get(messages.length)
+    if (endSystemMessage) pendingSystemMessages.push(endSystemMessage)
+    formattedMessages.push(...pendingSystemMessages)
+
     // Post-process: Anthropic requires strictly alternating user/assistant roles.
     // Tool results are sent as role:'user' messages, which can create consecutive
     // user messages when followed by a new user message. Merge them.
diff --git a/packages/ai-anthropic/src/model-meta.ts b/packages/ai-anthropic/src/model-meta.ts
index fbc0a67027..1dda8d8a83 100644
--- a/packages/ai-anthropic/src/model-meta.ts
+++ b/packages/ai-anthropic/src/model-meta.ts
@@ -1,4 +1,4 @@
-import type { Modality } from '@tanstack/ai'
+import type { MidConversationChannels, Modality } from '@tanstack/ai'
 import type {
   AnthropicCacheControlOptions,
   AnthropicContainerOptions,
@@ -808,6 +808,22 @@ export const ANTHROPIC_COMBINED_TOOLS_AND_SCHEMA_MODELS = new Set<string>([
   CLAUDE_HAIKU_4_5.id,
 ])
 
+/**
+ * The mid-conversation channels of each model (from pi 0.87.1): added tools
+ * use the `mid-conversation-tool-changes-2026-07-01` beta, and added prompts
+ * go in a mid-conversation `system` message. An unknown id gives
+ * `undefined`, so the adapter has no channels.
+ */
+export const ANTHROPIC_MODEL_MID_CONVERSATION_CHANNELS: Readonly<
+  Record<string, MidConversationChannels>
+> = {
+  [CLAUDE_OPUS_4_8.id]: { tools: true, systemPrompts: true },
+  [CLAUDE_OPUS_5.id]: { tools: true, systemPrompts: true },
+  [CLAUDE_OPUS_5_5.id]: { tools: true, systemPrompts: true },
+  [CLAUDE_FABLE_5.id]: { tools: true, systemPrompts: true },
+  [CLAUDE_FABLE_5_1.id]: { tools: true, systemPrompts: true },
+}
+
 // const ANTHROPIC_IMAGE_MODELS = [] as const
 // const ANTHROPIC_EMBEDDING_MODELS = [] as const
 // const ANTHROPIC_AUDIO_MODELS = [] as const
diff --git a/packages/ai-anthropic/src/prompt-cache.ts b/packages/ai-anthropic/src/prompt-cache.ts
index 9e9efa3942..60f9fde70c 100644
--- a/packages/ai-anthropic/src/prompt-cache.ts
+++ b/packages/ai-anthropic/src/prompt-cache.ts
@@ -9,16 +9,26 @@ import type { InternalTextProviderOptions } from './text/text-provider-options'
 
 /**
  * The block types that can take the automatic cache marker when they are
- * the last block of the last user message.
- * Later work adds the `tool_addition` and `tool_removal` blocks here.
+ * the last block of the last user message, or of a mid-conversation
+ * `system` message at the end.
  */
 export const ANTHROPIC_CACHEABLE_BLOCK_TYPES: ReadonlySet<string> = new Set([
   'text',
   'image',
   'document',
   'tool_result',
+  'tool_addition',
+  'tool_removal',
 ])
 
+/**
+ * The name of the deferred placeholder tool of mid-conversation tool mode.
+ * The text adapter puts it on the placeholder, and the cache markers find
+ * the placeholder by it.
+ */
+export const ANTHROPIC_DEFERRED_TOOL_PLACEHOLDER_NAME =
+  '__tanstack_deferred_placeholder__'
+
 // Anthropic rejects a request with more than 4 cache markers.
 const MAX_CACHE_MARKERS = 4
 
@@ -62,15 +72,20 @@ function withCacheControl<T extends object>(
 
 /**
  * The messages with a marker on the last block of the last message. Returns
- * `null` when that message is not from the user or its last block cannot
- * take a marker.
+ * `null` when that message is not from the user or a mid-conversation
+ * `system` message, or when its last block cannot take a marker.
  */
 function markLastUserMessage(
   messages: Array<BetaMessageParam>,
   cacheControl: BetaCacheControlEphemeral,
 ) {
   const last = messages.at(-1)
-  if (last === undefined || last.role !== 'user') return null
+  // A mid-conversation `system` message at the end takes the marker, as in
+  // pi 0.87.1. The SDK type has no `system` role, so compare it as a string.
+  const role: string | undefined = last?.role
+  if (last === undefined || (role !== 'user' && role !== 'system')) {
+    return null
+  }
   const blocks: Array<BetaContentBlockParam> =
     typeof last.content !== 'string'
       ? last.content
@@ -104,9 +119,11 @@ function markLastUserMessage(
  * request already has a marker of the caller's (on a system block, a message
  * block, a tool, or the top-level `cache_control`). Otherwise it marks, with
  * at most 4 markers:
- * 1. the last tool,
- * 2. the last block of the last message, when it is a user message and the
- *    block type is in {@link ANTHROPIC_CACHEABLE_BLOCK_TYPES},
+ * 1. the last tool. In mid-conversation tool mode (the tools hold the
+ *    placeholder), the last start tool, right before the placeholder,
+ * 2. the last block of the last message, when it is a user message or a
+ *    mid-conversation `system` message and the block type is in
+ *    {@link ANTHROPIC_CACHEABLE_BLOCK_TYPES},
  * 3. the system blocks from the end, with the markers that are left.
  *
  * It does not change the request it gets. It returns a new request, or the
@@ -130,8 +147,18 @@ export function applyAnthropicPromptCache(
       ? { type: 'ephemeral', ttl: '1h' }
       : { type: 'ephemeral' }
 
+  // Mid-conversation tool mode: the placeholder and the deferred added tools
+  // are not in the cached start, so the marker goes on the last start tool,
+  // right before the placeholder (pi 0.87.1). Without the placeholder, the
+  // last tool, as before.
+  const placeholder =
+    request.tools?.findIndex(
+      (tool) => tool.name === ANTHROPIC_DEFERRED_TOOL_PLACEHOLDER_NAME,
+    ) ?? -1
   const tools = request.tools?.map((tool, index, all) =>
-    index === all.length - 1 ? withCacheControl(tool, cacheControl) : tool,
+    index === (placeholder > 0 ? placeholder - 1 : all.length - 1)
+      ? withCacheControl(tool, cacheControl)
+      : tool,
   )
   const messages = markLastUserMessage(request.messages, cacheControl)
 
diff --git a/packages/ai-anthropic/src/text/text-provider-options.ts b/packages/ai-anthropic/src/text/text-provider-options.ts
index a0df6127d8..430331a47a 100644
--- a/packages/ai-anthropic/src/text/text-provider-options.ts
+++ b/packages/ai-anthropic/src/text/text-provider-options.ts
@@ -2,6 +2,7 @@ import type { AnthropicThinkingFields } from './reasoning'
 import type {
   BetaContextManagementConfig,
   BetaMessageParam,
+  BetaTool,
   BetaToolChoiceAny,
   BetaToolChoiceAuto,
   BetaToolChoiceTool,
@@ -195,7 +196,8 @@ export interface InternalTextProviderOptions
    */
   system?: string | Array<TextBlockParam>
 
-  tools?: Array<AnthropicTool>
+  /** `BetaTool`: the placeholder and the deferred tools of mid-conversation tool mode. */
+  tools?: Array<AnthropicTool | BetaTool>
 
   /**
    * Schema-constrained final answer in a single Messages request (issue
diff --git a/packages/ai-anthropic/tests/mid-conversation-changes.test.ts b/packages/ai-anthropic/tests/mid-conversation-changes.test.ts
new file mode 100644
index 0000000000..a9d48b98e9
--- /dev/null
+++ b/packages/ai-anthropic/tests/mid-conversation-changes.test.ts
@@ -0,0 +1,508 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { createAnthropicChat, createAnthropicChatWithClient } from '../src'
+import { AnthropicTextAdapter } from '../src/adapters/text'
+import { ANTHROPIC_MODEL_MID_CONVERSATION_CHANNELS } from '../src/model-meta'
+import { applyAnthropicPromptCache } from '../src/prompt-cache'
+import { webSearchTool } from '../src/tools'
+import { convertToolsToProviderFormat } from '../src/tools/tool-converter'
+import type {
+  MidConversationChanges,
+  ModelMessage,
+  TextOptions,
+  Tool,
+} from '@tanstack/ai'
+import type { AnthropicTextConfig } from '../src/adapters/text'
+import type { AnthropicChatModel } from '../src/model-meta'
+
+const mocks = vi.hoisted(() => {
+  const betaMessagesCreate = vi.fn()
+  const client = {
+    beta: { messages: { create: betaMessagesCreate } },
+    messages: { create: vi.fn() },
+  }
+  return { betaMessagesCreate, client }
+})
+
+vi.mock('@anthropic-ai/sdk', () => {
+  class MockAnthropic {
+    beta = mocks.client.beta
+    messages = mocks.client.messages
+    constructor(_: { apiKey: string }) {}
+  }
+  return { default: MockAnthropic }
+})
+
+const logger = resolveDebugOption(false)
+const BETA = 'mid-conversation-tool-changes-2026-07-01'
+const SHORT = { type: 'ephemeral' }
+
+// A proxy in ANTHROPIC_BASE_URL on this machine would turn the default off.
+// Clear it, so each test starts from Anthropic's own API.
+beforeEach(() => {
+  vi.stubEnv('ANTHROPIC_BASE_URL', '')
+})
+afterEach(() => {
+  vi.unstubAllEnvs()
+})
+const PLACEHOLDER = {
+  name: '__tanstack_deferred_placeholder__',
+  description: 'Reserved placeholder. Never available. Never call this.',
+  input_schema: { type: 'object', properties: {}, required: [] },
+  defer_loading: true,
+}
+
+function textStream() {
+  return (async function* () {
+    yield {
+      type: 'content_block_start',
+      index: 0,
+      content_block: { type: 'text', text: '' },
+    }
+    yield {
+      type: 'content_block_delta',
+      index: 0,
+      delta: { type: 'text_delta', text: 'ok' },
+    }
+    yield { type: 'content_block_stop', index: 0 }
+    yield {
+      type: 'message_delta',
+      delta: { stop_reason: 'end_turn' },
+      usage: { output_tokens: 1 },
+    }
+    yield { type: 'message_stop' }
+  })()
+}
+
+/** Run one call and give back the request body that the client got. */
+async function send(
+  model: AnthropicChatModel,
+  options: Pick<
+    TextOptions,
+    | 'messages'
+    | 'tools'
+    | 'systemPrompts'
+    | 'midConversationChanges'
+    | 'promptCache'
+  >,
+  config: Omit<AnthropicTextConfig, 'apiKey'> = {},
+) {
+  mocks.betaMessagesCreate.mockClear()
+  const adapter = new AnthropicTextAdapter(
+    { apiKey: 'test-key', ...config },
+    model,
+  )
+  for await (const chunk of adapter.chatStream({
+    logger,
+    model,
+    ...options,
+  })) {
+    if (chunk.type === 'RUN_ERROR') throw new Error(chunk.message)
+  }
+  const [body] = mocks.betaMessagesCreate.mock.calls[0]!
+  return body
+}
+
+const roles = (body: { messages: Array<{ role: string }> }) =>
+  body.messages.map((message) => message.role)
+
+const both = { tools: true, systemPrompts: true }
+/** Configs that do not talk to Anthropic's own API. The Cloudflare binding
+ *  route of the E2E app uses a custom `fetch`. */
+const customEndpoints = [
+  { baseURL: 'https://gateway.example.com' },
+  { fetch: vi.fn() },
+]
+const injectedClient = { beta: { messages: { create: vi.fn() } } }
+
+const lookup: Tool = { name: 'lookup', description: 'Look a thing up' }
+const fetchPage: Tool = { name: 'fetch_page', description: 'Fetch a page' }
+
+/** A user turn, an answer that called `lookup`, and the tool result. */
+const toolTurn: Array<ModelMessage> = [
+  { role: 'user', content: 'Find the page' },
+  {
+    role: 'assistant',
+    content: null,
+    toolCalls: [
+      {
+        id: 'call-1',
+        type: 'function',
+        function: { name: 'lookup', arguments: '{}' },
+      },
+    ],
+  },
+  { role: 'tool', toolCallId: 'call-1', content: 'https://example.com' },
+]
+
+/** After the tool result, `fetch_page` and a second prompt came. */
+const endChange: MidConversationChanges = {
+  start: { tools: ['lookup'], systemPrompts: 1 },
+  changes: [{ before: 3, tools: ['fetch_page'], systemPrompts: 1 }],
+}
+
+describe('Anthropic mid-conversation channels', () => {
+  it('gives the five models from pi both channels', () => {
+    const models = [
+      'claude-opus-4-8',
+      'claude-opus-5',
+      'claude-opus-5-5',
+      'claude-fable-5',
+      'claude-fable-5-1',
+    ] as const
+    expect(
+      Object.keys(ANTHROPIC_MODEL_MID_CONVERSATION_CHANNELS).sort(),
+    ).toEqual([...models].sort())
+    for (const model of models) {
+      expect(
+        new AnthropicTextAdapter({ apiKey: 'test-key' }, model)
+          .midConversationChannels,
+      ).toEqual(both)
+    }
+  })
+
+  it('is off by default with a custom baseURL, a custom fetch, or an injected client', () => {
+    for (const endpoint of customEndpoints) {
+      expect(
+        createAnthropicChat('claude-opus-5-5', 'test-key', endpoint)
+          .midConversationChannels,
+      ).toBeUndefined()
+    }
+    // anthropicVertexText builds its adapter this way.
+    expect(
+      createAnthropicChatWithClient('claude-opus-5', injectedClient)
+        .midConversationChannels,
+    ).toBeUndefined()
+  })
+
+  it('is off by default when the SDK reads a proxy from ANTHROPIC_BASE_URL', () => {
+    vi.stubEnv('ANTHROPIC_BASE_URL', 'https://proxy.example.com')
+    try {
+      expect(
+        createAnthropicChat('claude-opus-5-5', 'test-key')
+          .midConversationChannels,
+      ).toBeUndefined()
+      expect(
+        createAnthropicChat('claude-opus-5-5', 'test-key', {
+          midConversationChannels: true,
+        }).midConversationChannels,
+      ).toEqual(both)
+    } finally {
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it('turns on with midConversationChannels: true on a custom endpoint', () => {
+    for (const endpoint of customEndpoints) {
+      expect(
+        createAnthropicChat('claude-opus-5-5', 'test-key', {
+          ...endpoint,
+          midConversationChannels: true,
+        }).midConversationChannels,
+      ).toEqual(both)
+    }
+    expect(
+      new AnthropicTextAdapter(
+        { client: injectedClient, midConversationChannels: true },
+        'claude-opus-5-5',
+      ).midConversationChannels,
+    ).toEqual(both)
+  })
+
+  it('is off with midConversationChannels: false, and outside the map even with true', () => {
+    expect(
+      createAnthropicChat('claude-opus-5-5', 'test-key', {
+        midConversationChannels: false,
+      }).midConversationChannels,
+    ).toBeUndefined()
+    expect(
+      new AnthropicTextAdapter({ apiKey: 'test-key' }, 'claude-sonnet-5-5')
+        .midConversationChannels,
+    ).toBeUndefined()
+    expect(
+      new AnthropicTextAdapter(
+        { apiKey: 'test-key', midConversationChannels: true },
+        'claude-sonnet-5-5',
+      ).midConversationChannels,
+    ).toBeUndefined()
+  })
+})
+
+describe('Anthropic mid-conversation request', () => {
+  beforeEach(() => {
+    mocks.betaMessagesCreate.mockReset()
+    mocks.betaMessagesCreate.mockImplementation(() =>
+      Promise.resolve(textStream()),
+    )
+  })
+
+  it('sends the beta and the placeholder from the first call', async () => {
+    const body = await send('claude-opus-5-5', {
+      messages: [{ role: 'user', content: 'Find the page' }],
+      tools: [lookup],
+      midConversationChanges: {
+        start: { tools: ['lookup'], systemPrompts: 0 },
+        changes: [],
+      },
+    })
+
+    expect(body.betas).toContain(BETA)
+    expect(body.tools).toEqual([
+      ...convertToolsToProviderFormat([lookup]),
+      PLACEHOLDER,
+    ])
+    expect(roles(body)).toEqual(['user'])
+  })
+
+  it('defers an added tool and announces it with a tool_addition block', async () => {
+    const body = await send('claude-opus-5-5', {
+      messages: toolTurn,
+      tools: [lookup, fetchPage],
+      systemPrompts: ['Be brief.', 'Cite sources.'],
+      midConversationChanges: endChange,
+    })
+
+    expect(body.betas).toContain(BETA)
+    expect(body.tools).toEqual([
+      ...convertToolsToProviderFormat([lookup]),
+      PLACEHOLDER,
+      { ...convertToolsToProviderFormat([fetchPage])[0], defer_loading: true },
+    ])
+    expect(body.system).toEqual([{ type: 'text', text: 'Be brief.' }])
+    expect(roles(body)).toEqual(['user', 'assistant', 'user', 'system'])
+    expect(body.messages[3]).toEqual({
+      role: 'system',
+      content: [
+        { type: 'text', text: 'Cite sources.' },
+        {
+          type: 'tool_addition',
+          tool: { type: 'tool_reference', name: 'fetch_page' },
+        },
+      ],
+    })
+  })
+
+  it('puts an added prompt in a system message before the next assistant message', async () => {
+    const body = await send('claude-opus-5-5', {
+      messages: [
+        ...toolTurn,
+        { role: 'assistant', content: 'Here it is.' },
+        { role: 'user', content: 'Thanks' },
+      ],
+      tools: [lookup],
+      systemPrompts: ['Be brief.', 'Cite sources.'],
+      // The change sits before the tool result. The system message waits for
+      // the next assistant message, so tool_result still follows tool_use.
+      midConversationChanges: {
+        start: { tools: ['lookup'], systemPrompts: 1 },
+        changes: [{ before: 2, systemPrompts: 1 }],
+      },
+    })
+
+    expect(roles(body)).toEqual([
+      'user',
+      'assistant',
+      'user',
+      'system',
+      'assistant',
+      'user',
+    ])
+    expect(body.messages[2].content[0].type).toBe('tool_result')
+    expect(body.messages[3]).toEqual({
+      role: 'system',
+      content: [{ type: 'text', text: 'Cite sources.' }],
+    })
+  })
+
+  it('keeps cache_control on the start prompts', async () => {
+    const body = await send('claude-opus-5-5', {
+      messages: toolTurn,
+      tools: [lookup],
+      systemPrompts: [
+        {
+          content: 'Stable rules.',
+          metadata: { cache_control: { type: 'ephemeral' } },
+        },
+        {
+          content: 'Late rule.',
+          metadata: { cache_control: { type: 'ephemeral' } },
+        },
+      ],
+      midConversationChanges: {
+        start: { tools: ['lookup'], systemPrompts: 1 },
+        changes: [{ before: 3, systemPrompts: 1 }],
+      },
+    })
+
+    expect(body.system).toEqual([
+      {
+        type: 'text',
+        text: 'Stable rules.',
+        cache_control: { type: 'ephemeral' },
+      },
+    ])
+    // The added prompt goes out as text only.
+    expect(body.messages.at(-1)).toEqual({
+      role: 'system',
+      content: [{ type: 'text', text: 'Late rule.' }],
+    })
+  })
+
+  it('keeps the full tools list when a provider tool takes part', async () => {
+    const webSearch = webSearchTool({
+      name: 'web_search',
+      type: 'web_search_20250305',
+    })
+    const body = await send('claude-opus-5-5', {
+      messages: toolTurn,
+      tools: [lookup, webSearch, fetchPage],
+      systemPrompts: ['Be brief.', 'Cite sources.'],
+      midConversationChanges: {
+        start: { tools: ['lookup', 'web_search'], systemPrompts: 1 },
+        changes: [{ before: 3, tools: ['fetch_page'], systemPrompts: 1 }],
+      },
+    })
+
+    expect(body.tools).toEqual(
+      convertToolsToProviderFormat([lookup, webSearch, fetchPage]),
+    )
+    expect(body.betas).toBeUndefined()
+    // The prompt channel still works, with no tool_addition block.
+    expect(body.messages.at(-1)).toEqual({
+      role: 'system',
+      content: [{ type: 'text', text: 'Cite sources.' }],
+    })
+  })
+
+  it("sends today's request when off, on a custom endpoint, and outside the map", async () => {
+    const options = {
+      messages: toolTurn,
+      tools: [lookup, fetchPage],
+      systemPrompts: ['Be brief.', 'Cite sources.'],
+    }
+    const cases = [
+      ['claude-opus-5-5', { midConversationChannels: false }],
+      ['claude-opus-5-5', { baseURL: 'https://gateway.example.com' }],
+      ['claude-sonnet-5-5', {}],
+    ] as const
+    for (const [model, config] of cases) {
+      const today = await send(model, options, config)
+      const body = await send(
+        model,
+        { ...options, midConversationChanges: endChange },
+        config,
+      )
+
+      expect(JSON.stringify(body)).toBe(JSON.stringify(today))
+      expect(today.betas).toBeUndefined()
+      expect(roles(today)).toEqual(['user', 'assistant', 'user'])
+    }
+  })
+
+  it('puts the automatic tool cache marker on the last start tool', async () => {
+    const body = await send('claude-opus-5-5', {
+      messages: [
+        ...toolTurn,
+        { role: 'assistant', content: 'Here it is.' },
+        { role: 'user', content: 'Thanks' },
+      ],
+      tools: [lookup, fetchPage],
+      systemPrompts: ['Be brief.', 'Cite sources.'],
+      // A change in the history: the system message sits before an
+      // assistant message, so the last message is still the user's.
+      midConversationChanges: {
+        start: { tools: ['lookup'], systemPrompts: 1 },
+        changes: [{ before: 3, tools: ['fetch_page'], systemPrompts: 1 }],
+      },
+      promptCache: { retention: 'short' },
+    })
+
+    expect(body.tools).toEqual([
+      { ...convertToolsToProviderFormat([lookup])[0], cache_control: SHORT },
+      PLACEHOLDER,
+      { ...convertToolsToProviderFormat([fetchPage])[0], defer_loading: true },
+    ])
+    expect(body.messages[3]).toEqual({
+      role: 'system',
+      content: [
+        { type: 'text', text: 'Cite sources.' },
+        {
+          type: 'tool_addition',
+          tool: { type: 'tool_reference', name: 'fetch_page' },
+        },
+      ],
+    })
+    expect(body.messages.at(-1)).toEqual({
+      role: 'user',
+      content: [{ type: 'text', text: 'Thanks', cache_control: SHORT }],
+    })
+  })
+
+  it('puts the message cache marker on the last block of a system message at the end', async () => {
+    const body = await send('claude-opus-5-5', {
+      messages: toolTurn,
+      tools: [lookup, fetchPage],
+      systemPrompts: ['Be brief.', 'Cite sources.'],
+      // before === messages.length: the change goes at the end.
+      midConversationChanges: endChange,
+      promptCache: { retention: 'short' },
+    })
+
+    expect(body.messages.at(-1)).toEqual({
+      role: 'system',
+      content: [
+        { type: 'text', text: 'Cite sources.' },
+        {
+          type: 'tool_addition',
+          tool: { type: 'tool_reference', name: 'fetch_page' },
+          cache_control: SHORT,
+        },
+      ],
+    })
+    // The tool_result before it gets no marker.
+    expect(body.messages[2].content[0]).not.toHaveProperty('cache_control')
+    expect(body.tools[0].cache_control).toEqual(SHORT)
+    expect(body.tools.slice(1)).toEqual([
+      PLACEHOLDER,
+      { ...convertToolsToProviderFormat([fetchPage])[0], defer_loading: true },
+    ])
+    expect(body.system).toEqual([
+      { type: 'text', text: 'Be brief.', cache_control: SHORT },
+    ])
+  })
+
+  it("adds no cache marker in tool mode with promptCache: 'none'", async () => {
+    const body = await send('claude-opus-5-5', {
+      messages: toolTurn,
+      tools: [lookup, fetchPage],
+      systemPrompts: ['Be brief.', 'Cite sources.'],
+      midConversationChanges: endChange,
+      promptCache: { retention: 'none' },
+    })
+
+    expect(body.betas).toContain(BETA)
+    expect(JSON.stringify(body)).not.toMatch(/"cache_control":\{/)
+  })
+
+  it('keeps the tool marker on the last tool outside tool mode, also when that tool is deferred', () => {
+    // A caller's own deferred tool, with no placeholder in the request.
+    const lastTool = {
+      ...convertToolsToProviderFormat([fetchPage])[0]!,
+      defer_loading: true,
+    }
+    const body = applyAnthropicPromptCache(
+      {
+        model: 'claude-opus-5-5',
+        max_tokens: 1024,
+        messages: [{ role: 'user', content: 'hi' }],
+        tools: [...convertToolsToProviderFormat([lookup]), lastTool],
+      },
+      { retention: 'short' },
+    )
+
+    expect(body.tools).toEqual([
+      ...convertToolsToProviderFormat([lookup]),
+      { ...lastTool, cache_control: SHORT },
+    ])
+  })
+})

From 2558e7e8e8946ec05f022a2f57fd8068886050a4 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 16:02:19 +0200
Subject: [PATCH 185/286] chore: add changesets for block order and
 mid-conversation changes

---
 .changeset/block-order.md              | 12 ++++++++++++
 .changeset/mid-conversation-changes.md | 16 ++++++++++++++++
 2 files changed, 28 insertions(+)
 create mode 100644 .changeset/block-order.md
 create mode 100644 .changeset/mid-conversation-changes.md

diff --git a/.changeset/block-order.md b/.changeset/block-order.md
new file mode 100644
index 0000000000..9d89f0835d
--- /dev/null
+++ b/.changeset/block-order.md
@@ -0,0 +1,12 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-anthropic': minor
+---
+
+Keep the order of Claude's thinking, text, and tool calls in one answer.
+
+- Claude can answer with thinking, a tool call, more thinking, and another tool call. The stream, the stored messages, the client wire, and the next request to Claude keep that order.
+- `ModelMessage` has a new optional `blockOrder` field. The library writes it only when the order is not the default (thinking, then text, then tool calls), so a message in the default order does not change. `orderedAssistantBlocks(message)` gives adapter authors the blocks in order.
+- Each Claude thinking block ends with its own `REASONING_MESSAGE_END` and `REASONING_END`.
+- Text after a second thinking block starts a new text part.
+- On the client wire, an answer in another order goes out as ordered rows. A row that exists only for the order has `metadata.tanstack.continues`, and the server joins it back into one message. A `UIMessage` that holds two model calls with a tool result between them reaches the server as assistant, tool, assistant, for every adapter.
diff --git a/.changeset/mid-conversation-changes.md b/.changeset/mid-conversation-changes.md
new file mode 100644
index 0000000000..807a79d602
--- /dev/null
+++ b/.changeset/mid-conversation-changes.md
@@ -0,0 +1,16 @@
+---
+'@tanstack/ai': minor
+'@tanstack/openai-base': minor
+'@tanstack/ai-openai': minor
+'@tanstack/ai-anthropic': minor
+---
+
+Keep the prompt cache when tools or system prompts are added during a conversation.
+
+- Before each model call, `chat()` compares the tools and the system prompts with the earlier calls. On a model with a mid-conversation channel, an added tool, or a system prompt added at the end, goes out in the conversation. The start of the request stays the same.
+- `openaiText` on `gpt-5.4-mini`, `gpt-5.5`, `gpt-5.6-luna`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-6-astra`, `gpt-6-luna`, and `gpt-6-sol`: an added tool is an `additional_tools` input item, and an added prompt is a `developer` message. The Responses adapter of `@tanstack/openai-base` sends these when a subclass sets `midConversationChannels`.
+- `anthropicText` on `claude-opus-4-8`, `claude-opus-5`, `claude-opus-5-5`, `claude-fable-5`, and `claude-fable-5-1`: every request with tools has the `mid-conversation-tool-changes-2026-07-01` beta and one placeholder tool. An added tool has `defer_loading: true` and a `tool_addition` block in a `system` message.
+- Every other model and adapter sends the same request as before.
+- The channels are on by default only with the provider's own API. A custom `baseURL`, a custom `fetch`, an injected client, or the `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL` environment variable turns the default off. Set `midConversationChannels: true` to turn the channels on anyway. Set `false` to turn them off anywhere.
+- With prompt caching on (the default), the automatic Claude tool cache marker goes on the last start tool, not on the placeholder or an added tool.
+- New optional fields: `ModelMessage.midConversationChange`, `TextOptions.midConversationChanges`, and `TextAdapter.midConversationChannels`, with the types `MidConversationChange`, `MidConversationChanges`, and `MidConversationChannels`. `splitMidConversationChanges` helps adapter authors read the changes.

From 4851601e5f708f390a2eb37d8b588452d5eb618e Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 16:04:23 +0200
Subject: [PATCH 186/286] docs(ai): explain mid-conversation changes and the
 kept block order

A new guide for tools and system prompts added during a conversation, sections under Prompt Caching on the OpenAI and Anthropic pages with the default rule, a When the tools change section in prompt-caching, a gateway note on the Cloudflare page, an adapter-author section in extend-adapter, the block order in thinking-content, and a link from turn-control.
---
 docs/adapters/anthropic.md                |  36 +++++
 docs/adapters/cloudflare.md               |  19 +++
 docs/adapters/openai.md                   |  30 +++++
 docs/advanced/extend-adapter.md           | 101 ++++++++++++++
 docs/advanced/mid-conversation-changes.md | 153 ++++++++++++++++++++++
 docs/advanced/prompt-caching.md           |   6 +-
 docs/chat/thinking-content.md             |   8 +-
 docs/config.json                          |  15 ++-
 docs/harness/turn-control.md              |   2 +
 9 files changed, 364 insertions(+), 6 deletions(-)
 create mode 100644 docs/advanced/mid-conversation-changes.md

diff --git a/docs/adapters/anthropic.md b/docs/adapters/anthropic.md
index ac3ad86fcf..83b05042ad 100644
--- a/docs/adapters/anthropic.md
+++ b/docs/adapters/anthropic.md
@@ -288,6 +288,42 @@ const stream = chat({
 
 `modelOptions.cache_control` asks Anthropic to place one marker for the whole request. It also turns the automatic markers off.
 
+#### Tools and prompts added during a conversation
+
+On some Claude models, a tool or a system prompt that you add between model calls goes into the conversation, not into `tools` or `system`. The marked start of the request stays the same, so Claude reads it from the cache.
+
+The models: `claude-opus-4-8`, `claude-opus-5`, `claude-opus-5-5`, `claude-fable-5`, and `claude-fable-5-1`.
+
+What the adapter sends on these models:
+
+- `system` keeps the system prompts of the first call, with their `cache_control`.
+- In a request with tools, the `anthropic-beta` header has `mid-conversation-tool-changes-2026-07-01`, and `tools` has one placeholder tool, `__tanstack_deferred_placeholder__`. The model must never call it. It keeps Anthropic's hidden setup for added tools inside the cached start.
+- An added tool goes to the end of `tools` with `defer_loading: true`. A `system` message lists it in a `tool_addition` block.
+- A system prompt that you add goes into a `system` message as a text block. The message comes directly before the next assistant message, or at the end of the messages.
+- With a provider tool such as `webSearchTool()` in the first call or in a change, `tools` is the full list and has no placeholder.
+
+The automatic tool marker goes on the last tool of the first call, not on the placeholder or an added tool. So the marked start does not move when a tool is added. A `cache_control` of your own still wins.
+
+The channels are on by default with Anthropic's own API. With a custom `baseURL`, a custom `fetch`, or a proxy in the `ANTHROPIC_BASE_URL` environment variable, they are off, and every request is the same as on a model outside the list. An adapter on your own client (`createAnthropicChatWithClient`, `anthropicVertexText`) has no channels. Set `midConversationChannels` to choose:
+
+- `false`: send the full lists on every call.
+- `true`: use the channels with a custom `baseURL`, `fetch`, or `ANTHROPIC_BASE_URL`. Set it only when that endpoint sends the request and the `anthropic-beta` header to Anthropic as they are.
+
+```typescript
+import { anthropicText } from "@tanstack/ai-anthropic";
+
+export const fullLists = anthropicText("claude-opus-5-5", {
+  midConversationChannels: false,
+});
+
+export const throughProxy = anthropicText("claude-opus-5-5", {
+  baseURL: "https://llm-proxy.example.com",
+  midConversationChannels: true,
+});
+```
+
+See [Mid-Conversation Changes](../advanced/mid-conversation-changes) for how the library finds the changes.
+
 ## Summarization
 
 Anthropic supports text summarization:
diff --git a/docs/adapters/cloudflare.md b/docs/adapters/cloudflare.md
index cd892eeec3..80ea199d46 100644
--- a/docs/adapters/cloudflare.md
+++ b/docs/adapters/cloudflare.md
@@ -189,6 +189,25 @@ export default {
 - The adapter keeps all of its options: `chat({ reasoning })`, tools, `cache_control` for prompt caching, and Anthropic betas, which go out as the `anthropic-beta` header.
 - For `@cf/...` models and other gateway vendors, keep `createCloudflareText` with `binding: env.AI`.
 
+An adapter with a gateway `baseURL` (`cloudflareGateway()`) or with `cloudflareBindingFetch` sends the full tools and system prompts on every call, also on a model with a [mid-conversation channel](../advanced/mid-conversation-changes). AI Gateway then gets the same request as on any other model. To send tools and prompts added during a conversation through the channel, set `midConversationChannels: true`:
+
+```typescript
+import { createAnthropicChat } from "@tanstack/ai-anthropic";
+import { cloudflareBindingFetch } from "@tanstack/ai-cloudflare";
+import type { Ai } from "@cloudflare/workers-types";
+
+export function gatewayClaude(env: { AI: Ai }) {
+  return createAnthropicChat("claude-opus-5-5", "cloudflare-binding", {
+    fetch: cloudflareBindingFetch({
+      binding: env.AI,
+      vendor: "anthropic",
+      gateway: { id: "default" },
+    }),
+    midConversationChannels: true,
+  });
+}
+```
+
 ## Bring your own key
 
 Two different things go by this name. Both work.
diff --git a/docs/adapters/openai.md b/docs/adapters/openai.md
index 3bcd2f2f55..7649d76c12 100644
--- a/docs/adapters/openai.md
+++ b/docs/adapters/openai.md
@@ -394,6 +394,36 @@ const stream = chat({
 
 `modelOptions.prompt_cache_retention` also wins over the automatic `prompt_cache_retention`.
 
+#### Tools and prompts added during a conversation
+
+On some models, a tool or a system prompt that you add between model calls goes into the conversation, not into `tools` or `instructions`. The start of the request stays the same, so OpenAI can read it from its prompt cache. The `prompt_cache_key` above does not change.
+
+The models: `gpt-5.4-mini`, `gpt-5.5`, `gpt-5.6-luna`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-6-astra`, `gpt-6-luna`, and `gpt-6-sol`. Other models, such as `gpt-6.1-sol`, always send the full lists.
+
+What the adapter sends on these models:
+
+- `tools` and `instructions` keep the tools and the system prompts of the first call.
+- An added tool goes into `input` as `{ type: "additional_tools", role: "developer", tools: [...] }`.
+- A system prompt that you add at the end of the list goes into `input` as a `developer` message, at its place in the conversation.
+- With a provider tool such as `webSearchTool()` in the first call or in a change, `tools` is the full list for that request.
+
+The channels are on by default with OpenAI's own API. With a custom `baseURL` or `fetch`, or a proxy in the `OPENAI_BASE_URL` environment variable, they are off, and every call sends the full lists. Set `midConversationChannels` to choose:
+
+- `false`: send the full lists on every call.
+- `true`: use the channels with a custom `baseURL`, `fetch`, or `OPENAI_BASE_URL`. Set it only when that endpoint sends the request to OpenAI as it is.
+
+```typescript
+import { openaiText } from "@tanstack/ai-openai";
+
+const fullLists = openaiText("gpt-6-astra", { midConversationChannels: false });
+const throughProxy = openaiText("gpt-6-astra", {
+  baseURL: "https://llm-proxy.example.com/v1",
+  midConversationChannels: true,
+});
+```
+
+See [Mid-Conversation Changes](../advanced/mid-conversation-changes) for how the library finds the changes.
+
 ## Summarization
 
 Summarize long text content:
diff --git a/docs/advanced/extend-adapter.md b/docs/advanced/extend-adapter.md
index e974ccb9de..2dbb6ba9da 100644
--- a/docs/advanced/extend-adapter.md
+++ b/docs/advanced/extend-adapter.md
@@ -260,3 +260,104 @@ export const myText = () =>
 An adapter with another wire format calls `resolveReasoning` from `@tanstack/ai/adapter-internals` in its request code and sends the result its own way.
 
 Models added with `extendAdapter` take no `reasoning` option, because the adapter has no reasoning data for them.
+
+## Keep block order and mid-conversation changes
+
+Two optional fields reach your adapter. If your adapter ignores them, it sends the same request as before.
+
+### Send assistant blocks in their order
+
+A model can answer with thinking, a tool call, more thinking, then text. A `ModelMessage` keeps `thinking`, `content`, and `toolCalls` in separate fields. The optional `blockOrder` map says how they mix. `orderedAssistantBlocks` gives you the blocks in that order:
+
+```typescript
+import { orderedAssistantBlocks } from "@tanstack/ai";
+import type { ModelMessage } from "@tanstack/ai";
+
+type WireBlock =
+  | { type: "reasoning"; text: string; signature?: string }
+  | { type: "text"; text: string }
+  | { type: "call"; id: string; name: string; args: string };
+
+export function orderedWireBlocks(message: ModelMessage): Array<WireBlock> | undefined {
+  const blocks = orderedAssistantBlocks(message);
+  if (!blocks) return undefined;
+  return blocks.map((block): WireBlock => {
+    if (block.type === "thinking") {
+      return { type: "reasoning", text: block.thinking.content, signature: block.thinking.signature };
+    }
+    if (block.type === "text") return { type: "text", text: block.text };
+    return {
+      type: "call",
+      id: block.toolCall.id,
+      name: block.toolCall.function.name,
+      args: block.toolCall.function.arguments,
+    };
+  });
+}
+```
+
+- The function returns `undefined` when the message has no map, or when the map does not match the message. Then send your default order.
+- The library writes `blockOrder` only when the order is not the default. The default order is all thinking, then the text, then the tool calls.
+
+### Send mid-conversation changes
+
+Tools or system prompts can grow between model calls. If your provider has a mid-conversation channel, it can take the change inside the conversation. Then the cached start of the request stays the same. To support it:
+
+1. Set `midConversationChannels` on the adapter to the channels that your provider has: `{ tools, systemPrompts }`. Before each call, the `chat()` engine compares the lists. It passes the result as `options.midConversationChanges`.
+2. Resolve the change with `splitMidConversationChanges`. It gives the start lists and the changes by message index. It returns `undefined` when a name or a count does not match the current lists.
+3. Send the start lists at the top of the request. Send each change directly before the message at its index. A change at `options.messages.length` goes at the end.
+
+An adapter that extends the Responses adapter of `@tanstack/openai-base` only sets the field. The base then sends `additional_tools` and `developer` messages:
+
+```typescript
+import { OpenAIBaseResponsesTextAdapter } from "@tanstack/openai-base";
+
+export class MyResponsesAdapter extends OpenAIBaseResponsesTextAdapter<"my-model"> {
+  override readonly midConversationChannels = { tools: true, systemPrompts: true };
+}
+```
+
+An adapter with another wire format does the steps itself:
+
+```typescript
+import { splitMidConversationChanges } from "@tanstack/ai";
+import type { ModelMessage, TextOptions } from "@tanstack/ai";
+
+type WireTool = { name: string; description: string };
+type WireItem =
+  | { kind: "message"; message: ModelMessage }
+  | { kind: "change"; tools: Array<WireTool>; prompts: Array<string> };
+
+export function buildRequest(
+  options: TextOptions,
+  tools: Array<WireTool>,
+  prompts: Array<string>,
+) {
+  const changes = options.midConversationChanges;
+  const split = changes
+    ? splitMidConversationChanges({ changes, tools, systemPrompts: prompts })
+    : undefined;
+  if (!split) {
+    // No changes, or names that do not match: send the full lists.
+    const items = options.messages.map((message): WireItem => ({ kind: "message", message }));
+    return { tools, system: prompts, items };
+  }
+  const items: Array<WireItem> = [];
+  const pushChange = (index: number) => {
+    const change = split.at.get(index);
+    if (change) items.push({ kind: "change", tools: change.tools, prompts: change.systemPrompts });
+  };
+  options.messages.forEach((message, index) => {
+    pushChange(index);
+    items.push({ kind: "message", message });
+  });
+  pushChange(options.messages.length);
+  return { tools: split.startTools, system: split.startSystemPrompts, items };
+}
+```
+
+- `split.addedTools` lists every added tool, in change order. Use it if your provider also wants the added tools in its tool list. Claude takes them there with `defer_loading`.
+- A tool can keep its name and get a new definition. Take every definition from `options.tools`.
+- If your provider cannot add some kind of tool later (for example a hosted search tool), send the full tool list for that request. Keep the prompt changes in the conversation.
+
+See [Mid-Conversation Changes](./mid-conversation-changes) for how the library finds the changes.
diff --git a/docs/advanced/mid-conversation-changes.md b/docs/advanced/mid-conversation-changes.md
new file mode 100644
index 0000000000..727d4ee43b
--- /dev/null
+++ b/docs/advanced/mid-conversation-changes.md
@@ -0,0 +1,153 @@
+---
+title: Mid-Conversation Changes
+id: mid-conversation-changes
+order: 17
+description: "Add tools or system prompts during a conversation and keep the provider's prompt cache. TanStack AI sends the change through the model's own channel on GPT and Claude models that have one."
+keywords:
+  - tanstack ai
+  - prompt caching
+  - mid-conversation changes
+  - dynamic tools
+  - additional_tools
+  - tool_addition
+---
+
+Your agent gets a new tool in the middle of a conversation. A middleware adds it after the first tool call, a [lazy tool](../tools/lazy-tool-discovery) is found, or the user connects an MCP server. `chat()` asks the provider to cache the start of each request ([Prompt Caching](./prompt-caching)), and the tool list is at the start. A new tool changes the start, so the provider cannot use its cache. The next call costs more and starts slower.
+
+On models with a mid-conversation channel, TanStack AI keeps the start of the request the same and sends the change later in the conversation. You change no code.
+
+## Add a tool during a run
+
+This route starts with one tool. A middleware adds a second tool after the first tool call:
+
+```ts group=mid-conversation-changes
+import { chat, toServerSentEventsResponse, toolDefinition } from "@tanstack/ai";
+import type { ChatMiddleware } from "@tanstack/ai";
+import { openaiText } from "@tanstack/ai-openai";
+import { z } from "zod";
+
+const getWeather = toolDefinition({
+  name: "get_weather",
+  description: "Get the current weather for a city",
+  inputSchema: z.object({ city: z.string() }),
+}).server(async ({ city }) => ({ city, temperature: 21 }));
+
+const getForecast = toolDefinition({
+  name: "get_forecast",
+  description: "Get the forecast for a city",
+  inputSchema: z.object({ city: z.string() }),
+}).server(async ({ city }) => ({ city, tomorrow: "sunny" }));
+
+// Adds get_forecast before the second model call.
+const addForecast: ChatMiddleware = {
+  name: "add-forecast",
+  onConfig: (ctx, config) => {
+    if (ctx.phase !== "beforeModel" || ctx.iteration === 0) return;
+    if (config.tools.some((tool) => tool.name === "get_forecast")) return;
+    return { tools: [...config.tools, getForecast] };
+  },
+};
+
+export async function POST(request: Request) {
+  const { messages } = await request.json();
+  const stream = chat({
+    adapter: openaiText("gpt-6-astra"),
+    messages,
+    tools: [getWeather],
+    middleware: [addForecast],
+  });
+  return toServerSentEventsResponse(stream);
+}
+```
+
+What each model call sends:
+
+| Model | First call | Second call |
+|---|---|---|
+| `gpt-6-astra` | `tools`: `get_weather` | The same `tools`. An `additional_tools` item with `get_forecast` comes after the tool result. |
+| `claude-opus-5-5` | `tools`: `get_weather` and a placeholder tool | The same `tools`, then `get_forecast` with `defer_loading: true`. A `system` message with a `tool_addition` block comes after the tool result. |
+| A model with no channel, for example `gpt-6.1-sol` | `tools`: `get_weather` | `tools`: `get_weather` and `get_forecast` |
+
+## What happens on its own
+
+Before each model call, the library compares the tools and the system prompts with the earlier calls:
+
+1. The first call is a start point. Its tools and system prompts stay at the start of every later request.
+2. A tool that you add is a change. A system prompt that you add at the end of the list is a change too. A change goes out at its place in the conversation, in the model's own format.
+3. Any other difference makes a new start point. That request sends the full lists.
+
+The library saves a small record on the first assistant message of each call, in the `midConversationChange` field. The record holds tool names and short prompt hashes, not tool definitions. Keep the field when you store messages yourself.
+
+## The models
+
+| Provider | Models | Channels |
+|---|---|---|
+| OpenAI (`openaiText`) | `gpt-5.4-mini`, `gpt-5.5`, `gpt-5.6-luna`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-6-astra`, `gpt-6-luna`, `gpt-6-sol` | Tools and system prompts |
+| Anthropic (`anthropicText`) | `claude-opus-4-8`, `claude-opus-5`, `claude-opus-5-5`, `claude-fable-5`, `claude-fable-5-1` | Tools and system prompts |
+
+Every other model and adapter sends the full lists on each call. The channels are on by default only when the adapter talks to the provider's own API. See [Turn it on or off](#turn-it-on-or-off).
+
+To check an adapter in code, read `midConversationChannels` on it:
+
+```ts group=mid-conversation-changes
+const adapter = openaiText("gpt-6-astra");
+console.log(adapter.midConversationChannels); // { tools: true, systemPrompts: true }
+```
+
+It is `undefined` on a model with no channel, and on an adapter with the channels off.
+
+The provider pages show the request shapes: [OpenAI](../adapters/openai#tools-and-prompts-added-during-a-conversation) and [Anthropic](../adapters/anthropic#tools-and-prompts-added-during-a-conversation).
+
+## See it in the usage numbers
+
+Log `usage.promptTokensDetails.cachedTokens` for each model call, as in [Track cached tokens and cost](./prompt-caching#track-cached-tokens-and-cost). After a tool is added, the next call still reads the start of the request from the cache. On a model with no channel, the cached tokens drop at that call.
+
+On Claude, the automatic tool cache marker stays on the last tool of the start point. The placeholder and the added tools get no marker, so the marked start does not move.
+
+## Turn it on or off
+
+The channels are on by default when the adapter talks to the provider's own API. A gateway or a proxy can drop or change the extra request fields, so the channels are off by default when the adapter talks to another endpoint:
+
+- a custom `baseURL` or a custom `fetch`
+- a proxy in the `OPENAI_BASE_URL` or `ANTHROPIC_BASE_URL` environment variable
+
+An Anthropic adapter on your own client (`createAnthropicChatWithClient`, `anthropicVertexText`) has no channels.
+
+Set `midConversationChannels` in the adapter config to choose:
+
+- `false`: every call sends the full lists.
+- `true`: use the channels with a custom `baseURL` or `fetch`, or with a base URL from the environment. Set it only when that endpoint sends the request to the provider as it is.
+
+```ts group=mid-conversation-changes
+import { anthropicText } from "@tanstack/ai-anthropic";
+
+const fullGpt = openaiText("gpt-6-astra", { midConversationChannels: false });
+const proxiedClaude = anthropicText("claude-opus-5-5", {
+  baseURL: "https://llm-proxy.example.com",
+  midConversationChannels: true,
+});
+```
+
+On a model with no channel, `true` changes nothing.
+
+## Limits
+
+- These break the cache once: a removed tool, an edited system prompt, a new order of the system prompts, and a tool that keeps its name but gets a new definition. The lazy discovery tool leaves the list when every lazy tool is found, so that call breaks it once too.
+- A provider tool, for example `webSearchTool()`, in the start point or in a change: that request sends the full `tools`. System prompt changes still use the channel.
+- With a harness or a message store ([`withPersistence`](../persistence/chat-persistence)), the records last across turns and restarts. With plain `useChat` and no message store, they last for one `chat()` call, so each turn starts a new start point.
+- The structured-output call at the end of a run with `outputSchema` sends the full request.
+- Claude on Vertex or Bedrock, the Chat Completions adapters, and the other adapters on the OpenAI API have no channels.
+
+## In a harness
+
+A harness session keeps its messages in the session log. So the records hold across turns, a restart, and a `/model` switch. You set nothing.
+
+- Tools that a plugin finds before a turn ([Tools that appear later](../harness/mcp#tools-that-appear-later)) go out as a change on a model with a channel.
+- After a `/model` switch to a model with no channel, each call sends the full lists. A switch back continues from the stored records.
+- A `project` function or a compaction that removes the assistant message with the start point makes a new start point. The cache breaks once.
+
+## What you have now
+
+- Tools and system prompts that you add during a conversation keep the prompt cache on GPT and Claude models with a channel.
+- The full request on every other model.
+- One option, `midConversationChannels`: `false` sends the full request on every call, and `true` uses the channels behind a gateway or a proxy.
diff --git a/docs/advanced/prompt-caching.md b/docs/advanced/prompt-caching.md
index 34873c5c75..2bfb7e585f 100644
--- a/docs/advanced/prompt-caching.md
+++ b/docs/advanced/prompt-caching.md
@@ -137,7 +137,7 @@ Automatic caching adds these fields to the request.
 
 | Adapter | `'short'` | `'long'` |
 |---|---|---|
-| `anthropicText`, Claude on Vertex | `cache_control: { type: 'ephemeral' }` on the system blocks, the last tool, and the last block of the last user message. At most 4 markers. | The same markers with `ttl: '1h'` |
+| `anthropicText`, Claude on Vertex | `cache_control: { type: 'ephemeral' }` on the system blocks, the last tool, and the last block of the last user message. At most 4 markers. With [mid-conversation tool changes](./mid-conversation-changes) on, the tool marker goes on the last start tool instead, and a mid-conversation `system` message at the end takes the message marker. | The same markers with `ttl: '1h'` |
 | `bedrockText` (Converse), Claude models only | A `cachePoint` after the system prompt and at the end of the last user message | Both with `ttl: '1h'` |
 | `openRouterText` with an `anthropic/*` model | `sessionId`, plus markers on the system prompt, the last tool, and the last message | The markers with `ttl: '1h'` |
 | `openaiCompatible` with `compat.cacheControlFormat: 'anthropic'` (Claude through a gateway) | Markers on the system prompt, the last tool, and the last message | The markers with `ttl: '1h'` |
@@ -165,6 +165,10 @@ Your own cache settings win over the automatic ones:
 - **OpenAI**: `modelOptions.prompt_cache_key` and `modelOptions.prompt_cache_retention` replace the automatic values. See [OpenAI](../adapters/openai#prompt-caching).
 - **OpenRouter**: `modelOptions.sessionId` replaces the automatic `sessionId`.
 
+## When the tools change
+
+The tools are near the start of each request. A tool that a middleware adds during a run changes that start, so the next call cannot read the cache from there on. On GPT and Claude models with a mid-conversation channel, `chat()` keeps the start the same and sends the new tool later in the conversation. A system prompt that you add at the end of the list goes the same way. See [Mid-Conversation Changes](./mid-conversation-changes).
+
 ## Track cached tokens and cost
 
 `usage.promptTokens` is the full input on every adapter, cached tokens included. Two fields split it:
diff --git a/docs/chat/thinking-content.md b/docs/chat/thinking-content.md
index 54baf701b6..4f07c021da 100644
--- a/docs/chat/thinking-content.md
+++ b/docs/chat/thinking-content.md
@@ -16,7 +16,7 @@ keywords:
 
 Some models expose their internal reasoning as "thinking" content -- Claude with extended thinking, OpenAI o-series models with reasoning, and others. TanStack AI captures this as `ThinkingPart` in messages, streamed to your UI in real-time alongside text and tool calls.
 
-Unsigned thinking stays in the UI. Signed thinking is a `ThinkingPart` with a `signature`. Anthropic extended thinking uses this. The next request sends signed thinking back in the same order as the original response, including around provider-executed tools. The next-turn body puts that signature on spec `encryptedValue` on the `role: "reasoning"` fan-out. Stream events use `REASONING_ENCRYPTED_VALUE`.
+Unsigned thinking stays in the UI. Signed thinking is a `ThinkingPart` with a `signature`. Anthropic extended thinking uses this. The next request sends signed thinking back in the same order as the original response, including around tool calls and text. The next-turn body puts that signature on spec `encryptedValue` on the `role: "reasoning"` fan-out. Stream events use `REASONING_ENCRYPTED_VALUE`.
 
 ## How It Works
 
@@ -99,6 +99,12 @@ The typical streaming order is:
 
 `STEP_STARTED` and `STEP_FINISHED` only carry `stepName`. They do not carry thinking text.
 
+Claude can think more than once in one answer: thinking, a tool call, more thinking, then text. Each thinking block streams as its own reasoning message, with its own `REASONING_MESSAGE_END` and `REASONING_END`. Then:
+
+- `message.parts` has the parts in the order Claude sent them.
+- The stored messages keep that order, and the next request sends the blocks back to Claude in it.
+- A message that you build yourself goes back in the default order: thinking, then text, then tool calls.
+
 If you use `useChat` from `@tanstack/ai-react` (or the Solid/Vue/Svelte equivalents), your `messages` array updates with both thinking and text parts as they arrive.
 
 ## Next Steps
diff --git a/docs/config.json b/docs/config.json
index 21395527ab..3af4e9ad47 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -178,7 +178,7 @@
           "label": "Thinking & Reasoning",
           "to": "chat/thinking-content",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-09-30"
+          "updatedAt": "2026-10-02"
         },
         {
           "label": "Reasoning",
@@ -336,6 +336,12 @@
         {
           "label": "Prompt Caching",
           "to": "advanced/prompt-caching",
+          "addedAt": "2026-10-02",
+          "updatedAt": "2026-10-02"
+        },
+        {
+          "label": "Mid-Conversation Changes",
+          "to": "advanced/mid-conversation-changes",
           "addedAt": "2026-10-02"
         }
       ],
@@ -931,7 +937,8 @@
         {
           "label": "Control how a turn ends",
           "to": "harness/turn-control",
-          "addedAt": "2026-10-01"
+          "addedAt": "2026-10-01",
+          "updatedAt": "2026-10-02"
         },
         {
           "label": "Share one log between sessions",
@@ -1268,7 +1275,7 @@
           "label": "Extend Adapter",
           "to": "advanced/extend-adapter",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-09-30"
+          "updatedAt": "2026-10-02"
         },
         {
           "label": "Model Catalog",
@@ -1425,7 +1432,7 @@
           "label": "Cloudflare",
           "to": "adapters/cloudflare",
           "addedAt": "2026-09-03",
-          "updatedAt": "2026-09-30"
+          "updatedAt": "2026-10-02"
         },
         {
           "label": "Claude Code",
diff --git a/docs/harness/turn-control.md b/docs/harness/turn-control.md
index 58313d5a07..27cb1fa3fc 100644
--- a/docs/harness/turn-control.md
+++ b/docs/harness/turn-control.md
@@ -159,6 +159,8 @@ const selective = defineHarness({
 })
 ```
 
+Tools or system prompts that a plugin or a middleware adds during a turn keep the prompt cache on models with a mid-conversation channel. See [Mid-conversation changes in a harness](../advanced/mid-conversation-changes#in-a-harness).
+
 ## What you have now
 
 - A turn that goes back to work until the job is done, with a limit.

From 3eb401f57444ca3f54c890265c68cfebeef6a5df Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 16:08:07 +0200
Subject: [PATCH 187/286] test(ai-e2e): keep the order of a client tool answer
 with thinking

Claude answers thinking, tool_use, thinking, tool_use with two client tools. The client shows that order, and after the client sends the results over the wire the next request replays the blocks in that order with their signatures.
---
 .../api.anthropic-thinking-order-wire.ts      | 100 ++++++++++++++++--
 .../anthropic-thinking-order-wire.spec.ts     |  28 +++++
 2 files changed, 119 insertions(+), 9 deletions(-)

diff --git a/testing/e2e/src/routes/api.anthropic-thinking-order-wire.ts b/testing/e2e/src/routes/api.anthropic-thinking-order-wire.ts
index 871de874f5..36e74566ac 100644
--- a/testing/e2e/src/routes/api.anthropic-thinking-order-wire.ts
+++ b/testing/e2e/src/routes/api.anthropic-thinking-order-wire.ts
@@ -102,22 +102,22 @@ function text(index: number, value: string) {
   ]
 }
 
-function clientToolUse(index: number) {
+function clientToolUse(
+  index: number,
+  id = 'toolu_pick',
+  name = 'pick_arena',
+  args = '{}',
+) {
   return [
     {
       type: 'content_block_start',
       index,
-      content_block: {
-        type: 'tool_use',
-        id: 'toolu_pick',
-        name: 'pick_arena',
-        input: {},
-      },
+      content_block: { type: 'tool_use', id, name, input: {} },
     },
     {
       type: 'content_block_delta',
       index,
-      delta: { type: 'input_json_delta', partial_json: '{}' },
+      delta: { type: 'input_json_delta', partial_json: args },
     },
     { type: 'content_block_stop', index },
   ]
@@ -179,19 +179,32 @@ function blockTypes(message: { content: unknown } | undefined) {
     : []
 }
 
+/** Each block as `type:signature` or `type:id`, to check the order. */
+function blockKeys(message: { content: unknown } | undefined) {
+  return Array.isArray(message?.content)
+    ? message.content.map(
+        (block: { type: string; signature?: string; id?: string }) =>
+          `${block.type}:${block.signature ?? block.id ?? ''}`,
+      )
+    : []
+}
+
 /**
  * Anthropic signs every thinking block against the blocks before it. When
  * web_search runs inside the response, the next request must replay
  * `thinking, server_tool_use, web_search_tool_result, thinking, text` in that
  * order, or Claude rejects it with "thinking blocks ... cannot be modified".
  *
- * Two scripted runs, answered by a capturing `fetch` (no aimock fixture):
+ * Three scripted runs, answered by a capturing `fetch` (no aimock fixture):
  *
  * - `replay` — two turns through `StreamProcessor` → `uiMessagesToWire` →
  *   `chatParamsFromRequestBody` → `chat()`, as a browser client and
  *   `/api/chat` do. Returns the block order of the second request.
  * - `interrupt` — the same turn ends with a client tool. Returns the client
  *   tool requests and the client view after the interrupt snapshot.
+ * - `clientTools` — Claude answers thinking, tool_use, thinking, tool_use
+ *   with two client tools. The client sends both results back over the wire.
+ *   Returns the client view of the answer and the replayed blocks.
  */
 export const Route = createFileRoute('/api/anthropic-thinking-order-wire')({
   server: {
@@ -257,8 +270,77 @@ export const Route = createFileRoute('/api/anthropic-thinking-order-wire')({
           }
           interruptClient.finalizeStream()
 
+          const clientTools = scriptedFetch([
+            [
+              messageStart,
+              ...thinking(0, 'Check Stockholm first.', 'sig-c'),
+              ...clientToolUse(
+                1,
+                'toolu_stockholm',
+                'arena_size',
+                '{"city":"Stockholm"}',
+              ),
+              ...thinking(2, 'Now check Oslo.', 'sig-d'),
+              ...clientToolUse(
+                3,
+                'toolu_oslo',
+                'arena_size',
+                '{"city":"Oslo"}',
+              ),
+              ...end('tool_use'),
+            ],
+          ])
+          const clientToolsAdapter = createAnthropicChat(
+            'claude-sonnet-4-5',
+            DUMMY_KEY,
+            { fetch: clientTools.fetchImpl },
+          )
+          const sizeTool = {
+            name: 'arena_size',
+            description: 'Read the size of an arena.',
+          }
+          const toolClient = new StreamProcessor({})
+          toolClient.addUserMessage('Compare the two arenas')
+          /** One request, as a browser client and `/api/chat` send it. */
+          const sendClientToolTurn = async (runId: string) => {
+            const params = await chatParamsFromRequestBody({
+              threadId: 'thinking-order-client-tools',
+              runId,
+              // `JSON.parse(JSON.stringify(...))` stands in for the HTTP hop.
+              messages: JSON.parse(
+                JSON.stringify(uiMessagesToWire(toolClient.getMessages())),
+              ),
+              tools: [],
+              context: [],
+            })
+            for await (const chunk of chat({
+              ...createChatOptions({ adapter: clientToolsAdapter }),
+              messages: params.messages,
+              tools: [sizeTool],
+              stream: true,
+            })) {
+              toolClient.processChunk(chunk)
+            }
+            toolClient.finalizeStream()
+          }
+          await sendClientToolTurn('thinking-order-client-tools-1')
+          const clientToolView = toolClient
+            .getMessages()
+            .filter((message) => message.role === 'assistant')
+            .map((message) => message.parts.map((part) => part.type))
+          // The browser runs both tools and sends the results back.
+          toolClient.addToolResult('toolu_stockholm', { seats: 16000 })
+          toolClient.addToolResult('toolu_oslo', { seats: 9000 })
+          await sendClientToolTurn('thinking-order-client-tools-2')
+
           return Response.json({
             ok: true,
+            clientToolView,
+            clientToolReplay: blockKeys(
+              clientTools.bodies[1]?.messages.find(
+                (m) => m.role === 'assistant',
+              ),
+            ),
             replayedBlocks: blockTypes(
               replay.bodies[1]?.messages.find((m) => m.role === 'assistant'),
             ),
diff --git a/testing/e2e/tests/anthropic-thinking-order-wire.spec.ts b/testing/e2e/tests/anthropic-thinking-order-wire.spec.ts
index 1e9ea502d8..ca14c4a62e 100644
--- a/testing/e2e/tests/anthropic-thinking-order-wire.spec.ts
+++ b/testing/e2e/tests/anthropic-thinking-order-wire.spec.ts
@@ -40,4 +40,32 @@ test.describe('anthropic — signed thinking order around web_search', () => {
       ['thinking', 'tool-call', 'thinking', 'text', 'tool-call'],
     ])
   })
+
+  test('a client tool answer keeps its order through the client and the wire', async ({
+    request,
+  }) => {
+    const response = await request.post('/api/anthropic-thinking-order-wire')
+    expect(response.ok()).toBe(true)
+    const result = (await response.json()) as {
+      ok: boolean
+      error?: string
+      clientToolView: Array<Array<string>>
+      clientToolReplay: Array<string>
+    }
+    if (!result.ok) throw new Error(`Route failed: ${result.error}`)
+
+    // The client shows the answer in the order Claude sent it.
+    expect(result.clientToolView).toEqual([
+      ['thinking', 'tool-call', 'thinking', 'tool-call'],
+    ])
+
+    // After the client sends both tool results, the next request replays the
+    // answer in the order Claude signed it.
+    expect(result.clientToolReplay).toEqual([
+      'thinking:sig-c',
+      'tool_use:toolu_stockholm',
+      'thinking:sig-d',
+      'tool_use:toolu_oslo',
+    ])
+  })
 })

From 589b1433ae6926273af34bbb4060b626f56fe505 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 16:08:09 +0200
Subject: [PATCH 188/286] test(e2e): check mid-conversation tool changes on the
 wire

A middleware adds a tool after the first tool batch. gpt-6-astra sends it as additional_tools, claude-opus-5-5 sends a tool_addition block with the beta and the placeholder, and models outside the map send the full tools. A custom fetch with no option also sends the full tools (the gateway case).
---
 testing/e2e/src/routeTree.gen.ts              |  22 +
 .../api.mid-conversation-changes-wire.ts      | 381 ++++++++++++++++++
 .../mid-conversation-changes-wire.spec.ts     | 106 +++++
 3 files changed, 509 insertions(+)
 create mode 100644 testing/e2e/src/routes/api.mid-conversation-changes-wire.ts
 create mode 100644 testing/e2e/tests/mid-conversation-changes-wire.spec.ts

diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index 552ce72d32..3b55e110c0 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -82,6 +82,7 @@ import { Route as ApiMultimodalToolResultWireRouteImport } from './routes/api.mu
 import { Route as ApiMoonshotUsageDetailsRouteImport } from './routes/api.moonshot-usage-details'
 import { Route as ApiMistralStrictToolNullWireRouteImport } from './routes/api.mistral-strict-tool-null-wire'
 import { Route as ApiMiddlewareTestRouteImport } from './routes/api.middleware-test'
+import { Route as ApiMidConversationChangesWireRouteImport } from './routes/api.mid-conversation-changes-wire'
 import { Route as ApiMessageIdsRouteImport } from './routes/api.message-ids'
 import { Route as ApiMessageHistoryPagingRouteImport } from './routes/api.message-history-paging'
 import { Route as ApiMcpTypedTestRouteImport } from './routes/api.mcp-typed-test'
@@ -521,6 +522,12 @@ const ApiMiddlewareTestRoute = ApiMiddlewareTestRouteImport.update({
   path: '/api/middleware-test',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiMidConversationChangesWireRoute =
+  ApiMidConversationChangesWireRouteImport.update({
+    id: '/api/mid-conversation-changes-wire',
+    path: '/api/mid-conversation-changes-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
 const ApiMessageIdsRoute = ApiMessageIdsRouteImport.update({
   id: '/api/message-ids',
   path: '/api/message-ids',
@@ -888,6 +895,7 @@ export interface FileRoutesByFullPath {
   '/api/mcp-typed-test': typeof ApiMcpTypedTestRoute
   '/api/message-history-paging': typeof ApiMessageHistoryPagingRoute
   '/api/message-ids': typeof ApiMessageIdsRoute
+  '/api/mid-conversation-changes-wire': typeof ApiMidConversationChangesWireRoute
   '/api/middleware-test': typeof ApiMiddlewareTestRoute
   '/api/mistral-strict-tool-null-wire': typeof ApiMistralStrictToolNullWireRoute
   '/api/moonshot-usage-details': typeof ApiMoonshotUsageDetailsRoute
@@ -1018,6 +1026,7 @@ export interface FileRoutesByTo {
   '/api/mcp-typed-test': typeof ApiMcpTypedTestRoute
   '/api/message-history-paging': typeof ApiMessageHistoryPagingRoute
   '/api/message-ids': typeof ApiMessageIdsRoute
+  '/api/mid-conversation-changes-wire': typeof ApiMidConversationChangesWireRoute
   '/api/middleware-test': typeof ApiMiddlewareTestRoute
   '/api/mistral-strict-tool-null-wire': typeof ApiMistralStrictToolNullWireRoute
   '/api/moonshot-usage-details': typeof ApiMoonshotUsageDetailsRoute
@@ -1149,6 +1158,7 @@ export interface FileRoutesById {
   '/api/mcp-typed-test': typeof ApiMcpTypedTestRoute
   '/api/message-history-paging': typeof ApiMessageHistoryPagingRoute
   '/api/message-ids': typeof ApiMessageIdsRoute
+  '/api/mid-conversation-changes-wire': typeof ApiMidConversationChangesWireRoute
   '/api/middleware-test': typeof ApiMiddlewareTestRoute
   '/api/mistral-strict-tool-null-wire': typeof ApiMistralStrictToolNullWireRoute
   '/api/moonshot-usage-details': typeof ApiMoonshotUsageDetailsRoute
@@ -1281,6 +1291,7 @@ export interface FileRouteTypes {
     | '/api/mcp-typed-test'
     | '/api/message-history-paging'
     | '/api/message-ids'
+    | '/api/mid-conversation-changes-wire'
     | '/api/middleware-test'
     | '/api/mistral-strict-tool-null-wire'
     | '/api/moonshot-usage-details'
@@ -1411,6 +1422,7 @@ export interface FileRouteTypes {
     | '/api/mcp-typed-test'
     | '/api/message-history-paging'
     | '/api/message-ids'
+    | '/api/mid-conversation-changes-wire'
     | '/api/middleware-test'
     | '/api/mistral-strict-tool-null-wire'
     | '/api/moonshot-usage-details'
@@ -1541,6 +1553,7 @@ export interface FileRouteTypes {
     | '/api/mcp-typed-test'
     | '/api/message-history-paging'
     | '/api/message-ids'
+    | '/api/mid-conversation-changes-wire'
     | '/api/middleware-test'
     | '/api/mistral-strict-tool-null-wire'
     | '/api/moonshot-usage-details'
@@ -1672,6 +1685,7 @@ export interface RootRouteChildren {
   ApiMcpTypedTestRoute: typeof ApiMcpTypedTestRoute
   ApiMessageHistoryPagingRoute: typeof ApiMessageHistoryPagingRoute
   ApiMessageIdsRoute: typeof ApiMessageIdsRoute
+  ApiMidConversationChangesWireRoute: typeof ApiMidConversationChangesWireRoute
   ApiMiddlewareTestRoute: typeof ApiMiddlewareTestRoute
   ApiMistralStrictToolNullWireRoute: typeof ApiMistralStrictToolNullWireRoute
   ApiMoonshotUsageDetailsRoute: typeof ApiMoonshotUsageDetailsRoute
@@ -2230,6 +2244,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiMiddlewareTestRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/mid-conversation-changes-wire': {
+      id: '/api/mid-conversation-changes-wire'
+      path: '/api/mid-conversation-changes-wire'
+      fullPath: '/api/mid-conversation-changes-wire'
+      preLoaderRoute: typeof ApiMidConversationChangesWireRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/message-ids': {
       id: '/api/message-ids'
       path: '/api/message-ids'
@@ -2758,6 +2779,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiMcpTypedTestRoute: ApiMcpTypedTestRoute,
   ApiMessageHistoryPagingRoute: ApiMessageHistoryPagingRoute,
   ApiMessageIdsRoute: ApiMessageIdsRoute,
+  ApiMidConversationChangesWireRoute: ApiMidConversationChangesWireRoute,
   ApiMiddlewareTestRoute: ApiMiddlewareTestRoute,
   ApiMistralStrictToolNullWireRoute: ApiMistralStrictToolNullWireRoute,
   ApiMoonshotUsageDetailsRoute: ApiMoonshotUsageDetailsRoute,
diff --git a/testing/e2e/src/routes/api.mid-conversation-changes-wire.ts b/testing/e2e/src/routes/api.mid-conversation-changes-wire.ts
new file mode 100644
index 0000000000..4fe0fdb57a
--- /dev/null
+++ b/testing/e2e/src/routes/api.mid-conversation-changes-wire.ts
@@ -0,0 +1,381 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toolDefinition } from '@tanstack/ai'
+import { createAnthropicChat } from '@tanstack/ai-anthropic'
+import { createOpenaiChat } from '@tanstack/ai-openai'
+import { z } from 'zod'
+import type { ChatMiddleware } from '@tanstack/ai'
+
+const OPENAI_KEY = 'sk-e2e-test-dummy-key'
+const ANTHROPIC_KEY = 'sk-ant-e2e-test-dummy-key'
+
+type SseEvent = Record<string, unknown> & { type: string }
+
+/** Both SDKs read `event:` + `data:` frames. */
+function sse(events: Array<SseEvent>): string {
+  return events
+    .map((event) => `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`)
+    .join('')
+}
+
+const weatherArgs = JSON.stringify({ city: 'Paris' })
+
+const gptCall = {
+  id: 'call_weather',
+  call_id: 'call_weather',
+  type: 'function_call',
+  name: 'get_weather',
+  arguments: weatherArgs,
+  status: 'completed',
+}
+
+/** GPT calls get_weather, as OpenAI Responses streams it. */
+const gptToolCall = sse([
+  {
+    type: 'response.created',
+    response: {
+      id: 'resp_tool',
+      object: 'response',
+      model: 'gpt-6-astra',
+      status: 'in_progress',
+      output: [],
+    },
+  },
+  {
+    type: 'response.output_item.added',
+    response_id: 'resp_tool',
+    output_index: 0,
+    item: { ...gptCall, arguments: '', status: 'in_progress' },
+  },
+  {
+    type: 'response.function_call_arguments.delta',
+    response_id: 'resp_tool',
+    item_id: 'call_weather',
+    output_index: 0,
+    delta: weatherArgs,
+  },
+  {
+    type: 'response.function_call_arguments.done',
+    response_id: 'resp_tool',
+    item_id: 'call_weather',
+    output_index: 0,
+    arguments: weatherArgs,
+  },
+  {
+    type: 'response.output_item.done',
+    response_id: 'resp_tool',
+    output_index: 0,
+    item: gptCall,
+  },
+  {
+    type: 'response.completed',
+    response: {
+      id: 'resp_tool',
+      object: 'response',
+      model: 'gpt-6-astra',
+      status: 'completed',
+      output: [gptCall],
+      usage: { input_tokens: 5, output_tokens: 3, total_tokens: 8 },
+    },
+  },
+])
+
+/** GPT answers with text. */
+const gptText = sse([
+  {
+    type: 'response.created',
+    response: {
+      id: 'resp_text',
+      object: 'response',
+      model: 'gpt-6-astra',
+      status: 'in_progress',
+      output: [],
+    },
+  },
+  {
+    type: 'response.output_text.delta',
+    response_id: 'resp_text',
+    item_id: 'msg_text',
+    output_index: 0,
+    content_index: 0,
+    delta: 'Sunny in Paris.',
+  },
+  {
+    type: 'response.completed',
+    response: {
+      id: 'resp_text',
+      object: 'response',
+      model: 'gpt-6-astra',
+      status: 'completed',
+      output: [
+        {
+          id: 'msg_text',
+          type: 'message',
+          role: 'assistant',
+          status: 'completed',
+          content: [{ type: 'output_text', text: 'Sunny in Paris.' }],
+        },
+      ],
+      usage: { input_tokens: 8, output_tokens: 4, total_tokens: 12 },
+    },
+  },
+])
+
+function claudeStart(id: string): SseEvent {
+  return {
+    type: 'message_start',
+    message: {
+      id,
+      type: 'message',
+      role: 'assistant',
+      content: [],
+      model: 'claude-opus-5-5',
+      stop_reason: null,
+      stop_sequence: null,
+      usage: { input_tokens: 5, output_tokens: 0 },
+    },
+  }
+}
+
+function claudeEnd(stopReason: string): Array<SseEvent> {
+  return [
+    {
+      type: 'message_delta',
+      delta: { stop_reason: stopReason, stop_sequence: null },
+      usage: { output_tokens: 10 },
+    },
+    { type: 'message_stop' },
+  ]
+}
+
+/** Claude calls get_weather, as Anthropic Messages streams it. */
+const claudeToolCall = sse([
+  claudeStart('msg_tool'),
+  {
+    type: 'content_block_start',
+    index: 0,
+    content_block: {
+      type: 'tool_use',
+      id: 'toolu_weather',
+      name: 'get_weather',
+      input: {},
+    },
+  },
+  {
+    type: 'content_block_delta',
+    index: 0,
+    delta: { type: 'input_json_delta', partial_json: weatherArgs },
+  },
+  { type: 'content_block_stop', index: 0 },
+  ...claudeEnd('tool_use'),
+])
+
+/** Claude answers with text. */
+const claudeText = sse([
+  claudeStart('msg_text'),
+  {
+    type: 'content_block_start',
+    index: 0,
+    content_block: { type: 'text', text: '' },
+  },
+  {
+    type: 'content_block_delta',
+    index: 0,
+    delta: { type: 'text_delta', text: 'Sunny in Paris.' },
+  },
+  { type: 'content_block_stop', index: 0 },
+  ...claudeEnd('end_turn'),
+])
+
+type Captured = { body: Record<string, unknown>; beta: string | null }
+
+/** Records each request. Answers the first with `toolCall`, the rest with `text`. */
+function capture(toolCall: string, text: string) {
+  const requests: Array<Captured> = []
+  const fetchImpl: typeof fetch = async (input, init) => {
+    const request = input instanceof Request ? input : new Request(input, init)
+    requests.push({
+      body: JSON.parse(await request.text()),
+      beta: request.headers.get('anthropic-beta'),
+    })
+    return new Response(requests.length === 1 ? toolCall : text, {
+      status: 200,
+      headers: { 'Content-Type': 'text/event-stream' },
+    })
+  }
+  return { requests, fetchImpl }
+}
+
+const getWeather = toolDefinition({
+  name: 'get_weather',
+  description: 'Get the weather for a city',
+  inputSchema: z.object({ city: z.string() }),
+}).server(({ city }) => ({ city, temperature: 21 }))
+
+const getForecast = toolDefinition({
+  name: 'get_forecast',
+  description: 'Get the forecast for a city',
+  inputSchema: z.object({ city: z.string() }),
+}).server(({ city }) => ({ city, tomorrow: 'sunny' }))
+
+/** Adds get_forecast before the second model call, after the first tool batch. */
+const addForecast: ChatMiddleware = {
+  name: 'add-forecast',
+  onConfig: (ctx, config) => {
+    if (ctx.phase !== 'beforeModel' || ctx.iteration === 0) return undefined
+    if (config.tools.some((tool) => tool.name === 'get_forecast')) {
+      return undefined
+    }
+    return { tools: [...config.tools, getForecast] }
+  },
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function list(value: unknown): Array<unknown> {
+  return Array.isArray(value) ? value : []
+}
+
+function names(value: unknown): Array<string> {
+  return list(value).flatMap((tool) =>
+    isRecord(tool) && typeof tool.name === 'string' ? [tool.name] : [],
+  )
+}
+
+/** The RUN_ERROR chunks of a run, so a broken stream shows in the spec. */
+async function errorsOf(stream: AsyncIterable<{ type: string }>) {
+  const errors: Array<string> = []
+  for await (const chunk of stream) {
+    if (chunk.type === 'RUN_ERROR') errors.push(JSON.stringify(chunk))
+  }
+  return errors
+}
+
+/** What the spec checks in the two requests of one case. */
+function summarize(
+  name: string,
+  errors: Array<string>,
+  requests: Array<Captured>,
+) {
+  const [first, second] = requests
+  const last = list(second?.body.input ?? second?.body.messages).at(-1)
+  return {
+    name,
+    errors,
+    requestCount: requests.length,
+    firstTools: names(first?.body.tools),
+    secondTools: names(second?.body.tools),
+    // OpenAI: the tools of `additional_tools` input items.
+    additionalTools: list(second?.body.input).flatMap((item) =>
+      isRecord(item) && item.type === 'additional_tools'
+        ? names(item.tools)
+        : [],
+    ),
+    // Anthropic: the tools of `tool_addition` blocks in `system` messages.
+    toolAdditions: list(second?.body.messages)
+      .flatMap((message) =>
+        isRecord(message) && message.role === 'system'
+          ? list(message.content)
+          : [],
+      )
+      .flatMap((block) =>
+        isRecord(block) && block.type === 'tool_addition'
+          ? names([block.tool])
+          : [],
+      ),
+    deferred: list(second?.body.tools).flatMap((tool) =>
+      isRecord(tool) && tool.defer_loading === true ? names([tool]) : [],
+    ),
+    // The tools with a set prompt-cache marker, per request. Custom tools
+    // always send `cache_control: null`, so only an object counts.
+    toolCacheMarks: requests.map((request) =>
+      list(request.body.tools).flatMap((tool) =>
+        isRecord(tool) && isRecord(tool.cache_control) ? names([tool]) : [],
+      ),
+    ),
+    betas: requests.map((request) =>
+      request.beta ? request.beta.split(',').map((beta) => beta.trim()) : [],
+    ),
+    lastItem: isRecord(last) ? String(last.type ?? last.role) : null,
+  }
+}
+
+/** A custom `fetch` turns the channels off, so the GPT cases turn them on. */
+async function gpt(model: 'gpt-6-astra' | 'gpt-6.1-sol') {
+  const wire = capture(gptToolCall, gptText)
+  const errors = await errorsOf(
+    chat({
+      adapter: createOpenaiChat(model, OPENAI_KEY, {
+        fetch: wire.fetchImpl,
+        midConversationChannels: true,
+      }),
+      messages: [
+        { role: 'user', content: '[mid-conversation] weather in Paris' },
+      ],
+      tools: [getWeather],
+      middleware: [addForecast],
+    }),
+  )
+  return summarize(model, errors, wire.requests)
+}
+
+async function claude(
+  name: string,
+  model: 'claude-opus-5-5' | 'claude-sonnet-5-5',
+  options: { midConversationChannels?: boolean },
+) {
+  const wire = capture(claudeToolCall, claudeText)
+  const errors = await errorsOf(
+    chat({
+      adapter: createAnthropicChat(model, ANTHROPIC_KEY, {
+        fetch: wire.fetchImpl,
+        ...options,
+      }),
+      messages: [
+        { role: 'user', content: '[mid-conversation] weather in Paris' },
+      ],
+      tools: [getWeather],
+      middleware: [addForecast],
+    }),
+  )
+  return summarize(name, errors, wire.requests)
+}
+
+/**
+ * A middleware adds `get_forecast` after the first tool batch. Runs that with
+ * real adapters and a capturing `fetch` on two models in the map
+ * (`gpt-6-astra`, `claude-opus-5-5`) and two outside it (`gpt-6.1-sol`,
+ * `claude-sonnet-5-5`), all with `midConversationChannels: true`, and on
+ * `claude-opus-5-5` with no option (the gateway case). Returns what the two
+ * requests of each case held.
+ */
+export const Route = createFileRoute('/api/mid-conversation-changes-wire')({
+  server: {
+    handlers: {
+      POST: async () => {
+        try {
+          return Response.json({
+            ok: true,
+            cases: [
+              await gpt('gpt-6-astra'),
+              await gpt('gpt-6.1-sol'),
+              await claude('claude-opus-5-5', 'claude-opus-5-5', {
+                midConversationChannels: true,
+              }),
+              await claude('claude-sonnet-5-5', 'claude-sonnet-5-5', {
+                midConversationChannels: true,
+              }),
+              await claude('claude-opus-5-5 gateway', 'claude-opus-5-5', {}),
+            ],
+          })
+        } catch (error) {
+          return Response.json({
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+          })
+        }
+      },
+    },
+  },
+})
diff --git a/testing/e2e/tests/mid-conversation-changes-wire.spec.ts b/testing/e2e/tests/mid-conversation-changes-wire.spec.ts
new file mode 100644
index 0000000000..ca7b2354c9
--- /dev/null
+++ b/testing/e2e/tests/mid-conversation-changes-wire.spec.ts
@@ -0,0 +1,106 @@
+import { test, expect } from './fixtures'
+import type { APIRequestContext } from '@playwright/test'
+
+const BETA = 'mid-conversation-tool-changes-2026-07-01'
+const PLACEHOLDER = '__tanstack_deferred_placeholder__'
+
+type WireCase = {
+  name: string
+  errors: Array<string>
+  requestCount: number
+  firstTools: Array<string>
+  secondTools: Array<string>
+  additionalTools: Array<string>
+  toolAdditions: Array<string>
+  deferred: Array<string>
+  toolCacheMarks: Array<Array<string>>
+  betas: Array<Array<string>>
+  lastItem: string | null
+}
+
+/**
+ * A middleware adds `get_forecast` after the first tool batch.
+ * `/api/mid-conversation-changes-wire` runs that with the real adapters and a
+ * capturing `fetch`. Returns a lookup of what each case's two requests held.
+ */
+async function casesFrom(request: APIRequestContext) {
+  const response = await request.post('/api/mid-conversation-changes-wire')
+  expect(response.ok()).toBe(true)
+  const result = (await response.json()) as {
+    ok: boolean
+    error?: string
+    cases: Array<WireCase>
+  }
+  if (!result.ok) throw new Error(`Route failed: ${result.error}`)
+  return (name: string) => {
+    const found = result.cases.find((entry) => entry.name === name)
+    if (!found) throw new Error(`No case named ${name}`)
+    return found
+  }
+}
+
+/** The request of today: full tools, no placeholder, no beta, no change. */
+function expectFullTools(plain: WireCase) {
+  expect(plain.errors).toEqual([])
+  expect(plain.requestCount).toBe(2)
+  expect(plain.firstTools).toEqual(['get_weather'])
+  expect(plain.secondTools).toEqual(['get_weather', 'get_forecast'])
+  expect(plain.additionalTools).toEqual([])
+  expect(plain.toolAdditions).toEqual([])
+  expect(plain.deferred).toEqual([])
+  expect(plain.betas.flat()).not.toContain(BETA)
+}
+
+test.describe('mid-conversation changes: a tool added after the first tool batch', () => {
+  test('a GPT model with the channel sends it as additional_tools', async ({
+    request,
+  }) => {
+    const gpt = (await casesFrom(request))('gpt-6-astra')
+    expect(gpt.errors).toEqual([])
+    expect(gpt.requestCount).toBe(2)
+    expect(gpt.firstTools).toEqual(['get_weather'])
+    // The start of the request stays the same.
+    expect(gpt.secondTools).toEqual(['get_weather'])
+    expect(gpt.additionalTools).toEqual(['get_forecast'])
+    // The change comes after the tool result.
+    expect(gpt.lastItem).toBe('additional_tools')
+  })
+
+  test('a Claude model with the channel sends a tool_addition block and the beta', async ({
+    request,
+  }) => {
+    const claude = (await casesFrom(request))('claude-opus-5-5')
+    expect(claude.errors).toEqual([])
+    expect(claude.requestCount).toBe(2)
+    expect(claude.firstTools).toEqual(['get_weather', PLACEHOLDER])
+    expect(claude.secondTools).toEqual([
+      'get_weather',
+      PLACEHOLDER,
+      'get_forecast',
+    ])
+    expect(claude.deferred).toEqual([PLACEHOLDER, 'get_forecast'])
+    // The automatic prompt-cache marker sits on the last start tool, not on
+    // the placeholder or the deferred tool, so the cached start stays put.
+    expect(claude.toolCacheMarks).toEqual([['get_weather'], ['get_weather']])
+    expect(claude.toolAdditions).toEqual(['get_forecast'])
+    expect(claude.lastItem).toBe('system')
+    expect(claude.betas).toHaveLength(2)
+    for (const betas of claude.betas) expect(betas).toContain(BETA)
+  })
+
+  test('models without the channel send the full tools', async ({
+    request,
+  }) => {
+    const caseOf = await casesFrom(request)
+    // Both have `midConversationChannels: true`. The map still decides.
+    expectFullTools(caseOf('gpt-6.1-sol'))
+    expectFullTools(caseOf('claude-sonnet-5-5'))
+  })
+
+  test('a custom fetch with no option sends the full tools (the gateway case)', async ({
+    request,
+  }) => {
+    // claude-opus-5-5 is in the map, but a custom fetch turns the default off.
+    expectFullTools((await casesFrom(request))('claude-opus-5-5 gateway'))
+  })
+})

From 87b67bc31073e023aa754b2500dff2c24a1209fd Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 16:27:39 +0200
Subject: [PATCH 189/286] docs(ai): say when the mid-conversation record and
 the Claude beta apply

The record is saved only on a call that makes a start point or a change, and a provider tool keeps Claude out of tool mode, so that request has no beta and no placeholder.
---
 .changeset/mid-conversation-changes.md    | 2 +-
 docs/advanced/mid-conversation-changes.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.changeset/mid-conversation-changes.md b/.changeset/mid-conversation-changes.md
index 807a79d602..b942a2e2c7 100644
--- a/.changeset/mid-conversation-changes.md
+++ b/.changeset/mid-conversation-changes.md
@@ -9,7 +9,7 @@ Keep the prompt cache when tools or system prompts are added during a conversati
 
 - Before each model call, `chat()` compares the tools and the system prompts with the earlier calls. On a model with a mid-conversation channel, an added tool, or a system prompt added at the end, goes out in the conversation. The start of the request stays the same.
 - `openaiText` on `gpt-5.4-mini`, `gpt-5.5`, `gpt-5.6-luna`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-6-astra`, `gpt-6-luna`, and `gpt-6-sol`: an added tool is an `additional_tools` input item, and an added prompt is a `developer` message. The Responses adapter of `@tanstack/openai-base` sends these when a subclass sets `midConversationChannels`.
-- `anthropicText` on `claude-opus-4-8`, `claude-opus-5`, `claude-opus-5-5`, `claude-fable-5`, and `claude-fable-5-1`: every request with tools has the `mid-conversation-tool-changes-2026-07-01` beta and one placeholder tool. An added tool has `defer_loading: true` and a `tool_addition` block in a `system` message.
+- `anthropicText` on `claude-opus-4-8`, `claude-opus-5`, `claude-opus-5-5`, `claude-fable-5`, and `claude-fable-5-1`: every request with tools has the `mid-conversation-tool-changes-2026-07-01` beta and one placeholder tool, unless a provider tool such as `webSearchTool()` takes part. An added tool has `defer_loading: true` and a `tool_addition` block in a `system` message.
 - Every other model and adapter sends the same request as before.
 - The channels are on by default only with the provider's own API. A custom `baseURL`, a custom `fetch`, an injected client, or the `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL` environment variable turns the default off. Set `midConversationChannels: true` to turn the channels on anyway. Set `false` to turn them off anywhere.
 - With prompt caching on (the default), the automatic Claude tool cache marker goes on the last start tool, not on the placeholder or an added tool.
diff --git a/docs/advanced/mid-conversation-changes.md b/docs/advanced/mid-conversation-changes.md
index 727d4ee43b..9457996402 100644
--- a/docs/advanced/mid-conversation-changes.md
+++ b/docs/advanced/mid-conversation-changes.md
@@ -76,7 +76,7 @@ Before each model call, the library compares the tools and the system prompts wi
 2. A tool that you add is a change. A system prompt that you add at the end of the list is a change too. A change goes out at its place in the conversation, in the model's own format.
 3. Any other difference makes a new start point. That request sends the full lists.
 
-The library saves a small record on the first assistant message of each call, in the `midConversationChange` field. The record holds tool names and short prompt hashes, not tool definitions. Keep the field when you store messages yourself.
+The library saves a small record on the first assistant message of a call that makes a start point or a change, in the `midConversationChange` field. The record holds tool names and short prompt hashes, not tool definitions. Keep the field when you store messages yourself.
 
 ## The models
 

From 81f4d9ec3738bd7adb6165aa56e52454cda35d9e Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 18:16:10 +0200
Subject: [PATCH 190/286] feat(ai): let a middleware set the prompt cache of a
 model call

ChatMiddlewareConfig has promptCache, next to reasoning. onConfig gets the current value, and a returned value goes to the adapter on the next model call. It stays until a middleware changes it.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai/src/activities/chat/index.ts      |   2 +
 .../src/activities/chat/middleware/types.ts   |   6 +
 .../ai/tests/middleware-prompt-cache.test.ts  | 128 ++++++++++++++++++
 3 files changed, 136 insertions(+)
 create mode 100644 packages/ai/tests/middleware-prompt-cache.test.ts

diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index 84890789ae..d1676adcfa 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -4554,6 +4554,7 @@ class TextEngine<
       metadata: this.params.metadata,
       modelOptions: this.params.modelOptions,
       reasoning: this.params.reasoning,
+      promptCache: this.params.promptCache,
     }
   }
 
@@ -5023,6 +5024,7 @@ class TextEngine<
       metadata: config.metadata,
       modelOptions: config.modelOptions,
       reasoning: config.reasoning,
+      promptCache: config.promptCache ?? this.params.promptCache,
     }
 
     // Sync context fields that depend on config
diff --git a/packages/ai/src/activities/chat/middleware/types.ts b/packages/ai/src/activities/chat/middleware/types.ts
index 808d6ab2de..dffac3bfdb 100644
--- a/packages/ai/src/activities/chat/middleware/types.ts
+++ b/packages/ai/src/activities/chat/middleware/types.ts
@@ -8,6 +8,7 @@ import type {
   Interrupt,
   JSONSchema,
   ModelMessage,
+  ResolvedPromptCache,
   UIMessage,
   RunAgentResumeItem,
   StreamChunk,
@@ -341,6 +342,11 @@ export interface ChatMiddlewareConfig {
   modelOptions?: Record<string, unknown> | undefined
   /** How hard the model thinks at this call. A middleware can set or change it. */
   reasoning?: ReasoningRequest | undefined
+  /**
+   * The prompt cache of the next model call. A returned value stays until a
+   * middleware changes it.
+   */
+  promptCache?: ResolvedPromptCache | undefined
 }
 
 /**
diff --git a/packages/ai/tests/middleware-prompt-cache.test.ts b/packages/ai/tests/middleware-prompt-cache.test.ts
new file mode 100644
index 0000000000..7acca79fc4
--- /dev/null
+++ b/packages/ai/tests/middleware-prompt-cache.test.ts
@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { chat } from '../src'
+import { createMockAdapter, ev, serverTool } from './test-utils'
+import type {
+  ChatMiddleware,
+  PromptCacheOptions,
+  ResolvedPromptCache,
+} from '../src'
+
+const toolTurn = (toolCallId: string) => [
+  ev.runStarted(),
+  ev.toolStart(toolCallId, 'lookup'),
+  ev.toolArgs(toolCallId, '{}'),
+  ev.toolEnd(toolCallId),
+  ev.runFinished('tool_calls'),
+]
+
+const stopTurn = [
+  ev.runStarted(),
+  ev.textContent('Done'),
+  ev.runFinished('stop'),
+]
+
+/** Sets a long cache with key `k` at the second model call only. */
+const longAtSecondCall: ChatMiddleware = {
+  name: 'long-at-second-call',
+  onConfig: (ctx) => {
+    if (ctx.phase === 'beforeModel' && ctx.iteration === 1) {
+      return { promptCache: { retention: 'long', key: 'k' } }
+    }
+    return undefined
+  },
+}
+
+/** Run one chat() call with three model calls. Give back each call's promptCache. */
+async function promptCacheOfThreeCalls(options: {
+  threadId: string
+  promptCache?: PromptCacheOptions
+  middleware: Array<ChatMiddleware>
+}) {
+  const { adapter, calls } = createMockAdapter({
+    iterations: [toolTurn('tc-1'), toolTurn('tc-2'), stopTurn],
+  })
+  await chat({
+    adapter,
+    messages: [{ role: 'user', content: 'Hi' }],
+    tools: [serverTool('lookup', () => ({ ok: true }))],
+    stream: false,
+    ...options,
+  })
+  return calls.map((call) => call.promptCache)
+}
+
+describe('middleware onConfig promptCache', () => {
+  it('sets the cache from the second model call and keeps it for the third', async () => {
+    const seen = await promptCacheOfThreeCalls({
+      threadId: 't1',
+      middleware: [longAtSecondCall],
+    })
+    expect(seen).toStrictEqual([
+      { retention: 'short', key: 't1' },
+      { retention: 'long', key: 'k' },
+      { retention: 'long', key: 'k' },
+    ])
+  })
+
+  it('starts a later chat() call from its own option', async () => {
+    await promptCacheOfThreeCalls({
+      threadId: 't1',
+      middleware: [longAtSecondCall],
+    })
+    const seen = await promptCacheOfThreeCalls({
+      threadId: 't2',
+      promptCache: 'none',
+      middleware: [longAtSecondCall],
+    })
+    expect(seen[0]).toStrictEqual({ retention: 'none', key: 't2' })
+  })
+
+  it('gives onConfig the current promptCache', async () => {
+    const seen: Array<ResolvedPromptCache | undefined> = []
+    const { adapter } = createMockAdapter({ iterations: [stopTurn] })
+    await chat({
+      adapter,
+      messages: [{ role: 'user', content: 'Hi' }],
+      threadId: 't1',
+      promptCache: 'long',
+      stream: false,
+      middleware: [
+        {
+          name: 'recorder',
+          onConfig: (ctx, config) => {
+            if (ctx.phase === 'beforeModel') seen.push(config.promptCache)
+          },
+        },
+      ],
+    })
+    expect(seen).toStrictEqual([{ retention: 'long', key: 't1' }])
+  })
+
+  it('reaches structuredOutput when onConfig sets it at that phase', async () => {
+    let seen: ResolvedPromptCache | undefined
+    const { adapter } = createMockAdapter({
+      structuredOutput: async (options) => {
+        seen = options.chatOptions.promptCache
+        return { data: { name: 'Ada' }, rawText: '{"name":"Ada"}' }
+      },
+    })
+    const result = await chat({
+      adapter,
+      messages: [{ role: 'user', content: 'Who?' }],
+      threadId: 't1',
+      outputSchema: z.object({ name: z.string() }),
+      middleware: [
+        {
+          name: 'long-at-structured-output',
+          onConfig: (ctx) =>
+            ctx.phase === 'structuredOutput'
+              ? { promptCache: { retention: 'long', key: 'k' } }
+              : undefined,
+        },
+      ],
+    })
+    expect(result).toEqual({ name: 'Ada' })
+    expect(seen).toStrictEqual({ retention: 'long', key: 'k' })
+  })
+})

From b28bb791cba7317012decc0bfc8cdafe06c7e438 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 18:21:03 +0200
Subject: [PATCH 191/286] fix(openai-base): send the function call namespace
 back to the Responses API

A tool that came through additional_tools comes back with a namespace. The adapter kept only the item id, so the next request failed with 400 Missing namespace for function_call. The tool call metadata now keeps the namespace, and the replayed function_call item sends it. Found by a live check on gpt-5.5.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .../responses-function-call-namespace.md      |  5 +
 .../src/adapters/responses-text.ts            | 30 ++++--
 .../tests/responses-mid-conversation.test.ts  | 99 +++++++++++++++++++
 3 files changed, 125 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/responses-function-call-namespace.md

diff --git a/.changeset/responses-function-call-namespace.md b/.changeset/responses-function-call-namespace.md
new file mode 100644
index 0000000000..3603655621
--- /dev/null
+++ b/.changeset/responses-function-call-namespace.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/openai-base': patch
+---
+
+Send the `namespace` of a function call back to the Responses API. A tool that came through `additional_tools` is called in a namespace, and without it the next request failed with `400 Missing namespace for function_call`. The adapter now keeps the namespace in the tool call metadata and sends it with the replayed `function_call` item.
diff --git a/packages/openai-base/src/adapters/responses-text.ts b/packages/openai-base/src/adapters/responses-text.ts
index 3f92514a8d..07534b74f6 100644
--- a/packages/openai-base/src/adapters/responses-text.ts
+++ b/packages/openai-base/src/adapters/responses-text.ts
@@ -200,6 +200,11 @@ function readReasoningItem(
  */
 export interface OpenAIResponsesToolCallMetadata extends ProviderExecutedToolMetadata {
   itemId?: string
+  /**
+   * The namespace of the called function. A tool that came through
+   * `additional_tools` has one, and the API needs it on the replayed call.
+   */
+  namespace?: string
   /** Set for shell, local_shell, and apply_patch calls the app must run. */
   openaiUserTool?: OpenAIUserToolName
   /** Shell `action.max_output_length`, echoed on `shell_call_output`. */
@@ -211,6 +216,17 @@ export interface OpenAIResponsesToolCallMetadata extends ProviderExecutedToolMet
   }
 }
 
+/** The tool call metadata of a streamed `function_call` item. */
+function functionCallMetadata(item: {
+  id?: string
+  namespace?: string
+}): OpenAIResponsesToolCallMetadata {
+  return {
+    ...(item.id ? { itemId: item.id } : {}),
+    ...(item.namespace ? { namespace: item.namespace } : {}),
+  }
+}
+
 interface StreamedFunctionCallMetadata {
   callId: string
   index: number
@@ -1627,9 +1643,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
                 model: model || options.model,
                 timestamp: Date.now(),
                 index: chunk.output_index,
-                metadata: {
-                  itemId: item.id,
-                } satisfies OpenAIResponsesToolCallMetadata,
+                metadata: functionCallMetadata(item),
               }
               metadata.started = true
             }
@@ -1789,9 +1803,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
                 model: model || options.model,
                 timestamp: Date.now(),
                 index: metadata.index,
-                metadata: {
-                  itemId: item.id,
-                } satisfies OpenAIResponsesToolCallMetadata,
+                metadata: functionCallMetadata(item),
               }
               metadata.started = true
             }
@@ -1958,9 +1970,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
                 model: model || options.model,
                 timestamp: Date.now(),
                 index: metadata.index,
-                metadata: {
-                  itemId: item.id,
-                } satisfies OpenAIResponsesToolCallMetadata,
+                metadata: functionCallMetadata(item),
               }
               metadata.started = true
             }
@@ -2489,6 +2499,8 @@ export abstract class OpenAIBaseResponsesTextAdapter<
               ...(itemId && canPairReasoning && { id: itemId }),
               name: toolCall.function.name,
               arguments: argumentsString,
+              // Without its namespace, the API cannot find an added tool.
+              ...(metadata?.namespace && { namespace: metadata.namespace }),
             })
           }
         }
diff --git a/packages/openai-base/tests/responses-mid-conversation.test.ts b/packages/openai-base/tests/responses-mid-conversation.test.ts
index 530f3e0abb..b3da3a4ea7 100644
--- a/packages/openai-base/tests/responses-mid-conversation.test.ts
+++ b/packages/openai-base/tests/responses-mid-conversation.test.ts
@@ -225,3 +225,102 @@ describe('Responses mid-conversation changes', () => {
     expect(JSON.stringify(body)).toBe(JSON.stringify(today))
   })
 })
+
+describe('Responses function call namespace', () => {
+  // A tool that came through `additional_tools` is called in a namespace. The
+  // next request must send that namespace back, or the API answers 400.
+  const namespacedCall = {
+    id: 'fc_weather',
+    type: 'function_call',
+    call_id: 'call-weather',
+    name: 'get_weather',
+    namespace: 'get_weather',
+  }
+
+  /** A Responses stream in which the model calls `get_weather`. */
+  function namespacedCallStream() {
+    return (async function* () {
+      yield {
+        type: 'response.created',
+        response: { id: 'resp-2', model: 'test-model', status: 'in_progress' },
+      }
+      yield {
+        type: 'response.output_item.added',
+        output_index: 0,
+        item: { ...namespacedCall, status: 'in_progress', arguments: '' },
+      }
+      yield {
+        type: 'response.output_item.done',
+        output_index: 0,
+        item: {
+          ...namespacedCall,
+          status: 'completed',
+          arguments: '{"city":"Paris"}',
+        },
+      }
+      yield {
+        type: 'response.completed',
+        response: {
+          id: 'resp-2',
+          model: 'test-model',
+          status: 'completed',
+          output: [],
+          usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
+        },
+      }
+    })()
+  }
+
+  beforeEach(() => {
+    create.mockReset()
+  })
+
+  it('keeps the namespace of a streamed function call in the tool call metadata', async () => {
+    create.mockImplementation(() => Promise.resolve(namespacedCallStream()))
+    const starts: Array<unknown> = []
+    for await (const chunk of new ChannelAdapter(both).chatStream({
+      logger,
+      model: 'test-model',
+      messages: [{ role: 'user', content: 'Weather in Paris?' }],
+    })) {
+      if (chunk.type === 'TOOL_CALL_START') starts.push(chunk.metadata)
+    }
+
+    expect(starts).toEqual([{ itemId: 'fc_weather', namespace: 'get_weather' }])
+  })
+
+  it('sends the namespace back with the replayed function call', async () => {
+    create.mockImplementation(() => Promise.resolve(completedStream()))
+    const body = await send(new ChannelAdapter(both), {
+      messages: [
+        { role: 'user', content: 'Weather in Paris?' },
+        {
+          role: 'assistant',
+          content: null,
+          toolCalls: [
+            {
+              id: 'call-weather',
+              type: 'function',
+              function: { name: 'get_weather', arguments: '{"city":"Paris"}' },
+              metadata: { itemId: 'fc_weather', namespace: 'get_weather' },
+            },
+          ],
+        },
+        { role: 'tool', toolCallId: 'call-weather', content: 'Sunny' },
+      ],
+    })
+
+    expect(
+      body.input.find(
+        (item: { type?: string }) => item.type === 'function_call',
+      ),
+    ).toEqual({
+      type: 'function_call',
+      call_id: 'call-weather',
+      id: 'fc_weather',
+      name: 'get_weather',
+      arguments: '{"city":"Paris"}',
+      namespace: 'get_weather',
+    })
+  })
+})

From 577ef1cf215d070ff5be461c390e6073bc90c3cb Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 18:25:58 +0200
Subject: [PATCH 192/286] feat(ai-harness): add per-turn overrides to prompt()
 and followUp()

prompt() and followUp() take overrides: an adapter, reasoning, a prompt cache, and extra tools for one turn. They apply to every chat() call of the turn. They live in memory only: a queued turn keeps them, a joined steer uses the host turn's overrides, and a recovered turn uses the defaults. A middleware that rebuilds the tools keeps the override tools. HarnessConfig.reasoning sets the default reasoning, and the plugin adapter picker now gets the turn.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-harness/src/define.ts             |   7 +
 packages/ai-harness/src/index.ts              |   1 +
 packages/ai-harness/src/plugins.ts            |  11 +-
 packages/ai-harness/src/session.ts            |  80 ++-
 packages/ai-harness/src/types.ts              |  36 ++
 .../ai-harness/tests/turn-overrides.test.ts   | 454 ++++++++++++++++++
 6 files changed, 577 insertions(+), 12 deletions(-)
 create mode 100644 packages/ai-harness/tests/turn-overrides.test.ts

diff --git a/packages/ai-harness/src/define.ts b/packages/ai-harness/src/define.ts
index 92019d9f36..09477f75de 100644
--- a/packages/ai-harness/src/define.ts
+++ b/packages/ai-harness/src/define.ts
@@ -7,6 +7,7 @@ import type {
   KeyedAdapter,
   ModelMessage,
   PromptCacheOptions,
+  ReasoningRequest,
   SubagentRouterPick,
   SubagentsBag,
   SystemPrompt,
@@ -131,6 +132,12 @@ export interface HarnessConfig<
    * session uses its threadId as the key.
    */
   promptCache?: PromptCacheOptions
+  /**
+   * How hard the main model thinks on every turn, as the adapter gets it in
+   * `TextOptions`. Not set: no reasoning is sent, and the provider default
+   * applies. `overrides.reasoning` of a turn replaces it.
+   */
+  reasoning?: ReasoningRequest
   interrupts?: ReadonlyArray<InterruptDefinition<any, any, any, any>>
   /** Runtime context passed to middleware hooks and server tools. */
   context?: unknown
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index c7e3d703bf..649c2ddf35 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -122,6 +122,7 @@ export type {
   Principal,
   Receipt,
   SessionEvent,
+  TurnOverrides,
   UserInput,
 } from './types'
 
diff --git a/packages/ai-harness/src/plugins.ts b/packages/ai-harness/src/plugins.ts
index 110c08efce..932f58cee6 100644
--- a/packages/ai-harness/src/plugins.ts
+++ b/packages/ai-harness/src/plugins.ts
@@ -18,7 +18,7 @@ import type {
   AgentResultOf,
   AnyAgent,
 } from './agents'
-import type { Operation } from './types'
+import type { Operation, TurnOverrides } from './types'
 import type { CredentialsAccess } from './auth'
 import type { AnyCommand, PluginSessionApi } from './commands'
 import type { ConfigOption } from './config'
@@ -74,9 +74,14 @@ export interface PluginContributions {
   /**
    * Pick the main-loop adapter for the next turn, or return `undefined` to
    * keep the harness adapter. The last plugin that returns one wins. The
-   * session builds a `keyedAdapter(...)` with the user's key.
+   * session builds a `keyedAdapter(...)` with the user's key. `turn` is the
+   * turn that starts. Its `overrides.adapter` wins over every pick.
    */
-  adapter?: () => AnyTextAdapter | KeyedAdapter<AnyTextAdapter> | undefined
+  adapter?: (turn: {
+    operationId: string
+    inputId?: string
+    overrides?: TurnOverrides
+  }) => AnyTextAdapter | KeyedAdapter<AnyTextAdapter> | undefined
   /**
    * Tools found at run time, for example the tools of an MCP server the user
    * signed in to after the session opened. Called before each chat turn. A
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index d7ddcfca8d..decbfe6e47 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -109,6 +109,7 @@ import type {
   Principal,
   Receipt,
   SessionEvent,
+  TurnOverrides,
   UserInput,
 } from './types'
 
@@ -252,6 +253,8 @@ interface QueuedTurn {
   resume?: Array<RunAgentResumeItem>
   parentRunId?: string
   inputId?: string
+  /** The settings of this one turn. Kept in memory only, not in the log. */
+  overrides?: TurnOverrides
   /**
    * A resolve of a routed turn: the messages it continues from, with the
    * agents' cards. `root` is true when `routing` sent the turn to root
@@ -368,6 +371,24 @@ function isRoutedBag(bag: Pick<SubagentsBag, 'agents' | 'router'> | undefined) {
   return bag !== undefined && bag.agents.length > 0 && bag.router !== undefined
 }
 
+/**
+ * Middleware that keeps the override tools of a turn. A middleware `onConfig`
+ * can return a tool list without them, and this adds back each one whose
+ * name is missing.
+ */
+function keepTurnTools(kept: ReadonlyArray<AnyTool>) {
+  return {
+    name: 'harness:turn-tools',
+    onConfig: (ctx, config) => {
+      if (ctx.phase !== 'init' && ctx.phase !== 'beforeModel') return
+      const names = new Set(config.tools.map((tool) => tool.name))
+      const missing = kept.filter((tool) => !names.has(tool.name))
+      if (missing.length === 0) return
+      return { tools: [...config.tools, ...missing] }
+    },
+  } satisfies AnyChatMiddleware
+}
+
 /** The turn has its final answer: an assistant message with no open tool call after it was applied. */
 function hasFinalAnswer(
   messages: ReadonlyArray<ModelMessage>,
@@ -459,6 +480,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     inputId: string
     message: UserInput
     operation?: OperationImpl<ChatTurnResult>
+    /** Used only when the steer runs as its own turn. A join ignores them. */
+    overrides?: TurnOverrides
   }> = []
   /**
    * Waiting steers with an abort request. An id lands here before the abort
@@ -802,13 +825,22 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
    * same message returns the first input's operation and does not run again.
    * The same id with another message is rejected with `'conflict'`.
    * `await operation.receipt` resolves when the input is stored.
+   *
+   * `overrides` changes the adapter, reasoning, prompt cache, or tools of
+   * this turn only (see `TurnOverrides`). A steer that joins the running
+   * turn uses the overrides of that turn, and its own are ignored.
    */
   prompt(
     message: UserInput,
-    options?: { busy?: BusyPolicy; inputId?: string },
+    options?: {
+      busy?: BusyPolicy
+      inputId?: string
+      overrides?: TurnOverrides
+    },
   ): Operation<ChatTurnResult> {
     const busy = options?.busy ?? this.harness.busy ?? 'queue'
     const inputId = options?.inputId ?? createInputId()
+    const overrides = options?.overrides
     const input: HarnessInput = { op: 'prompt', message, busy }
     const known = this.knownTurn(inputId, input)
     if (known) return known
@@ -836,10 +868,10 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           operationId: operation.id,
         })
         if (this.activeTurn && busy === 'steer') {
-          this.steerQueue.push({ inputId, message, operation })
+          this.steerQueue.push({ inputId, message, operation, overrides })
           return
         }
-        this.enqueueTurn({ operation, message, inputId })
+        this.enqueueTurn({ operation, message, inputId, overrides })
       },
       (error: unknown) => {
         // The input was not stored. After a log failure, say why the
@@ -882,10 +914,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     })
   }
 
-  /** Run a turn after the current work settles. */
+  /**
+   * Run a turn after the current work settles. `overrides` changes the
+   * adapter, reasoning, prompt cache, or tools of this turn only.
+   */
   async followUp(
     message: UserInput,
-    options?: { inputId?: string },
+    options?: { inputId?: string; overrides?: TurnOverrides },
   ): Promise<Receipt> {
     const inputId = options?.inputId ?? createInputId()
     const admission = await this.accept(inputId, { op: 'followUp', message })
@@ -894,7 +929,12 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     this.bindTurn(inputId, operation)
     const status =
       this.activeTurn || this.queue.length > 0 ? 'queued' : 'accepted'
-    this.enqueueTurn({ operation, message, inputId })
+    this.enqueueTurn({
+      operation,
+      message,
+      inputId,
+      overrides: options?.overrides,
+    })
     return this.keep({ inputId, status, operationId: operation.id })
   }
 
@@ -2045,19 +2085,26 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           ...(runPlugins?.agents ?? []),
         ]),
       ]
+      // The settings of this turn. Every chat() call below uses them: the
+      // tool loop, retries, `beforeFinish` cycles, handoffs, and late joins.
+      const { overrides } = turn
       const picked = [
         ...(session?.adapters ?? []),
         ...(runPlugins?.adapters ?? []),
       ]
-        .map((pick) => pick())
+        .map((pick) =>
+          pick({ operationId: operation.id, inputId: turn.inputId, overrides }),
+        )
         .filter((adapter) => adapter !== undefined)
         .at(-1)
       const resolvePrompt = (prompt: string | (() => string)) =>
         typeof prompt === 'function' ? prompt() : prompt
+      const turnTools = overrides?.tools ?? []
       const staticTools = [
         ...(this.harness.tools ?? []),
         ...(session?.tools ?? []),
         ...(runPlugins?.tools ?? []),
+        ...turnTools,
       ]
       const discovered = await this.discoverTools(
         [...(session?.discoverers ?? []), ...(runPlugins?.discoverers ?? [])],
@@ -2077,10 +2124,22 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       const tools = bindTool
         ? prepared.map((tool) => bindDurable(tool, bindTool))
         : prepared
+      // The override tools as the turn has them: prepared and bound.
+      const turnToolNames = new Set(turnTools.map((tool) => tool.name))
+      const keptTools = tools.filter((tool) => turnToolNames.has(tool.name))
+      const keepTools =
+        keptTools.length > 0 ? keepTurnTools(keptTools) : undefined
+      const reasoning = overrides?.reasoning ?? this.harness.reasoning
+      // The turn value wins over the session value, field by field.
+      const turnCache = cacheObject(overrides?.promptCache)
+      const promptCache = {
+        retention: turnCache?.retention ?? this.promptCache.retention,
+        key: turnCache?.key ?? this.promptCache.key,
+      }
       // A keyed adapter is built for this turn with the user's key. A
       // missing key publishes `auth_required` and fails the turn.
       const adapter: AnyTextAdapter = await this.keys.adapter(
-        picked ?? this.harness.adapter,
+        overrides?.adapter ?? picked ?? this.harness.adapter,
       )
       let message =
         turn.message !== undefined
@@ -2200,6 +2259,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
               ...(this.harness.middleware ?? []),
               ...(session?.middleware ?? []),
               ...(runPlugins?.middleware ?? []),
+              ...(keepTools ? [keepTools] : []),
               ...(durableTools ? [durableTools] : []),
               ...(rootBag ? [] : [this.steering()]),
               // Last, because a later middleware that returns `messages` (as
@@ -2235,7 +2295,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             ...(this.harness.context !== undefined
               ? { context: this.harness.context }
               : {}),
-            promptCache: this.promptCache,
+            ...(reasoning !== undefined ? { reasoning } : {}),
+            promptCache,
             threadId: this.threadId,
             runId: operation.id,
             ...(parentRunId ? { parentRunId } : {}),
@@ -2525,6 +2586,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           operation: next,
           message: steer.message,
           inputId: steer.inputId,
+          overrides: steer.overrides,
         }
       }),
     )
diff --git a/packages/ai-harness/src/types.ts b/packages/ai-harness/src/types.ts
index f05a4868a3..739934a210 100644
--- a/packages/ai-harness/src/types.ts
+++ b/packages/ai-harness/src/types.ts
@@ -1,6 +1,11 @@
 import type {
+  AnyTextAdapter,
+  AnyTool,
   ContentPart,
   Interrupt,
+  KeyedAdapter,
+  PromptCacheOptions,
+  ReasoningRequest,
   RunAgentResumeItem,
   StreamChunk,
 } from '@tanstack/ai'
@@ -8,6 +13,37 @@ import type {
 /** A user message: plain text, or content parts (text, images, files). */
 export type UserInput = string | Array<ContentPart>
 
+/**
+ * Settings for one chat turn: `session.prompt(message, { overrides })` or
+ * `session.followUp(message, { overrides })`. They apply to every model call
+ * of the turn, retries included. The rest of the session keeps its defaults.
+ *
+ * They live only in memory, on the queued turn, so they are not part of the
+ * input: the `inputId` duplicate check does not read them. A turn that
+ * recovery runs again after a restart uses the defaults. A steer that joins
+ * a running turn uses the overrides of that turn.
+ *
+ * @example
+ * ```ts
+ * session.prompt('Plan the migration.', {
+ *   overrides: { reasoning: { level: 'high', summary: true }, tools: [planTool] },
+ * })
+ * ```
+ */
+export interface TurnOverrides {
+  /** Replaces the harness adapter and every plugin pick for this turn. */
+  adapter?: AnyTextAdapter | KeyedAdapter<AnyTextAdapter>
+  /** Replaces `HarnessConfig.reasoning` for this turn. */
+  reasoning?: ReasoningRequest
+  /** Replaces the session and harness values for this turn, field by field. */
+  promptCache?: PromptCacheOptions
+  /**
+   * Added to the static tools of this turn. A name that a static tool has
+   * fails the turn. Durable tools get `step` and `append`.
+   */
+  tools?: ReadonlyArray<AnyTool>
+}
+
 /**
  * What a `prompt` does when a chat turn is already running:
  * - `queue` (default): runs as a new turn after the current one settles.
diff --git a/packages/ai-harness/tests/turn-overrides.test.ts b/packages/ai-harness/tests/turn-overrides.test.ts
new file mode 100644
index 0000000000..e877d1b426
--- /dev/null
+++ b/packages/ai-harness/tests/turn-overrides.test.ts
@@ -0,0 +1,454 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { EventType, toolDefinition } from '@tanstack/ai'
+import { defineByokProvider, keyedAdapter } from '@tanstack/ai/byok'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  createHarnessHost,
+  defineHarness,
+  definePlugin,
+  durableTool,
+} from '../src'
+import {
+  after,
+  gate,
+  messageTexts,
+  mockAdapter,
+  text,
+  toolCall,
+  untilAborted,
+} from './helpers'
+import type {
+  AnyChatMiddleware,
+  AnyTool,
+  ModelMessage,
+  PromptCacheOptions,
+  ReasoningRequest,
+} from '@tanstack/ai'
+import type { HarnessConfig, PluginContributions } from '../src'
+import type { Reply } from './helpers'
+
+const THREAD = 't1'
+const HIGH: ReasoningRequest = { level: 'high', summary: true }
+const LOW: ReasoningRequest = { level: 'low', summary: false }
+
+afterEach(() => {
+  vi.unstubAllEnvs()
+})
+
+function durablePersistence() {
+  const { runs, metadata } = memoryPersistence().stores
+  return { stores: { log: memoryLogStore(), runs, metadata } }
+}
+
+type Durable = ReturnType<typeof durablePersistence>
+
+/** Open a session whose default adapter answers with `replies`. */
+async function open(
+  replies: Array<Reply>,
+  extras: Omit<HarnessConfig, 'name' | 'adapter'> = {},
+  options: { persistence?: Durable; promptCache?: PromptCacheOptions } = {},
+) {
+  const { adapter, calls } = mockAdapter(replies)
+  const host = createHarnessHost({
+    persistence: options.persistence ?? memoryPersistence(),
+  })
+  const session = await host.open(
+    defineHarness({ name: 'test/turn-overrides', adapter, ...extras }),
+    {
+      threadId: THREAD,
+      ...(options.promptCache ? { promptCache: options.promptCache } : {}),
+    },
+  )
+  return { host, session, calls }
+}
+
+/** A tool that answers `found`, after `during` when it is set. */
+const lookupTool = (during?: () => Promise<void>) =>
+  toolDefinition({
+    name: 'lookup',
+    description: 'Look something up',
+    inputSchema: z.object({ q: z.string() }),
+  }).server(async () => {
+    await during?.()
+    return 'found'
+  })
+
+const lookup = lookupTool()
+
+/** A model call that ends with a RUN_ERROR. */
+const failsWith =
+  (message: string): Reply =>
+  () => [
+    {
+      type: EventType.RUN_STARTED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: Date.now(),
+    },
+    { type: EventType.RUN_ERROR, message, timestamp: Date.now() },
+  ]
+
+/** The names of the tools the adapter got on one call. */
+const toolNames = (call: { tools?: ReadonlyArray<AnyTool> }) =>
+  (call.tools ?? []).map((tool) => tool.name)
+
+/** The content of the tool result for `toolCallId` in the transcript. */
+const toolResult = (
+  transcript: ReadonlyArray<ModelMessage>,
+  toolCallId: string,
+) =>
+  transcript.find(
+    (message) => message.role === 'tool' && message.toolCallId === toolCallId,
+  )?.content
+
+/** The records of the log, of one type. */
+async function recordsOf(persistence: Durable, type: string) {
+  return (await persistence.stores.log.read(THREAD))
+    .map((entry) => entry.record)
+    .filter((record) => record.type === type)
+}
+
+describe('turn overrides: adapter', () => {
+  it('uses the turn adapter in the tool loop and in a retry, then the default again', async () => {
+    const turnModel = mockAdapter([
+      () => toolCall('lookup', { q: 'x' }),
+      failsWith('overloaded'),
+      () => text('done'),
+    ])
+    const { host, session, calls } = await open([() => text('default')], {
+      tools: [lookup],
+      turn: {
+        onModelError: ({ retries }) => (retries === 0 ? 'retry' : undefined),
+      },
+    })
+
+    expect(
+      await session.prompt('go', { overrides: { adapter: turnModel.adapter } }),
+    ).toEqual({ text: 'done' })
+    expect(await session.prompt('again')).toEqual({ text: 'default' })
+
+    expect(turnModel.calls).toHaveLength(3)
+    expect(calls).toHaveLength(1)
+    await host.close()
+  })
+
+  it('builds a keyed turn adapter with the key of the user', async () => {
+    vi.stubEnv('TURN_OVERRIDES_TEST_KEY', 'sk-env-1234')
+    const provider = defineByokProvider({
+      id: 'turn-test',
+      label: 'Turn test',
+      env: 'TURN_OVERRIDES_TEST_KEY',
+    })
+    const turnModel = mockAdapter([() => text('keyed')])
+    const keys: Array<string> = []
+    const keyed = keyedAdapter(provider, (key) => {
+      keys.push(key)
+      return turnModel.adapter
+    })
+    const { host, session } = await open([])
+
+    expect(
+      await session.prompt('go', { overrides: { adapter: keyed } }),
+    ).toEqual({ text: 'keyed' })
+    expect(keys).toEqual(['sk-env-1234'])
+    await host.close()
+  })
+
+  it('runs a followUp with its overrides', async () => {
+    const turnModel = mockAdapter([() => text('followed')])
+    const { host, session, calls } = await open([])
+
+    await session.followUp('go', {
+      inputId: 'follow-1',
+      overrides: { adapter: turnModel.adapter },
+    })
+
+    expect(await session.settled('follow-1')).toMatchObject({
+      outcome: 'completed',
+    })
+    expect(turnModel.calls).toHaveLength(1)
+    expect(calls).toHaveLength(0)
+    await host.close()
+  })
+})
+
+describe('turn overrides: reasoning and prompt cache', () => {
+  it('sends the turn reasoning and prompt cache for that turn only', async () => {
+    const { host, session, calls } = await open(
+      [() => text('a'), () => text('b')],
+      {},
+      { promptCache: 'long' },
+    )
+
+    await session.prompt('go', {
+      overrides: { reasoning: HIGH, promptCache: { key: 'turn-key' } },
+    })
+    await session.prompt('again')
+
+    expect(calls[0].reasoning).toEqual({ level: 'high', summary: true })
+    // The session retention stays. Only the key changes.
+    expect(calls[0].promptCache).toEqual({
+      retention: 'long',
+      key: 'turn-key',
+    })
+    expect(calls[1].reasoning).toBeUndefined()
+    expect(calls[1].promptCache).toEqual({ retention: 'long', key: THREAD })
+    await host.close()
+  })
+
+  it('sends HarnessConfig.reasoning on every turn, and a turn value replaces it', async () => {
+    const { host, session, calls } = await open(
+      [() => text('a'), () => text('b'), () => text('c')],
+      { reasoning: LOW },
+    )
+
+    await session.prompt('one')
+    await session.prompt('two')
+    await session.prompt('three', { overrides: { reasoning: HIGH } })
+
+    expect(calls.map((call) => call.reasoning)).toEqual([
+      { level: 'low', summary: false },
+      { level: 'low', summary: false },
+      { level: 'high', summary: true },
+    ])
+    await host.close()
+  })
+})
+
+describe('turn overrides: tools', () => {
+  it('lets the model call a turn tool in that turn only', async () => {
+    const { host, session, calls } = await open([
+      () => toolCall('lookup', { q: 'x' }, 'call-lookup'),
+      () => text('done'),
+      () => text('again'),
+    ])
+
+    await session.prompt('go', { overrides: { tools: [lookup] } })
+    await session.prompt('again')
+
+    expect(toolResult(await session.transcript(), 'call-lookup')).toBe('found')
+    expect(toolNames(calls[0])).toEqual(['lookup'])
+    expect(toolNames(calls[2])).toEqual([])
+    await host.close()
+  })
+
+  it('keeps a turn tool when a middleware returns only the static tools', async () => {
+    const look = toolDefinition({ name: 'look', description: 'Look' }).server(
+      async () => 'seen',
+    )
+    const onlyStatic: AnyChatMiddleware = {
+      name: 'only-static',
+      onConfig: () => ({ tools: [look] }),
+    }
+    const { host, session, calls } = await open(
+      [() => toolCall('lookup', { q: 'x' }, 'call-lookup'), () => text('done')],
+      { tools: [look], middleware: [onlyStatic] },
+    )
+
+    await session.prompt('go', { overrides: { tools: [lookup] } })
+
+    expect(toolNames(calls[0])).toEqual(['look', 'lookup'])
+    expect(toolResult(await session.transcript(), 'call-lookup')).toBe('found')
+    await host.close()
+  })
+
+  it('gives a durable turn tool step and append on a durable host', async () => {
+    const persistence = durablePersistence()
+    const note = durableTool(
+      toolDefinition({ name: 'note', description: 'Write a note' }),
+      async (_args, { step, append }) => {
+        append([{ type: 'app.note', value: 1 }])
+        return step.do('write', async () => 'noted')
+      },
+    )
+    const { host, session } = await open(
+      [() => toolCall('note', {}, 'call-note'), () => text('done')],
+      {},
+      { persistence },
+    )
+
+    await session.prompt('note it', { overrides: { tools: [note] } })
+
+    expect(toolResult(await session.transcript(), 'call-note')).toBe('noted')
+    expect(await recordsOf(persistence, 'app.note')).toEqual([
+      { type: 'app.note', value: 1 },
+    ])
+    expect(
+      (await recordsOf(persistence, 'harness.tool.step')).map(
+        (record) => record.name,
+      ),
+    ).toEqual(['write'])
+    await host.close()
+  })
+
+  it('fails a turn tool with the name of a static tool, like two static tools', async () => {
+    const other = toolDefinition({
+      name: 'lookup',
+      description: 'Look something up somewhere else',
+      inputSchema: z.object({ q: z.string() }),
+    }).server(async () => 'other')
+    const duplicate =
+      'Cannot pass two tools named "lookup" in the same chat() call.'
+    const twoStatic = await open([() => text('never')], {
+      tools: [lookup, other],
+    })
+    const clash = await open([() => text('never')], { tools: [lookup] })
+
+    await expect(twoStatic.session.prompt('go')).rejects.toThrow(duplicate)
+    await expect(
+      clash.session.prompt('go', { overrides: { tools: [other] } }),
+    ).rejects.toThrow(duplicate)
+
+    expect(clash.calls).toHaveLength(0)
+    await twoStatic.host.close()
+    await clash.host.close()
+  })
+})
+
+describe('turn overrides: queue, steer, and recovery', () => {
+  it('runs a queued turn with its overrides after the running turn ends', async () => {
+    const release = gate()
+    const turnModel = mockAdapter([() => text('second')])
+    const { host, session, calls } = await open([
+      after(release.opened, 'first'),
+    ])
+
+    const first = session.prompt('one')
+    const second = session.prompt('two', {
+      overrides: { adapter: turnModel.adapter },
+    })
+    expect((await second.receipt).status).toBe('queued')
+    release.open()
+
+    expect(await first).toEqual({ text: 'first' })
+    expect(await second).toEqual({ text: 'second' })
+    expect(calls).toHaveLength(1)
+    expect(turnModel.calls).toHaveLength(1)
+    await host.close()
+  })
+
+  it('gives a steer that joins a turn the overrides of that turn', async () => {
+    const toolRuns = gate()
+    const release = gate()
+    const slowLookup = lookupTool(async () => {
+      toolRuns.open()
+      await release.opened
+    })
+    const hostModel = mockAdapter([
+      () => toolCall('lookup', { q: 'x' }),
+      () => text('done'),
+    ])
+    const steerModel = mockAdapter([() => text('never')])
+    const { host, session, calls } = await open([], { tools: [slowLookup] })
+
+    const turn = session.prompt('one', {
+      overrides: { adapter: hostModel.adapter },
+    })
+    await toolRuns.opened
+    const steer = session.prompt('two', {
+      busy: 'steer',
+      overrides: { adapter: steerModel.adapter },
+    })
+    await steer.receipt
+    release.open()
+
+    expect(await turn).toEqual({ text: 'done' })
+    expect(await steer).toEqual({ text: 'done' })
+    expect(messageTexts(hostModel.calls[1])).toContain('two')
+    expect(steerModel.calls).toHaveLength(0)
+    expect(calls).toHaveLength(0)
+    await host.close()
+  })
+
+  it('runs a steer that does not join as its own turn, with its own overrides', async () => {
+    const release = gate()
+    const hostModel = mockAdapter([after(release.opened, 'first')])
+    const steerModel = mockAdapter([() => text('second')])
+    const { host, session, calls } = await open([], {
+      turn: { canJoin: () => false },
+    })
+
+    const turn = session.prompt('one', {
+      overrides: { adapter: hostModel.adapter },
+    })
+    await vi.waitFor(() => expect(hostModel.calls).toHaveLength(1))
+    const steer = session.prompt('two', {
+      busy: 'steer',
+      overrides: { adapter: steerModel.adapter },
+    })
+    await steer.receipt
+    release.open()
+
+    expect(await turn).toEqual({ text: 'first' })
+    expect(await steer).toEqual({ text: 'second' })
+    expect(hostModel.calls).toHaveLength(1)
+    expect(steerModel.calls).toHaveLength(1)
+    expect(calls).toHaveLength(0)
+    await host.close()
+  })
+
+  it('runs a recovered turn after a restart with the defaults', async () => {
+    const persistence = durablePersistence()
+    const stopped = mockAdapter([untilAborted()])
+    const first = await open([], {}, { persistence })
+    const turn = first.session.prompt('go', {
+      inputId: 'in-1',
+      overrides: {
+        adapter: stopped.adapter,
+        reasoning: HIGH,
+        promptCache: { key: 'turn-key' },
+      },
+    })
+    await vi.waitFor(() => expect(stopped.calls).toHaveLength(1))
+    // The first host stops: its run lease expires.
+    await persistence.stores.runs.update(turn.id, {
+      leaseExpiresAt: Date.now() - 1,
+    })
+
+    const next = await open([() => text('recovered')], {}, { persistence })
+
+    expect(await next.session.settled('in-1')).toMatchObject({
+      outcome: 'completed',
+    })
+    expect(stopped.calls).toHaveLength(1)
+    expect(next.calls).toHaveLength(1)
+    expect(next.calls[0].reasoning).toBeUndefined()
+    expect(next.calls[0].promptCache).toEqual({
+      retention: 'short',
+      key: THREAD,
+    })
+    await first.host.close().catch(() => {})
+    await next.host.close()
+  })
+})
+
+describe('turn overrides: plugin adapter picker', () => {
+  it('gives the picker the turn, and the turn adapter wins over its pick', async () => {
+    type PickerTurn = Parameters<NonNullable<PluginContributions['adapter']>>[0]
+    const seen: Array<PickerTurn> = []
+    const picked = mockAdapter([() => text('picked')])
+    const turnModel = mockAdapter([() => text('turn')])
+    const picker = definePlugin({
+      name: 'test/picker',
+      setup: () => ({
+        adapter: (turn) => {
+          seen.push(turn)
+          return picked.adapter
+        },
+      }),
+    })
+    const { host, session, calls } = await open([], {
+      plugins: () => [picker],
+    })
+    const overrides = { adapter: turnModel.adapter }
+
+    const turn = session.prompt('go', { inputId: 'in-7', overrides })
+
+    expect(await turn).toEqual({ text: 'turn' })
+    expect(seen).toEqual([{ operationId: turn.id, inputId: 'in-7', overrides }])
+    expect(picked.calls).toHaveLength(0)
+    expect(calls).toHaveLength(0)
+    await host.close()
+  })
+})

From 598badac8f69336de817504250df9971240f9cad Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 18:36:21 +0200
Subject: [PATCH 193/286] test(e2e): check per-turn overrides on the wire

A harness session runs 3 prompts on a capturing fetch. Only turn 2 has overrides: another model, reasoning, and an extra tool. The spec checks that turn 2 uses them and that turns 1 and 3 use the defaults.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 testing/e2e/src/routeTree.gen.ts              |  21 +++
 .../src/routes/api.harness-turn-overrides.ts  | 124 ++++++++++++++++++
 .../e2e/tests/harness-turn-overrides.spec.ts  |  36 +++++
 3 files changed, 181 insertions(+)
 create mode 100644 testing/e2e/src/routes/api.harness-turn-overrides.ts
 create mode 100644 testing/e2e/tests/harness-turn-overrides.spec.ts

diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index 3b55e110c0..1b106f1216 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -105,6 +105,7 @@ import { Route as ApiLazyToolsWireRouteImport } from './routes/api.lazy-tools-wi
 import { Route as ApiJoinRunClientToolRouteImport } from './routes/api.join-run-client-tool'
 import { Route as ApiInterruptsTestRouteImport } from './routes/api.interrupts-test'
 import { Route as ApiImageRouteImport } from './routes/api.image'
+import { Route as ApiHarnessTurnOverridesRouteImport } from './routes/api.harness-turn-overrides'
 import { Route as ApiHarnessTestRouteImport } from './routes/api.harness-test'
 import { Route as ApiGenerationPersistenceServerRouteImport } from './routes/api.generation-persistence-server'
 import { Route as ApiGenerationPersistenceResumeRouteImport } from './routes/api.generation-persistence-resume'
@@ -638,6 +639,11 @@ const ApiImageRoute = ApiImageRouteImport.update({
   path: '/api/image',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiHarnessTurnOverridesRoute = ApiHarnessTurnOverridesRouteImport.update({
+  id: '/api/harness-turn-overrides',
+  path: '/api/harness-turn-overrides',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiHarnessTestRoute = ApiHarnessTestRouteImport.update({
   id: '/api/harness-test',
   path: '/api/harness-test',
@@ -873,6 +879,7 @@ export interface FileRoutesByFullPath {
   '/api/generation-persistence-resume': typeof ApiGenerationPersistenceResumeRoute
   '/api/generation-persistence-server': typeof ApiGenerationPersistenceServerRoute
   '/api/harness-test': typeof ApiHarnessTestRoute
+  '/api/harness-turn-overrides': typeof ApiHarnessTurnOverridesRoute
   '/api/image': typeof ApiImageRouteWithChildren
   '/api/interrupts-test': typeof ApiInterruptsTestRoute
   '/api/join-run-client-tool': typeof ApiJoinRunClientToolRoute
@@ -1004,6 +1011,7 @@ export interface FileRoutesByTo {
   '/api/generation-persistence-resume': typeof ApiGenerationPersistenceResumeRoute
   '/api/generation-persistence-server': typeof ApiGenerationPersistenceServerRoute
   '/api/harness-test': typeof ApiHarnessTestRoute
+  '/api/harness-turn-overrides': typeof ApiHarnessTurnOverridesRoute
   '/api/image': typeof ApiImageRouteWithChildren
   '/api/interrupts-test': typeof ApiInterruptsTestRoute
   '/api/join-run-client-tool': typeof ApiJoinRunClientToolRoute
@@ -1136,6 +1144,7 @@ export interface FileRoutesById {
   '/api/generation-persistence-resume': typeof ApiGenerationPersistenceResumeRoute
   '/api/generation-persistence-server': typeof ApiGenerationPersistenceServerRoute
   '/api/harness-test': typeof ApiHarnessTestRoute
+  '/api/harness-turn-overrides': typeof ApiHarnessTurnOverridesRoute
   '/api/image': typeof ApiImageRouteWithChildren
   '/api/interrupts-test': typeof ApiInterruptsTestRoute
   '/api/join-run-client-tool': typeof ApiJoinRunClientToolRoute
@@ -1269,6 +1278,7 @@ export interface FileRouteTypes {
     | '/api/generation-persistence-resume'
     | '/api/generation-persistence-server'
     | '/api/harness-test'
+    | '/api/harness-turn-overrides'
     | '/api/image'
     | '/api/interrupts-test'
     | '/api/join-run-client-tool'
@@ -1400,6 +1410,7 @@ export interface FileRouteTypes {
     | '/api/generation-persistence-resume'
     | '/api/generation-persistence-server'
     | '/api/harness-test'
+    | '/api/harness-turn-overrides'
     | '/api/image'
     | '/api/interrupts-test'
     | '/api/join-run-client-tool'
@@ -1531,6 +1542,7 @@ export interface FileRouteTypes {
     | '/api/generation-persistence-resume'
     | '/api/generation-persistence-server'
     | '/api/harness-test'
+    | '/api/harness-turn-overrides'
     | '/api/image'
     | '/api/interrupts-test'
     | '/api/join-run-client-tool'
@@ -1663,6 +1675,7 @@ export interface RootRouteChildren {
   ApiGenerationPersistenceResumeRoute: typeof ApiGenerationPersistenceResumeRoute
   ApiGenerationPersistenceServerRoute: typeof ApiGenerationPersistenceServerRoute
   ApiHarnessTestRoute: typeof ApiHarnessTestRoute
+  ApiHarnessTurnOverridesRoute: typeof ApiHarnessTurnOverridesRoute
   ApiImageRoute: typeof ApiImageRouteWithChildren
   ApiInterruptsTestRoute: typeof ApiInterruptsTestRoute
   ApiJoinRunClientToolRoute: typeof ApiJoinRunClientToolRoute
@@ -2405,6 +2418,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiImageRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/harness-turn-overrides': {
+      id: '/api/harness-turn-overrides'
+      path: '/api/harness-turn-overrides'
+      fullPath: '/api/harness-turn-overrides'
+      preLoaderRoute: typeof ApiHarnessTurnOverridesRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/harness-test': {
       id: '/api/harness-test'
       path: '/api/harness-test'
@@ -2757,6 +2777,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiGenerationPersistenceResumeRoute: ApiGenerationPersistenceResumeRoute,
   ApiGenerationPersistenceServerRoute: ApiGenerationPersistenceServerRoute,
   ApiHarnessTestRoute: ApiHarnessTestRoute,
+  ApiHarnessTurnOverridesRoute: ApiHarnessTurnOverridesRoute,
   ApiImageRoute: ApiImageRouteWithChildren,
   ApiInterruptsTestRoute: ApiInterruptsTestRoute,
   ApiJoinRunClientToolRoute: ApiJoinRunClientToolRoute,
diff --git a/testing/e2e/src/routes/api.harness-turn-overrides.ts b/testing/e2e/src/routes/api.harness-turn-overrides.ts
new file mode 100644
index 0000000000..450f7be283
--- /dev/null
+++ b/testing/e2e/src/routes/api.harness-turn-overrides.ts
@@ -0,0 +1,124 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { toolDefinition } from '@tanstack/ai'
+import { createAnthropicChat } from '@tanstack/ai-anthropic'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+
+/**
+ * Wire check for `session.prompt(message, { overrides })`.
+ *
+ * One session runs three turns. Turn 1 and turn 3 have no overrides. Turn 2
+ * sets another adapter, `reasoning`, and an extra tool. A custom `fetch`
+ * records each request body and answers with a canned stream, so no aimock
+ * fixture is needed. The route returns the model, the thinking field, and
+ * the tool names of each request.
+ */
+
+const DUMMY_KEY = 'sk-ant-e2e-test-dummy-key'
+
+const ANTHROPIC_REPLY = [
+  {
+    type: 'message_start',
+    message: {
+      id: 'msg_harness_turn_overrides',
+      type: 'message',
+      role: 'assistant',
+      content: [],
+      model: 'claude-sonnet-4-6',
+      stop_reason: null,
+      stop_sequence: null,
+      usage: { input_tokens: 5, output_tokens: 0 },
+    },
+  },
+  {
+    type: 'content_block_start',
+    index: 0,
+    content_block: { type: 'text', text: '' },
+  },
+  {
+    type: 'content_block_delta',
+    index: 0,
+    delta: { type: 'text_delta', text: 'ok' },
+  },
+  { type: 'content_block_stop', index: 0 },
+  {
+    type: 'message_delta',
+    delta: { stop_reason: 'end_turn', stop_sequence: null },
+    usage: { output_tokens: 1 },
+  },
+  { type: 'message_stop' },
+]
+
+/** The fields of an Anthropic Messages request body that the spec reads. */
+interface WireBody {
+  model: string
+  thinking?: unknown
+  tools?: Array<{ name: string }>
+}
+
+const getGuitars = toolDefinition({
+  name: 'get_guitars',
+  description: 'List the guitars in stock',
+}).server(async () => 'none')
+
+const getPrice = toolDefinition({
+  name: 'get_price',
+  description: 'Get the price of a guitar',
+}).server(async () => 'unknown')
+
+export const Route = createFileRoute('/api/harness-turn-overrides')({
+  server: {
+    handlers: {
+      POST: async () => {
+        const bodies: Array<WireBody> = []
+        const capturingFetch: typeof fetch = async (input, init) => {
+          bodies.push(await new Request(input, init).json())
+          const sse = ANTHROPIC_REPLY.map(
+            (event) => `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`,
+          ).join('')
+          return new Response(sse, {
+            headers: { 'Content-Type': 'text/event-stream' },
+          })
+        }
+
+        const host = createHarnessHost()
+        try {
+          const session = await host.open(
+            defineHarness({
+              name: 'e2e/harness-turn-overrides',
+              adapter: createAnthropicChat('claude-sonnet-4-6', DUMMY_KEY, {
+                fetch: capturingFetch,
+              }),
+              tools: [getGuitars],
+            }),
+            { threadId: 'e2e-turn-overrides' },
+          )
+          await session.prompt('[harness-turn-overrides] one')
+          await session.prompt('[harness-turn-overrides] two', {
+            overrides: {
+              adapter: createAnthropicChat('claude-opus-4-7', DUMMY_KEY, {
+                fetch: capturingFetch,
+              }),
+              reasoning: { level: 'high' },
+              tools: [getPrice],
+            },
+          })
+          await session.prompt('[harness-turn-overrides] three')
+        } catch (error) {
+          return Response.json({
+            error: error instanceof Error ? error.message : String(error),
+          })
+        } finally {
+          await host.close()
+        }
+
+        return Response.json({
+          requests: bodies.map((body) => ({
+            model: body.model,
+            thinking: body.thinking !== undefined,
+            tools: (body.tools ?? []).map((tool) => tool.name),
+          })),
+        })
+      },
+    },
+  },
+})
diff --git a/testing/e2e/tests/harness-turn-overrides.spec.ts b/testing/e2e/tests/harness-turn-overrides.spec.ts
new file mode 100644
index 0000000000..1746625262
--- /dev/null
+++ b/testing/e2e/tests/harness-turn-overrides.spec.ts
@@ -0,0 +1,36 @@
+import { test, expect } from './fixtures'
+
+interface WireRequest {
+  model: string
+  thinking: boolean
+  tools: Array<string>
+}
+
+const DEFAULT_TURN = {
+  model: 'claude-sonnet-4-6',
+  thinking: false,
+  tools: ['get_guitars'],
+}
+
+test.describe('harness: turn overrides on the wire', () => {
+  test('only the turn with overrides uses its adapter, reasoning, and tools', async ({
+    request,
+  }) => {
+    const res = await request.post('/api/harness-turn-overrides')
+    expect(res.ok()).toBe(true)
+    const result: { error?: string; requests: Array<WireRequest> } =
+      await res.json()
+    expect(result.error ?? null).toBeNull()
+
+    // One model call for each turn, in turn order.
+    expect(result.requests).toEqual([
+      DEFAULT_TURN,
+      {
+        model: 'claude-opus-4-7',
+        thinking: true,
+        tools: ['get_guitars', 'get_price'],
+      },
+      DEFAULT_TURN,
+    ])
+  })
+})

From 328ee9214dc05a98d7e79b824dcbcf0897c7326d Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 18:40:35 +0200
Subject: [PATCH 194/286] fix(ai-harness): take the same reasoning option as
 chat()

TurnOverrides.reasoning and HarnessConfig.reasoning now take ReasoningOption, as chat({ reasoning }) does: a level such as 'high', or { level, summary?, budgetTokens? }. ReasoningRequest is the normalized adapter type and needed summary.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-harness/src/define.ts                |  4 ++--
 packages/ai-harness/src/types.ts                 |  4 ++--
 packages/ai-harness/tests/turn-overrides.test.ts | 16 ++++++++++++++++
 3 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/packages/ai-harness/src/define.ts b/packages/ai-harness/src/define.ts
index 09477f75de..05a452b8a3 100644
--- a/packages/ai-harness/src/define.ts
+++ b/packages/ai-harness/src/define.ts
@@ -7,7 +7,7 @@ import type {
   KeyedAdapter,
   ModelMessage,
   PromptCacheOptions,
-  ReasoningRequest,
+  ReasoningOption,
   SubagentRouterPick,
   SubagentsBag,
   SystemPrompt,
@@ -137,7 +137,7 @@ export interface HarnessConfig<
    * `TextOptions`. Not set: no reasoning is sent, and the provider default
    * applies. `overrides.reasoning` of a turn replaces it.
    */
-  reasoning?: ReasoningRequest
+  reasoning?: ReasoningOption
   interrupts?: ReadonlyArray<InterruptDefinition<any, any, any, any>>
   /** Runtime context passed to middleware hooks and server tools. */
   context?: unknown
diff --git a/packages/ai-harness/src/types.ts b/packages/ai-harness/src/types.ts
index 739934a210..9b6c89e9f6 100644
--- a/packages/ai-harness/src/types.ts
+++ b/packages/ai-harness/src/types.ts
@@ -5,7 +5,7 @@ import type {
   Interrupt,
   KeyedAdapter,
   PromptCacheOptions,
-  ReasoningRequest,
+  ReasoningOption,
   RunAgentResumeItem,
   StreamChunk,
 } from '@tanstack/ai'
@@ -34,7 +34,7 @@ export interface TurnOverrides {
   /** Replaces the harness adapter and every plugin pick for this turn. */
   adapter?: AnyTextAdapter | KeyedAdapter<AnyTextAdapter>
   /** Replaces `HarnessConfig.reasoning` for this turn. */
-  reasoning?: ReasoningRequest
+  reasoning?: ReasoningOption
   /** Replaces the session and harness values for this turn, field by field. */
   promptCache?: PromptCacheOptions
   /**
diff --git a/packages/ai-harness/tests/turn-overrides.test.ts b/packages/ai-harness/tests/turn-overrides.test.ts
index e877d1b426..3bd652b7d0 100644
--- a/packages/ai-harness/tests/turn-overrides.test.ts
+++ b/packages/ai-harness/tests/turn-overrides.test.ts
@@ -197,6 +197,22 @@ describe('turn overrides: reasoning and prompt cache', () => {
     await host.close()
   })
 
+  it('takes a reasoning level alone, the same as chat()', async () => {
+    const { host, session, calls } = await open(
+      [() => text('a'), () => text('b')],
+      { reasoning: 'low' },
+    )
+
+    await session.prompt('one')
+    await session.prompt('two', { overrides: { reasoning: 'high' } })
+
+    expect(calls.map((call) => call.reasoning)).toEqual([
+      { level: 'low', summary: true },
+      { level: 'high', summary: true },
+    ])
+    await host.close()
+  })
+
   it('sends HarnessConfig.reasoning on every turn, and a turn value replaces it', async () => {
     const { host, session, calls } = await open(
       [() => text('a'), () => text('b'), () => text('c')],

From ceea3a43c6f90554eb3e6e27b0926ba3c0df38c9 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 18:40:37 +0200
Subject: [PATCH 195/286] docs: per-turn overrides, harness reasoning, and the
 cache in onConfig

turn-control gets a section on overrides for one prompt. The harness overview shows HarnessConfig.reasoning. Plugins shows the adapter picker and its turn argument. Middleware shows reasoning and promptCache in onConfig.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 docs/advanced/middleware.md     | 24 +++++++++++-
 docs/advanced/prompt-caching.md |  4 +-
 docs/config.json                |  2 +-
 docs/harness/overview.md        | 20 ++++++++++
 docs/harness/plugins.md         | 37 ++++++++++++++++++
 docs/harness/turn-control.md    | 68 ++++++++++++++++++++++++++++++++-
 6 files changed, 151 insertions(+), 4 deletions(-)

diff --git a/docs/advanced/middleware.md b/docs/advanced/middleware.md
index 8c0ecb2647..e352ea1d06 100644
--- a/docs/advanced/middleware.md
+++ b/docs/advanced/middleware.md
@@ -163,6 +163,8 @@ const dynamicTemperature: ChatMiddleware = {
 | `tools` | `Tool[]` | Available tools |
 | `metadata` | `Record<string, unknown>` | Request metadata |
 | `modelOptions` | `Record<string, unknown>` | Provider-native options — this is where sampling params (`temperature`, `top_p` / `topP`, the provider's `max*Tokens` key) now live, alongside every other model-specific knob. See [Moving Sampling Options into modelOptions](../migration/sampling-options-to-model-options). |
+| `reasoning` | `ReasoningRequest \| undefined` | How hard the model thinks at this call. See [Reasoning](../chat/reasoning#change-the-level-in-middleware). |
+| `promptCache` | `ResolvedPromptCache \| undefined` | The prompt cache of this call: its `retention` and `key`. See [Change the prompt cache of a call](#change-the-prompt-cache-of-a-call). |
 
 When multiple middleware define `onConfig`, the config is **piped** through them in order — each receives the merged config from the previous middleware.
 
@@ -170,6 +172,26 @@ Return `providerMessages` when a transform must affect only the model call. For
 compatibility, returning `messages` also updates provider input unless the same
 result sets `providerMessages` explicitly.
 
+#### Change the prompt cache of a call
+
+A slow tool, such as a build or a test suite, can pause an agent run for more than 5 minutes. The short Claude cache ends 5 minutes after its last read. Return `promptCache` from `onConfig` to change the cache of the next model call, the same as `reasoning`:
+
+```typescript
+import { type ChatMiddleware } from "@tanstack/ai";
+
+const longCacheAfterTools: ChatMiddleware = {
+  name: "long-cache-after-tools",
+  onConfig: (ctx, config) => {
+    if (ctx.phase !== "beforeModel" || ctx.iteration === 0) return;
+    return { promptCache: { ...config.promptCache, retention: "long" } };
+  },
+};
+```
+
+- `config.promptCache` is the current value, with its `retention` and its `key`.
+- The returned value goes to the adapter on the next model call. It stays for the later calls until a middleware returns another value.
+- For the retention values and their cost, see [Prompt Caching](./prompt-caching#pick-the-retention).
+
 ### onStructuredOutputConfig
 
 Called once at the start of the final structured-output adapter call — only when `chat()` was invoked with `outputSchema` **and** `supportsCombinedToolsAndSchema()` does not return `true` for the current model/options. Pipes through middleware in order, like `onConfig`, but with access to the **JSON Schema** being sent to the provider. Use this hook when you need to transform the schema (e.g., inject `$defs`, strip vendor-incompatible keywords) or apply structured-output-specific behavior (e.g., suppress system prompts on the final call).
@@ -510,7 +532,7 @@ capability, then return those fields from `onConfig` when
 | --- | --- |
 | `onInterruptBoundary` | Nothing. It can only pause. |
 | `onInterruptResolution` | Pending-tool policy (`toolResume`) |
-| `onConfig` | `messages`, `systemPrompts`, `tools`, `modelOptions`, `metadata` |
+| `onConfig` | `messages`, `systemPrompts`, `tools`, `modelOptions`, `metadata`, `reasoning`, `promptCache` |
 
 The full resume order, plus an example that writes a user note into the
 system prompt, is in [Apply Answers](../interrupts/apply-answers).
diff --git a/docs/advanced/prompt-caching.md b/docs/advanced/prompt-caching.md
index 2bfb7e585f..ccd1358662 100644
--- a/docs/advanced/prompt-caching.md
+++ b/docs/advanced/prompt-caching.md
@@ -82,7 +82,9 @@ const stream = chat({
 
 Both fields are optional. Without `retention`, the retention is `'short'`. The types are exported from `@tanstack/ai`: `PromptCacheRetention`, `PromptCacheOptions`, and `ResolvedPromptCache`.
 
-In a harness, you set `promptCache` one time for every session. See [Build your first harness](../harness/overview#prompt-caching).
+In a harness, you set `promptCache` one time for every session. See [Build your first harness](../harness/overview#prompt-caching). To change it for one prompt of a session, see [Give one prompt its own settings](../harness/turn-control#give-one-prompt-its-own-settings).
+
+A middleware can change the retention or the key of one model call. See [Change the prompt cache of a call](./middleware#change-the-prompt-cache-of-a-call).
 
 ## When to turn it off or keep it longer
 
diff --git a/docs/config.json b/docs/config.json
index 3af4e9ad47..94d4aa1e81 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -307,7 +307,7 @@
           "label": "Middleware",
           "to": "advanced/middleware",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-09-30"
+          "updatedAt": "2026-10-02"
         },
         {
           "label": "Built-in Middleware",
diff --git a/docs/harness/overview.md b/docs/harness/overview.md
index 8e7c706ff4..e6064df3ec 100644
--- a/docs/harness/overview.md
+++ b/docs/harness/overview.md
@@ -197,6 +197,26 @@ const support = await host.open(assistant, {
 
 If the `threadId` already has a live session, `host.open` returns that session with its first `promptCache` value. Agents in the session use the same retention. The `/usage` command of the [`usage()` plugin](./coding-agent#what-each-plugin-adds) shows cache reads and writes. For the options and the cost, see [Prompt Caching](../advanced/prompt-caching).
 
+To change it for one prompt, pass `overrides.promptCache`. See [Give one prompt its own settings](./turn-control#give-one-prompt-its-own-settings).
+
+## Set a reasoning level
+
+A harness sends no reasoning level by default, so the main model thinks at the default of its provider. To set a level for every turn, set `reasoning` on the harness:
+
+```ts group=harness-first
+export const careful = defineHarness({
+  name: 'acme/careful',
+  adapter: openaiText('gpt-6.1-sol'),
+  reasoning: 'medium',
+})
+```
+
+- `level`: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. A model that does not have the level gets the nearest level that it has.
+- `summary`: `true` streams the thinking text. `false` keeps it out of the stream.
+- `budgetTokens`: optional. A thinking token budget, for models that think with a budget.
+
+For the levels of each model, see [Reasoning](../chat/reasoning). To use another level for one prompt, pass `overrides.reasoning`. See [Give one prompt its own settings](./turn-control#give-one-prompt-its-own-settings).
+
 ## What you have now
 
 - A harness defined once, with the same options as `chat()`.
diff --git a/docs/harness/plugins.md b/docs/harness/plugins.md
index 6dec355cfa..3ab18e0ac2 100644
--- a/docs/harness/plugins.md
+++ b/docs/harness/plugins.md
@@ -34,6 +34,7 @@ Add it with `plugins: () => [today]` in `defineHarness`. `setup` runs once per s
 - `generationMiddleware`: middleware for the activities agents call.
 - `agents`: agents added to `session.agents`. `routing.router` can send a turn to them too, see [Route a turn to an agent](./subagents#route-a-turn-to-an-agent).
 - `subagents`: agents the model can call as tools. They are also added to `session.agents`. [Delegate to coding agents](./coding-agents) uses them.
+- `adapter`: a picker for the model of each turn, see [Pick the model of a turn](#pick-the-model-of-a-turn).
 - `commands`: user actions, see below.
 - `config`: session settings, see below.
 - `contribute`: items for another plugin's extension point.
@@ -186,6 +187,41 @@ export const usageByAgent = definePlugin({
 - `ctx.subagentRunId` is different for each run of an agent. For a nested child, `ctx.parentSubagentRunId` is the id of the child that started it.
 - Each model call goes to `onUsage` one time, in the run that made the call. The lead turn does not count the usage of a child again.
 
+## Pick the model of a turn
+
+Some turns need another model: a hard plan needs a strong model, and a short reply does not. Return an `adapter` picker from `setup`. The session calls it when each turn starts, with that turn:
+
+```ts group=harness-plugins
+import { anthropicText } from '@tanstack/ai-anthropic'
+
+export const strongForHardTurns = definePlugin({
+  name: 'acme/strong-for-hard-turns',
+  setup: () => ({
+    adapter: (turn) =>
+      turn.overrides?.reasoning === 'high'
+        ? anthropicText('claude-opus-5-5')
+        : undefined,
+  }),
+})
+```
+
+A prompt with `overrides: { reasoning: 'high' }` now runs on Claude Opus. Other turns keep the harness adapter.
+
+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.
+- `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:
+
+- `undefined` keeps the harness adapter.
+- If more than one plugin returns an adapter, the last plugin wins.
+- The `overrides.adapter` of the turn wins over every pick.
+- A keyed adapter gets the key of the user. See [Connect model providers](./provider-keys).
+
+If the picker does not need the turn, it can take no parameter.
+
 ## Let plugins work together
 
 Three ways, from simple to loose:
@@ -240,6 +276,7 @@ Set `lifetime: 'run'` to set a plugin up again for each turn.
 
 - A plugin that adds tools, prompts, commands, settings, and state to any harness.
 - Middleware that sees every model call, in the lead turn and in every agent.
+- A picker that chooses the model of each turn.
 - Plugins that share services, lists, and events without knowing each other.
 
 Next: see the [first-party plugins](./coding-agent) that turn a harness into a coding agent.
diff --git a/docs/harness/turn-control.md b/docs/harness/turn-control.md
index 27cb1fa3fc..dced6edd64 100644
--- a/docs/harness/turn-control.md
+++ b/docs/harness/turn-control.md
@@ -2,7 +2,7 @@
 title: Control how a turn ends
 id: harness-turn-control
 order: 4
-description: "Send the model back to work when it stops too soon, retry model errors, and choose which waiting messages join a running turn."
+description: "Send the model back to work when it stops too soon, retry model errors, choose which waiting messages join a running turn, and give one prompt its own model and tools."
 keywords:
   - tanstack ai
   - harness
@@ -12,10 +12,14 @@ keywords:
   - canJoin
   - onJoin
   - steer
+  - overrides
+  - TurnOverrides
 ---
 
 A model can stop before the job is done: it writes a nice answer and forgets to call `post_message`. A provider can answer 503 in the middle of a turn. A user can send three messages while the agent works, and one of them must not join. The `turn` options of the harness give you a hook for each case.
 
+One job can also need its own model or tools. Pass `overrides` to the prompt to [give it its own settings](#give-one-prompt-its-own-settings).
+
 ## Send the model back to work
 
 The `beforeFinish` hook runs when the model stops calling tools. Check the transcript. If the job is not done, return a message. The model runs again in the same operation.
@@ -161,8 +165,70 @@ const selective = defineHarness({
 
 Tools or system prompts that a plugin or a middleware adds during a turn keep the prompt cache on models with a mid-conversation channel. See [Mid-conversation changes in a harness](../advanced/mid-conversation-changes#in-a-harness).
 
+## Give one prompt its own settings
+
+Most prompts are fine with the harness settings. One job can need more: a stronger model for a review, more reasoning, or a tool that only this job uses. Pass `overrides` to `session.prompt` or `session.followUp`:
+
+```ts group=harness-turn-control
+import { toolDefinition } from '@tanstack/ai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+import { createHarnessHost } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+
+const readDiff = toolDefinition({
+  name: 'read_diff',
+  description: 'Read the diff of the open pull request',
+}).server(async () => 'diff --git a/src/cart.ts b/src/cart.ts')
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+const session = await host.open(resilient, { threadId: 'thread-1' })
+
+const review = await session.prompt('Review the open pull request.', {
+  overrides: {
+    adapter: anthropicText('claude-opus-5-5'),
+    reasoning: 'high',
+    tools: [readDiff],
+  },
+})
+console.log(review.text)
+```
+
+The overrides apply to this turn only. The next prompt without `overrides` uses the harness settings again. The type is `TurnOverrides`, from `@tanstack/ai-harness`.
+
+| Field | What it does in this turn |
+|---|---|
+| `adapter` | Replaces the harness adapter and every plugin pick. A keyed adapter uses the key of the user. |
+| `reasoning` | Replaces the `reasoning` of the harness. |
+| `promptCache` | Replaces the session and harness values, field by field. `{ key: 'review' }` keeps the session retention. |
+| `tools` | Adds tools to the tools of the harness and the plugins. |
+
+Every model call of the turn uses the overrides:
+
+- each step of the tool loop
+- each `onModelError` retry
+- each `beforeFinish` cycle
+- the main model after a [`routing`](./subagents#route-a-turn-to-an-agent) handoff
+- the extra model call for steer messages that arrive at the final answer
+
+### Tools for one turn
+
+- A tool name that the turn already has fails the turn, the same as two tools with one name.
+- A [durable tool](./durable-tools) gets `step` and `append` on a durable host.
+- A middleware `onConfig` that returns a new tool list does not drop these tools. The harness adds them back.
+
+### Where the overrides live
+
+The session keeps the overrides in memory only. The session log does not store them.
+
+- A queued prompt keeps its overrides until its turn runs.
+- A steer that joins a running turn uses the overrides of that turn. The session ignores the overrides of the steer.
+- A `prompt(text, { busy: 'steer', overrides })` that does not join runs as its own turn, with its own overrides.
+- After a restart, recovery runs an unfinished turn with the harness settings.
+- A second prompt with the same `inputId` and message is a duplicate, also when its overrides are different.
+
 ## What you have now
 
 - A turn that goes back to work until the job is done, with a limit.
 - Model errors that retry with a backoff, and a policy of your own for a context overflow.
 - Waiting messages that join a turn only when you allow it.
+- A prompt that runs with its own model, reasoning, prompt cache, and tools.

From a8b8d2dc61c6a4df450a300fad8a85f17eb946e2 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Fri, 2 Oct 2026 18:52:17 +0200
Subject: [PATCH 196/286] chore: add the turn overrides changeset

Also formats the E2E route.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/turn-overrides.md                        | 13 +++++++++++++
 .../e2e/src/routes/api.harness-turn-overrides.ts    |  3 ++-
 2 files changed, 15 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/turn-overrides.md

diff --git a/.changeset/turn-overrides.md b/.changeset/turn-overrides.md
new file mode 100644
index 0000000000..ad608c1ff5
--- /dev/null
+++ b/.changeset/turn-overrides.md
@@ -0,0 +1,13 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-harness': minor
+---
+
+One prompt can now run with its own settings.
+
+- `session.prompt(message, { overrides })` and `session.followUp(message, { overrides })` take `TurnOverrides`: an `adapter`, `reasoning`, a `promptCache`, and extra `tools` for that one turn. They apply to every model call of the turn: the tool loop, `onModelError` retries, `beforeFinish` cycles, and joins. The next turn uses the defaults again.
+- The overrides are kept in memory only. A queued turn keeps them, a steer that joins a turn uses that turn's overrides, and a turn that recovery runs again after a restart uses the defaults.
+- A middleware that rebuilds the tools in `onConfig` keeps the override tools. A durable tool among them gets `step` and `append`.
+- `HarnessConfig.reasoning` sets the default reasoning of every turn.
+- The plugin `adapter` picker now gets the turn: `{ operationId, inputId, overrides }`. A picker with no parameter still works.
+- `ChatMiddlewareConfig` has `promptCache`, next to `reasoning`. `onConfig` can change the prompt cache of the next model call.
diff --git a/testing/e2e/src/routes/api.harness-turn-overrides.ts b/testing/e2e/src/routes/api.harness-turn-overrides.ts
index 450f7be283..3b52398042 100644
--- a/testing/e2e/src/routes/api.harness-turn-overrides.ts
+++ b/testing/e2e/src/routes/api.harness-turn-overrides.ts
@@ -73,7 +73,8 @@ export const Route = createFileRoute('/api/harness-turn-overrides')({
         const capturingFetch: typeof fetch = async (input, init) => {
           bodies.push(await new Request(input, init).json())
           const sse = ANTHROPIC_REPLY.map(
-            (event) => `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`,
+            (event) =>
+              `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`,
           ).join('')
           return new Response(sse, {
             headers: { 'Content-Type': 'text/event-stream' },

From 75c87cdbb53e1b34db72c1f3dd19b5dfe499aff2 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 3 Oct 2026 17:34:57 +0200
Subject: [PATCH 197/286] feat(ai-mcp): fill missing schema fields and freeze
 tool annotations

A discovered tool schema without properties now gets properties: {}. A schema without type gets type: 'object'. A full schema does not change. metadata.mcp.annotations is now a frozen copy of the server annotations, on both tools() paths.
---
 packages/ai-mcp/src/tools.ts         | 23 +++++---
 packages/ai-mcp/src/types.ts         |  4 +-
 packages/ai-mcp/tests/client.test.ts | 20 +++++++
 packages/ai-mcp/tests/tools.test.ts  | 84 +++++++++++++++++++++++++++-
 4 files changed, 120 insertions(+), 11 deletions(-)

diff --git a/packages/ai-mcp/src/tools.ts b/packages/ai-mcp/src/tools.ts
index a1cd7f1757..ab8edf401e 100644
--- a/packages/ai-mcp/src/tools.ts
+++ b/packages/ai-mcp/src/tools.ts
@@ -55,9 +55,10 @@ function toolDisplayTitle(def: McpToolDef): string {
  * Shared by auto-discovery (`toServerTools`) and the explicit `tools(defs)`
  * path in `client.ts` so the two cannot drift.
  *
- * `annotations` is the server's own object, forwarded verbatim. Per the MCP
- * spec its fields (including `title`) are **hints** — a host may use them for
- * display or to shape an approval UI, but never as a security boundary.
+ * `annotations` is a frozen copy of the server's object. A host cannot change
+ * the server's data through it. Per the MCP spec, its fields (including
+ * `title`) are hints. A host may use them for display or for an approval UI,
+ * but never as a security boundary.
  *
  * Fields the server didn't declare are OMITTED rather than set to `undefined`:
  * the explicit path merges this over any `mcp` block the caller already put on
@@ -74,7 +75,9 @@ export function toolMcpMetadata(
     serverId,
     title: toolDisplayTitle(def),
     ...(uiResourceUri !== undefined ? { uiResourceUri } : {}),
-    ...(annotations !== undefined ? { annotations } : {}),
+    ...(annotations !== undefined
+      ? { annotations: Object.freeze({ ...annotations }) }
+      : {}),
   }
 }
 
@@ -699,14 +702,18 @@ export function toServerTools(
     .filter((def) => !requiresTaskExecution(def) || supportsTasks)
     .map((def) => {
       const name = options.prefix ? `${options.prefix}_${def.name}` : def.name
+      // A server can leave out `type` or `properties`. Fill both, because
+      // some providers reject an object schema without `properties`.
+      const schema: Partial<McpToolDef['inputSchema']> = def.inputSchema ?? {}
       const tool: McpServerTool = {
         __toolSide: 'server',
         name,
         description: def.description ?? '',
-        inputSchema: (def.inputSchema as any) ?? {
-          type: 'object',
-          properties: {},
-        },
+        inputSchema: {
+          ...schema,
+          type: schema.type ?? 'object',
+          properties: schema.properties ?? {},
+        } as any,
         ...(def.outputSchema ? { outputSchema: def.outputSchema as any } : {}),
         ...(options.lazy ? { lazy: true } : {}),
         metadata: {
diff --git a/packages/ai-mcp/src/types.ts b/packages/ai-mcp/src/types.ts
index 447260d0d4..66980c9f15 100644
--- a/packages/ai-mcp/src/types.ts
+++ b/packages/ai-mcp/src/types.ts
@@ -41,8 +41,8 @@ export interface McpToolMetadata {
   /** MCP Apps widget link, from the tool def's `_meta.ui.resourceUri`. */
   uiResourceUri?: string
   /**
-   * The server's `annotations` for this tool, forwarded verbatim (absent when
-   * the server declares none). All fields are **hints** — useful for display
+   * A frozen copy of the server's `annotations` for this tool (absent when
+   * the server declares none). All fields are **hints**: useful for display
    * and for shaping an approval UI, never a security boundary.
    */
   annotations?: ToolAnnotations
diff --git a/packages/ai-mcp/tests/client.test.ts b/packages/ai-mcp/tests/client.test.ts
index 14b6cbe957..79bec850d4 100644
--- a/packages/ai-mcp/tests/client.test.ts
+++ b/packages/ai-mcp/tests/client.test.ts
@@ -160,6 +160,26 @@ describe('createMCPClient', () => {
     expect(mcp.title).toBe('Weather Lookup')
   })
 
+  it('freezes a copy of the server annotations on bound definitions', async () => {
+    const { clientTransport } = await makeServerWithAnnotatedTool()
+    await using client = await createMCPClientFromTransport(clientTransport)
+    const getWeather = toolDefinition({
+      name: 'get_weather',
+      description: 'Get weather for a city',
+      inputSchema: z.object({ city: z.string() }),
+    })
+    const tools = await client.tools([getWeather])
+    const mcp = tools[0].metadata.mcp
+    expect(mcp.annotations).toEqual({
+      title: 'Legacy Weather Title',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    })
+    expect(Object.isFrozen(mcp.annotations)).toBe(true)
+  })
+
   it('discovers and executes task-required tools', async () => {
     const { clientTransport } = await makeServerWithTaskRequiredTool()
     await using client = await createMCPClientFromTransport(clientTransport)
diff --git a/packages/ai-mcp/tests/tools.test.ts b/packages/ai-mcp/tests/tools.test.ts
index 5d0a75df62..3c68f7be12 100644
--- a/packages/ai-mcp/tests/tools.test.ts
+++ b/packages/ai-mcp/tests/tools.test.ts
@@ -41,7 +41,11 @@ function mcpToolDef(def: {
   name: string
   title?: string
   description?: string
-  inputSchema?: { type: 'object'; properties?: Record<string, unknown> }
+  inputSchema?: {
+    type?: 'object'
+    properties?: Record<string, unknown>
+    required?: Array<string>
+  }
   execution?: { taskSupport?: 'optional' | 'required' | 'forbidden' }
   annotations?: {
     title?: string
@@ -682,6 +686,84 @@ describe('toServerTools — annotations + title', () => {
     expect(tool.name).toBe('wx_get_weather')
     expect(tool.metadata.mcp.title).toBe('Weather Lookup')
   })
+
+  it('gives a frozen copy of the title and all 5 annotation fields', () => {
+    const annotations = {
+      title: 'Weather Lookup',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    }
+    const def = mcpToolDef({ name: 'get_weather', annotations })
+    const [tool] = toServerTools(fakeMcpClient(vi.fn()), [def], {})
+    const mcp = tool!.metadata.mcp
+    expect(mcp.title).toBe('Weather Lookup')
+    expect(mcp.annotations).toStrictEqual({
+      title: 'Weather Lookup',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    })
+    expect(Object.isFrozen(mcp.annotations)).toBe(true)
+    // A copy: the server's own object stays as it was.
+    expect(mcp.annotations).not.toBe(def.annotations)
+    expect(Object.isFrozen(def.annotations)).toBe(false)
+  })
+})
+
+describe('toServerTools — input schema defaults', () => {
+  it('adds properties: {} to a schema without properties', () => {
+    const [tool] = toServerTools(
+      fakeMcpClient(vi.fn()),
+      [mcpToolDef({ name: 'ping', inputSchema: { type: 'object' } })],
+      {},
+    )
+    expect(tool!.inputSchema).toEqual({ type: 'object', properties: {} })
+  })
+
+  it("adds type: 'object' to a schema without type and keeps its other keys", () => {
+    const [tool] = toServerTools(
+      fakeMcpClient(vi.fn()),
+      [
+        mcpToolDef({
+          name: 'search',
+          inputSchema: {
+            properties: { query: { type: 'string' } },
+            required: ['query'],
+          },
+        }),
+      ],
+      {},
+    )
+    expect(tool!.inputSchema).toEqual({
+      type: 'object',
+      properties: { query: { type: 'string' } },
+      required: ['query'],
+    })
+  })
+
+  it('gives a tool without an input schema an empty object schema', () => {
+    const def = mcpToolDef({ name: 'bare' })
+    Reflect.deleteProperty(def, 'inputSchema')
+    const [tool] = toServerTools(fakeMcpClient(vi.fn()), [def], {})
+    expect(tool!.inputSchema).toEqual({ type: 'object', properties: {} })
+  })
+
+  it('keeps a full schema as the server sent it', () => {
+    const inputSchema = {
+      type: 'object' as const,
+      properties: { city: { type: 'string' } },
+      required: ['city'],
+    }
+    const [tool] = toServerTools(
+      fakeMcpClient(vi.fn()),
+      [mcpToolDef({ name: 'get_weather', inputSchema })],
+      {},
+    )
+    expect(tool!.inputSchema).toEqual(inputSchema)
+  })
 })
 
 describe('toServerTools', () => {

From 347f692878d71ff139373a3b4599a073318e7fd8 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 3 Oct 2026 17:46:04 +0200
Subject: [PATCH 198/286] feat(ai-mcp): add toolName to set the MCP tool names
 the model sees

toolName(tool) sets the name of each tool on both tools() paths. It wins over prefix. metadata.mcp.serverToolName keeps the server name, so callTool and MCP Apps widget calls still reach the tool. The duplicate check runs on the final names. The pool, mcpConnector, getInfo, McpServerDescriptor, and the MCP Apps call handler forward the option.
---
 packages/ai-mcp/src/apps/call-handler.ts      | 11 +++-
 packages/ai-mcp/src/apps/session-store.ts     |  2 +
 packages/ai-mcp/src/client.ts                 | 31 +++++++---
 packages/ai-mcp/src/connector.ts              |  7 +++
 packages/ai-mcp/src/pool.ts                   |  2 +
 packages/ai-mcp/src/tools.ts                  |  6 +-
 packages/ai-mcp/src/types.ts                  | 18 ++++++
 .../ai-mcp/tests/apps/call-handler.test.ts    | 30 ++++++++++
 packages/ai-mcp/tests/client.test.ts          | 57 +++++++++++++++++++
 packages/ai-mcp/tests/connector-edges.test.ts | 27 +++++++++
 packages/ai-mcp/tests/pool.test.ts            | 30 ++++++++++
 packages/ai-mcp/tests/tools.test.ts           | 32 +++++++++++
 12 files changed, 241 insertions(+), 12 deletions(-)

diff --git a/packages/ai-mcp/src/apps/call-handler.ts b/packages/ai-mcp/src/apps/call-handler.ts
index 9121831a88..f18420c564 100644
--- a/packages/ai-mcp/src/apps/call-handler.ts
+++ b/packages/ai-mcp/src/apps/call-handler.ts
@@ -130,6 +130,7 @@ function buildRegistry(clients: McpAppClientsInput): AppRegistry {
     clientOptions?: McpServerDescriptor['clientOptions']
     toolFilter?: McpServerDescriptor['toolFilter']
     needsApproval?: McpServerDescriptor['needsApproval']
+    toolName?: McpServerDescriptor['toolName']
   }) => {
     const descriptor: McpServerDescriptor = {
       transport: info.transport,
@@ -137,6 +138,7 @@ function buildRegistry(clients: McpAppClientsInput): AppRegistry {
       ...(info.clientOptions ? { clientOptions: info.clientOptions } : {}),
       ...(info.toolFilter ? { toolFilter: info.toolFilter } : {}),
       ...(info.needsApproval ? { needsApproval: info.needsApproval } : {}),
+      ...(info.toolName ? { toolName: info.toolName } : {}),
     }
     total += 1
     const key = info.prefix
@@ -239,12 +241,14 @@ export function createMcpAppCallHandler(opts: McpAppCallHandlerOptions) {
     }
 
     // A persistent store cannot serialize a function, so a stored descriptor
-    // can come back without `toolFilter` or `needsApproval`. Fall back to the
-    // policy of the same server in `clients`, or a widget could call a tool the
-    // model cannot see, or run one the model can run only after approval.
+    // can come back without `toolFilter`, `needsApproval`, or `toolName`. Fall
+    // back to the options of the same server in `clients`, or a widget could
+    // call a tool the model cannot see, or run one the model can run only
+    // after approval.
     const toolFilter = descriptor.toolFilter ?? fromRegistry?.toolFilter
     const needsApproval =
       descriptor.needsApproval ?? fromRegistry?.needsApproval
+    const toolName = descriptor.toolName ?? fromRegistry?.toolName
     const client = await createMCPClient({
       transport: descriptor.transport,
       prefix: descriptor.prefix,
@@ -253,6 +257,7 @@ export function createMcpAppCallHandler(opts: McpAppCallHandlerOptions) {
         : {}),
       ...(toolFilter ? { toolFilter } : {}),
       ...(needsApproval ? { needsApproval } : {}),
+      ...(toolName ? { toolName } : {}),
     })
 
     try {
diff --git a/packages/ai-mcp/src/apps/session-store.ts b/packages/ai-mcp/src/apps/session-store.ts
index e25469a35d..2001fe3322 100644
--- a/packages/ai-mcp/src/apps/session-store.ts
+++ b/packages/ai-mcp/src/apps/session-store.ts
@@ -20,6 +20,8 @@ export interface McpServerDescriptor {
   toolFilter?: MCPClientOptions['toolFilter']
   /** Carried so a widget cannot run a tool that the model can run only after approval. */
   needsApproval?: MCPClientOptions['needsApproval']
+  /** Carried so a reconnect names the tools the same way as for the model. */
+  toolName?: MCPClientOptions['toolName']
 }
 
 export interface McpSessionStore {
diff --git a/packages/ai-mcp/src/client.ts b/packages/ai-mcp/src/client.ts
index 5b8362ce2c..22bb057fcd 100644
--- a/packages/ai-mcp/src/client.ts
+++ b/packages/ai-mcp/src/client.ts
@@ -56,7 +56,10 @@ export type TypedCallToolResult<TOutput> = unknown extends TOutput
   ? CallToolResult
   : Omit<CallToolResult, 'structuredContent'> & { structuredContent?: TOutput }
 
-type ToolPolicy = Pick<MCPClientOptions, 'toolFilter' | 'needsApproval'>
+type ToolPolicy = Pick<
+  MCPClientOptions,
+  'toolFilter' | 'needsApproval' | 'toolName'
+>
 
 export interface MCPClient<
   TServer extends ServerDescriptor = AutomaticDescriptor,
@@ -74,9 +77,9 @@ export interface MCPClient<
     (options?: ToolsOptions): Promise<DescriptorTools<TServer>>
     /**
      * Explicit: bind these TanStack toolDefinitions to the server (typed +
-     * validated, allowlist). Note: when the client has a `prefix`, the
-     * runtime tool name is `${prefix}_${def.name}` while the static `TName`
-     * stays the unprefixed definition name.
+     * validated, allowlist). Note: the runtime tool name is `toolName(tool)`
+     * when the client sets `toolName`, else `${prefix}_${def.name}` with a
+     * `prefix`. The static `TName` stays the definition name.
      */
     <const TDefs extends ReadonlyArray<AnyToolDefinition>>(
       defs: TDefs,
@@ -143,6 +146,7 @@ export interface MCPClient<
     clientOptions?: ClientOptions
     toolFilter?: MCPClientOptions['toolFilter']
     needsApproval?: MCPClientOptions['needsApproval']
+    toolName?: MCPClientOptions['toolName']
   }
   close: () => Promise<void>
   [Symbol.asyncDispose]: () => Promise<void>
@@ -208,14 +212,16 @@ class MCPClientImpl<
     clientOptions?: ClientOptions
     toolFilter?: MCPClientOptions['toolFilter']
     needsApproval?: MCPClientOptions['needsApproval']
+    toolName?: MCPClientOptions['toolName']
   } {
-    const { toolFilter, needsApproval } = this.#policy
+    const { toolFilter, needsApproval, toolName } = this.#policy
     return {
       transport: this.#transport,
       prefix: this.prefix,
       ...(this.#clientOptions ? { clientOptions: this.#clientOptions } : {}),
       ...(toolFilter ? { toolFilter } : {}),
       ...(needsApproval ? { needsApproval } : {}),
+      ...(toolName ? { toolName } : {}),
     }
   }
 
@@ -291,7 +297,7 @@ class MCPClientImpl<
       : // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
         ((defsOrOptions as ToolsOptions) ?? {}) // SDK interop: defsOrOptions may be undefined at runtime even though TS types it as ToolsOptions here
 
-    const { toolFilter, needsApproval } = this.#policy
+    const { toolFilter, needsApproval, toolName } = this.#policy
     const listed = await this.#listTools()
     const defs = toolFilter ? listed.filter((def) => toolFilter(def)) : listed
 
@@ -335,9 +341,13 @@ class MCPClientImpl<
         // recover the UNPREFIXED native name + serverId, and carries the
         // server's display title / annotations to the host — mirrors
         // toServerTools.
+        // `toolName` wins over the prefix. metadata.mcp keeps the server name.
+        const name =
+          toolName?.(serverTool) ??
+          (this.prefix ? `${this.prefix}_${def.name}` : def.name)
         const tool: McpServerTool = {
           ...bound,
-          ...(this.prefix ? { name: `${this.prefix}_${def.name}` } : {}),
+          name,
           ...(options.lazy ? { lazy: true } : {}),
           metadata: {
             ...bound.metadata,
@@ -350,6 +360,7 @@ class MCPClientImpl<
       // Auto-discovery path.
       tools = toServerTools(this.#client, defs, {
         prefix: this.prefix,
+        toolName,
         lazy: options.lazy,
         needsApproval,
       })
@@ -510,7 +521,11 @@ async function connectTransport<
     // instance is single-use, so it is not retained as a descriptor.
     isTransportInstance(options.transport) ? undefined : options.transport,
     options.clientOptions,
-    { toolFilter: options.toolFilter, needsApproval: options.needsApproval },
+    {
+      toolFilter: options.toolFilter,
+      needsApproval: options.needsApproval,
+      toolName: options.toolName,
+    },
   )
   await impl.connect(transport)
   return impl
diff --git a/packages/ai-mcp/src/connector.ts b/packages/ai-mcp/src/connector.ts
index 6b7f9f93a1..13ccc472ab 100644
--- a/packages/ai-mcp/src/connector.ts
+++ b/packages/ai-mcp/src/connector.ts
@@ -16,6 +16,7 @@ import type {
 import type { AnyTool } from '@tanstack/ai'
 import type { CredentialsAccess } 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>`. */
@@ -25,6 +26,11 @@ export interface McpConnectorOptions {
   url: string
   /** Tool name prefix. Default: the id. Tools are named `<prefix>_<tool>`. */
   prefix?: string
+  /**
+   * The name the model sees for each tool. Wins over `prefix`.
+   * See `MCPClientOptions.toolName`.
+   */
+  toolName?: MCPClientOptions['toolName']
   /** 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'`. */
@@ -242,6 +248,7 @@ export function mcpConnector(options: McpConnectorOptions) {
                   ...(options.fetch ? { fetch: options.fetch } : {}),
                 },
                 prefix,
+                toolName: options.toolName,
                 needsApproval:
                   options.needsApproval ??
                   ((tool) => tool.annotations?.readOnlyHint !== true),
diff --git a/packages/ai-mcp/src/pool.ts b/packages/ai-mcp/src/pool.ts
index b7c8278801..68637ee903 100644
--- a/packages/ai-mcp/src/pool.ts
+++ b/packages/ai-mcp/src/pool.ts
@@ -52,6 +52,7 @@ export interface MCPClients<
       clientOptions?: ClientOptions
       toolFilter?: MCPClientOptions['toolFilter']
       needsApproval?: MCPClientOptions['needsApproval']
+      toolName?: MCPClientOptions['toolName']
     }
   >
   /** Close every client. */
@@ -160,6 +161,7 @@ export async function createMCPClients<
         clientOptions?: ClientOptions
         toolFilter?: MCPClientOptions['toolFilter']
         needsApproval?: MCPClientOptions['needsApproval']
+        toolName?: MCPClientOptions['toolName']
       }
     > {
       // Keyed by config key (serverId / default prefix). Read each underlying
diff --git a/packages/ai-mcp/src/tools.ts b/packages/ai-mcp/src/tools.ts
index ab8edf401e..f56d37e93c 100644
--- a/packages/ai-mcp/src/tools.ts
+++ b/packages/ai-mcp/src/tools.ts
@@ -28,6 +28,7 @@ import type { McpServerTool, McpToolMetadata } from './types'
 
 interface ConvertOptions {
   prefix?: string
+  toolName?: (tool: McpToolDef) => string
   lazy?: boolean
   needsApproval?: (tool: McpToolDef) => boolean
 }
@@ -701,7 +702,10 @@ export function toServerTools(
   return defs
     .filter((def) => !requiresTaskExecution(def) || supportsTasks)
     .map((def) => {
-      const name = options.prefix ? `${options.prefix}_${def.name}` : def.name
+      // `toolName` wins over the prefix. metadata.mcp keeps the server name.
+      const name =
+        options.toolName?.(def) ??
+        (options.prefix ? `${options.prefix}_${def.name}` : def.name)
       // A server can leave out `type` or `properties`. Fill both, because
       // some providers reject an object schema without `properties`.
       const schema: Partial<McpToolDef['inputSchema']> = def.inputSchema ?? {}
diff --git a/packages/ai-mcp/src/types.ts b/packages/ai-mcp/src/types.ts
index 66980c9f15..14638bd8cc 100644
--- a/packages/ai-mcp/src/types.ts
+++ b/packages/ai-mcp/src/types.ts
@@ -87,6 +87,24 @@ export interface MCPClientOptions {
   transport: TransportInput
   /** Tool-name prefix (e.g. 'github' → 'github_search'). Default: none. */
   prefix?: string
+  /**
+   * The name the model sees for each tool. Wins over `prefix`.
+   * Receives the raw MCP tool definition (native `name`).
+   * Default: `${prefix}_${tool.name}` with a prefix, else `tool.name`.
+   *
+   * Applies to `tools()` and `tools([...defs])`. Two tools with the same
+   * final name throw `DuplicateToolNameError`.
+   * `metadata.mcp.serverToolName` keeps the server's own name, so
+   * `callTool()` and MCP Apps widget calls still reach the tool.
+   *
+   * ```ts
+   * const mcp = await createMCPClient({
+   *   transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+   *   toolName: (tool) => `mcp__github__${tool.name}`,
+   * })
+   * ```
+   */
+  toolName?: (tool: McpToolDef) => string
   /** Client identity sent to the server. */
   name?: string
   version?: string
diff --git a/packages/ai-mcp/tests/apps/call-handler.test.ts b/packages/ai-mcp/tests/apps/call-handler.test.ts
index 799355b3d2..7d8c2106a7 100644
--- a/packages/ai-mcp/tests/apps/call-handler.test.ts
+++ b/packages/ai-mcp/tests/apps/call-handler.test.ts
@@ -36,6 +36,7 @@ type ServerInfo = {
   prefix: string | undefined
   toolFilter?: (tool: { name: string }) => boolean
   needsApproval?: (tool: { name: string }) => boolean
+  toolName?: (tool: { name: string }) => string
 }
 
 // A method the call handler must never reach in these tests. Calling it is a
@@ -194,6 +195,35 @@ describe('createMcpAppCallHandler', () => {
     })
   })
 
+  it('reconnects with the client toolName', async () => {
+    const toolName = (tool: { name: string }) => `mcp__weather__${tool.name}`
+    const handler = createMcpAppCallHandler({
+      clients: fakePool({ weather: { ...WEATHER_HTTP, toolName } }),
+    })
+    await handler({ threadId: 't1', serverId: 'weather', toolName: 'x' })
+    expect(createMCPClient).toHaveBeenCalledWith({
+      transport: { type: 'http', url: 'https://x/mcp' },
+      prefix: 'weather',
+      toolName,
+    })
+  })
+
+  it('keeps the client toolName when a store returns a descriptor without it', async () => {
+    const toolName = (tool: { name: string }) => `mcp__weather__${tool.name}`
+    const store = inMemoryMcpSessionStore()
+    await store.set('t1', { weather: JSON.parse(JSON.stringify(WEATHER_HTTP)) })
+    const handler = createMcpAppCallHandler({
+      clients: fakePool({ weather: { ...WEATHER_HTTP, toolName } }),
+      store,
+    })
+    await handler({ threadId: 't1', serverId: 'weather', toolName: 'x' })
+    expect(createMCPClient).toHaveBeenCalledWith({
+      transport: { type: 'http', url: 'https://x/mcp' },
+      prefix: 'weather',
+      toolName,
+    })
+  })
+
   it('single-client path: defaults to the sole unnamed client when serverId is undefined', async () => {
     const handler = createMcpAppCallHandler({
       clients: fakeClient({
diff --git a/packages/ai-mcp/tests/client.test.ts b/packages/ai-mcp/tests/client.test.ts
index 79bec850d4..4416b23f79 100644
--- a/packages/ai-mcp/tests/client.test.ts
+++ b/packages/ai-mcp/tests/client.test.ts
@@ -19,6 +19,7 @@ import {
   makeServerWithChangingTools,
   makeServerWithLaxOutputSchemaTool,
   makeServerWithLoopingCursor,
+  makeServerWithMixedTools,
   makeServerWithPaginatedLaxSchemaTool,
   makeServerWithPaginatedTools,
   makeServerWithPendingTaskTool,
@@ -180,6 +181,62 @@ describe('createMCPClient', () => {
     expect(Object.isFrozen(mcp.annotations)).toBe(true)
   })
 
+  it('names bound definitions with toolName and keeps the server name', async () => {
+    const { clientTransport } = await makeServerWithWeatherTool()
+    await using client = await createMCPClient({
+      transport: clientTransport,
+      prefix: 'wx',
+      toolName: (tool) => `mcp__weather__${tool.name}`,
+    })
+    const getWeather = toolDefinition({
+      name: 'get_weather',
+      description: 'Get weather for a city',
+      inputSchema: z.object({ city: z.string() }),
+    })
+    const tools = await client.tools([getWeather])
+    expect(tools[0].name).toBe('mcp__weather__get_weather')
+    expect(tools[0].metadata.mcp).toMatchObject({
+      serverToolName: 'get_weather',
+      serverId: 'wx',
+    })
+    // The call still reaches the server tool by its own name.
+    const result = await tools[0].execute!(
+      { city: 'Oslo' },
+      { toolCallId: 't', emitCustomEvent: () => {} },
+    )
+    expect(JSON.stringify(result)).toContain('Sunny in Oslo')
+  })
+
+  it('throws DuplicateToolNameError naming the name when toolName gives two tools the same name', async () => {
+    const { clientTransport } = await makeServerWithMixedTools()
+    await using client = await createMCPClient({
+      transport: clientTransport,
+      toolName: () => 'same_name',
+    })
+    const error: unknown = await client.tools().catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(DuplicateToolNameError)
+    if (!(error instanceof DuplicateToolNameError)) {
+      throw new Error('expected DuplicateToolNameError')
+    }
+    expect(error.toolName).toBe('same_name')
+    expect(error.message).toContain('"same_name"')
+  })
+
+  it('reports toolName on getInfo so a rebuilt client keeps it', async () => {
+    const { clientTransport } = await makeServerWithWeatherTool()
+    const toolName = (tool: { name: string }) => `mcp__weather__${tool.name}`
+    await using client = await createMCPClient({
+      transport: clientTransport,
+      prefix: 'wx',
+      toolName,
+    })
+    expect(client.getInfo()).toStrictEqual({
+      transport: undefined,
+      prefix: 'wx',
+      toolName,
+    })
+  })
+
   it('discovers and executes task-required tools', async () => {
     const { clientTransport } = await makeServerWithTaskRequiredTool()
     await using client = await createMCPClientFromTransport(clientTransport)
diff --git a/packages/ai-mcp/tests/connector-edges.test.ts b/packages/ai-mcp/tests/connector-edges.test.ts
index 637a4bbe5b..8c51507a3a 100644
--- a/packages/ai-mcp/tests/connector-edges.test.ts
+++ b/packages/ai-mcp/tests/connector-edges.test.ts
@@ -473,3 +473,30 @@ describe('mcpConnector stored credential shapes', () => {
     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'])
+  })
+})
diff --git a/packages/ai-mcp/tests/pool.test.ts b/packages/ai-mcp/tests/pool.test.ts
index c0dd32ed60..4d996c5211 100644
--- a/packages/ai-mcp/tests/pool.test.ts
+++ b/packages/ai-mcp/tests/pool.test.ts
@@ -208,6 +208,36 @@ describe('createMCPClients', () => {
     const names = (await pool.tools()).map((tool) => tool.name).sort()
     expect(names).toEqual(['legacy_get_weather', 'modern_get_weather'])
   })
+
+  it('names each server tools with its own toolName', async () => {
+    const a = await makeServerWithWeatherTool()
+    const b = await makeServerWithWeatherTool()
+    const alphaName = (tool: { name: string }) => `mcp__alpha__${tool.name}`
+    await using pool = await createMCPClients({
+      alpha: { transport: a.clientTransport, toolName: alphaName },
+      beta: {
+        transport: b.clientTransport,
+        toolName: (tool) => `mcp__beta__${tool.name}`,
+      },
+    })
+    const names = (await pool.tools()).map((tool) => tool.name).sort()
+    expect(names).toEqual(['mcp__alpha__get_weather', 'mcp__beta__get_weather'])
+    expect(pool.getServers().alpha).toStrictEqual({
+      transport: undefined,
+      prefix: 'alpha',
+      toolName: alphaName,
+    })
+  })
+
+  it('throws DuplicateToolNameError when toolName gives two servers one name', async () => {
+    const a = await makeServerWithWeatherTool()
+    const b = await makeServerWithWeatherTool()
+    await using pool = await createMCPClients({
+      alpha: { transport: a.clientTransport, toolName: (tool) => tool.name },
+      beta: { transport: b.clientTransport, toolName: (tool) => tool.name },
+    })
+    await expect(pool.tools()).rejects.toThrow(DuplicateToolNameError)
+  })
 })
 
 // The server has no public setter for the negotiated era, so the test sets it.
diff --git a/packages/ai-mcp/tests/tools.test.ts b/packages/ai-mcp/tests/tools.test.ts
index 3c68f7be12..50ed761b4a 100644
--- a/packages/ai-mcp/tests/tools.test.ts
+++ b/packages/ai-mcp/tests/tools.test.ts
@@ -766,6 +766,38 @@ describe('toServerTools — input schema defaults', () => {
   })
 })
 
+describe('toServerTools — toolName', () => {
+  it('names each tool with toolName, which wins over the prefix', () => {
+    const [tool] = toServerTools(
+      fakeMcpClient(vi.fn()),
+      [mcpToolDef({ name: 'get_weather' })],
+      { prefix: 'wx', toolName: (def) => `mcp__wx__${def.name}` },
+    )
+    expect(tool!.name).toBe('mcp__wx__get_weather')
+    expect(tool!.metadata.mcp).toMatchObject({
+      serverToolName: 'get_weather',
+      serverId: 'wx',
+    })
+  })
+
+  it('calls the server tool by its own name', async () => {
+    const callTool = vi
+      .fn()
+      .mockResolvedValue({ content: [{ type: 'text', text: 'ok' }] })
+    const [tool] = toServerTools(
+      fakeMcpClient(callTool),
+      [mcpToolDef({ name: 'get_weather' })],
+      { toolName: () => 'renamed' },
+    )
+    expect(tool!.name).toBe('renamed')
+    await expect(tool!.execute!({})).resolves.toBe('ok')
+    expect(callTool).toHaveBeenCalledWith(
+      { name: 'get_weather', arguments: {} },
+      expect.anything(),
+    )
+  })
+})
+
 describe('toServerTools', () => {
   it('discovers tools and proxies execute to callTool', async () => {
     const { clientTransport } = await makeServerWithWeatherTool()

From eac67f238804dcf4b266bf2c44a6f8b68b1e3cbb Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 3 Oct 2026 17:50:12 +0200
Subject: [PATCH 199/286] feat(ai, ai-harness): add LogRecordsCapability and
 provide it on a durable host

A middleware can now append records to the durable session log of its run. Core adds LogRecordsCapability with getLogRecords and provideLogRecords. A durable harness session provides it to each turn's chat run. The records land at once and fold, with the same checks as session.append, so a type that starts with harness. is refused. A host without a log provides nothing.
---
 packages/ai-harness/src/session.ts            | 27 +++++
 .../ai-harness/tests/durable-session.test.ts  | 98 ++++++++++++++++++-
 .../activities/chat/middleware/log-records.ts | 17 ++++
 packages/ai/src/index.ts                      |  7 ++
 packages/ai/tests/log-records.test.ts         | 31 ++++++
 5 files changed, 178 insertions(+), 2 deletions(-)
 create mode 100644 packages/ai/src/activities/chat/middleware/log-records.ts
 create mode 100644 packages/ai/tests/log-records.test.ts

diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index decbfe6e47..49412744b0 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -1,5 +1,6 @@
 import {
   EventType,
+  LogRecordsCapability,
   RUN_CANCEL_REASON,
   StreamProcessor,
   SubagentBudget,
@@ -9,6 +10,7 @@ import {
   createSubagentId,
   maxIterations,
   modelMessagesToUIMessages,
+  provideLogRecords,
   runAgentStream,
   validateWithStandardSchema,
 } from '@tanstack/ai'
@@ -43,6 +45,7 @@ import type {
   AnyTextAdapter,
   AnyTool,
   Interrupt,
+  LogRecordsWriter,
   Modality,
   ModelMessage,
   PromptCacheOptions,
@@ -1674,6 +1677,29 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }
   }
 
+  /**
+   * On a durable host, each turn's chat run gets `LogRecordsCapability`. A
+   * middleware, for example a durable compaction, appends host records with
+   * it. They land in the log at once and fold, with the checks of
+   * `session.append`. Agent runs do not get it: a child writes to its own
+   * thread.
+   */
+  private logRecords(): AnyChatMiddleware | undefined {
+    const { writer } = this
+    if (!writer) return undefined
+    const records: LogRecordsWriter = {
+      append: async (list) => {
+        checkHostRecords(list)
+        await writer.append(list)
+      },
+    }
+    return {
+      name: 'harness:log-records',
+      provides: [LogRecordsCapability],
+      setup: (ctx) => provideLogRecords(ctx, records),
+    }
+  }
+
   private isAbortRequested(inputId: string) {
     return (
       this.writer?.state.inputs.get(inputId)?.abortRequested === true ||
@@ -2065,6 +2091,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       const bridges = [
         session?.capabilityBridge,
         runPlugins?.capabilityBridge,
+        this.logRecords(),
       ].filter((bridge): bridge is AnyChatMiddleware => bridge !== undefined)
       // Agents the model can call: the harness's own, then the plugins'.
       const subagentList = [
diff --git a/packages/ai-harness/tests/durable-session.test.ts b/packages/ai-harness/tests/durable-session.test.ts
index b22e998870..2e728663de 100644
--- a/packages/ai-harness/tests/durable-session.test.ts
+++ b/packages/ai-harness/tests/durable-session.test.ts
@@ -1,10 +1,10 @@
 import { describe, expect, it, vi } from 'vitest'
-import { EventType, toolDefinition } from '@tanstack/ai'
+import { EventType, getLogRecords, toolDefinition } from '@tanstack/ai'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness, definePlugin } from '../src'
 import { loadLogState, sessionOf } from '../src/log'
 import { gate, messageTexts, mockAdapter, text, toolCall } from './helpers'
-import type { ModelMessage, StreamChunk } from '@tanstack/ai'
+import type { ChatMiddleware, ModelMessage, StreamChunk } from '@tanstack/ai'
 import type { LogStore } from '@tanstack/ai-persistence'
 import type { HarnessSession, ProjectOptions, SessionEvent } from '../src'
 import type { Reply } from './helpers'
@@ -529,3 +529,97 @@ describe('durable session log', () => {
     await next.close()
   })
 })
+
+describe('LogRecordsCapability', () => {
+  it('lets a middleware append host records that fold into the next model call', async () => {
+    const persistence = durablePersistence()
+    const { adapter, calls } = mockAdapter([() => text('a1'), () => text('a2')])
+    const signal: ChatMiddleware = {
+      name: 'test:signal',
+      onFinish: async (ctx) => {
+        await getLogRecords(ctx, { optional: true })?.append([
+          { type: 'app.signal', text: '[signal] saved' },
+        ])
+      },
+    }
+    const host = createHarnessHost({ persistence, project })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/log-records',
+        adapter,
+        middleware: [signal],
+      }),
+      { threadId: THREAD },
+    )
+
+    await session.prompt('q1')
+    await session.prompt('q2')
+
+    expect(messageTexts(calls[1])).toEqual(['q1', 'a1', '[signal] saved', 'q2'])
+    const rebuilt = sessionOf(
+      await loadLogState({
+        store: persistence.stores.log,
+        logId: THREAD,
+        project,
+      }),
+      THREAD,
+    )
+    expect(await session.transcript()).toEqual(rebuilt.messages)
+    await host.close()
+  })
+
+  it('refuses a record type that the harness owns', async () => {
+    let failure: unknown
+    const bad: ChatMiddleware = {
+      name: 'test:bad',
+      onFinish: async (ctx) => {
+        try {
+          await getLogRecords(ctx).append([{ type: 'harness.event' }])
+        } catch (error) {
+          failure = error
+        }
+      },
+    }
+    const { adapter } = mockAdapter([() => text('a1')])
+    const host = createHarnessHost({ persistence: durablePersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/log-records-bad',
+        adapter,
+        middleware: [bad],
+      }),
+      { threadId: THREAD },
+    )
+
+    await session.prompt('q1')
+
+    expect(failure).toBeInstanceOf(Error)
+    expect(String(failure)).toContain('reserved for the harness')
+    await host.close()
+  })
+
+  it('gives nothing on a host without a log', async () => {
+    let seen: unknown = 'not called'
+    const probe: ChatMiddleware = {
+      name: 'test:probe',
+      onConfig: (ctx) => {
+        seen = getLogRecords(ctx, { optional: true })
+      },
+    }
+    const { adapter } = mockAdapter([() => text('a1')])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/log-records-none',
+        adapter,
+        middleware: [probe],
+      }),
+      { threadId: THREAD },
+    )
+
+    await session.prompt('q1')
+
+    expect(seen).toBeUndefined()
+    await host.close()
+  })
+})
diff --git a/packages/ai/src/activities/chat/middleware/log-records.ts b/packages/ai/src/activities/chat/middleware/log-records.ts
new file mode 100644
index 0000000000..22dd4dbff3
--- /dev/null
+++ b/packages/ai/src/activities/chat/middleware/log-records.ts
@@ -0,0 +1,17 @@
+import { createCapability } from './capabilities'
+
+/**
+ * Appends records to the durable session log of this run. A host with a
+ * session log provides it, for example a durable harness session. The host
+ * checks the records, writes them at once, and folds them into the context.
+ */
+export interface LogRecordsWriter {
+  append: (
+    records: ReadonlyArray<{ type: string } & Record<string, unknown>>,
+  ) => Promise<void>
+}
+
+export const LogRecordsCapability =
+  createCapability<LogRecordsWriter>()('log-records')
+
+export const [getLogRecords, provideLogRecords] = LogRecordsCapability
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index 542295554f..4d01023eb2 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -378,6 +378,13 @@ export type {
   AnyChatMiddleware,
   MetadataStore,
 } from './activities/chat/middleware/index'
+// A durable host gives a run its session log with this capability.
+export {
+  LogRecordsCapability,
+  getLogRecords,
+  provideLogRecords,
+} from './activities/chat/middleware/log-records'
+export type { LogRecordsWriter } from './activities/chat/middleware/log-records'
 // Locks are a distributed-mutex primitive — coordination, not chat state — and
 // live behind their own subpath: `@tanstack/ai/locks` (see ./locks.ts).
 
diff --git a/packages/ai/tests/log-records.test.ts b/packages/ai/tests/log-records.test.ts
new file mode 100644
index 0000000000..14aaa4a82c
--- /dev/null
+++ b/packages/ai/tests/log-records.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import {
+  LogRecordsCapability,
+  getLogRecords,
+  provideLogRecords,
+} from '../src/index'
+import { CapabilityRegistry } from '../src/activities/chat/middleware/capabilities'
+import type { LogRecordsWriter } from '../src/index'
+
+describe('LogRecordsCapability', () => {
+  it('reads as undefined when no host provides it', () => {
+    const ctx = { capabilities: new CapabilityRegistry() }
+    expect(getLogRecords(ctx, { optional: true })).toBeUndefined()
+  })
+
+  it('gives a middleware the writer that the host provides', async () => {
+    const ctx = { capabilities: new CapabilityRegistry() }
+    const written: Array<unknown> = []
+    const writer: LogRecordsWriter = {
+      append: async (records) => {
+        written.push(...records)
+      },
+    }
+    provideLogRecords(ctx, writer)
+
+    await getLogRecords(ctx).append([{ type: 'app.note', text: 'hi' }])
+
+    expect(written).toEqual([{ type: 'app.note', text: 'hi' }])
+    expect(LogRecordsCapability.capabilityName).toBe('log-records')
+  })
+})

From e9a713a76dcfdca6660c8253026425245f80f3d5 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 3 Oct 2026 18:04:31 +0200
Subject: [PATCH 200/286] feat(ai-mcp): add requestOptions for MCP request
 timeouts

requestOptions { timeout, resetTimeoutOnProgress } is sent with tools/list on both eras, tools/call on all three paths, callTool, resources, resource templates, and prompts. The per-call signal is merged in. A spec 2026 tools/call uses timeout in place of the fixed 60 s. resetTimeoutOnProgress adds a no-op onprogress, because the SDK asks for progress only then. The pool, mcpConnector, getInfo, McpServerDescriptor, and the MCP Apps call handler forward the option.
---
 packages/ai-mcp/src/apps/call-handler.ts      |   9 +-
 packages/ai-mcp/src/apps/session-store.ts     |   2 +
 packages/ai-mcp/src/client.ts                 |  44 +++--
 packages/ai-mcp/src/connector.ts              |   3 +
 packages/ai-mcp/src/pool.ts                   |   2 +
 packages/ai-mcp/src/tools.ts                  |  58 +++++-
 packages/ai-mcp/src/types.ts                  |  20 +++
 .../ai-mcp/tests/apps/call-handler.test.ts    |  30 ++++
 packages/ai-mcp/tests/client.test.ts          | 169 ++++++++++++++++++
 packages/ai-mcp/tests/connector-edges.test.ts |  48 +++++
 packages/ai-mcp/tests/pool.test.ts            |  17 ++
 packages/ai-mcp/tests/tools.test.ts           |  80 +++++++++
 12 files changed, 460 insertions(+), 22 deletions(-)

diff --git a/packages/ai-mcp/src/apps/call-handler.ts b/packages/ai-mcp/src/apps/call-handler.ts
index f18420c564..50d55301b1 100644
--- a/packages/ai-mcp/src/apps/call-handler.ts
+++ b/packages/ai-mcp/src/apps/call-handler.ts
@@ -131,6 +131,7 @@ function buildRegistry(clients: McpAppClientsInput): AppRegistry {
     toolFilter?: McpServerDescriptor['toolFilter']
     needsApproval?: McpServerDescriptor['needsApproval']
     toolName?: McpServerDescriptor['toolName']
+    requestOptions?: McpServerDescriptor['requestOptions']
   }) => {
     const descriptor: McpServerDescriptor = {
       transport: info.transport,
@@ -139,6 +140,7 @@ function buildRegistry(clients: McpAppClientsInput): AppRegistry {
       ...(info.toolFilter ? { toolFilter: info.toolFilter } : {}),
       ...(info.needsApproval ? { needsApproval: info.needsApproval } : {}),
       ...(info.toolName ? { toolName: info.toolName } : {}),
+      ...(info.requestOptions ? { requestOptions: info.requestOptions } : {}),
     }
     total += 1
     const key = info.prefix
@@ -244,11 +246,15 @@ export function createMcpAppCallHandler(opts: McpAppCallHandlerOptions) {
     // can come back without `toolFilter`, `needsApproval`, or `toolName`. Fall
     // back to the options of the same server in `clients`, or a widget could
     // call a tool the model cannot see, or run one the model can run only
-    // after approval.
+    // after approval. A stored descriptor can also lack `requestOptions` when
+    // the code that wrote it did not set it. Then the widget call uses the
+    // timeout of the same server in `clients`.
     const toolFilter = descriptor.toolFilter ?? fromRegistry?.toolFilter
     const needsApproval =
       descriptor.needsApproval ?? fromRegistry?.needsApproval
     const toolName = descriptor.toolName ?? fromRegistry?.toolName
+    const requestOptions =
+      descriptor.requestOptions ?? fromRegistry?.requestOptions
     const client = await createMCPClient({
       transport: descriptor.transport,
       prefix: descriptor.prefix,
@@ -258,6 +264,7 @@ export function createMcpAppCallHandler(opts: McpAppCallHandlerOptions) {
       ...(toolFilter ? { toolFilter } : {}),
       ...(needsApproval ? { needsApproval } : {}),
       ...(toolName ? { toolName } : {}),
+      ...(requestOptions ? { requestOptions } : {}),
     })
 
     try {
diff --git a/packages/ai-mcp/src/apps/session-store.ts b/packages/ai-mcp/src/apps/session-store.ts
index 2001fe3322..0518d46c8a 100644
--- a/packages/ai-mcp/src/apps/session-store.ts
+++ b/packages/ai-mcp/src/apps/session-store.ts
@@ -22,6 +22,8 @@ export interface McpServerDescriptor {
   needsApproval?: MCPClientOptions['needsApproval']
   /** Carried so a reconnect names the tools the same way as for the model. */
   toolName?: MCPClientOptions['toolName']
+  /** Carried so a widget call waits as long as a model tool call. */
+  requestOptions?: MCPClientOptions['requestOptions']
 }
 
 export interface McpSessionStore {
diff --git a/packages/ai-mcp/src/client.ts b/packages/ai-mcp/src/client.ts
index 22bb057fcd..36a0f5480a 100644
--- a/packages/ai-mcp/src/client.ts
+++ b/packages/ai-mcp/src/client.ts
@@ -10,6 +10,7 @@ import {
   callMcpTool,
   makeMcpExecute,
   requiresTaskExecution,
+  sdkRequestOptions,
   serverSupportsTaskCalls,
   toolMcpMetadata,
   toServerTools,
@@ -58,7 +59,7 @@ export type TypedCallToolResult<TOutput> = unknown extends TOutput
 
 type ToolPolicy = Pick<
   MCPClientOptions,
-  'toolFilter' | 'needsApproval' | 'toolName'
+  'toolFilter' | 'needsApproval' | 'toolName' | 'requestOptions'
 >
 
 export interface MCPClient<
@@ -147,6 +148,7 @@ export interface MCPClient<
     toolFilter?: MCPClientOptions['toolFilter']
     needsApproval?: MCPClientOptions['needsApproval']
     toolName?: MCPClientOptions['toolName']
+    requestOptions?: MCPClientOptions['requestOptions']
   }
   close: () => Promise<void>
   [Symbol.asyncDispose]: () => Promise<void>
@@ -213,8 +215,9 @@ class MCPClientImpl<
     toolFilter?: MCPClientOptions['toolFilter']
     needsApproval?: MCPClientOptions['needsApproval']
     toolName?: MCPClientOptions['toolName']
+    requestOptions?: MCPClientOptions['requestOptions']
   } {
-    const { toolFilter, needsApproval, toolName } = this.#policy
+    const { toolFilter, needsApproval, toolName, requestOptions } = this.#policy
     return {
       transport: this.#transport,
       prefix: this.prefix,
@@ -222,6 +225,7 @@ class MCPClientImpl<
       ...(toolFilter ? { toolFilter } : {}),
       ...(needsApproval ? { needsApproval } : {}),
       ...(toolName ? { toolName } : {}),
+      ...(requestOptions ? { requestOptions } : {}),
     }
   }
 
@@ -268,19 +272,20 @@ class MCPClientImpl<
   // `raw: true` is the lazy `callTool` path. It must stay free of that cache.
   async #listTools(options?: { raw?: boolean }) {
     const client = this.#client
+    const requestOptions = sdkRequestOptions(this.#policy.requestOptions)
     const defs = await listPages(async (cursor) => {
       const page =
         cursor === undefined
-          ? await client.request({ method: 'tools/list' })
-          : await client.request({
-              method: 'tools/list',
-              params: { cursor },
-            })
+          ? await client.request({ method: 'tools/list' }, requestOptions)
+          : await client.request(
+              { method: 'tools/list', params: { cursor } },
+              requestOptions,
+            )
       return { items: page.tools, nextCursor: page.nextCursor }
     })
     this.#toolDefinitions = new Map(defs.map((def) => [def.name, def]))
     if (options?.raw !== true && client.getProtocolEra() !== 'modern') {
-      await client.listTools()
+      await client.listTools(undefined, requestOptions)
     }
     return defs
   }
@@ -297,7 +302,7 @@ class MCPClientImpl<
       : // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
         ((defsOrOptions as ToolsOptions) ?? {}) // SDK interop: defsOrOptions may be undefined at runtime even though TS types it as ToolsOptions here
 
-    const { toolFilter, needsApproval, toolName } = this.#policy
+    const { toolFilter, needsApproval, toolName, requestOptions } = this.#policy
     const listed = await this.#listTools()
     const defs = toolFilter ? listed.filter((def) => toolFilter(def)) : listed
 
@@ -322,6 +327,7 @@ class MCPClientImpl<
             def.name,
             Boolean(def.outputSchema),
             requiresTaskExecution(serverTool),
+            requestOptions,
           ),
         ) as ServerTool
         // A caller-supplied definition may already carry its own `mcp` block,
@@ -363,6 +369,7 @@ class MCPClientImpl<
         toolName,
         lazy: options.lazy,
         needsApproval,
+        requestOptions,
       })
     }
 
@@ -377,22 +384,27 @@ class MCPClientImpl<
 
   async resources(): Promise<Array<Resource>> {
     if (this.#closed) throw new MCPConnectionError('MCP client is closed')
-    return (await this.#client.listResources()).resources
+    const options = sdkRequestOptions(this.#policy.requestOptions)
+    return (await this.#client.listResources(undefined, options)).resources
   }
 
   async readResource(uri: string): Promise<ReadResourceResult> {
     if (this.#closed) throw new MCPConnectionError('MCP client is closed')
-    return this.#client.readResource({ uri })
+    const options = sdkRequestOptions(this.#policy.requestOptions)
+    return this.#client.readResource({ uri }, options)
   }
 
   async resourceTemplates(): Promise<Array<ResourceTemplateType>> {
     if (this.#closed) throw new MCPConnectionError('MCP client is closed')
-    return (await this.#client.listResourceTemplates()).resourceTemplates
+    const options = sdkRequestOptions(this.#policy.requestOptions)
+    return (await this.#client.listResourceTemplates(undefined, options))
+      .resourceTemplates
   }
 
   async prompts(): Promise<Array<Prompt>> {
     if (this.#closed) throw new MCPConnectionError('MCP client is closed')
-    return (await this.#client.listPrompts()).prompts
+    const options = sdkRequestOptions(this.#policy.requestOptions)
+    return (await this.#client.listPrompts(undefined, options)).prompts
   }
 
   async getPrompt(name: string, args?: unknown): Promise<GetPromptResult> {
@@ -403,7 +415,8 @@ class MCPClientImpl<
           Object.entries(args).map(([key, value]) => [key, String(value)]),
         )
       : undefined
-    return this.#client.getPrompt({ name, arguments: promptArgs })
+    const options = sdkRequestOptions(this.#policy.requestOptions)
+    return this.#client.getPrompt({ name, arguments: promptArgs }, options)
   }
 
   async callTool<TName extends keyof TServer['tools'] & string>(
@@ -438,6 +451,8 @@ class MCPClientImpl<
       isArgs(args) ? args : {},
       taskRequired,
       options?.signal,
+      undefined,
+      this.#policy.requestOptions,
     )
     // Trust boundary: the server type says what `structuredContent` holds.
     // The client does not check the wire value against that type.
@@ -525,6 +540,7 @@ async function connectTransport<
       toolFilter: options.toolFilter,
       needsApproval: options.needsApproval,
       toolName: options.toolName,
+      requestOptions: options.requestOptions,
     },
   )
   await impl.connect(transport)
diff --git a/packages/ai-mcp/src/connector.ts b/packages/ai-mcp/src/connector.ts
index 13ccc472ab..fb30f8eb53 100644
--- a/packages/ai-mcp/src/connector.ts
+++ b/packages/ai-mcp/src/connector.ts
@@ -31,6 +31,8 @@ export interface McpConnectorOptions {
    * See `MCPClientOptions.toolName`.
    */
   toolName?: MCPClientOptions['toolName']
+  /** Sent with every request to the server. 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'`. */
@@ -249,6 +251,7 @@ export function mcpConnector(options: McpConnectorOptions) {
                 },
                 prefix,
                 toolName: options.toolName,
+                requestOptions: options.requestOptions,
                 needsApproval:
                   options.needsApproval ??
                   ((tool) => tool.annotations?.readOnlyHint !== true),
diff --git a/packages/ai-mcp/src/pool.ts b/packages/ai-mcp/src/pool.ts
index 68637ee903..b5621aa04e 100644
--- a/packages/ai-mcp/src/pool.ts
+++ b/packages/ai-mcp/src/pool.ts
@@ -53,6 +53,7 @@ export interface MCPClients<
       toolFilter?: MCPClientOptions['toolFilter']
       needsApproval?: MCPClientOptions['needsApproval']
       toolName?: MCPClientOptions['toolName']
+      requestOptions?: MCPClientOptions['requestOptions']
     }
   >
   /** Close every client. */
@@ -162,6 +163,7 @@ export async function createMCPClients<
         toolFilter?: MCPClientOptions['toolFilter']
         needsApproval?: MCPClientOptions['needsApproval']
         toolName?: MCPClientOptions['toolName']
+        requestOptions?: MCPClientOptions['requestOptions']
       }
     > {
       // Keyed by config key (serverId / default prefix). Read each underlying
diff --git a/packages/ai-mcp/src/tools.ts b/packages/ai-mcp/src/tools.ts
index f56d37e93c..d0365f7a3d 100644
--- a/packages/ai-mcp/src/tools.ts
+++ b/packages/ai-mcp/src/tools.ts
@@ -10,6 +10,7 @@ import {
 import type {
   Client,
   Request,
+  RequestOptions,
   TaskStatus,
   Tool as McpToolDef,
   ToolAnnotations,
@@ -24,13 +25,14 @@ import {
   isMCPInputRequiredError,
   MCPInputRequiredError,
 } from './input-required'
-import type { McpServerTool, McpToolMetadata } from './types'
+import type { MCPClientOptions, McpServerTool, McpToolMetadata } from './types'
 
 interface ConvertOptions {
   prefix?: string
   toolName?: (tool: McpToolDef) => string
   lazy?: boolean
   needsApproval?: (tool: McpToolDef) => boolean
+  requestOptions?: MCPClientOptions['requestOptions']
 }
 
 /** Reads the MCP Apps `_meta.ui.resourceUri` link from a tool def, if present. */
@@ -144,6 +146,7 @@ export function mcpContentToTanstack(
  * @param taskRequired - True when the tool requires a spec 2025 task
  * @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
  */
 export async function callMcpTool(
   client: Client,
@@ -152,13 +155,17 @@ export async function callMcpTool(
   taskRequired: boolean,
   signal?: AbortSignal,
   inputResponse?: ToolInputResponse,
+  requestOptions?: MCPClientOptions['requestOptions'],
 ) {
   signal?.throwIfAborted()
   const isModern = client.getProtocolEra() === 'modern'
   if (!taskRequired && !isModern) {
     const result = await client.callTool(
       { name: mcpName, arguments: args },
-      { signal, allowInputRequired: true },
+      {
+        ...sdkRequestOptions(requestOptions, signal),
+        allowInputRequired: true,
+      },
     )
     throwIfInputRequired(result)
     return result
@@ -166,12 +173,13 @@ export async function callMcpTool(
 
   const params = { name: mcpName, arguments: args }
   let raw = isModern
-    ? await rawRequest(client, 'tools/call', params, signal)
+    ? await rawRequest(client, 'tools/call', params, signal, requestOptions)
     : await sdkRequest(
         client,
         'tools/call',
         { name: mcpName, arguments: args, task: {} },
         signal,
+        requestOptions,
       )
   // ponytail: the answer is sent on the second call, so the server state never
   // travels through the browser. The cost is one extra tools/call.
@@ -181,6 +189,7 @@ export async function callMcpTool(
       'tools/call',
       { ...params, ...retryParams(raw, inputResponse) },
       signal,
+      requestOptions,
     )
     // ponytail: one input round per call. The next resume starts with no
     // requestState, so a second pause would ask round 1 again forever.
@@ -356,6 +365,9 @@ async function readPolledTask(
   return task
 }
 
+// ponytail: task polls (tasks/get, tasks/result, tasks/cancel) keep the SDK
+// default timeout. Each poll is a short request. Pass the client
+// requestOptions here if a server is slow to answer a poll.
 function taskRequest(
   client: Client,
   method: string,
@@ -365,11 +377,33 @@ function taskRequest(
   return sdkRequest(client, method, params, signal)
 }
 
+/**
+ * The SDK options for one request: the client `requestOptions` plus the
+ * caller's `signal`. `undefined` when both are unset, so the SDK defaults
+ * apply.
+ *
+ * The SDK asks the server for progress only when `onprogress` is set. So a
+ * no-op `onprogress` comes with `resetTimeoutOnProgress`, or that option
+ * would never see a progress notification.
+ */
+export function sdkRequestOptions(
+  requestOptions: MCPClientOptions['requestOptions'],
+  signal?: AbortSignal,
+): RequestOptions | undefined {
+  if (requestOptions === undefined && signal === undefined) return undefined
+  return {
+    ...requestOptions,
+    ...(requestOptions?.resetTimeoutOnProgress ? { onprogress: () => {} } : {}),
+    ...(signal === undefined ? {} : { signal }),
+  }
+}
+
 async function sdkRequest(
   client: Client,
   method: string,
   params: Record<string, unknown>,
   signal?: AbortSignal,
+  requestOptions?: MCPClientOptions['requestOptions'],
 ) {
   signal?.throwIfAborted()
   const rpc: Request = { method, params }
@@ -377,7 +411,7 @@ async function sdkRequest(
     return await client.request(
       rpc,
       passThroughResult,
-      signal === undefined ? undefined : { signal },
+      sdkRequestOptions(requestOptions, signal),
     )
   } catch (error) {
     if (signal?.aborted) throw abortReason(signal)
@@ -390,6 +424,7 @@ function rawRequest(
   method: string,
   params: Record<string, unknown>,
   signal?: AbortSignal,
+  requestOptions?: MCPClientOptions['requestOptions'],
 ) {
   signal?.throwIfAborted()
   const transport = client.transport
@@ -402,15 +437,20 @@ function rawRequest(
   const body = withEnvelope(params, readEnvelope(client))
   return new Promise<unknown>((resolve, reject) => {
     let settled = false
-    // Same limit as an SDK request, so a lost response cannot hang the call.
+    // The client `timeout`, else the SDK default, so a lost response cannot
+    // hang the call.
+    // ponytail: this request sends no progressToken, so the server sends no
+    // progress and `resetTimeoutOnProgress` cannot apply. Send a token and
+    // match notifications/progress in `accept` if a spec 2026 server needs it.
+    const timeout = requestOptions?.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC
     const timer = setTimeout(() => {
       finish(
         new SdkError(
           SdkErrorCode.RequestTimeout,
-          `The MCP request ${method} timed out after ${DEFAULT_REQUEST_TIMEOUT_MSEC} ms.`,
+          `The MCP request ${method} timed out after ${timeout} ms.`,
         ),
       )
-    }, DEFAULT_REQUEST_TIMEOUT_MSEC)
+    }, timeout)
     const finish = (error: unknown, result?: unknown) => {
       if (settled) return
       settled = true
@@ -633,12 +673,14 @@ function isRecord(value: unknown): value is Record<string, unknown> {
  *   return `result.structuredContent` if present so the existing output
  *   validation in `executeServerTool` validates MCP's typed payload rather than
  *   a JSON-in-text blob. Otherwise normalize `content[]` → string | ContentPart[].
+ * @param requestOptions - The client `requestOptions`, sent with each call
  */
 export function makeMcpExecute(
   client: Client,
   mcpName: string,
   preferStructured: boolean,
   taskRequired = false,
+  requestOptions?: MCPClientOptions['requestOptions'],
 ) {
   return async (
     args: unknown,
@@ -651,6 +693,7 @@ export function makeMcpExecute(
       taskRequired,
       ctx?.abortSignal,
       ctx?.inputResponse,
+      requestOptions,
     )
     if (result.isError) {
       const text = Array.isArray(result.content)
@@ -728,6 +771,7 @@ export function toServerTools(
           def.name,
           Boolean(def.outputSchema),
           requiresTaskExecution(def),
+          options.requestOptions,
         ),
       }
       if (options.needsApproval?.(def)) {
diff --git a/packages/ai-mcp/src/types.ts b/packages/ai-mcp/src/types.ts
index 14638bd8cc..664cfe1662 100644
--- a/packages/ai-mcp/src/types.ts
+++ b/packages/ai-mcp/src/types.ts
@@ -133,6 +133,26 @@ export interface MCPClientOptions {
    * ```
    */
   clientOptions?: ClientOptions
+  /**
+   * Sent with every request this client makes: `tools/list`, `tools/call`,
+   * resources, and prompts. SDK defaults when unset.
+   *
+   * A spec 2026 `tools/call` gets no progress notifications, so there only
+   * `timeout` applies.
+   *
+   * ```ts
+   * const mcp = await createMCPClient({
+   *   transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+   *   requestOptions: { timeout: 120_000, resetTimeoutOnProgress: true },
+   * })
+   * ```
+   */
+  requestOptions?: {
+    /** Milliseconds. The SDK default is 60,000. */
+    timeout?: number
+    /** Restart the timeout when the server sends a progress notification. */
+    resetTimeoutOnProgress?: boolean
+  }
   /**
    * Return `false` to hide a server tool. Receives the raw MCP tool definition
    * (native `name`, `title`, `annotations`). Default: every tool.
diff --git a/packages/ai-mcp/tests/apps/call-handler.test.ts b/packages/ai-mcp/tests/apps/call-handler.test.ts
index 7d8c2106a7..6abe99216b 100644
--- a/packages/ai-mcp/tests/apps/call-handler.test.ts
+++ b/packages/ai-mcp/tests/apps/call-handler.test.ts
@@ -37,6 +37,7 @@ type ServerInfo = {
   toolFilter?: (tool: { name: string }) => boolean
   needsApproval?: (tool: { name: string }) => boolean
   toolName?: (tool: { name: string }) => string
+  requestOptions?: { timeout?: number; resetTimeoutOnProgress?: boolean }
 }
 
 // A method the call handler must never reach in these tests. Calling it is a
@@ -224,6 +225,35 @@ describe('createMcpAppCallHandler', () => {
     })
   })
 
+  it('reconnects with the client requestOptions', async () => {
+    const requestOptions = { timeout: 5000 }
+    const handler = createMcpAppCallHandler({
+      clients: fakePool({ weather: { ...WEATHER_HTTP, requestOptions } }),
+    })
+    await handler({ threadId: 't1', serverId: 'weather', toolName: 'x' })
+    expect(createMCPClient).toHaveBeenCalledWith({
+      transport: { type: 'http', url: 'https://x/mcp' },
+      prefix: 'weather',
+      requestOptions,
+    })
+  })
+
+  it('keeps the client requestOptions when a store returns a descriptor without them', async () => {
+    const requestOptions = { timeout: 5000 }
+    const store = inMemoryMcpSessionStore()
+    await store.set('t1', { weather: JSON.parse(JSON.stringify(WEATHER_HTTP)) })
+    const handler = createMcpAppCallHandler({
+      clients: fakePool({ weather: { ...WEATHER_HTTP, requestOptions } }),
+      store,
+    })
+    await handler({ threadId: 't1', serverId: 'weather', toolName: 'x' })
+    expect(createMCPClient).toHaveBeenCalledWith({
+      transport: { type: 'http', url: 'https://x/mcp' },
+      prefix: 'weather',
+      requestOptions,
+    })
+  })
+
   it('single-client path: defaults to the sole unnamed client when serverId is undefined', async () => {
     const handler = createMcpAppCallHandler({
       clients: fakeClient({
diff --git a/packages/ai-mcp/tests/client.test.ts b/packages/ai-mcp/tests/client.test.ts
index 4416b23f79..5f0e190bcb 100644
--- a/packages/ai-mcp/tests/client.test.ts
+++ b/packages/ai-mcp/tests/client.test.ts
@@ -651,6 +651,104 @@ describe('clientOptions', () => {
   })
 })
 
+describe('requestOptions', () => {
+  it('sends the timeout with tools/list, tools/call, resources, and prompts', async () => {
+    const { clientTransport } = await makeSilentServer()
+    await using client = await createMCPClient({
+      transport: clientTransport,
+      requestOptions: { timeout: 50 },
+    })
+    // The server never answers, so only the 50 ms timeout ends a request.
+    await expect(client.tools()).rejects.toThrow('Request timed out')
+    await expect(client.callTool('slow')).rejects.toThrow('Request timed out')
+    await expect(client.resources()).rejects.toThrow('Request timed out')
+    await expect(client.readResource('file:///a.txt')).rejects.toThrow(
+      'Request timed out',
+    )
+    await expect(client.resourceTemplates()).rejects.toThrow(
+      'Request timed out',
+    )
+    await expect(client.prompts()).rejects.toThrow('Request timed out')
+    await expect(client.getPrompt('brief')).rejects.toThrow('Request timed out')
+  }, 5000)
+
+  it('sends the timeout with the spec 2025 listTools cache fill', async () => {
+    const { clientTransport } = await makeServerThatAnswersListOnce()
+    await using client = await createMCPClient({
+      transport: clientTransport,
+      requestOptions: { timeout: 50 },
+    })
+    // The raw walk gets the first answer. Only the cache fill is left
+    // unanswered, so only the 50 ms timeout can end it.
+    await expect(client.tools()).rejects.toThrow('Request timed out')
+  }, 5000)
+
+  it('restarts the timeout on progress with resetTimeoutOnProgress', async () => {
+    const { clientTransport, sawProgressToken } = await makeProgressServer()
+    await using client = await createMCPClient({
+      transport: clientTransport,
+      requestOptions: { timeout: 200, resetTimeoutOnProgress: true },
+    })
+    // The tool runs 300 ms and reports progress every 50 ms.
+    const result = await client.callTool('slow')
+    expect(result.content).toEqual([{ type: 'text', text: 'done' }])
+    // The client asked for progress, so the server could send it.
+    expect(sawProgressToken()).toBe(true)
+  })
+
+  it('times out a long tool without resetTimeoutOnProgress', async () => {
+    const { clientTransport } = await makeProgressServer()
+    await using client = await createMCPClient({
+      transport: clientTransport,
+      requestOptions: { timeout: 200 },
+    })
+    await expect(client.callTool('slow')).rejects.toThrow('Request timed out')
+  })
+
+  it('sends requestOptions with the execute of tools from client.tools()', async () => {
+    const { clientTransport } = await makeProgressServer()
+    await using client = await createMCPClient({
+      transport: clientTransport,
+      requestOptions: { timeout: 200 },
+    })
+    const [tool] = await client.tools()
+    await expect(
+      tool!.execute!({}, { toolCallId: 't', emitCustomEvent: () => {} }),
+    ).rejects.toThrow('Request timed out')
+  })
+
+  it('sends requestOptions with the execute of tools from client.tools([defs])', async () => {
+    const { clientTransport } = await makeProgressServer()
+    await using client = await createMCPClient({
+      transport: clientTransport,
+      requestOptions: { timeout: 200 },
+    })
+    const [tool] = await client.tools([
+      toolDefinition({
+        name: 'slow',
+        description: 'Slow tool',
+        inputSchema: z.object({}),
+      }),
+    ])
+    await expect(
+      tool!.execute!({}, { toolCallId: 't', emitCustomEvent: () => {} }),
+    ).rejects.toThrow('Request timed out')
+  })
+
+  it('reports requestOptions on getInfo so a rebuilt client keeps them', async () => {
+    const { clientTransport } = await makeServerWithWeatherTool()
+    await using client = await createMCPClient({
+      transport: clientTransport,
+      requestOptions: { timeout: 5000 },
+    })
+    expect(client.getInfo()).toStrictEqual({
+      transport: undefined,
+      prefix: undefined,
+      requestOptions: { timeout: 5000 },
+    })
+  })
+})
+
 // tools/list always returns a new cursor, so pagination never reaches the last page.
 async function makeServerWithUnendingToolList() {
   const [clientTransport, serverTransport] =
@@ -756,3 +854,74 @@ function isSubscriptionsListen(
     (typeof message.id === 'string' || typeof message.id === 'number')
   )
 }
+
+// A spec 2025 server that never answers a request after the handshake.
+async function makeSilentServer() {
+  const [clientTransport, serverTransport] =
+    InMemoryTransport.createLinkedPair()
+  const server = new Server(
+    { name: 'silent', version: '1.0.0' },
+    { capabilities: { tools: {}, resources: {}, prompts: {} } },
+  )
+  const never = () => new Promise<never>(() => {})
+  server.setRequestHandler('tools/list', never)
+  server.setRequestHandler('tools/call', never)
+  server.setRequestHandler('resources/list', never)
+  server.setRequestHandler('resources/read', never)
+  server.setRequestHandler('resources/templates/list', never)
+  server.setRequestHandler('prompts/list', never)
+  server.setRequestHandler('prompts/get', never)
+  await server.connect(serverTransport)
+  return { server, clientTransport }
+}
+
+// A spec 2025 server that answers the first tools/list and never answers again.
+async function makeServerThatAnswersListOnce() {
+  const [clientTransport, serverTransport] =
+    InMemoryTransport.createLinkedPair()
+  const server = new Server(
+    { name: 'answers-once', version: '1.0.0' },
+    { capabilities: { tools: {} } },
+  )
+  let calls = 0
+  server.setRequestHandler('tools/list', () => {
+    calls += 1
+    if (calls > 1) return new Promise<never>(() => {})
+    return {
+      tools: [{ name: 'slow', inputSchema: { type: 'object' as const } }],
+    }
+  })
+  await server.connect(serverTransport)
+  return { server, clientTransport }
+}
+
+// A spec 2025 tool that runs 300 ms. It reports progress every 50 ms when
+// the request carries a progressToken.
+async function makeProgressServer() {
+  const [clientTransport, serverTransport] =
+    InMemoryTransport.createLinkedPair()
+  const server = new Server(
+    { name: 'progress', version: '1.0.0' },
+    { capabilities: { tools: {} } },
+  )
+  let sawToken = false
+  server.setRequestHandler('tools/list', () => ({
+    tools: [{ name: 'slow', inputSchema: { type: 'object' as const } }],
+  }))
+  server.setRequestHandler('tools/call', async (_request, ctx) => {
+    const progressToken = ctx.mcpReq._meta?.progressToken
+    if (progressToken !== undefined) sawToken = true
+    for (let step = 1; step <= 6; step += 1) {
+      await new Promise((resolve) => setTimeout(resolve, 50))
+      if (progressToken !== undefined) {
+        await ctx.mcpReq.notify({
+          method: 'notifications/progress',
+          params: { progressToken, progress: step, total: 6 },
+        })
+      }
+    }
+    return { content: [{ type: 'text' as const, text: 'done' }] }
+  })
+  await server.connect(serverTransport)
+  return { server, clientTransport, sawProgressToken: () => sawToken }
+}
diff --git a/packages/ai-mcp/tests/connector-edges.test.ts b/packages/ai-mcp/tests/connector-edges.test.ts
index 8c51507a3a..690343a74a 100644
--- a/packages/ai-mcp/tests/connector-edges.test.ts
+++ b/packages/ai-mcp/tests/connector-edges.test.ts
@@ -499,4 +499,52 @@ describe('mcpConnector client options', () => {
     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/pool.test.ts b/packages/ai-mcp/tests/pool.test.ts
index 4d996c5211..fadd097bb5 100644
--- a/packages/ai-mcp/tests/pool.test.ts
+++ b/packages/ai-mcp/tests/pool.test.ts
@@ -238,6 +238,23 @@ describe('createMCPClients', () => {
     })
     await expect(pool.tools()).rejects.toThrow(DuplicateToolNameError)
   })
+
+  it('reports each server requestOptions on getServers()', async () => {
+    const a = await makeServerWithWeatherTool()
+    await using pool = await createMCPClients({
+      alpha: {
+        transport: a.clientTransport,
+        requestOptions: { timeout: 5000 },
+      },
+    })
+    expect(pool.getServers()).toStrictEqual({
+      alpha: {
+        transport: undefined,
+        prefix: 'alpha',
+        requestOptions: { timeout: 5000 },
+      },
+    })
+  })
 })
 
 // The server has no public setter for the negotiated era, so the test sets it.
diff --git a/packages/ai-mcp/tests/tools.test.ts b/packages/ai-mcp/tests/tools.test.ts
index 50ed761b4a..e5034efc93 100644
--- a/packages/ai-mcp/tests/tools.test.ts
+++ b/packages/ai-mcp/tests/tools.test.ts
@@ -555,6 +555,45 @@ describe('makeMcpExecute', () => {
     )
   })
 
+  it('sends requestOptions with the abortSignal to client.callTool', async () => {
+    const callTool = vi
+      .fn()
+      .mockResolvedValue({ content: [{ type: 'text', text: 'ok' }] })
+    const controller = new AbortController()
+    const execute = makeMcpExecute(fakeMcpClient(callTool), 'x', false, false, {
+      timeout: 5000,
+      resetTimeoutOnProgress: true,
+    })
+    await expect(execute({}, { abortSignal: controller.signal })).resolves.toBe(
+      'ok',
+    )
+    expect(callTool).toHaveBeenCalledWith(
+      { name: 'x', arguments: {} },
+      {
+        timeout: 5000,
+        resetTimeoutOnProgress: true,
+        // The SDK asks the server for progress only with an onprogress callback.
+        onprogress: expect.any(Function),
+        signal: controller.signal,
+        allowInputRequired: true,
+      },
+    )
+  })
+
+  it('adds no onprogress when resetTimeoutOnProgress is not set', async () => {
+    const callTool = vi
+      .fn()
+      .mockResolvedValue({ content: [{ type: 'text', text: 'ok' }] })
+    const execute = makeMcpExecute(fakeMcpClient(callTool), 'x', false, false, {
+      timeout: 5000,
+    })
+    await execute({})
+    expect(callTool).toHaveBeenCalledWith(
+      { name: 'x', arguments: {} },
+      { timeout: 5000, allowInputRequired: true },
+    )
+  })
+
   it('rejects without calling the server when the signal is already aborted', async () => {
     const callTool = vi.fn()
     const client = fakeMcpClient(callTool)
@@ -1012,6 +1051,30 @@ describe('callMcpTool — spec 2026 raw requests', () => {
     }
   })
 
+  it('uses the requestOptions timeout', async () => {
+    vi.useFakeTimers()
+    try {
+      const { client } = scriptedModernClient(() => [])
+      const outcome = callMcpTool(
+        client,
+        'ask',
+        {},
+        false,
+        undefined,
+        undefined,
+        {
+          timeout: 1000,
+        },
+      ).catch((error: unknown) => error)
+      await vi.advanceTimersByTimeAsync(1000)
+      const error = await outcome
+      expect(error).toBeInstanceOf(Error)
+      expect(String(error)).toContain('timed out after 1000 ms')
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
   it('reads every input request shape', async () => {
     const call = (result: unknown) =>
       callMcpTool(
@@ -1188,6 +1251,23 @@ describe('callMcpTool — spec 2025 task replies', () => {
     )
   })
 
+  it('sends requestOptions with the task tools/call', async () => {
+    const seen: Array<unknown> = []
+    const client = {
+      getProtocolEra: () => 'legacy',
+      async request(_rpc: unknown, _schema: unknown, options?: unknown) {
+        seen.push(options)
+        return okResult
+      },
+    } as unknown as Client
+    await expect(
+      callMcpTool(client, 'job', {}, true, undefined, undefined, {
+        timeout: 5000,
+      }),
+    ).resolves.toEqual(okResult)
+    expect(seen).toEqual([{ timeout: 5000 }])
+  })
+
   it('throws the abort reason when the request fails after an abort', async () => {
     const controller = new AbortController()
     const client = scriptedLegacyClient({

From a5c8616221c640c058ff1fb7f38b6b7cae003518 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 3 Oct 2026 18:09:19 +0200
Subject: [PATCH 201/286] feat(ai-mcp): accept a strict list of tool names in
 toolFilter

toolFilter also takes a list of server tool names. The client keeps exactly those tools, in list order. A missing or repeated name throws the new MCPToolFilterError, which names them and the available tools. A listed task-required tool on a server without task support throws MCPTaskRequiredToolError. An empty list keeps no tools. A function filter works as before.
---
 packages/ai-mcp/src/client.ts             | 54 +++++++++++++-
 packages/ai-mcp/src/errors.ts             | 54 +++++++++++++-
 packages/ai-mcp/src/index.ts              |  1 +
 packages/ai-mcp/src/types.ts              | 20 ++++-
 packages/ai-mcp/tests/tool-policy.test.ts | 90 ++++++++++++++++++++++-
 packages/ai-mcp/tests/types.test-d.ts     |  7 ++
 6 files changed, 215 insertions(+), 11 deletions(-)

diff --git a/packages/ai-mcp/src/client.ts b/packages/ai-mcp/src/client.ts
index 36a0f5480a..393f6a44de 100644
--- a/packages/ai-mcp/src/client.ts
+++ b/packages/ai-mcp/src/client.ts
@@ -3,6 +3,7 @@ import {
   DuplicateToolNameError,
   MCPConnectionError,
   MCPTaskRequiredToolError,
+  MCPToolFilterError,
   MCPToolNotFoundError,
 } from './errors'
 import { listPages } from './list-pages'
@@ -304,7 +305,11 @@ class MCPClientImpl<
 
     const { toolFilter, needsApproval, toolName, requestOptions } = this.#policy
     const listed = await this.#listTools()
-    const defs = toolFilter ? listed.filter((def) => toolFilter(def)) : listed
+    const defs = applyToolFilter(
+      listed,
+      toolFilter,
+      serverSupportsTaskCalls(this.#client),
+    )
 
     let tools: Array<McpServerTool>
     if (isDefs) {
@@ -480,6 +485,53 @@ function isArgs(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
+/**
+ * Applies the client `toolFilter` to the listed tools.
+ * A function keeps the tools it returns `true` for.
+ * A list keeps exactly the listed tools, in list order. A missing or
+ * repeated name throws `MCPToolFilterError`. A listed tool that needs a task
+ * on a server without task support throws `MCPTaskRequiredToolError`.
+ */
+function applyToolFilter(
+  listed: Array<McpToolDef>,
+  toolFilter: MCPClientOptions['toolFilter'],
+  supportsTasks: boolean,
+): Array<McpToolDef> {
+  if (toolFilter === undefined) return listed
+  if (typeof toolFilter === 'function') {
+    return listed.filter((def) => toolFilter(def))
+  }
+  const byName = new Map(listed.map((def) => [def.name, def]))
+  const seen = new Set<string>()
+  const repeated = new Set<string>()
+  const missing: Array<string> = []
+  const kept: Array<McpToolDef> = []
+  for (const name of toolFilter) {
+    if (seen.has(name)) {
+      repeated.add(name)
+      continue
+    }
+    seen.add(name)
+    const def = byName.get(name)
+    if (def === undefined) missing.push(name)
+    else kept.push(def)
+  }
+  if (missing.length > 0 || repeated.size > 0) {
+    throw new MCPToolFilterError({
+      missing,
+      repeated: [...repeated],
+      available: listed.map((def) => def.name),
+    })
+  }
+  const unsupported = kept.find(
+    (def) => requiresTaskExecution(def) && !supportsTasks,
+  )
+  if (unsupported !== undefined) {
+    throw new MCPTaskRequiredToolError(unsupported.name)
+  }
+  return kept
+}
+
 /**
  * Connects to an MCP server.
  *
diff --git a/packages/ai-mcp/src/errors.ts b/packages/ai-mcp/src/errors.ts
index 3a3713bfdb..c99937265d 100644
--- a/packages/ai-mcp/src/errors.ts
+++ b/packages/ai-mcp/src/errors.ts
@@ -19,10 +19,10 @@ export class DuplicateToolNameError extends Error {
 }
 
 /**
- * Thrown when a task-required tool is explicitly bound via `mcp.tools([...])`
- * or called via `callTool()` but the server does not declare the tasks
- * capability for tools/call, so the call could never execute.
- * (Auto-discovery silently skips such tools.)
+ * Thrown when a task-required tool is explicitly bound via `mcp.tools([...])`,
+ * called via `callTool()`, or named in a `toolFilter` list, but the server
+ * does not declare the tasks capability for tools/call, so the call could
+ * never execute. (Auto-discovery without a `toolFilter` list skips such tools.)
  */
 export class MCPTaskRequiredToolError extends Error {
   constructor(public readonly toolName: string) {
@@ -44,3 +44,49 @@ export class MCPToolNotFoundError extends Error {
     this.name = 'MCPToolNotFoundError'
   }
 }
+
+type ToolFilterDetails = {
+  /** Listed, but the server has no tool with this name. */
+  missing: Array<string>
+  /** Listed more than once. */
+  repeated: Array<string>
+  /** The server's tool names. */
+  available: Array<string>
+}
+
+function toolFilterMessage(details: ToolFilterDetails) {
+  const names = (list: Array<string>) =>
+    list.map((name) => `"${name}"`).join(', ')
+  const parts = ['The MCP client `toolFilter` list does not match the server.']
+  if (details.missing.length > 0) {
+    parts.push(`The server has no tool named ${names(details.missing)}.`)
+  }
+  if (details.repeated.length > 0) {
+    parts.push(`The list repeats ${names(details.repeated)}.`)
+  }
+  const available =
+    details.available.length > 0 ? names(details.available) : '(none)'
+  parts.push(`Available tools: ${available}.`)
+  return parts.join(' ')
+}
+
+/**
+ * Thrown by `tools()` when a `toolFilter` list names a tool that the server
+ * does not have, or names a tool more than once.
+ */
+export class MCPToolFilterError extends Error {
+  /** Listed, but the server has no tool with this name. */
+  readonly missing: Array<string>
+  /** Listed more than once. */
+  readonly repeated: Array<string>
+  /** The server's tool names. */
+  readonly available: Array<string>
+
+  constructor(details: ToolFilterDetails) {
+    super(toolFilterMessage(details))
+    this.name = 'MCPToolFilterError'
+    this.missing = details.missing
+    this.repeated = details.repeated
+    this.available = details.available
+  }
+}
diff --git a/packages/ai-mcp/src/index.ts b/packages/ai-mcp/src/index.ts
index 8b92dc4ed7..2d9ca9cb14 100644
--- a/packages/ai-mcp/src/index.ts
+++ b/packages/ai-mcp/src/index.ts
@@ -28,6 +28,7 @@ export {
   MCPConnectionError,
   DuplicateToolNameError,
   MCPTaskRequiredToolError,
+  MCPToolFilterError,
   MCPToolNotFoundError,
 } from './errors'
 export {
diff --git a/packages/ai-mcp/src/types.ts b/packages/ai-mcp/src/types.ts
index 664cfe1662..23759f2846 100644
--- a/packages/ai-mcp/src/types.ts
+++ b/packages/ai-mcp/src/types.ts
@@ -154,8 +154,15 @@ export interface MCPClientOptions {
     resetTimeoutOnProgress?: boolean
   }
   /**
-   * Return `false` to hide a server tool. Receives the raw MCP tool definition
-   * (native `name`, `title`, `annotations`). Default: every tool.
+   * Choose the server tools the model gets. Default: every tool.
+   *
+   * - A function: keep the tools it returns `true` for. It receives the raw
+   *   MCP tool definition (native `name`, `title`, `annotations`).
+   * - A list of server tool names: keep exactly these, in this order. A name
+   *   the server does not have, or a repeated name, throws
+   *   `MCPToolFilterError`. A listed tool that needs task execution, on a
+   *   server without task support, throws `MCPTaskRequiredToolError`. An
+   *   empty list keeps no tools.
    *
    * Applies to `tools()`, `chat({ mcp })`, and MCP Apps widget calls. In
    * `tools([...defs])` a hidden definition throws `MCPToolNotFoundError`.
@@ -163,13 +170,18 @@ export interface MCPClientOptions {
    * a security boundary.
    *
    * ```ts
-   * const mcp = await createMCPClient({
+   * const readOnly = await createMCPClient({
    *   transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
    *   toolFilter: (tool) => tool.annotations?.readOnlyHint === true,
    * })
+   *
+   * const listed = await createMCPClient({
+   *   transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+   *   toolFilter: ['search_issues', 'get_issue'],
+   * })
    * ```
    */
-  toolFilter?: (tool: McpToolDef) => boolean
+  toolFilter?: ((tool: McpToolDef) => boolean) | ReadonlyArray<string>
   /**
    * Return `true` to require user approval before a discovered tool runs.
    * Default: no approval. `tools([...defs])` keeps each definition's own
diff --git a/packages/ai-mcp/tests/tool-policy.test.ts b/packages/ai-mcp/tests/tool-policy.test.ts
index 87ee580cd4..066ca8f4fb 100644
--- a/packages/ai-mcp/tests/tool-policy.test.ts
+++ b/packages/ai-mcp/tests/tool-policy.test.ts
@@ -2,9 +2,13 @@ import { describe, expect, it } from 'vitest'
 import { toolDefinition } from '@tanstack/ai'
 import { z } from 'zod'
 import { createMCPClient } from '../src/client'
-import { MCPToolNotFoundError } from '../src/errors'
+import { MCPTaskRequiredToolError, MCPToolNotFoundError } from '../src/errors'
+import { MCPToolFilterError } from '../src'
 import { createMCPClients } from '../src/pool'
-import { makeServerWithMixedTools } from './helpers/in-memory-server'
+import {
+  makeServerWithMixedTools,
+  makeServerWithUnsupportedTaskTool,
+} from './helpers/in-memory-server'
 import type { McpTool } from '../src'
 
 const readOnly = (tool: McpTool) => tool.annotations?.readOnlyHint === true
@@ -70,6 +74,88 @@ describe('toolFilter', () => {
   })
 })
 
+describe('toolFilter list', () => {
+  it('keeps exactly the listed tools, in list order', async () => {
+    const { clientTransport } = await makeServerWithMixedTools()
+    await using client = await createMCPClient({
+      transport: clientTransport,
+      toolFilter: ['set_alert', 'get_weather'],
+    })
+    const names = (await client.tools()).map((t) => t.name)
+    expect(names).toEqual(['set_alert', 'get_weather'])
+  })
+
+  it('keeps no tools for an empty list, and does not throw', async () => {
+    const { clientTransport } = await makeServerWithMixedTools()
+    await using client = await createMCPClient({
+      transport: clientTransport,
+      toolFilter: [],
+    })
+    await expect(client.tools()).resolves.toEqual([])
+  })
+
+  it('throws MCPToolFilterError that names the missing tool and the available ones', async () => {
+    const { clientTransport } = await makeServerWithMixedTools()
+    await using client = await createMCPClient({
+      transport: clientTransport,
+      toolFilter: ['get_weather', 'delete_city'],
+    })
+    const error: unknown = await client.tools().catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(MCPToolFilterError)
+    if (!(error instanceof MCPToolFilterError)) {
+      throw new Error('expected MCPToolFilterError')
+    }
+    expect(error.missing).toEqual(['delete_city'])
+    expect(error.repeated).toEqual([])
+    expect([...error.available].sort()).toEqual(['get_weather', 'set_alert'])
+    expect(error.message).toContain('"delete_city"')
+    expect(error.message).toContain('"get_weather"')
+    expect(error.message).toContain('"set_alert"')
+  })
+
+  it('throws MCPToolFilterError that names a repeated tool', async () => {
+    const { clientTransport } = await makeServerWithMixedTools()
+    await using client = await createMCPClient({
+      transport: clientTransport,
+      toolFilter: ['get_weather', 'get_weather', 'get_weather'],
+    })
+    const error: unknown = await client.tools().catch((e: unknown) => e)
+    if (!(error instanceof MCPToolFilterError)) {
+      throw new Error('expected MCPToolFilterError')
+    }
+    expect(error.missing).toEqual([])
+    expect(error.repeated).toEqual(['get_weather'])
+    expect(error.message).toContain('repeats "get_weather"')
+  })
+
+  it('throws MCPTaskRequiredToolError for a listed tool that needs a task the server cannot run', async () => {
+    const { clientTransport } = await makeServerWithUnsupportedTaskTool()
+    await using client = await createMCPClient({
+      transport: clientTransport,
+      toolFilter: ['plain_tool', 'needs_tasks'],
+    })
+    await expect(client.tools()).rejects.toBeInstanceOf(
+      MCPTaskRequiredToolError,
+    )
+  })
+
+  it('throws MCPToolNotFoundError for an explicit definition the list hides', async () => {
+    const { clientTransport } = await makeServerWithMixedTools()
+    await using client = await createMCPClient({
+      transport: clientTransport,
+      toolFilter: ['get_weather'],
+    })
+    const setAlert = toolDefinition({
+      name: 'set_alert',
+      description: 'Create a weather alert',
+      inputSchema: z.object({ city: z.string() }),
+    })
+    await expect(client.tools([setAlert])).rejects.toBeInstanceOf(
+      MCPToolNotFoundError,
+    )
+  })
+})
+
 describe('needsApproval', () => {
   it('leaves discovered tools without approval by default', async () => {
     const { clientTransport } = await makeServerWithMixedTools()
diff --git a/packages/ai-mcp/tests/types.test-d.ts b/packages/ai-mcp/tests/types.test-d.ts
index 8cddd56ebe..e41bec3f8d 100644
--- a/packages/ai-mcp/tests/types.test-d.ts
+++ b/packages/ai-mcp/tests/types.test-d.ts
@@ -141,3 +141,10 @@ const policy: MCPClientOptions = {
   needsApproval: (tool) => tool.annotations?.destructiveHint !== false,
 }
 void policy
+
+// A list of server tool names also works.
+const listPolicy: MCPClientOptions = {
+  transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+  toolFilter: ['search_issues', 'get_issue'],
+}
+void listPolicy

From f80e249981bc4316e04223e7fbf0b02a586e6112 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 3 Oct 2026 18:13:03 +0200
Subject: [PATCH 202/286] feat(ai-compaction): count tokens with the reported
 usage

Add countTokens: 'usage' to withCompaction. The middleware saves the usage of each model call with the length of the list it got and a hash of its last message. The next check counts that usage plus the estimate of the messages after the reply. It uses the estimate when the usage does not fit the list, and it uses the usage of a compacted view only when the call reuses that checkpoint. The usage is kept in the same store as the checkpoint: the MetadataStore when one exists with a strategy key, so a restart can use it, else memory (capped at the 1000 newest threads). In usage mode a run with no store keeps its checkpoint in memory, so a provider-only compaction stays in place.
---
 packages/ai-compaction/src/index.test.ts  | 359 ++++++++++++++++++++++
 packages/ai-compaction/src/index.ts       |  84 ++++-
 packages/ai-compaction/src/usage-count.ts | 116 +++++++
 3 files changed, 542 insertions(+), 17 deletions(-)
 create mode 100644 packages/ai-compaction/src/usage-count.ts

diff --git a/packages/ai-compaction/src/index.test.ts b/packages/ai-compaction/src/index.test.ts
index db220a521a..8c9f91c722 100644
--- a/packages/ai-compaction/src/index.test.ts
+++ b/packages/ai-compaction/src/index.test.ts
@@ -4,6 +4,7 @@ import type {
   ChatMiddlewareContext,
   MetadataStore,
   ModelMessage,
+  TokenUsage,
   ToolCall,
 } from '@tanstack/ai'
 import { provideMetadata } from '@tanstack/ai'
@@ -18,6 +19,7 @@ import {
   summarizeOldest,
   withCompaction,
 } from './index'
+import { countFromUsage, hashMessages, memoryMetadata } from './usage-count'
 
 interface RecordedCustom {
   name: string
@@ -541,3 +543,360 @@ describe('estimateMessageTokens', () => {
     expect(estimateMessageTokens(text('user', 'x'.repeat(40)))).toBe(10)
   })
 })
+
+/** A beforeModel context of thread-1 whose `messages` are `messages`. */
+function usageContext(
+  messages: ReadonlyArray<ModelMessage>,
+  extras: Partial<ChatMiddlewareContext> = {},
+) {
+  return recordingContext('beforeModel', {
+    threadId: 'thread-1',
+    messages,
+    ...extras,
+  })
+}
+
+const tokenUsage = (
+  promptTokens: number,
+  completionTokens = 0,
+): TokenUsage => ({
+  promptTokens,
+  completionTokens,
+  totalTokens: promptTokens + completionTokens,
+})
+
+describe('countTokens: usage', () => {
+  it('counts the reported usage and the messages after the reply', async () => {
+    const onCompact = vi.fn()
+    const mw = withCompaction({
+      maxTokens: 200,
+      countTokens: 'usage',
+      onCompact,
+    })
+    const first = [big('user'), big('assistant'), big('user')]
+    // No usage yet: the estimate (120) is under the limit.
+    expect(
+      await runOnConfig(mw, first, usageContext(first).ctx),
+    ).toBeUndefined()
+    await mw.onUsage?.(usageContext(first).ctx, tokenUsage(150, 40))
+
+    // The estimate is 180, but the usage count is 150 + 40 + 20 = 210.
+    const second = [...first, big('assistant'), text('user', 'x'.repeat(80))]
+    const { ctx, events } = usageContext(second)
+    await runOnConfig(mw, second, ctx)
+
+    expect(events[0]?.name).toBe(COMPACTION_STARTED_EVENT)
+    expect(events[0]?.value.before).toBe(210)
+    expect(onCompact).toHaveBeenCalledOnce()
+  })
+
+  it('uses the estimate when the last covered message changed or the list is shorter', async () => {
+    const mw = withCompaction({ maxTokens: 200, countTokens: 'usage' })
+    const first = [big('user'), big('assistant'), big('user')]
+    await mw.onUsage?.(usageContext(first).ctx, tokenUsage(150, 40))
+
+    const edited = [
+      big('user'),
+      big('assistant'),
+      text('user', 'edited'),
+      big('assistant'),
+      text('user', 'x'.repeat(80)),
+    ]
+    const editedCall = usageContext(edited)
+    expect(await runOnConfig(mw, edited, editedCall.ctx)).toBeUndefined()
+    expect(editedCall.events).toEqual([])
+
+    const shorter = [big('user'), big('assistant')]
+    const shorterCall = usageContext(shorter)
+    expect(await runOnConfig(mw, shorter, shorterCall.ctx)).toBeUndefined()
+    expect(shorterCall.events).toEqual([])
+  })
+
+  it('does not compact again after a provider-only compaction only because the canonical list is long', async () => {
+    const summarize = vi.fn(async () => 'the gist')
+    const mw = withCompaction({
+      maxTokens: 100,
+      countTokens: 'usage',
+      strategy: summarizeOldest({ summarize, keepRecentTokens: 50 }),
+    })
+    const first = [big('user'), big('assistant'), big('user'), big('assistant')]
+    const firstCall = usageContext(first)
+    const compacted = await runOnConfig(mw, first, firstCall.ctx)
+    expect(compacted?.providerMessages?.[0]?.content).toContain('the gist')
+    // The model got the short list, so its usage is small.
+    await mw.onUsage?.(firstCall.ctx, tokenUsage(30, 5))
+
+    // The canonical list is long (estimate 201). The count is 30 + 5 + 1 = 36.
+    // The estimate of the reused view is 100, so only the usage gives 36.
+    const second = [...first, big('assistant'), text('user', 'next')]
+    const { ctx, events } = usageContext(second)
+    const result = await runOnConfig(mw, second, ctx)
+
+    expect(summarize).toHaveBeenCalledOnce()
+    expect(events[0]?.value.before).toBe(36)
+    // The model still gets the compacted list, from the checkpoint in memory.
+    expect(result?.providerMessages?.[0]?.content).toContain('the gist')
+    expect(result?.providerMessages?.at(-1)?.content).toBe('next')
+  })
+
+  it('drops the saved usage after a compaction, so a call with no usage reuses the checkpoint', async () => {
+    const summarize = vi.fn(async () => 'the gist')
+    const mw = withCompaction({
+      maxTokens: 100,
+      countTokens: 'usage',
+      strategy: summarizeOldest({ summarize, keepRecentTokens: 50 }),
+    })
+    const first = [big('user')]
+    await mw.onUsage?.(usageContext(first).ctx, tokenUsage(40, 40))
+
+    // The count is 40 + 40 + 40 = 120, so this call compacts. The call is
+    // aborted, so it reports no usage.
+    const second = [...first, big('assistant'), big('user')]
+    const compacted = await runOnConfig(mw, second, usageContext(second).ctx)
+    expect(compacted?.providerMessages?.[0]?.content).toContain('the gist')
+
+    // The old usage counted the list before the compaction (122 here). With
+    // no usage, the estimate of the reused view (61) counts.
+    const third = [...second, text('assistant', 'ok'), text('user', 'next')]
+    const { ctx, events } = usageContext(third)
+    const result = await runOnConfig(mw, third, ctx)
+
+    expect(summarize).toHaveBeenCalledOnce()
+    expect(events[0]?.value).toMatchObject({
+      before: 61,
+      reusedCheckpoint: true,
+    })
+    expect(result?.providerMessages?.[0]?.content).toContain('the gist')
+  })
+
+  it('keeps the usage with the checkpoint when the strategy has no key', async () => {
+    const store = memoryStore()
+    // A strategy with no key keeps its checkpoint in the middleware's memory.
+    const strategy = evictOldest({
+      keepRecentTokens: 50,
+      marker: (count) => `[${count} dropped]`,
+    })
+    const first = [big('user'), big('assistant'), big('user'), big('assistant')]
+    const firstCtx = checkpointContext(store)
+    firstCtx.messages = first
+    const firstMw = withCompaction({
+      maxTokens: 100,
+      countTokens: 'usage',
+      strategy,
+    })
+    expect(await runOnConfig(firstMw, first, firstCtx)).toBeDefined()
+    // The model got the short list, so its usage is small.
+    await firstMw.onUsage?.(firstCtx, tokenUsage(30, 5))
+    expect(
+      await store.get('@tanstack/ai-compaction:usage', 'thread-1'),
+    ).toBeNull()
+
+    // A new middleware per request has no checkpoint. The usage of the
+    // compacted view does not fit, so the estimate (201) counts.
+    const onCompact = vi.fn()
+    const second = [...first, big('assistant'), text('user', 'next')]
+    const result = await runOnConfig(
+      withCompaction({
+        maxTokens: 100,
+        countTokens: 'usage',
+        strategy,
+        onCompact,
+      }),
+      second,
+      checkpointContext(store),
+    )
+
+    expect(onCompact.mock.calls[0]?.[0].before).toBe(201)
+    expect(result?.providerMessages?.length).toBeLessThan(second.length)
+  })
+
+  it('reads the usage from the store it was saved in when the strategy has no key', async () => {
+    const store = memoryStore()
+    const mw = withCompaction({
+      maxTokens: 100,
+      countTokens: 'usage',
+      strategy: evictOldest({
+        keepRecentTokens: 50,
+        marker: (count) => `[${count} dropped]`,
+      }),
+    })
+    const first = [big('user'), big('assistant'), big('user'), big('assistant')]
+    const firstCtx = checkpointContext(store)
+    firstCtx.messages = first
+    expect(await runOnConfig(mw, first, firstCtx)).toBeDefined()
+    await mw.onUsage?.(firstCtx, tokenUsage(30, 5))
+
+    // The usage is in the memory of this middleware, not in the store. The
+    // count is 30 + 5 + 1 = 36. The estimate of the reused view is 84.
+    const second = [...first, big('assistant'), text('user', 'next')]
+    const ctx = checkpointContext(store)
+    const emit = vi.spyOn(ctx, 'emitCustomEvent')
+    await runOnConfig(mw, second, ctx)
+
+    expect(emit.mock.calls[0]?.[1]).toMatchObject({
+      before: 36,
+      reusedCheckpoint: true,
+    })
+  })
+
+  it('does not use the usage of a compacted view when the checkpoint does not fit', async () => {
+    const store = memoryStore()
+    const summarize = vi.fn(async () => 'the gist')
+    const onCompact = vi.fn()
+    const mw = withCompaction({
+      maxTokens: 100,
+      countTokens: 'usage',
+      strategy: summarizeOldest({ summarize, keepRecentTokens: 50 }),
+      onCompact,
+    })
+    const first = [big('user'), big('assistant'), big('user'), big('assistant')]
+    const firstCtx = checkpointContext(store)
+    firstCtx.messages = first
+    await runOnConfig(mw, first, firstCtx)
+    // The model got the short list, so its usage is small.
+    await mw.onUsage?.(firstCtx, tokenUsage(30, 5))
+
+    // An earlier message changed (for example, a run tag from persistence).
+    // The checkpoint does not fit, but the last covered message is the same.
+    const second = [
+      big('user'),
+      text('assistant', 'y'.repeat(160)),
+      big('user'),
+      big('assistant'),
+      big('assistant'),
+      text('user', 'next'),
+    ]
+    const result = await runOnConfig(mw, second, checkpointContext(store))
+
+    // The estimate (201) counts, not the usage of the compacted view (36).
+    expect(onCompact.mock.calls[1]?.[0].before).toBe(201)
+    expect(summarize).toHaveBeenCalledTimes(2)
+    expect(result?.providerMessages?.length).toBeLessThan(second.length)
+  })
+
+  it('marks the usage of a reused checkpoint as a compacted view', async () => {
+    const store = memoryStore()
+    const summarize = vi.fn(async () => 'the gist')
+    const onCompact = vi.fn()
+    const mw = withCompaction({
+      maxTokens: 100,
+      countTokens: 'usage',
+      strategy: summarizeOldest({ summarize, keepRecentTokens: 50 }),
+      onCompact,
+    })
+    const first = [big('user'), big('assistant'), big('user'), big('assistant')]
+    await runOnConfig(mw, first, checkpointContext(store))
+
+    // This call reuses the checkpoint, so the model gets the compacted view.
+    const second = [...first, text('user', 'next')]
+    const secondCtx = checkpointContext(store)
+    secondCtx.messages = second
+    expect(
+      (await runOnConfig(mw, second, secondCtx))?.providerMessages?.[0]
+        ?.content,
+    ).toContain('the gist')
+    await mw.onUsage?.(secondCtx, tokenUsage(30, 5))
+
+    // The checkpoint does not fit, so the usage of that view (37) does not
+    // count. The estimate (203) counts, and the call compacts again.
+    const third = [
+      big('user'),
+      text('assistant', 'y'.repeat(160)),
+      big('user'),
+      big('assistant'),
+      text('user', 'next'),
+      big('assistant'),
+      text('user', 'again'),
+    ]
+    await runOnConfig(mw, third, checkpointContext(store))
+    expect(onCompact).toHaveBeenCalledTimes(2)
+  })
+
+  it('uses the last good usage after an aborted call, and the estimate when there is none', async () => {
+    const mw = withCompaction({ maxTokens: 200, countTokens: 'usage' })
+    // The first call was aborted, so no usage exists. The estimate (120) counts.
+    const first = [big('user'), big('assistant'), big('user')]
+    await expect(
+      runOnConfig(mw, first, usageContext(first).ctx),
+    ).resolves.toBeUndefined()
+
+    // A call that ends saves its usage.
+    const second = [...first, big('assistant'), big('user')]
+    await mw.onUsage?.(usageContext(second).ctx, tokenUsage(150, 10))
+
+    // The next call is aborted. A late report under the aborted signal is ignored.
+    const third = [...second, big('assistant'), text('user', 'x'.repeat(200))]
+    await mw.onUsage?.(
+      usageContext(third, { signal: AbortSignal.abort() }).ctx,
+      tokenUsage(5, 0),
+    )
+
+    // The count is the last good usage, 150 + 10, plus 50 for the new message.
+    const { ctx, events } = usageContext(third)
+    await expect(runOnConfig(mw, third, ctx)).resolves.toBeDefined()
+    expect(events[0]?.value.before).toBe(210)
+  })
+
+  it('saves the usage in the MetadataStore, so a restart can use it', async () => {
+    const store = memoryStore()
+    const covered = [big('user')]
+    const ctx = checkpointContext(store)
+    ctx.messages = covered
+    await withCompaction({ maxTokens: 200, countTokens: 'usage' }).onUsage?.(
+      ctx,
+      tokenUsage(150, 10),
+    )
+    expect(
+      await store.get('@tanstack/ai-compaction:usage', 'thread-1'),
+    ).toEqual({
+      schemaVersion: 1,
+      tokens: 160,
+      coveredCount: 1,
+      lastCoveredHash: expect.any(String),
+      compacted: false,
+    })
+
+    // A new middleware (a restart) reads the saved usage.
+    const onCompact = vi.fn()
+    const next = [...covered, big('assistant'), text('user', 'x'.repeat(200))]
+    await runOnConfig(
+      withCompaction({ maxTokens: 200, countTokens: 'usage', onCompact }),
+      next,
+      checkpointContext(store),
+    )
+    expect(onCompact.mock.calls[0]?.[0].before).toBe(210)
+  })
+
+  it('ignores a saved usage that has no compacted field', async () => {
+    const messages = [big('user'), text('user', 'next')]
+    const saved = {
+      schemaVersion: 1,
+      tokens: 10,
+      coveredCount: 1,
+      lastCoveredHash: await hashMessages([big('user')]),
+    }
+    const count = (value: unknown) =>
+      countFromUsage(value, messages, estimateMessageTokens, false)
+
+    expect(await count({ ...saved, compacted: false })).toBe(11)
+    expect(await count(saved)).toBeUndefined()
+  })
+
+  it('keeps the 1000 newest threads in memory', async () => {
+    const store = memoryMetadata()
+    for (let thread = 0; thread < 1000; thread++) {
+      await store.set('ns', String(thread), thread)
+    }
+    // A new value moves thread 0 to the newest place.
+    await store.set('ns', '0', 'again')
+    await store.set('ns', '1000', 1000)
+
+    expect(await store.get('ns', '0')).toBe('again')
+    expect(await store.get('ns', '1')).toBeNull()
+    expect(await store.get('ns', '1000')).toBe(1000)
+  })
+
+  it('keeps the estimate and adds no onUsage hook without countTokens', () => {
+    expect(withCompaction({ maxTokens: 100 }).onUsage).toBeUndefined()
+  })
+})
diff --git a/packages/ai-compaction/src/index.ts b/packages/ai-compaction/src/index.ts
index e467ecfa09..2d625061ac 100644
--- a/packages/ai-compaction/src/index.ts
+++ b/packages/ai-compaction/src/index.ts
@@ -13,6 +13,13 @@
  * `messages`.
  */
 import { MetadataCapability, getMetadata } from '@tanstack/ai'
+import {
+  USAGE_NAMESPACE,
+  countFromUsage,
+  hashMessages,
+  memoryMetadata,
+  toUsageCount,
+} from './usage-count'
 import type {
   ChatMiddleware,
   ChatMiddlewareContext,
@@ -115,16 +122,6 @@ function identifyStrategy(
   return strategy
 }
 
-async function hashMessages(
-  messages: ReadonlyArray<ModelMessage>,
-): Promise<string> {
-  const bytes = new TextEncoder().encode(JSON.stringify(messages))
-  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes)
-  return Array.from(new Uint8Array(digest), (byte) =>
-    byte.toString(16).padStart(2, '0'),
-  ).join('')
-}
-
 function isModelMessage(value: unknown): value is ModelMessage {
   return (
     typeof value === 'object' &&
@@ -275,6 +272,14 @@ export interface CompactionOptions {
   strategyKey?: string
   /** Observe each compaction (logging, metrics). */
   onCompact?: (info: CompactionInfo) => void
+  /**
+   * How to count the tokens of the list. `'usage'`: the usage the provider
+   * reported for the last model call, plus the estimate of each message after
+   * its reply. The estimate counts when no saved usage fits the list. The
+   * strategies still use the estimate to choose the cut. Default
+   * `'estimate'`.
+   */
+  countTokens?: 'estimate' | 'usage'
 }
 
 const sum = (
@@ -473,6 +478,20 @@ export function withCompaction(options: CompactionOptions): ChatMiddleware {
   const checkpointStrategyKey = strategyKey
     ? `${strategyKey}:maxTokens=${options.maxTokens}`
     : undefined
+  const countUsage = options.countTokens === 'usage'
+  const memory = memoryMetadata()
+  // The store of the checkpoint and of the usage. With countTokens: 'usage',
+  // a run with no store, or a strategy with no key, uses the memory of this
+  // middleware. Then the next call reuses the compacted list, and the saved
+  // usage fits that list.
+  const storeOf = (ctx: ChatMiddlewareContext) => {
+    const shared = getMetadata(ctx, { optional: true })
+    if (shared && checkpointStrategyKey) return shared
+    return countUsage ? memory : undefined
+  }
+  // True when the last model call of a run got a compacted view. The usage of
+  // that view fits a later call only when that call reuses the checkpoint.
+  const compactedViews = new WeakMap<ChatMiddlewareContext, boolean>()
 
   return {
     name: 'compaction',
@@ -485,15 +504,16 @@ export function withCompaction(options: CompactionOptions): ChatMiddleware {
       const startedAt = Date.now()
       const { messages } = config
       const inputMessages = config.providerMessages ?? messages
-      const metadata = getMetadata(ctx, { optional: true })
+      const metadata = storeOf(ctx)
+      const checkpointKey = checkpointStrategyKey ?? 'memory'
       let workingMessages = inputMessages
       let reusedCheckpoint = false
 
-      if (metadata && checkpointStrategyKey && inputMessages === messages) {
+      if (metadata && inputMessages === messages) {
         const stored = await metadata.get(CHECKPOINT_NAMESPACE, ctx.threadId)
         if (
           isCompactionCheckpoint(stored) &&
-          stored.strategyKey === checkpointStrategyKey &&
+          stored.strategyKey === checkpointKey &&
           stored.sourceMessageCount <= messages.length &&
           stored.sourceHash ===
             (await hashMessages(messages.slice(0, stored.sourceMessageCount)))
@@ -505,8 +525,20 @@ export function withCompaction(options: CompactionOptions): ChatMiddleware {
           reusedCheckpoint = true
         }
       }
-
-      const before = sum(workingMessages, estimate)
+      // A reused checkpoint is always given to the model. A new compaction
+      // sets this again below.
+      compactedViews.set(ctx, reusedCheckpoint)
+
+      const fromUsage =
+        countUsage && metadata
+          ? await countFromUsage(
+              await metadata.get(USAGE_NAMESPACE, ctx.threadId),
+              messages,
+              estimate,
+              reusedCheckpoint,
+            )
+          : undefined
+      const before = fromUsage ?? sum(workingMessages, estimate)
       const startedValue: CompactionStartedEventValue = {
         before,
         messagesBefore: workingMessages.length,
@@ -599,12 +631,17 @@ export function withCompaction(options: CompactionOptions): ChatMiddleware {
           : {}),
       })
 
-      if (metadata && checkpointStrategyKey && inputMessages === messages) {
+      if (countUsage) {
+        // The saved usage counted the list before this compaction.
+        await metadata?.delete(USAGE_NAMESPACE, ctx.threadId)
+      }
+
+      if (metadata && inputMessages === messages) {
         const checkpoint: CompactionCheckpoint = {
           schemaVersion: 1,
           sourceMessageCount: messages.length,
           sourceHash: await hashMessages(messages),
-          strategyKey: checkpointStrategyKey,
+          strategyKey: checkpointKey,
           compactedMessages: next,
         }
         if (!ctx.signal?.aborted) {
@@ -612,7 +649,20 @@ export function withCompaction(options: CompactionOptions): ChatMiddleware {
         }
       }
 
+      compactedViews.set(ctx, true)
       return { providerMessages: next }
     },
+    onUsage: countUsage
+      ? async (ctx, usage) => {
+          const saved = await toUsageCount(
+            ctx.messages,
+            usage,
+            compactedViews.get(ctx) ?? false,
+          )
+          // A cancelled call keeps the last good usage.
+          if (!saved || ctx.signal?.aborted) return
+          await storeOf(ctx)?.set(USAGE_NAMESPACE, ctx.threadId, saved)
+        }
+      : undefined,
   }
 }
diff --git a/packages/ai-compaction/src/usage-count.ts b/packages/ai-compaction/src/usage-count.ts
new file mode 100644
index 0000000000..b43eacd71e
--- /dev/null
+++ b/packages/ai-compaction/src/usage-count.ts
@@ -0,0 +1,116 @@
+import type { MetadataStore, ModelMessage, TokenUsage } from '@tanstack/ai'
+
+/** The MetadataStore namespace of the saved usage. The key is the thread id. */
+export const USAGE_NAMESPACE = '@tanstack/ai-compaction:usage'
+
+/** The usage of the last model call of a thread, and the list it got. */
+export interface UsageCount {
+  schemaVersion: 1
+  /** `promptTokens + completionTokens` of the call. */
+  tokens: number
+  /** How many messages the call got. Its reply comes after them. */
+  coveredCount: number
+  /** The hash of the last message the call got. */
+  lastCoveredHash: string
+  /** True when the call got a compacted view, not the canonical list. */
+  compacted: boolean
+}
+
+export async function hashMessages(
+  messages: ReadonlyArray<ModelMessage>,
+): Promise<string> {
+  const bytes = new TextEncoder().encode(JSON.stringify(messages))
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes)
+  return Array.from(new Uint8Array(digest), (byte) =>
+    byte.toString(16).padStart(2, '0'),
+  ).join('')
+}
+
+function isUsageCount(value: unknown): value is UsageCount {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'schemaVersion' in value &&
+    value.schemaVersion === 1 &&
+    'tokens' in value &&
+    typeof value.tokens === 'number' &&
+    'coveredCount' in value &&
+    typeof value.coveredCount === 'number' &&
+    Number.isInteger(value.coveredCount) &&
+    value.coveredCount >= 1 &&
+    'lastCoveredHash' in value &&
+    typeof value.lastCoveredHash === 'string' &&
+    'compacted' in value &&
+    typeof value.compacted === 'boolean'
+  )
+}
+
+/** The saved usage of a call that got `covered`. `undefined` for an empty list. */
+export async function toUsageCount(
+  covered: ReadonlyArray<ModelMessage>,
+  usage: TokenUsage,
+  compacted: boolean,
+): Promise<UsageCount | undefined> {
+  const last = covered.at(-1)
+  if (!last) return undefined
+  return {
+    schemaVersion: 1,
+    tokens: usage.promptTokens + usage.completionTokens,
+    coveredCount: covered.length,
+    lastCoveredHash: await hashMessages([last]),
+    compacted,
+  }
+}
+
+/**
+ * The token count of `messages` from a saved usage: the usage, plus the
+ * estimate of each message after the reply. `undefined` when the usage does
+ * not fit: none is saved, the list is shorter, the last covered message
+ * changed (a compaction or an edit), or the usage is of a compacted view and
+ * this call does not reuse the checkpoint of that view.
+ */
+export async function countFromUsage(
+  saved: unknown,
+  messages: ReadonlyArray<ModelMessage>,
+  estimate: (message: ModelMessage) => number,
+  reusedCheckpoint: boolean,
+): Promise<number | undefined> {
+  if (
+    !isUsageCount(saved) ||
+    (saved.compacted && !reusedCheckpoint) ||
+    messages.length < saved.coveredCount
+  ) {
+    return undefined
+  }
+  const last = messages[saved.coveredCount - 1]
+  if (!last || (await hashMessages([last])) !== saved.lastCoveredHash) {
+    return undefined
+  }
+  // completionTokens counts the reply. One reply can be more than one
+  // assistant message.
+  let start = saved.coveredCount
+  while (messages[start]?.role === 'assistant') start += 1
+  return messages
+    .slice(start)
+    .reduce((total, message) => total + estimate(message), saved.tokens)
+}
+
+/** A MetadataStore in memory, for a run that has none. The key is the thread. */
+export function memoryMetadata(): MetadataStore {
+  const threads = new Map<string, Map<string, unknown>>()
+  return {
+    get: async (namespace, key) => threads.get(key)?.get(namespace) ?? null,
+    set: async (namespace, key, value) => {
+      const values = threads.get(key) ?? new Map<string, unknown>()
+      // Delete, then set, so the thread moves to the newest place.
+      threads.delete(key)
+      threads.set(key, values.set(namespace, value))
+      // ponytail: keeps the 1000 newest threads; use a MetadataStore for more
+      const [oldest] = threads.keys()
+      if (threads.size > 1000 && oldest !== undefined) threads.delete(oldest)
+    },
+    delete: async (namespace, key) => {
+      threads.get(key)?.delete(namespace)
+    },
+  }
+}

From 1e89fafbddb75ddd1d90079963abd70f0847f061 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 3 Oct 2026 18:16:37 +0200
Subject: [PATCH 203/286] test(ai-harness): check compaction-style records from
 a middleware

A middleware writes a compaction-style record through LogRecordsCapability. A record from onFinish lands in the log after the transcript record that saved the reply. The live context equals a rebuild of the log, and the next model call gets the fold. A record from onConfig reaches the model call that follows it.
---
 .../ai-harness/tests/durable-session.test.ts  | 116 ++++++++++++++++++
 1 file changed, 116 insertions(+)

diff --git a/packages/ai-harness/tests/durable-session.test.ts b/packages/ai-harness/tests/durable-session.test.ts
index 2e728663de..3b971423d3 100644
--- a/packages/ai-harness/tests/durable-session.test.ts
+++ b/packages/ai-harness/tests/durable-session.test.ts
@@ -623,3 +623,119 @@ describe('LogRecordsCapability', () => {
     await host.close()
   })
 })
+
+describe('compaction-style host records from a middleware', () => {
+  const summary = 'Earlier: q1 and a1.'
+  // The same record a durable compaction writes, in this file's own shape.
+  const compactRecord = { type: 'app.compact', summary, firstKept: 2 }
+
+  async function rebuild(persistence: ReturnType<typeof durablePersistence>) {
+    const state = await loadLogState({
+      store: persistence.stores.log,
+      logId: THREAD,
+      project,
+    })
+    return sessionOf(state, THREAD).messages
+  }
+
+  it('lands a record from onFinish after the saved reply', async () => {
+    const persistence = durablePersistence()
+    const { adapter, calls } = mockAdapter([
+      () => text('a1'),
+      () => text('a2'),
+      () => text('a3'),
+    ])
+    let runs = 0
+    // Like an after-turn compaction: at the end of turn 2, replace q1 and a1.
+    const afterTurn: ChatMiddleware = {
+      name: 'test:after-turn',
+      onFinish: async (ctx) => {
+        runs += 1
+        if (runs !== 2) return
+        await getLogRecords(ctx).append([compactRecord])
+      },
+    }
+    const host = createHarnessHost({ persistence, project })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/after-turn-record',
+        adapter,
+        middleware: [afterTurn],
+      }),
+      { threadId: THREAD },
+    )
+
+    await session.prompt('q1')
+    await session.prompt('q2')
+
+    // (a) The record comes after the transcript record that saved the reply.
+    const entries = await persistence.stores.log.read(THREAD, { after: 0 })
+    const replyAt = entries.findIndex(
+      (entry) =>
+        entry.record.type === 'harness.transcript' &&
+        JSON.stringify(entry.record).includes('"a2"'),
+    )
+    const recordAt = entries.findIndex(
+      (entry) => entry.record.type === 'app.compact',
+    )
+    expect(replyAt).toBeGreaterThanOrEqual(0)
+    expect(recordAt).toBeGreaterThan(replyAt)
+
+    // (b) The live context equals a rebuild, and the fold keeps the reply.
+    const rebuilt = await rebuild(persistence)
+    expect(await session.transcript()).toEqual(rebuilt)
+    expect(rebuilt.map((message) => message.content)).toEqual([
+      summary,
+      'q2',
+      'a2',
+    ])
+
+    // (c) The next model call gets the fold.
+    await session.prompt('q3')
+    expect(messageTexts(calls[2])).toEqual([summary, 'q2', 'a2', 'q3'])
+    await host.close()
+  })
+
+  it('gives the model the fold after a record from onConfig, the same as a rebuild', async () => {
+    const persistence = durablePersistence()
+    const { adapter, calls } = mockAdapter([
+      () => text('a1'),
+      () => text('a2'),
+      () => text('a3'),
+    ])
+    // Like a durable compaction before the model call of turn 3. It returns
+    // nothing: the harness gives the model the fold.
+    const beforeCall: ChatMiddleware = {
+      name: 'test:before-call',
+      onConfig: async (ctx, config) => {
+        if (ctx.phase !== 'beforeModel' || config.messages.length !== 5) return
+        await getLogRecords(ctx).append([compactRecord])
+      },
+    }
+    const host = createHarnessHost({ persistence, project })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/before-call-record',
+        adapter,
+        middleware: [beforeCall],
+      }),
+      { threadId: THREAD },
+    )
+
+    await session.prompt('q1')
+    await session.prompt('q2')
+    await session.prompt('q3')
+
+    expect(messageTexts(calls[2])).toEqual([summary, 'q2', 'a2', 'q3'])
+    const rebuilt = await rebuild(persistence)
+    expect(await session.transcript()).toEqual(rebuilt)
+    expect(rebuilt.map((message) => message.content)).toEqual([
+      summary,
+      'q2',
+      'a2',
+      'q3',
+      'a3',
+    ])
+    await host.close()
+  })
+})

From ccdef926dd6324c2f7c2d5b8c1330a70ea91ebe6 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 3 Oct 2026 18:18:32 +0200
Subject: [PATCH 204/286] docs(ai-mcp): document toolName, requestOptions, and
 the toolFilter list

Add the Name Tools Yourself and Timeouts sections, the strict toolFilter list in Limit and Gate Tools and in Managed MCP, the frozen annotations note, and the schema defaults. Update the ai-mcp skill and the JSDoc of the connector and client options. Add the minor changeset with the two default changes.
---
 .changeset/mcp-tool-options.md         |  16 ++++
 docs/config.json                       |   4 +-
 docs/tools/mcp-managed.md              |  15 +++-
 docs/tools/mcp.md                      | 102 ++++++++++++++++++++++---
 packages/ai-mcp/skills/ai-mcp/SKILL.md |  64 ++++++++++++++--
 packages/ai-mcp/src/connector.ts       |   7 +-
 packages/ai-mcp/src/types.ts           |   4 +-
 7 files changed, 188 insertions(+), 24 deletions(-)
 create mode 100644 .changeset/mcp-tool-options.md

diff --git a/.changeset/mcp-tool-options.md b/.changeset/mcp-tool-options.md
new file mode 100644
index 0000000000..d81e484c3d
--- /dev/null
+++ b/.changeset/mcp-tool-options.md
@@ -0,0 +1,16 @@
+---
+'@tanstack/ai-mcp': minor
+---
+
+New `createMCPClient` options:
+
+- `toolName: (tool) => string` sets the name the model sees for each tool. It wins over `prefix`. `metadata.mcp.serverToolName` keeps the server's own name, so `callTool()` and MCP Apps widget calls still reach the tool. Two tools with the same final name throw `DuplicateToolNameError`.
+- `requestOptions: { timeout, resetTimeoutOnProgress }` is sent with tool lists, tool calls, resource requests, and prompt requests. The connect handshake, `subscriptions/listen`, and task status polls keep the SDK defaults. A spec 2026 `tools/call` uses `timeout` and gets no progress notifications.
+- `toolFilter` also takes a list of server tool names. The client keeps exactly those tools, in list order. A missing or repeated name throws the new `MCPToolFilterError`, which names them and the available tools.
+
+`toolName` and `requestOptions` also work per server in `createMCPClients`, in `mcpConnector`, and in MCP Apps widget calls.
+
+Two default changes:
+
+- A server input schema without `properties` now gets `properties: {}`, and a schema without `type` gets `type: 'object'`. A full schema does not change.
+- `metadata.mcp.annotations` is now a frozen copy of the server's annotations, not the server's own object.
diff --git a/docs/config.json b/docs/config.json
index 94d4aa1e81..222ca4c4ee 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -508,13 +508,13 @@
           "label": "MCP Server Tools",
           "to": "tools/mcp",
           "addedAt": "2026-06-05",
-          "updatedAt": "2026-09-25"
+          "updatedAt": "2026-10-03"
         },
         {
           "label": "Managed MCP with chat()",
           "to": "tools/mcp-managed",
           "addedAt": "2026-06-05",
-          "updatedAt": "2026-09-25"
+          "updatedAt": "2026-10-03"
         },
         {
           "label": "Manual MCP",
diff --git a/docs/tools/mcp-managed.md b/docs/tools/mcp-managed.md
index c2504bef78..e4089506c5 100644
--- a/docs/tools/mcp-managed.md
+++ b/docs/tools/mcp-managed.md
@@ -143,7 +143,11 @@ const pool = await createMCPClients({
     transport: { type: 'http', url: process.env.LINEAR_MCP_URL! },
     needsApproval: (tool) => tool.annotations?.readOnlyHint !== true,
   },
-  docs: { transport: { type: 'http', url: process.env.DOCS_MCP_URL! } },
+  docs: {
+    transport: { type: 'http', url: process.env.DOCS_MCP_URL! },
+    // Exactly these two tools, by server name
+    toolFilter: ['search_docs', 'get_page'],
+  },
 })
 
 const stream = chat({
@@ -153,7 +157,14 @@ const stream = chat({
 })
 ```
 
-The hints come from the server, and a compromised server can send false hints. For the trust rules and a name-based filter, see [Limit and Gate Tools](./mcp#limit-and-gate-tools).
+A `toolFilter` list is strict. If the server has no tool with a listed name, or a name is listed twice, discovery fails:
+
+- A single client throws `MCPToolFilterError`.
+- A `createMCPClients` pool throws `MCPConnectionError`. Its `cause` is the `MCPToolFilterError`.
+
+`chat()` handles this like any other [discovery failure](#handling-discovery-failures). By default, the run fails before the first model call.
+
+The hints come from the server, and a compromised server can send false hints. For the trust rules and the list form, see [Limit and Gate Tools](./mcp#limit-and-gate-tools).
 
 ## Keep connections warm
 
diff --git a/docs/tools/mcp.md b/docs/tools/mcp.md
index d5e931a8e1..ee46272c75 100644
--- a/docs/tools/mcp.md
+++ b/docs/tools/mcp.md
@@ -249,6 +249,33 @@ const mcp = await createMCPClient({
 > a provider backed by pre-provisioned or stored tokens with working refresh —
 > the config form shown above is all you need.
 
+## Timeouts
+
+A slow MCP server can hold a request for a long time. By default, each request waits up to 60 seconds, then fails. A tool that runs longer, such as a report or a build, fails at that limit too.
+
+Set `requestOptions` to change the limit for tool lists, tool calls, resource requests, and prompt requests:
+
+```ts
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+const mcp = await createMCPClient({
+  transport: { type: 'http', url: 'https://my-mcp-server.example.com/mcp' },
+  requestOptions: {
+    // Wait up to 2 minutes for each request.
+    timeout: 120_000,
+    // Start the 2 minutes again each time the server reports progress.
+    resetTimeoutOnProgress: true,
+  },
+})
+```
+
+- `timeout`: the limit in milliseconds. The SDK default is 60,000.
+- `resetTimeoutOnProgress`: start the timeout again when the server sends a progress notification. A tool call on protocol `2026-07-28` gets no progress notifications, so there only `timeout` applies.
+- The connect handshake, the `subscriptions/listen` stream, and task status polls keep the SDK defaults.
+- A request that runs out of time throws an `SdkError` from `@modelcontextprotocol/client`, with the code `SdkErrorCode.RequestTimeout`.
+
+Each server in [`createMCPClients`](#multi-server-pool) can have its own `requestOptions`. [MCP Apps](../mcp/apps) widget calls use the options of the same client.
+
 ## Three Modes of Type Safety
 
 ### Mode 1 — Auto-discovery (`client.tools()`)
@@ -265,6 +292,8 @@ const tools = await mcp.tools()
 // tools: ServerTool[]  — args typed unknown at compile time
 ```
 
+If a server sends an input schema without `properties`, the tool gets `properties: {}`. A schema without `type` gets `type: 'object'`. Some providers reject an object schema without `properties`, and these defaults keep those tools working. The client does not change a schema that has both fields.
+
 MCP schemas often use `$ref` or `oneOf`. On adapters built on the OpenAI API, those tools are sent without strict mode, and the adapter warns in development. See [Tools that cannot use strict mode](../adapters/openai.md#tools-that-cannot-use-strict-mode).
 
 > **Task-based tools are supported.** Tools that declare
@@ -315,7 +344,7 @@ MCP servers can ship display and behavior metadata alongside each tool: a human-
 | `metadata.mcp` field | Value |
 |---|---|
 | `title` | `string` — display name, resolved with the spec's precedence: the tool's `title` → `annotations.title` → `name`. Always set. |
-| `annotations` | The server's `annotations` object, forwarded verbatim. Absent when the server declares none. |
+| `annotations` | A frozen copy of the server's `annotations` object. Absent when the server declares none. To change a value, copy it first: `{ ...tool.metadata.mcp.annotations, readOnlyHint: false }`. |
 | `serverToolName` | `string` — server-native (unprefixed) tool name. |
 | `serverId` | The client's `prefix` (undefined when there is none). |
 | `uiResourceUri` | [MCP Apps](../mcp/apps) widget link, when the tool declares one. |
@@ -419,10 +448,10 @@ export function ToolCatalog() {
 
 By default, the model gets every tool that the server lists, and each tool runs without approval. A server can expose tools that write or delete data. Two client options control this:
 
-- `toolFilter`: return `false` to hide a tool from the model.
+- `toolFilter`: a function that returns `false` to hide a tool, or a list of the tool names to keep.
 - `needsApproval`: return `true` to pause the run for [approval](./tool-approval) before each call to the tool.
 
-Both options receive the tool definition that the server sent. The definition has the native (unprefixed) `name`, the `title`, and the `annotations`. Both options are off by default.
+A `toolFilter` function and `needsApproval` receive the tool definition that the server sent. The definition has the native (unprefixed) `name`, the `title`, and the `annotations`. Both options are off by default.
 
 Send only the tools that the server marks read-only:
 
@@ -439,19 +468,28 @@ const tools = await mcp.tools() // only read-only tools
 
 A tool with no `annotations` does not pass this filter.
 
-On a server that you do not trust, filter by name. You control the names, and the server controls the hints:
+On a server that you do not trust, list the tools by name. You control the names, and the server controls the hints:
 
 ```ts
 import { createMCPClient } from '@tanstack/ai-mcp'
 
-const allowed = new Set(['search_issues', 'get_issue'])
-
 const mcp = await createMCPClient({
   transport: { type: 'http', url: 'https://my-mcp-server.example.com/mcp' },
-  toolFilter: (tool) => allowed.has(tool.name),
+  toolFilter: ['search_issues', 'get_issue'],
 })
+
+const tools = await mcp.tools() // search_issues, then get_issue
 ```
 
+A list is strict:
+
+- The tools come back in the list order.
+- A name that the server does not have, or a name listed twice, throws `MCPToolFilterError`. Its `missing`, `repeated`, and `available` fields name the tools. A typo fails the `tools()` call, so the model never runs with fewer tools than you expect.
+- A listed tool that needs task execution, on a server without task support, throws `MCPTaskRequiredToolError`.
+- An empty list keeps no tools.
+
+A function does not fail when a tool is missing. If the tool list of the server can change, use a function.
+
 Keep every tool, but ask the user before a tool runs:
 
 ```ts
@@ -668,6 +706,51 @@ try {
 
 Use a unique `prefix` on each client to avoid collisions — `createMCPClients` does this automatically using the config key.
 
+## Name Tools Yourself
+
+The model sees `<prefix>_<tool>`, or the server's tool name when there is no prefix. Some apps need another pattern, for example a fixed `mcp__<server>__<tool>` form, or names without characters that a provider rejects.
+
+Pass `toolName`. It gets the tool definition from the server and returns the name the model sees. It wins over `prefix`:
+
+```ts
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+// Keep only letters, digits, `_`, and `-` in the name.
+const clean = (value: string) => value.replace(/[^A-Za-z0-9_-]/g, '_')
+
+const mcp = await createMCPClient({
+  transport: { type: 'http', url: 'https://my-mcp-server.example.com/mcp' },
+  toolName: (tool) => `mcp__github__${clean(tool.name)}`,
+})
+
+const tools = await mcp.tools() // mcp__github__search_issues, ...
+```
+
+- The name applies to `tools()` and to `tools([...defs])`.
+- `metadata.mcp.serverToolName` keeps the server's own name. [MCP Apps](../mcp/apps) widget calls use it, and `callTool()` takes it, so both still reach the tool.
+- `metadata.mcp.serverId` is still the client `prefix`.
+- MCP Apps routes widget calls by `prefix`. If you use MCP Apps with `toolName`, keep a `prefix` on each client.
+- Two tools with the same final name throw `DuplicateToolNameError`, in one client and across a pool.
+
+In a pool, each server gets its own `toolName`:
+
+```ts
+import { createMCPClients } from '@tanstack/ai-mcp'
+
+const pool = await createMCPClients({
+  github: {
+    transport: { type: 'http', url: process.env.GITHUB_MCP_URL! },
+    toolName: (tool) => `mcp__github__${tool.name}`,
+  },
+  linear: {
+    transport: { type: 'http', url: process.env.LINEAR_MCP_URL! },
+    toolName: (tool) => `mcp__linear__${tool.name}`,
+  },
+})
+
+const tools = await pool.tools() // mcp__github__..., mcp__linear__...
+```
+
 ## Lazy Tool Discovery
 
 Pass `{ lazy: true }` to defer sending tool schemas to the LLM until it explicitly asks for them. This reduces token usage when working with tool-heavy servers.
@@ -710,7 +793,8 @@ The Quick Start above hands tools to `chat()` manually via `tools: await mcp.too
 |---|---|
 | `MCPConnectionError` | `createMCPClient` fails to connect, or a method is called after `close()` |
 | `DuplicateToolNameError` | Two tools have the same name within one client or across the pool |
-| `MCPToolNotFoundError` | A `toolDefinition` name passed to `tools([...defs])` is not found on the server |
-| `MCPTaskRequiredToolError` | A task-required tool was bound via `tools([...defs])` or called via `callTool()` but the server does not declare the tasks capability for `tools/call`, so the call could never execute |
+| `MCPToolNotFoundError` | A `toolDefinition` name passed to `tools([...defs])` is not found on the server, or the client's `toolFilter` hides it |
+| `MCPToolFilterError` | A `toolFilter` list names a tool that the server does not have, or names a tool twice. In a pool, `pool.tools()` throws `MCPConnectionError` with this error as its `cause` |
+| `MCPTaskRequiredToolError` | A task-required tool was bound via `tools([...defs])`, listed in a `toolFilter` list, or called via `callTool()`, but the server does not declare the tasks capability for `tools/call`, so the call can never run |
 
 For the `MCPDuplicateToolNameError` thrown when merging tools from multiple sources inside a `chat({ mcp })` run, see [Managed MCP with `chat()`](./mcp-managed#tool-name-collisions).
diff --git a/packages/ai-mcp/skills/ai-mcp/SKILL.md b/packages/ai-mcp/skills/ai-mcp/SKILL.md
index 249503253b..0fcc432cef 100644
--- a/packages/ai-mcp/skills/ai-mcp/SKILL.md
+++ b/packages/ai-mcp/skills/ai-mcp/SKILL.md
@@ -296,6 +296,29 @@ If the connection fails, `createMCPClient` throws `MCPConnectionError`.
 If the server does not support that spec, the client uses the 2025 initialize handshake.
 The client keeps negotiation mode `auto`.
 
+Two more client options:
+
+- `toolName: (tool) => string` sets the name the model sees. It wins over
+  `prefix`. `metadata.mcp.serverToolName` keeps the server's name, so
+  `callTool()` and MCP Apps widget calls still reach the tool. Two tools with
+  the same final name throw `DuplicateToolNameError`.
+- `requestOptions: { timeout, resetTimeoutOnProgress }` is sent with tool
+  lists, tool calls, resource requests, and prompt requests. The connect
+  handshake, the `subscriptions/listen` stream, and task status polls keep
+  the SDK defaults. `timeout` is in milliseconds (SDK default 60,000). A
+  spec 2026 `tools/call` gets no progress notifications, so there only
+  `timeout` applies.
+
+```typescript
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+const client = await createMCPClient({
+  transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+  toolName: (tool) => `mcp__weather__${tool.name}`,
+  requestOptions: { timeout: 120_000, resetTimeoutOnProgress: true },
+})
+```
+
 ### Transports
 
 #### Streamable HTTP (default for internet-facing servers)
@@ -394,7 +417,10 @@ Import `StreamableHTTPClientTransport` from `@modelcontextprotocol/client`.
 ### Mode 1 — Auto-discovery (no types needed)
 
 `client.tools()` lists every tool the server exposes. Args are typed `unknown`
-at compile time but the tool's JSON Schema is forwarded to the LLM.
+at compile time but the tool's JSON Schema is forwarded to the LLM. A schema
+without `properties` gets `properties: {}`, and a schema without `type` gets
+`type: 'object'`. `tool.metadata.mcp.annotations` is a frozen copy of the
+server's annotations.
 
 ```typescript
 import { chat } from '@tanstack/ai'
@@ -468,8 +494,9 @@ See the "Codegen CLI" section below for details.
 
 By default every server tool reaches the model and runs without approval.
 Set a policy on the client. It applies in `tools()`, in `chat({ mcp })`, and
-per server in `createMCPClients`. Both callbacks receive the raw MCP tool
-definition (native unprefixed `name`, `title`, `annotations`).
+per server in `createMCPClients`. A `toolFilter` function and `needsApproval`
+receive the raw MCP tool definition (native unprefixed `name`, `title`,
+`annotations`).
 
 ```typescript
 import { createMCPClient } from '@tanstack/ai-mcp'
@@ -483,6 +510,26 @@ const mcp = await createMCPClient({
 })
 ```
 
+`toolFilter` also takes a list of server tool names. The list is strict:
+
+```typescript
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+const mcp = await createMCPClient({
+  transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+  // Exactly these tools, in this order.
+  toolFilter: ['search_issues', 'get_issue'],
+})
+```
+
+- A name the server does not have, or a repeated name, throws
+  `MCPToolFilterError` (`missing`, `repeated`, `available`).
+- A listed task-required tool on a server without task support throws
+  `MCPTaskRequiredToolError`.
+- An empty list keeps no tools.
+
+These rules apply to both `toolFilter` forms and to `needsApproval`:
+
 - `toolFilter` also applies to `tools([defs])`: a hidden definition throws
   `MCPToolNotFoundError`. MCP Apps widget calls also honor it. It does not
   apply to `callTool()`.
@@ -490,8 +537,8 @@ const mcp = await createMCPClient({
   its own `needsApproval`.
 - MCP Apps widget calls have no approval step, so the call handler refuses a
   tool that `needsApproval` marks (`{ ok: false, error: 'Tool needs approval: <name>' }`).
-- Annotations are server-declared hints. For an untrusted server, filter by
-  `tool.name` instead.
+- Annotations are server-declared hints. For an untrusted server, use a
+  `toolFilter` list of names instead.
 
 ## Lifecycle
 
@@ -1090,9 +1137,13 @@ and do NOT appear in the library's runtime dependency graph.
   methods after `close()`.
 - `MCPToolNotFoundError` — thrown from `client.tools([defs])` when a definition's
   `name` is not exposed by the server, or the client's `toolFilter` hides it.
+- `MCPToolFilterError`: thrown from `client.tools()` when a `toolFilter`
+  list names a tool the server does not have, or names a tool twice. Its
+  `missing`, `repeated`, and `available` fields name the tools.
 - `MCPTaskRequiredToolError` — thrown when a task-required tool is bound via
   `tools([defs])` or called via `callTool()` and the server does not declare
-  the tasks capability for `tools/call`. Auto-discovery skips those tools
+  the tasks capability for `tools/call`. It is also thrown when a `toolFilter`
+  list names such a tool. Auto-discovery without a list skips those tools
   instead of throwing.
 - `DuplicateToolNameError` — thrown by a single pool's own `tools()` when two
   tools within that pool share the same name (same server or pool clients with no
@@ -1106,6 +1157,7 @@ import {
   MCPConnectionError,
   MCPToolNotFoundError,
   MCPTaskRequiredToolError,
+  MCPToolFilterError,
   DuplicateToolNameError,
 } from '@tanstack/ai-mcp'
 
diff --git a/packages/ai-mcp/src/connector.ts b/packages/ai-mcp/src/connector.ts
index fb30f8eb53..8abd12ab1a 100644
--- a/packages/ai-mcp/src/connector.ts
+++ b/packages/ai-mcp/src/connector.ts
@@ -24,14 +24,14 @@ export interface McpConnectorOptions {
   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>`. */
+  /** 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 every request to the server. See `MCPClientOptions.requestOptions`. */
+  /** Sent with 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>
@@ -187,7 +187,8 @@ function credentialProvider(
  * - `/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>`.
+ * - 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
diff --git a/packages/ai-mcp/src/types.ts b/packages/ai-mcp/src/types.ts
index 23759f2846..e4ff9c0e13 100644
--- a/packages/ai-mcp/src/types.ts
+++ b/packages/ai-mcp/src/types.ts
@@ -134,8 +134,8 @@ export interface MCPClientOptions {
    */
   clientOptions?: ClientOptions
   /**
-   * Sent with every request this client makes: `tools/list`, `tools/call`,
-   * resources, and prompts. SDK defaults when unset.
+   * Sent with tool lists, tool calls, resources, and prompts. SDK defaults
+   * when unset.
    *
    * A spec 2026 `tools/call` gets no progress notifications, so there only
    * `timeout` applies.

From 29694fcc094c030728edf3ac7ff7462baf5c02a9 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 3 Oct 2026 18:24:14 +0200
Subject: [PATCH 205/286] test(e2e): check the MCP tool options on the wire

A provider-free route connects to the e2e MCP server with toolName, requestOptions, and a toolFilter list, and checks the names the model sees and the MCPToolFilterError for a missing listed name.
---
 testing/e2e/src/routeTree.gen.ts              | 21 +++++++++
 .../src/routes/api.mcp-tool-options-wire.ts   | 44 +++++++++++++++++++
 .../e2e/tests/mcp-tool-options-wire.spec.ts   | 17 +++++++
 3 files changed, 82 insertions(+)
 create mode 100644 testing/e2e/src/routes/api.mcp-tool-options-wire.ts
 create mode 100644 testing/e2e/tests/mcp-tool-options-wire.spec.ts

diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index 1b106f1216..a5c6b39828 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -87,6 +87,7 @@ import { Route as ApiMessageIdsRouteImport } from './routes/api.message-ids'
 import { Route as ApiMessageHistoryPagingRouteImport } from './routes/api.message-history-paging'
 import { Route as ApiMcpTypedTestRouteImport } from './routes/api.mcp-typed-test'
 import { Route as ApiMcpTypedServerRouteImport } from './routes/api.mcp-typed-server'
+import { Route as ApiMcpToolOptionsWireRouteImport } from './routes/api.mcp-tool-options-wire'
 import { Route as ApiMcpTestRouteImport } from './routes/api.mcp-test'
 import { Route as ApiMcpTaskErrorsRouteImport } from './routes/api.mcp-task-errors'
 import { Route as ApiMcpStatusTestRouteImport } from './routes/api.mcp-status-test'
@@ -549,6 +550,11 @@ const ApiMcpTypedServerRoute = ApiMcpTypedServerRouteImport.update({
   path: '/api/mcp-typed-server',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiMcpToolOptionsWireRoute = ApiMcpToolOptionsWireRouteImport.update({
+  id: '/api/mcp-tool-options-wire',
+  path: '/api/mcp-tool-options-wire',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiMcpTestRoute = ApiMcpTestRouteImport.update({
   id: '/api/mcp-test',
   path: '/api/mcp-test',
@@ -898,6 +904,7 @@ export interface FileRoutesByFullPath {
   '/api/mcp-status-test': typeof ApiMcpStatusTestRoute
   '/api/mcp-task-errors': typeof ApiMcpTaskErrorsRoute
   '/api/mcp-test': typeof ApiMcpTestRoute
+  '/api/mcp-tool-options-wire': typeof ApiMcpToolOptionsWireRoute
   '/api/mcp-typed-server': typeof ApiMcpTypedServerRoute
   '/api/mcp-typed-test': typeof ApiMcpTypedTestRoute
   '/api/message-history-paging': typeof ApiMessageHistoryPagingRoute
@@ -1030,6 +1037,7 @@ export interface FileRoutesByTo {
   '/api/mcp-status-test': typeof ApiMcpStatusTestRoute
   '/api/mcp-task-errors': typeof ApiMcpTaskErrorsRoute
   '/api/mcp-test': typeof ApiMcpTestRoute
+  '/api/mcp-tool-options-wire': typeof ApiMcpToolOptionsWireRoute
   '/api/mcp-typed-server': typeof ApiMcpTypedServerRoute
   '/api/mcp-typed-test': typeof ApiMcpTypedTestRoute
   '/api/message-history-paging': typeof ApiMessageHistoryPagingRoute
@@ -1163,6 +1171,7 @@ export interface FileRoutesById {
   '/api/mcp-status-test': typeof ApiMcpStatusTestRoute
   '/api/mcp-task-errors': typeof ApiMcpTaskErrorsRoute
   '/api/mcp-test': typeof ApiMcpTestRoute
+  '/api/mcp-tool-options-wire': typeof ApiMcpToolOptionsWireRoute
   '/api/mcp-typed-server': typeof ApiMcpTypedServerRoute
   '/api/mcp-typed-test': typeof ApiMcpTypedTestRoute
   '/api/message-history-paging': typeof ApiMessageHistoryPagingRoute
@@ -1297,6 +1306,7 @@ export interface FileRouteTypes {
     | '/api/mcp-status-test'
     | '/api/mcp-task-errors'
     | '/api/mcp-test'
+    | '/api/mcp-tool-options-wire'
     | '/api/mcp-typed-server'
     | '/api/mcp-typed-test'
     | '/api/message-history-paging'
@@ -1429,6 +1439,7 @@ export interface FileRouteTypes {
     | '/api/mcp-status-test'
     | '/api/mcp-task-errors'
     | '/api/mcp-test'
+    | '/api/mcp-tool-options-wire'
     | '/api/mcp-typed-server'
     | '/api/mcp-typed-test'
     | '/api/message-history-paging'
@@ -1561,6 +1572,7 @@ export interface FileRouteTypes {
     | '/api/mcp-status-test'
     | '/api/mcp-task-errors'
     | '/api/mcp-test'
+    | '/api/mcp-tool-options-wire'
     | '/api/mcp-typed-server'
     | '/api/mcp-typed-test'
     | '/api/message-history-paging'
@@ -1694,6 +1706,7 @@ export interface RootRouteChildren {
   ApiMcpStatusTestRoute: typeof ApiMcpStatusTestRoute
   ApiMcpTaskErrorsRoute: typeof ApiMcpTaskErrorsRoute
   ApiMcpTestRoute: typeof ApiMcpTestRoute
+  ApiMcpToolOptionsWireRoute: typeof ApiMcpToolOptionsWireRoute
   ApiMcpTypedServerRoute: typeof ApiMcpTypedServerRoute
   ApiMcpTypedTestRoute: typeof ApiMcpTypedTestRoute
   ApiMessageHistoryPagingRoute: typeof ApiMessageHistoryPagingRoute
@@ -2292,6 +2305,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiMcpTypedServerRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/mcp-tool-options-wire': {
+      id: '/api/mcp-tool-options-wire'
+      path: '/api/mcp-tool-options-wire'
+      fullPath: '/api/mcp-tool-options-wire'
+      preLoaderRoute: typeof ApiMcpToolOptionsWireRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/mcp-test': {
       id: '/api/mcp-test'
       path: '/api/mcp-test'
@@ -2796,6 +2816,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiMcpStatusTestRoute: ApiMcpStatusTestRoute,
   ApiMcpTaskErrorsRoute: ApiMcpTaskErrorsRoute,
   ApiMcpTestRoute: ApiMcpTestRoute,
+  ApiMcpToolOptionsWireRoute: ApiMcpToolOptionsWireRoute,
   ApiMcpTypedServerRoute: ApiMcpTypedServerRoute,
   ApiMcpTypedTestRoute: ApiMcpTypedTestRoute,
   ApiMessageHistoryPagingRoute: ApiMessageHistoryPagingRoute,
diff --git a/testing/e2e/src/routes/api.mcp-tool-options-wire.ts b/testing/e2e/src/routes/api.mcp-tool-options-wire.ts
new file mode 100644
index 0000000000..46bd832247
--- /dev/null
+++ b/testing/e2e/src/routes/api.mcp-tool-options-wire.ts
@@ -0,0 +1,44 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { MCPToolFilterError, createMCPClient } from '@tanstack/ai-mcp'
+
+/**
+ * `toolName` and the list form of `toolFilter`, against the e2e MCP server.
+ * Returns the names the model would see, and the error for a missing name.
+ */
+export const Route = createFileRoute('/api/mcp-tool-options-wire')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const url = `${new URL(request.url).origin}/api/mcp-server`
+
+        const named = await createMCPClient({
+          transport: { type: 'http', url },
+          toolName: (tool) => `mcp__store__${tool.name}`,
+          toolFilter: ['get_guitar_price'],
+          requestOptions: { timeout: 30_000 },
+        })
+        const names = (await named.tools()).map((tool) => tool.name)
+        await named.close()
+
+        const strict = await createMCPClient({
+          transport: { type: 'http', url },
+          toolFilter: ['get_guitar_price', 'no_such_tool'],
+        })
+        let missing: Array<string> = []
+        let errorName = ''
+        try {
+          await strict.tools()
+        } catch (error) {
+          if (error instanceof MCPToolFilterError) {
+            missing = error.missing
+            errorName = error.name
+          }
+        } finally {
+          await strict.close()
+        }
+
+        return Response.json({ names, missing, errorName })
+      },
+    },
+  },
+})
diff --git a/testing/e2e/tests/mcp-tool-options-wire.spec.ts b/testing/e2e/tests/mcp-tool-options-wire.spec.ts
new file mode 100644
index 0000000000..c3c30bc559
--- /dev/null
+++ b/testing/e2e/tests/mcp-tool-options-wire.spec.ts
@@ -0,0 +1,17 @@
+import { test, expect } from './fixtures'
+
+test.describe('mcp: toolName and a strict toolFilter list', () => {
+  test('names tools with toolName and fails on a missing listed name', async ({
+    request,
+  }) => {
+    const response = await request.post('/api/mcp-tool-options-wire')
+    expect(response.ok()).toBe(true)
+    const result: unknown = await response.json()
+
+    expect(result).toEqual({
+      names: ['mcp__store__get_guitar_price'],
+      missing: ['no_such_tool'],
+      errorName: 'MCPToolFilterError',
+    })
+  })
+})

From 9f907231bc80c4f8342266ef6a40de2d39a57856 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 3 Oct 2026 18:27:44 +0200
Subject: [PATCH 206/286] feat(ai-compaction): add compactNext and the auto
 option

withCompaction now returns a CompactionMiddleware. compactNext(threadId) makes the next model call on that thread compact, even under maxTokens. The call clears the flag. auto: false turns off the threshold compaction, and compactNext still works. A harness can now compact and retry once after a context overflow. Two tests of the usage count also check that estimate mode keeps no checkpoint in memory, and that the memory store keeps exactly 1000 threads.
---
 packages/ai-compaction/src/index.test.ts | 107 +++++++++++++++++++++++
 packages/ai-compaction/src/index.ts      |  32 ++++++-
 2 files changed, 135 insertions(+), 4 deletions(-)

diff --git a/packages/ai-compaction/src/index.test.ts b/packages/ai-compaction/src/index.test.ts
index 8c9f91c722..9a7b6f8025 100644
--- a/packages/ai-compaction/src/index.test.ts
+++ b/packages/ai-compaction/src/index.test.ts
@@ -20,6 +20,7 @@ import {
   withCompaction,
 } from './index'
 import { countFromUsage, hashMessages, memoryMetadata } from './usage-count'
+import type { CompactionStrategy } from './index'
 
 interface RecordedCustom {
   name: string
@@ -223,6 +224,10 @@ describe('withCompaction', () => {
 
     expect(summarize).toHaveBeenCalledOnce()
     expect(onCompact).toHaveBeenCalledOnce()
+
+    // Estimate mode keeps no checkpoint in memory, so the next call compacts again.
+    await runOnConfig(mw, msgs, phaseContext('beforeModel'))
+    expect(summarize).toHaveBeenCalledTimes(2)
   })
 
   it('reuses a persisted checkpoint for an unchanged canonical prefix', async () => {
@@ -893,6 +898,8 @@ describe('countTokens: usage', () => {
 
     expect(await store.get('ns', '0')).toBe('again')
     expect(await store.get('ns', '1')).toBeNull()
+    // Only the oldest thread went: the cap is 1000, not 999.
+    expect(await store.get('ns', '2')).toBe(2)
     expect(await store.get('ns', '1000')).toBe(1000)
   })
 
@@ -900,3 +907,103 @@ describe('countTokens: usage', () => {
     expect(withCompaction({ maxTokens: 100 }).onUsage).toBeUndefined()
   })
 })
+
+describe('compactNext and auto', () => {
+  const longList = () => [
+    big('user'),
+    big('assistant'),
+    big('user'),
+    big('assistant'),
+  ]
+  const threadContext = (
+    threadId = 'thread-1',
+    phase: ChatMiddlewareContext['phase'] = 'beforeModel',
+  ) => recordingContext(phase, { threadId })
+
+  it('compacts at the next model call under the limit, then clears the flag', async () => {
+    const onCompact = vi.fn()
+    const mw = withCompaction({
+      maxTokens: 1000,
+      onCompact,
+      strategy: evictOldest({ keepRecentTokens: 50 }),
+    })
+    mw.compactNext('thread-1')
+
+    const first = await runOnConfig(mw, longList(), threadContext().ctx)
+    expect(first?.providerMessages?.[0]?.content).toContain('omitted')
+    expect(
+      await runOnConfig(mw, longList(), threadContext().ctx),
+    ).toBeUndefined()
+    expect(onCompact).toHaveBeenCalledOnce()
+  })
+
+  it('keeps the flag through init and uses it at the model-bound call', async () => {
+    const mw = withCompaction({
+      maxTokens: 1000,
+      strategy: evictOldest({ keepRecentTokens: 50 }),
+    })
+    mw.compactNext('thread-1')
+
+    expect(
+      await runOnConfig(mw, longList(), threadContext('thread-1', 'init').ctx),
+    ).toBeUndefined()
+    const result = await runOnConfig(mw, longList(), threadContext().ctx)
+    expect(result?.providerMessages?.[0]?.content).toContain('omitted')
+  })
+
+  it('forces only the thread it names', async () => {
+    const mw = withCompaction({
+      maxTokens: 1000,
+      strategy: evictOldest({ keepRecentTokens: 50 }),
+    })
+    mw.compactNext('thread-a')
+
+    expect(
+      await runOnConfig(mw, longList(), threadContext('thread-b').ctx),
+    ).toBeUndefined()
+    const result = await runOnConfig(
+      mw,
+      longList(),
+      threadContext('thread-a').ctx,
+    )
+    expect(result?.providerMessages?.[0]?.content).toContain('omitted')
+  })
+
+  it('clears the flag and ends the events when the strategy returns null', async () => {
+    const strategy = vi.fn<CompactionStrategy>(() => null)
+    const mw = withCompaction({ maxTokens: 1000, strategy })
+    mw.compactNext('thread-1')
+
+    const first = threadContext()
+    expect(
+      await runOnConfig(mw, [text('user', 'hi')], first.ctx),
+    ).toBeUndefined()
+    expect(first.events.map((event) => event.name)).toEqual([
+      COMPACTION_STARTED_EVENT,
+      COMPACTION_ENDED_EVENT,
+    ])
+
+    // The next call is under the limit and is not forced again.
+    const second = threadContext()
+    expect(
+      await runOnConfig(mw, [text('user', 'hi')], second.ctx),
+    ).toBeUndefined()
+    expect(strategy).toHaveBeenCalledOnce()
+    expect(second.events).toEqual([])
+  })
+
+  it('does not compact on the threshold with auto: false, but compactNext still runs', async () => {
+    const onCompact = vi.fn()
+    const mw = withCompaction({ maxTokens: 100, auto: false, onCompact })
+
+    expect(
+      await runOnConfig(mw, longList(), threadContext().ctx),
+    ).toBeUndefined()
+    expect(onCompact).not.toHaveBeenCalled()
+
+    mw.compactNext('thread-1')
+    const result = await runOnConfig(mw, longList(), threadContext().ctx)
+    expect(result?.providerMessages?.[0]?.content).toContain('omitted')
+    expect(onCompact).toHaveBeenCalledOnce()
+  })
+})
diff --git a/packages/ai-compaction/src/index.ts b/packages/ai-compaction/src/index.ts
index 2d625061ac..74844eb362 100644
--- a/packages/ai-compaction/src/index.ts
+++ b/packages/ai-compaction/src/index.ts
@@ -238,7 +238,8 @@ export interface CompactionContext {
 }
 
 /**
- * Shrinks a message list. Called only when the estimate is over budget.
+ * Shrinks a message list. Called when the count is over `maxTokens`, or when
+ * `compactNext` forces it.
  * Return the rewritten messages, or `null` to leave them unchanged.
  */
 export type CompactionStrategy = (
@@ -259,7 +260,7 @@ export interface CompactionInfo {
 }
 
 export interface CompactionOptions {
-  /** Compact when estimated tokens across `messages` exceed this. */
+  /** Compact when the token count of `messages` passes this (see `countTokens` and `auto`). */
   maxTokens: number
   /** How to shrink the messages. Default: {@link evictOldest}. */
   strategy?: CompactionStrategy
@@ -280,6 +281,20 @@ export interface CompactionOptions {
    * `'estimate'`.
    */
   countTokens?: 'estimate' | 'usage'
+  /**
+   * `false`: do not compact when the count passes `maxTokens`.
+   * `compactNext` still compacts. Default `true`.
+   */
+  auto?: boolean
+}
+
+/** What {@link withCompaction} returns: a chat middleware with `compactNext`. */
+export interface CompactionMiddleware extends ChatMiddleware {
+  /**
+   * Compact at the next model call on `threadId`, even when the count is
+   * under `maxTokens` or `auto` is `false`. That call clears the flag.
+   */
+  compactNext: (threadId: string) => void
 }
 
 const sum = (
@@ -469,7 +484,9 @@ export function composeStrategies(
  * })
  * ```
  */
-export function withCompaction(options: CompactionOptions): ChatMiddleware {
+export function withCompaction(
+  options: CompactionOptions,
+): CompactionMiddleware {
   const estimate = options.estimateTokens ?? estimateMessageTokens
   const strategy = options.strategy ?? evictOldest()
   const strategyKey =
@@ -479,6 +496,7 @@ export function withCompaction(options: CompactionOptions): ChatMiddleware {
     ? `${strategyKey}:maxTokens=${options.maxTokens}`
     : undefined
   const countUsage = options.countTokens === 'usage'
+  const auto = options.auto !== false
   const memory = memoryMetadata()
   // The store of the checkpoint and of the usage. With countTokens: 'usage',
   // a run with no store, or a strategy with no key, uses the memory of this
@@ -492,14 +510,20 @@ export function withCompaction(options: CompactionOptions): ChatMiddleware {
   // True when the last model call of a run got a compacted view. The usage of
   // that view fits a later call only when that call reuses the checkpoint.
   const compactedViews = new WeakMap<ChatMiddlewareContext, boolean>()
+  /** The threads whose next model call compacts. */
+  const forced = new Set<string>()
 
   return {
     name: 'compaction',
     optionalRequires: [MetadataCapability],
+    compactNext: (threadId) => {
+      forced.add(threadId)
+    },
     async onConfig(ctx, config) {
       // init is discarded by the engine rebuild and can run before persistence
       // hydrates the thread. Compact only on model-bound phases.
       if (ctx.phase === 'init') return
+      const force = forced.delete(ctx.threadId)
 
       const startedAt = Date.now()
       const { messages } = config
@@ -549,7 +573,7 @@ export function withCompaction(options: CompactionOptions): ChatMiddleware {
           : {}),
       }
 
-      if (before <= options.maxTokens) {
+      if (!force && (!auto || before <= options.maxTokens)) {
         if (reusedCheckpoint) {
           emitCompactionStarted(ctx, startedValue)
           const stateValue = compactionStateValue({

From 18314ecf501444d2c1ce05ce9ff274abc54c1e41 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 3 Oct 2026 18:38:46 +0200
Subject: [PATCH 207/286] feat(ai-compaction): report the reason, usage, and
 errors of a compaction

The compaction events and onCompact now have a reason: threshold, forced, or after-turn. A strategy reports the usage of its own model calls with ctx.addUsage, and compaction:ended and onCompact give the sum. summarizeOldest accepts a callback that returns { summary, usage }, so the result of summarize() works as it is. A strategy that throws now ends with an error in compaction:ended. With continueOnError the run continues with the list as it was, unless the run was aborted.
---
 packages/ai-compaction/src/index.test.ts  | 183 ++++++++++++++++++++++
 packages/ai-compaction/src/index.ts       |  84 +++++++++-
 packages/ai-compaction/src/usage-count.ts |  19 +++
 3 files changed, 278 insertions(+), 8 deletions(-)

diff --git a/packages/ai-compaction/src/index.test.ts b/packages/ai-compaction/src/index.test.ts
index 9a7b6f8025..801519d235 100644
--- a/packages/ai-compaction/src/index.test.ts
+++ b/packages/ai-compaction/src/index.test.ts
@@ -4,6 +4,7 @@ import type {
   ChatMiddlewareContext,
   MetadataStore,
   ModelMessage,
+  SummarizationResult,
   TokenUsage,
   ToolCall,
 } from '@tanstack/ai'
@@ -1007,3 +1008,185 @@ describe('compactNext and auto', () => {
     expect(onCompact).toHaveBeenCalledOnce()
   })
 })
+
+describe('compaction usage and errors', () => {
+  const longList = () => [
+    big('user'),
+    big('assistant'),
+    big('user'),
+    big('assistant'),
+  ]
+
+  it('reports the usage of the summary call on onCompact and compaction:ended', async () => {
+    const summaryUsage = tokenUsage(120, 30)
+    // The result of summarize() from @tanstack/ai fits as it is.
+    const summarized: SummarizationResult = {
+      id: 's1',
+      model: 'test-model',
+      summary: 'the gist',
+      usage: summaryUsage,
+    }
+    const onCompact = vi.fn()
+    const mw = withCompaction({
+      maxTokens: 100,
+      onCompact,
+      strategy: summarizeOldest({
+        summarize: async () => summarized,
+        keepRecentTokens: 50,
+      }),
+    })
+    const { ctx, events } = recordingContext('beforeModel')
+    const result = await runOnConfig(mw, longList(), ctx)
+
+    expect(result?.providerMessages?.[0]?.content).toBe(
+      '<untrusted-conversation-summary>\nthe gist\n</untrusted-conversation-summary>',
+    )
+    expect(onCompact.mock.calls[0]?.[0]).toMatchObject({
+      reason: 'threshold',
+      usage: summaryUsage,
+    })
+    expect(events[0]?.value).toMatchObject({ reason: 'threshold' })
+    expect(events.at(-1)?.value).toMatchObject({
+      reason: 'threshold',
+      usage: summaryUsage,
+    })
+  })
+
+  it('sums the addUsage calls of a custom strategy', async () => {
+    const strategy: CompactionStrategy = (messages, ctx) => {
+      ctx.addUsage(tokenUsage(10, 2))
+      ctx.addUsage(tokenUsage(5, 1))
+      return messages.slice(-1)
+    }
+    const mw = withCompaction({ maxTokens: 100, strategy })
+    const { ctx, events } = recordingContext('beforeModel')
+    await runOnConfig(mw, longList(), ctx)
+    expect(events.at(-1)?.value.usage).toEqual(tokenUsage(15, 3))
+  })
+
+  it('marks a compactNext compaction with reason forced', async () => {
+    const mw = withCompaction({
+      maxTokens: 1000,
+      strategy: evictOldest({ keepRecentTokens: 50 }),
+    })
+    mw.compactNext('thread-1')
+    const { ctx, events } = recordingContext('beforeModel', {
+      threadId: 'thread-1',
+    })
+    await runOnConfig(mw, longList(), ctx)
+    expect(events[0]?.value.reason).toBe('forced')
+    expect(events.at(-1)?.value.reason).toBe('forced')
+  })
+
+  it('ends with the error and fails the run when the strategy throws', async () => {
+    const mw = withCompaction({
+      maxTokens: 100,
+      strategy: () => {
+        throw new Error('summary failed')
+      },
+    })
+    const { ctx, events } = recordingContext('beforeModel')
+    await expect(runOnConfig(mw, longList(), ctx)).rejects.toThrow(
+      'summary failed',
+    )
+    expect(events.map((event) => event.name)).toEqual([
+      COMPACTION_STARTED_EVENT,
+      COMPACTION_ENDED_EVENT,
+    ])
+    expect(events[1]?.value).toMatchObject({
+      after: 160,
+      messagesAfter: 4,
+      reason: 'threshold',
+      error: { message: 'summary failed' },
+    })
+  })
+
+  it('sends the list without compaction when continueOnError is set', async () => {
+    const mw = withCompaction({
+      maxTokens: 100,
+      continueOnError: true,
+      strategy: async () => {
+        throw new Error('summary failed')
+      },
+    })
+    const { ctx, events } = recordingContext('beforeModel')
+    expect(await runOnConfig(mw, longList(), ctx)).toBeUndefined()
+    expect(events.at(-1)?.value).toMatchObject({
+      error: { message: 'summary failed' },
+    })
+  })
+
+  it('keeps the checkpoint list when continueOnError is set and a later compaction fails', async () => {
+    const store = memoryStore()
+    const summarize = vi
+      .fn<() => Promise<string>>()
+      .mockResolvedValueOnce('the gist')
+      .mockRejectedValue(new Error('summary failed'))
+    const mw = withCompaction({
+      maxTokens: 100,
+      continueOnError: true,
+      strategy: summarizeOldest({ summarize, keepRecentTokens: 50 }),
+      strategyKey: 'summary-v1',
+    })
+    const messages = longList()
+    await runOnConfig(mw, messages, checkpointContext(store))
+
+    const longer = [...messages, big('user'), big('assistant')]
+    const result = await runOnConfig(mw, longer, checkpointContext(store))
+
+    expect(summarize).toHaveBeenCalledTimes(2)
+    expect(result?.providerMessages?.[0]?.content).toContain('the gist')
+    expect(result?.providerMessages).toHaveLength(4)
+    expect(longer).toHaveLength(6)
+    expect(result?.providerMessages).not.toHaveLength(longer.length)
+  })
+
+  it('rethrows when the run is aborted, even with continueOnError', async () => {
+    const mw = withCompaction({
+      maxTokens: 100,
+      continueOnError: true,
+      strategy: async () => {
+        throw new Error('aborted')
+      },
+    })
+    const ctx = checkpointContext(memoryStore(), { aborted: true })
+    await expect(runOnConfig(mw, longList(), ctx)).rejects.toThrow('aborted')
+  })
+
+  it('keeps the old event fields and values for a caller with no new option', async () => {
+    const mw = withCompaction({ maxTokens: 100 })
+    const { ctx, events } = recordingContext('beforeModel')
+    await runOnConfig(mw, longList(), ctx)
+
+    expect(Object.keys(events[0]?.value ?? {}).sort()).toEqual([
+      'before',
+      'maxTokens',
+      'messagesBefore',
+      'reason',
+      'reusedCheckpoint',
+      'strategyKey',
+    ])
+    expect(events[0]?.value).toMatchObject({
+      before: 160,
+      messagesBefore: 4,
+      reusedCheckpoint: false,
+      maxTokens: 100,
+      strategyKey: 'evict-oldest:half:maxTokens=100',
+    })
+    expect(Object.keys(events[2]?.value ?? {}).sort()).toEqual([
+      'after',
+      'durationMs',
+      'maxTokens',
+      'messagesAfter',
+      'reason',
+      'reusedCheckpoint',
+      'strategyKey',
+    ])
+    expect(events[2]?.value).toMatchObject({
+      messagesAfter: 2,
+      reusedCheckpoint: false,
+      maxTokens: 100,
+      durationMs: expect.any(Number),
+    })
+  })
+})
diff --git a/packages/ai-compaction/src/index.ts b/packages/ai-compaction/src/index.ts
index 74844eb362..2fffebb464 100644
--- a/packages/ai-compaction/src/index.ts
+++ b/packages/ai-compaction/src/index.ts
@@ -18,12 +18,14 @@ import {
   countFromUsage,
   hashMessages,
   memoryMetadata,
+  sumUsage,
   toUsageCount,
 } from './usage-count'
 import type {
   ChatMiddleware,
   ChatMiddlewareContext,
   ModelMessage,
+  TokenUsage,
 } from '@tanstack/ai'
 
 /** CUSTOM stream event: compaction is about to run. */
@@ -48,6 +50,9 @@ export interface CompactionMessagePreview {
   text: string
 }
 
+/** Why a compaction ran. */
+export type CompactionReason = 'threshold' | 'forced' | 'after-turn'
+
 /** Payload of {@link COMPACTION_STARTED_EVENT}. */
 export interface CompactionStartedEventValue {
   before: number
@@ -55,6 +60,7 @@ export interface CompactionStartedEventValue {
   reusedCheckpoint: boolean
   maxTokens: number
   strategyKey?: string
+  reason: CompactionReason
 }
 
 /** Payload of {@link COMPACTION_STATE_EVENT}. */
@@ -80,6 +86,11 @@ export interface CompactionEndedEventValue {
   maxTokens: number
   durationMs: number
   strategyKey?: string
+  reason: CompactionReason
+  /** The sum of the strategy's `addUsage` calls, for example its summary call. */
+  usage?: TokenUsage
+  /** Set when the strategy threw. */
+  error?: { message: string }
 }
 
 function emitCompactionStarted(
@@ -235,6 +246,8 @@ export interface CompactionContext {
   maxTokens: number
   /** The shared token estimator (default {@link estimateMessageTokens}). */
   estimate: (message: ModelMessage) => number
+  /** Report the usage of a model call the strategy made, for example a summary. */
+  addUsage: (usage: TokenUsage) => void
 }
 
 /**
@@ -257,6 +270,10 @@ export interface CompactionInfo {
   messagesBefore: number
   /** Message count after compaction (unchanged for {@link clearToolResults}). */
   messagesAfter: number
+  /** Why the compaction ran. */
+  reason: CompactionReason
+  /** The usage the strategy reported with `addUsage`. */
+  usage?: TokenUsage
 }
 
 export interface CompactionOptions {
@@ -286,6 +303,11 @@ export interface CompactionOptions {
    * `compactNext` still compacts. Default `true`.
    */
   auto?: boolean
+  /**
+   * `true`: when the strategy throws, report the error in `compaction:ended`
+   * and send the list without compaction. Default `false`: the run fails.
+   */
+  continueOnError?: boolean
 }
 
 /** What {@link withCompaction} returns: a chat middleware with `compactNext`. */
@@ -373,7 +395,10 @@ export function evictOldest(
  * `summarize()` or any model call.
  */
 export function summarizeOldest(options: {
-  summarize: (messages: Array<ModelMessage>) => Promise<string>
+  /** Returns the summary text, or the text and the usage of its model call. */
+  summarize: (
+    messages: Array<ModelMessage>,
+  ) => Promise<string | { summary: string; usage?: TokenUsage }>
   /** Tokens of recent messages to keep verbatim. Default `floor(maxTokens/2)`. */
   keepRecentTokens?: number
   /** Role of the injected summary message. Default `'assistant'`. */
@@ -383,7 +408,9 @@ export function summarizeOldest(options: {
     const keep = options.keepRecentTokens ?? Math.floor(ctx.maxTokens / 2)
     const cut = splitAtRecent(messages, ctx.estimate, keep)
     if (cut <= 0) return null
-    const summary = await options.summarize(messages.slice(0, cut))
+    const result = await options.summarize(messages.slice(0, cut))
+    if (typeof result !== 'string' && result.usage) ctx.addUsage(result.usage)
+    const summary = typeof result === 'string' ? result : result.summary
     return [
       {
         role: options.summaryRole ?? 'assistant',
@@ -524,6 +551,7 @@ export function withCompaction(
       // hydrates the thread. Compact only on model-bound phases.
       if (ctx.phase === 'init') return
       const force = forced.delete(ctx.threadId)
+      const reason: CompactionReason = force ? 'forced' : 'threshold'
 
       const startedAt = Date.now()
       const { messages } = config
@@ -571,6 +599,7 @@ export function withCompaction(
         ...(checkpointStrategyKey
           ? { strategyKey: checkpointStrategyKey }
           : {}),
+        reason,
       }
 
       if (!force && (!auto || before <= options.maxTokens)) {
@@ -597,6 +626,7 @@ export function withCompaction(
             ...(checkpointStrategyKey
               ? { strategyKey: checkpointStrategyKey }
               : {}),
+            reason,
           })
           return { providerMessages: workingMessages }
         }
@@ -604,10 +634,39 @@ export function withCompaction(
       }
 
       emitCompactionStarted(ctx, startedValue)
-      const next = await strategy(workingMessages, {
-        maxTokens: options.maxTokens,
-        estimate,
-      })
+      // An object, so the closure below can write it and TypeScript reads it.
+      const spent: { usage?: TokenUsage } = {}
+      let next: Array<ModelMessage> | null
+      try {
+        next = await strategy(workingMessages, {
+          maxTokens: options.maxTokens,
+          estimate,
+          addUsage: (usage) => {
+            spent.usage = sumUsage(spent.usage, usage)
+          },
+        })
+      } catch (error) {
+        emitCompactionEnded(ctx, {
+          after: before,
+          messagesAfter: workingMessages.length,
+          reusedCheckpoint,
+          maxTokens: options.maxTokens,
+          durationMs: Date.now() - startedAt,
+          ...(checkpointStrategyKey
+            ? { strategyKey: checkpointStrategyKey }
+            : {}),
+          reason,
+          ...(spent.usage ? { usage: spent.usage } : {}),
+          error: {
+            message: error instanceof Error ? error.message : String(error),
+          },
+        })
+        // An aborted run must stop. Do not call the adapter with its signal.
+        if (!options.continueOnError || ctx.signal?.aborted) throw error
+        return reusedCheckpoint
+          ? { providerMessages: workingMessages }
+          : undefined
+      }
       if (!next || next === workingMessages) {
         emitCompactionEnded(ctx, {
           after: before,
@@ -618,6 +677,8 @@ export function withCompaction(
           ...(checkpointStrategyKey
             ? { strategyKey: checkpointStrategyKey }
             : {}),
+          reason,
+          ...(spent.usage ? { usage: spent.usage } : {}),
         })
         if (reusedCheckpoint) {
           return { providerMessages: workingMessages }
@@ -625,17 +686,22 @@ export function withCompaction(
         return
       }
 
-      const info = {
+      const info: CompactionInfo = {
         before,
         after: sum(next, estimate),
         messagesBefore: workingMessages.length,
         messagesAfter: next.length,
+        reason,
+        ...(spent.usage ? { usage: spent.usage } : {}),
       }
       options.onCompact?.(info)
       emitCompactionState(
         ctx,
         compactionStateValue({
-          ...info,
+          before: info.before,
+          after: info.after,
+          messagesBefore: info.messagesBefore,
+          messagesAfter: info.messagesAfter,
           reusedCheckpoint,
           maxTokens: options.maxTokens,
           strategyKey: checkpointStrategyKey,
@@ -653,6 +719,8 @@ export function withCompaction(
         ...(checkpointStrategyKey
           ? { strategyKey: checkpointStrategyKey }
           : {}),
+        reason,
+        ...(spent.usage ? { usage: spent.usage } : {}),
       })
 
       if (countUsage) {
diff --git a/packages/ai-compaction/src/usage-count.ts b/packages/ai-compaction/src/usage-count.ts
index b43eacd71e..b4782cb0de 100644
--- a/packages/ai-compaction/src/usage-count.ts
+++ b/packages/ai-compaction/src/usage-count.ts
@@ -114,3 +114,22 @@ export function memoryMetadata(): MetadataStore {
     },
   }
 }
+
+/**
+ * Add two usages. ponytail: only the token counts and `cost` add up. The
+ * details of a first usage are dropped when a second one comes.
+ */
+export function sumUsage(
+  total: TokenUsage | undefined,
+  next: TokenUsage,
+): TokenUsage {
+  if (!total) return next
+  return {
+    promptTokens: total.promptTokens + next.promptTokens,
+    completionTokens: total.completionTokens + next.completionTokens,
+    totalTokens: total.totalTokens + next.totalTokens,
+    ...(total.cost !== undefined && next.cost !== undefined
+      ? { cost: total.cost + next.cost }
+      : {}),
+  }
+}

From bca797c67c1d10f3a2d4036a2477f19281691acd Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sat, 3 Oct 2026 19:53:41 +0200
Subject: [PATCH 208/286] feat(ai-compaction): durable compaction records and
 the after-turn check

With durable: true and a host that provides LogRecordsCapability, a compaction writes one tanstack.compaction record to the session log. The record keeps the new head and the index of the kept tail, with the id of the first kept message. projectCompaction folds the record into the model context, so a rebuild gives the same list. It skips a record that it cannot apply (a kept tail past the end of the fold, or a malformed record), so a fold that lags behind the engine never gets duplicate messages, and a bad record never stops a session from opening. Without the capability, the checkpoint is used as before. With countTokens: 'usage' on a durable host, a check after the last model call of a run compacts when the usage is over contextWindow, even with auto: false, or over maxTokens with auto on. A failed after-turn compaction never fails the run: onCompact gets the error.
---
 packages/ai-compaction/src/index.test.ts | 582 ++++++++++++++++++++++-
 packages/ai-compaction/src/index.ts      | 172 ++++++-
 packages/ai-compaction/src/record.ts     | 108 +++++
 3 files changed, 850 insertions(+), 12 deletions(-)
 create mode 100644 packages/ai-compaction/src/record.ts

diff --git a/packages/ai-compaction/src/index.test.ts b/packages/ai-compaction/src/index.test.ts
index 801519d235..52bf389bf7 100644
--- a/packages/ai-compaction/src/index.test.ts
+++ b/packages/ai-compaction/src/index.test.ts
@@ -2,26 +2,37 @@ import { describe, expect, it, vi } from 'vitest'
 import type {
   ChatMiddlewareConfig,
   ChatMiddlewareContext,
+  FinishInfo,
   MetadataStore,
   ModelMessage,
   SummarizationResult,
   TokenUsage,
   ToolCall,
 } from '@tanstack/ai'
-import { provideMetadata } from '@tanstack/ai'
+import {
+  CapabilityRegistry,
+  provideLogRecords,
+  provideMetadata,
+} from '@tanstack/ai'
 import {
   COMPACTION_ENDED_EVENT,
+  COMPACTION_RECORD_TYPE,
   COMPACTION_STARTED_EVENT,
   COMPACTION_STATE_EVENT,
   clearToolResults,
   composeStrategies,
   estimateMessageTokens,
   evictOldest,
+  projectCompaction,
   summarizeOldest,
   withCompaction,
 } from './index'
 import { countFromUsage, hashMessages, memoryMetadata } from './usage-count'
-import type { CompactionStrategy } from './index'
+import type {
+  CompactionInfo,
+  CompactionMiddleware,
+  CompactionStrategy,
+} from './index'
 
 interface RecordedCustom {
   name: string
@@ -1190,3 +1201,570 @@ describe('compaction usage and errors', () => {
     })
   })
 })
+
+const withId = (message: ModelMessage, id: string): ModelMessage => ({
+  ...message,
+  id,
+})
+
+const summaryOf = (summary: string): ModelMessage => ({
+  role: 'assistant',
+  content: `<untrusted-conversation-summary>\n${summary}\n</untrusted-conversation-summary>`,
+})
+
+/** A context of thread-1 with LogRecordsCapability. Each append lands in `appended`. */
+function durableContext(
+  appended: Array<unknown>,
+  messages: ReadonlyArray<ModelMessage> = [],
+) {
+  const recorded = usageContext(messages, {
+    capabilities: new CapabilityRegistry(),
+  })
+  provideLogRecords(recorded.ctx, {
+    append: async (records) => {
+      appended.push(...records)
+    },
+  })
+  return recorded
+}
+
+describe('durable compaction', () => {
+  const longList = () => [
+    withId(big('user'), 'm1'),
+    withId(big('assistant'), 'm2'),
+    withId(big('user'), 'm3'),
+    withId(big('assistant'), 'm4'),
+  ]
+
+  it('writes a head and from record and gives the model the same list', async () => {
+    const appended: Array<unknown> = []
+    const mw = withCompaction({
+      maxTokens: 100,
+      durable: true,
+      strategy: summarizeOldest({
+        summarize: async () => 'the gist',
+        keepRecentTokens: 50,
+      }),
+    })
+    const messages = longList()
+    const result = await runOnConfig(mw, messages, durableContext(appended).ctx)
+
+    expect(result?.providerMessages).toEqual([
+      summaryOf('the gist'),
+      messages[3],
+    ])
+    expect(appended).toEqual([
+      {
+        type: COMPACTION_RECORD_TYPE,
+        reason: 'threshold',
+        tokensBefore: 160,
+        tokensAfter: expect.any(Number),
+        head: [summaryOf('the gist')],
+        from: 3,
+        firstKeptId: 'm4',
+      },
+    ])
+  })
+
+  it('puts the usage of the summary call on the record', async () => {
+    const appended: Array<unknown> = []
+    const mw = withCompaction({
+      maxTokens: 100,
+      durable: true,
+      strategy: summarizeOldest({
+        summarize: async () => ({
+          summary: 'the gist',
+          usage: tokenUsage(12, 3),
+        }),
+        keepRecentTokens: 50,
+      }),
+    })
+    await runOnConfig(mw, longList(), durableContext(appended).ctx)
+    expect(appended[0]).toMatchObject({ usage: tokenUsage(12, 3) })
+  })
+
+  it('writes the full new list as head, from the end of the list, when the strategy changed the last message', async () => {
+    const appended: Array<unknown> = []
+    const strategy: CompactionStrategy = (messages) =>
+      messages.map((message) => ({ ...message, content: 'short' }))
+    const mw = withCompaction({ maxTokens: 100, durable: true, strategy })
+    const result = await runOnConfig(
+      mw,
+      longList(),
+      durableContext(appended).ctx,
+    )
+
+    expect(appended).toEqual([
+      {
+        type: COMPACTION_RECORD_TYPE,
+        reason: 'threshold',
+        tokensBefore: 160,
+        tokensAfter: 8,
+        head: result?.providerMessages,
+        from: 4,
+      },
+    ])
+  })
+
+  it('writes a record that a fold without the tool results of this phase skips', async () => {
+    // Five parallel tool calls. The fold of the log does not have their
+    // results yet: they are saved after this hook. A record that the fold
+    // used would give the model those results two times.
+    const appended: Array<{ type: string } & Record<string, unknown>> = []
+    const ids = ['c1', 'c2', 'c3', 'c4', 'c5']
+    const fold = [
+      withId(text('user', 'q1'), 'm1'),
+      withId(text('assistant', 'a1'), 'm2'),
+      withId(text('user', 'q2'), 'm3'),
+      withId(
+        {
+          role: 'assistant',
+          content: '',
+          toolCalls: ids.map((id) => ({ ...call, id })),
+        },
+        'm4',
+      ),
+    ]
+    const messages = [
+      ...fold,
+      ...ids.map(
+        (id): ModelMessage => ({
+          role: 'tool',
+          content: 'r'.repeat(40),
+          toolCallId: id,
+        }),
+      ),
+    ]
+    const mw = withCompaction({
+      maxTokens: 20,
+      durable: true,
+      strategy: clearToolResults(),
+    })
+    const result = await runOnConfig(mw, messages, durableContext(appended).ctx)
+
+    expect(appended).toMatchObject([
+      { head: result?.providerMessages?.slice(0, 6), from: 6 },
+    ])
+    expect(
+      appended.map((record) => projectCompaction({ messages: fold, record })),
+    ).toEqual([undefined])
+    // The fold that has the results gives the list the model got.
+    expect(
+      appended.map((record) => projectCompaction({ messages, record })),
+    ).toEqual([result?.providerMessages])
+  })
+
+  it('keeps each rewritten message of clearToolResults in head', async () => {
+    const appended: Array<unknown> = []
+    const toolResult = (id: string): ModelMessage => ({
+      role: 'tool',
+      content: 'x'.repeat(160),
+      toolCallId: id,
+    })
+    const messages = [
+      withId(big('user'), 'm1'),
+      toolResult('t1'),
+      toolResult('t2'),
+      withId(big('user'), 'm2'),
+    ]
+    const mw = withCompaction({
+      maxTokens: 10,
+      durable: true,
+      strategy: clearToolResults({ keepRecentToolResults: 1 }),
+    })
+    await runOnConfig(mw, messages, durableContext(appended).ctx)
+
+    expect(appended).toMatchObject([
+      {
+        head: [
+          messages[0],
+          {
+            role: 'tool',
+            content: '[tool output cleared to save context]',
+            toolCallId: 't1',
+          },
+        ],
+        from: 2,
+      },
+    ])
+  })
+
+  it('never reuses a checkpoint in durable mode', async () => {
+    const store = memoryStore()
+    const strategy = summarizeOldest({
+      summarize: async () => 'the gist',
+      keepRecentTokens: 50,
+    })
+    // A run on a host without a log writes a checkpoint to the shared store.
+    await runOnConfig(
+      withCompaction({ maxTokens: 100, durable: true, strategy }),
+      longList().slice(0, 3),
+      checkpointContext(store),
+    )
+    expect(
+      await store.get('@tanstack/ai-compaction', 'thread-1'),
+    ).not.toBeNull()
+
+    // A durable run with the same store compacts the full list again.
+    const appended: Array<unknown> = []
+    const { ctx } = durableContext(appended)
+    provideMetadata(ctx, store)
+    await runOnConfig(
+      withCompaction({ maxTokens: 100, durable: true, strategy }),
+      longList(),
+      ctx,
+    )
+    expect(appended).toMatchObject([{ from: 3, firstKeptId: 'm4' }])
+  })
+
+  it('falls back to the checkpoint without LogRecordsCapability', async () => {
+    const store = memoryStore()
+    await runOnConfig(
+      withCompaction({ maxTokens: 100, durable: true }),
+      longList(),
+      checkpointContext(store),
+    )
+    expect(
+      await store.get('@tanstack/ai-compaction', 'thread-1'),
+    ).not.toBeNull()
+  })
+
+  it('keeps a provider-only result when an earlier middleware set providerMessages', async () => {
+    const appended: Array<unknown> = []
+    const messages = longList()
+    const config: ChatMiddlewareConfig = {
+      messages,
+      providerMessages: [...messages],
+      systemPrompts: [],
+      tools: [],
+    }
+    const result = await withCompaction({
+      maxTokens: 100,
+      durable: true,
+    }).onConfig?.(durableContext(appended).ctx, config)
+
+    expect(result?.providerMessages?.[0]?.content).toContain('omitted')
+    expect(appended).toEqual([])
+  })
+})
+
+describe('projectCompaction', () => {
+  const fold = [
+    withId(text('user', 'q1'), 'm1'),
+    withId(text('assistant', 'a1'), 'm2'),
+    withId(text('user', 'q2'), 'm3'),
+    withId(text('assistant', 'a2'), 'm4'),
+  ]
+  const summary = summaryOf('the gist')
+
+  it('ignores a record of another type', () => {
+    expect(
+      projectCompaction({
+        messages: fold,
+        record: { type: 'app.note', head: [summary], from: 0 },
+      }),
+    ).toBeUndefined()
+  })
+
+  it('finds the first kept message by id before it uses from', () => {
+    // `from` is wrong here, as when a record lands before the reply is saved.
+    expect(
+      projectCompaction({
+        messages: fold,
+        record: {
+          type: COMPACTION_RECORD_TYPE,
+          head: [summary],
+          from: 1,
+          firstKeptId: 'm3',
+        },
+      }),
+    ).toEqual([summary, fold[2], fold[3]])
+  })
+
+  it('uses from when the first kept message has no id', () => {
+    expect(
+      projectCompaction({
+        messages: fold,
+        record: { type: COMPACTION_RECORD_TYPE, head: [summary], from: 2 },
+      }),
+    ).toEqual([summary, fold[2], fold[3]])
+  })
+
+  it('keeps the full head when from is the end of the fold', () => {
+    expect(
+      projectCompaction({
+        messages: fold,
+        record: { type: COMPACTION_RECORD_TYPE, head: [summary], from: 4 },
+      }),
+    ).toEqual([summary])
+  })
+
+  // The log is folded again on each open, so a bad record must not throw.
+  it.each<[string, Record<string, unknown>]>([
+    [
+      'a kept id that the fold does not have',
+      { head: [summary], from: 1, firstKeptId: 'x' },
+    ],
+    ['a from past the end of the fold', { head: [summary], from: 9 }],
+    ['a negative from', { head: [summary], from: -1 }],
+    ['a from that is not an integer', { head: [summary], from: 1.5 }],
+    ['a head that is not a message list', { head: [null], from: 1 }],
+    ['only a messages list', { messages: [1] }],
+  ])('skips a record with %s', (_label, fields) => {
+    expect(
+      projectCompaction({
+        messages: fold,
+        record: { type: COMPACTION_RECORD_TYPE, ...fields },
+      }),
+    ).toBeUndefined()
+  })
+})
+
+describe('after-turn check', () => {
+  const finish: FinishInfo = { finishReason: 'stop', duration: 0, content: '' }
+  const covered = () => [
+    withId(big('user'), 'm1'),
+    withId(big('assistant'), 'm2'),
+    withId(big('user'), 'm3'),
+  ]
+  const reply = withId(big('assistant'), 'm4')
+  const gist = () =>
+    summarizeOldest({ summarize: async () => 'the gist', keepRecentTokens: 50 })
+
+  /** One model call with `promptTokens + 10` of usage, then the end of the run. */
+  async function finishTurn(
+    mw: CompactionMiddleware,
+    ctx: ChatMiddlewareContext,
+    promptTokens: number,
+  ) {
+    const list = covered()
+    ctx.messages = list
+    await mw.onUsage?.(ctx, tokenUsage(promptTokens, 10))
+    ctx.messages = [...list, reply]
+    await mw.onFinish?.(ctx, finish)
+  }
+
+  it('compacts after a silent overflow, even with auto: false', async () => {
+    const appended: Array<unknown> = []
+    const onCompact = vi.fn()
+    const mw = withCompaction({
+      maxTokens: 1000,
+      contextWindow: 100,
+      countTokens: 'usage',
+      auto: false,
+      durable: true,
+      onCompact,
+      strategy: gist(),
+    })
+    await finishTurn(mw, durableContext(appended).ctx, 110)
+
+    expect(appended).toEqual([
+      {
+        type: COMPACTION_RECORD_TYPE,
+        reason: 'after-turn',
+        tokensBefore: 120,
+        tokensAfter: expect.any(Number),
+        head: [summaryOf('the gist')],
+        from: 3,
+        firstKeptId: 'm4',
+      },
+    ])
+    expect(onCompact).toHaveBeenCalledWith(
+      expect.objectContaining({ reason: 'after-turn', before: 120 }),
+    )
+  })
+
+  it('compacts after the turn over maxTokens when auto is on', async () => {
+    const appended: Array<unknown> = []
+    const mw = withCompaction({
+      maxTokens: 100,
+      contextWindow: 1000,
+      countTokens: 'usage',
+      durable: true,
+      strategy: gist(),
+    })
+    await finishTurn(mw, durableContext(appended).ctx, 110)
+    expect(appended).toMatchObject([{ reason: 'after-turn', from: 3 }])
+  })
+
+  it('counts the usage of a last call that got a compacted view', async () => {
+    const appended: Array<unknown> = []
+    const mw = withCompaction({
+      maxTokens: 100,
+      contextWindow: 1000,
+      countTokens: 'usage',
+      durable: true,
+      strategy: gist(),
+    })
+    const { ctx } = durableContext(appended)
+    // The call compacts, and the model gets the compacted view.
+    const view = (await runOnConfig(mw, covered(), ctx))?.providerMessages ?? []
+    ctx.messages = view
+    await mw.onUsage?.(ctx, tokenUsage(110, 10))
+    ctx.messages = [...view, reply]
+    await mw.onFinish?.(ctx, finish)
+
+    expect(appended).toMatchObject([
+      { reason: 'threshold' },
+      { reason: 'after-turn', tokensBefore: 120 },
+    ])
+  })
+
+  it('ignores maxTokens after the turn with auto: false', async () => {
+    const appended: Array<unknown> = []
+    const mw = withCompaction({
+      maxTokens: 100,
+      contextWindow: 1000,
+      countTokens: 'usage',
+      auto: false,
+      durable: true,
+      strategy: gist(),
+    })
+    await finishTurn(mw, durableContext(appended).ctx, 110)
+    expect(appended).toEqual([])
+  })
+
+  it('writes no record when the strategy returns its input', async () => {
+    const appended: Array<unknown> = []
+    const strategy = vi.fn<CompactionStrategy>(
+      (messages) => messages as Array<ModelMessage>,
+    )
+    const mw = withCompaction({
+      maxTokens: 100,
+      contextWindow: 1000,
+      countTokens: 'usage',
+      durable: true,
+      strategy,
+    })
+    await finishTurn(mw, durableContext(appended).ctx, 110)
+    expect(strategy).toHaveBeenCalledOnce()
+    expect(appended).toEqual([])
+  })
+
+  it('writes the record and never fails the run when onCompact throws', async () => {
+    const appended: Array<unknown> = []
+    const onCompact = vi.fn<(info: CompactionInfo) => void>(() => {
+      throw new Error('observer failed')
+    })
+    const mw = withCompaction({
+      maxTokens: 1000,
+      contextWindow: 100,
+      countTokens: 'usage',
+      durable: true,
+      onCompact,
+      strategy: gist(),
+    })
+
+    await expect(
+      finishTurn(mw, durableContext(appended).ctx, 110),
+    ).resolves.toBeUndefined()
+    expect(appended).toMatchObject([{ reason: 'after-turn' }])
+    expect(onCompact).toHaveBeenLastCalledWith(
+      expect.objectContaining({ error: { message: 'observer failed' } }),
+    )
+  })
+
+  it('fails the run when the log append fails, and reports no success', async () => {
+    const onCompact = vi.fn()
+    const mw = withCompaction({
+      maxTokens: 1000,
+      contextWindow: 100,
+      countTokens: 'usage',
+      durable: true,
+      onCompact,
+      strategy: gist(),
+    })
+    const { ctx } = usageContext([], {
+      capabilities: new CapabilityRegistry(),
+    })
+    provideLogRecords(ctx, {
+      append: async () => {
+        throw new Error('log closed')
+      },
+    })
+
+    await expect(finishTurn(mw, ctx, 110)).rejects.toThrow('log closed')
+    expect(onCompact).not.toHaveBeenCalled()
+  })
+
+  it('does nothing under both limits', async () => {
+    const appended: Array<unknown> = []
+    const summarize = vi.fn(async () => 'the gist')
+    const mw = withCompaction({
+      maxTokens: 1000,
+      contextWindow: 1000,
+      countTokens: 'usage',
+      durable: true,
+      strategy: summarizeOldest({ summarize, keepRecentTokens: 50 }),
+    })
+    await finishTurn(mw, durableContext(appended).ctx, 110)
+    expect(summarize).not.toHaveBeenCalled()
+    expect(appended).toEqual([])
+  })
+
+  it('skips without LogRecordsCapability, and the next call checks the overflow', async () => {
+    const store = memoryStore()
+    const summarize = vi.fn(async () => 'the gist')
+    const mw = withCompaction({
+      maxTokens: 100,
+      contextWindow: 1000,
+      countTokens: 'usage',
+      durable: true,
+      strategy: summarizeOldest({ summarize, keepRecentTokens: 50 }),
+    })
+    // A store but no log: the after-turn check does nothing.
+    await finishTurn(mw, checkpointContext(store), 110)
+    expect(summarize).not.toHaveBeenCalled()
+    expect(await store.get('@tanstack/ai-compaction', 'thread-1')).toBeNull()
+
+    // The next call counts 120 + 1 from the saved usage and compacts first.
+    const next = [...covered(), reply, text('user', 'next')]
+    const result = await runOnConfig(mw, next, checkpointContext(store))
+    expect(summarize).toHaveBeenCalledOnce()
+    expect(result?.providerMessages?.[0]).toEqual(summaryOf('the gist'))
+  })
+
+  it('reports a failed after-turn compaction through onCompact and never fails the run', async () => {
+    const appended: Array<unknown> = []
+    const onCompact = vi.fn()
+    // continueOnError is not set: the after-turn check still does not throw.
+    const mw = withCompaction({
+      maxTokens: 1000,
+      contextWindow: 100,
+      countTokens: 'usage',
+      durable: true,
+      onCompact,
+      strategy: summarizeOldest({
+        summarize: async () => {
+          throw new Error('summary failed')
+        },
+        keepRecentTokens: 50,
+      }),
+    })
+
+    await expect(
+      finishTurn(mw, durableContext(appended).ctx, 110),
+    ).resolves.toBeUndefined()
+    expect(onCompact).toHaveBeenCalledWith(
+      expect.objectContaining({
+        reason: 'after-turn',
+        before: 120,
+        error: { message: 'summary failed' },
+      }),
+    )
+    expect(appended).toEqual([])
+  })
+
+  it('adds no onFinish hook without both durable: true and countTokens: usage', () => {
+    expect(
+      withCompaction({ maxTokens: 100, durable: true }).onFinish,
+    ).toBeUndefined()
+    expect(
+      withCompaction({
+        maxTokens: 100,
+        contextWindow: 1000,
+        countTokens: 'usage',
+      }).onFinish,
+    ).toBeUndefined()
+  })
+})
diff --git a/packages/ai-compaction/src/index.ts b/packages/ai-compaction/src/index.ts
index 2fffebb464..fc55006f5b 100644
--- a/packages/ai-compaction/src/index.ts
+++ b/packages/ai-compaction/src/index.ts
@@ -12,7 +12,13 @@
  * The system prompt is never touched — `chat()` keeps it separate from
  * `messages`.
  */
-import { MetadataCapability, getMetadata } from '@tanstack/ai'
+import {
+  LogRecordsCapability,
+  MetadataCapability,
+  getLogRecords,
+  getMetadata,
+} from '@tanstack/ai'
+import { compactionRecord } from './record'
 import {
   USAGE_NAMESPACE,
   countFromUsage,
@@ -28,6 +34,9 @@ import type {
   TokenUsage,
 } from '@tanstack/ai'
 
+export { COMPACTION_RECORD_TYPE, projectCompaction } from './record'
+export type { CompactionRecord } from './record'
+
 /** CUSTOM stream event: compaction is about to run. */
 export const COMPACTION_STARTED_EVENT = 'compaction:started'
 /** CUSTOM stream event: compaction result (counts and previews). */
@@ -274,6 +283,12 @@ export interface CompactionInfo {
   reason: CompactionReason
   /** The usage the strategy reported with `addUsage`. */
   usage?: TokenUsage
+  /**
+   * Set only when the after-turn check failed: the strategy, the store, or
+   * `onCompact` threw. The run goes on. When the strategy failed, the next
+   * call's own check tries again.
+   */
+  error?: { message: string }
 }
 
 export interface CompactionOptions {
@@ -300,12 +315,30 @@ export interface CompactionOptions {
   countTokens?: 'estimate' | 'usage'
   /**
    * `false`: do not compact when the count passes `maxTokens`.
-   * `compactNext` still compacts. Default `true`.
+   * `compactNext` and the after-turn overflow check still compact. Default
+   * `true`.
    */
   auto?: boolean
   /**
-   * `true`: when the strategy throws, report the error in `compaction:ended`
-   * and send the list without compaction. Default `false`: the run fails.
+   * The model's context window in tokens. With `countTokens: 'usage'` and
+   * `durable: true` on a host with a log, the check after the last model call
+   * of a run compacts when the usage is over it, even with `auto: false`. A
+   * failed after-turn compaction never fails the run: `onCompact` gets
+   * `error`. Only a failed log append fails it.
+   */
+  contextWindow?: number
+  /**
+   * Write each compaction as a log record when the host provides
+   * `LogRecordsCapability` (a durable harness session). Fold the record with
+   * {@link projectCompaction}. Without the capability, the checkpoint is
+   * used, and there is no after-turn check. When an earlier middleware set
+   * `providerMessages`, the result stays provider-only. Default `false`.
+   */
+  durable?: boolean
+  /**
+   * `true`: when the strategy throws in the check before a model call, report
+   * the error in `compaction:ended` and send the list without compaction.
+   * Default `false`: the run fails. The after-turn check never fails the run.
    */
   continueOnError?: boolean
 }
@@ -540,9 +573,103 @@ export function withCompaction(
   /** The threads whose next model call compacts. */
   const forced = new Set<string>()
 
+  /**
+   * After the last model call of a run on a durable host: compact when the
+   * usage is over the context window, or over `maxTokens` with `auto` on, and
+   * write the record. Custom events from `onFinish` do not reach the stream,
+   * so only `onCompact` reports it.
+   */
+  async function afterTurn(ctx: ChatMiddlewareContext) {
+    // Without a log the result could go only to a checkpoint, and that can
+    // miss on the next run. The next call's own check covers it.
+    const logRecords = getLogRecords(ctx, { optional: true })
+    const store = storeOf(ctx)
+    if (!logRecords || !store) return
+    const messages = [...ctx.messages]
+    const spent: { usage?: TokenUsage } = {}
+    let tokens = 0
+    const info = (after: number, messagesAfter: number): CompactionInfo => ({
+      before: tokens,
+      after,
+      messagesBefore: messages.length,
+      messagesAfter,
+      reason: 'after-turn',
+      ...(spent.usage ? { usage: spent.usage } : {}),
+    })
+    // The answer already streamed, so only a failed log append fails the run.
+    // Other errors go to onCompact.
+    const fail = (error: unknown, done = info(tokens, messages.length)) => {
+      try {
+        options.onCompact?.({
+          ...done,
+          error: {
+            message: error instanceof Error ? error.message : String(error),
+          },
+        })
+      } catch {
+        // An onCompact that throws here must not fail the run either.
+      }
+    }
+
+    let next: Array<ModelMessage> | null
+    let tokensAfter: number
+    try {
+      // A durable run never reuses a checkpoint. So this is true only when
+      // the last call of this run compacted, and the list here is the folded
+      // view that the saved usage counted.
+      const counted = await countFromUsage(
+        await store.get(USAGE_NAMESPACE, ctx.threadId),
+        messages,
+        estimate,
+        compactedViews.get(ctx) === true,
+      )
+      if (counted === undefined) return
+      tokens = counted
+      const isOverflow =
+        options.contextWindow !== undefined && tokens > options.contextWindow
+      if (!isOverflow && !(auto && tokens > options.maxTokens)) return
+      next = await strategy(messages, {
+        maxTokens: options.maxTokens,
+        estimate,
+        addUsage: (usage) => {
+          spent.usage = sumUsage(spent.usage, usage)
+        },
+      })
+      if (!next || next === messages || ctx.signal?.aborted) return
+      tokensAfter = sum(next, estimate)
+    } catch (error) {
+      // The saved usage stays, and the next call's own check tries again.
+      fail(error)
+      return
+    }
+    const record = compactionRecord({
+      reason: 'after-turn',
+      before: messages,
+      after: next,
+      tokensBefore: tokens,
+      tokensAfter,
+      ...(spent.usage ? { usage: spent.usage } : {}),
+    })
+    // Append first, so a failed append is never reported as a success.
+    // withPersistence saved the reply before this hook: it is earlier in the
+    // middleware list. If it was not, firstKeptId finds the kept tail, or the
+    // fold skips the record.
+    await logRecords.append([record])
+    const done = info(tokensAfter, next.length)
+    try {
+      // The saved usage counted the list before this compaction.
+      await store.delete(USAGE_NAMESPACE, ctx.threadId)
+      options.onCompact?.(done)
+    } catch (error) {
+      fail(error, done)
+    }
+  }
+
   return {
     name: 'compaction',
-    optionalRequires: [MetadataCapability],
+    optionalRequires: options.durable
+      ? [MetadataCapability, LogRecordsCapability]
+      : [MetadataCapability],
     compactNext: (threadId) => {
       forced.add(threadId)
     },
@@ -556,7 +683,15 @@ export function withCompaction(
       const startedAt = Date.now()
       const { messages } = config
       const inputMessages = config.providerMessages ?? messages
-      const metadata = storeOf(ctx)
+      const store = storeOf(ctx)
+      // A durable compaction goes to the log, and the fold gives the next
+      // call the compacted list, so it needs no checkpoint. A list that an
+      // earlier middleware made provider-only cannot be recorded.
+      const logRecords =
+        options.durable && inputMessages === messages
+          ? getLogRecords(ctx, { optional: true })
+          : undefined
+      const metadata = logRecords ? undefined : store
       const checkpointKey = checkpointStrategyKey ?? 'memory'
       let workingMessages = inputMessages
       let reusedCheckpoint = false
@@ -582,9 +717,9 @@ export function withCompaction(
       compactedViews.set(ctx, reusedCheckpoint)
 
       const fromUsage =
-        countUsage && metadata
+        countUsage && store
           ? await countFromUsage(
-              await metadata.get(USAGE_NAMESPACE, ctx.threadId),
+              await store.get(USAGE_NAMESPACE, ctx.threadId),
               messages,
               estimate,
               reusedCheckpoint,
@@ -725,10 +860,24 @@ export function withCompaction(
 
       if (countUsage) {
         // The saved usage counted the list before this compaction.
-        await metadata?.delete(USAGE_NAMESPACE, ctx.threadId)
+        await store?.delete(USAGE_NAMESPACE, ctx.threadId)
       }
 
-      if (metadata && inputMessages === messages) {
+      if (logRecords) {
+        // The model gets `next` now. The record makes the log fold the same.
+        if (!ctx.signal?.aborted) {
+          await logRecords.append([
+            compactionRecord({
+              reason,
+              before: workingMessages,
+              after: next,
+              tokensBefore: before,
+              tokensAfter: info.after,
+              ...(spent.usage ? { usage: spent.usage } : {}),
+            }),
+          ])
+        }
+      } else if (metadata && inputMessages === messages) {
         const checkpoint: CompactionCheckpoint = {
           schemaVersion: 1,
           sourceMessageCount: messages.length,
@@ -756,5 +905,8 @@ export function withCompaction(
           await storeOf(ctx)?.set(USAGE_NAMESPACE, ctx.threadId, saved)
         }
       : undefined,
+    // Only a durable run checks after the turn (orchestrator decision).
+    onFinish:
+      countUsage && options.durable ? (ctx) => afterTurn(ctx) : undefined,
   }
 }
diff --git a/packages/ai-compaction/src/record.ts b/packages/ai-compaction/src/record.ts
new file mode 100644
index 0000000000..b8c593f26c
--- /dev/null
+++ b/packages/ai-compaction/src/record.ts
@@ -0,0 +1,108 @@
+import type { ModelMessage, TokenUsage } from '@tanstack/ai'
+import type { CompactionReason } from './index'
+
+/** The log record type of a durable compaction. */
+export const COMPACTION_RECORD_TYPE = 'tanstack.compaction'
+
+/**
+ * One durable compaction, as a host log record. Fold it into the model
+ * context with {@link projectCompaction}. It is a type, not an interface, so
+ * it fits the record shape of `LogRecordsWriter.append`.
+ */
+export type CompactionRecord = {
+  type: typeof COMPACTION_RECORD_TYPE
+  reason: CompactionReason
+  tokensBefore: number
+  tokensAfter: number
+  usage?: TokenUsage
+  /** The messages before `from` were replaced by `head`. */
+  head: Array<ModelMessage>
+  from: number
+  /** The id of the first kept message, when it has one. Checked before `from`. */
+  firstKeptId?: string
+}
+
+const sameMessage = (a: ModelMessage, b: ModelMessage) =>
+  a === b || JSON.stringify(a) === JSON.stringify(b)
+
+/**
+ * The record of a compaction from `before` to `after`: the new head, and the
+ * index in `before` where the kept tail starts. When `after` does not end with
+ * the tail of `before`, the head is all of `after`, and `from` is the end of
+ * `before`.
+ */
+export function compactionRecord(input: {
+  reason: CompactionReason
+  before: ReadonlyArray<ModelMessage>
+  after: Array<ModelMessage>
+  tokensBefore: number
+  tokensAfter: number
+  usage?: TokenUsage
+}): CompactionRecord {
+  const { before, after } = input
+  let kept = 0
+  for (;;) {
+    const old = before[before.length - 1 - kept]
+    const next = after[after.length - 1 - kept]
+    if (!old || !next || !sameMessage(old, next)) break
+    kept += 1
+  }
+  // A full rewrite keeps no tail: the head is all of `after`, and `from` is
+  // the end of `before`. A fold that does not have all of `before` yet (the
+  // results of a tool phase that are not saved) then skips the record.
+  const from = before.length - kept
+  const firstKeptId = before[from]?.id
+  return {
+    type: COMPACTION_RECORD_TYPE,
+    reason: input.reason,
+    tokensBefore: input.tokensBefore,
+    tokensAfter: input.tokensAfter,
+    ...(input.usage ? { usage: input.usage } : {}),
+    head: after.slice(0, after.length - kept),
+    from,
+    ...(firstKeptId ? { firstKeptId } : {}),
+  }
+}
+
+// The log is folded again on each open, so a bad record must not throw.
+const isMessageList = (value: unknown): value is Array<ModelMessage> =>
+  Array.isArray(value) &&
+  value.every(
+    (item: unknown) =>
+      typeof item === 'object' &&
+      item !== null &&
+      'role' in item &&
+      typeof item.role === 'string',
+  )
+
+/**
+ * Fold a compaction record into the model context. Give it to the host:
+ * `createHarnessHost({ project: { record: projectCompaction } })`. Returns
+ * `undefined` for a record of another type, and for a record that this fold
+ * cannot use. Pure: the same log always folds to the same context.
+ */
+export function projectCompaction(input: {
+  messages: ReadonlyArray<ModelMessage>
+  record: { type: string; [key: string]: unknown }
+}): Array<ModelMessage> | undefined {
+  const { messages, record } = input
+  if (record.type !== COMPACTION_RECORD_TYPE) return undefined
+  const head = record.head
+  if (!isMessageList(head)) return undefined
+  const start =
+    typeof record.firstKeptId === 'string'
+      ? messages.findIndex((message) => message.id === record.firstKeptId)
+      : record.from
+  // The record counted messages that this fold does not have yet (a kept id
+  // that is not here, or a `from` past the end), or it is malformed. Skip it:
+  // the next check compacts again. A slice here would repeat those messages.
+  if (
+    typeof start !== 'number' ||
+    !Number.isInteger(start) ||
+    start < 0 ||
+    start > messages.length
+  ) {
+    return undefined
+  }
+  return [...head, ...messages.slice(start)]
+}

From 2443f0c1fd59542e693fafea0328932f100153b0 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sun, 4 Oct 2026 12:20:41 +0200
Subject: [PATCH 209/286] feat(ai-compaction): turn cut, summary merge, and
 conversationSummarizer

- summarizeOldest takes cut: 'turn'. When the kept part starts inside a
  turn, the start of that turn gets its own summary under "Turn context".
  With no user message after the earlier summary, one update call merges it.
- conversationSummarizer is a ready summarizer with a structured prompt.
  It updates the earlier summary, cuts each tool result to 2,000 characters
  in the text it sends, and takes a details hook.
- A summarize function gets previousSummary, previousDetails, turnPrefix,
  turnPrefixMessages, and signal. When one of the two calls fails, the
  other call stops.
- The summarizer throws when the run aborts, so no empty summary is kept.
---
 packages/ai-compaction/src/index.test.ts | 581 +++++++++++++++++++++++
 packages/ai-compaction/src/index.ts      | 123 ++++-
 packages/ai-compaction/src/summarizer.ts | 257 ++++++++++
 3 files changed, 952 insertions(+), 9 deletions(-)
 create mode 100644 packages/ai-compaction/src/summarizer.ts

diff --git a/packages/ai-compaction/src/index.test.ts b/packages/ai-compaction/src/index.test.ts
index 52bf389bf7..5b39deb24a 100644
--- a/packages/ai-compaction/src/index.test.ts
+++ b/packages/ai-compaction/src/index.test.ts
@@ -6,6 +6,7 @@ import type {
   MetadataStore,
   ModelMessage,
   SummarizationResult,
+  TextOptions,
   TokenUsage,
   ToolCall,
 } from '@tanstack/ai'
@@ -14,6 +15,7 @@ import {
   provideLogRecords,
   provideMetadata,
 } from '@tanstack/ai'
+import { fakeText } from '@tanstack/ai/testing'
 import {
   COMPACTION_ENDED_EVENT,
   COMPACTION_RECORD_TYPE,
@@ -21,6 +23,7 @@ import {
   COMPACTION_STATE_EVENT,
   clearToolResults,
   composeStrategies,
+  conversationSummarizer,
   estimateMessageTokens,
   evictOldest,
   projectCompaction,
@@ -32,6 +35,8 @@ import type {
   CompactionInfo,
   CompactionMiddleware,
   CompactionStrategy,
+  SummarizeInput,
+  Summarizer,
 } from './index'
 
 interface RecordedCustom {
@@ -1755,6 +1760,34 @@ describe('after-turn check', () => {
     expect(appended).toEqual([])
   })
 
+  it('passes the abort signal of the run to the summary call', async () => {
+    const appended: Array<unknown> = []
+    const run = new AbortController()
+    const reason = new Error('stop')
+    let seen: unknown
+    const mw = withCompaction({
+      maxTokens: 1000,
+      contextWindow: 100,
+      countTokens: 'usage',
+      durable: true,
+      strategy: summarizeOldest({
+        summarize: async (_messages, input) => {
+          run.abort(reason)
+          seen = input.signal?.reason
+          return 'the gist'
+        },
+        keepRecentTokens: 50,
+      }),
+    })
+    const { ctx } = durableContext(appended)
+    ctx.signal = run.signal
+    await finishTurn(mw, ctx, 110)
+
+    expect(seen).toBe(reason)
+    // The run was aborted, so there is no record.
+    expect(appended).toEqual([])
+  })
+
   it('adds no onFinish hook without both durable: true and countTokens: usage', () => {
     expect(
       withCompaction({ maxTokens: 100, durable: true }).onFinish,
@@ -1768,3 +1801,551 @@ describe('after-turn check', () => {
     ).toBeUndefined()
   })
 })
+
+describe('summarizeOldest merge and turn cut', () => {
+  it('passes the earlier summary and its details to the callback', async () => {
+    const summarize = vi.fn<Summarizer>(async () => 'new summary')
+    const earlier: ModelMessage = {
+      role: 'assistant',
+      content:
+        '<untrusted-conversation-summary>\nold facts\n\n<compaction-details>\nfiles: a.ts\n</compaction-details>\n</untrusted-conversation-summary>',
+    }
+    const mw = withCompaction({
+      maxTokens: 100,
+      strategy: summarizeOldest({ summarize, keepRecentTokens: 50 }),
+    })
+    const messages = [
+      earlier,
+      big('user'),
+      big('assistant'),
+      big('user'),
+      big('assistant'),
+    ]
+    await runOnConfig(mw, messages)
+
+    expect(summarize).toHaveBeenCalledOnce()
+    // The messages are the same as before, so an old callback still works.
+    expect(summarize.mock.calls[0]?.[0]).toEqual(messages.slice(0, 4))
+    expect(summarize.mock.calls[0]?.[1]).toMatchObject({
+      previousSummary: 'old facts',
+      previousDetails: 'files: a.ts',
+    })
+  })
+
+  it('reads the details back on the next compaction', async () => {
+    const seen: Array<SummarizeInput> = []
+    const summarize: Summarizer = async (_messages, input) => {
+      seen.push(input)
+      return 'gist\n\n<compaction-details>\nfiles: a.ts\n</compaction-details>'
+    }
+    const mw = withCompaction({
+      maxTokens: 100,
+      strategy: summarizeOldest({ summarize, keepRecentTokens: 50 }),
+    })
+    const first = await runOnConfig(mw, [
+      big('user'),
+      big('assistant'),
+      big('user'),
+      big('assistant'),
+    ])
+    const compacted = first?.providerMessages ?? []
+    await runOnConfig(mw, [...compacted, big('user'), big('assistant')])
+
+    expect(seen[0]?.previousSummary).toBeUndefined()
+    expect(seen[1]).toMatchObject({
+      previousSummary: 'gist',
+      previousDetails: 'files: a.ts',
+    })
+  })
+
+  it('passes the abort signal of the run to the callback', async () => {
+    const controller = new AbortController()
+    const reason = new Error('stop')
+    let seen: unknown
+    const summarize = vi.fn<Summarizer>(async (_messages, input) => {
+      controller.abort(reason)
+      seen = input.signal?.reason
+      return 'the gist'
+    })
+    const mw = withCompaction({
+      maxTokens: 100,
+      strategy: summarizeOldest({ summarize, keepRecentTokens: 50 }),
+    })
+    await runOnConfig(
+      mw,
+      [big('user'), big('assistant'), big('user'), big('assistant')],
+      recordingContext('beforeModel', { signal: controller.signal }).ctx,
+    )
+    expect(seen).toBe(reason)
+  })
+
+  it('adds :turn to the strategy key with cut: turn', async () => {
+    const keyOf = async (cut?: 'turn') => {
+      const mw = withCompaction({
+        maxTokens: 100,
+        strategy: summarizeOldest({
+          summarize: async () => 'the gist',
+          keepRecentTokens: 50,
+          cut,
+        }),
+      })
+      const { ctx, events } = recordingContext('beforeModel')
+      await runOnConfig(
+        mw,
+        [big('user'), big('assistant'), big('user'), big('assistant')],
+        ctx,
+      )
+      return events[0]?.value.strategyKey
+    }
+    expect(await keyOf()).toBe('summarize-oldest:50:assistant:maxTokens=100')
+    expect(await keyOf('turn')).toBe(
+      'summarize-oldest:50:assistant:turn:maxTokens=100',
+    )
+  })
+
+  it('summarizes a split turn in two parallel calls with cut: turn', async () => {
+    const seen: Array<{
+      messages: Array<ModelMessage>
+      input: SummarizeInput
+    }> = []
+    let release!: () => void
+    const gate = new Promise<void>((resolve) => {
+      release = resolve
+    })
+    const summarize: Summarizer = async (messages, input) => {
+      seen.push({ messages, input })
+      await gate
+      return input.turnPrefix ? 'prefix gist' : 'history gist'
+    }
+    const mw = withCompaction({
+      maxTokens: 100,
+      strategy: summarizeOldest({
+        summarize,
+        keepRecentTokens: 50,
+        cut: 'turn',
+      }),
+    })
+    const lastAnswer = big('assistant')
+    // The kept tail starts at the last answer, inside the turn of 'new task'.
+    const messages: Array<ModelMessage> = [
+      text('user', 'old question'),
+      text('assistant', 'old answer'),
+      text('user', 'new task'),
+      { role: 'assistant', content: 'x'.repeat(160), toolCalls: [call] },
+      { role: 'tool', content: 'x'.repeat(160), toolCallId: 't1' },
+      lastAnswer,
+    ]
+    const pending = runOnConfig(mw, messages)
+    // Both calls start before either one ends.
+    await vi.waitFor(() => expect(seen).toHaveLength(2))
+    release()
+    const result = await pending
+
+    expect(seen.map((item) => item.input.turnPrefix ?? false)).toEqual([
+      false,
+      true,
+    ])
+    expect(seen[0]?.messages.map((message) => message.content)).toEqual([
+      'old question',
+      'old answer',
+    ])
+    expect(seen[1]?.messages.map((message) => message.role)).toEqual([
+      'user',
+      'assistant',
+      'tool',
+    ])
+    expect(result?.providerMessages).toEqual([
+      {
+        role: 'assistant',
+        content:
+          '<untrusted-conversation-summary>\nhistory gist\n\n## Turn context\n\nprefix gist\n</untrusted-conversation-summary>',
+      },
+      lastAnswer,
+    ])
+  })
+
+  it('makes only the turn-prefix call when the turn starts right after the earlier summary', async () => {
+    const summarize = vi.fn<Summarizer>(async () => 'prefix gist')
+    const mw = withCompaction({
+      maxTokens: 100,
+      strategy: summarizeOldest({
+        summarize,
+        keepRecentTokens: 50,
+        cut: 'turn',
+      }),
+    })
+    const lastAnswer = big('assistant')
+    // The user message of the turn comes right after the summary.
+    const result = await runOnConfig(mw, [
+      {
+        role: 'assistant',
+        content:
+          '<untrusted-conversation-summary>\nold facts\n\n<compaction-details>\nfiles: a.ts\n</compaction-details>\n</untrusted-conversation-summary>',
+      },
+      text('user', 'new task'),
+      { role: 'assistant', content: 'x'.repeat(160), toolCalls: [call] },
+      { role: 'tool', content: 'x'.repeat(160), toolCallId: 't1' },
+      lastAnswer,
+    ])
+
+    expect(summarize).toHaveBeenCalledOnce()
+    expect(summarize.mock.calls[0]?.[1].turnPrefix).toBe(true)
+    expect(result?.providerMessages).toEqual([
+      {
+        role: 'assistant',
+        content:
+          '<untrusted-conversation-summary>\nold facts\n\n<compaction-details>\nfiles: a.ts\n</compaction-details>\n\n## Turn context\n\nprefix gist\n</untrusted-conversation-summary>',
+      },
+      lastAnswer,
+    ])
+  })
+
+  it.each(['assistant', 'user'] as const)(
+    'merges with one update call when no user message comes after the earlier summary (summary role %s)',
+    async (role) => {
+      const summarize = vi.fn<Summarizer>(async () => 'new gist')
+      const mw = withCompaction({
+        maxTokens: 100,
+        strategy: summarizeOldest({
+          summarize,
+          keepRecentTokens: 50,
+          summaryRole: role,
+          cut: 'turn',
+        }),
+      })
+      // One long agent turn: it started before the earlier summary.
+      const result = await runOnConfig(mw, [
+        { ...summaryOf('old facts'), role },
+        { role: 'assistant', content: 'x'.repeat(160), toolCalls: [call] },
+        { role: 'tool', content: 'x'.repeat(160), toolCallId: 't1' },
+        { role: 'assistant', content: 'x'.repeat(160), toolCalls: [call] },
+        { role: 'tool', content: 'x'.repeat(160), toolCallId: 't1' },
+        big('assistant'),
+      ])
+
+      expect(summarize).toHaveBeenCalledOnce()
+      expect(summarize.mock.calls[0]?.[1]).toMatchObject({
+        previousSummary: 'old facts',
+      })
+      expect(summarize.mock.calls[0]?.[1].turnPrefix).toBeUndefined()
+      expect(result?.providerMessages?.[0]?.content).toBe(
+        '<untrusted-conversation-summary>\nnew gist\n</untrusted-conversation-summary>',
+      )
+    },
+  )
+
+  it('aborts the other call when one call fails', async () => {
+    let prefixSignal: AbortSignal | undefined
+    const summarize: Summarizer = async (_messages, input) => {
+      if (!input.turnPrefix) throw new Error('history failed')
+      prefixSignal = input.signal
+      // Ends when the signal aborts, so no promise stays open.
+      await new Promise((resolve) => {
+        input.signal?.addEventListener('abort', resolve)
+      })
+      return 'prefix gist'
+    }
+    const mw = withCompaction({
+      maxTokens: 100,
+      strategy: summarizeOldest({
+        summarize,
+        keepRecentTokens: 50,
+        cut: 'turn',
+      }),
+    })
+    await expect(
+      runOnConfig(mw, [
+        text('user', 'old question'),
+        text('assistant', 'old answer'),
+        text('user', 'new task'),
+        { role: 'assistant', content: 'x'.repeat(160), toolCalls: [call] },
+        { role: 'tool', content: 'x'.repeat(160), toolCallId: 't1' },
+        big('assistant'),
+      ]),
+    ).rejects.toThrow('history failed')
+    expect(prefixSignal?.aborted).toBe(true)
+  })
+
+  it('does not split a turn when the cut is at a user message', async () => {
+    const summarize = vi.fn<Summarizer>(async () => 'the gist')
+    const mw = withCompaction({
+      maxTokens: 100,
+      strategy: summarizeOldest({
+        summarize,
+        keepRecentTokens: 50,
+        cut: 'turn',
+      }),
+    })
+    await runOnConfig(mw, [
+      big('assistant'),
+      big('user'),
+      big('assistant'),
+      big('user'),
+    ])
+    expect(summarize).toHaveBeenCalledOnce()
+    expect(summarize.mock.calls[0]?.[1].turnPrefix).toBeUndefined()
+  })
+})
+
+describe('conversationSummarizer', () => {
+  /** A fake model that answers `the summary` twice and keeps each request. */
+  function fakeSummaryModel() {
+    const requests: Array<TextOptions> = []
+    const fake = fakeText()
+    const answer = ({ request }: { request: TextOptions }) => {
+      requests.push(request)
+      return { text: 'the summary' }
+    }
+    // Two answers: a split turn makes a history call and a turn-prefix call.
+    fake.setResponses([answer, answer])
+    return { fake, requests }
+  }
+  type Details = (input: {
+    messages: Array<ModelMessage>
+    previousDetails?: string
+  }) => string | undefined
+  /** summarizeOldest with cut: turn and conversationSummarizer. */
+  const turnCut = (fake: ReturnType<typeof fakeText>, details: Details) =>
+    withCompaction({
+      maxTokens: 100,
+      strategy: summarizeOldest({
+        summarize: conversationSummarizer({ adapter: fake, details }),
+        keepRecentTokens: 50,
+        cut: 'turn',
+      }),
+    })
+  const toolTurn = (): Array<ModelMessage> => [
+    { role: 'assistant', content: 'x'.repeat(160), toolCalls: [call] },
+    { role: 'tool', content: 'x'.repeat(160), toolCallId: 't1' },
+  ]
+  const systemOf = (request: TextOptions | undefined) =>
+    JSON.stringify(request?.systemPrompts)
+  const userOf = (request: TextOptions | undefined) =>
+    JSON.stringify(request?.messages)
+
+  it('asks with the checkpoint sections and reports the usage', async () => {
+    const { fake, requests } = fakeSummaryModel()
+    const result = await conversationSummarizer({ adapter: fake })(
+      [text('user', 'fix the bug'), text('assistant', 'done')],
+      {},
+    )
+
+    expect(result).toEqual({
+      summary: 'the summary',
+      usage: expect.objectContaining({
+        promptTokens: expect.any(Number),
+        completionTokens: 3,
+      }),
+    })
+    for (const heading of [
+      '## Goal',
+      '## Constraints',
+      '## Progress',
+      '## Key decisions',
+      '## Next steps',
+      '## Critical context',
+    ]) {
+      expect(systemOf(requests[0])).toContain(heading)
+    }
+    expect(userOf(requests[0])).toContain('[User]: fix the bug')
+    expect(userOf(requests[0])).toContain('[Assistant]: done')
+  })
+
+  it('uses the update prompt and leaves the earlier summary out of the conversation', async () => {
+    const { fake, requests } = fakeSummaryModel()
+    const earlier: ModelMessage = {
+      role: 'assistant',
+      content:
+        '<untrusted-conversation-summary>\nold facts\n</untrusted-conversation-summary>',
+    }
+    await conversationSummarizer({ adapter: fake })(
+      [earlier, text('user', 'new step')],
+      { previousSummary: 'old facts' },
+    )
+
+    expect(systemOf(requests[0])).toContain('You update a checkpoint summary')
+    const content = userOf(requests[0])
+    expect(content).toContain(
+      '<previous-summary>\\nold facts\\n</previous-summary>',
+    )
+    expect(content.match(/old facts/g)).toHaveLength(1)
+    expect(content).toContain('[User]: new step')
+  })
+
+  it('uses the turn-prefix prompt for the first part of a turn', async () => {
+    const { fake, requests } = fakeSummaryModel()
+    await conversationSummarizer({ adapter: fake })(
+      [text('user', 'new task')],
+      { turnPrefix: true },
+    )
+    expect(systemOf(requests[0])).toContain(
+      'the first part of the current turn',
+    )
+  })
+
+  it('cuts each tool result to 2,000 characters, or to maxToolResultChars', async () => {
+    const tool: ModelMessage = {
+      role: 'tool',
+      content: 'y'.repeat(5000),
+      toolCallId: 't1',
+    }
+    const first = fakeSummaryModel()
+    await conversationSummarizer({ adapter: first.fake })([tool], {})
+    expect(userOf(first.requests[0])).toContain('y'.repeat(2000))
+    expect(userOf(first.requests[0])).not.toContain('y'.repeat(2001))
+
+    const second = fakeSummaryModel()
+    await conversationSummarizer({
+      adapter: second.fake,
+      maxToolResultChars: 10,
+    })([tool], {})
+    expect(userOf(second.requests[0])).toContain('y'.repeat(10))
+    expect(userOf(second.requests[0])).not.toContain('y'.repeat(11))
+  })
+
+  it('adds the details tag only when details returns text', async () => {
+    const withDetails = fakeSummaryModel()
+    const details = vi.fn(
+      ({ previousDetails }: { previousDetails?: string }) =>
+        previousDetails ? `${previousDetails}, b.ts` : 'a.ts',
+    )
+    const result = await conversationSummarizer({
+      adapter: withDetails.fake,
+      details,
+    })([text('user', 'edit b.ts')], {
+      previousSummary: 'old',
+      previousDetails: 'a.ts',
+    })
+    expect(result).toMatchObject({
+      summary:
+        'the summary\n\n<compaction-details>\na.ts, b.ts\n</compaction-details>',
+    })
+
+    const without = fakeSummaryModel()
+    const plain = await conversationSummarizer({
+      adapter: without.fake,
+      details: () => undefined,
+    })([text('user', 'hi')], {})
+    expect(plain).toMatchObject({ summary: 'the summary' })
+  })
+
+  it('gives details the new messages without the earlier summary', async () => {
+    const { fake } = fakeSummaryModel()
+    const details = vi.fn<Details>(() => undefined)
+    await conversationSummarizer({ adapter: fake, details })(
+      [summaryOf('old facts'), text('user', 'new step')],
+      { previousSummary: 'old facts' },
+    )
+    expect(details).toHaveBeenCalledWith({
+      messages: [text('user', 'new step')],
+    })
+  })
+
+  it('gives details the history and the turn prefix, and keeps the prefix out of the history prompt', async () => {
+    const { fake, requests } = fakeSummaryModel()
+    const details = vi.fn<Details>(() => 'files: a.ts')
+    const prefix = [text('user', 'new task'), ...toolTurn()]
+    const result = await runOnConfig(turnCut(fake, details), [
+      summaryOf('old facts'),
+      text('user', 'old question'),
+      text('assistant', 'old answer'),
+      ...prefix,
+      big('assistant'),
+    ])
+
+    expect(details).toHaveBeenCalledOnce()
+    expect(details.mock.calls[0]?.[0].messages).toEqual([
+      text('user', 'old question'),
+      text('assistant', 'old answer'),
+      ...prefix,
+    ])
+    const history = requests.find((request) =>
+      systemOf(request).includes('You update a checkpoint summary'),
+    )
+    expect(userOf(history)).toContain('[User]: old question')
+    expect(userOf(history)).not.toContain('new task')
+    expect(result?.providerMessages?.[0]?.content).toBe(
+      '<untrusted-conversation-summary>\nthe summary\n\n<compaction-details>\nfiles: a.ts\n</compaction-details>\n\n## Turn context\n\nthe summary\n</untrusted-conversation-summary>',
+    )
+  })
+
+  it('writes the details in the turn-prefix call when no history call runs', async () => {
+    const { fake, requests } = fakeSummaryModel()
+    const details = vi.fn<Details>(() => 'files: a.ts')
+    // The first compaction of one long turn: the turn starts at index 0.
+    const prefix = [text('user', 'new task'), ...toolTurn()]
+    const result = await runOnConfig(turnCut(fake, details), [
+      ...prefix,
+      big('assistant'),
+    ])
+
+    expect(requests).toHaveLength(1)
+    expect(details.mock.calls).toEqual([[{ messages: prefix }]])
+    expect(result?.providerMessages?.[0]?.content).toBe(
+      '<untrusted-conversation-summary>\n<compaction-details>\nfiles: a.ts\n</compaction-details>\n\n## Turn context\n\nthe summary\n</untrusted-conversation-summary>',
+    )
+  })
+
+  it('replaces the details of the earlier summary when the turn starts right after it', async () => {
+    const { fake, requests } = fakeSummaryModel()
+    const details = vi.fn<Details>(
+      ({ previousDetails }) => `${previousDetails}, b.ts`,
+    )
+    const prefix = [text('user', 'new task'), ...toolTurn()]
+    const result = await runOnConfig(turnCut(fake, details), [
+      {
+        role: 'assistant',
+        content:
+          '<untrusted-conversation-summary>\nold facts\n\n<compaction-details>\na.ts\n</compaction-details>\n</untrusted-conversation-summary>',
+      },
+      ...prefix,
+      big('assistant'),
+    ])
+
+    expect(requests).toHaveLength(1)
+    expect(details.mock.calls).toEqual([
+      [{ messages: prefix, previousDetails: 'a.ts' }],
+    ])
+    // One details tag, with the merged text of the hook.
+    expect(result?.providerMessages?.[0]?.content).toBe(
+      '<untrusted-conversation-summary>\nold facts\n\n<compaction-details>\na.ts, b.ts\n</compaction-details>\n\n## Turn context\n\nthe summary\n</untrusted-conversation-summary>',
+    )
+  })
+
+  it('follows the abort signal of the run', async () => {
+    // Already aborted: it throws the reason and makes no model request.
+    const early = fakeSummaryModel()
+    await expect(
+      conversationSummarizer({ adapter: early.fake })([text('user', 'hi')], {
+        signal: AbortSignal.abort(new Error('stop')),
+      }),
+    ).rejects.toThrow('stop')
+    expect(early.requests).toEqual([])
+
+    // A reason that is not an Error: it throws its own error.
+    await expect(
+      conversationSummarizer({ adapter: early.fake })([text('user', 'hi')], {
+        signal: AbortSignal.abort('stop'),
+      }),
+    ).rejects.toThrow('The summary was aborted.')
+
+    // Aborted during the call: the signal of the model request is aborted.
+    // chat() gives the adapter `request.signal`, not `abortController`.
+    const controller = new AbortController()
+    const late = fakeText()
+    let requestSignal: AbortSignal | null | undefined
+    late.setResponses([
+      ({ request }) => {
+        controller.abort(new Error('stop'))
+        requestSignal = request.request?.signal
+        return { text: 'the summary' }
+      },
+    ])
+    await expect(
+      conversationSummarizer({ adapter: late })([text('user', 'hi')], {
+        signal: controller.signal,
+      }),
+    ).rejects.toThrow('stop')
+    expect(requestSignal?.aborted).toBe(true)
+  })
+})
diff --git a/packages/ai-compaction/src/index.ts b/packages/ai-compaction/src/index.ts
index fc55006f5b..b47ff226a4 100644
--- a/packages/ai-compaction/src/index.ts
+++ b/packages/ai-compaction/src/index.ts
@@ -19,6 +19,12 @@ import {
   getMetadata,
 } from '@tanstack/ai'
 import { compactionRecord } from './record'
+import {
+  readSummary,
+  splitDetails,
+  summaryBody,
+  summaryContent,
+} from './summarizer'
 import {
   USAGE_NAMESPACE,
   countFromUsage,
@@ -33,9 +39,12 @@ import type {
   ModelMessage,
   TokenUsage,
 } from '@tanstack/ai'
+import type { SummarizeInput, Summarizer } from './summarizer'
 
 export { COMPACTION_RECORD_TYPE, projectCompaction } from './record'
 export type { CompactionRecord } from './record'
+export { conversationSummarizer } from './summarizer'
+export type { SummarizeInput, Summarizer } from './summarizer'
 
 /** CUSTOM stream event: compaction is about to run. */
 export const COMPACTION_STARTED_EVENT = 'compaction:started'
@@ -257,6 +266,8 @@ export interface CompactionContext {
   estimate: (message: ModelMessage) => number
   /** Report the usage of a model call the strategy made, for example a summary. */
   addUsage: (usage: TokenUsage) => void
+  /** Aborted when the run is cancelled. Pass it to a model call. */
+  signal?: AbortSignal
 }
 
 /**
@@ -422,39 +433,131 @@ export function evictOldest(
   )
 }
 
+/**
+ * The start of the turn that holds index `cut`: its user message. When no
+ * user message comes after an earlier summary at index 0, the turn started
+ * before the summary. Then the cut is not a split turn: it returns `cut`, and
+ * one update call merges the messages into the summary.
+ */
+function turnStart(messages: ReadonlyArray<ModelMessage>, cut: number) {
+  let start = cut
+  // The walk stops at index 0 also when the summary has the role 'user'.
+  while (start > 0 && messages[start]?.role !== 'user') start -= 1
+  return start === 0 && readSummary(messages[0]) ? cut : start
+}
+
 /**
  * Drop the oldest messages and replace them with an LLM summary. Keeps the gist
  * of old turns at the cost of one summarization call. Wire `summarize` to
- * `summarize()` or any model call.
+ * {@link conversationSummarizer}, `summarize()`, or any model call.
+ *
+ * When the messages start with an earlier summary, `summarize` gets its text
+ * as `previousSummary`, so it can merge the new messages into it.
  */
 export function summarizeOldest(options: {
   /** Returns the summary text, or the text and the usage of its model call. */
-  summarize: (
-    messages: Array<ModelMessage>,
-  ) => Promise<string | { summary: string; usage?: TokenUsage }>
+  summarize: Summarizer
   /** Tokens of recent messages to keep verbatim. Default `floor(maxTokens/2)`. */
   keepRecentTokens?: number
   /** Role of the injected summary message. Default `'assistant'`. */
   summaryRole?: 'user' | 'assistant'
+  /**
+   * `'turn'`: when the kept tail starts inside a turn, summarize the history
+   * before the turn and the first part of the turn, in two parallel calls.
+   * When the user message of the turn comes right after an earlier summary,
+   * only the second call runs. When no user message comes after an earlier
+   * summary, the turn started before it: one update call runs, as with
+   * `'message'`. Default `'message'`.
+   */
+  cut?: 'message' | 'turn'
 }): CompactionStrategy {
   const strategy: CompactionStrategy = async (messages, ctx) => {
     const keep = options.keepRecentTokens ?? Math.floor(ctx.maxTokens / 2)
     const cut = splitAtRecent(messages, ctx.estimate, keep)
     if (cut <= 0) return null
-    const result = await options.summarize(messages.slice(0, cut))
-    if (typeof result !== 'string' && result.usage) ctx.addUsage(result.usage)
-    const summary = typeof result === 'string' ? result : result.summary
+    // Follows the signal of the run. When one call fails, it aborts the other
+    // call, so that call stops and adds no usage after the end event.
+    const controller = new AbortController()
+    const stop = () => controller.abort(ctx.signal?.reason)
+    if (ctx.signal?.aborted) stop()
+    ctx.signal?.addEventListener('abort', stop, { once: true })
+    const summarize = async (
+      part: Array<ModelMessage>,
+      input: SummarizeInput,
+    ) => {
+      try {
+        const result = await options.summarize(part, {
+          ...input,
+          signal: controller.signal,
+        })
+        if (typeof result === 'string') return result
+        if (result.usage) ctx.addUsage(result.usage)
+        return result.summary
+      } catch (error) {
+        controller.abort(error)
+        throw error
+      }
+    }
+    const earlier = readSummary(messages[0])
+    const start =
+      options.cut === 'turn' && messages[cut]?.role !== 'user'
+        ? turnStart(messages, cut)
+        : cut
+    const prefix = messages.slice(start, cut)
+    // With a turn prefix, an earlier summary right before the turn is the
+    // whole history. Keep its text, and make no history call.
+    const historyCall =
+      start > 0 && !(earlier && start === 1 && prefix.length > 0)
+    const previousDetails =
+      earlier?.details !== undefined ? { previousDetails: earlier.details } : {}
+    const [history, turn] = await Promise.all([
+      historyCall
+        ? summarize(messages.slice(0, start), {
+            ...(earlier ? { previousSummary: earlier.summary } : {}),
+            ...previousDetails,
+            ...(prefix.length > 0 ? { turnPrefixMessages: prefix } : {}),
+          })
+        : undefined,
+      prefix.length > 0
+        ? summarize(prefix, {
+            turnPrefix: true,
+            // With no history call, this call writes the details.
+            ...(historyCall
+              ? {}
+              : { turnPrefixMessages: prefix, ...previousDetails }),
+          })
+        : undefined,
+    ]).finally(() => ctx.signal?.removeEventListener('abort', stop))
+    let historyText = history
+    let turnText = turn
+    if (!historyCall && turn !== undefined) {
+      // The details of the turn-prefix call go with the history, before the
+      // turn context. When the call gives details, they replace the details
+      // of the earlier summary. Otherwise the earlier details stay.
+      const split = splitDetails(turn)
+      historyText = summaryBody(
+        earlier?.summary ?? '',
+        split.details ?? earlier?.details,
+      )
+      turnText = split.summary
+    }
+    const body = [
+      historyText,
+      turnText === undefined ? undefined : `## Turn context\n\n${turnText}`,
+    ]
+      .filter((part) => part !== undefined && part !== '')
+      .join('\n\n')
     return [
       {
         role: options.summaryRole ?? 'assistant',
-        content: `<untrusted-conversation-summary>\n${summary}\n</untrusted-conversation-summary>`,
+        content: summaryContent(body),
       },
       ...messages.slice(cut),
     ]
   }
   return identifyStrategy(
     strategy,
-    `summarize-oldest:${options.keepRecentTokens ?? 'half'}:${options.summaryRole ?? 'assistant'}`,
+    `summarize-oldest:${options.keepRecentTokens ?? 'half'}:${options.summaryRole ?? 'assistant'}${options.cut === 'turn' ? ':turn' : ''}`,
   )
 }
 
@@ -631,6 +734,7 @@ export function withCompaction(
       next = await strategy(messages, {
         maxTokens: options.maxTokens,
         estimate,
+        signal: ctx.signal,
         addUsage: (usage) => {
           spent.usage = sumUsage(spent.usage, usage)
         },
@@ -776,6 +880,7 @@ export function withCompaction(
         next = await strategy(workingMessages, {
           maxTokens: options.maxTokens,
           estimate,
+          signal: ctx.signal,
           addUsage: (usage) => {
             spent.usage = sumUsage(spent.usage, usage)
           },
diff --git a/packages/ai-compaction/src/summarizer.ts b/packages/ai-compaction/src/summarizer.ts
new file mode 100644
index 0000000000..cc7dac0403
--- /dev/null
+++ b/packages/ai-compaction/src/summarizer.ts
@@ -0,0 +1,257 @@
+import { chat } from '@tanstack/ai'
+import { sumUsage } from './usage-count'
+import type {
+  AnyTextAdapter,
+  ChatMiddleware,
+  ModelMessage,
+  TokenUsage,
+} from '@tanstack/ai'
+
+/** What a summary callback gets with the messages. */
+export interface SummarizeInput {
+  /** The text of an earlier compaction summary at the start of `messages`. */
+  previousSummary?: string
+  /** The details text of that summary, from its `<compaction-details>` tag. */
+  previousDetails?: string
+  /** `true`: `messages` is the first part of a turn that is too large to keep. */
+  turnPrefix?: boolean
+  /**
+   * The first part of the current turn. Only the call that writes the details
+   * gets it, so `details` can see each dropped message. In a history call, a
+   * separate call summarizes these messages. In a turn-prefix call, they are
+   * the same as `messages`, and no history call runs.
+   */
+  turnPrefixMessages?: Array<ModelMessage>
+  /** Aborted when the run is cancelled. */
+  signal?: AbortSignal
+}
+
+/**
+ * Turns messages into summary text. Return the text, or the text and the
+ * usage of the model call, so the compaction can report the cost.
+ */
+export type Summarizer = (
+  messages: Array<ModelMessage>,
+  input: SummarizeInput,
+) => Promise<string | { summary: string; usage?: TokenUsage }>
+
+const SUMMARY_OPEN = '<untrusted-conversation-summary>'
+const SUMMARY_CLOSE = '</untrusted-conversation-summary>'
+const DETAILS_OPEN = '<compaction-details>'
+const DETAILS_CLOSE = '</compaction-details>'
+
+/** The content of a summary message. */
+export const summaryContent = (summary: string) =>
+  `${SUMMARY_OPEN}\n${summary}\n${SUMMARY_CLOSE}`
+
+/** A summary text with its details in a `<compaction-details>` tag after it. */
+export const summaryBody = (summary: string, details?: string) =>
+  [summary, details ? `${DETAILS_OPEN}\n${details}\n${DETAILS_CLOSE}` : '']
+    .filter((part) => part !== '')
+    .join('\n\n')
+
+/** The summary text and the details text of a summary body. */
+export function splitDetails(body: string): {
+  summary: string
+  details?: string
+} {
+  const start = body.indexOf(DETAILS_OPEN)
+  const end = body.indexOf(DETAILS_CLOSE, start)
+  if (start < 0 || end < 0) return { summary: body }
+  return {
+    summary:
+      `${body.slice(0, start)}${body.slice(end + DETAILS_CLOSE.length)}`.trim(),
+    details: body.slice(start + DETAILS_OPEN.length, end).trim(),
+  }
+}
+
+/**
+ * The summary text and the details text of an earlier summary message.
+ * `undefined` when `message` is not a summary message.
+ */
+export function readSummary(
+  message: ModelMessage | undefined,
+): { summary: string; details?: string } | undefined {
+  const content = message?.content
+  if (typeof content !== 'string' || !content.startsWith(SUMMARY_OPEN)) {
+    return undefined
+  }
+  const close = content.lastIndexOf(SUMMARY_CLOSE)
+  return splitDetails(
+    content.slice(SUMMARY_OPEN.length, close < 0 ? undefined : close).trim(),
+  )
+}
+
+const SECTIONS = `## Goal
+What the user wants to get done. Keep the user's exact words for each requirement.
+
+## Constraints
+The rules, limits, and preferences that the user or the work set.
+
+## Progress
+What is done, what is in progress, and what failed. Give the file paths, the commands, and the results.
+
+## Key decisions
+Each decision, and the reason for it.
+
+## Next steps
+The next actions, in order.
+
+## Critical context
+The facts that the assistant must not lose: names, values, error messages, and open questions.`
+
+const CHECKPOINT_PROMPT = `You write a checkpoint summary of a conversation between a user and an AI assistant. The assistant continues the work from this summary. It does not see the old messages again.
+
+Write these sections, in this order. Write "None." in a section that has nothing.
+
+${SECTIONS}
+
+Be short and exact. Use only facts from the conversation. Do not answer the user. Write only the summary.`
+
+const UPDATE_PROMPT = `You update a checkpoint summary of a conversation between a user and an AI assistant. The earlier summary is in <previous-summary>. The messages that came after it are in <conversation>. The assistant continues the work from your summary. It does not see the old messages again.
+
+Merge the new messages into the earlier summary. Keep each fact of the earlier summary that is still true. Change each fact that the new messages changed. Move the finished items from "Next steps" to "Progress".
+
+Write these sections, in this order. Write "None." in a section that has nothing.
+
+${SECTIONS}
+
+Be short and exact. Use only facts from the earlier summary and the conversation. Do not answer the user. Write only the summary.`
+
+const TURN_PREFIX_PROMPT = `You summarize the first part of the current turn of a conversation between a user and an AI assistant. The last part of the turn stays in the context. The assistant needs your summary to finish the turn.
+
+Write a short summary of:
+- what the user asked in this turn,
+- what the assistant did in this turn so far: the tool calls and their results,
+- the facts that the rest of the turn needs.
+
+Be short and exact. Use only facts from the conversation. Write only the summary.`
+
+function contentText(content: ModelMessage['content']): string {
+  if (typeof content === 'string') return content
+  return (content ?? [])
+    .map((part) => (part.type === 'text' ? part.content : `[${part.type}]`))
+    .join('\n')
+}
+
+/** The messages as plain text. Each tool result is cut to `maxToolResultChars`. */
+function messagesText(
+  messages: ReadonlyArray<ModelMessage>,
+  maxToolResultChars: number,
+) {
+  return messages
+    .map((message) => {
+      const text = contentText(message.content)
+      if (message.role === 'tool') {
+        const extra = text.length - maxToolResultChars
+        return `[Tool result]: ${extra > 0 ? `${text.slice(0, maxToolResultChars)} [${extra} more characters cut]` : text}`
+      }
+      const calls = (message.toolCalls ?? []).map(
+        (call) =>
+          `[Tool call ${call.function.name}]: ${call.function.arguments}`,
+      )
+      const role = message.role === 'user' ? 'User' : 'Assistant'
+      return [`[${role}]: ${text}`, ...calls].join('\n')
+    })
+    .join('\n\n')
+}
+
+/**
+ * A {@link Summarizer} that asks a text model for a checkpoint summary with
+ * these sections: goal, constraints, progress, key decisions, next steps, and
+ * critical context. With an earlier summary it merges the new messages into
+ * it. It returns the usage of its model call.
+ *
+ * @example
+ * ```ts
+ * summarizeOldest({ summarize: conversationSummarizer({ adapter }) })
+ * ```
+ */
+export function conversationSummarizer(options: {
+  adapter: AnyTextAdapter
+  modelOptions?: Record<string, unknown>
+  /** Each tool result is cut to this many characters in the text to summarize. Default 2000. */
+  maxToolResultChars?: number
+  /**
+   * Text added after the summary, and passed to the next compaction as
+   * previousDetails. It gets each dropped message, also the first part of a
+   * split turn.
+   */
+  details?: (input: {
+    messages: Array<ModelMessage>
+    previousDetails?: string
+  }) => string | undefined
+}): Summarizer {
+  const maxChars = options.maxToolResultChars ?? 2000
+  return async (messages, input) => {
+    const isUpdate = input.previousSummary !== undefined && !input.turnPrefix
+    // The earlier summary goes in <previous-summary>, not in the conversation.
+    const fresh =
+      isUpdate && readSummary(messages[0]) ? messages.slice(1) : messages
+    const conversation = `<conversation>\n${messagesText(fresh, maxChars)}\n</conversation>`
+    const prompt = input.turnPrefix
+      ? TURN_PREFIX_PROMPT
+      : isUpdate
+        ? UPDATE_PROMPT
+        : CHECKPOINT_PROMPT
+    // An object, so the hook below can write it and TypeScript reads it.
+    const spent: { usage?: TokenUsage } = {}
+    const countUsage: ChatMiddleware = {
+      name: 'compaction:summary-usage',
+      onUsage: (_ctx, usage) => {
+        spent.usage = sumUsage(spent.usage, usage)
+      },
+    }
+    // An aborted run must not give an empty summary, so it throws instead.
+    const throwIfAborted = () => {
+      if (!input.signal?.aborted) return
+      const reason: unknown = input.signal.reason
+      throw reason instanceof Error
+        ? reason
+        : new Error('The summary was aborted.')
+    }
+    throwIfAborted()
+    // chat() takes an AbortController, so this one follows the run's signal.
+    const controller = new AbortController()
+    const stop = () => controller.abort(input.signal?.reason)
+    input.signal?.addEventListener('abort', stop, { once: true })
+    let text: string
+    try {
+      text = await chat({
+        adapter: options.adapter,
+        messages: [
+          {
+            role: 'user',
+            content: isUpdate
+              ? `<previous-summary>\n${input.previousSummary}\n</previous-summary>\n\n${conversation}`
+              : conversation,
+          },
+        ],
+        systemPrompts: [prompt],
+        modelOptions: options.modelOptions,
+        middleware: [countUsage],
+        abortController: controller,
+        stream: false,
+      })
+    } finally {
+      input.signal?.removeEventListener('abort', stop)
+    }
+    // chat() can return an empty text when the run is aborted.
+    throwIfAborted()
+    // The details cover each dropped message. A turn-prefix call writes them
+    // only when it gets turnPrefixMessages: then no history call runs.
+    const covered = input.turnPrefix
+      ? input.turnPrefixMessages
+      : [...fresh, ...(input.turnPrefixMessages ?? [])]
+    const details =
+      covered &&
+      options.details?.({
+        messages: covered,
+        ...(input.previousDetails !== undefined
+          ? { previousDetails: input.previousDetails }
+          : {}),
+      })
+    const summary = summaryBody(text.trim(), details)
+    return spent.usage ? { summary, usage: spent.usage } : { summary }
+  }
+}

From 2e7b5dd4f9381b3ca0e1fb77f1d1e7d1b15380f4 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sun, 4 Oct 2026 12:25:09 +0200
Subject: [PATCH 210/286] fix(ai-harness): commit the engine list with log
 records from a middleware

The session log lags the engine during a tool loop: the tool results of
the last phase reach the log only at the next steering commit. A record
that a middleware appended before that commit landed on a list without
those results, so the projection skipped it.

LogRecordsCapability.append now writes the engine's new messages and the
records in one log append. When the engine has no new messages, or its
list changed older messages, it appends only the records. So the staged
records of a running tool batch stay staged, and a saved reply keeps its
run id.
---
 packages/ai-harness/src/log.ts                |  26 +++++
 packages/ai-harness/src/session.ts            |  25 ++---
 .../ai-harness/tests/durable-session.test.ts  | 101 ++++++++++++++++++
 .../ai-harness/tests/durable-tools.test.ts    |  60 ++++++++++-
 4 files changed, 199 insertions(+), 13 deletions(-)

diff --git a/packages/ai-harness/src/log.ts b/packages/ai-harness/src/log.ts
index 5b232f06ac..189989f2da 100644
--- a/packages/ai-harness/src/log.ts
+++ b/packages/ai-harness/src/log.ts
@@ -1107,11 +1107,37 @@ export function engineMessageStore(options: {
         commonPrefix(target, list) === list.length
       return isSame ? undefined : [...target]
     },
+    /**
+     * Host records from a middleware of the running turn. The messages that
+     * the engine added since its last save (the tool results of the last
+     * phase) go first in the same append, as a save puts them. So a record
+     * that counts them lands on a fold that has them. A `list` that changed
+     * older messages is not written: the last save keeps them (for example
+     * the run id that `withPersistence` puts on a reply). A `list` with no
+     * new messages appends only the records, so the staged records of a
+     * running tool batch stay staged.
+     */
+    appendRecords: (
+      list: ReadonlyArray<ModelMessage>,
+      records: ReadonlyArray<LogRecord>,
+    ) => {
+      const kept = commonPrefix(held, list)
+      if (kept < held.length || list.length === held.length) {
+        return writer.append(records)
+      }
+      const target = rebase(held, [...list])
+      held = [...list]
+      return writer.commit({ messages: target, records })
+    },
   } satisfies MessageStore & {
     beforeModel: (
       list: ReadonlyArray<ModelMessage>,
       records?: ReadonlyArray<LogRecord>,
     ) => Promise<Array<ModelMessage> | undefined>
+    appendRecords: (
+      list: ReadonlyArray<ModelMessage>,
+      records: ReadonlyArray<LogRecord>,
+    ) => Promise<void>
   }
   return engine
 }
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 49412744b0..2498841321 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -45,7 +45,6 @@ import type {
   AnyTextAdapter,
   AnyTool,
   Interrupt,
-  LogRecordsWriter,
   Modality,
   ModelMessage,
   PromptCacheOptions,
@@ -1681,22 +1680,24 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
    * On a durable host, each turn's chat run gets `LogRecordsCapability`. A
    * middleware, for example a durable compaction, appends host records with
    * it. They land in the log at once and fold, with the checks of
-   * `session.append`. Agent runs do not get it: a child writes to its own
-   * thread.
+   * `session.append`. The engine's new messages go in the same append, so a
+   * record that counts the tool results of the last phase lands after them.
+   * Agent runs do not get it: a child writes to its own thread.
    */
   private logRecords(): AnyChatMiddleware | undefined {
-    const { writer } = this
-    if (!writer) return undefined
-    const records: LogRecordsWriter = {
-      append: async (list) => {
-        checkHostRecords(list)
-        await writer.append(list)
-      },
-    }
+    const { engine } = this
+    if (!engine) return undefined
     return {
       name: 'harness:log-records',
       provides: [LogRecordsCapability],
-      setup: (ctx) => provideLogRecords(ctx, records),
+      setup: (ctx) =>
+        provideLogRecords(ctx, {
+          append: async (records) => {
+            checkHostRecords(records)
+            // The engine's live list, read at the time of the append.
+            await engine.appendRecords(ctx.messages, records)
+          },
+        }),
     }
   }
 
diff --git a/packages/ai-harness/tests/durable-session.test.ts b/packages/ai-harness/tests/durable-session.test.ts
index 3b971423d3..b6ed04d45d 100644
--- a/packages/ai-harness/tests/durable-session.test.ts
+++ b/packages/ai-harness/tests/durable-session.test.ts
@@ -34,6 +34,16 @@ const project: ProjectOptions = {
         ...messages.slice(record.firstKept),
       ]
     }
+    // Like a durable compaction: `head` replaces the messages before `from`.
+    // A fold that does not have `from` messages yet skips it.
+    if (
+      record.type === 'app.compact-head' &&
+      Array.isArray(record.head) &&
+      typeof record.from === 'number' &&
+      record.from <= messages.length
+    ) {
+      return [...record.head, ...messages.slice(record.from)]
+    }
     return undefined
   },
 }
@@ -568,6 +578,35 @@ describe('LogRecordsCapability', () => {
     await host.close()
   })
 
+  it('keeps the saved reply when a record lands from onFinish', async () => {
+    const persistence = durablePersistence()
+    const { adapter } = mockAdapter([() => text('a1')])
+    const note: ChatMiddleware = {
+      name: 'test:note',
+      onFinish: async (ctx) => {
+        await getLogRecords(ctx).append([{ type: 'app.note' }])
+      },
+    }
+    const host = createHarnessHost({ persistence, project })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/log-records-note',
+        adapter,
+        middleware: [note],
+      }),
+      { threadId: THREAD },
+    )
+
+    await session.prompt('q1')
+
+    // The saved reply has its run id. The engine's copy has none, and it
+    // must not replace the saved one.
+    expect((await session.transcript()).at(-1)?.metadata).toMatchObject({
+      tanstack: { run: { id: expect.any(String) } },
+    })
+    await host.close()
+  })
+
   it('refuses a record type that the harness owns', async () => {
     let failure: unknown
     const bad: ChatMiddleware = {
@@ -738,4 +777,66 @@ describe('compaction-style host records from a middleware', () => {
     ])
     await host.close()
   })
+
+  it('lands a record from onConfig after a tool phase on its tool results', async () => {
+    const persistence = durablePersistence()
+    const lookup = toolDefinition({
+      name: 'lookup',
+      description: 'Look up the weather',
+    }).server(async () => 'sunny')
+    // Two tool calls in one model call, so they run in one tool phase.
+    const bothCalls = () => [
+      ...toolCall('lookup', { city: 'Berlin' }, 'call-1').slice(0, -1),
+      ...toolCall('lookup', { city: 'Paris' }, 'call-2').slice(1),
+    ]
+    const { adapter, calls } = mockAdapter([
+      () => bothCalls(),
+      () => text('Both are sunny.'),
+    ])
+    // Like a durable compaction before the call after the tool phase: it
+    // clears the first result. The record counts the engine's messages, with
+    // tool results that the log does not have yet.
+    const clearFirst: ChatMiddleware = {
+      name: 'test:clear-first',
+      onConfig: async (ctx, config) => {
+        const [question, answer, first] = config.messages
+        if (ctx.phase !== 'beforeModel' || first?.role !== 'tool') return
+        await getLogRecords(ctx).append([
+          {
+            type: 'app.compact-head',
+            head: [question, answer, { ...first, content: '[cleared]' }],
+            from: 3,
+          },
+        ])
+      },
+    }
+    const host = createHarnessHost({ persistence, project })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/tool-phase-record',
+        adapter,
+        tools: [lookup],
+        middleware: [clearFirst],
+      }),
+      { threadId: THREAD },
+    )
+
+    await session.prompt('Weather in Berlin and Paris?')
+
+    // Each result once, and the first one cleared.
+    const results = (messages: ReadonlyArray<ModelMessage>) =>
+      messages
+        .filter((message) => message.role === 'tool')
+        .map((message) => [message.toolCallId, message.content])
+    const cleared = [
+      ['call-1', '[cleared]'],
+      ['call-2', 'sunny'],
+    ]
+    expect(results(calls[1].messages)).toEqual(cleared)
+    const transcript = await session.transcript()
+    expect(results(transcript)).toEqual(cleared)
+    expect(transcript.at(-1)?.content).toBe('Both are sunny.')
+    expect(await rebuild(persistence)).toEqual(transcript)
+    await host.close()
+  })
 })
diff --git a/packages/ai-harness/tests/durable-tools.test.ts b/packages/ai-harness/tests/durable-tools.test.ts
index 990c2a9328..98ba7f9fac 100644
--- a/packages/ai-harness/tests/durable-tools.test.ts
+++ b/packages/ai-harness/tests/durable-tools.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 import { z } from 'zod'
-import { EventType, toolDefinition } from '@tanstack/ai'
+import { EventType, getLogRecords, toolDefinition } from '@tanstack/ai'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness, durableTool } from '../src'
 import { INTERRUPTED_TOOL_RESULT } from '../src/resume'
@@ -265,6 +265,64 @@ describe('host records of a tool batch', () => {
     await first.host.close().catch(() => {})
     await next.host.close().catch(() => {})
   })
+
+  it('keeps them staged when a middleware appends records in the batch', async () => {
+    const persistence = durablePersistence()
+    const appended = gate()
+    const audited = gate()
+    const note = durableTool(
+      noteDefinition,
+      async (_args, { append, abortSignal }) => {
+        append([{ type: 'app.state_write', name: 'x', value: 1 }])
+        appended.open()
+        // Still runs when the middleware appends.
+        return untilAborted(abortSignal)
+      },
+    )
+    const quick = toolDefinition({
+      name: 'quick',
+      description: 'Answer at once',
+    }).server(async () => {
+      await appended.opened
+      return 'ok'
+    })
+    // Appends a record when `quick` ends, while `note` still runs.
+    const audit: AnyChatMiddleware = {
+      name: 'test:audit',
+      onAfterToolCall: async (ctx, info) => {
+        if (info.toolCallId !== 'call-quick') return
+        await getLogRecords(ctx).append([{ type: 'app.audit' }])
+        audited.open()
+      },
+    }
+    const { adapter } = mockAdapter([
+      () =>
+        toolCalls([
+          { id: 'call-note', name: 'note' },
+          { id: 'call-quick', name: 'quick' },
+        ]),
+    ])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/durable-tools-audit',
+        adapter,
+        tools: [note, quick],
+        middleware: [audit],
+      }),
+      { threadId: THREAD },
+    )
+    const turn = session.prompt('note and check', { inputId: 'audit-1' })
+    await audited.opened
+
+    expect(await recordsOf(persistence, 'app.audit')).toEqual([
+      { type: 'app.audit' },
+    ])
+    // The batch did not complete, so the staged record is not in the log.
+    expect(await recordsOf(persistence, 'app.state_write')).toEqual([])
+    await host.close().catch(() => {})
+    await Promise.resolve(turn).catch(() => {})
+  })
 })
 
 describe('a durable tool with replay: never', () => {

From eb034cb0da6f9ee00ef91d986a266a14b55a950d Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sun, 4 Oct 2026 12:25:09 +0200
Subject: [PATCH 211/286] test(e2e): check durable compaction in a harness
 session

A provider-free route runs withCompaction({ durable: true }) in a harness
session with a scripted fetch. It checks four cases: a silent overflow on
a finished answer, an overflow error with compactNext and one retry, the
turn-control example, and a parallel tool phase where clearToolResults
clears the oldest result. For each case, a second host rebuilds the same
transcript from the log.
---
 testing/e2e/src/routeTree.gen.ts              |  22 ++
 .../src/routes/api.compaction-durable-wire.ts | 344 ++++++++++++++++++
 .../e2e/tests/compaction-durable-wire.spec.ts |  94 +++++
 3 files changed, 460 insertions(+)
 create mode 100644 testing/e2e/src/routes/api.compaction-durable-wire.ts
 create mode 100644 testing/e2e/tests/compaction-durable-wire.spec.ts

diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index a5c6b39828..496468b0de 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -119,6 +119,7 @@ import { Route as ApiDurableTakeoverRouteImport } from './routes/api.durable-tak
 import { Route as ApiDurableDeliveryRouteImport } from './routes/api.durable-delivery'
 import { Route as ApiDevtoolsMemoryRouteImport } from './routes/api.devtools-memory'
 import { Route as ApiCompactionWireRouteImport } from './routes/api.compaction-wire'
+import { Route as ApiCompactionDurableWireRouteImport } from './routes/api.compaction-durable-wire'
 import { Route as ApiCloudflareBindingWireRouteImport } from './routes/api.cloudflare-binding-wire'
 import { Route as ApiChatRouteImport } from './routes/api.chat'
 import { Route as ApiByteplusSeedance1080pWireRouteImport } from './routes/api.byteplus-seedance-1080p-wire'
@@ -713,6 +714,12 @@ const ApiCompactionWireRoute = ApiCompactionWireRouteImport.update({
   path: '/api/compaction-wire',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiCompactionDurableWireRoute =
+  ApiCompactionDurableWireRouteImport.update({
+    id: '/api/compaction-durable-wire',
+    path: '/api/compaction-durable-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
 const ApiCloudflareBindingWireRoute =
   ApiCloudflareBindingWireRouteImport.update({
     id: '/api/cloudflare-binding-wire',
@@ -873,6 +880,7 @@ export interface FileRoutesByFullPath {
   '/api/byteplus-seedance-1080p-wire': typeof ApiByteplusSeedance1080pWireRoute
   '/api/chat': typeof ApiChatRoute
   '/api/cloudflare-binding-wire': typeof ApiCloudflareBindingWireRoute
+  '/api/compaction-durable-wire': typeof ApiCompactionDurableWireRoute
   '/api/compaction-wire': typeof ApiCompactionWireRoute
   '/api/devtools-memory': typeof ApiDevtoolsMemoryRoute
   '/api/durable-delivery': typeof ApiDurableDeliveryRoute
@@ -1006,6 +1014,7 @@ export interface FileRoutesByTo {
   '/api/byteplus-seedance-1080p-wire': typeof ApiByteplusSeedance1080pWireRoute
   '/api/chat': typeof ApiChatRoute
   '/api/cloudflare-binding-wire': typeof ApiCloudflareBindingWireRoute
+  '/api/compaction-durable-wire': typeof ApiCompactionDurableWireRoute
   '/api/compaction-wire': typeof ApiCompactionWireRoute
   '/api/devtools-memory': typeof ApiDevtoolsMemoryRoute
   '/api/durable-delivery': typeof ApiDurableDeliveryRoute
@@ -1140,6 +1149,7 @@ export interface FileRoutesById {
   '/api/byteplus-seedance-1080p-wire': typeof ApiByteplusSeedance1080pWireRoute
   '/api/chat': typeof ApiChatRoute
   '/api/cloudflare-binding-wire': typeof ApiCloudflareBindingWireRoute
+  '/api/compaction-durable-wire': typeof ApiCompactionDurableWireRoute
   '/api/compaction-wire': typeof ApiCompactionWireRoute
   '/api/devtools-memory': typeof ApiDevtoolsMemoryRoute
   '/api/durable-delivery': typeof ApiDurableDeliveryRoute
@@ -1275,6 +1285,7 @@ export interface FileRouteTypes {
     | '/api/byteplus-seedance-1080p-wire'
     | '/api/chat'
     | '/api/cloudflare-binding-wire'
+    | '/api/compaction-durable-wire'
     | '/api/compaction-wire'
     | '/api/devtools-memory'
     | '/api/durable-delivery'
@@ -1408,6 +1419,7 @@ export interface FileRouteTypes {
     | '/api/byteplus-seedance-1080p-wire'
     | '/api/chat'
     | '/api/cloudflare-binding-wire'
+    | '/api/compaction-durable-wire'
     | '/api/compaction-wire'
     | '/api/devtools-memory'
     | '/api/durable-delivery'
@@ -1541,6 +1553,7 @@ export interface FileRouteTypes {
     | '/api/byteplus-seedance-1080p-wire'
     | '/api/chat'
     | '/api/cloudflare-binding-wire'
+    | '/api/compaction-durable-wire'
     | '/api/compaction-wire'
     | '/api/devtools-memory'
     | '/api/durable-delivery'
@@ -1675,6 +1688,7 @@ export interface RootRouteChildren {
   ApiByteplusSeedance1080pWireRoute: typeof ApiByteplusSeedance1080pWireRoute
   ApiChatRoute: typeof ApiChatRoute
   ApiCloudflareBindingWireRoute: typeof ApiCloudflareBindingWireRoute
+  ApiCompactionDurableWireRoute: typeof ApiCompactionDurableWireRoute
   ApiCompactionWireRoute: typeof ApiCompactionWireRoute
   ApiDevtoolsMemoryRoute: typeof ApiDevtoolsMemoryRoute
   ApiDurableDeliveryRoute: typeof ApiDurableDeliveryRoute
@@ -2529,6 +2543,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiCompactionWireRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/compaction-durable-wire': {
+      id: '/api/compaction-durable-wire'
+      path: '/api/compaction-durable-wire'
+      fullPath: '/api/compaction-durable-wire'
+      preLoaderRoute: typeof ApiCompactionDurableWireRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/cloudflare-binding-wire': {
       id: '/api/cloudflare-binding-wire'
       path: '/api/cloudflare-binding-wire'
@@ -2785,6 +2806,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiByteplusSeedance1080pWireRoute: ApiByteplusSeedance1080pWireRoute,
   ApiChatRoute: ApiChatRoute,
   ApiCloudflareBindingWireRoute: ApiCloudflareBindingWireRoute,
+  ApiCompactionDurableWireRoute: ApiCompactionDurableWireRoute,
   ApiCompactionWireRoute: ApiCompactionWireRoute,
   ApiDevtoolsMemoryRoute: ApiDevtoolsMemoryRoute,
   ApiDurableDeliveryRoute: ApiDurableDeliveryRoute,
diff --git a/testing/e2e/src/routes/api.compaction-durable-wire.ts b/testing/e2e/src/routes/api.compaction-durable-wire.ts
new file mode 100644
index 0000000000..bc525a5da9
--- /dev/null
+++ b/testing/e2e/src/routes/api.compaction-durable-wire.ts
@@ -0,0 +1,344 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, isContextOverflow, toolDefinition } from '@tanstack/ai'
+import { createOpenaiChat } from '@tanstack/ai-openai'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import {
+  COMPACTION_RECORD_TYPE,
+  clearToolResults,
+  projectCompaction,
+  summarizeOldest,
+  withCompaction,
+} from '@tanstack/ai-compaction'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { z } from 'zod'
+import type { AnyTextAdapter, ModelMessage } from '@tanstack/ai'
+
+/**
+ * Durable compaction in a harness session, end to end, with the real
+ * `withCompaction({ durable: true })`. A scripted `fetch` answers each
+ * OpenAI Responses call, so no aimock fixture is needed. The usage of a call
+ * is ceil(characters / 4) of the request body, like a faux model.
+ *
+ * POST `{ case }`:
+ * - `silent-overflow`: Flue's settings. The second answer is over the context
+ *   window with no error, so the after-turn check compacts: 3 calls.
+ * - `error-overflow`: the second call fails with an overflow error.
+ *   `turn.onModelError` calls `compactNext` and retries once: 4 calls.
+ * - `turn-control`: the docs example. `auto: false` on a short chat, an
+ *   overflow error, then `compactNext` and one retry: 4 calls.
+ * - `parallel-tools`: the model calls 4 tools in one phase. Before the next
+ *   call, `clearToolResults()` clears the oldest result and keeps 3: 2 calls.
+ *
+ * Each case then opens a second host on the same log and returns its
+ * transcript, so the spec can check that a rebuild gives the same context.
+ */
+
+const DUMMY_KEY = 'sk-e2e-test-dummy-key'
+const THREAD = 'compaction-durable-wire'
+const CONTEXT_WINDOW = 32_768
+const MAX_OUTPUT = 4_096
+const LONG_PROMPT = 'x'.repeat(70_000)
+const OVERFLOW = 'Your input exceeds the context window of this model.'
+
+type Case =
+  | 'silent-overflow'
+  | 'error-overflow'
+  | 'turn-control'
+  | 'parallel-tools'
+type Step = { text: string } | { error: string } | { tools: number }
+
+const SCRIPTS: Record<Case, Array<Step>> = {
+  'silent-overflow': [
+    { text: 'First response.' },
+    { text: 'Completed response.' },
+    { text: 'Conversation summary.' },
+  ],
+  'error-overflow': [
+    { text: 'First response.' },
+    { error: OVERFLOW },
+    { text: 'Conversation summary.' },
+    { text: 'Recovered response.' },
+  ],
+  'turn-control': [
+    { text: 'a1' },
+    { error: OVERFLOW },
+    { text: 'Earlier: the first question.' },
+    { text: 'fits now' },
+  ],
+  'parallel-tools': [{ tools: 4 }, { text: 'All parts read.' }],
+}
+
+const PROMPTS: Record<Case, Array<string>> = {
+  'silent-overflow': [LONG_PROMPT, LONG_PROMPT],
+  'error-overflow': [LONG_PROMPT, LONG_PROMPT],
+  'turn-control': ['first question OLD_DETAIL', 'second question'],
+  'parallel-tools': ['Read parts 1 to 4.'],
+}
+
+/** Each result is about 500 tokens, so 4 of them are over `maxTokens`. */
+const readPart = toolDefinition({
+  name: 'read_part',
+  description: 'Read one part of a long file.',
+  inputSchema: z.object({ part: z.number() }),
+}).server(({ part }) => `RESULT_${part} ${'r'.repeat(2_000)}`)
+
+function caseOf(body: unknown): Case | undefined {
+  if (typeof body !== 'object' || body === null || !('case' in body)) {
+    return undefined
+  }
+  const value = body.case
+  return value === 'silent-overflow' ||
+    value === 'error-overflow' ||
+    value === 'turn-control' ||
+    value === 'parallel-tools'
+    ? value
+    : undefined
+}
+
+function sse(events: Array<Record<string, unknown>>) {
+  const body = `${events.map((event) => `data: ${JSON.stringify(event)}\n\n`).join('')}data: [DONE]\n\n`
+  return new Response(body, {
+    headers: { 'Content-Type': 'text/event-stream' },
+  })
+}
+
+/**
+ * One Responses API stream: a text answer or parallel tool calls with usage,
+ * or a failed response.
+ */
+function reply(step: Step, call: number, inputTokens: number) {
+  const id = `resp_durable_${call}`
+  const created = {
+    type: 'response.created',
+    response: { id, object: 'response', status: 'in_progress', output: [] },
+  }
+  if ('error' in step) {
+    return sse([
+      created,
+      {
+        type: 'response.failed',
+        response: {
+          id,
+          object: 'response',
+          status: 'failed',
+          output: [],
+          error: { code: 'context_length_exceeded', message: step.error },
+        },
+      },
+    ])
+  }
+  const completed = (output: Array<Record<string, unknown>>, text: string) => {
+    const outputTokens = Math.ceil(text.length / 4)
+    return {
+      type: 'response.completed',
+      response: {
+        id,
+        object: 'response',
+        status: 'completed',
+        output,
+        usage: {
+          input_tokens: inputTokens,
+          output_tokens: outputTokens,
+          total_tokens: inputTokens + outputTokens,
+        },
+      },
+    }
+  }
+  if ('tools' in step) {
+    const calls = Array.from({ length: step.tools }, (_, index) => ({
+      id: `fc_durable_${call}_${index + 1}`,
+      call_id: `call_part_${index + 1}`,
+      type: 'function_call',
+      name: 'read_part',
+      arguments: JSON.stringify({ part: index + 1 }),
+      status: 'completed',
+    }))
+    return sse([
+      created,
+      ...calls.flatMap((item, index) => [
+        {
+          type: 'response.output_item.added',
+          response_id: id,
+          output_index: index,
+          item,
+        },
+        {
+          type: 'response.function_call_arguments.done',
+          response_id: id,
+          item_id: item.id,
+          output_index: index,
+          arguments: item.arguments,
+        },
+      ]),
+      completed(calls, JSON.stringify(calls)),
+    ])
+  }
+  const itemId = `msg_durable_${call}`
+  return sse([
+    created,
+    {
+      type: 'response.output_text.delta',
+      response_id: id,
+      item_id: itemId,
+      output_index: 0,
+      content_index: 0,
+      delta: step.text,
+    },
+    completed(
+      [
+        {
+          id: itemId,
+          type: 'message',
+          role: 'assistant',
+          status: 'completed',
+          content: [{ type: 'output_text', text: step.text }],
+        },
+      ],
+      step.text,
+    ),
+  ])
+}
+
+/** A `fetch` that answers each call with the next step, and keeps each body. */
+function scriptedFetch(steps: Array<Step>) {
+  const bodies: Array<unknown> = []
+  const fetch: typeof globalThis.fetch = async (input, init) => {
+    const body: unknown = await new Request(input, init).json()
+    bodies.push(body)
+    const step = steps[bodies.length - 1] ?? {
+      error: 'No more scripted responses.',
+    }
+    return reply(
+      step,
+      bodies.length,
+      Math.ceil(JSON.stringify(body).length / 4),
+    )
+  }
+  return { fetch, bodies }
+}
+
+/** The summary is one more call of the same model, as in Flue. */
+const summarizeWith =
+  (adapter: AnyTextAdapter) => (messages: Array<ModelMessage>) =>
+    chat({
+      adapter,
+      messages: [
+        {
+          role: 'user',
+          content: `Summarize this conversation.\n\n${messages
+            .map(
+              (message) =>
+                `${message.role}: ${typeof message.content === 'string' ? message.content : JSON.stringify(message.content)}`,
+            )
+            .join('\n')}`,
+        },
+      ],
+      stream: false,
+    })
+
+function compactionFor(testCase: Case, adapter: AnyTextAdapter) {
+  if (testCase === 'parallel-tools') {
+    return withCompaction({
+      maxTokens: 1_000,
+      durable: true,
+      strategy: clearToolResults(),
+    })
+  }
+  const summarize = summarizeWith(adapter)
+  if (testCase === 'turn-control') {
+    return withCompaction({
+      maxTokens: 100_000,
+      auto: false,
+      durable: true,
+      strategy: summarizeOldest({ summarize, keepRecentTokens: 1 }),
+    })
+  }
+  // Flue's `compaction: false`: no threshold compaction. The overflow check
+  // after the turn and compactNext still run.
+  return withCompaction({
+    maxTokens: CONTEXT_WINDOW - MAX_OUTPUT,
+    contextWindow: CONTEXT_WINDOW,
+    countTokens: 'usage',
+    auto: false,
+    durable: true,
+    strategy: summarizeOldest({ summarize, keepRecentTokens: 20_000 }),
+  })
+}
+
+export const Route = createFileRoute('/api/compaction-durable-wire')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const testCase = caseOf(await request.json())
+        if (!testCase) {
+          return Response.json({ ok: false, error: 'Unknown case.' })
+        }
+        const { fetch, bodies } = scriptedFetch(SCRIPTS[testCase])
+        const adapter = createOpenaiChat('gpt-5.2', DUMMY_KEY, { fetch })
+        const compaction = compactionFor(testCase, adapter)
+        const harness = defineHarness({
+          name: 'e2e/compaction-durable-wire',
+          adapter,
+          tools: testCase === 'parallel-tools' ? [readPart] : [],
+          middleware: [compaction],
+          turn: {
+            // Flue's rule: after an overflow error, compact and retry once.
+            onModelError: ({ error, retries, session }) => {
+              if (retries > 0 || !isContextOverflow({ error: error.message })) {
+                return undefined
+              }
+              compaction.compactNext(session.threadId)
+              return 'retry'
+            },
+          },
+        })
+        const { runs, metadata } = memoryPersistence().stores
+        const persistence = {
+          stores: { log: memoryLogStore(), runs, metadata },
+        }
+        const project = { version: 'v1', record: projectCompaction }
+
+        const texts: Array<string> = []
+        let transcript: Array<ModelMessage>
+        const first = createHarnessHost({ persistence, project })
+        try {
+          const session = await first.open(harness, { threadId: THREAD })
+          for (const prompt of PROMPTS[testCase]) {
+            texts.push((await session.prompt(prompt)).text)
+          }
+          transcript = await session.transcript()
+        } catch (error) {
+          return Response.json({
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+          })
+        } finally {
+          await first.close()
+        }
+
+        // A second host folds the same log again.
+        const second = createHarnessHost({ persistence, project })
+        let rebuilt: Array<ModelMessage>
+        try {
+          const reopened = await second.open(harness, { threadId: THREAD })
+          rebuilt = await reopened.transcript()
+        } finally {
+          await second.close()
+        }
+
+        const entries = await persistence.stores.log.read(THREAD, { after: 0 })
+        return Response.json({
+          ok: true,
+          calls: bodies.length,
+          texts,
+          transcript,
+          rebuilt,
+          records: entries
+            .filter((entry) => entry.record.type === COMPACTION_RECORD_TYPE)
+            .map((entry) => entry.record.reason),
+          lastRequest: bodies.at(-1),
+        })
+      },
+    },
+  },
+})
diff --git a/testing/e2e/tests/compaction-durable-wire.spec.ts b/testing/e2e/tests/compaction-durable-wire.spec.ts
new file mode 100644
index 0000000000..917774d7ef
--- /dev/null
+++ b/testing/e2e/tests/compaction-durable-wire.spec.ts
@@ -0,0 +1,94 @@
+import { z } from 'zod'
+import type { APIRequestContext } from '@playwright/test'
+import { test, expect } from './fixtures'
+
+const STUB = '[tool output cleared'
+
+const Message = z.object({
+  role: z.string(),
+  content: z.unknown(),
+  toolCallId: z.string().optional(),
+})
+
+const Result = z.object({
+  ok: z.literal(true),
+  calls: z.number(),
+  texts: z.array(z.string()),
+  transcript: z.array(Message),
+  rebuilt: z.array(Message),
+  records: z.array(z.string()),
+  lastRequest: z.object({
+    input: z.array(z.record(z.string(), z.unknown())),
+  }),
+})
+
+test.describe('compaction: durable records in a harness session', () => {
+  async function run(request: APIRequestContext, testCase: string) {
+    const response = await request.post('/api/compaction-durable-wire', {
+      data: { case: testCase },
+    })
+    expect(response.ok()).toBe(true)
+    const json: unknown = await response.json()
+    return Result.parse(json)
+  }
+
+  test('the after-turn check compacts a silent overflow', async ({
+    request,
+  }) => {
+    const result = await run(request, 'silent-overflow')
+    expect(result.texts).toEqual(['First response.', 'Completed response.'])
+    expect(result.calls).toBe(3)
+    expect(result.records).toEqual(['after-turn'])
+    expect(result.rebuilt).toEqual(result.transcript)
+  })
+
+  test('an overflow error compacts and retries once', async ({ request }) => {
+    const result = await run(request, 'error-overflow')
+    expect(result.texts).toEqual(['First response.', 'Recovered response.'])
+    expect(result.calls).toBe(4)
+    expect(result.records).toEqual(['forced'])
+    expect(result.rebuilt).toEqual(result.transcript)
+  })
+
+  test('turn control calls compactNext and retries', async ({ request }) => {
+    const result = await run(request, 'turn-control')
+    expect(result.texts).toEqual(['a1', 'fits now'])
+    expect(result.calls).toBe(4)
+    expect(result.records).toEqual(['forced'])
+    expect(result.rebuilt).toEqual(result.transcript)
+  })
+
+  test('parallel tools: only the oldest result is cleared', async ({
+    request,
+  }) => {
+    const result = await run(request, 'parallel-tools')
+    expect(result.texts).toEqual(['All parts read.'])
+    expect(result.calls).toBe(2)
+    expect(result.records).toEqual(['threshold'])
+    expect(result.transcript).toHaveLength(7)
+    expect(result.rebuilt).toEqual(result.transcript)
+
+    const tools = result.transcript.filter((m) => m.role === 'tool')
+    expect(tools.map((m) => m.toolCallId)).toEqual([
+      'call_part_1',
+      'call_part_2',
+      'call_part_3',
+      'call_part_4',
+    ])
+    expect(String(tools[0]?.content)).toContain(STUB)
+    tools.slice(1).forEach((m, index) => {
+      expect(String(m.content)).toContain(`RESULT_${index + 2}`)
+    })
+
+    const outputs = result.lastRequest.input.filter(
+      (item) => item.type === 'function_call_output',
+    )
+    expect(outputs.map((item) => item.call_id)).toEqual([
+      'call_part_1',
+      'call_part_2',
+      'call_part_3',
+      'call_part_4',
+    ])
+    expect(String(outputs[0]?.output)).toContain(STUB)
+  })
+})

From a05e8c4ef0c7428c18512ddf30b95d7429bc5f8a Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Sun, 4 Oct 2026 13:10:30 +0200
Subject: [PATCH 212/286] docs(ai-compaction): document usage counts,
 compactNext, durable compaction, and better summaries

- docs/advanced/compaction.md: countTokens 'usage', compactNext and auto,
  reason, usage and error, continueOnError, the after-turn check, durable
  records, and the summary options (cut: 'turn', conversationSummarizer,
  details).
- docs/harness/compaction.md (new): compact a harness session, retry
  after a context overflow, and keep the same context after a restart.
- turn-control, session-log, coding-agent, and testing pages link to it,
  and session-log documents getLogRecords.
- The ai-compaction README lists the new options.
- Changesets for @tanstack/ai-compaction, @tanstack/ai, and
  @tanstack/ai-harness.
---
 .changeset/compaction-usage-and-durable.md |  12 ++
 .changeset/log-records-capability.md       |   6 +
 docs/advanced/compaction.md                | 185 +++++++++++++++++++--
 docs/advanced/testing.md                   |   2 +-
 docs/config.json                           |  13 +-
 docs/harness/coding-agent.md               |   2 +
 docs/harness/compaction.md                 | 119 +++++++++++++
 docs/harness/session-log.md                |  12 +-
 docs/harness/turn-control.md               |  18 +-
 packages/ai-compaction/README.md           |  46 ++---
 10 files changed, 356 insertions(+), 59 deletions(-)
 create mode 100644 .changeset/compaction-usage-and-durable.md
 create mode 100644 .changeset/log-records-capability.md
 create mode 100644 docs/harness/compaction.md

diff --git a/.changeset/compaction-usage-and-durable.md b/.changeset/compaction-usage-and-durable.md
new file mode 100644
index 0000000000..abc6da631c
--- /dev/null
+++ b/.changeset/compaction-usage-and-durable.md
@@ -0,0 +1,12 @@
+---
+'@tanstack/ai-compaction': minor
+---
+
+Count with real usage, compact on demand, and keep compaction in a harness log.
+
+- `countTokens: 'usage'` counts with the usage the provider reported for the last call, plus an estimate of the newer messages.
+- `compactNext(threadId)` compacts at the next model call, for example after a context overflow. `auto: false` turns off compaction at `maxTokens` and keeps `compactNext` and the overflow check.
+- With `countTokens: 'usage'` and `durable: true`, a harness turn checks once more after its last model call. When the usage passed `maxTokens` or `contextWindow`, compaction runs right away. `contextWindow` also counts with `auto: false`.
+- `durable: true` writes a `tanstack.compaction` record into a harness session log. Set `project: { version, record: projectCompaction }` on the host.
+- `compaction:ended` and `onCompact` report `reason`, the summary `usage`, and an `error`. `continueOnError` sends the full messages when the strategy fails.
+- `summarizeOldest({ cut: 'turn' })` gives the start of a cut turn its own summary. `conversationSummarizer` writes a structured summary, updates the older summary, and takes a `details` hook.
diff --git a/.changeset/log-records-capability.md b/.changeset/log-records-capability.md
new file mode 100644
index 0000000000..b23d5fc935
--- /dev/null
+++ b/.changeset/log-records-capability.md
@@ -0,0 +1,6 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-harness': minor
+---
+
+Add `LogRecordsCapability`. A chat middleware can append records to the durable session log of its run. A durable harness host provides it to the chat run of each session turn. Agent runs do not get it.
diff --git a/docs/advanced/compaction.md b/docs/advanced/compaction.md
index 14fb2554ed..f617db1c29 100644
--- a/docs/advanced/compaction.md
+++ b/docs/advanced/compaction.md
@@ -51,7 +51,7 @@ Pass `strategy` to change how the history shrinks. Three are built in.
 | Strategy | What it does | Cost |
 |----------|--------------|------|
 | `evictOldest` (default) | Drop the oldest messages, leave a marker | No extra model call |
-| `summarizeOldest` | Replace the oldest messages with an LLM summary | One summarize call |
+| `summarizeOldest` | Replace the oldest messages with an LLM summary | One summarize call (two with `cut: 'turn'`) |
 | `clearToolResults` | Stub the content of old tool results, keep the messages | No extra model call |
 
 ### evictOldest
@@ -77,23 +77,23 @@ import { openaiText, openaiSummarize } from "@tanstack/ai-openai";
 import { withCompaction, summarizeOldest } from "@tanstack/ai-compaction";
 import type { ModelMessage } from "@tanstack/ai";
 
-async function summarizeHistory(messages: Array<ModelMessage>): Promise<string> {
+async function summarizeHistory(messages: Array<ModelMessage>) {
   const text = messages
     .map((m) => `${m.role}: ${typeof m.content === "string" ? m.content : ""}`)
     .join("\n");
 
-  const { summary } = await summarize({
-    adapter: openaiSummarize("gpt-5.5"),
+  // Return the whole result. Compaction reports its `usage`.
+  return summarize({
+    adapter: openaiSummarize("gpt-6.1-sol"),
     text,
   });
-  return summary;
 }
 
 export async function POST(request: Request) {
   const { messages } = await request.json();
 
   const stream = chat({
-    adapter: openaiText("gpt-5.5"),
+    adapter: openaiText("gpt-6.1-sol"),
     messages,
     middleware: [
       withCompaction({
@@ -107,6 +107,8 @@ export async function POST(request: Request) {
 }
 ```
 
+`summarize` can return the summary text, or an object with `summary` and `usage`. Return the `summarize()` result as it is, so compaction can report what the summary cost.
+
 ### clearToolResults
 
 Best for agent loops. Tool output (file reads, command output) is usually most of the tokens. This strategy replaces the content of old tool results with a stub and keeps every message and its tool-call pairing in place. The conversation shape does not change.
@@ -123,7 +125,7 @@ withCompaction({
 
 ### Write your own
 
-A strategy is a function. It gets the messages and the budget, and returns the rewritten messages, or `null` to change nothing. It runs only when the estimate is over `maxTokens`.
+A strategy is a function. It gets the messages and the budget, and returns the rewritten messages, or `null` to change nothing. It runs when the count is over `maxTokens`, and when `compactNext` forces it. Then the count can be under `maxTokens`.
 
 ```typescript
 import { withCompaction } from "@tanstack/ai-compaction";
@@ -170,22 +172,94 @@ withCompaction({
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `maxTokens` | `number` | - | **Required.** Compact when the estimated tokens across `messages` pass this. |
+| `maxTokens` | `number` | - | **Required.** Compact when the token count of `messages` passes this. See `countTokens`. |
 | `strategy` | `CompactionStrategy` | `evictOldest()` | How to shrink the messages. |
 | `estimateTokens` | `(message: ModelMessage) => number` | characters / 4 | Per-message token estimate. Pass a real tokenizer if you need exact counts. |
 | `strategyKey` | `string` | built-in strategy identity | Stable checkpoint identity. Set it for custom strategies, custom estimators, or a custom eviction marker. Change it when your `summarize` function can change. |
-| `onCompact` | `(info: CompactionInfo) => void` | - | Runs after each compaction. `info` is `{ before, after, messagesBefore, messagesAfter }` (token and message counts). |
+| `onCompact` | `(info: CompactionInfo) => void` | - | Runs after each compaction. `info` is `{ before, after, messagesBefore, messagesAfter, reason, usage, error }`. `error` is set only when the check after a harness turn fails. |
+| `countTokens` | `'estimate' \| 'usage'` | `'estimate'` | `'usage'` counts with the usage the provider reported for the last call. See [Count with real usage](#count-with-real-usage). |
+| `auto` | `boolean` | `true` | `false` turns off compaction at `maxTokens`. `compactNext` and the overflow check still run. |
+| `contextWindow` | `number` | - | The model's context window. With `countTokens: 'usage'` and `durable: true` in a harness with a log, compaction also runs after a turn whose usage passed it, even with `auto: false`. |
+| `durable` | `boolean` | `false` | In a harness with a log, write the result into the session log. See [Compact a harness session](../harness/compaction). |
+| `continueOnError` | `boolean` | `false` | When the strategy fails, send the full messages and go on. By default the run fails. |
 
 ### Strategy options
 
 | Strategy | Options |
 |----------|---------|
 | `evictOldest` | `keepRecentTokens` (default `maxTokens / 2`), `marker` |
-| `summarizeOldest` | `summarize` (**required**), `keepRecentTokens`, `summaryRole` (default `assistant`) |
+| `summarizeOldest` | `summarize` (**required**), `keepRecentTokens`, `summaryRole` (default `assistant`), `cut` (default `'message'`) |
 | `clearToolResults` | `keepRecentToolResults` (default `3`), `stub` |
 
 The token count is a rough `characters / 4` estimate. It is good enough to trigger on, not exact. Pass `estimateTokens` for provider-accurate counts.
 
+## Count with real usage
+
+The `characters / 4` estimate drifts on long agent runs. Code, JSON, and other languages do not split into tokens like English text. Then compaction runs too late and the call fails, or it runs too early and drops context you still need.
+
+Set `countTokens: 'usage'`. After each model call, compaction saves the usage that the provider reported. The next check starts from that number and estimates only the messages that came after it.
+
+```ts group=compaction-usage
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { withCompaction } from '@tanstack/ai-compaction'
+
+export async function POST(request: Request) {
+  const { messages } = await request.json()
+
+  const stream = chat({
+    adapter: openaiText('gpt-6.1-sol'),
+    messages,
+    middleware: [withCompaction({ maxTokens: 100_000, countTokens: 'usage' })],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+- Before the first model call there is no usage yet, so compaction uses the estimate.
+- With a [`metadata` store](#compaction-and-persistence), the usage is saved. The next request and a restarted server start from the real count.
+- The strategies still use the estimate to choose which messages to keep.
+
+## Set the limit from the context window
+
+Most models publish a context window. Keep room for the answer: set `maxTokens` to the window minus a reserve.
+
+```ts group=compaction-usage
+import { summarizeOldest } from '@tanstack/ai-compaction'
+import { summarize } from '@tanstack/ai'
+import { openaiSummarize } from '@tanstack/ai-openai'
+
+const contextWindow = 200_000
+const reserveTokens = 20_000
+
+const windowed = withCompaction({
+  maxTokens: contextWindow - reserveTokens,
+  contextWindow,
+  countTokens: 'usage',
+  strategy: summarizeOldest({
+    keepRecentTokens: 8_000,
+    summarize: (messages) =>
+      summarize({
+        adapter: openaiSummarize('gpt-6.1-sol'),
+        text: messages
+          .map((m) => `${m.role}: ${typeof m.content === 'string' ? m.content : ''}`)
+          .join('\n'),
+      }),
+  }),
+})
+```
+
+| You want | Set |
+|---|---|
+| Compact before the context passes the window minus a reserve | `maxTokens: contextWindow - reserveTokens` |
+| Keep the newest messages word for word | `keepRecentTokens` on the strategy |
+| In a durable harness: no automatic compaction, but recovery from a silent overflow | `auto: false`, `contextWindow`, `countTokens: 'usage'`, `durable: true` |
+
+Some providers accept a request that is too large. They cut the input and answer without an error. In a [harness with a durable log](../harness/compaction), compaction with `countTokens: 'usage'` and `durable: true` checks once more after the last model call of a turn. If the usage passed `maxTokens` or `contextWindow`, it compacts right away, so the next turn starts small. With `auto: false`, only `contextWindow` counts. The answer is not sent again. The only extra model calls are the summary calls.
+
+Outside a durable harness, there is no check after a run. The next request compacts before its first model call.
+
 ## What it keeps safe
 
 - **The system prompt is never dropped.** `chat()` keeps it separate from `messages`, so compaction only touches the conversation.
@@ -193,9 +267,9 @@ The token count is a rough `characters / 4` estimate. It is good enough to trigg
 - **It runs before every model call.** Compaction skips `init`. It runs on `beforeModel` and `structuredOutput`. Each later call can compact again.
 - **The canonical transcript stays complete.** Compaction writes provider-only context. Persistence and other middleware still read `ctx.messages`.
 
-## Retry after an overflow
+## Compact now after an overflow
 
-The token count is an estimate, so a call can still pass the model's context limit and fail. `isContextOverflow` from `@tanstack/ai` tells you that a call failed for this reason. Compact harder, then call the model again:
+A call can still pass the model's context limit and fail. `isContextOverflow` from `@tanstack/ai` tells you that a call failed for this reason. Call `compactNext(threadId)`, then send the request again. The next model call on that thread compacts first, even when the count is under `maxTokens`.
 
 ```ts group=compaction-overflow
 import { chat, isContextOverflow } from '@tanstack/ai'
@@ -203,14 +277,18 @@ import type { ModelMessage } from '@tanstack/ai'
 import { openaiText } from '@tanstack/ai-openai'
 import { withCompaction } from '@tanstack/ai-compaction'
 
-async function answer(messages: Array<ModelMessage>) {
-  for (const maxTokens of [100_000, 50_000]) {
+// Create it once, so compactNext reaches the same instance.
+const compaction = withCompaction({ maxTokens: 100_000, countTokens: 'usage' })
+
+async function answer(threadId: string, messages: Array<ModelMessage>) {
+  for (let attempt = 0; attempt < 2; attempt++) {
     let text = ''
     let overflow = false
     for await (const chunk of chat({
       adapter: openaiText('gpt-6.1-sol'),
       messages,
-      middleware: [withCompaction({ maxTokens })],
+      threadId,
+      middleware: [compaction],
     })) {
       if (chunk.type === 'TEXT_MESSAGE_CONTENT') text += chunk.delta
       if (chunk.type === 'RUN_ERROR') {
@@ -219,17 +297,82 @@ async function answer(messages: Array<ModelMessage>) {
       }
     }
     if (!overflow) return text
+    compaction.compactNext(threadId)
   }
   throw new Error('The conversation is too long, even after compaction.')
 }
 ```
 
+In a harness, call `compactNext` from `turn.onModelError`. See [Compact a harness session](../harness/compaction#retry-after-a-context-overflow).
+
+`compactNext` runs the strategy even under `maxTokens`, but a strategy can still find nothing to cut. `composeStrategies` stops when the estimate is under `maxTokens`, and `evictOldest` keeps `maxTokens / 2` by default. For an overflow retry, set a small `keepRecentTokens` on the strategy.
+
 `isContextOverflow` knows the overflow errors of Anthropic, OpenAI, Gemini, Bedrock, Mistral, xAI, Groq, OpenRouter, Ollama, and more. It ignores rate-limit errors. It takes one object, and every field is optional:
 
 - `error`: a `RUN_ERROR` event, an `Error`, or a message string.
 - `usage`, `finishReason`, and `contextWindow`: some providers accept an overflow and cut the input without an error. With the model's `contextWindow`, a call counts as an overflow when its `usage.promptTokens` is more than the window, or when it stopped with `'length'`, wrote nothing, and its input fills the window.
 - `provider`: set `'cerebras'` for Cerebras, which answers an overflow with a bare `400` or `413`.
 
+## Better summaries
+
+The basic `summarizeOldest` setup works for a chat. A coding agent needs more. It must keep the goal, the decisions, and the files it touched across many compactions. Three opt-in parts help:
+
+1. `cut: 'turn'` on `summarizeOldest`: a better summary when the cut falls inside a turn. The older turns get one summary. The start of the current turn gets its own short summary, under `## Turn context`.
+2. `conversationSummarizer`: a ready summarizer with a structured prompt (goal, constraints, progress, key decisions, next steps, critical context). When an older summary exists, it updates that summary. It reports the usage of each summary call.
+3. `details` on `conversationSummarizer`: your own facts after the summary, for example the files the agent read. The next compaction gets them back as `previousDetails`.
+
+```ts group=compaction-better
+import { openaiText } from '@tanstack/ai-openai'
+import {
+  conversationSummarizer,
+  summarizeOldest,
+  withCompaction,
+} from '@tanstack/ai-compaction'
+
+function pathOf(args: string) {
+  const input: unknown = JSON.parse(args)
+  return typeof input === 'object' &&
+    input !== null &&
+    'path' in input &&
+    typeof input.path === 'string'
+    ? input.path
+    : undefined
+}
+
+const agentCompaction = withCompaction({
+  maxTokens: 180_000,
+  contextWindow: 200_000,
+  countTokens: 'usage',
+  strategy: summarizeOldest({
+    cut: 'turn',
+    keepRecentTokens: 8_000,
+    summarize: conversationSummarizer({
+      adapter: openaiText('gpt-6.1-sol'),
+      details: ({ messages, previousDetails }) => {
+        const files = new Set(previousDetails?.split('\n').filter(Boolean))
+        for (const message of messages) {
+          for (const call of message.toolCalls ?? []) {
+            const path =
+              call.function.name === 'read_file'
+                ? pathOf(call.function.arguments)
+                : undefined
+            if (path) files.add(path)
+          }
+        }
+        return files.size > 0 ? [...files].join('\n') : undefined
+      },
+    }),
+  }),
+})
+```
+
+- In the text sent to the summarizer, each tool result is cut to 2,000 characters. Set `maxToolResultChars` to change it.
+- A `summarize` function of your own gets a second argument, `summarize(messages, input)`:
+  - `previousSummary` and `previousDetails`: the older summary and its details.
+  - `turnPrefix`: `true` when the call summarizes the start of the current turn.
+  - `turnPrefixMessages`: the start of the current turn. Only the call that writes the details gets it, so the details cover each dropped message.
+  - `signal`: aborts when the run aborts.
+
 ## DevTools
 
 After a compaction, the chat stream includes three CUSTOM events in order:
@@ -238,6 +381,15 @@ After a compaction, the chat stream includes three CUSTOM events in order:
 event as soon as it is emitted, so a slow `summarizeOldest` call still shows
 as started on the client while it runs. The state and ended events follow when
 the strategy returns.
+
+`compaction:ended` also says why compaction ran and what it cost:
+
+- `reason`: `'threshold'` (the count passed `maxTokens`) or `'forced'` (`compactNext`).
+- `usage`: the token usage of the summary calls.
+- `error`: the message when the strategy failed. By default the run then fails. Set `continueOnError: true` to send the full messages instead.
+
+A compaction after the last model call of a harness turn has `reason: 'after-turn'`. The stream is closed by then, so only `onCompact` reports it. A failed strategy or `onCompact` there does not fail the turn, because the answer is complete. Only a failed write to the log fails it.
+
 TanStack AI DevTools has a Compaction tab on the hook. Each compact shows:
 
 - started, state, and ended rows
@@ -279,7 +431,10 @@ Set `strategyKey` for custom strategies, custom estimators, or custom marker
 functions. Change `strategyKey` when your `summarize` function can change.
 Without a metadata store or safe key, compaction stays stateless.
 
+With `durable: true` in a harness with a durable log, compaction writes its result into the session log instead. A restarted session then sees the same context. See [Compact a harness session](../harness/compaction).
+
 ## Next steps
 
+- [Compact a harness session](../harness/compaction): keep the compaction in the session log, and retry after an overflow
 - [Middleware](./middleware): the full hook reference and how middleware composes
 - [Built-in Middleware](./built-in-middleware): ready-made middleware that ships in `@tanstack/ai`
diff --git a/docs/advanced/testing.md b/docs/advanced/testing.md
index ca31a868ec..7c26c1bd1c 100644
--- a/docs/advanced/testing.md
+++ b/docs/advanced/testing.md
@@ -84,7 +84,7 @@ echo.setResponses([
 
 ## Test errors and overflow
 
-An answer with `error` fails the call. With [`isContextOverflow`](./compaction#retry-after-an-overflow), test the code that compacts and retries:
+An answer with `error` fails the call. With [`isContextOverflow`](./compaction#compact-now-after-an-overflow), test the code that compacts and retries:
 
 ```ts group=testing
 import { isContextOverflow } from '@tanstack/ai'
diff --git a/docs/config.json b/docs/config.json
index 222ca4c4ee..74f5e99bf8 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -331,7 +331,7 @@
           "label": "Compaction",
           "to": "advanced/compaction",
           "addedAt": "2026-08-24",
-          "updatedAt": "2026-09-30"
+          "updatedAt": "2026-10-03"
         },
         {
           "label": "Prompt Caching",
@@ -932,13 +932,18 @@
           "label": "Build on the session log",
           "to": "harness/session-log",
           "addedAt": "2026-09-30",
-          "updatedAt": "2026-10-01"
+          "updatedAt": "2026-10-03"
         },
         {
           "label": "Control how a turn ends",
           "to": "harness/turn-control",
           "addedAt": "2026-10-01",
-          "updatedAt": "2026-10-02"
+          "updatedAt": "2026-10-03"
+        },
+        {
+          "label": "Compact a long session",
+          "to": "harness/compaction",
+          "addedAt": "2026-10-03"
         },
         {
           "label": "Share one log between sessions",
@@ -955,7 +960,7 @@
           "label": "Build a coding agent",
           "to": "harness/coding-agent",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-10-01"
+          "updatedAt": "2026-10-04"
         },
         {
           "label": "Connect model providers",
diff --git a/docs/harness/coding-agent.md b/docs/harness/coding-agent.md
index dd72795107..1394b52508 100644
--- a/docs/harness/coding-agent.md
+++ b/docs/harness/coding-agent.md
@@ -71,6 +71,8 @@ Run the file with `npx tsx coder.ts`. Ask for a change. The agent reads files fr
 | `usage()` | `/usage` shows the tokens of the session: the lead turn and every agent. Its state also has `contextTokens`, the prompt size of the last lead call, for a context meter. |
 | `goal({ judge })` | `/goal <text>` keeps the agent working until a judge model says that the goal is met. See [Work until a goal is met](./goal). |
 
+To compact on its own before the context limit, see [Compact a harness session](./compaction).
+
 ## Add your own rules
 
 Tool plugins add permission rules to the `PermissionRules` extension point. Add your own for any tool:
diff --git a/docs/harness/compaction.md b/docs/harness/compaction.md
new file mode 100644
index 0000000000..c9f435a578
--- /dev/null
+++ b/docs/harness/compaction.md
@@ -0,0 +1,119 @@
+---
+title: Compact a harness session
+id: harness-compaction
+order: 4
+description: "Keep a long harness session under the context limit. The compaction goes into the session log, so a session that opens again sees the same context."
+keywords:
+  - tanstack ai
+  - harness
+  - compaction
+  - context window
+  - projectCompaction
+  - compactNext
+  - session log
+---
+
+A harness session can run for days. Its transcript grows until a model call passes the context limit. [Compaction](../advanced/compaction) shrinks what the model sees. In a durable harness, the result must also survive a restart. A session that opens again must see the same context as before.
+
+Set `durable: true`. Compaction then writes a `tanstack.compaction` record into the session log. The host folds that record into the messages with `projectCompaction`, live and when the session opens again.
+
+## Add compaction to a harness
+
+1. Create the compaction middleware with `durable: true`.
+2. Add it to `middleware` in `defineHarness`.
+3. Give the host `projectCompaction` in its `project` option.
+
+```ts group=harness-compaction
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { openaiText } from '@tanstack/ai-openai'
+import {
+  conversationSummarizer,
+  projectCompaction,
+  summarizeOldest,
+  withCompaction,
+} from '@tanstack/ai-compaction'
+
+const compaction = withCompaction({
+  maxTokens: 180_000,
+  contextWindow: 200_000,
+  countTokens: 'usage',
+  durable: true,
+  strategy: summarizeOldest({
+    cut: 'turn',
+    keepRecentTokens: 8_000,
+    summarize: conversationSummarizer({ adapter: openaiText('gpt-6.1-sol') }),
+  }),
+})
+
+const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-6.1-sol'),
+  middleware: [compaction],
+})
+
+const { runs, metadata } = memoryPersistence().stores
+const host = createHarnessHost({
+  persistence: { stores: { log: memoryLogStore(), runs, metadata } },
+  project: { version: 'v1', record: projectCompaction },
+})
+```
+
+- Compaction runs before a model call when the count passes `maxTokens`. If the usage of the last model call of a turn passed `maxTokens` or `contextWindow`, compaction also runs right after that call. This check needs `countTokens: 'usage'`.
+- The log only grows, so the original messages stay in the store. The fold that the model gets starts with the summary.
+- A host without a log has no place for the record. Compaction then keeps its result in the `metadata` store, the same as in a plain `chat()` call. It also skips the check after the turn.
+
+## Fold your own records too
+
+If your host already folds records of its own, call `projectCompaction` first:
+
+```ts group=harness-compaction
+import type { ProjectOptions } from '@tanstack/ai-harness'
+
+const project: ProjectOptions = {
+  version: 'v2',
+  record: (input) => {
+    const compacted = projectCompaction(input)
+    if (compacted) return compacted
+    const { record, messages } = input
+    if (record.type === 'app.signal' && typeof record.text === 'string') {
+      return [...messages, { role: 'user', content: record.text }]
+    }
+    return undefined
+  },
+}
+```
+
+Change `version` when you change the function. A fold checkpoint with another version is ignored.
+
+## Retry after a context overflow
+
+A model call can still fail with a context overflow. Call `compactNext` in `turn.onModelError`, then return `'retry'`. The retried call compacts first and writes the record.
+
+```ts group=harness-compaction
+import { isContextOverflow } from '@tanstack/ai'
+
+const recovering = defineHarness({
+  name: 'acme/recovering',
+  adapter: openaiText('gpt-6.1-sol'),
+  middleware: [compaction],
+  turn: {
+    onModelError: ({ session, error, retries }) => {
+      if (retries > 0 || !isContextOverflow({ error: error.message })) {
+        return undefined
+      }
+      compaction.compactNext(session.threadId)
+      return 'retry'
+    },
+  },
+})
+```
+
+- `retries > 0` stops after one retry. A second overflow fails the turn with its error.
+- `compactNext` also works with `auto: false`. With `auto: false`, compaction runs only for this recovery and for the `contextWindow` check.
+
+## What you have now
+
+- A session that compacts before it passes the context limit, counted with the real usage of each call.
+- The same context after a restart, because the compaction is in the log.
+- One retry after an overflow, with a compaction first.
diff --git a/docs/harness/session-log.md b/docs/harness/session-log.md
index a2be7251f7..9eccd34af4 100644
--- a/docs/harness/session-log.md
+++ b/docs/harness/session-log.md
@@ -54,16 +54,6 @@ const project: ProjectOptions = {
     if (record.type === 'app.signal' && typeof record.text === 'string') {
       return [...messages, { role: 'user', content: record.text }]
     }
-    if (
-      record.type === 'app.compaction' &&
-      typeof record.summary === 'string' &&
-      typeof record.firstKept === 'number'
-    ) {
-      return [
-        { role: 'assistant', content: record.summary },
-        ...messages.slice(record.firstKept),
-      ]
-    }
     return undefined
   },
 }
@@ -77,6 +67,8 @@ const projectedHost = createHarnessHost({
 - `record` must be pure: the same log always folds to the same context, live and after a restart.
 - The model sees the change at its next model call. A message that arrives during a tool call comes after the tool result.
 - Change `version` when you change `record`. A fold checkpoint with another version is ignored.
+- For compaction, use `projectCompaction` from `@tanstack/ai-compaction`. See [Compact a harness session](./compaction).
+- A chat middleware on a durable host can append records itself with `getLogRecords(ctx).append([...])` from `@tanstack/ai`. The records land in the log at once. A plugin's middleware reads the writer with `getLogRecords(ctx, { optional: true })`. A plugin cannot list `LogRecordsCapability` in `requires`.
 
 ## Read the log
 
diff --git a/docs/harness/turn-control.md b/docs/harness/turn-control.md
index dced6edd64..323a86364e 100644
--- a/docs/harness/turn-control.md
+++ b/docs/harness/turn-control.md
@@ -99,33 +99,31 @@ Clients get a `harness.turn.retry` event for each retry. The text of the failed
 
 ### Compact after a context overflow
 
-`onModelError` is a plain function, so you can write your own policy. This one handles a context overflow: it appends a compaction record, then retries once. Your host must have a `project` function that folds `app.compaction` records into the messages. See [Fold records into the model context](./session-log#fold-records-into-the-model-context).
+`onModelError` is a plain function, so you can write your own policy. For a context overflow, use the [compaction middleware](../advanced/compaction): call `compactNext`, then retry once.
 
 ```ts group=harness-turn-control
 import { isContextOverflow } from '@tanstack/ai'
+import { withCompaction } from '@tanstack/ai-compaction'
+
+const compaction = withCompaction({ maxTokens: 100_000, countTokens: 'usage' })
 
 const compacting = defineHarness({
   name: 'acme/compacting',
   adapter: openaiText('gpt-5.6'),
+  middleware: [compaction],
   turn: {
-    onModelError: async ({ session, error, retries }) => {
+    onModelError: ({ session, error, retries }) => {
       if (retries > 0 || !isContextOverflow({ error: error.message })) {
         return undefined
       }
-      await session.append([
-        {
-          type: 'app.compaction',
-          summary: 'Earlier messages were removed to fit the context.',
-          firstKept: -6,
-        },
-      ])
+      compaction.compactNext(session.threadId)
       return 'retry'
     },
   },
 })
 ```
 
-Here `firstKept: -6` keeps the last six messages. The `project` function in the linked page reads it with `messages.slice(record.firstKept)`, and `slice` counts a negative number from the end.
+The retried call compacts before it calls the model. To keep the compaction after a restart, see [Compact a harness session](./compaction).
 
 ## Choose which messages join a turn
 
diff --git a/packages/ai-compaction/README.md b/packages/ai-compaction/README.md
index 748181042b..00c60cf35f 100644
--- a/packages/ai-compaction/README.md
+++ b/packages/ai-compaction/README.md
@@ -50,11 +50,11 @@ chat({
 
 Pass `strategy` to change how the history shrinks. Three are built in.
 
-| Strategy                | What it does                                            | Cost                |
-| ----------------------- | ------------------------------------------------------- | ------------------- |
-| `evictOldest` (default) | Drop the oldest messages, leave a marker                | No extra model call |
-| `summarizeOldest`       | Replace the oldest messages with an LLM summary         | One summarize call  |
-| `clearToolResults`      | Stub the content of old tool results, keep the messages | No extra model call |
+| Strategy                | What it does                                            | Cost                                        |
+| ----------------------- | ------------------------------------------------------- | ------------------------------------------- |
+| `evictOldest` (default) | Drop the oldest messages, leave a marker                | No extra model call                         |
+| `summarizeOldest`       | Replace the oldest messages with an LLM summary         | One summarize call (two with `cut: 'turn'`) |
+| `clearToolResults`      | Stub the content of old tool results, keep the messages | No extra model call                         |
 
 ```ts
 import {
@@ -106,8 +106,7 @@ withCompaction({
 ### Write your own
 
 A strategy gets the messages and the budget, and returns the rewritten messages
-(or `null` to change nothing). It runs only when the estimate is over
-`maxTokens`.
+(or `null` to change nothing). It runs when the count is over `maxTokens`, and when `compactNext` forces it. Then the count can be under `maxTokens`.
 
 ```ts
 import type { CompactionStrategy } from '@tanstack/ai-compaction'
@@ -126,21 +125,30 @@ withCompaction({
 
 ### `withCompaction`
 
-| Option           | Default         | What it does                                                                 |
-| ---------------- | --------------- | ---------------------------------------------------------------------------- |
-| `maxTokens`      | (required)      | Compact when estimated tokens exceed this.                                   |
-| `strategy`       | `evictOldest()` | How to shrink the messages.                                                  |
-| `estimateTokens` | chars / 4       | Per-message token estimate. Swap in a real tokenizer for accuracy.           |
-| `strategyKey`    | built-in key    | Stable checkpoint identity. Set it for custom strategies or estimators.      |
-| `onCompact`      | —               | Observe each compaction (`before`/`after`/`messagesBefore`/`messagesAfter`). |
+| Option            | Default         | What it does                                                                                                                                                                 |
+| ----------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `maxTokens`       | (required)      | Compact when the token count passes this.                                                                                                                                    |
+| `strategy`        | `evictOldest()` | How to shrink the messages.                                                                                                                                                  |
+| `estimateTokens`  | chars / 4       | Per-message token estimate. Swap in a real tokenizer for accuracy.                                                                                                           |
+| `strategyKey`     | built-in key    | Stable checkpoint identity. Set it for custom strategies or estimators.                                                                                                      |
+| `onCompact`       | (none)          | Observe each compaction (`before`, `after`, `messagesBefore`, `messagesAfter`, `reason`, `usage`, `error`).                                                                  |
+| `countTokens`     | `'estimate'`    | `'usage'`: count with the usage the provider reported for the last call, plus an estimate of the messages after it.                                                          |
+| `auto`            | `true`          | `false`: do not compact when the count passes `maxTokens`. `compactNext` and the `contextWindow` check still compact.                                                        |
+| `contextWindow`   | (none)          | The model's context window. With `countTokens: 'usage'` and `durable: true` in a harness with a log, the check after the last model call compacts when the usage is over it. |
+| `durable`         | `false`         | In a durable harness session, write each compaction as a session log record.                                                                                                 |
+| `continueOnError` | `false`         | When the strategy throws, send the messages without compaction instead of failing the run.                                                                                   |
+
+`withCompaction` returns a middleware with `compactNext(threadId)`. Call it to compact at the next model call on that thread, for example after a context overflow.
 
 ### Strategy options
 
-| Strategy           | Options                                                                         |
-| ------------------ | ------------------------------------------------------------------------------- |
-| `evictOldest`      | `keepRecentTokens` (default `maxTokens / 2`), `marker`                          |
-| `summarizeOldest`  | `summarize` (required), `keepRecentTokens`, `summaryRole` (default `assistant`) |
-| `clearToolResults` | `keepRecentToolResults` (default `3`), `stub`                                   |
+| Strategy           | Options                                                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `evictOldest`      | `keepRecentTokens` (default `maxTokens / 2`), `marker`                                                       |
+| `summarizeOldest`  | `summarize` (required), `keepRecentTokens`, `summaryRole` (default `assistant`), `cut` (default `'message'`) |
+| `clearToolResults` | `keepRecentToolResults` (default `3`), `stub`                                                                |
+
+`conversationSummarizer({ adapter })` gives a ready `summarize` function with a structured prompt. When an older summary exists, it updates that summary.
 
 The token estimate is a rough `chars / 4` heuristic, good enough to trigger on,
 not exact. Pass `estimateTokens` if you need provider-accurate counts.

From 6735e83200552c8b27119c6164938abc05548a2a Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 12:38:55 +0200
Subject: [PATCH 213/286] fix(ai): fakeText modalities, parentRunId, and unique
 tool call ids

- inputModalities is an optional property, so fakeText() type-checks as an adapter with exactOptionalPropertyTypes.
- RUN_STARTED carries parentRunId when the call has one.
- Tool call ids are unique across fakeText() instances.
---
 packages/ai/src/testing/fake-text.ts  | 24 +++++++++++++++---
 packages/ai/tests/fake-text.test-d.ts | 10 ++++++++
 packages/ai/tests/fake-text.test.ts   | 36 +++++++++++++++++++++++++++
 3 files changed, 66 insertions(+), 4 deletions(-)
 create mode 100644 packages/ai/tests/fake-text.test-d.ts

diff --git a/packages/ai/src/testing/fake-text.ts b/packages/ai/src/testing/fake-text.ts
index ccd0081ca2..deb64074b0 100644
--- a/packages/ai/src/testing/fake-text.ts
+++ b/packages/ai/src/testing/fake-text.ts
@@ -20,7 +20,10 @@ export interface FakeResponse {
   text?: string
   /** Thinking text, streamed before the answer. */
   thinking?: string
-  /** Tool calls. `id` defaults to `fake-call-<n>`. */
+  /**
+   * Tool calls. `id` defaults to `fake-call-<fake>-<call>-<index>`, unique
+   * across fakes.
+   */
   toolCalls?: Array<{ name: string; input?: unknown; id?: string }>
   /** Default: `'tool_calls'` when there are tool calls, else `'stop'`. */
   finishReason?: 'stop' | 'length' | 'content_filter' | 'tool_calls'
@@ -64,6 +67,12 @@ export interface FakeTextOptions<
 const EMPTY_QUEUE = 'No more fake responses queued'
 const CHARS_PER_TOKEN = 4
 
+/**
+ * Numbers each fake, so two fakes in one process (for example two hosts in a
+ * restart test) never give the same tool-call id.
+ */
+let fakeCount = 0
+
 function estimateTokens(text: string) {
   return Math.ceil(text.length / CHARS_PER_TOKEN)
 }
@@ -133,7 +142,9 @@ export class FakeTextAdapter<
   DefaultMessageMetadataByModality
 > {
   readonly name = 'fake'
-  override readonly inputModalities: ReadonlyArray<Modality> | undefined
+  // Optional, as on `TextAdapter`, so the fake is an adapter under
+  // `exactOptionalPropertyTypes` too.
+  declare readonly inputModalities?: ReadonlyArray<Modality>
   /** The context window from the options. */
   readonly contextWindow: number | undefined
   readonly state: FakeTextState = { callCount: 0 }
@@ -141,11 +152,12 @@ export class FakeTextAdapter<
   private queue: Array<FakeResponseStep> = []
   private readonly previousRequests = new Map<string, string>()
   private readonly options: FakeTextOptions<TModel, TInput>
+  private readonly instance = ++fakeCount
 
   constructor(model: TModel, options: FakeTextOptions<TModel, TInput>) {
     super({}, model)
     this.options = options
-    this.inputModalities = options.input
+    if (options.input) this.inputModalities = options.input
     this.contextWindow = options.contextWindow
   }
 
@@ -217,6 +229,8 @@ export class FakeTextAdapter<
       threadId,
       model,
       timestamp: Date.now(),
+      // As real adapters do: a continuation links to the run it resumes.
+      ...(options.parentRunId ? { parentRunId: options.parentRunId } : {}),
     }
     if (response.error !== undefined) {
       yield {
@@ -288,7 +302,9 @@ export class FakeTextAdapter<
 
     const toolCalls = response.toolCalls ?? []
     for (const [index, call] of toolCalls.entries()) {
-      const toolCallId = call.id ?? `fake-call-${this.state.callCount}-${index}`
+      const toolCallId =
+        call.id ??
+        `fake-call-${this.instance}-${this.state.callCount}-${index}`
       yield {
         type: EventType.TOOL_CALL_START,
         toolCallId,
diff --git a/packages/ai/tests/fake-text.test-d.ts b/packages/ai/tests/fake-text.test-d.ts
new file mode 100644
index 0000000000..e9b6595d89
--- /dev/null
+++ b/packages/ai/tests/fake-text.test-d.ts
@@ -0,0 +1,10 @@
+import { expectTypeOf } from 'vitest'
+import { fakeText } from '../src/testing'
+
+// `inputModalities` is optional, as on `TextAdapter`. A required
+// `X | undefined` field breaks `chat({ adapter: fakeText() })` in a project
+// with `exactOptionalPropertyTypes`.
+type Fake = ReturnType<typeof fakeText>
+expectTypeOf<
+  {} extends Pick<Fake, 'inputModalities'> ? true : false
+>().toEqualTypeOf<true>()
diff --git a/packages/ai/tests/fake-text.test.ts b/packages/ai/tests/fake-text.test.ts
index 69e697c849..9bc0e7e0e5 100644
--- a/packages/ai/tests/fake-text.test.ts
+++ b/packages/ai/tests/fake-text.test.ts
@@ -247,6 +247,42 @@ describe('fakeText', () => {
     expect(result.data).toEqual({ city: 'Oslo' })
   })
 
+  it('stamps parentRunId on RUN_STARTED when the call has one', async () => {
+    const fake = fakeText()
+    fake.setResponses([{ text: 'One' }, { text: 'Two' }])
+
+    const child = await adapterEvents(
+      fake,
+      request(hi, { runId: 'run-2', parentRunId: 'run-1' }),
+    )
+    const top = await adapterEvents(fake, request(hi, { runId: 'run-3' }))
+
+    expect(child[0]).toMatchObject({
+      type: EventType.RUN_STARTED,
+      runId: 'run-2',
+      parentRunId: 'run-1',
+    })
+    expect(top[0]).not.toHaveProperty('parentRunId')
+  })
+
+  it('gives tool calls ids that differ between two fakes', async () => {
+    const first = fakeText()
+    const second = fakeText()
+    const call = { toolCalls: [{ name: 'weather', input: {} }] }
+    first.setResponses([call])
+    second.setResponses([call])
+
+    const ids = [
+      ...(await adapterEvents(first, request(hi))),
+      ...(await adapterEvents(second, request(hi))),
+    ].flatMap((event) =>
+      event.type === EventType.TOOL_CALL_START ? [event.toolCallId] : [],
+    )
+
+    expect(ids).toHaveLength(2)
+    expect(new Set(ids).size).toBe(2)
+  })
+
   it('keeps the model id and the context window', () => {
     const fake = fakeText({ model: 'tiny', contextWindow: 8_000 })
 

From 0dd064bdc42117ed5481c417968f30db66ce6105 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 12:38:55 +0200
Subject: [PATCH 214/286] feat(ai): let a tool that asks for input set the
 interrupt reason

A tool that throws the MCP input-required shape can set reason. MCP interrupts still use 'mcp_input'.
---
 packages/ai/src/activities/chat/index.ts      |  2 +-
 .../src/activities/chat/tools/tool-calls.ts   |  4 +++
 packages/ai/tests/mcp-input-interrupt.test.ts | 33 +++++++++++++++++--
 3 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index d1676adcfa..3c1c994f22 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -3141,7 +3141,7 @@ class TextEngine<
       const id = `mcp_input_${pendingInput.toolCallId}`
       interrupts.push({
         id,
-        reason: 'mcp_input',
+        reason: pendingInput.reason ?? 'mcp_input',
         message: `Input required to run ${pendingInput.toolName}`,
         toolCallId: pendingInput.toolCallId,
         metadata: {
diff --git a/packages/ai/src/activities/chat/tools/tool-calls.ts b/packages/ai/src/activities/chat/tools/tool-calls.ts
index dfc1d6d614..96cc954aa9 100644
--- a/packages/ai/src/activities/chat/tools/tool-calls.ts
+++ b/packages/ai/src/activities/chat/tools/tool-calls.ts
@@ -540,12 +540,15 @@ export interface McpInputRequest {
   toolName: string
   kind: 'form' | 'sampling'
   request: unknown
+  /** The interrupt reason. Default: `'mcp_input'`. */
+  reason?: string
 }
 
 interface McpInputRequiredThrow {
   name: 'MCPInputRequiredError'
   kind: 'form' | 'sampling'
   request: unknown
+  reason?: unknown
 }
 
 function isMcpInputRequired(value: unknown): value is McpInputRequiredThrow {
@@ -834,6 +837,7 @@ export async function* executeServerTool<TContext = unknown>(
         toolName,
         kind: error.kind,
         request: error.request,
+        ...(typeof error.reason === 'string' ? { reason: error.reason } : {}),
       })
       return
     }
diff --git a/packages/ai/tests/mcp-input-interrupt.test.ts b/packages/ai/tests/mcp-input-interrupt.test.ts
index d90bab6c43..b8bc1e1bf4 100644
--- a/packages/ai/tests/mcp-input-interrupt.test.ts
+++ b/packages/ai/tests/mcp-input-interrupt.test.ts
@@ -5,17 +5,23 @@ import { EventType } from '../src/types'
 import { collectChunks, createMockAdapter, ev, serverTool } from './test-utils'
 import type { StreamChunk, ToolExecutionContext } from '../src/types'
 
-function inputRequiredThrow(kind: 'form' | 'sampling', request: unknown) {
+function inputRequiredThrow(
+  kind: 'form' | 'sampling',
+  request: unknown,
+  reason?: string,
+) {
   return {
     name: 'MCPInputRequiredError',
     kind,
     request,
+    ...(reason !== undefined ? { reason } : {}),
   }
 }
 
 async function runInputRequiredChat(
   kind: 'form' | 'sampling',
   request: unknown,
+  reason?: string,
 ) {
   const { adapter, calls } = createMockAdapter({
     iterations: [
@@ -41,7 +47,7 @@ async function runInputRequiredChat(
       messages: [{ role: 'user', content: 'Ask' }],
       tools: [
         serverTool('askInput', () => {
-          throw inputRequiredThrow(kind, request)
+          throw inputRequiredThrow(kind, request, reason)
         }),
       ],
     }) as AsyncIterable<StreamChunk>,
@@ -98,6 +104,29 @@ describe('MCP input interrupt', () => {
     })
   })
 
+  it('uses the reason the thrown shape gives', async () => {
+    const request = { connector: 'github' }
+    const finished = await runInputRequiredChat(
+      'form',
+      request,
+      'auth_required',
+    )
+
+    expect(finished?.outcome).toMatchObject({
+      type: 'interrupt',
+      interrupts: [
+        {
+          id: 'mcp_input_call_1',
+          reason: 'auth_required',
+          toolCallId: 'call_1',
+          metadata: {
+            'tanstack:interruptPayload': { kind: 'form', request },
+          },
+        },
+      ],
+    })
+  })
+
   it('pauses a sampling request as a different interrupt', async () => {
     const request = { messages: [{ role: 'user', content: 'Hi' }] }
     const finished = await runInputRequiredChat('sampling', request)

From 5d6ba16801693b27da54914b3a7f9887352da732 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 12:39:06 +0200
Subject: [PATCH 215/286] feat(ai-harness): per-input sender and context,
 useChat on POST run, sign-in wait, and report fixes

Fixes from the Pit spike report on the harness (#1555):

- A resolve that fails validation keeps the interrupt pending. A resolve sent on RUN_FINISHED is accepted. A busy: 'steer' prompt receipt names the running turn.
- POST run runs the turn as the request runId, so ChatClient and useChat can answer approvals and client tools. GET run?threadId= serves the hydrate data with the running turn, and GET run?runId= joins a running turn after a reload, with Last-Event-ID resume and canAccess.
- ask() questions arrive on the turn stream. snapshot().activeOperations has startedCursor.
- Each input, command, and wake turn runs as its sender: log record, credentials, provider keys, canJoin (principal and turnPrincipal), router. By default a steer joins only a turn of the same sender.
- Inputs take context. POST run fills it from forwardedProps. It is stored, kept after a restart and an interrupt, and merged under HarnessConfig.context.
- TurnInfo for plugin adapter() and ctx.turn. lifetime: 'turn'. defineHarness adapter is optional. harnessText takes inputModalities.
- Principal.tenantId goes into the credential scope. A read falls back from the user's credential to the tenant's.
- credentials.require(id, { wait: true }) stops the turn for a sign-in, and a save by the same sender continues it.
- The session view lists client tools in clientTools and sign-in waits in signIns.
- A client runId that a run record has, or that another sender used, is refused with conflict.
---
 packages/ai-harness/src/agents.ts             |   2 +-
 packages/ai-harness/src/auth.ts               |  99 +-
 packages/ai-harness/src/commands.ts           |  15 +
 packages/ai-harness/src/connectors.ts         |  23 +-
 packages/ai-harness/src/define.ts             |  22 +-
 .../src/first-party/provider-keys.ts          |  24 +-
 packages/ai-harness/src/harness-text.ts       |  29 +-
 packages/ai-harness/src/host.ts               |  33 +-
 packages/ai-harness/src/http.ts               | 141 ++-
 packages/ai-harness/src/index.ts              |   1 +
 packages/ai-harness/src/log.ts                |   4 +-
 packages/ai-harness/src/operation.ts          |   3 +
 packages/ai-harness/src/plugins.ts            |  38 +-
 packages/ai-harness/src/protocol.ts           |  30 +-
 packages/ai-harness/src/resources.ts          |   2 +-
 packages/ai-harness/src/session.ts            | 688 +++++++++++---
 packages/ai-harness/src/turn.ts               |  12 +-
 packages/ai-harness/src/types.ts              |  35 +-
 packages/ai-harness/src/view/index.ts         |  71 +-
 packages/ai-harness/src/view/reduce.ts        |  78 +-
 packages/ai-harness/src/view/types.ts         |  17 +
 .../ai-harness/tests/agent-middleware.test.ts |   4 +-
 packages/ai-harness/tests/auth-wait.test.ts   | 517 +++++++++++
 .../tests/harness-text-media.test.ts          |  20 +
 .../ai-harness/tests/input-sender.test.ts     | 872 ++++++++++++++++++
 .../tests/interrupt-resolve.test.ts           | 358 +++++++
 .../ai-harness/tests/plugin-subagents.test.ts |   2 +-
 packages/ai-harness/tests/routing.test.ts     |   4 +-
 packages/ai-harness/tests/run-route.test.ts   | 613 ++++++++++++
 packages/ai-harness/tests/session.test.ts     | 124 ++-
 .../ai-harness/tests/transport-edges.test.ts  |   4 +-
 .../ai-harness/tests/turn-overrides.test.ts   |   4 +-
 packages/ai-harness/tests/types.test-d.ts     |  15 +-
 .../tests/view-client-tools.test.ts           | 171 ++++
 packages/ai-harness/tests/view-reduce.test.ts |  73 ++
 packages/ai-persistence/src/types.ts          |   2 +-
 36 files changed, 3871 insertions(+), 279 deletions(-)
 create mode 100644 packages/ai-harness/tests/auth-wait.test.ts
 create mode 100644 packages/ai-harness/tests/input-sender.test.ts
 create mode 100644 packages/ai-harness/tests/interrupt-resolve.test.ts
 create mode 100644 packages/ai-harness/tests/run-route.test.ts
 create mode 100644 packages/ai-harness/tests/view-client-tools.test.ts

diff --git a/packages/ai-harness/src/agents.ts b/packages/ai-harness/src/agents.ts
index 1562c6e4ef..4e3a05b238 100644
--- a/packages/ai-harness/src/agents.ts
+++ b/packages/ai-harness/src/agents.ts
@@ -84,7 +84,7 @@ export class AgentRegistry implements AgentRegistryView {
     return this.list().find((agent) => agent.produces === query.produces)
   }
 
-  /** A copy for one chat turn, so run plugins can add agents for that turn only. */
+  /** A copy for one chat turn, so turn plugins can add agents for that turn only. */
   fork(): AgentRegistry {
     const copy = new AgentRegistry()
     for (const [name, entry] of this.agents) copy.agents.set(name, entry)
diff --git a/packages/ai-harness/src/auth.ts b/packages/ai-harness/src/auth.ts
index 886d05b187..31f6b2d384 100644
--- a/packages/ai-harness/src/auth.ts
+++ b/packages/ai-harness/src/auth.ts
@@ -23,11 +23,24 @@ export class AuthRequiredError extends Error {
   }
 }
 
-/** Credentials of the session's principal, as plugins see them. */
+/**
+ * Credentials of the running turn's sender (outside a turn, of the session's
+ * principal), as plugins see them.
+ */
 export interface CredentialsAccess {
   get: (id: string) => Promise<Credential | null>
-  /** Like `get`, but throws {@link AuthRequiredError} when the credential is missing. */
-  require: (id: string) => Promise<Credential>
+  /**
+   * Like `get`, but throws {@link AuthRequiredError} when the credential is
+   * missing. With `wait: true`, a tool of a chat turn waits for the sign-in
+   * instead: the turn stops with an interrupt with the reason
+   * `'auth_required'`. When the credential is saved (for example by
+   * `connect:<id>`), the turn goes on and the tool runs again. Cancel the
+   * interrupt to fail the tool. `wait` is for a tool of the running chat
+   * turn. Do not pass it elsewhere (a command, a background agent, a hook):
+   * the credentials of a command never wait, and outside a chat turn `wait`
+   * does nothing.
+   */
+  require: (id: string, options?: { wait?: boolean }) => Promise<Credential>
   set: (id: string, credential: Credential) => Promise<void>
   delete: (id: string) => Promise<void>
   list: () => Promise<
@@ -35,24 +48,88 @@ export interface CredentialsAccess {
   >
 }
 
-/** Scope credentials to one principal and thread. */
+/**
+ * What a session adds to `credentialsFor`: `canWait` says if a `require`
+ * with `wait` can stop the turn now, and `onSet` runs after each save.
+ */
+export interface CredentialHooks {
+  canWait?: (id: string) => boolean
+  onSet?: (id: string) => Promise<void>
+}
+
+/**
+ * The error that chat() reads as "stop the turn for input" (the shape of
+ * `MCPInputRequiredError`), with the reason `'auth_required'`.
+ */
+function signInRequired(error: AuthRequiredError) {
+  return Object.assign(new Error(error.message), {
+    name: 'MCPInputRequiredError',
+    kind: 'form' as const,
+    reason: 'auth_required',
+    request: {
+      connector: error.connector,
+      ...(error.url ? { url: error.url } : {}),
+    },
+  })
+}
+
+/**
+ * The tenant scope of a user scope: the same tenant, no user. A credential
+ * saved there belongs to every user of the tenant.
+ */
+const tenantOf = ({ userId, ...tenant }: Scope): Scope | undefined =>
+  userId === undefined ? undefined : tenant
+
+/**
+ * Scope credentials to one principal and thread. A function `scope` is read
+ * at each call, so the scope can follow the sender of the running turn.
+ *
+ * A read finds the user's own credential first, then the tenant's (saved
+ * without a `userId`). A save or a delete changes the user's own only.
+ */
 export function credentialsFor(
   store: CredentialStore,
-  scope: Scope,
+  scope: Scope | (() => Scope),
   onMissing: (error: AuthRequiredError) => void,
+  hooks?: CredentialHooks,
 ): CredentialsAccess {
+  const scopeNow = typeof scope === 'function' ? scope : () => scope
+  // ponytail: a refreshed tenant OAuth token is saved for the user, so each
+  // user keeps a copy. A provider that rotates refresh tokens would need a
+  // save for the whole tenant to share one token.
+  const get = async (id: string) => {
+    const user = scopeNow()
+    const own = await store.get(user, id)
+    if (own) return own
+    const tenant = tenantOf(user)
+    return tenant ? store.get(tenant, id) : null
+  }
   return {
-    get: (id) => store.get(scope, id),
-    require: async (id) => {
-      const credential = await store.get(scope, id)
+    get,
+    require: async (id, options) => {
+      const credential = await get(id)
       if (credential) return credential
       const error = new AuthRequiredError(id)
       onMissing(error)
+      if (options?.wait && hooks?.canWait?.(id)) throw signInRequired(error)
       throw error
     },
-    set: (id, credential) => store.set(scope, id, credential),
-    delete: (id) => store.delete(scope, id),
-    list: () => store.list(scope),
+    set: async (id, credential) => {
+      await store.set(scopeNow(), id, credential)
+      await hooks?.onSet?.(id)
+    },
+    delete: (id) => store.delete(scopeNow(), id),
+    list: async () => {
+      const user = scopeNow()
+      const tenant = tenantOf(user)
+      const own = await store.list(user)
+      if (!tenant) return own
+      const shared = await store.list(tenant)
+      return [
+        ...own,
+        ...shared.filter((item) => !own.some((o) => o.id === item.id)),
+      ]
+    },
   }
 }
 
diff --git a/packages/ai-harness/src/commands.ts b/packages/ai-harness/src/commands.ts
index e04e723567..d44810eff7 100644
--- a/packages/ai-harness/src/commands.ts
+++ b/packages/ai-harness/src/commands.ts
@@ -1,4 +1,5 @@
 import type { InferSchemaType, ModelMessage, SchemaInput } from '@tanstack/ai'
+import type { CredentialsAccess } from './auth'
 import type { SessionSnapshot } from './session'
 import type { ChatTurnResult, Operation, Principal, Receipt } from './types'
 
@@ -21,6 +22,12 @@ export type AnswerOf<TSchema> = TSchema extends SchemaInput
 /** The parts of the session a plugin can use. */
 export interface PluginSessionApi {
   threadId: string
+  /**
+   * Who sent the input of the running chat turn. Outside a turn: the
+   * principal that opened the session. In a command's `run` context: who
+   * runs the command. Code that runs after its turn ends (a background
+   * agent's tool) gets the sender of the turn that runs at that time.
+   */
   principal: Principal | undefined
   snapshot: () => SessionSnapshot
   /**
@@ -55,7 +62,15 @@ export interface PluginSessionApi {
 /** What a command handler receives besides its input. */
 export interface CommandContext {
   signal: AbortSignal
+  /** The session, for the user who runs the command: `session.prompt` runs as that user. */
   session: PluginSessionApi
+  /** Who runs the command. Default: the principal that opened the session. */
+  principal?: Principal
+  /**
+   * The credentials of the user who runs the command. Save a sign-in here,
+   * so it belongs to that user.
+   */
+  credentials: CredentialsAccess
 }
 
 /** A user action: a slash command, a button, a dashboard action. Not a model tool. */
diff --git a/packages/ai-harness/src/connectors.ts b/packages/ai-harness/src/connectors.ts
index 7b5aad47cd..09095844b5 100644
--- a/packages/ai-harness/src/connectors.ts
+++ b/packages/ai-harness/src/connectors.ts
@@ -18,9 +18,13 @@ export interface OAuthConnectorOptions {
   login?: 'loopback' | 'device'
   /**
    * The tools of this service. Call `token()` inside a tool: it returns a
-   * fresh access token, or pauses with `auth_required` before sign-in.
+   * 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: () => Promise<string>) => ReadonlyArray<AnyTool>
+  tools?: (
+    token: (options?: { wait?: boolean }) => Promise<string>,
+  ) => ReadonlyArray<AnyTool>
   /** Test hook for the token endpoint. */
   fetch?: typeof fetch
 }
@@ -45,8 +49,10 @@ export function oauthConnector(options: OAuthConnectorOptions) {
   return definePlugin({
     name: `connector/${id}`,
     setup: (ctx) => {
-      const token = async (): Promise<string> => {
-        let credential = await ctx.credentials.require(id)
+      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)
@@ -60,7 +66,8 @@ export function oauthConnector(options: OAuthConnectorOptions) {
         commands: {
           [`connect:${id}`]: defineCommand({
             description: `Sign in to ${label}`,
-            run: async () => {
+            // The sign-in belongs to the user who runs the command.
+            run: async (_input, { credentials }) => {
               const credential =
                 options.login === 'device'
                   ? await deviceLogin(oauth, {
@@ -77,14 +84,14 @@ export function oauthConnector(options: OAuthConnectorOptions) {
                         ctx.session.authRequired({ connector: id, url }),
                       ...(options.fetch ? { fetch: options.fetch } : {}),
                     })
-              await ctx.credentials.set(id, credential)
+              await credentials.set(id, credential)
               return `Connected to ${label}.`
             },
           }),
           [`disconnect:${id}`]: defineCommand({
             description: `Sign out of ${label}`,
-            run: async () => {
-              await ctx.credentials.delete(id)
+            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 05a452b8a3..f54e6e6541 100644
--- a/packages/ai-harness/src/define.ts
+++ b/packages/ai-harness/src/define.ts
@@ -17,7 +17,7 @@ import type { MediaOptions } from './media'
 import type { HarnessPlugin } from './plugins'
 import type { HarnessSession } from './session'
 import type { HarnessTurnOptions, RecoverHook } from './turn'
-import type { BusyPolicy, UserInput } from './types'
+import type { BusyPolicy, Principal, UserInput } from './types'
 
 /** The `subagents` option: the same as `chat({ subagents })`. */
 export type HarnessSubagents<TSubagents extends ReadonlyArray<AnyAgent>> = Omit<
@@ -34,7 +34,7 @@ export interface HarnessRouterContext {
   messages: Array<ModelMessage>
   /**
    * The root agents of this turn, in registration order: the harness
-   * `agents`, then the `agents` of session plugins, then of run plugins. An
+   * `agents`, then the `agents` of session plugins, then of turn plugins. An
    * agent that is only in `subagents` is not in this list.
    */
   agents: ReadonlyArray<AnyAgent>
@@ -50,6 +50,10 @@ export interface HarnessRouterContext {
   operationId: string
   /** The id of the turn input, when the turn has one. */
   inputId?: string
+  /** Who sent the turn input. Default: the principal that opened the session. */
+  principal?: Principal
+  /** The `context` of the turn input. Client data: do not trust it. */
+  context?: unknown
   /** The main text adapter of the turn, with the user's keys bound. */
   adapter: AnyTextAdapter
 }
@@ -117,8 +121,10 @@ export interface HarnessConfig<
    * The main agent-loop model, the same as `chat({ adapter })`. A
    * `keyedAdapter(...)` is built for each turn with the user's own key: the
    * key saved with `/connect <provider>`, else the provider's env var.
+   * Leave it out when a plugin `adapter()` picks the model of every turn. A
+   * turn that gets no model from any of them fails.
    */
-  adapter: TAdapter | KeyedAdapter<TAdapter>
+  adapter?: TAdapter | KeyedAdapter<TAdapter>
   systemPrompts?: Array<SystemPrompt>
   tools?: ReadonlyArray<AnyTool>
   middleware?: ReadonlyArray<AnyChatMiddleware>
@@ -139,7 +145,13 @@ export interface HarnessConfig<
    */
   reasoning?: ReasoningOption
   interrupts?: ReadonlyArray<InterruptDefinition<any, any, any, any>>
-  /** Runtime context passed to middleware hooks and server tools. */
+  /**
+   * Runtime context passed to middleware hooks and server tools. When this
+   * and the `context` of a turn input are both plain objects, a turn gets
+   * both merged, and this value wins for a key in both, so a client cannot
+   * replace a server value. Otherwise a turn gets this value when it is set,
+   * else the input's.
+   */
   context?: unknown
   /**
    * Typed agents the session can run from code, commands, plugins, and
@@ -223,7 +235,7 @@ export function isHarnessDefinition(value: unknown): value is AnyHarness {
  * ```
  */
 export function defineHarness<
-  TAdapter extends AnyTextAdapter,
+  TAdapter extends AnyTextAdapter = AnyTextAdapter,
   const TAgents extends ReadonlyArray<AnyAgent> = readonly [],
   const TSubagents extends ReadonlyArray<AnyAgent> = readonly [],
 >(
diff --git a/packages/ai-harness/src/first-party/provider-keys.ts b/packages/ai-harness/src/first-party/provider-keys.ts
index e6ab6261be..19021dfd24 100644
--- a/packages/ai-harness/src/first-party/provider-keys.ts
+++ b/packages/ai-harness/src/first-party/provider-keys.ts
@@ -98,10 +98,13 @@ export function providerKeys(options: {
     name: 'tanstack/provider-keys',
     setup: async (ctx) => {
       const state = ctx.state<ProviderKeysState>({ providers: [] })
-      /** Check every provider, keep the result for UIs, and return the `/keys` lines. */
-      const refresh = async () => {
+      /**
+       * Check every provider, keep the result for UIs, and return the `/keys`
+       * lines. A command passes the credentials of the user who runs it.
+       */
+      const refresh = async (credentials = ctx.credentials) => {
         const described = await Promise.all(
-          providers.map((provider) => describeKey(ctx.credentials, provider)),
+          providers.map((provider) => describeKey(credentials, provider)),
         )
         await state.update(() => ({
           providers: described.map((entry) => entry.status),
@@ -129,28 +132,29 @@ export function providerKeys(options: {
         keys: defineCommand({
           description:
             'Show the model providers and where their keys come from',
-          run: refresh,
+          run: (_input, { credentials }) => refresh(credentials),
         }),
       }
       for (const provider of providers) {
         const { id, label } = provider
         commands[`connect:${id}`] = defineCommand({
           description: `Connect ${label} with your own key`,
-          run: async (_input, { signal }) => {
+          // The key belongs to the user who runs the command.
+          run: async (_input, { signal, credentials }) => {
             const key = (await readKey(provider, signal)).trim()
             if (key === '') {
               throw new Error(`No ${label} key was given. Nothing was saved.`)
             }
-            await ctx.credentials.set(id, { type: 'api_key', value: key })
-            await refresh()
+            await credentials.set(id, { type: 'api_key', value: key })
+            await refresh(credentials)
             return `Connected to ${label} (key ...${maskKey(key)}).`
           },
         })
         commands[`disconnect:${id}`] = defineCommand({
           description: `Remove your ${label} key`,
-          run: async () => {
-            await ctx.credentials.delete(id)
-            await refresh()
+          run: async (_input, { credentials }) => {
+            await credentials.delete(id)
+            await refresh(credentials)
             return `Disconnected from ${label}.`
           },
         })
diff --git a/packages/ai-harness/src/harness-text.ts b/packages/ai-harness/src/harness-text.ts
index 644db9d60c..09277f100f 100644
--- a/packages/ai-harness/src/harness-text.ts
+++ b/packages/ai-harness/src/harness-text.ts
@@ -15,6 +15,13 @@ import type { UserInput } from './types'
 export interface HarnessTextOptions {
   /** The host that runs the inner sessions. Default: a memory host. */
   host?: HarnessHost
+  /**
+   * The kinds the inner model reads. Default: the list of the harness
+   * `adapter`. Set it for a harness whose plugin picks the model, or that
+   * has a `keyedAdapter`: neither list is known until a turn runs.
+   * `media.accepts` narrows it.
+   */
+  inputModalities?: ReadonlyArray<Modality>
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -29,15 +36,18 @@ function lastUserInput(messages: ReadonlyArray<ModelMessage>) {
 
 /**
  * What a harness reads: text, plus the kinds its session sends the model
- * (the adapter's list narrowed by `media.accepts`). `undefined` when neither
- * is known, so the outer harness sends every kind.
+ * (`modalities`, else the adapter's list, narrowed by `media.accepts`).
+ * `undefined` when neither is known, so the outer harness sends every kind.
  */
-function inputsOf(harness: AnyHarness) {
+function inputsOf(
+  harness: AnyHarness,
+  modalities: ReadonlyArray<Modality> | undefined,
+) {
   // ponytail: the harness adapter only. A plugin that picks another model at
-  // runtime is not seen here. A keyedAdapter has no model until a turn
-  // builds it, so it has no `inputModalities` and every kind is sent.
+  // runtime is not seen here, so the caller says it with `inputModalities`.
+  // A keyedAdapter has no model until a turn builds it, so it has no list.
   const kinds = acceptedKinds(
-    harness.adapter.inputModalities,
+    modalities ?? harness.adapter?.inputModalities,
     harness.media?.accepts,
   )
   if (kinds === undefined) return undefined
@@ -197,8 +207,9 @@ function remoteHarnessText(remote: RemoteHarness): AnyTextAdapter {
  * last user message with its content parts (images, audio, video,
  * documents). The outer chat sees the inner turn's text and reasoning.
  *
- * `inputModalities` is what the harness reads: its adapter's list narrowed
- * by `media.accepts`. It is `undefined` for a remote harness.
+ * `inputModalities` is what the harness reads: the `inputModalities`
+ * option, else its adapter's list, narrowed by `media.accepts`. It is
+ * `undefined` for a remote harness.
  *
  * @example
  * ```ts
@@ -221,7 +232,7 @@ export function harnessText(
     kind: 'text',
     name: 'harness',
     model: harness.name,
-    inputModalities: inputsOf(harness),
+    inputModalities: inputsOf(harness, options.inputModalities),
     '~types': TYPES,
     chatStream: (chatOptions) =>
       (async function* (): AsyncGenerator<StreamChunk> {
diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
index a1048ae0e9..48d28b2c38 100644
--- a/packages/ai-harness/src/host.ts
+++ b/packages/ai-harness/src/host.ts
@@ -127,6 +127,28 @@ export interface HarnessHost<TLogState = unknown> {
 
 let warned = false
 
+/** 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)
+  )
+}
+
 /** Throw a clear error for a durable store set that cannot work. */
 function checkDurableStores(persistence: HarnessPersistence) {
   const { stores } = persistence
@@ -225,7 +247,7 @@ export function createHarnessHost<TLogState = undefined>(
   const sessions = new Map<string, Promise<HarnessSession>>()
   const hostId = `host-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`
 
-  return {
+  const host: HarnessHost<TLogState> = {
     open(harness, { threadId, principal, logId: openLogId, promptCache }) {
       const key = `${harness.name}\u0000${threadId}`
       let session = sessions.get(key)
@@ -281,4 +303,13 @@ export function createHarnessHost<TLogState = undefined>(
     },
     logState: (logId) => resolved.get(logId)?.state.reduced,
   }
+  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
index e5665309c9..cd2f884268 100644
--- a/packages/ai-harness/src/http.ts
+++ b/packages/ai-harness/src/http.ts
@@ -3,9 +3,14 @@ import {
   chatParamsFromRequestBody,
   convertMessagesToModelMessages,
   isContentPart,
+  modelMessagesToUIMessages,
+  readInterruptBinding,
+  resolveResumeRunId,
   toServerSentEventsResponse,
+  toServerSentEventsStream,
 } from '@tanstack/ai'
 import { parseRangeHeader, resolveBlobRange } from '@tanstack/ai-persistence'
+import { sessionOfTurn } from './host'
 import { MediaError } from './media'
 import { base64url } from './oauth'
 import {
@@ -71,6 +76,12 @@ const MEDIA_HEADERS = {
 
 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,
@@ -154,8 +165,18 @@ async function mediaResponse(
  * these paths:
  *
  * - `GET  .../capabilities`: the AG-UI capabilities document.
- * - `POST .../run`: standard AG-UI. One request is one prompt, streamed as SSE.
- *   The prompt keeps every content part of the last user message.
+ * - `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. 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. 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.
@@ -171,6 +192,9 @@ async function mediaResponse(
  * - `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.
+ *
+ * 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,
@@ -227,6 +251,48 @@ export function createHarnessHandler(
     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,
+  ) => {
+    const session = await sessionOfTurn(host, harness, runId)
+    const turn = session?.operation(runId)
+    if (!session || !turn) return json({ error: 'unknown run' }, 404)
+    if (!(await canAccess(principal, session.threadId))) {
+      return json({ error: 'forbidden' }, 403)
+    }
+    // `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 startedCursor = session
+      .snapshot()
+      .activeOperations.find((item) => item.id === runId)?.startedCursor
+    const from = resumeFrom ?? startedCursor ?? '0'
+    const reader = new AbortController()
+    const events = turn.events({ from, signal: reader.signal })
+    const cursors: Array<string> = []
+    async function* chunks() {
+      for await (const entry of events) {
+        cursors.push(entry.cursor)
+        yield entry.event
+      }
+    }
+    return new Response(
+      toServerSentEventsStream(chunks(), reader, (_chunk, index) =>
+        cursors.at(index),
+      ),
+      { headers: SSE_HEADERS },
+    )
+  }
+
   return async (request) => {
     const url = new URL(request.url)
     const route = url.pathname.split('/').at(-1)
@@ -249,8 +315,12 @@ export function createHarnessHandler(
         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 }
         if (params.resume && params.resume.length > 0) {
-          const receipt = await session.resolve(params.resume)
+          const receipt = await session.resolve(params.resume, ids)
           if (receipt.status === 'rejected' || !receipt.operationId) {
             return json({ error: receipt.reason ?? 'rejected' }, 409)
           }
@@ -267,7 +337,18 @@ export function createHarnessHandler(
         }
         if (message === undefined)
           return json({ error: 'no user message' }, 400)
-        const operation = session.prompt(message)
+        // 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)
+        }
         const reader = new AbortController()
         return toServerSentEventsResponse(
           operation.stream({ signal: reader.signal }),
@@ -277,6 +358,17 @@ export function createHarnessHandler(
         )
       }
 
+      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))
+      }
+
       if (request.method === 'GET' && route === 'events') {
         const threadId = url.searchParams.get('threadId')
         if (!threadId) return json({ error: 'threadId is required' }, 400)
@@ -308,13 +400,7 @@ export function createHarnessHandler(
             }
           },
         })
-        return new Response(body, {
-          headers: {
-            'Content-Type': 'text/event-stream',
-            'Cache-Control': 'no-cache',
-            Connection: 'keep-alive',
-          },
-        })
+        return new Response(body, { headers: SSE_HEADERS })
       }
 
       if (request.method === 'POST' && route === 'control') {
@@ -334,7 +420,7 @@ export function createHarnessHandler(
         )
         const session = await openFor(principal, threadId)
         if (!session) return json({ error: 'forbidden' }, 403)
-        return json(await applyInput(harness, session, input))
+        return json(await applyInput(harness, session, input, principal))
       }
 
       if (
@@ -404,6 +490,30 @@ export function createHarnessHandler(
   }
 }
 
+/**
+ * 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.
+ */
+async function hydration(session: HarnessSession) {
+  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',
+  )
+  return {
+    messages: modelMessagesToUIMessages(await session.transcript()),
+    activeRun: running ? { runId: running.id } : null,
+    interrupts: runId ? { runId, pending: pendingInterrupts } : null,
+  }
+}
+
 /** Session events of one operation, until it finishes. */
 async function* followOperation(
   events: AsyncIterable<{ operationId: string; event: StreamChunk }>,
@@ -487,7 +597,12 @@ export function handleHarnessSocket(options: HarnessSocketOptions): void {
           send({ type: 'harness.snapshot', snapshot: session.snapshot() })
           return
         }
-        const receipt = await applyInput(harness, session, frame.input)
+        const receipt = await applyInput(
+          harness,
+          session,
+          frame.input,
+          principal,
+        )
         send({
           type: 'harness.receipt',
           requestId: frame.requestId,
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index 649c2ddf35..d9f4909176 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -122,6 +122,7 @@ export type {
   Principal,
   Receipt,
   SessionEvent,
+  TurnInfo,
   TurnOverrides,
   UserInput,
 } from './types'
diff --git a/packages/ai-harness/src/log.ts b/packages/ai-harness/src/log.ts
index 189989f2da..9eb2050a4d 100644
--- a/packages/ai-harness/src/log.ts
+++ b/packages/ai-harness/src/log.ts
@@ -25,7 +25,7 @@ export type HarnessRecord =
       type: 'harness.input'
       inputId: string
       input: HarnessInput
-      principal?: { id: string }
+      principal?: { id: string; tenantId?: string }
       at: number
     }
   | {
@@ -102,7 +102,7 @@ export interface ProjectOptions {
 export interface InputState {
   inputId: string
   input: HarnessInput
-  principal?: { id: string }
+  principal?: { id: string; tenantId?: string }
   at: number
   status: 'pending' | 'applied' | 'joined' | 'rejected' | 'settled'
   operationId?: string
diff --git a/packages/ai-harness/src/operation.ts b/packages/ai-harness/src/operation.ts
index 386d1201bd..fad51fe2b6 100644
--- a/packages/ai-harness/src/operation.ts
+++ b/packages/ai-harness/src/operation.ts
@@ -27,6 +27,8 @@ const TERMINAL: ReadonlySet<OperationStatus> = new Set([
 /** The session-side implementation of {@link Operation}. */
 export class OperationImpl<TResult> implements Operation<TResult> {
   readonly id: string
+  /** The feed head when the operation was made. Its events come after it. */
+  readonly startedCursor: Cursor
   readonly abortController = new AbortController()
   readonly receipt: Promise<Receipt>
   private current: OperationStatus = 'accepted'
@@ -46,6 +48,7 @@ export class OperationImpl<TResult> implements Operation<TResult> {
     id?: string,
   ) {
     this.id = id ?? createOperationId(kind)
+    this.startedCursor = feed.head()
     this.receipt = new Promise<Receipt>((resolve) => {
       this.settleReceipt = resolve
     })
diff --git a/packages/ai-harness/src/plugins.ts b/packages/ai-harness/src/plugins.ts
index 932f58cee6..e9761a9edd 100644
--- a/packages/ai-harness/src/plugins.ts
+++ b/packages/ai-harness/src/plugins.ts
@@ -18,7 +18,7 @@ import type {
   AgentResultOf,
   AnyAgent,
 } from './agents'
-import type { Operation, TurnOverrides } from './types'
+import type { Operation, TurnInfo } from './types'
 import type { CredentialsAccess } from './auth'
 import type { AnyCommand, PluginSessionApi } from './commands'
 import type { ConfigOption } from './config'
@@ -28,9 +28,10 @@ import type { ExtensionItem, ExtensionPoint, PluginEvent } from './extensions'
  * How long a plugin's `setup` result and resources live:
  * - `session` (default): from session open to session close. Resources such
  *   as an index, a watcher, or an LSP server stay up across turns.
- * - `run`: set up for each chat turn, disposed when that turn ends.
+ * - `turn`: set up for each chat turn, disposed when that turn ends.
+ * - `run`: deprecated, the old name of `turn`. It works the same.
  */
-export type PluginLifetime = 'session' | 'run'
+export type PluginLifetime = 'session' | 'turn' | 'run'
 
 /**
  * A prompt a plugin contributes. `id` must be unique in the session. A
@@ -75,13 +76,12 @@ export interface PluginContributions {
    * Pick the main-loop adapter for the next turn, or return `undefined` to
    * keep the harness adapter. The last plugin that returns one wins. The
    * session builds a `keyedAdapter(...)` with the user's key. `turn` is the
-   * turn that starts. Its `overrides.adapter` wins over every pick.
+   * turn that starts: its input, context, and sender. Its
+   * `overrides.adapter` wins over every pick.
    */
-  adapter?: (turn: {
-    operationId: string
-    inputId?: string
-    overrides?: TurnOverrides
-  }) => AnyTextAdapter | KeyedAdapter<AnyTextAdapter> | undefined
+  adapter?: (
+    turn: TurnInfo,
+  ) => AnyTextAdapter | KeyedAdapter<AnyTextAdapter> | undefined
   /**
    * Tools found at run time, for example the tools of an MCP server the user
    * signed in to after the session opened. Called before each chat turn. A
@@ -233,10 +233,17 @@ export interface PluginSetupContext {
   state: <T>(initial: T) => PluginState<T>
   /** Session settings. A change applies at the next turn. */
   config: { get: (key: string) => unknown }
-  /** Credentials of the session's principal. */
+  /**
+   * Credentials of the running turn's sender. Outside a turn: of the
+   * principal that opened the session. They are read at each call, so code
+   * that runs after its turn ends (a tool of a background agent) gets the
+   * sender of the turn that runs at that time. There, use the keys of the
+   * agent run (`ctx.keys` in the agent) and, in a command, the `credentials`
+   * of its `run` context.
+   */
   credentials: CredentialsAccess
   /**
-   * Model provider keys of the session's principal: the key saved with
+   * Model provider keys of the same principal as `credentials`: the key saved with
    * `/connect <provider>`, else the provider's env var. Build a
    * `keyedAdapter(...)` with `await ctx.keys.adapter(adapter)` just before
    * the call. A missing key throws `AuthRequiredError`.
@@ -245,6 +252,12 @@ export interface PluginSetupContext {
   session: PluginSessionApi
   /** Add and remove this plugin's commands while the session runs. */
   commands: PluginCommands
+  /**
+   * The turn this plugin is set up for: its input, context, and sender. Set
+   * only for a plugin with `lifetime: 'turn'`. A session plugin has no turn
+   * at setup.
+   */
+  turn?: TurnInfo
 }
 
 export interface PluginDefinition {
@@ -365,6 +378,8 @@ export interface MountEnvironment {
   >
   /** Session services. Tests of the mount alone can leave them out. */
   services?: PluginServices
+  /** The turn of a run mount. Plugins read it as `ctx.turn`. */
+  turn?: TurnInfo
 }
 
 const unavailable = (what: string) => () => {
@@ -611,6 +626,7 @@ export async function mountPlugins(
           },
           ready,
         },
+        ...(env.turn ? { turn: env.turn } : {}),
       })
       for (const handle of plugin.provides ?? []) {
         if (!provided.has(handle)) {
diff --git a/packages/ai-harness/src/protocol.ts b/packages/ai-harness/src/protocol.ts
index 74e8a2e4c6..6fc57b1a13 100644
--- a/packages/ai-harness/src/protocol.ts
+++ b/packages/ai-harness/src/protocol.ts
@@ -4,7 +4,7 @@ import type { StreamChunk } from '@tanstack/ai'
 import type { AnyAgent } from './agents'
 import type { AnyHarness } from './define'
 import type { HarnessSession, SessionSnapshot } from './session'
-import type { Cursor, HarnessInput, Receipt } from './types'
+import type { Cursor, HarnessInput, Principal, Receipt } from './types'
 
 /** The session-tier protocol version. Sent in `subscribe` and `hello`. */
 export const HARNESS_PROTOCOL_VERSION = 1
@@ -114,19 +114,31 @@ export function parseControlFrame(data: string): ControlFrame {
 
 /**
  * Apply a client input to a session. Only agents in `expose.agents` can run
- * from a client. Resolves to the receipt.
+ * from a client. 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 }
+  const id = {
+    ...(input.inputId === undefined ? {} : { inputId: input.inputId }),
+    ...(principal ? { principal } : {}),
+  }
+  const sent = {
+    ...id,
+    ...('context' in input && input.context !== undefined
+      ? { context: input.context }
+      : {}),
+  }
   switch (input.op) {
     case 'prompt': {
       const operation = session.prompt(input.message, {
         ...(input.busy ? { busy: input.busy } : {}),
-        ...id,
+        ...sent,
       })
       // Nobody may await a turn a client started. Its receipt is the answer.
       operation.then(
@@ -136,15 +148,19 @@ export async function applyInput(
       return operation.receipt
     }
     case 'steer':
-      return session.steer(input.message, id)
+      return session.steer(input.message, sent)
     case 'followUp':
-      return session.followUp(input.message, id)
+      return session.followUp(input.message, sent)
     case 'resolve':
       return session.resolve(input.resume, id)
     case 'cancel':
       return session.cancel(input.operationId)
     case 'command': {
-      const operation = session.command(input.name, input.input)
+      const operation = session.command(
+        input.name,
+        input.input,
+        principal ? { principal } : undefined,
+      )
       operation.then(
         () => {},
         () => {},
diff --git a/packages/ai-harness/src/resources.ts b/packages/ai-harness/src/resources.ts
index 41c093a521..3230fc5044 100644
--- a/packages/ai-harness/src/resources.ts
+++ b/packages/ai-harness/src/resources.ts
@@ -1,5 +1,5 @@
 /**
- * Resources one plugin owns for one lifetime (a session or a run).
+ * Resources one plugin owns for one lifetime (a session or a turn).
  *
  * - `acquire(open, close)` registers `close` only after `open` succeeds.
  * - If the scope closes while `open` is still running, the late resource is
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 2498841321..0b4d91735f 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -1,5 +1,6 @@
 import {
   EventType,
+  INTERRUPT_PAYLOAD_METADATA_KEY,
   LogRecordsCapability,
   RUN_CANCEL_REASON,
   StreamProcessor,
@@ -53,6 +54,7 @@ import type {
   RunAgentResumeItem,
   RunRecord,
   SchemaInput,
+  Scope,
   StreamChunk,
   SubagentBinding,
   SubagentRouterPick,
@@ -111,6 +113,7 @@ import type {
   Principal,
   Receipt,
   SessionEvent,
+  TurnInfo,
   TurnOverrides,
   UserInput,
 } from './types'
@@ -169,7 +172,16 @@ export interface SessionSnapshot {
    * outside input. `idle`: ready for a prompt (agents may still run).
    */
   status: 'idle' | 'running' | 'requires_action'
-  activeOperations: Array<{ id: string; kind: string; agent?: string }>
+  activeOperations: Array<{
+    id: string
+    kind: string
+    agent?: string
+    /**
+     * Every event of this operation comes after this cursor. Pass it as
+     * `from` to `events()` to read the operation from its first event.
+     */
+    startedCursor?: Cursor
+  }>
   queuedTurns: number
   pendingInterrupts: Array<Interrupt>
   /** Questions a command or a plugin asked, waiting for `session.answer`. */
@@ -253,23 +265,39 @@ interface QueuedTurn {
   operation: OperationImpl<ChatTurnResult>
   message?: UserInput
   resume?: Array<RunAgentResumeItem>
-  parentRunId?: string
+  /** A resolve: the interrupted turn it answers. */
+  answers?: InterruptedTurn
   inputId?: string
   /** The settings of this one turn. Kept in memory only, not in the log. */
   overrides?: TurnOverrides
+  /** Who sent the input. Its credentials and keys run the turn. */
+  principal?: Principal
+  /** The `context` of the input. */
+  context?: unknown
   /**
-   * A resolve of a routed turn: the messages it continues from, with the
-   * agents' cards. `root` is true when `routing` sent the turn to root
-   * agents, and false for `subagents.router`.
+   * The message of a turn that recovery runs again. The transcript has it
+   * already, so only plugins and the router read it.
    */
-  routed?: { messages: Array<UIMessage>; root: boolean }
+  sentMessage?: UserInput
 }
 
 /** The interrupts the last turn stopped for, and how a resolve continues it. */
 interface InterruptedTurn {
   runId: string
   interrupts: Array<Interrupt>
-  routed?: QueuedTurn['routed']
+  /**
+   * A routed turn stopped: the messages a resolve continues from, with the
+   * agents' cards. `root` is true when `routing` sent the turn to root
+   * agents, and false for `subagents.router`.
+   */
+  routed?: { messages: Array<UIMessage>; root: boolean }
+  /**
+   * Who sent the input of the stopped turn. Only this principal's saved
+   * credential answers its sign-ins. A copy from an older version has none.
+   */
+  principal?: { id: string; tenantId?: string }
+  /** The `context` of the stopped turn's input, so the resume sees it too. */
+  context?: unknown
 }
 
 /** Where `stores.metadata` keeps the interrupted turn of each thread. */
@@ -280,15 +308,29 @@ function isInterruptedTurn(value: unknown): value is InterruptedTurn {
   if (!isRecord(value) || typeof value.runId !== 'string') return false
   if (!Array.isArray(value.interrupts)) return false
   if (!value.interrupts.every((item) => isRecord(item))) return false
-  const { routed } = value
+  const { routed, principal } = value
+  const isPrincipal =
+    principal === undefined ||
+    (isRecord(principal) && typeof principal.id === 'string')
   return (
-    routed === undefined ||
-    (isRecord(routed) &&
-      Array.isArray(routed.messages) &&
-      typeof routed.root === 'boolean')
+    isPrincipal &&
+    (routed === undefined ||
+      (isRecord(routed) &&
+        Array.isArray(routed.messages) &&
+        typeof routed.root === 'boolean'))
   )
 }
 
+/** The connector a sign-in interrupt (`require` with `wait`) waits for. */
+function signInConnector(interrupt: Interrupt | undefined) {
+  if (interrupt?.reason !== 'auth_required') return undefined
+  const payload = interrupt.metadata?.[INTERRUPT_PAYLOAD_METADATA_KEY]
+  const request = isRecord(payload) ? payload.request : undefined
+  return isRecord(request) && typeof request.connector === 'string'
+    ? request.connector
+    : undefined
+}
+
 /** Limits for a harness's children when `subagents.limits` is not set. */
 export const DEFAULT_SUBAGENT_LIMITS = {
   maxDepth: 2,
@@ -318,6 +360,58 @@ const errorText = (error: unknown) =>
 const cacheObject = (option: PromptCacheOptions | undefined) =>
   typeof option === 'string' ? { retention: option, key: undefined } : option
 
+/** The credential scope of `principal` in a thread, with only the set fields. */
+const scopeOf = (
+  threadId: string,
+  principal: Principal | undefined,
+): Scope => ({
+  threadId,
+  ...(principal ? { userId: principal.id } : {}),
+  ...(principal?.tenantId ? { tenantId: principal.tenantId } : {}),
+})
+
+/** What the log and the inbox keep of a principal: its id and tenant. */
+const storedPrincipal = (principal: Principal | undefined) =>
+  principal
+    ? {
+        principal: {
+          id: principal.id,
+          ...(principal.tenantId ? { tenantId: principal.tenantId } : {}),
+        },
+      }
+    : {}
+
+/** One sender: the same id and tenant, or no principal on both. */
+const isSameSender = (
+  a: Pick<Principal, 'id' | 'tenantId'> | undefined,
+  b: Pick<Principal, 'id' | 'tenantId'> | undefined,
+) => a?.id === b?.id && a?.tenantId === b?.tenantId
+
+/**
+ * What makes two inputs with one id the same input: the payload and the
+ * sender. The same id from another sender is a conflict, not a retry.
+ */
+const inputKey = (
+  input: unknown,
+  principal: Pick<Principal, 'id' | 'tenantId'> | undefined,
+) => JSON.stringify([input, principal?.id ?? null, principal?.tenantId ?? null])
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  isRecord(value) &&
+  [Object.prototype, null].includes(Object.getPrototypeOf(value))
+
+/**
+ * The chat() context of a turn. Two plain objects merge, and the harness
+ * value wins, so a client cannot replace a server value. Else the harness
+ * value when it is set, else the input's.
+ */
+function turnContext(harness: unknown, input: unknown) {
+  if (isPlainObject(harness) && isPlainObject(input)) {
+    return { ...input, ...harness }
+  }
+  return harness !== undefined ? harness : input
+}
+
 /** A short transcript note about how an agent ended, for the next turn. */
 function referenceNote(
   agent: string,
@@ -355,6 +449,10 @@ const CHAT_OPS = new Set<string>(['prompt', 'steer', 'followUp', 'resolve'])
 /** Why a turn stops when its input passes its time limit. */
 const TIMEOUT_REASON = 'harness:input-timeout'
 
+/** Why a turn fails when no option gives it an adapter. */
+const NO_MODEL =
+  'This turn has no model. Set `adapter` in defineHarness, return one from a plugin `adapter()`, or pass `overrides.adapter` to the turn.'
+
 /**
  * The text of the last assistant message: the answer of an operation rebuilt
  * from the log, or of a routed turn.
@@ -484,6 +582,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     operation?: OperationImpl<ChatTurnResult>
     /** Used only when the steer runs as its own turn. A join ignores them. */
     overrides?: TurnOverrides
+    principal?: Principal
+    /** Used only when the steer runs as its own turn, as `overrides`. */
+    context?: unknown
   }> = []
   /**
    * Waiting steers with an abort request. An id lands here before the abort
@@ -494,6 +595,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   private readonly joining = new Set<string>()
   private readonly pendingNotes: Array<string> = []
   private activeTurn: OperationImpl<ChatTurnResult> | undefined
+  /** Who sent the input of the running turn. */
+  private turnPrincipal: Principal | undefined
   /**
    * The last turn stopped for these interrupts. `routed`: a routed turn
    * stopped. The resolve continues its saved plan. `stores.metadata` keeps a
@@ -517,6 +620,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       message: string
       schema: SchemaInput | undefined
       secret: boolean
+      /** The operation whose events carry the question and its answer. */
+      operationId: string
       resolve: (value: unknown) => void
       reject: (error: unknown) => void
     }
@@ -525,9 +630,27 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   /** Reads each plugin's saved state, so the first snapshot has it. */
   private readonly stateLoaders = new Map<string, () => Promise<unknown>>()
   private readonly localState = new Map<string, unknown>()
+  /** The credentials of the running turn's sender, else of the session's principal. */
   private readonly credentialAccess: CredentialsAccess
-  /** Model provider keys: saved with `/connect <provider>`, else the env var. */
+  /**
+   * The connectors whose sign-in the user cancelled. Their `require` with
+   * `wait` fails the tool, as without `wait`, until the next new turn.
+   */
+  private readonly declinedSignIns = new Set<string>()
+  /**
+   * Model provider keys of the same principal as `credentialAccess`: saved
+   * with `/connect <provider>`, else the env var.
+   */
   private readonly keys: ProviderKeys
+  /**
+   * The credentials of one principal: the user who runs a command, or an
+   * agent that outlives a turn. A save there can answer that user's sign-ins.
+   */
+  private readonly credentialsOf: (
+    principal: Principal | undefined,
+  ) => CredentialsAccess
+  /** The provider keys of one principal, for an agent that outlives a turn. */
+  private readonly keysOf: (principal: Principal | undefined) => ProviderKeys
   private readonly services: PluginServices
   private readonly media: SessionDependencies['media']
   private readonly mediaStore: MediaStore
@@ -568,15 +691,29 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           ...(error.url ? { url: error.url } : {}),
         }),
       )
+    // The scope is read at each call, so it follows the running turn.
     this.credentialAccess = credentialsFor(
       deps.credentials,
+      () => scopeOf(deps.threadId, this.sender()),
+      onMissing,
       {
-        threadId: deps.threadId,
-        ...(deps.principal ? { userId: deps.principal.id } : {}),
+        // A tool of a running turn can wait, unless the user cancelled the
+        // sign-in for this turn.
+        canWait: (id) =>
+          this.activeTurn !== undefined && !this.declinedSignIns.has(id),
+        onSet: () => this.resumeSignIns(),
       },
-      onMissing,
     )
     this.keys = providerKeysFor(this.credentialAccess, onMissing)
+    this.credentialsOf = (principal) =>
+      credentialsFor(
+        deps.credentials,
+        scopeOf(deps.threadId, principal),
+        onMissing,
+        { onSet: () => this.resumeSignIns() },
+      )
+    this.keysOf = (principal) =>
+      providerKeysFor(this.credentialsOf(principal), onMissing)
     this.services = {
       emit: (plugin, name, value) => this.emitPluginEvent(plugin, name, value),
       on: (name, handler) => {
@@ -831,6 +968,14 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
    * `overrides` changes the adapter, reasoning, prompt cache, or tools of
    * this turn only (see `TurnOverrides`). A steer that joins the running
    * turn uses the overrides of that turn, and its own are ignored.
+   *
+   * `principal` is who sent the message. Default: the principal that opened
+   * the session. The log keeps it, and the turn runs with its credentials
+   * and provider keys. A steer that joins the running turn runs with the
+   * credentials of that turn's sender.
+   *
+   * `context` is JSON data from the client, stored with the input. Tools
+   * get it in their context (see `HarnessConfig.context`). Do not trust it.
    */
   prompt(
     message: UserInput,
@@ -838,22 +983,50 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       busy?: BusyPolicy
       inputId?: string
       overrides?: TurnOverrides
+      principal?: Principal
+      context?: unknown
+      /** @internal The AG-UI `runId` of a `POST run` request. The turn runs as it. */
+      runId?: string
     },
   ): Operation<ChatTurnResult> {
     const busy = options?.busy ?? this.harness.busy ?? 'queue'
     const inputId = options?.inputId ?? createInputId()
     const overrides = options?.overrides
-    const input: HarnessInput = { op: 'prompt', message, busy }
-    const known = this.knownTurn(inputId, input)
+    const principal = options?.principal ?? this.principal
+    const context = options?.context
+    const input: HarnessInput = {
+      op: 'prompt',
+      message,
+      busy,
+      ...(context !== undefined ? { context } : {}),
+    }
+    const known = this.knownTurn(inputId, input, principal)
     if (known) return known
-    const operation = this.createTurnOperation()
+    const runId = options?.runId
+    // A run id must not take the id of another operation.
+    if (runId !== undefined && this.operations.has(runId)) {
+      const refused = this.createTurnOperation()
+      this.refuse(refused, { inputId, status: 'rejected', reason: 'conflict' })
+      return refused
+    }
+    const operation = this.createTurnOperation(runId)
     this.bindTurn(inputId, operation)
-    void this.accept(inputId, input).then(
-      (admission) => {
+    void this.accept(inputId, input, principal).then(
+      async (admission) => {
         if (admission !== 'new') {
           this.answerDuplicate(operation, inputId, admission)
           return
         }
+        // Awaited only for a client run id, so other prompts keep their order.
+        if (runId !== undefined && (await this.isRunTaken(runId))) {
+          this.reject(inputId, 'conflict')
+          this.refuse(operation, {
+            inputId,
+            status: 'rejected',
+            reason: 'conflict',
+          })
+          return
+        }
         if (this.activeTurn && busy === 'reject') {
           this.reject(inputId, 'busy')
           this.refuse(operation, {
@@ -864,16 +1037,26 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           return
         }
         const isWaiting = this.activeTurn !== undefined || this.queue.length > 0
+        // A steer joins the running turn, so the receipt names that turn, as
+        // `steer()` does.
+        const running = busy === 'steer' ? this.activeTurn : undefined
         this.answerTurn(operation, {
           inputId,
           status: isWaiting && busy !== 'steer' ? 'queued' : 'accepted',
-          operationId: operation.id,
+          operationId: running?.id ?? operation.id,
         })
-        if (this.activeTurn && busy === 'steer') {
-          this.steerQueue.push({ inputId, message, operation, overrides })
+        const sent = { principal, context }
+        if (running) {
+          this.steerQueue.push({
+            inputId,
+            message,
+            operation,
+            overrides,
+            ...sent,
+          })
           return
         }
-        this.enqueueTurn({ operation, message, inputId, overrides })
+        this.enqueueTurn({ operation, message, inputId, overrides, ...sent })
       },
       (error: unknown) => {
         // The input was not stored. After a log failure, say why the
@@ -890,25 +1073,38 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     return operation
   }
 
-  /** Add a message to the running turn at its next model call. */
+  /**
+   * Add a message to the running turn at its next model call. `principal`
+   * and `context` mean the same as in `prompt`.
+   */
   async steer(
     message: UserInput,
-    options?: { inputId?: string },
+    options?: { inputId?: string; principal?: Principal; context?: unknown },
   ): Promise<Receipt> {
     const inputId = options?.inputId ?? createInputId()
-    const admission = await this.accept(inputId, { op: 'steer', message })
+    const principal = options?.principal ?? this.principal
+    const context = options?.context
+    const admission = await this.accept(
+      inputId,
+      {
+        op: 'steer',
+        message,
+        ...(context !== undefined ? { context } : {}),
+      },
+      principal,
+    )
     if (admission !== 'new') return this.duplicateReceipt(inputId, admission)
     if (!this.activeTurn) {
       const operation = this.createTurnOperation()
       this.bindTurn(inputId, operation)
-      this.enqueueTurn({ operation, message, inputId })
+      this.enqueueTurn({ operation, message, inputId, principal, context })
       return this.keep({
         inputId,
         status: 'accepted',
         operationId: operation.id,
       })
     }
-    this.steerQueue.push({ inputId, message })
+    this.steerQueue.push({ inputId, message, principal, context })
     return this.keep({
       inputId,
       status: 'accepted',
@@ -919,13 +1115,29 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   /**
    * Run a turn after the current work settles. `overrides` changes the
    * adapter, reasoning, prompt cache, or tools of this turn only.
+   * `principal` and `context` mean the same as in `prompt`.
    */
   async followUp(
     message: UserInput,
-    options?: { inputId?: string; overrides?: TurnOverrides },
+    options?: {
+      inputId?: string
+      overrides?: TurnOverrides
+      principal?: Principal
+      context?: unknown
+    },
   ): Promise<Receipt> {
     const inputId = options?.inputId ?? createInputId()
-    const admission = await this.accept(inputId, { op: 'followUp', message })
+    const principal = options?.principal ?? this.principal
+    const context = options?.context
+    const admission = await this.accept(
+      inputId,
+      {
+        op: 'followUp',
+        message,
+        ...(context !== undefined ? { context } : {}),
+      },
+      principal,
+    )
     if (admission !== 'new') return this.duplicateReceipt(inputId, admission)
     const operation = this.createTurnOperation()
     this.bindTurn(inputId, operation)
@@ -936,34 +1148,77 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       message,
       inputId,
       overrides: options?.overrides,
+      principal,
+      context,
     })
     return this.keep({ inputId, status, operationId: operation.id })
   }
 
   /**
    * Answer the interrupts of the last turn. One resume must answer every open
-   * interrupt of that turn (the AG-UI rule).
+   * interrupt of that turn (the AG-UI rule). `principal` means the same as in
+   * `prompt`: the turn that continues runs with its credentials.
    */
   async resolve(
     resume: Array<RunAgentResumeItem>,
-    options?: { inputId?: string },
+    options?: {
+      inputId?: string
+      principal?: Principal
+      /** @internal The AG-UI `runId` of a `POST run` request. The turn runs as it. */
+      runId?: string
+    },
   ): Promise<Receipt> {
     const inputId = options?.inputId ?? createInputId()
-    const admission = await this.accept(inputId, { op: 'resolve', resume })
+    const principal = options?.principal ?? this.principal
+    const admission = await this.accept(
+      inputId,
+      { op: 'resolve', resume },
+      principal,
+    )
     if (admission !== 'new') return this.duplicateReceipt(inputId, admission)
-    if (!this.interrupted) {
+    const runId = options?.runId
+    // A run id must not take the id of another operation or stored run.
+    const isTaken =
+      runId !== undefined &&
+      (this.operations.has(runId) || (await this.isRunTaken(runId)))
+    if (isTaken) {
+      this.reject(inputId, 'conflict')
+      return { inputId, status: 'rejected', reason: 'conflict' }
+    }
+    const answers = this.interrupted
+    if (!answers) {
       this.reject(inputId, 'no_pending_interrupts')
       return { inputId, status: 'rejected', reason: 'no_pending_interrupts' }
     }
-    if (this.activeTurn) {
+    // A client answers on RUN_FINISHED, while the interrupted turn still
+    // ends. The resolve runs right after it.
+    const isEnding = this.activeTurn?.id === answers.runId
+    if (this.activeTurn && !isEnding) {
       this.reject(inputId, 'busy')
       return { inputId, status: 'rejected', reason: 'busy' }
     }
-    const { runId: parentRunId, routed } = this.interrupted
+    // A cancelled sign-in fails its tool when the turn runs it again.
+    for (const entry of resume) {
+      const connector = signInConnector(
+        answers.interrupts.find((item) => item.id === entry.interruptId),
+      )
+      if (connector && entry.status === 'cancelled')
+        this.declinedSignIns.add(connector)
+    }
     this.interrupted = undefined
-    const operation = this.createTurnOperation()
+    const operation = this.createTurnOperation(runId)
     this.bindTurn(inputId, operation)
-    this.enqueueTurn({ operation, resume, parentRunId, inputId, routed })
+    // The turn goes on with the context its input sent.
+    const turn: QueuedTurn = {
+      operation,
+      resume,
+      inputId,
+      answers,
+      principal,
+      context: answers.context,
+    }
+    if (isEnding) this.queue.unshift(turn)
+    else this.enqueueTurn(turn)
     // The stored copy goes too, so a restart does not offer this turn again.
     // A failed delete is a warning: the resolve runs anyway.
     await this.persistence.stores.metadata
@@ -1093,6 +1348,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         id: operation.id,
         kind: operation.kind,
         ...(operation.agent ? { agent: operation.agent } : {}),
+        startedCursor: operation.startedCursor,
       })),
       // A steer that waits to join the running turn waits too.
       queuedTurns: this.queue.length + this.steerQueue.length,
@@ -1242,15 +1498,24 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     } satisfies SessionDescription
   }
 
-  /** Run a plugin command. Its input is checked against the command's schema. */
-  command(name: string, input?: unknown): Operation<unknown> {
+  /**
+   * Run a plugin command. Its input is checked against the command's schema.
+   * `principal` is who runs it. Default: the principal that opened the
+   * session. The log keeps it, and the command gets that user's credentials.
+   */
+  command(
+    name: string,
+    input?: unknown,
+    options?: { principal?: Principal },
+  ): Operation<unknown> {
     const operation = new OperationImpl<unknown>(
       'command',
       this.feed,
       (target) => this.cancel(target.id),
     )
     this.operations.set(operation.id, operation)
-    void this.executeCommand(operation, name, input)
+    const principal = options?.principal ?? this.principal
+    void this.executeCommand(operation, name, input, principal)
     return operation
   }
 
@@ -1283,7 +1548,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     this.questions.delete(questionId)
     await this.applied(inputId, 'session')
     this.feed.publish(
-      'session',
+      question.operationId,
       customEvent(HARNESS_EVENTS.questionAnswered, { questionId }),
     )
     question.resolve(checked)
@@ -1345,6 +1610,55 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     if (isInterruptedTurn(stored)) this.interrupted = stored
   }
 
+  /**
+   * Make `stopped` the interrupted turn. `stores.metadata` gets it first, so a
+   * restart can resolve it too, and a resolve cannot delete the copy before
+   * it is written. A failed write is a warning.
+   */
+  private async keepInterrupted(
+    operation: OperationImpl<ChatTurnResult>,
+    stopped: InterruptedTurn,
+  ): Promise<void> {
+    await this.persistence.stores.metadata
+      ?.set(INTERRUPTED, this.threadId, stopped)
+      .catch((error: unknown) =>
+        this.warn(operation, 'harness:interrupts', error),
+      )
+    this.interrupted = stopped
+  }
+
+  /**
+   * A saved credential can answer the sign-ins the last turn waits for. When
+   * every open interrupt is a sign-in and each of their connectors has a
+   * credential of the turn's sender now, the turn goes on as that sender and
+   * its tools run again. The input id comes from the interrupts, so a second
+   * save does not resolve them twice.
+   */
+  private async resumeSignIns(): Promise<void> {
+    const stopped = this.interrupted
+    const waiting = stopped?.interrupts ?? []
+    const connectors = waiting.map(signInConnector)
+    if (waiting.length === 0) return
+    // Another user's credential never answers this sign-in.
+    const principal = stopped?.principal ?? this.principal
+    const credentials = this.credentialsOf(principal)
+    for (const connector of connectors) {
+      if (!connector || !(await credentials.get(connector))) return
+    }
+    if (this.interrupted !== stopped) return
+    await this.resolve(
+      waiting.map((interrupt, index) => ({
+        interruptId: interrupt.id,
+        status: 'resolved',
+        payload: { connector: connectors[index] },
+      })),
+      {
+        inputId: `sign-in:${waiting.map((item) => item.id).join(',')}`,
+        ...(principal ? { principal } : {}),
+      },
+    )
+  }
+
   /** Put each plugin's saved state in the snapshot before the first read. */
   private async loadPluginState() {
     for (const [plugin, load] of this.stateLoaders) {
@@ -1355,16 +1669,20 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   private ask(question: Question<SchemaInput | undefined>): Promise<unknown> {
     if (this.closing) return Promise.reject(new Error('Session closed.'))
     const questionId = `q-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`
+    // On the running chat turn, so a client that streams the turn (`POST
+    // run`) sees it. The session stream has every operation's events.
+    const operationId = this.activeTurn?.id ?? 'session'
     return new Promise((resolve, reject) => {
       this.questions.set(questionId, {
         message: question.message,
         schema: question.schema,
         secret: question.secret === true,
+        operationId,
         resolve,
         reject,
       })
       this.feed.publish(
-        'session',
+        operationId,
         customEvent(HARNESS_EVENTS.question, {
           questionId,
           message: question.message,
@@ -1377,13 +1695,29 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     })
   }
 
-  private pluginApi(): PluginSessionApi {
+  /**
+   * Who sent the input of the running turn, else the principal that opened
+   * the session. Turns run one at a time, so one value is enough.
+   */
+  private sender(): Principal | undefined {
+    return this.turnPrincipal ?? this.principal
+  }
+
+  /**
+   * The session API of plugins. With `principal` (a command), it acts for
+   * that user. Without it, it follows the sender of the running turn.
+   */
+  private pluginApi(principal?: Principal): PluginSessionApi {
+    const sender = () => principal ?? this.sender()
     return {
       threadId: this.threadId,
-      principal: this.principal,
+      get principal() {
+        return sender()
+      },
       snapshot: () => this.snapshot(),
       // A plugin turn always waits its turn. It cannot see a busy rejection.
-      prompt: (text) => this.prompt(text, { busy: 'queue' }),
+      prompt: (text) =>
+        this.prompt(text, { busy: 'queue', principal: sender() }),
       transcript: () => this.transcript(),
       replaceTranscript: (messages) =>
         this.messages.saveThread(this.threadId, messages),
@@ -1479,9 +1813,10 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     operation: OperationImpl<unknown>,
     name: string,
     input: unknown,
+    principal: Principal | undefined,
   ): Promise<void> {
     const inputId = createInputId()
-    await this.accept(inputId, { op: 'command', name, input })
+    await this.accept(inputId, { op: 'command', name, input }, principal)
     const entry = this.sessionPlugins?.commands.get(name)
     if (!entry) {
       this.reject(inputId, 'unknown_command')
@@ -1510,7 +1845,10 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     try {
       const result: unknown = await entry.command.run(checked, {
         signal: operation.abortController.signal,
-        session: this.services.session,
+        // The command acts for its sender, also while another user's turn runs.
+        session: principal ? this.pluginApi(principal) : this.services.session,
+        ...(principal ? { principal } : {}),
+        credentials: this.credentialsOf(principal),
       })
       operation.publish(
         customEvent('harness.command.result', {
@@ -1591,8 +1929,10 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     const next = this.queue.shift()
     if (!next) return
     this.activeTurn = next.operation
+    this.turnPrincipal = next.principal
     void this.runTurn(next).finally(() => {
       this.activeTurn = undefined
+      this.turnPrincipal = undefined
       this.drain()
     })
   }
@@ -1710,17 +2050,28 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
 
   /**
    * Take the waiting steers that join now: the prefix up to the first one
-   * that has an abort request, or that `turn.canJoin` refuses. A steer that
-   * a join took already stays in, with no new check. Returns how many.
+   * that has an abort request, or that `turn.canJoin` refuses. Without
+   * `canJoin`, only a steer of the running turn's sender joins, so nobody's
+   * message runs with another person's credentials. A steer that a join
+   * took already stays in, with no new check. Returns how many.
    */
   private async claimJoins() {
     const canJoin = this.harness.turn?.canJoin
+    const turnPrincipal = this.sender()
     let count = 0
     for (const steer of this.steerQueue) {
       if (!this.joining.has(steer.inputId)) {
         if (this.isAbortRequested(steer.inputId)) break
-        const candidate = { inputId: steer.inputId, message: steer.message }
-        if (canJoin && !(await canJoin(candidate))) break
+        const candidate = {
+          inputId: steer.inputId,
+          message: steer.message,
+          ...(steer.principal ? { principal: steer.principal } : {}),
+          ...(turnPrincipal ? { turnPrincipal } : {}),
+        }
+        const isAllowed = canJoin
+          ? await canJoin(candidate)
+          : isSameSender(steer.principal, turnPrincipal)
+        if (!isAllowed) break
       }
       count += 1
     }
@@ -1763,6 +2114,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
               inputs: steers.map((steer) => ({
                 inputId: steer.inputId,
                 message: steer.message,
+                ...(steer.principal ? { principal: steer.principal } : {}),
               })),
               signal: running.abortController.signal,
             })
@@ -2030,6 +2382,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   private async runTurn(turn: QueuedTurn): Promise<void> {
     const { operation } = turn
     operation.setStatus('running')
+    // A new turn may ask for a sign-in the user cancelled before.
+    if (!turn.answers) this.declinedSignIns.clear()
     if (turn.inputId) {
       try {
         await this.applied(turn.inputId, operation.id)
@@ -2057,17 +2411,33 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     let stopRunLease = () => {}
     /** The next chat() call runs the root agents that `routing` picked. */
     let isRootPart = false
-    /** The messages of the last run, with the agents' cards, when it was routed. */
-    let cardMessages: Array<UIMessage> | undefined
+    /** chat() refused the resume of this turn, so it ran nothing. */
+    let isResumeRefused = false
     let text = ''
     let interrupts: Array<Interrupt> | undefined
     let failure: string | undefined
     const captured: Array<MediaRecord> = []
+    // What plugins and the router see of this turn. A turn that recovery
+    // runs again gets the message its input sent.
+    const sentMessage = turn.message ?? turn.sentMessage
+    const sender = this.sender()
+    const info: TurnInfo = {
+      operationId: operation.id,
+      ...(turn.inputId ? { inputId: turn.inputId } : {}),
+      ...(sentMessage !== undefined ? { message: sentMessage } : {}),
+      ...(turn.context !== undefined ? { context: turn.context } : {}),
+      ...(sender ? { principal: sender } : {}),
+      ...(turn.overrides ? { overrides: turn.overrides } : {}),
+    }
     try {
       await this.flushNotes()
-      const perRun = this.plugins.filter((plugin) => plugin.lifetime === 'run')
+      // 'turn' and the old 'run'.
+      const perRun = this.plugins.filter(
+        (plugin) => (plugin.lifetime ?? 'session') !== 'session',
+      )
       if (perRun.length > 0) {
         runPlugins = await mountPlugins(perRun, {
+          turn: info,
           threadId: this.threadId,
           registry: this.agentRegistry.fork(),
           harnessTools: [
@@ -2120,9 +2490,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         ...(session?.adapters ?? []),
         ...(runPlugins?.adapters ?? []),
       ]
-        .map((pick) =>
-          pick({ operationId: operation.id, inputId: turn.inputId, overrides }),
-        )
+        .map((pick) => pick(info))
         .filter((adapter) => adapter !== undefined)
         .at(-1)
       const resolvePrompt = (prompt: string | (() => string)) =>
@@ -2158,6 +2526,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       const keepTools =
         keptTools.length > 0 ? keepTurnTools(keptTools) : undefined
       const reasoning = overrides?.reasoning ?? this.harness.reasoning
+      const context = turnContext(this.harness.context, turn.context)
       // The turn value wins over the session value, field by field.
       const turnCache = cacheObject(overrides?.promptCache)
       const promptCache = {
@@ -2166,15 +2535,15 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       }
       // A keyed adapter is built for this turn with the user's key. A
       // missing key publishes `auth_required` and fails the turn.
-      const adapter: AnyTextAdapter = await this.keys.adapter(
-        overrides?.adapter ?? picked ?? this.harness.adapter,
-      )
+      const model = overrides?.adapter ?? picked ?? this.harness.adapter
+      if (!model) throw new Error(NO_MODEL)
+      const adapter: AnyTextAdapter = await this.keys.adapter(model)
       let message =
         turn.message !== undefined
           ? await this.userMessage(turn.message)
           : undefined
       let resume = turn.resume
-      let parentRunId = turn.parentRunId
+      let parentRunId = turn.answers?.runId
       const { chatPersistence, checkpoint } = this
       if (!chatPersistence || !checkpoint) {
         throw new Error('The session is not open yet.')
@@ -2192,14 +2561,16 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           agents: rootAgents,
           abortSignal: signal,
           session: this,
-          ...(turn.message !== undefined ? { input: turn.message } : {}),
+          ...(sentMessage !== undefined ? { input: sentMessage } : {}),
           operationId: operation.id,
           ...(turn.inputId ? { inputId: turn.inputId } : {}),
+          ...(sender ? { principal: sender } : {}),
+          ...(turn.context !== undefined ? { context: turn.context } : {}),
           adapter,
         })
       }
       const isRootTurn =
-        turn.routed?.root === true || (pick ?? 'main') !== 'main'
+        turn.answers?.routed?.root === true || (pick ?? 'main') !== 'main'
       const rootBag =
         routing && isRootTurn
           ? {
@@ -2237,7 +2608,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         )
       }
       /** The messages a resolve of a routed turn continues from. */
-      let routedFrom = turn.routed?.messages
+      let routedFrom = turn.answers?.routed?.messages
       /** Retries since the last finished tool phase. */
       let retries = 0
       /** How many times `turn.beforeFinish` continued this turn. */
@@ -2320,9 +2691,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             ...(this.harness.interrupts
               ? { interrupts: this.harness.interrupts }
               : {}),
-            ...(this.harness.context !== undefined
-              ? { context: this.harness.context }
-              : {}),
+            ...(context !== undefined ? { context } : {}),
             ...(reasoning !== undefined ? { reasoning } : {}),
             promptCache,
             threadId: this.threadId,
@@ -2336,6 +2705,31 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           routedFrom = undefined
           for await (const chunk of stream) {
             cards?.processChunk(chunk)
+            // chat() refused the resume before it ran anything.
+            if (
+              chunk.type === EventType.RUN_ERROR &&
+              (chunk.metadata?.tanstack?.interruptErrors?.length ?? 0) > 0
+            ) {
+              isResumeRefused = true
+            }
+            if (
+              chunk.type === EventType.RUN_FINISHED &&
+              chunk.outcome?.type === 'interrupt'
+            ) {
+              interrupts = chunk.outcome.interrupts
+              const messages = cards?.getMessages()
+              // Pending before a client sees RUN_FINISHED, so a resolve sent
+              // at once is accepted.
+              await this.keepInterrupted(operation, {
+                runId: operation.id,
+                interrupts,
+                ...(messages ? { routed: { messages, root: isRootPart } } : {}),
+                ...storedPrincipal(this.sender()),
+                ...(turn.context !== undefined
+                  ? { context: turn.context }
+                  : {}),
+              })
+            }
             if (
               chunk.type === EventType.RUN_ERROR &&
               turnHooks?.onModelError &&
@@ -2356,12 +2750,6 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             ) {
               text += chunk.delta
             }
-            if (
-              chunk.type === EventType.RUN_FINISHED &&
-              chunk.outcome?.type === 'interrupt'
-            ) {
-              interrupts = chunk.outcome.interrupts
-            }
             if (chunk.type === EventType.RUN_ERROR) failure = chunk.message
             // A finished tool phase resets the retries, and its text stays in
             // the result. Streamed text does not reset them, so a call that
@@ -2371,7 +2759,6 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
               textBefore = text
             }
           }
-          cardMessages = cards?.getMessages()
         } catch (error) {
           // The outer catch handles a cancelled turn, a log failure, and a
           // harness without the hook, as before.
@@ -2530,6 +2917,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       // once.
       if (releaseLease) await releaseLease()
     }
+    // A refused resume ran nothing, so its interrupts wait again. Before the
+    // settlement, so a client that sees it can resolve once more.
+    if (isResumeRefused && turn.answers) {
+      await this.keepInterrupted(operation, turn.answers)
+    }
     if (this.logFailure) {
       if (releaseLease) await releaseLease()
       operation.fail('failed', this.logFailure)
@@ -2547,20 +2939,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       await settleTurn({ outcome: 'failed', error: { message: failure } })
       operation.fail('failed', new Error(failure))
     } else if (interrupts && interrupts.length > 0) {
-      this.interrupted = {
-        runId: operation.id,
-        interrupts,
-        ...(cardMessages
-          ? { routed: { messages: cardMessages, root: isRootPart } }
-          : {}),
-      }
-      // Kept before the turn ends, so a restart right after it can resolve.
-      // A failed write is a warning: the turn still ends interrupted.
-      await this.persistence.stores.metadata
-        ?.set(INTERRUPTED, this.threadId, this.interrupted)
-        .catch((error: unknown) =>
-          this.warn(operation, 'harness:interrupts', error),
-        )
+      // `this.interrupted` was kept at RUN_FINISHED.
       await settleTurn({ outcome: 'interrupted' })
       operation.finish('interrupted', { text, interrupts })
     } else {
@@ -2572,8 +2951,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   }
 
   /**
-   * Steers a turn never reached run next, before other queued turns. A
-   * steer with an abort request settles `aborted` instead.
+   * Steers a turn never reached run next, before other queued turns (after
+   * a resolve of that turn). A steer with an abort request settles `aborted`
+   * instead.
    */
   private requeueWaitingSteers(): void {
     this.joining.clear()
@@ -2606,7 +2986,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       }
       return
     }
-    this.queue.unshift(
+    // A resolve that answers the turn that just ended runs first.
+    const at = this.queue[0]?.answers ? 1 : 0
+    this.queue.splice(
+      at,
+      0,
       ...rest.map((steer) => {
         const next = steer.operation ?? this.createTurnOperation()
         this.bindTurn(steer.inputId, next)
@@ -2615,6 +2999,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           message: steer.message,
           inputId: steer.inputId,
           overrides: steer.overrides,
+          principal: steer.principal,
+          context: steer.context,
         }
       }),
     )
@@ -2708,7 +3094,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       name,
     )
     this.operations.set(operation.id, operation)
-    void this.executeAgent(operation, target, input, options)
+    // The agent runs for the sender of the turn that starts it, also after
+    // that turn ends.
+    void this.executeAgent(operation, target, input, options, this.sender())
     return operation
   }
 
@@ -2757,15 +3145,20 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     target: string | AnyAgent,
     input: unknown,
     options: AgentStartOptions,
+    principal: Principal | undefined,
   ): Promise<void> {
     const name = typeof target === 'string' ? target : target.name
     const inputId = createInputId()
-    await this.accept(inputId, {
-      op: 'agent',
-      agent: name,
-      input,
-      ...(options.wake ? { detached: true } : {}),
-    })
+    await this.accept(
+      inputId,
+      {
+        op: 'agent',
+        agent: name,
+        input,
+        ...(options.wake ? { detached: true } : {}),
+      },
+      principal,
+    )
     const agent: AnyAgent | undefined =
       typeof target === 'string' ? this.agentRegistry.get(target) : target
     if (!agent) {
@@ -2799,7 +3192,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       startedAt: Date.now(),
       kind: 'agent',
       agent: name,
-      ...(this.principal ? { principal: { id: this.principal.id } } : {}),
+      ...storedPrincipal(principal),
     })
     operation.publish({
       type: EventType.RUN_STARTED,
@@ -2843,7 +3236,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         // but not written to history: its messages live in its own thread
         // (`<threadId>:<name>`). Write it to the session thread if a UI must
         // show it after a restart.
-        { ...this.binding(operation, []), budget: this.codeBudget() },
+        {
+          ...this.binding(operation, []),
+          keys: this.keysOf(principal),
+          budget: this.codeBudget(),
+        },
       )
       for await (const chunk of stream) {
         operation.publish(chunk)
@@ -2907,7 +3304,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       })
       const error = { message: failure }
       await end({ status: 'failed', error }, { outcome: 'failed', error })
-      await this.noteAgentEnd(name, 'failed', failure, options)
+      await this.noteAgentEnd(name, 'failed', failure, options, principal)
       operation.fail('failed', new Error(failure))
     } else {
       operation.publish({
@@ -2921,7 +3318,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         { status: 'completed', result: compactForModel(value) },
         { outcome: 'completed' },
       )
-      await this.noteAgentEnd(name, 'finished', value, options)
+      await this.noteAgentEnd(name, 'finished', value, options, principal)
       operation.finish('completed', value)
     }
     stopRunLease()
@@ -2931,13 +3328,15 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
 
   /**
    * Tell the main model how an agent ended: a transcript note (unless
-   * `attach: 'none'`), and a new chat turn when `wake` is set.
+   * `attach: 'none'`), and a new chat turn when `wake` is set. The wake turn
+   * runs as `principal`, the user who started the agent.
    */
   private async noteAgentEnd(
     name: string,
     ended: 'finished' | 'failed',
     result: unknown,
     options: AgentStartOptions,
+    principal?: Principal,
   ): Promise<void> {
     const note = referenceNote(name, result, ended)
     if ((options.attach ?? 'reference') === 'reference') {
@@ -2945,7 +3344,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       if (!this.activeTurn) await this.flushNotes()
     }
     if (options.wake) {
-      void this.followUp(`Background agent ${name} ${ended}: ${note}`)
+      void this.followUp(`Background agent ${name} ${ended}: ${note}`, {
+        ...(principal ? { principal } : {}),
+      })
     }
   }
 
@@ -2960,6 +3361,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     agent: string
     inputId?: string
     wake?: boolean
+    /** Who started the agent. The wake turn runs as this user. */
+    principal?: Principal
   }): Promise<void> {
     const { operationId, inputId } = stopped
     await this.persistence.stores.runs?.update(operationId, {
@@ -2987,9 +3390,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         status: 'failed',
       }),
     )
-    await this.noteAgentEnd(stopped.agent, 'failed', AGENT_STOPPED, {
-      wake: stopped.wake === true,
-    })
+    await this.noteAgentEnd(
+      stopped.agent,
+      'failed',
+      AGENT_STOPPED,
+      { wake: stopped.wake === true },
+      stopped.principal,
+    )
   }
 
   /** Write queued agent notes to the transcript while no turn is writing it. */
@@ -3017,27 +3424,28 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   /**
    * Store an input, unless its id is known. The check before the first
    * `await` is synchronous, so a second call with the same id in the same
-   * tick is a duplicate too.
+   * tick is a duplicate too. `principal` is who sent it.
    */
   private async accept(
     inputId: string,
     input: HarnessInput,
+    principal = this.principal,
   ): Promise<'new' | 'duplicate' | 'conflict'> {
-    const payload = JSON.stringify(input)
+    const sender = storedPrincipal(principal)
+    const payload = inputKey(input, sender.principal)
     const local = this.admitted.get(inputId)
     if (local !== undefined) return local === payload ? 'duplicate' : 'conflict'
     const logged = this.writer?.state.inputs.get(inputId)
     if (logged) {
-      return JSON.stringify(logged.input) === payload ? 'duplicate' : 'conflict'
+      return inputKey(logged.input, logged.principal) === payload
+        ? 'duplicate'
+        : 'conflict'
     }
     this.admitted.set(inputId, payload)
     const at = Date.now()
-    const principal = this.principal
-      ? { principal: { id: this.principal.id } }
-      : {}
     if (this.writer) {
       await this.writer.append([
-        { type: 'harness.input', inputId, input, at, ...principal },
+        { type: 'harness.input', inputId, input, at, ...sender },
       ])
     } else {
       const stored = await this.inbox.append({
@@ -3045,11 +3453,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         threadId: this.threadId,
         input,
         createdAt: at,
-        ...principal,
+        ...sender,
       })
       // The inbox had the id before this session: a restart.
       if (stored.createdAt !== at || stored.status !== 'pending') {
-        return JSON.stringify(stored.input) === payload
+        return inputKey(stored.input, stored.principal) === payload
           ? 'duplicate'
           : 'conflict'
       }
@@ -3061,6 +3469,19 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     return 'new'
   }
 
+  /**
+   * Does `stores.runs` have a run with this id, on any thread? A client run
+   * id must not reuse it. A store that fails counts as yes, so nothing runs.
+   */
+  private async isRunTaken(runId: string): Promise<boolean> {
+    const runs = this.persistence.stores.runs
+    if (!runs) return false
+    return runs.get(runId).then(
+      (run) => run !== null,
+      () => true,
+    )
+  }
+
   /** Record that `operationId` runs the input. A durable host counts attempts. */
   private async markApplied(
     inputId: string,
@@ -3197,11 +3618,16 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
    * The operation for a prompt whose id is known: the live one, one that
    * settles from the log, or a refused one for another payload.
    */
-  private knownTurn(inputId: string, input: HarnessInput) {
-    const payload = JSON.stringify(input)
+  private knownTurn(
+    inputId: string,
+    input: HarnessInput,
+    principal: Principal | undefined,
+  ) {
+    const payload = inputKey(input, principal)
     const local = this.admitted.get(inputId)
     const logged = this.writer?.state.inputs.get(inputId)
-    const stored = local ?? (logged ? JSON.stringify(logged.input) : undefined)
+    const stored =
+      local ?? (logged ? inputKey(logged.input, logged.principal) : undefined)
     if (stored === undefined) return undefined
     if (stored !== payload) {
       const refused = this.createTurnOperation()
@@ -3350,12 +3776,14 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         input.op === 'steer'
       ) {
         const operation = this.createTurnOperation()
-        this.admitted.set(entry.inputId, JSON.stringify(input))
+        this.admitted.set(entry.inputId, inputKey(input, entry.principal))
         this.bindTurn(entry.inputId, operation)
         this.enqueueTurn({
           operation,
           message: input.message,
           inputId: entry.inputId,
+          principal: entry.principal,
+          context: input.context,
         })
       } else {
         this.reject(entry.inputId, 'expired_on_restart')
@@ -3432,6 +3860,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           operation,
           message: input.input.message,
           inputId: input.inputId,
+          principal: input.principal,
+          context: input.input.context,
         })
         continue
       }
@@ -3462,6 +3892,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             agent: input.input.agent,
             inputId: input.inputId,
             wake: input.input.detached,
+            ...(input.principal ? { principal: input.principal } : {}),
           })
         }
         continue
@@ -3533,7 +3964,16 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           ...(operationId ? { resumedFrom: operationId } : {}),
         }),
       )
-      this.enqueueTurn({ operation, inputId: input.inputId })
+      // The transcript has the message, so the turn adds none. Plugins and
+      // the router still get what the input sent.
+      const sent = input.input
+      this.enqueueTurn({
+        operation,
+        inputId: input.inputId,
+        principal: input.principal,
+        ...('message' in sent ? { sentMessage: sent.message } : {}),
+        ...('context' in sent ? { context: sent.context } : {}),
+      })
     }
   }
 }
diff --git a/packages/ai-harness/src/turn.ts b/packages/ai-harness/src/turn.ts
index b2e26ec340..a42a254b7f 100644
--- a/packages/ai-harness/src/turn.ts
+++ b/packages/ai-harness/src/turn.ts
@@ -1,7 +1,7 @@
 import type { ModelMessage } from '@tanstack/ai'
 import type { LogRecord } from '@tanstack/ai-persistence'
 import type { HarnessSession } from './session'
-import type { HarnessInput, UserInput } from './types'
+import type { HarnessInput, Principal, UserInput } from './types'
 
 /** What recovery does with one input. */
 export type RecoverDecision =
@@ -69,6 +69,16 @@ export interface FinishContext {
 export interface JoinCandidate {
   inputId: string
   message: UserInput
+  /**
+   * Who sent the input. A joined input runs with the credentials of the
+   * turn's sender, so refuse a join from another person when that matters.
+   */
+  principal?: Principal
+  /**
+   * Who sent the running turn. Compare it with `principal` to keep one
+   * person's message out of another person's turn.
+   */
+  turnPrincipal?: Principal
 }
 
 /** What `turn.onJoin` gets. */
diff --git a/packages/ai-harness/src/types.ts b/packages/ai-harness/src/types.ts
index 9b6c89e9f6..c1394b1ad4 100644
--- a/packages/ai-harness/src/types.ts
+++ b/packages/ai-harness/src/types.ts
@@ -89,11 +89,16 @@ export interface SessionEvent {
  * `inputId` is an optional id that the caller chooses. A second input with the
  * same id and the same payload gets the first input's receipt and does not run
  * again. The same id with another payload is rejected with `'conflict'`.
+ *
+ * `context` is JSON data the client sends with a message, for example the
+ * screen the user is on. It is stored with the input, so a turn that runs
+ * again after a restart sees the same value. It is client data: do not trust
+ * it. Who sent the input is the principal from `authorize`, not a field here.
  */
 export type HarnessInput = (
-  | { op: 'prompt'; message: UserInput; busy?: BusyPolicy }
-  | { op: 'steer'; message: UserInput }
-  | { op: 'followUp'; message: UserInput }
+  | { op: 'prompt'; message: UserInput; busy?: BusyPolicy; context?: unknown }
+  | { op: 'steer'; message: UserInput; context?: unknown }
+  | { op: 'followUp'; message: UserInput; context?: unknown }
   | { op: 'resolve'; resume: Array<RunAgentResumeItem> }
   | { op: 'agent'; agent: string; input?: unknown; detached?: boolean }
   | { op: 'cancel'; operationId?: string }
@@ -143,6 +148,30 @@ function rejectionMessage(reason: string | undefined) {
 export interface Principal {
   id: string
   name?: string
+  /**
+   * The organization of the principal. The credential scope gets it, so two
+   * organizations' credentials for one user stay apart.
+   */
+  tenantId?: string
+}
+
+/**
+ * A chat turn as plugins and the router see it: the input that started it,
+ * and who sent it.
+ */
+export interface TurnInfo {
+  /** The id of the turn operation. */
+  operationId: string
+  /** The id of the turn input, when the turn has one. */
+  inputId?: string
+  /** The user message of the input. `undefined` for a resolve. */
+  message?: UserInput
+  /** The `context` of the input. Client data: do not trust it. */
+  context?: unknown
+  /** Who sent the input. Default: the principal that opened the session. */
+  principal?: Principal
+  /** The settings of this turn only. Not kept after a restart. */
+  overrides?: TurnOverrides
 }
 
 /** What a chat turn operation resolves to. */
diff --git a/packages/ai-harness/src/view/index.ts b/packages/ai-harness/src/view/index.ts
index 90d327d9b7..b9fb6ffad5 100644
--- a/packages/ai-harness/src/view/index.ts
+++ b/packages/ai-harness/src/view/index.ts
@@ -1,6 +1,6 @@
 // Browser-safe: runtime imports only from @tanstack/ai, @tanstack/store,
 // ../types, ../media-ref, and ./reduce. Everything else is a type.
-import { EventType } from '@tanstack/ai'
+import { EventType, readUnopenedInterruptBinding } from '@tanstack/ai'
 import { createStore } from '@tanstack/store'
 import { mediaPart } from '../media-ref'
 import { HARNESS_EVENTS } from '../types'
@@ -32,6 +32,7 @@ import type {
 import type { ItemFactory } from './reduce'
 import type {
   Approval,
+  ClientToolCall,
   MediaPart,
   SessionViewState,
   SignIn,
@@ -51,6 +52,7 @@ export type { MediaKind, MediaRecord } from '../types'
 export type {
   AgentPart,
   Approval,
+  ClientToolCall,
   MediaPart,
   NoticeKind,
   SessionViewState,
@@ -93,6 +95,7 @@ export interface SessionViewSource {
 /** What `view.on(name, handler)` sends. */
 export interface SessionViewEvents {
   approval: Approval
+  clientTool: ClientToolCall
   question: ViewQuestion
   signIn: SignIn
   toolCall: { id: string; name: string }
@@ -219,7 +222,8 @@ export function createSessionView(source: SessionViewSource) {
   const store = createStore(() => internal.state)
   const reader = new AbortController()
   const handlers = new Map<string, Set<(value: unknown) => void>>()
-  const decisions = new Map<string, boolean>()
+  /** 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>()
@@ -327,22 +331,27 @@ export function createSessionView(source: SessionViewSource) {
     return messages === state.messages ? state : { ...state, messages }
   }
 
-  const decide = (id: string, approved: boolean) => {
+  /**
+   * 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 open = get().approvals
+    const id = entry.interruptId
     const isDecided =
       resolving || decisions.has(id) || !open.some((item) => item.id === id)
     if (isDecided) return
-    decisions.set(id, approved)
-    if (!open.every((item) => decisions.has(item.id))) return
-    const resume: Array<RunAgentResumeItem> = open.map((item) => ({
-      interruptId: item.id,
-      status: 'resolved',
-      payload: decisions.get(item.id),
-    }))
+    decisions.set(id, entry)
+    const { approvals, clientTools } = get()
+    const waiting = [...approvals, ...clientTools]
+    const resume = waiting.flatMap((item) => decisions.get(item.id) ?? [])
+    if (resume.length < waiting.length) return
     decisions.clear()
     resolving = true
-    commit({ ...get(), approvals: [] })
+    commit({ ...get(), approvals: [], clientTools: [] })
     void source
       .resolve(resume)
       .then(undefined, fail)
@@ -351,6 +360,12 @@ export function createSessionView(source: SessionViewSource) {
         refreshSnapshot()
       })
   }
+  const decide = (id: string, approved: boolean) =>
+    answer(get().approvals, {
+      interruptId: id,
+      status: 'resolved',
+      payload: approved,
+    })
   const decideAll = (approved: boolean) => {
     alive()
     const open = get().approvals
@@ -367,6 +382,34 @@ export function createSessionView(source: SessionViewSource) {
       approve: () => decide(interrupt.id, true),
       reject: () => decide(interrupt.id, false),
     }),
+    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,
@@ -385,6 +428,10 @@ export function createSessionView(source: SessionViewSource) {
     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 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)
   }
diff --git a/packages/ai-harness/src/view/reduce.ts b/packages/ai-harness/src/view/reduce.ts
index d5fd857346..b113cb03c2 100644
--- a/packages/ai-harness/src/view/reduce.ts
+++ b/packages/ai-harness/src/view/reduce.ts
@@ -1,4 +1,4 @@
-import { EventType } from '@tanstack/ai'
+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'
@@ -7,6 +7,7 @@ import type { SessionEvent } from '../types'
 import type {
   AgentPart,
   Approval,
+  ClientToolCall,
   MediaPart,
   NoticeKind,
   SessionViewState,
@@ -35,6 +36,10 @@ const TURN_EVENTS: ReadonlySet<string> = new Set([
 /** 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
@@ -48,6 +53,7 @@ export function emptyState(): SessionViewState {
     connection: 'open',
     messages: [],
     approvals: [],
+    clientTools: [],
     questions: [],
     signIns: [],
     agents: [],
@@ -542,10 +548,30 @@ export function keep<T>(old: Array<T>, next: Array<T>): Array<T> {
     : 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 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, questions, and background agents from a snapshot.
- * Plugin state is taken only for the first snapshot. Later changes come as
- * `STATE_SNAPSHOT` events. Returns `state` when nothing changes.
+ * Take status, approvals, client tools, questions, and background agents
+ * 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,
@@ -555,15 +581,39 @@ export function applySnapshot(
 ): SessionViewState {
   const approvals = keep(
     state.approvals,
-    snapshot.pendingInterrupts.map(
-      (interrupt) =>
-        state.approvals.find((item) => item.id === interrupt.id) ??
-        factory.approval(
-          interrupt,
-          findToolCall(state.messages, interrupt.toolCallId),
-        ),
-    ),
+    snapshot.pendingInterrupts
+      .filter((interrupt) => !isClientTool(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),
+          ),
+      ),
+  )
+  // 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(
@@ -594,6 +644,8 @@ export function applySnapshot(
     snapshot.status === state.status &&
     snapshot.queuedTurns === state.queuedTurns &&
     approvals === state.approvals &&
+    clientTools === state.clientTools &&
+    signIns === state.signIns &&
     questions === state.questions &&
     agents === state.agents &&
     messages === state.messages &&
@@ -605,6 +657,8 @@ export function applySnapshot(
     status: snapshot.status,
     queuedTurns: snapshot.queuedTurns,
     approvals,
+    clientTools,
+    signIns,
     questions,
     agents,
     messages,
diff --git a/packages/ai-harness/src/view/types.ts b/packages/ai-harness/src/view/types.ts
index deafd1dfed..46be2509a4 100644
--- a/packages/ai-harness/src/view/types.ts
+++ b/packages/ai-harness/src/view/types.ts
@@ -75,6 +75,21 @@ export interface Approval {
   reject: () => 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
@@ -115,6 +130,8 @@ export interface SessionViewState {
   connection: 'open' | 'reconnecting' | 'closed'
   messages: Array<ViewMessage>
   approvals: Array<Approval>
+  /** Client tool calls that wait for their output from the UI. */
+  clientTools: Array<ClientToolCall>
   questions: Array<ViewQuestion>
   signIns: Array<SignIn>
   /** Background agents that run now. */
diff --git a/packages/ai-harness/tests/agent-middleware.test.ts b/packages/ai-harness/tests/agent-middleware.test.ts
index de3dc90a6b..ef06a0e5f8 100644
--- a/packages/ai-harness/tests/agent-middleware.test.ts
+++ b/packages/ai-harness/tests/agent-middleware.test.ts
@@ -121,14 +121,14 @@ describe('plugin agentMiddleware', () => {
     await host.close()
   })
 
-  it('runs for a run-lifetime plugin too', async () => {
+  it('runs for a turn-lifetime plugin too', async () => {
     const { runs, middleware } = recordRuns()
     const { host, session } = await open(
       defineHarness({
         name: 'test/agent-middleware',
         adapter: leadCalling('helper'),
         subagents: { agents: [textAgent('helper')] },
-        plugins: () => [agentPlugin(middleware, 'run')],
+        plugins: () => [agentPlugin(middleware, 'turn')],
       }),
     )
 
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..e01d9fda5c
--- /dev/null
+++ b/packages/ai-harness/tests/auth-wait.test.ts
@@ -0,0 +1,517 @@
+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('github', {
+              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('note', { 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(
+      { threadId: 't', userId: 'alice' },
+      'github',
+      { 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)],
+    })
+    const handler = createHarnessHandler({
+      host,
+      harness,
+      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({ threadId: 't', userId: 'bob' }, 'github'),
+    ).toMatchObject({ value: 'bob-key' })
+    expect(
+      await credentials.get({ threadId: 't', userId: 'alice' }, '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
+                },
+              }),
+            },
+          }),
+        }),
+      ],
+    })
+    const handler = createHarnessHandler({
+      host,
+      harness,
+      authorize: () => bob,
+    })
+    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/harness-text-media.test.ts b/packages/ai-harness/tests/harness-text-media.test.ts
index 9551c1321e..7560102cc5 100644
--- a/packages/ai-harness/tests/harness-text-media.test.ts
+++ b/packages/ai-harness/tests/harness-text-media.test.ts
@@ -86,6 +86,26 @@ describe('harnessText media', () => {
     expect(harnessText(studio).inputModalities).toEqual(expected)
   })
 
+  it('reads the inputModalities option, for a harness without an adapter', () => {
+    const plain = defineHarness({ name: 'test/no-adapter' })
+    const studio = defineHarness({
+      name: 'test/picked',
+      adapter: innerAdapter(['text', 'image', 'audio']).adapter,
+      media: { accepts: ['image', 'audio'] },
+    })
+
+    expect(harnessText(plain).inputModalities).toBe(undefined)
+    expect(
+      harnessText(plain, { inputModalities: ['text', 'image'] })
+        .inputModalities,
+    ).toEqual(['text', 'image'])
+    // The option wins over the adapter list, and media.accepts narrows it.
+    expect(
+      harnessText(studio, { inputModalities: ['text', 'image', 'video'] })
+        .inputModalities,
+    ).toEqual(['text', 'image'])
+  })
+
   it('does not know what a remote harness reads', () => {
     expect(harnessText({ url: 'http://remote.test' }).inputModalities).toBe(
       undefined,
diff --git a/packages/ai-harness/tests/input-sender.test.ts b/packages/ai-harness/tests/input-sender.test.ts
new file mode 100644
index 0000000000..9bf1f8986c
--- /dev/null
+++ b/packages/ai-harness/tests/input-sender.test.ts
@@ -0,0 +1,872 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { defineAgent, keyedAdapter, toolDefinition } from '@tanstack/ai'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  createHarnessHandler,
+  createHarnessHost,
+  defineCommand,
+  defineHarness,
+  definePlugin,
+} from '../src'
+import { credentialsFor } from '../src/auth'
+import { after, gate, mockAdapter, text, toolCall } from './helpers'
+import type { LogRecord } from '@tanstack/ai-persistence'
+import type {
+  HarnessPlugin,
+  HarnessRouterContext,
+  JoinCandidate,
+  Operation,
+  TurnInfo,
+} from '../src'
+
+const THREAD = 't1'
+const alice = { id: 'alice' }
+const bob = { id: 'bob' }
+
+/** A tool that keeps who runs it and the context it gets. */
+function whoami() {
+  const seen: Array<{ principal: string | undefined; context: unknown }> = []
+  const tool = toolDefinition({
+    name: 'whoami',
+    description: 'Who runs this?',
+    inputSchema: z.object({}),
+  })
+  const plugin = definePlugin({
+    name: 'test/whoami',
+    setup: (ctx) => ({
+      tools: [
+        tool.server((_input, toolContext) => {
+          seen.push({
+            principal: ctx.session.principal?.id,
+            context: toolContext?.context,
+          })
+          return Promise.resolve({})
+        }),
+      ],
+    }),
+  })
+  return { plugin, seen }
+}
+
+function durablePersistence() {
+  const { runs, metadata, credentials } = memoryPersistence().stores
+  return { stores: { log: memoryLogStore(), runs, metadata, credentials } }
+}
+
+/** An AG-UI `POST run` body with one user message. */
+const runBody = (content: string) => ({
+  threadId: THREAD,
+  runId: 'run-1',
+  messages: [{ id: 'm-1', role: 'user', content }],
+  tools: [],
+  context: [],
+})
+
+describe('the sender of each input', () => {
+  it("runs bob's prompt on alice's session as bob, and the log keeps bob", async () => {
+    const { plugin, seen } = whoami()
+    const { adapter } = mockAdapter([
+      () => toolCall('whoami', {}, 'c1'),
+      () => text('ok'),
+      () => toolCall('whoami', {}, 'c2'),
+      () => text('ok'),
+    ])
+    const persistence = durablePersistence()
+    const host = createHarnessHost({ persistence })
+    const harness = defineHarness({
+      name: 'test/sender',
+      adapter,
+      plugins: () => [plugin],
+    })
+    const session = await host.open(harness, {
+      threadId: THREAD,
+      principal: alice,
+    })
+    expect(await host.open(harness, { threadId: THREAD, principal: bob })).toBe(
+      session,
+    )
+
+    await session.prompt('Who am I?', { inputId: 'in-bob', principal: bob })
+    // Without a principal, the input is the opener's.
+    await session.prompt('And now?', { inputId: 'in-default' })
+
+    expect(seen.map((entry) => entry.principal)).toEqual(['bob', 'alice'])
+    const inputs = (await persistence.stores.log.read(THREAD))
+      .map((entry): LogRecord => entry.record)
+      .filter((record) => record.type === 'harness.input')
+      .map((record) => [record['inputId'], record['principal']])
+    expect(inputs).toEqual([
+      ['in-bob', { id: 'bob' }],
+      ['in-default', { id: 'alice' }],
+    ])
+    await host.close()
+  })
+
+  it('runs each request as the principal that authorize returned, never one from the body', async () => {
+    const { plugin, seen } = whoami()
+    const { adapter } = mockAdapter([
+      () => toolCall('whoami', {}, 'c1'),
+      () => text('ok'),
+      () => toolCall('whoami', {}, 'c2'),
+      () => text('ok'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const harness = defineHarness({
+      name: 'test/sender-http',
+      adapter,
+      plugins: () => [plugin],
+    })
+    const handler = createHarnessHandler({
+      host,
+      harness,
+      authorize: (request) => ({ id: request.headers.get('x-user') ?? '' }),
+    })
+    const post = (user: string, route: string, body: object) =>
+      handler(
+        new Request(`http://h.test/${route}`, {
+          method: 'POST',
+          headers: { 'x-user': user },
+          body: JSON.stringify(body),
+        }),
+      )
+
+    // Alice opens the thread.
+    await (await post('alice', 'run', runBody('Hi.'))).text()
+    const receipt = await (
+      await post('bob', 'control', {
+        threadId: THREAD,
+        input: { op: 'prompt', message: 'Me?', principal: { id: 'mallory' } },
+      })
+    ).json()
+    const session = await host.open(harness, { threadId: THREAD })
+    expect(await session.settled(receipt.inputId)).toMatchObject({
+      outcome: 'completed',
+    })
+
+    expect(seen.map((entry) => entry.principal)).toEqual(['alice', 'bob'])
+    await host.close()
+  })
+
+  it("builds the model call of bob's input with bob's key", async () => {
+    const keys: Array<string> = []
+    const adapter = keyedAdapter('acme', (key) => {
+      keys.push(key)
+      return mockAdapter([() => text(`answered with ${key}`)]).adapter
+    })
+    const persistence = memoryPersistence()
+    for (const user of ['alice', 'bob']) {
+      await persistence.stores.credentials.set(
+        { threadId: THREAD, userId: user },
+        'acme',
+        { type: 'api_key', value: `${user}-key` },
+      )
+    }
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({ name: 'test/sender-keys', adapter }),
+      { threadId: THREAD, principal: alice },
+    )
+
+    expect((await session.prompt('Hi.', { principal: bob })).text).toBe(
+      'answered with bob-key',
+    )
+    expect((await session.prompt('Hi.')).text).toBe('answered with alice-key')
+    expect(keys).toEqual(['bob-key', 'alice-key'])
+    await host.close()
+  })
+
+  it('gives canJoin the sender, and a refused steer runs as its own turn for its sender', async () => {
+    const { plugin, seen } = whoami()
+    const release = gate()
+    const { adapter } = mockAdapter([
+      after(release.opened, 'first'),
+      () => toolCall('whoami', {}, 'c1'),
+      () => text('second'),
+    ])
+    const candidates: Array<JoinCandidate> = []
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/sender-join',
+        adapter,
+        plugins: () => [plugin],
+        turn: {
+          canJoin: (candidate) => {
+            candidates.push(candidate)
+            return candidate.principal?.id === alice.id
+          },
+        },
+      }),
+      { threadId: THREAD, principal: alice },
+    )
+
+    const turn = session.prompt('Start.')
+    await turn.receipt
+    await session.steer('Mine.', { inputId: 'in-bob', principal: bob })
+    release.open()
+
+    expect(await turn).toEqual({ text: 'first' })
+    expect(await session.settled('in-bob')).toMatchObject({
+      outcome: 'completed',
+    })
+    expect(candidates.length).toBeGreaterThan(0)
+    expect(candidates.every((candidate) => candidate.principal === bob)).toBe(
+      true,
+    )
+    expect(seen.map((entry) => entry.principal)).toEqual(['bob'])
+    await host.close()
+  })
+
+  it("keeps bob's message out of alice's turn with turnPrincipal, and alice's own steer joins", async () => {
+    const { plugin, seen } = whoami()
+    const started = gate()
+    const release = gate()
+    const { adapter } = mockAdapter([
+      // The steers wait until alice's turn is in its first model call.
+      (request) => (started.open(), after(release.opened, 'First.')(request)),
+      () => text('Joined.'),
+      () => toolCall('whoami', {}, 'c1'),
+      () => text('Bob here.'),
+    ])
+    const candidates: Array<JoinCandidate> = []
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/sender-turn-principal',
+        adapter,
+        plugins: () => [plugin],
+        turn: {
+          canJoin: (candidate) => {
+            candidates.push(candidate)
+            return candidate.principal?.id === candidate.turnPrincipal?.id
+          },
+        },
+      }),
+      { threadId: THREAD, principal: alice },
+    )
+
+    const turn = session.prompt('Start.')
+    await started.opened
+    await session.steer('Also this.', { inputId: 'in-alice' })
+    const bobs = session.prompt('Mine.', {
+      busy: 'steer',
+      inputId: 'in-bob',
+      principal: bob,
+    })
+    await bobs.receipt
+    release.open()
+
+    expect(await turn).toEqual({ text: 'First.Joined.' })
+    expect(await session.settled('in-alice')).toMatchObject({
+      operationId: turn.id,
+    })
+    expect(await bobs).toEqual({ text: 'Bob here.' })
+    const bobSettled = await session.settled('in-bob')
+    expect(bobSettled).toMatchObject({ outcome: 'completed' })
+    expect(bobSettled.operationId).not.toBe(turn.id)
+    expect(seen.map((entry) => entry.principal)).toEqual(['bob'])
+    expect(candidates).toContainEqual(
+      expect.objectContaining({ principal: bob, turnPrincipal: alice }),
+    )
+    await host.close()
+  })
+
+  it("keeps another person's steer out of a running turn without canJoin, and runs it as its own turn", async () => {
+    const { plugin, seen } = whoami()
+    const started = gate()
+    const release = gate()
+    const { adapter } = mockAdapter([
+      (request) => (started.open(), after(release.opened, 'First.')(request)),
+      () => text('Joined.'),
+      () => toolCall('whoami', {}, 'c1'),
+      () => text('Bob here.'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/sender-default-join',
+        adapter,
+        plugins: () => [plugin],
+      }),
+      { threadId: THREAD, principal: alice },
+    )
+
+    const turn = session.prompt('Start.')
+    await started.opened
+    await session.steer('Also this.', { inputId: 'in-alice' })
+    const bobs = session.prompt('Mine.', {
+      busy: 'steer',
+      inputId: 'in-bob',
+      principal: bob,
+    })
+    await bobs.receipt
+    release.open()
+
+    expect(await turn).toEqual({ text: 'First.Joined.' })
+    expect(await session.settled('in-alice')).toMatchObject({
+      operationId: turn.id,
+    })
+    expect(await bobs).toEqual({ text: 'Bob here.' })
+    expect((await session.settled('in-bob')).operationId).not.toBe(turn.id)
+    expect(seen.map((entry) => entry.principal)).toEqual(['bob'])
+    await host.close()
+  })
+
+  it("binds a command's session to the person who runs it", async () => {
+    const { plugin, seen } = whoami()
+    const started = gate()
+    const release = gate()
+    const { adapter } = mockAdapter([
+      (request) => (started.open(), after(release.opened, 'First.')(request)),
+      () => toolCall('whoami', {}, 'c1'),
+      () => text('Again.'),
+    ])
+    const commandSaw: Array<string | undefined> = []
+    let again: Operation<unknown> | undefined
+    const commands = definePlugin({
+      name: 'test/commands',
+      setup: () => ({
+        commands: {
+          again: defineCommand({
+            description: 'Ask again',
+            run: (_input, { session }) => {
+              commandSaw.push(session.principal?.id)
+              again = session.prompt('Again.')
+              return 'ok'
+            },
+          }),
+        },
+      }),
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/sender-command',
+        adapter,
+        plugins: () => [plugin, commands],
+      }),
+      { threadId: THREAD, principal: alice },
+    )
+
+    const turn = session.prompt('Start.')
+    await started.opened
+    // Bob runs a command while alice's turn runs.
+    await session.command('again', undefined, { principal: bob })
+    release.open()
+
+    expect(await turn).toEqual({ text: 'First.' })
+    expect(commandSaw).toEqual(['bob'])
+    expect(await again).toEqual({ text: 'Again.' })
+    expect(seen.map((entry) => entry.principal)).toEqual(['bob'])
+    await host.close()
+  })
+
+  it('runs the wake turn of a background agent as the person who started it', async () => {
+    const { plugin, seen } = whoami()
+    const writer = defineAgent({
+      name: 'writer',
+      description: 'Writes',
+      run: () => Promise.resolve('drafted'),
+    })
+    const startWriter = toolDefinition({
+      name: 'startWriter',
+      description: 'Start the writer',
+      inputSchema: z.object({}),
+    })
+    const starter = definePlugin({
+      name: 'test/starter',
+      setup: (ctx) => ({
+        tools: [
+          startWriter.server(() => {
+            ctx.agents.start(writer, undefined, { wake: true })
+            return Promise.resolve({})
+          }),
+        ],
+      }),
+    })
+    const { adapter } = mockAdapter([
+      () => toolCall('startWriter', {}, 'c1'),
+      () => text('started'),
+      // The wake turn.
+      () => toolCall('whoami', {}, 'c2'),
+      () => text('woke'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/sender-wake',
+        adapter,
+        plugins: () => [plugin, starter],
+      }),
+      { threadId: THREAD, principal: alice },
+    )
+
+    await session.prompt('Start the writer.', { principal: bob })
+    await vi.waitFor(() => expect(seen).toHaveLength(1))
+    expect(seen.map((entry) => entry.principal)).toEqual(['bob'])
+    await host.close()
+  })
+
+  it("runs a background agent that bob's turn starts with bob's key, after that turn ends", async () => {
+    const release = gate()
+    const keys: Array<string> = []
+    const keyed = keyedAdapter('acme', (key) => {
+      keys.push(key)
+      return mockAdapter([() => text('drafted')]).adapter
+    })
+    const writer = defineAgent({
+      name: 'writer',
+      description: 'Writes',
+      run: async (ctx) => {
+        await release.opened
+        return ctx.chat({
+          adapter: await ctx.keys.adapter(keyed),
+          stream: false,
+        })
+      },
+    })
+    let started: Operation<unknown> | undefined
+    const startWriter = toolDefinition({
+      name: 'startWriter',
+      description: 'Start the writer',
+      inputSchema: z.object({}),
+    })
+    const starter = definePlugin({
+      name: 'test/starter',
+      setup: (ctx) => ({
+        tools: [
+          startWriter.server(() => {
+            started = ctx.agents.start(writer)
+            return Promise.resolve({})
+          }),
+        ],
+      }),
+    })
+    const persistence = memoryPersistence()
+    for (const user of ['alice', 'bob']) {
+      await persistence.stores.credentials.set(
+        { threadId: THREAD, userId: user },
+        'acme',
+        { type: 'api_key', value: `${user}-key` },
+      )
+    }
+    const { adapter } = mockAdapter([
+      () => toolCall('startWriter', {}, 'c1'),
+      () => text('started'),
+    ])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/sender-agent',
+        adapter,
+        plugins: () => [starter],
+      }),
+      { threadId: THREAD, principal: alice },
+    )
+
+    await session.prompt('Start the writer.', { principal: bob })
+    release.open()
+
+    expect(await started).toBe('drafted')
+    expect(keys).toEqual(['bob-key'])
+    await host.close()
+  })
+})
+
+describe('the context of an input', () => {
+  it('gives tools the forwardedProps of POST run under the harness context, and stores them with the input', async () => {
+    const { plugin, seen } = whoami()
+    const { adapter } = mockAdapter([
+      () => toolCall('whoami', {}, 'c1'),
+      () => text('ok'),
+    ])
+    const persistence = memoryPersistence()
+    const host = createHarnessHost({ persistence })
+    const handler = createHarnessHandler({
+      host,
+      harness: defineHarness({
+        name: 'test/context',
+        adapter,
+        plugins: () => [plugin],
+        context: { tenant: 'server', db: 'main' },
+      }),
+      authorize: () => alice,
+    })
+
+    const response = await handler(
+      new Request('http://h.test/run', {
+        method: 'POST',
+        body: JSON.stringify({
+          ...runBody('Go.'),
+          forwardedProps: { tenant: 'acme', screen: 'settings' },
+        }),
+      }),
+    )
+    const body = await response.text()
+
+    // The harness value wins for `tenant`.
+    expect(seen).toEqual([
+      {
+        principal: 'alice',
+        context: { tenant: 'server', db: 'main', screen: 'settings' },
+      },
+    ])
+    const inputId =
+      /"name":"harness\.input\.applied","value":\{"inputId":"([^"]+)"/.exec(
+        body,
+      )?.[1]
+    const stored = await persistence.stores.inbox.get(inputId ?? '')
+    expect(stored).toMatchObject({
+      input: {
+        op: 'prompt',
+        message: 'Go.',
+        busy: 'queue',
+        context: { tenant: 'acme', screen: 'settings' },
+      },
+      principal: { id: 'alice' },
+    })
+    await host.close()
+  })
+
+  it('gives tools the context of a control input when the harness has none', async () => {
+    const { plugin, seen } = whoami()
+    const { adapter } = mockAdapter([
+      () => toolCall('whoami', {}, 'c1'),
+      () => text('ok'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const harness = defineHarness({
+      name: 'test/context-control',
+      adapter,
+      plugins: () => [plugin],
+    })
+    const handler = createHarnessHandler({
+      host,
+      harness,
+      authorize: () => alice,
+    })
+
+    const receipt = await (
+      await handler(
+        new Request('http://h.test/control', {
+          method: 'POST',
+          body: JSON.stringify({
+            threadId: THREAD,
+            input: {
+              op: 'prompt',
+              message: 'Go.',
+              context: { screen: 'home' },
+            },
+          }),
+        }),
+      )
+    ).json()
+    const session = await host.open(harness, { threadId: THREAD })
+    await session.settled(receipt.inputId)
+
+    expect(seen).toEqual([{ principal: 'alice', context: { screen: 'home' } }])
+    await host.close()
+  })
+})
+
+describe('recovery keeps the sender and the context', () => {
+  /** A run plugin that keeps the turn it is set up for, and a tool that reports. */
+  function recorder() {
+    const turns: Array<TurnInfo | undefined> = []
+    const { plugin, seen } = whoami()
+    const run = definePlugin({
+      name: 'test/turns',
+      lifetime: 'run',
+      setup: (ctx) => {
+        turns.push(ctx.turn)
+      },
+    })
+    return { plugins: (): Array<HarnessPlugin> => [plugin, run], turns, seen }
+  }
+
+  const sent = {
+    op: 'prompt',
+    message: 'go',
+    busy: 'queue',
+    context: { screen: 'x' },
+  }
+
+  it('runs an input that never ran with its sender and context', async () => {
+    const persistence = durablePersistence()
+    await persistence.stores.log.append(THREAD, 1, [
+      {
+        type: 'harness.input',
+        inputId: 'in-1',
+        input: sent,
+        principal: { id: 'bob', tenantId: 'org' },
+        at: 1,
+      },
+    ])
+    const { plugins, turns, seen } = recorder()
+    const { adapter } = mockAdapter([
+      () => toolCall('whoami', {}, 'c1'),
+      () => text('ok'),
+    ])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({ name: 'test/recover-pending', adapter, plugins }),
+      { threadId: THREAD, principal: alice },
+    )
+
+    expect(await session.settled('in-1')).toMatchObject({
+      outcome: 'completed',
+    })
+    expect(turns).toEqual([
+      expect.objectContaining({
+        inputId: 'in-1',
+        message: 'go',
+        context: { screen: 'x' },
+        principal: { id: 'bob', tenantId: 'org' },
+      }),
+    ])
+    expect(seen).toEqual([{ principal: 'bob', context: { screen: 'x' } }])
+    await host.close()
+  })
+
+  it('runs a turn whose host stopped again with its message, sender, and context', async () => {
+    const persistence = durablePersistence()
+    await persistence.stores.log.append(THREAD, 1, [
+      {
+        type: 'harness.input',
+        inputId: 'in-1',
+        input: sent,
+        principal: { id: 'bob' },
+        at: 1,
+      },
+      {
+        type: 'harness.input.applied',
+        inputId: 'in-1',
+        operationId: 'op-stopped',
+        attempt: 1,
+      },
+      {
+        type: 'harness.transcript',
+        keep: 0,
+        add: [{ id: 'u1', role: 'user', content: 'go' }],
+      },
+    ])
+    await persistence.stores.runs.createOrResume({
+      runId: 'op-stopped',
+      threadId: THREAD,
+      startedAt: Date.now() - 60_000,
+    })
+    await persistence.stores.runs.update('op-stopped', {
+      leaseOwner: 'host-gone',
+      leaseExpiresAt: Date.now() - 1_000,
+      checkpoint: { at: 1, pendingTools: [] },
+    })
+    const { plugins, turns, seen } = recorder()
+    const { adapter } = mockAdapter([
+      () => toolCall('whoami', {}, 'c1'),
+      () => text('ok'),
+    ])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({ name: 'test/recover-stopped', adapter, plugins }),
+      { threadId: THREAD, principal: alice },
+    )
+
+    expect(await session.settled('in-1')).toMatchObject({
+      outcome: 'completed',
+    })
+    expect(turns).toEqual([
+      expect.objectContaining({
+        inputId: 'in-1',
+        message: 'go',
+        context: { screen: 'x' },
+        principal: { id: 'bob' },
+      }),
+    ])
+    expect(seen).toEqual([{ principal: 'bob', context: { screen: 'x' } }])
+    await host.close()
+  })
+})
+
+describe('the turn where the model is picked', () => {
+  it('gives run plugins and adapter() the message, the context, and the sender', async () => {
+    const setups: Array<TurnInfo | undefined> = []
+    const picks: Array<TurnInfo> = []
+    const runPicker = definePlugin({
+      name: 'test/run-picker',
+      lifetime: 'run',
+      setup: (ctx) => {
+        setups.push(ctx.turn)
+        return {
+          adapter: (turn) => {
+            picks.push(turn)
+            return undefined
+          },
+        }
+      },
+    })
+    const sessionTurns: Array<TurnInfo | undefined> = []
+    const sessionPlugin = definePlugin({
+      name: 'test/session-plugin',
+      setup: (ctx) => {
+        sessionTurns.push(ctx.turn)
+      },
+    })
+    const { adapter } = mockAdapter([() => text('ok')])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/picker-turn',
+        adapter,
+        plugins: () => [sessionPlugin, runPicker],
+      }),
+      { threadId: THREAD, principal: alice },
+    )
+
+    const turn = session.prompt('Pick for me.', {
+      inputId: 'in-1',
+      principal: bob,
+      context: { plan: 'pro' },
+    })
+    await turn
+
+    const expected = {
+      operationId: turn.id,
+      inputId: 'in-1',
+      message: 'Pick for me.',
+      context: { plan: 'pro' },
+      principal: bob,
+    }
+    expect(setups).toEqual([expected])
+    expect(picks).toEqual([expected])
+    expect(sessionTurns).toEqual([undefined])
+    await host.close()
+  })
+
+  it('gives the router the sender and the context', async () => {
+    const seen: Array<HarnessRouterContext> = []
+    const helper = defineAgent({
+      name: 'helper',
+      description: 'Helps',
+      run: () => Promise.resolve('help'),
+    })
+    const { adapter } = mockAdapter([() => text('ok')])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/router-turn',
+        adapter,
+        agents: [helper],
+        routing: {
+          router: (ctx) => {
+            seen.push(ctx)
+            return 'main'
+          },
+        },
+      }),
+      { threadId: THREAD, principal: alice },
+    )
+
+    await session.prompt('Route me.', {
+      principal: bob,
+      context: { plan: 'pro' },
+    })
+
+    expect(seen).toEqual([
+      expect.objectContaining({
+        input: 'Route me.',
+        principal: bob,
+        context: { plan: 'pro' },
+      }),
+    ])
+    await host.close()
+  })
+})
+
+describe('the tenant of a principal', () => {
+  it('scopes credentials by user and tenant', async () => {
+    const seen: Array<unknown> = []
+    const read = toolDefinition({
+      name: 'readToken',
+      description: 'Read the GitHub token',
+      inputSchema: z.object({}),
+    })
+    const plugin = definePlugin({
+      name: 'test/token',
+      setup: (ctx) => ({
+        tools: [
+          read.server(async () => {
+            const credential = await ctx.credentials.get('github')
+            seen.push(credential?.type === 'api_key' ? credential.value : null)
+            return {}
+          }),
+        ],
+      }),
+    })
+    const persistence = memoryPersistence()
+    for (const tenantId of ['org-a', 'org-b']) {
+      await persistence.stores.credentials.set(
+        { threadId: THREAD, userId: 'u1', tenantId },
+        'github',
+        { type: 'api_key', value: `${tenantId}-token` },
+      )
+    }
+    const { adapter } = mockAdapter([
+      () => toolCall('readToken', {}, 'c1'),
+      () => text('ok'),
+      () => toolCall('readToken', {}, 'c2'),
+      () => text('ok'),
+    ])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({ name: 'test/tenant', adapter, plugins: () => [plugin] }),
+      { threadId: THREAD, principal: { id: 'u1', tenantId: 'org-a' } },
+    )
+
+    await session.prompt('Read it.')
+    await session.prompt('Read it again.', {
+      principal: { id: 'u1', tenantId: 'org-b' },
+    })
+
+    expect(seen).toEqual(['org-a-token', 'org-b-token'])
+    await host.close()
+  })
+
+  it("reads the tenant's credential when the user has none, and the user's own first", async () => {
+    const store = memoryPersistence().stores.credentials
+    // Saved without a userId: it belongs to the whole tenant.
+    await store.set({ threadId: THREAD, tenantId: 'org-a' }, 'github', {
+      type: 'api_key',
+      value: 'org-token',
+    })
+    await store.set({ threadId: THREAD, tenantId: 'org-a' }, 'notion', {
+      type: 'api_key',
+      value: 'org-notion',
+    })
+    const access = (userId: string, tenantId: string) =>
+      credentialsFor(store, { threadId: THREAD, userId, tenantId }, () => {})
+
+    const ada = access('ada', 'org-a')
+    expect(await ada.require('github')).toEqual({
+      type: 'api_key',
+      value: 'org-token',
+    })
+    // A user of another tenant does not see it.
+    expect(await access('ada', 'org-b').get('github')).toBeNull()
+
+    // The user's own credential wins, and a save goes to the user only.
+    await ada.set('github', { type: 'api_key', value: 'ada-token' })
+    expect(await ada.get('github')).toEqual({
+      type: 'api_key',
+      value: 'ada-token',
+    })
+    expect(await access('bob', 'org-a').get('github')).toEqual({
+      type: 'api_key',
+      value: 'org-token',
+    })
+    expect(await ada.list()).toEqual([
+      { id: 'github', type: 'api_key' },
+      { id: 'notion', type: 'api_key' },
+    ])
+  })
+})
diff --git a/packages/ai-harness/tests/interrupt-resolve.test.ts b/packages/ai-harness/tests/interrupt-resolve.test.ts
new file mode 100644
index 0000000000..7bebf7a24d
--- /dev/null
+++ b/packages/ai-harness/tests/interrupt-resolve.test.ts
@@ -0,0 +1,358 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { EventType, toolDefinition } from '@tanstack/ai'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness, definePlugin } from '../src'
+import {
+  after,
+  gate,
+  messageTexts,
+  mockAdapter,
+  text,
+  toolCall,
+} from './helpers'
+import type { StreamChunk } from '@tanstack/ai'
+import type { Reply } from './helpers'
+
+/** A client tool: the harness has no implementation, the client sends the result. */
+const openScreen = toolDefinition({
+  name: 'openScreen',
+  description: 'Open a screen in the browser. Runs on the client.',
+  inputSchema: z.object({ route: z.string() }),
+  outputSchema: z.object({ opened: z.boolean() }),
+})
+
+/** A model call that fails after it started. */
+const fails: Reply = () =>
+  (async function* (): AsyncGenerator<StreamChunk> {
+    yield {
+      type: EventType.RUN_STARTED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: Date.now(),
+    }
+    throw new Error('model down')
+  })()
+
+/** The stores of a host without a log, or of a durable host. */
+function persistenceFor(durable: boolean) {
+  const { stores } = memoryPersistence()
+  if (!durable) return { stores }
+  const { runs, metadata } = stores
+  return { stores: { log: memoryLogStore(), runs, metadata } }
+}
+
+describe.each([
+  { host: 'a host without a log', durable: false },
+  { host: 'a durable host', durable: true },
+])('resolve on $host', ({ durable }) => {
+  it('keeps the interrupt when the resume fails validation, so a correct resolve continues the turn', async () => {
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('openScreen', { route: '/settings' }),
+      () => text('Opened it.'),
+    ])
+    const host = createHarnessHost({ persistence: persistenceFor(durable) })
+    const session = await host.open(
+      defineHarness({ name: 'test/bad-resume', adapter, tools: [openScreen] }),
+      { threadId: 't1' },
+    )
+    const turn = await session.prompt('Open settings.')
+    const interruptId = turn.interrupts?.[0]?.id
+    if (!interruptId) throw new Error('The turn did not stop for the tool.')
+
+    // A client tool needs a result, not `true`.
+    await session.resolve(
+      [{ interruptId, status: 'resolved', payload: true }],
+      {
+        inputId: 'wrong',
+      },
+    )
+    expect(await session.settled('wrong')).toMatchObject({ outcome: 'failed' })
+    expect(session.snapshot()).toMatchObject({
+      status: 'requires_action',
+      pendingInterrupts: [{ id: interruptId }],
+    })
+
+    const right = await session.resolve(
+      [{ interruptId, status: 'resolved', payload: { opened: true } }],
+      { inputId: 'right' },
+    )
+    expect(right.status).toBe('accepted')
+    expect(await session.settled('right')).toMatchObject({
+      outcome: 'completed',
+    })
+    expect(calls).toHaveLength(2)
+    expect(session.snapshot().pendingInterrupts).toEqual([])
+    await host.close()
+  })
+
+  it("gives the turn after a resolve the input's context, also after a restart", async () => {
+    const seen: Array<unknown> = []
+    const probe = toolDefinition({
+      name: 'probe',
+      description: 'Probe. Needs approval.',
+      needsApproval: true,
+      inputSchema: z.object({}),
+    }).server((_input, toolContext) => {
+      seen.push(toolContext?.context)
+      return Promise.resolve({ ok: true })
+    })
+    const persistence = persistenceFor(durable)
+    const open = (replies: Array<Reply>) => {
+      const host = createHarnessHost({ persistence })
+      const harness = defineHarness({
+        name: 'test/resume-context',
+        adapter: mockAdapter(replies).adapter,
+        tools: [probe],
+      })
+      return { host, session: host.open(harness, { threadId: 't1' }) }
+    }
+
+    const first = open([() => toolCall('probe', {})])
+    const turn = await (
+      await first.session
+    ).prompt('Probe.', { context: { screen: 'settings' } })
+    const interruptId = turn.interrupts?.[0]?.id
+    if (!interruptId) throw new Error('The turn did not stop for the approval.')
+    await first.host.close()
+
+    const second = open([() => text('Done.')])
+    const session = await second.session
+    await session.resolve(
+      [{ interruptId, status: 'resolved', payload: true }],
+      { inputId: 'approve' },
+    )
+    expect(await session.settled('approve')).toMatchObject({
+      outcome: 'completed',
+    })
+    expect(seen).toEqual([{ screen: 'settings' }])
+    await second.host.close()
+  })
+
+  it('does not bring the interrupt back when the turn fails after the resume ran', async () => {
+    const execute = vi.fn(async () => ({ ok: true }))
+    const deploy = toolDefinition({
+      name: 'deploy',
+      description: 'Deploy. Needs approval.',
+      needsApproval: true,
+      inputSchema: z.object({ env: z.string() }),
+    }).server(execute)
+    const { adapter } = mockAdapter([
+      () => toolCall('deploy', { env: 'prod' }),
+      fails,
+    ])
+    const host = createHarnessHost({ persistence: persistenceFor(durable) })
+    const session = await host.open(
+      defineHarness({ name: 'test/late-failure', adapter, tools: [deploy] }),
+      { threadId: 't1' },
+    )
+    const turn = await session.prompt('Deploy.')
+    const interruptId = turn.interrupts?.[0]?.id
+    if (!interruptId) throw new Error('The turn did not stop for approval.')
+
+    await session.resolve(
+      [{ interruptId, status: 'resolved', payload: true }],
+      {
+        inputId: 'approve',
+      },
+    )
+    expect(await session.settled('approve')).toMatchObject({
+      outcome: 'failed',
+    })
+    expect(execute).toHaveBeenCalledTimes(1)
+    expect(session.snapshot().pendingInterrupts).toEqual([])
+    expect(
+      await session.resolve([
+        { interruptId, status: 'resolved', payload: true },
+      ]),
+    ).toMatchObject({ status: 'rejected', reason: 'no_pending_interrupts' })
+    await host.close()
+  })
+
+  it('accepts a resolve sent on RUN_FINISHED, while the interrupted turn still ends', async () => {
+    const execute = vi.fn(async () => ({ ok: true }))
+    const deploy = toolDefinition({
+      name: 'deploy',
+      description: 'Deploy. Needs approval.',
+      needsApproval: true,
+      inputSchema: z.object({ env: z.string() }),
+    }).server(execute)
+    // A run plugin whose cleanup waits, so the turn is still active after RUN_FINISHED.
+    const cleanup = gate()
+    const release = gate()
+    const slowCleanup = definePlugin({
+      name: 'test/slow-cleanup',
+      lifetime: 'turn',
+      setup: async (ctx) => {
+        await ctx.resources.acquire(
+          () => undefined,
+          async () => {
+            cleanup.open()
+            await release.opened
+          },
+        )
+      },
+    })
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('deploy', { env: 'prod' }),
+      () => text('Deployed.'),
+    ])
+    const host = createHarnessHost({ persistence: persistenceFor(durable) })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/resolve-on-finished',
+        adapter,
+        tools: [deploy],
+        plugins: () => [slowCleanup],
+      }),
+      { threadId: 't1' },
+    )
+
+    const turn = session.prompt('Deploy.')
+    let interruptId = ''
+    for await (const { operationId, event } of session.events()) {
+      if (operationId !== turn.id) continue
+      if (
+        event.type === EventType.RUN_FINISHED &&
+        event.outcome?.type === 'interrupt'
+      ) {
+        interruptId = event.outcome.interrupts[0]?.id ?? ''
+        break
+      }
+    }
+    await cleanup.opened
+    expect(session.snapshot().pendingInterrupts).toMatchObject([
+      { id: interruptId },
+    ])
+    const receipt = await session.resolve(
+      [{ interruptId, status: 'resolved', payload: true }],
+      { inputId: 'approve' },
+    )
+    expect(receipt.status).toBe('accepted')
+    release.open()
+
+    expect((await turn).interrupts).toHaveLength(1)
+    expect(await session.settled('approve')).toMatchObject({
+      outcome: 'completed',
+      operationId: receipt.operationId,
+    })
+    expect(execute).toHaveBeenCalledTimes(1)
+    expect(calls).toHaveLength(2)
+    expect(session.snapshot()).toMatchObject({
+      status: 'idle',
+      pendingInterrupts: [],
+    })
+    await host.close()
+  })
+})
+
+describe('a resolve and a waiting steer', () => {
+  it('runs the resolve before a steer that the interrupted turn never reached', async () => {
+    const execute = vi.fn(async () => ({ ok: true }))
+    const deploy = toolDefinition({
+      name: 'deploy',
+      description: 'Deploy. Needs approval.',
+      needsApproval: true,
+      inputSchema: z.object({ env: z.string() }),
+    }).server(execute)
+    const held = gate()
+    const cleanup = gate()
+    const release = gate()
+    const slowCleanup = definePlugin({
+      name: 'test/slow-cleanup',
+      lifetime: 'turn',
+      setup: async (ctx) => {
+        await ctx.resources.acquire(
+          () => undefined,
+          async () => {
+            cleanup.open()
+            await release.opened
+          },
+        )
+      },
+    })
+    const { adapter, calls } = mockAdapter([
+      () =>
+        (async function* () {
+          await held.opened
+          yield* toolCall('deploy', { env: 'prod' })
+        })(),
+      () => text('Deployed.'),
+      () => text('Steered.'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/resolve-before-steer',
+        adapter,
+        tools: [deploy],
+        plugins: () => [slowCleanup],
+      }),
+      { threadId: 't1' },
+    )
+
+    const turn = session.prompt('Deploy.')
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    const steer = session.prompt('And tell me.', {
+      busy: 'steer',
+      inputId: 'steer',
+    })
+    await steer.receipt
+    held.open()
+    await cleanup.opened
+    const interruptId = session.snapshot().pendingInterrupts[0]?.id ?? ''
+    await session.resolve(
+      [{ interruptId, status: 'resolved', payload: true }],
+      { inputId: 'approve' },
+    )
+    release.open()
+
+    await turn
+    expect(await session.settled('approve')).toMatchObject({
+      outcome: 'completed',
+    })
+    expect(await steer).toEqual({ text: 'Steered.' })
+    expect(execute).toHaveBeenCalledTimes(1)
+    expect(messageTexts(calls[2]).at(-1)).toBe('And tell me.')
+    await host.close()
+  })
+})
+
+describe("prompt({ busy: 'steer' })", () => {
+  it('answers with the running turn, which the prompt joins', async () => {
+    const first = gate()
+    const { adapter, calls } = mockAdapter([
+      after(first.opened, 'First.'),
+      () => text('Second.'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({ name: 'test/steer-receipt', adapter }),
+      { threadId: 't1' },
+    )
+
+    const turn = session.prompt('Start.')
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    const joined = session.prompt('Steer by prompt.', {
+      busy: 'steer',
+      inputId: 'by-prompt',
+    })
+    const receipt = await joined.receipt
+    expect(receipt).toEqual({
+      inputId: 'by-prompt',
+      status: 'accepted',
+      operationId: turn.id,
+    })
+    expect(session.operation(turn.id)).toBe(turn)
+    first.open()
+
+    const result = await turn
+    expect(result.text).toBe('First.Second.')
+    expect(await joined).toEqual(result)
+    expect(await session.settled('by-prompt')).toMatchObject({
+      outcome: 'completed',
+      operationId: turn.id,
+    })
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/plugin-subagents.test.ts b/packages/ai-harness/tests/plugin-subagents.test.ts
index 2e50f2750d..61479fc4f4 100644
--- a/packages/ai-harness/tests/plugin-subagents.test.ts
+++ b/packages/ai-harness/tests/plugin-subagents.test.ts
@@ -25,7 +25,7 @@ describe('plugin subagents', () => {
     })
     const fromRun = definePlugin({
       name: 'test/run-agents',
-      lifetime: 'run',
+      lifetime: 'turn',
       setup: () => ({ subagents: [agentNamed('writer', 'wrote')] }),
     })
     const { adapter, calls } = mockAdapter([
diff --git a/packages/ai-harness/tests/routing.test.ts b/packages/ai-harness/tests/routing.test.ts
index 7958a8e709..5ad441c3c8 100644
--- a/packages/ai-harness/tests/routing.test.ts
+++ b/packages/ai-harness/tests/routing.test.ts
@@ -243,7 +243,7 @@ describe('routing.router', () => {
         }),
         definePlugin({
           name: 'test/run-agents',
-          lifetime: 'run',
+          lifetime: 'turn',
           setup: () => ({ agents: [seo.agent] }),
         }),
       ],
@@ -513,7 +513,7 @@ describe('routing.router', () => {
       plugins: () => [
         definePlugin({
           name: 'test/run-cleaner',
-          lifetime: 'run',
+          lifetime: 'turn',
           // A new agent object on each mount, with the same name.
           setup: () => ({ agents: [make()] }),
         }),
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..7c88b38fc6
--- /dev/null
+++ b/packages/ai-harness/tests/run-route.test.ts
@@ -0,0 +1,613 @@
+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,
+  persistence = memoryPersistence(),
+) {
+  const host = createHarnessHost({ persistence })
+  const handler = createHarnessHandler({
+    host,
+    harness,
+    authorize: () => ({ id: 'user-1' }),
+    ...(canAccess ? { 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 }),
+      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/session.test.ts b/packages/ai-harness/tests/session.test.ts
index 1425dce9a9..c3ba5d68a8 100644
--- a/packages/ai-harness/tests/session.test.ts
+++ b/packages/ai-harness/tests/session.test.ts
@@ -413,52 +413,98 @@ describe('inbox', () => {
 })
 
 describe('plugins', () => {
-  it('keeps session plugins across turns and sets up run plugins per turn', async () => {
+  // 'run' is the old name of 'turn', and still works.
+  it.each(['turn', 'run'] as const)(
+    'keeps session plugins across turns and sets up %s plugins per turn',
+    async (lifetime) => {
+      const { host } = setup()
+      const log: Array<string> = []
+      const sessionPlugin = definePlugin({
+        name: 'test/session',
+        setup: async ({ resources }) => {
+          await resources.acquire(
+            () => log.push('session:open'),
+            () => log.push('session:close'),
+          )
+          return { prompts: ['Session prompt.'] }
+        },
+      })
+      const runPlugin = definePlugin({
+        name: 'test/run',
+        lifetime,
+        setup: async ({ resources }) => {
+          await resources.acquire(
+            () => log.push('run:open'),
+            () => log.push('run:close'),
+          )
+        },
+      })
+      const { adapter, calls } = mockAdapter([() => text('a'), () => text('b')])
+      const session = await host.open(
+        defineHarness({
+          name: 'test/plugins',
+          adapter,
+          plugins: () => [sessionPlugin, runPlugin],
+        }),
+        { threadId: 't1' },
+      )
+
+      await session.prompt('one')
+      await session.prompt('two')
+      await session.close()
+
+      expect(log).toEqual([
+        'session:open',
+        'run:open',
+        'run:close',
+        'run:open',
+        'run:close',
+        'session:close',
+      ])
+      expect(JSON.stringify(calls[0].systemPrompts)).toContain(
+        'Session prompt.',
+      )
+    },
+  )
+
+  it('runs a harness without an adapter on the model a plugin picks', async () => {
     const { host } = setup()
-    const log: Array<string> = []
-    const sessionPlugin = definePlugin({
-      name: 'test/session',
-      setup: async ({ resources }) => {
-        await resources.acquire(
-          () => log.push('session:open'),
-          () => log.push('session:close'),
-        )
-        return { prompts: ['Session prompt.'] }
-      },
-    })
-    const runPlugin = definePlugin({
-      name: 'test/run',
-      lifetime: 'run',
-      setup: async ({ resources }) => {
-        await resources.acquire(
-          () => log.push('run:open'),
-          () => log.push('run:close'),
-        )
-      },
+    const { adapter, calls } = mockAdapter([() => text('picked')])
+    const picker = definePlugin({
+      name: 'test/picker',
+      setup: () => ({ adapter: () => adapter }),
     })
-    const { adapter, calls } = mockAdapter([() => text('a'), () => text('b')])
     const session = await host.open(
-      defineHarness({
-        name: 'test/plugins',
-        adapter,
-        plugins: () => [sessionPlugin, runPlugin],
-      }),
+      defineHarness({ name: 'test/no-adapter', plugins: () => [picker] }),
       { threadId: 't1' },
     )
 
-    await session.prompt('one')
-    await session.prompt('two')
-    await session.close()
+    expect((await session.prompt('hi')).text).toBe('picked')
+    expect(calls).toHaveLength(1)
+    await host.close()
+  })
 
-    expect(log).toEqual([
-      'session:open',
-      'run:open',
-      'run:close',
-      'run:open',
-      'run:close',
-      'session:close',
-    ])
-    expect(JSON.stringify(calls[0].systemPrompts)).toContain('Session prompt.')
+  it('fails the turn when nothing gives it a model', async () => {
+    const { host } = setup()
+    const session = await host.open(defineHarness({ name: 'test/no-model' }), {
+      threadId: 't1',
+    })
+
+    const turn = session.prompt('hi', { inputId: 'in-1' })
+    const chunks: Array<StreamChunk> = []
+    for await (const chunk of turn.stream()) chunks.push(chunk)
+
+    const message =
+      'This turn has no model. Set `adapter` in defineHarness, return one from a plugin `adapter()`, or pass `overrides.adapter` to the turn.'
+    await expect(turn).rejects.toThrow(message)
+    expect(chunks).toContainEqual(
+      expect.objectContaining({ type: EventType.RUN_ERROR, message }),
+    )
+    expect(await session.settled('in-1')).toMatchObject({
+      outcome: 'failed',
+      error: { message },
+    })
+    await host.close()
   })
 
   it('gives plugin tools to the model and plugin capabilities to middleware', async () => {
diff --git a/packages/ai-harness/tests/transport-edges.test.ts b/packages/ai-harness/tests/transport-edges.test.ts
index 95c842698b..8aed7af3b2 100644
--- a/packages/ai-harness/tests/transport-edges.test.ts
+++ b/packages/ai-harness/tests/transport-edges.test.ts
@@ -94,7 +94,7 @@ describe('HTTP handler edges', () => {
     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(404)
+    expect(await statusOf('run', { method: 'GET' })).toBe(400)
 
     const control = (body: string) =>
       statusOf('control', { method: 'POST', body })
@@ -175,9 +175,11 @@ describe('HTTP handler edges', () => {
     })
     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 },
         ],
diff --git a/packages/ai-harness/tests/turn-overrides.test.ts b/packages/ai-harness/tests/turn-overrides.test.ts
index 3bd652b7d0..a437f64b80 100644
--- a/packages/ai-harness/tests/turn-overrides.test.ts
+++ b/packages/ai-harness/tests/turn-overrides.test.ts
@@ -462,7 +462,9 @@ describe('turn overrides: plugin adapter picker', () => {
     const turn = session.prompt('go', { inputId: 'in-7', overrides })
 
     expect(await turn).toEqual({ text: 'turn' })
-    expect(seen).toEqual([{ operationId: turn.id, inputId: 'in-7', overrides }])
+    expect(seen).toEqual([
+      { operationId: turn.id, inputId: 'in-7', message: 'go', overrides },
+    ])
     expect(picked.calls).toHaveLength(0)
     expect(calls).toHaveLength(0)
     await host.close()
diff --git a/packages/ai-harness/tests/types.test-d.ts b/packages/ai-harness/tests/types.test-d.ts
index 084c7eb9e7..50627af651 100644
--- a/packages/ai-harness/tests/types.test-d.ts
+++ b/packages/ai-harness/tests/types.test-d.ts
@@ -1,13 +1,15 @@
 import { expectTypeOf, it } from 'vitest'
 import { z } from 'zod'
 import { defineAgent } from '@tanstack/ai'
-import { defineHarness } from '../src'
+import { defineHarness, definePlugin } from '../src'
 import { mockAdapter } from './helpers'
+import type { AnyTextAdapter, KeyedAdapter } from '@tanstack/ai'
 import type {
   HarnessConfig,
   HarnessInput,
   HarnessSession,
   Operation,
+  PluginLifetime,
   Receipt,
   RecoverHook,
 } from '../src'
@@ -75,6 +77,17 @@ it('describes how an input ended', () => {
   >()
 })
 
+it('takes a harness without an adapter, and turn plugins', () => {
+  const picked = defineHarness({
+    name: 'test/no-adapter',
+    plugins: () => [definePlugin({ name: 'test/turn', lifetime: 'turn' })],
+  })
+  expectTypeOf(picked.adapter).toEqualTypeOf<
+    AnyTextAdapter | KeyedAdapter<AnyTextAdapter> | undefined
+  >()
+  expectTypeOf<PluginLifetime>().toEqualTypeOf<'session' | 'turn' | 'run'>()
+})
+
 it('takes attempt and time limits on the harness', () => {
   expectTypeOf<HarnessConfig['durability']>().toEqualTypeOf<
     | { maxAttempts?: number; timeoutMs?: number; recover?: RecoverHook }
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..80e75fad81
--- /dev/null
+++ b/packages/ai-harness/tests/view-client-tools.test.ts
@@ -0,0 +1,171 @@
+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,
+      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-reduce.test.ts b/packages/ai-harness/tests/view-reduce.test.ts
index 42c6049e6c..ceb2a06f9b 100644
--- a/packages/ai-harness/tests/view-reduce.test.ts
+++ b/packages/ai-harness/tests/view-reduce.test.ts
@@ -27,6 +27,14 @@ const factory: ItemFactory = {
     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,
@@ -393,6 +401,71 @@ describe('view reducer', () => {
     expect(again).toBe(first)
   })
 
+  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('builds messages from a saved transcript', () => {
     const messages = messagesFromTranscript([
       { role: 'user', content: 'hi' },
diff --git a/packages/ai-persistence/src/types.ts b/packages/ai-persistence/src/types.ts
index 7e5086cb42..55009716a1 100644
--- a/packages/ai-persistence/src/types.ts
+++ b/packages/ai-persistence/src/types.ts
@@ -382,7 +382,7 @@ export interface InboxEntry {
   inputId: string
   threadId: string
   /** Who sent it, from the host's `authorize`. */
-  principal?: { id: string }
+  principal?: { id: string; tenantId?: string }
   /** The input itself. Storage holds it as-is. The harness validates it. */
   input: unknown
   status: InboxStatus

From 6636a8f7ae51cdcb2b8687107dbdb1dd23458895 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 12:39:06 +0200
Subject: [PATCH 216/286] fix(ai-mcp): keep the connector sign-in per sender

mcpConnector keeps its sign-in state, client, and tools per principal, so one person's MCP sign-in is not used for another person's turn in a shared thread.
---
 packages/ai-mcp/src/connector.ts        | 75 ++++++++++++++++---------
 packages/ai-mcp/tests/connector.test.ts | 46 +++++++++++++++
 2 files changed, 96 insertions(+), 25 deletions(-)

diff --git a/packages/ai-mcp/src/connector.ts b/packages/ai-mcp/src/connector.ts
index 8abd12ab1a..39f8a05c1c 100644
--- a/packages/ai-mcp/src/connector.ts
+++ b/packages/ai-mcp/src/connector.ts
@@ -14,7 +14,7 @@ import type {
   StoredOAuthClientInformation,
 } from '@modelcontextprotocol/client'
 import type { AnyTool } from '@tanstack/ai'
-import type { CredentialsAccess } from '@tanstack/ai-harness'
+import type { CredentialsAccess, Principal } from '@tanstack/ai-harness'
 import type { MCPClient } from './client'
 import type { MCPClientOptions } from './types'
 
@@ -179,6 +179,13 @@ function credentialProvider(
   } 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
@@ -203,33 +210,51 @@ export function mcpConnector(options: McpConnectorOptions) {
   return definePlugin({
     name: `connector/${id}`,
     setup: async (ctx) => {
-      let connected = (await ctx.credentials.get(id)) !== null
-      let client: MCPClient | undefined
-      let tools: ReadonlyArray<AnyTool> | undefined
-      const reset = async () => {
-        tools = undefined
-        const open = client
-        client = undefined
-        await open?.close().catch(() => {})
+      // 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 ? `${principal.tenantId ?? ''}:${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,
-        () => reset(),
+        () => Promise.all([...connections.values()].map(close)),
       )
 
       return {
         prompts: [
           {
             id: `connector/${id}:status`,
+            // Read after `discoverTools`, which finds the sender's state.
             text: () =>
-              connected
+              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 () => {
-          if (!connected) return []
-          if (!tools) {
+          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.
@@ -239,7 +264,7 @@ export function mcpConnector(options: McpConnectorOptions) {
                 ? saved.client?.redirectUri
                 : undefined) ?? 'http://127.0.0.1/callback'
             try {
-              client = await createMCPClient({
+              connection.client = await createMCPClient({
                 transport: {
                   type: 'http',
                   url,
@@ -265,22 +290,24 @@ export function mcpConnector(options: McpConnectorOptions) {
                 error instanceof MCPConnectionError &&
                 error.cause instanceof AuthRequiredError
               if (!needsSignIn) throw error
-              connected = false
+              connection.connected = false
               ctx.session.authRequired({ connector: id })
               throw error.cause
             }
-            tools = (await client.tools()) as ReadonlyArray<AnyTool>
+            connection.tools =
+              (await connection.client.tools()) as ReadonlyArray<AnyTool>
           }
-          return tools
+          return connection.tools
         },
         commands: {
           [`connect:${id}`]: defineCommand({
             description: `Sign in to ${label}`,
-            run: async () => {
+            // 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, ctx.credentials, {
+                const provider = credentialProvider(id, credentials, {
                   redirectUri: receiver.redirectUri,
                   clientName,
                   scopes: options.scopes,
@@ -314,17 +341,15 @@ export function mcpConnector(options: McpConnectorOptions) {
               } finally {
                 receiver.close()
               }
-              connected = true
-              await reset()
+              await signedIn(principal, true)
               return `Connected to ${label}.`
             },
           }),
           [`disconnect:${id}`]: defineCommand({
             description: `Sign out of ${label}`,
-            run: async () => {
-              await ctx.credentials.delete(id)
-              connected = false
-              await reset()
+            run: async (_input, { credentials, principal }) => {
+              await credentials.delete(id)
+              await signedIn(principal, false)
               return `Disconnected from ${label}.`
             },
           }),
diff --git a/packages/ai-mcp/tests/connector.test.ts b/packages/ai-mcp/tests/connector.test.ts
index e07021fb27..8b7abd021b 100644
--- a/packages/ai-mcp/tests/connector.test.ts
+++ b/packages/ai-mcp/tests/connector.test.ts
@@ -154,6 +154,52 @@ describe('mcpConnector', () => {
     ).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({ threadId: 't', userId }, '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('tells the model to ask for /connect before sign-in', async () => {
     const model = recorder()
     const host = createHarnessHost({ persistence: memoryPersistence() })

From 802377ed73cb64e10e23a0934ec1a981e711344e Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 12:39:06 +0200
Subject: [PATCH 217/286] feat(ai-harness-cli): runCli takes a host and a
 principal

With host, the CLI uses it and does not close it. principal reaches every session the CLI opens and the --serve handler.
---
 packages/ai-harness-cli/src/index.ts          |  36 ++++-
 packages/ai-harness-cli/src/serve.ts          |   7 +-
 packages/ai-harness-cli/tests/cli.test.ts     | 134 ++++++++++++++++++
 packages/ai-harness-cli/tests/printer.test.ts |   1 +
 4 files changed, 170 insertions(+), 8 deletions(-)

diff --git a/packages/ai-harness-cli/src/index.ts b/packages/ai-harness-cli/src/index.ts
index ac057e0a99..9b5c511834 100644
--- a/packages/ai-harness-cli/src/index.ts
+++ b/packages/ai-harness-cli/src/index.ts
@@ -7,15 +7,27 @@ import { EXIT, runPrint } from './print'
 import { createToken, serve } from './serve'
 import type {
   AnyHarness,
+  HarnessHost,
   HarnessPersistence,
   HarnessSession,
+  Principal,
   UserInput,
 } from '@tanstack/ai-harness'
 import type { SessionView, SessionViewSource } from '@tanstack/ai-harness/view'
 
 export interface RunCliOptions {
-  /** Where sessions keep state. Default: in memory. */
+  /** Where sessions keep state. Default: in memory. Do not set it with `host`. */
   persistence?: HarnessPersistence
+  /**
+   * Your own host, so the CLI keeps its hooks: leases, recovery, and stores.
+   * You own it: the CLI does not close it. Do not set it with `persistence`.
+   */
+  host?: HarnessHost
+  /**
+   * Who uses the CLI. Sessions open as this principal, so credentials and
+   * provider keys are theirs. `--serve` authorizes each request as them.
+   */
+  principal?: Principal
   /** Default: `process.argv.slice(2)`. */
   argv?: ReadonlyArray<string>
   stdin?: NodeJS.ReadStream
@@ -95,9 +107,16 @@ export async function runCli(
     return EXIT.ok
   }
 
-  const host = createHarnessHost(
-    options.persistence ? { persistence: options.persistence } : {},
-  )
+  if (options.host && options.persistence) {
+    stderr.write('Give runCli a host or persistence, not both.\n')
+    return EXIT.failed
+  }
+  const host =
+    options.host ??
+    createHarnessHost(
+      options.persistence ? { persistence: options.persistence } : {},
+    )
+  const { principal } = options
   const approvals = args.yes ? 'auto' : 'ask'
   try {
     if (args.acp) {
@@ -182,6 +201,7 @@ export async function runCli(
         token,
         threadId: args.thread,
         approvals,
+        ...(principal ? { principal } : {}),
       })
       stderr.write(`Serving ${harness.name} at ${server.url}\n`)
       if (!args.token && !env.HARNESS_TOKEN) stderr.write(`Token: ${token}\n`)
@@ -193,7 +213,10 @@ export async function runCli(
       return EXIT.ok
     }
 
-    const session = await host.open(harness, { threadId: args.thread })
+    const session = await host.open(harness, {
+      threadId: args.thread,
+      ...(principal ? { principal } : {}),
+    })
     // Relative to the working folder, as a relative --media-dir is.
     const mediaDir = args.mediaDir ?? defaultMediaDir(harness.name)
     if (args.print !== undefined) {
@@ -223,7 +246,8 @@ export async function runCli(
     stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
     return EXIT.failed
   } finally {
-    await host.close()
+    // A host the caller gave stays open: the caller owns it.
+    if (!options.host) await host.close()
   }
 }
 
diff --git a/packages/ai-harness-cli/src/serve.ts b/packages/ai-harness-cli/src/serve.ts
index 944062f4ae..ba75af5be3 100644
--- a/packages/ai-harness-cli/src/serve.ts
+++ b/packages/ai-harness-cli/src/serve.ts
@@ -4,7 +4,7 @@ import { randomBytes, timingSafeEqual } from 'node:crypto'
 import { createHarnessHandler } from '@tanstack/ai-harness'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { ReadableStream as NodeReadableStream } from 'node:stream/web'
-import type { AnyHarness, HarnessHost } from '@tanstack/ai-harness'
+import type { AnyHarness, HarnessHost, Principal } from '@tanstack/ai-harness'
 
 export interface ServeOptions {
   host: HarnessHost
@@ -17,6 +17,8 @@ export interface ServeOptions {
   threadId?: string
   /** How `/mcp` handles tool calls that need approval. Default `'ask'`. */
   approvals?: 'ask' | 'auto'
+  /** Who a request with the token is. Default `{ id: 'cli' }`. */
+  principal?: Principal
 }
 
 /** The MCP server for `/mcp`, or `undefined` without `@tanstack/ai-mcp`. */
@@ -84,10 +86,11 @@ export async function serve(
 ): Promise<{ url: string; close: () => Promise<void> }> {
   const isAllowed = (request: Request) =>
     sameToken(request.headers.get('authorization'), options.token)
+  const principal = options.principal ?? { id: 'cli' }
   const handler = createHarnessHandler({
     host: options.host,
     harness: options.harness,
-    authorize: (request) => (isAllowed(request) ? { id: 'cli' } : null),
+    authorize: (request) => (isAllowed(request) ? principal : null),
   })
   const mcp = await mcpServer(options)
   const route = (request: Request) => {
diff --git a/packages/ai-harness-cli/tests/cli.test.ts b/packages/ai-harness-cli/tests/cli.test.ts
index 3f8227edfa..a566f494ac 100644
--- a/packages/ai-harness-cli/tests/cli.test.ts
+++ b/packages/ai-harness-cli/tests/cli.test.ts
@@ -364,6 +364,140 @@ describe('secret answers in line mode', () => {
   })
 })
 
+describe('a host and a principal', () => {
+  const acme = defineByokProvider({ id: 'acme', label: 'Acme' })
+
+  it('uses the given host, leaves it open, and saves keys for the principal', async () => {
+    const persistence = memoryPersistence()
+    const host = createHarnessHost({ persistence })
+    const close = vi.spyOn(host, 'close')
+    const code = await runCli(
+      defineHarness({
+        name: 'test/host',
+        adapter: scripted([]).adapter,
+        plugins: () => [providerKeys({ providers: [acme] })],
+      }),
+      {
+        argv: [],
+        stdin: stdinFrom(['/connect acme\n', 'sk-ada\n', '/exit\n'], {
+          isTTY: false,
+        }),
+        stdout: capture(),
+        stderr: capture(),
+        host,
+        principal: { id: 'ada' },
+      },
+    )
+    expect(code).toBe(EXIT.ok)
+    expect(close).not.toHaveBeenCalled()
+    const saved = (userId?: string) =>
+      persistence.stores.credentials.get(
+        { threadId: 'main', ...(userId ? { userId } : {}) },
+        'acme',
+      )
+    expect(await saved('ada')).toEqual({ type: 'api_key', value: 'sk-ada' })
+    expect(await saved()).toBeNull()
+    await host.close()
+  })
+
+  it('opens the session as the principal', async () => {
+    const { adapter } = scripted([textTurn('ok')])
+    const seen: Array<string | undefined> = []
+    const code = await runCli(
+      defineHarness({
+        name: 'test/principal',
+        adapter,
+        plugins: () => [
+          definePlugin({
+            name: 'test/whoami',
+            setup: (ctx) => void seen.push(ctx.session.principal?.id),
+          }),
+        ],
+      }),
+      {
+        argv: ['-p', 'hi'],
+        stdout: capture(),
+        stderr: capture(),
+        persistence: memoryPersistence(),
+        principal: { id: 'ada' },
+      },
+    )
+    expect(code).toBe(EXIT.ok)
+    expect(seen).toEqual(['ada'])
+  })
+
+  it('refuses a host and persistence together', async () => {
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const stderr = capture()
+    const code = await runCli(
+      defineHarness({ name: 'test/both', adapter: scripted([]).adapter }),
+      {
+        argv: ['-p', 'hi'],
+        stdout: capture(),
+        stderr,
+        host,
+        persistence: memoryPersistence(),
+      },
+    )
+    expect(code).toBe(EXIT.failed)
+    expect(stderr.text).toContain('host or persistence')
+    await host.close()
+  })
+
+  it('serves as the principal', async () => {
+    const persistence = memoryPersistence()
+    const host = createHarnessHost({ persistence })
+    const server = await serve({
+      host,
+      harness: defineHarness({
+        name: 'test/serve-principal',
+        adapter: scripted([]).adapter,
+        plugins: () => [providerKeys({ providers: [acme] })],
+      }),
+      port: 0,
+      hostname: '127.0.0.1',
+      token: 'secret',
+      principal: { id: 'ada' },
+    })
+    try {
+      const control = (input: unknown) =>
+        fetch(`${server.url}/control`, {
+          method: 'POST',
+          headers: {
+            authorization: 'Bearer secret',
+            'content-type': 'application/json',
+          },
+          body: JSON.stringify({ threadId: 't', input }),
+        })
+      await control({ op: 'command', name: 'connect:acme' })
+      const question = await vi.waitFor(async () => {
+        const snapshot = await fetch(`${server.url}/snapshot?threadId=t`, {
+          headers: { authorization: 'Bearer secret' },
+        })
+        const [pending] = (await snapshot.json()).pendingQuestions
+        expect(pending).toBeDefined()
+        return pending
+      })
+      await control({
+        op: 'answer',
+        questionId: question.questionId,
+        value: 'sk-ada',
+      })
+      await vi.waitFor(async () =>
+        expect(
+          await persistence.stores.credentials.get(
+            { threadId: 't', userId: 'ada' },
+            'acme',
+          ),
+        ).toEqual({ type: 'api_key', value: 'sk-ada' }),
+      )
+    } finally {
+      await server.close()
+      await host.close()
+    }
+  })
+})
+
 describe('serve mode', () => {
   it('serves the session protocol and requires the token', async () => {
     const { adapter } = scripted([textTurn('served')])
diff --git a/packages/ai-harness-cli/tests/printer.test.ts b/packages/ai-harness-cli/tests/printer.test.ts
index 084c825610..5b1b84d5a1 100644
--- a/packages/ai-harness-cli/tests/printer.test.ts
+++ b/packages/ai-harness-cli/tests/printer.test.ts
@@ -8,6 +8,7 @@ const base: SessionViewState = {
   connection: 'open',
   messages: [],
   approvals: [],
+  clientTools: [],
   questions: [],
   signIns: [],
   agents: [],

From 79e523a7a202913b16cdf17bc8461ec424e9ed4c Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 12:39:16 +0200
Subject: [PATCH 218/286] test(e2e): check the harness run route, inputs, and a
 reloaded ChatClient

POST run with the client runId and a resume, GET run hydrate, a resolve on RUN_FINISHED, forwardedProps as context, two senders on one thread, a ChatClient approval, and a reloaded ChatClient that joins a running turn.
---
 .../e2e/fixtures/harness/protocol-inputs.json | 112 ++++++
 testing/e2e/src/lib/harness-protocol-tools.ts |  34 ++
 .../e2e/src/routes/api.harness-protocol.$.ts  |  44 ++-
 testing/e2e/tests/harness-media.spec.ts       |   3 +-
 .../e2e/tests/harness-protocol-inputs.spec.ts | 357 ++++++++++++++++++
 testing/e2e/tests/harness-protocol.spec.ts    |   7 +-
 6 files changed, 551 insertions(+), 6 deletions(-)
 create mode 100644 testing/e2e/fixtures/harness/protocol-inputs.json
 create mode 100644 testing/e2e/src/lib/harness-protocol-tools.ts
 create mode 100644 testing/e2e/tests/harness-protocol-inputs.spec.ts

diff --git a/testing/e2e/fixtures/harness/protocol-inputs.json b/testing/e2e/fixtures/harness/protocol-inputs.json
new file mode 100644
index 0000000000..fb4193cc30
--- /dev/null
+++ b/testing/e2e/fixtures/harness/protocol-inputs.json
@@ -0,0 +1,112 @@
+{
+  "fixtures": [
+    {
+      "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."
+      }
+    }
+  ]
+}
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..12ffd28d0d
--- /dev/null
+++ b/testing/e2e/src/lib/harness-protocol-tools.ts
@@ -0,0 +1,34 @@
+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({}),
+})
diff --git a/testing/e2e/src/routes/api.harness-protocol.$.ts b/testing/e2e/src/routes/api.harness-protocol.$.ts
index 2e0880d4a0..0fd243d3b4 100644
--- a/testing/e2e/src/routes/api.harness-protocol.$.ts
+++ b/testing/e2e/src/routes/api.harness-protocol.$.ts
@@ -14,6 +14,7 @@ import {
 import { todos } from '@tanstack/ai-harness/plugins'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { z } from 'zod'
+import { askName, deploy, probe, whoami } from '@/lib/harness-protocol-tools'
 import { createImageAdapter } from '@/lib/media-providers'
 import { createTextAdapter } from '@/lib/providers'
 
@@ -77,6 +78,13 @@ function handlerFor(request: Request) {
     name: 'e2e/protocol',
     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,
+      })),
+    ],
     subagents: { agents: [painter] },
     agents: [
       defineAgent({
@@ -89,6 +97,31 @@ function handlerFor(request: Request) {
     expose: { agents: ['echo'] },
     plugins: () => [
       todos(),
+      // 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: () => ({
@@ -111,10 +144,13 @@ function handlerFor(request: Request) {
   return createHarnessHandler({
     host: request.headers.get('x-harness-durable') === '1' ? durableHost : host,
     harness,
-    authorize: (req) =>
-      req.headers.get('authorization') === 'Bearer e2e-token'
-        ? { id: 'e2e' }
-        : null,
+    // Two users, so a test can share one thread between them.
+    authorize: (req) => {
+      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
+    },
     // Each request makes a new handler, so a fixed secret keeps a signed URL
     // working on the next request.
     mediaSecret: 'e2e-media-secret',
diff --git a/testing/e2e/tests/harness-media.spec.ts b/testing/e2e/tests/harness-media.spec.ts
index 449ba9ef24..b7e41ebbb1 100644
--- a/testing/e2e/tests/harness-media.spec.ts
+++ b/testing/e2e/tests/harness-media.spec.ts
@@ -111,7 +111,8 @@ test.describe('harness media', () => {
       headers: { ...api.headers, 'content-type': 'application/json' },
       data: {
         threadId,
-        runId: 'client-run',
+        // The run id is also the input id, so each test needs its own.
+        runId: `media-run-${testId}`,
         messages: [
           {
             id: 'u1',
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..88630e62fb
--- /dev/null
+++ b/testing/e2e/tests/harness-protocol-inputs.spec.ts
@@ -0,0 +1,357 @@
+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
+}
+
+/** One user of the harness protocol route: its headers and its requests. */
+function asUser(
+  request: APIRequestContext,
+  testId: string,
+  aimockPort: number,
+  token = 'e2e-token',
+) {
+  const headers = {
+    authorization: `Bearer ${token}`,
+    'x-test-id': testId,
+    'x-aimock-port': String(aimockPort),
+  }
+  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 answers = async (threadId: string) => {
+    const response = await request.get(
+      `/api/harness-protocol/transcript?threadId=${threadId}`,
+      { headers },
+    )
+    const transcript: Array<{ role: string; content: unknown }> =
+      await response.json()
+    return transcript
+      .filter((message) => message.role === 'assistant')
+      .map((message) => message.content)
+  }
+  return { headers, json, run, control, answers }
+}
+
+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()
+  })
+})
diff --git a/testing/e2e/tests/harness-protocol.spec.ts b/testing/e2e/tests/harness-protocol.spec.ts
index 4e2e4ecec1..e3414aedc5 100644
--- a/testing/e2e/tests/harness-protocol.spec.ts
+++ b/testing/e2e/tests/harness-protocol.spec.ts
@@ -37,7 +37,8 @@ test.describe('harness protocol', () => {
       },
       data: {
         threadId: `protocol-${testId}`,
-        runId: 'client-run',
+        // 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' },
         ],
@@ -58,6 +59,10 @@ test.describe('harness protocol', () => {
       .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')
   })
 

From 306175098b0190f68549424737ec39cadaa4c9ad Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 12:39:16 +0200
Subject: [PATCH 219/286] docs(ai-harness): shared threads, useChat on POST
 run, client tools, context, and sign-in wait

- New: harness/shared-threads and sandbox/build-a-provider.
- Updated: connect, custom-ui, inputs, plugins, auth, cli, turn-control, overview, and the sandbox provider pages.
---
 docs/config.json                            |  31 ++-
 docs/harness/auth.md                        |  76 ++++++-
 docs/harness/cli.md                         |  31 +++
 docs/harness/connect.md                     | 111 ++++++++++-
 docs/harness/custom-ui.md                   |  71 ++++++-
 docs/harness/inputs.md                      |  64 +++++-
 docs/harness/overview.md                    |   2 +-
 docs/harness/plugins.md                     |  76 +++++--
 docs/harness/shared-threads.md              | 196 ++++++++++++++++++
 docs/harness/turn-control.md                |   2 +
 docs/persistence/build-a-sandbox-adapter.md |   2 +
 docs/sandbox/build-a-provider.md            | 207 ++++++++++++++++++++
 docs/sandbox/providers.md                   |   3 +
 13 files changed, 841 insertions(+), 31 deletions(-)
 create mode 100644 docs/harness/shared-threads.md
 create mode 100644 docs/sandbox/build-a-provider.md

diff --git a/docs/config.json b/docs/config.json
index 74f5e99bf8..3d9f518483 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -719,7 +719,7 @@
           "label": "Build a Sandbox Adapter",
           "to": "persistence/build-a-sandbox-adapter",
           "addedAt": "2026-08-04",
-          "updatedAt": "2026-08-14"
+          "updatedAt": "2026-10-05"
         },
         {
           "label": "Store Reference",
@@ -891,13 +891,13 @@
           "label": "Build your first harness",
           "to": "harness/overview",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-10-02"
+          "updatedAt": "2026-10-05"
         },
         {
           "label": "Connect clients",
           "to": "harness/connect",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-09-29"
+          "updatedAt": "2026-10-05"
         },
         {
           "label": "Send and show media",
@@ -908,7 +908,7 @@
           "label": "Run in the terminal",
           "to": "harness/cli",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-09-29"
+          "updatedAt": "2026-10-05"
         },
         {
           "label": "Durable sessions",
@@ -920,7 +920,7 @@
           "label": "Send inputs safely",
           "to": "harness/inputs",
           "addedAt": "2026-09-30",
-          "updatedAt": "2026-10-01"
+          "updatedAt": "2026-10-05"
         },
         {
           "label": "Run side effects once",
@@ -938,7 +938,7 @@
           "label": "Control how a turn ends",
           "to": "harness/turn-control",
           "addedAt": "2026-10-01",
-          "updatedAt": "2026-10-03"
+          "updatedAt": "2026-10-05"
         },
         {
           "label": "Compact a long session",
@@ -954,7 +954,7 @@
           "label": "Write a plugin",
           "to": "harness/plugins",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-10-02"
+          "updatedAt": "2026-10-05"
         },
         {
           "label": "Build a coding agent",
@@ -971,7 +971,13 @@
         {
           "label": "Auth and connectors",
           "to": "harness/auth",
-          "addedAt": "2026-09-26"
+          "addedAt": "2026-09-26",
+          "updatedAt": "2026-10-05"
+        },
+        {
+          "label": "Share a thread between people",
+          "to": "harness/shared-threads",
+          "addedAt": "2026-10-05"
         },
         {
           "label": "Use MCP servers",
@@ -1010,7 +1016,7 @@
           "label": "Build your own UI",
           "to": "harness/custom-ui",
           "addedAt": "2026-09-28",
-          "updatedAt": "2026-09-29"
+          "updatedAt": "2026-10-05"
         },
         {
           "label": "Run agents from a harness",
@@ -1050,7 +1056,7 @@
           "label": "Providers",
           "to": "sandbox/providers",
           "addedAt": "2026-06-29",
-          "updatedAt": "2026-09-24"
+          "updatedAt": "2026-10-05"
         },
         {
           "label": "Harnesses",
@@ -1191,6 +1197,11 @@
           "to": "sandbox/cloudflare",
           "addedAt": "2026-06-29",
           "updatedAt": "2026-08-20"
+        },
+        {
+          "label": "Build a Provider",
+          "to": "sandbox/build-a-provider",
+          "addedAt": "2026-10-05"
         }
       ]
     },
diff --git a/docs/harness/auth.md b/docs/harness/auth.md
index 90e38aab16..f9c7fa52e9 100644
--- a/docs/harness/auth.md
+++ b/docs/harness/auth.md
@@ -61,9 +61,78 @@ Set `login: 'device'` for SSH sessions, containers, and CI. The CLI then shows a
 
 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',
+  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-5.6'),
+  plugins: () => [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:
+
+```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 session's principal. Without it, credentials live in memory until the process stops.
+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'
@@ -89,13 +158,14 @@ export const credentials = defineCredentialStore({
 
 - 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 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 session's principal.
+`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/cli.md b/docs/harness/cli.md
index 42364b1bce..8c603a1f52 100644
--- a/docs/harness/cli.md
+++ b/docs/harness/cli.md
@@ -70,6 +70,36 @@ Line mode reads one message or command per line and waits for each turn. It work
 | 2 | The turn waits for an approval. |
 | 130 | The turn was cancelled. |
 
+## Use your own host and user
+
+By default, the CLI builds its own host in memory and opens sessions with no user. Your server already has a durable host with leases, recovery, and stores, and each person has their own credentials. Give the CLI that host and the user:
+
+```ts group=harness-cli-host
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { runCli } from '@tanstack/ai-harness-cli'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { openaiText } from '@tanstack/ai-openai'
+
+const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-5.6'),
+})
+
+const { runs, metadata, credentials } = memoryPersistence().stores
+const host = createHarnessHost({
+  persistence: { stores: { log: memoryLogStore(), runs, metadata, credentials } },
+})
+
+process.exitCode = await runCli(assistant, { host, principal: { id: 'ada' } })
+await host.close()
+```
+
+- You own the host, so the CLI does not close it. Close it yourself when `runCli` returns. Without `host`, the CLI builds a host and closes it.
+- Give `host` or `persistence`, not both. With both, `runCli` writes `Give runCli a host or persistence, not both.` and returns code 1.
+- Line mode, `-p`, and your own `ui` open the session as `principal`, so `/connect` saves keys for that user.
+- `--serve` gives the same principal to each request with the token.
+- `--acp`, `--mcp`, and `--dashboard` open their sessions without the principal.
+
 ## Commands in line mode
 
 For the session:
@@ -141,6 +171,7 @@ For a full Ink screen with approvals, questions, sign-ins, and child agents, cop
 ## What you have now
 
 - One entry file that runs your harness as a terminal app, a script step, an editor agent, an MCP server, or an HTTP server.
+- A CLI that uses your durable host and runs as your user.
 - Your own terminal screen on the same session, with any TUI library.
 - Files that you send with `@path`, and a folder with the media that your agents make.
 
diff --git a/docs/harness/connect.md b/docs/harness/connect.md
index 2173bd9ebc..c5bf7bc288 100644
--- a/docs/harness/connect.md
+++ b/docs/harness/connect.md
@@ -44,7 +44,9 @@ export const handler = createHarnessHandler({
 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. Any AG-UI client works. The prompt keeps every content part of the last user message, for example an image.
+- `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.
 - `GET snapshot?threadId=`: the status, running operations, and waiting approvals.
@@ -76,6 +78,110 @@ for await (const entry of client.events()) {
 
 To upload files and show the media that your agents make, read [Send and show media](./media).
 
+## 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-5.6'),
+  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.
+- With more than one server, send `GET run?runId=` to the server that runs the turn. Only that server has the live events of the turn.
+
+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.
+- 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`:
@@ -120,9 +226,12 @@ const stream = chat({
 
 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.
+- 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.
 - A WebSocket, an ACP agent for editors, and a harness you can call from `chat()`.
 
diff --git a/docs/harness/custom-ui.md b/docs/harness/custom-ui.md
index d243cde990..628a750f59 100644
--- a/docs/harness/custom-ui.md
+++ b/docs/harness/custom-ui.md
@@ -126,6 +126,7 @@ The conversation:
 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).
 - `questions`: questions from a command or a plugin.
 - `signIns`: connectors that need a sign-in, with a `url` and a `userCode` when the connector gives them.
 
@@ -166,9 +167,10 @@ 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.
 - `question.answer(value)`: answers a question.
 
-If a turn waits for more than one approval, the turn continues after you answer all of them.
+If a turn waits for more than one approval or client tool, the turn continues after you answer all of them.
 
 ## 4. Listen for events
 
@@ -184,6 +186,7 @@ view.on('approval', (approval) => {
 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.
 - `'question'`: a question with a `message`, a `schema`, and `answer(value)`.
 - `'signIn'`: a connector that needs a sign-in, with `connector`, `url`, and `userCode`.
 
@@ -378,9 +381,75 @@ export function Chat() {
 - `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-5.6'),
+  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/inputs.md b/docs/harness/inputs.md
index 98fdaaf374..47c0a59de0 100644
--- a/docs/harness/inputs.md
+++ b/docs/harness/inputs.md
@@ -109,15 +109,75 @@ A message that arrives while the model writes its final answer still gets an ans
 
 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.
 
-- A `busy: 'steer'` prompt has its own operation. 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.
-- A `session.steer` input has no operation of its own. The `operationId` of its receipt is the running turn, so a cancel with that id cancels the turn.
+- 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).
 
+## 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-5.6'),
+  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.
+- Context from the client that tools read, also after a restart.
diff --git a/docs/harness/overview.md b/docs/harness/overview.md
index e6064df3ec..61559c4e33 100644
--- a/docs/harness/overview.md
+++ b/docs/harness/overview.md
@@ -158,7 +158,7 @@ export const withClock = defineHarness({
 })
 ```
 
-`plugins` is a function, so every session gets its own plugin instances. Set `lifetime: 'run'` on a plugin to set it up again for each turn.
+`plugins` is a function, so every session gets its own plugin instances. Set `lifetime: 'turn'` on a plugin to set it up again for each turn.
 
 If two plugins add a tool with the same name, `host.open` fails and names both plugins.
 
diff --git a/docs/harness/plugins.md b/docs/harness/plugins.md
index 3ab18e0ac2..c84705d097 100644
--- a/docs/harness/plugins.md
+++ b/docs/harness/plugins.md
@@ -189,39 +189,89 @@ export const usageByAgent = definePlugin({
 
 ## Pick the model of a turn
 
-Some turns need another model: a hard plan needs a strong model, and a short reply does not. Return an `adapter` picker from `setup`. The session calls it when each turn starts, with that turn:
+Some turns need another model: a short question does not need your strongest model, and an organization can allow only some models. Return an `adapter` picker from `setup`. When each turn starts, the session calls it with the message, context, and sender of that turn:
 
 ```ts group=harness-plugins
 import { anthropicText } from '@tanstack/ai-anthropic'
 
-export const strongForHardTurns = definePlugin({
-  name: 'acme/strong-for-hard-turns',
+export const cheapForShortTurns = definePlugin({
+  name: 'acme/cheap-for-short-turns',
   setup: () => ({
     adapter: (turn) =>
-      turn.overrides?.reasoning === 'high'
-        ? anthropicText('claude-opus-5-5')
-        : undefined,
+      typeof turn.message === 'string' && turn.message.length < 200
+        ? anthropicText('claude-haiku-4-5')
+        : anthropicText('claude-sonnet-5-5'),
   }),
 })
 ```
 
-A prompt with `overrides: { reasoning: 'high' }` now runs on Claude Opus. Other turns keep the harness adapter.
+A short message now runs on Claude Haiku, and a long one on Claude Sonnet.
 
 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.
-- `overrides`: the [overrides of the prompt](./turn-control#give-one-prompt-its-own-settings), when it has some.
+| Field | What it is |
+| --- | --- |
+| `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. |
+| `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. 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:
 
 - `undefined` keeps the harness adapter.
 - If more than one plugin returns an adapter, the last plugin wins.
 - The `overrides.adapter` of the turn wins over every pick.
-- A keyed adapter gets the key of the user. See [Connect model providers](./provider-keys).
+- A keyed adapter gets the key of the sender. See [Connect model providers](./provider-keys).
 
 If the picker does not need the turn, it can take no parameter.
 
+### Read the model from your data
+
+The picker is synchronous. To read a database first, give the plugin `lifetime: 'turn'`. The session then runs its `setup` for each turn and gives it the same turn as `ctx.turn`. An async `setup` can read the model from your data:
+
+```ts group=harness-plugins
+// Your lookup, for example a database query.
+async function planOf(tenantId: string | undefined) {
+  return tenantId === 'acme' ? 'strong' : 'fast'
+}
+
+export const modelOfTheOrg = definePlugin({
+  name: 'acme/model-of-the-org',
+  lifetime: 'turn',
+  setup: async (ctx) => {
+    const plan = await planOf(ctx.turn?.principal?.tenantId)
+    const adapter =
+      plan === 'strong'
+        ? anthropicText('claude-sonnet-5-5')
+        : anthropicText('claude-haiku-4-5')
+    return { adapter: () => adapter }
+  },
+})
+```
+
+A plugin with the default lifetime has no turn at setup, so its `ctx.turn` is `undefined`.
+
+### Leave out the harness model
+
+When a plugin picks the model of every turn, `defineHarness` needs no `adapter`:
+
+```ts group=harness-plugins
+import { defineHarness } from '@tanstack/ai-harness'
+
+export const assistant = defineHarness({
+  name: 'acme/assistant',
+  plugins: () => [modelOfTheOrg],
+})
+```
+
+If no plugin picks a model and the turn has no `overrides.adapter`, the turn fails with this error:
+
+```text
+This turn has no model. Set `adapter` in defineHarness, return one from a plugin `adapter()`, or pass `overrides.adapter` to the turn.
+```
+
 ## Let plugins work together
 
 Three ways, from simple to loose:
@@ -266,7 +316,7 @@ Read `ctx.collect` at run time (in a command, a tool, or a middleware hook). Dur
 
 Open resources with `ctx.resources.acquire(open, close)`. They close when the session closes, newest first. If a later plugin fails in `setup`, every plugin set up so far is cleaned up, and no model request is sent.
 
-Set `lifetime: 'run'` to set a plugin up again for each turn.
+Set `lifetime: 'turn'` to set a plugin up again for each turn.
 
 ## See the plan
 
@@ -276,7 +326,7 @@ Set `lifetime: 'run'` to set a plugin up again for each turn.
 
 - A plugin that adds tools, prompts, commands, settings, and state to any harness.
 - Middleware that sees every model call, in the lead turn and in every agent.
-- A picker that chooses the model of each turn.
+- A picker that chooses the model of each turn from its message, context, and sender.
 - Plugins that share services, lists, and events without knowing each other.
 
 Next: see the [first-party plugins](./coding-agent) that turn a harness into a coding agent.
diff --git a/docs/harness/shared-threads.md b/docs/harness/shared-threads.md
new file mode 100644
index 0000000000..33297404a1
--- /dev/null
+++ b/docs/harness/shared-threads.md
@@ -0,0 +1,196 @@
+---
+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-5.6'),
+})
+
+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.
+- `mcpConnector` keeps the sign-in and the tools of each sender apart.
+
+`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('linear', { 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-5.6'),
+  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({ threadId: 'admin', tenantId }, 'linear', {
+    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/turn-control.md b/docs/harness/turn-control.md
index 323a86364e..ae585aa09c 100644
--- a/docs/harness/turn-control.md
+++ b/docs/harness/turn-control.md
@@ -136,6 +136,8 @@ 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. 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.
 
 - If `onJoin` throws, the turn fails, and those messages run as their own turns.
diff --git a/docs/persistence/build-a-sandbox-adapter.md b/docs/persistence/build-a-sandbox-adapter.md
index 421610939a..022448332a 100644
--- a/docs/persistence/build-a-sandbox-adapter.md
+++ b/docs/persistence/build-a-sandbox-adapter.md
@@ -281,3 +281,5 @@ painful to find by hand:
 - [Events](../sandbox/events) covers what a stored transcript holds, and how to trim it.
 - [Durable Runs Explained](../sandbox/durable-runs) is the same subject in plain language with
   no code, if the postures above felt abrupt.
+- [Build a Sandbox Provider](../sandbox/build-a-provider) runs the same journal, takeover,
+  and reaper suites against a provider that you write.
diff --git a/docs/sandbox/build-a-provider.md b/docs/sandbox/build-a-provider.md
new file mode 100644
index 0000000000..4e5d0d7d29
--- /dev/null
+++ b/docs/sandbox/build-a-provider.md
@@ -0,0 +1,207 @@
+---
+title: Build a Sandbox Provider (Advanced)
+id: sandbox-build-a-provider
+order: 15
+description: "Run sandboxes on a platform that TanStack AI has no provider for: implement the SandboxProvider contract, declare what it can do, and prove it with the conformance suites."
+keywords:
+  - SandboxProvider
+  - SandboxHandle
+  - sandbox capabilities
+  - sandbox conformance suite
+  - runJournalConformance
+---
+
+Your agent must run on a platform that TanStack AI has no provider for. The platform
+can be your own VM fleet, an internal container service, or a cloud that you already
+use. A provider is the small piece that creates, finds, and destroys sandboxes on that
+platform. Write one against the `SandboxProvider` contract. Then prove it with the same
+conformance suites that the bundled providers run.
+
+## 1. Write the provider
+
+A provider has a `name` and four methods: `capabilities`, `create`, `resume`, and
+`destroy`. `create` and `resume` give back a `SandboxHandle`, the object that the
+agent, the workspace setup, and the journal use. This provider wraps a platform SDK
+called `vms`:
+
+```ts
+import {
+  UnsupportedCapabilityError,
+  createExecBackedGit,
+} from '@tanstack/ai-sandbox'
+import type {
+  SandboxCapabilities,
+  SandboxHandle,
+  SandboxProcess,
+  SandboxProvider,
+} from '@tanstack/ai-sandbox'
+// The SDK of your platform.
+import { vms } from './vm-client'
+import type { Vm } from './vm-client'
+
+const capabilities: SandboxCapabilities = {
+  fs: true,
+  exec: true,
+  env: true,
+  backgroundProcesses: true,
+  durableFilesystem: true,
+  // Not measured yet, so false. See step 2.
+  killableProcesses: false,
+  writableStdin: false,
+  ports: false,
+  snapshots: false,
+  networkPolicy: false,
+  fork: false,
+}
+
+function toHandle(vm: Vm): SandboxHandle {
+  const proc: SandboxProcess = {
+    exec: (command, options) => vm.exec(command, options),
+    spawn: (command, options) => vm.spawn(command, options),
+  }
+  return {
+    id: vm.id,
+    provider: 'my-vm',
+    workspaceRoot: '/workspace',
+    capabilities,
+    fs: {
+      read: (path) => vm.files.readText(path),
+      readBytes: (path) => vm.files.readBytes(path),
+      write: (path, data) => vm.files.write(path, data),
+      list: (path) => vm.files.list(path),
+      mkdir: (path) => vm.files.mkdir(path),
+      remove: (path) => vm.files.remove(path),
+      rename: (from, to) => vm.files.rename(from, to),
+      exists: (path) => vm.files.exists(path),
+    },
+    git: createExecBackedGit(proc, '/workspace'),
+    process: proc,
+    ports: {
+      connect: async () => {
+        throw new UnsupportedCapabilityError('my-vm', 'ports')
+      },
+    },
+    env: { set: (vars) => vm.setEnv(vars) },
+    destroy: () => vm.delete(),
+  }
+}
+
+export function myVmSandbox(): SandboxProvider {
+  return {
+    name: 'my-vm',
+    capabilities: () => capabilities,
+    create: async (input) =>
+      toHandle(await vms.create({ name: input.id, env: input.env })),
+    resume: async ({ id }) => {
+      const vm = await vms.find(id)
+      return vm ? toHandle(vm) : null
+    },
+    destroy: ({ id }) => vms.delete(id),
+  }
+}
+```
+
+Each part has one rule:
+
+- `create`: if your platform can name a sandbox, use `input.id` as the name. Then a thread always finds the same sandbox again.
+- `resume`: find a sandbox by its id. If the sandbox is gone, return `null`.
+- `destroy`: delete a sandbox by its id. You get only the id here, not a handle.
+- `exec` and `spawn`: run the command string through a POSIX shell. The journal needs `>>` and `tail -c +N -f`.
+- `git`: `createExecBackedGit` runs `git` through your `exec`. If your platform has its own git API, you can use that instead.
+
+## 2. Declare what it can do
+
+`fs` and `exec` are always `true`. Each other flag is a promise to the code that uses
+your sandbox. Set a flag to `true` only after you saw it work on a real sandbox.
+
+- `killableProcesses`: `kill()` and the `signal` of `spawn` stop the process inside the sandbox, with its children. A wrong `true` leaves one `tail -f` running for each run.
+- `backgroundProcesses`: a process from `spawn` keeps running after the call returns. With `killableProcesses`, the journal streams the output of a run. If one of the two is `false`, the journal reader polls the file in a loop.
+- `writableStdin`: `stdin.write` of a spawned process works. If it is `false`, a harness writes its prompt to a file and redirects the file.
+- `snapshots`: add `restoreSnapshot` to the provider and `snapshot` to the handle.
+- `fork`: add `fork` to the handle.
+
+The [capability table](./providers#capabilities) has the other flags. A call to an
+optional feature that you do not support throws `UnsupportedCapabilityError`, as
+`ports.connect` does above.
+
+## 3. Prove it with the conformance suites
+
+`@tanstack/ai-sandbox/testkit` has three suites that run against a real sandbox:
+
+- `runJournalConformance`: the shell runs `>>` and `tail -f`. On a killable provider, `kill()` stops the process inside the sandbox.
+- `runTakeoverConformance`: a second host takes over a run and gets the rest of the output once, with no duplicate lines.
+- `runReaperConformance`: the sweeps delete the journals that they must delete and keep the others. They never touch a run that still writes output.
+
+The suites import `vitest`, so add it to your dev dependencies. Then add one test
+file for each suite:
+
+```ts
+// tests/journal.conformance.test.ts
+import { runJournalConformance } from '@tanstack/ai-sandbox/testkit'
+import { myVmSandbox } from '../src'
+
+runJournalConformance({
+  name: 'my-vm',
+  createHandle: async () => {
+    const handle = await myVmSandbox().create({})
+    return { handle, dispose: () => handle.destroy() }
+  },
+  // killableProcesses is false, so the journal reads in a loop.
+  followUnsupported: { reason: 'kill() is not measured yet' },
+})
+```
+
+`runTakeoverConformance` and `runReaperConformance` take the same `name` and
+`createHandle`. Each suite also takes declarations. Add one only if it is true for
+your provider:
+
+- `followUnsupported`: on the journal and reaper suites, when `backgroundProcesses` or `killableProcesses` is `false`. The suites compare it to a live sandbox, so a wrong value fails.
+- `mtimeListUnsupported`: on the reaper suite, when the shell has no GNU `stat -c`. Then the age-gate cases skip.
+- `unsupported`: on any suite, when the provider cannot do what the suite needs.
+
+A declaration puts your reason in the test output, so a missing feature never shows
+as a silent pass. Use `unsupported` for a missing API key too:
+
+```ts
+// tests/takeover.conformance.test.ts
+import { runTakeoverConformance } from '@tanstack/ai-sandbox/testkit'
+import { myVmSandbox } from '../src'
+
+const apiKey = process.env.MY_VM_API_KEY
+
+runTakeoverConformance({
+  name: 'my-vm',
+  createHandle: async () => {
+    const handle = await myVmSandbox().create({})
+    return { handle, dispose: () => handle.destroy() }
+  },
+  ...(apiKey
+    ? {}
+    : { unsupported: { reason: 'no MY_VM_API_KEY in the environment' } }),
+})
+```
+
+Run them with `npx vitest run tests`. Each case starts a real sandbox and a real agent
+process, so the suites give a case up to 3 minutes before it fails.
+
+## 4. Use it
+
+Give the provider to `defineSandbox`, the same as a bundled one:
+
+```ts
+import { defineSandbox } from '@tanstack/ai-sandbox'
+import { myVmSandbox } from './my-vm-sandbox'
+
+export const repoSandbox = defineSandbox({
+  id: 'bug-fixer',
+  provider: myVmSandbox(),
+})
+```
+
+## What you have now
+
+- A provider that runs the agent on your own platform.
+- Capability flags that you measured, so the journal and cancel do the right thing.
+- Conformance suites that fail when the provider breaks a promise.
+
+Next: keep runs alive through a lost connection with [Durable Runs](./durable-runs).
diff --git a/docs/sandbox/providers.md b/docs/sandbox/providers.md
index b968c77ed7..30cc4adf8b 100644
--- a/docs/sandbox/providers.md
+++ b/docs/sandbox/providers.md
@@ -554,6 +554,9 @@ Use the flags to write provider-agnostic code: branch on the capability rather
 than the concrete provider, and your sandbox definition keeps working when you
 swap one provider for another.
 
+To run sandboxes on a platform that is not in this list, write your own provider.
+See [Build a Sandbox Provider](./build-a-provider).
+
 ### `killableProcesses` across the bundled providers
 
 This flag is **measured, not asserted**. A wrong `true` hands the journal reader

From c9f8e5f901f82e5dcba3dbd505d7ee2ab9e110e3 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 12:39:16 +0200
Subject: [PATCH 220/286] chore: add changesets for the harness report fixes

---
 .changeset/fake-text-fixes.md              |  9 +++++++++
 .changeset/harness-auth-wait.md            | 11 +++++++++++
 .changeset/harness-cli-host-principal.md   |  9 +++++++++
 .changeset/harness-input-sender-context.md | 20 ++++++++++++++++++++
 .changeset/harness-resolve-fixes.md        |  9 +++++++++
 .changeset/harness-run-route.md            | 11 +++++++++++
 .changeset/harness-turn-lifetime.md        |  9 +++++++++
 .changeset/harness-view-client-tools.md    |  9 +++++++++
 8 files changed, 87 insertions(+)
 create mode 100644 .changeset/fake-text-fixes.md
 create mode 100644 .changeset/harness-auth-wait.md
 create mode 100644 .changeset/harness-cli-host-principal.md
 create mode 100644 .changeset/harness-input-sender-context.md
 create mode 100644 .changeset/harness-resolve-fixes.md
 create mode 100644 .changeset/harness-run-route.md
 create mode 100644 .changeset/harness-turn-lifetime.md
 create mode 100644 .changeset/harness-view-client-tools.md

diff --git a/.changeset/fake-text-fixes.md b/.changeset/fake-text-fixes.md
new file mode 100644
index 0000000000..6ae92927c4
--- /dev/null
+++ b/.changeset/fake-text-fixes.md
@@ -0,0 +1,9 @@
+---
+'@tanstack/ai': patch
+---
+
+Fix three problems in `fakeText` from `@tanstack/ai/testing`.
+
+- `fakeText()` type-checks as a text adapter with `exactOptionalPropertyTypes: true`. `inputModalities` is now an optional property.
+- `RUN_STARTED` carries `parentRunId` when the call has one, as real adapters do.
+- Tool call ids are unique across `fakeText()` instances. The default id is now `fake-call-<fake>-<call>-<index>`.
diff --git a/.changeset/harness-auth-wait.md b/.changeset/harness-auth-wait.md
new file mode 100644
index 0000000000..6fd2943054
--- /dev/null
+++ b/.changeset/harness-auth-wait.md
@@ -0,0 +1,11 @@
+---
+'@tanstack/ai': patch
+'@tanstack/ai-harness': minor
+---
+
+A turn can wait for a sign-in and then go on.
+
+- `ctx.credentials.require(id, { wait: true })`, and `token({ wait: true })` in an `oauthConnector`, stop the running chat turn with an interrupt whose `reason` is `'auth_required'`. Its payload has the connector id.
+- When the credential is saved (the `connect:<id>` command, `/connect`, or `ctx.credentials.set`), the same turn goes on and the tool runs again. No new prompt is needed. On a durable host this also works after a restart.
+- A resolve with `status: 'cancelled'` gives up: the tool fails as it does without `wait`.
+- In `@tanstack/ai`, a tool that throws the MCP input-required shape can set the interrupt `reason`. MCP interrupts still use `'mcp_input'`.
diff --git a/.changeset/harness-cli-host-principal.md b/.changeset/harness-cli-host-principal.md
new file mode 100644
index 0000000000..847c04b490
--- /dev/null
+++ b/.changeset/harness-cli-host-principal.md
@@ -0,0 +1,9 @@
+---
+'@tanstack/ai-harness-cli': minor
+---
+
+`runCli(harness, { host, principal })` can use your own host and user.
+
+- `host`: the CLI uses this host and does not close it. Without it, the CLI makes its own host and closes it at the end.
+- `principal`: every session the CLI opens runs as this principal, and `--serve` gives it to each request with the token. The default is still `{ id: 'cli' }`.
+- `host` and `persistence` together fail with "Give runCli a host or persistence, not both."
diff --git a/.changeset/harness-input-sender-context.md b/.changeset/harness-input-sender-context.md
new file mode 100644
index 0000000000..779bd73393
--- /dev/null
+++ b/.changeset/harness-input-sender-context.md
@@ -0,0 +1,20 @@
+---
+'@tanstack/ai-harness': minor
+'@tanstack/ai-persistence': patch
+'@tanstack/ai-mcp': patch
+---
+
+Each harness input carries its sender and its context.
+
+- `prompt`, `steer`, `followUp` and `resolve` take `principal`. Without it, the input belongs to the principal that opened the session. `createHarnessHandler` and `handleHarnessSocket` run each input, and each command, as the principal that `authorize` returned for its request.
+- The log keeps the sender of each input. The turn's tools, `ctx.session.principal`, `ctx.credentials` and `ctx.keys` use the turn's sender. A turn that waits for a sign-in continues only when its sender signs in.
+- `turn.canJoin` gets the `principal` of each waiting input and the `turnPrincipal` of the running turn, so it can keep one person's message out of another person's turn. The `routing.router` context gets `principal` and `context`.
+- 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, as its sender.
+- A command acts for the person who runs it: its `session.principal` is that person, and `session.prompt` from a command runs as that person. The wake turn after a background agent runs as the person who started the agent.
+- `Principal.tenantId` goes into the credential scope, so two organizations' credentials for one user stay apart.
+- A credential read finds the user's own credential first, then the tenant's (saved without a `userId`), so one key can serve a whole organization. Saves and deletes change the user's own credential only.
+- `prompt`, `steer` and `followUp` take `context`: JSON data from the client, stored with the input and kept after a restart. `POST run` fills it from AG-UI `forwardedProps`. Tools get it merged with `HarnessConfig.context`, and the harness value wins for a key in both.
+- A plugin `adapter(turn)` gets `TurnInfo`: the turn's `message`, `context`, `principal`, `inputId` and `overrides`. A plugin with `lifetime: 'turn'` gets the same as `ctx.turn` in `setup`.
+- `CommandContext` has `principal` and `credentials` of the principal that ran the command.
+- In `@tanstack/ai-persistence`, a stored input's `principal` can carry `tenantId`.
+- `mcpConnector` keeps its sign-in state, client and tools per sender, so one person's MCP sign-in is not used for another person's turn.
diff --git a/.changeset/harness-resolve-fixes.md b/.changeset/harness-resolve-fixes.md
new file mode 100644
index 0000000000..c5f1196b53
--- /dev/null
+++ b/.changeset/harness-resolve-fixes.md
@@ -0,0 +1,9 @@
+---
+'@tanstack/ai-harness': patch
+---
+
+Fix three bugs in how a harness session answers interrupts and steers.
+
+- A resolve whose payload fails validation (for example a client tool result that does not match its `outputSchema`) no longer drops the pause. The resolve still settles `failed`, but the interrupt stays pending, so a correct resolve continues the turn.
+- A resolve sent as soon as a client reads `RUN_FINISHED` with interrupts is now accepted. Before, it was rejected with `no_pending_interrupts` or `busy` while the turn was still ending. The resolve now runs right after the interrupted turn ends.
+- `prompt(text, { busy: 'steer' })` that joins the running turn now returns the running turn's id in its receipt, as `steer()` does.
diff --git a/.changeset/harness-run-route.md b/.changeset/harness-run-route.md
new file mode 100644
index 0000000000..35a2e954a9
--- /dev/null
+++ b/.changeset/harness-run-route.md
@@ -0,0 +1,11 @@
+---
+'@tanstack/ai-harness': minor
+---
+
+`ChatClient` and `useChat` work with the harness handler's `POST run` route.
+
+- A turn started by `POST run` runs as the request's `runId`, so a `ChatClient` can answer its approvals and client tools. A retry with the same `runId` runs once. The same `runId` with another message gets 409.
+- `GET run?threadId=` answers with the transcript, the running turn, and the waiting interrupts, as the hydrate data that a `ChatClient` with `persistence: true` reads.
+- `GET run?runId=` streams the turn with that run id from its first event, with each event's cursor as its SSE id. A reloaded `useChat` with `persistence: true` joins a running turn this way, and `Last-Event-ID` resumes the stream. `canAccess` decides who can join.
+- A question from `ctx.session.ask` during a turn arrives on that turn's stream.
+- Each `snapshot().activeOperations` entry has `startedCursor`, so `events({ from: startedCursor })` reads a running operation from its first event.
diff --git a/.changeset/harness-turn-lifetime.md b/.changeset/harness-turn-lifetime.md
new file mode 100644
index 0000000000..653d0988f5
--- /dev/null
+++ b/.changeset/harness-turn-lifetime.md
@@ -0,0 +1,9 @@
+---
+'@tanstack/ai-harness': minor
+---
+
+Plugins and models per turn.
+
+- A plugin with `lifetime: 'turn'` is set up for each chat turn and disposed when the turn ends. `'run'` still works the same way, as an old name for `'turn'`.
+- `adapter` in `defineHarness` is optional. A plugin `adapter()` or the turn's `overrides.adapter` can give the model. A turn with no model fails with a clear error.
+- `harnessText(harness, { inputModalities })` sets the input kinds the harness takes, for a harness without an adapter.
diff --git a/.changeset/harness-view-client-tools.md b/.changeset/harness-view-client-tools.md
new file mode 100644
index 0000000000..488d2b1f57
--- /dev/null
+++ b/.changeset/harness-view-client-tools.md
@@ -0,0 +1,9 @@
+---
+'@tanstack/ai-harness': minor
+---
+
+`createSessionView` from `@tanstack/ai-harness/view` now handles client tools and sign-ins that a turn waits for.
+
+- A client tool (a harness tool with no server implementation) is in the new `state.clientTools` list, not in `approvals`. Each item has `id`, `toolCallId`, `tool`, `args`, `resolve(output)` and `fail(message)`. A `clientTool` event fires for each new item.
+- The view sends one resume when every open approval and client tool has an answer.
+- A turn that waits for a sign-in (`credentials.require(id, { wait: true })`) shows in `state.signIns`, not in `approvals`, also after a reload.

From 4c12b1e89c9d272281cc48c582b419ac53aac02e Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 15:26:45 +0200
Subject: [PATCH 221/286] fix(ai-harness): pass the parent run of a queued
 resume turn

A `resume` input on an interrupted session queues a turn with
`parentRunId`, but `QueuedTurn` had no such field and the runner read
the parent only from `answers`. The build failed on the type, and
chat() rejected the resume: "Interrupt continuation requires
parentRunId to identify the interrupted run".

Declare the field and fall back to it in the runner.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-harness/src/session.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index f071421066..cd97554cd2 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -267,6 +267,8 @@ interface QueuedTurn {
   resume?: Array<RunAgentResumeItem>
   /** A resolve: the interrupted turn it answers. */
   answers?: InterruptedTurn
+  /** A `resume` input: the interrupted run it continues. */
+  parentRunId?: string
   inputId?: string
   /** The settings of this one turn. Kept in memory only, not in the log. */
   overrides?: TurnOverrides
@@ -2750,7 +2752,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           ? await this.userMessage(turn.message)
           : undefined
       let resume = turn.resume
-      let parentRunId = turn.answers?.runId
+      let parentRunId = turn.answers?.runId ?? turn.parentRunId
       const { chatPersistence, checkpoint } = this
       if (!chatPersistence || !checkpoint) {
         throw new Error('The session is not open yet.')

From 01a42c2cc4dea51abda4f568aeb3b262499fa7f9 Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Mon, 5 Oct 2026 13:28:50 +0000
Subject: [PATCH 222/286] ci: apply automated fixes

---
 packages/ai-harness/tests/view-client-tools.test.ts |  6 +++++-
 packages/ai-mcp/src/connector.ts                    |  4 +++-
 packages/ai-mcp/tests/connector.test.ts             |  5 +++--
 packages/ai/src/testing/fake-text.ts                |  3 +--
 testing/e2e/src/routeTree.gen.ts                    | 11 ++++++-----
 testing/e2e/tests/replay-adapter-parity.spec.ts     |  4 +++-
 6 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/packages/ai-harness/tests/view-client-tools.test.ts b/packages/ai-harness/tests/view-client-tools.test.ts
index 80e75fad81..87763be74e 100644
--- a/packages/ai-harness/tests/view-client-tools.test.ts
+++ b/packages/ai-harness/tests/view-client-tools.test.ts
@@ -86,7 +86,11 @@ describe('session view client tools', () => {
     expect(controls.at(-1)).toEqual({
       op: 'resolve',
       resume: [
-        { interruptId: call?.id, status: 'resolved', payload: { opened: true } },
+        {
+          interruptId: call?.id,
+          status: 'resolved',
+          payload: { opened: true },
+        },
       ],
     })
     expect(calls).toHaveLength(2)
diff --git a/packages/ai-mcp/src/connector.ts b/packages/ai-mcp/src/connector.ts
index de90ee921e..9b760d2690 100644
--- a/packages/ai-mcp/src/connector.ts
+++ b/packages/ai-mcp/src/connector.ts
@@ -214,7 +214,9 @@ export function mcpConnector(options: McpConnectorOptions) {
       // 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]) : ''
+        principal
+          ? JSON.stringify([principal.tenantId ?? null, principal.id])
+          : ''
       const close = async (connection: Connection | undefined) => {
         await connection?.client?.close().catch(() => {})
       }
diff --git a/packages/ai-mcp/tests/connector.test.ts b/packages/ai-mcp/tests/connector.test.ts
index ae8c5b34df..72d3cfb7d2 100644
--- a/packages/ai-mcp/tests/connector.test.ts
+++ b/packages/ai-mcp/tests/connector.test.ts
@@ -200,7 +200,6 @@ describe('mcpConnector', () => {
     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())
@@ -229,7 +228,9 @@ describe('mcpConnector', () => {
     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 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 =
diff --git a/packages/ai/src/testing/fake-text.ts b/packages/ai/src/testing/fake-text.ts
index deb64074b0..17a0f5a9f3 100644
--- a/packages/ai/src/testing/fake-text.ts
+++ b/packages/ai/src/testing/fake-text.ts
@@ -303,8 +303,7 @@ export class FakeTextAdapter<
     const toolCalls = response.toolCalls ?? []
     for (const [index, call] of toolCalls.entries()) {
       const toolCallId =
-        call.id ??
-        `fake-call-${this.instance}-${this.state.callCount}-${index}`
+        call.id ?? `fake-call-${this.instance}-${this.state.callCount}-${index}`
       yield {
         type: EventType.TOOL_CALL_START,
         toolCallId,
diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index f21e1321e0..86e17b4f3f 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -506,11 +506,12 @@ const ApiOpenaiImage25ModelsRoute = ApiOpenaiImage25ModelsRouteImport.update({
   path: '/api/openai-image-2-5-models',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiOpenaiMalformedToolArgumentsRoute = ApiOpenaiMalformedToolArgumentsRouteImport.update({
-  id: '/api/openai-malformed-tool-arguments',
-  path: '/api/openai-malformed-tool-arguments',
-  getParentRoute: () => rootRouteImport,
-} as any)
+const ApiOpenaiMalformedToolArgumentsRoute =
+  ApiOpenaiMalformedToolArgumentsRouteImport.update({
+    id: '/api/openai-malformed-tool-arguments',
+    path: '/api/openai-malformed-tool-arguments',
+    getParentRoute: () => rootRouteImport,
+  } as any)
 const ApiOpenaiCompletedResponseTextRoute =
   ApiOpenaiCompletedResponseTextRouteImport.update({
     id: '/api/openai-completed-response-text',
diff --git a/testing/e2e/tests/replay-adapter-parity.spec.ts b/testing/e2e/tests/replay-adapter-parity.spec.ts
index 2cd216f4e9..5d570c1f18 100644
--- a/testing/e2e/tests/replay-adapter-parity.spec.ts
+++ b/testing/e2e/tests/replay-adapter-parity.spec.ts
@@ -81,7 +81,9 @@ for (const scenario of ['replay-parity', 'replay-parity-cleanup']) {
     if (scenario === 'replay-parity-cleanup') {
       expect(JSON.stringify(wire)).not.toContain('Failed replay text')
       expect(JSON.stringify(wire)).not.toContain('orphan-result')
-      expect(body.requests.at(-1).body.instructions).toBe('Replay system prompt.')
+      expect(body.requests.at(-1).body.instructions).toBe(
+        'Replay system prompt.',
+      )
       expect(
         body.saved.some(
           (message: { role: string }) => message.role === 'system',

From af7274d6fbbbdbba4d91d52267fee7a69c3317a2 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 15:33:44 +0200
Subject: [PATCH 223/286] fix(ai-compaction): fail the compaction when the
 summary is empty

A summarizer that returned an empty summary (the model stopped with no
text) made summarizeOldest replace the history with an empty summary,
so the history was lost.

An empty or whitespace-only summary now fails the compaction. The
history stays, the compaction events carry the error, and no durable
record is written. Covered for the threshold, compactNext, durable and
after-turn paths, and end to end on the overflow retry path.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/compaction-empty-summary.md        |   5 +
 packages/ai-compaction/src/index.test.ts      | 116 ++++++++++++++++++
 packages/ai-compaction/src/index.ts           |  13 +-
 .../src/routes/api.compaction-durable-wire.ts |  33 ++++-
 .../e2e/tests/compaction-durable-wire.spec.ts |  27 ++++
 5 files changed, 186 insertions(+), 8 deletions(-)
 create mode 100644 .changeset/compaction-empty-summary.md

diff --git a/.changeset/compaction-empty-summary.md b/.changeset/compaction-empty-summary.md
new file mode 100644
index 0000000000..43b03fca34
--- /dev/null
+++ b/.changeset/compaction-empty-summary.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-compaction': patch
+---
+
+Fail a compaction when the summarizer returns an empty or whitespace-only summary. Before, `summarizeOldest` replaced the history with an empty summary, so the history was lost. Now the compaction fails like any failed strategy: the history stays, `compaction:ended` (or `onCompact` after the turn) carries the error, and no durable record is written. With `continueOnError`, the run sends the history as it is.
diff --git a/packages/ai-compaction/src/index.test.ts b/packages/ai-compaction/src/index.test.ts
index 5b39deb24a..48439fd6ba 100644
--- a/packages/ai-compaction/src/index.test.ts
+++ b/packages/ai-compaction/src/index.test.ts
@@ -1525,6 +1525,122 @@ describe('projectCompaction', () => {
   })
 })
 
+describe('an empty summary', () => {
+  const longList = () => [
+    withId(big('user'), 'm1'),
+    withId(big('assistant'), 'm2'),
+    withId(big('user'), 'm3'),
+    withId(big('assistant'), 'm4'),
+  ]
+  const EMPTY = 'The summarizer returned an empty summary.'
+  const blank = (summary: string) =>
+    summarizeOldest({ summarize: async () => summary, keepRecentTokens: 50 })
+
+  it.each(['', '  \n\t '])(
+    'fails the threshold compaction for %j and reports the error',
+    async (summary) => {
+      const mw = withCompaction({ maxTokens: 100, strategy: blank(summary) })
+      const { ctx, events } = recordingContext('beforeModel')
+      await expect(runOnConfig(mw, longList(), ctx)).rejects.toThrow(EMPTY)
+      expect(events.at(-1)?.value).toMatchObject({
+        reason: 'threshold',
+        messagesAfter: 4,
+        error: { message: EMPTY },
+      })
+    },
+  )
+
+  it('keeps the history with continueOnError', async () => {
+    const mw = withCompaction({
+      maxTokens: 100,
+      continueOnError: true,
+      strategy: blank(''),
+    })
+    const { ctx, events } = recordingContext('beforeModel')
+    expect(await runOnConfig(mw, longList(), ctx)).toBeUndefined()
+    expect(events.at(-1)?.value).toMatchObject({ error: { message: EMPTY } })
+  })
+
+  it('keeps the history on the compactNext path', async () => {
+    const mw = withCompaction({
+      maxTokens: 100_000,
+      auto: false,
+      continueOnError: true,
+      strategy: blank(''),
+    })
+    mw.compactNext('thread-1')
+    const { ctx, events } = recordingContext('beforeModel', {
+      threadId: 'thread-1',
+    })
+    expect(await runOnConfig(mw, longList(), ctx)).toBeUndefined()
+    expect(events.at(-1)?.value).toMatchObject({
+      reason: 'forced',
+      error: { message: EMPTY },
+    })
+  })
+
+  it('fails when one call of a turn cut is empty', async () => {
+    const mw = withCompaction({
+      maxTokens: 100,
+      strategy: summarizeOldest({
+        summarize: async (_messages, input) =>
+          input.turnPrefix ? '' : 'the gist',
+        keepRecentTokens: 50,
+        cut: 'turn',
+      }),
+    })
+    const list = [
+      big('user'),
+      big('assistant'),
+      big('user'),
+      big('assistant'),
+      big('assistant'),
+    ]
+    await expect(runOnConfig(mw, list)).rejects.toThrow(EMPTY)
+  })
+
+  it('writes no record on the durable path', async () => {
+    const appended: Array<unknown> = []
+    const mw = withCompaction({
+      maxTokens: 100,
+      durable: true,
+      continueOnError: true,
+      strategy: blank(''),
+    })
+    const { ctx, events } = durableContext(appended)
+    expect(await runOnConfig(mw, longList(), ctx)).toBeUndefined()
+    expect(appended).toEqual([])
+    expect(events.at(-1)?.value).toMatchObject({ error: { message: EMPTY } })
+  })
+
+  it('writes no record after the turn and reports the error', async () => {
+    const appended: Array<unknown> = []
+    const onCompact = vi.fn()
+    const mw = withCompaction({
+      maxTokens: 100,
+      contextWindow: 100,
+      countTokens: 'usage',
+      durable: true,
+      onCompact,
+      strategy: blank(''),
+    })
+    const { ctx } = durableContext(appended)
+    const list = longList().slice(0, 3)
+    ctx.messages = list
+    await mw.onUsage?.(ctx, tokenUsage(110, 10))
+    ctx.messages = longList()
+    await mw.onFinish?.(ctx, { finishReason: 'stop', duration: 0, content: '' })
+
+    expect(appended).toEqual([])
+    expect(onCompact).toHaveBeenCalledWith(
+      expect.objectContaining({
+        reason: 'after-turn',
+        error: { message: EMPTY },
+      }),
+    )
+  })
+})
+
 describe('after-turn check', () => {
   const finish: FinishInfo = { finishReason: 'stop', duration: 0, content: '' }
   const covered = () => [
diff --git a/packages/ai-compaction/src/index.ts b/packages/ai-compaction/src/index.ts
index b47ff226a4..bc20803c20 100644
--- a/packages/ai-compaction/src/index.ts
+++ b/packages/ai-compaction/src/index.ts
@@ -490,9 +490,16 @@ export function summarizeOldest(options: {
           ...input,
           signal: controller.signal,
         })
-        if (typeof result === 'string') return result
-        if (result.usage) ctx.addUsage(result.usage)
-        return result.summary
+        const summary = typeof result === 'string' ? result : result.summary
+        if (typeof result !== 'string' && result.usage) {
+          ctx.addUsage(result.usage)
+        }
+        // An empty summary would replace the history with nothing. Fail the
+        // compaction instead, so the history stays as it is.
+        if (summary.trim() === '') {
+          throw new Error('The summarizer returned an empty summary.')
+        }
+        return summary
       } catch (error) {
         controller.abort(error)
         throw error
diff --git a/testing/e2e/src/routes/api.compaction-durable-wire.ts b/testing/e2e/src/routes/api.compaction-durable-wire.ts
index bc525a5da9..82d18f8199 100644
--- a/testing/e2e/src/routes/api.compaction-durable-wire.ts
+++ b/testing/e2e/src/routes/api.compaction-durable-wire.ts
@@ -28,6 +28,9 @@ import type { AnyTextAdapter, ModelMessage } from '@tanstack/ai'
  *   overflow error, then `compactNext` and one retry: 4 calls.
  * - `parallel-tools`: the model calls 4 tools in one phase. Before the next
  *   call, `clearToolResults()` clears the oldest result and keeps 3: 2 calls.
+ * - `empty-summary-overflow`: like `error-overflow`, but the summary is empty.
+ *   The compaction fails, the history stays, and with `continueOnError` the
+ *   retry overflows again, so the turn fails with the overflow error: 4 calls.
  *
  * Each case then opens a second host on the same log and returns its
  * transcript, so the spec can check that a rebuild gives the same context.
@@ -45,6 +48,7 @@ type Case =
   | 'error-overflow'
   | 'turn-control'
   | 'parallel-tools'
+  | 'empty-summary-overflow'
 type Step = { text: string } | { error: string } | { tools: number }
 
 const SCRIPTS: Record<Case, Array<Step>> = {
@@ -66,6 +70,12 @@ const SCRIPTS: Record<Case, Array<Step>> = {
     { text: 'fits now' },
   ],
   'parallel-tools': [{ tools: 4 }, { text: 'All parts read.' }],
+  'empty-summary-overflow': [
+    { text: 'First response.' },
+    { error: OVERFLOW },
+    { text: '' },
+    { error: OVERFLOW },
+  ],
 }
 
 const PROMPTS: Record<Case, Array<string>> = {
@@ -73,6 +83,7 @@ const PROMPTS: Record<Case, Array<string>> = {
   'error-overflow': [LONG_PROMPT, LONG_PROMPT],
   'turn-control': ['first question OLD_DETAIL', 'second question'],
   'parallel-tools': ['Read parts 1 to 4.'],
+  'empty-summary-overflow': [LONG_PROMPT, LONG_PROMPT],
 }
 
 /** Each result is about 500 tokens, so 4 of them are over `maxTokens`. */
@@ -90,7 +101,8 @@ function caseOf(body: unknown): Case | undefined {
   return value === 'silent-overflow' ||
     value === 'error-overflow' ||
     value === 'turn-control' ||
-    value === 'parallel-tools'
+    value === 'parallel-tools' ||
+    value === 'empty-summary-overflow'
     ? value
     : undefined
 }
@@ -262,9 +274,20 @@ function compactionFor(testCase: Case, adapter: AnyTextAdapter) {
     auto: false,
     durable: true,
     strategy: summarizeOldest({ summarize, keepRecentTokens: 20_000 }),
+    // A failed compaction sends the list as it is, so the retry fails with
+    // the overflow error and not with an emptied context.
+    ...(testCase === 'empty-summary-overflow' ? { continueOnError: true } : {}),
   })
 }
 
+/** The reasons of the compaction records in the log of the thread. */
+async function recordReasons(log: ReturnType<typeof memoryLogStore>) {
+  const entries = await log.read(THREAD, { after: 0 })
+  return entries
+    .filter((entry) => entry.record.type === COMPACTION_RECORD_TYPE)
+    .map((entry) => entry.record.reason)
+}
+
 export const Route = createFileRoute('/api/compaction-durable-wire')({
   server: {
     handlers: {
@@ -311,6 +334,9 @@ export const Route = createFileRoute('/api/compaction-durable-wire')({
           return Response.json({
             ok: false,
             error: error instanceof Error ? error.message : String(error),
+            calls: bodies.length,
+            records: await recordReasons(persistence.stores.log),
+            lastRequest: bodies.at(-1),
           })
         } finally {
           await first.close()
@@ -326,16 +352,13 @@ export const Route = createFileRoute('/api/compaction-durable-wire')({
           await second.close()
         }
 
-        const entries = await persistence.stores.log.read(THREAD, { after: 0 })
         return Response.json({
           ok: true,
           calls: bodies.length,
           texts,
           transcript,
           rebuilt,
-          records: entries
-            .filter((entry) => entry.record.type === COMPACTION_RECORD_TYPE)
-            .map((entry) => entry.record.reason),
+          records: await recordReasons(persistence.stores.log),
           lastRequest: bodies.at(-1),
         })
       },
diff --git a/testing/e2e/tests/compaction-durable-wire.spec.ts b/testing/e2e/tests/compaction-durable-wire.spec.ts
index 917774d7ef..5a76a50916 100644
--- a/testing/e2e/tests/compaction-durable-wire.spec.ts
+++ b/testing/e2e/tests/compaction-durable-wire.spec.ts
@@ -22,7 +22,34 @@ const Result = z.object({
   }),
 })
 
+const Failed = z.object({
+  ok: z.literal(false),
+  error: z.string(),
+  calls: z.number(),
+  records: z.array(z.string()),
+  lastRequest: z.unknown(),
+})
+
 test.describe('compaction: durable records in a harness session', () => {
+  test('an empty summary keeps the history, and the overflow error fails the turn', async ({
+    request,
+  }) => {
+    const response = await request.post('/api/compaction-durable-wire', {
+      data: { case: 'empty-summary-overflow' },
+    })
+    expect(response.ok()).toBe(true)
+    const json: unknown = await response.json()
+    const result = Failed.parse(json)
+
+    expect(result.error).toContain('exceeds the context window')
+    expect(result.calls).toBe(4)
+    expect(result.records).toEqual([])
+    // The retry got the whole history, not an empty summary.
+    const sent = JSON.stringify(result.lastRequest)
+    expect(sent).toContain('First response.')
+    expect(sent).not.toContain('untrusted-conversation-summary')
+  })
+
   async function run(request: APIRequestContext, testCase: string) {
     const response = await request.post('/api/compaction-durable-wire', {
       data: { case: testCase },

From 581efd816c3b3389ad3ef55e09c6e05901aafafe Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 15:43:15 +0200
Subject: [PATCH 224/286] fix(ai-harness): keep a host record from the last
 model call of a turn

A host record appended during the last model call of a turn with a tool
phase was lost at the end of the turn. withPersistence tags the run on
older messages, so the engine save is not an extension of what the
engine held, and the rebase returned only the engine list. The transcript
commit then removed the message the record had folded in.

The engine list still wins for older messages, and host messages that
the fold added after the engine's last save now stay after it.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/harness-keep-host-records.md       |  5 ++
 packages/ai-harness/src/log.ts                | 12 ++--
 .../ai-harness/tests/durable-session.test.ts  | 62 +++++++++++++++++++
 packages/ai-harness/tests/log.test.ts         |  7 ++-
 4 files changed, 79 insertions(+), 7 deletions(-)
 create mode 100644 .changeset/harness-keep-host-records.md

diff --git a/.changeset/harness-keep-host-records.md b/.changeset/harness-keep-host-records.md
new file mode 100644
index 0000000000..52313b3d58
--- /dev/null
+++ b/.changeset/harness-keep-host-records.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-harness': patch
+---
+
+Keep a host record that lands during the last model call of a turn. At the end of a turn, `withPersistence` tags older messages with the run, so the engine save rewrites them, and the log rebase then kept only the engine list. A host message that a record had folded in after the engine's last save was lost. Now the engine list still wins for the older messages, and the host messages that came after stay after it.
diff --git a/packages/ai-harness/src/log.ts b/packages/ai-harness/src/log.ts
index 9eb2050a4d..bfb36c82a7 100644
--- a/packages/ai-harness/src/log.ts
+++ b/packages/ai-harness/src/log.ts
@@ -1064,17 +1064,19 @@ export function engineMessageStore(options: {
    *   between a tool call and its result.
    * - A host record rewrote the fold (a compaction): the engine's new
    *   messages go after the rewritten fold.
-   * - The engine changed older messages itself (a compaction middleware):
-   *   `list` wins.
+   * - The engine changed older messages itself (a compaction middleware, or
+   *   the run tags of `withPersistence` at the end of a turn): `list` wins,
+   *   and host messages that the fold added after `base` stay after it.
    */
   const rebase = (base: Array<ModelMessage>, list: Array<ModelMessage>) => {
     const current = writer.state.messages
+    const isFoldExtension = commonPrefix(base, current) === base.length
+    const hostAdded = isFoldExtension ? current.slice(base.length) : []
     const isEngineExtension = commonPrefix(base, list) === base.length
-    if (!isEngineExtension) return list
+    if (!isEngineExtension) return [...list, ...hostAdded]
     const added = list.slice(base.length)
-    const isFoldExtension = commonPrefix(base, current) === base.length
     return isFoldExtension
-      ? [...base, ...added, ...current.slice(base.length)]
+      ? [...base, ...added, ...hostAdded]
       : [...current, ...added]
   }
   const engine = {
diff --git a/packages/ai-harness/tests/durable-session.test.ts b/packages/ai-harness/tests/durable-session.test.ts
index b6ed04d45d..f348b4303b 100644
--- a/packages/ai-harness/tests/durable-session.test.ts
+++ b/packages/ai-harness/tests/durable-session.test.ts
@@ -578,6 +578,68 @@ describe('LogRecordsCapability', () => {
     await host.close()
   })
 
+  it('keeps a record from the last model call of a turn with a tool phase', async () => {
+    const persistence = durablePersistence()
+    const lookup = toolDefinition({
+      name: 'lookup',
+      description: 'Look up the weather',
+    }).server(async () => 'sunny')
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('lookup', { city: 'Berlin' }, 'call-1'),
+      () => text('It is sunny.'),
+      () => text('a2'),
+    ])
+    let sent = false
+    // Like a state write of the app while the last model call streams.
+    const signal: ChatMiddleware = {
+      name: 'test:signal-in-last-call',
+      onChunk: async (ctx, chunk) => {
+        if (sent || chunk.type !== EventType.TEXT_MESSAGE_CONTENT) return
+        sent = true
+        await getLogRecords(ctx).append([
+          { type: 'app.signal', text: '[signal] saved' },
+        ])
+      },
+    }
+    const host = createHarnessHost({ persistence, project })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/log-records-tool-phase',
+        adapter,
+        tools: [lookup],
+        middleware: [signal],
+      }),
+      { threadId: THREAD },
+    )
+
+    await session.prompt('Weather in Berlin?')
+
+    // The end of the turn tags the run on older messages. The signal must
+    // stay in the fold, and a rebuild must give the same messages.
+    const transcript = await session.transcript()
+    expect(transcript.map((message) => message.content)).toContain(
+      '[signal] saved',
+    )
+    const entries = await persistence.stores.log.read(THREAD, { after: 0 })
+    expect(entries.some((entry) => entry.record.type === 'app.signal')).toBe(
+      true,
+    )
+    const rebuilt = sessionOf(
+      await loadLogState({
+        store: persistence.stores.log,
+        logId: THREAD,
+        project,
+      }),
+      THREAD,
+    )
+    expect(rebuilt.messages).toEqual(transcript)
+
+    // The next turn's model call gets it too.
+    await session.prompt('q2')
+    expect(messageTexts(calls[2])).toContain('[signal] saved')
+    await host.close()
+  })
+
   it('keeps the saved reply when a record lands from onFinish', async () => {
     const persistence = durablePersistence()
     const { adapter } = mockAdapter([() => text('a1')])
diff --git a/packages/ai-harness/tests/log.test.ts b/packages/ai-harness/tests/log.test.ts
index 6fee58c221..201156884c 100644
--- a/packages/ai-harness/tests/log.test.ts
+++ b/packages/ai-harness/tests/log.test.ts
@@ -626,7 +626,7 @@ describe('engine message store', () => {
     ])
   })
 
-  it('lets an engine save that changes older messages win', async () => {
+  it('lets an engine save that changes older messages win, and keeps a later host message', async () => {
     const { writer, engine } = await engineOnLog()
     await engine.loadThread(THREAD)
     await engine.saveThread(THREAD, [user('u1', 'one'), assistant('a1', 'two')])
@@ -634,7 +634,10 @@ describe('engine message store', () => {
 
     await engine.saveThread(THREAD, [assistant('s', 'engine summary')])
 
-    expect(writer.state.messages).toEqual([assistant('s', 'engine summary')])
+    expect(writer.state.messages).toEqual([
+      assistant('s', 'engine summary'),
+      { role: 'user', content: '[signal] late' },
+    ])
   })
 
   it('commits the engine list before a model call and changes it only for a host record', async () => {

From 71d5e933caebf8c724885de76a70f71d65e20c7e Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 15:53:22 +0200
Subject: [PATCH 225/286] test(ai-mcp): count both tools/list walks in the
 sender isolation test

tools() walks tools/list two times on a spec 2025 server: a raw walk,
then listTools() for the SDK's output checks. The new test for colliding
sender names expected one walk per sender, so it failed in CI. The
isolation itself holds: every request of a sender uses that sender's
token, and each sender initializes once.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-mcp/tests/connector.test.ts | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/packages/ai-mcp/tests/connector.test.ts b/packages/ai-mcp/tests/connector.test.ts
index 72d3cfb7d2..49c5210e76 100644
--- a/packages/ai-mcp/tests/connector.test.ts
+++ b/packages/ai-mcp/tests/connector.test.ts
@@ -290,7 +290,15 @@ describe('mcpConnector', () => {
     expect(model.toolNames(1)).toEqual(['demo_second_echo'])
     expect(model.toolNames(2)).toEqual(['demo_first_echo'])
     expect(initialized).toEqual(['first-token', 'second-token'])
-    expect(toolLists).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 () => {

From e677b751655573c1e50d02eeec70dbf1035f5bc2 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 16:23:39 +0200
Subject: [PATCH 226/286] fix(ai-harness): do not offer an interrupt again
 after its tool ran

The replay-parity merge rebuilt pending interrupts from the interrupt
store. withPersistence commits a resume only at a success boundary, so
when a resumed turn failed, stopped, or hit its time limit after the
approved tool ran, the approval came back and a second answer ran the
tool again.

A resume whose tools got a real result is now used up: the harness marks
the interrupts answered in the store, and the log scan of a durable host
skips an interrupt whose tool call has a later result. A cancelled call,
or the error result a stopped run gives a call it did not run, does not
count, so a resume stopped before its tool still stays open for a retry.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/harness-consume-ran-resume.md      |   5 +
 packages/ai-harness/src/session.ts            | 118 +++++++++++++++++-
 .../ai-harness/tests/durable-inputs.test.ts   |  24 ++--
 .../tests/interrupt-resolve.test.ts           |  45 +++++++
 .../tests/interrupt-restart.test.ts           |  48 +++++--
 packages/ai-harness/tests/view.test.ts        |  18 +--
 6 files changed, 218 insertions(+), 40 deletions(-)
 create mode 100644 .changeset/harness-consume-ran-resume.md

diff --git a/.changeset/harness-consume-ran-resume.md b/.changeset/harness-consume-ran-resume.md
new file mode 100644
index 0000000000..f8a2c0bbdd
--- /dev/null
+++ b/.changeset/harness-consume-ran-resume.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-harness': patch
+---
+
+Do not offer an approval or a client-tool interrupt again after its tool ran. When a resumed turn failed, stopped, or hit its time limit after the tool ran, the interrupt came back, and answering it again ran the tool a second time. Now the harness marks it answered in the interrupt store, and a durable host without an interrupt store skips it when it rebuilds from the log. A resume that stops before its tool runs stays open for a retry.
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index cd97554cd2..d997116495 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -12,6 +12,7 @@ import {
   maxIterations,
   modelMessagesToUIMessages,
   provideLogRecords,
+  readInterruptBinding,
   runAgentStream,
   validateWithStandardSchema,
 } from '@tanstack/ai'
@@ -373,6 +374,18 @@ const scopeOf = (
 })
 
 /** What the log and the inbox keep of a principal: its id and tenant. */
+/** The `metadata.tanstack` of a logged event, if it has one. */
+const tanstackOf = (event: Record<string, unknown>) =>
+  isRecord(event.metadata) && isRecord(event.metadata.tanstack)
+    ? event.metadata.tanstack
+    : undefined
+
+/** The tool call an interrupt waits on: an approval or a client tool. */
+const toolCallOf = (interrupt: Interrupt) => {
+  const binding = readInterruptBinding(interrupt)
+  return binding && 'toolCallId' in binding ? binding.toolCallId : undefined
+}
+
 const storedPrincipal = (principal: Principal | undefined) =>
   principal
     ? {
@@ -1708,6 +1721,25 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           )
             continue
           const event = record.event
+          // A later result of an interrupt's tool call: its resume ran, so it
+          // is used up, also when that turn failed after the tool.
+          if (
+            event.type === EventType.TOOL_CALL_RESULT &&
+            typeof event.toolCallId === 'string' &&
+            next !== undefined
+          ) {
+            if (!(await this.isRunResult(event, record.operationId))) continue
+            const remaining = next.interrupts.filter(
+              (interrupt) => toolCallOf(interrupt) !== event.toolCallId,
+            )
+            if (remaining.length !== next.interrupts.length) {
+              next =
+                remaining.length > 0
+                  ? { ...next, interrupts: remaining }
+                  : undefined
+            }
+            continue
+          }
           if (
             event.type !== EventType.RUN_FINISHED ||
             event.subagentRunId ||
@@ -1794,6 +1826,43 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }
   }
 
+  /**
+   * True when a logged tool result means its tool ran: it is not cancelled,
+   * and an error result does not come from a stopped run.
+   */
+  private async isRunResult(
+    event: Record<string, unknown>,
+    operationId: unknown,
+  ) {
+    const tanstack = tanstackOf(event)
+    if (tanstack?.toolResultOutcome === 'cancelled') return false
+    if (tanstack?.state !== 'output-error') return true
+    if (typeof operationId !== 'string') return false
+    const run = await this.persistence.stores.runs?.get(operationId)
+    return run !== null && run !== undefined && run.status !== 'aborted'
+  }
+
+  /**
+   * Mark the interrupts of `resume` answered in the interrupt store, the same
+   * way `withPersistence` commits them at a success boundary. Records that are
+   * no longer pending are left as they are.
+   */
+  private async consumeResume(resume: ReadonlyArray<RunAgentResumeItem>) {
+    const store = this.persistence.stores.interrupts
+    if (!store) return
+    for (const item of resume) {
+      const record = await store.get(item.interruptId)
+      if (record?.status !== 'pending' || record.threadId !== this.threadId) {
+        continue
+      }
+      if (item.status === 'resolved') {
+        await store.resolve(item.interruptId, item.payload)
+      } else {
+        await store.cancel(item.interruptId)
+      }
+    }
+  }
+
   /** Refresh even when a turn failed before its main try block. */
   private async refreshTurnInterrupts(
     operation: OperationImpl<unknown> | OperationImpl<ChatTurnResult>,
@@ -2622,6 +2691,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     let isRootPart = false
     /** chat() refused the resume of this turn, so it ran nothing. */
     let isResumeRefused = false
+    /** The tool calls of this turn that got a result, and an error result. */
+    const resultIds = new Set<string>()
+    const errorResultIds = new Set<string>()
     let text = ''
     let interrupts: Array<Interrupt> | undefined
     let failure: string | undefined
@@ -2964,6 +3036,15 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             // the result. Streamed text does not reset them, so a call that
             // fails after some text still counts.
             if (chunk.type === EventType.TOOL_CALL_RESULT) {
+              // A cancelled call gets a result too, but its tool did not run.
+              const tanstack = chunk.metadata?.tanstack
+              if (tanstack?.toolResultOutcome !== 'cancelled') {
+                if (tanstack?.state === 'output-error') {
+                  errorResultIds.add(chunk.toolCallId)
+                } else {
+                  resultIds.add(chunk.toolCallId)
+                }
+              }
               retries = 0
               textBefore = text
             }
@@ -3143,13 +3224,42 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             ...(turn.context !== undefined ? { context: turn.context } : {}),
           }
         : undefined
+    // A resume whose tools ran is used up, even when the turn fails after
+    // them. Offering its interrupts again would run the tools a second time.
+    // A resume that failed before its tools ran stays open for a retry.
+    const resumed = turn.resume ?? []
+    const resumedFrom = (turn.answers ?? this.interrupted)?.interrupts ?? []
+    const didResumedToolsRun =
+      !isResumeRefused &&
+      resumed.length > 0 &&
+      resumed.every((item) => {
+        const interrupt = resumedFrom.find(
+          (candidate) => candidate.id === item.interruptId,
+        )
+        const toolCallId = interrupt ? toolCallOf(interrupt) : undefined
+        if (toolCallId === undefined) return false
+        // A stopped run gives the calls it did not run an error result.
+        return (
+          resultIds.has(toolCallId) ||
+          (!operation.abortController.signal.aborted &&
+            errorResultIds.has(toolCallId))
+        )
+      })
+    // On a success, withPersistence committed them already, and this skips
+    // them. A failure or a stop can also come after the tools ran.
+    if (didResumedToolsRun) {
+      await this.consumeResume(resumed).catch((error: unknown) =>
+        this.warn(operation, 'harness:interrupts', error),
+      )
+    }
     await this.refreshTurnInterrupts(
       operation,
       observedInterrupts,
-      turn.resume !== undefined &&
-        failure === undefined &&
-        !isResumeRefused &&
-        !operation.abortController.signal.aborted,
+      didResumedToolsRun ||
+        (turn.resume !== undefined &&
+          failure === undefined &&
+          !isResumeRefused &&
+          !operation.abortController.signal.aborted),
     )
     if (this.logFailure) {
       if (releaseLease) await releaseLease()
diff --git a/packages/ai-harness/tests/durable-inputs.test.ts b/packages/ai-harness/tests/durable-inputs.test.ts
index fe845faf43..dfbb07224a 100644
--- a/packages/ai-harness/tests/durable-inputs.test.ts
+++ b/packages/ai-harness/tests/durable-inputs.test.ts
@@ -524,7 +524,7 @@ describe('settled() without a log', () => {
 })
 
 describe('durable approval recovery', () => {
-  it('keeps approval after a resume time limit and allows a later retry', async () => {
+  it('uses up the approval when a resume hits the time limit after its tool ran', async () => {
     const stores = memoryPersistence().stores
     const persistence = {
       stores: {
@@ -543,7 +543,6 @@ describe('durable approval recovery', () => {
     const main = mockAdapter([
       () => toolCall('remove', {}, 'timeout-approval'),
       untilAborted(),
-      () => text('Recovered.'),
     ])
     const config = defineHarness({
       name: 'approval-timeout',
@@ -566,20 +565,21 @@ describe('durable approval recovery', () => {
       outcome: 'failed',
       error: { code: 'timeout' },
     })
-    expect(session.snapshot().pendingInterrupts.map((item) => item.id)).toEqual(
-      [approval.id],
-    )
-    expect((await stores.interrupts.get(approval.id))?.status).toBe('pending')
+    // The approved tool ran before the time limit. Offering the approval
+    // again would run it a second time, so it is used up.
+    expect(execute).toHaveBeenCalledTimes(1)
+    expect(session.snapshot().pendingInterrupts).toEqual([])
+    expect((await stores.interrupts.get(approval.id))?.status).toBe('resolved')
     await host.close()
     const next = createHarnessHost({ persistence })
     const reopened = await next.open(config, { threadId: THREAD })
-    const retry = await reopened.resolve([
-      { interruptId: approval.id, status: 'resolved', payload: true },
-    ])
-    await expect(reopened.operation(retry.operationId ?? '')).resolves.toEqual({
-      text: 'Recovered.',
-    })
     expect(reopened.snapshot().pendingInterrupts).toEqual([])
+    expect(
+      await reopened.resolve([
+        { interruptId: approval.id, status: 'resolved', payload: true },
+      ]),
+    ).toMatchObject({ status: 'rejected', reason: 'no_pending_interrupts' })
+    expect(execute).toHaveBeenCalledTimes(1)
     await next.close()
   })
 
diff --git a/packages/ai-harness/tests/interrupt-resolve.test.ts b/packages/ai-harness/tests/interrupt-resolve.test.ts
index 7bebf7a24d..6739fc198d 100644
--- a/packages/ai-harness/tests/interrupt-resolve.test.ts
+++ b/packages/ai-harness/tests/interrupt-resolve.test.ts
@@ -169,6 +169,51 @@ describe.each([
     await host.close()
   })
 
+  it('does not bring the interrupt back after a restart when the turn failed after the resume ran', async () => {
+    const execute = vi.fn(async () => ({ ok: true }))
+    const deploy = toolDefinition({
+      name: 'deploy',
+      description: 'Deploy. Needs approval.',
+      needsApproval: true,
+      inputSchema: z.object({ env: z.string() }),
+    }).server(execute)
+    const { adapter } = mockAdapter([
+      () => toolCall('deploy', { env: 'prod' }),
+      fails,
+    ])
+    const harness = defineHarness({
+      name: 'test/late-failure-restart',
+      adapter,
+      tools: [deploy],
+    })
+    const persistence = persistenceFor(durable)
+    const first = createHarnessHost({ persistence })
+    const session = await first.open(harness, { threadId: 't1' })
+    const turn = await session.prompt('Deploy.')
+    const interruptId = turn.interrupts?.[0]?.id
+    if (!interruptId) throw new Error('The turn did not stop for approval.')
+    await session.resolve(
+      [{ interruptId, status: 'resolved', payload: true }],
+      { inputId: 'approve' },
+    )
+    expect(await session.settled('approve')).toMatchObject({
+      outcome: 'failed',
+    })
+    await first.close()
+
+    // A new host on the same storage, like a restart.
+    const second = createHarnessHost({ persistence })
+    const reopened = await second.open(harness, { threadId: 't1' })
+    expect(reopened.snapshot().pendingInterrupts).toEqual([])
+    expect(
+      await reopened.resolve([
+        { interruptId, status: 'resolved', payload: true },
+      ]),
+    ).toMatchObject({ status: 'rejected', reason: 'no_pending_interrupts' })
+    expect(execute).toHaveBeenCalledTimes(1)
+    await second.close()
+  })
+
   it('accepts a resolve sent on RUN_FINISHED, while the interrupted turn still ends', async () => {
     const execute = vi.fn(async () => ({ ok: true }))
     const deploy = toolDefinition({
diff --git a/packages/ai-harness/tests/interrupt-restart.test.ts b/packages/ai-harness/tests/interrupt-restart.test.ts
index f86bacafa4..2e6ab3fa99 100644
--- a/packages/ai-harness/tests/interrupt-restart.test.ts
+++ b/packages/ai-harness/tests/interrupt-restart.test.ts
@@ -508,8 +508,12 @@ describe.each([false, true])(
     )
 
     it.each(['provider', 'save'])(
-      'keeps approval after a pre-commit %s failure',
+      'after a pre-commit %s failure, keeps the approval only when its tool did not run',
       async (kind) => {
+        // The provider fails after the approved tool ran. Without a log, the
+        // save of the started turn fails before the tool. A durable host
+        // saves through the log, and that write fails after the tool ran.
+        const toolRan = kind === 'provider' || durable
         const stores = memoryPersistence().stores
         const log = memoryLogStore()
         const persistence = durable
@@ -570,17 +574,27 @@ describe.each([false, true])(
         await expect(
           session.operation(receipt.operationId ?? ''),
         ).rejects.toThrow()
-        expect(
-          session.snapshot().pendingInterrupts.map((item) => item.id),
-        ).toEqual([approval.id])
-        expect((await stores.interrupts.get(approval.id))?.status).toBe(
-          'pending',
-        )
-        expect(
-          await stores.metadata.get('harness:interrupted', THREAD),
-        ).toMatchObject({
-          interrupts: [expect.objectContaining({ id: approval.id })],
-        })
+        expect(remove.execute).toHaveBeenCalledTimes(toolRan ? 1 : 0)
+        if (toolRan) {
+          // Offering the approval again would run the tool a second time,
+          // so it is used up.
+          expect(session.snapshot().pendingInterrupts).toEqual([])
+          expect((await stores.interrupts.get(approval.id))?.status).toBe(
+            'resolved',
+          )
+        } else {
+          expect(
+            session.snapshot().pendingInterrupts.map((item) => item.id),
+          ).toEqual([approval.id])
+          expect((await stores.interrupts.get(approval.id))?.status).toBe(
+            'pending',
+          )
+          expect(
+            await stores.metadata.get('harness:interrupted', THREAD),
+          ).toMatchObject({
+            interrupts: [expect.objectContaining({ id: approval.id })],
+          })
+        }
         logWrite.mockRestore()
         save.mockRestore()
         await host.close()
@@ -591,6 +605,15 @@ describe.each([false, true])(
           expect(await reopened.settled(receipt.inputId)).toMatchObject({
             outcome: 'completed',
           })
+        } else if (toolRan) {
+          expect(
+            await reopened.resolve([
+              { interruptId: approval.id, status: 'resolved', payload: true },
+            ]),
+          ).toMatchObject({
+            status: 'rejected',
+            reason: 'no_pending_interrupts',
+          })
         } else {
           expect(
             reopened.snapshot().pendingInterrupts.map((item) => item.id),
@@ -603,6 +626,7 @@ describe.each([false, true])(
           ).resolves.toEqual({ text: 'Recovered.' })
         }
         expect(reopened.snapshot().pendingInterrupts).toEqual([])
+        expect(remove.execute).toHaveBeenCalledTimes(1)
         await next.close()
       },
     )
diff --git a/packages/ai-harness/tests/view.test.ts b/packages/ai-harness/tests/view.test.ts
index 53f685d4b8..6f8cf257ab 100644
--- a/packages/ai-harness/tests/view.test.ts
+++ b/packages/ai-harness/tests/view.test.ts
@@ -176,7 +176,7 @@ describe('createSessionView', () => {
     await host.close()
   })
 
-  it('reserves approval actions during a running resolve and restores them after failure', async () => {
+  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'),
@@ -185,13 +185,11 @@ describe('createSessionView', () => {
           await hold.opened
           throw new Error('provider failed before commit')
         })(),
-      () => text('Retried approval.'),
     ])
     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 id = view.store.get().approvals[0]?.id
     const resolve = vi.spyOn(session, 'resolve')
     view.approveAll()
     await vi.waitFor(() => expect(calls).toHaveLength(2))
@@ -201,16 +199,12 @@ describe('createSessionView', () => {
     expect(resolve).toHaveBeenCalledTimes(1)
     hold.open()
     await vi.waitFor(() => expect(errors.length).toBeGreaterThan(0))
-    await vi.waitFor(() =>
-      expect(view.store.get().approvals.map((item) => item.id)).toEqual([id]),
-    )
+    // 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()
-    await vi.waitFor(() =>
-      expect(JSON.stringify(view.store.get().messages)).toContain(
-        'Retried approval.',
-      ),
-    )
-    expect(resolve).toHaveBeenCalledTimes(2)
+    expect(resolve).toHaveBeenCalledTimes(1)
     view.dispose()
     await host.close()
   })

From 343c8fb3617db87f9a433dc3000911f8f8620b9c Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 18:00:00 +0200
Subject: [PATCH 227/286] feat(ai): add a durable step to the agent run context

Agent code gets ctx.step.do(name, fn). SubagentBinding takes an optional step, so a host can keep each step result and skip it when the agent runs again. Without a binding, step.do runs fn each time.
---
 .../ai/src/activities/chat/agents/bound.ts    | 18 +++++
 .../activities/chat/agents/define-agent.ts    | 10 ++-
 .../ai/src/activities/chat/agents/spawn.ts    |  6 +-
 packages/ai/src/activities/index.ts           |  1 +
 packages/ai/src/client.ts                     |  1 +
 packages/ai/src/index.ts                      |  1 +
 packages/ai/tests/agent-step.test.ts          | 65 +++++++++++++++++++
 7 files changed, 99 insertions(+), 3 deletions(-)
 create mode 100644 packages/ai/tests/agent-step.test.ts

diff --git a/packages/ai/src/activities/chat/agents/bound.ts b/packages/ai/src/activities/chat/agents/bound.ts
index c73117bc3e..b7c6c78df4 100644
--- a/packages/ai/src/activities/chat/agents/bound.ts
+++ b/packages/ai/src/activities/chat/agents/bound.ts
@@ -34,12 +34,30 @@ export interface SubagentForward {
   promptCache?: PromptCacheRetention
 }
 
+/** The steps of an agent run, as `ctx.step`. */
+export interface AgentStep {
+  /**
+   * Run `fn` for `name`, and return its value. When a host runs a stopped
+   * agent again (a harness agent started with `resume: true`), a finished
+   * step returns its stored value and `fn` does not run again. Without such a
+   * host, `fn` runs each time. The value must be JSON. Use a name that is the
+   * same on every run.
+   */
+  do: <T>(name: string, fn: () => T | Promise<T>) => Promise<T>
+}
+
 /**
  * What a host (for example a harness session) adds to every activity call an
  * agent makes through `ctx`. Apps using plain `chat({ subagents })` do not set
  * it.
  */
 export interface SubagentBinding {
+  /**
+   * The steps the agent reads as `ctx.step`. Only this agent run gets them,
+   * not the children it starts. Without them, `ctx.step.do` runs `fn` each
+   * time.
+   */
+  step?: AgentStep
   /**
    * Added before the call's own middleware on every `ctx.chat` call. A
    * child's `ctx.chat({ subagents })` passes it down to its own children.
diff --git a/packages/ai/src/activities/chat/agents/define-agent.ts b/packages/ai/src/activities/chat/agents/define-agent.ts
index 5cbb5d24a6..5f391dc7e9 100644
--- a/packages/ai/src/activities/chat/agents/define-agent.ts
+++ b/packages/ai/src/activities/chat/agents/define-agent.ts
@@ -10,7 +10,7 @@ import type {
   UIMessage,
 } from '../../../types'
 import type { AnyClientTool } from '../tools/tool-definition'
-import type { BoundActivities, SubagentForward } from './bound'
+import type { AgentStep, BoundActivities, SubagentForward } from './bound'
 import type { ProviderKeys } from '../../../byok/keyed'
 
 /**
@@ -60,10 +60,16 @@ export interface SubagentRunInput<
  *   `keyedAdapter(...)`. A host sets the keys. Without a host, they come
  *   from each provider's `env` names, and a missing key throws an error that
  *   names the env var.
+ * - `step.do(name, fn)` keeps a side effect from running twice when a host
+ *   runs the agent again after a crash. See {@link AgentStep}.
  */
 export type SubagentRunContext<TInput extends SchemaInput | undefined = any> =
   SubagentRunInput<TInput> &
-    BoundActivities & { forward: SubagentForward; keys: ProviderKeys }
+    BoundActivities & {
+      forward: SubagentForward
+      keys: ProviderKeys
+      step: AgentStep
+    }
 
 /**
  * What an agent makes. Informative: plugins use it to find an agent by the
diff --git a/packages/ai/src/activities/chat/agents/spawn.ts b/packages/ai/src/activities/chat/agents/spawn.ts
index af147aafa5..8a478938eb 100644
--- a/packages/ai/src/activities/chat/agents/spawn.ts
+++ b/packages/ai/src/activities/chat/agents/spawn.ts
@@ -29,7 +29,7 @@ import type {
 import { envProviderKeys } from '../../../byok/env-keys'
 import { createBoundActivities } from './bound'
 import { SubagentBudget } from './limits'
-import type { SubagentBinding } from './bound'
+import type { AgentStep, SubagentBinding } from './bound'
 import type { SubagentLimits } from './limits'
 import type {
   DefinedAgent,
@@ -537,10 +537,14 @@ function runContext(
       ...(binding?.promptCache ? { promptCache: binding.promptCache } : {}),
     },
     keys: binding?.keys ?? envProviderKeys,
+    step: binding?.step ?? runEachTime,
     ...createBoundActivities(agentName, input, abortController, binding),
   } satisfies SubagentRunContext
 }
 
+/** The steps of an agent run that no host can run again: `fn` runs each time. */
+const runEachTime: AgentStep = { do: async (_name, fn) => fn() }
+
 export async function* spawnAgentStream(
   agent: DefinedAgent,
   input: SubagentRunInput,
diff --git a/packages/ai/src/activities/index.ts b/packages/ai/src/activities/index.ts
index cb8568b91c..1bd16cca76 100644
--- a/packages/ai/src/activities/index.ts
+++ b/packages/ai/src/activities/index.ts
@@ -50,6 +50,7 @@ export {
 } from './chat/agents/define-agent'
 export type {
   BoundActivities,
+  AgentStep,
   SubagentBinding,
   SubagentForward,
 } from './chat/agents/bound'
diff --git a/packages/ai/src/client.ts b/packages/ai/src/client.ts
index df357fd0f9..3b06d55005 100644
--- a/packages/ai/src/client.ts
+++ b/packages/ai/src/client.ts
@@ -236,6 +236,7 @@ export {
 } from './activities/chat/agents/define-agent'
 export type {
   BoundActivities,
+  AgentStep,
   SubagentBinding,
   SubagentForward,
 } from './activities/chat/agents/bound'
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index 1f40cb586b..a61e72a13c 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -97,6 +97,7 @@ export {
 } from './activities/chat/agents/define-agent'
 export type {
   BoundActivities,
+  AgentStep,
   SubagentBinding,
   SubagentForward,
 } from './activities/chat/agents/bound'
diff --git a/packages/ai/tests/agent-step.test.ts b/packages/ai/tests/agent-step.test.ts
new file mode 100644
index 0000000000..9569ba434d
--- /dev/null
+++ b/packages/ai/tests/agent-step.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest'
+import { defineAgent } from '../src/activities/chat/agents/define-agent'
+import { spawnAgentStream } from '../src/activities/chat/agents/spawn'
+import type { AgentStep } from '../src/activities/chat/agents/bound'
+import type { SubagentRunInput } from '../src/activities/chat/agents/define-agent'
+
+const input: SubagentRunInput = {
+  input: undefined,
+  messages: [],
+  threadId: 't',
+  runId: 'r',
+  parentRunId: 'p',
+  subagentRunId: 's',
+}
+
+async function drain(stream: AsyncIterable<unknown>) {
+  for await (const _chunk of stream) {
+    // Run the agent to its end.
+  }
+}
+
+describe('ctx.step of an agent run', () => {
+  it('runs fn each time when no host gives steps', async () => {
+    let runs = 0
+    const agent = defineAgent({
+      name: 'counter',
+      description: 'Counts',
+      run: async (ctx) => ctx.step.do('count', () => (runs += 1)),
+    })
+
+    await drain(spawnAgentStream(agent, input))
+    await drain(spawnAgentStream(agent, input))
+
+    expect(runs).toBe(2)
+  })
+
+  it('uses the steps of the host binding', async () => {
+    const names: Array<string> = []
+    const step: AgentStep = {
+      do: async <T>(name: string) => {
+        names.push(name)
+        return 'stored' as T
+      },
+    }
+    let ran = false
+    let value: unknown
+    const agent = defineAgent({
+      name: 'charger',
+      description: 'Charges once',
+      run: async (ctx) => {
+        value = await ctx.step.do('charge', () => {
+          ran = true
+          return 'fresh'
+        })
+        return value
+      },
+    })
+
+    await drain(spawnAgentStream(agent, input, undefined, undefined, { step }))
+
+    expect(names).toEqual(['charge'])
+    expect(ran).toBe(false)
+    expect(value).toBe('stored')
+  })
+})

From bce32d6778a620fcb2086a7a5a494af17a067456 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 18:00:01 +0200
Subject: [PATCH 228/286] feat(ai-harness): usage totals, resumable agents,
 thread settings, fork, and reset

- session.usage() and snapshot().usage total each model call per model and per sender, with provider cost. A durable host keeps a harness.usage record per call. A harness.usage event fires on each call.
- agents.start(agent, input, { resume: true }) on a durable host: the host that takes over runs the agent again, its model calls continue from the saved transcript, and ctx.step.do results are not run again. durability.maxAttempts caps the runs.
- defineHarness({ models }) and session.configure() store the model, reasoning, instructions, tools, plugins, and working folder of a thread. A client can change only the fields in expose.settings.
- host.fork() copies a thread up to a message into a new thread, with its settings and media.
- session.reset(note?) starts a fresh model context and keeps the transcript, with a marker.
- A resolve that a crash interrupted continues the interrupted turn with its routed plan, sender, and context. On a host without a log, the transcript is saved before each model call, so a tool result stays when the next model call fails.
---
 packages/ai-harness/src/client.ts             |  15 +
 packages/ai-harness/src/commands.ts           |  14 +-
 packages/ai-harness/src/define.ts             |  16 +-
 .../ai-harness/src/first-party/workspace.ts   |  66 +-
 packages/ai-harness/src/host.ts               |  61 ++
 packages/ai-harness/src/index.ts              |   4 +
 packages/ai-harness/src/log.ts                |  13 +
 packages/ai-harness/src/plugins.ts            |  26 +-
 packages/ai-harness/src/protocol.ts           |  30 +
 packages/ai-harness/src/session.ts            | 902 +++++++++++++++++-
 packages/ai-harness/src/types.ts              |  51 +-
 packages/ai-harness/src/usage.ts              |  96 ++
 packages/ai-harness/src/view/reduce.ts        |  20 +
 .../ai-harness/tests/agent-resume.test.ts     | 192 ++++
 packages/ai-harness/tests/fork.test.ts        | 212 ++++
 packages/ai-harness/tests/reset.test.ts       | 349 +++++++
 .../ai-harness/tests/thread-settings.test.ts  | 489 ++++++++++
 packages/ai-harness/tests/usage.test.ts       | 257 +++++
 packages/ai-harness/tests/view-fixtures.ts    |   2 +
 19 files changed, 2739 insertions(+), 76 deletions(-)
 create mode 100644 packages/ai-harness/src/usage.ts
 create mode 100644 packages/ai-harness/tests/agent-resume.test.ts
 create mode 100644 packages/ai-harness/tests/fork.test.ts
 create mode 100644 packages/ai-harness/tests/reset.test.ts
 create mode 100644 packages/ai-harness/tests/thread-settings.test.ts
 create mode 100644 packages/ai-harness/tests/usage.test.ts

diff --git a/packages/ai-harness/src/client.ts b/packages/ai-harness/src/client.ts
index 531344c6db..d8ada4baca 100644
--- a/packages/ai-harness/src/client.ts
+++ b/packages/ai-harness/src/client.ts
@@ -13,6 +13,7 @@ import type {
   MediaRecord,
   Receipt,
   SessionEvent,
+  ThreadSettingsChange,
   UserInput,
 } from './types'
 
@@ -74,6 +75,13 @@ export interface HarnessClient<THarness extends AnyHarness> {
   command: (name: string, input?: unknown) => Promise<Receipt>
   /** Change a session setting. */
   setConfig: (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>
   /**
    * The session events from `from` (exclusive). Reconnects after a network
    * error and resumes from the last cursor. Ends when `signal` aborts.
@@ -326,6 +334,13 @@ export function createHarnessClient<THarness extends AnyHarness>(
     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 } : {}),
+      }),
     events,
     snapshot: () => read('snapshot'),
     transcript: () => read('transcript'),
diff --git a/packages/ai-harness/src/commands.ts b/packages/ai-harness/src/commands.ts
index d44810eff7..ad0d1cd930 100644
--- a/packages/ai-harness/src/commands.ts
+++ b/packages/ai-harness/src/commands.ts
@@ -1,7 +1,13 @@
 import type { InferSchemaType, ModelMessage, SchemaInput } from '@tanstack/ai'
 import type { CredentialsAccess } from './auth'
 import type { SessionSnapshot } from './session'
-import type { ChatTurnResult, Operation, Principal, Receipt } from './types'
+import type {
+  ChatTurnResult,
+  Operation,
+  Principal,
+  Receipt,
+  ThreadSettings,
+} from './types'
 
 /** A question a command asks the user. The host renders it from the schema. */
 export interface Question<TSchema extends SchemaInput | undefined = undefined> {
@@ -57,6 +63,12 @@ export interface PluginSessionApi {
   }) => void
   /** Change a session setting, the same as a client. Applies at the next turn. */
   setConfig: (key: string, value: unknown) => Promise<Receipt>
+  /**
+   * The stored settings of the thread (`session.configure`). Read them at
+   * each call, for example the working folder `cwd`: a change applies from
+   * the next turn.
+   */
+  settings: () => ThreadSettings
 }
 
 /** What a command handler receives besides its input. */
diff --git a/packages/ai-harness/src/define.ts b/packages/ai-harness/src/define.ts
index f54e6e6541..aed9753d54 100644
--- a/packages/ai-harness/src/define.ts
+++ b/packages/ai-harness/src/define.ts
@@ -17,7 +17,7 @@ import type { MediaOptions } from './media'
 import type { HarnessPlugin } from './plugins'
 import type { HarnessSession } from './session'
 import type { HarnessTurnOptions, RecoverHook } from './turn'
-import type { BusyPolicy, Principal, UserInput } from './types'
+import type { BusyPolicy, Principal, ThreadSettings, UserInput } from './types'
 
 /** The `subagents` option: the same as `chat({ subagents })`. */
 export type HarnessSubagents<TSubagents extends ReadonlyArray<AnyAgent>> = Omit<
@@ -125,6 +125,12 @@ export interface HarnessConfig<
    * turn that gets no model from any of them fails.
    */
   adapter?: TAdapter | KeyedAdapter<TAdapter>
+  /**
+   * Models a thread can pick by name with `session.configure({ model })`.
+   * The stored name picks the model of each turn, after `overrides.adapter`
+   * and before a plugin `adapter()`.
+   */
+  models?: Record<string, AnyTextAdapter | KeyedAdapter<AnyTextAdapter>>
   systemPrompts?: Array<SystemPrompt>
   tools?: ReadonlyArray<AnyTool>
   middleware?: ReadonlyArray<AnyChatMiddleware>
@@ -186,6 +192,14 @@ export interface HarnessConfig<
   /** What clients may call. Nothing is exposed by default. */
   expose?: {
     agents?: ReadonlyArray<TAgents[number]['name'] | TSubagents[number]['name']>
+    /**
+     * The thread settings a client may change with a `configure` input. An
+     * input with any other field is refused with `not_exposed`. Server code
+     * that calls `session.configure()` can change every field. `plugins` and
+     * `instructions` let a client turn off a plugin and write into the
+     * system prompt, so expose them only to clients you trust.
+     */
+    settings?: ReadonlyArray<keyof ThreadSettings>
   }
 }
 
diff --git a/packages/ai-harness/src/first-party/workspace.ts b/packages/ai-harness/src/first-party/workspace.ts
index 46b99b990d..901e0466d1 100644
--- a/packages/ai-harness/src/first-party/workspace.ts
+++ b/packages/ai-harness/src/first-party/workspace.ts
@@ -63,6 +63,11 @@ export interface OutsideAccess {
   ask: (message: string) => Promise<unknown>
   /** The permission mode of the session, for example `'bypass'`. */
   mode: () => unknown
+  /**
+   * The working folder of the thread, from `root` (the `cwd` setting of
+   * `session.configure`). Relative paths start there. Read at each call.
+   */
+  cwd?: () => string | undefined
 }
 
 /** Is `full` the folder `dir`, or a path in it? */
@@ -83,6 +88,11 @@ export function createWorkspaceTools(
   // that wait for an answer, by folder, so parallel calls ask once.
   const allowed: Array<string> = []
   const asking = new Map<string, Promise<boolean>>()
+  /** The working folder: `root`, or the thread's `cwd` in it. */
+  const here = () => {
+    const cwd = access?.cwd?.()
+    return cwd ? resolve(root, cwd) : root
+  }
 
   /** Ask once about `folder`. A yes allows it for the session. */
   const allow = (folder: string, message: string) => {
@@ -103,7 +113,7 @@ export function createWorkspaceTools(
    * workspace is refused, or needs the user's yes for its folder.
    */
   const reach = async (path: string, tool: string, kind: 'file' | 'folder') => {
-    const full = isAbsolute(path) ? resolve(path) : resolve(root, path)
+    const full = isAbsolute(path) ? resolve(path) : resolve(here(), path)
     const isAllowed = [root, ...allowed].some((dir) => within(dir, full))
     if (isAllowed) return full
     if (options.outside !== 'ask' || !access) {
@@ -300,27 +310,28 @@ export function createWorkspaceTools(
         required: ['command'],
       },
       replay: 'never',
-    }).server(
-      (args: unknown) =>
-        new Promise<string>((done) => {
-          exec(
-            stringArg(args, 'command'),
-            {
-              cwd: root,
-              timeout: options.bashTimeoutMs ?? 120_000,
-              maxBuffer: 10 * 1024 * 1024,
-            },
-            (error, stdout, stderr) => {
-              const code = error && 'code' in error ? error.code : 0
-              done(
-                clip(
-                  `exit code: ${String(code ?? 0)}\n${stdout}${stderr ? `\nstderr:\n${stderr}` : ''}`,
-                ),
-              )
-            },
-          )
-        }),
-    ),
+    }).server(async (args: unknown) => {
+      // The shell runs in the working folder, so it must be in the workspace.
+      const cwd = await reach('.', 'bash', 'folder')
+      return new Promise<string>((done) => {
+        exec(
+          stringArg(args, 'command'),
+          {
+            cwd,
+            timeout: options.bashTimeoutMs ?? 120_000,
+            maxBuffer: 10 * 1024 * 1024,
+          },
+          (error, stdout, stderr) => {
+            const code = error && 'code' in error ? error.code : 0
+            done(
+              clip(
+                `exit code: ${String(code ?? 0)}\n${stdout}${stderr ? `\nstderr:\n${stderr}` : ''}`,
+              ),
+            )
+          },
+        )
+      })
+    }),
   ]
   const prompt =
     options.outside === 'ask'
@@ -347,13 +358,22 @@ export function workspaceTools(options: WorkspaceToolsOptions) {
   return definePlugin({
     name: 'tanstack/workspace-tools',
     setup: (ctx) => {
+      // The working folder is the thread's `cwd` setting, read at each call.
+      const cwd = () => ctx.session.settings().cwd
       const { tools, prompt } = createWorkspaceTools(options, {
         ask: (message) => ctx.session.ask({ message }),
         mode: () => ctx.config.get('mode'),
+        cwd,
       })
+      const folder = () => {
+        const dir = cwd()
+        return dir
+          ? ` The working folder of this thread is ${resolve(options.root, dir)}. Relative paths start there.`
+          : ''
+      }
       return {
         tools,
-        prompts: [prompt],
+        prompts: [() => prompt + folder()],
         contribute: [
           PermissionRules.item({
             tool: 'read_file',
diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
index 48d28b2c38..e48a446c62 100644
--- a/packages/ai-harness/src/host.ts
+++ b/packages/ai-harness/src/host.ts
@@ -106,6 +106,20 @@ export interface OpenSessionOptions {
   promptCache?: PromptCacheOptions
 }
 
+export interface ForkSessionOptions {
+  /** The thread to copy. */
+  threadId: string
+  /** The new thread. It must have no messages yet. */
+  newThreadId: string
+  /**
+   * The id of the last message to copy. Default: the whole transcript. An id
+   * the thread does not have throws.
+   */
+  at?: string
+  /** Who opens the new thread, as in `open`. */
+  principal?: Principal
+}
+
 /** Runs sessions for one or more harnesses in this process. */
 export interface HarnessHost<TLogState = unknown> {
   /**
@@ -116,6 +130,22 @@ export interface HarnessHost<TLogState = unknown> {
     harness: THarness,
     options: OpenSessionOptions,
   ) => Promise<HarnessSession<THarness>>
+  /**
+   * Start a new thread as a copy of another one, and return its open
+   * session. It copies the transcript up to and including the message `at`,
+   * the media that those messages use, the stored settings, and the plugin
+   * config. It does not copy plugin state, pending interrupts, queued
+   * inputs, or running work. A `newThreadId` with messages is refused.
+   *
+   * @example
+   * ```ts
+   * const fork = await host.fork(assistant, { threadId: 't-1', newThreadId: 't-2', at: messageId })
+   * ```
+   */
+  fork: <THarness extends AnyHarness>(
+    harness: THarness,
+    options: ForkSessionOptions,
+  ) => Promise<HarnessSession<THarness>>
   /** Close every live session. */
   close: () => Promise<void>
   /**
@@ -293,6 +323,37 @@ export function createHarnessHost<TLogState = undefined>(
       }
       return session as Promise<HarnessSession<typeof harness>>
     },
+    async fork(harness, { threadId, newThreadId, at, principal }) {
+      if (newThreadId === threadId) {
+        throw new Error('A fork needs a new thread: newThreadId is threadId.')
+      }
+      const source = await host.open(harness, { threadId })
+      const transcript = await source.transcript()
+      const end =
+        at === undefined
+          ? transcript.length
+          : transcript.findIndex((message) => message.id === at) + 1
+      if (end === 0) {
+        throw new Error(
+          `Thread ${JSON.stringify(threadId)} has no message ${JSON.stringify(at)}.`,
+        )
+      }
+      const isUsed = logStore
+        ? (await logStore.read(newThreadId, { limit: 1 })).length > 0
+        : ((await persistence.stores.messages?.loadThread(newThreadId))
+            ?.length ?? 0) > 0
+      if (isUsed) {
+        throw new Error(
+          `Thread ${JSON.stringify(newThreadId)} is not empty. Fork into a new thread.`,
+        )
+      }
+      const fork = await host.open(harness, {
+        threadId: newThreadId,
+        ...(principal ? { principal } : {}),
+      })
+      await fork.adoptFork(source, transcript.slice(0, end))
+      return fork
+    },
     async close() {
       const live = await Promise.allSettled(sessions.values())
       await Promise.all(
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index d9f4909176..6c85e5c001 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -76,6 +76,7 @@ export type {
 
 export { createHarnessHost } from './host'
 export type {
+  ForkSessionOptions,
   HarnessHost,
   HarnessHostOptions,
   HarnessPersistence,
@@ -93,6 +94,7 @@ export type {
   SessionInspection,
   SessionSnapshot,
 } from './session'
+export type { SessionUsage, UsageCounts } from './usage'
 
 export type {
   FinishContext,
@@ -122,6 +124,8 @@ export type {
   Principal,
   Receipt,
   SessionEvent,
+  ThreadSettings,
+  ThreadSettingsChange,
   TurnInfo,
   TurnOverrides,
   UserInput,
diff --git a/packages/ai-harness/src/log.ts b/packages/ai-harness/src/log.ts
index bfb36c82a7..e33cb6e493 100644
--- a/packages/ai-harness/src/log.ts
+++ b/packages/ai-harness/src/log.ts
@@ -1,5 +1,6 @@
 import { EventType } from '@tanstack/ai'
 import { LogConflictError } from '@tanstack/ai-persistence'
+import { addUsage, emptyUsage, isSessionUsage } from './usage'
 import { isRecord } from './utils'
 import type { ModelMessage, StreamChunk } from '@tanstack/ai'
 import type {
@@ -16,6 +17,7 @@ import type {
   InputSettlement,
   SessionEvent,
 } from './types'
+import type { SessionUsage, UsageCall } from './usage'
 
 /** The records the harness writes to a session log. */
 export type HarnessRecord =
@@ -58,6 +60,7 @@ export type HarnessRecord =
       name: string
       value: unknown
     }
+  | ({ type: 'harness.usage' } & UsageCall)
 
 const HARNESS_RECORD_TYPES = new Set<string>([
   'harness.event',
@@ -71,6 +74,7 @@ const HARNESS_RECORD_TYPES = new Set<string>([
   'harness.tool.result',
   'harness.tool.started',
   'harness.tool.step',
+  'harness.usage',
 ])
 
 // The harness wrote every record of these types, so the fields are its own.
@@ -129,6 +133,8 @@ export interface LogState {
   started: Map<string, { name: string; replay: 'safe' | 'never' }>
   /** By {@link stepKey}. */
   steps: Map<string, unknown>
+  /** The usage of every model call of the thread. */
+  usage: SessionUsage
 }
 
 export function emptyLogState() {
@@ -139,6 +145,7 @@ export function emptyLogState() {
     toolResults: new Map(),
     started: new Map(),
     steps: new Map(),
+    usage: emptyUsage(),
   }
   return state
 }
@@ -287,6 +294,9 @@ export function foldEntry(
     case 'harness.tool.step':
       state.steps.set(stepKey(record.toolCallId, record.name), record.value)
       return
+    case 'harness.usage':
+      addUsage(state.usage, record)
+      return
   }
 }
 
@@ -388,6 +398,7 @@ function serialize(state: SharedLogState, versions: CheckpointVersions) {
         toolResults: [...session.toolResults.entries()],
         started: [...session.started.entries()],
         steps: [...session.steps.entries()],
+        usage: session.usage,
       },
     ]),
     reduced: state.reduced ?? null,
@@ -421,6 +432,8 @@ function parseSession(value: unknown, seq: number) {
         : [],
     ),
     steps: new Map(steps as Array<[string, unknown]>),
+    // A checkpoint from before usage totals has none.
+    usage: isSessionUsage(value.usage) ? value.usage : emptyUsage(),
   }
   return session
 }
diff --git a/packages/ai-harness/src/plugins.ts b/packages/ai-harness/src/plugins.ts
index e9761a9edd..df6a949e12 100644
--- a/packages/ai-harness/src/plugins.ts
+++ b/packages/ai-harness/src/plugins.ts
@@ -119,12 +119,14 @@ export interface PluginAgentActions {
     <TAgent extends AnyAgent>(
       agent: TAgent,
       input?: AgentInputOf<TAgent>,
-      options?: { wake?: boolean },
+      /** See `AgentStartOptions`. */
+      options?: { wake?: boolean; resume?: boolean },
     ): Operation<AgentResultOf<TAgent>>
     (
       name: string,
       input?: unknown,
-      options?: { wake?: boolean },
+      /** See `AgentStartOptions`. */
+      options?: { wake?: boolean; resume?: boolean },
     ): Operation<unknown>
   }
   /**
@@ -342,7 +344,12 @@ export interface MountedPlugins {
       provides: Array<string>
     }>
     tools: Array<{ name: string; owner: string }>
+    /** The owner of each item of `prompts`, at the same index. */
     prompts: Array<{ id: string; owner: string }>
+    /** The owner of each item of `middleware`, at the same index. */
+    middleware: Array<string>
+    /** The owner of each item of `adapters`, at the same index. */
+    adapters: Array<string>
   }
   middleware: Array<AnyChatMiddleware>
   /** Chat middleware for every agent run. See `PluginContributions`. */
@@ -413,6 +420,7 @@ const NO_SERVICES: PluginServices = {
     ask: unavailable('ctx.session'),
     authRequired: unavailable('ctx.session'),
     setConfig: unavailable('ctx.session'),
+    settings: unavailable('ctx.session'),
   },
   agents: {
     run: unavailable('ctx.agents.run') as PluginAgentActions['run'],
@@ -516,6 +524,8 @@ export async function mountPlugins(
   }))
   const prompts: Array<Owned<PluginPrompt>> = []
   const middleware: Array<AnyChatMiddleware> = []
+  const middlewareOwners: Array<string> = []
+  const adapterOwners: Array<string> = []
   const agentMiddleware: Array<AnyChatMiddleware> = []
   const generationMiddleware: Array<AnyGenerationMiddleware> = []
   const commands = new Map<string, { command: AnyCommand; owner: string }>()
@@ -655,7 +665,10 @@ export async function mountPlugins(
         }
         prompts.push({ value: section, owner: plugin.name })
       })
-      middleware.push(...(contributions.middleware ?? []))
+      for (const item of contributions.middleware ?? []) {
+        middleware.push(item)
+        middlewareOwners.push(plugin.name)
+      }
       agentMiddleware.push(...(contributions.agentMiddleware ?? []))
       generationMiddleware.push(...(contributions.generationMiddleware ?? []))
       for (const [name, command] of Object.entries(
@@ -686,7 +699,10 @@ export async function mountPlugins(
         }
         items.push({ value: item.value, owner: plugin.name })
       }
-      if (contributions.adapter) adapters.push(contributions.adapter)
+      if (contributions.adapter) {
+        adapters.push(contributions.adapter)
+        adapterOwners.push(plugin.name)
+      }
       if (contributions.discoverTools) {
         discoverers.push({
           discover: contributions.discoverTools,
@@ -781,6 +797,8 @@ export async function mountPlugins(
         id: entry.value.id,
         owner: entry.owner,
       })),
+      middleware: middlewareOwners,
+      adapters: adapterOwners,
     },
     capabilityBridge,
     values,
diff --git a/packages/ai-harness/src/protocol.ts b/packages/ai-harness/src/protocol.ts
index 6fc57b1a13..9e56830e90 100644
--- a/packages/ai-harness/src/protocol.ts
+++ b/packages/ai-harness/src/protocol.ts
@@ -45,6 +45,8 @@ const INPUT_OPS = new Set([
   'command',
   'answer',
   'config',
+  'configure',
+  'reset',
 ])
 
 /** Check the shape of a client input. Throws with a short reason. */
@@ -80,6 +82,17 @@ export function parseHarnessInput(value: unknown): HarnessInput {
   if (value.op === 'config' && typeof value.key !== 'string') {
     throw new Error('Invalid input: config needs a key.')
   }
+  // 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.inputId !== undefined && typeof value.inputId !== 'string') {
     throw new Error('Invalid input: inputId must be a string.')
   }
@@ -175,6 +188,23 @@ export async function applyInput(
       return session.answer(input.questionId, input.value)
     case 'config':
       return session.setConfig(input.key, 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 {
+          inputId: input.inputId ?? '',
+          status: 'rejected',
+          reason: 'not_exposed',
+        }
+      }
+      return session.configure(input.settings, id)
+    }
+    case 'reset':
+      return session.reset(input.note, id)
     case 'agent': {
       const exposed = (harness.expose?.agents ?? []).includes(input.agent)
       if (!exposed) {
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index d997116495..7d6b7ef93d 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -31,7 +31,7 @@ import {
   stepKey,
 } from './log'
 import { createMediaStore, mediaCapture, mediaMiddleware } from './media'
-import { mediaIdOf, mediaOfMessage } from './media-ref'
+import { mediaIdOf, mediaOfMessage, mediaPart } from './media-ref'
 import { OperationImpl } from './operation'
 import { mountPlugins } from './plugins'
 import {
@@ -42,6 +42,7 @@ import {
   repairTranscript,
 } from './resume'
 import { HARNESS_EVENTS, InputRejectedError } from './types'
+import { addUsage, callUsage, emptyUsage, isSessionUsage } from './usage'
 import type {
   AnyChatMiddleware,
   AnyTextAdapter,
@@ -85,6 +86,7 @@ import type { LeaseOptions } from './resume'
 import type { MediaStore } from './media'
 import type { PluginSessionApi, Question } from './commands'
 import type { ConfigOption } from './config'
+import type { SessionUsage, UsageCall } from './usage'
 import type {
   AgentInputOf,
   AgentRegistryView,
@@ -114,6 +116,8 @@ import type {
   Principal,
   Receipt,
   SessionEvent,
+  ThreadSettings,
+  ThreadSettingsChange,
   TurnInfo,
   TurnOverrides,
   UserInput,
@@ -137,6 +141,16 @@ export interface AgentStartOptions extends AgentRunOptions {
    * during the run.
    */
   wake?: boolean
+  /**
+   * On a durable host, when the host stops during the run, the host that
+   * takes over runs the agent again with the same input, instead of failing
+   * it. The agent code runs again from its start: put each side effect in
+   * `ctx.step.do(name, fn)`, so a finished step returns its stored value.
+   * Its `ctx.chat` calls continue from their saved transcript. After
+   * `durability.maxAttempts` runs (default 10), the run fails with
+   * `attempts_exhausted`. A host without `stores.log` throws at start.
+   */
+  resume?: boolean
 }
 
 type RunArgs<TAgent, TOptions> =
@@ -195,6 +209,8 @@ export interface SessionSnapshot {
   }>
   /** The state of each plugin that uses `ctx.state`, by plugin name. */
   plugins: Record<string, unknown>
+  /** The token usage of the thread, the same as `session.usage()`. */
+  usage: SessionUsage
   /** The cursor of the newest event. */
   cursor: Cursor
 }
@@ -226,6 +242,10 @@ export interface SessionDescription {
     option: ConfigOption
   }>
   tools: SessionInspection['tools']
+  /** The stored settings of the thread (`session.configure`). */
+  settings?: ThreadSettings
+  /** The names of `defineHarness({ models })`, for a model menu. */
+  models?: Array<string>
 }
 
 /** What the host hands a new session. */
@@ -282,6 +302,8 @@ interface QueuedTurn {
    * already, so only plugins and the router read it.
    */
   sentMessage?: UserInput
+  /** A `reset()`: it adds its marker to the transcript and runs no model. */
+  reset?: { note?: string }
 }
 
 /** The interrupts the last turn stopped for, and how a resolve continues it. */
@@ -306,6 +328,15 @@ interface InterruptedTurn {
 /** Where `stores.metadata` keeps the interrupted turn of each thread. */
 const INTERRUPTED = 'harness:interrupted'
 
+/** Where `stores.metadata` keeps the usage totals of a host without a log. */
+const USAGE = 'harness:usage'
+
+/**
+ * The key of a resumable agent run in the session log: its steps, and the
+ * tool results of its chat. Not a tool call id, so a turn never reads them.
+ */
+const agentKey = (inputId: string) => `agent:${inputId}`
+
 /** True for an interrupted turn as `stores.metadata` gives it back. */
 function isInterruptedTurn(value: unknown): value is InterruptedTurn {
   if (!isRecord(value) || typeof value.runId !== 'string') return false
@@ -427,6 +458,189 @@ function turnContext(harness: unknown, input: unknown) {
   return harness !== undefined ? harness : input
 }
 
+/** Where `stores.metadata` keeps the stored settings of each thread. */
+const SETTINGS = 'harness:settings'
+
+const SETTING_KEYS = new Set<string>([
+  'model',
+  'reasoning',
+  'instructions',
+  'tools',
+  'plugins',
+  'cwd',
+])
+
+const isNames = (value: unknown): value is Array<string> =>
+  Array.isArray(value) && value.every((item) => typeof item === 'string')
+
+/** The names a setting can point at: the harness models and plugins. */
+interface SettingNames {
+  models: ReadonlySet<string>
+  plugins: ReadonlySet<string>
+}
+
+/** One checked setting value. Throws with a short reason for a bad one. */
+function checkSetting(
+  key: string,
+  value: unknown,
+  names: SettingNames,
+): unknown {
+  if (key === 'model') {
+    if (typeof value === 'string' && names.models.has(value)) return value
+    throw new Error(
+      `Unknown model ${JSON.stringify(value)}. Add it to defineHarness({ models }).`,
+    )
+  }
+  if (key === 'instructions' || key === 'cwd') {
+    if (typeof value === 'string') return value
+    throw new Error(`The setting "${key}" must be a string.`)
+  }
+  if (key === 'reasoning') {
+    // chat() checks the level itself.
+    const isOption =
+      typeof value === 'string' ||
+      (isRecord(value) && typeof value.level === 'string')
+    if (isOption) return value
+    throw new Error('The setting "reasoning" must be a level or { level }.')
+  }
+  if (key === 'tools') {
+    if (isNames(value)) return [...value]
+    if (isRecord(value) && isNames(value.remove)) {
+      return { remove: [...value.remove] }
+    }
+    throw new Error(
+      'The setting "tools" must be a list of tool names or { remove: [names] }.',
+    )
+  }
+  // `plugins`
+  if (!isRecord(value) || !isNames(value.remove)) {
+    throw new Error('The setting "plugins" must be { remove: [plugin names] }.')
+  }
+  const unknown = value.remove.find((name) => !names.plugins.has(name))
+  if (unknown !== undefined) {
+    throw new Error(`Unknown plugin ${JSON.stringify(unknown)}.`)
+  }
+  return { remove: [...value.remove] }
+}
+
+/**
+ * `settings` with `change` applied: `null` clears a field, a missing field
+ * stays. Throws with a short reason for an unknown field or a bad value.
+ */
+function changeSettings(
+  settings: ThreadSettings,
+  change: unknown,
+  names: SettingNames,
+): ThreadSettings {
+  if (!isRecord(change)) throw new Error('The settings must be an object.')
+  const next: Record<string, unknown> = { ...settings }
+  for (const [key, value] of Object.entries(change)) {
+    if (!SETTING_KEYS.has(key)) {
+      throw new Error(`Unknown setting ${JSON.stringify(key)}.`)
+    }
+    if (value === null) delete next[key]
+    else if (value !== undefined) next[key] = checkSetting(key, value, names)
+  }
+  // `checkSetting` gave each field its type.
+  return next as ThreadSettings
+}
+
+/**
+ * `mounted` without what the `removed` plugins give a turn: their tools,
+ * prompts, middleware, adapter picks, discoverers, and preparers.
+ */
+function withoutPlugins(
+  mounted: MountedPlugins,
+  removed: ReadonlySet<string>,
+): MountedPlugins {
+  const { owners } = mounted
+  const toolOwners = new Map(
+    owners.tools.map((entry) => [entry.name, entry.owner]),
+  )
+  const isKept = (owner: string | undefined) =>
+    owner === undefined || !removed.has(owner)
+  return {
+    ...mounted,
+    tools: mounted.tools.filter((tool) => isKept(toolOwners.get(tool.name))),
+    prompts: mounted.prompts.filter((_prompt, index) =>
+      isKept(owners.prompts[index]?.owner),
+    ),
+    middleware: mounted.middleware.filter((_item, index) =>
+      isKept(owners.middleware[index]),
+    ),
+    adapters: mounted.adapters.filter((_pick, index) =>
+      isKept(owners.adapters[index]),
+    ),
+    discoverers: mounted.discoverers.filter((item) => isKept(item.owner)),
+    preparers: mounted.preparers.filter((item) => isKept(item.owner)),
+  }
+}
+
+/**
+ * The tools that the `tools` setting keeps: the listed ones, or all but the
+ * removed ones. The tools named in `keep` (the turn's own) always stay.
+ */
+function settingTools(
+  tools: Array<AnyTool>,
+  setting: ThreadSettings['tools'],
+  keep: ReadonlySet<string>,
+) {
+  if (setting === undefined) return tools
+  const isList = Array.isArray(setting)
+  const names = new Set(isList ? setting : setting.remove)
+  return tools.filter(
+    (tool) => keep.has(tool.name) || names.has(tool.name) === isList,
+  )
+}
+
+/**
+ * The transcript message of a `reset()`: a user message with
+ * `metadata.harness.reset`. Its content is the note, which the model sees
+ * first. The id comes from the input, so the marker goes in once.
+ */
+function resetMarker(inputId: string, note: string | undefined): ModelMessage {
+  return {
+    id: `reset-${inputId}`,
+    role: 'user',
+    content: note ?? '',
+    metadata: { harness: { reset: note !== undefined ? { note } : {} } },
+  }
+}
+
+const isResetMarker = (message: ModelMessage) =>
+  isRecord(message.metadata?.harness) &&
+  isRecord(message.metadata.harness.reset)
+
+/**
+ * What the model sees of `messages`: only the messages after the last reset
+ * marker. A marker with a note stays, as a plain user message. Returns
+ * `messages` itself when it has no marker.
+ */
+function resetContext(messages: Array<ModelMessage>): Array<ModelMessage> {
+  const at = messages.findLastIndex(isResetMarker)
+  const marker = messages[at]
+  if (!marker) return messages
+  const after = messages.slice(at + 1)
+  if (marker.content === '') return after
+  const { metadata: _reset, ...note } = marker
+  return [note, ...after]
+}
+
+/**
+ * Gives the model only the context after the last reset. It changes only
+ * what the adapter gets (`providerMessages`), so every save keeps the
+ * messages before the reset.
+ */
+const resetCut: AnyChatMiddleware = {
+  name: 'harness:reset',
+  onConfig: (ctx, config) => {
+    if (ctx.phase !== 'init' && ctx.phase !== 'beforeModel') return undefined
+    const messages = config.providerMessages ?? config.messages
+    const cut = resetContext(messages)
+    return cut === messages ? undefined : { providerMessages: cut }
+  },
+}
+
 /** A short transcript note about how an agent ended, for the next turn. */
 function referenceNote(
   agent: string,
@@ -618,6 +832,10 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
    * copy, so a resolve after a restart continues the turn too.
    */
   private interrupted: InterruptedTurn | undefined
+  /** The usage totals of a host without a log. A durable host folds the log. */
+  private usageTotals: SessionUsage = emptyUsage()
+  /** Saves of `usageTotals` to `stores.metadata`, one after the other. */
+  private usageSaved: Promise<unknown> = Promise.resolve()
   private activeResume = false
   private plugins: ReadonlyArray<HarnessPlugin> = []
   private sessionPlugins: MountedPlugins | undefined
@@ -630,6 +848,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   private readonly lease: LeaseOptions | undefined
   private readonly listeners = new Map<string, Set<(value: unknown) => void>>()
   private readonly configValues = new Map<string, unknown>()
+  /** The stored settings of this thread: `session.configure`. */
+  private threadSettings: ThreadSettings = {}
   private readonly questions = new Map<
     string,
     {
@@ -828,12 +1048,14 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         },
       )
       await this.loadConfig()
+      await this.loadSettings()
       await this.loadPluginState()
       await this.loadInterrupted()
       if (this.writer) {
         await this.recoverFromLog(this.writer)
         return
       }
+      await this.loadUsage()
       await this.recoverCrashedTurn()
       await this.recoverInbox()
     } catch (error) {
@@ -1170,6 +1392,44 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     return this.keep({ inputId, status, operationId: operation.id })
   }
 
+  /**
+   * Start a fresh model context. From the next turn, the model sees only
+   * `note` (when you give one) and what comes after the reset.
+   * `transcript()` keeps every message: the reset adds a user message with
+   * `metadata.harness.reset`, whose content is the note.
+   *
+   * While a turn runs, the reset waits and applies when that turn ends,
+   * before the next queued turn. A thread that waits for interrupts is
+   * refused with `'pending_interrupts'`: resolve them first. `principal` and
+   * `inputId` mean the same as in `prompt`.
+   */
+  async reset(
+    note?: string,
+    options?: { principal?: Principal; inputId?: string },
+  ): Promise<Receipt> {
+    const inputId = options?.inputId ?? createInputId()
+    const principal = options?.principal ?? this.principal
+    // An empty note is no note: the model never gets an empty message.
+    const text = note?.trim() ? note : undefined
+    const admission = await this.accept(
+      inputId,
+      { op: 'reset', ...(text !== undefined ? { note: text } : {}) },
+      principal,
+    )
+    if (admission !== 'new') return this.duplicateReceipt(inputId, admission)
+    const isRunning = this.activeTurn !== undefined
+    if (!isRunning && this.queue.length === 0 && this.interrupted) {
+      this.reject(inputId, 'pending_interrupts')
+      return { inputId, status: 'rejected', reason: 'pending_interrupts' }
+    }
+    const operation = this.queueReset(inputId, text, principal, 'front')
+    return this.keep({
+      inputId,
+      status: isRunning ? 'queued' : 'accepted',
+      operationId: operation.id,
+    })
+  }
+
   /**
    * Answer the interrupts of the last turn. One resume must answer every open
    * interrupt of that turn (the AG-UI rule). `principal` means the same as in
@@ -1299,7 +1559,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
    * How a chat input ended: `completed`, `failed`, `aborted`, or
    * `interrupted` (the turn waits for human input). It waits until the input
    * ends. On a durable host it reads the log, so it also works after a
-   * restart and from another host that opens the thread.
+   * restart and from another host that opens the thread. There it also
+   * takes the input id of an agent run from the log.
    *
    * Rejects with `InputRejectedError` when the session refused the input,
    * and with an error for an id this session does not know.
@@ -1345,6 +1606,23 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     return this.feed.read(options ?? {})
   }
 
+  /**
+   * The token usage of this thread: every model call of its turns, their
+   * subagents, and its agent runs, in total, by `provider/model`, and by
+   * sender. `cost` is the sum of what the providers reported. A durable host
+   * keeps the totals in the log, a host with `stores.metadata` keeps them
+   * there, and other hosts keep them in memory.
+   *
+   * @example
+   * ```ts
+   * const { total, bySender } = session.usage()
+   * console.log(total.totalTokens, bySender['user-1']?.cost)
+   * ```
+   */
+  usage(): SessionUsage {
+    return structuredClone(this.writer?.state.usage ?? this.usageTotals)
+  }
+
   snapshot(): SessionSnapshot {
     const active = [...this.operations.values()].filter(
       (operation) => !operation.isSettled(),
@@ -1379,6 +1657,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         }),
       ),
       plugins: { ...this.stateDoc },
+      usage: this.usage(),
       cursor: this.feed.head(),
     }
   }
@@ -1425,6 +1704,78 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     return answer
   }
 
+  /**
+   * @internal Start this new thread as a fork of `source`, before its first
+   * turn: `messages` with their media copied to this thread, and the stored
+   * settings and plugin config of `source`. `host.fork` calls it.
+   */
+  async adoptFork(
+    source: HarnessSession,
+    messages: ReadonlyArray<ModelMessage>,
+  ): Promise<void> {
+    // A media id belongs to one thread, so each file gets a copy here.
+    const copies = new Map<string, MediaRecord | null>()
+    const copy = async (id: string) => {
+      if (!copies.has(id)) {
+        const record = await source.getMedia(id)
+        copies.set(
+          id,
+          record &&
+            (await this.putMedia(await source.loadMedia(id), {
+              mimeType: record.mimeType,
+              name: record.name,
+            })),
+        )
+      }
+      return copies.get(id) ?? undefined
+    }
+    const forked: Array<ModelMessage> = []
+    for (const message of messages) {
+      const content = Array.isArray(message.content)
+        ? await Promise.all(
+            message.content.map(async (part) => {
+              const id = mediaIdOf(part)
+              const made = id === undefined ? undefined : await copy(id)
+              return made ? mediaPart(made) : part
+            }),
+          )
+        : message.content
+      const media = mediaOfMessage(message)
+      if (media.length === 0) {
+        forked.push({ ...message, content })
+        continue
+      }
+      const harness = {
+        ...message.metadata?.harness,
+        media: await Promise.all(
+          media.map(async (record) => (await copy(record.id)) ?? record),
+        ),
+      }
+      forked.push({
+        ...message,
+        content,
+        metadata: { ...message.metadata, harness },
+      })
+    }
+    await this.messages.saveThread(this.threadId, forked)
+    const { metadata } = this.persistence.stores
+    this.threadSettings = source.settings()
+    if (Object.keys(this.threadSettings).length > 0) {
+      await metadata?.set(SETTINGS, this.threadId, this.threadSettings)
+    }
+    for (const [key, value] of source.configValues) {
+      if (this.sessionPlugins?.config.has(key))
+        this.configValues.set(key, value)
+    }
+    if (this.configValues.size > 0) {
+      await metadata?.set(
+        'harness:config',
+        this.threadId,
+        Object.fromEntries(this.configValues),
+      )
+    }
+  }
+
   // ===========================
   // Config, commands, questions
   // ===========================
@@ -1479,6 +1830,64 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     return { inputId, status: 'accepted' }
   }
 
+  /** The stored settings of this thread. See `configure`. */
+  settings(): ThreadSettings {
+    return structuredClone(this.threadSettings)
+  }
+
+  /**
+   * Change the stored settings of this thread: the model by name (from
+   * `defineHarness({ models })`), `reasoning`, `instructions`, `tools`,
+   * `plugins`, and the working folder `cwd`. A field set to `null` is
+   * cleared, and a missing field stays. They apply from the next turn, and
+   * the turn's `overrides` win over them. `stores.metadata` keeps them.
+   *
+   * It is an input, so the log keeps who changed what (`principal`). An
+   * unknown field, model, or plugin, or a bad value, is rejected.
+   *
+   * @example
+   * ```ts
+   * await session.configure({ model: 'strong', instructions: 'Answer in French.' })
+   * ```
+   */
+  async configure(
+    settings: ThreadSettingsChange,
+    options?: { principal?: Principal; inputId?: string },
+  ): Promise<Receipt> {
+    const inputId = options?.inputId ?? createInputId()
+    const principal = options?.principal ?? this.principal
+    const admission = await this.accept(
+      inputId,
+      { op: 'configure', settings },
+      principal,
+    )
+    if (admission !== 'new') return this.duplicateReceipt(inputId, admission)
+    let next: ThreadSettings
+    try {
+      next = changeSettings(this.threadSettings, settings, this.settingNames())
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      this.reject(inputId, reason)
+      return this.keep({ inputId, status: 'rejected', reason })
+    }
+    await this.persistence.stores.metadata?.set(SETTINGS, this.threadId, next)
+    this.threadSettings = next
+    await this.applied(inputId, 'session')
+    this.feed.publish(
+      'session',
+      customEvent(HARNESS_EVENTS.settingsChanged, { settings: next }),
+    )
+    return this.keep({ inputId, status: 'accepted' })
+  }
+
+  /** The model and plugin names that a setting can use. */
+  private settingNames(): SettingNames {
+    return {
+      models: new Set(Object.keys(this.harness.models ?? {})),
+      plugins: new Set(this.plugins.map((plugin) => plugin.name)),
+    }
+  }
+
   /** The commands of this session, for hosts to list. */
   commands(): Array<{
     name: string
@@ -1510,6 +1919,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         ...entry,
       })),
       tools: this.inspect().tools,
+      settings: this.settings(),
+      models: Object.keys(this.harness.models ?? {}),
     } satisfies SessionDescription
   }
 
@@ -1616,6 +2027,37 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }
   }
 
+  /** Read the stored settings of this thread. */
+  private async loadSettings(): Promise<void> {
+    const stored = await this.persistence.stores.metadata?.get(
+      SETTINGS,
+      this.threadId,
+    )
+    if (!isRecord(stored)) return
+    const names = this.settingNames()
+    for (const [key, value] of Object.entries(stored)) {
+      try {
+        this.threadSettings = changeSettings(
+          this.threadSettings,
+          { [key]: value },
+          names,
+        )
+      } catch {
+        // A value the harness no longer takes (a removed model or plugin)
+        // is dropped.
+      }
+    }
+  }
+
+  /** Restore the usage totals that `stores.metadata` keeps for this thread. */
+  private async loadUsage(): Promise<void> {
+    const stored = await this.persistence.stores.metadata?.get(
+      USAGE,
+      this.threadId,
+    )
+    if (isSessionUsage(stored)) this.usageTotals = stored
+  }
+
   /** Restore the interrupted turn that `stores.metadata` keeps for this thread. */
   private async loadInterrupted(): Promise<void> {
     const stored = await this.persistence.stores.metadata?.get(
@@ -1994,6 +2436,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           customEvent(HARNESS_EVENTS.authRequired, { ...info }),
         ),
       setConfig: (key, value) => this.setConfig(key, value),
+      settings: () => this.settings(),
     }
   }
 
@@ -2189,6 +2632,15 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     this.drain()
   }
 
+  /**
+   * Where a turn that runs next goes: after a resolve that answers the turn
+   * that just ended, and after the resets that wait, in their order.
+   */
+  private frontOfQueue(): number {
+    const at = this.queue.findIndex((turn) => !turn.answers && !turn.reset)
+    return at < 0 ? this.queue.length : at
+  }
+
   private drain(): void {
     if (this.activeTurn || this.closing) return
     const next = this.queue.shift()
@@ -2308,6 +2760,68 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }
   }
 
+  /**
+   * Middleware that counts the usage of each model call of `operation` for
+   * `principal`. The count does not hold back the stream: chat() waits for it
+   * after the run.
+   */
+  private usageCounter(
+    operation: OperationImpl<unknown> | OperationImpl<ChatTurnResult>,
+    principal: Principal | undefined,
+  ): AnyChatMiddleware {
+    return {
+      name: 'harness:usage',
+      onUsage: (ctx, usage) => {
+        ctx.defer(
+          this.countUsage(operation, {
+            model: `${ctx.provider}/${ctx.model}`,
+            ...storedPrincipal(principal),
+            usage: callUsage(usage),
+          }),
+        )
+      },
+    }
+  }
+
+  /**
+   * Add one model call to the totals, and send a `harness.usage` event. A
+   * durable host writes a `harness.usage` record, and the log fold adds it.
+   */
+  private async countUsage(
+    operation: OperationImpl<unknown> | OperationImpl<ChatTurnResult>,
+    call: UsageCall,
+  ): Promise<void> {
+    try {
+      if (this.writer) {
+        await this.writer.append([{ type: 'harness.usage', ...call }])
+      } else {
+        addUsage(this.usageTotals, call)
+        const { metadata } = this.persistence.stores
+        if (metadata) {
+          const totals = structuredClone(this.usageTotals)
+          this.usageSaved = this.usageSaved.then(() =>
+            metadata.set(USAGE, this.threadId, totals),
+          )
+          await this.usageSaved
+        }
+      }
+    } catch (error) {
+      // A refused log append stops the session already. A failed metadata
+      // save keeps the totals in memory.
+      this.usageSaved = Promise.resolve()
+      this.warn(operation, 'harness:usage', error)
+      return
+    }
+    operation.publish(
+      customEvent(HARNESS_EVENTS.usage, {
+        model: call.model,
+        ...(call.principal ? { sender: call.principal.id } : {}),
+        usage: call.usage,
+        total: this.usage().total,
+      }),
+    )
+  }
+
   private isAbortRequested(inputId: string) {
     return (
       this.writer?.state.inputs.get(inputId)?.abortRequested === true ||
@@ -2422,9 +2936,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             ...joins,
             ...records,
           ])
-          // A retried call loads the saved transcript, so a host without a
-          // log saves it before each model call when the harness can retry.
-          if (!this.engine && this.harness.turn?.onModelError) {
+          // A host without a log saves the transcript before each model call,
+          // as a durable host commits it. A tool result is then kept when the
+          // call fails, so a retried call, or a second resolve of a failed
+          // continuation, does not run the tool again.
+          if (!this.engine) {
             await this.messages.saveThread(this.threadId, list)
           }
           // Only now, so a hook or an append that fails leaves them waiting.
@@ -2498,11 +3014,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
    * plugins, then of run plugins, then the session's media middleware. It
    * keeps the media the agents make, publishes a `harness.media` event for
    * each file, and pushes its record to `captured`. The agents read the
-   * session's provider keys as `ctx.keys`.
+   * session's provider keys as `ctx.keys`. Their model calls count in the
+   * usage of `principal`.
    */
   private binding(
     operation: OperationImpl<unknown> | OperationImpl<ChatTurnResult>,
     captured: Array<MediaRecord>,
+    principal: Principal | undefined,
     runPlugins?: MountedPlugins,
   ) {
     const options = this.harness.media
@@ -2529,6 +3047,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       chatMiddleware: [
         ...(this.sessionPlugins?.agentMiddleware ?? []),
         ...(runPlugins?.agentMiddleware ?? []),
+        // A routed root agent gets the thread too, so a reset cuts it as well.
+        resetCut,
+        this.usageCounter(operation, principal),
         // Last, because a later middleware that returns `messages` resets
         // what the model gets. A child's adapter is not known here, so only
         // `media.accepts` narrows what it reads.
@@ -2646,7 +3167,58 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }
   }
 
+  /**
+   * Apply a `reset()`: add its marker to the transcript. A thread that waits
+   * for interrupts gets no marker, and the reset fails.
+   */
+  private async runReset(
+    turn: QueuedTurn,
+    reset: { note?: string },
+  ): Promise<void> {
+    const { operation } = turn
+    const inputId = turn.inputId ?? operation.id
+    operation.setStatus('running')
+    this.publishStarted(operation)
+    let error: { message: string; code?: string } | undefined
+    try {
+      await this.applied(inputId, operation.id)
+      await this.refreshInterrupted(undefined, false, false)
+      if (this.interrupted) {
+        error = {
+          message: 'The thread waits for interrupts. Resolve them first.',
+          code: 'pending_interrupts',
+        }
+      } else {
+        const marker = resetMarker(inputId, reset.note)
+        const history = await this.messages.loadThread(this.threadId)
+        // Once: recovery can apply the same reset again.
+        if (!history.some((message) => message.id === marker.id)) {
+          await this.addToTurn({ messages: [marker] })
+        }
+        operation.publish(
+          customEvent(HARNESS_EVENTS.reset, { inputId, ...reset }),
+        )
+      }
+    } catch (failure) {
+      error = { message: errorText(this.logFailure ?? failure) }
+    }
+    if (!this.logFailure) {
+      await this.settle({
+        inputId,
+        operationId: operation.id,
+        outcome: error ? 'failed' : 'completed',
+        ...(error ? { error } : {}),
+      }).catch(() => {})
+    }
+    if (error) operation.fail('failed', new Error(error.message))
+    else operation.finish('completed', { text: '' })
+    this.publishFinished(operation)
+    // A steer that came while the reset ran runs as its own turn.
+    this.requeueWaitingSteers()
+  }
+
   private async runTurn(turn: QueuedTurn): Promise<void> {
+    if (turn.reset) return this.runReset(turn, turn.reset)
     const { operation } = turn
     operation.setStatus('running')
     // A new turn may ask for a sign-in the user cancelled before.
@@ -2712,9 +3284,14 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }
     try {
       await this.flushNotes()
-      // 'turn' and the old 'run'.
+      // The stored settings of the thread, as they are when the turn starts.
+      const stored = this.threadSettings
+      const removed = new Set(stored.plugins?.remove ?? [])
+      // 'turn' and the old 'run'. A removed turn plugin is not set up.
       const perRun = this.plugins.filter(
-        (plugin) => (plugin.lifetime ?? 'session') !== 'session',
+        (plugin) =>
+          (plugin.lifetime ?? 'session') !== 'session' &&
+          !removed.has(plugin.name),
       )
       if (perRun.length > 0) {
         runPlugins = await mountPlugins(perRun, {
@@ -2739,7 +3316,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           services: this.services,
         })
       }
-      const session = this.sessionPlugins
+      // A removed session plugin stays mounted, but gives this turn nothing.
+      const session =
+        this.sessionPlugins && removed.size > 0
+          ? withoutPlugins(this.sessionPlugins, removed)
+          : this.sessionPlugins
       const bridges = [
         session?.capabilityBridge,
         runPlugins?.capabilityBridge,
@@ -2777,6 +3358,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       const resolvePrompt = (prompt: string | (() => string)) =>
         typeof prompt === 'function' ? prompt() : prompt
       const turnTools = overrides?.tools ?? []
+      const turnToolNames = new Set(turnTools.map((tool) => tool.name))
       const staticTools = [
         ...(this.harness.tools ?? []),
         ...(session?.tools ?? []),
@@ -2789,9 +3371,15 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         operation,
       )
       // Before the chat() options below: prompts may describe these tools.
+      // The `tools` setting picks from them first, so a preparer (code mode)
+      // sees only the kept ones.
       const prepared = await this.prepareTools(
         [...(session?.preparers ?? []), ...(runPlugins?.preparers ?? [])],
-        [...staticTools, ...discovered],
+        settingTools(
+          [...staticTools, ...discovered],
+          stored.tools,
+          turnToolNames,
+        ),
         operation,
       )
       // A durable host gives each durableTool call its steps in the log. The
@@ -2802,11 +3390,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         ? prepared.map((tool) => bindDurable(tool, bindTool))
         : prepared
       // The override tools as the turn has them: prepared and bound.
-      const turnToolNames = new Set(turnTools.map((tool) => tool.name))
       const keptTools = tools.filter((tool) => turnToolNames.has(tool.name))
       const keepTools =
         keptTools.length > 0 ? keepTurnTools(keptTools) : undefined
-      const reasoning = overrides?.reasoning ?? this.harness.reasoning
+      const reasoning =
+        overrides?.reasoning ?? stored.reasoning ?? this.harness.reasoning
       const context = turnContext(this.harness.context, turn.context)
       // The turn value wins over the session value, field by field.
       const turnCache = cacheObject(overrides?.promptCache)
@@ -2816,7 +3404,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       }
       // A keyed adapter is built for this turn with the user's key. A
       // missing key publishes `auth_required` and fails the turn.
-      const model = overrides?.adapter ?? picked ?? this.harness.adapter
+      // The turn override, the stored model, a plugin pick, the harness model.
+      const named =
+        stored.model === undefined
+          ? undefined
+          : this.harness.models?.[stored.model]
+      const model =
+        overrides?.adapter ?? named ?? picked ?? this.harness.adapter
       if (!model) throw new Error(NO_MODEL)
       const adapter: AnyTextAdapter = await this.keys.adapter(model)
       let message =
@@ -2838,7 +3432,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       if (routing && rootAgents.length > 0 && turn.resume === undefined) {
         const history = await this.messages.loadThread(this.threadId)
         pick = await routing.router({
-          messages: [...history, ...(message ? [message] : [])],
+          messages: resetContext([...history, ...(message ? [message] : [])]),
           agents: rootAgents,
           abortSignal: signal,
           session: this,
@@ -2930,18 +3524,27 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
               ...[...(session?.prompts ?? []), ...(runPlugins?.prompts ?? [])]
                 .map(resolvePrompt)
                 .filter((prompt) => prompt !== ''),
+              // The thread's own instructions go last.
+              ...(stored.instructions ? [stored.instructions] : []),
             ],
             tools,
             middleware: [
               ...bridges,
               withPersistence(chatPersistence),
               checkpoint,
+              // Before the harness middleware, so a compaction sees only the
+              // context after a reset.
+              resetCut,
+              this.usageCounter(operation, sender),
               ...(this.harness.middleware ?? []),
               ...(session?.middleware ?? []),
               ...(runPlugins?.middleware ?? []),
               ...(keepTools ? [keepTools] : []),
               ...(durableTools ? [durableTools] : []),
               ...(rootBag ? [] : [this.steering()]),
+              // Again: a middleware that returns `messages` (as steering
+              // does) resets what the model gets to the whole transcript.
+              resetCut,
               // Last, because a later middleware that returns `messages` (as
               // steering does) resets what the model gets.
               mediaMiddleware({
@@ -2958,7 +3561,12 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
                   subagents: {
                     ...bag,
                     limits: bag.limits ?? this.limits(),
-                    binding: this.binding(operation, captured, runPlugins),
+                    binding: this.binding(
+                      operation,
+                      captured,
+                      sender,
+                      runPlugins,
+                    ),
                   },
                 }
               : {}),
@@ -3325,10 +3933,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       }
       return
     }
-    // A resolve that answers the turn that just ended runs first.
-    const at = this.queue[0]?.answers ? 1 : 0
     this.queue.splice(
-      at,
+      this.frontOfQueue(),
       0,
       ...rest.map((steer) => {
         const next = steer.operation ?? this.createTurnOperation()
@@ -3426,6 +4032,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     options: AgentStartOptions,
   ): OperationImpl<unknown> {
     const name = typeof target === 'string' ? target : target.name
+    if (options.resume && !this.writer) {
+      throw new Error(
+        `Agent ${name}: resume: true needs a durable host (a host with stores.log).`,
+      )
+    }
     const operation = new OperationImpl<unknown>(
       'agent',
       this.feed,
@@ -3439,6 +4050,114 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     return operation
   }
 
+  /**
+   * Run again an agent run with `resume: true` whose host stopped. The new
+   * run has the same input id, so its attempt counts up, and it continues the
+   * agent's saved transcript.
+   */
+  private resumeAgent(input: InputState & { input: { op: 'agent' } }) {
+    const { agent, input: agentInput, detached } = input.input
+    const operation = new OperationImpl<unknown>(
+      'agent',
+      this.feed,
+      (running) => this.cancel(running.id),
+      agent,
+    )
+    this.operations.set(operation.id, operation)
+    this.feed.publish(
+      operation.id,
+      customEvent(HARNESS_EVENTS.operationResumed, {
+        operationId: operation.id,
+        ...(input.operationId ? { resumedFrom: input.operationId } : {}),
+      }),
+    )
+    void this.executeAgent(
+      operation,
+      agent,
+      agentInput,
+      { wake: detached === true, resume: true },
+      input.principal,
+      input.inputId,
+    )
+  }
+
+  /**
+   * What a resumable agent run adds to its binding on a durable host. Its
+   * `ctx.chat` calls save the transcript of its thread at each tool phase, as
+   * a turn does, and `ctx.step` keeps each step value in the session log.
+   */
+  private resumable(
+    binding: { chatMiddleware: ReadonlyArray<AnyChatMiddleware> },
+    inputId: string,
+  ) {
+    const { chatPersistence, writer } = this
+    if (!chatPersistence || !writer) return {}
+    const { runs } = this.persistence.stores
+    const key = agentKey(inputId)
+    const checkpoint = checkpointMiddleware({
+      ...(runs ? { runs } : {}),
+      messages: chatPersistence.stores.messages,
+      hostId: this.hostId,
+      ...(this.lease ? { lease: this.lease } : {}),
+      // As in a turn, each finished tool result goes to the session log at
+      // once, under a key of this run. A run again puts it back.
+      onToolResult: ({ toolCallId, message }) =>
+        writer.append([
+          {
+            type: 'harness.tool.result',
+            toolCallId: `${key}:${toolCallId}`,
+            message,
+          },
+        ]),
+    })
+    const durableTools = this.durableTools()
+    return {
+      chatMiddleware: [
+        withPersistence(chatPersistence),
+        checkpoint,
+        ...(durableTools ? [durableTools] : []),
+        ...binding.chatMiddleware,
+      ],
+      step: this.durableBinding(writer, key).step,
+    }
+  }
+
+  /**
+   * The saved transcript of a resumable agent run whose host stopped. The
+   * chat runs that host left running end `failed`, and the last tool batch
+   * gets the same repair as in a turn: the results that finished, and an
+   * error for a cut call that must not run twice.
+   */
+  private async continueAgentThread(agentThread: string, inputId: string) {
+    const store = this.chatPersistence?.stores.messages
+    if (!store) return []
+    const runs = this.persistence.stores.runs
+    const records = (await runs?.listByThread?.(agentThread)) ?? []
+    for (const run of records.filter((item) => item.status === 'running')) {
+      await runs?.update(run.runId, {
+        status: 'failed',
+        finishedAt: Date.now(),
+        error: { message: AGENT_STOPPED },
+      })
+    }
+    const newest = [...records].sort((a, b) => b.startedAt - a.startedAt)[0]
+    const prefix = `${agentKey(inputId)}:`
+    const finished = new Map(
+      [...(this.writer?.state.toolResults ?? [])].flatMap(([id, message]) =>
+        id.startsWith(prefix)
+          ? [[id.slice(prefix.length), message] as const]
+          : [],
+      ),
+    )
+    await repairTranscript({
+      messages: store,
+      threadId: agentThread,
+      pending: newest?.checkpoint?.pendingTools ?? [],
+      finished,
+    })
+    return store.loadThread(agentThread)
+  }
+
   /** Run a group of agents. Every child settles before the group returns. */
   private async agentGroup<T>(
     options: { onFailure?: 'cancel-siblings' | 'collect' },
@@ -3485,19 +4204,24 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     input: unknown,
     options: AgentStartOptions,
     principal: Principal | undefined,
+    /** The input of a stopped run that recovery runs again. */
+    resumed?: string,
   ): Promise<void> {
     const name = typeof target === 'string' ? target : target.name
-    const inputId = createInputId()
-    await this.accept(
-      inputId,
-      {
-        op: 'agent',
-        agent: name,
-        input,
-        ...(options.wake ? { detached: true } : {}),
-      },
-      principal,
-    )
+    const inputId = resumed ?? createInputId()
+    if (resumed === undefined) {
+      await this.accept(
+        inputId,
+        {
+          op: 'agent',
+          agent: name,
+          input,
+          ...(options.wake ? { detached: true } : {}),
+          ...(options.resume ? { resume: true } : {}),
+        },
+        principal,
+      )
+    }
     const agent: AnyAgent | undefined =
       typeof target === 'string' ? this.agentRegistry.get(target) : target
     if (!agent) {
@@ -3556,14 +4280,23 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         this.lease,
       )
       releaseLease = await this.holdLease(inputId, operation)
-      const messages = await this.messages.loadThread(this.threadId)
+      // A resumable run keeps its transcript in a thread of its own, so a
+      // run again continues it. Other runs start from the session thread.
+      const agentThread = options.resume
+        ? `${this.threadId}:${name}:${inputId}`
+        : `${this.threadId}:${name}`
+      const messages =
+        resumed !== undefined
+          ? await this.continueAgentThread(agentThread, inputId)
+          : await this.messages.loadThread(this.threadId)
       subagentRunId = createSubagentId()
+      const binding = this.binding(operation, [], principal)
       const stream = runAgentStream(
         agent,
         {
           input: checkedInput,
           messages: messages ?? [],
-          threadId: `${this.threadId}:${name}`,
+          threadId: agentThread,
           runId: `${operation.id}:${subagentRunId}`,
           parentRunId: operation.id,
           subagentRunId,
@@ -3576,7 +4309,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         // (`<threadId>:<name>`). Write it to the session thread if a UI must
         // show it after a restart.
         {
-          ...this.binding(operation, []),
+          ...binding,
+          ...(options.resume ? this.resumable(binding, inputId) : {}),
           keys: this.keysOf(principal),
           budget: this.codeBudget(),
         },
@@ -3702,24 +4436,22 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     wake?: boolean
     /** Who started the agent. The wake turn runs as this user. */
     principal?: Principal
+    /** Why it failed. Default: the host stopped. */
+    error?: InputSettlement['error']
   }): Promise<void> {
     const { operationId, inputId } = stopped
+    const error = stopped.error ?? { message: AGENT_STOPPED }
     await this.persistence.stores.runs?.update(operationId, {
       status: 'failed',
       finishedAt: Date.now(),
-      error: { message: AGENT_STOPPED },
+      error,
     })
     if (inputId) {
-      await this.settle({
-        inputId,
-        operationId,
-        outcome: 'failed',
-        error: { message: AGENT_STOPPED },
-      })
+      await this.settle({ inputId, operationId, outcome: 'failed', error })
     }
     this.feed.publish(operationId, {
       type: EventType.RUN_ERROR,
-      message: AGENT_STOPPED,
+      message: error.message,
       timestamp: Date.now(),
     })
     this.feed.publish(
@@ -3732,7 +4464,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     await this.noteAgentEnd(
       stopped.agent,
       'failed',
-      AGENT_STOPPED,
+      error.message,
       { wake: stopped.wake === true },
       stopped.principal,
     )
@@ -3906,7 +4638,11 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
 
   private isChatInput(inputId: string) {
     const input = this.writer?.state.inputs.get(inputId)?.input
-    if (input) return CHAT_OPS.has(input.op)
+    // A reset and an agent run in the log settle their input too.
+    if (input)
+      return (
+        CHAT_OPS.has(input.op) || input.op === 'reset' || input.op === 'agent'
+      )
     return this.turnOperations.has(inputId) || this.receipts.has(inputId)
   }
 
@@ -4102,6 +4838,39 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     this.enqueueTurn({ operation })
   }
 
+  /**
+   * Queue a reset: at the front for a new one (it applies when the running
+   * turn ends), at the end for one from before a restart (in its admission
+   * order). Its operation is a command, so clients do not see a chat turn.
+   */
+  private queueReset(
+    inputId: string,
+    note: string | undefined,
+    principal: Principal | undefined,
+    at: 'front' | 'end',
+  ) {
+    const operation = new OperationImpl<ChatTurnResult>(
+      'command',
+      this.feed,
+      (target) => this.cancel(target.id),
+    )
+    this.operations.set(operation.id, operation as OperationImpl<unknown>)
+    this.bindTurn(inputId, operation)
+    const turn: QueuedTurn = {
+      operation,
+      inputId,
+      principal,
+      reset: note !== undefined ? { note } : {},
+    }
+    this.queue.splice(
+      at === 'front' ? this.frontOfQueue() : this.queue.length,
+      0,
+      turn,
+    )
+    this.drain()
+    return operation
+  }
+
   /** Re-run turns that were accepted but never applied before a restart. */
   private async recoverInbox(): Promise<void> {
     const pending: Array<InboxEntry> = await this.inbox.listPending(
@@ -4124,6 +4893,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           principal: entry.principal,
           context: input.context,
         })
+      } else if (input.op === 'reset') {
+        this.queueReset(entry.inputId, input.note, entry.principal, 'end')
       } else {
         this.reject(entry.inputId, 'expired_on_restart')
       }
@@ -4171,6 +4942,21 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     const maxAttempts = this.harness.durability?.maxAttempts ?? 10
     const inputs = [...writer.state.inputs.values()]
     for (const input of inputs) {
+      // A reset that did not settle applies now. Its marker goes in once.
+      if (input.input.op === 'reset') {
+        const isOpen = input.status === 'pending' || input.status === 'applied'
+        if (isOpen && input.abortRequested) {
+          await this.settle({ inputId: input.inputId, outcome: 'aborted' })
+        } else if (isOpen) {
+          this.queueReset(
+            input.inputId,
+            input.input.note,
+            input.principal,
+            'end',
+          )
+        }
+        continue
+      }
       const isChat = CHAT_OPS.has(input.input.op)
       if (input.status === 'pending') {
         if (!(isChat && 'message' in input.input)) {
@@ -4226,12 +5012,35 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       if (input.input.op === 'agent') {
         // A run that ended before its settle record landed did not stop.
         if (!run || run.status === 'running') {
+          const isResumable = input.input.resume === true
+          if (isResumable && input.attempt < maxAttempts) {
+            if (input.operationId) {
+              await runs?.update(input.operationId, {
+                status: 'failed',
+                finishedAt: now,
+                error: {
+                  message:
+                    'The host stopped. The session continued this agent run in a new run.',
+                },
+              })
+            }
+            this.resumeAgent({ ...input, input: input.input })
+            continue
+          }
           await this.failStoppedAgent({
             operationId: input.operationId ?? '',
             agent: input.input.agent,
             inputId: input.inputId,
             wake: input.input.detached,
             ...(input.principal ? { principal: input.principal } : {}),
+            ...(isResumable
+              ? {
+                  error: {
+                    message: `The agent run stopped the host ${input.attempt} times.`,
+                    code: 'attempts_exhausted',
+                  },
+                }
+              : {}),
           })
         }
         continue
@@ -4328,14 +5137,15 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             ...(operationId ? { resumedFrom: operationId } : {}),
           }),
         )
+        // The same turn as a live `resolve()`: it answers the stopped turn,
+        // as the input's sender, with the context of the stopped turn.
         this.enqueueTurn({
           operation,
           inputId: input.inputId,
           resume: input.input.resume,
-          parentRunId: this.interrupted.runId,
-          ...(this.interrupted.routed
-            ? { routed: this.interrupted.routed }
-            : {}),
+          answers: this.interrupted,
+          principal: input.principal,
+          context: this.interrupted.context,
         })
         continue
       }
diff --git a/packages/ai-harness/src/types.ts b/packages/ai-harness/src/types.ts
index c1394b1ad4..1451fe0dd8 100644
--- a/packages/ai-harness/src/types.ts
+++ b/packages/ai-harness/src/types.ts
@@ -100,13 +100,50 @@ export type HarnessInput = (
   | { op: 'steer'; message: UserInput; context?: unknown }
   | { op: 'followUp'; message: UserInput; context?: unknown }
   | { op: 'resolve'; resume: Array<RunAgentResumeItem> }
-  | { op: 'agent'; agent: string; input?: unknown; detached?: boolean }
+  | {
+      op: 'agent'
+      agent: string
+      input?: unknown
+      detached?: boolean
+      /** Run again after a host stop. See `AgentStartOptions.resume`. */
+      resume?: boolean
+    }
   | { op: 'cancel'; operationId?: string }
   | { op: 'command'; name: string; input?: unknown }
   | { op: 'answer'; questionId: string; value: unknown }
   | { op: 'config'; key: string; value: unknown }
+  | { op: 'configure'; settings: ThreadSettingsChange }
+  | { op: 'reset'; note?: string }
 ) & { inputId?: string }
 
+/**
+ * The stored settings of one thread. They apply from the next turn, stay
+ * after a restart (with `stores.metadata`), and a fork copies them. A turn's
+ * `overrides` win over them.
+ */
+export interface ThreadSettings {
+  /** A name from `defineHarness({ models })`. */
+  model?: string
+  /** The `reasoning` of every turn, as `chat({ reasoning })` takes it. */
+  reasoning?: ReasoningOption
+  /** Text added as the last system prompt of every turn. */
+  instructions?: string
+  /** Exactly these tools (by name), or every tool but the `remove` ones. */
+  tools?: Array<string> | { remove: Array<string> }
+  /** Plugins whose tools, prompts, and middleware the turns leave out. */
+  plugins?: { remove: Array<string> }
+  /**
+   * The working folder of the thread, from the root of the workspace tools.
+   * A folder outside that root is refused when a tool uses it.
+   */
+  cwd?: string
+}
+
+/** A change to {@link ThreadSettings}: `null` clears a field, a missing field stays. */
+export type ThreadSettingsChange = {
+  [Key in keyof ThreadSettings]?: ThreadSettings[Key] | null
+}
+
 /** How an input ended. `session.settled(inputId)` resolves to it. */
 export interface InputSettlement {
   inputId: string
@@ -240,6 +277,8 @@ export const HARNESS_EVENTS = {
   operationFinished: 'harness.operation.finished',
   operationResumed: 'harness.operation.resumed',
   configChanged: 'harness.config.changed',
+  /** `session.configure` changed the settings. The value has `settings`. */
+  settingsChanged: 'harness.settings.changed',
   /** A plugin added or removed a command with `ctx.commands`. */
   commandsChanged: 'harness.commands.changed',
   question: 'harness.question',
@@ -258,4 +297,14 @@ export const HARNESS_EVENTS = {
    * `retries`, and `error`.
    */
   turnRetry: 'harness.turn.retry',
+  /**
+   * `session.reset()` started a fresh model context. The value has
+   * `inputId` and the `note`, when there is one.
+   */
+  reset: 'harness.reset',
+  /**
+   * A model call reported its usage. The value has `model`, `sender` (when
+   * known), the `usage` of the call, and the new thread `total`.
+   */
+  usage: 'harness.usage',
 } as const
diff --git a/packages/ai-harness/src/usage.ts b/packages/ai-harness/src/usage.ts
new file mode 100644
index 0000000000..2066d4133f
--- /dev/null
+++ b/packages/ai-harness/src/usage.ts
@@ -0,0 +1,96 @@
+import type { TokenUsage } from '@tanstack/ai'
+
+/** The token counts of some model calls, and their cost when known. */
+export interface UsageCounts {
+  /** How many model calls reported usage. */
+  calls: number
+  promptTokens: number
+  completionTokens: number
+  totalTokens: number
+  /** Prompt tokens read from the cache of the provider. */
+  cachedTokens: number
+  /** Prompt tokens written to the cache of the provider. */
+  cacheWriteTokens: number
+  /**
+   * The sum of the cost that the providers reported, in their currency (USD
+   * for most). Set only when at least one call reported a cost.
+   */
+  cost?: number
+}
+
+/**
+ * The usage of a thread: every model call of its turns, their subagents, and
+ * its agent runs. `bySender` has the calls of a known sender only, keyed by
+ * the principal id, so its sum can be less than `total`.
+ */
+export interface SessionUsage {
+  total: UsageCounts
+  /** By `provider/model`, for example `anthropic/claude-sonnet-5-5`. */
+  byModel: Record<string, UsageCounts>
+  /** By principal id. */
+  bySender: Record<string, UsageCounts>
+}
+
+/** One model call, as the log keeps it. A type, so it is a log record field set. */
+export type UsageCall = {
+  model: string
+  principal?: { id: string; tenantId?: string }
+  usage: Omit<UsageCounts, 'calls'>
+}
+
+const emptyCounts = (): UsageCounts => ({
+  calls: 0,
+  promptTokens: 0,
+  completionTokens: 0,
+  totalTokens: 0,
+  cachedTokens: 0,
+  cacheWriteTokens: 0,
+})
+
+export const emptyUsage = (): SessionUsage => ({
+  total: emptyCounts(),
+  byModel: {},
+  bySender: {},
+})
+
+/** The counts that one call adds, from what the provider reported. */
+export function callUsage(usage: TokenUsage): UsageCall['usage'] {
+  return {
+    promptTokens: usage.promptTokens,
+    completionTokens: usage.completionTokens,
+    totalTokens: usage.totalTokens,
+    cachedTokens: usage.promptTokensDetails?.cachedTokens ?? 0,
+    cacheWriteTokens: usage.promptTokensDetails?.cacheWriteTokens ?? 0,
+    ...(typeof usage.cost === 'number' ? { cost: usage.cost } : {}),
+  }
+}
+
+function add(counts: UsageCounts, usage: UsageCall['usage']) {
+  counts.calls += 1
+  counts.promptTokens += usage.promptTokens
+  counts.completionTokens += usage.completionTokens
+  counts.totalTokens += usage.totalTokens
+  counts.cachedTokens += usage.cachedTokens
+  counts.cacheWriteTokens += usage.cacheWriteTokens
+  if (usage.cost !== undefined) counts.cost = (counts.cost ?? 0) + usage.cost
+}
+
+/** Add one call to `totals`, in place. */
+export function addUsage(totals: SessionUsage, call: UsageCall) {
+  add(totals.total, call.usage)
+  add((totals.byModel[call.model] ??= emptyCounts()), call.usage)
+  if (call.principal) {
+    add((totals.bySender[call.principal.id] ??= emptyCounts()), call.usage)
+  }
+}
+
+/** Is `value` usage totals that the harness wrote? */
+export function isSessionUsage(value: unknown): value is SessionUsage {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'total' in value &&
+    'byModel' in value &&
+    'bySender' in value
+  )
+}
diff --git a/packages/ai-harness/src/view/reduce.ts b/packages/ai-harness/src/view/reduce.ts
index b113cb03c2..a615d2897c 100644
--- a/packages/ai-harness/src/view/reduce.ts
+++ b/packages/ai-harness/src/view/reduce.ts
@@ -142,6 +142,13 @@ function userMedia(message: ModelMessage) {
   })
 }
 
+/** 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.'
+}
+
 /** Add a notice line at the end of the messages. */
 export function withNotice(
   state: SessionViewState,
@@ -476,6 +483,8 @@ export function applyEvent(
       'rejected',
       `Not accepted: ${String(value.reason ?? 'unknown reason')}`,
     )
+  if (event.name === HARNESS_EVENTS.reset)
+    return withNotice(state, 'info', resetNotice(value.note))
   if (
     event.name === HARNESS_EVENTS.authRequired &&
     typeof value.connector === 'string'
@@ -690,6 +699,17 @@ export function messagesFromTranscript(
   const result: Array<ViewMessage> = []
   messages.forEach((message, index) => {
     const id = message.id ?? `history-${index}`
+    // The marker of a `session.reset()` shows as a notice, not a message.
+    const reset = recordOf(message.metadata?.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({
diff --git a/packages/ai-harness/tests/agent-resume.test.ts b/packages/ai-harness/tests/agent-resume.test.ts
new file mode 100644
index 0000000000..d2d38ba7fe
--- /dev/null
+++ b/packages/ai-harness/tests/agent-resume.test.ts
@@ -0,0 +1,192 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { defineAgent, toolDefinition } from '@tanstack/ai'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '../src'
+import {
+  messageTexts,
+  mockAdapter,
+  text,
+  toolCall,
+  untilAborted,
+} from './helpers'
+import type { AnyTextAdapter } from '@tanstack/ai'
+import type { HarnessDurability } from '../src'
+
+const THREAD = 't1'
+const alice = { id: 'alice' }
+
+/**
+ * Host A starts the background agent `worker`. It reserves an id in a step,
+ * and its model calls `lookup`, then waits in its second model call. Then
+ * host A stops: its log refuses writes, and its run lease expires. Host B
+ * opens the thread on the same stores.
+ */
+async function stopDuringAgent(options: {
+  resume: boolean
+  durability?: HarnessDurability
+  /** The agent model of host B. */
+  next: Parameters<typeof mockAdapter>[0]
+}) {
+  const stores = memoryPersistence().stores
+  const log = memoryLogStore()
+  const persistence = {
+    stores: { log, runs: stores.runs, metadata: stores.metadata },
+  }
+  const effects: Array<string> = []
+  const lookup = toolDefinition({
+    name: 'lookup',
+    description: 'Look it up',
+    inputSchema: z.object({}),
+  }).server(async () => {
+    effects.push('lookup')
+    return { found: true }
+  })
+  const worker = (adapter: AnyTextAdapter) =>
+    defineAgent({
+      name: 'worker',
+      description: 'Works',
+      run: async (ctx) => {
+        await ctx.step.do('reserve', () => {
+          effects.push('reserve')
+          return 'R-1'
+        })
+        return ctx.chat({ adapter, tools: [lookup] })
+      },
+    })
+  const harness = (main: AnyTextAdapter, agent: AnyTextAdapter) =>
+    defineHarness({
+      name: 'test/agent-resume',
+      adapter: main,
+      agents: [worker(agent)],
+      ...(options.durability ? { durability: options.durability } : {}),
+    })
+
+  const first = mockAdapter([
+    () => toolCall('lookup', {}, 'call-1'),
+    untilAborted(),
+  ])
+  const hostA = createHarnessHost({ persistence })
+  const sessionA = await hostA.open(
+    harness(mockAdapter([]).adapter, first.adapter),
+    { threadId: THREAD, principal: alice },
+  )
+  const operation = sessionA.agent('worker')?.start(undefined, {
+    wake: true,
+    ...(options.resume ? { resume: true } : {}),
+  })
+  if (!operation) throw new Error('No worker agent.')
+  await vi.waitFor(() => expect(first.calls).toHaveLength(2))
+  expect(effects).toEqual(['reserve', 'lookup'])
+
+  // Host A stops: its log refuses writes, so the session stops writing.
+  const refuse = vi
+    .spyOn(log, 'append')
+    .mockRejectedValue(new Error('the host is gone'))
+  await expect(sessionA.append([{ type: 'app.ping' }])).rejects.toThrow()
+  await expect(operation).rejects.toThrow()
+  refuse.mockRestore()
+  await stores.runs.update(operation.id, { leaseExpiresAt: Date.now() - 1000 })
+
+  const record = (await log.read(THREAD))
+    .map((entry) => entry.record)
+    .find(
+      (entry) =>
+        entry.type === 'harness.input' &&
+        (entry.input as { op?: string }).op === 'agent',
+    )
+  const inputId = String(record?.inputId)
+
+  const agentModel = mockAdapter(options.next)
+  const main = mockAdapter([() => text('noted')])
+  const hostB = createHarnessHost({ persistence })
+  const sessionB = await hostB.open(harness(main.adapter, agentModel.adapter), {
+    threadId: THREAD,
+    principal: alice,
+  })
+  return { sessionB, hostB, inputId, effects, agentModel, main, stores }
+}
+
+describe('a background agent with resume: true', () => {
+  it('runs again on the host that takes over, with its steps and transcript', async () => {
+    const run = await stopDuringAgent({
+      resume: true,
+      next: [() => text('Worked.')],
+    })
+
+    expect(await run.sessionB.settled(run.inputId)).toMatchObject({
+      outcome: 'completed',
+    })
+    // The step and the finished tool call did not run again.
+    expect(run.effects).toEqual(['reserve', 'lookup'])
+    // The model continues from the saved transcript, with the tool result.
+    expect(run.agentModel.calls).toHaveLength(1)
+    const sent = run.agentModel.calls[0].messages as Array<{
+      role: string
+      toolCallId?: string
+    }>
+    expect(
+      sent.some(
+        (message) => message.role === 'tool' && message.toolCallId === 'call-1',
+      ),
+    ).toBe(true)
+    // `wake`: the main model gets the result in a new turn.
+    await vi.waitFor(() => expect(run.main.calls).toHaveLength(1))
+    expect(messageTexts(run.main.calls[0]).at(-1)).toContain(
+      'Background agent worker finished',
+    )
+    await run.hostB.close()
+  })
+
+  it('fails with attempts_exhausted after durability.maxAttempts runs', async () => {
+    const run = await stopDuringAgent({
+      resume: true,
+      durability: { maxAttempts: 1 },
+      next: [() => text('never')],
+    })
+
+    expect(await run.sessionB.settled(run.inputId)).toMatchObject({
+      outcome: 'failed',
+      error: { code: 'attempts_exhausted' },
+    })
+    expect(run.agentModel.calls).toHaveLength(0)
+    expect(run.effects).toEqual(['reserve', 'lookup'])
+    await run.hostB.close()
+  })
+
+  it('without resume, still fails the run that a stopped host left', async () => {
+    const run = await stopDuringAgent({
+      resume: false,
+      next: [() => text('never')],
+    })
+
+    expect(await run.sessionB.settled(run.inputId)).toMatchObject({
+      outcome: 'failed',
+      error: { message: 'The host stopped during this agent run.' },
+    })
+    expect(run.agentModel.calls).toHaveLength(0)
+    await run.hostB.close()
+  })
+
+  it('throws at start on a host without a log', async () => {
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const worker = defineAgent({
+      name: 'worker',
+      description: 'Works',
+      run: async () => 'done',
+    })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/agent-resume-memory',
+        adapter: mockAdapter([]).adapter,
+        agents: [worker],
+      }),
+      { threadId: THREAD },
+    )
+
+    expect(() =>
+      session.agent('worker')?.start(undefined, { resume: true }),
+    ).toThrow('stores.log')
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/fork.test.ts b/packages/ai-harness/tests/fork.test.ts
new file mode 100644
index 0000000000..439b047ce3
--- /dev/null
+++ b/packages/ai-harness/tests/fork.test.ts
@@ -0,0 +1,212 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { toolDefinition } from '@tanstack/ai'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  configOption,
+  createHarnessHost,
+  defineHarness,
+  definePlugin,
+  mediaIdOf,
+  mediaPart,
+} from '../src'
+import { messageTexts, mockAdapter, text, toolCall } from './helpers'
+import type { ModelMessage } from '@tanstack/ai'
+import type { HarnessPersistence } from '../src'
+
+const SOURCE = 'source'
+const FORK = 'fork'
+
+function durablePersistence() {
+  const { runs, metadata } = memoryPersistence().stores
+  return { stores: { log: memoryLogStore(), runs, metadata } }
+}
+
+/** A plugin with a config option and a counter in its saved state. */
+const counter = definePlugin({
+  name: 'test/counter',
+  setup: (ctx) => {
+    const state = ctx.state({ count: 0 })
+    return {
+      config: {
+        tone: configOption.select({
+          options: ['plain', 'warm'],
+          default: 'plain',
+        }),
+      },
+      tools: [
+        toolDefinition({
+          name: 'count',
+          description: 'Count one up',
+          inputSchema: z.object({}),
+        }).server(async () => {
+          await state.update((current) => ({ count: current.count + 1 }))
+          return 'counted'
+        }),
+      ],
+    }
+  },
+})
+
+const contents = (messages: ReadonlyArray<ModelMessage>) =>
+  messages.map(
+    (message) => `${message.role}:${JSON.stringify(message.content)}`,
+  )
+
+describe.each([
+  { name: 'a host with a message store', durable: false },
+  { name: 'a durable host', durable: true },
+])('host.fork on $name', ({ durable }) => {
+  const setup = (persistence: HarnessPersistence) => {
+    const { adapter, calls } = mockAdapter([
+      () => text('A1'),
+      () => text('A2'),
+      () => text('A3'),
+    ])
+    const harness = defineHarness({ name: 'test/fork', adapter })
+    const host = createHarnessHost({ persistence })
+    return { harness, host, calls }
+  }
+
+  it('copies the transcript up to a message, and the fork goes on alone', async () => {
+    const persistence = durable ? durablePersistence() : memoryPersistence()
+    const { harness, host, calls } = setup(persistence)
+    const source = await host.open(harness, { threadId: SOURCE })
+    await source.prompt('one')
+    await source.prompt('two')
+    const before = await source.transcript()
+    const firstAnswer = before[1]
+    if (!firstAnswer?.id) throw new Error('The answer has no id.')
+
+    const fork = await host.fork(harness, {
+      threadId: SOURCE,
+      newThreadId: FORK,
+      at: firstAnswer.id,
+    })
+    expect(contents(await fork.transcript())).toEqual(
+      contents(before.slice(0, 2)),
+    )
+
+    await fork.prompt('three')
+    expect(messageTexts(calls[2])).toEqual(['one', 'A1', 'three'])
+    // The source keeps its own transcript.
+    expect(contents(await source.transcript())).toEqual(contents(before))
+    await host.close()
+
+    if (durable) {
+      // A later host folds the fork from its log.
+      const later = createHarnessHost({ persistence })
+      const reopened = await later.open(harness, { threadId: FORK })
+      expect((await reopened.transcript()).map((m) => m.role)).toEqual([
+        'user',
+        'assistant',
+        'user',
+        'assistant',
+      ])
+      await later.close()
+    }
+  })
+
+  it('copies the whole transcript by default, and refuses an unknown message or a used thread', async () => {
+    const persistence = durable ? durablePersistence() : memoryPersistence()
+    const { harness, host } = setup(persistence)
+    const source = await host.open(harness, { threadId: SOURCE })
+    await source.prompt('one')
+
+    const whole = await host.fork(harness, {
+      threadId: SOURCE,
+      newThreadId: FORK,
+    })
+    expect(contents(await whole.transcript())).toEqual(
+      contents(await source.transcript()),
+    )
+    await expect(
+      host.fork(harness, { threadId: SOURCE, newThreadId: 'other', at: 'm-x' }),
+    ).rejects.toThrow('m-x')
+    // The fork thread has messages now.
+    await expect(
+      host.fork(harness, { threadId: SOURCE, newThreadId: FORK }),
+    ).rejects.toThrow(FORK)
+    await host.close()
+  })
+})
+
+describe('host.fork', () => {
+  it('copies the settings and plugin config, but not plugin state or interrupts', async () => {
+    const deploy = toolDefinition({
+      name: 'deploy',
+      description: 'Deploy',
+      inputSchema: z.object({}),
+      needsApproval: true,
+    }).server(async () => 'deployed')
+    const { adapter } = mockAdapter([
+      () => toolCall('count', {}, 'c1'),
+      () => text('counted once'),
+      () => toolCall('deploy', {}, 'c2'),
+    ])
+    const harness = defineHarness({
+      name: 'test/fork',
+      adapter,
+      tools: [deploy],
+      models: { main: adapter },
+      plugins: () => [counter],
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const source = await host.open(harness, { threadId: SOURCE })
+    await source.configure({ model: 'main', instructions: 'Be brief.' })
+    await source.setConfig('tone', 'warm')
+    await source.prompt('Count.')
+    await source.prompt('Deploy.')
+    expect(source.snapshot().pendingInterrupts).toHaveLength(1)
+    expect(source.snapshot().plugins['test/counter']).toEqual({ count: 1 })
+
+    const fork = await host.fork(harness, {
+      threadId: SOURCE,
+      newThreadId: FORK,
+    })
+    expect(fork.settings()).toEqual({
+      model: 'main',
+      instructions: 'Be brief.',
+    })
+    expect(fork.config().tone?.value).toBe('warm')
+    expect(fork.snapshot().plugins['test/counter']).toEqual({ count: 0 })
+    expect(fork.snapshot().pendingInterrupts).toEqual([])
+    await host.close()
+  })
+
+  it('copies the media of the copied messages, so the fork loads them', async () => {
+    const { adapter } = mockAdapter(() => text('a cat'))
+    const harness = defineHarness({ name: 'test/fork', adapter })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const source = await host.open(harness, { threadId: SOURCE })
+    const bytes = new Uint8Array([1, 2, 3, 4])
+    const record = await source.putMedia(bytes, {
+      mimeType: 'image/png',
+      name: 'cat.png',
+    })
+    await source.prompt([
+      { type: 'text', content: 'What is this?' },
+      mediaPart(record),
+    ])
+
+    const fork = await host.fork(harness, {
+      threadId: SOURCE,
+      newThreadId: FORK,
+    })
+    const [question] = await fork.transcript()
+    const parts = Array.isArray(question?.content) ? question.content : []
+    const id = parts.map(mediaIdOf).find((value) => value !== undefined)
+    if (!id) throw new Error('The fork lost the media part.')
+
+    expect(id).not.toBe(record.id)
+    expect(await fork.getMedia(id)).toMatchObject({
+      threadId: FORK,
+      name: 'cat.png',
+    })
+    expect(await fork.loadMedia(id)).toEqual(bytes)
+    // Each thread sees only its own media.
+    expect(await fork.getMedia(record.id)).toBeNull()
+    expect(await source.getMedia(id)).toBeNull()
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/reset.test.ts b/packages/ai-harness/tests/reset.test.ts
new file mode 100644
index 0000000000..8639f53c77
--- /dev/null
+++ b/packages/ai-harness/tests/reset.test.ts
@@ -0,0 +1,349 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { toolDefinition } from '@tanstack/ai'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHandler, createHarnessHost, defineHarness } from '../src'
+import { messagesFromTranscript } from '../src/view/reduce'
+import {
+  after,
+  gate,
+  messageTexts,
+  mockAdapter,
+  text,
+  toolCall,
+} from './helpers'
+import type { AnyChatMiddleware } from '@tanstack/ai'
+import type { Reply } from './helpers'
+
+/** The stores of a host without a log, or of a durable host. */
+function persistenceFor(durable: boolean) {
+  const { stores } = memoryPersistence()
+  if (!durable) return { stores }
+  const { runs, metadata } = stores
+  return { stores: { log: memoryLogStore(), runs, metadata } }
+}
+
+const contents = (messages: ReadonlyArray<{ content: unknown }>) =>
+  messages.map((message) =>
+    typeof message.content === 'string'
+      ? message.content
+      : JSON.stringify(message.content),
+  )
+
+describe.each([
+  { host: 'a host without a log', durable: false },
+  { host: 'a durable host', durable: true },
+])('reset on $host', ({ durable }) => {
+  async function open(replies: Array<Reply>, extra = {}) {
+    const { adapter, calls } = mockAdapter(replies)
+    const persistence = persistenceFor(durable)
+    const host = createHarnessHost({ persistence })
+    const harness = defineHarness({ name: 'test/reset', adapter, ...extra })
+    const session = await host.open(harness, { threadId: 't1' })
+    return { session, calls, host, harness, persistence }
+  }
+
+  it('gives the next model call only the note and the new message', async () => {
+    const { session, calls, host } = await open([
+      () => text('One.'),
+      () => text('Two.'),
+    ])
+    await session.prompt('First.')
+    const receipt = await session.reset('We agreed on plan B.', {
+      inputId: 'r1',
+    })
+    expect(receipt).toMatchObject({ status: 'accepted' })
+    expect(await session.settled('r1')).toMatchObject({ outcome: 'completed' })
+    await session.prompt('Second.')
+
+    expect(messageTexts(calls[1])).toEqual(['We agreed on plan B.', 'Second.'])
+    // The transcript keeps every message, with the marker.
+    const transcript = await session.transcript()
+    expect(contents(transcript)).toEqual([
+      'First.',
+      'One.',
+      'We agreed on plan B.',
+      'Second.',
+      'Two.',
+    ])
+    expect(transcript[2]?.metadata?.harness?.reset).toEqual({
+      note: 'We agreed on plan B.',
+    })
+    await host.close()
+  })
+
+  it('gives the model only the new message without a note', async () => {
+    const { session, calls, host } = await open([
+      () => text('One.'),
+      () => text('Two.'),
+    ])
+    await session.prompt('First.')
+    await session.reset()
+    await session.prompt('Second.')
+
+    expect(messageTexts(calls[1])).toEqual(['Second.'])
+    const transcript = await session.transcript()
+    expect(contents(transcript)).toEqual([
+      'First.',
+      'One.',
+      '',
+      'Second.',
+      'Two.',
+    ])
+    expect(transcript[2]?.metadata?.harness?.reset).toEqual({})
+    await host.close()
+  })
+
+  it('keeps the old messages in the transcript after more turns', async () => {
+    const { session, calls, host } = await open([
+      () => text('One.'),
+      () => text('Two.'),
+      () => text('Three.'),
+      () => text('Four.'),
+    ])
+    await session.prompt('First.')
+    await session.reset('Note.')
+    await session.prompt('Second.')
+    await session.prompt('Third.')
+    await session.prompt('Fourth.')
+
+    expect(messageTexts(calls[3])).toEqual([
+      'Note.',
+      'Second.',
+      'Two.',
+      'Third.',
+      'Three.',
+      'Fourth.',
+    ])
+    expect(contents(await session.transcript()).slice(0, 3)).toEqual([
+      'First.',
+      'One.',
+      'Note.',
+    ])
+    await host.close()
+  })
+
+  it('waits for the running turn, then applies before the next queued turn', async () => {
+    const release = gate()
+    const { session, calls, host } = await open([
+      after(release.opened, 'One.'),
+      () => text('Two.'),
+    ])
+    const first = session.prompt('First.')
+    // Queued while the first turn runs, before the reset.
+    const second = session.prompt('Second.')
+    const receipt = await session.reset('Note.')
+    expect(receipt).toMatchObject({ status: 'queued' })
+    release.open()
+    await Promise.all([first, second])
+
+    // The running turn kept its context. The queued turn got the cut one.
+    expect(messageTexts(calls[0])).toEqual(['First.'])
+    expect(messageTexts(calls[1])).toEqual(['Note.', 'Second.'])
+    expect(contents(await session.transcript())).toEqual([
+      'First.',
+      'One.',
+      'Note.',
+      'Second.',
+      'Two.',
+    ])
+    await host.close()
+  })
+
+  it('keeps the cut when a steer joins the turn', async () => {
+    const started = gate()
+    const release = gate()
+    const lookup = toolDefinition({
+      name: 'lookup',
+      description: 'Look something up',
+      inputSchema: z.object({}),
+    }).server(async () => {
+      started.open()
+      await release.opened
+      return { found: true }
+    })
+    const { session, calls, host } = await open(
+      [() => text('One.'), () => toolCall('lookup', {}), () => text('Two.')],
+      { tools: [lookup] },
+    )
+    await session.prompt('First.')
+    await session.reset('Note.')
+    const turn = session.prompt('Second.')
+    await started.opened
+    // Joins at the model call after the tool.
+    await session.steer('Also this.')
+    release.open()
+    await turn
+
+    expect(messageTexts(calls[2])).toEqual([
+      'Note.',
+      'Second.',
+      'null',
+      '{"found":true}',
+      'Also this.',
+    ])
+    await host.close()
+  })
+
+  it('shows only the new context to the harness middleware', async () => {
+    const seen: Array<Array<string>> = []
+    const watch: AnyChatMiddleware = {
+      name: 'test/watch',
+      onConfig: (ctx, config) => {
+        if (ctx.phase === 'beforeModel') {
+          seen.push(contents(config.providerMessages ?? config.messages))
+        }
+      },
+    }
+    const { session, host } = await open(
+      [() => text('One.'), () => text('Two.')],
+      { middleware: [watch] },
+    )
+    await session.prompt('First.')
+    await session.reset('Note.')
+    await session.prompt('Second.')
+
+    expect(seen.at(-1)).toEqual(['Note.', 'Second.'])
+    await host.close()
+  })
+
+  it('runs once for the same inputId and refuses another note', async () => {
+    const { session, host } = await open([() => text('One.')])
+    await session.prompt('First.')
+    await session.reset('Note.', { inputId: 'r1' })
+    await session.settled('r1')
+    expect(await session.reset('Note.', { inputId: 'r1' })).toMatchObject({
+      status: 'accepted',
+    })
+    expect(await session.reset('Other.', { inputId: 'r1' })).toMatchObject({
+      status: 'rejected',
+      reason: 'conflict',
+    })
+    const markers = (await session.transcript()).filter(
+      (message) => message.metadata?.harness?.reset,
+    )
+    expect(markers).toHaveLength(1)
+    await host.close()
+  })
+
+  it('refuses a reset while the thread waits for interrupts', async () => {
+    const deploy = toolDefinition({
+      name: 'deploy',
+      description: 'Deploy. Needs approval.',
+      needsApproval: true,
+      inputSchema: z.object({}),
+    }).server(async () => ({ ok: true }))
+    const { session, host } = await open([() => toolCall('deploy', {})], {
+      tools: [deploy],
+    })
+    await session.prompt('Deploy.')
+    expect(await session.reset('Note.')).toMatchObject({
+      status: 'rejected',
+      reason: 'pending_interrupts',
+    })
+    await host.close()
+  })
+
+  it('takes the reset input over HTTP, as the request principal', async () => {
+    const { session, calls, host, harness } = await open([
+      () => text('One.'),
+      () => text('Two.'),
+    ])
+    await session.prompt('First.')
+    const handler = createHarnessHandler({
+      host,
+      harness,
+      authorize: () => ({ id: 'ada' }),
+    })
+    const response = await handler(
+      new Request('http://h.test/control', {
+        method: 'POST',
+        body: JSON.stringify({
+          threadId: 't1',
+          input: { op: 'reset', note: 'Note.', inputId: 'r1' },
+        }),
+      }),
+    )
+    expect(await response.json()).toMatchObject({ status: 'accepted' })
+    await session.settled('r1')
+    await session.prompt('Second.')
+    expect(messageTexts(calls[1])).toEqual(['Note.', 'Second.'])
+    await host.close()
+  })
+})
+
+describe('reset on a durable host', () => {
+  it('keeps the cut context after a restart', async () => {
+    const persistence = persistenceFor(true)
+    const first = mockAdapter([() => text('One.')])
+    const hostA = createHarnessHost({ persistence })
+    const sessionA = await hostA.open(
+      defineHarness({ name: 'test/reset', adapter: first.adapter }),
+      { threadId: 't1' },
+    )
+    await sessionA.prompt('First.')
+    await sessionA.reset('Note.', { inputId: 'r1' })
+    await sessionA.settled('r1')
+    await hostA.close()
+
+    const second = mockAdapter([() => text('Two.')])
+    const hostB = createHarnessHost({ persistence })
+    const sessionB = await hostB.open(
+      defineHarness({ name: 'test/reset', adapter: second.adapter }),
+      { threadId: 't1' },
+    )
+    await sessionB.prompt('Second.')
+    expect(messageTexts(second.calls[0])).toEqual(['Note.', 'Second.'])
+    expect(contents(await sessionB.transcript())).toEqual([
+      'First.',
+      'One.',
+      'Note.',
+      'Second.',
+      'Two.',
+    ])
+    await hostB.close()
+  })
+
+  it('applies a reset that a crash left in the log', async () => {
+    const log = memoryLogStore()
+    const { runs, metadata } = memoryPersistence().stores
+    const persistence = { stores: { log, runs, metadata } }
+    await log.append('t1', 1, [
+      {
+        type: 'harness.input',
+        inputId: 'r1',
+        input: { op: 'reset', note: 'Note.' },
+        at: Date.now(),
+      },
+    ])
+    const { adapter, calls } = mockAdapter([() => text('Two.')])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({ name: 'test/reset', adapter }),
+      { threadId: 't1' },
+    )
+    expect(await session.settled('r1')).toMatchObject({ outcome: 'completed' })
+    await session.prompt('Second.')
+    expect(messageTexts(calls[0])).toEqual(['Note.', 'Second.'])
+    await host.close()
+  })
+})
+
+describe('the session view', () => {
+  it('shows the reset marker of a transcript as a notice', () => {
+    const messages = messagesFromTranscript([
+      { id: 'u1', role: 'user', content: 'First.' },
+      {
+        id: 'reset-r1',
+        role: 'user',
+        content: 'Note.',
+        metadata: { harness: { reset: { note: 'Note.' } } },
+      },
+    ])
+    expect(messages[1]).toMatchObject({
+      role: 'notice',
+      kind: 'info',
+      text: expect.stringContaining('Note.'),
+    })
+  })
+})
diff --git a/packages/ai-harness/tests/thread-settings.test.ts b/packages/ai-harness/tests/thread-settings.test.ts
new file mode 100644
index 0000000000..7488157acc
--- /dev/null
+++ b/packages/ai-harness/tests/thread-settings.test.ts
@@ -0,0 +1,489 @@
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { EventType, toolDefinition } from '@tanstack/ai'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  HARNESS_EVENTS,
+  configOption,
+  createHarnessHandler,
+  createHarnessHost,
+  defineHarness,
+  definePlugin,
+} from '../src'
+import { workspaceTools } from '../src/first-party'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { AnyTool, ModelMessage } from '@tanstack/ai'
+import type { HarnessConfig, HarnessPersistence } from '../src'
+import type { Reply } from './helpers'
+
+const THREAD = 't1'
+
+function durablePersistence() {
+  const { runs, metadata } = memoryPersistence().stores
+  return { stores: { log: memoryLogStore(), runs, metadata } }
+}
+
+const toolNames = (call: { tools?: ReadonlyArray<AnyTool> }) =>
+  (call.tools ?? []).map((tool) => tool.name)
+
+const echo = (name: string) =>
+  toolDefinition({
+    name,
+    description: `The ${name} tool`,
+    inputSchema: z.object({}),
+  }).server(async () => name)
+
+/** A base adapter and two named models, each with its own calls. */
+function models(replies: Array<Reply> = [() => text('ok')]) {
+  const base = mockAdapter(() => text('base'))
+  const fast = mockAdapter(() => text('fast'))
+  const strong = mockAdapter(replies)
+  return { base, fast, strong }
+}
+
+async function open(
+  extras: Omit<HarnessConfig, 'name'> = {},
+  persistence: HarnessPersistence = memoryPersistence(),
+) {
+  const host = createHarnessHost({ persistence })
+  const harness = defineHarness({ name: 'test/settings', ...extras })
+  const session = await host.open(harness, { threadId: THREAD })
+  return { host, harness, session }
+}
+
+describe('thread settings', () => {
+  it('runs the next turn on the model the settings name', async () => {
+    const { base, fast, strong } = models()
+    const { host, session } = await open({
+      adapter: base.adapter,
+      models: { fast: fast.adapter, strong: strong.adapter },
+    })
+
+    expect(await session.configure({ model: 'strong' })).toMatchObject({
+      status: 'accepted',
+    })
+    expect(session.settings()).toEqual({ model: 'strong' })
+    expect((await session.prompt('Hi.')).text).toBe('ok')
+    expect(strong.calls).toHaveLength(1)
+    expect(base.calls).toHaveLength(0)
+
+    // `null` clears the field: the harness adapter answers again.
+    await session.configure({ model: null })
+    expect(session.settings()).toEqual({})
+    expect((await session.prompt('Again.')).text).toBe('base')
+    await host.close()
+  })
+
+  it('puts the settings model after the turn override and before a plugin pick', async () => {
+    const { base, fast, strong } = models()
+    const override = mockAdapter(() => text('override'))
+    const picked = mockAdapter(() => text('picked'))
+    const { host, session } = await open({
+      adapter: base.adapter,
+      models: { fast: fast.adapter, strong: strong.adapter },
+      plugins: () => [
+        definePlugin({
+          name: 'test/picker',
+          setup: () => ({ adapter: () => picked.adapter }),
+        }),
+      ],
+    })
+    await session.configure({ model: 'fast' })
+
+    const overridden = await session.prompt('One.', {
+      overrides: { adapter: override.adapter },
+    })
+    expect(overridden.text).toBe('override')
+    expect((await session.prompt('Two.')).text).toBe('fast')
+    await session.configure({ model: null })
+    expect((await session.prompt('Three.')).text).toBe('picked')
+    // A removed plugin's pick is left out too.
+    await session.configure({ plugins: { remove: ['test/picker'] } })
+    expect((await session.prompt('Four.')).text).toBe('base')
+    await host.close()
+  })
+
+  it('publishes the change, and treats a repeated inputId as the same input', async () => {
+    const { adapter } = mockAdapter(() => text('ok'))
+    const { host, session } = await open({ adapter })
+    const from = session.snapshot().cursor
+    const reader = new AbortController()
+
+    const first = await session.configure(
+      { instructions: 'Be short.' },
+      { inputId: 'set-1' },
+    )
+    expect(
+      await session.configure(
+        { instructions: 'Be short.' },
+        { inputId: 'set-1' },
+      ),
+    ).toEqual(first)
+    expect(
+      await session.configure(
+        { instructions: 'Be long.' },
+        { inputId: 'set-1' },
+      ),
+    ).toMatchObject({ status: 'rejected', reason: 'conflict' })
+    expect(session.settings()).toEqual({ instructions: 'Be short.' })
+
+    for await (const entry of session.events({ from, signal: reader.signal })) {
+      const { event } = entry
+      if (
+        event.type === EventType.CUSTOM &&
+        event.name === HARNESS_EVENTS.settingsChanged
+      ) {
+        expect(event.value).toEqual({ settings: { instructions: 'Be short.' } })
+        reader.abort()
+      }
+    }
+    await host.close()
+  })
+
+  it('sends the settings reasoning unless the turn overrides it', async () => {
+    const { adapter, calls } = mockAdapter(() => text('ok'))
+    const { host, session } = await open({ adapter })
+    await session.configure({ reasoning: 'high' })
+
+    await session.prompt('One.')
+    await session.prompt('Two.', { overrides: { reasoning: 'low' } })
+    expect(calls.map((call) => call.reasoning?.level)).toEqual(['high', 'low'])
+    await host.close()
+  })
+
+  it('adds the instructions as the last system prompt', async () => {
+    const { adapter, calls } = mockAdapter(() => text('ok'))
+    const { host, session } = await open({
+      adapter,
+      systemPrompts: ['You help with code.'],
+      plugins: () => [
+        definePlugin({
+          name: 'test/prompt',
+          setup: () => ({ prompts: ['Use tabs.'] }),
+        }),
+      ],
+    })
+    await session.configure({ instructions: 'Answer in French.' })
+
+    await session.prompt('Hi.')
+    const prompts: Array<unknown> = calls[0].systemPrompts
+    expect(JSON.stringify(prompts.at(-1))).toContain('Answer in French.')
+    expect(JSON.stringify(prompts)).toContain('Use tabs.')
+    await host.close()
+  })
+
+  it('keeps an exact tool list, or leaves out named tools', async () => {
+    const { adapter, calls } = mockAdapter(() => text('ok'))
+    const { host, session } = await open({
+      adapter,
+      tools: [echo('alpha'), echo('beta'), echo('gamma')],
+    })
+
+    await session.configure({ tools: ['alpha'] })
+    await session.prompt('One.')
+    await session.configure({ tools: { remove: ['alpha'] } })
+    await session.prompt('Two.')
+    // A tool of the turn override is kept.
+    await session.prompt('Three.', { overrides: { tools: [echo('delta')] } })
+
+    expect(calls.map(toolNames)).toEqual([
+      ['alpha'],
+      ['beta', 'gamma'],
+      ['beta', 'gamma', 'delta'],
+    ])
+    await host.close()
+  })
+
+  it('leaves out the tools, prompts, and middleware of a removed plugin', async () => {
+    const { adapter, calls } = mockAdapter(() => text('ok'))
+    const seen: Array<string> = []
+    const { host, session } = await open({
+      adapter,
+      plugins: () => [
+        definePlugin({
+          name: 'acme/notes',
+          setup: () => ({
+            tools: [echo('note')],
+            prompts: ['Keep notes.'],
+            middleware: [
+              { name: 'notes', onStart: () => void seen.push('notes') },
+            ],
+          }),
+        }),
+        definePlugin({
+          name: 'acme/search',
+          lifetime: 'turn',
+          setup: () => ({ tools: [echo('search')], prompts: ['Search.'] }),
+        }),
+      ],
+    })
+
+    await session.prompt('One.')
+    await session.configure({ plugins: { remove: ['acme/notes'] } })
+    await session.prompt('Two.')
+
+    expect(calls.map(toolNames)).toEqual([['note', 'search'], ['search']])
+    expect(JSON.stringify(calls[1].systemPrompts)).not.toContain('Keep notes.')
+    expect(JSON.stringify(calls[1].systemPrompts)).toContain('Search.')
+    expect(seen).toEqual(['notes'])
+    await host.close()
+  })
+
+  it('refuses an unknown model or plugin', async () => {
+    const { adapter } = mockAdapter(() => text('ok'))
+    const { host, session } = await open({
+      adapter,
+      models: { fast: adapter },
+    })
+
+    expect(await session.configure({ model: 'huge' })).toMatchObject({
+      status: 'rejected',
+      reason: expect.stringContaining('huge'),
+    })
+    expect(
+      await session.configure({ plugins: { remove: ['acme/none'] } }),
+    ).toMatchObject({
+      status: 'rejected',
+      reason: expect.stringContaining('acme/none'),
+    })
+    expect(session.settings()).toEqual({})
+    await host.close()
+  })
+
+  it.each([
+    { name: 'a host with a message store', durable: false },
+    { name: 'a durable host', durable: true },
+  ])('keeps the settings after a restart on $name', async ({ durable }) => {
+    const persistence = durable ? durablePersistence() : memoryPersistence()
+    const { base, strong } = models([() => text('strong')])
+    const harness = defineHarness({
+      name: 'test/settings',
+      adapter: base.adapter,
+      models: { strong: strong.adapter },
+    })
+    const first = createHarnessHost({ persistence })
+    await (
+      await first.open(harness, { threadId: THREAD })
+    ).configure({ model: 'strong', instructions: 'Be short.' })
+    await first.close()
+
+    const second = createHarnessHost({ persistence })
+    const session = await second.open(harness, { threadId: THREAD })
+    expect(session.settings()).toEqual({
+      model: 'strong',
+      instructions: 'Be short.',
+    })
+    expect((await session.prompt('Hi.')).text).toBe('strong')
+    await second.close()
+  })
+
+  it('takes a configure input over HTTP as the request principal, and checks its values', async () => {
+    const persistence = durablePersistence()
+    const { base, strong } = models()
+    const host = createHarnessHost({ persistence })
+    const harness = defineHarness({
+      name: 'test/settings',
+      adapter: base.adapter,
+      models: { strong: strong.adapter },
+      expose: { settings: ['model', 'instructions'] },
+    })
+    const handler = createHarnessHandler({
+      host,
+      harness,
+      authorize: () => ({ id: 'ada' }),
+    })
+    const control = async (input: unknown) =>
+      (
+        await handler(
+          new Request('http://h.test/control', {
+            method: 'POST',
+            body: JSON.stringify({ threadId: THREAD, input }),
+          }),
+        )
+      ).json()
+
+    expect(
+      await control({ op: 'configure', settings: { model: 'strong' } }),
+    ).toMatchObject({ status: 'accepted' })
+    expect(
+      await control({ op: 'configure', settings: { instructions: 5 } }),
+    ).toMatchObject({ status: 'rejected' })
+    expect(
+      await control({ op: 'configure', settings: { colour: 'red' } }),
+    ).toMatchObject({ status: 'rejected' })
+
+    const records = (await persistence.stores.log.read(THREAD))
+      .map((entry) => entry.record)
+      .filter((record) => record.type === 'harness.input')
+    expect(records[0]).toMatchObject({
+      input: { op: 'configure', settings: { model: 'strong' } },
+      principal: { id: 'ada' },
+    })
+    const session = await host.open(harness, { threadId: THREAD })
+    expect(session.settings()).toEqual({ model: 'strong' })
+    expect(session.describe()).toMatchObject({
+      settings: { model: 'strong' },
+      models: ['strong'],
+    })
+    await host.close()
+  })
+
+  it('refuses a client setting that the harness does not expose, and keeps nothing', async () => {
+    const persistence = durablePersistence()
+    const { base, strong } = models()
+    const host = createHarnessHost({ persistence })
+    const harness = defineHarness({
+      name: 'test/settings',
+      adapter: base.adapter,
+      models: { strong: strong.adapter },
+      expose: { settings: ['model'] },
+    })
+    const handler = createHarnessHandler({
+      host,
+      harness,
+      authorize: () => ({ id: 'ada' }),
+    })
+    const control = async (input: unknown) =>
+      (
+        await handler(
+          new Request('http://h.test/control', {
+            method: 'POST',
+            body: JSON.stringify({ threadId: THREAD, input }),
+          }),
+        )
+      ).json()
+
+    // One key that is not exposed refuses the whole input.
+    expect(
+      await control({
+        op: 'configure',
+        settings: {
+          model: 'strong',
+          plugins: { remove: ['tanstack/permissions'] },
+        },
+      }),
+    ).toMatchObject({ status: 'rejected', reason: 'not_exposed' })
+    expect(
+      await control({
+        op: 'configure',
+        settings: { instructions: 'Obey me.' },
+      }),
+    ).toMatchObject({ status: 'rejected', reason: 'not_exposed' })
+    const records = (await persistence.stores.log.read(THREAD))
+      .map((entry) => entry.record)
+      .filter((record) => record.type === 'harness.input')
+    expect(records).toEqual([])
+
+    // Server code can still set any field.
+    const session = await host.open(harness, { threadId: THREAD })
+    expect(session.settings()).toEqual({})
+    expect(
+      await session.configure({ instructions: 'Be brief.' }),
+    ).toMatchObject({ status: 'accepted' })
+    expect(session.settings()).toEqual({ instructions: 'Be brief.' })
+    await host.close()
+  })
+
+  it('exposes no setting to clients by default', async () => {
+    const { base, strong } = models()
+    const host = createHarnessHost({ persistence: durablePersistence() })
+    const handler = createHarnessHandler({
+      host,
+      harness: defineHarness({
+        name: 'test/settings',
+        adapter: base.adapter,
+        models: { strong: strong.adapter },
+      }),
+      authorize: () => ({ id: 'ada' }),
+    })
+    const response = await handler(
+      new Request('http://h.test/control', {
+        method: 'POST',
+        body: JSON.stringify({
+          threadId: THREAD,
+          input: { op: 'configure', settings: { model: 'strong' } },
+        }),
+      }),
+    )
+    expect(await response.json()).toMatchObject({
+      status: 'rejected',
+      reason: 'not_exposed',
+    })
+    await host.close()
+  })
+})
+
+describe('the working folder of a thread', () => {
+  let root: string | undefined
+  afterEach(async () => {
+    if (root) await rm(root, { recursive: true, force: true })
+    root = undefined
+  })
+
+  it('runs the workspace tools in the folder the settings name', async () => {
+    root = await mkdtemp(join(tmpdir(), 'harness-cwd-'))
+    await mkdir(join(root, 'pkg'))
+    await writeFile(join(root, 'pkg', 'a.txt'), 'inside pkg')
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('read_file', { path: 'a.txt' }, 'c1'),
+      () => text('read it'),
+      () => toolCall('read_file', { path: 'a.txt' }, 'c2'),
+      () => text('refused'),
+    ])
+    const workspaceRoot = root
+    const { host, session } = await open({
+      adapter,
+      plugins: () => [workspaceTools({ root: workspaceRoot })],
+    })
+    const toolResult = (messages: ReadonlyArray<ModelMessage>, id: string) =>
+      JSON.stringify(
+        messages.find((m) => m.role === 'tool' && m.toolCallId === id)?.content,
+      )
+
+    await session.configure({ cwd: 'pkg' })
+    await session.prompt('Read a.txt.')
+    expect(toolResult(await session.transcript(), 'c1')).toContain('inside pkg')
+    // JSON escapes the backslashes of a Windows path, so compare JSON.
+    expect(JSON.stringify(calls[1].systemPrompts)).toContain(
+      JSON.stringify(join(workspaceRoot, 'pkg')).slice(1, -1),
+    )
+
+    // A folder outside the workspace root is refused.
+    await session.configure({ cwd: '..' })
+    await session.prompt('Read a.txt again.')
+    expect(toolResult(await session.transcript(), 'c2')).toContain(
+      'outside the workspace',
+    )
+    await host.close()
+  })
+})
+
+describe('plugin config next to the settings', () => {
+  it('keeps plugin config and the settings apart', async () => {
+    const { adapter } = mockAdapter(() => text('ok'))
+    const { host, session } = await open({
+      adapter,
+      plugins: () => [
+        definePlugin({
+          name: 'test/tone',
+          setup: () => ({
+            config: {
+              tone: configOption.select({
+                options: ['plain', 'warm'],
+                default: 'plain',
+              }),
+            },
+          }),
+        }),
+      ],
+    })
+    await session.setConfig('tone', 'warm')
+    await session.configure({ instructions: 'Be brief.' })
+    expect(session.config().tone?.value).toBe('warm')
+    expect(session.settings()).toEqual({ instructions: 'Be brief.' })
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/usage.test.ts b/packages/ai-harness/tests/usage.test.ts
new file mode 100644
index 0000000000..27939cb78b
--- /dev/null
+++ b/packages/ai-harness/tests/usage.test.ts
@@ -0,0 +1,257 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { EventType, defineAgent, toolDefinition } from '@tanstack/ai'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '../src'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { StreamChunk } from '@tanstack/ai'
+import type { SessionEvent } from '../src'
+import type { Reply } from './helpers'
+
+const THREAD = 't1'
+const alice = { id: 'alice' }
+const bob = { id: 'bob' }
+
+/** `chunks` with this usage on RUN_FINISHED, as a provider reports it. */
+function withUsage(
+  chunks: Array<StreamChunk>,
+  usage: { prompt: number; completion: number; cost?: number },
+): Array<StreamChunk> {
+  return chunks.map((chunk) =>
+    chunk.type === EventType.RUN_FINISHED
+      ? {
+          ...chunk,
+          usage: {
+            promptTokens: usage.prompt,
+            completionTokens: usage.completion,
+            totalTokens: usage.prompt + usage.completion,
+            ...(usage.cost !== undefined ? { cost: usage.cost } : {}),
+          },
+        }
+      : chunk,
+  )
+}
+
+/** A mock model with its own model id, so totals can be told apart. */
+function model(id: string, replies: Array<Reply>) {
+  const { adapter, calls } = mockAdapter(replies)
+  return { adapter: { ...adapter, model: id }, calls }
+}
+
+const lookup = toolDefinition({
+  name: 'lookup',
+  description: 'Look something up',
+  inputSchema: z.object({}),
+}).server(async () => ({ found: true }))
+
+/** A model call that uses `lookup`, then one that answers. */
+const lookupThenAnswer = (cost?: [number, number]): Array<Reply> => [
+  () =>
+    withUsage(toolCall('lookup', {}), {
+      prompt: 10,
+      completion: 5,
+      ...(cost ? { cost: cost[0] } : {}),
+    }),
+  () =>
+    withUsage(text('done'), {
+      prompt: 20,
+      completion: 10,
+      ...(cost ? { cost: cost[1] } : {}),
+    }),
+]
+
+const usageEvents = (events: Array<SessionEvent>) =>
+  events.filter(
+    (entry) =>
+      entry.event.type === EventType.CUSTOM &&
+      entry.event.name === 'harness.usage',
+  )
+
+async function readEvents(session: {
+  events: (options?: { signal?: AbortSignal }) => AsyncIterable<SessionEvent>
+}) {
+  const seen: Array<SessionEvent> = []
+  const reader = new AbortController()
+  const done = (async () => {
+    for await (const entry of session.events({ signal: reader.signal }))
+      seen.push(entry)
+  })()
+  return {
+    seen,
+    stop: async () => {
+      reader.abort()
+      await done.catch(() => {})
+    },
+  }
+}
+
+describe('session usage totals', () => {
+  it('adds every model call of a turn, by model and by sender, with the reported cost', async () => {
+    const main = model('main-model', lookupThenAnswer([0.01, 0.02]))
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/usage',
+        adapter: main.adapter,
+        tools: [lookup],
+      }),
+      { threadId: THREAD, principal: alice },
+    )
+    const events = await readEvents(session)
+
+    const turn = session.prompt('Find it.')
+    await turn
+
+    const usage = session.usage()
+    expect(usage.total).toMatchObject({
+      calls: 2,
+      promptTokens: 30,
+      completionTokens: 15,
+      totalTokens: 45,
+    })
+    expect(usage.total.cost).toBeCloseTo(0.03)
+    expect(Object.keys(usage.byModel)).toEqual(['mock/main-model'])
+    expect(usage.byModel['mock/main-model']).toEqual(usage.total)
+    expect(usage.bySender).toEqual({ alice: usage.total })
+    expect(session.snapshot().usage).toEqual(usage)
+
+    await events.stop()
+    const published = usageEvents(events.seen)
+    expect(published).toHaveLength(2)
+    expect(published.every((entry) => entry.operationId === turn.id)).toBe(true)
+    expect(published.at(-1)?.event).toMatchObject({
+      value: {
+        model: 'mock/main-model',
+        sender: 'alice',
+        usage: { promptTokens: 20, completionTokens: 10, totalTokens: 30 },
+        total: { calls: 2, totalTokens: 45 },
+      },
+    })
+    await host.close()
+  })
+
+  it('keeps one total for each sender, and has no cost when no call reported one', async () => {
+    const main = model('main-model', [
+      () => withUsage(text('for alice'), { prompt: 4, completion: 1 }),
+      () => withUsage(text('for bob'), { prompt: 8, completion: 2 }),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({ name: 'test/usage-senders', adapter: main.adapter }),
+      { threadId: THREAD, principal: alice },
+    )
+
+    await session.prompt('Hi.')
+    await session.prompt('Hello.', { principal: bob })
+
+    const usage = session.usage()
+    expect(usage.total).toEqual({
+      calls: 2,
+      promptTokens: 12,
+      completionTokens: 3,
+      totalTokens: 15,
+      cachedTokens: 0,
+      cacheWriteTokens: 0,
+    })
+    expect(usage.bySender.alice?.totalTokens).toBe(5)
+    expect(usage.bySender.bob?.totalTokens).toBe(10)
+    await host.close()
+  })
+
+  it('adds the model calls of a subagent and of a background agent', async () => {
+    const helperModel = model('helper-model', [
+      () => withUsage(text('helped'), { prompt: 5, completion: 2 }),
+    ])
+    const workerModel = model('worker-model', [
+      () => withUsage(text('worked'), { prompt: 6, completion: 3 }),
+    ])
+    const lead = model('lead-model', [
+      () => withUsage(toolCall('helper', {}), { prompt: 1, completion: 1 }),
+      () => withUsage(text('lead done'), { prompt: 2, completion: 1 }),
+    ])
+    const helper = defineAgent({
+      name: 'helper',
+      description: 'Helps',
+      run: (ctx) => ctx.chat({ adapter: helperModel.adapter }),
+    })
+    const worker = defineAgent({
+      name: 'worker',
+      description: 'Works',
+      run: (ctx) => ctx.chat({ adapter: workerModel.adapter }),
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/usage-agents',
+        adapter: lead.adapter,
+        subagents: { agents: [helper] },
+        agents: [worker],
+      }),
+      { threadId: THREAD, principal: alice },
+    )
+
+    expect((await session.prompt('Get help.')).text).toBe('lead done')
+    expect(await session.agent('worker')?.start()).toBe('worked')
+
+    const usage = session.usage()
+    expect(usage.byModel['mock/lead-model']?.totalTokens).toBe(5)
+    expect(usage.byModel['mock/helper-model']?.totalTokens).toBe(7)
+    expect(usage.byModel['mock/worker-model']?.totalTokens).toBe(9)
+    expect(usage.total).toMatchObject({ calls: 4, totalTokens: 21 })
+    expect(usage.bySender.alice?.totalTokens).toBe(21)
+    await host.close()
+  })
+})
+
+describe('usage totals after a restart', () => {
+  it('keeps the totals in the log of a durable host', async () => {
+    const { runs, metadata } = memoryPersistence().stores
+    const log = memoryLogStore()
+    const persistence = { stores: { log, runs, metadata } }
+    const first = model('main-model', lookupThenAnswer([0.01, 0.02]))
+    const harness = (adapter: typeof first.adapter) =>
+      defineHarness({ name: 'test/usage-durable', adapter, tools: [lookup] })
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(harness(first.adapter), {
+      threadId: THREAD,
+      principal: alice,
+    })
+    await session.prompt('Find it.')
+    const before = session.usage()
+    await host.close()
+
+    const records = (await log.read(THREAD)).filter(
+      (entry) => entry.record.type === 'harness.usage',
+    )
+    expect(records).toHaveLength(2)
+
+    const next = createHarnessHost({ persistence })
+    const reopened = await next.open(harness(model('main-model', []).adapter), {
+      threadId: THREAD,
+      principal: alice,
+    })
+    expect(reopened.usage()).toEqual(before)
+    expect(reopened.usage().total.totalTokens).toBe(45)
+    await next.close()
+  })
+
+  it('keeps the totals in the metadata store of a host without a log', async () => {
+    const persistence = memoryPersistence()
+    const first = model('main-model', lookupThenAnswer())
+    const harness = (adapter: typeof first.adapter) =>
+      defineHarness({ name: 'test/usage-metadata', adapter, tools: [lookup] })
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(harness(first.adapter), {
+      threadId: THREAD,
+    })
+    await session.prompt('Find it.')
+    await host.close()
+
+    const next = createHarnessHost({ persistence })
+    const reopened = await next.open(harness(model('main-model', []).adapter), {
+      threadId: THREAD,
+    })
+    expect(reopened.usage().total).toMatchObject({ calls: 2, totalTokens: 45 })
+    await next.close()
+  })
+})
diff --git a/packages/ai-harness/tests/view-fixtures.ts b/packages/ai-harness/tests/view-fixtures.ts
index 60aabffa42..df0fc47cc1 100644
--- a/packages/ai-harness/tests/view-fixtures.ts
+++ b/packages/ai-harness/tests/view-fixtures.ts
@@ -1,4 +1,5 @@
 import { EventType } from '@tanstack/ai'
+import { emptyUsage } from '../src/usage'
 import type { StreamChunk } from '@tanstack/ai'
 import type { SessionEvent, SessionSnapshot } from '../src'
 
@@ -52,6 +53,7 @@ export function sessionSnapshot(
     pendingInterrupts: [],
     pendingQuestions: [],
     plugins: {},
+    usage: emptyUsage(),
     cursor: '0',
     ...over,
   }

From 7e591a7e570112752c46703506f47f28c45e14d7 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 18:00:02 +0200
Subject: [PATCH 229/286] test(e2e): check usage, settings, reset, fork, and a
 resumable agent

---
 .../e2e/fixtures/harness/thread-controls.json |  34 +++
 .../e2e/src/routes/api.harness-protocol.$.ts  |  67 ++++-
 testing/e2e/src/routes/api.harness-test.ts    |  80 ++++++
 .../e2e/tests/harness-thread-controls.spec.ts | 253 ++++++++++++++++++
 testing/e2e/tests/harness.spec.ts             |  16 ++
 5 files changed, 439 insertions(+), 11 deletions(-)
 create mode 100644 testing/e2e/fixtures/harness/thread-controls.json
 create mode 100644 testing/e2e/tests/harness-thread-controls.spec.ts

diff --git a/testing/e2e/fixtures/harness/thread-controls.json b/testing/e2e/fixtures/harness/thread-controls.json
new file mode 100644
index 0000000000..368a1c6230
--- /dev/null
+++ b/testing/e2e/fixtures/harness/thread-controls.json
@@ -0,0 +1,34 @@
+{
+  "fixtures": [
+    {
+      "match": { "userMessage": "[harness-usage] hello" },
+      "response": { "content": "Counted." }
+    },
+    {
+      "match": { "userMessage": "[harness-settings] hi" },
+      "response": { "content": "Strong." }
+    },
+    {
+      "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": "Background agent stepper finished: [stepper finished] charged once"
+      },
+      "response": { "content": "The stepper finished." }
+    }
+  ]
+}
diff --git a/testing/e2e/src/routes/api.harness-protocol.$.ts b/testing/e2e/src/routes/api.harness-protocol.$.ts
index 0fd243d3b4..4667de8700 100644
--- a/testing/e2e/src/routes/api.harness-protocol.$.ts
+++ b/testing/e2e/src/routes/api.harness-protocol.$.ts
@@ -36,7 +36,15 @@ const durableHost = createHarnessHost({
   },
 })
 
-function handlerFor(request: Request) {
+// 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
+}
+
+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({
@@ -77,6 +85,12 @@ function handlerFor(request: Request) {
   const harness = defineHarness({
     name: 'e2e/protocol',
     adapter,
+    // 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 })),
@@ -94,7 +108,7 @@ function handlerFor(request: Request) {
         run: async (ctx) => ctx.input.text,
       }),
     ],
-    expose: { agents: ['echo'] },
+    expose: { agents: ['echo'], settings: ['model', 'instructions'] },
     plugins: () => [
       todos(),
       // The sender of the running turn, as plugins see it.
@@ -141,27 +155,58 @@ function handlerFor(request: Request) {
       }),
     ],
   })
-  return createHarnessHandler({
+  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,
-    // Two users, so a test can share one thread between them.
-    authorize: (req) => {
-      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
-    },
+    authorize,
     // 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 has no fork route.
+ */
+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 }) => 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.harness-test.ts b/testing/e2e/src/routes/api.harness-test.ts
index c45cfdb0d9..f84eeb493b 100644
--- a/testing/e2e/src/routes/api.harness-test.ts
+++ b/testing/e2e/src/routes/api.harness-test.ts
@@ -283,6 +283,83 @@ async function agentRestart(
   }
 }
 
+/**
+ * A background agent with `resume: true` on a durable host that stops. Its
+ * step runs on the first host only, then the agent waits there. The next
+ * host takes over, runs the agent again without the step, and the agent
+ * finishes and wakes the thread.
+ */
+async function agentResume(
+  openai: () => ReturnType<typeof createTextAdapter>['adapter'],
+) {
+  const { runs, metadata } = memoryPersistence().stores
+  const persistence = { stores: { log: memoryLogStore(), runs, metadata } }
+  let attempts = 0
+  let charges = 0
+  const stepper = defineAgent({
+    name: 'stepper',
+    description: 'Charges once, then waits on the first host',
+    run: async (ctx) => {
+      attempts += 1
+      await ctx.step.do('charge', async () => {
+        charges += 1
+        return 'charged'
+      })
+      if (attempts === 1) {
+        // The first host stops before the agent ends.
+        await new Promise<void>((resolve) =>
+          ctx.abortSignal?.addEventListener('abort', () => resolve()),
+        )
+        return 'stopped'
+      }
+      return 'charged once'
+    },
+  })
+  const harness = defineHarness({
+    name: 'e2e/harness-resume',
+    adapter: openai(),
+    agents: [stepper],
+  })
+  const stopped = createHarnessHost({
+    persistence,
+    lease: { ttlMs: 50, renewMs: 60_000 },
+  })
+  const next = createHarnessHost({ persistence })
+  try {
+    const first = await stopped.open(harness, { threadId: 'e2e-resume' })
+    first.agents.stepper.start(undefined, { wake: true, resume: true })
+    await new Promise((resolve) => setTimeout(resolve, 200))
+
+    const session = await next.open(harness, { threadId: 'e2e-resume' })
+    // Only the text of chat turns: the wake turn writes it.
+    const chats = new Set<string>()
+    let text = ''
+    for await (const { event, operationId } of session.events({ from: '0' })) {
+      if (event.type !== 'CUSTOM' && event.type !== 'TEXT_MESSAGE_CONTENT')
+        continue
+      if (
+        event.type === 'CUSTOM' &&
+        event.name === HARNESS_EVENTS.operationStarted &&
+        (event.value as { kind?: string } | undefined)?.kind === 'chat'
+      )
+        chats.add(operationId)
+      if (!chats.has(operationId)) continue
+      if (event.type === 'TEXT_MESSAGE_CONTENT') text += event.delta
+      if (
+        event.type === 'CUSTOM' &&
+        event.name === HARNESS_EVENTS.operationFinished &&
+        text !== ''
+      )
+        break
+    }
+    return { attempts, charges, text }
+  } finally {
+    await next.close()
+    // The first host sees the writes of the second host, and stops.
+    await stopped.close().catch(() => {})
+  }
+}
+
 /**
  * Harness session. The main model and the agent are real OpenAI adapters
  * against aimock.
@@ -729,6 +806,9 @@ export const Route = createFileRoute('/api/harness-test')({
           if (body.scenario === 'agent-restart') {
             return Response.json(await agentRestart(openai))
           }
+          if (body.scenario === 'agent-resume') {
+            return Response.json(await agentResume(openai))
+          }
           if (body.scenario === 'routing') {
             return Response.json(await routingTurns(host, openai))
           }
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..1e5ab8f79e
--- /dev/null
+++ b/testing/e2e/tests/harness-thread-controls.spec.ts
@@ -0,0 +1,253 @@
+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 exposes only `model` and `instructions` 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('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('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)
+  })
+})
diff --git a/testing/e2e/tests/harness.spec.ts b/testing/e2e/tests/harness.spec.ts
index bac6eb4d50..7ed349bdb9 100644
--- a/testing/e2e/tests/harness.spec.ts
+++ b/testing/e2e/tests/harness.spec.ts
@@ -71,6 +71,22 @@ test.describe('harness session', () => {
     expect(body.text).toBe('The waiter stopped before it finished.')
   })
 
+  test('a resumable background agent continues on the next host, and its step runs once', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'agent-resume', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    expect(await response.json()).toEqual({
+      attempts: 2,
+      charges: 1,
+      text: 'The stepper finished.',
+    })
+  })
+
   test('routing.router sends each turn to the picked root agents or to the main model', async ({
     request,
     testId,

From 20b7a8665328fd9f222c245d69c2e07838b5042a Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 18:00:03 +0200
Subject: [PATCH 230/286] docs(ai-harness): usage, fork and reset, thread
 settings, and resumable agents

---
 docs/config.json                 |  19 +++-
 docs/harness/custom-ui.md        |   2 +-
 docs/harness/durable-sessions.md |   2 +-
 docs/harness/fork-and-reset.md   | 118 +++++++++++++++++++++++++
 docs/harness/inputs.md           |   3 +
 docs/harness/plugins.md          |   1 +
 docs/harness/subagents.md        |  59 +++++++++++++
 docs/harness/thread-settings.md  | 144 +++++++++++++++++++++++++++++++
 docs/harness/turn-control.md     |   2 +
 docs/harness/usage.md            | 113 ++++++++++++++++++++++++
 10 files changed, 459 insertions(+), 4 deletions(-)
 create mode 100644 docs/harness/fork-and-reset.md
 create mode 100644 docs/harness/thread-settings.md
 create mode 100644 docs/harness/usage.md

diff --git a/docs/config.json b/docs/config.json
index c81692335e..e4a77d62b5 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -914,7 +914,7 @@
           "label": "Durable sessions",
           "to": "harness/durable-sessions",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-10-02"
+          "updatedAt": "2026-10-05"
         },
         {
           "label": "Send inputs safely",
@@ -940,11 +940,21 @@
           "addedAt": "2026-10-01",
           "updatedAt": "2026-10-05"
         },
+        {
+          "label": "Store settings per thread",
+          "to": "harness/thread-settings",
+          "addedAt": "2026-10-05"
+        },
         {
           "label": "Compact a long session",
           "to": "harness/compaction",
           "addedAt": "2026-10-03"
         },
+        {
+          "label": "Fork and reset a thread",
+          "to": "harness/fork-and-reset",
+          "addedAt": "2026-10-05"
+        },
         {
           "label": "Share one log between sessions",
           "to": "harness/shared-logs",
@@ -979,6 +989,11 @@
           "to": "harness/shared-threads",
           "addedAt": "2026-10-05"
         },
+        {
+          "label": "Track usage and cost",
+          "to": "harness/usage",
+          "addedAt": "2026-10-05"
+        },
         {
           "label": "Use MCP servers",
           "to": "harness/mcp",
@@ -1022,7 +1037,7 @@
           "label": "Run agents from a harness",
           "to": "harness/subagents",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-10-02"
+          "updatedAt": "2026-10-05"
         },
         {
           "label": "Deploy a harness",
diff --git a/docs/harness/custom-ui.md b/docs/harness/custom-ui.md
index 628a750f59..20d34cb08c 100644
--- a/docs/harness/custom-ui.md
+++ b/docs/harness/custom-ui.md
@@ -147,7 +147,7 @@ An assistant message has `parts`. Each part is one of these:
 
 A notice has a `kind`:
 
-- `info`: the session continues a turn that a crash stopped.
+- `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.
diff --git a/docs/harness/durable-sessions.md b/docs/harness/durable-sessions.md
index 890f8e2328..93cafe7699 100644
--- a/docs/harness/durable-sessions.md
+++ b/docs/harness/durable-sessions.md
@@ -67,7 +67,7 @@ When a host opens the thread and finds a turn whose lease expired, it checks the
 
 An input that was stored but never ran, runs now. See [Send inputs safely](./inputs) to read how an input ended.
 
-A background agent does not run again, because it has no checkpoints. When its lease expired, the next host:
+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:
 
 1. Ends the run `failed`, with the message `The host stopped during this agent run.`
 2. Adds a note about the failure to the transcript.
diff --git a/docs/harness/fork-and-reset.md b/docs/harness/fork-and-reset.md
new file mode 100644
index 0000000000..768760b09c
--- /dev/null
+++ b/docs/harness/fork-and-reset.md
@@ -0,0 +1,118 @@
+---
+title: Fork and reset a thread
+id: harness-fork-and-reset
+order: 4
+description: "Copy a thread into a new one up to a message, to try another path. Or reset the model context with a handoff note, and keep the whole history."
+keywords:
+  - tanstack ai
+  - harness
+  - fork
+  - branch
+  - reset
+  - handoff
+---
+
+A user wants to try another answer from an earlier message, but keep the current path too. Another user has a long thread, and the old context confuses the model. A fork copies a thread into a new thread, up to a message. A reset starts a fresh model context with a short note, and the transcript keeps every message.
+
+## Fork a thread at a message
+
+`host.fork` copies a thread into a new thread and returns the open session of the new thread:
+
+```ts group=harness-fork-and-reset
+import { 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-5.6'),
+})
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+
+export async function branch(threadId: string, messageId: string) {
+  const fork = await host.fork(assistant, {
+    threadId,
+    newThreadId: `${threadId}-branch-${messageId}`,
+    at: messageId,
+  })
+  return fork.threadId
+}
+```
+
+`at` is the id of the last message to copy. Without `at`, the fork copies the whole transcript. The message ids stay the same, so `at` points at the same message in both threads.
+
+The fork copies:
+
+- The transcript, up to and including the message `at`.
+- The [stored settings](./thread-settings) of the thread, and the values that `setConfig` stored for its plugins.
+- The media that the copied messages use. The copies get new ids.
+
+The fork does not copy plugin state, pending interrupts, queued inputs, running work, or [usage totals](./usage). If `newThreadId` already has messages, `host.fork` throws. It also throws for an `at` that the thread does not have.
+
+If a thread waits for an approval, fork it at a message before the tool call. A fork of the whole transcript copies the tool call, but the fork has no interrupt to answer it.
+
+The handler has no fork route. Call `host.fork` from your own route, then open the new thread on the client:
+
+```ts group=harness-fork-and-reset-client
+import { createHarnessClient } from '@tanstack/ai-harness/client'
+import type { assistant } from './harness'
+
+// The new thread id comes from your route that calls host.fork.
+const response = await fetch('/api/branch', {
+  method: 'POST',
+  body: JSON.stringify({ threadId: 'support-1', messageId: 'msg-7' }),
+})
+const body: unknown = await response.json()
+if (
+  typeof body !== 'object' ||
+  body === null ||
+  !('threadId' in body) ||
+  typeof body.threadId !== 'string'
+) {
+  throw new Error('The branch route sent no thread id.')
+}
+
+const branch = createHarnessClient<typeof assistant>({
+  url: '/api/harness',
+  threadId: body.threadId,
+})
+await branch.prompt('Try a shorter answer.')
+```
+
+## Reset with a handoff note
+
+`session.reset(note)` starts a fresh model context. From the next turn, the model sees only the note and what comes after the reset:
+
+```ts group=harness-fork-and-reset
+export async function startFresh(threadId: string) {
+  const session = await host.open(assistant, { threadId })
+  return session.reset(
+    'Summary: the user moves the billing service to the new region. The DNS change is done. The database move is next.',
+  )
+}
+```
+
+A client sends the same input:
+
+```ts group=harness-fork-and-reset-client
+const support = createHarnessClient<typeof assistant>({
+  url: '/api/harness',
+  threadId: 'support-1',
+})
+await support.reset('Summary: the refund is approved. Only the email to the user is left.')
+```
+
+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 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.
+
+## What you have now
+
+- A branch of a thread at any message, with its settings and media.
+- A fresh model context with a handoff note, and the whole history in the transcript.
+- A marker in the transcript that your UI can show as a line.
diff --git a/docs/harness/inputs.md b/docs/harness/inputs.md
index 47c0a59de0..52f55ad593 100644
--- a/docs/harness/inputs.md
+++ b/docs/harness/inputs.md
@@ -42,6 +42,7 @@ 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
 
@@ -79,6 +80,8 @@ if (settlement.outcome === 'failed') {
 - `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
diff --git a/docs/harness/plugins.md b/docs/harness/plugins.md
index c84705d097..5ebc26995c 100644
--- a/docs/harness/plugins.md
+++ b/docs/harness/plugins.md
@@ -223,6 +223,7 @@ The session uses the picks like this:
 - `undefined` keeps the harness adapter.
 - If more than one plugin returns an adapter, the last plugin wins.
 - The `overrides.adapter` of the turn wins over every pick.
+- A model that the thread stored with `session.configure` also wins over every pick. See [Store settings per thread](./thread-settings).
 - A keyed adapter gets the key of the sender. See [Connect model providers](./provider-keys).
 
 If the picker does not need the turn, it can take no parameter.
diff --git a/docs/harness/subagents.md b/docs/harness/subagents.md
index eeb61d81e4..6dc80dc321 100644
--- a/docs/harness/subagents.md
+++ b/docs/harness/subagents.md
@@ -67,6 +67,64 @@ To track usage or apply a policy in each of these runs, see [Middleware in every
 
 The harness saves the images, audio, and video that these agents make, and the UI shows them. See [Media that agents make](./media#media-that-agents-make).
 
+## Keep a background agent going after a crash
+
+A background agent can work for a long time. When its host stops, for example in a deploy, the next host fails the run. Start it with `resume: true`, and the next host runs it again instead:
+
+```ts group=harness-subagents
+// Your own services.
+async function startExport(customer: string) {
+  return `export-${customer}`
+}
+async function importInto(region: string, exportId: string) {
+  return `${exportId} is in ${region}`
+}
+
+const migrator = defineAgent({
+  name: 'migrator',
+  description: 'Moves the data of one customer to the new region',
+  inputSchema: z.object({ customer: z.string() }),
+  run: async (ctx) => {
+    // Each side effect is a step. A finished step does not run again.
+    const exportId = await ctx.step.do('export', () => startExport(ctx.input.customer))
+    await ctx.step.do('import', () => importInto('eu-west', exportId))
+    return ctx.chat({
+      adapter: openaiText('gpt-5.6'),
+      messages: [{ role: 'user', content: `Write a short report about ${exportId}.` }],
+      stream: false,
+    })
+  },
+})
+
+export const migrations = definePlugin({
+  name: 'acme/migrations',
+  setup: (ctx) => ({
+    agents: [migrator],
+    commands: {
+      migrate: defineCommand({
+        description: 'Move one customer',
+        input: z.object({ customer: z.string() }),
+        run: ({ customer }) => {
+          ctx.agents.start(migrator, { customer }, { resume: true, wake: true })
+          return `Moving ${customer}.`
+        },
+      }),
+    },
+  }),
+})
+```
+
+1. Give the host a session log (`stores.log`). See [Durable sessions](./durable-sessions). Without a log, `start` with `resume: true` throws.
+2. Put each side effect in `ctx.step.do(name, fn)`. The agent code runs again from its start, and a finished step returns its stored value.
+3. Give each step a name that is the same on every run, and return a JSON value from `fn`.
+
+What the next host does:
+
+- It runs the agent again with the same input. Its `ctx.chat` calls continue from the saved transcript, and its finished tool calls do not run again.
+- A step runs at least once. A host can stop after `fn` ran and before the log stored its value. Then the next run calls `fn` again.
+- After `durability.maxAttempts` runs (default 10), the run ends `failed` with the code `attempts_exhausted`.
+- `host.close()` cancels the run. Only a host that stops without a close (a crash or a kill) leaves the run for the next host.
+
 ## Route a turn to an agent
 
 Your harness has a writer and a pricer, but the main model answers every turn. Add `routing.router` to send a turn to the agent that can answer it. The router runs at the start of each new turn: a `prompt`, a `followUp`, or the wake turn of a background agent.
@@ -181,6 +239,7 @@ See [subagent limits](../chat/subagents) for what each limit does.
 ## What you have now
 
 - Commands and plugins that start typed agents, alone or in groups.
+- Background agents that continue on the next host after a crash, with steps that do not run twice.
 - A router that sends each turn to the right agent, and gives each agent its input.
 - Harnesses that call other harnesses as tools.
 - A tree of children that stays within limits.
diff --git a/docs/harness/thread-settings.md b/docs/harness/thread-settings.md
new file mode 100644
index 0000000000..0970560e6c
--- /dev/null
+++ b/docs/harness/thread-settings.md
@@ -0,0 +1,144 @@
+---
+title: Store settings per thread
+id: harness-thread-settings
+order: 4
+description: "Store the model, reasoning, instructions, tools, plugins, and working folder of each thread, so the choice stays after a reload and a restart."
+keywords:
+  - tanstack ai
+  - harness
+  - settings
+  - configure
+  - model picker
+  - cwd
+---
+
+Each conversation in your app has its own choices: a faster model for one chat, extra instructions for another, a folder for a coding task. These choices must stay after a reload and a restart. `session.configure()` stores them with the thread, and every next turn uses them.
+
+## 1. Name the models a thread can pick
+
+Give the harness a `models` map. A thread picks a model by its name:
+
+```ts group=harness-thread-settings
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { anthropicText } from '@tanstack/ai-anthropic'
+
+export const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: anthropicText('claude-sonnet-5-5'),
+  models: {
+    fast: anthropicText('claude-haiku-4-5'),
+    strong: anthropicText('claude-opus-5-5'),
+  },
+  // The fields a client may change. See "Let the user pick".
+  expose: { settings: ['model', 'reasoning'] },
+})
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+```
+
+## 2. Store the settings of a thread
+
+```ts group=harness-thread-settings
+const session = await host.open(assistant, { threadId: 'review-thread' })
+
+const receipt = await session.configure({
+  model: 'strong',
+  reasoning: 'high',
+  instructions: 'Answer in French.',
+})
+console.log(receipt.status) // 'accepted'
+console.log(session.settings()) // { model: 'strong', reasoning: 'high', instructions: 'Answer in French.' }
+```
+
+The settings apply from the next turn. A field that you leave out stays as it is. Set a field to `null` to clear it:
+
+```ts group=harness-thread-settings
+await session.configure({ instructions: null })
+```
+
+The six fields:
+
+| Field | What it does |
+| --- | --- |
+| `model` | A name from `models`. |
+| `reasoning` | The reasoning level of every turn, as `chat({ reasoning })` takes it. |
+| `instructions` | Text added as the last system prompt of every turn. |
+| `tools` | Exactly these tools by name, or `{ remove: [names] }` for every tool but those. |
+| `plugins` | `{ remove: [names] }`: the turns leave out what those plugins give. |
+| `cwd` | The working folder of the thread. See [The working folder](#the-working-folder). |
+
+An unknown field, model, or plugin, or a bad value, gets a receipt with `status: 'rejected'` and the reason. `stores.metadata` keeps the settings, so they stay after a restart. Without a metadata store, they stay in memory. A [fork](./fork-and-reset) copies them.
+
+## 3. Let the user pick
+
+A client can change only the fields in `expose.settings` of the harness. The harness above exposes `model` and `reasoning`.
+
+- A client input with another field gets `status: 'rejected'` with the reason `not_exposed`. Nothing changes.
+- With no `expose.settings`, a client can change no field.
+- Server code that calls `session.configure()` can change every field.
+- Expose `plugins` and `instructions` only to clients that you trust. With them, a client can turn off a plugin (for example the one that asks for approvals) and write into the system prompt.
+
+`describe()` returns the stored `settings` and the names of the `models`, so a UI can build a menu. A client stores a choice with `client.configure()`:
+
+```ts group=harness-thread-settings-client
+import { createHarnessClient } from '@tanstack/ai-harness/client'
+import type { assistant } from './harness'
+
+const client = createHarnessClient<typeof assistant>({
+  url: '/api/harness',
+  threadId: 'review-thread',
+})
+
+const { models, settings } = await client.describe()
+console.log(models) // ['fast', 'strong']
+console.log(settings?.model)
+
+await client.configure({ model: 'fast' })
+```
+
+Over `POST control`, the same input is `{ op: 'configure', settings }`. It is an input, so the log keeps who changed what. Each change sends a `harness.settings.changed` event with the new `settings`.
+
+## What wins
+
+A turn can get its model from four places. The first one that is set wins:
+
+1. The `overrides.adapter` of the prompt. See [Give one prompt its own settings](./turn-control#give-one-prompt-its-own-settings).
+2. The stored `model`.
+3. A plugin `adapter()` pick. See [Pick the model of a turn](./plugins#pick-the-model-of-a-turn).
+4. The `adapter` of the harness.
+
+For `reasoning`, the `overrides` of the prompt win, then the stored setting, then the `reasoning` of the harness.
+
+## Tools and plugins
+
+- A `tools` list keeps only the tools with those names. `{ remove }` drops the tools with those names. Either way, the tools of the prompt `overrides` stay.
+- The harness applies `tools` before the plugins prepare the tool list. So [code mode](./code-mode) wraps only the tools that a thread keeps.
+- `plugins: { remove }` leaves the tools, prompts, middleware, and model pick of those plugins out of the turn. Plugins that run once per session stay mounted.
+- The agents and subagents that a removed plugin gives stay available.
+
+## The working folder
+
+`workspaceTools` work in the `cwd` of the thread. Relative paths start there, and `bash` runs there:
+
+```ts group=harness-thread-settings
+import { workspaceTools } from '@tanstack/ai-harness/plugins'
+
+export const coder = defineHarness({
+  name: 'acme/coder',
+  adapter: anthropicText('claude-sonnet-5-5'),
+  plugins: () => [workspaceTools({ root: '/srv/repos' })],
+})
+
+const task = await host.open(coder, { threadId: 'fix-login' })
+await task.configure({ cwd: 'web-app' })
+```
+
+`cwd` is relative to `root`. The tools refuse a working folder outside `root`. The coding agents of `@tanstack/ai-sandbox` get their folder from the sandbox, so they do not read `cwd`.
+
+## What you have now
+
+- A model menu per thread, from the `models` of the harness.
+- Instructions, reasoning, tools, and plugins that each thread keeps.
+- A working folder per thread for the workspace tools.
+- Settings that stay after a reload and a restart.
diff --git a/docs/harness/turn-control.md b/docs/harness/turn-control.md
index ae585aa09c..0b0cde331f 100644
--- a/docs/harness/turn-control.md
+++ b/docs/harness/turn-control.md
@@ -226,6 +226,8 @@ The session keeps the overrides in memory only. The session log does not store t
 - After a restart, recovery runs an unfinished turn with the harness settings.
 - A second prompt with the same `inputId` and message is a duplicate, also when its overrides are different.
 
+To keep a model or instructions for every turn of a thread, also after a restart, store them with `session.configure`. See [Store settings per thread](./thread-settings).
+
 ## What you have now
 
 - A turn that goes back to work until the job is done, with a limit.
diff --git a/docs/harness/usage.md b/docs/harness/usage.md
new file mode 100644
index 0000000000..8bfedd4145
--- /dev/null
+++ b/docs/harness/usage.md
@@ -0,0 +1,113 @@
+---
+title: Track usage and cost
+id: harness-usage
+order: 7
+description: "Read the tokens and the cost of a thread, in total, by model, and by sender. Show a live total, and stop a person who is over budget."
+keywords:
+  - tanstack ai
+  - harness
+  - usage
+  - cost
+  - tokens
+  - billing
+---
+
+Your app bills each person for what they use, or stops a thread that costs too much. For that, you need the tokens and the cost of every model call, per thread and per person. The harness adds up every model call of a thread, and `session.usage()` returns the totals.
+
+## Read the totals
+
+```ts group=harness-usage
+import { 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-5.6'),
+})
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+const session = await host.open(assistant, {
+  threadId: 'team-thread',
+  principal: { id: 'ada' },
+})
+
+await session.prompt('Summarize the open tickets.')
+
+const { total, byModel, bySender } = session.usage()
+console.log(total.calls, total.totalTokens, total.cost)
+console.log(byModel['openai/gpt-5.6']?.totalTokens, bySender.ada?.cost)
+```
+
+The totals have three groups. `snapshot().usage` has the same data:
+
+- `total`: every model call of the thread.
+- `byModel`: the calls of each model, keyed by `provider/model`, for example `openai/gpt-5.6`.
+- `bySender`: the calls of each person, keyed by the principal id. It has only the calls of a known sender, so its sum can be less than `total`.
+
+Each entry has `calls`, `promptTokens`, `completionTokens`, `totalTokens`, `cachedTokens`, and `cacheWriteTokens`. If a provider reported a cost, the entry also has `cost`. The harness adds the costs that the providers report, in their currency. It uses no price list of its own.
+
+## What counts
+
+At the end of each call, the provider reports its usage. These calls count:
+
+- The model calls of each turn, for the sender of that turn.
+- 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. In a [shared thread](./shared-threads), each message runs as its sender, so `bySender` shows what each person used.
+
+## Where the totals live
+
+The totals stay with the thread:
+
+- A durable host (with `stores.log`) keeps one `harness.usage` record per call in the log. The log keeps the totals after a restart.
+- Another host with `stores.metadata` keeps the totals there.
+- A host with neither keeps them in memory.
+
+A [fork of a thread](./fork-and-reset) starts at zero.
+
+## Show a live total
+
+Each call sends a `harness.usage` event on the operation that made the call. When the event arrives, read the new totals:
+
+```ts group=harness-usage-client
+import { createHarnessClient } from '@tanstack/ai-harness/client'
+import type { assistant } from './harness'
+
+const client = createHarnessClient<typeof assistant>({
+  url: '/api/harness',
+  threadId: 'team-thread',
+})
+
+for await (const { event } of client.events()) {
+  if (event.type === 'CUSTOM' && event.name === 'harness.usage') {
+    const { usage } = await client.snapshot()
+    console.log(`Tokens so far: ${usage.total.totalTokens}`)
+  }
+}
+```
+
+## Stop a person who is over budget
+
+Read the totals of the sender before you send a prompt. This route refuses a prompt from a person who used more than their budget:
+
+```ts group=harness-usage
+const BUDGET_USD = 5
+
+export async function send(threadId: string, userId: string, text: string) {
+  const thread = await host.open(assistant, { threadId })
+  const spent = thread.usage().bySender[userId]?.cost ?? 0
+  if (spent >= BUDGET_USD) {
+    return { error: 'You used your budget for this thread.' }
+  }
+  return thread.prompt(text, { principal: { id: userId } }).receipt
+}
+```
+
+## What you have now
+
+- The tokens and the cost of a thread, in total, by model, and by sender.
+- Totals that stay after a restart.
+- A live total in your UI, from the `harness.usage` event.
+- A budget check before each prompt.

From 6f3ea4ad6caebb872be2f7de272951b4a9b89fcb Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 18:00:03 +0200
Subject: [PATCH 231/286] chore: add changesets for usage, settings, fork,
 reset, and resumable agents

---
 .changeset/harness-recovered-resolve.md    |  6 ++++++
 .changeset/harness-reset.md                |  9 +++++++++
 .changeset/harness-resumable-agents.md     | 12 ++++++++++++
 .changeset/harness-thread-settings-fork.md | 12 ++++++++++++
 .changeset/harness-usage-totals.md         | 10 ++++++++++
 5 files changed, 49 insertions(+)
 create mode 100644 .changeset/harness-recovered-resolve.md
 create mode 100644 .changeset/harness-reset.md
 create mode 100644 .changeset/harness-resumable-agents.md
 create mode 100644 .changeset/harness-thread-settings-fork.md
 create mode 100644 .changeset/harness-usage-totals.md

diff --git a/.changeset/harness-recovered-resolve.md b/.changeset/harness-recovered-resolve.md
new file mode 100644
index 0000000000..9731f9ea0b
--- /dev/null
+++ b/.changeset/harness-recovered-resolve.md
@@ -0,0 +1,6 @@
+---
+'@tanstack/ai-harness': patch
+---
+
+- A resolve that a crash interrupted now continues the interrupted turn after the restart. Before, it ran without the id of the interrupted run, so `chat()` refused it, and it lost the routed plan, the sender, and the context of that turn.
+- On a host without a log, the transcript is saved before each model call. So when the model call after an approved tool fails, the result of that tool stays in the transcript.
diff --git a/.changeset/harness-reset.md b/.changeset/harness-reset.md
new file mode 100644
index 0000000000..2344a2f14d
--- /dev/null
+++ b/.changeset/harness-reset.md
@@ -0,0 +1,9 @@
+---
+'@tanstack/ai-harness': minor
+---
+
+`session.reset(note?)` starts a fresh model context and keeps the transcript.
+
+- From the next turn, the model sees only the note (when given) and what comes after the reset. `transcript()` keeps every message, plus a marker message with `metadata.harness.reset`. The session view shows the marker as a notice.
+- A reset is an input: it runs once per `inputId`, and it waits for a running turn to end. While the thread waits for interrupts, it is refused with `pending_interrupts`.
+- Clients send `{ op: 'reset', note }` or call `client.reset(note)`. A `harness.reset` event fires when it applies.
diff --git a/.changeset/harness-resumable-agents.md b/.changeset/harness-resumable-agents.md
new file mode 100644
index 0000000000..7c77ee3018
--- /dev/null
+++ b/.changeset/harness-resumable-agents.md
@@ -0,0 +1,12 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-harness': minor
+---
+
+A background agent can continue on the host that takes over after a crash.
+
+- `agents.start(agent, input, { resume: true })` needs a durable host (`stores.log`). Without one, it throws at start. Without `resume`, an agent that a stopped host left running still fails, as before.
+- The next host runs the agent again with the same input. Its model calls continue from the saved transcript, and its finished tool calls do not run again.
+- `ctx.step.do(name, fn)` in agent code keeps the result of `fn` in the log, so a side effect does not run again when the agent runs again.
+- `durability.maxAttempts` caps the runs. After the cap, the run settles `failed` with the code `attempts_exhausted`.
+- In `@tanstack/ai`, the agent run context has `step`, and `SubagentBinding` takes an optional `step`. Without a binding, `step.do` runs `fn` each time.
diff --git a/.changeset/harness-thread-settings-fork.md b/.changeset/harness-thread-settings-fork.md
new file mode 100644
index 0000000000..97bdcbdc5f
--- /dev/null
+++ b/.changeset/harness-thread-settings-fork.md
@@ -0,0 +1,12 @@
+---
+'@tanstack/ai-harness': minor
+---
+
+Stored settings per thread, and a fork of a thread.
+
+- `defineHarness({ models: { fast, strong } })` names the models a thread can pick.
+- `session.configure({ model, reasoning, instructions, tools, plugins, cwd })` stores settings for the thread, from the next turn. `null` clears a field. An unknown model, plugin or bad value gets a rejected receipt. Turn `overrides` still win over the settings.
+- A client can change only the fields in `defineHarness({ expose: { settings } })`. An input with another field is refused with `not_exposed`, and with no list a client can change no field. Server code that calls `session.configure()` can change every field.
+- `session.settings()` reads them, `describe()` lists them with the model names, and a `harness.settings.changed` event fires on each change. Clients send `{ op: 'configure', settings }` or call `client.configure(settings)`.
+- `workspaceTools` work in the thread's `cwd`, and refuse a folder outside their root.
+- `host.fork(harness, { threadId, newThreadId, at?, principal? })` copies the transcript up to the message `at` into a new thread, with its stored settings, plugin config and media. It does not copy plugin state, pending interrupts, queued inputs or usage totals.
diff --git a/.changeset/harness-usage-totals.md b/.changeset/harness-usage-totals.md
new file mode 100644
index 0000000000..ddae9eb3bd
--- /dev/null
+++ b/.changeset/harness-usage-totals.md
@@ -0,0 +1,10 @@
+---
+'@tanstack/ai-harness': minor
+---
+
+A harness session keeps usage totals for its thread.
+
+- `session.usage()` and `snapshot().usage` return `{ total, byModel, bySender }`. Each entry has `calls`, the token counts, and `cost` when a provider reported one.
+- Every model call counts: the turn's own calls, its subagents, and background agents, for the sender of the turn or the person who started the agent.
+- A durable host keeps a `harness.usage` record per call in the log. Other hosts keep the totals in `stores.metadata`, or in memory without one.
+- A `harness.usage` event fires on each call, so a UI can show a live total.

From bf329d5e3e29d8ae3b7ebb932a5628dc2e968d01 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 16:42:39 +0200
Subject: [PATCH 232/286] fix(ai): run a tool with no input or null arguments
 as {} again

The final tool input check kept a missing or literal null argument and
checked it against the schema, so a tool with no required fields did not
run when the model sent an empty tool_use block. That broke the fix for
issue #265, and its E2E test failed.

No input is {} again. A null that the schema rejects is checked as {}.
Other values, such as 2 or [1,2], must still fit the schema.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/ai-null-tool-input.md              |   5 +
 .../src/activities/chat/tools/tool-calls.ts   |  71 +++++++-----
 .../tests/client-tool-boundary-inputs.test.ts |  20 ++--
 .../ai/tests/tool-calls-null-input.test.ts    | 101 +++++++++++++-----
 .../ai/tests/tool-input-validation.test.ts    |  13 ++-
 5 files changed, 145 insertions(+), 65 deletions(-)
 create mode 100644 .changeset/ai-null-tool-input.md

diff --git a/.changeset/ai-null-tool-input.md b/.changeset/ai-null-tool-input.md
new file mode 100644
index 0000000000..2445fb5c58
--- /dev/null
+++ b/.changeset/ai-null-tool-input.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai': patch
+---
+
+Run a tool again when the model sends no input or a literal `null` for a tool with no required fields (an empty tool_use block, issue #265). The final tool input check rejected these, so the tool did not run. Now no input is `{}`, and a `null` that the schema rejects is checked as `{}`. Other values must still fit the schema.
diff --git a/packages/ai/src/activities/chat/tools/tool-calls.ts b/packages/ai/src/activities/chat/tools/tool-calls.ts
index 662b0e6dc7..c65b20ce58 100644
--- a/packages/ai/src/activities/chat/tools/tool-calls.ts
+++ b/packages/ai/src/activities/chat/tools/tool-calls.ts
@@ -52,6 +52,36 @@ function safeJsonParse(value: string): unknown {
   }
 }
 
+/**
+ * Parse tool call arguments. A model can send no input for a tool with no
+ * required fields (an empty tool_use block, issue #265): that is `{}`.
+ */
+function parseToolArguments(raw: string): unknown {
+  const text = raw.trim()
+  return text === '' ? {} : JSON.parse(text)
+}
+
+/**
+ * The final check of a tool input. A literal `null` from the model is also an
+ * empty tool_use block (issue #265): when the schema rejects `null`, the input
+ * is `{}`. Other values must fit the schema as they are.
+ */
+async function checkToolInput(
+  tool: Pick<Tool, 'inputSchema' | 'name'>,
+  input: unknown,
+) {
+  try {
+    return await validateToolInput(tool.inputSchema, input, tool.name)
+  } catch (error) {
+    if (input !== null) throw error
+    try {
+      return await validateToolInput(tool.inputSchema, {}, tool.name)
+    } catch {
+      throw error
+    }
+  }
+}
+
 /** Marks the synthetic tool that runs a subagent. */
 export const SUBAGENT_TOOL = Symbol.for('tanstack.ai.subagentTool')
 
@@ -409,17 +439,14 @@ export class ToolCallManager<
           // Keep the parsed value so the schema can check its type.
           let args: unknown
           try {
-            const argsString =
-              toolCall.function.arguments.trim() ||
-              (tool.inputSchema === undefined ? '{}' : '')
-            args = JSON.parse(argsString)
+            args = parseToolArguments(toolCall.function.arguments)
           } catch (parseError) {
             throw new Error(
               `Failed to parse tool arguments as JSON: ${toolCall.function.arguments}`,
             )
           }
 
-          args = await validateToolInput(tool.inputSchema, args, tool.name)
+          args = await checkToolInput(tool, args)
 
           // Execute the tool
           const executionContext = {
@@ -1079,24 +1106,20 @@ export async function* executeToolCalls<TContext = unknown>(
 
     // Parse arguments
     let input: unknown = {}
-    const argsStr =
-      toolCall.function.arguments.trim() ||
-      (tool.inputSchema === undefined ? '{}' : '')
-    if (argsStr || tool.inputSchema !== undefined) {
-      try {
-        input = JSON.parse(argsStr)
-      } catch {
-        results.push({
-          toolCallId: toolCall.id,
-          toolName,
-          result: {
-            error: `Failed to parse tool arguments as JSON: ${argsStr}`,
-          },
-          input,
-          state: 'output-error',
-        })
-        continue
-      }
+    const argsStr = toolCall.function.arguments.trim()
+    try {
+      input = parseToolArguments(argsStr)
+    } catch {
+      results.push({
+        toolCallId: toolCall.id,
+        toolName,
+        result: {
+          error: `Failed to parse tool arguments as JSON: ${argsStr}`,
+        },
+        input,
+        state: 'output-error',
+      })
+      continue
     }
 
     const resolution = tool.needsApproval
@@ -1144,7 +1167,7 @@ export async function* executeToolCalls<TContext = unknown>(
       input = decision.input
     }
     try {
-      input = await validateToolInput(tool.inputSchema, input, tool.name)
+      input = await checkToolInput(tool, input)
     } catch (error) {
       const message =
         error instanceof Error ? error.message : 'Validation failed'
diff --git a/packages/ai/tests/client-tool-boundary-inputs.test.ts b/packages/ai/tests/client-tool-boundary-inputs.test.ts
index be9534ceac..8f22b0a5f0 100644
--- a/packages/ai/tests/client-tool-boundary-inputs.test.ts
+++ b/packages/ai/tests/client-tool-boundary-inputs.test.ts
@@ -883,9 +883,11 @@ describe('client input at interrupt boundaries', () => {
   )
 })
 
+// A model sends no input for a tool with no required fields (an empty
+// tool_use block, issue #265). That is `{}`, so the call is dispatched.
 describe('empty schema-bearing client arguments', () => {
   it.each([false, true])(
-    'does not dispatch an empty client or approval call: approval=%s',
+    'dispatches an empty client or approval call with {}: approval=%s',
     async (needsApproval) => {
       for (const raw of ['', '  ']) {
         const { adapter } = createMockAdapter({
@@ -911,19 +913,15 @@ describe('empty schema-bearing client arguments', () => {
             tools: [client({ type: 'object', properties: {} }, needsApproval)],
           }),
         )
-        expect(descriptors(chunks)).toEqual([])
-        expect(
-          chunks.some(
-            (event) =>
-              event.type === EventType.TOOL_CALL_RESULT ||
-              event.type === EventType.RUN_ERROR,
-          ),
-        ).toBe(true)
+        expect(descriptors(chunks)).toHaveLength(1)
+        expect(chunks.some((event) => event.type === EventType.RUN_ERROR)).toBe(
+          false,
+        )
       }
     },
   )
   it.each([false, true])(
-    'rejects copied empty historical arguments before resumed client dispatch: approval=%s',
+    'dispatches copied empty historical arguments with {} and keeps them raw: approval=%s',
     async (needsApproval) => {
       for (const raw of ['', '  ']) {
         const messages: Array<ModelMessage> = [
@@ -950,7 +948,7 @@ describe('empty schema-bearing client arguments', () => {
             tools: [client({ type: 'object', properties: {} }, needsApproval)],
           }),
         )
-        expect(descriptors(chunks)).toEqual([])
+        expect(descriptors(chunks)).toHaveLength(1)
         expect(messages[0]?.toolCalls?.[0]?.function.arguments).toBe(raw)
       }
     },
diff --git a/packages/ai/tests/tool-calls-null-input.test.ts b/packages/ai/tests/tool-calls-null-input.test.ts
index 2599ddd7c6..e76ec5eb3d 100644
--- a/packages/ai/tests/tool-calls-null-input.test.ts
+++ b/packages/ai/tests/tool-calls-null-input.test.ts
@@ -326,7 +326,52 @@ describe('authoritative terminal snapshots', () => {
 })
 
 describe('terminal raw schema execution', () => {
-  it.each(['', '  ', 'null', '2', '[1,2]'])(
+  // No input or a literal null is an empty tool_use block (issue #265): the
+  // tool runs with {}.
+  it.each(['', '  ', 'null'])(
+    'runs no input or null with {} against an optional-only object schema: %j',
+    async (raw) => {
+      let received: unknown = 'not called'
+      const { adapter } = createMockAdapter({
+        iterations: [
+          [
+            ev.runStarted(),
+            ev.toolStart('raw-call', 'check'),
+            {
+              type: EventType.TOOL_CALL_END,
+              toolCallId: 'raw-call',
+              args: raw,
+              timestamp: 0,
+            },
+            ev.runFinished('tool_calls'),
+          ],
+          [ev.runStarted('second'), ev.runFinished()],
+        ],
+      })
+      await collectChunks(
+        chat({
+          adapter,
+          messages: [{ role: 'user', content: 'Check' }],
+          tools: [
+            {
+              name: 'check',
+              description: 'Check',
+              inputSchema: {
+                type: 'object',
+                properties: { optional: { type: 'string' } },
+              },
+              execute(input: unknown) {
+                received = input
+                return 'ok'
+              },
+            },
+          ],
+        }),
+      )
+      expect(received).toEqual({})
+    },
+  )
+  it.each(['2', '[1,2]'])(
     'rejects full terminal JSON against an optional-only object schema: %s',
     async (raw) => {
       let executions = 0
@@ -539,35 +584,33 @@ describe('authored terminal validation', () => {
 })
 
 describe('schema-bearing empty dispatcher input', () => {
-  it.each(['', '  '])(
-    'rejects empty raw input before dispatch: %j',
-    async (raw) => {
-      let executions = 0
-      const call: ToolCall = {
-        id: 'empty',
-        type: 'function',
-        function: { name: 'check', arguments: raw },
-      }
-      const result = await drainGenerator(
-        executeToolCalls(
-          [call],
-          [
-            {
-              name: 'check',
-              description: 'Check',
-              inputSchema: { type: 'object', properties: {} },
-              execute() {
-                executions++
-                return 'wrong'
-              },
+  // No input from the model is an empty tool_use block (issue #265): {}.
+  it.each(['', '  '])('runs empty raw input once with {}: %j', async (raw) => {
+    let executions = 0
+    const call: ToolCall = {
+      id: 'empty',
+      type: 'function',
+      function: { name: 'check', arguments: raw },
+    }
+    const result = await drainGenerator(
+      executeToolCalls(
+        [call],
+        [
+          {
+            name: 'check',
+            description: 'Check',
+            inputSchema: { type: 'object', properties: {} },
+            execute(input: unknown) {
+              executions++
+              return input
             },
-          ],
-        ),
-      )
-      expect(executions).toBe(0)
-      expect(result.results[0]?.state).toBe('output-error')
-    },
-  )
+          },
+        ],
+      ),
+    )
+    expect(executions).toBe(1)
+    expect(result.results[0]?.result).toEqual({})
+  })
   it('dispatches a valid explicit empty object once', async () => {
     let executions = 0
     const call: ToolCall = {
diff --git a/packages/ai/tests/tool-input-validation.test.ts b/packages/ai/tests/tool-input-validation.test.ts
index b25ad6edbe..9ecfd323ec 100644
--- a/packages/ai/tests/tool-input-validation.test.ts
+++ b/packages/ai/tests/tool-input-validation.test.ts
@@ -158,8 +158,19 @@ describe('tool input validation', () => {
     },
   )
 
-  it('rejects null for an explicit object schema', async () => {
+  it('runs null as {} for an object schema with no required fields', async () => {
+    // A literal null is an empty tool_use block (issue #265).
     const result = await runTool(null, { type: 'object', properties: {} })
+    expect(result.results[0]?.input).toEqual({})
+    expect(result.executions).toBe(1)
+  })
+
+  it('rejects null for an object schema with required fields', async () => {
+    const result = await runTool(null, {
+      type: 'object',
+      properties: { city: { type: 'string' } },
+      required: ['city'],
+    })
     expect(result.results[0]?.state).toBe('output-error')
     expect(result.executions).toBe(0)
   })

From c1e9fdad8c73004214f4f770bdeeca283e8eadcc Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 18:04:22 +0200
Subject: [PATCH 233/286] fix(ai): record no execute_tool span for a client
 tool

The final tool input check now runs onBeforeToolCall before a client
tool is dispatched, so otelMiddleware opened an execute_tool span for a
tool the server does not run. The client-tool wait E2E test then saw two
root spans.

otelMiddleware skips the span for a known tool with no execute. The
unit test is back to main's chat and iteration spans.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/otel-client-tool-span.md             | 5 +++++
 packages/ai/src/middlewares/otel.ts             | 3 +++
 packages/ai/tests/chat-client-tool-wait.test.ts | 2 +-
 3 files changed, 9 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/otel-client-tool-span.md

diff --git a/.changeset/otel-client-tool-span.md b/.changeset/otel-client-tool-span.md
new file mode 100644
index 0000000000..1492e6ebb8
--- /dev/null
+++ b/.changeset/otel-client-tool-span.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai': patch
+---
+
+Do not record an `execute_tool` span for a client tool in `otelMiddleware`. Middleware now sees a client tool's input before dispatch, so the middleware opened a span for a tool that the server does not run. A client tool runs in the client, so the server records only the chat and iteration spans, as before.
diff --git a/packages/ai/src/middlewares/otel.ts b/packages/ai/src/middlewares/otel.ts
index cef80e2e8d..00994530f7 100644
--- a/packages/ai/src/middlewares/otel.ts
+++ b/packages/ai/src/middlewares/otel.ts
@@ -899,6 +899,9 @@ export function otelMiddleware(
 
     onBeforeToolCall(ctx, hookCtx) {
       safeCall('otel.onBeforeToolCall', () => {
+        // A client tool runs in the client, not here, so it gets no
+        // execute_tool span. Middleware sees its input before dispatch.
+        if (hookCtx.tool && !hookCtx.tool.execute) return
         const state = stateByCtx.get(ctx)
         if (!state) return
         const parent = state.currentIterationSpan ?? state.rootSpan
diff --git a/packages/ai/tests/chat-client-tool-wait.test.ts b/packages/ai/tests/chat-client-tool-wait.test.ts
index 6e6fe16f34..24ee54158d 100644
--- a/packages/ai/tests/chat-client-tool-wait.test.ts
+++ b/packages/ai/tests/chat-client-tool-wait.test.ts
@@ -214,10 +214,10 @@ describe('client-tool wait lifecycle', () => {
       }),
     )
 
+    // The client runs the tool, so the server records no execute_tool span.
     expect(fakeTracer.spans.map((span) => span.name)).toEqual([
       'chat test-model',
       'chat test-model #0',
-      'execute_tool ask_client',
     ])
     expect(fakeTracer.spans.every((span) => span.ended)).toBe(true)
     expect(

From f02f0ddcd08f073e9c4c41edf388fe4eac87e0c0 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 18:04:22 +0200
Subject: [PATCH 234/286] test(e2e): keep two scenarios true under the final
 tool input check

The client-tool input error scenarios sent message: 42. The final input
check now coerces scalar types, so 42 became "42" and passed, and the
client ran the tool. The scenarios now omit the required message, which
is invalid with or without coercion.

The sandbox persistence spec now expects the runId and source that the
chat run records on the saved assistant message.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 testing/e2e/src/routes/api.tools-test.ts           |  6 ++++--
 testing/e2e/tests/sandbox-file-persistence.spec.ts | 11 +++++++++--
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/testing/e2e/src/routes/api.tools-test.ts b/testing/e2e/src/routes/api.tools-test.ts
index b4e93d0ab4..9e35b32332 100644
--- a/testing/e2e/src/routes/api.tools-test.ts
+++ b/testing/e2e/src/routes/api.tools-test.ts
@@ -65,9 +65,11 @@ function createProviderFreeAdapter(scenario: string): AnyTextAdapter {
           : scenario === 'client-tool-input-error' ||
               scenario === 'invalid-client-tool-retry'
             ? {
-                arguments: '{"message":42,"type":"info"}',
+                // No `message`: invalid even after the input check coerces
+                // scalar types (42 would become "42" and pass).
+                arguments: '{"type":"info"}',
                 initialText: 'Showing a notification.',
-                input: { message: 42, type: 'info' },
+                input: { type: 'info' },
                 name:
                   scenario === 'invalid-client-tool-retry'
                     ? 'invalid-client-tool-retry-test'
diff --git a/testing/e2e/tests/sandbox-file-persistence.spec.ts b/testing/e2e/tests/sandbox-file-persistence.spec.ts
index e5c36f3ad4..4ccce25e5a 100644
--- a/testing/e2e/tests/sandbox-file-persistence.spec.ts
+++ b/testing/e2e/tests/sandbox-file-persistence.spec.ts
@@ -46,8 +46,15 @@ test.describe('sandbox portable file snapshots', () => {
           content: 'automatic conversation',
           createdAt: expect.any(String),
           id: 'automatic-message',
-          // withPersistence records the run that produced the message.
-          metadata: { tanstack: { run: { id: 'recover' } } },
+          // withPersistence records the run that produced the message. The
+          // chat run records its id and the provider, API and model it used.
+          metadata: {
+            tanstack: {
+              run: { id: 'recover' },
+              runId: 'recover',
+              source: { provider: 'fixed', api: 'text', model: 'test-model' },
+            },
+          },
           role: 'assistant',
         },
       ],

From f07b75e0a951220f7be4541ffbe47e1ba5a516dd Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 18:14:24 +0200
Subject: [PATCH 235/286] test(e2e): count only this turn's tool results in the
 tools-test adapter

Replay now gives an unanswered tool call from an earlier turn a
"No result provided" result. The provider-free adapter counted every
tool message, so after Stop the next user turn answered with text and
ended before the race test could press Stop again.
---
 testing/e2e/src/routes/api.tools-test.ts | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/testing/e2e/src/routes/api.tools-test.ts b/testing/e2e/src/routes/api.tools-test.ts
index 9e35b32332..4c2b114db4 100644
--- a/testing/e2e/src/routes/api.tools-test.ts
+++ b/testing/e2e/src/routes/api.tools-test.ts
@@ -126,9 +126,15 @@ function createProviderFreeAdapter(scenario: string): AnyTextAdapter {
       const runId = options.runId ?? 'runtime-context-run'
       const threadId = options.threadId ?? 'runtime-context-thread'
       const messageId = `${runId}-message`
-      const toolResultCount = options.messages.filter(
-        (message) => message.role === 'tool',
-      ).length
+      // Count only this turn's results. Replay gives an unanswered call from
+      // an earlier turn a "No result provided" result, and a new user turn
+      // must still call the tool again.
+      const lastUserIndex = options.messages
+        .map((message) => message.role)
+        .lastIndexOf('user')
+      const toolResultCount = options.messages
+        .slice(lastUserIndex + 1)
+        .filter((message) => message.role === 'tool').length
       const hasToolResult = toolResultCount > 0
       const retryClientTool =
         scenario === 'invalid-client-tool-retry' && toolResultCount === 1

From 8092599302ae67409e5ea6cdcf80e9695ff06dc3 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 18:38:34 +0200
Subject: [PATCH 236/286] test: expect no input and null tool arguments to run
 as {} in adapter replay tests

The #265 fix runs a tool with no input or a literal null as {}. Five
adapter replay-parity tests still expected those inputs to be rejected.
They now check that the tool runs with {}, or that the call goes to the
client. Other scalars and malformed JSON are still rejected.

Mistral ends whitespace-only arguments with a parse error before the
input check, so that case still runs 0 times.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .../ai-gemini/tests/replay-parity.test.ts     |  8 +++++++-
 .../ai-mistral/tests/replay-parity.test.ts    | 12 ++++++-----
 .../ai-ollama/tests/replay-parity.test.ts     | 13 +++---------
 .../ai-openrouter/tests/replay-parity.test.ts | 20 ++++++++++++++-----
 .../openai-base/tests/replay-parity.test.ts   |  3 ++-
 5 files changed, 34 insertions(+), 22 deletions(-)

diff --git a/packages/ai-gemini/tests/replay-parity.test.ts b/packages/ai-gemini/tests/replay-parity.test.ts
index d7819bd201..e081faba8d 100644
--- a/packages/ai-gemini/tests/replay-parity.test.ts
+++ b/packages/ai-gemini/tests/replay-parity.test.ts
@@ -444,7 +444,8 @@ describe('Gemini replay parity', () => {
         (request: Parameters<GoogleGenAI['interactions']['create']>[0]) =>
           sdk.interactions.create(request),
       )
-      for (const raw of ['', '  ', '{"value":']) {
+      // No input runs as {} (issue #265), so '' and '  ' are not in this list.
+      for (const raw of ['{"value":']) {
         const events = [
           {
             event_type: 'interaction.created',
@@ -619,6 +620,11 @@ describe('Gemini replay parity', () => {
             expect(execute).toHaveBeenCalledTimes(1)
             expect(execute.mock.calls[0]?.[0]).toEqual(value)
             expect(validate).toHaveBeenCalledTimes(1)
+          } else if (value === null) {
+            // A null that the schema rejects runs as {} (issue #265).
+            if (client)
+              expect(JSON.stringify(chunks)).toContain('client_tool_call')
+            else expect(execute.mock.calls[0]?.[0]).toEqual({})
           } else {
             expect(execute).not.toHaveBeenCalled()
             expect(JSON.stringify(chunks)).not.toContain('client_tool_call')
diff --git a/packages/ai-mistral/tests/replay-parity.test.ts b/packages/ai-mistral/tests/replay-parity.test.ts
index 7b4a5c99ea..10028829a0 100644
--- a/packages/ai-mistral/tests/replay-parity.test.ts
+++ b/packages/ai-mistral/tests/replay-parity.test.ts
@@ -557,11 +557,13 @@ describe('Mistral replay parity', () => {
 })
 
 describe('Mistral empty terminal tool arguments', () => {
+  // No input runs as {} (issue #265). The adapter fails on whitespace-only
+  // arguments before the input check.
   it.each([
-    { withSchema: true, raw: '' },
-    { withSchema: true, raw: '   ' },
-    { withSchema: false, raw: '' },
-  ])('keeps empty raw input: %j', async ({ withSchema, raw }) => {
+    { withSchema: true, raw: '', runs: 1 },
+    { withSchema: true, raw: '   ', runs: 0 },
+    { withSchema: false, raw: '', runs: 1 },
+  ])('keeps empty raw input: %j', async ({ withSchema, raw, runs }) => {
     let requests = 0
     let executions = 0
     vi.stubGlobal('fetch', async () => {
@@ -622,7 +624,7 @@ describe('Mistral empty terminal tool arguments', () => {
       ],
     }))
       chunks.push(chunk)
-    expect(executions).toBe(withSchema ? 0 : 1)
+    expect(executions).toBe(runs)
     expect(
       chunks.find((chunk) => chunk.type === 'TOOL_CALL_END')?.metadata?.tanstack
         ?.args,
diff --git a/packages/ai-ollama/tests/replay-parity.test.ts b/packages/ai-ollama/tests/replay-parity.test.ts
index 7bcbc0259f..fb82ac6ea4 100644
--- a/packages/ai-ollama/tests/replay-parity.test.ts
+++ b/packages/ai-ollama/tests/replay-parity.test.ts
@@ -113,16 +113,9 @@ describe('Ollama replay parity', () => {
   it.each([false, true])(
     'rejects invalid raw input before server or client dispatch for doneOnly=%s',
     async (doneOnly) => {
-      for (const raw of [
-        '7',
-        'false',
-        'null',
-        '"value"',
-        '[1]',
-        '{"n":',
-        '',
-        '  ',
-      ]) {
+      // No input or a literal null runs as {} (issue #265), so they are not
+      // in this list.
+      for (const raw of ['7', 'false', '"value"', '[1]', '{"n":']) {
         for (const client of [false, true]) {
           const mock = sdk(
             doneOnly
diff --git a/packages/ai-openrouter/tests/replay-parity.test.ts b/packages/ai-openrouter/tests/replay-parity.test.ts
index b63801c3f3..8cf807ace7 100644
--- a/packages/ai-openrouter/tests/replay-parity.test.ts
+++ b/packages/ai-openrouter/tests/replay-parity.test.ts
@@ -519,7 +519,7 @@ describe('native OpenRouter replay parity', () => {
                 },
               ]
         const mock = sdk(api, events)
-        const execute = vi.fn(async () => 'never')
+        const execute = vi.fn(async (_input: unknown) => 'never')
         const chunks = await collect(
           chat({
             adapter: mock.adapter,
@@ -537,11 +537,16 @@ describe('native OpenRouter replay parity', () => {
             ],
           }),
         )
-        expect(execute).not.toHaveBeenCalled()
+        if (value === null) {
+          // A null that the schema rejects runs as {} (issue #265).
+          expect(execute.mock.calls[0]?.[0]).toEqual({})
+        } else {
+          expect(execute).not.toHaveBeenCalled()
+          expect(JSON.stringify(chunks)).toContain('Received arguments')
+        }
         expect(
           chunks.find((chunk) => chunk.type === EventType.TOOL_CALL_END),
         ).toMatchObject({ input: value })
-        expect(JSON.stringify(chunks)).toContain('Received arguments')
         expect(JSON.stringify(mock.bodies)).toContain(
           args.replaceAll('"', '\\"'),
         )
@@ -603,8 +608,13 @@ describe('native OpenRouter replay parity', () => {
             ],
           }),
         )
-        expect(JSON.stringify(chunks)).not.toContain('client_tool_call')
-        expect(JSON.stringify(chunks)).toContain('Received arguments')
+        if (value === null) {
+          // A null that the schema rejects runs as {} (issue #265).
+          expect(JSON.stringify(chunks)).toContain('client_tool_call')
+        } else {
+          expect(JSON.stringify(chunks)).not.toContain('client_tool_call')
+          expect(JSON.stringify(chunks)).toContain('Received arguments')
+        }
         const accepted = sdk(api, events)
         const validate = vi.fn((input: unknown) => ({ value: input }))
         const execute = vi.fn(async (input: unknown) => input)
diff --git a/packages/openai-base/tests/replay-parity.test.ts b/packages/openai-base/tests/replay-parity.test.ts
index f9fbce2383..0f9a8c46be 100644
--- a/packages/openai-base/tests/replay-parity.test.ts
+++ b/packages/openai-base/tests/replay-parity.test.ts
@@ -329,7 +329,8 @@ describe('OpenAI replay parity', () => {
   it.each([false, true])(
     'rejects raw wrong-type and malformed inputs before dispatch for Responses=%s',
     async (responses) => {
-      for (const raw of ['7', 'false', 'null', '\"text\"', '[1]', '{\"n\":']) {
+      // A literal null runs as {} (issue #265), so it is not in this list.
+      for (const raw of ['7', 'false', '\"text\"', '[1]', '{\"n\":']) {
         for (const client of [false, true]) {
           const item = {
             type: 'function_call',

From 15868e69396dea1ea69c22c7ed3141aa5c8d1d9c Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Mon, 5 Oct 2026 18:48:03 +0200
Subject: [PATCH 237/286] test(ai-compaction): cover part text in the summary
 prompt and after-turn summary usage

Two new functions had no test, so the Coverage job saw function coverage
for ai-compaction drop from 100% to 97.43%:

- contentText in conversationSummarizer, for content that is a list of
  parts.
- The addUsage callback of the after-turn check, for a summarizer that
  reports usage.

Each new test fails when its function is broken.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-compaction/src/index.test.ts | 45 ++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/packages/ai-compaction/src/index.test.ts b/packages/ai-compaction/src/index.test.ts
index 48439fd6ba..fd15658264 100644
--- a/packages/ai-compaction/src/index.test.ts
+++ b/packages/ai-compaction/src/index.test.ts
@@ -1695,6 +1695,28 @@ describe('after-turn check', () => {
     )
   })
 
+  it('records the usage of the summary call after the turn', async () => {
+    const appended: Array<unknown> = []
+    const mw = withCompaction({
+      maxTokens: 1000,
+      contextWindow: 100,
+      countTokens: 'usage',
+      durable: true,
+      strategy: summarizeOldest({
+        summarize: async () => ({
+          summary: 'the gist',
+          usage: tokenUsage(12, 3),
+        }),
+        keepRecentTokens: 50,
+      }),
+    })
+    await finishTurn(mw, durableContext(appended).ctx, 110)
+
+    expect(appended).toMatchObject([
+      { reason: 'after-turn', usage: tokenUsage(12, 3) },
+    ])
+  })
+
   it('compacts after the turn over maxTokens when auto is on', async () => {
     const appended: Array<unknown> = []
     const mw = withCompaction({
@@ -2267,6 +2289,29 @@ describe('conversationSummarizer', () => {
     expect(userOf(requests[0])).toContain('[Assistant]: done')
   })
 
+  it('writes text parts and a tag for each other part', async () => {
+    const { fake, requests } = fakeSummaryModel()
+    await conversationSummarizer({ adapter: fake })(
+      [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', content: 'look at this' },
+            {
+              type: 'image',
+              source: { type: 'url', value: 'https://x/y.png' },
+            },
+          ],
+        },
+        { role: 'assistant', content: null },
+      ],
+      {},
+    )
+
+    expect(userOf(requests[0])).toContain('[User]: look at this\\n[image]')
+    expect(userOf(requests[0])).toContain('[Assistant]: ')
+  })
+
   it('uses the update prompt and leaves the earlier summary out of the conversation', async () => {
     const { fake, requests } = fakeSummaryModel()
     const earlier: ModelMessage = {

From 432bc5d7db736dd6a65fd4b51b19d6eeb000b0ef Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 09:10:16 +0200
Subject: [PATCH 238/286] feat(ai, ai-harness, ai-persistence): add the first
 opencode primitives

Checkpoint of the finished nodes of the opencode primitives plan.

- ai: toolChoice in chat() and onConfig (C1 core). onAfterToolCall can
  replace a tool result (C2). One `subagent` tool mode, with input or
  prompt, sessionId, and background (C6 core).
- ai-persistence: SessionIndexStore contract, memory store, and
  conformance cases (C4). The recorder indexes child runs and provides
  a scoped loadChild service (C6).
- ai-harness: toolExecution option (F4). Permission rules reach
  subagents (F1). ctx.session.note and prepareTools({ tools, model }).
  List, cancel, and move waiting inputs (C3). host.sessions, the
  sessions routes, and the client helpers (C4). Permissions v2 with
  resources and saved answers (PL2).
- ai-harness/plugins/coding: new Node-only entry. workspaceTools moved
  there and runs on a WorkspaceBackend, with WorkspaceHooks (C7).
---
 docs/harness/coding-agent.md                  |   2 +-
 docs/harness/goal.md                          |   3 +-
 .../harness-cli-cloudflare/src/harness.ts     |   2 +-
 examples/harness-cli/src/harness.ts           |   2 +-
 packages/ai-code-mode/src/harness.ts          |   2 +-
 packages/ai-harness-cli/tests/printer.test.ts |   1 +
 packages/ai-harness/package.json              |  18 +-
 packages/ai-harness/src/client.ts             | 101 +++-
 packages/ai-harness/src/commands.ts           |  28 +
 packages/ai-harness/src/define.ts             |   7 +
 .../src/first-party/coding/backend.ts         | 205 +++++++
 .../ai-harness/src/first-party/coding/bash.ts |  34 ++
 .../ai-harness/src/first-party/coding/edit.ts |  67 +++
 .../src/first-party/coding/index.ts           |   7 +
 .../ai-harness/src/first-party/coding/read.ts |  57 ++
 .../src/first-party/coding/search.ts          | 105 ++++
 .../src/first-party/coding/workspace.ts       | 202 +++++++
 packages/ai-harness/src/first-party/glob.ts   |  14 +
 packages/ai-harness/src/first-party/index.ts  |   7 +-
 .../ai-harness/src/first-party/permissions.ts | 485 +++++++++++++++--
 .../src/first-party/workspace-hooks.ts        |  32 ++
 .../ai-harness/src/first-party/workspace.ts   | 392 --------------
 packages/ai-harness/src/host.ts               | 161 +++++-
 packages/ai-harness/src/http.ts               |  97 ++++
 packages/ai-harness/src/index.ts              |   9 +
 packages/ai-harness/src/log.ts                |  15 +
 packages/ai-harness/src/plugins.ts            |  13 +-
 packages/ai-harness/src/protocol.ts           |  14 +
 packages/ai-harness/src/session.ts            | 500 +++++++++++++++---
 packages/ai-harness/src/types.ts              |  35 ++
 packages/ai-harness/src/view/index.ts         |   2 +-
 packages/ai-harness/src/view/reduce.ts        |  21 +-
 packages/ai-harness/src/view/types.ts         |   4 +-
 .../ai-harness/tests/agent-middleware.test.ts |  46 +-
 .../ai-harness/tests/coding-backend.test.ts   | 112 ++++
 packages/ai-harness/tests/define.test.ts      |  55 +-
 .../ai-harness/tests/durable-inputs.test.ts   | 289 ++++++++--
 packages/ai-harness/tests/edge-safety.test.ts |  14 +-
 packages/ai-harness/tests/first-party.test.ts |   4 +-
 packages/ai-harness/tests/permissions.test.ts | 435 +++++++++++++++
 packages/ai-harness/tests/plugin-apis.test.ts |  88 +++
 .../ai-harness/tests/prepare-tools.test.ts    |   4 +-
 packages/ai-harness/tests/protocol.test.ts    | 144 +++--
 .../ai-harness/tests/sessions-index.test.ts   | 429 +++++++++++++++
 packages/ai-harness/tests/view-reduce.test.ts |  38 ++
 .../ai-harness/tests/workspace-tools.test.ts  | 472 ++++++++++-------
 packages/ai-harness/vite.config.ts            |   1 +
 packages/ai-persistence/src/index.ts          |   6 +
 packages/ai-persistence/src/memory.ts         |  71 ++-
 packages/ai-persistence/src/middleware.ts     |  21 +-
 packages/ai-persistence/src/subagent-runs.ts  | 196 ++++++-
 .../ai-persistence/src/testkit/conformance.ts | 182 +++++++
 packages/ai-persistence/src/types.ts          | 116 ++++
 packages/ai-persistence/tests/memory.test.ts  |   1 +
 .../tests/persistence-types.test-d.ts         |   2 +
 .../tests/persistence-validation.test.ts      |   7 +
 .../tests/subagent-persistence-cards.test.ts  | 362 +++++++++++++
 .../ai/skills/ai-core/middleware/SKILL.md     |  35 +-
 .../ai/src/activities/chat/agents/bound.ts    |  15 +
 .../ai/src/activities/chat/agents/spawn.ts    | 485 ++++++++++++-----
 packages/ai/src/activities/chat/index.ts      |  61 ++-
 .../src/activities/chat/middleware/compose.ts |  16 +-
 .../src/activities/chat/middleware/index.ts   |   1 +
 .../activities/chat/middleware/load-child.ts  |  16 +
 .../src/activities/chat/middleware/types.ts   |  32 +-
 .../src/activities/chat/tools/tool-calls.ts   | 204 ++++---
 packages/ai/src/index.ts                      |   9 +
 packages/ai/src/types.ts                      |  18 +
 .../ai/tests/after-tool-call-replace.test.ts  | 120 +++++
 .../ai/tests/subagent-single-tool.test.ts     | 366 +++++++++++++
 packages/ai/tests/tool-choice.test.ts         | 113 ++++
 pnpm-lock.yaml                                | 318 +++++++++--
 72 files changed, 6424 insertions(+), 1124 deletions(-)
 create mode 100644 packages/ai-harness/src/first-party/coding/backend.ts
 create mode 100644 packages/ai-harness/src/first-party/coding/bash.ts
 create mode 100644 packages/ai-harness/src/first-party/coding/edit.ts
 create mode 100644 packages/ai-harness/src/first-party/coding/index.ts
 create mode 100644 packages/ai-harness/src/first-party/coding/read.ts
 create mode 100644 packages/ai-harness/src/first-party/coding/search.ts
 create mode 100644 packages/ai-harness/src/first-party/coding/workspace.ts
 create mode 100644 packages/ai-harness/src/first-party/glob.ts
 create mode 100644 packages/ai-harness/src/first-party/workspace-hooks.ts
 delete mode 100644 packages/ai-harness/src/first-party/workspace.ts
 create mode 100644 packages/ai-harness/tests/coding-backend.test.ts
 create mode 100644 packages/ai-harness/tests/permissions.test.ts
 create mode 100644 packages/ai-harness/tests/plugin-apis.test.ts
 create mode 100644 packages/ai-harness/tests/sessions-index.test.ts
 create mode 100644 packages/ai/src/activities/chat/middleware/load-child.ts
 create mode 100644 packages/ai/tests/after-tool-call-replace.test.ts
 create mode 100644 packages/ai/tests/subagent-single-tool.test.ts
 create mode 100644 packages/ai/tests/tool-choice.test.ts

diff --git a/docs/harness/coding-agent.md b/docs/harness/coding-agent.md
index 1394b52508..63bda3a8d5 100644
--- a/docs/harness/coding-agent.md
+++ b/docs/harness/coding-agent.md
@@ -25,8 +25,8 @@ import {
   projectInstructions,
   todos,
   usage,
-  workspaceTools,
 } from '@tanstack/ai-harness/plugins'
+import { workspaceTools } from '@tanstack/ai-harness/plugins/coding'
 import { runCli } from '@tanstack/ai-harness-cli'
 import { openaiText } from '@tanstack/ai-openai'
 
diff --git a/docs/harness/goal.md b/docs/harness/goal.md
index bdfb182d35..922b28563c 100644
--- a/docs/harness/goal.md
+++ b/docs/harness/goal.md
@@ -19,7 +19,8 @@ The `goal()` plugin keeps the harness working. You give the goal one time. After
 
 ```ts group=harness-goal
 import { defineHarness } from '@tanstack/ai-harness'
-import { goal, permissions, workspaceTools } from '@tanstack/ai-harness/plugins'
+import { goal, permissions } from '@tanstack/ai-harness/plugins'
+import { workspaceTools } from '@tanstack/ai-harness/plugins/coding'
 import { openaiText } from '@tanstack/ai-openai'
 
 const root = process.cwd()
diff --git a/examples/harness-cli-cloudflare/src/harness.ts b/examples/harness-cli-cloudflare/src/harness.ts
index de6b582358..c5b812b2d6 100644
--- a/examples/harness-cli-cloudflare/src/harness.ts
+++ b/examples/harness-cli-cloudflare/src/harness.ts
@@ -11,8 +11,8 @@ import {
   projectInstructions,
   todos,
   usage,
-  workspaceTools,
 } from '@tanstack/ai-harness/plugins'
+import { workspaceTools } from '@tanstack/ai-harness/plugins/coding'
 import { claudeCodeText } from '@tanstack/ai-claude-code'
 import { createCloudflareText } from '@tanstack/ai-cloudflare'
 import { cloudflareByok } from '@tanstack/ai-cloudflare/byok'
diff --git a/examples/harness-cli/src/harness.ts b/examples/harness-cli/src/harness.ts
index 64105ec0d3..f13f357d73 100644
--- a/examples/harness-cli/src/harness.ts
+++ b/examples/harness-cli/src/harness.ts
@@ -12,8 +12,8 @@ import {
   providerKeys,
   todos,
   usage,
-  workspaceTools,
 } from '@tanstack/ai-harness/plugins'
+import { workspaceTools } from '@tanstack/ai-harness/plugins/coding'
 import { ANTHROPIC_MODELS, createAnthropicChat } from '@tanstack/ai-anthropic'
 import { anthropicByok } from '@tanstack/ai-anthropic/byok'
 import { claudeCodeText } from '@tanstack/ai-claude-code'
diff --git a/packages/ai-code-mode/src/harness.ts b/packages/ai-code-mode/src/harness.ts
index 5f9fb6f376..ff83c7effb 100644
--- a/packages/ai-code-mode/src/harness.ts
+++ b/packages/ai-code-mode/src/harness.ts
@@ -79,7 +79,7 @@ export function codeMode(options: CodeModePluginOptions) {
       let prompt = ''
       return {
         prompts: [{ id: 'tanstack/code-mode', text: () => prompt }],
-        prepareTools: (tools) => {
+        prepareTools: ({ tools }) => {
           // Two tools that map to the same identifier: the first one moves.
           const byIdentifier = new Map<string, CodeModeTool>()
           for (const tool of tools.filter(isServerTool)) {
diff --git a/packages/ai-harness-cli/tests/printer.test.ts b/packages/ai-harness-cli/tests/printer.test.ts
index 5b1b84d5a1..f51157997d 100644
--- a/packages/ai-harness-cli/tests/printer.test.ts
+++ b/packages/ai-harness-cli/tests/printer.test.ts
@@ -13,6 +13,7 @@ const base: SessionViewState = {
   signIns: [],
   agents: [],
   queuedTurns: 0,
+  waitingInputs: [],
   commands: [],
   config: [],
   tools: [],
diff --git a/packages/ai-harness/package.json b/packages/ai-harness/package.json
index 00f9bd8934..f5366cebe9 100644
--- a/packages/ai-harness/package.json
+++ b/packages/ai-harness/package.json
@@ -42,6 +42,10 @@
       "types": "./dist/esm/first-party/index.d.ts",
       "import": "./dist/esm/first-party/index.js"
     },
+    "./plugins/coding": {
+      "types": "./dist/esm/first-party/coding/index.d.ts",
+      "import": "./dist/esm/first-party/coding/index.js"
+    },
     "./build": {
       "types": "./dist/esm/build.d.ts",
       "import": "./dist/esm/build.js"
@@ -69,11 +73,23 @@
     "@tanstack/ai": "workspace:*",
     "@tanstack/ai-persistence": "workspace:*",
     "@vitest/coverage-v8": "4.1.10",
+    "@vscode/ripgrep": "^1.18.0",
+    "turndown": "^7.2.4",
     "zod": "^4.2.0"
   },
   "peerDependencies": {
     "@tanstack/ai": "workspace:^",
-    "@tanstack/ai-persistence": "workspace:^"
+    "@tanstack/ai-persistence": "workspace:^",
+    "@vscode/ripgrep": "^1.15.0",
+    "turndown": "^7.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@vscode/ripgrep": {
+      "optional": true
+    },
+    "turndown": {
+      "optional": true
+    }
   },
   "nx": {
     "targets": {
diff --git a/packages/ai-harness/src/client.ts b/packages/ai-harness/src/client.ts
index 531344c6db..71830f2791 100644
--- a/packages/ai-harness/src/client.ts
+++ b/packages/ai-harness/src/client.ts
@@ -3,17 +3,23 @@
 // 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 } from './define'
 import type { SessionDescription, SessionSnapshot } from './session'
 import type {
   BusyPolicy,
   Cursor,
+  ForkPoint,
   HarnessInput,
   MediaRecord,
   Receipt,
   SessionEvent,
   UserInput,
+  WaitingInput,
 } from './types'
 
 export {
@@ -23,7 +29,7 @@ export {
   mediaOfMessage,
   mediaPart,
 } from './media-ref'
-export type { MediaKind, MediaRecord } from './types'
+export type { ForkPoint, MediaKind, MediaRecord } from './types'
 
 export interface HarnessClientOptions {
   /** The base URL of `createHarnessHandler`, for example `/api/harness`. */
@@ -67,6 +73,19 @@ export interface HarnessClient<THarness extends AnyHarness> {
   ) => 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: (
+    inputId: string,
+    delivery: WaitingInput['delivery'],
+  ) => Promise<Receipt>
   agents: ClientAgentHandles<THarness>
   /** Answer a question from a command or a plugin. */
   answer: (questionId: string, value: unknown) => Promise<Receipt>
@@ -106,8 +125,36 @@ export interface HarnessClient<THarness extends AnyHarness> {
   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.
+   */
+  listSessions: (options?: {
+    limit?: number
+    cursor?: string
+    parentThreadId?: string
+  }) => Promise<SessionIndexPage>
+  /** Set the title of one of your sessions. Resolves to the changed entry. */
+  renameSession: (threadId: string, title: string) => Promise<SessionIndexEntry>
+  /**
+   * 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: (threadId: string, at: ForkPoint) => Promise<SessionIndexEntry>
 }
 
+/** The body of `POST sessions`. */
+type SessionChange =
+  | { op: 'rename'; threadId: string; title: string }
+  | { op: 'delete'; threadId: string }
+  | ({ op: 'fork'; threadId: string } & ForkPoint)
+
 // The answer of `GET media-url`: a signed path, relative to the base URL.
 function isSignedPath(
   value: unknown,
@@ -149,6 +196,15 @@ export function createHarnessClient<THarness extends AnyHarness>(
     )
   }
 
+  // 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',
@@ -192,11 +248,7 @@ export function createHarnessClient<THarness extends AnyHarness>(
       // if big uploads from bytes (not a Blob or File) ever matter.
       body: body instanceof Uint8Array ? body.slice() : body,
     })
-    if (!response.ok) {
-      // A proxy can refuse a big upload with a page, not JSON.
-      const refusal: unknown = await response.json().catch(() => undefined)
-      throw failure('upload', response, refusal)
-    }
+    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')
@@ -213,6 +265,21 @@ export function createHarnessClient<THarness extends AnyHarness>(
   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 and a fork with the entry.
+    (await (await changeSession(change)).json()) as SessionIndexEntry
+
   async function* events(
     eventOptions: {
       from?: Cursor
@@ -322,6 +389,9 @@ export function createHarnessClient<THarness extends AnyHarness>(
     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 }),
@@ -333,5 +403,24 @@ export function createHarnessClient<THarness extends AnyHarness>(
     upload,
     mediaUrl,
     loadMedia,
+    listSessions: async ({ limit, cursor, parentThreadId } = {}) => {
+      const query = new URLSearchParams()
+      if (limit !== undefined) query.set('limit', String(limit))
+      if (cursor) query.set('cursor', cursor)
+      if (parentThreadId) query.set('parentThreadId', parentThreadId)
+      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 SessionIndexPage
+    },
+    renameSession: (threadId, title) =>
+      sessionEntry({ op: 'rename', threadId, title }),
+    deleteSession: async (threadId) => {
+      await changeSession({ op: 'delete', threadId })
+    },
+    forkSession: (threadId, at) =>
+      sessionEntry({ op: 'fork', threadId, ...at }),
   }
 }
diff --git a/packages/ai-harness/src/commands.ts b/packages/ai-harness/src/commands.ts
index d44810eff7..8644498ea6 100644
--- a/packages/ai-harness/src/commands.ts
+++ b/packages/ai-harness/src/commands.ts
@@ -1,4 +1,5 @@
 import type { InferSchemaType, ModelMessage, SchemaInput } from '@tanstack/ai'
+import type { SessionIndexEntry } from '@tanstack/ai-persistence'
 import type { CredentialsAccess } from './auth'
 import type { SessionSnapshot } from './session'
 import type { ChatTurnResult, Operation, Principal, Receipt } from './types'
@@ -35,10 +36,37 @@ export interface PluginSessionApi {
    * turn waits in the queue. Cancel the returned turn to drop it before it starts.
    */
   prompt: (text: string) => Operation<ChatTurnResult>
+  /**
+   * Add `text` to the transcript as an assistant note, not as a user prompt.
+   * When no turn runs, the note is written at once. Else it is written before
+   * the next turn starts. With `wake: true`, a new turn that sends `text` is
+   * also queued, so the model can act on the note. Resolves when the note is
+   * written or queued and the wake turn is queued, not when that turn ends.
+   */
+  note: (text: string, options?: { wake?: boolean }) => Promise<void>
   /** The saved transcript. */
   transcript: () => Promise<Array<ModelMessage>>
   /** Replace the saved transcript (for example after a summary). */
   replaceTranscript: (messages: Array<ModelMessage>) => Promise<void>
+  /**
+   * The session index entry of this thread. `undefined` when the host has
+   * no `stores.sessions`, or the thread has no entry.
+   */
+  entry: () => Promise<SessionIndexEntry | undefined>
+  /**
+   * Change the session index entry of this thread. Each field you pass
+   * replaces the stored one. Resolves to the changed entry. Without
+   * `stores.sessions`, or for a thread with no entry, it writes nothing and
+   * resolves to `undefined`.
+   *
+   * @example
+   * ```ts
+   * await ctx.session.updateEntry({ title: 'Fix the login bug' })
+   * ```
+   */
+  updateEntry: (
+    patch: Partial<Pick<SessionIndexEntry, 'title' | 'metadata' | 'usage'>>,
+  ) => Promise<SessionIndexEntry | undefined>
   /**
    * Ask the user and wait for the answer. Hosts show it (the CLI prompts,
    * ACP shows an elicitation). Rejects when the session closes.
diff --git a/packages/ai-harness/src/define.ts b/packages/ai-harness/src/define.ts
index f54e6e6541..85f53cbd0d 100644
--- a/packages/ai-harness/src/define.ts
+++ b/packages/ai-harness/src/define.ts
@@ -130,6 +130,13 @@ export interface HarnessConfig<
   middleware?: ReadonlyArray<AnyChatMiddleware>
   /** When a turn stops calling the model. Defaults to `maxIterations(50)`. */
   agentLoopStrategy?: AgentLoopStrategy
+  /**
+   * How the server tools of one model call run, the same as
+   * `chat({ toolExecution })`. `'parallel'` starts them together.
+   * `'sequential'` runs them one at a time, in call order. Default
+   * `'parallel'`.
+   */
+  toolExecution?: 'parallel' | 'sequential'
   modelOptions?: TAdapter['~types']['providerOptions']
   /**
    * Automatic prompt caching for every session, the same as
diff --git a/packages/ai-harness/src/first-party/coding/backend.ts b/packages/ai-harness/src/first-party/coding/backend.ts
new file mode 100644
index 0000000000..d033de3838
--- /dev/null
+++ b/packages/ai-harness/src/first-party/coding/backend.ts
@@ -0,0 +1,205 @@
+import * as childProcess from 'node:child_process'
+import * as fs from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { isRecord } from '../../utils'
+import type { WorkspaceHooks } from '../workspace-hooks'
+
+/**
+ * Where the workspace tools read and write files and run commands. Every
+ * path is absolute. {@link hostBackend} is this machine. Another backend, for
+ * example a sandbox, lets the same tools work there.
+ */
+export interface WorkspaceBackend {
+  /** The bytes of a file. Throws when there is no file. */
+  readFile: (path: string) => Promise<Uint8Array>
+  /** Create or replace a file. Missing parent folders are created. */
+  writeFile: (path: string, data: Uint8Array | string) => Promise<void>
+  /** A file or a folder, or `undefined` when nothing is at `path`. */
+  stat: (
+    path: string,
+  ) => Promise<
+    { type: 'file' | 'dir'; size: number; mtimeMs: number } | undefined
+  >
+  /** The entries of a folder. */
+  readdir: (
+    path: string,
+  ) => Promise<Array<{ name: string; type: 'file' | 'dir' }>>
+  /**
+   * Run a shell command and wait for it to end. `env` is added to the
+   * environment. A command that fails resolves with its exit code.
+   */
+  exec: (
+    command: string,
+    options?: {
+      cwd?: string
+      env?: Record<string, string>
+      timeoutMs?: number
+      signal?: AbortSignal
+    },
+  ) => Promise<{ exitCode: number; stdout: string; stderr: string }>
+  /**
+   * Start a shell command in the background. `output()` is stdout and
+   * stderr so far. Optional: without it, background commands give an error.
+   */
+  spawn?: (
+    command: string,
+    options?: { cwd?: string; env?: Record<string, string> },
+  ) => {
+    wait: () => Promise<{ exitCode: number }>
+    kill: () => void
+    output: () => string
+  }
+}
+
+/** What each workspace tool gets from `workspaceTools()`. */
+export interface ToolEnv {
+  backend: WorkspaceBackend
+  /** The workspace folder, an absolute path. */
+  root: string
+  /** The hooks that plugins added. Read them when the tool runs. */
+  hooks: () => ReadonlyArray<WorkspaceHooks>
+  /** Run `fn` when the work before it on `path` is done, one at a time. */
+  lock: <T>(path: string, fn: () => Promise<T>) => Promise<T>
+  /**
+   * The absolute path of `path`, a file or a folder. A path outside the
+   * workspace is refused, or needs the user's yes for its folder.
+   */
+  reach: (
+    path: string,
+    tool: string,
+    kind: 'file' | 'folder',
+  ) => Promise<string>
+  /** A path for the model: from the workspace, or the full path outside it. */
+  shown: (full: string) => string
+}
+
+/** `env` added to the environment of this process. */
+const withEnv = (env: Record<string, string> | undefined) =>
+  env && { ...process.env, ...env }
+
+/**
+ * The workspace on this machine, with `node:fs` and `node:child_process`.
+ * Commands run in the system shell.
+ */
+export const hostBackend = {
+  readFile: (path) => fs.readFile(path),
+  writeFile: async (path, data) => {
+    await fs.mkdir(dirname(path), { recursive: true })
+    await fs.writeFile(path, data)
+  },
+  stat: async (path) => {
+    const info = await fs.stat(path).catch((error: unknown) => {
+      const isMissing =
+        error instanceof Error && 'code' in error && error.code === 'ENOENT'
+      if (isMissing) return undefined
+      throw error
+    })
+    if (!info) return undefined
+    return {
+      type: info.isDirectory() ? 'dir' : 'file',
+      size: info.size,
+      mtimeMs: info.mtimeMs,
+    }
+  },
+  readdir: async (path) => {
+    const entries = await fs.readdir(path, { withFileTypes: true })
+    return entries.map((entry) => ({
+      name: entry.name,
+      type: entry.isDirectory() ? ('dir' as const) : ('file' as const),
+    }))
+  },
+  exec: (command, options = {}) =>
+    new Promise((done) => {
+      childProcess.exec(
+        command,
+        {
+          cwd: options.cwd,
+          env: withEnv(options.env),
+          timeout: options.timeoutMs,
+          signal: options.signal,
+          maxBuffer: 10 * 1024 * 1024,
+        },
+        (error, stdout, stderr) =>
+          done({ exitCode: error?.code ?? 0, stdout, stderr }),
+      )
+    }),
+  spawn: (command, options = {}) => {
+    const isWindows = process.platform === 'win32'
+    // Off Windows, the command gets its own process group, so `kill` can
+    // stop the commands it started too.
+    const child = childProcess.spawn(command, {
+      cwd: options.cwd,
+      env: withEnv(options.env),
+      shell: true,
+      detached: !isWindows,
+    })
+    // ponytail: keeps all output in memory. Cap it if long jobs need that.
+    let output = ''
+    const collect = (chunk: Buffer) => {
+      output += chunk.toString()
+    }
+    child.stdout.on('data', collect)
+    child.stderr.on('data', collect)
+    const exited = new Promise<{ exitCode: number }>((done) => {
+      child.on('close', (code) => done({ exitCode: code ?? 1 }))
+      child.on('error', (error) => {
+        output += String(error)
+        done({ exitCode: 1 })
+      })
+    })
+    const kill = () => {
+      if (child.pid === undefined) return
+      // Stop the shell and every command it started.
+      if (isWindows) {
+        childProcess.execFile(
+          'taskkill',
+          ['/pid', String(child.pid), '/T', '/F'],
+          () => undefined,
+        )
+        return
+      }
+      try {
+        process.kill(-child.pid, 'SIGTERM')
+      } catch {
+        // The command already ended.
+      }
+    }
+    return { wait: () => exited, kill, output: () => output }
+  },
+} satisfies WorkspaceBackend
+
+const MAX_OUTPUT = 20_000
+
+/** Cut text after 20,000 characters, and say how many were cut. */
+export function clip(text: string) {
+  return text.length > MAX_OUTPUT
+    ? `${text.slice(0, MAX_OUTPUT)}\n[${text.length - MAX_OUTPUT} more characters]`
+    : text
+}
+
+/** The string argument `key` of a tool call. Throws when it is not a string. */
+export function stringArg(args: unknown, key: string) {
+  const value = optionalString(args, key)
+  if (value !== undefined) return value
+  throw new Error(`Argument "${key}" must be a string.`)
+}
+
+/** The string argument `key` of a tool call, or `undefined`. */
+export function optionalString(args: unknown, key: string) {
+  const value = isRecord(args) ? args[key] : undefined
+  return typeof value === 'string' ? value : undefined
+}
+
+// Keep a byte order mark, so an edit writes the file back as it was.
+const decoder = new TextDecoder('utf-8', { ignoreBOM: true })
+
+/** The text of the file at `path`, as UTF-8. */
+export async function readText(backend: WorkspaceBackend, path: string) {
+  return decoder.decode(await backend.readFile(path))
+}
+
+/** Run the `afterWrite` hooks for `path`, one after another. */
+export async function afterWrite(env: ToolEnv, path: string) {
+  const hooks = env.hooks()
+  for (const hook of hooks) await hook.afterWrite?.(path)
+}
diff --git a/packages/ai-harness/src/first-party/coding/bash.ts b/packages/ai-harness/src/first-party/coding/bash.ts
new file mode 100644
index 0000000000..0b1a8e2a81
--- /dev/null
+++ b/packages/ai-harness/src/first-party/coding/bash.ts
@@ -0,0 +1,34 @@
+import { toolDefinition } from '@tanstack/ai'
+import { clip, stringArg } from './backend'
+import type { ToolEnv } from './backend'
+
+/** `bash`: run a shell command in the workspace folder. */
+export function bashTools(
+  env: ToolEnv,
+  options: {
+    /** Stop the command after this many milliseconds. Default: 120,000. */
+    timeoutMs?: number
+  } = {},
+) {
+  return [
+    toolDefinition({
+      name: 'bash',
+      description:
+        'Run a shell command in the workspace folder. Output is cut at 20,000 characters.',
+      inputSchema: {
+        type: 'object',
+        properties: { command: { type: 'string' } },
+        required: ['command'],
+      },
+      replay: 'never',
+    }).server(async (args: unknown) => {
+      const { exitCode, stdout, stderr } = await env.backend.exec(
+        stringArg(args, 'command'),
+        { cwd: env.root, timeoutMs: options.timeoutMs ?? 120_000 },
+      )
+      return clip(
+        `exit code: ${exitCode}\n${stdout}${stderr ? `\nstderr:\n${stderr}` : ''}`,
+      )
+    }),
+  ]
+}
diff --git a/packages/ai-harness/src/first-party/coding/edit.ts b/packages/ai-harness/src/first-party/coding/edit.ts
new file mode 100644
index 0000000000..4d23bcccda
--- /dev/null
+++ b/packages/ai-harness/src/first-party/coding/edit.ts
@@ -0,0 +1,67 @@
+import { toolDefinition } from '@tanstack/ai'
+import { isRecord } from '../../utils'
+import { afterWrite, readText, stringArg } from './backend'
+import type { ToolEnv } from './backend'
+
+/**
+ * `write_file` and `edit_file`. After each write, the `afterWrite` hooks run
+ * for the file.
+ */
+export function editTools(env: ToolEnv) {
+  return [
+    toolDefinition({
+      name: 'write_file',
+      description: 'Create or replace a file in the workspace.',
+      inputSchema: {
+        type: 'object',
+        properties: { path: { type: 'string' }, content: { type: 'string' } },
+        required: ['path', 'content'],
+      },
+    }).server(async (args: unknown) => {
+      const full = await env.reach(
+        stringArg(args, 'path'),
+        'write_file',
+        'file',
+      )
+      const content = stringArg(args, 'content')
+      return env.lock(full, async () => {
+        await env.backend.writeFile(full, content)
+        await afterWrite(env, full)
+        return `Wrote ${env.shown(full)}.`
+      })
+    }),
+    toolDefinition({
+      name: 'edit_file',
+      description:
+        'Replace exact text in a file. `old` must appear once, unless `replaceAll` is true.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          old: { type: 'string' },
+          new: { type: 'string' },
+          replaceAll: { type: 'boolean' },
+        },
+        required: ['path', 'old', 'new'],
+      },
+    }).server(async (args: unknown) => {
+      const full = await env.reach(stringArg(args, 'path'), 'edit_file', 'file')
+      const oldText = stringArg(args, 'old')
+      const newText = stringArg(args, 'new')
+      const replaceAll = isRecord(args) && args.replaceAll === true
+      return env.lock(full, async () => {
+        const before = await readText(env.backend, full)
+        const count = before.split(oldText).length - 1
+        if (count === 0) throw new Error('The old text is not in the file.')
+        if (count > 1 && !replaceAll) {
+          throw new Error(
+            `The old text appears ${count} times. Add context, or set replaceAll.`,
+          )
+        }
+        await env.backend.writeFile(full, before.split(oldText).join(newText))
+        await afterWrite(env, full)
+        return `Edited ${env.shown(full)} (${replaceAll ? count : 1} change${count > 1 && replaceAll ? 's' : ''}).`
+      })
+    }),
+  ]
+}
diff --git a/packages/ai-harness/src/first-party/coding/index.ts b/packages/ai-harness/src/first-party/coding/index.ts
new file mode 100644
index 0000000000..0269e2fd19
--- /dev/null
+++ b/packages/ai-harness/src/first-party/coding/index.ts
@@ -0,0 +1,7 @@
+// First-party plugins for a coding agent. This entry is Node only: the
+// plugins use the file system and the shell.
+export { workspaceTools } from './workspace'
+export type { WorkspaceToolsOptions } from './workspace'
+export { hostBackend } from './backend'
+export type { WorkspaceBackend } from './backend'
+export { WorkspaceHooks } from '../workspace-hooks'
diff --git a/packages/ai-harness/src/first-party/coding/read.ts b/packages/ai-harness/src/first-party/coding/read.ts
new file mode 100644
index 0000000000..c182e3eccc
--- /dev/null
+++ b/packages/ai-harness/src/first-party/coding/read.ts
@@ -0,0 +1,57 @@
+import { toolDefinition } from '@tanstack/ai'
+import { isRecord } from '../../utils'
+import { clip, readText, stringArg } from './backend'
+import type { ToolEnv } from './backend'
+
+const MAX_READ_LINES = 2000
+
+/**
+ * `read_file`: numbered lines of a text file. The text that `afterRead`
+ * hooks return is added after the lines.
+ */
+export function readTools(env: ToolEnv) {
+  return [
+    toolDefinition({
+      name: 'read_file',
+      description:
+        'Read a text file in the workspace. Lines are numbered from 1.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          offset: { type: 'number', description: 'First line, from 1' },
+          limit: { type: 'number' },
+        },
+        required: ['path'],
+      },
+      replay: 'safe',
+    }).server(async (args: unknown) => {
+      const full = await env.reach(stringArg(args, 'path'), 'read_file', 'file')
+      const offset =
+        isRecord(args) && typeof args.offset === 'number'
+          ? Math.max(1, args.offset)
+          : 1
+      const limit =
+        isRecord(args) && typeof args.limit === 'number'
+          ? args.limit
+          : MAX_READ_LINES
+      return env.lock(full, async () => {
+        const lines = (await readText(env.backend, full)).split('\n')
+        const parts = [
+          clip(
+            lines
+              .slice(offset - 1, offset - 1 + limit)
+              .map((line, index) => `${offset + index}\t${line}`)
+              .join('\n'),
+          ),
+        ]
+        const hooks = env.hooks()
+        for (const hook of hooks) {
+          const extra = await hook.afterRead?.(full)
+          if (extra) parts.push(extra)
+        }
+        return parts.join('\n\n')
+      })
+    }),
+  ]
+}
diff --git a/packages/ai-harness/src/first-party/coding/search.ts b/packages/ai-harness/src/first-party/coding/search.ts
new file mode 100644
index 0000000000..ee2dcc4a8a
--- /dev/null
+++ b/packages/ai-harness/src/first-party/coding/search.ts
@@ -0,0 +1,105 @@
+import { relative, resolve, sep } from 'node:path'
+import { toolDefinition } from '@tanstack/ai'
+import { globToRegExp } from '../glob'
+import { clip, optionalString, readText, stringArg } from './backend'
+import type { ToolEnv, WorkspaceBackend } from './backend'
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.nx', '.turbo'])
+
+/** The path of `file` from the folder `base`, with `/`, for a glob. */
+const fromBase = (base: string, file: string) =>
+  relative(base, file).split(sep).join('/')
+
+/** Add the files in `dir` and its folders to `out`. Stops after 5000. */
+async function walk(
+  backend: WorkspaceBackend,
+  dir: string,
+  out: Array<string>,
+) {
+  const entries = await backend.readdir(dir)
+  for (const entry of entries) {
+    if (entry.type === 'dir') {
+      if (!SKIP_DIRS.has(entry.name))
+        await walk(backend, resolve(dir, entry.name), out)
+    } else out.push(resolve(dir, entry.name))
+    if (out.length > 5000) return
+  }
+}
+
+/** `list_files` and `grep`. Both skip dependency and build folders. */
+export function searchTools(env: ToolEnv) {
+  return [
+    toolDefinition({
+      name: 'list_files',
+      description:
+        'List files in a folder (default: the workspace), optionally matching a glob like `src/**/*.ts`. The glob is from that folder.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string' },
+          path: {
+            type: 'string',
+            description: 'The folder. Default: the workspace',
+          },
+        },
+      },
+      replay: 'safe',
+    }).server(async (args: unknown) => {
+      const base = await env.reach(
+        optionalString(args, 'path') ?? '.',
+        'list_files',
+        'folder',
+      )
+      const pattern = optionalString(args, 'pattern')
+      const files: Array<string> = []
+      await walk(env.backend, base, files)
+      const regex = pattern ? globToRegExp(pattern) : undefined
+      const listed = files
+        .filter((file) => !regex || regex.test(fromBase(base, file)))
+        .map(env.shown)
+      return clip(listed.slice(0, 1000).join('\n') || 'No files.')
+    }),
+    toolDefinition({
+      name: 'grep',
+      description:
+        'Search file contents in a folder (default: the workspace) with a regular expression. Returns `file:line: text`.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string' },
+          glob: { type: 'string' },
+          path: {
+            type: 'string',
+            description: 'The folder. Default: the workspace',
+          },
+        },
+        required: ['pattern'],
+      },
+      replay: 'safe',
+    }).server(async (args: unknown) => {
+      const regex = new RegExp(stringArg(args, 'pattern'))
+      const base = await env.reach(
+        optionalString(args, 'path') ?? '.',
+        'grep',
+        'folder',
+      )
+      const glob = optionalString(args, 'glob')
+      const fileFilter = glob ? globToRegExp(glob) : undefined
+      const files: Array<string> = []
+      await walk(env.backend, base, files)
+      const hits: Array<string> = []
+      for (const file of files) {
+        if (fileFilter && !fileFilter.test(fromBase(base, file))) continue
+        const info = await env.backend.stat(file)
+        if (!info || info.size > 1_000_000) continue
+        const lines = (await readText(env.backend, file)).split('\n')
+        lines.forEach((line, index) => {
+          if (hits.length < 200 && regex.test(line))
+            hits.push(`${env.shown(file)}:${index + 1}: ${line.trim()}`)
+        })
+        if (hits.length >= 200) break
+      }
+      return clip(hits.join('\n') || 'No matches.')
+    }),
+  ]
+}
diff --git a/packages/ai-harness/src/first-party/coding/workspace.ts b/packages/ai-harness/src/first-party/coding/workspace.ts
new file mode 100644
index 0000000000..f9d39a68e9
--- /dev/null
+++ b/packages/ai-harness/src/first-party/coding/workspace.ts
@@ -0,0 +1,202 @@
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+import { definePlugin } from '../../plugins'
+import { PermissionRules, isYes } from '../permissions'
+import { WorkspaceHooks } from '../workspace-hooks'
+import { hostBackend } from './backend'
+import { bashTools } from './bash'
+import { editTools } from './edit'
+import { readTools } from './read'
+import { searchTools } from './search'
+import type { ToolEnv, WorkspaceBackend } from './backend'
+
+export interface WorkspaceToolsOptions {
+  root: string
+  bashTimeoutMs?: number
+  /**
+   * A path outside `root`. `'deny'` (default) refuses it. `'ask'` asks the
+   * user first, and a yes allows that folder, and the folders in it, for the
+   * rest of the session. The `bypass` mode of `permissions()` allows it
+   * without a question.
+   */
+  outside?: 'deny' | 'ask'
+  /** Where the files are and commands run. Default: {@link hostBackend}. */
+  backend?: WorkspaceBackend
+}
+
+/** What the tools need from the session for a path outside the workspace. */
+export interface OutsideAccess {
+  /** Ask the user a question, and resolve with the answer. */
+  ask: (message: string) => Promise<unknown>
+  /** The permission mode of the session, for example `'bypass'`. */
+  mode: () => unknown
+}
+
+/** Is `full` the folder `dir`, or a path in it? */
+function within(dir: string, full: string) {
+  return full === dir || full.startsWith(dir.endsWith(sep) ? dir : dir + sep)
+}
+
+/** A lock per path: work on one path runs one at a time, in order. */
+function createLock() {
+  const queues = new Map<string, Promise<unknown>>()
+  return <T>(path: string, fn: () => Promise<T>) => {
+    const result = (queues.get(path) ?? Promise.resolve()).then(fn)
+    const settled = result.then(
+      () => undefined,
+      () => undefined,
+    )
+    queues.set(path, settled)
+    void settled.then(() => {
+      if (queues.get(path) === settled) queues.delete(path)
+    })
+    return result
+  }
+}
+
+/**
+ * The tools of {@link workspaceTools} for one session. `access` asks the user
+ * about a path outside the workspace when `options.outside` is `'ask'`.
+ * `hooks` are the hooks that plugins added.
+ */
+export function createWorkspaceTools(
+  options: WorkspaceToolsOptions,
+  session: {
+    access?: OutsideAccess
+    hooks?: () => ReadonlyArray<WorkspaceHooks>
+  } = {},
+) {
+  const root = resolve(options.root)
+  const { access } = session
+  // The outside folders the user allowed in this session, and the questions
+  // that wait for an answer, by folder, so parallel calls ask once.
+  const allowed: Array<string> = []
+  const asking = new Map<string, Promise<boolean>>()
+
+  /** Ask once about `folder`. A yes allows it for the session. */
+  const allow = (folder: string, message: string) => {
+    let answer = asking.get(folder)
+    if (!answer) {
+      answer = Promise.resolve(access?.ask(message)).then((reply) => {
+        asking.delete(folder)
+        if (isYes(reply)) allowed.push(folder)
+        return isYes(reply)
+      })
+      asking.set(folder, answer)
+    }
+    return answer
+  }
+
+  const reach: ToolEnv['reach'] = async (path, tool, kind) => {
+    const full = isAbsolute(path) ? resolve(path) : resolve(root, path)
+    const isAllowed = [root, ...allowed].some((dir) => within(dir, full))
+    if (isAllowed) return full
+    if (options.outside !== 'ask' || !access) {
+      throw new Error(`Path "${path}" is outside the workspace.`)
+    }
+    if (access.mode() === 'bypass') return full
+    const folder = kind === 'folder' ? full : dirname(full)
+    const yes = await allow(
+      folder,
+      `${tool} wants ${full}, outside the workspace (${root}). Allow ${folder} for this session? (y/n)`,
+    )
+    if (!yes) {
+      throw new Error(
+        `The user did not allow ${full}. It is outside the workspace.`,
+      )
+    }
+    return full
+  }
+
+  const env: ToolEnv = {
+    backend: options.backend ?? hostBackend,
+    root,
+    hooks: session.hooks ?? (() => []),
+    // ponytail: one lock per session. Sessions on one folder do not wait
+    // for each other.
+    lock: createLock(),
+    reach,
+    shown: (full) =>
+      (within(root, full) ? relative(root, full) || '.' : full)
+        .split(sep)
+        .join('/'),
+  }
+  const tools = [
+    ...readTools(env),
+    ...editTools(env),
+    ...searchTools(env),
+    ...bashTools(env, { timeoutMs: options.bashTimeoutMs }),
+  ]
+  const prompt =
+    options.outside === 'ask'
+      ? `Your workspace is ${root}. Paths are relative to it. A path outside it asks the user first.`
+      : `Your workspace is ${root}. Paths are relative to it.`
+  return { tools, prompt }
+}
+
+/**
+ * File and shell tools for a coding agent, in `root`: `read_file`,
+ * `write_file`, `edit_file`, `list_files`, `grep`, and `bash`. Edits and
+ * `bash` ask for approval through `permissions()`. A path outside `root` is
+ * refused, or with `outside: 'ask'` the user is asked first. Other plugins
+ * add {@link WorkspaceHooks} to run code after a read or a write.
+ *
+ * The tools use `backend` for files and commands. The default,
+ * `hostBackend`, runs on this machine with the host's authority. Use a
+ * sandbox backend for code you do not trust.
+ *
+ * @example
+ * ```ts
+ * workspaceTools({ root: process.cwd(), outside: 'ask' })
+ * ```
+ */
+export function workspaceTools(options: WorkspaceToolsOptions) {
+  return definePlugin({
+    name: 'tanstack/workspace-tools',
+    setup: (ctx) => {
+      const hooks = ctx.collect(WorkspaceHooks)
+      const { tools, prompt } = createWorkspaceTools(options, {
+        access: {
+          ask: (message) => ctx.session.ask({ message }),
+          mode: () => ctx.config.get('mode'),
+        },
+        hooks: () => hooks,
+      })
+      return {
+        tools,
+        prompts: [prompt],
+        contribute: [
+          PermissionRules.item({
+            tool: 'read_file',
+            decision: 'allow',
+            kind: 'read',
+          }),
+          PermissionRules.item({
+            tool: 'list_files',
+            decision: 'allow',
+            kind: 'read',
+          }),
+          PermissionRules.item({
+            tool: 'grep',
+            decision: 'allow',
+            kind: 'read',
+          }),
+          PermissionRules.item({
+            tool: 'write_file',
+            decision: 'ask',
+            kind: 'edit',
+          }),
+          PermissionRules.item({
+            tool: 'edit_file',
+            decision: 'ask',
+            kind: 'edit',
+          }),
+          PermissionRules.item({
+            tool: 'bash',
+            decision: 'ask',
+            kind: 'execute',
+          }),
+        ],
+      }
+    },
+  })
+}
diff --git a/packages/ai-harness/src/first-party/glob.ts b/packages/ai-harness/src/first-party/glob.ts
new file mode 100644
index 0000000000..8dc2b9e857
--- /dev/null
+++ b/packages/ai-harness/src/first-party/glob.ts
@@ -0,0 +1,14 @@
+/** A simple glob to RegExp: `**` any path, `*` any name part, `?` one character. */
+export function globToRegExp(glob: string) {
+  let pattern = ''
+  for (let index = 0; index < glob.length; index += 1) {
+    const char = glob.charAt(index)
+    if (char === '*' && glob[index + 1] === '*') {
+      pattern += '.*'
+      index += glob[index + 2] === '/' ? 2 : 1
+    } else if (char === '*') pattern += '[^/]*'
+    else if (char === '?') pattern += '[^/]'
+    else pattern += char.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp(`^${pattern}$`)
+}
diff --git a/packages/ai-harness/src/first-party/index.ts b/packages/ai-harness/src/first-party/index.ts
index b7c14acbbb..e2e69795b6 100644
--- a/packages/ai-harness/src/first-party/index.ts
+++ b/packages/ai-harness/src/first-party/index.ts
@@ -3,17 +3,20 @@
 export { modelPicker } from './model-picker'
 export {
   PERMISSION_MODES,
+  PermissionResources,
   PermissionRules,
   decidePermission,
+  isUnsplittableCommand,
   permissions,
 } from './permissions'
 export type {
+  CallResources,
   PermissionDecision,
   PermissionMode,
   PermissionRule,
+  ToolResources,
 } from './permissions'
-export { globToRegExp, workspaceTools } from './workspace'
-export type { WorkspaceToolsOptions } from './workspace'
+export { globToRegExp } from './glob'
 export { formatTodos, todos } from './todos'
 export type { Todo } from './todos'
 export { fileCommands, projectInstructions } from './files'
diff --git a/packages/ai-harness/src/first-party/permissions.ts b/packages/ai-harness/src/first-party/permissions.ts
index d358e97c86..ea653b1d55 100644
--- a/packages/ai-harness/src/first-party/permissions.ts
+++ b/packages/ai-harness/src/first-party/permissions.ts
@@ -1,7 +1,11 @@
+import { getMetadata } from '@tanstack/ai'
 import { defineCommand } from '../commands'
 import { configOption } from '../config'
 import { createExtensionPoint } from '../extensions'
 import { definePlugin } from '../plugins'
+import { isRecord } from '../utils'
+import { globToRegExp } from './glob'
+import type { AnyChatMiddleware, JSONSchema, MetadataStore } from '@tanstack/ai'
 
 export type PermissionDecision = 'allow' | 'ask' | 'deny'
 
@@ -9,6 +13,12 @@ export type PermissionDecision = 'allow' | 'ask' | 'deny'
 export interface PermissionRule {
   /** A tool name. A trailing `*` matches a prefix, for example `git_*`. */
   tool: string
+  /**
+   * A glob on what the call touches: a path for file tools (`src/**`,
+   * relative to the root), or a command part for shell tools (`git *`).
+   * Without it, the rule matches every call of the tool.
+   */
+  resource?: string
   decision: PermissionDecision
   kind?: 'read' | 'edit' | 'execute'
 }
@@ -18,6 +28,27 @@ export const PermissionRules = createExtensionPoint<PermissionRule>(
   'tanstack/permission-rules',
 )
 
+/**
+ * What the calls of one tool touch. Each function gets the raw input the
+ * model sent, before the schema check. A function that throws refuses the
+ * call.
+ */
+export interface ToolResources {
+  /** The files the call reads or writes, relative to the root or absolute. */
+  paths?: (input: unknown) => ReadonlyArray<string>
+  /** The shell commands the call runs, one part for each simple command. */
+  commands?: (input: unknown) => ReadonlyArray<string>
+}
+
+/**
+ * Tool plugins say what each call touches, so rules with a `resource` can
+ * match it. Each item maps tool names to their resources, for example
+ * `PermissionResources.item({ read_file: { paths: (input) => [...] } })`.
+ */
+export const PermissionResources = createExtensionPoint<
+  Readonly<Record<string, ToolResources>>
+>('tanstack/permission-resources')
+
 export const PERMISSION_MODES = [
   'default',
   'plan',
@@ -31,34 +62,285 @@ export function isYes(answer: unknown) {
   return answer === true || /^y(es)?$/i.test(String(answer).trim())
 }
 
-function matches(rule: PermissionRule, tool: string): boolean {
+/**
+ * True when a command part still has shell syntax that can run or chain
+ * more commands (`$(`, a backtick, `;`, `&`, `|`, `<`, `>`, a new line), so
+ * no allow rule applies to it.
+ */
+export function isUnsplittableCommand(part: string) {
+  return /[`;&|<>\r\n]|\$\(/.test(part)
+}
+
+/** What one call touches, as a tool's `ToolResources` returns it. */
+export interface CallResources {
+  paths?: ReadonlyArray<string>
+  commands?: ReadonlyArray<string>
+}
+
+/** One thing a call touches, ready to match rule globs against. */
+interface Resource {
+  type: 'path' | 'command'
+  /** The text rules match: a path relative to the root, or a command part. */
+  match: string
+  /** Asks even when a rule without a `resource` allows the tool. */
+  risky: boolean
+  /** No allow rule applies. */
+  unsplittable: boolean
+  /** Compare without letter case (a Windows path). */
+  foldCase: boolean
+}
+
+function matchesTool(rule: PermissionRule, tool: string) {
   return rule.tool.endsWith('*')
     ? tool.startsWith(rule.tool.slice(0, -1))
     : rule.tool === tool
 }
 
-/** The decision for a tool in a mode. The last matching rule wins. */
+/** A path or a drive root in Windows form: `C:\x`, `C:/x`, or `\\server\share`. */
+function isWindowsPath(path: string) {
+  return /^([a-z]:[\\/]|[\\/]{2})/i.test(path)
+}
+
+/** `path` with `/` separators, and `.` and `..` resolved. */
+function normalizePath(path: string) {
+  const slashed = path.replaceAll('\\', '/')
+  const prefix =
+    /^[a-z]:\//i.exec(slashed)?.[0] ?? (slashed.startsWith('/') ? '/' : '')
+  const segments: Array<string> = []
+  const parts = slashed.slice(prefix.length).split('/')
+  for (const segment of parts) {
+    if (segment === '' || segment === '.') continue
+    const climbs =
+      segment === '..' && segments.length > 0 && segments.at(-1) !== '..'
+    if (climbs) segments.pop()
+    // `..` above an absolute root stays at the root.
+    else if (segment !== '..' || prefix === '') segments.push(segment)
+  }
+  return prefix + segments.join('/')
+}
+
+/** A `.env` file, or `.env.local` and the like. They often hold secrets. */
+function isEnvFile(path: string) {
+  const name = path.slice(path.lastIndexOf('/') + 1).toLowerCase()
+  return /\.env(\.|$)/.test(name)
+}
+
+function pathResource(path: string, root: string | undefined) {
+  const foldCase = isWindowsPath(root ?? path)
+  const slashed = path.replaceAll('\\', '/')
+  // Forms we cannot resolve without the file system ask: `C:x` (relative to
+  // the current folder of drive C), a stream (`a.txt:secret`), and a name
+  // that ends in `.` or a space (Windows drops them).
+  const cannotResolve =
+    slashed.replace(/^[a-z]:\//i, '').includes(':') ||
+    slashed
+      .split('/')
+      .some((part) => /[. ]$/.test(part) && part !== '.' && part !== '..')
+  const isAbsolute = /^([a-z]:)?\//i.test(slashed)
+  const full = normalizePath(
+    isAbsolute || root === undefined ? slashed : `${root}/${slashed}`,
+  )
+  const resource = {
+    type: 'path' as const,
+    match: full,
+    risky: cannotResolve || isEnvFile(full),
+    unsplittable: false,
+    foldCase,
+  }
+  if (root === undefined) return resource
+  const base = normalizePath(root)
+  const folder = base.endsWith('/') ? base : `${base}/`
+  const fold = (value: string) => (foldCase ? value.toLowerCase() : value)
+  const isInside =
+    fold(full) === fold(base) || fold(full).startsWith(fold(folder))
+  // Inside the root, rules match the relative path. Outside, the full path.
+  return isInside
+    ? { ...resource, match: full.slice(folder.length) }
+    : { ...resource, risky: true }
+}
+
+function commandResource(part: string) {
+  return {
+    type: 'command' as const,
+    match: part.trim(),
+    risky: false,
+    unsplittable: isUnsplittableCommand(part),
+    foldCase: false,
+  }
+}
+
+/** A command glob: `*` matches any text, `/` too. */
+function commandPattern(glob: string) {
+  const source = glob
+    .split('*')
+    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('.*')
+  return new RegExp(`^${source}$`)
+}
+
+function matchesResource(glob: string, resource: Resource) {
+  if (resource.type === 'command') {
+    return commandPattern(glob).test(resource.match)
+  }
+  const pattern = globToRegExp(glob.replaceAll('\\', '/'))
+  return new RegExp(pattern.source, resource.foldCase ? 'i' : '').test(
+    resource.match,
+  )
+}
+
+function strictest(decisions: ReadonlyArray<PermissionDecision>) {
+  if (decisions.includes('deny')) return 'deny'
+  if (decisions.includes('ask')) return 'ask'
+  return 'allow'
+}
+
+/**
+ * The decision for a tool call in a mode. The last matching rule wins.
+ *
+ * - With `resources`, each path and command part is checked, and every one
+ *   must be allowed. A path outside `root`, a `.env` file, or a path that
+ *   cannot be resolved asks, unless a rule with a `resource` allows it. A
+ *   command part with shell syntax (see `isUnsplittableCommand`) never gets
+ *   an allow.
+ * - Without `resources`, the call could touch anything, so a later rule
+ *   with a `resource` that asks or denies counts too.
+ *
+ * Modes: `bypass` allows all. `plan` denies edits, commands, and every call
+ * that is not an allow. `acceptEdits` allows edits that would ask.
+ */
 export function decidePermission(
   rules: ReadonlyArray<PermissionRule>,
   tool: string,
   mode: PermissionMode,
-  fallback: PermissionDecision = 'allow',
-): PermissionDecision {
-  const rule = rules.findLast((candidate) => matches(candidate, tool))
-  const decision = rule?.decision ?? fallback
+  options: {
+    fallback?: PermissionDecision
+    resources?: CallResources
+    /** The workspace root. Without it, no path counts as outside. */
+    root?: string
+  } = {},
+) {
   if (mode === 'bypass') return 'allow'
-  if (mode === 'plan') {
-    return rule?.kind === 'edit' ||
-      rule?.kind === 'execute' ||
-      decision !== 'allow'
-      ? 'deny'
-      : 'allow'
+  // An allow rule without `kind` must not hide that a tool edits.
+  const kind = rules.findLast(
+    (rule) => matchesTool(rule, tool) && rule.kind !== undefined,
+  )?.kind
+  if (mode === 'plan' && (kind === 'edit' || kind === 'execute')) return 'deny'
+  const decisionOf = (rule: PermissionRule | undefined) => {
+    const decision = rule?.decision ?? options.fallback ?? 'allow'
+    const autoEdit =
+      mode === 'acceptEdits' &&
+      kind === 'edit' &&
+      decision === 'ask' &&
+      rule?.resource === undefined
+    return autoEdit ? 'allow' : decision
+  }
+  const toolRules = rules.filter((rule) => matchesTool(rule, tool))
+  const lastToolLevel = toolRules.findLastIndex(
+    (rule) => rule.resource === undefined,
+  )
+  const toolLevel = lastToolLevel === -1 ? undefined : toolRules[lastToolLevel]
+  const decideOne = (resource: Resource) => {
+    const rule = toolRules.findLast(
+      (candidate) =>
+        candidate.resource === undefined ||
+        matchesResource(candidate.resource, resource),
+    )
+    const decision = decisionOf(rule)
+    if (decision !== 'allow') return decision
+    const needsAsk =
+      resource.unsplittable || (resource.risky && rule?.resource === undefined)
+    return needsAsk ? 'ask' : 'allow'
   }
-  if (mode === 'acceptEdits' && rule?.kind === 'edit' && decision === 'ask')
-    return 'allow'
+  const resources =
+    options.resources === undefined
+      ? undefined
+      : [
+          ...(options.resources.paths ?? []).map((path) =>
+            pathResource(path, options.root),
+          ),
+          ...(options.resources.commands ?? []).map(commandResource),
+        ]
+  // Unknown resources: the rules with a `resource` after the tool rule could
+  // match, so the strictest of them counts.
+  const decisions =
+    resources === undefined
+      ? [
+          decisionOf(toolLevel),
+          ...toolRules.slice(lastToolLevel + 1).map((rule) => rule.decision),
+        ]
+      : resources.length === 0
+        ? [decisionOf(toolLevel)]
+        : resources.map(decideOne)
+  const decision = strictest(decisions)
+  if (mode === 'plan' && decision !== 'allow') return 'deny'
   return decision
 }
 
+/** Rules hide a tool when its last rule denies with no `resource`. */
+function isHidden(
+  rules: ReadonlyArray<PermissionRule>,
+  tool: string,
+  mode: PermissionMode,
+) {
+  if (mode === 'bypass') return false
+  const last = rules.findLast((rule) => matchesTool(rule, tool))
+  return last?.decision === 'deny' && last.resource === undefined
+}
+
+/** The answer to a permission question, for hosts that render a form. */
+const ANSWER_SCHEMA: JSONSchema = {
+  type: 'object',
+  properties: {
+    answer: {
+      type: 'string',
+      enum: ['once', 'always', 'reject'],
+      description:
+        'once: allow this call. always: allow it from now on in this project. reject: refuse it.',
+    },
+    message: {
+      type: 'string',
+      description: 'With reject: what the model should do instead.',
+    },
+  },
+  required: ['answer'],
+}
+
+/** The user's reply. Anything that is not `once` or `always` rejects. */
+function readAnswer(value: unknown) {
+  const raw = isRecord(value) ? value.answer : value
+  const choice = typeof raw === 'string' ? raw.trim().toLowerCase() : ''
+  const text =
+    isRecord(value) && typeof value.message === 'string'
+      ? value.message.trim()
+      : ''
+  return {
+    choice: choice === 'once' || choice === 'always' ? choice : 'reject',
+    message: text === '' ? undefined : text,
+  }
+}
+
+function isSavedRule(value: unknown): value is PermissionRule {
+  return (
+    isRecord(value) &&
+    typeof value.tool === 'string' &&
+    value.decision === 'allow' &&
+    (value.resource === undefined || typeof value.resource === 'string')
+  )
+}
+
+/** A refused call: the model gets a tool error with `error`. */
+function refuse(error: string) {
+  return { type: 'skip' as const, result: { error } }
+}
+
+const METADATA_NAMESPACE = 'tanstack/permissions'
+
+/** The root as one string for each folder: `C:\Repo` and `c:/repo/` are the same. */
+function projectId(root: string) {
+  const path = normalizePath(root)
+  return isWindowsPath(root) ? path.toLowerCase() : path
+}
+
 const PLAN_PROMPT =
   'You are in plan mode. Do not change files or run commands. Read what you need, then describe your plan.'
 
@@ -70,23 +352,157 @@ const PLAN_PROMPT =
  * - `plan`: read-only. Edits and commands are denied.
  * - `acceptEdits`: edits run without asking. Commands still ask.
  * - `bypass`: everything runs.
+ *
+ * Rules apply in this order, and the last match wins: rules from tool
+ * plugins (`PermissionRules`), then `rules`, then saved answers. A saved
+ * answer never beats a deny. Tool plugins say what a call touches through
+ * `PermissionResources`. A path outside `root` or a `.env` file asks, unless
+ * a rule with a `resource` allows it. A tool whose last rule denies with no
+ * `resource` is removed from the model's tools.
+ *
+ * A question takes `once`, `always`, or `reject` with a `message` for the
+ * model. `always` saves an allow rule for each path or command part of the
+ * call, for the project (`root`), in the metadata store, else in memory for
+ * the session.
  */
 export function permissions(
   options: {
     rules?: ReadonlyArray<PermissionRule>
     default?: PermissionDecision
+    /**
+     * The workspace root. A path outside it asks, and saved answers belong
+     * to it. Without it, no path counts as outside.
+     */
+    root?: string
   } = {},
 ) {
   return definePlugin({
     name: 'tanstack/permissions',
     setup: (ctx) => {
       const contributed = ctx.collect(PermissionRules)
+      const declared = ctx.collect(PermissionResources)
       const mode = (): PermissionMode => {
         const value = ctx.config.get('mode')
         return (
           PERMISSION_MODES.find((candidate) => candidate === value) ?? 'default'
         )
       }
+      const root = options.root
+      const savedKey =
+        root === undefined
+          ? 'permissions:saved'
+          : `permissions:saved:${projectId(root)}`
+      // Answers saved in this session. Runs without a metadata store use them.
+      const memory: Array<PermissionRule> = []
+      const loadSaved = async (metadata: MetadataStore | undefined) => {
+        const stored = metadata
+          ? await metadata.get(METADATA_NAMESPACE, savedKey)
+          : null
+        const rules = Array.isArray(stored) ? stored.filter(isSavedRule) : []
+        return [...rules, ...memory]
+      }
+      // ponytail: get + set, a parallel save can drop a rule. It then asks again.
+      const save = async (
+        metadata: MetadataStore | undefined,
+        rules: ReadonlyArray<PermissionRule>,
+      ) => {
+        memory.push(...rules)
+        if (!metadata || rules.length === 0) return
+        const stored = await metadata.get(METADATA_NAMESPACE, savedKey)
+        const current = Array.isArray(stored) ? stored.filter(isSavedRule) : []
+        await metadata.set(METADATA_NAMESPACE, savedKey, [...current, ...rules])
+      }
+      const resourcesOf = (tool: string, input: unknown) => {
+        const entry = declared.findLast((item) => Object.hasOwn(item, tool))?.[
+          tool
+        ]
+        if (!entry) return undefined
+        const resources = {
+          paths: entry.paths?.(input) ?? [],
+          commands: entry.commands?.(input) ?? [],
+        }
+        const values = [...resources.paths, ...resources.commands]
+        if (!values.every((value) => typeof value === 'string')) {
+          throw new Error('A resource is not a string.')
+        }
+        return resources
+      }
+      /** The rules an `always` answer saves: one allow for each resource. */
+      const rulesToSave = (tool: string, resources: CallResources | undefined) => {
+        if (resources === undefined) {
+          return [{ tool, decision: 'allow' as const }]
+        }
+        const values = [
+          ...(resources.paths ?? []).map(
+            (path) => pathResource(path, root).match,
+          ),
+          ...(resources.commands ?? [])
+            .filter((part) => !isUnsplittableCommand(part))
+            .map((part) => part.trim()),
+        ]
+        // A `*` or `?` would turn the saved rule into a wider glob.
+        return values
+          .filter((value) => !/[*?]/.test(value))
+          .map((resource) => ({ tool, resource, decision: 'allow' as const }))
+      }
+      const decide = async (
+        tool: string,
+        input: unknown,
+        current: PermissionMode,
+        metadata: MetadataStore | undefined,
+      ) => {
+        const resources = resourcesOf(tool, input)
+        const settings = { fallback: options.default, resources, root }
+        const configured = [...contributed, ...(options.rules ?? [])]
+        // A saved answer turns an ask into an allow. It never beats a deny.
+        if (decidePermission(configured, tool, current, settings) === 'deny') {
+          return { decision: 'deny' as const, resources }
+        }
+        const rules = [...configured, ...(await loadSaved(metadata))]
+        const decision = decidePermission(rules, tool, current, settings)
+        return { decision, resources }
+      }
+      const check = {
+        name: 'tanstack/permissions',
+        onBeforeToolCall: async (run, hook) => {
+          const current = mode()
+          if (current === 'bypass') return undefined
+          const metadata = getMetadata(run, { optional: true })
+          const checked = await decide(
+            hook.toolName,
+            hook.args,
+            current,
+            metadata,
+          ).catch((error: unknown) =>
+            error instanceof Error ? error : new Error(String(error)),
+          )
+          // Fail closed: a call we cannot check does not run.
+          if (checked instanceof Error) {
+            return refuse(
+              `Cannot check the permissions of this call: ${checked.message}`,
+            )
+          }
+          const { decision, resources } = checked
+          if (decision === 'allow') return undefined
+          if (decision === 'deny') {
+            return refuse(`This tool is not allowed in ${current} mode.`)
+          }
+          const preview = JSON.stringify(hook.args ?? {}).slice(0, 300)
+          const reply = readAnswer(
+            await ctx.session.ask({
+              message: `Allow ${hook.toolName} ${preview}? Answer once, always, or reject.`,
+              schema: ANSWER_SCHEMA,
+            }),
+          )
+          if (reply.choice === 'reject') {
+            return refuse(reply.message ?? 'The user denied this tool call.')
+          }
+          if (reply.choice === 'always') {
+            await save(metadata, rulesToSave(hook.toolName, resources))
+          }
+          return undefined
+        },
+      } satisfies AnyChatMiddleware
       return {
         config: {
           mode: configOption.select({
@@ -115,38 +531,15 @@ export function permissions(
             },
           }),
         },
-        middleware: [
-          {
-            name: 'tanstack/permissions',
-            onBeforeToolCall: async (_run, hook) => {
-              const rules = [...(options.rules ?? []), ...contributed]
-              const decision = decidePermission(
-                rules,
-                hook.toolName,
-                mode(),
-                options.default,
-              )
-              if (decision === 'allow') return undefined
-              if (decision === 'ask') {
-                const preview = JSON.stringify(hook.args ?? {}).slice(0, 300)
-                const answer: unknown = await ctx.session.ask({
-                  message: `Allow ${hook.toolName} ${preview}? (y/n)`,
-                })
-                if (isYes(answer)) return undefined
-              }
-              return {
-                type: 'skip',
-                result: {
-                  denied: true,
-                  reason:
-                    decision === 'ask'
-                      ? 'The user denied this tool call.'
-                      : `This tool is not allowed in ${mode()} mode.`,
-                },
-              }
-            },
-          },
-        ],
+        prepareTools: ({ tools }) => {
+          const rules = [...contributed, ...(options.rules ?? [])]
+          const current = mode()
+          return tools.filter((tool) => !isHidden(rules, tool.name, current))
+        },
+        // The lead turn and every agent run check the same rules. Each run
+        // gets only one of the two lists, so a call is checked once.
+        middleware: [check],
+        agentMiddleware: [check],
       }
     },
   })
diff --git a/packages/ai-harness/src/first-party/workspace-hooks.ts b/packages/ai-harness/src/first-party/workspace-hooks.ts
new file mode 100644
index 0000000000..6d591ec0b0
--- /dev/null
+++ b/packages/ai-harness/src/first-party/workspace-hooks.ts
@@ -0,0 +1,32 @@
+import { createExtensionPoint } from '../extensions'
+
+/**
+ * Hooks for the workspace tools. Each runs inside the tool, while the tool
+ * holds the lock on that path. A hook that throws fails the tool call.
+ */
+export interface WorkspaceHooks {
+  /** Runs after a tool wrote the file at `path`, an absolute path. */
+  afterWrite?: (path: string) => Promise<void>
+  /**
+   * Runs after `read_file` read the file at `path`, an absolute path. Return
+   * text to add to the result, or `undefined` to add nothing.
+   */
+  afterRead?: (path: string) => Promise<string | undefined>
+}
+
+/**
+ * Plugins add {@link WorkspaceHooks} here. The workspace tools run them.
+ *
+ * @example
+ * ```ts
+ * definePlugin({
+ *   name: 'acme/format',
+ *   setup: () => ({
+ *     contribute: [WorkspaceHooks.item({ afterWrite: async (path) => format(path) })],
+ *   }),
+ * })
+ * ```
+ */
+export const WorkspaceHooks = createExtensionPoint<WorkspaceHooks>(
+  'tanstack/workspace-hooks',
+)
diff --git a/packages/ai-harness/src/first-party/workspace.ts b/packages/ai-harness/src/first-party/workspace.ts
deleted file mode 100644
index 46b99b990d..0000000000
--- a/packages/ai-harness/src/first-party/workspace.ts
+++ /dev/null
@@ -1,392 +0,0 @@
-import { exec } from 'node:child_process'
-import { readFile, readdir, stat, writeFile, mkdir } from 'node:fs/promises'
-import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
-import { toolDefinition } from '@tanstack/ai'
-import { definePlugin } from '../plugins'
-import { PermissionRules, isYes } from './permissions'
-
-const MAX_OUTPUT = 20_000
-const MAX_READ_LINES = 2000
-const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.nx', '.turbo'])
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null
-}
-
-function stringArg(args: unknown, key: string): string {
-  const value = isRecord(args) ? args[key] : undefined
-  if (typeof value === 'string') return value
-  throw new Error(`Argument "${key}" must be a string.`)
-}
-
-function optionalString(args: unknown, key: string): string | undefined {
-  const value = isRecord(args) ? args[key] : undefined
-  return typeof value === 'string' ? value : undefined
-}
-
-function clip(text: string): string {
-  return text.length > MAX_OUTPUT
-    ? `${text.slice(0, MAX_OUTPUT)}\n[${text.length - MAX_OUTPUT} more characters]`
-    : text
-}
-
-/** A simple glob to RegExp: `**` any path, `*` any name part, `?` one character. */
-export function globToRegExp(glob: string): RegExp {
-  let pattern = ''
-  for (let index = 0; index < glob.length; index += 1) {
-    const char = glob.charAt(index)
-    if (char === '*' && glob[index + 1] === '*') {
-      pattern += '.*'
-      index += glob[index + 2] === '/' ? 2 : 1
-    } else if (char === '*') pattern += '[^/]*'
-    else if (char === '?') pattern += '[^/]'
-    else pattern += char.replace(/[.+^${}()|[\]\\]/g, '\\$&')
-  }
-  return new RegExp(`^${pattern}$`)
-}
-
-export interface WorkspaceToolsOptions {
-  root: string
-  bashTimeoutMs?: number
-  /**
-   * A path outside `root`. `'deny'` (default) refuses it. `'ask'` asks the
-   * user first, and a yes allows that folder, and the folders in it, for the
-   * rest of the session. The `bypass` mode of `permissions()` allows it
-   * without a question.
-   */
-  outside?: 'deny' | 'ask'
-}
-
-/** What the tools need from the session for a path outside the workspace. */
-export interface OutsideAccess {
-  /** Ask the user a question, and resolve with the answer. */
-  ask: (message: string) => Promise<unknown>
-  /** The permission mode of the session, for example `'bypass'`. */
-  mode: () => unknown
-}
-
-/** Is `full` the folder `dir`, or a path in it? */
-function within(dir: string, full: string) {
-  return full === dir || full.startsWith(dir.endsWith(sep) ? dir : dir + sep)
-}
-
-/**
- * The tools of {@link workspaceTools} for one session. `access` asks the user
- * about a path outside the workspace when `options.outside` is `'ask'`.
- */
-export function createWorkspaceTools(
-  options: WorkspaceToolsOptions,
-  access?: OutsideAccess,
-) {
-  const root = resolve(options.root)
-  // The outside folders the user allowed in this session, and the questions
-  // that wait for an answer, by folder, so parallel calls ask once.
-  const allowed: Array<string> = []
-  const asking = new Map<string, Promise<boolean>>()
-
-  /** Ask once about `folder`. A yes allows it for the session. */
-  const allow = (folder: string, message: string) => {
-    let answer = asking.get(folder)
-    if (!answer) {
-      answer = Promise.resolve(access?.ask(message)).then((reply) => {
-        asking.delete(folder)
-        if (isYes(reply)) allowed.push(folder)
-        return isYes(reply)
-      })
-      asking.set(folder, answer)
-    }
-    return answer
-  }
-
-  /**
-   * The full path of `path`, a file or a folder. A path outside the
-   * workspace is refused, or needs the user's yes for its folder.
-   */
-  const reach = async (path: string, tool: string, kind: 'file' | 'folder') => {
-    const full = isAbsolute(path) ? resolve(path) : resolve(root, path)
-    const isAllowed = [root, ...allowed].some((dir) => within(dir, full))
-    if (isAllowed) return full
-    if (options.outside !== 'ask' || !access) {
-      throw new Error(`Path "${path}" is outside the workspace.`)
-    }
-    if (access.mode() === 'bypass') return full
-    const folder = kind === 'folder' ? full : dirname(full)
-    const yes = await allow(
-      folder,
-      `${tool} wants ${full}, outside the workspace (${root}). Allow ${folder} for this session? (y/n)`,
-    )
-    if (!yes) {
-      throw new Error(
-        `The user did not allow ${full}. It is outside the workspace.`,
-      )
-    }
-    return full
-  }
-  /** A path for the model: from the workspace, or the full path outside it. */
-  const shown = (full: string) =>
-    (within(root, full) ? relative(root, full) || '.' : full)
-      .split(sep)
-      .join('/')
-
-  /** The path of `file` from the folder `base`, with `/`, for a glob. */
-  const fromBase = (base: string, file: string) =>
-    relative(base, file).split(sep).join('/')
-
-  async function walk(dir: string, out: Array<string>): Promise<void> {
-    for (const entry of await readdir(dir, { withFileTypes: true })) {
-      if (entry.isDirectory()) {
-        if (!SKIP_DIRS.has(entry.name))
-          await walk(resolve(dir, entry.name), out)
-      } else out.push(resolve(dir, entry.name))
-      if (out.length > 5000) return
-    }
-  }
-
-  const tools = [
-    toolDefinition({
-      name: 'read_file',
-      description:
-        'Read a text file in the workspace. Lines are numbered from 1.',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          path: { type: 'string' },
-          offset: { type: 'number', description: 'First line, from 1' },
-          limit: { type: 'number' },
-        },
-        required: ['path'],
-      },
-      replay: 'safe',
-    }).server(async (args: unknown) => {
-      const full = await reach(stringArg(args, 'path'), 'read_file', 'file')
-      const lines = (await readFile(full, 'utf8')).split('\n')
-      const offset =
-        isRecord(args) && typeof args.offset === 'number'
-          ? Math.max(1, args.offset)
-          : 1
-      const limit =
-        isRecord(args) && typeof args.limit === 'number'
-          ? args.limit
-          : MAX_READ_LINES
-      return clip(
-        lines
-          .slice(offset - 1, offset - 1 + limit)
-          .map((line, index) => `${offset + index}\t${line}`)
-          .join('\n'),
-      )
-    }),
-    toolDefinition({
-      name: 'write_file',
-      description: 'Create or replace a file in the workspace.',
-      inputSchema: {
-        type: 'object',
-        properties: { path: { type: 'string' }, content: { type: 'string' } },
-        required: ['path', 'content'],
-      },
-    }).server(async (args: unknown) => {
-      const full = await reach(stringArg(args, 'path'), 'write_file', 'file')
-      await mkdir(dirname(full), { recursive: true })
-      await writeFile(full, stringArg(args, 'content'), 'utf8')
-      return `Wrote ${shown(full)}.`
-    }),
-    toolDefinition({
-      name: 'edit_file',
-      description:
-        'Replace exact text in a file. `old` must appear once, unless `replaceAll` is true.',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          path: { type: 'string' },
-          old: { type: 'string' },
-          new: { type: 'string' },
-          replaceAll: { type: 'boolean' },
-        },
-        required: ['path', 'old', 'new'],
-      },
-    }).server(async (args: unknown) => {
-      const full = await reach(stringArg(args, 'path'), 'edit_file', 'file')
-      const before = await readFile(full, 'utf8')
-      const oldText = stringArg(args, 'old')
-      const newText = stringArg(args, 'new')
-      const count = before.split(oldText).length - 1
-      const replaceAll = isRecord(args) && args.replaceAll === true
-      if (count === 0) throw new Error('The old text is not in the file.')
-      if (count > 1 && !replaceAll) {
-        throw new Error(
-          `The old text appears ${count} times. Add context, or set replaceAll.`,
-        )
-      }
-      await writeFile(full, before.split(oldText).join(newText), 'utf8')
-      return `Edited ${shown(full)} (${replaceAll ? count : 1} change${count > 1 && replaceAll ? 's' : ''}).`
-    }),
-    toolDefinition({
-      name: 'list_files',
-      description:
-        'List files in a folder (default: the workspace), optionally matching a glob like `src/**/*.ts`. The glob is from that folder.',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          pattern: { type: 'string' },
-          path: {
-            type: 'string',
-            description: 'The folder. Default: the workspace',
-          },
-        },
-      },
-      replay: 'safe',
-    }).server(async (args: unknown) => {
-      const base = await reach(
-        optionalString(args, 'path') ?? '.',
-        'list_files',
-        'folder',
-      )
-      const pattern = optionalString(args, 'pattern')
-      const files: Array<string> = []
-      await walk(base, files)
-      const regex = pattern ? globToRegExp(pattern) : undefined
-      const listed = files
-        .filter((file) => !regex || regex.test(fromBase(base, file)))
-        .map(shown)
-      return clip(listed.slice(0, 1000).join('\n') || 'No files.')
-    }),
-    toolDefinition({
-      name: 'grep',
-      description:
-        'Search file contents in a folder (default: the workspace) with a regular expression. Returns `file:line: text`.',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          pattern: { type: 'string' },
-          glob: { type: 'string' },
-          path: {
-            type: 'string',
-            description: 'The folder. Default: the workspace',
-          },
-        },
-        required: ['pattern'],
-      },
-      replay: 'safe',
-    }).server(async (args: unknown) => {
-      const regex = new RegExp(stringArg(args, 'pattern'))
-      const base = await reach(
-        optionalString(args, 'path') ?? '.',
-        'grep',
-        'folder',
-      )
-      const glob = optionalString(args, 'glob')
-      const fileFilter = glob ? globToRegExp(glob) : undefined
-      const files: Array<string> = []
-      await walk(base, files)
-      const hits: Array<string> = []
-      for (const file of files) {
-        if (fileFilter && !fileFilter.test(fromBase(base, file))) continue
-        if ((await stat(file)).size > 1_000_000) continue
-        const lines = (await readFile(file, 'utf8')).split('\n')
-        lines.forEach((line, index) => {
-          if (hits.length < 200 && regex.test(line))
-            hits.push(`${shown(file)}:${index + 1}: ${line.trim()}`)
-        })
-        if (hits.length >= 200) break
-      }
-      return clip(hits.join('\n') || 'No matches.')
-    }),
-    toolDefinition({
-      name: 'bash',
-      description:
-        'Run a shell command in the workspace folder. Output is cut at 20,000 characters.',
-      inputSchema: {
-        type: 'object',
-        properties: { command: { type: 'string' } },
-        required: ['command'],
-      },
-      replay: 'never',
-    }).server(
-      (args: unknown) =>
-        new Promise<string>((done) => {
-          exec(
-            stringArg(args, 'command'),
-            {
-              cwd: root,
-              timeout: options.bashTimeoutMs ?? 120_000,
-              maxBuffer: 10 * 1024 * 1024,
-            },
-            (error, stdout, stderr) => {
-              const code = error && 'code' in error ? error.code : 0
-              done(
-                clip(
-                  `exit code: ${String(code ?? 0)}\n${stdout}${stderr ? `\nstderr:\n${stderr}` : ''}`,
-                ),
-              )
-            },
-          )
-        }),
-    ),
-  ]
-  const prompt =
-    options.outside === 'ask'
-      ? `Your workspace is ${root}. Paths are relative to it. A path outside it asks the user first.`
-      : `Your workspace is ${root}. Paths are relative to it.`
-  return { tools, prompt }
-}
-
-/**
- * File and shell tools for a coding agent, in `root`: `read_file`,
- * `write_file`, `edit_file`, `list_files`, `grep`, and `bash`. Edits and
- * `bash` ask for approval through `permissions()`. A path outside `root` is
- * refused, or with `outside: 'ask'` the user is asked first.
- *
- * These tools run on this machine with the host's authority. Use a sandbox
- * for code you do not trust.
- *
- * @example
- * ```ts
- * workspaceTools({ root: process.cwd(), outside: 'ask' })
- * ```
- */
-export function workspaceTools(options: WorkspaceToolsOptions) {
-  return definePlugin({
-    name: 'tanstack/workspace-tools',
-    setup: (ctx) => {
-      const { tools, prompt } = createWorkspaceTools(options, {
-        ask: (message) => ctx.session.ask({ message }),
-        mode: () => ctx.config.get('mode'),
-      })
-      return {
-        tools,
-        prompts: [prompt],
-        contribute: [
-          PermissionRules.item({
-            tool: 'read_file',
-            decision: 'allow',
-            kind: 'read',
-          }),
-          PermissionRules.item({
-            tool: 'list_files',
-            decision: 'allow',
-            kind: 'read',
-          }),
-          PermissionRules.item({
-            tool: 'grep',
-            decision: 'allow',
-            kind: 'read',
-          }),
-          PermissionRules.item({
-            tool: 'write_file',
-            decision: 'ask',
-            kind: 'edit',
-          }),
-          PermissionRules.item({
-            tool: 'edit_file',
-            decision: 'ask',
-            kind: 'edit',
-          }),
-          PermissionRules.item({
-            tool: 'bash',
-            decision: 'ask',
-            kind: 'execute',
-          }),
-        ],
-      }
-    },
-  })
-}
diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
index 48d28b2c38..7281930506 100644
--- a/packages/ai-harness/src/host.ts
+++ b/packages/ai-harness/src/host.ts
@@ -1,7 +1,7 @@
 import { memoryPersistence } from '@tanstack/ai-persistence'
-import { SharedLog, loadLogState } from './log'
+import { SharedLog, loadLogState, logMessageStore } from './log'
 import { HarnessSession } from './session'
-import type { PromptCacheOptions, RunStore } from '@tanstack/ai'
+import type { ModelMessage, PromptCacheOptions, RunStore } from '@tanstack/ai'
 import type {
   AIPersistence,
   ArtifactStore,
@@ -14,17 +14,23 @@ import type {
   LeaseStore,
   LogStore,
   MetadataStore,
+  SessionIndexEntry,
+  SessionIndexListOptions,
+  SessionIndexPage,
+  SessionIndexStore,
 } from '@tanstack/ai-persistence'
 import type { AnyHarness } from './define'
 import type { ProjectOptions, ReduceOptions } from './log'
 import type { LeaseOptions } from './resume'
-import type { Principal } from './types'
+import type { ForkPoint, Principal } from './types'
 
 type SharedStores = {
   credentials?: CredentialStore
   artifacts?: ArtifactStore
   blobs?: BlobStore
   generationRuns?: GenerationRunStore
+  /** The session index that `host.sessions` reads. */
+  sessions?: SessionIndexStore
 }
 
 /** A durable host needs run leases, host leases, or both. */
@@ -43,6 +49,8 @@ type DurableLeases =
  *   `messages` and no `inbox`.
  *
  * Without `artifacts`, `blobs`, and `generationRuns`, media is kept in memory.
+ * With `sessions`, the host keeps one index entry per thread (see
+ * `host.sessions`).
  */
 export type HarnessPersistence =
   | AIPersistence<
@@ -106,6 +114,43 @@ export interface OpenSessionOptions {
   promptCache?: PromptCacheOptions
 }
 
+/**
+ * The session index of a host: one entry per thread, for a list of
+ * sessions. The host writes the entry when a session opens and after each
+ * turn. Without `stores.sessions`, `list` is empty, `get` is `undefined`,
+ * and `rename` and `delete` write nothing.
+ */
+export interface HostSessions {
+  /**
+   * Entries, newest `updatedAt` first. Default: only top-level sessions
+   * (`parentThreadId: null`). Pass a thread id to get its child sessions.
+   * Pass `principal` to get only the sessions of that user.
+   */
+  list: (options?: SessionIndexListOptions) => Promise<SessionIndexPage>
+  /** The entry of a thread, or `undefined`. */
+  get: (threadId: string) => Promise<SessionIndexEntry | undefined>
+  /**
+   * Set the title of a thread. Resolves to the changed entry, or to
+   * `undefined` for a thread that has no entry.
+   */
+  rename: (
+    threadId: string,
+    title: string,
+  ) => Promise<SessionIndexEntry | undefined>
+  /**
+   * Remove the index entry of a thread. Only the entry: the transcript, the
+   * log, and the other data of the thread stay in their stores.
+   */
+  delete: (threadId: string) => Promise<void>
+  /**
+   * Copy the transcript of a thread into a new thread, up to a message. The
+   * new thread gets its own entry, with the title, harness, and owner of the
+   * old one. Resolves to the new entry. Throws when the message id is not in
+   * the transcript.
+   */
+  fork: (threadId: string, at: ForkPoint) => Promise<SessionIndexEntry>
+}
+
 /** Runs sessions for one or more harnesses in this process. */
 export interface HarnessHost<TLogState = unknown> {
   /**
@@ -123,10 +168,71 @@ export interface HarnessHost<TLogState = unknown> {
    * `undefined`.
    */
   logState: (logId: string) => TLogState | undefined
+  /** The session index: list, rename, delete, and fork sessions. */
+  sessions: HostSessions
 }
 
 let warned = false
 
+/**
+ * Writes to the session index. `upsert` replaces the whole entry, so a
+ * change reads the entry, changes a copy, and writes it back. The changes of
+ * one thread run one at a time, so no change loses the fields of another.
+ */
+function sessionIndex(store: SessionIndexStore | undefined) {
+  const tails = new Map<string, Promise<void>>()
+  const serial = <T>(threadId: string, task: () => Promise<T>) => {
+    // The tail never rejects, so a failed change does not stop the next one.
+    const run = (tails.get(threadId) ?? Promise.resolve()).then(task)
+    const tail = run.then(
+      () => {},
+      () => {},
+    )
+    tails.set(threadId, tail)
+    void tail.then(() => {
+      if (tails.get(threadId) === tail) tails.delete(threadId)
+    })
+    return run
+  }
+  return {
+    get: async (threadId: string) => store?.get(threadId),
+    /**
+     * Write `change(entry)` for the thread. `change` gets `undefined` when
+     * the thread has no entry, and returns `undefined` to write nothing.
+     */
+    update: (
+      threadId: string,
+      change: (
+        entry: SessionIndexEntry | undefined,
+      ) => SessionIndexEntry | undefined,
+    ) =>
+      serial(threadId, async () => {
+        if (!store) return undefined
+        const next = change(await store.get(threadId))
+        if (next) await store.upsert(next)
+        return next
+      }),
+    remove: (threadId: string) =>
+      serial(threadId, async () => {
+        await store?.delete(threadId)
+      }),
+  }
+}
+
+/** @internal How a session writes its index entry. */
+export type SessionIndexWriter = ReturnType<typeof sessionIndex>
+
+/** The messages of `messages` up to the message `at` names. */
+function cutTranscript(messages: ReadonlyArray<ModelMessage>, at: ForkPoint) {
+  const isBefore = 'before' in at
+  const messageId = isBefore ? at.before : at.through
+  const index = messages.findIndex((message) => message.id === messageId)
+  if (index === -1) {
+    throw new Error(`The transcript has no message with id ${messageId}.`)
+  }
+  return messages.slice(0, isBefore ? index : index + 1)
+}
+
 /** How each host finds the open session of a chat turn. Not public API. */
 const turnFinders = new WeakMap<
   object,
@@ -207,7 +313,18 @@ export function createHarnessHost<TLogState = undefined>(
     },
   }
   const logStore = persistence.stores.log
-  const { metadata } = persistence.stores
+  const { metadata, sessions: sessionStore } = persistence.stores
+  const index = sessionIndex(sessionStore)
+  // The transcript of any thread, for a fork. On a durable host, a view of
+  // the log of that thread. ponytail: a thread that shares another log (a
+  // `logId` that is not its thread id) is not found. Keep the log id in the
+  // entry if that matters.
+  const transcripts = logStore
+    ? logMessageStore({
+        store: logStore,
+        ...(options.project ? { project: options.project } : {}),
+      })
+    : persistence.stores.messages
   const coalesceMs = options.coalesceMs ?? 100
   /** The shared log of each log id with an open session, by log id. */
   const logs = new Map<string, Promise<SharedLog<TLogState>>>()
@@ -262,6 +379,7 @@ export function createHarnessHost<TLogState = undefined>(
           credentials,
           media,
           hostId,
+          index,
           ...(logStore
             ? {
                 log: {
@@ -302,6 +420,41 @@ export function createHarnessHost<TLogState = undefined>(
       )
     },
     logState: (logId) => resolved.get(logId)?.state.reduced,
+    sessions: {
+      list: async (listOptions) =>
+        (await sessionStore?.list({ parentThreadId: null, ...listOptions })) ?? {
+          entries: [],
+        },
+      get: (threadId) => index.get(threadId),
+      rename: (threadId, title) =>
+        index.update(
+          threadId,
+          (entry) => entry && { ...entry, title, updatedAt: Date.now() },
+        ),
+      delete: (threadId) => index.remove(threadId),
+      async fork(threadId, at) {
+        if (!transcripts) {
+          throw new Error('host.sessions.fork needs stores.messages or stores.log.')
+        }
+        const kept = cutTranscript(await transcripts.loadThread(threadId), at)
+        const source = await index.get(threadId)
+        const now = Date.now()
+        // A sibling of the old thread, not a child: no parentThreadId.
+        const entry: SessionIndexEntry = {
+          threadId: `thread-${crypto.randomUUID()}`,
+          createdAt: now,
+          updatedAt: now,
+          ...(source?.harness ? { harness: source.harness } : {}),
+          ...(source?.title ? { title: `${source.title} (fork)` } : {}),
+          ...(source?.principal ? { principal: source.principal } : {}),
+        }
+        // On a durable host, this appends one transcript record to the new
+        // log.
+        await transcripts.saveThread(entry.threadId, kept)
+        await index.update(entry.threadId, () => entry)
+        return entry
+      },
+    },
   }
   turnFinders.set(host, async (name, operationId) => {
     for (const [key, opening] of sessions) {
diff --git a/packages/ai-harness/src/http.ts b/packages/ai-harness/src/http.ts
index cd2f884268..2aa51503e9 100644
--- a/packages/ai-harness/src/http.ts
+++ b/packages/ai-harness/src/http.ts
@@ -20,12 +20,14 @@ import {
   parseControlFrame,
   parseHarnessInput,
 } from './protocol'
+import { isRecord } from './utils'
 import type {
   ModelMessage,
   StreamChunk,
   UIMessage,
   WebSocketLike,
 } from '@tanstack/ai'
+import type { SessionIndexEntry } from '@tanstack/ai-persistence'
 import type { AnyHarness } from './define'
 import type { HarnessHost } from './host'
 import type { HostFrame } from './protocol'
@@ -114,6 +116,41 @@ function lastUserInput(messages: Array<UIMessage | ModelMessage>) {
   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 } = body
+  if (typeof threadId !== 'string') return undefined
+  switch (op) {
+    case 'rename':
+      return typeof title === 'string'
+        ? { op: 'rename' as const, threadId, title }
+        : undefined
+    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 {
@@ -192,6 +229,15 @@ async function mediaResponse(
  * - `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: 'delete', threadId }` (it
+ *   removes the index entry only), or `{ op: 'fork', threadId, before }` or
+ *   `{ op: 'fork', threadId, through }` with a message id. Rename and fork
+ *   answer with the entry, delete with 204. 403 when `canAccess` refuses
+ *   the thread, 404 for a thread this principal does not own.
  *
  * Each chat input runs as the principal that `authorize` returned for its
  * request, not as the one that opened the session first.
@@ -446,6 +492,57 @@ export function createHarnessHandler(
         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)
+        // The store keeps only this principal's entries. `canAccess` can
+        // still refuse some of them.
+        const page = await host.sessions.list({
+          principal,
+          ...(limit ? { limit: Number(limit) } : {}),
+          ...(cursor ? { cursor } : {}),
+          ...(parentThreadId ? { parentThreadId } : {}),
+        })
+        const allowed = await Promise.all(
+          page.entries.map((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(op.threadId, op.title)
+            return renamed
+              ? json(renamed)
+              : json({ error: 'not found' }, 404)
+          }
+          case 'delete':
+            await host.sessions.delete(op.threadId)
+            return new Response(null, { status: 204 })
+          case 'fork':
+            return json(await host.sessions.fork(op.threadId, op.at))
+        }
+      }
+
       if (request.method === 'POST' && route === 'media') {
         const threadId = url.searchParams.get('threadId')
         const name = url.searchParams.get('name')
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index d9f4909176..644e3811db 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -79,8 +79,15 @@ export type {
   HarnessHost,
   HarnessHostOptions,
   HarnessPersistence,
+  HostSessions,
   OpenSessionOptions,
 } from './host'
+export type {
+  SessionIndexEntry,
+  SessionIndexListOptions,
+  SessionIndexPage,
+  SessionIndexStore,
+} from '@tanstack/ai-persistence'
 
 export { HarnessSession } from './session'
 export type {
@@ -112,6 +119,7 @@ export type {
   BusyPolicy,
   ChatTurnResult,
   Cursor,
+  ForkPoint,
   HarnessInput,
   InputSettlement,
   MediaKind,
@@ -125,6 +133,7 @@ export type {
   TurnInfo,
   TurnOverrides,
   UserInput,
+  WaitingInput,
 } from './types'
 
 export {
diff --git a/packages/ai-harness/src/log.ts b/packages/ai-harness/src/log.ts
index bfb36c82a7..cd9036d4a0 100644
--- a/packages/ai-harness/src/log.ts
+++ b/packages/ai-harness/src/log.ts
@@ -15,6 +15,7 @@ import type {
   HarnessInput,
   InputSettlement,
   SessionEvent,
+  WaitingInput,
 } from './types'
 
 /** The records the harness writes to a session log. */
@@ -38,6 +39,11 @@ export type HarnessRecord =
   | { type: 'harness.input.joined'; inputId: string; into: string }
   | { type: 'harness.input.rejected'; inputId: string; reason: string }
   | { type: 'harness.input.abort'; inputId: string }
+  | {
+      type: 'harness.input.delivery'
+      inputId: string
+      delivery: WaitingInput['delivery']
+    }
   | {
       type: 'harness.input.settled'
       inputId: string
@@ -67,6 +73,7 @@ const HARNESS_RECORD_TYPES = new Set<string>([
   'harness.input.joined',
   'harness.input.rejected',
   'harness.input.abort',
+  'harness.input.delivery',
   'harness.input.settled',
   'harness.tool.result',
   'harness.tool.started',
@@ -111,6 +118,8 @@ export interface InputState {
   /** The host input that this input joined. */
   into?: string
   abortRequested: boolean
+  /** The delivery that a `setDelivery` input set. Recovery honors it. */
+  delivery?: WaitingInput['delivery']
   /** Transcript length when the input was last applied. */
   appliedAt?: number
   settlement?: InputSettlement
@@ -263,6 +272,12 @@ export function foldEntry(
         abortRequested: true,
       }))
       return
+    case 'harness.input.delivery':
+      updateInput(state, record.inputId, (input) => ({
+        ...input,
+        delivery: record.delivery,
+      }))
+      return
     case 'harness.input.settled':
       updateInput(state, record.inputId, (input) => ({
         ...input,
diff --git a/packages/ai-harness/src/plugins.ts b/packages/ai-harness/src/plugins.ts
index e9761a9edd..a7a7c78f5c 100644
--- a/packages/ai-harness/src/plugins.ts
+++ b/packages/ai-harness/src/plugins.ts
@@ -92,11 +92,13 @@ export interface PluginContributions {
    * Change the tool list of a turn: every tool the model gets, after
    * `discoverTools`. Return the new list. Runs before prompts resolve, so a
    * prompt `text()` can describe the tools this returned. Code mode uses it to
-   * move tools behind `execute_typescript`.
+   * move tools behind `execute_typescript`. `model` is the model id of the
+   * turn's adapter, so the list can differ for each model.
    */
-  prepareTools?: (
-    tools: ReadonlyArray<AnyTool>,
-  ) => ReadonlyArray<AnyTool> | Promise<ReadonlyArray<AnyTool>>
+  prepareTools?: (turn: {
+    tools: ReadonlyArray<AnyTool>
+    model: string
+  }) => ReadonlyArray<AnyTool> | Promise<ReadonlyArray<AnyTool>>
 }
 
 /** Plugin state that survives restarts, stored in the metadata store. */
@@ -408,8 +410,11 @@ const NO_SERVICES: PluginServices = {
     principal: undefined,
     snapshot: unavailable('ctx.session'),
     prompt: unavailable('ctx.session'),
+    note: unavailable('ctx.session'),
     transcript: unavailable('ctx.session'),
     replaceTranscript: unavailable('ctx.session'),
+    entry: unavailable('ctx.session'),
+    updateEntry: unavailable('ctx.session'),
     ask: unavailable('ctx.session'),
     authRequired: unavailable('ctx.session'),
     setConfig: unavailable('ctx.session'),
diff --git a/packages/ai-harness/src/protocol.ts b/packages/ai-harness/src/protocol.ts
index 6fc57b1a13..50d5155764 100644
--- a/packages/ai-harness/src/protocol.ts
+++ b/packages/ai-harness/src/protocol.ts
@@ -42,6 +42,8 @@ const INPUT_OPS = new Set([
   'resolve',
   'agent',
   'cancel',
+  'cancelInput',
+  'setDelivery',
   'command',
   'answer',
   'config',
@@ -80,6 +82,14 @@ export function parseHarnessInput(value: unknown): HarnessInput {
   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'.")
+  }
   if (value.inputId !== undefined && typeof value.inputId !== 'string') {
     throw new Error('Invalid input: inputId must be a string.')
   }
@@ -155,6 +165,10 @@ export async function applyInput(
       return session.resolve(input.resume, id)
     case 'cancel':
       return session.cancel(input.operationId)
+    case 'cancelInput':
+      return session.cancelInput(input.inputId)
+    case 'setDelivery':
+      return session.setDelivery(input.inputId, input.delivery)
     case 'command': {
       const operation = session.command(
         input.name,
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index cd97554cd2..22a9b5a36c 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -9,6 +9,7 @@ import {
   compactForModel,
   convertSchemaToJsonSchema,
   createSubagentId,
+  fromSpecTokenUsage,
   maxIterations,
   modelMessagesToUIMessages,
   provideLogRecords,
@@ -52,6 +53,7 @@ import type {
   ProviderKeys,
   ResolvedPromptCache,
   RunAgentResumeItem,
+  RunFinishedEvent,
   RunRecord,
   SchemaInput,
   Scope,
@@ -75,10 +77,16 @@ import type {
   LogRecord,
   LogStore,
   MessageStore,
+  SessionIndexEntry,
 } from '@tanstack/ai-persistence'
 import type { AuthRequiredError, CredentialsAccess } from './auth'
 import type { EventFeed } from './feed'
-import type { InputState, LogWriter, ProjectOptions } from './log'
+import type {
+  HarnessRecord,
+  InputState,
+  LogWriter,
+  ProjectOptions,
+} from './log'
 import type { DurableBind } from './durable-tool'
 import type { LeaseOptions } from './resume'
 import type { MediaStore } from './media'
@@ -92,7 +100,7 @@ import type {
 } from './agents'
 import type { AnyHarness, HarnessAgentsOf } from './define'
 import type { RecoverDecision, TurnAdditions } from './turn'
-import type { HarnessPersistence } from './host'
+import type { HarnessPersistence, SessionIndexWriter } from './host'
 import type {
   AgentGroup,
   HarnessPlugin,
@@ -116,6 +124,7 @@ import type {
   TurnInfo,
   TurnOverrides,
   UserInput,
+  WaitingInput,
 } from './types'
 
 /** Options for running an agent from code. */
@@ -183,6 +192,12 @@ export interface SessionSnapshot {
     startedCursor?: Cursor
   }>
   queuedTurns: number
+  /**
+   * The inputs that wait, in the order they run: `session.inputs()`. A
+   * session always sets it. A snapshot built by hand (a test fixture) can
+   * leave it out.
+   */
+  waitingInputs?: Array<WaitingInput>
   pendingInterrupts: Array<Interrupt>
   /** Questions a command or a plugin asked, waiting for `session.answer`. */
   pendingQuestions: Array<{
@@ -243,6 +258,8 @@ export interface SessionDependencies {
   principal?: Principal
   /** Identifies this host on run leases. */
   hostId: string
+  /** Writes the session index entry of the thread. */
+  index: SessionIndexWriter
   /** The session log of a durable host. */
   log?: {
     store: LogStore
@@ -283,6 +300,21 @@ interface QueuedTurn {
   sentMessage?: UserInput
 }
 
+/**
+ * A message for the running turn. A steer that the turn never reached (no
+ * further model call) runs as the next turn instead.
+ */
+interface WaitingSteer {
+  inputId: string
+  message: UserInput
+  operation?: OperationImpl<ChatTurnResult>
+  /** Used only when the steer runs as its own turn. A join ignores them. */
+  overrides?: TurnOverrides
+  principal?: Principal
+  /** Used only when the steer runs as its own turn, as `overrides`. */
+  context?: unknown
+}
+
 /** The interrupts the last turn stopped for, and how a resolve continues it. */
 interface InterruptedTurn {
   runId: string
@@ -414,6 +446,50 @@ function turnContext(harness: unknown, input: unknown) {
   return harness !== undefined ? harness : input
 }
 
+type EntryUsage = NonNullable<SessionIndexEntry['usage']>
+
+/**
+ * The usage of one finished run, as session index totals. `undefined` when
+ * the run has no usage. A child run counts nothing: the run of its parent
+ * has the child's usage too.
+ */
+function entryUsageOf(chunk: RunFinishedEvent) {
+  if ('subagentRunId' in chunk && chunk.subagentRunId) return undefined
+  const { usage } = chunk
+  const tokens =
+    usage === undefined || Array.isArray(usage)
+      ? fromSpecTokenUsage(usage, chunk.metadata?.tanstack?.usage)
+      : usage
+  if (!tokens) return undefined
+  const counted: EntryUsage = {
+    // `usage[]` has one item per model call, the calls of children too.
+    turns: Array.isArray(usage) ? usage.length : 1,
+    promptTokens: tokens.promptTokens,
+    completionTokens: tokens.completionTokens,
+    totalTokens: tokens.totalTokens,
+    cachedTokens: tokens.promptTokensDetails?.cachedTokens ?? 0,
+    cacheWriteTokens: tokens.promptTokensDetails?.cacheWriteTokens ?? 0,
+    ...(tokens.cost !== undefined ? { cost: tokens.cost } : {}),
+  }
+  return counted
+}
+
+/** `total` plus `next`. A cost is kept when either one has a cost. */
+function addEntryUsage(total: EntryUsage | undefined, next: EntryUsage) {
+  if (!total) return next
+  const hasCost = total.cost !== undefined || next.cost !== undefined
+  const sum: EntryUsage = {
+    turns: total.turns + next.turns,
+    promptTokens: total.promptTokens + next.promptTokens,
+    completionTokens: total.completionTokens + next.completionTokens,
+    totalTokens: total.totalTokens + next.totalTokens,
+    cachedTokens: total.cachedTokens + next.cachedTokens,
+    cacheWriteTokens: total.cacheWriteTokens + next.cacheWriteTokens,
+    ...(hasCost ? { cost: (total.cost ?? 0) + (next.cost ?? 0) } : {}),
+  }
+  return sum
+}
+
 /** A short transcript note about how an agent ended, for the next turn. */
 function referenceNote(
   agent: string,
@@ -448,6 +524,9 @@ export function acceptedKinds(
 /** The inputs that run as chat turns. They settle, and so do agent inputs. */
 const CHAT_OPS = new Set<string>(['prompt', 'steer', 'followUp', 'resolve'])
 
+/** The inputs that change a waiting input. */
+const CONTROL_OPS = new Set<string>(['cancelInput', 'setDelivery'])
+
 /** Why a turn stops when its input passes its time limit. */
 const TIMEOUT_REASON = 'harness:input-timeout'
 
@@ -574,20 +653,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   private readonly agentRegistry = new AgentRegistry()
   private readonly operations = new Map<string, OperationImpl<unknown>>()
   private readonly queue: Array<QueuedTurn> = []
-  /**
-   * Messages for the running turn. A steer that the turn never reached (no
-   * further model call) runs as the next turn instead.
-   */
-  private readonly steerQueue: Array<{
-    inputId: string
-    message: UserInput
-    operation?: OperationImpl<ChatTurnResult>
-    /** Used only when the steer runs as its own turn. A join ignores them. */
-    overrides?: TurnOverrides
-    principal?: Principal
-    /** Used only when the steer runs as its own turn, as `overrides`. */
-    context?: unknown
-  }> = []
+  private readonly steerQueue: Array<WaitingSteer> = []
   /**
    * Waiting steers with an abort request. An id lands here before the abort
    * append, so a join that runs during that append skips the steer.
@@ -614,6 +680,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   /** Gives each durable tool call its steps in the log. One per session. */
   private bindTool: DurableBind | undefined
   private readonly hostId: string
+  private readonly index: SessionIndexWriter
   private readonly lease: LeaseOptions | undefined
   private readonly listeners = new Map<string, Set<(value: unknown) => void>>()
   private readonly configValues = new Map<string, unknown>()
@@ -682,6 +749,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     this.principal = deps.principal
     this.onClose = deps.onClose
     this.hostId = deps.hostId
+    this.index = deps.index
     this.lease = deps.lease
     this.log = deps.log
     // A durable host gets its log view in `open()`.
@@ -817,6 +885,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       await this.loadConfig()
       await this.loadPluginState()
       await this.loadInterrupted()
+      // Before recovery: a turn that recovery runs updates this entry.
+      await this.openEntry()
       if (this.writer) {
         await this.recoverFromLog(this.writer)
         return
@@ -831,6 +901,23 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }
   }
 
+  /**
+   * Write the index entry of this thread on open: a new entry the first
+   * time, else a new `updatedAt`. The owner is who opened the thread first,
+   * so an open by another user does not change it.
+   */
+  private async openEntry() {
+    const now = Date.now()
+    await this.index.update(this.threadId, (entry) => ({
+      threadId: this.threadId,
+      createdAt: now,
+      ...entry,
+      harness: entry?.harness ?? this.harness.name,
+      updatedAt: now,
+      ...storedPrincipal(entry?.principal ?? this.principal),
+    }))
+  }
+
   /**
    * A durable host gives the session its view of the log, and the session
    * writes through it: the log is the event feed and the transcript. Then
@@ -1184,15 +1271,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     const isTaken =
       runId !== undefined &&
       (this.operations.has(runId) || (await this.isRunTaken(runId)))
-    if (isTaken) {
-      this.reject(inputId, 'conflict')
-      return { inputId, status: 'rejected', reason: 'conflict' }
-    }
+    if (isTaken) return this.reject(inputId, 'conflict')
     const answers = this.interrupted
-    if (!answers) {
-      this.reject(inputId, 'no_pending_interrupts')
-      return { inputId, status: 'rejected', reason: 'no_pending_interrupts' }
-    }
+    if (!answers) return this.reject(inputId, 'no_pending_interrupts')
     // A client answers on RUN_FINISHED, while the interrupted turn still
     // ends. The resolve runs right after it.
     const isEnding = this.activeTurn?.id === answers.runId
@@ -1200,8 +1281,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       (this.activeTurn && !isEnding) ||
       this.queue.some((turn) => turn.answers?.runId === answers.runId)
     ) {
-      this.reject(inputId, 'busy')
-      return { inputId, status: 'rejected', reason: 'busy' }
+      return this.reject(inputId, 'busy')
     }
     // A cancelled sign-in fails its tool when the turn runs it again.
     for (const entry of resume) {
@@ -1239,16 +1319,14 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       ? this.operations.get(operationId)
       : this.activeTurn
     if (!target || target.isSettled()) {
-      this.reject(inputId, 'not_running')
-      return { inputId, status: 'rejected', reason: 'not_running' }
+      return this.reject(inputId, 'not_running')
     }
     const waitingSteer = this.steerQueue.find(
       (steer) => steer.operation === target,
     )
     // A join took it, so it ends with the running turn, as a joined steer.
     if (waitingSteer && this.joining.has(waitingSteer.inputId)) {
-      this.reject(inputId, 'not_running')
-      return { inputId, status: 'rejected', reason: 'not_running' }
+      return this.reject(inputId, 'not_running')
     }
     // It never joins now, and settles when the running turn ends.
     if (waitingSteer) this.abortedSteers.add(waitingSteer.inputId)
@@ -1282,6 +1360,116 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     return { inputId, status: 'accepted', operationId: target.id }
   }
 
+  /**
+   * The inputs that wait, in the order they run: first the steers for the
+   * running turn, then the queued turns. Change one with `cancelInput` or
+   * `setDelivery`.
+   *
+   * @example
+   * ```ts
+   * for (const input of session.inputs()) {
+   *   if (input.delivery === 'queue') await session.cancelInput(input.inputId)
+   * }
+   * ```
+   */
+  inputs() {
+    const waiting: Array<WaitingInput> = []
+    // A steer with an abort request never runs. It settles with the turn.
+    for (const steer of this.steerQueue) {
+      if (this.isAbortRequested(steer.inputId)) continue
+      waiting.push({
+        inputId: steer.inputId,
+        delivery: 'steer',
+        message: steer.message,
+      })
+    }
+    // A resolve and a turn that recovery runs again have no new message.
+    for (const turn of this.queue) {
+      if (turn.inputId === undefined || turn.message === undefined) continue
+      waiting.push({
+        inputId: turn.inputId,
+        delivery: 'queue',
+        message: turn.message,
+      })
+    }
+    return waiting
+  }
+
+  /**
+   * Cancel an input that waits, so it never runs, also after a restart. It
+   * settles `aborted`. An input that started, or that joins the running
+   * turn now, is refused with `not_waiting`: stop it with
+   * `cancel(operationId)`.
+   *
+   * @example
+   * ```ts
+   * await session.followUp('Then write the tests.', { inputId: 'tests' })
+   * await session.cancelInput('tests')
+   * ```
+   */
+  async cancelInput(target: string): Promise<Receipt> {
+    const inputId = createInputId()
+    await this.accept(inputId, { op: 'cancelInput', inputId: target })
+    const taken = this.takeWaiting(target)
+    if (!taken) return this.reject(inputId, 'not_waiting')
+    await this.applyControl(inputId, {
+      type: 'harness.input.abort',
+      inputId: target,
+    })
+    // Without a log, the inbox entry must not stay pending: a restart runs
+    // pending entries.
+    if (!this.writer) await this.inbox.markRejected(target, 'cancelled')
+    const { operation } = taken
+    await this.settle({
+      inputId: target,
+      outcome: 'aborted',
+      ...(operation ? { operationId: operation.id } : {}),
+    })
+    if (operation) {
+      operation.fail('cancelled', new Error('Cancelled before it started.'))
+      this.publishFinished(operation)
+    }
+    return { inputId, status: 'accepted' }
+  }
+
+  /**
+   * Move an input that waits. `'steer'` joins it to the running turn at the
+   * next model call. `'queue'` runs it as its own turn, after the queued
+   * turns. An input that started, or that joins the running turn now, is
+   * refused with `not_waiting`. On a durable host the log keeps the
+   * delivery, and a restart honors it. Without a log, it is kept in memory.
+   *
+   * @example
+   * ```ts
+   * await session.followUp('Use tabs, not spaces.', { inputId: 'style' })
+   * await session.setDelivery('style', 'steer')
+   * ```
+   */
+  async setDelivery(
+    target: string,
+    delivery: WaitingInput['delivery'],
+  ): Promise<Receipt> {
+    const inputId = createInputId()
+    await this.accept(inputId, { op: 'setDelivery', inputId: target, delivery })
+    const current = this.inputs().find((input) => input.inputId === target)
+    if (current?.delivery !== delivery) {
+      const taken = this.takeWaiting(target)
+      if (!taken) return this.reject(inputId, 'not_waiting')
+      if (delivery === 'steer') this.steerQueue.push(taken)
+      else this.enqueueTurn(this.steerTurn(taken))
+    }
+    await this.applyControl(inputId, {
+      type: 'harness.input.delivery',
+      inputId: target,
+      delivery,
+    })
+    this.feed.publish(
+      'session',
+      customEvent(HARNESS_EVENTS.inputDelivery, { inputId: target, delivery }),
+    )
+    return { inputId, status: 'accepted' }
+  }
+
   /**
    * How a chat input ended: `completed`, `failed`, `aborted`, or
    * `interrupted` (the turn waits for human input). It waits until the input
@@ -1351,6 +1539,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       })),
       // A steer that waits to join the running turn waits too.
       queuedTurns: this.queue.length + this.steerQueue.length,
+      waitingInputs: this.inputs(),
       pendingInterrupts:
         this.activeResume && !this.activeTurn?.isSettled()
           ? []
@@ -1440,17 +1629,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     const inputId = createInputId()
     await this.accept(inputId, { op: 'config', key, value })
     const entry = this.sessionPlugins?.config.get(key)
-    if (!entry) {
-      this.reject(inputId, 'unknown_config')
-      return { inputId, status: 'rejected', reason: 'unknown_config' }
-    }
+    if (!entry) return this.reject(inputId, 'unknown_config')
     let checked: unknown
     try {
       checked = checkConfigValue(key, entry.option, value)
     } catch (error) {
       const reason = error instanceof Error ? error.message : String(error)
-      this.reject(inputId, reason)
-      return { inputId, status: 'rejected', reason }
+      return this.reject(inputId, reason)
     }
     this.configValues.set(key, checked)
     await this.persistence.stores.metadata?.set(
@@ -1533,17 +1718,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       value: isSecret ? '[secret]' : value,
     })
     const question = this.questions.get(questionId)
-    if (!question) {
-      this.reject(inputId, 'unknown_question')
-      return { inputId, status: 'rejected', reason: 'unknown_question' }
-    }
+    if (!question) return this.reject(inputId, 'unknown_question')
     let checked: unknown = value
     if (question.schema !== undefined) {
       const result = await validateWithStandardSchema(question.schema, value)
       if (!result.success) {
         const reason = `Invalid answer: ${result.issues.map((issue) => issue.message).join(', ')}`
-        this.reject(inputId, reason)
-        return { inputId, status: 'rejected', reason }
+        return this.reject(inputId, reason)
       }
       checked = result.data
     }
@@ -1913,9 +2094,27 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       // A plugin turn always waits its turn. It cannot see a busy rejection.
       prompt: (text) =>
         this.prompt(text, { busy: 'queue', principal: sender() }),
+      note: async (text, options) => {
+        await this.addNote(text)
+        if (options?.wake) await this.followUp(text, { principal: sender() })
+      },
       transcript: () => this.transcript(),
       replaceTranscript: (messages) =>
         this.messages.saveThread(this.threadId, messages),
+      entry: () => this.index.get(this.threadId),
+      // Only these fields: a plugin cannot change the owner or the parent.
+      updateEntry: ({ title, metadata, usage }) =>
+        this.index.update(
+          this.threadId,
+          (entry) =>
+            entry && {
+              ...entry,
+              ...(title !== undefined ? { title } : {}),
+              ...(metadata !== undefined ? { metadata } : {}),
+              ...(usage !== undefined ? { usage } : {}),
+              updatedAt: Date.now(),
+            },
+        ),
       // The public type narrows the answer from the schema.
       ask: ((question: Question<SchemaInput | undefined>) =>
         this.ask(question)) as PluginSessionApi['ask'],
@@ -2166,13 +2365,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
    */
   private async prepareTools(
     preparers: MountedPlugins['preparers'],
-    tools: Array<AnyTool>,
+    turn: { tools: Array<AnyTool>; model: string },
     operation: OperationImpl<ChatTurnResult>,
   ): Promise<Array<AnyTool>> {
-    let prepared = tools
+    let prepared = turn.tools
     for (const { prepare, owner } of preparers) {
       try {
-        prepared = [...(await prepare(prepared))]
+        prepared = [...(await prepare({ tools: prepared, model: turn.model }))]
       } catch (error) {
         this.warn(operation, owner, error)
       }
@@ -2257,7 +2456,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     const canJoin = this.harness.turn?.canJoin
     const turnPrincipal = this.sender()
     let count = 0
-    for (const steer of this.steerQueue) {
+    const checked = [...this.steerQueue]
+    for (const steer of checked) {
       if (!this.joining.has(steer.inputId)) {
         if (this.isAbortRequested(steer.inputId)) break
         const candidate = {
@@ -2273,12 +2473,15 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       }
       count += 1
     }
-    // A cancel can land while canJoin runs. No await from here to the claim.
+    // A cancel or a move can land while canJoin runs. A moved steer shifts
+    // the list, so only steers still at their checked place join. No await
+    // from here to the claim.
     const steers = this.steerQueue.slice(0, count)
     const late = steers.findIndex(
-      (steer) =>
-        !this.joining.has(steer.inputId) &&
-        this.isAbortRequested(steer.inputId),
+      (steer, index) =>
+        steer !== checked[index] ||
+        (!this.joining.has(steer.inputId) &&
+          this.isAbortRequested(steer.inputId)),
     )
     const taken = late >= 0 ? steers.slice(0, late) : steers
     for (const steer of taken) this.joining.add(steer.inputId)
@@ -2625,6 +2828,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     let text = ''
     let interrupts: Array<Interrupt> | undefined
     let failure: string | undefined
+    /** What the model calls of this turn spent, for the session index. */
+    let turnUsage: EntryUsage | undefined
     const captured: Array<MediaRecord> = []
     // What plugins and the router see of this turn. A turn that recovery
     // runs again gets the message its input sent.
@@ -2702,6 +2907,12 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         .map((pick) => pick(info))
         .filter((adapter) => adapter !== undefined)
         .at(-1)
+      // A keyed adapter is built for this turn with the user's key. A
+      // missing key publishes `auth_required` and fails the turn. It is
+      // built before `prepareTools`, which gets its model id.
+      const model = overrides?.adapter ?? picked ?? this.harness.adapter
+      if (!model) throw new Error(NO_MODEL)
+      const adapter: AnyTextAdapter = await this.keys.adapter(model)
       const resolvePrompt = (prompt: string | (() => string)) =>
         typeof prompt === 'function' ? prompt() : prompt
       const turnTools = overrides?.tools ?? []
@@ -2719,7 +2930,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       // Before the chat() options below: prompts may describe these tools.
       const prepared = await this.prepareTools(
         [...(session?.preparers ?? []), ...(runPlugins?.preparers ?? [])],
-        [...staticTools, ...discovered],
+        { tools: [...staticTools, ...discovered], model: adapter.model },
         operation,
       )
       // A durable host gives each durableTool call its steps in the log. The
@@ -2742,11 +2953,6 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         retention: turnCache?.retention ?? this.promptCache.retention,
         key: turnCache?.key ?? this.promptCache.key,
       }
-      // A keyed adapter is built for this turn with the user's key. A
-      // missing key publishes `auth_required` and fails the turn.
-      const model = overrides?.adapter ?? picked ?? this.harness.adapter
-      if (!model) throw new Error(NO_MODEL)
-      const adapter: AnyTextAdapter = await this.keys.adapter(model)
       let message =
         turn.message !== undefined
           ? await this.userMessage(turn.message)
@@ -2894,6 +3100,9 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
             // reads, searches, and calls tools needs more before it can answer.
             agentLoopStrategy:
               this.harness.agentLoopStrategy ?? maxIterations(50),
+            ...(this.harness.toolExecution !== undefined
+              ? { toolExecution: this.harness.toolExecution }
+              : {}),
             ...(this.harness.modelOptions !== undefined
               ? { modelOptions: this.harness.modelOptions }
               : {}),
@@ -2914,6 +3123,10 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           routedFrom = undefined
           for await (const chunk of stream) {
             cards?.processChunk(chunk)
+            if (chunk.type === EventType.RUN_FINISHED) {
+              const counted = entryUsageOf(chunk)
+              if (counted) turnUsage = addEntryUsage(turnUsage, counted)
+            }
             // chat() refused the resume before it ran anything.
             if (
               chunk.type === EventType.RUN_ERROR &&
@@ -3100,6 +3313,28 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       )
     }
 
+    // The index entry gets the time of the turn and what it spent, before the
+    // turn ends. A deleted entry stays deleted. A failed write does not fail
+    // the turn.
+    const spent = turnUsage
+    await this.index
+      .update(
+        this.threadId,
+        (entry) =>
+          entry && {
+            ...entry,
+            updatedAt: Date.now(),
+            ...(spent ? { usage: addEntryUsage(entry.usage, spent) } : {}),
+          },
+      )
+      .catch((error: unknown) =>
+        this.warn(
+          operation,
+          'harness:sessions',
+          `The session index was not updated. ${String(error)}`,
+        ),
+      )
+
     const { inputId } = turn
     // The turn and every input that joined it settle in one append. The
     // settlement lands before the operation ends, so a caller that sees the
@@ -3217,22 +3452,68 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     }
     // A resolve that answers the turn that just ended runs first.
     const at = this.queue[0]?.answers ? 1 : 0
-    this.queue.splice(
-      at,
-      0,
-      ...rest.map((steer) => {
-        const next = steer.operation ?? this.createTurnOperation()
-        this.bindTurn(steer.inputId, next)
-        return {
-          operation: next,
-          message: steer.message,
-          inputId: steer.inputId,
-          overrides: steer.overrides,
-          principal: steer.principal,
-          context: steer.context,
-        }
-      }),
+    this.queue.splice(at, 0, ...rest.map((steer) => this.steerTurn(steer)))
+  }
+
+  /** A waiting steer as its own turn, with its own operation. */
+  private steerTurn(steer: WaitingSteer) {
+    const operation = steer.operation ?? this.createTurnOperation()
+    this.bindTurn(steer.inputId, operation)
+    const turn: QueuedTurn = { ...steer, operation }
+    return turn
+  }
+
+  /**
+   * Take a waiting input out of the steers or the queue, so it does not run
+   * from there. `undefined` when it does not wait: it started, a join holds
+   * it, it has an abort request, or the id is not known.
+   */
+  private takeWaiting(inputId: string) {
+    const steer = this.steerQueue.find(
+      (item) =>
+        item.inputId === inputId &&
+        !this.joining.has(inputId) &&
+        !this.isAbortRequested(inputId),
     )
+    // This shifts the later steers. `claimJoins` sees that and skips them.
+    if (steer) {
+      this.steerQueue.splice(this.steerQueue.indexOf(steer), 1)
+      return steer
+    }
+    const turn = this.queue.find((item) => item.inputId === inputId)
+    const message = turn?.message
+    if (!turn || message === undefined) return undefined
+    this.queue.splice(this.queue.indexOf(turn), 1)
+    const taken: WaitingSteer = {
+      inputId,
+      message,
+      operation: turn.operation,
+      overrides: turn.overrides,
+      principal: turn.principal,
+      context: turn.context,
+    }
+    return taken
+  }
+
+  /**
+   * Mark a `cancelInput` or `setDelivery` input applied. On a durable host,
+   * `change` lands in the same append, so a crash never keeps one without
+   * the other.
+   */
+  private async applyControl(inputId: string, change: HarnessRecord) {
+    if (!this.writer) {
+      await this.inbox.markApplied(inputId, 'session')
+      return
+    }
+    await this.writer.append([
+      change,
+      {
+        type: 'harness.input.applied',
+        inputId,
+        operationId: 'session',
+        attempt: 1,
+      },
+    ])
   }
 
   /**
@@ -3569,8 +3850,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   ): Promise<void> {
     const note = referenceNote(name, result, ended)
     if ((options.attach ?? 'reference') === 'reference') {
-      this.pendingNotes.push(note)
-      if (!this.activeTurn) await this.flushNotes()
+      await this.addNote(note)
     }
     if (options.wake) {
       void this.followUp(`Background agent ${name} ${ended}: ${note}`, {
@@ -3628,7 +3908,16 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     )
   }
 
-  /** Write queued agent notes to the transcript while no turn is writing it. */
+  /**
+   * Add an assistant note to the transcript: at once when no turn runs, else
+   * before the next turn starts.
+   */
+  private async addNote(note: string) {
+    this.pendingNotes.push(note)
+    if (!this.activeTurn) await this.flushNotes()
+  }
+
+  /** Write queued notes to the transcript while no turn is writing it. */
   private async flushNotes(): Promise<void> {
     const messages = this.messages
     if (this.pendingNotes.length === 0) return
@@ -3745,7 +4034,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     )
   }
 
-  private reject(inputId: string, reason: string): void {
+  /** Refuse an input. Returns its rejected receipt. */
+  private reject(inputId: string, reason: string) {
     if (this.writer) {
       void this.writer
         .append([{ type: 'harness.input.rejected', inputId, reason }])
@@ -3753,11 +4043,13 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     } else {
       void this.inbox.markRejected(inputId, reason)
     }
-    this.receipts.set(inputId, { inputId, status: 'rejected', reason })
+    const receipt: Receipt = { inputId, status: 'rejected', reason }
+    this.receipts.set(inputId, receipt)
     this.feed.publish(
       'session',
       customEvent(HARNESS_EVENTS.inputRejected, { inputId, reason }),
     )
+    return receipt
   }
 
   /**
@@ -4046,6 +4338,34 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     return answer ?? decision
   }
 
+  /**
+   * A `cancelInput` or `setDelivery` whose own record is in the log, but not
+   * its change: a crash cut it. Apply it now, before any input runs. When
+   * its input does not wait any more, reject it with `not_waiting`. Other
+   * ops are not changed.
+   */
+  private async recoverControl(writer: LogWriter, logged: InputState) {
+    const { input } = logged
+    if (input.op !== 'cancelInput' && input.op !== 'setDelivery') return
+    const target = writer.state.inputs.get(input.inputId)
+    const isWaiting =
+      target?.status === 'pending' && 'message' in target.input
+    if (!isWaiting) {
+      this.reject(logged.inputId, 'not_waiting')
+      return
+    }
+    await this.applyControl(
+      logged.inputId,
+      input.op === 'cancelInput'
+        ? { type: 'harness.input.abort', inputId: input.inputId }
+        : {
+            type: 'harness.input.delivery',
+            inputId: input.inputId,
+            delivery: input.delivery,
+          },
+    )
+  }
+
   /**
    * Recover a durable session from its log, input by input, in admission
    * order. A chat turn whose host stopped (its run lease expired) settles
@@ -4053,16 +4373,25 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
    * time is left, settles `completed` when the log already has its final
    * answer, and else runs again as the next attempt. An agent run whose host
    * stopped settles `failed` and does not run again: it has no checkpoints.
-   * An input that never ran runs now. Other inputs are rejected with
-   * `expired_on_restart`.
+   * An input that never ran runs now. One that a `setDelivery` sent to
+   * `steer` joins the turn that runs, when one does. A `cancelInput` or
+   * `setDelivery` that a crash cut before it was applied applies first.
+   * Other inputs are rejected with `expired_on_restart`.
    */
   private async recoverFromLog(writer: LogWriter): Promise<void> {
     const runs = this.persistence.stores.runs
     const maxAttempts = this.harness.durability?.maxAttempts ?? 10
+    const logged = [...writer.state.inputs.values()]
+    for (const input of logged) {
+      if (input.status === 'pending') await this.recoverControl(writer, input)
+    }
+    // Read again: the pass above changed the inputs it applied to.
     const inputs = [...writer.state.inputs.values()]
     for (const input of inputs) {
       const isChat = CHAT_OPS.has(input.input.op)
       if (input.status === 'pending') {
+        // The pass above handled it.
+        if (CONTROL_OPS.has(input.input.op)) continue
         if (!(isChat && 'message' in input.input)) {
           this.reject(input.inputId, 'expired_on_restart')
           continue
@@ -4083,15 +4412,18 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           })
           continue
         }
-        const operation = this.createTurnOperation()
-        this.bindTurn(input.inputId, operation)
-        this.enqueueTurn({
-          operation,
-          message: input.input.message,
+        const steer: WaitingSteer = {
           inputId: input.inputId,
+          message: input.input.message,
           principal: input.principal,
           context: input.input.context,
-        })
+        }
+        // Else it runs as its own turn, as `steer()` does when no turn runs.
+        if (input.delivery === 'steer' && this.activeTurn) {
+          this.steerQueue.push(steer)
+          continue
+        }
+        this.enqueueTurn(this.steerTurn(steer))
         continue
       }
       const isAgent = input.input.op === 'agent'
diff --git a/packages/ai-harness/src/types.ts b/packages/ai-harness/src/types.ts
index c1394b1ad4..3f2be85b08 100644
--- a/packages/ai-harness/src/types.ts
+++ b/packages/ai-harness/src/types.ts
@@ -94,6 +94,8 @@ export interface SessionEvent {
  * screen the user is on. It is stored with the input, so a turn that runs
  * again after a restart sees the same value. It is client data: do not trust
  * it. Who sent the input is the principal from `authorize`, not a field here.
+ *
+ * In `cancelInput` and `setDelivery`, `inputId` is the input that waits.
  */
 export type HarnessInput = (
   | { op: 'prompt'; message: UserInput; busy?: BusyPolicy; context?: unknown }
@@ -102,11 +104,39 @@ export type HarnessInput = (
   | { op: 'resolve'; resume: Array<RunAgentResumeItem> }
   | { op: 'agent'; agent: string; input?: unknown; detached?: boolean }
   | { op: 'cancel'; operationId?: string }
+  | { op: 'cancelInput'; inputId: string }
+  | {
+      op: 'setDelivery'
+      inputId: string
+      delivery: WaitingInput['delivery']
+    }
   | { op: 'command'; name: string; input?: unknown }
   | { op: 'answer'; questionId: string; value: unknown }
   | { op: 'config'; key: string; value: unknown }
 ) & { inputId?: string }
 
+/**
+ * An input that waits to run. `session.inputs()` lists them. Change one with
+ * the `cancelInput` and `setDelivery` inputs.
+ */
+export interface WaitingInput {
+  inputId: string
+  /**
+   * - `steer`: it joins the running turn at the next model call. When the
+   *   turn makes no more model calls, it runs as the next turn.
+   * - `queue`: it runs as its own turn, after the turns before it.
+   */
+  delivery: 'steer' | 'queue'
+  /** The user message of the input. */
+  message: UserInput
+}
+
+/**
+ * Where a fork cuts the transcript, by message id. `before` keeps the
+ * messages before that message. `through` keeps that message too.
+ */
+export type ForkPoint = { before: string } | { through: string }
+
 /** How an input ended. `session.settled(inputId)` resolves to it. */
 export interface InputSettlement {
   inputId: string
@@ -251,6 +281,11 @@ export const HARNESS_EVENTS = {
   inputRejected: 'harness.input.rejected',
   /** An input ended. The value is an `InputSettlement`. */
   inputSettled: 'harness.input.settled',
+  /**
+   * A `setDelivery` input moved a waiting input. The value has `inputId` and
+   * `delivery`.
+   */
+  inputDelivery: 'harness.input.delivery',
   /** A media file was stored. The value is a `MediaRecord`. */
   media: 'harness.media',
   /**
diff --git a/packages/ai-harness/src/view/index.ts b/packages/ai-harness/src/view/index.ts
index b9fb6ffad5..ba011cbc9e 100644
--- a/packages/ai-harness/src/view/index.ts
+++ b/packages/ai-harness/src/view/index.ts
@@ -48,7 +48,7 @@ export {
   mediaOfMessage,
   mediaPart,
 } from '../media-ref'
-export type { MediaKind, MediaRecord } from '../types'
+export type { MediaKind, MediaRecord, WaitingInput } from '../types'
 export type {
   AgentPart,
   Approval,
diff --git a/packages/ai-harness/src/view/reduce.ts b/packages/ai-harness/src/view/reduce.ts
index b113cb03c2..6b3c674ee8 100644
--- a/packages/ai-harness/src/view/reduce.ts
+++ b/packages/ai-harness/src/view/reduce.ts
@@ -58,6 +58,7 @@ export function emptyState(): SessionViewState {
     signIns: [],
     agents: [],
     queuedTurns: 0,
+    waitingInputs: [],
     commands: [],
     config: [],
     tools: [],
@@ -568,10 +569,10 @@ function signInOf(interrupt: Interrupt): SignIn | undefined {
 }
 
 /**
- * Take status, approvals, client tools, questions, and background agents
- * from a snapshot. Plugin state is taken only for the first snapshot. Later
- * changes come as `STATE_SNAPSHOT` events. Returns `state` when nothing
- * changes.
+ * 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,
@@ -634,6 +635,16 @@ export function applySnapshot(
           },
       ),
   )
+  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] : [])),
   )
@@ -643,6 +654,7 @@ export function applySnapshot(
     snapshot.threadId === state.threadId &&
     snapshot.status === state.status &&
     snapshot.queuedTurns === state.queuedTurns &&
+    waitingInputs === state.waitingInputs &&
     approvals === state.approvals &&
     clientTools === state.clientTools &&
     signIns === state.signIns &&
@@ -656,6 +668,7 @@ export function applySnapshot(
     threadId: snapshot.threadId,
     status: snapshot.status,
     queuedTurns: snapshot.queuedTurns,
+    waitingInputs,
     approvals,
     clientTools,
     signIns,
diff --git a/packages/ai-harness/src/view/types.ts b/packages/ai-harness/src/view/types.ts
index 46be2509a4..b66e9367ba 100644
--- a/packages/ai-harness/src/view/types.ts
+++ b/packages/ai-harness/src/view/types.ts
@@ -1,5 +1,5 @@
 import type { ConfigOption } from '../config'
-import type { MediaKind, Receipt } from '../types'
+import type { MediaKind, Receipt, WaitingInput } from '../types'
 
 export type ToolCallStatus = 'running' | 'done' | 'failed' | 'needs-approval'
 
@@ -137,6 +137,8 @@ export interface SessionViewState {
   /** Background agents that run now. */
   agents: Array<{ id: string; name: string }>
   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 }>
diff --git a/packages/ai-harness/tests/agent-middleware.test.ts b/packages/ai-harness/tests/agent-middleware.test.ts
index ef06a0e5f8..89c43a0b20 100644
--- a/packages/ai-harness/tests/agent-middleware.test.ts
+++ b/packages/ai-harness/tests/agent-middleware.test.ts
@@ -1,8 +1,8 @@
 import { describe, expect, it } from 'vitest'
-import { EventType, defineAgent } from '@tanstack/ai'
+import { EventType, defineAgent, toolDefinition } from '@tanstack/ai'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness, definePlugin } from '../src'
-import { usage } from '../src/first-party'
+import { permissions, usage } from '../src/first-party'
 import { mockAdapter, text, toolCall } from './helpers'
 import type { AnyChatMiddleware, StreamChunk } from '@tanstack/ai'
 import type { AnyHarness, PluginLifetime } from '../src'
@@ -206,4 +206,46 @@ describe('plugin agentMiddleware', () => {
     })
     await host.close()
   })
+
+  it('lets permissions() deny a write a subagent tries in plan mode', async () => {
+    const writes: Array<unknown> = []
+    const writeFile = toolDefinition({
+      name: 'write_file',
+      description: 'Write a file',
+    }).server(async (args) => {
+      writes.push(args)
+      return 'written'
+    })
+    const writerModel = mockAdapter([
+      () => toolCall('write_file', { path: 'x.txt' }),
+      () => text('writer done'),
+    ])
+    const writer = defineAgent({
+      name: 'writer',
+      description: 'Writes files',
+      run: (ctx) =>
+        ctx.chat({ adapter: writerModel.adapter, tools: [writeFile] }),
+    })
+    const { host, session } = await open(
+      defineHarness({
+        name: 'test/agent-middleware',
+        adapter: leadCalling('writer'),
+        subagents: { agents: [writer] },
+        plugins: () => [
+          permissions({
+            rules: [{ tool: 'write_file', decision: 'ask', kind: 'edit' }],
+          }),
+        ],
+      }),
+    )
+    await session.command('mode', 'plan')
+
+    await session.prompt('write it')
+
+    expect(writes).toEqual([])
+    expect(JSON.stringify(writerModel.calls[1].messages)).toContain(
+      'This tool is not allowed in plan mode.',
+    )
+    await host.close()
+  })
 })
diff --git a/packages/ai-harness/tests/coding-backend.test.ts b/packages/ai-harness/tests/coding-backend.test.ts
new file mode 100644
index 0000000000..d0c5e65a88
--- /dev/null
+++ b/packages/ai-harness/tests/coding-backend.test.ts
@@ -0,0 +1,112 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { basename, join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness, definePlugin } from '../src'
+import {
+  WorkspaceHooks,
+  hostBackend,
+  workspaceTools,
+} from '../src/first-party/coding'
+import { mockAdapter, text, toolCall } from './helpers'
+
+let dir = ''
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'harness-backend-'))
+})
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true })
+})
+
+const decoder = new TextDecoder()
+
+describe('hostBackend', () => {
+  it('writes into new folders, then reads, stats, and lists them', async () => {
+    const file = join(dir, 'a', 'b.txt')
+    await hostBackend.writeFile(file, 'hi')
+    expect(decoder.decode(await hostBackend.readFile(file))).toBe('hi')
+    expect(await hostBackend.stat(file)).toMatchObject({
+      type: 'file',
+      size: 2,
+    })
+    expect(await hostBackend.stat(join(dir, 'a'))).toMatchObject({
+      type: 'dir',
+    })
+    expect(await hostBackend.readdir(dir)).toEqual([{ name: 'a', type: 'dir' }])
+  })
+
+  it('stats a missing path as undefined', async () => {
+    expect(await hostBackend.stat(join(dir, 'missing'))).toBeUndefined()
+  })
+
+  it('runs a command with added env, and resolves with its exit code', async () => {
+    expect(
+      await hostBackend.exec(
+        `node -e "console.log(process.env.HARNESS_VALUE); process.exit(2)"`,
+        { cwd: dir, env: { HARNESS_VALUE: 'set' } },
+      ),
+    ).toEqual({ exitCode: 2, stdout: 'set\n', stderr: '' })
+  })
+
+  it('starts a background command, then gives its exit code and output', async () => {
+    const job = hostBackend.spawn(`node -e "console.log('done')"`, {
+      cwd: dir,
+    })
+    expect(await job.wait()).toEqual({ exitCode: 0 })
+    expect(job.output()).toBe('done\n')
+  })
+
+  it('kills a background command', async () => {
+    const job = hostBackend.spawn(
+      `node -e "setTimeout(function () {}, 60000)"`,
+    )
+    job.kill()
+    expect((await job.wait()).exitCode).not.toBe(0)
+  })
+})
+
+describe('workspace hooks', () => {
+  it('runs afterWrite after each write, and adds afterRead text to read_file', async () => {
+    const written: Array<string> = []
+    const hooks = definePlugin({
+      name: 'test/hooks',
+      setup: () => ({
+        contribute: [
+          WorkspaceHooks.item({
+            afterWrite: async (path) => {
+              written.push(decoder.decode(await hostBackend.readFile(path)))
+            },
+            afterRead: async (path) => `read ${basename(path)}`,
+          }),
+        ],
+      }),
+    })
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('write_file', { path: 'a.txt', content: 'one' }, 'c1'),
+      () =>
+        toolCall('edit_file', { path: 'a.txt', old: 'one', new: 'two' }, 'c2'),
+      () => toolCall('read_file', { path: 'a.txt' }, 'c3'),
+      () => text('done'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/hooks',
+        adapter,
+        // The hooks plugin comes after the tools: the tools read hooks
+        // when they run.
+        plugins: () => [workspaceTools({ root: dir }), hooks],
+      }),
+      { threadId: 't' },
+    )
+
+    await session.prompt('work')
+
+    expect(written).toEqual(['one', 'two'])
+    expect(JSON.stringify(calls[3].messages)).toContain(
+      '1\\ttwo\\n\\nread a.txt',
+    )
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/define.test.ts b/packages/ai-harness/tests/define.test.ts
index 7e46b4f603..47147c6cb1 100644
--- a/packages/ai-harness/tests/define.test.ts
+++ b/packages/ai-harness/tests/define.test.ts
@@ -1,8 +1,13 @@
 import { describe, expect, it } from 'vitest'
 import { z } from 'zod'
-import { defineAgent } from '@tanstack/ai'
-import { defineHarness, isHarnessDefinition } from '../src'
-import { mockAdapter } from './helpers'
+import { defineAgent, toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  createHarnessHost,
+  defineHarness,
+  isHarnessDefinition,
+} from '../src'
+import { mockAdapter, text, toolCall } from './helpers'
 
 const agent = (name: string) =>
   defineAgent({
@@ -62,3 +67,47 @@ describe('defineHarness', () => {
     ).toThrow('expose.agents names "missing"')
   })
 })
+
+describe('toolExecution', () => {
+  it("runs the tools of one model call one at a time with 'sequential'", async () => {
+    const log: Array<string> = []
+    const tool = (name: string) =>
+      toolDefinition({
+        name,
+        description: name,
+        inputSchema: z.object({}),
+      }).server(async () => {
+        log.push(`start:${name}`)
+        // Wait one macrotask. Parallel tools all start before it ends.
+        await new Promise((resolve) => setTimeout(resolve, 0))
+        log.push(`end:${name}`)
+        return {}
+      })
+    // One model call with two tool calls: drop the RUN_FINISHED of the
+    // first call and the RUN_STARTED of the second.
+    const bothTools = () => [
+      ...toolCall('first', {}, 'call-1').slice(0, -1),
+      ...toolCall('second', {}, 'call-2').slice(1),
+    ]
+    const { adapter } = mockAdapter([bothTools, () => text('done')])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/sequential',
+        adapter,
+        tools: [tool('first'), tool('second')],
+        toolExecution: 'sequential',
+      }),
+      { threadId: 't1' },
+    )
+
+    await expect(session.prompt('go')).resolves.toEqual({ text: 'done' })
+    expect(log).toEqual([
+      'start:first',
+      'end:first',
+      'start:second',
+      'end:second',
+    ])
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/durable-inputs.test.ts b/packages/ai-harness/tests/durable-inputs.test.ts
index fe845faf43..1972c652f1 100644
--- a/packages/ai-harness/tests/durable-inputs.test.ts
+++ b/packages/ai-harness/tests/durable-inputs.test.ts
@@ -4,6 +4,7 @@ import { z } from 'zod'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { InputRejectedError, createHarnessHost, defineHarness } from '../src'
 import {
+  after,
   gate,
   messageTexts,
   mockAdapter,
@@ -11,9 +12,9 @@ import {
   toolCall,
   untilAborted,
 } from './helpers'
-import type { ModelMessage } from '@tanstack/ai'
+import type { AnyTool, ModelMessage } from '@tanstack/ai'
 import type { LeaseStore, LogRecord } from '@tanstack/ai-persistence'
-import type { HarnessDurability } from '../src'
+import type { HarnessDurability, HarnessInput } from '../src'
 import type { Reply } from './helpers'
 
 const THREAD = 't1'
@@ -25,6 +26,29 @@ function durablePersistence() {
 
 type Durable = ReturnType<typeof durablePersistence>
 
+/** The log record of a prompt. With no other record, it never ran. */
+const pendingInput = (inputId: string, message: string): LogRecord => ({
+  type: 'harness.input',
+  inputId,
+  input: { op: 'prompt', message, busy: 'queue' },
+  at: 1,
+})
+
+/** The log record of a `cancelInput` or `setDelivery` input `ctl-1`. */
+const controlInput = (input: HarnessInput): LogRecord => ({
+  type: 'harness.input',
+  inputId: 'ctl-1',
+  input,
+  at: 2,
+})
+
+const controlApplied: LogRecord = {
+  type: 'harness.input.applied',
+  inputId: 'ctl-1',
+  operationId: 'session',
+  attempt: 1,
+}
+
 /**
  * The log and run of a host that stopped during attempt `attempt` of input
  * `in-1`: the input, its applied record, and the user message that the turn
@@ -41,12 +65,7 @@ async function seedStoppedTurn(
 ) {
   const user: ModelMessage = { id: 'u1', role: 'user', content: 'go' }
   const records: Array<LogRecord> = [
-    {
-      type: 'harness.input',
-      inputId: 'in-1',
-      input: { op: 'prompt', message: 'go', busy: 'queue' },
-      at: 1,
-    },
+    pendingInput('in-1', 'go'),
     {
       type: 'harness.input.applied',
       inputId: 'in-1',
@@ -84,6 +103,7 @@ async function openDurable(options: {
   persistence: Durable
   replies: Array<Reply>
   durability?: HarnessDurability
+  tools?: Array<AnyTool>
 }) {
   const { adapter, calls } = mockAdapter(options.replies)
   const host = createHarnessHost({ persistence: options.persistence })
@@ -92,14 +112,23 @@ async function openDurable(options: {
       name: 'test/durable-inputs',
       adapter,
       ...(options.durability ? { durability: options.durability } : {}),
+      ...(options.tools ? { tools: options.tools } : {}),
     }),
     { threadId: THREAD },
   )
   return { host, session, calls }
 }
 
+const logRecords = async (persistence: Durable) =>
+  (await persistence.stores.log.read(THREAD)).map((entry) => entry.record)
+
 const recordTypes = async (persistence: Durable) =>
-  (await persistence.stores.log.read(THREAD)).map((entry) => entry.record.type)
+  (await logRecords(persistence)).map((record) => record.type)
+
+const recordTypesOf = async (persistence: Durable, inputId: string) =>
+  (await logRecords(persistence))
+    .filter((record) => record.inputId === inputId)
+    .map((record) => record.type)
 
 describe('recovery of a durable input', () => {
   it('settles failed when the attempts are used up, with no model call', async () => {
@@ -141,9 +170,9 @@ describe('recovery of a durable input', () => {
 
     expect(settlement.outcome).toBe('completed')
     expect(calls).toHaveLength(1)
-    const applied = (await persistence.stores.log.read(THREAD))
-      .map((entry) => entry.record)
-      .filter((record) => record.type === 'harness.input.applied')
+    const applied = (await logRecords(persistence)).filter(
+      (record) => record.type === 'harness.input.applied',
+    )
     expect(applied.map((record) => record.attempt)).toEqual([1, 2])
     await host.close()
   })
@@ -186,12 +215,7 @@ describe('recovery of a durable input', () => {
   it('settles aborted a pending input that was cancelled before it ran', async () => {
     const persistence = durablePersistence()
     await persistence.stores.log.append(THREAD, 1, [
-      {
-        type: 'harness.input',
-        inputId: 'in-1',
-        input: { op: 'prompt', message: 'go', busy: 'queue' },
-        at: 1,
-      },
+      pendingInput('in-1', 'go'),
       { type: 'harness.input.abort', inputId: 'in-1' },
     ])
 
@@ -262,13 +286,11 @@ describe('recovery of a durable input', () => {
     expect((await persistence.stores.runs.get('op-agent'))?.status).toBe(
       'failed',
     )
-    const settled = (await persistence.stores.log.read(THREAD))
-      .map((entry) => entry.record)
-      .find(
-        (record) =>
-          record.type === 'harness.input.settled' &&
-          record.inputId === 'in-agent',
-      )
+    const settled = (await logRecords(persistence)).find(
+      (record) =>
+        record.type === 'harness.input.settled' &&
+        record.inputId === 'in-agent',
+    )
     expect(settled).toMatchObject({
       operationId: 'op-agent',
       outcome: 'failed',
@@ -339,12 +361,7 @@ describe('recovery of a durable input', () => {
   it('asks the recover hook about an input that never ran', async () => {
     const persistence = durablePersistence()
     await persistence.stores.log.append(THREAD, 1, [
-      {
-        type: 'harness.input',
-        inputId: 'in-new',
-        input: { op: 'prompt', message: 'later', busy: 'queue' },
-        at: 1,
-      },
+      pendingInput('in-new', 'later'),
     ])
 
     const { host, session, calls } = await openDurable({
@@ -403,6 +420,216 @@ describe('durable input limits while a turn runs', () => {
   })
 })
 
+/**
+ * A durable session whose first turn calls `hold`, which waits for
+ * `release`. The turn then makes one more model call, where a steer joins.
+ */
+async function openHolding(replies: Array<Reply>) {
+  const persistence = durablePersistence()
+  const release = gate()
+  const hold = toolDefinition({ name: 'hold', description: 'Hold' }).server(
+    async () => {
+      await release.opened
+      return 'held'
+    },
+  )
+  const opened = await openDurable({
+    persistence,
+    replies: [() => toolCall('hold', {}), ...replies],
+    tools: [hold],
+  })
+  return { ...opened, persistence, release }
+}
+
+describe('waiting inputs', () => {
+  it('lists the waiting inputs, and cancels a queued one so it never runs', async () => {
+    const persistence = durablePersistence()
+    const release = gate()
+    const { host, session, calls } = await openDurable({
+      persistence,
+      replies: [after(release.opened, 'first done'), () => text('steer done')],
+    })
+    const first = session.prompt('first', { inputId: 'first' })
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    await session.followUp('second', { inputId: 'second' })
+    await session.steer('third', { inputId: 'third' })
+
+    expect(session.inputs()).toEqual([
+      { inputId: 'third', delivery: 'steer', message: 'third' },
+      { inputId: 'second', delivery: 'queue', message: 'second' },
+    ])
+    expect(await session.cancelInput('second')).toMatchObject({
+      status: 'accepted',
+    })
+    expect(await session.settled('second')).toMatchObject({
+      outcome: 'aborted',
+    })
+    expect(session.inputs()).toEqual([
+      { inputId: 'third', delivery: 'steer', message: 'third' },
+    ])
+    expect(await logRecords(persistence)).toContainEqual({
+      type: 'harness.input.abort',
+      inputId: 'second',
+    })
+
+    release.open()
+    await first
+    expect(await session.settled('third')).toMatchObject({
+      outcome: 'completed',
+    })
+    expect(calls).toHaveLength(2)
+    expect(calls.flatMap(messageTexts)).not.toContain('second')
+    await host.close()
+  })
+
+  it('refuses to cancel an input that started', async () => {
+    const release = gate()
+    const { host, session, calls } = await openDurable({
+      persistence: durablePersistence(),
+      replies: [after(release.opened, 'done')],
+    })
+    const turn = session.prompt('first', { inputId: 'first' })
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+
+    expect(await session.cancelInput('first')).toMatchObject({
+      status: 'rejected',
+      reason: 'not_waiting',
+    })
+    release.open()
+    expect(await turn).toEqual({ text: 'done' })
+    await host.close()
+  })
+
+  it('joins a queued input to the running turn with setDelivery steer', async () => {
+    const { host, session, calls, persistence, release } = await openHolding([
+      () => text('done'),
+    ])
+    const first = session.prompt('first', { inputId: 'first' })
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    await session.followUp('later', { inputId: 'later' })
+
+    expect(await session.setDelivery('later', 'steer')).toMatchObject({
+      status: 'accepted',
+    })
+    expect(session.inputs()).toEqual([
+      { inputId: 'later', delivery: 'steer', message: 'later' },
+    ])
+    expect(await logRecords(persistence)).toContainEqual({
+      type: 'harness.input.delivery',
+      inputId: 'later',
+      delivery: 'steer',
+    })
+
+    release.open()
+    await first
+    expect(await session.settled('later')).toMatchObject({
+      outcome: 'completed',
+      operationId: first.id,
+    })
+    expect(calls).toHaveLength(2)
+    expect(messageTexts(calls[1])).toContain('later')
+    await host.close()
+  })
+
+  it('runs a steer as its own turn with setDelivery queue', async () => {
+    const { host, session, calls, release } = await openHolding([
+      () => text('done'),
+      () => text('own turn'),
+    ])
+    const first = session.prompt('first', { inputId: 'first' })
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    await session.steer('now', { inputId: 'now' })
+
+    expect(await session.setDelivery('now', 'queue')).toMatchObject({
+      status: 'accepted',
+    })
+    expect(session.inputs()).toEqual([
+      { inputId: 'now', delivery: 'queue', message: 'now' },
+    ])
+
+    release.open()
+    await first
+    await session.settled('now')
+    expect(calls).toHaveLength(3)
+    expect(messageTexts(calls[1])).not.toContain('now')
+    expect(messageTexts(calls[2])).toContain('now')
+    await host.close()
+  })
+
+  const nothingLanded: Array<LogRecord> = []
+  const abortLanded: Array<LogRecord> = [
+    { type: 'harness.input.abort', inputId: 'in-1' },
+    controlApplied,
+  ]
+  const deliveryLanded: Array<LogRecord> = [
+    { type: 'harness.input.delivery', inputId: 'in-2', delivery: 'steer' },
+    controlApplied,
+  ]
+
+  it.each([
+    ['before its change landed', nothingLanded],
+    ['after its change landed', abortLanded],
+  ])(
+    'recovery does not run an input after a cancelInput, crash %s',
+    async (_when, landed) => {
+      const persistence = durablePersistence()
+      await persistence.stores.log.append(THREAD, 1, [
+        pendingInput('in-1', 'go'),
+        controlInput({ op: 'cancelInput', inputId: 'in-1' }),
+        ...landed,
+      ])
+
+      const { host, session, calls } = await openDurable({
+        persistence,
+        replies: [() => text('never')],
+      })
+
+      expect(await session.settled('in-1')).toMatchObject({
+        outcome: 'aborted',
+      })
+      expect(calls).toHaveLength(0)
+      // Applied, not rejected with `expired_on_restart`.
+      expect(await recordTypesOf(persistence, 'ctl-1')).toEqual([
+        'harness.input',
+        'harness.input.applied',
+      ])
+      await host.close()
+    },
+  )
+
+  it.each([
+    ['before its change landed', nothingLanded],
+    ['after its change landed', deliveryLanded],
+  ])(
+    'recovery joins an input that a setDelivery sent to steer, crash %s',
+    async (_when, landed) => {
+      const persistence = durablePersistence()
+      await persistence.stores.log.append(THREAD, 1, [
+        pendingInput('in-1', 'first'),
+        pendingInput('in-2', 'second'),
+        controlInput({ op: 'setDelivery', inputId: 'in-2', delivery: 'steer' }),
+        ...landed,
+      ])
+
+      const { host, session, calls } = await openDurable({
+        persistence,
+        replies: [() => text('both'), () => text('never')],
+      })
+
+      expect(await session.settled('in-2')).toMatchObject({
+        outcome: 'completed',
+      })
+      expect(calls).toHaveLength(1)
+      expect(messageTexts(calls[0])).toEqual(['first', 'second'])
+      expect(await recordTypesOf(persistence, 'ctl-1')).toEqual([
+        'harness.input',
+        'harness.input.applied',
+      ])
+      await host.close()
+    },
+  )
+})
+
 describe('input ids', () => {
   it('returns the first operation for a duplicate, and runs once', async () => {
     const persistence = durablePersistence()
diff --git a/packages/ai-harness/tests/edge-safety.test.ts b/packages/ai-harness/tests/edge-safety.test.ts
index f4c6b14f89..44f9f17783 100644
--- a/packages/ai-harness/tests/edge-safety.test.ts
+++ b/packages/ai-harness/tests/edge-safety.test.ts
@@ -15,14 +15,22 @@ import { describe, expect, it } from 'vitest'
 const here = dirname(fileURLToPath(import.meta.url))
 const srcDir = resolve(here, '..', 'src')
 
-/** Node-only entry points, relative to `src`. */
+/**
+ * Node-only entry points, relative to `src`. A path that ends with `/` allows
+ * the whole folder: `first-party/coding/` is the Node-only `plugins/coding` entry.
+ */
 const ALLOWED = [
   'build.ts',
   'worker.ts',
   'first-party/files.ts',
-  'first-party/workspace.ts',
+  'first-party/coding/',
 ]
 
+const isAllowed = (file: string) =>
+  ALLOWED.some((entry) =>
+    entry.endsWith('/') ? file.startsWith(entry) : file === entry,
+  )
+
 const NODE_BUILTINS = [
   'fs',
   'path',
@@ -80,7 +88,7 @@ describe('edge safety of the harness core', () => {
     expect(files.length).toBeGreaterThan(0)
 
     const offenders = files
-      .filter((file) => !ALLOWED.includes(toPosix(file)))
+      .filter((file) => !isAllowed(toPosix(file)))
       .filter((file) => importsNode(readFileSync(file, 'utf8')))
       .map(toPosix)
 
diff --git a/packages/ai-harness/tests/first-party.test.ts b/packages/ai-harness/tests/first-party.test.ts
index 5b48556d6b..ed3044211d 100644
--- a/packages/ai-harness/tests/first-party.test.ts
+++ b/packages/ai-harness/tests/first-party.test.ts
@@ -14,8 +14,8 @@ import {
   projectInstructions,
   todos,
   usage,
-  workspaceTools,
 } from '../src/first-party'
+import { workspaceTools } from '../src/first-party/coding'
 import { messageTexts, mockAdapter, text, toolCall } from './helpers'
 import type { HarnessPlugin } from '../src'
 import type { AnyTextAdapter } from '@tanstack/ai'
@@ -81,7 +81,7 @@ describe('workspace tools with permissions', () => {
     )
     const [question] = session.snapshot().pendingQuestions
     expect(question?.message).toContain('write_file')
-    await session.answer(question!.questionId, 'y')
+    await session.answer(question!.questionId, { answer: 'once' })
     await turn
 
     expect(await readFile(join(root, 'out.txt'), 'utf8')).toBe('written')
diff --git a/packages/ai-harness/tests/permissions.test.ts b/packages/ai-harness/tests/permissions.test.ts
new file mode 100644
index 0000000000..c42116fb69
--- /dev/null
+++ b/packages/ai-harness/tests/permissions.test.ts
@@ -0,0 +1,435 @@
+import { describe, expect, it, vi } from 'vitest'
+import { toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness, definePlugin } from '../src'
+import {
+  PermissionResources,
+  PermissionRules,
+  decidePermission,
+  permissions,
+} from '../src/first-party/permissions'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { HarnessPersistence, HarnessPlugin, HarnessSession } from '../src'
+import type {
+  PermissionMode,
+  PermissionRule,
+} from '../src/first-party/permissions'
+import type { Reply } from './helpers'
+
+const ROOT = '/work/repo'
+const WINDOWS_ROOT = 'C:\\work\\repo'
+const readAllowed: Array<PermissionRule> = [
+  { tool: 'read_file', decision: 'allow', kind: 'read' },
+]
+
+function read(
+  path: string,
+  options: { root?: string; rules?: Array<PermissionRule> } = {},
+) {
+  return decidePermission(options.rules ?? readAllowed, 'read_file', 'default', {
+    resources: { paths: [path] },
+    root: options.root ?? ROOT,
+  })
+}
+
+function run(commands: Array<string>, rules: Array<PermissionRule>) {
+  return decidePermission(rules, 'bash', 'default', {
+    resources: { commands },
+  })
+}
+
+describe('decidePermission with resources', () => {
+  it('lets the last matching rule win, and needs every resource allowed', () => {
+    const rules: Array<PermissionRule> = [
+      ...readAllowed,
+      { tool: 'read_file', resource: 'secrets/**', decision: 'deny' },
+      { tool: 'read_file', resource: 'secrets/public/**', decision: 'allow' },
+    ]
+    const decide = (paths: Array<string>) =>
+      decidePermission(rules, 'read_file', 'default', {
+        resources: { paths },
+        root: ROOT,
+      })
+
+    expect(decide(['src/a.ts'])).toBe('allow')
+    expect(decide(['secrets/key'])).toBe('deny')
+    expect(decide(['secrets/public/logo.png'])).toBe('allow')
+    expect(decide(['src/a.ts', 'secrets/key'])).toBe('deny')
+  })
+
+  it('fails closed when the resources of a call are not known', () => {
+    const rules: Array<PermissionRule> = [
+      ...readAllowed,
+      { tool: 'read_file', resource: 'secrets/**', decision: 'ask' },
+    ]
+
+    expect(decidePermission(rules, 'read_file', 'default')).toBe('ask')
+  })
+
+  it('matches command rules against each part, and * spans slashes', () => {
+    const rules: Array<PermissionRule> = [
+      { tool: 'bash', decision: 'ask', kind: 'execute' },
+      { tool: 'bash', resource: 'ls*', decision: 'allow' },
+      { tool: 'bash', resource: 'git *', decision: 'allow' },
+    ]
+
+    expect(run(['ls -la'], rules)).toBe('allow')
+    expect(run(['git add src/a.ts'], rules)).toBe('allow')
+    expect(run(['ls', 'rm x'], rules)).toBe('ask')
+  })
+
+  it.each([
+    ['a command that was not split', 'ls && rm x'],
+    ['command substitution', 'echo $(rm x)'],
+    ['a backtick', 'echo `rm x`'],
+    ['process substitution', 'diff <(rm x) y'],
+    ['a heredoc', 'cat <<EOF\nrm x\nEOF'],
+  ])('asks for %s even when * is allowed', (_name, part) => {
+    expect(
+      run([part], [{ tool: 'bash', resource: '*', decision: 'allow' }]),
+    ).toBe('ask')
+  })
+
+  it('still denies a part with shell syntax when a deny matches', () => {
+    const rules: Array<PermissionRule> = [
+      { tool: 'bash', resource: '*', decision: 'allow' },
+      { tool: 'bash', resource: 'echo *', decision: 'deny' },
+    ]
+
+    expect(run(['echo $(rm x)'], rules)).toBe('deny')
+  })
+
+  it.each([
+    ['..', '../secret.txt'],
+    ['.. in the middle', 'src/../../secret.txt'],
+    ['an absolute path', '/etc/passwd'],
+    ['another letter case on a case-sensitive system', '/work/Repo/a.ts'],
+    ['a folder that only starts like the root', '/work/repo-evil/a.ts'],
+  ])('asks for a path that leaves the workspace: %s', (_name, path) => {
+    expect(read(path)).toBe('ask')
+  })
+
+  it.each([
+    ['another drive', 'D:\\other\\x.txt'],
+    ['a sibling folder in another letter case', 'C:/Work/Other/x.txt'],
+    ['a folder that only starts like the root', 'C:\\WORK\\REPO-evil\\x.txt'],
+    ['a path relative to the current folder of a drive', 'C:secret.txt'],
+    ['a stream of a file', 'notes.txt:hidden'],
+    ['a name that ends in a dot', 'notes.txt.'],
+  ])('asks for a Windows path that leaves the workspace: %s', (_name, path) => {
+    expect(read(path, { root: WINDOWS_ROOT })).toBe('ask')
+  })
+
+  it('compares Windows paths without letter case, for allows and denies', () => {
+    const rules: Array<PermissionRule> = [
+      ...readAllowed,
+      { tool: 'read_file', resource: 'secrets/**', decision: 'deny' },
+    ]
+
+    expect(read('c:\\WORK\\Repo\\src\\a.ts', { root: WINDOWS_ROOT })).toBe(
+      'allow',
+    )
+    expect(read('SECRETS\\key', { root: WINDOWS_ROOT, rules })).toBe('deny')
+  })
+
+  it('lets a rule with a resource allow a path outside the workspace', () => {
+    const rules: Array<PermissionRule> = [
+      ...readAllowed,
+      { tool: 'read_file', resource: '/shared/**', decision: 'allow' },
+    ]
+
+    expect(read('/shared/notes.md', { rules })).toBe('allow')
+  })
+
+  it.each(['.env', 'config/prod.env', '.env.local', 'Prod.ENV'])(
+    'asks before reading %s',
+    (path) => {
+      expect(read(path)).toBe('ask')
+    },
+  )
+
+  it('reads other files, and a .env file a rule names', () => {
+    const rules: Array<PermissionRule> = [
+      ...readAllowed,
+      { tool: 'read_file', resource: '.env.example', decision: 'allow' },
+    ]
+
+    expect(read('environment.ts')).toBe('allow')
+    expect(read('.env.example', { rules })).toBe('allow')
+  })
+
+  it('keeps the edit kind in plan mode when a later rule allows the tool', () => {
+    const rules: Array<PermissionRule> = [
+      { tool: 'write_file', decision: 'ask', kind: 'edit' },
+      { tool: 'write_file', decision: 'allow' },
+    ]
+
+    expect(decidePermission(rules, 'write_file', 'plan')).toBe('deny')
+  })
+
+  it('in acceptEdits mode, still asks for an edit outside the workspace', () => {
+    const rules: Array<PermissionRule> = [
+      { tool: 'write_file', decision: 'ask', kind: 'edit' },
+    ]
+    const write = (path: string, mode: PermissionMode) =>
+      decidePermission(rules, 'write_file', mode, {
+        resources: { paths: [path] },
+        root: ROOT,
+      })
+
+    expect(write('src/a.ts', 'acceptEdits')).toBe('allow')
+    expect(write('../a.ts', 'acceptEdits')).toBe('ask')
+  })
+})
+
+/** The string `key` of a call input. Throws when it is missing. */
+function field(input: unknown, key: string) {
+  const value =
+    typeof input === 'object' && input !== null
+      ? Reflect.get(input, key)
+      : undefined
+  if (typeof value !== 'string') throw new Error(`No ${key}.`)
+  return value
+}
+
+/**
+ * `read_file` and `bash` stand-ins that say what each call touches. `ran`
+ * lists the tools that ran. The `bash` splitter splits on ` && ` only.
+ */
+function fakeTools() {
+  const ran: Array<string> = []
+  const tool = (name: string) =>
+    toolDefinition({ name, description: name }).server(async () => {
+      ran.push(name)
+      return `${name} done`
+    })
+  const plugin = definePlugin({
+    name: 'test/tools',
+    setup: () => ({
+      tools: [tool('read_file'), tool('bash'), tool('deploy')],
+      contribute: [
+        PermissionRules.item({
+          tool: 'read_file',
+          decision: 'allow',
+          kind: 'read',
+        }),
+        PermissionRules.item({ tool: 'bash', decision: 'ask', kind: 'execute' }),
+        PermissionResources.item({
+          read_file: { paths: (input) => [field(input, 'path')] },
+          bash: { commands: (input) => field(input, 'command').split(' && ') },
+        }),
+      ],
+    }),
+  })
+  return { plugin, ran }
+}
+
+async function open(
+  persistence: HarnessPersistence,
+  plugins: Array<HarnessPlugin>,
+  replies: Array<Reply>,
+  threadId = 't',
+) {
+  const { adapter, calls } = mockAdapter([...replies, () => text('done')])
+  const host = createHarnessHost({ persistence })
+  const session = await host.open(
+    defineHarness({ name: 'test/permissions', adapter, plugins: () => plugins }),
+    { threadId },
+  )
+  return { host, session, calls }
+}
+
+/** Wait for the one open question, then answer it. Returns its message. */
+async function answer(session: HarnessSession, value: unknown) {
+  await vi.waitFor(() =>
+    expect(session.snapshot().pendingQuestions).toHaveLength(1),
+  )
+  const [question] = session.snapshot().pendingQuestions
+  if (!question) throw new Error('No question.')
+  await session.answer(question.questionId, value)
+  return question.message
+}
+
+describe('permissions()', () => {
+  it('saves an always answer for the project, for the next call and a new session', async () => {
+    const persistence = memoryPersistence()
+    const tools = fakeTools()
+    const plugins = [permissions({ root: ROOT }), tools.plugin]
+    const first = await open(persistence, plugins, [
+      () => toolCall('read_file', { path: '.env' }, 'c1'),
+      () => toolCall('read_file', { path: '.env' }, 'c2'),
+    ])
+
+    const turn = first.session.prompt('read it twice')
+    expect(await answer(first.session, { answer: 'always' })).toContain('.env')
+    await turn
+
+    expect(tools.ran).toEqual(['read_file', 'read_file'])
+    expect(
+      await persistence.stores.metadata.get(
+        'tanstack/permissions',
+        'permissions:saved:/work/repo',
+      ),
+    ).toEqual([{ tool: 'read_file', resource: '.env', decision: 'allow' }])
+    await first.host.close()
+
+    const second = await open(
+      persistence,
+      [permissions({ root: ROOT }), tools.plugin],
+      [
+        () => toolCall('read_file', { path: '.env' }, 'c3'),
+        () => toolCall('read_file', { path: 'other.env' }, 'c4'),
+      ],
+      't2',
+    )
+    const next = second.session.prompt('read again')
+    // `.env` runs at once. `other.env` has no saved answer, so it asks.
+    expect(await answer(second.session, { answer: 'once' })).toContain(
+      'other.env',
+    )
+    await next
+
+    expect(tools.ran).toHaveLength(4)
+    await second.host.close()
+  })
+
+  it('keeps an always answer for the session when there is no metadata store', async () => {
+    const { stores } = memoryPersistence()
+    const tools = fakeTools()
+    const { host, session } = await open(
+      { stores: { messages: stores.messages, runs: stores.runs } },
+      [permissions({ root: ROOT }), tools.plugin],
+      [
+        () => toolCall('read_file', { path: '../shared.txt' }, 'c1'),
+        () => toolCall('read_file', { path: '../shared.txt' }, 'c2'),
+      ],
+    )
+
+    const turn = session.prompt('read it twice')
+    await answer(session, { answer: 'always' })
+    await turn
+
+    expect(tools.ran).toEqual(['read_file', 'read_file'])
+    expect(session.snapshot().pendingQuestions).toHaveLength(0)
+    await host.close()
+  })
+
+  it('gives the model a tool error with the message of a reject', async () => {
+    const tools = fakeTools()
+    const { host, session, calls } = await open(
+      memoryPersistence(),
+      [permissions({ root: ROOT }), tools.plugin],
+      [() => toolCall('read_file', { path: '../secret.txt' }, 'c1')],
+    )
+
+    const turn = session.prompt('read outside')
+    await answer(session, {
+      answer: 'reject',
+      message: 'Stay inside the repo.',
+    })
+    await turn
+
+    expect(tools.ran).toEqual([])
+    expect(JSON.stringify(calls[1].messages)).toContain(
+      '{\\"error\\":\\"Stay inside the repo.\\"}',
+    )
+    await host.close()
+  })
+
+  it('asks for ls && rm x when only ls* is allowed', async () => {
+    const tools = fakeTools()
+    const { host, session, calls } = await open(
+      memoryPersistence(),
+      [
+        permissions({
+          rules: [{ tool: 'bash', resource: 'ls*', decision: 'allow' }],
+        }),
+        tools.plugin,
+      ],
+      [
+        () => toolCall('bash', { command: 'ls -la' }, 'c1'),
+        () => toolCall('bash', { command: 'ls && rm x' }, 'c2'),
+      ],
+    )
+
+    const turn = session.prompt('list, then clean')
+    expect(await answer(session, { answer: 'reject' })).toContain('rm x')
+    await turn
+
+    expect(tools.ran).toEqual(['bash'])
+    expect(JSON.stringify(calls[2].messages)).toContain(
+      'The user denied this tool call.',
+    )
+    await host.close()
+  })
+
+  it('hides a tool that its last rule denies, and keeps one a later rule allows in part', async () => {
+    const tools = fakeTools()
+    const { host, session, calls } = await open(
+      memoryPersistence(),
+      [
+        permissions({
+          rules: [
+            { tool: 'deploy', decision: 'deny' },
+            { tool: 'bash', decision: 'deny' },
+            { tool: 'bash', resource: 'ls*', decision: 'allow' },
+          ],
+        }),
+        tools.plugin,
+      ],
+      [],
+    )
+
+    await session.prompt('hi')
+
+    const names = calls[0].tools.map((tool: { name: string }) => tool.name)
+    expect(names.sort()).toEqual(['bash', 'read_file'])
+    await host.close()
+  })
+
+  it('refuses a call whose resources cannot be read', async () => {
+    const tools = fakeTools()
+    const { host, session, calls } = await open(
+      memoryPersistence(),
+      [permissions({ root: ROOT }), tools.plugin],
+      [() => toolCall('read_file', {}, 'c1')],
+    )
+
+    await session.prompt('read nothing')
+
+    expect(tools.ran).toEqual([])
+    expect(session.snapshot().pendingQuestions).toHaveLength(0)
+    expect(JSON.stringify(calls[1].messages)).toContain(
+      'Cannot check the permissions of this call: No path.',
+    )
+    await host.close()
+  })
+
+  it('never lets a saved answer beat a deny', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.metadata.set(
+      'tanstack/permissions',
+      'permissions:saved:/work/repo',
+      [{ tool: 'read_file', resource: 'secret.txt', decision: 'allow' }],
+    )
+    const tools = fakeTools()
+    const { host, session } = await open(
+      persistence,
+      [
+        permissions({
+          root: ROOT,
+          rules: [
+            { tool: 'read_file', resource: 'secret.txt', decision: 'deny' },
+          ],
+        }),
+        tools.plugin,
+      ],
+      [() => toolCall('read_file', { path: 'secret.txt' }, 'c1')],
+    )
+
+    await session.prompt('read the secret')
+
+    expect(tools.ran).toEqual([])
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/plugin-apis.test.ts b/packages/ai-harness/tests/plugin-apis.test.ts
new file mode 100644
index 0000000000..15df564c67
--- /dev/null
+++ b/packages/ai-harness/tests/plugin-apis.test.ts
@@ -0,0 +1,88 @@
+import { describe, expect, it, vi } from 'vitest'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness, definePlugin } from '../src'
+import { mockAdapter, text } from './helpers'
+import type { AnyTextAdapter } from '@tanstack/ai'
+import type { PluginSessionApi } from '../src'
+
+/** Open a session with a plugin that hands out its session API. */
+async function openWithApi(adapter: AnyTextAdapter) {
+  const apis: Array<PluginSessionApi> = []
+  const probe = definePlugin({
+    name: 'test/probe',
+    setup: (ctx) => {
+      apis.push(ctx.session)
+    },
+  })
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const session = await host.open(
+    defineHarness({ name: 'test/plugin-apis', adapter, plugins: () => [probe] }),
+    { threadId: 't' },
+  )
+  const api = apis[0]
+  if (!api) throw new Error('The probe plugin was not set up.')
+  return { host, session, api }
+}
+
+describe('ctx.session.note', () => {
+  it('adds an assistant note to the transcript and starts no turn', async () => {
+    const { adapter, calls } = mockAdapter([() => text('Nice.')])
+    const { host, session, api } = await openWithApi(adapter)
+
+    await api.note('Build finished.')
+    expect(await api.transcript()).toMatchObject([
+      { role: 'assistant', content: 'Build finished.' },
+    ])
+
+    // The next model call is the user's prompt, after the note.
+    await session.prompt('Any news?')
+    expect(calls).toHaveLength(1)
+    expect(calls[0].messages).toMatchObject([
+      { role: 'assistant', content: 'Build finished.' },
+      { role: 'user', content: 'Any news?' },
+    ])
+    await host.close()
+  })
+
+  it('starts a turn after the note with wake', async () => {
+    const { adapter, calls } = mockAdapter([() => text('On it.')])
+    const { host, session, api } = await openWithApi(adapter)
+
+    await api.note('Build finished.', { wake: true })
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    expect(calls[0].messages).toMatchObject([
+      { role: 'assistant', content: 'Build finished.' },
+      { role: 'user', content: 'Build finished.' },
+    ])
+    await vi.waitFor(() => expect(session.snapshot().status).toBe('idle'))
+    await host.close()
+  })
+})
+
+describe('prepareTools', () => {
+  it('gets the model id of the adapter the turn runs with', async () => {
+    const { adapter } = mockAdapter([])
+    const picked = mockAdapter([() => text('ok')])
+    const models: Array<string> = []
+    const plugin = definePlugin({
+      name: 'test/pick',
+      setup: () => ({
+        adapter: () => ({ ...picked.adapter, model: 'picked-model' }),
+        prepareTools: ({ tools, model }) => {
+          models.push(model)
+          return tools
+        },
+      }),
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({ name: 'test/model', adapter, plugins: () => [plugin] }),
+      { threadId: 't' },
+    )
+
+    await session.prompt('go')
+    expect(models).toEqual(['picked-model'])
+    expect(picked.calls).toHaveLength(1)
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/prepare-tools.test.ts b/packages/ai-harness/tests/prepare-tools.test.ts
index d12fe94c02..80d968e02e 100644
--- a/packages/ai-harness/tests/prepare-tools.test.ts
+++ b/packages/ai-harness/tests/prepare-tools.test.ts
@@ -20,7 +20,7 @@ describe('prepareTools', () => {
       name: 'test/bundle',
       setup: () => ({
         prompts: [{ id: 'test/bundle', text: () => described }],
-        prepareTools: (tools) => {
+        prepareTools: ({ tools }) => {
           described = `Bundled: ${tools.map((entry) => entry.name).join(', ')}`
           return [tool('bundled')]
         },
@@ -29,7 +29,7 @@ describe('prepareTools', () => {
     const extra = definePlugin({
       name: 'test/extra',
       setup: () => ({
-        prepareTools: async (tools) => [...tools, tool('extra')],
+        prepareTools: async ({ tools }) => [...tools, tool('extra')],
       }),
     })
     const broken = definePlugin({
diff --git a/packages/ai-harness/tests/protocol.test.ts b/packages/ai-harness/tests/protocol.test.ts
index 70d9cadf73..21058f802e 100644
--- a/packages/ai-harness/tests/protocol.test.ts
+++ b/packages/ai-harness/tests/protocol.test.ts
@@ -8,10 +8,12 @@ import {
   defineHarness,
   handleHarnessSocket,
   parseControlFrame,
+  parseHarnessInput,
 } from '../src'
-import { mockAdapter, text } from './helpers'
+import { after, gate, mockAdapter, text } from './helpers'
 import type { WebSocketLike } from '@tanstack/ai'
 import type { HostFrame } from '../src'
+import type { Reply } from './helpers'
 
 const pricer = defineAgent({
   name: 'pricer',
@@ -25,7 +27,9 @@ const secret = defineAgent({
   run: async () => 'hidden',
 })
 
-function setup(replies = [() => text('hello'), () => text('again')]) {
+function setup(
+  replies: Array<Reply> = [() => text('hello'), () => text('again')],
+) {
   const { adapter, calls } = mockAdapter(replies)
   const harness = defineHarness({
     name: 'test/protocol',
@@ -48,10 +52,35 @@ function setup(replies = [() => text('hello'), () => text('again')]) {
 
 const auth = { authorization: 'Bearer good' }
 
-async function readSse(response: Response, until: (data: any) => boolean) {
-  const reader = response.body!.getReader()
+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<any> = []
+  const frames: Array<HostFrame> = []
   let buffer = ''
   while (true) {
     const { value, done } = await reader.read()
@@ -65,7 +94,8 @@ async function readSse(response: Response, until: (data: any) => boolean) {
         .find((line) => line.startsWith('data: '))
         ?.slice(6)
       if (!data) continue
-      const parsed = JSON.parse(data)
+      // The handler writes each frame as JSON.
+      const parsed: HostFrame = JSON.parse(data)
       frames.push(parsed)
       if (until(parsed)) {
         await reader.cancel()
@@ -139,19 +169,11 @@ describe('HTTP handler', () => {
 
   it('takes control inputs, streams session events, and resumes from a cursor', async () => {
     const { handler, host } = setup()
-    const control = (input: unknown) =>
-      handler(
-        new Request('http://x/api/harness/control', {
-          method: 'POST',
-          headers: { ...auth, 'content-type': 'application/json' },
-          body: JSON.stringify({ threadId: 'user-1-t', input }),
-        }),
-      )
+    const control = controlOf(handler, 'user-1-t')
 
-    const receipt = await (
-      await control({ op: 'prompt', message: 'hi' })
-    ).json()
-    expect(receipt.status).toBe('accepted')
+    expect(await control({ op: 'prompt', message: 'hi' })).toMatchObject({
+      status: 'accepted',
+    })
 
     const first = await readSse(
       await handler(
@@ -159,39 +181,35 @@ describe('HTTP handler', () => {
           headers: auth,
         }),
       ),
-      (frame) => frame.event?.name === 'harness.operation.finished',
+      isTurnEnd,
     )
     expect(first.every((frame) => frame.type === 'harness.event')).toBe(true)
-    const cursor = first.at(-1).cursor
+    const last = first.at(-1)
+    const cursor = last?.type === 'harness.event' ? last.cursor : ''
 
-    await (await control({ op: 'prompt', message: 'more' })).json()
+    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 },
         }),
       ),
-      (frame) => frame.event?.name === 'harness.operation.finished',
-    )
-    expect(second.every((frame) => Number(frame.cursor) > Number(cursor))).toBe(
-      true,
+      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 = 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-retry', input }),
-          }),
-        )
-      ).json()
+    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' })
@@ -210,16 +228,7 @@ describe('HTTP handler', () => {
 
   it('runs exposed agents from a client and refuses the others', async () => {
     const { handler, host } = 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-a', input }),
-          }),
-        )
-      ).json()
+    const control = controlOf(handler, 'user-1-a')
 
     expect(await control({ op: 'agent', agent: 'secret' })).toMatchObject({
       status: 'rejected',
@@ -235,6 +244,51 @@ describe('HTTP handler', () => {
     })
     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()
+  })
+})
+
+describe('parseHarnessInput', () => {
+  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'.")
+  })
 })
 
 describe('WebSocket', () => {
diff --git a/packages/ai-harness/tests/sessions-index.test.ts b/packages/ai-harness/tests/sessions-index.test.ts
new file mode 100644
index 0000000000..f3bb72266b
--- /dev/null
+++ b/packages/ai-harness/tests/sessions-index.test.ts
@@ -0,0 +1,429 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { EventType } from '@tanstack/ai'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  createHarnessHandler,
+  createHarnessHost,
+  defineHarness,
+  definePlugin,
+} from '../src'
+import { createHarnessClient } from '../src/client'
+import { mockAdapter, text } from './helpers'
+import type { ModelMessage, StreamChunk, TokenUsage } from '@tanstack/ai'
+import type { SessionIndexPage } from '@tanstack/ai-persistence'
+import type { HarnessPersistence, PluginSessionApi } from '../src'
+import type { Reply } from './helpers'
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+/** One model call that answers `content` and reports `usage`. */
+function textWithUsage(content: string, usage: TokenUsage) {
+  return text(content).map(
+    (chunk): StreamChunk =>
+      chunk.type === EventType.RUN_FINISHED ? { ...chunk, usage } : chunk,
+  )
+}
+
+function idOf(message: ModelMessage | undefined) {
+  if (!message?.id) throw new Error('The message has no id.')
+  return message.id
+}
+
+/** Role and content of each message, to compare transcripts. */
+const turnsOf = (messages: ReadonlyArray<ModelMessage>) =>
+  messages.map((message) => [message.role, message.content])
+
+const threadIds = (page: SessionIndexPage) =>
+  page.entries.map((entry) => entry.threadId)
+
+function hostWith(replies: Array<Reply> | Reply = () => text('answer')) {
+  const persistence = memoryPersistence()
+  const host = createHarnessHost({ persistence })
+  const harness = defineHarness({
+    name: 'test/sessions',
+    adapter: mockAdapter(replies).adapter,
+  })
+  return { persistence, host, harness }
+}
+
+/** Open a session with a plugin that hands out its session API. */
+async function openWithApi(persistence: HarnessPersistence) {
+  const apis: Array<PluginSessionApi> = []
+  const probe = definePlugin({
+    name: 'test/probe',
+    setup: (ctx) => {
+      apis.push(ctx.session)
+    },
+  })
+  const host = createHarnessHost({ persistence })
+  const harness = defineHarness({
+    name: 'test/sessions-plugin',
+    adapter: mockAdapter(() => text('ok')).adapter,
+    plugins: () => [probe],
+  })
+  const session = await host.open(harness, {
+    threadId: 'p1',
+    principal: { id: 'u1' },
+  })
+  const api = apis[0]
+  if (!api) throw new Error('The probe plugin was not set up.')
+  return { host, session, api }
+}
+
+describe('host.sessions', () => {
+  it('writes the entry on open and adds the usage of each turn', async () => {
+    const { host, harness } = hostWith([
+      () =>
+        textWithUsage('one', {
+          promptTokens: 10,
+          completionTokens: 5,
+          totalTokens: 15,
+          promptTokensDetails: { cachedTokens: 4 },
+        }),
+      () =>
+        textWithUsage('two', {
+          promptTokens: 20,
+          completionTokens: 7,
+          totalTokens: 27,
+          promptTokensDetails: { cacheWriteTokens: 2 },
+        }),
+    ])
+    const session = await host.open(harness, {
+      threadId: 't1',
+      principal: { id: 'u1', name: 'Ada', tenantId: 'org-1' },
+    })
+
+    expect(await host.sessions.get('t1')).toEqual({
+      threadId: 't1',
+      harness: 'test/sessions',
+      createdAt: expect.any(Number),
+      updatedAt: expect.any(Number),
+      principal: { id: 'u1', tenantId: 'org-1' },
+    })
+
+    await session.prompt('first')
+    await session.prompt('second')
+
+    expect((await host.sessions.get('t1'))?.usage).toEqual({
+      turns: 2,
+      promptTokens: 30,
+      completionTokens: 12,
+      totalTokens: 42,
+      cachedTokens: 4,
+      cacheWriteTokens: 2,
+    })
+    await host.close()
+  })
+
+  it('keeps the first owner when another user opens the thread again', async () => {
+    const { host, harness } = hostWith()
+    await host.open(harness, { threadId: 't1', principal: { id: 'alice' } })
+    await host.close()
+
+    await host.open(harness, { threadId: 't1', principal: { id: 'bob' } })
+
+    expect((await host.sessions.get('t1'))?.principal).toEqual({ id: 'alice' })
+    await host.close()
+  })
+
+  it('lists newest first, and only top-level sessions by default', async () => {
+    vi.useFakeTimers({ toFake: ['Date'] })
+    const { persistence, host, harness } = hostWith()
+    vi.setSystemTime(1000)
+    await host.open(harness, { threadId: 'older' })
+    vi.setSystemTime(2000)
+    await host.open(harness, { threadId: 'newer' })
+    // A child session, as a subagent run writes it.
+    await persistence.stores.sessions.upsert({
+      threadId: 'subagent:run-1',
+      parentThreadId: 'older',
+      createdAt: 3000,
+      updatedAt: 3000,
+    })
+
+    expect(threadIds(await host.sessions.list())).toEqual(['newer', 'older'])
+    expect(
+      threadIds(await host.sessions.list({ parentThreadId: 'older' })),
+    ).toEqual(['subagent:run-1'])
+    await host.close()
+  })
+
+  it('renames a session, and renames nothing for an unknown thread', async () => {
+    const { host, harness } = hostWith()
+    await host.open(harness, { threadId: 't1' })
+
+    const renamed = await host.sessions.rename('t1', 'Fix the build')
+
+    expect(renamed?.title).toBe('Fix the build')
+    expect((await host.sessions.get('t1'))?.title).toBe('Fix the build')
+    expect(await host.sessions.rename('unknown', 'x')).toBeUndefined()
+    expect(await host.sessions.get('unknown')).toBeUndefined()
+    await host.close()
+  })
+
+  it('deletes the index entry only, and a later turn does not bring it back', async () => {
+    const { persistence, host, harness } = hostWith()
+    const session = await host.open(harness, { threadId: 't1' })
+    await session.prompt('hi')
+
+    await host.sessions.delete('t1')
+    await session.prompt('still here')
+
+    expect(await host.sessions.get('t1')).toBeUndefined()
+    expect(
+      turnsOf(await persistence.stores.messages.loadThread('t1')),
+    ).toEqual([
+      ['user', 'hi'],
+      ['assistant', 'answer'],
+      ['user', 'still here'],
+      ['assistant', 'answer'],
+    ])
+    await host.close()
+  })
+
+  it('forks the transcript before or through a message into a new thread', async () => {
+    const { persistence, host, harness } = hostWith()
+    const session = await host.open(harness, {
+      threadId: 't1',
+      principal: { id: 'u1' },
+    })
+    await session.prompt('first')
+    await session.prompt('second')
+    await host.sessions.rename('t1', 'Chat')
+    const [, , second] = await session.transcript()
+
+    const before = await host.sessions.fork('t1', { before: idOf(second) })
+    const through = await host.sessions.fork('t1', { through: idOf(second) })
+
+    expect(before).toEqual({
+      threadId: expect.any(String),
+      harness: 'test/sessions',
+      title: 'Chat (fork)',
+      principal: { id: 'u1' },
+      createdAt: expect.any(Number),
+      updatedAt: expect.any(Number),
+    })
+    expect(before.threadId).not.toBe(through.threadId)
+    expect(await host.sessions.get(before.threadId)).toEqual(before)
+    const { messages } = persistence.stores
+    expect(turnsOf(await messages.loadThread(before.threadId))).toEqual([
+      ['user', 'first'],
+      ['assistant', 'answer'],
+    ])
+    expect(turnsOf(await messages.loadThread(through.threadId))).toEqual([
+      ['user', 'first'],
+      ['assistant', 'answer'],
+      ['user', 'second'],
+    ])
+    await host.close()
+  })
+
+  it('forks a durable thread into one transcript record in a new log', async () => {
+    const log = memoryLogStore()
+    const { runs, metadata, sessions } = memoryPersistence().stores
+    const host = createHarnessHost({
+      persistence: { stores: { log, runs, metadata, sessions } },
+    })
+    const harness = defineHarness({
+      name: 'test/sessions-durable',
+      adapter: mockAdapter(() => text('durable answer')).adapter,
+    })
+    const session = await host.open(harness, { threadId: 'd1' })
+    await session.prompt('hi')
+    const [, answer] = await session.transcript()
+
+    const fork = await host.sessions.fork('d1', { through: idOf(answer) })
+
+    const records = await log.read(fork.threadId)
+    expect(records.map(({ record }) => [record.type, record.keep])).toEqual([
+      ['harness.transcript', 0],
+    ])
+    const forked = await host.open(harness, { threadId: fork.threadId })
+    expect(turnsOf(await forked.transcript())).toEqual([
+      ['user', 'hi'],
+      ['assistant', 'durable answer'],
+    ])
+    await host.close()
+  })
+
+  it('refuses a fork at a message that is not in the transcript', async () => {
+    const { host, harness } = hostWith()
+    const session = await host.open(harness, { threadId: 't1' })
+    await session.prompt('hi')
+
+    await expect(
+      host.sessions.fork('t1', { through: 'not-a-message' }),
+    ).rejects.toThrow('The transcript has no message with id not-a-message.')
+    expect(threadIds(await host.sessions.list())).toEqual(['t1'])
+    await host.close()
+  })
+})
+
+describe('ctx.session.entry and updateEntry', () => {
+  it('reads and changes the entry of the thread of the plugin', async () => {
+    const { host, api } = await openWithApi(memoryPersistence())
+
+    expect(await api.entry()).toMatchObject({
+      threadId: 'p1',
+      harness: 'test/sessions-plugin',
+    })
+    const changed = await api.updateEntry({
+      title: 'From a plugin',
+      metadata: { model: 'm-1' },
+    })
+
+    expect(changed).toMatchObject({
+      title: 'From a plugin',
+      metadata: { model: 'm-1' },
+    })
+    expect(await host.sessions.get('p1')).toMatchObject({
+      threadId: 'p1',
+      title: 'From a plugin',
+      metadata: { model: 'm-1' },
+      principal: { id: 'u1' },
+    })
+    await host.close()
+  })
+
+  it('reads nothing and writes nothing without a sessions store', async () => {
+    const { messages, runs, metadata } = memoryPersistence().stores
+    const { host, session, api } = await openWithApi({
+      stores: { messages, runs, metadata },
+    })
+    await session.prompt('hi')
+
+    expect(await host.sessions.list()).toEqual({ entries: [] })
+    expect(await host.sessions.get('p1')).toBeUndefined()
+    expect(await host.sessions.rename('p1', 'x')).toBeUndefined()
+    expect(await api.entry()).toBeUndefined()
+    expect(await api.updateEntry({ title: 'x' })).toBeUndefined()
+    await host.close()
+  })
+})
+
+describe('sessions over HTTP', () => {
+  /** A handler where the `x-user` header is the principal. */
+  function setup() {
+    const harness = defineHarness({
+      name: 'test/sessions-http',
+      adapter: mockAdapter(() => text('hello')).adapter,
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const handler = createHarnessHandler({
+      host,
+      harness,
+      authorize: (request) => {
+        const id = request.headers.get('x-user')
+        return id ? { id } : null
+      },
+      canAccess: (_principal, threadId) => threadId !== 'hidden',
+    })
+    const fetch: typeof globalThis.fetch = (input, init) =>
+      handler(new Request(input, init))
+    const clientOf = (user: string) =>
+      createHarnessClient({
+        url: 'http://local/api/harness',
+        threadId: `${user}-thread`,
+        headers: { 'x-user': user },
+        fetch,
+      })
+    /** Prompt in the thread of `client` and wait for the answer. */
+    const chat = async (client: ReturnType<typeof clientOf>) => {
+      await client.prompt('hi')
+      await vi.waitFor(async () =>
+        expect(await client.transcript()).toHaveLength(2),
+      )
+      return client.transcript()
+    }
+    return { host, harness, handler, clientOf, chat }
+  }
+
+  it('lists, renames, forks, and deletes the sessions of the user', async () => {
+    const { host, clientOf, chat } = setup()
+    const alice = clientOf('alice')
+    const [, answer] = await chat(alice)
+
+    expect(threadIds(await alice.listSessions())).toEqual(['alice-thread'])
+    expect(
+      (await alice.renameSession('alice-thread', 'Greetings')).title,
+    ).toBe('Greetings')
+    const fork = await alice.forkSession('alice-thread', {
+      through: idOf(answer),
+    })
+    expect(fork.title).toBe('Greetings (fork)')
+    expect(threadIds(await alice.listSessions()).sort()).toEqual(
+      ['alice-thread', fork.threadId].sort(),
+    )
+
+    await alice.deleteSession(fork.threadId)
+
+    expect(threadIds(await alice.listSessions())).toEqual(['alice-thread'])
+    await host.close()
+  })
+
+  it('keeps one user out of the sessions of another', async () => {
+    const { host, harness, clientOf, chat } = setup()
+    const alice = clientOf('alice')
+    const bob = clientOf('bob')
+    const [, answer] = await chat(alice)
+    await chat(bob)
+    // Alice owns this thread, but `canAccess` refuses it.
+    await host.open(harness, { threadId: 'hidden', principal: { id: 'alice' } })
+
+    expect(threadIds(await bob.listSessions())).toEqual(['bob-thread'])
+    expect(threadIds(await alice.listSessions())).toEqual(['alice-thread'])
+    await expect(bob.renameSession('alice-thread', 'Mine')).rejects.toThrow(
+      '(404)',
+    )
+    await expect(bob.deleteSession('alice-thread')).rejects.toThrow('(404)')
+    await expect(
+      bob.forkSession('alice-thread', { through: idOf(answer) }),
+    ).rejects.toThrow('(404)')
+    await expect(alice.renameSession('hidden', 'x')).rejects.toThrow('(403)')
+    expect(await host.sessions.get('alice-thread')).toMatchObject({
+      principal: { id: 'alice' },
+    })
+    expect((await host.sessions.get('alice-thread'))?.title).toBeUndefined()
+    await host.close()
+  })
+
+  it('answers 400 for a bad sessions request', async () => {
+    const { host, handler, clientOf, chat } = setup()
+    const alice = clientOf('alice')
+    await chat(alice)
+    const post = async (body: unknown) =>
+      (
+        await handler(
+          new Request('http://local/api/harness/sessions', {
+            method: 'POST',
+            headers: { 'x-user': 'alice', 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+          }),
+        )
+      ).status
+
+    expect(
+      await post({
+        op: 'fork',
+        threadId: 'alice-thread',
+        before: 'a',
+        through: 'b',
+      }),
+    ).toBe(400)
+    expect(await post({ op: 'move', threadId: 'alice-thread' })).toBe(400)
+    const list = await handler(
+      new Request('http://local/api/harness/sessions?limit=0', {
+        headers: { 'x-user': 'alice' },
+      }),
+    )
+    expect(list.status).toBe(400)
+    await expect(
+      alice.forkSession('alice-thread', { before: 'not-a-message' }),
+    ).rejects.toThrow(
+      '(400): The transcript has no message with id not-a-message.',
+    )
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/view-reduce.test.ts b/packages/ai-harness/tests/view-reduce.test.ts
index ceb2a06f9b..2dc4c6e2a9 100644
--- a/packages/ai-harness/tests/view-reduce.test.ts
+++ b/packages/ai-harness/tests/view-reduce.test.ts
@@ -12,6 +12,7 @@ import {
 } 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'
 
@@ -401,6 +402,43 @@ describe('view reducer', () => {
     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({
diff --git a/packages/ai-harness/tests/workspace-tools.test.ts b/packages/ai-harness/tests/workspace-tools.test.ts
index edebb29eca..f6ddaaff33 100644
--- a/packages/ai-harness/tests/workspace-tools.test.ts
+++ b/packages/ai-harness/tests/workspace-tools.test.ts
@@ -1,21 +1,91 @@
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { join, sep } from 'node:path'
+import { join, resolve, sep } from 'node:path'
 import { afterAll, beforeAll, describe, expect, it } from 'vitest'
-import { createWorkspaceTools } from '../src/first-party/workspace'
+import { hostBackend } from '../src/first-party/coding/backend'
+import { createWorkspaceTools } from '../src/first-party/coding/workspace'
 import type { AnyTool } from '@tanstack/ai'
+import type { WorkspaceBackend } from '../src/first-party/coding/backend'
 import type {
   OutsideAccess,
   WorkspaceToolsOptions,
-} from '../src/first-party/workspace'
+} from '../src/first-party/coding/workspace'
 
-let root: string
-let tools: Map<string, AnyTool>
+/** A backend that keeps files in a map, by absolute path. It runs no commands. */
+function memoryBackend() {
+  const files = new Map<string, Uint8Array>()
+  const backend: WorkspaceBackend = {
+    readFile: async (path) => {
+      const data = files.get(path)
+      if (!data) throw new Error(`No file ${path}`)
+      return data
+    },
+    writeFile: async (path, data) => {
+      files.set(
+        path,
+        typeof data === 'string' ? new TextEncoder().encode(data) : data,
+      )
+    },
+    stat: async (path) => {
+      const data = files.get(path)
+      if (!data) return undefined
+      return { type: 'file', size: data.length, mtimeMs: 0 }
+    },
+    readdir: async (path) => {
+      const prefix = path.endsWith(sep) ? path : path + sep
+      const entries = new Map<string, 'file' | 'dir'>()
+      for (const file of files.keys()) {
+        if (!file.startsWith(prefix)) continue
+        const [name = '', ...rest] = file.slice(prefix.length).split(sep)
+        entries.set(name, rest.length > 0 ? 'dir' : 'file')
+      }
+      // Sorted by name, like the host.
+      return [...entries]
+        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .map(([name, type]) => ({ name, type }))
+    },
+    exec: async (command, options) => ({
+      exitCode: 3,
+      stdout: `ran ${command} in ${options?.cwd}`,
+      stderr: 'warn',
+    }),
+  }
+  return backend
+}
+
+/** A backend, and how to make and remove an empty folder on it. */
+interface Fixture {
+  name: string
+  backend: WorkspaceBackend
+  folder: (prefix: string) => Promise<string>
+  remove: (folder: string) => Promise<void>
+}
+
+let memoryFolders = 0
+const fixtures: Array<Fixture> = [
+  {
+    name: 'host',
+    backend: hostBackend,
+    folder: (prefix) => mkdtemp(join(tmpdir(), prefix)),
+    remove: (folder) => rm(folder, { recursive: true, force: true }),
+  },
+  {
+    name: 'memory',
+    backend: memoryBackend(),
+    folder: async (prefix) => {
+      memoryFolders += 1
+      return resolve(tmpdir(), `${prefix}${memoryFolders}`)
+    },
+    remove: async () => undefined,
+  },
+]
+
+const decoder = new TextDecoder()
 
 /** The tools by name, for `options` and the user's `access`. */
 function toolsOf(options: WorkspaceToolsOptions, access?: OutsideAccess) {
   return new Map(
-    createWorkspaceTools(options, access).tools.map(
+    createWorkspaceTools(options, { access }).tools.map(
       (tool): [string, AnyTool] => [tool.name, tool],
     ),
   )
@@ -30,209 +100,241 @@ const runIn = (
   if (!tool?.execute) throw new Error(`No tool ${name}`)
   return Promise.resolve(tool.execute(args))
 }
-const run = (name: string, args: unknown) => runIn(tools, name, args)
-
-beforeAll(async () => {
-  root = await mkdtemp(join(tmpdir(), 'harness-workspace-'))
-  await mkdir(join(root, 'src', 'deep'), { recursive: true })
-  await mkdir(join(root, 'node_modules', 'pkg'), { recursive: true })
-  await writeFile(join(root, 'src', 'a.ts'), 'one\ntwo\nthree\nfour\n')
-  await writeFile(join(root, 'src', 'deep', 'b.ts'), 'const two = 2\n')
-  await writeFile(join(root, 'notes.md'), 'two words\n')
-  await writeFile(join(root, 'node_modules', 'pkg', 'index.js'), 'two\n')
-  await writeFile(join(root, 'big.txt'), `two\n${'x'.repeat(1_100_000)}`)
-  tools = toolsOf({ root, bashTimeoutMs: 20_000 })
-})
 
-afterAll(async () => {
-  await rm(root, { recursive: true, force: true })
-})
+describe.each(fixtures)('workspace tools on the $name backend', (fixture) => {
+  const { backend } = fixture
+  let root: string
+  let tools: Map<string, AnyTool>
 
-describe('read_file', () => {
-  it('reads a window of numbered lines', async () => {
-    expect(
-      await run('read_file', { path: 'src/a.ts', offset: 2, limit: 2 }),
-    ).toBe('2\ttwo\n3\tthree')
-    expect(
-      await run('read_file', { path: 'src/a.ts', offset: -4, limit: 1 }),
-    ).toBe('1\tone')
-  })
+  const run = (name: string, args: unknown) => runIn(tools, name, args)
+  const write = (path: string, text: string) =>
+    backend.writeFile(join(root, path), text)
+  const read = async (path: string) =>
+    decoder.decode(await backend.readFile(join(root, path)))
 
-  it('refuses paths outside the workspace and missing arguments', async () => {
-    await expect(run('read_file', { path: '../outside.txt' })).rejects.toThrow(
-      'outside the workspace',
-    )
-    await expect(
-      run('read_file', { path: join(tmpdir(), 'elsewhere.txt') }),
-    ).rejects.toThrow('outside the workspace')
-    await expect(run('read_file', {})).rejects.toThrow(
-      'Argument "path" must be a string.',
-    )
-    await expect(run('read_file', null)).rejects.toThrow('must be a string')
+  beforeAll(async () => {
+    root = await fixture.folder('harness-workspace-')
+    await write('src/a.ts', 'one\ntwo\nthree\nfour\n')
+    await write('src/deep/b.ts', 'const two = 2\n')
+    await write('notes.md', 'two words\n')
+    await write('node_modules/pkg/index.js', 'two\n')
+    await write('big.txt', `two\n${'x'.repeat(1_100_000)}`)
+    tools = toolsOf({ root, backend })
   })
 
-  it('cuts very long output', async () => {
-    await writeFile(join(root, 'long.txt'), 'y'.repeat(25_000))
-    const text = await run('read_file', { path: 'long.txt' })
-    expect(text).toContain('more characters]')
-    expect(text.length).toBeLessThan(21_000)
+  afterAll(async () => {
+    await fixture.remove(root)
   })
-})
 
-describe('write_file and edit_file', () => {
-  it('creates folders and files', async () => {
-    expect(
-      await run('write_file', { path: 'new/dir/c.txt', content: 'hi' }),
-    ).toBe('Wrote new/dir/c.txt.')
-    expect(await readFile(join(root, 'new', 'dir', 'c.txt'), 'utf8')).toBe('hi')
-    await expect(run('write_file', { path: 'x.txt' })).rejects.toThrow(
-      'Argument "content" must be a string.',
-    )
-  })
+  describe('read_file', () => {
+    it('reads a window of numbered lines', async () => {
+      expect(
+        await run('read_file', { path: 'src/a.ts', offset: 2, limit: 2 }),
+      ).toBe('2\ttwo\n3\tthree')
+      expect(
+        await run('read_file', { path: 'src/a.ts', offset: -4, limit: 1 }),
+      ).toBe('1\tone')
+    })
 
-  it('edits one match, refuses ambiguous or missing text, and replaces all when asked', async () => {
-    await writeFile(join(root, 'e.txt'), 'a b a')
-    await expect(
-      run('edit_file', { path: 'e.txt', old: 'zzz', new: 'q' }),
-    ).rejects.toThrow('not in the file')
-    await expect(
-      run('edit_file', { path: 'e.txt', old: 'a', new: 'q' }),
-    ).rejects.toThrow('appears 2 times')
-    expect(
-      await run('edit_file', {
-        path: 'e.txt',
-        old: 'a',
-        new: 'q',
-        replaceAll: true,
-      }),
-    ).toBe('Edited e.txt (2 changes).')
-    expect(await run('edit_file', { path: 'e.txt', old: 'b', new: 'c' })).toBe(
-      'Edited e.txt (1 change).',
-    )
-    expect(await readFile(join(root, 'e.txt'), 'utf8')).toBe('q c q')
-  })
-})
+    it('refuses paths outside the workspace and missing arguments', async () => {
+      await expect(
+        run('read_file', { path: '../outside.txt' }),
+      ).rejects.toThrow('outside the workspace')
+      await expect(
+        run('read_file', { path: join(tmpdir(), 'elsewhere.txt') }),
+      ).rejects.toThrow('outside the workspace')
+      await expect(run('read_file', {})).rejects.toThrow(
+        'Argument "path" must be a string.',
+      )
+      await expect(run('read_file', null)).rejects.toThrow('must be a string')
+    })
 
-describe('list_files and grep', () => {
-  it('lists files, skips dependency folders, and filters by glob', async () => {
-    const all = await run('list_files', {})
-    expect(all).toContain('src/deep/b.ts')
-    expect(all).not.toContain('node_modules')
-    expect(await run('list_files', { pattern: 'src/**/*.ts' })).toBe(
-      'src/a.ts\nsrc/deep/b.ts',
-    )
-    expect(await run('list_files', { pattern: '*.none' })).toBe('No files.')
+    it('cuts very long output', async () => {
+      await write('long.txt', 'y'.repeat(25_000))
+      const text = await run('read_file', { path: 'long.txt' })
+      expect(text).toContain('more characters]')
+      expect(text.length).toBeLessThan(21_000)
+    })
   })
 
-  it('finds lines, skips big files, and filters by glob', async () => {
-    const hits = await run('grep', { pattern: 'two' })
-    expect(hits).toContain('src/a.ts:2: two')
-    expect(hits).toContain('notes.md:1: two words')
-    expect(hits).not.toContain('big.txt')
-    expect(hits).not.toContain('node_modules')
-    expect(await run('grep', { pattern: 'two', glob: '**/*.md' })).toBe(
-      'notes.md:1: two words',
-    )
-    expect(await run('grep', { pattern: 'nothing-like-this' })).toBe(
-      'No matches.',
-    )
-  })
-})
+  describe('write_file and edit_file', () => {
+    it('creates folders and files', async () => {
+      expect(
+        await run('write_file', { path: 'new/dir/c.txt', content: 'hi' }),
+      ).toBe('Wrote new/dir/c.txt.')
+      expect(await read('new/dir/c.txt')).toBe('hi')
+      await expect(run('write_file', { path: 'x.txt' })).rejects.toThrow(
+        'Argument "content" must be a string.',
+      )
+    })
 
-describe('bash', () => {
-  it('reports the exit code and stderr', async () => {
-    const ok = await run('bash', {
-      command: `node -e "console.log('out'); console.error('warn')"`,
+    it('edits one match, refuses ambiguous or missing text, and replaces all when asked', async () => {
+      await write('e.txt', 'a b a')
+      await expect(
+        run('edit_file', { path: 'e.txt', old: 'zzz', new: 'q' }),
+      ).rejects.toThrow('not in the file')
+      await expect(
+        run('edit_file', { path: 'e.txt', old: 'a', new: 'q' }),
+      ).rejects.toThrow('appears 2 times')
+      expect(
+        await run('edit_file', {
+          path: 'e.txt',
+          old: 'a',
+          new: 'q',
+          replaceAll: true,
+        }),
+      ).toBe('Edited e.txt (2 changes).')
+      expect(
+        await run('edit_file', { path: 'e.txt', old: 'b', new: 'c' }),
+      ).toBe('Edited e.txt (1 change).')
+      expect(await read('e.txt')).toBe('q c q')
     })
-    expect(ok).toMatch(/^exit code: 0\nout/)
-    expect(ok).toContain('stderr:\nwarn')
-    const failed = await run('bash', { command: `node -e "process.exit(3)"` })
-    expect(failed).toMatch(/^exit code: 3/)
-  })
-})
 
-describe('outside the workspace', () => {
-  let outside: string
-  beforeAll(async () => {
-    outside = await mkdtemp(join(tmpdir(), 'harness-outside-'))
-    await mkdir(join(outside, 'docs'), { recursive: true })
-    await writeFile(join(outside, 'docs', 'a.md'), 'alpha')
-    await writeFile(join(outside, 'docs', 'b.md'), 'beta')
-    await writeFile(join(outside, 'top.md'), 'top')
+    it('runs edits to one file one at a time, so none is lost', async () => {
+      await write('race.txt', 'a b')
+      await Promise.all([
+        run('edit_file', { path: 'race.txt', old: 'a', new: 'x' }),
+        run('edit_file', { path: 'race.txt', old: 'b', new: 'y' }),
+      ])
+      expect(await read('race.txt')).toBe('x y')
+    })
   })
-  afterAll(async () => {
-    await rm(outside, { recursive: true, force: true })
+
+  describe('list_files and grep', () => {
+    it('lists files, skips dependency folders, and filters by glob', async () => {
+      const all = await run('list_files', {})
+      expect(all).toContain('src/deep/b.ts')
+      expect(all).not.toContain('node_modules')
+      expect(await run('list_files', { pattern: 'src/**/*.ts' })).toBe(
+        'src/a.ts\nsrc/deep/b.ts',
+      )
+      expect(await run('list_files', { pattern: '*.none' })).toBe('No files.')
+    })
+
+    it('finds lines, skips big files, and filters by glob', async () => {
+      const hits = await run('grep', { pattern: 'two' })
+      expect(hits).toContain('src/a.ts:2: two')
+      expect(hits).toContain('notes.md:1: two words')
+      expect(hits).not.toContain('big.txt')
+      expect(hits).not.toContain('node_modules')
+      expect(await run('grep', { pattern: 'two', glob: '**/*.md' })).toBe(
+        'notes.md:1: two words',
+      )
+      expect(await run('grep', { pattern: 'nothing-like-this' })).toBe(
+        'No matches.',
+      )
+    })
   })
 
-  /** Tools that ask about outside paths. The user answers from `answers`. */
-  function asking(answers: Array<unknown>, mode = 'default') {
-    const questions: Array<string> = []
-    const set = toolsOf(
-      { root, outside: 'ask' },
-      {
-        ask: async (message) => {
-          questions.push(message)
-          return answers.shift()
+  describe('outside the workspace', () => {
+    let outside: string
+    beforeAll(async () => {
+      outside = await fixture.folder('harness-outside-')
+      await backend.writeFile(join(outside, 'docs', 'a.md'), 'alpha')
+      await backend.writeFile(join(outside, 'docs', 'b.md'), 'beta')
+      await backend.writeFile(join(outside, 'top.md'), 'top')
+    })
+    afterAll(async () => {
+      await fixture.remove(outside)
+    })
+
+    /** Tools that ask about outside paths. The user answers from `answers`. */
+    function asking(answers: Array<unknown>, mode = 'default') {
+      const questions: Array<string> = []
+      const set = toolsOf(
+        { root, backend, outside: 'ask' },
+        {
+          ask: async (message) => {
+            questions.push(message)
+            return answers.shift()
+          },
+          mode: () => mode,
         },
-        mode: () => mode,
-      },
-    )
-    return { set, questions }
-  }
+      )
+      return { set, questions }
+    }
 
-  it('refuses outside paths without the outside option', async () => {
-    await expect(
-      run('read_file', { path: join(outside, 'top.md') }),
-    ).rejects.toThrow('outside the workspace')
-  })
+    it('refuses outside paths without the outside option', async () => {
+      await expect(
+        run('read_file', { path: join(outside, 'top.md') }),
+      ).rejects.toThrow('outside the workspace')
+    })
 
-  it('asks once for a folder, then allows it for the session', async () => {
-    const { set, questions } = asking([true])
-    expect(
-      await runIn(set, 'read_file', { path: join(outside, 'docs', 'a.md') }),
-    ).toBe('1\talpha')
-    expect(
-      await runIn(set, 'read_file', { path: join(outside, 'docs', 'b.md') }),
-    ).toBe('1\tbeta')
-    expect(questions).toHaveLength(1)
-    expect(questions[0]).toContain(`Allow ${join(outside, 'docs')}`)
-  })
+    it('asks once for a folder, then allows it for the session', async () => {
+      const { set, questions } = asking([true])
+      expect(
+        await runIn(set, 'read_file', { path: join(outside, 'docs', 'a.md') }),
+      ).toBe('1\talpha')
+      expect(
+        await runIn(set, 'read_file', { path: join(outside, 'docs', 'b.md') }),
+      ).toBe('1\tbeta')
+      expect(questions).toHaveLength(1)
+      expect(questions[0]).toContain(`Allow ${join(outside, 'docs')}`)
+    })
 
-  it('asks again for another folder, and refuses after a no', async () => {
-    const { set, questions } = asking([true, 'n'])
-    await runIn(set, 'read_file', { path: join(outside, 'docs', 'a.md') })
-    await expect(
-      runIn(set, 'read_file', { path: join(outside, 'top.md') }),
-    ).rejects.toThrow('The user did not allow')
-    expect(questions).toHaveLength(2)
-  })
+    it('asks again for another folder, and refuses after a no', async () => {
+      const { set, questions } = asking([true, 'n'])
+      await runIn(set, 'read_file', { path: join(outside, 'docs', 'a.md') })
+      await expect(
+        runIn(set, 'read_file', { path: join(outside, 'top.md') }),
+      ).rejects.toThrow('The user did not allow')
+      expect(questions).toHaveLength(2)
+    })
 
-  it('asks one question for calls at the same time', async () => {
-    const { set, questions } = asking([true])
-    await Promise.all([
-      runIn(set, 'read_file', { path: join(outside, 'docs', 'a.md') }),
-      runIn(set, 'read_file', { path: join(outside, 'docs', 'b.md') }),
-    ])
-    expect(questions).toHaveLength(1)
+    it('asks one question for calls at the same time', async () => {
+      const { set, questions } = asking([true])
+      await Promise.all([
+        runIn(set, 'read_file', { path: join(outside, 'docs', 'a.md') }),
+        runIn(set, 'read_file', { path: join(outside, 'docs', 'b.md') }),
+      ])
+      expect(questions).toHaveLength(1)
+    })
+
+    it('lists and searches an allowed outside folder with full paths', async () => {
+      const { set } = asking([true])
+      const folder = join(outside, 'docs')
+      const shown = folder.split(sep).join('/')
+      expect(await runIn(set, 'list_files', { path: folder })).toBe(
+        `${shown}/a.md\n${shown}/b.md`,
+      )
+      expect(await runIn(set, 'grep', { pattern: 'beta', path: folder })).toBe(
+        `${shown}/b.md:1: beta`,
+      )
+    })
+
+    it('does not ask in bypass mode', async () => {
+      const { set, questions } = asking([], 'bypass')
+      expect(
+        await runIn(set, 'read_file', { path: join(outside, 'top.md') }),
+      ).toBe('1\ttop')
+      expect(questions).toHaveLength(0)
+    })
   })
+})
 
-  it('lists and searches an allowed outside folder with full paths', async () => {
-    const { set } = asking([true])
-    const folder = join(outside, 'docs')
-    const shown = folder.split(sep).join('/')
-    expect(await runIn(set, 'list_files', { path: folder })).toBe(
-      `${shown}/a.md\n${shown}/b.md`,
-    )
-    expect(await runIn(set, 'grep', { pattern: 'beta', path: folder })).toBe(
-      `${shown}/b.md:1: beta`,
-    )
+describe('bash', () => {
+  it('reports the exit code and stderr on the host', async () => {
+    const set = toolsOf({
+      root: tmpdir(),
+      backend: hostBackend,
+      bashTimeoutMs: 20_000,
+    })
+    const ok = await runIn(set, 'bash', {
+      command: `node -e "console.log('out'); console.error('warn')"`,
+    })
+    expect(ok).toMatch(/^exit code: 0\nout/)
+    expect(ok).toContain('stderr:\nwarn')
+    const failed = await runIn(set, 'bash', {
+      command: `node -e "process.exit(3)"`,
+    })
+    expect(failed).toMatch(/^exit code: 3/)
   })
 
-  it('does not ask in bypass mode', async () => {
-    const { set, questions } = asking([], 'bypass')
-    expect(
-      await runIn(set, 'read_file', { path: join(outside, 'top.md') }),
-    ).toBe('1\ttop')
-    expect(questions).toHaveLength(0)
+  it('runs the command through the backend, in the workspace folder', async () => {
+    const root = resolve(tmpdir(), 'harness-bash')
+    const set = toolsOf({ root, backend: memoryBackend() })
+    expect(await runIn(set, 'bash', { command: 'make' })).toBe(
+      `exit code: 3\nran make in ${root}\nstderr:\nwarn`,
+    )
   })
 })
diff --git a/packages/ai-harness/vite.config.ts b/packages/ai-harness/vite.config.ts
index 17373da93a..5e7fcb2d13 100644
--- a/packages/ai-harness/vite.config.ts
+++ b/packages/ai-harness/vite.config.ts
@@ -33,6 +33,7 @@ export default mergeConfig(
       './src/client.ts',
       './src/view/index.ts',
       './src/first-party/index.ts',
+      './src/first-party/coding/index.ts',
       './src/build.ts',
       './src/worker.ts',
     ],
diff --git a/packages/ai-persistence/src/index.ts b/packages/ai-persistence/src/index.ts
index 6c1855ec76..d1d1b2b0c0 100644
--- a/packages/ai-persistence/src/index.ts
+++ b/packages/ai-persistence/src/index.ts
@@ -12,6 +12,7 @@ export {
   defineInboxStore,
   defineCredentialStore,
   defineLogStore,
+  defineSessionIndexStore,
   LogConflictError,
   // Run lifecycle helpers owned by @tanstack/ai, transiting through ./types so
   // this package's public surface stays a single import for backend authors.
@@ -44,6 +45,11 @@ export type {
   LeaseStore,
   TurnLease,
   TurnLeaseKey,
+  // Harness session index
+  SessionIndexEntry,
+  SessionIndexListOptions,
+  SessionIndexPage,
+  SessionIndexStore,
   // Named product shapes (prefer these over a sparse bag)
   ChatTranscriptStores,
   ChatPersistenceStores,
diff --git a/packages/ai-persistence/src/memory.ts b/packages/ai-persistence/src/memory.ts
index 1b2890c371..13983a0d78 100644
--- a/packages/ai-persistence/src/memory.ts
+++ b/packages/ai-persistence/src/memory.ts
@@ -29,6 +29,9 @@ import type {
   MetadataStore,
   RunRecord,
   RunStore,
+  SessionIndexEntry,
+  SessionIndexListOptions,
+  SessionIndexStore,
 } from './types'
 
 const compareUtf8Bytes = (left: string, right: string): number => {
@@ -674,6 +677,70 @@ class MemoryCredentialStore implements CredentialStore {
   }
 }
 
+// Newest `updatedAt` first, then `threadId` order. The cursor uses it too.
+const bySessionOrder = (
+  a: Pick<SessionIndexEntry, 'updatedAt' | 'threadId'>,
+  b: Pick<SessionIndexEntry, 'updatedAt' | 'threadId'>,
+) => b.updatedAt - a.updatedAt || compareUtf8Bytes(a.threadId, b.threadId)
+
+// The cursor is `<updatedAt>:<threadId>` of the last entry of a page.
+function parseSessionCursor(cursor: string) {
+  const split = cursor.indexOf(':')
+  const updatedAt = Number(cursor.slice(0, split))
+  if (split <= 0 || !Number.isFinite(updatedAt)) {
+    throw new Error(`Invalid session index cursor: ${cursor}`)
+  }
+  return { updatedAt, threadId: cursor.slice(split + 1) }
+}
+
+class MemorySessionIndexStore implements SessionIndexStore {
+  private readonly entries = new Map<string, SessionIndexEntry>()
+  upsert(entry: SessionIndexEntry) {
+    // Copies in and out, so a caller never changes a stored entry.
+    this.entries.set(entry.threadId, structuredClone(entry))
+    return Promise.resolve()
+  }
+  get(threadId: string) {
+    const entry = this.entries.get(threadId)
+    return Promise.resolve(entry && structuredClone(entry))
+  }
+  list(options: SessionIndexListOptions = {}) {
+    const { limit, cursor, parentThreadId, principal } = options
+    const after = cursor === undefined ? undefined : parseSessionCursor(cursor)
+    const matching = [...this.entries.values()]
+      .filter((entry) => {
+        // `null` asks for the entries with no parent.
+        const isChild =
+          parentThreadId === undefined ||
+          (entry.parentThreadId ?? null) === parentThreadId
+        const isSameTenant =
+          principal?.tenantId === undefined ||
+          entry.principal?.tenantId === principal.tenantId
+        const isOwned =
+          principal === undefined ||
+          (entry.principal?.id === principal.id && isSameTenant)
+        const isAfterCursor =
+          after === undefined || bySessionOrder(after, entry) < 0
+        return isChild && isOwned && isAfterCursor
+      })
+      .sort(bySessionOrder)
+    const page = limit === undefined ? matching : matching.slice(0, limit)
+    const last = page.at(-1)
+    const hasMore =
+      limit !== undefined && matching.length > limit && last !== undefined
+    return Promise.resolve({
+      entries: page.map((entry) => structuredClone(entry)),
+      ...(hasMore
+        ? { cursor: `${last.updatedAt}:${last.threadId}`, truncated: true }
+        : {}),
+    })
+  }
+  delete(threadId: string) {
+    this.entries.delete(threadId)
+    return Promise.resolve()
+  }
+}
+
 /** A JSON copy, so the log never shares an object with a caller. */
 const copyRecord = (record: LogRecord) =>
   JSON.parse(JSON.stringify(record)) as LogRecord
@@ -761,13 +828,14 @@ interface MemoryPersistenceStores {
   blobs: BlobStore
   inbox: InboxStore
   credentials: CredentialStore
+  sessions: SessionIndexStore
 }
 
 /**
  * In-process reference backend for the full state + generation store set.
  *
  * Returns messages + runs + generationRuns + interrupts + metadata + artifacts
- * + blobs + inbox + credentials. Locks are not included — use `InMemoryLockStore` +
+ * + blobs + inbox + credentials + sessions. Locks are not included. Use `InMemoryLockStore` +
  * `withLocks` from `@tanstack/ai` when a test or single-process app needs
  * coordination.
  */
@@ -780,6 +848,7 @@ export function memoryPersistence() {
     metadata: new MemoryMetadataStore(),
     inbox: new MemoryInboxStore(),
     credentials: new MemoryCredentialStore(),
+    sessions: new MemorySessionIndexStore(),
     artifacts: new MemoryArtifactStore(),
     blobs: new MemoryBlobStore(),
   }
diff --git a/packages/ai-persistence/src/middleware.ts b/packages/ai-persistence/src/middleware.ts
index 89e0d92fee..f768cd77ff 100644
--- a/packages/ai-persistence/src/middleware.ts
+++ b/packages/ai-persistence/src/middleware.ts
@@ -3,7 +3,9 @@ import {
   fromSpecTokenUsage,
   getDetachableRun,
   InterruptResumeValidationError,
+  LoadChildCapability,
   MetadataCapability,
+  provideLoadChild,
   provideMetadata,
   readInterruptBinding,
   validateInterruptResumeBatch,
@@ -1916,6 +1918,7 @@ interface PersistencePlan {
   wantsInterrupts: boolean
   wantsArtifactPersistence: boolean
   runs: AIPersistence['stores']['runs']
+  sessions: AIPersistence['stores']['sessions']
 }
 
 function resolvePersistencePlan(persistence: AIPersistence): PersistencePlan {
@@ -1925,6 +1928,7 @@ function resolvePersistencePlan(persistence: AIPersistence): PersistencePlan {
       persistence.stores.artifacts !== undefined &&
       persistence.stores.blobs !== undefined,
     runs: persistence.stores.runs,
+    sessions: persistence.stores.sessions,
   }
 }
 
@@ -2250,7 +2254,7 @@ export function withPersistence<TStores extends ChatTranscriptStores>(
   const snapshotStreaming = options.snapshotStreaming ?? false
   const snapshotIntervalMs = options.snapshotIntervalMs ?? 1000
   const plan = resolvePersistencePlan(persistence)
-  const { wantsInterrupts, runs } = plan
+  const { wantsInterrupts, runs, sessions } = plan
   const messageStore = persistence.stores.messages
   if (!messageStore) {
     // validateChatPersistenceStores already throws; this narrows for TypeScript.
@@ -2260,6 +2264,7 @@ export function withPersistence<TStores extends ChatTranscriptStores>(
   const provides = [
     PersistenceCapability,
     PersistenceCompletionCapability,
+    LoadChildCapability,
     ...(persistence.stores.metadata ? [MetadataCapability] : []),
     ...(wantsInterrupts ? [InterruptsCapability] : []),
   ]
@@ -2271,6 +2276,7 @@ export function withPersistence<TStores extends ChatTranscriptStores>(
     ...(wantsInterrupts && persistence.stores.interrupts
       ? { interrupts: persistence.stores.interrupts }
       : {}),
+    ...(sessions ? { sessions } : {}),
   })
 
   async function updateStreamingRows(
@@ -2311,6 +2317,16 @@ export function withPersistence<TStores extends ChatTranscriptStores>(
       if (persistence.stores.metadata) {
         provideMetadata(ctx, persistence.stores.metadata)
       }
+      // The `subagent` tool reads stored children through this, to continue
+      // one by `sessionId`. Only the children of this chat can load.
+      provideLoadChild(ctx, (subagentRunId) =>
+        subagentRuns.loadChild(subagentRunId, {
+          threadId: ctx.threadId,
+          ...(ctx.subagentRunId !== undefined && {
+            subagentRunId: ctx.subagentRunId,
+          }),
+        }),
+      )
 
       let resolveCompletion: () => void = () => undefined
       let rejectCompletion: (error: unknown) => void = () => undefined
@@ -2462,6 +2478,9 @@ export function withPersistence<TStores extends ChatTranscriptStores>(
       await subagentRuns.chunk({
         threadId: ctx.threadId,
         runId: ctx.runId,
+        ...(ctx.subagentRunId !== undefined && {
+          subagentRunId: ctx.subagentRunId,
+        }),
         chunk,
       })
       const current = runState.get(ctx)
diff --git a/packages/ai-persistence/src/subagent-runs.ts b/packages/ai-persistence/src/subagent-runs.ts
index 53c2e96530..f8bf0552fa 100644
--- a/packages/ai-persistence/src/subagent-runs.ts
+++ b/packages/ai-persistence/src/subagent-runs.ts
@@ -16,7 +16,7 @@ import type {
   UIMessage,
 } from '@tanstack/ai'
 import { mergeStoredMessages } from './merge-stored'
-import type { InterruptStore, MessageStore } from './types'
+import type { InterruptStore, MessageStore, SessionIndexStore } from './types'
 
 function withSubagentInfo(
   metadata: ModelMessage['metadata'],
@@ -37,6 +37,63 @@ function childStoreId(subagentRunId: string) {
   return `subagent:${subagentRunId}`
 }
 
+/**
+ * Head metadata key for what a later call of the child needs:
+ * - `base`: how many stored messages came before the current call. A resume
+ *   of that call keeps the number.
+ * - `parentThreadId`: the thread that started the child. Only that thread can
+ *   continue it.
+ * - `prompt`: the task of the first call, the first user message of the child.
+ */
+const CHILD_KEY = 'tanstack:subagentChild'
+
+function storedMarker(messages: ReadonlyArray<ModelMessage>) {
+  const marker: unknown = messages[0]?.metadata?.[CHILD_KEY]
+  const read = (key: string) =>
+    marker !== null && typeof marker === 'object'
+      ? Reflect.get(marker, key)
+      : undefined
+  const base = read('base')
+  const parentThreadId = read('parentThreadId')
+  const prompt = read('prompt')
+  return {
+    ...(typeof base === 'number' && { base }),
+    ...(typeof parentThreadId === 'string' && { parentThreadId }),
+    ...(typeof prompt === 'string' && { prompt }),
+  }
+}
+
+/** The thread a chat writes its children under: its own child thread, if any. */
+function ownerThread(caller: { threadId: string; subagentRunId?: string }) {
+  return caller.subagentRunId === undefined
+    ? caller.threadId
+    : childStoreId(caller.subagentRunId)
+}
+
+// ponytail: only the `subagent` tool has `prompt` and `input` fields. Core does
+// not export its name.
+const SINGLE_TOOL = 'subagent'
+
+/**
+ * The task of a child that a tool call started: the `prompt` of the `subagent`
+ * tool, else its `input` as JSON. Other tools pass their whole arguments.
+ */
+function callPrompt(call: { name: string; args: string }) {
+  if (call.args === '') return undefined
+  if (call.name !== SINGLE_TOOL) return call.args
+  let args: unknown
+  try {
+    args = JSON.parse(call.args)
+  } catch {
+    return call.args
+  }
+  if (args === null || typeof args !== 'object') return call.args
+  const prompt = Reflect.get(args, 'prompt')
+  if (typeof prompt === 'string') return prompt
+  const input = Reflect.get(args, 'input')
+  return input === undefined ? call.args : JSON.stringify(input)
+}
+
 function readSubagentRunId(chunk: StreamChunk) {
   if (!('subagentRunId' in chunk)) return
   const id = chunk.subagentRunId
@@ -287,6 +344,13 @@ export function storedSubagentInfo(
   return wireSubagentInfo(messages[0])
 }
 
+/** A stored child transcript without its card-only placeholder. */
+function withoutPlaceholder(messages: ReadonlyArray<ModelMessage>) {
+  return messages.filter(
+    (message) => storedSubagentInfo([message])?.placeholder !== true,
+  )
+}
+
 type ChildNote = {
   name: string
   /** The thread and run that feed this note now. */
@@ -303,12 +367,20 @@ type ChildNote = {
   interruptIds?: Array<string>
   error?: { message: string; code?: string }
   metadata?: Record<string, unknown>
+  /** Stored messages from before the current call. A resume keeps it. */
+  base: number
+  /** The thread that started this child. */
+  parentThreadId: string
+  /** The task of the first call. */
+  prompt?: string
 }
 
 export function createSubagentRunRecorder(stores: {
   messages: MessageStore
   runs?: RunStore
   interrupts?: InterruptStore
+  /** When present, each child gets a session index entry. */
+  sessions?: SessionIndexStore
   /** Minimum milliseconds between writes while a child streams. */
   intervalMs?: number
 }) {
@@ -320,6 +392,10 @@ export function createSubagentRunRecorder(stores: {
   // suspends. Dropped on abort.
   const answered = new Map<string, Array<RunAgentResumeItem>>()
   const parentSavedAt = new Map<string, number>()
+  // Name and arguments of each open tool call, by id. A child that a call
+  // starts reads its task from here. ponytail: a call that never gets a result
+  // or a child stays here, add a run-end sweep if that grows.
+  const calls = new Map<string, { name: string; args: string }>()
 
   async function loadMessages(threadId: string) {
     return stores.messages.loadThread(threadId)
@@ -360,14 +436,27 @@ export function createSubagentRunRecorder(stores: {
     const transcript = convertMessagesToModelMessages(
       withoutCards(note.processor.getMessages()),
     )
+    const marker = {
+      [CHILD_KEY]: {
+        base: note.base,
+        parentThreadId: note.parentThreadId,
+        ...(note.prompt !== undefined && { prompt: note.prompt }),
+      },
+    }
     const [first, ...rest] = transcript
     const head: ModelMessage = first
-      ? { ...first, metadata: withSubagentInfo(first.metadata, info) }
+      ? {
+          ...first,
+          metadata: { ...withSubagentInfo(first.metadata, info), ...marker },
+        }
       : {
           id: `child:${subagentRunId}`,
           role: 'assistant',
           content: '',
-          metadata: withSubagentInfo(undefined, { ...info, placeholder: true }),
+          metadata: {
+            ...withSubagentInfo(undefined, { ...info, placeholder: true }),
+            ...marker,
+          },
         }
     await stores.messages.saveThread(childStoreId(subagentRunId), [
       head,
@@ -427,10 +516,17 @@ export function createSubagentRunRecorder(stores: {
   }
 
   async function startChild(
-    input: { threadId: string; runId: string },
+    input: { threadId: string; runId: string; subagentRunId?: string },
     chunk: Extract<StreamChunk, { type: 'SUBAGENT_STARTED' }>,
   ) {
     const id = chunk.subagentRunId
+    const call =
+      chunk.parentToolCallId === undefined
+        ? undefined
+        : calls.get(chunk.parentToolCallId)
+    if (chunk.parentToolCallId !== undefined) {
+      calls.delete(chunk.parentToolCallId)
+    }
     const record = await stores.runs?.createOrResume({
       runId: id,
       threadId: childStoreId(id),
@@ -447,10 +543,16 @@ export function createSubagentRunRecorder(stores: {
       delete existing.interruptIds
       if (chunk.metadata !== undefined) existing.metadata = chunk.metadata
     } else {
-      // A resume continues the stored transcript.
-      const stored = (await loadMessages(childStoreId(id))).filter(
-        (message) => storedSubagentInfo([message])?.placeholder !== true,
-      )
+      // A resume or a continue goes on from the stored transcript.
+      const raw = await loadMessages(childStoreId(id))
+      const stored = withoutPlaceholder(raw)
+      const marker = storedMarker(raw)
+      // A resume keeps the base of the call it resumes. A new call starts
+      // after the whole stored transcript.
+      const resumes = storedSubagentInfo(raw)?.status === 'suspended'
+      // Only the first call gives the prompt. A later call keeps it.
+      const prompt =
+        raw.length > 0 ? marker.prompt : call && callPrompt(call)
       children.set(id, {
         name: chunk.name,
         threadId: input.threadId,
@@ -470,6 +572,13 @@ export function createSubagentRunRecorder(stores: {
           initialMessages: modelMessagesToUIMessages(stored),
         }),
         status: 'running',
+        base: resumes ? (marker.base ?? 0) : stored.length,
+        // A nested child belongs to the thread of the child that started it.
+        parentThreadId: ownerThread({
+          threadId: input.threadId,
+          subagentRunId: chunk.parentSubagentRunId ?? input.subagentRunId,
+        }),
+        ...(prompt !== undefined && { prompt }),
       })
     }
     if (record && record.status !== 'running') {
@@ -480,6 +589,65 @@ export function createSubagentRunRecorder(stores: {
       children.get(chunk.parentSubagentRunId)?.processor.processChunk(chunk)
     }
     await saveChild(id)
+    const note = children.get(id)
+    if (stores.sessions && note) await indexChild(stores.sessions, id, note)
+  }
+
+  // One index entry per child. `upsert` replaces the whole entry, so keep the
+  // fields that other writers set, like a title.
+  async function indexChild(
+    sessions: SessionIndexStore,
+    subagentRunId: string,
+    note: ChildNote,
+  ) {
+    const childThreadId = childStoreId(subagentRunId)
+    const current = await sessions.get(childThreadId)
+    const now = Date.now()
+    await sessions.upsert({
+      ...current,
+      threadId: childThreadId,
+      parentThreadId: note.parentThreadId,
+      ...(note.parentToolCallId !== undefined && {
+        parentToolCallId: note.parentToolCallId,
+      }),
+      createdAt: current?.createdAt ?? now,
+      updatedAt: now,
+    })
+  }
+
+  /**
+   * The stored transcript of a child, for a call that continues it by
+   * `sessionId`. It starts with the task of the first call as a user message.
+   * `undefined` when `caller` did not start a child with this id. While the
+   * child waits on an interrupt, it is the transcript from before that call:
+   * the resume adds the newer messages of the child itself.
+   */
+  async function loadChild(
+    subagentRunId: string,
+    caller: { threadId: string; subagentRunId?: string },
+  ) {
+    const stored = await loadMessages(childStoreId(subagentRunId))
+    const marker = storedMarker(stored)
+    // The id can come from a prompt injection. Never load the child of an
+    // other thread.
+    if (marker.parentThreadId !== ownerThread(caller)) return undefined
+    const messages = withoutPlaceholder(stored)
+    const waits = storedSubagentInfo(stored)?.status === 'suspended'
+    const transcript =
+      waits && marker.base !== undefined
+        ? messages.slice(0, marker.base)
+        : messages
+    const task: Array<ModelMessage> =
+      marker.prompt === undefined
+        ? []
+        : [
+            {
+              id: `${childStoreId(subagentRunId)}:prompt`,
+              role: 'user',
+              content: marker.prompt,
+            },
+          ]
+    return { messages: [...task, ...transcript] }
   }
 
   async function settleChild(
@@ -594,6 +762,8 @@ export function createSubagentRunRecorder(stores: {
   }
 
   return {
+    loadChild,
+
     async start(input: {
       threadId: string
       runId: string
@@ -649,9 +819,19 @@ export function createSubagentRunRecorder(stores: {
     async chunk(input: {
       threadId: string
       runId: string
+      /** Set when the chat that streams this chunk is a child itself. */
+      subagentRunId?: string
       chunk: StreamChunk
     }) {
       const chunk = input.chunk
+      if (chunk.type === 'TOOL_CALL_START') {
+        calls.set(chunk.toolCallId, { name: chunk.toolCallName, args: '' })
+      }
+      if (chunk.type === 'TOOL_CALL_ARGS') {
+        const call = calls.get(chunk.toolCallId)
+        if (call) call.args += chunk.delta
+      }
+      if (chunk.type === 'TOOL_CALL_RESULT') calls.delete(chunk.toolCallId)
       if (chunk.type === 'SUBAGENT_STARTED') {
         await startChild(input, chunk)
         return
diff --git a/packages/ai-persistence/src/testkit/conformance.ts b/packages/ai-persistence/src/testkit/conformance.ts
index 6db6f3824f..97eb0f81d1 100644
--- a/packages/ai-persistence/src/testkit/conformance.ts
+++ b/packages/ai-persistence/src/testkit/conformance.ts
@@ -45,6 +45,8 @@ import type {
   ArtifactRecord,
   LogStore,
   RunStore,
+  SessionIndexEntry,
+  SessionIndexPage,
 } from '../types'
 
 type MakePersistence = () => Promise<AIPersistence> | AIPersistence
@@ -1792,6 +1794,186 @@ export function runPersistenceConformance(
       })
     })
 
+    // The session index is opt-in: only harness hosts read it. A backend
+    // without it skips these cases and needs no `skip` entry. Each case uses
+    // its own ids, because the suite shares one persistence.
+    describe('sessions', () => {
+      const newId = () => `sessions-${crypto.randomUUID()}`
+      const sessionEntry = (
+        threadId: string,
+        updatedAt: number,
+        extra: Partial<SessionIndexEntry> = {},
+      ) => ({ threadId, createdAt: 1, updatedAt, ...extra })
+      const threadIds = (page: SessionIndexPage) =>
+        page.entries.map((entry) => entry.threadId)
+
+      it('gets every field of an upserted entry, and undefined for an unknown thread', async (ctx) => {
+        const store = persistence.stores.sessions
+        if (!store) return ctx.skip('sessions store not provided')
+        const threadId = newId()
+        const written: SessionIndexEntry = {
+          threadId,
+          harness: 'coder',
+          title: 'Fix the build',
+          parentThreadId: `${threadId}-parent`,
+          parentToolCallId: 'call-1',
+          createdAt: 1,
+          updatedAt: 2,
+          pinned: true,
+          principal: { id: 'user-1', tenantId: 'org-1' },
+          usage: {
+            turns: 2,
+            promptTokens: 10,
+            completionTokens: 5,
+            totalTokens: 15,
+            cachedTokens: 4,
+            cacheWriteTokens: 1,
+            cost: 0.25,
+          },
+          metadata: { model: 'm-1' },
+        }
+
+        await store.upsert(written)
+
+        expect(await store.get(threadId)).toEqual(written)
+        expect(await store.get(newId())).toBeUndefined()
+      })
+
+      it('replaces the whole entry on a second upsert', async (ctx) => {
+        const store = persistence.stores.sessions
+        if (!store) return ctx.skip('sessions store not provided')
+        const threadId = newId()
+        await store.upsert(
+          sessionEntry(threadId, 2, { title: 'old', pinned: true }),
+        )
+
+        await store.upsert(sessionEntry(threadId, 3, { title: 'new' }))
+
+        // `pinned` is gone: upsert does not merge.
+        expect(await store.get(threadId)).toEqual({
+          threadId,
+          createdAt: 1,
+          updatedAt: 3,
+          title: 'new',
+        })
+      })
+
+      it('lists newest first and pages with a cursor', async (ctx) => {
+        const store = persistence.stores.sessions
+        if (!store) return ctx.skip('sessions store not provided')
+        const owner = { id: newId() }
+        const a = `${owner.id}-a`
+        const b = `${owner.id}-b`
+        const c = `${owner.id}-c`
+        await store.upsert(sessionEntry(c, 20, { principal: owner }))
+        await store.upsert(sessionEntry(a, 30, { principal: owner }))
+        await store.upsert(sessionEntry(b, 20, { principal: owner }))
+
+        // Newest first. The same `updatedAt` goes in `threadId` order.
+        expect(threadIds(await store.list({ principal: owner }))).toEqual([
+          a,
+          b,
+          c,
+        ])
+
+        const first = await store.list({ principal: owner, limit: 2 })
+        expect(threadIds(first)).toEqual([a, b])
+        expect(first.truncated).toBe(true)
+
+        const second = await store.list({
+          principal: owner,
+          limit: 2,
+          cursor: required(first.cursor, 'the cursor of a truncated page'),
+        })
+        expect(threadIds(second)).toEqual([c])
+        expect(second.truncated).toBeFalsy()
+        expect(second.cursor).toBeUndefined()
+      })
+
+      it('filters by parent thread and by owner', async (ctx) => {
+        const store = persistence.stores.sessions
+        if (!store) return ctx.skip('sessions store not provided')
+        const prefix = newId()
+        const owner = { id: `${prefix}-user`, tenantId: 'org-1' }
+        const parent = `${prefix}-parent`
+        const child = `${prefix}-child`
+        const unowned = `${prefix}-unowned`
+        const otherTenant = `${prefix}-other-tenant`
+        await store.upsert(sessionEntry(parent, 10, { principal: owner }))
+        await store.upsert(
+          sessionEntry(child, 20, {
+            principal: owner,
+            parentThreadId: parent,
+            parentToolCallId: 'call-1',
+          }),
+        )
+        await store.upsert(
+          sessionEntry(unowned, 30, { parentThreadId: parent }),
+        )
+        await store.upsert(
+          sessionEntry(otherTenant, 40, {
+            principal: { id: owner.id, tenantId: 'org-2' },
+          }),
+        )
+
+        expect(threadIds(await store.list({ parentThreadId: parent }))).toEqual(
+          [unowned, child],
+        )
+        // With a tenant, the tenant must match. An entry without an owner
+        // never matches.
+        expect(threadIds(await store.list({ principal: owner }))).toEqual([
+          child,
+          parent,
+        ])
+        // Without a tenant, the id alone decides.
+        expect(
+          threadIds(await store.list({ principal: { id: owner.id } })),
+        ).toEqual([otherTenant, child, parent])
+        expect(
+          threadIds(
+            await store.list({
+              principal: { id: `${prefix}-nobody` },
+              parentThreadId: parent,
+            }),
+          ),
+        ).toEqual([])
+      })
+
+      it('lists only the entries with no parent for parentThreadId null', async (ctx) => {
+        const store = persistence.stores.sessions
+        if (!store) return ctx.skip('sessions store not provided')
+        const owner = { id: newId() }
+        const parent = `${owner.id}-parent`
+        const child = `${owner.id}-child`
+        await store.upsert(sessionEntry(parent, 10, { principal: owner }))
+        await store.upsert(
+          sessionEntry(child, 20, { principal: owner, parentThreadId: parent }),
+        )
+
+        expect(
+          threadIds(await store.list({ principal: owner, parentThreadId: null })),
+        ).toEqual([parent])
+      })
+
+      it('deletes an entry, and ignores an unknown thread', async (ctx) => {
+        const store = persistence.stores.sessions
+        if (!store) return ctx.skip('sessions store not provided')
+        const owner = { id: newId() }
+        const kept = `${owner.id}-kept`
+        const removed = `${owner.id}-removed`
+        await store.upsert(sessionEntry(kept, 1, { principal: owner }))
+        await store.upsert(sessionEntry(removed, 2, { principal: owner }))
+
+        await store.delete(removed)
+        await store.delete(newId())
+
+        expect(await store.get(removed)).toBeUndefined()
+        expect(threadIds(await store.list({ principal: owner }))).toEqual([
+          kept,
+        ])
+      })
+    })
+
     describe('metadata', () => {
       it('sets, gets, namespaces, and deletes without composite-key collisions', async (ctx) => {
         const store = resolveStore('metadata')
diff --git a/packages/ai-persistence/src/types.ts b/packages/ai-persistence/src/types.ts
index 55009716a1..f344a8f5f8 100644
--- a/packages/ai-persistence/src/types.ts
+++ b/packages/ai-persistence/src/types.ts
@@ -505,6 +505,119 @@ export function defineLogStore(store: LogStore): LogStore {
   return store
 }
 
+/**
+ * One entry of the session index: what a list of sessions shows for one
+ * thread. The index holds no messages. The thread data stays in the stores
+ * that hold it.
+ *
+ * @property createdAt - Epoch ms when the thread was first opened.
+ * @property updatedAt - Epoch ms of the last change. {@link SessionIndexStore.list}
+ *   sorts by it.
+ */
+export interface SessionIndexEntry {
+  threadId: string
+  /** The `name` of the harness that runs the thread. */
+  harness?: string
+  title?: string
+  /**
+   * The thread that started this one. A subagent child has the thread id
+   * `subagent:<runId>` and the thread of its parent here.
+   */
+  parentThreadId?: string
+  /** The tool call in the parent thread that started this thread. */
+  parentToolCallId?: string
+  createdAt: number
+  updatedAt: number
+  pinned?: boolean
+  /** Who owns the thread, from the host's `authorize`. */
+  principal?: { id: string; tenantId?: string }
+  /**
+   * Token totals of the thread. The names match the totals of the harness
+   * `usage()` plugin.
+   */
+  usage?: {
+    /** Model calls. */
+    turns: number
+    promptTokens: number
+    completionTokens: number
+    totalTokens: number
+    /** Input tokens the provider read from its prompt cache. */
+    cachedTokens: number
+    /** Input tokens the provider wrote to its prompt cache. */
+    cacheWriteTokens: number
+    /** Cost in USD, when a plugin counts it. */
+    cost?: number
+  }
+  metadata?: Record<string, unknown>
+}
+
+/** Options for {@link SessionIndexStore.list}. */
+export interface SessionIndexListOptions {
+  /** The most entries in one page. Without it, the page has all entries. */
+  limit?: number
+  /** The `cursor` of the previous page. */
+  cursor?: string
+  /**
+   * Only the entries whose `parentThreadId` is this thread. `null`: only the
+   * entries with no parent (the top-level sessions).
+   */
+  parentThreadId?: string | null
+  /**
+   * Only the entries owned by this principal id. With `tenantId`, the
+   * tenant must match too. An entry without a principal never matches.
+   */
+  principal?: { id: string; tenantId?: string }
+}
+
+/**
+ * One page of a {@link SessionIndexStore.list} scan.
+ *
+ * @property cursor - The token for the next page. Only when `truncated`.
+ * @property truncated - `true` when more entries match after this page.
+ */
+export interface SessionIndexPage {
+  entries: Array<SessionIndexEntry>
+  cursor?: string
+  truncated?: boolean
+}
+
+/** Durable index of harness sessions, one entry per thread. */
+export interface SessionIndexStore {
+  /**
+   * Write the entry for `entry.threadId`.
+   *
+   * INVARIANT (full replace): a second upsert for the same thread replaces
+   * the whole entry. A field that the new entry does not have is gone. To
+   * change one field, `get` the entry and upsert a changed copy.
+   */
+  upsert: (entry: SessionIndexEntry) => Promise<void>
+  /** The entry for `threadId`, or `undefined`. */
+  get: (threadId: string) => Promise<SessionIndexEntry | undefined>
+  /**
+   * The entries that match the filters, newest `updatedAt` first. Entries with
+   * the same `updatedAt` are in `threadId` order. Pinned entries get no
+   * special place.
+   *
+   * CURSOR SEMANTICS: when `limit` is given and more entries match, the page
+   * is `truncated: true` with a `cursor`. Pass that `cursor` back to get the
+   * entries that follow the last entry of the page. An entry that changes
+   * between two pages can move in the order.
+   */
+  list: (options?: SessionIndexListOptions) => Promise<SessionIndexPage>
+  /**
+   * Remove the index entry for `threadId`. A no-op for an unknown id.
+   *
+   * This removes the entry only. The messages, the log, and the other data of
+   * the thread stay. The stores that hold that data remove it.
+   */
+  delete: (threadId: string) => Promise<void>
+}
+
+/** Type a {@link SessionIndexStore} implementation inline. */
+export function defineSessionIndexStore(store: SessionIndexStore) {
+  return store
+}
+
 /** A secret a user or an organization saved: an API key or OAuth tokens. */
 export type Credential =
   | { type: 'api_key'; value: string }
@@ -841,6 +954,8 @@ export interface AIPersistenceStores {
   log?: LogStore
   /** Turn leases. Optional: only durable harness hosts read it. */
   leases?: LeaseStore
+  /** The session index. Optional: only harness hosts read it. */
+  sessions?: SessionIndexStore
 }
 
 /**
@@ -1020,6 +1135,7 @@ const storeKeys = [
   'credentials',
   'log',
   'leases',
+  'sessions',
 ] satisfies Array<StoreKey>
 
 const storeKeySet = new Set<string>(storeKeys)
diff --git a/packages/ai-persistence/tests/memory.test.ts b/packages/ai-persistence/tests/memory.test.ts
index bf9aa03e61..8664716930 100644
--- a/packages/ai-persistence/tests/memory.test.ts
+++ b/packages/ai-persistence/tests/memory.test.ts
@@ -22,6 +22,7 @@ describe('memoryPersistence', () => {
       'messages',
       'metadata',
       'runs',
+      'sessions',
     ])
   })
 
diff --git a/packages/ai-persistence/tests/persistence-types.test-d.ts b/packages/ai-persistence/tests/persistence-types.test-d.ts
index d77673e7e6..87fb937d6c 100644
--- a/packages/ai-persistence/tests/persistence-types.test-d.ts
+++ b/packages/ai-persistence/tests/persistence-types.test-d.ts
@@ -28,6 +28,7 @@ import type {
   MessageStore,
   MetadataStore,
   RunStore,
+  SessionIndexStore,
 } from '../src'
 
 declare const messages: MessageStore
@@ -143,6 +144,7 @@ expectTypeOf(memoryPersistence()).toEqualTypeOf<
     blobs: BlobStore
     inbox: InboxStore
     credentials: CredentialStore
+    sessions: SessionIndexStore
   }>
 >()
 const transcript: ChatTranscriptPersistence = messagesOnly
diff --git a/packages/ai-persistence/tests/persistence-validation.test.ts b/packages/ai-persistence/tests/persistence-validation.test.ts
index 24c7614c63..f729ad5665 100644
--- a/packages/ai-persistence/tests/persistence-validation.test.ts
+++ b/packages/ai-persistence/tests/persistence-validation.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest'
+import { memoryPersistence } from '../src/memory'
 import { withGenerationPersistence, withPersistence } from '../src/middleware'
 import { reconstructChat } from '../src/reconstruct'
 import { defineAIPersistence } from '../src/types'
@@ -107,4 +108,10 @@ describe('persistence store dependency validation', () => {
 
     expect(() => defineAIPersistence({ stores: { leases } })).not.toThrow()
   })
+
+  it('accepts a session index store', () => {
+    const { sessions } = memoryPersistence().stores
+
+    expect(() => defineAIPersistence({ stores: { sessions } })).not.toThrow()
+  })
 })
diff --git a/packages/ai-persistence/tests/subagent-persistence-cards.test.ts b/packages/ai-persistence/tests/subagent-persistence-cards.test.ts
index 8cea000461..d2d51b80ec 100644
--- a/packages/ai-persistence/tests/subagent-persistence-cards.test.ts
+++ b/packages/ai-persistence/tests/subagent-persistence-cards.test.ts
@@ -2,6 +2,8 @@ import { describe, expect, it, vi } from 'vitest'
 import { EventType, chat, defineAgent, uiMessagesToWire } from '@tanstack/ai'
 import type {
   AnyTextAdapter,
+  ChatMiddleware,
+  DefinedAgent,
   ModelMessage,
   StreamChunk,
   SubagentPart,
@@ -152,6 +154,151 @@ async function collect(stream: AsyncIterable<StreamChunk>) {
   return chunks
 }
 
+/** One text message, start to end. */
+function textMessage(
+  messageId: string,
+  text: string,
+  ids: { subagentRunId?: string } = {},
+) {
+  return [
+    {
+      type: EventType.TEXT_MESSAGE_START,
+      messageId,
+      role: 'assistant',
+      ...ids,
+      timestamp: t,
+    },
+    {
+      type: EventType.TEXT_MESSAGE_CONTENT,
+      messageId,
+      delta: text,
+      ...ids,
+      timestamp: t,
+    },
+    { type: EventType.TEXT_MESSAGE_END, messageId, ...ids, timestamp: t },
+  ] satisfies Array<StreamChunk>
+}
+
+/** A child start, as the parent stream carries it. */
+function childStarted(
+  subagentRunId: string,
+  links: { parentToolCallId?: string; parentSubagentRunId?: string },
+) {
+  return {
+    type: EventType.SUBAGENT_STARTED,
+    subagentRunId,
+    name: 'writer',
+    ...links,
+    timestamp: t,
+  } satisfies StreamChunk
+}
+
+/** Feed one parent run's chunks on thread `desk` to a recorder. */
+async function feed(
+  recorder: ReturnType<typeof createSubagentRunRecorder>,
+  runId: string,
+  chunks: ReadonlyArray<StreamChunk>,
+) {
+  for (const chunk of chunks) {
+    await recorder.chunk({ threadId: 'desk', runId, chunk })
+  }
+}
+
+/** A child that writes one note per call and keeps the messages it saw. */
+function noteTaker() {
+  const seen: Array<ReadonlyArray<UIMessage | ModelMessage>> = []
+  const agent = defineAgent({
+    name: 'writer',
+    description: 'Writes notes',
+    run: async function* (ctx) {
+      seen.push(ctx.messages)
+      yield* textMessage(`note-${seen.length}`, `Note ${seen.length}`)
+    },
+  })
+  return { agent, seen }
+}
+
+/** A parent model that calls the `subagent` tool once, then stops. */
+function callingSubagent(toolCallId: string, args: object) {
+  return scriptedAdapter([
+    [
+      {
+        type: EventType.TOOL_CALL_START,
+        toolCallId,
+        toolCallName: 'subagent',
+        timestamp: t,
+      },
+      {
+        type: EventType.TOOL_CALL_ARGS,
+        toolCallId,
+        delta: JSON.stringify(args),
+        timestamp: t,
+      },
+      {
+        type: EventType.RUN_FINISHED,
+        runId: 'model',
+        threadId: 'desk',
+        finishReason: 'tool_calls',
+        timestamp: t,
+      },
+    ],
+    [
+      {
+        type: EventType.RUN_FINISHED,
+        runId: 'model',
+        threadId: 'desk',
+        finishReason: 'stop',
+        timestamp: t,
+      },
+    ],
+  ])
+}
+
+/** One parent turn with the single `subagent` tool. The thread is `desk`. */
+function subagentTurn(
+  middleware: ChatMiddleware,
+  agent: DefinedAgent,
+  turn: { runId: string; toolCallId: string; args: object; threadId?: string },
+) {
+  return collect(
+    chat({
+      adapter: callingSubagent(turn.toolCallId, turn.args),
+      threadId: turn.threadId ?? 'desk',
+      runId: turn.runId,
+      messages: [{ id: `u-${turn.runId}`, role: 'user', content: 'Notes' }],
+      middleware: [middleware],
+      subagents: { agents: [agent], tool: 'single' },
+    }),
+  )
+}
+
+/** The id of the first child a run started. */
+function startedId(chunks: ReadonlyArray<StreamChunk>) {
+  const started = chunks.find(
+    (chunk) => chunk.type === EventType.SUBAGENT_STARTED,
+  )
+  if (started?.type !== EventType.SUBAGENT_STARTED) {
+    throw new Error('no child started')
+  }
+  return started.subagentRunId
+}
+
+/** The parsed result of one tool call. */
+function toolResult(chunks: ReadonlyArray<StreamChunk>, toolCallId: string) {
+  const result = chunks.find(
+    (chunk) =>
+      chunk.type === EventType.TOOL_CALL_RESULT &&
+      chunk.toolCallId === toolCallId,
+  )
+  if (
+    result?.type !== EventType.TOOL_CALL_RESULT ||
+    typeof result.content !== 'string'
+  ) {
+    throw new Error(`no text result for ${toolCallId}`)
+  }
+  return JSON.parse(result.content)
+}
+
 describe('persisted subagent cards', () => {
   it('keeps reasoning, tool calls, and interrupts across a reload', async () => {
     const persistence = memoryPersistence()
@@ -439,6 +586,221 @@ describe('subagent run recorder', () => {
     expect(second).toContain('second thread notes')
     expect(second).not.toContain('first thread notes')
   })
+
+  it('gives a nested child to the child that started it', async () => {
+    const { stores } = memoryPersistence()
+    const recorder = createSubagentRunRecorder({
+      messages: stores.messages,
+      sessions: stores.sessions,
+      intervalMs: 0,
+    })
+    await feed(recorder, 'run-1', [
+      childStarted('outer', { parentToolCallId: 'call_1' }),
+      childStarted('inner', {
+        parentSubagentRunId: 'outer',
+        parentToolCallId: 'call_n',
+      }),
+      ...textMessage('m1', 'Inner notes', { subagentRunId: 'inner' }),
+    ])
+
+    expect(await stores.sessions.get('subagent:inner')).toMatchObject({
+      parentThreadId: 'subagent:outer',
+      parentToolCallId: 'call_n',
+    })
+    // The outer child's chat can continue it. The top thread cannot.
+    const fromOuter = { threadId: 'desk:writer', subagentRunId: 'outer' }
+    expect((await recorder.loadChild('inner', fromOuter))?.messages).toEqual([
+      expect.objectContaining({ role: 'assistant', content: 'Inner notes' }),
+    ])
+    expect(
+      await recorder.loadChild('inner', { threadId: 'desk' }),
+    ).toBeUndefined()
+  })
+
+  it('loads a waiting continued child without the messages of the call it waits in', async () => {
+    const { stores } = memoryPersistence()
+    const recorder = createSubagentRunRecorder({
+      messages: stores.messages,
+      runs: stores.runs,
+      intervalMs: 0,
+    })
+    const waiting = {
+      type: EventType.SUBAGENT_FINISHED,
+      subagentRunId: 'child',
+      outcome: { type: 'suspended', interruptIds: ['approval'] },
+      timestamp: t,
+    } satisfies StreamChunk
+    const old = [{ role: 'assistant', content: 'Old notes' }]
+    await feed(recorder, 'run-1', [
+      childStarted('child', { parentToolCallId: 'call_1' }),
+      ...textMessage('m1', 'Old notes', { subagentRunId: 'child' }),
+      { type: EventType.SUBAGENT_FINISHED, subagentRunId: 'child', timestamp: t },
+    ])
+
+    // run-2 continues the child. It writes, then waits for an approval. The
+    // resume brings those newer messages itself.
+    await feed(recorder, 'run-2', [
+      childStarted('child', { parentToolCallId: 'call_2' }),
+      ...textMessage('m2', 'Delete a?', { subagentRunId: 'child' }),
+      waiting,
+    ])
+    const desk = { threadId: 'desk' }
+    expect((await recorder.loadChild('child', desk))?.messages).toMatchObject(
+      old,
+    )
+
+    // run-3 resumes that call, and the child waits again.
+    await feed(recorder, 'run-3', [
+      childStarted('child', { parentToolCallId: 'call_2' }),
+      ...textMessage('m3', 'Delete b?', { subagentRunId: 'child' }),
+      waiting,
+    ])
+    expect((await recorder.loadChild('child', desk))?.messages).toMatchObject(
+      old,
+    )
+  })
+
+  it('starts a loaded child with the task of its first call', async () => {
+    const { stores } = memoryPersistence()
+    const recorder = createSubagentRunRecorder({
+      messages: stores.messages,
+      intervalMs: 0,
+    })
+    await feed(recorder, 'run-1', [
+      {
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 'call_1',
+        toolCallName: 'subagent',
+        timestamp: t,
+      },
+      {
+        type: EventType.TOOL_CALL_ARGS,
+        toolCallId: 'call_1',
+        delta: '{"agent":"writer","input":{"topic":"tides"}}',
+        timestamp: t,
+      },
+      childStarted('child', { parentToolCallId: 'call_1' }),
+      ...textMessage('m1', 'Tide notes', { subagentRunId: 'child' }),
+    ])
+
+    expect(
+      (await recorder.loadChild('child', { threadId: 'desk' }))?.messages,
+    ).toMatchObject([
+      { role: 'user', content: '{"topic":"tides"}' },
+      { role: 'assistant', content: 'Tide notes' },
+    ])
+  })
+
+  it('loads nothing for an unknown child', async () => {
+    const { stores } = memoryPersistence()
+    const recorder = createSubagentRunRecorder({ messages: stores.messages })
+
+    expect(
+      await recorder.loadChild('missing', { threadId: 'desk' }),
+    ).toBeUndefined()
+  })
+})
+
+describe('single subagent tool with persistence', () => {
+  it('writes one index entry per child and keeps fields others wrote', async () => {
+    const persistence = memoryPersistence()
+    const middleware = withPersistence(persistence)
+    const sessions = persistence.stores.sessions
+    const { agent } = noteTaker()
+    const first = await subagentTurn(middleware, agent, {
+      runId: 'run-1',
+      toolCallId: 'call_1',
+      args: { agent: 'writer', prompt: 'Take notes' },
+    })
+    const threadId = `subagent:${startedId(first)}`
+    const entry = await sessions.get(threadId)
+    expect(entry).toEqual({
+      threadId,
+      parentThreadId: 'desk',
+      parentToolCallId: 'call_1',
+      createdAt: expect.any(Number),
+      updatedAt: expect.any(Number),
+    })
+    if (!entry) throw new Error('no index entry')
+
+    // Another writer names the session. A continue keeps the name.
+    await sessions.upsert({ ...entry, title: 'Tide notes' })
+    await subagentTurn(middleware, agent, {
+      runId: 'run-2',
+      toolCallId: 'call_2',
+      args: { agent: 'writer', sessionId: startedId(first), prompt: 'More' },
+    })
+    expect(await sessions.get(threadId)).toEqual({
+      threadId,
+      title: 'Tide notes',
+      parentThreadId: 'desk',
+      parentToolCallId: 'call_2',
+      createdAt: entry.createdAt,
+      updatedAt: expect.any(Number),
+    })
+  })
+
+  const setups: Array<[string, () => ChatMiddleware]> = [
+    ['with', () => withPersistence(memoryPersistence())],
+    [
+      'without',
+      () => {
+        const { messages, runs, interrupts, metadata } =
+          memoryPersistence().stores
+        return withPersistence({
+          stores: { messages, runs, interrupts, metadata },
+        })
+      },
+    ],
+  ]
+  it.each(setups)(
+    'continues a stored child by sessionId %s a sessions store',
+    async (_label, persist) => {
+      const middleware = persist()
+      const { agent, seen } = noteTaker()
+      const first = await subagentTurn(middleware, agent, {
+        runId: 'run-1',
+        toolCallId: 'call_1',
+        args: { agent: 'writer', prompt: 'Take notes' },
+      })
+      const second = await subagentTurn(middleware, agent, {
+        runId: 'run-2',
+        toolCallId: 'call_2',
+        args: { agent: 'writer', sessionId: startedId(first), prompt: 'More' },
+      })
+
+      expect(startedId(second)).toBe(startedId(first))
+      // The child starts from its first task and its stored transcript, then
+      // the new prompt. The first message is a user message.
+      expect(seen[1]).toMatchObject([
+        { role: 'user', content: 'Take notes' },
+        { role: 'assistant', content: 'Note 1' },
+        { role: 'user', content: 'More' },
+      ])
+    },
+  )
+
+  it('does not continue a child of another thread', async () => {
+    const middleware = withPersistence(memoryPersistence())
+    const { agent, seen } = noteTaker()
+    const first = await subagentTurn(middleware, agent, {
+      runId: 'run-1',
+      toolCallId: 'call_1',
+      args: { agent: 'writer', prompt: 'Take notes' },
+    })
+    const id = startedId(first)
+    const other = await subagentTurn(middleware, agent, {
+      threadId: 'other',
+      runId: 'run-2',
+      toolCallId: 'call_2',
+      args: { agent: 'writer', sessionId: id, prompt: 'Show me' },
+    })
+
+    expect(toolResult(other, 'call_2')).toEqual({
+      error: `Unknown sessionId "${id}".`,
+    })
+    expect(seen).toHaveLength(1)
+  })
 })
 
 describe('host ownership collisions', () => {
diff --git a/packages/ai/skills/ai-core/middleware/SKILL.md b/packages/ai/skills/ai-core/middleware/SKILL.md
index ca168fd1f5..f9972a4116 100644
--- a/packages/ai/skills/ai-core/middleware/SKILL.md
+++ b/packages/ai/skills/ai-core/middleware/SKILL.md
@@ -66,7 +66,7 @@ Every hook receives a `ChatMiddlewareContext` as its first argument, which provi
 | `onShouldContinue`         | Whether to start another agent-loop iteration (AND with strategy; `false` stops)                         | `AgentLoopState`                                    |
 | `onChunk`                  | Every streamed chunk                                                                                     | `StreamChunk` (return void/chunk/chunk[]/null)      |
 | `onBeforeToolCall`         | Before each tool executes                                                                                | `ToolCallHookContext` (return decision or void)     |
-| `onAfterToolCall`          | After each tool executes                                                                                 | `AfterToolCallInfo`                                 |
+| `onAfterToolCall`          | After each tool executes                                                                                 | `AfterToolCallInfo` (return decision or void)       |
 | `onToolPhaseComplete`      | After all tool calls in an iteration                                                                     | `ToolPhaseCompleteInfo`                             |
 | `onUsage`                  | When `RUN_FINISHED` includes usage data                                                                  | `UsageInfo`                                         |
 | `onFinish`                 | Run completed normally                                                                                   | `FinishInfo`                                        |
@@ -235,7 +235,7 @@ export async function POST(request: Request) {
 ### Pattern 2: Tool Interception Middleware
 
 Use `onBeforeToolCall` to validate, gate, or transform tool arguments before execution.
-Use `onAfterToolCall` to log results and timing. The first middleware that returns a
+Use `onAfterToolCall` to log results and timing, or to replace the result. The first middleware that returns a
 non-void decision from `onBeforeToolCall` short-circuits remaining middleware for that call.
 
 ```typescript
@@ -285,6 +285,35 @@ const toolGuard: ChatMiddleware = {
 | `{ type: 'skip', result }`        | Skip execution, use provided result (used by `toolCacheMiddleware`) |
 | `{ type: 'abort', reason? }`      | Abort the entire chat run                                           |
 
+**`onAfterToolCall` decision:** return `{ type: 'replaceResult', result }` to
+change the result that the model and the stream see. Return void to keep it.
+
+- Middleware run in order. Each one gets the result of the one before it as
+  `info.result`.
+- A replaced error result stays an error.
+- On a failed call, `info.result` is unset until a middleware replaces it.
+  Read `info.error`.
+
+```typescript
+import type { ChatMiddleware } from '@tanstack/ai'
+
+const MAX_CHARS = 2000
+
+const shortToolOutput: ChatMiddleware = {
+  name: 'short-tool-output',
+  onAfterToolCall: (ctx, info) => {
+    if (typeof info.result !== 'string' || info.result.length <= MAX_CHARS) {
+      return
+    }
+    const cut = info.result.length - MAX_CHARS
+    return {
+      type: 'replaceResult',
+      result: `${info.result.slice(0, MAX_CHARS)}\n[${cut} more characters cut]`,
+    }
+  },
+}
+```
+
 ### Pattern 3: Structured-Output Middleware
 
 On the separate-finalization path, the final structured-output adapter call
@@ -416,7 +445,7 @@ export async function POST(request: Request) {
 | `onStart`                  | Sequential                                    | All run in order                           |
 | `onChunk`                  | **Piped** -- chunks flow through each         | If first drops a chunk, later never see it |
 | `onBeforeToolCall`         | **First-win** -- first non-void decision wins | Earlier middleware has priority            |
-| `onAfterToolCall`          | Sequential                                    | All run in order                           |
+| `onAfterToolCall`          | **Piped** -- each receives previous result    | Earlier middleware replaces first          |
 | `onUsage`                  | Sequential                                    | All run in order                           |
 | `onFinish/onAbort/onError` | Sequential                                    | All run in order                           |
 
diff --git a/packages/ai/src/activities/chat/agents/bound.ts b/packages/ai/src/activities/chat/agents/bound.ts
index c73117bc3e..f1041acda7 100644
--- a/packages/ai/src/activities/chat/agents/bound.ts
+++ b/packages/ai/src/activities/chat/agents/bound.ts
@@ -66,6 +66,21 @@ export interface SubagentBinding {
    * uses it when the call gives no `promptCache`.
    */
   promptCache?: PromptCacheRetention
+  /**
+   * Starts a child without waiting for it and returns its id at once. The
+   * single `subagent` tool calls it for `background: true`. With
+   * `wake: true`, the host starts a new parent turn when the child ends. A
+   * harness session sets it. It does not pass down to nested children.
+   */
+  start?: (
+    call: {
+      agent: string
+      input?: unknown
+      prompt?: string
+      parentToolCallId?: string
+    },
+    options: { wake: true },
+  ) => Promise<{ subagentRunId: string }>
 }
 
 /**
diff --git a/packages/ai/src/activities/chat/agents/spawn.ts b/packages/ai/src/activities/chat/agents/spawn.ts
index af147aafa5..140cff91b8 100644
--- a/packages/ai/src/activities/chat/agents/spawn.ts
+++ b/packages/ai/src/activities/chat/agents/spawn.ts
@@ -12,10 +12,16 @@ import {
 import { mergeStreams } from '../../../utilities/merge-streams'
 import { INTERRUPT_BINDING_METADATA_KEY } from '../../../interrupt-resume'
 import { EMIT_STREAM_CHUNK, SUBAGENT_TOOL } from '../tools/tool-calls'
+import { validateToolInput } from '../tools/input-validation'
+import { convertSchemaToJsonSchema } from '../tools/schema-converter'
+import { getLoadChild } from '../middleware/load-child'
+import type { LoadChild } from '../middleware/load-child'
 import type { SubagentToolOutcome } from '../tools/tool-calls'
 import type { SpecTokenUsage } from '../../../utilities/ag-ui-usage'
 import type {
+  InferSchemaType,
   Interrupt,
+  JSONSchema,
   ModelMessage,
   RunAgentResumeItem,
   StreamChunk,
@@ -24,6 +30,7 @@ import type {
   SubagentStartedEvent,
   TokenUsage,
   Tool,
+  ToolExecutionContext,
   UIMessage,
 } from '../../../types'
 import { envProviderKeys } from '../../../byok/env-keys'
@@ -117,6 +124,50 @@ export interface SubagentsBag<
    * it. Apps do not.
    */
   binding?: SubagentBinding
+  /**
+   * The tools the parent model gets. `per-agent` (the default) gives one tool
+   * per agent, with the agent's name. `single` gives one tool named
+   * `subagent`. It takes the agent name, plus `sessionId` to continue a
+   * stored child and `background` to start a child without waiting.
+   */
+  tool?: 'per-agent' | 'single'
+}
+
+/** The name of the one tool in `subagents: { tool: 'single' }`. */
+export const SINGLE_SUBAGENT_TOOL = 'subagent'
+
+/** Fields every call of the single `subagent` tool can add. */
+interface SubagentCallOptions {
+  /** The `subagentRunId` of a stored, finished child. The call continues it. */
+  sessionId?: string
+  /** Start the child and return at once. Needs a harness host. */
+  background?: boolean
+}
+
+/** One agent's call: `input` for an agent with `inputSchema`, else `prompt`. */
+type SubagentCallFor<TAgent extends DefinedAgent> = TAgent extends DefinedAgent
+  ? ([NonNullable<TAgent['inputSchema']>] extends [never]
+      ? { agent: TAgent['name']; prompt?: string }
+      : {
+          agent: TAgent['name']
+          input: InferSchemaType<NonNullable<TAgent['inputSchema']>>
+        }) &
+      SubagentCallOptions
+  : never
+
+/**
+ * The input of the single `subagent` tool (`subagents: { tool: 'single' }`).
+ * A union on `agent`: an agent with an `inputSchema` needs `input`, and an
+ * agent without one takes an optional `prompt`.
+ */
+export type SubagentToolInput<TAgents extends ReadonlyArray<DefinedAgent>> =
+  SubagentCallFor<TAgents[number]>
+
+/** A call of the single `subagent` tool, after the wire schema check. */
+interface SubagentCall extends SubagentCallOptions {
+  agent: string
+  input?: unknown
+  prompt?: string
 }
 
 /** What the children of one parent run left behind for the parent terminal. */
@@ -137,6 +188,13 @@ export interface SpawnEntry {
   name: string
   /** The checked input of an agent with `inputSchema`, from a tool or a router. */
   input?: unknown
+  /** Text for an agent without `inputSchema`. One user message at the end. */
+  prompt?: string
+  /** A stored, finished child to run again from its transcript. */
+  continued?: {
+    subagentRunId: string
+    messages: Array<UIMessage | ModelMessage>
+  }
   resume?: {
     subagentRunId: string
     /** The child's own messages from the interrupted run. */
@@ -277,7 +335,9 @@ function openAgentStream(
 ) {
   const agent = agentByName(bag.agents, entry.name)
   const resume = entry.resume
-  const subagentRunId = resume?.subagentRunId ?? createSubagentId()
+  const continued = entry.continued
+  const subagentRunId =
+    resume?.subagentRunId ?? continued?.subagentRunId ?? createSubagentId()
   // The parent binds child interrupts to its own run (see rebindInterrupts),
   // so the resumed child continues from the interrupted parent run id.
   if (resume !== undefined && ctx.interruptedRunId === undefined) {
@@ -285,10 +345,29 @@ function openAgentStream(
       `Subagent "${entry.name}" has interrupt answers, but the run has no parentRunId. Pass the interrupted run id as parentRunId.`,
     )
   }
+  // A continued child starts from its stored transcript, not from the parent
+  // messages. A prompt is one more user message at the end.
+  const base = continued?.messages ?? ctx.messages
+  const messages =
+    entry.prompt === undefined
+      ? base
+      : [
+          ...base,
+          { role: 'user', content: entry.prompt } satisfies ModelMessage,
+        ]
+  // The card of a continued child also holds its stored messages. Keep only
+  // the messages that the stored transcript does not have.
+  const storedIds = new Set(continued?.messages.map((message) => message.id))
   const resumed =
     resume !== undefined
       ? {
-          messages: [...ctx.messages, ...resume.messages],
+          messages: [
+            ...messages,
+            ...resume.messages.filter(
+              (message) =>
+                message.id === undefined || !storedIds.has(message.id),
+            ),
+          ],
           parentRunId: ctx.interruptedRunId,
           resume: resume.entries,
         }
@@ -297,7 +376,7 @@ function openAgentStream(
     agent,
     {
       input: entry.input,
-      messages: resumed?.messages ?? ctx.messages,
+      messages: resumed?.messages ?? messages,
       ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}),
       threadId: childThreadId(bag.sandbox, ctx.threadId, entry.name),
       runId: childRunId(ctx.parentRunId, subagentRunId),
@@ -475,14 +554,16 @@ function isAsyncIterable(value: unknown): value is AsyncIterable<StreamChunk> {
 /**
  * Chunks for an agent whose `run` resolved to a plain value instead of a
  * stream. A string also streams as the child's text, so the parent model, a
- * `sequence` router, and the UI all read it like chat output.
+ * `sequence` router, and the UI all read it like chat output. `messageId` is
+ * new for each run and call, so the text of a continued child does not merge
+ * into its stored text.
  */
 function* valueResultChunks(
   value: unknown,
   id: string,
+  messageId: string,
 ): Generator<StreamChunk> {
   if (typeof value === 'string' && value !== '') {
-    const messageId = `${id}-text`
     const timestamp = Date.now()
     yield attributeChunk(
       {
@@ -579,7 +660,11 @@ export async function* spawnAgentStream(
         yield stoppedEvent(id)
         return
       }
-      yield* valueResultChunks(produced, id)
+      const messageId =
+        parentToolCallId === undefined
+          ? `${ctx.runId}-text`
+          : `${ctx.runId}-${parentToolCallId}-text`
+      yield* valueResultChunks(produced, id, messageId)
       return
     }
     iterator = produced[Symbol.asyncIterator]()
@@ -803,12 +888,17 @@ function messagesBeforeCall(
 
 /**
  * Record the parent messages when the model calls a subagent tool, so the
- * child reads the conversation as it is at that call.
+ * child reads the conversation as it is at that call. Also read the run's
+ * `loadChild` service, so a call can continue a stored child.
  */
 export function subagentCallMessages(names: ReadonlySet<string>) {
   const byCall = new Map<string, Array<ModelMessage>>()
+  let loadChild: LoadChild | undefined
   const middleware: ChatMiddleware = {
     name: 'subagent-call-messages',
+    onStart(ctx) {
+      loadChild = getLoadChild(ctx, { optional: true })
+    },
     onBeforeToolCall(ctx, hook) {
       if (!names.has(hook.toolName)) return undefined
       byCall.set(
@@ -822,7 +912,72 @@ export function subagentCallMessages(names: ReadonlySet<string>) {
     middleware,
     messagesFor: (toolCallId: string | undefined) =>
       toolCallId === undefined ? undefined : byCall.get(toolCallId),
+    childLoader: () => loadChild,
+  }
+}
+
+/** The JSON Schema of each agent `input`, by agent name. */
+function agentInputSchemas(agents: ReadonlyArray<DefinedAgent>) {
+  const schemas = new Map<string, JSONSchema>()
+  for (const agent of agents) {
+    const schema = convertSchemaToJsonSchema(agent.inputSchema, { io: 'input' })
+    if (schema) schemas.set(agent.name, schema)
+  }
+  return schemas
+}
+
+/**
+ * The description and the wire schema of the single `subagent` tool.
+ * Providers need one object at the top, so `input` is an `anyOf` of the agent
+ * schemas. `execute` checks each field against the picked agent.
+ */
+function singleToolShape(agents: ReadonlyArray<DefinedAgent>) {
+  const inputs = agentInputSchemas(agents)
+  const takesPrompt = agents.some((agent) => !inputs.has(agent.name))
+  const lines = agents.map((agent) => {
+    const schema = inputs.get(agent.name)
+    const how = schema
+      ? `Pass \`input\`: ${JSON.stringify(schema)}`
+      : 'Pass `prompt`: the task as text.'
+    return `- ${agent.name}: ${agent.description} ${how}`
+  })
+  const inputSchema: JSONSchema = {
+    type: 'object',
+    properties: {
+      agent: { type: 'string', enum: agents.map((agent) => agent.name) },
+      ...(inputs.size > 0 && { input: { anyOf: [...inputs.values()] } }),
+      ...(takesPrompt && { prompt: { type: 'string' } }),
+      sessionId: { type: 'string' },
+      background: { type: 'boolean' },
+    },
+    required: ['agent'],
+  }
+  return {
+    description: [
+      'Run a subagent. Set `agent` to one of these names:',
+      ...lines,
+      'Set `sessionId` to the subagentRunId of an earlier result to continue that child.',
+      'Set `background` to true to start the child and get its subagentRunId at once.',
+    ].join('\n'),
+    inputSchema,
+  }
+}
+
+/** The checked `input` of a single-tool call. A wrong field throws a tool error. */
+async function callInput(agent: DefinedAgent, call: SubagentCall) {
+  if (agent.inputSchema === undefined) {
+    if (call.input !== undefined) {
+      throw new Error(`Agent "${agent.name}" takes prompt, not input.`)
+    }
+    return undefined
   }
+  if (call.prompt !== undefined) {
+    throw new Error(`Agent "${agent.name}" takes input, not prompt.`)
+  }
+  if (call.input === undefined) {
+    throw new Error(`Agent "${agent.name}" needs input.`)
+  }
+  return validateToolInput(agent.inputSchema, call.input, agent.name)
 }
 
 export function createSyntheticSubagentTools(
@@ -842,141 +997,207 @@ export function createSyntheticSubagentTools(
     abortSignal?: AbortSignal
     turn?: SubagentTurn
     sink: SubagentSink
+    /** The run's `loadChild` service. See subagentCallMessages. */
+    childLoader?: () => LoadChild | undefined
   },
 ): Array<Tool> {
   // One budget per root run. A child run inherits its parent's budget.
   const budget = bag.binding?.budget ?? SubagentBudget.root(bag.limits)
   let active = 0
+
+  /** Run one child for a tool call. The model gets its text or result. */
+  async function runChild(child: SpawnEntry, context: unknown) {
+    const toolContext = context as
+      | {
+          toolCallId?: string
+          [EMIT_STREAM_CHUNK]?: (chunk: StreamChunk) => void
+        }
+      | undefined
+    const toolCallId = toolContext?.toolCallId
+    const suspended = parent.turn?.children.find(
+      (turnChild) =>
+        turnChild.status === 'suspended' &&
+        turnChild.parentToolCallId !== undefined &&
+        turnChild.parentToolCallId === toolCallId,
+    )
+    const entry: SpawnEntry = {
+      ...child,
+      ...(suspended && {
+        resume: {
+          subagentRunId: suspended.subagentRunId,
+          messages: suspended.messages,
+          entries: suspended.resume,
+          text: suspended.text,
+        },
+      }),
+    }
+    // A resumed child already counted when it first started.
+    const refusal = suspended ? undefined : budget.reserve(active)
+    if (refusal !== undefined) {
+      return {
+        subagentRunId: '',
+        text: '',
+        error: refusal,
+      } satisfies SubagentToolOutcome
+    }
+    active += 1
+    const sink = createSubagentSink()
+    const link = linkAbort(parent.abortSignal)
+    const timeout = budget.childTimeout()
+    const timer =
+      timeout === undefined
+        ? undefined
+        : setTimeout(
+            () =>
+              link.controller.abort(
+                new Error(`subagent timed out after ${timeout} ms`),
+              ),
+            timeout,
+          )
+    const childBinding: SubagentBinding = {
+      ...bag.binding,
+      budget: budget.child(
+        timeout === undefined ? undefined : Date.now() + timeout,
+      ),
+    }
+    let subagentRunId = suspended?.subagentRunId ?? ''
+    let text = suspended?.text ?? ''
+    let error: string | undefined
+    let result: unknown
+    try {
+      for await (const chunk of openAgentStream(
+        entry,
+        bag,
+        {
+          messages: parent.messagesFor?.(toolCallId) ?? parent.messages,
+          abortSignal: link.controller.signal,
+          threadId: parent.threadId,
+          parentRunId: parent.runId,
+          ...(parent.interruptedRunId !== undefined
+            ? { interruptedRunId: parent.interruptedRunId }
+            : {}),
+          ...(parent.parentSubagentRunId !== undefined
+            ? { parentSubagentRunId: parent.parentSubagentRunId }
+            : {}),
+        },
+        sink,
+        toolCallId,
+        childBinding,
+      )) {
+        if (chunk.type === SUBAGENT_STARTED && subagentRunId === '') {
+          subagentRunId = chunk.subagentRunId
+        }
+        if (
+          chunk.type === EventType.TEXT_MESSAGE_CONTENT &&
+          'subagentRunId' in chunk &&
+          chunk.subagentRunId === subagentRunId
+        ) {
+          text += chunk.delta
+        }
+        if (
+          chunk.type === SUBAGENT_ERROR &&
+          chunk.subagentRunId === subagentRunId
+        ) {
+          error = chunk.message
+        }
+        if (
+          chunk.type === SUBAGENT_FINISHED &&
+          chunk.subagentRunId === subagentRunId &&
+          chunk.result !== undefined
+        ) {
+          result = chunk.result
+        }
+        toolContext?.[EMIT_STREAM_CHUNK]?.(chunk)
+      }
+    } finally {
+      active -= 1
+      if (timer !== undefined) clearTimeout(timer)
+      link.dispose()
+    }
+    parent.sink.usage.push(...sink.usage)
+    if (sink.total) {
+      parent.sink.total = parent.sink.total
+        ? addTokenUsage(parent.sink.total, sink.total)
+        : sink.total
+    }
+    return {
+      subagentRunId,
+      text,
+      ...(result !== undefined ? { result } : {}),
+      ...(error !== undefined ? { error } : {}),
+      ...(sink.interrupts.length > 0 ? { interrupts: sink.interrupts } : {}),
+    } satisfies SubagentToolOutcome
+  }
+
+  /** The stored child that a `sessionId` names. Throws a tool error. */
+  async function storedChild(sessionId: string) {
+    const load = parent.childLoader?.()
+    if (!load) throw new Error('sessionId needs a persistence store.')
+    const stored = await load(sessionId)
+    if (!stored) throw new Error(`Unknown sessionId "${sessionId}".`)
+    return { subagentRunId: sessionId, messages: stored.messages }
+  }
+
+  if (bag.tool === 'single') {
+    // A thrown error in `execute` goes back to the model as a tool error.
+    const single = {
+      name: SINGLE_SUBAGENT_TOOL,
+      ...singleToolShape(bag.agents),
+      [SUBAGENT_TOOL]: true,
+      execute: async (call: SubagentCall, context?: ToolExecutionContext) => {
+        const agent = bag.agents.find((entry) => entry.name === call.agent)
+        if (!agent) throw new Error(`Unknown agent "${call.agent}".`)
+        const input = await callInput(agent, call)
+        const fields = {
+          ...(input !== undefined && { input }),
+          ...(call.prompt !== undefined && { prompt: call.prompt }),
+        }
+        const child = { name: agent.name, ...fields }
+        if (call.background === true) {
+          if (call.sessionId !== undefined) {
+            throw new Error('background cannot continue a sessionId.')
+          }
+          const start = bag.binding?.start
+          if (!start) throw new Error('background needs a harness host.')
+          const { subagentRunId } = await start(
+            {
+              agent: agent.name,
+              ...fields,
+              ...(context?.toolCallId !== undefined && {
+                parentToolCallId: context.toolCallId,
+              }),
+            },
+            { wake: true },
+          )
+          return {
+            subagentRunId,
+            text: '',
+            result: { status: 'started' },
+          } satisfies SubagentToolOutcome
+        }
+        if (call.sessionId === undefined) return runChild(child, context)
+        const continued = await storedChild(call.sessionId)
+        return runChild({ ...child, continued }, context)
+      },
+    }
+    return [single]
+  }
+
   return bag.agents.map((agent) => ({
     name: agent.name,
     description: agent.description,
     ...(agent.inputSchema !== undefined && { inputSchema: agent.inputSchema }),
     [SUBAGENT_TOOL]: true,
     // The tool loop checks `input` against `inputSchema` before this runs.
-    execute: async (input: unknown, context?: unknown) => {
-      const toolContext = context as
-        | {
-            toolCallId?: string
-            [EMIT_STREAM_CHUNK]?: (chunk: StreamChunk) => void
-          }
-        | undefined
-      const toolCallId = toolContext?.toolCallId
-      const suspended = parent.turn?.children.find(
-        (child) =>
-          child.status === 'suspended' &&
-          child.parentToolCallId !== undefined &&
-          child.parentToolCallId === toolCallId,
-      )
-      // An agent without `inputSchema` still gets `{}` from the model. Its
-      // `ctx.input` stays undefined.
-      const entry: SpawnEntry = {
-        name: agent.name,
-        ...(agent.inputSchema !== undefined && { input }),
-        ...(suspended && {
-          resume: {
-            subagentRunId: suspended.subagentRunId,
-            messages: suspended.messages,
-            entries: suspended.resume,
-            text: suspended.text,
-          },
-        }),
-      }
-      // A resumed child already counted when it first started.
-      const refusal = suspended ? undefined : budget.reserve(active)
-      if (refusal !== undefined) {
-        return {
-          subagentRunId: '',
-          text: '',
-          error: refusal,
-        } satisfies SubagentToolOutcome
-      }
-      active += 1
-      const sink = createSubagentSink()
-      const link = linkAbort(parent.abortSignal)
-      const timeout = budget.childTimeout()
-      const timer =
-        timeout === undefined
-          ? undefined
-          : setTimeout(
-              () =>
-                link.controller.abort(
-                  new Error(`subagent timed out after ${timeout} ms`),
-                ),
-              timeout,
-            )
-      const childBinding: SubagentBinding = {
-        ...bag.binding,
-        budget: budget.child(
-          timeout === undefined ? undefined : Date.now() + timeout,
-        ),
-      }
-      let subagentRunId = suspended?.subagentRunId ?? ''
-      let text = suspended?.text ?? ''
-      let error: string | undefined
-      let result: unknown
-      try {
-        for await (const chunk of openAgentStream(
-          entry,
-          bag,
-          {
-            messages: parent.messagesFor?.(toolCallId) ?? parent.messages,
-            abortSignal: link.controller.signal,
-            threadId: parent.threadId,
-            parentRunId: parent.runId,
-            ...(parent.interruptedRunId !== undefined
-              ? { interruptedRunId: parent.interruptedRunId }
-              : {}),
-            ...(parent.parentSubagentRunId !== undefined
-              ? { parentSubagentRunId: parent.parentSubagentRunId }
-              : {}),
-          },
-          sink,
-          toolCallId,
-          childBinding,
-        )) {
-          if (chunk.type === SUBAGENT_STARTED && subagentRunId === '') {
-            subagentRunId = chunk.subagentRunId
-          }
-          if (
-            chunk.type === EventType.TEXT_MESSAGE_CONTENT &&
-            'subagentRunId' in chunk &&
-            chunk.subagentRunId === subagentRunId
-          ) {
-            text += chunk.delta
-          }
-          if (
-            chunk.type === SUBAGENT_ERROR &&
-            chunk.subagentRunId === subagentRunId
-          ) {
-            error = chunk.message
-          }
-          if (
-            chunk.type === SUBAGENT_FINISHED &&
-            chunk.subagentRunId === subagentRunId &&
-            chunk.result !== undefined
-          ) {
-            result = chunk.result
-          }
-          toolContext?.[EMIT_STREAM_CHUNK]?.(chunk)
-        }
-      } finally {
-        active -= 1
-        if (timer !== undefined) clearTimeout(timer)
-        link.dispose()
-      }
-      parent.sink.usage.push(...sink.usage)
-      if (sink.total) {
-        parent.sink.total = parent.sink.total
-          ? addTokenUsage(parent.sink.total, sink.total)
-          : sink.total
-      }
-      return {
-        subagentRunId,
-        text,
-        ...(result !== undefined ? { result } : {}),
-        ...(error !== undefined ? { error } : {}),
-        ...(sink.interrupts.length > 0 ? { interrupts: sink.interrupts } : {}),
-      } satisfies SubagentToolOutcome
-    },
+    // An agent without `inputSchema` still gets `{}` from the model. Its
+    // `ctx.input` stays undefined.
+    execute: (input: unknown, context?: unknown) =>
+      runChild(
+        {
+          name: agent.name,
+          ...(agent.inputSchema !== undefined && { input }),
+        },
+        context,
+      ),
   }))
 }
diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index d0235547a0..dff0fa55f0 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -62,6 +62,7 @@ import { LazyToolManager } from './tools/lazy-tool-manager'
 import { assertUniqueToolNames } from './tools/unique-tool-names'
 import type { DefinedAgent } from './agents/define-agent'
 import {
+  SINGLE_SUBAGENT_TOOL,
   collectNamedText,
   createSubagentSink,
   createSyntheticSubagentTools,
@@ -162,6 +163,7 @@ import type {
   ToolCallEndEvent,
   ToolCallResultEvent,
   ToolCallStartEvent,
+  ToolChoice,
   ToolInputResponse,
   UIMessage,
 } from '../../types'
@@ -590,6 +592,18 @@ export interface TextActivityOptions<
    * ```
    */
   promptCache?: PromptCacheOptions
+  /**
+   * How the model uses the tools: `'auto'`, `'none'`, `'required'`, or
+   * `{ type: 'tool', name }`. It applies to every model call of this
+   * `chat()`. A middleware `onConfig` can change it for one call. A call with
+   * no tools sends no tool choice. A provider value in `modelOptions` wins.
+   *
+   * @example
+   * ```ts
+   * chat({ adapter, messages, tools, toolChoice: 'required' })
+   * ```
+   */
+  toolChoice?: ToolChoice
   /** Run ID override for AG-UI protocol. Auto-generated by adapter if not provided. */
   runId?: TextOptions['runId']
   /** Parent run ID for AG-UI protocol nested run correlation. */
@@ -885,6 +899,11 @@ class TextEngine<
     InterruptDefinition<any, any, any, any>
   >
   private params: TParams
+  /**
+   * The tool choice of the next model call. `params.toolChoice` keeps the
+   * `chat()` option, so a middleware value lasts for one call only.
+   */
+  private callToolChoice: ToolChoice | undefined = undefined
   private systemPrompts: Array<SystemPrompt>
   private tools: Array<AnyRuntimeTool>
   private readonly loopStrategy: AgentLoopStrategy
@@ -1759,6 +1778,10 @@ class TextEngine<
       }
     }
 
+    // Providers reject a tool choice on a request with no tools.
+    const toolChoice =
+      toolsWithJsonSchemas.length > 0 ? this.callToolChoice : undefined
+
     for await (const adapterChunk of this.adapter.chatStream({
       model: this.params.model,
       messages: replay.messages,
@@ -1771,6 +1794,7 @@ class TextEngine<
       logger: this.logger,
       threadId: this.threadId,
       promptCache: this.params.promptCache,
+      ...(toolChoice ? { toolChoice } : {}),
       ...(midConversation
         ? { midConversationChanges: midConversation.changes }
         : {}),
@@ -2456,7 +2480,7 @@ class TextEngine<
             name: info.toolName,
             result: info.result,
           })
-          await this.middlewareRunner.runOnAfterToolCall(
+          return this.middlewareRunner.runOnAfterToolCall(
             this.middlewareCtx,
             info,
           )
@@ -2657,7 +2681,7 @@ class TextEngine<
             name: info.toolName,
             result: info.result,
           })
-          await this.middlewareRunner.runOnAfterToolCall(
+          return this.middlewareRunner.runOnAfterToolCall(
             this.middlewareCtx,
             info,
           )
@@ -4355,11 +4379,15 @@ class TextEngine<
 
     this.middlewareCtx.phase = 'structuredOutput'
 
-    // Build the structured-output config view. `tools` is intentionally
-    // excluded from the type because it isn't forwarded to the structured-
-    // output adapter call — including it here would be misleading API.
+    // Build the structured-output config view. `tools` and `toolChoice` are
+    // intentionally excluded from the type because they aren't forwarded to
+    // the structured-output adapter call — including them would be misleading.
     const baseConfig = this.buildMiddlewareConfig()
-    const { tools: _omitTools, ...baseWithoutTools } = baseConfig
+    const {
+      tools: _omitTools,
+      toolChoice: _omitToolChoice,
+      ...baseWithoutTools
+    } = baseConfig
     let structuredConfig: StructuredOutputMiddlewareConfig = {
       ...baseWithoutTools,
       outputSchema: this.finalStructuredOutput.jsonSchema,
@@ -4921,6 +4949,7 @@ class TextEngine<
       modelOptions: this.params.modelOptions,
       reasoning: this.params.reasoning,
       promptCache: this.params.promptCache,
+      toolChoice: this.params.toolChoice,
     }
   }
 
@@ -5399,6 +5428,8 @@ class TextEngine<
       reasoning: config.reasoning,
       promptCache: config.promptCache ?? this.params.promptCache,
     }
+    // Not stored in params: the next call starts from the chat() option.
+    this.callToolChoice = config.toolChoice ?? this.params.toolChoice
 
     // Sync context fields that depend on config
     this.middlewareCtx.messages = this.messages
@@ -5835,6 +5866,17 @@ export function chat<
     )
   }
 
+  const singleToolNameTaken =
+    options.subagents?.tool === 'single' &&
+    [...options.subagents.agents, ...(options.tools ?? [])].some(
+      (entry) => entry.name === SINGLE_SUBAGENT_TOOL,
+    )
+  if (singleToolNameTaken) {
+    throw new Error(
+      `subagents.tool 'single' adds a tool named "${SINGLE_SUBAGENT_TOOL}". Rename the agent or tool that uses this name.`,
+    )
+  }
+
   if (outputSchema && stream === true) {
     return runStreamingStructuredOutput(
       toRuntimeTextActivityOptions(options, {
@@ -6100,11 +6142,16 @@ async function* streamTextChunks(
     const turn = readSubagentTurn(messages, options.resume)
     const sink = createSubagentSink()
     const calls = subagentCallMessages(
-      new Set(bag.agents.map((agent: DefinedAgent) => agent.name)),
+      new Set(
+        bag.tool === 'single'
+          ? [SINGLE_SUBAGENT_TOOL]
+          : bag.agents.map((agent: DefinedAgent) => agent.name),
+      ),
     )
     const synthetic = createSyntheticSubagentTools(bag, {
       messages: turn?.before ?? messages,
       messagesFor: calls.messagesFor,
+      childLoader: calls.childLoader,
       threadId,
       runId,
       ...(options.parentRunId !== undefined && {
diff --git a/packages/ai/src/activities/chat/middleware/compose.ts b/packages/ai/src/activities/chat/middleware/compose.ts
index 5493e20485..2963296c76 100644
--- a/packages/ai/src/activities/chat/middleware/compose.ts
+++ b/packages/ai/src/activities/chat/middleware/compose.ts
@@ -3,6 +3,7 @@ import type { AgentLoopState, StreamChunk } from '../../../types'
 import type { InternalLogger } from '../../../logger/internal-logger'
 import type {
   AbortInfo,
+  AfterToolCallDecision,
   AfterToolCallInfo,
   BeforeToolCallDecision,
   ChatMiddleware,
@@ -524,16 +525,24 @@ export class MiddlewareRunner<
 
   /**
    * Run onAfterToolCall on all middleware in order.
+   * A `replaceResult` decision changes `info.result` for the next middleware.
+   * Returns the last replacement, or undefined when no middleware replaced it.
    */
   async runOnAfterToolCall(
     ctx: ChatMiddlewareContext<TContext>,
     info: AfterToolCallInfo,
-  ): Promise<void> {
+  ): Promise<AfterToolCallDecision> {
+    let current = info
+    let replacement: AfterToolCallDecision = undefined
     for (const mw of this.middlewares) {
       if (mw.onAfterToolCall) {
         const skip = shouldSkipInstrumentation(mw)
         const start = Date.now()
-        await mw.onAfterToolCall(ctx, info)
+        const decision = await mw.onAfterToolCall(ctx, current)
+        if (decision) {
+          current = { ...current, result: decision.result }
+          replacement = decision
+        }
         if (!skip) {
           this.logger.middleware(
             `hook=onAfterToolCall middleware=${mw.name ?? 'unnamed'}`,
@@ -545,11 +554,12 @@ export class MiddlewareRunner<
             hookName: 'onAfterToolCall',
             iteration: ctx.iteration,
             duration: Date.now() - start,
-            hasTransform: false,
+            hasTransform: Boolean(decision),
           })
         }
       }
     }
+    return replacement
   }
 
   /**
diff --git a/packages/ai/src/activities/chat/middleware/index.ts b/packages/ai/src/activities/chat/middleware/index.ts
index 2c4b8a7fbd..ce42248bf3 100644
--- a/packages/ai/src/activities/chat/middleware/index.ts
+++ b/packages/ai/src/activities/chat/middleware/index.ts
@@ -8,6 +8,7 @@ export type {
   StructuredOutputMiddlewareConfig,
   ToolCallHookContext,
   BeforeToolCallDecision,
+  AfterToolCallDecision,
   AfterToolCallInfo,
   IterationInfo,
   ToolPhaseCompleteInfo,
diff --git a/packages/ai/src/activities/chat/middleware/load-child.ts b/packages/ai/src/activities/chat/middleware/load-child.ts
new file mode 100644
index 0000000000..50b093d6a7
--- /dev/null
+++ b/packages/ai/src/activities/chat/middleware/load-child.ts
@@ -0,0 +1,16 @@
+import { createCapability } from './capabilities'
+import type { ModelMessage, UIMessage } from '../../../types'
+
+/**
+ * Loads the stored transcript of a finished subagent run by its
+ * `subagentRunId`. Returns `undefined` for an unknown id. A persistence
+ * middleware provides it. The single `subagent` tool reads it to continue a
+ * child by `sessionId`.
+ */
+export type LoadChild = (
+  subagentRunId: string,
+) => Promise<{ messages: Array<ModelMessage | UIMessage> } | undefined>
+
+export const LoadChildCapability = createCapability<LoadChild>()('load-child')
+
+export const [getLoadChild, provideLoadChild] = LoadChildCapability
diff --git a/packages/ai/src/activities/chat/middleware/types.ts b/packages/ai/src/activities/chat/middleware/types.ts
index 18a990ff00..0e339d1fce 100644
--- a/packages/ai/src/activities/chat/middleware/types.ts
+++ b/packages/ai/src/activities/chat/middleware/types.ts
@@ -15,6 +15,7 @@ import type {
   TokenUsage,
   Tool,
   ToolCall,
+  ToolChoice,
 } from '../../../types'
 import type { SystemPrompt } from '../../../system-prompts'
 import type { ToolApprovalResolution } from '../../../interrupts'
@@ -347,6 +348,12 @@ export interface ChatMiddlewareConfig {
    * middleware changes it.
    */
   promptCache?: ResolvedPromptCache | undefined
+  /**
+   * How the model uses the tools of the next model call. A returned value
+   * applies to that call only. The next call starts again from the `chat()`
+   * option. A call with no tools sends no tool choice.
+   */
+  toolChoice?: ToolChoice | undefined
 }
 
 /**
@@ -379,16 +386,17 @@ export type ChatResumeGenericResolution =
 /**
  * Config passed to onStructuredOutputConfig.
  *
- * Mirrors ChatMiddlewareConfig minus `tools` (the final structured-output call
- * is a single typed-response request, not an agentic loop — tools cannot be
- * forwarded to it), plus the `outputSchema` being sent to the provider.
+ * Mirrors ChatMiddlewareConfig minus `tools` and `toolChoice` (the final
+ * structured-output call is a single typed-response request, not an agentic
+ * loop — tools cannot be forwarded to it), plus the `outputSchema` being sent
+ * to the provider.
  * Middleware may transform the schema (e.g., inject $defs, strip
  * vendor-incompatible keywords) by returning a partial that includes
  * `outputSchema`.
  */
 export interface StructuredOutputMiddlewareConfig extends Omit<
   ChatMiddlewareConfig,
-  'tools'
+  'tools' | 'toolChoice'
 > {
   /** JSON Schema being sent to the provider for structured output. */
   outputSchema: JSONSchema
@@ -450,6 +458,17 @@ export interface AfterToolCallInfo {
   error?: unknown
 }
 
+/**
+ * Decision returned from onAfterToolCall.
+ * - undefined/void: keep the current result
+ * - { type: 'replaceResult', result }: use this result instead. The model and
+ *   the stream see it. The next middleware gets it as `info.result`. An error
+ *   result stays an error.
+ */
+export type AfterToolCallDecision =
+  | void
+  | { type: 'replaceResult'; result: unknown }
+
 // ===========================
 // Iteration Info
 // ===========================
@@ -796,11 +815,14 @@ export interface ChatMiddleware<
 
   /**
    * Called after a tool execution completes (success or failure).
+   * Return `{ type: 'replaceResult', result }` to change the result that the
+   * model and the stream see. Middleware run in order. Each one sees the
+   * result of the one before it.
    */
   onAfterToolCall?: (
     ctx: ChatMiddlewareContext<TContext>,
     info: AfterToolCallInfo,
-  ) => void | Promise<void>
+  ) => AfterToolCallDecision | Promise<AfterToolCallDecision>
 
   /**
    * Called after all tool calls in an iteration have been processed.
diff --git a/packages/ai/src/activities/chat/tools/tool-calls.ts b/packages/ai/src/activities/chat/tools/tool-calls.ts
index 662b0e6dc7..c4fbed4a78 100644
--- a/packages/ai/src/activities/chat/tools/tool-calls.ts
+++ b/packages/ai/src/activities/chat/tools/tool-calls.ts
@@ -33,6 +33,7 @@ import type {
   ToolOutputState,
 } from '../../../types'
 import type {
+  AfterToolCallDecision,
   AfterToolCallInfo,
   BeforeToolCallDecision,
 } from '../middleware/types'
@@ -200,7 +201,7 @@ export interface ToolExecutionMiddlewareHooks {
     tool: Tool | undefined,
     args: unknown,
   ) => Promise<BeforeToolCallDecision>
-  onAfterToolCall?: (info: AfterToolCallInfo) => Promise<void>
+  onAfterToolCall?: (info: AfterToolCallInfo) => Promise<AfterToolCallDecision>
 }
 
 /**
@@ -650,6 +651,22 @@ async function* executeWithEventPolling<T>(
   return state.result
 }
 
+/**
+ * Push a tool result, then run the onAfterToolCall hook. A `replaceResult`
+ * decision sets the pushed result, so the model and the stream see it.
+ * The state does not change: an error result stays an error.
+ */
+async function pushResultAndRunAfterHook(
+  results: Array<ToolResult>,
+  entry: ToolResult,
+  info: AfterToolCallInfo,
+  middlewareHooks?: ToolExecutionMiddlewareHooks,
+) {
+  results.push(entry)
+  const decision = await middlewareHooks?.onAfterToolCall?.(info)
+  if (decision) entry.result = decision.result
+}
+
 /**
  * Apply a middleware onBeforeToolCall decision.
  * Returns the (possibly transformed) input if execution should proceed,
@@ -678,18 +695,15 @@ async function applyBeforeToolCallDecision(
   }
 
   if (decision?.type === 'skip') {
-    const skipResult = decision.result
-    results.push({
-      toolCallId: toolCall.id,
-      toolName,
-      result:
-        typeof skipResult === 'string'
-          ? safeJsonParse(skipResult)
-          : (skipResult ?? null),
-      duration: 0,
-    })
-    if (middlewareHooks.onAfterToolCall) {
-      await middlewareHooks.onAfterToolCall({
+    // One parsed value: the hook sees the same value that is pushed.
+    const skipResult =
+      typeof decision.result === 'string'
+        ? safeJsonParse(decision.result)
+        : (decision.result ?? null)
+    await pushResultAndRunAfterHook(
+      results,
+      { toolCallId: toolCall.id, toolName, result: skipResult, duration: 0 },
+      {
         toolCall,
         tool,
         toolName,
@@ -697,8 +711,9 @@ async function applyBeforeToolCallDecision(
         ok: true,
         duration: 0,
         result: skipResult,
-      })
-    }
+      },
+      middlewareHooks,
+    )
     return { proceed: false }
   }
 
@@ -753,25 +768,29 @@ export async function* executeServerTool<TContext = unknown>(
                 ? compactForModel(outcome.result)
                 : outcome.text,
           }
-      results.push({
-        toolCallId: toolCall.id,
-        toolName,
-        result: modelResult,
-        input,
-        output: modelResult,
-        duration,
-        ...(outcome.error ? { state: 'output-error' as const } : {}),
-      })
-      await middlewareHooks?.onAfterToolCall?.({
-        toolCall,
-        tool,
-        toolName,
-        toolCallId: toolCall.id,
-        duration,
-        ...(outcome.error
-          ? { ok: false as const, error: new Error(outcome.error) }
-          : { ok: true as const, result: modelResult }),
-      })
+      await pushResultAndRunAfterHook(
+        results,
+        {
+          toolCallId: toolCall.id,
+          toolName,
+          result: modelResult,
+          input,
+          output: modelResult,
+          duration,
+          ...(outcome.error ? { state: 'output-error' as const } : {}),
+        },
+        {
+          toolCall,
+          tool,
+          toolName,
+          toolCallId: toolCall.id,
+          duration,
+          ...(outcome.error
+            ? { ok: false as const, error: new Error(outcome.error) }
+            : { ok: true as const, result: modelResult }),
+        },
+        middlewareHooks,
+      )
       return
     }
 
@@ -797,17 +816,17 @@ export async function* executeServerTool<TContext = unknown>(
     const finalResult =
       typeof result === 'string' ? safeJsonParse(result) : (result ?? null)
 
-    results.push({
-      toolCallId: toolCall.id,
-      toolName,
-      result: finalResult,
-      input,
-      output: finalResult,
-      duration,
-    })
-
-    if (middlewareHooks?.onAfterToolCall) {
-      await middlewareHooks.onAfterToolCall({
+    await pushResultAndRunAfterHook(
+      results,
+      {
+        toolCallId: toolCall.id,
+        toolName,
+        result: finalResult,
+        input,
+        output: finalResult,
+        duration,
+      },
+      {
         toolCall,
         tool,
         toolName,
@@ -815,8 +834,9 @@ export async function* executeServerTool<TContext = unknown>(
         ok: true,
         duration,
         result: finalResult,
-      })
-    }
+      },
+      middlewareHooks,
+    )
   } catch (error: unknown) {
     const duration = Date.now() - startTime
 
@@ -844,17 +864,17 @@ export async function* executeServerTool<TContext = unknown>(
     }
 
     const message = error instanceof Error ? error.message : 'Unknown error'
-    results.push({
-      toolCallId: toolCall.id,
-      toolName,
-      result: { error: message },
-      input,
-      state: 'output-error',
-      duration,
-    })
-
-    if (middlewareHooks?.onAfterToolCall) {
-      await middlewareHooks.onAfterToolCall({
+    await pushResultAndRunAfterHook(
+      results,
+      {
+        toolCallId: toolCall.id,
+        toolName,
+        result: { error: message },
+        input,
+        state: 'output-error',
+        duration,
+      },
+      {
         toolCall,
         tool,
         toolName,
@@ -862,8 +882,9 @@ export async function* executeServerTool<TContext = unknown>(
         ok: false,
         duration,
         error,
-      })
-    }
+      },
+      middlewareHooks,
+    )
   }
 }
 
@@ -986,23 +1007,27 @@ export async function* executeToolCalls<TContext = unknown>(
   ): AsyncGenerator<CustomEvent | StreamChunk, void, void> {
     try {
       if (abortSignal?.aborted) {
-        results.push({
-          toolCallId: toolCall.id,
-          toolName,
-          result: { error: 'Operation aborted' },
-          input,
-          state: 'output-error',
-          duration: 0,
-        })
-        await middlewareHooks?.onAfterToolCall?.({
-          toolCall,
-          tool,
-          toolName,
-          toolCallId: toolCall.id,
-          ok: false,
-          duration: 0,
-          error: new Error('Operation aborted'),
-        })
+        await pushResultAndRunAfterHook(
+          results,
+          {
+            toolCallId: toolCall.id,
+            toolName,
+            result: { error: 'Operation aborted' },
+            input,
+            state: 'output-error',
+            duration: 0,
+          },
+          {
+            toolCall,
+            tool,
+            toolName,
+            toolCallId: toolCall.id,
+            ok: false,
+            duration: 0,
+            error: new Error('Operation aborted'),
+          },
+          middlewareHooks,
+        )
         return
       }
       const interrupts: Array<Interrupt> = []
@@ -1148,15 +1173,16 @@ export async function* executeToolCalls<TContext = unknown>(
     } catch (error) {
       const message =
         error instanceof Error ? error.message : 'Validation failed'
-      results.push({
-        toolCallId: toolCall.id,
-        toolName,
-        result: { error: message },
-        input,
-        state: 'output-error',
-      })
-      if (!needsPreview) {
-        await middlewareHooks?.onAfterToolCall?.({
+      await pushResultAndRunAfterHook(
+        results,
+        {
+          toolCallId: toolCall.id,
+          toolName,
+          result: { error: message },
+          input,
+          state: 'output-error',
+        },
+        {
           toolCall,
           tool,
           toolName,
@@ -1164,8 +1190,10 @@ export async function* executeToolCalls<TContext = unknown>(
           ok: false,
           duration: 0,
           error,
-        })
-      }
+        },
+        // A preview call runs no hooks.
+        needsPreview ? undefined : middlewareHooks,
+      )
       continue
     }
     if (needsPreview) {
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index 1f40cb586b..cdc9b013b2 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -122,6 +122,7 @@ export type {
   SubagentStep,
   SubagentStepsPlan,
   SubagentsBag,
+  SubagentToolInput,
 } from './activities/chat/agents/spawn'
 // For hosts (a harness session) that run an agent outside a parent chat turn.
 export {
@@ -274,6 +275,7 @@ export type {
   StructuredOutputMiddlewareConfig,
   ToolCallHookContext,
   BeforeToolCallDecision,
+  AfterToolCallDecision,
   AfterToolCallInfo,
   IterationInfo,
   ToolPhaseCompleteInfo,
@@ -386,6 +388,13 @@ export {
   provideLogRecords,
 } from './activities/chat/middleware/log-records'
 export type { LogRecordsWriter } from './activities/chat/middleware/log-records'
+// A persistence store gives the single `subagent` tool the stored children.
+export {
+  LoadChildCapability,
+  getLoadChild,
+  provideLoadChild,
+} from './activities/chat/middleware/load-child'
+export type { LoadChild } from './activities/chat/middleware/load-child'
 // Locks are a distributed-mutex primitive — coordination, not chat state — and
 // live behind their own subpath: `@tanstack/ai/locks` (see ./locks.ts).
 
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index 6a418577e6..7c9ee1bcac 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -1187,6 +1187,19 @@ export interface ResolvedPromptCache {
   key?: string
 }
 
+/**
+ * How the model uses the tools of a call.
+ * - `'auto'`: the model decides.
+ * - `'none'`: the model calls no tool.
+ * - `'required'`: the model must call a tool.
+ * - `{ type: 'tool', name }`: the model must call that tool.
+ */
+export type ToolChoice =
+  | 'auto'
+  | 'none'
+  | 'required'
+  | { type: 'tool'; name: string }
+
 /**
  * Options passed into the SDK and further piped to the AI provider.
  */
@@ -1321,6 +1334,11 @@ export interface TextOptions<
    * absent, the adapter adds no automatic cache fields.
    */
   promptCache?: ResolvedPromptCache
+  /**
+   * How the model uses the tools of this request. `chat()` sets it only when
+   * the request has tools. A provider value in `modelOptions` wins over it.
+   */
+  toolChoice?: ToolChoice
   /**
    * The tools and system prompts that changed between model calls. The
    * engine sets it only when `adapter.midConversationChannels` has a channel
diff --git a/packages/ai/tests/after-tool-call-replace.test.ts b/packages/ai/tests/after-tool-call-replace.test.ts
new file mode 100644
index 0000000000..a6b94503a7
--- /dev/null
+++ b/packages/ai/tests/after-tool-call-replace.test.ts
@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest'
+import { chat } from '../src/activities/chat/index'
+import { EventType } from '../src/types'
+import { collectChunks, createMockAdapter, ev, serverTool } from './test-utils'
+import type { ChatMiddleware } from '../src/activities/chat/middleware/types'
+import type { Tool } from '../src/types'
+
+const toolTurn = [
+  ev.runStarted(),
+  ev.toolStart('tc-1', 'lookup'),
+  ev.toolArgs('tc-1', '{}'),
+  ev.toolEnd('tc-1'),
+  ev.runFinished('tool_calls'),
+]
+
+const stopTurn = [
+  ev.runStarted(),
+  ev.textContent('Done'),
+  ev.runFinished('stop'),
+]
+
+/** Run one tool call, then a stop turn. Give back what the stream and the model saw. */
+async function runToolCall(tool: Tool, middleware: Array<ChatMiddleware>) {
+  const { adapter, calls } = createMockAdapter({
+    iterations: [toolTurn, stopTurn],
+  })
+  const chunks = await collectChunks(
+    chat({
+      adapter,
+      messages: [{ role: 'user', content: 'Hi' }],
+      tools: [tool],
+      middleware,
+    }),
+  )
+  return {
+    resultChunk: chunks.find(
+      (chunk) => chunk.type === EventType.TOOL_CALL_RESULT,
+    ),
+    toolMessage: calls[1]?.messages.find((message) => message.role === 'tool'),
+  }
+}
+
+describe('onAfterToolCall replaceResult', () => {
+  it('chains replacements, and the stream and the model see the final one', async () => {
+    const { resultChunk, toolMessage } = await runToolCall(
+      serverTool('lookup', () => ({ rows: 500 })),
+      [
+        {
+          name: 'first',
+          onAfterToolCall: () => ({ type: 'replaceResult', result: 'trimmed' }),
+        },
+        {
+          name: 'second',
+          onAfterToolCall: (_ctx, info) => ({
+            type: 'replaceResult',
+            result: { summary: info.result },
+          }),
+        },
+      ],
+    )
+
+    expect(resultChunk).toMatchObject({
+      toolCallId: 'tc-1',
+      content: '{"summary":"trimmed"}',
+    })
+    expect(toolMessage).toMatchObject({
+      toolCallId: 'tc-1',
+      content: '{"summary":"trimmed"}',
+    })
+  })
+
+  it('keeps an error result an error after a replacement', async () => {
+    const { resultChunk, toolMessage } = await runToolCall(
+      serverTool('lookup', () => {
+        throw new Error('disk full while writing /var/log/huge.log')
+      }),
+      [
+        {
+          name: 'short-errors',
+          onAfterToolCall: (_ctx, info) =>
+            info.ok
+              ? undefined
+              : { type: 'replaceResult', result: { error: 'disk full' } },
+        },
+      ],
+    )
+
+    expect(resultChunk).toMatchObject({
+      content: '{"error":"disk full"}',
+      metadata: { tanstack: { state: 'output-error' } },
+    })
+    expect(toolMessage).toMatchObject({
+      content: '{"error":"disk full"}',
+      error: 'disk full',
+    })
+  })
+
+  it('gives the hook the parsed skip result and replaces it', async () => {
+    let seen: unknown
+    const { resultChunk } = await runToolCall(
+      serverTool('lookup', () => 'not called'),
+      [
+        {
+          name: 'cache',
+          onBeforeToolCall: () => ({ type: 'skip', result: '{"rows":3}' }),
+        },
+        {
+          name: 'replace',
+          onAfterToolCall: (_ctx, info) => {
+            seen = info.result
+            return { type: 'replaceResult', result: 'from cache' }
+          },
+        },
+      ],
+    )
+
+    expect(seen).toEqual({ rows: 3 })
+    expect(resultChunk).toMatchObject({ content: 'from cache' })
+  })
+})
diff --git a/packages/ai/tests/subagent-single-tool.test.ts b/packages/ai/tests/subagent-single-tool.test.ts
new file mode 100644
index 0000000000..ce9242e405
--- /dev/null
+++ b/packages/ai/tests/subagent-single-tool.test.ts
@@ -0,0 +1,366 @@
+import { beforeEach, describe, expect, expectTypeOf, it, vi } from 'vitest'
+import { z } from 'zod'
+import { defineAgent } from '../src/activities/chat/agents/define-agent'
+import { chat } from '../src/activities/chat'
+import { provideLoadChild } from '../src/activities/chat/middleware/load-child'
+import {
+  createSubagentSink,
+  createSyntheticSubagentTools,
+} from '../src/activities/chat/agents/spawn'
+import { EventType } from '../src/types'
+import { collectChunks, createMockAdapter, ev, serverTool } from './test-utils'
+import type { DefinedAgent } from '../src/activities/chat/agents/define-agent'
+import type { SubagentToolInput } from '../src/activities/chat/agents/spawn'
+import type { SubagentTurn } from '../src/activities/chat/agents/turn'
+import type { SubagentBinding } from '../src/activities/chat/agents/bound'
+import type { ChatMiddleware } from '../src/activities/chat/middleware/types'
+import type { ModelMessage, StreamChunk, Tool, UIMessage } from '../src/types'
+
+/** What one child run saw. */
+interface ChildRun {
+  agent: string
+  input: unknown
+  messages: Array<UIMessage | ModelMessage>
+}
+
+const runs: Array<ChildRun> = []
+
+const researcher = defineAgent({
+  name: 'researcher',
+  description: 'Looks up facts',
+  inputSchema: z.object({ topic: z.string() }),
+  run: async (ctx) => {
+    runs.push({ agent: 'researcher', input: ctx.input, messages: ctx.messages })
+    return `facts about ${ctx.input.topic}`
+  },
+})
+
+const writer = defineAgent({
+  name: 'writer',
+  description: 'Writes text',
+  run: async (ctx) => {
+    runs.push({ agent: 'writer', input: ctx.input, messages: ctx.messages })
+    return 'draft'
+  },
+})
+
+const agents = [researcher, writer]
+
+type Call = SubagentToolInput<typeof agents>
+
+beforeEach(() => {
+  runs.length = 0
+})
+
+/**
+ * A parent model that writes a line of text, calls the `subagent` tool once
+ * with `args`, then stops.
+ */
+function parentCalling(args: object) {
+  return createMockAdapter({
+    iterations: [
+      [
+        ev.runStarted(),
+        ev.textStart(),
+        ev.textContent('Asking a subagent.'),
+        ev.textEnd(),
+        ev.toolStart('call_1', 'subagent'),
+        ev.toolArgs('call_1', JSON.stringify(args)),
+        ev.runFinished('tool_calls'),
+      ],
+      [ev.runStarted(), ev.runFinished('stop')],
+    ],
+  })
+}
+
+/** The parsed result of tool call `call_1`. */
+function toolResult(chunks: Array<StreamChunk>) {
+  for (const chunk of chunks) {
+    if (
+      chunk.type === EventType.TOOL_CALL_RESULT &&
+      chunk.toolCallId === 'call_1' &&
+      typeof chunk.content === 'string'
+    ) {
+      return JSON.parse(chunk.content)
+    }
+  }
+  throw new Error('No result for call_1')
+}
+
+/** Run a parent chat with the single tool. The model calls it with `args`. */
+async function callSubagent(
+  args: object,
+  options: {
+    middleware?: Array<ChatMiddleware>
+    binding?: SubagentBinding
+    runId?: string
+  } = {},
+) {
+  const { adapter, calls } = parentCalling(args)
+  const chunks = await collectChunks(
+    chat({
+      adapter,
+      ...(options.runId !== undefined && { runId: options.runId }),
+      messages: [{ role: 'user', content: 'Go' }],
+      subagents: {
+        agents,
+        tool: 'single',
+        ...(options.binding && { binding: options.binding }),
+      },
+      ...(options.middleware && { middleware: options.middleware }),
+    }) as AsyncIterable<StreamChunk>,
+  )
+  return { chunks, calls, result: toolResult(chunks) }
+}
+
+/** A fake persistence middleware that provides the `loadChild` service. */
+function storedChildren(
+  stored: Map<string, Array<ModelMessage>>,
+): ChatMiddleware {
+  return {
+    name: 'stored-children',
+    setup(ctx) {
+      provideLoadChild(ctx, async (subagentRunId) => {
+        const messages = stored.get(subagentRunId)
+        return messages === undefined ? undefined : { messages }
+      })
+    },
+  }
+}
+
+const oldChild = new Map<string, Array<ModelMessage>>([
+  [
+    'subagent-old',
+    [
+      { role: 'user', content: 'Draft a tide report' },
+      { role: 'assistant', content: 'Tides rise twice a day.' },
+    ],
+  ],
+])
+
+describe('subagents tool: single', () => {
+  it('gives the model one subagent tool and runs an agent with its input', async () => {
+    const call: Call = { agent: 'researcher', input: { topic: 'tides' } }
+    const { calls, result } = await callSubagent(call)
+
+    const tools = calls[0]?.tools ?? []
+    expect(tools.map((tool) => tool.name)).toEqual(['subagent'])
+    expect(tools[0]?.inputSchema).toMatchObject({
+      type: 'object',
+      properties: { agent: { enum: ['researcher', 'writer'] } },
+      required: ['agent'],
+    })
+    expect(runs).toMatchObject([
+      { agent: 'researcher', input: { topic: 'tides' } },
+    ])
+    expect(result.result).toBe('facts about tides')
+  })
+
+  it('adds the prompt as the last user message of a child without inputSchema', async () => {
+    const call: Call = { agent: 'writer', prompt: 'Write a haiku' }
+    await callSubagent(call)
+
+    expect(runs).toHaveLength(1)
+    expect(runs[0]?.input).toBeUndefined()
+    expect(runs[0]?.messages).toMatchObject([
+      { role: 'user', content: 'Go' },
+      { role: 'assistant', content: 'Asking a subagent.' },
+      { role: 'user', content: 'Write a haiku' },
+    ])
+  })
+
+  it('continues a stored child by sessionId', async () => {
+    const call: Call = {
+      agent: 'writer',
+      sessionId: 'subagent-old',
+      prompt: 'Make it shorter',
+    }
+    const { result } = await callSubagent(call, {
+      middleware: [storedChildren(oldChild)],
+    })
+
+    expect(runs[0]?.messages).toEqual([
+      { role: 'user', content: 'Draft a tide report' },
+      { role: 'assistant', content: 'Tides rise twice a day.' },
+      { role: 'user', content: 'Make it shorter' },
+    ])
+    expect(result).toEqual({ subagentRunId: 'subagent-old', result: 'draft' })
+  })
+
+  it('gives the text of each continue its own message', async () => {
+    const call: Call = { agent: 'writer', sessionId: 'subagent-old' }
+    const ids: Array<string> = []
+    for (const runId of ['run-1', 'run-2']) {
+      const { chunks } = await callSubagent(call, {
+        middleware: [storedChildren(oldChild)],
+        runId,
+      })
+      for (const chunk of chunks) {
+        const isChildText =
+          chunk.type === EventType.TEXT_MESSAGE_START &&
+          'subagentRunId' in chunk &&
+          chunk.subagentRunId === 'subagent-old'
+        if (isChildText) ids.push(chunk.messageId)
+      }
+    }
+
+    expect(ids).toHaveLength(2)
+    expect(ids[0]).not.toBe(ids[1])
+  })
+
+  it('gives a resumed continued child each stored message once', async () => {
+    const stored: Array<ModelMessage> = [
+      { id: 'old-user', role: 'user', content: 'Draft a tide report' },
+      { id: 'old-reply', role: 'assistant', content: 'Tides rise twice.' },
+    ]
+    const waiting: ModelMessage = {
+      id: 'new-reply',
+      role: 'assistant',
+      content: 'Shorter like this?',
+    }
+    const turn: SubagentTurn = {
+      before: [],
+      children: [
+        {
+          subagentRunId: 'subagent-old',
+          name: 'writer',
+          status: 'suspended',
+          parentToolCallId: 'call_1',
+          // The card holds the whole child: the stored messages, then the
+          // call that waits.
+          messages: [...stored, waiting],
+          text: '',
+          resume: [
+            { interruptId: 'approval_1', status: 'resolved', payload: true },
+          ],
+        },
+      ],
+      rest: [],
+    }
+    const [tool] = createSyntheticSubagentTools(
+      { agents, tool: 'single' },
+      {
+        messages: [],
+        threadId: 'thread-1',
+        runId: 'run-2',
+        interruptedRunId: 'run-1',
+        turn,
+        sink: createSubagentSink(),
+        childLoader: () => async () => ({ messages: stored }),
+      },
+    )
+    await tool?.execute?.(
+      { agent: 'writer', sessionId: 'subagent-old', prompt: 'Make it shorter' },
+      { toolCallId: 'call_1', emitCustomEvent: () => {} },
+    )
+
+    expect(runs[0]?.messages).toEqual([
+      ...stored,
+      { role: 'user', content: 'Make it shorter' },
+      waiting,
+    ])
+  })
+
+  it('starts a background child through the start hook', async () => {
+    const start = vi.fn(async () => ({ subagentRunId: 'subagent-bg' }))
+    const call: Call = { agent: 'writer', prompt: 'Draft', background: true }
+    const { result } = await callSubagent(call, { binding: { start } })
+
+    expect(result).toEqual({
+      subagentRunId: 'subagent-bg',
+      result: { status: 'started' },
+    })
+    expect(start).toHaveBeenCalledWith(
+      { agent: 'writer', prompt: 'Draft', parentToolCallId: 'call_1' },
+      { wake: true },
+    )
+    expect(runs).toEqual([])
+  })
+
+  const toolErrors: Array<[string, object, Array<ChatMiddleware>, string]> = [
+    [
+      'a prompt for an agent with inputSchema',
+      { agent: 'researcher', prompt: 'tides' },
+      [],
+      'Agent "researcher" takes input, not prompt.',
+    ],
+    [
+      'no input for an agent with inputSchema',
+      { agent: 'researcher' },
+      [],
+      'Agent "researcher" needs input.',
+    ],
+    [
+      'an input for an agent without inputSchema',
+      { agent: 'writer', input: { topic: 'tides' } },
+      [],
+      'Agent "writer" takes prompt, not input.',
+    ],
+    [
+      'a sessionId without a persistence store',
+      { agent: 'writer', sessionId: 'subagent-old' },
+      [],
+      'sessionId needs a persistence store.',
+    ],
+    [
+      'an unknown sessionId',
+      { agent: 'writer', sessionId: 'subagent-missing' },
+      [storedChildren(oldChild)],
+      'Unknown sessionId "subagent-missing".',
+    ],
+    [
+      'background without a harness host',
+      { agent: 'writer', background: true },
+      [],
+      'background needs a harness host.',
+    ],
+    [
+      'background with a sessionId',
+      { agent: 'writer', background: true, sessionId: 'subagent-old' },
+      [],
+      'background cannot continue a sessionId.',
+    ],
+  ]
+  it.each(toolErrors)(
+    'returns a tool error for %s',
+    async (_label, args, middleware, error) => {
+      const { chunks, result } = await callSubagent(args, { middleware })
+
+      expect(result).toEqual({ error })
+      expect(runs).toEqual([])
+      // The parent run goes on after the tool error.
+      expect(chunks.some((chunk) => chunk.type === EventType.RUN_ERROR)).toBe(
+        false,
+      )
+    },
+  )
+
+  const namedSubagent = defineAgent({ ...writer, name: 'subagent' })
+  const takenNames: Array<[string, Array<DefinedAgent>, Array<Tool>]> = [
+    ['an agent', [researcher, namedSubagent], []],
+    ['a tool', agents, [serverTool('subagent', () => 'ok')]],
+  ]
+  it.each(takenNames)(
+    'throws when %s is named subagent',
+    (_label, named, tools) => {
+      const { adapter } = parentCalling({})
+      expect(() =>
+        chat({
+          adapter,
+          messages: [{ role: 'user', content: 'Go' }],
+          tools,
+          subagents: { agents: named, tool: 'single' },
+        }),
+      ).toThrow(`subagents.tool 'single' adds a tool named "subagent"`)
+    },
+  )
+
+  it('types the input as a union on agent', () => {
+    expectTypeOf<
+      Extract<Call, { agent: 'researcher' }>['input']
+    >().toEqualTypeOf<{ topic: string }>()
+    expectTypeOf<Extract<Call, { agent: 'writer' }>>().not.toHaveProperty(
+      'input',
+    )
+  })
+})
diff --git a/packages/ai/tests/tool-choice.test.ts b/packages/ai/tests/tool-choice.test.ts
new file mode 100644
index 0000000000..dac400fae6
--- /dev/null
+++ b/packages/ai/tests/tool-choice.test.ts
@@ -0,0 +1,113 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { chat } from '../src'
+import { createMockAdapter, ev, serverTool } from './test-utils'
+import type { ChatMiddleware, ToolChoice } from '../src'
+
+const toolTurn = (toolCallId: string) => [
+  ev.runStarted(),
+  ev.toolStart(toolCallId, 'lookup'),
+  ev.toolArgs(toolCallId, '{}'),
+  ev.toolEnd(toolCallId),
+  ev.runFinished('tool_calls'),
+]
+
+const stopTurn = [
+  ev.runStarted(),
+  ev.textContent('Done'),
+  ev.runFinished('stop'),
+]
+
+const lookup = serverTool('lookup', () => ({ ok: true }))
+
+/** Forces the `lookup` tool at the second model call only. */
+const lookupAtSecondCall: ChatMiddleware = {
+  name: 'lookup-at-second-call',
+  onConfig: (ctx) =>
+    ctx.phase === 'beforeModel' && ctx.iteration === 1
+      ? { toolChoice: { type: 'tool', name: 'lookup' } }
+      : undefined,
+}
+
+/** Run one chat() call with tools and three model calls. Give back each call's toolChoice. */
+async function toolChoiceOfThreeCalls(options: {
+  toolChoice: ToolChoice
+  middleware?: Array<ChatMiddleware>
+}) {
+  const { adapter, calls } = createMockAdapter({
+    iterations: [toolTurn('tc-1'), toolTurn('tc-2'), stopTurn],
+  })
+  await chat({
+    adapter,
+    messages: [{ role: 'user', content: 'Hi' }],
+    tools: [lookup],
+    stream: false,
+    ...options,
+  })
+  return calls.map((call) => call.toolChoice)
+}
+
+describe('chat({ toolChoice })', () => {
+  it('sends the chat() option on every model call', async () => {
+    const seen = await toolChoiceOfThreeCalls({ toolChoice: 'required' })
+    expect(seen).toStrictEqual(['required', 'required', 'required'])
+  })
+
+  it('lets onConfig change it for one model call only', async () => {
+    const seen = await toolChoiceOfThreeCalls({
+      toolChoice: 'auto',
+      middleware: [lookupAtSecondCall],
+    })
+    expect(seen).toStrictEqual([
+      'auto',
+      { type: 'tool', name: 'lookup' },
+      'auto',
+    ])
+  })
+
+  it('sends no toolChoice on a call with no tools', async () => {
+    const { adapter, calls } = createMockAdapter({ iterations: [stopTurn] })
+    await chat({
+      adapter,
+      messages: [{ role: 'user', content: 'Hi' }],
+      toolChoice: 'required',
+      stream: false,
+    })
+    expect(calls).toHaveLength(1)
+    expect(calls[0]).not.toHaveProperty('toolChoice')
+  })
+
+  it('keeps it out of the structured-output call and its middleware view', async () => {
+    let callHasToolChoice: boolean | undefined
+    let viewHasToolChoice: boolean | undefined
+    const { adapter, calls } = createMockAdapter({
+      iterations: [stopTurn],
+      structuredOutput: async (options) => {
+        callHasToolChoice = 'toolChoice' in options.chatOptions
+        return { data: { name: 'Ada' }, rawText: '{"name":"Ada"}' }
+      },
+    })
+    const result = await chat({
+      adapter,
+      messages: [{ role: 'user', content: 'Who?' }],
+      tools: [lookup],
+      toolChoice: 'required',
+      outputSchema: z.object({ name: z.string() }),
+      middleware: [
+        {
+          name: 'structured-view-recorder',
+          onStructuredOutputConfig: (_ctx, config) => {
+            viewHasToolChoice = 'toolChoice' in config
+          },
+        },
+      ],
+    })
+    expect(result).toEqual({ name: 'Ada' })
+    // The agent-loop call had it, so the option was on for this run.
+    expect(calls[0]?.toolChoice).toBe('required')
+    expect({ callHasToolChoice, viewHasToolChoice }).toStrictEqual({
+      callHasToolChoice: false,
+      viewHasToolChoice: false,
+    })
+  })
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 71a5e44db5..a6b2abfd1f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2802,6 +2802,12 @@ importers:
       '@vitest/coverage-v8':
         specifier: 4.1.10
         version: 4.1.10(vitest@4.1.11)
+      '@vscode/ripgrep':
+        specifier: ^1.18.0
+        version: 1.18.0
+      turndown:
+        specifier: ^7.2.4
+        version: 7.2.4
       zod:
         specifier: ^4.2.0
         version: 4.3.6
@@ -3695,7 +3701,7 @@ importers:
     devDependencies:
       '@google/genai':
         specifier: ^2.10.0
-        version: 2.10.0(@modelcontextprotocol/sdk@1.29.0(zod@4.3.6))
+        version: 2.10.0(@modelcontextprotocol/sdk@1.29.0(zod@4.6.5))
       '@tanstack/ai':
         specifier: workspace:*
         version: link:../ai
@@ -6809,6 +6815,9 @@ packages:
   '@mistralai/mistralai@2.2.0':
     resolution: {integrity: sha512-JQUGIXjFWnw/J9LpTSf/ZXwVW3Sh8FBAcfTo5QvAHqkl4CfSiIwnjRJhMoAFcP6ncCe84YPU1ncDGX+p3OXnfg==}
 
+  '@mixmark-io/domino@2.2.0':
+    resolution: {integrity: sha512-Y28PR25bHXUg88kCV7nivXrP2Nj2RueZ3/l/jdx6J9f8J4nsEGcgX0Qe6lt7Pa+J79+kPiJU3LguR6O/6zrLOw==}
+
   '@modelcontextprotocol/client@2.1.0':
     resolution: {integrity: sha512-mDVhoy5WjDb0U+4dQPzLcciC2erSex/GRVQqnoZdiuMoE3YiTZdiS7ezNcFwX4XEOWOaj7jZr0kLYnILnL8orA==}
     engines: {node: '>=20'}
@@ -8297,24 +8306,48 @@ packages:
     cpu: [arm64]
     os: [android]
 
+  '@parcel/watcher-android-arm64@2.6.0':
+    resolution: {integrity: sha512-trgpLSCKRC/huFjXX/Smh+0sWe4+YtKfktIToiMl59ghz7z+qkH6kMvNnUbLyRs9N11t8l4svSCs1+5B3rOAhA==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [android]
+
   '@parcel/watcher-darwin-arm64@2.5.1':
     resolution: {integrity: sha512-eAzPv5osDmZyBhou8PoF4i6RQXAfeKL9tjb3QzYuccXFMQU0ruIc/POh30ePnaOyD1UXdlKguHBmsTs53tVoPw==}
     engines: {node: '>= 10.0.0'}
     cpu: [arm64]
     os: [darwin]
 
+  '@parcel/watcher-darwin-arm64@2.6.0':
+    resolution: {integrity: sha512-Y3QV0gl7Q1zbfueunkWIERICbEojQFCgpyG7YqOGNFLsckXyI1xu9mAIUpKY9QBYzBtSkN8dBPwd3yiAO9ovMw==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
   '@parcel/watcher-darwin-x64@2.5.1':
     resolution: {integrity: sha512-1ZXDthrnNmwv10A0/3AJNZ9JGlzrF82i3gNQcWOzd7nJ8aj+ILyW1MTxVk35Db0u91oD5Nlk9MBiujMlwmeXZg==}
     engines: {node: '>= 10.0.0'}
     cpu: [x64]
     os: [darwin]
 
+  '@parcel/watcher-darwin-x64@2.6.0':
+    resolution: {integrity: sha512-Ohv6OpzhUfKYD7Beb8kDvG0jbIxORCYY1JRdZnaBtnjjkJxgD7ZVL0nw2sCYd0yTMKTvz3nnTnOF3cDifK+kvw==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
   '@parcel/watcher-freebsd-x64@2.5.1':
     resolution: {integrity: sha512-SI4eljM7Flp9yPuKi8W0ird8TI/JK6CSxju3NojVI6BjHsTyK7zxA9urjVjEKJ5MBYC+bLmMcbAWlZ+rFkLpJQ==}
     engines: {node: '>= 10.0.0'}
     cpu: [x64]
     os: [freebsd]
 
+  '@parcel/watcher-freebsd-x64@2.6.0':
+    resolution: {integrity: sha512-5HmXvDgs8VK+74jF9y9/2FE3/OnlcKmc56tjmSrEuZjpSZOGL+fvAu+HKJBdPs9uwoP2hE6TlSUpXZ/C5jUFmQ==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
   '@parcel/watcher-linux-arm-glibc@2.5.1':
     resolution: {integrity: sha512-RCdZlEyTs8geyBkkcnPWvtXLY44BCeZKmGYRtSgtwwnHR4dxfHRG3gR99XdMEdQ7KeiDdasJwwvNSF5jKtDwdA==}
     engines: {node: '>= 10.0.0'}
@@ -8322,6 +8355,13 @@ packages:
     os: [linux]
     libc: [glibc]
 
+  '@parcel/watcher-linux-arm-glibc@2.6.0':
+    resolution: {integrity: sha512-Ps/hui3A+vMbjdqlqAowK2ZL8+BO8dBjxeWXj6npTBs3jx4wWmbPpaLuqwrQrSqIVMCnpWo238bJ1U37GhQOYg==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm]
+    os: [linux]
+    libc: [glibc]
+
   '@parcel/watcher-linux-arm-musl@2.5.1':
     resolution: {integrity: sha512-6E+m/Mm1t1yhB8X412stiKFG3XykmgdIOqhjWj+VL8oHkKABfu/gjFj8DvLrYVHSBNC+/u5PeNrujiSQ1zwd1Q==}
     engines: {node: '>= 10.0.0'}
@@ -8329,6 +8369,13 @@ packages:
     os: [linux]
     libc: [musl]
 
+  '@parcel/watcher-linux-arm-musl@2.6.0':
+    resolution: {integrity: sha512-9c6AUHgHoG+IY88MRIHupztQiQnrbqHYQjkM2btA+Bf/wQnQMuiD0Wfk1EVv3TlNT3x41uU71rn6E4xh/+zvkw==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm]
+    os: [linux]
+    libc: [musl]
+
   '@parcel/watcher-linux-arm64-glibc@2.5.1':
     resolution: {integrity: sha512-LrGp+f02yU3BN9A+DGuY3v3bmnFUggAITBGriZHUREfNEzZh/GO06FF5u2kx8x+GBEUYfyTGamol4j3m9ANe8w==}
     engines: {node: '>= 10.0.0'}
@@ -8336,6 +8383,13 @@ packages:
     os: [linux]
     libc: [glibc]
 
+  '@parcel/watcher-linux-arm64-glibc@2.6.0':
+    resolution: {integrity: sha512-yHRqS2owEXe6Hic9z6Mh1ECsCd+ODVOGvZDyciqRd21+v+o+DnXMOrw50DSpIG2sb8GPEaPPmfeCAWKPJdq46g==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
   '@parcel/watcher-linux-arm64-musl@2.5.1':
     resolution: {integrity: sha512-cFOjABi92pMYRXS7AcQv9/M1YuKRw8SZniCDw0ssQb/noPkRzA+HBDkwmyOJYp5wXcsTrhxO0zq1U11cK9jsFg==}
     engines: {node: '>= 10.0.0'}
@@ -8343,6 +8397,13 @@ packages:
     os: [linux]
     libc: [musl]
 
+  '@parcel/watcher-linux-arm64-musl@2.6.0':
+    resolution: {integrity: sha512-WhB2e/V7rqdHHWZusBSPuy5Ei8S6lSz6FE5TKKQz5h3a0O+C+mhY7vxU9b/stqvMb8beLnPY82ZrFTLKs+SrKA==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
   '@parcel/watcher-linux-x64-glibc@2.5.1':
     resolution: {integrity: sha512-GcESn8NZySmfwlTsIur+49yDqSny2IhPeZfXunQi48DMugKeZ7uy1FX83pO0X22sHntJ4Ub+9k34XQCX+oHt2A==}
     engines: {node: '>= 10.0.0'}
@@ -8350,6 +8411,13 @@ packages:
     os: [linux]
     libc: [glibc]
 
+  '@parcel/watcher-linux-x64-glibc@2.6.0':
+    resolution: {integrity: sha512-ulGE6x6Oz6iAwg75T8YQSoguBWasniIbX+QWpaYPcCnDOpdWX3k+4xbEYPZVLxOuoJI+svJJPD3sEj8G7lrQ3A==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
   '@parcel/watcher-linux-x64-musl@2.5.1':
     resolution: {integrity: sha512-n0E2EQbatQ3bXhcH2D1XIAANAcTZkQICBPVaxMeaCVBtOpBZpWJuf7LwyWPSBDITb7In8mqQgJ7gH8CILCURXg==}
     engines: {node: '>= 10.0.0'}
@@ -8357,6 +8425,13 @@ packages:
     os: [linux]
     libc: [musl]
 
+  '@parcel/watcher-linux-x64-musl@2.6.0':
+    resolution: {integrity: sha512-tkBYKt7YQrjIJWYDnto2YgO8MRkjlMTSNoRHzsXinBqbLdeOM3L32wPZJvIZxqaLMfSlS/4sUjH/6STVP/XDLw==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
   '@parcel/watcher-wasm@2.5.1':
     resolution: {integrity: sha512-RJxlQQLkaMMIuWRozy+z2vEqbaQlCuaCgVZIUCzQLYggY22LZbP5Y1+ia+FD724Ids9e+XIyOLXLrLgQSHIthw==}
     engines: {node: '>= 10.0.0'}
@@ -8369,6 +8444,12 @@ packages:
     cpu: [arm64]
     os: [win32]
 
+  '@parcel/watcher-win32-arm64@2.6.0':
+    resolution: {integrity: sha512-gIZAP23jaHjGWasY/TY6yL7NHFClf0Ga7FN+iINvk+KN94rhm94lYZhFsbYFNcA04/onvGD9kKmiJLJB2HbNwQ==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
   '@parcel/watcher-win32-ia32@2.5.1':
     resolution: {integrity: sha512-c2KkcVN+NJmuA7CGlaGD1qJh1cLfDnQsHjE89E60vUEMlqduHGCdCLJCID5geFVM0dOtA3ZiIO8BoEQmzQVfpQ==}
     engines: {node: '>= 10.0.0'}
@@ -8381,6 +8462,12 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@parcel/watcher-win32-x64@2.6.0':
+    resolution: {integrity: sha512-cA+/pXV2YkfxlIcXOQ5fSWqAzzPyD78/x5qbK/I0vUkrlYHA8TIz+MXjAbGouguKVSI4bOmkTSJ1/poVSsgt+A==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [win32]
+
   '@parcel/watcher@2.5.1':
     resolution: {integrity: sha512-dfUnCxiN9H4ap84DvD2ubjw+3vUNpstxa0TneY/Paat8a3R4uQZDLSvWjmznAY/DoahqTHl9V46HF/Zs3F29pg==}
     engines: {node: '>= 10.0.0'}
@@ -10711,20 +10798,14 @@ packages:
       vite:
         optional: true
 
-  '@tanstack/react-store@0.11.2':
-    resolution: {integrity: sha512-oj5O5DmiMWE+ih+SioX2ayC1kbK7d3fpLx0B75fPJr9nY3zU+hoW010yr64qXsY/9fyiLVE2bn5mGNV3owm8RQ==}
-    peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-
   '@tanstack/react-store@0.11.1':
     resolution: {integrity: sha512-HaIGKI3YLmjBYIvy5DFDY23oNaYZIsTZfngey07Uh5iLVJgM3bIGCnZeOFOqzjFld9JHWcaHJnasD/bKoGKwJQ==}
     peerDependencies:
       react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
       react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
-  '@tanstack/react-store@0.8.0':
-    resolution: {integrity: sha512-1vG9beLIuB7q69skxK9r5xiLN3ztzIPfSQSs0GfeqWGO2tGIyInZx0x1COhpx97RKaONSoAb8C3dxacWksm1ow==}
+  '@tanstack/react-store@0.11.2':
+    resolution: {integrity: sha512-oj5O5DmiMWE+ih+SioX2ayC1kbK7d3fpLx0B75fPJr9nY3zU+hoW010yr64qXsY/9fyiLVE2bn5mGNV3owm8RQ==}
     peerDependencies:
       react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
       react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
@@ -10864,11 +10945,6 @@ packages:
     peerDependencies:
       solid-js: ^1.6.0
 
-  '@tanstack/solid-store@0.8.0':
-    resolution: {integrity: sha512-JwqTedbxyOGw7mfmdGkB0RGgefRCw/tNauc8tlMcaS1mV5wTFT8c1KIB3LgttuHaanMJEBeqQJ7bc/R0WTP1fA==}
-    peerDependencies:
-      solid-js: ^1.6.0
-
   '@tanstack/start-client-core@1.170.34':
     resolution: {integrity: sha512-LfwZSbau2MLLZ/uPAoO+NC9fK3J66c0wLhnNQqIa+Goqw7bXPjkHwlsjY7evlUz1AnyhhQ1Qab95v+VmP0TZ9A==}
     engines: {node: '>=22.12.0'}
@@ -10903,9 +10979,6 @@ packages:
   '@tanstack/store@0.11.2':
     resolution: {integrity: sha512-sJ4mjol8uQsHV0gOJzzjwXfh2Fwm+Sz0+8deqiTm4jGbMdjzNSW+xZCFm0kUa870uhd8yi+DpKnZb5Kc4apa0Q==}
 
-  '@tanstack/store@0.8.0':
-    resolution: {integrity: sha512-Om+BO0YfMZe//X2z0uLF2j+75nQga6TpTJgLJQBiq85aOyZNIhkCgleNcud2KQg4k4v9Y9l+Uhru3qWMPGTOzQ==}
-
   '@tanstack/typedoc-config@0.3.4':
     resolution: {integrity: sha512-WXJavpiNqumNwdBQTM3wBqbHaULgoZ3cIri7xJinKqX/mOGXgc6ZghfAardD2PydP8tOcPf+xhrd1Qk/am9DMg==}
     engines: {node: '>=18'}
@@ -11575,6 +11648,69 @@ packages:
   '@volar/typescript@2.4.27':
     resolution: {integrity: sha512-eWaYCcl/uAPInSK2Lze6IqVWaBu/itVqR5InXcHXFyles4zO++Mglt3oxdgj75BDcv1Knr9Y93nowS8U3wqhxg==}
 
+  '@vscode/ripgrep-darwin-arm64@1.18.0':
+    resolution: {integrity: sha512-r3ktHSvbFycQNF6sl7sNDPocpsI7J+mEzh1IaZFkY0spm3k2Z9t8hPAeOK7+p0l6p6/swkQC14XWX01low+94Q==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@vscode/ripgrep-darwin-x64@1.18.0':
+    resolution: {integrity: sha512-25b4gWbL138dGuQU244ebCKKc0q05ULBMoFSz9oAEUHNeqK/lOJViDS7DRvbDazzAzSEdan391Znks/R5mkaTQ==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@vscode/ripgrep-linux-arm64@1.18.0':
+    resolution: {integrity: sha512-lQ/5zTG++U0E3IhVgS4EPTTn/U4okncaRMM5GOFfOYZywS4nuD31GhkHbNYlDk5CuDC68+hYJ0/eQeyCKJDA+g==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@vscode/ripgrep-linux-arm@1.18.0':
+    resolution: {integrity: sha512-GDAvufNDHu8zqLEmXstalQF0Wh6wQvdsBi/Vg3Yi3CK4a8XoFXqqXVEHEZ9xQz3t0NfoSEc9JbvK9DDS6FxyxQ==}
+    cpu: [arm]
+    os: [linux]
+
+  '@vscode/ripgrep-linux-ia32@1.18.0':
+    resolution: {integrity: sha512-YWLkSUtFd4Jh5EepIhA9RJSfv3uMAVMo+2rBIGHPBnvgLrZciIs2cDKei1/p6Wc/aCzUoHyMAg2R6tw4ZCBKGg==}
+    cpu: [ia32]
+    os: [linux]
+
+  '@vscode/ripgrep-linux-ppc64@1.18.0':
+    resolution: {integrity: sha512-quXVY8fwQ8O/lvU1yrSqSl3jlUzysRSb+AfUfCL/tRtphxsKlFvPAejryZ6vg4Bgvn8XL74xb4qMCDmWgYrT5w==}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@vscode/ripgrep-linux-riscv64@1.18.0':
+    resolution: {integrity: sha512-f5kBQBrWfQt8Q7OhSORuNDei5dkYagBj3y4jImSUXGMy8B/Ke7SltSRcUtjPv166FAFfHCAmWuZp3+cWnX2/Vw==}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@vscode/ripgrep-linux-s390x@1.18.0':
+    resolution: {integrity: sha512-rTOcJFGGcl2c07RUOWUo4U1ndnemKhY6A9hnMB18uk7jSgJc0d/QLBGWMWpumdtoJtpizn/wIv5mXIisJukusQ==}
+    cpu: [s390x]
+    os: [linux]
+
+  '@vscode/ripgrep-linux-x64@1.18.0':
+    resolution: {integrity: sha512-mQ3bVrUpnD2vs7QT0vX90Lt0cnUq467uFtEktIdsJJmW296RoSULRGqWgzG1AKxyBpNDD6l4ZO4qKf6SgyC23Q==}
+    cpu: [x64]
+    os: [linux]
+
+  '@vscode/ripgrep-win32-arm64@1.18.0':
+    resolution: {integrity: sha512-vfTIjq1OHnzUjxZcHVQAMbnggp8dpGf+0QKFOZHwWPqFwXxQC8eCWM+5NUdoJ6yrElCeMzoUTXoK/LdZaniB+Q==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@vscode/ripgrep-win32-ia32@1.18.0':
+    resolution: {integrity: sha512-//rfAE+BOw5AC2EMmepmiE36jUuevtQYNQqqlw1s3m9FlRxjxEut97RkRPHAu9BG4mSojatZx+kXZXNdyI9caQ==}
+    cpu: [ia32]
+    os: [win32]
+
+  '@vscode/ripgrep-win32-x64@1.18.0':
+    resolution: {integrity: sha512-KNPvtElldqILHdnAetujPaowkNbpqJy3ssIGGN6F6Kve9Qi+nNLI2DN01O83JjCEVQbCzl8Ov3QZ9Eov3BR8Dg==}
+    cpu: [x64]
+    os: [win32]
+
+  '@vscode/ripgrep@1.18.0':
+    resolution: {integrity: sha512-ns5lWe44tSfbTMbVUsyB+I1819PVSw4AdpgK0RNkzfWfwy6+3IUNSxwSrfTno1/oWaS/hERNz+XLWVyga2aJBQ==}
+
   '@vue/compiler-core@3.5.25':
     resolution: {integrity: sha512-vay5/oQJdsNHmliWoZfHPoVZZRmnSWhug0BYT34njkYTPqClh3DNWLkZNJBVSjsNMrg0CCrBfoKkjZQPM/QVUw==}
 
@@ -12322,10 +12458,6 @@ packages:
   classnames@2.5.1:
     resolution: {integrity: sha512-saHYOzhIQs6wy2sVxTM6bUDsQO4F50V9RQ22qBpEdCW+I+/Wmke2HOl6lS6dTpdxVhb88/I6+Hs+438c3lfUow==}
 
-  cli-boxes@3.0.0:
-    resolution: {integrity: sha512-/lzGpEWL/8PfI0BmBOPRwp0c/wFNX1RdUML3jK/RcSBA9T8mZDdQpqYBKtCFTOfQbwPqWEOpjqW+Fnayc0969g==}
-    engines: {node: '>=10'}
-
   cli-boxes@4.0.1:
     resolution: {integrity: sha512-5IOn+jcCEHEraYolBPs/sT4BxYCe2nHg374OPiItB1O96KZFseS2gthU4twyYzeDcFew4DaUM/xwc5BQf08JJw==}
     engines: {node: '>=18.20 <19 || >=20.10'}
@@ -17740,6 +17872,10 @@ packages:
   tunnel-agent@0.6.0:
     resolution: {integrity: sha512-McnNiV1l8RYeY8tBgEpuodCC1mLUdbSN+CYBL7kJsJNInOP8UjDDEwdk6Mw60vdLLrr5NHKZhMAOSrR2NZuQ+w==}
 
+  turndown@7.2.4:
+    resolution: {integrity: sha512-I8yFsfRzmzK0WV1pNNOA4A7y4RDfFxPRxb3t+e3ui14qSGOxGtiSP6GjeX+Y6CHb7HYaFj7ECUD7VE5kQMZWGQ==}
+    engines: {node: '>=18', npm: '>=9'}
+
   tw-animate-css@1.4.0:
     resolution: {integrity: sha512-7bziOlRqH0hJx80h/3mbicLW7o8qLsH5+RaLR2t+OHM3D0JlWGODQKQ4cxbK7WlvmUxpcj6Kgu6EKqjrGFe3QQ==}
 
@@ -17758,10 +17894,6 @@ packages:
     resolution: {integrity: sha512-Ne2YiiGN8bmrmJJEuTWTLJR32nh/JdL1+PSicowtNb0WFpn59GK8/lfD61bVtzguz7b3PBt74nxpv/Pw5po5Rg==}
     engines: {node: '>=8'}
 
-  type-fest@2.19.0:
-    resolution: {integrity: sha512-RAH822pAdBgcNMAfWnCBU3CFZcfZ/i1eZjwFU/dsLKumyuuP3niueg2UAukXYF0E2AAoc82ZSSf9J0WQBinzHA==}
-    engines: {node: '>=12.20'}
-
   type-fest@5.10.0:
     resolution: {integrity: sha512-NoSdpq/WEiAg5sjmBkmV/hfxv6HJH4NqPNrqjtSO5CwRmpsDfaf4begxW34KdJykH/l1yHtwBWQkCRdoXO8mPA==}
     engines: {node: '>=20'}
@@ -18659,10 +18791,6 @@ packages:
     engines: {node: '>=8'}
     hasBin: true
 
-  widest-line@4.0.1:
-    resolution: {integrity: sha512-o0cyEG0e8GPzT4iGHphIOh0cJOV8fivsXxddQasHPHfoZf1ZexrfeA21w2NaEN1RHE+fXlfISmOE8R9N3u3Qig==}
-    engines: {node: '>=12'}
-
   widest-line@6.0.0:
     resolution: {integrity: sha512-U89AsyEeAsyoF0zVJBkG9zBgekjgjK7yk9sje3F4IQpXBJ10TF6ByLlIfjMhcmHMJgHZI4KHt4rdNfktzxIAMA==}
     engines: {node: '>=20'}
@@ -22659,6 +22787,8 @@ snapshots:
       - bufferutil
       - utf-8-validate
 
+  '@mixmark-io/domino@2.2.0': {}
+
   '@modelcontextprotocol/client@2.1.0':
     dependencies:
       '@modelcontextprotocol/core': 2.1.0
@@ -23779,33 +23909,63 @@ snapshots:
   '@parcel/watcher-android-arm64@2.5.1':
     optional: true
 
+  '@parcel/watcher-android-arm64@2.6.0':
+    optional: true
+
   '@parcel/watcher-darwin-arm64@2.5.1':
     optional: true
 
+  '@parcel/watcher-darwin-arm64@2.6.0':
+    optional: true
+
   '@parcel/watcher-darwin-x64@2.5.1':
     optional: true
 
+  '@parcel/watcher-darwin-x64@2.6.0':
+    optional: true
+
   '@parcel/watcher-freebsd-x64@2.5.1':
     optional: true
 
+  '@parcel/watcher-freebsd-x64@2.6.0':
+    optional: true
+
   '@parcel/watcher-linux-arm-glibc@2.5.1':
     optional: true
 
+  '@parcel/watcher-linux-arm-glibc@2.6.0':
+    optional: true
+
   '@parcel/watcher-linux-arm-musl@2.5.1':
     optional: true
 
+  '@parcel/watcher-linux-arm-musl@2.6.0':
+    optional: true
+
   '@parcel/watcher-linux-arm64-glibc@2.5.1':
     optional: true
 
+  '@parcel/watcher-linux-arm64-glibc@2.6.0':
+    optional: true
+
   '@parcel/watcher-linux-arm64-musl@2.5.1':
     optional: true
 
+  '@parcel/watcher-linux-arm64-musl@2.6.0':
+    optional: true
+
   '@parcel/watcher-linux-x64-glibc@2.5.1':
     optional: true
 
+  '@parcel/watcher-linux-x64-glibc@2.6.0':
+    optional: true
+
   '@parcel/watcher-linux-x64-musl@2.5.1':
     optional: true
 
+  '@parcel/watcher-linux-x64-musl@2.6.0':
+    optional: true
+
   '@parcel/watcher-wasm@2.5.1':
     dependencies:
       is-glob: 4.0.3
@@ -23814,12 +23974,18 @@ snapshots:
   '@parcel/watcher-win32-arm64@2.5.1':
     optional: true
 
+  '@parcel/watcher-win32-arm64@2.6.0':
+    optional: true
+
   '@parcel/watcher-win32-ia32@2.5.1':
     optional: true
 
   '@parcel/watcher-win32-x64@2.5.1':
     optional: true
 
+  '@parcel/watcher-win32-x64@2.6.0':
+    optional: true
+
   '@parcel/watcher@2.5.1':
     dependencies:
       detect-libc: 1.0.3
@@ -23847,6 +24013,19 @@ snapshots:
       is-glob: 4.0.3
       node-addon-api: 7.1.1
       picomatch: 4.0.7
+    optionalDependencies:
+      '@parcel/watcher-android-arm64': 2.6.0
+      '@parcel/watcher-darwin-arm64': 2.6.0
+      '@parcel/watcher-darwin-x64': 2.6.0
+      '@parcel/watcher-freebsd-x64': 2.6.0
+      '@parcel/watcher-linux-arm-glibc': 2.6.0
+      '@parcel/watcher-linux-arm-musl': 2.6.0
+      '@parcel/watcher-linux-arm64-glibc': 2.6.0
+      '@parcel/watcher-linux-arm64-musl': 2.6.0
+      '@parcel/watcher-linux-x64-glibc': 2.6.0
+      '@parcel/watcher-linux-x64-musl': 2.6.0
+      '@parcel/watcher-win32-arm64': 2.6.0
+      '@parcel/watcher-win32-x64': 2.6.0
     optional: true
 
   '@pkgjs/parseargs@0.11.0':
@@ -27336,13 +27515,6 @@ snapshots:
       react-dom: 19.2.3(react@19.2.3)
       use-sync-external-store: 1.6.0(react@19.2.3)
 
-  '@tanstack/react-store@0.8.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
-    dependencies:
-      '@tanstack/store': 0.8.0
-      react: 19.2.3
-      react-dom: 19.2.3(react@19.2.3)
-      use-sync-external-store: 1.6.0(react@19.2.3)
-
   '@tanstack/router-core@1.171.34':
     dependencies:
       '@tanstack/history': 1.162.4
@@ -27549,11 +27721,6 @@ snapshots:
       '@tanstack/store': 0.11.1
       solid-js: 1.9.10
 
-  '@tanstack/solid-store@0.8.0(solid-js@1.9.10)':
-    dependencies:
-      '@tanstack/store': 0.8.0
-      solid-js: 1.9.10
-
   '@tanstack/start-client-core@1.170.34':
     dependencies:
       '@tanstack/router-core': 1.171.34
@@ -27680,8 +27847,6 @@ snapshots:
       - vite-plugin-solid
       - webpack
 
-  '@tanstack/store@0.11.1': {}
-
   '@tanstack/start-server-core@1.169.39(crossws@0.4.6(srvx@0.11.17))':
     dependencies:
       '@tanstack/history': 1.162.4
@@ -27710,9 +27875,9 @@ snapshots:
     dependencies:
       '@tanstack/router-core': 1.171.34
 
-  '@tanstack/store@0.11.2': {}
+  '@tanstack/store@0.11.1': {}
 
-  '@tanstack/store@0.8.0': {}
+  '@tanstack/store@0.11.2': {}
 
   '@tanstack/typedoc-config@0.3.4':
     dependencies:
@@ -28620,6 +28785,57 @@ snapshots:
       path-browserify: 1.0.1
       vscode-uri: 3.1.0
 
+  '@vscode/ripgrep-darwin-arm64@1.18.0':
+    optional: true
+
+  '@vscode/ripgrep-darwin-x64@1.18.0':
+    optional: true
+
+  '@vscode/ripgrep-linux-arm64@1.18.0':
+    optional: true
+
+  '@vscode/ripgrep-linux-arm@1.18.0':
+    optional: true
+
+  '@vscode/ripgrep-linux-ia32@1.18.0':
+    optional: true
+
+  '@vscode/ripgrep-linux-ppc64@1.18.0':
+    optional: true
+
+  '@vscode/ripgrep-linux-riscv64@1.18.0':
+    optional: true
+
+  '@vscode/ripgrep-linux-s390x@1.18.0':
+    optional: true
+
+  '@vscode/ripgrep-linux-x64@1.18.0':
+    optional: true
+
+  '@vscode/ripgrep-win32-arm64@1.18.0':
+    optional: true
+
+  '@vscode/ripgrep-win32-ia32@1.18.0':
+    optional: true
+
+  '@vscode/ripgrep-win32-x64@1.18.0':
+    optional: true
+
+  '@vscode/ripgrep@1.18.0':
+    optionalDependencies:
+      '@vscode/ripgrep-darwin-arm64': 1.18.0
+      '@vscode/ripgrep-darwin-x64': 1.18.0
+      '@vscode/ripgrep-linux-arm': 1.18.0
+      '@vscode/ripgrep-linux-arm64': 1.18.0
+      '@vscode/ripgrep-linux-ia32': 1.18.0
+      '@vscode/ripgrep-linux-ppc64': 1.18.0
+      '@vscode/ripgrep-linux-riscv64': 1.18.0
+      '@vscode/ripgrep-linux-s390x': 1.18.0
+      '@vscode/ripgrep-linux-x64': 1.18.0
+      '@vscode/ripgrep-win32-arm64': 1.18.0
+      '@vscode/ripgrep-win32-ia32': 1.18.0
+      '@vscode/ripgrep-win32-x64': 1.18.0
+
   '@vue/compiler-core@3.5.25':
     dependencies:
       '@babel/parser': 7.29.9
@@ -29588,8 +29804,6 @@ snapshots:
   classnames@2.5.1:
     optional: true
 
-  cli-boxes@3.0.0: {}
-
   cli-boxes@4.0.1: {}
 
   cli-cursor@2.1.0:
@@ -36940,6 +37154,10 @@ snapshots:
       safe-buffer: 5.2.1
     optional: true
 
+  turndown@7.2.4:
+    dependencies:
+      '@mixmark-io/domino': 2.2.0
+
   tw-animate-css@1.4.0: {}
 
   tweetnacl@0.14.5: {}
@@ -36952,8 +37170,6 @@ snapshots:
 
   type-fest@0.7.1: {}
 
-  type-fest@2.19.0: {}
-
   type-fest@5.10.0:
     dependencies:
       tagged-tag: 1.0.0
@@ -37907,10 +38123,6 @@ snapshots:
       siginfo: 2.0.0
       stackback: 0.0.2
 
-  widest-line@4.0.1:
-    dependencies:
-      string-width: 5.1.2
-
   widest-line@6.0.0:
     dependencies:
       string-width: 8.2.2

From 35965d9496b57f6ac088e8194c2266e3cd0b7a77 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 09:52:05 +0200
Subject: [PATCH 239/286] feat(ai-harness): add the status feed, child
 sessions, and coding tool parts

Checkpoint 2 of the opencode primitives plan.

- Host status feed: host.events(), GET host-events, and the client
  hostEvents() helper, filtered to the sessions a principal may see (C5).
- Child sessions: subagent runs and background agents get index entries,
  and the single subagent tool can start a child in the background (C6).
- Coding tools: edit_file matches through Unicode forms and trailing
  spaces and keeps CRLF and the BOM; a patch tool with a parser and an
  all-or-nothing applier; bash with a fail-closed command splitter,
  AGENT=1, per-call timeouts, tail output, spill files, and background
  jobs (PL1).
- boundToolOutput limits every tool result, also in subagents (PL1).
- Permission path rules ignore letter case on macOS and Windows hosts.
---
 packages/ai-harness/src/client.ts             | 119 +++--
 .../src/first-party/bound-output.ts           | 241 ++++++++++
 .../ai-harness/src/first-party/coding/bash.ts | 216 ++++++++-
 .../ai-harness/src/first-party/coding/edit.ts | 128 +++++-
 .../src/first-party/coding/patch.ts           | 384 ++++++++++++++++
 .../ai-harness/src/first-party/permissions.ts |  15 +-
 packages/ai-harness/src/host.ts               | 176 +++++++-
 packages/ai-harness/src/http.ts               |  79 +++-
 packages/ai-harness/src/index.ts              |   4 +
 packages/ai-harness/src/session.ts            | 131 +++++-
 .../ai-harness/tests/bound-output.test.ts     | 311 +++++++++++++
 packages/ai-harness/tests/coding-bash.test.ts | 256 +++++++++++
 packages/ai-harness/tests/coding-edit.test.ts | 162 +++++++
 .../ai-harness/tests/coding-patch.test.ts     | 415 ++++++++++++++++++
 packages/ai-harness/tests/permissions.test.ts |  33 +-
 packages/ai-harness/tests/status-feed.test.ts | 247 +++++++++++
 .../tests/subagent-children.test.ts           | 172 ++++++++
 17 files changed, 2997 insertions(+), 92 deletions(-)
 create mode 100644 packages/ai-harness/src/first-party/bound-output.ts
 create mode 100644 packages/ai-harness/src/first-party/coding/patch.ts
 create mode 100644 packages/ai-harness/tests/bound-output.test.ts
 create mode 100644 packages/ai-harness/tests/coding-bash.test.ts
 create mode 100644 packages/ai-harness/tests/coding-edit.test.ts
 create mode 100644 packages/ai-harness/tests/coding-patch.test.ts
 create mode 100644 packages/ai-harness/tests/status-feed.test.ts
 create mode 100644 packages/ai-harness/tests/subagent-children.test.ts

diff --git a/packages/ai-harness/src/client.ts b/packages/ai-harness/src/client.ts
index 71830f2791..164397f9bb 100644
--- a/packages/ai-harness/src/client.ts
+++ b/packages/ai-harness/src/client.ts
@@ -9,6 +9,7 @@ import type {
 } from '@tanstack/ai-persistence'
 import type { AgentInputOf } from './agents'
 import type { AnyHarness, HarnessAgentsOf } from './define'
+import type { HostEvent } from './host'
 import type { SessionDescription, SessionSnapshot } from './session'
 import type {
   BusyPolicy,
@@ -30,6 +31,12 @@ export {
   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`. */
@@ -104,6 +111,13 @@ export interface HarnessClient<THarness extends AnyHarness> {
     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>>
@@ -155,6 +169,41 @@ type SessionChange =
   | { 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,
@@ -301,41 +350,21 @@ export function createHarnessClient<THarness extends AnyHarness>(
           throw new Error(`Harness events failed (${response.status})`)
         }
         eventOptions.onConnection?.('open')
-        const reader = response.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 = ''
-        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
-            const frame: unknown = JSON.parse(data)
-            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
+        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) {
@@ -351,6 +380,27 @@ export function createHarnessClient<THarness extends AnyHarness>(
     }
   }
 
+  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'
@@ -397,6 +447,7 @@ export function createHarnessClient<THarness extends AnyHarness>(
     command: (name, input) => send({ op: 'command', name, input }),
     setConfig: (key, value) => send({ op: 'config', key, value }),
     events,
+    hostEvents,
     snapshot: () => read('snapshot'),
     transcript: () => read('transcript'),
     describe: () => read('describe'),
diff --git a/packages/ai-harness/src/first-party/bound-output.ts b/packages/ai-harness/src/first-party/bound-output.ts
new file mode 100644
index 0000000000..e157e25479
--- /dev/null
+++ b/packages/ai-harness/src/first-party/bound-output.ts
@@ -0,0 +1,241 @@
+import { mkdir, readdir, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { normalizeToolResult } from '@tanstack/ai'
+import { definePlugin } from '../plugins'
+import { isRecord } from '../utils'
+import type { AfterToolCallInfo, AnyChatMiddleware } from '@tanstack/ai'
+
+const HOUR = 60 * 60 * 1000
+const DAY = 24 * HOUR
+/** Saved outputs start with this. The cleanup removes only these files. */
+const SAVED_PREFIX = 'tool-output-'
+/** Core marks subagent tools with this global symbol. */
+const SUBAGENT_TOOL = Symbol.for('tanstack.ai.subagentTool')
+const encoder = new TextEncoder()
+// ignoreBOM keeps a leading byte order mark in the kept text.
+const decoder = new TextDecoder('utf-8', { ignoreBOM: true })
+
+/** The number of lines in `text`. A final newline does not start a new line. */
+function countLines(text: string) {
+  return text.split('\n').length - (text.endsWith('\n') ? 1 : 0)
+}
+
+/** True for a UTF-8 byte inside a character, not at its start. */
+function isContinuationByte(byte: number | undefined) {
+  return byte !== undefined && (byte & 0xc0) === 0x80
+}
+
+/** The start of `text` inside both limits. `bytes` is `text` as UTF-8. */
+function firstPart(
+  text: string,
+  bytes: Uint8Array,
+  limits: { maxLines: number; maxBytes: number },
+) {
+  let end = limits.maxBytes
+  // Step back to the start of a character, so the cut never splits one.
+  while (isContinuationByte(bytes[end])) end--
+  const firstBytes = decoder.decode(bytes.subarray(0, end))
+  const firstLines = text.split('\n', limits.maxLines).join('\n')
+  return firstLines.length < firstBytes.length ? firstLines : firstBytes
+}
+
+/** The end of `text` inside both limits. `bytes` is `text` as UTF-8. */
+function lastPart(
+  text: string,
+  bytes: Uint8Array,
+  limits: { maxLines: number; maxBytes: number },
+) {
+  let start = Math.max(0, bytes.length - limits.maxBytes)
+  // Step forward to the start of a character, so the cut never splits one.
+  while (isContinuationByte(bytes[start])) start++
+  const lastBytes = decoder.decode(bytes.subarray(start))
+  const lines = text.split('\n')
+  // A final newline ends the last line. It does not start a new one.
+  const finalNewline = text.endsWith('\n') ? 1 : 0
+  const from = Math.max(0, lines.length - limits.maxLines - finalNewline)
+  const lastLines = lines.slice(from).join('\n')
+  return lastLines.length < lastBytes.length ? lastLines : lastBytes
+}
+
+/**
+ * Keep the part of `text` that fits in `maxLines` lines and `maxBytes` UTF-8
+ * bytes: the first lines (`keep: 'head'`, the default) or the last lines
+ * (`keep: 'tail'`). When something is cut, `truncated` is `true` and a note
+ * tells how much is shown: after the text for `head`, before it for `tail`.
+ * A cut never splits a character. Text inside both limits comes back
+ * unchanged.
+ *
+ * @example
+ * ```ts
+ * const { text, truncated } = boundText(output, {
+ *   maxLines: 2000,
+ *   maxBytes: 50 * 1024,
+ *   keep: 'tail',
+ * })
+ * ```
+ */
+export function boundText(
+  text: string,
+  limits: { maxLines: number; maxBytes: number; keep?: 'head' | 'tail' },
+) {
+  const lines = countLines(text)
+  const bytes = encoder.encode(text)
+  const isOverLimit = lines > limits.maxLines || bytes.length > limits.maxBytes
+  if (!isOverLimit) return { text, truncated: false }
+  const isTail = limits.keep === 'tail'
+  const kept = isTail
+    ? lastPart(text, bytes, limits)
+    : firstPart(text, bytes, limits)
+  const shown = `${countLines(kept)} of ${lines} lines, ${encoder.encode(kept).length} of ${bytes.length} bytes`
+  return isTail
+    ? { text: `[Output cut. Showing the last ${shown}.]\n\n${kept}`, truncated: true }
+    : { text: `${kept}\n\n[Output cut. Showing the first ${shown}.]`, truncated: true }
+}
+
+/**
+ * The time a saved output was written, from its file name, so no stat call
+ * is needed. `NaN` for a file this plugin did not save.
+ */
+function savedAt(name: string) {
+  if (!name.startsWith(SAVED_PREFIX)) return Number.NaN
+  return Number(name.slice(SAVED_PREFIX.length).split('-')[0])
+}
+
+/** Remove the saved outputs in `dir` that are older than `maxAgeMs`. */
+async function removeOldOutputs(dir: string, maxAgeMs: number) {
+  const cutoff = Date.now() - maxAgeMs
+  const names = await readdir(dir)
+  const old = names.filter((name) => savedAt(name) < cutoff)
+  await Promise.all(old.map((name) => rm(join(dir, name), { force: true })))
+}
+
+/**
+ * Save the full output of one tool call in `dir`. Gives back the note for
+ * the model: the file path, or why the save failed.
+ */
+async function saveFullOutput(dir: string, toolCallId: string, text: string) {
+  const safeId = toolCallId.replace(/[^\w-]/g, '_')
+  const path = join(dir, `${SAVED_PREFIX}${Date.now()}-${safeId}.txt`)
+  try {
+    await mkdir(dir, { recursive: true })
+    await writeFile(path, text)
+    return `[Full output saved to ${path}.]`
+  } catch (error) {
+    // The cut result is still useful, so a failed save does not fail the call.
+    return `[The full output was not saved: ${String(error)}]`
+  }
+}
+
+/**
+ * The result the model sees now. A failed call shows `{ error: message }`,
+ * unless an earlier middleware replaced it. `undefined` when there is
+ * nothing to cut.
+ */
+function currentResult(info: AfterToolCallInfo) {
+  if (info.ok || info.result !== undefined) return info.result
+  // A failed subagent call also shows its subagentRunId, which `info` does
+  // not carry. Leave it alone, so the model can still continue the child.
+  const isSubagent = info.tool !== undefined && SUBAGENT_TOOL in info.tool
+  if (isSubagent || !(info.error instanceof Error)) return undefined
+  return { error: info.error.message }
+}
+
+/**
+ * The long part of a result, and a function that puts the cut text back.
+ * An error result keeps its other fields. A subagent result keeps its
+ * `subagentRunId`, so the model can still continue the child.
+ */
+function longPart(result: unknown, ok: boolean) {
+  if (isRecord(result)) {
+    if (!ok && 'error' in result) {
+      return {
+        long: result.error,
+        put: (cut: string) => ({ ...result, error: cut }),
+      }
+    }
+    if (typeof result.subagentRunId === 'string' && 'result' in result) {
+      return {
+        long: result.result,
+        put: (cut: string) => ({ ...result, result: cut }),
+      }
+    }
+  }
+  return { long: result, put: (cut: string) => cut }
+}
+
+/**
+ * Keep every tool result small enough for the model. A result over
+ * `maxLines` lines (default 2000) or `maxBytes` UTF-8 bytes (default 50 KiB)
+ * is cut to its first lines, with a note.
+ *
+ * - A string result is cut as is. Any other value is cut as JSON text.
+ * - A failed call has its error text cut. It stays an error.
+ * - A subagent result has the child's answer cut. Its `subagentRunId` stays.
+ * - Content parts (images, audio, and so on) are not changed.
+ *
+ * It runs for every tool, MCP tools too, in the lead turn and in every agent
+ * run. With `dir`, the full output is saved to a file in `dir` and the note
+ * gives its path. Saved files older than `retentionDays` (default 7) are
+ * removed, at most once an hour. Node only.
+ *
+ * @example
+ * ```ts
+ * defineHarness({
+ *   name: 'acme/coder',
+ *   adapter,
+ *   plugins: () => [boundToolOutput({ dir: '.agent/tool-output' })],
+ * })
+ * ```
+ */
+export function boundToolOutput(
+  options: {
+    maxLines?: number
+    maxBytes?: number
+    dir?: string
+    retentionDays?: number
+  } = {},
+) {
+  const {
+    maxLines = 2000,
+    maxBytes = 50 * 1024,
+    dir,
+    retentionDays = 7,
+  } = options
+  return definePlugin({
+    name: 'tanstack/bound-tool-output',
+    setup: () => {
+      let lastCleanup = 0
+      const cleanUp = async (folder: string) => {
+        const now = Date.now()
+        if (now - lastCleanup < HOUR) return
+        lastCleanup = now
+        // ponytail: best effort. A failed cleanup tries again an hour later.
+        await removeOldOutputs(folder, retentionDays * DAY).catch(() => {})
+      }
+      const bound = {
+        name: 'tanstack/bound-tool-output',
+        onAfterToolCall: async (_ctx, info) => {
+          const result = currentResult(info)
+          if (result === undefined) return
+          const { long, put } = longPart(result, info.ok)
+          const full = normalizeToolResult(long)
+          // Content parts (images, audio, and so on) stay as they are.
+          if (typeof full !== 'string') return
+          const bounded = boundText(full, { maxLines, maxBytes })
+          if (!bounded.truncated) return
+          if (dir === undefined) {
+            return { type: 'replaceResult', result: put(bounded.text) }
+          }
+          const saved = await saveFullOutput(dir, info.toolCallId, full)
+          await cleanUp(dir)
+          return {
+            type: 'replaceResult',
+            result: put(`${bounded.text}\n${saved}`),
+          }
+        },
+      } satisfies AnyChatMiddleware
+      // The same middleware for the lead turn and every agent run.
+      return { middleware: [bound], agentMiddleware: [bound] }
+    },
+  })
+}
diff --git a/packages/ai-harness/src/first-party/coding/bash.ts b/packages/ai-harness/src/first-party/coding/bash.ts
index 0b1a8e2a81..5ee7afd3d4 100644
--- a/packages/ai-harness/src/first-party/coding/bash.ts
+++ b/packages/ai-harness/src/first-party/coding/bash.ts
@@ -1,33 +1,229 @@
+import { join, resolve } from 'node:path'
 import { toolDefinition } from '@tanstack/ai'
-import { clip, stringArg } from './backend'
+import { isRecord } from '../../utils'
+import { boundText } from '../bound-output'
+import { stringArg } from './backend'
 import type { ToolEnv } from './backend'
 
-/** `bash`: run a shell command in the workspace folder. */
+/** The longest timeout that one call can ask for: 10 minutes. */
+const MAX_TIMEOUT_MS = 10 * 60 * 1000
+/**
+ * How much output the model gets: the last lines. The limits are below the
+ * defaults of `boundToolOutput` (2000 lines, 50 KiB), so that plugin does
+ * not cut the result again and remove the exit code.
+ */
+const OUTPUT_LIMITS = {
+  maxLines: 1000,
+  maxBytes: 20 * 1024,
+  keep: 'tail',
+} as const
+/** Added to the environment of every command, so tools can see an agent. */
+const AGENT_ENV = { AGENT: '1' }
+/** Shell syntax that can hide a command inside another command. */
+const HIDDEN_COMMAND = /\$\(|`|<\(|>\(|<</
+/** The operators between simple commands. `||` comes before `|`. */
+const OPERATORS = ['&&', '||', ';', '|', '\n']
+
+/**
+ * The simple commands in a shell command, so a permission rule can check
+ * each one. It splits on `&&`, `||`, `;`, `|`, and new lines that are not
+ * in quotes or after a backslash.
+ *
+ * It fails closed: for `$(`, a backtick, `<(`, `>(`, a heredoc (`<<`), an
+ * unquoted `(`, or a quote that does not close, the whole command comes
+ * back as one part. The permission rules never allow a part that still has
+ * shell syntax in it.
+ *
+ * @example
+ * ```ts
+ * splitCommand('ls && rm -rf x') // ['ls', 'rm -rf x']
+ * splitCommand('echo $(rm x)') // ['echo $(rm x)']
+ * ```
+ */
+export function splitCommand(command: string) {
+  if (HIDDEN_COMMAND.test(command)) return [command]
+  const parts: Array<string> = []
+  let part = ''
+  // The open quote. In `'...'` every character is as is. In `"..."` and
+  // `$'...'` a backslash escapes the next character.
+  let quote: "'" | '"' | "$'" | undefined
+  for (let i = 0; i < command.length; i++) {
+    const char = command.charAt(i)
+    if (quote === "'") {
+      if (char === "'") quote = undefined
+      part += char
+      continue
+    }
+    if (char === '\\') {
+      part += command.slice(i, i + 2)
+      i++
+      continue
+    }
+    if (quote !== undefined) {
+      const closes = char === (quote === '"' ? '"' : "'")
+      if (closes) quote = undefined
+      part += char
+      continue
+    }
+    const operator = OPERATORS.find((item) => command.startsWith(item, i))
+    if (operator !== undefined) {
+      parts.push(part)
+      part = ''
+      i += operator.length - 1
+      continue
+    }
+    // A subshell or a function body, for example `ls() ( rm -rf x ); ls`.
+    if (char === '(') return [command]
+    if (command.startsWith("$'", i)) {
+      quote = "$'"
+      part += "$'"
+      i++
+      continue
+    }
+    if (char === "'" || char === '"') quote = char
+    part += char
+  }
+  if (quote !== undefined) return [command]
+  parts.push(part)
+  // Remove only spaces and tabs, the blanks of the shell. A `\r` stays, so
+  // the permission rules see it.
+  return parts
+    .map((item) => item.replace(/^[ \t]+|[ \t]+$/g, ''))
+    .filter((item) => item !== '')
+}
+
+/**
+ * The command parts of a `bash` call, for `PermissionResources`. Throws when
+ * `command` is not a string, and that refuses the call.
+ *
+ * @example
+ * ```ts
+ * PermissionResources.item({ bash: { commands: bashResources } })
+ * ```
+ */
+export function bashResources(input: unknown) {
+  return splitCommand(stringArg(input, 'command'))
+}
+
+/**
+ * `bash`: run a shell command in the workspace folder. Every command gets
+ * `AGENT=1` in its environment. The model gets the exit code and the last
+ * part of the output.
+ *
+ * With `background: true`, the call returns at once with a job id, and
+ * `note` tells the model when the job ends. Background jobs need
+ * `env.backend.spawn`. They are killed when `signal` aborts.
+ */
 export function bashTools(
   env: ToolEnv,
   options: {
     /** Stop the command after this many milliseconds. Default: 120,000. */
     timeoutMs?: number
+    /** Tells the model that a background job ended. Without it, no one is told. */
+    note?: (text: string) => Promise<void>
+    /**
+     * When the model gets only the end of the output, the full output is
+     * saved in this folder, and the model gets the path. Relative to the
+     * workspace, or absolute.
+     */
+    spillDir?: string
+    /** Kills the background jobs that still run, for example on plugin cleanup. */
+    signal?: AbortSignal
   } = {},
 ) {
+  const { timeoutMs: defaultTimeoutMs = 120_000, note, spillDir, signal } =
+    options
+  // ponytail: jobs live in memory only. A restart forgets them.
+  const jobs = new Set<{ kill: () => void }>()
+  let started = 0
+  signal?.addEventListener('abort', () => {
+    for (const job of jobs) job.kill()
+  })
+
+  /** Save the full output in `dir`. Gives back the note for the model. */
+  const spill = async (dir: string, output: string) => {
+    const path = join(
+      resolve(env.root, dir),
+      `bash-${crypto.randomUUID()}.txt`,
+    )
+    try {
+      await env.backend.writeFile(path, output)
+      return `[Full output saved to ${env.shown(path)}.]`
+    } catch (error) {
+      // The cut output is still useful, so a failed save does not fail the call.
+      return `[The full output was not saved: ${String(error)}]`
+    }
+  }
+
+  /** The exit code and the end of `output`, as the model gets them. */
+  const report = async (exitCode: number, output: string) => {
+    const bounded = boundText(output, OUTPUT_LIMITS)
+    const lines = [`exit code: ${exitCode}`, bounded.text]
+    if (bounded.truncated && spillDir !== undefined) {
+      lines.push(await spill(spillDir, output))
+    }
+    return lines.join('\n')
+  }
+
+  /** Start `command` in the background. `note` tells the model when it ends. */
+  const startJob = (command: string) => {
+    if (!env.backend.spawn) {
+      throw new Error('This workspace cannot run commands in the background.')
+    }
+    const job = env.backend.spawn(command, { cwd: env.root, env: AGENT_ENV })
+    started += 1
+    const jobId = `bash-${started}`
+    jobs.add(job)
+    const tell = async () => {
+      const { exitCode } = await job.wait()
+      jobs.delete(job)
+      if (note === undefined || signal?.aborted) return
+      const result = await report(exitCode, job.output())
+      await note(`Background job ${jobId} ended.\n${result}`)
+    }
+    // No one waits for the job, so a failed note must not crash the process.
+    tell().catch(() => undefined)
+    return { jobId, status: 'started' }
+  }
+
   return [
     toolDefinition({
       name: 'bash',
       description:
-        'Run a shell command in the workspace folder. Output is cut at 20,000 characters.',
+        'Run a shell command in the workspace folder. You get the exit code and the last 1000 lines (20 KiB) of the output. For a command that runs long, like a dev server, set background to true: the call returns at once, and you get a note when the command ends.',
       inputSchema: {
         type: 'object',
-        properties: { command: { type: 'string' } },
+        properties: {
+          command: { type: 'string' },
+          timeoutMs: {
+            type: 'number',
+            description:
+              'Stop the command after this many milliseconds. At most 600000.',
+          },
+          background: {
+            type: 'boolean',
+            description: 'Run the command in the background.',
+          },
+        },
         required: ['command'],
       },
       replay: 'never',
     }).server(async (args: unknown) => {
-      const { exitCode, stdout, stderr } = await env.backend.exec(
-        stringArg(args, 'command'),
-        { cwd: env.root, timeoutMs: options.timeoutMs ?? 120_000 },
-      )
-      return clip(
-        `exit code: ${exitCode}\n${stdout}${stderr ? `\nstderr:\n${stderr}` : ''}`,
+      const command = stringArg(args, 'command')
+      if (isRecord(args) && args.background === true) return startJob(command)
+      const requested = isRecord(args) ? args.timeoutMs : undefined
+      // A timeout of 0 would mean no timeout, so it gets the default.
+      const isTimeout = typeof requested === 'number' && requested > 0
+      const { exitCode, stdout, stderr } = await env.backend.exec(command, {
+        cwd: env.root,
+        env: AGENT_ENV,
+        timeoutMs: isTimeout
+          ? Math.min(requested, MAX_TIMEOUT_MS)
+          : defaultTimeoutMs,
+      })
+      return report(
+        exitCode,
+        `${stdout}${stderr ? `\nstderr:\n${stderr}` : ''}`,
       )
     }),
   ]
diff --git a/packages/ai-harness/src/first-party/coding/edit.ts b/packages/ai-harness/src/first-party/coding/edit.ts
index 4d23bcccda..44075a8fda 100644
--- a/packages/ai-harness/src/first-party/coding/edit.ts
+++ b/packages/ai-harness/src/first-party/coding/edit.ts
@@ -3,9 +3,118 @@ import { isRecord } from '../../utils'
 import { afterWrite, readText, stringArg } from './backend'
 import type { ToolEnv } from './backend'
 
+const BOM = ''
+
+/**
+ * How one match level changes text before the search. `pieces` cuts the text
+ * into pieces, and `change` gives the new text of each piece.
+ */
+interface Level {
+  pieces: RegExp
+  change: (piece: RegExpExecArray) => string
+}
+
+// The match levels after the exact text, from strict to loose.
+const LEVELS: ReadonlyArray<Level> = [
+  // Unicode NFC form. A piece is a character and the marks after it.
+  // ponytail: decomposed Hangul jamo stay apart. Cut by grapheme if needed.
+  {
+    pieces: /\P{M}\p{M}*|\p{M}+/gu,
+    change: (piece) => piece[0].normalize('NFC'),
+  },
+  // Spaces and tabs at the end of each line removed.
+  {
+    pieces: /([^\S\n]+(?=\n|$))|[\s\S]/g,
+    change: (piece) => (piece[1] ? '' : piece[0]),
+  },
+]
+
+/**
+ * `text` changed by `level`, and where each character of the result starts in
+ * `text`. `at[i]` is `undefined` inside a changed piece. The last entry of
+ * `at` is the end of `text`.
+ */
+function changed(text: string, level: Level) {
+  let result = ''
+  const at: Array<number | undefined> = []
+  const pieces = text.matchAll(level.pieces)
+  for (const piece of pieces) {
+    const next = level.change(piece)
+    // An unchanged piece maps one to one. A changed piece maps its start only.
+    const same = next === piece[0]
+    for (let i = 0; i < next.length; i++) {
+      at.push(same || i === 0 ? piece.index + i : undefined)
+    }
+    result += next
+  }
+  at.push(text.length)
+  return { text: result, at }
+}
+
+/** Where `find` starts in `text`, without overlaps. None for an empty `find`. */
+function indexesOf(text: string, find: string) {
+  const found: Array<number> = []
+  if (find === '') return found
+  let index = text.indexOf(find)
+  while (index !== -1) {
+    found.push(index)
+    index = text.indexOf(find, index + find.length)
+  }
+  return found
+}
+
+/** `text` with the line endings of `content`: CRLF when it has one, else LF. */
+export function toEndingsOf(text: string, content: string) {
+  return text.replace(/\r?\n/g, content.includes('\r\n') ? '\r\n' : '\n')
+}
+
+/**
+ * Find `find` in `content`. Three levels are tried in order, and the first
+ * level with a match wins:
+ *
+ * 1. The exact text.
+ * 2. Both sides in Unicode NFC form.
+ * 3. Spaces and tabs at the end of each line ignored. A match then also covers
+ *    the trailing spaces of its last line.
+ *
+ * `find` first gets the line endings of `content`, so LF text matches a CRLF
+ * file.
+ *
+ * Returns each match as `{ start, end }` offsets into the original `content`,
+ * in order and without overlaps. An empty array means no match. More than one
+ * match means the text is not unique.
+ *
+ * @example
+ * ```ts
+ * findMatches('a  \nb\n', 'a\nb') // [{ start: 0, end: 5 }]
+ * ```
+ */
+export function findMatches(content: string, find: string) {
+  const wanted = toEndingsOf(find, content)
+  const exact = indexesOf(content, wanted)
+  if (exact.length > 0) {
+    return exact.map((start) => ({ start, end: start + wanted.length }))
+  }
+  for (const level of LEVELS) {
+    const { text, at } = changed(content, level)
+    const needle = changed(wanted, level).text
+    const starts = indexesOf(text, needle)
+    const matches = starts.flatMap((index) => {
+      const start = at[index]
+      const end = at[index + needle.length]
+      // A match must start and end where a piece starts.
+      return start === undefined || end === undefined ? [] : [{ start, end }]
+    })
+    if (matches.length > 0) return matches
+  }
+  return []
+}
+
 /**
  * `write_file` and `edit_file`. After each write, the `afterWrite` hooks run
- * for the file.
+ * for the file. `edit_file` finds the old text with {@link findMatches}. It
+ * writes the new text with the line endings of the file, and keeps a byte
+ * order mark.
  */
 export function editTools(env: ToolEnv) {
   return [
@@ -51,16 +160,27 @@ export function editTools(env: ToolEnv) {
       const replaceAll = isRecord(args) && args.replaceAll === true
       return env.lock(full, async () => {
         const before = await readText(env.backend, full)
-        const count = before.split(oldText).length - 1
+        const matches = findMatches(before, oldText)
+        const count = matches.length
         if (count === 0) throw new Error('The old text is not in the file.')
         if (count > 1 && !replaceAll) {
           throw new Error(
             `The old text appears ${count} times. Add context, or set replaceAll.`,
           )
         }
-        await env.backend.writeFile(full, before.split(oldText).join(newText))
+        const replacement = toEndingsOf(newText, before)
+        let after = ''
+        let from = 0
+        for (const { start, end } of matches) {
+          after += before.slice(from, start) + replacement
+          from = end
+        }
+        after += before.slice(from)
+        // Keep the byte order mark, also when the new text drops it.
+        const keepBom = before.startsWith(BOM) && !after.startsWith(BOM)
+        await env.backend.writeFile(full, keepBom ? BOM + after : after)
         await afterWrite(env, full)
-        return `Edited ${env.shown(full)} (${replaceAll ? count : 1} change${count > 1 && replaceAll ? 's' : ''}).`
+        return `Edited ${env.shown(full)} (${count} change${count > 1 ? 's' : ''}).`
       })
     }),
   ]
diff --git a/packages/ai-harness/src/first-party/coding/patch.ts b/packages/ai-harness/src/first-party/coding/patch.ts
new file mode 100644
index 0000000000..915d25a031
--- /dev/null
+++ b/packages/ai-harness/src/first-party/coding/patch.ts
@@ -0,0 +1,384 @@
+import { toolDefinition } from '@tanstack/ai'
+import { afterWrite, readText, stringArg } from './backend'
+import { findMatches, toEndingsOf } from './edit'
+import type { ToolEnv } from './backend'
+
+const BOM = ''
+
+/** One chunk of an `*** Update File:` section. */
+export interface PatchChunk {
+  /** The text after `@@`: a line above the change, to find the place. */
+  context?: string
+  /** The lines that the chunk replaces: the context and `-` lines. */
+  oldLines: Array<string>
+  /** The lines that replace them: the context and `+` lines. */
+  newLines: Array<string>
+  /** True after `*** End of File`: the old lines end the file. */
+  endOfFile: boolean
+}
+
+/** One file change of a patch. The paths are as the patch gives them. */
+export type PatchOperation =
+  | { type: 'add'; path: string; content: string }
+  | { type: 'delete'; path: string }
+  | {
+      type: 'update'
+      path: string
+      movePath?: string
+      chunks: Array<PatchChunk>
+    }
+
+/** The file changes of a patch, in order. */
+export type ParsedPatch = Array<PatchOperation>
+
+const DESCRIPTION = `Change files with a patch:
+
+*** Begin Patch
+*** Add File: src/new.ts
++each line of a new file starts with +
+*** Update File: src/app.ts
+@@ function main() {
+ a context line starts with a space
+-a removed line starts with -
++an added line starts with +
+*** Delete File: src/old.ts
+*** End Patch
+
+In an update, each chunk starts with @@. The text after @@ is optional. It is a line above the change, to find the place. Give 3 context lines above and below each change, so the old lines are unique. Chunks apply in order. "*** Move to: <path>" right after "*** Update File:" renames the file. "*** End of File" after a chunk means that the chunk ends the file.`
+
+function lineError(index: number, message: string) {
+  return new Error(`Patch line ${index + 1}: ${message}`)
+}
+
+/** The path after a header. Throws when it is empty. */
+function pathAt(index: number, rest = '') {
+  const path = rest.trim()
+  if (path === '') throw lineError(index, 'the path is missing.')
+  return path
+}
+
+/** Throws when `operation` is an update with no lines and no move. */
+function checkNotEmpty(operation: PatchOperation | undefined, index: number) {
+  if (operation?.type !== 'update' || operation.movePath !== undefined) return
+  const hasLines = operation.chunks.some(
+    (chunk) => chunk.oldLines.length + chunk.newLines.length > 0,
+  )
+  if (!hasLines) {
+    throw lineError(
+      index,
+      `"*** Update File: ${operation.path}" has no changes.`,
+    )
+  }
+}
+
+function newChunk(context: string) {
+  const chunk: PatchChunk = {
+    context: context || undefined,
+    oldLines: [],
+    newLines: [],
+    endOfFile: false,
+  }
+  return chunk
+}
+
+const isFilled = (line: string) => line.trim() !== ''
+
+/**
+ * Read a patch in the `*** Begin Patch` format into its file changes. Throws
+ * an error with the line number when the text does not follow the format.
+ *
+ * @example
+ * ```ts
+ * parsePatch('*** Begin Patch\n*** Delete File: old.txt\n*** End Patch')
+ * // [{ type: 'delete', path: 'old.txt' }]
+ * ```
+ */
+export function parsePatch(text: string) {
+  const lines = text.split(/\r?\n/)
+  const first = Math.max(lines.findIndex(isFilled), 0)
+  const last = lines.findLastIndex(isFilled)
+  if (lines[first]?.trim() !== '*** Begin Patch') {
+    throw lineError(first, 'the patch must start with "*** Begin Patch".')
+  }
+  if (last === first || lines[last]?.trim() !== '*** End Patch') {
+    throw lineError(last, 'the patch must end with "*** End Patch".')
+  }
+  const operations: ParsedPatch = []
+  let current: PatchOperation | undefined
+  let currentLine = first
+  // The chunk that new lines go to.
+  let chunk: PatchChunk | undefined
+  for (let index = first + 1; index < last; index++) {
+    const line = lines[index] ?? ''
+    const head = line.trimEnd()
+    const header = /^\*\*\* (Add|Delete|Update) File:(.*)$/.exec(head)
+    if (header) {
+      checkNotEmpty(current, currentLine)
+      const [, kind, rest] = header
+      const path = pathAt(index, rest)
+      switch (kind) {
+        case 'Add':
+          current = { type: 'add', path, content: '' }
+          break
+        case 'Delete':
+          current = { type: 'delete', path }
+          break
+        default:
+          current = { type: 'update', path, chunks: [] }
+      }
+      operations.push(current)
+      currentLine = index
+      chunk = undefined
+      continue
+    }
+    const move = /^\*\*\* Move to:(.*)$/.exec(head)
+    if (move) {
+      if (
+        current?.type !== 'update' ||
+        current.chunks.length > 0 ||
+        current.movePath !== undefined
+      ) {
+        throw lineError(
+          index,
+          '"*** Move to:" must come right after "*** Update File:".',
+        )
+      }
+      current.movePath = pathAt(index, move[1])
+      continue
+    }
+    if (head === '*** End of File') {
+      if (!chunk) {
+        throw lineError(index, '"*** End of File" must come after a chunk.')
+      }
+      chunk.endOfFile = true
+      chunk = undefined
+      continue
+    }
+    switch (current?.type) {
+      case undefined:
+      case 'delete':
+        if (head !== '') {
+          throw lineError(
+            index,
+            'expected "*** Add File:", "*** Delete File:", or "*** Update File:".',
+          )
+        }
+        break
+      case 'add':
+        if (!line.startsWith('+')) {
+          throw lineError(
+            index,
+            'each line of an added file must start with "+".',
+          )
+        }
+        current.content += `${line.slice(1)}\n`
+        break
+      case 'update': {
+        if (line.startsWith('@@')) {
+          chunk = newChunk(line.slice(2).trim())
+          current.chunks.push(chunk)
+          break
+        }
+        // An empty line is an empty context line. Editors often drop the
+        // space at the end of a line.
+        const sign = line.charAt(0) || ' '
+        if (sign !== ' ' && sign !== '-' && sign !== '+') {
+          throw lineError(
+            index,
+            'each chunk line must start with " ", "-", or "+".',
+          )
+        }
+        // The first chunk can start without `@@`.
+        if (!chunk) {
+          chunk = newChunk('')
+          current.chunks.push(chunk)
+        }
+        const body = line.slice(1)
+        if (sign !== '+') chunk.oldLines.push(body)
+        if (sign !== '-') chunk.newLines.push(body)
+        break
+      }
+    }
+  }
+  checkNotEmpty(current, currentLine)
+  if (operations.length === 0) {
+    throw lineError(first, 'the patch has no file changes.')
+  }
+  return operations
+}
+
+/**
+ * Every path that a patch changes, also the targets of `*** Move to:`, as
+ * the patch gives them. The permission rules check them. Throws when the
+ * patch does not parse.
+ *
+ * @example
+ * ```ts
+ * patchPaths(text) // ['src/a.ts', 'src/old.ts', 'src/new.ts']
+ * ```
+ */
+export function patchPaths(text: string) {
+  const operations = parsePatch(text)
+  return operations.flatMap((operation) =>
+    operation.type === 'update' && operation.movePath !== undefined
+      ? [operation.path, operation.movePath]
+      : [operation.path],
+  )
+}
+
+/** The lines as text, each with a line ending. */
+const asText = (lines: ReadonlyArray<string>) =>
+  lines.map((line) => `${line}\n`).join('')
+
+/**
+ * `content` with `chunks` applied in order. A chunk is searched after the
+ * chunk before it, and from the line of its `@@` text. The old lines must be
+ * whole lines, and must be there once. Keeps a byte order mark, the line
+ * endings, and a missing line ending at the end. `name` is the file, for the
+ * errors.
+ */
+function applyChunks(
+  content: string,
+  chunks: ReadonlyArray<PatchChunk>,
+  name: string,
+) {
+  const hasBom = content.startsWith(BOM)
+  const body = hasBom ? content.slice(1) : content
+  const eol = toEndingsOf('\n', body)
+  // Work on text that ends with a line ending, so the last line is like the
+  // others.
+  const ended = body === '' || body.endsWith('\n')
+  let text = ended ? body : body + eol
+  // Where the next chunk starts to search.
+  let from = 0
+  const entries = chunks.entries()
+  for (const [index, chunk] of entries) {
+    const label = `Chunk ${index + 1} of ${name}`
+    const newText = toEndingsOf(asText(chunk.newLines), text)
+    // With `@@` text, search from its line. Only added lines go below it.
+    let searchFrom = from
+    let below = text.length
+    if (chunk.context !== undefined) {
+      const [found] = findMatches(text.slice(from), chunk.context)
+      if (!found) {
+        throw new Error(`${label}: "@@ ${chunk.context}" is not in the file.`)
+      }
+      searchFrom = text.lastIndexOf('\n', from + found.start - 1) + 1
+      below = text.indexOf('\n', from + found.end) + 1
+    }
+    if (chunk.oldLines.length === 0) {
+      const spot = chunk.endOfFile ? text.length : below
+      text = text.slice(0, spot) + newText + text.slice(spot)
+      from = spot + newText.length
+      continue
+    }
+    const oldText = toEndingsOf(asText(chunk.oldLines), text)
+    // ponytail: a match inside a line can hide a whole-line match that
+    // overlaps it. The chunk then is not found, and the model adds context.
+    const isWhole = (match: { start: number; end: number }) => {
+      const startsLine = match.start === 0 || text[match.start - 1] === '\n'
+      const endsRight = !chunk.endOfFile || match.end === text.length
+      return startsLine && endsRight
+    }
+    const matches = findMatches(text.slice(searchFrom), oldText)
+      .map((match) => ({
+        start: match.start + searchFrom,
+        end: match.end + searchFrom,
+      }))
+      .filter(isWhole)
+    const [match, ...others] = matches
+    if (!match) throw new Error(`${label}: the old lines are not in the file.`)
+    if (others.length > 0) {
+      throw new Error(
+        `${label}: the old lines appear ${matches.length} times. Add context lines.`,
+      )
+    }
+    text = text.slice(0, match.start) + newText + text.slice(match.end)
+    from = match.start + newText.length
+  }
+  const result = ended ? text : text.replace(/\r?\n$/, '')
+  return hasBom ? BOM + result : result
+}
+
+/**
+ * Apply each operation to its absolute path `full`. Every file is read and
+ * checked first. The files are written only when every operation fits.
+ */
+async function applyAll(
+  env: ToolEnv,
+  steps: ReadonlyArray<{ operation: PatchOperation; full: string }>,
+) {
+  // The new text of each file. A later operation on a file sees it.
+  const planned = new Map<string, string>()
+  const changes: Array<string> = []
+  for (const { operation, full } of steps) {
+    const shown = env.shown(full)
+    switch (operation.type) {
+      case 'add':
+        planned.set(full, operation.content)
+        changes.push(`added ${shown}`)
+        break
+      case 'update': {
+        // ponytail: WorkspaceBackend cannot remove a file, so a move or a
+        // delete is refused. Add them when the backend can remove files.
+        if (operation.movePath !== undefined) {
+          throw new Error(
+            `Cannot move ${shown}: the workspace cannot remove files.`,
+          )
+        }
+        const before =
+          planned.get(full) ?? (await readText(env.backend, full))
+        planned.set(full, applyChunks(before, operation.chunks, shown))
+        changes.push(`updated ${shown}`)
+        break
+      }
+      case 'delete':
+        throw new Error(
+          `Cannot delete ${shown}: the workspace cannot remove files.`,
+        )
+    }
+  }
+  const files = [...planned]
+  for (const [full, text] of files) await env.backend.writeFile(full, text)
+  for (const [full] of files) await afterWrite(env, full)
+  return ['Applied the patch:', ...changes].join('\n')
+}
+
+/**
+ * The `patch` tool: it changes files with a patch in the `*** Begin Patch`
+ * format (see {@link parsePatch}). The old lines of a chunk are found with
+ * {@link findMatches}. All files are checked before the first write, so a
+ * patch that does not fit changes nothing. The `afterWrite` hooks run for
+ * each written file. The result lists the changed files.
+ */
+export function patchTools(env: ToolEnv) {
+  return [
+    toolDefinition({
+      name: 'patch',
+      description: DESCRIPTION,
+      inputSchema: {
+        type: 'object',
+        properties: { patch: { type: 'string' } },
+        required: ['patch'],
+      },
+    }).server(async (args: unknown) => {
+      const operations = parsePatch(stringArg(args, 'patch'))
+      // Resolve each path first. A path outside the workspace can ask the
+      // user.
+      const steps: Array<{ operation: PatchOperation; full: string }> = []
+      for (const operation of operations) {
+        const full = await env.reach(operation.path, 'patch', 'file')
+        steps.push({ operation, full })
+      }
+      // Hold the lock of every file, taken in one fixed order, so two
+      // patches cannot wait for each other.
+      const paths = [...new Set(steps.map((step) => step.full))].sort()
+      let run = () => applyAll(env, steps)
+      for (const path of paths) {
+        const inner = run
+        run = () => env.lock(path, inner)
+      }
+      return run()
+    }),
+  ]
+}
diff --git a/packages/ai-harness/src/first-party/permissions.ts b/packages/ai-harness/src/first-party/permissions.ts
index ea653b1d55..7148e7e73a 100644
--- a/packages/ai-harness/src/first-party/permissions.ts
+++ b/packages/ai-harness/src/first-party/permissions.ts
@@ -101,6 +101,17 @@ function isWindowsPath(path: string) {
   return /^([a-z]:[\\/]|[\\/]{2})/i.test(path)
 }
 
+/**
+ * Compare paths without letter case on macOS and Windows, whose file systems
+ * ignore case by default, and for any Windows-form path. Else `Secrets/key`
+ * would pass a deny rule for `secrets/**`.
+ */
+// ponytail: platform default, add a `caseInsensitive` option if a case-sensitive macOS volume needs it
+function foldsCase(path: string) {
+  const platform = typeof process === 'undefined' ? '' : process.platform
+  return platform === 'darwin' || platform === 'win32' || isWindowsPath(path)
+}
+
 /** `path` with `/` separators, and `.` and `..` resolved. */
 function normalizePath(path: string) {
   const slashed = path.replaceAll('\\', '/')
@@ -126,7 +137,7 @@ function isEnvFile(path: string) {
 }
 
 function pathResource(path: string, root: string | undefined) {
-  const foldCase = isWindowsPath(root ?? path)
+  const foldCase = foldsCase(root ?? path)
   const slashed = path.replaceAll('\\', '/')
   // Forms we cannot resolve without the file system ask: `C:x` (relative to
   // the current folder of drive C), a stream (`a.txt:secret`), and a name
@@ -338,7 +349,7 @@ const METADATA_NAMESPACE = 'tanstack/permissions'
 /** The root as one string for each folder: `C:\Repo` and `c:/repo/` are the same. */
 function projectId(root: string) {
   const path = normalizePath(root)
-  return isWindowsPath(root) ? path.toLowerCase() : path
+  return foldsCase(root) ? path.toLowerCase() : path
 }
 
 const PLAN_PROMPT =
diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
index 7281930506..30ba335085 100644
--- a/packages/ai-harness/src/host.ts
+++ b/packages/ai-harness/src/host.ts
@@ -1,7 +1,15 @@
+import { EventType } from '@tanstack/ai'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { SharedLog, loadLogState, logMessageStore } from './log'
 import { HarnessSession } from './session'
-import type { ModelMessage, PromptCacheOptions, RunStore } from '@tanstack/ai'
+import { HARNESS_EVENTS } from './types'
+import { isRecord } from './utils'
+import type {
+  ModelMessage,
+  PromptCacheOptions,
+  RunStore,
+  StreamChunk,
+} from '@tanstack/ai'
 import type {
   AIPersistence,
   ArtifactStore,
@@ -151,6 +159,41 @@ export interface HostSessions {
   fork: (threadId: string, at: ForkPoint) => Promise<SessionIndexEntry>
 }
 
+/**
+ * An open session of the host changed its status. `running`: an operation
+ * runs. `waiting`: a question or an interrupt waits for an answer. `idle`:
+ * nothing runs or waits. `at` is the time of the change, in epoch ms.
+ */
+export interface HostStatusEvent {
+  type: 'status'
+  threadId: string
+  status: 'idle' | 'running' | 'waiting'
+  at: number
+}
+
+/**
+ * The host wrote the index entry of a thread: a new session, the end of a
+ * turn, a rename, or a fork. `entry` is the new entry.
+ */
+export interface HostSessionEvent {
+  type: 'session'
+  threadId: string
+  entry: SessionIndexEntry
+}
+
+/** The host removed the index entry of a thread. `entry` is the removed entry. */
+export interface HostSessionDeletedEvent {
+  type: 'session-deleted'
+  threadId: string
+  entry: SessionIndexEntry
+}
+
+/** What `host.events()` yields. */
+export type HostEvent =
+  | HostStatusEvent
+  | HostSessionEvent
+  | HostSessionDeletedEvent
+
 /** Runs sessions for one or more harnesses in this process. */
 export interface HarnessHost<TLogState = unknown> {
   /**
@@ -170,6 +213,20 @@ export interface HarnessHost<TLogState = unknown> {
   logState: (logId: string) => TLogState | undefined
   /** The session index: list, rename, delete, and fork sessions. */
   sessions: HostSessions
+  /**
+   * The status changes and the session index changes of this host, for a
+   * list of sessions that stays current. First the current status of each
+   * open session, then each change as it occurs. Each call reads on its own.
+   * The read stops when `signal` aborts or the loop ends.
+   *
+   * @example
+   * ```ts
+   * for await (const event of host.events({ signal })) {
+   *   if (event.type === 'status') console.log(event.threadId, event.status)
+   * }
+   * ```
+   */
+  events: (options?: { signal?: AbortSignal }) => AsyncIterable<HostEvent>
 }
 
 let warned = false
@@ -178,8 +235,12 @@ let warned = false
  * Writes to the session index. `upsert` replaces the whole entry, so a
  * change reads the entry, changes a copy, and writes it back. The changes of
  * one thread run one at a time, so no change loses the fields of another.
+ * `onChange` gets each write and each removal.
  */
-function sessionIndex(store: SessionIndexStore | undefined) {
+function sessionIndex(
+  store: SessionIndexStore | undefined,
+  onChange: (event: HostSessionEvent | HostSessionDeletedEvent) => void,
+) {
   const tails = new Map<string, Promise<void>>()
   const serial = <T>(threadId: string, task: () => Promise<T>) => {
     // The tail never rejects, so a failed change does not stop the next one.
@@ -209,12 +270,18 @@ function sessionIndex(store: SessionIndexStore | undefined) {
       serial(threadId, async () => {
         if (!store) return undefined
         const next = change(await store.get(threadId))
-        if (next) await store.upsert(next)
+        if (next) {
+          await store.upsert(next)
+          onChange({ type: 'session', threadId, entry: next })
+        }
         return next
       }),
     remove: (threadId: string) =>
       serial(threadId, async () => {
-        await store?.delete(threadId)
+        if (!store) return
+        const entry = await store.get(threadId)
+        await store.delete(threadId)
+        if (entry) onChange({ type: 'session-deleted', threadId, entry })
       }),
   }
 }
@@ -233,6 +300,38 @@ function cutTranscript(messages: ReadonlyArray<ModelMessage>, at: ForkPoint) {
   return messages.slice(0, isBefore ? index : index + 1)
 }
 
+/**
+ * The status rule: the status of `session` after `event`, or `undefined`
+ * when the event changes nothing. An operation that starts runs, and a
+ * question waits. When an operation ends or a question gets its answer, the
+ * session waits while a question or an interrupt still waits, runs while
+ * another operation runs, and else is idle.
+ */
+function statusAfter(session: HarnessSession, event: StreamChunk) {
+  if (event.type !== EventType.CUSTOM) return undefined
+  switch (event.name) {
+    case HARNESS_EVENTS.operationStarted:
+      return 'running'
+    case HARNESS_EVENTS.question:
+      return 'waiting'
+    case HARNESS_EVENTS.operationFinished:
+    case HARNESS_EVENTS.questionAnswered: {
+      const { pendingQuestions, pendingInterrupts, activeOperations } =
+        session.snapshot()
+      const isInterrupted =
+        isRecord(event.value) && event.value.status === 'interrupted'
+      const stillWaits =
+        isInterrupted ||
+        pendingQuestions.length > 0 ||
+        pendingInterrupts.length > 0
+      if (stillWaits) return 'waiting'
+      return activeOperations.length > 0 ? 'running' : 'idle'
+    }
+    default:
+      return undefined
+  }
+}
+
 /** How each host finds the open session of a chat turn. Not public API. */
 const turnFinders = new WeakMap<
   object,
@@ -314,7 +413,29 @@ export function createHarnessHost<TLogState = undefined>(
   }
   const logStore = persistence.stores.log
   const { metadata, sessions: sessionStore } = persistence.stores
-  const index = sessionIndex(sessionStore)
+  /** One per running `host.events()` read. */
+  const listeners = new Set<(event: HostEvent) => void>()
+  const emit = (event: HostEvent) => {
+    for (const listener of listeners) listener(event)
+  }
+  /** The latest status of each open session, by session key. */
+  const statuses = new Map<string, HostStatusEvent>()
+  const setStatus = (
+    key: string,
+    threadId: string,
+    status: HostStatusEvent['status'],
+  ) => {
+    if (statuses.get(key)?.status === status) return
+    const event: HostStatusEvent = {
+      type: 'status',
+      threadId,
+      status,
+      at: Date.now(),
+    }
+    statuses.set(key, event)
+    emit(event)
+  }
+  const index = sessionIndex(sessionStore, emit)
   // The transcript of any thread, for a fork. On a durable host, a view of
   // the log of that thread. ponytail: a thread that shares another log (a
   // `logId` that is not its thread id) is not found. Keep the log id in the
@@ -398,12 +519,24 @@ export function createHarnessHost<TLogState = undefined>(
           ...(options.lease ? { lease: options.lease } : {}),
           ...(principal ? { principal } : {}),
           ...(promptCache ? { promptCache } : {}),
-          onClose: () => sessions.delete(key),
+          onEvent: (event) => {
+            const status = statusAfter(created, event)
+            if (status) setStatus(key, threadId, status)
+          },
+          onClose: () => {
+            sessions.delete(key)
+            statuses.delete(key)
+          },
         })
         session = created.open().then(
-          () => created,
+          () => {
+            // A recovered turn can run already. Else the new session is idle.
+            if (!statuses.has(key)) setStatus(key, threadId, 'idle')
+            return created
+          },
           (error: unknown) => {
             sessions.delete(key)
+            statuses.delete(key)
             throw error
           },
         )
@@ -455,6 +588,35 @@ export function createHarnessHost<TLogState = undefined>(
         return entry
       },
     },
+    async *events({ signal } = {}) {
+      // The current statuses first. A change while the reader handles an
+      // event waits in the queue.
+      const queue: Array<HostEvent> = [...statuses.values()]
+      let wake = () => {}
+      const listener = (event: HostEvent) => {
+        queue.push(event)
+        wake()
+      }
+      const onAbort = () => wake()
+      listeners.add(listener)
+      signal?.addEventListener('abort', onAbort)
+      try {
+        while (!signal?.aborted) {
+          const next = queue.shift()
+          if (next) {
+            yield next
+            continue
+          }
+          await new Promise<void>((resolve) => {
+            wake = resolve
+          })
+        }
+      } finally {
+        // A loop that ends (break, return, throw, abort) stops listening.
+        listeners.delete(listener)
+        signal?.removeEventListener('abort', onAbort)
+      }
+    },
   }
   turnFinders.set(host, async (name, operationId) => {
     for (const [key, opening] of sessions) {
diff --git a/packages/ai-harness/src/http.ts b/packages/ai-harness/src/http.ts
index 2aa51503e9..19fe8e3d93 100644
--- a/packages/ai-harness/src/http.ts
+++ b/packages/ai-harness/src/http.ts
@@ -29,7 +29,7 @@ import type {
 } from '@tanstack/ai'
 import type { SessionIndexEntry } from '@tanstack/ai-persistence'
 import type { AnyHarness } from './define'
-import type { HarnessHost } from './host'
+import type { HarnessHost, HostEvent } from './host'
 import type { HostFrame } from './protocol'
 import type { HarnessSession } from './session'
 import type { Principal, UserInput } from './types'
@@ -90,6 +90,33 @@ const json = (body: unknown, status = 200) =>
     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 })
+}
+
 /** A handler error as JSON: a `MediaError` keeps its status, the rest is 400. */
 const failed = (error: unknown) =>
   error instanceof MediaError
@@ -238,6 +265,10 @@ async function mediaResponse(
  *   `{ op: 'fork', threadId, through }` with a message id. Rename and fork
  *   answer with the entry, delete with 204. 403 when `canAccess` refuses
  *   the thread, 404 for a thread this principal does not own.
+ * - `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.
@@ -424,29 +455,31 @@ export function createHarnessHandler(
           request.headers.get('Last-Event-ID') ??
           url.searchParams.get('from') ??
           undefined
-        // Stops when the client cancels the response stream.
-        const reader = new AbortController()
-        const body = new ReadableStream<Uint8Array>({
-          cancel: () => reader.abort(),
-          async start(controller) {
-            try {
-              for await (const entry of session.events({
-                ...(from ? { from } : {}),
-                signal: reader.signal,
-              })) {
-                const frame: HostFrame = { type: 'harness.event', ...entry }
-                controller.enqueue(
-                  encoder.encode(
-                    `id: ${entry.cursor}\ndata: ${JSON.stringify(frame)}\n\n`,
-                  ),
-                )
-              }
-            } finally {
-              if (!reader.signal.aborted) controller.close()
-            }
-          },
+        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 }
+          }
         })
-        return new Response(body, { headers: SSE_HEADERS })
       }
 
       if (request.method === 'POST' && route === 'control') {
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index 644e3811db..ba67d5f34d 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -79,7 +79,11 @@ export type {
   HarnessHost,
   HarnessHostOptions,
   HarnessPersistence,
+  HostEvent,
+  HostSessionDeletedEvent,
+  HostSessionEvent,
   HostSessions,
+  HostStatusEvent,
   OpenSessionOptions,
 } from './host'
 export type {
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 22a9b5a36c..5832da808f 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -78,6 +78,7 @@ import type {
   LogStore,
   MessageStore,
   SessionIndexEntry,
+  SessionIndexStore,
 } from '@tanstack/ai-persistence'
 import type { AuthRequiredError, CredentialsAccess } from './auth'
 import type { EventFeed } from './feed'
@@ -147,6 +148,16 @@ export interface AgentStartOptions extends AgentRunOptions {
   wake?: boolean
 }
 
+/** One agent run as a child of the session thread. */
+interface AgentChild {
+  /** The run id of the child. Its index entry is `subagent:<subagentRunId>`. */
+  subagentRunId: string
+  /** The `subagent` tool call that started the run. */
+  parentToolCallId?: string
+  /** Text for an agent without `inputSchema`: one user message at the end. */
+  prompt?: string
+}
+
 type RunArgs<TAgent, TOptions> =
   AgentInputOf<TAgent> extends undefined
     ? [input?: undefined, options?: TOptions]
@@ -275,6 +286,8 @@ export interface SessionDependencies {
   lease?: LeaseOptions
   /** The `promptCache` of `host.open()`. It overrides the harness value. */
   promptCache?: PromptCacheOptions
+  /** Gets each event the session publishes, after the feed has it. */
+  onEvent: (event: StreamChunk) => void
   onClose: () => void
 }
 
@@ -607,6 +620,19 @@ const notOpenMessages: MessageStore = {
   saveThread: notOpen,
 }
 
+/** `feed`, and `onEvent` after each publish. This is how the host sees events. */
+function tapFeed(feed: EventFeed, onEvent: (event: StreamChunk) => void) {
+  return {
+    publish: (operationId, event) => {
+      feed.publish(operationId, event)
+      onEvent(event)
+    },
+    head: () => feed.head(),
+    read: (options) => feed.read(options),
+    close: () => feed.close(),
+  } satisfies EventFeed
+}
+
 /**
  * A live harness session: one conversation (`threadId`) with its plugins,
  * operations, inbox, and event stream. Open one with `host.open()`.
@@ -625,11 +651,17 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
   private readonly principal: Principal | undefined
   /** The session log writer of a durable host. It is also the feed. */
   private writer: LogWriter | undefined
-  private feed: EventFeed = new SessionFeed()
+  private feed: EventFeed
+  private readonly onEvent: (event: StreamChunk) => void
   /** The transcript: `stores.messages`, or a view of the log. */
   private messages: MessageStore
-  /** What `withPersistence` gets: the chat stores, with `messages`. */
-  private chatPersistence: AIPersistence<ChatTranscriptStores> | undefined
+  /**
+   * What `withPersistence` gets: the chat stores, with `messages`. With
+   * `sessions`, each child the model starts gets an index entry.
+   */
+  private chatPersistence:
+    | AIPersistence<ChatTranscriptStores & { sessions?: SessionIndexStore }>
+    | undefined
   /** The message store the chat engine saves through, on a durable host. */
   private engine: ReturnType<typeof engineMessageStore> | undefined
   /** Why the session log stopped taking writes. */
@@ -747,6 +779,8 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       options: this.harness.media,
     })
     this.principal = deps.principal
+    this.onEvent = deps.onEvent
+    this.feed = tapFeed(new SessionFeed(), deps.onEvent)
     this.onClose = deps.onClose
     this.hostId = deps.hostId
     this.index = deps.index
@@ -931,7 +965,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       this.writer = await this.log.open(this.threadId, (error) =>
         this.stopOnLogFailure(error),
       )
-      this.feed = this.writer
+      this.feed = tapFeed(this.writer, this.onEvent)
       const view = {
         writer: this.writer,
         store,
@@ -947,6 +981,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         ...(stores.runs ? { runs: stores.runs } : {}),
         ...(stores.interrupts ? { interrupts: stores.interrupts } : {}),
         ...(stores.metadata ? { metadata: stores.metadata } : {}),
+        ...(stores.sessions ? { sessions: stores.sessions } : {}),
       },
     }
     const { writer } = this
@@ -2632,14 +2667,33 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
    * plugins, then of run plugins, then the session's media middleware. It
    * keeps the media the agents make, publishes a `harness.media` event for
    * each file, and pushes its record to `captured`. The agents read the
-   * session's provider keys as `ctx.keys`.
+   * session's provider keys as `ctx.keys`. With `agents` (the subagents of
+   * a turn), the `subagent` tool can start one of them in the background.
    */
   private binding(
     operation: OperationImpl<unknown> | OperationImpl<ChatTurnResult>,
     captured: Array<MediaRecord>,
     runPlugins?: MountedPlugins,
+    agents?: ReadonlyArray<AnyAgent>,
   ) {
     const options = this.harness.media
+    // The child runs as a background agent of this session, and its end
+    // starts a new turn. Core does not pass `start` to nested children.
+    const start: SubagentBinding['start'] =
+      agents &&
+      (async (call, startOptions) => {
+        const agent = agents.find((entry) => entry.name === call.agent)
+        if (!agent) throw new Error(`Unknown agent "${call.agent}".`)
+        const subagentRunId = createSubagentId()
+        this.runAgent(agent, call.input, startOptions, {
+          subagentRunId,
+          ...(call.prompt !== undefined && { prompt: call.prompt }),
+          ...(call.parentToolCallId !== undefined && {
+            parentToolCallId: call.parentToolCallId,
+          }),
+        })
+        return { subagentRunId }
+      })
     return {
       generationMiddleware: [
         ...(this.sessionPlugins?.generationMiddleware ?? []),
@@ -2675,6 +2729,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       keys: this.keys,
       // A child uses its own threadId as the key, so only the retention goes down.
       promptCache: this.promptCache.retention,
+      ...(start && { start }),
     } satisfies SubagentBinding
   }
 
@@ -3092,7 +3147,12 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
                   subagents: {
                     ...bag,
                     limits: bag.limits ?? this.limits(),
-                    binding: this.binding(operation, captured, runPlugins),
+                    binding: this.binding(
+                      operation,
+                      captured,
+                      runPlugins,
+                      bag.agents,
+                    ),
                   },
                 }
               : {}),
@@ -3595,6 +3655,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     target: string | AnyAgent,
     input: unknown,
     options: AgentStartOptions,
+    child: AgentChild = { subagentRunId: createSubagentId() },
   ): OperationImpl<unknown> {
     const name = typeof target === 'string' ? target : target.name
     const operation = new OperationImpl<unknown>(
@@ -3606,7 +3667,14 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     this.operations.set(operation.id, operation)
     // The agent runs for the sender of the turn that starts it, also after
     // that turn ends.
-    void this.executeAgent(operation, target, input, options, this.sender())
+    void this.executeAgent(
+      operation,
+      target,
+      input,
+      options,
+      this.sender(),
+      child,
+    )
     return operation
   }
 
@@ -3656,6 +3724,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     input: unknown,
     options: AgentStartOptions,
     principal: Principal | undefined,
+    child: AgentChild,
   ): Promise<void> {
     const name = typeof target === 'string' ? target : target.name
     const inputId = createInputId()
@@ -3711,11 +3780,12 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       timestamp: Date.now(),
     })
     this.publishStarted(operation)
+    await this.indexAgent(operation, child, principal)
 
     let text = ''
     let result: unknown
     let failure: string | undefined
-    let subagentRunId = ''
+    const { subagentRunId, prompt } = child
     let stopRunLease = () => {}
     let releaseLease: (() => Promise<void>) | undefined
     try {
@@ -3727,13 +3797,19 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
         this.lease,
       )
       releaseLease = await this.holdLease(inputId, operation)
-      const messages = await this.messages.loadThread(this.threadId)
-      subagentRunId = createSubagentId()
+      const messages = (await this.messages.loadThread(this.threadId)) ?? []
       const stream = runAgentStream(
         agent,
         {
           input: checkedInput,
-          messages: messages ?? [],
+          // A prompt is one more user message at the end, as in core.
+          messages:
+            prompt === undefined
+              ? messages
+              : [
+                  ...messages,
+                  { role: 'user', content: prompt } satisfies ModelMessage,
+                ],
           threadId: `${this.threadId}:${name}`,
           runId: `${operation.id}:${subagentRunId}`,
           parentRunId: operation.id,
@@ -3836,6 +3912,39 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     this.publishFinished(operation)
   }
 
+  /**
+   * The index entry of an agent run: thread `subagent:<subagentRunId>`, with
+   * this thread as its parent. `upsert` replaces the whole entry, so the
+   * fields of other writers stay. A failed write does not fail the run.
+   */
+  private async indexAgent(
+    operation: OperationImpl<unknown>,
+    child: AgentChild,
+    principal: Principal | undefined,
+  ) {
+    const threadId = `subagent:${child.subagentRunId}`
+    const now = Date.now()
+    await this.index
+      .update(threadId, (entry) => ({
+        ...entry,
+        threadId,
+        parentThreadId: this.threadId,
+        ...(child.parentToolCallId !== undefined && {
+          parentToolCallId: child.parentToolCallId,
+        }),
+        createdAt: entry?.createdAt ?? now,
+        updatedAt: now,
+        ...storedPrincipal(entry?.principal ?? principal),
+      }))
+      .catch((error: unknown) =>
+        this.warn(
+          operation,
+          'harness:sessions',
+          `The session index was not updated. ${String(error)}`,
+        ),
+      )
+  }
+
   /**
    * Tell the main model how an agent ended: a transcript note (unless
    * `attach: 'none'`), and a new chat turn when `wake` is set. The wake turn
diff --git a/packages/ai-harness/tests/bound-output.test.ts b/packages/ai-harness/tests/bound-output.test.ts
new file mode 100644
index 0000000000..1cfc3eaddc
--- /dev/null
+++ b/packages/ai-harness/tests/bound-output.test.ts
@@ -0,0 +1,311 @@
+import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { defineAgent, toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '../src'
+import { boundText, boundToolOutput } from '../src/first-party/bound-output'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { AnyTool, ModelMessage } from '@tanstack/ai'
+import type { AnyAgent, AnyHarness } from '../src'
+
+const DAY = 24 * 60 * 60 * 1000
+/** Five lines, 34 bytes. */
+const FIVE_LINES = 'line 1\nline 2\nline 3\nline 4\nline 5'
+/** FIVE_LINES cut to `maxLines: 3`. */
+const FIRST_THREE =
+  'line 1\nline 2\nline 3\n\n[Output cut. Showing the first 3 of 5 lines, 20 of 34 bytes.]'
+
+let dir: string
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'harness-bound-output-'))
+})
+
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true })
+})
+
+/** A tool named `lookup` that returns `output`. */
+function lookup(output: unknown) {
+  return toolDefinition({
+    name: 'lookup',
+    description: 'Look something up',
+  }).server(async () => output)
+}
+
+/** A model that calls `tool` once, then answers. */
+function callsOnce(tool: string) {
+  return mockAdapter([() => toolCall(tool, {}), () => text('done')])
+}
+
+/** The tool message in the messages of one model call. */
+function toolMessageIn(call: { messages: Array<ModelMessage> }) {
+  return call.messages.find((message) => message.role === 'tool')
+}
+
+/** Open a session on `harness`, send one prompt, and close it. */
+async function promptOnce(harness: AnyHarness) {
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const session = await host.open(harness, { threadId: 't' })
+  await session.prompt('go')
+  await host.close()
+}
+
+/** The lead model calls `tool`. Gives back the tool message the model saw. */
+async function leadToolMessage(
+  tool: AnyTool,
+  options: Parameters<typeof boundToolOutput>[0] = { maxLines: 3 },
+) {
+  const model = callsOnce(tool.name)
+  await promptOnce(
+    defineHarness({
+      name: 'test/bound-output',
+      adapter: model.adapter,
+      tools: [tool],
+      plugins: () => [boundToolOutput(options)],
+    }),
+  )
+  return toolMessageIn(model.calls[1])
+}
+
+/** The lead model calls `lookup`, which returns `output`. Gives back the result the model saw. */
+async function leadSees(
+  output: unknown,
+  options?: Parameters<typeof boundToolOutput>[0],
+) {
+  const message = await leadToolMessage(lookup(output), options)
+  return message?.content
+}
+
+/** The lead model calls `agent` as a subagent. Gives back the result the model saw, parsed. */
+async function leadSeesAgent(agent: AnyAgent) {
+  const lead = callsOnce(agent.name)
+  await promptOnce(
+    defineHarness({
+      name: 'test/bound-output',
+      adapter: lead.adapter,
+      subagents: { agents: [agent] },
+      plugins: () => [boundToolOutput({ maxLines: 3 })],
+    }),
+  )
+  return JSON.parse(String(toolMessageIn(lead.calls[1])?.content))
+}
+
+/** The paths of the outputs saved in `dir`. */
+async function savedOutputs() {
+  const names = await readdir(dir)
+  return names
+    .filter((name) => name.startsWith('tool-output-'))
+    .map((name) => join(dir, name))
+}
+
+describe('boundText', () => {
+  it.each([
+    [
+      'too many lines',
+      'a\nb\nc\nd',
+      { maxLines: 2, maxBytes: 100 },
+      'a\nb\n\n[Output cut. Showing the first 2 of 4 lines, 3 of 7 bytes.]',
+    ],
+    [
+      'too many bytes',
+      'abcdef',
+      { maxLines: 10, maxBytes: 4 },
+      'abcd\n\n[Output cut. Showing the first 1 of 1 lines, 4 of 6 bytes.]',
+    ],
+    [
+      'a two-byte character over the byte limit',
+      'aéé',
+      { maxLines: 10, maxBytes: 4 },
+      'aé\n\n[Output cut. Showing the first 1 of 1 lines, 3 of 5 bytes.]',
+    ],
+    [
+      'a surrogate pair over the byte limit',
+      'x\u{1F600}',
+      { maxLines: 10, maxBytes: 4 },
+      'x\n\n[Output cut. Showing the first 1 of 1 lines, 1 of 5 bytes.]',
+    ],
+  ])('keeps the head of text with %s', (_case, input, limits, expected) => {
+    expect(boundText(input, limits)).toEqual({ text: expected, truncated: true })
+  })
+
+  it.each([
+    [
+      'too many lines',
+      'a\nb\nc\nd',
+      { maxLines: 2, maxBytes: 100 },
+      '[Output cut. Showing the last 2 of 4 lines, 3 of 7 bytes.]\n\nc\nd',
+    ],
+    [
+      'too many lines and a final newline',
+      'a\nb\nc\n',
+      { maxLines: 2, maxBytes: 100 },
+      '[Output cut. Showing the last 2 of 3 lines, 4 of 6 bytes.]\n\nb\nc\n',
+    ],
+    [
+      'too many bytes',
+      'abcdef',
+      { maxLines: 10, maxBytes: 4 },
+      '[Output cut. Showing the last 1 of 1 lines, 4 of 6 bytes.]\n\ncdef',
+    ],
+    [
+      'a two-byte character over the byte limit',
+      'ééa',
+      { maxLines: 10, maxBytes: 4 },
+      '[Output cut. Showing the last 1 of 1 lines, 3 of 5 bytes.]\n\néa',
+    ],
+    [
+      'a surrogate pair over the byte limit',
+      '\u{1F600}x',
+      { maxLines: 10, maxBytes: 4 },
+      '[Output cut. Showing the last 1 of 1 lines, 1 of 5 bytes.]\n\nx',
+    ],
+  ])('keeps the tail of text with %s', (_case, input, limits, expected) => {
+    expect(boundText(input, { ...limits, keep: 'tail' })).toEqual({
+      text: expected,
+      truncated: true,
+    })
+  })
+
+  it('leaves text inside both limits, and a final newline is not an extra line', () => {
+    expect(boundText('a\nb\n', { maxLines: 2, maxBytes: 4 })).toEqual({
+      text: 'a\nb\n',
+      truncated: false,
+    })
+  })
+})
+
+describe('boundToolOutput', () => {
+  it('cuts a long string result to its first lines, with a note', async () => {
+    expect(await leadSees(FIVE_LINES)).toBe(FIRST_THREE)
+  })
+
+  it('cuts any other value as JSON text', async () => {
+    const seen = await leadSees({ name: 'x'.repeat(200) }, { maxBytes: 20 })
+
+    expect(seen).toBe(
+      `{"name":"${'x'.repeat(11)}\n\n[Output cut. Showing the first 1 of 1 lines, 20 of 211 bytes.]`,
+    )
+  })
+
+  it('leaves a short result alone and saves no file', async () => {
+    const seen = await leadSees('line 1\nline 2', { maxLines: 3, dir })
+
+    expect(seen).toBe('line 1\nline 2')
+    expect(await savedOutputs()).toEqual([])
+  })
+
+  it('leaves content parts alone', async () => {
+    const image = [
+      {
+        type: 'image',
+        source: { type: 'data', value: 'A'.repeat(500), mimeType: 'image/png' },
+      },
+    ]
+
+    expect(await leadSees(image, { maxBytes: 100 })).toEqual(image)
+  })
+
+  it('cuts the error text of a failed call, and it stays an error', async () => {
+    const failing = toolDefinition({
+      name: 'lookup',
+      description: 'Look something up',
+    }).server(async () => {
+      throw new Error(FIVE_LINES)
+    })
+
+    const message = await leadToolMessage(failing)
+
+    expect(message).toMatchObject({
+      content: JSON.stringify({ error: FIRST_THREE }),
+      error: FIRST_THREE,
+    })
+  })
+
+  it('saves the full output in dir and gives its path in the note', async () => {
+    const seen = await leadSees(FIVE_LINES, { maxLines: 3, dir })
+
+    const [saved = ''] = await savedOutputs()
+    expect(saved).toMatch(/tool-output-\d+-call-1\.txt$/)
+    expect(seen).toBe(`${FIRST_THREE}\n[Full output saved to ${saved}.]`)
+    expect(await readFile(saved, 'utf8')).toBe(FIVE_LINES)
+  })
+
+  it('removes saved outputs older than retentionDays and keeps other files', async () => {
+    const old = `tool-output-${Date.now() - 8 * DAY}-old.txt`
+    const recent = `tool-output-${Date.now() - DAY}-recent.txt`
+    const names = [old, recent, 'notes.txt']
+    await Promise.all(names.map((name) => writeFile(join(dir, name), 'x')))
+
+    await leadSees(FIVE_LINES, { maxLines: 3, dir, retentionDays: 7 })
+
+    const left = await readdir(dir)
+    expect(left).not.toContain(old)
+    expect(left).toEqual(expect.arrayContaining([recent, 'notes.txt']))
+    expect(left).toHaveLength(3)
+  })
+
+  it('still cuts the result when the full output cannot be saved', async () => {
+    const file = join(dir, 'a-file')
+    await writeFile(file, 'x')
+
+    const seen = await leadSees(FIVE_LINES, {
+      maxLines: 3,
+      dir: join(file, 'out'),
+    })
+
+    expect(seen).toEqual(
+      expect.stringContaining(
+        `${FIRST_THREE}\n[The full output was not saved: Error:`,
+      ),
+    )
+  })
+
+  it('cuts a tool result in a subagent run too', async () => {
+    const researcherModel = callsOnce('lookup')
+    const researcher = defineAgent({
+      name: 'researcher',
+      description: 'Looks things up',
+      run: (ctx) =>
+        ctx.chat({
+          adapter: researcherModel.adapter,
+          tools: [lookup(FIVE_LINES)],
+        }),
+    })
+
+    await leadSeesAgent(researcher)
+
+    expect(toolMessageIn(researcherModel.calls[1])?.content).toBe(FIRST_THREE)
+  })
+
+  it('cuts a subagent answer and keeps its subagentRunId', async () => {
+    const answers = mockAdapter([() => text(FIVE_LINES)])
+    const researcher = defineAgent({
+      name: 'researcher',
+      description: 'Looks things up',
+      run: (ctx) => ctx.chat({ adapter: answers.adapter }),
+    })
+
+    expect(await leadSeesAgent(researcher)).toEqual({
+      subagentRunId: expect.stringMatching(/.+/),
+      result: FIRST_THREE,
+    })
+  })
+
+  it('leaves a failed subagent call alone, so it keeps its subagentRunId', async () => {
+    const researcher = defineAgent({
+      name: 'researcher',
+      description: 'Looks things up',
+      run: async () => {
+        throw new Error(FIVE_LINES)
+      },
+    })
+
+    expect(await leadSeesAgent(researcher)).toEqual({
+      subagentRunId: expect.stringMatching(/.+/),
+      error: FIVE_LINES,
+    })
+  })
+})
diff --git a/packages/ai-harness/tests/coding-bash.test.ts b/packages/ai-harness/tests/coding-bash.test.ts
new file mode 100644
index 0000000000..a40478f6ed
--- /dev/null
+++ b/packages/ai-harness/tests/coding-bash.test.ts
@@ -0,0 +1,256 @@
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import {
+  bashResources,
+  bashTools,
+  splitCommand,
+} from '../src/first-party/coding/bash'
+import { decidePermission } from '../src/first-party/permissions'
+import type { ToolEnv, WorkspaceBackend } from '../src/first-party/coding/backend'
+import type { PermissionRule } from '../src/first-party/permissions'
+
+type ExecOptions = Parameters<WorkspaceBackend['exec']>[1]
+type BashOptions = Parameters<typeof bashTools>[1]
+
+const root = resolve(tmpdir(), 'harness-bash')
+const OK = { exitCode: 0, stdout: 'ok', stderr: '' }
+// 3000 lines: the model gets only the last 1000.
+const LONG = {
+  exitCode: 1,
+  stdout: 'old\n'.repeat(2000) + 'new\n'.repeat(1000),
+  stderr: '',
+}
+const LONG_RESULT = `exit code: 1\n[Output cut. Showing the last 1000 of 3000 lines, 4000 of 12000 bytes.]\n\n${'new\n'.repeat(1000)}`
+
+/**
+ * A workspace whose commands all give back `result`. It records each
+ * command and each written file. `backend` replaces parts of the backend.
+ */
+function workspace(
+  result: { exitCode: number; stdout: string; stderr: string },
+  backend: Partial<WorkspaceBackend> = {},
+) {
+  const execs: Array<{ command: string; options: ExecOptions }> = []
+  const files = new Map<string, string | Uint8Array>()
+  const env: ToolEnv = {
+    backend: {
+      readFile: async (path) => {
+        throw new Error(`No file ${path}`)
+      },
+      writeFile: async (path, data) => {
+        files.set(path, data)
+      },
+      stat: async () => undefined,
+      readdir: async () => [],
+      exec: async (command, options) => {
+        execs.push({ command, options })
+        return result
+      },
+      ...backend,
+    },
+    root,
+    hooks: () => [],
+    lock: (_path, fn) => fn(),
+    reach: async (path) => path,
+    shown: (full) => full,
+  }
+  return { env, execs, files }
+}
+
+/** Run the `bash` tool once. */
+async function bash(env: ToolEnv, args: object, options?: BashOptions) {
+  const [tool] = bashTools(env, options)
+  if (!tool?.execute) throw new Error('No bash tool')
+  return tool.execute(args)
+}
+
+/** A background job that ends when the test calls `end`, or when killed. */
+function fakeJob(output: string) {
+  let end!: (exitCode: number) => void
+  const exited = new Promise<{ exitCode: number }>((done) => {
+    end = (exitCode) => done({ exitCode })
+  })
+  const job = {
+    killed: false,
+    wait: () => exited,
+    kill: () => {
+      job.killed = true
+      end(143)
+    },
+    output: () => output,
+  }
+  return { job, end }
+}
+
+/** A `note` option that keeps each note. */
+function collectNotes() {
+  const notes: Array<string> = []
+  const note = async (text: string) => {
+    notes.push(text)
+  }
+  return { notes, note }
+}
+
+/** Wait until the promises that are ready now have run. */
+const settle = () => new Promise((done) => setTimeout(done, 0))
+
+describe('splitCommand', () => {
+  it.each([
+    { command: 'ls && rm -rf x', parts: ['ls', 'rm -rf x'] },
+    { command: 'a | b; c || d', parts: ['a', 'b', 'c', 'd'] },
+    { command: 'ls\npwd', parts: ['ls', 'pwd'] },
+    { command: 'echo "a && b"', parts: ['echo "a && b"'] },
+    { command: "echo 'a; b' && ls", parts: ["echo 'a; b'", 'ls'] },
+    { command: 'echo "a \\" b" && ls', parts: ['echo "a \\" b"', 'ls'] },
+    { command: 'echo a\\;b', parts: ['echo a\\;b'] },
+    { command: "echo $'a\\'b' && ls", parts: ["echo $'a\\'b'", 'ls'] },
+  ])('splits `$command`', ({ command, parts }) => {
+    expect(splitCommand(command)).toEqual(parts)
+  })
+
+  it.each([
+    { name: 'a command substitution', command: 'echo $(rm x) && ls' },
+    { name: 'a backtick', command: 'echo `rm x` && ls' },
+    { name: 'an input process substitution', command: 'diff <(ls a) b' },
+    { name: 'an output process substitution', command: 'ls | tee >(rm x)' },
+    { name: 'a heredoc', command: 'cat <<EOF && ls\nrm x\nEOF' },
+    { name: 'a quote that does not close', command: "echo 'a && rm x" },
+    { name: 'a function body', command: 'ls() ( rm -rf x ); ls' },
+  ])('gives back the whole command for $name', ({ command }) => {
+    expect(splitCommand(command)).toEqual([command])
+  })
+})
+
+describe('bash permissions', () => {
+  const rules: Array<PermissionRule> = [
+    { tool: 'bash', decision: 'ask', kind: 'execute' },
+    { tool: 'bash', resource: 'ls*', decision: 'allow' },
+  ]
+
+  it.each([
+    { command: 'ls -la && ls src', expected: 'allow' },
+    { command: 'ls && rm -rf x', expected: 'ask' },
+    { command: 'ls $(rm -rf x)', expected: 'ask' },
+    { command: 'ls() ( rm -rf x ); ls', expected: 'ask' },
+  ])('$expected for `$command`, with an allow rule for ls*', (example) => {
+    const commands = bashResources({ command: example.command })
+    expect(
+      decidePermission(rules, 'bash', 'default', { resources: { commands } }),
+    ).toBe(example.expected)
+  })
+
+  it('refuses a call without a command string', () => {
+    expect(() => bashResources({ command: 1 })).toThrow(
+      'Argument "command" must be a string.',
+    )
+  })
+})
+
+describe('bash', () => {
+  it('runs the command in the workspace, with AGENT=1 and the default timeout', async () => {
+    const { env, execs } = workspace(OK)
+    expect(await bash(env, { command: 'make' })).toBe('exit code: 0\nok')
+    expect(execs).toEqual([
+      {
+        command: 'make',
+        options: { cwd: root, env: { AGENT: '1' }, timeoutMs: 120_000 },
+      },
+    ])
+  })
+
+  it.each([
+    { name: 'the factory timeout without one', args: {}, expected: 30_000 },
+    { name: 'the timeout of the call', args: { timeoutMs: 5_000 }, expected: 5_000 },
+    { name: 'at most 10 minutes', args: { timeoutMs: 3_600_000 }, expected: 600_000 },
+    { name: 'the factory timeout for 0', args: { timeoutMs: 0 }, expected: 30_000 },
+  ])('gives exec $name', async ({ args, expected }) => {
+    const { env, execs } = workspace(OK)
+    await bash(env, { command: 'make', ...args }, { timeoutMs: 30_000 })
+    expect(execs[0]?.options?.timeoutMs).toBe(expected)
+  })
+
+  it('keeps the last lines of long output, with a note, and saves no file', async () => {
+    const { env, files } = workspace(LONG)
+    expect(await bash(env, { command: 'test' })).toBe(LONG_RESULT)
+    expect(files.size).toBe(0)
+  })
+
+  it('saves the full output in spillDir, and gives its path', async () => {
+    const { env, files } = workspace(LONG)
+    const result = await bash(
+      env,
+      { command: 'test' },
+      { spillDir: '.agent/bash' },
+    )
+    const [path = ''] = files.keys()
+    expect(files.size).toBe(1)
+    expect(dirname(path)).toBe(join(root, '.agent', 'bash'))
+    expect(files.get(path)).toBe(LONG.stdout)
+    expect(result).toBe(`${LONG_RESULT}\n[Full output saved to ${path}.]`)
+  })
+
+  it('still gives the output when the save fails', async () => {
+    const { env } = workspace(LONG, {
+      writeFile: async () => {
+        throw new Error('disk full')
+      },
+    })
+    expect(
+      await bash(env, { command: 'test' }, { spillDir: '.agent/bash' }),
+    ).toBe(
+      `${LONG_RESULT}\n[The full output was not saved: Error: disk full]`,
+    )
+  })
+})
+
+describe('bash in the background', () => {
+  it('returns at once, and notes the exit code and output when the job ends', async () => {
+    const { job, end } = fakeJob('built\n')
+    const spawned: Array<{ command: string; options: unknown }> = []
+    const { env } = workspace(OK, {
+      spawn: (command, options) => {
+        spawned.push({ command, options })
+        return job
+      },
+    })
+    const { notes, note } = collectNotes()
+    expect(
+      await bash(env, { command: 'npm run build', background: true }, { note }),
+    ).toEqual({ jobId: 'bash-1', status: 'started' })
+    expect(spawned).toEqual([
+      {
+        command: 'npm run build',
+        options: { cwd: root, env: { AGENT: '1' } },
+      },
+    ])
+    await settle()
+    expect(notes).toEqual([])
+    end(2)
+    await settle()
+    expect(notes).toEqual(['Background job bash-1 ended.\nexit code: 2\nbuilt\n'])
+  })
+
+  it('kills running jobs when the signal aborts, and sends no note', async () => {
+    const { job } = fakeJob('')
+    const { env } = workspace(OK, { spawn: () => job })
+    const { notes, note } = collectNotes()
+    const controller = new AbortController()
+    await bash(
+      env,
+      { command: 'npm run dev', background: true },
+      { note, signal: controller.signal },
+    )
+    controller.abort()
+    await settle()
+    expect(job.killed).toBe(true)
+    expect(notes).toEqual([])
+  })
+
+  it('gives a tool error when the backend cannot start background commands', async () => {
+    const { env } = workspace(OK)
+    await expect(
+      bash(env, { command: 'npm run dev', background: true }),
+    ).rejects.toThrow('This workspace cannot run commands in the background.')
+  })
+})
diff --git a/packages/ai-harness/tests/coding-edit.test.ts b/packages/ai-harness/tests/coding-edit.test.ts
new file mode 100644
index 0000000000..10619c5d80
--- /dev/null
+++ b/packages/ai-harness/tests/coding-edit.test.ts
@@ -0,0 +1,162 @@
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { createWorkspaceTools } from '../src/first-party/coding/workspace'
+import type { AnyTool } from '@tanstack/ai'
+import type { WorkspaceBackend } from '../src/first-party/coding/backend'
+
+/** A backend that keeps files in a map, by absolute path. */
+function memoryBackend() {
+  const files = new Map<string, Uint8Array>()
+  const backend: WorkspaceBackend = {
+    readFile: async (path) => {
+      const data = files.get(path)
+      if (!data) throw new Error(`No file ${path}`)
+      return data
+    },
+    writeFile: async (path, data) => {
+      files.set(
+        path,
+        typeof data === 'string' ? new TextEncoder().encode(data) : data,
+      )
+    },
+    stat: async () => undefined,
+    readdir: async () => [],
+    exec: async () => ({ exitCode: 0, stdout: '', stderr: '' }),
+  }
+  return backend
+}
+
+const root = resolve(tmpdir(), 'harness-edit')
+const backend = memoryBackend()
+const tools: Array<AnyTool> = createWorkspaceTools({ root, backend }).tools
+// Keep a byte order mark in the text, so the tests can see it.
+const decoder = new TextDecoder('utf-8', { ignoreBOM: true })
+
+async function run(name: string, args: object) {
+  const tool = tools.find((item) => item.name === name)
+  if (!tool?.execute) throw new Error(`No tool ${name}`)
+  const result: string = await tool.execute(args)
+  return result
+}
+
+async function read(path: string) {
+  return decoder.decode(await backend.readFile(join(root, path)))
+}
+
+/** Write `text` to `path`, run `edit_file` on it, and read the file back. */
+async function edit(
+  path: string,
+  text: string,
+  change: { old: string; new: string; replaceAll?: boolean },
+) {
+  await backend.writeFile(join(root, path), text)
+  const result = await run('edit_file', { path, ...change })
+  return { result, text: await read(path) }
+}
+
+describe('edit_file', () => {
+  it('replaces the exact text', async () => {
+    expect(
+      await edit('exact.txt', 'let a = 1\nlet b = 2\n', {
+        old: 'a = 1',
+        new: 'a = 3',
+      }),
+    ).toEqual({
+      result: 'Edited exact.txt (1 change).',
+      text: 'let a = 3\nlet b = 2\n',
+    })
+  })
+
+  it('matches text in another Unicode form, and keeps the rest of the file', async () => {
+    // The file is in NFD form. The old text is in NFC form.
+    const { text } = await edit('nfd.txt', 'café and naïve\n', {
+      old: 'café',
+      new: 'tea',
+    })
+    expect(text).toBe('tea and naïve\n')
+  })
+
+  it('ignores spaces and tabs at the end of lines', async () => {
+    const { text } = await edit('trailing.txt', 'a  \nb\t\nc  \n', {
+      old: 'a\nb',
+      new: 'x',
+    })
+    expect(text).toBe('x\nc  \n')
+  })
+
+  it('prefers an exact match over a looser one', async () => {
+    // With trailing spaces ignored, `foo\n` is in the file twice.
+    const { text } = await edit('prefer.txt', 'foo\nfoo  \n', {
+      old: 'foo\n',
+      new: 'bar\n',
+    })
+    expect(text).toBe('bar\nfoo  \n')
+  })
+
+  it('refuses text that is not unique at the level that finds it, unless replaceAll', async () => {
+    const file = 'foo \nbar\nfoo\t\nbar\n'
+    await expect(
+      edit('twice.txt', file, { old: 'foo\nbar', new: 'x' }),
+    ).rejects.toThrow('The old text appears 2 times.')
+    expect(
+      await edit('twice.txt', file, {
+        old: 'foo\nbar',
+        new: 'x',
+        replaceAll: true,
+      }),
+    ).toEqual({ result: 'Edited twice.txt (2 changes).', text: 'x\nx\n' })
+  })
+
+  it('refuses text that is not in the file, and empty text', async () => {
+    await expect(
+      edit('missing.txt', 'abc\n', { old: 'zzz', new: 'q' }),
+    ).rejects.toThrow('The old text is not in the file.')
+    await expect(
+      edit('missing.txt', 'abc\n', { old: '', new: 'q' }),
+    ).rejects.toThrow('The old text is not in the file.')
+  })
+
+  it.each([
+    {
+      name: 'a CRLF file with LF text',
+      file: 'one\r\ntwo\r\nthree\r\n',
+      old: 'one\ntwo',
+      new: '1\n2',
+      expected: '1\r\n2\r\nthree\r\n',
+    },
+    {
+      name: 'an LF file with CRLF text',
+      file: 'one\ntwo\nthree\n',
+      old: 'one\r\ntwo',
+      new: '1\r\n2',
+      expected: '1\n2\nthree\n',
+    },
+  ])('edits $name, and keeps the line endings of the file', async (example) => {
+    const { text } = await edit('endings.txt', example.file, {
+      old: example.old,
+      new: example.new,
+    })
+    expect(text).toBe(example.expected)
+  })
+
+  it.each([
+    { name: 'without the mark', old: 'first' },
+    { name: 'that starts with the mark', old: 'first' },
+  ])('keeps the byte order mark, with old text $name', async ({ old }) => {
+    const { text } = await edit('bom.txt', 'first\nsecond\n', {
+      old,
+      new: '1st',
+    })
+    expect(text).toBe('1st\nsecond\n')
+  })
+})
+
+describe('write_file', () => {
+  it('writes the content as given', async () => {
+    expect(
+      await run('write_file', { path: 'new/w.txt', content: 'hi\r\n' }),
+    ).toBe('Wrote new/w.txt.')
+    expect(await read('new/w.txt')).toBe('hi\r\n')
+  })
+})
diff --git a/packages/ai-harness/tests/coding-patch.test.ts b/packages/ai-harness/tests/coding-patch.test.ts
new file mode 100644
index 0000000000..0e302f64a7
--- /dev/null
+++ b/packages/ai-harness/tests/coding-patch.test.ts
@@ -0,0 +1,415 @@
+import { tmpdir } from 'node:os'
+import { join, relative, resolve, sep } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import {
+  parsePatch,
+  patchPaths,
+  patchTools,
+} from '../src/first-party/coding/patch'
+import type { AnyTool } from '@tanstack/ai'
+import type {
+  ToolEnv,
+  WorkspaceBackend,
+} from '../src/first-party/coding/backend'
+
+const root = resolve(tmpdir(), 'harness-patch')
+const encoder = new TextEncoder()
+// Keep a byte order mark in the text, so the tests can see it.
+const decoder = new TextDecoder('utf-8', { ignoreBOM: true })
+
+/** A workspace path, with `/` between the parts. */
+const shown = (full: string) => relative(root, full).split(sep).join('/')
+
+/** A patch with `lines` between the begin and end lines. */
+function patch(...lines: Array<string>) {
+  return ['*** Begin Patch', ...lines, '*** End Patch'].join('\n')
+}
+
+/**
+ * The patch tool on files in memory that start as `files`. `written` lists
+ * the files that the `afterWrite` hook saw, in order.
+ */
+function workspace(files: Record<string, string>) {
+  const store = new Map<string, Uint8Array>()
+  for (const [path, text] of Object.entries(files)) {
+    store.set(join(root, path), encoder.encode(text))
+  }
+  const backend: WorkspaceBackend = {
+    readFile: async (path) => {
+      const data = store.get(path)
+      if (!data) throw new Error(`No file ${path}`)
+      return data
+    },
+    writeFile: async (path, data) => {
+      store.set(path, typeof data === 'string' ? encoder.encode(data) : data)
+    },
+    stat: async () => undefined,
+    readdir: async () => [],
+    exec: async () => ({ exitCode: 0, stdout: '', stderr: '' }),
+  }
+  const written: Array<string> = []
+  const env: ToolEnv = {
+    backend,
+    root,
+    hooks: () => [
+      {
+        afterWrite: async (path) => {
+          written.push(shown(path))
+        },
+      },
+    ],
+    lock: (_path, fn) => fn(),
+    reach: async (path) => resolve(root, path),
+    shown,
+  }
+  const tools: Array<AnyTool> = patchTools(env)
+  const [tool] = tools
+  return {
+    written,
+    run: async (text: string) => {
+      if (!tool?.execute) throw new Error('No patch tool')
+      const result: string = await tool.execute({ patch: text })
+      return result
+    },
+    /** Every file, by workspace path. */
+    files: () =>
+      Object.fromEntries(
+        [...store].map(
+          ([full, data]) => [shown(full), decoder.decode(data)] as const,
+        ),
+      ),
+  }
+}
+
+/** Apply `text` to a workspace with one file, `a.txt`, and read it back. */
+async function patchFile(content: string, text: string) {
+  const files = workspace({ 'a.txt': content })
+  await files.run(text)
+  return files.files()['a.txt']
+}
+
+describe('parsePatch', () => {
+  it('reads added, deleted, and updated files, and a move', () => {
+    const text = patch(
+      '*** Add File: src/new.ts',
+      '+export const a = 1',
+      '+',
+      '*** Delete File: old.txt',
+      '*** Update File: src/app.ts',
+      '*** Move to: src/main.ts',
+      '@@ function main() {',
+      ' const x = 1',
+      '-const y = 2',
+      '+const y = 3',
+    )
+    expect(parsePatch(text)).toEqual([
+      { type: 'add', path: 'src/new.ts', content: 'export const a = 1\n\n' },
+      { type: 'delete', path: 'old.txt' },
+      {
+        type: 'update',
+        path: 'src/app.ts',
+        movePath: 'src/main.ts',
+        chunks: [
+          {
+            context: 'function main() {',
+            oldLines: ['const x = 1', 'const y = 2'],
+            newLines: ['const x = 1', 'const y = 3'],
+            endOfFile: false,
+          },
+        ],
+      },
+    ])
+  })
+
+  it('reads several chunks, a first chunk without @@, End of File, and CRLF text', () => {
+    const text = patch(
+      '*** Update File: a.txt',
+      '-one',
+      '+1',
+      '@@',
+      ' two',
+      '',
+      '-three',
+      '*** End of File',
+    ).replaceAll('\n', '\r\n')
+    expect(parsePatch(text)).toEqual([
+      {
+        type: 'update',
+        path: 'a.txt',
+        chunks: [
+          {
+            oldLines: ['one'],
+            newLines: ['1'],
+            endOfFile: false,
+          },
+          {
+            oldLines: ['two', '', 'three'],
+            newLines: ['two', ''],
+            endOfFile: true,
+          },
+        ],
+      },
+    ])
+  })
+
+  it.each([
+    {
+      name: 'a missing begin line',
+      text: '\n*** Update File: a.txt\n*** End Patch',
+      error: 'Patch line 2: the patch must start with "*** Begin Patch".',
+    },
+    {
+      name: 'a missing end line',
+      text: '*** Begin Patch\n*** Delete File: a.txt\n',
+      error: 'Patch line 2: the patch must end with "*** End Patch".',
+    },
+    {
+      name: 'an unknown header',
+      text: patch('*** Rename File: a.txt'),
+      error:
+        'Patch line 2: expected "*** Add File:", "*** Delete File:", or "*** Update File:".',
+    },
+    {
+      name: 'an added line without +',
+      text: patch('*** Add File: a.txt', '+one', 'two'),
+      error:
+        'Patch line 4: each line of an added file must start with "+".',
+    },
+    {
+      name: 'a chunk line without a prefix',
+      text: patch('*** Update File: a.txt', '@@', ' one', 'two'),
+      error:
+        'Patch line 5: each chunk line must start with " ", "-", or "+".',
+    },
+    {
+      name: 'an update without changes',
+      text: patch('*** Update File: a.txt', '@@', '*** Delete File: b.txt'),
+      error: 'Patch line 2: "*** Update File: a.txt" has no changes.',
+    },
+    {
+      name: 'a header without a path',
+      text: patch('*** Add File: '),
+      error: 'Patch line 2: the path is missing.',
+    },
+  ])('refuses $name', ({ text, error }) => {
+    expect(() => parsePatch(text)).toThrow(error)
+  })
+})
+
+describe('patchPaths', () => {
+  it('lists every path, with the move targets', () => {
+    const text = patch(
+      '*** Add File: new.txt',
+      '+x',
+      '*** Delete File: old.txt',
+      '*** Update File: src/a.ts',
+      '*** Move to: src/b.ts',
+      '-x',
+    )
+    expect(patchPaths(text)).toEqual([
+      'new.txt',
+      'old.txt',
+      'src/a.ts',
+      'src/b.ts',
+    ])
+  })
+
+  it('throws when the patch does not parse', () => {
+    expect(() => patchPaths('*** Delete File: a.txt')).toThrow(
+      'Patch line 1: the patch must start with "*** Begin Patch".',
+    )
+  })
+})
+
+describe('patch tool', () => {
+  it('adds and updates files, and lists them', async () => {
+    const files = workspace({ 'src/a.ts': 'const a = 1\nconst b = 2\n' })
+    const result = await files.run(
+      patch(
+        '*** Add File: src/new.ts',
+        '+hello',
+        '*** Update File: src/a.ts',
+        '@@',
+        '-const b = 2',
+        '+const b = 3',
+      ),
+    )
+    expect(result).toBe(
+      'Applied the patch:\nadded src/new.ts\nupdated src/a.ts',
+    )
+    expect(files.files()).toEqual({
+      'src/a.ts': 'const a = 1\nconst b = 3\n',
+      'src/new.ts': 'hello\n',
+    })
+  })
+
+  it('searches from the @@ line', async () => {
+    const file = 'function a() {\n  return 1\n}\nfunction b() {\n  return 1\n}\n'
+    const text = patch(
+      '*** Update File: a.txt',
+      '@@ function b() {',
+      '-  return 1',
+      '+  return 2',
+    )
+    expect(await patchFile(file, text)).toBe(
+      'function a() {\n  return 1\n}\nfunction b() {\n  return 2\n}\n',
+    )
+  })
+
+  it('puts only added lines below the @@ line', async () => {
+    const text = patch('*** Update File: a.txt', '@@ two', '+two and a half')
+    expect(await patchFile('one\ntwo\nthree\n', text)).toBe(
+      'one\ntwo\ntwo and a half\nthree\n',
+    )
+  })
+
+  it('searches each chunk after the chunk before it', async () => {
+    // `x` is in the file twice, but once after the first chunk.
+    const text = patch('*** Update File: a.txt', '@@', '-a', '+A', '@@', '-x', '+X')
+    expect(await patchFile('x\na\nx\n', text)).toBe('x\nA\nX\n')
+  })
+
+  it('matches the end of the file after End of File', async () => {
+    const text = patch(
+      '*** Update File: a.txt',
+      '@@',
+      '-end',
+      '+END',
+      '*** End of File',
+    )
+    expect(await patchFile('end\nmiddle\nend\n', text)).toBe(
+      'end\nmiddle\nEND\n',
+    )
+  })
+
+  it('sees the changes of an earlier section on the same file', async () => {
+    const text = patch(
+      '*** Update File: a.txt',
+      '-one',
+      '+1',
+      '*** Update File: a.txt',
+      '-1',
+      '+uno',
+    )
+    expect(await patchFile('one\n', text)).toBe('uno\n')
+  })
+
+  it.each([
+    {
+      name: 'a CRLF file stays CRLF',
+      file: 'one\r\ntwo\r\nthree\r\n',
+      expected: 'one\r\n2\r\nthree\r\n',
+    },
+    {
+      name: 'a byte order mark stays',
+      file: 'one\ntwo\nthree\n',
+      expected: 'one\n2\nthree\n',
+    },
+    {
+      name: 'a file without a last line ending stays without it',
+      file: 'one\ntwo',
+      expected: 'one\n2',
+    },
+  ])('$name', async ({ file, expected }) => {
+    const text = patch('*** Update File: a.txt', '@@', ' one', '-two', '+2')
+    expect(await patchFile(file, text)).toBe(expected)
+  })
+
+  it('matches lines in another Unicode form', async () => {
+    // The file is in NFD form. The patch is in NFC form.
+    const file = 'café\nnaïve\n'
+    const text = patch('*** Update File: a.txt', '@@', '-café', '+tea')
+    expect(await patchFile(file, text)).toBe('tea\nnaïve\n')
+  })
+
+  it.each([
+    {
+      name: 'old lines that are not in the file',
+      file: 'x\nmid\nx\n',
+      lines: ['@@', '-zzz', '+q'],
+      error: 'Chunk 1 of a.txt: the old lines are not in the file.',
+    },
+    {
+      name: 'old lines that are in the file twice',
+      file: 'x\nmid\nx\n',
+      lines: ['@@', '-x', '+y'],
+      error:
+        'Chunk 1 of a.txt: the old lines appear 2 times. Add context lines.',
+    },
+    {
+      name: 'an @@ line that is not in the file',
+      file: 'x\nmid\nx\n',
+      lines: ['@@ function nope() {', '-x', '+y'],
+      error: 'Chunk 1 of a.txt: "@@ function nope() {" is not in the file.',
+    },
+    {
+      // The file has `x` only at the end of the line `ax`.
+      name: 'old lines that start inside a line',
+      file: 'ax\nb\n',
+      lines: ['@@', '-x', '+y'],
+      error: 'Chunk 1 of a.txt: the old lines are not in the file.',
+    },
+  ])('refuses $name, and changes nothing', async ({ file, lines, error }) => {
+    const files = workspace({ 'a.txt': file })
+    await expect(
+      files.run(patch('*** Update File: a.txt', ...lines)),
+    ).rejects.toThrow(error)
+    expect(files.files()).toEqual({ 'a.txt': file })
+  })
+
+  it('changes no file when a later file does not fit', async () => {
+    const files = workspace({ 'a.txt': 'a\n', 'b.txt': 'b\n' })
+    const text = patch(
+      '*** Update File: a.txt',
+      '-a',
+      '+A',
+      '*** Add File: c.txt',
+      '+c',
+      '*** Update File: b.txt',
+      '-zzz',
+      '+Z',
+    )
+    await expect(files.run(text)).rejects.toThrow(
+      'Chunk 1 of b.txt: the old lines are not in the file.',
+    )
+    expect(files.files()).toEqual({ 'a.txt': 'a\n', 'b.txt': 'b\n' })
+    expect(files.written).toEqual([])
+  })
+
+  it('runs the afterWrite hook once for each written file', async () => {
+    const files = workspace({ 'a.txt': 'a\n', 'b.txt': 'b\n' })
+    await files.run(
+      patch(
+        '*** Update File: a.txt',
+        '-a',
+        '+A',
+        '*** Update File: b.txt',
+        '-b',
+        '+B',
+        '*** Update File: a.txt',
+        '-A',
+        '+AA',
+      ),
+    )
+    expect(files.written).toEqual(['a.txt', 'b.txt'])
+  })
+
+  it.each([
+    {
+      name: 'a delete',
+      lines: ['*** Delete File: a.txt'],
+      error: 'Cannot delete a.txt: the workspace cannot remove files.',
+    },
+    {
+      name: 'a move',
+      lines: ['*** Update File: a.txt', '*** Move to: b.txt'],
+      error: 'Cannot move a.txt: the workspace cannot remove files.',
+    },
+  ])('refuses $name, and changes nothing', async ({ lines, error }) => {
+    const files = workspace({ 'a.txt': 'a\n' })
+    await expect(
+      files.run(patch('*** Add File: c.txt', '+c', ...lines)),
+    ).rejects.toThrow(error)
+    expect(files.files()).toEqual({ 'a.txt': 'a\n' })
+  })
+})
diff --git a/packages/ai-harness/tests/permissions.test.ts b/packages/ai-harness/tests/permissions.test.ts
index c42116fb69..147a6af37b 100644
--- a/packages/ai-harness/tests/permissions.test.ts
+++ b/packages/ai-harness/tests/permissions.test.ts
@@ -32,6 +32,17 @@ function read(
   })
 }
 
+/** Run `fn` as if the host were `platform`. Letter case rules depend on it. */
+function onPlatform<T>(platform: NodeJS.Platform, fn: () => T) {
+  const real = process.platform
+  Object.defineProperty(process, 'platform', { value: platform })
+  try {
+    return fn()
+  } finally {
+    Object.defineProperty(process, 'platform', { value: real })
+  }
+}
+
 function run(commands: Array<string>, rules: Array<PermissionRule>) {
   return decidePermission(rules, 'bash', 'default', {
     resources: { commands },
@@ -57,6 +68,23 @@ describe('decidePermission with resources', () => {
     expect(decide(['src/a.ts', 'secrets/key'])).toBe('deny')
   })
 
+  it.each([
+    ['darwin', 'deny'],
+    ['win32', 'deny'],
+    ['linux', 'allow'],
+  ] as const)(
+    'on %s, a deny rule for a posix path matches another letter case: %s',
+    (platform, expected) => {
+      const rules: Array<PermissionRule> = [
+        ...readAllowed,
+        { tool: 'read_file', resource: 'secrets/**', decision: 'deny' },
+      ]
+      expect(onPlatform(platform, () => read('Secrets/key', { rules }))).toBe(
+        expected,
+      )
+    },
+  )
+
   it('fails closed when the resources of a call are not known', () => {
     const rules: Array<PermissionRule> = [
       ...readAllowed,
@@ -103,12 +131,15 @@ describe('decidePermission with resources', () => {
     ['..', '../secret.txt'],
     ['.. in the middle', 'src/../../secret.txt'],
     ['an absolute path', '/etc/passwd'],
-    ['another letter case on a case-sensitive system', '/work/Repo/a.ts'],
     ['a folder that only starts like the root', '/work/repo-evil/a.ts'],
   ])('asks for a path that leaves the workspace: %s', (_name, path) => {
     expect(read(path)).toBe('ask')
   })
 
+  it('asks for another letter case of the root on a case-sensitive system', () => {
+    expect(onPlatform('linux', () => read('/work/Repo/a.ts'))).toBe('ask')
+  })
+
   it.each([
     ['another drive', 'D:\\other\\x.txt'],
     ['a sibling folder in another letter case', 'C:/Work/Other/x.txt'],
diff --git a/packages/ai-harness/tests/status-feed.test.ts b/packages/ai-harness/tests/status-feed.test.ts
new file mode 100644
index 0000000000..b0bcfdc747
--- /dev/null
+++ b/packages/ai-harness/tests/status-feed.test.ts
@@ -0,0 +1,247 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  createHarnessHandler,
+  createHarnessHost,
+  defineHarness,
+  definePlugin,
+} from '../src'
+import { createHarnessClient } from '../src/client'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { HostEvent } from '../src'
+
+/** Read a stream of host events into `seen` until `stop()`. */
+function watch(read: (signal: AbortSignal) => AsyncIterable<HostEvent>) {
+  const seen: Array<HostEvent> = []
+  const reader = new AbortController()
+  const done = (async () => {
+    for await (const event of read(reader.signal)) seen.push(event)
+  })()
+  return {
+    seen,
+    stop: async () => {
+      reader.abort()
+      await done
+    },
+  }
+}
+
+/** The statuses of one thread, in order. */
+const statusesOf = (seen: ReadonlyArray<HostEvent>, threadId: string) =>
+  seen.flatMap((event) =>
+    event.type === 'status' && event.threadId === threadId
+      ? [event.status]
+      : [],
+  )
+
+const probe = toolDefinition({
+  name: 'probe',
+  description: 'Asks a question.',
+  inputSchema: z.object({}),
+})
+
+/** A harness whose turn calls a tool that asks a question, then answers. */
+function askingHarness() {
+  const asker = definePlugin({
+    name: 'test/asker',
+    setup: (ctx) => ({
+      tools: [
+        probe.server(async () => ({
+          sure: await ctx.session.ask({ message: 'Sure?' }),
+        })),
+      ],
+    }),
+  })
+  return defineHarness({
+    name: 'test/status-asking',
+    adapter: mockAdapter([() => toolCall('probe', {}), () => text('Done.')])
+      .adapter,
+    plugins: () => [asker],
+  })
+}
+
+const plainHarness = () =>
+  defineHarness({
+    name: 'test/status-plain',
+    adapter: mockAdapter(() => text('answer')).adapter,
+  })
+
+describe('host.events', () => {
+  it('shows each status change of two sessions', async () => {
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const feed = watch((signal) => host.events({ signal }))
+    const a = await host.open(askingHarness(), { threadId: 'a' })
+    const b = await host.open(plainHarness(), { threadId: 'b' })
+
+    const turn = a.prompt('go')
+    await vi.waitFor(() =>
+      expect(a.snapshot().pendingQuestions).toHaveLength(1),
+    )
+    await b.prompt('hi')
+    const [question] = a.snapshot().pendingQuestions
+    await a.answer(question?.questionId ?? '', 'yes')
+    await turn
+
+    await vi.waitFor(() =>
+      expect(statusesOf(feed.seen, 'a')).toEqual([
+        'idle',
+        'running',
+        'waiting',
+        'running',
+        'idle',
+      ]),
+    )
+    expect(statusesOf(feed.seen, 'b')).toEqual(['idle', 'running', 'idle'])
+    await feed.stop()
+    await host.close()
+  })
+
+  it('gives a late reader the current status of each open session first', async () => {
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const a = await host.open(askingHarness(), { threadId: 'a' })
+    await host.open(plainHarness(), { threadId: 'b' })
+    void a.prompt('go')
+    await vi.waitFor(() =>
+      expect(a.snapshot().pendingQuestions).toHaveLength(1),
+    )
+
+    const feed = watch((signal) => host.events({ signal }))
+
+    await vi.waitFor(() => expect(feed.seen).toHaveLength(2))
+    expect(feed.seen).toEqual([
+      { type: 'status', threadId: 'a', status: 'waiting', at: expect.any(Number) },
+      { type: 'status', threadId: 'b', status: 'idle', at: expect.any(Number) },
+    ])
+    await feed.stop()
+    await host.close()
+  })
+
+  it('shows a rename as a session event and a delete as session-deleted', async () => {
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    await host.open(plainHarness(), { threadId: 'b' })
+    const feed = watch((signal) => host.events({ signal }))
+
+    await host.sessions.rename('b', 'Greetings')
+    await host.sessions.delete('b')
+
+    await vi.waitFor(() => expect(feed.seen).toHaveLength(3))
+    expect(feed.seen).toMatchObject([
+      { type: 'status', threadId: 'b', status: 'idle' },
+      { type: 'session', threadId: 'b', entry: { title: 'Greetings' } },
+      { type: 'session-deleted', threadId: 'b', entry: { title: 'Greetings' } },
+    ])
+    await feed.stop()
+    await host.close()
+  })
+
+  it('stops a read when its loop ends or its signal aborts', async () => {
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    await host.open(plainHarness(), { threadId: 'b' })
+    const events = host.events()[Symbol.asyncIterator]()
+    expect(await events.next()).toMatchObject({ value: { status: 'idle' } })
+
+    await events.return?.()
+    await host.sessions.rename('b', 'After the end')
+
+    expect(await events.next()).toEqual({ done: true, value: undefined })
+    // `stop` resolves only when the waiting read ends.
+    const feed = watch((signal) => host.events({ signal }))
+    await vi.waitFor(() => expect(feed.seen).toHaveLength(1))
+    await feed.stop()
+    await host.close()
+  })
+})
+
+describe('GET host-events', () => {
+  /** A handler where the `x-user` header is the principal. */
+  function setup() {
+    const harness = plainHarness()
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    /** The thread of each `canAccess` call, in order. */
+    const checked: Array<string> = []
+    const handler = createHarnessHandler({
+      host,
+      harness,
+      authorize: (request) => {
+        const id = request.headers.get('x-user')
+        return id ? { id } : null
+      },
+      canAccess: (_principal, threadId) => {
+        checked.push(threadId)
+        return threadId !== 'hidden'
+      },
+    })
+    const fetch: typeof globalThis.fetch = (input, init) =>
+      handler(new Request(input, init))
+    const clientOf = (user: string) =>
+      createHarnessClient({
+        url: 'http://local/api/harness',
+        threadId: `${user}-thread`,
+        headers: { 'x-user': user },
+        fetch,
+      })
+    return { host, harness, handler, checked, clientOf }
+  }
+
+  it('sends a user only the events of the sessions of that user', async () => {
+    const { host, harness, handler, clientOf } = setup()
+    const alice = clientOf('alice')
+    const bob = clientOf('bob')
+    // Opens the thread of alice, so the feed starts with its status.
+    await alice.snapshot()
+    const feed = watch((signal) => alice.hostEvents({ signal }))
+    await vi.waitFor(() =>
+      expect(statusesOf(feed.seen, 'alice-thread')).toEqual(['idle']),
+    )
+
+    await bob.prompt('hi')
+    await vi.waitFor(async () =>
+      expect(await bob.transcript()).toHaveLength(2),
+    )
+    // Alice owns this thread, but `canAccess` refuses it.
+    await host.open(harness, { threadId: 'hidden', principal: { id: 'alice' } })
+    await alice.prompt('hi')
+
+    await vi.waitFor(() =>
+      expect(statusesOf(feed.seen, 'alice-thread')).toEqual([
+        'idle',
+        'running',
+        'idle',
+      ]),
+    )
+    expect(new Set(feed.seen.map((event) => event.threadId))).toEqual(
+      new Set(['alice-thread']),
+    )
+    const anonymous = await handler(
+      new Request('http://local/api/harness/host-events'),
+    )
+    expect(anonymous.status).toBe(401)
+    await feed.stop()
+    await host.close()
+  })
+
+  it('stops reading the host when the client leaves', async () => {
+    const { host, handler, checked, clientOf } = setup()
+    await clientOf('alice').snapshot()
+    const response = await handler(
+      new Request('http://local/api/harness/host-events', {
+        headers: { 'x-user': 'alice' },
+      }),
+    )
+    if (!response.body) throw new Error('The answer has no body.')
+    const reader = response.body.getReader()
+    const first = await reader.read()
+    expect(new TextDecoder().decode(first.value)).toContain('"status":"idle"')
+
+    await reader.cancel()
+    const checksBefore = checked.length
+    await host.sessions.rename('alice-thread', 'After the end')
+    await new Promise((resolve) => setTimeout(resolve, 20))
+
+    // A route that still read would check the access of the rename.
+    expect(checked).toHaveLength(checksBefore)
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/subagent-children.test.ts b/packages/ai-harness/tests/subagent-children.test.ts
new file mode 100644
index 0000000000..a75513d113
--- /dev/null
+++ b/packages/ai-harness/tests/subagent-children.test.ts
@@ -0,0 +1,172 @@
+import { describe, expect, it } from 'vitest'
+import { defineAgent } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '../src'
+import {
+  after,
+  gate,
+  messageTexts,
+  mockAdapter,
+  text,
+  toolCall,
+} from './helpers'
+import type { AnyTextAdapter, ModelMessage } from '@tanstack/ai'
+import type { HarnessPersistence } from '../src'
+
+/**
+ * Open thread `t` of a harness whose lead model can start `writer` through
+ * the single `subagent` tool. `writer` answers with `child`.
+ */
+async function openLead(
+  lead: AnyTextAdapter,
+  child: AnyTextAdapter,
+  persistence: HarnessPersistence = memoryPersistence(),
+) {
+  const writer = defineAgent({
+    name: 'writer',
+    description: 'Writes notes',
+    run: (ctx) => ctx.chat({ adapter: child }),
+  })
+  const host = createHarnessHost({ persistence })
+  const session = await host.open(
+    defineHarness({
+      name: 'test/subagent-children',
+      adapter: lead,
+      subagents: { agents: [writer], tool: 'single' },
+    }),
+    { threadId: 't' },
+  )
+  return { host, session }
+}
+
+/** One lead model call of the `subagent` tool for `writer`. */
+function callWriter(args: Record<string, unknown>, id: string) {
+  return toolCall('subagent', { agent: 'writer', ...args }, id)
+}
+
+/** The result the lead model got for tool call `id`, parsed. */
+function toolResultIn(call: { messages: Array<ModelMessage> }, id: string) {
+  const message = call.messages.find(
+    (entry) => entry.role === 'tool' && entry.toolCallId === id,
+  )
+  return JSON.parse(String(message?.content))
+}
+
+/** The id of the child that tool call `id` started. */
+function childIdIn(call: { messages: Array<ModelMessage> }, id: string) {
+  const { subagentRunId } = toolResultIn(call, id)
+  if (typeof subagentRunId !== 'string') throw new Error('no child id')
+  return subagentRunId
+}
+
+/** Lead replies: start `writer` in the background, then answer the wake. */
+function backgroundLead(woke: { open: () => void }) {
+  return [
+    () => callWriter({ prompt: 'Look around', background: true }, 'call-1'),
+    () => text('Started.'),
+    () => {
+      woke.open()
+      return text('Got it.')
+    },
+  ]
+}
+
+const WAKE = 'Background agent writer finished: [writer finished] Found it'
+
+describe('subagent children of a harness session', () => {
+  it('indexes a child the model starts under the session thread', async () => {
+    const lead = mockAdapter([
+      () => callWriter({ prompt: 'Take notes' }, 'call-1'),
+      () => text('Done.'),
+    ])
+    const child = mockAdapter(() => text('Note 1'))
+    const { host, session } = await openLead(lead.adapter, child.adapter)
+
+    await session.prompt('Notes, please')
+
+    const threadId = `subagent:${childIdIn(lead.calls[1], 'call-1')}`
+    expect(await host.sessions.get(threadId)).toEqual({
+      threadId,
+      parentThreadId: 't',
+      parentToolCallId: 'call-1',
+      createdAt: expect.any(Number),
+      updatedAt: expect.any(Number),
+    })
+    const children = await host.sessions.list({ parentThreadId: 't' })
+    expect(children.entries.map((entry) => entry.threadId)).toEqual([threadId])
+    await host.close()
+  })
+
+  it('continues a child by sessionId from its stored messages', async () => {
+    const lead = mockAdapter([
+      () => callWriter({ prompt: 'Take notes' }, 'call-1'),
+      () => text('First done.'),
+      (options) =>
+        callWriter(
+          { sessionId: childIdIn(options, 'call-1'), prompt: 'More' },
+          'call-2',
+        ),
+      () => text('Second done.'),
+    ])
+    const child = mockAdapter([() => text('Note 1'), () => text('Note 2')])
+    const { host, session } = await openLead(lead.adapter, child.adapter)
+
+    await session.prompt('Notes, please')
+    await session.prompt('Add more')
+
+    expect(childIdIn(lead.calls[3], 'call-2')).toBe(
+      childIdIn(lead.calls[3], 'call-1'),
+    )
+    expect(messageTexts(child.calls[1])).toEqual([
+      'Take notes',
+      'Note 1',
+      'More',
+    ])
+    await host.close()
+  })
+
+  it('starts a background child and wakes the session when it ends', async () => {
+    const finish = gate()
+    const woke = gate()
+    const lead = mockAdapter(backgroundLead(woke))
+    const child = mockAdapter(after(finish.opened, 'Found it'))
+    const { host, session } = await openLead(lead.adapter, child.adapter)
+
+    await session.prompt('Look around for me')
+
+    expect(toolResultIn(lead.calls[1], 'call-1')).toEqual({
+      subagentRunId: expect.any(String),
+      result: { status: 'started' },
+    })
+    finish.open()
+    await woke.opened
+
+    expect(messageTexts(child.calls[0]).at(-1)).toBe('Look around')
+    expect(messageTexts(lead.calls[2]).at(-1)).toBe(WAKE)
+    const threadId = `subagent:${childIdIn(lead.calls[1], 'call-1')}`
+    expect(await host.sessions.get(threadId)).toEqual({
+      threadId,
+      parentThreadId: 't',
+      parentToolCallId: 'call-1',
+      createdAt: expect.any(Number),
+      updatedAt: expect.any(Number),
+    })
+    await host.close()
+  })
+
+  it('runs and wakes children without a sessions store', async () => {
+    const { messages, runs, metadata } = memoryPersistence().stores
+    const woke = gate()
+    const lead = mockAdapter(backgroundLead(woke))
+    const child = mockAdapter(() => text('Found it'))
+    const { host, session } = await openLead(lead.adapter, child.adapter, {
+      stores: { messages, runs, metadata },
+    })
+
+    await session.prompt('Look around for me')
+    await woke.opened
+
+    expect(messageTexts(lead.calls[2]).at(-1)).toBe(WAKE)
+    await host.close()
+  })
+})

From 6767029fb66f0cbe3248ccfda2300cb09a26eb55 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 12:28:46 +0200
Subject: [PATCH 240/286] feat: take a model's reasoning data from the adapter
 config

A catalog model whose id is not in the adapter's own table got no
reasoning at all, because each adapter looked up its generated table by
model id. About 500 catalog models lost their thinking this way.

Each first-party text adapter now takes `reasoning?: ModelReasoning` in
its config. When it is set, it wins over the table for the request
fields and for the levels `chat({ reasoning })` takes. `false` sends no
reasoning field. When it is not set, nothing changes.

- Anthropic (anthropicText, createAnthropicChat, anthropicVertexText)
- OpenAI (openaiText, createOpenaiChat) and azureOpenaiText
- Gemini (geminiText, createGeminiChat), AI Studio and Vertex mode
- Bedrock createBedrockConverse
- Mistral (mistralText, createMistralText)
- Cloudflare (cloudflareText, createCloudflareText)

The factories take any model id string. A config with `reasoning` types
`chat({ reasoning })` with every level (ConfigReasoning in @tanstack/ai);
the adapter moves a level the model does not have to the nearest one.

@tanstack/ai-models adds `modelReasoning(record)`, the one rule that
turns a record into the config value.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-anthropic/src/adapters/text.ts    | 78 +++++++++++------
 packages/ai-anthropic/src/index.ts            |  2 +
 packages/ai-anthropic/src/vertex/auth.ts      |  5 +-
 packages/ai-anthropic/src/vertex/index.ts     | 14 +--
 .../tests/chat-per-model-type-safety.test.ts  | 47 +++++++++-
 .../tests/input-modalities.test.ts            |  3 +-
 .../tests/reasoning-request.test.ts           | 79 ++++++++++++++++-
 .../ai-bedrock/src/adapters/converse-text.ts  | 43 ++++++++--
 packages/ai-bedrock/src/index.ts              |  1 +
 .../tests/reasoning-request.test.ts           | 85 ++++++++++++++++++-
 packages/ai-cloudflare/src/adapters/text.ts   | 41 +++++++--
 packages/ai-cloudflare/src/index.ts           |  1 +
 packages/ai-cloudflare/src/utils/config.ts    | 15 +++-
 .../tests/reasoning-request.test.ts           | 60 ++++++++++++-
 packages/ai-gemini/src/adapters/text.ts       | 80 ++++++++++++-----
 packages/ai-gemini/src/index.ts               |  2 +
 .../tests/chat-per-model-type-safety.test.ts  | 48 ++++++++---
 .../ai-gemini/tests/input-modalities.test.ts  |  3 +-
 .../ai-gemini/tests/reasoning-request.test.ts | 68 ++++++++++++++-
 packages/ai-mistral/src/adapters/text.ts      | 63 +++++++++++---
 packages/ai-mistral/src/index.ts              |  2 +
 .../ai-mistral/src/input-modalities.test.ts   |  3 +-
 .../tests/reasoning-request.test.ts           | 67 ++++++++++++++-
 packages/ai-models/src/index.ts               |  7 +-
 packages/ai-models/src/reasoning.ts           | 16 +++-
 packages/ai-models/src/types.ts               |  7 ++
 packages/ai-models/tests/catalog.test.ts      | 31 +++++++
 packages/ai-openai/src/adapters/azure-text.ts | 43 ++++++++--
 packages/ai-openai/src/adapters/text.ts       | 64 +++++++++++---
 packages/ai-openai/src/index.ts               |  2 +
 .../tests/chat-per-model-type-safety.test.ts  | 59 ++++++++++++-
 .../ai-openai/tests/input-modalities.test.ts  |  3 +-
 .../ai-openai/tests/reasoning-request.test.ts | 73 ++++++++++++++--
 packages/ai/src/index.ts                      |  1 +
 packages/ai/src/reasoning.ts                  | 16 ++++
 35 files changed, 981 insertions(+), 151 deletions(-)

diff --git a/packages/ai-anthropic/src/adapters/text.ts b/packages/ai-anthropic/src/adapters/text.ts
index 8e12fa87c4..9e9273ee2b 100644
--- a/packages/ai-anthropic/src/adapters/text.ts
+++ b/packages/ai-anthropic/src/adapters/text.ts
@@ -77,12 +77,15 @@ import type Anthropic_SDK from '@anthropic-ai/sdk'
 import type { AnthropicBeta } from '@anthropic-ai/sdk/resources/beta/beta'
 import type {
   AnyTool,
+  ConfigReasoning,
   ContentPart,
   MidConversationChannels,
   Modality,
   ModelMessage,
+  ModelReasoning,
   AdapterYieldChunk,
   NormalizedSystemPrompt,
+  ReasoningCapability,
   TextOptions,
   ToolCall,
 } from '@tanstack/ai'
@@ -311,6 +314,13 @@ export interface AnthropicTextConfig extends AnthropicClientConfig {
   allowEmptySignature?: boolean
   /** Identify a gateway separately from the direct Anthropic API. */
   provider?: string
+  /**
+   * The model's reasoning data, for example `modelReasoning(record)` from a
+   * `@tanstack/ai-models` record. It wins over the adapter's own table, for
+   * the thinking fields and for the levels `chat({ reasoning })` takes.
+   * `false`: the model does not reason, so no thinking field goes out.
+   */
+  reasoning?: ModelReasoning
   /**
    * The mid-conversation channels (the
    * `mid-conversation-tool-changes-2026-07-01` beta and mid-conversation
@@ -333,6 +343,8 @@ export type AnthropicTextAdapterConfig =
       oauth?: boolean
       allowEmptySignature?: boolean
       provider?: string
+      /** See {@link AnthropicTextConfig.reasoning}. */
+      reasoning?: ModelReasoning
     }
 
 /**
@@ -368,6 +380,12 @@ type ResolveReasoning<TModel extends string> =
     ? AnthropicModelReasoningByName[TModel]
     : never
 
+/**
+ * A model id: a known Anthropic model, or any other id, for example a
+ * gateway or catalog id such as `anthropic/claude-sonnet-4.6`.
+ */
+export type AnthropicModelId = (typeof ANTHROPIC_MODELS)[number] | (string & {})
+
 type ResolveToolCapabilities<TModel extends string> =
   TModel extends keyof AnthropicChatModelToolCapabilitiesByName
     ? NonNullable<AnthropicChatModelToolCapabilitiesByName[TModel]>
@@ -402,12 +420,13 @@ function asSdkAnthropicMessagesClient(
  * Import only what you need for smaller bundle sizes.
  */
 export class AnthropicTextAdapter<
-  TModel extends (typeof ANTHROPIC_MODELS)[number],
+  TModel extends AnthropicModelId,
   TProviderOptions extends Record<string, any> = ResolveProviderOptions<TModel>,
   TInputModalities extends ReadonlyArray<Modality> =
     ResolveInputModalities<TModel>,
   TToolCapabilities extends ReadonlyArray<string> =
     ResolveToolCapabilities<TModel>,
+  TReasoning extends ReasoningCapability = ResolveReasoning<TModel>,
 > extends BaseTextAdapter<
   TModel,
   TProviderOptions,
@@ -419,7 +438,7 @@ export class AnthropicTextAdapter<
   // TSystemPromptMetadata — narrows `systemPrompts[i].metadata` at the
   // chat() call site so users get `cache_control` autocomplete.
   AnthropicSystemPromptMetadata,
-  ResolveReasoning<TModel>
+  TReasoning
 > {
   override readonly kind = 'text' as const
   readonly name = 'anthropic' as const
@@ -435,6 +454,8 @@ export class AnthropicTextAdapter<
     | undefined = undefined
 
   private readonly client: SdkAnthropicMessagesClient
+  /** `config.reasoning`, which wins over `ANTHROPIC_MODEL_REASONING`. */
+  private readonly modelReasoning: ModelReasoning | undefined
   private readonly oauth: boolean
   private readonly allowEmptySignature: boolean
   private readonly tokenAuthentication: boolean
@@ -446,6 +467,8 @@ export class AnthropicTextAdapter<
   constructor(config: AnthropicTextAdapterConfig, model: TModel) {
     super({}, model)
     this.provider = config.provider ?? this.name
+    this.modelReasoning =
+      config.reasoning ?? ANTHROPIC_MODEL_REASONING[this.model]
     const credentials =
       'client' in config
         ? undefined
@@ -859,11 +882,7 @@ export class AnthropicTextAdapter<
 
     // `chat({ reasoning })`, as this model's thinking fields.
     const { output_config: reasoningOutputConfig, ...thinkingFields } =
-      anthropicThinking(
-        this.model,
-        options.reasoning,
-        ANTHROPIC_MODEL_REASONING[this.model],
-      )
+      anthropicThinking(this.model, options.reasoning, this.modelReasoning)
     const thinkingBudget =
       thinkingFields.thinking?.type === 'enabled'
         ? thinkingFields.thinking.budget_tokens
@@ -2130,21 +2149,36 @@ export class AnthropicTextAdapter<
   }
 }
 
+/**
+ * The adapter type for a model and a config. A config with `reasoning` sets
+ * the levels `chat({ reasoning })` takes; see {@link ConfigReasoning}.
+ */
+export type AnthropicTextAdapterFor<
+  TModel extends AnthropicModelId,
+  TConfig = AnthropicTextConfig,
+> = AnthropicTextAdapter<
+  TModel,
+  ResolveProviderOptions<TModel>,
+  ResolveInputModalities<TModel>,
+  ResolveToolCapabilities<TModel>,
+  ConfigReasoning<TConfig, ResolveReasoning<TModel>>
+>
+
 /**
  * Creates an Anthropic chat adapter with explicit API key.
  * Type resolution happens here at the call site.
  */
 export function createAnthropicChat<
-  TModel extends (typeof ANTHROPIC_MODELS)[number],
+  TModel extends AnthropicModelId,
+  TConfig extends Omit<AnthropicTextConfig, 'apiKey'> = Omit<
+    AnthropicTextConfig,
+    'apiKey'
+  >,
 >(
   model: TModel,
   apiKey: string,
-  config?: Omit<AnthropicTextConfig, 'apiKey'>,
-): AnthropicTextAdapter<
-  TModel,
-  ResolveProviderOptions<TModel>,
-  ResolveInputModalities<TModel>
-> {
+  config?: TConfig,
+): AnthropicTextAdapterFor<TModel, TConfig> {
   return new AnthropicTextAdapter({ apiKey, ...config }, model)
 }
 
@@ -2152,9 +2186,7 @@ export function createAnthropicChat<
  * Creates an Anthropic chat adapter with an injected Messages client.
  * Type resolution happens here at the call site.
  */
-export function createAnthropicChatWithClient<
-  TModel extends (typeof ANTHROPIC_MODELS)[number],
->(
+export function createAnthropicChatWithClient<TModel extends AnthropicModelId>(
   model: TModel,
   client: AnthropicMessagesClient,
 ): AnthropicTextAdapter<
@@ -2169,13 +2201,9 @@ export function createAnthropicChatWithClient<
  * Creates an Anthropic text adapter with automatic API key detection.
  * Type resolution happens here at the call site.
  */
-export function anthropicText<TModel extends (typeof ANTHROPIC_MODELS)[number]>(
-  model: TModel,
-  config?: AnthropicTextConfig,
-): AnthropicTextAdapter<
-  TModel,
-  ResolveProviderOptions<TModel>,
-  ResolveInputModalities<TModel>
-> {
+export function anthropicText<
+  TModel extends AnthropicModelId,
+  TConfig extends AnthropicTextConfig = AnthropicTextConfig,
+>(model: TModel, config?: TConfig): AnthropicTextAdapterFor<TModel, TConfig> {
   return new AnthropicTextAdapter(config ?? {}, model)
 }
diff --git a/packages/ai-anthropic/src/index.ts b/packages/ai-anthropic/src/index.ts
index 0c489cb14b..8248295238 100644
--- a/packages/ai-anthropic/src/index.ts
+++ b/packages/ai-anthropic/src/index.ts
@@ -8,7 +8,9 @@ export {
   anthropicText,
   createAnthropicChat,
   createAnthropicChatWithClient,
+  type AnthropicModelId,
   type AnthropicTextAdapterConfig,
+  type AnthropicTextAdapterFor,
   type AnthropicTextConfig,
   type AnthropicTextProviderOptions,
 } from './adapters/text'
diff --git a/packages/ai-anthropic/src/vertex/auth.ts b/packages/ai-anthropic/src/vertex/auth.ts
index a7829c4a7a..b3467b7524 100644
--- a/packages/ai-anthropic/src/vertex/auth.ts
+++ b/packages/ai-anthropic/src/vertex/auth.ts
@@ -1,4 +1,5 @@
 import type { AnthropicVertex } from '@anthropic-ai/vertex-sdk'
+import type { ModelReasoning } from '@tanstack/ai'
 
 export class AnthropicVertexAuthError extends Error {
   constructor(message: string) {
@@ -21,6 +22,8 @@ export type AnthropicVertexConfig = Omit<
 > & {
   project?: string
   location?: string
+  /** See `AnthropicTextConfig.reasoning`. It does not go to the Vertex SDK. */
+  reasoning?: ModelReasoning
 }
 
 function nonEmpty(value: string | undefined): string | undefined {
@@ -40,7 +43,7 @@ function readEnv(name: string): string | undefined {
 export function resolveAnthropicVertexOptions(
   config: AnthropicVertexConfig = {},
 ): VertexSdkOptions {
-  const { project, location, ...rest } = config
+  const { project, location, reasoning: _reasoning, ...rest } = config
   const projectId =
     nonEmpty(project) ??
     readEnv('GOOGLE_CLOUD_PROJECT') ??
diff --git a/packages/ai-anthropic/src/vertex/index.ts b/packages/ai-anthropic/src/vertex/index.ts
index f55cc4f098..5d7718fe16 100644
--- a/packages/ai-anthropic/src/vertex/index.ts
+++ b/packages/ai-anthropic/src/vertex/index.ts
@@ -1,6 +1,7 @@
 import { AnthropicVertex } from '@anthropic-ai/vertex-sdk'
 import { AnthropicTextAdapter } from '../adapters/text'
 import { resolveAnthropicVertexOptions } from './auth'
+import type { AnthropicTextAdapterFor } from '../adapters/text'
 import type { AnthropicVertexChatModel } from '../model-meta'
 import type { AnthropicVertexConfig } from './auth'
 
@@ -19,10 +20,13 @@ export {
  *
  * Install `@anthropic-ai/vertex-sdk` next to `@tanstack/ai-anthropic`.
  */
-export function anthropicVertexText<TModel extends AnthropicVertexChatModel>(
-  model: TModel,
-  config: AnthropicVertexConfig = {},
-): AnthropicTextAdapter<TModel> {
+export function anthropicVertexText<
+  TModel extends AnthropicVertexChatModel | (string & {}),
+  TConfig extends AnthropicVertexConfig = AnthropicVertexConfig,
+>(model: TModel, config?: TConfig): AnthropicTextAdapterFor<TModel, TConfig> {
   const client = new AnthropicVertex(resolveAnthropicVertexOptions(config))
-  return new AnthropicTextAdapter({ client, provider: 'google-vertex' }, model)
+  return new AnthropicTextAdapter(
+    { client, provider: 'google-vertex', reasoning: config?.reasoning },
+    model,
+  )
 }
diff --git a/packages/ai-anthropic/tests/chat-per-model-type-safety.test.ts b/packages/ai-anthropic/tests/chat-per-model-type-safety.test.ts
index 236485bc19..2d1e4beaf3 100644
--- a/packages/ai-anthropic/tests/chat-per-model-type-safety.test.ts
+++ b/packages/ai-anthropic/tests/chat-per-model-type-safety.test.ts
@@ -11,6 +11,7 @@
 import { beforeAll, describe, expectTypeOf, it } from 'vitest'
 import { chat } from '@tanstack/ai'
 import { anthropicText } from '../src'
+import type { ModelReasoning } from '@tanstack/ai'
 import type { AnthropicChatModelProviderOptionsByName } from '../src'
 
 // Set a dummy API key so adapter construction does not throw at runtime.
@@ -177,9 +178,49 @@ describe('Anthropic per-model chat modelOptions gating', () => {
   })
 
   describe('Model name type safety', () => {
-    it('rejects unknown model names at the factory', () => {
-      // @ts-expect-error - 'claude-fake-9000' is not a valid Anthropic chat model
-      anthropicText('claude-fake-9000')
+    it('accepts any model id, such as a gateway or catalog id', () => {
+      anthropicText('anthropic/claude-sonnet-4.6')
+      const id: string = 'MiniMax-M2.5'
+      anthropicText(id)
+    })
+  })
+})
+
+describe('Anthropic chat reasoning from the config', () => {
+  const messages = [{ role: 'user' as const, content: 'hi' }]
+
+  it('a config with reasoning takes every level, for any model id', () => {
+    chat({
+      adapter: anthropicText('anthropic/claude-sonnet-4.6', {
+        reasoning: { budget: true },
+      }),
+      messages,
+      reasoning: { level: 'max', budgetTokens: 4000 },
+    })
+    // The table gives claude-opus-4-5 only low, medium, and high.
+    const reasoning: ModelReasoning = { map: { xhigh: 'xhigh' }, budget: false }
+    chat({
+      adapter: anthropicText('claude-opus-4-5', { reasoning }),
+      messages,
+      reasoning: 'xhigh',
+    })
+  })
+
+  it('an id with no table and no config takes no reasoning', () => {
+    chat({
+      adapter: anthropicText('anthropic/claude-sonnet-4.6'),
+      messages,
+      // @ts-expect-error - no reasoning data for this id
+      reasoning: 'high',
+    })
+  })
+
+  it('reasoning: false takes no reasoning, also on a known model', () => {
+    chat({
+      adapter: anthropicText('claude-opus-5-5', { reasoning: false }),
+      messages,
+      // @ts-expect-error - the config says the model does not reason
+      reasoning: 'high',
     })
   })
 })
diff --git a/packages/ai-anthropic/tests/input-modalities.test.ts b/packages/ai-anthropic/tests/input-modalities.test.ts
index b6913b323f..4bad67bdb0 100644
--- a/packages/ai-anthropic/tests/input-modalities.test.ts
+++ b/packages/ai-anthropic/tests/input-modalities.test.ts
@@ -17,8 +17,7 @@ describe('Anthropic text adapter inputModalities', () => {
   })
 
   it('is undefined for a model the metadata does not list', () => {
-    // A JS caller, or a model id newer than this package, reaches the adapter.
-    // @ts-expect-error - 'claude-unknown-9000' is not a declared model
+    // A gateway or catalog id, or a model id newer than this package.
     const adapter = new AnthropicTextAdapter(config, 'claude-unknown-9000')
 
     expect(adapter.inputModalities).toBeUndefined()
diff --git a/packages/ai-anthropic/tests/reasoning-request.test.ts b/packages/ai-anthropic/tests/reasoning-request.test.ts
index 8198b8f054..622a29c933 100644
--- a/packages/ai-anthropic/tests/reasoning-request.test.ts
+++ b/packages/ai-anthropic/tests/reasoning-request.test.ts
@@ -2,8 +2,8 @@ import { describe, expect, it, vi } from 'vitest'
 import { chat } from '@tanstack/ai'
 import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
 import { z } from 'zod'
-import { createAnthropicChatWithClient } from '../src'
-import type { ReasoningRequest, Tool } from '@tanstack/ai'
+import { AnthropicTextAdapter, createAnthropicChatWithClient } from '../src'
+import type { ModelReasoning, ReasoningRequest, Tool } from '@tanstack/ai'
 import type { AnthropicChatModel } from '../src/model-meta'
 
 const logger = resolveDebugOption(false)
@@ -161,3 +161,78 @@ describe('Anthropic chat({ reasoning }) request shape', () => {
     })
   })
 })
+
+describe('Anthropic reasoning from the config', () => {
+  /** Run one call with `reasoning` in the config. Returns the request body. */
+  async function sendWith(
+    model: string,
+    reasoning: ModelReasoning,
+    request: ReasoningRequest,
+  ) {
+    const create = vi.fn().mockResolvedValue(textStream('ok'))
+    const adapter = new AnthropicTextAdapter(
+      { client: { beta: { messages: { create } } }, reasoning },
+      model,
+    )
+    for await (const _chunk of adapter.chatStream({
+      logger,
+      model,
+      messages: [{ role: 'user', content: 'hi' }],
+      reasoning: request,
+    })) {
+      // Drain the stream.
+    }
+    const [body] = create.mock.calls[0] ?? []
+    return body as Record<string, any>
+  }
+
+  const effortMap = {
+    off: null,
+    minimal: null,
+    low: 'low',
+    medium: 'medium',
+    high: 'high',
+    xhigh: 'xhigh',
+    max: 'max',
+  }
+
+  it('sends budget thinking for a model id that the table does not have', async () => {
+    // Like the catalog record of a gateway id with a token budget.
+    const body = await sendWith(
+      'anthropic/claude-sonnet-4.6',
+      { budget: true },
+      on('medium'),
+    )
+    expect(body.thinking).toEqual({ type: 'enabled', budget_tokens: 8192 })
+  })
+
+  it('sends adaptive thinking with the effort from the config map', async () => {
+    const body = await sendWith(
+      'anthropic.claude-fable-5',
+      { map: effortMap, budget: false },
+      on('xhigh'),
+    )
+    expect(body.thinking).toEqual({ type: 'adaptive', display: 'summarized' })
+    expect(body.output_config).toEqual({ effort: 'xhigh' })
+  })
+
+  it('sends no thinking field for reasoning: false, also on a known model', async () => {
+    const body = await sendWith('claude-opus-5-5', false, on('high'))
+    expect(body).not.toHaveProperty('thinking')
+    expect(body).not.toHaveProperty('effort')
+    expect(body).not.toHaveProperty('output_config')
+  })
+
+  it('clamps the level with the config, not with the table', async () => {
+    // The table gives claude-opus-4-5 low, medium, and high with a budget.
+    // This config has only high and max, and no budget.
+    const config: ModelReasoning = {
+      map: { minimal: null, low: null, medium: null, high: 'high', max: 'max' },
+      budget: false,
+    }
+    const max = await sendWith('claude-opus-4-5', config, on('max'))
+    expect(max.output_config).toEqual({ effort: 'max' })
+    const low = await sendWith('claude-opus-4-5', config, on('low'))
+    expect(low.output_config).toEqual({ effort: 'high' })
+  })
+})
diff --git a/packages/ai-bedrock/src/adapters/converse-text.ts b/packages/ai-bedrock/src/adapters/converse-text.ts
index 7f755b8083..493bc1191b 100644
--- a/packages/ai-bedrock/src/adapters/converse-text.ts
+++ b/packages/ai-bedrock/src/adapters/converse-text.ts
@@ -31,9 +31,12 @@ import type {
   ConverseStreamOutput,
 } from '@aws-sdk/client-bedrock-runtime'
 import type {
+  ConfigReasoning,
   JSONSchema,
   Modality,
+  ModelReasoning,
   AdapterYieldChunk,
+  ReasoningCapability,
   TextOptions,
   TokenUsage,
   Tool,
@@ -55,7 +58,21 @@ import type {
 } from '../model-meta'
 
 /** Config for the Converse adapter — same client config as the chat adapter. */
-export interface BedrockConverseConfig extends BedrockClientConfig {}
+export interface BedrockConverseConfig extends BedrockClientConfig {
+  /**
+   * The model's reasoning data, for example `modelReasoning(record)` from a
+   * `@tanstack/ai-models` record. It wins over the adapter's own table, for
+   * the Claude thinking fields in `additionalModelRequestFields` and for the
+   * levels `chat({ reasoning })` takes. `false`: no thinking fields go out.
+   */
+  reasoning?: ModelReasoning
+}
+
+/**
+ * A model id: a known Converse model, or any other id, for example a
+ * catalog id or an inference profile id that this package does not list.
+ */
+export type BedrockConverseModelId = BedrockConverseModels | (string & {})
 
 /**
  * Bedrock Converse text adapter. Wires the Converse translation modules (message
@@ -78,7 +95,7 @@ type ResolveReasoning<TModel extends string> =
     : never
 
 export class BedrockConverseTextAdapter<
-  TModel extends BedrockConverseModels,
+  TModel extends BedrockConverseModelId,
   // Constraint mirrors the chat adapter (text.ts): the base parameterises
   // `TProviderOptions extends Record<string, any>`, and our default
   // `ResolveConverseProviderOptions<TModel>` resolves to an interface lacking an
@@ -89,6 +106,7 @@ export class BedrockConverseTextAdapter<
     ResolveConverseProviderOptions<TModel>,
   TInputModalities extends ReadonlyArray<Modality> =
     ResolveInputModalities<TModel>,
+  TReasoning extends ReasoningCapability = ResolveReasoning<TModel>,
 > extends BaseTextAdapter<
   TModel,
   TProviderOptions,
@@ -102,7 +120,7 @@ export class BedrockConverseTextAdapter<
   // TSystemPromptMetadata — narrows `systemPrompts[i].metadata` at the chat()
   // call site so users get `cachePoint` autocomplete.
   BedrockSystemPromptMetadata,
-  ResolveReasoning<TModel>
+  TReasoning
 > {
   override readonly kind = 'text' as const
   override readonly name = 'bedrock-converse' as const
@@ -807,7 +825,7 @@ export class BedrockConverseTextAdapter<
     const { additionalModelRequestFields, minMaxTokens } = converseThinking(
       this.model,
       options.reasoning,
-      BEDROCK_MODEL_REASONING[this.model],
+      this.clientConfig.reasoning ?? BEDROCK_MODEL_REASONING[this.model],
     )
     const requestedMaxTokens = modelOptions?.max_completion_tokens
     const maxTokens =
@@ -894,10 +912,21 @@ function extractStructuredToolInput(
 }
 
 /** Converse adapter with an explicit API key (low-level; mirrors createBedrockChat). */
-export function createBedrockConverse<TModel extends BedrockConverseModels>(
+export function createBedrockConverse<
+  TModel extends BedrockConverseModelId,
+  TConfig extends Omit<BedrockConverseConfig, 'apiKey'> = Omit<
+    BedrockConverseConfig,
+    'apiKey'
+  >,
+>(
   model: TModel,
   apiKey: string,
-  config?: Omit<BedrockConverseConfig, 'apiKey'>,
-): BedrockConverseTextAdapter<TModel> {
+  config?: TConfig,
+): BedrockConverseTextAdapter<
+  TModel,
+  ResolveConverseProviderOptions<TModel>,
+  ResolveInputModalities<TModel>,
+  ConfigReasoning<TConfig, ResolveReasoning<TModel>>
+> {
   return new BedrockConverseTextAdapter({ ...config, apiKey }, model)
 }
diff --git a/packages/ai-bedrock/src/index.ts b/packages/ai-bedrock/src/index.ts
index bd6a9aedbe..f15d402cbb 100644
--- a/packages/ai-bedrock/src/index.ts
+++ b/packages/ai-bedrock/src/index.ts
@@ -181,6 +181,7 @@ export {
   BedrockConverseTextAdapter,
   createBedrockConverse,
   type BedrockConverseConfig,
+  type BedrockConverseModelId,
 } from './adapters/converse-text'
 export {
   BedrockEmbeddingAdapter,
diff --git a/packages/ai-bedrock/tests/reasoning-request.test.ts b/packages/ai-bedrock/tests/reasoning-request.test.ts
index a9431336dd..5ef8e4b807 100644
--- a/packages/ai-bedrock/tests/reasoning-request.test.ts
+++ b/packages/ai-bedrock/tests/reasoning-request.test.ts
@@ -1,10 +1,18 @@
 import { describe, expect, it } from 'vitest'
+import { chat } from '@tanstack/ai'
 import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
 import { BedrockTextAdapter } from '../src/adapters/text'
 import { BedrockResponsesTextAdapter } from '../src/adapters/responses-text'
-import { BedrockConverseTextAdapter } from '../src/adapters/converse-text'
-import type { ReasoningRequest, TextOptions } from '@tanstack/ai'
-import type { BedrockConverseModels } from '../src/model-meta'
+import {
+  BedrockConverseTextAdapter,
+  createBedrockConverse,
+} from '../src/adapters/converse-text'
+import type {
+  ModelReasoning,
+  ReasoningRequest,
+  TextOptions,
+} from '@tanstack/ai'
+import type { BedrockConverseModelId } from '../src/adapters/converse-text'
 import type { BedrockConverseProviderOptions } from '../src/converse/provider-options'
 
 const logger = resolveDebugOption(false)
@@ -35,7 +43,7 @@ class ResponsesProbe extends BedrockResponsesTextAdapter<'openai.gpt-oss-120b-1:
 }
 
 class ConverseProbe<
-  TModel extends BedrockConverseModels,
+  TModel extends BedrockConverseModelId,
 > extends BedrockConverseTextAdapter<TModel, BedrockConverseProviderOptions> {
   request(
     reasoning: ReasoningRequest | undefined,
@@ -107,3 +115,72 @@ describe('Bedrock chat({ reasoning }) request shape', () => {
     )
   })
 })
+
+describe('Bedrock Converse reasoning from the config', () => {
+  const effortMap: ModelReasoning = {
+    map: { off: null, minimal: null, xhigh: 'xhigh', max: 'max' },
+    budget: false,
+  }
+  const probe = (model: string, reasoning: ModelReasoning) =>
+    new ConverseProbe({ ...config, reasoning }, model)
+
+  it('sends adaptive thinking for a Claude id that the table does not have', () => {
+    expect(
+      probe('anthropic.claude-fable-5', effortMap).request(on('xhigh'))
+        .additionalModelRequestFields,
+    ).toEqual({
+      thinking: { type: 'adaptive' },
+      output_config: { effort: 'xhigh' },
+    })
+  })
+
+  it('sends budget thinking for a budget record', () => {
+    const input = probe('global.anthropic.claude-sonnet-4-6', {
+      budget: true,
+    }).request(on('medium'))
+    expect(input.additionalModelRequestFields).toEqual({
+      thinking: { type: 'enabled', budget_tokens: 8192 },
+      anthropic_beta: ['interleaved-thinking-2025-05-14'],
+    })
+  })
+
+  it('sends no thinking for reasoning: false, also on a known model', () => {
+    expect(
+      probe('us.anthropic.claude-haiku-4-5-20251001-v1:0', false).request(
+        on('high'),
+      ),
+    ).not.toHaveProperty('additionalModelRequestFields')
+  })
+
+  it('clamps the level with the config, not with the table', () => {
+    // This config has no minimal, so minimal moves up to low.
+    expect(
+      probe('anthropic.claude-fable-5', effortMap).request(on('minimal'))
+        .additionalModelRequestFields,
+    ).toEqual({
+      thinking: { type: 'adaptive' },
+      output_config: { effort: 'low' },
+    })
+  })
+})
+
+describe('Bedrock Converse chat reasoning types', () => {
+  const messages = [{ role: 'user' as const, content: 'hi' }]
+
+  it('takes any model id, and every level with a reasoning config', () => {
+    const id: string = 'anthropic.claude-fable-5'
+    const reasoning: ModelReasoning = { budget: true }
+    // Type-level only: chat() is never iterated, so no request goes out.
+    chat({
+      adapter: createBedrockConverse(id, 'k', { reasoning }),
+      messages,
+      reasoning: { level: 'max', budgetTokens: 4000 },
+    })
+    chat({
+      adapter: createBedrockConverse(id, 'k'),
+      messages,
+      // @ts-expect-error - no reasoning data for this id
+      reasoning: 'high',
+    })
+  })
+})
diff --git a/packages/ai-cloudflare/src/adapters/text.ts b/packages/ai-cloudflare/src/adapters/text.ts
index 4100ed7fc6..ee74b3bf45 100644
--- a/packages/ai-cloudflare/src/adapters/text.ts
+++ b/packages/ai-cloudflare/src/adapters/text.ts
@@ -16,13 +16,17 @@ import type {
 import type {
   CloudflareConfigInput,
   CloudflareTextConfig,
+  CloudflareTextReasoningConfig,
   CloudflareTextRestConfig,
 } from '../utils/config'
 import type { CloudflareTextModel } from '../utils/models'
 import type {
+  ConfigReasoning,
   DefaultMessageMetadataByModality,
   Modality,
   ModelMessage,
+  ModelReasoning,
+  ReasoningCapability,
   TextOptions,
 } from '@tanstack/ai'
 import type { CloudflareModelReasoningByName } from '../model-reasoning'
@@ -65,6 +69,7 @@ function createClient(config: CloudflareTextConfig): OpenAI {
     accountId: _accountId,
     binding: _binding,
     gateway,
+    reasoning: _reasoning,
     ...clientOptions
   } = config
   return new OpenAI({
@@ -90,19 +95,23 @@ function createClient(config: CloudflareTextConfig): OpenAI {
 export class CloudflareTextAdapter<
   TModel extends CloudflareTextModel,
   TProviderOptions extends Record<string, any> = CloudflareTextProviderOptions,
+  TReasoning extends ReasoningCapability = ResolveReasoning<TModel>,
 > extends OpenAIBaseChatCompletionsTextAdapter<
   TModel,
   TProviderOptions,
   ReadonlyArray<Modality>,
   DefaultMessageMetadataByModality,
   ReadonlyArray<string>,
-  ResolveReasoning<TModel>
+  TReasoning
 > {
   override readonly kind = 'text' as const
   override readonly name = 'cloudflare' as const
+  /** `config.reasoning`, which wins over `CLOUDFLARE_MODEL_REASONING`. */
+  private readonly configReasoning: ModelReasoning | undefined
 
   constructor(config: CloudflareTextConfig, model: TModel) {
     super(model, 'cloudflare', createClient(config), config)
+    this.configReasoning = config.reasoning
   }
 
   /**
@@ -113,7 +122,7 @@ export class CloudflareTextAdapter<
     const request = super.mapOptionsToRequest(options)
     const resolved = resolveReasoning(
       options.reasoning,
-      CLOUDFLARE_MODEL_REASONING[options.model],
+      this.configReasoning ?? CLOUDFLARE_MODEL_REASONING[options.model],
     )
     if (resolved) {
       Object.assign(request, {
@@ -170,10 +179,17 @@ export class CloudflareTextAdapter<
  * const adapter = createCloudflareText('@cf/zai-org/glm-5.3-flash', { accountId, apiKey })
  * ```
  */
-export function createCloudflareText<TModel extends CloudflareTextModel>(
+export function createCloudflareText<
+  TModel extends CloudflareTextModel,
+  TConfig extends CloudflareTextConfig = CloudflareTextConfig,
+>(
   model: TModel,
-  config: CloudflareTextConfig,
-): CloudflareTextAdapter<TModel> {
+  config: TConfig,
+): CloudflareTextAdapter<
+  TModel,
+  CloudflareTextProviderOptions,
+  ConfigReasoning<TConfig, ResolveReasoning<TModel>>
+> {
   return new CloudflareTextAdapter(config, model)
 }
 
@@ -181,9 +197,18 @@ export function createCloudflareText<TModel extends CloudflareTextModel>(
  * Creates a Cloudflare text adapter, reading `CLOUDFLARE_ACCOUNT_ID` and
  * `CLOUDFLARE_API_TOKEN` from the environment unless a binding is passed.
  */
-export function cloudflareText<TModel extends CloudflareTextModel>(
+export function cloudflareText<
+  TModel extends CloudflareTextModel,
+  TConfig extends CloudflareConfigInput<CloudflareTextRestConfig> &
+    CloudflareTextReasoningConfig =
+    CloudflareConfigInput<CloudflareTextRestConfig>,
+>(
   model: TModel,
-  config?: CloudflareConfigInput<CloudflareTextRestConfig>,
-): CloudflareTextAdapter<TModel> {
+  config?: TConfig,
+): CloudflareTextAdapter<
+  TModel,
+  CloudflareTextProviderOptions,
+  ConfigReasoning<TConfig, ResolveReasoning<TModel>>
+> {
   return new CloudflareTextAdapter(resolveConfigFromEnv(config), model)
 }
diff --git a/packages/ai-cloudflare/src/index.ts b/packages/ai-cloudflare/src/index.ts
index 396680687d..8bbe07093b 100644
--- a/packages/ai-cloudflare/src/index.ts
+++ b/packages/ai-cloudflare/src/index.ts
@@ -67,6 +67,7 @@ export type {
   CloudflareGatewayOptions,
   CloudflareRestConfig,
   CloudflareTextConfig,
+  CloudflareTextReasoningConfig,
   CloudflareTextRestConfig,
 } from './utils/config'
 
diff --git a/packages/ai-cloudflare/src/utils/config.ts b/packages/ai-cloudflare/src/utils/config.ts
index 48fffb36fe..4ddc8b0808 100644
--- a/packages/ai-cloudflare/src/utils/config.ts
+++ b/packages/ai-cloudflare/src/utils/config.ts
@@ -1,5 +1,6 @@
 import { getApiKeyFromEnv } from '@tanstack/ai-utils'
 import type { Ai, GatewayOptions } from '@cloudflare/workers-types'
+import type { ModelReasoning } from '@tanstack/ai'
 import type { ClientOptions } from 'openai'
 import type { OpenAIBaseTextAdapterOptions } from '@tanstack/openai-base'
 
@@ -48,7 +49,19 @@ export type CloudflareTextConfig = (
   | CloudflareBindingConfig
   | CloudflareTextRestConfig
 ) &
-  OpenAIBaseTextAdapterOptions
+  OpenAIBaseTextAdapterOptions &
+  CloudflareTextReasoningConfig
+
+/** The `reasoning` field of the Cloudflare text configs. */
+export interface CloudflareTextReasoningConfig {
+  /**
+   * The model's reasoning data, for example `modelReasoning(record)` from a
+   * `@tanstack/ai-models` record. It wins over the adapter's own table, for
+   * `reasoning_effort` and for the levels `chat({ reasoning })` takes.
+   * `false`: the model does not reason, so no reasoning field goes out.
+   */
+  reasoning?: ModelReasoning
+}
 
 /**
  * What the env-reading factories accept: a binding, or REST fields with any
diff --git a/packages/ai-cloudflare/tests/reasoning-request.test.ts b/packages/ai-cloudflare/tests/reasoning-request.test.ts
index ed066cc4cd..6219713ad6 100644
--- a/packages/ai-cloudflare/tests/reasoning-request.test.ts
+++ b/packages/ai-cloudflare/tests/reasoning-request.test.ts
@@ -1,7 +1,11 @@
 import { describe, expect, it } from 'vitest'
 import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
-import { CloudflareTextAdapter } from '../src/adapters/text'
-import type { ReasoningRequest } from '@tanstack/ai'
+import { chat } from '@tanstack/ai'
+import {
+  CloudflareTextAdapter,
+  createCloudflareText,
+} from '../src/adapters/text'
+import type { ModelReasoning, ReasoningRequest } from '@tanstack/ai'
 
 const logger = resolveDebugOption(false)
 const model = '@cf/deepseek-ai/deepseek-v4-flash-0731'
@@ -36,3 +40,55 @@ describe('Cloudflare chat({ reasoning }) request shape', () => {
     expect(adapter.request(undefined)).not.toHaveProperty('reasoning_effort')
   })
 })
+
+describe('Cloudflare reasoning from the config', () => {
+  /** The request for any model id, with `reasoning` in the config. */
+  class AnyProbe extends CloudflareTextAdapter<string> {
+    request(reasoning: ReasoningRequest) {
+      return this.mapOptionsToRequest({
+        model: this.model,
+        logger,
+        messages: [{ role: 'user', content: 'hi' }],
+        reasoning,
+      })
+    }
+  }
+  const probe = (id: string, reasoning: ModelReasoning) =>
+    new AnyProbe({ accountId: 'a', apiKey: 'k', reasoning }, id)
+
+  it('sends the effort for a model id that the table does not have', () => {
+    expect(
+      probe('@cf/qwen/qwen3.6-30b-a3b', { budget: false }).request({
+        level: 'high',
+        summary: true,
+      }),
+    ).toMatchObject({ reasoning_effort: 'high' })
+  })
+
+  it('sends nothing for reasoning: false, also on a known model', () => {
+    expect(
+      probe(model, false).request({ level: 'high', summary: true }),
+    ).not.toHaveProperty('reasoning_effort')
+  })
+
+  it('clamps the level with the config, not with the table', () => {
+    // The table gives this model max. This config tops out at high.
+    expect(
+      probe(model, { budget: false }).request({ level: 'max', summary: true }),
+    ).toMatchObject({ reasoning_effort: 'high' })
+  })
+
+  it('takes every level in the types with a reasoning config', () => {
+    const reasoning: ModelReasoning = { budget: false }
+    // Type-level only: chat() is never iterated, so no request goes out.
+    chat({
+      adapter: createCloudflareText('@cf/qwen/qwen3.6-30b-a3b', {
+        accountId: 'a',
+        apiKey: 'k',
+        reasoning,
+      }),
+      messages: [{ role: 'user', content: 'hi' }],
+      reasoning: 'medium',
+    })
+  })
+})
diff --git a/packages/ai-gemini/src/adapters/text.ts b/packages/ai-gemini/src/adapters/text.ts
index 59a5705ec9..d404504435 100644
--- a/packages/ai-gemini/src/adapters/text.ts
+++ b/packages/ai-gemini/src/adapters/text.ts
@@ -50,10 +50,13 @@ import type {
   VideoMetadata,
 } from '@google/genai'
 import type {
+  ConfigReasoning,
   ContentPart,
   Modality,
   ModelMessage,
+  ModelReasoning,
   MessageSource,
+  ReasoningCapability,
   ToolCall,
   AdapterYieldChunk,
   ProviderExecutedToolSource,
@@ -331,7 +334,21 @@ function buildInteractionsInput(
 /**
  * Configuration for Gemini text adapter
  */
-export interface GeminiTextConfig extends GeminiClientConfig {}
+export interface GeminiTextConfig extends GeminiClientConfig {
+  /**
+   * The model's reasoning data, for example `modelReasoning(record)` from a
+   * `@tanstack/ai-models` record. It wins over the adapter's own table, for
+   * `thinkingConfig` and for the levels `chat({ reasoning })` takes.
+   * `false`: the model does not reason, so no thinking config goes out.
+   */
+  reasoning?: ModelReasoning
+}
+
+/**
+ * A model id: a known Gemini model, or any other id, for example a Vertex or
+ * catalog id that this package does not list yet.
+ */
+export type GeminiModelId = (typeof GEMINI_MODELS)[number] | (string & {})
 
 /**
  * Gemini-specific provider options for text/chat
@@ -386,12 +403,13 @@ type ResolveToolCapabilities<TModel extends string> =
  * Import only what you need for smaller bundle sizes.
  */
 export class GeminiTextAdapter<
-  TModel extends (typeof GEMINI_MODELS)[number],
+  TModel extends GeminiModelId,
   TProviderOptions extends Record<string, any> = ResolveProviderOptions<TModel>,
   TInputModalities extends ReadonlyArray<Modality> =
     ResolveInputModalities<TModel>,
   TToolCapabilities extends ReadonlyArray<string> =
     ResolveToolCapabilities<TModel>,
+  TReasoning extends ReasoningCapability = ResolveReasoning<TModel>,
 > extends BaseTextAdapter<
   TModel,
   TProviderOptions,
@@ -400,7 +418,7 @@ export class GeminiTextAdapter<
   TToolCapabilities,
   GeminiToolCallMetadata,
   never,
-  ResolveReasoning<TModel>
+  TReasoning
 > {
   override readonly kind = 'text' as const
   readonly name = 'gemini' as const
@@ -411,9 +429,13 @@ export class GeminiTextAdapter<
   override readonly inputModalities = GEMINI_MODEL_INPUT_MODALITIES[this.model]
 
   private readonly client: GoogleGenAI
+  /** `config.reasoning`, which wins over `GEMINI_MODEL_REASONING`. */
+  private readonly configReasoning: ModelReasoning | undefined
 
   constructor(config: GeminiTextConfig, model: TModel) {
     super({}, model)
+    const { reasoning, ...clientConfig } = config
+    this.configReasoning = reasoning
     this.provider =
       config.vertexai === true || config.enterprise === true
         ? 'google-vertex'
@@ -422,7 +444,7 @@ export class GeminiTextAdapter<
       this.provider === 'google-vertex'
         ? 'google-vertex'
         : 'google-generative-ai'
-    this.client = createGeminiClient(config)
+    this.client = createGeminiClient(clientConfig)
   }
 
   async *chatStream(
@@ -1522,7 +1544,7 @@ export class GeminiTextAdapter<
     const mappedThinkingConfig = geminiThinkingConfig(
       options.model,
       options.reasoning,
-      GEMINI_MODEL_REASONING[options.model],
+      this.configReasoning ?? GEMINI_MODEL_REASONING[options.model],
     )
 
     const normalizedPrompts = normalizeSystemPrompts(options.systemPrompts)
@@ -1614,20 +1636,36 @@ function structuredStreamError(
   }
 }
 
+/**
+ * The adapter type for a model and a config. A config with `reasoning` sets
+ * the levels `chat({ reasoning })` takes; see {@link ConfigReasoning}.
+ */
+export type GeminiTextAdapterFor<
+  TModel extends GeminiModelId,
+  TConfig = GeminiTextConfig,
+> = GeminiTextAdapter<
+  TModel,
+  ResolveProviderOptions<TModel>,
+  ResolveInputModalities<TModel>,
+  ResolveToolCapabilities<TModel>,
+  ConfigReasoning<TConfig, ResolveReasoning<TModel>>
+>
+
 /**
  * Creates a Gemini text adapter with explicit API key.
  * Type resolution happens here at the call site.
  */
-export function createGeminiChat<TModel extends (typeof GEMINI_MODELS)[number]>(
+export function createGeminiChat<
+  TModel extends GeminiModelId,
+  TConfig extends Omit<GeminiTextConfig, 'apiKey'> = Omit<
+    GeminiTextConfig,
+    'apiKey'
+  >,
+>(
   model: TModel,
   apiKey: string,
-  config?: Omit<GeminiTextConfig, 'apiKey'>,
-): GeminiTextAdapter<
-  TModel,
-  ResolveProviderOptions<TModel>,
-  ResolveInputModalities<TModel>,
-  ResolveToolCapabilities<TModel>
-> {
+  config?: TConfig,
+): GeminiTextAdapterFor<TModel, TConfig> {
   return new GeminiTextAdapter({ apiKey, ...config }, model)
 }
 
@@ -1635,15 +1673,13 @@ export function createGeminiChat<TModel extends (typeof GEMINI_MODELS)[number]>(
  * Creates a Gemini text adapter with automatic API key detection.
  * Type resolution happens here at the call site.
  */
-export function geminiText<TModel extends (typeof GEMINI_MODELS)[number]>(
-  model: TModel,
-  config?: Omit<GeminiTextConfig, 'apiKey'>,
-): GeminiTextAdapter<
-  TModel,
-  ResolveProviderOptions<TModel>,
-  ResolveInputModalities<TModel>,
-  ResolveToolCapabilities<TModel>
-> {
+export function geminiText<
+  TModel extends GeminiModelId,
+  TConfig extends Omit<GeminiTextConfig, 'apiKey'> = Omit<
+    GeminiTextConfig,
+    'apiKey'
+  >,
+>(model: TModel, config?: TConfig): GeminiTextAdapterFor<TModel, TConfig> {
   const apiKey = getGeminiApiKeyFromEnv()
   return createGeminiChat(model, apiKey, config)
 }
diff --git a/packages/ai-gemini/src/index.ts b/packages/ai-gemini/src/index.ts
index 11f8f7a151..aa12b84ac0 100644
--- a/packages/ai-gemini/src/index.ts
+++ b/packages/ai-gemini/src/index.ts
@@ -7,6 +7,8 @@ export {
   GeminiTextAdapter,
   createGeminiChat,
   geminiText,
+  type GeminiModelId,
+  type GeminiTextAdapterFor,
   type GeminiTextConfig,
   type GeminiTextProviderOptions,
 } from './adapters/text'
diff --git a/packages/ai-gemini/tests/chat-per-model-type-safety.test.ts b/packages/ai-gemini/tests/chat-per-model-type-safety.test.ts
index 0e9e05d39d..040d898c76 100644
--- a/packages/ai-gemini/tests/chat-per-model-type-safety.test.ts
+++ b/packages/ai-gemini/tests/chat-per-model-type-safety.test.ts
@@ -10,6 +10,7 @@
 import { beforeAll, describe, expectTypeOf, it } from 'vitest'
 import { chat } from '@tanstack/ai'
 import { geminiText } from '../src'
+import type { ModelReasoning } from '@tanstack/ai'
 import type { GeminiChatModelProviderOptionsByName } from '../src'
 
 // Set a dummy API key so adapter construction does not throw at runtime.
@@ -136,18 +137,10 @@ describe('Gemini per-model chat modelOptions gating', () => {
   })
 
   describe('Model name type safety', () => {
-    it('rejects unknown model names at the factory', () => {
-      // @ts-expect-error - 'gemini-fake-9000' is not a valid Gemini chat model
-      geminiText('gemini-fake-9000')
-    })
-
-    it('rejects retired model ids at the factory', () => {
-      // @ts-expect-error - 'gemini-3-pro-preview' was retired by Google
-      geminiText('gemini-3-pro-preview')
-      // @ts-expect-error - 'gemini-2.0-flash' was retired by Google
-      geminiText('gemini-2.0-flash')
-      // @ts-expect-error - 'gemini-2.0-flash-lite' was retired by Google
-      geminiText('gemini-2.0-flash-lite')
+    it('accepts any model id, such as a Vertex or catalog id', () => {
+      geminiText('gemini-3.5-pro-preview')
+      const id: string = 'gemini-fake-9000'
+      geminiText(id)
     })
   })
 })
@@ -206,3 +199,34 @@ describe('Gemini provider options shape assertions', () => {
     })
   })
 })
+
+describe('Gemini chat reasoning from the config', () => {
+  const messages = [{ role: 'user' as const, content: 'hi' }]
+
+  it('a config with reasoning takes every level, for any model id', () => {
+    const reasoning: ModelReasoning = { budget: true }
+    chat({
+      adapter: geminiText('gemini-3.5-pro-preview', { reasoning }),
+      messages,
+      reasoning: { level: 'high', budgetTokens: 4000 },
+    })
+  })
+
+  it('an id with no table and no config takes no reasoning', () => {
+    chat({
+      adapter: geminiText('gemini-3.5-pro-preview'),
+      messages,
+      // @ts-expect-error - no reasoning data for this id
+      reasoning: 'high',
+    })
+  })
+
+  it('reasoning: false takes no reasoning', () => {
+    chat({
+      adapter: geminiText('gemini-3-flash-preview', { reasoning: false }),
+      messages,
+      // @ts-expect-error - the config says the model does not reason
+      reasoning: 'high',
+    })
+  })
+})
diff --git a/packages/ai-gemini/tests/input-modalities.test.ts b/packages/ai-gemini/tests/input-modalities.test.ts
index c0d6642791..94471794c4 100644
--- a/packages/ai-gemini/tests/input-modalities.test.ts
+++ b/packages/ai-gemini/tests/input-modalities.test.ts
@@ -15,8 +15,7 @@ describe('Gemini text adapter inputModalities', () => {
   })
 
   it('is undefined for a model the metadata does not list', () => {
-    // A JS caller, or a model id newer than this package, reaches the adapter.
-    // @ts-expect-error - 'gemini-unknown-9000' is not a declared model
+    // A Vertex or catalog id, or a model id newer than this package.
     const adapter = new GeminiTextAdapter(config, 'gemini-unknown-9000')
 
     expect(adapter.inputModalities).toBeUndefined()
diff --git a/packages/ai-gemini/tests/reasoning-request.test.ts b/packages/ai-gemini/tests/reasoning-request.test.ts
index e655e65991..db14e12850 100644
--- a/packages/ai-gemini/tests/reasoning-request.test.ts
+++ b/packages/ai-gemini/tests/reasoning-request.test.ts
@@ -2,8 +2,8 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
 import { GeminiTextAdapter } from '../src/adapters/text'
 import { GeminiTextInteractionsAdapter } from '../src/experimental/text-interactions/adapter'
-import type { ReasoningRequest } from '@tanstack/ai'
-import type { GeminiModels } from '../src/model-meta'
+import type { ModelReasoning, ReasoningRequest } from '@tanstack/ai'
+import type { GeminiTextConfig } from '../src/adapters/text'
 
 const mocks = vi.hoisted(() => ({
   generateContentStream: vi.fn(),
@@ -27,11 +27,12 @@ async function* noChunks() {}
 
 /** Run one call and return the `thinkingConfig` it sent. */
 async function thinkingConfig(
-  model: GeminiModels,
+  model: string,
   reasoning: ReasoningRequest | undefined,
+  config: GeminiTextConfig = { apiKey: 'test' },
 ) {
   mocks.generateContentStream.mockResolvedValue(noChunks())
-  const adapter = new GeminiTextAdapter({ apiKey: 'test' }, model)
+  const adapter = new GeminiTextAdapter(config, model)
   for await (const _chunk of adapter.chatStream({
     logger,
     model,
@@ -98,6 +99,65 @@ describe('Gemini chat({ reasoning }) request shape', () => {
   })
 })
 
+describe('Gemini reasoning from the config', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  const levels: ModelReasoning = {
+    map: { off: null, minimal: null, xhigh: null },
+    budget: false,
+  }
+
+  it('sends thinkingLevel for a model id that the table does not have', async () => {
+    expect(
+      await thinkingConfig('gemini-3.5-pro-preview', on('high'), {
+        apiKey: 'test',
+        reasoning: levels,
+      }),
+    ).toEqual({ includeThoughts: true, thinkingLevel: 'HIGH' })
+  })
+
+  it('works the same in Vertex mode', async () => {
+    expect(
+      await thinkingConfig('gemini-3.5-pro-preview', on('low'), {
+        vertexai: true,
+        project: 'p',
+        location: 'global',
+        reasoning: levels,
+      }),
+    ).toEqual({ includeThoughts: true, thinkingLevel: 'LOW' })
+  })
+
+  it('sends a thinking budget for a budget model from the config', async () => {
+    expect(
+      await thinkingConfig('gemini-2.5-flash-preview-09-2025', on('low'), {
+        apiKey: 'test',
+        reasoning: { budget: true },
+      }),
+    ).toEqual({ includeThoughts: true, thinkingBudget: 2048 })
+  })
+
+  it('sends no thinkingConfig for reasoning: false, also on a known model', async () => {
+    expect(
+      await thinkingConfig('gemini-3-flash-preview', on('high'), {
+        apiKey: 'test',
+        reasoning: false,
+      }),
+    ).toBeUndefined()
+  })
+
+  it('clamps the level with the config, not with the table', async () => {
+    // The table gives gemini-3-flash-preview minimal. This config has none.
+    expect(
+      await thinkingConfig('gemini-3-flash-preview', on('minimal'), {
+        apiKey: 'test',
+        reasoning: levels,
+      }),
+    ).toEqual({ includeThoughts: true, thinkingLevel: 'LOW' })
+  })
+})
+
 describe('Gemini Interactions chat({ reasoning }) request shape', () => {
   it('sends thinking_level and thinking_summaries', async () => {
     mocks.interactionsCreate.mockResolvedValue(noChunks())
diff --git a/packages/ai-mistral/src/adapters/text.ts b/packages/ai-mistral/src/adapters/text.ts
index 9b7673d34a..a967e258aa 100644
--- a/packages/ai-mistral/src/adapters/text.ts
+++ b/packages/ai-mistral/src/adapters/text.ts
@@ -26,12 +26,13 @@ import type {
   ModelMessage,
   AdapterYieldChunk,
   ModelReasoning,
+  ConfigReasoning,
+  ReasoningCapability,
   ReasoningRequest,
   ResolvedPromptCache,
   TextOptions,
 } from '@tanstack/ai'
 import type {
-  MISTRAL_CHAT_MODELS,
   MistralChatModelProviderOptionsByName,
   MistralModelInputModalitiesByName,
   MistralTextAdapterModel,
@@ -93,7 +94,21 @@ function parseToolCallInput(
 /**
  * Configuration for Mistral text adapter.
  */
-export type MistralTextConfig = MistralClientConfig
+export interface MistralTextConfig extends MistralClientConfig {
+  /**
+   * The model's reasoning data, for example `modelReasoning(record)` from a
+   * `@tanstack/ai-models` record. It wins over the adapter's own table, for
+   * `reasoning_effort` and for the levels `chat({ reasoning })` takes.
+   * `false`: the model does not reason, so no reasoning field goes out.
+   */
+  reasoning?: ModelReasoning
+}
+
+/**
+ * A model id: a known Mistral model, or any other id, for example a catalog
+ * id that this package does not list yet.
+ */
+export type MistralModelId = MistralTextAdapterModel | (string & {})
 
 /**
  * Alias for TextProviderOptions for external use.
@@ -244,10 +259,11 @@ interface MistralRawChunk {
  * Tree-shakeable adapter for Mistral chat/text completion functionality.
  */
 export class MistralTextAdapter<
-  TModel extends MistralTextAdapterModel,
+  TModel extends MistralModelId,
   TProviderOptions extends Record<string, any> = ResolveProviderOptions<TModel>,
   TInputModalities extends ReadonlyArray<Modality> =
     ResolveInputModalities<TModel>,
+  TReasoning extends ReasoningCapability = ResolveReasoning<TModel>,
 > extends BaseTextAdapter<
   TModel,
   TProviderOptions,
@@ -256,7 +272,7 @@ export class MistralTextAdapter<
   ReadonlyArray<string>,
   unknown,
   never,
-  ResolveReasoning<TModel>
+  TReasoning
 > {
   readonly name = 'mistral' as const
   override readonly api = 'mistral-conversations' as const
@@ -264,7 +280,7 @@ export class MistralTextAdapter<
   override readonly inputModalities = MISTRAL_MODEL_INPUT_MODALITIES[this.model]
 
   private readonly client: Mistral
-  private readonly rawConfig: MistralClientConfig
+  private readonly rawConfig: MistralTextConfig
 
   constructor(config: MistralTextConfig, model: TModel) {
     super(config, model)
@@ -1102,7 +1118,7 @@ export class MistralTextAdapter<
       stream: true,
       ...mistralReasoning(
         options.reasoning,
-        MISTRAL_MODEL_REASONING[options.model],
+        this.rawConfig.reasoning ?? MISTRAL_MODEL_REASONING[options.model],
       ),
       ...(modelOptions && {
         ...(modelOptions.stop != null && { stop: modelOptions.stop }),
@@ -1383,6 +1399,20 @@ function messageToWire(msg: ChatCompletionStreamRequest['messages'][number]) {
   return msg
 }
 
+/**
+ * The adapter type for a model and a config. A config with `reasoning` sets
+ * the levels `chat({ reasoning })` takes; see {@link ConfigReasoning}.
+ */
+export type MistralTextAdapterFor<
+  TModel extends MistralModelId,
+  TConfig = MistralTextConfig,
+> = MistralTextAdapter<
+  TModel,
+  ResolveProviderOptions<TModel>,
+  ResolveInputModalities<TModel>,
+  ConfigReasoning<TConfig, ResolveReasoning<TModel>>
+>
+
 /**
  * Creates a Mistral text adapter with explicit API key.
  *
@@ -1397,12 +1427,16 @@ function messageToWire(msg: ChatCompletionStreamRequest['messages'][number]) {
  * ```
  */
 export function createMistralText<
-  TModel extends (typeof MISTRAL_CHAT_MODELS)[number],
+  TModel extends MistralModelId,
+  TConfig extends Omit<MistralTextConfig, 'apiKey'> = Omit<
+    MistralTextConfig,
+    'apiKey'
+  >,
 >(
   model: TModel,
   apiKey: string,
-  config?: Omit<MistralTextConfig, 'apiKey'>,
-): MistralTextAdapter<TModel> {
+  config?: TConfig,
+): MistralTextAdapterFor<TModel, TConfig> {
   return new MistralTextAdapter({ apiKey, ...config }, model)
 }
 
@@ -1420,11 +1454,12 @@ export function createMistralText<
  * ```
  */
 export function mistralText<
-  TModel extends (typeof MISTRAL_CHAT_MODELS)[number],
->(
-  model: TModel,
-  config?: Omit<MistralTextConfig, 'apiKey'>,
-): MistralTextAdapter<TModel> {
+  TModel extends MistralModelId,
+  TConfig extends Omit<MistralTextConfig, 'apiKey'> = Omit<
+    MistralTextConfig,
+    'apiKey'
+  >,
+>(model: TModel, config?: TConfig): MistralTextAdapterFor<TModel, TConfig> {
   const apiKey = getMistralApiKeyFromEnv()
   return createMistralText(model, apiKey, config)
 }
diff --git a/packages/ai-mistral/src/index.ts b/packages/ai-mistral/src/index.ts
index 1b993a1ab3..8f243d35cb 100644
--- a/packages/ai-mistral/src/index.ts
+++ b/packages/ai-mistral/src/index.ts
@@ -10,6 +10,8 @@ export {
   MistralTextAdapter,
   createMistralText,
   mistralText,
+  type MistralModelId,
+  type MistralTextAdapterFor,
   type MistralTextConfig,
   type MistralTextProviderOptions,
 } from './adapters/text'
diff --git a/packages/ai-mistral/src/input-modalities.test.ts b/packages/ai-mistral/src/input-modalities.test.ts
index ec5cfd6e34..2322894921 100644
--- a/packages/ai-mistral/src/input-modalities.test.ts
+++ b/packages/ai-mistral/src/input-modalities.test.ts
@@ -15,8 +15,7 @@ describe('Mistral text adapter inputModalities', () => {
   })
 
   it('is undefined for a model the metadata does not list', () => {
-    // A JS caller, or a model id newer than this package, reaches the adapter.
-    // @ts-expect-error - 'mistral-unknown-9000' is not a declared model
+    // A catalog id, or a model id newer than this package.
     const adapter = new MistralTextAdapter(config, 'mistral-unknown-9000')
 
     expect(adapter.inputModalities).toBeUndefined()
diff --git a/packages/ai-mistral/tests/reasoning-request.test.ts b/packages/ai-mistral/tests/reasoning-request.test.ts
index 82a080531b..653b0d0337 100644
--- a/packages/ai-mistral/tests/reasoning-request.test.ts
+++ b/packages/ai-mistral/tests/reasoning-request.test.ts
@@ -1,15 +1,17 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { chat } from '@tanstack/ai'
 import { createMistralText } from '../src/adapters/text'
-import type { ReasoningRequest } from '@tanstack/ai'
-import type { MISTRAL_CHAT_MODELS } from '../src/model-meta'
+import type { ModelReasoning, ReasoningRequest } from '@tanstack/ai'
+import type { MistralModelId } from '../src/adapters/text'
 
 const logger = resolveDebugOption(false)
 
 /** Run one streaming call and return the JSON body it sent. */
 async function send(
-  model: (typeof MISTRAL_CHAT_MODELS)[number],
+  model: MistralModelId,
   reasoning: ReasoningRequest | undefined,
+  config?: ModelReasoning,
 ) {
   const fetchMock = vi.fn().mockResolvedValue({
     ok: true,
@@ -22,7 +24,11 @@ async function send(
     }),
   })
   vi.stubGlobal('fetch', fetchMock)
-  const adapter = createMistralText(model, 'test-key')
+  const adapter = createMistralText(
+    model,
+    'test-key',
+    config !== undefined ? { reasoning: config } : {},
+  )
   for await (const _chunk of adapter.chatStream({
     logger,
     model,
@@ -68,3 +74,56 @@ describe('Mistral chat({ reasoning }) request shape', () => {
     expect(body).not.toHaveProperty('prompt_mode')
   })
 })
+
+describe('Mistral reasoning from the config', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  const effort: ModelReasoning = {
+    map: { off: 'none', minimal: null, low: null, medium: null, high: 'high' },
+    budget: false,
+  }
+
+  it('sends reasoning_effort for a model id that the table does not have', async () => {
+    expect(await send('mistral-medium-2509', on('high'), effort)).toMatchObject(
+      { reasoning_effort: 'high' },
+    )
+  })
+
+  it('sends prompt_mode for a record with no level map', async () => {
+    const body = await send('magistral-small-2509', on('medium'), {
+      budget: false,
+    })
+    expect(body.prompt_mode).toBe('reasoning')
+  })
+
+  it('sends no reasoning field for reasoning: false, also on a known model', async () => {
+    const body = await send('mistral-small-latest', on('high'), false)
+    expect(body).not.toHaveProperty('reasoning_effort')
+    expect(body).not.toHaveProperty('prompt_mode')
+  })
+
+  it('clamps the level with the config, not with the table', async () => {
+    // This config has only off and high, so low moves up to high.
+    expect(await send('mistral-small-latest', on('low'), effort)).toMatchObject(
+      { reasoning_effort: 'high' },
+    )
+  })
+
+  it('takes every level in the types with a reasoning config', () => {
+    const id: string = 'mistral-medium-2509'
+    // Type-level only: chat() is never iterated, so no request goes out.
+    chat({
+      adapter: createMistralText(id, 'k', { reasoning: effort }),
+      messages: [{ role: 'user', content: 'hi' }],
+      reasoning: 'max',
+    })
+    chat({
+      adapter: createMistralText(id, 'k'),
+      messages: [{ role: 'user', content: 'hi' }],
+      // @ts-expect-error - no reasoning data for this id
+      reasoning: 'high',
+    })
+  })
+})
diff --git a/packages/ai-models/src/index.ts b/packages/ai-models/src/index.ts
index 11cdbc144d..ac12b525f0 100644
--- a/packages/ai-models/src/index.ts
+++ b/packages/ai-models/src/index.ts
@@ -2,13 +2,18 @@ import { generatedAt, providerModules } from './catalog'
 import type { ModelRecord, ProviderRecord } from './types'
 
 export { generatedAt }
-export { clampReasoningLevel, supportedReasoningLevels } from './reasoning'
+export {
+  clampReasoningLevel,
+  modelReasoning,
+  supportedReasoningLevels,
+} from './reasoning'
 export { modelCost } from './cost'
 export type {
   Cost,
   InputModality,
   ModelCompat,
   ModelCostRates,
+  ModelReasoning,
   ModelRecord,
   ProviderRecord,
   ReasoningLevel,
diff --git a/packages/ai-models/src/reasoning.ts b/packages/ai-models/src/reasoning.ts
index 4f0dcf8eda..346009b384 100644
--- a/packages/ai-models/src/reasoning.ts
+++ b/packages/ai-models/src/reasoning.ts
@@ -1,4 +1,18 @@
-import type { ModelRecord, ReasoningLevel } from './types'
+import type { ModelReasoning, ModelRecord, ReasoningLevel } from './types'
+
+/**
+ * The record's reasoning data for an adapter's `reasoning` config:
+ * `createAnthropicChat(record.id, key, { reasoning: modelReasoning(record) })`.
+ */
+export function modelReasoning(
+  model: Pick<ModelRecord, 'reasoning' | 'reasoningMap' | 'reasoningBudget'>,
+): ModelReasoning {
+  if (!model.reasoning) return false
+  return {
+    ...(model.reasoningMap ? { map: model.reasoningMap } : {}),
+    budget: model.reasoningBudget === true,
+  }
+}
 
 // ponytail: the same rules as `supportedReasoningLevels` and
 // `clampReasoningLevel` in `@tanstack/ai` (pi's rules). They are copied so
diff --git a/packages/ai-models/src/types.ts b/packages/ai-models/src/types.ts
index 57205e66bf..33479944bd 100644
--- a/packages/ai-models/src/types.ts
+++ b/packages/ai-models/src/types.ts
@@ -18,6 +18,13 @@ export type ReasoningLevel =
  */
 export type ReasoningMap = Partial<Record<ReasoningLevel, string | null>>
 
+/**
+ * A model's reasoning data, in the shape of the `reasoning` config of the
+ * `@tanstack/ai` adapters (`ModelReasoning` there). `false`: the model does
+ * not reason. Otherwise its level map and whether it takes a token budget.
+ */
+export type ModelReasoning = false | { map?: ReasoningMap; budget: boolean }
+
 /** The wire protocol of a model. It picks the adapter. */
 export type WireApi =
   | 'anthropic-messages'
diff --git a/packages/ai-models/tests/catalog.test.ts b/packages/ai-models/tests/catalog.test.ts
index 9f46039ce7..632907e911 100644
--- a/packages/ai-models/tests/catalog.test.ts
+++ b/packages/ai-models/tests/catalog.test.ts
@@ -3,6 +3,7 @@ import {
   clampReasoningLevel as coreClamp,
   supportedReasoningLevels as coreSupported,
 } from '@tanstack/ai'
+import type { ModelReasoning as CoreModelReasoning } from '@tanstack/ai'
 import {
   clampReasoningLevel,
   generatedAt,
@@ -10,6 +11,7 @@ import {
   getModels,
   getProviders,
   modelCost,
+  modelReasoning,
   supportedReasoningLevels,
 } from '../src'
 import * as deepseek from '../src/providers/deepseek'
@@ -121,3 +123,32 @@ describe('reasoning helpers match @tanstack/ai', () => {
     expect(clampReasoningLevel({ reasoning: false }, 'max')).toBe('off')
   })
 })
+
+describe('modelReasoning', () => {
+  const map: ReasoningMap = { off: null, xhigh: 'xhigh' }
+
+  it('gives false for a model that does not reason', () => {
+    expect(modelReasoning({ reasoning: false, reasoningMap: map })).toBe(false)
+  })
+
+  it('gives the level map and the budget flag', () => {
+    expect(
+      modelReasoning({
+        reasoning: true,
+        reasoningMap: map,
+        reasoningBudget: true,
+      }),
+    ).toEqual({ map, budget: true })
+    expect(modelReasoning({ reasoning: true })).toEqual({ budget: false })
+  })
+
+  it('fits the reasoning config of the adapters', () => {
+    const record = getModel('anthropic', 'claude-sonnet-4-5-20250929')
+    if (!record) throw new Error('Expected the catalog record')
+    const config: CoreModelReasoning = modelReasoning(record)
+    expect(config).toEqual({
+      ...(record.reasoningMap ? { map: record.reasoningMap } : {}),
+      budget: record.reasoningBudget === true,
+    })
+  })
+})
diff --git a/packages/ai-openai/src/adapters/azure-text.ts b/packages/ai-openai/src/adapters/azure-text.ts
index dc1539d8ed..8ae4792399 100644
--- a/packages/ai-openai/src/adapters/azure-text.ts
+++ b/packages/ai-openai/src/adapters/azure-text.ts
@@ -1,7 +1,15 @@
 import { AzureOpenAI } from 'openai'
 import { OpenAIBaseResponsesTextAdapter } from '@tanstack/openai-base'
 import { convertToolsToProviderFormat } from '../tools'
-import type { AnyTool, TextOptions } from '@tanstack/ai'
+import type {
+  AnyTool,
+  ConfigReasoning,
+  DefaultMessageMetadataByModality,
+  Modality,
+  ModelReasoning,
+  ReasoningCapability,
+  TextOptions,
+} from '@tanstack/ai'
 import type { OpenAIBaseTextAdapterOptions } from '@tanstack/openai-base'
 import type { Tool as ResponsesTool } from 'openai/resources/responses/responses'
 import type { ExternalTextProviderOptions } from '../text/text-provider-options'
@@ -14,6 +22,12 @@ export interface AzureOpenAITextConfig
   apiVersion?: string
   deploymentName?: string
   deploymentNameMap?: Readonly<Record<string, string>>
+  /**
+   * The model's reasoning data, for example `modelReasoning(record)` from a
+   * `@tanstack/ai-models` record. With it, `chat({ reasoning })` sends
+   * `reasoning.effort`. Without it, no reasoning field goes out.
+   */
+  reasoning?: ModelReasoning
 }
 
 function normalizeAzureBaseURL(baseURL: string): string {
@@ -34,12 +48,19 @@ function normalizeAzureBaseURL(baseURL: string): string {
   return url.toString().replace(/\/+$/, '')
 }
 
-export class AzureOpenAITextAdapter extends OpenAIBaseResponsesTextAdapter<
+export class AzureOpenAITextAdapter<
+  TReasoning extends ReasoningCapability = never,
+> extends OpenAIBaseResponsesTextAdapter<
   string,
-  { [K in keyof ExternalTextProviderOptions]: ExternalTextProviderOptions[K] }
+  { [K in keyof ExternalTextProviderOptions]: ExternalTextProviderOptions[K] },
+  ReadonlyArray<Modality>,
+  DefaultMessageMetadataByModality,
+  ReadonlyArray<string>,
+  TReasoning
 > {
   override readonly api = 'azure-openai-responses'
   private readonly deploymentName: string
+  private readonly configReasoning: ModelReasoning | undefined
 
   constructor(config: AzureOpenAITextConfig, model: string) {
     const {
@@ -49,6 +70,7 @@ export class AzureOpenAITextAdapter extends OpenAIBaseResponsesTextAdapter<
       apiVersion,
       deploymentName,
       deploymentNameMap,
+      reasoning,
       ...clientOptions
     } = config
     const env: Record<string, string | undefined> =
@@ -72,6 +94,7 @@ export class AzureOpenAITextAdapter extends OpenAIBaseResponsesTextAdapter<
       apiVersion: apiVersion || env.AZURE_OPENAI_API_VERSION || 'v1',
     })
     super(model, 'azure-openai-responses', client, config)
+    this.configReasoning = reasoning
     const envMap = new Map<string, string>()
     for (const entry of (env.AZURE_OPENAI_DEPLOYMENT_NAME_MAP ?? '').split(
       ',',
@@ -91,6 +114,10 @@ export class AzureOpenAITextAdapter extends OpenAIBaseResponsesTextAdapter<
       model
   }
 
+  protected override modelReasoning(_model: string) {
+    return this.configReasoning
+  }
+
   protected override convertTools(tools: Array<AnyTool>): Array<ResponsesTool> {
     return convertToolsToProviderFormat(tools)
   }
@@ -102,9 +129,11 @@ export class AzureOpenAITextAdapter extends OpenAIBaseResponsesTextAdapter<
   }
 }
 
-export function azureOpenaiText(
+export function azureOpenaiText<
+  TConfig extends AzureOpenAITextConfig = AzureOpenAITextConfig,
+>(
   model: string,
-  config: AzureOpenAITextConfig = {},
-): AzureOpenAITextAdapter {
-  return new AzureOpenAITextAdapter(config, model)
+  config?: TConfig,
+): AzureOpenAITextAdapter<ConfigReasoning<TConfig, never>> {
+  return new AzureOpenAITextAdapter(config ?? {}, model)
 }
diff --git a/packages/ai-openai/src/adapters/text.ts b/packages/ai-openai/src/adapters/text.ts
index 702d61e4f8..ea8af5559b 100644
--- a/packages/ai-openai/src/adapters/text.ts
+++ b/packages/ai-openai/src/adapters/text.ts
@@ -13,7 +13,6 @@ import {
 import { responsesPromptCacheFields } from '../prompt-cache'
 import type {
   OPENAI_CHAT_MODELS,
-  OpenAIChatModel,
   OpenAIChatModelProviderOptionsByName,
   OpenAIChatModelToolCapabilitiesByName,
   OpenAIModelInputModalitiesByName,
@@ -24,8 +23,11 @@ import type {
 } from 'openai/resources/responses/responses'
 import type {
   AnyTool,
+  ConfigReasoning,
   MidConversationChannels,
   Modality,
+  ModelReasoning,
+  ReasoningCapability,
   TextOptions,
 } from '@tanstack/ai'
 import type { OpenAIModelReasoningByName } from '../model-reasoning'
@@ -52,8 +54,21 @@ export interface OpenAITextConfig
    * `false` turns them off, so every request is built as before.
    */
   midConversationChannels?: boolean
+  /**
+   * The model's reasoning data, for example `modelReasoning(record)` from a
+   * `@tanstack/ai-models` record. It wins over the adapter's own table, for
+   * `reasoning.effort` and for the levels `chat({ reasoning })` takes.
+   * `false`: the model does not reason, so no reasoning field goes out.
+   */
+  reasoning?: ModelReasoning
 }
 
+/**
+ * A model id: a known OpenAI model, or any other id, for example a catalog
+ * id that this package does not list yet.
+ */
+export type OpenAIModelId = (typeof OPENAI_CHAT_MODELS)[number] | (string & {})
+
 /**
  * Alias for TextProviderOptions
  */
@@ -112,19 +127,20 @@ type ResolveToolCapabilities<TModel extends string> =
  * apply provider option validation.
  */
 export class OpenAITextAdapter<
-  TModel extends OpenAIChatModel,
+  TModel extends OpenAIModelId,
   TProviderOptions extends Record<string, any> = ResolveProviderOptions<TModel>,
   TInputModalities extends ReadonlyArray<Modality> =
     ResolveInputModalities<TModel>,
   TToolCapabilities extends ReadonlyArray<string> =
     ResolveToolCapabilities<TModel>,
+  TReasoning extends ReasoningCapability = ResolveReasoning<TModel>,
 > extends OpenAIBaseResponsesTextAdapter<
   TModel,
   TProviderOptions,
   TInputModalities,
   OpenAIMessageMetadataByModality,
   TToolCapabilities,
-  ResolveReasoning<TModel>
+  TReasoning
 > {
   override readonly kind = 'text' as const
   override readonly name = 'openai' as const
@@ -139,8 +155,12 @@ export class OpenAITextAdapter<
     | MidConversationChannels
     | undefined = undefined
 
+  /** `config.reasoning`, which wins over `OPENAI_MODEL_REASONING`. */
+  private readonly configReasoning: ModelReasoning | undefined
+
   constructor(config: OpenAITextConfig, model: TModel) {
     super(model, 'openai', new OpenAI(config), config)
+    this.configReasoning = config.reasoning
     // On by default only on OpenAI's own API: a proxy or a gateway (a
     // `baseURL`, a `fetch`, or the SDK's OPENAI_BASE_URL env var) may not
     // pass the changes. The option wins.
@@ -156,7 +176,7 @@ export class OpenAITextAdapter<
   }
 
   protected override modelReasoning(model: string) {
-    return OPENAI_MODEL_REASONING[model]
+    return this.configReasoning ?? OPENAI_MODEL_REASONING[model]
   }
 
   /** OpenAI's full tool converter (file_search, web_search, etc.). */
@@ -256,6 +276,21 @@ export class OpenAITextAdapter<
   }
 }
 
+/**
+ * The adapter type for a model and a config. A config with `reasoning` sets
+ * the levels `chat({ reasoning })` takes; see {@link ConfigReasoning}.
+ */
+export type OpenAITextAdapterFor<
+  TModel extends OpenAIModelId,
+  TConfig = OpenAITextConfig,
+> = OpenAITextAdapter<
+  TModel,
+  ResolveProviderOptions<TModel>,
+  ResolveInputModalities<TModel>,
+  ResolveToolCapabilities<TModel>,
+  ConfigReasoning<TConfig, ResolveReasoning<TModel>>
+>
+
 /**
  * Creates an OpenAI chat adapter with explicit API key.
  * Type resolution happens here at the call site.
@@ -272,12 +307,16 @@ export class OpenAITextAdapter<
  * ```
  */
 export function createOpenaiChat<
-  TModel extends (typeof OPENAI_CHAT_MODELS)[number],
+  TModel extends OpenAIModelId,
+  TConfig extends Omit<OpenAITextConfig, 'apiKey'> = Omit<
+    OpenAITextConfig,
+    'apiKey'
+  >,
 >(
   model: TModel,
   apiKey: string,
-  config?: Omit<OpenAITextConfig, 'apiKey'>,
-): OpenAITextAdapter<TModel> {
+  config?: TConfig,
+): OpenAITextAdapterFor<TModel, TConfig> {
   return new OpenAITextAdapter({ apiKey, ...config }, model)
 }
 
@@ -305,10 +344,13 @@ export function createOpenaiChat<
  * });
  * ```
  */
-export function openaiText<TModel extends (typeof OPENAI_CHAT_MODELS)[number]>(
-  model: TModel,
-  config?: Omit<OpenAITextConfig, 'apiKey'>,
-): OpenAITextAdapter<TModel> {
+export function openaiText<
+  TModel extends OpenAIModelId,
+  TConfig extends Omit<OpenAITextConfig, 'apiKey'> = Omit<
+    OpenAITextConfig,
+    'apiKey'
+  >,
+>(model: TModel, config?: TConfig): OpenAITextAdapterFor<TModel, TConfig> {
   const apiKey = getOpenAIApiKeyFromEnv()
   return createOpenaiChat(model, apiKey, config)
 }
diff --git a/packages/ai-openai/src/index.ts b/packages/ai-openai/src/index.ts
index 530c990b50..faed321fb3 100644
--- a/packages/ai-openai/src/index.ts
+++ b/packages/ai-openai/src/index.ts
@@ -7,6 +7,8 @@ export {
   OpenAITextAdapter,
   createOpenaiChat,
   openaiText,
+  type OpenAIModelId,
+  type OpenAITextAdapterFor,
   type OpenAITextConfig,
   type OpenAITextProviderOptions,
 } from './adapters/text'
diff --git a/packages/ai-openai/tests/chat-per-model-type-safety.test.ts b/packages/ai-openai/tests/chat-per-model-type-safety.test.ts
index b5f3730fff..d00939b43e 100644
--- a/packages/ai-openai/tests/chat-per-model-type-safety.test.ts
+++ b/packages/ai-openai/tests/chat-per-model-type-safety.test.ts
@@ -9,7 +9,8 @@
  */
 import { beforeAll, describe, expectTypeOf, it } from 'vitest'
 import { chat } from '@tanstack/ai'
-import { openaiText } from '../src'
+import { azureOpenaiText, openaiText } from '../src'
+import type { ModelReasoning } from '@tanstack/ai'
 import type { OpenAIChatModelProviderOptionsByName } from '../src'
 
 // Set a dummy API key so adapter construction does not throw at runtime.
@@ -229,9 +230,59 @@ describe('OpenAI per-model chat modelOptions gating', () => {
   })
 
   describe('Model name type safety', () => {
-    it('rejects unknown model names at the factory', () => {
-      // @ts-expect-error - 'gpt-unknown-9000' is not a valid OpenAI chat model
-      openaiText('gpt-unknown-9000')
+    it('accepts any model id, such as a catalog id', () => {
+      openaiText('gpt-5.3-codex')
+      const id: string = 'gpt-unknown-9000'
+      openaiText(id)
+    })
+  })
+})
+
+describe('OpenAI chat reasoning from the config', () => {
+  const messages = [{ role: 'user' as const, content: 'hi' }]
+
+  it('a config with reasoning takes every level, for any model id', () => {
+    const reasoning: ModelReasoning = { budget: false }
+    chat({
+      adapter: openaiText('gpt-5.3-codex', { reasoning }),
+      messages,
+      reasoning: 'high',
+    })
+  })
+
+  it('an id with no table and no config takes no reasoning', () => {
+    chat({
+      adapter: openaiText('gpt-5.3-codex'),
+      messages,
+      // @ts-expect-error - no reasoning data for this id
+      reasoning: 'high',
+    })
+  })
+
+  it('reasoning: false takes no reasoning', () => {
+    chat({
+      adapter: openaiText('gpt-5.3-codex', { reasoning: false }),
+      messages,
+      // @ts-expect-error - the config says the model does not reason
+      reasoning: 'high',
+    })
+  })
+
+  it('azureOpenaiText takes reasoning only from the config', () => {
+    chat({
+      adapter: azureOpenaiText('gpt-5.5', {
+        resourceName: 'r',
+        apiKey: 'k',
+        reasoning: { budget: false },
+      }),
+      messages,
+      reasoning: 'medium',
+    })
+    chat({
+      adapter: azureOpenaiText('gpt-5.5', { resourceName: 'r', apiKey: 'k' }),
+      messages,
+      // @ts-expect-error - no reasoning data without the config
+      reasoning: 'medium',
     })
   })
 })
diff --git a/packages/ai-openai/tests/input-modalities.test.ts b/packages/ai-openai/tests/input-modalities.test.ts
index 949cf80da1..fce7d07cbd 100644
--- a/packages/ai-openai/tests/input-modalities.test.ts
+++ b/packages/ai-openai/tests/input-modalities.test.ts
@@ -19,8 +19,7 @@ describe('OpenAI text adapter inputModalities', () => {
   })
 
   it('is undefined for a model the metadata does not list', () => {
-    // A JS caller, or a model id newer than this package, reaches the adapter.
-    // @ts-expect-error - 'gpt-unknown-9000' is not a declared model
+    // A catalog id, or a model id newer than this package.
     const adapter = new OpenAITextAdapter(config, 'gpt-unknown-9000')
 
     expect(adapter.inputModalities).toBeUndefined()
diff --git a/packages/ai-openai/tests/reasoning-request.test.ts b/packages/ai-openai/tests/reasoning-request.test.ts
index 1b2a056229..185345c3e2 100644
--- a/packages/ai-openai/tests/reasoning-request.test.ts
+++ b/packages/ai-openai/tests/reasoning-request.test.ts
@@ -1,14 +1,15 @@
 import { describe, expect, it, vi } from 'vitest'
 import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
 import { OpenAITextAdapter } from '../src/adapters/text'
-import type { OpenAIChatModel } from '../src/model-meta'
-import type { ReasoningRequest } from '@tanstack/ai'
+import { azureOpenaiText } from '../src'
+import type { OpenAIModelId } from '../src/adapters/text'
+import type { ModelReasoning, ReasoningRequest } from '@tanstack/ai'
 
 const logger = resolveDebugOption(false)
 
 /** The adapter, with its SDK client in reach, so a test can stub it. */
 class TestAdapter<
-  TModel extends OpenAIChatModel,
+  TModel extends OpenAIModelId,
 > extends OpenAITextAdapter<TModel> {
   get sdk() {
     return this.client
@@ -19,10 +20,14 @@ async function* noEvents() {}
 
 /** The `reasoning` field of the Responses request for one call. */
 async function reasoningFor(
-  model: OpenAIChatModel,
+  model: OpenAIModelId,
   reasoning: ReasoningRequest | undefined,
+  config?: ModelReasoning,
 ) {
-  const adapter = new TestAdapter({ apiKey: 'test' }, model)
+  const adapter = new TestAdapter(
+    { apiKey: 'test', ...(config !== undefined ? { reasoning: config } : {}) },
+    model,
+  )
   const create = vi.fn().mockResolvedValue(noEvents())
   adapter.sdk.responses.create = create as typeof adapter.sdk.responses.create
   for await (const _chunk of adapter.chatStream({
@@ -80,3 +85,61 @@ describe('OpenAI chat({ reasoning })', () => {
     ).toBeUndefined()
   })
 })
+
+describe('OpenAI reasoning from the config', () => {
+  const high: ReasoningRequest = { level: 'high', summary: true }
+
+  it('sends the effort for a model id that the table does not have', async () => {
+    expect(
+      await reasoningFor('gpt-5.3-codex', high, {
+        map: { off: 'none', xhigh: 'xhigh' },
+        budget: false,
+      }),
+    ).toEqual({ effort: 'high', summary: 'auto' })
+  })
+
+  it('sends nothing for reasoning: false, also on a known model', async () => {
+    expect(await reasoningFor('gpt-5.2', high, false)).toBeUndefined()
+  })
+
+  it('clamps the level with the config, not with the table', async () => {
+    // The table gives gpt-5.2 xhigh. This config tops out at high.
+    expect(
+      await reasoningFor(
+        'gpt-5.2',
+        { level: 'xhigh', summary: false },
+        { budget: false },
+      ),
+    ).toEqual({ effort: 'high' })
+  })
+
+  it('azureOpenaiText sends the effort only with the config', async () => {
+    const bodies: Array<Record<string, unknown>> = []
+    const fetcher: typeof fetch = async (input, init) => {
+      bodies.push(JSON.parse(await new Request(input, init).text()))
+      return Response.json({
+        id: 'r',
+        status: 'completed',
+        output: [],
+      })
+    }
+    for (const reasoning of [{ budget: false }, undefined]) {
+      const adapter = azureOpenaiText('gpt-5.5', {
+        resourceName: 'test',
+        apiKey: 'key',
+        fetch: fetcher,
+        ...(reasoning ? { reasoning } : {}),
+      })
+      for await (const _chunk of adapter.chatStream({
+        logger,
+        model: 'gpt-5.5',
+        messages: [{ role: 'user', content: 'hi' }],
+        reasoning: high,
+      })) {
+        // Drain the stream.
+      }
+    }
+    expect(bodies[0]?.reasoning).toEqual({ effort: 'high', summary: 'auto' })
+    expect(bodies[1]).not.toHaveProperty('reasoning')
+  })
+})
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index a61e72a13c..5684ccb941 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -457,6 +457,7 @@ export {
 } from './reasoning'
 export type {
   AdapterReasoning,
+  ConfigReasoning,
   ModelReasoning,
   ReasoningCapability,
   ReasoningLevel,
diff --git a/packages/ai/src/reasoning.ts b/packages/ai/src/reasoning.ts
index 72055aef10..0db74031e5 100644
--- a/packages/ai/src/reasoning.ts
+++ b/packages/ai/src/reasoning.ts
@@ -84,6 +84,22 @@ export interface ReasoningRequest {
  */
 export type ModelReasoning = false | { map?: ReasoningMap; budget: boolean }
 
+/**
+ * The reasoning capability of an adapter whose config can carry `reasoning`
+ * (a model's data, for example from a catalog record). With `reasoning` in
+ * the config, `chat({ reasoning })` takes every level, and the adapter moves
+ * a level the model does not have to the nearest one. `reasoning: false`
+ * takes none. Without it, the adapter's own data for the model applies.
+ */
+export type ConfigReasoning<
+  TConfig,
+  TTable extends ReasoningCapability,
+> = TConfig extends { reasoning: false }
+  ? never
+  : TConfig extends { reasoning: ModelReasoning }
+    ? ReasoningCapability
+    : TTable
+
 /** A level or an object, as the user passed it, into the one shape adapters read. */
 export function normalizeReasoning(
   option: ReasoningOption | undefined,

From d4cab6f1937797855ca2cd229ceb431074dfb7d9 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 12:31:22 +0200
Subject: [PATCH 241/286] feat(ai-harness, ai-persistence): finish the coding
 tools and the harness plugins

Checkpoint 3 of the opencode primitives plan.

- Coding tools (PL1): read_file reads pages, images and PDFs, refuses
  binary files, and suggests close names; list_files and grep use
  ripgrep, git ls-files, or a walk, with safe shell quoting; a patch
  tool with delete and move; webfetch with private host checks and an
  optional turndown; a websearch provider interface; a question tool.
  workspaceTools joins them, with editStyle, permission resources, and
  background bash notes.
- Workspace safety: the boundary check follows real paths, links are
  skipped in listings, quoting follows the backend shell, sandbox roots
  keep POSIX paths, and a timeout kills the whole process tree.
- WorkspaceBackend gets optional remove, realpath, and shell.
- agents() with built-in and markdown agents, /agent, and a step limit
  (PL3). projectInstructions walks up to the repo root, adds an
  environment block, and sends changes as mid-conversation changes (PL4).
- snapshots() with /undo and /redo in a shadow git repository (PL5),
  formatter() after writes (PL6), title() and the usage cost (PL8).
- Child index entries copy the owner of their parent thread (C6).
---
 packages/ai-harness/src/build.ts              |   5 +-
 packages/ai-harness/src/first-party/agents.ts | 353 ++++++++++++
 .../src/first-party/coding/backend.ts         | 205 +++++--
 .../src/first-party/coding/formatter.ts       | 242 ++++++++
 .../src/first-party/coding/patch.ts           | 120 +++-
 .../ai-harness/src/first-party/coding/read.ts | 176 +++++-
 .../src/first-party/coding/search.ts          | 380 +++++++++++--
 .../src/first-party/coding/snapshots.ts       | 279 +++++++++
 .../ai-harness/src/first-party/coding/web.ts  | 384 +++++++++++++
 .../src/first-party/coding/workspace.ts       | 174 +++++-
 packages/ai-harness/src/first-party/files.ts  | 295 ++++++++--
 .../ai-harness/src/first-party/question.ts    | 189 ++++++
 .../src/first-party/session-tools.ts          | 100 +++-
 packages/ai-harness/src/first-party/title.ts  |  88 +++
 packages/ai-harness/tests/agents.test.ts      | 377 ++++++++++++
 .../ai-harness/tests/coding-backend.test.ts   |  28 +
 .../ai-harness/tests/coding-formatter.test.ts | 289 ++++++++++
 .../ai-harness/tests/coding-patch.test.ts     |  81 ++-
 packages/ai-harness/tests/coding-read.test.ts | 282 +++++++++
 .../ai-harness/tests/coding-search.test.ts    | 453 +++++++++++++++
 .../ai-harness/tests/coding-snapshots.test.ts | 336 +++++++++++
 packages/ai-harness/tests/coding-web.test.ts  | 315 ++++++++++
 packages/ai-harness/tests/edge-safety.test.ts |   1 +
 .../ai-harness/tests/instructions.test.ts     | 265 +++++++++
 packages/ai-harness/tests/permissions.test.ts |   4 +
 packages/ai-harness/tests/question.test.ts    | 124 ++++
 packages/ai-harness/tests/title-usage.test.ts | 185 ++++++
 .../ai-harness/tests/workspace-tools.test.ts  | 537 ++++++++++++++++--
 packages/ai-persistence/src/subagent-runs.ts  |   5 +-
 .../tests/subagent-persistence-cards.test.ts  |  29 +
 30 files changed, 6043 insertions(+), 258 deletions(-)
 create mode 100644 packages/ai-harness/src/first-party/agents.ts
 create mode 100644 packages/ai-harness/src/first-party/coding/formatter.ts
 create mode 100644 packages/ai-harness/src/first-party/coding/snapshots.ts
 create mode 100644 packages/ai-harness/src/first-party/coding/web.ts
 create mode 100644 packages/ai-harness/src/first-party/question.ts
 create mode 100644 packages/ai-harness/src/first-party/title.ts
 create mode 100644 packages/ai-harness/tests/agents.test.ts
 create mode 100644 packages/ai-harness/tests/coding-formatter.test.ts
 create mode 100644 packages/ai-harness/tests/coding-read.test.ts
 create mode 100644 packages/ai-harness/tests/coding-search.test.ts
 create mode 100644 packages/ai-harness/tests/coding-snapshots.test.ts
 create mode 100644 packages/ai-harness/tests/coding-web.test.ts
 create mode 100644 packages/ai-harness/tests/instructions.test.ts
 create mode 100644 packages/ai-harness/tests/question.test.ts
 create mode 100644 packages/ai-harness/tests/title-usage.test.ts

diff --git a/packages/ai-harness/src/build.ts b/packages/ai-harness/src/build.ts
index 6ebfb5b5c2..3035c77ccc 100644
--- a/packages/ai-harness/src/build.ts
+++ b/packages/ai-harness/src/build.ts
@@ -155,7 +155,10 @@ export async function buildHarness(options: BuildHarnessOptions): Promise<{
         '{}',
     )
     const names = described.plugins.map((plugin) => plugin.name)
-    const usesWorkspace = names.includes('tanstack/workspace-tools')
+    // Snapshots run git in the workspace, like the workspace tools.
+    const usesWorkspace =
+      names.includes('tanstack/workspace-tools') ||
+      names.includes('tanstack/snapshots')
     const manifest: HarnessManifestV1 = {
       format: 'tanstack-ai-harness',
       version: 1,
diff --git a/packages/ai-harness/src/first-party/agents.ts b/packages/ai-harness/src/first-party/agents.ts
new file mode 100644
index 0000000000..187c9582d9
--- /dev/null
+++ b/packages/ai-harness/src/first-party/agents.ts
@@ -0,0 +1,353 @@
+import { defineAgent, maxIterations } from '@tanstack/ai'
+import { defineCommand } from '../commands'
+import { configOption } from '../config'
+import { definePlugin } from '../plugins'
+import { readMarkdownFiles } from './files'
+import { globToRegExp } from './glob'
+import { PermissionRules } from './permissions'
+import type {
+  AnyTextAdapter,
+  AnyTool,
+  ChatMiddleware,
+  ChatMiddlewareConfig,
+  KeyedAdapter,
+} from '@tanstack/ai'
+import type { FrontmatterValue } from './files'
+import type { PermissionRule } from './permissions'
+
+/** A named agent: its prompt, tools, model, rules, and step limit. */
+export interface AgentProfile {
+  name: string
+  /** What the agent does. The model reads it to pick a subagent. */
+  description: string
+  /**
+   * - `primary`: it answers the user's turns. Pick it with `/agent`.
+   * - `subagent`: the main model starts it with the `subagent` tool.
+   * - `all`: both.
+   */
+  mode: 'primary' | 'subagent' | 'all'
+  /**
+   * A model id. `agents({ adapter })` turns it into an adapter. Without it,
+   * a primary agent keeps the harness model, and a subagent uses the model
+   * of the main turn.
+   */
+  model?: string
+  /** System prompt text added to each turn of this agent. */
+  system?: string
+  /**
+   * The tools this agent can call, by name. A `*` matches any text, for
+   * example `todo_*`. Without it, the agent gets every tool.
+   */
+  tools?: ReadonlyArray<string>
+  /**
+   * Permission rules that count while this agent is the primary agent.
+   * `permissions()` reads them. They do not apply in a subagent run.
+   */
+  permissions?: ReadonlyArray<PermissionRule>
+  /**
+   * The most model calls with tools in one run. The next call gets no tool
+   * calls and a note to answer now, and then the run stops.
+   */
+  steps?: number
+  /**
+   * Leave it out of the `/agent` list and the `agent` setting. The model
+   * can still start it as a subagent.
+   */
+  hidden?: boolean
+}
+
+/** The tools that only read: files, search, the web, and questions. */
+const READ_TOOLS = [
+  'read_file',
+  'list_files',
+  'grep',
+  'webfetch',
+  'websearch',
+  'question',
+]
+
+/** The built-in agents: `build`, `plan`, `general`, and `explore`. */
+export const builtInAgents: ReadonlyArray<AgentProfile> = [
+  {
+    name: 'build',
+    description: 'Does the work: reads code, changes files, and runs commands.',
+    mode: 'primary',
+    system:
+      'You are the build agent. Do the task the user gives you. Read the code you need, change files, and run commands. Check your work before you say it is done.',
+  },
+  {
+    name: 'plan',
+    description: 'Reads the code and makes a plan. Does not change files.',
+    mode: 'primary',
+    tools: [...READ_TOOLS, 'todo_write'],
+    system:
+      'You are the plan agent. You can only read and search. Do not change files or run commands. Study the code, then give the user a clear plan in numbered steps.',
+  },
+  {
+    name: 'general',
+    description:
+      'Does a research or work task in many steps and reports back. Give it the full task.',
+    mode: 'subagent',
+    system:
+      'You are a general agent. Do the task you get in as many steps as it needs. Use your tools to search, read, and act. At the end, reply with a short report of what you found or did.',
+  },
+  {
+    name: 'explore',
+    description:
+      'Searches the code fast and reports what it finds. Read-only. Give it a question.',
+    mode: 'subagent',
+    tools: READ_TOOLS,
+    system:
+      'You are a fast search agent. Find the files and code that answer the question you get. Only read and search. Reply with the paths and a short note for each.',
+  },
+]
+
+const MODES = ['primary', 'subagent', 'all'] as const
+
+const MAX_STEPS_PROMPT =
+  'You reached the step limit. Do not call more tools. Answer now with what you have, and say what is left to do.'
+
+/** The tools whose name matches one of `patterns`. Without patterns, all of them. */
+function allowedTools<TTool extends { name: string }>(
+  tools: ReadonlyArray<TTool>,
+  patterns: ReadonlyArray<string> | undefined,
+) {
+  if (patterns === undefined) return [...tools]
+  const matchers = patterns.map((pattern) => globToRegExp(pattern))
+  return tools.filter((tool) =>
+    matchers.some((matcher) => matcher.test(tool.name)),
+  )
+}
+
+/**
+ * Apply a profile to each model call of a chat run: keep only its tools,
+ * and at its step limit, make one last call with no tool calls.
+ */
+function profileMiddleware(current: () => AgentProfile) {
+  const middleware: ChatMiddleware = {
+    name: 'tanstack/agents',
+    onConfig: (run, config) => {
+      if (run.phase !== 'init' && run.phase !== 'beforeModel') return
+      const { tools, steps } = current()
+      const isLastStep =
+        run.phase === 'beforeModel' &&
+        steps !== undefined &&
+        run.iteration >= steps
+      const update: Partial<ChatMiddlewareConfig> = {}
+      if (tools !== undefined) update.tools = allowedTools(config.tools, tools)
+      if (isLastStep) {
+        update.toolChoice = 'none'
+        update.systemPrompts = [...config.systemPrompts, MAX_STEPS_PROMPT]
+      }
+      return update
+    },
+    // After the last call, stop. The harness loop limit still applies.
+    onShouldContinue: (_run, state) => {
+      const { steps } = current()
+      return steps === undefined || state.iterationCount <= steps
+    },
+  }
+  return middleware
+}
+
+/** A profile from a Markdown file. The body is its system prompt. */
+function profileOfFile(file: {
+  name: string
+  fields: Record<string, FrontmatterValue>
+  body: string
+}) {
+  const text = (key: string) => {
+    const value = file.fields[key]
+    return typeof value === 'string' && value !== '' ? value : undefined
+  }
+  const fail = (key: string) => {
+    throw new Error(`Agent file ${file.name}.md: "${key}" is not valid.`)
+  }
+  const modeText = text('mode')
+  const mode =
+    modeText === undefined
+      ? 'all'
+      : (MODES.find((candidate) => candidate === modeText) ?? fail('mode'))
+  const stepsText = text('steps')
+  const steps = stepsText === undefined ? undefined : Number(stepsText)
+  if (steps !== undefined && !(Number.isInteger(steps) && steps >= 0)) {
+    fail('steps')
+  }
+  const model = text('model')
+  const { tools } = file.fields
+  const system = file.body.trim()
+  // ponytail: no `permissions` from files, the parser reads no nested values
+  const profile: AgentProfile = {
+    name: file.name,
+    description: text('description') ?? `The ${file.name} agent`,
+    mode,
+    ...(model !== undefined && { model }),
+    ...(system !== '' && { system }),
+    ...(tools !== undefined && {
+      tools: typeof tools === 'string' ? [tools] : tools,
+    }),
+    ...(steps !== undefined && { steps }),
+    ...(text('hidden') === 'true' && { hidden: true }),
+  }
+  return profile
+}
+
+/**
+ * Named agents, each with its own system prompt, tools, model, permission
+ * rules, and step limit.
+ *
+ * - A primary agent answers the user's turns. Switch it with
+ *   `/agent <name>` or the `agent` setting. It applies at the next turn.
+ * - A subagent is a child that the main model starts with the `subagent`
+ *   tool. For one `subagent` tool, give the harness
+ *   `subagents: { agents: [], tool: 'single' }`.
+ *
+ * The built-in agents are `build` (primary, the default, every tool),
+ * `plan` (primary, read-only tools), `general` (subagent, every tool), and
+ * `explore` (subagent, read-only tools). See {@link builtInAgents}.
+ *
+ * @param options.adapter - Turns a model id into an adapter: the `model` of
+ *   a profile, or for a subagent without one, the model id of the main turn.
+ *   A `keyedAdapter(...)` is built with the user's key.
+ * @param options.agents - More profiles. A profile replaces an earlier one
+ *   with the same name: built-ins first, then `dirs`, then `agents`.
+ * @param options.dirs - Folders of `*.md` agent files. The file name is the
+ *   agent name and the body is its system prompt. The frontmatter sets
+ *   `description`, `mode` (default `all`), `model`, `tools` (a list),
+ *   `steps`, and `hidden`.
+ * @param options.builtIns - `false` drops the built-in agents.
+ * @param options.default - The primary agent of a new session. Default: the
+ *   first primary agent, `build` with the built-ins.
+ *
+ * @example
+ * ```ts
+ * const models: Record<string, AnyTextAdapter> = {
+ *   'claude-sonnet-4-5': anthropicText('claude-sonnet-4-5'),
+ * }
+ * agents({
+ *   adapter: (model) => models[model] ?? openaiText('gpt-5.5'),
+ *   dirs: ['.agents/agents'],
+ * })
+ * ```
+ */
+export function agents(options: {
+  adapter: (model: string) => AnyTextAdapter | KeyedAdapter<AnyTextAdapter>
+  agents?: ReadonlyArray<AgentProfile>
+  dirs?: ReadonlyArray<string>
+  builtIns?: boolean
+  default?: string
+}) {
+  return definePlugin({
+    name: 'tanstack/agents',
+    setup: async (ctx) => {
+      const dirs = options.dirs ?? []
+      const files = (await Promise.all(dirs.map(readMarkdownFiles))).flat()
+      const all = [
+        ...(options.builtIns === false ? [] : builtInAgents),
+        ...files.map(profileOfFile),
+        ...(options.agents ?? []),
+      ]
+      // A later profile replaces an earlier one and keeps its place.
+      const profiles = [
+        ...new Map(all.map((profile) => [profile.name, profile])).values(),
+      ]
+      const visible = profiles.filter(
+        (profile) => profile.mode !== 'subagent' && !profile.hidden,
+      )
+      const names = visible.map((profile) => profile.name)
+      const first = visible.find(
+        (profile) => profile.name === (options.default ?? names[0]),
+      )
+      if (!first) {
+        throw new Error(
+          'agents(): `default` must name a primary agent that is not hidden.',
+        )
+      }
+      const active = () => {
+        const name = ctx.config.get('agent')
+        return visible.find((profile) => profile.name === name) ?? first
+      }
+      // The tools and the model id of the last main turn. Subagents use them.
+      // ponytail: a subagent started before any turn has no tools and needs a `model`
+      let lead: { tools: ReadonlyArray<AnyTool>; model: string } | undefined
+
+      const subagentOf = (profile: AgentProfile) =>
+        defineAgent({
+          name: profile.name,
+          description: profile.description,
+          run: async (child) => {
+            const model = profile.model ?? lead?.model
+            if (model === undefined) {
+              throw new Error(
+                `Agent ${profile.name} has no model. Give it a model, or start it from a turn.`,
+              )
+            }
+            return child.chat({
+              adapter: await child.keys.adapter(options.adapter(model)),
+              tools: allowedTools(lead?.tools ?? [], profile.tools),
+              systemPrompts:
+                profile.system === undefined ? [] : [profile.system],
+              middleware: [profileMiddleware(() => profile)],
+              // The harness main loop has the same limit. chat() alone stops at 5 calls.
+              agentLoopStrategy: maxIterations(50),
+            })
+          },
+        })
+
+      // A profile's rules count only while it is the primary agent. At other
+      // times the getter gives a tool name that matches no tool.
+      // ponytail: subagent runs get no profile rules, that needs the run in PermissionRules
+      const rules = profiles.flatMap((profile) =>
+        (profile.permissions ?? []).map((rule) =>
+          PermissionRules.item({
+            ...rule,
+            get tool() {
+              return active().name === profile.name ? rule.tool : ''
+            },
+          }),
+        ),
+      )
+
+      return {
+        config: {
+          agent: configOption.select({
+            options: names,
+            default: first.name,
+            description: 'The primary agent',
+          }),
+        },
+        commands: {
+          agent: defineCommand({
+            description: `Show or switch the primary agent (${names.join(', ')})`,
+            run: async (input: unknown) => {
+              const name = typeof input === 'string' ? input.trim() : ''
+              const list = `Agents: ${names.join(', ')}.`
+              if (name === '') return `Agent: ${active().name}. ${list}`
+              const receipt = await ctx.session.setConfig('agent', name)
+              return receipt.status === 'rejected'
+                ? `Unknown agent "${name}". ${list}`
+                : `Agent: ${name}. It applies at the next turn.`
+            },
+          }),
+        },
+        prompts: [
+          { id: 'tanstack/agents:system', text: () => active().system ?? '' },
+        ],
+        adapter: () => {
+          const { model } = active()
+          return model === undefined ? undefined : options.adapter(model)
+        },
+        prepareTools: ({ tools, model }) => {
+          lead = { tools, model }
+          return tools
+        },
+        // In onConfig, so the `subagent` tool that chat() adds is filtered too.
+        middleware: [profileMiddleware(active)],
+        subagents: profiles
+          .filter((profile) => profile.mode !== 'primary')
+          .map(subagentOf),
+        contribute: rules,
+      }
+    },
+  })
+}
diff --git a/packages/ai-harness/src/first-party/coding/backend.ts b/packages/ai-harness/src/first-party/coding/backend.ts
index d033de3838..9a68a7bfb1 100644
--- a/packages/ai-harness/src/first-party/coding/backend.ts
+++ b/packages/ai-harness/src/first-party/coding/backend.ts
@@ -1,6 +1,6 @@
 import * as childProcess from 'node:child_process'
 import * as fs from 'node:fs/promises'
-import { dirname } from 'node:path'
+import * as nodePath from 'node:path'
 import { isRecord } from '../../utils'
 import type { WorkspaceHooks } from '../workspace-hooks'
 
@@ -10,20 +10,44 @@ import type { WorkspaceHooks } from '../workspace-hooks'
  * example a sandbox, lets the same tools work there.
  */
 export interface WorkspaceBackend {
+  /**
+   * The shell that runs the commands: `'sh'` (a POSIX shell) or `'cmd'`
+   * (Windows `cmd.exe`). The tools quote arguments for it. It also sets the
+   * path style: POSIX paths for `'sh'`, Windows paths for `'cmd'`. Without
+   * it, arguments are quoted for `sh`, and paths have the style of this
+   * machine. A Linux sandbox sets `'sh'`, so its root `/workspace` stays a
+   * POSIX path on a Windows host.
+   */
+  shell?: 'sh' | 'cmd'
   /** The bytes of a file. Throws when there is no file. */
   readFile: (path: string) => Promise<Uint8Array>
   /** Create or replace a file. Missing parent folders are created. */
   writeFile: (path: string, data: Uint8Array | string) => Promise<void>
+  /**
+   * Remove one file. Throws when there is no file, or for a folder. Optional:
+   * without it, the `patch` tool cannot delete or move files.
+   */
+  remove?: (path: string) => Promise<void>
   /** A file or a folder, or `undefined` when nothing is at `path`. */
   stat: (
     path: string,
   ) => Promise<
     { type: 'file' | 'dir'; size: number; mtimeMs: number } | undefined
   >
-  /** The entries of a folder. */
+  /**
+   * The real path of `path`, with every link resolved, or `undefined` when
+   * nothing is at `path`. Throws for a link to a target that is not there.
+   * The tools use it to refuse a link that leads out of the workspace.
+   * Optional: without it, the tools do not check links.
+   */
+  realpath?: (path: string) => Promise<string | undefined>
+  /**
+   * The entries of a folder. A symbolic link (or a Windows junction) has
+   * the type `'link'`, whatever it points to. The tools do not follow it.
+   */
   readdir: (
     path: string,
-  ) => Promise<Array<{ name: string; type: 'file' | 'dir' }>>
+  ) => Promise<Array<{ name: string; type: 'file' | 'dir' | 'link' }>>
   /**
    * Run a shell command and wait for it to end. `env` is added to the
    * environment. A command that fails resolves with its exit code.
@@ -62,7 +86,8 @@ export interface ToolEnv {
   lock: <T>(path: string, fn: () => Promise<T>) => Promise<T>
   /**
    * The absolute path of `path`, a file or a folder. A path outside the
-   * workspace is refused, or needs the user's yes for its folder.
+   * workspace is refused, or needs the user's yes for its folder. The check
+   * uses the real path, so a link that leads out counts as outside.
    */
   reach: (
     path: string,
@@ -73,25 +98,89 @@ export interface ToolEnv {
   shown: (full: string) => string
 }
 
+/**
+ * The path functions for the paths of `backend`: POSIX for a `'sh'`
+ * backend, Windows for a `'cmd'` backend. Without `shell`, the functions of
+ * this machine.
+ */
+export function pathsOf(backend: WorkspaceBackend) {
+  switch (backend.shell) {
+    case 'sh':
+      return nodePath.posix
+    case 'cmd':
+      return nodePath.win32
+    case undefined:
+      return nodePath
+  }
+}
+
 /** `env` added to the environment of this process. */
 const withEnv = (env: Record<string, string> | undefined) =>
   env && { ...process.env, ...env }
 
+/** True for the error of a path that is not there. */
+const isMissing = (error: unknown) =>
+  error instanceof Error && 'code' in error && error.code === 'ENOENT'
+
+/** `exec` stops a command that writes more than 10 MiB of output. */
+const MAX_EXEC_OUTPUT = 10 * 1024 * 1024
+
+/**
+ * Start `command` in the system shell. `kill` stops the shell and every
+ * command it started: on Windows, a killed `cmd.exe` leaves its commands
+ * running.
+ */
+function startShell(
+  command: string,
+  options: { cwd?: string; env?: Record<string, string> },
+) {
+  const isWindows = process.platform === 'win32'
+  // Off Windows, the command gets its own process group, so `kill` can
+  // stop the commands it started too.
+  const child = childProcess.spawn(command, {
+    cwd: options.cwd,
+    env: withEnv(options.env),
+    shell: true,
+    detached: !isWindows,
+  })
+  const kill = () => {
+    if (child.pid === undefined) return
+    if (isWindows) {
+      childProcess.execFile(
+        'taskkill',
+        ['/pid', String(child.pid), '/T', '/F'],
+        () => undefined,
+      )
+      return
+    }
+    try {
+      process.kill(-child.pid, 'SIGTERM')
+    } catch {
+      // The command already ended.
+    }
+  }
+  return { child, kill }
+}
+
 /**
  * The workspace on this machine, with `node:fs` and `node:child_process`.
- * Commands run in the system shell.
+ * Commands run in the system shell. `exec` gives exit code 124, like GNU
+ * `timeout`, when the timeout stops a command or the output is over 10 MiB.
+ * It gives 1 when the signal stops a command, or the command did not
+ * start. A stopped command is stopped with every command it started.
  */
 export const hostBackend = {
+  shell: process.platform === 'win32' ? 'cmd' : 'sh',
   readFile: (path) => fs.readFile(path),
   writeFile: async (path, data) => {
-    await fs.mkdir(dirname(path), { recursive: true })
+    await fs.mkdir(nodePath.dirname(path), { recursive: true })
     await fs.writeFile(path, data)
   },
+  // Without `recursive`, `fs.rm` refuses a folder.
+  remove: (path) => fs.rm(path),
   stat: async (path) => {
     const info = await fs.stat(path).catch((error: unknown) => {
-      const isMissing =
-        error instanceof Error && 'code' in error && error.code === 'ENOENT'
-      if (isMissing) return undefined
+      if (isMissing(error)) return undefined
       throw error
     })
     if (!info) return undefined
@@ -101,38 +190,75 @@ export const hostBackend = {
       mtimeMs: info.mtimeMs,
     }
   },
+  realpath: async (path) => {
+    try {
+      return await fs.realpath(path)
+    } catch (error) {
+      // A link to a missing target is there, so it is not `undefined`.
+      const isThere = await fs.lstat(path).then(
+        () => true,
+        () => false,
+      )
+      if (isMissing(error) && !isThere) return undefined
+      throw error
+    }
+  },
   readdir: async (path) => {
     const entries = await fs.readdir(path, { withFileTypes: true })
     return entries.map((entry) => ({
       name: entry.name,
-      type: entry.isDirectory() ? ('dir' as const) : ('file' as const),
+      type: entry.isSymbolicLink()
+        ? ('link' as const)
+        : entry.isDirectory()
+          ? ('dir' as const)
+          : ('file' as const),
     }))
   },
   exec: (command, options = {}) =>
     new Promise((done) => {
-      childProcess.exec(
-        command,
-        {
-          cwd: options.cwd,
-          env: withEnv(options.env),
-          timeout: options.timeoutMs,
-          signal: options.signal,
-          maxBuffer: 10 * 1024 * 1024,
-        },
-        (error, stdout, stderr) =>
-          done({ exitCode: error?.code ?? 0, stdout, stderr }),
-      )
+      const { child, kill } = startShell(command, options)
+      const stdout: Array<Buffer> = []
+      const stderr: Array<Buffer> = []
+      let size = 0
+      // The exit code of a command that was stopped. The first reason wins.
+      let stoppedWith: number | undefined
+      const stop = (exitCode: number) => {
+        stoppedWith ??= exitCode
+        kill()
+      }
+      const collect = (chunks: Array<Buffer>) => (chunk: Buffer) => {
+        chunks.push(chunk)
+        size += chunk.length
+        if (size > MAX_EXEC_OUTPUT) stop(124)
+      }
+      child.stdout.on('data', collect(stdout))
+      child.stderr.on('data', collect(stderr))
+      // A timeout of 0 means no timeout.
+      const timer = options.timeoutMs
+        ? setTimeout(() => stop(124), options.timeoutMs)
+        : undefined
+      const onAbort = () => stop(1)
+      options.signal?.addEventListener('abort', onAbort)
+      if (options.signal?.aborted) onAbort()
+      let startError = ''
+      // Runs on `close`, and on `error` when the command did not start.
+      const finish = (code: number | null) => {
+        clearTimeout(timer)
+        options.signal?.removeEventListener('abort', onAbort)
+        done({
+          exitCode: stoppedWith ?? code ?? 1,
+          stdout: Buffer.concat(stdout).toString(),
+          stderr: Buffer.concat(stderr).toString() + startError,
+        })
+      }
+      child.on('close', finish)
+      child.on('error', (error) => {
+        startError = String(error)
+        finish(1)
+      })
     }),
   spawn: (command, options = {}) => {
-    const isWindows = process.platform === 'win32'
-    // Off Windows, the command gets its own process group, so `kill` can
-    // stop the commands it started too.
-    const child = childProcess.spawn(command, {
-      cwd: options.cwd,
-      env: withEnv(options.env),
-      shell: true,
-      detached: !isWindows,
-    })
+    const { child, kill } = startShell(command, options)
     // ponytail: keeps all output in memory. Cap it if long jobs need that.
     let output = ''
     const collect = (chunk: Buffer) => {
@@ -147,23 +273,6 @@ export const hostBackend = {
         done({ exitCode: 1 })
       })
     })
-    const kill = () => {
-      if (child.pid === undefined) return
-      // Stop the shell and every command it started.
-      if (isWindows) {
-        childProcess.execFile(
-          'taskkill',
-          ['/pid', String(child.pid), '/T', '/F'],
-          () => undefined,
-        )
-        return
-      }
-      try {
-        process.kill(-child.pid, 'SIGTERM')
-      } catch {
-        // The command already ended.
-      }
-    }
     return { wait: () => exited, kill, output: () => output }
   },
 } satisfies WorkspaceBackend
diff --git a/packages/ai-harness/src/first-party/coding/formatter.ts b/packages/ai-harness/src/first-party/coding/formatter.ts
new file mode 100644
index 0000000000..215f0fdda2
--- /dev/null
+++ b/packages/ai-harness/src/first-party/coding/formatter.ts
@@ -0,0 +1,242 @@
+import { extname, join, resolve } from 'node:path'
+import { createPluginEvent } from '../../extensions'
+import { definePlugin } from '../../plugins'
+import { isRecord } from '../../utils'
+import { WorkspaceHooks } from '../workspace-hooks'
+import { hostBackend, readText } from './backend'
+import { quoteArg } from './search'
+import type { WorkspaceBackend } from './backend'
+
+/** What a formatter can check in the project root folder. */
+export interface FormatterProject {
+  /** The names of the files and folders in the root folder. */
+  files: ReadonlyArray<string>
+  /** The text of the file `name` in the root folder, or `''` without one. */
+  read: (name: string) => Promise<string>
+}
+
+/** A formatter CLI for some file types. */
+export interface Formatter {
+  /** A short name, for the warning when it fails. */
+  name: string
+  /** The file extensions it formats, with the dot, like `'.ts'`. */
+  extensions: ReadonlyArray<string>
+  /**
+   * The shell command that formats `file` in place. `file` is the absolute
+   * path, already quoted for the shell. Put it in the command as it is.
+   */
+  command: (file: string) => string
+  /** Does the project use this formatter? Default: yes. */
+  when?: (project: FormatterProject) => boolean | Promise<boolean>
+}
+
+export interface FormatterOptions {
+  /** The workspace folder. Commands run in it. */
+  root: string
+  /** Where the files are and commands run. Default: {@link hostBackend}. */
+  backend?: WorkspaceBackend
+  /** Your formatters. They come before the built-in formatters. */
+  formatters?: ReadonlyArray<Formatter>
+  /** `false` turns the built-in formatters off. Default: `true`. */
+  builtins?: boolean
+  /** The time limit of each run. Default: 20 seconds. */
+  timeoutMs?: number
+}
+
+/** A formatter run that failed. The written file stays as it was. */
+export interface FormatFailure {
+  /** The absolute path of the file. */
+  path: string
+  message: string
+}
+
+/** Sent when a formatter fails. The tool call does not fail. */
+export const FormatFailed = createPluginEvent<FormatFailure>(
+  'tanstack/formatter:failed',
+)
+
+const SCRIPT = ['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.mts', '.cts']
+/** The file types that prettier and oxfmt format. */
+const WEB = [
+  ...SCRIPT,
+  ...['.json', '.jsonc', '.css', '.scss', '.less', '.html', '.vue'],
+  ...['.md', '.mdx', '.yaml', '.yml', '.graphql'],
+]
+
+/** The field `key` of the project's `package.json`, or `undefined`. */
+async function packageField(project: FormatterProject, key: string) {
+  try {
+    const value: unknown = JSON.parse(await project.read('package.json'))
+    return isRecord(value) ? value[key] : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** Does a name in the root folder start with one of the `prefixes`? */
+const hasFile = (project: FormatterProject, ...prefixes: Array<string>) =>
+  project.files.some((name) =>
+    prefixes.some((prefix) => name.startsWith(prefix)),
+  )
+
+// ponytail: six built-in formatters. Add more with `formatters`.
+const BUILTINS: ReadonlyArray<Formatter> = [
+  {
+    name: 'prettier',
+    extensions: WEB,
+    command: (file) => `npx --no-install prettier --write ${file}`,
+    when: async (project) =>
+      hasFile(project, '.prettierrc', 'prettier.config.') ||
+      (await packageField(project, 'prettier')) !== undefined,
+  },
+  {
+    name: 'biome',
+    extensions: [...SCRIPT, '.json', '.jsonc', '.css', '.graphql'],
+    command: (file) => `npx --no-install biome format --write ${file}`,
+    when: (project) =>
+      project.files.includes('biome.json') ||
+      project.files.includes('biome.jsonc'),
+  },
+  {
+    name: 'oxfmt',
+    extensions: WEB,
+    command: (file) => `npx --no-install oxfmt ${file}`,
+    when: async (project) => {
+      const devDependencies = await packageField(project, 'devDependencies')
+      return (
+        hasFile(project, '.oxfmtrc') ||
+        (isRecord(devDependencies) && 'oxfmt' in devDependencies)
+      )
+    },
+  },
+  {
+    name: 'ruff',
+    extensions: ['.py', '.pyi'],
+    command: (file) => `ruff format ${file}`,
+    when: async (project) =>
+      project.files.includes('ruff.toml') ||
+      project.files.includes('.ruff.toml') ||
+      (await project.read('pyproject.toml')).includes('[tool.ruff'),
+  },
+  {
+    name: 'gofmt',
+    extensions: ['.go'],
+    command: (file) => `gofmt -w ${file}`,
+    when: (project) => project.files.includes('go.mod'),
+  },
+  {
+    name: 'rustfmt',
+    extensions: ['.rs'],
+    command: (file) => `rustfmt ${file}`,
+    when: (project) => project.files.includes('Cargo.toml'),
+  },
+]
+
+const messageOf = (error: unknown) =>
+  error instanceof Error ? error.message : String(error)
+
+/**
+ * The `afterWrite` hook of {@link formatter}. It runs the first formatter
+ * that the project uses for the file type. The project is checked at the
+ * first write, once. A failure goes to `onFailure` and never throws.
+ */
+export function formatOnWrite(
+  options: FormatterOptions,
+  onFailure: (failure: FormatFailure) => void,
+) {
+  const root = resolve(options.root)
+  const backend = options.backend ?? hostBackend
+  const timeoutMs = options.timeoutMs ?? 20_000
+  // ponytail: the same rule as search.ts. A backend other than the host is
+  // taken to have a POSIX `sh`, like a Linux sandbox.
+  const platform = backend === hostBackend ? process.platform : 'linux'
+  const candidates = [
+    ...(options.formatters ?? []),
+    ...(options.builtins === false ? [] : BUILTINS),
+  ]
+
+  /** The formatters that the project uses, in order. */
+  const detect = async () => {
+    const entries = await backend.readdir(root)
+    const project: FormatterProject = {
+      files: entries.map((entry) => entry.name),
+      read: (name) => readText(backend, join(root, name)).catch(() => ''),
+    }
+    const used = await Promise.all(
+      candidates.map((candidate) => candidate.when?.(project) ?? true),
+    )
+    return candidates.filter((_, index) => used[index])
+  }
+  let detected: ReturnType<typeof detect> | undefined
+
+  const format = async (path: string) => {
+    const extension = extname(path).toLowerCase()
+    const formatters = await (detected ??= detect())
+    const match = formatters.find((candidate) =>
+      candidate.extensions.includes(extension),
+    )
+    if (!match) return
+    const command = match.command(quoteArg(path, platform))
+    const result = await backend.exec(command, { cwd: root, timeoutMs })
+    if (result.exitCode === 0) return
+    const reason =
+      result.exitCode === 124
+        ? `it took longer than ${timeoutMs / 1000} seconds`
+        : result.stderr.trim().split('\n')[0] || `exit code ${result.exitCode}`
+    throw new Error(`${match.name} failed: ${reason}`)
+  }
+
+  return (path: string) =>
+    format(path).catch((error: unknown) =>
+      onFailure({ path, message: messageOf(error) }),
+    )
+}
+
+/**
+ * Format each file that `write_file`, `edit_file`, and `patch` write, with
+ * the formatter that the project uses for its file type. Use it with
+ * `workspaceTools`.
+ *
+ * At the first write in a session, the plugin checks the config files in
+ * `root`, and keeps the result:
+ *
+ * - prettier: `.prettierrc*`, `prettier.config.*`, or `prettier` in
+ *   `package.json`.
+ * - biome: `biome.json` or `biome.jsonc`.
+ * - oxfmt: `.oxfmtrc*`, or `oxfmt` in the `devDependencies`.
+ * - ruff (`.py`): `ruff.toml`, or `[tool.ruff]` in `pyproject.toml`.
+ * - gofmt (`.go`): `go.mod`. rustfmt (`.rs`): `Cargo.toml`.
+ *
+ * Your `formatters` come first. `builtins: false` turns the list above off.
+ * Each run is a command through `backend.exec` in `root`, with a time limit
+ * (`timeoutMs`, default 20 seconds). A formatter that fails, times out, or
+ * is not installed does not fail the tool call: the file stays as written,
+ * and the plugin sends a {@link FormatFailed} event.
+ *
+ * @example
+ * ```ts
+ * plugins: () => [
+ *   workspaceTools({ root }),
+ *   formatter({
+ *     root,
+ *     formatters: [
+ *       { name: 'taplo', extensions: ['.toml'], command: (file) => `taplo fmt ${file}` },
+ *     ],
+ *   }),
+ * ]
+ * ```
+ */
+export function formatter(options: FormatterOptions) {
+  return definePlugin({
+    name: 'tanstack/formatter',
+    setup: (ctx) => ({
+      contribute: [
+        WorkspaceHooks.item({
+          afterWrite: formatOnWrite(options, (failure) =>
+            ctx.emit(FormatFailed, failure),
+          ),
+        }),
+      ],
+    }),
+  })
+}
diff --git a/packages/ai-harness/src/first-party/coding/patch.ts b/packages/ai-harness/src/first-party/coding/patch.ts
index 915d25a031..5255e82597 100644
--- a/packages/ai-harness/src/first-party/coding/patch.ts
+++ b/packages/ai-harness/src/first-party/coding/patch.ts
@@ -301,46 +301,97 @@ function applyChunks(
 }
 
 /**
- * Apply each operation to its absolute path `full`. Every file is read and
- * checked first. The files are written only when every operation fits.
+ * One operation with its absolute paths. `to` is the move target, or `full`
+ * when the file does not move.
  */
-async function applyAll(
-  env: ToolEnv,
-  steps: ReadonlyArray<{ operation: PatchOperation; full: string }>,
-) {
-  // The new text of each file. A later operation on a file sees it.
-  const planned = new Map<string, string>()
+interface Step {
+  operation: PatchOperation
+  full: string
+  to: string
+}
+
+/**
+ * Apply each step. Every file is read and checked first. The files are
+ * written and removed only when every operation fits. Then the `afterWrite`
+ * hooks run for the written files.
+ */
+async function applyAll(env: ToolEnv, steps: ReadonlyArray<Step>) {
+  const { backend } = env
+  // The new state of each file: its text, or `null` to remove it. A later
+  // operation on a file sees it. A removed file is always a file that was
+  // there before the patch.
+  const planned = new Map<string, string | null>()
   const changes: Array<string> = []
-  for (const { operation, full } of steps) {
+  for (const { operation, full, to } of steps) {
     const shown = env.shown(full)
     switch (operation.type) {
       case 'add':
         planned.set(full, operation.content)
         changes.push(`added ${shown}`)
         break
-      case 'update': {
-        // ponytail: WorkspaceBackend cannot remove a file, so a move or a
-        // delete is refused. Add them when the backend can remove files.
-        if (operation.movePath !== undefined) {
+      case 'delete': {
+        if (!backend.remove) {
+          throw new Error(
+            `Cannot delete ${shown}: the workspace cannot remove files.`,
+          )
+        }
+        if (planned.has(full)) {
           throw new Error(
-            `Cannot move ${shown}: the workspace cannot remove files.`,
+            `Cannot delete ${shown}: the patch changes it before.`,
           )
         }
-        const before =
-          planned.get(full) ?? (await readText(env.backend, full))
-        planned.set(full, applyChunks(before, operation.chunks, shown))
-        changes.push(`updated ${shown}`)
+        const isFile = (await backend.stat(full))?.type === 'file'
+        if (!isFile) throw new Error(`Cannot delete ${shown}: no such file.`)
+        planned.set(full, null)
+        changes.push(`deleted ${shown}`)
         break
       }
-      case 'delete':
-        throw new Error(
-          `Cannot delete ${shown}: the workspace cannot remove files.`,
+      case 'update': {
+        const isMove = to !== full
+        const toShown = env.shown(to)
+        if (isMove) {
+          if (!backend.remove) {
+            throw new Error(
+              `Cannot move ${shown}: the workspace cannot remove files.`,
+            )
+          }
+          if (planned.has(full)) {
+            throw new Error(`Cannot move ${shown}: the patch changes it before.`)
+          }
+          // The target must be free: no file, or a file that the patch
+          // removes before.
+          const isFree =
+            planned.get(to) === null ||
+            (!planned.has(to) && (await backend.stat(to)) === undefined)
+          if (!isFree) {
+            throw new Error(
+              `Cannot move ${shown} to ${toShown}: ${toShown} already exists.`,
+            )
+          }
+        }
+        const known = planned.get(full)
+        if (known === null) {
+          throw new Error(`Cannot update ${shown}: the patch removes it before.`)
+        }
+        const before = known ?? (await readText(backend, full))
+        planned.set(to, applyChunks(before, operation.chunks, shown))
+        if (isMove) planned.set(full, null)
+        changes.push(
+          isMove ? `moved ${shown} to ${toShown}` : `updated ${shown}`,
         )
+        break
+      }
     }
   }
   const files = [...planned]
-  for (const [full, text] of files) await env.backend.writeFile(full, text)
-  for (const [full] of files) await afterWrite(env, full)
+  const written = files.flatMap(([full, text]) =>
+    text === null ? [] : [{ full, text }],
+  )
+  const removed = files.flatMap(([full, text]) => (text === null ? [full] : []))
+  for (const { full, text } of written) await backend.writeFile(full, text)
+  // The checks above refuse a removal when the backend has no `remove`.
+  for (const full of removed) await backend.remove?.(full)
+  for (const { full } of written) await afterWrite(env, full)
   return ['Applied the patch:', ...changes].join('\n')
 }
 
@@ -350,6 +401,15 @@ async function applyAll(
  * {@link findMatches}. All files are checked before the first write, so a
  * patch that does not fit changes nothing. The `afterWrite` hooks run for
  * each written file. The result lists the changed files.
+ *
+ * - `*** Add File:` replaces a file that is there, like `write_file`.
+ * - `*** Delete File:` needs a file there.
+ * - `*** Move to:` writes the new path, then removes the old one. It refuses
+ *   a target that is already there, unless the patch removes it first.
+ * - A delete or a move needs `remove` on the backend. Without it, the tool
+ *   refuses them, before it writes anything.
+ * - A file that the patch removed or moved away cannot change again in the
+ *   same patch. A file cannot be removed or moved after the patch changed it.
  */
 export function patchTools(env: ToolEnv) {
   return [
@@ -365,14 +425,22 @@ export function patchTools(env: ToolEnv) {
       const operations = parsePatch(stringArg(args, 'patch'))
       // Resolve each path first. A path outside the workspace can ask the
       // user.
-      const steps: Array<{ operation: PatchOperation; full: string }> = []
+      const steps: Array<Step> = []
       for (const operation of operations) {
         const full = await env.reach(operation.path, 'patch', 'file')
-        steps.push({ operation, full })
+        const movePath =
+          operation.type === 'update' ? operation.movePath : undefined
+        const to =
+          movePath === undefined
+            ? full
+            : await env.reach(movePath, 'patch', 'file')
+        steps.push({ operation, full, to })
       }
       // Hold the lock of every file, taken in one fixed order, so two
       // patches cannot wait for each other.
-      const paths = [...new Set(steps.map((step) => step.full))].sort()
+      const paths = [
+        ...new Set(steps.flatMap((step) => [step.full, step.to])),
+      ].sort()
       let run = () => applyAll(env, steps)
       for (const path of paths) {
         const inner = run
diff --git a/packages/ai-harness/src/first-party/coding/read.ts b/packages/ai-harness/src/first-party/coding/read.ts
index c182e3eccc..d0f2d0e173 100644
--- a/packages/ai-harness/src/first-party/coding/read.ts
+++ b/packages/ai-harness/src/first-party/coding/read.ts
@@ -1,26 +1,150 @@
+import { dirname, join, parse } from 'node:path'
 import { toolDefinition } from '@tanstack/ai'
+import { toBase64 } from '../../media'
+import { mimeTypeOf } from '../../media-ref'
 import { isRecord } from '../../utils'
-import { clip, readText, stringArg } from './backend'
+import { stringArg } from './backend'
+import type { ContentPart } from '@tanstack/ai'
 import type { ToolEnv } from './backend'
 
-const MAX_READ_LINES = 2000
+// The page limits stay inside the defaults of `boundToolOutput` (2000 lines,
+// 50 KiB), so that plugin does not cut a page again.
+const MAX_LINES = 2000
+const MAX_PAGE_BYTES = 50 * 1024
+const MAX_LINE_CHARS = 2000
+// A NUL byte in this many first bytes marks a binary file.
+const BINARY_CHECK_BYTES = 8 * 1024
+// ponytail: media goes to the model as inline base64, and it stays in the
+// transcript. Store it as harness media if big files make turns too large.
+const MAX_MEDIA_BYTES = 5 * 1024 * 1024
+const MAX_SUGGESTIONS = 3
+
+// The first bytes of the files that go to the model as media parts. The
+// bytes decide, not the extension: a Git LFS pointer named `x.png` is text.
+const MEDIA = [
+  { type: 'image', mimeType: 'image/png', signature: /^\x89PNG/ },
+  { type: 'image', mimeType: 'image/jpeg', signature: /^\xff\xd8\xff/ },
+  { type: 'image', mimeType: 'image/gif', signature: /^GIF8/ },
+  { type: 'image', mimeType: 'image/webp', signature: /^RIFF[\s\S]{4}WEBP/ },
+  { type: 'document', mimeType: 'application/pdf', signature: /^%PDF-/ },
+] as const
+
+// The default decoder drops a byte order mark, so the model does not see
+// it. `edit_file` keeps the mark in the file.
+const decoder = new TextDecoder()
+const encoder = new TextEncoder()
+
+/** The edit distance of `a` and `b`: the fewest one-character changes. */
+function distance(a: string, b: string) {
+  // `row[j]` is the distance of the first i characters of `a` and the first
+  // j characters of `b`. Each pass over `a` makes the next row.
+  let row = Array.from({ length: b.length + 1 }, (_, j) => j)
+  for (let i = 0; i < a.length; i++) {
+    let diagonal = i
+    let left = i + 1
+    row = row.map((above, j) => {
+      if (j === 0) return left
+      const cost = a[i] === b[j - 1] ? 0 : 1
+      left = Math.min(above + 1, left + 1, diagonal + cost)
+      diagonal = above
+      return left
+    })
+  }
+  return row.at(-1) ?? 0
+}
+
+/**
+ * The error for a file that does not exist. It names up to 3 files in the
+ * same folder with a similar name: the same name in other letter case, the
+ * same name with another extension, or a name 2 or fewer changes away.
+ */
+async function notFound(env: ToolEnv, full: string) {
+  const folder = dirname(full)
+  const wanted = parse(full).base.toLowerCase()
+  const wantedStem = parse(wanted).name
+  // A missing folder has no names to suggest.
+  const entries = await env.backend.readdir(folder).catch(() => [])
+  const similar = entries
+    .filter((entry) => entry.type === 'file')
+    .map((entry) => {
+      const name = entry.name.toLowerCase()
+      const isSameStem = parse(name).name === wantedStem
+      return { name: entry.name, isSameStem, distance: distance(name, wanted) }
+    })
+    .filter((item) => item.isSameStem || item.distance <= 2)
+    .sort((a, b) => a.distance - b.distance)
+    .slice(0, MAX_SUGGESTIONS)
+    .map((item) => env.shown(join(folder, item.name)))
+  const message = `File not found: ${env.shown(full)}.`
+  return new Error(
+    similar.length > 0
+      ? `${message} Did you mean ${similar.join(', ')}?`
+      : message,
+  )
+}
+
+/** `line` with its number. A line over 2000 characters is cut. */
+function numbered(lineNumber: number, line: string) {
+  const isLong = line.length > MAX_LINE_CHARS
+  const text = isLong
+    ? `${line.slice(0, MAX_LINE_CHARS)}... [line cut: ${line.length - MAX_LINE_CHARS} more characters]`
+    : line
+  return `${lineNumber}\t${text}`
+}
+
+/**
+ * The numbered lines from line `offset`, at most `limit` lines (2000 when
+ * `limit` is not set) and 50 KiB. When the page shows fewer lines than were
+ * asked for and the file goes on, a note says how to read the next page.
+ */
+function page(
+  text: string,
+  options: { path: string; offset: number; limit: number | undefined },
+) {
+  const { path, offset, limit } = options
+  const lines = text.split('\n')
+  // A final newline ends the last line. It does not start a new one.
+  if (text.endsWith('\n')) lines.pop()
+  const window = lines.slice(
+    offset - 1,
+    offset - 1 + Math.min(limit ?? MAX_LINES, MAX_LINES),
+  )
+  const shown: Array<string> = []
+  let bytes = 0
+  for (const [index, line] of window.entries()) {
+    const row = numbered(offset + index, line)
+    // One line is at most about 8 KB, so the first line always fits.
+    bytes += encoder.encode(row).length + 1
+    if (bytes > MAX_PAGE_BYTES) break
+    shown.push(row)
+  }
+  if (shown.length === 0) {
+    return `[No lines from line ${offset}. ${path} has ${lines.length} lines.]`
+  }
+  const last = offset + shown.length - 1
+  const isCut = shown.length < (limit ?? Infinity) && last < lines.length
+  if (!isCut) return shown.join('\n')
+  return `${shown.join('\n')}\n\n[Showing lines ${offset}-${last} of ${lines.length}. Read more with offset ${last + 1}.]`
+}
 
 /**
- * `read_file`: numbered lines of a text file. The text that `afterRead`
- * hooks return is added after the lines.
+ * `read_file`: numbered lines of a text file, a page at a time. An image
+ * (PNG, JPEG, GIF, WebP) or a PDF comes back as a content part. A binary
+ * file gets a short note, not its bytes. The text that `afterRead` hooks
+ * return is added after the lines of a text file.
  */
 export function readTools(env: ToolEnv) {
   return [
     toolDefinition({
       name: 'read_file',
       description:
-        'Read a text file in the workspace. Lines are numbered from 1.',
+        'Read a file in the workspace. Text comes back as lines numbered from 1, at most 2000 lines or 50 KiB a page. Use offset and limit to read other lines. Images (PNG, JPEG, GIF, WebP) and PDFs up to 5 MB come back as media.',
       inputSchema: {
         type: 'object',
         properties: {
           path: { type: 'string' },
           offset: { type: 'number', description: 'First line, from 1' },
-          limit: { type: 'number' },
+          limit: { type: 'number', description: 'Most lines to read' },
         },
         required: ['path'],
       },
@@ -34,17 +158,37 @@ export function readTools(env: ToolEnv) {
       const limit =
         isRecord(args) && typeof args.limit === 'number'
           ? args.limit
-          : MAX_READ_LINES
+          : undefined
       return env.lock(full, async () => {
-        const lines = (await readText(env.backend, full)).split('\n')
-        const parts = [
-          clip(
-            lines
-              .slice(offset - 1, offset - 1 + limit)
-              .map((line, index) => `${offset + index}\t${line}`)
-              .join('\n'),
-          ),
-        ]
+        const path = env.shown(full)
+        if (!(await env.backend.stat(full))) throw await notFound(env, full)
+        const bytes = await env.backend.readFile(full)
+        const head = String.fromCharCode(...bytes.subarray(0, 12))
+        const media = MEDIA.find((item) => item.signature.test(head))
+        if (media) {
+          if (bytes.length > MAX_MEDIA_BYTES) {
+            const size = (bytes.length / 1024 / 1024).toFixed(1)
+            throw new Error(
+              `${path} is ${size} MB. read_file sends images and PDFs up to 5 MB.`,
+            )
+          }
+          const part: ContentPart = {
+            type: media.type,
+            source: {
+              type: 'data',
+              value: toBase64(bytes),
+              mimeType: media.mimeType,
+            },
+          }
+          return [part]
+        }
+        if (bytes.subarray(0, BINARY_CHECK_BYTES).includes(0)) {
+          const type = mimeTypeOf(full)
+          const typeNote = type === undefined ? '' : `, ${type}`
+          return `${path} is a binary file (${bytes.length} bytes${typeNote}). read_file shows text, images, and PDFs only.`
+        }
+        const text = decoder.decode(bytes)
+        const parts = [page(text, { path, offset, limit })]
         const hooks = env.hooks()
         for (const hook of hooks) {
           const extra = await hook.afterRead?.(full)
diff --git a/packages/ai-harness/src/first-party/coding/search.ts b/packages/ai-harness/src/first-party/coding/search.ts
index ee2dcc4a8a..508e5d8d1a 100644
--- a/packages/ai-harness/src/first-party/coding/search.ts
+++ b/packages/ai-harness/src/first-party/coding/search.ts
@@ -1,38 +1,342 @@
-import { relative, resolve, sep } from 'node:path'
 import { toolDefinition } from '@tanstack/ai'
 import { globToRegExp } from '../glob'
-import { clip, optionalString, readText, stringArg } from './backend'
+import {
+  clip,
+  hostBackend,
+  optionalString,
+  pathsOf,
+  readText,
+  stringArg,
+} from './backend'
 import type { ToolEnv, WorkspaceBackend } from './backend'
 
-const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.nx', '.turbo'])
+/** Folders that no search looks in. */
+const SKIP = new Set(['.git', 'node_modules'])
+/** The time limit of each search command. */
+const TIMEOUT_MS = 30_000
+const MAX_FILES = 1000
+const MAX_MATCHES = 200
+/** A matching line is cut after this many characters. */
+const MAX_LINE = 2000
+/** grep skips bigger files, the same as `rg --max-filesize 1M`. */
+const MAX_SIZE = 1024 * 1024
+// ponytail: the JS walk stops after 5000 files, and the tools say so. Raise
+// it if folders without rg and without git get that big.
+const MAX_WALK = 5000
 
-/** The path of `file` from the folder `base`, with `/`, for a glob. */
-const fromBase = (base: string, file: string) =>
-  relative(base, file).split(sep).join('/')
+const FILES_NOTE =
+  '[Not all files are shown. Use a pattern or a folder to see fewer.]'
+const MATCHES_NOTE =
+  '[Not all matches are shown. Use a narrower pattern, glob, or folder.]'
 
-/** Add the files in `dir` and its folders to `out`. Stops after 5000. */
+/** `git` applies the `.gitignore` files. `-z` ends each path with NUL. */
+const GIT_FILES = 'git ls-files -z --cached --others --exclude-standard'
+/** rg flags for grep. One match more than shown tells that there are more. */
+const RG_GREP = `--line-number --no-heading --color never --max-columns ${MAX_LINE} --max-columns-preview --max-filesize 1M --max-count ${MAX_MATCHES + 1}`
+
+/** Characters that `cmd.exe` reads as special. */
+const CMD_SPECIAL = /[()\][%!^"`<>&|;, *?]/g
+
+/**
+ * `value` as one argument of a shell command. The shell gives the value to
+ * the program as it is. `platform` is the platform of the shell.
+ *
+ * - POSIX `sh`: the value goes in single quotes. No character is special
+ *   in them. A single quote in the value becomes `'\''`.
+ * - Windows `cmd.exe`: first the value is quoted for the program: a `"`
+ *   gets a backslash, and the backslashes before a `"` are doubled. Then a
+ *   `^` goes before each character that `cmd.exe` reads as special, the
+ *   quotes too. So `cmd.exe` expands no `%VAR%` and runs no `&` or `|`.
+ *   This needs delayed expansion off, which is the default. A line break
+ *   cannot be passed safely, so it throws.
+ *
+ * @example
+ * ```ts
+ * quoteArg(`it's`, 'linux') // 'it'\''s'
+ * quoteArg('a & b', 'win32') // ^"a^ ^&^ b^"
+ * ```
+ */
+export function quoteArg(value: string, platform: NodeJS.Platform) {
+  if (platform !== 'win32') return `'${value.replaceAll("'", `'\\''`)}'`
+  if (/[\r\n]/.test(value)) {
+    throw new Error('cmd.exe cannot take an argument with a line break.')
+  }
+  const quoted = `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1')}"`
+  return quoted.replace(CMD_SPECIAL, '^$&')
+}
+
+/**
+ * The platform of the shell that `backend.exec` uses, for {@link quoteArg}.
+ * A backend without `shell` has a POSIX `sh`, like a Linux sandbox.
+ */
+function shellPlatform(backend: WorkspaceBackend) {
+  return backend.shell === 'cmd' ? 'win32' : 'linux'
+}
+
+/** The rg binary of `@vscode/ripgrep`, when that optional peer is there. */
+async function bundledRg() {
+  try {
+    // Lazy and optional. The import throws when the binary package is missing.
+    const { rgPath } = await import('@vscode/ripgrep')
+    const info = await hostBackend.stat(rgPath)
+    return info?.type === 'file' ? rgPath : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** The command that starts rg on `backend`, or `undefined` without rg. */
+async function findRg(backend: WorkspaceBackend) {
+  // The bundled binary is a host file. A sandbox cannot run it.
+  if (backend === hostBackend) {
+    const bundled = await bundledRg()
+    if (bundled !== undefined) return quoteArg(bundled, process.platform)
+  }
+  const probe = await backend.exec('rg --version', { timeoutMs: TIMEOUT_MS })
+  return probe.exitCode === 0 ? 'rg' : undefined
+}
+
+/** Run an rg command in `cwd`, and give its output. */
+async function runRg(backend: WorkspaceBackend, command: string, cwd: string) {
+  const { exitCode, stdout, stderr } = await backend.exec(command, {
+    cwd,
+    timeoutMs: TIMEOUT_MS,
+  })
+  // 1 means that rg found nothing. 2 with output means that rg could not
+  // read some files, but searched the others.
+  const isDone =
+    exitCode === 0 || exitCode === 1 || (exitCode === 2 && stdout !== '')
+  if (isDone) return stdout
+  const reason =
+    exitCode === 124
+      ? `it took longer than ${TIMEOUT_MS / 1000} seconds, or gave too much output`
+      : stderr.trim() || `exit code ${exitCode}`
+  throw new Error(`The search failed: ${reason}`)
+}
+
+/** A line that grep found. `path` is from the searched folder, with `/`. */
+interface Hit {
+  path: string
+  line: number
+  text: string
+}
+
+/** `path` without the `./` that rg puts first. */
+const fromDot = (path: string) => path.replace(/^\.\//, '')
+
+/** Is `path` in a folder that no search looks in? */
+const isSkipped = (path: string) =>
+  path.split('/').some((part) => SKIP.has(part))
+
+/** The paths without empty ones, skipped ones, or repeats, sorted. */
+function tidy(paths: Array<string>) {
+  const kept = paths
+    .map(fromDot)
+    .filter((path) => path !== '' && !isSkipped(path))
+  return [...new Set(kept)].sort()
+}
+
+/** Sort by path only, so the lines of one file stay in order. */
+const byPath = (a: Hit, b: Hit) =>
+  Number(a.path > b.path) - Number(a.path < b.path)
+
+/** A test for the paths that match `glob`. Without a glob, all match. */
+function globMatcher(glob: string | undefined) {
+  const regex = glob ? globToRegExp(glob) : undefined
+  return (path: string) => !regex || regex.test(path)
+}
+
+/** The hits in rg output. Each line is the path, NUL, `line:text`. */
+function rgHits(out: string) {
+  const rows = out.split('\n')
+  const hits: Array<Hit> = []
+  for (const row of rows) {
+    const nul = row.indexOf('\0')
+    const colon = row.indexOf(':', nul)
+    if (nul === -1 || colon === -1) continue
+    hits.push({
+      path: fromDot(row.slice(0, nul)),
+      line: Number(row.slice(nul + 1, colon)),
+      text: row.slice(colon + 1),
+    })
+  }
+  return hits
+}
+
+/**
+ * Add the files under `dir` to `out`, as paths that start with `prefix`.
+ * Stops after MAX_WALK files. It skips links, so it never leaves `dir`.
+ */
 async function walk(
   backend: WorkspaceBackend,
   dir: string,
+  prefix: string,
   out: Array<string>,
 ) {
   const entries = await backend.readdir(dir)
   for (const entry of entries) {
+    if (out.length > MAX_WALK) return
+    if (SKIP.has(entry.name) || entry.type === 'link') continue
+    const path = prefix + entry.name
     if (entry.type === 'dir') {
-      if (!SKIP_DIRS.has(entry.name))
-        await walk(backend, resolve(dir, entry.name), out)
-    } else out.push(resolve(dir, entry.name))
-    if (out.length > 5000) return
+      const next = pathsOf(backend).join(dir, entry.name)
+      await walk(backend, next, `${path}/`, out)
+    } else out.push(path)
+  }
+}
+
+/**
+ * `files`, paths from `base` with `/`, without the links and the files in a
+ * linked folder. git lists links, and git for Windows lists the files in a
+ * junction. Each folder is read once. A name is compared without letter
+ * case, so a case-insensitive file system cannot hide a link.
+ */
+async function withoutLinks(
+  backend: WorkspaceBackend,
+  base: string,
+  files: Array<string>,
+) {
+  const linksIn = new Map<string, Promise<Set<string> | undefined>>()
+  /** The links in `folder`, from `base`. `undefined` when it cannot be read. */
+  const linksOf = (folder: string) => {
+    let links = linksIn.get(folder)
+    if (links === undefined) {
+      links = backend.readdir(pathsOf(backend).resolve(base, folder)).then(
+        (entries) =>
+          new Set(
+            entries
+              .filter((entry) => entry.type === 'link')
+              .map((entry) => entry.name.toLowerCase()),
+          ),
+        () => undefined,
+      )
+      linksIn.set(folder, links)
+    }
+    return links
   }
+  const kept: Array<string> = []
+  for (const file of files) {
+    const parts = file.split('/')
+    let folder = '.'
+    let isLinked = false
+    for (const part of parts) {
+      const links = await linksOf(folder)
+      // A folder that cannot be read fails closed: its files are skipped.
+      if (links === undefined || links.has(part.toLowerCase())) {
+        isLinked = true
+        break
+      }
+      folder = `${folder}/${part}`
+    }
+    if (!isLinked) kept.push(file)
+  }
+  return kept
 }
 
-/** `list_files` and `grep`. Both skip dependency and build folders. */
+/** grep in JS: read each file through the backend and test each line. */
+async function grepFiles(
+  backend: WorkspaceBackend,
+  base: string,
+  files: Array<string>,
+  regex: RegExp,
+) {
+  const hits: Array<Hit> = []
+  for (const path of files) {
+    const full = pathsOf(backend).resolve(base, path)
+    const info = await backend.stat(full)
+    if (info?.type !== 'file' || info.size > MAX_SIZE) continue
+    const text = await readText(backend, full)
+    // rg skips binary files too.
+    if (text.includes('\0')) continue
+    const lines = text.split('\n')
+    for (const [index, line] of lines.entries()) {
+      if (!regex.test(line)) continue
+      hits.push({ path, line: index + 1, text: line })
+      if (hits.length > MAX_MATCHES) return hits
+    }
+  }
+  return hits
+}
+
+/**
+ * `list_files` and `grep`. Both use the first engine that works:
+ *
+ * 1. The rg binary of `@vscode/ripgrep`, only with `hostBackend`.
+ * 2. `rg` on the PATH of the backend.
+ * 3. `git ls-files`, when the folder is in a git work tree.
+ * 4. A walk through `backend.readdir`.
+ *
+ * rg and git skip the files that `.gitignore` names. No engine looks in
+ * `.git` or `node_modules`, or gives links: rg does not follow them, and
+ * the git list and the walk leave them out. The results have the same
+ * shape whichever engine ran.
+ */
 export function searchTools(env: ToolEnv) {
+  const { backend } = env
+  const { resolve } = pathsOf(backend)
+  const platform = shellPlatform(backend)
+  // Show hidden files, like git. End each path with NUL, and use `/`.
+  const rgCommon = [
+    '--no-config --hidden --null --path-separator /',
+    ...[...SKIP].map((dir) => `--glob ${quoteArg(`!${dir}`, platform)}`),
+  ].join(' ')
+  let rg: Promise<string | undefined> | undefined
+  /** The rg command. The first search finds it, and the tools keep it. */
+  const findRgOnce = () => (rg ??= findRg(backend))
+
+  /** Every file under `base`, sorted, as paths from `base` with `/`. */
+  async function filesUnder(base: string) {
+    const command = await findRgOnce()
+    if (command !== undefined) {
+      // The `.` path stops rg from reading stdin.
+      const out = await runRg(backend, `${command} --files ${rgCommon} .`, base)
+      return { files: tidy(out.split('\0')), partial: false }
+    }
+    const git = await backend.exec(GIT_FILES, {
+      cwd: base,
+      timeoutMs: TIMEOUT_MS,
+    })
+    if (git.exitCode === 0) {
+      const listed = tidy(git.stdout.split('\0'))
+      const files = await withoutLinks(backend, base, listed)
+      return { files, partial: false }
+    }
+    const walked: Array<string> = []
+    await walk(backend, base, '', walked)
+    return { files: tidy(walked), partial: walked.length > MAX_WALK }
+  }
+
+  /** The hits for `pattern` under `base`, in the files that `isWanted` keeps. */
+  async function grepUnder(
+    base: string,
+    pattern: string,
+    isWanted: (path: string) => boolean,
+  ) {
+    // A pattern that is not a valid JS regular expression throws here,
+    // whichever engine runs.
+    const regex = new RegExp(pattern)
+    const command = await findRgOnce()
+    if (command === undefined) {
+      const { files, partial } = await filesUnder(base)
+      const hits = await grepFiles(backend, base, files.filter(isWanted), regex)
+      return { hits, partial }
+    }
+    const out = await runRg(
+      backend,
+      `${command} ${RG_GREP} ${rgCommon} -e ${quoteArg(pattern, platform)} .`,
+      base,
+    )
+    const hits = rgHits(out)
+      .filter((hit) => isWanted(hit.path))
+      .sort(byPath)
+    return { hits, partial: false }
+  }
+
   return [
     toolDefinition({
       name: 'list_files',
       description:
-        'List files in a folder (default: the workspace), optionally matching a glob like `src/**/*.ts`. The glob is from that folder.',
+        'List files in a folder (default: the workspace), optionally matching a glob like `src/**/*.ts`. The glob is from that folder. Files that .gitignore names are left out.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -50,19 +354,20 @@ export function searchTools(env: ToolEnv) {
         'list_files',
         'folder',
       )
-      const pattern = optionalString(args, 'pattern')
-      const files: Array<string> = []
-      await walk(env.backend, base, files)
-      const regex = pattern ? globToRegExp(pattern) : undefined
-      const listed = files
-        .filter((file) => !regex || regex.test(fromBase(base, file)))
-        .map(env.shown)
-      return clip(listed.slice(0, 1000).join('\n') || 'No files.')
+      const isWanted = globMatcher(optionalString(args, 'pattern'))
+      const { files, partial } = await filesUnder(base)
+      const listed = files.filter(isWanted)
+      const shown = listed
+        .slice(0, MAX_FILES)
+        .map((file) => env.shown(resolve(base, file)))
+      const text = shown.join('\n') || 'No files.'
+      const isCut = partial || listed.length > MAX_FILES
+      return clip(isCut ? `${text}\n${FILES_NOTE}` : text)
     }),
     toolDefinition({
       name: 'grep',
       description:
-        'Search file contents in a folder (default: the workspace) with a regular expression. Returns `file:line: text`.',
+        'Search file contents in a folder (default: the workspace) with a regular expression. Returns `file:line: text`. Files that .gitignore names are left out.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -77,29 +382,24 @@ export function searchTools(env: ToolEnv) {
       },
       replay: 'safe',
     }).server(async (args: unknown) => {
-      const regex = new RegExp(stringArg(args, 'pattern'))
+      const pattern = stringArg(args, 'pattern')
+      if (/[\r\n]/.test(pattern)) {
+        throw new Error('The pattern must be one line. grep tests each line.')
+      }
       const base = await env.reach(
         optionalString(args, 'path') ?? '.',
         'grep',
         'folder',
       )
-      const glob = optionalString(args, 'glob')
-      const fileFilter = glob ? globToRegExp(glob) : undefined
-      const files: Array<string> = []
-      await walk(env.backend, base, files)
-      const hits: Array<string> = []
-      for (const file of files) {
-        if (fileFilter && !fileFilter.test(fromBase(base, file))) continue
-        const info = await env.backend.stat(file)
-        if (!info || info.size > 1_000_000) continue
-        const lines = (await readText(env.backend, file)).split('\n')
-        lines.forEach((line, index) => {
-          if (hits.length < 200 && regex.test(line))
-            hits.push(`${env.shown(file)}:${index + 1}: ${line.trim()}`)
-        })
-        if (hits.length >= 200) break
-      }
-      return clip(hits.join('\n') || 'No matches.')
+      const isWanted = globMatcher(optionalString(args, 'glob'))
+      const { hits, partial } = await grepUnder(base, pattern, isWanted)
+      const shown = hits.slice(0, MAX_MATCHES).map((hit) => {
+        const text = hit.text.slice(0, MAX_LINE).trim()
+        return `${env.shown(resolve(base, hit.path))}:${hit.line}: ${text}`
+      })
+      const text = shown.join('\n') || 'No matches.'
+      const isCut = partial || hits.length > MAX_MATCHES
+      return clip(isCut ? `${text}\n${MATCHES_NOTE}` : text)
     }),
   ]
 }
diff --git a/packages/ai-harness/src/first-party/coding/snapshots.ts b/packages/ai-harness/src/first-party/coding/snapshots.ts
new file mode 100644
index 0000000000..bf8920a32c
--- /dev/null
+++ b/packages/ai-harness/src/first-party/coding/snapshots.ts
@@ -0,0 +1,279 @@
+import { createHash } from 'node:crypto'
+import { LogRecordsCapability, getLogRecords } from '@tanstack/ai'
+import { defineCommand } from '../../commands'
+import { definePlugin } from '../../plugins'
+import { hostBackend } from './backend'
+import { quoteArg } from './search'
+import type { ModelMessage } from '@tanstack/ai'
+import type { WorkspaceBackend } from './backend'
+
+export interface SnapshotsOptions {
+  /** The workspace folder, an absolute path. */
+  root: string
+  /**
+   * A folder for the shadow git repositories, an absolute path. Each
+   * workspace gets its own repository in it. The project's own `.git` is
+   * never used.
+   */
+  dataDir: string
+  /** Where the files are and git runs. Default: {@link hostBackend}. */
+  backend?: WorkspaceBackend
+}
+
+/** The files that one model step changed, between two snapshots. */
+export interface SnapshotStep {
+  /** The tree id at the start of the step. */
+  from: string
+  /** The tree id at the end of the step. */
+  to: string
+  /** The changed paths, relative to the workspace, with `/`. */
+  files: Array<string>
+}
+
+/** The log record type of a {@link SnapshotStep}. */
+const STEP_RECORD = 'tanstack/snapshots:step'
+const TIMEOUT_MS = 60_000
+const BUSY = 'Wait until the turn ends, then try again.'
+
+/**
+ * A shadow git repository for `options.root`. Git commands of one
+ * repository run one at a time, so sessions on one workspace do not clash
+ * on its index.
+ */
+function shadowRepo(options: SnapshotsOptions) {
+  const backend = options.backend ?? hostBackend
+  // ponytail: the same rule as search.ts. A backend other than the host is
+  // taken to have a POSIX `sh`, like a Linux sandbox.
+  const platform = backend === hostBackend ? process.platform : 'linux'
+  const quote = (value: string) => quoteArg(value, platform)
+  const hash = createHash('sha1').update(options.root).digest('hex')
+  const gitDir = `${options.dataDir}/${hash}`
+  // The env wins over a GIT_DIR or GIT_INDEX_FILE from a git hook, so git
+  // never writes to the project's repository.
+  const env = { GIT_DIR: gitDir, GIT_INDEX_FILE: `${gitDir}/index` }
+  // `core.autocrlf=false` keeps the line endings of every file.
+  const git = `git -c core.autocrlf=false --git-dir ${quote(gitDir)} --work-tree ${quote(options.root)}`
+
+  /** Run a command in the workspace. Throws with git's message when it fails. */
+  const exec = async (command: string) => {
+    const result = await backend.exec(command, {
+      cwd: options.root,
+      env,
+      timeoutMs: TIMEOUT_MS,
+    })
+    if (result.exitCode !== 0) {
+      throw new Error(`${command} failed: ${result.stderr.trim()}`)
+    }
+    return result.stdout
+  }
+  const run = (args: string) => exec(`${git} ${args}`)
+
+  /**
+   * Save the workspace files, and give the id of their tree. One shell runs
+   * both git commands: each shell start is slow on Windows.
+   */
+  const track = async () =>
+    (await exec(`${git} add -A && ${git} write-tree`)).trim()
+  const changed = async (from: string, to: string) => {
+    const names = await run(
+      `diff --name-only -z --no-renames ${quote(from)} ${quote(to)}`,
+    )
+    return names.split('\0').filter((name) => name !== '')
+  }
+
+  let queue: Promise<void> = Promise.resolve()
+  const serial = <T>(fn: () => Promise<T>) => {
+    const result = queue.then(fn)
+    queue = result.then(
+      () => undefined,
+      () => undefined,
+    )
+    return result
+  }
+
+  return {
+    /** Create the repository. `false` when the backend has no git. */
+    init: () =>
+      serial(async () => {
+        const probe = await backend.exec('git --version', {
+          timeoutMs: TIMEOUT_MS,
+        })
+        if (probe.exitCode !== 0) return false
+        // A bare repository: it has no work tree of its own.
+        await exec(`git init --bare -q ${quote(gitDir)}`)
+        // Keep the bytes of every file: no line ending change, no filter.
+        await backend.writeFile(
+          `${gitDir}/info/attributes`,
+          '* -text -ident -filter\n',
+        )
+        return true
+      }),
+    track: () => serial(track),
+    changed: (from: string, to: string) => serial(() => changed(from, to)),
+    diff: (from: string, to?: string) =>
+      serial(async () => {
+        const target = to ?? (await track())
+        const patch = await run(
+          `diff --no-color --no-ext-diff --no-renames ${quote(from)} ${quote(target)}`,
+        )
+        return { files: await changed(from, target), patch }
+      }),
+    /**
+     * Make the workspace files match `tree`. Files that are not in `tree`
+     * are removed.
+     */
+    restore: (tree: string) =>
+      serial(async () => {
+        // The index must list the files on disk, so the reset sees them.
+        await exec(`${git} add -A && ${git} read-tree --reset -u ${quote(tree)}`)
+      }),
+  }
+}
+
+const messageOf = (error: unknown) =>
+  error instanceof Error ? error.message : String(error)
+
+/**
+ * Snapshots of the workspace files at the start and the end of each model
+ * step, in a shadow git repository in `dataDir`. Adds two commands:
+ *
+ * - `/undo`: put the files back as they were before the last turn, and
+ *   remove that turn from the transcript.
+ * - `/redo`: bring back what the last `/undo` removed. A new turn clears it.
+ *
+ * The changed files of each step go to the session log as a
+ * `tanstack/snapshots:step` record on a durable host, else to the plugin
+ * state. `diff(from, to?)` gives the changed files and a unified diff
+ * between two tree ids. Without `to`, it compares with the files now.
+ *
+ * Needs the git CLI on the backend. Without git, the plugin does nothing.
+ *
+ * @example
+ * ```ts
+ * const root = process.cwd()
+ * const history = snapshots({ root, dataDir: '/var/lib/agent/snapshots' })
+ * defineHarness({ adapter, plugins: () => [workspaceTools({ root }), history] })
+ * // `step` is a `tanstack/snapshots:step` record.
+ * const { files, patch } = await history.diff(step.from, step.to)
+ * ```
+ */
+export function snapshots(options: SnapshotsOptions) {
+  const repo = shadowRepo(options)
+  let ready: Promise<boolean> | undefined
+  const isReady = () =>
+    (ready ??= repo.init().then(
+      (hasGit) => {
+        if (!hasGit)
+          console.warn('snapshots: git was not found. Snapshots are off.')
+        return hasGit
+      },
+      (error: unknown) => {
+        console.warn(`snapshots: ${messageOf(error)}. Snapshots are off.`)
+        return false
+      },
+    ))
+
+  return definePlugin({
+    name: 'tanstack/snapshots',
+    diff: async (from: string, to?: string) => {
+      if (!(await isReady()))
+        throw new Error('snapshots: git is not available.')
+      return repo.diff(from, to)
+    },
+    setup: async (ctx) => {
+      if (!(await isReady())) return
+      const noSteps: Array<SnapshotStep> = []
+      const steps = ctx.state(noSteps)
+      /** The tree at the start of the step that runs. */
+      let stepStart: string | undefined
+      /** The tree at the start of the last turn: what `/undo` restores. */
+      let turnStart: string | undefined
+      /** What the last `/undo` removed. */
+      let redo: { tree: string; messages: Array<ModelMessage> } | undefined
+
+      // A failed snapshot must not fail the turn. It only says so.
+      const guard = async <T>(fn: () => Promise<T>) => {
+        try {
+          return await fn()
+        } catch (error) {
+          console.warn(`snapshots: ${messageOf(error)}`)
+          return undefined
+        }
+      }
+
+      return {
+        middleware: [
+          {
+            name: 'tanstack/snapshots',
+            optionalRequires: [LogRecordsCapability],
+            onIteration: async (_ctx, { iteration }) => {
+              // A later step starts with the files the step before it left,
+              // so it reuses that snapshot. The model call changes no file.
+              if (iteration > 0 && stepStart !== undefined) return
+              stepStart = await guard(repo.track)
+              if (iteration > 0) return
+              turnStart = stepStart
+              redo = undefined
+            },
+            onToolPhaseComplete: async (ctx) => {
+              const from = stepStart
+              if (from === undefined) return
+              const step = await guard(async () => {
+                const to = await repo.track()
+                const files = to === from ? [] : await repo.changed(from, to)
+                return { from, to, files }
+              })
+              // A failed snapshot leaves no start: the next step takes one.
+              stepStart = step?.to
+              if (!step || step.files.length === 0) return
+              const log = getLogRecords(ctx, { optional: true })
+              if (log) await log.append([{ type: STEP_RECORD, ...step }])
+              else await steps.update((saved) => [...saved, step])
+            },
+          },
+        ],
+        commands: {
+          // ponytail: one level. A stack of turn starts gives more undos.
+          undo: defineCommand({
+            description:
+              'Undo the last turn: restore the files and remove it from the transcript',
+            run: async (_input, { session }) => {
+              if (session.snapshot().status !== 'idle') return BUSY
+              const messages = await session.transcript()
+              // ponytail: the turn starts at the last user message. A steer
+              // that joined the turn is a user message too, so only the
+              // part after it goes.
+              const start = messages.findLastIndex(
+                (message) => message.role === 'user',
+              )
+              if (turnStart === undefined || start === -1) {
+                return 'Nothing to undo.'
+              }
+              const now = await repo.track()
+              const files = await repo.changed(turnStart, now)
+              await repo.restore(turnStart)
+              redo = { tree: now, messages: messages.slice(start) }
+              turnStart = undefined
+              await session.replaceTranscript(messages.slice(0, start))
+              return `Undid the last turn. Files restored: ${files.length}.`
+            },
+          }),
+          redo: defineCommand({
+            description: 'Bring back the files and the turn of the last /undo',
+            run: async (_input, { session }) => {
+              if (session.snapshot().status !== 'idle') return BUSY
+              if (!redo) return 'Nothing to redo.'
+              const { tree, messages } = redo
+              turnStart = await repo.track()
+              await repo.restore(tree)
+              redo = undefined
+              const transcript = await session.transcript()
+              await session.replaceTranscript([...transcript, ...messages])
+              return 'Redid the last turn.'
+            },
+          }),
+        },
+      }
+    },
+  })
+}
diff --git a/packages/ai-harness/src/first-party/coding/web.ts b/packages/ai-harness/src/first-party/coding/web.ts
new file mode 100644
index 0000000000..1d63f8502a
--- /dev/null
+++ b/packages/ai-harness/src/first-party/coding/web.ts
@@ -0,0 +1,384 @@
+import { lookup } from 'node:dns/promises'
+import { BlockList, isIP } from 'node:net'
+import { toolDefinition } from '@tanstack/ai'
+import { isRecord } from '../../utils'
+import { optionalString, stringArg } from './backend'
+
+const DEFAULT_TIMEOUT_MS = 30_000
+const MAX_TIMEOUT_MS = 120_000
+/** `webfetch` stops reading a body after this many bytes. */
+const MAX_BYTES = 5 * 1024 * 1024
+const MAX_REDIRECTS = 5
+/** A NUL byte in this many first bytes marks a binary body. */
+const BINARY_CHECK_BYTES = 8 * 1024
+const DEFAULT_RESULTS = 8
+const MAX_RESULTS = 20
+
+const FORMATS = ['markdown', 'text', 'html'] as const
+type Format = (typeof FORMATS)[number]
+
+const HTML_TYPES = /^(text\/html|application\/xhtml\+xml)$/
+const TEXT_TYPES = /^text\/|[/+](json|xml)$|javascript$/
+
+/** The part of `turndown` that `webfetch` uses. It ships no types. */
+type TurndownClass = new (options: {
+  headingStyle: 'atx'
+  codeBlockStyle: 'fenced'
+}) => {
+  remove: (tags: Array<string>) => unknown
+  turndown: (html: string) => string
+}
+
+const ENTITIES: Record<string, string> = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: ' ',
+}
+
+/** The addresses that are not on the public internet. */
+const PRIVATE = new BlockList()
+// This network. 0.0.0.0 reaches this machine.
+PRIVATE.addSubnet('0.0.0.0', 8)
+PRIVATE.addSubnet('10.0.0.0', 8)
+// Shared address space. Some clouds keep metadata here.
+PRIVATE.addSubnet('100.64.0.0', 10)
+PRIVATE.addSubnet('127.0.0.0', 8)
+// Link-local, with the cloud metadata address 169.254.169.254.
+PRIVATE.addSubnet('169.254.0.0', 16)
+PRIVATE.addSubnet('172.16.0.0', 12)
+PRIVATE.addSubnet('192.168.0.0', 16)
+// Multicast and reserved.
+PRIVATE.addSubnet('224.0.0.0', 3)
+// `::`, `::1`, and IPv4 in the old `::a.b.c.d` form. The IPv4 rules above
+// also match the `::ffff:a.b.c.d` form.
+PRIVATE.addSubnet('::', 96, 'ipv6')
+PRIVATE.addSubnet('fc00::', 7, 'ipv6')
+PRIVATE.addSubnet('fe80::', 10, 'ipv6')
+PRIVATE.addSubnet('ff00::', 8, 'ipv6')
+
+/** A search engine for the `websearch` tool. */
+export interface SearchProvider {
+  /** At most `options.limit` results for `query`. */
+  search: (
+    query: string,
+    options: { limit: number; signal?: AbortSignal },
+  ) => Promise<Array<{ title: string; url: string; snippet?: string }>>
+}
+
+export interface WebToolsOptions {
+  /** The `fetch` that `webfetch` uses. Default: the global `fetch`. */
+  fetch?: typeof fetch
+  /**
+   * Let `webfetch` read localhost and private network hosts. Default:
+   * `false`. Turn it on only when the model may reach your network.
+   */
+  allowPrivateHosts?: boolean
+  /** Adds the `websearch` tool. Without it, there is no `websearch` tool. */
+  search?: SearchProvider
+}
+
+/** The `turndown` class, or `undefined` when that optional peer is missing. */
+async function loadTurndown() {
+  try {
+    // @ts-expect-error -- turndown ships no types. TurndownClass is the part we use.
+    const turndown: { default: TurndownClass } = await import('turndown')
+    return turndown.default
+  } catch {
+    return undefined
+  }
+}
+
+/** Decode `&amp;`, `&lt;`, `&#39;`, `&#x41;`, and the other common entities. */
+function decodeEntities(text: string) {
+  return text.replace(
+    /&(#x[\da-f]+|#\d+|[a-z]+);/gi,
+    (entity, name: string) => {
+      if (!name.startsWith('#')) return ENTITIES[name.toLowerCase()] ?? entity
+      const isHex = name[1] === 'x' || name[1] === 'X'
+      const code = Number.parseInt(name.slice(isHex ? 2 : 1), isHex ? 16 : 10)
+      return code <= 0x10ffff ? String.fromCodePoint(code) : entity
+    },
+  )
+}
+
+/** The text of an HTML page: no tags, scripts, or styles. One block a line. */
+function htmlToText(html: string) {
+  const text = html
+    .replace(/<(script|style|noscript|template)\b[\s\S]*?<\/\1\s*>/gi, '')
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<\/?(br|p|div|li|tr|h[1-6])\b[^>]*>/gi, '\n')
+    .replace(/<[^>]*>/g, '')
+  return decodeEntities(text)
+    .replace(/[^\S\n]+/g, ' ')
+    .replace(/ *\n\s*/g, '\n')
+    .trim()
+}
+
+/** `html` in the format the model asked for. */
+async function convert(html: string, format: Format | undefined) {
+  const Turndown = await loadTurndown()
+  const wanted = format ?? (Turndown ? 'markdown' : 'text')
+  switch (wanted) {
+    case 'html':
+      return html
+    case 'text':
+      return htmlToText(html)
+    case 'markdown': {
+      if (!Turndown) {
+        throw new Error(
+          'Install turndown to get markdown (npm install turndown), or ask for format "text".',
+        )
+      }
+      const service = new Turndown({
+        headingStyle: 'atx',
+        codeBlockStyle: 'fenced',
+      })
+      service.remove(['script', 'style', 'noscript', 'template'])
+      return service.turndown(html)
+    }
+  }
+}
+
+/** The `format` argument, or `undefined` when the model did not set it. */
+function formatArg(args: unknown) {
+  const value = optionalString(args, 'format')
+  if (value === undefined) return undefined
+  const format = FORMATS.find((item) => item === value)
+  if (format === undefined) {
+    throw new Error('Argument "format" must be markdown, text, or html.')
+  }
+  return format
+}
+
+/** True when `address`, an IP address, is not on the public internet. */
+function isPrivateAddress(address: string) {
+  return PRIVATE.check(address, isIP(address) === 6 ? 'ipv6' : 'ipv4')
+}
+
+/**
+ * Throws unless `url` is http or https. Unless `allowPrivateHosts` is set,
+ * it also throws for a private or local host: the host as written, and
+ * every address that DNS gives for it.
+ */
+async function checkUrl(url: URL, allowPrivateHosts: boolean) {
+  const isWeb = url.protocol === 'http:' || url.protocol === 'https:'
+  if (!isWeb) {
+    throw new Error(
+      `webfetch reads http and https URLs only, not ${url.protocol}`,
+    )
+  }
+  if (allowPrivateHosts) return
+  // The URL keeps IPv6 hosts in brackets. A name can end with a dot.
+  const host = url.hostname.replace(/^\[|\]$/g, '').replace(/\.$/, '')
+  const refused = `webfetch does not read private or local hosts: ${url.hostname}`
+  const isLocalName = host === 'localhost' || host.endsWith('.localhost')
+  if (isLocalName) throw new Error(refused)
+  if (isIP(host) !== 0) {
+    if (isPrivateAddress(host)) throw new Error(refused)
+    return
+  }
+  // ponytail: `fetch` looks the name up again. A DNS server that changes
+  // its answer between the two lookups (DNS rebinding) can still reach a
+  // private host. Pin the checked address in a custom dispatcher if that
+  // matters.
+  const addresses = await lookup(host, { all: true }).catch(() => {
+    throw new Error(`Could not resolve ${host}.`)
+  })
+  const isPrivate = addresses.some(({ address }) => isPrivateAddress(address))
+  if (isPrivate) throw new Error(refused)
+}
+
+/**
+ * Fetch `start` and follow at most 5 redirects. Each URL is checked before
+ * it is fetched, so a redirect cannot lead to a private host.
+ */
+async function follow(
+  start: URL,
+  options: {
+    fetch: typeof fetch
+    allowPrivateHosts: boolean
+    signal: AbortSignal
+  },
+) {
+  let url = start
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    await checkUrl(url, options.allowPrivateHosts)
+    const response = await options.fetch(url.href, {
+      redirect: 'manual',
+      signal: options.signal,
+    })
+    const location = response.headers.get('location')
+    const isRedirect =
+      response.status >= 300 && response.status < 400 && location !== null
+    if (!isRedirect) return { response, url }
+    await response.body?.cancel()
+    url = new URL(location, url)
+  }
+  throw new Error(`${start.href} redirected more than ${MAX_REDIRECTS} times.`)
+}
+
+/** The body bytes, at most 5 MB. `isCut` is true when there was more. */
+async function readBody(response: Response) {
+  const reader = response.body?.getReader()
+  const chunks: Array<Uint8Array> = []
+  let size = 0
+  let isCut = false
+  while (reader) {
+    const { done, value } = await reader.read()
+    if (done) break
+    chunks.push(value)
+    size += value.length
+    if (size > MAX_BYTES) {
+      isCut = true
+      await reader.cancel()
+      break
+    }
+  }
+  return { bytes: Buffer.concat(chunks).subarray(0, MAX_BYTES), isCut }
+}
+
+/** The page as the model gets it: HTML converted, text and JSON as they are. */
+async function readPage(
+  response: Response,
+  url: URL,
+  format: Format | undefined,
+) {
+  if (!response.ok) {
+    await response.body?.cancel()
+    throw new Error(`${url.href} answered with HTTP ${response.status}.`)
+  }
+  const header = response.headers.get('content-type') ?? ''
+  const type = (header.split(';', 1)[0] ?? '').trim().toLowerCase()
+  const isHtml = HTML_TYPES.test(type)
+  const binary = `${url.href} is ${type || 'binary'}. webfetch reads HTML, text, and JSON only.`
+  // A missing type is checked on the bytes below.
+  const isKnownBinary = type !== '' && !isHtml && !TEXT_TYPES.test(type)
+  if (isKnownBinary) {
+    await response.body?.cancel()
+    throw new Error(binary)
+  }
+  const { bytes, isCut } = await readBody(response)
+  if (type === '' && bytes.subarray(0, BINARY_CHECK_BYTES).includes(0)) {
+    throw new Error(binary)
+  }
+  // ponytail: reads every page as UTF-8. Decode the charset of the
+  // content type if other charsets matter.
+  const text = new TextDecoder().decode(bytes)
+  const page = isHtml ? await convert(text, format) : text
+  return isCut ? `${page}\n\n[Cut at 5 MB. The rest was not read.]` : page
+}
+
+/**
+ * The web tools for a coding agent:
+ *
+ * - `webfetch` reads a URL. HTML comes back as Markdown when the optional
+ *   `turndown` package is installed, else as text. Text and JSON come back
+ *   as they are. Other content types are refused. It reads at most 5 MB,
+ *   stops after 30 seconds (the model can ask for up to 120), and follows
+ *   at most 5 redirects.
+ * - `websearch` searches with `options.search`. Without a provider, there
+ *   is no `websearch` tool.
+ *
+ * `webfetch` fetches URLs that the model picks. So it reads only http and
+ * https, and it refuses localhost, loopback, link-local (with cloud
+ * metadata), and private network hosts, unless `allowPrivateHosts` is set.
+ *
+ * @example
+ * ```ts
+ * const tools = webTools({
+ *   search: { search: (query, { limit }) => mySearch(query, limit) },
+ * })
+ * ```
+ */
+export function webTools(options: WebToolsOptions = {}) {
+  const { allowPrivateHosts = false, search } = options
+
+  const webfetch = toolDefinition({
+    name: 'webfetch',
+    description:
+      'Read a web page by its http or https URL. HTML comes back as Markdown by default, or set format to text or html. Text and JSON come back as they are. At most 5 MB is read.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string' },
+        format: { type: 'string', enum: ['markdown', 'text', 'html'] },
+        timeoutMs: {
+          type: 'number',
+          description: 'Stop after this many milliseconds. At most 120000.',
+        },
+      },
+      required: ['url'],
+    },
+    replay: 'safe',
+  }).server(async (args: unknown, context) => {
+    const url = new URL(stringArg(args, 'url'))
+    const format = formatArg(args)
+    const requested = isRecord(args) ? args.timeoutMs : undefined
+    // A timeout of 0 would stop at once, so it gets the default.
+    const isTimeout = typeof requested === 'number' && requested > 0
+    const timeoutMs = isTimeout
+      ? Math.min(requested, MAX_TIMEOUT_MS)
+      : DEFAULT_TIMEOUT_MS
+    const timeout = AbortSignal.timeout(timeoutMs)
+    const runSignal = context?.abortSignal
+    const signal = runSignal ? AbortSignal.any([timeout, runSignal]) : timeout
+    try {
+      const fetched = await follow(url, {
+        fetch: options.fetch ?? fetch,
+        allowPrivateHosts,
+        signal,
+      })
+      return await readPage(fetched.response, fetched.url, format)
+    } catch (error) {
+      if (timeout.aborted) {
+        throw new Error(`${url.href} timed out after ${timeoutMs} ms.`)
+      }
+      throw error
+    }
+  })
+
+  if (!search) return [webfetch]
+
+  const websearch = toolDefinition({
+    name: 'websearch',
+    description:
+      'Search the web. You get a numbered list of results: title, URL, and a short snippet. Read a result with webfetch.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string' },
+        limit: {
+          type: 'number',
+          description: `Most results to get. Default ${DEFAULT_RESULTS}, at most ${MAX_RESULTS}.`,
+        },
+      },
+      required: ['query'],
+    },
+    replay: 'safe',
+  }).server(async (args: unknown, context) => {
+    const query = stringArg(args, 'query')
+    const requested = isRecord(args) ? args.limit : undefined
+    const isLimit = typeof requested === 'number' && requested >= 1
+    const limit = isLimit
+      ? Math.min(Math.floor(requested), MAX_RESULTS)
+      : DEFAULT_RESULTS
+    const results = await search.search(query, {
+      limit,
+      signal: context?.abortSignal,
+    })
+    if (results.length === 0) return `No results for "${query}".`
+    return results
+      .slice(0, limit)
+      .map((result, index) => {
+        const lines = [`${index + 1}. ${result.title}`, `   ${result.url}`]
+        if (result.snippet) lines.push(`   ${result.snippet}`)
+        return lines.join('\n')
+      })
+      .join('\n\n')
+  })
+
+  return [webfetch, websearch]
+}
diff --git a/packages/ai-harness/src/first-party/coding/workspace.ts b/packages/ai-harness/src/first-party/coding/workspace.ts
index f9d39a68e9..b114bcaaed 100644
--- a/packages/ai-harness/src/first-party/coding/workspace.ts
+++ b/packages/ai-harness/src/first-party/coding/workspace.ts
@@ -1,13 +1,17 @@
-import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
 import { definePlugin } from '../../plugins'
-import { PermissionRules, isYes } from '../permissions'
+import { PermissionResources, PermissionRules, isYes } from '../permissions'
 import { WorkspaceHooks } from '../workspace-hooks'
-import { hostBackend } from './backend'
-import { bashTools } from './bash'
+import { hostBackend, optionalString, pathsOf, stringArg } from './backend'
+import { bashResources, bashTools } from './bash'
 import { editTools } from './edit'
+import { patchPaths, patchTools } from './patch'
 import { readTools } from './read'
 import { searchTools } from './search'
+import { webTools } from './web'
+import type { AnyTool } from '@tanstack/ai'
+import type { ToolResources } from '../permissions'
 import type { ToolEnv, WorkspaceBackend } from './backend'
+import type { WebToolsOptions } from './web'
 
 export interface WorkspaceToolsOptions {
   root: string
@@ -21,6 +25,23 @@ export interface WorkspaceToolsOptions {
   outside?: 'deny' | 'ask'
   /** Where the files are and commands run. Default: {@link hostBackend}. */
   backend?: WorkspaceBackend
+  /**
+   * The tools that change files. `'auto'` (default): GPT models (an id that
+   * starts with `gpt-`, or `o` and a digit, like `o3`) get `patch` and no
+   * `edit_file`. Other models get `edit_file` and `write_file`, and no
+   * `patch`. `'edit'` or `'patch'` gives that style to every model.
+   */
+  editStyle?: 'auto' | 'edit' | 'patch'
+  /**
+   * The web tools. Default: on, with `webfetch`. Pass `search` to add
+   * `websearch`. `false` adds no web tools.
+   */
+  web?: false | WebToolsOptions
+  /**
+   * When `bash` gives the model only the end of the output, it saves the
+   * full output in this folder. Relative to `root`, or absolute.
+   */
+  spillDir?: string
 }
 
 /** What the tools need from the session for a path outside the workspace. */
@@ -31,8 +52,8 @@ export interface OutsideAccess {
   mode: () => unknown
 }
 
-/** Is `full` the folder `dir`, or a path in it? */
-function within(dir: string, full: string) {
+/** Is `full` the folder `dir`, or a path in it? `sep` is the separator. */
+function within(dir: string, full: string, sep: string) {
   return full === dir || full.startsWith(dir.endsWith(sep) ? dir : dir + sep)
 }
 
@@ -54,21 +75,37 @@ function createLock() {
 }
 
 /**
- * The tools of {@link workspaceTools} for one session. `access` asks the user
- * about a path outside the workspace when `options.outside` is `'ask'`.
- * `hooks` are the hooks that plugins added.
+ * Does `editStyle: 'auto'` give `model` the `patch` tool? GPT models do:
+ * `gpt-` ids and the `o` series, like `o3`.
+ */
+function prefersPatch(model: string) {
+  // A gateway id can name the provider first, like `openai/gpt-5`.
+  const id = model.slice(model.lastIndexOf('/') + 1)
+  return /^(gpt-|o\d)/i.test(id)
+}
+
+/**
+ * The tools of {@link workspaceTools} for one session, and what each call
+ * touches for `PermissionResources`. `access` asks the user about a path
+ * outside the workspace when `options.outside` is `'ask'`. `hooks` are the
+ * hooks that plugins added. `note` tells the model that a background `bash`
+ * job ended, and `signal` kills the jobs that still run.
  */
 export function createWorkspaceTools(
   options: WorkspaceToolsOptions,
   session: {
     access?: OutsideAccess
     hooks?: () => ReadonlyArray<WorkspaceHooks>
+    note?: (text: string) => Promise<void>
+    signal?: AbortSignal
   } = {},
 ) {
-  const root = resolve(options.root)
+  const backend = options.backend ?? hostBackend
+  const paths = pathsOf(backend)
+  const root = paths.resolve(options.root)
   const { access } = session
-  // The outside folders the user allowed in this session, and the questions
-  // that wait for an answer, by folder, so parallel calls ask once.
+  // The real outside folders the user allowed in this session, and the
+  // questions that wait for an answer, by folder, so parallel calls ask once.
   const allowed: Array<string> = []
   const asking = new Map<string, Promise<boolean>>()
 
@@ -86,18 +123,41 @@ export function createWorkspaceTools(
     return answer
   }
 
+  /**
+   * The real path of `full`, with every link resolved. For a path that is
+   * not there yet: the real path of the nearest parent that is there, plus
+   * the rest. A link to a missing target throws.
+   */
+  const realPath = async (full: string) => {
+    const rest: Array<string> = []
+    let head = full
+    for (;;) {
+      const real = backend.realpath ? await backend.realpath(head) : head
+      if (real !== undefined) return paths.join(real, ...rest)
+      const parent = paths.dirname(head)
+      // Not even the top folder is there.
+      if (parent === head) return full
+      rest.unshift(paths.basename(head))
+      head = parent
+    }
+  }
+
+  // The boundary check uses real paths, so a link inside the workspace that
+  // leads out of it counts as outside.
   const reach: ToolEnv['reach'] = async (path, tool, kind) => {
-    const full = isAbsolute(path) ? resolve(path) : resolve(root, path)
-    const isAllowed = [root, ...allowed].some((dir) => within(dir, full))
+    const full = paths.resolve(root, path)
+    const real = await realPath(full)
+    const folders = [await realPath(root), ...allowed]
+    const isAllowed = folders.some((dir) => within(dir, real, paths.sep))
     if (isAllowed) return full
     if (options.outside !== 'ask' || !access) {
       throw new Error(`Path "${path}" is outside the workspace.`)
     }
     if (access.mode() === 'bypass') return full
-    const folder = kind === 'folder' ? full : dirname(full)
+    const folder = kind === 'folder' ? real : paths.dirname(real)
     const yes = await allow(
       folder,
-      `${tool} wants ${full}, outside the workspace (${root}). Allow ${folder} for this session? (y/n)`,
+      `${tool} wants ${real}, outside the workspace (${root}). Allow ${folder} for this session? (y/n)`,
     )
     if (!yes) {
       throw new Error(
@@ -108,7 +168,7 @@ export function createWorkspaceTools(
   }
 
   const env: ToolEnv = {
-    backend: options.backend ?? hostBackend,
+    backend,
     root,
     hooks: session.hooks ?? (() => []),
     // ponytail: one lock per session. Sessions on one folder do not wait
@@ -116,29 +176,78 @@ export function createWorkspaceTools(
     lock: createLock(),
     reach,
     shown: (full) =>
-      (within(root, full) ? relative(root, full) || '.' : full)
-        .split(sep)
+      (within(root, full, paths.sep) ? paths.relative(root, full) || '.' : full)
+        .split(paths.sep)
         .join('/'),
   }
   const tools = [
     ...readTools(env),
     ...editTools(env),
+    ...patchTools(env),
     ...searchTools(env),
-    ...bashTools(env, { timeoutMs: options.bashTimeoutMs }),
+    ...bashTools(env, {
+      timeoutMs: options.bashTimeoutMs,
+      note: session.note,
+      spillDir: options.spillDir,
+      signal: session.signal,
+    }),
+    ...(options.web === false ? [] : webTools(options.web)),
   ]
+
+  // What each call touches, as the tool resolves it, for the permission
+  // rules with a `resource`.
+  const file = (input: unknown) => [
+    paths.resolve(root, stringArg(input, 'path')),
+  ]
+  const folder = (input: unknown) => [
+    paths.resolve(root, optionalString(input, 'path') ?? '.'),
+  ]
+  const resources: Record<string, ToolResources> = {
+    read_file: { paths: file },
+    write_file: { paths: file },
+    edit_file: { paths: file },
+    list_files: { paths: folder },
+    grep: { paths: folder },
+    patch: {
+      paths: (input) =>
+        patchPaths(stringArg(input, 'patch')).map((each) =>
+          paths.resolve(root, each),
+        ),
+    },
+    bash: { commands: bashResources },
+  }
+
   const prompt =
     options.outside === 'ask'
       ? `Your workspace is ${root}. Paths are relative to it. A path outside it asks the user first.`
       : `Your workspace is ${root}. Paths are relative to it.`
-  return { tools, prompt }
+  return { tools, prompt, resources }
 }
 
 /**
- * File and shell tools for a coding agent, in `root`: `read_file`,
- * `write_file`, `edit_file`, `list_files`, `grep`, and `bash`. Edits and
- * `bash` ask for approval through `permissions()`. A path outside `root` is
- * refused, or with `outside: 'ask'` the user is asked first. Other plugins
- * add {@link WorkspaceHooks} to run code after a read or a write.
+ * `tools` with the edit tools of `editStyle` for `model`: without
+ * `edit_file` for the patch style, else without `patch`.
+ */
+function withEditStyle(
+  tools: ReadonlyArray<AnyTool>,
+  editStyle: NonNullable<WorkspaceToolsOptions['editStyle']>,
+  model: string,
+) {
+  const usesPatch =
+    editStyle === 'patch' || (editStyle === 'auto' && prefersPatch(model))
+  const hidden = usesPatch ? 'edit_file' : 'patch'
+  return tools.filter((tool) => tool.name !== hidden)
+}
+
+/**
+ * File, shell, and web tools for a coding agent, in `root`: `read_file`,
+ * `write_file`, `edit_file` or `patch` (see `editStyle`), `list_files`,
+ * `grep`, `bash`, `webfetch`, and `websearch` with a search provider. Edits
+ * and `bash` ask for approval through `permissions()`, and each call tells
+ * the permission rules which paths or commands it touches. A path outside
+ * `root` is refused, or with `outside: 'ask'` the user is asked first. A
+ * link that leads out of `root` counts as outside. Other plugins add
+ * {@link WorkspaceHooks} to run code after a read or a write.
  *
  * The tools use `backend` for files and commands. The default,
  * `hostBackend`, runs on this machine with the host's authority. Use a
@@ -154,16 +263,21 @@ export function workspaceTools(options: WorkspaceToolsOptions) {
     name: 'tanstack/workspace-tools',
     setup: (ctx) => {
       const hooks = ctx.collect(WorkspaceHooks)
-      const { tools, prompt } = createWorkspaceTools(options, {
+      const { tools, prompt, resources } = createWorkspaceTools(options, {
         access: {
           ask: (message) => ctx.session.ask({ message }),
           mode: () => ctx.config.get('mode'),
         },
         hooks: () => hooks,
+        note: (text) => ctx.session.note(text, { wake: true }),
+        // Kills the background `bash` jobs when the plugin is disposed.
+        signal: ctx.resources.signal,
       })
       return {
         tools,
         prompts: [prompt],
+        prepareTools: (turn) =>
+          withEditStyle(turn.tools, options.editStyle ?? 'auto', turn.model),
         contribute: [
           PermissionRules.item({
             tool: 'read_file',
@@ -190,11 +304,17 @@ export function workspaceTools(options: WorkspaceToolsOptions) {
             decision: 'ask',
             kind: 'edit',
           }),
+          PermissionRules.item({
+            tool: 'patch',
+            decision: 'ask',
+            kind: 'edit',
+          }),
           PermissionRules.item({
             tool: 'bash',
             decision: 'ask',
             kind: 'execute',
           }),
+          PermissionResources.item(resources),
         ],
       }
     },
diff --git a/packages/ai-harness/src/first-party/files.ts b/packages/ai-harness/src/first-party/files.ts
index 2b9fa2e0d2..941bc92cfb 100644
--- a/packages/ai-harness/src/first-party/files.ts
+++ b/packages/ai-harness/src/first-party/files.ts
@@ -1,52 +1,282 @@
+import { existsSync, readFileSync, statSync } from 'node:fs'
 import { readFile, readdir } from 'node:fs/promises'
-import { basename, extname, resolve } from 'node:path'
+import { homedir } from 'node:os'
+import {
+  basename,
+  dirname,
+  extname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  sep,
+} from 'node:path'
 import { defineCommand } from '../commands'
 import { definePlugin } from '../plugins'
+import { hostBackend } from './coding/backend'
+import { WorkspaceHooks } from './workspace-hooks'
 import type { AnyCommand } from '../commands'
 
-async function readIfPresent(path: string): Promise<string | undefined> {
+/** Prompt slots kept free for instruction files that change. */
+const SPARE_SLOTS = 8
+
+/** The mtime of the file at `path`, or `undefined` when there is none. */
+function mtimeOf(path: string) {
   try {
-    return await readFile(path, 'utf8')
+    return statSync(path).mtimeMs
   } catch {
     return undefined
   }
 }
 
+/** The trimmed text of the file at `path`, or `''` when there is none. */
+function textOf(path: string) {
+  try {
+    return readFileSync(path, 'utf8').trim()
+  } catch {
+    return ''
+  }
+}
+
 /**
- * Add project instruction files (AGENTS.md, CLAUDE.md) to the system prompt,
- * read once when the session opens.
+ * The folders from the repo root (the nearest folder with `.git`) down to
+ * `root`, outermost first. Only `root` when no folder has `.git`.
+ */
+function repoFolders(root: string) {
+  const folders = [root]
+  let dir = root
+  while (!existsSync(join(dir, '.git'))) {
+    const parent = dirname(dir)
+    if (parent === dir) return { folders: [root], isRepo: false }
+    dir = parent
+    folders.unshift(dir)
+  }
+  return { folders, isRepo: true }
+}
+
+/** The date, platform, working folder, and git facts, as a prompt. */
+async function environment(root: string, isRepo: boolean) {
+  const now = new Date()
+  // toISOString is UTC. Move by the offset to get the local date.
+  const date = new Date(now.getTime() - now.getTimezoneOffset() * 60_000)
+    .toISOString()
+    .slice(0, 10)
+  const lines = [
+    `Date: ${date}`,
+    `Platform: ${process.platform}`,
+    `Working folder: ${root}`,
+    `Git repository: ${isRepo ? 'yes' : 'no'}`,
+  ]
+  if (isRepo) {
+    const git = await hostBackend.exec('git rev-parse --abbrev-ref HEAD', {
+      cwd: root,
+      timeoutMs: 5000,
+    })
+    if (git.exitCode === 0) lines.push(`Git branch: ${git.stdout.trim()}`)
+  }
+  return `Environment:\n${lines.map((line) => `- ${line}`).join('\n')}`
+}
+
+/** The note for an instruction file whose text changed from `before`. */
+function changeNote(title: string, before: string, text: string) {
+  if (text === '') return `${title} were removed.`
+  if (before === '') return `${title}:\n${text}`
+  return `${title} changed. Follow this text instead:\n${text}`
+}
+
+/**
+ * Add instruction files (AGENTS.md, CLAUDE.md) and an environment block to
+ * the system prompt.
+ *
+ * - `global`: files that come first, for example `~/.config/AGENTS.md`. `~`
+ *   is the home folder.
+ * - Then `files` from each folder between the repo root (the folder with
+ *   `.git`) and `root`, outermost first. With no repo root, only `root`.
+ * - `env` (default `true`): the date, platform, working folder, and git
+ *   repository and branch, read when the session opens.
+ *
+ * At the start of each turn, the plugin checks the mtime of each file. A note
+ * with the new text of a changed file goes after this plugin's other prompts.
+ * Put this plugin last: when no prompt comes after its prompts, an adapter
+ * with mid-conversation changes adds the note to the conversation, and the
+ * prompt cache holds. Else the change is not additive, and the prompt cache
+ * starts again.
+ *
+ * When `read_file` reads a file below `root`, the instruction files in the
+ * folders between `root` and that file are added to the result, once per
+ * file in the session.
+ *
+ * @example
+ * ```ts
+ * projectInstructions({ root: process.cwd(), global: ['~/.config/AGENTS.md'] })
+ * ```
  */
 export function projectInstructions(options: {
   root: string
   files?: ReadonlyArray<string>
+  global?: ReadonlyArray<string>
+  env?: boolean
 }) {
-  const files = options.files ?? ['AGENTS.md', 'CLAUDE.md']
+  const { files: names = ['AGENTS.md', 'CLAUDE.md'], env = true } = options
   return definePlugin({
     name: 'tanstack/project-instructions',
     setup: async () => {
-      const found: Array<string> = []
-      for (const file of files) {
-        const text = await readIfPresent(resolve(options.root, file))
-        if (text?.trim())
-          found.push(`Project instructions from ${file}:\n${text.trim()}`)
+      const root = resolve(options.root)
+      const { folders, isRepo } = repoFolders(root)
+      const shownPath = (path: string) =>
+        relative(root, path).split(sep).join('/')
+      const globals = (options.global ?? []).map((path) => ({
+        path: resolve(path.replace(/^~(?=$|[\\/])/, homedir())),
+        title: `Global instructions from ${path}`,
+      }))
+      const projects = folders.flatMap((dir) =>
+        names.map((name) => ({
+          path: join(dir, name),
+          title: `Project instructions from ${shownPath(join(dir, name))}`,
+        })),
+      )
+      const files = [...globals, ...projects].map((file) => ({
+        ...file,
+        mtimeMs: mtimeOf(file.path),
+        text: textOf(file.path),
+      }))
+      const envBlock = env ? [await environment(root, isRepo)] : []
+      /** The prompt with each file as it is now. */
+      const current = () => [
+        ...files
+          .filter((file) => file.text !== '')
+          .map((file) => `${file.title}:\n${file.text}`),
+        ...envBlock,
+      ]
+      const sections = current()
+      const slots = files.length + envBlock.length + SPARE_SLOTS
+
+      /** Add a note for each file that changed since the last check. */
+      const refresh = () => {
+        const notes: Array<string> = []
+        for (const file of files) {
+          const mtimeMs = mtimeOf(file.path)
+          if (mtimeMs === file.mtimeMs) continue
+          const before = file.text
+          file.mtimeMs = mtimeMs
+          file.text = textOf(file.path)
+          if (file.text !== before)
+            notes.push(changeNote(file.title, before, file.text))
+        }
+        // ponytail: with no spare slot left, the prompt is built again. That
+        // one change is not added to the conversation.
+        if (sections.length + notes.length > slots) {
+          sections.splice(0, sections.length, ...current())
+        } else {
+          sections.push(...notes)
+        }
+      }
+
+      /** Nested instruction files the model already got. */
+      const given = new Set<string>()
+      const afterRead = async (path: string) => {
+        const inside = relative(root, path)
+        const isBelowRoot =
+          inside !== '' && !inside.startsWith('..') && !isAbsolute(inside)
+        if (!isBelowRoot) return undefined
+        const notes: Array<string> = []
+        // The folders below `root`, down to the folder of the file.
+        const parts = inside.split(sep).slice(0, -1)
+        let dir = root
+        for (const part of parts) {
+          dir = join(dir, part)
+          for (const name of names) {
+            const file = join(dir, name)
+            if (given.has(file)) continue
+            const text = textOf(file)
+            if (text === '') continue
+            given.add(file)
+            // The model just read this file, so it has the text.
+            if (file !== path) {
+              notes.push(`Instructions from ${shownPath(file)}:\n${text}`)
+            }
+          }
+        }
+        return notes.length > 0 ? notes.join('\n\n') : undefined
+      }
+
+      return {
+        // One prompt per slot. Empty slots are left out. The harness reads
+        // the prompts in order each turn, so slot 0 checks the files first.
+        prompts: Array.from({ length: slots }, (_, index) => () => {
+          if (index === 0) refresh()
+          return sections[index] ?? ''
+        }),
+        contribute: [WorkspaceHooks.item({ afterRead })],
       }
-      return { prompts: found }
     },
   })
 }
 
-/** Split `---` frontmatter from a Markdown file. */
-function splitFrontmatter(text: string): {
-  description?: string
-  body: string
-} {
+/** A frontmatter value: text, or a list from `[a, b]` or `- a` lines. */
+export type FrontmatterValue = string | Array<string>
+
+/** The text without the quotes around it: `"a"` and `'a'` become `a`. */
+function unquote(value: string) {
+  return value.trim().replace(/^(["'])(.*)\1$/, '$2')
+}
+
+/**
+ * Split `---` frontmatter from a Markdown file. It reads `key: value`
+ * lines and lists: `key: [a, b]`, or `key:` with `- a` lines under it.
+ * Nested values are not read.
+ */
+export function splitFrontmatter(text: string) {
+  const fields: Record<string, FrontmatterValue> = {}
   const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text)
-  if (!match) return { body: text }
-  const description = /^description:\s*(.+)$/m.exec(match[1] ?? '')?.[1]?.trim()
-  return {
-    ...(description ? { description } : {}),
-    body: text.slice(match[0].length),
+  if (!match) return { fields, body: text }
+  // The list that `- a` lines add to: the last `key:` with no value.
+  let list: Array<string> | undefined
+  const lines = (match[1] ?? '').split(/\r?\n/)
+  for (const line of lines) {
+    const item = /^\s*-\s+(.*)$/.exec(line)
+    if (item && list) {
+      list.push(unquote(item[1] ?? ''))
+      continue
+    }
+    list = undefined
+    const pair = /^([\w-]+):(.*)$/.exec(line)
+    if (!pair) continue
+    const key = pair[1] ?? ''
+    const value = (pair[2] ?? '').trim()
+    const inline = /^\[(.*)\]$/.exec(value)
+    if (value === '') {
+      list = []
+      fields[key] = list
+    } else if (inline) {
+      fields[key] = (inline[1] ?? '')
+        .split(',')
+        .map(unquote)
+        .filter((entry) => entry !== '')
+    } else {
+      fields[key] = unquote(value)
+    }
   }
+  return { fields, body: text.slice(match[0].length) }
+}
+
+/**
+ * The Markdown files in `dir`: the name without `.md`, the frontmatter
+ * fields, and the body. A folder that cannot be read has no files.
+ */
+export async function readMarkdownFiles(dir: string) {
+  let files: Array<string> = []
+  try {
+    files = (await readdir(dir)).filter((file) => extname(file) === '.md')
+  } catch {
+    return []
+  }
+  return Promise.all(
+    files.map(async (file) => ({
+      name: basename(file, '.md'),
+      ...splitFrontmatter(await readFile(resolve(dir, file), 'utf8')),
+    })),
+  )
 }
 
 /**
@@ -58,22 +288,15 @@ export function fileCommands(options: { dir: string }) {
   return definePlugin({
     name: 'tanstack/file-commands',
     setup: async (ctx) => {
-      let names: Array<string> = []
-      try {
-        names = (await readdir(options.dir)).filter(
-          (file) => extname(file) === '.md',
-        )
-      } catch {
-        return {}
-      }
+      const files = await readMarkdownFiles(options.dir)
       const commands: Record<string, AnyCommand> = {}
-      for (const file of names) {
-        const name = basename(file, '.md')
-        const { description, body } = splitFrontmatter(
-          await readFile(resolve(options.dir, file), 'utf8'),
-        )
+      for (const { name, fields, body } of files) {
+        const { description } = fields
         commands[name] = defineCommand({
-          description: description ?? `Run ${file}`,
+          description:
+            typeof description === 'string' && description !== ''
+              ? description
+              : `Run ${name}.md`,
           run: (input: unknown) => {
             const args =
               typeof input === 'string'
diff --git a/packages/ai-harness/src/first-party/question.ts b/packages/ai-harness/src/first-party/question.ts
new file mode 100644
index 0000000000..7b59088692
--- /dev/null
+++ b/packages/ai-harness/src/first-party/question.ts
@@ -0,0 +1,189 @@
+import { toolDefinition } from '@tanstack/ai'
+import { definePlugin } from '../plugins'
+import { isRecord } from '../utils'
+
+/** One question the model asks, as the tool input has it. */
+interface ToolQuestion {
+  question: string
+  header?: string
+  options: Array<{ label: string; description?: string }>
+  multiple?: boolean
+}
+
+const NO_ANSWER = 'The user did not answer.'
+
+function isOption(value: unknown) {
+  return (
+    isRecord(value) &&
+    typeof value.label === 'string' &&
+    (value.description === undefined || typeof value.description === 'string')
+  )
+}
+
+function isToolQuestion(value: unknown): value is ToolQuestion {
+  return (
+    isRecord(value) &&
+    typeof value.question === 'string' &&
+    (value.header === undefined || typeof value.header === 'string') &&
+    Array.isArray(value.options) &&
+    value.options.every(isOption) &&
+    (value.multiple === undefined || typeof value.multiple === 'boolean')
+  )
+}
+
+/** The text the user sees: the question, the numbered options, and how to answer. */
+function messageOf(item: ToolQuestion) {
+  const title = item.header ? `${item.header}: ${item.question}` : item.question
+  const options = item.options.map(
+    (option, index) =>
+      `${index + 1}. ${option.label}${option.description ? ` - ${option.description}` : ''}`,
+  )
+  const how =
+    item.multiple === true
+      ? 'Type one or more numbers or labels, split by commas, or your own answer.'
+      : 'Type a number or a label, or your own answer.'
+  return [title, ...options, how].join('\n')
+}
+
+/**
+ * The answer shape, for hosts that render a form: one label, or a list of
+ * labels. Hosts that show a text box send the typed text, and the tool reads it.
+ */
+function answerSchema(item: ToolQuestion) {
+  const choice = {
+    type: 'string',
+    enum: item.options.map((option) => option.label),
+  }
+  return item.multiple === true
+    ? { type: 'array', items: choice, minItems: 1, uniqueItems: true }
+    : choice
+}
+
+/** The option `text` names, by its label (any letter case) or its number. */
+function labelOf(text: string, options: ToolQuestion['options']) {
+  const lower = text.toLowerCase()
+  const byLabel = options.find(
+    (option) => option.label.trim().toLowerCase() === lower,
+  )
+  if (byLabel) return byLabel.label
+  return /^\d+$/.test(text) ? options[Number(text) - 1]?.label : undefined
+}
+
+/**
+ * The answer line for the model: the picked labels, or the user's own
+ * words. `undefined` when the reply has no text.
+ */
+function readAnswer(reply: unknown, item: ToolQuestion) {
+  const isSplit = item.multiple === true && typeof reply === 'string'
+  const parts = Array.isArray(reply)
+    ? reply
+    : isSplit
+      ? reply.split(',')
+      : [reply]
+  const texts = parts
+    .map((part) =>
+      typeof part === 'string' || typeof part === 'number'
+        ? String(part).trim()
+        : '',
+    )
+    .filter((text) => text !== '')
+  if (texts.length === 0) return undefined
+  const picked = texts
+    .map((text) => labelOf(text, item.options))
+    .filter((label) => label !== undefined)
+  const isPicked =
+    picked.length === texts.length &&
+    (item.multiple === true || picked.length === 1)
+  if (isPicked) return `Answer: ${[...new Set(picked)].join(', ')}`
+  const own = typeof reply === 'string' ? reply.trim() : texts.join(', ')
+  return `Own answer: ${own}`
+}
+
+/**
+ * Add a `question` tool: the model asks the user one to four questions,
+ * each with two to six options, and waits for the answers. Each question
+ * goes to the user through `ctx.session.ask`, one at a time. The user picks
+ * by number or label, or types their own answer. With no answer, or when
+ * the session closes, the model gets a tool error.
+ *
+ * @example
+ * ```ts
+ * plugins: () => [question()]
+ * ```
+ */
+export function question() {
+  return definePlugin({
+    name: 'tanstack/question',
+    setup: (ctx) => ({
+      tools: [
+        toolDefinition({
+          name: 'question',
+          description:
+            'Ask the user one or more questions, each with options, and wait for the answers. Use it when you need a decision or a preference from the user to continue. The user can also type their own answer.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              questions: {
+                type: 'array',
+                minItems: 1,
+                maxItems: 4,
+                items: {
+                  type: 'object',
+                  properties: {
+                    question: {
+                      type: 'string',
+                      description: 'The full question.',
+                    },
+                    header: {
+                      type: 'string',
+                      description: 'A short label for the question.',
+                    },
+                    options: {
+                      type: 'array',
+                      minItems: 2,
+                      maxItems: 6,
+                      items: {
+                        type: 'object',
+                        properties: {
+                          label: { type: 'string' },
+                          description: { type: 'string' },
+                        },
+                        required: ['label'],
+                      },
+                    },
+                    multiple: {
+                      type: 'boolean',
+                      description: 'The user can pick more than one option.',
+                    },
+                  },
+                  required: ['question', 'options'],
+                },
+              },
+            },
+            required: ['questions'],
+          },
+          // Asking again after a crash has no side effect.
+          replay: 'safe',
+        }).server(async (args: unknown) => {
+          const items =
+            isRecord(args) && Array.isArray(args.questions)
+              ? args.questions
+              : []
+          if (!items.every(isToolQuestion))
+            throw new Error('Each question needs a question and options.')
+          const answers: Array<string> = []
+          for (const item of items) {
+            // A closed session rejects the question: that is no answer too.
+            const reply = await ctx.session
+              .ask({ message: messageOf(item), schema: answerSchema(item) })
+              .catch(() => undefined)
+            const answer = readAnswer(reply, item)
+            if (answer === undefined) throw new Error(NO_ANSWER)
+            answers.push(`${item.question}\n${answer}`)
+          }
+          return answers.join('\n\n')
+        }),
+      ],
+    }),
+  })
+}
diff --git a/packages/ai-harness/src/first-party/session-tools.ts b/packages/ai-harness/src/first-party/session-tools.ts
index 8e9a2c0c4e..dab01316e8 100644
--- a/packages/ai-harness/src/first-party/session-tools.ts
+++ b/packages/ai-harness/src/first-party/session-tools.ts
@@ -6,6 +6,7 @@ import type {
   AnyTextAdapter,
   KeyedAdapter,
   ModelMessage,
+  UsageInfo,
 } from '@tanstack/ai'
 
 const SUMMARY_PROMPT =
@@ -91,6 +92,48 @@ interface UsageTotals {
    * the model's context the conversation fills now.
    */
   contextTokens: number
+  /** The cost in USD of the priced model calls. Only with the `model` option. */
+  cost?: number
+  /** The model calls that the `model` option had no prices for. */
+  unpricedCalls?: number
+}
+
+/** Prices in USD per 1M tokens: the `cost` of an `@tanstack/ai-models` record. */
+interface ModelPrices {
+  input: number
+  output: number
+  cacheRead?: number
+  cacheWrite?: number
+}
+
+/** The usage of an index entry before the host adds the tokens of a turn. */
+const NO_TOKENS = {
+  turns: 0,
+  promptTokens: 0,
+  completionTokens: 0,
+  totalTokens: 0,
+  cachedTokens: 0,
+  cacheWriteTokens: 0,
+}
+
+/**
+ * The cost in USD of one model call.
+ * ponytail: the formula of `modelCost` in `@tanstack/ai-models`, copied, so
+ * ai-harness does not depend on ai-models.
+ */
+function callCost(prices: ModelPrices, usage: UsageInfo) {
+  const cached = usage.promptTokensDetails?.cachedTokens ?? 0
+  const written = usage.promptTokensDetails?.cacheWriteTokens ?? 0
+  // `promptTokens` counts the cache parts too, and each part has its own price.
+  const uncached = usage.promptTokens - cached - written
+  const part = (price: number | undefined, tokens: number) =>
+    ((price ?? 0) / 1_000_000) * tokens
+  return (
+    part(prices.input, uncached) +
+    part(prices.output, usage.completionTokens) +
+    part(prices.cacheRead, cached) +
+    part(prices.cacheWrite, written)
+  )
 }
 
 /**
@@ -99,8 +142,26 @@ interface UsageTotals {
  * totals, with the input tokens read from and written to the prompt cache.
  * The plugin state also has `contextTokens`, the size of the lead
  * model's context at its latest call, for a UI.
+ *
+ * With `model`, the plugin also prices each model call. `model` gets the
+ * model id of the call and returns its prices in USD per 1M tokens, or
+ * `undefined` when it does not know the model. `/usage` then shows the
+ * cost, and the plugin writes it to `usage.cost` of the session index
+ * entry. A call with no prices adds no cost, and `/usage` says how many
+ * calls it could not price.
+ *
+ * @example
+ * ```ts
+ * import { getModel } from '@tanstack/ai-models'
+ *
+ * plugins: () => [usage({ model: (id) => getModel('anthropic', id) })]
+ * ```
  */
-export function usage() {
+export function usage(
+  options: {
+    model?: (modelId: string) => { cost: ModelPrices } | undefined
+  } = {},
+) {
   return definePlugin({
     name: 'tanstack/usage',
     setup: (ctx) => {
@@ -119,13 +180,40 @@ export function usage() {
         const cache = hasCache
           ? ` (${totals.cachedTokens} cache read, ${totals.cacheWriteTokens} cache write)`
           : ''
-        return `${totals.turns} model calls, ${totals.promptTokens} input tokens${cache}, ${totals.completionTokens} output tokens, ${totals.totalTokens} total.`
+        const tokens = `${totals.turns} model calls, ${totals.promptTokens} input tokens${cache}, ${totals.completionTokens} output tokens, ${totals.totalTokens} total.`
+        if (!options.model) return tokens
+        const unpriced = totals.unpricedCalls ?? 0
+        const note =
+          unpriced > 0
+            ? ` (cost unknown for ${unpriced} ${unpriced === 1 ? 'call' : 'calls'})`
+            : ''
+        return `${tokens} Cost: $${(totals.cost ?? 0).toFixed(4)}${note}.`
+      }
+      // The host adds the tokens of each turn to the index entry. This
+      // plugin writes only `cost`, and keeps the tokens of the entry.
+      const saveCost = async (cost: number) => {
+        const entry = await ctx.session.entry()
+        if (!entry) return
+        // Before the first turn ends, the entry has no usage.
+        const tokens = entry.usage ?? NO_TOKENS
+        // ponytail: read, then write. A host write or another agent's write
+        // between the two can be lost until the next priced call writes the
+        // total again. Upgrade: a change function in updateEntry.
+        await ctx.session.updateEntry({ usage: { ...tokens, cost } })
       }
       const counter = (lead: boolean) =>
         ({
           name: 'tanstack/usage',
-          onUsage: async (_run, info) => {
-            await state.update((totals) => ({
+          onUsage: async (run, info) => {
+            const prices = options.model?.(run.model)?.cost
+            const cost = prices ? callCost(prices, info) : undefined
+            const isUnpriced = options.model !== undefined && cost === undefined
+            const { cost: total } = await state.update((totals) => ({
+              ...totals,
+              ...(cost !== undefined ? { cost: (totals.cost ?? 0) + cost } : {}),
+              ...(isUnpriced
+                ? { unpricedCalls: (totals.unpricedCalls ?? 0) + 1 }
+                : {}),
               turns: totals.turns + 1,
               promptTokens: totals.promptTokens + (info.promptTokens ?? 0),
               completionTokens:
@@ -141,6 +229,10 @@ export function usage() {
                 ? (info.promptTokens ?? totals.contextTokens)
                 : totals.contextTokens,
             }))
+            if (cost === undefined || total === undefined) return
+            // The index is only a list of sessions: a failed write does not
+            // fail the turn. The next priced call writes the total again.
+            await saveCost(total).catch(() => {})
           },
         }) satisfies AnyChatMiddleware
       return {
diff --git a/packages/ai-harness/src/first-party/title.ts b/packages/ai-harness/src/first-party/title.ts
new file mode 100644
index 0000000000..637bcc37ff
--- /dev/null
+++ b/packages/ai-harness/src/first-party/title.ts
@@ -0,0 +1,88 @@
+import { chat } from '@tanstack/ai'
+import { createPluginEvent } from '../extensions'
+import { definePlugin } from '../plugins'
+import { textOf } from './session-tools'
+import type {
+  AnyChatMiddleware,
+  AnyTextAdapter,
+  KeyedAdapter,
+  ModelMessage,
+} from '@tanstack/ai'
+
+const TITLE_PROMPT =
+  'Write a short title for a conversation that starts with the message below. Use at most 60 characters on one line, with no quotes. Answer with the title only.'
+
+/** Sent when the title call fails. The turn does not fail. */
+export const TitleFailed = createPluginEvent<{ message: string }>(
+  'tanstack/title:failed',
+)
+
+/** The first line of `answer`, with no quotes around it, at most 60 characters. */
+function cleanTitle(answer: string) {
+  const line = answer.trim().split('\n')[0] ?? ''
+  return line
+    .replace(/^["'`]+|["'`]+$/g, '')
+    .trim()
+    .slice(0, 60)
+}
+
+/**
+ * Give each session a title. At the first turn of a session with no title,
+ * `adapter` writes a short title from the first user message, and the plugin
+ * saves it as the `title` of the session index entry. The call runs next to
+ * the turn: it does not slow the turn, and a failure does not fail it. A
+ * failure sends a {@link TitleFailed} event, and the next turn tries again.
+ * Without `stores.sessions`, the plugin does nothing.
+ *
+ * @example
+ * ```ts
+ * plugins: () => [title({ adapter: openaiText('gpt-5.4-nano') })]
+ * ```
+ */
+export function title(options: {
+  adapter: AnyTextAdapter | KeyedAdapter<AnyTextAdapter>
+}) {
+  return definePlugin({
+    name: 'tanstack/title',
+    setup: (ctx) => {
+      let isNaming = false
+      const name = async (messages: ReadonlyArray<ModelMessage>) => {
+        const first = messages.find((message) => message.role === 'user')
+        const entry = await ctx.session.entry()
+        // No sessions store, or the session has a title (also after a restart).
+        if (!first || !entry || entry.title) return
+        // ponytail: the first 2000 characters are enough for a title.
+        const message = textOf(first).slice(0, 2000)
+        const answer = await chat({
+          adapter: await ctx.keys.adapter(options.adapter),
+          messages: [{ role: 'user', content: `${TITLE_PROMPT}\n\n${message}` }],
+          stream: false,
+        })
+        const text = cleanTitle(answer)
+        if (text) await ctx.session.updateEntry({ title: text })
+      }
+      return {
+        middleware: [
+          {
+            name: 'tanstack/title',
+            onConfig: (run, config) => {
+              if (run.phase !== 'init' || isNaming) return
+              isNaming = true
+              // Not awaited: the title call never slows or fails the turn.
+              void name(config.messages)
+                .catch((error: unknown) =>
+                  ctx.emit(TitleFailed, {
+                    message:
+                      error instanceof Error ? error.message : String(error),
+                  }),
+                )
+                .finally(() => {
+                  isNaming = false
+                })
+            },
+          } satisfies AnyChatMiddleware,
+        ],
+      }
+    },
+  })
+}
diff --git a/packages/ai-harness/tests/agents.test.ts b/packages/ai-harness/tests/agents.test.ts
new file mode 100644
index 0000000000..fe585a2853
--- /dev/null
+++ b/packages/ai-harness/tests/agents.test.ts
@@ -0,0 +1,377 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '../src'
+import { permissions } from '../src/first-party'
+import { agents } from '../src/first-party/agents'
+import { splitFrontmatter } from '../src/first-party/files'
+import { messageTexts, mockAdapter, text, toolCall } from './helpers'
+import type { AnyTextAdapter } from '@tanstack/ai'
+import type { HarnessPlugin } from '../src'
+import type { AgentProfile } from '../src/first-party/agents'
+
+const tool = (name: string) =>
+  toolDefinition({
+    name,
+    description: `The ${name} tool`,
+    inputSchema: z.object({}),
+  }).server(async () => name)
+
+/**
+ * Open thread `t` with the tools `read_file` and `write_file`. The main
+ * model starts subagents with the single `subagent` tool.
+ */
+async function open(adapter: AnyTextAdapter, plugins: Array<HarnessPlugin>) {
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const session = await host.open(
+    defineHarness({
+      name: 'test/agents',
+      adapter,
+      tools: [tool('read_file'), tool('write_file')],
+      subagents: { agents: [], tool: 'single' },
+      plugins: () => plugins,
+    }),
+    { threadId: 't' },
+  )
+  return { host, session }
+}
+
+/** The names of the tools the model got on one call. */
+function toolNames(call: { tools: Array<{ name: string }> }) {
+  return call.tools.map((entry) => entry.name)
+}
+
+/** The parts of the `subagent` tool these tests read. */
+interface SubagentTool {
+  name: string
+  description: string
+  inputSchema: { properties: { agent: { enum: Array<string> } } }
+}
+
+/** The `subagent` tool the model got on one call. */
+function subagentTool(call: { tools: Array<SubagentTool> }) {
+  return call.tools.find((entry) => entry.name === 'subagent')
+}
+
+/** The system prompts of one call, as one string. */
+function promptsOf(call: { systemPrompts: unknown }) {
+  return JSON.stringify(call.systemPrompts)
+}
+
+describe('splitFrontmatter', () => {
+  it('reads values and both list forms', () => {
+    const file = [
+      '---',
+      'description: "Reviews: code"',
+      'tools: [read_file, grep]',
+      'models:',
+      '  - fast',
+      "  - 'smart'",
+      '---',
+      'Body',
+    ].join('\n')
+    expect(splitFrontmatter(file)).toEqual({
+      fields: {
+        description: 'Reviews: code',
+        tools: ['read_file', 'grep'],
+        models: ['fast', 'smart'],
+      },
+      body: 'Body',
+    })
+  })
+
+  it('keeps a file without frontmatter as the body', () => {
+    expect(splitFrontmatter('Just text')).toEqual({
+      fields: {},
+      body: 'Just text',
+    })
+  })
+})
+
+describe('agents', () => {
+  it('offers build and plan as primary agents, and general and explore as subagents', async () => {
+    const { adapter, calls } = mockAdapter([() => text('hi')])
+    const { host, session } = await open(adapter, [
+      agents({ adapter: () => adapter }),
+    ])
+
+    expect(await session.command('agent')).toBe(
+      'Agent: build. Agents: build, plan.',
+    )
+    await session.prompt('hi')
+
+    expect(subagentTool(calls[0])?.inputSchema.properties.agent.enum).toEqual([
+      'general',
+      'explore',
+    ])
+    expect(promptsOf(calls[0])).toContain('You are the build agent.')
+    await host.close()
+  })
+
+  it('switches to plan with /agent: the next turn gets its prompt and read-only tools', async () => {
+    const { adapter, calls } = mockAdapter([
+      () => text('built'),
+      () => text('planned'),
+    ])
+    const { host, session } = await open(adapter, [
+      agents({ adapter: () => adapter }),
+    ])
+
+    await session.prompt('build it')
+    expect(await session.command('agent', 'plan')).toBe(
+      'Agent: plan. It applies at the next turn.',
+    )
+    await session.prompt('plan it')
+
+    expect(toolNames(calls[0])).toEqual(['read_file', 'write_file', 'subagent'])
+    expect(toolNames(calls[1])).toEqual(['read_file'])
+    expect(promptsOf(calls[1])).toContain('You are the plan agent.')
+    expect(promptsOf(calls[1])).not.toContain('You are the build agent.')
+    expect(await session.command('agent', 'nope')).toBe(
+      'Unknown agent "nope". Agents: build, plan.',
+    )
+    await host.close()
+  })
+
+  it('switches the primary agent with the agent setting', async () => {
+    const { adapter, calls } = mockAdapter([() => text('planned')])
+    const { host, session } = await open(adapter, [
+      agents({ adapter: () => adapter }),
+    ])
+
+    expect((await session.setConfig('agent', 'plan')).status).toBe('accepted')
+    // A subagent is not a primary agent.
+    expect((await session.setConfig('agent', 'general')).status).toBe(
+      'rejected',
+    )
+    await session.prompt('plan it')
+
+    expect(toolNames(calls[0])).toEqual(['read_file'])
+    await host.close()
+  })
+
+  it('switches the model when the agent has one, and keeps the harness model when not', async () => {
+    const main = mockAdapter([() => text('from main')])
+    const fast = mockAdapter([() => text('from fast')])
+    const byModel = (model: string) => {
+      if (model !== 'fast-model') throw new Error(`Unknown model ${model}`)
+      return fast.adapter
+    }
+    const quick: AgentProfile = {
+      name: 'quick',
+      description: 'Answers fast',
+      mode: 'primary',
+      model: 'fast-model',
+    }
+    const { host, session } = await open(main.adapter, [
+      agents({ adapter: byModel, agents: [quick] }),
+    ])
+
+    expect(await session.prompt('one')).toEqual({ text: 'from main' })
+    await session.command('agent', 'quick')
+    expect(await session.prompt('two')).toEqual({ text: 'from fast' })
+    await host.close()
+  })
+
+  it('makes the call after `steps` model calls with no tool calls, then stops', async () => {
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('read_file', {}, 'c1'),
+      () => toolCall('read_file', {}, 'c2'),
+      () => toolCall('read_file', {}, 'c3'),
+      () => text('never asked'),
+    ])
+    const short: AgentProfile = {
+      name: 'short',
+      description: 'Two steps',
+      mode: 'primary',
+      steps: 2,
+    }
+    const { host, session } = await open(adapter, [
+      agents({ adapter: () => adapter, agents: [short], default: 'short' }),
+    ])
+
+    await session.prompt('go')
+
+    expect(calls.map((call) => call.toolChoice)).toEqual([
+      undefined,
+      undefined,
+      'none',
+    ])
+    expect(promptsOf(calls[1])).not.toContain('step limit')
+    expect(promptsOf(calls[2])).toContain('step limit')
+    await host.close()
+  })
+
+  it('runs a subagent agent as a child of the subagent tool', async () => {
+    const lead = mockAdapter([
+      () =>
+        toolCall('subagent', { agent: 'explore', prompt: 'Find the config' }),
+      () => text('Done.'),
+    ])
+    const child = mockAdapter(() => text('It is in config.ts'))
+    const models: Array<string> = []
+    const { host, session } = await open(lead.adapter, [
+      agents({
+        adapter: (model) => {
+          models.push(model)
+          return child.adapter
+        },
+      }),
+    ])
+
+    await session.prompt('Where is the config?')
+
+    // Without its own model, the child uses the model of the main turn.
+    expect(models).toEqual(['test-model'])
+    expect(toolNames(child.calls[0])).toEqual(['read_file'])
+    expect(promptsOf(child.calls[0])).toContain('You are a fast search agent.')
+    expect(messageTexts(child.calls[0]).at(-1)).toBe('Find the config')
+    expect(JSON.stringify(lead.calls[1].messages)).toContain(
+      'It is in config.ts',
+    )
+    await host.close()
+  })
+
+  it('applies the permission rules of an agent only while it is the primary agent', async () => {
+    const { adapter, calls } = mockAdapter([
+      () => text('one'),
+      () => text('two'),
+    ])
+    const careful: AgentProfile = {
+      name: 'careful',
+      description: 'Never writes',
+      mode: 'primary',
+      permissions: [{ tool: 'write_file', decision: 'deny' }],
+    }
+    const { host, session } = await open(adapter, [
+      permissions(),
+      agents({ adapter: () => adapter, agents: [careful] }),
+    ])
+
+    await session.command('agent', 'careful')
+    await session.prompt('one')
+    await session.command('agent', 'build')
+    await session.prompt('two')
+
+    expect(toolNames(calls[0])).toEqual(['read_file', 'subagent'])
+    expect(toolNames(calls[1])).toEqual(['read_file', 'write_file', 'subagent'])
+    await host.close()
+  })
+
+  it('replaces a built-in agent with one of the same name', async () => {
+    const { adapter, calls } = mockAdapter([() => text('planned')])
+    const plan: AgentProfile = {
+      name: 'plan',
+      description: 'My plan',
+      mode: 'primary',
+      system: 'My own plan prompt.',
+    }
+    const { host, session } = await open(adapter, [
+      agents({ adapter: () => adapter, agents: [plan] }),
+    ])
+
+    expect(await session.command('agent')).toBe(
+      'Agent: build. Agents: build, plan.',
+    )
+    await session.command('agent', 'plan')
+    await session.prompt('plan it')
+
+    expect(toolNames(calls[0])).toEqual(['read_file', 'write_file', 'subagent'])
+    expect(promptsOf(calls[0])).toContain('My own plan prompt.')
+    await host.close()
+  })
+
+  it('drops the built-ins, and leaves hidden agents out of the list', async () => {
+    const { adapter, calls } = mockAdapter([() => text('hi')])
+    const { host, session } = await open(adapter, [
+      agents({
+        adapter: () => adapter,
+        builtIns: false,
+        agents: [
+          { name: 'solo', description: 'The only agent', mode: 'primary' },
+          {
+            name: 'secret',
+            description: 'Not listed',
+            mode: 'primary',
+            hidden: true,
+          },
+        ],
+      }),
+    ])
+
+    expect(await session.command('agent')).toBe('Agent: solo. Agents: solo.')
+    await session.prompt('hi')
+
+    expect(toolNames(calls[0])).toEqual(['read_file', 'write_file'])
+    await host.close()
+  })
+})
+
+describe('agents from Markdown files', () => {
+  let root = ''
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'harness-agents-'))
+  })
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true })
+  })
+
+  it('loads an agent with its frontmatter fields', async () => {
+    await writeFile(
+      join(root, 'reviewer.md'),
+      [
+        '---',
+        'description: Reviews code',
+        'mode: all',
+        'model: smart-model',
+        'tools: [read_file]',
+        'steps: 1',
+        '---',
+        'You review code.',
+      ].join('\n'),
+    )
+    const main = mockAdapter([() => text('built')])
+    const smart = mockAdapter([
+      () => toolCall('read_file', {}, 'c1'),
+      () => text('reviewed'),
+    ])
+    const { host, session } = await open(main.adapter, [
+      agents({
+        adapter: (model) =>
+          model === 'smart-model' ? smart.adapter : main.adapter,
+        dirs: [root],
+      }),
+    ])
+
+    expect(await session.command('agent')).toBe(
+      'Agent: build. Agents: build, plan, reviewer.',
+    )
+    await session.prompt('build it')
+    expect(subagentTool(main.calls[0])?.description).toContain(
+      '- reviewer: Reviews code',
+    )
+    await session.command('agent', 'reviewer')
+    await session.prompt('review it')
+
+    expect(toolNames(smart.calls[0])).toEqual(['read_file'])
+    expect(promptsOf(smart.calls[0])).toContain('You review code.')
+    expect(smart.calls.map((call) => call.toolChoice)).toEqual([
+      undefined,
+      'none',
+    ])
+    await host.close()
+  })
+
+  it('refuses an agent file with an unknown mode', async () => {
+    await writeFile(join(root, 'bad.md'), '---\nmode: sometimes\n---\nText')
+    const { adapter } = mockAdapter([])
+
+    await expect(
+      open(adapter, [agents({ adapter: () => adapter, dirs: [root] })]),
+    ).rejects.toThrow('Agent file bad.md: "mode" is not valid.')
+  })
+})
diff --git a/packages/ai-harness/tests/coding-backend.test.ts b/packages/ai-harness/tests/coding-backend.test.ts
index d0c5e65a88..96f27fe3dd 100644
--- a/packages/ai-harness/tests/coding-backend.test.ts
+++ b/packages/ai-harness/tests/coding-backend.test.ts
@@ -40,6 +40,17 @@ describe('hostBackend', () => {
     expect(await hostBackend.stat(join(dir, 'missing'))).toBeUndefined()
   })
 
+  it('removes a file, and refuses a folder', async () => {
+    const file = join(dir, 'a', 'b.txt')
+    await hostBackend.writeFile(file, 'hi')
+    await expect(hostBackend.remove(join(dir, 'a'))).rejects.toThrow()
+    await hostBackend.remove(file)
+    expect(await hostBackend.stat(file)).toBeUndefined()
+    expect(await hostBackend.stat(join(dir, 'a'))).toMatchObject({
+      type: 'dir',
+    })
+  })
+
   it('runs a command with added env, and resolves with its exit code', async () => {
     expect(
       await hostBackend.exec(
@@ -49,6 +60,23 @@ describe('hostBackend', () => {
     ).toEqual({ exitCode: 2, stdout: 'set\n', stderr: '' })
   })
 
+  // The command sleeps for one second. On Windows, `exec` waits for it even
+  // after the timeout kills the shell, so keep it short. It runs outside
+  // `dir`: on Windows, a running command keeps its folder from removal.
+  const sleep = `node -e "setTimeout(function () {}, 1000)"`
+
+  it('gives exit code 124 when the timeout kills a command', async () => {
+    const result = await hostBackend.exec(sleep, { timeoutMs: 100 })
+    expect(result.exitCode).toBe(124)
+  })
+
+  it('gives exit code 1 when the signal stops a command', async () => {
+    const controller = new AbortController()
+    const running = hostBackend.exec(sleep, { signal: controller.signal })
+    controller.abort()
+    expect((await running).exitCode).toBe(1)
+  })
+
   it('starts a background command, then gives its exit code and output', async () => {
     const job = hostBackend.spawn(`node -e "console.log('done')"`, {
       cwd: dir,
diff --git a/packages/ai-harness/tests/coding-formatter.test.ts b/packages/ai-harness/tests/coding-formatter.test.ts
new file mode 100644
index 0000000000..8e6590fa7c
--- /dev/null
+++ b/packages/ai-harness/tests/coding-formatter.test.ts
@@ -0,0 +1,289 @@
+import { tmpdir } from 'node:os'
+import { basename, dirname, join, resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness, definePlugin } from '../src'
+import { workspaceTools } from '../src/first-party/coding'
+import {
+  FormatFailed,
+  formatOnWrite,
+  formatter,
+} from '../src/first-party/coding/formatter'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { WorkspaceBackend } from '../src/first-party/coding/backend'
+import type {
+  FormatFailure,
+  Formatter,
+  FormatterOptions,
+} from '../src/first-party/coding/formatter'
+
+const root = resolve(tmpdir(), 'harness-format')
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+type Exec = (command: string) => Awaited<ReturnType<WorkspaceBackend['exec']>>
+
+const ok: Exec = () => ({ exitCode: 0, stdout: '', stderr: '' })
+
+/** `path` from the root, as the fake POSIX shell gets it. */
+const quoted = (path: string) => `'${join(root, path)}'`
+
+/**
+ * A project in memory that starts as `files`, by path from the root. `exec`
+ * answers each command. `runs` lists each command with its options.
+ */
+function project(files: Record<string, string>, exec: Exec = ok) {
+  const store = new Map<string, Uint8Array>()
+  const put = (path: string, content: string) =>
+    store.set(join(root, path), encoder.encode(content))
+  for (const [path, content] of Object.entries(files)) put(path, content)
+  const runs: Array<{ command: string; cwd?: string; timeoutMs?: number }> = []
+  const backend: WorkspaceBackend = {
+    readFile: async (path) => {
+      const data = store.get(path)
+      if (!data) throw new Error(`No file ${path}`)
+      return data
+    },
+    writeFile: async (path, data) => {
+      store.set(path, typeof data === 'string' ? encoder.encode(data) : data)
+    },
+    stat: async (path) => {
+      const data = store.get(path)
+      return data && { type: 'file', size: data.length, mtimeMs: 0 }
+    },
+    readdir: async (dir) =>
+      [...store.keys()]
+        .filter((path) => dirname(path) === dir)
+        .map((path) => ({ name: basename(path), type: 'file' as const })),
+    exec: async (command, options) => {
+      runs.push({ command, cwd: options?.cwd, timeoutMs: options?.timeoutMs })
+      return exec(command)
+    },
+  }
+  const read = (path: string) => decoder.decode(store.get(join(root, path)))
+  return { backend, runs, put, read }
+}
+
+/** Run the hook once for `path` in a project of `files`. */
+async function formatIn(
+  files: Record<string, string>,
+  path: string,
+  options: Omit<FormatterOptions, 'root' | 'backend'> = {},
+  exec: Exec = ok,
+) {
+  const { backend, runs } = project(files, exec)
+  const failures: Array<FormatFailure> = []
+  const afterWrite = formatOnWrite({ root, backend, ...options }, (failure) =>
+    failures.push(failure),
+  )
+  await afterWrite(join(root, path))
+  return { runs, commands: runs.map((run) => run.command), failures }
+}
+
+const prettier = { '.prettierrc': '{}' }
+const mine: Formatter = {
+  name: 'mine',
+  extensions: ['.ts'],
+  command: (file) => `mine ${file}`,
+}
+
+describe('formatOnWrite', () => {
+  it.each([
+    ['.prettierrc', prettier, 'a.ts', 'npx --no-install prettier --write'],
+    [
+      'prettier.config.js',
+      { 'prettier.config.js': '' },
+      'a.css',
+      'npx --no-install prettier --write',
+    ],
+    [
+      'a prettier key in package.json',
+      { 'package.json': '{"prettier": {}}' },
+      'a.md',
+      'npx --no-install prettier --write',
+    ],
+    [
+      'biome.json',
+      { 'biome.json': '{}' },
+      'a.tsx',
+      'npx --no-install biome format --write',
+    ],
+    [
+      '.oxfmtrc.json',
+      { '.oxfmtrc.json': '{}' },
+      'a.ts',
+      'npx --no-install oxfmt',
+    ],
+    [
+      'oxfmt in devDependencies',
+      { 'package.json': '{"devDependencies": {"oxfmt": "^0.59.0"}}' },
+      'a.json',
+      'npx --no-install oxfmt',
+    ],
+    ['ruff.toml', { 'ruff.toml': '' }, 'a.py', 'ruff format'],
+    [
+      '[tool.ruff] in pyproject.toml',
+      { 'pyproject.toml': '[tool.ruff]\nline-length = 88\n' },
+      'a.py',
+      'ruff format',
+    ],
+    ['go.mod', { 'go.mod': 'module a\n' }, 'main.go', 'gofmt -w'],
+    ['Cargo.toml', { 'Cargo.toml': '' }, 'src/main.rs', 'rustfmt'],
+  ])(
+    'detects %s and runs its command in the root',
+    async (_, files, path, command) => {
+      const { runs } = await formatIn(files, path)
+      expect(runs).toEqual([
+        { command: `${command} ${quoted(path)}`, cwd: root, timeoutMs: 20_000 },
+      ])
+    },
+  )
+
+  it.each([
+    ['no config file', {}, 'a.ts'],
+    [
+      'a pyproject.toml without ruff',
+      { 'pyproject.toml': '[project]\n' },
+      'a.py',
+    ],
+    ['a file type no formatter takes', { 'go.mod': 'module a\n' }, 'a.ts'],
+    ['a package.json that is not JSON', { 'package.json': '{' }, 'a.ts'],
+  ])('runs nothing for %s', async (_, files, path) => {
+    expect(await formatIn(files, path)).toEqual({
+      runs: [],
+      commands: [],
+      failures: [],
+    })
+  })
+
+  it('quotes the path, so a space and a & stay in one argument', async () => {
+    const { commands } = await formatIn(prettier, 'src/my file & co.ts')
+    expect(commands).toEqual([
+      `npx --no-install prettier --write '${join(root, 'src', 'my file & co.ts')}'`,
+    ])
+  })
+
+  it('runs a user formatter before the built-in one', async () => {
+    const { commands } = await formatIn(prettier, 'a.ts', {
+      formatters: [mine],
+    })
+    expect(commands).toEqual([`mine ${quoted('a.ts')}`])
+  })
+
+  it('reads the root files for when, and skips a formatter that says no', async () => {
+    const taplo: Formatter = {
+      name: 'taplo',
+      extensions: ['.toml'],
+      command: (file) => `taplo fmt ${file}`,
+      when: async (project) =>
+        (await project.read('taplo.toml')).includes('[formatting]'),
+    }
+    const used = await formatIn({ 'taplo.toml': '[formatting]\n' }, 'a.toml', {
+      formatters: [taplo],
+    })
+    const skipped = await formatIn({}, 'a.toml', { formatters: [taplo] })
+    expect(used.commands).toEqual([`taplo fmt ${quoted('a.toml')}`])
+    expect(skipped.commands).toEqual([])
+  })
+
+  it('runs no built-in formatter with builtins: false', async () => {
+    const { commands } = await formatIn(prettier, 'a.ts', { builtins: false })
+    expect(commands).toEqual([])
+  })
+
+  it('checks the config files once, at the first write', async () => {
+    const { backend, runs, put } = project({})
+    const afterWrite = formatOnWrite({ root, backend }, () => undefined)
+    await afterWrite(join(root, 'a.ts'))
+    put('.prettierrc', '{}')
+    await afterWrite(join(root, 'a.ts'))
+    expect(runs).toEqual([])
+  })
+
+  it.each([
+    [
+      'a non-zero exit, with the first stderr line',
+      { exitCode: 2, stdout: '', stderr: '[error] a.ts: SyntaxError\nat 1:1' },
+      'prettier failed: [error] a.ts: SyntaxError',
+    ],
+    [
+      'a missing formatter, with the exit code',
+      { exitCode: 127, stdout: '', stderr: '' },
+      'prettier failed: exit code 127',
+    ],
+    [
+      'a timeout',
+      { exitCode: 124, stdout: '', stderr: '' },
+      'prettier failed: it took longer than 5 seconds',
+    ],
+  ])('reports %s, and does not throw', async (_, result, message) => {
+    const { runs, failures } = await formatIn(
+      prettier,
+      'a.ts',
+      { timeoutMs: 5000 },
+      () => result,
+    )
+    expect(runs[0]?.timeoutMs).toBe(5000)
+    expect(failures).toEqual([{ path: join(root, 'a.ts'), message }])
+  })
+
+  it('reports a backend that throws, and does not throw', async () => {
+    const { failures } = await formatIn(prettier, 'a.ts', {}, () => {
+      throw new Error('spawn sh ENOENT')
+    })
+    expect(failures).toEqual([
+      { path: join(root, 'a.ts'), message: 'spawn sh ENOENT' },
+    ])
+  })
+})
+
+describe('formatter', () => {
+  it('formats after write_file and edit_file, and a failure keeps the file and the tool result', async () => {
+    const { backend, runs, read } = project(prettier, () => ({
+      exitCode: 2,
+      stdout: '',
+      stderr: 'SyntaxError',
+    }))
+    const failures: Array<FormatFailure> = []
+    const listener = definePlugin({
+      name: 'test/listener',
+      setup: (ctx) => {
+        ctx.on(FormatFailed, (failure) => failures.push(failure))
+      },
+    })
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('write_file', { path: 'a.ts', content: 'let a=1' }, 'c1'),
+      () =>
+        toolCall('edit_file', { path: 'a.ts', old: 'a=1', new: 'a=2' }, 'c2'),
+      () => text('done'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/formatter',
+        adapter,
+        plugins: () => [
+          workspaceTools({ root, backend }),
+          formatter({ root, backend }),
+          listener,
+        ],
+      }),
+      { threadId: 't' },
+    )
+
+    await session.prompt('work')
+    await host.close()
+
+    const command = `npx --no-install prettier --write ${quoted('a.ts')}`
+    const failure = {
+      path: join(root, 'a.ts'),
+      message: 'prettier failed: SyntaxError',
+    }
+    expect(runs.map((run) => run.command)).toEqual([command, command])
+    expect(failures).toEqual([failure, failure])
+    expect(read('a.ts')).toBe('let a=2')
+    expect(JSON.stringify(calls[2].messages)).toContain(
+      'Edited a.ts (1 change).',
+    )
+  })
+})
diff --git a/packages/ai-harness/tests/coding-patch.test.ts b/packages/ai-harness/tests/coding-patch.test.ts
index 0e302f64a7..a43d554e51 100644
--- a/packages/ai-harness/tests/coding-patch.test.ts
+++ b/packages/ai-harness/tests/coding-patch.test.ts
@@ -27,9 +27,10 @@ function patch(...lines: Array<string>) {
 
 /**
  * The patch tool on files in memory that start as `files`. `written` lists
- * the files that the `afterWrite` hook saw, in order.
+ * the files that the `afterWrite` hook saw, in order. With `canRemove:
+ * false`, the backend has no `remove`.
  */
-function workspace(files: Record<string, string>) {
+function workspace(files: Record<string, string>, { canRemove = true } = {}) {
   const store = new Map<string, Uint8Array>()
   for (const [path, text] of Object.entries(files)) {
     store.set(join(root, path), encoder.encode(text))
@@ -43,7 +44,15 @@ function workspace(files: Record<string, string>) {
     writeFile: async (path, data) => {
       store.set(path, typeof data === 'string' ? encoder.encode(data) : data)
     },
-    stat: async () => undefined,
+    remove: canRemove
+      ? async (path) => {
+          if (!store.delete(path)) throw new Error(`No file ${path}`)
+        }
+      : undefined,
+    stat: async (path) => {
+      const data = store.get(path)
+      return data && { type: 'file', size: data.length, mtimeMs: 0 }
+    },
     readdir: async () => [],
     exec: async () => ({ exitCode: 0, stdout: '', stderr: '' }),
   }
@@ -394,6 +403,55 @@ describe('patch tool', () => {
     expect(files.written).toEqual(['a.txt', 'b.txt'])
   })
 
+  it('deletes a file, and runs no hook for it', async () => {
+    const files = workspace({ 'a.txt': 'a\n', 'b.txt': 'b\n' })
+    const result = await files.run(
+      patch('*** Add File: c.txt', '+c', '*** Delete File: a.txt'),
+    )
+    expect(result).toBe('Applied the patch:\nadded c.txt\ndeleted a.txt')
+    expect(files.files()).toEqual({ 'b.txt': 'b\n', 'c.txt': 'c\n' })
+    expect(files.written).toEqual(['c.txt'])
+  })
+
+  it('moves a file, and applies its chunks', async () => {
+    const files = workspace({ 'a.txt': 'one\ntwo\n' })
+    const result = await files.run(
+      patch(
+        '*** Update File: a.txt',
+        '*** Move to: src/b.txt',
+        '@@',
+        ' one',
+        '-two',
+        '+2',
+      ),
+    )
+    expect(result).toBe('Applied the patch:\nmoved a.txt to src/b.txt')
+    expect(files.files()).toEqual({ 'src/b.txt': 'one\n2\n' })
+    expect(files.written).toEqual(['src/b.txt'])
+  })
+
+  it.each([
+    {
+      name: 'a delete of a missing file',
+      lines: ['*** Delete File: missing.txt'],
+      error: 'Cannot delete missing.txt: no such file.',
+    },
+    {
+      name: 'a move onto a file that is there',
+      lines: ['*** Update File: a.txt', '*** Move to: b.txt'],
+      error: 'Cannot move a.txt to b.txt: b.txt already exists.',
+    },
+  ])('refuses $name, and changes nothing', async ({ lines, error }) => {
+    const before = { 'a.txt': 'a\n', 'b.txt': 'b\n', 'd.txt': 'd\n' }
+    const files = workspace(before)
+    await expect(
+      files.run(
+        patch('*** Add File: c.txt', '+c', '*** Delete File: d.txt', ...lines),
+      ),
+    ).rejects.toThrow(error)
+    expect(files.files()).toEqual(before)
+  })
+
   it.each([
     {
       name: 'a delete',
@@ -405,11 +463,14 @@ describe('patch tool', () => {
       lines: ['*** Update File: a.txt', '*** Move to: b.txt'],
       error: 'Cannot move a.txt: the workspace cannot remove files.',
     },
-  ])('refuses $name, and changes nothing', async ({ lines, error }) => {
-    const files = workspace({ 'a.txt': 'a\n' })
-    await expect(
-      files.run(patch('*** Add File: c.txt', '+c', ...lines)),
-    ).rejects.toThrow(error)
-    expect(files.files()).toEqual({ 'a.txt': 'a\n' })
-  })
+  ])(
+    'refuses $name when the backend cannot remove files, and changes nothing',
+    async ({ lines, error }) => {
+      const files = workspace({ 'a.txt': 'a\n' }, { canRemove: false })
+      await expect(
+        files.run(patch('*** Add File: c.txt', '+c', ...lines)),
+      ).rejects.toThrow(error)
+      expect(files.files()).toEqual({ 'a.txt': 'a\n' })
+    },
+  )
 })
diff --git a/packages/ai-harness/tests/coding-read.test.ts b/packages/ai-harness/tests/coding-read.test.ts
new file mode 100644
index 0000000000..2ef0c6eb7c
--- /dev/null
+++ b/packages/ai-harness/tests/coding-read.test.ts
@@ -0,0 +1,282 @@
+import { tmpdir } from 'node:os'
+import { join, resolve, sep } from 'node:path'
+import { beforeAll, describe, expect, it } from 'vitest'
+import { createWorkspaceTools } from '../src/first-party/coding/workspace'
+import type { WorkspaceBackend } from '../src/first-party/coding/backend'
+import type { WorkspaceHooks } from '../src/first-party/workspace-hooks'
+
+/** A backend that keeps files in a map, by absolute path. It runs no commands. */
+function memoryBackend() {
+  const files = new Map<string, Uint8Array>()
+  const backend: WorkspaceBackend = {
+    readFile: async (path) => {
+      const data = files.get(path)
+      if (!data) throw new Error(`No file ${path}`)
+      return data
+    },
+    writeFile: async (path, data) => {
+      files.set(
+        path,
+        typeof data === 'string' ? new TextEncoder().encode(data) : data,
+      )
+    },
+    stat: async (path) => {
+      const data = files.get(path)
+      if (!data) return undefined
+      return { type: 'file', size: data.length, mtimeMs: 0 }
+    },
+    readdir: async (path) => {
+      const prefix = path + sep
+      const paths = [...files.keys()].filter((file) => file.startsWith(prefix))
+      // Like the host, a folder that is not there throws.
+      if (paths.length === 0) throw new Error(`No folder ${path}`)
+      return paths
+        .map((file) => file.slice(prefix.length))
+        .filter((name) => !name.includes(sep))
+        .sort()
+        .map((name) => ({ name, type: 'file' as const }))
+    },
+    exec: async () => ({ exitCode: 0, stdout: '', stderr: '' }),
+  }
+  return backend
+}
+
+const root = resolve(tmpdir(), 'harness-read')
+const backend = memoryBackend()
+
+const ascii = (text: string) => new TextEncoder().encode(text)
+const put = (path: string, data: Uint8Array | string) =>
+  backend.writeFile(join(root, path), data)
+
+/** `read_file` on the memory backend, with `hooks`. */
+function reader(hooks: Array<WorkspaceHooks> = []) {
+  const tool = createWorkspaceTools(
+    { root, backend },
+    { hooks: () => hooks },
+  ).tools.find((item) => item.name === 'read_file')
+  return async (
+    path: string,
+    options: { offset?: number; limit?: number } = {},
+  ) => {
+    if (!tool?.execute) throw new Error('No read_file tool')
+    const result: unknown = await tool.execute({ path, ...options })
+    return result
+  }
+}
+
+const read = reader()
+
+/** The result of `read_file` for a text file. Throws for any other result. */
+async function readText(
+  path: string,
+  options: { offset?: number; limit?: number } = {},
+) {
+  const result = await read(path, options)
+  if (typeof result !== 'string') throw new Error('Not a text result')
+  return result
+}
+
+const PNG = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+const pngPart = {
+  type: 'image',
+  source: { type: 'data', value: 'iVBORw0KGgo=', mimeType: 'image/png' },
+}
+const BINARY = new Uint8Array([0x49, 0x44, 0x00, 0x01])
+
+describe('read_file text', () => {
+  it('reads a file with a byte order mark without the mark', async () => {
+    await put('bom.txt', new Uint8Array([0xef, 0xbb, 0xbf, ...ascii('a\nb\n')]))
+    expect(await read('bom.txt')).toBe('1\ta\n2\tb')
+  })
+
+  it('cuts a line over 2000 characters, and says how much is cut', async () => {
+    await put('long.txt', `${'a'.repeat(2500)}\nshort`)
+    expect(await read('long.txt')).toBe(
+      `1\t${'a'.repeat(2000)}... [line cut: 500 more characters]\n2\tshort`,
+    )
+  })
+
+  it('reads a Git LFS pointer named .png as text', async () => {
+    await put('pointer.png', 'version https://git-lfs.github.com/spec/v1\n')
+    expect(await read('pointer.png')).toBe(
+      '1\tversion https://git-lfs.github.com/spec/v1',
+    )
+  })
+})
+
+describe('read_file pages', () => {
+  beforeAll(async () => {
+    const lines = Array.from({ length: 2500 }, (_, index) => `L${index + 1}`)
+    await put('many.txt', lines.join('\n'))
+  })
+
+  it.each([{}, { limit: 5000 }])(
+    'shows at most 2000 lines, then says where the next page starts (%o)',
+    async (options) => {
+      const lines = (await readText('many.txt', options)).split('\n')
+      expect(lines.slice(0, 2)).toEqual(['1\tL1', '2\tL2'])
+      expect(lines.slice(-3)).toEqual([
+        '2000\tL2000',
+        '',
+        '[Showing lines 1-2000 of 2500. Read more with offset 2001.]',
+      ])
+    },
+  )
+
+  it('reads the next page from its offset to the end, with no note', async () => {
+    const lines = (await readText('many.txt', { offset: 2001 })).split('\n')
+    expect(lines).toHaveLength(500)
+    expect(lines[0]).toBe('2001\tL2001')
+    expect(lines.at(-1)).toBe('2500\tL2500')
+  })
+
+  it('keeps a page under 50 KiB', async () => {
+    // Each line is about 1 KB, so 51 lines fit in 50 KiB.
+    await put(
+      'wide.txt',
+      Array.from({ length: 100 }, () => 'x'.repeat(1000)).join('\n'),
+    )
+    const lines = (await readText('wide.txt')).split('\n')
+    expect(lines.at(-3)).toBe(`51\t${'x'.repeat(1000)}`)
+    expect(lines.at(-1)).toBe(
+      '[Showing lines 1-51 of 100. Read more with offset 52.]',
+    )
+  })
+
+  it('says how many lines there are when offset is past the end', async () => {
+    expect(await read('many.txt', { offset: 3000 })).toBe(
+      '[No lines from line 3000. many.txt has 2500 lines.]',
+    )
+  })
+})
+
+describe('read_file media and binary files', () => {
+  it.each([
+    { file: 'a.png', bytes: PNG, part: pngPart },
+    {
+      file: 'a.jpg',
+      bytes: new Uint8Array([0xff, 0xd8, 0xff, 0xe0]),
+      part: {
+        type: 'image',
+        source: { type: 'data', value: '/9j/4A==', mimeType: 'image/jpeg' },
+      },
+    },
+    {
+      file: 'a.gif',
+      bytes: ascii('GIF89a'),
+      part: {
+        type: 'image',
+        source: { type: 'data', value: 'R0lGODlh', mimeType: 'image/gif' },
+      },
+    },
+    {
+      file: 'a.webp',
+      bytes: new Uint8Array([
+        ...ascii('RIFF'),
+        0,
+        0,
+        0,
+        0,
+        ...ascii('WEBPVP8 '),
+      ]),
+      part: {
+        type: 'image',
+        source: {
+          type: 'data',
+          value: 'UklGRgAAAABXRUJQVlA4IA==',
+          mimeType: 'image/webp',
+        },
+      },
+    },
+    {
+      file: 'a.pdf',
+      bytes: ascii('%PDF-1.7'),
+      part: {
+        type: 'document',
+        source: {
+          type: 'data',
+          value: 'JVBERi0xLjc=',
+          mimeType: 'application/pdf',
+        },
+      },
+    },
+  ])('returns $file as a $part.type part', async ({ file, bytes, part }) => {
+    await put(file, bytes)
+    expect(await read(file)).toEqual([part])
+  })
+
+  it('refuses an image over 5 MB', async () => {
+    const big = new Uint8Array(6 * 1024 * 1024)
+    big.set(PNG)
+    await put('big.png', big)
+    await expect(read('big.png')).rejects.toThrow(
+      'big.png is 6.0 MB. read_file sends images and PDFs up to 5 MB.',
+    )
+  })
+
+  it.each([
+    {
+      file: 'data.bin',
+      expected:
+        'data.bin is a binary file (4 bytes). read_file shows text, images, and PDFs only.',
+    },
+    {
+      file: 'clip.mp3',
+      expected:
+        'clip.mp3 is a binary file (4 bytes, audio/mpeg). read_file shows text, images, and PDFs only.',
+    },
+  ])('says $file is binary, with its size', async ({ file, expected }) => {
+    await put(file, BINARY)
+    expect(await read(file)).toBe(expected)
+  })
+})
+
+describe('read_file on a missing file', () => {
+  beforeAll(async () => {
+    const names = [
+      'src/Button.tsx',
+      'src/button.css',
+      'src/helpers.ts',
+      'src/index.ts',
+      'parts/a1.ts',
+      'parts/a2.ts',
+      'parts/a3.ts',
+      'parts/a4.ts',
+    ]
+    await Promise.all(names.map((name) => put(name, 'x')))
+  })
+
+  it.each([
+    {
+      path: 'src/button.ts',
+      message:
+        'File not found: src/button.ts. Did you mean src/Button.tsx, src/button.css?',
+    },
+    {
+      path: 'src/helpres.ts',
+      message: 'File not found: src/helpres.ts. Did you mean src/helpers.ts?',
+    },
+    {
+      path: 'parts/a.ts',
+      message:
+        'File not found: parts/a.ts. Did you mean parts/a1.ts, parts/a2.ts, parts/a3.ts?',
+    },
+    { path: 'nowhere/x.ts', message: 'File not found: nowhere/x.ts.' },
+  ])('names similar files for $path', async ({ path, message }) => {
+    await expect(read(path)).rejects.toThrow(message)
+  })
+})
+
+describe('read_file hooks', () => {
+  it('adds afterRead text to a text file, not to media or binary files', async () => {
+    const readWithHook = reader([{ afterRead: async () => 'hook note' }])
+    await put('hooked.txt', 'hello')
+    await put('hooked.png', PNG)
+    await put('hooked.bin', BINARY)
+    expect(await readWithHook('hooked.txt')).toBe('1\thello\n\nhook note')
+    expect(await readWithHook('hooked.png')).toEqual([pngPart])
+    expect(await readWithHook('hooked.bin')).toBe(
+      'hooked.bin is a binary file (4 bytes). read_file shows text, images, and PDFs only.',
+    )
+  })
+})
diff --git a/packages/ai-harness/tests/coding-search.test.ts b/packages/ai-harness/tests/coding-search.test.ts
new file mode 100644
index 0000000000..895a6e906d
--- /dev/null
+++ b/packages/ai-harness/tests/coding-search.test.ts
@@ -0,0 +1,453 @@
+import { mkdtemp, rm, symlink } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve, sep } from 'node:path'
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
+import { hostBackend } from '../src/first-party/coding/backend'
+import { quoteArg } from '../src/first-party/coding/search'
+import { createWorkspaceTools } from '../src/first-party/coding/workspace'
+import type { WorkspaceBackend } from '../src/first-party/coding/backend'
+
+// The bundled rg of `@vscode/ripgrep`. It points at a file that exists, so
+// no test needs the real binary. No test runs it.
+const ripgrep = vi.hoisted(() => ({ rgPath: process.execPath }))
+vi.mock('@vscode/ripgrep', () => ({
+  get rgPath() {
+    return ripgrep.rgPath
+  },
+}))
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  ripgrep.rgPath = process.execPath
+})
+
+interface ExecResult {
+  exitCode: number
+  stdout: string
+  stderr: string
+}
+
+const ok = (stdout: string): ExecResult => ({ exitCode: 0, stdout, stderr: '' })
+const NOT_FOUND: ExecResult = { exitCode: 127, stdout: '', stderr: 'not found' }
+const GIT = 'git ls-files -z --cached --others --exclude-standard'
+const NOT_GIT: ExecResult = {
+  exitCode: 128,
+  stdout: '',
+  stderr: 'fatal: not a git repository',
+}
+const FILES_NOTE =
+  '[Not all files are shown. Use a pattern or a folder to see fewer.]'
+const MATCHES_NOTE =
+  '[Not all matches are shown. Use a narrower pattern, glob, or folder.]'
+
+const root = resolve(tmpdir(), 'coding-search')
+const hasGit = (await hostBackend.exec('git --version')).exitCode === 0
+// A real process can take seconds to start on a busy machine.
+const SPAWN_TIMEOUT = 60_000
+
+/**
+ * A backend with `files` in memory, by path from `root`. `script` answers
+ * each command. A command that it does not answer is not found.
+ */
+function fakeBackend(
+  files: Record<string, string>,
+  script: (command: string) => ExecResult | undefined = () => undefined,
+) {
+  const encoder = new TextEncoder()
+  const byPath = new Map(
+    Object.entries(files).map(([path, text]) => [
+      join(root, path),
+      encoder.encode(text),
+    ]),
+  )
+  const commands: Array<string> = []
+  const backend: WorkspaceBackend = {
+    readFile: async (path) => {
+      const data = byPath.get(path)
+      if (!data) throw new Error(`No file ${path}`)
+      return data
+    },
+    writeFile: async () => {
+      throw new Error('Read only')
+    },
+    stat: async (path) => {
+      const data = byPath.get(path)
+      if (!data) return undefined
+      return { type: 'file', size: data.length, mtimeMs: 0 }
+    },
+    readdir: async (path) => {
+      const prefix = path + sep
+      const entries = new Map<string, 'file' | 'dir'>()
+      for (const file of byPath.keys()) {
+        if (!file.startsWith(prefix)) continue
+        const [name = '', ...rest] = file.slice(prefix.length).split(sep)
+        entries.set(name, rest.length > 0 ? 'dir' : 'file')
+      }
+      // Sorted by name, like the host.
+      return [...entries]
+        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .map(([name, type]) => ({ name, type }))
+    },
+    exec: async (command) => {
+      commands.push(command)
+      return script(command) ?? NOT_FOUND
+    },
+  }
+  return { backend, commands }
+}
+
+/** `list_files` and `grep` on `backend`, with the workspace at `folder`. */
+function searchOn(backend: WorkspaceBackend, folder = root) {
+  const { tools } = createWorkspaceTools({ root: folder, backend })
+  const run = async (name: string, args: object) => {
+    const tool = tools.find((each) => each.name === name)
+    if (!tool?.execute) throw new Error(`No tool ${name}`)
+    const result: unknown = await tool.execute(args)
+    if (typeof result !== 'string') throw new Error(`${name} gave no text`)
+    return result
+  }
+  return {
+    listFiles: (args: object = {}) => run('list_files', args),
+    grep: (args: object) => run('grep', args),
+  }
+}
+
+/** Run `script` for the commands of the host backend, not a real shell. */
+function scriptHostExec(script: (command: string) => ExecResult | undefined) {
+  return vi
+    .spyOn(hostBackend, 'exec')
+    .mockImplementation(async (command) => script(command) ?? NOT_FOUND)
+}
+
+describe('list_files and grep engines', () => {
+  const long = `two${'x'.repeat(3000)}`
+  const files = {
+    'src/b.ts': 'const two = 2\r\n',
+    'src/a.ts': 'one\ntwo\n',
+    'long.txt': `${long}\n`,
+    '.github/ci.yml': 'two: yes\n',
+    'image.png': 'two\0',
+    'node_modules/pkg/i.js': 'two\n',
+    '.git/HEAD': 'two\n',
+  }
+  // What rg prints for `files`: not sorted, with `./`, NUL after each path.
+  // A long line is cut after 2000 bytes, with a note after it.
+  const rgFiles = './src/b.ts\0./src/a.ts\0./long.txt\0./image.png\0./.github/ci.yml\0'
+  const rgMatches = [
+    './src/b.ts\x001:const two = 2\r',
+    './.github/ci.yml\x001:two: yes',
+    `./long.txt\x001:${long.slice(0, 2000)} [... omitted end of long line]`,
+    './src/a.ts\x002:two',
+    '',
+  ].join('\n')
+  const gitFiles =
+    '.github/ci.yml\0image.png\0long.txt\0node_modules/pkg/i.js\0src/a.ts\0src/b.ts\0'
+
+  const engines = [
+    {
+      name: 'rg on the PATH',
+      script: (command: string) => {
+        if (command === 'rg --version') return ok('ripgrep 14.1.0')
+        if (command.startsWith('rg --files ')) return ok(rgFiles)
+        const isGrepForTwo =
+          command.startsWith('rg --line-number ') &&
+          command.endsWith(` -e 'two' .`)
+        return isGrepForTwo ? ok(rgMatches) : undefined
+      },
+      commands: [
+        'rg --version',
+        expect.stringMatching(/^rg --files /),
+        expect.stringMatching(/^rg --line-number /),
+      ],
+    },
+    {
+      name: 'git ls-files',
+      script: (command: string) => (command === GIT ? ok(gitFiles) : undefined),
+      commands: ['rg --version', GIT, GIT],
+    },
+    {
+      name: 'the JS walk',
+      script: (command: string) => (command === GIT ? NOT_GIT : undefined),
+      commands: ['rg --version', GIT, GIT],
+    },
+  ]
+
+  it.each(engines)(
+    '$name gives the same files and matches',
+    async ({ script, commands }) => {
+      const fake = fakeBackend(files, script)
+      const { listFiles, grep } = searchOn(fake.backend)
+
+      expect(await listFiles()).toBe(
+        '.github/ci.yml\nimage.png\nlong.txt\nsrc/a.ts\nsrc/b.ts',
+      )
+      expect(await grep({ pattern: 'two' })).toBe(
+        [
+          '.github/ci.yml:1: two: yes',
+          `long.txt:1: two${'x'.repeat(1997)}`,
+          'src/a.ts:2: two',
+          'src/b.ts:1: const two = 2',
+        ].join('\n'),
+      )
+      // The engine order, and rg looked for once.
+      expect(fake.commands).toEqual(commands)
+
+      expect(await listFiles({ pattern: 'src/**' })).toBe('src/a.ts\nsrc/b.ts')
+      expect(await grep({ pattern: 'two', glob: 'src/**' })).toBe(
+        'src/a.ts:2: two\nsrc/b.ts:1: const two = 2',
+      )
+    },
+  )
+
+  it('runs the bundled rg with the host backend, and does not look on the PATH', async () => {
+    const exec = scriptHostExec(() => ok('./a.ts\0'))
+    expect(await searchOn(hostBackend, tmpdir()).listFiles()).toBe('a.ts')
+    const commands = exec.mock.calls.map(([command]) => command)
+    expect(commands).toHaveLength(1)
+    const bundled = quoteArg(process.execPath, process.platform)
+    expect(commands[0]?.startsWith(`${bundled} --files `)).toBe(true)
+  })
+
+  it('looks for rg on the PATH when the bundled binary is missing', async () => {
+    ripgrep.rgPath = join(tmpdir(), 'no-such-rg-binary')
+    const exec = scriptHostExec((command) => {
+      if (command === 'rg --version') return ok('ripgrep 14.1.0')
+      return command.startsWith('rg --files ') ? ok('./a.ts\0') : undefined
+    })
+    expect(await searchOn(hostBackend, tmpdir()).listFiles()).toBe('a.ts')
+    expect(exec.mock.calls.map(([command]) => command)).toEqual([
+      'rg --version',
+      expect.stringMatching(/^rg --files /),
+    ])
+  })
+
+  it.each([
+    {
+      exitCode: 2,
+      stderr: 'regex parse error',
+      message: 'The search failed: regex parse error',
+    },
+    {
+      exitCode: 124,
+      stderr: '',
+      message: 'The search failed: it took longer than 30 seconds',
+    },
+  ])(
+    'throws when rg ends with exit code $exitCode and no output',
+    async ({ exitCode, stderr, message }) => {
+      const fake = fakeBackend({}, (command) =>
+        command === 'rg --version'
+          ? ok('ripgrep 14.1.0')
+          : { exitCode, stdout: '', stderr },
+      )
+      await expect(
+        searchOn(fake.backend).grep({ pattern: 'two' }),
+      ).rejects.toThrow(message)
+    },
+  )
+
+  it('refuses a pattern with a line break', async () => {
+    const { grep } = searchOn(fakeBackend({}).backend)
+    await expect(grep({ pattern: 'a\nb' })).rejects.toThrow(
+      'The pattern must be one line.',
+    )
+  })
+})
+
+describe('quoting for the shell of the backend', () => {
+  /** rg on the PATH answers every rg command with no output. */
+  const rgOnPath = (command: string) =>
+    command.startsWith('rg ') ? ok('') : undefined
+
+  /** The rg command that a grep for `a b` runs on `backend`. */
+  async function grepCommand(backend: WorkspaceBackend) {
+    await searchOn(backend).grep({ pattern: 'a b' })
+    return (
+      exec.mock.calls
+        .map(([command]) => command)
+        .find((command) => command.startsWith('rg --line-number')) ?? ''
+    )
+  }
+  const exec = vi.fn(async (command: string) => rgOnPath(command) ?? NOT_FOUND)
+
+  afterEach(() => {
+    exec.mockClear()
+  })
+
+  it.each([
+    { shell: undefined, quoted: `'a b'` },
+    { shell: 'sh' as const, quoted: `'a b'` },
+    { shell: 'cmd' as const, quoted: '^"a^ b^"' },
+  ])('quotes the pattern for shell $shell', async ({ shell, quoted }) => {
+    const backend = { ...fakeBackend({}).backend, shell, exec }
+    expect(await grepCommand(backend)).toContain(` -e ${quoted} .`)
+  })
+
+  it('quotes for the shell of this host in a copy of hostBackend', async () => {
+    const quoted = process.platform === 'win32' ? '^"a^ b^"' : `'a b'`
+    expect(await grepCommand({ ...hostBackend, exec })).toContain(
+      ` -e ${quoted} .`,
+    )
+  })
+})
+
+describe('limits', () => {
+  /** `count` files named `f0000.txt` and up, each with `text`. */
+  const numbered = (count: number, text = '') =>
+    Object.fromEntries(
+      Array.from({ length: count }, (_, index) => [
+        `f${String(index).padStart(4, '0')}.txt`,
+        text,
+      ]),
+    )
+
+  it('lists 1000 files, then a note', async () => {
+    const lines = (
+      await searchOn(fakeBackend(numbered(1001)).backend).listFiles()
+    ).split('\n')
+    expect(lines).toHaveLength(1001)
+    expect(lines[999]).toBe('f0999.txt')
+    expect(lines[1000]).toBe(FILES_NOTE)
+  })
+
+  it('shows 200 matches, then a note', async () => {
+    const fake = fakeBackend({ 'a.txt': 'two\n'.repeat(201) })
+    const lines = (await searchOn(fake.backend).grep({ pattern: 'two' })).split(
+      '\n',
+    )
+    expect(lines).toHaveLength(201)
+    expect(lines[199]).toBe('a.txt:200: two')
+    expect(lines[200]).toBe(MATCHES_NOTE)
+  })
+
+  it('says so when the JS walk stops before the end', async () => {
+    const fake = fakeBackend({ ...numbered(5001), 'z.md': '' })
+    expect(await searchOn(fake.backend).listFiles({ pattern: '*.md' })).toBe(
+      `No files.\n${FILES_NOTE}`,
+    )
+  })
+})
+
+describe('on the host', () => {
+  /** The host backend, but rg is never found. */
+  const withoutRg: WorkspaceBackend = {
+    ...hostBackend,
+    exec: (command, options) =>
+      command.startsWith('rg ')
+        ? Promise.resolve(NOT_FOUND)
+        : hostBackend.exec(command, options),
+  }
+  /** The host backend, but no command runs, so the JS walk runs. */
+  const walkOnly: WorkspaceBackend = {
+    ...hostBackend,
+    exec: async () => NOT_FOUND,
+  }
+  const put = (dir: string, path: string, text: string) =>
+    hostBackend.writeFile(join(dir, path), text)
+
+  it.skipIf(!hasGit)(
+    'leaves out what .gitignore names, through git ls-files',
+    { timeout: SPAWN_TIMEOUT },
+    async () => {
+      const dir = await mkdtemp(join(tmpdir(), 'coding-search-git-'))
+      try {
+        await put(dir, '.gitignore', 'ignored/\n*.log\n')
+        await put(dir, 'src/a.ts', 'two\n')
+        await put(dir, 'ignored/b.ts', 'two\n')
+        await put(dir, 'debug.log', 'two\n')
+        await put(dir, 'node_modules/pkg/i.js', 'two\n')
+        const init = await hostBackend.exec('git init -q', { cwd: dir })
+        expect(init.exitCode).toBe(0)
+
+        const { listFiles, grep } = searchOn(withoutRg, dir)
+        expect(await listFiles()).toBe('.gitignore\nsrc/a.ts')
+        expect(await grep({ pattern: 'two' })).toBe('src/a.ts:1: two')
+      } finally {
+        await rm(dir, { recursive: true, force: true })
+      }
+    },
+  )
+
+  describe('links to outside the workspace', () => {
+    let dir = ''
+    let outside = ''
+    beforeAll(async () => {
+      dir = await mkdtemp(join(tmpdir(), 'coding-search-walk-'))
+      outside = await mkdtemp(join(tmpdir(), 'coding-search-outside-'))
+      await put(dir, 'a.txt', 'two\n')
+      await put(outside, 'secret.txt', 'two\n')
+      // A junction on Windows needs no admin rights. Elsewhere it is a link.
+      await symlink(outside, join(dir, 'linked'), 'junction')
+      // A link to a file can need admin rights on Windows. Without it, the
+      // folder link still covers the tests.
+      await symlink(
+        join(outside, 'secret.txt'),
+        join(dir, 'secret-link.txt'),
+        'file',
+      ).catch(() => undefined)
+    })
+    afterAll(async () => {
+      await rm(outside, { recursive: true, force: true })
+      await rm(dir, { recursive: true, force: true })
+    })
+
+    it('the JS walk leaves the links out', async () => {
+      const { listFiles, grep } = searchOn(walkOnly, dir)
+      expect(await listFiles()).toBe('a.txt')
+      expect(await grep({ pattern: 'two' })).toBe('a.txt:1: two')
+    })
+
+    it.skipIf(!hasGit)(
+      'the git list leaves the links out, and the files in a linked folder',
+      { timeout: SPAWN_TIMEOUT },
+      async () => {
+        const init = await hostBackend.exec('git init -q', { cwd: dir })
+        expect(init.exitCode).toBe(0)
+        const { listFiles, grep } = searchOn(withoutRg, dir)
+        expect(await listFiles()).toBe('a.txt')
+        expect(await grep({ pattern: 'two' })).toBe('a.txt:1: two')
+      },
+    )
+  })
+})
+
+describe('quoteArg', () => {
+  const hostile = [
+    {
+      value: '"; rm -rf x',
+      posix: `'"; rm -rf x'`,
+      win32: '^"\\^"^;^ rm^ -rf^ x^"',
+    },
+    { value: '$(x)', posix: `'$(x)'`, win32: '^"$^(x^)^"' },
+    { value: '`x`', posix: "'`x`'", win32: '^"^`x^`^"' },
+    { value: '%PATH%', posix: `'%PATH%'`, win32: '^"^%PATH^%^"' },
+    { value: 'a & b', posix: `'a & b'`, win32: '^"a^ ^&^ b^"' },
+    { value: 'a | b', posix: `'a | b'`, win32: '^"a^ ^|^ b^"' },
+    { value: `it's`, posix: `'it'\\''s'`, win32: `^"it's^"` },
+    { value: 'C:\\dir\\', posix: `'C:\\dir\\'`, win32: '^"C:\\dir\\\\^"' },
+  ]
+
+  it.each(hostile)('quotes $value for sh and cmd.exe', ({ value, posix, win32 }) => {
+    expect(quoteArg(value, 'linux')).toBe(posix)
+    expect(quoteArg(value, 'win32')).toBe(win32)
+  })
+
+  it('refuses a line break for cmd.exe', () => {
+    expect(() => quoteArg('a\nb', 'win32')).toThrow('line break')
+  })
+
+  it(
+    'passes hostile values through the real shell of this host unchanged',
+    { timeout: SPAWN_TIMEOUT },
+    async () => {
+      const values = [...hostile.map((row) => row.value), '']
+      const quote = (value: string) => quoteArg(value, process.platform)
+      const script = 'console.log(JSON.stringify(process.argv.slice(1)))'
+      const command = [process.execPath, '-e', script, ...values]
+        .map(quote)
+        .join(' ')
+      const result = await hostBackend.exec(command)
+      expect(JSON.parse(result.stdout)).toEqual(values)
+    },
+  )
+})
diff --git a/packages/ai-harness/tests/coding-snapshots.test.ts b/packages/ai-harness/tests/coding-snapshots.test.ts
new file mode 100644
index 0000000000..b79020bdd5
--- /dev/null
+++ b/packages/ai-harness/tests/coding-snapshots.test.ts
@@ -0,0 +1,336 @@
+import {
+  mkdir,
+  mkdtemp,
+  readFile,
+  readdir,
+  rm,
+  writeFile,
+} from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { toolDefinition } from '@tanstack/ai'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '../src'
+import { hostBackend } from '../src/first-party/coding/backend'
+import { quoteArg } from '../src/first-party/coding/search'
+import { snapshots } from '../src/first-party/coding/snapshots'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { HarnessPersistence, HarnessSession } from '../src'
+import type { WorkspaceBackend } from '../src/first-party/coding/backend'
+import type { Reply } from './helpers'
+
+const THREAD = 't1'
+const hasGit = (await hostBackend.exec('git --version')).exitCode === 0
+
+let base = ''
+let root = ''
+let dataDir = ''
+
+beforeEach(async () => {
+  // Each test gets its own folder. The workspace and the data folder are in it.
+  base = await mkdtemp(join(tmpdir(), 'tanstack-snapshots-'))
+  root = join(base, 'work')
+  dataDir = join(base, 'data')
+  await mkdir(root)
+})
+
+afterEach(async () => {
+  vi.restoreAllMocks()
+  await rm(base, { recursive: true, force: true })
+})
+
+/** Write `text` to `path` in the workspace. Parent folders are created. */
+async function put(path: string, text: string) {
+  const full = join(root, path)
+  await mkdir(dirname(full), { recursive: true })
+  await writeFile(full, text)
+}
+
+const read = (path: string) => readFile(join(root, path), 'utf8')
+
+/** One turn: the model calls `change`, then answers `answer`. */
+const editTurn = (answer: string): Array<Reply> => [
+  () => toolCall('change', {}),
+  () => text(answer),
+]
+
+/**
+ * Open a session with `snapshots()` and a `change` tool. Each call of the
+ * tool runs the next function of `changes`.
+ */
+async function open(options: {
+  replies: Array<Reply>
+  changes?: Array<() => Promise<unknown>>
+  persistence?: HarnessPersistence
+  backend?: WorkspaceBackend
+}) {
+  const changes = options.changes ?? []
+  const change = toolDefinition({
+    name: 'change',
+    description: 'Change the files',
+  }).server(async () => {
+    await changes.shift()?.()
+    return 'changed'
+  })
+  const plugin = snapshots({ root, dataDir, backend: options.backend })
+  const { adapter } = mockAdapter(options.replies)
+  const host = createHarnessHost({
+    persistence: options.persistence ?? memoryPersistence(),
+  })
+  const session = await host.open(
+    defineHarness({
+      name: 'test/snapshots',
+      adapter,
+      tools: [change],
+      plugins: () => [plugin],
+    }),
+    { threadId: THREAD },
+  )
+  return { host, session, plugin }
+}
+
+/** The steps that the plugin state keeps. */
+function savedSteps(session: HarnessSession) {
+  const steps = session.snapshot().plugins['tanstack/snapshots']
+  if (!Array.isArray(steps)) throw new Error('No steps in the plugin state.')
+  return steps
+}
+
+/** Every file under `folder`, by path, with its bytes. */
+async function filesUnder(folder: string) {
+  const entries = await readdir(folder, {
+    recursive: true,
+    withFileTypes: true,
+  })
+  const files = new Map<string, Buffer>()
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    const full = join(entry.parentPath, entry.name)
+    files.set(full, await readFile(full))
+  }
+  return files
+}
+
+const TREE = /^[0-9a-f]{40}$/
+
+describe.skipIf(!hasGit)('snapshots', () => {
+  // Each git call starts a shell and a process, which is slow on Windows.
+  it('starts few git commands for each step', async () => {
+    await put('a.txt', 'one')
+    const { host, session } = await open({
+      replies: [
+        () => toolCall('change', {}),
+        () => toolCall('change', {}),
+        () => text('Done.'),
+      ],
+      changes: [async () => put('a.txt', 'two'), async () => undefined],
+    })
+    const exec = vi.spyOn(hostBackend, 'exec')
+
+    await session.prompt('Edit the file')
+
+    const commands = exec.mock.calls.map(([command]) => command)
+    // `git --version` and `git init` once, the turn start, and one snapshot
+    // after each tool step. Step starts reuse the snapshot before them.
+    expect(commands.filter((command) => /write-tree/.test(command))).toHaveLength(3)
+    // The second step changed nothing, so it needs no diff.
+    expect(commands.filter((command) => / diff /.test(command))).toHaveLength(1)
+    expect(commands.length).toBeLessThanOrEqual(6)
+    await host.close()
+  })
+
+  it('keeps the changed files of each step in the plugin state', async () => {
+    await put('a.txt', 'one')
+    const { host, session } = await open({
+      replies: editTurn('Done.'),
+      changes: [
+        async () => {
+          await put('a.txt', 'two')
+          await put('src/b.txt', 'new')
+        },
+      ],
+    })
+
+    await session.prompt('Edit the files')
+
+    const steps = savedSteps(session)
+    expect(steps).toMatchObject([{ files: ['a.txt', 'src/b.txt'] }])
+    expect(steps[0].from).toMatch(TREE)
+    expect(steps[0].to).toMatch(TREE)
+    expect(steps[0].to).not.toBe(steps[0].from)
+    await host.close()
+  })
+
+  it('writes each step as a log record on a durable host', async () => {
+    await put('a.txt', 'one')
+    const { runs, metadata } = memoryPersistence().stores
+    const log = memoryLogStore()
+    const { host, session } = await open({
+      replies: editTurn('Done.'),
+      changes: [() => put('a.txt', 'two')],
+      persistence: { stores: { log, runs, metadata } },
+    })
+
+    await session.prompt('Edit a.txt')
+
+    const entries = await log.read(THREAD, { after: 0 })
+    const records = entries
+      .map((entry) => entry.record)
+      .filter((record) => record.type === 'tanstack/snapshots:step')
+    expect(records).toMatchObject([{ files: ['a.txt'] }])
+    await host.close()
+  })
+
+  it('gives the changed files and a unified diff between two trees', async () => {
+    await put('a.txt', 'one\n')
+    const { host, session, plugin } = await open({
+      replies: editTurn('Done.'),
+      changes: [() => put('a.txt', 'two\n')],
+    })
+    await session.prompt('Edit a.txt')
+    const [step] = savedSteps(session)
+
+    const between = await plugin.diff(step.from, step.to)
+    expect(between.files).toEqual(['a.txt'])
+    expect(between.patch).toContain('\n-one\n+two\n')
+
+    // Without `to`, the diff is against the files now.
+    await put('c.txt', 'later\n')
+    const sinceStep = await plugin.diff(step.to)
+    expect(sinceStep.files).toEqual(['c.txt'])
+    expect(sinceStep.patch).toContain('+later')
+    await host.close()
+  })
+
+  it('/undo restores the files and removes the last turn', async () => {
+    await put('a.txt', 'one')
+    await put('sub/keep.txt', 'keep')
+    const { host, session } = await open({
+      replies: [() => text('Hi.'), ...editTurn('Done.')],
+      changes: [
+        async () => {
+          await put('a.txt', 'two')
+          await put('new/deep/c.txt', 'added')
+          await rm(join(root, 'sub/keep.txt'))
+        },
+      ],
+    })
+    await session.prompt('Hello')
+    await session.prompt('Edit the files')
+
+    expect(await session.command('undo')).toBe(
+      'Undid the last turn. Files restored: 3.',
+    )
+    expect(await read('a.txt')).toBe('one')
+    expect(await read('sub/keep.txt')).toBe('keep')
+    expect((await readdir(root)).sort()).toEqual(['a.txt', 'sub'])
+    expect(await session.transcript()).toMatchObject([
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi.' },
+    ])
+    expect(await session.command('undo')).toBe('Nothing to undo.')
+    await host.close()
+  })
+
+  it('/redo brings back the files and the turn', async () => {
+    await put('a.txt', 'one')
+    const { host, session } = await open({
+      replies: editTurn('Done.'),
+      changes: [
+        async () => {
+          await put('a.txt', 'two')
+          await put('new/c.txt', 'added')
+        },
+      ],
+    })
+    await session.prompt('Edit the files')
+    const edited = await session.transcript()
+    await session.command('undo')
+
+    expect(await session.command('redo')).toBe('Redid the last turn.')
+    expect(await read('a.txt')).toBe('two')
+    expect(await read('new/c.txt')).toBe('added')
+    expect(await session.transcript()).toEqual(edited)
+    // The turn is back, so it can be undone again.
+    await session.command('undo')
+    expect(await read('a.txt')).toBe('one')
+    await host.close()
+  })
+
+  it('clears redo when a new turn starts', async () => {
+    await put('a.txt', 'one')
+    const { host, session } = await open({
+      replies: [...editTurn('Done.'), () => text('Sure.')],
+      changes: [() => put('a.txt', 'two')],
+    })
+    await session.prompt('Edit a.txt')
+    await session.command('undo')
+    await session.prompt('Something else')
+
+    expect(await session.command('redo')).toBe('Nothing to redo.')
+    expect(await read('a.txt')).toBe('one')
+    await host.close()
+  })
+
+  it("leaves the project's own .git untouched", async () => {
+    // GIT_DIR keeps this init in the test folder, even inside a git hook.
+    const projectGit = join(root, '.git')
+    const init = await hostBackend.exec(
+      `git init -q ${quoteArg(root, process.platform)}`,
+      { env: { GIT_DIR: projectGit } },
+    )
+    expect(init.exitCode).toBe(0)
+    await put('a.txt', 'one')
+    const before = await filesUnder(projectGit)
+    const { host, session } = await open({
+      replies: editTurn('Done.'),
+      changes: [() => put('b.txt', 'new')],
+    })
+
+    await session.prompt('Add b.txt')
+    await session.command('undo')
+
+    expect(savedSteps(session)).toMatchObject([{ files: ['b.txt'] }])
+    expect(await filesUnder(projectGit)).toEqual(before)
+    await host.close()
+  })
+})
+
+describe('snapshots without git', () => {
+  /** A backend where every command fails, like a machine with no git. */
+  function noGitBackend() {
+    const fail = () => Promise.reject(new Error('Not used.'))
+    const backend: WorkspaceBackend = {
+      readFile: fail,
+      writeFile: fail,
+      stat: fail,
+      readdir: fail,
+      exec: async () => ({ exitCode: 127, stdout: '', stderr: 'not found' }),
+    }
+    return backend
+  }
+
+  it('adds no commands, warns once, and the turn still runs', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const { host, session, plugin } = await open({
+      replies: [() => text('Hi.')],
+      backend: noGitBackend(),
+    })
+
+    await session.prompt('Hello')
+
+    expect(session.commands()).toEqual([])
+    expect(await session.transcript()).toMatchObject([
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi.' },
+    ])
+    expect(warn.mock.calls).toEqual([
+      ['snapshots: git was not found. Snapshots are off.'],
+    ])
+    await expect(plugin.diff('abc')).rejects.toThrow(
+      'snapshots: git is not available.',
+    )
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/coding-web.test.ts b/packages/ai-harness/tests/coding-web.test.ts
new file mode 100644
index 0000000000..3a0f7c089f
--- /dev/null
+++ b/packages/ai-harness/tests/coding-web.test.ts
@@ -0,0 +1,315 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { webTools } from '../src/first-party/coding/web'
+import type {
+  SearchProvider,
+  WebToolsOptions,
+} from '../src/first-party/coding/web'
+
+// DNS is the network boundary: each test says what a name resolves to.
+const dns = vi.hoisted(() => ({ hosts: new Map<string, Array<string>>() }))
+
+vi.mock('node:dns/promises', () => ({
+  lookup: async (hostname: string) => {
+    const addresses = dns.hosts.get(hostname)
+    if (!addresses) throw new Error(`getaddrinfo ENOTFOUND ${hostname}`)
+    return addresses.map((address) => ({
+      address,
+      family: address.includes(':') ? 6 : 4,
+    }))
+  },
+}))
+
+const PUBLIC_IP = '93.184.216.34'
+const MB5 = 5 * 1024 * 1024
+const REFUSED = 'webfetch does not read private or local hosts'
+
+type Route = (init: RequestInit | undefined) => Response | Promise<Response>
+
+/** A route that answers with `body` and the `content-type` `type`. */
+function page(body: BodyInit, type: string) {
+  return () => new Response(body, { headers: { 'content-type': type } })
+}
+
+/** A route that redirects to `location`. */
+function redirect(location: string) {
+  return () => new Response(null, { status: 302, headers: { location } })
+}
+
+/** A fetch that answers from `routes`, by URL. `urls` lists each fetch. */
+function fakeFetch(routes: Record<string, Route>) {
+  const urls: Array<string> = []
+  const fetch: typeof globalThis.fetch = async (input, init) => {
+    const url = String(input)
+    urls.push(url)
+    const route = routes[url]
+    if (!route) throw new Error(`No route for ${url}`)
+    return route(init)
+  }
+  return { fetch, urls }
+}
+
+/** Run the tool `name` from `webTools(options)` once. */
+async function run(name: string, args: object, options: WebToolsOptions = {}) {
+  const tool = webTools(options).find((item) => item.name === name)
+  if (!tool?.execute) throw new Error(`No ${name} tool`)
+  return tool.execute(args)
+}
+
+/** Fetch `url` with a fetch that knows `routes`. */
+function webfetch(
+  args: { url: string; format?: string; timeoutMs?: number },
+  routes: Record<string, Route>,
+  options: WebToolsOptions = {},
+) {
+  const { fetch } = fakeFetch(routes)
+  return run('webfetch', args, { fetch, ...options })
+}
+
+beforeEach(() => {
+  dns.hosts.clear()
+  dns.hosts.set('example.com', [PUBLIC_IP])
+})
+
+describe('webfetch formats', () => {
+  const html =
+    '<html><head><title>Doc</title><style>p { color: red }</style></head><body><h1>Hello</h1><p>Tom &amp; <strong>Jerry</strong> &lt;3 &#x41;&#66;</p><script>alert("x")</script></body></html>'
+  const routes = { 'https://example.com/': page(html, 'text/html; charset=utf-8') }
+
+  it('gives back HTML as markdown when turndown is installed', async () => {
+    const result = await webfetch({ url: 'https://example.com/' }, routes)
+    expect(result).toBe('Doc\n\n# Hello\n\nTom & **Jerry** <3 AB')
+  })
+
+  it('gives back text without tags, scripts, or styles', async () => {
+    const result = await webfetch(
+      { url: 'https://example.com/', format: 'text' },
+      routes,
+    )
+    expect(result).toBe('Doc\nHello\nTom & Jerry <3 AB')
+  })
+
+  it('gives back the HTML as is with format html', async () => {
+    const result = await webfetch(
+      { url: 'https://example.com/', format: 'html' },
+      routes,
+    )
+    expect(result).toBe(html)
+  })
+
+  it('gives back JSON as it is', async () => {
+    const result = await webfetch(
+      { url: 'https://example.com/data' },
+      { 'https://example.com/data': page('{"ok":true}', 'application/json') },
+    )
+    expect(result).toBe('{"ok":true}')
+  })
+
+  it('without turndown, refuses markdown and gives text by default', async () => {
+    vi.doMock('turndown', () => {
+      throw new Error('Cannot find package turndown')
+    })
+    try {
+      await expect(
+        webfetch({ url: 'https://example.com/', format: 'markdown' }, routes),
+      ).rejects.toThrow('Install turndown to get markdown')
+      const result = await webfetch({ url: 'https://example.com/' }, routes)
+      expect(result).toBe('Doc\nHello\nTom & Jerry <3 AB')
+    } finally {
+      vi.doUnmock('turndown')
+    }
+  })
+})
+
+describe('webfetch limits', () => {
+  it('stops reading at 5 MB and says the page was cut', async () => {
+    const body = 'a'.repeat(MB5 + 100)
+    const result = await webfetch(
+      { url: 'https://example.com/big.txt' },
+      { 'https://example.com/big.txt': page(body, 'text/plain') },
+    )
+    expect(result).toBe(
+      `${'a'.repeat(MB5)}\n\n[Cut at 5 MB. The rest was not read.]`,
+    )
+  })
+
+  it('stops after the timeout', async () => {
+    const hang: Route = (init) =>
+      new Promise((_, reject) => {
+        init?.signal?.addEventListener('abort', () =>
+          reject(new Error('aborted')),
+        )
+      })
+    await expect(
+      webfetch(
+        { url: 'https://example.com/slow', timeoutMs: 20 },
+        { 'https://example.com/slow': hang },
+      ),
+    ).rejects.toThrow('https://example.com/slow timed out after 20 ms.')
+  })
+
+  it('refuses binary content', async () => {
+    const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47])
+    await expect(
+      webfetch(
+        { url: 'https://example.com/logo.png' },
+        { 'https://example.com/logo.png': page(png, 'image/png') },
+      ),
+    ).rejects.toThrow(
+      'https://example.com/logo.png is image/png. webfetch reads HTML, text, and JSON only.',
+    )
+  })
+
+  it('refuses a body with no content type and a NUL byte', async () => {
+    const bytes = new Uint8Array([0x7f, 0x45, 0x4c, 0x46, 0x00, 0x01])
+    await expect(
+      webfetch(
+        { url: 'https://example.com/tool' },
+        { 'https://example.com/tool': () => new Response(bytes) },
+      ),
+    ).rejects.toThrow('https://example.com/tool is binary.')
+  })
+
+  it('fails on an HTTP error status', async () => {
+    await expect(
+      webfetch(
+        { url: 'https://example.com/missing' },
+        {
+          'https://example.com/missing': () =>
+            new Response('gone', { status: 404 }),
+        },
+      ),
+    ).rejects.toThrow('https://example.com/missing answered with HTTP 404.')
+  })
+})
+
+describe('webfetch hosts', () => {
+  it.each([
+    'http://localhost:3000/',
+    'http://127.0.0.1/',
+    'http://169.254.169.254/latest/meta-data/',
+    'http://10.0.0.8/',
+    'http://172.16.0.1/',
+    'http://192.168.1.1/',
+    'http://[::1]/',
+    'http://[fd00::1]/',
+    'http://[::ffff:127.0.0.1]/',
+  ])('refuses %s without fetching it', async (url) => {
+    const { fetch, urls } = fakeFetch({})
+    await expect(run('webfetch', { url }, { fetch })).rejects.toThrow(REFUSED)
+    expect(urls).toEqual([])
+  })
+
+  it('refuses a name when DNS gives a private address', async () => {
+    dns.hosts.set('intranet.example', [PUBLIC_IP, '10.1.2.3'])
+    const { fetch, urls } = fakeFetch({})
+    await expect(
+      run('webfetch', { url: 'https://intranet.example/' }, { fetch }),
+    ).rejects.toThrow(`${REFUSED}: intranet.example`)
+    expect(urls).toEqual([])
+  })
+
+  it('refuses a name that DNS cannot resolve', async () => {
+    await expect(
+      webfetch({ url: 'https://nowhere.example/' }, {}),
+    ).rejects.toThrow('Could not resolve nowhere.example.')
+  })
+
+  it('reads private hosts with allowPrivateHosts', async () => {
+    const result = await webfetch(
+      { url: 'http://localhost:3000/' },
+      { 'http://localhost:3000/': page('local', 'text/plain') },
+      { allowPrivateHosts: true },
+    )
+    expect(result).toBe('local')
+  })
+
+  it('refuses a URL that is not http or https', async () => {
+    await expect(
+      webfetch({ url: 'file:///etc/passwd' }, {}, { allowPrivateHosts: true }),
+    ).rejects.toThrow('webfetch reads http and https URLs only, not file:')
+  })
+})
+
+describe('webfetch redirects', () => {
+  it('follows a redirect to a public host', async () => {
+    const { fetch, urls } = fakeFetch({
+      'https://example.com/old': redirect('/new'),
+      'https://example.com/new': page('moved', 'text/plain'),
+    })
+    const result = await run(
+      'webfetch',
+      { url: 'https://example.com/old' },
+      { fetch },
+    )
+    expect(result).toBe('moved')
+    expect(urls).toEqual(['https://example.com/old', 'https://example.com/new'])
+  })
+
+  it('refuses a redirect to a private host', async () => {
+    const { fetch, urls } = fakeFetch({
+      'https://example.com/go': redirect('http://169.254.169.254/latest/'),
+    })
+    await expect(
+      run('webfetch', { url: 'https://example.com/go' }, { fetch }),
+    ).rejects.toThrow(`${REFUSED}: 169.254.169.254`)
+    expect(urls).toEqual(['https://example.com/go'])
+  })
+
+  it('stops after 5 redirects', async () => {
+    const { fetch, urls } = fakeFetch({
+      'https://example.com/loop': redirect('/loop'),
+    })
+    await expect(
+      run('webfetch', { url: 'https://example.com/loop' }, { fetch }),
+    ).rejects.toThrow('https://example.com/loop redirected more than 5 times.')
+    expect(urls).toHaveLength(6)
+  })
+})
+
+describe('websearch', () => {
+  /** A provider that gives back `results` and records each search. */
+  function provider(results: Awaited<ReturnType<SearchProvider['search']>>) {
+    const searches: Array<{ query: string; limit: number }> = []
+    const search: SearchProvider = {
+      search: async (query, { limit }) => {
+        searches.push({ query, limit })
+        return results
+      },
+    }
+    return { search, searches }
+  }
+
+  it('gives back the results as a numbered list', async () => {
+    const { search, searches } = provider([
+      {
+        title: 'TanStack AI',
+        url: 'https://tanstack.com/ai',
+        snippet: 'Type-safe AI SDK',
+      },
+      { title: 'TanStack Query', url: 'https://tanstack.com/query' },
+    ])
+    const result = await run(
+      'websearch',
+      { query: 'tanstack', limit: 2 },
+      { search },
+    )
+    expect(result).toBe(
+      '1. TanStack AI\n   https://tanstack.com/ai\n   Type-safe AI SDK\n\n2. TanStack Query\n   https://tanstack.com/query',
+    )
+    expect(searches).toEqual([{ query: 'tanstack', limit: 2 }])
+  })
+
+  it('says when there are no results', async () => {
+    const { search } = provider([])
+    const result = await run('websearch', { query: 'nothing' }, { search })
+    expect(result).toBe('No results for "nothing".')
+  })
+
+  it('exists only with a provider', () => {
+    const { search } = provider([])
+    const names = (options: WebToolsOptions) =>
+      webTools(options).map((tool) => tool.name)
+    expect(names({})).toEqual(['webfetch'])
+    expect(names({ search })).toEqual(['webfetch', 'websearch'])
+  })
+})
diff --git a/packages/ai-harness/tests/edge-safety.test.ts b/packages/ai-harness/tests/edge-safety.test.ts
index 44f9f17783..2c613989d5 100644
--- a/packages/ai-harness/tests/edge-safety.test.ts
+++ b/packages/ai-harness/tests/edge-safety.test.ts
@@ -23,6 +23,7 @@ const ALLOWED = [
   'build.ts',
   'worker.ts',
   'first-party/files.ts',
+  'first-party/bound-output.ts',
   'first-party/coding/',
 ]
 
diff --git a/packages/ai-harness/tests/instructions.test.ts b/packages/ai-harness/tests/instructions.test.ts
new file mode 100644
index 0000000000..f66ac2063a
--- /dev/null
+++ b/packages/ai-harness/tests/instructions.test.ts
@@ -0,0 +1,265 @@
+import { mkdir, mkdtemp, rm, utimes, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '../src'
+import { projectInstructions } from '../src/first-party'
+import { workspaceTools } from '../src/first-party/coding'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { AnyTextAdapter, ModelMessage } from '@tanstack/ai'
+import type { HarnessPlugin } from '../src'
+
+// `~` in a global path is the home folder. Each test points it into its own
+// folder.
+const home = vi.hoisted(() => ({ dir: '' }))
+vi.mock('node:os', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('node:os')>()),
+  homedir: () => home.dir,
+}))
+
+// A fake git: real git can take seconds to start on a busy machine, more
+// than the plugin waits. It names `git.branch` for `git rev-parse` in
+// `git.cwd`, and fails for anything else.
+const git = vi.hoisted(() => {
+  const fake: { cwd: string; branch: string | undefined } = {
+    cwd: '',
+    branch: undefined,
+  }
+  return fake
+})
+vi.mock('node:child_process', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('node:child_process')>()),
+  exec: (
+    command: string,
+    options: { cwd?: string },
+    callback: (error: Error | null, stdout: string, stderr: string) => void,
+  ) => {
+    const isBranchQuery =
+      command === 'git rev-parse --abbrev-ref HEAD' &&
+      options.cwd === git.cwd &&
+      git.branch !== undefined
+    if (isBranchQuery) callback(null, `${git.branch}\n`, '')
+    else callback(Object.assign(new Error('git failed'), { code: 128 }), '', '')
+  },
+}))
+
+let dir = ''
+/** The `root` of the plugin, in the test folder. */
+let root = ''
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'harness-instructions-'))
+  home.dir = join(dir, 'home')
+  root = join(dir, 'project')
+  await mkdir(root)
+})
+afterEach(async () => {
+  vi.useRealTimers()
+  await rm(dir, { recursive: true, force: true })
+})
+
+/** Write `content` to `path` in the test folder, and make its folders. */
+async function put(path: string, content: string) {
+  const full = join(dir, path)
+  await mkdir(dirname(full), { recursive: true })
+  await writeFile(full, content)
+}
+
+/** Write `content` to `path`, with an mtime `minutes` in the future. */
+async function change(path: string, content: string, minutes: number) {
+  await put(path, content)
+  const time = Date.now() / 1000 + minutes * 60
+  await utimes(join(dir, path), time, time)
+}
+
+/** A model that answers 'ok', on a model with mid-conversation changes. */
+function okModel() {
+  const { adapter, calls } = mockAdapter(() => text('ok'))
+  const withChannels: AnyTextAdapter = {
+    ...adapter,
+    midConversationChannels: { tools: true, systemPrompts: true },
+  }
+  return { adapter: withChannels, calls }
+}
+
+/** Open a session on `adapter` with `plugins`. */
+async function open(adapter: AnyTextAdapter, plugins: Array<HarnessPlugin>) {
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const session = await host.open(
+    defineHarness({
+      name: 'test/instructions',
+      adapter,
+      plugins: () => plugins,
+    }),
+    { threadId: 't' },
+  )
+  return { host, session }
+}
+
+/** The system prompts of one turn with `projectInstructions(options)`. */
+async function promptsOfOneTurn(
+  options: Parameters<typeof projectInstructions>[0],
+) {
+  const { adapter, calls } = okModel()
+  const { host, session } = await open(adapter, [projectInstructions(options)])
+  await session.prompt('hi')
+  await host.close()
+  return calls[0].systemPrompts
+}
+
+describe('projectInstructions', () => {
+  it('puts global files first, then the files from the repo root down to root', async () => {
+    await put('home/.config/AGENTS.md', 'Global rule.')
+    await mkdir(join(dir, 'repo', '.git'), { recursive: true })
+    await put('repo/AGENTS.md', 'Repo rule.')
+    await put('repo/pkg/AGENTS.md', 'Package rule.')
+    await put('repo/pkg/CLAUDE.md', 'Claude rule.')
+
+    expect(
+      await promptsOfOneTurn({
+        root: join(dir, 'repo', 'pkg'),
+        global: ['~/.config/AGENTS.md'],
+        env: false,
+      }),
+    ).toEqual([
+      'Global instructions from ~/.config/AGENTS.md:\nGlobal rule.',
+      'Project instructions from ../AGENTS.md:\nRepo rule.',
+      'Project instructions from AGENTS.md:\nPackage rule.',
+      'Project instructions from CLAUDE.md:\nClaude rule.',
+    ])
+  })
+
+  it('reads only root when no folder has .git', async () => {
+    await put('AGENTS.md', 'Outer rule.')
+    await put('project/AGENTS.md', 'Inner rule.')
+
+    expect(await promptsOfOneTurn({ root, env: false })).toEqual([
+      'Project instructions from AGENTS.md:\nInner rule.',
+    ])
+  })
+
+  it('adds a changed file at the end, as a mid-conversation change', async () => {
+    await put('project/AGENTS.md', 'Use tabs.')
+    const { adapter, calls } = okModel()
+    const { host, session } = await open(adapter, [
+      projectInstructions({ root, env: false }),
+    ])
+
+    await session.prompt('one')
+    await change('project/AGENTS.md', 'Use spaces.', 1)
+    await session.prompt('two')
+    await host.close()
+
+    expect(calls[1].systemPrompts).toEqual([
+      'Project instructions from AGENTS.md:\nUse tabs.',
+      'Project instructions from AGENTS.md changed. Follow this text instead:\nUse spaces.',
+    ])
+    expect(calls[1].midConversationChanges).toEqual({
+      start: { tools: [], systemPrompts: 1 },
+      changes: [{ before: calls[1].messages.length, systemPrompts: 1 }],
+    })
+  })
+
+  it('notes a removed file and a new file', async () => {
+    await put('project/AGENTS.md', 'Use tabs.')
+    const { adapter, calls } = okModel()
+    const { host, session } = await open(adapter, [
+      projectInstructions({ root, env: false }),
+    ])
+
+    await session.prompt('one')
+    await rm(join(root, 'AGENTS.md'))
+    await put('project/CLAUDE.md', 'Be brief.')
+    await session.prompt('two')
+    await host.close()
+
+    expect(calls[1].systemPrompts).toEqual([
+      'Project instructions from AGENTS.md:\nUse tabs.',
+      'Project instructions from AGENTS.md were removed.',
+      'Project instructions from CLAUDE.md:\nBe brief.',
+    ])
+  })
+
+  it('builds the prompt again when no spare slot is left', async () => {
+    await put('project/AGENTS.md', 'Version 0.')
+    const { adapter, calls } = okModel()
+    // One file and 8 spare slots: 9 slots in all.
+    const { host, session } = await open(adapter, [
+      projectInstructions({ root, files: ['AGENTS.md'], env: false }),
+    ])
+
+    await session.prompt('turn 0')
+    for (let version = 1; version <= 9; version++) {
+      await change('project/AGENTS.md', `Version ${version}.`, version)
+      await session.prompt(`turn ${version}`)
+    }
+    await host.close()
+
+    expect(calls[8].systemPrompts.at(-1)).toBe(
+      'Project instructions from AGENTS.md changed. Follow this text instead:\nVersion 8.',
+    )
+    expect(calls[9].systemPrompts).toEqual([
+      'Project instructions from AGENTS.md:\nVersion 9.',
+    ])
+  })
+
+  it('adds an environment block with the date, platform, and folder', async () => {
+    vi.setSystemTime(new Date('2026-03-04T12:00:00Z'))
+
+    expect(await promptsOfOneTurn({ root })).toEqual([
+      `Environment:\n- Date: 2026-03-04\n- Platform: ${process.platform}\n- Working folder: ${root}\n- Git repository: no`,
+    ])
+  })
+
+  it('names the git branch in a git repository', async () => {
+    await mkdir(join(root, '.git'))
+    git.cwd = root
+    git.branch = 'instructions-test'
+
+    const [environment] = await promptsOfOneTurn({ root })
+    expect(environment).toMatch(
+      /- Git repository: yes\n- Git branch: instructions-test$/,
+    )
+  })
+
+  it('leaves out the branch when git cannot name it', async () => {
+    await mkdir(join(root, '.git'))
+    git.cwd = root
+    git.branch = undefined
+
+    const [environment] = await promptsOfOneTurn({ root })
+    expect(environment).toMatch(/- Git repository: yes$/)
+  })
+
+  it('adds a nested instruction file to read_file once', async () => {
+    await put('project/AGENTS.md', 'Root rule.')
+    await put('project/src/AGENTS.md', 'Src rule.')
+    await put('project/src/lib/AGENTS.md', 'Lib rule.')
+    await put('project/src/lib/a.ts', 'a')
+    await put('project/src/b.ts', 'b')
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('read_file', { path: 'src/b.ts' }, 'c1'),
+      () => toolCall('read_file', { path: 'src/lib/AGENTS.md' }, 'c2'),
+      () => toolCall('read_file', { path: 'src/lib/a.ts' }, 'c3'),
+      () => text('done'),
+    ])
+    const { host, session } = await open(adapter, [
+      workspaceTools({ root }),
+      projectInstructions({ root, env: false }),
+    ])
+
+    await session.prompt('read')
+    await host.close()
+
+    // What each read added after the lines of the file.
+    const messages: Array<ModelMessage> = calls[3].messages
+    const added = messages
+      .filter((message) => message.role === 'tool')
+      .map((message) => String(message.content).split('\n\n').slice(1))
+    expect(added).toEqual([
+      ['Instructions from src/AGENTS.md:\nSrc rule.'],
+      [],
+      [],
+    ])
+  })
+})
diff --git a/packages/ai-harness/tests/permissions.test.ts b/packages/ai-harness/tests/permissions.test.ts
index 147a6af37b..2d86434dcb 100644
--- a/packages/ai-harness/tests/permissions.test.ts
+++ b/packages/ai-harness/tests/permissions.test.ts
@@ -112,6 +112,10 @@ describe('decidePermission with resources', () => {
     ['a backtick', 'echo `rm x`'],
     ['process substitution', 'diff <(rm x) y'],
     ['a heredoc', 'cat <<EOF\nrm x\nEOF'],
+    // The splitter keeps these in one part. They must still ask.
+    ['a lone & (background, or a separator in cmd.exe)', 'ls & rm -rf x'],
+    ['a carriage return', 'ls\rrm -rf x'],
+    ['an output redirect', 'ls > ~/.bashrc'],
   ])('asks for %s even when * is allowed', (_name, part) => {
     expect(
       run([part], [{ tool: 'bash', resource: '*', decision: 'allow' }]),
diff --git a/packages/ai-harness/tests/question.test.ts b/packages/ai-harness/tests/question.test.ts
new file mode 100644
index 0000000000..2be07da990
--- /dev/null
+++ b/packages/ai-harness/tests/question.test.ts
@@ -0,0 +1,124 @@
+import { describe, expect, it, vi } from 'vitest'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '../src'
+import { question } from '../src/first-party/question'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { HarnessSession } from '../src'
+
+const database = {
+  question: 'Which database?',
+  header: 'Database',
+  options: [
+    { label: 'Postgres', description: 'Relational, the default' },
+    { label: 'SQLite' },
+  ],
+}
+
+const features = {
+  question: 'Which features?',
+  options: [{ label: 'Auth' }, { label: 'Search' }, { label: 'Billing' }],
+  multiple: true,
+}
+
+/** The model calls `question` with `questions`, then ends the turn. */
+async function open(questions: Array<object>) {
+  const { adapter, calls } = mockAdapter([
+    () => toolCall('question', { questions }, 'c1'),
+    () => text('done'),
+  ])
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const session = await host.open(
+    defineHarness({
+      name: 'test/question',
+      adapter,
+      plugins: () => [question()],
+    }),
+    { threadId: 't' },
+  )
+  const turn = session.prompt('ask me')
+  return { host, session, calls, turn }
+}
+
+/** Wait for the one open question, then answer it. Returns the question. */
+async function reply(session: HarnessSession, value: unknown) {
+  await vi.waitFor(() =>
+    expect(session.snapshot().pendingQuestions).toHaveLength(1),
+  )
+  const [pending] = session.snapshot().pendingQuestions
+  if (!pending) throw new Error('No question.')
+  await session.answer(pending.questionId, value)
+  return pending
+}
+
+/** The tool result the model got on its second call. */
+function toolResult(
+  calls: Array<{ messages: Array<{ role: string; content: unknown }> }>,
+) {
+  return calls[1]?.messages.find((message) => message.role === 'tool')
+    ?.content
+}
+
+describe('question()', () => {
+  it('asks each question in turn and gives the model the picked labels', async () => {
+    const { host, session, calls, turn } = await open([database, features])
+
+    const first = await reply(session, '2')
+    const second = await reply(session, ['billing', 'Auth'])
+    await turn
+
+    expect(first.message).toBe(
+      'Database: Which database?\n1. Postgres - Relational, the default\n2. SQLite\nType a number or a label, or your own answer.',
+    )
+    expect(first.schema).toEqual({
+      type: 'string',
+      enum: ['Postgres', 'SQLite'],
+    })
+    expect(second.message).toContain('3. Billing')
+    expect(second.schema).toEqual({
+      type: 'array',
+      items: { type: 'string', enum: ['Auth', 'Search', 'Billing'] },
+      minItems: 1,
+      uniqueItems: true,
+    })
+    expect(toolResult(calls)).toBe(
+      'Which database?\nAnswer: SQLite\n\nWhich features?\nAnswer: Billing, Auth',
+    )
+    await host.close()
+  })
+
+  it.each([
+    ['a label in another case', database, ' postgres ', 'Answer: Postgres'],
+    [
+      'numbers and labels split by commas',
+      features,
+      'auth, 3',
+      'Answer: Auth, Billing',
+    ],
+    [
+      'text that names no option',
+      database,
+      'We use Mongo',
+      'Own answer: We use Mongo',
+    ],
+  ])('reads %s', async (_name, asked, value, expected) => {
+    const { host, session, calls, turn } = await open([asked])
+
+    await reply(session, value)
+    await turn
+
+    expect(toolResult(calls)).toBe(`${asked.question}\n${expected}`)
+    await host.close()
+  })
+
+  it('gives the model a tool error when the reply is empty', async () => {
+    const { host, session, calls, turn } = await open([database, features])
+
+    await reply(session, '   ')
+    await turn
+
+    expect(toolResult(calls)).toContain('The user did not answer.')
+    // The second question is not asked.
+    expect(session.snapshot().pendingQuestions).toHaveLength(0)
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/title-usage.test.ts b/packages/ai-harness/tests/title-usage.test.ts
new file mode 100644
index 0000000000..9d0525e4a1
--- /dev/null
+++ b/packages/ai-harness/tests/title-usage.test.ts
@@ -0,0 +1,185 @@
+import { describe, expect, it, vi } from 'vitest'
+import { EventType } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness, definePlugin } from '../src'
+import { usage } from '../src/first-party/session-tools'
+import { TitleFailed, title } from '../src/first-party/title'
+import { messageTexts, mockAdapter, text } from './helpers'
+import type { StreamChunk, TokenUsage } from '@tanstack/ai'
+import type { HarnessPersistence, HarnessPlugin } from '../src'
+import type { Reply } from './helpers'
+
+/** Open thread `t`. The main model answers `answer` unless `reply` is given. */
+async function open(
+  plugins: Array<HarnessPlugin>,
+  {
+    persistence = memoryPersistence(),
+    reply = () => text('answer'),
+  }: { persistence?: HarnessPersistence; reply?: Reply } = {},
+) {
+  const host = createHarnessHost({ persistence })
+  const session = await host.open(
+    defineHarness({
+      name: 'test/title-usage',
+      adapter: mockAdapter(reply).adapter,
+      plugins: () => plugins,
+    }),
+    { threadId: 't' },
+  )
+  return { host, session }
+}
+
+describe('title()', () => {
+  it('writes a title from the first user message after the first turn', async () => {
+    const titler = mockAdapter(() => text('"Trip to Rome"\nA second line'))
+    const { host, session } = await open([title({ adapter: titler.adapter })])
+
+    const turn = await session.prompt('Plan a trip to Rome for me')
+
+    expect(turn.text).toBe('answer')
+    await vi.waitFor(async () =>
+      expect((await host.sessions.get('t'))?.title).toBe('Trip to Rome'),
+    )
+    expect(messageTexts(titler.calls[0])[0]).toContain(
+      'Plan a trip to Rome for me',
+    )
+    await host.close()
+  })
+
+  it('does not ask for a title again once the session has one', async () => {
+    const titler = mockAdapter([
+      () => text('Trip to Rome'),
+      () => text('Another title'),
+    ])
+    const { host, session } = await open([title({ adapter: titler.adapter })])
+    await session.prompt('Plan a trip to Rome for me')
+    await vi.waitFor(async () =>
+      expect((await host.sessions.get('t'))?.title).toBe('Trip to Rome'),
+    )
+
+    await session.prompt('Add a day in Florence')
+
+    expect(titler.calls).toHaveLength(1)
+    expect((await host.sessions.get('t'))?.title).toBe('Trip to Rome')
+    await host.close()
+  })
+
+  it('keeps the turn when the title call fails', async () => {
+    const failures: Array<{ message: string }> = []
+    const listener = definePlugin({
+      name: 'test/listener',
+      setup: (ctx) => {
+        ctx.on(TitleFailed, (failure) => failures.push(failure))
+      },
+    })
+    const titler = mockAdapter(() => {
+      throw new Error('title model down')
+    })
+    const { host, session } = await open([
+      listener,
+      title({ adapter: titler.adapter }),
+    ])
+
+    const turn = await session.prompt('Plan a trip to Rome for me')
+
+    expect(turn.text).toBe('answer')
+    await vi.waitFor(() =>
+      expect(failures).toEqual([{ message: 'title model down' }]),
+    )
+    expect((await host.sessions.get('t'))?.title).toBeUndefined()
+    await host.close()
+  })
+
+  it('does nothing without a sessions store', async () => {
+    const { messages, runs, metadata } = memoryPersistence().stores
+    const titler = mockAdapter(() => text('Trip to Rome'))
+    const { host, session } = await open([title({ adapter: titler.adapter })], {
+      persistence: { stores: { messages, runs, metadata } },
+    })
+
+    await session.prompt('Plan a trip to Rome for me')
+
+    expect(titler.calls).toHaveLength(0)
+    await host.close()
+  })
+})
+
+describe('usage({ model })', () => {
+  /** Prices in USD per 1M tokens. */
+  const PRICES = { input: 2, output: 10, cacheRead: 1, cacheWrite: 4 }
+  /**
+   * One model call. With PRICES it costs $3.25: 500k uncached input ($1),
+   * 100k output ($1), 250k cache read ($0.25), 250k cache write ($1).
+   */
+  const CALL: TokenUsage = {
+    promptTokens: 1_000_000,
+    completionTokens: 100_000,
+    totalTokens: 1_100_000,
+    promptTokensDetails: { cachedTokens: 250_000, cacheWriteTokens: 250_000 },
+  }
+  const withUsage = () =>
+    text('answer').map(
+      (chunk): StreamChunk =>
+        chunk.type === EventType.RUN_FINISHED
+          ? { ...chunk, usage: CALL }
+          : chunk,
+    )
+  /** The prices of the mock adapter's model only. */
+  const pricesOf = (modelId: string) =>
+    modelId === 'test-model' ? { cost: PRICES } : undefined
+
+  it('prices each model call and shows the cost in /usage', async () => {
+    const { host, session } = await open([usage({ model: pricesOf })], {
+      reply: withUsage,
+    })
+
+    await session.prompt('one')
+    await session.prompt('two')
+
+    expect(await session.command('usage')).toBe(
+      '2 model calls, 2000000 input tokens (500000 cache read, 500000 cache write), 200000 output tokens, 2200000 total. Cost: $6.5000.',
+    )
+    await host.close()
+  })
+
+  it('writes the cost to the index entry and keeps the token totals of the host', async () => {
+    const { host, session } = await open([usage({ model: pricesOf })], {
+      reply: withUsage,
+    })
+
+    await session.prompt('one')
+    await session.prompt('two')
+
+    expect((await host.sessions.get('t'))?.usage).toEqual({
+      turns: 2,
+      promptTokens: 2_000_000,
+      completionTokens: 200_000,
+      totalTokens: 2_200_000,
+      cachedTokens: 500_000,
+      cacheWriteTokens: 500_000,
+      cost: expect.closeTo(6.5, 10),
+    })
+    await host.close()
+  })
+
+  it('adds no cost for a model with no prices, and says so in /usage', async () => {
+    const { host, session } = await open([usage({ model: () => undefined })], {
+      reply: withUsage,
+    })
+
+    await session.prompt('one')
+
+    expect(await session.command('usage')).toBe(
+      '1 model calls, 1000000 input tokens (250000 cache read, 250000 cache write), 100000 output tokens, 1100000 total. Cost: $0.0000 (cost unknown for 1 call).',
+    )
+    expect((await host.sessions.get('t'))?.usage).toEqual({
+      turns: 1,
+      promptTokens: 1_000_000,
+      completionTokens: 100_000,
+      totalTokens: 1_100_000,
+      cachedTokens: 250_000,
+      cacheWriteTokens: 250_000,
+    })
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/workspace-tools.test.ts b/packages/ai-harness/tests/workspace-tools.test.ts
index f6ddaaff33..a6f9e3a729 100644
--- a/packages/ai-harness/tests/workspace-tools.test.ts
+++ b/packages/ai-harness/tests/workspace-tools.test.ts
@@ -1,20 +1,36 @@
-import { mkdtemp, rm } from 'node:fs/promises'
+import { mkdtemp, readFile, realpath, rm, symlink } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { join, resolve, sep } from 'node:path'
-import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import * as nodePath from 'node:path'
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '../src'
+import { permissions } from '../src/first-party/permissions'
 import { hostBackend } from '../src/first-party/coding/backend'
-import { createWorkspaceTools } from '../src/first-party/coding/workspace'
-import type { AnyTool } from '@tanstack/ai'
+import {
+  createWorkspaceTools,
+  workspaceTools,
+} from '../src/first-party/coding/workspace'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { PlatformPath } from 'node:path'
+import type { AnyTextAdapter, AnyTool } from '@tanstack/ai'
+import type { HarnessPlugin } from '../src'
 import type { WorkspaceBackend } from '../src/first-party/coding/backend'
 import type {
   OutsideAccess,
   WorkspaceToolsOptions,
 } from '../src/first-party/coding/workspace'
 
-/** A backend that keeps files in a map, by absolute path. It runs no commands. */
-function memoryBackend() {
+const { posix } = nodePath
+
+/**
+ * A backend that keeps files in a map, by absolute POSIX path, like a Linux
+ * sandbox. Its commands answer with the command and the folder. `extra`
+ * replaces parts of it.
+ */
+function memoryBackend(extra: Partial<WorkspaceBackend> = {}) {
   const files = new Map<string, Uint8Array>()
   const backend: WorkspaceBackend = {
+    shell: 'sh',
     readFile: async (path) => {
       const data = files.get(path)
       if (!data) throw new Error(`No file ${path}`)
@@ -32,11 +48,11 @@ function memoryBackend() {
       return { type: 'file', size: data.length, mtimeMs: 0 }
     },
     readdir: async (path) => {
-      const prefix = path.endsWith(sep) ? path : path + sep
+      const prefix = path.endsWith('/') ? path : `${path}/`
       const entries = new Map<string, 'file' | 'dir'>()
       for (const file of files.keys()) {
         if (!file.startsWith(prefix)) continue
-        const [name = '', ...rest] = file.slice(prefix.length).split(sep)
+        const [name = '', ...rest] = file.slice(prefix.length).split('/')
         entries.set(name, rest.length > 0 ? 'dir' : 'file')
       }
       // Sorted by name, like the host.
@@ -49,14 +65,16 @@ function memoryBackend() {
       stdout: `ran ${command} in ${options?.cwd}`,
       stderr: 'warn',
     }),
+    ...extra,
   }
-  return backend
+  return { backend, files }
 }
 
-/** A backend, and how to make and remove an empty folder on it. */
+/** A backend, its path functions, and how to make and remove a folder on it. */
 interface Fixture {
   name: string
   backend: WorkspaceBackend
+  paths: PlatformPath
   folder: (prefix: string) => Promise<string>
   remove: (folder: string) => Promise<void>
 }
@@ -66,15 +84,17 @@ const fixtures: Array<Fixture> = [
   {
     name: 'host',
     backend: hostBackend,
-    folder: (prefix) => mkdtemp(join(tmpdir(), prefix)),
+    paths: nodePath,
+    folder: (prefix) => mkdtemp(nodePath.join(tmpdir(), prefix)),
     remove: (folder) => rm(folder, { recursive: true, force: true }),
   },
   {
     name: 'memory',
-    backend: memoryBackend(),
+    backend: memoryBackend().backend,
+    paths: posix,
     folder: async (prefix) => {
       memoryFolders += 1
-      return resolve(tmpdir(), `${prefix}${memoryFolders}`)
+      return `/${prefix}${memoryFolders}`
     },
     remove: async () => undefined,
   },
@@ -101,16 +121,47 @@ const runIn = (
   return Promise.resolve(tool.execute(args))
 }
 
+/** A session with `plugins`, whose model is `adapter`. */
+async function openSession(
+  adapter: AnyTextAdapter,
+  plugins: Array<HarnessPlugin>,
+) {
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const session = await host.open(
+    defineHarness({
+      name: 'test/workspace-tools',
+      adapter,
+      plugins: () => plugins,
+    }),
+    { threadId: 't' },
+  )
+  return { host, session }
+}
+
+/** The names of the tools that the model got in `call`. */
+const toolNames = (call: { tools: Array<{ name: string }> }) =>
+  call.tools.map((tool) => tool.name)
+
+/** Is the process `pid` still running? */
+function isRunning(pid: number) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
 describe.each(fixtures)('workspace tools on the $name backend', (fixture) => {
-  const { backend } = fixture
+  const { backend, paths } = fixture
   let root: string
   let tools: Map<string, AnyTool>
 
   const run = (name: string, args: unknown) => runIn(tools, name, args)
   const write = (path: string, text: string) =>
-    backend.writeFile(join(root, path), text)
+    backend.writeFile(paths.join(root, path), text)
   const read = async (path: string) =>
-    decoder.decode(await backend.readFile(join(root, path)))
+    decoder.decode(await backend.readFile(paths.join(root, path)))
 
   beforeAll(async () => {
     root = await fixture.folder('harness-workspace-')
@@ -141,7 +192,9 @@ describe.each(fixtures)('workspace tools on the $name backend', (fixture) => {
         run('read_file', { path: '../outside.txt' }),
       ).rejects.toThrow('outside the workspace')
       await expect(
-        run('read_file', { path: join(tmpdir(), 'elsewhere.txt') }),
+        run('read_file', {
+          path: paths.join(paths.dirname(root), 'elsewhere.txt'),
+        }),
       ).rejects.toThrow('outside the workspace')
       await expect(run('read_file', {})).rejects.toThrow(
         'Argument "path" must be a string.',
@@ -200,6 +253,21 @@ describe.each(fixtures)('workspace tools on the $name backend', (fixture) => {
     })
   })
 
+  describe('patch', () => {
+    it('adds a file in the workspace', async () => {
+      const patch = [
+        '*** Begin Patch',
+        '*** Add File: patched/p.txt',
+        '+patched',
+        '*** End Patch',
+      ].join('\n')
+      expect(await run('patch', { patch })).toBe(
+        'Applied the patch:\nadded patched/p.txt',
+      )
+      expect(await read('patched/p.txt')).toBe('patched\n')
+    })
+  })
+
   describe('list_files and grep', () => {
     it('lists files, skips dependency folders, and filters by glob', async () => {
       const all = await run('list_files', {})
@@ -230,9 +298,9 @@ describe.each(fixtures)('workspace tools on the $name backend', (fixture) => {
     let outside: string
     beforeAll(async () => {
       outside = await fixture.folder('harness-outside-')
-      await backend.writeFile(join(outside, 'docs', 'a.md'), 'alpha')
-      await backend.writeFile(join(outside, 'docs', 'b.md'), 'beta')
-      await backend.writeFile(join(outside, 'top.md'), 'top')
+      await backend.writeFile(paths.join(outside, 'docs', 'a.md'), 'alpha')
+      await backend.writeFile(paths.join(outside, 'docs', 'b.md'), 'beta')
+      await backend.writeFile(paths.join(outside, 'top.md'), 'top')
     })
     afterAll(async () => {
       await fixture.remove(outside)
@@ -256,27 +324,32 @@ describe.each(fixtures)('workspace tools on the $name backend', (fixture) => {
 
     it('refuses outside paths without the outside option', async () => {
       await expect(
-        run('read_file', { path: join(outside, 'top.md') }),
+        run('read_file', { path: paths.join(outside, 'top.md') }),
       ).rejects.toThrow('outside the workspace')
     })
 
     it('asks once for a folder, then allows it for the session', async () => {
       const { set, questions } = asking([true])
+      const docs = paths.join(outside, 'docs')
       expect(
-        await runIn(set, 'read_file', { path: join(outside, 'docs', 'a.md') }),
+        await runIn(set, 'read_file', { path: paths.join(docs, 'a.md') }),
       ).toBe('1\talpha')
       expect(
-        await runIn(set, 'read_file', { path: join(outside, 'docs', 'b.md') }),
+        await runIn(set, 'read_file', { path: paths.join(docs, 'b.md') }),
       ).toBe('1\tbeta')
       expect(questions).toHaveLength(1)
-      expect(questions[0]).toContain(`Allow ${join(outside, 'docs')}`)
+      // The question names the real folder: the temp folder can be a link.
+      const real = (await backend.realpath?.(docs)) ?? docs
+      expect(questions[0]).toContain(`Allow ${real} `)
     })
 
     it('asks again for another folder, and refuses after a no', async () => {
       const { set, questions } = asking([true, 'n'])
-      await runIn(set, 'read_file', { path: join(outside, 'docs', 'a.md') })
+      await runIn(set, 'read_file', {
+        path: paths.join(outside, 'docs', 'a.md'),
+      })
       await expect(
-        runIn(set, 'read_file', { path: join(outside, 'top.md') }),
+        runIn(set, 'read_file', { path: paths.join(outside, 'top.md') }),
       ).rejects.toThrow('The user did not allow')
       expect(questions).toHaveLength(2)
     })
@@ -284,16 +357,16 @@ describe.each(fixtures)('workspace tools on the $name backend', (fixture) => {
     it('asks one question for calls at the same time', async () => {
       const { set, questions } = asking([true])
       await Promise.all([
-        runIn(set, 'read_file', { path: join(outside, 'docs', 'a.md') }),
-        runIn(set, 'read_file', { path: join(outside, 'docs', 'b.md') }),
+        runIn(set, 'read_file', { path: paths.join(outside, 'docs', 'a.md') }),
+        runIn(set, 'read_file', { path: paths.join(outside, 'docs', 'b.md') }),
       ])
       expect(questions).toHaveLength(1)
     })
 
     it('lists and searches an allowed outside folder with full paths', async () => {
       const { set } = asking([true])
-      const folder = join(outside, 'docs')
-      const shown = folder.split(sep).join('/')
+      const folder = paths.join(outside, 'docs')
+      const shown = folder.split(paths.sep).join('/')
       expect(await runIn(set, 'list_files', { path: folder })).toBe(
         `${shown}/a.md\n${shown}/b.md`,
       )
@@ -305,36 +378,402 @@ describe.each(fixtures)('workspace tools on the $name backend', (fixture) => {
     it('does not ask in bypass mode', async () => {
       const { set, questions } = asking([], 'bypass')
       expect(
-        await runIn(set, 'read_file', { path: join(outside, 'top.md') }),
+        await runIn(set, 'read_file', { path: paths.join(outside, 'top.md') }),
       ).toBe('1\ttop')
       expect(questions).toHaveLength(0)
     })
   })
 })
 
-describe('bash', () => {
-  it('reports the exit code and stderr on the host', async () => {
-    const set = toolsOf({
-      root: tmpdir(),
-      backend: hostBackend,
-      bashTimeoutMs: 20_000,
-    })
-    const ok = await runIn(set, 'bash', {
-      command: `node -e "console.log('out'); console.error('warn')"`,
+describe('a sandbox backend with POSIX paths', () => {
+  it('keeps the root /workspace, also on a Windows host', async () => {
+    const { backend, files } = memoryBackend()
+    const set = toolsOf({ root: '/workspace', backend })
+    expect(
+      await runIn(set, 'write_file', { path: 'src/a.ts', content: 'one' }),
+    ).toBe('Wrote src/a.ts.')
+    expect([...files.keys()]).toEqual(['/workspace/src/a.ts'])
+    expect(await runIn(set, 'list_files', {})).toBe('src/a.ts')
+    expect(await runIn(set, 'bash', { command: 'make' })).toBe(
+      'exit code: 3\nran make in /workspace\nstderr:\nwarn',
+    )
+    await expect(
+      runIn(set, 'read_file', { path: '/etc/passwd' }),
+    ).rejects.toThrow('outside the workspace')
+  })
+})
+
+describe('the tools of workspaceTools', () => {
+  const names = (options: Partial<WorkspaceToolsOptions> = {}) =>
+    createWorkspaceTools({
+      root: '/workspace',
+      backend: memoryBackend().backend,
+      ...options,
+    }).tools.map((tool) => tool.name)
+  const search = { search: async () => [] }
+
+  it('has the file, shell, and webfetch tools by default', () => {
+    expect(names()).toEqual([
+      'read_file',
+      'write_file',
+      'edit_file',
+      'patch',
+      'list_files',
+      'grep',
+      'bash',
+      'webfetch',
+    ])
+  })
+
+  it('adds websearch with a search provider, and no web tools for web: false', () => {
+    expect(names({ web: { search } }).slice(-2)).toEqual([
+      'webfetch',
+      'websearch',
+    ])
+    expect(names({ web: false })).not.toContain('webfetch')
+  })
+})
+
+describe('editStyle', () => {
+  const EDIT_TOOLS = ['write_file', 'edit_file', 'patch']
+
+  it.each([
+    { editStyle: undefined, model: 'gpt-5', tools: ['write_file', 'patch'] },
+    { editStyle: undefined, model: 'o3', tools: ['write_file', 'patch'] },
+    {
+      editStyle: undefined,
+      model: 'openai/gpt-4.1',
+      tools: ['write_file', 'patch'],
+    },
+    {
+      editStyle: undefined,
+      model: 'claude-sonnet-4-5',
+      tools: ['write_file', 'edit_file'],
+    },
+    {
+      editStyle: 'edit' as const,
+      model: 'gpt-5',
+      tools: ['write_file', 'edit_file'],
+    },
+    {
+      editStyle: 'patch' as const,
+      model: 'claude-sonnet-4-5',
+      tools: ['write_file', 'patch'],
+    },
+  ])(
+    'gives $model the edit tools $tools with editStyle $editStyle',
+    async ({ editStyle, model, tools }) => {
+      const { adapter, calls } = mockAdapter([() => text('ok')])
+      const { host, session } = await openSession({ ...adapter, model }, [
+        workspaceTools({
+          root: '/workspace',
+          backend: memoryBackend().backend,
+          editStyle,
+        }),
+      ])
+      await session.prompt('hi')
+      expect(
+        toolNames(calls[0]).filter((name) => EDIT_TOOLS.includes(name)),
+      ).toEqual(tools)
+      await host.close()
+    },
+  )
+})
+
+describe('permission resources', () => {
+  const { resources } = createWorkspaceTools({
+    root: '/workspace',
+    backend: memoryBackend().backend,
+  })
+
+  it('gives each call its paths, from the root', () => {
+    expect(resources.read_file?.paths?.({ path: 'src/a.ts' })).toEqual([
+      '/workspace/src/a.ts',
+    ])
+    expect(resources.edit_file?.paths?.({ path: '/etc/hosts' })).toEqual([
+      '/etc/hosts',
+    ])
+    expect(resources.write_file?.paths?.({ path: '../x.txt' })).toEqual([
+      '/x.txt',
+    ])
+    expect(resources.list_files?.paths?.({})).toEqual(['/workspace'])
+    expect(resources.grep?.paths?.({ pattern: 'a', path: 'src' })).toEqual([
+      '/workspace/src',
+    ])
+  })
+
+  it('gives every path of a patch, also the target of a move', () => {
+    const patch = [
+      '*** Begin Patch',
+      '*** Add File: a.ts',
+      '+a',
+      '*** Update File: old.ts',
+      '*** Move to: lib/new.ts',
+      '@@',
+      '-x',
+      '+y',
+      '*** End Patch',
+    ].join('\n')
+    expect(resources.patch?.paths?.({ patch })).toEqual([
+      '/workspace/a.ts',
+      '/workspace/old.ts',
+      '/workspace/lib/new.ts',
+    ])
+  })
+
+  it('gives the command parts of bash', () => {
+    expect(resources.bash?.commands?.({ command: 'ls && rm x' })).toEqual([
+      'ls',
+      'rm x',
+    ])
+  })
+
+  it('throws, so the call is refused, when the input has no path or patch', () => {
+    expect(() => resources.read_file?.paths?.({})).toThrow(
+      'Argument "path" must be a string.',
+    )
+    expect(() => resources.patch?.paths?.({ patch: 'not a patch' })).toThrow(
+      'Patch line 1',
+    )
+  })
+
+  it('reach permissions(), so an allow rule for a path skips the question', async () => {
+    const { backend, files } = memoryBackend()
+    const patch = (path: string) =>
+      ['*** Begin Patch', `*** Add File: ${path}`, '+a', '*** End Patch'].join(
+        '\n',
+      )
+    const { adapter } = mockAdapter([
+      () => toolCall('patch', { patch: patch('src/a.ts') }, 'c1'),
+      () => text('done'),
+    ])
+    const { host, session } = await openSession(adapter, [
+      permissions({
+        root: '/workspace',
+        rules: [{ tool: 'patch', resource: 'src/**', decision: 'allow' }],
+      }),
+      workspaceTools({ root: '/workspace', backend, editStyle: 'patch' }),
+    ])
+    await session.prompt('work')
+    expect(session.snapshot().pendingQuestions).toHaveLength(0)
+    expect([...files.keys()]).toEqual(['/workspace/src/a.ts'])
+    await host.close()
+  })
+})
+
+describe('background bash in a session', () => {
+  it('notes the end of a job, and starts a turn for it', async () => {
+    const { backend } = memoryBackend({
+      spawn: () => ({
+        wait: async () => ({ exitCode: 0 }),
+        kill: () => undefined,
+        output: () => 'built\n',
+      }),
     })
-    expect(ok).toMatch(/^exit code: 0\nout/)
-    expect(ok).toContain('stderr:\nwarn')
-    const failed = await runIn(set, 'bash', {
-      command: `node -e "process.exit(3)"`,
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('bash', { command: 'make', background: true }, 'c1'),
+      () => text('started'),
+      () => text('saw the note'),
+    ])
+    const { host, session } = await openSession(adapter, [
+      workspaceTools({ root: '/workspace', backend }),
+    ])
+    await session.prompt('build')
+    await vi.waitFor(() => expect(calls).toHaveLength(3))
+    expect(JSON.stringify(calls[2].messages)).toContain(
+      'Background job bash-1 ended.\\nexit code: 0\\nbuilt',
+    )
+    await host.close()
+  })
+
+  it('kills a job that still runs when the session closes', async () => {
+    let killed = false
+    const { backend } = memoryBackend({
+      spawn: () => {
+        let end: (exitCode: number) => void = () => undefined
+        const exited = new Promise<{ exitCode: number }>((done) => {
+          end = (exitCode) => done({ exitCode })
+        })
+        return {
+          wait: () => exited,
+          kill: () => {
+            killed = true
+            end(143)
+          },
+          output: () => '',
+        }
+      },
     })
-    expect(failed).toMatch(/^exit code: 3/)
+    const { adapter } = mockAdapter([
+      () => toolCall('bash', { command: 'serve', background: true }, 'c1'),
+      () => text('started'),
+    ])
+    const { host, session } = await openSession(adapter, [
+      workspaceTools({ root: '/workspace', backend }),
+    ])
+    await session.prompt('serve')
+    expect(killed).toBe(false)
+    await host.close()
+    expect(killed).toBe(true)
+  })
+})
+
+describe('links on the host', () => {
+  let dir = ''
+  let root = ''
+  let outside = ''
+  // A link to a file can need admin rights on Windows. The tests that need
+  // one skip without it.
+  let hasFileLinks = false
+  let tools: Map<string, AnyTool>
+  const run = (name: string, args: unknown) => runIn(tools, name, args)
+  const put = (path: string, text: string) =>
+    hostBackend.writeFile(nodePath.join(dir, path), text)
+
+  beforeAll(async () => {
+    dir = await mkdtemp(nodePath.join(tmpdir(), 'harness-links-'))
+    root = nodePath.join(dir, 'root')
+    outside = nodePath.join(dir, 'outside')
+    await put('root/src/a.ts', 'inside\n')
+    await put('outside/secret.txt', 'secret\n')
+    // A junction on Windows needs no admin rights. Elsewhere it is a link.
+    await symlink(outside, nodePath.join(root, 'linked'), 'junction')
+    await symlink(
+      nodePath.join(root, 'src'),
+      nodePath.join(root, 'inner'),
+      'junction',
+    )
+    hasFileLinks = await symlink(
+      nodePath.join(outside, 'missing.txt'),
+      nodePath.join(root, 'dangling.txt'),
+      'file',
+    ).then(
+      () => true,
+      () => false,
+    )
+    tools = toolsOf({ root, backend: hostBackend })
+  })
+  afterAll(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it('marks links in readdir', async () => {
+    const entries = await hostBackend.readdir(root)
+    const sorted = entries.sort((a, b) => (a.name < b.name ? -1 : 1))
+    expect(sorted.filter((entry) => entry.name !== 'dangling.txt')).toEqual([
+      { name: 'inner', type: 'link' },
+      { name: 'linked', type: 'link' },
+      { name: 'src', type: 'dir' },
+    ])
+  })
+
+  it('refuses a link inside the workspace that leads out of it', async () => {
+    await expect(
+      run('read_file', { path: 'linked/secret.txt' }),
+    ).rejects.toThrow('outside the workspace')
+    await expect(run('list_files', { path: 'linked' })).rejects.toThrow(
+      'outside the workspace',
+    )
+    await expect(
+      run('write_file', { path: 'linked/new.txt', content: 'x' }),
+    ).rejects.toThrow('outside the workspace')
+    expect(await hostBackend.stat(nodePath.join(outside, 'new.txt'))).toBe(
+      undefined,
+    )
+  })
+
+  it('refuses a write through a link to a missing file', async (context) => {
+    if (!hasFileLinks) context.skip()
+    await expect(
+      run('write_file', { path: 'dangling.txt', content: 'x' }),
+    ).rejects.toThrow('ENOENT')
+    expect(await hostBackend.stat(nodePath.join(outside, 'missing.txt'))).toBe(
+      undefined,
+    )
+  })
+
+  it('allows a link that stays inside the workspace', async () => {
+    expect(await run('read_file', { path: 'inner/a.ts' })).toBe('1\tinside')
+  })
+
+  it('asks about the real folder of a linked path with outside: ask', async () => {
+    const questions: Array<string> = []
+    const set = toolsOf(
+      { root, backend: hostBackend, outside: 'ask' },
+      {
+        ask: async (message) => {
+          questions.push(message)
+          return 'n'
+        },
+        mode: () => 'default',
+      },
+    )
+    await expect(
+      runIn(set, 'read_file', { path: 'linked/secret.txt' }),
+    ).rejects.toThrow('The user did not allow')
+    expect(questions[0]).toContain(`Allow ${await realpath(outside)} `)
+  })
+})
+
+describe('bash', () => {
+  it('reports the exit code and stderr on the host', async () => {
+    // Its own folder: the shared system temp folder churns while the other
+    // tests run, and a process that starts there can take seconds.
+    const root = await mkdtemp(nodePath.join(tmpdir(), 'harness-bash-host-'))
+    try {
+      const set = toolsOf({
+        root,
+        backend: hostBackend,
+        bashTimeoutMs: 20_000,
+      })
+      const ok = await runIn(set, 'bash', {
+        command: `node -e "console.log('out'); console.error('warn')"`,
+      })
+      expect(ok).toMatch(/^exit code: 0\nout/)
+      expect(ok).toContain('stderr:\nwarn')
+      const failed = await runIn(set, 'bash', {
+        command: `node -e "process.exit(3)"`,
+      })
+      expect(failed).toMatch(/^exit code: 3/)
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
   })
 
   it('runs the command through the backend, in the workspace folder', async () => {
-    const root = resolve(tmpdir(), 'harness-bash')
-    const set = toolsOf({ root, backend: memoryBackend() })
+    const set = toolsOf({
+      root: '/harness-bash',
+      backend: memoryBackend().backend,
+    })
     expect(await runIn(set, 'bash', { command: 'make' })).toBe(
-      `exit code: 3\nran make in ${root}\nstderr:\nwarn`,
+      'exit code: 3\nran make in /harness-bash\nstderr:\nwarn',
     )
   })
+
+  it(
+    'stops the commands that a command started when the timeout ends it',
+    { timeout: 60_000 },
+    async () => {
+      const cwd = await mkdtemp(nodePath.join(tmpdir(), 'harness-exec-tree-'))
+      try {
+        // The shell starts node, then waits for it, so node is a child of
+        // the shell. A killed shell alone leaves node running.
+        const child = `node -e "require('fs').writeFileSync('child.pid', String(process.pid)); setTimeout(function () {}, 60000)"`
+        const result = await hostBackend.exec(`${child} && echo after`, {
+          cwd,
+          timeoutMs: 3000,
+        })
+        expect(result.exitCode).toBe(124)
+        expect(result.stdout).not.toContain('after')
+        const pid = Number(
+          await readFile(nodePath.join(cwd, 'child.pid'), 'utf8'),
+        )
+        await vi.waitFor(() => expect(isRunning(pid)).toBe(false), {
+          timeout: 5000,
+        })
+      } finally {
+        await rm(cwd, { recursive: true, force: true, maxRetries: 5 })
+      }
+    },
+  )
 })
diff --git a/packages/ai-persistence/src/subagent-runs.ts b/packages/ai-persistence/src/subagent-runs.ts
index f8bf0552fa..297f1e43e4 100644
--- a/packages/ai-persistence/src/subagent-runs.ts
+++ b/packages/ai-persistence/src/subagent-runs.ts
@@ -594,7 +594,8 @@ export function createSubagentRunRecorder(stores: {
   }
 
   // One index entry per child. `upsert` replaces the whole entry, so keep the
-  // fields that other writers set, like a title.
+  // fields that other writers set, like a title. The child has the owner of
+  // its parent thread, so a list filtered by owner shows it.
   async function indexChild(
     sessions: SessionIndexStore,
     subagentRunId: string,
@@ -602,6 +603,7 @@ export function createSubagentRunRecorder(stores: {
   ) {
     const childThreadId = childStoreId(subagentRunId)
     const current = await sessions.get(childThreadId)
+    const parent = await sessions.get(note.parentThreadId)
     const now = Date.now()
     await sessions.upsert({
       ...current,
@@ -610,6 +612,7 @@ export function createSubagentRunRecorder(stores: {
       ...(note.parentToolCallId !== undefined && {
         parentToolCallId: note.parentToolCallId,
       }),
+      ...(parent?.principal !== undefined && { principal: parent.principal }),
       createdAt: current?.createdAt ?? now,
       updatedAt: now,
     })
diff --git a/packages/ai-persistence/tests/subagent-persistence-cards.test.ts b/packages/ai-persistence/tests/subagent-persistence-cards.test.ts
index d2d51b80ec..edb441e986 100644
--- a/packages/ai-persistence/tests/subagent-persistence-cards.test.ts
+++ b/packages/ai-persistence/tests/subagent-persistence-cards.test.ts
@@ -617,6 +617,35 @@ describe('subagent run recorder', () => {
     ).toBeUndefined()
   })
 
+  it('gives each child the owner of its parent thread', async () => {
+    const { stores } = memoryPersistence()
+    await stores.sessions.upsert({
+      threadId: 'desk',
+      principal: { id: 'alice' },
+      createdAt: t,
+      updatedAt: t,
+    })
+    const recorder = createSubagentRunRecorder({
+      messages: stores.messages,
+      sessions: stores.sessions,
+      intervalMs: 0,
+    })
+    await feed(recorder, 'run-1', [
+      childStarted('outer', { parentToolCallId: 'call_1' }),
+      childStarted('inner', {
+        parentSubagentRunId: 'outer',
+        parentToolCallId: 'call_n',
+      }),
+    ])
+
+    const owners = await Promise.all(
+      ['subagent:outer', 'subagent:inner'].map(
+        async (threadId) => (await stores.sessions.get(threadId))?.principal,
+      ),
+    )
+    expect(owners).toEqual([{ id: 'alice' }, { id: 'alice' }])
+  })
+
   it('loads a waiting continued child without the messages of the call it waits in', async () => {
     const { stores } = memoryPersistence()
     const recorder = createSubagentRunRecorder({

From b24c0b655e071d7f681b7edd9d16dbd6d69772ab Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 13:03:29 +0200
Subject: [PATCH 242/286] feat(ai-models): price tiers and 1-hour cache writes,
 no Claude on google-vertex

modelCost now follows pi's two rules that it did not have:

- Tiers. A record's `cost.tiers` holds higher prices above an input size,
  for example long context. A call uses the tier with the highest
  `inputTokensAbove` below its input (uncached + cache read + cache write).
  The tiers come from models.dev `cost.tiers`. A price that models.dev
  leaves out is 0, as in pi's catalog.
- 1-hour cache writes. `TokenCounts.cacheWrite1h` is the part of
  `cacheWrite` with a 1-hour retention. It costs 2x the input price.

Usage gets `promptTokensDetails.cacheWrite1hTokens`. The Anthropic adapter
fills it from `cache_creation.ephemeral_1h_input_tokens`, and the Bedrock
Converse adapter from the 1-hour `cacheDetails`.

The google-vertex catalog listed Claude models with the Gemini wire, which
the Gemini adapter cannot call. They are left out, as in pi.

The fetch script keeps the tiers. The models.dev snapshot gets the tiers
of today's models.dev for the models it already has. Regenerating also
picks up 11 gateway models that the snapshot already had.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-anthropic/src/usage.ts            |   10 +-
 .../tests/usage-extraction.test.ts            |   48 +
 packages/ai-bedrock/src/converse/usage.ts     |    7 +-
 .../ai-bedrock/tests/converse/usage.test.ts   |   34 +
 packages/ai-event-client/src/index.ts         |    5 +
 packages/ai-models/scripts/catalog.ts         |   28 +-
 packages/ai-models/scripts/providers.ts       |    5 +
 packages/ai-models/scripts/rules.ts           |    7 +
 packages/ai-models/src/catalog.ts             |    2 +-
 packages/ai-models/src/cost.ts                |   24 +-
 packages/ai-models/src/index.ts               |    1 +
 .../ai-models/src/providers/amazon-bedrock.ts |  320 +-
 .../src/providers/azure-openai-responses.ts   |  208 +-
 .../src/providers/cloudflare-ai-gateway.ts    |   96 +-
 packages/ai-models/src/providers/fireworks.ts |   16 +-
 .../ai-models/src/providers/google-vertex.ts  |  419 +-
 packages/ai-models/src/providers/google.ts    |   96 +-
 .../ai-models/src/providers/minimax-cn.ts     |   16 +-
 packages/ai-models/src/providers/minimax.ts   |   16 +-
 packages/ai-models/src/providers/openai.ts    |  208 +-
 .../ai-models/src/providers/opencode-go.ts    |  128 +-
 packages/ai-models/src/providers/opencode.ts  |  256 +-
 .../ai-models/src/providers/openrouter.ts     | 1101 ++++-
 .../src/providers/qwen-token-plan-cn.ts       |   64 +-
 .../providers/qwen-token-plan-individual.ts   |   16 +-
 .../src/providers/qwen-token-plan.ts          |   32 +-
 .../src/providers/vercel-ai-gateway.ts        |  914 ++++-
 packages/ai-models/src/providers/xai.ts       |  128 +-
 packages/ai-models/src/types.ts               |   22 +-
 packages/ai-models/tests/catalog.test.ts      |   90 +-
 scripts/fetch-models-dev.ts                   |   15 +
 scripts/models-dev.models.json                | 3643 +++++++++++++++--
 32 files changed, 7134 insertions(+), 841 deletions(-)
 create mode 100644 packages/ai-bedrock/tests/converse/usage.test.ts

diff --git a/packages/ai-anthropic/src/usage.ts b/packages/ai-anthropic/src/usage.ts
index 275606ef03..91dc038400 100644
--- a/packages/ai-anthropic/src/usage.ts
+++ b/packages/ai-anthropic/src/usage.ts
@@ -25,7 +25,8 @@ export type AnthropicProviderUsageDetails = {
  * `promptTokens` is the total input: uncached + cache read + cache write.
  * Anthropic's `input_tokens` counts only the uncached part, so this function
  * adds the cache parts. The cache parts are also in `promptTokensDetails`:
- * `cachedTokens` (read) and `cacheWriteTokens` (write). `totalTokens` is
+ * `cachedTokens` (read), `cacheWriteTokens` (write), and `cacheWrite1hTokens`
+ * (the 1-hour part of the write). `totalTokens` is
  * `promptTokens + completionTokens`.
  *
  * Also handles server tool use metrics. Returns `undefined` when the provider
@@ -53,6 +54,12 @@ export function buildAnthropicUsage(
     usage.cache_creation_input_tokens ?? start?.cache_creation_input_tokens ?? 0
   const cacheRead =
     usage.cache_read_input_tokens ?? start?.cache_read_input_tokens ?? 0
+  // The 1-hour part of the cache write (`promptCache: 'long'`). A closing
+  // message_delta has no `cache_creation`, so a stream takes message_start's.
+  const cacheCreation =
+    ('cache_creation' in usage ? usage.cache_creation : null) ??
+    start?.cache_creation
+  const cacheWrite1h = cacheCreation?.ephemeral_1h_input_tokens ?? 0
   // `input_tokens` is only the uncached part. Add the cache parts so
   // promptTokens is the total input, the same as the other adapters.
   const promptTokens = inputTokens + cacheRead + cacheWrite
@@ -68,6 +75,7 @@ export function buildAnthropicUsage(
   // other adapter guards with the same Object.keys check).
   const promptTokensDetails = {
     ...(cacheWrite ? { cacheWriteTokens: cacheWrite } : {}),
+    ...(cacheWrite1h ? { cacheWrite1hTokens: cacheWrite1h } : {}),
     ...(cacheRead ? { cachedTokens: cacheRead } : {}),
   }
   if (Object.keys(promptTokensDetails).length > 0) {
diff --git a/packages/ai-anthropic/tests/usage-extraction.test.ts b/packages/ai-anthropic/tests/usage-extraction.test.ts
index b031e2bfe5..5dd8571364 100644
--- a/packages/ai-anthropic/tests/usage-extraction.test.ts
+++ b/packages/ai-anthropic/tests/usage-extraction.test.ts
@@ -336,6 +336,54 @@ describe('Anthropic usage extraction', () => {
     },
   )
 
+  it('reports the 1-hour part of the cache write from message_start', async () => {
+    mocks.betaMessagesCreate.mockResolvedValueOnce(
+      createMockStream([
+        {
+          type: 'message_start',
+          message: {
+            id: 'msg_123',
+            type: 'message',
+            role: 'assistant',
+            content: [],
+            model: 'claude-opus-4-1',
+            usage: {
+              input_tokens: 10,
+              output_tokens: 1,
+              cache_creation_input_tokens: 300,
+              cache_read_input_tokens: 0,
+              cache_creation: {
+                ephemeral_1h_input_tokens: 200,
+                ephemeral_5m_input_tokens: 100,
+              },
+            },
+          },
+        },
+        {
+          type: 'message_delta',
+          delta: { stop_reason: 'end_turn' },
+          usage: { output_tokens: 5 },
+        },
+        { type: 'message_stop' },
+      ]),
+    )
+
+    const chunks: Array<AdapterYieldChunk> = []
+    for await (const chunk of createAdapter().chatStream({
+      model: 'claude-opus-4-1',
+      messages: [{ role: 'user', content: 'Hello' }],
+      logger: createSilentLogger(),
+    })) {
+      chunks.push(chunk)
+    }
+
+    const done = chunks.find((c) => c.type === 'RUN_FINISHED')
+    expect(tokenUsageOf(done)?.promptTokensDetails).toEqual({
+      cacheWriteTokens: 300,
+      cacheWrite1hTokens: 200,
+    })
+  })
+
   it('takes the message_delta counts over message_start when both are present', async () => {
     mocks.betaMessagesCreate.mockResolvedValueOnce(
       createMockStream([
diff --git a/packages/ai-bedrock/src/converse/usage.ts b/packages/ai-bedrock/src/converse/usage.ts
index 7229c0cedb..ae2ebb5924 100644
--- a/packages/ai-bedrock/src/converse/usage.ts
+++ b/packages/ai-bedrock/src/converse/usage.ts
@@ -6,7 +6,8 @@ import type { TokenUsage as ConverseTokenUsage } from '@aws-sdk/client-bedrock-r
  *
  * `promptTokens` is the total input. Converse `inputTokens` is only the
  * uncached part, so the cache reads and cache writes are added to it. The two
- * cache parts also go on `promptTokensDetails`. Zero is kept, unlike the
+ * cache parts also go on `promptTokensDetails`, with `cacheWrite1hTokens` for
+ * the writes with a 1-hour TTL in `cacheDetails`. Zero is kept, unlike the
  * Anthropic and OpenAI builders. Bedrock leaves the fields out when no
  * checkpoint applied and sends 0 when one did (a served checkpoint writes 0),
  * so absent and zero are different results.
@@ -14,6 +15,9 @@ import type { TokenUsage as ConverseTokenUsage } from '@aws-sdk/client-bedrock-r
 export function buildConverseUsage(usage: ConverseTokenUsage) {
   const cachedTokens = usage.cacheReadInputTokens
   const cacheWriteTokens = usage.cacheWriteInputTokens
+  const cacheWrite1hTokens = usage.cacheDetails
+    ?.filter((detail) => detail.ttl === '1h')
+    .reduce((total, detail) => total + (detail.inputTokens ?? 0), 0)
   const promptTokens =
     (usage.inputTokens ?? 0) + (cachedTokens ?? 0) + (cacheWriteTokens ?? 0)
   const completionTokens = usage.outputTokens ?? 0
@@ -30,6 +34,7 @@ export function buildConverseUsage(usage: ConverseTokenUsage) {
   const promptTokensDetails = {
     ...(cachedTokens !== undefined ? { cachedTokens } : {}),
     ...(cacheWriteTokens !== undefined ? { cacheWriteTokens } : {}),
+    ...(cacheWrite1hTokens ? { cacheWrite1hTokens } : {}),
   }
   if (Object.keys(promptTokensDetails).length > 0) {
     result.promptTokensDetails = promptTokensDetails
diff --git a/packages/ai-bedrock/tests/converse/usage.test.ts b/packages/ai-bedrock/tests/converse/usage.test.ts
new file mode 100644
index 0000000000..8ea6e2cbcd
--- /dev/null
+++ b/packages/ai-bedrock/tests/converse/usage.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import { buildConverseUsage } from '../../src/converse/usage'
+
+describe('buildConverseUsage', () => {
+  it('reports the cache writes with a 1-hour TTL', () => {
+    const usage = buildConverseUsage({
+      inputTokens: 10,
+      outputTokens: 5,
+      totalTokens: 15,
+      cacheReadInputTokens: 0,
+      cacheWriteInputTokens: 300,
+      cacheDetails: [
+        { ttl: '1h', inputTokens: 200 },
+        { ttl: '5m', inputTokens: 100 },
+      ],
+    })
+    expect(usage.promptTokensDetails).toEqual({
+      cachedTokens: 0,
+      cacheWriteTokens: 300,
+      cacheWrite1hTokens: 200,
+    })
+  })
+
+  it('sends no 1-hour field without 1-hour writes', () => {
+    const usage = buildConverseUsage({
+      inputTokens: 10,
+      outputTokens: 5,
+      totalTokens: 15,
+      cacheWriteInputTokens: 100,
+      cacheDetails: [{ ttl: '5m', inputTokens: 100 }],
+    })
+    expect(usage.promptTokensDetails).toEqual({ cacheWriteTokens: 100 })
+  })
+})
diff --git a/packages/ai-event-client/src/index.ts b/packages/ai-event-client/src/index.ts
index 0e95002d31..e639eeb7f9 100644
--- a/packages/ai-event-client/src/index.ts
+++ b/packages/ai-event-client/src/index.ts
@@ -161,6 +161,11 @@ export interface PromptTokensDetails {
   cachedTokens?: number
   /** Tokens written to cache */
   cacheWriteTokens?: number
+  /**
+   * The part of `cacheWriteTokens` written with a 1-hour retention
+   * (`promptCache: 'long'`). Providers price it higher than a 5-minute write.
+   */
+  cacheWrite1hTokens?: number
   /** Audio input tokens */
   audioTokens?: number
   /** Video input tokens */
diff --git a/packages/ai-models/scripts/catalog.ts b/packages/ai-models/scripts/catalog.ts
index 69af0ab2d1..4318a66ccc 100644
--- a/packages/ai-models/scripts/catalog.ts
+++ b/packages/ai-models/scripts/catalog.ts
@@ -11,6 +11,7 @@ import type { ProviderRow, Wire } from './providers'
 import type { DevModel } from './rules'
 import type {
   ModelCompat,
+  ModelCostRates,
   ModelRecord,
   ProviderRecord,
   WireApi,
@@ -45,6 +46,27 @@ const mergeCompat = (
   return Object.keys(merged).length > 0 ? merged : undefined
 }
 
+/**
+ * The models.dev context tiers, in pi's shape. A tier price that models.dev
+ * leaves out is 0, as in pi's catalog.
+ */
+function costTiers(model: DevModel): ModelCostRates['tiers'] {
+  const tiers = (model.cost?.tiers ?? []).flatMap((tier) =>
+    tier.tier?.type === 'context' && tier.tier.size !== undefined
+      ? [
+          {
+            inputTokensAbove: tier.tier.size,
+            input: tier.input ?? 0,
+            output: tier.output ?? 0,
+            cacheRead: tier.cache_read ?? 0,
+            cacheWrite: tier.cache_write ?? 0,
+          },
+        ]
+      : [],
+  )
+  return tiers.length > 0 ? tiers : undefined
+}
+
 /** Turn one models.dev model into a catalog record for `row`. */
 export function toRecord(
   row: ProviderRow,
@@ -75,12 +97,13 @@ export function toRecord(
     reasoning,
     reasoningMap: map,
     reasoningBudget: budget || undefined,
-    cost: {
+    cost: compact({
       input: model.cost?.input ?? 0,
       output: model.cost?.output ?? 0,
       cacheRead: model.cost?.cache_read ?? 0,
       cacheWrite: model.cost?.cache_write ?? 0,
-    },
+      tiers: costTiers(model),
+    }),
     contextWindow: model.limit?.context ?? 0,
     maxTokens: model.limit?.output ?? 0,
     headers: row.headers,
@@ -108,6 +131,7 @@ export function buildModels(
     for (const [sourceId, model] of Object.entries(
       inputs.dev[source]?.models ?? {},
     )) {
+      if (row.exclude?.(sourceId)) continue
       const id = row.modelId?.(sourceId) ?? sourceId
       if (records.has(id) || !allowed(id) || !makesText(model)) continue
       records.set(id, toRecord(row, id, model, sourceId))
diff --git a/packages/ai-models/scripts/providers.ts b/packages/ai-models/scripts/providers.ts
index 7e361400c8..d39cc3d3cf 100644
--- a/packages/ai-models/scripts/providers.ts
+++ b/packages/ai-models/scripts/providers.ts
@@ -32,6 +32,8 @@ export interface ProviderRow {
   wire?: (model: SourceModel) => Wire
   /** The model id the catalog uses, from the models.dev id. Default: the same. */
   modelId?: (sourceId: string) => string
+  /** `true`: leave this models.dev model out, for example one on a wire no adapter here takes. */
+  exclude?: (sourceId: string) => boolean
   /** Quirks of every model of this provider. */
   compat?: ModelCompat
   /** Quirks of some models of this provider, by model id. */
@@ -286,6 +288,9 @@ export const PROVIDERS: ReadonlyArray<ProviderRow> = [
     sources: ['google-vertex'],
     baseUrl: 'https://{location}-aiplatform.googleapis.com',
     api: 'google-vertex',
+    // Claude on Vertex speaks the Anthropic Messages wire, which the Gemini
+    // adapter cannot call. pi lists no Claude models on Vertex either.
+    exclude: (id) => id.startsWith('claude-'),
     // An API key, or Application Default Credentials with a project and a location.
     env: [
       ['GOOGLE_CLOUD_API_KEY'],
diff --git a/packages/ai-models/scripts/rules.ts b/packages/ai-models/scripts/rules.ts
index 0057245cda..b2c5a8b8aa 100644
--- a/packages/ai-models/scripts/rules.ts
+++ b/packages/ai-models/scripts/rules.ts
@@ -30,6 +30,13 @@ export interface DevModel {
     output?: number
     cache_read?: number
     cache_write?: number
+    tiers?: ReadonlyArray<{
+      input?: number
+      output?: number
+      cache_read?: number
+      cache_write?: number
+      tier?: { type?: string; size?: number }
+    }>
   }
   limit?: { context?: number; output?: number }
   provider?: { npm?: string; api?: string }
diff --git a/packages/ai-models/src/catalog.ts b/packages/ai-models/src/catalog.ts
index 71b3773e09..18bf78f320 100644
--- a/packages/ai-models/src/catalog.ts
+++ b/packages/ai-models/src/catalog.ts
@@ -39,7 +39,7 @@ import * as zai from './providers/zai'
 import * as zaiCodingCn from './providers/zai-coding-cn'
 
 /** The day the catalog was generated, as `YYYY-MM-DD`. */
-export const generatedAt = '2026-09-30'
+export const generatedAt = '2026-10-06'
 
 /** Every provider module, in id order. */
 export const providerModules = [
diff --git a/packages/ai-models/src/cost.ts b/packages/ai-models/src/cost.ts
index 5e79fd481f..9c94173010 100644
--- a/packages/ai-models/src/cost.ts
+++ b/packages/ai-models/src/cost.ts
@@ -2,17 +2,31 @@ import type { Cost, ModelRecord, TokenCounts } from './types'
 
 /**
  * What a call cost in USD: each price is per 1M tokens, so the cost of a part
- * is `price / 1_000_000 * tokens`.
+ * is `price / 1_000_000 * tokens`. pi's rules:
+ * - A call with more input than a tier's `inputTokensAbove` uses that tier's
+ *   prices: the tier with the highest threshold below the input (uncached +
+ *   cache read + cache write).
+ * - A 1-hour cache write (`cacheWrite1h`) costs 2x the input price. The rest
+ *   of `cacheWrite` costs the cache write price.
  */
 export function modelCost(
   model: Pick<ModelRecord, 'cost'>,
   usage: TokenCounts,
 ): Cost {
+  const totalInput =
+    usage.input + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0)
+  const rates =
+    (model.cost.tiers ?? [])
+      .filter((tier) => totalInput > tier.inputTokensAbove)
+      .sort((a, b) => b.inputTokensAbove - a.inputTokensAbove)[0] ?? model.cost
   const part = (price: number, tokens = 0) => (price / 1_000_000) * tokens
-  const input = part(model.cost.input, usage.input)
-  const output = part(model.cost.output, usage.output)
-  const cacheRead = part(model.cost.cacheRead, usage.cacheRead)
-  const cacheWrite = part(model.cost.cacheWrite, usage.cacheWrite)
+  const longWrite = usage.cacheWrite1h ?? 0
+  const input = part(rates.input, usage.input)
+  const output = part(rates.output, usage.output)
+  const cacheRead = part(rates.cacheRead, usage.cacheRead)
+  const cacheWrite =
+    part(rates.cacheWrite, (usage.cacheWrite ?? 0) - longWrite) +
+    part(rates.input * 2, longWrite)
   return {
     input,
     output,
diff --git a/packages/ai-models/src/index.ts b/packages/ai-models/src/index.ts
index ac12b525f0..139499e0aa 100644
--- a/packages/ai-models/src/index.ts
+++ b/packages/ai-models/src/index.ts
@@ -13,6 +13,7 @@ export type {
   InputModality,
   ModelCompat,
   ModelCostRates,
+  ModelCostTier,
   ModelReasoning,
   ModelRecord,
   ProviderRecord,
diff --git a/packages/ai-models/src/providers/amazon-bedrock.ts b/packages/ai-models/src/providers/amazon-bedrock.ts
index 625115bdbc..75e4f7b599 100644
--- a/packages/ai-models/src/providers/amazon-bedrock.ts
+++ b/packages/ai-models/src/providers/amazon-bedrock.ts
@@ -1385,7 +1385,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    cost: {
+      input: 0.2,
+      output: 1.2,
+      cacheRead: 0.02,
+      cacheWrite: 0.25,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.4,
+          output: 1.8,
+          cacheRead: 0.04,
+          cacheWrite: 0.5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -1407,7 +1421,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
+    cost: {
+      input: 4,
+      output: 20,
+      cacheRead: 0.4,
+      cacheWrite: 5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 8,
+          output: 30,
+          cacheRead: 0.8,
+          cacheWrite: 10,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -1429,7 +1457,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -1451,7 +1493,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    cost: {
+      input: 10,
+      output: 50,
+      cacheRead: 1,
+      cacheWrite: 12.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 20,
+          output: 75,
+          cacheRead: 2,
+          cacheWrite: 25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -1473,7 +1529,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    cost: {
+      input: 0.1,
+      output: 0.5,
+      cacheRead: 0.01,
+      cacheWrite: 0.125,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.2,
+          output: 0.75,
+          cacheRead: 0.02,
+          cacheWrite: 0.25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -1495,7 +1565,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 10,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 15,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -1658,7 +1742,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.22, output: 1.32, cacheRead: 0.022, cacheWrite: 0.275 },
+    cost: {
+      input: 0.22,
+      output: 1.32,
+      cacheRead: 0.022,
+      cacheWrite: 0.275,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.44,
+          output: 1.98,
+          cacheRead: 0.044,
+          cacheWrite: 0.55,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -1680,7 +1778,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2.2, output: 13.2, cacheRead: 0.22, cacheWrite: 2.75 },
+    cost: {
+      input: 2.2,
+      output: 13.2,
+      cacheRead: 0.22,
+      cacheWrite: 2.75,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4.4,
+          output: 19.8,
+          cacheRead: 0.44,
+          cacheWrite: 5.5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -2221,7 +2333,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.22, output: 1.32, cacheRead: 0.022, cacheWrite: 0.275 },
+    cost: {
+      input: 0.22,
+      output: 1.32,
+      cacheRead: 0.022,
+      cacheWrite: 0.275,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.44,
+          output: 1.98,
+          cacheRead: 0.044,
+          cacheWrite: 0.55,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -2243,7 +2369,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 4.4, output: 22, cacheRead: 0.44, cacheWrite: 5.5 },
+    cost: {
+      input: 4.4,
+      output: 22,
+      cacheRead: 0.44,
+      cacheWrite: 5.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 8.8,
+          output: 33,
+          cacheRead: 0.88,
+          cacheWrite: 11,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -2265,7 +2405,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2.2, output: 13.2, cacheRead: 0.22, cacheWrite: 2.75 },
+    cost: {
+      input: 2.2,
+      output: 13.2,
+      cacheRead: 0.22,
+      cacheWrite: 2.75,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4.4,
+          output: 19.8,
+          cacheRead: 0.44,
+          cacheWrite: 5.5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -2287,7 +2441,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 11, output: 55, cacheRead: 1.1, cacheWrite: 13.75 },
+    cost: {
+      input: 11,
+      output: 55,
+      cacheRead: 1.1,
+      cacheWrite: 13.75,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 22,
+          output: 82.5,
+          cacheRead: 2.2,
+          cacheWrite: 27.5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -2309,7 +2477,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.11, output: 0.55, cacheRead: 0.011, cacheWrite: 0.1375 },
+    cost: {
+      input: 0.11,
+      output: 0.55,
+      cacheRead: 0.011,
+      cacheWrite: 0.1375,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.22,
+          output: 0.825,
+          cacheRead: 0.022,
+          cacheWrite: 0.275,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -2331,7 +2513,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2.2, output: 11, cacheRead: 0.22, cacheWrite: 2.75 },
+    cost: {
+      input: 2.2,
+      output: 11,
+      cacheRead: 0.22,
+      cacheWrite: 2.75,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4.4,
+          output: 16.5,
+          cacheRead: 0.44,
+          cacheWrite: 5.5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -3078,7 +3274,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.22, output: 1.32, cacheRead: 0.022, cacheWrite: 0.275 },
+    cost: {
+      input: 0.22,
+      output: 1.32,
+      cacheRead: 0.022,
+      cacheWrite: 0.275,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.44,
+          output: 1.98,
+          cacheRead: 0.044,
+          cacheWrite: 0.55,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -3100,7 +3310,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 4.4, output: 22, cacheRead: 0.44, cacheWrite: 5.5 },
+    cost: {
+      input: 4.4,
+      output: 22,
+      cacheRead: 0.44,
+      cacheWrite: 5.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 8.8,
+          output: 33,
+          cacheRead: 0.88,
+          cacheWrite: 11,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -3122,7 +3346,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2.2, output: 13.2, cacheRead: 0.22, cacheWrite: 2.75 },
+    cost: {
+      input: 2.2,
+      output: 13.2,
+      cacheRead: 0.22,
+      cacheWrite: 2.75,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4.4,
+          output: 19.8,
+          cacheRead: 0.44,
+          cacheWrite: 5.5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -3144,7 +3382,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 11, output: 55, cacheRead: 1.1, cacheWrite: 13.75 },
+    cost: {
+      input: 11,
+      output: 55,
+      cacheRead: 1.1,
+      cacheWrite: 13.75,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 22,
+          output: 82.5,
+          cacheRead: 2.2,
+          cacheWrite: 27.5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -3166,7 +3418,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.11, output: 0.55, cacheRead: 0.011, cacheWrite: 0.1375 },
+    cost: {
+      input: 0.11,
+      output: 0.55,
+      cacheRead: 0.011,
+      cacheWrite: 0.1375,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.22,
+          output: 0.825,
+          cacheRead: 0.022,
+          cacheWrite: 0.275,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -3188,7 +3454,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2.2, output: 11, cacheRead: 0.22, cacheWrite: 2.75 },
+    cost: {
+      input: 2.2,
+      output: 11,
+      cacheRead: 0.22,
+      cacheWrite: 2.75,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4.4,
+          output: 16.5,
+          cacheRead: 0.44,
+          cacheWrite: 5.5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
diff --git a/packages/ai-models/src/providers/azure-openai-responses.ts b/packages/ai-models/src/providers/azure-openai-responses.ts
index 575fa35151..7ed8bcf3cf 100644
--- a/packages/ai-models/src/providers/azure-openai-responses.ts
+++ b/packages/ai-models/src/providers/azure-openai-responses.ts
@@ -144,7 +144,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       max: 'max',
     },
     reasoningBudget: true,
-    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    cost: {
+      input: 5,
+      output: 25,
+      cacheRead: 0.5,
+      cacheWrite: 6.25,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 10,
+          output: 37.5,
+          cacheRead: 1,
+          cacheWrite: 12.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 128000,
   },
@@ -187,7 +201,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    cost: {
+      input: 5,
+      output: 25,
+      cacheRead: 0.5,
+      cacheWrite: 6.25,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 10,
+          output: 37.5,
+          cacheRead: 1,
+          cacheWrite: 12.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -1008,7 +1036,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
+    cost: {
+      input: 2.5,
+      output: 15,
+      cacheRead: 0.25,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 5,
+          output: 22.5,
+          cacheRead: 0.5,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
   },
@@ -1071,7 +1113,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 30,
+      output: 180,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 60,
+          output: 270,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -1093,7 +1149,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 5,
+      output: 30,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 10,
+          output: 45,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -1115,7 +1185,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 30,
+      output: 180,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 60,
+          output: 270,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -1138,7 +1222,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    cost: {
+      input: 0.2,
+      output: 1.2,
+      cacheRead: 0.02,
+      cacheWrite: 0.25,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.4,
+          output: 1.8,
+          cacheRead: 0.04,
+          cacheWrite: 0.5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -1160,7 +1258,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 4, output: 20, cacheRead: 0.5, cacheWrite: 6.25 },
+    cost: {
+      input: 4,
+      output: 20,
+      cacheRead: 0.5,
+      cacheWrite: 6.25,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 10,
+          output: 45,
+          cacheRead: 1,
+          cacheWrite: 12.5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -1182,7 +1294,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -1204,7 +1330,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    cost: {
+      input: 10,
+      output: 50,
+      cacheRead: 1,
+      cacheWrite: 12.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 20,
+          output: 75,
+          cacheRead: 2,
+          cacheWrite: 25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -1226,7 +1366,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    cost: {
+      input: 0.1,
+      output: 0.5,
+      cacheRead: 0.01,
+      cacheWrite: 0.125,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.2,
+          output: 0.75,
+          cacheRead: 0.02,
+          cacheWrite: 0.25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -1248,7 +1402,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 10,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 15,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
@@ -1270,7 +1438,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 10,
+      cacheRead: 0.1,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 15,
+          cacheRead: 0.2,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsTemperature: false },
diff --git a/packages/ai-models/src/providers/cloudflare-ai-gateway.ts b/packages/ai-models/src/providers/cloudflare-ai-gateway.ts
index 332590ca8c..82b06f5718 100644
--- a/packages/ai-models/src/providers/cloudflare-ai-gateway.ts
+++ b/packages/ai-models/src/providers/cloudflare-ai-gateway.ts
@@ -899,7 +899,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12 },
+    cost: {
+      input: 10,
+      output: 50,
+      cacheRead: 1,
+      cacheWrite: 12,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 20,
+          output: 75,
+          cacheRead: 2,
+          cacheWrite: 25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -926,7 +940,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    cost: {
+      input: 0.1,
+      output: 0.5,
+      cacheRead: 0.01,
+      cacheWrite: 0.125,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.2,
+          output: 0.75,
+          cacheRead: 0.02,
+          cacheWrite: 0.25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -953,7 +981,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 10,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 15,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -1697,7 +1739,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.3, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.3,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 12,
+          cacheRead: 0.6,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 500000,
     compat: {
@@ -1727,7 +1783,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 12,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 500000,
     compat: {
@@ -1757,7 +1827,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 12,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 500000,
     compat: {
diff --git a/packages/ai-models/src/providers/fireworks.ts b/packages/ai-models/src/providers/fireworks.ts
index b50dc03b2f..e9deb986be 100644
--- a/packages/ai-models/src/providers/fireworks.ts
+++ b/packages/ai-models/src/providers/fireworks.ts
@@ -550,7 +550,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       high: 'high',
     },
     reasoningBudget: true,
-    cost: { input: 0.4, output: 1.6, cacheRead: 0.04, cacheWrite: 0.5 },
+    cost: {
+      input: 0.4,
+      output: 1.6,
+      cacheRead: 0.04,
+      cacheWrite: 0.5,
+      tiers: [
+        {
+          inputTokensAbove: 256000,
+          input: 1.2,
+          output: 4.8,
+          cacheRead: 0.12,
+          cacheWrite: 1.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 131072,
     compat: {
diff --git a/packages/ai-models/src/providers/google-vertex.ts b/packages/ai-models/src/providers/google-vertex.ts
index 8b8c4e3311..7fab1d1fb6 100644
--- a/packages/ai-models/src/providers/google-vertex.ts
+++ b/packages/ai-models/src/providers/google-vertex.ts
@@ -24,313 +24,6 @@ export const provider: ProviderRecord = {
 
 /** Every Google Vertex AI model, sorted by id. */
 export const models: ReadonlyArray<ModelRecord> = [
-  {
-    id: 'claude-fable-5-1@default',
-    provider: 'google-vertex',
-    name: 'Claude Fable 5.1',
-    api: 'google-vertex',
-    baseUrl: 'https://{location}-aiplatform.googleapis.com',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningMap: {
-      off: null,
-      minimal: null,
-      low: 'low',
-      medium: 'medium',
-      high: 'high',
-      xhigh: 'xhigh',
-      max: 'max',
-    },
-    cost: { input: 10, output: 50, cacheRead: 0.25, cacheWrite: 12.5 },
-    contextWindow: 1000000,
-    maxTokens: 128000,
-    compat: { supportsTemperature: false },
-  },
-  {
-    id: 'claude-fable-5@default',
-    provider: 'google-vertex',
-    name: 'Claude Fable 5',
-    api: 'google-vertex',
-    baseUrl: 'https://{location}-aiplatform.googleapis.com',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningMap: {
-      off: null,
-      minimal: null,
-      low: 'low',
-      medium: 'medium',
-      high: 'high',
-      xhigh: 'xhigh',
-      max: 'max',
-    },
-    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
-    contextWindow: 1000000,
-    maxTokens: 128000,
-    compat: { supportsTemperature: false },
-  },
-  {
-    id: 'claude-haiku-4-5@20251001',
-    provider: 'google-vertex',
-    name: 'Claude Haiku 4.5',
-    api: 'google-vertex',
-    baseUrl: 'https://{location}-aiplatform.googleapis.com',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningBudget: true,
-    cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
-    contextWindow: 200000,
-    maxTokens: 64000,
-  },
-  {
-    id: 'claude-opus-4-1@20250805',
-    provider: 'google-vertex',
-    name: 'Claude Opus 4.1',
-    api: 'google-vertex',
-    baseUrl: 'https://{location}-aiplatform.googleapis.com',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningBudget: true,
-    cost: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
-    contextWindow: 200000,
-    maxTokens: 32000,
-  },
-  {
-    id: 'claude-opus-4-5@20251101',
-    provider: 'google-vertex',
-    name: 'Claude Opus 4.5',
-    api: 'google-vertex',
-    baseUrl: 'https://{location}-aiplatform.googleapis.com',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningMap: {
-      off: null,
-      minimal: null,
-      low: 'low',
-      medium: 'medium',
-      high: 'high',
-      xhigh: null,
-      max: null,
-    },
-    reasoningBudget: true,
-    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
-    contextWindow: 200000,
-    maxTokens: 64000,
-  },
-  {
-    id: 'claude-opus-4-6@default',
-    provider: 'google-vertex',
-    name: 'Claude Opus 4.6',
-    api: 'google-vertex',
-    baseUrl: 'https://{location}-aiplatform.googleapis.com',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningMap: {
-      off: null,
-      minimal: null,
-      low: 'low',
-      medium: 'medium',
-      high: 'high',
-      xhigh: null,
-      max: 'max',
-    },
-    reasoningBudget: true,
-    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
-    contextWindow: 1000000,
-    maxTokens: 128000,
-  },
-  {
-    id: 'claude-opus-4-7@default',
-    provider: 'google-vertex',
-    name: 'Claude Opus 4.7',
-    api: 'google-vertex',
-    baseUrl: 'https://{location}-aiplatform.googleapis.com',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningMap: {
-      off: null,
-      minimal: null,
-      low: 'low',
-      medium: 'medium',
-      high: 'high',
-      xhigh: 'xhigh',
-      max: 'max',
-    },
-    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
-    contextWindow: 1000000,
-    maxTokens: 128000,
-    compat: { supportsTemperature: false },
-  },
-  {
-    id: 'claude-opus-4-8@default',
-    provider: 'google-vertex',
-    name: 'Claude Opus 4.8',
-    api: 'google-vertex',
-    baseUrl: 'https://{location}-aiplatform.googleapis.com',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningMap: {
-      off: null,
-      minimal: null,
-      low: 'low',
-      medium: 'medium',
-      high: 'high',
-      xhigh: 'xhigh',
-      max: 'max',
-    },
-    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
-    contextWindow: 1000000,
-    maxTokens: 128000,
-    compat: { supportsTemperature: false },
-  },
-  {
-    id: 'claude-opus-4@20250514',
-    provider: 'google-vertex',
-    name: 'Claude Opus 4',
-    api: 'google-vertex',
-    baseUrl: 'https://{location}-aiplatform.googleapis.com',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningBudget: true,
-    cost: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
-    contextWindow: 200000,
-    maxTokens: 32000,
-  },
-  {
-    id: 'claude-opus-5-5@default',
-    provider: 'google-vertex',
-    name: 'Claude Opus 5.5',
-    api: 'google-vertex',
-    baseUrl: 'https://{location}-aiplatform.googleapis.com',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningMap: {
-      off: null,
-      minimal: null,
-      low: 'low',
-      medium: 'medium',
-      high: 'high',
-      xhigh: 'xhigh',
-      max: 'max',
-    },
-    cost: { input: 4, output: 20, cacheRead: 0.2, cacheWrite: 5 },
-    contextWindow: 1000000,
-    maxTokens: 128000,
-    compat: { supportsTemperature: false },
-  },
-  {
-    id: 'claude-opus-5@default',
-    provider: 'google-vertex',
-    name: 'Claude Opus 5',
-    api: 'google-vertex',
-    baseUrl: 'https://{location}-aiplatform.googleapis.com',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningMap: {
-      off: null,
-      minimal: null,
-      low: 'low',
-      medium: 'medium',
-      high: 'high',
-      xhigh: 'xhigh',
-      max: 'max',
-    },
-    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
-    contextWindow: 1000000,
-    maxTokens: 128000,
-    compat: { supportsTemperature: false },
-  },
-  {
-    id: 'claude-sonnet-4-5@20250929',
-    provider: 'google-vertex',
-    name: 'Claude Sonnet 4.5',
-    api: 'google-vertex',
-    baseUrl: 'https://{location}-aiplatform.googleapis.com',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningBudget: true,
-    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
-    contextWindow: 200000,
-    maxTokens: 64000,
-  },
-  {
-    id: 'claude-sonnet-4-6@default',
-    provider: 'google-vertex',
-    name: 'Claude Sonnet 4.6',
-    api: 'google-vertex',
-    baseUrl: 'https://{location}-aiplatform.googleapis.com',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningMap: {
-      off: null,
-      minimal: null,
-      low: 'low',
-      medium: 'medium',
-      high: 'high',
-      xhigh: null,
-      max: 'max',
-    },
-    reasoningBudget: true,
-    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
-    contextWindow: 1000000,
-    maxTokens: 128000,
-  },
-  {
-    id: 'claude-sonnet-4@20250514',
-    provider: 'google-vertex',
-    name: 'Claude Sonnet 4',
-    api: 'google-vertex',
-    baseUrl: 'https://{location}-aiplatform.googleapis.com',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningBudget: true,
-    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
-    contextWindow: 200000,
-    maxTokens: 64000,
-  },
-  {
-    id: 'claude-sonnet-5-5@default',
-    provider: 'google-vertex',
-    name: 'Claude Sonnet 5.5',
-    api: 'google-vertex',
-    baseUrl: 'https://{location}-aiplatform.googleapis.com',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningMap: {
-      off: null,
-      minimal: null,
-      low: 'low',
-      medium: 'medium',
-      high: 'high',
-      xhigh: 'xhigh',
-      max: 'max',
-    },
-    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
-    contextWindow: 1000000,
-    maxTokens: 128000,
-    compat: { supportsTemperature: false },
-  },
-  {
-    id: 'claude-sonnet-5@default',
-    provider: 'google-vertex',
-    name: 'Claude Sonnet 5',
-    api: 'google-vertex',
-    baseUrl: 'https://{location}-aiplatform.googleapis.com',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningMap: {
-      off: 'none',
-      minimal: null,
-      low: 'low',
-      medium: 'medium',
-      high: 'high',
-      xhigh: 'xhigh',
-      max: 'max',
-    },
-    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
-    contextWindow: 1000000,
-    maxTokens: 128000,
-    compat: { supportsTemperature: false },
-  },
   {
     id: 'deepseek-ai/deepseek-v3.1-maas',
     provider: 'google-vertex',
@@ -416,7 +109,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     input: ['text', 'image', 'audio', 'video', 'document'],
     reasoning: true,
     reasoningBudget: true,
-    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 10,
+      cacheRead: 0.125,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2.5,
+          output: 15,
+          cacheRead: 0.25,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1048576,
     maxTokens: 65536,
   },
@@ -533,7 +240,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1048576,
     maxTokens: 65536,
   },
@@ -554,7 +275,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1048576,
     maxTokens: 65536,
   },
@@ -840,7 +575,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://{location}-aiplatform.googleapis.com',
     input: ['text', 'image'],
     reasoning: false,
-    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 2.5,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2.5,
+          output: 5,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 2000000,
     maxTokens: 30000,
   },
@@ -852,7 +601,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://{location}-aiplatform.googleapis.com',
     input: ['text', 'image'],
     reasoning: true,
-    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 2.5,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2.5,
+          output: 5,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 2000000,
     maxTokens: 30000,
   },
@@ -864,7 +627,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://{location}-aiplatform.googleapis.com',
     input: ['text', 'image'],
     reasoning: true,
-    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 2.5,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2.5,
+          output: 5,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 200000,
     maxTokens: 30000,
   },
@@ -876,7 +653,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://{location}-aiplatform.googleapis.com',
     input: ['text', 'image'],
     reasoning: true,
-    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 12,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 524288,
     maxTokens: 500000,
   },
diff --git a/packages/ai-models/src/providers/google.ts b/packages/ai-models/src/providers/google.ts
index 6b88b186c4..53ecfb7d40 100644
--- a/packages/ai-models/src/providers/google.ts
+++ b/packages/ai-models/src/providers/google.ts
@@ -20,7 +20,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
     input: ['text', 'image', 'audio', 'video', 'document'],
     reasoning: true,
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 131072,
     maxTokens: 65536,
   },
@@ -32,7 +46,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
     input: ['text', 'image', 'audio', 'video', 'document'],
     reasoning: true,
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 131072,
     maxTokens: 65536,
   },
@@ -44,7 +72,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
     input: ['text', 'image'],
     reasoning: true,
-    cost: { input: 1.25, output: 10, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 10,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2.5,
+          output: 15,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 128000,
     maxTokens: 64000,
   },
@@ -109,7 +151,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     input: ['text', 'image', 'audio', 'video', 'document'],
     reasoning: true,
     reasoningBudget: true,
-    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 10,
+      cacheRead: 0.125,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2.5,
+          output: 15,
+          cacheRead: 0.25,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1048576,
     maxTokens: 65536,
   },
@@ -310,7 +366,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1048576,
     maxTokens: 65536,
   },
@@ -331,7 +401,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1048576,
     maxTokens: 65536,
   },
diff --git a/packages/ai-models/src/providers/minimax-cn.ts b/packages/ai-models/src/providers/minimax-cn.ts
index 40ca0864e9..9787199788 100644
--- a/packages/ai-models/src/providers/minimax-cn.ts
+++ b/packages/ai-models/src/providers/minimax-cn.ts
@@ -99,7 +99,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       medium: null,
       high: 'high',
     },
-    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+    cost: {
+      input: 0.3,
+      output: 1.2,
+      cacheRead: 0.06,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 512000,
+          input: 0.6,
+          output: 2.4,
+          cacheRead: 0.12,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 512000,
   },
diff --git a/packages/ai-models/src/providers/minimax.ts b/packages/ai-models/src/providers/minimax.ts
index 7d15652390..f272c93dbb 100644
--- a/packages/ai-models/src/providers/minimax.ts
+++ b/packages/ai-models/src/providers/minimax.ts
@@ -99,7 +99,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       medium: null,
       high: 'high',
     },
-    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+    cost: {
+      input: 0.3,
+      output: 1.2,
+      cacheRead: 0.06,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 512000,
+          input: 0.6,
+          output: 2.4,
+          cacheRead: 0.12,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 512000,
   },
diff --git a/packages/ai-models/src/providers/openai.ts b/packages/ai-models/src/providers/openai.ts
index a60ce516c2..a937e111ed 100644
--- a/packages/ai-models/src/providers/openai.ts
+++ b/packages/ai-models/src/providers/openai.ts
@@ -432,7 +432,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
+    cost: {
+      input: 2.5,
+      output: 15,
+      cacheRead: 0.25,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 5,
+          output: 22.5,
+          cacheRead: 0.5,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsStrictMode: true },
@@ -498,7 +512,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 30,
+      output: 180,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 60,
+          output: 270,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsStrictMode: true, supportsTemperature: false },
@@ -520,7 +548,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 5,
+      output: 30,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 10,
+          output: 45,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsStrictMode: true, supportsTemperature: false },
@@ -542,7 +584,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 30,
+      output: 180,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 60,
+          output: 270,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsStrictMode: true, supportsTemperature: false },
@@ -564,7 +620,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
+    cost: {
+      input: 4,
+      output: 20,
+      cacheRead: 0.4,
+      cacheWrite: 5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 8,
+          output: 30,
+          cacheRead: 0.8,
+          cacheWrite: 10,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsStrictMode: true, supportsTemperature: false },
@@ -586,7 +656,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    cost: {
+      input: 0.2,
+      output: 1.2,
+      cacheRead: 0.02,
+      cacheWrite: 0.25,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.4,
+          output: 1.8,
+          cacheRead: 0.04,
+          cacheWrite: 0.5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsStrictMode: true, supportsTemperature: false },
@@ -608,7 +692,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
+    cost: {
+      input: 4,
+      output: 20,
+      cacheRead: 0.4,
+      cacheWrite: 5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 8,
+          output: 30,
+          cacheRead: 0.8,
+          cacheWrite: 10,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsStrictMode: true, supportsTemperature: false },
@@ -630,7 +728,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsStrictMode: true, supportsTemperature: false },
@@ -652,7 +764,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    cost: {
+      input: 10,
+      output: 50,
+      cacheRead: 1,
+      cacheWrite: 12.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 20,
+          output: 75,
+          cacheRead: 2,
+          cacheWrite: 25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsStrictMode: true, supportsTemperature: false },
@@ -674,7 +800,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    cost: {
+      input: 0.1,
+      output: 0.5,
+      cacheRead: 0.01,
+      cacheWrite: 0.125,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.2,
+          output: 0.75,
+          cacheRead: 0.02,
+          cacheWrite: 0.25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsStrictMode: true, supportsTemperature: false },
@@ -696,7 +836,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 10,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 15,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsStrictMode: true, supportsTemperature: false },
@@ -718,7 +872,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 10,
+      cacheRead: 0.1,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 15,
+          cacheRead: 0.2,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsStrictMode: true, supportsTemperature: false },
@@ -740,7 +908,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
+    cost: {
+      input: 4,
+      output: 20,
+      cacheRead: 0.4,
+      cacheWrite: 5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 8,
+          output: 30,
+          cacheRead: 0.8,
+          cacheWrite: 10,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { supportsStrictMode: true, supportsTemperature: false },
diff --git a/packages/ai-models/src/providers/opencode-go.ts b/packages/ai-models/src/providers/opencode-go.ts
index a1118d8e4e..d4793d38ac 100644
--- a/packages/ai-models/src/providers/opencode-go.ts
+++ b/packages/ai-models/src/providers/opencode-go.ts
@@ -256,7 +256,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    cost: {
+      input: 0.2,
+      output: 1.2,
+      cacheRead: 0.02,
+      cacheWrite: 0.25,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.4,
+          output: 1.8,
+          cacheRead: 0.04,
+          cacheWrite: 0.5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -281,7 +295,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    cost: {
+      input: 0.1,
+      output: 0.5,
+      cacheRead: 0.01,
+      cacheWrite: 0.125,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.2,
+          output: 0.75,
+          cacheRead: 0.02,
+          cacheWrite: 0.25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -306,7 +334,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.3, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.3,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 12,
+          cacheRead: 0.6,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 500000,
     compat: { sessionAffinityFormat: 'openai-nosession' },
@@ -328,7 +370,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 12,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 500000,
     compat: { sessionAffinityFormat: 'openai-nosession' },
@@ -350,7 +406,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 12,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 500000,
     compat: { sessionAffinityFormat: 'openai-nosession' },
@@ -632,7 +702,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       medium: null,
       high: 'high',
     },
-    cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+    cost: {
+      input: 0.3,
+      output: 1.2,
+      cacheRead: 0.06,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 512000,
+          input: 0.6,
+          output: 2.4,
+          cacheRead: 0.12,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 131072,
   },
@@ -696,7 +780,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       high: 'high',
     },
     reasoningBudget: true,
-    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0.625 },
+    cost: {
+      input: 0.5,
+      output: 3,
+      cacheRead: 0.05,
+      cacheWrite: 0.625,
+      tiers: [
+        {
+          inputTokensAbove: 256000,
+          input: 2,
+          output: 6,
+          cacheRead: 0.2,
+          cacheWrite: 2.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 65536,
     compat: {
@@ -748,7 +846,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       high: 'high',
     },
     reasoningBudget: true,
-    cost: { input: 0.4, output: 1.6, cacheRead: 0.04, cacheWrite: 0.5 },
+    cost: {
+      input: 0.4,
+      output: 1.6,
+      cacheRead: 0.04,
+      cacheWrite: 0.5,
+      tiers: [
+        {
+          inputTokensAbove: 256000,
+          input: 1.2,
+          output: 4.8,
+          cacheRead: 0.12,
+          cacheWrite: 1.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 65536,
     compat: {
diff --git a/packages/ai-models/src/providers/opencode.ts b/packages/ai-models/src/providers/opencode.ts
index d56c44577a..78b6dd3f5c 100644
--- a/packages/ai-models/src/providers/opencode.ts
+++ b/packages/ai-models/src/providers/opencode.ts
@@ -259,7 +259,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     input: ['text', 'image', 'document'],
     reasoning: true,
     reasoningBudget: true,
-    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    cost: {
+      input: 3,
+      output: 15,
+      cacheRead: 0.3,
+      cacheWrite: 3.75,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 6,
+          output: 22.5,
+          cacheRead: 0.6,
+          cacheWrite: 7.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 64000,
   },
@@ -272,7 +286,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     input: ['text', 'image', 'document'],
     reasoning: true,
     reasoningBudget: true,
-    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    cost: {
+      input: 3,
+      output: 15,
+      cacheRead: 0.3,
+      cacheWrite: 3.75,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 6,
+          output: 22.5,
+          cacheRead: 0.6,
+          cacheWrite: 7.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 64000,
   },
@@ -525,7 +553,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1048576,
     maxTokens: 65536,
   },
@@ -546,7 +588,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1048576,
     maxTokens: 65536,
   },
@@ -1186,7 +1242,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
+    cost: {
+      input: 2.5,
+      output: 15,
+      cacheRead: 0.25,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 5,
+          output: 22.5,
+          cacheRead: 0.5,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { sessionAffinityFormat: 'openai-nosession' },
@@ -1283,7 +1353,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 5,
+      output: 30,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 10,
+          output: 45,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -1333,7 +1417,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    cost: {
+      input: 0.2,
+      output: 1.2,
+      cacheRead: 0.02,
+      cacheWrite: 0.25,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.4,
+          output: 1.8,
+          cacheRead: 0.04,
+          cacheWrite: 0.5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -1358,7 +1456,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
+    cost: {
+      input: 4,
+      output: 20,
+      cacheRead: 0.4,
+      cacheWrite: 5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 8,
+          output: 30,
+          cacheRead: 0.8,
+          cacheWrite: 10,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -1383,7 +1495,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 3.125 },
+    cost: {
+      input: 2.5,
+      output: 15,
+      cacheRead: 0.25,
+      cacheWrite: 3.125,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 5,
+          output: 22.5,
+          cacheRead: 0.5,
+          cacheWrite: 6.25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -1408,7 +1534,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    cost: {
+      input: 10,
+      output: 50,
+      cacheRead: 1,
+      cacheWrite: 12.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 20,
+          output: 75,
+          cacheRead: 2,
+          cacheWrite: 25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -1433,7 +1573,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    cost: {
+      input: 0.1,
+      output: 0.5,
+      cacheRead: 0.01,
+      cacheWrite: 0.125,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.2,
+          output: 0.75,
+          cacheRead: 0.02,
+          cacheWrite: 0.25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -1458,7 +1612,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 10,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 15,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -1483,7 +1651,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 10,
+      cacheRead: 0.1,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 15,
+          cacheRead: 0.2,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -1508,7 +1690,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.3, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.3,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 12,
+          cacheRead: 0.6,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 500000,
     compat: { sessionAffinityFormat: 'openai-nosession' },
@@ -1530,7 +1726,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 12,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 500000,
     compat: { sessionAffinityFormat: 'openai-nosession' },
@@ -1552,7 +1762,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 12,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 500000,
     compat: { sessionAffinityFormat: 'openai-nosession' },
diff --git a/packages/ai-models/src/providers/openrouter.ts b/packages/ai-models/src/providers/openrouter.ts
index 7323a6f6c2..6cc79abd6a 100644
--- a/packages/ai-models/src/providers/openrouter.ts
+++ b/packages/ai-models/src/providers/openrouter.ts
@@ -257,7 +257,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0.375 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 0.375,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1048576,
     maxTokens: 65536,
     compat: {
@@ -313,7 +327,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    cost: {
+      input: 10,
+      output: 50,
+      cacheRead: 1,
+      cacheWrite: 12.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 20,
+          output: 75,
+          cacheRead: 2,
+          cacheWrite: 25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -342,7 +370,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    cost: {
+      input: 0.1,
+      output: 0.5,
+      cacheRead: 0.01,
+      cacheWrite: 0.125,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.2,
+          output: 0.75,
+          cacheRead: 0.02,
+          cacheWrite: 0.25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -400,7 +442,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 10,
+      cacheRead: 0.1,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 15,
+          cacheRead: 0.2,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -429,7 +485,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -458,7 +528,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 12,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 450000,
     compat: {
@@ -1080,7 +1164,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       max: 'max',
     },
     reasoningBudget: true,
-    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    cost: {
+      input: 5,
+      output: 25,
+      cacheRead: 0.5,
+      cacheWrite: 6.25,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 10,
+          output: 37.5,
+          cacheRead: 1,
+          cacheWrite: 12.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 128000,
     compat: {
@@ -1138,7 +1236,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    cost: {
+      input: 5,
+      output: 25,
+      cacheRead: 0.5,
+      cacheWrite: 6.25,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 10,
+          output: 37.5,
+          cacheRead: 1,
+          cacheWrite: 12.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 128000,
     compat: {
@@ -1377,7 +1489,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       medium: null,
       high: 'high',
     },
-    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    cost: {
+      input: 3,
+      output: 15,
+      cacheRead: 0.3,
+      cacheWrite: 3.75,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 6,
+          output: 22.5,
+          cacheRead: 0.6,
+          cacheWrite: 7.5,
+        },
+      ],
+    },
     contextWindow: 200000,
     maxTokens: 64000,
     compat: {
@@ -1404,7 +1530,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       medium: null,
       high: 'high',
     },
-    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    cost: {
+      input: 3,
+      output: 15,
+      cacheRead: 0.3,
+      cacheWrite: 3.75,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 6,
+          output: 22.5,
+          cacheRead: 0.6,
+          cacheWrite: 7.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 64000,
     compat: {
@@ -1453,7 +1593,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: 'max',
     },
-    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    cost: {
+      input: 3,
+      output: 15,
+      cacheRead: 0.3,
+      cacheWrite: 3.75,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 6,
+          output: 22.5,
+          cacheRead: 0.6,
+          cacheWrite: 7.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 128000,
     compat: {
@@ -1616,6 +1770,25 @@ export const models: ReadonlyArray<ModelRecord> = [
       supportsTemperature: false,
     },
   },
+  {
+    id: 'apodex/apodex-1.1-mini:free',
+    provider: 'openrouter',
+    name: 'Apodex: Apodex 1.1 Mini (free)',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 235929,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
   {
     id: 'arcee-ai/trinity-large-thinking',
     provider: 'openrouter',
@@ -1696,7 +1869,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       medium: null,
       high: 'high',
     },
-    cost: { input: 0.25, output: 2, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 0.25,
+      output: 2,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 128000,
+          input: 0.5,
+          output: 4,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 262144,
     maxTokens: 32768,
     compat: {
@@ -1722,7 +1909,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       medium: null,
       high: 'high',
     },
-    cost: { input: 0.075, output: 0.3, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 0.075,
+      output: 0.3,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 128000,
+          input: 0.1,
+          output: 0.8,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 262144,
     maxTokens: 32768,
     compat: {
@@ -1776,7 +1977,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 0.5, output: 3, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 0.5,
+      output: 3,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 128000,
+          input: 1,
+          output: 6,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 262144,
     maxTokens: 131072,
     compat: {
@@ -1804,7 +2019,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 0.25, output: 2, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 0.25,
+      output: 2,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 128000,
+          input: 0.5,
+          output: 4,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 262144,
     maxTokens: 131072,
     compat: {
@@ -1832,7 +2061,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 0.1, output: 0.4, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 0.1,
+      output: 0.4,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 128000,
+          input: 0.2,
+          output: 0.8,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 262144,
     maxTokens: 131072,
     compat: {
@@ -2559,7 +2802,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     input: ['text', 'image', 'audio', 'video', 'document'],
     reasoning: true,
     reasoningBudget: true,
-    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0.375 },
+    cost: {
+      input: 1.25,
+      output: 10,
+      cacheRead: 0.125,
+      cacheWrite: 0.375,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2.5,
+          output: 15,
+          cacheRead: 0.25,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1048576,
     maxTokens: 65536,
     compat: {
@@ -2579,7 +2836,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     input: ['text', 'image', 'audio', 'document'],
     reasoning: true,
     reasoningBudget: true,
-    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0.375 },
+    cost: {
+      input: 1.25,
+      output: 10,
+      cacheRead: 0.125,
+      cacheWrite: 0.375,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2.5,
+          output: 15,
+          cacheRead: 0.25,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1048576,
     maxTokens: 65536,
     compat: {
@@ -2888,7 +3159,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0.375 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 0.375,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1048576,
     maxTokens: 65536,
     compat: {
@@ -2916,7 +3201,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0.375 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 0.375,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1048576,
     maxTokens: 65536,
     compat: {
@@ -3756,6 +4055,25 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     borrowedFrom: 'nano-gpt/inclusionai/ling-3.0-flash-vl',
   },
+  {
+    id: 'inclusionai/ling-3.1-flash',
+    provider: 'openrouter',
+    name: 'inclusionAI: Ling 3.1 Flash',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text'],
+    reasoning: true,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 32768,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
   {
     id: 'inference-net/schematron-v2-small',
     provider: 'openrouter',
@@ -6630,7 +6948,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
+    cost: {
+      input: 2.5,
+      output: 15,
+      cacheRead: 0.25,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 5,
+          output: 22.5,
+          cacheRead: 0.5,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -6804,7 +7136,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 30,
+      output: 180,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 60,
+          output: 270,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -6891,7 +7237,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 5,
+      output: 30,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 10,
+          output: 45,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -6920,7 +7280,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 30,
+      output: 180,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 60,
+          output: 270,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -7007,7 +7381,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    cost: {
+      input: 0.2,
+      output: 1.2,
+      cacheRead: 0.02,
+      cacheWrite: 0.25,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.4,
+          output: 1.8,
+          cacheRead: 0.04,
+          cacheWrite: 0.5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -7036,7 +7424,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    cost: {
+      input: 0.2,
+      output: 1.2,
+      cacheRead: 0.02,
+      cacheWrite: 0.25,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.4,
+          output: 1.8,
+          cacheRead: 0.04,
+          cacheWrite: 0.5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -7123,7 +7525,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 10,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 15,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -7152,7 +7568,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
+    cost: {
+      input: 4,
+      output: 20,
+      cacheRead: 0.4,
+      cacheWrite: 5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 15,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -7239,7 +7669,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -7268,7 +7712,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -7355,7 +7813,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    cost: {
+      input: 10,
+      output: 50,
+      cacheRead: 1,
+      cacheWrite: 12.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 20,
+          output: 75,
+          cacheRead: 2,
+          cacheWrite: 25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -7384,7 +7856,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    cost: {
+      input: 10,
+      output: 50,
+      cacheRead: 1,
+      cacheWrite: 12.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 20,
+          output: 75,
+          cacheRead: 2,
+          cacheWrite: 25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -7471,7 +7957,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    cost: {
+      input: 0.1,
+      output: 0.5,
+      cacheRead: 0.01,
+      cacheWrite: 0.125,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.2,
+          output: 0.75,
+          cacheRead: 0.02,
+          cacheWrite: 0.25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -7500,7 +8000,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    cost: {
+      input: 0.1,
+      output: 0.5,
+      cacheRead: 0.01,
+      cacheWrite: 0.125,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.2,
+          output: 0.75,
+          cacheRead: 0.02,
+          cacheWrite: 0.25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -7587,7 +8101,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 10,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 15,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -7616,7 +8144,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 10,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 15,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -7703,7 +8245,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 10,
+      cacheRead: 0.1,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 15,
+          cacheRead: 0.2,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -7732,65 +8288,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5 },
-    contextWindow: 1050000,
-    maxTokens: 128000,
-    compat: {
-      thinkingFormat: 'openrouter',
-      supportsStrictMode: true,
-      sendSessionAffinityHeaders: true,
-      sessionAffinityFormat: 'openrouter',
-      supportsDeveloperRole: true,
-      supportsTemperature: false,
-    },
-  },
-  {
-    id: 'openai/gpt-6.1-sol-pro:batch',
-    provider: 'openrouter',
-    name: 'OpenAI: GPT-6.1 Sol Pro (batch)',
-    api: 'openai-completions',
-    baseUrl: 'https://openrouter.ai/api/v1',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningMap: {
-      off: null,
-      minimal: null,
-      low: 'low',
-      medium: 'medium',
-      high: 'high',
-      xhigh: 'xhigh',
-      max: 'max',
-    },
-    cost: { input: 1, output: 5, cacheRead: 0.05, cacheWrite: 1.25 },
-    contextWindow: 1050000,
-    maxTokens: 128000,
-    compat: {
-      thinkingFormat: 'openrouter',
-      supportsStrictMode: true,
-      sendSessionAffinityHeaders: true,
-      sessionAffinityFormat: 'openrouter',
-      supportsDeveloperRole: true,
-      supportsTemperature: false,
-    },
-  },
-  {
-    id: 'openai/gpt-6.1-sol:batch',
-    provider: 'openrouter',
-    name: 'OpenAI: GPT-6.1 Sol (batch)',
-    api: 'openai-completions',
-    baseUrl: 'https://openrouter.ai/api/v1',
-    input: ['text', 'image', 'document'],
-    reasoning: true,
-    reasoningMap: {
-      off: null,
-      minimal: null,
-      low: 'low',
-      medium: 'medium',
-      high: 'high',
-      xhigh: 'xhigh',
-      max: 'max',
+    cost: {
+      input: 2,
+      output: 10,
+      cacheRead: 0.1,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 15,
+          cacheRead: 0.2,
+          cacheWrite: 5,
+        },
+      ],
     },
-    cost: { input: 1, output: 5, cacheRead: 0.05, cacheWrite: 1.25 },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -8750,7 +9262,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://openrouter.ai/api/v1',
     input: ['text'],
     reasoning: false,
-    cost: { input: 0.26, output: 0.78, cacheRead: 0.052, cacheWrite: 0.325 },
+    cost: {
+      input: 0.26,
+      output: 0.78,
+      cacheRead: 0.052,
+      cacheWrite: 0.325,
+      tiers: [
+        {
+          inputTokensAbove: 256000,
+          input: 0.78,
+          output: 2.34,
+          cacheRead: 0.156,
+          cacheWrite: 0.975,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 32768,
     compat: {
@@ -8769,7 +9295,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://openrouter.ai/api/v1',
     input: ['text'],
     reasoning: false,
-    cost: { input: 0.26, output: 0.78, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 0.26,
+      output: 0.78,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 256000,
+          input: 0.78,
+          output: 2.34,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 32768,
     compat: {
@@ -9056,6 +9596,22 @@ export const models: ReadonlyArray<ModelRecord> = [
       output: 0.975,
       cacheRead: 0.039,
       cacheWrite: 0.24375,
+      tiers: [
+        {
+          inputTokensAbove: 32000,
+          input: 0.325,
+          output: 1.625,
+          cacheRead: 0.065,
+          cacheWrite: 0.40625,
+        },
+        {
+          inputTokensAbove: 128000,
+          input: 0.52,
+          output: 2.6,
+          cacheRead: 0.104,
+          cacheWrite: 0.65,
+        },
+      ],
     },
     contextWindow: 1000000,
     maxTokens: 65536,
@@ -9094,7 +9650,28 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://openrouter.ai/api/v1',
     input: ['text'],
     reasoning: false,
-    cost: { input: 0.65, output: 3.25, cacheRead: 0.13, cacheWrite: 0.8125 },
+    cost: {
+      input: 0.65,
+      output: 3.25,
+      cacheRead: 0.13,
+      cacheWrite: 0.8125,
+      tiers: [
+        {
+          inputTokensAbove: 32000,
+          input: 1.17,
+          output: 5.85,
+          cacheRead: 0.234,
+          cacheWrite: 1.4625,
+        },
+        {
+          inputTokensAbove: 128000,
+          input: 1.95,
+          output: 9.75,
+          cacheRead: 0.39,
+          cacheWrite: 2.4375,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 65536,
     compat: {
@@ -9113,7 +9690,28 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://openrouter.ai/api/v1',
     input: ['text'],
     reasoning: false,
-    cost: { input: 0.78, output: 3.9, cacheRead: 0.156, cacheWrite: 0.975 },
+    cost: {
+      input: 0.78,
+      output: 3.9,
+      cacheRead: 0.156,
+      cacheWrite: 0.975,
+      tiers: [
+        {
+          inputTokensAbove: 32000,
+          input: 1.56,
+          output: 7.8,
+          cacheRead: 0.312,
+          cacheWrite: 1.95,
+        },
+        {
+          inputTokensAbove: 128000,
+          input: 1.95,
+          output: 9.75,
+          cacheRead: 0.39,
+          cacheWrite: 2.4375,
+        },
+      ],
+    },
     contextWindow: 262144,
     maxTokens: 65536,
     compat: {
@@ -9139,7 +9737,28 @@ export const models: ReadonlyArray<ModelRecord> = [
       medium: null,
       high: 'high',
     },
-    cost: { input: 0.78, output: 3.9, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 0.78,
+      output: 3.9,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 32000,
+          input: 1.56,
+          output: 7.8,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+        {
+          inputTokensAbove: 128000,
+          input: 1.95,
+          output: 9.75,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 262144,
     maxTokens: 65536,
     compat: {
@@ -9492,7 +10111,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       medium: null,
       high: 'high',
     },
-    cost: { input: 0.26, output: 1.56, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 0.26,
+      output: 1.56,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 256000,
+          input: 0.325,
+          output: 1.95,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 65536,
     compat: {
@@ -9518,7 +10151,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       medium: null,
       high: 'high',
     },
-    cost: { input: 0.3, output: 1.8, cacheRead: 0, cacheWrite: 0.375 },
+    cost: {
+      input: 0.3,
+      output: 1.8,
+      cacheRead: 0,
+      cacheWrite: 0.375,
+      tiers: [
+        {
+          inputTokensAbove: 256000,
+          input: 0.375,
+          output: 2.25,
+          cacheRead: 0,
+          cacheWrite: 0.46875,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 65536,
     compat: {
@@ -9596,7 +10243,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       medium: null,
       high: 'high',
     },
-    cost: { input: 0.1875, output: 1.125, cacheRead: 0, cacheWrite: 0.234375 },
+    cost: {
+      input: 0.1875,
+      output: 1.125,
+      cacheRead: 0,
+      cacheWrite: 0.234375,
+      tiers: [
+        {
+          inputTokensAbove: 256000,
+          input: 0.75,
+          output: 3,
+          cacheRead: 0,
+          cacheWrite: 0.9375,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 65536,
     compat: {
@@ -9622,7 +10283,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       medium: null,
       high: 'high',
     },
-    cost: { input: 1.027, output: 6.162, cacheRead: 0, cacheWrite: 1.28375 },
+    cost: {
+      input: 1.027,
+      output: 6.162,
+      cacheRead: 0,
+      cacheWrite: 1.28375,
+      tiers: [
+        {
+          inputTokensAbove: 128000,
+          input: 1.58,
+          output: 9.48,
+          cacheRead: 0,
+          cacheWrite: 1.975,
+        },
+      ],
+    },
     contextWindow: 262144,
     maxTokens: 65536,
     compat: {
@@ -9648,7 +10323,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       medium: null,
       high: 'high',
     },
-    cost: { input: 0.325, output: 1.95, cacheRead: 0, cacheWrite: 0.40625 },
+    cost: {
+      input: 0.325,
+      output: 1.95,
+      cacheRead: 0,
+      cacheWrite: 0.40625,
+      tiers: [
+        {
+          inputTokensAbove: 256000,
+          input: 1.3,
+          output: 3.9,
+          cacheRead: 0,
+          cacheWrite: 1.625,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 65536,
     compat: {
@@ -9675,7 +10364,28 @@ export const models: ReadonlyArray<ModelRecord> = [
       high: 'high',
     },
     reasoningBudget: true,
-    cost: { input: 0.03, output: 0.13, cacheRead: 0.006, cacheWrite: 0.038 },
+    cost: {
+      input: 0.03,
+      output: 0.13,
+      cacheRead: 0.006,
+      cacheWrite: 0.038,
+      tiers: [
+        {
+          inputTokensAbove: 32000,
+          input: 0.1,
+          output: 0.4,
+          cacheRead: 0.02,
+          cacheWrite: 0.125,
+        },
+        {
+          inputTokensAbove: 256000,
+          input: 0.2,
+          output: 0.8,
+          cacheRead: 0.04,
+          cacheWrite: 0.25,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 65536,
     compat: {
@@ -9732,7 +10442,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       medium: null,
       high: 'high',
     },
-    cost: { input: 0.32, output: 1.28, cacheRead: 0.064, cacheWrite: 0.4 },
+    cost: {
+      input: 0.32,
+      output: 1.28,
+      cacheRead: 0.064,
+      cacheWrite: 0.4,
+      tiers: [
+        {
+          inputTokensAbove: 256000,
+          input: 0.96,
+          output: 3.84,
+          cacheRead: 0.192,
+          cacheWrite: 1.2,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 131072,
     compat: {
@@ -10060,7 +10784,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 5,
+      output: 30,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 10,
+          output: 45,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 128000,
     compat: {
@@ -10089,7 +10827,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 5,
+      output: 30,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 10,
+          output: 45,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 128000,
     compat: {
@@ -10617,6 +11369,25 @@ export const models: ReadonlyArray<ModelRecord> = [
       supportsDeveloperRole: false,
     },
   },
+  {
+    id: 'unbiased/pareto-26.10-preview',
+    provider: 'openrouter',
+    name: 'Pareto 26.10 Preview',
+    api: 'openai-completions',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: ['text', 'image'],
+    reasoning: false,
+    cost: { input: 0.8, output: 3.2, cacheRead: 0.03, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 131072,
+    compat: {
+      thinkingFormat: 'openrouter',
+      supportsStrictMode: true,
+      sendSessionAffinityHeaders: true,
+      sessionAffinityFormat: 'openrouter',
+      supportsDeveloperRole: false,
+    },
+  },
   {
     id: 'undi95/remm-slerp-l2-13b',
     provider: 'openrouter',
@@ -10754,7 +11525,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       medium: null,
       high: 'high',
     },
-    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 2.5,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2.5,
+          output: 5,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 2000000,
     maxTokens: 1800000,
     compat: {
@@ -10782,7 +11567,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 2.5,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2.5,
+          output: 5,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 2000000,
     maxTokens: 1800000,
     compat: {
@@ -10810,7 +11609,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 2.5,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2.5,
+          output: 5,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 900000,
     compat: {
@@ -10866,7 +11679,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.3, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.3,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 12,
+          cacheRead: 0.6,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 450000,
     compat: {
@@ -10894,7 +11721,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 12,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 450000,
     compat: {
@@ -10922,7 +11763,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 12,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 450000,
     compat: {
@@ -10941,7 +11796,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://openrouter.ai/api/v1',
     input: ['text', 'image', 'document'],
     reasoning: true,
-    cost: { input: 1, output: 2, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1,
+      output: 2,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2,
+          output: 4,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 256000,
     maxTokens: 230400,
     compat: {
diff --git a/packages/ai-models/src/providers/qwen-token-plan-cn.ts b/packages/ai-models/src/providers/qwen-token-plan-cn.ts
index 26b9ca002e..6ff626efb0 100644
--- a/packages/ai-models/src/providers/qwen-token-plan-cn.ts
+++ b/packages/ai-models/src/providers/qwen-token-plan-cn.ts
@@ -211,7 +211,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       high: 'high',
     },
     reasoningBudget: true,
-    cost: { input: 0.573, output: 2.58, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 0.573,
+      output: 2.58,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 32000,
+          input: 0.86,
+          output: 3.154,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 202752,
     maxTokens: 16384,
     compat: {
@@ -240,7 +254,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       high: 'high',
     },
     reasoningBudget: true,
-    cost: { input: 0.825, output: 3.301, cacheRead: 0.17, cacheWrite: 0 },
+    cost: {
+      input: 0.825,
+      output: 3.301,
+      cacheRead: 0.17,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 32000,
+          input: 1.1,
+          output: 3.851,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 202752,
     maxTokens: 128000,
     compat: {
@@ -450,7 +478,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       high: 'high',
     },
     reasoningBudget: true,
-    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0.625 },
+    cost: {
+      input: 0.5,
+      output: 3,
+      cacheRead: 0.05,
+      cacheWrite: 0.625,
+      tiers: [
+        {
+          inputTokensAbove: 256000,
+          input: 2,
+          output: 6,
+          cacheRead: 0.2,
+          cacheWrite: 2.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 65536,
     compat: {
@@ -506,7 +548,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       high: 'high',
     },
     reasoningBudget: true,
-    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0.625 },
+    cost: {
+      input: 0.5,
+      output: 3,
+      cacheRead: 0.05,
+      cacheWrite: 0.625,
+      tiers: [
+        {
+          inputTokensAbove: 128000,
+          input: 2,
+          output: 6,
+          cacheRead: 0.2,
+          cacheWrite: 2.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 64000,
     compat: {
diff --git a/packages/ai-models/src/providers/qwen-token-plan-individual.ts b/packages/ai-models/src/providers/qwen-token-plan-individual.ts
index 0a2be8dcb4..eb71a2b917 100644
--- a/packages/ai-models/src/providers/qwen-token-plan-individual.ts
+++ b/packages/ai-models/src/providers/qwen-token-plan-individual.ts
@@ -207,7 +207,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       high: 'high',
     },
     reasoningBudget: true,
-    cost: { input: 0.4, output: 1.6, cacheRead: 0.04, cacheWrite: 0.5 },
+    cost: {
+      input: 0.4,
+      output: 1.6,
+      cacheRead: 0.04,
+      cacheWrite: 0.5,
+      tiers: [
+        {
+          inputTokensAbove: 256000,
+          input: 1.2,
+          output: 4.8,
+          cacheRead: 0.12,
+          cacheWrite: 1.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 131072,
     compat: {
diff --git a/packages/ai-models/src/providers/qwen-token-plan.ts b/packages/ai-models/src/providers/qwen-token-plan.ts
index a478fbbdc0..418a74f7de 100644
--- a/packages/ai-models/src/providers/qwen-token-plan.ts
+++ b/packages/ai-models/src/providers/qwen-token-plan.ts
@@ -460,7 +460,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       high: 'high',
     },
     reasoningBudget: true,
-    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0.625 },
+    cost: {
+      input: 0.5,
+      output: 3,
+      cacheRead: 0.05,
+      cacheWrite: 0.625,
+      tiers: [
+        {
+          inputTokensAbove: 256000,
+          input: 2,
+          output: 6,
+          cacheRead: 0.2,
+          cacheWrite: 2.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 65536,
     compat: {
@@ -516,7 +530,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       high: 'high',
     },
     reasoningBudget: true,
-    cost: { input: 0.4, output: 1.6, cacheRead: 0.04, cacheWrite: 0.5 },
+    cost: {
+      input: 0.4,
+      output: 1.6,
+      cacheRead: 0.04,
+      cacheWrite: 0.5,
+      tiers: [
+        {
+          inputTokensAbove: 256000,
+          input: 1.2,
+          output: 4.8,
+          cacheRead: 0.12,
+          cacheWrite: 1.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 131072,
     compat: {
diff --git a/packages/ai-models/src/providers/vercel-ai-gateway.ts b/packages/ai-models/src/providers/vercel-ai-gateway.ts
index bd294db333..59ee404e5c 100644
--- a/packages/ai-models/src/providers/vercel-ai-gateway.ts
+++ b/packages/ai-models/src/providers/vercel-ai-gateway.ts
@@ -111,7 +111,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       high: 'high',
     },
     reasoningBudget: true,
-    cost: { input: 1.3, output: 7.8, cacheRead: 0.13, cacheWrite: 1.625 },
+    cost: {
+      input: 1.3,
+      output: 7.8,
+      cacheRead: 0.13,
+      cacheWrite: 1.625,
+      tiers: [
+        {
+          inputTokensAbove: 128000,
+          input: 2,
+          output: 12,
+          cacheRead: 0.2,
+          cacheWrite: 2.5,
+        },
+      ],
+    },
     contextWindow: 240000,
     maxTokens: 64000,
     compat: { allowEmptySignature: true },
@@ -138,7 +152,28 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://ai-gateway.vercel.sh',
     input: ['text'],
     reasoning: true,
-    cost: { input: 1.5, output: 7.5, cacheRead: 0.3, cacheWrite: 0 },
+    cost: {
+      input: 1.5,
+      output: 7.5,
+      cacheRead: 0.3,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 32001,
+          input: 2.7,
+          output: 13.5,
+          cacheRead: 0.54,
+          cacheWrite: 0,
+        },
+        {
+          inputTokensAbove: 128001,
+          input: 4.5,
+          output: 22.5,
+          cacheRead: 0.9,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 262144,
     maxTokens: 65536,
     compat: { allowEmptySignature: true },
@@ -177,7 +212,35 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://ai-gateway.vercel.sh',
     input: ['text'],
     reasoning: false,
-    cost: { input: 1, output: 5, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1,
+      output: 5,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 32001,
+          input: 1.8,
+          output: 9,
+          cacheRead: 0.36,
+          cacheWrite: 0,
+        },
+        {
+          inputTokensAbove: 128001,
+          input: 3,
+          output: 15,
+          cacheRead: 0.6,
+          cacheWrite: 0,
+        },
+        {
+          inputTokensAbove: 256001,
+          input: 6,
+          output: 60,
+          cacheRead: 1.2,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 65536,
     compat: { allowEmptySignature: true },
@@ -229,7 +292,28 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://ai-gateway.vercel.sh',
     input: ['text'],
     reasoning: false,
-    cost: { input: 1.2, output: 6, cacheRead: 0.24, cacheWrite: 0 },
+    cost: {
+      input: 1.2,
+      output: 6,
+      cacheRead: 0.24,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 32001,
+          input: 2.4,
+          output: 12,
+          cacheRead: 0.48,
+          cacheWrite: 0,
+        },
+        {
+          inputTokensAbove: 128001,
+          input: 3,
+          output: 15,
+          cacheRead: 0.6,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 262144,
     maxTokens: 32768,
     compat: { allowEmptySignature: true },
@@ -242,7 +326,28 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://ai-gateway.vercel.sh',
     input: ['text'],
     reasoning: false,
-    cost: { input: 1.2, output: 6, cacheRead: 0.24, cacheWrite: 0 },
+    cost: {
+      input: 1.2,
+      output: 6,
+      cacheRead: 0.24,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 32001,
+          input: 2.4,
+          output: 12,
+          cacheRead: 0.48,
+          cacheWrite: 0,
+        },
+        {
+          inputTokensAbove: 128001,
+          input: 3,
+          output: 15,
+          cacheRead: 0.6,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 262144,
     maxTokens: 32768,
     compat: { allowEmptySignature: true },
@@ -256,7 +361,28 @@ export const models: ReadonlyArray<ModelRecord> = [
     input: ['text'],
     reasoning: true,
     reasoningBudget: true,
-    cost: { input: 1.2, output: 6, cacheRead: 0.24, cacheWrite: 0 },
+    cost: {
+      input: 1.2,
+      output: 6,
+      cacheRead: 0.24,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 32001,
+          input: 2.4,
+          output: 12,
+          cacheRead: 0.48,
+          cacheWrite: 0,
+        },
+        {
+          inputTokensAbove: 128001,
+          input: 3,
+          output: 15,
+          cacheRead: 0.6,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 256000,
     maxTokens: 65536,
     compat: { allowEmptySignature: true },
@@ -369,7 +495,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       max: 'max',
     },
     reasoningBudget: true,
-    cost: { input: 0.4, output: 2.4, cacheRead: 0.04, cacheWrite: 0.5 },
+    cost: {
+      input: 0.4,
+      output: 2.4,
+      cacheRead: 0.04,
+      cacheWrite: 0.5,
+      tiers: [
+        {
+          inputTokensAbove: 256001,
+          input: 0.5,
+          output: 3,
+          cacheRead: 0.05,
+          cacheWrite: 0.625,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 64000,
     compat: { allowEmptySignature: true },
@@ -413,7 +553,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       max: 'max',
     },
     reasoningBudget: true,
-    cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0.625 },
+    cost: {
+      input: 0.5,
+      output: 3,
+      cacheRead: 0.05,
+      cacheWrite: 0.625,
+      tiers: [
+        {
+          inputTokensAbove: 256000,
+          input: 2,
+          output: 6,
+          cacheRead: 0.2,
+          cacheWrite: 2.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 64000,
     compat: { allowEmptySignature: true },
@@ -436,7 +590,28 @@ export const models: ReadonlyArray<ModelRecord> = [
       max: 'max',
     },
     reasoningBudget: true,
-    cost: { input: 0.03, output: 0.13, cacheRead: 0.006, cacheWrite: 0.038 },
+    cost: {
+      input: 0.03,
+      output: 0.13,
+      cacheRead: 0.006,
+      cacheWrite: 0.038,
+      tiers: [
+        {
+          inputTokensAbove: 32000,
+          input: 0.1,
+          output: 0.4,
+          cacheRead: 0.02,
+          cacheWrite: 0.125,
+        },
+        {
+          inputTokensAbove: 256000,
+          input: 0.2,
+          output: 0.8,
+          cacheRead: 0.04,
+          cacheWrite: 0.25,
+        },
+      ],
+    },
     contextWindow: 991000,
     maxTokens: 64000,
     compat: { allowEmptySignature: true },
@@ -482,7 +657,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       max: 'max',
     },
     reasoningBudget: true,
-    cost: { input: 0.4, output: 1.6, cacheRead: 0.08, cacheWrite: 0.5 },
+    cost: {
+      input: 0.4,
+      output: 1.6,
+      cacheRead: 0.08,
+      cacheWrite: 0.5,
+      tiers: [
+        {
+          inputTokensAbove: 256000,
+          input: 1.2,
+          output: 4.8,
+          cacheRead: 0.24,
+          cacheWrite: 1.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 64000,
     compat: { allowEmptySignature: true },
@@ -1049,7 +1238,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       high: 'high',
     },
     reasoningBudget: true,
-    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    cost: {
+      input: 3,
+      output: 15,
+      cacheRead: 0.3,
+      cacheWrite: 3.75,
+      tiers: [
+        {
+          inputTokensAbove: 200001,
+          input: 6,
+          output: 22.5,
+          cacheRead: 0.6,
+          cacheWrite: 7.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 64000,
     compat: { allowEmptySignature: true },
@@ -1086,7 +1289,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       max: 'max',
     },
     reasoningBudget: true,
-    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    cost: {
+      input: 3,
+      output: 15,
+      cacheRead: 0.3,
+      cacheWrite: 3.75,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 6,
+          output: 22.5,
+          cacheRead: 0.6,
+          cacheWrite: 7.5,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 128000,
     compat: { allowEmptySignature: true },
@@ -1177,7 +1394,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       medium: null,
       high: 'high',
     },
-    cost: { input: 0.25, output: 2, cacheRead: 0.05, cacheWrite: 0 },
+    cost: {
+      input: 0.25,
+      output: 2,
+      cacheRead: 0.05,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 128001,
+          input: 0.5,
+          output: 4,
+          cacheRead: 0.05,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 256000,
     maxTokens: 32000,
     compat: { allowEmptySignature: true },
@@ -1199,7 +1430,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 0.25, output: 2, cacheRead: 0.05, cacheWrite: 0 },
+    cost: {
+      input: 0.25,
+      output: 2,
+      cacheRead: 0.05,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 128001,
+          input: 0.5,
+          output: 4,
+          cacheRead: 0.05,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 256000,
     maxTokens: 32768,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -1291,6 +1536,32 @@ export const models: ReadonlyArray<ModelRecord> = [
     maxTokens: 32000,
     compat: { allowEmptySignature: true },
   },
+  {
+    id: 'convaiinnovations/laya',
+    provider: 'vercel-ai-gateway',
+    name: 'Laya',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'convaiinnovations/laya-free',
+    provider: 'vercel-ai-gateway',
+    name: 'Laya (Free)',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 8192,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
   {
     id: 'deepseek/deepseek-r1',
     provider: 'vercel-ai-gateway',
@@ -1515,6 +1786,28 @@ export const models: ReadonlyArray<ModelRecord> = [
     maxTokens: 32768,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
   },
+  {
+    id: 'deepseek/deepseek-v4.1-flash-fast',
+    provider: 'vercel-ai-gateway',
+    name: 'DeepSeek V4.1 Flash Fast',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text', 'image'],
+    reasoning: true,
+    reasoningMap: {
+      off: 'none',
+      minimal: null,
+      low: 'low',
+      medium: 'medium',
+      high: 'high',
+      xhigh: null,
+      max: null,
+    },
+    cost: { input: 0.3, output: 1.2, cacheRead: 0.006, cacheWrite: 0 },
+    contextWindow: 1048576,
+    maxTokens: 1000000,
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+  },
   {
     id: 'fireworks/ember-1',
     provider: 'vercel-ai-gateway',
@@ -1617,7 +1910,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     input: ['text', 'image', 'audio', 'video', 'document'],
     reasoning: true,
     reasoningBudget: true,
-    cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 10,
+      cacheRead: 0.125,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2.5,
+          output: 15,
+          cacheRead: 0.25,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1048576,
     maxTokens: 65536,
     compat: { allowEmptySignature: true },
@@ -1762,7 +2069,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200001,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 64000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -2563,6 +2884,45 @@ export const models: ReadonlyArray<ModelRecord> = [
     maxTokens: 1048576,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
   },
+  {
+    id: 'microsoft/mai-transcribe-1.5',
+    provider: 'vercel-ai-gateway',
+    name: 'MAI-Transcribe-1.5',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['audio'],
+    reasoning: false,
+    cost: { input: 0.0001, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'microsoft/mai-transcribe-2',
+    provider: 'vercel-ai-gateway',
+    name: 'MAI-Transcribe 2',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['audio'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'microsoft/mai-transcribe-2-streaming',
+    provider: 'vercel-ai-gateway',
+    name: 'MAI-Transcribe-2-Streaming',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['audio'],
+    reasoning: false,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 0,
+    maxTokens: 0,
+    compat: { allowEmptySignature: true },
+  },
   {
     id: 'minimax/minimax-m2',
     provider: 'vercel-ai-gateway',
@@ -3768,7 +4128,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
+    cost: {
+      input: 2.5,
+      output: 15,
+      cacheRead: 0.25,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 5,
+          output: 22.5,
+          cacheRead: 0.5,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -3878,7 +4252,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 30,
+      output: 180,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 60,
+          output: 270,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -3900,7 +4288,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 5,
+      output: 30,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 10,
+          output: 45,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 128000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -3948,7 +4350,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
+    cost: {
+      input: 30,
+      output: 180,
+      cacheRead: 0,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 60,
+          output: 270,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 128000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -3970,7 +4386,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.2, output: 1.2, cacheRead: 0.02, cacheWrite: 0.25 },
+    cost: {
+      input: 0.2,
+      output: 1.2,
+      cacheRead: 0.02,
+      cacheWrite: 0.25,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.4,
+          output: 1.8,
+          cacheRead: 0.04,
+          cacheWrite: 0.5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -3992,7 +4422,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.4, output: 2.4, cacheRead: 0.04, cacheWrite: 0.5 },
+    cost: {
+      input: 0.4,
+      output: 2.4,
+      cacheRead: 0.04,
+      cacheWrite: 0.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 0.8,
+          output: 3.6,
+          cacheRead: 0.08,
+          cacheWrite: 1,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -4018,7 +4462,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
+    cost: {
+      input: 4,
+      output: 20,
+      cacheRead: 0.4,
+      cacheWrite: 5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 8,
+          output: 30,
+          cacheRead: 0.8,
+          cacheWrite: 10,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -4040,7 +4498,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 8, output: 40, cacheRead: 0.8, cacheWrite: 10 },
+    cost: {
+      input: 8,
+      output: 40,
+      cacheRead: 0.8,
+      cacheWrite: 10,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 16,
+          output: 60,
+          cacheRead: 1.6,
+          cacheWrite: 20,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -4066,7 +4538,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 12, cacheRead: 0.2, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 12,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 4,
+          output: 18,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -4088,7 +4574,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 4, output: 24, cacheRead: 0.4, cacheWrite: 5 },
+    cost: {
+      input: 4,
+      output: 24,
+      cacheRead: 0.4,
+      cacheWrite: 5,
+      tiers: [
+        {
+          inputTokensAbove: 272000,
+          input: 8,
+          output: 36,
+          cacheRead: 0.8,
+          cacheWrite: 10,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -4114,7 +4614,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
+    cost: {
+      input: 10,
+      output: 50,
+      cacheRead: 1,
+      cacheWrite: 12.5,
+      tiers: [
+        {
+          inputTokensAbove: 272001,
+          input: 20,
+          output: 75,
+          cacheRead: 2,
+          cacheWrite: 25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -4140,7 +4654,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 20, output: 100, cacheRead: 2, cacheWrite: 25 },
+    cost: {
+      input: 20,
+      output: 100,
+      cacheRead: 2,
+      cacheWrite: 25,
+      tiers: [
+        {
+          inputTokensAbove: 272001,
+          input: 40,
+          output: 150,
+          cacheRead: 4,
+          cacheWrite: 50,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -4166,7 +4694,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 },
+    cost: {
+      input: 0.1,
+      output: 0.5,
+      cacheRead: 0.01,
+      cacheWrite: 0.125,
+      tiers: [
+        {
+          inputTokensAbove: 272001,
+          input: 0.2,
+          output: 0.75,
+          cacheRead: 0.02,
+          cacheWrite: 0.25,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -4192,7 +4734,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 0.2, output: 1, cacheRead: 0.02, cacheWrite: 0.25 },
+    cost: {
+      input: 0.2,
+      output: 1,
+      cacheRead: 0.02,
+      cacheWrite: 0.25,
+      tiers: [
+        {
+          inputTokensAbove: 272001,
+          input: 0.4,
+          output: 1.5,
+          cacheRead: 0.04,
+          cacheWrite: 0.5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -4218,7 +4774,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 10,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272001,
+          input: 4,
+          output: 15,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -4244,7 +4814,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
+    cost: {
+      input: 4,
+      output: 20,
+      cacheRead: 0.4,
+      cacheWrite: 5,
+      tiers: [
+        {
+          inputTokensAbove: 272001,
+          input: 8,
+          output: 30,
+          cacheRead: 0.8,
+          cacheWrite: 10,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -4270,7 +4854,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5 },
+    cost: {
+      input: 2,
+      output: 10,
+      cacheRead: 0.1,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 272001,
+          input: 4,
+          output: 15,
+          cacheRead: 0.2,
+          cacheWrite: 5,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -4296,7 +4894,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: 'max',
     },
-    cost: { input: 4, output: 20, cacheRead: 0.2, cacheWrite: 5 },
+    cost: {
+      input: 4,
+      output: 20,
+      cacheRead: 0.2,
+      cacheWrite: 5,
+      tiers: [
+        {
+          inputTokensAbove: 272001,
+          input: 8,
+          output: 30,
+          cacheRead: 0.4,
+          cacheWrite: 10,
+        },
+      ],
+    },
     contextWindow: 1050000,
     maxTokens: 128000,
     compat: {
@@ -4872,7 +5484,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 5,
+      output: 30,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272001,
+          input: 10,
+          output: 45,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 1000000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -4894,7 +5520,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 5,
+      output: 30,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 272001,
+          input: 10,
+          output: 45,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 1000000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -4973,7 +5613,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 2.5,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200001,
+          input: 2.5,
+          output: 5,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 2000000,
     maxTokens: 2000000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -4995,7 +5649,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 2.5,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200001,
+          input: 2.5,
+          output: 5,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 2000000,
     maxTokens: 2000000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -5008,7 +5676,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://ai-gateway.vercel.sh',
     input: ['text', 'image', 'document'],
     reasoning: false,
-    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 2.5,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200001,
+          input: 2.5,
+          output: 5,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 2000000,
     maxTokens: 2000000,
     compat: { allowEmptySignature: true },
@@ -5021,7 +5703,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://ai-gateway.vercel.sh',
     input: ['text', 'image', 'document'],
     reasoning: false,
-    cost: { input: 1.25, output: 2.5, cacheRead: 0.4, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 2.5,
+      cacheRead: 0.4,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200001,
+          input: 2.5,
+          output: 5,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 2000000,
     maxTokens: 2000000,
     compat: { allowEmptySignature: true },
@@ -5043,7 +5739,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 2.5,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200001,
+          input: 2.5,
+          output: 5,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 2000000,
     maxTokens: 2000000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -5065,7 +5775,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 2.5,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200001,
+          input: 2.5,
+          output: 5,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 2000000,
     maxTokens: 2000000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -5087,7 +5811,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 2.5,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200001,
+          input: 2.5,
+          output: 5,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 1000000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -5109,7 +5847,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.3, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.3,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200001,
+          input: 4,
+          output: 12,
+          cacheRead: 0.6,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 500000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -5131,7 +5883,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200001,
+          input: 4,
+          output: 12,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 500000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -5153,7 +5919,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200001,
+          input: 4,
+          output: 12,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 500000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -5175,7 +5955,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 1, output: 2, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1,
+      output: 2,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200001,
+          input: 2,
+          output: 4,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 256000,
     maxTokens: 256000,
     compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
@@ -5464,6 +6258,32 @@ export const models: ReadonlyArray<ModelRecord> = [
     maxTokens: 32000,
     compat: { allowEmptySignature: true },
   },
+  {
+    id: 'voyage/rerank-3',
+    provider: 'vercel-ai-gateway',
+    name: 'Voyage Rerank 3',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.05, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 32000,
+    compat: { allowEmptySignature: true },
+  },
+  {
+    id: 'voyage/rerank-3-lite',
+    provider: 'vercel-ai-gateway',
+    name: 'Voyage Rerank 3 Lite',
+    api: 'anthropic-messages',
+    baseUrl: 'https://ai-gateway.vercel.sh',
+    input: ['text'],
+    reasoning: false,
+    cost: { input: 0.02, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 32000,
+    maxTokens: 32000,
+    compat: { allowEmptySignature: true },
+  },
   {
     id: 'voyage/voyage-3-large',
     provider: 'vercel-ai-gateway',
diff --git a/packages/ai-models/src/providers/xai.ts b/packages/ai-models/src/providers/xai.ts
index 4f46780d50..8e92c97cea 100644
--- a/packages/ai-models/src/providers/xai.ts
+++ b/packages/ai-models/src/providers/xai.ts
@@ -20,7 +20,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://api.x.ai/v1',
     input: ['text', 'image', 'document'],
     reasoning: false,
-    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 2.5,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2.5,
+          output: 5,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 30000,
     compat: { supportsLongCacheRetention: false },
@@ -33,7 +47,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://api.x.ai/v1',
     input: ['text', 'image', 'document'],
     reasoning: true,
-    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 2.5,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2.5,
+          output: 5,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 30000,
     compat: { supportsLongCacheRetention: false },
@@ -55,7 +83,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 2.5,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2.5,
+          output: 5,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 30000,
     compat: { supportsLongCacheRetention: false },
@@ -77,7 +119,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1.25,
+      output: 2.5,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2.5,
+          output: 5,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 1000000,
     maxTokens: 30000,
     compat: { supportsLongCacheRetention: false },
@@ -99,7 +155,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: null,
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.3, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.3,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 12,
+          cacheRead: 0.6,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 500000,
     compat: { supportsLongCacheRetention: false },
@@ -121,7 +191,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 12,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 500000,
     compat: { supportsLongCacheRetention: false },
@@ -143,7 +227,21 @@ export const models: ReadonlyArray<ModelRecord> = [
       xhigh: 'xhigh',
       max: null,
     },
-    cost: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    cost: {
+      input: 2,
+      output: 6,
+      cacheRead: 0.5,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 4,
+          output: 12,
+          cacheRead: 1,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 500000,
     maxTokens: 500000,
     compat: { supportsLongCacheRetention: false },
@@ -156,7 +254,21 @@ export const models: ReadonlyArray<ModelRecord> = [
     baseUrl: 'https://api.x.ai/v1',
     input: ['text', 'image', 'document'],
     reasoning: true,
-    cost: { input: 1, output: 2, cacheRead: 0.2, cacheWrite: 0 },
+    cost: {
+      input: 1,
+      output: 2,
+      cacheRead: 0.2,
+      cacheWrite: 0,
+      tiers: [
+        {
+          inputTokensAbove: 200000,
+          input: 2,
+          output: 4,
+          cacheRead: 0.4,
+          cacheWrite: 0,
+        },
+      ],
+    },
     contextWindow: 256000,
     maxTokens: 256000,
     compat: { supportsLongCacheRetention: false },
diff --git a/packages/ai-models/src/types.ts b/packages/ai-models/src/types.ts
index 33479944bd..2b7440fb45 100644
--- a/packages/ai-models/src/types.ts
+++ b/packages/ai-models/src/types.ts
@@ -98,6 +98,21 @@ export interface ModelCostRates {
   output: number
   cacheRead: number
   cacheWrite: number
+  /**
+   * Higher prices for a call with more input, for example long context. A
+   * call uses the tier with the highest `inputTokensAbove` below its input
+   * (uncached + cache read + cache write). Same rule as pi.
+   */
+  tiers?: ReadonlyArray<ModelCostTier>
+}
+
+/** The prices of a call with more than `inputTokensAbove` input tokens. */
+export interface ModelCostTier {
+  inputTokensAbove: number
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
 }
 
 /** One model of one provider. */
@@ -143,12 +158,17 @@ export interface ProviderRecord {
   env: ReadonlyArray<ReadonlyArray<string>>
 }
 
-/** Token counts of one call. */
+/** Token counts of one call. `input` is the uncached input only. */
 export interface TokenCounts {
   input: number
   output: number
   cacheRead?: number
   cacheWrite?: number
+  /**
+   * The part of `cacheWrite` written with a 1-hour retention
+   * (`promptCache: 'long'` on Anthropic). It costs 2x the input price.
+   */
+  cacheWrite1h?: number
 }
 
 /** What a call cost, in USD. */
diff --git a/packages/ai-models/tests/catalog.test.ts b/packages/ai-models/tests/catalog.test.ts
index 632907e911..70a26c1744 100644
--- a/packages/ai-models/tests/catalog.test.ts
+++ b/packages/ai-models/tests/catalog.test.ts
@@ -15,7 +15,7 @@ import {
   supportedReasoningLevels,
 } from '../src'
 import * as deepseek from '../src/providers/deepseek'
-import type { ModelRecord, ReasoningLevel, ReasoningMap } from '../src'
+import type { Cost, ModelRecord, ReasoningLevel, ReasoningMap } from '../src'
 
 describe('the catalog', () => {
   it('has one module per provider, and the root lists them all', () => {
@@ -75,6 +75,94 @@ describe('the catalog', () => {
 })
 
 describe('modelCost', () => {
+  // Long-context prices above 200k and 1M input tokens, like a tiered record.
+  const tiered = {
+    cost: {
+      input: 2,
+      output: 10,
+      cacheRead: 0.2,
+      cacheWrite: 2.5,
+      tiers: [
+        {
+          inputTokensAbove: 1_000_000,
+          input: 6,
+          output: 30,
+          cacheRead: 0.6,
+          cacheWrite: 7.5,
+        },
+        {
+          inputTokensAbove: 200_000,
+          input: 4,
+          output: 20,
+          cacheRead: 0.4,
+          cacheWrite: 5,
+        },
+      ],
+    },
+  }
+
+  /** Each part of `cost` is close to `expected` (USD floats). */
+  const expectCost = (cost: Cost, expected: Cost) => {
+    for (const key of Object.keys(expected) as Array<keyof Cost>)
+      expect(cost[key]).toBeCloseTo(expected[key], 10)
+  }
+
+  it('uses the base prices at or below the lowest tier', () => {
+    expectCost(modelCost(tiered, { input: 200_000, output: 1_000_000 }), {
+      input: 0.4,
+      output: 10,
+      cacheRead: 0,
+      cacheWrite: 0,
+      total: 10.4,
+    })
+  })
+
+  it('uses the highest tier below the input, with the cache parts counted', () => {
+    // 150k uncached + 60k cache read = 210k input: the 200k tier.
+    expectCost(
+      modelCost(tiered, { input: 150_000, output: 0, cacheRead: 60_000 }),
+      { input: 0.6, output: 0, cacheRead: 0.024, cacheWrite: 0, total: 0.624 },
+    )
+    expect(
+      modelCost(tiered, { input: 1_500_000, output: 0 }).input,
+    ).toBeCloseTo(9, 10)
+  })
+
+  it('prices a 1-hour cache write at 2x the input price', () => {
+    const base = {
+      cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    }
+    // 100k written: 40k with a 1-hour TTL, 60k with the 5-minute price.
+    expectCost(
+      modelCost(base, {
+        input: 0,
+        output: 0,
+        cacheWrite: 100_000,
+        cacheWrite1h: 40_000,
+      }),
+      { input: 0, output: 0, cacheRead: 0, cacheWrite: 0.465, total: 0.465 },
+    )
+  })
+
+  it('takes the 1-hour price from the tier', () => {
+    // 300k written in all, so the 200k tier: 2 x 4 for the 1-hour part.
+    expect(
+      modelCost(tiered, {
+        input: 0,
+        output: 0,
+        cacheWrite: 300_000,
+        cacheWrite1h: 300_000,
+      }).cacheWrite,
+    ).toBeCloseTo(2.4, 10)
+  })
+
+  it('has the models.dev tiers on catalog records', () => {
+    const record = getModel('openai', 'gpt-5.5')
+    expect(record?.cost.tiers).toEqual([
+      expect.objectContaining({ inputTokensAbove: 272000 }),
+    ])
+  })
+
   it('prices each part per 1M tokens', () => {
     const cost = modelCost(
       { cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 } },
diff --git a/scripts/fetch-models-dev.ts b/scripts/fetch-models-dev.ts
index 1fe77a9e04..042a5bb45b 100644
--- a/scripts/fetch-models-dev.ts
+++ b/scripts/fetch-models-dev.ts
@@ -36,6 +36,14 @@ interface ApiModel {
     output?: number
     cache_read?: number
     cache_write?: number
+    /** Higher prices above an input size, for example long context. */
+    tiers?: Array<{
+      input?: number
+      output?: number
+      cache_read?: number
+      cache_write?: number
+      tier?: { type?: string; size?: number }
+    }>
   }
   limit?: { context?: number; output?: number }
   provider?: { npm?: string; api?: string }
@@ -65,6 +73,13 @@ const trimModel = (model: ApiModel) => ({
     output: model.cost.output,
     cache_read: model.cost.cache_read,
     cache_write: model.cost.cache_write,
+    tiers: model.cost.tiers?.map((tier) => ({
+      input: tier.input,
+      output: tier.output,
+      cache_read: tier.cache_read,
+      cache_write: tier.cache_write,
+      tier: tier.tier && { type: tier.tier.type, size: tier.tier.size },
+    })),
   },
   limit: model.limit && {
     context: model.limit.context,
diff --git a/scripts/models-dev.models.json b/scripts/models-dev.models.json
index 5ffe45aa3f..e00c03444d 100644
--- a/scripts/models-dev.models.json
+++ b/scripts/models-dev.models.json
@@ -497,7 +497,29 @@
           "input": 0.03,
           "output": 0.13,
           "cache_read": 0.003,
-          "cache_write": 0.0375
+          "cache_write": 0.0375,
+          "tiers": [
+            {
+              "input": 0.1,
+              "output": 0.4,
+              "cache_read": 0.01,
+              "cache_write": 0.125,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 0.2,
+              "output": 0.8,
+              "cache_read": 0.02,
+              "cache_write": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -552,7 +574,25 @@
         },
         "cost": {
           "input": 1.5,
-          "output": 7.5
+          "output": 7.5,
+          "tiers": [
+            {
+              "input": 2.7,
+              "output": 13.5,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 4.5,
+              "output": 22.5,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -596,7 +636,25 @@
         },
         "cost": {
           "input": 0.45,
-          "output": 2.25
+          "output": 2.25,
+          "tiers": [
+            {
+              "input": 0.75,
+              "output": 3.75,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 1.2,
+              "output": 6,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -1303,7 +1361,19 @@
           "input": 0.5,
           "output": 3,
           "cache_read": 0.05,
-          "cache_write": 0.625
+          "cache_write": 0.625,
+          "tiers": [
+            {
+              "input": 2,
+              "output": 6,
+              "cache_read": 0.2,
+              "cache_write": 2.5,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -1360,7 +1430,19 @@
           "input": 0.4,
           "output": 1.6,
           "cache_read": 0.04,
-          "cache_write": 0.5
+          "cache_write": 0.5,
+          "tiers": [
+            {
+              "input": 1.2,
+              "output": 4.8,
+              "cache_read": 0.12,
+              "cache_write": 1.5,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -1444,7 +1526,25 @@
         },
         "cost": {
           "input": 0.029,
-          "output": 0.287
+          "output": 0.287,
+          "tiers": [
+            {
+              "input": 0.115,
+              "output": 1.147,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            },
+            {
+              "input": 0.172,
+              "output": 1.72,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -1858,7 +1958,25 @@
         },
         "cost": {
           "input": 0.115,
-          "output": 0.688
+          "output": 0.688,
+          "tiers": [
+            {
+              "input": 0.287,
+              "output": 1.72,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            },
+            {
+              "input": 0.573,
+              "output": 3.44,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -1906,7 +2024,17 @@
         },
         "cost": {
           "input": 0.573,
-          "output": 2.58
+          "output": 2.58,
+          "tiers": [
+            {
+              "input": 0.86,
+              "output": 3.154,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 202752,
@@ -2060,7 +2188,29 @@
           "input": 0.02962,
           "output": 0.1185,
           "cache_read": 0.002962,
-          "cache_write": 0.03703
+          "cache_write": 0.03703,
+          "tiers": [
+            {
+              "input": 0.08887,
+              "output": 0.35549,
+              "cache_read": 0.008887,
+              "cache_write": 0.11109,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 0.17774,
+              "output": 0.71098,
+              "cache_read": 0.017774,
+              "cache_write": 0.22218,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -2121,7 +2271,25 @@
         },
         "cost": {
           "input": 0.359,
-          "output": 1.434
+          "output": 1.434,
+          "tiers": [
+            {
+              "input": 0.574,
+              "output": 2.294,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 1.004,
+              "output": 4.014,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -2194,7 +2362,25 @@
         },
         "cost": {
           "input": 0.861,
-          "output": 3.441
+          "output": 3.441,
+          "tiers": [
+            {
+              "input": 1.291,
+              "output": 5.161,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 2.151,
+              "output": 8.602,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -2276,7 +2462,25 @@
         },
         "cost": {
           "input": 0.216,
-          "output": 0.861
+          "output": 0.861,
+          "tiers": [
+            {
+              "input": 0.323,
+              "output": 1.291,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 0.538,
+              "output": 2.151,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -2695,7 +2899,33 @@
         },
         "cost": {
           "input": 0.574,
-          "output": 2.296
+          "output": 2.296,
+          "tiers": [
+            {
+              "input": 0.861,
+              "output": 3.444,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 1.435,
+              "output": 5.74,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            },
+            {
+              "input": 2.87,
+              "output": 28.7,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -2916,7 +3146,17 @@
         },
         "cost": {
           "input": 0.172,
-          "output": 1.032
+          "output": 1.032,
+          "tiers": [
+            {
+              "input": 0.43,
+              "output": 2.58,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -3017,7 +3257,17 @@
         "cost": {
           "input": 0.825,
           "output": 3.301,
-          "cache_read": 0.17
+          "cache_read": 0.17,
+          "tiers": [
+            {
+              "input": 1.1,
+              "output": 3.851,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 202752,
@@ -3171,7 +3421,19 @@
           "input": 0.5,
           "output": 3,
           "cache_read": 0.05,
-          "cache_write": 0.625
+          "cache_write": 0.625,
+          "tiers": [
+            {
+              "input": 2,
+              "output": 6,
+              "cache_read": 0.2,
+              "cache_write": 2.5,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -3257,7 +3519,19 @@
           "input": 0.5,
           "output": 3,
           "cache_read": 0.05,
-          "cache_write": 0.625
+          "cache_write": 0.625,
+          "tiers": [
+            {
+              "input": 2,
+              "output": 6,
+              "cache_read": 0.2,
+              "cache_write": 2.5,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -3670,7 +3944,19 @@
           "input": 10,
           "output": 50,
           "cache_read": 1,
-          "cache_write": 12.5
+          "cache_write": 12.5,
+          "tiers": [
+            {
+              "input": 20,
+              "output": 75,
+              "cache_read": 2,
+              "cache_write": 25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -3979,7 +4265,19 @@
           "input": 0.22,
           "output": 1.32,
           "cache_read": 0.022,
-          "cache_write": 0.275
+          "cache_write": 0.275,
+          "tiers": [
+            {
+              "input": 0.44,
+              "output": 1.98,
+              "cache_read": 0.044,
+              "cache_write": 0.55,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -4115,7 +4413,19 @@
           "input": 2,
           "output": 10,
           "cache_read": 0.2,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 15,
+              "cache_read": 0.4,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -4552,7 +4862,19 @@
           "input": 2.2,
           "output": 13.2,
           "cache_read": 0.22,
-          "cache_write": 2.75
+          "cache_write": 2.75,
+          "tiers": [
+            {
+              "input": 4.4,
+              "output": 19.8,
+              "cache_read": 0.44,
+              "cache_write": 5.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -4741,7 +5063,19 @@
           "input": 0.22,
           "output": 1.32,
           "cache_read": 0.022,
-          "cache_write": 0.275
+          "cache_write": 0.275,
+          "tiers": [
+            {
+              "input": 0.44,
+              "output": 1.98,
+              "cache_read": 0.044,
+              "cache_write": 0.55,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -4877,7 +5211,19 @@
           "input": 11,
           "output": 55,
           "cache_read": 1.1,
-          "cache_write": 13.75
+          "cache_write": 13.75,
+          "tiers": [
+            {
+              "input": 22,
+              "output": 82.5,
+              "cache_read": 2.2,
+              "cache_write": 27.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -4904,7 +5250,19 @@
           "input": 2.2,
           "output": 13.2,
           "cache_read": 0.22,
-          "cache_write": 2.75
+          "cache_write": 2.75,
+          "tiers": [
+            {
+              "input": 4.4,
+              "output": 19.8,
+              "cache_read": 0.44,
+              "cache_write": 5.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -5319,7 +5677,19 @@
           "input": 0.22,
           "output": 1.32,
           "cache_read": 0.022,
-          "cache_write": 0.275
+          "cache_write": 0.275,
+          "tiers": [
+            {
+              "input": 0.44,
+              "output": 1.98,
+              "cache_read": 0.044,
+              "cache_write": 0.55,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -5692,7 +6062,19 @@
           "input": 4.4,
           "output": 22,
           "cache_read": 0.44,
-          "cache_write": 5.5
+          "cache_write": 5.5,
+          "tiers": [
+            {
+              "input": 8.8,
+              "output": 33,
+              "cache_read": 0.88,
+              "cache_write": 11,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -6024,7 +6406,19 @@
           "input": 0.11,
           "output": 0.55,
           "cache_read": 0.011,
-          "cache_write": 0.1375
+          "cache_write": 0.1375,
+          "tiers": [
+            {
+              "input": 0.22,
+              "output": 0.825,
+              "cache_read": 0.022,
+              "cache_write": 0.275,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -6051,7 +6445,19 @@
           "input": 4,
           "output": 20,
           "cache_read": 0.4,
-          "cache_write": 5
+          "cache_write": 5,
+          "tiers": [
+            {
+              "input": 8,
+              "output": 30,
+              "cache_read": 0.8,
+              "cache_write": 10,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -6415,7 +6821,19 @@
           "input": 0.2,
           "output": 1.2,
           "cache_read": 0.02,
-          "cache_write": 0.25
+          "cache_write": 0.25,
+          "tiers": [
+            {
+              "input": 0.4,
+              "output": 1.8,
+              "cache_read": 0.04,
+              "cache_write": 0.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -6641,7 +7059,19 @@
           "input": 2.2,
           "output": 11,
           "cache_read": 0.22,
-          "cache_write": 2.75
+          "cache_write": 2.75,
+          "tiers": [
+            {
+              "input": 4.4,
+              "output": 16.5,
+              "cache_read": 0.44,
+              "cache_write": 5.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -6743,7 +7173,19 @@
           "input": 2.2,
           "output": 11,
           "cache_read": 0.22,
-          "cache_write": 2.75
+          "cache_write": 2.75,
+          "tiers": [
+            {
+              "input": 4.4,
+              "output": 16.5,
+              "cache_read": 0.44,
+              "cache_write": 5.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -6947,7 +7389,19 @@
           "input": 0.1,
           "output": 0.5,
           "cache_read": 0.01,
-          "cache_write": 0.125
+          "cache_write": 0.125,
+          "tiers": [
+            {
+              "input": 0.2,
+              "output": 0.75,
+              "cache_read": 0.02,
+              "cache_write": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -7258,7 +7712,19 @@
           "input": 0.11,
           "output": 0.55,
           "cache_read": 0.011,
-          "cache_write": 0.1375
+          "cache_write": 0.1375,
+          "tiers": [
+            {
+              "input": 0.22,
+              "output": 0.825,
+              "cache_read": 0.022,
+              "cache_write": 0.275,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -7531,7 +7997,19 @@
           "input": 2,
           "output": 12,
           "cache_read": 0.2,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -7558,7 +8036,19 @@
           "input": 11,
           "output": 55,
           "cache_read": 1.1,
-          "cache_write": 13.75
+          "cache_write": 13.75,
+          "tiers": [
+            {
+              "input": 22,
+              "output": 82.5,
+              "cache_read": 2.2,
+              "cache_write": 27.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -7756,7 +8246,19 @@
           "input": 2.2,
           "output": 13.2,
           "cache_read": 0.22,
-          "cache_write": 2.75
+          "cache_write": 2.75,
+          "tiers": [
+            {
+              "input": 4.4,
+              "output": 19.8,
+              "cache_read": 0.44,
+              "cache_write": 5.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -7861,7 +8363,19 @@
           "input": 4.4,
           "output": 22,
           "cache_read": 0.44,
-          "cache_write": 5.5
+          "cache_write": 5.5,
+          "tiers": [
+            {
+              "input": 8.8,
+              "output": 33,
+              "cache_read": 0.88,
+              "cache_write": 11,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -8738,7 +9252,18 @@
         "cost": {
           "input": 2.5,
           "output": 15,
-          "cache_read": 0.25
+          "cache_read": 0.25,
+          "tiers": [
+            {
+              "input": 5,
+              "output": 22.5,
+              "cache_read": 0.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -8812,7 +9337,17 @@
         },
         "cost": {
           "input": 30,
-          "output": 180
+          "output": 180,
+          "tiers": [
+            {
+              "input": 60,
+              "output": 270,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -9660,7 +10195,19 @@
           "input": 2,
           "output": 10,
           "cache_read": 0.1,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 15,
+              "cache_read": 0.2,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -9752,7 +10299,19 @@
           "input": 10,
           "output": 50,
           "cache_read": 1,
-          "cache_write": 12.5
+          "cache_write": 12.5,
+          "tiers": [
+            {
+              "input": 20,
+              "output": 75,
+              "cache_read": 2,
+              "cache_write": 25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -10072,7 +10631,19 @@
           "input": 0.2,
           "output": 1.2,
           "cache_read": 0.02,
-          "cache_write": 0.25
+          "cache_write": 0.25,
+          "tiers": [
+            {
+              "input": 0.4,
+              "output": 1.8,
+              "cache_read": 0.04,
+              "cache_write": 0.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -10150,7 +10721,19 @@
           "input": 5,
           "output": 25,
           "cache_read": 0.5,
-          "cache_write": 6.25
+          "cache_write": 6.25,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 37.5,
+              "cache_read": 1,
+              "cache_write": 12.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -10198,7 +10781,18 @@
         "cost": {
           "input": 5,
           "output": 30,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 45,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -10321,7 +10915,19 @@
           "input": 5,
           "output": 25,
           "cache_read": 0.5,
-          "cache_write": 6.25
+          "cache_write": 6.25,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 37.5,
+              "cache_read": 1,
+              "cache_write": 12.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -10429,7 +11035,19 @@
           "input": 0.1,
           "output": 0.5,
           "cache_read": 0.01,
-          "cache_write": 0.125
+          "cache_write": 0.125,
+          "tiers": [
+            {
+              "input": 0.2,
+              "output": 0.75,
+              "cache_read": 0.02,
+              "cache_write": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -10624,7 +11242,19 @@
           "input": 2,
           "output": 12,
           "cache_read": 0.2,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -10847,7 +11477,19 @@
           "input": 4,
           "output": 20,
           "cache_read": 0.5,
-          "cache_write": 6.25
+          "cache_write": 6.25,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 45,
+              "cache_read": 1,
+              "cache_write": 12.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -10916,7 +11558,19 @@
           "input": 2,
           "output": 10,
           "cache_read": 0.2,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 15,
+              "cache_read": 0.4,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -12286,7 +12940,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -12359,7 +13024,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.3
+          "cache_read": 0.3,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 0.6,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -12405,7 +13081,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -12737,7 +13424,19 @@
           "input": 10,
           "output": 50,
           "cache_read": 1,
-          "cache_write": 12
+          "cache_write": 12,
+          "tiers": [
+            {
+              "input": 20,
+              "output": 75,
+              "cache_read": 2,
+              "cache_write": 25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -12952,7 +13651,19 @@
           "input": 0.1,
           "output": 0.5,
           "cache_read": 0.01,
-          "cache_write": 0.125
+          "cache_write": 0.125,
+          "tiers": [
+            {
+              "input": 0.2,
+              "output": 0.75,
+              "cache_read": 0.02,
+              "cache_write": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -13100,7 +13811,19 @@
           "input": 2,
           "output": 10,
           "cache_read": 0.2,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 15,
+              "cache_read": 0.4,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -15090,7 +15813,18 @@
         "cost": {
           "input": 2,
           "output": 12,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -15109,7 +15843,17 @@
         },
         "cost": {
           "input": 1.25,
-          "output": 10
+          "output": 10,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 15,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 128000,
@@ -15161,7 +15905,18 @@
         "cost": {
           "input": 1.25,
           "output": 10,
-          "cache_read": 0.125
+          "cache_read": 0.125,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 15,
+              "cache_read": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -15280,7 +16035,18 @@
         "cost": {
           "input": 2,
           "output": 12,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 131072,
@@ -15301,7 +16067,18 @@
         "cost": {
           "input": 2,
           "output": 12,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 131072,
@@ -15384,7 +16161,18 @@
         "cost": {
           "input": 2,
           "output": 12,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -15615,7 +16403,19 @@
           "input": 5,
           "output": 25,
           "cache_read": 0.5,
-          "cache_write": 6.25
+          "cache_write": 6.25,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 37.5,
+              "cache_read": 1,
+              "cache_write": 12.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -15743,7 +16543,19 @@
           "input": 5,
           "output": 25,
           "cache_read": 0.5,
-          "cache_write": 6.25
+          "cache_write": 6.25,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 37.5,
+              "cache_read": 1,
+              "cache_write": 12.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -15950,7 +16762,19 @@
           "input": 3,
           "output": 15,
           "cache_read": 0.3,
-          "cache_write": 3.75
+          "cache_write": 3.75,
+          "tiers": [
+            {
+              "input": 6,
+              "output": 22.5,
+              "cache_read": 0.6,
+              "cache_write": 7.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -16061,7 +16885,18 @@
         "cost": {
           "input": 2,
           "output": 12,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -16153,7 +16988,19 @@
           "input": 5,
           "output": 25,
           "cache_read": 0.5,
-          "cache_write": 6.25
+          "cache_write": 6.25,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 37.5,
+              "cache_read": 1,
+              "cache_write": 12.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -16209,7 +17056,18 @@
         "cost": {
           "input": 1.25,
           "output": 10,
-          "cache_read": 0.125
+          "cache_read": 0.125,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 15,
+              "cache_read": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -16341,7 +17199,18 @@
         "cost": {
           "input": 2,
           "output": 12,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -16674,7 +17543,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 2000000,
@@ -16698,7 +17578,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 2000000,
@@ -16749,7 +17640,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 200000,
@@ -16800,7 +17702,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 524288,
@@ -17103,7 +18016,19 @@
           "input": 5,
           "output": 25,
           "cache_read": 0.5,
-          "cache_write": 6.25
+          "cache_write": 6.25,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 37.5,
+              "cache_read": 1,
+              "cache_write": 12.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -17161,7 +18086,19 @@
           "input": 5,
           "output": 25,
           "cache_read": 0.5,
-          "cache_write": 6.25
+          "cache_write": 6.25,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 37.5,
+              "cache_read": 1,
+              "cache_write": 12.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -17301,7 +18238,19 @@
           "input": 3,
           "output": 15,
           "cache_read": 0.3,
-          "cache_write": 3.75
+          "cache_write": 3.75,
+          "tiers": [
+            {
+              "input": 6,
+              "output": 22.5,
+              "cache_read": 0.6,
+              "cache_write": 7.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -17414,7 +18363,19 @@
           "input": 5,
           "output": 25,
           "cache_read": 0.5,
-          "cache_write": 6.25
+          "cache_write": 6.25,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 37.5,
+              "cache_read": 1,
+              "cache_write": 12.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -20440,7 +21401,18 @@
         "cost": {
           "input": 0.14,
           "output": 0.28,
-          "cache_read": 0.0028
+          "cache_read": 0.0028,
+          "tiers": [
+            {
+              "input": 0.8,
+              "output": 4,
+              "cache_read": 0.16,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -20465,7 +21437,17 @@
         },
         "cost": {
           "input": 30,
-          "output": 180
+          "output": 180,
+          "tiers": [
+            {
+              "input": 60,
+              "output": 270,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -20935,7 +21917,18 @@
         "cost": {
           "input": 1,
           "output": 2,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2,
+              "output": 4,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 256000,
@@ -22474,7 +23467,18 @@
         "cost": {
           "input": 2,
           "output": 12,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -22551,7 +23555,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 2000000,
@@ -22892,7 +23907,18 @@
         "cost": {
           "input": 1.25,
           "output": 10,
-          "cache_read": 0.125
+          "cache_read": 0.125,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 15,
+              "cache_read": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -23086,7 +24112,18 @@
         "cost": {
           "input": 0.435,
           "output": 0.87,
-          "cache_read": 0.0036
+          "cache_read": 0.0036,
+          "tiers": [
+            {
+              "input": 2,
+              "output": 6,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -23542,7 +24579,18 @@
         "cost": {
           "input": 5,
           "output": 30,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 45,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -23953,7 +25001,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -24011,7 +25070,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 2000000,
@@ -24063,7 +25133,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 2000000,
@@ -24616,7 +25697,19 @@
           "input": 0.5,
           "output": 3,
           "cache_read": 0.05,
-          "cache_write": 0.625
+          "cache_write": 0.625,
+          "tiers": [
+            {
+              "input": 2,
+              "output": 6,
+              "cache_read": 0.2,
+              "cache_write": 2.5,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -24661,7 +25754,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 2000000,
@@ -25545,7 +26649,18 @@
         "cost": {
           "input": 0.3,
           "output": 1.2,
-          "cache_read": 0.06
+          "cache_read": 0.06,
+          "tiers": [
+            {
+              "input": 0.6,
+              "output": 2.4,
+              "cache_read": 0.12,
+              "tier": {
+                "type": "context",
+                "size": 512000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -25702,7 +26817,18 @@
         "cost": {
           "input": 0.3,
           "output": 1.2,
-          "cache_read": 0.06
+          "cache_read": 0.06,
+          "tiers": [
+            {
+              "input": 0.6,
+              "output": 2.4,
+              "cache_read": 0.12,
+              "tier": {
+                "type": "context",
+                "size": 512000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -29666,7 +30792,18 @@
         "cost": {
           "input": 2.5,
           "output": 15,
-          "cache_read": 0.25
+          "cache_read": 0.25,
+          "tiers": [
+            {
+              "input": 5,
+              "output": 22.5,
+              "cache_read": 0.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -29690,7 +30827,17 @@
         },
         "cost": {
           "input": 30,
-          "output": 180
+          "output": 180,
+          "tiers": [
+            {
+              "input": 60,
+              "output": 270,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -29734,7 +30881,17 @@
         },
         "cost": {
           "input": 30,
-          "output": 180
+          "output": 180,
+          "tiers": [
+            {
+              "input": 60,
+              "output": 270,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -30095,7 +31252,19 @@
           "input": 4,
           "output": 20,
           "cache_read": 0.4,
-          "cache_write": 5
+          "cache_write": 5,
+          "tiers": [
+            {
+              "input": 8,
+              "output": 30,
+              "cache_read": 0.8,
+              "cache_write": 10,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -30223,7 +31392,19 @@
           "input": 2,
           "output": 10,
           "cache_read": 0.1,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 15,
+              "cache_read": 0.2,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -30287,7 +31468,19 @@
           "input": 10,
           "output": 50,
           "cache_read": 1,
-          "cache_write": 12.5
+          "cache_write": 12.5,
+          "tiers": [
+            {
+              "input": 20,
+              "output": 75,
+              "cache_read": 2,
+              "cache_write": 25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -30398,7 +31591,19 @@
           "input": 4,
           "output": 20,
           "cache_read": 0.4,
-          "cache_write": 5
+          "cache_write": 5,
+          "tiers": [
+            {
+              "input": 8,
+              "output": 30,
+              "cache_read": 0.8,
+              "cache_write": 10,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -30450,7 +31655,19 @@
           "input": 0.2,
           "output": 1.2,
           "cache_read": 0.02,
-          "cache_write": 0.25
+          "cache_write": 0.25,
+          "tiers": [
+            {
+              "input": 0.4,
+              "output": 1.8,
+              "cache_read": 0.04,
+              "cache_write": 0.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -30501,7 +31718,18 @@
         "cost": {
           "input": 5,
           "output": 30,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 45,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -30584,7 +31812,19 @@
           "input": 0.1,
           "output": 0.5,
           "cache_read": 0.01,
-          "cache_write": 0.125
+          "cache_write": 0.125,
+          "tiers": [
+            {
+              "input": 0.2,
+              "output": 0.75,
+              "cache_read": 0.02,
+              "cache_write": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -30660,7 +31900,19 @@
           "input": 2,
           "output": 12,
           "cache_read": 0.2,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -30784,7 +32036,19 @@
           "input": 4,
           "output": 20,
           "cache_read": 0.4,
-          "cache_write": 5
+          "cache_write": 5,
+          "tiers": [
+            {
+              "input": 8,
+              "output": 30,
+              "cache_read": 0.8,
+              "cache_write": 10,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -30811,7 +32075,19 @@
           "input": 2,
           "output": 10,
           "cache_read": 0.2,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 15,
+              "cache_read": 0.4,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -30896,7 +32172,18 @@
         "cost": {
           "input": 2.5,
           "output": 15,
-          "cache_read": 0.25
+          "cache_read": 0.25,
+          "tiers": [
+            {
+              "input": 5,
+              "output": 22.5,
+              "cache_read": 0.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -31173,7 +32460,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -31862,7 +33160,19 @@
           "input": 3,
           "output": 15,
           "cache_read": 0.3,
-          "cache_write": 3.75
+          "cache_write": 3.75,
+          "tiers": [
+            {
+              "input": 6,
+              "output": 22.5,
+              "cache_read": 0.6,
+              "cache_write": 7.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -32056,7 +33366,19 @@
           "input": 2,
           "output": 10,
           "cache_read": 0.1,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 15,
+              "cache_read": 0.2,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -32145,7 +33467,19 @@
           "input": 10,
           "output": 50,
           "cache_read": 1,
-          "cache_write": 12.5
+          "cache_write": 12.5,
+          "tiers": [
+            {
+              "input": 20,
+              "output": 75,
+              "cache_read": 2,
+              "cache_write": 25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -32174,7 +33508,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.3
+          "cache_read": 0.3,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 0.6,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -32595,7 +33940,18 @@
         "cost": {
           "input": 2,
           "output": 12,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -32649,7 +34005,19 @@
           "input": 3,
           "output": 15,
           "cache_read": 0.3,
-          "cache_write": 3.75
+          "cache_write": 3.75,
+          "tiers": [
+            {
+              "input": 6,
+              "output": 22.5,
+              "cache_read": 0.6,
+              "cache_write": 7.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -32787,7 +34155,19 @@
           "input": 0.2,
           "output": 1.2,
           "cache_read": 0.02,
-          "cache_write": 0.25
+          "cache_write": 0.25,
+          "tiers": [
+            {
+              "input": 0.4,
+              "output": 1.8,
+              "cache_read": 0.04,
+              "cache_write": 0.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -32984,7 +34364,18 @@
         "cost": {
           "input": 5,
           "output": 30,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 45,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -33421,7 +34812,19 @@
           "input": 0.1,
           "output": 0.5,
           "cache_read": 0.01,
-          "cache_write": 0.125
+          "cache_write": 0.125,
+          "tiers": [
+            {
+              "input": 0.2,
+              "output": 0.75,
+              "cache_read": 0.02,
+              "cache_write": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -33603,7 +35006,19 @@
           "input": 2.5,
           "output": 15,
           "cache_read": 0.25,
-          "cache_write": 3.125
+          "cache_write": 3.125,
+          "tiers": [
+            {
+              "input": 5,
+              "output": 22.5,
+              "cache_read": 0.5,
+              "cache_write": 6.25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -33794,7 +35209,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -33823,7 +35249,18 @@
         "cost": {
           "input": 2,
           "output": 12,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -33876,7 +35313,19 @@
           "input": 4,
           "output": 20,
           "cache_read": 0.4,
-          "cache_write": 5
+          "cache_write": 5,
+          "tiers": [
+            {
+              "input": 8,
+              "output": 30,
+              "cache_read": 0.8,
+              "cache_write": 10,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -33995,7 +35444,19 @@
           "input": 2,
           "output": 10,
           "cache_read": 0.2,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 15,
+              "cache_read": 0.4,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -34110,7 +35571,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -34372,7 +35844,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.3
+          "cache_read": 0.3,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 0.6,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -34500,7 +35983,18 @@
         "cost": {
           "input": 0.3,
           "output": 1.2,
-          "cache_read": 0.06
+          "cache_read": 0.06,
+          "tiers": [
+            {
+              "input": 0.6,
+              "output": 2.4,
+              "cache_read": 0.12,
+              "tier": {
+                "type": "context",
+                "size": 512000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -34529,7 +36023,19 @@
           "input": 0.2,
           "output": 1.2,
           "cache_read": 0.02,
-          "cache_write": 0.25
+          "cache_write": 0.25,
+          "tiers": [
+            {
+              "input": 0.4,
+              "output": 1.8,
+              "cache_read": 0.04,
+              "cache_write": 0.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -34679,7 +36185,19 @@
           "input": 0.1,
           "output": 0.5,
           "cache_read": 0.01,
-          "cache_write": 0.125
+          "cache_write": 0.125,
+          "tiers": [
+            {
+              "input": 0.2,
+              "output": 0.75,
+              "cache_read": 0.02,
+              "cache_write": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -34740,7 +36258,19 @@
           "input": 0.5,
           "output": 3,
           "cache_read": 0.05,
-          "cache_write": 0.625
+          "cache_write": 0.625,
+          "tiers": [
+            {
+              "input": 2,
+              "output": 6,
+              "cache_read": 0.2,
+              "cache_write": 2.5,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -34873,7 +36403,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -34906,7 +36447,19 @@
           "input": 0.4,
           "output": 1.6,
           "cache_read": 0.04,
-          "cache_write": 0.5
+          "cache_write": 0.5,
+          "tiers": [
+            {
+              "input": 1.2,
+              "output": 4.8,
+              "cache_read": 0.12,
+              "cache_write": 1.5,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -35064,7 +36617,17 @@
         },
         "cost": {
           "input": 0.075,
-          "output": 0.3
+          "output": 0.3,
+          "tiers": [
+            {
+              "input": 0.1,
+              "output": 0.8,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -35091,7 +36654,17 @@
         },
         "cost": {
           "input": 0.25,
-          "output": 2
+          "output": 2,
+          "tiers": [
+            {
+              "input": 0.5,
+              "output": 4,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -35142,7 +36715,17 @@
         },
         "cost": {
           "input": 0.1,
-          "output": 0.4
+          "output": 0.4,
+          "tiers": [
+            {
+              "input": 0.2,
+              "output": 0.8,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -35170,7 +36753,17 @@
         },
         "cost": {
           "input": 0.5,
-          "output": 3
+          "output": 3,
+          "tiers": [
+            {
+              "input": 1,
+              "output": 6,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -35194,7 +36787,17 @@
         },
         "cost": {
           "input": 0.25,
-          "output": 2
+          "output": 2,
+          "tiers": [
+            {
+              "input": 0.5,
+              "output": 4,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -35430,7 +37033,19 @@
           "input": 5,
           "output": 25,
           "cache_read": 0.5,
-          "cache_write": 6.25
+          "cache_write": 6.25,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 37.5,
+              "cache_read": 1,
+              "cache_write": 12.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -35460,7 +37075,19 @@
           "input": 5,
           "output": 25,
           "cache_read": 0.5,
-          "cache_write": 6.25
+          "cache_write": 6.25,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 37.5,
+              "cache_read": 1,
+              "cache_write": 12.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -35626,7 +37253,19 @@
           "input": 3,
           "output": 15,
           "cache_read": 0.3,
-          "cache_write": 3.75
+          "cache_write": 3.75,
+          "tiers": [
+            {
+              "input": 6,
+              "output": 22.5,
+              "cache_read": 0.6,
+              "cache_write": 7.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -35679,7 +37318,19 @@
           "input": 3,
           "output": 15,
           "cache_read": 0.3,
-          "cache_write": 3.75
+          "cache_write": 3.75,
+          "tiers": [
+            {
+              "input": 6,
+              "output": 22.5,
+              "cache_read": 0.6,
+              "cache_write": 7.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 200000,
@@ -35738,7 +37389,19 @@
           "input": 3,
           "output": 15,
           "cache_read": 0.3,
-          "cache_write": 3.75
+          "cache_write": 3.75,
+          "tiers": [
+            {
+              "input": 6,
+              "output": 22.5,
+              "cache_read": 0.6,
+              "cache_write": 7.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -36685,7 +38348,18 @@
           "input": 2,
           "output": 12,
           "cache_read": 0.2,
-          "cache_write": 0.375
+          "cache_write": 0.375,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -37809,7 +39483,19 @@
           "input": 2,
           "output": 12,
           "cache_read": 0.2,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -37835,7 +39521,19 @@
           "input": 0.1,
           "output": 0.5,
           "cache_read": 0.01,
-          "cache_write": 0.125
+          "cache_write": 0.125,
+          "tiers": [
+            {
+              "input": 0.2,
+              "output": 0.75,
+              "cache_read": 0.02,
+              "cache_write": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -37861,7 +39559,19 @@
           "input": 2,
           "output": 10,
           "cache_read": 0.1,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 15,
+              "cache_read": 0.2,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -37887,7 +39597,19 @@
           "input": 10,
           "output": 50,
           "cache_read": 1,
-          "cache_write": 12.5
+          "cache_write": 12.5,
+          "tiers": [
+            {
+              "input": 20,
+              "output": 75,
+              "cache_read": 2,
+              "cache_write": 25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -38034,7 +39756,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 2000000,
@@ -38059,7 +39792,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -38085,7 +39829,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -38111,7 +39866,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.3
+          "cache_read": 0.3,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 0.6,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -38132,7 +39898,18 @@
         "cost": {
           "input": 1,
           "output": 2,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2,
+              "output": 4,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 256000,
@@ -38157,7 +39934,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 2000000,
@@ -38182,7 +39970,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -38486,7 +40285,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -38880,7 +40690,18 @@
           "input": 2,
           "output": 12,
           "cache_read": 0.2,
-          "cache_write": 0.375
+          "cache_write": 0.375,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -38954,7 +40775,18 @@
           "input": 1.25,
           "output": 10,
           "cache_read": 0.125,
-          "cache_write": 0.375
+          "cache_write": 0.375,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 15,
+              "cache_read": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -39087,7 +40919,18 @@
           "input": 2,
           "output": 12,
           "cache_read": 0.2,
-          "cache_write": 0.375
+          "cache_write": 0.375,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -39220,7 +41063,18 @@
           "input": 1.25,
           "output": 10,
           "cache_read": 0.125,
-          "cache_write": 0.375
+          "cache_write": 0.375,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 15,
+              "cache_read": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -39792,7 +41646,18 @@
         "cost": {
           "input": 5,
           "output": 30,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 45,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -39817,7 +41682,18 @@
         "cost": {
           "input": 5,
           "output": 30,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 45,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -41425,7 +43301,19 @@
           "input": 0.26,
           "output": 0.78,
           "cache_read": 0.052,
-          "cache_write": 0.325
+          "cache_write": 0.325,
+          "tiers": [
+            {
+              "input": 0.78,
+              "output": 2.34,
+              "cache_read": 0.156,
+              "cache_write": 0.975,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -41454,7 +43342,29 @@
           "input": 0.03,
           "output": 0.13,
           "cache_read": 0.006,
-          "cache_write": 0.038
+          "cache_write": 0.038,
+          "tiers": [
+            {
+              "input": 0.1,
+              "output": 0.4,
+              "cache_read": 0.02,
+              "cache_write": 0.125,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 0.2,
+              "output": 0.8,
+              "cache_read": 0.04,
+              "cache_write": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -41475,7 +43385,29 @@
           "input": 0.78,
           "output": 3.9,
           "cache_read": 0.156,
-          "cache_write": 0.975
+          "cache_write": 0.975,
+          "tiers": [
+            {
+              "input": 1.56,
+              "output": 7.8,
+              "cache_read": 0.312,
+              "cache_write": 1.95,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 1.95,
+              "output": 9.75,
+              "cache_read": 0.39,
+              "cache_write": 2.4375,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -41626,7 +43558,17 @@
         },
         "cost": {
           "input": 0.26,
-          "output": 0.78
+          "output": 0.78,
+          "tiers": [
+            {
+              "input": 0.78,
+              "output": 2.34,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -41714,7 +43656,18 @@
         "cost": {
           "input": 0.1875,
           "output": 1.125,
-          "cache_write": 0.234375
+          "cache_write": 0.234375,
+          "tiers": [
+            {
+              "input": 0.75,
+              "output": 3,
+              "cache_write": 0.9375,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -41735,7 +43688,29 @@
           "input": 0.195,
           "output": 0.975,
           "cache_read": 0.039,
-          "cache_write": 0.24375
+          "cache_write": 0.24375,
+          "tiers": [
+            {
+              "input": 0.325,
+              "output": 1.625,
+              "cache_read": 0.065,
+              "cache_write": 0.40625,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 0.52,
+              "output": 2.6,
+              "cache_read": 0.104,
+              "cache_write": 0.65,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -41800,7 +43775,25 @@
         },
         "cost": {
           "input": 0.78,
-          "output": 3.9
+          "output": 3.9,
+          "tiers": [
+            {
+              "input": 1.56,
+              "output": 7.8,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 1.95,
+              "output": 9.75,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -41820,7 +43813,29 @@
           "input": 0.65,
           "output": 3.25,
           "cache_read": 0.13,
-          "cache_write": 0.8125
+          "cache_write": 0.8125,
+          "tiers": [
+            {
+              "input": 1.17,
+              "output": 5.85,
+              "cache_read": 0.234,
+              "cache_write": 1.4625,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 1.95,
+              "output": 9.75,
+              "cache_read": 0.39,
+              "cache_write": 2.4375,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -41895,7 +43910,18 @@
         "cost": {
           "input": 0.3,
           "output": 1.8,
-          "cache_write": 0.375
+          "cache_write": 0.375,
+          "tiers": [
+            {
+              "input": 0.375,
+              "output": 2.25,
+              "cache_write": 0.46875,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -41972,7 +43998,18 @@
         "cost": {
           "input": 1.027,
           "output": 6.162,
-          "cache_write": 1.28375
+          "cache_write": 1.28375,
+          "tiers": [
+            {
+              "input": 1.58,
+              "output": 9.48,
+              "cache_write": 1.975,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -42159,7 +44196,17 @@
         },
         "cost": {
           "input": 0.26,
-          "output": 1.56
+          "output": 1.56,
+          "tiers": [
+            {
+              "input": 0.325,
+              "output": 1.95,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -42244,7 +44291,18 @@
         "cost": {
           "input": 0.325,
           "output": 1.95,
-          "cache_write": 0.40625
+          "cache_write": 0.40625,
+          "tiers": [
+            {
+              "input": 1.3,
+              "output": 3.9,
+              "cache_write": 1.625,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -42312,7 +44370,19 @@
           "input": 0.32,
           "output": 1.28,
           "cache_read": 0.064,
-          "cache_write": 0.4
+          "cache_write": 0.4,
+          "tiers": [
+            {
+              "input": 0.96,
+              "output": 3.84,
+              "cache_read": 0.192,
+              "cache_write": 1.2,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -42429,7 +44499,18 @@
         "cost": {
           "input": 2.5,
           "output": 15,
-          "cache_read": 0.25
+          "cache_read": 0.25,
+          "tiers": [
+            {
+              "input": 5,
+              "output": 22.5,
+              "cache_read": 0.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -42479,7 +44560,17 @@
         },
         "cost": {
           "input": 30,
-          "output": 180
+          "output": 180,
+          "tiers": [
+            {
+              "input": 60,
+              "output": 270,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -42543,7 +44634,19 @@
           "input": 10,
           "output": 50,
           "cache_read": 1,
-          "cache_write": 12.5
+          "cache_write": 12.5,
+          "tiers": [
+            {
+              "input": 20,
+              "output": 75,
+              "cache_read": 2,
+              "cache_write": 25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -42567,7 +44670,17 @@
         },
         "cost": {
           "input": 30,
-          "output": 180
+          "output": 180,
+          "tiers": [
+            {
+              "input": 60,
+              "output": 270,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -42767,7 +44880,19 @@
           "input": 4,
           "output": 20,
           "cache_read": 0.4,
-          "cache_write": 5
+          "cache_write": 5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 15,
+              "cache_read": 0.4,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -43054,7 +45179,19 @@
           "input": 2,
           "output": 10,
           "cache_read": 0.1,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 15,
+              "cache_read": 0.2,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -43101,7 +45238,19 @@
           "input": 10,
           "output": 50,
           "cache_read": 1,
-          "cache_write": 12.5
+          "cache_write": 12.5,
+          "tiers": [
+            {
+              "input": 20,
+              "output": 75,
+              "cache_read": 2,
+              "cache_write": 25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -43128,7 +45277,19 @@
           "input": 0.2,
           "output": 1.2,
           "cache_read": 0.02,
-          "cache_write": 0.25
+          "cache_write": 0.25,
+          "tiers": [
+            {
+              "input": 0.4,
+              "output": 1.8,
+              "cache_read": 0.04,
+              "cache_write": 0.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -43359,7 +45520,19 @@
           "input": 2,
           "output": 10,
           "cache_read": 0.2,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 15,
+              "cache_read": 0.4,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -43431,7 +45604,19 @@
           "input": 0.2,
           "output": 1.2,
           "cache_read": 0.02,
-          "cache_write": 0.25
+          "cache_write": 0.25,
+          "tiers": [
+            {
+              "input": 0.4,
+              "output": 1.8,
+              "cache_read": 0.04,
+              "cache_write": 0.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -43509,7 +45694,18 @@
         "cost": {
           "input": 5,
           "output": 30,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 45,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -43614,7 +45810,19 @@
           "input": 2,
           "output": 12,
           "cache_read": 0.2,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -43641,7 +45849,19 @@
           "input": 0.1,
           "output": 0.5,
           "cache_read": 0.01,
-          "cache_write": 0.125
+          "cache_write": 0.125,
+          "tiers": [
+            {
+              "input": 0.2,
+              "output": 0.75,
+              "cache_read": 0.02,
+              "cache_write": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -43668,7 +45888,19 @@
           "input": 2,
           "output": 10,
           "cache_read": 0.1,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 15,
+              "cache_read": 0.2,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -43719,7 +45951,19 @@
           "input": 0.1,
           "output": 0.5,
           "cache_read": 0.01,
-          "cache_write": 0.125
+          "cache_write": 0.125,
+          "tiers": [
+            {
+              "input": 0.2,
+              "output": 0.75,
+              "cache_read": 0.02,
+              "cache_write": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -43745,7 +45989,19 @@
           "input": 2,
           "output": 12,
           "cache_read": 0.2,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -43896,7 +46152,19 @@
           "input": 2,
           "output": 10,
           "cache_read": 0.2,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 15,
+              "cache_read": 0.4,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -43923,7 +46191,19 @@
           "input": 2,
           "output": 10,
           "cache_read": 0.2,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 15,
+              "cache_read": 0.4,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -45508,7 +47788,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 2000000,
@@ -45545,7 +47836,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 2000000,
@@ -45570,7 +47872,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 200001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -45602,7 +47915,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 2000000,
@@ -45692,7 +48016,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -45733,7 +48068,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.3
+          "cache_read": 0.3,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 0.6,
+              "tier": {
+                "type": "context",
+                "size": 200001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -45786,7 +48132,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 2000000,
@@ -45804,7 +48161,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.4
+          "cache_read": 0.4,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 2000000,
@@ -45829,7 +48197,18 @@
         "cost": {
           "input": 1,
           "output": 2,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2,
+              "output": 4,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 256000,
@@ -45872,7 +48251,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 2000000,
@@ -45897,7 +48287,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 200001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -46463,7 +48864,19 @@
           "input": 3,
           "output": 15,
           "cache_read": 0.3,
-          "cache_write": 3.75
+          "cache_write": 3.75,
+          "tiers": [
+            {
+              "input": 6,
+              "output": 22.5,
+              "cache_read": 0.6,
+              "cache_write": 7.5,
+              "tier": {
+                "type": "context",
+                "size": 200001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -46524,7 +48937,19 @@
           "input": 3,
           "output": 15,
           "cache_read": 0.3,
-          "cache_write": 3.75
+          "cache_write": 3.75,
+          "tiers": [
+            {
+              "input": 6,
+              "output": 22.5,
+              "cache_read": 0.6,
+              "cache_write": 7.5,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -48093,7 +50518,27 @@
         "cost": {
           "input": 1.5,
           "output": 7.5,
-          "cache_read": 0.3
+          "cache_read": 0.3,
+          "tiers": [
+            {
+              "input": 2.7,
+              "output": 13.5,
+              "cache_read": 0.54,
+              "tier": {
+                "type": "context",
+                "size": 32001
+              }
+            },
+            {
+              "input": 4.5,
+              "output": 22.5,
+              "cache_read": 0.9,
+              "tier": {
+                "type": "context",
+                "size": 128001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -48132,7 +50577,19 @@
           "input": 0.4,
           "output": 2.4,
           "cache_read": 0.04,
-          "cache_write": 0.5
+          "cache_write": 0.5,
+          "tiers": [
+            {
+              "input": 0.5,
+              "output": 3,
+              "cache_read": 0.05,
+              "cache_write": 0.625,
+              "tier": {
+                "type": "context",
+                "size": 256001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -48163,7 +50620,19 @@
           "input": 1.3,
           "output": 7.8,
           "cache_read": 0.13,
-          "cache_write": 1.625
+          "cache_write": 1.625,
+          "tiers": [
+            {
+              "input": 2,
+              "output": 12,
+              "cache_read": 0.2,
+              "cache_write": 2.5,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 240000,
@@ -48251,7 +50720,29 @@
           "input": 0.03,
           "output": 0.13,
           "cache_read": 0.006,
-          "cache_write": 0.038
+          "cache_write": 0.038,
+          "tiers": [
+            {
+              "input": 0.1,
+              "output": 0.4,
+              "cache_read": 0.02,
+              "cache_write": 0.125,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 0.2,
+              "output": 0.8,
+              "cache_read": 0.04,
+              "cache_write": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 991000,
@@ -48271,7 +50762,27 @@
         "cost": {
           "input": 1.2,
           "output": 6,
-          "cache_read": 0.24
+          "cache_read": 0.24,
+          "tiers": [
+            {
+              "input": 2.4,
+              "output": 12,
+              "cache_read": 0.48,
+              "tier": {
+                "type": "context",
+                "size": 32001
+              }
+            },
+            {
+              "input": 3,
+              "output": 15,
+              "cache_read": 0.6,
+              "tier": {
+                "type": "context",
+                "size": 128001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -48386,7 +50897,27 @@
         "cost": {
           "input": 1.2,
           "output": 6,
-          "cache_read": 0.24
+          "cache_read": 0.24,
+          "tiers": [
+            {
+              "input": 2.4,
+              "output": 12,
+              "cache_read": 0.48,
+              "tier": {
+                "type": "context",
+                "size": 32001
+              }
+            },
+            {
+              "input": 3,
+              "output": 15,
+              "cache_read": 0.6,
+              "tier": {
+                "type": "context",
+                "size": 128001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -48459,7 +50990,27 @@
         "cost": {
           "input": 1.2,
           "output": 6,
-          "cache_read": 0.24
+          "cache_read": 0.24,
+          "tiers": [
+            {
+              "input": 2.4,
+              "output": 12,
+              "cache_read": 0.48,
+              "tier": {
+                "type": "context",
+                "size": 32001
+              }
+            },
+            {
+              "input": 3,
+              "output": 15,
+              "cache_read": 0.6,
+              "tier": {
+                "type": "context",
+                "size": 128001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 256000,
@@ -48478,7 +51029,36 @@
         "cost": {
           "input": 1,
           "output": 5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 1.8,
+              "output": 9,
+              "cache_read": 0.36,
+              "tier": {
+                "type": "context",
+                "size": 32001
+              }
+            },
+            {
+              "input": 3,
+              "output": 15,
+              "cache_read": 0.6,
+              "tier": {
+                "type": "context",
+                "size": 128001
+              }
+            },
+            {
+              "input": 6,
+              "output": 60,
+              "cache_read": 1.2,
+              "tier": {
+                "type": "context",
+                "size": 256001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -48717,7 +51297,19 @@
           "input": 0.5,
           "output": 3,
           "cache_read": 0.05,
-          "cache_write": 0.625
+          "cache_write": 0.625,
+          "tiers": [
+            {
+              "input": 2,
+              "output": 6,
+              "cache_read": 0.2,
+              "cache_write": 2.5,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -48757,7 +51349,19 @@
           "input": 0.4,
           "output": 1.6,
           "cache_read": 0.08,
-          "cache_write": 0.5
+          "cache_write": 0.5,
+          "tiers": [
+            {
+              "input": 1.2,
+              "output": 4.8,
+              "cache_read": 0.24,
+              "cache_write": 1.5,
+              "tier": {
+                "type": "context",
+                "size": 256000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -49008,7 +51612,18 @@
         "cost": {
           "input": 0.25,
           "output": 2,
-          "cache_read": 0.05
+          "cache_read": 0.05,
+          "tiers": [
+            {
+              "input": 0.5,
+              "output": 4,
+              "cache_read": 0.05,
+              "tier": {
+                "type": "context",
+                "size": 128001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 256000,
@@ -49180,7 +51795,18 @@
         "cost": {
           "input": 0.25,
           "output": 2,
-          "cache_read": 0.05
+          "cache_read": 0.05,
+          "tiers": [
+            {
+              "input": 0.5,
+              "output": 4,
+              "cache_read": 0.05,
+              "tier": {
+                "type": "context",
+                "size": 128001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 256000,
@@ -49485,7 +52111,18 @@
         "cost": {
           "input": 2,
           "output": 12,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -49900,7 +52537,18 @@
         "cost": {
           "input": 1.25,
           "output": 10,
-          "cache_read": 0.125
+          "cache_read": 0.125,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 15,
+              "cache_read": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1048576,
@@ -49980,7 +52628,18 @@
         "cost": {
           "input": 5,
           "output": 30,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 45,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 272001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -50029,7 +52688,18 @@
         "cost": {
           "input": 5,
           "output": 30,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 45,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 272001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -51494,7 +54164,18 @@
         "cost": {
           "input": 2.5,
           "output": 15,
-          "cache_read": 0.25
+          "cache_read": 0.25,
+          "tiers": [
+            {
+              "input": 5,
+              "output": 22.5,
+              "cache_read": 0.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -51519,7 +54200,17 @@
         },
         "cost": {
           "input": 30,
-          "output": 180
+          "output": 180,
+          "tiers": [
+            {
+              "input": 60,
+              "output": 270,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -51632,7 +54323,17 @@
         },
         "cost": {
           "input": 30,
-          "output": 180
+          "output": 180,
+          "tiers": [
+            {
+              "input": 60,
+              "output": 270,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -51797,7 +54498,19 @@
           "input": 4,
           "output": 20,
           "cache_read": 0.2,
-          "cache_write": 5
+          "cache_write": 5,
+          "tiers": [
+            {
+              "input": 8,
+              "output": 30,
+              "cache_read": 0.4,
+              "cache_write": 10,
+              "tier": {
+                "type": "context",
+                "size": 272001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -51922,7 +54635,19 @@
           "input": 0.4,
           "output": 2.4,
           "cache_read": 0.04,
-          "cache_write": 0.5
+          "cache_write": 0.5,
+          "tiers": [
+            {
+              "input": 0.8,
+              "output": 3.6,
+              "cache_read": 0.08,
+              "cache_write": 1,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -51949,7 +54674,19 @@
           "input": 20,
           "output": 100,
           "cache_read": 2,
-          "cache_write": 25
+          "cache_write": 25,
+          "tiers": [
+            {
+              "input": 40,
+              "output": 150,
+              "cache_read": 4,
+              "cache_write": 50,
+              "tier": {
+                "type": "context",
+                "size": 272001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -52185,7 +54922,19 @@
           "input": 8,
           "output": 40,
           "cache_read": 0.8,
-          "cache_write": 10
+          "cache_write": 10,
+          "tiers": [
+            {
+              "input": 16,
+              "output": 60,
+              "cache_read": 1.6,
+              "cache_write": 20,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -52263,7 +55012,19 @@
           "input": 2,
           "output": 10,
           "cache_read": 0.1,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 15,
+              "cache_read": 0.2,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -52329,7 +55090,19 @@
           "input": 10,
           "output": 50,
           "cache_read": 1,
-          "cache_write": 12.5
+          "cache_write": 12.5,
+          "tiers": [
+            {
+              "input": 20,
+              "output": 75,
+              "cache_read": 2,
+              "cache_write": 25,
+              "tier": {
+                "type": "context",
+                "size": 272001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -52530,7 +55303,19 @@
           "input": 4,
           "output": 24,
           "cache_read": 0.4,
-          "cache_write": 5
+          "cache_write": 5,
+          "tiers": [
+            {
+              "input": 8,
+              "output": 36,
+              "cache_read": 0.8,
+              "cache_write": 10,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -52603,7 +55388,19 @@
           "input": 0.2,
           "output": 1.2,
           "cache_read": 0.02,
-          "cache_write": 0.25
+          "cache_write": 0.25,
+          "tiers": [
+            {
+              "input": 0.4,
+              "output": 1.8,
+              "cache_read": 0.04,
+              "cache_write": 0.5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -52681,7 +55478,18 @@
         "cost": {
           "input": 5,
           "output": 30,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 10,
+              "output": 45,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -52708,7 +55516,19 @@
           "input": 4,
           "output": 20,
           "cache_read": 0.4,
-          "cache_write": 5
+          "cache_write": 5,
+          "tiers": [
+            {
+              "input": 8,
+              "output": 30,
+              "cache_read": 0.8,
+              "cache_write": 10,
+              "tier": {
+                "type": "context",
+                "size": 272001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -52749,7 +55569,19 @@
           "input": 0.2,
           "output": 1,
           "cache_read": 0.02,
-          "cache_write": 0.25
+          "cache_write": 0.25,
+          "tiers": [
+            {
+              "input": 0.4,
+              "output": 1.5,
+              "cache_read": 0.04,
+              "cache_write": 0.5,
+              "tier": {
+                "type": "context",
+                "size": 272001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -52841,7 +55673,19 @@
           "input": 0.1,
           "output": 0.5,
           "cache_read": 0.01,
-          "cache_write": 0.125
+          "cache_write": 0.125,
+          "tiers": [
+            {
+              "input": 0.2,
+              "output": 0.75,
+              "cache_read": 0.02,
+              "cache_write": 0.25,
+              "tier": {
+                "type": "context",
+                "size": 272001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -52933,7 +55777,19 @@
           "input": 2,
           "output": 12,
           "cache_read": 0.2,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 18,
+              "cache_read": 0.4,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -53020,7 +55876,19 @@
           "input": 4,
           "output": 20,
           "cache_read": 0.4,
-          "cache_write": 5
+          "cache_write": 5,
+          "tiers": [
+            {
+              "input": 8,
+              "output": 30,
+              "cache_read": 0.8,
+              "cache_write": 10,
+              "tier": {
+                "type": "context",
+                "size": 272000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -53082,7 +55950,19 @@
           "input": 2,
           "output": 10,
           "cache_read": 0.2,
-          "cache_write": 2.5
+          "cache_write": 2.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 15,
+              "cache_read": 0.4,
+              "cache_write": 5,
+              "tier": {
+                "type": "context",
+                "size": 272001
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1050000,
@@ -53460,7 +56340,27 @@
         "cost": {
           "input": 0.11875,
           "output": 1.18747,
-          "cache_read": 0.02375
+          "cache_read": 0.02375,
+          "tiers": [
+            {
+              "input": 0.17812,
+              "output": 2.37494,
+              "cache_read": 0.02375,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 0.35624,
+              "output": 3.56241,
+              "cache_read": 0.02375,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 256000,
@@ -53497,7 +56397,27 @@
         "cost": {
           "input": 0.47499,
           "output": 2.37494,
-          "cache_read": 0.095
+          "cache_read": 0.095,
+          "tiers": [
+            {
+              "input": 0.71248,
+              "output": 3.56241,
+              "cache_read": 0.1425,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 1.42496,
+              "output": 7.12482,
+              "cache_read": 0.28499,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 256000,
@@ -53534,7 +56454,27 @@
         "cost": {
           "input": 0.08906,
           "output": 0.53436,
-          "cache_read": 0.01781
+          "cache_read": 0.01781,
+          "tiers": [
+            {
+              "input": 0.13359,
+              "output": 0.80154,
+              "cache_read": 0.02672,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 0.26718,
+              "output": 1.60308,
+              "cache_read": 0.05344,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 256000,
@@ -53599,7 +56539,27 @@
         "cost": {
           "input": 0.11875,
           "output": 1.18747,
-          "cache_read": 0.02375
+          "cache_read": 0.02375,
+          "tiers": [
+            {
+              "input": 0.17812,
+              "output": 2.37494,
+              "cache_read": 0.02375,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 0.35624,
+              "output": 3.56241,
+              "cache_read": 0.02375,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 256000,
@@ -53636,7 +56596,27 @@
         "cost": {
           "input": 0.02969,
           "output": 0.29687,
-          "cache_read": 0.00594
+          "cache_read": 0.00594,
+          "tiers": [
+            {
+              "input": 0.05937,
+              "output": 0.59374,
+              "cache_read": 0.01187,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 0.11875,
+              "output": 1.18747,
+              "cache_read": 0.02375,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 256000,
@@ -53673,7 +56653,27 @@
         "cost": {
           "input": 0.47499,
           "output": 2.37494,
-          "cache_read": 0.095
+          "cache_read": 0.095,
+          "tiers": [
+            {
+              "input": 0.71248,
+              "output": 3.56241,
+              "cache_read": 0.1425,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 1.42496,
+              "output": 7.12482,
+              "cache_read": 0.28499,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 262144,
@@ -53779,7 +56779,27 @@
         "cost": {
           "input": 0.11875,
           "output": 1.18747,
-          "cache_read": 0.02375
+          "cache_read": 0.02375,
+          "tiers": [
+            {
+              "input": 0.17812,
+              "output": 2.37494,
+              "cache_read": 0.02375,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 0.35624,
+              "output": 3.56241,
+              "cache_read": 0.02375,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 256000,
@@ -53844,7 +56864,27 @@
         "cost": {
           "input": 0.02227,
           "output": 0.22265,
-          "cache_read": 0.00445
+          "cache_read": 0.00445,
+          "tiers": [
+            {
+              "input": 0.04453,
+              "output": 0.4453,
+              "cache_read": 0.00445,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            },
+            {
+              "input": 0.08906,
+              "output": 0.8906,
+              "cache_read": 0.00445,
+              "tier": {
+                "type": "context",
+                "size": 128000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 256000,
@@ -53876,7 +56916,18 @@
         "cost": {
           "input": 0.11875,
           "output": 0.29687,
-          "cache_read": 0.02375
+          "cache_read": 0.02375,
+          "tiers": [
+            {
+              "input": 0.17812,
+              "output": 0.8906,
+              "cache_read": 0.02375,
+              "tier": {
+                "type": "context",
+                "size": 32000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 256000,
@@ -53974,7 +57025,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -54028,7 +57090,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -54048,7 +57121,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -54088,7 +57172,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.3
+          "cache_read": 0.3,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 0.6,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,
@@ -54108,7 +57203,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -54143,7 +57249,18 @@
         "cost": {
           "input": 1,
           "output": 2,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2,
+              "output": 4,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 256000,
@@ -54168,7 +57285,18 @@
         "cost": {
           "input": 1.25,
           "output": 2.5,
-          "cache_read": 0.2
+          "cache_read": 0.2,
+          "tiers": [
+            {
+              "input": 2.5,
+              "output": 5,
+              "cache_read": 0.4,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 1000000,
@@ -54193,7 +57321,18 @@
         "cost": {
           "input": 2,
           "output": 6,
-          "cache_read": 0.5
+          "cache_read": 0.5,
+          "tiers": [
+            {
+              "input": 4,
+              "output": 12,
+              "cache_read": 1,
+              "tier": {
+                "type": "context",
+                "size": 200000
+              }
+            }
+          ]
         },
         "limit": {
           "context": 500000,

From d26ce8ff80486ff75412a116c01ce523de43d8b2 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 14:23:49 +0200
Subject: [PATCH 243/286] feat(openai-base): replay Responses answer items with
 their id and phase

OpenAI Responses gives each answer item an id and a phase (commentary or
final_answer). The adapter kept item ids only for tool calls and
reasoning, so a replayed answer lost its phase.

The adapter now puts each message item's id and phase on RUN_FINISHED,
and chat() keeps them on the assistant message in
`metadata.tanstack.responseItems`. A same-model replay sends each text
block back as its item, with the id and the phase. Another model, or a
message whose blocks do not match its items, gets the plain text.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/responses-answer-items.md          |  6 ++
 packages/ai/src/activities/chat/index.ts      |  2 +
 packages/ai/src/types.ts                      |  8 ++
 .../src/adapters/responses-text.ts            | 53 +++++++++-
 .../openai-base/tests/replay-parity.test.ts   | 97 ++++++++++++++++++-
 5 files changed, 160 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/responses-answer-items.md

diff --git a/.changeset/responses-answer-items.md b/.changeset/responses-answer-items.md
new file mode 100644
index 0000000000..0f6f8bc51a
--- /dev/null
+++ b/.changeset/responses-answer-items.md
@@ -0,0 +1,6 @@
+---
+'@tanstack/ai': minor
+'@tanstack/openai-base': patch
+---
+
+Keep each OpenAI Responses answer item's `id` and `phase` (`commentary` or `final_answer`) on the assistant message, in `metadata.tanstack.responseItems`. A same-model replay sends each item back with its `id` and `phase`. Another model gets the plain text, as before.
diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index eb9534cb5f..5fda2a0f2b 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -2050,6 +2050,8 @@ class TextEngine<
       const responseId = chunk.responseId ?? incoming?.responseId
       if (model !== undefined) metadata.model = model
       if (responseId !== undefined) metadata.responseId = responseId
+      if (incoming?.responseItems !== undefined)
+        metadata.responseItems = incoming.responseItems
     }
     if (chunk.type === EventType.RUN_ERROR) {
       metadata.stopReason ??= 'error'
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index a3740fecf1..9860021892 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -690,6 +690,12 @@ export interface TanStackMessageMetadata {
   source?: MessageSource
   stopReason?: 'error' | 'aborted'
   responseId?: string
+  /**
+   * The provider's answer items of this assistant message, in order, for a
+   * same-model replay. The OpenAI Responses adapter keeps each output
+   * message item's `id` and `phase` (`commentary` or `final_answer`).
+   */
+  responseItems?: Array<{ id: string; phase?: string }>
   /** Parent chat run that produced this assistant message. */
   runId?: string
   /**
@@ -735,6 +741,8 @@ export interface TanStackRunMetadata {
   source?: MessageSource
   model?: string
   responseId?: string
+  /** The answer items of this model call. See `TanStackMessageMetadata.responseItems`. */
+  responseItems?: TanStackMessageMetadata['responseItems']
   finishReason?: 'stop' | 'length' | 'content_filter' | 'tool_calls' | null
   /** TokenUsage fields that have no AG-UI `usage[]` equivalent. */
   usage?: TokenUsageLeftover
diff --git a/packages/openai-base/src/adapters/responses-text.ts b/packages/openai-base/src/adapters/responses-text.ts
index d10876d422..3335bcf7a4 100644
--- a/packages/openai-base/src/adapters/responses-text.ts
+++ b/packages/openai-base/src/adapters/responses-text.ts
@@ -65,6 +65,7 @@ import type {
   ModelReasoning,
   ProviderExecutedToolSource,
   ReasoningCapability,
+  TanStackMessageMetadata,
   TextOptions,
   AnyTool,
   NormalizedSystemPrompt,
@@ -251,6 +252,43 @@ interface LegacyReasoningDeltaEvent {
   delta?: unknown
 }
 
+/**
+ * The assistant's text as Responses input. A same-model message with one
+ * saved answer item per text block replays each block with its item `id`
+ * and `phase`. Another model's message, or one whose blocks do not match its
+ * items, replays as plain text.
+ */
+function answerItems(
+  message: ModelMessage,
+  text: string,
+  foreign: boolean,
+): ResponseInput {
+  const items: TanStackMessageMetadata['responseItems'] = foreign
+    ? undefined
+    : message.metadata?.tanstack?.responseItems
+  const texts = orderedAssistantBlocks(message)?.flatMap((block) =>
+    block.type === 'text' ? [block.text] : [],
+  ) ?? [text]
+  if (!items || items.length !== texts.length)
+    return [{ type: 'message', role: 'assistant', content: text }]
+  return items.map((item, index) => ({
+    type: 'message',
+    role: 'assistant',
+    id: item.id,
+    status: 'completed',
+    content: [
+      {
+        type: 'output_text',
+        text: sanitizeUnicode(texts[index] ?? ''),
+        annotations: [],
+      },
+    ],
+    ...(item.phase === 'commentary' || item.phase === 'final_answer'
+      ? { phase: item.phase }
+      : {}),
+  }))
+}
+
 /**
  * Shared implementation of the OpenAI Responses API. Holds the stream-event
  * accumulator + AG-UI lifecycle and calls the OpenAI SDK directly. Subclasses
@@ -2144,9 +2182,18 @@ export abstract class OpenAIBaseResponsesTextAdapter<
                 ? 'content_filter'
                 : 'stop'
 
+          // Each answer item's id and phase, for a same-model replay.
+          const responseItems = responseOutput.flatMap((item) =>
+            item.type === 'message' && item.id
+              ? [{ id: item.id, ...(item.phase ? { phase: item.phase } : {}) }]
+              : [],
+          )
           yield {
             type: EventType.RUN_FINISHED,
             ...(responseId ? { responseId } : {}),
+            ...(responseItems.length > 0
+              ? { metadata: { tanstack: { responseItems } } }
+              : {}),
             runId: aguiState.runId,
             threadId: aguiState.threadId,
             model: model || options.model,
@@ -2738,11 +2785,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
           // Add the assistant's text message if there is content
           const contentStr = this.extractTextContent(message.content)
           if (contentStr) {
-            result.push({
-              type: 'message',
-              role: 'assistant',
-              content: contentStr,
-            })
+            result.push(...answerItems(message, contentStr, Boolean(foreign)))
           }
         }
 
diff --git a/packages/openai-base/tests/replay-parity.test.ts b/packages/openai-base/tests/replay-parity.test.ts
index 0f9a8c46be..79cfc56295 100644
--- a/packages/openai-base/tests/replay-parity.test.ts
+++ b/packages/openai-base/tests/replay-parity.test.ts
@@ -1,7 +1,11 @@
 import { describe, expect, it, vi } from 'vitest'
 import OpenAI from 'openai'
 import { chat, EventType } from '@tanstack/ai'
-import type { AdapterYieldChunk, ModelMessage } from '@tanstack/ai'
+import type {
+  AdapterYieldChunk,
+  ChatMiddleware,
+  ModelMessage,
+} from '@tanstack/ai'
 import {
   resolveDebugOption,
   hashToolCallId,
@@ -1752,3 +1756,94 @@ describe('OpenAI replay parity', () => {
     },
   )
 })
+
+describe('Responses answer items on replay', () => {
+  /** Turn 1 with one answer item. Returns the saved transcript. */
+  async function firstTurn() {
+    const answer = {
+      type: 'message',
+      id: 'msg_answer',
+      role: 'assistant',
+      status: 'completed',
+      phase: 'final_answer',
+      content: [{ type: 'output_text', text: 'Hi there', annotations: [] }],
+    }
+    const mock = sdk(
+      [
+        {
+          ...responseCompleted,
+          response: { ...responseCompleted.response, output: [answer] },
+        },
+      ],
+      true,
+    )
+    let saved: Array<ModelMessage> = []
+    const keep: ChatMiddleware = {
+      name: 'keep-transcript',
+      onFinish(ctx) {
+        saved = [...ctx.messages]
+      },
+    }
+    await collect(
+      chat({
+        adapter: new Responses(mock.client),
+        messages: [{ role: 'user', content: 'Hi' }],
+        middleware: [keep],
+      }),
+    )
+    return saved
+  }
+
+  /** Turn 2 on `messages`. Returns the assistant items of its request input. */
+  async function secondTurnInput(messages: Array<ModelMessage>) {
+    const mock = sdk([responseCompleted], true)
+    await collect(
+      chat({
+        adapter: new Responses(mock.client),
+        messages: [...messages, { role: 'user', content: 'Again' }],
+      }),
+    )
+    const body = mock.bodies[0] as { input: Array<Record<string, unknown>> }
+    return body.input.filter((item) => item.role === 'assistant')
+  }
+
+  it('sends the id and phase of the first answer on a same-model request', async () => {
+    const saved = await firstTurn()
+    expect(saved.at(-1)?.metadata?.tanstack?.responseItems).toEqual([
+      { id: 'msg_answer', phase: 'final_answer' },
+    ])
+    expect(await secondTurnInput(saved)).toEqual([
+      {
+        type: 'message',
+        role: 'assistant',
+        id: 'msg_answer',
+        status: 'completed',
+        phase: 'final_answer',
+        content: [{ type: 'output_text', text: 'Hi there', annotations: [] }],
+      },
+    ])
+  })
+
+  it('leaves them out for another model', async () => {
+    const saved = (await firstTurn()).map((message) =>
+      message.role === 'assistant'
+        ? {
+            ...message,
+            metadata: {
+              tanstack: {
+                ...message.metadata?.tanstack,
+                source: {
+                  provider: 'openai',
+                  api: 'openai-responses',
+                  model: 'gpt-4.1',
+                },
+              },
+            },
+          }
+        : message,
+    )
+    expect(await secondTurnInput(saved)).toEqual([
+      { type: 'message', role: 'assistant', content: 'Hi there' },
+    ])
+  })
+})

From c0d7bfe216c75834381e9d68afccbd8a8fc15274 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 14:23:52 +0200
Subject: [PATCH 244/286] docs: reasoning from the adapter config, catalog
 adapters, and cost rules

- Reasoning: a model the adapter does not list takes the `reasoning`
  config, with the factories that accept it.
- Model catalog: build an adapter from a record with modelReasoning, the
  adapter for each `api`, and the tier and 1-hour cache write prices.
- Prompt caching: usage reports `cacheWrite1hTokens`.
- OpenAI: answer items keep their id and phase on the next request.

Changesets for the reasoning config, the cost rules, and the Vertex
Claude records. An E2E wire test checks that a gateway id outside the
Anthropic list gets its thinking budget from the config, and none with
`reasoning: false`.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/adapter-reasoning-config.md        |  20 +++
 .changeset/ai-models-no-vertex-claude.md      |   5 +
 .changeset/model-cost-tiers.md                |  10 ++
 docs/adapters/openai.md                       |   6 +
 docs/advanced/prompt-caching.md               |   2 +
 docs/chat/reasoning.md                        |  47 +++++++
 docs/config.json                              |  10 +-
 docs/models/catalog.md                        |  72 +++++++++-
 testing/e2e/src/routeTree.gen.ts              |  45 ++++++
 .../api.adapter-config-reasoning-wire.ts      | 130 ++++++++++++++++++
 .../adapter-config-reasoning-wire.spec.ts     |  37 +++++
 11 files changed, 379 insertions(+), 5 deletions(-)
 create mode 100644 .changeset/adapter-reasoning-config.md
 create mode 100644 .changeset/ai-models-no-vertex-claude.md
 create mode 100644 .changeset/model-cost-tiers.md
 create mode 100644 testing/e2e/src/routes/api.adapter-config-reasoning-wire.ts
 create mode 100644 testing/e2e/tests/adapter-config-reasoning-wire.spec.ts

diff --git a/.changeset/adapter-reasoning-config.md b/.changeset/adapter-reasoning-config.md
new file mode 100644
index 0000000000..473256abca
--- /dev/null
+++ b/.changeset/adapter-reasoning-config.md
@@ -0,0 +1,20 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-anthropic': minor
+'@tanstack/ai-openai': minor
+'@tanstack/ai-gemini': minor
+'@tanstack/ai-bedrock': minor
+'@tanstack/ai-mistral': minor
+'@tanstack/ai-cloudflare': minor
+'@tanstack/ai-models': minor
+---
+
+Give an adapter the model's reasoning data in its config. A model id that is not in the adapter's own list (a gateway id, a new model, or a catalog id) got no reasoning field before. Now `reasoning?: ModelReasoning` in the config wins over the adapter's table, for the request fields and for the levels that `chat({ reasoning })` takes. `false` sends no reasoning field. Without it, nothing changes.
+
+The factories take any model id string: `anthropicText`, `createAnthropicChat`, `anthropicVertexText`, `openaiText`, `createOpenaiChat`, `azureOpenaiText`, `geminiText`, `createGeminiChat`, `createBedrockConverse`, `mistralText`, `createMistralText`, `cloudflareText`, and `createCloudflareText`. A misspelled id is no longer a type error.
+
+`@tanstack/ai-models` adds `modelReasoning(record)`, which turns a catalog record into the config value:
+
+```ts
+createAnthropicChat(record.id, apiKey, { reasoning: modelReasoning(record) })
+```
diff --git a/.changeset/ai-models-no-vertex-claude.md b/.changeset/ai-models-no-vertex-claude.md
new file mode 100644
index 0000000000..6adc44c716
--- /dev/null
+++ b/.changeset/ai-models-no-vertex-claude.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-models': patch
+---
+
+Leave the Claude models out of the `google-vertex` catalog. They had the Gemini wire (`api: 'google-vertex'`), which the Gemini adapter cannot call. Use `anthropicVertexText` from `@tanstack/ai-anthropic/vertex` for Claude on Vertex.
diff --git a/.changeset/model-cost-tiers.md b/.changeset/model-cost-tiers.md
new file mode 100644
index 0000000000..98d11b8396
--- /dev/null
+++ b/.changeset/model-cost-tiers.md
@@ -0,0 +1,10 @@
+---
+'@tanstack/ai-models': minor
+'@tanstack/ai-event-client': minor
+'@tanstack/ai-anthropic': patch
+'@tanstack/ai-bedrock': patch
+---
+
+Price long context and 1-hour cache writes in `modelCost`. A record's `cost.tiers` (from models.dev) holds higher prices above an input size, and a call uses the tier with the highest `inputTokensAbove` below its input. `TokenCounts.cacheWrite1h`, the part of `cacheWrite` with a 1-hour retention, costs 2 times the input price.
+
+Usage reports that part as `promptTokensDetails.cacheWrite1hTokens`. The Anthropic adapter reads it from `cache_creation.ephemeral_1h_input_tokens`, and the Bedrock Converse adapter from the 1-hour `cacheDetails`.
diff --git a/docs/adapters/openai.md b/docs/adapters/openai.md
index 161f6c526f..e6614bd4e4 100644
--- a/docs/adapters/openai.md
+++ b/docs/adapters/openai.md
@@ -426,6 +426,12 @@ const stream = chat({
 
 The adapter sends the level as `reasoning.effort`, with `summary: "auto"` so the reasoning summary streams back as thinking parts. Pass `reasoning: { level: "high", summary: false }` to skip the summary. The types list only the levels the model has. See [Reasoning](../chat/reasoning).
 
+For a model that this package does not list, pass the model's reasoning data as `reasoning` in the config. See [A model the adapter does not list](../chat/reasoning#a-model-the-adapter-does-not-list).
+
+### Answers on the next request
+
+OpenAI gives each answer item an `id` and a `phase`: `commentary` for text before a tool call, and `final_answer` for the answer. The adapter keeps both in the assistant message, in `metadata.tanstack.responseItems`. When the same model gets that message again, for example on the next turn, the adapter sends each item back with its `id` and `phase`. Another model gets the plain text.
+
 ### Prompt caching
 
 `chat()` sends `prompt_cache_key` by default, set to the `threadId` that you pass. OpenAI uses the key to send requests with the same start to the same cache. With `promptCache: 'long'`, `chat()` also asks for the long retention. See [Prompt Caching](../advanced/prompt-caching).
diff --git a/docs/advanced/prompt-caching.md b/docs/advanced/prompt-caching.md
index ccd1358662..12d8c825be 100644
--- a/docs/advanced/prompt-caching.md
+++ b/docs/advanced/prompt-caching.md
@@ -99,6 +99,8 @@ Claude bills the cache write. This applies to Claude on Anthropic, Bedrock, Vert
 
 The newest Claude models read from the cache for less. With `'short'`, the same start sent 2 times in 5 minutes already costs less than no cache. With `'long'`, it costs less from the third request.
 
+The usage of a call gives the 1-hour part of the cache write as `promptTokensDetails.cacheWrite1hTokens`, on Anthropic and Bedrock. To price it, see [Work out what a call cost](../models/catalog#work-out-what-a-call-cost).
+
 Two cases change the choice:
 
 - **A large prompt that you send one time.** For example, one long document per call that is never sent again. Nothing reads the cache, so the write is only extra cost. Use `'none'`.
diff --git a/docs/chat/reasoning.md b/docs/chat/reasoning.md
index 0a35725704..8739431742 100644
--- a/docs/chat/reasoning.md
+++ b/docs/chat/reasoning.md
@@ -88,6 +88,53 @@ const levels = model ? supportedReasoningLevels(model) : [];
 // ["low", "medium", "high", "xhigh", "max"]
 ```
 
+## A model the adapter does not list
+
+An adapter knows the levels of the models in its own list. A gateway id, a new model, or an id from a catalog is not in that list. For such a model, the adapter sends no reasoning field, and the types take no `reasoning` option.
+
+Give the adapter the model's reasoning data in its config. The factory takes any model id:
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { createAnthropicChat } from "@tanstack/ai-anthropic";
+
+const adapter = createAnthropicChat(
+  "anthropic/claude-sonnet-4.6",
+  process.env.AI_GATEWAY_API_KEY ?? "",
+  {
+    baseURL: "https://ai-gateway.vercel.sh",
+    reasoning: { map: { minimal: null, xhigh: null, max: "max" }, budget: true },
+  },
+);
+
+const stream = chat({
+  adapter,
+  messages: [{ role: "user", content: "Plan a database migration." }],
+  reasoning: "high",
+});
+```
+
+The `reasoning` config has the same shape on every adapter:
+
+- `false`: the model does not reason. No reasoning field goes out, and the types take no level.
+- `map`: the provider value for each level. `null` means that the model does not have the level. A level with no entry passes as its own name, except `xhigh` and `max`.
+- `budget`: `true` when the model thinks with a token budget.
+
+With `reasoning` in the config, the types take every level. The adapter moves a level that the model does not have to the nearest one, as in [A level from the user](#a-level-from-the-user). The config wins over the adapter's own data, also for a model in its list.
+
+These factories take the `reasoning` config:
+
+| Package | Factories |
+| --- | --- |
+| `@tanstack/ai-anthropic` | `anthropicText`, `createAnthropicChat`, `anthropicVertexText` |
+| `@tanstack/ai-openai` | `openaiText`, `createOpenaiChat`, `azureOpenaiText` |
+| `@tanstack/ai-gemini` | `geminiText`, `createGeminiChat`, also with `vertexai: true` |
+| `@tanstack/ai-bedrock` | `createBedrockConverse` |
+| `@tanstack/ai-mistral` | `mistralText`, `createMistralText` |
+| `@tanstack/ai-cloudflare` | `cloudflareText`, `createCloudflareText` |
+
+To build the config from a catalog record, see [Build an adapter from a record](../models/catalog#build-an-adapter-from-a-record).
+
 ## Change the level in middleware
 
 Middleware can set the level for a call, for example to lower it on a retry:
diff --git a/docs/config.json b/docs/config.json
index c2c54942c0..1a232750be 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -183,7 +183,8 @@
         {
           "label": "Reasoning",
           "to": "chat/reasoning",
-          "addedAt": "2026-09-30"
+          "addedAt": "2026-09-30",
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Message Queue",
@@ -337,7 +338,7 @@
           "label": "Prompt Caching",
           "to": "advanced/prompt-caching",
           "addedAt": "2026-10-02",
-          "updatedAt": "2026-10-02"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Mid-Conversation Changes",
@@ -1312,7 +1313,8 @@
         {
           "label": "Model Catalog",
           "to": "models/catalog",
-          "addedAt": "2026-09-30"
+          "addedAt": "2026-09-30",
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Typed Pre-Configured Options",
@@ -1341,7 +1343,7 @@
           "label": "OpenAI",
           "to": "adapters/openai",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-10-04"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Anthropic",
diff --git a/docs/models/catalog.md b/docs/models/catalog.md
index a60239f7be..d29359afff 100644
--- a/docs/models/catalog.md
+++ b/docs/models/catalog.md
@@ -56,9 +56,47 @@ const levels = model ? supportedReasoningLevels(model) : [];
 
 `clampReasoningLevel(model, level)` gives the level an adapter uses for a level the model does not have. Pass the level to [`chat({ reasoning })`](../chat/reasoning).
 
+## Build an adapter from a record
+
+A record says which wire API the model uses (`api`) and how it reasons. Many catalog ids, such as gateway ids, are not in the adapter's own model list. Pass `modelReasoning(record)` as the `reasoning` config, so the adapter sends the model's thinking fields:
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { createAnthropicChat } from "@tanstack/ai-anthropic";
+import { getModel, modelReasoning } from "@tanstack/ai-models";
+
+const record = getModel("vercel-ai-gateway", "anthropic/claude-sonnet-4.6");
+if (record) {
+  const adapter = createAnthropicChat(
+    record.id,
+    process.env.AI_GATEWAY_API_KEY ?? "",
+    { baseURL: record.baseUrl, reasoning: modelReasoning(record) },
+  );
+  const stream = chat({
+    adapter,
+    messages: [{ role: "user", content: "Hello" }],
+    reasoning: "high",
+  });
+}
+```
+
+Pick the adapter from the record's `api`:
+
+| `api` | Adapter |
+| --- | --- |
+| `anthropic-messages` | `createAnthropicChat` from `@tanstack/ai-anthropic` |
+| `openai-responses` | `createOpenaiChat` from `@tanstack/ai-openai` |
+| `azure-openai-responses` | `azureOpenaiText` from `@tanstack/ai-openai` |
+| `google-generative-ai`, `google-vertex` | `createGeminiChat` from `@tanstack/ai-gemini`, with `vertexai: true` for Vertex |
+| `bedrock-converse-stream` | `createBedrockConverse` from `@tanstack/ai-bedrock` |
+| `mistral-conversations` | `createMistralText` from `@tanstack/ai-mistral` |
+| `openai-completions` | `openaiCompatible` from `@tanstack/ai-openai`, see [OpenAI-Compatible](../adapters/openai-compatible) |
+
+The catalog has no Claude models under `google-vertex`, because Claude on Vertex uses the Anthropic wire. Use `anthropicVertexText` from `@tanstack/ai-anthropic/vertex` for them.
+
 ## Work out what a call cost
 
-Prices are in USD per million tokens. `modelCost` turns token counts into a cost:
+Prices are in USD per million tokens. `modelCost` turns token counts into a cost. `input` is the uncached input:
 
 ```typescript
 import { getModel, modelCost } from "@tanstack/ai-models";
@@ -70,6 +108,38 @@ if (model) {
 }
 ```
 
+`modelCost` also follows two price rules:
+
+- **Long context.** Some models cost more above an input size. The record lists these prices in `cost.tiers`. A call uses the tier with the highest `inputTokensAbove` below its input (uncached, plus cache reads, plus cache writes).
+- **1-hour cache writes.** `cacheWrite1h` is the part of `cacheWrite` that was written with a 1-hour retention. It costs 2 times the input price.
+
+To price each call of a chat, read its usage in middleware. Anthropic and Bedrock report the 1-hour part as `promptTokensDetails.cacheWrite1hTokens`:
+
+```typescript
+import type { ChatMiddleware } from "@tanstack/ai";
+import { getModel, modelCost } from "@tanstack/ai-models";
+
+const model = getModel("anthropic", "claude-sonnet-4-5-20250929");
+
+const logCost: ChatMiddleware = {
+  name: "log-cost",
+  onUsage(_ctx, usage) {
+    if (!model) return;
+    const details = usage.promptTokensDetails;
+    const cacheRead = details?.cachedTokens ?? 0;
+    const cacheWrite = details?.cacheWriteTokens ?? 0;
+    const cost = modelCost(model, {
+      input: usage.promptTokens - cacheRead - cacheWrite,
+      output: usage.completionTokens,
+      cacheRead,
+      cacheWrite,
+      cacheWrite1h: details?.cacheWrite1hTokens ?? 0,
+    });
+    console.log(cost.total.toFixed(4));
+  },
+};
+```
+
 ## Load one provider only
 
 The root import has every provider. To load only one, import its subpath:
diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index 69bb600408..d2a2396903 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -9,6 +9,7 @@
 // Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
 
 import { Route as rootRouteImport } from './routes/__root'
+import { Route as ApiAdapterConfigReasoningWireRouteImport } from './routes/api.adapter-config-reasoning-wire'
 import { Route as ApiActivityTestRouteImport } from './routes/api.activity-test'
 import { Route as ActivityTestRouteImport } from './routes/activity-test'
 import { Route as ApiForeignClientToolRouteImport } from './routes/api.foreign-client-tool'
@@ -154,6 +155,35 @@ import { Route as ApiImageStreamRouteImport } from './routes/api.image.stream'
 import { Route as ApiHarnessProtocolSplatRouteImport } from './routes/api.harness-protocol.$'
 import { Route as ApiAudioStreamRouteImport } from './routes/api.audio.stream'
 
+const ApiAdapterConfigReasoningWireRoute =
+  ApiAdapterConfigReasoningWireRouteImport.update({
+    id: '/api/adapter-config-reasoning-wire',
+    path: '/api/adapter-config-reasoning-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiAnthropicStructuredUsageRoute =
+  ApiAnthropicStructuredUsageRouteImport.update({
+    id: '/api/anthropic-structured-usage',
+    path: '/api/anthropic-structured-usage',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiAnthropicThinkingOrderWireRoute =
+  ApiAnthropicThinkingOrderWireRouteImport.update({
+    id: '/api/anthropic-thinking-order-wire',
+    path: '/api/anthropic-thinking-order-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiAnthropicTruncatedToolInputWireRoute =
+  ApiAnthropicTruncatedToolInputWireRouteImport.update({
+    id: '/api/anthropic-truncated-tool-input-wire',
+    path: '/api/anthropic-truncated-tool-input-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiArktypeToolWireRoute = ApiArktypeToolWireRouteImport.update({
+  id: '/api/arktype-tool-wire',
+  path: '/api/arktype-tool-wire',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiActivityTestRoute = ApiActivityTestRouteImport.update({
   id: '/api/activity-test',
   path: '/api/activity-test',
@@ -962,6 +992,7 @@ const ApiAudioStreamRoute = ApiAudioStreamRouteImport.update({
 } as any)
 
 export interface FileRoutesByFullPath {
+  '/api/adapter-config-reasoning-wire': typeof ApiAdapterConfigReasoningWireRoute
   '/api/activity-test': typeof ApiActivityTestRoute
   '/activity-test': typeof ActivityTestRoute
   '/api/foreign-client-tool': typeof ApiForeignClientToolRoute
@@ -1108,6 +1139,7 @@ export interface FileRoutesByFullPath {
   '/api/video/stream': typeof ApiVideoStreamRoute
 }
 export interface FileRoutesByTo {
+  '/api/adapter-config-reasoning-wire': typeof ApiAdapterConfigReasoningWireRoute
   '/api/activity-test': typeof ApiActivityTestRoute
   '/activity-test': typeof ActivityTestRoute
   '/api/foreign-client-tool': typeof ApiForeignClientToolRoute
@@ -1254,6 +1286,7 @@ export interface FileRoutesByTo {
   '/api/video/stream': typeof ApiVideoStreamRoute
 }
 export interface FileRoutesById {
+  '/api/adapter-config-reasoning-wire': typeof ApiAdapterConfigReasoningWireRoute
   '/api/activity-test': typeof ApiActivityTestRoute
   '/activity-test': typeof ActivityTestRoute
   '/api/foreign-client-tool': typeof ApiForeignClientToolRoute
@@ -1403,6 +1436,7 @@ export interface FileRoutesById {
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
   fullPaths:
+    | '/api/adapter-config-reasoning-wire'
     | '/api/activity-test'
     | '/activity-test'
     | '/api/foreign-client-tool'
@@ -1549,6 +1583,7 @@ export interface FileRouteTypes {
     | '/api/video/stream'
   fileRoutesByTo: FileRoutesByTo
   to:
+    | '/api/adapter-config-reasoning-wire'
     | '/api/activity-test'
     | '/activity-test'
     | '/api/foreign-client-tool'
@@ -1694,6 +1729,7 @@ export interface FileRouteTypes {
     | '/api/tts/stream'
     | '/api/video/stream'
   id:
+    | '/api/adapter-config-reasoning-wire'
     | '/api/activity-test'
     | '/activity-test'
     | '/api/foreign-client-tool'
@@ -1842,6 +1878,7 @@ export interface FileRouteTypes {
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
+  ApiAdapterConfigReasoningWireRoute: typeof ApiAdapterConfigReasoningWireRoute
   ApiActivityTestRoute: typeof ApiActivityTestRoute
   ActivityTestRoute: typeof ActivityTestRoute
   ApiForeignClientToolRoute: typeof ApiForeignClientToolRoute
@@ -1985,6 +2022,13 @@ export interface RootRouteChildren {
 
 declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
+    '/api/adapter-config-reasoning-wire': {
+      id: '/api/adapter-config-reasoning-wire'
+      path: '/api/adapter-config-reasoning-wire'
+      fullPath: '/api/adapter-config-reasoning-wire'
+      preLoaderRoute: typeof ApiAdapterConfigReasoningWireRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/activity-test': {
       id: '/api/activity-test'
       path: '/api/activity-test'
@@ -3055,6 +3099,7 @@ const ApiVideoRouteWithChildren = ApiVideoRoute._addFileChildren(
 )
 
 const rootRouteChildren: RootRouteChildren = {
+  ApiAdapterConfigReasoningWireRoute: ApiAdapterConfigReasoningWireRoute,
   ApiActivityTestRoute: ApiActivityTestRoute,
   ActivityTestRoute: ActivityTestRoute,
   ApiForeignClientToolRoute: ApiForeignClientToolRoute,
diff --git a/testing/e2e/src/routes/api.adapter-config-reasoning-wire.ts b/testing/e2e/src/routes/api.adapter-config-reasoning-wire.ts
new file mode 100644
index 0000000000..3541f55842
--- /dev/null
+++ b/testing/e2e/src/routes/api.adapter-config-reasoning-wire.ts
@@ -0,0 +1,130 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { chat } from '@tanstack/ai'
+import { createAnthropicChat } from '@tanstack/ai-anthropic'
+import type { ModelReasoning } from '@tanstack/ai'
+
+const DUMMY_KEY = 'sk-ant-e2e-test-dummy-key'
+
+/** A gateway id that the Anthropic adapter does not list. */
+const GATEWAY_MODEL = 'anthropic/claude-sonnet-4.6'
+
+/** The reasoning data of its catalog record (budget thinking). */
+const RECORD_REASONING: ModelReasoning = {
+  map: { minimal: null, xhigh: null, max: 'max' },
+  budget: true,
+}
+
+/**
+ * Wire-format verification for the `reasoning` config of an adapter.
+ *
+ * The route runs `chat({ reasoning: 'high' })` two times on a model id that
+ * the Anthropic adapter does not list: once with the record's reasoning data
+ * in the config, once with `reasoning: false`. A custom `fetch` records each
+ * Messages request and answers with a synthetic Claude stream, the same
+ * approach as `api.anthropic-sonnet-5-5-wire.ts`.
+ */
+function makeSyntheticAnthropicStream(): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder()
+  const events = [
+    {
+      type: 'message_start',
+      message: {
+        id: 'msg_config_reasoning_wire',
+        type: 'message',
+        role: 'assistant',
+        content: [],
+        model: GATEWAY_MODEL,
+        stop_reason: null,
+        stop_sequence: null,
+        usage: { input_tokens: 5, output_tokens: 0 },
+      },
+    },
+    {
+      type: 'content_block_start',
+      index: 0,
+      content_block: { type: 'text', text: '' },
+    },
+    {
+      type: 'content_block_delta',
+      index: 0,
+      delta: { type: 'text_delta', text: 'Done.' },
+    },
+    { type: 'content_block_stop', index: 0 },
+    {
+      type: 'message_delta',
+      delta: { stop_reason: 'end_turn', stop_sequence: null },
+      usage: { output_tokens: 2 },
+    },
+    { type: 'message_stop' },
+  ]
+
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      for (const event of events) {
+        controller.enqueue(
+          encoder.encode(
+            `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`,
+          ),
+        )
+      }
+      controller.close()
+    },
+  })
+}
+
+export const Route = createFileRoute('/api/adapter-config-reasoning-wire')({
+  server: {
+    handlers: {
+      POST: async () => {
+        const capturedRequests: Array<Record<string, unknown> | null> = []
+
+        /** Records the outgoing request and answers with the synthetic stream. */
+        const capturingFetch: typeof fetch = async (input, init) => {
+          const req =
+            input instanceof Request ? input : new Request(input, init)
+          const rawBody = await req.text()
+          capturedRequests.push(
+            rawBody ? (JSON.parse(rawBody) as Record<string, unknown>) : null,
+          )
+          return new Response(makeSyntheticAnthropicStream(), {
+            status: 200,
+            headers: {
+              'Content-Type': 'text/event-stream',
+              'Cache-Control': 'no-cache',
+            },
+          })
+        }
+
+        try {
+          for await (const _ of chat({
+            adapter: createAnthropicChat(GATEWAY_MODEL, DUMMY_KEY, {
+              fetch: capturingFetch,
+              reasoning: RECORD_REASONING,
+            }),
+            messages: [{ role: 'user', content: '[config-reasoning] plan it' }],
+            reasoning: 'high',
+          })) {
+            // Drain the stream.
+          }
+          for await (const _ of chat({
+            adapter: createAnthropicChat(GATEWAY_MODEL, DUMMY_KEY, {
+              fetch: capturingFetch,
+              reasoning: false,
+            }),
+            messages: [{ role: 'user', content: '[config-reasoning] plan it' }],
+          })) {
+            // Drain the stream.
+          }
+        } catch (error) {
+          return Response.json({
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+            capturedRequests,
+          })
+        }
+
+        return Response.json({ ok: true, capturedRequests })
+      },
+    },
+  },
+})
diff --git a/testing/e2e/tests/adapter-config-reasoning-wire.spec.ts b/testing/e2e/tests/adapter-config-reasoning-wire.spec.ts
new file mode 100644
index 0000000000..9285fd4c62
--- /dev/null
+++ b/testing/e2e/tests/adapter-config-reasoning-wire.spec.ts
@@ -0,0 +1,37 @@
+import { test, expect } from './fixtures'
+
+/**
+ * Wire-format verification for the `reasoning` config of an adapter.
+ *
+ * `/api/adapter-config-reasoning-wire` runs `chat()` on
+ * `anthropic/claude-sonnet-4.6`, a gateway id that the Anthropic adapter does
+ * not list. With the record's reasoning data in the config, the request
+ * carries a thinking budget. With `reasoning: false`, it carries none.
+ */
+type WireResponse = {
+  ok: boolean
+  error?: string
+  capturedRequests: Array<Record<string, unknown> | null>
+}
+
+test.describe('adapter reasoning config wire format', () => {
+  test('a model id outside the adapter list gets thinking from the config', async ({
+    request,
+  }) => {
+    const res = await request.post('/api/adapter-config-reasoning-wire')
+    expect(res.ok()).toBe(true)
+    const payload = (await res.json()) as WireResponse
+    expect(payload.error).toBeUndefined()
+    expect(payload.ok).toBe(true)
+
+    expect(payload.capturedRequests).toHaveLength(2)
+    const [withRecord, withFalse] = payload.capturedRequests
+    expect(withRecord?.['model']).toBe('anthropic/claude-sonnet-4.6')
+    expect(withRecord?.['thinking']).toEqual({
+      type: 'enabled',
+      budget_tokens: 16384,
+    })
+    expect(withFalse).not.toHaveProperty('thinking')
+    expect(withFalse).not.toHaveProperty('output_config')
+  })
+})

From 280263df45901889e3e3aabc0ee5dfbfb4a030b6 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 14:54:57 +0200
Subject: [PATCH 245/286] test(e2e): expect the failed-message mark on a chunk
 before RUN_ERROR

The foreign *_CHUNK spec from main expected only the sender's metadata
on a message that ends in RUN_ERROR. This branch also marks that message
with `tanstack.stopReason: 'error'`, so a replay leaves the failed batch
out. The sender's metadata is still there.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 testing/e2e/tests/foreign-chunk-events.spec.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/testing/e2e/tests/foreign-chunk-events.spec.ts b/testing/e2e/tests/foreign-chunk-events.spec.ts
index e3e918f239..e649d2867a 100644
--- a/testing/e2e/tests/foreign-chunk-events.spec.ts
+++ b/testing/e2e/tests/foreign-chunk-events.spec.ts
@@ -29,8 +29,9 @@ test.describe('AG-UI *_CHUNK events from a foreign server', () => {
 
     const message = page.getByTestId('message-msg-error')
     await expect(message.getByTestId('text')).toHaveText('the run failed')
+    // RUN_ERROR also marks the message as failed, so a replay leaves it out.
     await expect(message.getByTestId('metadata')).toHaveText(
-      '{"error":"upstream timeout"}',
+      '{"error":"upstream timeout","tanstack":{"stopReason":"error"}}',
     )
   })
 })

From 1a6241de740e7ac325982a04073cf92ec2319a44 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 14:59:03 +0200
Subject: [PATCH 246/286] feat: send toolChoice from every provider, and add
 the mcp() harness plugin

Checkpoint 4 of the opencode primitives plan.

- toolChoice reaches the wire in the OpenAI-compatible providers, Bedrock
  Converse, Gemini, Mistral, and OpenRouter. A tool choice in modelOptions
  wins. Claude 5.x models, and older Claude models with thinking on, get
  auto for a forced choice on Anthropic and on Bedrock.
- mcp() harness plugin in @tanstack/ai-mcp/harness (PL7). Code mode moves
  a tool only when the permission rules allow it and it declares no
  permission resources.
- ctx.collect() gives a view that works with every array method. Before,
  filter and some saw no items, so code mode missed ask and deny rules.
- The plugins and plugins/coding entries export the new plugins.
  PermissionResources is in the core entry. Sandbox paths stay POSIX in
  read, bash, and formatter. webfetch asks before it runs by default.
- sandboxWorkspaceBackend() for @tanstack/ai-sandbox (C7).
- Test fixes: projectInstructions fakes git through hostBackend.exec, and
  the view test counts only the view's own snapshot reads.
- Text fixes: code mode keeps bash, not run_command; serveAcp does not
  send config options yet.
---
 docs/harness/code-mode.md                     |   2 +-
 packages/ai-anthropic/src/adapters/text.ts    |  51 +-
 .../tests/tool-choice-wire.test.ts            | 152 ++++++
 .../ai-bedrock/src/adapters/converse-text.ts  |  34 +-
 .../ai-bedrock/tests/tool-choice-wire.test.ts | 284 +++++++++++
 .../tests/tool-choice-wire.test.ts            |  77 +++
 .../tests/tool-choice-wire.test.ts            |  81 ++++
 packages/ai-code-mode/src/harness.ts          |  34 +-
 packages/ai-code-mode/tests/harness.test.ts   |  83 +++-
 packages/ai-gemini/src/adapters/text.ts       |  36 +-
 .../ai-gemini/tests/tool-choice-wire.test.ts  | 151 ++++++
 packages/ai-grok/src/adapters/text.ts         |  14 +-
 .../ai-grok/tests/tool-choice-wire.test.ts    | 106 ++++
 .../ai-groq/tests/tool-choice-wire.test.ts    |  77 +++
 packages/ai-harness/src/config.ts             |  10 +-
 .../ai-harness/src/first-party/coding/bash.ts |   4 +-
 .../src/first-party/coding/formatter.ts       |  12 +-
 .../src/first-party/coding/index.ts           |   9 +
 .../ai-harness/src/first-party/coding/read.ts |   4 +-
 .../src/first-party/coding/search.ts          |   2 +-
 .../src/first-party/coding/snapshots.ts       |   6 +-
 .../ai-harness/src/first-party/coding/web.ts  | 134 ++++-
 .../src/first-party/coding/workspace.ts       |  17 +-
 packages/ai-harness/src/first-party/index.ts  |   5 +
 packages/ai-harness/src/index.ts              |  10 +-
 packages/ai-harness/src/plugins.ts            |  15 +-
 packages/ai-harness/tests/coding-bash.test.ts |  13 +-
 .../ai-harness/tests/coding-formatter.test.ts |  42 +-
 packages/ai-harness/tests/coding-read.test.ts |  50 +-
 .../ai-harness/tests/coding-snapshots.test.ts |  57 ++-
 packages/ai-harness/tests/coding-web.test.ts  |  73 ++-
 packages/ai-harness/tests/extensions.test.ts  |  54 +++
 .../ai-harness/tests/instructions.test.ts     |  40 +-
 packages/ai-harness/tests/view.test.ts        |  16 +-
 .../ai-harness/tests/workspace-tools.test.ts  |  51 ++
 .../tests/tool-choice-wire.test.ts            |  77 +++
 .../ai-lovable/tests/tool-choice-wire.test.ts | 101 ++++
 packages/ai-mcp/skills/ai-mcp/SKILL.md        |  63 ++-
 packages/ai-mcp/src/harness-plugin.ts         | 246 ++++++++++
 packages/ai-mcp/src/harness.ts                |   3 +
 packages/ai-mcp/tests/harness-plugin.test.ts  | 210 ++++++++
 packages/ai-mistral/src/adapters/text.ts      |  17 +
 .../ai-mistral/tests/tool-choice-wire.test.ts |  91 ++++
 .../ai-openai/tests/tool-choice-wire.test.ts  | 147 ++++++
 .../src/adapters/responses-text.ts            |  17 +
 packages/ai-openrouter/src/adapters/text.ts   |  17 +
 .../tests/tool-choice-wire.test.ts            | 106 ++++
 packages/ai-sandbox/src/harness.ts            |   2 +
 packages/ai-sandbox/src/workspace-backend.ts  | 150 ++++++
 .../tests/workspace-backend.test.ts           | 456 ++++++++++++++++++
 .../tests/tool-choice-wire.test.ts            | 101 ++++
 .../src/adapters/chat-completions-text.ts     |   9 +
 .../src/adapters/responses-text.ts            |   9 +
 packages/openai-base/src/tools/index.ts       |   6 +-
 packages/openai-base/src/tools/tool-choice.ts |  20 +
 .../tests/tool-choice-wire.test.ts            | 115 +++++
 56 files changed, 3624 insertions(+), 145 deletions(-)
 create mode 100644 packages/ai-anthropic/tests/tool-choice-wire.test.ts
 create mode 100644 packages/ai-bedrock/tests/tool-choice-wire.test.ts
 create mode 100644 packages/ai-byteplus/tests/tool-choice-wire.test.ts
 create mode 100644 packages/ai-cloudflare/tests/tool-choice-wire.test.ts
 create mode 100644 packages/ai-gemini/tests/tool-choice-wire.test.ts
 create mode 100644 packages/ai-grok/tests/tool-choice-wire.test.ts
 create mode 100644 packages/ai-groq/tests/tool-choice-wire.test.ts
 create mode 100644 packages/ai-llmgateway/tests/tool-choice-wire.test.ts
 create mode 100644 packages/ai-lovable/tests/tool-choice-wire.test.ts
 create mode 100644 packages/ai-mcp/src/harness-plugin.ts
 create mode 100644 packages/ai-mcp/tests/harness-plugin.test.ts
 create mode 100644 packages/ai-mistral/tests/tool-choice-wire.test.ts
 create mode 100644 packages/ai-openai/tests/tool-choice-wire.test.ts
 create mode 100644 packages/ai-openrouter/tests/tool-choice-wire.test.ts
 create mode 100644 packages/ai-sandbox/src/workspace-backend.ts
 create mode 100644 packages/ai-sandbox/tests/workspace-backend.test.ts
 create mode 100644 packages/ai-vercel-gateway/tests/tool-choice-wire.test.ts
 create mode 100644 packages/openai-base/tests/tool-choice-wire.test.ts

diff --git a/docs/harness/code-mode.md b/docs/harness/code-mode.md
index 8f93c89e93..b3c962a9a4 100644
--- a/docs/harness/code-mode.md
+++ b/docs/harness/code-mode.md
@@ -71,7 +71,7 @@ The model now has an `execute_typescript` tool. Inside the program, each moved t
 A call inside the program does not stop for approval. So by default, a tool moves into code mode only when it is safe to run without a question:
 
 - The tool runs on the server and does not set `needsApproval`.
-- The permission rules allow it in plan mode. File reads move. `write_file` and `run_command` stay.
+- The permission rules allow it in plan mode. File reads move. `write_file` and `bash` stay.
 - MCP tools that the server does not mark read-only ask for approval, so they stay too.
 
 Every other tool stays a normal tool call, with its approvals. To pick the tools yourself, pass `include`:
diff --git a/packages/ai-anthropic/src/adapters/text.ts b/packages/ai-anthropic/src/adapters/text.ts
index 7a39010f78..9aec854202 100644
--- a/packages/ai-anthropic/src/adapters/text.ts
+++ b/packages/ai-anthropic/src/adapters/text.ts
@@ -85,6 +85,7 @@ import type {
   NormalizedSystemPrompt,
   TextOptions,
   ToolCall,
+  ToolChoice,
 } from '@tanstack/ai'
 import type {
   AnthropicSystemPromptMetadata,
@@ -276,6 +277,30 @@ export function computeAnthropicBetas(
   return betas.size > 0 ? Array.from(betas) : undefined
 }
 
+/**
+ * The models that reject a forced tool (`any` or a named `tool`) on every
+ * request, with or without thinking.
+ * ponytail: a hand list, because the model sync script writes model-meta.ts.
+ * Move it to a model-meta capability when that script can set one.
+ */
+const ANTHROPIC_NO_FORCED_TOOL_MODELS = new Set<
+  (typeof ANTHROPIC_MODELS)[number]
+>(['claude-fable-5-1', 'claude-opus-5-5', 'claude-sonnet-5-5'])
+
+/**
+ * Maps `chat({ toolChoice })` to the Messages `tool_choice`. When the
+ * request cannot force a tool, a forced choice falls back to `auto`.
+ */
+function toAnthropicToolChoice(
+  choice: ToolChoice,
+  { canForceTool }: { canForceTool: boolean },
+) {
+  if (choice === 'none') return { type: 'none' as const }
+  if (choice === 'auto' || !canForceTool) return { type: 'auto' as const }
+  if (choice === 'required') return { type: 'any' as const }
+  return { type: 'tool' as const, name: choice.name }
+}
+
 /**
  * The tool placeholder of mid-conversation tool mode, copied from pi 0.87.1.
  * Anthropic adds hidden scaffolding once any tool has `defer_loading`. This
@@ -977,8 +1002,30 @@ export class AnthropicTextAdapter<
       ...(outputConfig ?? {}),
     }
     validateTextProviderOptions(requestParams)
-    // Last step: the merged messages decide which message is last.
-    return applyAnthropicPromptCache(requestParams, options.promptCache)
+
+    // `chat({ toolChoice })` is sent only when the request has tools. It goes
+    // before the request spread, so a `tool_choice` in modelOptions wins. It
+    // is not in `requestParams`, because that type has no `none` choice.
+    // The API rejects a forced tool while thinking is on, and some models
+    // reject it on every request.
+    const isThinking =
+      thinkingFields.thinking !== undefined &&
+      thinkingFields.thinking.type !== 'disabled'
+    const canForceTool =
+      !isThinking && !ANTHROPIC_NO_FORCED_TOOL_MODELS.has(this.model)
+    const toolChoiceField =
+      tools?.length && options.toolChoice !== undefined
+        ? {
+            tool_choice: toAnthropicToolChoice(options.toolChoice, {
+              canForceTool,
+            }),
+          }
+        : undefined
+    return {
+      ...toolChoiceField,
+      // Last step: the merged messages decide which message is last.
+      ...applyAnthropicPromptCache(requestParams, options.promptCache),
+    }
   }
 
   /**
diff --git a/packages/ai-anthropic/tests/tool-choice-wire.test.ts b/packages/ai-anthropic/tests/tool-choice-wire.test.ts
new file mode 100644
index 0000000000..c1f0d3ba6a
--- /dev/null
+++ b/packages/ai-anthropic/tests/tool-choice-wire.test.ts
@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { createAnthropicChat } from '../src/adapters/text'
+import type { TextOptions, Tool, ToolChoice } from '@tanstack/ai'
+import type { AnthropicChatModel } from '../src/model-meta'
+import type { AnthropicToolChoiceOptions } from '../src/text/text-provider-options'
+
+const logger = resolveDebugOption(false)
+// Takes a forced tool, and can turn thinking on and off.
+const haiku = 'claude-haiku-4-5'
+// Rejects a forced tool on every request.
+const opus = 'claude-opus-5-5'
+
+const weatherTool: Tool = {
+  name: 'lookup_weather',
+  description: 'Return the forecast for a location',
+}
+
+const sse = [
+  {
+    type: 'content_block_start',
+    index: 0,
+    content_block: { type: 'text', text: '' },
+  },
+  {
+    type: 'content_block_delta',
+    index: 0,
+    delta: { type: 'text_delta', text: 'Done' },
+  },
+  { type: 'content_block_stop', index: 0 },
+  {
+    type: 'message_delta',
+    delta: { stop_reason: 'end_turn' },
+    usage: { output_tokens: 1 },
+  },
+  { type: 'message_stop' },
+]
+  .map((event) => `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`)
+  .join('')
+
+let lastBody: unknown
+const captureFetch: typeof globalThis.fetch = async (input, init) => {
+  lastBody = await new Request(input, init).json()
+  return new Response(sse, {
+    headers: { 'content-type': 'text/event-stream' },
+  })
+}
+
+type CallOptions = Pick<
+  TextOptions<AnthropicToolChoiceOptions>,
+  'tools' | 'toolChoice' | 'modelOptions' | 'reasoning'
+>
+
+/** Runs one streaming call and returns the JSON body sent over HTTP. */
+async function sentBody(model: AnthropicChatModel, options: CallOptions) {
+  lastBody = undefined
+  const adapter = createAnthropicChat(model, 'test-key', {
+    fetch: captureFetch,
+  })
+  for await (const _ of adapter.chatStream({
+    logger,
+    model,
+    messages: [{ role: 'user', content: 'Weather in Paris?' }],
+    ...options,
+  })) {
+    // drain
+  }
+  return lastBody
+}
+
+interface Row {
+  label: string
+  toolChoice: ToolChoice
+  expected: object
+}
+
+const named: ToolChoice = { type: 'tool', name: 'lookup_weather' }
+
+const shapes: Array<Row> = [
+  { label: 'auto', toolChoice: 'auto', expected: { type: 'auto' } },
+  { label: 'none', toolChoice: 'none', expected: { type: 'none' } },
+  { label: 'required', toolChoice: 'required', expected: { type: 'any' } },
+  {
+    label: 'a named tool',
+    toolChoice: named,
+    expected: { type: 'tool', name: 'lookup_weather' },
+  },
+]
+
+const thinkingShapes: Array<Row> = [
+  { label: 'required', toolChoice: 'required', expected: { type: 'auto' } },
+  { label: 'a named tool', toolChoice: named, expected: { type: 'auto' } },
+  { label: 'none', toolChoice: 'none', expected: { type: 'none' } },
+]
+
+const noForcedToolShapes: Array<Row> = [
+  { label: 'required', toolChoice: 'required', expected: { type: 'auto' } },
+  { label: 'none', toolChoice: 'none', expected: { type: 'none' } },
+]
+
+describe('Anthropic tool_choice', () => {
+  it.each(shapes)('sends $label', async ({ toolChoice, expected }) => {
+    const body = await sentBody(haiku, { tools: [weatherTool], toolChoice })
+    expect(body).toHaveProperty('tool_choice', expected)
+  })
+
+  it('lets a tool_choice in modelOptions win', async () => {
+    const body = await sentBody(haiku, {
+      tools: [weatherTool],
+      toolChoice: 'required',
+      modelOptions: { tool_choice: { type: 'auto' } },
+    })
+    expect(body).toHaveProperty('tool_choice', { type: 'auto' })
+  })
+
+  it('sends no tool_choice when the request has no tools', async () => {
+    const body = await sentBody(haiku, { toolChoice: 'required' })
+    expect(body).not.toHaveProperty('tool_choice')
+  })
+
+  it.each(thinkingShapes)(
+    'with thinking on, sends $label without forcing a tool',
+    async ({ toolChoice, expected }) => {
+      const body = await sentBody(haiku, {
+        tools: [weatherTool],
+        toolChoice,
+        reasoning: { level: 'high', summary: false },
+      })
+      expect(body).toHaveProperty('thinking.type', 'enabled')
+      expect(body).toHaveProperty('tool_choice', expected)
+    },
+  )
+
+  it('with thinking off, still forces the tool', async () => {
+    const body = await sentBody(haiku, {
+      tools: [weatherTool],
+      toolChoice: 'required',
+      reasoning: { level: 'off', summary: false },
+    })
+    expect(body).toHaveProperty('thinking', { type: 'disabled' })
+    expect(body).toHaveProperty('tool_choice', { type: 'any' })
+  })
+
+  it.each(noForcedToolShapes)(
+    'on a model that cannot force a tool, sends $label without forcing',
+    async ({ toolChoice, expected }) => {
+      const body = await sentBody(opus, { tools: [weatherTool], toolChoice })
+      expect(body).not.toHaveProperty('thinking')
+      expect(body).toHaveProperty('tool_choice', expected)
+    },
+  )
+})
diff --git a/packages/ai-bedrock/src/adapters/converse-text.ts b/packages/ai-bedrock/src/adapters/converse-text.ts
index 7f755b8083..12b520a641 100644
--- a/packages/ai-bedrock/src/adapters/converse-text.ts
+++ b/packages/ai-bedrock/src/adapters/converse-text.ts
@@ -54,6 +54,20 @@ import type {
   ResolveInputModalities,
 } from '../model-meta'
 
+/**
+ * The Claude models that reject a forced tool (`any` or a named `tool`) on
+ * every request, with or without thinking. A Bedrock id has the family name
+ * inside it, for example `us.anthropic.claude-opus-5-5-...`.
+ * ponytail: a hand list, the same as the Anthropic adapter. Move it to the
+ * model catalog when the catalog script can set it.
+ */
+const CLAUDE_NO_FORCED_TOOL_MODELS = [
+  'claude-fable-5-1',
+  'claude-mythos-5-1',
+  'claude-opus-5-5',
+  'claude-sonnet-5-5',
+]
+
 /** Config for the Converse adapter — same client config as the chat adapter. */
 export interface BedrockConverseConfig extends BedrockClientConfig {}
 
@@ -791,10 +805,6 @@ export class BedrockConverseTextAdapter<
       },
     )
 
-    const toolConfig = options.tools
-      ? toToolConfig(convertTools(options.tools), 'auto')
-      : undefined
-
     // Sampling options live on `modelOptions` (typed as the narrowed
     // `BedrockConverseProviderOptions`, which surfaces the OpenAI Chat
     // Completions field names); translate them into Converse's `inferenceConfig`,
@@ -809,6 +819,22 @@ export class BedrockConverseTextAdapter<
       options.reasoning,
       BEDROCK_MODEL_REASONING[this.model],
     )
+
+    // `chat({ toolChoice })`. Converse has no `none` choice, so `none` sends
+    // no tool config. Claude rejects a forced tool while thinking is on (only
+    // Claude gets thinking fields), and some Claude models reject it on every
+    // request. Then a forced choice falls back to auto.
+    const canForceTool =
+      additionalModelRequestFields === undefined &&
+      !CLAUDE_NO_FORCED_TOOL_MODELS.some((name) => this.model.includes(name))
+    const toolChoice =
+      canForceTool || options.toolChoice === 'none'
+        ? options.toolChoice
+        : 'auto'
+    const toolConfig = options.tools
+      ? toToolConfig(convertTools(options.tools), toolChoice)
+      : undefined
+
     const requestedMaxTokens = modelOptions?.max_completion_tokens
     const maxTokens =
       minMaxTokens !== undefined &&
diff --git a/packages/ai-bedrock/tests/tool-choice-wire.test.ts b/packages/ai-bedrock/tests/tool-choice-wire.test.ts
new file mode 100644
index 0000000000..7ed5f5d125
--- /dev/null
+++ b/packages/ai-bedrock/tests/tool-choice-wire.test.ts
@@ -0,0 +1,284 @@
+import { describe, expect, it } from 'vitest'
+import { BedrockRuntimeClient } from '@aws-sdk/client-bedrock-runtime'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { BedrockConverseTextAdapter } from '../src/adapters/converse-text'
+import { createBedrockChat } from '../src/adapters/text'
+import { createBedrockResponsesText } from '../src/adapters/responses-text'
+import type { ModelMessage, TextOptions, Tool, ToolChoice } from '@tanstack/ai'
+
+const logger = resolveDebugOption(false)
+const messages: Array<ModelMessage> = [
+  { role: 'user', content: 'Weather in Paris?' },
+]
+const weatherTool: Tool = {
+  name: 'lookup_weather',
+  description: 'Return the forecast for a location',
+}
+const named: ToolChoice = { type: 'tool', name: 'lookup_weather' }
+const forcedChoices: Array<{ label: string; toolChoice: ToolChoice }> = [
+  { label: 'required', toolChoice: 'required' },
+  { label: 'a named tool', toolChoice: named },
+]
+
+// Not Claude: takes a forced tool.
+const nova = 'us.amazon.nova-pro-v1:0'
+// Older Claude: takes a forced tool, and thinks when `reasoning` asks for it.
+const sonnet45 = 'us.anthropic.claude-sonnet-4-5-20250929-v1:0'
+// Claude models that reject a forced tool on every request, in the id shapes
+// Bedrock uses (plain, regional, and global inference profiles).
+const noForcedToolModels = [
+  'anthropic.claude-opus-5-5-v1:0',
+  'us.anthropic.claude-sonnet-5-5-v1:0',
+  'global.anthropic.claude-fable-5-1-v1:0',
+  'eu.anthropic.claude-mythos-5-1-v1:0',
+]
+
+type ConverseRequest = Pick<TextOptions, 'tools' | 'toolChoice' | 'reasoning'>
+
+/**
+ * Runs one Converse stream call through the installed AWS SDK and returns the
+ * model id and the JSON body that the SDK sent over HTTP.
+ */
+async function converseRequest(model: string, request: ConverseRequest) {
+  let path = ''
+  let body: unknown
+  const client = new BedrockRuntimeClient({
+    region: 'us-east-1',
+    maxAttempts: 1,
+    credentials: { accessKeyId: 'test', secretAccessKey: 'test' },
+    requestHandler: {
+      async handle(sent: { body?: unknown; path: string }) {
+        path = sent.path
+        body = JSON.parse(String(sent.body))
+        throw new Error('Transport probe complete')
+      },
+    },
+  })
+  class WireAdapter extends BedrockConverseTextAdapter<typeof nova> {
+    protected override async getClient(): Promise<BedrockRuntimeClient> {
+      return client
+    }
+  }
+  const adapter = new WireAdapter({ apiKey: 'test-key' }, nova)
+  // The adapter type takes only catalog ids, and the Claude 5.x models are
+  // not in the Bedrock catalog yet. So the test sets the id at runtime.
+  Object.defineProperty(adapter, 'model', { value: model })
+  try {
+    for await (const _ of adapter.chatStream({
+      logger,
+      model,
+      messages,
+      ...request,
+    })) {
+      // drain: the probe ends the call with RUN_ERROR
+    }
+  } finally {
+    client.destroy()
+  }
+  return { modelId: decodeURIComponent(path.split('/')[2] ?? ''), body }
+}
+
+async function converseBody(model: string, request: ConverseRequest) {
+  return (await converseRequest(model, request)).body
+}
+
+interface Row {
+  label: string
+  toolChoice: ToolChoice
+  expected: object
+}
+
+const forcedShapes: Array<Row> = [
+  { label: 'auto', toolChoice: 'auto', expected: { auto: {} } },
+  { label: 'required', toolChoice: 'required', expected: { any: {} } },
+  {
+    label: 'a named tool',
+    toolChoice: named,
+    expected: { tool: { name: 'lookup_weather' } },
+  },
+]
+
+describe('Bedrock Converse toolChoice', () => {
+  it.each(forcedShapes)(
+    'sends $label on a model that is not Claude',
+    async ({ toolChoice, expected }) => {
+      const body = await converseBody(nova, {
+        tools: [weatherTool],
+        toolChoice,
+      })
+      expect(body).toHaveProperty('toolConfig.toolChoice', expected)
+      expect(body).toHaveProperty(
+        'toolConfig.tools.0.toolSpec.name',
+        'lookup_weather',
+      )
+    },
+  )
+
+  it('sends auto when the request sets no toolChoice', async () => {
+    const body = await converseBody(nova, { tools: [weatherTool] })
+    expect(body).toHaveProperty('toolConfig.toolChoice', { auto: {} })
+  })
+
+  it('sends no tools and no toolConfig for none', async () => {
+    const body = await converseBody(nova, {
+      tools: [weatherTool],
+      toolChoice: 'none',
+    })
+    expect(body).toHaveProperty('messages')
+    expect(body).not.toHaveProperty('toolConfig')
+  })
+
+  it('sends no toolConfig when the request has no tools', async () => {
+    const body = await converseBody(nova, { toolChoice: 'required' })
+    expect(body).toHaveProperty('messages')
+    expect(body).not.toHaveProperty('toolConfig')
+  })
+
+  it('forces the tool on an older Claude model with thinking off', async () => {
+    const body = await converseBody(sonnet45, {
+      tools: [weatherTool],
+      toolChoice: 'required',
+    })
+    expect(body).not.toHaveProperty('additionalModelRequestFields')
+    expect(body).toHaveProperty('toolConfig.toolChoice', { any: {} })
+  })
+
+  it.each(forcedChoices)(
+    'with thinking on an older Claude model, sends auto for $label',
+    async ({ toolChoice }) => {
+      const body = await converseBody(sonnet45, {
+        tools: [weatherTool],
+        toolChoice,
+        reasoning: { level: 'high', summary: false },
+      })
+      expect(body).toHaveProperty(
+        'additionalModelRequestFields.thinking.type',
+        'enabled',
+      )
+      expect(body).toHaveProperty('toolConfig.toolChoice', { auto: {} })
+    },
+  )
+
+  it('with thinking on an older Claude model, still sends no toolConfig for none', async () => {
+    const body = await converseBody(sonnet45, {
+      tools: [weatherTool],
+      toolChoice: 'none',
+      reasoning: { level: 'high', summary: false },
+    })
+    expect(body).toHaveProperty('additionalModelRequestFields')
+    expect(body).not.toHaveProperty('toolConfig')
+  })
+
+  it.each(noForcedToolModels)(
+    'on %s, sends auto for a forced choice',
+    async (model) => {
+      for (const { toolChoice } of forcedChoices) {
+        const { modelId, body } = await converseRequest(model, {
+          tools: [weatherTool],
+          toolChoice,
+        })
+        expect(modelId).toBe(model)
+        expect(body).not.toHaveProperty('additionalModelRequestFields')
+        expect(body).toHaveProperty('toolConfig.toolChoice', { auto: {} })
+      }
+    },
+  )
+
+  it('on a Claude model that rejects a forced tool, sends no toolConfig for none', async () => {
+    const body = await converseBody('us.anthropic.claude-opus-5-5-v1:0', {
+      tools: [weatherTool],
+      toolChoice: 'none',
+    })
+    expect(body).not.toHaveProperty('toolConfig')
+  })
+})
+
+// The Bedrock OpenAI-compatible adapters inherit the openai-base mapping.
+const gptOss = 'openai.gpt-oss-120b-1:0'
+
+interface OpenAIRequest {
+  tools?: Array<Tool>
+  toolChoice?: ToolChoice
+  modelOptions?: { tool_choice: 'none' }
+}
+
+type Send = (
+  fetch: typeof globalThis.fetch,
+  request: OpenAIRequest,
+) => AsyncIterable<unknown>
+
+const openaiAdapters = [
+  {
+    adapter: 'Bedrock Chat Completions',
+    namedChoice: { type: 'function', function: { name: 'lookup_weather' } },
+    send: (fetch, request) =>
+      createBedrockChat(gptOss, 'test-key', { fetch }).chatStream({
+        logger,
+        model: gptOss,
+        messages,
+        ...request,
+      }),
+  },
+  {
+    adapter: 'Bedrock Responses',
+    namedChoice: { type: 'function', name: 'lookup_weather' },
+    send: (fetch, request) =>
+      createBedrockResponsesText(gptOss, 'test-key', { fetch }).chatStream({
+        logger,
+        model: gptOss,
+        messages,
+        ...request,
+      }),
+  },
+] satisfies Array<{ adapter: string; namedChoice: object; send: Send }>
+
+/** Runs one streaming call and returns the JSON body sent over HTTP. */
+async function openaiBody(send: Send, request: OpenAIRequest) {
+  let body: unknown
+  const fetch: typeof globalThis.fetch = async (_url, init) => {
+    body = JSON.parse(String(init?.body))
+    return new Response('', {
+      headers: { 'content-type': 'text/event-stream' },
+    })
+  }
+  for await (const _ of send(fetch, request)) {
+    // drain
+  }
+  return body
+}
+
+describe.each(openaiAdapters)(
+  '$adapter tool_choice',
+  ({ send, namedChoice }) => {
+    it('sends required as is', async () => {
+      const body = await openaiBody(send, {
+        tools: [weatherTool],
+        toolChoice: 'required',
+      })
+      expect(body).toHaveProperty('tool_choice', 'required')
+    })
+
+    it('sends a named tool as a function choice', async () => {
+      const body = await openaiBody(send, {
+        tools: [weatherTool],
+        toolChoice: named,
+      })
+      expect(body).toHaveProperty('tool_choice', namedChoice)
+    })
+
+    it('lets a tool_choice in modelOptions win', async () => {
+      const body = await openaiBody(send, {
+        tools: [weatherTool],
+        toolChoice: 'required',
+        modelOptions: { tool_choice: 'none' },
+      })
+      expect(body).toHaveProperty('tool_choice', 'none')
+    })
+
+    it('sends no tool_choice when the request has no tools', async () => {
+      const body = await openaiBody(send, { toolChoice: 'required' })
+      expect(body).toHaveProperty('model')
+      expect(body).not.toHaveProperty('tool_choice')
+    })
+  },
+)
diff --git a/packages/ai-byteplus/tests/tool-choice-wire.test.ts b/packages/ai-byteplus/tests/tool-choice-wire.test.ts
new file mode 100644
index 0000000000..a8baeea9a0
--- /dev/null
+++ b/packages/ai-byteplus/tests/tool-choice-wire.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { createBytePlusText } from '../src/adapters/text'
+import type { ModelMessage, Tool, ToolChoice } from '@tanstack/ai'
+
+const logger = resolveDebugOption(false)
+const model = 'seed-2-0-lite-260428'
+const messages: Array<ModelMessage> = [
+  { role: 'user', content: 'Weather in Paris?' },
+]
+const weatherTool: Tool = {
+  name: 'lookup_weather',
+  description: 'Return the forecast for a location',
+}
+
+interface ToolRequest {
+  tools?: Array<Tool>
+  toolChoice?: ToolChoice
+  modelOptions?: { tool_choice: 'none' }
+}
+
+/** Runs one streaming call and returns the JSON body sent over HTTP. */
+async function sentBody(request: ToolRequest) {
+  let body: unknown
+  const fetch: typeof globalThis.fetch = async (_url, init) => {
+    body = JSON.parse(String(init?.body))
+    return new Response('', {
+      headers: { 'content-type': 'text/event-stream' },
+    })
+  }
+  const adapter = createBytePlusText(model, 'test-key', { fetch })
+  for await (const _ of adapter.chatStream({
+    logger,
+    model,
+    messages,
+    ...request,
+  })) {
+    // drain
+  }
+  return body
+}
+
+describe('byteplusText tool_choice', () => {
+  it('sends required as is', async () => {
+    const body = await sentBody({
+      tools: [weatherTool],
+      toolChoice: 'required',
+    })
+    expect(body).toHaveProperty('tool_choice', 'required')
+  })
+
+  it('sends a named tool as a function choice', async () => {
+    const body = await sentBody({
+      tools: [weatherTool],
+      toolChoice: { type: 'tool', name: 'lookup_weather' },
+    })
+    expect(body).toHaveProperty('tool_choice', {
+      type: 'function',
+      function: { name: 'lookup_weather' },
+    })
+  })
+
+  it('lets a tool_choice in modelOptions win', async () => {
+    const body = await sentBody({
+      tools: [weatherTool],
+      toolChoice: 'required',
+      modelOptions: { tool_choice: 'none' },
+    })
+    expect(body).toHaveProperty('tool_choice', 'none')
+  })
+
+  it('sends no tool_choice when the request has no tools', async () => {
+    const body = await sentBody({ toolChoice: 'required' })
+    expect(body).toHaveProperty('model', model)
+    expect(body).not.toHaveProperty('tool_choice')
+  })
+})
diff --git a/packages/ai-cloudflare/tests/tool-choice-wire.test.ts b/packages/ai-cloudflare/tests/tool-choice-wire.test.ts
new file mode 100644
index 0000000000..bee6ddac40
--- /dev/null
+++ b/packages/ai-cloudflare/tests/tool-choice-wire.test.ts
@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { CloudflareTextAdapter } from '../src/adapters/text'
+import type { ModelMessage, Tool, ToolChoice } from '@tanstack/ai'
+
+const logger = resolveDebugOption(false)
+const model = '@cf/zai-org/glm-5.3-flash'
+const messages: Array<ModelMessage> = [
+  { role: 'user', content: 'Weather in Paris?' },
+]
+const weatherTool: Tool = {
+  name: 'lookup_weather',
+  description: 'Return the forecast for a location',
+}
+
+interface ToolRequest {
+  tools?: Array<Tool>
+  toolChoice?: ToolChoice
+  modelOptions?: { tool_choice: 'none' }
+}
+
+/** Runs one streaming call over REST and returns the JSON body sent. */
+async function sentBody(request: ToolRequest) {
+  let body: unknown
+  const fetch: typeof globalThis.fetch = async (_url, init) => {
+    body = JSON.parse(String(init?.body))
+    return new Response('', {
+      headers: { 'content-type': 'text/event-stream' },
+    })
+  }
+  // The Cloudflare options type has no `tool_choice`, so it is added here.
+  const adapter = new CloudflareTextAdapter<
+    typeof model,
+    { tool_choice?: 'none' }
+  >({ accountId: 'test-account', apiKey: 'test-key', fetch }, model)
+  for await (const _ of adapter.chatStream({
+    logger,
+    model,
+    messages,
+    ...request,
+  })) {
+    // drain
+  }
+  return body
+}
+
+describe('cloudflareText tool_choice', () => {
+  it('sends required as is', async () => {
+    const body = await sentBody({
+      tools: [weatherTool],
+      toolChoice: 'required',
+    })
+    expect(body).toHaveProperty('tool_choice', 'required')
+  })
+
+  it('sends a named tool as a function choice', async () => {
+    const body = await sentBody({
+      tools: [weatherTool],
+      toolChoice: { type: 'tool', name: 'lookup_weather' },
+    })
+    expect(body).toHaveProperty('tool_choice', {
+      type: 'function',
+      function: { name: 'lookup_weather' },
+    })
+  })
+
+  it('lets a tool_choice in modelOptions win', async () => {
+    const body = await sentBody({
+      tools: [weatherTool],
+      toolChoice: 'required',
+      modelOptions: { tool_choice: 'none' },
+    })
+    expect(body).toHaveProperty('tool_choice', 'none')
+  })
+
+  it('sends no tool_choice when the request has no tools', async () => {
+    const body = await sentBody({ toolChoice: 'required' })
+    expect(body).toHaveProperty('model', model)
+    expect(body).not.toHaveProperty('tool_choice')
+  })
+})
diff --git a/packages/ai-code-mode/src/harness.ts b/packages/ai-code-mode/src/harness.ts
index ff83c7effb..ddfa73acda 100644
--- a/packages/ai-code-mode/src/harness.ts
+++ b/packages/ai-code-mode/src/harness.ts
@@ -1,4 +1,5 @@
 import {
+  PermissionResources,
   PermissionRules,
   decidePermission,
   definePlugin,
@@ -14,7 +15,9 @@ export interface CodeModePluginOptions extends Omit<
   /**
    * Which tools move into code mode. Default: every server tool that does
    * not need approval and that the permission rules allow in plan mode (so
-   * no edits, no commands, nothing that asks first).
+   * no edits, no commands, nothing that asks first). A safe tool with
+   * `metadata.codeMode: true`, for example a tool of an `mcp()` server with
+   * `codeMode: true`, moves even when `include` does not pick it.
    */
   include?: (tool: CodeModeTool) => boolean
   /**
@@ -51,8 +54,12 @@ function isServerTool(tool: AnyTool): tool is CodeModeTool {
  *
  * Calls inside the isolate do not stop for approval, so by default only
  * tools that are safe to run without a question move into code mode. The
- * other tools stay normal tool calls. With `lazy: true`, the model gets only
- * the names of the moved tools and asks `discover_tools` for the signatures.
+ * other tools stay normal tool calls. A tool with `metadata.codeMode: true`
+ * moves even when `include` does not pick it, but only when it is safe in
+ * the same way. Calls inside the isolate also skip the permission checks,
+ * so a tool that declares `PermissionResources` never moves. With
+ * `lazy: true`, the model gets only the names of the moved tools and asks
+ * `discover_tools` for the signatures.
  *
  * @example
  * ```ts
@@ -72,18 +79,31 @@ export function codeMode(options: CodeModePluginOptions) {
     name: 'tanstack/code-mode',
     setup: (ctx) => {
       const rules = ctx.collect(PermissionRules)
-      const safe = (tool: CodeModeTool) =>
-        !tool.needsApproval &&
-        decidePermission(rules, tool.name, 'plan') === 'allow'
+      const resources = ctx.collect(PermissionResources)
       // The system prompt for the tools of the current turn.
       let prompt = ''
       return {
         prompts: [{ id: 'tanstack/code-mode', text: () => prompt }],
         prepareTools: ({ tools }) => {
+          const safe = (tool: CodeModeTool) =>
+            !tool.needsApproval &&
+            decidePermission(rules, tool.name, 'plan') === 'allow'
+          const moves = (tool: CodeModeTool) => {
+            // The permission checks run on tool calls of the model. A call
+            // inside the isolate skips them, so such a tool stays a tool call.
+            const hasResources = resources.some((map) =>
+              Object.hasOwn(map, tool.name),
+            )
+            if (hasResources) return false
+            // A marked tool still needs the checks of the default pick.
+            const isMarked = tool.metadata?.codeMode === true
+            if (isMarked && safe(tool)) return true
+            return include ? include(tool) : safe(tool)
+          }
           // Two tools that map to the same identifier: the first one moves.
           const byIdentifier = new Map<string, CodeModeTool>()
           for (const tool of tools.filter(isServerTool)) {
-            if (!(include ? include(tool) : safe(tool))) continue
+            if (!moves(tool)) continue
             const identifier = identifierOf(tool.name)
             if (!byIdentifier.has(identifier))
               byIdentifier.set(identifier, tool)
diff --git a/packages/ai-code-mode/tests/harness.test.ts b/packages/ai-code-mode/tests/harness.test.ts
index 5f1a85aaac..d09e9fc304 100644
--- a/packages/ai-code-mode/tests/harness.test.ts
+++ b/packages/ai-code-mode/tests/harness.test.ts
@@ -8,8 +8,10 @@ import {
   defineHarness,
   definePlugin,
 } from '@tanstack/ai-harness'
+import { PermissionResources } from '@tanstack/ai-harness/plugins'
 import { codeMode } from '../src/harness'
-import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import type { AnyTextAdapter, AnyTool, StreamChunk } from '@tanstack/ai'
+import type { HarnessPlugin } from '@tanstack/ai-harness'
 import type { ExecutionResult, IsolateDriver, ToolBinding } from '../src/types'
 
 const now = () => Date.now()
@@ -182,6 +184,38 @@ const notion = definePlugin({
   setup: () => ({ discoverTools: () => [tools.notionSearch] }),
 })
 
+/** A server tool marked for code mode, like the tools of `mcp({ codeMode })`. */
+function markedTool(name: string, needsApproval = false) {
+  return toolDefinition({
+    name,
+    description: 'A marked tool',
+    inputSchema: z.object({}),
+    needsApproval,
+    metadata: { codeMode: true },
+  }).server(async () => name)
+}
+
+/** Opens a code mode session and returns the tool names of the first model call. */
+async function firstToolNames(options: {
+  tools: ReadonlyArray<AnyTool>
+  plugins: ReadonlyArray<HarnessPlugin>
+}) {
+  const { adapter, calls } = scripted([textTurn('ok')])
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const session = await host.open(
+    defineHarness({
+      name: 'test/code-mode-marked',
+      adapter,
+      tools: options.tools,
+      plugins: () => options.plugins,
+    }),
+    { threadId: 't' },
+  )
+  await session.prompt('hi')
+  await host.close()
+  return calls[0].tools.map((tool: { name: string }) => tool.name)
+}
+
 describe('codeMode', () => {
   it('moves safe tools, including discovered ones, behind execute_typescript', async () => {
     const { driver, seen } = fakeDriver()
@@ -340,4 +374,51 @@ describe('codeMode', () => {
     expect(JSON.stringify(calls[1].messages)).toContain('from web-search')
     await host.close()
   })
+
+  it('moves a marked tool that include does not pick, unless a rule or an approval stops it', async () => {
+    const rules = definePlugin({
+      name: 'test/marked-rules',
+      setup: () => ({
+        contribute: [
+          PermissionRules.item({ tool: 'docs_allowed', decision: 'allow' }),
+          PermissionRules.item({ tool: 'docs_ask', decision: 'ask' }),
+          PermissionRules.item({ tool: 'docs_deny', decision: 'deny' }),
+        ],
+      }),
+    })
+    const names = await firstToolNames({
+      tools: [
+        markedTool('docs_allowed'),
+        markedTool('docs_ask'),
+        markedTool('docs_deny'),
+        markedTool('docs_write', true),
+      ],
+      plugins: [
+        rules,
+        codeMode({ driver: fakeDriver().driver, include: () => false }),
+      ],
+    })
+    expect(names).toEqual([
+      'docs_ask',
+      'docs_deny',
+      'docs_write',
+      'execute_typescript',
+    ])
+  })
+
+  it('keeps a tool that declares permission resources as a tool call', async () => {
+    const resources = definePlugin({
+      name: 'test/resources',
+      setup: () => ({
+        contribute: [
+          PermissionResources.item({ read_file: { paths: () => ['a.txt'] } }),
+        ],
+      }),
+    })
+    const names = await firstToolNames({
+      tools: [tools.lookup, markedTool('read_file')],
+      plugins: [resources, codeMode({ driver: fakeDriver().driver })],
+    })
+    expect(names).toEqual(['read_file', 'execute_typescript'])
+  })
 })
diff --git a/packages/ai-gemini/src/adapters/text.ts b/packages/ai-gemini/src/adapters/text.ts
index 59a5705ec9..dc465c10e7 100644
--- a/packages/ai-gemini/src/adapters/text.ts
+++ b/packages/ai-gemini/src/adapters/text.ts
@@ -1,4 +1,4 @@
-import { FinishReason } from '@google/genai'
+import { FinishReason, FunctionCallingConfigMode } from '@google/genai'
 import {
   EventType,
   fileReferenceFor,
@@ -42,6 +42,7 @@ import type {
 import type { InternalLogger } from '@tanstack/ai/adapter-internals'
 import type {
   Content,
+  FunctionCallingConfig,
   GenerateContentParameters,
   GenerateContentResponse,
   GoogleGenAI,
@@ -58,6 +59,7 @@ import type {
   AdapterYieldChunk,
   ProviderExecutedToolSource,
   TextOptions,
+  ToolChoice,
 } from '@tanstack/ai'
 import type { ExternalTextProviderOptions } from '../text/text-provider-options'
 import type {
@@ -136,6 +138,19 @@ function getGroundingSources(
   return [...sources.values()]
 }
 
+/** Maps `chat({ toolChoice })` to the Gemini function calling config. */
+function toGeminiFunctionCallingConfig(
+  choice: ToolChoice,
+): FunctionCallingConfig {
+  if (choice === 'auto') return { mode: FunctionCallingConfigMode.AUTO }
+  if (choice === 'none') return { mode: FunctionCallingConfigMode.NONE }
+  if (choice === 'required') return { mode: FunctionCallingConfigMode.ANY }
+  return {
+    mode: FunctionCallingConfigMode.ANY,
+    allowedFunctionNames: [choice.name],
+  }
+}
+
 /**
  * Content block shape for an Interactions API `input` step. The installed
  * @google/genai types predate the video `processing` field, so we model the
@@ -1550,6 +1565,17 @@ export class GeminiTextAdapter<
         }
       : undefined
 
+    // `chat({ toolChoice })` is sent only when the request has function
+    // declarations, because Gemini rejects a function calling config without
+    // them. A `toolConfig` in modelOptions wins key by key, so its own
+    // `functionCallingConfig` wins, and a `retrievalConfig` alone keeps this one.
+    const tools = convertToolsToProviderFormat(options.tools)
+    const functionCallingConfig =
+      options.toolChoice !== undefined &&
+      tools.some((tool) => 'functionDeclarations' in tool)
+        ? toGeminiFunctionCallingConfig(options.toolChoice)
+        : undefined
+
     // Vendor `GenerateContentConfig` fields are `field?: T` (no `| undefined`)
     // under EOPT, so spread each common option only when present rather than
     // emitting `field: undefined`s into the wire payload.
@@ -1564,11 +1590,17 @@ export class GeminiTextAdapter<
       ),
       config: {
         ...modelOpts,
+        ...(functionCallingConfig !== undefined && {
+          toolConfig: {
+            functionCallingConfig,
+            ...options.modelOptions?.toolConfig,
+          },
+        }),
         ...(mappedThinkingConfig !== undefined && {
           thinkingConfig: mappedThinkingConfig,
         }),
         ...(systemInstruction !== undefined && { systemInstruction }),
-        tools: convertToolsToProviderFormat(options.tools),
+        tools,
         ...(combinedSchemaConfig ?? {}),
         // Forward the caller's abort signal so cancellation reaches the SDK
         // request, matching the OpenAI-compatible adapters (issue #1374).
diff --git a/packages/ai-gemini/tests/tool-choice-wire.test.ts b/packages/ai-gemini/tests/tool-choice-wire.test.ts
new file mode 100644
index 0000000000..2ed988c393
--- /dev/null
+++ b/packages/ai-gemini/tests/tool-choice-wire.test.ts
@@ -0,0 +1,151 @@
+import { describe, expect, it, vi } from 'vitest'
+import { FunctionCallingConfigMode } from '@google/genai'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { createGeminiChat } from '../src/adapters/text'
+import { googleSearchTool } from '../src/tools'
+import type { TextOptions, Tool, ToolChoice } from '@tanstack/ai'
+import type { GeminiTextProviderOptions } from '../src/adapters/text'
+
+const logger = resolveDebugOption(false)
+const model = 'gemini-3.1-pro-preview'
+
+const weatherTool: Tool = {
+  name: 'lookup_weather',
+  description: 'Return the forecast for a location',
+}
+
+const sse = `data: ${JSON.stringify({
+  candidates: [
+    {
+      content: { role: 'model', parts: [{ text: 'Done' }] },
+      finishReason: 'STOP',
+    },
+  ],
+})}\n\n`
+
+type CallOptions = Pick<
+  TextOptions<GeminiTextProviderOptions>,
+  'tools' | 'toolChoice' | 'modelOptions'
+>
+
+/**
+ * Runs one streaming call through the real SDK and returns the JSON body
+ * sent over HTTP. Vertex runs in express mode, so it needs only an API key.
+ */
+async function sentBody(options: CallOptions, config: { vertexai?: boolean }) {
+  let body: unknown
+  const fetch = vi
+    .spyOn(globalThis, 'fetch')
+    .mockImplementation(async (_url, init) => {
+      body = JSON.parse(String(init?.body))
+      return new Response(sse, {
+        headers: { 'content-type': 'text/event-stream' },
+      })
+    })
+  try {
+    const adapter = createGeminiChat(model, 'test-key', config)
+    for await (const _ of adapter.chatStream({
+      logger,
+      model,
+      messages: [{ role: 'user', content: 'Weather in Paris?' }],
+      ...options,
+    })) {
+      // drain
+    }
+  } finally {
+    fetch.mockRestore()
+  }
+  return body
+}
+
+interface Row {
+  label: string
+  toolChoice: ToolChoice
+  expected: object
+}
+
+const shapes: Array<Row> = [
+  { label: 'auto', toolChoice: 'auto', expected: { mode: 'AUTO' } },
+  { label: 'none', toolChoice: 'none', expected: { mode: 'NONE' } },
+  { label: 'required', toolChoice: 'required', expected: { mode: 'ANY' } },
+  {
+    label: 'a named tool',
+    toolChoice: { type: 'tool', name: 'lookup_weather' },
+    expected: { mode: 'ANY', allowedFunctionNames: ['lookup_weather'] },
+  },
+]
+
+describe('Gemini toolConfig.functionCallingConfig', () => {
+  it.each(shapes)('sends $label', async ({ toolChoice, expected }) => {
+    const body = await sentBody({ tools: [weatherTool], toolChoice }, {})
+    expect(body).toHaveProperty('toolConfig', {
+      functionCallingConfig: expected,
+    })
+  })
+
+  it('sends a named tool on Vertex', async () => {
+    const body = await sentBody(
+      {
+        tools: [weatherTool],
+        toolChoice: { type: 'tool', name: 'lookup_weather' },
+      },
+      { vertexai: true },
+    )
+    expect(body).toHaveProperty('toolConfig', {
+      functionCallingConfig: {
+        mode: 'ANY',
+        allowedFunctionNames: ['lookup_weather'],
+      },
+    })
+  })
+
+  it('sends no toolConfig when the request has no tools', async () => {
+    const body = await sentBody({ toolChoice: 'required' }, {})
+    expect(body).toHaveProperty('contents')
+    expect(body).not.toHaveProperty('toolConfig')
+  })
+
+  it('sends no toolConfig when the request has only provider tools', async () => {
+    const body = await sentBody(
+      { tools: [googleSearchTool()], toolChoice: 'required' },
+      {},
+    )
+    expect(body).toHaveProperty('tools', [{ googleSearch: {} }])
+    expect(body).not.toHaveProperty('toolConfig')
+  })
+
+  it('lets a functionCallingConfig in modelOptions win', async () => {
+    const body = await sentBody(
+      {
+        tools: [weatherTool],
+        toolChoice: 'required',
+        modelOptions: {
+          toolConfig: {
+            functionCallingConfig: { mode: FunctionCallingConfigMode.NONE },
+          },
+        },
+      },
+      {},
+    )
+    expect(body).toHaveProperty('toolConfig', {
+      functionCallingConfig: { mode: 'NONE' },
+    })
+  })
+
+  it('keeps the mapped mode next to a retrievalConfig in modelOptions', async () => {
+    const body = await sentBody(
+      {
+        tools: [weatherTool],
+        toolChoice: 'required',
+        modelOptions: {
+          toolConfig: { retrievalConfig: { languageCode: 'en' } },
+        },
+      },
+      {},
+    )
+    expect(body).toHaveProperty('toolConfig', {
+      functionCallingConfig: { mode: 'ANY' },
+      retrievalConfig: { languageCode: 'en' },
+    })
+  })
+})
diff --git a/packages/ai-grok/src/adapters/text.ts b/packages/ai-grok/src/adapters/text.ts
index e42c137cc2..1081f3ca48 100644
--- a/packages/ai-grok/src/adapters/text.ts
+++ b/packages/ai-grok/src/adapters/text.ts
@@ -1,6 +1,9 @@
 import OpenAI from 'openai'
 import { fileReferenceFor, isFileSource } from '@tanstack/ai'
-import { OpenAIBaseResponsesTextAdapter } from '@tanstack/openai-base'
+import {
+  OpenAIBaseResponsesTextAdapter,
+  toResponsesToolChoice,
+} from '@tanstack/openai-base'
 import { GROK_MODEL_INPUT_MODALITIES } from '../model-meta'
 import { GROK_MODEL_REASONING } from '../model-reasoning'
 import type { GrokModelReasoningByName } from '../model-reasoning'
@@ -131,7 +134,16 @@ export class GrokTextAdapter<
       ? convertToolsToProviderFormat(options.tools)
       : undefined
 
+    // The base saw no tools, so it sent no `chat({ toolChoice })`. Set it
+    // here when the request has tools. It goes before `request`, so a
+    // `tool_choice` from modelOptions wins.
+    const toolChoiceField =
+      tools?.length && options.toolChoice !== undefined
+        ? { tool_choice: toResponsesToolChoice(options.toolChoice) }
+        : undefined
+
     return {
+      ...toolChoiceField,
       ...request,
       // xAI recommends encrypted reasoning for reasoning-capable Responses
       // requests; callers can still override either field in modelOptions.
diff --git a/packages/ai-grok/tests/tool-choice-wire.test.ts b/packages/ai-grok/tests/tool-choice-wire.test.ts
new file mode 100644
index 0000000000..8db9ec0b7b
--- /dev/null
+++ b/packages/ai-grok/tests/tool-choice-wire.test.ts
@@ -0,0 +1,106 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { GrokTextAdapter } from '../src/adapters/text'
+import { grokVertexText } from '../src/vertex'
+import type { ModelMessage, Tool, ToolChoice } from '@tanstack/ai'
+
+const logger = resolveDebugOption(false)
+const model = 'grok-4.3'
+const messages: Array<ModelMessage> = [
+  { role: 'user', content: 'Weather in Paris?' },
+]
+const weatherTool: Tool = {
+  name: 'lookup_weather',
+  description: 'Return the forecast for a location',
+}
+
+interface ToolRequest {
+  tools?: Array<Tool>
+  toolChoice?: ToolChoice
+  modelOptions?: { tool_choice: 'none' }
+}
+
+/** Drains one chat stream and returns the JSON body sent over HTTP. */
+async function sentBody(
+  send: (fetch: typeof globalThis.fetch) => AsyncIterable<unknown>,
+) {
+  let body: unknown
+  const fetch: typeof globalThis.fetch = async (_url, init) => {
+    body = JSON.parse(String(init?.body))
+    return new Response('', {
+      headers: { 'content-type': 'text/event-stream' },
+    })
+  }
+  for await (const _ of send(fetch)) {
+    // drain
+  }
+  return body
+}
+
+/** The JSON body that the xAI adapter sends for one request. */
+function xaiBody(request: ToolRequest) {
+  return sentBody((fetch) =>
+    // The Grok options type has no `tool_choice`, so it is added here.
+    new GrokTextAdapter<typeof model, { tool_choice?: 'none' }>(
+      { apiKey: 'test-key', fetch },
+      model,
+    ).chatStream({ logger, model, messages, ...request }),
+  )
+}
+
+describe('grokText tool_choice', () => {
+  it('sends required as is', async () => {
+    const body = await xaiBody({ tools: [weatherTool], toolChoice: 'required' })
+    expect(body).toHaveProperty('tool_choice', 'required')
+  })
+
+  it('sends a named tool as a function choice', async () => {
+    const body = await xaiBody({
+      tools: [weatherTool],
+      toolChoice: { type: 'tool', name: 'lookup_weather' },
+    })
+    expect(body).toHaveProperty('tool_choice', {
+      type: 'function',
+      name: 'lookup_weather',
+    })
+  })
+
+  it('lets a tool_choice in modelOptions win', async () => {
+    const body = await xaiBody({
+      tools: [weatherTool],
+      toolChoice: 'required',
+      modelOptions: { tool_choice: 'none' },
+    })
+    expect(body).toHaveProperty('tool_choice', 'none')
+  })
+
+  it('sends no tool_choice when the request has no tools', async () => {
+    const body = await xaiBody({ toolChoice: 'required' })
+    expect(body).toHaveProperty('model', model)
+    expect(body).not.toHaveProperty('tool_choice')
+  })
+})
+
+describe('grokVertexText tool_choice', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('sends required as is', async () => {
+    const body = await sentBody((fetch) => {
+      // The Vertex adapter calls the global fetch.
+      vi.stubGlobal('fetch', fetch)
+      return grokVertexText(model, {
+        baseURL: 'http://vertex.test/v1',
+        getAccessToken: async () => 'vertex-token',
+      }).chatStream({
+        logger,
+        model,
+        messages,
+        tools: [weatherTool],
+        toolChoice: 'required',
+      })
+    })
+    expect(body).toHaveProperty('tool_choice', 'required')
+  })
+})
diff --git a/packages/ai-groq/tests/tool-choice-wire.test.ts b/packages/ai-groq/tests/tool-choice-wire.test.ts
new file mode 100644
index 0000000000..28e8e2e5e0
--- /dev/null
+++ b/packages/ai-groq/tests/tool-choice-wire.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { createGroqText } from '../src/adapters/text'
+import type { ModelMessage, Tool, ToolChoice } from '@tanstack/ai'
+
+const logger = resolveDebugOption(false)
+const model = 'llama-3.3-70b-versatile'
+const messages: Array<ModelMessage> = [
+  { role: 'user', content: 'Weather in Paris?' },
+]
+const weatherTool: Tool = {
+  name: 'lookup_weather',
+  description: 'Return the forecast for a location',
+}
+
+interface ToolRequest {
+  tools?: Array<Tool>
+  toolChoice?: ToolChoice
+  modelOptions?: { tool_choice: 'none' }
+}
+
+/** Runs one streaming call and returns the JSON body sent over HTTP. */
+async function sentBody(request: ToolRequest) {
+  let body: unknown
+  const fetch: typeof globalThis.fetch = async (_url, init) => {
+    body = JSON.parse(String(init?.body))
+    return new Response('', {
+      headers: { 'content-type': 'text/event-stream' },
+    })
+  }
+  const adapter = createGroqText(model, 'test-key', { fetch })
+  for await (const _ of adapter.chatStream({
+    logger,
+    model,
+    messages,
+    ...request,
+  })) {
+    // drain
+  }
+  return body
+}
+
+describe('groqText tool_choice', () => {
+  it('sends required as is', async () => {
+    const body = await sentBody({
+      tools: [weatherTool],
+      toolChoice: 'required',
+    })
+    expect(body).toHaveProperty('tool_choice', 'required')
+  })
+
+  it('sends a named tool as a function choice', async () => {
+    const body = await sentBody({
+      tools: [weatherTool],
+      toolChoice: { type: 'tool', name: 'lookup_weather' },
+    })
+    expect(body).toHaveProperty('tool_choice', {
+      type: 'function',
+      function: { name: 'lookup_weather' },
+    })
+  })
+
+  it('lets a tool_choice in modelOptions win', async () => {
+    const body = await sentBody({
+      tools: [weatherTool],
+      toolChoice: 'required',
+      modelOptions: { tool_choice: 'none' },
+    })
+    expect(body).toHaveProperty('tool_choice', 'none')
+  })
+
+  it('sends no tool_choice when the request has no tools', async () => {
+    const body = await sentBody({ toolChoice: 'required' })
+    expect(body).toHaveProperty('model', model)
+    expect(body).not.toHaveProperty('tool_choice')
+  })
+})
diff --git a/packages/ai-harness/src/config.ts b/packages/ai-harness/src/config.ts
index 1ae460642f..72df9a16d7 100644
--- a/packages/ai-harness/src/config.ts
+++ b/packages/ai-harness/src/config.ts
@@ -1,7 +1,8 @@
 /**
  * A session setting a plugin declares, for example the model or the
- * thinking level. Hosts render it from this description (a picker in the
- * CLI, `configOptions` in ACP). A change applies at the next turn.
+ * thinking level. Hosts render it from this description, for example a
+ * picker in the CLI. `serveAcp` does not send config options yet. A change
+ * applies at the next turn.
  */
 export type ConfigOption =
   | {
@@ -9,7 +10,10 @@ export type ConfigOption =
       options: ReadonlyArray<string>
       default: string
       description?: string
-      /** ACP category, for example `'model'` or `'thought_level'`. */
+      /**
+       * A kind for hosts that group settings, for example `'model'` or
+       * `'thought_level'`. `serveAcp` does not send it yet.
+       */
       category?: string
     }
   | { type: 'boolean'; default: boolean; description?: string }
diff --git a/packages/ai-harness/src/first-party/coding/bash.ts b/packages/ai-harness/src/first-party/coding/bash.ts
index 5ee7afd3d4..d7211497d4 100644
--- a/packages/ai-harness/src/first-party/coding/bash.ts
+++ b/packages/ai-harness/src/first-party/coding/bash.ts
@@ -1,8 +1,7 @@
-import { join, resolve } from 'node:path'
 import { toolDefinition } from '@tanstack/ai'
 import { isRecord } from '../../utils'
 import { boundText } from '../bound-output'
-import { stringArg } from './backend'
+import { pathsOf, stringArg } from './backend'
 import type { ToolEnv } from './backend'
 
 /** The longest timeout that one call can ask for: 10 minutes. */
@@ -142,6 +141,7 @@ export function bashTools(
 
   /** Save the full output in `dir`. Gives back the note for the model. */
   const spill = async (dir: string, output: string) => {
+    const { join, resolve } = pathsOf(env.backend)
     const path = join(
       resolve(env.root, dir),
       `bash-${crypto.randomUUID()}.txt`,
diff --git a/packages/ai-harness/src/first-party/coding/formatter.ts b/packages/ai-harness/src/first-party/coding/formatter.ts
index 215f0fdda2..fc451213fc 100644
--- a/packages/ai-harness/src/first-party/coding/formatter.ts
+++ b/packages/ai-harness/src/first-party/coding/formatter.ts
@@ -1,10 +1,9 @@
-import { extname, join, resolve } from 'node:path'
 import { createPluginEvent } from '../../extensions'
 import { definePlugin } from '../../plugins'
 import { isRecord } from '../../utils'
 import { WorkspaceHooks } from '../workspace-hooks'
-import { hostBackend, readText } from './backend'
-import { quoteArg } from './search'
+import { hostBackend, pathsOf, readText } from './backend'
+import { quoteArg, shellPlatform } from './search'
 import type { WorkspaceBackend } from './backend'
 
 /** What a formatter can check in the project root folder. */
@@ -144,12 +143,11 @@ export function formatOnWrite(
   options: FormatterOptions,
   onFailure: (failure: FormatFailure) => void,
 ) {
-  const root = resolve(options.root)
   const backend = options.backend ?? hostBackend
+  const { extname, join, resolve } = pathsOf(backend)
+  const root = resolve(options.root)
   const timeoutMs = options.timeoutMs ?? 20_000
-  // ponytail: the same rule as search.ts. A backend other than the host is
-  // taken to have a POSIX `sh`, like a Linux sandbox.
-  const platform = backend === hostBackend ? process.platform : 'linux'
+  const platform = shellPlatform(backend)
   const candidates = [
     ...(options.formatters ?? []),
     ...(options.builtins === false ? [] : BUILTINS),
diff --git a/packages/ai-harness/src/first-party/coding/index.ts b/packages/ai-harness/src/first-party/coding/index.ts
index 0269e2fd19..f6620a0b18 100644
--- a/packages/ai-harness/src/first-party/coding/index.ts
+++ b/packages/ai-harness/src/first-party/coding/index.ts
@@ -5,3 +5,12 @@ export type { WorkspaceToolsOptions } from './workspace'
 export { hostBackend } from './backend'
 export type { WorkspaceBackend } from './backend'
 export { WorkspaceHooks } from '../workspace-hooks'
+export type { SearchProvider, WebToolsOptions } from './web'
+export { snapshots } from './snapshots'
+export type { SnapshotStep, SnapshotsOptions } from './snapshots'
+export { FormatFailed, formatter } from './formatter'
+export type {
+  Formatter,
+  FormatterOptions,
+  FormatterProject,
+} from './formatter'
diff --git a/packages/ai-harness/src/first-party/coding/read.ts b/packages/ai-harness/src/first-party/coding/read.ts
index d0f2d0e173..7aaa315901 100644
--- a/packages/ai-harness/src/first-party/coding/read.ts
+++ b/packages/ai-harness/src/first-party/coding/read.ts
@@ -1,9 +1,8 @@
-import { dirname, join, parse } from 'node:path'
 import { toolDefinition } from '@tanstack/ai'
 import { toBase64 } from '../../media'
 import { mimeTypeOf } from '../../media-ref'
 import { isRecord } from '../../utils'
-import { stringArg } from './backend'
+import { pathsOf, stringArg } from './backend'
 import type { ContentPart } from '@tanstack/ai'
 import type { ToolEnv } from './backend'
 
@@ -59,6 +58,7 @@ function distance(a: string, b: string) {
  * same name with another extension, or a name 2 or fewer changes away.
  */
 async function notFound(env: ToolEnv, full: string) {
+  const { dirname, join, parse } = pathsOf(env.backend)
   const folder = dirname(full)
   const wanted = parse(full).base.toLowerCase()
   const wantedStem = parse(wanted).name
diff --git a/packages/ai-harness/src/first-party/coding/search.ts b/packages/ai-harness/src/first-party/coding/search.ts
index 508e5d8d1a..a80556a6b4 100644
--- a/packages/ai-harness/src/first-party/coding/search.ts
+++ b/packages/ai-harness/src/first-party/coding/search.ts
@@ -69,7 +69,7 @@ export function quoteArg(value: string, platform: NodeJS.Platform) {
  * The platform of the shell that `backend.exec` uses, for {@link quoteArg}.
  * A backend without `shell` has a POSIX `sh`, like a Linux sandbox.
  */
-function shellPlatform(backend: WorkspaceBackend) {
+export function shellPlatform(backend: WorkspaceBackend) {
   return backend.shell === 'cmd' ? 'win32' : 'linux'
 }
 
diff --git a/packages/ai-harness/src/first-party/coding/snapshots.ts b/packages/ai-harness/src/first-party/coding/snapshots.ts
index bf8920a32c..b538849cdc 100644
--- a/packages/ai-harness/src/first-party/coding/snapshots.ts
+++ b/packages/ai-harness/src/first-party/coding/snapshots.ts
@@ -3,7 +3,7 @@ import { LogRecordsCapability, getLogRecords } from '@tanstack/ai'
 import { defineCommand } from '../../commands'
 import { definePlugin } from '../../plugins'
 import { hostBackend } from './backend'
-import { quoteArg } from './search'
+import { quoteArg, shellPlatform } from './search'
 import type { ModelMessage } from '@tanstack/ai'
 import type { WorkspaceBackend } from './backend'
 
@@ -42,9 +42,7 @@ const BUSY = 'Wait until the turn ends, then try again.'
  */
 function shadowRepo(options: SnapshotsOptions) {
   const backend = options.backend ?? hostBackend
-  // ponytail: the same rule as search.ts. A backend other than the host is
-  // taken to have a POSIX `sh`, like a Linux sandbox.
-  const platform = backend === hostBackend ? process.platform : 'linux'
+  const platform = shellPlatform(backend)
   const quote = (value: string) => quoteArg(value, platform)
   const hash = createHash('sha1').update(options.root).digest('hex')
   const gitDir = `${options.dataDir}/${hash}`
diff --git a/packages/ai-harness/src/first-party/coding/web.ts b/packages/ai-harness/src/first-party/coding/web.ts
index 1d63f8502a..cb45d92cc4 100644
--- a/packages/ai-harness/src/first-party/coding/web.ts
+++ b/packages/ai-harness/src/first-party/coding/web.ts
@@ -1,8 +1,12 @@
 import { lookup } from 'node:dns/promises'
+import * as http from 'node:http'
+import * as https from 'node:https'
 import { BlockList, isIP } from 'node:net'
 import { toolDefinition } from '@tanstack/ai'
 import { isRecord } from '../../utils'
 import { optionalString, stringArg } from './backend'
+import type { IncomingMessage } from 'node:http'
+import type { LookupFunction } from 'node:net'
 
 const DEFAULT_TIMEOUT_MS = 30_000
 const MAX_TIMEOUT_MS = 120_000
@@ -69,7 +73,12 @@ export interface SearchProvider {
 }
 
 export interface WebToolsOptions {
-  /** The `fetch` that `webfetch` uses. Default: the global `fetch`. */
+  /**
+   * The `fetch` that `webfetch` uses. Default: a request with `node:http`
+   * and `node:https` that checks the address of each connection. A custom
+   * `fetch` looks up host names itself. Then a DNS server that changes its
+   * answer after the check (DNS rebinding) can reach a private host.
+   */
   fetch?: typeof fetch
   /**
    * Let `webfetch` read localhost and private network hosts. Default:
@@ -158,10 +167,16 @@ function isPrivateAddress(address: string) {
   return PRIVATE.check(address, isIP(address) === 6 ? 'ipv6' : 'ipv4')
 }
 
+/** The error for a host that `webfetch` does not read. */
+function refused(host: string) {
+  return new Error(`webfetch does not read private or local hosts: ${host}`)
+}
+
 /**
  * Throws unless `url` is http or https. Unless `allowPrivateHosts` is set,
  * it also throws for a private or local host: the host as written, and
- * every address that DNS gives for it.
+ * every address that DNS gives for it. The default request checks the
+ * addresses again when it connects.
  */
 async function checkUrl(url: URL, allowPrivateHosts: boolean) {
   const isWeb = url.protocol === 'http:' || url.protocol === 'https:'
@@ -173,43 +188,113 @@ async function checkUrl(url: URL, allowPrivateHosts: boolean) {
   if (allowPrivateHosts) return
   // The URL keeps IPv6 hosts in brackets. A name can end with a dot.
   const host = url.hostname.replace(/^\[|\]$/g, '').replace(/\.$/, '')
-  const refused = `webfetch does not read private or local hosts: ${url.hostname}`
   const isLocalName = host === 'localhost' || host.endsWith('.localhost')
-  if (isLocalName) throw new Error(refused)
+  if (isLocalName) throw refused(url.hostname)
   if (isIP(host) !== 0) {
-    if (isPrivateAddress(host)) throw new Error(refused)
+    if (isPrivateAddress(host)) throw refused(url.hostname)
     return
   }
-  // ponytail: `fetch` looks the name up again. A DNS server that changes
-  // its answer between the two lookups (DNS rebinding) can still reach a
-  // private host. Pin the checked address in a custom dispatcher if that
-  // matters.
   const addresses = await lookup(host, { all: true }).catch(() => {
     throw new Error(`Could not resolve ${host}.`)
   })
   const isPrivate = addresses.some(({ address }) => isPrivateAddress(address))
-  if (isPrivate) throw new Error(refused)
+  if (isPrivate) throw refused(url.hostname)
 }
 
 /**
- * Fetch `start` and follow at most 5 redirects. Each URL is checked before
- * it is fetched, so a redirect cannot lead to a private host.
+ * A `lookup` for Node sockets. It refuses `hostname` when any of its
+ * addresses is private, unless `allowPrivateHosts` is set. The socket
+ * connects only to the addresses that were checked here, so a DNS answer
+ * that changes after `checkUrl` cannot reach a private host.
+ */
+function checkedLookup(allowPrivateHosts: boolean) {
+  const checked: LookupFunction = (hostname, options, callback) => {
+    void lookup(hostname, { ...options, all: true }).then(
+      (addresses) => {
+        const isPrivate =
+          !allowPrivateHosts &&
+          addresses.some(({ address }) => isPrivateAddress(address))
+        const [first] = addresses
+        if (isPrivate) callback(refused(hostname), [])
+        else if (options.all) callback(null, addresses)
+        else if (first) callback(null, first.address, first.family)
+        else callback(new Error(`Could not resolve ${hostname}.`), [])
+      },
+      (error) => callback(error, []),
+    )
+  }
+  return checked
+}
+
+/**
+ * A Node response as a fetch `Response`. Only the headers that `webfetch`
+ * reads are copied. The body is read from the socket on demand.
+ */
+function toResponse(response: IncomingMessage) {
+  const status = response.statusCode ?? 500
+  const headers = new Headers()
+  const { location, 'content-type': type } = response.headers
+  if (location !== undefined) headers.set('location', location)
+  if (type !== undefined) headers.set('content-type', type)
+  const hasNoBody = status === 204 || status === 205 || status === 304
+  if (hasNoBody) {
+    response.resume()
+    return new Response(null, { status, headers })
+  }
+  // The chunks are Buffers, so the stream gives Uint8Array chunks.
+  const chunks = response[Symbol.asyncIterator]()
+  const body = new ReadableStream({
+    pull: async (controller) => {
+      const next = await chunks.next()
+      if (next.done) controller.close()
+      else controller.enqueue(next.value)
+    },
+    cancel: () => {
+      response.destroy()
+    },
+  })
+  return new Response(body, { status, headers })
+}
+
+/**
+ * GET `url` with `node:http` or `node:https`. It never follows redirects.
+ * Each request gets its own connection (`agent: false`), so every
+ * connection goes through `checkedLookup`.
+ */
+async function request(
+  url: URL,
+  options: { signal: AbortSignal; allowPrivateHosts: boolean },
+) {
+  const settings = {
+    agent: false,
+    signal: options.signal,
+    lookup: checkedLookup(options.allowPrivateHosts),
+  }
+  const response = await new Promise<IncomingMessage>((resolve, reject) => {
+    const sent =
+      url.protocol === 'https:'
+        ? https.get(url, settings, resolve)
+        : http.get(url, settings, resolve)
+    sent.on('error', reject)
+  })
+  return toResponse(response)
+}
+
+/**
+ * Fetch `start` with `send` and follow at most 5 redirects. Each URL is
+ * checked before it is sent, so a redirect cannot lead to a private host.
  */
 async function follow(
   start: URL,
   options: {
-    fetch: typeof fetch
+    send: (url: URL) => Promise<Response>
     allowPrivateHosts: boolean
-    signal: AbortSignal
   },
 ) {
   let url = start
   for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
     await checkUrl(url, options.allowPrivateHosts)
-    const response = await options.fetch(url.href, {
-      redirect: 'manual',
-      signal: options.signal,
-    })
+    const response = await options.send(url)
     const location = response.headers.get('location')
     const isRedirect =
       response.status >= 300 && response.status < 400 && location !== null
@@ -285,6 +370,8 @@ async function readPage(
  * `webfetch` fetches URLs that the model picks. So it reads only http and
  * https, and it refuses localhost, loopback, link-local (with cloud
  * metadata), and private network hosts, unless `allowPrivateHosts` is set.
+ * Without `options.fetch`, it checks the address of each connection, so a
+ * DNS answer that changes after the check cannot reach a private host.
  *
  * @example
  * ```ts
@@ -325,12 +412,13 @@ export function webTools(options: WebToolsOptions = {}) {
     const timeout = AbortSignal.timeout(timeoutMs)
     const runSignal = context?.abortSignal
     const signal = runSignal ? AbortSignal.any([timeout, runSignal]) : timeout
+    const customFetch = options.fetch
+    const send = customFetch
+      ? (target: URL) =>
+          customFetch(target.href, { redirect: 'manual', signal })
+      : (target: URL) => request(target, { signal, allowPrivateHosts })
     try {
-      const fetched = await follow(url, {
-        fetch: options.fetch ?? fetch,
-        allowPrivateHosts,
-        signal,
-      })
+      const fetched = await follow(url, { send, allowPrivateHosts })
       return await readPage(fetched.response, fetched.url, format)
     } catch (error) {
       if (timeout.aborted) {
diff --git a/packages/ai-harness/src/first-party/coding/workspace.ts b/packages/ai-harness/src/first-party/coding/workspace.ts
index b114bcaaed..eb28aef115 100644
--- a/packages/ai-harness/src/first-party/coding/workspace.ts
+++ b/packages/ai-harness/src/first-party/coding/workspace.ts
@@ -242,12 +242,12 @@ function withEditStyle(
 /**
  * File, shell, and web tools for a coding agent, in `root`: `read_file`,
  * `write_file`, `edit_file` or `patch` (see `editStyle`), `list_files`,
- * `grep`, `bash`, `webfetch`, and `websearch` with a search provider. Edits
- * and `bash` ask for approval through `permissions()`, and each call tells
- * the permission rules which paths or commands it touches. A path outside
- * `root` is refused, or with `outside: 'ask'` the user is asked first. A
- * link that leads out of `root` counts as outside. Other plugins add
- * {@link WorkspaceHooks} to run code after a read or a write.
+ * `grep`, `bash`, `webfetch`, and `websearch` with a search provider. Edits,
+ * `bash`, and `webfetch` ask for approval through `permissions()`, and each
+ * call tells the permission rules which paths or commands it touches. A
+ * path outside `root` is refused, or with `outside: 'ask'` the user is
+ * asked first. A link that leads out of `root` counts as outside. Other
+ * plugins add {@link WorkspaceHooks} to run code after a read or a write.
  *
  * The tools use `backend` for files and commands. The default,
  * `hostBackend`, runs on this machine with the host's authority. Use a
@@ -314,6 +314,11 @@ export function workspaceTools(options: WorkspaceToolsOptions) {
             decision: 'ask',
             kind: 'execute',
           }),
+          // webfetch sends a request to a URL that the model picks, so it
+          // asks. A user rule can allow it. websearch stays allowed.
+          ...(options.web === false
+            ? []
+            : [PermissionRules.item({ tool: 'webfetch', decision: 'ask' })]),
           PermissionResources.item(resources),
         ],
       }
diff --git a/packages/ai-harness/src/first-party/index.ts b/packages/ai-harness/src/first-party/index.ts
index e2e69795b6..7ebced7a39 100644
--- a/packages/ai-harness/src/first-party/index.ts
+++ b/packages/ai-harness/src/first-party/index.ts
@@ -24,3 +24,8 @@ export { compact, usage } from './session-tools'
 export { GoalMet, goal, selectGoal } from './goal'
 export type { Goal } from './goal'
 export { providerKeys } from './provider-keys'
+export { agents, builtInAgents } from './agents'
+export type { AgentProfile } from './agents'
+export { question } from './question'
+export { TitleFailed, title } from './title'
+export { boundToolOutput } from './bound-output'
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index ba67d5f34d..68bd591aa0 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -42,12 +42,18 @@ export type {
 
 export { createExtensionPoint, createPluginEvent } from './extensions'
 // Portable (no Node imports), so edge-safe plugins such as code mode can read
-// the permission rules without the Node-only `./plugins` entry.
-export { PermissionRules, decidePermission } from './first-party/permissions'
+// the permission rules and resources without the Node-only `./plugins` entry.
+export {
+  PermissionResources,
+  PermissionRules,
+  decidePermission,
+} from './first-party/permissions'
 export type {
+  CallResources,
   PermissionDecision,
   PermissionMode,
   PermissionRule,
+  ToolResources,
 } from './first-party/permissions'
 export type { ExtensionItem, ExtensionPoint, PluginEvent } from './extensions'
 
diff --git a/packages/ai-harness/src/plugins.ts b/packages/ai-harness/src/plugins.ts
index a7a7c78f5c..8d7abfe7f7 100644
--- a/packages/ai-harness/src/plugins.ts
+++ b/packages/ai-harness/src/plugins.ts
@@ -595,13 +595,16 @@ export async function mountPlugins(
             extensions.set(point.name, items)
           }
           const source = items
-          // A live view: items contributed after this call appear too.
+          const values = () => source.map((item) => item.value as T)
+          // A live view: items contributed after this call appear too. Array
+          // methods like `filter` also check that an index exists, so every
+          // trap reads the items, not the empty target.
           return new Proxy<Array<T>>([], {
-            get: (_target, key) =>
-              Reflect.get(
-                source.map((item) => item.value as T),
-                key,
-              ),
+            get: (_target, key) => Reflect.get(values(), key),
+            has: (_target, key) => Reflect.has(values(), key),
+            ownKeys: () => Reflect.ownKeys(values()),
+            getOwnPropertyDescriptor: (_target, key) =>
+              Reflect.getOwnPropertyDescriptor(values(), key),
           })
         },
         emit: (event, value) => services.emit(plugin.name, event.name, value),
diff --git a/packages/ai-harness/tests/coding-bash.test.ts b/packages/ai-harness/tests/coding-bash.test.ts
index a40478f6ed..51925353aa 100644
--- a/packages/ai-harness/tests/coding-bash.test.ts
+++ b/packages/ai-harness/tests/coding-bash.test.ts
@@ -1,5 +1,5 @@
 import { tmpdir } from 'node:os'
-import { dirname, join, resolve } from 'node:path'
+import { dirname, join, posix, resolve } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import {
   bashResources,
@@ -190,6 +190,17 @@ describe('bash', () => {
     expect(result).toBe(`${LONG_RESULT}\n[Full output saved to ${path}.]`)
   })
 
+  it('saves it with a POSIX path in a sandbox, also on a Windows host', async () => {
+    const { env, files } = workspace(LONG, { shell: 'sh' })
+    await bash(
+      { ...env, root: '/workspace' },
+      { command: 'test' },
+      { spillDir: '.agent/bash' },
+    )
+    const [path = ''] = files.keys()
+    expect(posix.dirname(path)).toBe('/workspace/.agent/bash')
+  })
+
   it('still gives the output when the save fails', async () => {
     const { env } = workspace(LONG, {
       writeFile: async () => {
diff --git a/packages/ai-harness/tests/coding-formatter.test.ts b/packages/ai-harness/tests/coding-formatter.test.ts
index 8e6590fa7c..c99e4926a9 100644
--- a/packages/ai-harness/tests/coding-formatter.test.ts
+++ b/packages/ai-harness/tests/coding-formatter.test.ts
@@ -1,5 +1,5 @@
 import { tmpdir } from 'node:os'
-import { basename, dirname, join, resolve } from 'node:path'
+import * as nodePath from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness, definePlugin } from '../src'
@@ -17,6 +17,7 @@ import type {
   FormatterOptions,
 } from '../src/first-party/coding/formatter'
 
+const { join, posix, resolve } = nodePath
 const root = resolve(tmpdir(), 'harness-format')
 const encoder = new TextEncoder()
 const decoder = new TextDecoder()
@@ -29,16 +30,25 @@ const ok: Exec = () => ({ exitCode: 0, stdout: '', stderr: '' })
 const quoted = (path: string) => `'${join(root, path)}'`
 
 /**
- * A project in memory that starts as `files`, by path from the root. `exec`
- * answers each command. `runs` lists each command with its options.
+ * A project in memory that starts as `files`, by path from its root. `exec`
+ * answers each command. `runs` lists each command with its options. With
+ * `shell: 'sh'`, the project is at `/workspace` with POSIX paths, like a
+ * Linux sandbox. Else it is at `root` on this machine.
  */
-function project(files: Record<string, string>, exec: Exec = ok) {
+function project(
+  files: Record<string, string>,
+  exec: Exec = ok,
+  shell?: 'sh',
+) {
+  const paths = shell === 'sh' ? posix : nodePath
+  const base = shell === 'sh' ? '/workspace' : root
   const store = new Map<string, Uint8Array>()
   const put = (path: string, content: string) =>
-    store.set(join(root, path), encoder.encode(content))
+    store.set(paths.join(base, path), encoder.encode(content))
   for (const [path, content] of Object.entries(files)) put(path, content)
   const runs: Array<{ command: string; cwd?: string; timeoutMs?: number }> = []
   const backend: WorkspaceBackend = {
+    shell,
     readFile: async (path) => {
       const data = store.get(path)
       if (!data) throw new Error(`No file ${path}`)
@@ -53,14 +63,15 @@ function project(files: Record<string, string>, exec: Exec = ok) {
     },
     readdir: async (dir) =>
       [...store.keys()]
-        .filter((path) => dirname(path) === dir)
-        .map((path) => ({ name: basename(path), type: 'file' as const })),
+        .filter((path) => paths.dirname(path) === dir)
+        .map((path) => ({ name: paths.basename(path), type: 'file' as const })),
     exec: async (command, options) => {
       runs.push({ command, cwd: options?.cwd, timeoutMs: options?.timeoutMs })
       return exec(command)
     },
   }
-  const read = (path: string) => decoder.decode(store.get(join(root, path)))
+  const read = (path: string) =>
+    decoder.decode(store.get(paths.join(base, path)))
   return { backend, runs, put, read }
 }
 
@@ -186,6 +197,21 @@ describe('formatOnWrite', () => {
     expect(skipped.commands).toEqual([])
   })
 
+  it('keeps POSIX paths in a sandbox, also on a Windows host', async () => {
+    const { backend, runs } = project(prettier, ok, 'sh')
+    const afterWrite = formatOnWrite({ root: '/workspace', backend }, () =>
+      undefined,
+    )
+    await afterWrite('/workspace/src/a.ts')
+    expect(runs).toEqual([
+      {
+        command: `npx --no-install prettier --write '/workspace/src/a.ts'`,
+        cwd: '/workspace',
+        timeoutMs: 20_000,
+      },
+    ])
+  })
+
   it('runs no built-in formatter with builtins: false', async () => {
     const { commands } = await formatIn(prettier, 'a.ts', { builtins: false })
     expect(commands).toEqual([])
diff --git a/packages/ai-harness/tests/coding-read.test.ts b/packages/ai-harness/tests/coding-read.test.ts
index 2ef0c6eb7c..bf3d93bacf 100644
--- a/packages/ai-harness/tests/coding-read.test.ts
+++ b/packages/ai-harness/tests/coding-read.test.ts
@@ -1,14 +1,19 @@
 import { tmpdir } from 'node:os'
-import { join, resolve, sep } from 'node:path'
+import { join, posix, resolve, sep } from 'node:path'
 import { beforeAll, describe, expect, it } from 'vitest'
 import { createWorkspaceTools } from '../src/first-party/coding/workspace'
 import type { WorkspaceBackend } from '../src/first-party/coding/backend'
 import type { WorkspaceHooks } from '../src/first-party/workspace-hooks'
 
-/** A backend that keeps files in a map, by absolute path. It runs no commands. */
-function memoryBackend() {
+/**
+ * A backend that keeps files in a map, by absolute path. It runs no
+ * commands. `shell: 'sh'` gives it POSIX paths, like a Linux sandbox.
+ */
+function memoryBackend(shell?: 'sh') {
+  const separator = shell === 'sh' ? posix.sep : sep
   const files = new Map<string, Uint8Array>()
   const backend: WorkspaceBackend = {
+    shell,
     readFile: async (path) => {
       const data = files.get(path)
       if (!data) throw new Error(`No file ${path}`)
@@ -26,13 +31,13 @@ function memoryBackend() {
       return { type: 'file', size: data.length, mtimeMs: 0 }
     },
     readdir: async (path) => {
-      const prefix = path + sep
+      const prefix = path + separator
       const paths = [...files.keys()].filter((file) => file.startsWith(prefix))
       // Like the host, a folder that is not there throws.
       if (paths.length === 0) throw new Error(`No folder ${path}`)
       return paths
         .map((file) => file.slice(prefix.length))
-        .filter((name) => !name.includes(sep))
+        .filter((name) => !name.includes(separator))
         .sort()
         .map((name) => ({ name, type: 'file' as const }))
     },
@@ -48,12 +53,20 @@ const ascii = (text: string) => new TextEncoder().encode(text)
 const put = (path: string, data: Uint8Array | string) =>
   backend.writeFile(join(root, path), data)
 
-/** `read_file` on the memory backend, with `hooks`. */
-function reader(hooks: Array<WorkspaceHooks> = []) {
-  const tool = createWorkspaceTools(
-    { root, backend },
-    { hooks: () => hooks },
-  ).tools.find((item) => item.name === 'read_file')
+/**
+ * `read_file` with `hooks`, in `workspace`. Default: the memory backend at
+ * `root`.
+ */
+function reader(
+  options: {
+    hooks?: Array<WorkspaceHooks>
+    workspace?: { root: string; backend: WorkspaceBackend }
+  } = {},
+) {
+  const { hooks = [], workspace = { root, backend } } = options
+  const tool = createWorkspaceTools(workspace, {
+    hooks: () => hooks,
+  }).tools.find((item) => item.name === 'read_file')
   return async (
     path: string,
     options: { offset?: number; limit?: number } = {},
@@ -265,11 +278,24 @@ describe('read_file on a missing file', () => {
   ])('names similar files for $path', async ({ path, message }) => {
     await expect(read(path)).rejects.toThrow(message)
   })
+
+  it('names them with POSIX paths in a sandbox, also on a Windows host', async () => {
+    const sandbox = memoryBackend('sh')
+    await sandbox.writeFile('/workspace/src/Button.tsx', 'x')
+    const readInSandbox = reader({
+      workspace: { root: '/workspace', backend: sandbox },
+    })
+    await expect(readInSandbox('src/button.tsx')).rejects.toThrow(
+      'File not found: src/button.tsx. Did you mean src/Button.tsx?',
+    )
+  })
 })
 
 describe('read_file hooks', () => {
   it('adds afterRead text to a text file, not to media or binary files', async () => {
-    const readWithHook = reader([{ afterRead: async () => 'hook note' }])
+    const readWithHook = reader({
+      hooks: [{ afterRead: async () => 'hook note' }],
+    })
     await put('hooked.txt', 'hello')
     await put('hooked.png', PNG)
     await put('hooked.bin', BINARY)
diff --git a/packages/ai-harness/tests/coding-snapshots.test.ts b/packages/ai-harness/tests/coding-snapshots.test.ts
index b79020bdd5..5932786e73 100644
--- a/packages/ai-harness/tests/coding-snapshots.test.ts
+++ b/packages/ai-harness/tests/coding-snapshots.test.ts
@@ -114,6 +114,23 @@ async function filesUnder(folder: string) {
 
 const TREE = /^[0-9a-f]{40}$/
 
+/** A backend that keeps no files. Each command goes to `exec`. */
+function fakeBackend(
+  exec: WorkspaceBackend['exec'],
+  shell?: WorkspaceBackend['shell'],
+) {
+  const fail = () => Promise.reject(new Error('Not used.'))
+  const backend: WorkspaceBackend = {
+    shell,
+    readFile: fail,
+    writeFile: async () => undefined,
+    stat: fail,
+    readdir: fail,
+    exec,
+  }
+  return backend
+}
+
 describe.skipIf(!hasGit)('snapshots', () => {
   // Each git call starts a shell and a process, which is slow on Windows.
   it('starts few git commands for each step', async () => {
@@ -297,25 +314,37 @@ describe.skipIf(!hasGit)('snapshots', () => {
   })
 })
 
-describe('snapshots without git', () => {
-  /** A backend where every command fails, like a machine with no git. */
-  function noGitBackend() {
-    const fail = () => Promise.reject(new Error('Not used.'))
-    const backend: WorkspaceBackend = {
-      readFile: fail,
-      writeFile: fail,
-      stat: fail,
-      readdir: fail,
-      exec: async () => ({ exitCode: 127, stdout: '', stderr: 'not found' }),
-    }
-    return backend
-  }
+describe('snapshots on a cmd.exe backend', () => {
+  it('quotes the git arguments for cmd.exe', async () => {
+    const commands: Array<string> = []
+    const backend = fakeBackend(async (command) => {
+      commands.push(command)
+      return { exitCode: 0, stdout: '', stderr: '' }
+    }, 'cmd')
+    const { host, session } = await open({
+      replies: [() => text('Hi.')],
+      backend,
+    })
 
+    await session.prompt('Hello')
+
+    // `git --version`, then the init of the shadow repository.
+    expect(commands[1]).toMatch(/^git init --bare -q \^".+\^"$/)
+    await host.close()
+  })
+})
+
+describe('snapshots without git', () => {
   it('adds no commands, warns once, and the turn still runs', async () => {
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    // Every command fails, like a machine with no git.
     const { host, session, plugin } = await open({
       replies: [() => text('Hi.')],
-      backend: noGitBackend(),
+      backend: fakeBackend(async () => ({
+        exitCode: 127,
+        stdout: '',
+        stderr: 'not found',
+      })),
     })
 
     await session.prompt('Hello')
diff --git a/packages/ai-harness/tests/coding-web.test.ts b/packages/ai-harness/tests/coding-web.test.ts
index 3a0f7c089f..9135b8bb3a 100644
--- a/packages/ai-harness/tests/coding-web.test.ts
+++ b/packages/ai-harness/tests/coding-web.test.ts
@@ -1,16 +1,22 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createServer } from 'node:http'
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
 import { webTools } from '../src/first-party/coding/web'
+import type { AddressInfo } from 'node:net'
 import type {
   SearchProvider,
   WebToolsOptions,
 } from '../src/first-party/coding/web'
 
-// DNS is the network boundary: each test says what a name resolves to.
-const dns = vi.hoisted(() => ({ hosts: new Map<string, Array<string>>() }))
+// DNS is the network boundary. Each lookup of a name takes its next
+// answer, and the last answer repeats.
+const dns = vi.hoisted(() => ({
+  answers: new Map<string, Array<Array<string>>>(),
+}))
 
 vi.mock('node:dns/promises', () => ({
   lookup: async (hostname: string) => {
-    const addresses = dns.hosts.get(hostname)
+    const answers = dns.answers.get(hostname) ?? []
+    const addresses = answers.length > 1 ? answers.shift() : answers[0]
     if (!addresses) throw new Error(`getaddrinfo ENOTFOUND ${hostname}`)
     return addresses.map((address) => ({
       address,
@@ -19,6 +25,11 @@ vi.mock('node:dns/promises', () => ({
   },
 }))
 
+/** `host` resolves to `answers`, one answer a lookup. */
+function resolves(host: string, ...answers: Array<Array<string>>) {
+  dns.answers.set(host, answers)
+}
+
 const PUBLIC_IP = '93.184.216.34'
 const MB5 = 5 * 1024 * 1024
 const REFUSED = 'webfetch does not read private or local hosts'
@@ -66,8 +77,8 @@ function webfetch(
 }
 
 beforeEach(() => {
-  dns.hosts.clear()
-  dns.hosts.set('example.com', [PUBLIC_IP])
+  dns.answers.clear()
+  resolves('example.com', [PUBLIC_IP])
 })
 
 describe('webfetch formats', () => {
@@ -200,7 +211,7 @@ describe('webfetch hosts', () => {
   })
 
   it('refuses a name when DNS gives a private address', async () => {
-    dns.hosts.set('intranet.example', [PUBLIC_IP, '10.1.2.3'])
+    resolves('intranet.example', [PUBLIC_IP, '10.1.2.3'])
     const { fetch, urls } = fakeFetch({})
     await expect(
       run('webfetch', { url: 'https://intranet.example/' }, { fetch }),
@@ -266,6 +277,54 @@ describe('webfetch redirects', () => {
   })
 })
 
+describe('webfetch without a custom fetch', () => {
+  // A real server on 127.0.0.1. `paths` lists the requests that reach it.
+  const paths: Array<string> = []
+  const server = createServer((req, res) => {
+    paths.push(req.url ?? '')
+    if (req.url === '/old') {
+      res.writeHead(302, { location: '/new' }).end()
+      return
+    }
+    res.writeHead(200, { 'content-type': 'text/plain' }).end('hello')
+  })
+  let port = 0
+
+  beforeAll(async () => {
+    await new Promise<void>((done) => server.listen(0, '127.0.0.1', done))
+    const address: AddressInfo | string | null = server.address()
+    port = typeof address === 'object' && address ? address.port : 0
+  })
+
+  afterAll(async () => {
+    await new Promise<void>((done) => server.close(() => done()))
+  })
+
+  beforeEach(() => {
+    paths.length = 0
+  })
+
+  it('refuses a name whose answer turns private when it connects', async () => {
+    // The check sees a public address. The connection sees 127.0.0.1.
+    resolves('rebind.test', [PUBLIC_IP], ['127.0.0.1'])
+    await expect(
+      run('webfetch', { url: `http://rebind.test:${port}/` }),
+    ).rejects.toThrow(`${REFUSED}: rebind.test`)
+    expect(paths).toEqual([])
+  })
+
+  it('reaches a private host with allowPrivateHosts and follows redirects', async () => {
+    resolves('rebind.test', ['127.0.0.1'])
+    const result = await run(
+      'webfetch',
+      { url: `http://rebind.test:${port}/old` },
+      { allowPrivateHosts: true },
+    )
+    expect(result).toBe('hello')
+    expect(paths).toEqual(['/old', '/new'])
+  })
+})
+
 describe('websearch', () => {
   /** A provider that gives back `results` and records each search. */
   function provider(results: Awaited<ReturnType<SearchProvider['search']>>) {
diff --git a/packages/ai-harness/tests/extensions.test.ts b/packages/ai-harness/tests/extensions.test.ts
index 4628ff8d6b..86dfadd34d 100644
--- a/packages/ai-harness/tests/extensions.test.ts
+++ b/packages/ai-harness/tests/extensions.test.ts
@@ -59,6 +59,60 @@ describe('extension points', () => {
     ])
     await host.close()
   })
+
+  it('gives a view that works with every array method', async () => {
+    // Array methods like `filter` and `some` check that an index exists.
+    // A view that hides its indexes makes them skip every item.
+    const Rules = createExtensionPoint<{ tool: string }>('test/rules')
+    let seen: unknown
+    const reader = definePlugin({
+      name: 'test/reader',
+      setup: (ctx) => {
+        const rules = ctx.collect(Rules)
+        return {
+          commands: {
+            rules: defineCommand({
+              description: 'Read the rules',
+              run: () => {
+                seen = {
+                  has: 0 in rules,
+                  filter: rules.filter((rule) => rule.tool === 'bash'),
+                  some: rules.some((rule) => rule.tool === 'bash'),
+                  map: rules.map((rule) => rule.tool),
+                  keys: Object.keys(rules),
+                }
+              },
+            }),
+          },
+        }
+      },
+    })
+    const writer = definePlugin({
+      name: 'test/writer',
+      setup: () => ({ contribute: [Rules.item({ tool: 'bash' })] }),
+    })
+    const { adapter } = mockAdapter([])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/ext-view',
+        adapter,
+        plugins: () => [reader, writer],
+      }),
+      { threadId: 't' },
+    )
+
+    await session.command('rules')
+
+    expect(seen).toEqual({
+      has: true,
+      filter: [{ tool: 'bash' }],
+      some: true,
+      map: ['bash'],
+      keys: ['0'],
+    })
+    await host.close()
+  })
 })
 
 describe('events and state', () => {
diff --git a/packages/ai-harness/tests/instructions.test.ts b/packages/ai-harness/tests/instructions.test.ts
index f66ac2063a..3f49f17fec 100644
--- a/packages/ai-harness/tests/instructions.test.ts
+++ b/packages/ai-harness/tests/instructions.test.ts
@@ -5,7 +5,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness } from '../src'
 import { projectInstructions } from '../src/first-party'
-import { workspaceTools } from '../src/first-party/coding'
+import { hostBackend, workspaceTools } from '../src/first-party/coding'
 import { mockAdapter, text, toolCall } from './helpers'
 import type { AnyTextAdapter, ModelMessage } from '@tanstack/ai'
 import type { HarnessPlugin } from '../src'
@@ -19,30 +19,22 @@ vi.mock('node:os', async (importOriginal) => ({
 }))
 
 // A fake git: real git can take seconds to start on a busy machine, more
-// than the plugin waits. It names `git.branch` for `git rev-parse` in
-// `git.cwd`, and fails for anything else.
-const git = vi.hoisted(() => {
-  const fake: { cwd: string; branch: string | undefined } = {
-    cwd: '',
-    branch: undefined,
-  }
-  return fake
+// than the plugin waits. The plugin runs git with `hostBackend.exec`. The
+// fake names `git.branch` for `git rev-parse` in `git.cwd`, and fails for
+// anything else.
+const git: { cwd: string; branch: string | undefined } = {
+  cwd: '',
+  branch: undefined,
+}
+vi.spyOn(hostBackend, 'exec').mockImplementation(async (command, options) => {
+  const isBranchQuery =
+    command === 'git rev-parse --abbrev-ref HEAD' &&
+    options?.cwd === git.cwd &&
+    git.branch !== undefined
+  return isBranchQuery
+    ? { exitCode: 0, stdout: `${git.branch}\n`, stderr: '' }
+    : { exitCode: 128, stdout: '', stderr: 'git failed' }
 })
-vi.mock('node:child_process', async (importOriginal) => ({
-  ...(await importOriginal<typeof import('node:child_process')>()),
-  exec: (
-    command: string,
-    options: { cwd?: string },
-    callback: (error: Error | null, stdout: string, stderr: string) => void,
-  ) => {
-    const isBranchQuery =
-      command === 'git rev-parse --abbrev-ref HEAD' &&
-      options.cwd === git.cwd &&
-      git.branch !== undefined
-    if (isBranchQuery) callback(null, `${git.branch}\n`, '')
-    else callback(Object.assign(new Error('git failed'), { code: 128 }), '', '')
-  },
-}))
 
 let dir = ''
 /** The `root` of the plugin, in the test folder. */
diff --git a/packages/ai-harness/tests/view.test.ts b/packages/ai-harness/tests/view.test.ts
index 53f685d4b8..6b67272286 100644
--- a/packages/ai-harness/tests/view.test.ts
+++ b/packages/ai-harness/tests/view.test.ts
@@ -281,16 +281,26 @@ describe('createSessionView', () => {
   })
 
   it('stops after dispose', async () => {
-    const { host, session, view } = await openView([])
+    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()
-    const slow = vi.spyOn(session, 'snapshot')
+    snapshot.mockClear()
 
     view.dispose()
     await session.command('ping')
     await new Promise((resolve) => setTimeout(resolve, 20))
 
     expect(view.store.get()).toEqual({ ...before, connection: 'closed' })
-    expect(slow).not.toHaveBeenCalled()
+    expect(snapshot).not.toHaveBeenCalled()
     await expect(view.send('hi')).rejects.toThrow('disposed')
     expect(() => view.approve('x')).toThrow('disposed')
     await host.close()
diff --git a/packages/ai-harness/tests/workspace-tools.test.ts b/packages/ai-harness/tests/workspace-tools.test.ts
index a6f9e3a729..2f8173956f 100644
--- a/packages/ai-harness/tests/workspace-tools.test.ts
+++ b/packages/ai-harness/tests/workspace-tools.test.ts
@@ -14,6 +14,7 @@ import { mockAdapter, text, toolCall } from './helpers'
 import type { PlatformPath } from 'node:path'
 import type { AnyTextAdapter, AnyTool } from '@tanstack/ai'
 import type { HarnessPlugin } from '../src'
+import type { PermissionRule } from '../src/first-party/permissions'
 import type { WorkspaceBackend } from '../src/first-party/coding/backend'
 import type {
   OutsideAccess,
@@ -561,6 +562,56 @@ describe('permission resources', () => {
   })
 })
 
+describe('webfetch approval', () => {
+  /** The page that every request gets, so no request leaves the test. */
+  const fetchPage: typeof fetch = async () =>
+    new Response('fetched body', {
+      headers: { 'content-type': 'text/plain' },
+    })
+
+  /** A session where the model calls webfetch once. `rules` go to permissions(). */
+  async function fetchOnce(rules: Array<PermissionRule> = []) {
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('webfetch', { url: 'https://example.com/' }, 'c1'),
+      () => text('done'),
+    ])
+    const { host, session } = await openSession(adapter, [
+      permissions({ root: '/workspace', rules }),
+      workspaceTools({
+        root: '/workspace',
+        backend: memoryBackend().backend,
+        // So the URL check does no DNS lookup.
+        web: { fetch: fetchPage, allowPrivateHosts: true },
+      }),
+    ])
+    return { host, session, calls }
+  }
+
+  it('asks before webfetch by default', async () => {
+    const { host, session } = await fetchOnce()
+    const turn = session.prompt('read the page')
+    await vi.waitFor(() =>
+      expect(session.snapshot().pendingQuestions).toHaveLength(1),
+    )
+    const [question] = session.snapshot().pendingQuestions
+    if (!question) throw new Error('No question.')
+    expect(question.message).toContain('Allow webfetch')
+    await session.answer(question.questionId, { answer: 'reject' })
+    await turn
+    await host.close()
+  })
+
+  it('runs webfetch without a question when a user rule allows it', async () => {
+    const { host, session, calls } = await fetchOnce([
+      { tool: 'webfetch', decision: 'allow' },
+    ])
+    await session.prompt('read the page')
+    expect(session.snapshot().pendingQuestions).toHaveLength(0)
+    expect(JSON.stringify(calls[1].messages)).toContain('fetched body')
+    await host.close()
+  })
+})
+
 describe('background bash in a session', () => {
   it('notes the end of a job, and starts a turn for it', async () => {
     const { backend } = memoryBackend({
diff --git a/packages/ai-llmgateway/tests/tool-choice-wire.test.ts b/packages/ai-llmgateway/tests/tool-choice-wire.test.ts
new file mode 100644
index 0000000000..b32aeb0030
--- /dev/null
+++ b/packages/ai-llmgateway/tests/tool-choice-wire.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { createLLMGatewayText } from '../src/adapters/text'
+import type { ModelMessage, Tool, ToolChoice } from '@tanstack/ai'
+
+const logger = resolveDebugOption(false)
+const model = 'gpt-5.6-terra'
+const messages: Array<ModelMessage> = [
+  { role: 'user', content: 'Weather in Paris?' },
+]
+const weatherTool: Tool = {
+  name: 'lookup_weather',
+  description: 'Return the forecast for a location',
+}
+
+interface ToolRequest {
+  tools?: Array<Tool>
+  toolChoice?: ToolChoice
+  modelOptions?: { tool_choice: 'none' }
+}
+
+/** Runs one streaming call and returns the JSON body sent over HTTP. */
+async function sentBody(request: ToolRequest) {
+  let body: unknown
+  const fetch: typeof globalThis.fetch = async (_url, init) => {
+    body = JSON.parse(String(init?.body))
+    return new Response('', {
+      headers: { 'content-type': 'text/event-stream' },
+    })
+  }
+  const adapter = createLLMGatewayText(model, 'test-key', { fetch })
+  for await (const _ of adapter.chatStream({
+    logger,
+    model,
+    messages,
+    ...request,
+  })) {
+    // drain
+  }
+  return body
+}
+
+describe('llmGatewayText tool_choice', () => {
+  it('sends required as is', async () => {
+    const body = await sentBody({
+      tools: [weatherTool],
+      toolChoice: 'required',
+    })
+    expect(body).toHaveProperty('tool_choice', 'required')
+  })
+
+  it('sends a named tool as a function choice', async () => {
+    const body = await sentBody({
+      tools: [weatherTool],
+      toolChoice: { type: 'tool', name: 'lookup_weather' },
+    })
+    expect(body).toHaveProperty('tool_choice', {
+      type: 'function',
+      function: { name: 'lookup_weather' },
+    })
+  })
+
+  it('lets a tool_choice in modelOptions win', async () => {
+    const body = await sentBody({
+      tools: [weatherTool],
+      toolChoice: 'required',
+      modelOptions: { tool_choice: 'none' },
+    })
+    expect(body).toHaveProperty('tool_choice', 'none')
+  })
+
+  it('sends no tool_choice when the request has no tools', async () => {
+    const body = await sentBody({ toolChoice: 'required' })
+    expect(body).toHaveProperty('model', model)
+    expect(body).not.toHaveProperty('tool_choice')
+  })
+})
diff --git a/packages/ai-lovable/tests/tool-choice-wire.test.ts b/packages/ai-lovable/tests/tool-choice-wire.test.ts
new file mode 100644
index 0000000000..16df20d88c
--- /dev/null
+++ b/packages/ai-lovable/tests/tool-choice-wire.test.ts
@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { LovableTextAdapter } from '../src/adapters/text'
+import { LovableResponsesTextAdapter } from '../src/adapters/responses-text'
+import type { ModelMessage, Tool, ToolChoice } from '@tanstack/ai'
+
+const logger = resolveDebugOption(false)
+const model = 'openai/gpt-5.5'
+const messages: Array<ModelMessage> = [
+  { role: 'user', content: 'Weather in Paris?' },
+]
+const weatherTool: Tool = {
+  name: 'lookup_weather',
+  description: 'Return the forecast for a location',
+}
+
+interface ToolRequest {
+  tools?: Array<Tool>
+  toolChoice?: ToolChoice
+  modelOptions?: { tool_choice: 'none' }
+}
+
+// The Lovable options types have no `tool_choice`, so it is added here.
+type WithToolChoice = { tool_choice?: 'none' }
+
+type Send = (
+  fetch: typeof globalThis.fetch,
+  request: ToolRequest,
+) => AsyncIterable<unknown>
+
+const adapters = [
+  {
+    adapter: 'Chat Completions',
+    namedChoice: { type: 'function', function: { name: 'lookup_weather' } },
+    send: (fetch, request) =>
+      new LovableTextAdapter<typeof model, WithToolChoice>(
+        { apiKey: 'test-key', fetch },
+        model,
+      ).chatStream({ logger, model, messages, ...request }),
+  },
+  {
+    adapter: 'Responses',
+    namedChoice: { type: 'function', name: 'lookup_weather' },
+    send: (fetch, request) =>
+      new LovableResponsesTextAdapter<typeof model, WithToolChoice>(
+        { apiKey: 'test-key', fetch },
+        model,
+      ).chatStream({ logger, model, messages, ...request }),
+  },
+] satisfies Array<{ adapter: string; send: Send }>
+
+/** Runs one streaming call and returns the JSON body sent over HTTP. */
+async function sentBody(send: Send, request: ToolRequest) {
+  let body: unknown
+  const fetch: typeof globalThis.fetch = async (_url, init) => {
+    body = JSON.parse(String(init?.body))
+    return new Response('', {
+      headers: { 'content-type': 'text/event-stream' },
+    })
+  }
+  for await (const _ of send(fetch, request)) {
+    // drain
+  }
+  return body
+}
+
+describe.each(adapters)(
+  'lovable $adapter tool_choice',
+  ({ send, namedChoice }) => {
+    it('sends required as is', async () => {
+      const body = await sentBody(send, {
+        tools: [weatherTool],
+        toolChoice: 'required',
+      })
+      expect(body).toHaveProperty('tool_choice', 'required')
+    })
+
+    it('sends a named tool as a function choice', async () => {
+      const body = await sentBody(send, {
+        tools: [weatherTool],
+        toolChoice: { type: 'tool', name: 'lookup_weather' },
+      })
+      expect(body).toHaveProperty('tool_choice', namedChoice)
+    })
+
+    it('lets a tool_choice in modelOptions win', async () => {
+      const body = await sentBody(send, {
+        tools: [weatherTool],
+        toolChoice: 'required',
+        modelOptions: { tool_choice: 'none' },
+      })
+      expect(body).toHaveProperty('tool_choice', 'none')
+    })
+
+    it('sends no tool_choice when the request has no tools', async () => {
+      const body = await sentBody(send, { toolChoice: 'required' })
+      expect(body).toHaveProperty('model', model)
+      expect(body).not.toHaveProperty('tool_choice')
+    })
+  },
+)
diff --git a/packages/ai-mcp/skills/ai-mcp/SKILL.md b/packages/ai-mcp/skills/ai-mcp/SKILL.md
index 0fcc432cef..c44edf826c 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`
@@ -55,7 +56,9 @@ The package has these subpaths:
 - `./server/stdio` exports `serveMCPStdio`.
 - `./apps` exports `createMcpAppCallHandler`.
 - `./harness` exports `createHarnessMcpServer`. It serves a TanStack AI
-  harness as an MCP server. See `docs/harness/mcp-server.md`.
+  harness as an MCP server. See `docs/harness/mcp-server.md`. It also
+  exports the `mcp()` harness plugin. See "`mcp()`: MCP servers in a
+  harness" below.
 
 Import `./stdio` and `./server/stdio` only from Node code.
 Those entries use Node I/O.
@@ -815,6 +818,64 @@ 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-5.5'),
+  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,
+          codeMode: true,
+        },
+        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.
+
+Options for each server:
+
+- `timeoutMs`: the limit for each tool list and tool call of that server.
+  The connect itself uses the SDK default.
+- `oauth: true` (`http` only): sign in like `mcpConnector`. The user runs
+  `/connect <name>`, and the tools come after the sign-in.
+- `codeMode: true`: sets `metadata.codeMode` on the tools of the server. The
+  `codeMode()` plugin of `@tanstack/ai-code-mode` then moves each safe tool
+  into `execute_typescript`. A safe tool needs no approval, the permission
+  rules allow it in plan mode, and it declares no `PermissionResources`.
+
 ## 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/harness-plugin.ts b/packages/ai-mcp/src/harness-plugin.ts
new file mode 100644
index 0000000000..e0e1dc3942
--- /dev/null
+++ b/packages/ai-mcp/src/harness-plugin.ts
@@ -0,0 +1,246 @@
+import { defineCommand, definePlugin } from '@tanstack/ai-harness'
+import { createMCPClient } from './client'
+import type { AnyTool } from '@tanstack/ai'
+import type { AnyCommand, PluginPrompt } from '@tanstack/ai-harness'
+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 a tool list or a tool call of this server
+   * can take. 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 createMCPClient({
+                transport,
+                prefix: name,
+                requestOptions: requestOptionsOf(server),
+              })
+              try {
+                const tools = forCodeMode(server, await client.tools())
+                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 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
index 911c94d9a2..1a89008301 100644
--- a/packages/ai-mcp/src/harness.ts
+++ b/packages/ai-mcp/src/harness.ts
@@ -27,6 +27,9 @@ import type {
 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`. */
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..e40d100f7e
--- /dev/null
+++ b/packages/ai-mcp/tests/harness-plugin.test.ts
@@ -0,0 +1,210 @@
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { McpServer } 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, recorder } 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('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('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-mistral/src/adapters/text.ts b/packages/ai-mistral/src/adapters/text.ts
index 9b7673d34a..b7c1bade21 100644
--- a/packages/ai-mistral/src/adapters/text.ts
+++ b/packages/ai-mistral/src/adapters/text.ts
@@ -29,6 +29,7 @@ import type {
   ReasoningRequest,
   ResolvedPromptCache,
   TextOptions,
+  ToolChoice,
 } from '@tanstack/ai'
 import type {
   MISTRAL_CHAT_MODELS,
@@ -137,6 +138,14 @@ function mistralReasoning(
   return resolved.level === 'off' ? {} : { promptMode: 'reasoning' }
 }
 
+/** Maps `chat({ toolChoice })` to the Mistral `toolChoice`. */
+function toMistralToolChoice(
+  choice: ToolChoice,
+): NonNullable<ChatCompletionStreamRequest['toolChoice']> {
+  if (typeof choice === 'string') return choice
+  return { type: 'function', function: { name: choice.name } }
+}
+
 /**
  * The Mistral wire field for `chat({ promptCache })`, by pi's rule. Mistral
  * caches without a flag, so only the key goes out. There is no key for
@@ -1092,7 +1101,15 @@ export class MistralTextAdapter<
       messages.push(this.convertMessageToMistral(message))
     }
 
+    // `chat({ toolChoice })` is sent only when the request has tools. It goes
+    // before the `modelOptions` spread, so a `tool_choice` there wins.
+    const toolChoiceField =
+      tools?.length && options.toolChoice !== undefined
+        ? { toolChoice: toMistralToolChoice(options.toolChoice) }
+        : undefined
+
     return {
+      ...toolChoiceField,
       model: this.rawConfig.requestModel ?? options.model,
       messages: messages,
       temperature: modelOptions?.temperature ?? undefined,
diff --git a/packages/ai-mistral/tests/tool-choice-wire.test.ts b/packages/ai-mistral/tests/tool-choice-wire.test.ts
new file mode 100644
index 0000000000..31fea7b7dc
--- /dev/null
+++ b/packages/ai-mistral/tests/tool-choice-wire.test.ts
@@ -0,0 +1,91 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { createMistralText } from '../src/adapters/text'
+import type { TextOptions, Tool, ToolChoice } from '@tanstack/ai'
+import type { MistralTextProviderOptions } from '../src/adapters/text'
+
+const logger = resolveDebugOption(false)
+const model = 'mistral-large-latest'
+
+const weatherTool: Tool = {
+  name: 'lookup_weather',
+  description: 'Return the forecast for a location',
+}
+
+const sse = `data: ${JSON.stringify({
+  id: 'cmpl-1',
+  model,
+  choices: [{ index: 0, delta: { content: 'Done' }, finish_reason: 'stop' }],
+})}\n\ndata: [DONE]\n\n`
+
+type CallOptions = Pick<
+  TextOptions<MistralTextProviderOptions>,
+  'tools' | 'toolChoice' | 'modelOptions'
+>
+
+/**
+ * Runs one streaming call and returns the JSON body sent over HTTP. The
+ * stream path calls the global `fetch` directly, not the SDK.
+ */
+async function sentBody(options: CallOptions) {
+  let body: unknown
+  vi.stubGlobal('fetch', async (_url: unknown, init?: RequestInit) => {
+    body = JSON.parse(String(init?.body))
+    return new Response(sse, {
+      headers: { 'content-type': 'text/event-stream' },
+    })
+  })
+  const adapter = createMistralText(model, 'test-key')
+  for await (const _ of adapter.chatStream({
+    logger,
+    model,
+    messages: [{ role: 'user', content: 'Weather in Paris?' }],
+    ...options,
+  })) {
+    // drain
+  }
+  return body
+}
+
+interface Row {
+  label: string
+  toolChoice: ToolChoice
+  expected: unknown
+}
+
+const shapes: Array<Row> = [
+  { label: 'auto', toolChoice: 'auto', expected: 'auto' },
+  { label: 'none', toolChoice: 'none', expected: 'none' },
+  { label: 'required', toolChoice: 'required', expected: 'required' },
+  {
+    label: 'a named tool',
+    toolChoice: { type: 'tool', name: 'lookup_weather' },
+    expected: { type: 'function', function: { name: 'lookup_weather' } },
+  },
+]
+
+describe('Mistral tool_choice', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it.each(shapes)('sends $label', async ({ toolChoice, expected }) => {
+    const body = await sentBody({ tools: [weatherTool], toolChoice })
+    expect(body).toHaveProperty('tool_choice', expected)
+  })
+
+  it('sends no tool_choice when the request has no tools', async () => {
+    const body = await sentBody({ toolChoice: 'required' })
+    expect(body).toHaveProperty('model')
+    expect(body).not.toHaveProperty('tool_choice')
+  })
+
+  it('lets a tool_choice in modelOptions win', async () => {
+    const body = await sentBody({
+      tools: [weatherTool],
+      toolChoice: 'required',
+      modelOptions: { tool_choice: 'none' },
+    })
+    expect(body).toHaveProperty('tool_choice', 'none')
+  })
+})
diff --git a/packages/ai-openai/tests/tool-choice-wire.test.ts b/packages/ai-openai/tests/tool-choice-wire.test.ts
new file mode 100644
index 0000000000..f09e102088
--- /dev/null
+++ b/packages/ai-openai/tests/tool-choice-wire.test.ts
@@ -0,0 +1,147 @@
+import { describe, expect, it } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { createOpenaiChat } from '../src/adapters/text'
+import { createOpenaiChatCompletions } from '../src/adapters/text-chat-completions'
+import { azureOpenaiText } from '../src/adapters/azure-text'
+import { openaiCompatible } from '../src/compatible'
+import type { ModelMessage, Tool, ToolChoice } from '@tanstack/ai'
+
+const logger = resolveDebugOption(false)
+const messages: Array<ModelMessage> = [
+  { role: 'user', content: 'Weather in Paris?' },
+]
+const weatherTool: Tool = {
+  name: 'lookup_weather',
+  description: 'Return the forecast for a location',
+}
+
+const chatCompletionsChoice = {
+  type: 'function',
+  function: { name: 'lookup_weather' },
+}
+const responsesChoice = { type: 'function', name: 'lookup_weather' }
+
+interface ToolRequest {
+  tools?: Array<Tool>
+  toolChoice?: ToolChoice
+  modelOptions?: { tool_choice: 'none' }
+}
+
+/** The `chatStream` options of one call: one user message plus the tool fields. */
+function callOptions(model: string, request: ToolRequest) {
+  return { logger, model, messages, ...request }
+}
+
+/** An OpenAI-compatible provider on a test URL, for one API. */
+function compatible(
+  fetch: typeof globalThis.fetch,
+  api: 'chat-completions' | 'responses',
+) {
+  return openaiCompatible({
+    baseURL: 'https://compatible.test/v1',
+    apiKey: 'test-key',
+    models: ['my-model'],
+    api,
+    // A compat runs the request quirks, which edit the request body.
+    compat: { supportsStore: false },
+    fetch,
+  })
+}
+
+type Send = (
+  fetch: typeof globalThis.fetch,
+  request: ToolRequest,
+) => AsyncIterable<unknown>
+
+const adapters = [
+  {
+    adapter: 'openaiText (Responses)',
+    namedChoice: responsesChoice,
+    send: (fetch, request) =>
+      createOpenaiChat('gpt-5.5', 'test-key', { fetch }).chatStream(
+        callOptions('gpt-5.5', request),
+      ),
+  },
+  {
+    adapter: 'openaiChatCompletions',
+    namedChoice: chatCompletionsChoice,
+    send: (fetch, request) =>
+      createOpenaiChatCompletions('gpt-5.5', 'test-key', { fetch }).chatStream(
+        callOptions('gpt-5.5', request),
+      ),
+  },
+  {
+    adapter: 'azureOpenaiText',
+    namedChoice: responsesChoice,
+    send: (fetch, request) =>
+      azureOpenaiText('gpt-5.5', {
+        apiKey: 'test-key',
+        resourceName: 'test-resource',
+        fetch,
+      }).chatStream(callOptions('gpt-5.5', request)),
+  },
+  {
+    adapter: 'openaiCompatible (Chat Completions)',
+    namedChoice: chatCompletionsChoice,
+    send: (fetch, request) =>
+      compatible(fetch, 'chat-completions')('my-model').chatStream(
+        callOptions('my-model', request),
+      ),
+  },
+  {
+    adapter: 'openaiCompatible (Responses)',
+    namedChoice: responsesChoice,
+    send: (fetch, request) =>
+      compatible(fetch, 'responses')('my-model').chatStream(
+        callOptions('my-model', request),
+      ),
+  },
+] satisfies Array<{ adapter: string; send: Send }>
+
+/** Runs one streaming call and returns the JSON body sent over HTTP. */
+async function sentBody(send: Send, request: ToolRequest) {
+  let body: unknown
+  const fetch: typeof globalThis.fetch = async (_url, init) => {
+    body = JSON.parse(String(init?.body))
+    return new Response('', {
+      headers: { 'content-type': 'text/event-stream' },
+    })
+  }
+  for await (const _ of send(fetch, request)) {
+    // drain
+  }
+  return body
+}
+
+describe.each(adapters)('$adapter tool_choice', ({ send, namedChoice }) => {
+  it('sends required as is', async () => {
+    const body = await sentBody(send, {
+      tools: [weatherTool],
+      toolChoice: 'required',
+    })
+    expect(body).toHaveProperty('tool_choice', 'required')
+  })
+
+  it('sends a named tool as a function choice', async () => {
+    const body = await sentBody(send, {
+      tools: [weatherTool],
+      toolChoice: { type: 'tool', name: 'lookup_weather' },
+    })
+    expect(body).toHaveProperty('tool_choice', namedChoice)
+  })
+
+  it('lets a tool_choice in modelOptions win', async () => {
+    const body = await sentBody(send, {
+      tools: [weatherTool],
+      toolChoice: 'required',
+      modelOptions: { tool_choice: 'none' },
+    })
+    expect(body).toHaveProperty('tool_choice', 'none')
+  })
+
+  it('sends no tool_choice when the request has no tools', async () => {
+    const body = await sentBody(send, { toolChoice: 'required' })
+    expect(body).toHaveProperty('model')
+    expect(body).not.toHaveProperty('tool_choice')
+  })
+})
diff --git a/packages/ai-openrouter/src/adapters/responses-text.ts b/packages/ai-openrouter/src/adapters/responses-text.ts
index 593fac111e..53aaaf4b60 100644
--- a/packages/ai-openrouter/src/adapters/responses-text.ts
+++ b/packages/ai-openrouter/src/adapters/responses-text.ts
@@ -56,6 +56,7 @@ import type {
   ModelMessage,
   AdapterYieldChunk,
   TextOptions,
+  ToolChoice,
 } from '@tanstack/ai'
 import type { ExternalResponsesProviderOptions } from '../text/responses-provider-options'
 import type { OpenRouterModelReasoningByName } from '../model-reasoning'
@@ -110,6 +111,14 @@ type ResolveToolCapabilities<TModel extends string> =
     ? NonNullable<OpenRouterChatModelToolCapabilitiesByName[TModel]>
     : readonly []
 
+/** Maps `chat({ toolChoice })` to the OpenRouter Responses `toolChoice`. */
+function toOpenRouterResponsesToolChoice(
+  choice: ToolChoice,
+): NonNullable<ResponsesRequest['toolChoice']> {
+  if (typeof choice === 'string') return choice
+  return { type: 'function', name: choice.name }
+}
+
 /**
  * OpenRouter Responses (beta) Adapter — standalone implementation that talks
  * to OpenRouter's `/v1/responses` (beta) endpoint via the `@openrouter/sdk`
@@ -1838,6 +1847,13 @@ export class OpenRouterResponsesTextAdapter<
     )
     const effort = openRouterEffort(resolved)
 
+    // `chat({ toolChoice })` is sent only when the request has tools. It goes
+    // before the `modelOptions` spread, so a `toolChoice` there wins.
+    const toolChoiceField =
+      tools?.length && options.toolChoice !== undefined
+        ? { toolChoice: toOpenRouterResponsesToolChoice(options.toolChoice) }
+        : undefined
+
     const built: Pick<
       ResponsesRequest,
       | 'model'
@@ -1853,6 +1869,7 @@ export class OpenRouterResponsesTextAdapter<
       | 'text'
       | 'reasoning'
     > = {
+      ...toolChoiceField,
       ...modelOptions,
       model: options.model + variantSuffix,
       // Root `metadata` is observability-only and intentionally not forwarded:
diff --git a/packages/ai-openrouter/src/adapters/text.ts b/packages/ai-openrouter/src/adapters/text.ts
index 4fca52813c..8a8e657230 100644
--- a/packages/ai-openrouter/src/adapters/text.ts
+++ b/packages/ai-openrouter/src/adapters/text.ts
@@ -48,6 +48,7 @@ import type {
   ModelMessage,
   AdapterYieldChunk,
   TextOptions,
+  ToolChoice,
 } from '@tanstack/ai'
 import type {
   OPENROUTER_CHAT_MODELS,
@@ -105,6 +106,14 @@ type ResolveReasoning<TModel extends string> =
       }
     : never
 
+/** Maps `chat({ toolChoice })` to the OpenRouter chat `toolChoice`. */
+function toOpenRouterChatToolChoice(
+  choice: ToolChoice,
+): NonNullable<ChatRequest['toolChoice']> {
+  if (typeof choice === 'string') return choice
+  return { type: 'function', function: { name: choice.name } }
+}
+
 /**
  * OpenRouter Text (Chat) Adapter — standalone implementation that talks to
  * OpenRouter's `/v1/chat/completions` endpoint via the `@openrouter/sdk` SDK.
@@ -1642,6 +1651,13 @@ export class OpenRouterTextAdapter<
           )
         : undefined
 
+    // `chat({ toolChoice })` is sent only when the request has tools. It goes
+    // before the `modelOptions` spread, so a `toolChoice` there wins.
+    const toolChoiceField =
+      tools?.length && options.toolChoice !== undefined
+        ? { toolChoice: toOpenRouterChatToolChoice(options.toolChoice) }
+        : undefined
+
     // `modelOptions` is the sole wire surface: callers set provider-native
     // names (`temperature`, `topP`, `maxCompletionTokens`, `metadata`, etc.)
     // there and they flow through the spread below. Root `metadata` is
@@ -1649,6 +1665,7 @@ export class OpenRouterTextAdapter<
     // forwarded here — it may carry arbitrarily structured values while the
     // SDK validates `chatRequest.metadata` as `Record<string, string>` (#735).
     const request: Omit<ChatRequest, 'stream'> = {
+      ...toolChoiceField,
       ...restModelOptions,
       ...(effort && { reasoning: { effort: effort as ChatRequestEffort } }),
       model: options.model + variantSuffix,
diff --git a/packages/ai-openrouter/tests/tool-choice-wire.test.ts b/packages/ai-openrouter/tests/tool-choice-wire.test.ts
new file mode 100644
index 0000000000..9f6076704c
--- /dev/null
+++ b/packages/ai-openrouter/tests/tool-choice-wire.test.ts
@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest'
+import { HTTPClient } from '@openrouter/sdk'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { OpenRouterTextAdapter } from '../src/adapters/text'
+import { OpenRouterResponsesTextAdapter } from '../src/adapters/responses-text'
+import type { ModelMessage, Tool, ToolChoice } from '@tanstack/ai'
+
+const logger = resolveDebugOption(false)
+const model = 'openai/gpt-5.5'
+const messages: Array<ModelMessage> = [
+  { role: 'user', content: 'Weather in Paris?' },
+]
+const weatherTool: Tool = {
+  name: 'lookup_weather',
+  description: 'Return the forecast for a location',
+}
+
+interface ToolRequest {
+  tools?: Array<Tool>
+  toolChoice?: ToolChoice
+  modelOptions?: { toolChoice: 'none' }
+}
+
+/**
+ * Runs one streaming call through the real SDK and returns the JSON body
+ * sent over HTTP.
+ */
+async function sentBody(
+  api: 'chat' | 'responses',
+  request: ToolRequest,
+): Promise<unknown> {
+  let body: unknown
+  const httpClient = new HTTPClient({
+    fetcher: async (input) => {
+      if (!(input instanceof Request)) throw new Error('Missing SDK request')
+      body = JSON.parse(await input.text())
+      return new Response('', {
+        headers: { 'content-type': 'text/event-stream' },
+      })
+    },
+  })
+  const config = { apiKey: 'test-key', httpClient }
+  const options = { logger, model, messages, ...request }
+  const stream =
+    api === 'chat'
+      ? new OpenRouterTextAdapter(config, model).chatStream(options)
+      : new OpenRouterResponsesTextAdapter(config, model).chatStream(options)
+  for await (const _ of stream) {
+    // drain
+  }
+  return body
+}
+
+const adapters = [
+  {
+    adapter: 'OpenRouterTextAdapter (Chat Completions)',
+    api: 'chat',
+    namedChoice: { type: 'function', function: { name: 'lookup_weather' } },
+  },
+  {
+    adapter: 'OpenRouterResponsesTextAdapter (Responses)',
+    api: 'responses',
+    namedChoice: { type: 'function', name: 'lookup_weather' },
+  },
+] as const
+
+describe.each(adapters)('$adapter tool_choice', ({ api, namedChoice }) => {
+  it('sends required as is', async () => {
+    const body = await sentBody(api, {
+      tools: [weatherTool],
+      toolChoice: 'required',
+    })
+    expect(body).toHaveProperty('tool_choice', 'required')
+  })
+
+  it('sends none as is', async () => {
+    const body = await sentBody(api, {
+      tools: [weatherTool],
+      toolChoice: 'none',
+    })
+    expect(body).toHaveProperty('tool_choice', 'none')
+  })
+
+  it('sends a named tool as a function choice', async () => {
+    const body = await sentBody(api, {
+      tools: [weatherTool],
+      toolChoice: { type: 'tool', name: 'lookup_weather' },
+    })
+    expect(body).toHaveProperty('tool_choice', namedChoice)
+  })
+
+  it('lets a toolChoice in modelOptions win', async () => {
+    const body = await sentBody(api, {
+      tools: [weatherTool],
+      toolChoice: 'required',
+      modelOptions: { toolChoice: 'none' },
+    })
+    expect(body).toHaveProperty('tool_choice', 'none')
+  })
+
+  it('sends no tool_choice when the request has no tools', async () => {
+    const body = await sentBody(api, { toolChoice: 'required' })
+    expect(body).toHaveProperty('model')
+    expect(body).not.toHaveProperty('tool_choice')
+  })
+})
diff --git a/packages/ai-sandbox/src/harness.ts b/packages/ai-sandbox/src/harness.ts
index f320e8588b..9356bc207f 100644
--- a/packages/ai-sandbox/src/harness.ts
+++ b/packages/ai-sandbox/src/harness.ts
@@ -11,6 +11,8 @@ import type {
 import type { SandboxMiddlewareOptions } from './middleware'
 import type { SandboxDefinition } from './sandbox'
 
+export { sandboxWorkspaceBackend } from './workspace-backend'
+
 export interface CodingAgentConfig {
   /** A coding-agent adapter: `claudeCodeText`, `codexText`, `grokBuildText`, `acpCompatibleText`, and more. */
   adapter: AnyTextAdapter
diff --git a/packages/ai-sandbox/src/workspace-backend.ts b/packages/ai-sandbox/src/workspace-backend.ts
new file mode 100644
index 0000000000..d19631bbe6
--- /dev/null
+++ b/packages/ai-sandbox/src/workspace-backend.ts
@@ -0,0 +1,150 @@
+import type { WorkspaceBackend } from '@tanstack/ai-harness/plugins/coding'
+import type { ExecResult, SandboxHandle } from './contracts'
+
+/**
+ * A `WorkspaceBackend` over a live sandbox. With it, `workspaceTools()`
+ * reads and writes files and runs commands in the sandbox, not on this
+ * machine. You start the sandbox before, and you stop it after.
+ *
+ * - Paths are POSIX paths in the sandbox, like `/workspace/src/a.ts`.
+ * - `exec` gives exit code 124 when `timeoutMs` stops a command, and 1 when
+ *   `signal` stops it. A sandbox with `capabilities.killableProcesses` off
+ *   cannot stop the command, so it continues in the sandbox.
+ * - `spawn` is there only when the sandbox has
+ *   `capabilities.backgroundProcesses`.
+ * - `stat` gives `mtimeMs: 0`. The sandbox file system does not give the
+ *   time of the last change.
+ * - There is no `realpath`, so the tools do not check where links go.
+ *
+ * @param handle - The sandbox, from `provider.create()` or `provider.resume()`.
+ *
+ * @example
+ * ```ts
+ * const handle = await localProcessSandbox().create({})
+ * workspaceTools({
+ *   root: '/workspace',
+ *   backend: sandboxWorkspaceBackend(handle),
+ * })
+ * ```
+ */
+export function sandboxWorkspaceBackend(handle: SandboxHandle) {
+  const { fs } = handle
+
+  // The read of the sandbox follows links, so this follows links too. A
+  // path that `readBytes` cannot read is a folder.
+  // ponytail: reads the whole file for its size. Only links, and a sandbox
+  // without `lstat`, come here.
+  const follow: WorkspaceBackend['stat'] = async (path) => {
+    if (!(await fs.exists(path))) return undefined
+    const bytes = await fs.readBytes(path).catch(() => undefined)
+    if (!bytes) return { type: 'dir', size: 0, mtimeMs: 0 }
+    return { type: 'file', size: bytes.byteLength, mtimeMs: 0 }
+  }
+
+  const stat: WorkspaceBackend['stat'] = async (path) => {
+    if (!fs.lstat) return follow(path)
+    const info = await fs.lstat(path)
+    if (!info) return undefined
+    switch (info.type) {
+      case 'file':
+        return { type: 'file', size: info.size, mtimeMs: 0 }
+      case 'dir':
+        return { type: 'dir', size: 0, mtimeMs: 0 }
+      // Like `fs.stat` on the host, a fifo or a socket is an empty file.
+      case 'other':
+        return { type: 'file', size: 0, mtimeMs: 0 }
+      case 'symlink':
+        return follow(path)
+    }
+  }
+
+  const spawn: WorkspaceBackend['spawn'] = (command, options) => {
+    // ponytail: keeps all output in memory, like `hostBackend`.
+    let output = ''
+    const collect = async (stream: AsyncIterable<string>) => {
+      for await (const chunk of stream) output += chunk
+    }
+    const started = handle.process.spawn(command, options)
+    // Wait for the end of the output too, so `output()` is complete.
+    const exited = started
+      .then(async (job) => {
+        const [exitCode] = await Promise.all([
+          job.wait(),
+          collect(job.stdout),
+          collect(job.stderr),
+        ])
+        return { exitCode }
+      })
+      .catch((error: unknown) => {
+        output += String(error)
+        return { exitCode: 1 }
+      })
+    return {
+      wait: () => exited,
+      // Before the process starts, this kills it when it starts.
+      kill: () => {
+        started.then((job) => job.kill()).catch(() => undefined)
+      },
+      output: () => output,
+    }
+  }
+
+  return {
+    shell: 'sh',
+    readFile: (path) => fs.readBytes(path),
+    writeFile: (path, data) => fs.write(path, data),
+    // The sandbox `remove` also removes folders, and it does not fail for a
+    // missing path. This backend removes one file only.
+    remove: async (path) => {
+      const isFile = (await stat(path))?.type === 'file'
+      if (!isFile) throw new Error(`Cannot remove ${path}: no such file.`)
+      await fs.remove(path)
+    },
+    stat,
+    readdir: async (path) => {
+      const entries = await fs.list(path)
+      const { lstat } = fs
+      // ponytail: one `lstat` for each entry, so a big folder is slow in a
+      // remote sandbox. Without `lstat`, a link has the type of its target.
+      return Promise.all(
+        entries.map(async (entry) => {
+          const isLink =
+            lstat !== undefined &&
+            (await lstat(entry.path))?.type === 'symlink'
+          const type = isLink ? ('link' as const) : entry.type
+          return { name: entry.name, type }
+        }),
+      )
+    },
+    exec: (command, options = {}) => {
+      const { cwd, env, timeoutMs, signal } = options
+      const controller = new AbortController()
+      // Stop with an exit code. The first reason wins. The result does not
+      // wait for the sandbox, because some sandboxes cannot stop a command.
+      let stop = (_exitCode: number) => {}
+      const stopped = new Promise<ExecResult>((resolve) => {
+        stop = (exitCode) => {
+          resolve({ exitCode, stdout: '', stderr: '' })
+          controller.abort()
+        }
+      })
+      // A timeout of 0 means no timeout.
+      const timer = timeoutMs
+        ? setTimeout(() => stop(124), timeoutMs)
+        : undefined
+      const onAbort = () => stop(1)
+      signal?.addEventListener('abort', onAbort)
+      if (signal?.aborted) onAbort()
+      const run = handle.process.exec(command, {
+        cwd,
+        env,
+        signal: controller.signal,
+      })
+      return Promise.race([stopped, run]).finally(() => {
+        clearTimeout(timer)
+        signal?.removeEventListener('abort', onAbort)
+      })
+    },
+    ...(handle.capabilities.backgroundProcesses ? { spawn } : {}),
+  } satisfies WorkspaceBackend
+}
diff --git a/packages/ai-sandbox/tests/workspace-backend.test.ts b/packages/ai-sandbox/tests/workspace-backend.test.ts
new file mode 100644
index 0000000000..bb6aceb649
--- /dev/null
+++ b/packages/ai-sandbox/tests/workspace-backend.test.ts
@@ -0,0 +1,456 @@
+import { describe, expect, it } from 'vitest'
+import { EventType } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { workspaceTools } from '@tanstack/ai-harness/plugins/coding'
+import { sandboxWorkspaceBackend } from '../src/harness'
+import { FULL_CAPS, makeFakeHandle } from './fakes'
+import type { AnyTextAdapter, StreamChunk, TextOptions } from '@tanstack/ai'
+import type {
+  ExecResult,
+  SandboxCapabilities,
+  SandboxFs,
+  SandboxHandle,
+} from '../src/contracts'
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+interface FsSeed {
+  files?: Record<string, string>
+  dirs?: Array<string>
+  /** A link and its target. */
+  links?: Record<string, string>
+  /** Paths that are not a file, a folder, or a link, like a fifo. */
+  others?: Array<string>
+}
+
+/**
+ * A sandbox file system in memory, by POSIX path. Like a real sandbox:
+ * `readBytes`, `exists`, and `list` follow links, `lstat` does not, `write`
+ * makes the parent folders, and `remove` is `rm -rf`. With
+ * `withLstat: false`, it has no `lstat`.
+ */
+function memoryFs(seed: FsSeed, withLstat = true) {
+  const files = new Map(
+    Object.entries(seed.files ?? {}).map(([path, text]) => [
+      path,
+      encoder.encode(text),
+    ]),
+  )
+  const dirs = new Set(['/', ...(seed.dirs ?? [])])
+  const links = new Map(Object.entries(seed.links ?? {}))
+  const others = new Set(seed.others ?? [])
+  const target = (path: string) => links.get(path) ?? path
+  const parent = (path: string) => path.slice(0, path.lastIndexOf('/')) || '/'
+  const baseName = (path: string) => path.slice(path.lastIndexOf('/') + 1)
+  const paths = () => [...files.keys(), ...dirs, ...links.keys(), ...others]
+
+  const lstat: SandboxFs['lstat'] = async (path) => {
+    const data = files.get(path)
+    if (links.has(path)) return { type: 'symlink', mode: 0o120777 }
+    if (data) return { type: 'file', mode: 0o100644, size: data.byteLength }
+    if (dirs.has(path)) return { type: 'dir', mode: 0o40755 }
+    if (others.has(path)) return { type: 'other', mode: 0o10644 }
+    return undefined
+  }
+  const readBytes: SandboxFs['readBytes'] = async (path) => {
+    const data = files.get(target(path))
+    if (data) return data
+    throw new Error(`${dirs.has(target(path)) ? 'EISDIR' : 'ENOENT'}: ${path}`)
+  }
+  const fs: SandboxFs = {
+    read: async (path) => decoder.decode(await readBytes(path)),
+    readBytes,
+    write: async (path, data) => {
+      for (let dir = parent(path); !dirs.has(dir); dir = parent(dir)) {
+        dirs.add(dir)
+      }
+      files.set(path, typeof data === 'string' ? encoder.encode(data) : data)
+    },
+    list: async (path) => {
+      if (!dirs.has(target(path))) throw new Error(`ENOENT: ${path}`)
+      const names = paths()
+        .filter((each) => each !== '/' && parent(each) === target(path))
+        .map(baseName)
+        .sort()
+      return names.map((name) => {
+        const type: 'file' | 'dir' = dirs.has(target(`${path}/${name}`))
+          ? 'dir'
+          : 'file'
+        return { name, path: `${path}/${name}`, type }
+      })
+    },
+    mkdir: async (path) => {
+      dirs.add(path)
+    },
+    remove: async (path) => {
+      const gone = paths().filter(
+        (each) => each === path || each.startsWith(`${path}/`),
+      )
+      for (const each of gone) {
+        files.delete(each)
+        dirs.delete(each)
+        links.delete(each)
+      }
+    },
+    rename: () => Promise.reject(new Error('rename is not used')),
+    exists: async (path) => files.has(target(path)) || dirs.has(target(path)),
+    ...(withLstat ? { lstat } : {}),
+  }
+  return { fs, files, dirs }
+}
+
+async function* fromChunks(chunks: Array<string>) {
+  for (const chunk of chunks) yield chunk
+}
+
+/**
+ * Sandbox processes. `exec` answers like a shell that prints the command,
+ * the folder, and `$AGENT`. A `sleep` command never ends, like in a sandbox
+ * that cannot stop it, and only notes the abort in `aborted`.
+ *
+ * `spawn` prints `<command> out` and `<command> err`. `serve` runs until it
+ * is killed, then ends with 143. `nope` does not start.
+ */
+function fakeProcesses() {
+  const aborted: Array<string> = []
+  const killed: Array<string> = []
+  const process: SandboxHandle['process'] = {
+    exec: (command, options = {}) => {
+      if (command.startsWith('sleep')) {
+        options.signal?.addEventListener('abort', () => aborted.push(command))
+        return new Promise<ExecResult>(() => {})
+      }
+      return Promise.resolve({
+        exitCode: 3,
+        stdout: `ran ${command} in ${options.cwd} with AGENT=${options.env?.AGENT}`,
+        stderr: 'warn',
+      })
+    },
+    spawn: async (command) => {
+      if (command === 'nope') throw new Error('nope: not found')
+      let end = () => {}
+      const ended =
+        command === 'serve'
+          ? new Promise<void>((resolve) => (end = resolve))
+          : Promise.resolve()
+      async function* stdout() {
+        yield `${command} out\n`
+        await ended
+      }
+      return {
+        pid: 7,
+        stdout: stdout(),
+        stderr: fromChunks([`${command} err\n`]),
+        stdin: { write: async () => {}, end: async () => {} },
+        wait: async () => {
+          await ended
+          return command === 'serve' ? 143 : 0
+        },
+        kill: async () => {
+          killed.push(command)
+          end()
+        },
+      }
+    },
+  }
+  return { process, aborted, killed }
+}
+
+/** A sandbox handle with `memoryFs` and `fakeProcesses`. */
+function fakeSandbox(
+  seed: FsSeed = {},
+  options: { withLstat?: boolean; caps?: SandboxCapabilities } = {},
+) {
+  const { fs, files, dirs } = memoryFs(seed, options.withLstat)
+  const { process, aborted, killed } = fakeProcesses()
+  const handle: SandboxHandle = {
+    ...makeFakeHandle('sandbox-1', 'fake', options.caps),
+    fs,
+    process,
+  }
+  const backend = sandboxWorkspaceBackend(handle)
+  return { backend, files, dirs, aborted, killed }
+}
+
+const SEED: FsSeed = {
+  files: { '/workspace/a.txt': 'hello' },
+  dirs: ['/workspace', '/workspace/src'],
+  links: {
+    '/workspace/to-file': '/workspace/a.txt',
+    '/workspace/to-src': '/workspace/src',
+    '/workspace/broken': '/workspace/gone',
+  },
+  others: ['/workspace/pipe'],
+}
+
+describe('sandboxWorkspaceBackend files', () => {
+  it('uses POSIX paths and quoting, and checks no links', () => {
+    const { backend } = fakeSandbox()
+    expect(backend.shell).toBe('sh')
+    expect(backend).not.toHaveProperty('realpath')
+  })
+
+  it('reads and writes the bytes of a file in the sandbox', async () => {
+    const { backend, files } = fakeSandbox(SEED)
+    expect(decoder.decode(await backend.readFile('/workspace/a.txt'))).toBe(
+      'hello',
+    )
+    await backend.writeFile('/workspace/new/b.txt', 'made')
+    await backend.writeFile('/workspace/c.bin', new Uint8Array([1, 2]))
+    expect(decoder.decode(files.get('/workspace/new/b.txt'))).toBe('made')
+    expect(files.get('/workspace/c.bin')).toEqual(new Uint8Array([1, 2]))
+  })
+
+  it.each([
+    { withLstat: true, path: '/workspace/a.txt', type: 'file', size: 5 },
+    { withLstat: true, path: '/workspace/src', type: 'dir', size: 0 },
+    { withLstat: true, path: '/workspace/to-file', type: 'file', size: 5 },
+    { withLstat: true, path: '/workspace/to-src', type: 'dir', size: 0 },
+    { withLstat: true, path: '/workspace/pipe', type: 'file', size: 0 },
+    { withLstat: false, path: '/workspace/a.txt', type: 'file', size: 5 },
+    { withLstat: false, path: '/workspace/src', type: 'dir', size: 0 },
+    { withLstat: false, path: '/workspace/to-file', type: 'file', size: 5 },
+  ])(
+    'stat gives a $type of size $size for $path (lstat: $withLstat)',
+    async ({ withLstat, path, type, size }) => {
+      const { backend } = fakeSandbox(SEED, { withLstat })
+      expect(await backend.stat(path)).toEqual({ type, size, mtimeMs: 0 })
+    },
+  )
+
+  it.each([true, false])(
+    'stat gives undefined for a missing path and a broken link (lstat: %s)',
+    async (withLstat) => {
+      const { backend } = fakeSandbox(SEED, { withLstat })
+      expect(await backend.stat('/workspace/gone')).toBeUndefined()
+      expect(await backend.stat('/workspace/broken')).toBeUndefined()
+    },
+  )
+
+  it('lists a folder with links as links when the sandbox has lstat', async () => {
+    const { backend } = fakeSandbox(SEED)
+    expect(await backend.readdir('/workspace')).toEqual([
+      { name: 'a.txt', type: 'file' },
+      { name: 'broken', type: 'link' },
+      { name: 'pipe', type: 'file' },
+      { name: 'src', type: 'dir' },
+      { name: 'to-file', type: 'link' },
+      { name: 'to-src', type: 'link' },
+    ])
+  })
+
+  it('lists a link with the type of its target when the sandbox has no lstat', async () => {
+    const { backend } = fakeSandbox(SEED, { withLstat: false })
+    expect(await backend.readdir('/workspace')).toEqual([
+      { name: 'a.txt', type: 'file' },
+      { name: 'broken', type: 'file' },
+      { name: 'pipe', type: 'file' },
+      { name: 'src', type: 'dir' },
+      { name: 'to-file', type: 'file' },
+      { name: 'to-src', type: 'dir' },
+    ])
+  })
+
+  it('removes one file, and refuses a folder or a missing file', async () => {
+    const { backend, files, dirs } = fakeSandbox({
+      files: { '/workspace/a.txt': 'a', '/workspace/src/b.ts': 'b' },
+      dirs: ['/workspace', '/workspace/src'],
+    })
+    await backend.remove('/workspace/a.txt')
+    expect(files.has('/workspace/a.txt')).toBe(false)
+    await expect(backend.remove('/workspace/src')).rejects.toThrow(
+      'Cannot remove /workspace/src: no such file.',
+    )
+    await expect(backend.remove('/workspace/gone')).rejects.toThrow(
+      'Cannot remove /workspace/gone: no such file.',
+    )
+    expect(dirs.has('/workspace/src')).toBe(true)
+    expect(files.has('/workspace/src/b.ts')).toBe(true)
+  })
+})
+
+describe('sandboxWorkspaceBackend exec', () => {
+  it('runs a command in the sandbox with the folder and the env', async () => {
+    const { backend } = fakeSandbox()
+    expect(
+      await backend.exec('ls', { cwd: '/workspace', env: { AGENT: '1' } }),
+    ).toEqual({
+      exitCode: 3,
+      stdout: 'ran ls in /workspace with AGENT=1',
+      stderr: 'warn',
+    })
+  })
+
+  it('stops a command at the timeout with exit code 124', async () => {
+    const { backend, aborted } = fakeSandbox()
+    expect(await backend.exec('sleep 60', { timeoutMs: 20 })).toEqual({
+      exitCode: 124,
+      stdout: '',
+      stderr: '',
+    })
+    expect(aborted).toEqual(['sleep 60'])
+  })
+
+  it('stops a command with exit code 1 when the signal aborts', async () => {
+    const { backend, aborted } = fakeSandbox()
+    const controller = new AbortController()
+    const result = backend.exec('sleep 60', {
+      timeoutMs: 60_000,
+      signal: controller.signal,
+    })
+    controller.abort()
+    expect(await result).toEqual({ exitCode: 1, stdout: '', stderr: '' })
+    expect(aborted).toEqual(['sleep 60'])
+  })
+})
+
+describe('sandboxWorkspaceBackend spawn', () => {
+  it('gives the exit code and all output of a background command', async () => {
+    const { backend } = fakeSandbox()
+    const job = backend.spawn?.('build', { cwd: '/workspace' })
+    expect(await job?.wait()).toEqual({ exitCode: 0 })
+    expect(job?.output()).toBe('build out\nbuild err\n')
+  })
+
+  it('kills a background command, also before it started', async () => {
+    const { backend, killed } = fakeSandbox()
+    const job = backend.spawn?.('serve')
+    job?.kill()
+    expect(await job?.wait()).toEqual({ exitCode: 143 })
+    expect(killed).toEqual(['serve'])
+    expect(job?.output()).toBe('serve out\nserve err\n')
+  })
+
+  it('gives exit code 1 and the error when the command does not start', async () => {
+    const { backend } = fakeSandbox()
+    const job = backend.spawn?.('nope')
+    expect(await job?.wait()).toEqual({ exitCode: 1 })
+    expect(job?.output()).toBe('Error: nope: not found')
+  })
+
+  it('has no spawn when the sandbox cannot run background processes', () => {
+    const { backend } = fakeSandbox(
+      {},
+      { caps: { ...FULL_CAPS, backgroundProcesses: false } },
+    )
+    expect(backend.spawn).toBeUndefined()
+  })
+})
+
+const now = () => Date.now()
+
+/** The chunks of one model reply: `chunks` in one run. */
+function reply(
+  finishReason: 'tool_calls' | 'stop',
+  chunks: Array<StreamChunk> = [],
+) {
+  const all: Array<StreamChunk> = [
+    {
+      type: EventType.RUN_STARTED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: now(),
+    },
+    ...chunks,
+    {
+      type: EventType.RUN_FINISHED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: now(),
+      metadata: { tanstack: { finishReason } },
+    },
+  ]
+  return all
+}
+
+/** The chunks of one model reply that calls `tool` with `args`. */
+function toolCall(id: string, tool: string, args: Record<string, unknown>) {
+  return reply('tool_calls', [
+    {
+      type: EventType.TOOL_CALL_START,
+      toolCallId: id,
+      toolCallName: tool,
+      timestamp: now(),
+    },
+    {
+      type: EventType.TOOL_CALL_ARGS,
+      toolCallId: id,
+      delta: JSON.stringify(args),
+      timestamp: now(),
+    },
+    { type: EventType.TOOL_CALL_END, toolCallId: id, timestamp: now() },
+  ])
+}
+
+/**
+ * A model that gives `replies` in order, then ends the turn. `calls` has the
+ * options of each call.
+ */
+function scriptedModel(replies: Array<Array<StreamChunk>>) {
+  const calls: Array<TextOptions> = []
+  const adapter: AnyTextAdapter = {
+    kind: 'text',
+    name: 'scripted',
+    model: 'scripted',
+    '~types': {
+      providerOptions: {},
+      inputModalities: ['text'],
+      messageMetadataByModality: {},
+      toolCapabilities: [],
+      toolCallMetadata: undefined,
+      systemPromptMetadata: undefined,
+    },
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+    chatStream: (options) => {
+      calls.push(options)
+      const chunks = replies[calls.length - 1] ?? reply('stop')
+      return (async function* () {
+        yield* chunks
+      })()
+    },
+  }
+  return { adapter, calls }
+}
+
+describe('sandboxWorkspaceBackend with workspaceTools', () => {
+  it('writes and reads a file under /workspace, with POSIX paths for the model', async () => {
+    const sandbox = fakeSandbox({ dirs: ['/workspace'] })
+    const { adapter, calls } = scriptedModel([
+      toolCall('c1', 'write_file', {
+        path: 'src/a.ts',
+        content: 'export const a = 1\n',
+      }),
+      toolCall('c2', 'read_file', { path: 'src/a.ts' }),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/sandbox-workspace',
+        adapter,
+        plugins: () => [
+          workspaceTools({
+            root: '/workspace',
+            backend: sandbox.backend,
+            web: false,
+          }),
+        ],
+      }),
+      { threadId: 't' },
+    )
+    await session.prompt('work')
+    await host.close()
+
+    expect(decoder.decode(sandbox.files.get('/workspace/src/a.ts'))).toBe(
+      'export const a = 1\n',
+    )
+    const results = calls[2]?.messages
+      .filter((message) => message.role === 'tool')
+      .map((message) => message.content)
+    expect(results).toEqual(['Wrote src/a.ts.', '1\texport const a = 1'])
+    expect(calls[0]?.systemPrompts).toContainEqual(
+      expect.stringContaining('Your workspace is /workspace.'),
+    )
+  })
+})
diff --git a/packages/ai-vercel-gateway/tests/tool-choice-wire.test.ts b/packages/ai-vercel-gateway/tests/tool-choice-wire.test.ts
new file mode 100644
index 0000000000..6ca2e706d3
--- /dev/null
+++ b/packages/ai-vercel-gateway/tests/tool-choice-wire.test.ts
@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { VercelGatewayTextAdapter } from '../src/adapters/text'
+import { VercelGatewayResponsesTextAdapter } from '../src/adapters/responses-text'
+import type { ModelMessage, Tool, ToolChoice } from '@tanstack/ai'
+
+const logger = resolveDebugOption(false)
+const model = 'openai/gpt-5.5'
+const messages: Array<ModelMessage> = [
+  { role: 'user', content: 'Weather in Paris?' },
+]
+const weatherTool: Tool = {
+  name: 'lookup_weather',
+  description: 'Return the forecast for a location',
+}
+
+interface ToolRequest {
+  tools?: Array<Tool>
+  toolChoice?: ToolChoice
+  modelOptions?: { tool_choice: 'none' }
+}
+
+// The gateway options types have no `tool_choice`, so it is added here.
+type WithToolChoice = { tool_choice?: 'none' }
+
+type Send = (
+  fetch: typeof globalThis.fetch,
+  request: ToolRequest,
+) => AsyncIterable<unknown>
+
+const adapters = [
+  {
+    adapter: 'Chat Completions',
+    namedChoice: { type: 'function', function: { name: 'lookup_weather' } },
+    send: (fetch, request) =>
+      new VercelGatewayTextAdapter<typeof model, WithToolChoice>(
+        { apiKey: 'test-key', fetch },
+        model,
+      ).chatStream({ logger, model, messages, ...request }),
+  },
+  {
+    adapter: 'Responses',
+    namedChoice: { type: 'function', name: 'lookup_weather' },
+    send: (fetch, request) =>
+      new VercelGatewayResponsesTextAdapter<typeof model, WithToolChoice>(
+        { apiKey: 'test-key', fetch },
+        model,
+      ).chatStream({ logger, model, messages, ...request }),
+  },
+] satisfies Array<{ adapter: string; send: Send }>
+
+/** Runs one streaming call and returns the JSON body sent over HTTP. */
+async function sentBody(send: Send, request: ToolRequest) {
+  let body: unknown
+  const fetch: typeof globalThis.fetch = async (_url, init) => {
+    body = JSON.parse(String(init?.body))
+    return new Response('', {
+      headers: { 'content-type': 'text/event-stream' },
+    })
+  }
+  for await (const _ of send(fetch, request)) {
+    // drain
+  }
+  return body
+}
+
+describe.each(adapters)(
+  'vercel gateway $adapter tool_choice',
+  ({ send, namedChoice }) => {
+    it('sends required as is', async () => {
+      const body = await sentBody(send, {
+        tools: [weatherTool],
+        toolChoice: 'required',
+      })
+      expect(body).toHaveProperty('tool_choice', 'required')
+    })
+
+    it('sends a named tool as a function choice', async () => {
+      const body = await sentBody(send, {
+        tools: [weatherTool],
+        toolChoice: { type: 'tool', name: 'lookup_weather' },
+      })
+      expect(body).toHaveProperty('tool_choice', namedChoice)
+    })
+
+    it('lets a tool_choice in modelOptions win', async () => {
+      const body = await sentBody(send, {
+        tools: [weatherTool],
+        toolChoice: 'required',
+        modelOptions: { tool_choice: 'none' },
+      })
+      expect(body).toHaveProperty('tool_choice', 'none')
+    })
+
+    it('sends no tool_choice when the request has no tools', async () => {
+      const body = await sentBody(send, { toolChoice: 'required' })
+      expect(body).toHaveProperty('model', model)
+      expect(body).not.toHaveProperty('tool_choice')
+    })
+  },
+)
diff --git a/packages/openai-base/src/adapters/chat-completions-text.ts b/packages/openai-base/src/adapters/chat-completions-text.ts
index f2edc8359d..c45292d03d 100644
--- a/packages/openai-base/src/adapters/chat-completions-text.ts
+++ b/packages/openai-base/src/adapters/chat-completions-text.ts
@@ -26,6 +26,7 @@ import type {
   StructuredOutputCompatibility,
 } from '../utils/schema-converter'
 import { buildChatCompletionsUsage } from '../usage'
+import { toChatCompletionsToolChoice } from '../tools/tool-choice'
 import { convertToolsToChatCompletionsFormat } from './chat-completions-tool-converter'
 import type OpenAI from 'openai'
 import type {
@@ -1466,11 +1467,19 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
       this.modelReasoning(options.model),
     )
 
+    // `chat({ toolChoice })` is sent only when the request has tools. It goes
+    // before the `modelOptions` spread, so a `tool_choice` there wins.
+    const toolChoiceField =
+      tools?.length && options.toolChoice !== undefined
+        ? { tool_choice: toChatCompletionsToolChoice(options.toolChoice) }
+        : undefined
+
     // `modelOptions` is the sole sampling surface: callers set provider-native
     // wire names (`temperature`, `top_p`, `max_tokens`/`max_completion_tokens`)
     // there and they flow through the spread below. The root
     // `temperature`/`topP`/`maxTokens` fields are intentionally NOT read here.
     const params: ChatCompletionCreateParamsStreaming = {
+      ...toolChoiceField,
       ...modelOptions,
       model: options.model,
       messages,
diff --git a/packages/openai-base/src/adapters/responses-text.ts b/packages/openai-base/src/adapters/responses-text.ts
index 4beed6cba7..59eb2638d6 100644
--- a/packages/openai-base/src/adapters/responses-text.ts
+++ b/packages/openai-base/src/adapters/responses-text.ts
@@ -30,6 +30,7 @@ import type {
 } from '../utils/schema-converter'
 import { buildResponsesUsage } from '../usage'
 import { getOpenAIProviderToolKind } from '../tools/openai-provider-tool'
+import { toResponsesToolChoice } from '../tools/tool-choice'
 import { convertToolsToResponsesFormat } from './responses-tool-converter'
 import {
   hostedShellCallIds,
@@ -2289,6 +2290,13 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         }
       : undefined
 
+    // `chat({ toolChoice })` is sent only when the request has tools. It goes
+    // before the `modelOptions` spread, so a `tool_choice` there wins.
+    const toolChoiceField =
+      tools?.length && options.toolChoice !== undefined
+        ? { tool_choice: toResponsesToolChoice(options.toolChoice) }
+        : undefined
+
     // `modelOptions` is the sole sampling surface: `temperature`, `top_p`, and
     // `max_output_tokens` live there (typed via OpenAISamplingOptions) and are
     // spread first. Engine-managed fields (`model`, `metadata`, `instructions`,
@@ -2296,6 +2304,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
     // always win over any same-named key a caller happened to put in
     // `modelOptions`.
     const params: Omit<ResponseCreateParams, 'stream'> = {
+      ...toolChoiceField,
       ...modelOptions,
       model: options.model,
       ...(options.metadata !== undefined && { metadata: options.metadata }),
diff --git a/packages/openai-base/src/tools/index.ts b/packages/openai-base/src/tools/index.ts
index da3911a716..0f41388c62 100644
--- a/packages/openai-base/src/tools/index.ts
+++ b/packages/openai-base/src/tools/index.ts
@@ -35,7 +35,11 @@ export * from './image-generation-tool'
 export * from './local-shell-tool'
 export * from './mcp-tool'
 export * from './shell-tool'
-export type * from './tool-choice'
+export {
+  toChatCompletionsToolChoice,
+  toResponsesToolChoice,
+  type ToolChoice,
+} from './tool-choice'
 export * from './tool-converter'
 export * from './web-search-preview-tool'
 export * from './web-search-tool'
diff --git a/packages/openai-base/src/tools/tool-choice.ts b/packages/openai-base/src/tools/tool-choice.ts
index 139b80f26e..644e49c72e 100644
--- a/packages/openai-base/src/tools/tool-choice.ts
+++ b/packages/openai-base/src/tools/tool-choice.ts
@@ -1,3 +1,23 @@
+import type { ToolChoice as CoreToolChoice } from '@tanstack/ai'
+
+/**
+ * Maps the `chat({ toolChoice })` value to the Chat Completions
+ * `tool_choice` wire value.
+ */
+export function toChatCompletionsToolChoice(choice: CoreToolChoice) {
+  if (typeof choice === 'string') return choice
+  return { type: 'function' as const, function: { name: choice.name } }
+}
+
+/**
+ * Maps the `chat({ toolChoice })` value to the Responses `tool_choice` wire
+ * value.
+ */
+export function toResponsesToolChoice(choice: CoreToolChoice) {
+  if (typeof choice === 'string') return choice
+  return { type: 'function' as const, name: choice.name }
+}
+
 interface MCPToolChoice {
   type: 'mcp'
   server_label: string
diff --git a/packages/openai-base/tests/tool-choice-wire.test.ts b/packages/openai-base/tests/tool-choice-wire.test.ts
new file mode 100644
index 0000000000..17df60f310
--- /dev/null
+++ b/packages/openai-base/tests/tool-choice-wire.test.ts
@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest'
+import OpenAI from 'openai'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { OpenAIBaseChatCompletionsTextAdapter } from '../src/adapters/chat-completions-text'
+import { OpenAIBaseResponsesTextAdapter } from '../src/adapters/responses-text'
+import type { TextOptions, Tool } from '@tanstack/ai'
+
+const logger = resolveDebugOption(false)
+const model = 'gpt-5.5'
+
+const weatherTool: Tool = {
+  name: 'lookup_weather',
+  description: 'Return the forecast for a location',
+}
+
+class Completions extends OpenAIBaseChatCompletionsTextAdapter<string> {}
+class Responses extends OpenAIBaseResponsesTextAdapter<string> {}
+
+const completionsDone = {
+  id: 'response-1',
+  model,
+  choices: [{ delta: { content: 'Done' }, finish_reason: 'stop' }],
+}
+const responsesDone = {
+  type: 'response.completed',
+  response: {
+    id: 'response-1',
+    model,
+    status: 'completed',
+    output: [
+      {
+        type: 'message',
+        id: 'message-1',
+        role: 'assistant',
+        content: [{ type: 'output_text', text: 'Done', annotations: [] }],
+      },
+    ],
+  },
+}
+
+const apis = [
+  {
+    api: 'Chat Completions',
+    adapter: (client: OpenAI) => new Completions(model, 'openai', client),
+    sse: `data: ${JSON.stringify(completionsDone)}\n\ndata: [DONE]\n\n`,
+    namedChoice: { type: 'function', function: { name: 'lookup_weather' } },
+  },
+  {
+    api: 'Responses',
+    adapter: (client: OpenAI) => new Responses(model, 'openai', client),
+    sse: `data: ${JSON.stringify(responsesDone)}\n\n`,
+    namedChoice: { type: 'function', name: 'lookup_weather' },
+  },
+]
+
+/** Runs one streaming call and returns the JSON body sent over HTTP. */
+async function sentBody(
+  { adapter, sse }: (typeof apis)[number],
+  request: Pick<TextOptions, 'tools' | 'toolChoice' | 'modelOptions'>,
+) {
+  let body: unknown
+  const client = new OpenAI({
+    apiKey: 'test-key',
+    fetch: async (_url, init) => {
+      body = JSON.parse(String(init?.body))
+      return new Response(sse, {
+        headers: { 'content-type': 'text/event-stream' },
+      })
+    },
+  })
+  for await (const _ of adapter(client).chatStream({
+    logger,
+    model,
+    messages: [{ role: 'user', content: 'Weather in Paris?' }],
+    ...request,
+  })) {
+    // drain
+  }
+  return body
+}
+
+describe.each(apis)('$api tool_choice', (api) => {
+  it.each(['auto', 'none', 'required'] as const)(
+    'sends %s as is',
+    async (choice) => {
+      const body = await sentBody(api, {
+        tools: [weatherTool],
+        toolChoice: choice,
+      })
+      expect(body).toHaveProperty('tool_choice', choice)
+    },
+  )
+
+  it('sends a named tool as a function choice', async () => {
+    const body = await sentBody(api, {
+      tools: [weatherTool],
+      toolChoice: { type: 'tool', name: 'lookup_weather' },
+    })
+    expect(body).toHaveProperty('tool_choice', api.namedChoice)
+  })
+
+  it('lets a tool_choice in modelOptions win', async () => {
+    const body = await sentBody(api, {
+      tools: [weatherTool],
+      toolChoice: 'required',
+      modelOptions: { tool_choice: 'none' },
+    })
+    expect(body).toHaveProperty('tool_choice', 'none')
+  })
+
+  it('sends no tool_choice when the request has no tools', async () => {
+    const body = await sentBody(api, { toolChoice: 'required' })
+    expect(body).not.toHaveProperty('tool_choice')
+  })
+})

From 1d6c666f9efeff00b3ac7ca93e87e5cf70d8cc50 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 15:00:03 +0200
Subject: [PATCH 247/286] feat(examples): add Batman-themed harness CLI

Add examples/harness-cli-batman as a themed copy of the harness CLI.
It uses a bat splash, a yellow header, and a separate save folder.
Voice input times out after 45 seconds and Esc cancels it.
---
 examples/README.md                            |   16 +
 examples/harness-cli-batman/.env.example      |   27 +
 examples/harness-cli-batman/.gitignore        |    6 +
 examples/harness-cli-batman/README.md         |   49 +
 examples/harness-cli-batman/package.json      |   45 +
 .../harness-cli-batman/playground/.gitkeep    |    0
 .../harness-cli-batman/playground/AGENTS.md   |    1 +
 examples/harness-cli-batman/src/cli.ts        |   55 +
 .../harness-cli-batman/src/credentials.ts     |   65 ++
 examples/harness-cli-batman/src/effort.ts     |   57 +
 examples/harness-cli-batman/src/env.ts        |   10 +
 examples/harness-cli-batman/src/harness.ts    |  478 ++++++++
 .../src/marked-terminal.d.ts                  |   10 +
 examples/harness-cli-batman/src/media.ts      |  193 +++
 .../src/screen/batman-art.ts                  |  134 +++
 .../harness-cli-batman/src/screen/commands.ts |   23 +
 .../harness-cli-batman/src/screen/editor.ts   |  124 ++
 .../harness-cli-batman/src/screen/footer.tsx  |   76 ++
 .../harness-cli-batman/src/screen/keys.ts     |   71 ++
 .../harness-cli-batman/src/screen/markdown.ts |   61 +
 .../harness-cli-batman/src/screen/media.ts    |  116 ++
 .../harness-cli-batman/src/screen/menu.tsx    |   59 +
 .../harness-cli-batman/src/screen/parts.tsx   |  254 ++++
 .../harness-cli-batman/src/screen/paths.ts    |   70 ++
 .../harness-cli-batman/src/screen/splash.tsx  |  155 +++
 .../harness-cli-batman/src/screen/status.tsx  |   98 ++
 .../harness-cli-batman/src/screen/theme.ts    |   20 +
 examples/harness-cli-batman/src/sessions.ts   |  155 +++
 examples/harness-cli-batman/src/store.ts      |   51 +
 examples/harness-cli-batman/src/tui.tsx       | 1038 +++++++++++++++++
 examples/harness-cli-batman/src/voice.ts      |  448 +++++++
 examples/harness-cli-batman/src/workdir.ts    |    6 +
 examples/harness-cli-batman/tsconfig.json     |   14 +
 pnpm-lock.yaml                                |  299 ++++-
 34 files changed, 4220 insertions(+), 64 deletions(-)
 create mode 100644 examples/harness-cli-batman/.env.example
 create mode 100644 examples/harness-cli-batman/.gitignore
 create mode 100644 examples/harness-cli-batman/README.md
 create mode 100644 examples/harness-cli-batman/package.json
 create mode 100644 examples/harness-cli-batman/playground/.gitkeep
 create mode 100644 examples/harness-cli-batman/playground/AGENTS.md
 create mode 100644 examples/harness-cli-batman/src/cli.ts
 create mode 100644 examples/harness-cli-batman/src/credentials.ts
 create mode 100644 examples/harness-cli-batman/src/effort.ts
 create mode 100644 examples/harness-cli-batman/src/env.ts
 create mode 100644 examples/harness-cli-batman/src/harness.ts
 create mode 100644 examples/harness-cli-batman/src/marked-terminal.d.ts
 create mode 100644 examples/harness-cli-batman/src/media.ts
 create mode 100644 examples/harness-cli-batman/src/screen/batman-art.ts
 create mode 100644 examples/harness-cli-batman/src/screen/commands.ts
 create mode 100644 examples/harness-cli-batman/src/screen/editor.ts
 create mode 100644 examples/harness-cli-batman/src/screen/footer.tsx
 create mode 100644 examples/harness-cli-batman/src/screen/keys.ts
 create mode 100644 examples/harness-cli-batman/src/screen/markdown.ts
 create mode 100644 examples/harness-cli-batman/src/screen/media.ts
 create mode 100644 examples/harness-cli-batman/src/screen/menu.tsx
 create mode 100644 examples/harness-cli-batman/src/screen/parts.tsx
 create mode 100644 examples/harness-cli-batman/src/screen/paths.ts
 create mode 100644 examples/harness-cli-batman/src/screen/splash.tsx
 create mode 100644 examples/harness-cli-batman/src/screen/status.tsx
 create mode 100644 examples/harness-cli-batman/src/screen/theme.ts
 create mode 100644 examples/harness-cli-batman/src/sessions.ts
 create mode 100644 examples/harness-cli-batman/src/store.ts
 create mode 100644 examples/harness-cli-batman/src/tui.tsx
 create mode 100644 examples/harness-cli-batman/src/voice.ts
 create mode 100644 examples/harness-cli-batman/src/workdir.ts
 create mode 100644 examples/harness-cli-batman/tsconfig.json

diff --git a/examples/README.md b/examples/README.md
index f2b0737244..c450dd095e 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -37,6 +37,22 @@ OPENAI_API_KEY=... pnpm --filter harness-cli-example start
 
 ---
 
+### Batman CLI
+
+A Batman-themed copy of the harness CLI. Same stack, yellow header, bat splash, and a separate save folder.
+
+**Path:** `examples/harness-cli-batman`
+
+**Getting Started:**
+
+```bash
+pnpm --filter harness-cli-batman start
+```
+
+📖 [Full Documentation](harness-cli-batman/README.md)
+
+---
+
 ### Basic Chat
 
 A slim TanStack Start chat. One provider (OpenRouter). You paste your own key.
diff --git a/examples/harness-cli-batman/.env.example b/examples/harness-cli-batman/.env.example
new file mode 100644
index 0000000000..6795c68083
--- /dev/null
+++ b/examples/harness-cli-batman/.env.example
@@ -0,0 +1,27 @@
+# Optional. The app needs no .env file: run /connect openai (paste a key) or
+# /connect openrouter (sign in with the browser) inside the app.
+# This file is a shortcut for development. Copy it to .env. An env var works
+# when no key is saved with /connect.
+# OpenAI: the gpt models, images, speech, Sora video, and voice input.
+OPENAI_API_KEY=
+# Anthropic: the claude models.
+ANTHROPIC_API_KEY=
+# xAI: the grok model, video with Grok Imagine (it wins over Sora), and voice.
+XAI_API_KEY=
+# fal: songs and sound effects.
+FAL_KEY=
+# OpenRouter: the openrouter-gpt and openrouter-claude models.
+OPENROUTER_API_KEY=
+# Claude Code and Codex turn on when `claude` and `codex` are on the PATH.
+# They use your own `claude login` and `codex login`. Set 0 to turn them off.
+CODING_AGENTS=
+# Codex uses the model and sandbox_mode of ~/.codex/config.toml. These win.
+CODEX_MODEL=
+CODEX_SANDBOX_MODE=
+# Voice input records the microphone with ffmpeg. The first recording picks
+# the microphone. VOICE_DEVICE names one instead. VOICE_LANGUAGE (for example
+# en) is the language you talk in.
+FFMPEG_PATH=
+VOICE_DEVICE=
+VOICE_LANGUAGE=
+VOICE_MIN_LOUDNESS=
diff --git a/examples/harness-cli-batman/.gitignore b/examples/harness-cli-batman/.gitignore
new file mode 100644
index 0000000000..dbf9171399
--- /dev/null
+++ b/examples/harness-cli-batman/.gitignore
@@ -0,0 +1,6 @@
+.env
+playground/media/
+# Media the CLI saves (the default --media-dir).
+example-coder-media/
+# Marker the sandbox writes into the workspace.
+playground/.tanstack-projected-*
diff --git a/examples/harness-cli-batman/README.md b/examples/harness-cli-batman/README.md
new file mode 100644
index 0000000000..49bd76a795
--- /dev/null
+++ b/examples/harness-cli-batman/README.md
@@ -0,0 +1,49 @@
+# Batman CLI (TanStack AI harness)
+
+A Batman-themed coding agent in your terminal. Same stack as
+[`harness-cli`](../harness-cli): `@tanstack/ai-harness`, `runCli`, and the
+Ink screen. The cave is yellow and black. Bats fly. The agent talks like
+Batman.
+
+This example lives on the harness stack from
+[PR 1555](https://github.com/TanStack/ai/pull/1555).
+
+## Run it
+
+From the repo root of this worktree:
+
+1. `pnpm install`
+2. `pnpm build:all` (the example uses the local packages)
+3. `pnpm --filter harness-cli-batman start`
+4. Type `/connect` and pick OpenRouter. It signs you in with the browser.
+5. Type `/model`, pick OpenRouter, then a model.
+
+Now send a message. Batman answers.
+
+A key skips the splash.
+
+## What you see
+
+- Bats fly across the boot splash. Then **BATMAN** in block letters. Then
+  the line `I AM THE NIGHT`.
+- The header is the Bat-signal yellow. Features that are on show a bat.
+- The input prompt is a bat. Status says `patrolling Gotham` while a turn
+  runs.
+- The agent speaks as Batman. The demo model does too, until you connect a
+  key.
+
+Sessions and keys are in `~/.tanstack-harness-batman`, so they stay apart
+from the plain harness CLI example.
+
+## Everything else
+
+The rest matches [the harness CLI example](../harness-cli/README.md): files
+in the folder where you start, `/connect`, voice, media, Claude Code and
+Codex, Notion and Linear, skills, `/resume`, `--serve`, `--mcp`, and the
+dashboard.
+
+```sh
+pnpm --filter harness-cli-batman start
+pnpm --filter harness-cli-batman start --resume
+pnpm --filter harness-cli-batman start -p "list the files"
+```
diff --git a/examples/harness-cli-batman/package.json b/examples/harness-cli-batman/package.json
new file mode 100644
index 0000000000..d87c1e22a6
--- /dev/null
+++ b/examples/harness-cli-batman/package.json
@@ -0,0 +1,45 @@
+{
+  "name": "harness-cli-batman",
+  "private": true,
+  "description": "A Batman-themed coding agent in the terminal, built with @tanstack/ai-harness",
+  "type": "module",
+  "scripts": {
+    "start": "tsx src/cli.ts",
+    "dashboard": "tanstack-ai-dashboard",
+    "test:types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-acp": "workspace:*",
+    "@tanstack/ai-anthropic": "workspace:*",
+    "@tanstack/ai-claude-code": "workspace:*",
+    "@tanstack/ai-code-mode": "workspace:*",
+    "@tanstack/ai-codex": "workspace:*",
+    "@tanstack/ai-dashboard": "workspace:*",
+    "@tanstack/ai-fal": "workspace:*",
+    "@tanstack/ai-grok": "workspace:*",
+    "@tanstack/ai-harness": "workspace:*",
+    "@tanstack/ai-harness-cli": "workspace:*",
+    "@tanstack/ai-isolate-quickjs": "workspace:*",
+    "@tanstack/ai-mcp": "workspace:*",
+    "@tanstack/ai-models": "workspace:*",
+    "@tanstack/ai-openai": "workspace:*",
+    "@tanstack/ai-openrouter": "workspace:*",
+    "@tanstack/ai-persistence": "workspace:*",
+    "@tanstack/ai-sandbox": "workspace:*",
+    "@tanstack/ai-sandbox-local-process": "workspace:*",
+    "@tanstack/ai-skills": "workspace:*",
+    "@tanstack/react-store": "^0.11.1",
+    "beautiful-mermaid": "^1.1.3",
+    "ink": "^7.1.1",
+    "marked": "^15.0.6",
+    "marked-terminal": "^7.3.0",
+    "react": "^19.2.3",
+    "zod": "^4.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "tsx": "^4.23.12"
+  }
+}
diff --git a/examples/harness-cli-batman/playground/.gitkeep b/examples/harness-cli-batman/playground/.gitkeep
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/examples/harness-cli-batman/playground/AGENTS.md b/examples/harness-cli-batman/playground/AGENTS.md
new file mode 100644
index 0000000000..9fcc63b5ea
--- /dev/null
+++ b/examples/harness-cli-batman/playground/AGENTS.md
@@ -0,0 +1 @@
+This is a playground folder. Keep files short and add a comment at the top of every new file.
diff --git a/examples/harness-cli-batman/src/cli.ts b/examples/harness-cli-batman/src/cli.ts
new file mode 100644
index 0000000000..d8e8ea0cc9
--- /dev/null
+++ b/examples/harness-cli-batman/src/cli.ts
@@ -0,0 +1,55 @@
+import "./env";
+import "./workdir";
+import { runCli } from "@tanstack/ai-harness-cli";
+import { assistant } from "./harness";
+import { hasSession, listSessions, newSessionId } from "./sessions";
+import { persistence } from "./store";
+import { runTui, takeNextSession } from "./tui";
+
+/**
+ * The session to open first: `--resume <id>`, `--resume` alone for the
+ * newest saved session, `--thread <id>`, else a new session. The other
+ * options go to runCli.
+ */
+async function firstSession(argv: Array<string>) {
+  const at = argv.findIndex((arg) => arg === "--resume" || arg.startsWith("--resume="));
+  if (at === -1) {
+    const thread = argv.indexOf("--thread");
+    const given = thread === -1 ? undefined : argv[thread + 1];
+    return { argv, threadId: given ?? newSessionId() };
+  }
+  const [flag = ""] = argv.splice(at, 1);
+  const next = argv[at];
+  const id = flag.startsWith("--resume=")
+    ? flag.slice("--resume=".length)
+    : next !== undefined && !next.startsWith("-")
+      ? argv.splice(at, 1)[0]
+      : (await listSessions(1))[0]?.id;
+  if (id === undefined || !(await hasSession(id))) {
+    process.stderr.write(
+      id === undefined ? "No saved session yet.\n" : `No saved session ${id}.\n`,
+    );
+    process.exit(1);
+  }
+  return { argv, threadId: id };
+}
+
+const first = await firstSession(process.argv.slice(2));
+let threadId = first.threadId;
+
+// A terminal shows the Ink screen from ./tui. Piped input uses line mode.
+// `/resume` closes the screen, and the loop opens the session it picked.
+for (;;) {
+  process.exitCode = await runCli(assistant, {
+    persistence,
+    ui: runTui,
+    // The last `--thread` wins.
+    argv: [...first.argv, "--thread", threadId],
+  });
+  const next = takeNextSession();
+  if (next === undefined) break;
+  threadId = next;
+}
+if (await hasSession(threadId)) {
+  process.stderr.write(`🦇 Continue this patrol with: pnpm start --resume ${threadId}\n`);
+}
diff --git a/examples/harness-cli-batman/src/credentials.ts b/examples/harness-cli-batman/src/credentials.ts
new file mode 100644
index 0000000000..15535e7b8e
--- /dev/null
+++ b/examples/harness-cli-batman/src/credentials.ts
@@ -0,0 +1,65 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { defineCredentialStore } from "@tanstack/ai-persistence";
+import type { Credential } from "@tanstack/ai-persistence";
+
+/** The folder in your home folder where the example saves its files. */
+export const SAVE_DIR = join(homedir(), ".tanstack-harness-batman");
+
+/**
+ * Values in groups, saved as JSON in `file`. `load` gives `{}` for a missing
+ * or broken file. `update` changes the saved values. Updates run one after
+ * the other, so a second update never loses the first.
+ */
+export function jsonFile<TValue>(file: string) {
+  type Saved = Record<string, Record<string, TValue>>;
+  let updating = Promise.resolve();
+  const load = async (): Promise<Saved> => {
+    try {
+      const parsed: unknown = JSON.parse(await readFile(file, "utf8"));
+      return typeof parsed === "object" && parsed !== null ? (parsed as Saved) : {};
+    } catch {
+      return {};
+    }
+  };
+  const update = (change: (all: Saved) => void) => {
+    const run = updating.then(async () => {
+      const all = await load();
+      change(all);
+      await mkdir(dirname(file), { recursive: true });
+      await writeFile(file, JSON.stringify(all, null, 2), { mode: 0o600 });
+    });
+    updating = run.catch(() => {});
+    return run;
+  };
+  return { load, update };
+}
+
+/**
+ * Sign-ins (Notion, Linear) and model keys (`/connect openai`) saved in a
+ * file in your home folder, so they survive a restart. The file is readable
+ * by your user only. A production store would encrypt the values.
+ */
+export function fileCredentials(file = join(SAVE_DIR, "credentials.json")) {
+  const { load, update } = jsonFile<Credential>(file);
+  const owner = (scope: { userId?: string; tenantId?: string }) =>
+    `${scope.tenantId ?? "-"}/${scope.userId ?? "-"}`;
+
+  return defineCredentialStore({
+    get: async (scope, id) => (await load())[owner(scope)]?.[id] ?? null,
+    set: (scope, id, credential) =>
+      update((all) => {
+        all[owner(scope)] = { ...all[owner(scope)], [id]: credential };
+      }),
+    delete: (scope, id) =>
+      update((all) => {
+        delete all[owner(scope)]?.[id];
+      }),
+    list: async (scope) =>
+      Object.entries((await load())[owner(scope)] ?? {}).map(([id, credential]) => ({
+        id,
+        type: credential.type,
+      })),
+  });
+}
diff --git a/examples/harness-cli-batman/src/effort.ts b/examples/harness-cli-batman/src/effort.ts
new file mode 100644
index 0000000000..73f3c6229b
--- /dev/null
+++ b/examples/harness-cli-batman/src/effort.ts
@@ -0,0 +1,57 @@
+import { REASONING_LEVELS } from "@tanstack/ai";
+import { configOption, defineCommand, definePlugin } from "@tanstack/ai-harness";
+
+export const EFFORTS = ["default", ...REASONING_LEVELS] as const;
+type Effort = (typeof EFFORTS)[number];
+
+/**
+ * `/effort`: how hard the main model thinks at the next turn. It sets
+ * `chat({ reasoning })`, which every adapter maps to its own wire field and
+ * clamps to the levels the model has. `default` sends nothing: the model
+ * decides. `reasons` says whether the current model reasons at all.
+ */
+export function effortPicker(options: { reasons: (model: string) => boolean }) {
+  return definePlugin({
+    name: "example/effort",
+    setup: (ctx) => {
+      const current = (): Effort =>
+        EFFORTS.find((effort) => effort === ctx.config.get("effort")) ?? "default";
+      return {
+        config: {
+          effort: configOption.select({
+            options: EFFORTS,
+            default: "default",
+            category: "thought_level",
+            description: "How hard the model thinks",
+          }),
+        },
+        middleware: [
+          {
+            name: "example/effort",
+            onConfig: () => {
+              const effort = current();
+              if (effort === "default") return undefined;
+              if (!options.reasons(String(ctx.config.get("model")))) {
+                return undefined;
+              }
+              return { reasoning: { level: effort, summary: true } };
+            },
+          },
+        ],
+        commands: {
+          effort: defineCommand({
+            description: `Show or set how hard the model thinks (${EFFORTS.join(", ")})`,
+            run: async (input: unknown) => {
+              const name = typeof input === "string" ? input.trim() : "";
+              if (name === "") return `Effort: ${current()}.`;
+              const effort = EFFORTS.find((item) => item === name);
+              if (!effort) return `Unknown effort "${name}". Choices: ${EFFORTS.join(", ")}.`;
+              await ctx.session.setConfig("effort", effort);
+              return `Effort: ${effort}. It applies at the next turn.`;
+            },
+          }),
+        },
+      };
+    },
+  });
+}
diff --git a/examples/harness-cli-batman/src/env.ts b/examples/harness-cli-batman/src/env.ts
new file mode 100644
index 0000000000..e314d621d5
--- /dev/null
+++ b/examples/harness-cli-batman/src/env.ts
@@ -0,0 +1,10 @@
+// The `.env` shortcut: the keys in ./.env, when the file is there. A missing
+// file is normal (the app needs none), so it says nothing. The CLI imports
+// this file first, so the keys are set before the harness reads them.
+try {
+  process.loadEnvFile();
+} catch (error) {
+  if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+    throw error;
+  }
+}
diff --git a/examples/harness-cli-batman/src/harness.ts b/examples/harness-cli-batman/src/harness.ts
new file mode 100644
index 0000000000..1d3b9fa3bd
--- /dev/null
+++ b/examples/harness-cli-batman/src/harness.ts
@@ -0,0 +1,478 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { EventType, defineAgent, keyedAdapter } from "@tanstack/ai";
+import { defineHarness } from "@tanstack/ai-harness";
+import {
+  compact,
+  goal,
+  modelPicker,
+  permissions,
+  projectInstructions,
+  providerKeys,
+  todos,
+  usage,
+  workspaceTools,
+} from "@tanstack/ai-harness/plugins";
+import { ANTHROPIC_MODELS, createAnthropicChat } from "@tanstack/ai-anthropic";
+import { anthropicByok } from "@tanstack/ai-anthropic/byok";
+import { claudeCodeText } from "@tanstack/ai-claude-code";
+import { codeMode } from "@tanstack/ai-code-mode/harness";
+import { codexText } from "@tanstack/ai-codex";
+import { falByok } from "@tanstack/ai-fal/byok";
+import { mcpConnector } from "@tanstack/ai-mcp/connector";
+import { GROK_CHAT_MODELS, createGrokText } from "@tanstack/ai-grok";
+import { grokByok } from "@tanstack/ai-grok/byok";
+import { createQuickJSIsolateDriver } from "@tanstack/ai-isolate-quickjs";
+import { getModel, supportedReasoningLevels } from "@tanstack/ai-models";
+import { OPENAI_CHAT_MODELS, createOpenaiChat, openaiTranscription } from "@tanstack/ai-openai";
+import { openaiByok } from "@tanstack/ai-openai/byok";
+import { createOpenRouterText } from "@tanstack/ai-openrouter";
+import { openrouterByok } from "@tanstack/ai-openrouter/byok";
+import { OPENROUTER_CHAT_MODELS } from "@tanstack/ai-openrouter/model-meta";
+import { openrouterSignIn } from "@tanstack/ai-openrouter/pkce";
+import { defineSandbox, defineWorkspace, localSource } from "@tanstack/ai-sandbox";
+import { codingAgents } from "@tanstack/ai-sandbox/harness";
+import type { CodingAgentConfig } from "@tanstack/ai-sandbox/harness";
+import { localProcessSandbox } from "@tanstack/ai-sandbox-local-process";
+import { skills } from "@tanstack/ai-skills/harness";
+import { z } from "zod";
+import { imageAgent, songAgent, soundAgent, speechAgent, videoAgent } from "./media";
+import { effortPicker } from "./effort";
+import { SAVE_DIR } from "./credentials";
+import { SCREEN_COMMANDS } from "./screen/commands";
+import { envKey, providerKey } from "./store";
+import type { AnyTextAdapter, KeyedAdapter } from "@tanstack/ai";
+import type { ModelRecord } from "@tanstack/ai-models";
+import type { ByokProvider } from "@tanstack/ai/byok";
+
+// The agent works in the folder where you started the app (src/workdir.ts).
+// A path outside it asks you first.
+const root = process.cwd();
+
+/**
+ * The demo model's answer, in markdown, so the screen shows how it renders
+ * markdown. Ask it for a chart, and it draws one in Mermaid.
+ */
+function demoReply(said: string) {
+  const chart = /chart|mermaid|diagram/i.test(said)
+    ? "\n\n```mermaid\ngraph LR\n  You --> Batman --> Model\n  Batman --> Tools\n  Batman --> Gotham\n```"
+    : "";
+  return (
+    [
+      `🦇 **(demo, the night shift)** You said: "${said}".`,
+      "",
+      "The cave has no key yet. Light the signal:",
+      "- Type `/connect` to connect a provider.",
+      "- Type `/model` to pick a real model.",
+      "",
+      "_I am the night. I am Batman._",
+    ].join("\n") + chart
+  );
+}
+
+/** Without any model key, a stand-in model that explains how to add one. */
+function demoModel(): AnyTextAdapter {
+  let calls = 0;
+  return {
+    kind: "text",
+    name: "demo",
+    model: "demo",
+    "~types": {
+      providerOptions: {},
+      inputModalities: ["text"],
+      messageMetadataByModality: {
+        text: undefined,
+        image: undefined,
+        audio: undefined,
+        video: undefined,
+        document: undefined,
+      },
+      toolCapabilities: [],
+      toolCallMetadata: undefined,
+      systemPromptMetadata: undefined as never,
+    },
+    structuredOutput: async () => ({ data: {}, rawText: "{}" }),
+    chatStream: (options) =>
+      (async function* () {
+        calls += 1;
+        const messageId = `demo-${calls}`;
+        const last = options.messages.at(-1);
+        const said = typeof last?.content === "string" ? last.content : "";
+        const now = Date.now();
+        yield {
+          type: EventType.RUN_STARTED,
+          runId: "demo",
+          threadId: "demo",
+          timestamp: now,
+        };
+        yield {
+          type: EventType.TEXT_MESSAGE_START,
+          messageId,
+          role: "assistant",
+          timestamp: now,
+        };
+        yield {
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          messageId,
+          delta: demoReply(said),
+          timestamp: now,
+        };
+        yield { type: EventType.TEXT_MESSAGE_END, messageId, timestamp: now };
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId: "demo",
+          threadId: "demo",
+          timestamp: now,
+          // ponytail: about 4 characters a token, so the footer counts in demo mode too.
+          usage: {
+            promptTokens: Math.ceil(JSON.stringify(options.messages).length / 4),
+            completionTokens: 30,
+            totalTokens: Math.ceil(JSON.stringify(options.messages).length / 4) + 30,
+          },
+          metadata: { tanstack: { finishReason: "stop" } },
+        };
+      })(),
+  };
+}
+
+/** Is a key for `provider` in the environment (the `.env` shortcut)? */
+function hasEnvKey(provider: ByokProvider) {
+  return envKey(provider) !== null;
+}
+
+const openai = (model: (typeof OPENAI_CHAT_MODELS)[number]) =>
+  keyedAdapter(openaiByok, (key) => createOpenaiChat(model, key));
+const anthropic = (model: (typeof ANTHROPIC_MODELS)[number]) =>
+  keyedAdapter(anthropicByok, (key) => createAnthropicChat(model, key));
+const grok = (model: (typeof GROK_CHAT_MODELS)[number]) =>
+  keyedAdapter(grokByok, (key) => createGrokText(model, key));
+const openrouter = (model: (typeof OPENROUTER_CHAT_MODELS)[number]) =>
+  keyedAdapter(openrouterByok, (key) => createOpenRouterText(model, key));
+
+/** A model `/model` can pick. */
+export interface ModelEntry {
+  id: string;
+  /** The key provider to connect, for example `openai` or `grok`. */
+  provider: string;
+  record: ModelRecord;
+  adapter: KeyedAdapter<AnyTextAdapter>;
+}
+
+/**
+ * The models of one provider: each chat model its adapter knows that the
+ * `@tanstack/ai-models` catalog has too. The catalog gives the context size,
+ * the reasoning levels, and the price. Sorted by id, the newest version of
+ * each family first (`claude-opus-5-5` before `claude-opus-4-8`).
+ */
+function providerModels<TModel extends string>(
+  catalogId: string,
+  byok: ByokProvider,
+  ids: ReadonlyArray<TModel>,
+  adapter: (model: TModel) => KeyedAdapter<AnyTextAdapter>,
+  start: TModel,
+) {
+  const models = ids.flatMap((id): Array<ModelEntry> => {
+    const record = getModel(catalogId, id);
+    return record ? [{ id, provider: byok.id, record, adapter: adapter(id) }] : [];
+  });
+  return {
+    id: byok.id,
+    label: byok.label,
+    byok,
+    start,
+    models: models.sort((a, b) => b.id.localeCompare(a.id, "en", { numeric: true })),
+  };
+}
+
+/**
+ * The models `/model` can switch to, by provider and by their real model id.
+ * Each one is built for each turn with the user's own key: the key saved
+ * with `/connect <provider>`, else the env var. A model without a key asks
+ * the user to connect.
+ */
+export const modelProviders = [
+  providerModels("openai", openaiByok, OPENAI_CHAT_MODELS, openai, "gpt-6-astra"),
+  providerModels("anthropic", anthropicByok, ANTHROPIC_MODELS, anthropic, "claude-opus-5-5"),
+  providerModels("xai", grokByok, GROK_CHAT_MODELS, grok, "grok-4.7"),
+  providerModels(
+    "openrouter",
+    openrouterByok,
+    OPENROUTER_CHAT_MODELS,
+    openrouter,
+    "openai/gpt-6-astra",
+  ),
+];
+
+/**
+ * Each model by its id: the provider that must be connected, its catalog
+ * record (context size, reasoning levels, price), and its adapter. The ids
+ * of the providers do not overlap: OpenRouter ids start with the vendor.
+ */
+export const modelInfo: Record<string, ModelEntry> = Object.fromEntries(
+  modelProviders.flatMap((provider) => provider.models.map((model) => [model.id, model])),
+);
+
+// A new session starts on the first provider with a key: one saved with
+// /connect, or one in the env (a `.env` file). Without any key, `gpt-6-astra`
+// starts, and the first message asks the user to run /connect. A resumed
+// session keeps the model it had.
+const keyed = await Promise.all(
+  modelProviders.map(async (provider) =>
+    (await providerKey(provider.byok, "startup")) === null ? [] : [provider],
+  ),
+);
+const startProvider = keyed.flat()[0];
+const startModel = startProvider?.start ?? "gpt-6-astra";
+// The start model: the harness, /compact, /goal, and /agent haiku use it.
+const main: KeyedAdapter<AnyTextAdapter> = modelInfo[startModel].adapter;
+// With no key at all, `/model demo` answers without a key.
+const choices = {
+  ...Object.fromEntries(Object.values(modelInfo).map((model) => [model.id, model.adapter])),
+  ...(startProvider ? {} : { demo: demoModel() }),
+};
+
+/** Does the model think, so `/effort` changes it? */
+export function reasons(model: string) {
+  const record = modelInfo[model]?.record;
+  return record ? supportedReasoningLevels(record).some((level) => level !== "off") : false;
+}
+
+// `/connect openrouter` signs in with the browser: no key to paste, and one
+// sign-in covers GPT, Claude, Gemini, and more. OpenAI, Anthropic, xAI, and
+// fal have no browser sign-in for other apps, so `/connect openai` opens the
+// page to make a key, then asks for it (the screen hides it as you type).
+export const keyProviders = [
+  { ...openrouterByok, signIn: openrouterSignIn() },
+  { ...openaiByok, keyUrl: "https://platform.openai.com/api-keys" },
+  { ...anthropicByok, keyUrl: "https://console.anthropic.com/settings/keys" },
+  { ...grokByok, keyUrl: "https://console.x.ai" },
+  { ...falByok, keyUrl: "https://fal.ai/dashboard/keys" },
+];
+
+/** Is `command` on the PATH? Checks the Windows extensions too. */
+function onPath(command: string) {
+  const extensions =
+    process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
+  return (process.env.PATH ?? "")
+    .split(delimiter)
+    .some((dir) =>
+      extensions.some((extension) => existsSync(join(dir, `${command}${extension.toLowerCase()}`))),
+    );
+}
+
+/**
+ * A top-level setting of your ~/.codex/config.toml (the lines before the
+ * first `[section]`), so the example runs Codex the way you set it up.
+ */
+function codexSetting(key: string) {
+  const config = join(homedir(), ".codex", "config.toml");
+  if (!existsSync(config)) return undefined;
+  const [topLevel = ""] = readFileSync(config, "utf8").split(/^\s*\[/m);
+  return new RegExp(`^\\s*${key}\\s*=\\s*"([^"]+)"`, "m").exec(topLevel)?.[1];
+}
+
+const CODEX_SANDBOX_MODES = ["read-only", "workspace-write", "danger-full-access"] as const;
+
+/**
+ * The Codex sandbox: CODEX_SANDBOX_MODE, else `sandbox_mode` in your Codex
+ * config, else workspace-write. On Windows, workspace-write can block the
+ * folder (Access is denied).
+ */
+function codexSandbox() {
+  const mode = process.env.CODEX_SANDBOX_MODE ?? codexSetting("sandbox_mode");
+  return CODEX_SANDBOX_MODES.find((known) => known === mode) ?? "workspace-write";
+}
+
+/** A typed agent you can run with `/agent haiku {"topic":"rain"}`. */
+const haiku = defineAgent({
+  name: "haiku",
+  description: "Writes a haiku about a topic",
+  inputSchema: z.object({ topic: z.string() }),
+  run: async (ctx) =>
+    ctx.chat({
+      adapter: await ctx.keys.adapter(main),
+      messages: [
+        {
+          role: "user",
+          content: `Write one haiku about ${ctx.input.topic}. Only the haiku.`,
+        },
+      ],
+      stream: false,
+    }),
+});
+
+// The model calls the media agents as tools, and the harness keeps each file
+// they make. Each one uses the key its provider needs. Without the key, the
+// tool says which /connect to run:
+// - OpenAI: images, speech, and video with Sora.
+// - xAI Grok: video with Grok Imagine (it wins over Sora).
+// - fal: songs and sound effects.
+const media = [imageAgent, speechAgent, videoAgent, songAgent, soundAgent];
+
+// Notion and Linear through their MCP servers. `/connect notion` signs in
+// through the browser. No app setup or API key is needed.
+const notion = mcpConnector({
+  id: "notion",
+  label: "Notion",
+  url: "https://mcp.notion.com/mcp",
+});
+const linear = mcpConnector({
+  id: "linear",
+  label: "Linear",
+  url: "https://mcp.linear.app/mcp",
+});
+
+// The lead model can hand coding work to your local Claude Code and Codex.
+// Each one turns on when its CLI is on the PATH (CODING_AGENTS=0 turns both
+// off). They work in your folder with your own `claude login` and
+// `codex login`, so the API keys are removed from their processes.
+const useCodingAgents = process.env.CODING_AGENTS !== "0";
+const codingAgentList: Record<string, CodingAgentConfig> = {};
+if (useCodingAgents && onPath("claude")) {
+  codingAgentList.claude_code = {
+    adapter: claudeCodeText("claude-opus-4-8", {
+      authMode: "host",
+      permissionMode: "acceptEdits",
+    }),
+    description:
+      "Claude Code, the local coding agent. Larger changes, refactors, and reviews in the workspace.",
+  };
+}
+if (useCodingAgents && onPath("codex")) {
+  codingAgentList.codex = {
+    // A ChatGPT login supports only some models, so the model and the sandbox
+    // come from your Codex config unless CODEX_MODEL or CODEX_SANDBOX_MODE is
+    // set.
+    adapter: codexText(process.env.CODEX_MODEL ?? codexSetting("model") ?? "gpt-5.3-codex", {
+      authMode: "host",
+      sandboxMode: codexSandbox(),
+      approvalPolicy: "never",
+    }),
+    description: "Codex, the local coding agent. Quick fixes, scripts, and tests in the workspace.",
+  };
+}
+const coding =
+  Object.keys(codingAgentList).length > 0
+    ? [
+        codingAgents({
+          sandbox: defineSandbox({
+            id: "workspace",
+            provider: localProcessSandbox({
+              dir: root,
+              scrubEnv: ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
+            }),
+            workspace: defineWorkspace({ source: localSource(root) }),
+          }),
+          agents: codingAgentList,
+        }),
+      ]
+    : [];
+
+const tools = [...media.map((agent) => agent.name), ...Object.keys(codingAgentList)];
+
+/**
+ * A feature that a key for any one of `providers` turns on. `on` is the
+ * state at startup, from the env vars only. The screen follows the saved
+ * keys live.
+ */
+function keyFeature(name: string, providers: Array<ByokProvider>, needs: string) {
+  return {
+    name,
+    on: providers.some(hasEnvKey),
+    needs,
+    providers: providers.map((provider) => provider.id),
+  };
+}
+
+/**
+ * What this session can do, and what turns each one on, for the screen.
+ * `providers` are the ids of the key providers a feature needs (any one).
+ */
+export const features = [
+  keyFeature(
+    "voice",
+    [openaiByok, grokByok],
+    "an OpenAI or xAI key (/connect openai or /connect grok), and ffmpeg",
+  ),
+  keyFeature("images", [openaiByok], "an OpenAI key (/connect openai)"),
+  keyFeature("speech", [openaiByok], "an OpenAI key (/connect openai)"),
+  keyFeature(
+    "video",
+    [grokByok, openaiByok],
+    "an xAI or OpenAI key (/connect grok or /connect openai)",
+  ),
+  keyFeature("songs", [falByok], "a fal key (/connect fal)"),
+  {
+    name: "claude code",
+    on: "claude_code" in codingAgentList,
+    needs: "`claude` on the PATH",
+    providers: [],
+  },
+  {
+    name: "codex",
+    on: "codex" in codingAgentList,
+    needs: "`codex` on the PATH",
+    providers: [],
+  },
+  { name: "notion", on: true, needs: "", providers: [] },
+  { name: "linear", on: true, needs: "", providers: [] },
+];
+
+export const assistant = defineHarness({
+  name: "gotham/batman",
+  description:
+    "Batman in the terminal: files, voice, media, Notion, Linear, and local coding agents",
+  adapter: main,
+  systemPrompts: [
+    "You are Batman, the Dark Knight, working as a careful coding agent in the workspace, the folder where the user started you. Speak like Batman: short, grave, direct. Call the user Commissioner when it fits. Use a bat emoji when you start a reply. Read files before you edit them. Keep answers short.",
+    `Your agent tools: ${tools.join(", ") || "none"}. The user gets each file a media tool makes, so do not paste file contents or links.`,
+    'When the user asks to run Codex or Claude Code (by voice too: "run a Codex agent"), call that tool with a clear task, then give its answer back in a few lines.',
+    "The user can send files and voice messages. When they send an image and ask for a new version, a style, or an edit of it, call the image tool with useAttachedImages.",
+    "You can read Notion and Linear when they are connected. If a tool says to sign in or that a key is missing, tell the user the /connect command it names, for example /connect notion or /connect openai.",
+  ],
+  agents: [haiku],
+  subagents: { agents: media },
+  // Audio files the user sends become text for models that cannot read audio.
+  // ponytail: `media.transcribe` takes a plain adapter, not a keyed one, so
+  // this needs OPENAI_API_KEY in the env. A key saved with /connect does not
+  // turn it on. Voice messages on the screen use the saved key (src/voice.ts).
+  ...(process.env.OPENAI_API_KEY
+    ? { media: { transcribe: openaiTranscription("gpt-4o-transcribe") } }
+    : {}),
+  plugins: () => [
+    notion,
+    linear,
+    permissions(),
+    workspaceTools({ root, outside: "ask" }),
+    todos(),
+    providerKeys({ providers: keyProviders }),
+    modelPicker({ choices, default: startModel }),
+    effortPicker({ reasons }),
+    projectInstructions({ root }),
+    compact({ adapter: main }),
+    usage(),
+    // /goal keeps the agent working until the main model says the goal is met.
+    goal({ judge: main }),
+    // Skills: each folder holds skill folders with a SKILL.md. Each skill is a
+    // /<name> command, and the model sees the list. A skill you add while the
+    // app runs shows at once. The repo folders (where you run the app) win
+    // over the global one. A skill named like a screen command is
+    // /skill:<name>.
+    skills({
+      dirs: ["./.agents/skills", "./.claude/skills", join(SAVE_DIR, "skills")],
+      reserved: SCREEN_COMMANDS.map((command) => command.name),
+    }),
+    // Read-only tools (file reads, read-only Notion and Linear tools) move
+    // behind execute_typescript, so the model can call several in one program.
+    // The tools are lazy: the model gets their names, asks discover_tools for
+    // the signatures it needs, then calls them in the program. The program
+    // runs in a QuickJS isolate. Any @tanstack/ai-isolate-* driver works here.
+    codeMode({
+      driver: createQuickJSIsolateDriver(),
+      lazy: true,
+      lazyToolsConfig: { includeDescription: "first-sentence" },
+    }),
+    ...coding,
+  ],
+});
diff --git a/examples/harness-cli-batman/src/marked-terminal.d.ts b/examples/harness-cli-batman/src/marked-terminal.d.ts
new file mode 100644
index 0000000000..4dbc0dcad9
--- /dev/null
+++ b/examples/harness-cli-batman/src/marked-terminal.d.ts
@@ -0,0 +1,10 @@
+// marked-terminal has no types of its own. This is the one function the
+// screen uses.
+declare module "marked-terminal" {
+  import type { MarkedExtension } from "marked";
+
+  export function markedTerminal(
+    options?: Record<string, unknown>,
+    highlightOptions?: Record<string, unknown>,
+  ): MarkedExtension;
+}
diff --git a/examples/harness-cli-batman/src/media.ts b/examples/harness-cli-batman/src/media.ts
new file mode 100644
index 0000000000..36b78505e4
--- /dev/null
+++ b/examples/harness-cli-batman/src/media.ts
@@ -0,0 +1,193 @@
+import { EventType, defineAgent, keyedAdapter } from "@tanstack/ai";
+import { mediaIdOf } from "@tanstack/ai-harness";
+import { falAudio } from "@tanstack/ai-fal";
+import { falByok } from "@tanstack/ai-fal/byok";
+import { createGrokVideo } from "@tanstack/ai-grok";
+import { grokByok } from "@tanstack/ai-grok/byok";
+import { createOpenaiImage, createOpenaiSpeech, createOpenaiVideo } from "@tanstack/ai-openai";
+import { openaiByok } from "@tanstack/ai-openai/byok";
+import { z } from "zod";
+import { mediaBytes } from "./store";
+import type {
+  AnyVideoAdapter,
+  ImagePart,
+  MediaInputMetadata,
+  ModelMessage,
+  UIMessage,
+} from "@tanstack/ai";
+
+// Every agent here returns a short text. The harness keeps each file it makes
+// and publishes a `harness.media` event, so the screen can show and save it.
+//
+// Each agent builds its model with the user's key just before the call: the
+// key saved with `/connect <provider>`, else the env var. Without a key, the
+// call stops, and the screen says which `/connect` to run.
+const gptImage = keyedAdapter(openaiByok, (key) => createOpenaiImage("gpt-image-2.5-flare", key));
+const openaiVoice = keyedAdapter(openaiByok, (key) => createOpenaiSpeech("tts-1-hd", key));
+const sora = keyedAdapter(openaiByok, (key) => createOpenaiVideo("sora-2", key));
+const grokImagine = keyedAdapter(grokByok, (key) => createGrokVideo("grok-imagine-video-1.5", key));
+const falMusic = keyedAdapter(falByok, (key) =>
+  falAudio("fal-ai/elevenlabs/music", { apiKey: key }),
+);
+const falSound = keyedAdapter(falByok, (key) =>
+  falAudio("fal-ai/stable-audio-25/text-to-audio", { apiKey: key }),
+);
+
+/**
+ * The images in the latest user message that has files: the ones the user
+ * sent with `@path`, or with a voice message that named a file.
+ */
+async function attachedImages(messages: ReadonlyArray<UIMessage | ModelMessage>) {
+  for (const message of [...messages].reverse()) {
+    if (message.role !== "user" || !("content" in message)) continue;
+    if (!Array.isArray(message.content)) continue;
+    const images: Array<ImagePart<MediaInputMetadata>> = [];
+    for (const part of message.content) {
+      const id = mediaIdOf(part);
+      if (id === undefined || part.type !== "image") continue;
+      const bytes = await mediaBytes(id);
+      const mimeType = part.source.mimeType ?? "image/png";
+      if (bytes) {
+        images.push({
+          type: "image",
+          source: {
+            type: "data",
+            value: Buffer.from(bytes).toString("base64"),
+            mimeType,
+          },
+        });
+      }
+    }
+    if (images.length > 0) return images;
+  }
+  return [];
+}
+
+/** Makes an image with OpenAI. It can start from the images the user sent. */
+export const imageAgent = defineAgent({
+  name: "image",
+  description:
+    "Generates one image from a detailed visual prompt. Set useAttachedImages when the user sent images to use as references (a new version, a style, an edit). The user gets the image.",
+  produces: "image",
+  inputSchema: z.object({
+    prompt: z.string().describe("A detailed description of the image"),
+    useAttachedImages: z
+      .boolean()
+      .optional()
+      .describe("Use the images the user sent as references"),
+  }),
+  run: async (ctx) => {
+    const references = ctx.input.useAttachedImages ? await attachedImages(ctx.messages) : [];
+    const adapter = await ctx.keys.adapter(gptImage);
+    // With references, the prompt is the text plus the images (an edit).
+    const result =
+      references.length > 0
+        ? await ctx.generateImage({
+            adapter,
+            prompt: [{ type: "text", content: ctx.input.prompt }, ...references],
+            size: "1024x1024",
+          })
+        : await ctx.generateImage({
+            adapter,
+            prompt: ctx.input.prompt,
+            size: "1024x1024",
+          });
+    if (result.images.length === 0) throw new Error("The image model returned no image.");
+    const from = references.length > 0 ? ` from ${references.length} reference image(s)` : "";
+    return `Made the image${from} with ${result.model}. The user has it.`;
+  },
+});
+
+/**
+ * Makes a short video: with Grok Imagine when the user has an xAI key, else
+ * with Sora. The harness keeps only streamed video, so this uses
+ * `stream: true`: one stream from the job start to the file.
+ */
+export const videoAgent = defineAgent({
+  name: "video",
+  description:
+    "Generates one short video clip from a detailed visual prompt. Takes a minute or two. The user gets the video.",
+  produces: "video",
+  inputSchema: z.object({
+    prompt: z.string().describe("A detailed description of the scene and the motion"),
+  }),
+  run: async (ctx) => {
+    const hasGrokKey = (await ctx.keys.get(grokByok)) !== null;
+    const adapter: AnyVideoAdapter = hasGrokKey
+      ? await ctx.keys.adapter(grokImagine)
+      : await ctx.keys.adapter(sora);
+    const stream = ctx.generateVideo({
+      adapter,
+      prompt: ctx.input.prompt,
+      stream: true,
+    });
+    for await (const chunk of stream) {
+      // The stream reports a failed or stopped job as an event, not a throw.
+      if (chunk.type === EventType.RUN_ERROR) throw new Error(chunk.message);
+    }
+    return `Made the video with ${adapter.model}. The user has it.`;
+  },
+});
+
+/** Reads a text aloud with OpenAI text to speech. */
+export const speechAgent = defineAgent({
+  name: "speech",
+  description:
+    "Reads a text aloud and makes an audio file of it (text to speech). The user gets the audio.",
+  produces: "speech",
+  inputSchema: z.object({
+    text: z.string().describe("The exact words to say"),
+    voice: z
+      .enum(["alloy", "echo", "fable", "onyx", "nova", "shimmer"])
+      .optional()
+      .describe("The voice. Default: alloy"),
+  }),
+  run: async (ctx) => {
+    const result = await ctx.generateSpeech({
+      adapter: await ctx.keys.adapter(openaiVoice),
+      text: ctx.input.text,
+      voice: ctx.input.voice ?? "alloy",
+    });
+    return `Read the text aloud with ${result.model}. The user has the audio.`;
+  },
+});
+
+/** Makes a song with vocals and music through fal (ElevenLabs Music). */
+export const songAgent = defineAgent({
+  name: "song",
+  description:
+    "Composes a song or an instrumental track from a description (genre, mood, instruments, and lyrics if the user gave any). Takes up to a minute. The user gets the audio.",
+  produces: "audio",
+  inputSchema: z.object({
+    prompt: z.string().describe("The style, mood, instruments, and the lyrics, if any"),
+    seconds: z.number().min(10).max(120).optional().describe("The length in seconds. Default: 30"),
+  }),
+  run: async (ctx) => {
+    const result = await ctx.generateAudio({
+      adapter: await ctx.keys.adapter(falMusic),
+      prompt: ctx.input.prompt,
+      duration: ctx.input.seconds ?? 30,
+    });
+    return `Composed the song with ${result.model}. The user has the audio.`;
+  },
+});
+
+/** Makes a sound effect through fal (Stable Audio). */
+export const soundAgent = defineAgent({
+  name: "sound_effect",
+  description:
+    "Makes a short sound effect or ambience from a description, for example rain on a window. The user gets the audio.",
+  produces: "audio",
+  inputSchema: z.object({
+    prompt: z.string().describe("The sound to make"),
+    seconds: z.number().min(1).max(30).optional().describe("The length in seconds. Default: 8"),
+  }),
+  run: async (ctx) => {
+    const result = await ctx.generateAudio({
+      adapter: await ctx.keys.adapter(falSound),
+      prompt: ctx.input.prompt,
+      duration: ctx.input.seconds ?? 8,
+    });
+    return `Made the sound effect with ${result.model}. The user has the audio.`;
+  },
+});
diff --git a/examples/harness-cli-batman/src/screen/batman-art.ts b/examples/harness-cli-batman/src/screen/batman-art.ts
new file mode 100644
index 0000000000..46f979bbc0
--- /dev/null
+++ b/examples/harness-cli-batman/src/screen/batman-art.ts
@@ -0,0 +1,134 @@
+/** ASCII from asciiart.eu. Initials stay on the drawings (snd, z_M). */
+
+function padArt(lines: ReadonlyArray<string>) {
+  const width = Math.max(0, ...lines.map((line) => line.length));
+  return lines.map((line) => line.padEnd(width));
+}
+
+/** Bat symbol. Joan Stark / unknown, 60 x 21. asciiart.eu/art/f5be3a8046b61e0a */
+export const SYMBOL = padArt([
+  "                   ,.ood888888888888boo.,",
+  '              .od888P^""            ""^Y888bo.',
+  "          .od8P''   ..oood88888888booo.    ``Y8bo.",
+  '       .odP\'"  .ood8888888888888888888888boo.  "`Ybo.',
+  "     .d8'   od8'd888888888f`8888't888888888b`8bo   `Yb.",
+  "    d8'  od8^   8888888888[  `'  ]8888888888   ^8bo  `8b",
+  "  .8P  d88'     8888888888P      Y8888888888     `88b  Y8.",
+  " d8' .d8'       `Y88888888'      `88888888P'       `8b. `8b",
+  '.8P .88P            """"            """"            Y88. Y8.',
+  "88  888                                              888  88",
+  "88  888                                              888  88",
+  "88  888.        ..                        ..        .888  88",
+  "`8b `88b,     d8888b.od8bo.      .od8bo.d8888b     ,d88' d8'",
+  " Y8. `Y88.    8888888888888b    d8888888888888    .88P' .8P",
+  "  `8b  Y88b.  `88888888888888  88888888888888'  .d88P  d8'",
+  "    Y8.  ^Y88bod8888888888888..8888888888888bod88P^  .8P",
+  "     `Y8.   ^Y888888888888888LS888888888888888P^   .8P'",
+  "       `^Yb.,  `^^Y8888888888888888888888P^^'  ,.dP^'",
+  "          `^Y8b..   ``^^^Y88888888P^^^'    ..d8P^'",
+  "              `^Y888bo.,            ,.od888P^'",
+  '                   "`^^Y888888888888P^^\'"',
+]);
+
+/** Standing Batman. Shanaka Dias (snd), 24 x 22. asciiart.eu/art/59a93c84f7c5a9f6 */
+export const STAND = padArt([
+  "          .  .",
+  "          |\\_|\\",
+  "          | a_a\\",
+  '          | | "]',
+  "      ____| '-\\___",
+  "     /.----.___.-'\\",
+  "    //        _    \\",
+  "   //   .-. (~v~) /|",
+  "  |'|  /\\:  .--  / \\",
+  " // |-/  \\_/____/\\/~|",
+  "|/  \\ |  []_|_|_] \\ |",
+  "| \\  | \\ |___   _\\ ]_}",
+  "| |  '-' /   '.'  |",
+  "| |     /    /|:  | ",
+  "| |     |   / |:  /\\",
+  "| |     /  /  |  /  \\",
+  "| |    |  /  /  |    \\",
+  "\\ |    |/\\/  |/|/\\    \\",
+  " \\|\\ |\\|  |  | / /\\/\\__\\",
+  "  \\ \\| | /   | |__",
+  "snd    / |   |____)",
+  "       |_/",
+]);
+
+/** Batman with the cape out. Shanaka Dias (snd), 45 x 26. asciiart.eu/art/39ab1850ef7b32a8 */
+export const CAPE = padArt([
+  "           |    |              _.-7",
+  "           |\\.-.|             ( ,(_",
+  "           | a a|              \\\\  \\,",
+  "           ) [\"||          _.--' \\  \\\\",
+  "        .-'  '-''-..____.-'    ___)  )\\",
+  "       F   _/-``-.__;-.-.--`--' . .' \\_L_",
+  "      |   l  {~~} ,_\\  '.'.      ` __.' )\\",
+  "      (    -.;___,;  | '- _       :__.'( /",
+  "      | -.__ _/_.'.-'      '-._ .'      \\\\",
+  "      |     .'   |  -- _                 '\\,",
+  "      |  \\ /--,--{ .    '---.__.       .'  .'",
+  "      J  ;/ __;__]. '.-.            .-' )_/",
+  "      J  (-.     '\\'. '. '-._.-.-'--._ /",
+  "      |  |  '. .' | \\'. '.    ._       \\",
+  "      |   \\   T   |  \\  '. '._  '-._    '.",
+  "      F   J   |   |  '.    .  '._   '-,_.--`",
+  "      F   \\   \\   F .  \\    '.   '.  /",
+  "     J     \\  |  J   \\  '.   '.    '/",
+  "     J      '.L__|    .   \\    '    |",
+  "     |   .    \\  |     \\   '.   '. /",
+  "     |    '    '.|      |    ,-.  (",
+  "     F   | ' ___  ',._   .  /   '. \\",
+  "     F   (.'`|| (-._\\ '.  \\-      '-\\",
+  "     \\ .-'  ( L `._ '\\ '._ (",
+  "snd  /'  |  /  '-._\\      ''\\",
+  "         `-'",
+]);
+
+/** Batman with pointed ears. z_M, 48 x 25. asciiart.eu/art/7b11b14980469ed1 */
+export const EARS = padArt([
+  "                T\\ T\\",
+  "                | \\| \\",
+  "                |  |  :",
+  "           _____I__I  |",
+  "         .'            '.",
+  "       .'                '",
+  "       |   ..             '",
+  "       |  /__.            |",
+  "       :.' -'             |",
+  "      /__.                |",
+  "     /__, \\               |",
+  "        |__\\        _|    |",
+  "        :  '\\     .'|     |",
+  "        |___|_,,,/  |     |    _..--.",
+  "     ,--_-   |     /'      \\../ /  /\\\\",
+  "    ,'|_ I---|    7    ,,,_/ / ,  / _\\\\",
+  "  ,-- 7 \\|  / ___..,,/   /  ,  ,_/   '-----.",
+  " /   ,   \\  |/  ,____,,,__,,__/            '\\",
+  ",   ,     \\__,,/                             |",
+  "| '.       _..---.._                         !.",
+  "! |      .' z_M__s. '.                        |",
+  ".:'      | (-_ _--')  :          L            !",
+  ".'.       '.  Y    _.'             \\,         :",
+  " .          '-----'                 !          .",
+  " .           /  \\                   .          .",
+]);
+
+/** The three figure poses, padded to one size so the animation does not jump. */
+export const POSES = padFrames([STAND, CAPE, EARS]);
+
+function padFrames(frames: ReadonlyArray<ReadonlyArray<string>>) {
+  const width = Math.max(...frames.map((frame) => frame[0]?.length ?? 0));
+  const height = Math.max(...frames.map((frame) => frame.length));
+  return frames.map((frame) => {
+    const left = Math.floor((width - (frame[0]?.length ?? 0)) / 2);
+    const top = Math.floor((height - frame.length) / 2);
+    const rows = [
+      ...Array.from({ length: top }, () => " ".repeat(width)),
+      ...frame.map((line) => line.padStart(line.length + left).padEnd(width)),
+      ...Array.from({ length: height - top - frame.length }, () => " ".repeat(width)),
+    ];
+    return rows;
+  });
+}
diff --git a/examples/harness-cli-batman/src/screen/commands.ts b/examples/harness-cli-batman/src/screen/commands.ts
new file mode 100644
index 0000000000..3f6f84c683
--- /dev/null
+++ b/examples/harness-cli-batman/src/screen/commands.ts
@@ -0,0 +1,23 @@
+/** The commands of the screen itself. The harness adds its own to the list. */
+export const SCREEN_COMMANDS = [
+  {
+    name: "connect",
+    description: "Light the signal: connect a model provider, Notion, or Linear",
+  },
+  { name: "disconnect", description: "Cut a key or a sign-in" },
+  { name: "model", description: "Pick which mind patrols tonight" },
+  { name: "effort", description: "Pick how hard the model thinks" },
+  { name: "resume", description: "Continue a saved session" },
+  { name: "mic", description: "Pick the microphone" },
+  { name: "open", description: "Open a media file (default: the last one)" },
+  { name: "play", description: "Play an audio or video file" },
+  {
+    name: "voice",
+    description: "Send a recorded voice message: /voice note.m4a",
+  },
+  { name: "help", description: "Show the commands and the voice tips" },
+  { name: "exit", description: "Return to the cave" },
+];
+
+// Commands that need text after the name: Enter in the list fills the name.
+export const TAKES_INPUT = new Set(["voice"]);
diff --git a/examples/harness-cli-batman/src/screen/editor.ts b/examples/harness-cli-batman/src/screen/editor.ts
new file mode 100644
index 0000000000..85bd990524
--- /dev/null
+++ b/examples/harness-cli-batman/src/screen/editor.ts
@@ -0,0 +1,124 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { useReducer, useRef } from "react";
+
+// The lines you sent, for the up and down arrows, kept next to the sign-ins.
+const historyFile = join(homedir(), ".tanstack-harness-example", "history.json");
+const HISTORY_SIZE = 200;
+
+function loadHistory() {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(historyFile, "utf8"));
+    return Array.isArray(parsed) ? parsed.filter((item) => typeof item === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
+function saveHistory(lines: ReadonlyArray<string>) {
+  try {
+    mkdirSync(dirname(historyFile), { recursive: true });
+    writeFileSync(historyFile, JSON.stringify(lines.slice(-HISTORY_SIZE)));
+  } catch {
+    // ponytail: history is a convenience. A failed write loses it, no more.
+  }
+}
+
+/** The input line. `hidden`: it holds a secret (a key), shown as dots. */
+export interface Line {
+  text: string;
+  cursor: number;
+  hidden: boolean;
+}
+
+const empty: Line = { text: "", cursor: 0, hidden: false };
+
+/**
+ * The input line of the screen: typing at the cursor, the arrow keys, and
+ * the history of sent lines. The line is in a ref, so a key that comes
+ * before React renders still sees the keys before it.
+ */
+export function useLineEditor() {
+  const current = useRef<Line>(empty);
+  const [, render] = useReducer((count: number) => count + 1, 0);
+  const history = useRef<Array<string>>(loadHistory());
+  // While you go through the history: where you are, and the line you had.
+  const browsing = useRef<{ index: number; draft: string } | undefined>(undefined);
+  const show = (line: Line) => {
+    current.current = line;
+    render();
+  };
+  const edit = (line: Line) => {
+    browsing.current = undefined;
+    show(line);
+  };
+  const showText = (text: string) => show({ text, cursor: text.length, hidden: false });
+
+  return {
+    get line() {
+      return current.current;
+    },
+    /** The line came from the history (the arrows), not from typing. */
+    get browsing() {
+      return browsing.current !== undefined;
+    },
+    /** Type or paste at the cursor. A hidden line stays hidden until it is empty. */
+    insert: (text: string, hidden = false) => {
+      const line = current.current;
+      edit({
+        text: line.text.slice(0, line.cursor) + text + line.text.slice(line.cursor),
+        cursor: line.cursor + text.length,
+        hidden: hidden || (line.hidden && line.text !== ""),
+      });
+    },
+    /** Delete the character before the cursor. */
+    backspace: () => {
+      const line = current.current;
+      if (line.cursor === 0) return;
+      edit({
+        ...line,
+        text: line.text.slice(0, line.cursor - 1) + line.text.slice(line.cursor),
+        cursor: line.cursor - 1,
+      });
+    },
+    /** Move the cursor by `by` characters, or to the start or the end. */
+    move: (by: number | "start" | "end") => {
+      const line = current.current;
+      const target = by === "start" ? 0 : by === "end" ? line.text.length : line.cursor + by;
+      show({ ...line, cursor: Math.max(0, Math.min(line.text.length, target)) });
+    },
+    /** Replace the line. The cursor goes to `cursor`, or to the end. */
+    set: (text: string, cursor = text.length) => edit({ text, cursor, hidden: false }),
+    clear: () => edit(empty),
+    /** Keep a sent line for the up arrow. */
+    remember: (text: string) => {
+      const trimmed = text.trim();
+      if (trimmed === "" || history.current.at(-1) === trimmed) return;
+      history.current.push(trimmed);
+      saveHistory(history.current);
+    },
+    /** The up arrow: the sent line before the one shown. */
+    older: () => {
+      const lines = history.current;
+      if (lines.length === 0) return;
+      const at = browsing.current;
+      const index = at ? Math.max(0, at.index - 1) : lines.length - 1;
+      browsing.current = { index, draft: at?.draft ?? current.current.text };
+      showText(lines[index] ?? "");
+    },
+    /** The down arrow: the next sent line, then the line you had typed. */
+    newer: () => {
+      const at = browsing.current;
+      if (!at) return;
+      if (at.index >= history.current.length - 1) {
+        browsing.current = undefined;
+        showText(at.draft);
+        return;
+      }
+      const index = at.index + 1;
+      browsing.current = { ...at, index };
+      showText(history.current[index] ?? "");
+    },
+  };
+}
diff --git a/examples/harness-cli-batman/src/screen/footer.tsx b/examples/harness-cli-batman/src/screen/footer.tsx
new file mode 100644
index 0000000000..213bb08bdd
--- /dev/null
+++ b/examples/harness-cli-batman/src/screen/footer.tsx
@@ -0,0 +1,76 @@
+import React from "react";
+import { Box, Text } from "ink";
+import { REASONING_LEVELS } from "@tanstack/ai";
+import { clampReasoningLevel } from "@tanstack/ai-models";
+import { useSelector } from "@tanstack/react-store";
+import { modelInfo, reasons } from "../harness";
+import { PROVIDER_KEYS, USAGE, providerKeysIn, usageIn } from "./keys";
+import { ACCENT, compact } from "./theme";
+import type { SessionView } from "@tanstack/ai-harness/view";
+
+const BAR = 10;
+
+/**
+ * The status bar at the bottom: the model, how much of its context the
+ * conversation fills, and the tokens and model calls so far. It follows the
+ * session live. The features and the key hints are in the header.
+ */
+export function Footer({ view }: { view: SessionView }) {
+  const model = useSelector(view.store, (state) =>
+    String(state.config.find((entry) => entry.key === "model")?.value ?? "?"),
+  );
+  const effort = useSelector(
+    view.store,
+    (state) => state.config.find((entry) => entry.key === "effort")?.value,
+  );
+  // The plugin states themselves, so the bar renders only when they change.
+  const usageState = useSelector(view.store, (state) => state.plugins[USAGE]);
+  const keysState = useSelector(view.store, (state) => state.plugins[PROVIDER_KEYS]);
+  const usage = usageIn(usageState);
+  const keys = providerKeysIn(keysState);
+  const info = modelInfo[model];
+  const window = info?.record.contextWindow;
+  // The level the model gets: the adapter moves an effort the model does not
+  // have to the nearest one it has.
+  const level = REASONING_LEVELS.find((name) => name === effort);
+  const shownEffort =
+    info && level && reasons(model) ? clampReasoningLevel(info.record, level) : undefined;
+  const share = window ? Math.min(1, usage.contextTokens / window) : 0;
+  const filled = Math.round(share * BAR);
+  const barColor = share > 0.8 ? "red" : share > 0.5 ? "yellow" : "green";
+  const needsKey =
+    info !== undefined && keys.find((key) => key.id === info.provider)?.state === "missing";
+  // Each group keeps its width, and a group that does not fit goes to the
+  // next line.
+  return (
+    <Box flexWrap="wrap" columnGap={3}>
+      <Box flexShrink={0}>
+        <Text color={needsKey ? "red" : ACCENT} bold>{`🦇 ${model}`}</Text>
+        {needsKey ? <Text color="red">{`  (run /connect ${info.provider})`}</Text> : null}
+        {shownEffort ? <Text dimColor>{`  effort ${shownEffort}`}</Text> : null}
+      </Box>
+      <Box flexShrink={0}>
+        <Text dimColor>{"context "}</Text>
+        <Text>
+          {compact(usage.contextTokens)}
+          {window ? `/${compact(window)}` : ""}
+        </Text>
+        {window ? (
+          <>
+            <Text> </Text>
+            <Text color={barColor}>{"▰".repeat(filled)}</Text>
+            <Text dimColor>{"▱".repeat(BAR - filled)}</Text>
+            <Text dimColor>{` ${Math.round(share * 100)}%`}</Text>
+          </>
+        ) : null}
+      </Box>
+      <Box flexShrink={0}>
+        <Text dimColor>{"tokens in "}</Text>
+        <Text>{compact(usage.promptTokens)}</Text>
+        <Text dimColor>{" out "}</Text>
+        <Text>{compact(usage.completionTokens)}</Text>
+      </Box>
+      <Text dimColor>{`${usage.turns} model calls`}</Text>
+    </Box>
+  );
+}
diff --git a/examples/harness-cli-batman/src/screen/keys.ts b/examples/harness-cli-batman/src/screen/keys.ts
new file mode 100644
index 0000000000..df959d8bb1
--- /dev/null
+++ b/examples/harness-cli-batman/src/screen/keys.ts
@@ -0,0 +1,71 @@
+import type { features } from "../harness";
+
+// The names of the `providerKeys()` and `usage()` plugins: their state is in
+// the view's `state.plugins`.
+export const PROVIDER_KEYS = "tanstack/provider-keys";
+export const USAGE = "tanstack/usage";
+
+/** A model provider of `providerKeys()`, and where its key comes from. */
+export interface ProviderKey {
+  id: string;
+  label: string;
+  state: "connected" | "env" | "missing";
+}
+
+function isProviderKey(value: unknown): value is ProviderKey {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "id" in value &&
+    typeof value.id === "string" &&
+    "label" in value &&
+    typeof value.label === "string" &&
+    "state" in value &&
+    (value.state === "connected" || value.state === "env" || value.state === "missing")
+  );
+}
+
+/**
+ * The providers in `saved`, the state of the provider-keys plugin.
+ * `/connect` and `/disconnect` update it, so the screen shows the keys live.
+ * Empty before the plugin reports.
+ */
+export function providerKeysIn(saved: unknown) {
+  const isState = typeof saved === "object" && saved !== null && "providers" in saved;
+  if (!isState) return [];
+  const { providers } = saved;
+  return Array.isArray(providers) ? providers.filter(isProviderKey) : [];
+}
+
+/**
+ * Is `feature` on? A feature that needs a key follows the saved keys: any
+ * one of its providers with a key turns it on. The rest stay as at startup.
+ */
+export function isOn(feature: (typeof features)[number], keys: ReadonlyArray<ProviderKey>) {
+  const followsKeys = feature.providers.length > 0 && keys.length > 0;
+  if (!followsKeys) return feature.on;
+  return keys.some((key) => feature.providers.includes(key.id) && key.state !== "missing");
+}
+
+/** The totals of the usage plugin. */
+export interface Usage {
+  turns: number;
+  promptTokens: number;
+  completionTokens: number;
+  contextTokens: number;
+}
+
+/** The usage plugin state in `saved`, with 0 for anything it has not counted. */
+export function usageIn(saved: unknown): Usage {
+  const read = (key: string) => {
+    if (typeof saved !== "object" || saved === null || !(key in saved)) return 0;
+    const value: unknown = Reflect.get(saved, key);
+    return typeof value === "number" ? value : 0;
+  };
+  return {
+    turns: read("turns"),
+    promptTokens: read("promptTokens"),
+    completionTokens: read("completionTokens"),
+    contextTokens: read("contextTokens"),
+  };
+}
diff --git a/examples/harness-cli-batman/src/screen/markdown.ts b/examples/harness-cli-batman/src/screen/markdown.ts
new file mode 100644
index 0000000000..1b1b2413d8
--- /dev/null
+++ b/examples/harness-cli-batman/src/screen/markdown.ts
@@ -0,0 +1,61 @@
+import { renderMermaidASCII } from "beautiful-mermaid";
+import { Marked } from "marked";
+import { markedTerminal } from "marked-terminal";
+
+// A closed ```mermaid block. An open one (still streaming) stays code.
+const MERMAID = /```mermaid[^\n]*\n([\s\S]*?)```/g;
+
+// One parser for each width: marked-terminal wraps text to the width.
+const parsers = new Map<number, Marked>();
+function parserFor(width: number) {
+  let parser = parsers.get(width);
+  if (!parser) {
+    parser = new Marked(
+      markedTerminal({
+        width,
+        reflowText: true,
+        tab: 2,
+        emoji: false,
+        showSectionPrefix: false,
+      }),
+      {
+        renderer: {
+          // ponytail: marked-terminal 7 prints the text of a list item as it
+          // is, so `**bold**` in a list stays raw. This parses it.
+          text(token) {
+            return "tokens" in token && token.tokens
+              ? this.parser.parseInline(token.tokens)
+              : token.text;
+          },
+        },
+      },
+    );
+    parsers.set(width, parser);
+  }
+  return parser;
+}
+
+/**
+ * Markdown as terminal text, `width` columns wide: headings, lists, tables,
+ * links, and highlighted code. A Mermaid block becomes a chart drawn in text.
+ * A chart that does not parse stays a code block.
+ */
+export function renderMarkdown(text: string, width: number) {
+  const charts: Array<string> = [];
+  const source = text.replace(MERMAID, (block, code: string) => {
+    try {
+      charts.push(renderMermaidASCII(code));
+      // A plain word marked-terminal keeps as it is, in its own paragraph.
+      return `\n\nMERMAIDCHART${charts.length - 1}\n\n`;
+    } catch {
+      return block;
+    }
+  });
+  return (
+    parserFor(Math.max(20, width))
+      // An open (still streaming) Mermaid block shows as plain code.
+      .parse(source.replace(/```mermaid/g, "```"), { async: false })
+      .replace(/MERMAIDCHART(\d+)/g, (_match, index: string) => charts[Number(index)] ?? "")
+      .trimEnd()
+  );
+}
diff --git a/examples/harness-cli-batman/src/screen/media.ts b/examples/harness-cli-batman/src/screen/media.ts
new file mode 100644
index 0000000000..064ee626f6
--- /dev/null
+++ b/examples/harness-cli-batman/src/screen/media.ts
@@ -0,0 +1,116 @@
+import { spawn } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { useEffect, useState } from "react";
+import { assistant } from "../harness";
+import type { MediaPart, SessionView, ViewMessage, ViewPart } from "@tanstack/ai-harness/view";
+
+// ponytail: the CLI's default media folder, `./<harness-name>-media`. A custom
+// ui gets no `--media-dir`, and the CLI does not export `defaultMediaDir`, so
+// this copies its rule. The media id in front of the name keeps names unique.
+export const mediaDir = `${assistant.name.replace(/[^\w.-]+/g, "-").replace(/^[-.]+|-+$/g, "")}-media`;
+
+/** A media file the screen saved. `number` is what `/open` and `/play` take. */
+export interface Saved {
+  id: string;
+  number: number;
+  kind: string;
+  name: string;
+  path?: string;
+  error?: string;
+}
+
+/** Write the bytes of a media file into `mediaDir`, and return the path. */
+async function saveMedia(part: MediaPart) {
+  await mkdir(mediaDir, { recursive: true });
+  const path = join(mediaDir, `${part.id}-${basename(part.name)}`);
+  await writeFile(path, await part.load());
+  return path;
+}
+
+/** Add the media parts of `parts` to `into`, also the ones of child agents. */
+function collectMedia(parts: ReadonlyArray<ViewPart>, into: Array<MediaPart>) {
+  for (const part of parts) {
+    if (part.type === "media") into.push(part);
+    if (part.type === "agent") collectMedia(part.parts, into);
+  }
+}
+
+/** The media files that the agents made, from the assistant messages. */
+function generatedMedia(messages: ReadonlyArray<ViewMessage>) {
+  const media: Array<MediaPart> = [];
+  for (const message of messages) {
+    if (message.role === "assistant") collectMedia(message.parts, media);
+  }
+  return media;
+}
+
+/**
+ * Save each new media file once, and number it. Files in the history when
+ * the screen opens are not saved again. `saving(id)`: is that file new, and
+ * neither saved nor failed yet?
+ */
+export function useSavedMedia(view: SessionView, messages: Array<ViewMessage>) {
+  const [saved, setSaved] = useState<ReadonlyArray<Saved>>([]);
+  const [seen] = useState(
+    () => new Set(generatedMedia(view.store.get().messages).map((part) => part.id)),
+  );
+  useEffect(() => {
+    for (const part of generatedMedia(messages)) {
+      if (seen.has(part.id)) continue;
+      seen.add(part.id);
+      const number = seen.size;
+      const update = (change: Partial<Saved>) =>
+        setSaved((current) =>
+          current.map((item) => (item.id === part.id ? { ...item, ...change } : item)),
+        );
+      setSaved((current) => [
+        ...current,
+        { id: part.id, number, kind: part.kind, name: part.name },
+      ]);
+      saveMedia(part).then(
+        (path) => update({ path }),
+        (error: unknown) =>
+          update({
+            error: error instanceof Error ? error.message : String(error),
+          }),
+      );
+    }
+  }, [messages, seen]);
+  const saving = (id: string) => {
+    if (!seen.has(id)) return true;
+    const item = saved.find((entry) => entry.id === id);
+    return item !== undefined && !item.path && !item.error;
+  };
+  return { saved, saving };
+}
+
+/** Start a program without a shell. The screen still shows the path on error. */
+function launch(command: string, args: Array<string>) {
+  const child = spawn(command, args, { stdio: "ignore", detached: true });
+  child.on("error", () => {});
+  child.unref();
+}
+
+/** Open a link or a file with the default app. No shell is involved. */
+export function openExternal(target: string) {
+  if (process.platform === "win32") {
+    // Not `cmd /c start`: cmd would read `&` in a URL as a command separator.
+    if (/^https?:\/\//.test(target)) launch("rundll32", ["url.dll,FileProtocolHandler", target]);
+    else launch("explorer", [resolve(target)]);
+    return;
+  }
+  launch(process.platform === "darwin" ? "open" : "xdg-open", [target]);
+}
+
+/** Play audio or video with ffplay, which comes with ffmpeg. */
+export function play(item: Saved & { path: string }) {
+  const window = item.kind === "video" ? [] : ["-nodisp"];
+  launch(process.env.FFPLAY_PATH || "ffplay", [
+    ...window,
+    "-autoexit",
+    "-loglevel",
+    "quiet",
+    item.path,
+  ]);
+}
diff --git a/examples/harness-cli-batman/src/screen/menu.tsx b/examples/harness-cli-batman/src/screen/menu.tsx
new file mode 100644
index 0000000000..43abd4f670
--- /dev/null
+++ b/examples/harness-cli-batman/src/screen/menu.tsx
@@ -0,0 +1,59 @@
+import React from "react";
+import { Box, Text } from "ink";
+import { ACCENT } from "./theme";
+
+/** One row of the command list or of a picker. */
+export interface MenuItem {
+  id: string;
+  label: string;
+  detail?: string;
+  /** The current choice, for example the model in use. */
+  current?: boolean;
+}
+
+const VISIBLE = 8;
+
+/**
+ * A list you move through with the arrow keys: the `/` command list, or a
+ * picker such as `/connect` or `/model`. It shows at most 8 rows around the
+ * selected one.
+ */
+export function Menu({
+  title,
+  items,
+  selected,
+  hint,
+}: {
+  title?: string;
+  items: ReadonlyArray<MenuItem>;
+  selected: number;
+  hint: string;
+}) {
+  const start = Math.max(0, Math.min(selected - Math.floor(VISIBLE / 2), items.length - VISIBLE));
+  const shown = items.slice(start, start + VISIBLE);
+  const width = Math.max(...items.map((item) => item.label.length), 8);
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="gray" paddingX={1}>
+      {title ? <Text bold>{title}</Text> : null}
+      {shown.map((item, index) => {
+        const isSelected = start + index === selected;
+        return (
+          <Box key={item.id}>
+            <Box flexShrink={0}>
+              <Text color={isSelected ? ACCENT : undefined} bold={isSelected}>
+                {`${isSelected ? "🦇" : " "} ${item.label.padEnd(width)}`}
+              </Text>
+            </Box>
+            <Text color={item.current ? "green" : "gray"} wrap="truncate-end">
+              {`  ${item.current ? "● " : ""}${item.detail ?? ""}`}
+            </Text>
+          </Box>
+        );
+      })}
+      {items.length > VISIBLE ? (
+        <Text dimColor>{`  ${selected + 1} of ${items.length}`}</Text>
+      ) : null}
+      <Text dimColor>{hint}</Text>
+    </Box>
+  );
+}
diff --git a/examples/harness-cli-batman/src/screen/parts.tsx b/examples/harness-cli-batman/src/screen/parts.tsx
new file mode 100644
index 0000000000..04be383e5d
--- /dev/null
+++ b/examples/harness-cli-batman/src/screen/parts.tsx
@@ -0,0 +1,254 @@
+import { basename } from "node:path";
+import React, { useMemo } from "react";
+import { Box, Spacer, Text, useAnimation } from "ink";
+import { renderMarkdown } from "./markdown";
+import { ACCENT, KIND_COLOR, SPINNER } from "./theme";
+import type {
+  AgentPart,
+  MediaPart,
+  ToolCallPart,
+  ViewMessage,
+  ViewPart,
+} from "@tanstack/ai-harness/view";
+import type { Saved } from "./media";
+
+export function Spinner({ color = "yellow" }: { color?: string }) {
+  const { frame } = useAnimation({ interval: 90 });
+  return <Text color={color}>{SPINNER[frame % SPINNER.length]}</Text>;
+}
+
+function textOf(parts: ReadonlyArray<ViewPart>) {
+  return parts.map((part) => (part.type === "text" ? part.text : "")).join("");
+}
+
+/** A short one-line view of tool arguments. */
+function argsPreview(call: ToolCallPart) {
+  const text =
+    typeof call.args === "object" && call.args !== null
+      ? Object.values(call.args)
+          .filter((value) => typeof value === "string")
+          .join(", ")
+      : "";
+  const line = text.replace(/\s+/g, " ").trim();
+  return line.length > 70 ? `${line.slice(0, 70)}...` : line;
+}
+
+function ToolLine({ call, indent = 2 }: { call: ToolCallPart; indent?: number }) {
+  const icon =
+    call.status === "running" ? (
+      <Spinner />
+    ) : call.status === "done" ? (
+      <Text color="green">✓</Text>
+    ) : call.status === "failed" ? (
+      <Text color="red">✗</Text>
+    ) : (
+      <Text color="magenta">?</Text>
+    );
+  const preview = argsPreview(call);
+  return (
+    <Box marginLeft={indent}>
+      {icon}
+      <Text color="yellow">{` ${call.name}`}</Text>
+      {preview ? <Text dimColor>{`  ${preview}`}</Text> : null}
+      {call.status === "needs-approval" ? (
+        <Text color="magenta"> waits for your approval</Text>
+      ) : null}
+    </Box>
+  );
+}
+
+function MediaLine({
+  part,
+  saved,
+  indent = 2,
+}: {
+  part: MediaPart;
+  saved: ReadonlyArray<Saved>;
+  indent?: number;
+}) {
+  const item = saved.find((entry) => entry.id === part.id);
+  const color = KIND_COLOR[part.kind] ?? "white";
+  return (
+    <Box marginLeft={indent}>
+      <Text color={color} bold>
+        {`▣ ${item ? `${item.number} ` : ""}${part.kind}`}
+      </Text>
+      <Text>{`  ${part.name}`}</Text>
+      {item?.path ? <Text dimColor>{`  -> ${item.path}`}</Text> : null}
+      {item?.error ? <Text color="red">{`  not saved: ${item.error}`}</Text> : null}
+      {item && !item.path && !item.error ? <Text dimColor> saving...</Text> : null}
+    </Box>
+  );
+}
+
+/**
+ * A child agent, for example Codex or Claude Code, in its own card: its
+ * status, its last tool calls, its media, and its output. While it runs, the
+ * last 4 lines show. When it ends, the last 15 lines of its answer stay.
+ */
+function Agent({ part, saved }: { part: AgentPart; saved: ReadonlyArray<Saved> }) {
+  const lines = textOf(part.parts)
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim() !== "");
+  const running = part.status === "running";
+  const output = running ? lines.slice(-4) : lines.slice(-15);
+  const calls = part.parts.flatMap((inner) => (inner.type === "tool-call" ? [inner] : []));
+  const media = part.parts.flatMap((inner) => (inner.type === "media" ? [inner] : []));
+  const color = part.status === "failed" ? "red" : running ? "yellow" : "green";
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor={color} paddingX={1} marginLeft={2}>
+      <Box>
+        {running ? (
+          <Spinner color={color} />
+        ) : (
+          <Text color={color}>{part.status === "done" ? "✓" : "✗"}</Text>
+        )}
+        <Text bold>{` ${part.name}`}</Text>
+        <Spacer />
+        <Text color={color}>{part.status}</Text>
+      </Box>
+      {calls.slice(-4).map((call) => (
+        <ToolLine key={call.id} call={call} indent={0} />
+      ))}
+      {media.map((inner) => (
+        <MediaLine key={inner.id} part={inner} saved={saved} indent={0} />
+      ))}
+      {output.map((line, index) => (
+        <Text key={`line-${index}`} dimColor={running}>
+          {line}
+        </Text>
+      ))}
+      {part.error ? <Text color="red">{part.error}</Text> : null}
+    </Box>
+  );
+}
+
+/** The model's text as markdown, `width` columns wide. */
+function Markdown({ text, width }: { text: string; width: number }) {
+  const shown = useMemo(() => renderMarkdown(text, width), [text, width]);
+  return (
+    <Box marginLeft={2}>
+      <Text>{shown}</Text>
+    </Box>
+  );
+}
+
+function Part({
+  part,
+  saved,
+  width,
+}: {
+  part: ViewPart;
+  saved: ReadonlyArray<Saved>;
+  width: number;
+}) {
+  switch (part.type) {
+    case "text":
+      return <Markdown text={part.text} width={width - 2} />;
+    case "reasoning":
+      return (
+        <Box marginLeft={2}>
+          <Text dimColor italic>
+            {part.text}
+          </Text>
+        </Box>
+      );
+    case "tool-call":
+      return <ToolLine call={part} />;
+    case "agent":
+      return <Agent part={part} saved={saved} />;
+    case "media":
+      return <MediaLine part={part} saved={saved} />;
+  }
+}
+
+export function Message({
+  message,
+  saved,
+  width,
+}: {
+  message: ViewMessage;
+  saved: ReadonlyArray<Saved>;
+  /** The terminal width, for the markdown of the model's text. */
+  width: number;
+}) {
+  switch (message.role) {
+    case "user": {
+      // A voice message names its files as `@"path"`, shown as a file badge.
+      const named: Array<string> = [];
+      const text = message.text
+        .replace(/@"([^"]+)"/g, (_match, path: string) => {
+          named.push(basename(path));
+          return "";
+        })
+        .trim();
+      const files = [...(message.media ?? []).map((part) => `${part.kind} ${part.name}`), ...named];
+      return (
+        <Box marginTop={1} flexWrap="wrap">
+          <Text bold>
+            <Text color={ACCENT}>🦇 </Text>
+            {text}
+            {files.length > 0 ? " " : ""}
+          </Text>
+          {files.map((file) => (
+            <Text key={file} color="black" backgroundColor={ACCENT}>
+              {` ${file} `}
+            </Text>
+          ))}
+        </Box>
+      );
+    }
+    case "notice": {
+      const isError = message.kind === "error";
+      // A command's answer, for example "Connected to Notion.", stands out.
+      const done =
+        message.kind === "command" && /^(Connected|Disconnected|Model|Effort)\b/.test(message.text);
+      return (
+        <Box marginLeft={2}>
+          <Text color={isError ? "red" : done ? "green" : "gray"} bold={done}>
+            {`${isError ? "✗" : done ? "✓" : "·"} ${message.text}`}
+          </Text>
+        </Box>
+      );
+    }
+    case "assistant":
+      return (
+        <Box flexDirection="column" marginTop={1}>
+          {message.parts.map((part, index) => (
+            <Part key={index} part={part} saved={saved} width={width} />
+          ))}
+        </Box>
+      );
+  }
+}
+
+/** Does a part still change: a running tool or agent, or media still saving? */
+function isLivePart(part: ViewPart, saving: (id: string) => boolean): boolean {
+  if (part.type === "tool-call")
+    return part.status === "running" || part.status === "needs-approval";
+  if (part.type === "agent")
+    return part.status === "running" || part.parts.some((inner) => isLivePart(inner, saving));
+  return part.type === "media" && saving(part.id);
+}
+
+/**
+ * How many messages from the start no longer change. The screen prints them
+ * once, above the live area, so a long conversation does not redraw.
+ * `running`: a turn streams now, so the last assistant message can still
+ * grow. The screen never takes back a printed message, so holding the one of
+ * the turn before costs nothing.
+ */
+export function settledCount(
+  messages: ReadonlyArray<ViewMessage>,
+  saving: (id: string) => boolean,
+  running: boolean,
+) {
+  const lastAssistant = messages.map((message) => message.role).lastIndexOf("assistant");
+  for (const [index, message] of messages.entries()) {
+    if (message.role !== "assistant") continue;
+    const streaming = running && index === lastAssistant;
+    if (streaming || message.parts.some((part) => isLivePart(part, saving))) return index;
+  }
+  return messages.length;
+}
diff --git a/examples/harness-cli-batman/src/screen/paths.ts b/examples/harness-cli-batman/src/screen/paths.ts
new file mode 100644
index 0000000000..b4b0b1e219
--- /dev/null
+++ b/examples/harness-cli-batman/src/screen/paths.ts
@@ -0,0 +1,70 @@
+import { readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Line } from "./editor";
+import type { MenuItem } from "./menu";
+
+/**
+ * An `@path` that is being typed, just before the cursor: an `@` at the
+ * start or after white space, then a quoted path that is not closed yet
+ * (`@"my ca`), or the text up to the cursor. runCli attaches the same tokens.
+ */
+const TYPING = /(^|\s)@(?:"([^"]*)|([^\s"]*))$/;
+
+/** A file or a folder in the `@` list. `fill` replaces the typed token. */
+export interface PathItem extends MenuItem {
+  fill: string;
+}
+
+/**
+ * The files and folders that the `@path` before the cursor can name, from
+ * the working folder, where runCli finds the files it attaches. Folders
+ * come first. Hidden files show only when the typed name starts with a dot.
+ * `start` is where the token starts in the line. `undefined` when no token
+ * is typed, nothing matches, or the token already names a file.
+ * ponytail: one folder read, at most 100 entries.
+ */
+export function pathSuggestions(line: Line, cwd = process.cwd()) {
+  const match = TYPING.exec(line.text.slice(0, line.cursor));
+  if (!match) return undefined;
+  const quoted = match[2] !== undefined;
+  const typed = match[2] ?? match[3] ?? "";
+  const dir = typed.slice(0, typed.lastIndexOf("/") + 1);
+  const name = typed.slice(dir.length).toLowerCase();
+  let entries;
+  try {
+    entries = readdirSync(resolve(cwd, dir || "."), { withFileTypes: true });
+  } catch {
+    return undefined;
+  }
+  const items = entries
+    .filter(
+      (entry) =>
+        entry.name.toLowerCase().startsWith(name) &&
+        (name.startsWith(".") || !entry.name.startsWith(".")),
+    )
+    .sort(
+      (a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name),
+    )
+    .slice(0, 100)
+    .map((entry): PathItem => {
+      const folder = entry.isDirectory();
+      const path = `${dir}${entry.name}${folder ? "/" : ""}`;
+      // A path with a space needs quotes. A folder stays open, so the next
+      // name can follow it. A file ends the token with a space.
+      const fill =
+        quoted || /\s/.test(path)
+          ? `@"${path}${folder ? "" : '" '}`
+          : `@${path}${folder ? "" : " "}`;
+      return {
+        id: path,
+        label: path,
+        fill,
+        ...(folder ? { detail: "folder" } : {}),
+      };
+    });
+  const [only] = items;
+  if (items.length === 0 || (items.length === 1 && only?.id === typed)) {
+    return undefined;
+  }
+  return { start: match.index + (match[1] ?? "").length, items };
+}
diff --git a/examples/harness-cli-batman/src/screen/splash.tsx b/examples/harness-cli-batman/src/screen/splash.tsx
new file mode 100644
index 0000000000..ae4c55b4bc
--- /dev/null
+++ b/examples/harness-cli-batman/src/screen/splash.tsx
@@ -0,0 +1,155 @@
+import React, { useEffect, useState } from "react";
+import { Box, Text, render, useApp, useInput, useWindowSize } from "ink";
+import { ACCENT, GOLD, NIGHT } from "./theme";
+import { POSES, STAND, SYMBOL } from "./batman-art";
+import type { RenderOptions } from "ink";
+
+const TAGLINE = "I   A M   T H E   N I G H T";
+const SUB = "TanStack AI harness  ·  Gotham terminal";
+const FILL = new Set("8");
+
+const SYMBOL_MS = 1800;
+const POSE_MS = 340;
+const HOLD_MS = 700;
+const END = SYMBOL_MS + POSE_MS * POSES.length * 2 + HOLD_MS;
+
+const easeOut = (x: number) => 1 - (1 - Math.min(1, Math.max(0, x))) ** 3;
+
+const BAT_SEEDS = [0.1, 0.28, 0.47, 0.63, 0.81, 0.94, 0.17, 0.55];
+
+function batLine(width: number, elapsed: number, reverse: boolean) {
+  const marks = new Map<number, string>();
+  const span = Math.max(10, width + 10);
+  for (const [index, seed] of BAT_SEEDS.entries()) {
+    const speed = 28 + (index % 4) * 9;
+    let x = Math.floor((elapsed / speed + seed * span) % span) - 5;
+    if (reverse) x = width - x - 2;
+    if (x >= 0 && x <= width - 2) marks.set(x, index % 3 === 0 ? "✦" : "🦇");
+  }
+  let out = "";
+  for (let i = 0; i < width;) {
+    const mark = marks.get(i);
+    if (mark) {
+      out += mark;
+      i += 2;
+    } else {
+      out += " ";
+      i += 1;
+    }
+  }
+  return out;
+}
+
+function hop(frame: ReadonlyArray<string>, up: boolean) {
+  if (up || frame.length === 0) return frame;
+  const blank = " ".repeat(frame[0]?.length ?? 0);
+  return [blank, ...frame.slice(0, -1)];
+}
+
+/** One row of ASCII, cut into runs of one color. */
+function Row(props: {
+  text: string;
+  shown: number;
+  light: number;
+  revealing: boolean;
+  fill?: Set<string>;
+}) {
+  const { text, shown, light, revealing, fill } = props;
+  const runs: Array<{ color: string | undefined; text: string }> = [];
+  for (const [column, char] of [...text].entries()) {
+    const visible = column < shown && char !== " ";
+    const lit = Math.abs(column - light) < 3 || (revealing && column >= shown - 2);
+    const color = !visible ? undefined : lit || fill?.has(char) ? GOLD : ACCENT;
+    const shownChar = column < shown ? char : " ";
+    const last = runs.at(-1);
+    if (last && last.color === color) last.text += shownChar;
+    else runs.push({ color, text: shownChar });
+  }
+  return (
+    <Text>
+      {runs.map((run, index) => (
+        <Text key={index} color={run.color}>
+          {run.text}
+        </Text>
+      ))}
+    </Text>
+  );
+}
+
+function Splash() {
+  const { exit } = useApp();
+  const { columns, rows } = useWindowSize();
+  const [elapsed, setElapsed] = useState(0);
+  useEffect(() => {
+    const start = Date.now();
+    const timer = setInterval(() => {
+      const now = Date.now() - start;
+      setElapsed(now);
+      if (now >= END) exit();
+    }, 33);
+    return () => clearInterval(timer);
+  }, []);
+  useInput(() => exit());
+
+  const canSymbol = columns >= (SYMBOL[0]?.length ?? 0) + 2;
+  const canPoses = columns >= (POSES[0]?.[0]?.length ?? 0) + 2;
+  const showSymbol = canSymbol && elapsed < SYMBOL_MS;
+  const poseSource = canPoses ? POSES : [STAND];
+  const poseAt = Math.max(0, elapsed - (canSymbol ? SYMBOL_MS : 0));
+  const poseIndex = Math.floor(poseAt / POSE_MS) % poseSource.length;
+  const pose = hop(poseSource[poseIndex] ?? STAND, Math.floor(poseAt / 170) % 2 === 0);
+  const art = showSymbol ? SYMBOL : pose;
+  const width = art[0]?.length ?? 0;
+  const revealFor = showSymbol ? SYMBOL_MS * 0.55 : 280;
+  const local = showSymbol ? elapsed : poseAt % POSE_MS;
+  const shown = Math.ceil(width * easeOut(Math.min(1, local / revealFor)));
+  const light = -6 + (width + 12) * easeOut(Math.min(1, local / (revealFor + 400)));
+  const revealing = local < revealFor;
+  const typed = Math.round(TAGLINE.length * easeOut(elapsed / 900));
+  const inner = Math.max(8, columns);
+  const showBats = rows >= (art.length ?? 0) + 6;
+
+  return (
+    <Box
+      width={columns}
+      height={Math.max(1, rows - 1)}
+      flexDirection="column"
+      alignItems="center"
+      justifyContent="center"
+    >
+      {showBats ? <Text color={ACCENT}>{batLine(inner, elapsed, false)}</Text> : null}
+      <Box marginTop={showBats ? 1 : 0} flexDirection="column" alignItems="center">
+        {art.map((line, index) => (
+          <Row
+            key={`${showSymbol ? "symbol" : poseIndex}-${index}`}
+            text={line}
+            shown={shown}
+            light={light}
+            revealing={revealing}
+            fill={showSymbol ? FILL : undefined}
+          />
+        ))}
+      </Box>
+      <Box marginTop={1}>
+        <Text color={GOLD} bold>
+          {TAGLINE.slice(0, Math.max(0, typed)).padEnd(TAGLINE.length)}
+        </Text>
+      </Box>
+      <Text dimColor>{elapsed > 700 ? SUB : ""}</Text>
+      {showBats ? (
+        <Box marginTop={1}>
+          <Text color={NIGHT}>{batLine(inner, elapsed + 400, true)}</Text>
+        </Box>
+      ) : null}
+    </Box>
+  );
+}
+
+/**
+ * The boot animation: the bat symbol, then three Batman poses. About 4.5
+ * seconds. A key skips it. A narrow screen gets the standing pose only.
+ */
+export async function showSplash(io: RenderOptions = {}) {
+  const app = render(<Splash />, io);
+  await app.waitUntilExit();
+}
diff --git a/examples/harness-cli-batman/src/screen/status.tsx b/examples/harness-cli-batman/src/screen/status.tsx
new file mode 100644
index 0000000000..31044a7d74
--- /dev/null
+++ b/examples/harness-cli-batman/src/screen/status.tsx
@@ -0,0 +1,98 @@
+import React from "react";
+import { Box, Text, useAnimation } from "ink";
+import { useSelector } from "@tanstack/react-store";
+import { selectGoal } from "@tanstack/ai-harness/plugins";
+import { Spinner } from "./parts";
+import type { SessionView } from "@tanstack/ai-harness/view";
+import type { Recording } from "../voice";
+
+export type VoiceState = "idle" | "starting" | "recording" | "transcribing";
+
+/** A live level meter from the microphone loudness (0 to 32768). */
+function LevelMeter({ recording }: { recording: Recording }) {
+  const { time } = useAnimation({ interval: 80 });
+  const level = recording.level();
+  // Map loudness to 0..1 on a log scale: -60 dB is empty, 0 dB is full.
+  const decibels = 20 * Math.log10(Math.max(level, 1) / 32768);
+  const filled = Math.round(Math.min(1, Math.max(0, (decibels + 60) / 60)) * 16);
+  const seconds = Math.floor(time / 1000);
+  const clock = `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
+  return (
+    <Box>
+      <Text color="red" bold>{`● REC ${clock}  `}</Text>
+      <Text color={filled > 9 ? "green" : filled > 4 ? "yellow" : "gray"}>
+        {"▮".repeat(filled)}
+      </Text>
+      <Text dimColor>{"▯".repeat(16 - filled)}</Text>
+      <Text dimColor>{`  ${recording.microphone}`}</Text>
+    </Box>
+  );
+}
+
+/** What waits for the user or runs now: sign-ins, approvals, voice, the turn. */
+export function Status({
+  view,
+  voice,
+  recording,
+}: {
+  view: SessionView;
+  voice: VoiceState;
+  recording: Recording | undefined;
+}) {
+  const status = useSelector(view.store, (state) => state.status);
+  const approvals = useSelector(view.store, (state) => state.approvals);
+  const question = useSelector(view.store, (state) => state.questions.at(0));
+  const signIns = useSelector(view.store, (state) => state.signIns);
+  const goal = useSelector(view.store, selectGoal);
+  return (
+    <Box flexDirection="column" marginTop={1}>
+      {/* A key question says itself that the page is open, so it waits alone. */}
+      {question
+        ? null
+        : signIns.map((signIn) => (
+            <Box key={signIn.connector} flexDirection="column">
+              <Box>
+                <Spinner color="magenta" />
+                <Text color="magenta">
+                  {` 🦇 Waiting for you to sign in to ${signIn.connector} in your browser${signIn.userCode ? ` (code ${signIn.userCode})` : ""}.`}
+                </Text>
+              </Box>
+              {signIn.url ? <Text dimColor>{`  No tab opened? Open ${signIn.url}`}</Text> : null}
+            </Box>
+          ))}
+      {approvals.length > 0 ? (
+        <Text color="magenta" bold>
+          {`🦇 Approve ${approvals.map((item) => item.tool).join(", ")}? Type y or n.`}
+        </Text>
+      ) : null}
+      {question ? <Text color="magenta">{`🦇 ${question.message}`}</Text> : null}
+      {goal ? (
+        <Text color="yellow">{`🦇 Goal: ${goal.text} (${goal.status}, round ${goal.round})`}</Text>
+      ) : null}
+      {voice === "recording" && recording ? (
+        <Box flexDirection="column">
+          <LevelMeter recording={recording} />
+          <Text dimColor>Let go of Ctrl+R (or tap it again) to send. Esc drops it.</Text>
+        </Box>
+      ) : voice === "starting" ? (
+        <Box>
+          <Spinner color="red" />
+          <Text color="red"> opening the cave microphone...</Text>
+          <Text dimColor> Esc cancels</Text>
+        </Box>
+      ) : voice === "transcribing" ? (
+        <Box>
+          <Spinner color="cyan" />
+          <Text color="cyan"> transcribing your voice...</Text>
+          <Text dimColor> Esc cancels</Text>
+        </Box>
+      ) : status === "running" ? (
+        <Box>
+          <Spinner />
+          <Text color="yellow"> patrolling Gotham</Text>
+          <Text dimColor> Esc cancels, typing steers</Text>
+        </Box>
+      ) : null}
+    </Box>
+  );
+}
diff --git a/examples/harness-cli-batman/src/screen/theme.ts b/examples/harness-cli-batman/src/screen/theme.ts
new file mode 100644
index 0000000000..93bb26f8f2
--- /dev/null
+++ b/examples/harness-cli-batman/src/screen/theme.ts
@@ -0,0 +1,20 @@
+// Bat-signal yellow on a dark terminal.
+export const ACCENT = "#f5d000";
+export const GOLD = "#fff3a0";
+export const NIGHT = "#6b5a12";
+
+export const KIND_COLOR: Record<string, string> = {
+  image: "yellow",
+  audio: "cyan",
+  video: "blue",
+  document: "white",
+};
+
+export const SPINNER = ["🦇", "⚡", "🌙", "🦇", "✦", "⚡"];
+
+/** 12400 is "12.4k", 1050000 is "1.05M". */
+export function compact(count: number) {
+  if (count >= 1_000_000) return `${Number((count / 1_000_000).toFixed(2))}M`;
+  if (count >= 1_000) return `${Number((count / 1_000).toFixed(1))}k`;
+  return String(count);
+}
diff --git a/examples/harness-cli-batman/src/sessions.ts b/examples/harness-cli-batman/src/sessions.ts
new file mode 100644
index 0000000000..c355f12542
--- /dev/null
+++ b/examples/harness-cli-batman/src/sessions.ts
@@ -0,0 +1,155 @@
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { logMessageStore } from "@tanstack/ai-harness";
+import { LogConflictError, defineLogStore, defineMetadataStore } from "@tanstack/ai-persistence";
+import { SAVE_DIR, jsonFile } from "./credentials";
+import type { ModelMessage } from "@tanstack/ai";
+import type { LogRecord } from "@tanstack/ai-persistence";
+
+/** One file for each session, in your home folder. */
+const SESSIONS_DIR = join(SAVE_DIR, "sessions");
+const fileOf = (threadId: string) => join(SESSIONS_DIR, `${encodeURIComponent(threadId)}.jsonl`);
+
+/**
+ * The records of a session file. Each line is one batch of records. A crash
+ * while a line is written leaves a cut last line: it is removed with its
+ * batch, so a batch is in the file in full or not at all.
+ */
+async function readLog(file: string) {
+  const text = await readFile(file, "utf8").catch(() => "");
+  const lines = text.split("\n").filter((line) => line !== "");
+  const records: Array<LogRecord> = [];
+  for (const [index, line] of lines.entries()) {
+    try {
+      records.push(...(JSON.parse(line) as Array<LogRecord>));
+    } catch (error) {
+      if (index < lines.length - 1) throw error;
+      await writeFile(file, lines.slice(0, -1).join("\n") + "\n");
+    }
+  }
+  return records;
+}
+
+/**
+ * The session log, in files: the transcript, the inputs, and the events of
+ * each session, so a session survives a restart. It keeps each session in
+ * memory after the first read.
+ * ponytail: for one process. Two CLIs on one session need a store with
+ * locks, for example a database.
+ */
+function fileLog() {
+  const loaded = new Map<string, Promise<Array<LogRecord>>>();
+  const listeners = new Map<string, Set<() => void>>();
+  let appending = Promise.resolve();
+  const load = (threadId: string) => {
+    let log = loaded.get(threadId);
+    if (!log) {
+      log = readLog(fileOf(threadId));
+      loaded.set(threadId, log);
+    }
+    return log;
+  };
+  return defineLogStore({
+    append: (threadId, seq, records) => {
+      const run = appending.then(async () => {
+        if (records.length === 0) return;
+        const log = await load(threadId);
+        if (seq !== log.length + 1) throw new LogConflictError(threadId, seq);
+        const line = JSON.stringify(records);
+        await mkdir(SESSIONS_DIR, { recursive: true });
+        await appendFile(fileOf(threadId), `${line}\n`);
+        log.push(...(JSON.parse(line) as Array<LogRecord>));
+        for (const listener of [...(listeners.get(threadId) ?? [])]) {
+          listener();
+        }
+      });
+      appending = run.catch(() => {});
+      return run;
+    },
+    read: async (threadId, options = {}) => {
+      const log = await load(threadId);
+      const after = options.after ?? 0;
+      const end = options.limit === undefined ? log.length : after + options.limit;
+      return log.slice(after, end).map((record, index) => ({
+        seq: after + index + 1,
+        record: structuredClone(record),
+      }));
+    },
+    subscribe: (threadId, listener) => {
+      const set = listeners.get(threadId) ?? new Set();
+      listeners.set(threadId, set);
+      set.add(listener);
+      return () => {
+        set.delete(listener);
+      };
+    },
+  });
+}
+
+/** Each session's settings and plugin state (the model, the todos), in a file. */
+function fileMetadata() {
+  const { load, update } = jsonFile<unknown>(join(SAVE_DIR, "metadata.json"));
+  return defineMetadataStore({
+    get: async (namespace, key) => structuredClone((await load())[namespace]?.[key] ?? null),
+    set: (namespace, key, value) =>
+      update((all) => {
+        all[namespace] = { ...all[namespace], [key]: value };
+      }),
+    delete: (namespace, key) =>
+      update((all) => {
+        delete all[namespace]?.[key];
+      }),
+  });
+}
+
+export const sessionLog = fileLog();
+export const sessionMetadata = fileMetadata();
+
+/** A new session id: short, so it is easy to type after `--resume`. */
+export const newSessionId = () => randomUUID().slice(0, 8);
+
+/** Is `threadId` a saved session? */
+export async function hasSession(threadId: string) {
+  return (await sessionLog.read(threadId, { limit: 1 })).length > 0;
+}
+
+/** The first thing the user said in a session, on one line. */
+function titleOf(messages: ReadonlyArray<ModelMessage>) {
+  const content = messages.find((message) => message.role === "user")?.content;
+  const text =
+    typeof content === "string"
+      ? content
+      : (content ?? []).flatMap((part) => (part.type === "text" ? [part.content] : []));
+  return [text].flat().join(" ").replace(/\s+/g, " ").trim();
+}
+
+/**
+ * The saved sessions, newest first, with what the user said first. A
+ * session with no message yet is left out. The threads of child agents
+ * (`<session>:<agent>`) are not sessions of their own.
+ * ponytail: it reads the files in full, newest first, until it has `limit`
+ * sessions. An index file is faster when there are many big sessions.
+ */
+export async function listSessions(limit = 20) {
+  const names = await readdir(SESSIONS_DIR).catch(() => []);
+  const files = await Promise.all(
+    names
+      .filter((name) => name.endsWith(".jsonl"))
+      .map(async (name) => ({
+        id: decodeURIComponent(name.slice(0, -".jsonl".length)),
+        updatedAt: (await stat(join(SESSIONS_DIR, name))).mtimeMs,
+      })),
+  );
+  const recent = files
+    .filter((file) => !file.id.includes(":"))
+    .sort((a, b) => b.updatedAt - a.updatedAt);
+  const messages = logMessageStore({ store: sessionLog });
+  const sessions: Array<{ id: string; updatedAt: number; title: string }> = [];
+  for (const file of recent) {
+    if (sessions.length === limit) break;
+    const title = titleOf(await messages.loadThread(file.id));
+    if (title !== "") sessions.push({ ...file, title });
+  }
+  return sessions;
+}
diff --git a/examples/harness-cli-batman/src/store.ts b/examples/harness-cli-batman/src/store.ts
new file mode 100644
index 0000000000..8c2d8d9108
--- /dev/null
+++ b/examples/harness-cli-batman/src/store.ts
@@ -0,0 +1,51 @@
+import { defineAIPersistence, memoryPersistence, retrieveBlob } from "@tanstack/ai-persistence";
+import { fileCredentials } from "./credentials";
+import { sessionLog, sessionMetadata } from "./sessions";
+import type { ByokProvider } from "@tanstack/ai/byok";
+
+/** Sign-ins and the model keys you save with `/connect`, kept in a file. */
+const credentials = fileCredentials();
+const memory = memoryPersistence().stores;
+
+/**
+ * The sessions, their settings, and the sign-ins and keys are kept in files,
+ * so `--resume <id>` and `/resume` continue a session after a restart. The
+ * rest is in memory: the run records, the approvals, and the media (the
+ * files you send and the files agents make).
+ */
+export const persistence = defineAIPersistence({
+  stores: {
+    log: sessionLog,
+    metadata: sessionMetadata,
+    credentials,
+    runs: memory.runs,
+    interrupts: memory.interrupts,
+    generationRuns: memory.generationRuns,
+    artifacts: memory.artifacts,
+    blobs: memory.blobs,
+  },
+});
+
+/** The bytes of a stored media file, or `undefined` when it is gone. */
+export async function mediaBytes(id: string) {
+  const blob = await retrieveBlob(persistence, id);
+  return blob ? new Uint8Array(await blob.arrayBuffer()) : undefined;
+}
+
+/** The value of the first env var of `provider` that is set, or `null`. */
+export function envKey(provider: ByokProvider) {
+  const names = provider.env ?? [];
+  const name = names.find((env) => Boolean(process.env[env]));
+  return name ? (process.env[name] ?? null) : null;
+}
+
+/**
+ * The key for `provider`: the one you saved with `/connect <id>`, else its
+ * env var, else `null`. The CLI opens its sessions without a user, so every
+ * session uses the same saved keys.
+ */
+export async function providerKey(provider: ByokProvider, threadId: string) {
+  const saved = await credentials.get({ threadId }, provider.id);
+  if (saved?.type === "api_key") return saved.value;
+  return envKey(provider);
+}
diff --git a/examples/harness-cli-batman/src/tui.tsx b/examples/harness-cli-batman/src/tui.tsx
new file mode 100644
index 0000000000..b2c3378714
--- /dev/null
+++ b/examples/harness-cli-batman/src/tui.tsx
@@ -0,0 +1,1038 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import React, { useEffect, useLayoutEffect, useMemo, useReducer, useRef, useState } from "react";
+import {
+  Box,
+  Spacer,
+  Static,
+  Text,
+  measureElement,
+  render,
+  useApp,
+  useBoxMetrics,
+  useCursor,
+  useInput,
+  usePaste,
+  useStdout,
+  useWindowSize,
+} from "ink";
+import { useSelector } from "@tanstack/react-store";
+import { supportedReasoningLevels } from "@tanstack/ai-models";
+import { features, keyProviders, modelInfo, modelProviders, reasons } from "./harness";
+import { hasSession, listSessions } from "./sessions";
+import {
+  canTranscribe,
+  chooseMicrophone,
+  currentMicrophone,
+  isSilent,
+  listMicrophones,
+  startRecording,
+  transcribe,
+  withSpokenFiles,
+} from "./voice";
+import { useLineEditor } from "./screen/editor";
+import { Footer } from "./screen/footer";
+import { PROVIDER_KEYS, isOn, providerKeysIn } from "./screen/keys";
+import { mediaDir, openExternal, play, useSavedMedia } from "./screen/media";
+import { SCREEN_COMMANDS, TAKES_INPUT } from "./screen/commands";
+import { Menu } from "./screen/menu";
+import { pathSuggestions } from "./screen/paths";
+import { showSplash } from "./screen/splash";
+import { Message, settledCount } from "./screen/parts";
+import { Status } from "./screen/status";
+import { ACCENT, compact } from "./screen/theme";
+import type { ReactNode } from "react";
+import type { DOMElement, RenderOptions } from "ink";
+import type { ModelEntry } from "./harness";
+import type { Recording, VoiceClip } from "./voice";
+import type { Line } from "./screen/editor";
+import type { MenuItem } from "./screen/menu";
+import type { PathItem } from "./screen/paths";
+import type { VoiceState } from "./screen/status";
+import type {
+  SessionView,
+  SessionViewState,
+  ViewCommand,
+  ViewMessage,
+} from "@tanstack/ai-harness/view";
+
+const HELP = [
+  "🦇 Type / to see the commands. ↑ and ↓ go through the lines you sent.",
+  "🦇 Type @ to pick a file or a folder to send. Tab or Enter fills the path.",
+  "🦇 Voice: hold Ctrl+R and talk, then let go. Or tap Ctrl+R, talk, tap again.",
+  "  The words go into the input line. Fix them if needed, then press Enter.",
+  '  Name a file ("use cat dot png") or say "the last image" to send it too.',
+  "  The first recording listens on all microphones and keeps the loudest.",
+  "🦇 I am the night. You type. I work.",
+];
+
+/** The `/` commands that start with (or contain) what you typed after `/`. */
+function suggestionsFor(text: string, commands: ReadonlyArray<ViewCommand>) {
+  if (!/^\/\S*$/.test(text)) return [];
+  const query = text.slice(1).toLowerCase();
+  const own = new Set(SCREEN_COMMANDS.map((command) => command.name));
+  const all: Array<MenuItem & { takesInput: boolean }> = [
+    ...SCREEN_COMMANDS.map((command) => ({
+      id: command.name,
+      label: `/${command.name}`,
+      detail: command.description,
+      takesInput: TAKES_INPUT.has(command.name),
+    })),
+    // `connect:openai` and the like are in the `/connect` picker instead.
+    // `skill:<name>` (a skill whose name was taken) shows here.
+    ...commands
+      .filter(
+        (command) =>
+          (!command.name.includes(":") || command.name.startsWith("skill:")) &&
+          !own.has(command.name),
+      )
+      .map((command) => ({
+        id: command.name,
+        label: `/${command.name}`,
+        detail: command.description,
+        takesInput: command.input !== undefined,
+      })),
+  ];
+  return [
+    ...all.filter((item) => item.id.startsWith(query)),
+    ...all.filter((item) => !item.id.startsWith(query) && item.id.includes(query)),
+  ];
+}
+
+/** Does `/connect <id>` sign in with the browser, with no key to paste? */
+function signsIn(id: string) {
+  return keyProviders.some((provider) => provider.id === id && "signIn" in provider);
+}
+
+/** The rows of the `/connect` picker: the model providers, then the apps. */
+function connectItems(state: SessionViewState): Array<MenuItem> {
+  const keys = providerKeysIn(state.plugins[PROVIDER_KEYS]);
+  const providers = keys.map((key) => ({
+    id: key.id,
+    label: key.label,
+    current: key.state !== "missing",
+    detail:
+      key.state === "connected"
+        ? "connected"
+        : key.state === "env"
+          ? "key from the environment"
+          : signsIn(key.id)
+            ? "sign in with the browser, no key to paste"
+            : "opens the page to make a key, then you paste it",
+  }));
+  const apps = state.commands.flatMap((command) => {
+    const id = command.name.slice("connect:".length);
+    const isApp = command.name.startsWith("connect:") && !keys.some((key) => key.id === id);
+    return isApp ? [{ id, label: id, detail: command.description }] : [];
+  });
+  return [...providers, ...apps];
+}
+
+const modelCount = (count: number) => `${count} model${count === 1 ? "" : "s"}`;
+
+const currentModel = (state: SessionViewState) =>
+  String(state.config.find((item) => item.key === "model")?.value ?? "");
+
+/** The context size, the effort levels, and the price of a model. */
+function modelDetail(model: ModelEntry) {
+  const { contextWindow, cost } = model.record;
+  const levels = supportedReasoningLevels(model.record).filter((level) => level !== "off");
+  return [
+    `${compact(contextWindow)} context`,
+    levels.length === 0
+      ? "no effort setting"
+      : levels.length === 1
+        ? `effort ${levels[0]}`
+        : `effort ${levels[0]} to ${levels.at(-1)}`,
+    ...(cost.input > 0 ? [`$${cost.input}/$${cost.output} per 1M tokens`] : []),
+  ].join(", ");
+}
+
+/** The rows of a `/model` picker for these models. */
+function modelRows(models: ReadonlyArray<ModelEntry>, state: SessionViewState): Array<MenuItem> {
+  const current = currentModel(state);
+  return models.map((model) => ({
+    id: model.id,
+    label: model.id,
+    current: model.id === current,
+    detail: modelDetail(model),
+  }));
+}
+
+/** The first `/model` step: the providers, then the demo model if it is on. */
+function providerItems(state: SessionViewState): Array<MenuItem> {
+  const current = currentModel(state);
+  const keys = providerKeysIn(state.plugins[PROVIDER_KEYS]);
+  const rows = modelProviders.map((provider) => {
+    const missing = keys.find((key) => key.id === provider.id)?.state === "missing";
+    return {
+      id: provider.id,
+      label: provider.label,
+      current: modelInfo[current]?.provider === provider.id,
+      detail: `${modelCount(provider.models.length)}${missing ? `, needs /connect ${provider.id}` : ""}`,
+    };
+  });
+  const entry = state.config.find((item) => item.key === "model");
+  const demo = entry?.option.type === "select" && entry.option.options.includes("demo");
+  return demo
+    ? [
+        ...rows,
+        {
+          id: "demo",
+          label: "Demo",
+          current: current === "demo",
+          detail: "answers without a key",
+        },
+      ]
+    : rows;
+}
+
+/**
+ * The OpenRouter step between the provider and the model: the vendors. An
+ * alias vendor (`~anthropic`, its `latest` models) sorts after its vendor.
+ */
+function vendorItems(models: ReadonlyArray<ModelEntry>, state: SessionViewState): Array<MenuItem> {
+  const current = currentModel(state);
+  const counts = new Map<string, number>();
+  for (const model of models) {
+    const [vendor = ""] = model.id.split("/");
+    counts.set(vendor, (counts.get(vendor) ?? 0) + 1);
+  }
+  return [...counts]
+    .sort(
+      ([a], [b]) => a.replace(/^~/, "").localeCompare(b.replace(/^~/, "")) || a.localeCompare(b),
+    )
+    .map(([vendor, count]) => ({
+      id: vendor,
+      label: vendor,
+      current: current.startsWith(`${vendor}/`),
+      detail: modelCount(count),
+    }));
+}
+
+const EFFORT_DETAIL: Record<string, string> = {
+  default: "the model decides",
+  off: "no thinking",
+  minimal: "the least thinking",
+  low: "fast, few tokens",
+  medium: "balanced",
+  high: "thinks longer",
+  xhigh: "thinks very long",
+  max: "the most the model can think",
+};
+
+/** The rows of the `/effort` picker: the levels the current model has. */
+function effortItems(state: SessionViewState): Array<MenuItem> {
+  const effort = state.config.find((item) => item.key === "effort")?.value;
+  const record = modelInfo[currentModel(state)]?.record;
+  const levels = record ? supportedReasoningLevels(record) : [];
+  return ["default", ...levels].map((name) => ({
+    id: name,
+    label: name,
+    current: name === effort,
+    detail: EFFORT_DETAIL[name] ?? "",
+  }));
+}
+
+/** The rows of the `/resume` picker: the saved sessions, newest first. */
+async function sessionItems(state: SessionViewState): Promise<Array<MenuItem>> {
+  const sessions = await listSessions();
+  return sessions.map((session) => ({
+    id: session.id,
+    label: session.id,
+    current: session.id === state.threadId,
+    detail: `${new Date(session.updatedAt).toLocaleString(undefined, { dateStyle: "short", timeStyle: "short" })}  ${session.title.slice(0, 60)}`,
+  }));
+}
+
+// The session the user picked with /resume. The CLI opens it after the
+// screen closes.
+let nextSession: string | undefined;
+
+/** The session `/resume` picked, once. `undefined` when the user quit. */
+export function takeNextSession() {
+  const next = nextSession;
+  nextSession = undefined;
+  return next;
+}
+
+/** A list open over the input line, for example the `/connect` picker. */
+interface Picker {
+  title: string;
+  items: Array<MenuItem>;
+  pick: (item: MenuItem) => unknown;
+}
+
+/**
+ * The header, as wide as the screen: the name, the folder, and which
+ * features are on. It prints once, so the App prints the screen again when
+ * a feature turns on or off.
+ */
+function Header({ view, width }: { view: SessionView; width: number }) {
+  const keys = providerKeysIn(useSelector(view.store, (state) => state.plugins[PROVIDER_KEYS]));
+  const threadId = useSelector(view.store, (state) => state.threadId);
+  const marks = features.map((feature) => {
+    const on = isOn(feature, keys);
+    return {
+      name: feature.name,
+      on,
+      text: `${on ? "●" : "○"} ${feature.name}  `,
+    };
+  });
+  return (
+    <Box
+      width={width}
+      flexDirection="column"
+      borderStyle="single"
+      borderColor={ACCENT}
+      paddingX={1}
+    >
+      <Box>
+        <Box flexShrink={0}>
+          <Text color={ACCENT} bold>
+            🦇 BATMAN
+          </Text>
+          <Text dimColor>{`  ${threadId}`}</Text>
+        </Box>
+        <Spacer />
+        <Box flexShrink={1} minWidth={0}>
+          <Text dimColor wrap="truncate-start">
+            {process.cwd()}
+          </Text>
+        </Box>
+      </Box>
+      <Box>
+        {marks.map((mark) => (
+          <Text key={mark.name} color={mark.on ? ACCENT : "gray"}>
+            {mark.text}
+          </Text>
+        ))}
+      </Box>
+    </Box>
+  );
+}
+
+// Prompt in the input box. The bat emoji is two columns, then a space.
+const PROMPT = "🦇 ";
+const PROMPT_COLS = 3;
+
+function InputBox({
+  line,
+  voice,
+  hidden,
+}: {
+  line: Line;
+  voice: VoiceState;
+  /** The input is a secret (a key): show a dot for each character. */
+  hidden: boolean;
+}) {
+  const shown = hidden ? "•".repeat(line.text.length) : line.text;
+  // The terminal cursor shows where you type (see `inputCursor`).
+  return (
+    <Box
+      borderStyle="round"
+      borderColor={voice === "recording" ? "red" : voice === "idle" ? ACCENT : "gray"}
+      paddingX={1}
+    >
+      <Text color={ACCENT} bold>
+        {PROMPT}
+      </Text>
+      {shown === "" ? (
+        // The cursor goes before the hint, so the hint does not look typed.
+        <Text>
+          {" "}
+          <Text dimColor>
+            {hidden
+              ? " Paste the key. It stays hidden."
+              : " Speak, commissioner. / for commands, @file to attach, Ctrl+R to talk"}
+          </Text>
+        </Text>
+      ) : (
+        // At any character, so `inputCursor` knows the row of each one.
+        <Text wrap="hard">{shown}</Text>
+      )}
+    </Box>
+  );
+}
+
+/**
+ * Where the terminal cursor goes in the input box, which is `width` wide
+ * and starts at `top`: after the border, the padding, and the prompt, at
+ * the row and the column of the line's cursor.
+ */
+function inputCursor(line: Line, width: number, top: number) {
+  const before = 2 + PROMPT_COLS;
+  const textWidth = Math.max(1, width - before - 2);
+  return {
+    x: before + (line.cursor % textWidth),
+    y: top + 1 + Math.floor(line.cursor / textWidth),
+  };
+}
+
+// A key held down repeats. Repeats closer than this are one press.
+const REPEAT_GAP = 1100;
+// After the last repeat, the key is up when no repeat comes for this long.
+const RELEASE_WAIT = 450;
+
+type Row = { id: "header" } | ViewMessage;
+
+/** Reports its height once, when Ink prints it (Static prints a row once). */
+function Measured({
+  id,
+  onHeight,
+  children,
+}: {
+  id: string;
+  onHeight: (id: string, height: number) => void;
+  children: ReactNode;
+}) {
+  const ref = useRef<DOMElement>(null);
+  // Ink lays out the frame before layout effects run, so the height is there.
+  useLayoutEffect(() => {
+    if (ref.current) onHeight(id, measureElement(ref.current).height);
+  }, []);
+  return (
+    <Box ref={ref} flexDirection="column">
+      {children}
+    </Box>
+  );
+}
+
+/** One printed row: the header, or a message that no longer changes. */
+function PrintedRow({
+  view,
+  row,
+  saved,
+  width,
+}: {
+  view: SessionView;
+  row: Row;
+  saved: ReturnType<typeof useSavedMedia>["saved"];
+  width: number;
+}) {
+  return "role" in row ? (
+    <Message message={row} saved={saved} width={width} />
+  ) : (
+    <Header view={view} width={width} />
+  );
+}
+
+function App({ view }: { view: SessionView }) {
+  const { exit } = useApp();
+  const messages = useSelector(view.store, (state) => state.messages);
+  const running = useSelector(view.store, (state) => state.status === "running");
+  const { saved, saving } = useSavedMedia(view, messages);
+  // The input line. A line typed while a question asks for a key stays hidden
+  // until it is sent or deleted, also when the question ends first, so a key
+  // never shows or goes out as a message.
+  const editor = useLineEditor();
+  const secretAsked = useSelector(view.store, (state) => state.questions.at(0)?.secret === true);
+  const asksSecret = () => view.store.get().questions.at(0)?.secret === true;
+  const commands = useSelector(view.store, (state) => state.commands);
+  const waiting = useSelector(
+    view.store,
+    (state) => state.questions.length > 0 || state.approvals.length > 0,
+  );
+  const [picker, setPicker] = useState<Picker | undefined>(undefined);
+  const [selected, setSelected] = useState(0);
+  // A line from the history keeps the arrows for the history.
+  const blocked = Boolean(picker || waiting || editor.line.hidden || editor.browsing);
+  const commandItems = blocked ? [] : suggestionsFor(editor.line.text, commands);
+  // The files for an `@path`, read again only when the line changes.
+  const { text: lineText, cursor: lineCursor } = editor.line;
+  const paths = useMemo(
+    () =>
+      blocked || commandItems.length > 0
+        ? undefined
+        : pathSuggestions({
+            text: lineText,
+            cursor: lineCursor,
+            hidden: false,
+          }),
+    [blocked, commandItems.length, lineText, lineCursor],
+  );
+  const suggestions: Array<(MenuItem & { takesInput: boolean }) | PathItem> =
+    commandItems.length > 0 ? commandItems : (paths?.items ?? []);
+  const [suggested, setSuggested] = useState(0);
+  useEffect(() => setSuggested(0), [editor.line.text]);
+
+  // Messages that no longer change print once, above the live area. The
+  // count only grows: a printed message is never printed again.
+  const printed = useRef(0);
+  printed.current = Math.max(printed.current, settledCount(messages, saving, running));
+  const rows: Array<Row> = [{ id: "header" }, ...messages.slice(0, printed.current)];
+
+  // The input sits at the bottom of the screen: until the printed rows fill
+  // the screen, empty space above the live area fills the rest. Each row
+  // measures itself when it prints. Ink redraws the whole screen for a frame
+  // as tall as the screen, so the frame stays one line shorter.
+  // ponytail: the heights are from the width at print time. A resize makes
+  // the space a little off until the screen is full.
+  const { columns, rows: screenRows } = useWindowSize();
+  const heights = useRef(new Map<string, number>());
+  const [, remeasure] = useReducer((count: number) => count + 1, 0);
+  const onHeight = (id: string, height: number) => {
+    heights.current.set(id, height);
+    remeasure();
+  };
+  const printedHeight = rows.reduce((sum, row) => sum + (heights.current.get(row.id) ?? 0), 0);
+  const live = useRef<DOMElement>(null);
+  const { height: liveHeight } = useBoxMetrics(live);
+  const space = Math.max(0, screenRows - 1 - printedHeight - liveHeight);
+
+  // The terminal cursor sits in the input box, not under the screen. The
+  // box is in the live area, which starts after the empty space.
+  const inputBox = useRef<DOMElement>(null);
+  const input = useBoxMetrics(inputBox);
+  const { setCursorPosition } = useCursor();
+  setCursorPosition(
+    input.hasMeasured ? inputCursor(editor.line, input.width, space + input.top) : undefined,
+  );
+
+  // The header shows which features are on, but printed rows never change.
+  // So when a feature turns on or off (a /connect), clear the screen and
+  // print the header and the conversation again.
+  const { stdout } = useStdout();
+  const featureMarks = useSelector(view.store, (state) => {
+    const keys = providerKeysIn(state.plugins[PROVIDER_KEYS]);
+    return features.map((feature) => (isOn(feature, keys) ? 1 : 0)).join("");
+  });
+  const shownMarks = useRef(featureMarks);
+  const [printRound, setPrintRound] = useState(0);
+  useEffect(() => {
+    if (featureMarks === shownMarks.current) return;
+    shownMarks.current = featureMarks;
+    if (stdout.isTTY) stdout.write("\x1b[2J\x1b[3J\x1b[H");
+    setPrintRound((round) => round + 1);
+  }, [featureMarks]);
+
+  const [voice, setVoiceState] = useState<VoiceState>("idle");
+  // The phase in a ref too: key events come faster than React renders, and a
+  // second Ctrl+R must see "starting" at once, or it starts a second recorder.
+  const phase = useRef<VoiceState>("idle");
+  const setVoice = (next: VoiceState) => {
+    phase.current = next;
+    setVoiceState(next);
+  };
+  const recording = useRef<Recording | undefined>(undefined);
+  const [recorder, setRecorder] = useState<Recording | undefined>(undefined);
+  const talk = useRef({
+    last: 0,
+    holding: false,
+    stopWanted: false,
+    cancelWanted: false,
+  });
+  const release = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const voiceAbort = useRef<AbortController | undefined>(undefined);
+
+  const fail = (error: unknown) =>
+    view.notice(error instanceof Error ? error.message : String(error));
+  const failVoice = (error: unknown) =>
+    view.notice(`Voice: ${error instanceof Error ? error.message : String(error)}`);
+
+  const cancelVoice = () => {
+    voiceAbort.current?.abort();
+    voiceAbort.current = undefined;
+    clearTimeout(release.current);
+    talk.current.cancelWanted = true;
+    const current = recording.current;
+    if (current) {
+      recording.current = undefined;
+      setRecorder(undefined);
+      current.cancel();
+    }
+    setVoice("idle");
+  };
+
+  /**
+   * A voice message: transcribe it, and put the words in the input line, with
+   * an `@path` for each file it names. The user fixes the line if needed,
+   * then presses Enter to send it.
+   */
+  const hear = async (audio: Uint8Array, name: string, clip?: VoiceClip) => {
+    voiceAbort.current?.abort();
+    const abort = new AbortController();
+    voiceAbort.current = abort;
+    setVoice("transcribing");
+    try {
+      if (clip?.pickedMicrophone)
+        view.notice(`Voice: using "${clip.microphone}" from now on. /mic changes it.`);
+      // Transcription models make up words for silence, so it is not sent.
+      if (clip && isSilent(clip))
+        return view.notice(
+          `Voice: only silence from "${clip.microphone}". Hold Ctrl+R while you talk, or pick another microphone with /mic.`,
+        );
+      const text = await transcribe(audio, {
+        name,
+        threadId: view.store.get().threadId,
+        abortSignal: abort.signal,
+      });
+      if (abort.signal.aborted) return;
+      // Drop the spinner before the file walk, so a big folder cannot
+      // leave the transcribe line on the screen.
+      setVoice("idle");
+      if (text === "") return view.notice("Voice: no speech heard.");
+      const recent = saved.flatMap((item) =>
+        item.path ? [{ kind: item.kind, path: item.path }] : [],
+      );
+      const message = await withSpokenFiles(text, [process.cwd(), mediaDir], recent);
+      if (abort.signal.aborted) return;
+      // A key question keeps its line for the key only.
+      if (asksSecret()) return view.notice("Voice: answer the key question first.");
+      // After what the user typed already, so nothing they typed is lost.
+      const typed = editor.line.text.trimEnd();
+      editor.set(typed === "" ? message.text : `${typed} ${message.text}`);
+    } catch (error) {
+      if (abort.signal.aborted) return;
+      if (error instanceof Error && error.name === "TimeoutError") {
+        return view.notice("Voice: transcription stopped after 45 seconds. Try a shorter clip.");
+      }
+      failVoice(error);
+    } finally {
+      if (voiceAbort.current === abort) voiceAbort.current = undefined;
+      setVoice("idle");
+    }
+  };
+
+  const stopTalking = async () => {
+    clearTimeout(release.current);
+    const current = recording.current;
+    if (!current) {
+      // Still opening: stop as soon as it is open.
+      talk.current.stopWanted = true;
+      return;
+    }
+    recording.current = undefined;
+    setRecorder(undefined);
+    await current.stop().then(
+      (clip) => {
+        if (talk.current.cancelWanted) {
+          setVoice("idle");
+          return;
+        }
+        return hear(clip.audio, "voice.wav", clip);
+      },
+      (error) => {
+        setVoice("idle");
+        failVoice(error);
+      },
+    );
+  };
+
+  const startTalking = async () => {
+    talk.current = {
+      last: Date.now(),
+      holding: false,
+      stopWanted: false,
+      cancelWanted: false,
+    };
+    // "starting" before the key check, so a repeated Ctrl+R starts nothing.
+    setVoice("starting");
+    try {
+      if (!(await canTranscribe(view.store.get().threadId))) {
+        setVoice("idle");
+        return view.notice("Voice: run /connect and pick OpenAI or xAI to turn voice on.");
+      }
+      const started = await startRecording();
+      if (talk.current.cancelWanted) {
+        started.cancel();
+        setVoice("idle");
+        return;
+      }
+      recording.current = started;
+      setRecorder(started);
+      setVoice("recording");
+      if (talk.current.stopWanted) await stopTalking();
+    } catch (error) {
+      setVoice("idle");
+      failVoice(error);
+    }
+  };
+
+  /**
+   * Ctrl+R. A terminal sends no key-up, only repeats while a key is held. So
+   * repeats mean "held": the recording stops when they stop. A single press
+   * starts, and the next single press stops.
+   */
+  const onTalkKey = () => {
+    const now = Date.now();
+    const gap = now - talk.current.last;
+    talk.current.last = now;
+    if (phase.current === "transcribing") {
+      cancelVoice();
+      return;
+    }
+    if (phase.current === "idle") return void startTalking();
+    if (gap < REPEAT_GAP) {
+      talk.current.holding = true;
+      clearTimeout(release.current);
+      release.current = setTimeout(() => void stopTalking(), RELEASE_WAIT);
+      return;
+    }
+    if (!talk.current.holding) void stopTalking();
+  };
+
+  /** The saved media file `/open 2` or `/play` names. */
+  const pick = (arg: string | undefined) => {
+    const ready = saved.filter((item) => item.path !== undefined);
+    const item = arg ? ready.find((entry) => entry.number === Number(arg)) : ready.at(-1);
+    if (!item?.path) {
+      view.notice(arg ? `No saved media file ${arg}.` : "No media file yet.");
+      return undefined;
+    }
+    return { ...item, path: item.path };
+  };
+
+  const openPicker = (next: Picker) => {
+    if (next.items.length === 0) return view.notice(`${next.title}: nothing to pick.`);
+    setSelected(
+      Math.max(
+        0,
+        next.items.findIndex((item) => item.current),
+      ),
+    );
+    setPicker(next);
+  };
+
+  const pickMicrophone = async () => {
+    const names = await listMicrophones();
+    const current = await currentMicrophone();
+    if (names.length === 0)
+      return view.notice(`Recording from the default input${current ? ` (${current})` : ""}.`);
+    openPicker({
+      title: "Record from which microphone?",
+      items: names.map((name) => ({
+        id: name,
+        label: name,
+        current: name === current,
+      })),
+      pick: async (item) => {
+        await chooseMicrophone(item.id);
+        view.notice(`Voice: recording from "${item.id}".`);
+      },
+    });
+  };
+
+  /** Pick a model of the provider `id`. OpenRouter asks for the vendor first. */
+  const pickModelOf = (id: string) => {
+    if (id === "demo") return view.command("model", "demo");
+    const provider = modelProviders.find((entry) => entry.id === id);
+    if (!provider) return;
+    const state = view.store.get();
+    const pickModel = (title: string, models: ReadonlyArray<ModelEntry>) =>
+      openPicker({
+        title,
+        items: modelRows(models, state),
+        pick: (item) => view.command("model", item.id),
+      });
+    if (provider.id !== "openrouter")
+      return pickModel(`${provider.label}: pick the model`, provider.models);
+    openPicker({
+      title: "OpenRouter: pick the vendor",
+      items: vendorItems(provider.models, state),
+      pick: (vendor) =>
+        pickModel(
+          `OpenRouter: pick the ${vendor.id} model`,
+          provider.models.filter((model) => model.id.startsWith(`${vendor.id}/`)),
+        ),
+    });
+  };
+
+  /** Close the screen, and the CLI opens the saved session `id`. */
+  const resume = async (id: string) => {
+    if (id === view.store.get().threadId) return view.notice("You are in this session.");
+    if (!(await hasSession(id))) return view.notice(`No saved session ${id}. /resume lists them.`);
+    nextSession = id;
+    exit();
+  };
+
+  /** Enter: answer an approval or a question, run a screen command, or send. */
+  const submit = async (line: Line) => {
+    const text = line.text.trim();
+    const state = view.store.get();
+    const [question] = state.questions;
+    if (question?.secret) {
+      // The key goes as it is. The screen does not show it anywhere.
+      await question.answer(text);
+      return;
+    }
+    if (line.hidden) {
+      // The question ended before Enter: drop the key, do not send it.
+      view.notice("The key question ended, so the key was not used.");
+      return;
+    }
+    if (state.approvals.length > 0) {
+      if (/^y(es)?$/i.test(text)) view.approveAll();
+      else view.rejectAll();
+      return;
+    }
+    if (question) {
+      const answer = /^y(es)?$/i.test(text) ? true : /^no?$/i.test(text) ? false : text;
+      await question.answer(answer);
+      return;
+    }
+    const [command, ...rest] = text.split(" ");
+    const arg = rest.join(" ").trim() || undefined;
+    switch (command) {
+      case "/exit":
+        return exit();
+      case "/help": {
+        const keys = providerKeysIn(state.plugins[PROVIDER_KEYS]);
+        const off = features
+          .filter((feature) => !isOn(feature, keys))
+          .map((feature) => `  ${feature.name} is off: it needs ${feature.needs}.`);
+        const list = suggestionsFor("/", state.commands).map(
+          (item) => `${item.label.padEnd(14)}${item.detail ?? ""}`,
+        );
+        return view.notice([...HELP, ...off, ...list].join("\n"));
+      }
+      case "/connect":
+        if (arg) return view.command(`connect:${arg}`);
+        return openPicker({
+          title: "Connect to what?",
+          items: connectItems(state),
+          pick: (item) => view.command(`connect:${item.id}`),
+        });
+      case "/disconnect": {
+        if (arg) return view.command(`disconnect:${arg}`);
+        // A key from the environment cannot be removed here, so it is not listed.
+        const keys = providerKeysIn(state.plugins[PROVIDER_KEYS]);
+        return openPicker({
+          title: "Remove which key or sign-in?",
+          items: connectItems(state).filter(
+            (item) => !keys.some((key) => key.id === item.id && key.state !== "connected"),
+          ),
+          pick: (item) => view.command(`disconnect:${item.id}`),
+        });
+      }
+      case "/model":
+        if (arg) break;
+        return openPicker({
+          title: "Pick the provider",
+          items: providerItems(state),
+          pick: (item) => pickModelOf(item.id),
+        });
+      case "/effort":
+        if (arg) break;
+        if (!reasons(currentModel(state)))
+          return view.notice(
+            `${currentModel(state)} has no effort setting. Pick another model with /model.`,
+          );
+        return openPicker({
+          title: "How hard should the model think?",
+          items: effortItems(state),
+          pick: (item) => view.command("effort", item.id),
+        });
+      case "/resume":
+        if (arg) return resume(arg);
+        return openPicker({
+          title: "Continue which session?",
+          items: await sessionItems(state),
+          pick: (item) => resume(item.id),
+        });
+      case "/mic": {
+        if (!arg) return pickMicrophone().catch(failVoice);
+        const names = await listMicrophones().catch(() => []);
+        const chosen = names[Number(arg) - 1];
+        if (!chosen) return view.notice(`No microphone ${arg}. /mic lists them.`);
+        await chooseMicrophone(chosen);
+        return view.notice(`Voice: recording from "${chosen}".`);
+      }
+      case "/voice": {
+        if (!arg) return view.notice("Give an audio file: /voice note.m4a");
+        const path = arg.replace(/^@|^"|"$/g, "");
+        const audio = await readFile(path).catch(failVoice);
+        if (audio) await hear(new Uint8Array(audio), basename(path));
+        return;
+      }
+      case "/open":
+      case "/play": {
+        const item = pick(arg);
+        if (!item) return;
+        if (command === "/play" && item.kind !== "image") play(item);
+        else openExternal(item.path);
+        return;
+      }
+    }
+    await view.send(text);
+  };
+
+  /** Send a line and keep it for the up arrow, unless it is a key or an answer. */
+  const send = (line: Line) => {
+    const state = view.store.get();
+    const isAnswer = state.questions.length > 0 || state.approvals.length > 0;
+    if (!line.hidden && !isAnswer) editor.remember(line.text);
+    editor.clear();
+    submit(line).catch(fail);
+  };
+
+  usePaste((text) => editor.insert(text, asksSecret()));
+
+  useInput((character, key) => {
+    if (key.ctrl && (character === "r" || character === "R")) return onTalkKey();
+    if (picker) {
+      const count = picker.items.length;
+      const number = Number(character);
+      const chosen = key.return
+        ? picker.items[selected]
+        : Number.isInteger(number) && number >= 1
+          ? picker.items[number - 1]
+          : undefined;
+      if (key.escape || chosen) setPicker(undefined);
+      if (chosen) Promise.resolve(picker.pick(chosen)).catch(fail);
+      if (key.upArrow) setSelected((index) => (index - 1 + count) % count);
+      if (key.downArrow) setSelected((index) => (index + 1) % count);
+      return;
+    }
+    if (key.escape) {
+      if (
+        phase.current === "starting" ||
+        phase.current === "recording" ||
+        phase.current === "transcribing"
+      ) {
+        cancelVoice();
+        return;
+      }
+      if (view.store.get().status === "running") void view.cancel();
+      else editor.clear();
+      return;
+    }
+    const suggestion = suggestions[Math.min(suggested, suggestions.length - 1)];
+    if (suggestion) {
+      const count = suggestions.length;
+      if (key.upArrow) return setSuggested((index) => (index - 1 + count) % count);
+      if (key.downArrow) return setSuggested((index) => (index + 1) % count);
+      if ("fill" in suggestion) {
+        // Put the path in place of the typed `@` token.
+        if (key.tab || key.return) {
+          const { text, cursor } = editor.line;
+          const filled = text.slice(0, paths?.start ?? cursor) + suggestion.fill;
+          return editor.set(filled + text.slice(cursor), filled.length);
+        }
+      } else {
+        if (key.tab) return editor.set(`/${suggestion.id} `);
+        if (key.return) {
+          if (suggestion.takesInput) return editor.set(`/${suggestion.id} `);
+          return send({ text: `/${suggestion.id}`, cursor: 0, hidden: false });
+        }
+      }
+    }
+    if (key.upArrow) return editor.older();
+    if (key.downArrow) return editor.newer();
+    if (key.leftArrow) return editor.move(-1);
+    if (key.rightArrow) return editor.move(1);
+    if (key.home) return editor.move("start");
+    if (key.end) return editor.move("end");
+    if (key.return) {
+      if (phase.current === "recording" || phase.current === "starting") return void stopTalking();
+      return send(editor.line);
+    }
+    // Most terminals send Backspace as the delete key.
+    if (key.backspace || key.delete) return editor.backspace();
+    if (!key.ctrl && !key.meta && !key.tab && character) editor.insert(character, asksSecret());
+  });
+
+  return (
+    <Box flexDirection="column">
+      <Static key={printRound} items={rows}>
+        {(row) => (
+          <Measured key={row.id} id={row.id} onHeight={onHeight}>
+            <PrintedRow view={view} row={row} saved={saved} width={columns} />
+          </Measured>
+        )}
+      </Static>
+      {space > 0 ? <Box height={space} /> : null}
+      <Box ref={live} flexDirection="column">
+        {messages.slice(printed.current).map((message) => (
+          <Message key={message.id} message={message} saved={saved} width={columns} />
+        ))}
+        <Status view={view} voice={voice} recording={recorder} />
+        {/* A column, so the input box keeps the full width. */}
+        <Box ref={inputBox} flexDirection="column">
+          <InputBox
+            line={editor.line}
+            voice={voice}
+            hidden={secretAsked || (editor.line.hidden && editor.line.text !== "")}
+          />
+        </Box>
+        {picker ? (
+          <Menu
+            title={picker.title}
+            items={picker.items}
+            selected={selected}
+            hint="↑↓ move   Enter or a number picks   Esc closes"
+          />
+        ) : suggestions.length > 0 ? (
+          <Menu
+            items={suggestions}
+            selected={Math.min(suggested, suggestions.length - 1)}
+            hint={
+              commandItems.length > 0
+                ? "↑↓ move   Tab fills   Enter runs"
+                : "↑↓ move   Tab or Enter fills"
+            }
+          />
+        ) : null}
+        <Footer view={view} />
+      </Box>
+    </Box>
+  );
+}
+
+// The boot splash shows once in a process.
+let splashShown = false;
+
+/**
+ * The Ink screen for `runCli({ ui })`. It clears the terminal, opens sign-in
+ * links in the browser, records voice messages, saves the media the agents
+ * make into `./<harness-name>-media`, and resolves when the user types /exit
+ * or presses Ctrl+C. `io` replaces the terminal, for a test.
+ */
+export async function runTui(view: SessionView, io: RenderOptions = {}) {
+  view.on("signIn", (signIn) => {
+    if (signIn.url) openExternal(signIn.url);
+  });
+  const keys = providerKeysIn(view.store.get().plugins[PROVIDER_KEYS]);
+  if (keys.every((key) => key.state === "missing"))
+    view.notice("🦇 The cave is dark. Type /connect and pick OpenRouter to light the signal.");
+  // Start on a clean terminal: clear the screen and the scrollback. The
+  // splash shows once, at the first start, not again after a /resume.
+  const clear = () => {
+    if (!io.stdout && process.stdout.isTTY) process.stdout.write("\x1b[2J\x1b[3J\x1b[H");
+  };
+  if (!splashShown && (io.stdout ?? process.stdout).isTTY) {
+    splashShown = true;
+    clear();
+    await showSplash(io);
+  }
+  clear();
+  const app = render(<App view={view} />, io);
+  // ponytail: the SDK logs its warnings and errors on the console (the
+  // message, then its details with console.dir), and the code highlighter
+  // warns about languages it does not know. Ink prints console output above
+  // the screen, and the screen shows the errors itself, so it drops them.
+  // This wraps the console after render(), because render() replaces it.
+  const before = { warn: console.warn, error: console.error, dir: console.dir };
+  let dropDetails = false;
+  const quiet =
+    (log: (...args: Array<unknown>) => void) =>
+    (...args: Array<unknown>) => {
+      const text = typeof args[0] === "string" ? args[0] : "";
+      dropDetails = /\[tanstack-ai:(warn|errors)\]|Could not find the language/.test(text);
+      if (!dropDetails) log(...args);
+    };
+  const quietWarn = quiet(before.warn);
+  console.warn = quietWarn;
+  console.error = quiet(before.error);
+  console.dir = (...args: Parameters<typeof console.dir>) => {
+    if (dropDetails) dropDetails = false;
+    else before.dir(...args);
+  };
+  try {
+    await app.waitUntilExit();
+  } finally {
+    // Ink puts the first console back when it stops. Without its console
+    // (`patchConsole: false`), the screen puts it back itself.
+    if (console.warn === quietWarn) Object.assign(console, before);
+  }
+}
diff --git a/examples/harness-cli-batman/src/voice.ts b/examples/harness-cli-batman/src/voice.ts
new file mode 100644
index 0000000000..b129d71231
--- /dev/null
+++ b/examples/harness-cli-batman/src/voice.ts
@@ -0,0 +1,448 @@
+import { execFile, spawn } from "node:child_process";
+import type { ChildProcess } from "node:child_process";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join, relative } from "node:path";
+import { generateTranscription } from "@tanstack/ai";
+import { createGrokTranscription } from "@tanstack/ai-grok";
+import { grokByok } from "@tanstack/ai-grok/byok";
+import { createOpenaiTranscription } from "@tanstack/ai-openai";
+import { openaiByok } from "@tanstack/ai-openai/byok";
+import { SAVE_DIR } from "./credentials";
+import { providerKey } from "./store";
+
+// Voice input for the terminal: ffmpeg records the microphone, a
+// transcription model turns it into text, and spoken file names become
+// `@path` attachments that the CLI sends with the message.
+
+const ffmpeg = process.env.FFMPEG_PATH || "ffmpeg";
+const RATE = 16000;
+const TRANSCRIBE_MS = 45_000;
+const MAX_SPOKEN_FILES = 400;
+// The microphone you picked, kept next to the sign-ins.
+const saved = join(SAVE_DIR, "voice.json");
+
+/**
+ * Can the session of `threadId` turn speech into text? It needs an OpenAI or
+ * an xAI key: saved with `/connect`, or in the env.
+ */
+export async function canTranscribe(threadId: string) {
+  const keys = await Promise.all([
+    providerKey(openaiByok, threadId),
+    providerKey(grokByok, threadId),
+  ]);
+  return keys.some((key) => key !== null);
+}
+
+/**
+ * The audio inputs ffmpeg can record on Windows (DirectShow). Other systems
+ * record the default input, so this is empty there.
+ */
+export function listMicrophones() {
+  if (process.platform !== "win32") return Promise.resolve<Array<string>>([]);
+  return new Promise<Array<string>>((resolve, reject) => {
+    execFile(
+      ffmpeg,
+      ["-hide_banner", "-list_devices", "true", "-f", "dshow", "-i", "dummy"],
+      (error, _stdout, stderr) => {
+        if (error?.code === "ENOENT")
+          return reject(new Error("Voice needs ffmpeg on the PATH (or FFMPEG_PATH)."));
+        resolve([...stderr.matchAll(/"([^"]+)" \(audio\)/g)].map((match) => match[1] ?? ""));
+      },
+    );
+  });
+}
+
+// The microphone `/mic <n>` picked, or the first recording found.
+let picked: string | undefined;
+
+/** Record from this microphone from now on, also after a restart. */
+export async function chooseMicrophone(name: string) {
+  picked = name;
+  await mkdir(dirname(saved), { recursive: true });
+  await writeFile(saved, JSON.stringify({ microphone: name }, null, 2));
+}
+
+/** The microphone to record from, when one is set: VOICE_DEVICE, then yours. */
+export async function currentMicrophone() {
+  if (process.env.VOICE_DEVICE) return process.env.VOICE_DEVICE;
+  if (picked) return picked;
+  try {
+    const parsed: unknown = JSON.parse(await readFile(saved, "utf8"));
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      "microphone" in parsed &&
+      typeof parsed.microphone === "string"
+    )
+      picked = parsed.microphone;
+  } catch {
+    // No saved microphone yet.
+  }
+  return picked;
+}
+
+/**
+ * The inputs a first recording listens on: every microphone, without capture
+ * cards and virtual inputs (they are often silent).
+ */
+async function candidateMicrophones() {
+  const names = await listMicrophones();
+  const real = names.filter((name) => !/hdmi|cam link|virtual|stereo mix|line in/i.test(name));
+  return real.length > 0 ? real : names;
+}
+
+/** The ffmpeg input arguments for one microphone. */
+function microphoneInput(name: string | undefined) {
+  if (process.platform === "win32") return ["-f", "dshow", "-i", `audio=${name}`];
+  if (process.platform === "darwin") return ["-f", "avfoundation", "-i", `:${name ?? "0"}`];
+  return ["-f", "pulse", "-i", name ?? "default"];
+}
+
+/** The root mean square of 16-bit samples, without a constant offset. */
+function rms(samples: Int16Array) {
+  if (samples.length === 0) return 0;
+  let sum = 0;
+  let squares = 0;
+  for (const sample of samples) {
+    sum += sample;
+    squares += sample * sample;
+  }
+  const mean = sum / samples.length;
+  return Math.sqrt(Math.max(0, squares / samples.length - mean * mean));
+}
+
+function samplesOf(pcm: Uint8Array) {
+  return new Int16Array(pcm.buffer.slice(pcm.byteOffset, pcm.byteOffset + (pcm.byteLength & ~1)));
+}
+
+/**
+ * How much speech a clip holds, from its 100 ms windows:
+ * - `peak`: the loudness of the loud part (90th percentile), 0 to 32768.
+ * - `floor`: the loudness of the quiet part (20th percentile), the noise.
+ * Speech makes the peak much louder than the floor. Steady noise and a few
+ * clicks do not, so they read as silence.
+ */
+export function speechStats(pcm: Uint8Array) {
+  const samples = samplesOf(pcm);
+  const size = RATE / 10;
+  const windows: Array<number> = [];
+  for (let start = 0; start + size <= samples.length; start += size)
+    windows.push(rms(samples.subarray(start, start + size)));
+  windows.sort((a, b) => a - b);
+  const at = (share: number) =>
+    windows[Math.min(windows.length - 1, Math.floor(windows.length * share))] ?? 0;
+  return { peak: at(0.9), floor: at(0.2) };
+}
+
+/** How clearly a clip holds speech: the peak over the noise floor. */
+function speechScore(stats: { peak: number; floor: number }) {
+  return stats.peak / Math.max(stats.floor, 30);
+}
+
+/** A 16 kHz mono 16-bit WAV file for raw samples. */
+function wavFile(pcm: Uint8Array) {
+  const header = new DataView(new ArrayBuffer(44));
+  const text = (offset: number, value: string) => {
+    for (let index = 0; index < 4; index++)
+      header.setUint8(offset + index, value.charCodeAt(index));
+  };
+  text(0, "RIFF");
+  header.setUint32(4, 36 + pcm.byteLength, true);
+  text(8, "WAVE");
+  text(12, "fmt ");
+  header.setUint32(16, 16, true);
+  header.setUint16(20, 1, true);
+  header.setUint16(22, 1, true);
+  header.setUint32(24, RATE, true);
+  header.setUint32(28, RATE * 2, true);
+  header.setUint16(32, 2, true);
+  header.setUint16(34, 16, true);
+  text(36, "data");
+  header.setUint32(40, pcm.byteLength, true);
+  const file = new Uint8Array(44 + pcm.byteLength);
+  file.set(new Uint8Array(header.buffer));
+  file.set(pcm, 44);
+  return file;
+}
+
+// Every ffmpeg recorder that runs. They are stopped when the app exits, so no
+// recorder keeps the microphone open after it.
+const recorders = new Set<ChildProcess>();
+process.once("exit", () => {
+  for (const child of recorders) child.kill();
+});
+
+/** One ffmpeg process that streams raw samples from one microphone. */
+function capture(name: string | undefined) {
+  const child = spawn(
+    ffmpeg,
+    [
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      ...microphoneInput(name),
+      "-ac",
+      "1",
+      "-ar",
+      String(RATE),
+      "-f",
+      "s16le",
+      "pipe:1",
+    ],
+    { stdio: ["pipe", "pipe", "pipe"] },
+  );
+  recorders.add(child);
+  child.on("exit", () => recorders.delete(child));
+  const chunks: Array<Buffer> = [];
+  let level = 0;
+  let errors = "";
+  child.stdout.on("data", (chunk: Buffer) => {
+    chunks.push(chunk);
+    level = rms(samplesOf(chunk));
+  });
+  child.stderr.on("data", (chunk: Buffer) => (errors += chunk.toString()));
+  const exited = new Promise<void>((resolve, reject) => {
+    child.on("error", (error: NodeJS.ErrnoException) =>
+      reject(
+        error.code === "ENOENT"
+          ? new Error("Voice needs ffmpeg on the PATH (or FFMPEG_PATH).")
+          : error,
+      ),
+    );
+    child.on("exit", () => resolve());
+  });
+  let running = true;
+  void exited.then(
+    () => (running = false),
+    () => (running = false),
+  );
+  return {
+    name: name ?? "the default input",
+    exited,
+    isRunning: () => running,
+    errors: () => errors.trim(),
+    level: () => level,
+    pcm: () => new Uint8Array(Buffer.concat(chunks)),
+    stop: async () => {
+      // `q` makes ffmpeg stop cleanly. Kill it if it does not. Do not wait
+      // forever: on Windows, dshow sometimes ignores stdin and kill.
+      try {
+        child.stdin.end("q");
+      } catch {
+        // stdin can already be closed when ffmpeg exited.
+      }
+      const timer = setTimeout(() => child.kill(), 1500);
+      await Promise.race([
+        exited.catch(() => {}),
+        new Promise<void>((resolve) => setTimeout(resolve, 2500)),
+      ]);
+      clearTimeout(timer);
+    },
+    kill: () => child.kill(),
+  };
+}
+
+/** A voice message from the microphone. */
+export interface VoiceClip {
+  /** 16 kHz mono WAV. */
+  audio: Uint8Array;
+  /** The loud part and the noise floor, from 0 to 32768. */
+  peak: number;
+  floor: number;
+  microphone: string;
+  /** True when this recording picked the microphone (the clearest one). */
+  pickedMicrophone: boolean;
+}
+
+export interface Recording {
+  /** The microphone, or "all microphones" while the first recording picks one. */
+  microphone: string;
+  /** The loudness right now, from 0 to 32768, for a level meter. */
+  level: () => number;
+  /** Stop, and give the voice message. */
+  stop: () => Promise<VoiceClip>;
+  /** Stop and drop the audio. */
+  cancel: () => void;
+}
+
+/**
+ * Start recording until `stop` or `cancel`. With no microphone set yet, it
+ * listens on every microphone, keeps the one that heard speech the clearest,
+ * and remembers it.
+ */
+export async function startRecording(): Promise<Recording> {
+  const chosen = await currentMicrophone();
+  const names =
+    chosen !== undefined || process.platform !== "win32" ? [chosen] : await candidateMicrophones();
+  if (names.length === 0) throw new Error("No microphone found. Set VOICE_DEVICE to its name.");
+  const captures = names.map(capture);
+  // ffmpeg stops at once when a device does not open.
+  await new Promise((resolve) => setTimeout(resolve, 400));
+  const live = captures.filter((item) => item.isRunning());
+  if (live.length === 0) {
+    const errors = captures.map((item) => item.errors()).filter(Boolean);
+    throw new Error(`The microphone did not open. ${errors.join(" ")}`.trim());
+  }
+  const picking = chosen === undefined && live.length > 1;
+  return {
+    microphone: picking ? "all microphones" : (live[0]?.name ?? ""),
+    level: () => Math.max(...live.map((item) => item.level())),
+    stop: async () => {
+      await Promise.all(live.map((item) => item.stop()));
+      const clips = live.map((item) => {
+        const pcm = item.pcm();
+        return { name: item.name, pcm, ...speechStats(pcm) };
+      });
+      const best = clips.reduce((clearest, clip) =>
+        speechScore(clip) > speechScore(clearest) ? clip : clearest,
+      );
+      const clip: VoiceClip = {
+        audio: wavFile(best.pcm),
+        peak: best.peak,
+        floor: best.floor,
+        microphone: best.name,
+        pickedMicrophone: false,
+      };
+      // Keep that microphone only when it heard speech: in silence, the
+      // clearest one means nothing.
+      if (picking && !isSilent(clip)) {
+        await chooseMicrophone(best.name);
+        clip.pickedMicrophone = true;
+      }
+      return clip;
+    },
+    cancel: () => {
+      for (const item of live) item.kill();
+    },
+  };
+}
+
+/**
+ * Is a clip silent? Transcription models make up words for silence, so a
+ * silent clip is not sent. A clip is silent when its loud part is under
+ * VOICE_MIN_LOUDNESS (default 300), for example a muted microphone.
+ */
+export function isSilent(clip: Pick<VoiceClip, "peak">) {
+  return clip.peak < Number(process.env.VOICE_MIN_LOUDNESS || 300);
+}
+
+/**
+ * The words in `audio`, with OpenAI, or Grok when there is only an xAI key.
+ * The key is the one the session of `threadId` uses: saved with `/connect`,
+ * else the env var. `name` gives the format, for example `voice.wav`.
+ * VOICE_LANGUAGE (an ISO-639-1 code such as `en`) tells the model which
+ * language to expect.
+ */
+export async function transcribe(
+  audio: Uint8Array,
+  options: {
+    name: string;
+    threadId: string;
+    abortSignal?: AbortSignal;
+  },
+) {
+  const file = new File([audio.slice()], options.name, { type: "audio/wav" });
+  const language = process.env.VOICE_LANGUAGE ? { language: process.env.VOICE_LANGUAGE } : {};
+  const openaiKey = await providerKey(openaiByok, options.threadId);
+  if (openaiKey !== null) {
+    const result = await generateTranscription({
+      adapter: createOpenaiTranscription("gpt-4o-transcribe", openaiKey),
+      audio: file,
+      timeout: TRANSCRIBE_MS,
+      abortSignal: options.abortSignal,
+      ...language,
+    });
+    return result.text.trim();
+  }
+  const grokKey = await providerKey(grokByok, options.threadId);
+  if (grokKey !== null) {
+    const result = await generateTranscription({
+      adapter: createGrokTranscription("grok-stt", grokKey),
+      audio: file,
+      timeout: TRANSCRIBE_MS,
+      abortSignal: options.abortSignal,
+      ...language,
+    });
+    return result.text.trim();
+  }
+  throw new Error(
+    "Voice needs an OpenAI or xAI key for the transcript. Run /connect openai or /connect grok.",
+  );
+}
+
+const SKIP = new Set(["node_modules", ".git", "dist"]);
+
+/** The files in `dir` and its folders, 3 levels deep. Stops at MAX_SPOKEN_FILES. */
+async function filesIn(dir: string, depth = 0, acc: Array<string> = []): Promise<Array<string>> {
+  if (depth > 3 || acc.length >= MAX_SPOKEN_FILES) return acc;
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    if (acc.length >= MAX_SPOKEN_FILES) break;
+    if (entry.name.startsWith(".") || SKIP.has(entry.name)) continue;
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) await filesIn(path, depth + 1, acc);
+    else acc.push(path);
+  }
+  return acc;
+}
+
+/** Spoken text in a form that file names match: "cat dot png" is "cat.png". */
+function normalize(text: string) {
+  return text
+    .toLowerCase()
+    .replace(/\s+dot\s+/g, ".")
+    .replace(/\s*\.\s*(?=[a-z0-9]{2,4}\b)/g, ".");
+}
+
+/** The media a turn made, newest last, for "the last image" and the like. */
+export interface RecentMedia {
+  kind: string;
+  path: string;
+}
+
+const RECENT =
+  /\b(last|latest|previous|that|this|the)\s+(image|picture|photo|video|clip|song|track|audio|sound)\b/;
+
+const KIND_OF_WORD: Record<string, string> = {
+  image: "image",
+  picture: "image",
+  photo: "image",
+  video: "video",
+  clip: "video",
+  song: "audio",
+  track: "audio",
+  audio: "audio",
+  sound: "audio",
+};
+
+/**
+ * Turn the files a user names in a voice message into `@path` attachments.
+ * A file counts when its name is in the text ("use cat dot png as a
+ * reference"), or when the text says "the last image" and the screen saved
+ * one. The CLI reads each `@path` and sends the file with the message.
+ */
+export async function withSpokenFiles(
+  text: string,
+  roots: ReadonlyArray<string>,
+  recent: ReadonlyArray<RecentMedia> = [],
+) {
+  const spoken = normalize(text);
+  const match = RECENT.exec(spoken);
+  const wantsNamedFile = /\.[a-z0-9]{2,4}\b/.test(spoken);
+  if (!wantsNamedFile && !match) return { text, files: [] };
+  const found = new Set<string>();
+  if (wantsNamedFile) {
+    for (const root of roots) {
+      for (const file of await filesIn(root)) {
+        const name = basename(file).toLowerCase();
+        if (extname(name) !== "" && spoken.includes(name)) found.add(file);
+      }
+    }
+  }
+  const kind = match ? KIND_OF_WORD[match[2] ?? ""] : undefined;
+  const latest = kind ? [...recent].reverse().find((media) => media.kind === kind) : undefined;
+  if (latest) found.add(latest.path);
+  const files = [...found].map((file) => relative(process.cwd(), file));
+  const refs = files.map((file) => `@"${file}"`);
+  return { text: [text, ...refs].join(" "), files };
+}
diff --git a/examples/harness-cli-batman/src/workdir.ts b/examples/harness-cli-batman/src/workdir.ts
new file mode 100644
index 0000000000..b160038b21
--- /dev/null
+++ b/examples/harness-cli-batman/src/workdir.ts
@@ -0,0 +1,6 @@
+// Work in the folder where you started the app. `pnpm start` runs the
+// script in this example's folder, and keeps your folder in INIT_CWD. The
+// CLI imports this file after ./env (the .env file is in this example's
+// folder) and before the harness, which reads the folder.
+const started = process.env.INIT_CWD;
+if (started) process.chdir(started);
diff --git a/examples/harness-cli-batman/tsconfig.json b/examples/harness-cli-batman/tsconfig.json
new file mode 100644
index 0000000000..cc93365a78
--- /dev/null
+++ b/examples/harness-cli-batman/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "esModuleInterop": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src"]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 34062fc523..71ca07ad66 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -268,6 +268,100 @@ importers:
         specifier: ^4.23.12
         version: 4.23.12
 
+  examples/harness-cli-batman:
+    dependencies:
+      '@tanstack/ai':
+        specifier: workspace:*
+        version: link:../../packages/ai
+      '@tanstack/ai-acp':
+        specifier: workspace:*
+        version: link:../../packages/ai-acp
+      '@tanstack/ai-anthropic':
+        specifier: workspace:*
+        version: link:../../packages/ai-anthropic
+      '@tanstack/ai-claude-code':
+        specifier: workspace:*
+        version: link:../../packages/ai-claude-code
+      '@tanstack/ai-code-mode':
+        specifier: workspace:*
+        version: link:../../packages/ai-code-mode
+      '@tanstack/ai-codex':
+        specifier: workspace:*
+        version: link:../../packages/ai-codex
+      '@tanstack/ai-dashboard':
+        specifier: workspace:*
+        version: link:../../packages/ai-dashboard
+      '@tanstack/ai-fal':
+        specifier: workspace:*
+        version: link:../../packages/ai-fal
+      '@tanstack/ai-grok':
+        specifier: workspace:*
+        version: link:../../packages/ai-grok
+      '@tanstack/ai-harness':
+        specifier: workspace:*
+        version: link:../../packages/ai-harness
+      '@tanstack/ai-harness-cli':
+        specifier: workspace:*
+        version: link:../../packages/ai-harness-cli
+      '@tanstack/ai-isolate-quickjs':
+        specifier: workspace:*
+        version: link:../../packages/ai-isolate-quickjs
+      '@tanstack/ai-mcp':
+        specifier: workspace:*
+        version: link:../../packages/ai-mcp
+      '@tanstack/ai-models':
+        specifier: workspace:*
+        version: link:../../packages/ai-models
+      '@tanstack/ai-openai':
+        specifier: workspace:*
+        version: link:../../packages/ai-openai
+      '@tanstack/ai-openrouter':
+        specifier: workspace:*
+        version: link:../../packages/ai-openrouter
+      '@tanstack/ai-persistence':
+        specifier: workspace:*
+        version: link:../../packages/ai-persistence
+      '@tanstack/ai-sandbox':
+        specifier: workspace:*
+        version: link:../../packages/ai-sandbox
+      '@tanstack/ai-sandbox-local-process':
+        specifier: workspace:*
+        version: link:../../packages/ai-sandbox-local-process
+      '@tanstack/ai-skills':
+        specifier: workspace:*
+        version: link:../../packages/ai-skills
+      '@tanstack/react-store':
+        specifier: ^0.11.1
+        version: 0.11.2(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      beautiful-mermaid:
+        specifier: ^1.1.3
+        version: 1.1.3
+      ink:
+        specifier: ^7.1.1
+        version: 7.1.1(@types/react@19.3.0)(react-devtools-core@6.1.5)(react@19.2.3)
+      marked:
+        specifier: ^15.0.6
+        version: 15.0.12
+      marked-terminal:
+        specifier: ^7.3.0
+        version: 7.3.0(marked@15.0.12)
+      react:
+        specifier: ^19.2.3
+        version: 19.2.3
+      zod:
+        specifier: ^4.2.0
+        version: 4.6.5
+    devDependencies:
+      '@types/node':
+        specifier: ^24.10.1
+        version: 24.13.6
+      '@types/react':
+        specifier: ^19.2.7
+        version: 19.3.0
+      tsx:
+        specifier: ^4.23.12
+        version: 4.23.12
+
   examples/harness-cli-cloudflare:
     dependencies:
       '@tanstack/ai':
@@ -3716,7 +3810,7 @@ importers:
     devDependencies:
       '@google/genai':
         specifier: ^2.10.0
-        version: 2.10.0(@modelcontextprotocol/sdk@1.29.0(zod@4.3.6))
+        version: 2.10.0(@modelcontextprotocol/sdk@1.29.0(zod@4.6.5))
       '@tanstack/ai':
         specifier: workspace:*
         version: link:../ai
@@ -8318,24 +8412,48 @@ packages:
     cpu: [arm64]
     os: [android]
 
+  '@parcel/watcher-android-arm64@2.6.0':
+    resolution: {integrity: sha512-trgpLSCKRC/huFjXX/Smh+0sWe4+YtKfktIToiMl59ghz7z+qkH6kMvNnUbLyRs9N11t8l4svSCs1+5B3rOAhA==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [android]
+
   '@parcel/watcher-darwin-arm64@2.5.1':
     resolution: {integrity: sha512-eAzPv5osDmZyBhou8PoF4i6RQXAfeKL9tjb3QzYuccXFMQU0ruIc/POh30ePnaOyD1UXdlKguHBmsTs53tVoPw==}
     engines: {node: '>= 10.0.0'}
     cpu: [arm64]
     os: [darwin]
 
+  '@parcel/watcher-darwin-arm64@2.6.0':
+    resolution: {integrity: sha512-Y3QV0gl7Q1zbfueunkWIERICbEojQFCgpyG7YqOGNFLsckXyI1xu9mAIUpKY9QBYzBtSkN8dBPwd3yiAO9ovMw==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
   '@parcel/watcher-darwin-x64@2.5.1':
     resolution: {integrity: sha512-1ZXDthrnNmwv10A0/3AJNZ9JGlzrF82i3gNQcWOzd7nJ8aj+ILyW1MTxVk35Db0u91oD5Nlk9MBiujMlwmeXZg==}
     engines: {node: '>= 10.0.0'}
     cpu: [x64]
     os: [darwin]
 
+  '@parcel/watcher-darwin-x64@2.6.0':
+    resolution: {integrity: sha512-Ohv6OpzhUfKYD7Beb8kDvG0jbIxORCYY1JRdZnaBtnjjkJxgD7ZVL0nw2sCYd0yTMKTvz3nnTnOF3cDifK+kvw==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
   '@parcel/watcher-freebsd-x64@2.5.1':
     resolution: {integrity: sha512-SI4eljM7Flp9yPuKi8W0ird8TI/JK6CSxju3NojVI6BjHsTyK7zxA9urjVjEKJ5MBYC+bLmMcbAWlZ+rFkLpJQ==}
     engines: {node: '>= 10.0.0'}
     cpu: [x64]
     os: [freebsd]
 
+  '@parcel/watcher-freebsd-x64@2.6.0':
+    resolution: {integrity: sha512-5HmXvDgs8VK+74jF9y9/2FE3/OnlcKmc56tjmSrEuZjpSZOGL+fvAu+HKJBdPs9uwoP2hE6TlSUpXZ/C5jUFmQ==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
   '@parcel/watcher-linux-arm-glibc@2.5.1':
     resolution: {integrity: sha512-RCdZlEyTs8geyBkkcnPWvtXLY44BCeZKmGYRtSgtwwnHR4dxfHRG3gR99XdMEdQ7KeiDdasJwwvNSF5jKtDwdA==}
     engines: {node: '>= 10.0.0'}
@@ -8343,6 +8461,13 @@ packages:
     os: [linux]
     libc: [glibc]
 
+  '@parcel/watcher-linux-arm-glibc@2.6.0':
+    resolution: {integrity: sha512-Ps/hui3A+vMbjdqlqAowK2ZL8+BO8dBjxeWXj6npTBs3jx4wWmbPpaLuqwrQrSqIVMCnpWo238bJ1U37GhQOYg==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm]
+    os: [linux]
+    libc: [glibc]
+
   '@parcel/watcher-linux-arm-musl@2.5.1':
     resolution: {integrity: sha512-6E+m/Mm1t1yhB8X412stiKFG3XykmgdIOqhjWj+VL8oHkKABfu/gjFj8DvLrYVHSBNC+/u5PeNrujiSQ1zwd1Q==}
     engines: {node: '>= 10.0.0'}
@@ -8350,6 +8475,13 @@ packages:
     os: [linux]
     libc: [musl]
 
+  '@parcel/watcher-linux-arm-musl@2.6.0':
+    resolution: {integrity: sha512-9c6AUHgHoG+IY88MRIHupztQiQnrbqHYQjkM2btA+Bf/wQnQMuiD0Wfk1EVv3TlNT3x41uU71rn6E4xh/+zvkw==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm]
+    os: [linux]
+    libc: [musl]
+
   '@parcel/watcher-linux-arm64-glibc@2.5.1':
     resolution: {integrity: sha512-LrGp+f02yU3BN9A+DGuY3v3bmnFUggAITBGriZHUREfNEzZh/GO06FF5u2kx8x+GBEUYfyTGamol4j3m9ANe8w==}
     engines: {node: '>= 10.0.0'}
@@ -8357,6 +8489,13 @@ packages:
     os: [linux]
     libc: [glibc]
 
+  '@parcel/watcher-linux-arm64-glibc@2.6.0':
+    resolution: {integrity: sha512-yHRqS2owEXe6Hic9z6Mh1ECsCd+ODVOGvZDyciqRd21+v+o+DnXMOrw50DSpIG2sb8GPEaPPmfeCAWKPJdq46g==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
   '@parcel/watcher-linux-arm64-musl@2.5.1':
     resolution: {integrity: sha512-cFOjABi92pMYRXS7AcQv9/M1YuKRw8SZniCDw0ssQb/noPkRzA+HBDkwmyOJYp5wXcsTrhxO0zq1U11cK9jsFg==}
     engines: {node: '>= 10.0.0'}
@@ -8364,6 +8503,13 @@ packages:
     os: [linux]
     libc: [musl]
 
+  '@parcel/watcher-linux-arm64-musl@2.6.0':
+    resolution: {integrity: sha512-WhB2e/V7rqdHHWZusBSPuy5Ei8S6lSz6FE5TKKQz5h3a0O+C+mhY7vxU9b/stqvMb8beLnPY82ZrFTLKs+SrKA==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
   '@parcel/watcher-linux-x64-glibc@2.5.1':
     resolution: {integrity: sha512-GcESn8NZySmfwlTsIur+49yDqSny2IhPeZfXunQi48DMugKeZ7uy1FX83pO0X22sHntJ4Ub+9k34XQCX+oHt2A==}
     engines: {node: '>= 10.0.0'}
@@ -8371,6 +8517,13 @@ packages:
     os: [linux]
     libc: [glibc]
 
+  '@parcel/watcher-linux-x64-glibc@2.6.0':
+    resolution: {integrity: sha512-ulGE6x6Oz6iAwg75T8YQSoguBWasniIbX+QWpaYPcCnDOpdWX3k+4xbEYPZVLxOuoJI+svJJPD3sEj8G7lrQ3A==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
   '@parcel/watcher-linux-x64-musl@2.5.1':
     resolution: {integrity: sha512-n0E2EQbatQ3bXhcH2D1XIAANAcTZkQICBPVaxMeaCVBtOpBZpWJuf7LwyWPSBDITb7In8mqQgJ7gH8CILCURXg==}
     engines: {node: '>= 10.0.0'}
@@ -8378,6 +8531,13 @@ packages:
     os: [linux]
     libc: [musl]
 
+  '@parcel/watcher-linux-x64-musl@2.6.0':
+    resolution: {integrity: sha512-tkBYKt7YQrjIJWYDnto2YgO8MRkjlMTSNoRHzsXinBqbLdeOM3L32wPZJvIZxqaLMfSlS/4sUjH/6STVP/XDLw==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
   '@parcel/watcher-wasm@2.5.1':
     resolution: {integrity: sha512-RJxlQQLkaMMIuWRozy+z2vEqbaQlCuaCgVZIUCzQLYggY22LZbP5Y1+ia+FD724Ids9e+XIyOLXLrLgQSHIthw==}
     engines: {node: '>= 10.0.0'}
@@ -8390,6 +8550,12 @@ packages:
     cpu: [arm64]
     os: [win32]
 
+  '@parcel/watcher-win32-arm64@2.6.0':
+    resolution: {integrity: sha512-gIZAP23jaHjGWasY/TY6yL7NHFClf0Ga7FN+iINvk+KN94rhm94lYZhFsbYFNcA04/onvGD9kKmiJLJB2HbNwQ==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
   '@parcel/watcher-win32-ia32@2.5.1':
     resolution: {integrity: sha512-c2KkcVN+NJmuA7CGlaGD1qJh1cLfDnQsHjE89E60vUEMlqduHGCdCLJCID5geFVM0dOtA3ZiIO8BoEQmzQVfpQ==}
     engines: {node: '>= 10.0.0'}
@@ -8402,6 +8568,12 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@parcel/watcher-win32-x64@2.6.0':
+    resolution: {integrity: sha512-cA+/pXV2YkfxlIcXOQ5fSWqAzzPyD78/x5qbK/I0vUkrlYHA8TIz+MXjAbGouguKVSI4bOmkTSJ1/poVSsgt+A==}
+    engines: {node: '>= 10.0.0'}
+    cpu: [x64]
+    os: [win32]
+
   '@parcel/watcher@2.5.1':
     resolution: {integrity: sha512-dfUnCxiN9H4ap84DvD2ubjw+3vUNpstxa0TneY/Paat8a3R4uQZDLSvWjmznAY/DoahqTHl9V46HF/Zs3F29pg==}
     engines: {node: '>= 10.0.0'}
@@ -10732,20 +10904,14 @@ packages:
       vite:
         optional: true
 
-  '@tanstack/react-store@0.11.2':
-    resolution: {integrity: sha512-oj5O5DmiMWE+ih+SioX2ayC1kbK7d3fpLx0B75fPJr9nY3zU+hoW010yr64qXsY/9fyiLVE2bn5mGNV3owm8RQ==}
-    peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-
   '@tanstack/react-store@0.11.1':
     resolution: {integrity: sha512-HaIGKI3YLmjBYIvy5DFDY23oNaYZIsTZfngey07Uh5iLVJgM3bIGCnZeOFOqzjFld9JHWcaHJnasD/bKoGKwJQ==}
     peerDependencies:
       react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
       react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
-  '@tanstack/react-store@0.8.0':
-    resolution: {integrity: sha512-1vG9beLIuB7q69skxK9r5xiLN3ztzIPfSQSs0GfeqWGO2tGIyInZx0x1COhpx97RKaONSoAb8C3dxacWksm1ow==}
+  '@tanstack/react-store@0.11.2':
+    resolution: {integrity: sha512-oj5O5DmiMWE+ih+SioX2ayC1kbK7d3fpLx0B75fPJr9nY3zU+hoW010yr64qXsY/9fyiLVE2bn5mGNV3owm8RQ==}
     peerDependencies:
       react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
       react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
@@ -10885,11 +11051,6 @@ packages:
     peerDependencies:
       solid-js: ^1.6.0
 
-  '@tanstack/solid-store@0.8.0':
-    resolution: {integrity: sha512-JwqTedbxyOGw7mfmdGkB0RGgefRCw/tNauc8tlMcaS1mV5wTFT8c1KIB3LgttuHaanMJEBeqQJ7bc/R0WTP1fA==}
-    peerDependencies:
-      solid-js: ^1.6.0
-
   '@tanstack/start-client-core@1.170.34':
     resolution: {integrity: sha512-LfwZSbau2MLLZ/uPAoO+NC9fK3J66c0wLhnNQqIa+Goqw7bXPjkHwlsjY7evlUz1AnyhhQ1Qab95v+VmP0TZ9A==}
     engines: {node: '>=22.12.0'}
@@ -10924,9 +11085,6 @@ packages:
   '@tanstack/store@0.11.2':
     resolution: {integrity: sha512-sJ4mjol8uQsHV0gOJzzjwXfh2Fwm+Sz0+8deqiTm4jGbMdjzNSW+xZCFm0kUa870uhd8yi+DpKnZb5Kc4apa0Q==}
 
-  '@tanstack/store@0.8.0':
-    resolution: {integrity: sha512-Om+BO0YfMZe//X2z0uLF2j+75nQga6TpTJgLJQBiq85aOyZNIhkCgleNcud2KQg4k4v9Y9l+Uhru3qWMPGTOzQ==}
-
   '@tanstack/typedoc-config@0.3.4':
     resolution: {integrity: sha512-WXJavpiNqumNwdBQTM3wBqbHaULgoZ3cIri7xJinKqX/mOGXgc6ZghfAardD2PydP8tOcPf+xhrd1Qk/am9DMg==}
     engines: {node: '>=18'}
@@ -12343,10 +12501,6 @@ packages:
   classnames@2.5.1:
     resolution: {integrity: sha512-saHYOzhIQs6wy2sVxTM6bUDsQO4F50V9RQ22qBpEdCW+I+/Wmke2HOl6lS6dTpdxVhb88/I6+Hs+438c3lfUow==}
 
-  cli-boxes@3.0.0:
-    resolution: {integrity: sha512-/lzGpEWL/8PfI0BmBOPRwp0c/wFNX1RdUML3jK/RcSBA9T8mZDdQpqYBKtCFTOfQbwPqWEOpjqW+Fnayc0969g==}
-    engines: {node: '>=10'}
-
   cli-boxes@4.0.1:
     resolution: {integrity: sha512-5IOn+jcCEHEraYolBPs/sT4BxYCe2nHg374OPiItB1O96KZFseS2gthU4twyYzeDcFew4DaUM/xwc5BQf08JJw==}
     engines: {node: '>=18.20 <19 || >=20.10'}
@@ -17782,10 +17936,6 @@ packages:
     resolution: {integrity: sha512-Ne2YiiGN8bmrmJJEuTWTLJR32nh/JdL1+PSicowtNb0WFpn59GK8/lfD61bVtzguz7b3PBt74nxpv/Pw5po5Rg==}
     engines: {node: '>=8'}
 
-  type-fest@2.19.0:
-    resolution: {integrity: sha512-RAH822pAdBgcNMAfWnCBU3CFZcfZ/i1eZjwFU/dsLKumyuuP3niueg2UAukXYF0E2AAoc82ZSSf9J0WQBinzHA==}
-    engines: {node: '>=12.20'}
-
   type-fest@5.10.0:
     resolution: {integrity: sha512-NoSdpq/WEiAg5sjmBkmV/hfxv6HJH4NqPNrqjtSO5CwRmpsDfaf4begxW34KdJykH/l1yHtwBWQkCRdoXO8mPA==}
     engines: {node: '>=20'}
@@ -18683,10 +18833,6 @@ packages:
     engines: {node: '>=8'}
     hasBin: true
 
-  widest-line@4.0.1:
-    resolution: {integrity: sha512-o0cyEG0e8GPzT4iGHphIOh0cJOV8fivsXxddQasHPHfoZf1ZexrfeA21w2NaEN1RHE+fXlfISmOE8R9N3u3Qig==}
-    engines: {node: '>=12'}
-
   widest-line@6.0.0:
     resolution: {integrity: sha512-U89AsyEeAsyoF0zVJBkG9zBgekjgjK7yk9sje3F4IQpXBJ10TF6ByLlIfjMhcmHMJgHZI4KHt4rdNfktzxIAMA==}
     engines: {node: '>=20'}
@@ -20951,7 +21097,7 @@ snapshots:
   '@blaxel/core@0.3.11(@hey-api/openapi-ts@0.99.0(magicast@0.5.2)(typescript@7.0.2))':
     dependencies:
       '@hey-api/client-fetch': 0.10.2(@hey-api/openapi-ts@0.99.0(magicast@0.5.2)(typescript@7.0.2))
-      '@modelcontextprotocol/sdk': 1.29.0(zod@4.3.6)
+      '@modelcontextprotocol/sdk': 1.29.0(zod@4.6.5)
       archiver: 7.0.1
       axios: 1.18.1(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)
       dockerfile-ast: 0.7.1
@@ -20962,7 +21108,7 @@ snapshots:
       uuid: 11.1.1
       ws: 8.21.0
       yaml: 2.9.0
-      zod: 4.3.6
+      zod: 4.6.5
     transitivePeerDependencies:
       - '@cfworker/json-schema'
       - '@hey-api/openapi-ts'
@@ -22677,8 +22823,8 @@ snapshots:
   '@mistralai/mistralai@2.2.0':
     dependencies:
       ws: 8.21.0
-      zod: 4.3.6
-      zod-to-json-schema: 3.25.2(zod@4.3.6)
+      zod: 4.6.5
+      zod-to-json-schema: 3.25.2(zod@4.6.5)
     transitivePeerDependencies:
       - bufferutil
       - utf-8-validate
@@ -22691,11 +22837,11 @@ snapshots:
       eventsource-parser: 3.1.1
       jose: 6.2.12
       pkce-challenge: 5.0.1
-      zod: 4.3.6
+      zod: 4.6.5
 
   '@modelcontextprotocol/core@2.1.0':
     dependencies:
-      zod: 4.3.6
+      zod: 4.6.5
 
   '@modelcontextprotocol/ext-apps@1.7.4(@modelcontextprotocol/sdk@1.29.0(supports-color@7.2.0)(zod@4.2.1))(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(zod@3.25.76)':
     dependencies:
@@ -22793,12 +22939,11 @@ snapshots:
       zod-to-json-schema: 3.25.2(zod@4.6.5)
     transitivePeerDependencies:
       - supports-color
-    optional: true
 
   '@modelcontextprotocol/server@2.1.0':
     dependencies:
       '@modelcontextprotocol/core': 2.1.0
-      zod: 4.3.6
+      zod: 4.6.5
 
   '@msgpack/msgpack@3.1.3': {}
 
@@ -23058,7 +23203,7 @@ snapshots:
 
   '@openrouter/sdk@0.13.20':
     dependencies:
-      zod: 4.3.6
+      zod: 4.6.5
 
   '@opentelemetry/api-logs@0.217.0':
     dependencies:
@@ -23803,33 +23948,63 @@ snapshots:
   '@parcel/watcher-android-arm64@2.5.1':
     optional: true
 
+  '@parcel/watcher-android-arm64@2.6.0':
+    optional: true
+
   '@parcel/watcher-darwin-arm64@2.5.1':
     optional: true
 
+  '@parcel/watcher-darwin-arm64@2.6.0':
+    optional: true
+
   '@parcel/watcher-darwin-x64@2.5.1':
     optional: true
 
+  '@parcel/watcher-darwin-x64@2.6.0':
+    optional: true
+
   '@parcel/watcher-freebsd-x64@2.5.1':
     optional: true
 
+  '@parcel/watcher-freebsd-x64@2.6.0':
+    optional: true
+
   '@parcel/watcher-linux-arm-glibc@2.5.1':
     optional: true
 
+  '@parcel/watcher-linux-arm-glibc@2.6.0':
+    optional: true
+
   '@parcel/watcher-linux-arm-musl@2.5.1':
     optional: true
 
+  '@parcel/watcher-linux-arm-musl@2.6.0':
+    optional: true
+
   '@parcel/watcher-linux-arm64-glibc@2.5.1':
     optional: true
 
+  '@parcel/watcher-linux-arm64-glibc@2.6.0':
+    optional: true
+
   '@parcel/watcher-linux-arm64-musl@2.5.1':
     optional: true
 
+  '@parcel/watcher-linux-arm64-musl@2.6.0':
+    optional: true
+
   '@parcel/watcher-linux-x64-glibc@2.5.1':
     optional: true
 
+  '@parcel/watcher-linux-x64-glibc@2.6.0':
+    optional: true
+
   '@parcel/watcher-linux-x64-musl@2.5.1':
     optional: true
 
+  '@parcel/watcher-linux-x64-musl@2.6.0':
+    optional: true
+
   '@parcel/watcher-wasm@2.5.1':
     dependencies:
       is-glob: 4.0.3
@@ -23838,12 +24013,18 @@ snapshots:
   '@parcel/watcher-win32-arm64@2.5.1':
     optional: true
 
+  '@parcel/watcher-win32-arm64@2.6.0':
+    optional: true
+
   '@parcel/watcher-win32-ia32@2.5.1':
     optional: true
 
   '@parcel/watcher-win32-x64@2.5.1':
     optional: true
 
+  '@parcel/watcher-win32-x64@2.6.0':
+    optional: true
+
   '@parcel/watcher@2.5.1':
     dependencies:
       detect-libc: 1.0.3
@@ -23871,6 +24052,19 @@ snapshots:
       is-glob: 4.0.3
       node-addon-api: 7.1.1
       picomatch: 4.0.7
+    optionalDependencies:
+      '@parcel/watcher-android-arm64': 2.6.0
+      '@parcel/watcher-darwin-arm64': 2.6.0
+      '@parcel/watcher-darwin-x64': 2.6.0
+      '@parcel/watcher-freebsd-x64': 2.6.0
+      '@parcel/watcher-linux-arm-glibc': 2.6.0
+      '@parcel/watcher-linux-arm-musl': 2.6.0
+      '@parcel/watcher-linux-arm64-glibc': 2.6.0
+      '@parcel/watcher-linux-arm64-musl': 2.6.0
+      '@parcel/watcher-linux-x64-glibc': 2.6.0
+      '@parcel/watcher-linux-x64-musl': 2.6.0
+      '@parcel/watcher-win32-arm64': 2.6.0
+      '@parcel/watcher-win32-x64': 2.6.0
     optional: true
 
   '@pkgjs/parseargs@0.11.0':
@@ -27360,13 +27554,6 @@ snapshots:
       react-dom: 19.2.3(react@19.2.3)
       use-sync-external-store: 1.6.0(react@19.2.3)
 
-  '@tanstack/react-store@0.8.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
-    dependencies:
-      '@tanstack/store': 0.8.0
-      react: 19.2.3
-      react-dom: 19.2.3(react@19.2.3)
-      use-sync-external-store: 1.6.0(react@19.2.3)
-
   '@tanstack/router-core@1.171.34':
     dependencies:
       '@tanstack/history': 1.162.4
@@ -27573,11 +27760,6 @@ snapshots:
       '@tanstack/store': 0.11.1
       solid-js: 1.9.10
 
-  '@tanstack/solid-store@0.8.0(solid-js@1.9.10)':
-    dependencies:
-      '@tanstack/store': 0.8.0
-      solid-js: 1.9.10
-
   '@tanstack/start-client-core@1.170.34':
     dependencies:
       '@tanstack/router-core': 1.171.34
@@ -27704,8 +27886,6 @@ snapshots:
       - vite-plugin-solid
       - webpack
 
-  '@tanstack/store@0.11.1': {}
-
   '@tanstack/start-server-core@1.169.39(crossws@0.4.6(srvx@0.11.17))':
     dependencies:
       '@tanstack/history': 1.162.4
@@ -27734,9 +27914,9 @@ snapshots:
     dependencies:
       '@tanstack/router-core': 1.171.34
 
-  '@tanstack/store@0.11.2': {}
+  '@tanstack/store@0.11.1': {}
 
-  '@tanstack/store@0.8.0': {}
+  '@tanstack/store@0.11.2': {}
 
   '@tanstack/typedoc-config@0.3.4':
     dependencies:
@@ -28352,7 +28532,7 @@ snapshots:
       tar-stream: 3.1.7
       undici: 7.28.0
       xdg-app-paths: 5.1.0
-      zod: 4.3.6
+      zod: 4.6.5
     transitivePeerDependencies:
       - bare-abort-controller
       - react-native-b4a
@@ -29612,8 +29792,6 @@ snapshots:
   classnames@2.5.1:
     optional: true
 
-  cli-boxes@3.0.0: {}
-
   cli-boxes@4.0.1: {}
 
   cli-cursor@2.1.0:
@@ -36978,8 +37156,6 @@ snapshots:
 
   type-fest@0.7.1: {}
 
-  type-fest@2.19.0: {}
-
   type-fest@5.10.0:
     dependencies:
       tagged-tag: 1.0.0
@@ -37933,10 +38109,6 @@ snapshots:
       siginfo: 2.0.0
       stackback: 0.0.2
 
-  widest-line@4.0.1:
-    dependencies:
-      string-width: 5.1.2
-
   widest-line@6.0.0:
     dependencies:
       string-width: 8.2.2
@@ -38170,7 +38342,6 @@ snapshots:
   zod-to-json-schema@3.25.2(zod@4.6.5):
     dependencies:
       zod: 4.6.5
-    optional: true
 
   zod@3.25.76: {}
 

From bf5db167c9be31c93b8dfe7281a70a48c787ab97 Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Tue, 6 Oct 2026 13:02:14 +0000
Subject: [PATCH 248/286] ci: apply automated fixes

---
 examples/harness-cli-batman/src/cli.ts        |   64 +-
 .../harness-cli-batman/src/credentials.ts     |   66 +-
 examples/harness-cli-batman/src/effort.ts     |   50 +-
 examples/harness-cli-batman/src/env.ts        |    6 +-
 examples/harness-cli-batman/src/harness.ts    |  426 ++++---
 .../src/marked-terminal.d.ts                  |    6 +-
 examples/harness-cli-batman/src/media.ts      |  203 ++--
 .../src/screen/batman-art.ts                  |  108 +-
 .../harness-cli-batman/src/screen/commands.ts |   31 +-
 .../harness-cli-batman/src/screen/editor.ts   |  129 ++-
 .../harness-cli-batman/src/screen/footer.tsx  |   78 +-
 .../harness-cli-batman/src/screen/keys.ts     |   78 +-
 .../harness-cli-batman/src/screen/markdown.ts |   41 +-
 .../harness-cli-batman/src/screen/media.ts    |  113 +-
 .../harness-cli-batman/src/screen/menu.tsx    |   52 +-
 .../harness-cli-batman/src/screen/parts.tsx   |  214 ++--
 .../harness-cli-batman/src/screen/paths.ts    |   56 +-
 .../harness-cli-batman/src/screen/splash.tsx  |  171 +--
 .../harness-cli-batman/src/screen/status.tsx  |   78 +-
 .../harness-cli-batman/src/screen/theme.ts    |   24 +-
 examples/harness-cli-batman/src/sessions.ts   |  158 +--
 examples/harness-cli-batman/src/store.ts      |   34 +-
 examples/harness-cli-batman/src/tui.tsx       | 1032 +++++++++--------
 examples/harness-cli-batman/src/voice.ts      |  430 +++----
 examples/harness-cli-batman/src/workdir.ts    |    4 +-
 25 files changed, 2001 insertions(+), 1651 deletions(-)

diff --git a/examples/harness-cli-batman/src/cli.ts b/examples/harness-cli-batman/src/cli.ts
index d8e8ea0cc9..5189e0ee43 100644
--- a/examples/harness-cli-batman/src/cli.ts
+++ b/examples/harness-cli-batman/src/cli.ts
@@ -1,10 +1,10 @@
-import "./env";
-import "./workdir";
-import { runCli } from "@tanstack/ai-harness-cli";
-import { assistant } from "./harness";
-import { hasSession, listSessions, newSessionId } from "./sessions";
-import { persistence } from "./store";
-import { runTui, takeNextSession } from "./tui";
+import './env'
+import './workdir'
+import { runCli } from '@tanstack/ai-harness-cli'
+import { assistant } from './harness'
+import { hasSession, listSessions, newSessionId } from './sessions'
+import { persistence } from './store'
+import { runTui, takeNextSession } from './tui'
 
 /**
  * The session to open first: `--resume <id>`, `--resume` alone for the
@@ -12,30 +12,34 @@ import { runTui, takeNextSession } from "./tui";
  * options go to runCli.
  */
 async function firstSession(argv: Array<string>) {
-  const at = argv.findIndex((arg) => arg === "--resume" || arg.startsWith("--resume="));
+  const at = argv.findIndex(
+    (arg) => arg === '--resume' || arg.startsWith('--resume='),
+  )
   if (at === -1) {
-    const thread = argv.indexOf("--thread");
-    const given = thread === -1 ? undefined : argv[thread + 1];
-    return { argv, threadId: given ?? newSessionId() };
+    const thread = argv.indexOf('--thread')
+    const given = thread === -1 ? undefined : argv[thread + 1]
+    return { argv, threadId: given ?? newSessionId() }
   }
-  const [flag = ""] = argv.splice(at, 1);
-  const next = argv[at];
-  const id = flag.startsWith("--resume=")
-    ? flag.slice("--resume=".length)
-    : next !== undefined && !next.startsWith("-")
+  const [flag = ''] = argv.splice(at, 1)
+  const next = argv[at]
+  const id = flag.startsWith('--resume=')
+    ? flag.slice('--resume='.length)
+    : next !== undefined && !next.startsWith('-')
       ? argv.splice(at, 1)[0]
-      : (await listSessions(1))[0]?.id;
+      : (await listSessions(1))[0]?.id
   if (id === undefined || !(await hasSession(id))) {
     process.stderr.write(
-      id === undefined ? "No saved session yet.\n" : `No saved session ${id}.\n`,
-    );
-    process.exit(1);
+      id === undefined
+        ? 'No saved session yet.\n'
+        : `No saved session ${id}.\n`,
+    )
+    process.exit(1)
   }
-  return { argv, threadId: id };
+  return { argv, threadId: id }
 }
 
-const first = await firstSession(process.argv.slice(2));
-let threadId = first.threadId;
+const first = await firstSession(process.argv.slice(2))
+let threadId = first.threadId
 
 // A terminal shows the Ink screen from ./tui. Piped input uses line mode.
 // `/resume` closes the screen, and the loop opens the session it picked.
@@ -44,12 +48,14 @@ for (;;) {
     persistence,
     ui: runTui,
     // The last `--thread` wins.
-    argv: [...first.argv, "--thread", threadId],
-  });
-  const next = takeNextSession();
-  if (next === undefined) break;
-  threadId = next;
+    argv: [...first.argv, '--thread', threadId],
+  })
+  const next = takeNextSession()
+  if (next === undefined) break
+  threadId = next
 }
 if (await hasSession(threadId)) {
-  process.stderr.write(`🦇 Continue this patrol with: pnpm start --resume ${threadId}\n`);
+  process.stderr.write(
+    `🦇 Continue this patrol with: pnpm start --resume ${threadId}\n`,
+  )
 }
diff --git a/examples/harness-cli-batman/src/credentials.ts b/examples/harness-cli-batman/src/credentials.ts
index 15535e7b8e..a41250f02f 100644
--- a/examples/harness-cli-batman/src/credentials.ts
+++ b/examples/harness-cli-batman/src/credentials.ts
@@ -1,11 +1,11 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { defineCredentialStore } from "@tanstack/ai-persistence";
-import type { Credential } from "@tanstack/ai-persistence";
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { defineCredentialStore } from '@tanstack/ai-persistence'
+import type { Credential } from '@tanstack/ai-persistence'
 
 /** The folder in your home folder where the example saves its files. */
-export const SAVE_DIR = join(homedir(), ".tanstack-harness-batman");
+export const SAVE_DIR = join(homedir(), '.tanstack-harness-batman')
 
 /**
  * Values in groups, saved as JSON in `file`. `load` gives `{}` for a missing
@@ -13,27 +13,29 @@ export const SAVE_DIR = join(homedir(), ".tanstack-harness-batman");
  * the other, so a second update never loses the first.
  */
 export function jsonFile<TValue>(file: string) {
-  type Saved = Record<string, Record<string, TValue>>;
-  let updating = Promise.resolve();
+  type Saved = Record<string, Record<string, TValue>>
+  let updating = Promise.resolve()
   const load = async (): Promise<Saved> => {
     try {
-      const parsed: unknown = JSON.parse(await readFile(file, "utf8"));
-      return typeof parsed === "object" && parsed !== null ? (parsed as Saved) : {};
+      const parsed: unknown = JSON.parse(await readFile(file, 'utf8'))
+      return typeof parsed === 'object' && parsed !== null
+        ? (parsed as Saved)
+        : {}
     } catch {
-      return {};
+      return {}
     }
-  };
+  }
   const update = (change: (all: Saved) => void) => {
     const run = updating.then(async () => {
-      const all = await load();
-      change(all);
-      await mkdir(dirname(file), { recursive: true });
-      await writeFile(file, JSON.stringify(all, null, 2), { mode: 0o600 });
-    });
-    updating = run.catch(() => {});
-    return run;
-  };
-  return { load, update };
+      const all = await load()
+      change(all)
+      await mkdir(dirname(file), { recursive: true })
+      await writeFile(file, JSON.stringify(all, null, 2), { mode: 0o600 })
+    })
+    updating = run.catch(() => {})
+    return run
+  }
+  return { load, update }
 }
 
 /**
@@ -41,25 +43,27 @@ export function jsonFile<TValue>(file: string) {
  * file in your home folder, so they survive a restart. The file is readable
  * by your user only. A production store would encrypt the values.
  */
-export function fileCredentials(file = join(SAVE_DIR, "credentials.json")) {
-  const { load, update } = jsonFile<Credential>(file);
+export function fileCredentials(file = join(SAVE_DIR, 'credentials.json')) {
+  const { load, update } = jsonFile<Credential>(file)
   const owner = (scope: { userId?: string; tenantId?: string }) =>
-    `${scope.tenantId ?? "-"}/${scope.userId ?? "-"}`;
+    `${scope.tenantId ?? '-'}/${scope.userId ?? '-'}`
 
   return defineCredentialStore({
     get: async (scope, id) => (await load())[owner(scope)]?.[id] ?? null,
     set: (scope, id, credential) =>
       update((all) => {
-        all[owner(scope)] = { ...all[owner(scope)], [id]: credential };
+        all[owner(scope)] = { ...all[owner(scope)], [id]: credential }
       }),
     delete: (scope, id) =>
       update((all) => {
-        delete all[owner(scope)]?.[id];
+        delete all[owner(scope)]?.[id]
       }),
     list: async (scope) =>
-      Object.entries((await load())[owner(scope)] ?? {}).map(([id, credential]) => ({
-        id,
-        type: credential.type,
-      })),
-  });
+      Object.entries((await load())[owner(scope)] ?? {}).map(
+        ([id, credential]) => ({
+          id,
+          type: credential.type,
+        }),
+      ),
+  })
 }
diff --git a/examples/harness-cli-batman/src/effort.ts b/examples/harness-cli-batman/src/effort.ts
index 73f3c6229b..8d7e3555bc 100644
--- a/examples/harness-cli-batman/src/effort.ts
+++ b/examples/harness-cli-batman/src/effort.ts
@@ -1,8 +1,8 @@
-import { REASONING_LEVELS } from "@tanstack/ai";
-import { configOption, defineCommand, definePlugin } from "@tanstack/ai-harness";
+import { REASONING_LEVELS } from '@tanstack/ai'
+import { configOption, defineCommand, definePlugin } from '@tanstack/ai-harness'
 
-export const EFFORTS = ["default", ...REASONING_LEVELS] as const;
-type Effort = (typeof EFFORTS)[number];
+export const EFFORTS = ['default', ...REASONING_LEVELS] as const
+type Effort = (typeof EFFORTS)[number]
 
 /**
  * `/effort`: how hard the main model thinks at the next turn. It sets
@@ -12,46 +12,48 @@ type Effort = (typeof EFFORTS)[number];
  */
 export function effortPicker(options: { reasons: (model: string) => boolean }) {
   return definePlugin({
-    name: "example/effort",
+    name: 'example/effort',
     setup: (ctx) => {
       const current = (): Effort =>
-        EFFORTS.find((effort) => effort === ctx.config.get("effort")) ?? "default";
+        EFFORTS.find((effort) => effort === ctx.config.get('effort')) ??
+        'default'
       return {
         config: {
           effort: configOption.select({
             options: EFFORTS,
-            default: "default",
-            category: "thought_level",
-            description: "How hard the model thinks",
+            default: 'default',
+            category: 'thought_level',
+            description: 'How hard the model thinks',
           }),
         },
         middleware: [
           {
-            name: "example/effort",
+            name: 'example/effort',
             onConfig: () => {
-              const effort = current();
-              if (effort === "default") return undefined;
-              if (!options.reasons(String(ctx.config.get("model")))) {
-                return undefined;
+              const effort = current()
+              if (effort === 'default') return undefined
+              if (!options.reasons(String(ctx.config.get('model')))) {
+                return undefined
               }
-              return { reasoning: { level: effort, summary: true } };
+              return { reasoning: { level: effort, summary: true } }
             },
           },
         ],
         commands: {
           effort: defineCommand({
-            description: `Show or set how hard the model thinks (${EFFORTS.join(", ")})`,
+            description: `Show or set how hard the model thinks (${EFFORTS.join(', ')})`,
             run: async (input: unknown) => {
-              const name = typeof input === "string" ? input.trim() : "";
-              if (name === "") return `Effort: ${current()}.`;
-              const effort = EFFORTS.find((item) => item === name);
-              if (!effort) return `Unknown effort "${name}". Choices: ${EFFORTS.join(", ")}.`;
-              await ctx.session.setConfig("effort", effort);
-              return `Effort: ${effort}. It applies at the next turn.`;
+              const name = typeof input === 'string' ? input.trim() : ''
+              if (name === '') return `Effort: ${current()}.`
+              const effort = EFFORTS.find((item) => item === name)
+              if (!effort)
+                return `Unknown effort "${name}". Choices: ${EFFORTS.join(', ')}.`
+              await ctx.session.setConfig('effort', effort)
+              return `Effort: ${effort}. It applies at the next turn.`
             },
           }),
         },
-      };
+      }
     },
-  });
+  })
 }
diff --git a/examples/harness-cli-batman/src/env.ts b/examples/harness-cli-batman/src/env.ts
index e314d621d5..16b37bb24d 100644
--- a/examples/harness-cli-batman/src/env.ts
+++ b/examples/harness-cli-batman/src/env.ts
@@ -2,9 +2,9 @@
 // file is normal (the app needs none), so it says nothing. The CLI imports
 // this file first, so the keys are set before the harness reads them.
 try {
-  process.loadEnvFile();
+  process.loadEnvFile()
 } catch (error) {
-  if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
-    throw error;
+  if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+    throw error
   }
 }
diff --git a/examples/harness-cli-batman/src/harness.ts b/examples/harness-cli-batman/src/harness.ts
index 1d3b9fa3bd..cea583d4c8 100644
--- a/examples/harness-cli-batman/src/harness.ts
+++ b/examples/harness-cli-batman/src/harness.ts
@@ -1,8 +1,8 @@
-import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { delimiter, join } from "node:path";
-import { EventType, defineAgent, keyedAdapter } from "@tanstack/ai";
-import { defineHarness } from "@tanstack/ai-harness";
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { delimiter, join } from 'node:path'
+import { EventType, defineAgent, keyedAdapter } from '@tanstack/ai'
+import { defineHarness } from '@tanstack/ai-harness'
 import {
   compact,
   goal,
@@ -13,42 +13,56 @@ import {
   todos,
   usage,
   workspaceTools,
-} from "@tanstack/ai-harness/plugins";
-import { ANTHROPIC_MODELS, createAnthropicChat } from "@tanstack/ai-anthropic";
-import { anthropicByok } from "@tanstack/ai-anthropic/byok";
-import { claudeCodeText } from "@tanstack/ai-claude-code";
-import { codeMode } from "@tanstack/ai-code-mode/harness";
-import { codexText } from "@tanstack/ai-codex";
-import { falByok } from "@tanstack/ai-fal/byok";
-import { mcpConnector } from "@tanstack/ai-mcp/connector";
-import { GROK_CHAT_MODELS, createGrokText } from "@tanstack/ai-grok";
-import { grokByok } from "@tanstack/ai-grok/byok";
-import { createQuickJSIsolateDriver } from "@tanstack/ai-isolate-quickjs";
-import { getModel, supportedReasoningLevels } from "@tanstack/ai-models";
-import { OPENAI_CHAT_MODELS, createOpenaiChat, openaiTranscription } from "@tanstack/ai-openai";
-import { openaiByok } from "@tanstack/ai-openai/byok";
-import { createOpenRouterText } from "@tanstack/ai-openrouter";
-import { openrouterByok } from "@tanstack/ai-openrouter/byok";
-import { OPENROUTER_CHAT_MODELS } from "@tanstack/ai-openrouter/model-meta";
-import { openrouterSignIn } from "@tanstack/ai-openrouter/pkce";
-import { defineSandbox, defineWorkspace, localSource } from "@tanstack/ai-sandbox";
-import { codingAgents } from "@tanstack/ai-sandbox/harness";
-import type { CodingAgentConfig } from "@tanstack/ai-sandbox/harness";
-import { localProcessSandbox } from "@tanstack/ai-sandbox-local-process";
-import { skills } from "@tanstack/ai-skills/harness";
-import { z } from "zod";
-import { imageAgent, songAgent, soundAgent, speechAgent, videoAgent } from "./media";
-import { effortPicker } from "./effort";
-import { SAVE_DIR } from "./credentials";
-import { SCREEN_COMMANDS } from "./screen/commands";
-import { envKey, providerKey } from "./store";
-import type { AnyTextAdapter, KeyedAdapter } from "@tanstack/ai";
-import type { ModelRecord } from "@tanstack/ai-models";
-import type { ByokProvider } from "@tanstack/ai/byok";
+} from '@tanstack/ai-harness/plugins'
+import { ANTHROPIC_MODELS, createAnthropicChat } from '@tanstack/ai-anthropic'
+import { anthropicByok } from '@tanstack/ai-anthropic/byok'
+import { claudeCodeText } from '@tanstack/ai-claude-code'
+import { codeMode } from '@tanstack/ai-code-mode/harness'
+import { codexText } from '@tanstack/ai-codex'
+import { falByok } from '@tanstack/ai-fal/byok'
+import { mcpConnector } from '@tanstack/ai-mcp/connector'
+import { GROK_CHAT_MODELS, createGrokText } from '@tanstack/ai-grok'
+import { grokByok } from '@tanstack/ai-grok/byok'
+import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs'
+import { getModel, supportedReasoningLevels } from '@tanstack/ai-models'
+import {
+  OPENAI_CHAT_MODELS,
+  createOpenaiChat,
+  openaiTranscription,
+} from '@tanstack/ai-openai'
+import { openaiByok } from '@tanstack/ai-openai/byok'
+import { createOpenRouterText } from '@tanstack/ai-openrouter'
+import { openrouterByok } from '@tanstack/ai-openrouter/byok'
+import { OPENROUTER_CHAT_MODELS } from '@tanstack/ai-openrouter/model-meta'
+import { openrouterSignIn } from '@tanstack/ai-openrouter/pkce'
+import {
+  defineSandbox,
+  defineWorkspace,
+  localSource,
+} from '@tanstack/ai-sandbox'
+import { codingAgents } from '@tanstack/ai-sandbox/harness'
+import type { CodingAgentConfig } from '@tanstack/ai-sandbox/harness'
+import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'
+import { skills } from '@tanstack/ai-skills/harness'
+import { z } from 'zod'
+import {
+  imageAgent,
+  songAgent,
+  soundAgent,
+  speechAgent,
+  videoAgent,
+} from './media'
+import { effortPicker } from './effort'
+import { SAVE_DIR } from './credentials'
+import { SCREEN_COMMANDS } from './screen/commands'
+import { envKey, providerKey } from './store'
+import type { AnyTextAdapter, KeyedAdapter } from '@tanstack/ai'
+import type { ModelRecord } from '@tanstack/ai-models'
+import type { ByokProvider } from '@tanstack/ai/byok'
 
 // The agent works in the folder where you started the app (src/workdir.ts).
 // A path outside it asks you first.
-const root = process.cwd();
+const root = process.cwd()
 
 /**
  * The demo model's answer, in markdown, so the screen shows how it renders
@@ -56,31 +70,31 @@ const root = process.cwd();
  */
 function demoReply(said: string) {
   const chart = /chart|mermaid|diagram/i.test(said)
-    ? "\n\n```mermaid\ngraph LR\n  You --> Batman --> Model\n  Batman --> Tools\n  Batman --> Gotham\n```"
-    : "";
+    ? '\n\n```mermaid\ngraph LR\n  You --> Batman --> Model\n  Batman --> Tools\n  Batman --> Gotham\n```'
+    : ''
   return (
     [
       `🦇 **(demo, the night shift)** You said: "${said}".`,
-      "",
-      "The cave has no key yet. Light the signal:",
-      "- Type `/connect` to connect a provider.",
-      "- Type `/model` to pick a real model.",
-      "",
-      "_I am the night. I am Batman._",
-    ].join("\n") + chart
-  );
+      '',
+      'The cave has no key yet. Light the signal:',
+      '- Type `/connect` to connect a provider.',
+      '- Type `/model` to pick a real model.',
+      '',
+      '_I am the night. I am Batman._',
+    ].join('\n') + chart
+  )
 }
 
 /** Without any model key, a stand-in model that explains how to add one. */
 function demoModel(): AnyTextAdapter {
-  let calls = 0;
+  let calls = 0
   return {
-    kind: "text",
-    name: "demo",
-    model: "demo",
-    "~types": {
+    kind: 'text',
+    name: 'demo',
+    model: 'demo',
+    '~types': {
       providerOptions: {},
-      inputModalities: ["text"],
+      inputModalities: ['text'],
       messageMetadataByModality: {
         text: undefined,
         image: undefined,
@@ -92,71 +106,74 @@ function demoModel(): AnyTextAdapter {
       toolCallMetadata: undefined,
       systemPromptMetadata: undefined as never,
     },
-    structuredOutput: async () => ({ data: {}, rawText: "{}" }),
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
     chatStream: (options) =>
       (async function* () {
-        calls += 1;
-        const messageId = `demo-${calls}`;
-        const last = options.messages.at(-1);
-        const said = typeof last?.content === "string" ? last.content : "";
-        const now = Date.now();
+        calls += 1
+        const messageId = `demo-${calls}`
+        const last = options.messages.at(-1)
+        const said = typeof last?.content === 'string' ? last.content : ''
+        const now = Date.now()
         yield {
           type: EventType.RUN_STARTED,
-          runId: "demo",
-          threadId: "demo",
+          runId: 'demo',
+          threadId: 'demo',
           timestamp: now,
-        };
+        }
         yield {
           type: EventType.TEXT_MESSAGE_START,
           messageId,
-          role: "assistant",
+          role: 'assistant',
           timestamp: now,
-        };
+        }
         yield {
           type: EventType.TEXT_MESSAGE_CONTENT,
           messageId,
           delta: demoReply(said),
           timestamp: now,
-        };
-        yield { type: EventType.TEXT_MESSAGE_END, messageId, timestamp: now };
+        }
+        yield { type: EventType.TEXT_MESSAGE_END, messageId, timestamp: now }
         yield {
           type: EventType.RUN_FINISHED,
-          runId: "demo",
-          threadId: "demo",
+          runId: 'demo',
+          threadId: 'demo',
           timestamp: now,
           // ponytail: about 4 characters a token, so the footer counts in demo mode too.
           usage: {
-            promptTokens: Math.ceil(JSON.stringify(options.messages).length / 4),
+            promptTokens: Math.ceil(
+              JSON.stringify(options.messages).length / 4,
+            ),
             completionTokens: 30,
-            totalTokens: Math.ceil(JSON.stringify(options.messages).length / 4) + 30,
+            totalTokens:
+              Math.ceil(JSON.stringify(options.messages).length / 4) + 30,
           },
-          metadata: { tanstack: { finishReason: "stop" } },
-        };
+          metadata: { tanstack: { finishReason: 'stop' } },
+        }
       })(),
-  };
+  }
 }
 
 /** Is a key for `provider` in the environment (the `.env` shortcut)? */
 function hasEnvKey(provider: ByokProvider) {
-  return envKey(provider) !== null;
+  return envKey(provider) !== null
 }
 
 const openai = (model: (typeof OPENAI_CHAT_MODELS)[number]) =>
-  keyedAdapter(openaiByok, (key) => createOpenaiChat(model, key));
+  keyedAdapter(openaiByok, (key) => createOpenaiChat(model, key))
 const anthropic = (model: (typeof ANTHROPIC_MODELS)[number]) =>
-  keyedAdapter(anthropicByok, (key) => createAnthropicChat(model, key));
+  keyedAdapter(anthropicByok, (key) => createAnthropicChat(model, key))
 const grok = (model: (typeof GROK_CHAT_MODELS)[number]) =>
-  keyedAdapter(grokByok, (key) => createGrokText(model, key));
+  keyedAdapter(grokByok, (key) => createGrokText(model, key))
 const openrouter = (model: (typeof OPENROUTER_CHAT_MODELS)[number]) =>
-  keyedAdapter(openrouterByok, (key) => createOpenRouterText(model, key));
+  keyedAdapter(openrouterByok, (key) => createOpenRouterText(model, key))
 
 /** A model `/model` can pick. */
 export interface ModelEntry {
-  id: string;
+  id: string
   /** The key provider to connect, for example `openai` or `grok`. */
-  provider: string;
-  record: ModelRecord;
-  adapter: KeyedAdapter<AnyTextAdapter>;
+  provider: string
+  record: ModelRecord
+  adapter: KeyedAdapter<AnyTextAdapter>
 }
 
 /**
@@ -173,16 +190,20 @@ function providerModels<TModel extends string>(
   start: TModel,
 ) {
   const models = ids.flatMap((id): Array<ModelEntry> => {
-    const record = getModel(catalogId, id);
-    return record ? [{ id, provider: byok.id, record, adapter: adapter(id) }] : [];
-  });
+    const record = getModel(catalogId, id)
+    return record
+      ? [{ id, provider: byok.id, record, adapter: adapter(id) }]
+      : []
+  })
   return {
     id: byok.id,
     label: byok.label,
     byok,
     start,
-    models: models.sort((a, b) => b.id.localeCompare(a.id, "en", { numeric: true })),
-  };
+    models: models.sort((a, b) =>
+      b.id.localeCompare(a.id, 'en', { numeric: true }),
+    ),
+  }
 }
 
 /**
@@ -192,17 +213,29 @@ function providerModels<TModel extends string>(
  * the user to connect.
  */
 export const modelProviders = [
-  providerModels("openai", openaiByok, OPENAI_CHAT_MODELS, openai, "gpt-6-astra"),
-  providerModels("anthropic", anthropicByok, ANTHROPIC_MODELS, anthropic, "claude-opus-5-5"),
-  providerModels("xai", grokByok, GROK_CHAT_MODELS, grok, "grok-4.7"),
   providerModels(
-    "openrouter",
+    'openai',
+    openaiByok,
+    OPENAI_CHAT_MODELS,
+    openai,
+    'gpt-6-astra',
+  ),
+  providerModels(
+    'anthropic',
+    anthropicByok,
+    ANTHROPIC_MODELS,
+    anthropic,
+    'claude-opus-5-5',
+  ),
+  providerModels('xai', grokByok, GROK_CHAT_MODELS, grok, 'grok-4.7'),
+  providerModels(
+    'openrouter',
     openrouterByok,
     OPENROUTER_CHAT_MODELS,
     openrouter,
-    "openai/gpt-6-astra",
+    'openai/gpt-6-astra',
   ),
-];
+]
 
 /**
  * Each model by its id: the provider that must be connected, its catalog
@@ -210,8 +243,10 @@ export const modelProviders = [
  * of the providers do not overlap: OpenRouter ids start with the vendor.
  */
 export const modelInfo: Record<string, ModelEntry> = Object.fromEntries(
-  modelProviders.flatMap((provider) => provider.models.map((model) => [model.id, model])),
-);
+  modelProviders.flatMap((provider) =>
+    provider.models.map((model) => [model.id, model]),
+  ),
+)
 
 // A new session starts on the first provider with a key: one saved with
 // /connect, or one in the env (a `.env` file). Without any key, `gpt-6-astra`
@@ -219,23 +254,27 @@ export const modelInfo: Record<string, ModelEntry> = Object.fromEntries(
 // session keeps the model it had.
 const keyed = await Promise.all(
   modelProviders.map(async (provider) =>
-    (await providerKey(provider.byok, "startup")) === null ? [] : [provider],
+    (await providerKey(provider.byok, 'startup')) === null ? [] : [provider],
   ),
-);
-const startProvider = keyed.flat()[0];
-const startModel = startProvider?.start ?? "gpt-6-astra";
+)
+const startProvider = keyed.flat()[0]
+const startModel = startProvider?.start ?? 'gpt-6-astra'
 // The start model: the harness, /compact, /goal, and /agent haiku use it.
-const main: KeyedAdapter<AnyTextAdapter> = modelInfo[startModel].adapter;
+const main: KeyedAdapter<AnyTextAdapter> = modelInfo[startModel].adapter
 // With no key at all, `/model demo` answers without a key.
 const choices = {
-  ...Object.fromEntries(Object.values(modelInfo).map((model) => [model.id, model.adapter])),
+  ...Object.fromEntries(
+    Object.values(modelInfo).map((model) => [model.id, model.adapter]),
+  ),
   ...(startProvider ? {} : { demo: demoModel() }),
-};
+}
 
 /** Does the model think, so `/effort` changes it? */
 export function reasons(model: string) {
-  const record = modelInfo[model]?.record;
-  return record ? supportedReasoningLevels(record).some((level) => level !== "off") : false;
+  const record = modelInfo[model]?.record
+  return record
+    ? supportedReasoningLevels(record).some((level) => level !== 'off')
+    : false
 }
 
 // `/connect openrouter` signs in with the browser: no key to paste, and one
@@ -244,21 +283,25 @@ export function reasons(model: string) {
 // page to make a key, then asks for it (the screen hides it as you type).
 export const keyProviders = [
   { ...openrouterByok, signIn: openrouterSignIn() },
-  { ...openaiByok, keyUrl: "https://platform.openai.com/api-keys" },
-  { ...anthropicByok, keyUrl: "https://console.anthropic.com/settings/keys" },
-  { ...grokByok, keyUrl: "https://console.x.ai" },
-  { ...falByok, keyUrl: "https://fal.ai/dashboard/keys" },
-];
+  { ...openaiByok, keyUrl: 'https://platform.openai.com/api-keys' },
+  { ...anthropicByok, keyUrl: 'https://console.anthropic.com/settings/keys' },
+  { ...grokByok, keyUrl: 'https://console.x.ai' },
+  { ...falByok, keyUrl: 'https://fal.ai/dashboard/keys' },
+]
 
 /** Is `command` on the PATH? Checks the Windows extensions too. */
 function onPath(command: string) {
   const extensions =
-    process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
-  return (process.env.PATH ?? "")
+    process.platform === 'win32'
+      ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';')
+      : ['']
+  return (process.env.PATH ?? '')
     .split(delimiter)
     .some((dir) =>
-      extensions.some((extension) => existsSync(join(dir, `${command}${extension.toLowerCase()}`))),
-    );
+      extensions.some((extension) =>
+        existsSync(join(dir, `${command}${extension.toLowerCase()}`)),
+      ),
+    )
 }
 
 /**
@@ -266,13 +309,17 @@ function onPath(command: string) {
  * first `[section]`), so the example runs Codex the way you set it up.
  */
 function codexSetting(key: string) {
-  const config = join(homedir(), ".codex", "config.toml");
-  if (!existsSync(config)) return undefined;
-  const [topLevel = ""] = readFileSync(config, "utf8").split(/^\s*\[/m);
-  return new RegExp(`^\\s*${key}\\s*=\\s*"([^"]+)"`, "m").exec(topLevel)?.[1];
+  const config = join(homedir(), '.codex', 'config.toml')
+  if (!existsSync(config)) return undefined
+  const [topLevel = ''] = readFileSync(config, 'utf8').split(/^\s*\[/m)
+  return new RegExp(`^\\s*${key}\\s*=\\s*"([^"]+)"`, 'm').exec(topLevel)?.[1]
 }
 
-const CODEX_SANDBOX_MODES = ["read-only", "workspace-write", "danger-full-access"] as const;
+const CODEX_SANDBOX_MODES = [
+  'read-only',
+  'workspace-write',
+  'danger-full-access',
+] as const
 
 /**
  * The Codex sandbox: CODEX_SANDBOX_MODE, else `sandbox_mode` in your Codex
@@ -280,27 +327,29 @@ const CODEX_SANDBOX_MODES = ["read-only", "workspace-write", "danger-full-access
  * folder (Access is denied).
  */
 function codexSandbox() {
-  const mode = process.env.CODEX_SANDBOX_MODE ?? codexSetting("sandbox_mode");
-  return CODEX_SANDBOX_MODES.find((known) => known === mode) ?? "workspace-write";
+  const mode = process.env.CODEX_SANDBOX_MODE ?? codexSetting('sandbox_mode')
+  return (
+    CODEX_SANDBOX_MODES.find((known) => known === mode) ?? 'workspace-write'
+  )
 }
 
 /** A typed agent you can run with `/agent haiku {"topic":"rain"}`. */
 const haiku = defineAgent({
-  name: "haiku",
-  description: "Writes a haiku about a topic",
+  name: 'haiku',
+  description: 'Writes a haiku about a topic',
   inputSchema: z.object({ topic: z.string() }),
   run: async (ctx) =>
     ctx.chat({
       adapter: await ctx.keys.adapter(main),
       messages: [
         {
-          role: "user",
+          role: 'user',
           content: `Write one haiku about ${ctx.input.topic}. Only the haiku.`,
         },
       ],
       stream: false,
     }),
-});
+})
 
 // The model calls the media agents as tools, and the harness keeps each file
 // they make. Each one uses the key its provider needs. Without the key, the
@@ -308,81 +357,92 @@ const haiku = defineAgent({
 // - OpenAI: images, speech, and video with Sora.
 // - xAI Grok: video with Grok Imagine (it wins over Sora).
 // - fal: songs and sound effects.
-const media = [imageAgent, speechAgent, videoAgent, songAgent, soundAgent];
+const media = [imageAgent, speechAgent, videoAgent, songAgent, soundAgent]
 
 // Notion and Linear through their MCP servers. `/connect notion` signs in
 // through the browser. No app setup or API key is needed.
 const notion = mcpConnector({
-  id: "notion",
-  label: "Notion",
-  url: "https://mcp.notion.com/mcp",
-});
+  id: 'notion',
+  label: 'Notion',
+  url: 'https://mcp.notion.com/mcp',
+})
 const linear = mcpConnector({
-  id: "linear",
-  label: "Linear",
-  url: "https://mcp.linear.app/mcp",
-});
+  id: 'linear',
+  label: 'Linear',
+  url: 'https://mcp.linear.app/mcp',
+})
 
 // The lead model can hand coding work to your local Claude Code and Codex.
 // Each one turns on when its CLI is on the PATH (CODING_AGENTS=0 turns both
 // off). They work in your folder with your own `claude login` and
 // `codex login`, so the API keys are removed from their processes.
-const useCodingAgents = process.env.CODING_AGENTS !== "0";
-const codingAgentList: Record<string, CodingAgentConfig> = {};
-if (useCodingAgents && onPath("claude")) {
+const useCodingAgents = process.env.CODING_AGENTS !== '0'
+const codingAgentList: Record<string, CodingAgentConfig> = {}
+if (useCodingAgents && onPath('claude')) {
   codingAgentList.claude_code = {
-    adapter: claudeCodeText("claude-opus-4-8", {
-      authMode: "host",
-      permissionMode: "acceptEdits",
+    adapter: claudeCodeText('claude-opus-4-8', {
+      authMode: 'host',
+      permissionMode: 'acceptEdits',
     }),
     description:
-      "Claude Code, the local coding agent. Larger changes, refactors, and reviews in the workspace.",
-  };
+      'Claude Code, the local coding agent. Larger changes, refactors, and reviews in the workspace.',
+  }
 }
-if (useCodingAgents && onPath("codex")) {
+if (useCodingAgents && onPath('codex')) {
   codingAgentList.codex = {
     // A ChatGPT login supports only some models, so the model and the sandbox
     // come from your Codex config unless CODEX_MODEL or CODEX_SANDBOX_MODE is
     // set.
-    adapter: codexText(process.env.CODEX_MODEL ?? codexSetting("model") ?? "gpt-5.3-codex", {
-      authMode: "host",
-      sandboxMode: codexSandbox(),
-      approvalPolicy: "never",
-    }),
-    description: "Codex, the local coding agent. Quick fixes, scripts, and tests in the workspace.",
-  };
+    adapter: codexText(
+      process.env.CODEX_MODEL ?? codexSetting('model') ?? 'gpt-5.3-codex',
+      {
+        authMode: 'host',
+        sandboxMode: codexSandbox(),
+        approvalPolicy: 'never',
+      },
+    ),
+    description:
+      'Codex, the local coding agent. Quick fixes, scripts, and tests in the workspace.',
+  }
 }
 const coding =
   Object.keys(codingAgentList).length > 0
     ? [
         codingAgents({
           sandbox: defineSandbox({
-            id: "workspace",
+            id: 'workspace',
             provider: localProcessSandbox({
               dir: root,
-              scrubEnv: ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
+              scrubEnv: ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY'],
             }),
             workspace: defineWorkspace({ source: localSource(root) }),
           }),
           agents: codingAgentList,
         }),
       ]
-    : [];
+    : []
 
-const tools = [...media.map((agent) => agent.name), ...Object.keys(codingAgentList)];
+const tools = [
+  ...media.map((agent) => agent.name),
+  ...Object.keys(codingAgentList),
+]
 
 /**
  * A feature that a key for any one of `providers` turns on. `on` is the
  * state at startup, from the env vars only. The screen follows the saved
  * keys live.
  */
-function keyFeature(name: string, providers: Array<ByokProvider>, needs: string) {
+function keyFeature(
+  name: string,
+  providers: Array<ByokProvider>,
+  needs: string,
+) {
   return {
     name,
     on: providers.some(hasEnvKey),
     needs,
     providers: providers.map((provider) => provider.id),
-  };
+  }
 }
 
 /**
@@ -391,45 +451,45 @@ function keyFeature(name: string, providers: Array<ByokProvider>, needs: string)
  */
 export const features = [
   keyFeature(
-    "voice",
+    'voice',
     [openaiByok, grokByok],
-    "an OpenAI or xAI key (/connect openai or /connect grok), and ffmpeg",
+    'an OpenAI or xAI key (/connect openai or /connect grok), and ffmpeg',
   ),
-  keyFeature("images", [openaiByok], "an OpenAI key (/connect openai)"),
-  keyFeature("speech", [openaiByok], "an OpenAI key (/connect openai)"),
+  keyFeature('images', [openaiByok], 'an OpenAI key (/connect openai)'),
+  keyFeature('speech', [openaiByok], 'an OpenAI key (/connect openai)'),
   keyFeature(
-    "video",
+    'video',
     [grokByok, openaiByok],
-    "an xAI or OpenAI key (/connect grok or /connect openai)",
+    'an xAI or OpenAI key (/connect grok or /connect openai)',
   ),
-  keyFeature("songs", [falByok], "a fal key (/connect fal)"),
+  keyFeature('songs', [falByok], 'a fal key (/connect fal)'),
   {
-    name: "claude code",
-    on: "claude_code" in codingAgentList,
-    needs: "`claude` on the PATH",
+    name: 'claude code',
+    on: 'claude_code' in codingAgentList,
+    needs: '`claude` on the PATH',
     providers: [],
   },
   {
-    name: "codex",
-    on: "codex" in codingAgentList,
-    needs: "`codex` on the PATH",
+    name: 'codex',
+    on: 'codex' in codingAgentList,
+    needs: '`codex` on the PATH',
     providers: [],
   },
-  { name: "notion", on: true, needs: "", providers: [] },
-  { name: "linear", on: true, needs: "", providers: [] },
-];
+  { name: 'notion', on: true, needs: '', providers: [] },
+  { name: 'linear', on: true, needs: '', providers: [] },
+]
 
 export const assistant = defineHarness({
-  name: "gotham/batman",
+  name: 'gotham/batman',
   description:
-    "Batman in the terminal: files, voice, media, Notion, Linear, and local coding agents",
+    'Batman in the terminal: files, voice, media, Notion, Linear, and local coding agents',
   adapter: main,
   systemPrompts: [
-    "You are Batman, the Dark Knight, working as a careful coding agent in the workspace, the folder where the user started you. Speak like Batman: short, grave, direct. Call the user Commissioner when it fits. Use a bat emoji when you start a reply. Read files before you edit them. Keep answers short.",
-    `Your agent tools: ${tools.join(", ") || "none"}. The user gets each file a media tool makes, so do not paste file contents or links.`,
+    'You are Batman, the Dark Knight, working as a careful coding agent in the workspace, the folder where the user started you. Speak like Batman: short, grave, direct. Call the user Commissioner when it fits. Use a bat emoji when you start a reply. Read files before you edit them. Keep answers short.',
+    `Your agent tools: ${tools.join(', ') || 'none'}. The user gets each file a media tool makes, so do not paste file contents or links.`,
     'When the user asks to run Codex or Claude Code (by voice too: "run a Codex agent"), call that tool with a clear task, then give its answer back in a few lines.',
-    "The user can send files and voice messages. When they send an image and ask for a new version, a style, or an edit of it, call the image tool with useAttachedImages.",
-    "You can read Notion and Linear when they are connected. If a tool says to sign in or that a key is missing, tell the user the /connect command it names, for example /connect notion or /connect openai.",
+    'The user can send files and voice messages. When they send an image and ask for a new version, a style, or an edit of it, call the image tool with useAttachedImages.',
+    'You can read Notion and Linear when they are connected. If a tool says to sign in or that a key is missing, tell the user the /connect command it names, for example /connect notion or /connect openai.',
   ],
   agents: [haiku],
   subagents: { agents: media },
@@ -438,13 +498,13 @@ export const assistant = defineHarness({
   // this needs OPENAI_API_KEY in the env. A key saved with /connect does not
   // turn it on. Voice messages on the screen use the saved key (src/voice.ts).
   ...(process.env.OPENAI_API_KEY
-    ? { media: { transcribe: openaiTranscription("gpt-4o-transcribe") } }
+    ? { media: { transcribe: openaiTranscription('gpt-4o-transcribe') } }
     : {}),
   plugins: () => [
     notion,
     linear,
     permissions(),
-    workspaceTools({ root, outside: "ask" }),
+    workspaceTools({ root, outside: 'ask' }),
     todos(),
     providerKeys({ providers: keyProviders }),
     modelPicker({ choices, default: startModel }),
@@ -460,7 +520,7 @@ export const assistant = defineHarness({
     // over the global one. A skill named like a screen command is
     // /skill:<name>.
     skills({
-      dirs: ["./.agents/skills", "./.claude/skills", join(SAVE_DIR, "skills")],
+      dirs: ['./.agents/skills', './.claude/skills', join(SAVE_DIR, 'skills')],
       reserved: SCREEN_COMMANDS.map((command) => command.name),
     }),
     // Read-only tools (file reads, read-only Notion and Linear tools) move
@@ -471,8 +531,8 @@ export const assistant = defineHarness({
     codeMode({
       driver: createQuickJSIsolateDriver(),
       lazy: true,
-      lazyToolsConfig: { includeDescription: "first-sentence" },
+      lazyToolsConfig: { includeDescription: 'first-sentence' },
     }),
     ...coding,
   ],
-});
+})
diff --git a/examples/harness-cli-batman/src/marked-terminal.d.ts b/examples/harness-cli-batman/src/marked-terminal.d.ts
index 4dbc0dcad9..aa3a2469a8 100644
--- a/examples/harness-cli-batman/src/marked-terminal.d.ts
+++ b/examples/harness-cli-batman/src/marked-terminal.d.ts
@@ -1,10 +1,10 @@
 // marked-terminal has no types of its own. This is the one function the
 // screen uses.
-declare module "marked-terminal" {
-  import type { MarkedExtension } from "marked";
+declare module 'marked-terminal' {
+  import type { MarkedExtension } from 'marked'
 
   export function markedTerminal(
     options?: Record<string, unknown>,
     highlightOptions?: Record<string, unknown>,
-  ): MarkedExtension;
+  ): MarkedExtension
 }
diff --git a/examples/harness-cli-batman/src/media.ts b/examples/harness-cli-batman/src/media.ts
index 36b78505e4..c8e74eb365 100644
--- a/examples/harness-cli-batman/src/media.ts
+++ b/examples/harness-cli-batman/src/media.ts
@@ -1,20 +1,24 @@
-import { EventType, defineAgent, keyedAdapter } from "@tanstack/ai";
-import { mediaIdOf } from "@tanstack/ai-harness";
-import { falAudio } from "@tanstack/ai-fal";
-import { falByok } from "@tanstack/ai-fal/byok";
-import { createGrokVideo } from "@tanstack/ai-grok";
-import { grokByok } from "@tanstack/ai-grok/byok";
-import { createOpenaiImage, createOpenaiSpeech, createOpenaiVideo } from "@tanstack/ai-openai";
-import { openaiByok } from "@tanstack/ai-openai/byok";
-import { z } from "zod";
-import { mediaBytes } from "./store";
+import { EventType, defineAgent, keyedAdapter } from '@tanstack/ai'
+import { mediaIdOf } from '@tanstack/ai-harness'
+import { falAudio } from '@tanstack/ai-fal'
+import { falByok } from '@tanstack/ai-fal/byok'
+import { createGrokVideo } from '@tanstack/ai-grok'
+import { grokByok } from '@tanstack/ai-grok/byok'
+import {
+  createOpenaiImage,
+  createOpenaiSpeech,
+  createOpenaiVideo,
+} from '@tanstack/ai-openai'
+import { openaiByok } from '@tanstack/ai-openai/byok'
+import { z } from 'zod'
+import { mediaBytes } from './store'
 import type {
   AnyVideoAdapter,
   ImagePart,
   MediaInputMetadata,
   ModelMessage,
   UIMessage,
-} from "@tanstack/ai";
+} from '@tanstack/ai'
 
 // Every agent here returns a short text. The harness keeps each file it makes
 // and publishes a `harness.media` event, so the screen can show and save it.
@@ -22,81 +26,98 @@ import type {
 // Each agent builds its model with the user's key just before the call: the
 // key saved with `/connect <provider>`, else the env var. Without a key, the
 // call stops, and the screen says which `/connect` to run.
-const gptImage = keyedAdapter(openaiByok, (key) => createOpenaiImage("gpt-image-2.5-flare", key));
-const openaiVoice = keyedAdapter(openaiByok, (key) => createOpenaiSpeech("tts-1-hd", key));
-const sora = keyedAdapter(openaiByok, (key) => createOpenaiVideo("sora-2", key));
-const grokImagine = keyedAdapter(grokByok, (key) => createGrokVideo("grok-imagine-video-1.5", key));
+const gptImage = keyedAdapter(openaiByok, (key) =>
+  createOpenaiImage('gpt-image-2.5-flare', key),
+)
+const openaiVoice = keyedAdapter(openaiByok, (key) =>
+  createOpenaiSpeech('tts-1-hd', key),
+)
+const sora = keyedAdapter(openaiByok, (key) => createOpenaiVideo('sora-2', key))
+const grokImagine = keyedAdapter(grokByok, (key) =>
+  createGrokVideo('grok-imagine-video-1.5', key),
+)
 const falMusic = keyedAdapter(falByok, (key) =>
-  falAudio("fal-ai/elevenlabs/music", { apiKey: key }),
-);
+  falAudio('fal-ai/elevenlabs/music', { apiKey: key }),
+)
 const falSound = keyedAdapter(falByok, (key) =>
-  falAudio("fal-ai/stable-audio-25/text-to-audio", { apiKey: key }),
-);
+  falAudio('fal-ai/stable-audio-25/text-to-audio', { apiKey: key }),
+)
 
 /**
  * The images in the latest user message that has files: the ones the user
  * sent with `@path`, or with a voice message that named a file.
  */
-async function attachedImages(messages: ReadonlyArray<UIMessage | ModelMessage>) {
+async function attachedImages(
+  messages: ReadonlyArray<UIMessage | ModelMessage>,
+) {
   for (const message of [...messages].reverse()) {
-    if (message.role !== "user" || !("content" in message)) continue;
-    if (!Array.isArray(message.content)) continue;
-    const images: Array<ImagePart<MediaInputMetadata>> = [];
+    if (message.role !== 'user' || !('content' in message)) continue
+    if (!Array.isArray(message.content)) continue
+    const images: Array<ImagePart<MediaInputMetadata>> = []
     for (const part of message.content) {
-      const id = mediaIdOf(part);
-      if (id === undefined || part.type !== "image") continue;
-      const bytes = await mediaBytes(id);
-      const mimeType = part.source.mimeType ?? "image/png";
+      const id = mediaIdOf(part)
+      if (id === undefined || part.type !== 'image') continue
+      const bytes = await mediaBytes(id)
+      const mimeType = part.source.mimeType ?? 'image/png'
       if (bytes) {
         images.push({
-          type: "image",
+          type: 'image',
           source: {
-            type: "data",
-            value: Buffer.from(bytes).toString("base64"),
+            type: 'data',
+            value: Buffer.from(bytes).toString('base64'),
             mimeType,
           },
-        });
+        })
       }
     }
-    if (images.length > 0) return images;
+    if (images.length > 0) return images
   }
-  return [];
+  return []
 }
 
 /** Makes an image with OpenAI. It can start from the images the user sent. */
 export const imageAgent = defineAgent({
-  name: "image",
+  name: 'image',
   description:
-    "Generates one image from a detailed visual prompt. Set useAttachedImages when the user sent images to use as references (a new version, a style, an edit). The user gets the image.",
-  produces: "image",
+    'Generates one image from a detailed visual prompt. Set useAttachedImages when the user sent images to use as references (a new version, a style, an edit). The user gets the image.',
+  produces: 'image',
   inputSchema: z.object({
-    prompt: z.string().describe("A detailed description of the image"),
+    prompt: z.string().describe('A detailed description of the image'),
     useAttachedImages: z
       .boolean()
       .optional()
-      .describe("Use the images the user sent as references"),
+      .describe('Use the images the user sent as references'),
   }),
   run: async (ctx) => {
-    const references = ctx.input.useAttachedImages ? await attachedImages(ctx.messages) : [];
-    const adapter = await ctx.keys.adapter(gptImage);
+    const references = ctx.input.useAttachedImages
+      ? await attachedImages(ctx.messages)
+      : []
+    const adapter = await ctx.keys.adapter(gptImage)
     // With references, the prompt is the text plus the images (an edit).
     const result =
       references.length > 0
         ? await ctx.generateImage({
             adapter,
-            prompt: [{ type: "text", content: ctx.input.prompt }, ...references],
-            size: "1024x1024",
+            prompt: [
+              { type: 'text', content: ctx.input.prompt },
+              ...references,
+            ],
+            size: '1024x1024',
           })
         : await ctx.generateImage({
             adapter,
             prompt: ctx.input.prompt,
-            size: "1024x1024",
-          });
-    if (result.images.length === 0) throw new Error("The image model returned no image.");
-    const from = references.length > 0 ? ` from ${references.length} reference image(s)` : "";
-    return `Made the image${from} with ${result.model}. The user has it.`;
+            size: '1024x1024',
+          })
+    if (result.images.length === 0)
+      throw new Error('The image model returned no image.')
+    const from =
+      references.length > 0
+        ? ` from ${references.length} reference image(s)`
+        : ''
+    return `Made the image${from} with ${result.model}. The user has it.`
   },
-});
+})
 
 /**
  * Makes a short video: with Grok Imagine when the user has an xAI key, else
@@ -104,90 +125,104 @@ export const imageAgent = defineAgent({
  * `stream: true`: one stream from the job start to the file.
  */
 export const videoAgent = defineAgent({
-  name: "video",
+  name: 'video',
   description:
-    "Generates one short video clip from a detailed visual prompt. Takes a minute or two. The user gets the video.",
-  produces: "video",
+    'Generates one short video clip from a detailed visual prompt. Takes a minute or two. The user gets the video.',
+  produces: 'video',
   inputSchema: z.object({
-    prompt: z.string().describe("A detailed description of the scene and the motion"),
+    prompt: z
+      .string()
+      .describe('A detailed description of the scene and the motion'),
   }),
   run: async (ctx) => {
-    const hasGrokKey = (await ctx.keys.get(grokByok)) !== null;
+    const hasGrokKey = (await ctx.keys.get(grokByok)) !== null
     const adapter: AnyVideoAdapter = hasGrokKey
       ? await ctx.keys.adapter(grokImagine)
-      : await ctx.keys.adapter(sora);
+      : await ctx.keys.adapter(sora)
     const stream = ctx.generateVideo({
       adapter,
       prompt: ctx.input.prompt,
       stream: true,
-    });
+    })
     for await (const chunk of stream) {
       // The stream reports a failed or stopped job as an event, not a throw.
-      if (chunk.type === EventType.RUN_ERROR) throw new Error(chunk.message);
+      if (chunk.type === EventType.RUN_ERROR) throw new Error(chunk.message)
     }
-    return `Made the video with ${adapter.model}. The user has it.`;
+    return `Made the video with ${adapter.model}. The user has it.`
   },
-});
+})
 
 /** Reads a text aloud with OpenAI text to speech. */
 export const speechAgent = defineAgent({
-  name: "speech",
+  name: 'speech',
   description:
-    "Reads a text aloud and makes an audio file of it (text to speech). The user gets the audio.",
-  produces: "speech",
+    'Reads a text aloud and makes an audio file of it (text to speech). The user gets the audio.',
+  produces: 'speech',
   inputSchema: z.object({
-    text: z.string().describe("The exact words to say"),
+    text: z.string().describe('The exact words to say'),
     voice: z
-      .enum(["alloy", "echo", "fable", "onyx", "nova", "shimmer"])
+      .enum(['alloy', 'echo', 'fable', 'onyx', 'nova', 'shimmer'])
       .optional()
-      .describe("The voice. Default: alloy"),
+      .describe('The voice. Default: alloy'),
   }),
   run: async (ctx) => {
     const result = await ctx.generateSpeech({
       adapter: await ctx.keys.adapter(openaiVoice),
       text: ctx.input.text,
-      voice: ctx.input.voice ?? "alloy",
-    });
-    return `Read the text aloud with ${result.model}. The user has the audio.`;
+      voice: ctx.input.voice ?? 'alloy',
+    })
+    return `Read the text aloud with ${result.model}. The user has the audio.`
   },
-});
+})
 
 /** Makes a song with vocals and music through fal (ElevenLabs Music). */
 export const songAgent = defineAgent({
-  name: "song",
+  name: 'song',
   description:
-    "Composes a song or an instrumental track from a description (genre, mood, instruments, and lyrics if the user gave any). Takes up to a minute. The user gets the audio.",
-  produces: "audio",
+    'Composes a song or an instrumental track from a description (genre, mood, instruments, and lyrics if the user gave any). Takes up to a minute. The user gets the audio.',
+  produces: 'audio',
   inputSchema: z.object({
-    prompt: z.string().describe("The style, mood, instruments, and the lyrics, if any"),
-    seconds: z.number().min(10).max(120).optional().describe("The length in seconds. Default: 30"),
+    prompt: z
+      .string()
+      .describe('The style, mood, instruments, and the lyrics, if any'),
+    seconds: z
+      .number()
+      .min(10)
+      .max(120)
+      .optional()
+      .describe('The length in seconds. Default: 30'),
   }),
   run: async (ctx) => {
     const result = await ctx.generateAudio({
       adapter: await ctx.keys.adapter(falMusic),
       prompt: ctx.input.prompt,
       duration: ctx.input.seconds ?? 30,
-    });
-    return `Composed the song with ${result.model}. The user has the audio.`;
+    })
+    return `Composed the song with ${result.model}. The user has the audio.`
   },
-});
+})
 
 /** Makes a sound effect through fal (Stable Audio). */
 export const soundAgent = defineAgent({
-  name: "sound_effect",
+  name: 'sound_effect',
   description:
-    "Makes a short sound effect or ambience from a description, for example rain on a window. The user gets the audio.",
-  produces: "audio",
+    'Makes a short sound effect or ambience from a description, for example rain on a window. The user gets the audio.',
+  produces: 'audio',
   inputSchema: z.object({
-    prompt: z.string().describe("The sound to make"),
-    seconds: z.number().min(1).max(30).optional().describe("The length in seconds. Default: 8"),
+    prompt: z.string().describe('The sound to make'),
+    seconds: z
+      .number()
+      .min(1)
+      .max(30)
+      .optional()
+      .describe('The length in seconds. Default: 8'),
   }),
   run: async (ctx) => {
     const result = await ctx.generateAudio({
       adapter: await ctx.keys.adapter(falSound),
       prompt: ctx.input.prompt,
       duration: ctx.input.seconds ?? 8,
-    });
-    return `Made the sound effect with ${result.model}. The user has the audio.`;
+    })
+    return `Made the sound effect with ${result.model}. The user has the audio.`
   },
-});
+})
diff --git a/examples/harness-cli-batman/src/screen/batman-art.ts b/examples/harness-cli-batman/src/screen/batman-art.ts
index 46f979bbc0..58bfad5a67 100644
--- a/examples/harness-cli-batman/src/screen/batman-art.ts
+++ b/examples/harness-cli-batman/src/screen/batman-art.ts
@@ -1,13 +1,13 @@
 /** ASCII from asciiart.eu. Initials stay on the drawings (snd, z_M). */
 
 function padArt(lines: ReadonlyArray<string>) {
-  const width = Math.max(0, ...lines.map((line) => line.length));
-  return lines.map((line) => line.padEnd(width));
+  const width = Math.max(0, ...lines.map((line) => line.length))
+  return lines.map((line) => line.padEnd(width))
 }
 
 /** Bat symbol. Joan Stark / unknown, 60 x 21. asciiart.eu/art/f5be3a8046b61e0a */
 export const SYMBOL = padArt([
-  "                   ,.ood888888888888boo.,",
+  '                   ,.ood888888888888boo.,',
   '              .od888P^""            ""^Y888bo.',
   "          .od8P''   ..oood88888888booo.    ``Y8bo.",
   '       .odP\'"  .ood8888888888888888888888boo.  "`Ybo.',
@@ -16,52 +16,52 @@ export const SYMBOL = padArt([
   "  .8P  d88'     8888888888P      Y8888888888     `88b  Y8.",
   " d8' .d8'       `Y88888888'      `88888888P'       `8b. `8b",
   '.8P .88P            """"            """"            Y88. Y8.',
-  "88  888                                              888  88",
-  "88  888                                              888  88",
-  "88  888.        ..                        ..        .888  88",
+  '88  888                                              888  88',
+  '88  888                                              888  88',
+  '88  888.        ..                        ..        .888  88',
   "`8b `88b,     d8888b.od8bo.      .od8bo.d8888b     ,d88' d8'",
   " Y8. `Y88.    8888888888888b    d8888888888888    .88P' .8P",
   "  `8b  Y88b.  `88888888888888  88888888888888'  .d88P  d8'",
-  "    Y8.  ^Y88bod8888888888888..8888888888888bod88P^  .8P",
+  '    Y8.  ^Y88bod8888888888888..8888888888888bod88P^  .8P',
   "     `Y8.   ^Y888888888888888LS888888888888888P^   .8P'",
   "       `^Yb.,  `^^Y8888888888888888888888P^^'  ,.dP^'",
   "          `^Y8b..   ``^^^Y88888888P^^^'    ..d8P^'",
   "              `^Y888bo.,            ,.od888P^'",
   '                   "`^^Y888888888888P^^\'"',
-]);
+])
 
 /** Standing Batman. Shanaka Dias (snd), 24 x 22. asciiart.eu/art/59a93c84f7c5a9f6 */
 export const STAND = padArt([
-  "          .  .",
-  "          |\\_|\\",
-  "          | a_a\\",
+  '          .  .',
+  '          |\\_|\\',
+  '          | a_a\\',
   '          | | "]',
   "      ____| '-\\___",
   "     /.----.___.-'\\",
-  "    //        _    \\",
-  "   //   .-. (~v~) /|",
+  '    //        _    \\',
+  '   //   .-. (~v~) /|',
   "  |'|  /\\:  .--  / \\",
-  " // |-/  \\_/____/\\/~|",
-  "|/  \\ |  []_|_|_] \\ |",
-  "| \\  | \\ |___   _\\ ]_}",
+  ' // |-/  \\_/____/\\/~|',
+  '|/  \\ |  []_|_|_] \\ |',
+  '| \\  | \\ |___   _\\ ]_}',
   "| |  '-' /   '.'  |",
-  "| |     /    /|:  | ",
-  "| |     |   / |:  /\\",
-  "| |     /  /  |  /  \\",
-  "| |    |  /  /  |    \\",
-  "\\ |    |/\\/  |/|/\\    \\",
-  " \\|\\ |\\|  |  | / /\\/\\__\\",
-  "  \\ \\| | /   | |__",
-  "snd    / |   |____)",
-  "       |_/",
-]);
+  '| |     /    /|:  | ',
+  '| |     |   / |:  /\\',
+  '| |     /  /  |  /  \\',
+  '| |    |  /  /  |    \\',
+  '\\ |    |/\\/  |/|/\\    \\',
+  ' \\|\\ |\\|  |  | / /\\/\\__\\',
+  '  \\ \\| | /   | |__',
+  'snd    / |   |____)',
+  '       |_/',
+])
 
 /** Batman with the cape out. Shanaka Dias (snd), 45 x 26. asciiart.eu/art/39ab1850ef7b32a8 */
 export const CAPE = padArt([
-  "           |    |              _.-7",
-  "           |\\.-.|             ( ,(_",
-  "           | a a|              \\\\  \\,",
-  "           ) [\"||          _.--' \\  \\\\",
+  '           |    |              _.-7',
+  '           |\\.-.|             ( ,(_',
+  '           | a a|              \\\\  \\,',
+  '           ) ["||          _.--\' \\  \\\\',
   "        .-'  '-''-..____.-'    ___)  )\\",
   "       F   _/-``-.__;-.-.--`--' . .' \\_L_",
   "      |   l  {~~} ,_\\  '.'.      ` __.' )\\",
@@ -84,51 +84,53 @@ export const CAPE = padArt([
   "     \\ .-'  ( L `._ '\\ '._ (",
   "snd  /'  |  /  '-._\\      ''\\",
   "         `-'",
-]);
+])
 
 /** Batman with pointed ears. z_M, 48 x 25. asciiart.eu/art/7b11b14980469ed1 */
 export const EARS = padArt([
-  "                T\\ T\\",
-  "                | \\| \\",
-  "                |  |  :",
-  "           _____I__I  |",
+  '                T\\ T\\',
+  '                | \\| \\',
+  '                |  |  :',
+  '           _____I__I  |',
   "         .'            '.",
   "       .'                '",
   "       |   ..             '",
-  "       |  /__.            |",
+  '       |  /__.            |',
   "       :.' -'             |",
-  "      /__.                |",
-  "     /__, \\               |",
-  "        |__\\        _|    |",
+  '      /__.                |',
+  '     /__, \\               |',
+  '        |__\\        _|    |',
   "        :  '\\     .'|     |",
-  "        |___|_,,,/  |     |    _..--.",
+  '        |___|_,,,/  |     |    _..--.',
   "     ,--_-   |     /'      \\../ /  /\\\\",
   "    ,'|_ I---|    7    ,,,_/ / ,  / _\\\\",
   "  ,-- 7 \\|  / ___..,,/   /  ,  ,_/   '-----.",
   " /   ,   \\  |/  ,____,,,__,,__/            '\\",
-  ",   ,     \\__,,/                             |",
+  ',   ,     \\__,,/                             |',
   "| '.       _..---.._                         !.",
   "! |      .' z_M__s. '.                        |",
   ".:'      | (-_ _--')  :          L            !",
   ".'.       '.  Y    _.'             \\,         :",
   " .          '-----'                 !          .",
-  " .           /  \\                   .          .",
-]);
+  ' .           /  \\                   .          .',
+])
 
 /** The three figure poses, padded to one size so the animation does not jump. */
-export const POSES = padFrames([STAND, CAPE, EARS]);
+export const POSES = padFrames([STAND, CAPE, EARS])
 
 function padFrames(frames: ReadonlyArray<ReadonlyArray<string>>) {
-  const width = Math.max(...frames.map((frame) => frame[0]?.length ?? 0));
-  const height = Math.max(...frames.map((frame) => frame.length));
+  const width = Math.max(...frames.map((frame) => frame[0]?.length ?? 0))
+  const height = Math.max(...frames.map((frame) => frame.length))
   return frames.map((frame) => {
-    const left = Math.floor((width - (frame[0]?.length ?? 0)) / 2);
-    const top = Math.floor((height - frame.length) / 2);
+    const left = Math.floor((width - (frame[0]?.length ?? 0)) / 2)
+    const top = Math.floor((height - frame.length) / 2)
     const rows = [
-      ...Array.from({ length: top }, () => " ".repeat(width)),
+      ...Array.from({ length: top }, () => ' '.repeat(width)),
       ...frame.map((line) => line.padStart(line.length + left).padEnd(width)),
-      ...Array.from({ length: height - top - frame.length }, () => " ".repeat(width)),
-    ];
-    return rows;
-  });
+      ...Array.from({ length: height - top - frame.length }, () =>
+        ' '.repeat(width),
+      ),
+    ]
+    return rows
+  })
 }
diff --git a/examples/harness-cli-batman/src/screen/commands.ts b/examples/harness-cli-batman/src/screen/commands.ts
index 3f6f84c683..cda1416676 100644
--- a/examples/harness-cli-batman/src/screen/commands.ts
+++ b/examples/harness-cli-batman/src/screen/commands.ts
@@ -1,23 +1,24 @@
 /** The commands of the screen itself. The harness adds its own to the list. */
 export const SCREEN_COMMANDS = [
   {
-    name: "connect",
-    description: "Light the signal: connect a model provider, Notion, or Linear",
+    name: 'connect',
+    description:
+      'Light the signal: connect a model provider, Notion, or Linear',
   },
-  { name: "disconnect", description: "Cut a key or a sign-in" },
-  { name: "model", description: "Pick which mind patrols tonight" },
-  { name: "effort", description: "Pick how hard the model thinks" },
-  { name: "resume", description: "Continue a saved session" },
-  { name: "mic", description: "Pick the microphone" },
-  { name: "open", description: "Open a media file (default: the last one)" },
-  { name: "play", description: "Play an audio or video file" },
+  { name: 'disconnect', description: 'Cut a key or a sign-in' },
+  { name: 'model', description: 'Pick which mind patrols tonight' },
+  { name: 'effort', description: 'Pick how hard the model thinks' },
+  { name: 'resume', description: 'Continue a saved session' },
+  { name: 'mic', description: 'Pick the microphone' },
+  { name: 'open', description: 'Open a media file (default: the last one)' },
+  { name: 'play', description: 'Play an audio or video file' },
   {
-    name: "voice",
-    description: "Send a recorded voice message: /voice note.m4a",
+    name: 'voice',
+    description: 'Send a recorded voice message: /voice note.m4a',
   },
-  { name: "help", description: "Show the commands and the voice tips" },
-  { name: "exit", description: "Return to the cave" },
-];
+  { name: 'help', description: 'Show the commands and the voice tips' },
+  { name: 'exit', description: 'Return to the cave' },
+]
 
 // Commands that need text after the name: Enter in the list fills the name.
-export const TAKES_INPUT = new Set(["voice"]);
+export const TAKES_INPUT = new Set(['voice'])
diff --git a/examples/harness-cli-batman/src/screen/editor.ts b/examples/harness-cli-batman/src/screen/editor.ts
index 85bd990524..b85c6fdd81 100644
--- a/examples/harness-cli-batman/src/screen/editor.ts
+++ b/examples/harness-cli-batman/src/screen/editor.ts
@@ -1,25 +1,27 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { useReducer, useRef } from "react";
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { useReducer, useRef } from 'react'
 
 // The lines you sent, for the up and down arrows, kept next to the sign-ins.
-const historyFile = join(homedir(), ".tanstack-harness-example", "history.json");
-const HISTORY_SIZE = 200;
+const historyFile = join(homedir(), '.tanstack-harness-example', 'history.json')
+const HISTORY_SIZE = 200
 
 function loadHistory() {
   try {
-    const parsed: unknown = JSON.parse(readFileSync(historyFile, "utf8"));
-    return Array.isArray(parsed) ? parsed.filter((item) => typeof item === "string") : [];
+    const parsed: unknown = JSON.parse(readFileSync(historyFile, 'utf8'))
+    return Array.isArray(parsed)
+      ? parsed.filter((item) => typeof item === 'string')
+      : []
   } catch {
-    return [];
+    return []
   }
 }
 
 function saveHistory(lines: ReadonlyArray<string>) {
   try {
-    mkdirSync(dirname(historyFile), { recursive: true });
-    writeFileSync(historyFile, JSON.stringify(lines.slice(-HISTORY_SIZE)));
+    mkdirSync(dirname(historyFile), { recursive: true })
+    writeFileSync(historyFile, JSON.stringify(lines.slice(-HISTORY_SIZE)))
   } catch {
     // ponytail: history is a convenience. A failed write loses it, no more.
   }
@@ -27,12 +29,12 @@ function saveHistory(lines: ReadonlyArray<string>) {
 
 /** The input line. `hidden`: it holds a secret (a key), shown as dots. */
 export interface Line {
-  text: string;
-  cursor: number;
-  hidden: boolean;
+  text: string
+  cursor: number
+  hidden: boolean
 }
 
-const empty: Line = { text: "", cursor: 0, hidden: false };
+const empty: Line = { text: '', cursor: 0, hidden: false }
 
 /**
  * The input line of the screen: typing at the cursor, the arrow keys, and
@@ -40,85 +42,92 @@ const empty: Line = { text: "", cursor: 0, hidden: false };
  * before React renders still sees the keys before it.
  */
 export function useLineEditor() {
-  const current = useRef<Line>(empty);
-  const [, render] = useReducer((count: number) => count + 1, 0);
-  const history = useRef<Array<string>>(loadHistory());
+  const current = useRef<Line>(empty)
+  const [, render] = useReducer((count: number) => count + 1, 0)
+  const history = useRef<Array<string>>(loadHistory())
   // While you go through the history: where you are, and the line you had.
-  const browsing = useRef<{ index: number; draft: string } | undefined>(undefined);
+  const browsing = useRef<{ index: number; draft: string } | undefined>(
+    undefined,
+  )
   const show = (line: Line) => {
-    current.current = line;
-    render();
-  };
+    current.current = line
+    render()
+  }
   const edit = (line: Line) => {
-    browsing.current = undefined;
-    show(line);
-  };
-  const showText = (text: string) => show({ text, cursor: text.length, hidden: false });
+    browsing.current = undefined
+    show(line)
+  }
+  const showText = (text: string) =>
+    show({ text, cursor: text.length, hidden: false })
 
   return {
     get line() {
-      return current.current;
+      return current.current
     },
     /** The line came from the history (the arrows), not from typing. */
     get browsing() {
-      return browsing.current !== undefined;
+      return browsing.current !== undefined
     },
     /** Type or paste at the cursor. A hidden line stays hidden until it is empty. */
     insert: (text: string, hidden = false) => {
-      const line = current.current;
+      const line = current.current
       edit({
-        text: line.text.slice(0, line.cursor) + text + line.text.slice(line.cursor),
+        text:
+          line.text.slice(0, line.cursor) + text + line.text.slice(line.cursor),
         cursor: line.cursor + text.length,
-        hidden: hidden || (line.hidden && line.text !== ""),
-      });
+        hidden: hidden || (line.hidden && line.text !== ''),
+      })
     },
     /** Delete the character before the cursor. */
     backspace: () => {
-      const line = current.current;
-      if (line.cursor === 0) return;
+      const line = current.current
+      if (line.cursor === 0) return
       edit({
         ...line,
-        text: line.text.slice(0, line.cursor - 1) + line.text.slice(line.cursor),
+        text:
+          line.text.slice(0, line.cursor - 1) + line.text.slice(line.cursor),
         cursor: line.cursor - 1,
-      });
+      })
     },
     /** Move the cursor by `by` characters, or to the start or the end. */
-    move: (by: number | "start" | "end") => {
-      const line = current.current;
-      const target = by === "start" ? 0 : by === "end" ? line.text.length : line.cursor + by;
-      show({ ...line, cursor: Math.max(0, Math.min(line.text.length, target)) });
+    move: (by: number | 'start' | 'end') => {
+      const line = current.current
+      const target =
+        by === 'start' ? 0 : by === 'end' ? line.text.length : line.cursor + by
+      show({ ...line, cursor: Math.max(0, Math.min(line.text.length, target)) })
     },
     /** Replace the line. The cursor goes to `cursor`, or to the end. */
-    set: (text: string, cursor = text.length) => edit({ text, cursor, hidden: false }),
+    set: (text: string, cursor = text.length) =>
+      edit({ text, cursor, hidden: false }),
     clear: () => edit(empty),
     /** Keep a sent line for the up arrow. */
     remember: (text: string) => {
-      const trimmed = text.trim();
-      if (trimmed === "" || history.current.at(-1) === trimmed) return;
-      history.current.push(trimmed);
-      saveHistory(history.current);
+      const trimmed = text.trim()
+      if (trimmed === '' || history.current.at(-1) === trimmed) return
+      history.current.push(trimmed)
+      saveHistory(history.current)
     },
     /** The up arrow: the sent line before the one shown. */
     older: () => {
-      const lines = history.current;
-      if (lines.length === 0) return;
-      const at = browsing.current;
-      const index = at ? Math.max(0, at.index - 1) : lines.length - 1;
-      browsing.current = { index, draft: at?.draft ?? current.current.text };
-      showText(lines[index] ?? "");
+      const lines = history.current
+      if (lines.length === 0) return
+      const at = browsing.current
+      const index = at ? Math.max(0, at.index - 1) : lines.length - 1
+      browsing.current = { index, draft: at?.draft ?? current.current.text }
+      showText(lines[index] ?? '')
     },
     /** The down arrow: the next sent line, then the line you had typed. */
     newer: () => {
-      const at = browsing.current;
-      if (!at) return;
+      const at = browsing.current
+      if (!at) return
       if (at.index >= history.current.length - 1) {
-        browsing.current = undefined;
-        showText(at.draft);
-        return;
+        browsing.current = undefined
+        showText(at.draft)
+        return
       }
-      const index = at.index + 1;
-      browsing.current = { ...at, index };
-      showText(history.current[index] ?? "");
+      const index = at.index + 1
+      browsing.current = { ...at, index }
+      showText(history.current[index] ?? '')
     },
-  };
+  }
 }
diff --git a/examples/harness-cli-batman/src/screen/footer.tsx b/examples/harness-cli-batman/src/screen/footer.tsx
index 213bb08bdd..b69e336fd9 100644
--- a/examples/harness-cli-batman/src/screen/footer.tsx
+++ b/examples/harness-cli-batman/src/screen/footer.tsx
@@ -1,14 +1,14 @@
-import React from "react";
-import { Box, Text } from "ink";
-import { REASONING_LEVELS } from "@tanstack/ai";
-import { clampReasoningLevel } from "@tanstack/ai-models";
-import { useSelector } from "@tanstack/react-store";
-import { modelInfo, reasons } from "../harness";
-import { PROVIDER_KEYS, USAGE, providerKeysIn, usageIn } from "./keys";
-import { ACCENT, compact } from "./theme";
-import type { SessionView } from "@tanstack/ai-harness/view";
+import React from 'react'
+import { Box, Text } from 'ink'
+import { REASONING_LEVELS } from '@tanstack/ai'
+import { clampReasoningLevel } from '@tanstack/ai-models'
+import { useSelector } from '@tanstack/react-store'
+import { modelInfo, reasons } from '../harness'
+import { PROVIDER_KEYS, USAGE, providerKeysIn, usageIn } from './keys'
+import { ACCENT, compact } from './theme'
+import type { SessionView } from '@tanstack/ai-harness/view'
 
-const BAR = 10;
+const BAR = 10
 
 /**
  * The status bar at the bottom: the model, how much of its context the
@@ -17,60 +17,68 @@ const BAR = 10;
  */
 export function Footer({ view }: { view: SessionView }) {
   const model = useSelector(view.store, (state) =>
-    String(state.config.find((entry) => entry.key === "model")?.value ?? "?"),
-  );
+    String(state.config.find((entry) => entry.key === 'model')?.value ?? '?'),
+  )
   const effort = useSelector(
     view.store,
-    (state) => state.config.find((entry) => entry.key === "effort")?.value,
-  );
+    (state) => state.config.find((entry) => entry.key === 'effort')?.value,
+  )
   // The plugin states themselves, so the bar renders only when they change.
-  const usageState = useSelector(view.store, (state) => state.plugins[USAGE]);
-  const keysState = useSelector(view.store, (state) => state.plugins[PROVIDER_KEYS]);
-  const usage = usageIn(usageState);
-  const keys = providerKeysIn(keysState);
-  const info = modelInfo[model];
-  const window = info?.record.contextWindow;
+  const usageState = useSelector(view.store, (state) => state.plugins[USAGE])
+  const keysState = useSelector(
+    view.store,
+    (state) => state.plugins[PROVIDER_KEYS],
+  )
+  const usage = usageIn(usageState)
+  const keys = providerKeysIn(keysState)
+  const info = modelInfo[model]
+  const window = info?.record.contextWindow
   // The level the model gets: the adapter moves an effort the model does not
   // have to the nearest one it has.
-  const level = REASONING_LEVELS.find((name) => name === effort);
+  const level = REASONING_LEVELS.find((name) => name === effort)
   const shownEffort =
-    info && level && reasons(model) ? clampReasoningLevel(info.record, level) : undefined;
-  const share = window ? Math.min(1, usage.contextTokens / window) : 0;
-  const filled = Math.round(share * BAR);
-  const barColor = share > 0.8 ? "red" : share > 0.5 ? "yellow" : "green";
+    info && level && reasons(model)
+      ? clampReasoningLevel(info.record, level)
+      : undefined
+  const share = window ? Math.min(1, usage.contextTokens / window) : 0
+  const filled = Math.round(share * BAR)
+  const barColor = share > 0.8 ? 'red' : share > 0.5 ? 'yellow' : 'green'
   const needsKey =
-    info !== undefined && keys.find((key) => key.id === info.provider)?.state === "missing";
+    info !== undefined &&
+    keys.find((key) => key.id === info.provider)?.state === 'missing'
   // Each group keeps its width, and a group that does not fit goes to the
   // next line.
   return (
     <Box flexWrap="wrap" columnGap={3}>
       <Box flexShrink={0}>
-        <Text color={needsKey ? "red" : ACCENT} bold>{`🦇 ${model}`}</Text>
-        {needsKey ? <Text color="red">{`  (run /connect ${info.provider})`}</Text> : null}
+        <Text color={needsKey ? 'red' : ACCENT} bold>{`🦇 ${model}`}</Text>
+        {needsKey ? (
+          <Text color="red">{`  (run /connect ${info.provider})`}</Text>
+        ) : null}
         {shownEffort ? <Text dimColor>{`  effort ${shownEffort}`}</Text> : null}
       </Box>
       <Box flexShrink={0}>
-        <Text dimColor>{"context "}</Text>
+        <Text dimColor>{'context '}</Text>
         <Text>
           {compact(usage.contextTokens)}
-          {window ? `/${compact(window)}` : ""}
+          {window ? `/${compact(window)}` : ''}
         </Text>
         {window ? (
           <>
             <Text> </Text>
-            <Text color={barColor}>{"▰".repeat(filled)}</Text>
-            <Text dimColor>{"▱".repeat(BAR - filled)}</Text>
+            <Text color={barColor}>{'▰'.repeat(filled)}</Text>
+            <Text dimColor>{'▱'.repeat(BAR - filled)}</Text>
             <Text dimColor>{` ${Math.round(share * 100)}%`}</Text>
           </>
         ) : null}
       </Box>
       <Box flexShrink={0}>
-        <Text dimColor>{"tokens in "}</Text>
+        <Text dimColor>{'tokens in '}</Text>
         <Text>{compact(usage.promptTokens)}</Text>
-        <Text dimColor>{" out "}</Text>
+        <Text dimColor>{' out '}</Text>
         <Text>{compact(usage.completionTokens)}</Text>
       </Box>
       <Text dimColor>{`${usage.turns} model calls`}</Text>
     </Box>
-  );
+  )
 }
diff --git a/examples/harness-cli-batman/src/screen/keys.ts b/examples/harness-cli-batman/src/screen/keys.ts
index df959d8bb1..ccd6c1ae9b 100644
--- a/examples/harness-cli-batman/src/screen/keys.ts
+++ b/examples/harness-cli-batman/src/screen/keys.ts
@@ -1,28 +1,30 @@
-import type { features } from "../harness";
+import type { features } from '../harness'
 
 // The names of the `providerKeys()` and `usage()` plugins: their state is in
 // the view's `state.plugins`.
-export const PROVIDER_KEYS = "tanstack/provider-keys";
-export const USAGE = "tanstack/usage";
+export const PROVIDER_KEYS = 'tanstack/provider-keys'
+export const USAGE = 'tanstack/usage'
 
 /** A model provider of `providerKeys()`, and where its key comes from. */
 export interface ProviderKey {
-  id: string;
-  label: string;
-  state: "connected" | "env" | "missing";
+  id: string
+  label: string
+  state: 'connected' | 'env' | 'missing'
 }
 
 function isProviderKey(value: unknown): value is ProviderKey {
   return (
-    typeof value === "object" &&
+    typeof value === 'object' &&
     value !== null &&
-    "id" in value &&
-    typeof value.id === "string" &&
-    "label" in value &&
-    typeof value.label === "string" &&
-    "state" in value &&
-    (value.state === "connected" || value.state === "env" || value.state === "missing")
-  );
+    'id' in value &&
+    typeof value.id === 'string' &&
+    'label' in value &&
+    typeof value.label === 'string' &&
+    'state' in value &&
+    (value.state === 'connected' ||
+      value.state === 'env' ||
+      value.state === 'missing')
+  )
 }
 
 /**
@@ -31,41 +33,47 @@ function isProviderKey(value: unknown): value is ProviderKey {
  * Empty before the plugin reports.
  */
 export function providerKeysIn(saved: unknown) {
-  const isState = typeof saved === "object" && saved !== null && "providers" in saved;
-  if (!isState) return [];
-  const { providers } = saved;
-  return Array.isArray(providers) ? providers.filter(isProviderKey) : [];
+  const isState =
+    typeof saved === 'object' && saved !== null && 'providers' in saved
+  if (!isState) return []
+  const { providers } = saved
+  return Array.isArray(providers) ? providers.filter(isProviderKey) : []
 }
 
 /**
  * Is `feature` on? A feature that needs a key follows the saved keys: any
  * one of its providers with a key turns it on. The rest stay as at startup.
  */
-export function isOn(feature: (typeof features)[number], keys: ReadonlyArray<ProviderKey>) {
-  const followsKeys = feature.providers.length > 0 && keys.length > 0;
-  if (!followsKeys) return feature.on;
-  return keys.some((key) => feature.providers.includes(key.id) && key.state !== "missing");
+export function isOn(
+  feature: (typeof features)[number],
+  keys: ReadonlyArray<ProviderKey>,
+) {
+  const followsKeys = feature.providers.length > 0 && keys.length > 0
+  if (!followsKeys) return feature.on
+  return keys.some(
+    (key) => feature.providers.includes(key.id) && key.state !== 'missing',
+  )
 }
 
 /** The totals of the usage plugin. */
 export interface Usage {
-  turns: number;
-  promptTokens: number;
-  completionTokens: number;
-  contextTokens: number;
+  turns: number
+  promptTokens: number
+  completionTokens: number
+  contextTokens: number
 }
 
 /** The usage plugin state in `saved`, with 0 for anything it has not counted. */
 export function usageIn(saved: unknown): Usage {
   const read = (key: string) => {
-    if (typeof saved !== "object" || saved === null || !(key in saved)) return 0;
-    const value: unknown = Reflect.get(saved, key);
-    return typeof value === "number" ? value : 0;
-  };
+    if (typeof saved !== 'object' || saved === null || !(key in saved)) return 0
+    const value: unknown = Reflect.get(saved, key)
+    return typeof value === 'number' ? value : 0
+  }
   return {
-    turns: read("turns"),
-    promptTokens: read("promptTokens"),
-    completionTokens: read("completionTokens"),
-    contextTokens: read("contextTokens"),
-  };
+    turns: read('turns'),
+    promptTokens: read('promptTokens'),
+    completionTokens: read('completionTokens'),
+    contextTokens: read('contextTokens'),
+  }
 }
diff --git a/examples/harness-cli-batman/src/screen/markdown.ts b/examples/harness-cli-batman/src/screen/markdown.ts
index 1b1b2413d8..dbc0772205 100644
--- a/examples/harness-cli-batman/src/screen/markdown.ts
+++ b/examples/harness-cli-batman/src/screen/markdown.ts
@@ -1,14 +1,14 @@
-import { renderMermaidASCII } from "beautiful-mermaid";
-import { Marked } from "marked";
-import { markedTerminal } from "marked-terminal";
+import { renderMermaidASCII } from 'beautiful-mermaid'
+import { Marked } from 'marked'
+import { markedTerminal } from 'marked-terminal'
 
 // A closed ```mermaid block. An open one (still streaming) stays code.
-const MERMAID = /```mermaid[^\n]*\n([\s\S]*?)```/g;
+const MERMAID = /```mermaid[^\n]*\n([\s\S]*?)```/g
 
 // One parser for each width: marked-terminal wraps text to the width.
-const parsers = new Map<number, Marked>();
+const parsers = new Map<number, Marked>()
 function parserFor(width: number) {
-  let parser = parsers.get(width);
+  let parser = parsers.get(width)
   if (!parser) {
     parser = new Marked(
       markedTerminal({
@@ -23,16 +23,16 @@ function parserFor(width: number) {
           // ponytail: marked-terminal 7 prints the text of a list item as it
           // is, so `**bold**` in a list stays raw. This parses it.
           text(token) {
-            return "tokens" in token && token.tokens
+            return 'tokens' in token && token.tokens
               ? this.parser.parseInline(token.tokens)
-              : token.text;
+              : token.text
           },
         },
       },
-    );
-    parsers.set(width, parser);
+    )
+    parsers.set(width, parser)
   }
-  return parser;
+  return parser
 }
 
 /**
@@ -41,21 +41,24 @@ function parserFor(width: number) {
  * A chart that does not parse stays a code block.
  */
 export function renderMarkdown(text: string, width: number) {
-  const charts: Array<string> = [];
+  const charts: Array<string> = []
   const source = text.replace(MERMAID, (block, code: string) => {
     try {
-      charts.push(renderMermaidASCII(code));
+      charts.push(renderMermaidASCII(code))
       // A plain word marked-terminal keeps as it is, in its own paragraph.
-      return `\n\nMERMAIDCHART${charts.length - 1}\n\n`;
+      return `\n\nMERMAIDCHART${charts.length - 1}\n\n`
     } catch {
-      return block;
+      return block
     }
-  });
+  })
   return (
     parserFor(Math.max(20, width))
       // An open (still streaming) Mermaid block shows as plain code.
-      .parse(source.replace(/```mermaid/g, "```"), { async: false })
-      .replace(/MERMAIDCHART(\d+)/g, (_match, index: string) => charts[Number(index)] ?? "")
+      .parse(source.replace(/```mermaid/g, '```'), { async: false })
+      .replace(
+        /MERMAIDCHART(\d+)/g,
+        (_match, index: string) => charts[Number(index)] ?? '',
+      )
       .trimEnd()
-  );
+  )
 }
diff --git a/examples/harness-cli-batman/src/screen/media.ts b/examples/harness-cli-batman/src/screen/media.ts
index 064ee626f6..6222ed8a3c 100644
--- a/examples/harness-cli-batman/src/screen/media.ts
+++ b/examples/harness-cli-batman/src/screen/media.ts
@@ -1,48 +1,53 @@
-import { spawn } from "node:child_process";
-import { mkdir, writeFile } from "node:fs/promises";
-import { basename, join, resolve } from "node:path";
-import { useEffect, useState } from "react";
-import { assistant } from "../harness";
-import type { MediaPart, SessionView, ViewMessage, ViewPart } from "@tanstack/ai-harness/view";
+import { spawn } from 'node:child_process'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { basename, join, resolve } from 'node:path'
+import { useEffect, useState } from 'react'
+import { assistant } from '../harness'
+import type {
+  MediaPart,
+  SessionView,
+  ViewMessage,
+  ViewPart,
+} from '@tanstack/ai-harness/view'
 
 // ponytail: the CLI's default media folder, `./<harness-name>-media`. A custom
 // ui gets no `--media-dir`, and the CLI does not export `defaultMediaDir`, so
 // this copies its rule. The media id in front of the name keeps names unique.
-export const mediaDir = `${assistant.name.replace(/[^\w.-]+/g, "-").replace(/^[-.]+|-+$/g, "")}-media`;
+export const mediaDir = `${assistant.name.replace(/[^\w.-]+/g, '-').replace(/^[-.]+|-+$/g, '')}-media`
 
 /** A media file the screen saved. `number` is what `/open` and `/play` take. */
 export interface Saved {
-  id: string;
-  number: number;
-  kind: string;
-  name: string;
-  path?: string;
-  error?: string;
+  id: string
+  number: number
+  kind: string
+  name: string
+  path?: string
+  error?: string
 }
 
 /** Write the bytes of a media file into `mediaDir`, and return the path. */
 async function saveMedia(part: MediaPart) {
-  await mkdir(mediaDir, { recursive: true });
-  const path = join(mediaDir, `${part.id}-${basename(part.name)}`);
-  await writeFile(path, await part.load());
-  return path;
+  await mkdir(mediaDir, { recursive: true })
+  const path = join(mediaDir, `${part.id}-${basename(part.name)}`)
+  await writeFile(path, await part.load())
+  return path
 }
 
 /** Add the media parts of `parts` to `into`, also the ones of child agents. */
 function collectMedia(parts: ReadonlyArray<ViewPart>, into: Array<MediaPart>) {
   for (const part of parts) {
-    if (part.type === "media") into.push(part);
-    if (part.type === "agent") collectMedia(part.parts, into);
+    if (part.type === 'media') into.push(part)
+    if (part.type === 'agent') collectMedia(part.parts, into)
   }
 }
 
 /** The media files that the agents made, from the assistant messages. */
 function generatedMedia(messages: ReadonlyArray<ViewMessage>) {
-  const media: Array<MediaPart> = [];
+  const media: Array<MediaPart> = []
   for (const message of messages) {
-    if (message.role === "assistant") collectMedia(message.parts, media);
+    if (message.role === 'assistant') collectMedia(message.parts, media)
   }
-  return media;
+  return media
 }
 
 /**
@@ -51,66 +56,70 @@ function generatedMedia(messages: ReadonlyArray<ViewMessage>) {
  * neither saved nor failed yet?
  */
 export function useSavedMedia(view: SessionView, messages: Array<ViewMessage>) {
-  const [saved, setSaved] = useState<ReadonlyArray<Saved>>([]);
+  const [saved, setSaved] = useState<ReadonlyArray<Saved>>([])
   const [seen] = useState(
-    () => new Set(generatedMedia(view.store.get().messages).map((part) => part.id)),
-  );
+    () =>
+      new Set(generatedMedia(view.store.get().messages).map((part) => part.id)),
+  )
   useEffect(() => {
     for (const part of generatedMedia(messages)) {
-      if (seen.has(part.id)) continue;
-      seen.add(part.id);
-      const number = seen.size;
+      if (seen.has(part.id)) continue
+      seen.add(part.id)
+      const number = seen.size
       const update = (change: Partial<Saved>) =>
         setSaved((current) =>
-          current.map((item) => (item.id === part.id ? { ...item, ...change } : item)),
-        );
+          current.map((item) =>
+            item.id === part.id ? { ...item, ...change } : item,
+          ),
+        )
       setSaved((current) => [
         ...current,
         { id: part.id, number, kind: part.kind, name: part.name },
-      ]);
+      ])
       saveMedia(part).then(
         (path) => update({ path }),
         (error: unknown) =>
           update({
             error: error instanceof Error ? error.message : String(error),
           }),
-      );
+      )
     }
-  }, [messages, seen]);
+  }, [messages, seen])
   const saving = (id: string) => {
-    if (!seen.has(id)) return true;
-    const item = saved.find((entry) => entry.id === id);
-    return item !== undefined && !item.path && !item.error;
-  };
-  return { saved, saving };
+    if (!seen.has(id)) return true
+    const item = saved.find((entry) => entry.id === id)
+    return item !== undefined && !item.path && !item.error
+  }
+  return { saved, saving }
 }
 
 /** Start a program without a shell. The screen still shows the path on error. */
 function launch(command: string, args: Array<string>) {
-  const child = spawn(command, args, { stdio: "ignore", detached: true });
-  child.on("error", () => {});
-  child.unref();
+  const child = spawn(command, args, { stdio: 'ignore', detached: true })
+  child.on('error', () => {})
+  child.unref()
 }
 
 /** Open a link or a file with the default app. No shell is involved. */
 export function openExternal(target: string) {
-  if (process.platform === "win32") {
+  if (process.platform === 'win32') {
     // Not `cmd /c start`: cmd would read `&` in a URL as a command separator.
-    if (/^https?:\/\//.test(target)) launch("rundll32", ["url.dll,FileProtocolHandler", target]);
-    else launch("explorer", [resolve(target)]);
-    return;
+    if (/^https?:\/\//.test(target))
+      launch('rundll32', ['url.dll,FileProtocolHandler', target])
+    else launch('explorer', [resolve(target)])
+    return
   }
-  launch(process.platform === "darwin" ? "open" : "xdg-open", [target]);
+  launch(process.platform === 'darwin' ? 'open' : 'xdg-open', [target])
 }
 
 /** Play audio or video with ffplay, which comes with ffmpeg. */
 export function play(item: Saved & { path: string }) {
-  const window = item.kind === "video" ? [] : ["-nodisp"];
-  launch(process.env.FFPLAY_PATH || "ffplay", [
+  const window = item.kind === 'video' ? [] : ['-nodisp']
+  launch(process.env.FFPLAY_PATH || 'ffplay', [
     ...window,
-    "-autoexit",
-    "-loglevel",
-    "quiet",
+    '-autoexit',
+    '-loglevel',
+    'quiet',
     item.path,
-  ]);
+  ])
 }
diff --git a/examples/harness-cli-batman/src/screen/menu.tsx b/examples/harness-cli-batman/src/screen/menu.tsx
index 43abd4f670..94f3c7b52e 100644
--- a/examples/harness-cli-batman/src/screen/menu.tsx
+++ b/examples/harness-cli-batman/src/screen/menu.tsx
@@ -1,17 +1,17 @@
-import React from "react";
-import { Box, Text } from "ink";
-import { ACCENT } from "./theme";
+import React from 'react'
+import { Box, Text } from 'ink'
+import { ACCENT } from './theme'
 
 /** One row of the command list or of a picker. */
 export interface MenuItem {
-  id: string;
-  label: string;
-  detail?: string;
+  id: string
+  label: string
+  detail?: string
   /** The current choice, for example the model in use. */
-  current?: boolean;
+  current?: boolean
 }
 
-const VISIBLE = 8;
+const VISIBLE = 8
 
 /**
  * A list you move through with the arrow keys: the `/` command list, or a
@@ -24,36 +24,44 @@ export function Menu({
   selected,
   hint,
 }: {
-  title?: string;
-  items: ReadonlyArray<MenuItem>;
-  selected: number;
-  hint: string;
+  title?: string
+  items: ReadonlyArray<MenuItem>
+  selected: number
+  hint: string
 }) {
-  const start = Math.max(0, Math.min(selected - Math.floor(VISIBLE / 2), items.length - VISIBLE));
-  const shown = items.slice(start, start + VISIBLE);
-  const width = Math.max(...items.map((item) => item.label.length), 8);
+  const start = Math.max(
+    0,
+    Math.min(selected - Math.floor(VISIBLE / 2), items.length - VISIBLE),
+  )
+  const shown = items.slice(start, start + VISIBLE)
+  const width = Math.max(...items.map((item) => item.label.length), 8)
   return (
-    <Box flexDirection="column" borderStyle="round" borderColor="gray" paddingX={1}>
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor="gray"
+      paddingX={1}
+    >
       {title ? <Text bold>{title}</Text> : null}
       {shown.map((item, index) => {
-        const isSelected = start + index === selected;
+        const isSelected = start + index === selected
         return (
           <Box key={item.id}>
             <Box flexShrink={0}>
               <Text color={isSelected ? ACCENT : undefined} bold={isSelected}>
-                {`${isSelected ? "🦇" : " "} ${item.label.padEnd(width)}`}
+                {`${isSelected ? '🦇' : ' '} ${item.label.padEnd(width)}`}
               </Text>
             </Box>
-            <Text color={item.current ? "green" : "gray"} wrap="truncate-end">
-              {`  ${item.current ? "● " : ""}${item.detail ?? ""}`}
+            <Text color={item.current ? 'green' : 'gray'} wrap="truncate-end">
+              {`  ${item.current ? '● ' : ''}${item.detail ?? ''}`}
             </Text>
           </Box>
-        );
+        )
       })}
       {items.length > VISIBLE ? (
         <Text dimColor>{`  ${selected + 1} of ${items.length}`}</Text>
       ) : null}
       <Text dimColor>{hint}</Text>
     </Box>
-  );
+  )
 }
diff --git a/examples/harness-cli-batman/src/screen/parts.tsx b/examples/harness-cli-batman/src/screen/parts.tsx
index 04be383e5d..b9c3cf36a8 100644
--- a/examples/harness-cli-batman/src/screen/parts.tsx
+++ b/examples/harness-cli-batman/src/screen/parts.tsx
@@ -1,60 +1,66 @@
-import { basename } from "node:path";
-import React, { useMemo } from "react";
-import { Box, Spacer, Text, useAnimation } from "ink";
-import { renderMarkdown } from "./markdown";
-import { ACCENT, KIND_COLOR, SPINNER } from "./theme";
+import { basename } from 'node:path'
+import React, { useMemo } from 'react'
+import { Box, Spacer, Text, useAnimation } from 'ink'
+import { renderMarkdown } from './markdown'
+import { ACCENT, KIND_COLOR, SPINNER } from './theme'
 import type {
   AgentPart,
   MediaPart,
   ToolCallPart,
   ViewMessage,
   ViewPart,
-} from "@tanstack/ai-harness/view";
-import type { Saved } from "./media";
+} from '@tanstack/ai-harness/view'
+import type { Saved } from './media'
 
-export function Spinner({ color = "yellow" }: { color?: string }) {
-  const { frame } = useAnimation({ interval: 90 });
-  return <Text color={color}>{SPINNER[frame % SPINNER.length]}</Text>;
+export function Spinner({ color = 'yellow' }: { color?: string }) {
+  const { frame } = useAnimation({ interval: 90 })
+  return <Text color={color}>{SPINNER[frame % SPINNER.length]}</Text>
 }
 
 function textOf(parts: ReadonlyArray<ViewPart>) {
-  return parts.map((part) => (part.type === "text" ? part.text : "")).join("");
+  return parts.map((part) => (part.type === 'text' ? part.text : '')).join('')
 }
 
 /** A short one-line view of tool arguments. */
 function argsPreview(call: ToolCallPart) {
   const text =
-    typeof call.args === "object" && call.args !== null
+    typeof call.args === 'object' && call.args !== null
       ? Object.values(call.args)
-          .filter((value) => typeof value === "string")
-          .join(", ")
-      : "";
-  const line = text.replace(/\s+/g, " ").trim();
-  return line.length > 70 ? `${line.slice(0, 70)}...` : line;
+          .filter((value) => typeof value === 'string')
+          .join(', ')
+      : ''
+  const line = text.replace(/\s+/g, ' ').trim()
+  return line.length > 70 ? `${line.slice(0, 70)}...` : line
 }
 
-function ToolLine({ call, indent = 2 }: { call: ToolCallPart; indent?: number }) {
+function ToolLine({
+  call,
+  indent = 2,
+}: {
+  call: ToolCallPart
+  indent?: number
+}) {
   const icon =
-    call.status === "running" ? (
+    call.status === 'running' ? (
       <Spinner />
-    ) : call.status === "done" ? (
+    ) : call.status === 'done' ? (
       <Text color="green">✓</Text>
-    ) : call.status === "failed" ? (
+    ) : call.status === 'failed' ? (
       <Text color="red">✗</Text>
     ) : (
       <Text color="magenta">?</Text>
-    );
-  const preview = argsPreview(call);
+    )
+  const preview = argsPreview(call)
   return (
     <Box marginLeft={indent}>
       {icon}
       <Text color="yellow">{` ${call.name}`}</Text>
       {preview ? <Text dimColor>{`  ${preview}`}</Text> : null}
-      {call.status === "needs-approval" ? (
+      {call.status === 'needs-approval' ? (
         <Text color="magenta"> waits for your approval</Text>
       ) : null}
     </Box>
-  );
+  )
 }
 
 function MediaLine({
@@ -62,23 +68,27 @@ function MediaLine({
   saved,
   indent = 2,
 }: {
-  part: MediaPart;
-  saved: ReadonlyArray<Saved>;
-  indent?: number;
+  part: MediaPart
+  saved: ReadonlyArray<Saved>
+  indent?: number
 }) {
-  const item = saved.find((entry) => entry.id === part.id);
-  const color = KIND_COLOR[part.kind] ?? "white";
+  const item = saved.find((entry) => entry.id === part.id)
+  const color = KIND_COLOR[part.kind] ?? 'white'
   return (
     <Box marginLeft={indent}>
       <Text color={color} bold>
-        {`▣ ${item ? `${item.number} ` : ""}${part.kind}`}
+        {`▣ ${item ? `${item.number} ` : ''}${part.kind}`}
       </Text>
       <Text>{`  ${part.name}`}</Text>
       {item?.path ? <Text dimColor>{`  -> ${item.path}`}</Text> : null}
-      {item?.error ? <Text color="red">{`  not saved: ${item.error}`}</Text> : null}
-      {item && !item.path && !item.error ? <Text dimColor> saving...</Text> : null}
+      {item?.error ? (
+        <Text color="red">{`  not saved: ${item.error}`}</Text>
+      ) : null}
+      {item && !item.path && !item.error ? (
+        <Text dimColor> saving...</Text>
+      ) : null}
     </Box>
-  );
+  )
 }
 
 /**
@@ -86,23 +96,39 @@ function MediaLine({
  * status, its last tool calls, its media, and its output. While it runs, the
  * last 4 lines show. When it ends, the last 15 lines of its answer stay.
  */
-function Agent({ part, saved }: { part: AgentPart; saved: ReadonlyArray<Saved> }) {
+function Agent({
+  part,
+  saved,
+}: {
+  part: AgentPart
+  saved: ReadonlyArray<Saved>
+}) {
   const lines = textOf(part.parts)
-    .split("\n")
+    .split('\n')
     .map((line) => line.trimEnd())
-    .filter((line) => line.trim() !== "");
-  const running = part.status === "running";
-  const output = running ? lines.slice(-4) : lines.slice(-15);
-  const calls = part.parts.flatMap((inner) => (inner.type === "tool-call" ? [inner] : []));
-  const media = part.parts.flatMap((inner) => (inner.type === "media" ? [inner] : []));
-  const color = part.status === "failed" ? "red" : running ? "yellow" : "green";
+    .filter((line) => line.trim() !== '')
+  const running = part.status === 'running'
+  const output = running ? lines.slice(-4) : lines.slice(-15)
+  const calls = part.parts.flatMap((inner) =>
+    inner.type === 'tool-call' ? [inner] : [],
+  )
+  const media = part.parts.flatMap((inner) =>
+    inner.type === 'media' ? [inner] : [],
+  )
+  const color = part.status === 'failed' ? 'red' : running ? 'yellow' : 'green'
   return (
-    <Box flexDirection="column" borderStyle="round" borderColor={color} paddingX={1} marginLeft={2}>
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={color}
+      paddingX={1}
+      marginLeft={2}
+    >
       <Box>
         {running ? (
           <Spinner color={color} />
         ) : (
-          <Text color={color}>{part.status === "done" ? "✓" : "✗"}</Text>
+          <Text color={color}>{part.status === 'done' ? '✓' : '✗'}</Text>
         )}
         <Text bold>{` ${part.name}`}</Text>
         <Spacer />
@@ -121,17 +147,17 @@ function Agent({ part, saved }: { part: AgentPart; saved: ReadonlyArray<Saved> }
       ))}
       {part.error ? <Text color="red">{part.error}</Text> : null}
     </Box>
-  );
+  )
 }
 
 /** The model's text as markdown, `width` columns wide. */
 function Markdown({ text, width }: { text: string; width: number }) {
-  const shown = useMemo(() => renderMarkdown(text, width), [text, width]);
+  const shown = useMemo(() => renderMarkdown(text, width), [text, width])
   return (
     <Box marginLeft={2}>
       <Text>{shown}</Text>
     </Box>
-  );
+  )
 }
 
 function Part({
@@ -139,27 +165,27 @@ function Part({
   saved,
   width,
 }: {
-  part: ViewPart;
-  saved: ReadonlyArray<Saved>;
-  width: number;
+  part: ViewPart
+  saved: ReadonlyArray<Saved>
+  width: number
 }) {
   switch (part.type) {
-    case "text":
-      return <Markdown text={part.text} width={width - 2} />;
-    case "reasoning":
+    case 'text':
+      return <Markdown text={part.text} width={width - 2} />
+    case 'reasoning':
       return (
         <Box marginLeft={2}>
           <Text dimColor italic>
             {part.text}
           </Text>
         </Box>
-      );
-    case "tool-call":
-      return <ToolLine call={part} />;
-    case "agent":
-      return <Agent part={part} saved={saved} />;
-    case "media":
-      return <MediaLine part={part} saved={saved} />;
+      )
+    case 'tool-call':
+      return <ToolLine call={part} />
+    case 'agent':
+      return <Agent part={part} saved={saved} />
+    case 'media':
+      return <MediaLine part={part} saved={saved} />
   }
 }
 
@@ -168,28 +194,31 @@ export function Message({
   saved,
   width,
 }: {
-  message: ViewMessage;
-  saved: ReadonlyArray<Saved>;
+  message: ViewMessage
+  saved: ReadonlyArray<Saved>
   /** The terminal width, for the markdown of the model's text. */
-  width: number;
+  width: number
 }) {
   switch (message.role) {
-    case "user": {
+    case 'user': {
       // A voice message names its files as `@"path"`, shown as a file badge.
-      const named: Array<string> = [];
+      const named: Array<string> = []
       const text = message.text
         .replace(/@"([^"]+)"/g, (_match, path: string) => {
-          named.push(basename(path));
-          return "";
+          named.push(basename(path))
+          return ''
         })
-        .trim();
-      const files = [...(message.media ?? []).map((part) => `${part.kind} ${part.name}`), ...named];
+        .trim()
+      const files = [
+        ...(message.media ?? []).map((part) => `${part.kind} ${part.name}`),
+        ...named,
+      ]
       return (
         <Box marginTop={1} flexWrap="wrap">
           <Text bold>
             <Text color={ACCENT}>🦇 </Text>
             {text}
-            {files.length > 0 ? " " : ""}
+            {files.length > 0 ? ' ' : ''}
           </Text>
           {files.map((file) => (
             <Text key={file} color="black" backgroundColor={ACCENT}>
@@ -197,39 +226,43 @@ export function Message({
             </Text>
           ))}
         </Box>
-      );
+      )
     }
-    case "notice": {
-      const isError = message.kind === "error";
+    case 'notice': {
+      const isError = message.kind === 'error'
       // A command's answer, for example "Connected to Notion.", stands out.
       const done =
-        message.kind === "command" && /^(Connected|Disconnected|Model|Effort)\b/.test(message.text);
+        message.kind === 'command' &&
+        /^(Connected|Disconnected|Model|Effort)\b/.test(message.text)
       return (
         <Box marginLeft={2}>
-          <Text color={isError ? "red" : done ? "green" : "gray"} bold={done}>
-            {`${isError ? "✗" : done ? "✓" : "·"} ${message.text}`}
+          <Text color={isError ? 'red' : done ? 'green' : 'gray'} bold={done}>
+            {`${isError ? '✗' : done ? '✓' : '·'} ${message.text}`}
           </Text>
         </Box>
-      );
+      )
     }
-    case "assistant":
+    case 'assistant':
       return (
         <Box flexDirection="column" marginTop={1}>
           {message.parts.map((part, index) => (
             <Part key={index} part={part} saved={saved} width={width} />
           ))}
         </Box>
-      );
+      )
   }
 }
 
 /** Does a part still change: a running tool or agent, or media still saving? */
 function isLivePart(part: ViewPart, saving: (id: string) => boolean): boolean {
-  if (part.type === "tool-call")
-    return part.status === "running" || part.status === "needs-approval";
-  if (part.type === "agent")
-    return part.status === "running" || part.parts.some((inner) => isLivePart(inner, saving));
-  return part.type === "media" && saving(part.id);
+  if (part.type === 'tool-call')
+    return part.status === 'running' || part.status === 'needs-approval'
+  if (part.type === 'agent')
+    return (
+      part.status === 'running' ||
+      part.parts.some((inner) => isLivePart(inner, saving))
+    )
+  return part.type === 'media' && saving(part.id)
 }
 
 /**
@@ -244,11 +277,14 @@ export function settledCount(
   saving: (id: string) => boolean,
   running: boolean,
 ) {
-  const lastAssistant = messages.map((message) => message.role).lastIndexOf("assistant");
+  const lastAssistant = messages
+    .map((message) => message.role)
+    .lastIndexOf('assistant')
   for (const [index, message] of messages.entries()) {
-    if (message.role !== "assistant") continue;
-    const streaming = running && index === lastAssistant;
-    if (streaming || message.parts.some((part) => isLivePart(part, saving))) return index;
+    if (message.role !== 'assistant') continue
+    const streaming = running && index === lastAssistant
+    if (streaming || message.parts.some((part) => isLivePart(part, saving)))
+      return index
   }
-  return messages.length;
+  return messages.length
 }
diff --git a/examples/harness-cli-batman/src/screen/paths.ts b/examples/harness-cli-batman/src/screen/paths.ts
index b4b0b1e219..0f1bc779c2 100644
--- a/examples/harness-cli-batman/src/screen/paths.ts
+++ b/examples/harness-cli-batman/src/screen/paths.ts
@@ -1,18 +1,18 @@
-import { readdirSync } from "node:fs";
-import { resolve } from "node:path";
-import type { Line } from "./editor";
-import type { MenuItem } from "./menu";
+import { readdirSync } from 'node:fs'
+import { resolve } from 'node:path'
+import type { Line } from './editor'
+import type { MenuItem } from './menu'
 
 /**
  * An `@path` that is being typed, just before the cursor: an `@` at the
  * start or after white space, then a quoted path that is not closed yet
  * (`@"my ca`), or the text up to the cursor. runCli attaches the same tokens.
  */
-const TYPING = /(^|\s)@(?:"([^"]*)|([^\s"]*))$/;
+const TYPING = /(^|\s)@(?:"([^"]*)|([^\s"]*))$/
 
 /** A file or a folder in the `@` list. `fill` replaces the typed token. */
 export interface PathItem extends MenuItem {
-  fill: string;
+  fill: string
 }
 
 /**
@@ -24,47 +24,49 @@ export interface PathItem extends MenuItem {
  * ponytail: one folder read, at most 100 entries.
  */
 export function pathSuggestions(line: Line, cwd = process.cwd()) {
-  const match = TYPING.exec(line.text.slice(0, line.cursor));
-  if (!match) return undefined;
-  const quoted = match[2] !== undefined;
-  const typed = match[2] ?? match[3] ?? "";
-  const dir = typed.slice(0, typed.lastIndexOf("/") + 1);
-  const name = typed.slice(dir.length).toLowerCase();
-  let entries;
+  const match = TYPING.exec(line.text.slice(0, line.cursor))
+  if (!match) return undefined
+  const quoted = match[2] !== undefined
+  const typed = match[2] ?? match[3] ?? ''
+  const dir = typed.slice(0, typed.lastIndexOf('/') + 1)
+  const name = typed.slice(dir.length).toLowerCase()
+  let entries
   try {
-    entries = readdirSync(resolve(cwd, dir || "."), { withFileTypes: true });
+    entries = readdirSync(resolve(cwd, dir || '.'), { withFileTypes: true })
   } catch {
-    return undefined;
+    return undefined
   }
   const items = entries
     .filter(
       (entry) =>
         entry.name.toLowerCase().startsWith(name) &&
-        (name.startsWith(".") || !entry.name.startsWith(".")),
+        (name.startsWith('.') || !entry.name.startsWith('.')),
     )
     .sort(
-      (a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name),
+      (a, b) =>
+        Number(b.isDirectory()) - Number(a.isDirectory()) ||
+        a.name.localeCompare(b.name),
     )
     .slice(0, 100)
     .map((entry): PathItem => {
-      const folder = entry.isDirectory();
-      const path = `${dir}${entry.name}${folder ? "/" : ""}`;
+      const folder = entry.isDirectory()
+      const path = `${dir}${entry.name}${folder ? '/' : ''}`
       // A path with a space needs quotes. A folder stays open, so the next
       // name can follow it. A file ends the token with a space.
       const fill =
         quoted || /\s/.test(path)
-          ? `@"${path}${folder ? "" : '" '}`
-          : `@${path}${folder ? "" : " "}`;
+          ? `@"${path}${folder ? '' : '" '}`
+          : `@${path}${folder ? '' : ' '}`
       return {
         id: path,
         label: path,
         fill,
-        ...(folder ? { detail: "folder" } : {}),
-      };
-    });
-  const [only] = items;
+        ...(folder ? { detail: 'folder' } : {}),
+      }
+    })
+  const [only] = items
   if (items.length === 0 || (items.length === 1 && only?.id === typed)) {
-    return undefined;
+    return undefined
   }
-  return { start: match.index + (match[1] ?? "").length, items };
+  return { start: match.index + (match[1] ?? '').length, items }
 }
diff --git a/examples/harness-cli-batman/src/screen/splash.tsx b/examples/harness-cli-batman/src/screen/splash.tsx
index ae4c55b4bc..4e15d4968e 100644
--- a/examples/harness-cli-batman/src/screen/splash.tsx
+++ b/examples/harness-cli-batman/src/screen/splash.tsx
@@ -1,69 +1,70 @@
-import React, { useEffect, useState } from "react";
-import { Box, Text, render, useApp, useInput, useWindowSize } from "ink";
-import { ACCENT, GOLD, NIGHT } from "./theme";
-import { POSES, STAND, SYMBOL } from "./batman-art";
-import type { RenderOptions } from "ink";
+import React, { useEffect, useState } from 'react'
+import { Box, Text, render, useApp, useInput, useWindowSize } from 'ink'
+import { ACCENT, GOLD, NIGHT } from './theme'
+import { POSES, STAND, SYMBOL } from './batman-art'
+import type { RenderOptions } from 'ink'
 
-const TAGLINE = "I   A M   T H E   N I G H T";
-const SUB = "TanStack AI harness  ·  Gotham terminal";
-const FILL = new Set("8");
+const TAGLINE = 'I   A M   T H E   N I G H T'
+const SUB = 'TanStack AI harness  ·  Gotham terminal'
+const FILL = new Set('8')
 
-const SYMBOL_MS = 1800;
-const POSE_MS = 340;
-const HOLD_MS = 700;
-const END = SYMBOL_MS + POSE_MS * POSES.length * 2 + HOLD_MS;
+const SYMBOL_MS = 1800
+const POSE_MS = 340
+const HOLD_MS = 700
+const END = SYMBOL_MS + POSE_MS * POSES.length * 2 + HOLD_MS
 
-const easeOut = (x: number) => 1 - (1 - Math.min(1, Math.max(0, x))) ** 3;
+const easeOut = (x: number) => 1 - (1 - Math.min(1, Math.max(0, x))) ** 3
 
-const BAT_SEEDS = [0.1, 0.28, 0.47, 0.63, 0.81, 0.94, 0.17, 0.55];
+const BAT_SEEDS = [0.1, 0.28, 0.47, 0.63, 0.81, 0.94, 0.17, 0.55]
 
 function batLine(width: number, elapsed: number, reverse: boolean) {
-  const marks = new Map<number, string>();
-  const span = Math.max(10, width + 10);
+  const marks = new Map<number, string>()
+  const span = Math.max(10, width + 10)
   for (const [index, seed] of BAT_SEEDS.entries()) {
-    const speed = 28 + (index % 4) * 9;
-    let x = Math.floor((elapsed / speed + seed * span) % span) - 5;
-    if (reverse) x = width - x - 2;
-    if (x >= 0 && x <= width - 2) marks.set(x, index % 3 === 0 ? "✦" : "🦇");
+    const speed = 28 + (index % 4) * 9
+    let x = Math.floor((elapsed / speed + seed * span) % span) - 5
+    if (reverse) x = width - x - 2
+    if (x >= 0 && x <= width - 2) marks.set(x, index % 3 === 0 ? '✦' : '🦇')
   }
-  let out = "";
+  let out = ''
   for (let i = 0; i < width;) {
-    const mark = marks.get(i);
+    const mark = marks.get(i)
     if (mark) {
-      out += mark;
-      i += 2;
+      out += mark
+      i += 2
     } else {
-      out += " ";
-      i += 1;
+      out += ' '
+      i += 1
     }
   }
-  return out;
+  return out
 }
 
 function hop(frame: ReadonlyArray<string>, up: boolean) {
-  if (up || frame.length === 0) return frame;
-  const blank = " ".repeat(frame[0]?.length ?? 0);
-  return [blank, ...frame.slice(0, -1)];
+  if (up || frame.length === 0) return frame
+  const blank = ' '.repeat(frame[0]?.length ?? 0)
+  return [blank, ...frame.slice(0, -1)]
 }
 
 /** One row of ASCII, cut into runs of one color. */
 function Row(props: {
-  text: string;
-  shown: number;
-  light: number;
-  revealing: boolean;
-  fill?: Set<string>;
+  text: string
+  shown: number
+  light: number
+  revealing: boolean
+  fill?: Set<string>
 }) {
-  const { text, shown, light, revealing, fill } = props;
-  const runs: Array<{ color: string | undefined; text: string }> = [];
+  const { text, shown, light, revealing, fill } = props
+  const runs: Array<{ color: string | undefined; text: string }> = []
   for (const [column, char] of [...text].entries()) {
-    const visible = column < shown && char !== " ";
-    const lit = Math.abs(column - light) < 3 || (revealing && column >= shown - 2);
-    const color = !visible ? undefined : lit || fill?.has(char) ? GOLD : ACCENT;
-    const shownChar = column < shown ? char : " ";
-    const last = runs.at(-1);
-    if (last && last.color === color) last.text += shownChar;
-    else runs.push({ color, text: shownChar });
+    const visible = column < shown && char !== ' '
+    const lit =
+      Math.abs(column - light) < 3 || (revealing && column >= shown - 2)
+    const color = !visible ? undefined : lit || fill?.has(char) ? GOLD : ACCENT
+    const shownChar = column < shown ? char : ' '
+    const last = runs.at(-1)
+    if (last && last.color === color) last.text += shownChar
+    else runs.push({ color, text: shownChar })
   }
   return (
     <Text>
@@ -73,41 +74,45 @@ function Row(props: {
         </Text>
       ))}
     </Text>
-  );
+  )
 }
 
 function Splash() {
-  const { exit } = useApp();
-  const { columns, rows } = useWindowSize();
-  const [elapsed, setElapsed] = useState(0);
+  const { exit } = useApp()
+  const { columns, rows } = useWindowSize()
+  const [elapsed, setElapsed] = useState(0)
   useEffect(() => {
-    const start = Date.now();
+    const start = Date.now()
     const timer = setInterval(() => {
-      const now = Date.now() - start;
-      setElapsed(now);
-      if (now >= END) exit();
-    }, 33);
-    return () => clearInterval(timer);
-  }, []);
-  useInput(() => exit());
+      const now = Date.now() - start
+      setElapsed(now)
+      if (now >= END) exit()
+    }, 33)
+    return () => clearInterval(timer)
+  }, [])
+  useInput(() => exit())
 
-  const canSymbol = columns >= (SYMBOL[0]?.length ?? 0) + 2;
-  const canPoses = columns >= (POSES[0]?.[0]?.length ?? 0) + 2;
-  const showSymbol = canSymbol && elapsed < SYMBOL_MS;
-  const poseSource = canPoses ? POSES : [STAND];
-  const poseAt = Math.max(0, elapsed - (canSymbol ? SYMBOL_MS : 0));
-  const poseIndex = Math.floor(poseAt / POSE_MS) % poseSource.length;
-  const pose = hop(poseSource[poseIndex] ?? STAND, Math.floor(poseAt / 170) % 2 === 0);
-  const art = showSymbol ? SYMBOL : pose;
-  const width = art[0]?.length ?? 0;
-  const revealFor = showSymbol ? SYMBOL_MS * 0.55 : 280;
-  const local = showSymbol ? elapsed : poseAt % POSE_MS;
-  const shown = Math.ceil(width * easeOut(Math.min(1, local / revealFor)));
-  const light = -6 + (width + 12) * easeOut(Math.min(1, local / (revealFor + 400)));
-  const revealing = local < revealFor;
-  const typed = Math.round(TAGLINE.length * easeOut(elapsed / 900));
-  const inner = Math.max(8, columns);
-  const showBats = rows >= (art.length ?? 0) + 6;
+  const canSymbol = columns >= (SYMBOL[0]?.length ?? 0) + 2
+  const canPoses = columns >= (POSES[0]?.[0]?.length ?? 0) + 2
+  const showSymbol = canSymbol && elapsed < SYMBOL_MS
+  const poseSource = canPoses ? POSES : [STAND]
+  const poseAt = Math.max(0, elapsed - (canSymbol ? SYMBOL_MS : 0))
+  const poseIndex = Math.floor(poseAt / POSE_MS) % poseSource.length
+  const pose = hop(
+    poseSource[poseIndex] ?? STAND,
+    Math.floor(poseAt / 170) % 2 === 0,
+  )
+  const art = showSymbol ? SYMBOL : pose
+  const width = art[0]?.length ?? 0
+  const revealFor = showSymbol ? SYMBOL_MS * 0.55 : 280
+  const local = showSymbol ? elapsed : poseAt % POSE_MS
+  const shown = Math.ceil(width * easeOut(Math.min(1, local / revealFor)))
+  const light =
+    -6 + (width + 12) * easeOut(Math.min(1, local / (revealFor + 400)))
+  const revealing = local < revealFor
+  const typed = Math.round(TAGLINE.length * easeOut(elapsed / 900))
+  const inner = Math.max(8, columns)
+  const showBats = rows >= (art.length ?? 0) + 6
 
   return (
     <Box
@@ -117,11 +122,17 @@ function Splash() {
       alignItems="center"
       justifyContent="center"
     >
-      {showBats ? <Text color={ACCENT}>{batLine(inner, elapsed, false)}</Text> : null}
-      <Box marginTop={showBats ? 1 : 0} flexDirection="column" alignItems="center">
+      {showBats ? (
+        <Text color={ACCENT}>{batLine(inner, elapsed, false)}</Text>
+      ) : null}
+      <Box
+        marginTop={showBats ? 1 : 0}
+        flexDirection="column"
+        alignItems="center"
+      >
         {art.map((line, index) => (
           <Row
-            key={`${showSymbol ? "symbol" : poseIndex}-${index}`}
+            key={`${showSymbol ? 'symbol' : poseIndex}-${index}`}
             text={line}
             shown={shown}
             light={light}
@@ -135,14 +146,14 @@ function Splash() {
           {TAGLINE.slice(0, Math.max(0, typed)).padEnd(TAGLINE.length)}
         </Text>
       </Box>
-      <Text dimColor>{elapsed > 700 ? SUB : ""}</Text>
+      <Text dimColor>{elapsed > 700 ? SUB : ''}</Text>
       {showBats ? (
         <Box marginTop={1}>
           <Text color={NIGHT}>{batLine(inner, elapsed + 400, true)}</Text>
         </Box>
       ) : null}
     </Box>
-  );
+  )
 }
 
 /**
@@ -150,6 +161,6 @@ function Splash() {
  * seconds. A key skips it. A narrow screen gets the standing pose only.
  */
 export async function showSplash(io: RenderOptions = {}) {
-  const app = render(<Splash />, io);
-  await app.waitUntilExit();
+  const app = render(<Splash />, io)
+  await app.waitUntilExit()
 }
diff --git a/examples/harness-cli-batman/src/screen/status.tsx b/examples/harness-cli-batman/src/screen/status.tsx
index 31044a7d74..5f3e3cfe9a 100644
--- a/examples/harness-cli-batman/src/screen/status.tsx
+++ b/examples/harness-cli-batman/src/screen/status.tsx
@@ -1,32 +1,32 @@
-import React from "react";
-import { Box, Text, useAnimation } from "ink";
-import { useSelector } from "@tanstack/react-store";
-import { selectGoal } from "@tanstack/ai-harness/plugins";
-import { Spinner } from "./parts";
-import type { SessionView } from "@tanstack/ai-harness/view";
-import type { Recording } from "../voice";
+import React from 'react'
+import { Box, Text, useAnimation } from 'ink'
+import { useSelector } from '@tanstack/react-store'
+import { selectGoal } from '@tanstack/ai-harness/plugins'
+import { Spinner } from './parts'
+import type { SessionView } from '@tanstack/ai-harness/view'
+import type { Recording } from '../voice'
 
-export type VoiceState = "idle" | "starting" | "recording" | "transcribing";
+export type VoiceState = 'idle' | 'starting' | 'recording' | 'transcribing'
 
 /** A live level meter from the microphone loudness (0 to 32768). */
 function LevelMeter({ recording }: { recording: Recording }) {
-  const { time } = useAnimation({ interval: 80 });
-  const level = recording.level();
+  const { time } = useAnimation({ interval: 80 })
+  const level = recording.level()
   // Map loudness to 0..1 on a log scale: -60 dB is empty, 0 dB is full.
-  const decibels = 20 * Math.log10(Math.max(level, 1) / 32768);
-  const filled = Math.round(Math.min(1, Math.max(0, (decibels + 60) / 60)) * 16);
-  const seconds = Math.floor(time / 1000);
-  const clock = `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
+  const decibels = 20 * Math.log10(Math.max(level, 1) / 32768)
+  const filled = Math.round(Math.min(1, Math.max(0, (decibels + 60) / 60)) * 16)
+  const seconds = Math.floor(time / 1000)
+  const clock = `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`
   return (
     <Box>
       <Text color="red" bold>{`● REC ${clock}  `}</Text>
-      <Text color={filled > 9 ? "green" : filled > 4 ? "yellow" : "gray"}>
-        {"▮".repeat(filled)}
+      <Text color={filled > 9 ? 'green' : filled > 4 ? 'yellow' : 'gray'}>
+        {'▮'.repeat(filled)}
       </Text>
-      <Text dimColor>{"▯".repeat(16 - filled)}</Text>
+      <Text dimColor>{'▯'.repeat(16 - filled)}</Text>
       <Text dimColor>{`  ${recording.microphone}`}</Text>
     </Box>
-  );
+  )
 }
 
 /** What waits for the user or runs now: sign-ins, approvals, voice, the turn. */
@@ -35,15 +35,15 @@ export function Status({
   voice,
   recording,
 }: {
-  view: SessionView;
-  voice: VoiceState;
-  recording: Recording | undefined;
+  view: SessionView
+  voice: VoiceState
+  recording: Recording | undefined
 }) {
-  const status = useSelector(view.store, (state) => state.status);
-  const approvals = useSelector(view.store, (state) => state.approvals);
-  const question = useSelector(view.store, (state) => state.questions.at(0));
-  const signIns = useSelector(view.store, (state) => state.signIns);
-  const goal = useSelector(view.store, selectGoal);
+  const status = useSelector(view.store, (state) => state.status)
+  const approvals = useSelector(view.store, (state) => state.approvals)
+  const question = useSelector(view.store, (state) => state.questions.at(0))
+  const signIns = useSelector(view.store, (state) => state.signIns)
+  const goal = useSelector(view.store, selectGoal)
   return (
     <Box flexDirection="column" marginTop={1}>
       {/* A key question says itself that the page is open, so it waits alone. */}
@@ -54,39 +54,45 @@ export function Status({
               <Box>
                 <Spinner color="magenta" />
                 <Text color="magenta">
-                  {` 🦇 Waiting for you to sign in to ${signIn.connector} in your browser${signIn.userCode ? ` (code ${signIn.userCode})` : ""}.`}
+                  {` 🦇 Waiting for you to sign in to ${signIn.connector} in your browser${signIn.userCode ? ` (code ${signIn.userCode})` : ''}.`}
                 </Text>
               </Box>
-              {signIn.url ? <Text dimColor>{`  No tab opened? Open ${signIn.url}`}</Text> : null}
+              {signIn.url ? (
+                <Text dimColor>{`  No tab opened? Open ${signIn.url}`}</Text>
+              ) : null}
             </Box>
           ))}
       {approvals.length > 0 ? (
         <Text color="magenta" bold>
-          {`🦇 Approve ${approvals.map((item) => item.tool).join(", ")}? Type y or n.`}
+          {`🦇 Approve ${approvals.map((item) => item.tool).join(', ')}? Type y or n.`}
         </Text>
       ) : null}
-      {question ? <Text color="magenta">{`🦇 ${question.message}`}</Text> : null}
+      {question ? (
+        <Text color="magenta">{`🦇 ${question.message}`}</Text>
+      ) : null}
       {goal ? (
         <Text color="yellow">{`🦇 Goal: ${goal.text} (${goal.status}, round ${goal.round})`}</Text>
       ) : null}
-      {voice === "recording" && recording ? (
+      {voice === 'recording' && recording ? (
         <Box flexDirection="column">
           <LevelMeter recording={recording} />
-          <Text dimColor>Let go of Ctrl+R (or tap it again) to send. Esc drops it.</Text>
+          <Text dimColor>
+            Let go of Ctrl+R (or tap it again) to send. Esc drops it.
+          </Text>
         </Box>
-      ) : voice === "starting" ? (
+      ) : voice === 'starting' ? (
         <Box>
           <Spinner color="red" />
           <Text color="red"> opening the cave microphone...</Text>
           <Text dimColor> Esc cancels</Text>
         </Box>
-      ) : voice === "transcribing" ? (
+      ) : voice === 'transcribing' ? (
         <Box>
           <Spinner color="cyan" />
           <Text color="cyan"> transcribing your voice...</Text>
           <Text dimColor> Esc cancels</Text>
         </Box>
-      ) : status === "running" ? (
+      ) : status === 'running' ? (
         <Box>
           <Spinner />
           <Text color="yellow"> patrolling Gotham</Text>
@@ -94,5 +100,5 @@ export function Status({
         </Box>
       ) : null}
     </Box>
-  );
+  )
 }
diff --git a/examples/harness-cli-batman/src/screen/theme.ts b/examples/harness-cli-batman/src/screen/theme.ts
index 93bb26f8f2..997c0f8fa1 100644
--- a/examples/harness-cli-batman/src/screen/theme.ts
+++ b/examples/harness-cli-batman/src/screen/theme.ts
@@ -1,20 +1,20 @@
 // Bat-signal yellow on a dark terminal.
-export const ACCENT = "#f5d000";
-export const GOLD = "#fff3a0";
-export const NIGHT = "#6b5a12";
+export const ACCENT = '#f5d000'
+export const GOLD = '#fff3a0'
+export const NIGHT = '#6b5a12'
 
 export const KIND_COLOR: Record<string, string> = {
-  image: "yellow",
-  audio: "cyan",
-  video: "blue",
-  document: "white",
-};
+  image: 'yellow',
+  audio: 'cyan',
+  video: 'blue',
+  document: 'white',
+}
 
-export const SPINNER = ["🦇", "⚡", "🌙", "🦇", "✦", "⚡"];
+export const SPINNER = ['🦇', '⚡', '🌙', '🦇', '✦', '⚡']
 
 /** 12400 is "12.4k", 1050000 is "1.05M". */
 export function compact(count: number) {
-  if (count >= 1_000_000) return `${Number((count / 1_000_000).toFixed(2))}M`;
-  if (count >= 1_000) return `${Number((count / 1_000).toFixed(1))}k`;
-  return String(count);
+  if (count >= 1_000_000) return `${Number((count / 1_000_000).toFixed(2))}M`
+  if (count >= 1_000) return `${Number((count / 1_000).toFixed(1))}k`
+  return String(count)
 }
diff --git a/examples/harness-cli-batman/src/sessions.ts b/examples/harness-cli-batman/src/sessions.ts
index c355f12542..435d941882 100644
--- a/examples/harness-cli-batman/src/sessions.ts
+++ b/examples/harness-cli-batman/src/sessions.ts
@@ -1,15 +1,27 @@
-import { randomUUID } from "node:crypto";
-import { appendFile, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { logMessageStore } from "@tanstack/ai-harness";
-import { LogConflictError, defineLogStore, defineMetadataStore } from "@tanstack/ai-persistence";
-import { SAVE_DIR, jsonFile } from "./credentials";
-import type { ModelMessage } from "@tanstack/ai";
-import type { LogRecord } from "@tanstack/ai-persistence";
+import { randomUUID } from 'node:crypto'
+import {
+  appendFile,
+  mkdir,
+  readFile,
+  readdir,
+  stat,
+  writeFile,
+} from 'node:fs/promises'
+import { join } from 'node:path'
+import { logMessageStore } from '@tanstack/ai-harness'
+import {
+  LogConflictError,
+  defineLogStore,
+  defineMetadataStore,
+} from '@tanstack/ai-persistence'
+import { SAVE_DIR, jsonFile } from './credentials'
+import type { ModelMessage } from '@tanstack/ai'
+import type { LogRecord } from '@tanstack/ai-persistence'
 
 /** One file for each session, in your home folder. */
-const SESSIONS_DIR = join(SAVE_DIR, "sessions");
-const fileOf = (threadId: string) => join(SESSIONS_DIR, `${encodeURIComponent(threadId)}.jsonl`);
+const SESSIONS_DIR = join(SAVE_DIR, 'sessions')
+const fileOf = (threadId: string) =>
+  join(SESSIONS_DIR, `${encodeURIComponent(threadId)}.jsonl`)
 
 /**
  * The records of a session file. Each line is one batch of records. A crash
@@ -17,18 +29,18 @@ const fileOf = (threadId: string) => join(SESSIONS_DIR, `${encodeURIComponent(th
  * batch, so a batch is in the file in full or not at all.
  */
 async function readLog(file: string) {
-  const text = await readFile(file, "utf8").catch(() => "");
-  const lines = text.split("\n").filter((line) => line !== "");
-  const records: Array<LogRecord> = [];
+  const text = await readFile(file, 'utf8').catch(() => '')
+  const lines = text.split('\n').filter((line) => line !== '')
+  const records: Array<LogRecord> = []
   for (const [index, line] of lines.entries()) {
     try {
-      records.push(...(JSON.parse(line) as Array<LogRecord>));
+      records.push(...(JSON.parse(line) as Array<LogRecord>))
     } catch (error) {
-      if (index < lines.length - 1) throw error;
-      await writeFile(file, lines.slice(0, -1).join("\n") + "\n");
+      if (index < lines.length - 1) throw error
+      await writeFile(file, lines.slice(0, -1).join('\n') + '\n')
     }
   }
-  return records;
+  return records
 }
 
 /**
@@ -39,89 +51,93 @@ async function readLog(file: string) {
  * locks, for example a database.
  */
 function fileLog() {
-  const loaded = new Map<string, Promise<Array<LogRecord>>>();
-  const listeners = new Map<string, Set<() => void>>();
-  let appending = Promise.resolve();
+  const loaded = new Map<string, Promise<Array<LogRecord>>>()
+  const listeners = new Map<string, Set<() => void>>()
+  let appending = Promise.resolve()
   const load = (threadId: string) => {
-    let log = loaded.get(threadId);
+    let log = loaded.get(threadId)
     if (!log) {
-      log = readLog(fileOf(threadId));
-      loaded.set(threadId, log);
+      log = readLog(fileOf(threadId))
+      loaded.set(threadId, log)
     }
-    return log;
-  };
+    return log
+  }
   return defineLogStore({
     append: (threadId, seq, records) => {
       const run = appending.then(async () => {
-        if (records.length === 0) return;
-        const log = await load(threadId);
-        if (seq !== log.length + 1) throw new LogConflictError(threadId, seq);
-        const line = JSON.stringify(records);
-        await mkdir(SESSIONS_DIR, { recursive: true });
-        await appendFile(fileOf(threadId), `${line}\n`);
-        log.push(...(JSON.parse(line) as Array<LogRecord>));
+        if (records.length === 0) return
+        const log = await load(threadId)
+        if (seq !== log.length + 1) throw new LogConflictError(threadId, seq)
+        const line = JSON.stringify(records)
+        await mkdir(SESSIONS_DIR, { recursive: true })
+        await appendFile(fileOf(threadId), `${line}\n`)
+        log.push(...(JSON.parse(line) as Array<LogRecord>))
         for (const listener of [...(listeners.get(threadId) ?? [])]) {
-          listener();
+          listener()
         }
-      });
-      appending = run.catch(() => {});
-      return run;
+      })
+      appending = run.catch(() => {})
+      return run
     },
     read: async (threadId, options = {}) => {
-      const log = await load(threadId);
-      const after = options.after ?? 0;
-      const end = options.limit === undefined ? log.length : after + options.limit;
+      const log = await load(threadId)
+      const after = options.after ?? 0
+      const end =
+        options.limit === undefined ? log.length : after + options.limit
       return log.slice(after, end).map((record, index) => ({
         seq: after + index + 1,
         record: structuredClone(record),
-      }));
+      }))
     },
     subscribe: (threadId, listener) => {
-      const set = listeners.get(threadId) ?? new Set();
-      listeners.set(threadId, set);
-      set.add(listener);
+      const set = listeners.get(threadId) ?? new Set()
+      listeners.set(threadId, set)
+      set.add(listener)
       return () => {
-        set.delete(listener);
-      };
+        set.delete(listener)
+      }
     },
-  });
+  })
 }
 
 /** Each session's settings and plugin state (the model, the todos), in a file. */
 function fileMetadata() {
-  const { load, update } = jsonFile<unknown>(join(SAVE_DIR, "metadata.json"));
+  const { load, update } = jsonFile<unknown>(join(SAVE_DIR, 'metadata.json'))
   return defineMetadataStore({
-    get: async (namespace, key) => structuredClone((await load())[namespace]?.[key] ?? null),
+    get: async (namespace, key) =>
+      structuredClone((await load())[namespace]?.[key] ?? null),
     set: (namespace, key, value) =>
       update((all) => {
-        all[namespace] = { ...all[namespace], [key]: value };
+        all[namespace] = { ...all[namespace], [key]: value }
       }),
     delete: (namespace, key) =>
       update((all) => {
-        delete all[namespace]?.[key];
+        delete all[namespace]?.[key]
       }),
-  });
+  })
 }
 
-export const sessionLog = fileLog();
-export const sessionMetadata = fileMetadata();
+export const sessionLog = fileLog()
+export const sessionMetadata = fileMetadata()
 
 /** A new session id: short, so it is easy to type after `--resume`. */
-export const newSessionId = () => randomUUID().slice(0, 8);
+export const newSessionId = () => randomUUID().slice(0, 8)
 
 /** Is `threadId` a saved session? */
 export async function hasSession(threadId: string) {
-  return (await sessionLog.read(threadId, { limit: 1 })).length > 0;
+  return (await sessionLog.read(threadId, { limit: 1 })).length > 0
 }
 
 /** The first thing the user said in a session, on one line. */
 function titleOf(messages: ReadonlyArray<ModelMessage>) {
-  const content = messages.find((message) => message.role === "user")?.content;
+  const content = messages.find((message) => message.role === 'user')?.content
   const text =
-    typeof content === "string"
+    typeof content === 'string'
       ? content
-      : (content ?? []).flatMap((part) => (part.type === "text" ? [part.content] : []));
-  return [text].flat().join(" ").replace(/\s+/g, " ").trim();
+      : (content ?? []).flatMap((part) =>
+          part.type === 'text' ? [part.content] : [],
+        )
+  return [text].flat().join(' ').replace(/\s+/g, ' ').trim()
 }
 
 /**
@@ -132,24 +148,24 @@ function titleOf(messages: ReadonlyArray<ModelMessage>) {
  * sessions. An index file is faster when there are many big sessions.
  */
 export async function listSessions(limit = 20) {
-  const names = await readdir(SESSIONS_DIR).catch(() => []);
+  const names = await readdir(SESSIONS_DIR).catch(() => [])
   const files = await Promise.all(
     names
-      .filter((name) => name.endsWith(".jsonl"))
+      .filter((name) => name.endsWith('.jsonl'))
       .map(async (name) => ({
-        id: decodeURIComponent(name.slice(0, -".jsonl".length)),
+        id: decodeURIComponent(name.slice(0, -'.jsonl'.length)),
         updatedAt: (await stat(join(SESSIONS_DIR, name))).mtimeMs,
       })),
-  );
+  )
   const recent = files
-    .filter((file) => !file.id.includes(":"))
-    .sort((a, b) => b.updatedAt - a.updatedAt);
-  const messages = logMessageStore({ store: sessionLog });
-  const sessions: Array<{ id: string; updatedAt: number; title: string }> = [];
+    .filter((file) => !file.id.includes(':'))
+    .sort((a, b) => b.updatedAt - a.updatedAt)
+  const messages = logMessageStore({ store: sessionLog })
+  const sessions: Array<{ id: string; updatedAt: number; title: string }> = []
   for (const file of recent) {
-    if (sessions.length === limit) break;
-    const title = titleOf(await messages.loadThread(file.id));
-    if (title !== "") sessions.push({ ...file, title });
+    if (sessions.length === limit) break
+    const title = titleOf(await messages.loadThread(file.id))
+    if (title !== '') sessions.push({ ...file, title })
   }
-  return sessions;
+  return sessions
 }
diff --git a/examples/harness-cli-batman/src/store.ts b/examples/harness-cli-batman/src/store.ts
index 8c2d8d9108..0e27cbd95b 100644
--- a/examples/harness-cli-batman/src/store.ts
+++ b/examples/harness-cli-batman/src/store.ts
@@ -1,11 +1,15 @@
-import { defineAIPersistence, memoryPersistence, retrieveBlob } from "@tanstack/ai-persistence";
-import { fileCredentials } from "./credentials";
-import { sessionLog, sessionMetadata } from "./sessions";
-import type { ByokProvider } from "@tanstack/ai/byok";
+import {
+  defineAIPersistence,
+  memoryPersistence,
+  retrieveBlob,
+} from '@tanstack/ai-persistence'
+import { fileCredentials } from './credentials'
+import { sessionLog, sessionMetadata } from './sessions'
+import type { ByokProvider } from '@tanstack/ai/byok'
 
 /** Sign-ins and the model keys you save with `/connect`, kept in a file. */
-const credentials = fileCredentials();
-const memory = memoryPersistence().stores;
+const credentials = fileCredentials()
+const memory = memoryPersistence().stores
 
 /**
  * The sessions, their settings, and the sign-ins and keys are kept in files,
@@ -24,19 +28,19 @@ export const persistence = defineAIPersistence({
     artifacts: memory.artifacts,
     blobs: memory.blobs,
   },
-});
+})
 
 /** The bytes of a stored media file, or `undefined` when it is gone. */
 export async function mediaBytes(id: string) {
-  const blob = await retrieveBlob(persistence, id);
-  return blob ? new Uint8Array(await blob.arrayBuffer()) : undefined;
+  const blob = await retrieveBlob(persistence, id)
+  return blob ? new Uint8Array(await blob.arrayBuffer()) : undefined
 }
 
 /** The value of the first env var of `provider` that is set, or `null`. */
 export function envKey(provider: ByokProvider) {
-  const names = provider.env ?? [];
-  const name = names.find((env) => Boolean(process.env[env]));
-  return name ? (process.env[name] ?? null) : null;
+  const names = provider.env ?? []
+  const name = names.find((env) => Boolean(process.env[env]))
+  return name ? (process.env[name] ?? null) : null
 }
 
 /**
@@ -45,7 +49,7 @@ export function envKey(provider: ByokProvider) {
  * session uses the same saved keys.
  */
 export async function providerKey(provider: ByokProvider, threadId: string) {
-  const saved = await credentials.get({ threadId }, provider.id);
-  if (saved?.type === "api_key") return saved.value;
-  return envKey(provider);
+  const saved = await credentials.get({ threadId }, provider.id)
+  if (saved?.type === 'api_key') return saved.value
+  return envKey(provider)
 }
diff --git a/examples/harness-cli-batman/src/tui.tsx b/examples/harness-cli-batman/src/tui.tsx
index b2c3378714..4cd309621a 100644
--- a/examples/harness-cli-batman/src/tui.tsx
+++ b/examples/harness-cli-batman/src/tui.tsx
@@ -1,6 +1,13 @@
-import { readFile } from "node:fs/promises";
-import { basename } from "node:path";
-import React, { useEffect, useLayoutEffect, useMemo, useReducer, useRef, useState } from "react";
+import { readFile } from 'node:fs/promises'
+import { basename } from 'node:path'
+import React, {
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+} from 'react'
 import {
   Box,
   Spacer,
@@ -15,11 +22,17 @@ import {
   usePaste,
   useStdout,
   useWindowSize,
-} from "ink";
-import { useSelector } from "@tanstack/react-store";
-import { supportedReasoningLevels } from "@tanstack/ai-models";
-import { features, keyProviders, modelInfo, modelProviders, reasons } from "./harness";
-import { hasSession, listSessions } from "./sessions";
+} from 'ink'
+import { useSelector } from '@tanstack/react-store'
+import { supportedReasoningLevels } from '@tanstack/ai-models'
+import {
+  features,
+  keyProviders,
+  modelInfo,
+  modelProviders,
+  reasons,
+} from './harness'
+import { hasSession, listSessions } from './sessions'
 import {
   canTranscribe,
   chooseMicrophone,
@@ -29,48 +42,48 @@ import {
   startRecording,
   transcribe,
   withSpokenFiles,
-} from "./voice";
-import { useLineEditor } from "./screen/editor";
-import { Footer } from "./screen/footer";
-import { PROVIDER_KEYS, isOn, providerKeysIn } from "./screen/keys";
-import { mediaDir, openExternal, play, useSavedMedia } from "./screen/media";
-import { SCREEN_COMMANDS, TAKES_INPUT } from "./screen/commands";
-import { Menu } from "./screen/menu";
-import { pathSuggestions } from "./screen/paths";
-import { showSplash } from "./screen/splash";
-import { Message, settledCount } from "./screen/parts";
-import { Status } from "./screen/status";
-import { ACCENT, compact } from "./screen/theme";
-import type { ReactNode } from "react";
-import type { DOMElement, RenderOptions } from "ink";
-import type { ModelEntry } from "./harness";
-import type { Recording, VoiceClip } from "./voice";
-import type { Line } from "./screen/editor";
-import type { MenuItem } from "./screen/menu";
-import type { PathItem } from "./screen/paths";
-import type { VoiceState } from "./screen/status";
+} from './voice'
+import { useLineEditor } from './screen/editor'
+import { Footer } from './screen/footer'
+import { PROVIDER_KEYS, isOn, providerKeysIn } from './screen/keys'
+import { mediaDir, openExternal, play, useSavedMedia } from './screen/media'
+import { SCREEN_COMMANDS, TAKES_INPUT } from './screen/commands'
+import { Menu } from './screen/menu'
+import { pathSuggestions } from './screen/paths'
+import { showSplash } from './screen/splash'
+import { Message, settledCount } from './screen/parts'
+import { Status } from './screen/status'
+import { ACCENT, compact } from './screen/theme'
+import type { ReactNode } from 'react'
+import type { DOMElement, RenderOptions } from 'ink'
+import type { ModelEntry } from './harness'
+import type { Recording, VoiceClip } from './voice'
+import type { Line } from './screen/editor'
+import type { MenuItem } from './screen/menu'
+import type { PathItem } from './screen/paths'
+import type { VoiceState } from './screen/status'
 import type {
   SessionView,
   SessionViewState,
   ViewCommand,
   ViewMessage,
-} from "@tanstack/ai-harness/view";
+} from '@tanstack/ai-harness/view'
 
 const HELP = [
-  "🦇 Type / to see the commands. ↑ and ↓ go through the lines you sent.",
-  "🦇 Type @ to pick a file or a folder to send. Tab or Enter fills the path.",
-  "🦇 Voice: hold Ctrl+R and talk, then let go. Or tap Ctrl+R, talk, tap again.",
-  "  The words go into the input line. Fix them if needed, then press Enter.",
+  '🦇 Type / to see the commands. ↑ and ↓ go through the lines you sent.',
+  '🦇 Type @ to pick a file or a folder to send. Tab or Enter fills the path.',
+  '🦇 Voice: hold Ctrl+R and talk, then let go. Or tap Ctrl+R, talk, tap again.',
+  '  The words go into the input line. Fix them if needed, then press Enter.',
   '  Name a file ("use cat dot png") or say "the last image" to send it too.',
-  "  The first recording listens on all microphones and keeps the loudest.",
-  "🦇 I am the night. You type. I work.",
-];
+  '  The first recording listens on all microphones and keeps the loudest.',
+  '🦇 I am the night. You type. I work.',
+]
 
 /** The `/` commands that start with (or contain) what you typed after `/`. */
 function suggestionsFor(text: string, commands: ReadonlyArray<ViewCommand>) {
-  if (!/^\/\S*$/.test(text)) return [];
-  const query = text.slice(1).toLowerCase();
-  const own = new Set(SCREEN_COMMANDS.map((command) => command.name));
+  if (!/^\/\S*$/.test(text)) return []
+  const query = text.slice(1).toLowerCase()
+  const own = new Set(SCREEN_COMMANDS.map((command) => command.name))
   const all: Array<MenuItem & { takesInput: boolean }> = [
     ...SCREEN_COMMANDS.map((command) => ({
       id: command.name,
@@ -83,7 +96,7 @@ function suggestionsFor(text: string, commands: ReadonlyArray<ViewCommand>) {
     ...commands
       .filter(
         (command) =>
-          (!command.name.includes(":") || command.name.startsWith("skill:")) &&
+          (!command.name.includes(':') || command.name.startsWith('skill:')) &&
           !own.has(command.name),
       )
       .map((command) => ({
@@ -92,175 +105,192 @@ function suggestionsFor(text: string, commands: ReadonlyArray<ViewCommand>) {
         detail: command.description,
         takesInput: command.input !== undefined,
       })),
-  ];
+  ]
   return [
     ...all.filter((item) => item.id.startsWith(query)),
-    ...all.filter((item) => !item.id.startsWith(query) && item.id.includes(query)),
-  ];
+    ...all.filter(
+      (item) => !item.id.startsWith(query) && item.id.includes(query),
+    ),
+  ]
 }
 
 /** Does `/connect <id>` sign in with the browser, with no key to paste? */
 function signsIn(id: string) {
-  return keyProviders.some((provider) => provider.id === id && "signIn" in provider);
+  return keyProviders.some(
+    (provider) => provider.id === id && 'signIn' in provider,
+  )
 }
 
 /** The rows of the `/connect` picker: the model providers, then the apps. */
 function connectItems(state: SessionViewState): Array<MenuItem> {
-  const keys = providerKeysIn(state.plugins[PROVIDER_KEYS]);
+  const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
   const providers = keys.map((key) => ({
     id: key.id,
     label: key.label,
-    current: key.state !== "missing",
+    current: key.state !== 'missing',
     detail:
-      key.state === "connected"
-        ? "connected"
-        : key.state === "env"
-          ? "key from the environment"
+      key.state === 'connected'
+        ? 'connected'
+        : key.state === 'env'
+          ? 'key from the environment'
           : signsIn(key.id)
-            ? "sign in with the browser, no key to paste"
-            : "opens the page to make a key, then you paste it",
-  }));
+            ? 'sign in with the browser, no key to paste'
+            : 'opens the page to make a key, then you paste it',
+  }))
   const apps = state.commands.flatMap((command) => {
-    const id = command.name.slice("connect:".length);
-    const isApp = command.name.startsWith("connect:") && !keys.some((key) => key.id === id);
-    return isApp ? [{ id, label: id, detail: command.description }] : [];
-  });
-  return [...providers, ...apps];
+    const id = command.name.slice('connect:'.length)
+    const isApp =
+      command.name.startsWith('connect:') && !keys.some((key) => key.id === id)
+    return isApp ? [{ id, label: id, detail: command.description }] : []
+  })
+  return [...providers, ...apps]
 }
 
-const modelCount = (count: number) => `${count} model${count === 1 ? "" : "s"}`;
+const modelCount = (count: number) => `${count} model${count === 1 ? '' : 's'}`
 
 const currentModel = (state: SessionViewState) =>
-  String(state.config.find((item) => item.key === "model")?.value ?? "");
+  String(state.config.find((item) => item.key === 'model')?.value ?? '')
 
 /** The context size, the effort levels, and the price of a model. */
 function modelDetail(model: ModelEntry) {
-  const { contextWindow, cost } = model.record;
-  const levels = supportedReasoningLevels(model.record).filter((level) => level !== "off");
+  const { contextWindow, cost } = model.record
+  const levels = supportedReasoningLevels(model.record).filter(
+    (level) => level !== 'off',
+  )
   return [
     `${compact(contextWindow)} context`,
     levels.length === 0
-      ? "no effort setting"
+      ? 'no effort setting'
       : levels.length === 1
         ? `effort ${levels[0]}`
         : `effort ${levels[0]} to ${levels.at(-1)}`,
     ...(cost.input > 0 ? [`$${cost.input}/$${cost.output} per 1M tokens`] : []),
-  ].join(", ");
+  ].join(', ')
 }
 
 /** The rows of a `/model` picker for these models. */
-function modelRows(models: ReadonlyArray<ModelEntry>, state: SessionViewState): Array<MenuItem> {
-  const current = currentModel(state);
+function modelRows(
+  models: ReadonlyArray<ModelEntry>,
+  state: SessionViewState,
+): Array<MenuItem> {
+  const current = currentModel(state)
   return models.map((model) => ({
     id: model.id,
     label: model.id,
     current: model.id === current,
     detail: modelDetail(model),
-  }));
+  }))
 }
 
 /** The first `/model` step: the providers, then the demo model if it is on. */
 function providerItems(state: SessionViewState): Array<MenuItem> {
-  const current = currentModel(state);
-  const keys = providerKeysIn(state.plugins[PROVIDER_KEYS]);
+  const current = currentModel(state)
+  const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
   const rows = modelProviders.map((provider) => {
-    const missing = keys.find((key) => key.id === provider.id)?.state === "missing";
+    const missing =
+      keys.find((key) => key.id === provider.id)?.state === 'missing'
     return {
       id: provider.id,
       label: provider.label,
       current: modelInfo[current]?.provider === provider.id,
-      detail: `${modelCount(provider.models.length)}${missing ? `, needs /connect ${provider.id}` : ""}`,
-    };
-  });
-  const entry = state.config.find((item) => item.key === "model");
-  const demo = entry?.option.type === "select" && entry.option.options.includes("demo");
+      detail: `${modelCount(provider.models.length)}${missing ? `, needs /connect ${provider.id}` : ''}`,
+    }
+  })
+  const entry = state.config.find((item) => item.key === 'model')
+  const demo =
+    entry?.option.type === 'select' && entry.option.options.includes('demo')
   return demo
     ? [
         ...rows,
         {
-          id: "demo",
-          label: "Demo",
-          current: current === "demo",
-          detail: "answers without a key",
+          id: 'demo',
+          label: 'Demo',
+          current: current === 'demo',
+          detail: 'answers without a key',
         },
       ]
-    : rows;
+    : rows
 }
 
 /**
  * The OpenRouter step between the provider and the model: the vendors. An
  * alias vendor (`~anthropic`, its `latest` models) sorts after its vendor.
  */
-function vendorItems(models: ReadonlyArray<ModelEntry>, state: SessionViewState): Array<MenuItem> {
-  const current = currentModel(state);
-  const counts = new Map<string, number>();
+function vendorItems(
+  models: ReadonlyArray<ModelEntry>,
+  state: SessionViewState,
+): Array<MenuItem> {
+  const current = currentModel(state)
+  const counts = new Map<string, number>()
   for (const model of models) {
-    const [vendor = ""] = model.id.split("/");
-    counts.set(vendor, (counts.get(vendor) ?? 0) + 1);
+    const [vendor = ''] = model.id.split('/')
+    counts.set(vendor, (counts.get(vendor) ?? 0) + 1)
   }
   return [...counts]
     .sort(
-      ([a], [b]) => a.replace(/^~/, "").localeCompare(b.replace(/^~/, "")) || a.localeCompare(b),
+      ([a], [b]) =>
+        a.replace(/^~/, '').localeCompare(b.replace(/^~/, '')) ||
+        a.localeCompare(b),
     )
     .map(([vendor, count]) => ({
       id: vendor,
       label: vendor,
       current: current.startsWith(`${vendor}/`),
       detail: modelCount(count),
-    }));
+    }))
 }
 
 const EFFORT_DETAIL: Record<string, string> = {
-  default: "the model decides",
-  off: "no thinking",
-  minimal: "the least thinking",
-  low: "fast, few tokens",
-  medium: "balanced",
-  high: "thinks longer",
-  xhigh: "thinks very long",
-  max: "the most the model can think",
-};
+  default: 'the model decides',
+  off: 'no thinking',
+  minimal: 'the least thinking',
+  low: 'fast, few tokens',
+  medium: 'balanced',
+  high: 'thinks longer',
+  xhigh: 'thinks very long',
+  max: 'the most the model can think',
+}
 
 /** The rows of the `/effort` picker: the levels the current model has. */
 function effortItems(state: SessionViewState): Array<MenuItem> {
-  const effort = state.config.find((item) => item.key === "effort")?.value;
-  const record = modelInfo[currentModel(state)]?.record;
-  const levels = record ? supportedReasoningLevels(record) : [];
-  return ["default", ...levels].map((name) => ({
+  const effort = state.config.find((item) => item.key === 'effort')?.value
+  const record = modelInfo[currentModel(state)]?.record
+  const levels = record ? supportedReasoningLevels(record) : []
+  return ['default', ...levels].map((name) => ({
     id: name,
     label: name,
     current: name === effort,
-    detail: EFFORT_DETAIL[name] ?? "",
-  }));
+    detail: EFFORT_DETAIL[name] ?? '',
+  }))
 }
 
 /** The rows of the `/resume` picker: the saved sessions, newest first. */
 async function sessionItems(state: SessionViewState): Promise<Array<MenuItem>> {
-  const sessions = await listSessions();
+  const sessions = await listSessions()
   return sessions.map((session) => ({
     id: session.id,
     label: session.id,
     current: session.id === state.threadId,
-    detail: `${new Date(session.updatedAt).toLocaleString(undefined, { dateStyle: "short", timeStyle: "short" })}  ${session.title.slice(0, 60)}`,
-  }));
+    detail: `${new Date(session.updatedAt).toLocaleString(undefined, { dateStyle: 'short', timeStyle: 'short' })}  ${session.title.slice(0, 60)}`,
+  }))
 }
 
 // The session the user picked with /resume. The CLI opens it after the
 // screen closes.
-let nextSession: string | undefined;
+let nextSession: string | undefined
 
 /** The session `/resume` picked, once. `undefined` when the user quit. */
 export function takeNextSession() {
-  const next = nextSession;
-  nextSession = undefined;
-  return next;
+  const next = nextSession
+  nextSession = undefined
+  return next
 }
 
 /** A list open over the input line, for example the `/connect` picker. */
 interface Picker {
-  title: string;
-  items: Array<MenuItem>;
-  pick: (item: MenuItem) => unknown;
+  title: string
+  items: Array<MenuItem>
+  pick: (item: MenuItem) => unknown
 }
 
 /**
@@ -269,16 +299,18 @@ interface Picker {
  * a feature turns on or off.
  */
 function Header({ view, width }: { view: SessionView; width: number }) {
-  const keys = providerKeysIn(useSelector(view.store, (state) => state.plugins[PROVIDER_KEYS]));
-  const threadId = useSelector(view.store, (state) => state.threadId);
+  const keys = providerKeysIn(
+    useSelector(view.store, (state) => state.plugins[PROVIDER_KEYS]),
+  )
+  const threadId = useSelector(view.store, (state) => state.threadId)
   const marks = features.map((feature) => {
-    const on = isOn(feature, keys);
+    const on = isOn(feature, keys)
     return {
       name: feature.name,
       on,
-      text: `${on ? "●" : "○"} ${feature.name}  `,
-    };
-  });
+      text: `${on ? '●' : '○'} ${feature.name}  `,
+    }
+  })
   return (
     <Box
       width={width}
@@ -303,48 +335,50 @@ function Header({ view, width }: { view: SessionView; width: number }) {
       </Box>
       <Box>
         {marks.map((mark) => (
-          <Text key={mark.name} color={mark.on ? ACCENT : "gray"}>
+          <Text key={mark.name} color={mark.on ? ACCENT : 'gray'}>
             {mark.text}
           </Text>
         ))}
       </Box>
     </Box>
-  );
+  )
 }
 
 // Prompt in the input box. The bat emoji is two columns, then a space.
-const PROMPT = "🦇 ";
-const PROMPT_COLS = 3;
+const PROMPT = '🦇 '
+const PROMPT_COLS = 3
 
 function InputBox({
   line,
   voice,
   hidden,
 }: {
-  line: Line;
-  voice: VoiceState;
+  line: Line
+  voice: VoiceState
   /** The input is a secret (a key): show a dot for each character. */
-  hidden: boolean;
+  hidden: boolean
 }) {
-  const shown = hidden ? "•".repeat(line.text.length) : line.text;
+  const shown = hidden ? '•'.repeat(line.text.length) : line.text
   // The terminal cursor shows where you type (see `inputCursor`).
   return (
     <Box
       borderStyle="round"
-      borderColor={voice === "recording" ? "red" : voice === "idle" ? ACCENT : "gray"}
+      borderColor={
+        voice === 'recording' ? 'red' : voice === 'idle' ? ACCENT : 'gray'
+      }
       paddingX={1}
     >
       <Text color={ACCENT} bold>
         {PROMPT}
       </Text>
-      {shown === "" ? (
+      {shown === '' ? (
         // The cursor goes before the hint, so the hint does not look typed.
         <Text>
-          {" "}
+          {' '}
           <Text dimColor>
             {hidden
-              ? " Paste the key. It stays hidden."
-              : " Speak, commissioner. / for commands, @file to attach, Ctrl+R to talk"}
+              ? ' Paste the key. It stays hidden.'
+              : ' Speak, commissioner. / for commands, @file to attach, Ctrl+R to talk'}
           </Text>
         </Text>
       ) : (
@@ -352,7 +386,7 @@ function InputBox({
         <Text wrap="hard">{shown}</Text>
       )}
     </Box>
-  );
+  )
 }
 
 /**
@@ -361,20 +395,20 @@ function InputBox({
  * the row and the column of the line's cursor.
  */
 function inputCursor(line: Line, width: number, top: number) {
-  const before = 2 + PROMPT_COLS;
-  const textWidth = Math.max(1, width - before - 2);
+  const before = 2 + PROMPT_COLS
+  const textWidth = Math.max(1, width - before - 2)
   return {
     x: before + (line.cursor % textWidth),
     y: top + 1 + Math.floor(line.cursor / textWidth),
-  };
+  }
 }
 
 // A key held down repeats. Repeats closer than this are one press.
-const REPEAT_GAP = 1100;
+const REPEAT_GAP = 1100
 // After the last repeat, the key is up when no repeat comes for this long.
-const RELEASE_WAIT = 450;
+const RELEASE_WAIT = 450
 
-type Row = { id: "header" } | ViewMessage;
+type Row = { id: 'header' } | ViewMessage
 
 /** Reports its height once, when Ink prints it (Static prints a row once). */
 function Measured({
@@ -382,20 +416,20 @@ function Measured({
   onHeight,
   children,
 }: {
-  id: string;
-  onHeight: (id: string, height: number) => void;
-  children: ReactNode;
+  id: string
+  onHeight: (id: string, height: number) => void
+  children: ReactNode
 }) {
-  const ref = useRef<DOMElement>(null);
+  const ref = useRef<DOMElement>(null)
   // Ink lays out the frame before layout effects run, so the height is there.
   useLayoutEffect(() => {
-    if (ref.current) onHeight(id, measureElement(ref.current).height);
-  }, []);
+    if (ref.current) onHeight(id, measureElement(ref.current).height)
+  }, [])
   return (
     <Box ref={ref} flexDirection="column">
       {children}
     </Box>
-  );
+  )
 }
 
 /** One printed row: the header, or a message that no longer changes. */
@@ -405,41 +439,46 @@ function PrintedRow({
   saved,
   width,
 }: {
-  view: SessionView;
-  row: Row;
-  saved: ReturnType<typeof useSavedMedia>["saved"];
-  width: number;
+  view: SessionView
+  row: Row
+  saved: ReturnType<typeof useSavedMedia>['saved']
+  width: number
 }) {
-  return "role" in row ? (
+  return 'role' in row ? (
     <Message message={row} saved={saved} width={width} />
   ) : (
     <Header view={view} width={width} />
-  );
+  )
 }
 
 function App({ view }: { view: SessionView }) {
-  const { exit } = useApp();
-  const messages = useSelector(view.store, (state) => state.messages);
-  const running = useSelector(view.store, (state) => state.status === "running");
-  const { saved, saving } = useSavedMedia(view, messages);
+  const { exit } = useApp()
+  const messages = useSelector(view.store, (state) => state.messages)
+  const running = useSelector(view.store, (state) => state.status === 'running')
+  const { saved, saving } = useSavedMedia(view, messages)
   // The input line. A line typed while a question asks for a key stays hidden
   // until it is sent or deleted, also when the question ends first, so a key
   // never shows or goes out as a message.
-  const editor = useLineEditor();
-  const secretAsked = useSelector(view.store, (state) => state.questions.at(0)?.secret === true);
-  const asksSecret = () => view.store.get().questions.at(0)?.secret === true;
-  const commands = useSelector(view.store, (state) => state.commands);
+  const editor = useLineEditor()
+  const secretAsked = useSelector(
+    view.store,
+    (state) => state.questions.at(0)?.secret === true,
+  )
+  const asksSecret = () => view.store.get().questions.at(0)?.secret === true
+  const commands = useSelector(view.store, (state) => state.commands)
   const waiting = useSelector(
     view.store,
     (state) => state.questions.length > 0 || state.approvals.length > 0,
-  );
-  const [picker, setPicker] = useState<Picker | undefined>(undefined);
-  const [selected, setSelected] = useState(0);
+  )
+  const [picker, setPicker] = useState<Picker | undefined>(undefined)
+  const [selected, setSelected] = useState(0)
   // A line from the history keeps the arrows for the history.
-  const blocked = Boolean(picker || waiting || editor.line.hidden || editor.browsing);
-  const commandItems = blocked ? [] : suggestionsFor(editor.line.text, commands);
+  const blocked = Boolean(
+    picker || waiting || editor.line.hidden || editor.browsing,
+  )
+  const commandItems = blocked ? [] : suggestionsFor(editor.line.text, commands)
   // The files for an `@path`, read again only when the line changes.
-  const { text: lineText, cursor: lineCursor } = editor.line;
+  const { text: lineText, cursor: lineCursor } = editor.line
   const paths = useMemo(
     () =>
       blocked || commandItems.length > 0
@@ -450,17 +489,23 @@ function App({ view }: { view: SessionView }) {
             hidden: false,
           }),
     [blocked, commandItems.length, lineText, lineCursor],
-  );
+  )
   const suggestions: Array<(MenuItem & { takesInput: boolean }) | PathItem> =
-    commandItems.length > 0 ? commandItems : (paths?.items ?? []);
-  const [suggested, setSuggested] = useState(0);
-  useEffect(() => setSuggested(0), [editor.line.text]);
+    commandItems.length > 0 ? commandItems : (paths?.items ?? [])
+  const [suggested, setSuggested] = useState(0)
+  useEffect(() => setSuggested(0), [editor.line.text])
 
   // Messages that no longer change print once, above the live area. The
   // count only grows: a printed message is never printed again.
-  const printed = useRef(0);
-  printed.current = Math.max(printed.current, settledCount(messages, saving, running));
-  const rows: Array<Row> = [{ id: "header" }, ...messages.slice(0, printed.current)];
+  const printed = useRef(0)
+  printed.current = Math.max(
+    printed.current,
+    settledCount(messages, saving, running),
+  )
+  const rows: Array<Row> = [
+    { id: 'header' },
+    ...messages.slice(0, printed.current),
+  ]
 
   // The input sits at the bottom of the screen: until the printed rows fill
   // the screen, empty space above the live area fills the rest. Each row
@@ -468,81 +513,88 @@ function App({ view }: { view: SessionView }) {
   // as tall as the screen, so the frame stays one line shorter.
   // ponytail: the heights are from the width at print time. A resize makes
   // the space a little off until the screen is full.
-  const { columns, rows: screenRows } = useWindowSize();
-  const heights = useRef(new Map<string, number>());
-  const [, remeasure] = useReducer((count: number) => count + 1, 0);
+  const { columns, rows: screenRows } = useWindowSize()
+  const heights = useRef(new Map<string, number>())
+  const [, remeasure] = useReducer((count: number) => count + 1, 0)
   const onHeight = (id: string, height: number) => {
-    heights.current.set(id, height);
-    remeasure();
-  };
-  const printedHeight = rows.reduce((sum, row) => sum + (heights.current.get(row.id) ?? 0), 0);
-  const live = useRef<DOMElement>(null);
-  const { height: liveHeight } = useBoxMetrics(live);
-  const space = Math.max(0, screenRows - 1 - printedHeight - liveHeight);
+    heights.current.set(id, height)
+    remeasure()
+  }
+  const printedHeight = rows.reduce(
+    (sum, row) => sum + (heights.current.get(row.id) ?? 0),
+    0,
+  )
+  const live = useRef<DOMElement>(null)
+  const { height: liveHeight } = useBoxMetrics(live)
+  const space = Math.max(0, screenRows - 1 - printedHeight - liveHeight)
 
   // The terminal cursor sits in the input box, not under the screen. The
   // box is in the live area, which starts after the empty space.
-  const inputBox = useRef<DOMElement>(null);
-  const input = useBoxMetrics(inputBox);
-  const { setCursorPosition } = useCursor();
+  const inputBox = useRef<DOMElement>(null)
+  const input = useBoxMetrics(inputBox)
+  const { setCursorPosition } = useCursor()
   setCursorPosition(
-    input.hasMeasured ? inputCursor(editor.line, input.width, space + input.top) : undefined,
-  );
+    input.hasMeasured
+      ? inputCursor(editor.line, input.width, space + input.top)
+      : undefined,
+  )
 
   // The header shows which features are on, but printed rows never change.
   // So when a feature turns on or off (a /connect), clear the screen and
   // print the header and the conversation again.
-  const { stdout } = useStdout();
+  const { stdout } = useStdout()
   const featureMarks = useSelector(view.store, (state) => {
-    const keys = providerKeysIn(state.plugins[PROVIDER_KEYS]);
-    return features.map((feature) => (isOn(feature, keys) ? 1 : 0)).join("");
-  });
-  const shownMarks = useRef(featureMarks);
-  const [printRound, setPrintRound] = useState(0);
+    const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
+    return features.map((feature) => (isOn(feature, keys) ? 1 : 0)).join('')
+  })
+  const shownMarks = useRef(featureMarks)
+  const [printRound, setPrintRound] = useState(0)
   useEffect(() => {
-    if (featureMarks === shownMarks.current) return;
-    shownMarks.current = featureMarks;
-    if (stdout.isTTY) stdout.write("\x1b[2J\x1b[3J\x1b[H");
-    setPrintRound((round) => round + 1);
-  }, [featureMarks]);
+    if (featureMarks === shownMarks.current) return
+    shownMarks.current = featureMarks
+    if (stdout.isTTY) stdout.write('\x1b[2J\x1b[3J\x1b[H')
+    setPrintRound((round) => round + 1)
+  }, [featureMarks])
 
-  const [voice, setVoiceState] = useState<VoiceState>("idle");
+  const [voice, setVoiceState] = useState<VoiceState>('idle')
   // The phase in a ref too: key events come faster than React renders, and a
   // second Ctrl+R must see "starting" at once, or it starts a second recorder.
-  const phase = useRef<VoiceState>("idle");
+  const phase = useRef<VoiceState>('idle')
   const setVoice = (next: VoiceState) => {
-    phase.current = next;
-    setVoiceState(next);
-  };
-  const recording = useRef<Recording | undefined>(undefined);
-  const [recorder, setRecorder] = useState<Recording | undefined>(undefined);
+    phase.current = next
+    setVoiceState(next)
+  }
+  const recording = useRef<Recording | undefined>(undefined)
+  const [recorder, setRecorder] = useState<Recording | undefined>(undefined)
   const talk = useRef({
     last: 0,
     holding: false,
     stopWanted: false,
     cancelWanted: false,
-  });
-  const release = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
-  const voiceAbort = useRef<AbortController | undefined>(undefined);
+  })
+  const release = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  const voiceAbort = useRef<AbortController | undefined>(undefined)
 
   const fail = (error: unknown) =>
-    view.notice(error instanceof Error ? error.message : String(error));
+    view.notice(error instanceof Error ? error.message : String(error))
   const failVoice = (error: unknown) =>
-    view.notice(`Voice: ${error instanceof Error ? error.message : String(error)}`);
+    view.notice(
+      `Voice: ${error instanceof Error ? error.message : String(error)}`,
+    )
 
   const cancelVoice = () => {
-    voiceAbort.current?.abort();
-    voiceAbort.current = undefined;
-    clearTimeout(release.current);
-    talk.current.cancelWanted = true;
-    const current = recording.current;
+    voiceAbort.current?.abort()
+    voiceAbort.current = undefined
+    clearTimeout(release.current)
+    talk.current.cancelWanted = true
+    const current = recording.current
     if (current) {
-      recording.current = undefined;
-      setRecorder(undefined);
-      current.cancel();
+      recording.current = undefined
+      setRecorder(undefined)
+      current.cancel()
     }
-    setVoice("idle");
-  };
+    setVoice('idle')
+  }
 
   /**
    * A voice message: transcribe it, and put the words in the input line, with
@@ -550,74 +602,83 @@ function App({ view }: { view: SessionView }) {
    * then presses Enter to send it.
    */
   const hear = async (audio: Uint8Array, name: string, clip?: VoiceClip) => {
-    voiceAbort.current?.abort();
-    const abort = new AbortController();
-    voiceAbort.current = abort;
-    setVoice("transcribing");
+    voiceAbort.current?.abort()
+    const abort = new AbortController()
+    voiceAbort.current = abort
+    setVoice('transcribing')
     try {
       if (clip?.pickedMicrophone)
-        view.notice(`Voice: using "${clip.microphone}" from now on. /mic changes it.`);
+        view.notice(
+          `Voice: using "${clip.microphone}" from now on. /mic changes it.`,
+        )
       // Transcription models make up words for silence, so it is not sent.
       if (clip && isSilent(clip))
         return view.notice(
           `Voice: only silence from "${clip.microphone}". Hold Ctrl+R while you talk, or pick another microphone with /mic.`,
-        );
+        )
       const text = await transcribe(audio, {
         name,
         threadId: view.store.get().threadId,
         abortSignal: abort.signal,
-      });
-      if (abort.signal.aborted) return;
+      })
+      if (abort.signal.aborted) return
       // Drop the spinner before the file walk, so a big folder cannot
       // leave the transcribe line on the screen.
-      setVoice("idle");
-      if (text === "") return view.notice("Voice: no speech heard.");
+      setVoice('idle')
+      if (text === '') return view.notice('Voice: no speech heard.')
       const recent = saved.flatMap((item) =>
         item.path ? [{ kind: item.kind, path: item.path }] : [],
-      );
-      const message = await withSpokenFiles(text, [process.cwd(), mediaDir], recent);
-      if (abort.signal.aborted) return;
+      )
+      const message = await withSpokenFiles(
+        text,
+        [process.cwd(), mediaDir],
+        recent,
+      )
+      if (abort.signal.aborted) return
       // A key question keeps its line for the key only.
-      if (asksSecret()) return view.notice("Voice: answer the key question first.");
+      if (asksSecret())
+        return view.notice('Voice: answer the key question first.')
       // After what the user typed already, so nothing they typed is lost.
-      const typed = editor.line.text.trimEnd();
-      editor.set(typed === "" ? message.text : `${typed} ${message.text}`);
+      const typed = editor.line.text.trimEnd()
+      editor.set(typed === '' ? message.text : `${typed} ${message.text}`)
     } catch (error) {
-      if (abort.signal.aborted) return;
-      if (error instanceof Error && error.name === "TimeoutError") {
-        return view.notice("Voice: transcription stopped after 45 seconds. Try a shorter clip.");
+      if (abort.signal.aborted) return
+      if (error instanceof Error && error.name === 'TimeoutError') {
+        return view.notice(
+          'Voice: transcription stopped after 45 seconds. Try a shorter clip.',
+        )
       }
-      failVoice(error);
+      failVoice(error)
     } finally {
-      if (voiceAbort.current === abort) voiceAbort.current = undefined;
-      setVoice("idle");
+      if (voiceAbort.current === abort) voiceAbort.current = undefined
+      setVoice('idle')
     }
-  };
+  }
 
   const stopTalking = async () => {
-    clearTimeout(release.current);
-    const current = recording.current;
+    clearTimeout(release.current)
+    const current = recording.current
     if (!current) {
       // Still opening: stop as soon as it is open.
-      talk.current.stopWanted = true;
-      return;
+      talk.current.stopWanted = true
+      return
     }
-    recording.current = undefined;
-    setRecorder(undefined);
+    recording.current = undefined
+    setRecorder(undefined)
     await current.stop().then(
       (clip) => {
         if (talk.current.cancelWanted) {
-          setVoice("idle");
-          return;
+          setVoice('idle')
+          return
         }
-        return hear(clip.audio, "voice.wav", clip);
+        return hear(clip.audio, 'voice.wav', clip)
       },
       (error) => {
-        setVoice("idle");
-        failVoice(error);
+        setVoice('idle')
+        failVoice(error)
       },
-    );
-  };
+    )
+  }
 
   const startTalking = async () => {
     talk.current = {
@@ -625,29 +686,31 @@ function App({ view }: { view: SessionView }) {
       holding: false,
       stopWanted: false,
       cancelWanted: false,
-    };
+    }
     // "starting" before the key check, so a repeated Ctrl+R starts nothing.
-    setVoice("starting");
+    setVoice('starting')
     try {
       if (!(await canTranscribe(view.store.get().threadId))) {
-        setVoice("idle");
-        return view.notice("Voice: run /connect and pick OpenAI or xAI to turn voice on.");
+        setVoice('idle')
+        return view.notice(
+          'Voice: run /connect and pick OpenAI or xAI to turn voice on.',
+        )
       }
-      const started = await startRecording();
+      const started = await startRecording()
       if (talk.current.cancelWanted) {
-        started.cancel();
-        setVoice("idle");
-        return;
+        started.cancel()
+        setVoice('idle')
+        return
       }
-      recording.current = started;
-      setRecorder(started);
-      setVoice("recording");
-      if (talk.current.stopWanted) await stopTalking();
+      recording.current = started
+      setRecorder(started)
+      setVoice('recording')
+      if (talk.current.stopWanted) await stopTalking()
     } catch (error) {
-      setVoice("idle");
-      failVoice(error);
+      setVoice('idle')
+      failVoice(error)
     }
-  };
+  }
 
   /**
    * Ctrl+R. A terminal sends no key-up, only repeats while a key is held. So
@@ -655,282 +718,304 @@ function App({ view }: { view: SessionView }) {
    * starts, and the next single press stops.
    */
   const onTalkKey = () => {
-    const now = Date.now();
-    const gap = now - talk.current.last;
-    talk.current.last = now;
-    if (phase.current === "transcribing") {
-      cancelVoice();
-      return;
+    const now = Date.now()
+    const gap = now - talk.current.last
+    talk.current.last = now
+    if (phase.current === 'transcribing') {
+      cancelVoice()
+      return
     }
-    if (phase.current === "idle") return void startTalking();
+    if (phase.current === 'idle') return void startTalking()
     if (gap < REPEAT_GAP) {
-      talk.current.holding = true;
-      clearTimeout(release.current);
-      release.current = setTimeout(() => void stopTalking(), RELEASE_WAIT);
-      return;
+      talk.current.holding = true
+      clearTimeout(release.current)
+      release.current = setTimeout(() => void stopTalking(), RELEASE_WAIT)
+      return
     }
-    if (!talk.current.holding) void stopTalking();
-  };
+    if (!talk.current.holding) void stopTalking()
+  }
 
   /** The saved media file `/open 2` or `/play` names. */
   const pick = (arg: string | undefined) => {
-    const ready = saved.filter((item) => item.path !== undefined);
-    const item = arg ? ready.find((entry) => entry.number === Number(arg)) : ready.at(-1);
+    const ready = saved.filter((item) => item.path !== undefined)
+    const item = arg
+      ? ready.find((entry) => entry.number === Number(arg))
+      : ready.at(-1)
     if (!item?.path) {
-      view.notice(arg ? `No saved media file ${arg}.` : "No media file yet.");
-      return undefined;
+      view.notice(arg ? `No saved media file ${arg}.` : 'No media file yet.')
+      return undefined
     }
-    return { ...item, path: item.path };
-  };
+    return { ...item, path: item.path }
+  }
 
   const openPicker = (next: Picker) => {
-    if (next.items.length === 0) return view.notice(`${next.title}: nothing to pick.`);
+    if (next.items.length === 0)
+      return view.notice(`${next.title}: nothing to pick.`)
     setSelected(
       Math.max(
         0,
         next.items.findIndex((item) => item.current),
       ),
-    );
-    setPicker(next);
-  };
+    )
+    setPicker(next)
+  }
 
   const pickMicrophone = async () => {
-    const names = await listMicrophones();
-    const current = await currentMicrophone();
+    const names = await listMicrophones()
+    const current = await currentMicrophone()
     if (names.length === 0)
-      return view.notice(`Recording from the default input${current ? ` (${current})` : ""}.`);
+      return view.notice(
+        `Recording from the default input${current ? ` (${current})` : ''}.`,
+      )
     openPicker({
-      title: "Record from which microphone?",
+      title: 'Record from which microphone?',
       items: names.map((name) => ({
         id: name,
         label: name,
         current: name === current,
       })),
       pick: async (item) => {
-        await chooseMicrophone(item.id);
-        view.notice(`Voice: recording from "${item.id}".`);
+        await chooseMicrophone(item.id)
+        view.notice(`Voice: recording from "${item.id}".`)
       },
-    });
-  };
+    })
+  }
 
   /** Pick a model of the provider `id`. OpenRouter asks for the vendor first. */
   const pickModelOf = (id: string) => {
-    if (id === "demo") return view.command("model", "demo");
-    const provider = modelProviders.find((entry) => entry.id === id);
-    if (!provider) return;
-    const state = view.store.get();
+    if (id === 'demo') return view.command('model', 'demo')
+    const provider = modelProviders.find((entry) => entry.id === id)
+    if (!provider) return
+    const state = view.store.get()
     const pickModel = (title: string, models: ReadonlyArray<ModelEntry>) =>
       openPicker({
         title,
         items: modelRows(models, state),
-        pick: (item) => view.command("model", item.id),
-      });
-    if (provider.id !== "openrouter")
-      return pickModel(`${provider.label}: pick the model`, provider.models);
+        pick: (item) => view.command('model', item.id),
+      })
+    if (provider.id !== 'openrouter')
+      return pickModel(`${provider.label}: pick the model`, provider.models)
     openPicker({
-      title: "OpenRouter: pick the vendor",
+      title: 'OpenRouter: pick the vendor',
       items: vendorItems(provider.models, state),
       pick: (vendor) =>
         pickModel(
           `OpenRouter: pick the ${vendor.id} model`,
-          provider.models.filter((model) => model.id.startsWith(`${vendor.id}/`)),
+          provider.models.filter((model) =>
+            model.id.startsWith(`${vendor.id}/`),
+          ),
         ),
-    });
-  };
+    })
+  }
 
   /** Close the screen, and the CLI opens the saved session `id`. */
   const resume = async (id: string) => {
-    if (id === view.store.get().threadId) return view.notice("You are in this session.");
-    if (!(await hasSession(id))) return view.notice(`No saved session ${id}. /resume lists them.`);
-    nextSession = id;
-    exit();
-  };
+    if (id === view.store.get().threadId)
+      return view.notice('You are in this session.')
+    if (!(await hasSession(id)))
+      return view.notice(`No saved session ${id}. /resume lists them.`)
+    nextSession = id
+    exit()
+  }
 
   /** Enter: answer an approval or a question, run a screen command, or send. */
   const submit = async (line: Line) => {
-    const text = line.text.trim();
-    const state = view.store.get();
-    const [question] = state.questions;
+    const text = line.text.trim()
+    const state = view.store.get()
+    const [question] = state.questions
     if (question?.secret) {
       // The key goes as it is. The screen does not show it anywhere.
-      await question.answer(text);
-      return;
+      await question.answer(text)
+      return
     }
     if (line.hidden) {
       // The question ended before Enter: drop the key, do not send it.
-      view.notice("The key question ended, so the key was not used.");
-      return;
+      view.notice('The key question ended, so the key was not used.')
+      return
     }
     if (state.approvals.length > 0) {
-      if (/^y(es)?$/i.test(text)) view.approveAll();
-      else view.rejectAll();
-      return;
+      if (/^y(es)?$/i.test(text)) view.approveAll()
+      else view.rejectAll()
+      return
     }
     if (question) {
-      const answer = /^y(es)?$/i.test(text) ? true : /^no?$/i.test(text) ? false : text;
-      await question.answer(answer);
-      return;
+      const answer = /^y(es)?$/i.test(text)
+        ? true
+        : /^no?$/i.test(text)
+          ? false
+          : text
+      await question.answer(answer)
+      return
     }
-    const [command, ...rest] = text.split(" ");
-    const arg = rest.join(" ").trim() || undefined;
+    const [command, ...rest] = text.split(' ')
+    const arg = rest.join(' ').trim() || undefined
     switch (command) {
-      case "/exit":
-        return exit();
-      case "/help": {
-        const keys = providerKeysIn(state.plugins[PROVIDER_KEYS]);
+      case '/exit':
+        return exit()
+      case '/help': {
+        const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
         const off = features
           .filter((feature) => !isOn(feature, keys))
-          .map((feature) => `  ${feature.name} is off: it needs ${feature.needs}.`);
-        const list = suggestionsFor("/", state.commands).map(
-          (item) => `${item.label.padEnd(14)}${item.detail ?? ""}`,
-        );
-        return view.notice([...HELP, ...off, ...list].join("\n"));
+          .map(
+            (feature) => `  ${feature.name} is off: it needs ${feature.needs}.`,
+          )
+        const list = suggestionsFor('/', state.commands).map(
+          (item) => `${item.label.padEnd(14)}${item.detail ?? ''}`,
+        )
+        return view.notice([...HELP, ...off, ...list].join('\n'))
       }
-      case "/connect":
-        if (arg) return view.command(`connect:${arg}`);
+      case '/connect':
+        if (arg) return view.command(`connect:${arg}`)
         return openPicker({
-          title: "Connect to what?",
+          title: 'Connect to what?',
           items: connectItems(state),
           pick: (item) => view.command(`connect:${item.id}`),
-        });
-      case "/disconnect": {
-        if (arg) return view.command(`disconnect:${arg}`);
+        })
+      case '/disconnect': {
+        if (arg) return view.command(`disconnect:${arg}`)
         // A key from the environment cannot be removed here, so it is not listed.
-        const keys = providerKeysIn(state.plugins[PROVIDER_KEYS]);
+        const keys = providerKeysIn(state.plugins[PROVIDER_KEYS])
         return openPicker({
-          title: "Remove which key or sign-in?",
+          title: 'Remove which key or sign-in?',
           items: connectItems(state).filter(
-            (item) => !keys.some((key) => key.id === item.id && key.state !== "connected"),
+            (item) =>
+              !keys.some(
+                (key) => key.id === item.id && key.state !== 'connected',
+              ),
           ),
           pick: (item) => view.command(`disconnect:${item.id}`),
-        });
+        })
       }
-      case "/model":
-        if (arg) break;
+      case '/model':
+        if (arg) break
         return openPicker({
-          title: "Pick the provider",
+          title: 'Pick the provider',
           items: providerItems(state),
           pick: (item) => pickModelOf(item.id),
-        });
-      case "/effort":
-        if (arg) break;
+        })
+      case '/effort':
+        if (arg) break
         if (!reasons(currentModel(state)))
           return view.notice(
             `${currentModel(state)} has no effort setting. Pick another model with /model.`,
-          );
+          )
         return openPicker({
-          title: "How hard should the model think?",
+          title: 'How hard should the model think?',
           items: effortItems(state),
-          pick: (item) => view.command("effort", item.id),
-        });
-      case "/resume":
-        if (arg) return resume(arg);
+          pick: (item) => view.command('effort', item.id),
+        })
+      case '/resume':
+        if (arg) return resume(arg)
         return openPicker({
-          title: "Continue which session?",
+          title: 'Continue which session?',
           items: await sessionItems(state),
           pick: (item) => resume(item.id),
-        });
-      case "/mic": {
-        if (!arg) return pickMicrophone().catch(failVoice);
-        const names = await listMicrophones().catch(() => []);
-        const chosen = names[Number(arg) - 1];
-        if (!chosen) return view.notice(`No microphone ${arg}. /mic lists them.`);
-        await chooseMicrophone(chosen);
-        return view.notice(`Voice: recording from "${chosen}".`);
+        })
+      case '/mic': {
+        if (!arg) return pickMicrophone().catch(failVoice)
+        const names = await listMicrophones().catch(() => [])
+        const chosen = names[Number(arg) - 1]
+        if (!chosen)
+          return view.notice(`No microphone ${arg}. /mic lists them.`)
+        await chooseMicrophone(chosen)
+        return view.notice(`Voice: recording from "${chosen}".`)
       }
-      case "/voice": {
-        if (!arg) return view.notice("Give an audio file: /voice note.m4a");
-        const path = arg.replace(/^@|^"|"$/g, "");
-        const audio = await readFile(path).catch(failVoice);
-        if (audio) await hear(new Uint8Array(audio), basename(path));
-        return;
+      case '/voice': {
+        if (!arg) return view.notice('Give an audio file: /voice note.m4a')
+        const path = arg.replace(/^@|^"|"$/g, '')
+        const audio = await readFile(path).catch(failVoice)
+        if (audio) await hear(new Uint8Array(audio), basename(path))
+        return
       }
-      case "/open":
-      case "/play": {
-        const item = pick(arg);
-        if (!item) return;
-        if (command === "/play" && item.kind !== "image") play(item);
-        else openExternal(item.path);
-        return;
+      case '/open':
+      case '/play': {
+        const item = pick(arg)
+        if (!item) return
+        if (command === '/play' && item.kind !== 'image') play(item)
+        else openExternal(item.path)
+        return
       }
     }
-    await view.send(text);
-  };
+    await view.send(text)
+  }
 
   /** Send a line and keep it for the up arrow, unless it is a key or an answer. */
   const send = (line: Line) => {
-    const state = view.store.get();
-    const isAnswer = state.questions.length > 0 || state.approvals.length > 0;
-    if (!line.hidden && !isAnswer) editor.remember(line.text);
-    editor.clear();
-    submit(line).catch(fail);
-  };
+    const state = view.store.get()
+    const isAnswer = state.questions.length > 0 || state.approvals.length > 0
+    if (!line.hidden && !isAnswer) editor.remember(line.text)
+    editor.clear()
+    submit(line).catch(fail)
+  }
 
-  usePaste((text) => editor.insert(text, asksSecret()));
+  usePaste((text) => editor.insert(text, asksSecret()))
 
   useInput((character, key) => {
-    if (key.ctrl && (character === "r" || character === "R")) return onTalkKey();
+    if (key.ctrl && (character === 'r' || character === 'R')) return onTalkKey()
     if (picker) {
-      const count = picker.items.length;
-      const number = Number(character);
+      const count = picker.items.length
+      const number = Number(character)
       const chosen = key.return
         ? picker.items[selected]
         : Number.isInteger(number) && number >= 1
           ? picker.items[number - 1]
-          : undefined;
-      if (key.escape || chosen) setPicker(undefined);
-      if (chosen) Promise.resolve(picker.pick(chosen)).catch(fail);
-      if (key.upArrow) setSelected((index) => (index - 1 + count) % count);
-      if (key.downArrow) setSelected((index) => (index + 1) % count);
-      return;
+          : undefined
+      if (key.escape || chosen) setPicker(undefined)
+      if (chosen) Promise.resolve(picker.pick(chosen)).catch(fail)
+      if (key.upArrow) setSelected((index) => (index - 1 + count) % count)
+      if (key.downArrow) setSelected((index) => (index + 1) % count)
+      return
     }
     if (key.escape) {
       if (
-        phase.current === "starting" ||
-        phase.current === "recording" ||
-        phase.current === "transcribing"
+        phase.current === 'starting' ||
+        phase.current === 'recording' ||
+        phase.current === 'transcribing'
       ) {
-        cancelVoice();
-        return;
+        cancelVoice()
+        return
       }
-      if (view.store.get().status === "running") void view.cancel();
-      else editor.clear();
-      return;
+      if (view.store.get().status === 'running') void view.cancel()
+      else editor.clear()
+      return
     }
-    const suggestion = suggestions[Math.min(suggested, suggestions.length - 1)];
+    const suggestion = suggestions[Math.min(suggested, suggestions.length - 1)]
     if (suggestion) {
-      const count = suggestions.length;
-      if (key.upArrow) return setSuggested((index) => (index - 1 + count) % count);
-      if (key.downArrow) return setSuggested((index) => (index + 1) % count);
-      if ("fill" in suggestion) {
+      const count = suggestions.length
+      if (key.upArrow)
+        return setSuggested((index) => (index - 1 + count) % count)
+      if (key.downArrow) return setSuggested((index) => (index + 1) % count)
+      if ('fill' in suggestion) {
         // Put the path in place of the typed `@` token.
         if (key.tab || key.return) {
-          const { text, cursor } = editor.line;
-          const filled = text.slice(0, paths?.start ?? cursor) + suggestion.fill;
-          return editor.set(filled + text.slice(cursor), filled.length);
+          const { text, cursor } = editor.line
+          const filled = text.slice(0, paths?.start ?? cursor) + suggestion.fill
+          return editor.set(filled + text.slice(cursor), filled.length)
         }
       } else {
-        if (key.tab) return editor.set(`/${suggestion.id} `);
+        if (key.tab) return editor.set(`/${suggestion.id} `)
         if (key.return) {
-          if (suggestion.takesInput) return editor.set(`/${suggestion.id} `);
-          return send({ text: `/${suggestion.id}`, cursor: 0, hidden: false });
+          if (suggestion.takesInput) return editor.set(`/${suggestion.id} `)
+          return send({ text: `/${suggestion.id}`, cursor: 0, hidden: false })
         }
       }
     }
-    if (key.upArrow) return editor.older();
-    if (key.downArrow) return editor.newer();
-    if (key.leftArrow) return editor.move(-1);
-    if (key.rightArrow) return editor.move(1);
-    if (key.home) return editor.move("start");
-    if (key.end) return editor.move("end");
+    if (key.upArrow) return editor.older()
+    if (key.downArrow) return editor.newer()
+    if (key.leftArrow) return editor.move(-1)
+    if (key.rightArrow) return editor.move(1)
+    if (key.home) return editor.move('start')
+    if (key.end) return editor.move('end')
     if (key.return) {
-      if (phase.current === "recording" || phase.current === "starting") return void stopTalking();
-      return send(editor.line);
+      if (phase.current === 'recording' || phase.current === 'starting')
+        return void stopTalking()
+      return send(editor.line)
     }
     // Most terminals send Backspace as the delete key.
-    if (key.backspace || key.delete) return editor.backspace();
-    if (!key.ctrl && !key.meta && !key.tab && character) editor.insert(character, asksSecret());
-  });
+    if (key.backspace || key.delete) return editor.backspace()
+    if (!key.ctrl && !key.meta && !key.tab && character)
+      editor.insert(character, asksSecret())
+  })
 
   return (
     <Box flexDirection="column">
@@ -944,7 +1029,12 @@ function App({ view }: { view: SessionView }) {
       {space > 0 ? <Box height={space} /> : null}
       <Box ref={live} flexDirection="column">
         {messages.slice(printed.current).map((message) => (
-          <Message key={message.id} message={message} saved={saved} width={columns} />
+          <Message
+            key={message.id}
+            message={message}
+            saved={saved}
+            width={columns}
+          />
         ))}
         <Status view={view} voice={voice} recording={recorder} />
         {/* A column, so the input box keeps the full width. */}
@@ -952,7 +1042,9 @@ function App({ view }: { view: SessionView }) {
           <InputBox
             line={editor.line}
             voice={voice}
-            hidden={secretAsked || (editor.line.hidden && editor.line.text !== "")}
+            hidden={
+              secretAsked || (editor.line.hidden && editor.line.text !== '')
+            }
           />
         </Box>
         {picker ? (
@@ -968,19 +1060,19 @@ function App({ view }: { view: SessionView }) {
             selected={Math.min(suggested, suggestions.length - 1)}
             hint={
               commandItems.length > 0
-                ? "↑↓ move   Tab fills   Enter runs"
-                : "↑↓ move   Tab or Enter fills"
+                ? '↑↓ move   Tab fills   Enter runs'
+                : '↑↓ move   Tab or Enter fills'
             }
           />
         ) : null}
         <Footer view={view} />
       </Box>
     </Box>
-  );
+  )
 }
 
 // The boot splash shows once in a process.
-let splashShown = false;
+let splashShown = false
 
 /**
  * The Ink screen for `runCli({ ui })`. It clears the terminal, opens sign-in
@@ -989,50 +1081,54 @@ let splashShown = false;
  * or presses Ctrl+C. `io` replaces the terminal, for a test.
  */
 export async function runTui(view: SessionView, io: RenderOptions = {}) {
-  view.on("signIn", (signIn) => {
-    if (signIn.url) openExternal(signIn.url);
-  });
-  const keys = providerKeysIn(view.store.get().plugins[PROVIDER_KEYS]);
-  if (keys.every((key) => key.state === "missing"))
-    view.notice("🦇 The cave is dark. Type /connect and pick OpenRouter to light the signal.");
+  view.on('signIn', (signIn) => {
+    if (signIn.url) openExternal(signIn.url)
+  })
+  const keys = providerKeysIn(view.store.get().plugins[PROVIDER_KEYS])
+  if (keys.every((key) => key.state === 'missing'))
+    view.notice(
+      '🦇 The cave is dark. Type /connect and pick OpenRouter to light the signal.',
+    )
   // Start on a clean terminal: clear the screen and the scrollback. The
   // splash shows once, at the first start, not again after a /resume.
   const clear = () => {
-    if (!io.stdout && process.stdout.isTTY) process.stdout.write("\x1b[2J\x1b[3J\x1b[H");
-  };
+    if (!io.stdout && process.stdout.isTTY)
+      process.stdout.write('\x1b[2J\x1b[3J\x1b[H')
+  }
   if (!splashShown && (io.stdout ?? process.stdout).isTTY) {
-    splashShown = true;
-    clear();
-    await showSplash(io);
+    splashShown = true
+    clear()
+    await showSplash(io)
   }
-  clear();
-  const app = render(<App view={view} />, io);
+  clear()
+  const app = render(<App view={view} />, io)
   // ponytail: the SDK logs its warnings and errors on the console (the
   // message, then its details with console.dir), and the code highlighter
   // warns about languages it does not know. Ink prints console output above
   // the screen, and the screen shows the errors itself, so it drops them.
   // This wraps the console after render(), because render() replaces it.
-  const before = { warn: console.warn, error: console.error, dir: console.dir };
-  let dropDetails = false;
+  const before = { warn: console.warn, error: console.error, dir: console.dir }
+  let dropDetails = false
   const quiet =
     (log: (...args: Array<unknown>) => void) =>
     (...args: Array<unknown>) => {
-      const text = typeof args[0] === "string" ? args[0] : "";
-      dropDetails = /\[tanstack-ai:(warn|errors)\]|Could not find the language/.test(text);
-      if (!dropDetails) log(...args);
-    };
-  const quietWarn = quiet(before.warn);
-  console.warn = quietWarn;
-  console.error = quiet(before.error);
+      const text = typeof args[0] === 'string' ? args[0] : ''
+      dropDetails =
+        /\[tanstack-ai:(warn|errors)\]|Could not find the language/.test(text)
+      if (!dropDetails) log(...args)
+    }
+  const quietWarn = quiet(before.warn)
+  console.warn = quietWarn
+  console.error = quiet(before.error)
   console.dir = (...args: Parameters<typeof console.dir>) => {
-    if (dropDetails) dropDetails = false;
-    else before.dir(...args);
-  };
+    if (dropDetails) dropDetails = false
+    else before.dir(...args)
+  }
   try {
-    await app.waitUntilExit();
+    await app.waitUntilExit()
   } finally {
     // Ink puts the first console back when it stops. Without its console
     // (`patchConsole: false`), the screen puts it back itself.
-    if (console.warn === quietWarn) Object.assign(console, before);
+    if (console.warn === quietWarn) Object.assign(console, before)
   }
 }
diff --git a/examples/harness-cli-batman/src/voice.ts b/examples/harness-cli-batman/src/voice.ts
index b129d71231..53571e3bf9 100644
--- a/examples/harness-cli-batman/src/voice.ts
+++ b/examples/harness-cli-batman/src/voice.ts
@@ -1,25 +1,25 @@
-import { execFile, spawn } from "node:child_process";
-import type { ChildProcess } from "node:child_process";
-import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
-import { basename, dirname, extname, join, relative } from "node:path";
-import { generateTranscription } from "@tanstack/ai";
-import { createGrokTranscription } from "@tanstack/ai-grok";
-import { grokByok } from "@tanstack/ai-grok/byok";
-import { createOpenaiTranscription } from "@tanstack/ai-openai";
-import { openaiByok } from "@tanstack/ai-openai/byok";
-import { SAVE_DIR } from "./credentials";
-import { providerKey } from "./store";
+import { execFile, spawn } from 'node:child_process'
+import type { ChildProcess } from 'node:child_process'
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
+import { basename, dirname, extname, join, relative } from 'node:path'
+import { generateTranscription } from '@tanstack/ai'
+import { createGrokTranscription } from '@tanstack/ai-grok'
+import { grokByok } from '@tanstack/ai-grok/byok'
+import { createOpenaiTranscription } from '@tanstack/ai-openai'
+import { openaiByok } from '@tanstack/ai-openai/byok'
+import { SAVE_DIR } from './credentials'
+import { providerKey } from './store'
 
 // Voice input for the terminal: ffmpeg records the microphone, a
 // transcription model turns it into text, and spoken file names become
 // `@path` attachments that the CLI sends with the message.
 
-const ffmpeg = process.env.FFMPEG_PATH || "ffmpeg";
-const RATE = 16000;
-const TRANSCRIBE_MS = 45_000;
-const MAX_SPOKEN_FILES = 400;
+const ffmpeg = process.env.FFMPEG_PATH || 'ffmpeg'
+const RATE = 16000
+const TRANSCRIBE_MS = 45_000
+const MAX_SPOKEN_FILES = 400
 // The microphone you picked, kept next to the sign-ins.
-const saved = join(SAVE_DIR, "voice.json");
+const saved = join(SAVE_DIR, 'voice.json')
 
 /**
  * Can the session of `threadId` turn speech into text? It needs an OpenAI or
@@ -29,8 +29,8 @@ export async function canTranscribe(threadId: string) {
   const keys = await Promise.all([
     providerKey(openaiByok, threadId),
     providerKey(grokByok, threadId),
-  ]);
-  return keys.some((key) => key !== null);
+  ])
+  return keys.some((key) => key !== null)
 }
 
 /**
@@ -38,47 +38,53 @@ export async function canTranscribe(threadId: string) {
  * record the default input, so this is empty there.
  */
 export function listMicrophones() {
-  if (process.platform !== "win32") return Promise.resolve<Array<string>>([]);
+  if (process.platform !== 'win32') return Promise.resolve<Array<string>>([])
   return new Promise<Array<string>>((resolve, reject) => {
     execFile(
       ffmpeg,
-      ["-hide_banner", "-list_devices", "true", "-f", "dshow", "-i", "dummy"],
+      ['-hide_banner', '-list_devices', 'true', '-f', 'dshow', '-i', 'dummy'],
       (error, _stdout, stderr) => {
-        if (error?.code === "ENOENT")
-          return reject(new Error("Voice needs ffmpeg on the PATH (or FFMPEG_PATH)."));
-        resolve([...stderr.matchAll(/"([^"]+)" \(audio\)/g)].map((match) => match[1] ?? ""));
+        if (error?.code === 'ENOENT')
+          return reject(
+            new Error('Voice needs ffmpeg on the PATH (or FFMPEG_PATH).'),
+          )
+        resolve(
+          [...stderr.matchAll(/"([^"]+)" \(audio\)/g)].map(
+            (match) => match[1] ?? '',
+          ),
+        )
       },
-    );
-  });
+    )
+  })
 }
 
 // The microphone `/mic <n>` picked, or the first recording found.
-let picked: string | undefined;
+let picked: string | undefined
 
 /** Record from this microphone from now on, also after a restart. */
 export async function chooseMicrophone(name: string) {
-  picked = name;
-  await mkdir(dirname(saved), { recursive: true });
-  await writeFile(saved, JSON.stringify({ microphone: name }, null, 2));
+  picked = name
+  await mkdir(dirname(saved), { recursive: true })
+  await writeFile(saved, JSON.stringify({ microphone: name }, null, 2))
 }
 
 /** The microphone to record from, when one is set: VOICE_DEVICE, then yours. */
 export async function currentMicrophone() {
-  if (process.env.VOICE_DEVICE) return process.env.VOICE_DEVICE;
-  if (picked) return picked;
+  if (process.env.VOICE_DEVICE) return process.env.VOICE_DEVICE
+  if (picked) return picked
   try {
-    const parsed: unknown = JSON.parse(await readFile(saved, "utf8"));
+    const parsed: unknown = JSON.parse(await readFile(saved, 'utf8'))
     if (
-      typeof parsed === "object" &&
+      typeof parsed === 'object' &&
       parsed !== null &&
-      "microphone" in parsed &&
-      typeof parsed.microphone === "string"
+      'microphone' in parsed &&
+      typeof parsed.microphone === 'string'
     )
-      picked = parsed.microphone;
+      picked = parsed.microphone
   } catch {
     // No saved microphone yet.
   }
-  return picked;
+  return picked
 }
 
 /**
@@ -86,33 +92,39 @@ export async function currentMicrophone() {
  * cards and virtual inputs (they are often silent).
  */
 async function candidateMicrophones() {
-  const names = await listMicrophones();
-  const real = names.filter((name) => !/hdmi|cam link|virtual|stereo mix|line in/i.test(name));
-  return real.length > 0 ? real : names;
+  const names = await listMicrophones()
+  const real = names.filter(
+    (name) => !/hdmi|cam link|virtual|stereo mix|line in/i.test(name),
+  )
+  return real.length > 0 ? real : names
 }
 
 /** The ffmpeg input arguments for one microphone. */
 function microphoneInput(name: string | undefined) {
-  if (process.platform === "win32") return ["-f", "dshow", "-i", `audio=${name}`];
-  if (process.platform === "darwin") return ["-f", "avfoundation", "-i", `:${name ?? "0"}`];
-  return ["-f", "pulse", "-i", name ?? "default"];
+  if (process.platform === 'win32')
+    return ['-f', 'dshow', '-i', `audio=${name}`]
+  if (process.platform === 'darwin')
+    return ['-f', 'avfoundation', '-i', `:${name ?? '0'}`]
+  return ['-f', 'pulse', '-i', name ?? 'default']
 }
 
 /** The root mean square of 16-bit samples, without a constant offset. */
 function rms(samples: Int16Array) {
-  if (samples.length === 0) return 0;
-  let sum = 0;
-  let squares = 0;
+  if (samples.length === 0) return 0
+  let sum = 0
+  let squares = 0
   for (const sample of samples) {
-    sum += sample;
-    squares += sample * sample;
+    sum += sample
+    squares += sample * sample
   }
-  const mean = sum / samples.length;
-  return Math.sqrt(Math.max(0, squares / samples.length - mean * mean));
+  const mean = sum / samples.length
+  return Math.sqrt(Math.max(0, squares / samples.length - mean * mean))
 }
 
 function samplesOf(pcm: Uint8Array) {
-  return new Int16Array(pcm.buffer.slice(pcm.byteOffset, pcm.byteOffset + (pcm.byteLength & ~1)));
+  return new Int16Array(
+    pcm.buffer.slice(pcm.byteOffset, pcm.byteOffset + (pcm.byteLength & ~1)),
+  )
 }
 
 /**
@@ -123,101 +135,102 @@ function samplesOf(pcm: Uint8Array) {
  * clicks do not, so they read as silence.
  */
 export function speechStats(pcm: Uint8Array) {
-  const samples = samplesOf(pcm);
-  const size = RATE / 10;
-  const windows: Array<number> = [];
+  const samples = samplesOf(pcm)
+  const size = RATE / 10
+  const windows: Array<number> = []
   for (let start = 0; start + size <= samples.length; start += size)
-    windows.push(rms(samples.subarray(start, start + size)));
-  windows.sort((a, b) => a - b);
+    windows.push(rms(samples.subarray(start, start + size)))
+  windows.sort((a, b) => a - b)
   const at = (share: number) =>
-    windows[Math.min(windows.length - 1, Math.floor(windows.length * share))] ?? 0;
-  return { peak: at(0.9), floor: at(0.2) };
+    windows[Math.min(windows.length - 1, Math.floor(windows.length * share))] ??
+    0
+  return { peak: at(0.9), floor: at(0.2) }
 }
 
 /** How clearly a clip holds speech: the peak over the noise floor. */
 function speechScore(stats: { peak: number; floor: number }) {
-  return stats.peak / Math.max(stats.floor, 30);
+  return stats.peak / Math.max(stats.floor, 30)
 }
 
 /** A 16 kHz mono 16-bit WAV file for raw samples. */
 function wavFile(pcm: Uint8Array) {
-  const header = new DataView(new ArrayBuffer(44));
+  const header = new DataView(new ArrayBuffer(44))
   const text = (offset: number, value: string) => {
     for (let index = 0; index < 4; index++)
-      header.setUint8(offset + index, value.charCodeAt(index));
-  };
-  text(0, "RIFF");
-  header.setUint32(4, 36 + pcm.byteLength, true);
-  text(8, "WAVE");
-  text(12, "fmt ");
-  header.setUint32(16, 16, true);
-  header.setUint16(20, 1, true);
-  header.setUint16(22, 1, true);
-  header.setUint32(24, RATE, true);
-  header.setUint32(28, RATE * 2, true);
-  header.setUint16(32, 2, true);
-  header.setUint16(34, 16, true);
-  text(36, "data");
-  header.setUint32(40, pcm.byteLength, true);
-  const file = new Uint8Array(44 + pcm.byteLength);
-  file.set(new Uint8Array(header.buffer));
-  file.set(pcm, 44);
-  return file;
+      header.setUint8(offset + index, value.charCodeAt(index))
+  }
+  text(0, 'RIFF')
+  header.setUint32(4, 36 + pcm.byteLength, true)
+  text(8, 'WAVE')
+  text(12, 'fmt ')
+  header.setUint32(16, 16, true)
+  header.setUint16(20, 1, true)
+  header.setUint16(22, 1, true)
+  header.setUint32(24, RATE, true)
+  header.setUint32(28, RATE * 2, true)
+  header.setUint16(32, 2, true)
+  header.setUint16(34, 16, true)
+  text(36, 'data')
+  header.setUint32(40, pcm.byteLength, true)
+  const file = new Uint8Array(44 + pcm.byteLength)
+  file.set(new Uint8Array(header.buffer))
+  file.set(pcm, 44)
+  return file
 }
 
 // Every ffmpeg recorder that runs. They are stopped when the app exits, so no
 // recorder keeps the microphone open after it.
-const recorders = new Set<ChildProcess>();
-process.once("exit", () => {
-  for (const child of recorders) child.kill();
-});
+const recorders = new Set<ChildProcess>()
+process.once('exit', () => {
+  for (const child of recorders) child.kill()
+})
 
 /** One ffmpeg process that streams raw samples from one microphone. */
 function capture(name: string | undefined) {
   const child = spawn(
     ffmpeg,
     [
-      "-hide_banner",
-      "-loglevel",
-      "error",
+      '-hide_banner',
+      '-loglevel',
+      'error',
       ...microphoneInput(name),
-      "-ac",
-      "1",
-      "-ar",
+      '-ac',
+      '1',
+      '-ar',
       String(RATE),
-      "-f",
-      "s16le",
-      "pipe:1",
+      '-f',
+      's16le',
+      'pipe:1',
     ],
-    { stdio: ["pipe", "pipe", "pipe"] },
-  );
-  recorders.add(child);
-  child.on("exit", () => recorders.delete(child));
-  const chunks: Array<Buffer> = [];
-  let level = 0;
-  let errors = "";
-  child.stdout.on("data", (chunk: Buffer) => {
-    chunks.push(chunk);
-    level = rms(samplesOf(chunk));
-  });
-  child.stderr.on("data", (chunk: Buffer) => (errors += chunk.toString()));
+    { stdio: ['pipe', 'pipe', 'pipe'] },
+  )
+  recorders.add(child)
+  child.on('exit', () => recorders.delete(child))
+  const chunks: Array<Buffer> = []
+  let level = 0
+  let errors = ''
+  child.stdout.on('data', (chunk: Buffer) => {
+    chunks.push(chunk)
+    level = rms(samplesOf(chunk))
+  })
+  child.stderr.on('data', (chunk: Buffer) => (errors += chunk.toString()))
   const exited = new Promise<void>((resolve, reject) => {
-    child.on("error", (error: NodeJS.ErrnoException) =>
+    child.on('error', (error: NodeJS.ErrnoException) =>
       reject(
-        error.code === "ENOENT"
-          ? new Error("Voice needs ffmpeg on the PATH (or FFMPEG_PATH).")
+        error.code === 'ENOENT'
+          ? new Error('Voice needs ffmpeg on the PATH (or FFMPEG_PATH).')
           : error,
       ),
-    );
-    child.on("exit", () => resolve());
-  });
-  let running = true;
+    )
+    child.on('exit', () => resolve())
+  })
+  let running = true
   void exited.then(
     () => (running = false),
     () => (running = false),
-  );
+  )
   return {
-    name: name ?? "the default input",
+    name: name ?? 'the default input',
     exited,
     isRunning: () => running,
     errors: () => errors.trim(),
@@ -227,42 +240,42 @@ function capture(name: string | undefined) {
       // `q` makes ffmpeg stop cleanly. Kill it if it does not. Do not wait
       // forever: on Windows, dshow sometimes ignores stdin and kill.
       try {
-        child.stdin.end("q");
+        child.stdin.end('q')
       } catch {
         // stdin can already be closed when ffmpeg exited.
       }
-      const timer = setTimeout(() => child.kill(), 1500);
+      const timer = setTimeout(() => child.kill(), 1500)
       await Promise.race([
         exited.catch(() => {}),
         new Promise<void>((resolve) => setTimeout(resolve, 2500)),
-      ]);
-      clearTimeout(timer);
+      ])
+      clearTimeout(timer)
     },
     kill: () => child.kill(),
-  };
+  }
 }
 
 /** A voice message from the microphone. */
 export interface VoiceClip {
   /** 16 kHz mono WAV. */
-  audio: Uint8Array;
+  audio: Uint8Array
   /** The loud part and the noise floor, from 0 to 32768. */
-  peak: number;
-  floor: number;
-  microphone: string;
+  peak: number
+  floor: number
+  microphone: string
   /** True when this recording picked the microphone (the clearest one). */
-  pickedMicrophone: boolean;
+  pickedMicrophone: boolean
 }
 
 export interface Recording {
   /** The microphone, or "all microphones" while the first recording picks one. */
-  microphone: string;
+  microphone: string
   /** The loudness right now, from 0 to 32768, for a level meter. */
-  level: () => number;
+  level: () => number
   /** Stop, and give the voice message. */
-  stop: () => Promise<VoiceClip>;
+  stop: () => Promise<VoiceClip>
   /** Stop and drop the audio. */
-  cancel: () => void;
+  cancel: () => void
 }
 
 /**
@@ -271,50 +284,53 @@ export interface Recording {
  * and remembers it.
  */
 export async function startRecording(): Promise<Recording> {
-  const chosen = await currentMicrophone();
+  const chosen = await currentMicrophone()
   const names =
-    chosen !== undefined || process.platform !== "win32" ? [chosen] : await candidateMicrophones();
-  if (names.length === 0) throw new Error("No microphone found. Set VOICE_DEVICE to its name.");
-  const captures = names.map(capture);
+    chosen !== undefined || process.platform !== 'win32'
+      ? [chosen]
+      : await candidateMicrophones()
+  if (names.length === 0)
+    throw new Error('No microphone found. Set VOICE_DEVICE to its name.')
+  const captures = names.map(capture)
   // ffmpeg stops at once when a device does not open.
-  await new Promise((resolve) => setTimeout(resolve, 400));
-  const live = captures.filter((item) => item.isRunning());
+  await new Promise((resolve) => setTimeout(resolve, 400))
+  const live = captures.filter((item) => item.isRunning())
   if (live.length === 0) {
-    const errors = captures.map((item) => item.errors()).filter(Boolean);
-    throw new Error(`The microphone did not open. ${errors.join(" ")}`.trim());
+    const errors = captures.map((item) => item.errors()).filter(Boolean)
+    throw new Error(`The microphone did not open. ${errors.join(' ')}`.trim())
   }
-  const picking = chosen === undefined && live.length > 1;
+  const picking = chosen === undefined && live.length > 1
   return {
-    microphone: picking ? "all microphones" : (live[0]?.name ?? ""),
+    microphone: picking ? 'all microphones' : (live[0]?.name ?? ''),
     level: () => Math.max(...live.map((item) => item.level())),
     stop: async () => {
-      await Promise.all(live.map((item) => item.stop()));
+      await Promise.all(live.map((item) => item.stop()))
       const clips = live.map((item) => {
-        const pcm = item.pcm();
-        return { name: item.name, pcm, ...speechStats(pcm) };
-      });
+        const pcm = item.pcm()
+        return { name: item.name, pcm, ...speechStats(pcm) }
+      })
       const best = clips.reduce((clearest, clip) =>
         speechScore(clip) > speechScore(clearest) ? clip : clearest,
-      );
+      )
       const clip: VoiceClip = {
         audio: wavFile(best.pcm),
         peak: best.peak,
         floor: best.floor,
         microphone: best.name,
         pickedMicrophone: false,
-      };
+      }
       // Keep that microphone only when it heard speech: in silence, the
       // clearest one means nothing.
       if (picking && !isSilent(clip)) {
-        await chooseMicrophone(best.name);
-        clip.pickedMicrophone = true;
+        await chooseMicrophone(best.name)
+        clip.pickedMicrophone = true
       }
-      return clip;
+      return clip
     },
     cancel: () => {
-      for (const item of live) item.kill();
+      for (const item of live) item.kill()
     },
-  };
+  }
 }
 
 /**
@@ -322,8 +338,8 @@ export async function startRecording(): Promise<Recording> {
  * silent clip is not sent. A clip is silent when its loud part is under
  * VOICE_MIN_LOUDNESS (default 300), for example a muted microphone.
  */
-export function isSilent(clip: Pick<VoiceClip, "peak">) {
-  return clip.peak < Number(process.env.VOICE_MIN_LOUDNESS || 300);
+export function isSilent(clip: Pick<VoiceClip, 'peak'>) {
+  return clip.peak < Number(process.env.VOICE_MIN_LOUDNESS || 300)
 }
 
 /**
@@ -336,84 +352,90 @@ export function isSilent(clip: Pick<VoiceClip, "peak">) {
 export async function transcribe(
   audio: Uint8Array,
   options: {
-    name: string;
-    threadId: string;
-    abortSignal?: AbortSignal;
+    name: string
+    threadId: string
+    abortSignal?: AbortSignal
   },
 ) {
-  const file = new File([audio.slice()], options.name, { type: "audio/wav" });
-  const language = process.env.VOICE_LANGUAGE ? { language: process.env.VOICE_LANGUAGE } : {};
-  const openaiKey = await providerKey(openaiByok, options.threadId);
+  const file = new File([audio.slice()], options.name, { type: 'audio/wav' })
+  const language = process.env.VOICE_LANGUAGE
+    ? { language: process.env.VOICE_LANGUAGE }
+    : {}
+  const openaiKey = await providerKey(openaiByok, options.threadId)
   if (openaiKey !== null) {
     const result = await generateTranscription({
-      adapter: createOpenaiTranscription("gpt-4o-transcribe", openaiKey),
+      adapter: createOpenaiTranscription('gpt-4o-transcribe', openaiKey),
       audio: file,
       timeout: TRANSCRIBE_MS,
       abortSignal: options.abortSignal,
       ...language,
-    });
-    return result.text.trim();
+    })
+    return result.text.trim()
   }
-  const grokKey = await providerKey(grokByok, options.threadId);
+  const grokKey = await providerKey(grokByok, options.threadId)
   if (grokKey !== null) {
     const result = await generateTranscription({
-      adapter: createGrokTranscription("grok-stt", grokKey),
+      adapter: createGrokTranscription('grok-stt', grokKey),
       audio: file,
       timeout: TRANSCRIBE_MS,
       abortSignal: options.abortSignal,
       ...language,
-    });
-    return result.text.trim();
+    })
+    return result.text.trim()
   }
   throw new Error(
-    "Voice needs an OpenAI or xAI key for the transcript. Run /connect openai or /connect grok.",
-  );
+    'Voice needs an OpenAI or xAI key for the transcript. Run /connect openai or /connect grok.',
+  )
 }
 
-const SKIP = new Set(["node_modules", ".git", "dist"]);
+const SKIP = new Set(['node_modules', '.git', 'dist'])
 
 /** The files in `dir` and its folders, 3 levels deep. Stops at MAX_SPOKEN_FILES. */
-async function filesIn(dir: string, depth = 0, acc: Array<string> = []): Promise<Array<string>> {
-  if (depth > 3 || acc.length >= MAX_SPOKEN_FILES) return acc;
-  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+async function filesIn(
+  dir: string,
+  depth = 0,
+  acc: Array<string> = [],
+): Promise<Array<string>> {
+  if (depth > 3 || acc.length >= MAX_SPOKEN_FILES) return acc
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => [])
   for (const entry of entries) {
-    if (acc.length >= MAX_SPOKEN_FILES) break;
-    if (entry.name.startsWith(".") || SKIP.has(entry.name)) continue;
-    const path = join(dir, entry.name);
-    if (entry.isDirectory()) await filesIn(path, depth + 1, acc);
-    else acc.push(path);
+    if (acc.length >= MAX_SPOKEN_FILES) break
+    if (entry.name.startsWith('.') || SKIP.has(entry.name)) continue
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) await filesIn(path, depth + 1, acc)
+    else acc.push(path)
   }
-  return acc;
+  return acc
 }
 
 /** Spoken text in a form that file names match: "cat dot png" is "cat.png". */
 function normalize(text: string) {
   return text
     .toLowerCase()
-    .replace(/\s+dot\s+/g, ".")
-    .replace(/\s*\.\s*(?=[a-z0-9]{2,4}\b)/g, ".");
+    .replace(/\s+dot\s+/g, '.')
+    .replace(/\s*\.\s*(?=[a-z0-9]{2,4}\b)/g, '.')
 }
 
 /** The media a turn made, newest last, for "the last image" and the like. */
 export interface RecentMedia {
-  kind: string;
-  path: string;
+  kind: string
+  path: string
 }
 
 const RECENT =
-  /\b(last|latest|previous|that|this|the)\s+(image|picture|photo|video|clip|song|track|audio|sound)\b/;
+  /\b(last|latest|previous|that|this|the)\s+(image|picture|photo|video|clip|song|track|audio|sound)\b/
 
 const KIND_OF_WORD: Record<string, string> = {
-  image: "image",
-  picture: "image",
-  photo: "image",
-  video: "video",
-  clip: "video",
-  song: "audio",
-  track: "audio",
-  audio: "audio",
-  sound: "audio",
-};
+  image: 'image',
+  picture: 'image',
+  photo: 'image',
+  video: 'video',
+  clip: 'video',
+  song: 'audio',
+  track: 'audio',
+  audio: 'audio',
+  sound: 'audio',
+}
 
 /**
  * Turn the files a user names in a voice message into `@path` attachments.
@@ -426,23 +448,25 @@ export async function withSpokenFiles(
   roots: ReadonlyArray<string>,
   recent: ReadonlyArray<RecentMedia> = [],
 ) {
-  const spoken = normalize(text);
-  const match = RECENT.exec(spoken);
-  const wantsNamedFile = /\.[a-z0-9]{2,4}\b/.test(spoken);
-  if (!wantsNamedFile && !match) return { text, files: [] };
-  const found = new Set<string>();
+  const spoken = normalize(text)
+  const match = RECENT.exec(spoken)
+  const wantsNamedFile = /\.[a-z0-9]{2,4}\b/.test(spoken)
+  if (!wantsNamedFile && !match) return { text, files: [] }
+  const found = new Set<string>()
   if (wantsNamedFile) {
     for (const root of roots) {
       for (const file of await filesIn(root)) {
-        const name = basename(file).toLowerCase();
-        if (extname(name) !== "" && spoken.includes(name)) found.add(file);
+        const name = basename(file).toLowerCase()
+        if (extname(name) !== '' && spoken.includes(name)) found.add(file)
       }
     }
   }
-  const kind = match ? KIND_OF_WORD[match[2] ?? ""] : undefined;
-  const latest = kind ? [...recent].reverse().find((media) => media.kind === kind) : undefined;
-  if (latest) found.add(latest.path);
-  const files = [...found].map((file) => relative(process.cwd(), file));
-  const refs = files.map((file) => `@"${file}"`);
-  return { text: [text, ...refs].join(" "), files };
+  const kind = match ? KIND_OF_WORD[match[2] ?? ''] : undefined
+  const latest = kind
+    ? [...recent].reverse().find((media) => media.kind === kind)
+    : undefined
+  if (latest) found.add(latest.path)
+  const files = [...found].map((file) => relative(process.cwd(), file))
+  const refs = files.map((file) => `@"${file}"`)
+  return { text: [text, ...refs].join(' '), files }
 }
diff --git a/examples/harness-cli-batman/src/workdir.ts b/examples/harness-cli-batman/src/workdir.ts
index b160038b21..581ee50c10 100644
--- a/examples/harness-cli-batman/src/workdir.ts
+++ b/examples/harness-cli-batman/src/workdir.ts
@@ -2,5 +2,5 @@
 // script in this example's folder, and keeps your folder in INIT_CWD. The
 // CLI imports this file after ./env (the .env file is in this example's
 // folder) and before the harness, which reads the folder.
-const started = process.env.INIT_CWD;
-if (started) process.chdir(started);
+const started = process.env.INIT_CWD
+if (started) process.chdir(started)

From e1a9b0086131418c75d09819eccdcfa7696e6032 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 15:11:03 +0200
Subject: [PATCH 249/286] fix(ai-dashboard): pair again after a restart, and
 open a thread from a host row

- A host whose token the dashboard no longer knows pairs again when
  onPairingCode is set, and calls the new onError option when it is not.
  Before, a 401 on hello or on the event stream stopped the host with no
  message.
- Each host row has an "Open a thread" form. It survives the 5 s refresh
  while its input has focus, and a refused input shows as an error.
---
 packages/ai-dashboard/README.md           |  19 +
 packages/ai-dashboard/src/connect.ts      |  61 ++--
 packages/ai-dashboard/src/ui.ts           |  32 +-
 packages/ai-dashboard/tests/relay.test.ts | 414 +++++++++++++++++++++-
 4 files changed, 487 insertions(+), 39 deletions(-)

diff --git a/packages/ai-dashboard/README.md b/packages/ai-dashboard/README.md
index be3f0a764b..5065313dab 100644
--- a/packages/ai-dashboard/README.md
+++ b/packages/ai-dashboard/README.md
@@ -47,6 +47,25 @@ await connectDashboard({
 
 With `@tanstack/ai-harness-cli`, run your CLI with `--dashboard <url>`.
 
+## When the dashboard restarts
+
+The dashboard keeps host tokens in memory. After a restart, it refuses the saved token of each agent. It also refuses the token of a revoked host. What the agent does next depends on `onPairingCode`:
+
+- If `onPairingCode` is set, the agent pairs again. It calls `onPairingCode` with a new code, then `onToken` with the new token.
+- If `onPairingCode` is not set, the agent stops and calls `onError`.
+
+```ts
+const connection = await connectDashboard({
+  host,
+  harness: studio,
+  url: 'http://127.0.0.1:8790',
+  token: savedToken,
+  onError: (error) => console.error(`Pair this host again: ${error.message}`),
+})
+```
+
+`connection.token` always holds the current host token.
+
 ## Documentation
 
 Read [Self-host the dashboard](https://tanstack.com/ai/latest/docs/harness/dashboard).
diff --git a/packages/ai-dashboard/src/connect.ts b/packages/ai-dashboard/src/connect.ts
index 07f4cd66ac..98eda603aa 100644
--- a/packages/ai-dashboard/src/connect.ts
+++ b/packages/ai-dashboard/src/connect.ts
@@ -18,10 +18,12 @@ export interface ConnectDashboardOptions {
   threads?: ReadonlyArray<string>
   /** Let the dashboard open new sessions on this host. Default false. */
   allowRemoteStart?: boolean
-  /** Called with the code to approve in the dashboard. */
+  /** Called with the code to approve in the dashboard. Set it to pair again when the dashboard refuses the token. */
   onPairingCode?: (code: string) => void
   /** Called with the new host token after pairing. Save it to skip pairing next time. */
   onToken?: (token: string) => void
+  /** Called when the dashboard refuses the host token and `onPairingCode` is not set. The connection stops. */
+  onError?: (error: Error) => void
   fetch?: typeof fetch
   /** Wait between reconnects, doubled up to 30 s. Default 1000 ms. */
   reconnectDelayMs?: number
@@ -60,9 +62,8 @@ export async function connectDashboard(options: ConnectDashboardOptions) {
   const base = options.url.replace(/\/$/, '')
   const doFetch = options.fetch ?? fetch
   const stopped = new AbortController()
-  let token = options.token
 
-  if (!token) {
+  const pair = async (): Promise<string> => {
     const started = await (
       await doFetch(`${base}/api/pair/start`, {
         method: 'POST',
@@ -78,7 +79,7 @@ export async function connectDashboard(options: ConnectDashboardOptions) {
       throw new Error('The dashboard did not start a pairing.')
     }
     options.onPairingCode?.(started.code)
-    while (!token) {
+    while (true) {
       if (stopped.signal.aborted)
         throw new Error('Stopped before pairing finished.')
       await new Promise((resolve) => setTimeout(resolve, 1000))
@@ -92,30 +93,42 @@ export async function connectDashboard(options: ConnectDashboardOptions) {
         status.status === 'approved' &&
         typeof status.token === 'string'
       ) {
-        token = status.token
+        options.onToken?.(status.token)
+        return status.token
       } else if (!isRecord(status) || status.status !== 'pending') {
         throw new Error('The pairing expired. Start again.')
       }
     }
-    options.onToken?.(token)
   }
-  const hostToken = token
-  const headers = {
+
+  let hostToken = options.token || (await pair())
+  const headers = () => ({
     'Content-Type': 'application/json',
     Authorization: `Bearer ${hostToken}`,
-  }
+  })
 
   const post = (path: string, value: unknown) =>
     doFetch(`${base}${path}`, {
       method: 'POST',
-      headers,
+      headers: headers(),
       body: JSON.stringify(value),
     })
 
-  await post('/api/host/hello', {
-    name: options.name ?? options.harness.name,
-    harnesses: [options.harness.name],
-  })
+  const hello = async (): Promise<void> => {
+    const response = await post('/api/host/hello', {
+      name: options.name ?? options.harness.name,
+      harnesses: [options.harness.name],
+    })
+    if (response.status !== 401) return
+    // A restarted dashboard forgets its host tokens. Pair again, or report it.
+    if (!options.onPairingCode) {
+      options.onError?.(new Error('The dashboard refused this host token.'))
+      return stopped.abort()
+    }
+    hostToken = await pair()
+    await hello()
+  }
+  await hello()
 
   const attached = new Map<string, HarnessSession>()
   const attach = async (threadId: string): Promise<HarnessSession> => {
@@ -217,16 +230,17 @@ export async function connectDashboard(options: ConnectDashboardOptions) {
     while (!stopped.signal.aborted) {
       try {
         const response = await doFetch(`${base}/api/host/stream`, {
-          headers,
+          headers: headers(),
           signal: stopped.signal,
         })
-        if (response.status === 401)
-          throw new Error('The dashboard refused this host token.')
-        delay = options.reconnectDelayMs ?? 1000
-        for await (const envelope of sseData(response)) void handle(envelope)
-      } catch (error) {
+        if (response.status === 401) {
+          await hello()
+        } else {
+          delay = options.reconnectDelayMs ?? 1000
+          for await (const envelope of sseData(response)) void handle(envelope)
+        }
+      } catch {
         if (stopped.signal.aborted) return
-        if (error instanceof Error && error.message.includes('refused')) return
       }
       await new Promise((resolve) => setTimeout(resolve, delay))
       delay = Math.min(delay * 2, 30_000)
@@ -234,7 +248,10 @@ export async function connectDashboard(options: ConnectDashboardOptions) {
   })()
 
   return {
-    token: hostToken,
+    /** The host token. It changes when the host pairs again. */
+    get token() {
+      return hostToken
+    },
     /** Show another thread in the dashboard. */
     attach: (threadId: string) => attach(threadId).then(() => undefined),
     close: () => stopped.abort(),
diff --git a/packages/ai-dashboard/src/ui.ts b/packages/ai-dashboard/src/ui.ts
index 76d2e0c840..e35575d58a 100644
--- a/packages/ai-dashboard/src/ui.ts
+++ b/packages/ai-dashboard/src/ui.ts
@@ -69,17 +69,33 @@ async function refresh() {
       $('button', { onclick: async () => { await api('/api/pair/approve', { method: 'POST', body: JSON.stringify({ code: pairing.code }) }); refresh() } }, 'Approve'))) : [$('p', { class: 'muted' }, 'None')]),
     $('h3', {}, 'Hosts'),
     ...(hosts.length ? hosts.map((host) => $('div', { class: 'row' },
-      $('span', { class: host.online ? 'dot on' : 'dot' }), $('span', {}, host.name + ' (' + host.harnesses.join(', ') + ')'))) : [$('p', { class: 'muted' }, 'No hosts yet')]),
+      $('span', { class: host.online ? 'dot on' : 'dot' }), $('span', {}, host.name + ' (' + host.harnesses.join(', ') + ')'), openForm(host))) : [$('p', { class: 'muted' }, 'No hosts yet')]),
     $('h3', {}, 'Sessions'),
     ...(sessions.length ? sessions.map((session) => $('button', { class: 'session ' + session.status, onclick: () => open(session) },
       session.threadId + ' | ' + (session.harness || '') + ' | ' + session.status)) : [$('p', { class: 'muted' }, 'No sessions yet')]),
   )
 }
 
+const sessionPath = (hostId, threadId) => '/api/sessions/' + encodeURIComponent(hostId) + '/' + encodeURIComponent(threadId)
+
+// Start or attach a thread on a host, then watch it. A host without
+// allowRemoteStart ignores this and refuses the first input instead.
+function openForm(host) {
+  const input = $('input', { placeholder: 'Thread id', 'aria-label': 'Thread id', autocomplete: 'off' })
+  return $('form', { class: 'row open-thread', onsubmit: async (event) => {
+    event.preventDefault(); const threadId = input.value.trim(); if (!threadId) return
+    const result = await api(sessionPath(host.hostId, threadId) + '/open', { method: 'POST' })
+    open({ hostId: host.hostId, threadId })
+    if (result.error) current.messages.push({ kind: 'error', text: result.error })
+    if (result.status === 'queued') current.messages.push({ kind: 'notice', text: 'Queued: the host is offline.' })
+    draw(); refresh().catch(() => {})
+  } }, input, $('button', {}, 'Open'))
+}
+
 function open(session) {
   current = { ...session, messages: [], interrupts: [], questions: new Map(), running: false }
   if (source) source.close()
-  const path = '/api/sessions/' + encodeURIComponent(session.hostId) + '/' + encodeURIComponent(session.threadId)
+  const path = sessionPath(session.hostId, session.threadId)
   current.path = path
   source = new EventSource(path + '/events?token=' + encodeURIComponent(token))
   source.onmessage = (message) => { apply(JSON.parse(message.data)); draw() }
@@ -87,7 +103,10 @@ function open(session) {
 }
 
 function apply(frame) {
-  if (frame.type !== 'harness.event' || !current) return
+  if (!current) return
+  // A refused input, for example to a thread the host does not let the dashboard start.
+  if (frame.type === 'harness.receipt' && frame.status === 'rejected') current.messages.push({ kind: 'error', text: 'Refused: ' + (frame.reason || 'no reason') })
+  if (frame.type !== 'harness.event') return
   const event = frame.event
   if (event.subagentRunId) { applyChild(event); return }
   if (event.type === 'TEXT_MESSAGE_CONTENT') {
@@ -175,7 +194,11 @@ function render() {
   app.replaceChildren($('aside', { id: 'side' }), $('main', { id: 'main' }))
   draw(); refresh().catch(() => {})
 }
-setInterval(() => refresh().catch(() => {}), 5000)
+// No refresh while a side panel input has focus, so a half-typed thread id survives.
+setInterval(() => {
+  const side = document.getElementById('side'), focused = document.activeElement
+  if (!(side && focused && focused.tagName === 'INPUT' && side.contains(focused))) refresh().catch(() => {})
+}, 5000)
 if ('serviceWorker' in navigator) navigator.serviceWorker.register('/sw.js').catch(() => {})
 render()
 `
@@ -204,6 +227,7 @@ export const DASHBOARD_HTML = `<!doctype html>
   button.ghost { background: transparent; color: var(--text); border: 1px solid var(--line); }
   button.session { display: block; width: 100%; text-align: left; background: var(--panel); color: var(--text); border: 1px solid var(--line); margin-bottom: 6px; font-weight: 400; }
   button.session.waiting { border-color: #f5b041; } button.session.running { border-color: var(--accent); }
+  .open-thread { flex-basis: 100%; }
   .dot { width: 9px; height: 9px; border-radius: 50%; background: #555; display: inline-block; } .dot.on { background: #3ecf8e; }
   .log { flex: 1; overflow-y: auto; display: flex; flex-direction: column; gap: 8px; min-height: 200px; max-height: 65vh; }
   .msg { white-space: pre-wrap; padding: 10px 12px; border-radius: 10px; background: var(--panel); max-width: 80ch; }
diff --git a/packages/ai-dashboard/tests/relay.test.ts b/packages/ai-dashboard/tests/relay.test.ts
index daee6fa05f..51969acf41 100644
--- a/packages/ai-dashboard/tests/relay.test.ts
+++ b/packages/ai-dashboard/tests/relay.test.ts
@@ -1,9 +1,11 @@
+import { createContext, runInContext } from 'node:vm'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { EventType } from '@tanstack/ai'
 import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { startDashboard } from '../src'
 import { connectDashboard } from '../src/connect'
+import { DASHBOARD_HTML } from '../src/ui'
 import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
 
 let calls = 0
@@ -67,6 +69,81 @@ afterEach(async () => {
   for (const cleanup of cleanups.splice(0).reverse()) await cleanup()
 })
 
+/** Open a session's event stream. `until` reads frames up to the first one that has `marker`. */
+async function openEvents(url: string) {
+  const controller = new AbortController()
+  cleanups.push(() => controller.abort())
+  const reader = (
+    await fetch(url, { signal: controller.signal })
+  ).body!.getReader()
+  const decoder = new TextDecoder()
+  const frames: Array<string> = []
+  let buffer = ''
+  return async (marker: string): Promise<Array<unknown>> => {
+    while (!frames.some((frame) => frame.includes(marker))) {
+      const { value, done } = await reader.read()
+      if (done) throw new Error(`The stream ended before ${marker}.`)
+      const blocks = (buffer + decoder.decode(value, { stream: true })).split(
+        '\n\n',
+      )
+      buffer = blocks.pop() ?? ''
+      for (const block of blocks) {
+        const data = block.split('\n').find((line) => line.startsWith('data: '))
+        if (data) frames.push(data.slice(6))
+      }
+    }
+    return frames.map((frame) => JSON.parse(frame))
+  }
+}
+
+/** Pair a host over the API, connect it, and wait until it is online. */
+async function onlineHost(
+  dashboard: { url: string; ownerToken: string },
+  allowRemoteStart: boolean,
+) {
+  const owner = {
+    Authorization: `Bearer ${dashboard.ownerToken}`,
+    'Content-Type': 'application/json',
+  }
+  const started = await (
+    await fetch(`${dashboard.url}/api/pair/start`, { method: 'POST' })
+  ).json()
+  await fetch(`${dashboard.url}/api/pair/approve`, {
+    method: 'POST',
+    headers: owner,
+    body: JSON.stringify({ code: started.code }),
+  })
+  const { hostId, token } = await (
+    await fetch(
+      `${dashboard.url}/api/pair/status?pairingId=${started.pairingId}`,
+    )
+  ).json()
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  cleanups.push(() => host.close())
+  const connection = await connectDashboard({
+    host,
+    harness: defineHarness({
+      name: 'acme/remote',
+      adapter: adapterSaying('Hello from the host.'),
+    }),
+    url: dashboard.url,
+    token,
+    allowRemoteStart,
+  })
+  cleanups.push(() => connection.close())
+  await vi.waitFor(async () => {
+    const hosts = await (
+      await fetch(`${dashboard.url}/api/hosts`, { headers: owner })
+    ).json()
+    expect(hosts).toMatchObject([{ hostId, online: true }])
+  })
+  return { host, hostId, owner }
+}
+
+const answered = expect.objectContaining({
+  event: expect.objectContaining({ delta: 'Hello from the host.' }),
+})
+
 describe('dashboard relay', () => {
   it(
     'pairs a host, shows its session, and relays a prompt and its answer',
@@ -143,25 +220,178 @@ describe('dashboard relay', () => {
           { hostId, threadId: 'main', harness: 'acme/remote', status: 'idle' },
         ])
       })
-      const controller = new AbortController()
-      const events = await fetch(
+      const until = await openEvents(
         `${dashboard.url}/api/sessions/${hostId}/main/events?token=${dashboard.ownerToken}`,
-        {
-          signal: controller.signal,
-        },
       )
-      const reader = events.body!.getReader()
-      let text = ''
-      while (!text.includes('harness.operation.finished')) {
-        const { value, done } = await reader.read()
-        if (done) break
-        text += new TextDecoder().decode(value)
+      expect(await until('harness.operation.finished')).toContainEqual(answered)
+    },
+  )
+
+  it(
+    'opens a thread on a host that allows remote start',
+    { timeout: 20_000 },
+    async () => {
+      const dashboard = await startDashboard({ port: 0 })
+      cleanups.push(() => dashboard.close())
+      const { host, hostId, owner } = await onlineHost(dashboard, true)
+      const session = `${dashboard.url}/api/sessions/${hostId}/fresh`
+      const until = await openEvents(
+        `${session}/events?token=${dashboard.ownerToken}`,
+      )
+
+      // The host opens the thread when the dashboard asks.
+      const stop = new AbortController()
+      cleanups.push(() => stop.abort())
+      const attached = (async () => {
+        for await (const event of host.events({ signal: stop.signal }))
+          if (event.type === 'status' && event.threadId === 'fresh') return
+      })()
+      const opened = await fetch(`${session}/open`, {
+        method: 'POST',
+        headers: owner,
+      })
+      expect(opened.status).toBe(202)
+      expect(await opened.json()).toEqual({ status: 'sent' })
+      await attached
+
+      const receipt = await (
+        await fetch(`${session}/input`, {
+          method: 'POST',
+          headers: owner,
+          body: JSON.stringify({ input: { op: 'prompt', message: 'hi' } }),
+        })
+      ).json()
+      expect(receipt.status).toBe('sent')
+      expect(await until('harness.operation.finished')).toContainEqual(answered)
+    },
+  )
+
+  it(
+    'refuses inputs to a thread the host does not let the dashboard start',
+    { timeout: 20_000 },
+    async () => {
+      const dashboard = await startDashboard({ port: 0 })
+      cleanups.push(() => dashboard.close())
+      const { hostId, owner } = await onlineHost(dashboard, false)
+      const session = `${dashboard.url}/api/sessions/${hostId}/fresh`
+      const until = await openEvents(
+        `${session}/events?token=${dashboard.ownerToken}`,
+      )
+
+      // The route only relays the request. The host ignores it and refuses
+      // the first input with the reason.
+      const opened = await fetch(`${session}/open`, {
+        method: 'POST',
+        headers: owner,
+      })
+      expect(await opened.json()).toEqual({ status: 'sent' })
+      await fetch(`${session}/input`, {
+        method: 'POST',
+        headers: owner,
+        body: JSON.stringify({ input: { op: 'prompt', message: 'hi' } }),
+      })
+      const frames = await until('remote_start_disabled')
+      expect(frames).toContainEqual(
+        expect.objectContaining({
+          type: 'harness.receipt',
+          status: 'rejected',
+          reason: 'remote_start_disabled',
+        }),
+      )
+    },
+  )
+
+  it(
+    'pairs again when the dashboard restarts on the same port',
+    { timeout: 20_000 },
+    async () => {
+      const ownerToken = 'owner-token'
+      let dashboard = await startDashboard({ port: 0, ownerToken })
+      cleanups.push(() => dashboard.close())
+      const owner = {
+        Authorization: `Bearer ${ownerToken}`,
+        'Content-Type': 'application/json',
+      }
+      const onlineHosts = async () => {
+        const hosts: unknown = await (
+          await fetch(`${dashboard.url}/api/hosts`, { headers: owner })
+        ).json()
+        return Array.isArray(hosts)
+          ? hosts.filter((host) => host.online === true)
+          : []
       }
-      controller.abort()
-      expect(text).toContain('Hello from the host.')
+
+      const host = createHarnessHost({ persistence: memoryPersistence() })
+      cleanups.push(() => host.close())
+      const tokens: Array<string> = []
+      const connection = await connectDashboard({
+        host,
+        harness: defineHarness({
+          name: 'acme/remote',
+          adapter: adapterSaying('unused'),
+        }),
+        url: dashboard.url,
+        reconnectDelayMs: 50,
+        onPairingCode: (code) => {
+          void fetch(`${dashboard.url}/api/pair/approve`, {
+            method: 'POST',
+            headers: owner,
+            body: JSON.stringify({ code }),
+          })
+        },
+        onToken: (token) => tokens.push(token),
+      })
+      cleanups.push(() => connection.close())
+      await vi.waitFor(async () => expect(await onlineHosts()).toHaveLength(1))
+
+      // The restarted dashboard has no host tokens in memory.
+      const port = new URL(dashboard.url).port
+      await dashboard.close()
+      dashboard = await startDashboard({ port: Number(port), ownerToken })
+
+      await vi.waitFor(
+        async () =>
+          expect(await onlineHosts()).toMatchObject([
+            { name: 'acme/remote', harnesses: ['acme/remote'] },
+          ]),
+        { timeout: 10_000 },
+      )
+      expect(tokens).toHaveLength(2)
+      expect(tokens[1]).not.toBe(tokens[0])
+      expect(connection.token).toBe(tokens[1])
     },
   )
 
+  it('reports a refused token when it cannot pair again', async () => {
+    const dashboard = await startDashboard({ port: 0, ownerToken: 'owner' })
+    cleanups.push(() => dashboard.close())
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    cleanups.push(() => host.close())
+
+    const errors: Array<Error> = []
+    const connection = await connectDashboard({
+      host,
+      harness: defineHarness({
+        name: 'acme/remote',
+        adapter: adapterSaying('unused'),
+      }),
+      url: dashboard.url,
+      token: 'a-token-from-before-the-restart',
+      onError: (error) => errors.push(error),
+    })
+    cleanups.push(() => connection.close())
+
+    expect(errors.map((error) => error.message)).toEqual([
+      'The dashboard refused this host token.',
+    ])
+    const pairings = await (
+      await fetch(`${dashboard.url}/api/pairings`, {
+        headers: { Authorization: 'Bearer owner' },
+      })
+    ).json()
+    expect(pairings).toEqual([])
+  })
+
   it(
     'queues inputs for an offline host and refuses revoked hosts',
     { timeout: 20_000 },
@@ -217,3 +447,161 @@ describe('dashboard relay', () => {
     },
   )
 })
+
+/** Just enough DOM for the page script. */
+class FakeNode {
+  children: Array<FakeNode> = []
+  className = ''
+  attributes: Record<string, string> = {}
+  value = ''
+  onsubmit?: (event: { preventDefault: () => void }) => Promise<void>
+  constructor(
+    readonly tag: string,
+    readonly text = '',
+  ) {}
+  get tagName() {
+    return this.tag.toUpperCase()
+  }
+  append(...children: Array<FakeNode>) {
+    this.children.push(...children)
+  }
+  replaceChildren(...children: Array<FakeNode>) {
+    this.children = children
+  }
+  setAttribute(key: string, value: string) {
+    this.attributes[key] = value
+  }
+  contains(node: FakeNode | null): boolean {
+    return node === this || this.children.some((child) => child.contains(node))
+  }
+  find(test: (node: FakeNode) => boolean): FakeNode | undefined {
+    if (test(this)) return this
+    for (const child of this.children) {
+      const found = child.find(test)
+      if (found) return found
+    }
+    return undefined
+  }
+  get textContent(): string {
+    return this.text + this.children.map((child) => child.textContent).join('')
+  }
+}
+
+/** Run the page script against a fake DOM, a fake API, and a manual timer. */
+function loadPage(hosts: Array<Record<string, unknown>>) {
+  const script = /<script>([\s\S]*)<\/script>/.exec(DASHBOARD_HTML)?.[1] ?? ''
+  const nodes = new Map<string, FakeNode>()
+  const byId = (id: string) => {
+    const node = nodes.get(id) ?? new FakeNode('div')
+    nodes.set(id, node)
+    return node
+  }
+  const requests: Array<string> = []
+  const sources: Array<FakeEventSource> = []
+  class FakeEventSource {
+    onmessage?: (message: { data: string }) => void
+    constructor(readonly url: string) {
+      sources.push(this)
+    }
+    close() {}
+  }
+  let tick = () => {}
+  let focused: FakeNode | null = null
+  runInContext(
+    script,
+    createContext({
+      Node: FakeNode,
+      document: {
+        createElement: (tag: string) => new FakeNode(tag),
+        createTextNode: (text: string) => new FakeNode('#text', text),
+        getElementById: byId,
+        get activeElement() {
+          return focused
+        },
+      },
+      location: { hash: '' },
+      history: { replaceState: () => {} },
+      localStorage: {
+        getItem: () => 'owner',
+        setItem: () => {},
+        removeItem: () => {},
+      },
+      navigator: {},
+      setInterval: (callback: () => void) => {
+        tick = callback
+        return 0
+      },
+      fetch: async (path: string, options: { method?: string } = {}) => {
+        requests.push(`${options.method ?? 'GET'} ${path}`)
+        const body = path === '/api/hosts' ? hosts : []
+        return { status: 200, json: async () => body }
+      },
+      EventSource: FakeEventSource,
+      URLSearchParams,
+    }),
+  )
+  return {
+    side: () => byId('side'),
+    main: () => byId('main'),
+    requests,
+    sources,
+    focus: (node: FakeNode | null) => {
+      focused = node
+    },
+    tick: () => tick(),
+  }
+}
+
+const settle = () => new Promise((resolve) => setTimeout(resolve, 0))
+
+describe('dashboard page', () => {
+  it('opens a thread from a host row, and keeps the form while it has focus', async () => {
+    const page = loadPage([
+      { hostId: 'host 1', name: 'laptop', harnesses: ['acme/remote'] },
+    ])
+    await settle()
+    const hostLoads = () =>
+      page.requests.filter((request) => request === 'GET /api/hosts').length
+    const row = page
+      .side()
+      .find((node) => node.textContent.startsWith('laptop'))
+    const form = row?.find((node) => node.tag === 'form')
+    const input = form?.find((node) => node.tag === 'input')
+    if (!row || !form?.onsubmit || !input) throw new Error('No open form.')
+    expect(row.className).toBe('row')
+    expect(form.textContent).toBe('Open')
+
+    // The 5 s refresh skips while the input has focus.
+    input.value = 'feature/<b>'
+    page.focus(input)
+    page.tick()
+    await settle()
+    expect(hostLoads()).toBe(1)
+    expect(page.side().contains(form)).toBe(true)
+
+    await form.onsubmit({ preventDefault: () => {} })
+    const path = '/api/sessions/host%201/feature%2F%3Cb%3E'
+    expect(page.requests).toContain(`POST ${path}/open`)
+    expect(page.sources[0]?.url).toBe(`${path}/events?token=owner`)
+    expect(page.main().children[0]?.textContent).toBe('feature/<b>')
+
+    // A host without allowRemoteStart refuses the first input.
+    page.sources[0]?.onmessage?.({
+      data: JSON.stringify({
+        type: 'harness.receipt',
+        status: 'rejected',
+        reason: 'remote_start_disabled',
+      }),
+    })
+    const error = page.main().find((node) => node.className === 'msg error')
+    expect(error?.textContent).toBe('Refused: remote_start_disabled')
+
+    // Without focus, the refresh runs again.
+    page.focus(null)
+    await settle()
+    const loads = hostLoads()
+    page.tick()
+    await settle()
+    expect(hostLoads()).toBe(loads + 1)
+  })
+})

From 8cfb1e3b9b947068197c8fdb5c7de084a85e5274 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 15:12:34 +0200
Subject: [PATCH 250/286] fix(ai-harness): clear the oxlint errors in http,
 formatter, and patch

Promise.all gets only promises, the patch header picks its kind with if
and else, and the collect view helper no longer shadows the plugin values.
---
 .../ai-harness/src/first-party/coding/formatter.ts  |  4 +++-
 packages/ai-harness/src/first-party/coding/patch.ts | 13 +++----------
 packages/ai-harness/src/http.ts                     |  4 +++-
 packages/ai-harness/src/plugins.ts                  | 10 +++++-----
 4 files changed, 14 insertions(+), 17 deletions(-)

diff --git a/packages/ai-harness/src/first-party/coding/formatter.ts b/packages/ai-harness/src/first-party/coding/formatter.ts
index fc451213fc..1d97cd9249 100644
--- a/packages/ai-harness/src/first-party/coding/formatter.ts
+++ b/packages/ai-harness/src/first-party/coding/formatter.ts
@@ -161,7 +161,9 @@ export function formatOnWrite(
       read: (name) => readText(backend, join(root, name)).catch(() => ''),
     }
     const used = await Promise.all(
-      candidates.map((candidate) => candidate.when?.(project) ?? true),
+      candidates.map(
+        async (candidate) => (await candidate.when?.(project)) ?? true,
+      ),
     )
     return candidates.filter((_, index) => used[index])
   }
diff --git a/packages/ai-harness/src/first-party/coding/patch.ts b/packages/ai-harness/src/first-party/coding/patch.ts
index 5255e82597..d3e7e182d3 100644
--- a/packages/ai-harness/src/first-party/coding/patch.ts
+++ b/packages/ai-harness/src/first-party/coding/patch.ts
@@ -116,16 +116,9 @@ export function parsePatch(text: string) {
       checkNotEmpty(current, currentLine)
       const [, kind, rest] = header
       const path = pathAt(index, rest)
-      switch (kind) {
-        case 'Add':
-          current = { type: 'add', path, content: '' }
-          break
-        case 'Delete':
-          current = { type: 'delete', path }
-          break
-        default:
-          current = { type: 'update', path, chunks: [] }
-      }
+      if (kind === 'Add') current = { type: 'add', path, content: '' }
+      else if (kind === 'Delete') current = { type: 'delete', path }
+      else current = { type: 'update', path, chunks: [] }
       operations.push(current)
       currentLine = index
       chunk = undefined
diff --git a/packages/ai-harness/src/http.ts b/packages/ai-harness/src/http.ts
index 19fe8e3d93..9fee956367 100644
--- a/packages/ai-harness/src/http.ts
+++ b/packages/ai-harness/src/http.ts
@@ -543,7 +543,9 @@ export function createHarnessHandler(
           ...(parentThreadId ? { parentThreadId } : {}),
         })
         const allowed = await Promise.all(
-          page.entries.map((entry) => canAccess(principal, entry.threadId)),
+          page.entries.map(async (entry) =>
+            canAccess(principal, entry.threadId),
+          ),
         )
         return json({
           ...page,
diff --git a/packages/ai-harness/src/plugins.ts b/packages/ai-harness/src/plugins.ts
index 233263292f..565dd17a35 100644
--- a/packages/ai-harness/src/plugins.ts
+++ b/packages/ai-harness/src/plugins.ts
@@ -605,16 +605,16 @@ export async function mountPlugins(
             extensions.set(point.name, items)
           }
           const source = items
-          const values = () => source.map((item) => item.value as T)
+          const live = () => source.map((item) => item.value as T)
           // A live view: items contributed after this call appear too. Array
           // methods like `filter` also check that an index exists, so every
           // trap reads the items, not the empty target.
           return new Proxy<Array<T>>([], {
-            get: (_target, key) => Reflect.get(values(), key),
-            has: (_target, key) => Reflect.has(values(), key),
-            ownKeys: () => Reflect.ownKeys(values()),
+            get: (_target, key) => Reflect.get(live(), key),
+            has: (_target, key) => Reflect.has(live(), key),
+            ownKeys: () => Reflect.ownKeys(live()),
             getOwnPropertyDescriptor: (_target, key) =>
-              Reflect.getOwnPropertyDescriptor(values(), key),
+              Reflect.getOwnPropertyDescriptor(live(), key),
           })
         },
         emit: (event, value) => services.emit(plugin.name, event.name, value),

From 53fab0187a725f8054e49b6b7a821a3d7d4a9d08 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 16:54:47 +0200
Subject: [PATCH 251/286] fix(examples): resolve harness-cli-batman like
 harness-cli in the lockfile

The batman example's install re-resolved part of the workspace: zod moved
to 4.6.5 for @modelcontextprotocol/server, and @google/genai got a second
copy. That broke the ai-mcp type check (two zod copies in the server
types) and the ai-vertex factory tests (the mocked SDK was the other
copy).

The example has the same dependencies as examples/harness-cli, so its
lockfile entry now resolves the same way (zod 4.3.6,
@tanstack/react-store 0.11.1). The rest of the lockfile is as before the
example. A frozen install passes, and ai-mcp test:types, ai-vertex
test:lib, and the example's test:types pass.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 pnpm-lock.yaml | 209 ++++++++++++++++---------------------------------
 1 file changed, 66 insertions(+), 143 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 71ca07ad66..0fe2ce9dca 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -332,7 +332,7 @@ importers:
         version: link:../../packages/ai-skills
       '@tanstack/react-store':
         specifier: ^0.11.1
-        version: 0.11.2(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+        version: 0.11.1(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       beautiful-mermaid:
         specifier: ^1.1.3
         version: 1.1.3
@@ -350,7 +350,7 @@ importers:
         version: 19.2.3
       zod:
         specifier: ^4.2.0
-        version: 4.6.5
+        version: 4.3.6
     devDependencies:
       '@types/node':
         specifier: ^24.10.1
@@ -3810,7 +3810,7 @@ importers:
     devDependencies:
       '@google/genai':
         specifier: ^2.10.0
-        version: 2.10.0(@modelcontextprotocol/sdk@1.29.0(zod@4.6.5))
+        version: 2.10.0(@modelcontextprotocol/sdk@1.29.0(zod@4.3.6))
       '@tanstack/ai':
         specifier: workspace:*
         version: link:../ai
@@ -8412,48 +8412,24 @@ packages:
     cpu: [arm64]
     os: [android]
 
-  '@parcel/watcher-android-arm64@2.6.0':
-    resolution: {integrity: sha512-trgpLSCKRC/huFjXX/Smh+0sWe4+YtKfktIToiMl59ghz7z+qkH6kMvNnUbLyRs9N11t8l4svSCs1+5B3rOAhA==}
-    engines: {node: '>= 10.0.0'}
-    cpu: [arm64]
-    os: [android]
-
   '@parcel/watcher-darwin-arm64@2.5.1':
     resolution: {integrity: sha512-eAzPv5osDmZyBhou8PoF4i6RQXAfeKL9tjb3QzYuccXFMQU0ruIc/POh30ePnaOyD1UXdlKguHBmsTs53tVoPw==}
     engines: {node: '>= 10.0.0'}
     cpu: [arm64]
     os: [darwin]
 
-  '@parcel/watcher-darwin-arm64@2.6.0':
-    resolution: {integrity: sha512-Y3QV0gl7Q1zbfueunkWIERICbEojQFCgpyG7YqOGNFLsckXyI1xu9mAIUpKY9QBYzBtSkN8dBPwd3yiAO9ovMw==}
-    engines: {node: '>= 10.0.0'}
-    cpu: [arm64]
-    os: [darwin]
-
   '@parcel/watcher-darwin-x64@2.5.1':
     resolution: {integrity: sha512-1ZXDthrnNmwv10A0/3AJNZ9JGlzrF82i3gNQcWOzd7nJ8aj+ILyW1MTxVk35Db0u91oD5Nlk9MBiujMlwmeXZg==}
     engines: {node: '>= 10.0.0'}
     cpu: [x64]
     os: [darwin]
 
-  '@parcel/watcher-darwin-x64@2.6.0':
-    resolution: {integrity: sha512-Ohv6OpzhUfKYD7Beb8kDvG0jbIxORCYY1JRdZnaBtnjjkJxgD7ZVL0nw2sCYd0yTMKTvz3nnTnOF3cDifK+kvw==}
-    engines: {node: '>= 10.0.0'}
-    cpu: [x64]
-    os: [darwin]
-
   '@parcel/watcher-freebsd-x64@2.5.1':
     resolution: {integrity: sha512-SI4eljM7Flp9yPuKi8W0ird8TI/JK6CSxju3NojVI6BjHsTyK7zxA9urjVjEKJ5MBYC+bLmMcbAWlZ+rFkLpJQ==}
     engines: {node: '>= 10.0.0'}
     cpu: [x64]
     os: [freebsd]
 
-  '@parcel/watcher-freebsd-x64@2.6.0':
-    resolution: {integrity: sha512-5HmXvDgs8VK+74jF9y9/2FE3/OnlcKmc56tjmSrEuZjpSZOGL+fvAu+HKJBdPs9uwoP2hE6TlSUpXZ/C5jUFmQ==}
-    engines: {node: '>= 10.0.0'}
-    cpu: [x64]
-    os: [freebsd]
-
   '@parcel/watcher-linux-arm-glibc@2.5.1':
     resolution: {integrity: sha512-RCdZlEyTs8geyBkkcnPWvtXLY44BCeZKmGYRtSgtwwnHR4dxfHRG3gR99XdMEdQ7KeiDdasJwwvNSF5jKtDwdA==}
     engines: {node: '>= 10.0.0'}
@@ -8461,13 +8437,6 @@ packages:
     os: [linux]
     libc: [glibc]
 
-  '@parcel/watcher-linux-arm-glibc@2.6.0':
-    resolution: {integrity: sha512-Ps/hui3A+vMbjdqlqAowK2ZL8+BO8dBjxeWXj6npTBs3jx4wWmbPpaLuqwrQrSqIVMCnpWo238bJ1U37GhQOYg==}
-    engines: {node: '>= 10.0.0'}
-    cpu: [arm]
-    os: [linux]
-    libc: [glibc]
-
   '@parcel/watcher-linux-arm-musl@2.5.1':
     resolution: {integrity: sha512-6E+m/Mm1t1yhB8X412stiKFG3XykmgdIOqhjWj+VL8oHkKABfu/gjFj8DvLrYVHSBNC+/u5PeNrujiSQ1zwd1Q==}
     engines: {node: '>= 10.0.0'}
@@ -8475,13 +8444,6 @@ packages:
     os: [linux]
     libc: [musl]
 
-  '@parcel/watcher-linux-arm-musl@2.6.0':
-    resolution: {integrity: sha512-9c6AUHgHoG+IY88MRIHupztQiQnrbqHYQjkM2btA+Bf/wQnQMuiD0Wfk1EVv3TlNT3x41uU71rn6E4xh/+zvkw==}
-    engines: {node: '>= 10.0.0'}
-    cpu: [arm]
-    os: [linux]
-    libc: [musl]
-
   '@parcel/watcher-linux-arm64-glibc@2.5.1':
     resolution: {integrity: sha512-LrGp+f02yU3BN9A+DGuY3v3bmnFUggAITBGriZHUREfNEzZh/GO06FF5u2kx8x+GBEUYfyTGamol4j3m9ANe8w==}
     engines: {node: '>= 10.0.0'}
@@ -8489,13 +8451,6 @@ packages:
     os: [linux]
     libc: [glibc]
 
-  '@parcel/watcher-linux-arm64-glibc@2.6.0':
-    resolution: {integrity: sha512-yHRqS2owEXe6Hic9z6Mh1ECsCd+ODVOGvZDyciqRd21+v+o+DnXMOrw50DSpIG2sb8GPEaPPmfeCAWKPJdq46g==}
-    engines: {node: '>= 10.0.0'}
-    cpu: [arm64]
-    os: [linux]
-    libc: [glibc]
-
   '@parcel/watcher-linux-arm64-musl@2.5.1':
     resolution: {integrity: sha512-cFOjABi92pMYRXS7AcQv9/M1YuKRw8SZniCDw0ssQb/noPkRzA+HBDkwmyOJYp5wXcsTrhxO0zq1U11cK9jsFg==}
     engines: {node: '>= 10.0.0'}
@@ -8503,13 +8458,6 @@ packages:
     os: [linux]
     libc: [musl]
 
-  '@parcel/watcher-linux-arm64-musl@2.6.0':
-    resolution: {integrity: sha512-WhB2e/V7rqdHHWZusBSPuy5Ei8S6lSz6FE5TKKQz5h3a0O+C+mhY7vxU9b/stqvMb8beLnPY82ZrFTLKs+SrKA==}
-    engines: {node: '>= 10.0.0'}
-    cpu: [arm64]
-    os: [linux]
-    libc: [musl]
-
   '@parcel/watcher-linux-x64-glibc@2.5.1':
     resolution: {integrity: sha512-GcESn8NZySmfwlTsIur+49yDqSny2IhPeZfXunQi48DMugKeZ7uy1FX83pO0X22sHntJ4Ub+9k34XQCX+oHt2A==}
     engines: {node: '>= 10.0.0'}
@@ -8517,13 +8465,6 @@ packages:
     os: [linux]
     libc: [glibc]
 
-  '@parcel/watcher-linux-x64-glibc@2.6.0':
-    resolution: {integrity: sha512-ulGE6x6Oz6iAwg75T8YQSoguBWasniIbX+QWpaYPcCnDOpdWX3k+4xbEYPZVLxOuoJI+svJJPD3sEj8G7lrQ3A==}
-    engines: {node: '>= 10.0.0'}
-    cpu: [x64]
-    os: [linux]
-    libc: [glibc]
-
   '@parcel/watcher-linux-x64-musl@2.5.1':
     resolution: {integrity: sha512-n0E2EQbatQ3bXhcH2D1XIAANAcTZkQICBPVaxMeaCVBtOpBZpWJuf7LwyWPSBDITb7In8mqQgJ7gH8CILCURXg==}
     engines: {node: '>= 10.0.0'}
@@ -8531,13 +8472,6 @@ packages:
     os: [linux]
     libc: [musl]
 
-  '@parcel/watcher-linux-x64-musl@2.6.0':
-    resolution: {integrity: sha512-tkBYKt7YQrjIJWYDnto2YgO8MRkjlMTSNoRHzsXinBqbLdeOM3L32wPZJvIZxqaLMfSlS/4sUjH/6STVP/XDLw==}
-    engines: {node: '>= 10.0.0'}
-    cpu: [x64]
-    os: [linux]
-    libc: [musl]
-
   '@parcel/watcher-wasm@2.5.1':
     resolution: {integrity: sha512-RJxlQQLkaMMIuWRozy+z2vEqbaQlCuaCgVZIUCzQLYggY22LZbP5Y1+ia+FD724Ids9e+XIyOLXLrLgQSHIthw==}
     engines: {node: '>= 10.0.0'}
@@ -8550,12 +8484,6 @@ packages:
     cpu: [arm64]
     os: [win32]
 
-  '@parcel/watcher-win32-arm64@2.6.0':
-    resolution: {integrity: sha512-gIZAP23jaHjGWasY/TY6yL7NHFClf0Ga7FN+iINvk+KN94rhm94lYZhFsbYFNcA04/onvGD9kKmiJLJB2HbNwQ==}
-    engines: {node: '>= 10.0.0'}
-    cpu: [arm64]
-    os: [win32]
-
   '@parcel/watcher-win32-ia32@2.5.1':
     resolution: {integrity: sha512-c2KkcVN+NJmuA7CGlaGD1qJh1cLfDnQsHjE89E60vUEMlqduHGCdCLJCID5geFVM0dOtA3ZiIO8BoEQmzQVfpQ==}
     engines: {node: '>= 10.0.0'}
@@ -8568,12 +8496,6 @@ packages:
     cpu: [x64]
     os: [win32]
 
-  '@parcel/watcher-win32-x64@2.6.0':
-    resolution: {integrity: sha512-cA+/pXV2YkfxlIcXOQ5fSWqAzzPyD78/x5qbK/I0vUkrlYHA8TIz+MXjAbGouguKVSI4bOmkTSJ1/poVSsgt+A==}
-    engines: {node: '>= 10.0.0'}
-    cpu: [x64]
-    os: [win32]
-
   '@parcel/watcher@2.5.1':
     resolution: {integrity: sha512-dfUnCxiN9H4ap84DvD2ubjw+3vUNpstxa0TneY/Paat8a3R4uQZDLSvWjmznAY/DoahqTHl9V46HF/Zs3F29pg==}
     engines: {node: '>= 10.0.0'}
@@ -10904,14 +10826,20 @@ packages:
       vite:
         optional: true
 
+  '@tanstack/react-store@0.11.2':
+    resolution: {integrity: sha512-oj5O5DmiMWE+ih+SioX2ayC1kbK7d3fpLx0B75fPJr9nY3zU+hoW010yr64qXsY/9fyiLVE2bn5mGNV3owm8RQ==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
   '@tanstack/react-store@0.11.1':
     resolution: {integrity: sha512-HaIGKI3YLmjBYIvy5DFDY23oNaYZIsTZfngey07Uh5iLVJgM3bIGCnZeOFOqzjFld9JHWcaHJnasD/bKoGKwJQ==}
     peerDependencies:
       react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
       react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
-  '@tanstack/react-store@0.11.2':
-    resolution: {integrity: sha512-oj5O5DmiMWE+ih+SioX2ayC1kbK7d3fpLx0B75fPJr9nY3zU+hoW010yr64qXsY/9fyiLVE2bn5mGNV3owm8RQ==}
+  '@tanstack/react-store@0.8.0':
+    resolution: {integrity: sha512-1vG9beLIuB7q69skxK9r5xiLN3ztzIPfSQSs0GfeqWGO2tGIyInZx0x1COhpx97RKaONSoAb8C3dxacWksm1ow==}
     peerDependencies:
       react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
       react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
@@ -11051,6 +10979,11 @@ packages:
     peerDependencies:
       solid-js: ^1.6.0
 
+  '@tanstack/solid-store@0.8.0':
+    resolution: {integrity: sha512-JwqTedbxyOGw7mfmdGkB0RGgefRCw/tNauc8tlMcaS1mV5wTFT8c1KIB3LgttuHaanMJEBeqQJ7bc/R0WTP1fA==}
+    peerDependencies:
+      solid-js: ^1.6.0
+
   '@tanstack/start-client-core@1.170.34':
     resolution: {integrity: sha512-LfwZSbau2MLLZ/uPAoO+NC9fK3J66c0wLhnNQqIa+Goqw7bXPjkHwlsjY7evlUz1AnyhhQ1Qab95v+VmP0TZ9A==}
     engines: {node: '>=22.12.0'}
@@ -11085,6 +11018,9 @@ packages:
   '@tanstack/store@0.11.2':
     resolution: {integrity: sha512-sJ4mjol8uQsHV0gOJzzjwXfh2Fwm+Sz0+8deqiTm4jGbMdjzNSW+xZCFm0kUa870uhd8yi+DpKnZb5Kc4apa0Q==}
 
+  '@tanstack/store@0.8.0':
+    resolution: {integrity: sha512-Om+BO0YfMZe//X2z0uLF2j+75nQga6TpTJgLJQBiq85aOyZNIhkCgleNcud2KQg4k4v9Y9l+Uhru3qWMPGTOzQ==}
+
   '@tanstack/typedoc-config@0.3.4':
     resolution: {integrity: sha512-WXJavpiNqumNwdBQTM3wBqbHaULgoZ3cIri7xJinKqX/mOGXgc6ZghfAardD2PydP8tOcPf+xhrd1Qk/am9DMg==}
     engines: {node: '>=18'}
@@ -12501,6 +12437,10 @@ packages:
   classnames@2.5.1:
     resolution: {integrity: sha512-saHYOzhIQs6wy2sVxTM6bUDsQO4F50V9RQ22qBpEdCW+I+/Wmke2HOl6lS6dTpdxVhb88/I6+Hs+438c3lfUow==}
 
+  cli-boxes@3.0.0:
+    resolution: {integrity: sha512-/lzGpEWL/8PfI0BmBOPRwp0c/wFNX1RdUML3jK/RcSBA9T8mZDdQpqYBKtCFTOfQbwPqWEOpjqW+Fnayc0969g==}
+    engines: {node: '>=10'}
+
   cli-boxes@4.0.1:
     resolution: {integrity: sha512-5IOn+jcCEHEraYolBPs/sT4BxYCe2nHg374OPiItB1O96KZFseS2gthU4twyYzeDcFew4DaUM/xwc5BQf08JJw==}
     engines: {node: '>=18.20 <19 || >=20.10'}
@@ -17936,6 +17876,10 @@ packages:
     resolution: {integrity: sha512-Ne2YiiGN8bmrmJJEuTWTLJR32nh/JdL1+PSicowtNb0WFpn59GK8/lfD61bVtzguz7b3PBt74nxpv/Pw5po5Rg==}
     engines: {node: '>=8'}
 
+  type-fest@2.19.0:
+    resolution: {integrity: sha512-RAH822pAdBgcNMAfWnCBU3CFZcfZ/i1eZjwFU/dsLKumyuuP3niueg2UAukXYF0E2AAoc82ZSSf9J0WQBinzHA==}
+    engines: {node: '>=12.20'}
+
   type-fest@5.10.0:
     resolution: {integrity: sha512-NoSdpq/WEiAg5sjmBkmV/hfxv6HJH4NqPNrqjtSO5CwRmpsDfaf4begxW34KdJykH/l1yHtwBWQkCRdoXO8mPA==}
     engines: {node: '>=20'}
@@ -18833,6 +18777,10 @@ packages:
     engines: {node: '>=8'}
     hasBin: true
 
+  widest-line@4.0.1:
+    resolution: {integrity: sha512-o0cyEG0e8GPzT4iGHphIOh0cJOV8fivsXxddQasHPHfoZf1ZexrfeA21w2NaEN1RHE+fXlfISmOE8R9N3u3Qig==}
+    engines: {node: '>=12'}
+
   widest-line@6.0.0:
     resolution: {integrity: sha512-U89AsyEeAsyoF0zVJBkG9zBgekjgjK7yk9sje3F4IQpXBJ10TF6ByLlIfjMhcmHMJgHZI4KHt4rdNfktzxIAMA==}
     engines: {node: '>=20'}
@@ -21097,7 +21045,7 @@ snapshots:
   '@blaxel/core@0.3.11(@hey-api/openapi-ts@0.99.0(magicast@0.5.2)(typescript@7.0.2))':
     dependencies:
       '@hey-api/client-fetch': 0.10.2(@hey-api/openapi-ts@0.99.0(magicast@0.5.2)(typescript@7.0.2))
-      '@modelcontextprotocol/sdk': 1.29.0(zod@4.6.5)
+      '@modelcontextprotocol/sdk': 1.29.0(zod@4.3.6)
       archiver: 7.0.1
       axios: 1.18.1(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)
       dockerfile-ast: 0.7.1
@@ -21108,7 +21056,7 @@ snapshots:
       uuid: 11.1.1
       ws: 8.21.0
       yaml: 2.9.0
-      zod: 4.6.5
+      zod: 4.3.6
     transitivePeerDependencies:
       - '@cfworker/json-schema'
       - '@hey-api/openapi-ts'
@@ -22823,8 +22771,8 @@ snapshots:
   '@mistralai/mistralai@2.2.0':
     dependencies:
       ws: 8.21.0
-      zod: 4.6.5
-      zod-to-json-schema: 3.25.2(zod@4.6.5)
+      zod: 4.3.6
+      zod-to-json-schema: 3.25.2(zod@4.3.6)
     transitivePeerDependencies:
       - bufferutil
       - utf-8-validate
@@ -22837,11 +22785,11 @@ snapshots:
       eventsource-parser: 3.1.1
       jose: 6.2.12
       pkce-challenge: 5.0.1
-      zod: 4.6.5
+      zod: 4.3.6
 
   '@modelcontextprotocol/core@2.1.0':
     dependencies:
-      zod: 4.6.5
+      zod: 4.3.6
 
   '@modelcontextprotocol/ext-apps@1.7.4(@modelcontextprotocol/sdk@1.29.0(supports-color@7.2.0)(zod@4.2.1))(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(zod@3.25.76)':
     dependencies:
@@ -22939,11 +22887,12 @@ snapshots:
       zod-to-json-schema: 3.25.2(zod@4.6.5)
     transitivePeerDependencies:
       - supports-color
+    optional: true
 
   '@modelcontextprotocol/server@2.1.0':
     dependencies:
       '@modelcontextprotocol/core': 2.1.0
-      zod: 4.6.5
+      zod: 4.3.6
 
   '@msgpack/msgpack@3.1.3': {}
 
@@ -23203,7 +23152,7 @@ snapshots:
 
   '@openrouter/sdk@0.13.20':
     dependencies:
-      zod: 4.6.5
+      zod: 4.3.6
 
   '@opentelemetry/api-logs@0.217.0':
     dependencies:
@@ -23948,63 +23897,33 @@ snapshots:
   '@parcel/watcher-android-arm64@2.5.1':
     optional: true
 
-  '@parcel/watcher-android-arm64@2.6.0':
-    optional: true
-
   '@parcel/watcher-darwin-arm64@2.5.1':
     optional: true
 
-  '@parcel/watcher-darwin-arm64@2.6.0':
-    optional: true
-
   '@parcel/watcher-darwin-x64@2.5.1':
     optional: true
 
-  '@parcel/watcher-darwin-x64@2.6.0':
-    optional: true
-
   '@parcel/watcher-freebsd-x64@2.5.1':
     optional: true
 
-  '@parcel/watcher-freebsd-x64@2.6.0':
-    optional: true
-
   '@parcel/watcher-linux-arm-glibc@2.5.1':
     optional: true
 
-  '@parcel/watcher-linux-arm-glibc@2.6.0':
-    optional: true
-
   '@parcel/watcher-linux-arm-musl@2.5.1':
     optional: true
 
-  '@parcel/watcher-linux-arm-musl@2.6.0':
-    optional: true
-
   '@parcel/watcher-linux-arm64-glibc@2.5.1':
     optional: true
 
-  '@parcel/watcher-linux-arm64-glibc@2.6.0':
-    optional: true
-
   '@parcel/watcher-linux-arm64-musl@2.5.1':
     optional: true
 
-  '@parcel/watcher-linux-arm64-musl@2.6.0':
-    optional: true
-
   '@parcel/watcher-linux-x64-glibc@2.5.1':
     optional: true
 
-  '@parcel/watcher-linux-x64-glibc@2.6.0':
-    optional: true
-
   '@parcel/watcher-linux-x64-musl@2.5.1':
     optional: true
 
-  '@parcel/watcher-linux-x64-musl@2.6.0':
-    optional: true
-
   '@parcel/watcher-wasm@2.5.1':
     dependencies:
       is-glob: 4.0.3
@@ -24013,18 +23932,12 @@ snapshots:
   '@parcel/watcher-win32-arm64@2.5.1':
     optional: true
 
-  '@parcel/watcher-win32-arm64@2.6.0':
-    optional: true
-
   '@parcel/watcher-win32-ia32@2.5.1':
     optional: true
 
   '@parcel/watcher-win32-x64@2.5.1':
     optional: true
 
-  '@parcel/watcher-win32-x64@2.6.0':
-    optional: true
-
   '@parcel/watcher@2.5.1':
     dependencies:
       detect-libc: 1.0.3
@@ -24052,19 +23965,6 @@ snapshots:
       is-glob: 4.0.3
       node-addon-api: 7.1.1
       picomatch: 4.0.7
-    optionalDependencies:
-      '@parcel/watcher-android-arm64': 2.6.0
-      '@parcel/watcher-darwin-arm64': 2.6.0
-      '@parcel/watcher-darwin-x64': 2.6.0
-      '@parcel/watcher-freebsd-x64': 2.6.0
-      '@parcel/watcher-linux-arm-glibc': 2.6.0
-      '@parcel/watcher-linux-arm-musl': 2.6.0
-      '@parcel/watcher-linux-arm64-glibc': 2.6.0
-      '@parcel/watcher-linux-arm64-musl': 2.6.0
-      '@parcel/watcher-linux-x64-glibc': 2.6.0
-      '@parcel/watcher-linux-x64-musl': 2.6.0
-      '@parcel/watcher-win32-arm64': 2.6.0
-      '@parcel/watcher-win32-x64': 2.6.0
     optional: true
 
   '@pkgjs/parseargs@0.11.0':
@@ -27554,6 +27454,13 @@ snapshots:
       react-dom: 19.2.3(react@19.2.3)
       use-sync-external-store: 1.6.0(react@19.2.3)
 
+  '@tanstack/react-store@0.8.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
+    dependencies:
+      '@tanstack/store': 0.8.0
+      react: 19.2.3
+      react-dom: 19.2.3(react@19.2.3)
+      use-sync-external-store: 1.6.0(react@19.2.3)
+
   '@tanstack/router-core@1.171.34':
     dependencies:
       '@tanstack/history': 1.162.4
@@ -27760,6 +27667,11 @@ snapshots:
       '@tanstack/store': 0.11.1
       solid-js: 1.9.10
 
+  '@tanstack/solid-store@0.8.0(solid-js@1.9.10)':
+    dependencies:
+      '@tanstack/store': 0.8.0
+      solid-js: 1.9.10
+
   '@tanstack/start-client-core@1.170.34':
     dependencies:
       '@tanstack/router-core': 1.171.34
@@ -27886,6 +27798,8 @@ snapshots:
       - vite-plugin-solid
       - webpack
 
+  '@tanstack/store@0.11.1': {}
+
   '@tanstack/start-server-core@1.169.39(crossws@0.4.6(srvx@0.11.17))':
     dependencies:
       '@tanstack/history': 1.162.4
@@ -27914,10 +27828,10 @@ snapshots:
     dependencies:
       '@tanstack/router-core': 1.171.34
 
-  '@tanstack/store@0.11.1': {}
-
   '@tanstack/store@0.11.2': {}
 
+  '@tanstack/store@0.8.0': {}
+
   '@tanstack/typedoc-config@0.3.4':
     dependencies:
       typedoc: 0.28.20(@typescript/typescript6@6.0.2)
@@ -28532,7 +28446,7 @@ snapshots:
       tar-stream: 3.1.7
       undici: 7.28.0
       xdg-app-paths: 5.1.0
-      zod: 4.6.5
+      zod: 4.3.6
     transitivePeerDependencies:
       - bare-abort-controller
       - react-native-b4a
@@ -29792,6 +29706,8 @@ snapshots:
   classnames@2.5.1:
     optional: true
 
+  cli-boxes@3.0.0: {}
+
   cli-boxes@4.0.1: {}
 
   cli-cursor@2.1.0:
@@ -37156,6 +37072,8 @@ snapshots:
 
   type-fest@0.7.1: {}
 
+  type-fest@2.19.0: {}
+
   type-fest@5.10.0:
     dependencies:
       tagged-tag: 1.0.0
@@ -38109,6 +38027,10 @@ snapshots:
       siginfo: 2.0.0
       stackback: 0.0.2
 
+  widest-line@4.0.1:
+    dependencies:
+      string-width: 5.1.2
+
   widest-line@6.0.0:
     dependencies:
       string-width: 8.2.2
@@ -38342,6 +38264,7 @@ snapshots:
   zod-to-json-schema@3.25.2(zod@4.6.5):
     dependencies:
       zod: 4.6.5
+    optional: true
 
   zod@3.25.76: {}
 

From 7b1538835664a0e8f6e87c3bf08e50339f29610f Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 17:09:25 +0200
Subject: [PATCH 252/286] fix(ai-anthropic): read the no-forced-tool list with
 any model id

The adapter model is now an AnthropicModelId, which allows any string, so
the list is read as a set of strings. Its entries are still checked
against the known models.
---
 packages/ai-anthropic/src/adapters/text.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/ai-anthropic/src/adapters/text.ts b/packages/ai-anthropic/src/adapters/text.ts
index c4fcd667c9..b622177554 100644
--- a/packages/ai-anthropic/src/adapters/text.ts
+++ b/packages/ai-anthropic/src/adapters/text.ts
@@ -286,7 +286,7 @@ export function computeAnthropicBetas(
  * ponytail: a hand list, because the model sync script writes model-meta.ts.
  * Move it to a model-meta capability when that script can set one.
  */
-const ANTHROPIC_NO_FORCED_TOOL_MODELS = new Set<
+const ANTHROPIC_NO_FORCED_TOOL_MODELS: ReadonlySet<string> = new Set<
   (typeof ANTHROPIC_MODELS)[number]
 >(['claude-fable-5-1', 'claude-opus-5-5', 'claude-sonnet-5-5'])
 

From 8559ebb4a27f9db71983c54be505ab4873a495e7 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 17:09:25 +0200
Subject: [PATCH 253/286] test(e2e): check that toolChoice reaches the wire

- The chat route passes a feature's toolChoice to chat().
- OpenAI: the tool-choice feature reads tool_choice from the aimock
  journal.
- Anthropic: aimock leaves tool_choice out of its journal, so a wire route
  captures the request. claude-sonnet-4-5 gets the named tool, and
  claude-opus-5-5 gets auto.
- The route tree is generated again. The merged copy declared 13 routes
  twice.
---
 testing/e2e/fixtures/tool-choice/basic.json   |   27 +
 testing/e2e/src/lib/feature-support.ts        |    4 +
 testing/e2e/src/lib/features.ts               |    9 +-
 testing/e2e/src/lib/types.ts                  |    2 +
 testing/e2e/src/routeTree.gen.ts              | 2991 ++++++++---------
 testing/e2e/src/routes/api.chat.ts            |    3 +
 .../e2e/src/routes/api.tool-choice-wire.ts    |  132 +
 testing/e2e/tests/tool-choice.spec.ts         |  125 +
 8 files changed, 1770 insertions(+), 1523 deletions(-)
 create mode 100644 testing/e2e/fixtures/tool-choice/basic.json
 create mode 100644 testing/e2e/src/routes/api.tool-choice-wire.ts
 create mode 100644 testing/e2e/tests/tool-choice.spec.ts

diff --git a/testing/e2e/fixtures/tool-choice/basic.json b/testing/e2e/fixtures/tool-choice/basic.json
new file mode 100644
index 0000000000..8d45b5ed23
--- /dev/null
+++ b/testing/e2e/fixtures/tool-choice/basic.json
@@ -0,0 +1,27 @@
+{
+  "fixtures": [
+    {
+      "match": {
+        "userMessage": "[toolchoice] what guitars do you have in stock",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "getGuitars",
+            "arguments": "{}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[toolchoice] what guitars do you have in stock",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "We have the Fender Stratocaster and the Gibson Les Paul in stock."
+      }
+    }
+  ]
+}
diff --git a/testing/e2e/src/lib/feature-support.ts b/testing/e2e/src/lib/feature-support.ts
index 80db339afa..2cdc47411a 100644
--- a/testing/e2e/src/lib/feature-support.ts
+++ b/testing/e2e/src/lib/feature-support.ts
@@ -115,6 +115,10 @@ export const matrix: Record<Feature, Set<Provider>> = {
     'llmgateway',
     'cloudflare',
   ]),
+  // OpenAI only: aimock's journal keeps `tool_choice` for Responses requests,
+  // but stores Anthropic requests in OpenAI shape without it. Anthropic is
+  // covered by `/api/tool-choice-wire`, which captures the request body.
+  'tool-choice': new Set(['openai']),
   'parallel-tool-calls': new Set([
     'openai',
     'anthropic',
diff --git a/testing/e2e/src/lib/features.ts b/testing/e2e/src/lib/features.ts
index 4ed0ef03e5..1f70bd2f4b 100644
--- a/testing/e2e/src/lib/features.ts
+++ b/testing/e2e/src/lib/features.ts
@@ -1,4 +1,4 @@
-import type { ReasoningRequest } from '@tanstack/ai'
+import type { ReasoningRequest, ToolChoice } from '@tanstack/ai'
 import type { Feature, Provider } from '@/lib/types'
 import { getGuitars, compareGuitars, addToCart } from '@/lib/tools'
 
@@ -7,6 +7,8 @@ interface FeatureConfig {
   modelOptions: Record<string, any>
   /** `chat({ reasoning })` for the feature. */
   reasoning?: ReasoningRequest
+  /** `chat({ toolChoice })` for the feature. */
+  toolChoice?: ToolChoice
   modelOverrides?: Partial<Record<Provider, string>>
   dedicatedRoute?: string
   /**
@@ -58,6 +60,11 @@ export const featureConfigs: Record<Feature, FeatureConfig> = {
     tools: [getGuitars],
     modelOptions: {},
   },
+  'tool-choice': {
+    tools: [getGuitars],
+    modelOptions: {},
+    toolChoice: { type: 'tool', name: 'getGuitars' },
+  },
   'parallel-tool-calls': {
     tools: [getGuitars, compareGuitars],
     modelOptions: {},
diff --git a/testing/e2e/src/lib/types.ts b/testing/e2e/src/lib/types.ts
index 0df692df7c..dedae1754a 100644
--- a/testing/e2e/src/lib/types.ts
+++ b/testing/e2e/src/lib/types.ts
@@ -32,6 +32,7 @@ export type Feature =
   | 'reasoning'
   | 'multi-turn'
   | 'tool-calling'
+  | 'tool-choice'
   | 'parallel-tool-calls'
   | 'tool-approval'
   | 'text-tool-text'
@@ -93,6 +94,7 @@ export const ALL_FEATURES: Feature[] = [
   'reasoning',
   'multi-turn',
   'tool-calling',
+  'tool-choice',
   'parallel-tool-calls',
   'tool-approval',
   'text-tool-text',
diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index d2a2396903..cb5b3bd376 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -9,739 +9,584 @@
 // Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
 
 import { Route as rootRouteImport } from './routes/__root'
-import { Route as ApiAdapterConfigReasoningWireRouteImport } from './routes/api.adapter-config-reasoning-wire'
-import { Route as ApiActivityTestRouteImport } from './routes/api.activity-test'
+import { Route as IndexRouteImport } from './routes/index'
 import { Route as ActivityTestRouteImport } from './routes/activity-test'
-import { Route as ApiForeignClientToolRouteImport } from './routes/api.foreign-client-tool'
-import { Route as ApiForeignChunkEventsRouteImport } from './routes/api.foreign-chunk-events'
-import { Route as ApiAnthropicTruncatedToolInputWireRouteImport } from './routes/api.anthropic-truncated-tool-input-wire'
-import { Route as ApiAnthropicSonnet55WireRouteImport } from './routes/api.anthropic-sonnet-5-5-wire'
-import { Route as ApiAnthropicMaxTokensUsageRouteImport } from './routes/api.anthropic-max-tokens-usage'
-import { Route as ForeignClientToolRouteImport } from './routes/foreign-client-tool'
+import { Route as ByokRouteImport } from './routes/byok'
+import { Route as ChatClientDefaultBridgeRouteImport } from './routes/chat-client-default-bridge'
+import { Route as ChatClientStreamProcessingRouteImport } from './routes/chat-client-stream-processing'
+import { Route as ClientMountHydrateRouteImport } from './routes/client-mount-hydrate'
+import { Route as DevtoolsChatRouteImport } from './routes/devtools-chat'
+import { Route as DevtoolsGenerationHooksRouteImport } from './routes/devtools-generation-hooks'
+import { Route as DevtoolsMemoryRouteImport } from './routes/devtools-memory'
+import { Route as DevtoolsRouteARouteImport } from './routes/devtools-route-a'
+import { Route as DevtoolsRouteBRouteImport } from './routes/devtools-route-b'
+import { Route as DevtoolsStructuredRouteImport } from './routes/devtools-structured'
+import { Route as DevtoolsSubagentsRouteImport } from './routes/devtools-subagents'
+import { Route as DevtoolsToolsRouteImport } from './routes/devtools-tools'
 import { Route as ForeignChunkEventsRouteImport } from './routes/foreign-chunk-events'
-import { Route as WebsocketAdapterRouteImport } from './routes/websocket-adapter'
-import { Route as WebMcpToolsRouteImport } from './routes/web-mcp-tools'
-import { Route as WebMcpPageToolsRouteImport } from './routes/web-mcp-page-tools'
-import { Route as ToolsTestRouteImport } from './routes/tools-test'
-import { Route as ToolFirstTextRouteImport } from './routes/tool-first-text'
-import { Route as TextFirstToolRouteImport } from './routes/text-first-tool'
-import { Route as SubagentsUiTestRouteImport } from './routes/subagents-ui-test'
-import { Route as SubagentsTestRouteImport } from './routes/subagents-test'
-import { Route as PersistenceDurabilityRouteImport } from './routes/persistence-durability'
-import { Route as MiddlewareTestRouteImport } from './routes/middleware-test'
-import { Route as MessageHistoryPagingRouteImport } from './routes/message-history-paging'
-import { Route as MarkdownCjkRouteImport } from './routes/markdown-cjk'
-import { Route as JoinRunClientToolRouteImport } from './routes/join-run-client-tool'
-import { Route as InterruptsTestRouteImport } from './routes/interrupts-test'
-import { Route as InterruptLineageRouteImport } from './routes/interrupt-lineage'
-import { Route as HeadlessUiRouteImport } from './routes/headless-ui'
-import { Route as GenerationPersistenceServerRouteImport } from './routes/generation-persistence-server'
-import { Route as GenerationPersistenceResumeRouteImport } from './routes/generation-persistence-resume'
+import { Route as ForeignClientToolRouteImport } from './routes/foreign-client-tool'
 import { Route as ForeignInterruptRouteImport } from './routes/foreign-interrupt'
-import { Route as DevtoolsToolsRouteImport } from './routes/devtools-tools'
-import { Route as DevtoolsSubagentsRouteImport } from './routes/devtools-subagents'
-import { Route as DevtoolsStructuredRouteImport } from './routes/devtools-structured'
-import { Route as DevtoolsRouteBRouteImport } from './routes/devtools-route-b'
-import { Route as DevtoolsRouteARouteImport } from './routes/devtools-route-a'
-import { Route as DevtoolsMemoryRouteImport } from './routes/devtools-memory'
-import { Route as DevtoolsGenerationHooksRouteImport } from './routes/devtools-generation-hooks'
-import { Route as DevtoolsChatRouteImport } from './routes/devtools-chat'
-import { Route as ClientMountHydrateRouteImport } from './routes/client-mount-hydrate'
-import { Route as ChatClientStreamProcessingRouteImport } from './routes/chat-client-stream-processing'
-import { Route as ChatClientDefaultBridgeRouteImport } from './routes/chat-client-default-bridge'
-import { Route as ByokRouteImport } from './routes/byok'
-import { Route as IndexRouteImport } from './routes/index'
+import { Route as GenerationPersistenceResumeRouteImport } from './routes/generation-persistence-resume'
+import { Route as GenerationPersistenceServerRouteImport } from './routes/generation-persistence-server'
+import { Route as HeadlessUiRouteImport } from './routes/headless-ui'
+import { Route as InterruptLineageRouteImport } from './routes/interrupt-lineage'
+import { Route as InterruptsTestRouteImport } from './routes/interrupts-test'
+import { Route as JoinRunClientToolRouteImport } from './routes/join-run-client-tool'
+import { Route as MarkdownCjkRouteImport } from './routes/markdown-cjk'
+import { Route as MessageHistoryPagingRouteImport } from './routes/message-history-paging'
+import { Route as MiddlewareTestRouteImport } from './routes/middleware-test'
+import { Route as PersistenceDurabilityRouteImport } from './routes/persistence-durability'
+import { Route as SubagentsTestRouteImport } from './routes/subagents-test'
+import { Route as SubagentsUiTestRouteImport } from './routes/subagents-ui-test'
+import { Route as TextFirstToolRouteImport } from './routes/text-first-tool'
+import { Route as ToolFirstTextRouteImport } from './routes/tool-first-text'
+import { Route as ToolsTestRouteImport } from './routes/tools-test'
+import { Route as WebMcpPageToolsRouteImport } from './routes/web-mcp-page-tools'
+import { Route as WebMcpToolsRouteImport } from './routes/web-mcp-tools'
+import { Route as WebsocketAdapterRouteImport } from './routes/websocket-adapter'
 import { Route as ProviderIndexRouteImport } from './routes/$provider/index'
-import { Route as ApiWorldRouteImport } from './routes/api.world'
-import { Route as ApiWebMcpPageToolsRouteImport } from './routes/api.web-mcp-page-tools'
-import { Route as ApiVoiceRouteImport } from './routes/api.voice'
-import { Route as ApiVideoLiveRouteImport } from './routes/api.video-live'
-import { Route as ApiVideoRouteImport } from './routes/api.video'
-import { Route as ApiTtsRouteImport } from './routes/api.tts'
-import { Route as ApiTranscriptionRouteImport } from './routes/api.transcription'
-import { Route as ApiToolsTestRouteImport } from './routes/api.tools-test'
-import { Route as ApiToolFirstTextWireRouteImport } from './routes/api.tool-first-text-wire'
-import { Route as ApiToolCallLifecycleWireRouteImport } from './routes/api.tool-call-lifecycle-wire'
-import { Route as ApiTextFirstToolWireRouteImport } from './routes/api.text-first-tool-wire'
-import { Route as ApiSummarizeRouteImport } from './routes/api.summarize'
-import { Route as ApiSubagentsTestRouteImport } from './routes/api.subagents-test'
-import { Route as ApiStructuredOutputLengthWireRouteImport } from './routes/api.structured-output-length-wire'
-import { Route as ApiSandboxToolHistoryRouteImport } from './routes/api.sandbox-tool-history'
-import { Route as ApiSandboxFilePersistenceRouteImport } from './routes/api.sandbox-file-persistence'
-import { Route as ApiSandboxDurabilityRouteImport } from './routes/api.sandbox-durability'
-import { Route as ApiProviderToolDispatchWireRouteImport } from './routes/api.provider-tool-dispatch-wire'
-import { Route as ApiProviderSearchMetadataWireRouteImport } from './routes/api.provider-search-metadata-wire'
-import { Route as ApiPromptCacheWireRouteImport } from './routes/api.prompt-cache-wire'
-import { Route as ApiPortableSkillsWireRouteImport } from './routes/api.portable-skills-wire'
-import { Route as ApiPersistenceDurabilityRouteImport } from './routes/api.persistence-durability'
-import { Route as ApiOtelUsageRouteImport } from './routes/api.otel-usage'
-import { Route as ApiOtelTranscriptionRouteImport } from './routes/api.otel-transcription'
-import { Route as ApiOtelMediaRouteImport } from './routes/api.otel-media'
-import { Route as ApiOpenrouterWebToolsWireRouteImport } from './routes/api.openrouter-web-tools-wire'
-import { Route as ApiOpenrouterStreamOptionsWireRouteImport } from './routes/api.openrouter-stream-options-wire'
-import { Route as ApiOpenrouterStrictToolOptionalsRouteImport } from './routes/api.openrouter-strict-tool-optionals'
-import { Route as ApiOpenrouterRetryCodesRouteImport } from './routes/api.openrouter-retry-codes'
-import { Route as ApiOpenrouterReasoningWireRouteImport } from './routes/api.openrouter-reasoning-wire'
-import { Route as ApiOpenrouterJsonObjectWireRouteImport } from './routes/api.openrouter-json-object-wire'
-import { Route as ApiOpenrouterCostRouteImport } from './routes/api.openrouter-cost'
-import { Route as ApiOpenaiUsageDetailsRouteImport } from './routes/api.openai-usage-details'
-import { Route as ApiOpenaiStrictToolNullWireRouteImport } from './routes/api.openai-strict-tool-null-wire'
-import { Route as ApiOpenaiShellSkillsWireRouteImport } from './routes/api.openai-shell-skills-wire'
+import { Route as ProviderFeatureRouteImport } from './routes/$provider/$feature'
+import { Route as ApiActivityTestRouteImport } from './routes/api.activity-test'
+import { Route as ApiAdapterConfigReasoningWireRouteImport } from './routes/api.adapter-config-reasoning-wire'
+import { Route as ApiAnthropicBugTestRouteImport } from './routes/api.anthropic-bug-test'
+import { Route as ApiAnthropicMaxTokensUsageRouteImport } from './routes/api.anthropic-max-tokens-usage'
+import { Route as ApiAnthropicMultiTurnStructuredWireRouteImport } from './routes/api.anthropic-multi-turn-structured-wire'
+import { Route as ApiAnthropicOpus5CombinedWireRouteImport } from './routes/api.anthropic-opus-5-combined-wire'
+import { Route as ApiAnthropicRedactedThinkingWireRouteImport } from './routes/api.anthropic-redacted-thinking-wire'
+import { Route as ApiAnthropicSkillsWireRouteImport } from './routes/api.anthropic-skills-wire'
+import { Route as ApiAnthropicSonnet55WireRouteImport } from './routes/api.anthropic-sonnet-5-5-wire'
+import { Route as ApiAnthropicStructuredUsageRouteImport } from './routes/api.anthropic-structured-usage'
+import { Route as ApiAnthropicThinkingOrderWireRouteImport } from './routes/api.anthropic-thinking-order-wire'
+import { Route as ApiAnthropicTruncatedToolInputWireRouteImport } from './routes/api.anthropic-truncated-tool-input-wire'
+import { Route as ApiArktypeToolWireRouteImport } from './routes/api.arktype-tool-wire'
+import { Route as ApiAudioRouteImport } from './routes/api.audio'
+import { Route as ApiBedrockConverseCacheRouteImport } from './routes/api.bedrock-converse-cache'
+import { Route as ApiByokChatRouteImport } from './routes/api.byok-chat'
+import { Route as ApiByteplusSeedance1080pWireRouteImport } from './routes/api.byteplus-seedance-1080p-wire'
+import { Route as ApiChatRouteImport } from './routes/api.chat'
+import { Route as ApiCloudflareBindingWireRouteImport } from './routes/api.cloudflare-binding-wire'
+import { Route as ApiCompactionDurableWireRouteImport } from './routes/api.compaction-durable-wire'
+import { Route as ApiCompactionWireRouteImport } from './routes/api.compaction-wire'
+import { Route as ApiDevtoolsMemoryRouteImport } from './routes/api.devtools-memory'
+import { Route as ApiDurableDeliveryRouteImport } from './routes/api.durable-delivery'
+import { Route as ApiDurableTakeoverRouteImport } from './routes/api.durable-takeover'
+import { Route as ApiEmbeddingRouteImport } from './routes/api.embedding'
+import { Route as ApiFileSourceWireRouteImport } from './routes/api.file-source-wire'
+import { Route as ApiForeignChunkEventsRouteImport } from './routes/api.foreign-chunk-events'
+import { Route as ApiForeignClientToolRouteImport } from './routes/api.foreign-client-tool'
+import { Route as ApiForeignInterruptRouteImport } from './routes/api.foreign-interrupt'
+import { Route as ApiGeminiImageGaModelsRouteImport } from './routes/api.gemini-image-ga-models'
+import { Route as ApiGeminiNativeImageWireRouteImport } from './routes/api.gemini-native-image-wire'
+import { Route as ApiGenerationPersistenceResumeRouteImport } from './routes/api.generation-persistence-resume'
+import { Route as ApiGenerationPersistenceServerRouteImport } from './routes/api.generation-persistence-server'
+import { Route as ApiHarnessTestRouteImport } from './routes/api.harness-test'
+import { Route as ApiHarnessTurnOverridesRouteImport } from './routes/api.harness-turn-overrides'
+import { Route as ApiImageRouteImport } from './routes/api.image'
+import { Route as ApiInterruptsTestRouteImport } from './routes/api.interrupts-test'
+import { Route as ApiJoinRunClientToolRouteImport } from './routes/api.join-run-client-tool'
+import { Route as ApiLazyToolsWireRouteImport } from './routes/api.lazy-tools-wire'
+import { Route as ApiMaxToolCallsWireRouteImport } from './routes/api.max-tool-calls-wire'
+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 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'
+import { Route as ApiMcpNoTasksServerRouteImport } from './routes/api.mcp-no-tasks-server'
+import { Route as ApiMcpPolicyTestRouteImport } from './routes/api.mcp-policy-test'
+import { Route as ApiMcpServerRouteImport } from './routes/api.mcp-server'
+import { Route as ApiMcpStatusTestRouteImport } from './routes/api.mcp-status-test'
+import { Route as ApiMcpTaskErrorsRouteImport } from './routes/api.mcp-task-errors'
+import { Route as ApiMcpTestRouteImport } from './routes/api.mcp-test'
+import { Route as ApiMcpToolOptionsWireRouteImport } from './routes/api.mcp-tool-options-wire'
+import { Route as ApiMcpTypedServerRouteImport } from './routes/api.mcp-typed-server'
+import { Route as ApiMcpTypedTestRouteImport } from './routes/api.mcp-typed-test'
+import { Route as ApiMessageHistoryPagingRouteImport } from './routes/api.message-history-paging'
+import { Route as ApiMessageIdsRouteImport } from './routes/api.message-ids'
+import { Route as ApiMidConversationChangesWireRouteImport } from './routes/api.mid-conversation-changes-wire'
+import { Route as ApiMiddlewareTestRouteImport } from './routes/api.middleware-test'
+import { Route as ApiMistralStrictToolNullWireRouteImport } from './routes/api.mistral-strict-tool-null-wire'
+import { Route as ApiMoonshotUsageDetailsRouteImport } from './routes/api.moonshot-usage-details'
+import { Route as ApiMultimodalToolResultWireRouteImport } from './routes/api.multimodal-tool-result-wire'
+import { Route as ApiNonStreamingRunErrorRouteImport } from './routes/api.non-streaming-run-error'
+import { Route as ApiOpenaiCompletedResponseTextRouteImport } from './routes/api.openai-completed-response-text'
 import { Route as ApiOpenaiImage25ModelsRouteImport } from './routes/api.openai-image-2-5-models'
 import { Route as ApiOpenaiMalformedToolArgumentsRouteImport } from './routes/api.openai-malformed-tool-arguments'
-import { Route as ApiOpenaiCompletedResponseTextRouteImport } from './routes/api.openai-completed-response-text'
-import { Route as ApiNonStreamingRunErrorRouteImport } from './routes/api.non-streaming-run-error'
-import { Route as ApiMultimodalToolResultWireRouteImport } from './routes/api.multimodal-tool-result-wire'
-import { Route as ApiMoonshotUsageDetailsRouteImport } from './routes/api.moonshot-usage-details'
-import { Route as ApiMistralStrictToolNullWireRouteImport } from './routes/api.mistral-strict-tool-null-wire'
-import { Route as ApiMiddlewareTestRouteImport } from './routes/api.middleware-test'
-import { Route as ApiMidConversationChangesWireRouteImport } from './routes/api.mid-conversation-changes-wire'
-import { Route as ApiMessageIdsRouteImport } from './routes/api.message-ids'
-import { Route as ApiMessageHistoryPagingRouteImport } from './routes/api.message-history-paging'
-import { Route as ApiMcpTypedTestRouteImport } from './routes/api.mcp-typed-test'
-import { Route as ApiMcpTypedServerRouteImport } from './routes/api.mcp-typed-server'
-import { Route as ApiMcpToolOptionsWireRouteImport } from './routes/api.mcp-tool-options-wire'
-import { Route as ApiMcpTestRouteImport } from './routes/api.mcp-test'
-import { Route as ApiMcpTaskErrorsRouteImport } from './routes/api.mcp-task-errors'
-import { Route as ApiMcpStatusTestRouteImport } from './routes/api.mcp-status-test'
-import { Route as ApiMcpServerRouteImport } from './routes/api.mcp-server'
-import { Route as ApiMcpPolicyTestRouteImport } from './routes/api.mcp-policy-test'
-import { Route as ApiMcpNoTasksServerRouteImport } from './routes/api.mcp-no-tasks-server'
-import { Route as ApiMcpManagedTestRouteImport } from './routes/api.mcp-managed-test'
-import { Route as ApiMcpLifecycleTestRouteImport } from './routes/api.mcp-lifecycle-test'
-import { Route as ApiMcpInputTestRouteImport } from './routes/api.mcp-input-test'
-import { Route as ApiMcpInputServerRouteImport } from './routes/api.mcp-input-server'
-import { Route as ApiMcpAppsServerRouteImport } from './routes/api.mcp-apps-server'
-import { Route as ApiMcpAppsChatRouteImport } from './routes/api.mcp-apps-chat'
-import { Route as ApiMcpAppsCallRouteImport } from './routes/api.mcp-apps-call'
-import { Route as ApiMaxToolCallsWireRouteImport } from './routes/api.max-tool-calls-wire'
-import { Route as ApiLazyToolsWireRouteImport } from './routes/api.lazy-tools-wire'
-import { Route as ApiJoinRunClientToolRouteImport } from './routes/api.join-run-client-tool'
-import { Route as ApiInterruptsTestRouteImport } from './routes/api.interrupts-test'
-import { Route as ApiImageRouteImport } from './routes/api.image'
-import { Route as ApiHarnessTurnOverridesRouteImport } from './routes/api.harness-turn-overrides'
-import { Route as ApiHarnessTestRouteImport } from './routes/api.harness-test'
-import { Route as ApiGenerationPersistenceServerRouteImport } from './routes/api.generation-persistence-server'
-import { Route as ApiGenerationPersistenceResumeRouteImport } from './routes/api.generation-persistence-resume'
-import { Route as ApiGeminiNativeImageWireRouteImport } from './routes/api.gemini-native-image-wire'
-import { Route as ApiGeminiImageGaModelsRouteImport } from './routes/api.gemini-image-ga-models'
-import { Route as ApiForeignInterruptRouteImport } from './routes/api.foreign-interrupt'
-import { Route as ApiFileSourceWireRouteImport } from './routes/api.file-source-wire'
-import { Route as ApiEmbeddingRouteImport } from './routes/api.embedding'
-import { Route as ApiDurableTakeoverRouteImport } from './routes/api.durable-takeover'
-import { Route as ApiDurableDeliveryRouteImport } from './routes/api.durable-delivery'
-import { Route as ApiDevtoolsMemoryRouteImport } from './routes/api.devtools-memory'
-import { Route as ApiCompactionWireRouteImport } from './routes/api.compaction-wire'
-import { Route as ApiCompactionDurableWireRouteImport } from './routes/api.compaction-durable-wire'
-import { Route as ApiCloudflareBindingWireRouteImport } from './routes/api.cloudflare-binding-wire'
-import { Route as ApiChatRouteImport } from './routes/api.chat'
-import { Route as ApiByteplusSeedance1080pWireRouteImport } from './routes/api.byteplus-seedance-1080p-wire'
-import { Route as ApiByokChatRouteImport } from './routes/api.byok-chat'
-import { Route as ApiBedrockConverseCacheRouteImport } from './routes/api.bedrock-converse-cache'
-import { Route as ApiAudioRouteImport } from './routes/api.audio'
-import { Route as ApiArktypeToolWireRouteImport } from './routes/api.arktype-tool-wire'
-import { Route as ApiAnthropicThinkingOrderWireRouteImport } from './routes/api.anthropic-thinking-order-wire'
-import { Route as ApiAnthropicStructuredUsageRouteImport } from './routes/api.anthropic-structured-usage'
-import { Route as ApiAnthropicSkillsWireRouteImport } from './routes/api.anthropic-skills-wire'
-import { Route as ApiAnthropicRedactedThinkingWireRouteImport } from './routes/api.anthropic-redacted-thinking-wire'
-import { Route as ApiAnthropicOpus5CombinedWireRouteImport } from './routes/api.anthropic-opus-5-combined-wire'
-import { Route as ApiAnthropicMultiTurnStructuredWireRouteImport } from './routes/api.anthropic-multi-turn-structured-wire'
-import { Route as ApiAnthropicBugTestRouteImport } from './routes/api.anthropic-bug-test'
-import { Route as ProviderFeatureRouteImport } from './routes/$provider/$feature'
-import { Route as ApiVideoStreamRouteImport } from './routes/api.video.stream'
-import { Route as ApiTtsStreamRouteImport } from './routes/api.tts.stream'
-import { Route as ApiTranscriptionStreamRouteImport } from './routes/api.transcription.stream'
-import { Route as ApiImageStreamRouteImport } from './routes/api.image.stream'
-import { Route as ApiHarnessProtocolSplatRouteImport } from './routes/api.harness-protocol.$'
+import { Route as ApiOpenaiShellSkillsWireRouteImport } from './routes/api.openai-shell-skills-wire'
+import { Route as ApiOpenaiStrictToolNullWireRouteImport } from './routes/api.openai-strict-tool-null-wire'
+import { Route as ApiOpenaiUsageDetailsRouteImport } from './routes/api.openai-usage-details'
+import { Route as ApiOpenrouterCostRouteImport } from './routes/api.openrouter-cost'
+import { Route as ApiOpenrouterJsonObjectWireRouteImport } from './routes/api.openrouter-json-object-wire'
+import { Route as ApiOpenrouterReasoningWireRouteImport } from './routes/api.openrouter-reasoning-wire'
+import { Route as ApiOpenrouterRetryCodesRouteImport } from './routes/api.openrouter-retry-codes'
+import { Route as ApiOpenrouterStreamOptionsWireRouteImport } from './routes/api.openrouter-stream-options-wire'
+import { Route as ApiOpenrouterStrictToolOptionalsRouteImport } from './routes/api.openrouter-strict-tool-optionals'
+import { Route as ApiOpenrouterWebToolsWireRouteImport } from './routes/api.openrouter-web-tools-wire'
+import { Route as ApiOtelMediaRouteImport } from './routes/api.otel-media'
+import { Route as ApiOtelTranscriptionRouteImport } from './routes/api.otel-transcription'
+import { Route as ApiOtelUsageRouteImport } from './routes/api.otel-usage'
+import { Route as ApiPersistenceDurabilityRouteImport } from './routes/api.persistence-durability'
+import { Route as ApiPortableSkillsWireRouteImport } from './routes/api.portable-skills-wire'
+import { Route as ApiPromptCacheWireRouteImport } from './routes/api.prompt-cache-wire'
+import { Route as ApiProviderSearchMetadataWireRouteImport } from './routes/api.provider-search-metadata-wire'
+import { Route as ApiProviderToolDispatchWireRouteImport } from './routes/api.provider-tool-dispatch-wire'
+import { Route as ApiSandboxDurabilityRouteImport } from './routes/api.sandbox-durability'
+import { Route as ApiSandboxFilePersistenceRouteImport } from './routes/api.sandbox-file-persistence'
+import { Route as ApiSandboxToolHistoryRouteImport } from './routes/api.sandbox-tool-history'
+import { Route as ApiStructuredOutputLengthWireRouteImport } from './routes/api.structured-output-length-wire'
+import { Route as ApiSubagentsTestRouteImport } from './routes/api.subagents-test'
+import { Route as ApiSummarizeRouteImport } from './routes/api.summarize'
+import { Route as ApiTextFirstToolWireRouteImport } from './routes/api.text-first-tool-wire'
+import { Route as ApiToolCallLifecycleWireRouteImport } from './routes/api.tool-call-lifecycle-wire'
+import { Route as ApiToolChoiceWireRouteImport } from './routes/api.tool-choice-wire'
+import { Route as ApiToolFirstTextWireRouteImport } from './routes/api.tool-first-text-wire'
+import { Route as ApiToolsTestRouteImport } from './routes/api.tools-test'
+import { Route as ApiTranscriptionRouteImport } from './routes/api.transcription'
+import { Route as ApiTtsRouteImport } from './routes/api.tts'
+import { Route as ApiVideoRouteImport } from './routes/api.video'
+import { Route as ApiVideoLiveRouteImport } from './routes/api.video-live'
+import { Route as ApiVoiceRouteImport } from './routes/api.voice'
+import { Route as ApiWebMcpPageToolsRouteImport } from './routes/api.web-mcp-page-tools'
+import { Route as ApiWorldRouteImport } from './routes/api.world'
 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'
+import { Route as ApiVideoStreamRouteImport } from './routes/api.video.stream'
 
-const ApiAdapterConfigReasoningWireRoute =
-  ApiAdapterConfigReasoningWireRouteImport.update({
-    id: '/api/adapter-config-reasoning-wire',
-    path: '/api/adapter-config-reasoning-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiAnthropicStructuredUsageRoute =
-  ApiAnthropicStructuredUsageRouteImport.update({
-    id: '/api/anthropic-structured-usage',
-    path: '/api/anthropic-structured-usage',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiAnthropicThinkingOrderWireRoute =
-  ApiAnthropicThinkingOrderWireRouteImport.update({
-    id: '/api/anthropic-thinking-order-wire',
-    path: '/api/anthropic-thinking-order-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiAnthropicTruncatedToolInputWireRoute =
-  ApiAnthropicTruncatedToolInputWireRouteImport.update({
-    id: '/api/anthropic-truncated-tool-input-wire',
-    path: '/api/anthropic-truncated-tool-input-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiArktypeToolWireRoute = ApiArktypeToolWireRouteImport.update({
-  id: '/api/arktype-tool-wire',
-  path: '/api/arktype-tool-wire',
-  getParentRoute: () => rootRouteImport,
-} as any)
-const ApiActivityTestRoute = ApiActivityTestRouteImport.update({
-  id: '/api/activity-test',
-  path: '/api/activity-test',
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
   getParentRoute: () => rootRouteImport,
 } as any)
 const ActivityTestRoute = ActivityTestRouteImport.update({
   id: '/activity-test',
   path: '/activity-test',
   getParentRoute: () => rootRouteImport,
-} as any)
-const ApiForeignClientToolRoute = ApiForeignClientToolRouteImport.update({
-  id: '/api/foreign-client-tool',
-  path: '/api/foreign-client-tool',
-  getParentRoute: () => rootRouteImport,
-} as any)
-const ApiForeignChunkEventsRoute = ApiForeignChunkEventsRouteImport.update({
-  id: '/api/foreign-chunk-events',
-  path: '/api/foreign-chunk-events',
-  getParentRoute: () => rootRouteImport,
-} as any)
-const ApiAnthropicTruncatedToolInputWireRoute =
-  ApiAnthropicTruncatedToolInputWireRouteImport.update({
-    id: '/api/anthropic-truncated-tool-input-wire',
-    path: '/api/anthropic-truncated-tool-input-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiArktypeToolWireRoute = ApiArktypeToolWireRouteImport.update({
-  id: '/api/arktype-tool-wire',
-  path: '/api/arktype-tool-wire',
-  getParentRoute: () => rootRouteImport,
-} as any)
-const ApiAnthropicSonnet55WireRoute =
-  ApiAnthropicSonnet55WireRouteImport.update({
-    id: '/api/anthropic-sonnet-5-5-wire',
-    path: '/api/anthropic-sonnet-5-5-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiAnthropicStructuredUsageRoute =
-  ApiAnthropicStructuredUsageRouteImport.update({
-    id: '/api/anthropic-structured-usage',
-    path: '/api/anthropic-structured-usage',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiAnthropicThinkingOrderWireRoute =
-  ApiAnthropicThinkingOrderWireRouteImport.update({
-    id: '/api/anthropic-thinking-order-wire',
-    path: '/api/anthropic-thinking-order-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiAnthropicTruncatedToolInputWireRoute =
-  ApiAnthropicTruncatedToolInputWireRouteImport.update({
-    id: '/api/anthropic-truncated-tool-input-wire',
-    path: '/api/anthropic-truncated-tool-input-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiArktypeToolWireRoute = ApiArktypeToolWireRouteImport.update({
-  id: '/api/arktype-tool-wire',
-  path: '/api/arktype-tool-wire',
-  getParentRoute: () => rootRouteImport,
-} as any)
-const ApiAnthropicMaxTokensUsageRoute =
-  ApiAnthropicMaxTokensUsageRouteImport.update({
-    id: '/api/anthropic-max-tokens-usage',
-    path: '/api/anthropic-max-tokens-usage',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiAnthropicMultiTurnStructuredWireRoute =
-  ApiAnthropicMultiTurnStructuredWireRouteImport.update({
-    id: '/api/anthropic-multi-turn-structured-wire',
-    path: '/api/anthropic-multi-turn-structured-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiAnthropicOpus5CombinedWireRoute =
-  ApiAnthropicOpus5CombinedWireRouteImport.update({
-    id: '/api/anthropic-opus-5-combined-wire',
-    path: '/api/anthropic-opus-5-combined-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiAnthropicRedactedThinkingWireRoute =
-  ApiAnthropicRedactedThinkingWireRouteImport.update({
-    id: '/api/anthropic-redacted-thinking-wire',
-    path: '/api/anthropic-redacted-thinking-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiAnthropicSkillsWireRoute = ApiAnthropicSkillsWireRouteImport.update({
-  id: '/api/anthropic-skills-wire',
-  path: '/api/anthropic-skills-wire',
-  getParentRoute: () => rootRouteImport,
-} as any)
-const ForeignClientToolRoute = ForeignClientToolRouteImport.update({
-  id: '/foreign-client-tool',
-  path: '/foreign-client-tool',
-  getParentRoute: () => rootRouteImport,
-} as any)
-const ForeignChunkEventsRoute = ForeignChunkEventsRouteImport.update({
-  id: '/foreign-chunk-events',
-  path: '/foreign-chunk-events',
-  getParentRoute: () => rootRouteImport,
-} as any)
-const WebsocketAdapterRoute = WebsocketAdapterRouteImport.update({
-  id: '/websocket-adapter',
-  path: '/websocket-adapter',
-  getParentRoute: () => rootRouteImport,
-} as any)
-const WebMcpToolsRoute = WebMcpToolsRouteImport.update({
-  id: '/web-mcp-tools',
-  path: '/web-mcp-tools',
-  getParentRoute: () => rootRouteImport,
-} as any)
-const WebMcpPageToolsRoute = WebMcpPageToolsRouteImport.update({
-  id: '/web-mcp-page-tools',
-  path: '/web-mcp-page-tools',
+} as any)
+const ByokRoute = ByokRouteImport.update({
+  id: '/byok',
+  path: '/byok',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ToolsTestRoute = ToolsTestRouteImport.update({
-  id: '/tools-test',
-  path: '/tools-test',
+const ChatClientDefaultBridgeRoute = ChatClientDefaultBridgeRouteImport.update({
+  id: '/chat-client-default-bridge',
+  path: '/chat-client-default-bridge',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ToolFirstTextRoute = ToolFirstTextRouteImport.update({
-  id: '/tool-first-text',
-  path: '/tool-first-text',
+const ChatClientStreamProcessingRoute =
+  ChatClientStreamProcessingRouteImport.update({
+    id: '/chat-client-stream-processing',
+    path: '/chat-client-stream-processing',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ClientMountHydrateRoute = ClientMountHydrateRouteImport.update({
+  id: '/client-mount-hydrate',
+  path: '/client-mount-hydrate',
   getParentRoute: () => rootRouteImport,
 } as any)
-const TextFirstToolRoute = TextFirstToolRouteImport.update({
-  id: '/text-first-tool',
-  path: '/text-first-tool',
+const DevtoolsChatRoute = DevtoolsChatRouteImport.update({
+  id: '/devtools-chat',
+  path: '/devtools-chat',
   getParentRoute: () => rootRouteImport,
 } as any)
-const SubagentsUiTestRoute = SubagentsUiTestRouteImport.update({
-  id: '/subagents-ui-test',
-  path: '/subagents-ui-test',
+const DevtoolsGenerationHooksRoute = DevtoolsGenerationHooksRouteImport.update({
+  id: '/devtools-generation-hooks',
+  path: '/devtools-generation-hooks',
   getParentRoute: () => rootRouteImport,
 } as any)
-const SubagentsTestRoute = SubagentsTestRouteImport.update({
-  id: '/subagents-test',
-  path: '/subagents-test',
+const DevtoolsMemoryRoute = DevtoolsMemoryRouteImport.update({
+  id: '/devtools-memory',
+  path: '/devtools-memory',
   getParentRoute: () => rootRouteImport,
 } as any)
-const PersistenceDurabilityRoute = PersistenceDurabilityRouteImport.update({
-  id: '/persistence-durability',
-  path: '/persistence-durability',
+const DevtoolsRouteARoute = DevtoolsRouteARouteImport.update({
+  id: '/devtools-route-a',
+  path: '/devtools-route-a',
   getParentRoute: () => rootRouteImport,
 } as any)
-const MiddlewareTestRoute = MiddlewareTestRouteImport.update({
-  id: '/middleware-test',
-  path: '/middleware-test',
+const DevtoolsRouteBRoute = DevtoolsRouteBRouteImport.update({
+  id: '/devtools-route-b',
+  path: '/devtools-route-b',
   getParentRoute: () => rootRouteImport,
 } as any)
-const MessageHistoryPagingRoute = MessageHistoryPagingRouteImport.update({
-  id: '/message-history-paging',
-  path: '/message-history-paging',
+const DevtoolsStructuredRoute = DevtoolsStructuredRouteImport.update({
+  id: '/devtools-structured',
+  path: '/devtools-structured',
   getParentRoute: () => rootRouteImport,
 } as any)
-const MarkdownCjkRoute = MarkdownCjkRouteImport.update({
-  id: '/markdown-cjk',
-  path: '/markdown-cjk',
+const DevtoolsSubagentsRoute = DevtoolsSubagentsRouteImport.update({
+  id: '/devtools-subagents',
+  path: '/devtools-subagents',
   getParentRoute: () => rootRouteImport,
 } as any)
-const JoinRunClientToolRoute = JoinRunClientToolRouteImport.update({
-  id: '/join-run-client-tool',
-  path: '/join-run-client-tool',
+const DevtoolsToolsRoute = DevtoolsToolsRouteImport.update({
+  id: '/devtools-tools',
+  path: '/devtools-tools',
   getParentRoute: () => rootRouteImport,
 } as any)
-const InterruptsTestRoute = InterruptsTestRouteImport.update({
-  id: '/interrupts-test',
-  path: '/interrupts-test',
+const ForeignChunkEventsRoute = ForeignChunkEventsRouteImport.update({
+  id: '/foreign-chunk-events',
+  path: '/foreign-chunk-events',
   getParentRoute: () => rootRouteImport,
 } as any)
-const InterruptLineageRoute = InterruptLineageRouteImport.update({
-  id: '/interrupt-lineage',
-  path: '/interrupt-lineage',
+const ForeignClientToolRoute = ForeignClientToolRouteImport.update({
+  id: '/foreign-client-tool',
+  path: '/foreign-client-tool',
   getParentRoute: () => rootRouteImport,
 } as any)
-const HeadlessUiRoute = HeadlessUiRouteImport.update({
-  id: '/headless-ui',
-  path: '/headless-ui',
+const ForeignInterruptRoute = ForeignInterruptRouteImport.update({
+  id: '/foreign-interrupt',
+  path: '/foreign-interrupt',
   getParentRoute: () => rootRouteImport,
 } as any)
-const GenerationPersistenceServerRoute =
-  GenerationPersistenceServerRouteImport.update({
-    id: '/generation-persistence-server',
-    path: '/generation-persistence-server',
-    getParentRoute: () => rootRouteImport,
-  } as any)
 const GenerationPersistenceResumeRoute =
   GenerationPersistenceResumeRouteImport.update({
     id: '/generation-persistence-resume',
     path: '/generation-persistence-resume',
     getParentRoute: () => rootRouteImport,
   } as any)
-const ForeignInterruptRoute = ForeignInterruptRouteImport.update({
-  id: '/foreign-interrupt',
-  path: '/foreign-interrupt',
-  getParentRoute: () => rootRouteImport,
-} as any)
-const DevtoolsToolsRoute = DevtoolsToolsRouteImport.update({
-  id: '/devtools-tools',
-  path: '/devtools-tools',
-  getParentRoute: () => rootRouteImport,
-} as any)
-const DevtoolsSubagentsRoute = DevtoolsSubagentsRouteImport.update({
-  id: '/devtools-subagents',
-  path: '/devtools-subagents',
+const GenerationPersistenceServerRoute =
+  GenerationPersistenceServerRouteImport.update({
+    id: '/generation-persistence-server',
+    path: '/generation-persistence-server',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const HeadlessUiRoute = HeadlessUiRouteImport.update({
+  id: '/headless-ui',
+  path: '/headless-ui',
   getParentRoute: () => rootRouteImport,
 } as any)
-const DevtoolsStructuredRoute = DevtoolsStructuredRouteImport.update({
-  id: '/devtools-structured',
-  path: '/devtools-structured',
+const InterruptLineageRoute = InterruptLineageRouteImport.update({
+  id: '/interrupt-lineage',
+  path: '/interrupt-lineage',
   getParentRoute: () => rootRouteImport,
 } as any)
-const DevtoolsRouteBRoute = DevtoolsRouteBRouteImport.update({
-  id: '/devtools-route-b',
-  path: '/devtools-route-b',
+const InterruptsTestRoute = InterruptsTestRouteImport.update({
+  id: '/interrupts-test',
+  path: '/interrupts-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const DevtoolsRouteARoute = DevtoolsRouteARouteImport.update({
-  id: '/devtools-route-a',
-  path: '/devtools-route-a',
+const JoinRunClientToolRoute = JoinRunClientToolRouteImport.update({
+  id: '/join-run-client-tool',
+  path: '/join-run-client-tool',
   getParentRoute: () => rootRouteImport,
 } as any)
-const DevtoolsMemoryRoute = DevtoolsMemoryRouteImport.update({
-  id: '/devtools-memory',
-  path: '/devtools-memory',
+const MarkdownCjkRoute = MarkdownCjkRouteImport.update({
+  id: '/markdown-cjk',
+  path: '/markdown-cjk',
   getParentRoute: () => rootRouteImport,
 } as any)
-const DevtoolsGenerationHooksRoute = DevtoolsGenerationHooksRouteImport.update({
-  id: '/devtools-generation-hooks',
-  path: '/devtools-generation-hooks',
+const MessageHistoryPagingRoute = MessageHistoryPagingRouteImport.update({
+  id: '/message-history-paging',
+  path: '/message-history-paging',
   getParentRoute: () => rootRouteImport,
 } as any)
-const DevtoolsChatRoute = DevtoolsChatRouteImport.update({
-  id: '/devtools-chat',
-  path: '/devtools-chat',
+const MiddlewareTestRoute = MiddlewareTestRouteImport.update({
+  id: '/middleware-test',
+  path: '/middleware-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ClientMountHydrateRoute = ClientMountHydrateRouteImport.update({
-  id: '/client-mount-hydrate',
-  path: '/client-mount-hydrate',
+const PersistenceDurabilityRoute = PersistenceDurabilityRouteImport.update({
+  id: '/persistence-durability',
+  path: '/persistence-durability',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ChatClientStreamProcessingRoute =
-  ChatClientStreamProcessingRouteImport.update({
-    id: '/chat-client-stream-processing',
-    path: '/chat-client-stream-processing',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ChatClientDefaultBridgeRoute = ChatClientDefaultBridgeRouteImport.update({
-  id: '/chat-client-default-bridge',
-  path: '/chat-client-default-bridge',
+const SubagentsTestRoute = SubagentsTestRouteImport.update({
+  id: '/subagents-test',
+  path: '/subagents-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ByokRoute = ByokRouteImport.update({
-  id: '/byok',
-  path: '/byok',
+const SubagentsUiTestRoute = SubagentsUiTestRouteImport.update({
+  id: '/subagents-ui-test',
+  path: '/subagents-ui-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const IndexRoute = IndexRouteImport.update({
-  id: '/',
-  path: '/',
+const TextFirstToolRoute = TextFirstToolRouteImport.update({
+  id: '/text-first-tool',
+  path: '/text-first-tool',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ProviderIndexRoute = ProviderIndexRouteImport.update({
-  id: '/$provider/',
-  path: '/$provider/',
+const ToolFirstTextRoute = ToolFirstTextRouteImport.update({
+  id: '/tool-first-text',
+  path: '/tool-first-text',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiWorldRoute = ApiWorldRouteImport.update({
-  id: '/api/world',
-  path: '/api/world',
+const ToolsTestRoute = ToolsTestRouteImport.update({
+  id: '/tools-test',
+  path: '/tools-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiWebMcpPageToolsRoute = ApiWebMcpPageToolsRouteImport.update({
-  id: '/api/web-mcp-page-tools',
-  path: '/api/web-mcp-page-tools',
+const WebMcpPageToolsRoute = WebMcpPageToolsRouteImport.update({
+  id: '/web-mcp-page-tools',
+  path: '/web-mcp-page-tools',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiVoiceRoute = ApiVoiceRouteImport.update({
-  id: '/api/voice',
-  path: '/api/voice',
+const WebMcpToolsRoute = WebMcpToolsRouteImport.update({
+  id: '/web-mcp-tools',
+  path: '/web-mcp-tools',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiVideoLiveRoute = ApiVideoLiveRouteImport.update({
-  id: '/api/video-live',
-  path: '/api/video-live',
+const WebsocketAdapterRoute = WebsocketAdapterRouteImport.update({
+  id: '/websocket-adapter',
+  path: '/websocket-adapter',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiVideoRoute = ApiVideoRouteImport.update({
-  id: '/api/video',
-  path: '/api/video',
+const ProviderIndexRoute = ProviderIndexRouteImport.update({
+  id: '/$provider/',
+  path: '/$provider/',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiTtsRoute = ApiTtsRouteImport.update({
-  id: '/api/tts',
-  path: '/api/tts',
+const ProviderFeatureRoute = ProviderFeatureRouteImport.update({
+  id: '/$provider/$feature',
+  path: '/$provider/$feature',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiTranscriptionRoute = ApiTranscriptionRouteImport.update({
-  id: '/api/transcription',
-  path: '/api/transcription',
+const ApiActivityTestRoute = ApiActivityTestRouteImport.update({
+  id: '/api/activity-test',
+  path: '/api/activity-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiToolsTestRoute = ApiToolsTestRouteImport.update({
-  id: '/api/tools-test',
-  path: '/api/tools-test',
+const ApiAdapterConfigReasoningWireRoute =
+  ApiAdapterConfigReasoningWireRouteImport.update({
+    id: '/api/adapter-config-reasoning-wire',
+    path: '/api/adapter-config-reasoning-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiAnthropicBugTestRoute = ApiAnthropicBugTestRouteImport.update({
+  id: '/api/anthropic-bug-test',
+  path: '/api/anthropic-bug-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiToolFirstTextWireRoute = ApiToolFirstTextWireRouteImport.update({
-  id: '/api/tool-first-text-wire',
-  path: '/api/tool-first-text-wire',
+const ApiAnthropicMaxTokensUsageRoute =
+  ApiAnthropicMaxTokensUsageRouteImport.update({
+    id: '/api/anthropic-max-tokens-usage',
+    path: '/api/anthropic-max-tokens-usage',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiAnthropicMultiTurnStructuredWireRoute =
+  ApiAnthropicMultiTurnStructuredWireRouteImport.update({
+    id: '/api/anthropic-multi-turn-structured-wire',
+    path: '/api/anthropic-multi-turn-structured-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiAnthropicOpus5CombinedWireRoute =
+  ApiAnthropicOpus5CombinedWireRouteImport.update({
+    id: '/api/anthropic-opus-5-combined-wire',
+    path: '/api/anthropic-opus-5-combined-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiAnthropicRedactedThinkingWireRoute =
+  ApiAnthropicRedactedThinkingWireRouteImport.update({
+    id: '/api/anthropic-redacted-thinking-wire',
+    path: '/api/anthropic-redacted-thinking-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiAnthropicSkillsWireRoute = ApiAnthropicSkillsWireRouteImport.update({
+  id: '/api/anthropic-skills-wire',
+  path: '/api/anthropic-skills-wire',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiToolCallLifecycleWireRoute =
-  ApiToolCallLifecycleWireRouteImport.update({
-    id: '/api/tool-call-lifecycle-wire',
-    path: '/api/tool-call-lifecycle-wire',
+const ApiAnthropicSonnet55WireRoute =
+  ApiAnthropicSonnet55WireRouteImport.update({
+    id: '/api/anthropic-sonnet-5-5-wire',
+    path: '/api/anthropic-sonnet-5-5-wire',
     getParentRoute: () => rootRouteImport,
   } as any)
-const ApiTextFirstToolWireRoute = ApiTextFirstToolWireRouteImport.update({
-  id: '/api/text-first-tool-wire',
-  path: '/api/text-first-tool-wire',
+const ApiAnthropicStructuredUsageRoute =
+  ApiAnthropicStructuredUsageRouteImport.update({
+    id: '/api/anthropic-structured-usage',
+    path: '/api/anthropic-structured-usage',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiAnthropicThinkingOrderWireRoute =
+  ApiAnthropicThinkingOrderWireRouteImport.update({
+    id: '/api/anthropic-thinking-order-wire',
+    path: '/api/anthropic-thinking-order-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiAnthropicTruncatedToolInputWireRoute =
+  ApiAnthropicTruncatedToolInputWireRouteImport.update({
+    id: '/api/anthropic-truncated-tool-input-wire',
+    path: '/api/anthropic-truncated-tool-input-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiArktypeToolWireRoute = ApiArktypeToolWireRouteImport.update({
+  id: '/api/arktype-tool-wire',
+  path: '/api/arktype-tool-wire',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiSummarizeRoute = ApiSummarizeRouteImport.update({
-  id: '/api/summarize',
-  path: '/api/summarize',
+const ApiAudioRoute = ApiAudioRouteImport.update({
+  id: '/api/audio',
+  path: '/api/audio',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiSubagentsTestRoute = ApiSubagentsTestRouteImport.update({
-  id: '/api/subagents-test',
-  path: '/api/subagents-test',
+const ApiBedrockConverseCacheRoute = ApiBedrockConverseCacheRouteImport.update({
+  id: '/api/bedrock-converse-cache',
+  path: '/api/bedrock-converse-cache',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiStructuredOutputLengthWireRoute =
-  ApiStructuredOutputLengthWireRouteImport.update({
-    id: '/api/structured-output-length-wire',
-    path: '/api/structured-output-length-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiSandboxToolHistoryRoute = ApiSandboxToolHistoryRouteImport.update({
-  id: '/api/sandbox-tool-history',
-  path: '/api/sandbox-tool-history',
+const ApiByokChatRoute = ApiByokChatRouteImport.update({
+  id: '/api/byok-chat',
+  path: '/api/byok-chat',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiSandboxFilePersistenceRoute =
-  ApiSandboxFilePersistenceRouteImport.update({
-    id: '/api/sandbox-file-persistence',
-    path: '/api/sandbox-file-persistence',
+const ApiByteplusSeedance1080pWireRoute =
+  ApiByteplusSeedance1080pWireRouteImport.update({
+    id: '/api/byteplus-seedance-1080p-wire',
+    path: '/api/byteplus-seedance-1080p-wire',
     getParentRoute: () => rootRouteImport,
   } as any)
-const ApiSandboxDurabilityRoute = ApiSandboxDurabilityRouteImport.update({
-  id: '/api/sandbox-durability',
-  path: '/api/sandbox-durability',
+const ApiChatRoute = ApiChatRouteImport.update({
+  id: '/api/chat',
+  path: '/api/chat',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiProviderToolDispatchWireRoute =
-  ApiProviderToolDispatchWireRouteImport.update({
-    id: '/api/provider-tool-dispatch-wire',
-    path: '/api/provider-tool-dispatch-wire',
+const ApiCloudflareBindingWireRoute =
+  ApiCloudflareBindingWireRouteImport.update({
+    id: '/api/cloudflare-binding-wire',
+    path: '/api/cloudflare-binding-wire',
     getParentRoute: () => rootRouteImport,
   } as any)
-const ApiProviderSearchMetadataWireRoute =
-  ApiProviderSearchMetadataWireRouteImport.update({
-    id: '/api/provider-search-metadata-wire',
-    path: '/api/provider-search-metadata-wire',
+const ApiCompactionDurableWireRoute =
+  ApiCompactionDurableWireRouteImport.update({
+    id: '/api/compaction-durable-wire',
+    path: '/api/compaction-durable-wire',
     getParentRoute: () => rootRouteImport,
   } as any)
-const ApiPromptCacheWireRoute = ApiPromptCacheWireRouteImport.update({
-  id: '/api/prompt-cache-wire',
-  path: '/api/prompt-cache-wire',
+const ApiCompactionWireRoute = ApiCompactionWireRouteImport.update({
+  id: '/api/compaction-wire',
+  path: '/api/compaction-wire',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiPortableSkillsWireRoute = ApiPortableSkillsWireRouteImport.update({
-  id: '/api/portable-skills-wire',
-  path: '/api/portable-skills-wire',
+const ApiDevtoolsMemoryRoute = ApiDevtoolsMemoryRouteImport.update({
+  id: '/api/devtools-memory',
+  path: '/api/devtools-memory',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiPersistenceDurabilityRoute =
-  ApiPersistenceDurabilityRouteImport.update({
-    id: '/api/persistence-durability',
-    path: '/api/persistence-durability',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiOtelUsageRoute = ApiOtelUsageRouteImport.update({
-  id: '/api/otel-usage',
-  path: '/api/otel-usage',
+const ApiDurableDeliveryRoute = ApiDurableDeliveryRouteImport.update({
+  id: '/api/durable-delivery',
+  path: '/api/durable-delivery',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiOtelTranscriptionRoute = ApiOtelTranscriptionRouteImport.update({
-  id: '/api/otel-transcription',
-  path: '/api/otel-transcription',
+const ApiDurableTakeoverRoute = ApiDurableTakeoverRouteImport.update({
+  id: '/api/durable-takeover',
+  path: '/api/durable-takeover',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiOtelMediaRoute = ApiOtelMediaRouteImport.update({
-  id: '/api/otel-media',
-  path: '/api/otel-media',
+const ApiEmbeddingRoute = ApiEmbeddingRouteImport.update({
+  id: '/api/embedding',
+  path: '/api/embedding',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiOpenrouterWebToolsWireRoute =
-  ApiOpenrouterWebToolsWireRouteImport.update({
-    id: '/api/openrouter-web-tools-wire',
-    path: '/api/openrouter-web-tools-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiOpenrouterStreamOptionsWireRoute =
-  ApiOpenrouterStreamOptionsWireRouteImport.update({
-    id: '/api/openrouter-stream-options-wire',
-    path: '/api/openrouter-stream-options-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiOpenrouterStrictToolOptionalsRoute =
-  ApiOpenrouterStrictToolOptionalsRouteImport.update({
-    id: '/api/openrouter-strict-tool-optionals',
-    path: '/api/openrouter-strict-tool-optionals',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiOpenrouterRetryCodesRoute = ApiOpenrouterRetryCodesRouteImport.update({
-  id: '/api/openrouter-retry-codes',
-  path: '/api/openrouter-retry-codes',
+const ApiFileSourceWireRoute = ApiFileSourceWireRouteImport.update({
+  id: '/api/file-source-wire',
+  path: '/api/file-source-wire',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiOpenrouterReasoningWireRoute =
-  ApiOpenrouterReasoningWireRouteImport.update({
-    id: '/api/openrouter-reasoning-wire',
-    path: '/api/openrouter-reasoning-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiOpenrouterJsonObjectWireRoute =
-  ApiOpenrouterJsonObjectWireRouteImport.update({
-    id: '/api/openrouter-json-object-wire',
-    path: '/api/openrouter-json-object-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiOpenrouterCostRoute = ApiOpenrouterCostRouteImport.update({
-  id: '/api/openrouter-cost',
-  path: '/api/openrouter-cost',
+const ApiForeignChunkEventsRoute = ApiForeignChunkEventsRouteImport.update({
+  id: '/api/foreign-chunk-events',
+  path: '/api/foreign-chunk-events',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiOpenaiUsageDetailsRoute = ApiOpenaiUsageDetailsRouteImport.update({
-  id: '/api/openai-usage-details',
-  path: '/api/openai-usage-details',
+const ApiForeignClientToolRoute = ApiForeignClientToolRouteImport.update({
+  id: '/api/foreign-client-tool',
+  path: '/api/foreign-client-tool',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiOpenaiStrictToolNullWireRoute =
-  ApiOpenaiStrictToolNullWireRouteImport.update({
-    id: '/api/openai-strict-tool-null-wire',
-    path: '/api/openai-strict-tool-null-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiOpenaiShellSkillsWireRoute =
-  ApiOpenaiShellSkillsWireRouteImport.update({
-    id: '/api/openai-shell-skills-wire',
-    path: '/api/openai-shell-skills-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiOpenaiImage25ModelsRoute = ApiOpenaiImage25ModelsRouteImport.update({
-  id: '/api/openai-image-2-5-models',
-  path: '/api/openai-image-2-5-models',
+const ApiForeignInterruptRoute = ApiForeignInterruptRouteImport.update({
+  id: '/api/foreign-interrupt',
+  path: '/api/foreign-interrupt',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiOpenaiMalformedToolArgumentsRoute =
-  ApiOpenaiMalformedToolArgumentsRouteImport.update({
-    id: '/api/openai-malformed-tool-arguments',
-    path: '/api/openai-malformed-tool-arguments',
+const ApiGeminiImageGaModelsRoute = ApiGeminiImageGaModelsRouteImport.update({
+  id: '/api/gemini-image-ga-models',
+  path: '/api/gemini-image-ga-models',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiGeminiNativeImageWireRoute =
+  ApiGeminiNativeImageWireRouteImport.update({
+    id: '/api/gemini-native-image-wire',
+    path: '/api/gemini-native-image-wire',
     getParentRoute: () => rootRouteImport,
   } as any)
-const ApiOpenaiCompletedResponseTextRoute =
-  ApiOpenaiCompletedResponseTextRouteImport.update({
-    id: '/api/openai-completed-response-text',
-    path: '/api/openai-completed-response-text',
+const ApiGenerationPersistenceResumeRoute =
+  ApiGenerationPersistenceResumeRouteImport.update({
+    id: '/api/generation-persistence-resume',
+    path: '/api/generation-persistence-resume',
     getParentRoute: () => rootRouteImport,
   } as any)
-const ApiNonStreamingRunErrorRoute = ApiNonStreamingRunErrorRouteImport.update({
-  id: '/api/non-streaming-run-error',
-  path: '/api/non-streaming-run-error',
-  getParentRoute: () => rootRouteImport,
-} as any)
-const ApiMultimodalToolResultWireRoute =
-  ApiMultimodalToolResultWireRouteImport.update({
-    id: '/api/multimodal-tool-result-wire',
-    path: '/api/multimodal-tool-result-wire',
+const ApiGenerationPersistenceServerRoute =
+  ApiGenerationPersistenceServerRouteImport.update({
+    id: '/api/generation-persistence-server',
+    path: '/api/generation-persistence-server',
     getParentRoute: () => rootRouteImport,
   } as any)
-const ApiMoonshotUsageDetailsRoute = ApiMoonshotUsageDetailsRouteImport.update({
-  id: '/api/moonshot-usage-details',
-  path: '/api/moonshot-usage-details',
+const ApiHarnessTestRoute = ApiHarnessTestRouteImport.update({
+  id: '/api/harness-test',
+  path: '/api/harness-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMistralStrictToolNullWireRoute =
-  ApiMistralStrictToolNullWireRouteImport.update({
-    id: '/api/mistral-strict-tool-null-wire',
-    path: '/api/mistral-strict-tool-null-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiMiddlewareTestRoute = ApiMiddlewareTestRouteImport.update({
-  id: '/api/middleware-test',
-  path: '/api/middleware-test',
+const ApiHarnessTurnOverridesRoute = ApiHarnessTurnOverridesRouteImport.update({
+  id: '/api/harness-turn-overrides',
+  path: '/api/harness-turn-overrides',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMidConversationChangesWireRoute =
-  ApiMidConversationChangesWireRouteImport.update({
-    id: '/api/mid-conversation-changes-wire',
-    path: '/api/mid-conversation-changes-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiMessageIdsRoute = ApiMessageIdsRouteImport.update({
-  id: '/api/message-ids',
-  path: '/api/message-ids',
+const ApiImageRoute = ApiImageRouteImport.update({
+  id: '/api/image',
+  path: '/api/image',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMessageHistoryPagingRoute = ApiMessageHistoryPagingRouteImport.update({
-  id: '/api/message-history-paging',
-  path: '/api/message-history-paging',
+const ApiInterruptsTestRoute = ApiInterruptsTestRouteImport.update({
+  id: '/api/interrupts-test',
+  path: '/api/interrupts-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMcpTypedTestRoute = ApiMcpTypedTestRouteImport.update({
-  id: '/api/mcp-typed-test',
-  path: '/api/mcp-typed-test',
+const ApiJoinRunClientToolRoute = ApiJoinRunClientToolRouteImport.update({
+  id: '/api/join-run-client-tool',
+  path: '/api/join-run-client-tool',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMcpTypedServerRoute = ApiMcpTypedServerRouteImport.update({
-  id: '/api/mcp-typed-server',
-  path: '/api/mcp-typed-server',
+const ApiLazyToolsWireRoute = ApiLazyToolsWireRouteImport.update({
+  id: '/api/lazy-tools-wire',
+  path: '/api/lazy-tools-wire',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMcpToolOptionsWireRoute = ApiMcpToolOptionsWireRouteImport.update({
-  id: '/api/mcp-tool-options-wire',
-  path: '/api/mcp-tool-options-wire',
+const ApiMaxToolCallsWireRoute = ApiMaxToolCallsWireRouteImport.update({
+  id: '/api/max-tool-calls-wire',
+  path: '/api/max-tool-calls-wire',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMcpTestRoute = ApiMcpTestRouteImport.update({
-  id: '/api/mcp-test',
-  path: '/api/mcp-test',
+const ApiMcpAppsCallRoute = ApiMcpAppsCallRouteImport.update({
+  id: '/api/mcp-apps-call',
+  path: '/api/mcp-apps-call',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMcpTaskErrorsRoute = ApiMcpTaskErrorsRouteImport.update({
-  id: '/api/mcp-task-errors',
-  path: '/api/mcp-task-errors',
+const ApiMcpAppsChatRoute = ApiMcpAppsChatRouteImport.update({
+  id: '/api/mcp-apps-chat',
+  path: '/api/mcp-apps-chat',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMcpStatusTestRoute = ApiMcpStatusTestRouteImport.update({
-  id: '/api/mcp-status-test',
-  path: '/api/mcp-status-test',
+const ApiMcpAppsServerRoute = ApiMcpAppsServerRouteImport.update({
+  id: '/api/mcp-apps-server',
+  path: '/api/mcp-apps-server',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMcpServerRoute = ApiMcpServerRouteImport.update({
-  id: '/api/mcp-server',
-  path: '/api/mcp-server',
+const ApiMcpInputServerRoute = ApiMcpInputServerRouteImport.update({
+  id: '/api/mcp-input-server',
+  path: '/api/mcp-input-server',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMcpPolicyTestRoute = ApiMcpPolicyTestRouteImport.update({
-  id: '/api/mcp-policy-test',
-  path: '/api/mcp-policy-test',
+const ApiMcpInputTestRoute = ApiMcpInputTestRouteImport.update({
+  id: '/api/mcp-input-test',
+  path: '/api/mcp-input-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMcpNoTasksServerRoute = ApiMcpNoTasksServerRouteImport.update({
-  id: '/api/mcp-no-tasks-server',
-  path: '/api/mcp-no-tasks-server',
+const ApiMcpLifecycleTestRoute = ApiMcpLifecycleTestRouteImport.update({
+  id: '/api/mcp-lifecycle-test',
+  path: '/api/mcp-lifecycle-test',
   getParentRoute: () => rootRouteImport,
 } as any)
 const ApiMcpManagedTestRoute = ApiMcpManagedTestRouteImport.update({
@@ -749,260 +594,338 @@ const ApiMcpManagedTestRoute = ApiMcpManagedTestRouteImport.update({
   path: '/api/mcp-managed-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMcpLifecycleTestRoute = ApiMcpLifecycleTestRouteImport.update({
-  id: '/api/mcp-lifecycle-test',
-  path: '/api/mcp-lifecycle-test',
+const ApiMcpNoTasksServerRoute = ApiMcpNoTasksServerRouteImport.update({
+  id: '/api/mcp-no-tasks-server',
+  path: '/api/mcp-no-tasks-server',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMcpInputTestRoute = ApiMcpInputTestRouteImport.update({
-  id: '/api/mcp-input-test',
-  path: '/api/mcp-input-test',
+const ApiMcpPolicyTestRoute = ApiMcpPolicyTestRouteImport.update({
+  id: '/api/mcp-policy-test',
+  path: '/api/mcp-policy-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMcpInputServerRoute = ApiMcpInputServerRouteImport.update({
-  id: '/api/mcp-input-server',
-  path: '/api/mcp-input-server',
+const ApiMcpServerRoute = ApiMcpServerRouteImport.update({
+  id: '/api/mcp-server',
+  path: '/api/mcp-server',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMcpAppsServerRoute = ApiMcpAppsServerRouteImport.update({
-  id: '/api/mcp-apps-server',
-  path: '/api/mcp-apps-server',
+const ApiMcpStatusTestRoute = ApiMcpStatusTestRouteImport.update({
+  id: '/api/mcp-status-test',
+  path: '/api/mcp-status-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMcpAppsChatRoute = ApiMcpAppsChatRouteImport.update({
-  id: '/api/mcp-apps-chat',
-  path: '/api/mcp-apps-chat',
+const ApiMcpTaskErrorsRoute = ApiMcpTaskErrorsRouteImport.update({
+  id: '/api/mcp-task-errors',
+  path: '/api/mcp-task-errors',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMcpAppsCallRoute = ApiMcpAppsCallRouteImport.update({
-  id: '/api/mcp-apps-call',
-  path: '/api/mcp-apps-call',
+const ApiMcpTestRoute = ApiMcpTestRouteImport.update({
+  id: '/api/mcp-test',
+  path: '/api/mcp-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiMaxToolCallsWireRoute = ApiMaxToolCallsWireRouteImport.update({
-  id: '/api/max-tool-calls-wire',
-  path: '/api/max-tool-calls-wire',
+const ApiMcpToolOptionsWireRoute = ApiMcpToolOptionsWireRouteImport.update({
+  id: '/api/mcp-tool-options-wire',
+  path: '/api/mcp-tool-options-wire',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiLazyToolsWireRoute = ApiLazyToolsWireRouteImport.update({
-  id: '/api/lazy-tools-wire',
-  path: '/api/lazy-tools-wire',
+const ApiMcpTypedServerRoute = ApiMcpTypedServerRouteImport.update({
+  id: '/api/mcp-typed-server',
+  path: '/api/mcp-typed-server',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiJoinRunClientToolRoute = ApiJoinRunClientToolRouteImport.update({
-  id: '/api/join-run-client-tool',
-  path: '/api/join-run-client-tool',
+const ApiMcpTypedTestRoute = ApiMcpTypedTestRouteImport.update({
+  id: '/api/mcp-typed-test',
+  path: '/api/mcp-typed-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiInterruptsTestRoute = ApiInterruptsTestRouteImport.update({
-  id: '/api/interrupts-test',
-  path: '/api/interrupts-test',
+const ApiMessageHistoryPagingRoute = ApiMessageHistoryPagingRouteImport.update({
+  id: '/api/message-history-paging',
+  path: '/api/message-history-paging',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiImageRoute = ApiImageRouteImport.update({
-  id: '/api/image',
-  path: '/api/image',
+const ApiMessageIdsRoute = ApiMessageIdsRouteImport.update({
+  id: '/api/message-ids',
+  path: '/api/message-ids',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiHarnessTurnOverridesRoute = ApiHarnessTurnOverridesRouteImport.update({
-  id: '/api/harness-turn-overrides',
-  path: '/api/harness-turn-overrides',
+const ApiMidConversationChangesWireRoute =
+  ApiMidConversationChangesWireRouteImport.update({
+    id: '/api/mid-conversation-changes-wire',
+    path: '/api/mid-conversation-changes-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiMiddlewareTestRoute = ApiMiddlewareTestRouteImport.update({
+  id: '/api/middleware-test',
+  path: '/api/middleware-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiHarnessTestRoute = ApiHarnessTestRouteImport.update({
-  id: '/api/harness-test',
-  path: '/api/harness-test',
+const ApiMistralStrictToolNullWireRoute =
+  ApiMistralStrictToolNullWireRouteImport.update({
+    id: '/api/mistral-strict-tool-null-wire',
+    path: '/api/mistral-strict-tool-null-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiMoonshotUsageDetailsRoute = ApiMoonshotUsageDetailsRouteImport.update({
+  id: '/api/moonshot-usage-details',
+  path: '/api/moonshot-usage-details',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiGenerationPersistenceServerRoute =
-  ApiGenerationPersistenceServerRouteImport.update({
-    id: '/api/generation-persistence-server',
-    path: '/api/generation-persistence-server',
+const ApiMultimodalToolResultWireRoute =
+  ApiMultimodalToolResultWireRouteImport.update({
+    id: '/api/multimodal-tool-result-wire',
+    path: '/api/multimodal-tool-result-wire',
     getParentRoute: () => rootRouteImport,
   } as any)
-const ApiGenerationPersistenceResumeRoute =
-  ApiGenerationPersistenceResumeRouteImport.update({
-    id: '/api/generation-persistence-resume',
-    path: '/api/generation-persistence-resume',
+const ApiNonStreamingRunErrorRoute = ApiNonStreamingRunErrorRouteImport.update({
+  id: '/api/non-streaming-run-error',
+  path: '/api/non-streaming-run-error',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiOpenaiCompletedResponseTextRoute =
+  ApiOpenaiCompletedResponseTextRouteImport.update({
+    id: '/api/openai-completed-response-text',
+    path: '/api/openai-completed-response-text',
     getParentRoute: () => rootRouteImport,
   } as any)
-const ApiGeminiNativeImageWireRoute =
-  ApiGeminiNativeImageWireRouteImport.update({
-    id: '/api/gemini-native-image-wire',
-    path: '/api/gemini-native-image-wire',
+const ApiOpenaiImage25ModelsRoute = ApiOpenaiImage25ModelsRouteImport.update({
+  id: '/api/openai-image-2-5-models',
+  path: '/api/openai-image-2-5-models',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiOpenaiMalformedToolArgumentsRoute =
+  ApiOpenaiMalformedToolArgumentsRouteImport.update({
+    id: '/api/openai-malformed-tool-arguments',
+    path: '/api/openai-malformed-tool-arguments',
     getParentRoute: () => rootRouteImport,
   } as any)
-const ApiGeminiImageGaModelsRoute = ApiGeminiImageGaModelsRouteImport.update({
-  id: '/api/gemini-image-ga-models',
-  path: '/api/gemini-image-ga-models',
+const ApiOpenaiShellSkillsWireRoute =
+  ApiOpenaiShellSkillsWireRouteImport.update({
+    id: '/api/openai-shell-skills-wire',
+    path: '/api/openai-shell-skills-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiOpenaiStrictToolNullWireRoute =
+  ApiOpenaiStrictToolNullWireRouteImport.update({
+    id: '/api/openai-strict-tool-null-wire',
+    path: '/api/openai-strict-tool-null-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiOpenaiUsageDetailsRoute = ApiOpenaiUsageDetailsRouteImport.update({
+  id: '/api/openai-usage-details',
+  path: '/api/openai-usage-details',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiForeignInterruptRoute = ApiForeignInterruptRouteImport.update({
-  id: '/api/foreign-interrupt',
-  path: '/api/foreign-interrupt',
+const ApiOpenrouterCostRoute = ApiOpenrouterCostRouteImport.update({
+  id: '/api/openrouter-cost',
+  path: '/api/openrouter-cost',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiFileSourceWireRoute = ApiFileSourceWireRouteImport.update({
-  id: '/api/file-source-wire',
-  path: '/api/file-source-wire',
+const ApiOpenrouterJsonObjectWireRoute =
+  ApiOpenrouterJsonObjectWireRouteImport.update({
+    id: '/api/openrouter-json-object-wire',
+    path: '/api/openrouter-json-object-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiOpenrouterReasoningWireRoute =
+  ApiOpenrouterReasoningWireRouteImport.update({
+    id: '/api/openrouter-reasoning-wire',
+    path: '/api/openrouter-reasoning-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiOpenrouterRetryCodesRoute = ApiOpenrouterRetryCodesRouteImport.update({
+  id: '/api/openrouter-retry-codes',
+  path: '/api/openrouter-retry-codes',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiEmbeddingRoute = ApiEmbeddingRouteImport.update({
-  id: '/api/embedding',
-  path: '/api/embedding',
+const ApiOpenrouterStreamOptionsWireRoute =
+  ApiOpenrouterStreamOptionsWireRouteImport.update({
+    id: '/api/openrouter-stream-options-wire',
+    path: '/api/openrouter-stream-options-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiOpenrouterStrictToolOptionalsRoute =
+  ApiOpenrouterStrictToolOptionalsRouteImport.update({
+    id: '/api/openrouter-strict-tool-optionals',
+    path: '/api/openrouter-strict-tool-optionals',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiOpenrouterWebToolsWireRoute =
+  ApiOpenrouterWebToolsWireRouteImport.update({
+    id: '/api/openrouter-web-tools-wire',
+    path: '/api/openrouter-web-tools-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiOtelMediaRoute = ApiOtelMediaRouteImport.update({
+  id: '/api/otel-media',
+  path: '/api/otel-media',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiDurableTakeoverRoute = ApiDurableTakeoverRouteImport.update({
-  id: '/api/durable-takeover',
-  path: '/api/durable-takeover',
+const ApiOtelTranscriptionRoute = ApiOtelTranscriptionRouteImport.update({
+  id: '/api/otel-transcription',
+  path: '/api/otel-transcription',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiDurableDeliveryRoute = ApiDurableDeliveryRouteImport.update({
-  id: '/api/durable-delivery',
-  path: '/api/durable-delivery',
+const ApiOtelUsageRoute = ApiOtelUsageRouteImport.update({
+  id: '/api/otel-usage',
+  path: '/api/otel-usage',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiDevtoolsMemoryRoute = ApiDevtoolsMemoryRouteImport.update({
-  id: '/api/devtools-memory',
-  path: '/api/devtools-memory',
+const ApiPersistenceDurabilityRoute =
+  ApiPersistenceDurabilityRouteImport.update({
+    id: '/api/persistence-durability',
+    path: '/api/persistence-durability',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiPortableSkillsWireRoute = ApiPortableSkillsWireRouteImport.update({
+  id: '/api/portable-skills-wire',
+  path: '/api/portable-skills-wire',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiCompactionWireRoute = ApiCompactionWireRouteImport.update({
-  id: '/api/compaction-wire',
-  path: '/api/compaction-wire',
+const ApiPromptCacheWireRoute = ApiPromptCacheWireRouteImport.update({
+  id: '/api/prompt-cache-wire',
+  path: '/api/prompt-cache-wire',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiCompactionDurableWireRoute =
-  ApiCompactionDurableWireRouteImport.update({
-    id: '/api/compaction-durable-wire',
-    path: '/api/compaction-durable-wire',
+const ApiProviderSearchMetadataWireRoute =
+  ApiProviderSearchMetadataWireRouteImport.update({
+    id: '/api/provider-search-metadata-wire',
+    path: '/api/provider-search-metadata-wire',
     getParentRoute: () => rootRouteImport,
   } as any)
-const ApiCloudflareBindingWireRoute =
-  ApiCloudflareBindingWireRouteImport.update({
-    id: '/api/cloudflare-binding-wire',
-    path: '/api/cloudflare-binding-wire',
+const ApiProviderToolDispatchWireRoute =
+  ApiProviderToolDispatchWireRouteImport.update({
+    id: '/api/provider-tool-dispatch-wire',
+    path: '/api/provider-tool-dispatch-wire',
     getParentRoute: () => rootRouteImport,
   } as any)
-const ApiChatRoute = ApiChatRouteImport.update({
-  id: '/api/chat',
-  path: '/api/chat',
+const ApiSandboxDurabilityRoute = ApiSandboxDurabilityRouteImport.update({
+  id: '/api/sandbox-durability',
+  path: '/api/sandbox-durability',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiByteplusSeedance1080pWireRoute =
-  ApiByteplusSeedance1080pWireRouteImport.update({
-    id: '/api/byteplus-seedance-1080p-wire',
-    path: '/api/byteplus-seedance-1080p-wire',
+const ApiSandboxFilePersistenceRoute =
+  ApiSandboxFilePersistenceRouteImport.update({
+    id: '/api/sandbox-file-persistence',
+    path: '/api/sandbox-file-persistence',
     getParentRoute: () => rootRouteImport,
   } as any)
-const ApiByokChatRoute = ApiByokChatRouteImport.update({
-  id: '/api/byok-chat',
-  path: '/api/byok-chat',
+const ApiSandboxToolHistoryRoute = ApiSandboxToolHistoryRouteImport.update({
+  id: '/api/sandbox-tool-history',
+  path: '/api/sandbox-tool-history',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiBedrockConverseCacheRoute = ApiBedrockConverseCacheRouteImport.update({
-  id: '/api/bedrock-converse-cache',
-  path: '/api/bedrock-converse-cache',
+const ApiStructuredOutputLengthWireRoute =
+  ApiStructuredOutputLengthWireRouteImport.update({
+    id: '/api/structured-output-length-wire',
+    path: '/api/structured-output-length-wire',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const ApiSubagentsTestRoute = ApiSubagentsTestRouteImport.update({
+  id: '/api/subagents-test',
+  path: '/api/subagents-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiAudioRoute = ApiAudioRouteImport.update({
-  id: '/api/audio',
-  path: '/api/audio',
+const ApiSummarizeRoute = ApiSummarizeRouteImport.update({
+  id: '/api/summarize',
+  path: '/api/summarize',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiArktypeToolWireRoute = ApiArktypeToolWireRouteImport.update({
-  id: '/api/arktype-tool-wire',
-  path: '/api/arktype-tool-wire',
+const ApiTextFirstToolWireRoute = ApiTextFirstToolWireRouteImport.update({
+  id: '/api/text-first-tool-wire',
+  path: '/api/text-first-tool-wire',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiAnthropicThinkingOrderWireRoute =
-  ApiAnthropicThinkingOrderWireRouteImport.update({
-    id: '/api/anthropic-thinking-order-wire',
-    path: '/api/anthropic-thinking-order-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiAnthropicStructuredUsageRoute =
-  ApiAnthropicStructuredUsageRouteImport.update({
-    id: '/api/anthropic-structured-usage',
-    path: '/api/anthropic-structured-usage',
+const ApiToolCallLifecycleWireRoute =
+  ApiToolCallLifecycleWireRouteImport.update({
+    id: '/api/tool-call-lifecycle-wire',
+    path: '/api/tool-call-lifecycle-wire',
     getParentRoute: () => rootRouteImport,
   } as any)
-const ApiAnthropicSkillsWireRoute = ApiAnthropicSkillsWireRouteImport.update({
-  id: '/api/anthropic-skills-wire',
-  path: '/api/anthropic-skills-wire',
+const ApiToolChoiceWireRoute = ApiToolChoiceWireRouteImport.update({
+  id: '/api/tool-choice-wire',
+  path: '/api/tool-choice-wire',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiAnthropicRedactedThinkingWireRoute =
-  ApiAnthropicRedactedThinkingWireRouteImport.update({
-    id: '/api/anthropic-redacted-thinking-wire',
-    path: '/api/anthropic-redacted-thinking-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiAnthropicOpus5CombinedWireRoute =
-  ApiAnthropicOpus5CombinedWireRouteImport.update({
-    id: '/api/anthropic-opus-5-combined-wire',
-    path: '/api/anthropic-opus-5-combined-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiAnthropicMultiTurnStructuredWireRoute =
-  ApiAnthropicMultiTurnStructuredWireRouteImport.update({
-    id: '/api/anthropic-multi-turn-structured-wire',
-    path: '/api/anthropic-multi-turn-structured-wire',
-    getParentRoute: () => rootRouteImport,
-  } as any)
-const ApiAnthropicBugTestRoute = ApiAnthropicBugTestRouteImport.update({
-  id: '/api/anthropic-bug-test',
-  path: '/api/anthropic-bug-test',
+const ApiToolFirstTextWireRoute = ApiToolFirstTextWireRouteImport.update({
+  id: '/api/tool-first-text-wire',
+  path: '/api/tool-first-text-wire',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ProviderFeatureRoute = ProviderFeatureRouteImport.update({
-  id: '/$provider/$feature',
-  path: '/$provider/$feature',
+const ApiToolsTestRoute = ApiToolsTestRouteImport.update({
+  id: '/api/tools-test',
+  path: '/api/tools-test',
   getParentRoute: () => rootRouteImport,
 } as any)
-const ApiVideoStreamRoute = ApiVideoStreamRouteImport.update({
+const ApiTranscriptionRoute = ApiTranscriptionRouteImport.update({
+  id: '/api/transcription',
+  path: '/api/transcription',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiTtsRoute = ApiTtsRouteImport.update({
+  id: '/api/tts',
+  path: '/api/tts',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiVideoRoute = ApiVideoRouteImport.update({
+  id: '/api/video',
+  path: '/api/video',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiVideoLiveRoute = ApiVideoLiveRouteImport.update({
+  id: '/api/video-live',
+  path: '/api/video-live',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiVoiceRoute = ApiVoiceRouteImport.update({
+  id: '/api/voice',
+  path: '/api/voice',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiWebMcpPageToolsRoute = ApiWebMcpPageToolsRouteImport.update({
+  id: '/api/web-mcp-page-tools',
+  path: '/api/web-mcp-page-tools',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiWorldRoute = ApiWorldRouteImport.update({
+  id: '/api/world',
+  path: '/api/world',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiAudioStreamRoute = ApiAudioStreamRouteImport.update({
   id: '/stream',
   path: '/stream',
-  getParentRoute: () => ApiVideoRoute,
+  getParentRoute: () => ApiAudioRoute,
 } as any)
-const ApiTtsStreamRoute = ApiTtsStreamRouteImport.update({
+const ApiHarnessProtocolSplatRoute = ApiHarnessProtocolSplatRouteImport.update({
+  id: '/api/harness-protocol/$',
+  path: '/api/harness-protocol/$',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiImageStreamRoute = ApiImageStreamRouteImport.update({
   id: '/stream',
   path: '/stream',
-  getParentRoute: () => ApiTtsRoute,
+  getParentRoute: () => ApiImageRoute,
 } as any)
 const ApiTranscriptionStreamRoute = ApiTranscriptionStreamRouteImport.update({
   id: '/stream',
   path: '/stream',
   getParentRoute: () => ApiTranscriptionRoute,
 } as any)
-const ApiImageStreamRoute = ApiImageStreamRouteImport.update({
+const ApiTtsStreamRoute = ApiTtsStreamRouteImport.update({
   id: '/stream',
   path: '/stream',
-  getParentRoute: () => ApiImageRoute,
-} as any)
-const ApiHarnessProtocolSplatRoute = ApiHarnessProtocolSplatRouteImport.update({
-  id: '/api/harness-protocol/$',
-  path: '/api/harness-protocol/$',
-  getParentRoute: () => rootRouteImport,
+  getParentRoute: () => ApiTtsRoute,
 } as any)
-const ApiAudioStreamRoute = ApiAudioStreamRouteImport.update({
+const ApiVideoStreamRoute = ApiVideoStreamRouteImport.update({
   id: '/stream',
   path: '/stream',
-  getParentRoute: () => ApiAudioRoute,
+  getParentRoute: () => ApiVideoRoute,
 } as any)
 
 export interface FileRoutesByFullPath {
-  '/api/adapter-config-reasoning-wire': typeof ApiAdapterConfigReasoningWireRoute
-  '/api/activity-test': typeof ApiActivityTestRoute
-  '/activity-test': typeof ActivityTestRoute
-  '/api/foreign-client-tool': typeof ApiForeignClientToolRoute
-  '/api/foreign-chunk-events': typeof ApiForeignChunkEventsRoute
-  '/api/anthropic-truncated-tool-input-wire': typeof ApiAnthropicTruncatedToolInputWireRoute
-  '/api/anthropic-sonnet-5-5-wire': typeof ApiAnthropicSonnet55WireRoute
-  '/api/anthropic-max-tokens-usage': typeof ApiAnthropicMaxTokensUsageRoute
-  '/foreign-client-tool': typeof ForeignClientToolRoute
-  '/foreign-chunk-events': typeof ForeignChunkEventsRoute
   '/': typeof IndexRoute
+  '/activity-test': typeof ActivityTestRoute
   '/byok': typeof ByokRoute
   '/chat-client-default-bridge': typeof ChatClientDefaultBridgeRoute
   '/chat-client-stream-processing': typeof ChatClientStreamProcessingRoute
@@ -1015,6 +938,8 @@ export interface FileRoutesByFullPath {
   '/devtools-structured': typeof DevtoolsStructuredRoute
   '/devtools-subagents': typeof DevtoolsSubagentsRoute
   '/devtools-tools': typeof DevtoolsToolsRoute
+  '/foreign-chunk-events': typeof ForeignChunkEventsRoute
+  '/foreign-client-tool': typeof ForeignClientToolRoute
   '/foreign-interrupt': typeof ForeignInterruptRoute
   '/generation-persistence-resume': typeof GenerationPersistenceResumeRoute
   '/generation-persistence-server': typeof GenerationPersistenceServerRoute
@@ -1035,13 +960,18 @@ export interface FileRoutesByFullPath {
   '/web-mcp-tools': typeof WebMcpToolsRoute
   '/websocket-adapter': typeof WebsocketAdapterRoute
   '/$provider/$feature': typeof ProviderFeatureRoute
+  '/api/activity-test': typeof ApiActivityTestRoute
+  '/api/adapter-config-reasoning-wire': typeof ApiAdapterConfigReasoningWireRoute
   '/api/anthropic-bug-test': typeof ApiAnthropicBugTestRoute
+  '/api/anthropic-max-tokens-usage': typeof ApiAnthropicMaxTokensUsageRoute
   '/api/anthropic-multi-turn-structured-wire': typeof ApiAnthropicMultiTurnStructuredWireRoute
   '/api/anthropic-opus-5-combined-wire': typeof ApiAnthropicOpus5CombinedWireRoute
   '/api/anthropic-redacted-thinking-wire': typeof ApiAnthropicRedactedThinkingWireRoute
   '/api/anthropic-skills-wire': typeof ApiAnthropicSkillsWireRoute
+  '/api/anthropic-sonnet-5-5-wire': typeof ApiAnthropicSonnet55WireRoute
   '/api/anthropic-structured-usage': typeof ApiAnthropicStructuredUsageRoute
   '/api/anthropic-thinking-order-wire': typeof ApiAnthropicThinkingOrderWireRoute
+  '/api/anthropic-truncated-tool-input-wire': typeof ApiAnthropicTruncatedToolInputWireRoute
   '/api/arktype-tool-wire': typeof ApiArktypeToolWireRoute
   '/api/audio': typeof ApiAudioRouteWithChildren
   '/api/bedrock-converse-cache': typeof ApiBedrockConverseCacheRoute
@@ -1056,6 +986,8 @@ export interface FileRoutesByFullPath {
   '/api/durable-takeover': typeof ApiDurableTakeoverRoute
   '/api/embedding': typeof ApiEmbeddingRoute
   '/api/file-source-wire': typeof ApiFileSourceWireRoute
+  '/api/foreign-chunk-events': typeof ApiForeignChunkEventsRoute
+  '/api/foreign-client-tool': typeof ApiForeignClientToolRoute
   '/api/foreign-interrupt': typeof ApiForeignInterruptRoute
   '/api/gemini-image-ga-models': typeof ApiGeminiImageGaModelsRoute
   '/api/gemini-native-image-wire': typeof ApiGeminiNativeImageWireRoute
@@ -1121,6 +1053,7 @@ export interface FileRoutesByFullPath {
   '/api/summarize': typeof ApiSummarizeRoute
   '/api/text-first-tool-wire': typeof ApiTextFirstToolWireRoute
   '/api/tool-call-lifecycle-wire': typeof ApiToolCallLifecycleWireRoute
+  '/api/tool-choice-wire': typeof ApiToolChoiceWireRoute
   '/api/tool-first-text-wire': typeof ApiToolFirstTextWireRoute
   '/api/tools-test': typeof ApiToolsTestRoute
   '/api/transcription': typeof ApiTranscriptionRouteWithChildren
@@ -1139,17 +1072,8 @@ export interface FileRoutesByFullPath {
   '/api/video/stream': typeof ApiVideoStreamRoute
 }
 export interface FileRoutesByTo {
-  '/api/adapter-config-reasoning-wire': typeof ApiAdapterConfigReasoningWireRoute
-  '/api/activity-test': typeof ApiActivityTestRoute
-  '/activity-test': typeof ActivityTestRoute
-  '/api/foreign-client-tool': typeof ApiForeignClientToolRoute
-  '/api/foreign-chunk-events': typeof ApiForeignChunkEventsRoute
-  '/api/anthropic-truncated-tool-input-wire': typeof ApiAnthropicTruncatedToolInputWireRoute
-  '/api/anthropic-sonnet-5-5-wire': typeof ApiAnthropicSonnet55WireRoute
-  '/api/anthropic-max-tokens-usage': typeof ApiAnthropicMaxTokensUsageRoute
-  '/foreign-client-tool': typeof ForeignClientToolRoute
-  '/foreign-chunk-events': typeof ForeignChunkEventsRoute
   '/': typeof IndexRoute
+  '/activity-test': typeof ActivityTestRoute
   '/byok': typeof ByokRoute
   '/chat-client-default-bridge': typeof ChatClientDefaultBridgeRoute
   '/chat-client-stream-processing': typeof ChatClientStreamProcessingRoute
@@ -1162,6 +1086,8 @@ export interface FileRoutesByTo {
   '/devtools-structured': typeof DevtoolsStructuredRoute
   '/devtools-subagents': typeof DevtoolsSubagentsRoute
   '/devtools-tools': typeof DevtoolsToolsRoute
+  '/foreign-chunk-events': typeof ForeignChunkEventsRoute
+  '/foreign-client-tool': typeof ForeignClientToolRoute
   '/foreign-interrupt': typeof ForeignInterruptRoute
   '/generation-persistence-resume': typeof GenerationPersistenceResumeRoute
   '/generation-persistence-server': typeof GenerationPersistenceServerRoute
@@ -1182,13 +1108,18 @@ export interface FileRoutesByTo {
   '/web-mcp-tools': typeof WebMcpToolsRoute
   '/websocket-adapter': typeof WebsocketAdapterRoute
   '/$provider/$feature': typeof ProviderFeatureRoute
+  '/api/activity-test': typeof ApiActivityTestRoute
+  '/api/adapter-config-reasoning-wire': typeof ApiAdapterConfigReasoningWireRoute
   '/api/anthropic-bug-test': typeof ApiAnthropicBugTestRoute
+  '/api/anthropic-max-tokens-usage': typeof ApiAnthropicMaxTokensUsageRoute
   '/api/anthropic-multi-turn-structured-wire': typeof ApiAnthropicMultiTurnStructuredWireRoute
   '/api/anthropic-opus-5-combined-wire': typeof ApiAnthropicOpus5CombinedWireRoute
   '/api/anthropic-redacted-thinking-wire': typeof ApiAnthropicRedactedThinkingWireRoute
   '/api/anthropic-skills-wire': typeof ApiAnthropicSkillsWireRoute
+  '/api/anthropic-sonnet-5-5-wire': typeof ApiAnthropicSonnet55WireRoute
   '/api/anthropic-structured-usage': typeof ApiAnthropicStructuredUsageRoute
   '/api/anthropic-thinking-order-wire': typeof ApiAnthropicThinkingOrderWireRoute
+  '/api/anthropic-truncated-tool-input-wire': typeof ApiAnthropicTruncatedToolInputWireRoute
   '/api/arktype-tool-wire': typeof ApiArktypeToolWireRoute
   '/api/audio': typeof ApiAudioRouteWithChildren
   '/api/bedrock-converse-cache': typeof ApiBedrockConverseCacheRoute
@@ -1203,6 +1134,8 @@ export interface FileRoutesByTo {
   '/api/durable-takeover': typeof ApiDurableTakeoverRoute
   '/api/embedding': typeof ApiEmbeddingRoute
   '/api/file-source-wire': typeof ApiFileSourceWireRoute
+  '/api/foreign-chunk-events': typeof ApiForeignChunkEventsRoute
+  '/api/foreign-client-tool': typeof ApiForeignClientToolRoute
   '/api/foreign-interrupt': typeof ApiForeignInterruptRoute
   '/api/gemini-image-ga-models': typeof ApiGeminiImageGaModelsRoute
   '/api/gemini-native-image-wire': typeof ApiGeminiNativeImageWireRoute
@@ -1268,6 +1201,7 @@ export interface FileRoutesByTo {
   '/api/summarize': typeof ApiSummarizeRoute
   '/api/text-first-tool-wire': typeof ApiTextFirstToolWireRoute
   '/api/tool-call-lifecycle-wire': typeof ApiToolCallLifecycleWireRoute
+  '/api/tool-choice-wire': typeof ApiToolChoiceWireRoute
   '/api/tool-first-text-wire': typeof ApiToolFirstTextWireRoute
   '/api/tools-test': typeof ApiToolsTestRoute
   '/api/transcription': typeof ApiTranscriptionRouteWithChildren
@@ -1284,20 +1218,11 @@ export interface FileRoutesByTo {
   '/api/transcription/stream': typeof ApiTranscriptionStreamRoute
   '/api/tts/stream': typeof ApiTtsStreamRoute
   '/api/video/stream': typeof ApiVideoStreamRoute
-}
-export interface FileRoutesById {
-  '/api/adapter-config-reasoning-wire': typeof ApiAdapterConfigReasoningWireRoute
-  '/api/activity-test': typeof ApiActivityTestRoute
-  '/activity-test': typeof ActivityTestRoute
-  '/api/foreign-client-tool': typeof ApiForeignClientToolRoute
-  '/api/foreign-chunk-events': typeof ApiForeignChunkEventsRoute
-  '/api/anthropic-truncated-tool-input-wire': typeof ApiAnthropicTruncatedToolInputWireRoute
-  '/api/anthropic-sonnet-5-5-wire': typeof ApiAnthropicSonnet55WireRoute
-  '/api/anthropic-max-tokens-usage': typeof ApiAnthropicMaxTokensUsageRoute
-  '/foreign-client-tool': typeof ForeignClientToolRoute
-  '/foreign-chunk-events': typeof ForeignChunkEventsRoute
+}
+export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
+  '/activity-test': typeof ActivityTestRoute
   '/byok': typeof ByokRoute
   '/chat-client-default-bridge': typeof ChatClientDefaultBridgeRoute
   '/chat-client-stream-processing': typeof ChatClientStreamProcessingRoute
@@ -1310,6 +1235,8 @@ export interface FileRoutesById {
   '/devtools-structured': typeof DevtoolsStructuredRoute
   '/devtools-subagents': typeof DevtoolsSubagentsRoute
   '/devtools-tools': typeof DevtoolsToolsRoute
+  '/foreign-chunk-events': typeof ForeignChunkEventsRoute
+  '/foreign-client-tool': typeof ForeignClientToolRoute
   '/foreign-interrupt': typeof ForeignInterruptRoute
   '/generation-persistence-resume': typeof GenerationPersistenceResumeRoute
   '/generation-persistence-server': typeof GenerationPersistenceServerRoute
@@ -1330,13 +1257,18 @@ export interface FileRoutesById {
   '/web-mcp-tools': typeof WebMcpToolsRoute
   '/websocket-adapter': typeof WebsocketAdapterRoute
   '/$provider/$feature': typeof ProviderFeatureRoute
+  '/api/activity-test': typeof ApiActivityTestRoute
+  '/api/adapter-config-reasoning-wire': typeof ApiAdapterConfigReasoningWireRoute
   '/api/anthropic-bug-test': typeof ApiAnthropicBugTestRoute
+  '/api/anthropic-max-tokens-usage': typeof ApiAnthropicMaxTokensUsageRoute
   '/api/anthropic-multi-turn-structured-wire': typeof ApiAnthropicMultiTurnStructuredWireRoute
   '/api/anthropic-opus-5-combined-wire': typeof ApiAnthropicOpus5CombinedWireRoute
   '/api/anthropic-redacted-thinking-wire': typeof ApiAnthropicRedactedThinkingWireRoute
   '/api/anthropic-skills-wire': typeof ApiAnthropicSkillsWireRoute
+  '/api/anthropic-sonnet-5-5-wire': typeof ApiAnthropicSonnet55WireRoute
   '/api/anthropic-structured-usage': typeof ApiAnthropicStructuredUsageRoute
   '/api/anthropic-thinking-order-wire': typeof ApiAnthropicThinkingOrderWireRoute
+  '/api/anthropic-truncated-tool-input-wire': typeof ApiAnthropicTruncatedToolInputWireRoute
   '/api/arktype-tool-wire': typeof ApiArktypeToolWireRoute
   '/api/audio': typeof ApiAudioRouteWithChildren
   '/api/bedrock-converse-cache': typeof ApiBedrockConverseCacheRoute
@@ -1351,6 +1283,8 @@ export interface FileRoutesById {
   '/api/durable-takeover': typeof ApiDurableTakeoverRoute
   '/api/embedding': typeof ApiEmbeddingRoute
   '/api/file-source-wire': typeof ApiFileSourceWireRoute
+  '/api/foreign-chunk-events': typeof ApiForeignChunkEventsRoute
+  '/api/foreign-client-tool': typeof ApiForeignClientToolRoute
   '/api/foreign-interrupt': typeof ApiForeignInterruptRoute
   '/api/gemini-image-ga-models': typeof ApiGeminiImageGaModelsRoute
   '/api/gemini-native-image-wire': typeof ApiGeminiNativeImageWireRoute
@@ -1416,6 +1350,7 @@ export interface FileRoutesById {
   '/api/summarize': typeof ApiSummarizeRoute
   '/api/text-first-tool-wire': typeof ApiTextFirstToolWireRoute
   '/api/tool-call-lifecycle-wire': typeof ApiToolCallLifecycleWireRoute
+  '/api/tool-choice-wire': typeof ApiToolChoiceWireRoute
   '/api/tool-first-text-wire': typeof ApiToolFirstTextWireRoute
   '/api/tools-test': typeof ApiToolsTestRoute
   '/api/transcription': typeof ApiTranscriptionRouteWithChildren
@@ -1436,17 +1371,8 @@ export interface FileRoutesById {
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
   fullPaths:
-    | '/api/adapter-config-reasoning-wire'
-    | '/api/activity-test'
-    | '/activity-test'
-    | '/api/foreign-client-tool'
-    | '/api/foreign-chunk-events'
-    | '/api/anthropic-truncated-tool-input-wire'
-    | '/api/anthropic-sonnet-5-5-wire'
-    | '/api/anthropic-max-tokens-usage'
-    | '/foreign-client-tool'
-    | '/foreign-chunk-events'
     | '/'
+    | '/activity-test'
     | '/byok'
     | '/chat-client-default-bridge'
     | '/chat-client-stream-processing'
@@ -1459,6 +1385,8 @@ export interface FileRouteTypes {
     | '/devtools-structured'
     | '/devtools-subagents'
     | '/devtools-tools'
+    | '/foreign-chunk-events'
+    | '/foreign-client-tool'
     | '/foreign-interrupt'
     | '/generation-persistence-resume'
     | '/generation-persistence-server'
@@ -1479,13 +1407,18 @@ export interface FileRouteTypes {
     | '/web-mcp-tools'
     | '/websocket-adapter'
     | '/$provider/$feature'
+    | '/api/activity-test'
+    | '/api/adapter-config-reasoning-wire'
     | '/api/anthropic-bug-test'
+    | '/api/anthropic-max-tokens-usage'
     | '/api/anthropic-multi-turn-structured-wire'
     | '/api/anthropic-opus-5-combined-wire'
     | '/api/anthropic-redacted-thinking-wire'
     | '/api/anthropic-skills-wire'
+    | '/api/anthropic-sonnet-5-5-wire'
     | '/api/anthropic-structured-usage'
     | '/api/anthropic-thinking-order-wire'
+    | '/api/anthropic-truncated-tool-input-wire'
     | '/api/arktype-tool-wire'
     | '/api/audio'
     | '/api/bedrock-converse-cache'
@@ -1500,6 +1433,8 @@ export interface FileRouteTypes {
     | '/api/durable-takeover'
     | '/api/embedding'
     | '/api/file-source-wire'
+    | '/api/foreign-chunk-events'
+    | '/api/foreign-client-tool'
     | '/api/foreign-interrupt'
     | '/api/gemini-image-ga-models'
     | '/api/gemini-native-image-wire'
@@ -1565,6 +1500,7 @@ export interface FileRouteTypes {
     | '/api/summarize'
     | '/api/text-first-tool-wire'
     | '/api/tool-call-lifecycle-wire'
+    | '/api/tool-choice-wire'
     | '/api/tool-first-text-wire'
     | '/api/tools-test'
     | '/api/transcription'
@@ -1583,17 +1519,8 @@ export interface FileRouteTypes {
     | '/api/video/stream'
   fileRoutesByTo: FileRoutesByTo
   to:
-    | '/api/adapter-config-reasoning-wire'
-    | '/api/activity-test'
-    | '/activity-test'
-    | '/api/foreign-client-tool'
-    | '/api/foreign-chunk-events'
-    | '/api/anthropic-truncated-tool-input-wire'
-    | '/api/anthropic-sonnet-5-5-wire'
-    | '/api/anthropic-max-tokens-usage'
-    | '/foreign-client-tool'
-    | '/foreign-chunk-events'
     | '/'
+    | '/activity-test'
     | '/byok'
     | '/chat-client-default-bridge'
     | '/chat-client-stream-processing'
@@ -1606,6 +1533,8 @@ export interface FileRouteTypes {
     | '/devtools-structured'
     | '/devtools-subagents'
     | '/devtools-tools'
+    | '/foreign-chunk-events'
+    | '/foreign-client-tool'
     | '/foreign-interrupt'
     | '/generation-persistence-resume'
     | '/generation-persistence-server'
@@ -1626,13 +1555,18 @@ export interface FileRouteTypes {
     | '/web-mcp-tools'
     | '/websocket-adapter'
     | '/$provider/$feature'
+    | '/api/activity-test'
+    | '/api/adapter-config-reasoning-wire'
     | '/api/anthropic-bug-test'
+    | '/api/anthropic-max-tokens-usage'
     | '/api/anthropic-multi-turn-structured-wire'
     | '/api/anthropic-opus-5-combined-wire'
     | '/api/anthropic-redacted-thinking-wire'
     | '/api/anthropic-skills-wire'
+    | '/api/anthropic-sonnet-5-5-wire'
     | '/api/anthropic-structured-usage'
     | '/api/anthropic-thinking-order-wire'
+    | '/api/anthropic-truncated-tool-input-wire'
     | '/api/arktype-tool-wire'
     | '/api/audio'
     | '/api/bedrock-converse-cache'
@@ -1647,6 +1581,8 @@ export interface FileRouteTypes {
     | '/api/durable-takeover'
     | '/api/embedding'
     | '/api/file-source-wire'
+    | '/api/foreign-chunk-events'
+    | '/api/foreign-client-tool'
     | '/api/foreign-interrupt'
     | '/api/gemini-image-ga-models'
     | '/api/gemini-native-image-wire'
@@ -1712,6 +1648,7 @@ export interface FileRouteTypes {
     | '/api/summarize'
     | '/api/text-first-tool-wire'
     | '/api/tool-call-lifecycle-wire'
+    | '/api/tool-choice-wire'
     | '/api/tool-first-text-wire'
     | '/api/tools-test'
     | '/api/transcription'
@@ -1729,18 +1666,9 @@ export interface FileRouteTypes {
     | '/api/tts/stream'
     | '/api/video/stream'
   id:
-    | '/api/adapter-config-reasoning-wire'
-    | '/api/activity-test'
-    | '/activity-test'
-    | '/api/foreign-client-tool'
-    | '/api/foreign-chunk-events'
-    | '/api/anthropic-truncated-tool-input-wire'
-    | '/api/anthropic-sonnet-5-5-wire'
-    | '/api/anthropic-max-tokens-usage'
-    | '/foreign-client-tool'
-    | '/foreign-chunk-events'
     | '__root__'
     | '/'
+    | '/activity-test'
     | '/byok'
     | '/chat-client-default-bridge'
     | '/chat-client-stream-processing'
@@ -1753,6 +1681,8 @@ export interface FileRouteTypes {
     | '/devtools-structured'
     | '/devtools-subagents'
     | '/devtools-tools'
+    | '/foreign-chunk-events'
+    | '/foreign-client-tool'
     | '/foreign-interrupt'
     | '/generation-persistence-resume'
     | '/generation-persistence-server'
@@ -1773,13 +1703,18 @@ export interface FileRouteTypes {
     | '/web-mcp-tools'
     | '/websocket-adapter'
     | '/$provider/$feature'
+    | '/api/activity-test'
+    | '/api/adapter-config-reasoning-wire'
     | '/api/anthropic-bug-test'
+    | '/api/anthropic-max-tokens-usage'
     | '/api/anthropic-multi-turn-structured-wire'
     | '/api/anthropic-opus-5-combined-wire'
     | '/api/anthropic-redacted-thinking-wire'
     | '/api/anthropic-skills-wire'
+    | '/api/anthropic-sonnet-5-5-wire'
     | '/api/anthropic-structured-usage'
     | '/api/anthropic-thinking-order-wire'
+    | '/api/anthropic-truncated-tool-input-wire'
     | '/api/arktype-tool-wire'
     | '/api/audio'
     | '/api/bedrock-converse-cache'
@@ -1794,6 +1729,8 @@ export interface FileRouteTypes {
     | '/api/durable-takeover'
     | '/api/embedding'
     | '/api/file-source-wire'
+    | '/api/foreign-chunk-events'
+    | '/api/foreign-client-tool'
     | '/api/foreign-interrupt'
     | '/api/gemini-image-ga-models'
     | '/api/gemini-native-image-wire'
@@ -1859,6 +1796,7 @@ export interface FileRouteTypes {
     | '/api/summarize'
     | '/api/text-first-tool-wire'
     | '/api/tool-call-lifecycle-wire'
+    | '/api/tool-choice-wire'
     | '/api/tool-first-text-wire'
     | '/api/tools-test'
     | '/api/transcription'
@@ -1878,17 +1816,8 @@ export interface FileRouteTypes {
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
-  ApiAdapterConfigReasoningWireRoute: typeof ApiAdapterConfigReasoningWireRoute
-  ApiActivityTestRoute: typeof ApiActivityTestRoute
-  ActivityTestRoute: typeof ActivityTestRoute
-  ApiForeignClientToolRoute: typeof ApiForeignClientToolRoute
-  ApiForeignChunkEventsRoute: typeof ApiForeignChunkEventsRoute
-  ApiAnthropicTruncatedToolInputWireRoute: typeof ApiAnthropicTruncatedToolInputWireRoute
-  ApiAnthropicSonnet55WireRoute: typeof ApiAnthropicSonnet55WireRoute
-  ApiAnthropicMaxTokensUsageRoute: typeof ApiAnthropicMaxTokensUsageRoute
-  ForeignClientToolRoute: typeof ForeignClientToolRoute
-  ForeignChunkEventsRoute: typeof ForeignChunkEventsRoute
   IndexRoute: typeof IndexRoute
+  ActivityTestRoute: typeof ActivityTestRoute
   ByokRoute: typeof ByokRoute
   ChatClientDefaultBridgeRoute: typeof ChatClientDefaultBridgeRoute
   ChatClientStreamProcessingRoute: typeof ChatClientStreamProcessingRoute
@@ -1901,6 +1830,8 @@ export interface RootRouteChildren {
   DevtoolsStructuredRoute: typeof DevtoolsStructuredRoute
   DevtoolsSubagentsRoute: typeof DevtoolsSubagentsRoute
   DevtoolsToolsRoute: typeof DevtoolsToolsRoute
+  ForeignChunkEventsRoute: typeof ForeignChunkEventsRoute
+  ForeignClientToolRoute: typeof ForeignClientToolRoute
   ForeignInterruptRoute: typeof ForeignInterruptRoute
   GenerationPersistenceResumeRoute: typeof GenerationPersistenceResumeRoute
   GenerationPersistenceServerRoute: typeof GenerationPersistenceServerRoute
@@ -1921,13 +1852,18 @@ export interface RootRouteChildren {
   WebMcpToolsRoute: typeof WebMcpToolsRoute
   WebsocketAdapterRoute: typeof WebsocketAdapterRoute
   ProviderFeatureRoute: typeof ProviderFeatureRoute
+  ApiActivityTestRoute: typeof ApiActivityTestRoute
+  ApiAdapterConfigReasoningWireRoute: typeof ApiAdapterConfigReasoningWireRoute
   ApiAnthropicBugTestRoute: typeof ApiAnthropicBugTestRoute
+  ApiAnthropicMaxTokensUsageRoute: typeof ApiAnthropicMaxTokensUsageRoute
   ApiAnthropicMultiTurnStructuredWireRoute: typeof ApiAnthropicMultiTurnStructuredWireRoute
   ApiAnthropicOpus5CombinedWireRoute: typeof ApiAnthropicOpus5CombinedWireRoute
   ApiAnthropicRedactedThinkingWireRoute: typeof ApiAnthropicRedactedThinkingWireRoute
   ApiAnthropicSkillsWireRoute: typeof ApiAnthropicSkillsWireRoute
+  ApiAnthropicSonnet55WireRoute: typeof ApiAnthropicSonnet55WireRoute
   ApiAnthropicStructuredUsageRoute: typeof ApiAnthropicStructuredUsageRoute
   ApiAnthropicThinkingOrderWireRoute: typeof ApiAnthropicThinkingOrderWireRoute
+  ApiAnthropicTruncatedToolInputWireRoute: typeof ApiAnthropicTruncatedToolInputWireRoute
   ApiArktypeToolWireRoute: typeof ApiArktypeToolWireRoute
   ApiAudioRoute: typeof ApiAudioRouteWithChildren
   ApiBedrockConverseCacheRoute: typeof ApiBedrockConverseCacheRoute
@@ -1942,6 +1878,8 @@ export interface RootRouteChildren {
   ApiDurableTakeoverRoute: typeof ApiDurableTakeoverRoute
   ApiEmbeddingRoute: typeof ApiEmbeddingRoute
   ApiFileSourceWireRoute: typeof ApiFileSourceWireRoute
+  ApiForeignChunkEventsRoute: typeof ApiForeignChunkEventsRoute
+  ApiForeignClientToolRoute: typeof ApiForeignClientToolRoute
   ApiForeignInterruptRoute: typeof ApiForeignInterruptRoute
   ApiGeminiImageGaModelsRoute: typeof ApiGeminiImageGaModelsRoute
   ApiGeminiNativeImageWireRoute: typeof ApiGeminiNativeImageWireRoute
@@ -2007,6 +1945,7 @@ export interface RootRouteChildren {
   ApiSummarizeRoute: typeof ApiSummarizeRoute
   ApiTextFirstToolWireRoute: typeof ApiTextFirstToolWireRoute
   ApiToolCallLifecycleWireRoute: typeof ApiToolCallLifecycleWireRoute
+  ApiToolChoiceWireRoute: typeof ApiToolChoiceWireRoute
   ApiToolFirstTextWireRoute: typeof ApiToolFirstTextWireRoute
   ApiToolsTestRoute: typeof ApiToolsTestRoute
   ApiTranscriptionRoute: typeof ApiTranscriptionRouteWithChildren
@@ -2022,18 +1961,11 @@ export interface RootRouteChildren {
 
 declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
-    '/api/adapter-config-reasoning-wire': {
-      id: '/api/adapter-config-reasoning-wire'
-      path: '/api/adapter-config-reasoning-wire'
-      fullPath: '/api/adapter-config-reasoning-wire'
-      preLoaderRoute: typeof ApiAdapterConfigReasoningWireRouteImport
-      parentRoute: typeof rootRouteImport
-    }
-    '/api/activity-test': {
-      id: '/api/activity-test'
-      path: '/api/activity-test'
-      fullPath: '/api/activity-test'
-      preLoaderRoute: typeof ApiActivityTestRouteImport
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
       parentRoute: typeof rootRouteImport
     }
     '/activity-test': {
@@ -2043,137 +1975,144 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ActivityTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/foreign-client-tool': {
-      id: '/api/foreign-client-tool'
-      path: '/api/foreign-client-tool'
-      fullPath: '/api/foreign-client-tool'
-      preLoaderRoute: typeof ApiForeignClientToolRouteImport
+    '/byok': {
+      id: '/byok'
+      path: '/byok'
+      fullPath: '/byok'
+      preLoaderRoute: typeof ByokRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/foreign-chunk-events': {
-      id: '/api/foreign-chunk-events'
-      path: '/api/foreign-chunk-events'
-      fullPath: '/api/foreign-chunk-events'
-      preLoaderRoute: typeof ApiForeignChunkEventsRouteImport
+    '/chat-client-default-bridge': {
+      id: '/chat-client-default-bridge'
+      path: '/chat-client-default-bridge'
+      fullPath: '/chat-client-default-bridge'
+      preLoaderRoute: typeof ChatClientDefaultBridgeRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/anthropic-truncated-tool-input-wire': {
-      id: '/api/anthropic-truncated-tool-input-wire'
-      path: '/api/anthropic-truncated-tool-input-wire'
-      fullPath: '/api/anthropic-truncated-tool-input-wire'
-      preLoaderRoute: typeof ApiAnthropicTruncatedToolInputWireRouteImport
+    '/chat-client-stream-processing': {
+      id: '/chat-client-stream-processing'
+      path: '/chat-client-stream-processing'
+      fullPath: '/chat-client-stream-processing'
+      preLoaderRoute: typeof ChatClientStreamProcessingRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/anthropic-sonnet-5-5-wire': {
-      id: '/api/anthropic-sonnet-5-5-wire'
-      path: '/api/anthropic-sonnet-5-5-wire'
-      fullPath: '/api/anthropic-sonnet-5-5-wire'
-      preLoaderRoute: typeof ApiAnthropicSonnet55WireRouteImport
+    '/client-mount-hydrate': {
+      id: '/client-mount-hydrate'
+      path: '/client-mount-hydrate'
+      fullPath: '/client-mount-hydrate'
+      preLoaderRoute: typeof ClientMountHydrateRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/anthropic-max-tokens-usage': {
-      id: '/api/anthropic-max-tokens-usage'
-      path: '/api/anthropic-max-tokens-usage'
-      fullPath: '/api/anthropic-max-tokens-usage'
-      preLoaderRoute: typeof ApiAnthropicMaxTokensUsageRouteImport
+    '/devtools-chat': {
+      id: '/devtools-chat'
+      path: '/devtools-chat'
+      fullPath: '/devtools-chat'
+      preLoaderRoute: typeof DevtoolsChatRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/foreign-client-tool': {
-      id: '/foreign-client-tool'
-      path: '/foreign-client-tool'
-      fullPath: '/foreign-client-tool'
-      preLoaderRoute: typeof ForeignClientToolRouteImport
+    '/devtools-generation-hooks': {
+      id: '/devtools-generation-hooks'
+      path: '/devtools-generation-hooks'
+      fullPath: '/devtools-generation-hooks'
+      preLoaderRoute: typeof DevtoolsGenerationHooksRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/foreign-chunk-events': {
-      id: '/foreign-chunk-events'
-      path: '/foreign-chunk-events'
-      fullPath: '/foreign-chunk-events'
-      preLoaderRoute: typeof ForeignChunkEventsRouteImport
+    '/devtools-memory': {
+      id: '/devtools-memory'
+      path: '/devtools-memory'
+      fullPath: '/devtools-memory'
+      preLoaderRoute: typeof DevtoolsMemoryRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/websocket-adapter': {
-      id: '/websocket-adapter'
-      path: '/websocket-adapter'
-      fullPath: '/websocket-adapter'
-      preLoaderRoute: typeof WebsocketAdapterRouteImport
+    '/devtools-route-a': {
+      id: '/devtools-route-a'
+      path: '/devtools-route-a'
+      fullPath: '/devtools-route-a'
+      preLoaderRoute: typeof DevtoolsRouteARouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/web-mcp-tools': {
-      id: '/web-mcp-tools'
-      path: '/web-mcp-tools'
-      fullPath: '/web-mcp-tools'
-      preLoaderRoute: typeof WebMcpToolsRouteImport
+    '/devtools-route-b': {
+      id: '/devtools-route-b'
+      path: '/devtools-route-b'
+      fullPath: '/devtools-route-b'
+      preLoaderRoute: typeof DevtoolsRouteBRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/web-mcp-page-tools': {
-      id: '/web-mcp-page-tools'
-      path: '/web-mcp-page-tools'
-      fullPath: '/web-mcp-page-tools'
-      preLoaderRoute: typeof WebMcpPageToolsRouteImport
+    '/devtools-structured': {
+      id: '/devtools-structured'
+      path: '/devtools-structured'
+      fullPath: '/devtools-structured'
+      preLoaderRoute: typeof DevtoolsStructuredRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/tools-test': {
-      id: '/tools-test'
-      path: '/tools-test'
-      fullPath: '/tools-test'
-      preLoaderRoute: typeof ToolsTestRouteImport
+    '/devtools-subagents': {
+      id: '/devtools-subagents'
+      path: '/devtools-subagents'
+      fullPath: '/devtools-subagents'
+      preLoaderRoute: typeof DevtoolsSubagentsRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/tool-first-text': {
-      id: '/tool-first-text'
-      path: '/tool-first-text'
-      fullPath: '/tool-first-text'
-      preLoaderRoute: typeof ToolFirstTextRouteImport
+    '/devtools-tools': {
+      id: '/devtools-tools'
+      path: '/devtools-tools'
+      fullPath: '/devtools-tools'
+      preLoaderRoute: typeof DevtoolsToolsRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/text-first-tool': {
-      id: '/text-first-tool'
-      path: '/text-first-tool'
-      fullPath: '/text-first-tool'
-      preLoaderRoute: typeof TextFirstToolRouteImport
+    '/foreign-chunk-events': {
+      id: '/foreign-chunk-events'
+      path: '/foreign-chunk-events'
+      fullPath: '/foreign-chunk-events'
+      preLoaderRoute: typeof ForeignChunkEventsRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/subagents-ui-test': {
-      id: '/subagents-ui-test'
-      path: '/subagents-ui-test'
-      fullPath: '/subagents-ui-test'
-      preLoaderRoute: typeof SubagentsUiTestRouteImport
+    '/foreign-client-tool': {
+      id: '/foreign-client-tool'
+      path: '/foreign-client-tool'
+      fullPath: '/foreign-client-tool'
+      preLoaderRoute: typeof ForeignClientToolRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/foreign-interrupt': {
+      id: '/foreign-interrupt'
+      path: '/foreign-interrupt'
+      fullPath: '/foreign-interrupt'
+      preLoaderRoute: typeof ForeignInterruptRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/subagents-test': {
-      id: '/subagents-test'
-      path: '/subagents-test'
-      fullPath: '/subagents-test'
-      preLoaderRoute: typeof SubagentsTestRouteImport
+    '/generation-persistence-resume': {
+      id: '/generation-persistence-resume'
+      path: '/generation-persistence-resume'
+      fullPath: '/generation-persistence-resume'
+      preLoaderRoute: typeof GenerationPersistenceResumeRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/persistence-durability': {
-      id: '/persistence-durability'
-      path: '/persistence-durability'
-      fullPath: '/persistence-durability'
-      preLoaderRoute: typeof PersistenceDurabilityRouteImport
+    '/generation-persistence-server': {
+      id: '/generation-persistence-server'
+      path: '/generation-persistence-server'
+      fullPath: '/generation-persistence-server'
+      preLoaderRoute: typeof GenerationPersistenceServerRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/middleware-test': {
-      id: '/middleware-test'
-      path: '/middleware-test'
-      fullPath: '/middleware-test'
-      preLoaderRoute: typeof MiddlewareTestRouteImport
+    '/headless-ui': {
+      id: '/headless-ui'
+      path: '/headless-ui'
+      fullPath: '/headless-ui'
+      preLoaderRoute: typeof HeadlessUiRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/message-history-paging': {
-      id: '/message-history-paging'
-      path: '/message-history-paging'
-      fullPath: '/message-history-paging'
-      preLoaderRoute: typeof MessageHistoryPagingRouteImport
+    '/interrupt-lineage': {
+      id: '/interrupt-lineage'
+      path: '/interrupt-lineage'
+      fullPath: '/interrupt-lineage'
+      preLoaderRoute: typeof InterruptLineageRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/markdown-cjk': {
-      id: '/markdown-cjk'
-      path: '/markdown-cjk'
-      fullPath: '/markdown-cjk'
-      preLoaderRoute: typeof MarkdownCjkRouteImport
+    '/interrupts-test': {
+      id: '/interrupts-test'
+      path: '/interrupts-test'
+      fullPath: '/interrupts-test'
+      preLoaderRoute: typeof InterruptsTestRouteImport
       parentRoute: typeof rootRouteImport
     }
     '/join-run-client-tool': {
@@ -2183,473 +2122,480 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof JoinRunClientToolRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/interrupts-test': {
-      id: '/interrupts-test'
-      path: '/interrupts-test'
-      fullPath: '/interrupts-test'
-      preLoaderRoute: typeof InterruptsTestRouteImport
+    '/markdown-cjk': {
+      id: '/markdown-cjk'
+      path: '/markdown-cjk'
+      fullPath: '/markdown-cjk'
+      preLoaderRoute: typeof MarkdownCjkRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/interrupt-lineage': {
-      id: '/interrupt-lineage'
-      path: '/interrupt-lineage'
-      fullPath: '/interrupt-lineage'
-      preLoaderRoute: typeof InterruptLineageRouteImport
+    '/message-history-paging': {
+      id: '/message-history-paging'
+      path: '/message-history-paging'
+      fullPath: '/message-history-paging'
+      preLoaderRoute: typeof MessageHistoryPagingRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/headless-ui': {
-      id: '/headless-ui'
-      path: '/headless-ui'
-      fullPath: '/headless-ui'
-      preLoaderRoute: typeof HeadlessUiRouteImport
+    '/middleware-test': {
+      id: '/middleware-test'
+      path: '/middleware-test'
+      fullPath: '/middleware-test'
+      preLoaderRoute: typeof MiddlewareTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/generation-persistence-server': {
-      id: '/generation-persistence-server'
-      path: '/generation-persistence-server'
-      fullPath: '/generation-persistence-server'
-      preLoaderRoute: typeof GenerationPersistenceServerRouteImport
+    '/persistence-durability': {
+      id: '/persistence-durability'
+      path: '/persistence-durability'
+      fullPath: '/persistence-durability'
+      preLoaderRoute: typeof PersistenceDurabilityRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/generation-persistence-resume': {
-      id: '/generation-persistence-resume'
-      path: '/generation-persistence-resume'
-      fullPath: '/generation-persistence-resume'
-      preLoaderRoute: typeof GenerationPersistenceResumeRouteImport
+    '/subagents-test': {
+      id: '/subagents-test'
+      path: '/subagents-test'
+      fullPath: '/subagents-test'
+      preLoaderRoute: typeof SubagentsTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/foreign-interrupt': {
-      id: '/foreign-interrupt'
-      path: '/foreign-interrupt'
-      fullPath: '/foreign-interrupt'
-      preLoaderRoute: typeof ForeignInterruptRouteImport
+    '/subagents-ui-test': {
+      id: '/subagents-ui-test'
+      path: '/subagents-ui-test'
+      fullPath: '/subagents-ui-test'
+      preLoaderRoute: typeof SubagentsUiTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/devtools-tools': {
-      id: '/devtools-tools'
-      path: '/devtools-tools'
-      fullPath: '/devtools-tools'
-      preLoaderRoute: typeof DevtoolsToolsRouteImport
+    '/text-first-tool': {
+      id: '/text-first-tool'
+      path: '/text-first-tool'
+      fullPath: '/text-first-tool'
+      preLoaderRoute: typeof TextFirstToolRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/devtools-subagents': {
-      id: '/devtools-subagents'
-      path: '/devtools-subagents'
-      fullPath: '/devtools-subagents'
-      preLoaderRoute: typeof DevtoolsSubagentsRouteImport
+    '/tool-first-text': {
+      id: '/tool-first-text'
+      path: '/tool-first-text'
+      fullPath: '/tool-first-text'
+      preLoaderRoute: typeof ToolFirstTextRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/devtools-structured': {
-      id: '/devtools-structured'
-      path: '/devtools-structured'
-      fullPath: '/devtools-structured'
-      preLoaderRoute: typeof DevtoolsStructuredRouteImport
+    '/tools-test': {
+      id: '/tools-test'
+      path: '/tools-test'
+      fullPath: '/tools-test'
+      preLoaderRoute: typeof ToolsTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/devtools-route-b': {
-      id: '/devtools-route-b'
-      path: '/devtools-route-b'
-      fullPath: '/devtools-route-b'
-      preLoaderRoute: typeof DevtoolsRouteBRouteImport
+    '/web-mcp-page-tools': {
+      id: '/web-mcp-page-tools'
+      path: '/web-mcp-page-tools'
+      fullPath: '/web-mcp-page-tools'
+      preLoaderRoute: typeof WebMcpPageToolsRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/devtools-route-a': {
-      id: '/devtools-route-a'
-      path: '/devtools-route-a'
-      fullPath: '/devtools-route-a'
-      preLoaderRoute: typeof DevtoolsRouteARouteImport
+    '/web-mcp-tools': {
+      id: '/web-mcp-tools'
+      path: '/web-mcp-tools'
+      fullPath: '/web-mcp-tools'
+      preLoaderRoute: typeof WebMcpToolsRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/devtools-memory': {
-      id: '/devtools-memory'
-      path: '/devtools-memory'
-      fullPath: '/devtools-memory'
-      preLoaderRoute: typeof DevtoolsMemoryRouteImport
+    '/websocket-adapter': {
+      id: '/websocket-adapter'
+      path: '/websocket-adapter'
+      fullPath: '/websocket-adapter'
+      preLoaderRoute: typeof WebsocketAdapterRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/devtools-generation-hooks': {
-      id: '/devtools-generation-hooks'
-      path: '/devtools-generation-hooks'
-      fullPath: '/devtools-generation-hooks'
-      preLoaderRoute: typeof DevtoolsGenerationHooksRouteImport
+    '/$provider/': {
+      id: '/$provider/'
+      path: '/$provider'
+      fullPath: '/$provider/'
+      preLoaderRoute: typeof ProviderIndexRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/devtools-chat': {
-      id: '/devtools-chat'
-      path: '/devtools-chat'
-      fullPath: '/devtools-chat'
-      preLoaderRoute: typeof DevtoolsChatRouteImport
+    '/$provider/$feature': {
+      id: '/$provider/$feature'
+      path: '/$provider/$feature'
+      fullPath: '/$provider/$feature'
+      preLoaderRoute: typeof ProviderFeatureRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/client-mount-hydrate': {
-      id: '/client-mount-hydrate'
-      path: '/client-mount-hydrate'
-      fullPath: '/client-mount-hydrate'
-      preLoaderRoute: typeof ClientMountHydrateRouteImport
+    '/api/activity-test': {
+      id: '/api/activity-test'
+      path: '/api/activity-test'
+      fullPath: '/api/activity-test'
+      preLoaderRoute: typeof ApiActivityTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/chat-client-stream-processing': {
-      id: '/chat-client-stream-processing'
-      path: '/chat-client-stream-processing'
-      fullPath: '/chat-client-stream-processing'
-      preLoaderRoute: typeof ChatClientStreamProcessingRouteImport
+    '/api/adapter-config-reasoning-wire': {
+      id: '/api/adapter-config-reasoning-wire'
+      path: '/api/adapter-config-reasoning-wire'
+      fullPath: '/api/adapter-config-reasoning-wire'
+      preLoaderRoute: typeof ApiAdapterConfigReasoningWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/chat-client-default-bridge': {
-      id: '/chat-client-default-bridge'
-      path: '/chat-client-default-bridge'
-      fullPath: '/chat-client-default-bridge'
-      preLoaderRoute: typeof ChatClientDefaultBridgeRouteImport
+    '/api/anthropic-bug-test': {
+      id: '/api/anthropic-bug-test'
+      path: '/api/anthropic-bug-test'
+      fullPath: '/api/anthropic-bug-test'
+      preLoaderRoute: typeof ApiAnthropicBugTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/byok': {
-      id: '/byok'
-      path: '/byok'
-      fullPath: '/byok'
-      preLoaderRoute: typeof ByokRouteImport
+    '/api/anthropic-max-tokens-usage': {
+      id: '/api/anthropic-max-tokens-usage'
+      path: '/api/anthropic-max-tokens-usage'
+      fullPath: '/api/anthropic-max-tokens-usage'
+      preLoaderRoute: typeof ApiAnthropicMaxTokensUsageRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/': {
-      id: '/'
-      path: '/'
-      fullPath: '/'
-      preLoaderRoute: typeof IndexRouteImport
+    '/api/anthropic-multi-turn-structured-wire': {
+      id: '/api/anthropic-multi-turn-structured-wire'
+      path: '/api/anthropic-multi-turn-structured-wire'
+      fullPath: '/api/anthropic-multi-turn-structured-wire'
+      preLoaderRoute: typeof ApiAnthropicMultiTurnStructuredWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/$provider/': {
-      id: '/$provider/'
-      path: '/$provider'
-      fullPath: '/$provider/'
-      preLoaderRoute: typeof ProviderIndexRouteImport
+    '/api/anthropic-opus-5-combined-wire': {
+      id: '/api/anthropic-opus-5-combined-wire'
+      path: '/api/anthropic-opus-5-combined-wire'
+      fullPath: '/api/anthropic-opus-5-combined-wire'
+      preLoaderRoute: typeof ApiAnthropicOpus5CombinedWireRouteImport
       parentRoute: typeof rootRouteImport
-    }
-    '/api/world': {
-      id: '/api/world'
-      path: '/api/world'
-      fullPath: '/api/world'
-      preLoaderRoute: typeof ApiWorldRouteImport
+    }
+    '/api/anthropic-redacted-thinking-wire': {
+      id: '/api/anthropic-redacted-thinking-wire'
+      path: '/api/anthropic-redacted-thinking-wire'
+      fullPath: '/api/anthropic-redacted-thinking-wire'
+      preLoaderRoute: typeof ApiAnthropicRedactedThinkingWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/web-mcp-page-tools': {
-      id: '/api/web-mcp-page-tools'
-      path: '/api/web-mcp-page-tools'
-      fullPath: '/api/web-mcp-page-tools'
-      preLoaderRoute: typeof ApiWebMcpPageToolsRouteImport
+    '/api/anthropic-skills-wire': {
+      id: '/api/anthropic-skills-wire'
+      path: '/api/anthropic-skills-wire'
+      fullPath: '/api/anthropic-skills-wire'
+      preLoaderRoute: typeof ApiAnthropicSkillsWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/voice': {
-      id: '/api/voice'
-      path: '/api/voice'
-      fullPath: '/api/voice'
-      preLoaderRoute: typeof ApiVoiceRouteImport
+    '/api/anthropic-sonnet-5-5-wire': {
+      id: '/api/anthropic-sonnet-5-5-wire'
+      path: '/api/anthropic-sonnet-5-5-wire'
+      fullPath: '/api/anthropic-sonnet-5-5-wire'
+      preLoaderRoute: typeof ApiAnthropicSonnet55WireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/video-live': {
-      id: '/api/video-live'
-      path: '/api/video-live'
-      fullPath: '/api/video-live'
-      preLoaderRoute: typeof ApiVideoLiveRouteImport
+    '/api/anthropic-structured-usage': {
+      id: '/api/anthropic-structured-usage'
+      path: '/api/anthropic-structured-usage'
+      fullPath: '/api/anthropic-structured-usage'
+      preLoaderRoute: typeof ApiAnthropicStructuredUsageRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/video': {
-      id: '/api/video'
-      path: '/api/video'
-      fullPath: '/api/video'
-      preLoaderRoute: typeof ApiVideoRouteImport
+    '/api/anthropic-thinking-order-wire': {
+      id: '/api/anthropic-thinking-order-wire'
+      path: '/api/anthropic-thinking-order-wire'
+      fullPath: '/api/anthropic-thinking-order-wire'
+      preLoaderRoute: typeof ApiAnthropicThinkingOrderWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/tts': {
-      id: '/api/tts'
-      path: '/api/tts'
-      fullPath: '/api/tts'
-      preLoaderRoute: typeof ApiTtsRouteImport
+    '/api/anthropic-truncated-tool-input-wire': {
+      id: '/api/anthropic-truncated-tool-input-wire'
+      path: '/api/anthropic-truncated-tool-input-wire'
+      fullPath: '/api/anthropic-truncated-tool-input-wire'
+      preLoaderRoute: typeof ApiAnthropicTruncatedToolInputWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/transcription': {
-      id: '/api/transcription'
-      path: '/api/transcription'
-      fullPath: '/api/transcription'
-      preLoaderRoute: typeof ApiTranscriptionRouteImport
+    '/api/arktype-tool-wire': {
+      id: '/api/arktype-tool-wire'
+      path: '/api/arktype-tool-wire'
+      fullPath: '/api/arktype-tool-wire'
+      preLoaderRoute: typeof ApiArktypeToolWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/tools-test': {
-      id: '/api/tools-test'
-      path: '/api/tools-test'
-      fullPath: '/api/tools-test'
-      preLoaderRoute: typeof ApiToolsTestRouteImport
+    '/api/audio': {
+      id: '/api/audio'
+      path: '/api/audio'
+      fullPath: '/api/audio'
+      preLoaderRoute: typeof ApiAudioRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/tool-first-text-wire': {
-      id: '/api/tool-first-text-wire'
-      path: '/api/tool-first-text-wire'
-      fullPath: '/api/tool-first-text-wire'
-      preLoaderRoute: typeof ApiToolFirstTextWireRouteImport
+    '/api/bedrock-converse-cache': {
+      id: '/api/bedrock-converse-cache'
+      path: '/api/bedrock-converse-cache'
+      fullPath: '/api/bedrock-converse-cache'
+      preLoaderRoute: typeof ApiBedrockConverseCacheRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/tool-call-lifecycle-wire': {
-      id: '/api/tool-call-lifecycle-wire'
-      path: '/api/tool-call-lifecycle-wire'
-      fullPath: '/api/tool-call-lifecycle-wire'
-      preLoaderRoute: typeof ApiToolCallLifecycleWireRouteImport
+    '/api/byok-chat': {
+      id: '/api/byok-chat'
+      path: '/api/byok-chat'
+      fullPath: '/api/byok-chat'
+      preLoaderRoute: typeof ApiByokChatRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/text-first-tool-wire': {
-      id: '/api/text-first-tool-wire'
-      path: '/api/text-first-tool-wire'
-      fullPath: '/api/text-first-tool-wire'
-      preLoaderRoute: typeof ApiTextFirstToolWireRouteImport
+    '/api/byteplus-seedance-1080p-wire': {
+      id: '/api/byteplus-seedance-1080p-wire'
+      path: '/api/byteplus-seedance-1080p-wire'
+      fullPath: '/api/byteplus-seedance-1080p-wire'
+      preLoaderRoute: typeof ApiByteplusSeedance1080pWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/summarize': {
-      id: '/api/summarize'
-      path: '/api/summarize'
-      fullPath: '/api/summarize'
-      preLoaderRoute: typeof ApiSummarizeRouteImport
+    '/api/chat': {
+      id: '/api/chat'
+      path: '/api/chat'
+      fullPath: '/api/chat'
+      preLoaderRoute: typeof ApiChatRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/subagents-test': {
-      id: '/api/subagents-test'
-      path: '/api/subagents-test'
-      fullPath: '/api/subagents-test'
-      preLoaderRoute: typeof ApiSubagentsTestRouteImport
+    '/api/cloudflare-binding-wire': {
+      id: '/api/cloudflare-binding-wire'
+      path: '/api/cloudflare-binding-wire'
+      fullPath: '/api/cloudflare-binding-wire'
+      preLoaderRoute: typeof ApiCloudflareBindingWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/structured-output-length-wire': {
-      id: '/api/structured-output-length-wire'
-      path: '/api/structured-output-length-wire'
-      fullPath: '/api/structured-output-length-wire'
-      preLoaderRoute: typeof ApiStructuredOutputLengthWireRouteImport
+    '/api/compaction-durable-wire': {
+      id: '/api/compaction-durable-wire'
+      path: '/api/compaction-durable-wire'
+      fullPath: '/api/compaction-durable-wire'
+      preLoaderRoute: typeof ApiCompactionDurableWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/sandbox-tool-history': {
-      id: '/api/sandbox-tool-history'
-      path: '/api/sandbox-tool-history'
-      fullPath: '/api/sandbox-tool-history'
-      preLoaderRoute: typeof ApiSandboxToolHistoryRouteImport
+    '/api/compaction-wire': {
+      id: '/api/compaction-wire'
+      path: '/api/compaction-wire'
+      fullPath: '/api/compaction-wire'
+      preLoaderRoute: typeof ApiCompactionWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/sandbox-file-persistence': {
-      id: '/api/sandbox-file-persistence'
-      path: '/api/sandbox-file-persistence'
-      fullPath: '/api/sandbox-file-persistence'
-      preLoaderRoute: typeof ApiSandboxFilePersistenceRouteImport
+    '/api/devtools-memory': {
+      id: '/api/devtools-memory'
+      path: '/api/devtools-memory'
+      fullPath: '/api/devtools-memory'
+      preLoaderRoute: typeof ApiDevtoolsMemoryRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/sandbox-durability': {
-      id: '/api/sandbox-durability'
-      path: '/api/sandbox-durability'
-      fullPath: '/api/sandbox-durability'
-      preLoaderRoute: typeof ApiSandboxDurabilityRouteImport
+    '/api/durable-delivery': {
+      id: '/api/durable-delivery'
+      path: '/api/durable-delivery'
+      fullPath: '/api/durable-delivery'
+      preLoaderRoute: typeof ApiDurableDeliveryRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/provider-tool-dispatch-wire': {
-      id: '/api/provider-tool-dispatch-wire'
-      path: '/api/provider-tool-dispatch-wire'
-      fullPath: '/api/provider-tool-dispatch-wire'
-      preLoaderRoute: typeof ApiProviderToolDispatchWireRouteImport
+    '/api/durable-takeover': {
+      id: '/api/durable-takeover'
+      path: '/api/durable-takeover'
+      fullPath: '/api/durable-takeover'
+      preLoaderRoute: typeof ApiDurableTakeoverRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/provider-search-metadata-wire': {
-      id: '/api/provider-search-metadata-wire'
-      path: '/api/provider-search-metadata-wire'
-      fullPath: '/api/provider-search-metadata-wire'
-      preLoaderRoute: typeof ApiProviderSearchMetadataWireRouteImport
+    '/api/embedding': {
+      id: '/api/embedding'
+      path: '/api/embedding'
+      fullPath: '/api/embedding'
+      preLoaderRoute: typeof ApiEmbeddingRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/prompt-cache-wire': {
-      id: '/api/prompt-cache-wire'
-      path: '/api/prompt-cache-wire'
-      fullPath: '/api/prompt-cache-wire'
-      preLoaderRoute: typeof ApiPromptCacheWireRouteImport
+    '/api/file-source-wire': {
+      id: '/api/file-source-wire'
+      path: '/api/file-source-wire'
+      fullPath: '/api/file-source-wire'
+      preLoaderRoute: typeof ApiFileSourceWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/portable-skills-wire': {
-      id: '/api/portable-skills-wire'
-      path: '/api/portable-skills-wire'
-      fullPath: '/api/portable-skills-wire'
-      preLoaderRoute: typeof ApiPortableSkillsWireRouteImport
+    '/api/foreign-chunk-events': {
+      id: '/api/foreign-chunk-events'
+      path: '/api/foreign-chunk-events'
+      fullPath: '/api/foreign-chunk-events'
+      preLoaderRoute: typeof ApiForeignChunkEventsRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/persistence-durability': {
-      id: '/api/persistence-durability'
-      path: '/api/persistence-durability'
-      fullPath: '/api/persistence-durability'
-      preLoaderRoute: typeof ApiPersistenceDurabilityRouteImport
+    '/api/foreign-client-tool': {
+      id: '/api/foreign-client-tool'
+      path: '/api/foreign-client-tool'
+      fullPath: '/api/foreign-client-tool'
+      preLoaderRoute: typeof ApiForeignClientToolRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/otel-usage': {
-      id: '/api/otel-usage'
-      path: '/api/otel-usage'
-      fullPath: '/api/otel-usage'
-      preLoaderRoute: typeof ApiOtelUsageRouteImport
+    '/api/foreign-interrupt': {
+      id: '/api/foreign-interrupt'
+      path: '/api/foreign-interrupt'
+      fullPath: '/api/foreign-interrupt'
+      preLoaderRoute: typeof ApiForeignInterruptRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/otel-transcription': {
-      id: '/api/otel-transcription'
-      path: '/api/otel-transcription'
-      fullPath: '/api/otel-transcription'
-      preLoaderRoute: typeof ApiOtelTranscriptionRouteImport
+    '/api/gemini-image-ga-models': {
+      id: '/api/gemini-image-ga-models'
+      path: '/api/gemini-image-ga-models'
+      fullPath: '/api/gemini-image-ga-models'
+      preLoaderRoute: typeof ApiGeminiImageGaModelsRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/otel-media': {
-      id: '/api/otel-media'
-      path: '/api/otel-media'
-      fullPath: '/api/otel-media'
-      preLoaderRoute: typeof ApiOtelMediaRouteImport
+    '/api/gemini-native-image-wire': {
+      id: '/api/gemini-native-image-wire'
+      path: '/api/gemini-native-image-wire'
+      fullPath: '/api/gemini-native-image-wire'
+      preLoaderRoute: typeof ApiGeminiNativeImageWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/openrouter-web-tools-wire': {
-      id: '/api/openrouter-web-tools-wire'
-      path: '/api/openrouter-web-tools-wire'
-      fullPath: '/api/openrouter-web-tools-wire'
-      preLoaderRoute: typeof ApiOpenrouterWebToolsWireRouteImport
+    '/api/generation-persistence-resume': {
+      id: '/api/generation-persistence-resume'
+      path: '/api/generation-persistence-resume'
+      fullPath: '/api/generation-persistence-resume'
+      preLoaderRoute: typeof ApiGenerationPersistenceResumeRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/openrouter-stream-options-wire': {
-      id: '/api/openrouter-stream-options-wire'
-      path: '/api/openrouter-stream-options-wire'
-      fullPath: '/api/openrouter-stream-options-wire'
-      preLoaderRoute: typeof ApiOpenrouterStreamOptionsWireRouteImport
+    '/api/generation-persistence-server': {
+      id: '/api/generation-persistence-server'
+      path: '/api/generation-persistence-server'
+      fullPath: '/api/generation-persistence-server'
+      preLoaderRoute: typeof ApiGenerationPersistenceServerRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/openrouter-strict-tool-optionals': {
-      id: '/api/openrouter-strict-tool-optionals'
-      path: '/api/openrouter-strict-tool-optionals'
-      fullPath: '/api/openrouter-strict-tool-optionals'
-      preLoaderRoute: typeof ApiOpenrouterStrictToolOptionalsRouteImport
+    '/api/harness-test': {
+      id: '/api/harness-test'
+      path: '/api/harness-test'
+      fullPath: '/api/harness-test'
+      preLoaderRoute: typeof ApiHarnessTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/openrouter-retry-codes': {
-      id: '/api/openrouter-retry-codes'
-      path: '/api/openrouter-retry-codes'
-      fullPath: '/api/openrouter-retry-codes'
-      preLoaderRoute: typeof ApiOpenrouterRetryCodesRouteImport
+    '/api/harness-turn-overrides': {
+      id: '/api/harness-turn-overrides'
+      path: '/api/harness-turn-overrides'
+      fullPath: '/api/harness-turn-overrides'
+      preLoaderRoute: typeof ApiHarnessTurnOverridesRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/openrouter-reasoning-wire': {
-      id: '/api/openrouter-reasoning-wire'
-      path: '/api/openrouter-reasoning-wire'
-      fullPath: '/api/openrouter-reasoning-wire'
-      preLoaderRoute: typeof ApiOpenrouterReasoningWireRouteImport
+    '/api/image': {
+      id: '/api/image'
+      path: '/api/image'
+      fullPath: '/api/image'
+      preLoaderRoute: typeof ApiImageRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/openrouter-json-object-wire': {
-      id: '/api/openrouter-json-object-wire'
-      path: '/api/openrouter-json-object-wire'
-      fullPath: '/api/openrouter-json-object-wire'
-      preLoaderRoute: typeof ApiOpenrouterJsonObjectWireRouteImport
+    '/api/interrupts-test': {
+      id: '/api/interrupts-test'
+      path: '/api/interrupts-test'
+      fullPath: '/api/interrupts-test'
+      preLoaderRoute: typeof ApiInterruptsTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/openrouter-cost': {
-      id: '/api/openrouter-cost'
-      path: '/api/openrouter-cost'
-      fullPath: '/api/openrouter-cost'
-      preLoaderRoute: typeof ApiOpenrouterCostRouteImport
+    '/api/join-run-client-tool': {
+      id: '/api/join-run-client-tool'
+      path: '/api/join-run-client-tool'
+      fullPath: '/api/join-run-client-tool'
+      preLoaderRoute: typeof ApiJoinRunClientToolRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/openai-usage-details': {
-      id: '/api/openai-usage-details'
-      path: '/api/openai-usage-details'
-      fullPath: '/api/openai-usage-details'
-      preLoaderRoute: typeof ApiOpenaiUsageDetailsRouteImport
+    '/api/lazy-tools-wire': {
+      id: '/api/lazy-tools-wire'
+      path: '/api/lazy-tools-wire'
+      fullPath: '/api/lazy-tools-wire'
+      preLoaderRoute: typeof ApiLazyToolsWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/openai-strict-tool-null-wire': {
-      id: '/api/openai-strict-tool-null-wire'
-      path: '/api/openai-strict-tool-null-wire'
-      fullPath: '/api/openai-strict-tool-null-wire'
-      preLoaderRoute: typeof ApiOpenaiStrictToolNullWireRouteImport
+    '/api/max-tool-calls-wire': {
+      id: '/api/max-tool-calls-wire'
+      path: '/api/max-tool-calls-wire'
+      fullPath: '/api/max-tool-calls-wire'
+      preLoaderRoute: typeof ApiMaxToolCallsWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/openai-shell-skills-wire': {
-      id: '/api/openai-shell-skills-wire'
-      path: '/api/openai-shell-skills-wire'
-      fullPath: '/api/openai-shell-skills-wire'
-      preLoaderRoute: typeof ApiOpenaiShellSkillsWireRouteImport
+    '/api/mcp-apps-call': {
+      id: '/api/mcp-apps-call'
+      path: '/api/mcp-apps-call'
+      fullPath: '/api/mcp-apps-call'
+      preLoaderRoute: typeof ApiMcpAppsCallRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/openai-image-2-5-models': {
-      id: '/api/openai-image-2-5-models'
-      path: '/api/openai-image-2-5-models'
-      fullPath: '/api/openai-image-2-5-models'
-      preLoaderRoute: typeof ApiOpenaiImage25ModelsRouteImport
+    '/api/mcp-apps-chat': {
+      id: '/api/mcp-apps-chat'
+      path: '/api/mcp-apps-chat'
+      fullPath: '/api/mcp-apps-chat'
+      preLoaderRoute: typeof ApiMcpAppsChatRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/openai-malformed-tool-arguments': {
-      id: '/api/openai-malformed-tool-arguments'
-      path: '/api/openai-malformed-tool-arguments'
-      fullPath: '/api/openai-malformed-tool-arguments'
-      preLoaderRoute: typeof ApiOpenaiMalformedToolArgumentsRouteImport
+    '/api/mcp-apps-server': {
+      id: '/api/mcp-apps-server'
+      path: '/api/mcp-apps-server'
+      fullPath: '/api/mcp-apps-server'
+      preLoaderRoute: typeof ApiMcpAppsServerRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/openai-completed-response-text': {
-      id: '/api/openai-completed-response-text'
-      path: '/api/openai-completed-response-text'
-      fullPath: '/api/openai-completed-response-text'
-      preLoaderRoute: typeof ApiOpenaiCompletedResponseTextRouteImport
+    '/api/mcp-input-server': {
+      id: '/api/mcp-input-server'
+      path: '/api/mcp-input-server'
+      fullPath: '/api/mcp-input-server'
+      preLoaderRoute: typeof ApiMcpInputServerRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/non-streaming-run-error': {
-      id: '/api/non-streaming-run-error'
-      path: '/api/non-streaming-run-error'
-      fullPath: '/api/non-streaming-run-error'
-      preLoaderRoute: typeof ApiNonStreamingRunErrorRouteImport
+    '/api/mcp-input-test': {
+      id: '/api/mcp-input-test'
+      path: '/api/mcp-input-test'
+      fullPath: '/api/mcp-input-test'
+      preLoaderRoute: typeof ApiMcpInputTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/multimodal-tool-result-wire': {
-      id: '/api/multimodal-tool-result-wire'
-      path: '/api/multimodal-tool-result-wire'
-      fullPath: '/api/multimodal-tool-result-wire'
-      preLoaderRoute: typeof ApiMultimodalToolResultWireRouteImport
+    '/api/mcp-lifecycle-test': {
+      id: '/api/mcp-lifecycle-test'
+      path: '/api/mcp-lifecycle-test'
+      fullPath: '/api/mcp-lifecycle-test'
+      preLoaderRoute: typeof ApiMcpLifecycleTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/moonshot-usage-details': {
-      id: '/api/moonshot-usage-details'
-      path: '/api/moonshot-usage-details'
-      fullPath: '/api/moonshot-usage-details'
-      preLoaderRoute: typeof ApiMoonshotUsageDetailsRouteImport
+    '/api/mcp-managed-test': {
+      id: '/api/mcp-managed-test'
+      path: '/api/mcp-managed-test'
+      fullPath: '/api/mcp-managed-test'
+      preLoaderRoute: typeof ApiMcpManagedTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/mistral-strict-tool-null-wire': {
-      id: '/api/mistral-strict-tool-null-wire'
-      path: '/api/mistral-strict-tool-null-wire'
-      fullPath: '/api/mistral-strict-tool-null-wire'
-      preLoaderRoute: typeof ApiMistralStrictToolNullWireRouteImport
+    '/api/mcp-no-tasks-server': {
+      id: '/api/mcp-no-tasks-server'
+      path: '/api/mcp-no-tasks-server'
+      fullPath: '/api/mcp-no-tasks-server'
+      preLoaderRoute: typeof ApiMcpNoTasksServerRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/middleware-test': {
-      id: '/api/middleware-test'
-      path: '/api/middleware-test'
-      fullPath: '/api/middleware-test'
-      preLoaderRoute: typeof ApiMiddlewareTestRouteImport
+    '/api/mcp-policy-test': {
+      id: '/api/mcp-policy-test'
+      path: '/api/mcp-policy-test'
+      fullPath: '/api/mcp-policy-test'
+      preLoaderRoute: typeof ApiMcpPolicyTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/mid-conversation-changes-wire': {
-      id: '/api/mid-conversation-changes-wire'
-      path: '/api/mid-conversation-changes-wire'
-      fullPath: '/api/mid-conversation-changes-wire'
-      preLoaderRoute: typeof ApiMidConversationChangesWireRouteImport
+    '/api/mcp-server': {
+      id: '/api/mcp-server'
+      path: '/api/mcp-server'
+      fullPath: '/api/mcp-server'
+      preLoaderRoute: typeof ApiMcpServerRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/message-ids': {
-      id: '/api/message-ids'
-      path: '/api/message-ids'
-      fullPath: '/api/message-ids'
-      preLoaderRoute: typeof ApiMessageIdsRouteImport
+    '/api/mcp-status-test': {
+      id: '/api/mcp-status-test'
+      path: '/api/mcp-status-test'
+      fullPath: '/api/mcp-status-test'
+      preLoaderRoute: typeof ApiMcpStatusTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/message-history-paging': {
-      id: '/api/message-history-paging'
-      path: '/api/message-history-paging'
-      fullPath: '/api/message-history-paging'
-      preLoaderRoute: typeof ApiMessageHistoryPagingRouteImport
+    '/api/mcp-task-errors': {
+      id: '/api/mcp-task-errors'
+      path: '/api/mcp-task-errors'
+      fullPath: '/api/mcp-task-errors'
+      preLoaderRoute: typeof ApiMcpTaskErrorsRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/mcp-typed-test': {
-      id: '/api/mcp-typed-test'
-      path: '/api/mcp-typed-test'
-      fullPath: '/api/mcp-typed-test'
-      preLoaderRoute: typeof ApiMcpTypedTestRouteImport
+    '/api/mcp-test': {
+      id: '/api/mcp-test'
+      path: '/api/mcp-test'
+      fullPath: '/api/mcp-test'
+      preLoaderRoute: typeof ApiMcpTestRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/mcp-tool-options-wire': {
+      id: '/api/mcp-tool-options-wire'
+      path: '/api/mcp-tool-options-wire'
+      fullPath: '/api/mcp-tool-options-wire'
+      preLoaderRoute: typeof ApiMcpToolOptionsWireRouteImport
       parentRoute: typeof rootRouteImport
     }
     '/api/mcp-typed-server': {
@@ -2659,355 +2605,362 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiMcpTypedServerRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/mcp-tool-options-wire': {
-      id: '/api/mcp-tool-options-wire'
-      path: '/api/mcp-tool-options-wire'
-      fullPath: '/api/mcp-tool-options-wire'
-      preLoaderRoute: typeof ApiMcpToolOptionsWireRouteImport
+    '/api/mcp-typed-test': {
+      id: '/api/mcp-typed-test'
+      path: '/api/mcp-typed-test'
+      fullPath: '/api/mcp-typed-test'
+      preLoaderRoute: typeof ApiMcpTypedTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/mcp-test': {
-      id: '/api/mcp-test'
-      path: '/api/mcp-test'
-      fullPath: '/api/mcp-test'
-      preLoaderRoute: typeof ApiMcpTestRouteImport
+    '/api/message-history-paging': {
+      id: '/api/message-history-paging'
+      path: '/api/message-history-paging'
+      fullPath: '/api/message-history-paging'
+      preLoaderRoute: typeof ApiMessageHistoryPagingRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/mcp-task-errors': {
-      id: '/api/mcp-task-errors'
-      path: '/api/mcp-task-errors'
-      fullPath: '/api/mcp-task-errors'
-      preLoaderRoute: typeof ApiMcpTaskErrorsRouteImport
+    '/api/message-ids': {
+      id: '/api/message-ids'
+      path: '/api/message-ids'
+      fullPath: '/api/message-ids'
+      preLoaderRoute: typeof ApiMessageIdsRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/mcp-status-test': {
-      id: '/api/mcp-status-test'
-      path: '/api/mcp-status-test'
-      fullPath: '/api/mcp-status-test'
-      preLoaderRoute: typeof ApiMcpStatusTestRouteImport
+    '/api/mid-conversation-changes-wire': {
+      id: '/api/mid-conversation-changes-wire'
+      path: '/api/mid-conversation-changes-wire'
+      fullPath: '/api/mid-conversation-changes-wire'
+      preLoaderRoute: typeof ApiMidConversationChangesWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/mcp-server': {
-      id: '/api/mcp-server'
-      path: '/api/mcp-server'
-      fullPath: '/api/mcp-server'
-      preLoaderRoute: typeof ApiMcpServerRouteImport
+    '/api/middleware-test': {
+      id: '/api/middleware-test'
+      path: '/api/middleware-test'
+      fullPath: '/api/middleware-test'
+      preLoaderRoute: typeof ApiMiddlewareTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/mcp-policy-test': {
-      id: '/api/mcp-policy-test'
-      path: '/api/mcp-policy-test'
-      fullPath: '/api/mcp-policy-test'
-      preLoaderRoute: typeof ApiMcpPolicyTestRouteImport
+    '/api/mistral-strict-tool-null-wire': {
+      id: '/api/mistral-strict-tool-null-wire'
+      path: '/api/mistral-strict-tool-null-wire'
+      fullPath: '/api/mistral-strict-tool-null-wire'
+      preLoaderRoute: typeof ApiMistralStrictToolNullWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/mcp-no-tasks-server': {
-      id: '/api/mcp-no-tasks-server'
-      path: '/api/mcp-no-tasks-server'
-      fullPath: '/api/mcp-no-tasks-server'
-      preLoaderRoute: typeof ApiMcpNoTasksServerRouteImport
+    '/api/moonshot-usage-details': {
+      id: '/api/moonshot-usage-details'
+      path: '/api/moonshot-usage-details'
+      fullPath: '/api/moonshot-usage-details'
+      preLoaderRoute: typeof ApiMoonshotUsageDetailsRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/mcp-managed-test': {
-      id: '/api/mcp-managed-test'
-      path: '/api/mcp-managed-test'
-      fullPath: '/api/mcp-managed-test'
-      preLoaderRoute: typeof ApiMcpManagedTestRouteImport
+    '/api/multimodal-tool-result-wire': {
+      id: '/api/multimodal-tool-result-wire'
+      path: '/api/multimodal-tool-result-wire'
+      fullPath: '/api/multimodal-tool-result-wire'
+      preLoaderRoute: typeof ApiMultimodalToolResultWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/mcp-lifecycle-test': {
-      id: '/api/mcp-lifecycle-test'
-      path: '/api/mcp-lifecycle-test'
-      fullPath: '/api/mcp-lifecycle-test'
-      preLoaderRoute: typeof ApiMcpLifecycleTestRouteImport
+    '/api/non-streaming-run-error': {
+      id: '/api/non-streaming-run-error'
+      path: '/api/non-streaming-run-error'
+      fullPath: '/api/non-streaming-run-error'
+      preLoaderRoute: typeof ApiNonStreamingRunErrorRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/mcp-input-test': {
-      id: '/api/mcp-input-test'
-      path: '/api/mcp-input-test'
-      fullPath: '/api/mcp-input-test'
-      preLoaderRoute: typeof ApiMcpInputTestRouteImport
+    '/api/openai-completed-response-text': {
+      id: '/api/openai-completed-response-text'
+      path: '/api/openai-completed-response-text'
+      fullPath: '/api/openai-completed-response-text'
+      preLoaderRoute: typeof ApiOpenaiCompletedResponseTextRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/mcp-input-server': {
-      id: '/api/mcp-input-server'
-      path: '/api/mcp-input-server'
-      fullPath: '/api/mcp-input-server'
-      preLoaderRoute: typeof ApiMcpInputServerRouteImport
+    '/api/openai-image-2-5-models': {
+      id: '/api/openai-image-2-5-models'
+      path: '/api/openai-image-2-5-models'
+      fullPath: '/api/openai-image-2-5-models'
+      preLoaderRoute: typeof ApiOpenaiImage25ModelsRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/mcp-apps-server': {
-      id: '/api/mcp-apps-server'
-      path: '/api/mcp-apps-server'
-      fullPath: '/api/mcp-apps-server'
-      preLoaderRoute: typeof ApiMcpAppsServerRouteImport
+    '/api/openai-malformed-tool-arguments': {
+      id: '/api/openai-malformed-tool-arguments'
+      path: '/api/openai-malformed-tool-arguments'
+      fullPath: '/api/openai-malformed-tool-arguments'
+      preLoaderRoute: typeof ApiOpenaiMalformedToolArgumentsRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/mcp-apps-chat': {
-      id: '/api/mcp-apps-chat'
-      path: '/api/mcp-apps-chat'
-      fullPath: '/api/mcp-apps-chat'
-      preLoaderRoute: typeof ApiMcpAppsChatRouteImport
+    '/api/openai-shell-skills-wire': {
+      id: '/api/openai-shell-skills-wire'
+      path: '/api/openai-shell-skills-wire'
+      fullPath: '/api/openai-shell-skills-wire'
+      preLoaderRoute: typeof ApiOpenaiShellSkillsWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/mcp-apps-call': {
-      id: '/api/mcp-apps-call'
-      path: '/api/mcp-apps-call'
-      fullPath: '/api/mcp-apps-call'
-      preLoaderRoute: typeof ApiMcpAppsCallRouteImport
+    '/api/openai-strict-tool-null-wire': {
+      id: '/api/openai-strict-tool-null-wire'
+      path: '/api/openai-strict-tool-null-wire'
+      fullPath: '/api/openai-strict-tool-null-wire'
+      preLoaderRoute: typeof ApiOpenaiStrictToolNullWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/max-tool-calls-wire': {
-      id: '/api/max-tool-calls-wire'
-      path: '/api/max-tool-calls-wire'
-      fullPath: '/api/max-tool-calls-wire'
-      preLoaderRoute: typeof ApiMaxToolCallsWireRouteImport
+    '/api/openai-usage-details': {
+      id: '/api/openai-usage-details'
+      path: '/api/openai-usage-details'
+      fullPath: '/api/openai-usage-details'
+      preLoaderRoute: typeof ApiOpenaiUsageDetailsRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/lazy-tools-wire': {
-      id: '/api/lazy-tools-wire'
-      path: '/api/lazy-tools-wire'
-      fullPath: '/api/lazy-tools-wire'
-      preLoaderRoute: typeof ApiLazyToolsWireRouteImport
+    '/api/openrouter-cost': {
+      id: '/api/openrouter-cost'
+      path: '/api/openrouter-cost'
+      fullPath: '/api/openrouter-cost'
+      preLoaderRoute: typeof ApiOpenrouterCostRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/join-run-client-tool': {
-      id: '/api/join-run-client-tool'
-      path: '/api/join-run-client-tool'
-      fullPath: '/api/join-run-client-tool'
-      preLoaderRoute: typeof ApiJoinRunClientToolRouteImport
+    '/api/openrouter-json-object-wire': {
+      id: '/api/openrouter-json-object-wire'
+      path: '/api/openrouter-json-object-wire'
+      fullPath: '/api/openrouter-json-object-wire'
+      preLoaderRoute: typeof ApiOpenrouterJsonObjectWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/interrupts-test': {
-      id: '/api/interrupts-test'
-      path: '/api/interrupts-test'
-      fullPath: '/api/interrupts-test'
-      preLoaderRoute: typeof ApiInterruptsTestRouteImport
+    '/api/openrouter-reasoning-wire': {
+      id: '/api/openrouter-reasoning-wire'
+      path: '/api/openrouter-reasoning-wire'
+      fullPath: '/api/openrouter-reasoning-wire'
+      preLoaderRoute: typeof ApiOpenrouterReasoningWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/image': {
-      id: '/api/image'
-      path: '/api/image'
-      fullPath: '/api/image'
-      preLoaderRoute: typeof ApiImageRouteImport
+    '/api/openrouter-retry-codes': {
+      id: '/api/openrouter-retry-codes'
+      path: '/api/openrouter-retry-codes'
+      fullPath: '/api/openrouter-retry-codes'
+      preLoaderRoute: typeof ApiOpenrouterRetryCodesRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/harness-turn-overrides': {
-      id: '/api/harness-turn-overrides'
-      path: '/api/harness-turn-overrides'
-      fullPath: '/api/harness-turn-overrides'
-      preLoaderRoute: typeof ApiHarnessTurnOverridesRouteImport
+    '/api/openrouter-stream-options-wire': {
+      id: '/api/openrouter-stream-options-wire'
+      path: '/api/openrouter-stream-options-wire'
+      fullPath: '/api/openrouter-stream-options-wire'
+      preLoaderRoute: typeof ApiOpenrouterStreamOptionsWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/harness-test': {
-      id: '/api/harness-test'
-      path: '/api/harness-test'
-      fullPath: '/api/harness-test'
-      preLoaderRoute: typeof ApiHarnessTestRouteImport
+    '/api/openrouter-strict-tool-optionals': {
+      id: '/api/openrouter-strict-tool-optionals'
+      path: '/api/openrouter-strict-tool-optionals'
+      fullPath: '/api/openrouter-strict-tool-optionals'
+      preLoaderRoute: typeof ApiOpenrouterStrictToolOptionalsRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/generation-persistence-server': {
-      id: '/api/generation-persistence-server'
-      path: '/api/generation-persistence-server'
-      fullPath: '/api/generation-persistence-server'
-      preLoaderRoute: typeof ApiGenerationPersistenceServerRouteImport
+    '/api/openrouter-web-tools-wire': {
+      id: '/api/openrouter-web-tools-wire'
+      path: '/api/openrouter-web-tools-wire'
+      fullPath: '/api/openrouter-web-tools-wire'
+      preLoaderRoute: typeof ApiOpenrouterWebToolsWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/generation-persistence-resume': {
-      id: '/api/generation-persistence-resume'
-      path: '/api/generation-persistence-resume'
-      fullPath: '/api/generation-persistence-resume'
-      preLoaderRoute: typeof ApiGenerationPersistenceResumeRouteImport
+    '/api/otel-media': {
+      id: '/api/otel-media'
+      path: '/api/otel-media'
+      fullPath: '/api/otel-media'
+      preLoaderRoute: typeof ApiOtelMediaRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/gemini-native-image-wire': {
-      id: '/api/gemini-native-image-wire'
-      path: '/api/gemini-native-image-wire'
-      fullPath: '/api/gemini-native-image-wire'
-      preLoaderRoute: typeof ApiGeminiNativeImageWireRouteImport
+    '/api/otel-transcription': {
+      id: '/api/otel-transcription'
+      path: '/api/otel-transcription'
+      fullPath: '/api/otel-transcription'
+      preLoaderRoute: typeof ApiOtelTranscriptionRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/gemini-image-ga-models': {
-      id: '/api/gemini-image-ga-models'
-      path: '/api/gemini-image-ga-models'
-      fullPath: '/api/gemini-image-ga-models'
-      preLoaderRoute: typeof ApiGeminiImageGaModelsRouteImport
+    '/api/otel-usage': {
+      id: '/api/otel-usage'
+      path: '/api/otel-usage'
+      fullPath: '/api/otel-usage'
+      preLoaderRoute: typeof ApiOtelUsageRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/foreign-interrupt': {
-      id: '/api/foreign-interrupt'
-      path: '/api/foreign-interrupt'
-      fullPath: '/api/foreign-interrupt'
-      preLoaderRoute: typeof ApiForeignInterruptRouteImport
+    '/api/persistence-durability': {
+      id: '/api/persistence-durability'
+      path: '/api/persistence-durability'
+      fullPath: '/api/persistence-durability'
+      preLoaderRoute: typeof ApiPersistenceDurabilityRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/file-source-wire': {
-      id: '/api/file-source-wire'
-      path: '/api/file-source-wire'
-      fullPath: '/api/file-source-wire'
-      preLoaderRoute: typeof ApiFileSourceWireRouteImport
+    '/api/portable-skills-wire': {
+      id: '/api/portable-skills-wire'
+      path: '/api/portable-skills-wire'
+      fullPath: '/api/portable-skills-wire'
+      preLoaderRoute: typeof ApiPortableSkillsWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/embedding': {
-      id: '/api/embedding'
-      path: '/api/embedding'
-      fullPath: '/api/embedding'
-      preLoaderRoute: typeof ApiEmbeddingRouteImport
+    '/api/prompt-cache-wire': {
+      id: '/api/prompt-cache-wire'
+      path: '/api/prompt-cache-wire'
+      fullPath: '/api/prompt-cache-wire'
+      preLoaderRoute: typeof ApiPromptCacheWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/durable-takeover': {
-      id: '/api/durable-takeover'
-      path: '/api/durable-takeover'
-      fullPath: '/api/durable-takeover'
-      preLoaderRoute: typeof ApiDurableTakeoverRouteImport
+    '/api/provider-search-metadata-wire': {
+      id: '/api/provider-search-metadata-wire'
+      path: '/api/provider-search-metadata-wire'
+      fullPath: '/api/provider-search-metadata-wire'
+      preLoaderRoute: typeof ApiProviderSearchMetadataWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/durable-delivery': {
-      id: '/api/durable-delivery'
-      path: '/api/durable-delivery'
-      fullPath: '/api/durable-delivery'
-      preLoaderRoute: typeof ApiDurableDeliveryRouteImport
+    '/api/provider-tool-dispatch-wire': {
+      id: '/api/provider-tool-dispatch-wire'
+      path: '/api/provider-tool-dispatch-wire'
+      fullPath: '/api/provider-tool-dispatch-wire'
+      preLoaderRoute: typeof ApiProviderToolDispatchWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/devtools-memory': {
-      id: '/api/devtools-memory'
-      path: '/api/devtools-memory'
-      fullPath: '/api/devtools-memory'
-      preLoaderRoute: typeof ApiDevtoolsMemoryRouteImport
+    '/api/sandbox-durability': {
+      id: '/api/sandbox-durability'
+      path: '/api/sandbox-durability'
+      fullPath: '/api/sandbox-durability'
+      preLoaderRoute: typeof ApiSandboxDurabilityRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/compaction-wire': {
-      id: '/api/compaction-wire'
-      path: '/api/compaction-wire'
-      fullPath: '/api/compaction-wire'
-      preLoaderRoute: typeof ApiCompactionWireRouteImport
+    '/api/sandbox-file-persistence': {
+      id: '/api/sandbox-file-persistence'
+      path: '/api/sandbox-file-persistence'
+      fullPath: '/api/sandbox-file-persistence'
+      preLoaderRoute: typeof ApiSandboxFilePersistenceRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/compaction-durable-wire': {
-      id: '/api/compaction-durable-wire'
-      path: '/api/compaction-durable-wire'
-      fullPath: '/api/compaction-durable-wire'
-      preLoaderRoute: typeof ApiCompactionDurableWireRouteImport
+    '/api/sandbox-tool-history': {
+      id: '/api/sandbox-tool-history'
+      path: '/api/sandbox-tool-history'
+      fullPath: '/api/sandbox-tool-history'
+      preLoaderRoute: typeof ApiSandboxToolHistoryRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/cloudflare-binding-wire': {
-      id: '/api/cloudflare-binding-wire'
-      path: '/api/cloudflare-binding-wire'
-      fullPath: '/api/cloudflare-binding-wire'
-      preLoaderRoute: typeof ApiCloudflareBindingWireRouteImport
+    '/api/structured-output-length-wire': {
+      id: '/api/structured-output-length-wire'
+      path: '/api/structured-output-length-wire'
+      fullPath: '/api/structured-output-length-wire'
+      preLoaderRoute: typeof ApiStructuredOutputLengthWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/chat': {
-      id: '/api/chat'
-      path: '/api/chat'
-      fullPath: '/api/chat'
-      preLoaderRoute: typeof ApiChatRouteImport
+    '/api/subagents-test': {
+      id: '/api/subagents-test'
+      path: '/api/subagents-test'
+      fullPath: '/api/subagents-test'
+      preLoaderRoute: typeof ApiSubagentsTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/byteplus-seedance-1080p-wire': {
-      id: '/api/byteplus-seedance-1080p-wire'
-      path: '/api/byteplus-seedance-1080p-wire'
-      fullPath: '/api/byteplus-seedance-1080p-wire'
-      preLoaderRoute: typeof ApiByteplusSeedance1080pWireRouteImport
+    '/api/summarize': {
+      id: '/api/summarize'
+      path: '/api/summarize'
+      fullPath: '/api/summarize'
+      preLoaderRoute: typeof ApiSummarizeRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/byok-chat': {
-      id: '/api/byok-chat'
-      path: '/api/byok-chat'
-      fullPath: '/api/byok-chat'
-      preLoaderRoute: typeof ApiByokChatRouteImport
+    '/api/text-first-tool-wire': {
+      id: '/api/text-first-tool-wire'
+      path: '/api/text-first-tool-wire'
+      fullPath: '/api/text-first-tool-wire'
+      preLoaderRoute: typeof ApiTextFirstToolWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/bedrock-converse-cache': {
-      id: '/api/bedrock-converse-cache'
-      path: '/api/bedrock-converse-cache'
-      fullPath: '/api/bedrock-converse-cache'
-      preLoaderRoute: typeof ApiBedrockConverseCacheRouteImport
+    '/api/tool-call-lifecycle-wire': {
+      id: '/api/tool-call-lifecycle-wire'
+      path: '/api/tool-call-lifecycle-wire'
+      fullPath: '/api/tool-call-lifecycle-wire'
+      preLoaderRoute: typeof ApiToolCallLifecycleWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/audio': {
-      id: '/api/audio'
-      path: '/api/audio'
-      fullPath: '/api/audio'
-      preLoaderRoute: typeof ApiAudioRouteImport
+    '/api/tool-choice-wire': {
+      id: '/api/tool-choice-wire'
+      path: '/api/tool-choice-wire'
+      fullPath: '/api/tool-choice-wire'
+      preLoaderRoute: typeof ApiToolChoiceWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/arktype-tool-wire': {
-      id: '/api/arktype-tool-wire'
-      path: '/api/arktype-tool-wire'
-      fullPath: '/api/arktype-tool-wire'
-      preLoaderRoute: typeof ApiArktypeToolWireRouteImport
+    '/api/tool-first-text-wire': {
+      id: '/api/tool-first-text-wire'
+      path: '/api/tool-first-text-wire'
+      fullPath: '/api/tool-first-text-wire'
+      preLoaderRoute: typeof ApiToolFirstTextWireRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/anthropic-thinking-order-wire': {
-      id: '/api/anthropic-thinking-order-wire'
-      path: '/api/anthropic-thinking-order-wire'
-      fullPath: '/api/anthropic-thinking-order-wire'
-      preLoaderRoute: typeof ApiAnthropicThinkingOrderWireRouteImport
+    '/api/tools-test': {
+      id: '/api/tools-test'
+      path: '/api/tools-test'
+      fullPath: '/api/tools-test'
+      preLoaderRoute: typeof ApiToolsTestRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/anthropic-structured-usage': {
-      id: '/api/anthropic-structured-usage'
-      path: '/api/anthropic-structured-usage'
-      fullPath: '/api/anthropic-structured-usage'
-      preLoaderRoute: typeof ApiAnthropicStructuredUsageRouteImport
+    '/api/transcription': {
+      id: '/api/transcription'
+      path: '/api/transcription'
+      fullPath: '/api/transcription'
+      preLoaderRoute: typeof ApiTranscriptionRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/anthropic-skills-wire': {
-      id: '/api/anthropic-skills-wire'
-      path: '/api/anthropic-skills-wire'
-      fullPath: '/api/anthropic-skills-wire'
-      preLoaderRoute: typeof ApiAnthropicSkillsWireRouteImport
+    '/api/tts': {
+      id: '/api/tts'
+      path: '/api/tts'
+      fullPath: '/api/tts'
+      preLoaderRoute: typeof ApiTtsRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/anthropic-redacted-thinking-wire': {
-      id: '/api/anthropic-redacted-thinking-wire'
-      path: '/api/anthropic-redacted-thinking-wire'
-      fullPath: '/api/anthropic-redacted-thinking-wire'
-      preLoaderRoute: typeof ApiAnthropicRedactedThinkingWireRouteImport
+    '/api/video': {
+      id: '/api/video'
+      path: '/api/video'
+      fullPath: '/api/video'
+      preLoaderRoute: typeof ApiVideoRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/anthropic-opus-5-combined-wire': {
-      id: '/api/anthropic-opus-5-combined-wire'
-      path: '/api/anthropic-opus-5-combined-wire'
-      fullPath: '/api/anthropic-opus-5-combined-wire'
-      preLoaderRoute: typeof ApiAnthropicOpus5CombinedWireRouteImport
+    '/api/video-live': {
+      id: '/api/video-live'
+      path: '/api/video-live'
+      fullPath: '/api/video-live'
+      preLoaderRoute: typeof ApiVideoLiveRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/anthropic-multi-turn-structured-wire': {
-      id: '/api/anthropic-multi-turn-structured-wire'
-      path: '/api/anthropic-multi-turn-structured-wire'
-      fullPath: '/api/anthropic-multi-turn-structured-wire'
-      preLoaderRoute: typeof ApiAnthropicMultiTurnStructuredWireRouteImport
+    '/api/voice': {
+      id: '/api/voice'
+      path: '/api/voice'
+      fullPath: '/api/voice'
+      preLoaderRoute: typeof ApiVoiceRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/anthropic-bug-test': {
-      id: '/api/anthropic-bug-test'
-      path: '/api/anthropic-bug-test'
-      fullPath: '/api/anthropic-bug-test'
-      preLoaderRoute: typeof ApiAnthropicBugTestRouteImport
+    '/api/web-mcp-page-tools': {
+      id: '/api/web-mcp-page-tools'
+      path: '/api/web-mcp-page-tools'
+      fullPath: '/api/web-mcp-page-tools'
+      preLoaderRoute: typeof ApiWebMcpPageToolsRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/$provider/$feature': {
-      id: '/$provider/$feature'
-      path: '/$provider/$feature'
-      fullPath: '/$provider/$feature'
-      preLoaderRoute: typeof ProviderFeatureRouteImport
+    '/api/world': {
+      id: '/api/world'
+      path: '/api/world'
+      fullPath: '/api/world'
+      preLoaderRoute: typeof ApiWorldRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/api/video/stream': {
-      id: '/api/video/stream'
+    '/api/audio/stream': {
+      id: '/api/audio/stream'
       path: '/stream'
-      fullPath: '/api/video/stream'
-      preLoaderRoute: typeof ApiVideoStreamRouteImport
-      parentRoute: typeof ApiVideoRoute
+      fullPath: '/api/audio/stream'
+      preLoaderRoute: typeof ApiAudioStreamRouteImport
+      parentRoute: typeof ApiAudioRoute
     }
-    '/api/tts/stream': {
-      id: '/api/tts/stream'
+    '/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'
-      fullPath: '/api/tts/stream'
-      preLoaderRoute: typeof ApiTtsStreamRouteImport
-      parentRoute: typeof ApiTtsRoute
+      fullPath: '/api/image/stream'
+      preLoaderRoute: typeof ApiImageStreamRouteImport
+      parentRoute: typeof ApiImageRoute
     }
     '/api/transcription/stream': {
       id: '/api/transcription/stream'
@@ -3016,26 +2969,19 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiTranscriptionStreamRouteImport
       parentRoute: typeof ApiTranscriptionRoute
     }
-    '/api/image/stream': {
-      id: '/api/image/stream'
+    '/api/tts/stream': {
+      id: '/api/tts/stream'
       path: '/stream'
-      fullPath: '/api/image/stream'
-      preLoaderRoute: typeof ApiImageStreamRouteImport
-      parentRoute: typeof ApiImageRoute
-    }
-    '/api/harness-protocol/$': {
-      id: '/api/harness-protocol/$'
-      path: '/api/harness-protocol/$'
-      fullPath: '/api/harness-protocol/$'
-      preLoaderRoute: typeof ApiHarnessProtocolSplatRouteImport
-      parentRoute: typeof rootRouteImport
+      fullPath: '/api/tts/stream'
+      preLoaderRoute: typeof ApiTtsStreamRouteImport
+      parentRoute: typeof ApiTtsRoute
     }
-    '/api/audio/stream': {
-      id: '/api/audio/stream'
+    '/api/video/stream': {
+      id: '/api/video/stream'
       path: '/stream'
-      fullPath: '/api/audio/stream'
-      preLoaderRoute: typeof ApiAudioStreamRouteImport
-      parentRoute: typeof ApiAudioRoute
+      fullPath: '/api/video/stream'
+      preLoaderRoute: typeof ApiVideoStreamRouteImport
+      parentRoute: typeof ApiVideoRoute
     }
   }
 }
@@ -3099,18 +3045,8 @@ const ApiVideoRouteWithChildren = ApiVideoRoute._addFileChildren(
 )
 
 const rootRouteChildren: RootRouteChildren = {
-  ApiAdapterConfigReasoningWireRoute: ApiAdapterConfigReasoningWireRoute,
-  ApiActivityTestRoute: ApiActivityTestRoute,
-  ActivityTestRoute: ActivityTestRoute,
-  ApiForeignClientToolRoute: ApiForeignClientToolRoute,
-  ApiForeignChunkEventsRoute: ApiForeignChunkEventsRoute,
-  ApiAnthropicTruncatedToolInputWireRoute:
-    ApiAnthropicTruncatedToolInputWireRoute,
-  ApiAnthropicSonnet55WireRoute: ApiAnthropicSonnet55WireRoute,
-  ApiAnthropicMaxTokensUsageRoute: ApiAnthropicMaxTokensUsageRoute,
-  ForeignClientToolRoute: ForeignClientToolRoute,
-  ForeignChunkEventsRoute: ForeignChunkEventsRoute,
   IndexRoute: IndexRoute,
+  ActivityTestRoute: ActivityTestRoute,
   ByokRoute: ByokRoute,
   ChatClientDefaultBridgeRoute: ChatClientDefaultBridgeRoute,
   ChatClientStreamProcessingRoute: ChatClientStreamProcessingRoute,
@@ -3123,6 +3059,8 @@ const rootRouteChildren: RootRouteChildren = {
   DevtoolsStructuredRoute: DevtoolsStructuredRoute,
   DevtoolsSubagentsRoute: DevtoolsSubagentsRoute,
   DevtoolsToolsRoute: DevtoolsToolsRoute,
+  ForeignChunkEventsRoute: ForeignChunkEventsRoute,
+  ForeignClientToolRoute: ForeignClientToolRoute,
   ForeignInterruptRoute: ForeignInterruptRoute,
   GenerationPersistenceResumeRoute: GenerationPersistenceResumeRoute,
   GenerationPersistenceServerRoute: GenerationPersistenceServerRoute,
@@ -3143,14 +3081,20 @@ const rootRouteChildren: RootRouteChildren = {
   WebMcpToolsRoute: WebMcpToolsRoute,
   WebsocketAdapterRoute: WebsocketAdapterRoute,
   ProviderFeatureRoute: ProviderFeatureRoute,
+  ApiActivityTestRoute: ApiActivityTestRoute,
+  ApiAdapterConfigReasoningWireRoute: ApiAdapterConfigReasoningWireRoute,
   ApiAnthropicBugTestRoute: ApiAnthropicBugTestRoute,
+  ApiAnthropicMaxTokensUsageRoute: ApiAnthropicMaxTokensUsageRoute,
   ApiAnthropicMultiTurnStructuredWireRoute:
     ApiAnthropicMultiTurnStructuredWireRoute,
   ApiAnthropicOpus5CombinedWireRoute: ApiAnthropicOpus5CombinedWireRoute,
   ApiAnthropicRedactedThinkingWireRoute: ApiAnthropicRedactedThinkingWireRoute,
   ApiAnthropicSkillsWireRoute: ApiAnthropicSkillsWireRoute,
+  ApiAnthropicSonnet55WireRoute: ApiAnthropicSonnet55WireRoute,
   ApiAnthropicStructuredUsageRoute: ApiAnthropicStructuredUsageRoute,
   ApiAnthropicThinkingOrderWireRoute: ApiAnthropicThinkingOrderWireRoute,
+  ApiAnthropicTruncatedToolInputWireRoute:
+    ApiAnthropicTruncatedToolInputWireRoute,
   ApiArktypeToolWireRoute: ApiArktypeToolWireRoute,
   ApiAudioRoute: ApiAudioRouteWithChildren,
   ApiBedrockConverseCacheRoute: ApiBedrockConverseCacheRoute,
@@ -3165,6 +3109,8 @@ const rootRouteChildren: RootRouteChildren = {
   ApiDurableTakeoverRoute: ApiDurableTakeoverRoute,
   ApiEmbeddingRoute: ApiEmbeddingRoute,
   ApiFileSourceWireRoute: ApiFileSourceWireRoute,
+  ApiForeignChunkEventsRoute: ApiForeignChunkEventsRoute,
+  ApiForeignClientToolRoute: ApiForeignClientToolRoute,
   ApiForeignInterruptRoute: ApiForeignInterruptRoute,
   ApiGeminiImageGaModelsRoute: ApiGeminiImageGaModelsRoute,
   ApiGeminiNativeImageWireRoute: ApiGeminiNativeImageWireRoute,
@@ -3230,6 +3176,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiSummarizeRoute: ApiSummarizeRoute,
   ApiTextFirstToolWireRoute: ApiTextFirstToolWireRoute,
   ApiToolCallLifecycleWireRoute: ApiToolCallLifecycleWireRoute,
+  ApiToolChoiceWireRoute: ApiToolChoiceWireRoute,
   ApiToolFirstTextWireRoute: ApiToolFirstTextWireRoute,
   ApiToolsTestRoute: ApiToolsTestRoute,
   ApiTranscriptionRoute: ApiTranscriptionRouteWithChildren,
diff --git a/testing/e2e/src/routes/api.chat.ts b/testing/e2e/src/routes/api.chat.ts
index d3790bfe40..d4fa2f89f5 100644
--- a/testing/e2e/src/routes/api.chat.ts
+++ b/testing/e2e/src/routes/api.chat.ts
@@ -167,6 +167,9 @@ export const Route = createFileRoute('/api/chat')({
                   : chat({
                       ...adapterOptions,
                       tools: config.tools,
+                      ...(config.toolChoice && {
+                        toolChoice: config.toolChoice,
+                      }),
                       modelOptions,
                       ...(config.reasoning && { reasoning: config.reasoning }),
                       systemPrompts,
diff --git a/testing/e2e/src/routes/api.tool-choice-wire.ts b/testing/e2e/src/routes/api.tool-choice-wire.ts
new file mode 100644
index 0000000000..f075493090
--- /dev/null
+++ b/testing/e2e/src/routes/api.tool-choice-wire.ts
@@ -0,0 +1,132 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { chat } from '@tanstack/ai'
+import { createAnthropicChat } from '@tanstack/ai-anthropic'
+import { getGuitars } from '@/lib/tools'
+
+const DUMMY_KEY = 'sk-ant-e2e-test-dummy-key'
+
+/** Models the spec drives through this route. */
+const WIRE_MODELS = ['claude-sonnet-4-5', 'claude-opus-5-5'] as const
+type WireModel = (typeof WIRE_MODELS)[number]
+
+/** Reads `model` from the request body. Defaults to `claude-sonnet-4-5`. */
+async function readModel(request: Request): Promise<WireModel> {
+  const body: unknown = await request.json().catch(() => null)
+  const model =
+    body && typeof body === 'object' && 'model' in body ? body.model : null
+  return WIRE_MODELS.find((known) => known === model) ?? 'claude-sonnet-4-5'
+}
+
+/**
+ * Wire-format verification for `chat({ toolChoice })` on Anthropic. POST
+ * `{ model }` to pick the model.
+ *
+ * aimock stores Anthropic requests in its journal in OpenAI shape and drops
+ * `tool_choice`, so the journal cannot show it. A custom `fetch` captures the
+ * outgoing request and answers with a synthetic Claude SSE stream, the same
+ * approach as `api.anthropic-opus-5-combined-wire.ts`. The stream has no
+ * tool call, so the run makes one request.
+ */
+
+/** Minimal Anthropic Messages stream with one text block. */
+function makeSyntheticAnthropicStream(
+  model: WireModel,
+): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder()
+  const events = [
+    {
+      type: 'message_start',
+      message: {
+        id: 'msg_tool_choice_wire',
+        type: 'message',
+        role: 'assistant',
+        content: [],
+        model,
+        stop_reason: null,
+        stop_sequence: null,
+        usage: { input_tokens: 5, output_tokens: 0 },
+      },
+    },
+    {
+      type: 'content_block_start',
+      index: 0,
+      content_block: { type: 'text', text: '' },
+    },
+    {
+      type: 'content_block_delta',
+      index: 0,
+      delta: { type: 'text_delta', text: 'Done.' },
+    },
+    { type: 'content_block_stop', index: 0 },
+    {
+      type: 'message_delta',
+      delta: { stop_reason: 'end_turn', stop_sequence: null },
+      usage: { output_tokens: 2 },
+    },
+    { type: 'message_stop' },
+  ]
+
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      for (const event of events) {
+        controller.enqueue(
+          encoder.encode(
+            `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`,
+          ),
+        )
+      }
+      controller.close()
+    },
+  })
+}
+
+export const Route = createFileRoute('/api/tool-choice-wire')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const model = await readModel(request)
+        const capturedBodies: Array<unknown> = []
+
+        /** Records the outgoing request and answers with the synthetic stream. */
+        const capturingFetch: typeof fetch = async (input, init) => {
+          const req =
+            input instanceof Request ? input : new Request(input, init)
+          capturedBodies.push(await req.json())
+          return new Response(makeSyntheticAnthropicStream(model), {
+            status: 200,
+            headers: {
+              'Content-Type': 'text/event-stream',
+              'Cache-Control': 'no-cache',
+            },
+          })
+        }
+
+        try {
+          for await (const _ of chat({
+            adapter: createAnthropicChat(model, DUMMY_KEY, {
+              fetch: capturingFetch,
+            }),
+            messages: [
+              {
+                role: 'user',
+                content: '[toolchoice] what guitars do you have in stock',
+              },
+            ],
+            tools: [getGuitars],
+            toolChoice: { type: 'tool', name: 'getGuitars' },
+          })) {
+            // Drain the stream.
+          }
+        } catch (error) {
+          return Response.json({
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+            capturedBodies,
+          })
+        }
+
+        return Response.json({ ok: true, capturedBodies })
+      },
+    },
+  },
+})
diff --git a/testing/e2e/tests/tool-choice.spec.ts b/testing/e2e/tests/tool-choice.spec.ts
new file mode 100644
index 0000000000..1638597316
--- /dev/null
+++ b/testing/e2e/tests/tool-choice.spec.ts
@@ -0,0 +1,125 @@
+import { test, expect } from './fixtures'
+import type { APIRequestContext } from '@playwright/test'
+
+/**
+ * Wire-format verification for `chat({ toolChoice })`.
+ *
+ * OpenAI runs through `/api/chat` and aimock. The `tool-choice` feature asks
+ * for the named tool `getGuitars`, and aimock's journal keeps `tool_choice`
+ * for Responses requests, so the spec reads it back from there.
+ *
+ * aimock stores Anthropic requests in OpenAI shape and drops `tool_choice`.
+ * The Anthropic cases use `/api/tool-choice-wire`, which captures the request
+ * body with a custom `fetch`.
+ */
+test.describe('tool choice — wire format', () => {
+  test('openai sends a named tool as a function tool_choice', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/chat', {
+      data: {
+        threadId: 'thread-tool-choice-1',
+        runId: 'run-tool-choice-1',
+        state: {},
+        messages: [
+          {
+            id: 'u1',
+            role: 'user',
+            content: '[toolchoice] what guitars do you have in stock',
+          },
+        ],
+        tools: [],
+        context: [],
+        forwardedProps: {
+          provider: 'openai',
+          feature: 'tool-choice',
+          testId,
+          aimockPort,
+        },
+      },
+    })
+    expect(
+      response.ok(),
+      `expected 200, got ${response.status()}: ${await response.text()}`,
+    ).toBe(true)
+    const text = await response.text()
+    expect(text).toContain('RUN_FINISHED')
+    expect(text).not.toContain('RUN_ERROR')
+
+    const bodies = await readCapturedBodies(request, aimockPort, testId)
+
+    // The first request of the run carries the caller's choice.
+    expect(bodies[0]).toHaveProperty('tool_choice', {
+      type: 'function',
+      name: 'getGuitars',
+    })
+  })
+
+  const anthropicCases = [
+    {
+      model: 'claude-sonnet-4-5',
+      label: 'forces the named tool',
+      expected: { type: 'tool', name: 'getGuitars' },
+    },
+    {
+      // This model rejects a forced tool, so the adapter falls back to auto.
+      model: 'claude-opus-5-5',
+      label: 'falls back to auto',
+      expected: { type: 'auto' },
+    },
+  ]
+
+  for (const { model, label, expected } of anthropicCases) {
+    test(`anthropic ${model} ${label}`, async ({ request }) => {
+      const response = await request.post('/api/tool-choice-wire', {
+        data: { model },
+      })
+      expect(response.ok()).toBe(true)
+      const payload: {
+        ok: boolean
+        error?: string
+        capturedBodies: Array<unknown>
+      } = await response.json()
+      expect(payload, payload.error).toMatchObject({ ok: true })
+
+      expect(payload.capturedBodies).toHaveLength(1)
+      expect(payload.capturedBodies[0]).toHaveProperty('tool_choice', expected)
+    })
+  }
+})
+
+/**
+ * Reads the request bodies this test's own run sent to aimock, oldest first.
+ *
+ * aimock is a singleton shared by every Playwright worker, so select this
+ * test's entries by the `X-Test-Id` header that `createTextAdapter` adds, the
+ * same as `provider-tool-dispatch-wire.spec.ts`.
+ */
+async function readCapturedBodies(
+  request: APIRequestContext,
+  aimockPort: number,
+  testId: string,
+): Promise<Array<unknown>> {
+  const response = await request.get(
+    `http://127.0.0.1:${aimockPort}/v1/_requests`,
+  )
+  const entries: Array<{
+    headers?: Record<string, string>
+    body: unknown
+  }> = await response.json()
+
+  const mine = entries.filter((entry) =>
+    Object.entries(entry.headers ?? {}).some(
+      ([key, value]) => key.toLowerCase() === 'x-test-id' && value === testId,
+    ),
+  )
+
+  expect(
+    mine,
+    `no aimock journal entry carried X-Test-Id "${testId}"`,
+  ).not.toHaveLength(0)
+
+  return mine.map((entry) => entry.body)
+}

From b8ba547e34fce23a09e10b7cc4e8e546fb487a31 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 17:09:25 +0200
Subject: [PATCH 254/286] docs(harness): sessions, waiting inputs, fork points,
 and the session index store

- New sessions page: list, rename, delete, fork, and the host status feed,
  on the server and the client.
- Inputs: cancel a waiting message or move it between steer and queue.
- Fork and reset: fork before or through a message, fork from the client,
  and at: null.
- Store reference: the SessionIndexStore contract and its conformance
  tests.
---
 docs/harness/fork-and-reset.md      |  49 ++++--
 docs/harness/inputs.md              |  44 +++++-
 docs/harness/sessions.md            | 224 ++++++++++++++++++++++++++++
 docs/persistence/store-reference.md | 129 +++++++++++++++-
 4 files changed, 426 insertions(+), 20 deletions(-)
 create mode 100644 docs/harness/sessions.md

diff --git a/docs/harness/fork-and-reset.md b/docs/harness/fork-and-reset.md
index 768760b09c..1a776f1ba9 100644
--- a/docs/harness/fork-and-reset.md
+++ b/docs/harness/fork-and-reset.md
@@ -40,7 +40,10 @@ export async function branch(threadId: string, messageId: string) {
 }
 ```
 
-`at` is the id of the last message to copy. Without `at`, the fork copies the whole transcript. The message ids stay the same, so `at` points at the same message in both threads.
+`at` is the id of the last message to copy. The message ids stay the same, so `at` points at the same message in both threads.
+
+- Without `at`, the fork copies the whole transcript.
+- With `at: null`, the fork copies no messages. It still copies the settings and the plugin config, so the new thread starts empty with the same setup.
 
 The fork copies:
 
@@ -52,34 +55,47 @@ The fork does not copy plugin state, pending interrupts, queued inputs, running
 
 If a thread waits for an approval, fork it at a message before the tool call. A fork of the whole transcript copies the tool call, but the fork has no interrupt to answer it.
 
-The handler has no fork route. Call `host.fork` from your own route, then open the new thread on the client:
+## Fork before or through a message
+
+A user edits an earlier message and sends it again. The fork must stop before that message. `host.sessions.fork` takes the cut as `{ before: id }` or `{ through: id }`, and it writes the new thread into the [session index](./sessions):
+
+```ts group=harness-fork-and-reset
+export async function editAndResend(threadId: string, messageId: string, text: string) {
+  const entry = await host.sessions.fork(assistant, threadId, { before: messageId })
+  const fork = await host.open(assistant, { threadId: entry.threadId })
+  await fork.prompt(text)
+  return entry.threadId
+}
+```
+
+- `{ before: id }` copies the messages before `id`. Before the first message, the fork has no messages, but it keeps the settings.
+- `{ through: id }` copies the messages up to and including `id`, as `at` does.
+- The host picks the new thread id. The new index entry has the title of the old one plus ` (fork)`, and the same owner.
+- `host.sessions.fork` calls `host.fork`, so it copies the same things as `host.fork`.
+
+## Fork from the client
+
+The handler forks with `POST sessions` and the body `{ op: 'fork', threadId, before }` or `{ op: 'fork', threadId, through }`. The client calls it with `forkSession`, then opens the new thread:
 
 ```ts group=harness-fork-and-reset-client
 import { createHarnessClient } from '@tanstack/ai-harness/client'
 import type { assistant } from './harness'
 
-// The new thread id comes from your route that calls host.fork.
-const response = await fetch('/api/branch', {
-  method: 'POST',
-  body: JSON.stringify({ threadId: 'support-1', messageId: 'msg-7' }),
+const client = createHarnessClient<typeof assistant>({
+  url: '/api/harness',
+  threadId: 'support-1',
 })
-const body: unknown = await response.json()
-if (
-  typeof body !== 'object' ||
-  body === null ||
-  !('threadId' in body) ||
-  typeof body.threadId !== 'string'
-) {
-  throw new Error('The branch route sent no thread id.')
-}
+const entry = await client.forkSession('support-1', { through: 'msg-7' })
 
 const branch = createHarnessClient<typeof assistant>({
   url: '/api/harness',
-  threadId: body.threadId,
+  threadId: entry.threadId,
 })
 await branch.prompt('Try a shorter answer.')
 ```
 
+The route needs `stores.sessions` on the host. A user can fork only a thread that the user owns in the index. For another thread, the handler answers `404`.
+
 ## Reset with a handoff note
 
 `session.reset(note)` starts a fresh model context. From the next turn, the model sees only the note and what comes after the reset:
@@ -114,5 +130,6 @@ What the reset does:
 ## What you have now
 
 - A branch of a thread at any message, with its settings and media.
+- A fork from the browser, before or through a message.
 - A fresh model context with a handoff note, and the whole history in the transcript.
 - A marker in the transcript that your UI can show as a line.
diff --git a/docs/harness/inputs.md b/docs/harness/inputs.md
index 52f55ad593..93af922049 100644
--- a/docs/harness/inputs.md
+++ b/docs/harness/inputs.md
@@ -2,7 +2,7 @@
 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, and ask the session how an input ended, also after a restart."
+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
@@ -10,6 +10,8 @@ keywords:
   - idempotency
   - settled
   - steer
+  - cancelInput
+  - setDelivery
 ---
 
 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.
@@ -119,6 +121,45 @@ Waiting `steer` inputs join before each model call, in the order they arrived. T
 
 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('req-47', '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('req-47', '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.
+
 ## 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.
@@ -183,4 +224,5 @@ On `POST run`, the AG-UI `forwardedProps` of the request are the `context`, for
 - 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.
 - Context from the client that tools read, also after a restart.
diff --git a/docs/harness/sessions.md b/docs/harness/sessions.md
new file mode 100644
index 0000000000..264b12e3a1
--- /dev/null
+++ b/docs/harness/sessions.md
@@ -0,0 +1,224 @@
+---
+title: List, rename, and fork sessions
+id: harness-sessions
+order: 4
+description: "Show a sidebar of past chats with titles and a live status. Rename, remove, and fork a chat from the server or the browser."
+keywords:
+  - tanstack ai
+  - harness
+  - sessions
+  - session index
+  - sidebar
+  - host events
+---
+
+Your app needs a sidebar of past chats. It shows the newest chat first, a title for each chat, and a mark on a chat that runs or waits for an answer. The host keeps a session index for this, with one entry per thread. It writes the entry when a thread opens and after each turn.
+
+## Turn on the session index
+
+Give the host a `sessions` store. `memoryPersistence()` has one. The `title()` plugin gives each session a title:
+
+```ts group=harness-sessions
+import {
+  createHarnessHandler,
+  createHarnessHost,
+  defineHarness,
+} from '@tanstack/ai-harness'
+import { title } from '@tanstack/ai-harness/plugins'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { openaiText } from '@tanstack/ai-openai'
+
+export const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-5.6'),
+  plugins: () => [title({ adapter: openaiText('gpt-5.4-nano') })],
+})
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+
+// Your own lookup: a session token to a user.
+const users = new Map([['Bearer token-ada', { id: 'ada' }]])
+
+export const handler = createHarnessHandler({
+  host,
+  harness: assistant,
+  authorize: (request) => users.get(request.headers.get('authorization') ?? '') ?? null,
+})
+
+const session = await host.open(assistant, {
+  threadId: 'chat-1',
+  principal: { id: 'ada' },
+})
+await session.prompt('Plan a trip to Lisbon.')
+console.log((await host.sessions.get('chat-1'))?.principal) // { id: 'ada' }
+```
+
+What an entry holds:
+
+- `title`: the plugin writes it at the first turn, from the first user message. The turn does not wait for it. If the call fails, the next turn tries again.
+- `updatedAt`: the time of the last change. The list sorts by it.
+- `principal`: the owner. This is the user who opened the thread first.
+- `usage`: the token totals of the thread.
+- `parentThreadId`: the parent thread of a child session, for example a subagent run.
+
+A durable host takes `sessions` next to `log`:
+
+```ts group=harness-sessions
+import { memoryLogStore } from '@tanstack/ai-persistence'
+
+const { runs, sessions } = memoryPersistence().stores
+const durableHost = createHarnessHost({
+  persistence: { stores: { log: memoryLogStore(), runs, sessions } },
+})
+```
+
+Without `stores.sessions`, `list` is empty, `get` returns `undefined`, and `rename` and `delete` write nothing. The HTTP routes on this page then find no sessions. To write your own store, read the [`SessionIndexStore` contract](../persistence/store-reference#sessionindexstore).
+
+## List the sessions of a user
+
+```ts group=harness-sessions
+const page = await host.sessions.list({ principal: { id: 'ada' }, limit: 20 })
+for (const entry of page.entries) {
+  console.log(entry.threadId, entry.title ?? 'New chat')
+}
+
+if (page.truncated) {
+  const next = await host.sessions.list({
+    principal: { id: 'ada' },
+    limit: 20,
+    cursor: page.cursor,
+  })
+  console.log(next.entries.length)
+}
+```
+
+- The newest `updatedAt` comes first.
+- By default, the list has only top-level sessions. Pass `parentThreadId: 'chat-1'` to get the child sessions of `chat-1`.
+- With `limit`, a page that has more entries after it has `truncated: true` and a `cursor`. Pass the `cursor` to get the next page.
+- If `principal` has a `tenantId`, the tenant of the entry must match too.
+
+In the browser, call `listSessions`. The handler lists only the sessions of the user that `authorize` returns, and only the threads that `canAccess` lets in:
+
+```ts group=harness-sessions-client
+import { createHarnessClient } from '@tanstack/ai-harness/client'
+import type { assistant } from './harness'
+
+const client = createHarnessClient<typeof assistant>({
+  url: '/api/harness',
+  threadId: 'chat-1',
+  headers: { authorization: 'Bearer token-ada' },
+})
+
+const page = await client.listSessions({ limit: 20 })
+const next = page.truncated
+  ? await client.listSessions({ limit: 20, cursor: page.cursor })
+  : undefined
+```
+
+The session calls of the client do not use its `threadId`. Each call names its thread in its own arguments.
+
+## Fork a session
+
+A fork copies a chat into a new chat, up to a message. Use it to try another answer, or to edit a message and send it again:
+
+```ts group=harness-sessions
+const [first] = await session.transcript()
+if (!first?.id) throw new Error('The chat has no messages.')
+
+const forked = await host.sessions.fork(assistant, 'chat-1', { before: first.id })
+const fork = await host.open(assistant, { threadId: forked.threadId })
+await fork.prompt('Plan a trip to Porto.')
+```
+
+- `{ through: id }` copies the messages up to and including `id`.
+- `{ before: id }` copies the messages before `id`. A fork before the first message has no messages, but it keeps the settings.
+- The host picks the new thread id. The new entry has the title of the old one plus ` (fork)`, and the same owner.
+- If the transcript has no message with that id, `fork` throws.
+
+In the browser, call `forkSession`, then open the new thread:
+
+```ts group=harness-sessions-client
+const forked = await client.forkSession('chat-1', { through: 'msg-7' })
+
+const fork = createHarnessClient<typeof assistant>({
+  url: '/api/harness',
+  threadId: forked.threadId,
+  headers: { authorization: 'Bearer token-ada' },
+})
+await fork.prompt('Make the plan shorter.')
+```
+
+What a fork copies, and what it does not copy: [Fork and reset a thread](./fork-and-reset#fork-a-thread-at-a-message).
+
+## Rename and remove a session
+
+```ts group=harness-sessions
+await host.sessions.rename(forked.threadId, 'Porto trip')
+await host.sessions.delete('chat-1')
+```
+
+- `rename` resolves to the changed entry. For a thread with no entry, it resolves to `undefined`.
+- `delete` removes the index entry only. The transcript, the log, the media, and the settings of the thread stay in their stores.
+- After `delete`, the turns of the open session do not write the entry again. If the thread opens again after a restart, the host writes a new entry for it.
+
+In the browser:
+
+```ts group=harness-sessions-client
+await client.renameSession(forked.threadId, 'Porto trip')
+await client.deleteSession('chat-1')
+```
+
+A user can change only the sessions that the user owns. For a thread of another user, the handler answers `404`. For a thread that `canAccess` refuses, it answers `403`. The client calls throw for both.
+
+## Show a live status
+
+`host.events()` yields the changes of status and of the index. First it yields the current status of each open session:
+
+```ts group=harness-sessions
+const stop = new AbortController()
+
+async function watch() {
+  for await (const event of host.events({ signal: stop.signal })) {
+    if (event.type === 'status') console.log(event.threadId, event.status)
+    if (event.type === 'session') console.log('changed', event.entry.title)
+    if (event.type === 'session-deleted') console.log('removed', event.threadId)
+  }
+}
+void watch()
+```
+
+- `status`: `running` (an operation runs), `waiting` (a question or an approval waits for an answer), or `idle`. `at` is the time of the change.
+- `session`: the host wrote an entry, for a new session, the end of a turn, a rename, or a fork. `entry` is the new entry.
+- `session-deleted`: the host removed an entry. `entry` is the removed entry.
+
+Each host reports only the sessions that are open in it. A session with no status event is not open, so show it as idle.
+
+`host.close()` does not end the readers of `events()`. Abort the signal of each reader before you close the host. If you do not abort it, the loop waits forever:
+
+```ts group=harness-sessions
+stop.abort()
+await host.close()
+```
+
+In the browser, read the same feed with `hostEvents`:
+
+```ts group=harness-sessions-client
+const statuses = new Map<string, 'idle' | 'running' | 'waiting'>()
+const stop = new AbortController()
+
+for await (const event of client.hostEvents({ signal: stop.signal })) {
+  if (event.type === 'status') statuses.set(event.threadId, event.status)
+  if (event.type === 'session-deleted') statuses.delete(event.threadId)
+}
+```
+
+- The handler sends only the threads that the user owns in the index and that `canAccess` lets in. So the feed needs `stores.sessions`.
+- The stream ends when the signal aborts or the server closes it. It does not reconnect. To reconnect, call `hostEvents()` again. The current statuses come first again.
+
+To watch the sessions of many machines from a phone, without a screen of your own, use the [dashboard](./dashboard).
+
+## What you have now
+
+- A sidebar of past chats, newest first, with a title for each.
+- Rename, remove, and fork, from the server and from the browser.
+- A status for each chat that stays current.
diff --git a/docs/persistence/store-reference.md b/docs/persistence/store-reference.md
index 377b76ef35..90e4d33ab7 100644
--- a/docs/persistence/store-reference.md
+++ b/docs/persistence/store-reference.md
@@ -18,6 +18,7 @@ there is no separate enable list.
 | `blobs` | File bytes. Needs `artifacts`. | `withGenerationPersistence`, portable snapshots |
 | `log` | Append-only session log per thread. | Durable harness hosts, with `runs` or `leases` |
 | `leases` | Leases for harness turns, from a system that already has them. | Durable harness hosts, instead of `runs` |
+| `sessions` | One index entry per thread, for a list of sessions. | Harness hosts (`host.sessions`) |
 
 Named groupings of the chat stores (`ChatTranscriptStores`, `ChatPersistenceStores`,
 `ChatWithInterruptsStores`) are covered in [Controls](./controls).
@@ -680,6 +681,127 @@ function createMemoryLeases(): LeaseStore {
 To wire `leases` into a host, and to set `lease.renewMs` and `lease.ttlMs`, see
 [Use your own leases](../harness/durable-sessions#use-your-own-leases).
 
+## SessionIndexStore
+
+A harness host keeps one entry per thread in this store: the title, the owner, the
+time of the last change, and the token totals. The host reads it for
+`host.sessions` and for the `sessions` routes of the handler. The index holds no
+messages. The data of each thread stays in the stores that hold it.
+
+```ts
+interface SessionIndexEntry {
+  threadId: string
+  harness?: string // the `name` of the harness that runs the thread
+  title?: string
+  parentThreadId?: string // a child session, for example `subagent:<runId>`
+  parentToolCallId?: string // the tool call in the parent thread that started it
+  createdAt: number // epoch ms, the first open
+  updatedAt: number // epoch ms, the last change
+  pinned?: boolean
+  principal?: { id: string; tenantId?: string } // the owner
+  usage?: {
+    turns: number // model calls
+    promptTokens: number
+    completionTokens: number
+    totalTokens: number
+    cachedTokens: number
+    cacheWriteTokens: number
+    cost?: number // USD, when a plugin counts it
+  }
+  metadata?: Record<string, unknown>
+}
+
+interface SessionIndexListOptions {
+  limit?: number
+  cursor?: string
+  parentThreadId?: string | null
+  principal?: { id: string; tenantId?: string }
+}
+
+interface SessionIndexPage {
+  entries: Array<SessionIndexEntry>
+  cursor?: string // only when `truncated`
+  truncated?: boolean
+}
+
+interface SessionIndexStore {
+  upsert(entry: SessionIndexEntry): Promise<void>
+  get(threadId: string): Promise<SessionIndexEntry | undefined>
+  list(options?: SessionIndexListOptions): Promise<SessionIndexPage>
+  delete(threadId: string): Promise<void>
+}
+```
+
+Rules for `upsert`, `get`, and `delete`:
+
+- `upsert` replaces the whole entry for `entry.threadId`. A field that the new entry
+  does not have is gone. Do not merge. To change one field, the host reads the entry
+  and writes a changed copy, one change at a time for each thread.
+- `get` returns `undefined` for an unknown thread, not `null`.
+- `delete` removes the entry only. The messages, the log, and the other data of the
+  thread stay. For an unknown thread, `delete` does nothing.
+
+Rules for `list`:
+
+- Sort by `updatedAt`, the newest first. Entries with the same `updatedAt` go in
+  `threadId` order. `pinned` gets no special place.
+- `parentThreadId: 'x'` returns only the entries whose parent is `x`. `null` returns
+  only the entries with no parent. Without it, the parent does not filter.
+- `principal` returns only the entries of that owner id. With a `tenantId`, the
+  tenant must match too. An entry without a `principal` never matches.
+- Without `limit`, return every entry that matches. With `limit`, when more entries
+  match, return `truncated: true` and a `cursor`. The last page has no `cursor`.
+- With the `cursor` of a page, return the entries after the last entry of that page.
+  The format of the cursor is yours. An entry that changes between two pages can
+  move in the order.
+
+The reference implementation is `MemorySessionIndexStore` in
+`packages/ai-persistence/src/memory.ts`. `memoryPersistence().stores.sessions` is an
+instance of it. Its cursor is `<updatedAt>:<threadId>` of the last entry of a page.
+
+### Prove it with the conformance suite
+
+The `sessions` cases of `runPersistenceConformance` run when your persistence has
+`stores.sessions`. A persistence without it needs no `skip` entry. To check the store
+alone, skip the stores that the suite reads by default:
+
+```ts
+import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
+import { mySessionIndex } from './session-index'
+
+runPersistenceConformance(
+  'my session index',
+  () => ({ stores: { sessions: mySessionIndex() } }),
+  {
+    skip: [
+      'messages',
+      'activities',
+      'runs',
+      'interrupts',
+      'metadata',
+      'generationRuns',
+      'artifacts',
+      'blobs',
+    ],
+  },
+)
+```
+
+If your persistence already runs the suite, add `sessions` to it, and the cases run
+there. The suite checks that:
+
+- `get` returns every field of an upserted entry, and `undefined` for an unknown
+  thread.
+- A second `upsert` replaces the whole entry.
+- `list` sorts the newest first, sorts ties by `threadId`, and pages with `limit` and
+  `cursor`.
+- `list` filters by `parentThreadId` (also `null`) and by `principal`, with the
+  tenant rule.
+- `delete` removes one entry, and does nothing for an unknown thread.
+
+To see how an app lists, renames, and forks sessions with this store, read
+[List, rename, and fork sessions](../harness/sessions).
+
 ## How the records relate
 
 The thread is not a table of its own: it exists as the `thread_id` the other records
@@ -737,12 +859,13 @@ erDiagram
 
 Each store has a `define*Store` helper (`defineMessageStore`, `defineRunStore`,
 `defineInterruptStore`, `defineMetadataStore`, `defineGenerationRunStore`,
-`defineArtifactStore`, `defineBlobStore`, `defineLogStore`). They compose into
+`defineArtifactStore`, `defineBlobStore`, `defineLogStore`,
+`defineSessionIndexStore`). They compose into
 `defineAIPersistence`, which tracks exact presence: the stores you passed autocomplete
 on `persistence.stores`, and reading one you did not pass is a compile error.
 
 The keys in the table at the top are the only ones `stores` accepts, together with the
-harness keys `inbox`, `credentials`, `log`, and `leases`. Anything else throws
+harness keys `inbox`, `credentials`, `log`, `leases`, and `sessions`. Anything else throws
 `Unknown AIPersistence store key` at construction.
 
 To annotate the value instead, use a named shape:
@@ -756,4 +879,4 @@ To annotate the value instead, use a named shape:
 
 - [Build a chat adapter](./build-your-own-chat-adapter): these contracts implemented against SQLite.
 - [Build a generation adapter](./build-your-own-generation-adapter): the generation half.
-- [Build your own adapter](./build-your-own-adapter#verify-with-the-conformance-suite): check an implementation against the conformance suite.
+- [Build your own adapter](./build-your-own-adapter#prove-it-with-the-conformance-suite): check an implementation against the conformance suite.

From ceacede613f504c2e14315f9e60c7810a2e272b7 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 17:11:59 +0200
Subject: [PATCH 255/286] fix(ai-bedrock): send the tools with auto for none
 after a tool call

Converse has no none tool choice, and Bedrock rejects tool blocks in the
history without a tool config. So toolChoice 'none' sends the tools with
auto when the messages have a toolUse or toolResult block. Without them,
it still sends no tool config.
---
 .../ai-bedrock/src/adapters/converse-text.ts  | 22 +++++---
 .../ai-bedrock/tests/tool-choice-wire.test.ts | 50 ++++++++++++++++++-
 2 files changed, 64 insertions(+), 8 deletions(-)

diff --git a/packages/ai-bedrock/src/adapters/converse-text.ts b/packages/ai-bedrock/src/adapters/converse-text.ts
index 8f9eabeaf4..8ce0ced1b5 100644
--- a/packages/ai-bedrock/src/adapters/converse-text.ts
+++ b/packages/ai-bedrock/src/adapters/converse-text.ts
@@ -839,16 +839,26 @@ export class BedrockConverseTextAdapter<
     )
 
     // `chat({ toolChoice })`. Converse has no `none` choice, so `none` sends
-    // no tool config. Claude rejects a forced tool while thinking is on (only
-    // Claude gets thinking fields), and some Claude models reject it on every
-    // request. Then a forced choice falls back to auto.
+    // no tool config. But Bedrock rejects `toolUse` or `toolResult` blocks
+    // without a tool config, so with tool blocks in the history `none` sends
+    // the tools with auto (the model can still call one). Claude rejects a
+    // forced tool while thinking is on (only Claude gets thinking fields), and
+    // some Claude models reject it on every request. Then a forced choice
+    // falls back to auto.
     const canForceTool =
       additionalModelRequestFields === undefined &&
       !CLAUDE_NO_FORCED_TOOL_MODELS.some((name) => this.model.includes(name))
+    const hasToolBlocks = messages.some((message) =>
+      message.content?.some((block) => block.toolUse || block.toolResult),
+    )
     const toolChoice =
-      canForceTool || options.toolChoice === 'none'
-        ? options.toolChoice
-        : 'auto'
+      options.toolChoice === 'none'
+        ? hasToolBlocks
+          ? 'auto'
+          : 'none'
+        : canForceTool
+          ? options.toolChoice
+          : 'auto'
     const toolConfig = options.tools
       ? toToolConfig(convertTools(options.tools), toolChoice)
       : undefined
diff --git a/packages/ai-bedrock/tests/tool-choice-wire.test.ts b/packages/ai-bedrock/tests/tool-choice-wire.test.ts
index 7ed5f5d125..0e40b998c3 100644
--- a/packages/ai-bedrock/tests/tool-choice-wire.test.ts
+++ b/packages/ai-bedrock/tests/tool-choice-wire.test.ts
@@ -14,6 +14,22 @@ const weatherTool: Tool = {
   name: 'lookup_weather',
   description: 'Return the forecast for a location',
 }
+// A finished tool call. Converse gets a `toolUse` and a `toolResult` block.
+const toolHistory: Array<ModelMessage> = [
+  ...messages,
+  {
+    role: 'assistant',
+    content: null,
+    toolCalls: [
+      {
+        id: 'call_1',
+        type: 'function',
+        function: { name: 'lookup_weather', arguments: '{"location":"Paris"}' },
+      },
+    ],
+  },
+  { role: 'tool', toolCallId: 'call_1', content: 'Sunny' },
+]
 const named: ToolChoice = { type: 'tool', name: 'lookup_weather' }
 const forcedChoices: Array<{ label: string; toolChoice: ToolChoice }> = [
   { label: 'required', toolChoice: 'required' },
@@ -33,7 +49,9 @@ const noForcedToolModels = [
   'eu.anthropic.claude-mythos-5-1-v1:0',
 ]
 
-type ConverseRequest = Pick<TextOptions, 'tools' | 'toolChoice' | 'reasoning'>
+type ConverseRequest = Partial<
+  Pick<TextOptions, 'messages' | 'tools' | 'toolChoice' | 'reasoning'>
+>
 
 /**
  * Runs one Converse stream call through the installed AWS SDK and returns the
@@ -119,7 +137,7 @@ describe('Bedrock Converse toolChoice', () => {
     expect(body).toHaveProperty('toolConfig.toolChoice', { auto: {} })
   })
 
-  it('sends no tools and no toolConfig for none', async () => {
+  it('sends no tools and no toolConfig for none without tool history', async () => {
     const body = await converseBody(nova, {
       tools: [weatherTool],
       toolChoice: 'none',
@@ -128,6 +146,25 @@ describe('Bedrock Converse toolChoice', () => {
     expect(body).not.toHaveProperty('toolConfig')
   })
 
+  // Bedrock rejects toolUse and toolResult blocks without a toolConfig.
+  it('sends the tools with auto for none after a tool call', async () => {
+    const body = await converseBody(nova, {
+      messages: toolHistory,
+      tools: [weatherTool],
+      toolChoice: 'none',
+    })
+    expect(body).toHaveProperty(
+      'messages.1.content.0.toolUse.name',
+      'lookup_weather',
+    )
+    expect(body).toHaveProperty('messages.2.content.0.toolResult.toolUseId')
+    expect(body).toHaveProperty('toolConfig.toolChoice', { auto: {} })
+    expect(body).toHaveProperty(
+      'toolConfig.tools.0.toolSpec.name',
+      'lookup_weather',
+    )
+  })
+
   it('sends no toolConfig when the request has no tools', async () => {
     const body = await converseBody(nova, { toolChoice: 'required' })
     expect(body).toHaveProperty('messages')
@@ -191,6 +228,15 @@ describe('Bedrock Converse toolChoice', () => {
     })
     expect(body).not.toHaveProperty('toolConfig')
   })
+
+  it('on a Claude model that rejects a forced tool, sends auto for none after a tool call', async () => {
+    const body = await converseBody('us.anthropic.claude-opus-5-5-v1:0', {
+      messages: toolHistory,
+      tools: [weatherTool],
+      toolChoice: 'none',
+    })
+    expect(body).toHaveProperty('toolConfig.toolChoice', { auto: {} })
+  })
 })
 
 // The Bedrock OpenAI-compatible adapters inherit the openai-base mapping.

From c824007d9dbe1e12f7469d17c6456fa34cf2e180 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 17:15:19 +0200
Subject: [PATCH 256/286] docs(harness): dashboard restarts, opening a thread,
 and toolExecution

- Dashboard: a saved token lasts while the dashboard process runs. After a
  restart the agent pairs again, or calls onError. Open a thread from a host
  row, and the allowRemoteStart limits.
- Turn control: run tools one at a time with toolExecution: 'sequential'.
---
 docs/harness/dashboard.md    | 73 +++++++++++++++++++++++++++++++++++-
 docs/harness/turn-control.md | 52 ++++++++++++++++++++++++-
 2 files changed, 121 insertions(+), 4 deletions(-)

diff --git a/docs/harness/dashboard.md b/docs/harness/dashboard.md
index f30c6f197c..9958fb5d7f 100644
--- a/docs/harness/dashboard.md
+++ b/docs/harness/dashboard.md
@@ -9,6 +9,8 @@ keywords:
   - dashboard
   - mobile
   - relay
+  - pairing
+  - allowRemoteStart
 ---
 
 Your agent runs on a laptop, a server, or a CI runner, and it stops to ask for approval while you are away from that terminal. The dashboard shows every connected session in a browser or on your phone. You approve tools, answer questions, and send prompts from there. Agents connect out to the dashboard, so they need no open port.
@@ -51,7 +53,9 @@ const connection = await connectDashboard({
 
 ## 3. Pair it
 
-The first time, the agent prints a pairing code. Approve the code in the dashboard under "Pairing requests". The agent gets a host token. Pass it as `token` (or `HARNESS_DASHBOARD_TOKEN` for the CLI) to skip pairing next time. Revoke a host in the dashboard to cut it off.
+The first time, the agent prints a pairing code. Approve the code in the dashboard under "Pairing requests". The agent gets a host token. Pass it as `token` (or `HARNESS_DASHBOARD_TOKEN` for the CLI) to skip pairing next time. Revoke a host in the dashboard to remove its access.
+
+A saved token works while the same dashboard process runs. The dashboard keeps tokens in memory, so a restart makes them invalid. See [When the dashboard restarts](#when-the-dashboard-restarts).
 
 ## What you can do in the dashboard
 
@@ -59,11 +63,76 @@ The first time, the agent prints a pairing code. Approve the code in the dashboa
 - Read the messages and tool calls of a session as they stream.
 - Approve or reject tool calls, and answer questions from plugins.
 - Send a prompt, steer a running turn, or stop it.
+- Open a thread on a host by its id. See [Open a thread](#open-a-thread).
 
-Inputs for an offline host wait at the dashboard for 10 minutes and reach the host when it reconnects. Set `allowRemoteStart: true` in `connectDashboard` to let the dashboard open new sessions on the host.
+Inputs for an offline host wait at the dashboard for 10 minutes and reach the host when it reconnects.
 
 On a phone, open the dashboard and add it to the home screen. It works as an installed web app.
 
+To show a session list and a live status in your own app, use the session index of the host. See [List, rename, and fork sessions](./sessions).
+
+## Open a thread
+
+The dashboard shows the threads in `threads`. To watch another thread, or to start a new one from your phone, open it by its id.
+
+Set `allowRemoteStart: true` in `connectDashboard`:
+
+```ts group=harness-dashboard
+const remote = await connectDashboard({
+  host,
+  harness: studio,
+  url: 'http://127.0.0.1:8790',
+  threads: ['main'],
+  allowRemoteStart: true,
+  onPairingCode: (code) => console.log(`Approve ${code} in the dashboard`),
+})
+```
+
+Then open the thread in the dashboard:
+
+1. Find the host under "Hosts".
+2. Type a thread id in the "Thread id" field.
+3. Click "Open".
+
+The thread view opens. For a new thread, send a prompt to start it. If the host is offline, the view shows "Queued: the host is offline." The host opens the thread if it reconnects within 10 minutes.
+
+Know these limits:
+
+- The form shows on every host. A host does not tell the dashboard if it allows remote start.
+- The dashboard sends the open request to the host and does not wait for an answer. A host without `allowRemoteStart` ignores it. Then the host refuses the first input that you send, and the view shows "Refused: remote_start_disabled".
+- A thread in `threads`, or a thread that you attach with `connection.attach(threadId)`, opens without `allowRemoteStart`.
+- The CLI does not set `allowRemoteStart`. It opens only its own thread: the `--thread` value, `main` by default.
+
+## When the dashboard restarts
+
+The dashboard keeps host tokens in memory. After a restart, it refuses each saved token with a `401`. What the agent does next depends on `onPairingCode`:
+
+- With `onPairingCode`, the agent pairs again. It calls `onPairingCode` with a new code. After you approve the code, it calls `onToken` with the new token.
+- Without `onPairingCode`, the connection stops, and the agent calls `onError`.
+
+If the agent starts with a refused token and has `onPairingCode`, `connectDashboard` waits until you approve the new code. The CLI sets `onPairingCode`, so it prints a new code, then a new token to save.
+
+To stop and report the error, set `onError` and do not set `onPairingCode`:
+
+```ts group=harness-dashboard
+const savedToken = process.env.HARNESS_DASHBOARD_TOKEN
+if (!savedToken) throw new Error('Set HARNESS_DASHBOARD_TOKEN first.')
+
+const strict = await connectDashboard({
+  host,
+  harness: studio,
+  url: 'http://127.0.0.1:8790',
+  token: savedToken,
+  onError: (error) => console.error(`Pair this host again: ${error.message}`),
+})
+```
+
+`connection.token` always holds the current host token. It changes when the agent pairs again.
+
+A revoked host also gets a `401`. If it has `onPairingCode`, it asks to pair again, and a new request shows under "Pairing requests". If you do not approve the request, the host does not connect. Each request expires after 10 minutes, and then the host asks again. To stop the requests, call `connection.close()` on that host, or stop the agent.
+
 ## What you have now
 
 - Your sessions on any screen, with approvals and prompts a tap away.
+- Threads that you open from the dashboard, on hosts that allow it.
+- Agents that pair again after a dashboard restart, or that stop and report it.
diff --git a/docs/harness/turn-control.md b/docs/harness/turn-control.md
index 0b0cde331f..ce1a098129 100644
--- a/docs/harness/turn-control.md
+++ b/docs/harness/turn-control.md
@@ -2,7 +2,7 @@
 title: Control how a turn ends
 id: harness-turn-control
 order: 4
-description: "Send the model back to work when it stops too soon, retry model errors, choose which waiting messages join a running turn, and give one prompt its own model and tools."
+description: "Send the model back to work when it stops too soon, retry model errors, choose which waiting messages join a running turn, run tools one at a time, and give one prompt its own model and tools."
 keywords:
   - tanstack ai
   - harness
@@ -14,11 +14,12 @@ keywords:
   - steer
   - overrides
   - TurnOverrides
+  - toolExecution
 ---
 
 A model can stop before the job is done: it writes a nice answer and forgets to call `post_message`. A provider can answer 503 in the middle of a turn. A user can send three messages while the agent works, and one of them must not join. The `turn` options of the harness give you a hook for each case.
 
-One job can also need its own model or tools. Pass `overrides` to the prompt to [give it its own settings](#give-one-prompt-its-own-settings).
+One job can also need its own model or tools. Pass `overrides` to the prompt to [give it its own settings](#give-one-prompt-its-own-settings). Two tools of one model call can need to run one after the other. Set [`toolExecution`](#run-tools-one-at-a-time) on the harness.
 
 ## Send the model back to work
 
@@ -165,6 +166,52 @@ const selective = defineHarness({
 
 Tools or system prompts that a plugin or a middleware adds during a turn keep the prompt cache on models with a mid-conversation channel. See [Mid-conversation changes in a harness](../advanced/mid-conversation-changes#in-a-harness).
 
+## Run tools one at a time
+
+The model can call several server tools in one model call. By default, they run at the same time. Some tools must not overlap, for example a tool that writes a file and a tool that runs the tests. Set `toolExecution: 'sequential'` on the harness:
+
+```ts group=harness-turn-control-tools
+import { toolDefinition } from '@tanstack/ai'
+import { defineHarness } from '@tanstack/ai-harness'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+const writeFile = toolDefinition({
+  name: 'write_file',
+  description: 'Write a file',
+  inputSchema: z.object({ path: z.string(), content: z.string() }),
+}).server(async ({ path }) => ({ written: path }))
+
+const runTests = toolDefinition({
+  name: 'run_tests',
+  description: 'Run the test suite',
+  inputSchema: z.object({}),
+}).server(async () => ({ passed: true }))
+
+const coder = defineHarness({
+  name: 'acme/coder',
+  adapter: openaiText('gpt-6.1-sol'),
+  tools: [writeFile, runTests],
+  toolExecution: 'sequential',
+})
+```
+
+| Value | What it does |
+|---|---|
+| `'parallel'` (default) | Prepares each call in call order: the input check, the approval check, and `onBeforeToolCall`. Then the server tools start together. |
+| `'sequential'` | Runs one call at a time, in call order. Each call finishes `onBeforeToolCall`, its run, and `onAfterToolCall` before the next call starts. |
+
+With both values, the model gets the results in the order of its calls. Client tools do not change.
+
+Use `'sequential'` when:
+
+- a tool must see the changes of an earlier tool in the same model call, for example `run_tests` after `write_file`.
+- two identical calls must share one [`toolCacheMiddleware`](../advanced/built-in-middleware#toolcachemiddleware) entry. When they run at the same time, both calls miss the cache.
+
+Keep `'parallel'` for slow tools that do not depend on each other. Then a model call with three web fetches takes as long as the slowest fetch.
+
+The setting applies to every turn of the harness. `overrides` cannot change it for one prompt. To set it on `chat()` without a harness, see [Run tools one at a time](../tools/tools#run-tools-one-at-a-time).
+
 ## Give one prompt its own settings
 
 Most prompts are fine with the harness settings. One job can need more: a stronger model for a review, more reasoning, or a tool that only this job uses. Pass `overrides` to `session.prompt` or `session.followUp`:
@@ -233,4 +280,5 @@ To keep a model or instructions for every turn of a thread, also after a restart
 - A turn that goes back to work until the job is done, with a limit.
 - Model errors that retry with a backoff, and a policy of your own for a context overflow.
 - Waiting messages that join a turn only when you allow it.
+- Tools that run one at a time when they must not overlap.
 - A prompt that runs with its own model, reasoning, prompt cache, and tools.

From 4c9ca0c043d009179142ee27509011852619825f Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 17:19:11 +0200
Subject: [PATCH 257/286] refactor(ai-harness): one fork, through host.fork

host.sessions.fork(harness, threadId, { before | through }) and the HTTP
fork op now call host.fork, so a fork from the session index or a client
also copies the thread settings, plugin config, and media. host.fork takes
at: null to copy no messages.
---
 packages/ai-harness/src/host.ts               | 108 ++++++++++--------
 packages/ai-harness/src/http.ts               |  14 ++-
 packages/ai-harness/tests/fork.test.ts        |   8 +-
 .../ai-harness/tests/sessions-index.test.ts   |  70 +++++++++---
 4 files changed, 127 insertions(+), 73 deletions(-)

diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
index ce6b9eff46..8c367b32dd 100644
--- a/packages/ai-harness/src/host.ts
+++ b/packages/ai-harness/src/host.ts
@@ -1,15 +1,10 @@
 import { EventType } from '@tanstack/ai'
 import { memoryPersistence } from '@tanstack/ai-persistence'
-import { SharedLog, loadLogState, logMessageStore } from './log'
+import { SharedLog, loadLogState } from './log'
 import { HarnessSession } from './session'
 import { HARNESS_EVENTS } from './types'
 import { isRecord } from './utils'
-import type {
-  ModelMessage,
-  PromptCacheOptions,
-  RunStore,
-  StreamChunk,
-} from '@tanstack/ai'
+import type { PromptCacheOptions, RunStore, StreamChunk } from '@tanstack/ai'
 import type {
   AIPersistence,
   ArtifactStore,
@@ -151,12 +146,25 @@ export interface HostSessions {
    */
   delete: (threadId: string) => Promise<void>
   /**
-   * Copy the transcript of a thread into a new thread, up to a message. The
-   * new thread gets its own entry, with the title, harness, and owner of the
-   * old one. Resolves to the new entry. Throws when the message id is not in
-   * the transcript.
+   * Fork a thread into a new thread with `host.fork`, so the fork gets the
+   * settings, plugin config, and media too. `{ through: id }` copies the
+   * messages up to and including `id`. `{ before: id }` copies the messages
+   * before `id`, so a fork before the first message has no messages. The new
+   * thread gets its own entry, with the title of the old one plus ` (fork)`,
+   * the harness, and the owner of the old one. Resolves to the new entry.
+   * Throws when the message id is not in the transcript.
+   *
+   * @example
+   * ```ts
+   * const entry = await host.sessions.fork(assistant, 't-1', { before: messageId })
+   * const fork = await host.open(assistant, { threadId: entry.threadId })
+   * ```
    */
-  fork: (threadId: string, at: ForkPoint) => Promise<SessionIndexEntry>
+  fork: (
+    harness: AnyHarness,
+    threadId: string,
+    at: ForkPoint,
+  ) => Promise<SessionIndexEntry>
 }
 
 /**
@@ -200,10 +208,11 @@ export interface ForkSessionOptions {
   /** The new thread. It must have no messages yet. */
   newThreadId: string
   /**
-   * The id of the last message to copy. Default: the whole transcript. An id
-   * the thread does not have throws.
+   * The id of the last message to copy. `null` copies no messages, but still
+   * copies the settings and plugin config. Default: the whole transcript. An
+   * id the thread does not have throws.
    */
-  at?: string
+  at?: string | null
   /** Who opens the new thread, as in `open`. */
   principal?: Principal
 }
@@ -319,17 +328,6 @@ function sessionIndex(
 /** @internal How a session writes its index entry. */
 export type SessionIndexWriter = ReturnType<typeof sessionIndex>
 
-/** The messages of `messages` up to the message `at` names. */
-function cutTranscript(messages: ReadonlyArray<ModelMessage>, at: ForkPoint) {
-  const isBefore = 'before' in at
-  const messageId = isBefore ? at.before : at.through
-  const index = messages.findIndex((message) => message.id === messageId)
-  if (index === -1) {
-    throw new Error(`The transcript has no message with id ${messageId}.`)
-  }
-  return messages.slice(0, isBefore ? index : index + 1)
-}
-
 /**
  * The status rule: the status of `session` after `event`, or `undefined`
  * when the event changes nothing. An operation that starts runs, and a
@@ -466,16 +464,6 @@ export function createHarnessHost<TLogState = undefined>(
     emit(event)
   }
   const index = sessionIndex(sessionStore, emit)
-  // The transcript of any thread, for a fork. On a durable host, a view of
-  // the log of that thread. ponytail: a thread that shares another log (a
-  // `logId` that is not its thread id) is not found. Keep the log id in the
-  // entry if that matters.
-  const transcripts = logStore
-    ? logMessageStore({
-        store: logStore,
-        ...(options.project ? { project: options.project } : {}),
-      })
-    : persistence.stores.messages
   const coalesceMs = options.coalesceMs ?? 100
   /** The shared log of each log id with an open session, by log id. */
   const logs = new Map<string, Promise<SharedLog<TLogState>>>()
@@ -583,8 +571,10 @@ export function createHarnessHost<TLogState = undefined>(
       const end =
         at === undefined
           ? transcript.length
-          : transcript.findIndex((message) => message.id === at) + 1
-      if (end === 0) {
+          : at === null
+            ? 0
+            : transcript.findIndex((message) => message.id === at) + 1
+      if (typeof at === 'string' && end === 0) {
         throw new Error(
           `Thread ${JSON.stringify(threadId)} has no message ${JSON.stringify(at)}.`,
         )
@@ -616,7 +606,10 @@ export function createHarnessHost<TLogState = undefined>(
     logState: (logId) => resolved.get(logId)?.state.reduced,
     sessions: {
       list: async (listOptions) =>
-        (await sessionStore?.list({ parentThreadId: null, ...listOptions })) ?? {
+        (await sessionStore?.list({
+          parentThreadId: null,
+          ...listOptions,
+        })) ?? {
           entries: [],
         },
       get: (threadId) => index.get(threadId),
@@ -626,25 +619,44 @@ export function createHarnessHost<TLogState = undefined>(
           (entry) => entry && { ...entry, title, updatedAt: Date.now() },
         ),
       delete: (threadId) => index.remove(threadId),
-      async fork(threadId, at) {
-        if (!transcripts) {
-          throw new Error('host.sessions.fork needs stores.messages or stores.log.')
+      async fork(harness, threadId, at) {
+        // `host.fork` takes the last message to copy, so `before` becomes
+        // the message just before it, or `null` before the first one.
+        let last: string | null = 'through' in at ? at.through : null
+        if ('before' in at) {
+          const opened = await host.open(harness, { threadId })
+          const transcript = await opened.transcript()
+          const position = transcript.findIndex(({ id }) => id === at.before)
+          if (position === -1) {
+            throw new Error(
+              `The transcript has no message with id ${at.before}.`,
+            )
+          }
+          if (position > 0) {
+            const previous = transcript[position - 1]?.id
+            if (!previous) {
+              throw new Error(`The message before ${at.before} has no id.`)
+            }
+            last = previous
+          }
         }
-        const kept = cutTranscript(await transcripts.loadThread(threadId), at)
         const source = await index.get(threadId)
+        const forked = await host.fork(harness, {
+          threadId,
+          newThreadId: `thread-${crypto.randomUUID()}`,
+          at: last,
+          ...(source?.principal ? { principal: source.principal } : {}),
+        })
         const now = Date.now()
         // A sibling of the old thread, not a child: no parentThreadId.
         const entry: SessionIndexEntry = {
-          threadId: `thread-${crypto.randomUUID()}`,
+          threadId: forked.threadId,
           createdAt: now,
           updatedAt: now,
-          ...(source?.harness ? { harness: source.harness } : {}),
+          harness: harness.name,
           ...(source?.title ? { title: `${source.title} (fork)` } : {}),
           ...(source?.principal ? { principal: source.principal } : {}),
         }
-        // On a durable host, this appends one transcript record to the new
-        // log.
-        await transcripts.saveThread(entry.threadId, kept)
         await index.update(entry.threadId, () => entry)
         return entry
       },
diff --git a/packages/ai-harness/src/http.ts b/packages/ai-harness/src/http.ts
index 9fee956367..70b4869a71 100644
--- a/packages/ai-harness/src/http.ts
+++ b/packages/ai-harness/src/http.ts
@@ -95,7 +95,9 @@ const json = (body: unknown, status = 200) =>
  * the frame has one. When the client leaves, `signal` aborts.
  */
 function sseResponse(
-  frames: (signal: AbortSignal) => AsyncIterable<{ id?: string; data: unknown }>,
+  frames: (
+    signal: AbortSignal,
+  ) => AsyncIterable<{ id?: string; data: unknown }>,
 ) {
   // Not `request.signal`: some servers abort it once the body is read.
   const reader = new AbortController()
@@ -175,7 +177,9 @@ function parseSessionOp(body: unknown) {
 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
+  return (
+    principal.tenantId === undefined || owner.tenantId === principal.tenantId
+  )
 }
 
 /** Base64url to bytes, or `undefined` for a value that is not base64url. */
@@ -566,15 +570,13 @@ export function createHarnessHandler(
         switch (op.op) {
           case 'rename': {
             const renamed = await host.sessions.rename(op.threadId, op.title)
-            return renamed
-              ? json(renamed)
-              : json({ error: 'not found' }, 404)
+            return renamed ? json(renamed) : json({ error: 'not found' }, 404)
           }
           case 'delete':
             await host.sessions.delete(op.threadId)
             return new Response(null, { status: 204 })
           case 'fork':
-            return json(await host.sessions.fork(op.threadId, op.at))
+            return json(await host.sessions.fork(harness, op.threadId, op.at))
         }
       }
 
diff --git a/packages/ai-harness/tests/fork.test.ts b/packages/ai-harness/tests/fork.test.ts
index 439b047ce3..51106cafb2 100644
--- a/packages/ai-harness/tests/fork.test.ts
+++ b/packages/ai-harness/tests/fork.test.ts
@@ -107,7 +107,7 @@ describe.each([
     }
   })
 
-  it('copies the whole transcript by default, and refuses an unknown message or a used thread', async () => {
+  it('copies the whole transcript by default, no messages for a null at, and refuses an unknown message or a used thread', async () => {
     const persistence = durable ? durablePersistence() : memoryPersistence()
     const { harness, host } = setup(persistence)
     const source = await host.open(harness, { threadId: SOURCE })
@@ -120,6 +120,12 @@ describe.each([
     expect(contents(await whole.transcript())).toEqual(
       contents(await source.transcript()),
     )
+    const empty = await host.fork(harness, {
+      threadId: SOURCE,
+      newThreadId: 'empty',
+      at: null,
+    })
+    expect(await empty.transcript()).toEqual([])
     await expect(
       host.fork(harness, { threadId: SOURCE, newThreadId: 'other', at: 'm-x' }),
     ).rejects.toThrow('m-x')
diff --git a/packages/ai-harness/tests/sessions-index.test.ts b/packages/ai-harness/tests/sessions-index.test.ts
index f3bb72266b..46a7d34c4d 100644
--- a/packages/ai-harness/tests/sessions-index.test.ts
+++ b/packages/ai-harness/tests/sessions-index.test.ts
@@ -172,30 +172,35 @@ describe('host.sessions', () => {
     await session.prompt('still here')
 
     expect(await host.sessions.get('t1')).toBeUndefined()
-    expect(
-      turnsOf(await persistence.stores.messages.loadThread('t1')),
-    ).toEqual([
-      ['user', 'hi'],
-      ['assistant', 'answer'],
-      ['user', 'still here'],
-      ['assistant', 'answer'],
-    ])
+    expect(turnsOf(await persistence.stores.messages.loadThread('t1'))).toEqual(
+      [
+        ['user', 'hi'],
+        ['assistant', 'answer'],
+        ['user', 'still here'],
+        ['assistant', 'answer'],
+      ],
+    )
     await host.close()
   })
 
-  it('forks the transcript before or through a message into a new thread', async () => {
+  it('forks the transcript before or through a message into a new thread, with the settings', async () => {
     const { persistence, host, harness } = hostWith()
     const session = await host.open(harness, {
       threadId: 't1',
       principal: { id: 'u1' },
     })
+    await session.configure({ instructions: 'Be brief.' })
     await session.prompt('first')
     await session.prompt('second')
     await host.sessions.rename('t1', 'Chat')
     const [, , second] = await session.transcript()
 
-    const before = await host.sessions.fork('t1', { before: idOf(second) })
-    const through = await host.sessions.fork('t1', { through: idOf(second) })
+    const before = await host.sessions.fork(harness, 't1', {
+      before: idOf(second),
+    })
+    const through = await host.sessions.fork(harness, 't1', {
+      through: idOf(second),
+    })
 
     expect(before).toEqual({
       threadId: expect.any(String),
@@ -217,6 +222,29 @@ describe('host.sessions', () => {
       ['assistant', 'answer'],
       ['user', 'second'],
     ])
+    for (const { threadId } of [before, through]) {
+      const fork = await host.open(harness, { threadId })
+      expect(fork.settings()).toEqual({ instructions: 'Be brief.' })
+    }
+    await host.close()
+  })
+
+  it('forks before the first message into a thread with no messages, but with the settings', async () => {
+    const { persistence, host, harness } = hostWith()
+    const session = await host.open(harness, { threadId: 't1' })
+    await session.configure({ instructions: 'Be brief.' })
+    await session.prompt('first')
+    const [first] = await session.transcript()
+
+    const fork = await host.sessions.fork(harness, 't1', {
+      before: idOf(first),
+    })
+
+    expect(await persistence.stores.messages.loadThread(fork.threadId)).toEqual(
+      [],
+    )
+    const forked = await host.open(harness, { threadId: fork.threadId })
+    expect(forked.settings()).toEqual({ instructions: 'Be brief.' })
     await host.close()
   })
 
@@ -234,7 +262,9 @@ describe('host.sessions', () => {
     await session.prompt('hi')
     const [, answer] = await session.transcript()
 
-    const fork = await host.sessions.fork('d1', { through: idOf(answer) })
+    const fork = await host.sessions.fork(harness, 'd1', {
+      through: idOf(answer),
+    })
 
     const records = await log.read(fork.threadId)
     expect(records.map(({ record }) => [record.type, record.keep])).toEqual([
@@ -254,8 +284,8 @@ describe('host.sessions', () => {
     await session.prompt('hi')
 
     await expect(
-      host.sessions.fork('t1', { through: 'not-a-message' }),
-    ).rejects.toThrow('The transcript has no message with id not-a-message.')
+      host.sessions.fork(harness, 't1', { through: 'not-a-message' }),
+    ).rejects.toThrow('Thread "t1" has no message "not-a-message".')
     expect(threadIds(await host.sessions.list())).toEqual(['t1'])
     await host.close()
   })
@@ -341,18 +371,22 @@ describe('sessions over HTTP', () => {
   }
 
   it('lists, renames, forks, and deletes the sessions of the user', async () => {
-    const { host, clientOf, chat } = setup()
+    const { host, harness, clientOf, chat } = setup()
     const alice = clientOf('alice')
     const [, answer] = await chat(alice)
+    const source = await host.open(harness, { threadId: 'alice-thread' })
+    await source.configure({ instructions: 'Be brief.' })
 
     expect(threadIds(await alice.listSessions())).toEqual(['alice-thread'])
-    expect(
-      (await alice.renameSession('alice-thread', 'Greetings')).title,
-    ).toBe('Greetings')
+    expect((await alice.renameSession('alice-thread', 'Greetings')).title).toBe(
+      'Greetings',
+    )
     const fork = await alice.forkSession('alice-thread', {
       through: idOf(answer),
     })
     expect(fork.title).toBe('Greetings (fork)')
+    const forked = await host.open(harness, { threadId: fork.threadId })
+    expect(forked.settings()).toEqual({ instructions: 'Be brief.' })
     expect(threadIds(await alice.listSessions()).sort()).toEqual(
       ['alice-thread', fork.threadId].sort(),
     )

From 4ae3164e8a51a988acfd9410f6bacf04555776cf Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 17:19:12 +0200
Subject: [PATCH 258/286] refactor(ai-harness): count usage once, in
 session.usage()

- The usage() plugin reads session.usage(). /usage shows the total and a
  line for each model. A provider cost is used as is, and usage({ model })
  prices only the calls without one.
- The session index entry takes its token counts from session.usage(), so
  it has the calls of background agents and counts a provider cost once.
  The plugin writes the cost whenever it has one.
- The plugin state keeps a copy of the totals next to contextTokens, so
  the harness CLI footer shows them again.
---
 .../harness-cli-cloudflare/src/screen/keys.ts |   5 +-
 examples/harness-cli/src/screen/keys.ts       |   5 +-
 .../src/first-party/session-tools.ts          | 227 ++++++++++--------
 packages/ai-harness/src/session.ts            |  80 ++----
 packages/ai-harness/tests/title-usage.test.ts | 145 ++++++++++-
 packages/ai-persistence/src/types.ts          |   8 +-
 6 files changed, 288 insertions(+), 182 deletions(-)

diff --git a/examples/harness-cli-cloudflare/src/screen/keys.ts b/examples/harness-cli-cloudflare/src/screen/keys.ts
index e47e758b8b..16b9215a67 100644
--- a/examples/harness-cli-cloudflare/src/screen/keys.ts
+++ b/examples/harness-cli-cloudflare/src/screen/keys.ts
@@ -57,8 +57,9 @@ export function isOn(
   )
 }
 
-/** The totals of the usage plugin. */
+/** The usage plugin state: a copy of `session.usage().total`. */
 export interface Usage {
+  /** Model calls: `calls` in the state. */
   turns: number
   promptTokens: number
   completionTokens: number
@@ -73,7 +74,7 @@ export function usageIn(saved: unknown): Usage {
     return typeof value === 'number' ? value : 0
   }
   return {
-    turns: read('turns'),
+    turns: read('calls'),
     promptTokens: read('promptTokens'),
     completionTokens: read('completionTokens'),
     contextTokens: read('contextTokens'),
diff --git a/examples/harness-cli/src/screen/keys.ts b/examples/harness-cli/src/screen/keys.ts
index ccd6c1ae9b..1cdb9144a6 100644
--- a/examples/harness-cli/src/screen/keys.ts
+++ b/examples/harness-cli/src/screen/keys.ts
@@ -55,8 +55,9 @@ export function isOn(
   )
 }
 
-/** The totals of the usage plugin. */
+/** The usage plugin state: a copy of `session.usage().total`. */
 export interface Usage {
+  /** Model calls: `calls` in the state. */
   turns: number
   promptTokens: number
   completionTokens: number
@@ -71,7 +72,7 @@ export function usageIn(saved: unknown): Usage {
     return typeof value === 'number' ? value : 0
   }
   return {
-    turns: read('turns'),
+    turns: read('calls'),
     promptTokens: read('promptTokens'),
     completionTokens: read('completionTokens'),
     contextTokens: read('contextTokens'),
diff --git a/packages/ai-harness/src/first-party/session-tools.ts b/packages/ai-harness/src/first-party/session-tools.ts
index dab01316e8..4b95597f20 100644
--- a/packages/ai-harness/src/first-party/session-tools.ts
+++ b/packages/ai-harness/src/first-party/session-tools.ts
@@ -1,13 +1,14 @@
 import { chat } from '@tanstack/ai'
 import { defineCommand } from '../commands'
 import { definePlugin } from '../plugins'
+import { emptyUsage } from '../usage'
 import type {
   AnyChatMiddleware,
   AnyTextAdapter,
   KeyedAdapter,
   ModelMessage,
-  UsageInfo,
 } from '@tanstack/ai'
+import type { SessionUsage, UsageCounts } from '../usage'
 
 const SUMMARY_PROMPT =
   'Summarize the conversation so far for yourself. Keep decisions, open tasks, file names, and facts you still need. Leave out small talk.'
@@ -78,26 +79,6 @@ export function compact(options: {
   })
 }
 
-interface UsageTotals {
-  turns: number
-  promptTokens: number
-  completionTokens: number
-  totalTokens: number
-  /** Input tokens the provider read from its prompt cache. */
-  cachedTokens: number
-  /** Input tokens the provider wrote to its prompt cache. */
-  cacheWriteTokens: number
-  /**
-   * The input tokens of the latest model call of the lead turn: how much of
-   * the model's context the conversation fills now.
-   */
-  contextTokens: number
-  /** The cost in USD of the priced model calls. Only with the `model` option. */
-  cost?: number
-  /** The model calls that the `model` option had no prices for. */
-  unpricedCalls?: number
-}
-
 /** Prices in USD per 1M tokens: the `cost` of an `@tanstack/ai-models` record. */
 interface ModelPrices {
   input: number
@@ -106,7 +87,7 @@ interface ModelPrices {
   cacheWrite?: number
 }
 
-/** The usage of an index entry before the host adds the tokens of a turn. */
+/** The usage of an index entry before the host writes the tokens of a turn. */
 const NO_TOKENS = {
   turns: 0,
   promptTokens: 0,
@@ -117,38 +98,49 @@ const NO_TOKENS = {
 }
 
 /**
- * The cost in USD of one model call.
+ * The cost in USD of some model calls of one model.
  * ponytail: the formula of `modelCost` in `@tanstack/ai-models`, copied, so
  * ai-harness does not depend on ai-models.
  */
-function callCost(prices: ModelPrices, usage: UsageInfo) {
-  const cached = usage.promptTokensDetails?.cachedTokens ?? 0
-  const written = usage.promptTokensDetails?.cacheWriteTokens ?? 0
+function priceOf(prices: ModelPrices, counts: UsageCounts) {
+  const { cachedTokens, cacheWriteTokens } = counts
   // `promptTokens` counts the cache parts too, and each part has its own price.
-  const uncached = usage.promptTokens - cached - written
+  const uncached = counts.promptTokens - cachedTokens - cacheWriteTokens
   const part = (price: number | undefined, tokens: number) =>
     ((price ?? 0) / 1_000_000) * tokens
   return (
     part(prices.input, uncached) +
-    part(prices.output, usage.completionTokens) +
-    part(prices.cacheRead, cached) +
-    part(prices.cacheWrite, written)
+    part(prices.output, counts.completionTokens) +
+    part(prices.cacheRead, cachedTokens) +
+    part(prices.cacheWrite, cacheWriteTokens)
   )
 }
 
+/** One `/usage` line: the calls and tokens of `counts`. */
+function usageLine(counts: UsageCounts) {
+  // Only a provider that reports its prompt cache has these counts.
+  const hasCache = counts.cachedTokens > 0 || counts.cacheWriteTokens > 0
+  const cache = hasCache
+    ? ` (${counts.cachedTokens} cache read, ${counts.cacheWriteTokens} cache write)`
+    : ''
+  return `${counts.calls} model calls, ${counts.promptTokens} input tokens${cache}, ${counts.completionTokens} output tokens, ${counts.totalTokens} total.`
+}
+
 /**
- * Count tokens across the session: the lead turn and every agent run
- * (subagents, background agents, and their children). `/usage` shows the
- * totals, with the input tokens read from and written to the prompt cache.
- * The plugin state also has `contextTokens`, the size of the lead
- * model's context at its latest call, for a UI.
+ * Show the token usage of the session (`session.usage()`): the lead turn and
+ * every agent run (subagents, background agents, and their children).
+ * `/usage` shows the totals, with the input tokens read from and written to
+ * the prompt cache, and a line for each model when there is more than one.
+ * The plugin state, for a UI, has a copy of `session.usage().total` and
+ * `contextTokens`, the size of the lead model's context at its latest call.
  *
- * With `model`, the plugin also prices each model call. `model` gets the
- * model id of the call and returns its prices in USD per 1M tokens, or
- * `undefined` when it does not know the model. `/usage` then shows the
- * cost, and the plugin writes it to `usage.cost` of the session index
- * entry. A call with no prices adds no cost, and `/usage` says how many
- * calls it could not price.
+ * A model call that has a cost from its provider keeps that cost. With
+ * `model`, the plugin also prices the calls that have no provider cost.
+ * `model` gets the model id and returns its prices in USD per 1M tokens, or
+ * `undefined` when it does not know the model. `/usage` shows the cost when
+ * a call has one, and says how many calls it could not price. When a call
+ * has a cost, the plugin writes the cost to `usage.cost` of the session
+ * index entry.
  *
  * @example
  * ```ts
@@ -165,85 +157,112 @@ export function usage(
   return definePlugin({
     name: 'tanstack/usage',
     setup: (ctx) => {
-      const state = ctx.state<UsageTotals>({
-        turns: 0,
-        promptTokens: 0,
-        completionTokens: 0,
-        totalTokens: 0,
-        cachedTokens: 0,
-        cacheWriteTokens: 0,
-        contextTokens: 0,
-      })
-      const show = (totals: UsageTotals) => {
-        // Only a provider that reports its prompt cache has these counts.
-        const hasCache = totals.cachedTokens > 0 || totals.cacheWriteTokens > 0
-        const cache = hasCache
-          ? ` (${totals.cachedTokens} cache read, ${totals.cacheWriteTokens} cache write)`
-          : ''
-        const tokens = `${totals.turns} model calls, ${totals.promptTokens} input tokens${cache}, ${totals.completionTokens} output tokens, ${totals.totalTokens} total.`
-        if (!options.model) return tokens
-        const unpriced = totals.unpricedCalls ?? 0
+      /**
+       * A copy of the session totals, and `contextTokens`: the input tokens
+       * of the latest model call of the lead turn, so how much of the
+       * model's context the conversation fills now.
+       */
+      const state = ctx.state({ ...emptyUsage().total, contextTokens: 0 })
+      // The cost of the model calls of one model, else `undefined`.
+      const costOf = (model: string, counts: UsageCounts) => {
+        if (counts.cost !== undefined) return counts.cost
+        // The key is `provider/model`. The lookup gets the model id only.
+        const prices = options.model?.(model.slice(model.indexOf('/') + 1))
+        return prices && priceOf(prices.cost, counts)
+      }
+      /**
+       * The cost of the session, and how many calls have no cost. `cost` is
+       * `undefined` when no call has one.
+       * ponytail: core sums by model. When a model has a provider cost, its
+       * calls with no provider cost add nothing. Upgrade: core keeps, by
+       * model, the counts of the calls with no provider cost.
+       */
+      const sessionCost = (totals: SessionUsage) => {
+        let cost: number | undefined
+        let unpriced = 0
+        for (const [model, counts] of Object.entries(totals.byModel)) {
+          const modelCost = costOf(model, counts)
+          if (modelCost === undefined) unpriced += counts.calls
+          else cost = (cost ?? 0) + modelCost
+        }
+        return { cost, unpriced }
+      }
+      const show = () => {
+        const totals = ctx.session.snapshot().usage
+        const { cost, unpriced } = sessionCost(totals)
         const note =
           unpriced > 0
             ? ` (cost unknown for ${unpriced} ${unpriced === 1 ? 'call' : 'calls'})`
             : ''
-        return `${tokens} Cost: $${(totals.cost ?? 0).toFixed(4)}${note}.`
+        const isPriced = options.model !== undefined || cost !== undefined
+        const priced = isPriced
+          ? ` Cost: $${(cost ?? 0).toFixed(4)}${note}.`
+          : ''
+        const lines = [`${usageLine(totals.total)}${priced}`]
+        const models = Object.entries(totals.byModel)
+        // One model has the same counts as the total.
+        if (models.length > 1) {
+          for (const [model, counts] of models) {
+            lines.push(`${model}: ${usageLine(counts)}`)
+          }
+        }
+        return lines.join('\n')
       }
-      // The host adds the tokens of each turn to the index entry. This
-      // plugin writes only `cost`, and keeps the tokens of the entry.
-      const saveCost = async (cost: number) => {
+      // The host writes the token totals to the index entry at the end of
+      // each turn. This plugin writes only `cost`, and keeps the tokens of
+      // the entry.
+      // ponytail: a host with a log counts a call when its log write lands,
+      // which can be after the run ends. Then the entry and the state get
+      // that call at the end of the next run or call. Upgrade: the host
+      // writes the cost at turn end.
+      const saveCost = async () => {
+        const { cost } = sessionCost(ctx.session.snapshot().usage)
+        if (cost === undefined) return
         const entry = await ctx.session.entry()
         if (!entry) return
         // Before the first turn ends, the entry has no usage.
         const tokens = entry.usage ?? NO_TOKENS
         // ponytail: read, then write. A host write or another agent's write
-        // between the two can be lost until the next priced call writes the
-        // total again. Upgrade: a change function in updateEntry.
+        // between the two can be lost until the next run writes the total
+        // again. Upgrade: a change function in updateEntry.
         await ctx.session.updateEntry({ usage: { ...tokens, cost } })
       }
-      const counter = (lead: boolean) =>
-        ({
-          name: 'tanstack/usage',
-          onUsage: async (run, info) => {
-            const prices = options.model?.(run.model)?.cost
-            const cost = prices ? callCost(prices, info) : undefined
-            const isUnpriced = options.model !== undefined && cost === undefined
-            const { cost: total } = await state.update((totals) => ({
-              ...totals,
-              ...(cost !== undefined ? { cost: (totals.cost ?? 0) + cost } : {}),
-              ...(isUnpriced
-                ? { unpricedCalls: (totals.unpricedCalls ?? 0) + 1 }
-                : {}),
-              turns: totals.turns + 1,
-              promptTokens: totals.promptTokens + (info.promptTokens ?? 0),
-              completionTokens:
-                totals.completionTokens + (info.completionTokens ?? 0),
-              totalTokens: totals.totalTokens + (info.totalTokens ?? 0),
-              cachedTokens:
-                totals.cachedTokens +
-                (info.promptTokensDetails?.cachedTokens ?? 0),
-              cacheWriteTokens:
-                totals.cacheWriteTokens +
-                (info.promptTokensDetails?.cacheWriteTokens ?? 0),
-              contextTokens: lead
-                ? (info.promptTokens ?? totals.contextTokens)
-                : totals.contextTokens,
-            }))
-            if (cost === undefined || total === undefined) return
-            // The index is only a list of sessions: a failed write does not
-            // fail the turn. The next priced call writes the total again.
-            await saveCost(total).catch(() => {})
-          },
-        }) satisfies AnyChatMiddleware
+      // Copy the session totals to the state. Only a call of the lead turn
+      // sets the context size.
+      const mirror = (contextTokens?: number) =>
+        state.update((current) => ({
+          ...ctx.session.snapshot().usage.total,
+          contextTokens: contextTokens ?? current.contextTokens,
+        }))
+      // At the end of each run, the state gets the totals and the index entry
+      // gets the cost so far. The index is only a list of sessions, and the
+      // state only a copy: a failed write does not fail the run. The next run
+      // writes them again.
+      const save = async () => {
+        await Promise.all([mirror(), saveCost()]).catch(() => {})
+      }
+      const atRunEnd = {
+        name: 'tanstack/usage',
+        onFinish: save,
+        onAbort: save,
+        onError: save,
+      } satisfies AnyChatMiddleware
       return {
-        // The same totals for the lead turn and every agent run. Only the
-        // lead turn sets the context size.
-        middleware: [counter(true)],
-        agentMiddleware: [counter(false)],
+        middleware: [
+          {
+            ...atRunEnd,
+            onUsage: async (_run, info) => {
+              await mirror(info.promptTokens)
+            },
+          } satisfies AnyChatMiddleware,
+        ],
+        // An agent's middleware runs before the host counts its call, so its
+        // run copies the totals only at its end.
+        agentMiddleware: [atRunEnd],
         commands: {
           usage: defineCommand({
             description: 'Show token usage for this session',
-            run: async () => show(await state.get()),
+            run: show,
           }),
         },
       }
diff --git a/packages/ai-harness/src/session.ts b/packages/ai-harness/src/session.ts
index 94d24611c4..118da88b4c 100644
--- a/packages/ai-harness/src/session.ts
+++ b/packages/ai-harness/src/session.ts
@@ -9,7 +9,6 @@ import {
   compactForModel,
   convertSchemaToJsonSchema,
   createSubagentId,
-  fromSpecTokenUsage,
   maxIterations,
   modelMessagesToUIMessages,
   provideLogRecords,
@@ -55,7 +54,6 @@ import type {
   ProviderKeys,
   ResolvedPromptCache,
   RunAgentResumeItem,
-  RunFinishedEvent,
   RunRecord,
   SchemaInput,
   Scope,
@@ -79,7 +77,6 @@ import type {
   LogRecord,
   LogStore,
   MessageStore,
-  SessionIndexEntry,
   SessionIndexStore,
 } from '@tanstack/ai-persistence'
 import type { AuthRequiredError, CredentialsAccess } from './auth'
@@ -503,50 +500,6 @@ function turnContext(harness: unknown, input: unknown) {
   return harness !== undefined ? harness : input
 }
 
-type EntryUsage = NonNullable<SessionIndexEntry['usage']>
-
-/**
- * The usage of one finished run, as session index totals. `undefined` when
- * the run has no usage. A child run counts nothing: the run of its parent
- * has the child's usage too.
- */
-function entryUsageOf(chunk: RunFinishedEvent) {
-  if ('subagentRunId' in chunk && chunk.subagentRunId) return undefined
-  const { usage } = chunk
-  const tokens =
-    usage === undefined || Array.isArray(usage)
-      ? fromSpecTokenUsage(usage, chunk.metadata?.tanstack?.usage)
-      : usage
-  if (!tokens) return undefined
-  const counted: EntryUsage = {
-    // `usage[]` has one item per model call, the calls of children too.
-    turns: Array.isArray(usage) ? usage.length : 1,
-    promptTokens: tokens.promptTokens,
-    completionTokens: tokens.completionTokens,
-    totalTokens: tokens.totalTokens,
-    cachedTokens: tokens.promptTokensDetails?.cachedTokens ?? 0,
-    cacheWriteTokens: tokens.promptTokensDetails?.cacheWriteTokens ?? 0,
-    ...(tokens.cost !== undefined ? { cost: tokens.cost } : {}),
-  }
-  return counted
-}
-
-/** `total` plus `next`. A cost is kept when either one has a cost. */
-function addEntryUsage(total: EntryUsage | undefined, next: EntryUsage) {
-  if (!total) return next
-  const hasCost = total.cost !== undefined || next.cost !== undefined
-  const sum: EntryUsage = {
-    turns: total.turns + next.turns,
-    promptTokens: total.promptTokens + next.promptTokens,
-    completionTokens: total.completionTokens + next.completionTokens,
-    totalTokens: total.totalTokens + next.totalTokens,
-    cachedTokens: total.cachedTokens + next.cachedTokens,
-    cacheWriteTokens: total.cacheWriteTokens + next.cacheWriteTokens,
-    ...(hasCost ? { cost: (total.cost ?? 0) + (next.cost ?? 0) } : {}),
-  }
-  return sum
-}
-
 /** Where `stores.metadata` keeps the stored settings of each thread. */
 const SETTINGS = 'harness:settings'
 
@@ -3527,8 +3480,6 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     let text = ''
     let interrupts: Array<Interrupt> | undefined
     let failure: string | undefined
-    /** What the model calls of this turn spent, for the session index. */
-    let turnUsage: EntryUsage | undefined
     const captured: Array<MediaRecord> = []
     // What plugins and the router see of this turn. A turn that recovery
     // runs again gets the message its input sent.
@@ -3862,10 +3813,6 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           routedFrom = undefined
           for await (const chunk of stream) {
             cards?.processChunk(chunk)
-            if (chunk.type === EventType.RUN_FINISHED) {
-              const counted = entryUsageOf(chunk)
-              if (counted) turnUsage = addEntryUsage(turnUsage, counted)
-            }
             // chat() refused the resume before it ran anything.
             if (
               chunk.type === EventType.RUN_ERROR &&
@@ -4061,10 +4008,12 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
       )
     }
 
-    // The index entry gets the time of the turn and what it spent, before the
-    // turn ends. A deleted entry stays deleted. A failed write does not fail
-    // the turn.
-    const spent = turnUsage
+    // The index entry gets the time of the turn and the token totals of the
+    // session, before the turn ends. chat() waits for the usage counts before
+    // its stream ends, so the totals have every call of this turn. The totals
+    // replace the stored ones. The cost stays: a usage plugin writes it. A
+    // deleted entry stays deleted. A failed write does not fail the turn.
+    const { total } = this.usage()
     await this.index
       .update(
         this.threadId,
@@ -4072,7 +4021,19 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
           entry && {
             ...entry,
             updatedAt: Date.now(),
-            ...(spent ? { usage: addEntryUsage(entry.usage, spent) } : {}),
+            ...(total.calls > 0
+              ? {
+                  usage: {
+                    ...entry.usage,
+                    turns: total.calls,
+                    promptTokens: total.promptTokens,
+                    completionTokens: total.completionTokens,
+                    totalTokens: total.totalTokens,
+                    cachedTokens: total.cachedTokens,
+                    cacheWriteTokens: total.cacheWriteTokens,
+                  },
+                }
+              : {}),
           },
       )
       .catch((error: unknown) =>
@@ -5342,8 +5303,7 @@ export class HarnessSession<THarness extends AnyHarness = AnyHarness> {
     const { input } = logged
     if (input.op !== 'cancelInput' && input.op !== 'setDelivery') return
     const target = writer.state.inputs.get(input.inputId)
-    const isWaiting =
-      target?.status === 'pending' && 'message' in target.input
+    const isWaiting = target?.status === 'pending' && 'message' in target.input
     if (!isWaiting) {
       this.reject(logged.inputId, 'not_waiting')
       return
diff --git a/packages/ai-harness/tests/title-usage.test.ts b/packages/ai-harness/tests/title-usage.test.ts
index 9d0525e4a1..9e2f6ca709 100644
--- a/packages/ai-harness/tests/title-usage.test.ts
+++ b/packages/ai-harness/tests/title-usage.test.ts
@@ -1,27 +1,36 @@
 import { describe, expect, it, vi } from 'vitest'
-import { EventType } from '@tanstack/ai'
+import { EventType, defineAgent } from '@tanstack/ai'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness, definePlugin } from '../src'
 import { usage } from '../src/first-party/session-tools'
 import { TitleFailed, title } from '../src/first-party/title'
 import { messageTexts, mockAdapter, text } from './helpers'
 import type { StreamChunk, TokenUsage } from '@tanstack/ai'
-import type { HarnessPersistence, HarnessPlugin } from '../src'
+import type { AnyAgent, HarnessPersistence, HarnessPlugin } from '../src'
 import type { Reply } from './helpers'
 
-/** Open thread `t`. The main model answers `answer` unless `reply` is given. */
+/**
+ * Open thread `t`. The main model answers `answer` unless `reply` is given.
+ * `agents` are the background agents of the session.
+ */
 async function open(
   plugins: Array<HarnessPlugin>,
   {
     persistence = memoryPersistence(),
     reply = () => text('answer'),
-  }: { persistence?: HarnessPersistence; reply?: Reply } = {},
+    agents = [],
+  }: {
+    persistence?: HarnessPersistence
+    reply?: Reply
+    agents?: Array<AnyAgent>
+  } = {},
 ) {
   const host = createHarnessHost({ persistence })
   const session = await host.open(
     defineHarness({
       name: 'test/title-usage',
       adapter: mockAdapter(reply).adapter,
+      agents,
       plugins: () => plugins,
     }),
     { threadId: 't' },
@@ -104,7 +113,7 @@ describe('title()', () => {
   })
 })
 
-describe('usage({ model })', () => {
+describe('usage()', () => {
   /** Prices in USD per 1M tokens. */
   const PRICES = { input: 2, output: 10, cacheRead: 1, cacheWrite: 4 }
   /**
@@ -117,16 +126,132 @@ describe('usage({ model })', () => {
     totalTokens: 1_100_000,
     promptTokensDetails: { cachedTokens: 250_000, cacheWriteTokens: 250_000 },
   }
-  const withUsage = () =>
+  /** The `/usage` line of one CALL. */
+  const CALL_LINE =
+    '1 model calls, 1000000 input tokens (250000 cache read, 250000 cache write), 100000 output tokens, 1100000 total.'
+  /** A model call that answers and reports `usage`. */
+  const replyWith = (usage: TokenUsage) => () =>
     text('answer').map(
       (chunk): StreamChunk =>
-        chunk.type === EventType.RUN_FINISHED
-          ? { ...chunk, usage: CALL }
-          : chunk,
+        chunk.type === EventType.RUN_FINISHED ? { ...chunk, usage } : chunk,
     )
+  const withUsage = replyWith(CALL)
   /** The prices of the mock adapter's model only. */
   const pricesOf = (modelId: string) =>
     modelId === 'test-model' ? { cost: PRICES } : undefined
+  /** A background agent. Its model, `worker-model`, reports `usage`. */
+  const workerWith = (usage: TokenUsage) => {
+    const { adapter } = mockAdapter(replyWith(usage))
+    return defineAgent({
+      name: 'worker',
+      description: 'Works',
+      run: (ctx) =>
+        ctx.chat({ adapter: { ...adapter, model: 'worker-model' } }),
+    })
+  }
+
+  it('uses a provider cost as is, and prices only the calls with no provider cost', async () => {
+    // The lookup knows every model: it would price the worker call at $3.25.
+    const { host, session } = await open(
+      [usage({ model: () => ({ cost: PRICES }) })],
+      { reply: withUsage, agents: [workerWith({ ...CALL, cost: 0.5 })] },
+    )
+
+    await session.prompt('one')
+    await session.agent('worker')?.start()
+
+    // The lead call costs $3.25 from the lookup, the worker call $0.50 from
+    // its provider.
+    expect(await session.command('usage')).toBe(
+      [
+        '2 model calls, 2000000 input tokens (500000 cache read, 500000 cache write), 200000 output tokens, 2200000 total. Cost: $3.7500.',
+        `mock/test-model: ${CALL_LINE}`,
+        `mock/worker-model: ${CALL_LINE}`,
+      ].join('\n'),
+    )
+    // `/usage` shows the totals of the session.
+    expect(session.usage().total).toEqual({
+      calls: 2,
+      promptTokens: 2_000_000,
+      completionTokens: 200_000,
+      totalTokens: 2_200_000,
+      cachedTokens: 500_000,
+      cacheWriteTokens: 500_000,
+      cost: 0.5,
+    })
+    expect((await host.sessions.get('t'))?.usage?.cost).toBeCloseTo(3.75, 10)
+    await host.close()
+  })
+
+  it('shows a provider cost without the model option, and writes it to the index entry', async () => {
+    const { host, session } = await open([usage()], {
+      reply: replyWith({ ...CALL, cost: 0.5 }),
+    })
+
+    await session.prompt('one')
+
+    expect(await session.command('usage')).toBe(`${CALL_LINE} Cost: $0.5000.`)
+    expect((await host.sessions.get('t'))?.usage?.cost).toBe(0.5)
+    await host.close()
+  })
+
+  it('counts a provider cost once in the index entry', async () => {
+    const { host, session } = await open([usage({ model: pricesOf })], {
+      reply: replyWith({ ...CALL, cost: 0.5 }),
+    })
+
+    await session.prompt('one')
+    await session.prompt('two')
+
+    // Two calls at $0.50. The host writes no cost of its own.
+    expect((await host.sessions.get('t'))?.usage?.cost).toBeCloseTo(1, 10)
+    await host.close()
+  })
+
+  it('writes the session totals to the index entry, with the calls of a background agent', async () => {
+    const { host, session } = await open([usage()], {
+      reply: withUsage,
+      agents: [workerWith(CALL)],
+    })
+
+    await session.prompt('one')
+    await session.agent('worker')?.start()
+    await session.prompt('two')
+
+    // Two lead calls and one worker call.
+    expect((await host.sessions.get('t'))?.usage).toEqual({
+      turns: 3,
+      promptTokens: 3_000_000,
+      completionTokens: 300_000,
+      totalTokens: 3_300_000,
+      cachedTokens: 750_000,
+      cacheWriteTokens: 750_000,
+    })
+    await host.close()
+  })
+
+  it('keeps a copy of the session totals in its state', async () => {
+    const { host, session } = await open([usage()], {
+      reply: withUsage,
+      agents: [workerWith({ ...CALL, promptTokens: 2_000_000 })],
+    })
+
+    await session.prompt('one')
+    await session.agent('worker')?.start()
+
+    // The worker's call is in the copy too.
+    expect(session.snapshot().plugins['tanstack/usage']).toEqual({
+      calls: 2,
+      promptTokens: 3_000_000,
+      completionTokens: 200_000,
+      totalTokens: 2_200_000,
+      cachedTokens: 500_000,
+      cacheWriteTokens: 500_000,
+      // The input of the lead's latest call, not the worker's.
+      contextTokens: 1_000_000,
+    })
+    await host.close()
+  })
 
   it('prices each model call and shows the cost in /usage', async () => {
     const { host, session } = await open([usage({ model: pricesOf })], {
@@ -170,7 +295,7 @@ describe('usage({ model })', () => {
     await session.prompt('one')
 
     expect(await session.command('usage')).toBe(
-      '1 model calls, 1000000 input tokens (250000 cache read, 250000 cache write), 100000 output tokens, 1100000 total. Cost: $0.0000 (cost unknown for 1 call).',
+      `${CALL_LINE} Cost: $0.0000 (cost unknown for 1 call).`,
     )
     expect((await host.sessions.get('t'))?.usage).toEqual({
       turns: 1,
diff --git a/packages/ai-persistence/src/types.ts b/packages/ai-persistence/src/types.ts
index f04cecf164..d888686468 100644
--- a/packages/ai-persistence/src/types.ts
+++ b/packages/ai-persistence/src/types.ts
@@ -568,11 +568,11 @@ export interface SessionIndexEntry {
   /** Who owns the thread, from the host's `authorize`. */
   principal?: { id: string; tenantId?: string }
   /**
-   * Token totals of the thread. The names match the totals of the harness
-   * `usage()` plugin.
+   * Token totals of the thread. The harness writes the counts from its core
+   * usage (`session.usage().total`) at the end of each turn.
    */
   usage?: {
-    /** Model calls. */
+    /** Model calls: `calls` in the harness usage. */
     turns: number
     promptTokens: number
     completionTokens: number
@@ -581,7 +581,7 @@ export interface SessionIndexEntry {
     cachedTokens: number
     /** Input tokens the provider wrote to its prompt cache. */
     cacheWriteTokens: number
-    /** Cost in USD, when a plugin counts it. */
+    /** Cost in USD, when a usage plugin writes it. */
     cost?: number
   }
   metadata?: Record<string, unknown>

From 2b0d79c66fa66b17a5169633c582b9112f5cb708 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 17:28:41 +0200
Subject: [PATCH 259/286] docs: toolChoice, replaceResult, and the single
 subagent tool

- Tools: choose when the model calls a tool, with notes for each provider.
- Ollama ignores toolChoice.
- Middleware: change the tool choice of one call, and replace a tool
  result.
- Subagents: one subagent tool that picks an agent by name, continues a
  child by sessionId, or runs it in the background, in chat() and in the
  harness, with its limits.
- Migration from the Vercel AI SDK: toolChoice is a chat() option.
---
 docs/adapters/ollama.md                    |  10 +-
 docs/advanced/middleware.md                | 197 +++++++++++++++------
 docs/chat/subagents.md                     |  88 ++++++++-
 docs/harness/subagents.md                  |  74 +++++++-
 docs/migration/migration-from-vercel-ai.md |   2 +-
 docs/tools/tools.md                        |  95 +++++++++-
 6 files changed, 398 insertions(+), 68 deletions(-)

diff --git a/docs/adapters/ollama.md b/docs/adapters/ollama.md
index 785a088588..a27b048e6a 100644
--- a/docs/adapters/ollama.md
+++ b/docs/adapters/ollama.md
@@ -159,9 +159,13 @@ export async function POST(request: Request) {
 
 **Note:** Tool support varies by model. Models like `llama3`, `mistral`, and `qwen2` generally have good tool calling support.
 
+## Tool choice
+
+Ollama has no tool choice. The adapter ignores `chat({ toolChoice })`, so the model decides to call a tool or not, also with `'none'` or `'required'`. To stop tool calls for a request, do not pass tools. For the other providers, see [Choose when the model calls a tool](../tools/tools#choose-when-the-model-calls-a-tool).
+
 ## Model Options
 
-Ollama supports various provider-specific options. Unlike the other providers, Ollama nests its sampling and runner parameters inside an `options` object **within** `modelOptions` — `temperature`, `top_p`, and `num_predict` (the token-limit key) all live under `modelOptions.options`:
+Ollama supports various provider-specific options. Unlike the other providers, Ollama nests its sampling and runner parameters inside an `options` object **within** `modelOptions`. `temperature`, `top_p`, and `num_predict` (the token-limit key) all live under `modelOptions.options`:
 
 ```typescript
 import { chat } from "@tanstack/ai";
@@ -258,7 +262,7 @@ const result = await embed({
 console.log(result.embeddings[0]?.vector);
 ```
 
-Known models (`nomic-embed-text`, `mxbai-embed-large`, `all-minilm`, `snowflake-arctic-embed`, `bge-m3`, `embeddinggemma`) get autocomplete, and any other model name is accepted. Pull the model first with `ollama pull nomic-embed-text`. Output dimensions are fixed per model — the top-level `dimensions` option is not supported.
+Known models (`nomic-embed-text`, `mxbai-embed-large`, `all-minilm`, `snowflake-arctic-embed`, `bge-m3`, `embeddinggemma`) get autocomplete, and any other model name is accepted. Pull the model first with `ollama pull nomic-embed-text`. Output dimensions are fixed per model, so the top-level `dimensions` option is not supported.
 
 See the [Embeddings guide](../embeddings.md) for the full API.
 
@@ -334,7 +338,7 @@ Creates an Ollama text/chat adapter with an explicit host or client config.
 
 ### `ollamaSummarize(model)` / `createOllamaSummarize(model, hostOrConfig?)`
 
-Creates an Ollama summarization adapter — same signature shape as the chat adapter.
+Creates an Ollama summarization adapter, with the same signature shape as the chat adapter.
 
 ## Benefits of Ollama
 
diff --git a/docs/advanced/middleware.md b/docs/advanced/middleware.md
index 10d35cc374..4bcca8c9d7 100644
--- a/docs/advanced/middleware.md
+++ b/docs/advanced/middleware.md
@@ -2,7 +2,7 @@
 title: Middleware
 id: middleware
 order: 1
-description: "Hook into every stage of TanStack AI's chat() lifecycle with middleware — logging, analytics, stream transforms, tool interception, and side effects."
+description: "Hook into every stage of TanStack AI's chat() lifecycle with middleware: logging, analytics, stream transforms, tool interception, and side effects."
 keywords:
   - tanstack ai
   - middleware
@@ -14,15 +14,15 @@ keywords:
   - stream transform
 ---
 
-Middleware lets you hook into every stage of the `chat()` lifecycle — from configuration to streaming, tool execution, usage tracking, and completion. You can observe, transform, or short-circuit behavior at each stage without modifying your adapter or tool implementations.
+Middleware lets you hook into every stage of the `chat()` lifecycle, from configuration to streaming, tool execution, usage tracking, and completion. You can observe, transform, or short-circuit behavior at each stage without modifying your adapter or tool implementations.
 
 Common use cases include:
 
-- **Logging and observability** — track token usage, tool execution timing, errors
-- **Configuration transforms** — inject system prompts, adjust temperature per iteration, filter tools
-- **Stream processing** — redact sensitive content, transform chunks, drop unwanted events
-- **Tool call interception** — validate arguments, cache results, abort on dangerous calls
-- **Side effects** — send analytics, update databases, trigger notifications
+- **Logging and observability**: track token usage, tool execution timing, errors
+- **Configuration transforms**: inject system prompts, adjust temperature per iteration, filter tools
+- **Stream processing**: redact sensitive content, transform chunks, drop unwanted events
+- **Tool call interception**: validate arguments, cache or replace results, abort on dangerous calls
+- **Side effects**: send analytics, update databases, trigger notifications
 
 ## Quick Start
 
@@ -50,7 +50,7 @@ const stream = chat({
 ```
 
 > **Just want to see chunks flowing through your middleware during development?**
-> Use `debug: { middleware: true }` on your `chat()` call — no custom middleware required. See [Debug Logging](./debug-logging).
+> Use `debug: { middleware: true }` on your `chat()` call. No custom middleware is required. See [Debug Logging](./debug-logging).
 
 ## Lifecycle Overview
 
@@ -113,7 +113,7 @@ The context's `phase` field tracks where you are in the lifecycle:
 
 Called once during `init` (startup) and once per iteration during `beforeModel` (before each model call). On the separate-finalization path, `onConfig` additionally re-fires at the structured-output boundary with `ctx.phase === 'structuredOutput'`, receiving the post-`onStructuredOutputConfig` view of the config. A single-iteration separate-finalization run therefore fires `onConfig` three times (`init` + `beforeModel` + `structuredOutput`). Native-combined output does not add this third call. Use `onConfig` to transform the configuration that the model receives.
 
-Return a **partial** config object with only the fields you want to change — they are shallow-merged with the current config automatically. No need to spread the existing config.
+Return a **partial** config object with only the fields you want to change. They are shallow-merged with the current config automatically. No need to spread the existing config.
 
 ```typescript
 import { type ChatMiddleware } from "@tanstack/ai";
@@ -122,7 +122,7 @@ const dynamicTemperature: ChatMiddleware = {
   name: "dynamic-temperature",
   onConfig: (ctx, config) => {
     if (ctx.phase === "init") {
-      // Add a system prompt at startup — only systemPrompts is overwritten
+      // Add a system prompt at startup. Only systemPrompts is overwritten
       return {
         systemPrompts: [
           ...config.systemPrompts,
@@ -133,7 +133,7 @@ const dynamicTemperature: ChatMiddleware = {
 
     if (ctx.phase === "beforeModel" && ctx.iteration > 0) {
       // Increase temperature on retries. Sampling params live in the
-      // provider-native modelOptions object — `temperature` is universal,
+      // provider-native modelOptions object. `temperature` is universal,
       // so it's the same key across providers. Spread the existing
       // modelOptions so other model options stay unchanged.
       const current =
@@ -151,7 +151,7 @@ const dynamicTemperature: ChatMiddleware = {
 };
 ```
 
-> Sampling parameters (`temperature`, `top_p` / `topP`, the various `max*Tokens` keys) live inside `modelOptions` under each provider's native name — they are no longer root config fields. `temperature` happens to be spelled the same across every provider, so the example above is provider-agnostic; if you mutate a token limit instead, use the provider-native key (e.g. `max_output_tokens` for OpenAI, `num_predict` nested under `modelOptions.options` for Ollama). See [Moving Sampling Options into modelOptions](../migration/sampling-options-to-model-options).
+> Sampling parameters (`temperature`, `top_p` / `topP`, the various `max*Tokens` keys) live inside `modelOptions` under each provider's native name. They are not root config fields. `temperature` happens to be spelled the same across every provider, so the example above is provider-agnostic; if you mutate a token limit instead, use the provider-native key (e.g. `max_output_tokens` for OpenAI, `num_predict` nested under `modelOptions.options` for Ollama). See [Moving Sampling Options into modelOptions](../migration/sampling-options-to-model-options).
 
 **Config fields you can transform:**
 
@@ -162,11 +162,12 @@ const dynamicTemperature: ChatMiddleware = {
 | `systemPrompts` | `string[]` | System prompts |
 | `tools` | `Tool[]` | Available tools |
 | `metadata` | `Record<string, unknown>` | Request metadata |
-| `modelOptions` | `Record<string, unknown>` | Provider-native options — this is where sampling params (`temperature`, `top_p` / `topP`, the provider's `max*Tokens` key) now live, alongside every other model-specific knob. See [Moving Sampling Options into modelOptions](../migration/sampling-options-to-model-options). |
+| `modelOptions` | `Record<string, unknown>` | Provider-native options. Sampling params (`temperature`, `top_p` / `topP`, the provider's `max*Tokens` key) live here, next to every other model-specific option. See [Moving Sampling Options into modelOptions](../migration/sampling-options-to-model-options). |
 | `reasoning` | `ReasoningRequest \| undefined` | How hard the model thinks at this call. See [Reasoning](../chat/reasoning#change-the-level-in-middleware). |
 | `promptCache` | `ResolvedPromptCache \| undefined` | The prompt cache of this call: its `retention` and `key`. See [Change the prompt cache of a call](#change-the-prompt-cache-of-a-call). |
+| `toolChoice` | `ToolChoice \| undefined` | How the model uses the tools at the next call. See [Change the tool choice of a call](#change-the-tool-choice-of-a-call). |
 
-When multiple middleware define `onConfig`, the config is **piped** through them in order — each receives the merged config from the previous middleware.
+When multiple middleware define `onConfig`, the config is **piped** through them in order. Each receives the merged config from the previous middleware.
 
 Return `providerMessages` when a transform must affect only the model call. For
 compatibility, returning `messages` also updates provider input unless the same
@@ -192,13 +193,54 @@ const longCacheAfterTools: ChatMiddleware = {
 - The returned value goes to the adapter on the next model call. It stays for the later calls until a middleware returns another value.
 - For the retention values and their cost, see [Prompt Caching](./prompt-caching#pick-the-retention).
 
+#### Change the tool choice of a call
+
+An agent run can reach its last model call while the model still calls tools. The run then ends after a tool result, with no answer for the user. Return `toolChoice` from `onConfig` to change how the model uses the tools at the next call:
+
+```typescript
+import { chat, maxIterations, toolDefinition, type ChatMiddleware } from "@tanstack/ai";
+import { openaiText } from "@tanstack/ai-openai";
+import { z } from "zod";
+
+const MAX_CALLS = 10;
+
+const search = toolDefinition({
+  name: "search",
+  description: "Search the docs",
+  inputSchema: z.object({ query: z.string() }),
+}).server(async ({ query }) => ({ hits: [`A page about ${query}`] }));
+
+// The last call gets no tool calls, so the model answers in text.
+const answerOnLastCall: ChatMiddleware = {
+  name: "answer-on-last-call",
+  onConfig: (ctx) => {
+    if (ctx.phase === "beforeModel" && ctx.iteration === MAX_CALLS - 1) {
+      return { toolChoice: "none" };
+    }
+  },
+};
+
+const stream = chat({
+  adapter: openaiText("gpt-6.1-sol"),
+  messages: [{ role: "user", content: "How do I add a tool?" }],
+  tools: [search],
+  agentLoopStrategy: maxIterations(MAX_CALLS),
+  middleware: [answerOnLastCall],
+});
+```
+
+- `config.toolChoice` is the `chat()` option.
+- The returned value applies to the next model call only. The call after it starts again from the `chat()` option.
+- Return it in the `beforeModel` phase. A value from the `init` phase does not reach a model call.
+- For the values, and for what each provider does with them, see [Choose when the model calls a tool](../tools/tools#choose-when-the-model-calls-a-tool).
+
 ### onStructuredOutputConfig
 
-Called once at the start of the final structured-output adapter call — only when `chat()` was invoked with `outputSchema` **and** `supportsCombinedToolsAndSchema()` does not return `true` for the current model/options. Pipes through middleware in order, like `onConfig`, but with access to the **JSON Schema** being sent to the provider. Use this hook when you need to transform the schema (e.g., inject `$defs`, strip vendor-incompatible keywords) or apply structured-output-specific behavior (e.g., suppress system prompts on the final call).
+Called once at the start of the final structured-output adapter call, only when `chat()` was invoked with `outputSchema` **and** `supportsCombinedToolsAndSchema()` does not return `true` for the current model/options. Pipes through middleware in order, like `onConfig`, but with access to the **JSON Schema** being sent to the provider. Use this hook when you need to transform the schema (e.g., inject `$defs`, strip vendor-incompatible keywords) or apply structured-output-specific behavior (e.g., suppress system prompts on the final call).
 
-> Native-combined adapters (modern OpenAI, Claude 4.5+, Gemini 3.x, Grok 4.x — see issue #605) skip the separate finalization call and never invoke this hook. The engine passes the converted schema directly to `chatStream` after `onConfig` runs, so middleware cannot transform the native-combined schema.
+> Native-combined adapters (modern OpenAI, Claude 4.5+, Gemini 3.x, and Grok 4.x, per issue #605) skip the separate finalization call and never invoke this hook. The engine passes the converted schema directly to `chatStream` after `onConfig` runs, so middleware cannot transform the native-combined schema.
 
-Return a **partial** `StructuredOutputMiddlewareConfig` with only the fields you want to change — they are shallow-merged with the current config. Return `void` to pass through.
+Return a **partial** `StructuredOutputMiddlewareConfig` with only the fields you want to change. They are shallow-merged with the current config. Return `void` to pass through.
 
 ```typescript
 import { type ChatMiddleware } from "@tanstack/ai";
@@ -226,7 +268,7 @@ const injectDefs: ChatMiddleware = {
 | `providerMessages` | `ModelMessage[]` | Temporary context sent to the final call |
 | `systemPrompts` | `SystemPrompt[]` | System prompts on the final call |
 | `metadata` | `Record<string, unknown>` | Request metadata |
-| `modelOptions` | `Record<string, unknown>` | Provider-native options — this is where sampling params (`temperature`, `top_p` / `topP`, the provider's `max*Tokens` key) now live, alongside every other model-specific knob. See [Moving Sampling Options into modelOptions](../migration/sampling-options-to-model-options). |
+| `modelOptions` | `Record<string, unknown>` | Provider-native options. Sampling params (`temperature`, `top_p` / `topP`, the provider's `max*Tokens` key) live here, next to every other model-specific option. See [Moving Sampling Options into modelOptions](../migration/sampling-options-to-model-options). |
 | `outputSchema` | `JSONSchema` | JSON Schema being sent to the provider for structured output |
 
 **Ordering at the structured-output boundary:**
@@ -234,7 +276,7 @@ const injectDefs: ChatMiddleware = {
 1. `onStructuredOutputConfig` fires first, piping through every middleware in array order.
 2. `onConfig` then re-fires at the same boundary with `ctx.phase === 'structuredOutput'`, receiving the post-`onStructuredOutputConfig` view of the config (minus `outputSchema`). Use `onConfig` for general-purpose transforms that apply to every adapter call; use `onStructuredOutputConfig` when you need access to the schema.
 
-When multiple middleware define `onStructuredOutputConfig`, the config is **piped** through them in order — each receives the merged config from the previous middleware.
+When multiple middleware define `onStructuredOutputConfig`, the config is **piped** through them in order. Each receives the merged config from the previous middleware.
 
 ### onStart
 
@@ -286,7 +328,7 @@ When multiple middleware define `onChunk`, chunks flow through them in order. If
 
 #### Chunk types you'll see
 
-`onChunk` receives every [AG-UI event](https://docs.ag-ui.com/introduction) the run produces — not just text. Narrow on `chunk.type` (a discriminated union) before reading type-specific fields. The common ones:
+`onChunk` receives every [AG-UI event](https://docs.ag-ui.com/introduction) the run produces, not only text. Narrow on `chunk.type` (a discriminated union) before reading type-specific fields. The common ones:
 
 | `chunk.type` | Meaning | Key fields |
 |--------------|---------|-----------|
@@ -295,18 +337,18 @@ When multiple middleware define `onChunk`, chunks flow through them in order. If
 | `TOOL_CALL_START` / `TOOL_CALL_ARGS` / `TOOL_CALL_END` | Tool invocation streaming | `toolCallId`, `toolCallName`, `delta` (args), result on end |
 | `STEP_STARTED` / `STEP_FINISHED` | Thinking / reasoning steps | `delta`, `signature` |
 | `STATE_SNAPSHOT` / `STATE_DELTA` | Agent state sync | `snapshot`, `delta` |
-| `CUSTOM` | Extensibility events (incl. structured-output — see below) | `name`, `value` |
+| `CUSTOM` | Extensibility events, including structured output (see below) | `name`, `value` |
 
 See the [AG-UI protocol docs](https://docs.ag-ui.com/introduction) for the full event catalogue and exact field shapes.
 
 #### Transforming structured-output chunks
 
-There is **no separate `onStructuredOutputChunk` hook** — and you don't need one. When `chat()` is invoked with `outputSchema`, the structured-output chunks (the JSON `TEXT_MESSAGE_CONTENT` deltas, plus the `structured-output.start` / `structured-output.complete` CUSTOM events and any finalization `RUN_ERROR`) flow through the **same `onChunk` hook** as everything else. You transform, expand, or drop them exactly like any other chunk.
+There is **no separate `onStructuredOutputChunk` hook**, and you do not need one. When `chat()` is invoked with `outputSchema`, the structured-output chunks (the JSON `TEXT_MESSAGE_CONTENT` deltas, plus the `structured-output.start` / `structured-output.complete` CUSTOM events and any finalization `RUN_ERROR`) flow through the **same `onChunk` hook** as everything else. You transform, expand, or drop them exactly like any other chunk.
 
 How you distinguish them depends on which finalization path the adapter takes:
 
 - **Separate-finalization adapters** (`supportsCombinedToolsAndSchema()` does not return `true` for the current model/options): `ctx.phase === 'structuredOutput'` during the finalization call. Discriminate on the phase.
-- **Native-combined adapters** (modern OpenAI Chat Completions / Responses, Claude 4.5+, Gemini 3.x, Grok 4.x — see issue #605): the schema-constrained JSON is produced on the model's natural final turn, so **`ctx.phase` stays `'modelStream'`** — the `'structuredOutput'` phase never fires. Discriminate on the CUSTOM event name (`structured-output.start` / `structured-output.complete`) instead.
+- **Native-combined adapters** (modern OpenAI Chat Completions / Responses, Claude 4.5+, Gemini 3.x, and Grok 4.x, per issue #605): the schema-constrained JSON is produced on the model's natural final turn, so **`ctx.phase` stays `'modelStream'`**. The `'structuredOutput'` phase never fires. Discriminate on the CUSTOM event name (`structured-output.start` / `structured-output.complete`) instead.
 
 ```typescript ignore
 import { type ChatMiddleware } from "@tanstack/ai";
@@ -316,7 +358,7 @@ const redactStructuredOutput: ChatMiddleware = {
   onChunk: (ctx, chunk) => {
     // Separate-finalization path: the JSON streams as TEXT_MESSAGE_CONTENT
     // during the 'structuredOutput' phase. Transform the delta like any
-    // other text chunk — here, redact anything that looks like an SSN before
+    // other text chunk. Here, redact anything that looks like an SSN before
     // it reaches the client.
     if (
       ctx.phase === "structuredOutput" &&
@@ -341,11 +383,11 @@ const redactStructuredOutput: ChatMiddleware = {
 };
 ```
 
-> Why is there `onStructuredOutputConfig` but no `onStructuredOutputChunk`? Because the **config** shape genuinely differs at the structured-output boundary — it carries an `outputSchema` field that plain `ChatMiddlewareConfig` doesn't (see [onStructuredOutputConfig](#onstructuredoutputconfig)). **Chunks** are all just `StreamChunk` regardless of phase, so one `onChunk` plus `ctx.phase` (or the CUSTOM event name) covers every case — a parallel chunk hook would be redundant.
+> Why is there `onStructuredOutputConfig` but no `onStructuredOutputChunk`? Because the **config** shape differs at the structured-output boundary: it carries an `outputSchema` field that plain `ChatMiddlewareConfig` doesn't (see [onStructuredOutputConfig](#onstructuredoutputconfig)). **Chunks** are all just `StreamChunk` regardless of phase, so one `onChunk` plus `ctx.phase` (or the CUSTOM event name) covers every case. A parallel chunk hook is not necessary.
 
 ### onShouldContinue
 
-Called when the engine is deciding whether to start another agent-loop iteration (after a tool phase or between model turns). Combined with AND semantics across middleware **and** with `agentLoopStrategy` — any explicit `false` stops the loop. Return `true`, `void`, or `undefined` to allow continuation.
+Called when the engine is deciding whether to start another agent-loop iteration (after a tool phase or between model turns). Combined with AND semantics across middleware **and** with `agentLoopStrategy`: any explicit `false` stops the loop. Return `true`, `void`, or `undefined` to allow continuation.
 
 Does **not** abort the run: the stream finishes normally with the current messages. Use `ctx.abort()` only for a hard abort.
 
@@ -532,7 +574,7 @@ capability, then return those fields from `onConfig` when
 | --- | --- |
 | `onInterruptBoundary` | Nothing. It can only pause. |
 | `onInterruptResolution` | Pending-tool policy (`toolResume`) |
-| `onConfig` | `messages`, `systemPrompts`, `tools`, `modelOptions`, `metadata`, `reasoning`, `promptCache` |
+| `onConfig` | `messages`, `systemPrompts`, `tools`, `modelOptions`, `metadata`, `reasoning`, `promptCache`, `toolChoice` |
 
 The full resume order, plus an example that writes a user note into the
 system prompt, is in [Apply Answers](../interrupts/apply-answers).
@@ -599,7 +641,7 @@ The `hookCtx` provides:
 
 ### onAfterToolCall
 
-Called after each tool execution (or skip). All middleware run — there is no short-circuiting.
+Called after each tool execution (or skip). Every middleware runs, in array order.
 
 ```typescript
 import { type ChatMiddleware } from "@tanstack/ai";
@@ -626,9 +668,46 @@ The `info` object provides:
 | `toolCallId` | `string` | Tool call ID |
 | `ok` | `boolean` | Whether execution succeeded |
 | `duration` | `number` | Execution time in milliseconds |
-| `result` | `unknown` | Result (when `ok` is true) |
+| `result` | `unknown` | Result (when `ok` is true). After a `replaceResult` from an earlier middleware, the new result. |
 | `error` | `unknown` | Error (when `ok` is false) |
 
+#### Replace a tool result
+
+A tool can return more than the model needs, for example 500 rows or a long log. The model reads every token of it. Return `{ type: 'replaceResult', result }` to give the model and the stream a different result:
+
+```typescript
+import { type ChatMiddleware } from "@tanstack/ai";
+
+const firstTwentyRows: ChatMiddleware = {
+  name: "first-twenty-rows",
+  onAfterToolCall: (ctx, info) => {
+    if (!info.ok || !Array.isArray(info.result)) return;
+    if (info.result.length <= 20) return;
+    return {
+      type: "replaceResult",
+      result: {
+        rows: info.result.slice(0, 20),
+        omitted: info.result.length - 20,
+      },
+    };
+  },
+};
+```
+
+**Return values:**
+
+| Return | Effect |
+|--------|--------|
+| `void` / `undefined` | The result stays the same |
+| `{ type: 'replaceResult', result }` | The model gets `result`. The stream sends it in `TOOL_CALL_RESULT`, so the client shows it too. |
+
+Several middleware can replace the same result:
+
+- Each middleware gets the result of the middleware before it as `info.result`. The last replacement wins.
+- For example, with `middleware: [firstTwentyRows, summarize]`, `summarize` gets the 20 rows.
+- A failed call stays failed. The replacement becomes the error that the model reads.
+- A `skip` result from `onBeforeToolCall` also goes through this hook. `info.result` is the parsed skip result.
+
 ### Tool hook order in one turn
 
 When the model calls several server tools in one turn, the tools run at the same time:
@@ -683,10 +762,10 @@ Exactly **one** terminal hook fires per `chat()` invocation. They are mutually e
 > - `onStructuredOutputConfig` fires before the separate provider call, and `ctx.phase` is `'structuredOutput'` for its chunks.
 > - `onIteration` does **not** fire for finalization; it only fires for agent-loop iterations.
 > - `onFinish` fires after finalization completes. Its `info` object reflects the **agent loop's** terminal state.
-> - `info.content` — the agent loop's accumulated text. Separate-finalization JSON deltas are **not** included. Middleware can observe the completed result through the `structured-output.complete` CUSTOM event in `onChunk`.
-> - `info.usage` — the agent loop's last `RUN_FINISHED.usage`. For a tools-less structured-output run (no agent-loop iteration produces `RUN_FINISHED`), this is `undefined`. To capture finalization tokens, use `onUsage` — that hook fires for **every** `RUN_FINISHED` carrying usage, including the finalization call.
-> - `info.finishReason` — the agent loop's last `finishReason`. `null` when no agent-loop iteration produced `RUN_FINISHED` (e.g. a tools-less structured-output run).
-> - `info.duration` — wall-clock duration of the entire `chat()` invocation, including finalization.
+> - `info.content`: the agent loop's accumulated text. Separate-finalization JSON deltas are **not** included. Middleware can observe the completed result through the `structured-output.complete` CUSTOM event in `onChunk`.
+> - `info.usage`: the agent loop's last `RUN_FINISHED.usage`. For a tools-less structured-output run (no agent-loop iteration produces `RUN_FINISHED`), this is `undefined`. To capture finalization tokens, use `onUsage`. That hook fires for **every** `RUN_FINISHED` carrying usage, including the finalization call.
+> - `info.finishReason`: the agent loop's last `finishReason`. `null` when no agent-loop iteration produced `RUN_FINISHED` (e.g. a tools-less structured-output run).
+> - `info.duration`: wall-clock duration of the entire `chat()` invocation, including finalization.
 >
 > **Native-combined output:** Adapters with native-combined support produce the schema-constrained JSON in the regular agent-loop stream. `onStructuredOutputConfig` does not fire, `ctx.phase` remains `'modelStream'`, and `onIteration` fires for the iteration that produces the JSON. The JSON is agent-loop text, so `info.content` includes it. Middleware observes the `structured-output.complete` event in `onChunk` during the same phase.
 >
@@ -722,7 +801,7 @@ The `info` object for `onFinish` (`FinishInfo`):
 | `finishReason` | `string \| null` | The agent loop's last `finishReason`. `null` when no agent-loop iteration produced `RUN_FINISHED` (e.g. a tools-less `chat({ outputSchema })` run). |
 | `duration` | `number` | Total run duration in milliseconds, including any structured-output finalization. |
 | `content` | `string` | The agent loop's accumulated text content. Includes native-combined structured JSON; excludes separate-finalization JSON. Observe the completed result through the `structured-output.complete` CUSTOM event via `onChunk`. |
-| `usage` | `{ promptTokens; completionTokens; totalTokens } \| undefined` | **Optional.** The agent loop's last `RUN_FINISHED.usage`. **Does not include finalization tokens** — use `onUsage` to observe those. Always guard with `if (info.usage)` or `info.usage?.`. |
+| `usage` | `{ promptTokens; completionTokens; totalTokens } \| undefined` | **Optional.** The agent loop's last `RUN_FINISHED.usage`. **Does not include finalization tokens.** Use `onUsage` to observe those. Always guard with `if (info.usage)` or `info.usage?.`. |
 
 ## Context Object
 
@@ -847,13 +926,13 @@ const stream = chat({
 
 | Hook | Composition | Effect of Order |
 |------|------------|----------------|
-| `onConfig` | **Piped** — each receives previous output | Earlier middleware transforms first |
-| `onStructuredOutputConfig` | **Piped** — each receives previous output | Earlier middleware transforms first |
+| `onConfig` | **Piped**: each receives previous output | Earlier middleware transforms first |
+| `onStructuredOutputConfig` | **Piped**: each receives previous output | Earlier middleware transforms first |
 | `onStart` | Sequential | All run in order |
-| `onChunk` | **Piped** — chunks flow through each middleware | If first drops a chunk, later middleware never see it |
-| `onBeforeToolCall` | **First-win** — first non-void decision wins | Earlier middleware has priority |
-| `onShouldContinue` | **AND** — any explicit `false` stops the loop | Order only affects which middleware runs first when short-circuiting |
-| `onAfterToolCall` | Sequential | All run in order |
+| `onChunk` | **Piped**: chunks flow through each middleware | If first drops a chunk, later middleware never see it |
+| `onBeforeToolCall` | **First-win**: the first non-void decision wins | Earlier middleware has priority |
+| `onShouldContinue` | **AND**: any explicit `false` stops the loop | Order only affects which middleware runs first when short-circuiting |
+| `onAfterToolCall` | **Piped**: each receives the result of the previous `replaceResult` | The last replacement wins |
 | `onUsage` | Sequential | All run in order |
 | `onFinish/onAbort/onError` | Sequential | All run in order |
 
@@ -863,7 +942,7 @@ Middleware often need to **share state**. A provider middleware sets something u
 
 ### Creating a capability
 
-A capability is created with `createCapability<TValue>()('name')` — a **curried** call:
+A capability is created with `createCapability<TValue>()('name')`, a **curried** call:
 
 ```typescript
 import { createCapability } from "@tanstack/ai";
@@ -872,11 +951,11 @@ const counterCapability = createCapability<{ value: number }>()("counter");
 const [getCounter, provideCounter] = counterCapability;
 ```
 
-The currying is deliberate: you supply the **value type** explicitly (`<{ value: number }>`) while the **name literal** is inferred from the argument (`"counter"`). A single `createCapability<T>('name')` call can't do both — supplying `T` explicitly stops TypeScript inferring the name, collapsing it to `string` and defeating the compile-time coverage check that keys on the literal name.
+The currying is deliberate: you supply the **value type** explicitly (`<{ value: number }>`) while the **name literal** is inferred from the argument (`"counter"`). A single `createCapability<T>('name')` call cannot do both. Supplying `T` explicitly stops TypeScript inferring the name, collapsing it to `string` and defeating the compile-time coverage check that keys on the literal name.
 
 The returned `counterCapability` is a hybrid value:
 
-- It **destructures to `[get, provide]`** — the two accessors you use inside hooks.
+- It **destructures to `[get, provide]`**: the two accessors you use inside hooks.
 - It **is itself the identity** you list in `requires` / `provides`. There is no separate token to import.
 
 The accessors:
@@ -884,30 +963,30 @@ The accessors:
 | Accessor | Behavior |
 |----------|----------|
 | `getCounter(ctx)` | Returns the value. **Throws** if the capability was never provided. |
-| `getCounter(ctx, { optional: true })` | Returns `TValue \| undefined` — no throw when absent. |
+| `getCounter(ctx, { optional: true })` | Returns `TValue \| undefined`. No throw when absent. |
 | `provideCounter(ctx, value)` | Sets the value for this run. Call it from `setup`. |
 
-Equivalently, the context exposes `ctx.get(capability)`, `ctx.getOptional(capability)`, and `ctx.provide(capability, value)` — pass the capability handle directly. These are typed by the handle you pass (`ctx.get(counterCapability)` returns the value type), so `getCounter(ctx)` and `ctx.get(counterCapability)` are interchangeable — use whichever reads better in your hook.
+Equivalently, the context exposes `ctx.get(capability)`, `ctx.getOptional(capability)`, and `ctx.provide(capability, value)`. Pass the capability handle directly. These are typed by the handle you pass (`ctx.get(counterCapability)` returns the value type), so `getCounter(ctx)` and `ctx.get(counterCapability)` are interchangeable. Use whichever reads better in your hook.
 
 > **Capability names must be unique across your app.** The compile-time coverage check keys on the name literal (runtime keys on the handle reference), so two capabilities sharing a name will conflate in the type-level check.
 
 ### The `setup` hook
 
-Provisioning happens in a dedicated `setup(ctx)` hook. It **runs first** — before any `onConfig` (init), across all middleware in array order — so that by the time the rest of the lifecycle begins, every capability is in place. `setup` receives the stable `ChatMiddlewareContext` (not the mutable config), and may be async.
+Provisioning happens in a dedicated `setup(ctx)` hook. It **runs first**, before any `onConfig` (init), across all middleware in array order. So by the time the rest of the lifecycle begins, every capability is in place. `setup` receives the stable `ChatMiddlewareContext` (not the mutable config), and may be async.
 
 ### `requires` / `provides` / `optionalRequires`
 
-Three array fields on a middleware declare its capability contract. Each is a `ReadonlyArray<CapabilityHandle>` — you list the capability handles themselves:
+Three array fields on a middleware declare its capability contract. Each is a `ReadonlyArray<CapabilityHandle>`. You list the capability handles themselves:
 
 | Field | Meaning |
 |-------|---------|
 | `provides` | Capabilities this middleware sets up. Each one **must** be `provide`d inside `setup`, or `chat()` throws after the setup phase. |
 | `requires` | Capabilities this middleware reads. `chat()` validates (compile time + runtime) that some earlier middleware provides each one. |
-| `optionalRequires` | Capabilities used **if present** but not required. Non-gating — never causes a validation error. Read with `getX(ctx, { optional: true })`. |
+| `optionalRequires` | Capabilities used **if present** but not required. Non-gating: never causes a validation error. Read with `getX(ctx, { optional: true })`. |
 
 ### Array example
 
-Author middleware with `defineChatMiddleware` — it sharpens the `requires` / `provides` tuple types so the coverage check and builder can read them precisely. Here a **provider** sets up a counter in `setup`, and a **consumer** reads it in a hook:
+Author middleware with `defineChatMiddleware`. It sharpens the `requires` / `provides` tuple types so the coverage check and builder can read them precisely. Here a **provider** sets up a counter in `setup`, and a **consumer** reads it in a hook:
 
 ```typescript
 import {
@@ -950,7 +1029,7 @@ const stream = chat({
 });
 ```
 
-If you drop `withCounter` from the array, `chat()` reports a compile-time error at the `middleware` option naming the missing `"counter"` capability — and throws at runtime before the adapter is ever called.
+If you drop `withCounter` from the array, `chat()` reports a compile-time error at the `middleware` option naming the missing `"counter"` capability, and throws at runtime before the adapter is ever called.
 
 ### Builder example
 
@@ -986,7 +1065,7 @@ const countsChunks = defineChatMiddleware({
 
 const middleware = createChatMiddleware()
   .use(withCounter) // provides "counter"
-  .use(countsChunks) // requires "counter" — OK, already provided above
+  .use(countsChunks) // requires "counter": OK, already provided above
   .build();
 
 const stream = chat({
@@ -996,7 +1075,7 @@ const stream = chat({
 });
 ```
 
-Swap the two `.use()` calls (`.use(countsChunks).use(withCounter)`) and the builder rejects it at the `.use(countsChunks)` line — the consumer is ordered before its provider, so `"counter"` isn't in the provided set yet.
+Swap the two `.use()` calls (`.use(countsChunks).use(withCounter)`) and the builder rejects it at the `.use(countsChunks)` line. The consumer is ordered before its provider, so `"counter"` isn't in the provided set yet.
 
 ### Validation guarantees
 
@@ -1004,13 +1083,13 @@ The capability system fails loudly and early:
 
 - **Compile-time coverage.** A required capability that nothing provides surfaces as a type error at the `middleware` option. This is enforced two ways: an **array coverage check** on `middleware: [...]`, and the order-aware **`createChatMiddleware()` builder** (which additionally enforces ordering).
 - **Runtime coverage.** Even if types are bypassed, `chat()` validates coverage and **throws before the adapter runs** if a required capability is missing.
-- **Post-`setup` assertion.** If a middleware declares a capability in `provides` but never calls its `provide` accessor during `setup`, `chat()` throws after the setup phase — you can't silently forget to provision.
+- **Post-`setup` assertion.** If a middleware declares a capability in `provides` but never calls its `provide` accessor during `setup`, `chat()` throws after the setup phase. You cannot forget to provision without an error.
 - **Duplicate provide → last-wins + warning.** If two middleware provide the same capability, the last write wins and a development warning is emitted.
 - **Unique names.** Capability `name`s must be unique across your app; the compile-time coverage check keys on the name literal (runtime keys on the handle reference).
 
 ## Built-in Middleware
 
-TanStack AI ships ready-made middleware for common cases — caching tool results, redacting streamed text, and OpenTelemetry tracing:
+TanStack AI ships ready-made middleware for common cases: caching tool results, redacting streamed text, and OpenTelemetry tracing:
 
 | Middleware | Import | What it does |
 |------------|--------|--------------|
@@ -1195,6 +1274,7 @@ import type {
   ToolCallHookContext,
   BeforeToolCallDecision,
   AfterToolCallInfo,
+  AfterToolCallDecision,
   IterationInfo,
   ToolPhaseCompleteInfo,
   UsageInfo,
@@ -1219,8 +1299,9 @@ import type {
 
 ## Next Steps
 
-- [Built-in Middleware](./built-in-middleware) — `toolCacheMiddleware`, `contentGuardMiddleware`, `otelMiddleware`
+- [Built-in Middleware](./built-in-middleware): `toolCacheMiddleware`, `contentGuardMiddleware`, `otelMiddleware`
 - [Compaction](./compaction): keep long chats under the context limit with `withCompaction`
-- [OpenTelemetry](./otel) — emit traces and metrics via `otelMiddleware`- [Tools](../tools/tools) — Learn about the isomorphic tool system
-- [Agentic Cycle](../chat/agentic-cycle) — Understand the multi-step agent loop
-- [Streaming](../chat/streaming) — How streaming works in TanStack AI
+- [OpenTelemetry](./otel): emit traces and metrics via `otelMiddleware`
+- [Tools](../tools/tools): learn about the isomorphic tool system
+- [Agentic Cycle](../chat/agentic-cycle): understand the multi-step agent loop
+- [Streaming](../chat/streaming): how streaming works in TanStack AI
diff --git a/docs/chat/subagents.md b/docs/chat/subagents.md
index e34dd64678..9cf1210a29 100644
--- a/docs/chat/subagents.md
+++ b/docs/chat/subagents.md
@@ -219,7 +219,7 @@ const stream = chat({
 - `chat()` checks each input against the schema before the child starts. If an input does not match, `chat()` throws, and the child does not start.
 - `run` reads the input as `ctx.input`. A resumed child gets the same input.
 
-**Without a router.** The library adds one synthetic server tool per agent. The main model calls that tool. The public stream still emits `SUBAGENT_STARTED` / `SUBAGENT_FINISHED` (or `SUBAGENT_ERROR`) and nested parts. The UI does not treat spawn as a normal tool card. The child's events stream while the tool runs, and the child's text becomes the tool result. The child reads the conversation as it is at that tool call.
+**Without a router.** The library adds one synthetic server tool per agent. The main model calls that tool. The public stream still emits `SUBAGENT_STARTED` / `SUBAGENT_FINISHED` (or `SUBAGENT_ERROR`) and nested parts. The UI does not treat spawn as a normal tool card. The child's events stream while the tool runs, and the child's text becomes the tool result. The child reads the conversation as it is at that tool call. For one tool that can start every agent, see [Give the model one subagent tool](#give-the-model-one-subagent-tool).
 
 ## Let the model write the brief
 
@@ -271,6 +271,90 @@ const stream = chat({
 
 To show the brief in the UI, see [Show the brief on a card](#show-the-brief-on-a-card).
 
+## Give the model one subagent tool
+
+Without a router, the model gets one tool per agent, and each call starts a new child. The model cannot send a follow-up to a child that already answered. Set `tool: 'single'`. The model then gets one tool, `subagent`, and names the agent in each call. A call can also continue a child from an earlier turn.
+
+```ts
+import {
+  chat,
+  chatParamsFromRequest,
+  defineAgent,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { memoryPersistence, withPersistence } from '@tanstack/ai-persistence'
+import { z } from 'zod'
+
+const researcher = defineAgent({
+  name: 'researcher',
+  description: 'Researches one question and returns sourced findings',
+  inputSchema: z.object({ question: z.string() }),
+  run: (ctx) =>
+    ctx.chat({
+      adapter: openaiText('gpt-6.1-sol'),
+      messages: [{ role: 'user', content: ctx.input.question }],
+    }),
+})
+
+const writer = defineAgent({
+  name: 'writer',
+  description: 'Writes and edits drafts',
+  run: (ctx) => ctx.chat({ adapter: openaiText('gpt-6.1-sol') }),
+})
+
+// A continued child loads from this store. Use a durable backend in production.
+const persistence = memoryPersistence()
+
+export async function POST(request: Request) {
+  const params = await chatParamsFromRequest(request)
+  const stream = chat({
+    adapter: openaiText('gpt-6.1-sol'),
+    messages: params.messages,
+    threadId: params.threadId,
+    runId: params.runId,
+    middleware: [withPersistence(persistence)],
+    subagents: { agents: [researcher, writer], tool: 'single' },
+  })
+  return toServerSentEventsResponse(stream)
+}
+```
+
+The model fills these fields of the tool input:
+
+- `agent`: the agent name. Each call needs it.
+- `input`: the input of an agent with `inputSchema`. That agent needs it.
+- `prompt`: the task as text, for an agent without `inputSchema`. The child gets it as the last user message.
+- `sessionId`: the `subagentRunId` of an earlier result. The call continues that child.
+- `background`: `true` starts the child and returns at once. Only a harness can do this. See [Run agents from a harness](../harness/subagents#give-the-model-one-subagent-tool).
+
+On the client, each child is a `type: 'subagent'` part, the same as with one tool per agent. `part.subagent.name` is the agent name.
+
+### Continue a child
+
+Each result gives the model the `subagentRunId` of the child. The model uses it in a later turn:
+
+1. The model calls `{ "agent": "writer", "prompt": "Draft a post about tides" }`.
+2. It gets `{ "subagentRunId": "subagent-1767225600000-x7k2m9q", "result": "Tides rise twice a day..." }`.
+3. In the next turn, it calls `{ "agent": "writer", "sessionId": "subagent-1767225600000-x7k2m9q", "prompt": "Make it shorter" }`.
+
+The writer gets its stored transcript, then `Make it shorter` as the last user message.
+
+- `sessionId` needs `withPersistence` on the parent `chat()`. The stored child comes from that store.
+- A thread can continue only its own children. An id from another thread gives the tool error `Unknown sessionId "..."`.
+- The stream uses the same `subagentRunId`, so the client shows the new work on the card with that id.
+
+### Wrong calls
+
+A wrong call returns to the model as a tool error, and the run continues. For example:
+
+- `Agent "researcher" takes input, not prompt.`
+- `Agent "researcher" needs input.`
+- `sessionId needs a persistence store.`
+- `background needs a harness host.`
+
+If an agent or a tool already has the name `subagent`, `chat()` throws before the run starts.
+
 ## Return a value, or call any activity
 
 A child does not have to be a chat. It can make an image, or return a plain value that the parent model reads as the tool result. Call the activity on `ctx` and return what it gives you:
@@ -722,6 +806,8 @@ function Briefs({ message }: { message: UIMessage }) {
 
 A child that a router started has no `parentToolCallId`, so `briefOf` finds no brief for it.
 
+With `tool: 'single'`, that tool call is a call of the `subagent` tool. The brief is in the `input` field or the `prompt` field of its input.
+
 ### Style one child's parts
 
 The researcher's reasoning and tool calls use the root widgets by default. To make them look different on the researcher card only, pass widgets to that card's `Parts`:
diff --git a/docs/harness/subagents.md b/docs/harness/subagents.md
index 6dc80dc321..388f164ea9 100644
--- a/docs/harness/subagents.md
+++ b/docs/harness/subagents.md
@@ -219,6 +219,78 @@ export const lead = defineHarness({
 
 The tool name comes from the harness name, with characters other than letters, digits, `_`, and `-` changed to `_`. Pass `name` to pick another.
 
+## Give the model one subagent tool
+
+In a long session, the model can need a follow-up from a child that it started earlier. It can also need to start slow work and answer the user while the work runs. Set `subagents.tool` to `'single'`, and the model gets one `subagent` tool for every agent:
+
+```ts
+import { defineAgent } from '@tanstack/ai'
+import { defineHarness } from '@tanstack/ai-harness'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+const researcher = defineAgent({
+  name: 'researcher',
+  description: 'Researches one question and returns sourced findings',
+  inputSchema: z.object({ question: z.string() }),
+  run: (ctx) =>
+    ctx.chat({
+      adapter: openaiText('gpt-6.1-sol'),
+      messages: [{ role: 'user', content: ctx.input.question }],
+      stream: false,
+    }),
+})
+
+const writer = defineAgent({
+  name: 'writer',
+  description: 'Writes and edits drafts',
+  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'),
+  subagents: { agents: [researcher, writer], tool: 'single' },
+})
+```
+
+The tool input is the same as in `chat()`: `agent`, then `input` or `prompt`, plus `sessionId` and `background`. See [Give the model one subagent tool](../chat/subagents#give-the-model-one-subagent-tool). In a harness:
+
+- `sessionId` needs no more setup, because the host stores each child.
+- `background: true` gives the model `{ subagentRunId, result: { status: 'started' } }` at once. The child runs as a background agent of the session.
+- When a background child ends, the session starts a new turn. Its message starts with `Background agent researcher finished:` or `Background agent researcher failed:`.
+
+What a [session view](./custom-ui#what-the-state-holds) shows:
+
+- A child that the tool runs is an `agent` part on the assistant message.
+- A background child is in `state.agents` while it runs.
+- With a session index, each child gets an entry with its `parentThreadId` and `parentToolCallId`. See [Turn on the session index](./sessions#turn-on-the-session-index).
+
+Known limits:
+
+- A background child cannot be continued by its `sessionId`. If the model needs follow-ups, start the child without `background`.
+- Only the turns of the session can start a background child. A child that calls the `subagent` tool with `background` gets the tool error `background needs a harness host.`
+- A call with `background` and `sessionId` gets the tool error `background cannot continue a sessionId.`
+
+### Agents from plugins
+
+The `tool` setting also applies to the agents that plugins add. For example, the `agents()` plugin adds its subagent profiles, such as `general` and `explore`. With `subagents: { agents: [], tool: 'single' }`, they share one `subagent` tool:
+
+```ts
+import { defineHarness } from '@tanstack/ai-harness'
+import { agents } from '@tanstack/ai-harness/plugins'
+import { openaiText } from '@tanstack/ai-openai'
+
+export const coder = defineHarness({
+  name: 'acme/coder',
+  adapter: openaiText('gpt-6.1-sol'),
+  subagents: { agents: [], tool: 'single' },
+  plugins: () => [agents({ adapter: () => openaiText('gpt-6.1-sol') })],
+})
+```
+
+The permission rules of an `agents()` profile apply only while that profile is the primary agent. They do not apply inside a child run.
+
 ## Stay within limits
 
 A harness always limits its children. Without `subagents.limits`, it uses a depth of 2, 3 children at once, and 12 children per tree. Agents started from code count against the same limits:
@@ -241,5 +313,5 @@ See [subagent limits](../chat/subagents) for what each limit does.
 - Commands and plugins that start typed agents, alone or in groups.
 - Background agents that continue on the next host after a crash, with steps that do not run twice.
 - A router that sends each turn to the right agent, and gives each agent its input.
-- Harnesses that call other harnesses as tools.
+- Harnesses that call other harnesses as tools, and one `subagent` tool that continues a child or starts it in the background.
 - A tree of children that stays within limits.
diff --git a/docs/migration/migration-from-vercel-ai.md b/docs/migration/migration-from-vercel-ai.md
index 19c717912b..e1a1bd4bff 100644
--- a/docs/migration/migration-from-vercel-ai.md
+++ b/docs/migration/migration-from-vercel-ai.md
@@ -135,7 +135,7 @@ Options accepted by `streamText` as of AI SDK v6, and where each lives in TanSta
 | `messages` | `messages` | Same concept; content parts differ (see [Multimodal](#multimodal-content)) |
 | `system: 'You are…'` | `systemPrompts: ['You are…']` | Root-level `string[]` |
 | `tools: { name: tool({…}) }` | `tools: [toolInstance, …]` | Array of tool instances instead of a keyed object |
-| `toolChoice: 'auto' \| 'required' \| 'none' \| { type, toolName }` | `modelOptions.toolChoice` (provider-specific) | Not a top-level option — set on the adapter's `modelOptions` |
+| `toolChoice: 'auto' \| 'required' \| 'none' \| { type, toolName }` | `toolChoice: 'auto' \| 'required' \| 'none' \| { type: 'tool', name }` | `toolName` is `name`. See [Choose when the model calls a tool](../tools/tools#choose-when-the-model-calls-a-tool) |
 | `activeTools: string[]` | Filter `tools` yourself, or use `prepareStep` equivalent via middleware | No dedicated option — see [Middleware](#middleware) for dynamic tool filtering |
 | `maxOutputTokens` | `maxTokens` | Renamed to match the original OpenAI naming |
 | `temperature` | `temperature` | Same |
diff --git a/docs/tools/tools.md b/docs/tools/tools.md
index 3ed9f3067c..4ed5003148 100644
--- a/docs/tools/tools.md
+++ b/docs/tools/tools.md
@@ -222,7 +222,7 @@ const getWeatherDef = toolDefinition({
   outputSchema,
 });
 
-// With a raw JSON Schema, `args` is `unknown` — narrow it before use
+// With a raw JSON Schema, `args` is `unknown`. Narrow it before use
 // (prefer a Zod schema for automatic typing).
 const getWeatherServer = getWeatherDef.server(async (args) => {
   if (typeof args !== "object" || args === null || !("location" in args)) {
@@ -383,7 +383,7 @@ const addToCartClient = addToCartDef.client((input) => {
 });
 ```
 
-On the server, pass either the definition (for client execution) or the server implementation — in separate `chat()` calls:
+On the server, pass either the definition (for client execution) or the server implementation, in separate `chat()` calls:
 
 ```typescript group=tools
 const messages = [{ role: 'user' as const, content: 'Add item abc to my cart' }]
@@ -476,9 +476,96 @@ const stream = chat({
 
 Client tools do not change: the client runs them as their calls arrive.
 
+## Choose when the model calls a tool
+
+By default, the model decides to call a tool or not. Sometimes a tool call must come first, for example a weather lookup before the model gives advice. Sometimes the model must answer in text. `toolChoice` sets this for a model call.
+
+`toolChoice` on `chat()` applies to every model call of the run. With `'required'` or a named tool, the model calls a tool on each call and never writes a text answer. The run then stops at the loop limit, after a tool result. Use a forced value in one of these two ways.
+
+**Force a tool on the first call only.** Return `toolChoice` from a middleware:
+
+```ts group=tool-choice
+import { chat, toolDefinition, type ChatMiddleware } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+const getWeather = toolDefinition({
+  name: 'get_weather',
+  description: 'Get the current weather for a city',
+  inputSchema: z.object({ city: z.string() }),
+}).server(async ({ city }) => ({ city, temperature: 21 }))
+
+const weatherFirst: ChatMiddleware = {
+  name: 'weather-first',
+  onConfig: (ctx) => {
+    if (ctx.phase === 'beforeModel' && ctx.iteration === 0) {
+      return { toolChoice: { type: 'tool', name: 'get_weather' } }
+    }
+  },
+}
+
+const stream = chat({
+  adapter: openaiText('gpt-6.1-sol'),
+  messages: [{ role: 'user', content: 'What should I wear in Paris today?' }],
+  tools: [getWeather],
+  middleware: [weatherFirst],
+})
+```
+
+The first call must call `get_weather`. A value from middleware applies to that call only, so the next call uses the `chat()` option again. Here that is the provider default, and the model answers with the forecast.
+
+**Run one step only.** Set `agentLoopStrategy: maxIterations(1)`. The model makes one call, the tool runs, and the run ends:
+
+```ts group=tool-choice
+import { maxIterations } from '@tanstack/ai'
+
+const oneLookup = chat({
+  adapter: openaiText('gpt-6.1-sol'),
+  messages: [{ role: 'user', content: 'Weather in Oslo?' }],
+  tools: [getWeather],
+  toolChoice: 'required',
+  agentLoopStrategy: maxIterations(1),
+})
+```
+
+To end a run with a text answer, return `{ toolChoice: 'none' }` on its last call. See [Change the tool choice of a call](../advanced/middleware#change-the-tool-choice-of-a-call).
+
+The values:
+
+| Value | What the model does |
+| --- | --- |
+| `'auto'` | It decides. |
+| `'none'` | It calls no tool. |
+| `'required'` | It must call a tool. |
+| `{ type: 'tool', name }` | It must call the tool with this name. |
+
+The rules for every adapter:
+
+- If the request has no tools, the adapter sends no tool choice.
+- A provider tool choice in `modelOptions` wins over `toolChoice`, for example `tool_choice` on OpenAI.
+- The adapter sends the name in `{ type: 'tool', name }` as you give it. It does not check that a tool has this name.
+
+### Provider notes
+
+Some providers change or ignore some values:
+
+- **OpenAI, Grok, Groq, Mistral, OpenRouter, and the other OpenAI-compatible adapters**: the adapter sends the value as the provider tool choice.
+- **Anthropic**: if the request cannot force a tool, `'required'` and a named tool become `'auto'`.
+  - `claude-fable-5-1`, `claude-opus-5-5`, and `claude-sonnet-5-5` never take a forced tool.
+  - No Claude model takes a forced tool while thinking is on.
+- **Amazon Bedrock (Converse API)**:
+  - The Anthropic rule applies to the Claude models, and also to `claude-mythos-5-1`.
+  - Converse has no `none` value, so `'none'` sends no tools.
+  - After a tool call in the history, Bedrock needs the tools. Then `'none'` sends them with `auto`, and the model can still call a tool.
+  - AWS documents a named tool for Claude and Nova models only.
+- **Gemini**: the value becomes `functionCallingConfig`.
+  - The modes are `AUTO`, `NONE`, and `ANY`. A named tool is `ANY` with `allowedFunctionNames`.
+  - With only provider tools, such as Google Search, Gemini gets no tool config.
+- **Ollama**: Ollama has no tool choice, so the adapter ignores `toolChoice`. See [Ollama](../adapters/ollama#tool-choice).
+
 ## Progress Events and Runtime Context
 
-A server tool's `.server()` implementation receives a second argument, the `ToolExecutionContext` — `{ context, toolCallId, emitCustomEvent }`. Use `emitCustomEvent` to stream typed progress to the client while the tool runs, and `context` to read request-scoped dependencies (auth, DB clients, etc.):
+A server tool's `.server()` implementation receives a second argument, the `ToolExecutionContext`: `{ context, toolCallId, emitCustomEvent }`. Use `emitCustomEvent` to stream typed progress to the client while the tool runs, and `context` to read request-scoped dependencies (auth, DB clients, etc.):
 
 ```typescript
 import { toolDefinition } from "@tanstack/ai";
@@ -528,7 +615,7 @@ Tools go through different states during execution:
 
 Once arguments (and approval, if required) are in, the result appears as `part.output` on the tool-call part and as a separate sibling `tool-result` part whose `state` is `complete` or `error`. See [Tool Architecture](./tool-architecture) for the full state model.
 
-> **Tip:** If your use case involves calling multiple tools with complex logic (filtering, aggregation, parallel calls), consider [Code Mode](../code-mode/code-mode) — it lets the LLM write a TypeScript program that orchestrates tools in a single execution instead of one tool call at a time.
+> **Tip:** If your use case involves calling multiple tools with complex logic (filtering, aggregation, parallel calls), consider [Code Mode](../code-mode/code-mode). It lets the LLM write a TypeScript program that orchestrates tools in a single execution instead of one tool call at a time.
 
 ## Next Steps
 

From af46c2d91f92f8f883315af081b8d23becd067c2 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 17:30:23 +0200
Subject: [PATCH 260/286] docs(harness): the coding tools, and running them in
 a sandbox

- Coding tools: install with the optional peers, each tool, permissions and
  approvals, outside paths, and the working folder.
- Sandbox and extend the coding tools: sandboxWorkspaceBackend, your own
  backend, WorkspaceHooks, formatter(), and boundToolOutput.
- Thread settings import workspaceTools from plugins/coding.
---
 docs/harness/coding-tools-backends.md | 263 ++++++++++++++++++++++++++
 docs/harness/coding-tools.md          | 253 +++++++++++++++++++++++++
 docs/harness/thread-settings.md       |   2 +-
 docs/sandbox/tools.md                 |   4 +
 4 files changed, 521 insertions(+), 1 deletion(-)
 create mode 100644 docs/harness/coding-tools-backends.md
 create mode 100644 docs/harness/coding-tools.md

diff --git a/docs/harness/coding-tools-backends.md b/docs/harness/coding-tools-backends.md
new file mode 100644
index 0000000000..573b2bde5c
--- /dev/null
+++ b/docs/harness/coding-tools-backends.md
@@ -0,0 +1,263 @@
+---
+title: Sandbox and extend the coding tools
+id: harness-coding-tools-backends
+order: 7
+description: "Run the coding tools in a sandbox or on your own backend, format each written file, and keep tool output small."
+keywords:
+  - tanstack ai
+  - harness
+  - coding agent
+  - workspace tools
+  - sandbox
+  - formatter
+  - workspace hooks
+---
+
+Your agent must work on files that are not on this machine, or on code that you do not trust. Or you want code to run after each write, like a formatter. The [coding tools](./coding-tools) send every read, write, and command through a backend, and they run hooks after each read and write. This page shows how to change both.
+
+## Run the tools in a sandbox
+
+By default, the tools run on your machine, with the rights of your user. For code that you do not trust, run them in a sandbox. `sandboxWorkspaceBackend()` sends every read, write, and command to the sandbox.
+
+1. Install the sandbox packages:
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: @tanstack/ai-sandbox @tanstack/ai-sandbox-docker
+vue: @tanstack/ai-sandbox @tanstack/ai-sandbox-docker
+solid: @tanstack/ai-sandbox @tanstack/ai-sandbox-docker
+svelte: @tanstack/ai-sandbox @tanstack/ai-sandbox-docker
+preact: @tanstack/ai-sandbox @tanstack/ai-sandbox-docker
+angular: @tanstack/ai-sandbox @tanstack/ai-sandbox-docker
+octane: @tanstack/ai-sandbox @tanstack/ai-sandbox-docker
+vanilla: @tanstack/ai-sandbox @tanstack/ai-sandbox-docker
+
+<!-- ::end:tabs -->
+
+2. Start a sandbox, and give its backend to `workspaceTools()`:
+
+```ts group=harness-coding-tools-sandbox
+import { defineHarness } from '@tanstack/ai-harness'
+import { permissions } from '@tanstack/ai-harness/plugins'
+import { workspaceTools } from '@tanstack/ai-harness/plugins/coding'
+import { openaiText } from '@tanstack/ai-openai'
+import { sandboxWorkspaceBackend } from '@tanstack/ai-sandbox/harness'
+import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
+
+const sandbox = await dockerSandbox({ image: 'node:22' }).create({})
+// Without `dir`, the clone goes to the workspace root, /workspace.
+await sandbox.git.clone({ url: 'https://github.com/acme/web-app.git' })
+
+const root = '/workspace'
+
+export const sandboxed = defineHarness({
+  name: 'acme/sandboxed-coder',
+  adapter: openaiText('gpt-5.6'),
+  plugins: () => [
+    permissions({ root }),
+    workspaceTools({ root, backend: sandboxWorkspaceBackend(sandbox) }),
+  ],
+})
+```
+
+3. When you are done, stop the sandbox with `await sandbox.destroy()`.
+
+Every provider works. Get the handle from `create()`, or from `resume()` for a sandbox that runs already. See [Providers](../sandbox/providers).
+
+In a sandbox, some things are different:
+
+- Paths are POSIX paths in the sandbox, like `/workspace/src/a.ts`, also on a Windows host.
+- The tools do not check where links lead. The sandbox backend has no `realpath`.
+- `background: true` needs a sandbox with `capabilities.backgroundProcesses`.
+- A sandbox with `capabilities.killableProcesses` off cannot stop a command after the time limit. The call returns, and the command continues in the sandbox.
+- `list_files` and `grep` use `rg` in the sandbox. The `@vscode/ripgrep` binary is a host file, so the sandbox does not use it.
+
+## Write your own backend
+
+A `WorkspaceBackend` is where the tools read and write files and run commands. Write one for another place, for example a remote machine. Every path that the tools give it is absolute.
+
+The backend must have:
+
+| Method | What it does |
+| --- | --- |
+| `readFile(path)` | Gives the bytes of a file. Throws when there is no file. |
+| `writeFile(path, data)` | Creates or replaces a file. Creates the missing parent folders. |
+| `stat(path)` | Gives `{ type, size, mtimeMs }`, or `undefined` when nothing is at `path`. |
+| `readdir(path)` | Gives the entries of a folder. A link has the type `'link'`. |
+| `exec(command, options)` | Runs a shell command and waits. Gives `{ exitCode, stdout, stderr }`. |
+
+`exec` resolves with the exit code of a command that fails. It does not throw. After `options.timeoutMs`, it stops the command with every process that it started, and gives exit code 124.
+
+The backend can also have:
+
+| Member | What it does | Without it |
+| --- | --- | --- |
+| `shell` | `'sh'` or `'cmd'`. Sets the path style and how arguments are quoted. | `sh` quotes, and the path style of this machine. |
+| `remove(path)` | Removes one file. | `patch` cannot delete or move files. |
+| `realpath(path)` | Gives the path with every link resolved. | The tools do not check links. |
+| `spawn(command, options)` | Starts a command in the background. | `background: true` gives an error. |
+
+The fastest start is to wrap `hostBackend`. This backend logs each command before it runs:
+
+```ts group=harness-coding-tools-backends
+import { hostBackend, workspaceTools } from '@tanstack/ai-harness/plugins/coding'
+import type { WorkspaceBackend } from '@tanstack/ai-harness/plugins/coding'
+
+const root = process.cwd()
+
+const logged: WorkspaceBackend = {
+  ...hostBackend,
+  exec: (command, options) => {
+    console.log(`$ ${command}`)
+    return hostBackend.exec(command, options)
+  },
+}
+
+export const loggedTools = workspaceTools({ root, backend: logged })
+```
+
+Only `hostBackend` itself uses the `@vscode/ripgrep` binary. A wrapped backend uses `rg` on the `PATH`.
+
+## Run code after a read or a write
+
+Another plugin can add code that runs after the tools read or write a file. Add a `WorkspaceHooks` item:
+
+```ts group=harness-coding-tools-backends
+import { definePlugin } from '@tanstack/ai-harness'
+import { WorkspaceHooks } from '@tanstack/ai-harness/plugins/coding'
+
+export const generatedFiles = definePlugin({
+  name: 'acme/generated-files',
+  setup: () => ({
+    contribute: [
+      WorkspaceHooks.item({
+        afterRead: async (path) =>
+          path.endsWith('.gen.ts')
+            ? 'This file is generated. Change its source, not this file.'
+            : undefined,
+        afterWrite: async (path) => {
+          console.log(`changed ${path}`)
+        },
+      }),
+    ],
+  }),
+})
+```
+
+- `afterRead` gets the absolute path. The text that it gives is added after the lines that `read_file` shows.
+- `afterWrite` runs after `write_file`, `edit_file`, and `patch`.
+- A hook runs while the tool holds the lock on that path. A hook that throws fails the tool call.
+
+Add the plugin next to the tools: `plugins: () => [workspaceTools({ root }), generatedFiles]`.
+
+## Format each file after a write
+
+The model writes code that your formatter changes later, and the diff gets noisy. `formatter()` formats each file that the tools write:
+
+```ts group=harness-coding-tools-backends
+import { defineHarness } from '@tanstack/ai-harness'
+import { permissions } from '@tanstack/ai-harness/plugins'
+import { formatter } from '@tanstack/ai-harness/plugins/coding'
+import { openaiText } from '@tanstack/ai-openai'
+
+export const formatted = defineHarness({
+  name: 'acme/formatted-coder',
+  adapter: openaiText('gpt-5.6'),
+  plugins: () => [
+    permissions({ root }),
+    workspaceTools({ root }),
+    formatter({ root }),
+  ],
+})
+```
+
+At the first write of a session, `formatter()` looks at the files in `root`. For each file, the first formatter that the project uses for that file type runs.
+
+For JavaScript, TypeScript, JSON, CSS, and other web files:
+
+| Formatter | Runs when `root` has |
+| --- | --- |
+| prettier | `.prettierrc*`, `prettier.config.*`, or a `prettier` field in `package.json` |
+| biome | `biome.json` or `biome.jsonc` |
+| oxfmt | `.oxfmtrc*`, or `oxfmt` in the `devDependencies` |
+
+These three run with `npx --no-install`, so the project must have them installed.
+
+For other languages:
+
+| Formatter | Files | Runs when `root` has |
+| --- | --- | --- |
+| ruff | `.py`, `.pyi` | `ruff.toml`, `.ruff.toml`, or `[tool.ruff]` in `pyproject.toml` |
+| gofmt | `.go` | `go.mod` |
+| rustfmt | `.rs` | `Cargo.toml` |
+
+Add your own formatter. Your formatters come before the built-in ones:
+
+```ts group=harness-coding-tools-backends
+export const withToml = formatter({
+  root,
+  formatters: [
+    {
+      name: 'taplo',
+      extensions: ['.toml'],
+      command: (file) => `taplo fmt ${file}`,
+    },
+  ],
+})
+```
+
+- `command` gets the absolute path, already quoted for the shell.
+- `when(project)` limits a formatter to some projects. Without it, the formatter is used in every project.
+- `builtins: false` turns the built-in formatters off.
+- `timeoutMs` limits each run. The default is 20 seconds.
+- In a sandbox, give `formatter()` the same `backend` as `workspaceTools()`.
+
+A formatter that fails, stops at the time limit, or is not installed does not fail the tool call. The file stays as the tool wrote it, and the plugin sends `FormatFailed`:
+
+```ts group=harness-coding-tools-backends
+import { FormatFailed } from '@tanstack/ai-harness/plugins/coding'
+
+export const formatAlerts = definePlugin({
+  name: 'acme/format-alerts',
+  setup: (ctx) => {
+    ctx.on(FormatFailed, (failure) =>
+      console.warn(`${failure.path}: ${failure.message}`),
+    )
+  },
+})
+```
+
+Clients get the same event as a `harness.plugin.event` with the name `tanstack/formatter:failed`.
+
+## Keep tool output small
+
+One tool result with a full log or a big JSON file fills the context of the model. `boundToolOutput()` cuts every tool result that is too long:
+
+```ts group=harness-coding-tools-backends
+import { boundToolOutput } from '@tanstack/ai-harness/plugins'
+
+export const bounded = defineHarness({
+  name: 'acme/bounded-coder',
+  adapter: openaiText('gpt-5.6'),
+  plugins: () => [
+    workspaceTools({ root }),
+    boundToolOutput({ dir: '.agent/tool-output' }),
+  ],
+})
+```
+
+- A result over 2000 lines or 50 KiB keeps its first lines and gets a note. Set other limits with `maxLines` and `maxBytes`.
+- With `dir`, the full output goes to a file in `dir`, and the note gives the path. Files older than `retentionDays` (default 7) are removed.
+- It cuts the result of every tool, MCP tools too, in the lead turn and in agent runs.
+- An error stays an error. Images and other content parts do not change.
+
+`read_file` and `bash` keep their output inside the default limits, so `boundToolOutput()` does not cut them again.
+
+## What you have now
+
+- The coding tools in a sandbox, with one option.
+- A backend of your own for another place.
+- Code that runs after each read and each write.
+- Formatted files after each write, and tool results that fit the context.
+
+Next: let the user undo the changes of a turn with [snapshots](./snapshots).
diff --git a/docs/harness/coding-tools.md b/docs/harness/coding-tools.md
new file mode 100644
index 0000000000..a70545641b
--- /dev/null
+++ b/docs/harness/coding-tools.md
@@ -0,0 +1,253 @@
+---
+title: Give your agent coding tools
+id: harness-coding-tools
+order: 6
+description: "Let a harness agent read, change, and search files, run commands, and read web pages, with a question before each risky call."
+keywords:
+  - tanstack ai
+  - harness
+  - coding agent
+  - workspace tools
+  - sandbox
+  - permissions
+  - formatter
+---
+
+Your agent must read and change the files of a project, search them, and run commands like `pnpm test`. It must stay in that project, and it must ask before it changes a file. `workspaceTools()` gives the model these tools for one folder. `permissions()` asks the user before each risky call.
+
+## 1. Install
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: @tanstack/ai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-harness-cli @tanstack/ai-openai
+vue: @tanstack/ai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-harness-cli @tanstack/ai-openai
+solid: @tanstack/ai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-harness-cli @tanstack/ai-openai
+svelte: @tanstack/ai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-harness-cli @tanstack/ai-openai
+preact: @tanstack/ai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-harness-cli @tanstack/ai-openai
+angular: @tanstack/ai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-harness-cli @tanstack/ai-openai
+octane: @tanstack/ai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-harness-cli @tanstack/ai-openai
+vanilla: @tanstack/ai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-harness-cli @tanstack/ai-openai
+
+<!-- ::end:tabs -->
+
+Two optional packages make the tools better:
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: @vscode/ripgrep turndown
+vue: @vscode/ripgrep turndown
+solid: @vscode/ripgrep turndown
+svelte: @vscode/ripgrep turndown
+preact: @vscode/ripgrep turndown
+angular: @vscode/ripgrep turndown
+octane: @vscode/ripgrep turndown
+vanilla: @vscode/ripgrep turndown
+
+<!-- ::end:tabs -->
+
+- `@vscode/ripgrep`: a fast `rg` binary for `list_files` and `grep`. Without it, the tools use `rg` on the `PATH`. Without `rg`, they use `git ls-files`, then a walk through the folders.
+- `turndown`: `webfetch` gives HTML pages as Markdown. Without it, HTML pages come back as plain text.
+
+## 2. Add the tools
+
+```ts group=harness-coding-tools
+import { defineHarness } from '@tanstack/ai-harness'
+import { permissions } from '@tanstack/ai-harness/plugins'
+import { workspaceTools } from '@tanstack/ai-harness/plugins/coding'
+import { runCli } from '@tanstack/ai-harness-cli'
+import { openaiText } from '@tanstack/ai-openai'
+
+const root = process.cwd()
+
+const coder = defineHarness({
+  name: 'acme/coder',
+  adapter: openaiText('gpt-5.6'),
+  plugins: () => [permissions({ root }), workspaceTools({ root })],
+})
+
+process.exitCode = await runCli(coder)
+```
+
+`@tanstack/ai-harness/plugins/coding` runs only in Node. The tools use the file system and the shell of the machine. For code that you do not trust, [run the tools in a sandbox](./coding-tools-backends#run-the-tools-in-a-sandbox).
+
+## 3. Run it
+
+1. Run `npx tsx coder.ts` in your project.
+2. Ask: `find the failing test and fix it`.
+3. When the agent wants to change a file or run a command, answer the question in the CLI.
+
+The agent reads and searches without a question. For a full terminal agent with a todo list and a model picker, see [Build a coding agent](./coding-agent).
+
+## The tools
+
+### Read and search
+
+These tools run without a question.
+
+| Tool | What it does |
+| --- | --- |
+| `read_file` | Reads a text file as numbered lines, at most 2000 lines or 50 KiB a page. The model reads more with `offset` and `limit`. |
+| `list_files` | Lists the files in a folder. An optional glob, like `src/**/*.ts`, filters them. |
+| `grep` | Searches the file contents with a regular expression. Gives `file:line: text`. |
+
+- `read_file` gives images (PNG, JPEG, GIF, WebP) and PDFs up to 5 MB to the model as media.
+- `read_file` refuses a binary file with a short note. For a missing file, it names up to 3 files with a close name.
+- `list_files` and `grep` skip the files that `.gitignore` names, the `.git` and `node_modules` folders, and links.
+- `list_files` shows at most 1000 files. `grep` shows at most 200 matches.
+
+### Change files
+
+These tools ask first.
+
+| Tool | What it does |
+| --- | --- |
+| `write_file` | Creates or replaces a file. |
+| `edit_file` | Replaces text in a file. The old text must be in the file once, unless the model sets `replaceAll`. |
+| `patch` | Applies a patch that adds, deletes, updates, or moves files. |
+
+A model gets `edit_file` or `patch`, not both. Every model gets `write_file`. The `editStyle` option picks the edit tool:
+
+- `'auto'` (default): GPT models (ids that start with `gpt-`, or `o` and a digit, like `o3`) get `patch`. Other models get `edit_file`.
+- `'edit'` or `'patch'`: every model gets that tool.
+
+`edit_file` keeps the line endings and the byte order mark of the file. It also finds text that is different only in Unicode form or in the spaces at the end of a line.
+
+To let the user undo the changes of a turn, add [snapshots](./snapshots).
+
+### Commands and the web
+
+| Tool | What it does | Asks first |
+| --- | --- | --- |
+| `bash` | Runs a shell command in the working folder. | Yes |
+| `webfetch` | Reads a web page by its URL. | Yes |
+| `websearch` | Searches the web. It is there only with a search provider. | No |
+
+For `bash`:
+
+- The model gets the exit code and the last 1000 lines (20 KiB) of the output.
+- A command stops after 2 minutes, with exit code 124. Every process that it started stops too. Set another limit with `bashTimeoutMs`. The model can ask for up to 10 minutes.
+- With `background: true`, the call returns at once with a job id. When the job ends, the model gets a note with the output, and a new turn starts.
+- With `spillDir`, long output goes to a file in that folder, and the model gets the path. `spillDir` is relative to `root`, or absolute.
+- When the session closes, the background jobs stop.
+
+For `webfetch`:
+
+- It reads `http` and `https` URLs only, and follows at most 5 redirects.
+- It refuses `localhost`, private network addresses, and cloud metadata addresses. It checks the DNS answer of each connection.
+- HTML comes back as Markdown, or as text without `turndown`. The model can ask for `format: 'html'`. Text and JSON come back as they are.
+- It reads at most 5 MB. It stops after 30 seconds, and the model can ask for up to 120 seconds.
+
+Change the web tools with the `web` option:
+
+- `web: false`: no web tools.
+- `web: { allowPrivateHosts: true }`: `webfetch` can read `localhost` and your private network. Set it only for a model that is allowed to reach your network.
+- `web: { search }`: adds `websearch`.
+
+There is no built-in search engine. Give `websearch` a `SearchProvider`:
+
+```ts group=harness-coding-tools
+import type { SearchProvider } from '@tanstack/ai-harness/plugins/coding'
+import { searchTheWeb } from './search'
+
+const search: SearchProvider = {
+  search: (query, { limit, signal }) => searchTheWeb(query, { limit, signal }),
+}
+
+export const withSearch = workspaceTools({ root, web: { search } })
+```
+
+The provider gives at most `limit` results. Each result is `{ title, url, snippet? }`. The model reads a result with `webfetch`.
+
+## Permissions and approvals
+
+Each tool tells `permissions()` what kind of call it makes:
+
+| Tools | `default` mode | `plan` mode |
+| --- | --- | --- |
+| `read_file`, `list_files`, `grep`, `websearch` | Runs | Runs |
+| `write_file`, `edit_file`, `patch` | Asks | Denied |
+| `bash` | Asks | Denied |
+| `webfetch` | Asks | Denied |
+
+- `acceptEdits` mode runs the edits without a question. `bash` still asks.
+- `bypass` mode runs every call.
+- `read_file` asks for a `.env` file.
+
+Let `webfetch` run without a question with one rule:
+
+```ts group=harness-coding-tools
+export const trustTheWeb = permissions({
+  root,
+  rules: [{ tool: 'webfetch', decision: 'allow' }],
+})
+```
+
+In `plan` mode, a call that asks is denied. This rule makes `webfetch` an allow, so `webfetch` runs in `plan` mode too.
+
+Each call also tells `permissions()` the paths or the commands that it touches. So a rule with a `resource` can allow one folder or one command:
+
+```ts group=harness-coding-tools
+export const trustTests = permissions({
+  root,
+  rules: [
+    { tool: 'edit_file', resource: 'src/**', decision: 'allow' },
+    { tool: 'bash', resource: 'pnpm test*', decision: 'allow' },
+  ],
+})
+```
+
+- Paths match from `root`. Give `permissions()` and `workspaceTools()` the same `root`.
+- `bash` splits a command at `&&`, `||`, `;`, `|`, and new lines. Every part must be allowed.
+- A command with `$(`, a backtick, or a heredoc never gets an allow.
+
+[Permissions](./permissions) explains the rules, the modes, and the saved answers.
+
+## Outside paths and the working folder
+
+### A path outside `root`
+
+The tools refuse a path outside `root`. To ask the user instead, set `outside: 'ask'`:
+
+```ts group=harness-coding-tools
+export const askOutside = workspaceTools({ root, outside: 'ask' })
+```
+
+- A yes allows that folder, and the folders in it, until the session ends.
+- `bypass` mode allows every path without a question.
+- A link in `root` that leads out of `root` counts as outside.
+
+### A working folder for each thread
+
+Each thread can work in its own folder in `root`. Set the `cwd` thread setting:
+
+```ts group=harness-coding-tools-cwd
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { workspaceTools } from '@tanstack/ai-harness/plugins/coding'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { openaiText } from '@tanstack/ai-openai'
+
+const repos = defineHarness({
+  name: 'acme/repos',
+  adapter: openaiText('gpt-5.6'),
+  plugins: () => [workspaceTools({ root: '/srv/repos' })],
+})
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+const session = await host.open(repos, { threadId: 'fix-login' })
+await session.configure({ cwd: 'web-app' })
+```
+
+- Relative paths start in `/srv/repos/web-app`, and `bash` runs there.
+- The system prompt tells the model the working folder.
+- Permission rules still match paths from `root`, for example `web-app/src/**`.
+- `cwd` is relative to `root`. A `cwd` outside `root` counts as an outside path.
+
+[Store settings per thread](./thread-settings) shows how a client sets `cwd`.
+
+## What you have now
+
+- An agent that reads, searches, and changes the files of one folder, and runs commands in it.
+- A question before each edit, command, and web fetch.
+- A working folder for each thread, and a question before a path outside `root`.
+
+Next: run the same tools in a sandbox, or format each file after a write. See [Sandbox and extend the coding tools](./coding-tools-backends).
diff --git a/docs/harness/thread-settings.md b/docs/harness/thread-settings.md
index 0970560e6c..43a5988c63 100644
--- a/docs/harness/thread-settings.md
+++ b/docs/harness/thread-settings.md
@@ -122,7 +122,7 @@ For `reasoning`, the `overrides` of the prompt win, then the stored setting, the
 `workspaceTools` work in the `cwd` of the thread. Relative paths start there, and `bash` runs there:
 
 ```ts group=harness-thread-settings
-import { workspaceTools } from '@tanstack/ai-harness/plugins'
+import { workspaceTools } from '@tanstack/ai-harness/plugins/coding'
 
 export const coder = defineHarness({
   name: 'acme/coder',
diff --git a/docs/sandbox/tools.md b/docs/sandbox/tools.md
index 74e0505e75..07442e7daf 100644
--- a/docs/sandbox/tools.md
+++ b/docs/sandbox/tools.md
@@ -19,6 +19,10 @@ secrets, the closures you captured when you defined a tool. For that, the
 > [Provisioning](./provisioning). For server tools in general, see the main
 > [server tools](../tools/server-tools) doc.
 
+> The file and shell tools of a harness (`read_file`, `bash`, and more) can
+> also work in a sandbox, with no agent CLI in it. See
+> [Run the tools in a sandbox](../harness/coding-tools-backends#run-the-tools-in-a-sandbox).
+
 ## Native vs bridged tools
 
 When you pass `tools` to `chat()` with a sandbox in the middleware, each tool is

From 29081a664cfe11d8770fd6890c69df18f807155e Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 17:32:50 +0200
Subject: [PATCH 261/286] test(e2e): sessions, waiting inputs, and approvals
 over HTTP

- Cancel a waiting input and move another into the running turn.
- The permissions plugin asks once for a tool the user allows always, and
  a rejected call gives the model its message.
- List, rename, and fork sessions with their settings, and the host status
  feed shows running, then idle.
---
 .../e2e/fixtures/harness/protocol-inputs.json |  62 +++++
 .../e2e/src/routes/api.harness-protocol.$.ts  |  18 +-
 .../e2e/tests/harness-protocol-inputs.spec.ts | 249 +++++++++++++++++-
 testing/e2e/tests/harness-protocol.spec.ts    | 140 ++++++++++
 4 files changed, 458 insertions(+), 11 deletions(-)

diff --git a/testing/e2e/fixtures/harness/protocol-inputs.json b/testing/e2e/fixtures/harness/protocol-inputs.json
index fb4193cc30..3b5671f1b8 100644
--- a/testing/e2e/fixtures/harness/protocol-inputs.json
+++ b/testing/e2e/fixtures/harness/protocol-inputs.json
@@ -107,6 +107,68 @@
       "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-always] who am i twice",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [{ "name": "whoami", "arguments": "{}" }]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-always] who am i twice",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "toolCalls": [{ "name": "whoami", "arguments": "{}" }]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-always] who am i twice",
+        "sequenceIndex": 2
+      },
+      "response": {
+        "content": "You are e2e, twice."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-reject] who am i",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [{ "name": "whoami", "arguments": "{}" }]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-reject] who am i",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Hi, without a look."
+      }
     }
   ]
 }
diff --git a/testing/e2e/src/routes/api.harness-protocol.$.ts b/testing/e2e/src/routes/api.harness-protocol.$.ts
index 4667de8700..f319c970fc 100644
--- a/testing/e2e/src/routes/api.harness-protocol.$.ts
+++ b/testing/e2e/src/routes/api.harness-protocol.$.ts
@@ -11,7 +11,7 @@ import {
   defineHarness,
   definePlugin,
 } from '@tanstack/ai-harness'
-import { todos } from '@tanstack/ai-harness/plugins'
+import { permissions, todos } from '@tanstack/ai-harness/plugins'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { z } from 'zod'
 import { askName, deploy, probe, whoami } from '@/lib/harness-protocol-tools'
@@ -82,6 +82,18 @@ function harnessFor(request: Request) {
           maxRetries: 0,
         })
       : createTextAdapter('openai', undefined, port, testId).adapter
+  // `x-harness-permissions: 1` asks the user before each `whoami` call. An
+  // `always` answer is saved for the root, and the host is shared, so each
+  // test gets its own root.
+  const asks =
+    request.headers.get('x-harness-permissions') === '1'
+      ? [
+          permissions({
+            root: `/e2e/${testId}`,
+            rules: [{ tool: 'whoami', decision: 'ask' }],
+          }),
+        ]
+      : []
   const harness = defineHarness({
     name: 'e2e/protocol',
     adapter,
@@ -110,6 +122,7 @@ function harnessFor(request: Request) {
     ],
     expose: { agents: ['echo'], settings: ['model', 'instructions'] },
     plugins: () => [
+      ...asks,
       todos(),
       // The sender of the running turn, as plugins see it.
       definePlugin({
@@ -176,7 +189,8 @@ function handlerFor(request: Request) {
 /**
  * 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 has no fork route.
+ * 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)
diff --git a/testing/e2e/tests/harness-protocol-inputs.spec.ts b/testing/e2e/tests/harness-protocol-inputs.spec.ts
index 88630e62fb..6d3f678338 100644
--- a/testing/e2e/tests/harness-protocol-inputs.spec.ts
+++ b/testing/e2e/tests/harness-protocol-inputs.spec.ts
@@ -40,17 +40,65 @@ const interruptOf = (chunks: Array<Chunk>) => {
   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) =>
@@ -65,18 +113,35 @@ function asUser(
         data: { threadId, input },
       })
     ).json()
-  const answers = async (threadId: string) => {
-    const response = await request.get(
-      `/api/harness-protocol/transcript?threadId=${threadId}`,
-      { headers },
-    )
-    const transcript: Array<{ role: string; content: unknown }> =
-      await response.json()
-    return transcript
+  const read = async (route: string, threadId: string) =>
+    (
+      await request.get(`/api/harness-protocol/${route}?threadId=${threadId}`, {
+        headers,
+      })
+    ).json()
+  const transcript = (
+    threadId: string,
+  ): Promise<Array<{ 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,
   }
-  return { headers, json, run, control, answers }
 }
 
 const userMessage = (content: string) => [{ id: 'u1', role: 'user', content }]
@@ -354,4 +419,170 @@ test.describe('harness protocol inputs', () => {
     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('asks once for a tool that the user allows always', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const user = asUser(request, testId, aimockPort, 'e2e-token', {
+      'x-harness-permissions': '1',
+    })
+    const threadId = `always-${testId}`
+    expect(
+      await user.control(threadId, {
+        op: 'prompt',
+        message: '[harness-always] who am i twice',
+      }),
+    ).toMatchObject({ status: 'accepted' })
+    await expect.poll(() => user.question(threadId)).toBeTruthy()
+    const asked = await user.question(threadId)
+    expect(asked?.message).toContain('Allow whoami')
+    expect(
+      await user.control(threadId, {
+        op: 'answer',
+        questionId: asked?.questionId,
+        value: { answer: 'always' },
+      }),
+    ).toMatchObject({ status: 'accepted' })
+
+    // The model calls whoami twice, and this test answers once: the second
+    // call runs without a question.
+    await expect
+      .poll(() => user.answers(threadId))
+      .toContain('You are e2e, twice.')
+    const results = (await user.transcript(threadId)).filter(
+      (message) => message.role === 'tool',
+    )
+    expect(results).toHaveLength(2)
+    expect((await user.snapshot(threadId)).pendingQuestions).toEqual([])
+  })
+
+  test('gives the model the message of a rejected tool call', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const user = asUser(request, testId, aimockPort, 'e2e-token', {
+      'x-harness-permissions': '1',
+    })
+    const threadId = `reject-${testId}`
+    const reason = 'Do not look. Say hi.'
+    expect(
+      await user.control(threadId, {
+        op: 'prompt',
+        message: '[harness-reject] who am i',
+      }),
+    ).toMatchObject({ status: 'accepted' })
+    await expect.poll(() => user.question(threadId)).toBeTruthy()
+    const asked = await user.question(threadId)
+    expect(
+      await user.control(threadId, {
+        op: 'answer',
+        questionId: asked?.questionId,
+        value: { answer: 'reject', message: reason },
+      }),
+    ).toMatchObject({ status: 'accepted' })
+    await expect
+      .poll(() => user.answers(threadId))
+      .toContain('Hi, without a look.')
+
+    // The last model call got the message as the result of the tool call.
+    const journal = await request.get(
+      `http://127.0.0.1:${aimockPort}/v1/_requests`,
+    )
+    const entries: Array<JournalEntry> = await journal.json()
+    const last = entries
+      .filter((entry) => entry.headers?.['x-test-id'] === testId)
+      .at(-1)
+    const result = last?.body?.messages?.find(
+      (message) => message.role === 'tool',
+    )
+    expect(String(result?.content)).toContain(reason)
+  })
 })
diff --git a/testing/e2e/tests/harness-protocol.spec.ts b/testing/e2e/tests/harness-protocol.spec.ts
index e3414aedc5..6b856de9e8 100644
--- a/testing/e2e/tests/harness-protocol.spec.ts
+++ b/testing/e2e/tests/harness-protocol.spec.ts
@@ -230,4 +230,144 @@ test.describe('harness protocol', () => {
     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('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'])
+  })
 })

From f75d46d22ba101273a81a382e851e442b845a514 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 17:41:16 +0200
Subject: [PATCH 262/286] test(e2e): plan mode in a subagent, and the order of
 tool runs

- permissions() in plan mode deny the write_file call of a subagent.
- toolExecution 'sequential' starts the second tool after the first ends,
  and 'parallel' starts it while the first runs.
---
 testing/e2e/fixtures/harness/basic.json    |  88 +++++++++++++++
 testing/e2e/src/routes/api.harness-test.ts | 123 +++++++++++++++++++++
 testing/e2e/tests/harness.spec.ts          |  46 ++++++++
 3 files changed, 257 insertions(+)

diff --git a/testing/e2e/fixtures/harness/basic.json b/testing/e2e/fixtures/harness/basic.json
index 3a642d81df..562a0eb4d0 100644
--- a/testing/e2e/fixtures/harness/basic.json
+++ b/testing/e2e/fixtures/harness/basic.json
@@ -205,6 +205,94 @@
       "response": {
         "content": "The second call hit the limit."
       }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-plan-subagent] write x.txt",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "writer",
+            "arguments": "{}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-plan-subagent] write x.txt",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "The writer could not write in plan mode."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-plan-writer] write x.txt",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "write_file",
+            "arguments": "{\"path\":\"x.txt\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-plan-writer] write x.txt",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Plan mode blocked the write."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-tool-order] sequential",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          { "name": "first", "arguments": "{}" },
+          { "name": "second", "arguments": "{}" }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-tool-order] sequential",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Both steps ran."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-tool-order] parallel",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          { "name": "first", "arguments": "{}" },
+          { "name": "second", "arguments": "{}" }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-tool-order] parallel",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Both steps ran."
+      }
     }
   ]
 }
diff --git a/testing/e2e/src/routes/api.harness-test.ts b/testing/e2e/src/routes/api.harness-test.ts
index f84eeb493b..db0901277d 100644
--- a/testing/e2e/src/routes/api.harness-test.ts
+++ b/testing/e2e/src/routes/api.harness-test.ts
@@ -10,6 +10,7 @@ import {
 import { createOpenaiChat } from '@tanstack/ai-openai'
 import Anthropic from '@anthropic-ai/sdk'
 import { createAnthropicChatWithClient } from '@tanstack/ai-anthropic'
+import { permissions } from '@tanstack/ai-harness/plugins'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { z } from 'zod'
 import type { ModelMessage, UIMessage } from '@tanstack/ai'
@@ -360,6 +361,111 @@ async function agentResume(
   }
 }
 
+/**
+ * The lead calls `writer` in plan mode, and the writer's model calls
+ * `write_file`. `permissions()` checks the child run too, so it denies the
+ * edit. Returns how many times the tool ran, the tool results the writer
+ * got, and the text of the turn.
+ */
+async function planSubagent(
+  host: HarnessHost,
+  openai: () => ReturnType<typeof createTextAdapter>['adapter'],
+) {
+  let writes = 0
+  const results: Array<unknown> = []
+  // ponytail: a fake write_file, so a failing test changes no files.
+  const writeFile = toolDefinition({
+    name: 'write_file',
+    description: 'Write a file',
+    inputSchema: z.object({ path: z.string() }),
+  }).server(async () => {
+    writes += 1
+    return { written: true }
+  })
+  const writer = defineAgent({
+    name: 'writer',
+    description: 'Writes files',
+    run: (ctx) =>
+      ctx.chat({
+        adapter: openai(),
+        messages: [
+          { role: 'user', content: '[harness-plan-writer] write x.txt' },
+        ],
+        tools: [writeFile],
+        middleware: [
+          {
+            name: 'e2e/tool-results',
+            onAfterToolCall: (_ctx, info) => {
+              results.push(info.result)
+            },
+          },
+        ],
+        stream: false,
+      }),
+  })
+  const session = await host.open(
+    defineHarness({
+      name: 'e2e/harness-plan',
+      adapter: openai(),
+      subagents: { agents: [writer] },
+      plugins: () => [
+        permissions({
+          rules: [{ tool: 'write_file', decision: 'ask', kind: 'edit' }],
+        }),
+      ],
+    }),
+    { threadId: 'e2e-plan' },
+  )
+  await session.command('mode', 'plan')
+  const turn = await session.prompt('[harness-plan-subagent] write x.txt')
+  return { writes, results, text: turn.text }
+}
+
+/**
+ * One model call asks for the server tools `first` and `second`. `first`
+ * waits until `second` starts, for at most one second. With `'parallel'`,
+ * `second` starts and ends in that wait. With `'sequential'`, it starts
+ * after `first` ends. Returns the start and end order, and the turn text.
+ */
+async function toolOrder(
+  host: HarnessHost,
+  openai: () => ReturnType<typeof createTextAdapter>['adapter'],
+  toolExecution: 'parallel' | 'sequential',
+) {
+  const log: Array<string> = []
+  let secondStarted = () => {}
+  const started = new Promise<void>((resolve) => {
+    secondStarted = resolve
+  })
+  const step = (name: 'first' | 'second') =>
+    toolDefinition({
+      name,
+      description: `The ${name} step`,
+      inputSchema: z.object({}),
+    }).server(async () => {
+      log.push(`start:${name}`)
+      if (name === 'second') secondStarted()
+      else
+        await Promise.race([
+          started,
+          new Promise((resolve) => setTimeout(resolve, 1_000)),
+        ])
+      log.push(`end:${name}`)
+      return { done: name }
+    })
+  const session = await host.open(
+    defineHarness({
+      name: `e2e/harness-tools-${toolExecution}`,
+      adapter: openai(),
+      tools: [step('first'), step('second')],
+      toolExecution,
+    }),
+    { threadId: `e2e-tools-${toolExecution}` },
+  )
+  const turn = await session.prompt(`[harness-tool-order] ${toolExecution}`)
+  return { log, text: turn.text }
+}
+
 /**
  * Harness session. The main model and the agent are real OpenAI adapters
  * against aimock.
@@ -812,6 +918,23 @@ export const Route = createFileRoute('/api/harness-test')({
           if (body.scenario === 'routing') {
             return Response.json(await routingTurns(host, openai))
           }
+          if (body.scenario === 'plan-subagent') {
+            return Response.json(await planSubagent(host, openai))
+          }
+          if (
+            body.scenario === 'tools-sequential' ||
+            body.scenario === 'tools-parallel'
+          ) {
+            return Response.json(
+              await toolOrder(
+                host,
+                openai,
+                body.scenario === 'tools-sequential'
+                  ? 'sequential'
+                  : 'parallel',
+              ),
+            )
+          }
           if (body.scenario === 'agent') {
             const result = await session.agents.pricer.run({
               task: '[harness-agent] price vendor a',
diff --git a/testing/e2e/tests/harness.spec.ts b/testing/e2e/tests/harness.spec.ts
index 7ed349bdb9..d75871ef6f 100644
--- a/testing/e2e/tests/harness.spec.ts
+++ b/testing/e2e/tests/harness.spec.ts
@@ -135,4 +135,50 @@ test.describe('harness session', () => {
       removed: 1,
     })
   })
+
+  test('permissions() in plan mode deny the write of a subagent', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'plan-subagent', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    expect(await response.json()).toEqual({
+      writes: 0,
+      results: [{ error: 'This tool is not allowed in plan mode.' }],
+      text: 'The writer could not write in plan mode.',
+    })
+  })
+
+  test("toolExecution: 'sequential' starts the second tool after the first ends", async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'tools-sequential', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    expect(await response.json()).toEqual({
+      log: ['start:first', 'end:first', 'start:second', 'end:second'],
+      text: 'Both steps ran.',
+    })
+  })
+
+  test("toolExecution: 'parallel' starts the second tool while the first runs", async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'tools-parallel', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    expect(await response.json()).toEqual({
+      log: ['start:first', 'start:second', 'end:second', 'end:first'],
+      text: 'Both steps ran.',
+    })
+  })
 })

From 222e5744edb088165ee84d35223f51275778283b Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 17:46:09 +0200
Subject: [PATCH 263/286] docs(harness): permissions and agent profiles

- Ask before risky tool calls: modes, rules with paths and commands, the
  built-in rules, answering once, always, or reject, rules in subagents, and
  rules for your own tool.
- Switch between agent profiles: the built-in agents, your own, Markdown
  agents, /agent, the step limit, and subagents.
---
 docs/harness/agents.md      | 206 ++++++++++++++++++++++++++
 docs/harness/permissions.md | 286 ++++++++++++++++++++++++++++++++++++
 2 files changed, 492 insertions(+)
 create mode 100644 docs/harness/agents.md
 create mode 100644 docs/harness/permissions.md

diff --git a/docs/harness/agents.md b/docs/harness/agents.md
new file mode 100644
index 0000000000..0cdec35659
--- /dev/null
+++ b/docs/harness/agents.md
@@ -0,0 +1,206 @@
+---
+title: Switch between agent profiles
+id: harness-agents
+order: 8
+description: "Give one harness several agents, such as a read-only planner and a builder. Each profile has its own prompt, tools, model, rules, and step limit, in code or in Markdown files."
+keywords:
+  - tanstack ai
+  - harness
+  - agents
+  - agent profiles
+  - plan
+  - subagents
+---
+
+Your coding agent has two jobs. First it must plan a change without touching a file. Then it must build the change with every tool. The main model also needs a fast helper that searches the code. `agents()` gives the harness named agent profiles. Each profile has its own system prompt, tools, model, permission rules, and step limit.
+
+## 1. Add the plugin
+
+```ts group=harness-agents
+import { defineHarness } from '@tanstack/ai-harness'
+import { agents, permissions } from '@tanstack/ai-harness/plugins'
+import { workspaceTools } from '@tanstack/ai-harness/plugins/coding'
+import { runCli } from '@tanstack/ai-harness-cli'
+import { anthropicText } from '@tanstack/ai-anthropic'
+
+const root = process.cwd()
+const sonnet = anthropicText('claude-sonnet-5-5')
+
+const coder = defineHarness({
+  name: 'acme/coder',
+  adapter: sonnet,
+  plugins: () => [
+    permissions({ root }),
+    workspaceTools({ root }),
+    agents({ adapter: () => sonnet }),
+  ],
+})
+
+process.exitCode = await runCli(coder)
+```
+
+`adapter` turns a model id into an adapter. Here every agent uses the same model.
+
+## 2. Plan, then build
+
+1. Run `npx tsx coder.ts` in your project.
+2. Type `/agent plan`.
+3. Ask: `how do I add a dark mode?` The agent reads the code and gives numbered steps. It has no tool that changes a file.
+4. Type `/agent build`.
+5. Ask: `do step 1`. The agent changes the files, after your answer to each [permission question](./permissions).
+
+- `/agent` alone shows the current agent and the list: `Agent: build. Agents: build, plan.`
+- A switch applies at the next turn.
+
+A client changes the `agent` setting. The [session view](./custom-ui) lists its options for a menu:
+
+```ts group=harness-agents-client
+import { createHarnessClient } from '@tanstack/ai-harness/client'
+import { createSessionView } from '@tanstack/ai-harness/view'
+
+const view = createSessionView(
+  createHarnessClient({ url: '/api/harness', threadId: 'fix-login' }),
+)
+await view.ready
+
+const setting = view.store.get().config.find((entry) => entry.key === 'agent')
+if (setting?.option.type === 'select') {
+  console.log(setting.value, setting.option.options) // 'build' ['build', 'plan']
+}
+
+await view.setConfig('agent', 'plan')
+```
+
+## The built-in agents
+
+| Agent | Mode | Tools | What it does |
+| --- | --- | --- | --- |
+| `build` | `primary`, the default | Every tool | Reads code, changes files, and runs commands. |
+| `plan` | `primary` | The read tools and `todo_write` | Reads the code and gives a plan in numbered steps. |
+| `general` | `subagent` | Every tool | Does a task in many steps and reports back. |
+| `explore` | `subagent` | The read tools | Searches the code and reports the paths that it finds. |
+
+The read tools are `read_file`, `list_files`, `grep`, `webfetch`, `websearch`, and `question`. An agent gets only the tools that the harness has.
+
+The mode of a profile says who starts it:
+
+- `primary`: it answers the user's turns. Pick it with `/agent`.
+- `subagent`: the main model starts it as a child.
+- `all`: both.
+
+The `plan` agent and the `plan` mode of [permissions](./permissions#pick-a-mode) are separate. The agent has only the read tools and `todo_write`. The mode denies edits and commands for every agent. To drop the built-in agents, set `builtIns: false`.
+
+## Add your own agent
+
+Give `agents()` a profile. This one reviews the changes with a stronger model:
+
+```ts group=harness-agents
+import type { AnyTextAdapter } from '@tanstack/ai'
+import type { AgentProfile } from '@tanstack/ai-harness/plugins'
+
+const review: AgentProfile = {
+  name: 'review',
+  description: 'Reviews the changes and lists the risks. Does not change files.',
+  mode: 'all',
+  model: 'claude-opus-5-5',
+  system: 'You review code. Read the diff, then list each risk with its file and line.',
+  tools: ['read_file', 'list_files', 'grep', 'bash'],
+  permissions: [{ tool: 'bash', resource: 'git diff*', decision: 'allow' }],
+  steps: 20,
+}
+
+const models: Record<string, AnyTextAdapter> = {
+  'claude-opus-5-5': anthropicText('claude-opus-5-5'),
+}
+
+export const withReview = agents({
+  adapter: (model) => models[model] ?? sonnet,
+  agents: [review],
+})
+```
+
+`name`, `description`, and `mode` are required. The other fields:
+
+| Field | What it does |
+| --- | --- |
+| `model` | A model id. `adapter` turns it into an adapter. Without it, a primary agent keeps the harness model, and a subagent uses the model of the main turn. |
+| `system` | Text for the system prompt of each turn of this agent. |
+| `tools` | The tools that this agent can call, by name. A `*` matches any text, for example `todo_*`. Without it, the agent gets every tool. |
+| `permissions` | [Permission rules](./permissions#write-rules) that count while this agent is the primary agent. |
+| `steps` | The step limit. See [Limit the steps](#limit-the-steps). |
+| `hidden` | `true` leaves the agent out of `/agent` and the `agent` setting. The model can still start it as a subagent. |
+
+- A profile replaces an earlier profile with the same name. The order is the built-in agents, then `dirs`, then `agents`. So a profile named `plan` replaces the built-in `plan`.
+- `default` names the primary agent of a new session. Without it, the first primary agent is the default, which is `build`.
+- In the main turn, a model that the thread stored with `session.configure` wins over the profile `model`. See [What wins](./thread-settings#what-wins).
+- A `tools` list also filters the subagent tools. To let the agent start subagents, add their tool names, for example `explore`.
+
+## Load agents from Markdown files
+
+Keep your agents next to your code as Markdown files. Save this file as `.agents/agents/review.md`:
+
+```md
+---
+description: Reviews the changes and lists the risks. Does not change files.
+mode: all
+model: claude-opus-5-5
+tools: [read_file, list_files, grep]
+steps: 20
+---
+
+You review code. Read the diff, then list each risk with its file and line.
+```
+
+Then give `agents()` the folder:
+
+```ts group=harness-agents
+export const fromFiles = agents({
+  adapter: (model) => models[model] ?? sonnet,
+  dirs: [`${root}/.agents/agents`],
+})
+```
+
+- The file name is the agent name, here `review`.
+- The body is the system prompt.
+- The frontmatter sets `description`, `mode`, `model`, `tools`, `steps`, and `hidden: true`. The default `mode` is `all`.
+- An unknown `mode`, or a `steps` that is not a whole number, stops `host.open` with an error, for example `Agent file review.md: "mode" is not valid.`
+- The plugin reads the folder when a session opens. A folder that it cannot read gives no agents.
+
+## Limit the steps
+
+An agent can call tools for a long time. `steps` sets the most model calls with tools in one run. With `steps: 20`:
+
+1. The agent makes up to 20 model calls with tools.
+2. Call 21 gets `toolChoice: 'none'` and a note: answer now, and say what is left to do.
+3. Then the run stops.
+
+The limit counts again in each turn of a primary agent and in each run of a subagent.
+
+On Amazon Bedrock, `'none'` after a tool call goes to the model as `auto`. So the model can still call a tool on the last call. See [Provider notes](../tools/tools#provider-notes).
+
+## Let the model start a subagent
+
+A profile with the mode `subagent` or `all` is also a subagent. The main model gets a tool for each one, for example `explore`. Ask the build agent: `use explore to find where the theme is set`.
+
+A subagent run gets these parts of its profile:
+
+- The tools of the last main turn, filtered by its `tools`.
+- Its `system` prompt.
+- Its `model`, or the model of the main turn.
+- Its step limit.
+
+To give the model one `subagent` tool for every agent, see [Agents from plugins](./subagents#agents-from-plugins). The harness also limits the depth and the number of children. See [Stay within limits](./subagents#stay-within-limits).
+
+## Known limits
+
+- The `permissions` of a profile count only while it is the primary agent. When the profile runs as a subagent, its own rules do not apply. Put rules that must hold in every run in `permissions({ rules })`. See [Rules in subagents](./permissions#rules-in-subagents).
+- A Markdown agent cannot set `permissions`. Put those rules in a profile in code.
+- On Amazon Bedrock, the last step can still call a tool.
+- A subagent that starts before the first turn of the session has no tools. It also needs its own `model`.
+
+## What you have now
+
+- `/agent plan` for a read-only planner, and `/agent build` to do the work.
+- Your own agents in code or in Markdown files, each with its own prompt, tools, model, and rules.
+- A step limit that ends a run with a text answer.
+- Subagents that the main model starts to search and to research.
diff --git a/docs/harness/permissions.md b/docs/harness/permissions.md
new file mode 100644
index 0000000000..7bf16db9d2
--- /dev/null
+++ b/docs/harness/permissions.md
@@ -0,0 +1,286 @@
+---
+title: Ask before risky tool calls
+id: harness-permissions
+order: 7
+description: "Make a harness agent ask before it changes a file or runs a command. Pick a mode, write rules for paths and commands, answer the questions from a client, and keep the rules in subagents."
+keywords:
+  - tanstack ai
+  - harness
+  - permissions
+  - approvals
+  - plan mode
+  - rules
+---
+
+Your agent can change files and run commands. It must not do that without a yes from the user, and some files it must never touch. `permissions()` checks each tool call against rules. Each call runs, waits for the user, or does not run.
+
+## 1. Add the plugin
+
+```ts group=harness-permissions
+import { defineHarness } from '@tanstack/ai-harness'
+import { permissions } from '@tanstack/ai-harness/plugins'
+import { workspaceTools } from '@tanstack/ai-harness/plugins/coding'
+import { runCli } from '@tanstack/ai-harness-cli'
+import { openaiText } from '@tanstack/ai-openai'
+
+const root = process.cwd()
+
+const coder = defineHarness({
+  name: 'acme/coder',
+  adapter: openaiText('gpt-6.1-sol'),
+  plugins: () => [permissions({ root }), workspaceTools({ root })],
+})
+
+process.exitCode = await runCli(coder)
+```
+
+Give `permissions()` and `workspaceTools()` the same `root`. The rules match paths from there.
+
+## 2. Answer the first question
+
+1. Run `npx tsx coder.ts` in your project.
+2. Ask: `add a test for the date parser`.
+3. Wait for the question. The agent reads files without a question, but it asks before it writes a file:
+
+```text
+? Allow write_file {"path":"src/date.test.ts","content":"..."}? Answer once, always, or reject.
+```
+
+4. Type `once`.
+
+The agent writes the file and continues.
+
+## Pick a mode
+
+The `mode` setting decides how much runs without a question:
+
+| Mode | What happens |
+| --- | --- |
+| `default` | The rules apply as written. A call that asks waits for the user. |
+| `plan` | Read-only. Edits, commands, and calls that ask do not run. The model gets a note to plan and to change no files. |
+| `acceptEdits` | Edits run without a question. Commands still ask. |
+| `bypass` | Every call runs, also a call that a rule denies. |
+
+Switch the mode in one of these places:
+
+- The CLI: type `/mode plan`. `/mode` alone shows the current mode.
+- A client: call `client.setConfig('mode', 'plan')`, or `view.setConfig('mode', 'plan')` in a [session view](./custom-ui).
+- Server code: call `session.setConfig('mode', 'plan')`.
+
+In `acceptEdits` mode, an edit outside `root` or of a `.env` file still asks.
+
+## Write rules
+
+Add your own rules with `rules`:
+
+```ts group=harness-permissions
+export const strict = permissions({
+  root,
+  rules: [
+    { tool: 'read_file', resource: 'secrets/**', decision: 'deny' },
+    { tool: 'edit_file', resource: 'src/**', decision: 'allow' },
+    { tool: 'bash', resource: 'pnpm test*', decision: 'allow' },
+    { tool: 'deploy_*', decision: 'deny' },
+  ],
+})
+```
+
+A rule has these fields:
+
+- `tool`: a tool name. A `*` at the end matches every tool that starts with that text.
+- `decision`: `allow`, `ask`, or `deny`.
+- `resource`: optional. A glob on the path or the command that the call touches. Without it, the rule matches every call of the tool.
+- `kind`: optional. `read`, `edit`, or `execute`. The modes read it: `plan` denies `edit` and `execute`, and `acceptEdits` allows `edit`.
+
+The plugin reads the rules in this order, and the last rule that matches a call wins:
+
+1. The rules of the tool plugins, for example the coding tools.
+2. Your `rules`.
+3. The saved `always` answers. A saved answer never wins over a `deny`.
+
+Two more rules apply to each tool:
+
+- A tool with no rule runs without a question. To ask for each tool that has no rule, set `default: 'ask'`.
+- When the last rule of a tool is a `deny` with no `resource`, the model does not get the tool.
+
+### Paths
+
+- Inside `root`, a rule matches the path from `root`, for example `src/app.ts`. Outside `root`, it matches the full path, for example `/etc/hosts`.
+- `**` matches any part of a path. `*` matches text in one name. `?` matches one character.
+- On macOS and Windows, letter case does not count. So a `deny` for `secrets/**` also stops `Secrets/key`.
+- A call with more than one path, for example a `patch`, runs only when the rules allow every path.
+
+These paths ask, unless a rule with a `resource` allows them:
+
+- A path outside `root`.
+- A `.env` file, for example `.env`, `.env.local`, or `prod.env`.
+- A path that the plugin cannot resolve without the file system, for example `C:notes.txt` or `notes.txt:hidden`.
+
+This rule lets the agent read `.env.example` without a question:
+
+```ts group=harness-permissions
+export const exampleEnv = permissions({
+  root,
+  rules: [{ tool: 'read_file', resource: '.env.example', decision: 'allow' }],
+})
+```
+
+### Commands
+
+- `bash` splits a command at `&&`, `||`, `;`, `|`, and new lines. The rules must allow every part. So when only `ls*` is allowed, `ls && rm -rf build` asks.
+- In a command rule, `*` matches any text, also `/`. So `git *` allows `git add src/app.ts`.
+- A part with shell syntax that can hide a command never gets an `allow`. This includes `$(`, a backtick, `&`, `<`, `>`, and a heredoc. Such a part asks, or a matching `deny` stops it.
+
+## The built-in rules
+
+`workspaceTools()` adds these rules. [Give your agent coding tools](./coding-tools#permissions-and-approvals) shows what each tool does.
+
+| Tool | Decision | Kind |
+| --- | --- | --- |
+| `read_file`, `list_files`, `grep` | `allow` | `read` |
+| `write_file`, `edit_file`, `patch` | `ask` | `edit` |
+| `bash` | `ask` | `execute` |
+| `webfetch` | `ask` | none |
+
+- `websearch` has no rule, so it runs.
+- The path rules above also apply. For example, `read_file` asks for a `.env` file.
+- Your `rules` come after these rules, so they win. `{ tool: 'webfetch', decision: 'allow' }` lets `webfetch` run without a question.
+
+## Answer a question
+
+A call that asks waits for one of three answers:
+
+| Answer | What happens |
+| --- | --- |
+| `once` | This call runs. |
+| `always` | This call runs, and the plugin saves an `allow` rule for it. |
+| `reject` | The call does not run. The model gets a tool error. |
+
+- Send the answer as a string, `'once'`, or as an object, `{ answer: 'once' }`.
+- A reject can carry a `message` for the model: `{ answer: 'reject', message: 'Use pnpm, not npm.' }`. The model gets your message as the tool error.
+- Any other answer rejects the call. This includes `y` and `yes`.
+
+### In a web app
+
+Show the question with three buttons. `question.answer()` sends the choice:
+
+```ts group=harness-permissions-client
+import { createHarnessClient } from '@tanstack/ai-harness/client'
+import { createSessionView } from '@tanstack/ai-harness/view'
+
+const view = createSessionView(
+  createHarnessClient({ url: '/api/harness', threadId: 'fix-login' }),
+)
+
+view.on('question', (question) => {
+  const card = document.createElement('div')
+  const note = document.createElement('input')
+  note.setAttribute('aria-label', 'Note for the model, sent with reject')
+  card.append(question.message, note)
+  for (const answer of ['once', 'always', 'reject']) {
+    const button = document.createElement('button')
+    button.textContent = answer
+    button.onclick = () => {
+      card.remove()
+      void question.answer({ answer, message: note.value })
+    }
+    card.append(button)
+  }
+  document.body.append(card)
+})
+```
+
+This card fits the permission question. A question from another plugin has its own `schema`.
+
+### In other places
+
+- The CLI: type `once`, `always`, or `reject`. To add a note, type JSON: `{"answer":"reject","message":"Use pnpm."}`.
+- A client without a view: call `client.answer(questionId, value)`. Over HTTP, send `POST control` with `{ threadId, input: { op: 'answer', questionId, value } }`.
+- Server code: call `session.answer(questionId, value)`. `session.snapshot().pendingQuestions` lists the open questions.
+- The [dashboard](./dashboard) shows each question in the browser.
+
+### What `always` saves
+
+- One `allow` rule for each path or command part of the call, for example `{ tool: 'bash', resource: 'pnpm test', decision: 'allow' }`. The rule names that exact text, not a glob.
+- One `allow` for the whole tool, when the tool does not say what it touches.
+- With a metadata store (`stores.metadata`), the rules belong to `root`. Every session with that `root` uses them, for every user, also after a restart.
+- Without a metadata store, the rules stay in memory until the session closes.
+- No rule for a part with shell syntax, `*`, or `?`. The next call like it asks again.
+
+## Rules in subagents
+
+The same check runs in every agent run of the session:
+
+- Each call in a child run gets the same rules and the same mode. This includes the agents that the model calls, the agents that plugins start, and their children.
+- A question from a child waits in the same session. Answer it the same way.
+- In `plan` mode, a child cannot change a file. Its call gets the tool error `This tool is not allowed in plan mode.`
+- The `permissions` of an [agent profile](./agents) count only while that profile is the primary agent. They do not apply when the profile runs as a subagent.
+- [Coding agents](./coding-agents#plan-mode) such as Claude Code start read-only in `plan` mode.
+
+## Rules for your own tool
+
+Your plugin adds a tool that touches files. A rule with a `resource` can match its calls only when the tool says what it touches. Add the tool to `PermissionResources`:
+
+```ts
+import { copyFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { toolDefinition } from '@tanstack/ai'
+import { PermissionResources, PermissionRules, definePlugin } from '@tanstack/ai-harness'
+import { z } from 'zod'
+
+const root = process.cwd()
+
+const copy = toolDefinition({
+  name: 'copy_file',
+  description: 'Copy a file in the project',
+  inputSchema: z.object({ from: z.string(), to: z.string() }),
+}).server(async ({ from, to }) => {
+  await copyFile(resolve(root, from), resolve(root, to))
+  return `Copied ${from} to ${to}.`
+})
+
+/** A string field of the raw input. It throws when the field is missing. */
+function field(input: unknown, key: string) {
+  const value =
+    typeof input === 'object' && input !== null ? Reflect.get(input, key) : undefined
+  if (typeof value !== 'string') throw new Error(`No ${key}.`)
+  return value
+}
+
+export const fileCopy = definePlugin({
+  name: 'acme/file-copy',
+  setup: () => ({
+    tools: [copy],
+    contribute: [
+      PermissionRules.item({ tool: 'copy_file', decision: 'ask', kind: 'edit' }),
+      PermissionResources.item({
+        copy_file: { paths: (input) => [field(input, 'from'), field(input, 'to')] },
+      }),
+    ],
+  }),
+})
+```
+
+Now `{ tool: 'copy_file', resource: 'docs/**', decision: 'allow' }` copies files in `docs` without a question.
+
+- Each function gets the raw input of the model, before the schema check. If it throws, the call does not run, and the model gets `Cannot check the permissions of this call: No from.`
+- `paths` are relative to `root`, or absolute. `commands` are command parts, one for each simple command.
+- `kind: 'edit'` puts the tool under the modes. `plan` denies it, and `acceptEdits` runs it.
+- If a tool does not say what it touches, a rule with a `resource` counts for every call. So a `deny` for one folder denies every call of the tool.
+- [Code mode](./code-mode) keeps a tool with resources as a normal tool call, so the plugin still checks each call.
+
+## Known limits
+
+- A rule that allows a tool with no `kind` also lets it run in `plan` mode. For example, an `allow` for `webfetch` lets it fetch pages in `plan` mode. `plan` denies only edits, commands, and calls that ask.
+- `serveAcp` does not show harness questions. An editor that uses [ACP](./connect#use-it-from-an-editor-acp) shows tool approvals only, so a call that asks waits.
+- A client that can send inputs to the thread can change the mode, also to `bypass`. It can also answer the questions. Control who opens a thread with `canAccess`. See [Connect clients](./connect).
+- There is no command to forget a saved `always` answer.
+
+## What you have now
+
+- A question before each edit, command, and web fetch.
+- Modes to plan, to edit fast, or to run everything.
+- Rules for folders, files, and commands, and saved answers for each project.
+- The same rules in every agent run.
+
+Next: give the agent a planner and a builder with [agent profiles](./agents).

From a0eb579684ed7e55025f581fdd9f85aef1c88a5c Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 17:57:38 +0200
Subject: [PATCH 264/286] feat: send the Anthropic thinking shape that the
 model record gives

Flue's shape check found 195 Anthropic Messages models where our
thinking fields differ from pi's. Gateway ids with dots
(anthropic/claude-opus-4.7) got budget thinking, older Claude on
OpenRouter got adaptive thinking, and most other models on the wire got
adaptive thinking because the adapter sent adaptive whenever a model had
no token budget.

Adaptive or budget from the record:
- ModelReasoning.adaptive: true sends adaptive thinking, false sends
  budget thinking. Without it, the adapter decides from the id, as before.
- Adaptive thinking without a level map sends pi's default effort.
- modelReasoning(record) sets adaptive from compat.forceAdaptiveThinking
  for anthropic-messages records.
- The catalog rule is pi's: Claude 4.6 and later (dash or dot ids) think
  adaptively. Fireworks takes pi's list. All 291 shared records now have
  pi's flag. Seven Fireworks records take Fireworks' own levels (pi), and
  Vercel gemma-4-31b-it reasons, as at Google and OpenRouter.

Mid-conversation effort (pi supportsMidConvoEffort):
- ModelReasoning.midConversationEffort, from the new
  compat.supportsMidConvoEffort (5 models, pi's list).
- The adapter sends adaptive thinking with block_binding and a fixed
  output_config.effort high, an effort system message before each
  earlier answer and one at the end, the two betas, and no temperature.
- Each answer keeps its effort in metadata.tanstack.reasoningEffort.
- The automatic cache marker skips the trailing effort message.

Mid-conversation channels: midConversationChannels takes
{ tools?, systemPrompts? } to turn on one channel only.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-anthropic/src/adapters/text.ts    |  96 +++-
 packages/ai-anthropic/src/prompt-cache.ts     |  14 +-
 packages/ai-anthropic/src/text/reasoning.ts   |  74 ++-
 .../tests/mid-conversation-changes.test.ts    |  46 ++
 .../tests/mid-conversation-effort.test.ts     | 190 ++++++++
 .../tests/reasoning-request.test.ts           |  59 +++
 packages/ai-models/scripts/known-ids.ts       |  22 +
 packages/ai-models/scripts/overrides.ts       |  52 ++-
 packages/ai-models/scripts/providers.ts       |  16 +-
 packages/ai-models/scripts/rules.ts           |  15 +-
 packages/ai-models/src/providers/anthropic.ts |   7 +-
 .../src/providers/cloudflare-ai-gateway.ts    |   4 +-
 packages/ai-models/src/providers/fireworks.ts |  42 +-
 packages/ai-models/src/providers/opencode.ts  |   2 +
 .../ai-models/src/providers/openrouter.ts     |   3 +
 .../src/providers/vercel-ai-gateway.ts        | 422 +++++++-----------
 packages/ai-models/src/reasoning.ts           |  14 +-
 packages/ai-models/src/types.ts               |  14 +-
 packages/ai-models/tests/catalog.test.ts      |  42 ++
 packages/ai-models/tests/rules.test.ts        |  30 +-
 packages/ai/src/activities/chat/index.ts      |   2 +
 packages/ai/src/reasoning.ts                  |  19 +-
 packages/ai/src/types.ts                      |   8 +
 23 files changed, 863 insertions(+), 330 deletions(-)
 create mode 100644 packages/ai-anthropic/tests/mid-conversation-effort.test.ts

diff --git a/packages/ai-anthropic/src/adapters/text.ts b/packages/ai-anthropic/src/adapters/text.ts
index 9e9273ee2b..3bfe902012 100644
--- a/packages/ai-anthropic/src/adapters/text.ts
+++ b/packages/ai-anthropic/src/adapters/text.ts
@@ -25,7 +25,8 @@ import {
   ANTHROPIC_DEFERRED_TOOL_PLACEHOLDER_NAME,
   applyAnthropicPromptCache,
 } from '../prompt-cache'
-import { anthropicThinking } from '../text/reasoning'
+import { anthropicThinking, isAnthropicEffort } from '../text/reasoning'
+import type { AnthropicEffort } from '../text/reasoning'
 import { ANTHROPIC_MODEL_REASONING } from '../model-reasoning'
 import type { AnthropicModelReasoningByName } from '../model-reasoning'
 import { buildAnthropicUsage } from '../usage'
@@ -203,7 +204,10 @@ export function messagesHaveFileSource(messages: Array<ModelMessage>): boolean {
  * - `skills-2025-10-02` when that tool carries skills,
  * - `context-management-2025-06-27` when `context_management` is set,
  * - `files-api-2025-04-14` when a message references an uploaded file handle,
- * - `mid-conversation-tool-changes-2026-07-01` in mid-conversation tool mode.
+ * - `mid-conversation-tool-changes-2026-07-01` in mid-conversation tool mode,
+ * - `mid-conversation-output-config-2026-07-01` and
+ *   `thinking-binding-controls-2026-08-01` with mid-conversation effort
+ *   (`thinking.block_binding`).
  * Returns `undefined` when none apply (so the call site omits `betas`).
  */
 export function computeAnthropicBetas(
@@ -213,6 +217,7 @@ export function computeAnthropicBetas(
         thinking?: {
           type?: 'enabled' | 'disabled' | 'adaptive'
           budget_tokens?: number
+          block_binding?: unknown
         }
         context_management?: unknown | null
         mcp_servers?: ReadonlyArray<unknown>
@@ -233,6 +238,10 @@ export function computeAnthropicBetas(
     typeof modelOptions.thinking.budget_tokens === 'number' &&
     modelOptions.thinking.budget_tokens > 0
   if (useInterleavedThinking) betas.add('interleaved-thinking-2025-05-14')
+  if (modelOptions?.thinking?.block_binding) {
+    betas.add('mid-conversation-output-config-2026-07-01')
+    betas.add('thinking-binding-controls-2026-08-01')
+  }
 
   // Context editing requires the beta header; the body field alone is not
   // enough (issue #1074). `null` is a typed "unset" — do not enable the beta.
@@ -304,6 +313,13 @@ interface AnthropicMidConversationSystemMessage {
   >
 }
 
+/** pi's effort message: a `system` message with no content that sets the effort. */
+function effortMessage(effort: AnthropicEffort): BetaMessageParam {
+  const message = { role: 'system', content: [], output_config: { effort } }
+  // oxlint-disable-next-line eslint-js/no-restricted-syntax -- SDK 0.97.1 types no `system` message in `messages`; the models with mid-conversation effort accept one (pi 0.87.1).
+  return message as unknown as BetaMessageParam
+}
+
 /**
  * Configuration for Anthropic text adapter
  */
@@ -329,9 +345,12 @@ export interface AnthropicTextConfig extends AnthropicClientConfig {
    * only for Anthropic's own API: a `baseURL`, a `fetch`, an injected
    * `client`, or the SDK's `ANTHROPIC_BASE_URL` env var turns the default off. `true` turns them on anyway, for a
    * gateway that passes the changes. `false` turns them off, so every
-   * request is built as before.
+   * request is built as before. An object turns on only the channels it
+   * names, for a gateway that passes one of them:
+   * `{ systemPrompts: true }` sends a system prompt change in place and a
+   * tool change as the full tool list.
    */
-  midConversationChannels?: boolean
+  midConversationChannels?: boolean | Partial<MidConversationChannels>
 }
 
 export type AnthropicTextAdapterConfig =
@@ -339,7 +358,7 @@ export type AnthropicTextAdapterConfig =
   | {
       client: AnthropicMessagesClient
       /** See {@link AnthropicTextConfig.midConversationChannels}. */
-      midConversationChannels?: boolean
+      midConversationChannels?: AnthropicTextConfig['midConversationChannels']
       oauth?: boolean
       allowEmptySignature?: boolean
       provider?: string
@@ -512,9 +531,16 @@ export class AnthropicTextAdapter<
       'client' in config ||
       Boolean(config.baseURL || config.fetch) ||
       envBaseURL
-    if (config.midConversationChannels ?? !customEndpoint) {
-      this.midConversationChannels =
-        ANTHROPIC_MODEL_MID_CONVERSATION_CHANNELS[model]
+    const table = ANTHROPIC_MODEL_MID_CONVERSATION_CHANNELS[model]
+    const option = config.midConversationChannels
+    if (typeof option === 'object') {
+      if (table)
+        this.midConversationChannels = {
+          tools: table.tools && option.tools === true,
+          systemPrompts: table.systemPrompts && option.systemPrompts === true,
+        }
+    } else if (option ?? !customEndpoint) {
+      this.midConversationChannels = table
     }
   }
 
@@ -818,9 +844,16 @@ export class AnthropicTextAdapter<
       }),
     }
     const mid = this.midConversationRequest(options)
+    // `chat({ reasoning })`, as this model's thinking fields.
+    const {
+      output_config: reasoningOutputConfig,
+      messageEffort,
+      ...thinkingFields
+    } = anthropicThinking(this.model, options.reasoning, this.modelReasoning)
     const formattedMessages = this.formatMessages(
       options.messages,
       mid?.systemMessages,
+      messageEffort,
     )
     const tools = options.tools
       ? (mid?.tools ?? convertToolsToProviderFormat(options.tools))
@@ -880,9 +913,8 @@ export class AnthropicTextAdapter<
       }
     }
 
-    // `chat({ reasoning })`, as this model's thinking fields.
-    const { output_config: reasoningOutputConfig, ...thinkingFields } =
-      anthropicThinking(this.model, options.reasoning, this.modelReasoning)
+    // pi sends no `temperature` with mid-conversation effort.
+    if (messageEffort !== undefined) delete validProviderOptions.temperature
     const thinkingBudget =
       thinkingFields.thinking?.type === 'enabled'
         ? thinkingFields.thinking.budget_tokens
@@ -1194,6 +1226,12 @@ export class AnthropicTextAdapter<
     messages: Array<ModelMessage>,
     /** Mid-conversation `system` messages by message index (`before`). */
     systemMessages?: ReadonlyMap<number, BetaMessageParam>,
+    /**
+     * Mid-conversation effort: this turn's effort. Each earlier assistant
+     * message of this provider gets its own effort message before it, and
+     * this one goes at the end (pi's `insertThinkingLevelMessages`).
+     */
+    messageEffort?: AnthropicEffort,
   ): InternalTextProviderOptions['messages'] {
     const formattedMessages: InternalTextProviderOptions['messages'] = []
     // A system message waits for the next assistant message (or the end),
@@ -1206,6 +1244,8 @@ export class AnthropicTextAdapter<
       if (systemMessage) pendingSystemMessages.push(systemMessage)
       if (role === 'assistant') {
         formattedMessages.push(...pendingSystemMessages.splice(0))
+        const stored = messageEffort && this.storedEffort(message)
+        if (stored) formattedMessages.push(effortMessage(stored))
       }
 
       if (role === 'tool' && message.toolCallId) {
@@ -1336,7 +1376,19 @@ export class AnthropicTextAdapter<
     // Post-process: Anthropic requires strictly alternating user/assistant roles.
     // Tool results are sent as role:'user' messages, which can create consecutive
     // user messages when followed by a new user message. Merge them.
-    return this.mergeConsecutiveSameRoleMessages(formattedMessages)
+    const merged = this.mergeConsecutiveSameRoleMessages(formattedMessages)
+    return messageEffort ? [...merged, effortMessage(messageEffort)] : merged
+  }
+
+  /** The effort an assistant message of this provider was made with. */
+  private storedEffort(message: ModelMessage): AnthropicEffort | undefined {
+    const tanstack = message.metadata?.tanstack
+    const effort = tanstack?.reasoningEffort
+    return tanstack?.source?.provider === this.provider &&
+      tanstack.source.api === this.api &&
+      isAnthropicEffort(effort)
+      ? effort
+      : undefined
   }
 
   private appendThinkingBlocks(
@@ -1435,7 +1487,13 @@ export class AnthropicTextAdapter<
       }
 
       const prev = merged[merged.length - 1]
-      if (prev && prev.role === msg.role) {
+      // An effort message stays a message of its own.
+      if (
+        prev &&
+        prev.role === msg.role &&
+        !('output_config' in prev) &&
+        !('output_config' in msg)
+      ) {
         // Normalize both contents to arrays and concatenate
         const prevBlocks = Array.isArray(prev.content)
           ? prev.content
@@ -1503,6 +1561,15 @@ export class AnthropicTextAdapter<
       api: this.api,
       model: options.model,
     }
+    // Mid-conversation effort: the message keeps its effort for the next turn.
+    const { messageEffort } = anthropicThinking(
+      this.model,
+      options.reasoning,
+      this.modelReasoning,
+    )
+    const effortMetadata = messageEffort
+      ? { metadata: { tanstack: { reasoningEffort: messageEffort } } }
+      : {}
     let accumulatedContent = ''
     let accumulatedThinking = ''
     let accumulatedSignature = ''
@@ -2021,6 +2088,7 @@ export class AnthropicTextAdapter<
             yield {
               type: EventType.RUN_FINISHED,
               ...(responseId !== undefined && { responseId }),
+              ...effortMetadata,
               runId,
               threadId,
               model,
@@ -2055,6 +2123,7 @@ export class AnthropicTextAdapter<
                 yield {
                   type: EventType.RUN_FINISHED,
                   ...(responseId !== undefined && { responseId }),
+                  ...effortMetadata,
                   runId,
                   threadId,
                   model,
@@ -2111,6 +2180,7 @@ export class AnthropicTextAdapter<
                 yield {
                   type: EventType.RUN_FINISHED,
                   ...(responseId !== undefined && { responseId }),
+                  ...effortMetadata,
                   runId,
                   threadId,
                   model,
diff --git a/packages/ai-anthropic/src/prompt-cache.ts b/packages/ai-anthropic/src/prompt-cache.ts
index 60f9fde70c..b48d2bfb87 100644
--- a/packages/ai-anthropic/src/prompt-cache.ts
+++ b/packages/ai-anthropic/src/prompt-cache.ts
@@ -73,13 +73,20 @@ function withCacheControl<T extends object>(
 /**
  * The messages with a marker on the last block of the last message. Returns
  * `null` when that message is not from the user or a mid-conversation
- * `system` message, or when its last block cannot take a marker.
+ * `system` message, or when its last block cannot take a marker. A
+ * mid-conversation effort message at the end has no blocks, so the marker
+ * goes on the message before it (pi 0.87.1 marks before it adds them).
  */
 function markLastUserMessage(
   messages: Array<BetaMessageParam>,
   cacheControl: BetaCacheControlEphemeral,
 ) {
-  const last = messages.at(-1)
+  const tail = messages.at(-1)
+  const end =
+    tail !== undefined && 'output_config' in tail
+      ? messages.length - 1
+      : messages.length
+  const last = messages[end - 1]
   // A mid-conversation `system` message at the end takes the marker, as in
   // pi 0.87.1. The SDK type has no `system` role, so compare it as a string.
   const role: string | undefined = last?.role
@@ -100,7 +107,7 @@ function markLastUserMessage(
     return null
   }
   return [
-    ...messages.slice(0, -1),
+    ...messages.slice(0, end - 1),
     {
       ...last,
       content: [
@@ -108,6 +115,7 @@ function markLastUserMessage(
         withCacheControl(lastBlock, cacheControl),
       ],
     },
+    ...messages.slice(end),
   ]
 }
 
diff --git a/packages/ai-anthropic/src/text/reasoning.ts b/packages/ai-anthropic/src/text/reasoning.ts
index 1767bb66b6..13016bd89c 100644
--- a/packages/ai-anthropic/src/text/reasoning.ts
+++ b/packages/ai-anthropic/src/text/reasoning.ts
@@ -4,11 +4,11 @@ import {
 } from '@tanstack/ai/adapter-internals'
 import type { ModelReasoning, ReasoningRequest } from '@tanstack/ai'
 
-type AnthropicEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+export type AnthropicEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max'
 
 const EFFORTS: ReadonlyArray<string> = ['low', 'medium', 'high', 'xhigh', 'max']
-const isEffort = (value: string): value is AnthropicEffort =>
-  EFFORTS.includes(value)
+export const isAnthropicEffort = (value: unknown): value is AnthropicEffort =>
+  typeof value === 'string' && EFFORTS.includes(value)
 
 /**
  * Claude 4.6 takes the effort as the top-level `effort` field. Claude 4.7 and
@@ -23,25 +23,48 @@ const TOP_LEVEL_EFFORT = new Set(['claude-opus-4-6', 'claude-sonnet-4-6'])
  */
 const ADAPTIVE_THINKING = /opus-4-[6-9]|sonnet-4-[6-9]|opus-5|sonnet-5|fable-5/
 
+/** pi's `mapThinkingLevelToEffort` for a level the map does not name. */
+const defaultEffort = (level: string): AnthropicEffort =>
+  level === 'minimal' || level === 'low'
+    ? 'low'
+    : level === 'medium'
+      ? 'medium'
+      : 'high'
+
 /** The Messages API thinking fields for one request. */
 export interface AnthropicThinkingFields {
   thinking?:
-    | { type: 'adaptive'; display: 'summarized' | 'omitted' }
+    | {
+        type: 'adaptive'
+        display: 'summarized' | 'omitted'
+        block_binding?: { prefix_mismatch_behavior: 'drop_block' }
+      }
     | { type: 'enabled'; budget_tokens: number }
     | { type: 'disabled' }
   effort?: AnthropicEffort
   output_config?: { effort: AnthropicEffort }
+  /**
+   * Mid-conversation effort: the effort of this turn. It goes into the
+   * messages, not into the request fields.
+   */
+  messageEffort?: AnthropicEffort
 }
 
 /**
  * The thinking fields for `chat({ reasoning })`:
+ * - mid-conversation effort (`reasoning.midConversationEffort`, pi's
+ *   managed effort): always adaptive thinking with `block_binding` and a
+ *   fixed `output_config.effort: 'high'`. The level's effort is
+ *   `messageEffort` (`high` without a level).
  * - `off`: thinking disabled. A model that cannot stop thinking never gets
  *   here, because the clamp moves `off` to its lowest level.
- * - a budget model without adaptive thinking, or a request with
- *   `budgetTokens`: `thinking.type: 'enabled'` with the budget (pi's table
- *   when the request sets none).
- * - otherwise adaptive thinking with the model's effort for the level.
- *   `summary` picks whether the thinking text streams back.
+ * - budget thinking (`thinking.type: 'enabled'`, pi's table when the
+ *   request sets no `budgetTokens`) when `reasoning.adaptive` is `false`, or
+ *   for a budget model that sets `budgetTokens`. Without `adaptive`, also
+ *   for a budget model without a map or outside `ADAPTIVE_THINKING`.
+ * - otherwise adaptive thinking with the model's effort for the level, or
+ *   pi's default effort when the map has none. `summary` picks whether the
+ *   thinking text streams back.
  */
 export function anthropicThinking(
   model: string,
@@ -49,13 +72,24 @@ export function anthropicThinking(
   reasoning: ModelReasoning | undefined,
 ): AnthropicThinkingFields {
   const resolved = resolveReasoning(request, reasoning)
+  if (reasoning && reasoning.midConversationEffort)
+    return {
+      thinking: {
+        type: 'adaptive',
+        display: resolved?.summary === false ? 'omitted' : 'summarized',
+        block_binding: { prefix_mismatch_behavior: 'drop_block' },
+      },
+      output_config: { effort: 'high' },
+      messageEffort: resolved ? effortOf(resolved) : 'high',
+    }
   if (!resolved || !reasoning) return {}
   if (resolved.level === 'off') return { thinking: { type: 'disabled' } }
+  const adaptive =
+    reasoning.adaptive ??
+    (!reasoning.budget ||
+      (reasoning.map !== undefined && ADAPTIVE_THINKING.test(model)))
   const budgetOnly =
-    reasoning.budget &&
-    (resolved.budgetTokens !== undefined ||
-      !reasoning.map ||
-      !ADAPTIVE_THINKING.test(model))
+    !adaptive || (reasoning.budget && resolved.budgetTokens !== undefined)
   if (budgetOnly)
     return {
       thinking: {
@@ -73,10 +107,18 @@ export function anthropicThinking(
     type: 'adaptive' as const,
     display: resolved.summary ? ('summarized' as const) : ('omitted' as const),
   }
-  const effort = resolved.value
-  if (!reasoning.map || effort === null || !isEffort(effort))
-    return { thinking }
+  const effort = effortOf(resolved)
   return TOP_LEVEL_EFFORT.has(model)
     ? { thinking, effort }
     : { thinking, output_config: { effort } }
 }
+
+/** The map's effort for the level, else pi's default effort. */
+function effortOf(resolved: {
+  level: string
+  value: string | null
+}): AnthropicEffort {
+  return isAnthropicEffort(resolved.value)
+    ? resolved.value
+    : defaultEffort(resolved.level)
+}
diff --git a/packages/ai-anthropic/tests/mid-conversation-changes.test.ts b/packages/ai-anthropic/tests/mid-conversation-changes.test.ts
index a9d48b98e9..e5b0236b1c 100644
--- a/packages/ai-anthropic/tests/mid-conversation-changes.test.ts
+++ b/packages/ai-anthropic/tests/mid-conversation-changes.test.ts
@@ -209,6 +209,25 @@ describe('Anthropic mid-conversation channels', () => {
     ).toEqual(both)
   })
 
+  it('turns on only the channels an object names', () => {
+    expect(
+      createAnthropicChat('claude-opus-5-5', 'test-key', {
+        baseURL: 'https://gateway.example.com',
+        midConversationChannels: { systemPrompts: true },
+      }).midConversationChannels,
+    ).toEqual({ tools: false, systemPrompts: true })
+    expect(
+      createAnthropicChat('claude-opus-5-5', 'test-key', {
+        midConversationChannels: { tools: true },
+      }).midConversationChannels,
+    ).toEqual({ tools: true, systemPrompts: false })
+    expect(
+      createAnthropicChat('claude-sonnet-5-5', 'test-key', {
+        midConversationChannels: { systemPrompts: true },
+      }).midConversationChannels,
+    ).toBeUndefined()
+  })
+
   it('is off with midConversationChannels: false, and outside the map even with true', () => {
     expect(
       createAnthropicChat('claude-opus-5-5', 'test-key', {
@@ -282,6 +301,33 @@ describe('Anthropic mid-conversation request', () => {
     })
   })
 
+  it('with { systemPrompts: true } on a custom baseURL: the prompt in place, the tools as the full list', async () => {
+    const body = await send(
+      'claude-opus-5-5',
+      {
+        messages: toolTurn,
+        tools: [lookup, fetchPage],
+        systemPrompts: ['Be brief.', 'Cite sources.'],
+        midConversationChanges: endChange,
+      },
+      {
+        baseURL: 'https://gateway.example.com',
+        midConversationChannels: { systemPrompts: true },
+      },
+    )
+
+    expect(body.system).toEqual([{ type: 'text', text: 'Be brief.' }])
+    expect(roles(body)).toEqual(['user', 'assistant', 'user', 'system'])
+    expect(body.messages[3]).toEqual({
+      role: 'system',
+      content: [{ type: 'text', text: 'Cite sources.' }],
+    })
+    expect(body.tools).toEqual(
+      convertToolsToProviderFormat([lookup, fetchPage]),
+    )
+    expect(body.betas ?? []).not.toContain(BETA)
+  })
+
   it('puts an added prompt in a system message before the next assistant message', async () => {
     const body = await send('claude-opus-5-5', {
       messages: [
diff --git a/packages/ai-anthropic/tests/mid-conversation-effort.test.ts b/packages/ai-anthropic/tests/mid-conversation-effort.test.ts
new file mode 100644
index 0000000000..2fcc52d7b7
--- /dev/null
+++ b/packages/ai-anthropic/tests/mid-conversation-effort.test.ts
@@ -0,0 +1,190 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { chat } from '@tanstack/ai'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { createAnthropicChat } from '../src'
+import type { ChatMiddleware, ModelMessage, ModelReasoning } from '@tanstack/ai'
+
+const mocks = vi.hoisted(() => ({ create: vi.fn() }))
+
+vi.mock('@anthropic-ai/sdk', () => {
+  class MockAnthropic {
+    beta = { messages: { create: mocks.create } }
+    messages = { create: vi.fn() }
+    constructor(_: { apiKey: string }) {}
+  }
+  return { default: MockAnthropic }
+})
+
+const logger = resolveDebugOption(false)
+
+function textStream() {
+  return (async function* () {
+    yield {
+      type: 'content_block_start',
+      index: 0,
+      content_block: { type: 'text', text: '' },
+    }
+    yield {
+      type: 'content_block_delta',
+      index: 0,
+      delta: { type: 'text_delta', text: 'ok' },
+    }
+    yield { type: 'content_block_stop', index: 0 }
+    yield {
+      type: 'message_delta',
+      delta: { stop_reason: 'end_turn' },
+      usage: { output_tokens: 1 },
+    }
+    yield { type: 'message_stop' }
+  })()
+}
+
+/** `modelReasoning(record)` of OpenRouter `anthropic/claude-opus-5.5`. */
+const MANAGED: ModelReasoning = {
+  map: {
+    off: null,
+    minimal: null,
+    low: 'low',
+    medium: 'medium',
+    high: 'high',
+    xhigh: 'xhigh',
+    max: 'max',
+  },
+  budget: false,
+  adaptive: true,
+  midConversationEffort: true,
+}
+const MODEL = 'anthropic/claude-opus-5.5'
+const adapter = () =>
+  createAnthropicChat(MODEL, 'test-key', { reasoning: MANAGED })
+
+const effortMessage = (effort: string) => ({
+  role: 'system',
+  content: [],
+  output_config: { effort },
+})
+
+/** One chat() turn. Returns the request body and the saved transcript. */
+async function turn(messages: Array<ModelMessage>, reasoning: 'low' | 'high') {
+  mocks.create.mockClear()
+  let saved: Array<ModelMessage> = []
+  const keep: ChatMiddleware = {
+    name: 'keep-transcript',
+    onFinish(ctx) {
+      saved = [...ctx.messages]
+    },
+  }
+  for await (const _chunk of chat({
+    adapter: adapter(),
+    messages,
+    reasoning,
+    middleware: [keep],
+    // The cache marker moves to the last user message on each turn
+    // (Anthropic's multi-turn pattern). It is not part of the cached
+    // content, so this test leaves it out and compares the bytes.
+    promptCache: 'none',
+  })) {
+    // Drain the stream.
+  }
+  const [body] = mocks.create.mock.calls[0] ?? []
+  return { body: body as Record<string, any>, saved }
+}
+
+describe('Anthropic mid-conversation effort', () => {
+  beforeEach(() => {
+    mocks.create.mockReset()
+    mocks.create.mockImplementation(() => Promise.resolve(textStream()))
+  })
+
+  it('sends the level in the messages and keeps the first request as the prefix', async () => {
+    const first = await turn([{ role: 'user', content: 'Hi' }], 'low')
+    expect(first.body.thinking).toEqual({
+      type: 'adaptive',
+      display: 'summarized',
+      block_binding: { prefix_mismatch_behavior: 'drop_block' },
+    })
+    expect(first.body.output_config).toEqual({ effort: 'high' })
+    expect(first.body.messages).toEqual([
+      { role: 'user', content: 'Hi' },
+      effortMessage('low'),
+    ])
+    // The answer keeps its effort for the next turn.
+    expect(first.saved.at(-1)?.metadata?.tanstack?.reasoningEffort).toBe('low')
+
+    // The level changes. The first request stays the start of the second.
+    const second = await turn(
+      [...first.saved, { role: 'user', content: 'Again' }],
+      'high',
+    )
+    const messages: Array<unknown> = second.body.messages
+    expect(JSON.stringify(messages.slice(0, 2))).toBe(
+      JSON.stringify(first.body.messages),
+    )
+    expect(messages.slice(2)).toEqual([
+      { role: 'assistant', content: [{ type: 'text', text: 'ok' }] },
+      { role: 'user', content: 'Again' },
+      effortMessage('high'),
+    ])
+    expect(second.body.thinking.block_binding).toEqual({
+      prefix_mismatch_behavior: 'drop_block',
+    })
+    expect(second.body.output_config).toEqual({ effort: 'high' })
+    expect(second.body.betas).toEqual(
+      expect.arrayContaining([
+        'mid-conversation-output-config-2026-07-01',
+        'thinking-binding-controls-2026-08-01',
+      ]),
+    )
+  })
+
+  it('leaves out the effort of another provider and sends high without a level', async () => {
+    const foreign: ModelMessage = {
+      role: 'assistant',
+      content: 'ok',
+      metadata: {
+        tanstack: {
+          source: { provider: 'openai', api: 'openai-responses', model: 'x' },
+          reasoningEffort: 'low',
+        },
+      },
+    }
+    mocks.create.mockClear()
+    for await (const _chunk of adapter().chatStream({
+      logger,
+      model: MODEL,
+      messages: [{ role: 'user', content: 'Hi' }, foreign],
+    })) {
+      // Drain the stream.
+    }
+    const [body] = mocks.create.mock.calls[0] ?? []
+    expect(
+      body.messages.map((message: { role: string }) => message.role),
+    ).toEqual(['user', 'assistant', 'system'])
+    expect(body.messages.at(-1)).toEqual(effortMessage('high'))
+  })
+
+  it('sends no temperature and keeps the cache marker on the last user message', async () => {
+    mocks.create.mockClear()
+    for await (const _chunk of adapter().chatStream({
+      logger,
+      model: MODEL,
+      messages: [{ role: 'user', content: 'Hi' }],
+      reasoning: { level: 'medium', summary: true },
+      modelOptions: { temperature: 0.5 },
+      promptCache: { retention: 'short' },
+    })) {
+      // Drain the stream.
+    }
+    const [body] = mocks.create.mock.calls[0] ?? []
+    expect(body).not.toHaveProperty('temperature')
+    expect(body.messages).toEqual([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'Hi', cache_control: { type: 'ephemeral' } },
+        ],
+      },
+      effortMessage('medium'),
+    ])
+  })
+})
diff --git a/packages/ai-anthropic/tests/reasoning-request.test.ts b/packages/ai-anthropic/tests/reasoning-request.test.ts
index 622a29c933..1f099cde5b 100644
--- a/packages/ai-anthropic/tests/reasoning-request.test.ts
+++ b/packages/ai-anthropic/tests/reasoning-request.test.ts
@@ -223,6 +223,65 @@ describe('Anthropic reasoning from the config', () => {
     expect(body).not.toHaveProperty('output_config')
   })
 
+  // The configs below are `modelReasoning(record)` of the catalog records
+  // (`@tanstack/ai-models` tests that part).
+  it('adaptive: true gives adaptive thinking to a dot id (Vercel anthropic/claude-opus-4.7)', async () => {
+    const body = await sendWith(
+      'anthropic/claude-opus-4.7',
+      { map: { ...effortMap, off: 'none' }, budget: true, adaptive: true },
+      on('high'),
+    )
+    expect(body.thinking).toEqual({ type: 'adaptive', display: 'summarized' })
+    expect(body.output_config).toEqual({ effort: 'high' })
+  })
+
+  it('adaptive: false gives budget thinking to older Claude (OpenRouter anthropic/claude-sonnet-4.5)', async () => {
+    const body = await sendWith(
+      'anthropic/claude-sonnet-4.5',
+      {
+        map: {
+          off: 'off',
+          minimal: null,
+          low: null,
+          medium: null,
+          high: 'high',
+        },
+        budget: false,
+        adaptive: false,
+      },
+      on('high'),
+    )
+    expect(body.thinking).toEqual({ type: 'enabled', budget_tokens: 16384 })
+    expect(body).not.toHaveProperty('output_config')
+  })
+
+  it('adaptive: false gives budget thinking to another model on the wire (Vercel openai/gpt-5)', async () => {
+    const body = await sendWith(
+      'openai/gpt-5',
+      {
+        map: { ...effortMap, minimal: 'minimal' },
+        budget: false,
+        adaptive: false,
+      },
+      on('medium'),
+    )
+    expect(body.thinking).toEqual({ type: 'enabled', budget_tokens: 8192 })
+    expect(body).not.toHaveProperty('output_config')
+  })
+
+  it("adaptive thinking without a map sends pi's default effort", async () => {
+    const config: ModelReasoning = { budget: false, adaptive: true }
+    const effort = async (level: ReasoningRequest['level']) =>
+      (await sendWith('kimi-for-coding-highspeed', config, on(level)))
+        .output_config
+    expect(await effort('minimal')).toEqual({ effort: 'low' })
+    expect(await effort('low')).toEqual({ effort: 'low' })
+    expect(await effort('medium')).toEqual({ effort: 'medium' })
+    expect(await effort('high')).toEqual({ effort: 'high' })
+    // No map: xhigh and max clamp to high.
+    expect(await effort('max')).toEqual({ effort: 'high' })
+  })
+
   it('clamps the level with the config, not with the table', async () => {
     // The table gives claude-opus-4-5 low, medium, and high with a budget.
     // This config has only high and max, and no budget.
diff --git a/packages/ai-models/scripts/known-ids.ts b/packages/ai-models/scripts/known-ids.ts
index a0eb81df49..4b5a95f9ee 100644
--- a/packages/ai-models/scripts/known-ids.ts
+++ b/packages/ai-models/scripts/known-ids.ts
@@ -248,3 +248,25 @@ export const FIREWORKS_ANTHROPIC_WIRE: ReadonlyArray<string> = [
   'accounts/fireworks/routers/minimax-latest',
   'accounts/fireworks/routers/qwen-max-latest',
 ]
+
+/**
+ * Fireworks models on the Anthropic endpoint that think with a budget (pi
+ * 0.87.1). The others think adaptively: pi has `effort` levels for them,
+ * and models.dev does not have them for all.
+ */
+export const FIREWORKS_BUDGET_THINKING: ReadonlyArray<string> = [
+  'accounts/fireworks/models/inkling',
+  'accounts/fireworks/models/kimi-k2p6',
+  'accounts/fireworks/models/kimi-k2p7-code',
+  'accounts/fireworks/models/nemotron-3-ultra-nvfp4',
+  'accounts/fireworks/models/nemotron-lightning-3p5-30b-a3b',
+  'accounts/fireworks/routers/qwen-max-latest',
+]
+
+/** The models with mid-conversation effort, by provider (pi 0.87.1 `supportsMidConvoEffort`). */
+export const MID_CONVERSATION_EFFORT: Readonly<
+  Record<string, ReadonlyArray<string>>
+> = {
+  anthropic: ['claude-fable-5-1', 'claude-opus-5', 'claude-opus-5-5'],
+  openrouter: ['anthropic/claude-fable-5.1', 'anthropic/claude-opus-5.5'],
+}
diff --git a/packages/ai-models/scripts/overrides.ts b/packages/ai-models/scripts/overrides.ts
index ea66304d03..d8e1ff6067 100644
--- a/packages/ai-models/scripts/overrides.ts
+++ b/packages/ai-models/scripts/overrides.ts
@@ -1,4 +1,4 @@
-import type { ModelRecord } from '../src/types'
+import type { ModelRecord, ReasoningLevel, ReasoningMap } from '../src/types'
 
 /** A model record without the fields its provider row fills in. */
 export type ExtraModel = Omit<ModelRecord, 'provider' | 'api' | 'baseUrl'> &
@@ -35,10 +35,58 @@ export const EXTRA_MODELS: Readonly<Record<string, ReadonlyArray<ExtraModel>>> =
     ],
   }
 
+/** A level map: `off` as given, the named levels as their own name, the rest `null`. */
+function only(
+  off: string | null,
+  ...levels: Array<ReasoningLevel>
+): ReasoningMap {
+  const map: ReasoningMap = { off }
+  for (const level of [
+    'minimal',
+    'low',
+    'medium',
+    'high',
+    'xhigh',
+    'max',
+  ] as const)
+    map[level] = levels.includes(level) ? level : null
+  return map
+}
+
 /**
  * Corrections for single models, merged over the generated record. Keep a
  * comment on each one that says why.
  */
 export const MODEL_OVERRIDES: Readonly<
   Record<string, Readonly<Record<string, Partial<ModelRecord>>>>
-> = {}
+> = {
+  // Fireworks' own effort levels on its Anthropic endpoint (pi 0.87.1).
+  // models.dev has no levels for these, and the record borrows the levels
+  // of the same model at another provider.
+  fireworks: {
+    'accounts/fireworks/models/deepseek-v4-flash-0731': {
+      reasoningMap: only('none', 'low', 'high', 'max'),
+    },
+    'accounts/fireworks/models/deepseek-v4-pro': {
+      reasoningMap: only('none', 'high', 'max'),
+    },
+    'accounts/fireworks/models/deepseek-v4-pro-0813': {
+      reasoningMap: only('none', 'low', 'high', 'max'),
+    },
+    'accounts/fireworks/models/muse-glimmer-30b': {
+      reasoningMap: only(null, 'low', 'medium', 'high', 'xhigh'),
+    },
+    'accounts/fireworks/models/qwen3p7-plus': {
+      reasoningMap: only('none', 'low', 'medium', 'high'),
+    },
+    'accounts/fireworks/models/qwen3p8-max': {
+      reasoningMap: only('none', 'low', 'medium', 'xhigh'),
+    },
+    'accounts/fireworks/routers/deepseek-pro-latest': {
+      reasoningMap: only('none', 'high', 'max'),
+    },
+  },
+  // models.dev lists no reasoning for it at Vercel. Google, OpenRouter, and
+  // pi 0.87.1 list it.
+  'vercel-ai-gateway': { 'google/gemma-4-31b-it': { reasoning: true } },
+}
diff --git a/packages/ai-models/scripts/providers.ts b/packages/ai-models/scripts/providers.ts
index d39cc3d3cf..4d4d1e8a91 100644
--- a/packages/ai-models/scripts/providers.ts
+++ b/packages/ai-models/scripts/providers.ts
@@ -1,4 +1,8 @@
-import { FIREWORKS_ANTHROPIC_WIRE } from './known-ids'
+import {
+  FIREWORKS_ANTHROPIC_WIRE,
+  FIREWORKS_BUDGET_THINKING,
+  MID_CONVERSATION_EFFORT,
+} from './known-ids'
 import type { ModelCompat, WireApi } from '../src/types'
 
 /** Where one model is served: its wire protocol and endpoint. */
@@ -143,6 +147,10 @@ export const PROVIDERS: ReadonlyArray<ProviderRow> = [
       ['ANTHROPIC_AUTH_TOKEN'],
     ],
     compat: { supportsStrictTools: true },
+    modelCompat: (id) =>
+      MID_CONVERSATION_EFFORT.anthropic?.includes(id)
+        ? { supportsMidConvoEffort: true }
+        : undefined,
   },
   {
     id: 'azure-openai-responses',
@@ -271,6 +279,9 @@ export const PROVIDERS: ReadonlyArray<ProviderRow> = [
             allowEmptySignature: true,
             supportsEagerToolInputStreaming: false,
             supportsCacheControlOnTools: false,
+            ...(!FIREWORKS_BUDGET_THINKING.includes(id) && {
+              forceAdaptiveThinking: true,
+            }),
           }
         : { ...NON_STANDARD, supportsStrictMode: true, ...deepseekFamily(id) },
   },
@@ -455,6 +466,9 @@ export const PROVIDERS: ReadonlyArray<ProviderRow> = [
       ...(id.startsWith('anthropic/')
         ? { cacheControlFormat: 'anthropic' as const }
         : {}),
+      ...(MID_CONVERSATION_EFFORT.openrouter?.includes(id)
+        ? { supportsMidConvoEffort: true }
+        : {}),
     }),
   },
   ...(
diff --git a/packages/ai-models/scripts/rules.ts b/packages/ai-models/scripts/rules.ts
index b2c5a8b8aa..d7dd2bc050 100644
--- a/packages/ai-models/scripts/rules.ts
+++ b/packages/ai-models/scripts/rules.ts
@@ -96,6 +96,10 @@ export function takesBudget(
   return (options ?? []).some((option) => option.type === 'budget_tokens')
 }
 
+/** Claude 4.6 and later, with dash or dot ids (`claude-opus-4-7`, `anthropic/claude-opus-4.7`). */
+const ADAPTIVE_CLAUDE =
+  /claude-(?:(?:opus|sonnet)-4[.-][6-9]|(?:opus|sonnet|fable)-[5-9])/
+
 /** The model hints models.dev has for the wire quirks. */
 export function modelHints(
   model: DevModel,
@@ -110,12 +114,11 @@ export function modelHints(
     hints.requiresReasoningContentOnAssistantMessages = true
   if (model.temperature === false) hints.supportsTemperature = false
   const options = model.reasoning_options ?? []
-  // Claude with `effort` and no token budget thinks adaptively only.
-  if (
-    wire.api === 'anthropic-messages' &&
-    effortValues(options) !== undefined &&
-    !takesBudget(options)
-  )
+  // pi's rule: Claude 4.6 and later think adaptively, on every provider.
+  // Another model on the Anthropic wire thinks with a budget unless its
+  // provider row says otherwise (models.dev lists `effort` for many models
+  // that a gateway serves with budget thinking).
+  if (wire.api === 'anthropic-messages' && ADAPTIVE_CLAUDE.test(model.id))
     hints.forceAdaptiveThinking = true
   if (effortByModel && wire.api === 'openai-completions')
     hints.supportsReasoningEffort = (effortValues(options)?.length ?? 0) > 0
diff --git a/packages/ai-models/src/providers/anthropic.ts b/packages/ai-models/src/providers/anthropic.ts
index 4897f09e36..c41fee6856 100644
--- a/packages/ai-models/src/providers/anthropic.ts
+++ b/packages/ai-models/src/providers/anthropic.ts
@@ -64,6 +64,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     maxTokens: 128000,
     compat: {
       supportsStrictTools: true,
+      supportsMidConvoEffort: true,
       supportsTemperature: false,
       forceAdaptiveThinking: true,
     },
@@ -163,7 +164,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { supportsStrictTools: true },
+    compat: { supportsStrictTools: true, forceAdaptiveThinking: true },
   },
   {
     id: 'claude-opus-4-7',
@@ -239,6 +240,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     maxTokens: 128000,
     compat: {
       supportsStrictTools: true,
+      supportsMidConvoEffort: true,
       supportsTemperature: false,
       forceAdaptiveThinking: true,
     },
@@ -265,6 +267,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     maxTokens: 128000,
     compat: {
       supportsStrictTools: true,
+      supportsMidConvoEffort: true,
       supportsTemperature: false,
       forceAdaptiveThinking: true,
     },
@@ -318,7 +321,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { supportsStrictTools: true },
+    compat: { supportsStrictTools: true, forceAdaptiveThinking: true },
   },
   {
     id: 'claude-sonnet-5',
diff --git a/packages/ai-models/src/providers/cloudflare-ai-gateway.ts b/packages/ai-models/src/providers/cloudflare-ai-gateway.ts
index 82b06f5718..6979fd5f28 100644
--- a/packages/ai-models/src/providers/cloudflare-ai-gateway.ts
+++ b/packages/ai-models/src/providers/cloudflare-ai-gateway.ts
@@ -268,7 +268,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { sendSessionAffinityHeaders: true },
+    compat: { sendSessionAffinityHeaders: true, forceAdaptiveThinking: true },
   },
   {
     id: 'claude-opus-4.7',
@@ -415,7 +415,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { sendSessionAffinityHeaders: true },
+    compat: { sendSessionAffinityHeaders: true, forceAdaptiveThinking: true },
   },
   {
     id: 'claude-sonnet-5',
diff --git a/packages/ai-models/src/providers/fireworks.ts b/packages/ai-models/src/providers/fireworks.ts
index e9deb986be..b9dffc1045 100644
--- a/packages/ai-models/src/providers/fireworks.ts
+++ b/packages/ai-models/src/providers/fireworks.ts
@@ -21,11 +21,13 @@ export const models: ReadonlyArray<ModelRecord> = [
     input: ['text'],
     reasoning: true,
     reasoningMap: {
-      off: 'off',
+      off: 'none',
       minimal: null,
-      low: null,
+      low: 'low',
       medium: null,
       high: 'high',
+      xhigh: null,
+      max: 'max',
     },
     cost: { input: 0.06, output: 0.18, cacheRead: 0.015, cacheWrite: 0 },
     contextWindow: 1048576,
@@ -36,6 +38,7 @@ export const models: ReadonlyArray<ModelRecord> = [
       allowEmptySignature: true,
       supportsEagerToolInputStreaming: false,
       supportsCacheControlOnTools: false,
+      forceAdaptiveThinking: true,
     },
     borrowedFrom: 'deepinfra/deepseek-ai/DeepSeek-V4-Flash-0731',
   },
@@ -80,7 +83,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     reasoningMap: {
       off: 'none',
       minimal: null,
-      low: 'low',
+      low: null,
       medium: null,
       high: 'high',
       xhigh: null,
@@ -110,7 +113,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     reasoningMap: {
       off: 'none',
       minimal: null,
-      low: null,
+      low: 'low',
       medium: null,
       high: 'high',
       xhigh: null,
@@ -420,6 +423,7 @@ export const models: ReadonlyArray<ModelRecord> = [
       allowEmptySignature: true,
       supportsEagerToolInputStreaming: false,
       supportsCacheControlOnTools: false,
+      forceAdaptiveThinking: true,
     },
     borrowedFrom: 'minimax/MiniMax-M2.7',
   },
@@ -461,13 +465,13 @@ export const models: ReadonlyArray<ModelRecord> = [
     input: ['text', 'image'],
     reasoning: true,
     reasoningMap: {
-      off: 'none',
+      off: null,
       minimal: null,
       low: 'low',
       medium: 'medium',
       high: 'high',
-      xhigh: null,
-      max: 'max',
+      xhigh: 'xhigh',
+      max: null,
     },
     cost: { input: 0.2, output: 0.8, cacheRead: 0.05, cacheWrite: 0 },
     contextWindow: 131072,
@@ -543,11 +547,13 @@ export const models: ReadonlyArray<ModelRecord> = [
     input: ['text', 'image', 'video'],
     reasoning: true,
     reasoningMap: {
-      off: 'off',
+      off: 'none',
       minimal: null,
-      low: null,
-      medium: null,
+      low: 'low',
+      medium: 'medium',
       high: 'high',
+      xhigh: null,
+      max: null,
     },
     reasoningBudget: true,
     cost: {
@@ -573,6 +579,7 @@ export const models: ReadonlyArray<ModelRecord> = [
       allowEmptySignature: true,
       supportsEagerToolInputStreaming: false,
       supportsCacheControlOnTools: false,
+      forceAdaptiveThinking: true,
     },
     borrowedFrom: 'alibaba/qwen3.7-plus',
   },
@@ -614,11 +621,13 @@ export const models: ReadonlyArray<ModelRecord> = [
     input: ['text', 'image'],
     reasoning: true,
     reasoningMap: {
-      off: 'off',
+      off: 'none',
       minimal: null,
-      low: null,
-      medium: null,
-      high: 'high',
+      low: 'low',
+      medium: 'medium',
+      high: null,
+      xhigh: 'xhigh',
+      max: null,
     },
     cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 0 },
     contextWindow: 262144,
@@ -629,6 +638,7 @@ export const models: ReadonlyArray<ModelRecord> = [
       allowEmptySignature: true,
       supportsEagerToolInputStreaming: false,
       supportsCacheControlOnTools: false,
+      forceAdaptiveThinking: true,
     },
   },
   {
@@ -671,7 +681,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     reasoningMap: {
       off: 'none',
       minimal: null,
-      low: 'low',
+      low: null,
       medium: null,
       high: 'high',
       xhigh: null,
@@ -863,6 +873,7 @@ export const models: ReadonlyArray<ModelRecord> = [
       allowEmptySignature: true,
       supportsEagerToolInputStreaming: false,
       supportsCacheControlOnTools: false,
+      forceAdaptiveThinking: true,
       supportsTemperature: false,
     },
   },
@@ -924,6 +935,7 @@ export const models: ReadonlyArray<ModelRecord> = [
       allowEmptySignature: true,
       supportsEagerToolInputStreaming: false,
       supportsCacheControlOnTools: false,
+      forceAdaptiveThinking: true,
       supportsTemperature: false,
     },
   },
diff --git a/packages/ai-models/src/providers/opencode.ts b/packages/ai-models/src/providers/opencode.ts
index 78b6dd3f5c..14d51c3b5a 100644
--- a/packages/ai-models/src/providers/opencode.ts
+++ b/packages/ai-models/src/providers/opencode.ts
@@ -161,6 +161,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
     contextWindow: 1000000,
     maxTokens: 128000,
+    compat: { forceAdaptiveThinking: true },
   },
   {
     id: 'claude-opus-4-7',
@@ -325,6 +326,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
     contextWindow: 1000000,
     maxTokens: 64000,
+    compat: { forceAdaptiveThinking: true },
   },
   {
     id: 'claude-sonnet-5',
diff --git a/packages/ai-models/src/providers/openrouter.ts b/packages/ai-models/src/providers/openrouter.ts
index 6cc79abd6a..d14cd478ad 100644
--- a/packages/ai-models/src/providers/openrouter.ts
+++ b/packages/ai-models/src/providers/openrouter.ts
@@ -971,6 +971,7 @@ export const models: ReadonlyArray<ModelRecord> = [
       sessionAffinityFormat: 'openrouter',
       supportsDeveloperRole: true,
       cacheControlFormat: 'anthropic',
+      supportsMidConvoEffort: true,
       supportsTemperature: false,
       forceAdaptiveThinking: true,
     },
@@ -1188,6 +1189,7 @@ export const models: ReadonlyArray<ModelRecord> = [
       sessionAffinityFormat: 'openrouter',
       supportsDeveloperRole: true,
       cacheControlFormat: 'anthropic',
+      forceAdaptiveThinking: true,
     },
   },
   {
@@ -1441,6 +1443,7 @@ export const models: ReadonlyArray<ModelRecord> = [
       sessionAffinityFormat: 'openrouter',
       supportsDeveloperRole: true,
       cacheControlFormat: 'anthropic',
+      supportsMidConvoEffort: true,
       forceAdaptiveThinking: true,
     },
   },
diff --git a/packages/ai-models/src/providers/vercel-ai-gateway.ts b/packages/ai-models/src/providers/vercel-ai-gateway.ts
index 59ee404e5c..228480a333 100644
--- a/packages/ai-models/src/providers/vercel-ai-gateway.ts
+++ b/packages/ai-models/src/providers/vercel-ai-gateway.ts
@@ -52,7 +52,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.22, output: 0.88, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 262144,
     maxTokens: 16384,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'alibaba/qwen-3-30b',
@@ -696,7 +696,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 0 },
     contextWindow: 262144,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'alibaba/qwen3.8-27b',
@@ -718,7 +718,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.5, output: 3, cacheRead: 0.1, cacheWrite: 0.625 },
     contextWindow: 1000000,
     maxTokens: 131072,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'alibaba/qwen3.8-flash',
@@ -832,7 +832,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.15, output: 0.47, cacheRead: 0.016, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 131072,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'amazon/nova-2-lite',
@@ -854,7 +854,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.3, output: 2.5, cacheRead: 0.075, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 65535,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'amazon/nova-lite',
@@ -942,7 +942,11 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, supportsTemperature: false },
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
   },
   {
     id: 'anthropic/claude-fable-5.1',
@@ -965,7 +969,11 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 10, output: 50, cacheRead: 0.25, cacheWrite: 12.5 },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, supportsTemperature: false },
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
   },
   {
     id: 'anthropic/claude-haiku-4.5',
@@ -1053,7 +1061,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true },
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
   },
   {
     id: 'anthropic/claude-opus-4.7',
@@ -1076,7 +1084,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true },
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
   },
   {
     id: 'anthropic/claude-opus-4.8',
@@ -1099,7 +1107,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true },
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
   },
   {
     id: 'anthropic/claude-opus-4.8-fast',
@@ -1122,7 +1130,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true },
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
   },
   {
     id: 'anthropic/claude-opus-5',
@@ -1145,7 +1153,11 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, supportsTemperature: false },
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
   },
   {
     id: 'anthropic/claude-opus-5-fast',
@@ -1168,7 +1180,11 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 10, output: 50, cacheRead: 1, cacheWrite: 12.5 },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, supportsTemperature: false },
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
   },
   {
     id: 'anthropic/claude-opus-5.5',
@@ -1306,7 +1322,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true },
+    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
   },
   {
     id: 'anthropic/claude-sonnet-5',
@@ -1329,7 +1345,11 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, supportsTemperature: false },
+    compat: {
+      allowEmptySignature: true,
+      supportsTemperature: false,
+      forceAdaptiveThinking: true,
+    },
   },
   {
     id: 'anthropic/claude-sonnet-5.5',
@@ -1377,7 +1397,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.25, output: 0.9, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 262100,
     maxTokens: 80000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'bytedance/seed-1.6',
@@ -1447,7 +1467,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 256000,
     maxTokens: 32768,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'bytedance/seed-2.1-turbo',
@@ -1469,7 +1489,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.5, output: 2.5, cacheRead: 0.1, cacheWrite: 0 },
     contextWindow: 262144,
     maxTokens: 262144,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'cohere/command-a',
@@ -1595,7 +1615,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.25, output: 0.95, cacheRead: 0.13, cacheWrite: 0 },
     contextWindow: 163840,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'deepseek/deepseek-v3.1-terminus',
@@ -1617,7 +1637,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.27, output: 1, cacheRead: 0.135, cacheWrite: 0 },
     contextWindow: 131072,
     maxTokens: 32768,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'deepseek/deepseek-v3.2',
@@ -1652,7 +1672,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.62, output: 1.85, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 128000,
     maxTokens: 8000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'deepseek/deepseek-v4-flash',
@@ -1674,7 +1694,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.13, output: 0.26, cacheRead: 0.028, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 384000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'deepseek/deepseek-v4-flash-0731',
@@ -1696,7 +1716,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.076, output: 0.153, cacheRead: 0.014, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 384000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'deepseek/deepseek-v4-flash-vision-exp',
@@ -1718,7 +1738,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.2156, output: 0.6468, cacheRead: 0.0068, cacheWrite: 0 },
     contextWindow: 1048576,
     maxTokens: 1048576,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'deepseek/deepseek-v4-pro',
@@ -1740,7 +1760,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.66, output: 1.98, cacheRead: 0.022, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 384000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'deepseek/deepseek-v4-pro-0813',
@@ -1762,7 +1782,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.66, output: 1.98, cacheRead: 0.066, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 384000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'deepseek/deepseek-v4.1-flash',
@@ -1784,7 +1804,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.3, output: 1.2, cacheRead: 0.007, cacheWrite: 0 },
     contextWindow: 1048576,
     maxTokens: 32768,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'deepseek/deepseek-v4.1-flash-fast',
@@ -1806,7 +1826,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.3, output: 1.2, cacheRead: 0.006, cacheWrite: 0 },
     contextWindow: 1048576,
     maxTokens: 1000000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'fireworks/ember-1',
@@ -1949,7 +1969,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 65000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'google/gemini-3-pro-image',
@@ -1984,7 +2004,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0 },
     contextWindow: 131072,
     maxTokens: 32768,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'google/gemini-3.1-flash-image-preview',
@@ -2006,7 +2026,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.5, output: 3, cacheRead: 0.05, cacheWrite: 0 },
     contextWindow: 131072,
     maxTokens: 32768,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'google/gemini-3.1-flash-lite',
@@ -2028,7 +2048,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.25, output: 1.5, cacheRead: 0.03, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 65000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'google/gemini-3.1-flash-lite-image',
@@ -2050,7 +2070,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.25, output: 1.5, cacheRead: 0.03, cacheWrite: 0 },
     contextWindow: 65536,
     maxTokens: 4096,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'google/gemini-3.1-pro-preview',
@@ -2086,7 +2106,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1000000,
     maxTokens: 64000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'google/gemini-3.5-flash',
@@ -2108,7 +2128,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.5, output: 9, cacheRead: 0.15, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 64000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'google/gemini-3.5-flash-lite',
@@ -2130,7 +2150,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.3, output: 2.5, cacheRead: 0.03, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 65000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'google/gemini-3.5-transcribe',
@@ -2178,7 +2198,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 64000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'google/gemini-3.7-flash',
@@ -2200,7 +2220,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 65535,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'google/gemini-3.8-flash',
@@ -2222,7 +2242,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.75, output: 3.75, cacheRead: 0.075, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 65535,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'google/gemini-3.8-live',
@@ -2296,7 +2316,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.5, output: 9, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 57920,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'google/gemma-4-26b-a4b-it',
@@ -2318,7 +2338,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     api: 'anthropic-messages',
     baseUrl: 'https://ai-gateway.vercel.sh',
     input: ['text', 'image', 'document'],
-    reasoning: false,
+    reasoning: true,
     cost: { input: 0.14, output: 0.4, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 262144,
     maxTokens: 131072,
@@ -2375,7 +2395,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 128000,
     maxTokens: 50000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'inception/mercury-2.5',
@@ -2397,7 +2417,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.04, output: 0.15, cacheRead: 0.004, cacheWrite: 0 },
     contextWindow: 260000,
     maxTokens: 65536,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'inception/mercury-coder-small',
@@ -2472,7 +2492,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.075, output: 0.22, cacheRead: 0.015, cacheWrite: 0 },
     contextWindow: 262144,
     maxTokens: 235929,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
     borrowedFrom: 'kilo/inclusionai/ling-3.0-flash-fin',
   },
   {
@@ -2495,7 +2515,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 256000,
     maxTokens: 32000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'inclusionai/ling-3.0-flash-sante-free',
@@ -2517,7 +2537,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 256000,
     maxTokens: 32000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'inclusionai/ling-3.0-flash-vl',
@@ -2559,7 +2579,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.06, output: 0.18, cacheRead: 0.012, cacheWrite: 0 },
     contextWindow: 262144,
     maxTokens: 32768,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
     borrowedFrom: 'nano-gpt/inclusionai/ling-3.0-flash-vl',
   },
   {
@@ -2582,7 +2602,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 262144,
     maxTokens: 32768,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'inclusionai/ling-3.1-flash-free',
@@ -2604,7 +2624,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 262144,
     maxTokens: 32768,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'inference-net/schematron-v2-small',
@@ -2652,7 +2672,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.5, output: 3.5, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 32000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'liquid/d1',
@@ -2772,7 +2792,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.35, output: 1.5, cacheRead: 0.04, cacheWrite: 0 },
     contextWindow: 131072,
     maxTokens: 131072,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'meta/muse-spark-1.1',
@@ -2794,7 +2814,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
     contextWindow: 1048576,
     maxTokens: 1048576,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'meta/muse-spark-1.2',
@@ -2816,7 +2836,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
     contextWindow: 1048576,
     maxTokens: 1048576,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'meta/muse-spark-1.2-contributor',
@@ -2838,7 +2858,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.1, output: 0.2, cacheRead: 0.002, cacheWrite: 0 },
     contextWindow: 1048576,
     maxTokens: 1048576,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'meta/muse-spark-1.3',
@@ -2860,7 +2880,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
     contextWindow: 1048576,
     maxTokens: 1048576,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'meta/muse-spark-1.3-contributor',
@@ -2882,7 +2902,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.1, output: 0.2, cacheRead: 0.002, cacheWrite: 0 },
     contextWindow: 1048576,
     maxTokens: 1048576,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'microsoft/mai-transcribe-1.5',
@@ -3146,7 +3166,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.5, output: 7.5, cacheRead: 0.15, cacheWrite: 0 },
     contextWindow: 262144,
     maxTokens: 256000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'mistral/mistral-nemo',
@@ -3220,7 +3240,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.47, output: 2, cacheRead: 0.141, cacheWrite: 0 },
     contextWindow: 216144,
     maxTokens: 216144,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'moonshotai/kimi-k2.5',
@@ -3282,7 +3302,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.95, output: 4, cacheRead: 0.19, cacheWrite: 0 },
     contextWindow: 256000,
     maxTokens: 32768,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'moonshotai/kimi-k2.7-code-highspeed',
@@ -3304,7 +3324,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.9, output: 8, cacheRead: 0.38, cacheWrite: 0 },
     contextWindow: 262144,
     maxTokens: 32768,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'moonshotai/kimi-k3',
@@ -3326,11 +3346,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 131072,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'moonshotai/kimi-k3-fast',
@@ -3352,11 +3368,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 4.5, output: 22.5, cacheRead: 0.45, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 131072,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'morph/morph-v3-fast',
@@ -3424,7 +3436,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.15, output: 0.65, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 256000,
     maxTokens: 32000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'nvidia/nemotron-3-ultra-550b-a55b',
@@ -3446,7 +3458,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 65000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'nvidia/nemotron-3.5-lightning',
@@ -3711,11 +3723,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-5-codex',
@@ -3737,11 +3745,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.25, output: 10, cacheRead: 0.13, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-5-fast',
@@ -3763,11 +3767,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 2.5, output: 20, cacheRead: 0.25, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-5-mini',
@@ -3789,11 +3789,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.25, output: 2, cacheRead: 0.025, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-5-mini-fast',
@@ -3815,11 +3811,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.45, output: 3.6, cacheRead: 0.045, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-5-nano',
@@ -3841,11 +3833,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.05, output: 0.4, cacheRead: 0.005, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-5-pro',
@@ -3867,7 +3855,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 15, output: 120, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 272000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.1-codex',
@@ -3889,7 +3877,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.25, output: 10, cacheRead: 0.13, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.1-codex-max',
@@ -3911,7 +3899,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.1-codex-mini',
@@ -3933,7 +3921,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.25, output: 2, cacheRead: 0.03, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.1-thinking',
@@ -3955,7 +3943,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.1-thinking-fast',
@@ -3977,7 +3965,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 2.5, output: 20, cacheRead: 0.25, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.2',
@@ -3999,7 +3987,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.2-codex',
@@ -4021,7 +4009,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.2-fast',
@@ -4043,7 +4031,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 3.5, output: 28, cacheRead: 0.35, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.2-pro',
@@ -4065,7 +4053,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 21, output: 168, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.3-codex',
@@ -4087,7 +4075,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.3-codex-fast',
@@ -4109,7 +4097,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 3.5, output: 28, cacheRead: 0.35, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.4',
@@ -4145,7 +4133,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1050000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.4-fast',
@@ -4167,7 +4155,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
     contextWindow: 1050000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.4-mini',
@@ -4189,7 +4177,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.75, output: 4.5, cacheRead: 0.075, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.4-mini-fast',
@@ -4211,7 +4199,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.5, output: 9, cacheRead: 0.15, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.4-nano',
@@ -4233,7 +4221,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.2, output: 1.25, cacheRead: 0.02, cacheWrite: 0 },
     contextWindow: 400000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.4-pro',
@@ -4269,7 +4257,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1050000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.5',
@@ -4305,7 +4293,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.5-fast',
@@ -4327,11 +4315,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 12.5, output: 75, cacheRead: 1.25, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-5.5-pro',
@@ -4367,7 +4351,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.6-luna',
@@ -4403,7 +4387,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1050000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.6-luna-fast',
@@ -4439,11 +4423,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1050000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-5.6-sol',
@@ -4479,7 +4459,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1050000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.6-sol-fast',
@@ -4515,11 +4495,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1050000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-5.6-terra',
@@ -4555,7 +4531,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1050000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-5.6-terra-fast',
@@ -4591,11 +4567,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1050000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-6-astra',
@@ -4631,11 +4603,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1050000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-6-astra-fast',
@@ -4671,11 +4639,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1050000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-6-luna',
@@ -4711,11 +4675,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1050000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-6-luna-fast',
@@ -4751,11 +4711,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1050000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-6-sol',
@@ -4791,11 +4747,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1050000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-6-sol-fast',
@@ -4831,11 +4783,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1050000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-6.1-sol',
@@ -4871,11 +4819,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1050000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-6.1-sol-fast',
@@ -4911,11 +4855,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1050000,
     maxTokens: 128000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/gpt-live-1',
@@ -4950,7 +4890,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.1, output: 0.5, cacheRead: 0.1, cacheWrite: 0 },
     contextWindow: 131072,
     maxTokens: 131072,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-oss-20b',
@@ -4972,7 +4912,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.03, output: 0.14, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 131072,
     maxTokens: 8192,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-oss-safeguard-120b',
@@ -4994,7 +4934,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.15, output: 0.6, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 128000,
     maxTokens: 16000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-oss-safeguard-20b',
@@ -5016,7 +4956,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.07, output: 0.2, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 128000,
     maxTokens: 16000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-realtime-1.5',
@@ -5064,7 +5004,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 4, output: 24, cacheRead: 0.4, cacheWrite: 0 },
     contextWindow: 128000,
     maxTokens: 32000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/gpt-realtime-mini',
@@ -5112,11 +5052,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 15, output: 60, cacheRead: 7.5, cacheWrite: 0 },
     contextWindow: 200000,
     maxTokens: 100000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/o3',
@@ -5138,11 +5074,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 2, output: 8, cacheRead: 0.5, cacheWrite: 0 },
     contextWindow: 200000,
     maxTokens: 100000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/o3-fast',
@@ -5164,11 +5096,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 3.5, output: 14, cacheRead: 0.875, cacheWrite: 0 },
     contextWindow: 200000,
     maxTokens: 100000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/o3-mini',
@@ -5190,11 +5118,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.1, output: 4.4, cacheRead: 0.55, cacheWrite: 0 },
     contextWindow: 200000,
     maxTokens: 100000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/o3-pro',
@@ -5216,7 +5140,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 20, output: 80, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 200000,
     maxTokens: 100000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'openai/o4-mini',
@@ -5238,11 +5162,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.1, output: 4.4, cacheRead: 0.275, cacheWrite: 0 },
     contextWindow: 200000,
     maxTokens: 100000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/o4-mini-fast',
@@ -5264,11 +5184,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 2, output: 8, cacheRead: 0.5, cacheWrite: 0 },
     contextWindow: 200000,
     maxTokens: 100000,
-    compat: {
-      allowEmptySignature: true,
-      supportsTemperature: false,
-      forceAdaptiveThinking: true,
-    },
+    compat: { allowEmptySignature: true, supportsTemperature: false },
   },
   {
     id: 'openai/text-embedding-3-large',
@@ -5421,7 +5337,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 4, output: 20, cacheRead: 0.4, cacheWrite: 5 },
     contextWindow: 131072,
     maxTokens: 65536,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'quiverai/arrow-2-telos',
@@ -5443,7 +5359,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 6, output: 30, cacheRead: 0.6, cacheWrite: 7.5 },
     contextWindow: 131072,
     maxTokens: 65536,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'sakana/fugu-max',
@@ -5465,7 +5381,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 2, output: 6, cacheRead: 0.25, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 1000000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'sakana/fugu-ultra',
@@ -5501,7 +5417,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1000000,
     maxTokens: 1000000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'sakana/fugu-ultra-v2',
@@ -5537,7 +5453,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1000000,
     maxTokens: 1000000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'sakana/namazu',
@@ -5559,7 +5475,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.95, output: 4, cacheRead: 0.15, cacheWrite: 0 },
     contextWindow: 256000,
     maxTokens: 256000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'spacexai/grok-4.1-fast-non-reasoning',
@@ -5594,7 +5510,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.2, output: 0.5, cacheRead: 0.05, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 1000000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'spacexai/grok-4.20-multi-agent',
@@ -5630,7 +5546,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 2000000,
     maxTokens: 2000000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'spacexai/grok-4.20-multi-agent-beta',
@@ -5666,7 +5582,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 2000000,
     maxTokens: 2000000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'spacexai/grok-4.20-non-reasoning',
@@ -5756,7 +5672,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 2000000,
     maxTokens: 2000000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'spacexai/grok-4.20-reasoning-beta',
@@ -5792,7 +5708,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 2000000,
     maxTokens: 2000000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'spacexai/grok-4.3',
@@ -5828,7 +5744,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 1000000,
     maxTokens: 1000000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'spacexai/grok-4.5',
@@ -5864,7 +5780,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 500000,
     maxTokens: 500000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'spacexai/grok-4.6',
@@ -5900,7 +5816,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 500000,
     maxTokens: 500000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'spacexai/grok-4.7',
@@ -5936,7 +5852,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 500000,
     maxTokens: 500000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'spacexai/grok-build-0.1',
@@ -5972,7 +5888,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     },
     contextWindow: 256000,
     maxTokens: 256000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'spacexai/grok-stt',
@@ -6033,7 +5949,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 262144,
     maxTokens: 131072,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'stepfun/step-3.5-flash',
@@ -6055,7 +5971,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.09, output: 0.3, cacheRead: 0.02, cacheWrite: 0 },
     contextWindow: 262114,
     maxTokens: 262114,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'stepfun/step-3.7-flash',
@@ -6077,7 +5993,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.2, output: 1.15, cacheRead: 0.04, cacheWrite: 0 },
     contextWindow: 256000,
     maxTokens: 256000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'stepfun/step-5-preview',
@@ -6151,7 +6067,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.14, output: 0.58, cacheRead: 0.035, cacheWrite: 0 },
     contextWindow: 262144,
     maxTokens: 262144,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'tencent/hy4-preview',
@@ -6173,7 +6089,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.834, output: 2.501, cacheRead: 0.042, cacheWrite: 0 },
     contextWindow: 1024000,
     maxTokens: 64000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'thinkingmachines/inkling',
@@ -6195,7 +6111,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1, output: 4.05, cacheRead: 0.17, cacheWrite: 0 },
     contextWindow: 256000,
     maxTokens: 256000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'thinkingmachines/inkling-small',
@@ -6217,7 +6133,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.45, output: 1.2, cacheRead: 0.1, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 1000000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'typesafe-ai/jev',
@@ -6474,7 +6390,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
     contextWindow: 1048576,
     maxTokens: 131072,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'xiaomi/mimo-v2.6-pro',
@@ -6496,7 +6412,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.435, output: 0.87, cacheRead: 0.0036, cacheWrite: 0 },
     contextWindow: 1048576,
     maxTokens: 131072,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'xiaomi/mimo-v2.6-pro-ultraspeed',
@@ -6518,7 +6434,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 4.35, output: 8.7, cacheRead: 0.036, cacheWrite: 0 },
     contextWindow: 1048576,
     maxTokens: 131072,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'zai/glm-4.5',
@@ -6740,7 +6656,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.8, output: 2.55, cacheRead: 0.16, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'zai/glm-5.2-fast',
@@ -6762,7 +6678,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 2.8, output: 8.8, cacheRead: 0.56, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 128000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'zai/glm-5.3',
@@ -6784,7 +6700,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 1.4, output: 4.4, cacheRead: 0.14, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 1000000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'zai/glm-5.3-fast',
@@ -6806,7 +6722,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 2.1, output: 6.6, cacheRead: 0.21, cacheWrite: 0 },
     contextWindow: 1048576,
     maxTokens: 262144,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'zai/glm-5.3-flash',
@@ -6828,7 +6744,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.15, output: 0.5, cacheRead: 0.03, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 131000,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'zai/glm-5.3-flashx',
@@ -6850,7 +6766,7 @@ export const models: ReadonlyArray<ModelRecord> = [
     cost: { input: 0.37, output: 1.25, cacheRead: 0.075, cacheWrite: 0 },
     contextWindow: 1000000,
     maxTokens: 131072,
-    compat: { allowEmptySignature: true, forceAdaptiveThinking: true },
+    compat: { allowEmptySignature: true },
   },
   {
     id: 'zai/glm-5v-turbo',
diff --git a/packages/ai-models/src/reasoning.ts b/packages/ai-models/src/reasoning.ts
index 346009b384..243f2fcb90 100644
--- a/packages/ai-models/src/reasoning.ts
+++ b/packages/ai-models/src/reasoning.ts
@@ -3,14 +3,26 @@ import type { ModelReasoning, ModelRecord, ReasoningLevel } from './types'
 /**
  * The record's reasoning data for an adapter's `reasoning` config:
  * `createAnthropicChat(record.id, key, { reasoning: modelReasoning(record) })`.
+ * An Anthropic Messages record also gives its thinking shape: `adaptive`
+ * from `compat.forceAdaptiveThinking`, and `midConversationEffort` from
+ * `compat.supportsMidConvoEffort`.
  */
 export function modelReasoning(
-  model: Pick<ModelRecord, 'reasoning' | 'reasoningMap' | 'reasoningBudget'>,
+  model: Pick<ModelRecord, 'reasoning' | 'reasoningMap' | 'reasoningBudget'> &
+    Partial<Pick<ModelRecord, 'api' | 'compat'>>,
 ): ModelReasoning {
   if (!model.reasoning) return false
+  const anthropic = model.api === 'anthropic-messages'
   return {
     ...(model.reasoningMap ? { map: model.reasoningMap } : {}),
     budget: model.reasoningBudget === true,
+    ...(anthropic && {
+      adaptive: model.compat?.forceAdaptiveThinking === true,
+    }),
+    ...(anthropic &&
+      model.compat?.supportsMidConvoEffort === true && {
+        midConversationEffort: true,
+      }),
   }
 }
 
diff --git a/packages/ai-models/src/types.ts b/packages/ai-models/src/types.ts
index 2b7440fb45..27c00a1e5a 100644
--- a/packages/ai-models/src/types.ts
+++ b/packages/ai-models/src/types.ts
@@ -21,9 +21,17 @@ export type ReasoningMap = Partial<Record<ReasoningLevel, string | null>>
 /**
  * A model's reasoning data, in the shape of the `reasoning` config of the
  * `@tanstack/ai` adapters (`ModelReasoning` there). `false`: the model does
- * not reason. Otherwise its level map and whether it takes a token budget.
+ * not reason. Otherwise its level map, whether it takes a token budget, and
+ * for Anthropic Messages, its thinking shape.
  */
-export type ModelReasoning = false | { map?: ReasoningMap; budget: boolean }
+export type ModelReasoning =
+  | false
+  | {
+      map?: ReasoningMap
+      budget: boolean
+      adaptive?: boolean
+      midConversationEffort?: boolean
+    }
 
 /** The wire protocol of a model. It picks the adapter. */
 export type WireApi =
@@ -79,6 +87,8 @@ export interface ModelCompat {
   supportsTemperature?: boolean
   // Anthropic Messages.
   forceAdaptiveThinking?: boolean
+  /** The level goes into the messages, not into `output_config` (pi's flag). */
+  supportsMidConvoEffort?: boolean
   supportsMidConvoSystemMessages?: boolean
   supportsStrictTools?: boolean
   allowEmptySignature?: boolean
diff --git a/packages/ai-models/tests/catalog.test.ts b/packages/ai-models/tests/catalog.test.ts
index 70a26c1744..e75ddddf68 100644
--- a/packages/ai-models/tests/catalog.test.ts
+++ b/packages/ai-models/tests/catalog.test.ts
@@ -237,6 +237,48 @@ describe('modelReasoning', () => {
     expect(config).toEqual({
       ...(record.reasoningMap ? { map: record.reasoningMap } : {}),
       budget: record.reasoningBudget === true,
+      adaptive: false,
     })
   })
+
+  /** The thinking shape fields of a catalog record's config. */
+  const shape = (provider: string, id: string) => {
+    const record = getModel(provider, id)
+    if (!record) throw new Error(`Expected the record ${provider}/${id}`)
+    const config = modelReasoning(record)
+    if (!config) throw new Error(`Expected ${provider}/${id} to reason`)
+    return {
+      adaptive: config.adaptive,
+      midConversationEffort: config.midConversationEffort,
+    }
+  }
+
+  it('sets adaptive from compat.forceAdaptiveThinking on the Anthropic wire', () => {
+    // Claude 4.6 and later with a dot id: adaptive.
+    expect(shape('vercel-ai-gateway', 'anthropic/claude-opus-4.7')).toEqual({
+      adaptive: true,
+      midConversationEffort: undefined,
+    })
+    // Older Claude: budget.
+    expect(shape('openrouter', 'anthropic/claude-sonnet-4.5').adaptive).toBe(
+      false,
+    )
+    // Another model on the Anthropic wire: budget.
+    expect(shape('vercel-ai-gateway', 'openai/gpt-5').adaptive).toBe(false)
+    // Another wire: no thinking shape.
+    expect(shape('openai', 'gpt-5').adaptive).toBeUndefined()
+  })
+
+  it('sets midConversationEffort from compat.supportsMidConvoEffort', () => {
+    expect(shape('anthropic', 'claude-opus-5-5')).toEqual({
+      adaptive: true,
+      midConversationEffort: true,
+    })
+    expect(
+      shape('openrouter', 'anthropic/claude-opus-5.5').midConversationEffort,
+    ).toBe(true)
+    expect(
+      shape('anthropic', 'claude-opus-4-8').midConversationEffort,
+    ).toBeUndefined()
+  })
 })
diff --git a/packages/ai-models/tests/rules.test.ts b/packages/ai-models/tests/rules.test.ts
index a5d22f9edb..adb1a8ec45 100644
--- a/packages/ai-models/tests/rules.test.ts
+++ b/packages/ai-models/tests/rules.test.ts
@@ -75,18 +75,26 @@ describe('modelHints', () => {
     ).toEqual({ requiresReasoningContentOnAssistantMessages: true })
   })
 
-  it('reads temperature support and adaptive-only Claude thinking', () => {
+  it('reads temperature support', () => {
     expect(
-      modelHints(
-        {
-          id: 'claude',
-          temperature: false,
-          reasoning_options: [{ type: 'effort', values: ['low', 'high'] }],
-        },
-        messages,
-        false,
-      ),
-    ).toEqual({ supportsTemperature: false, forceAdaptiveThinking: true })
+      modelHints({ id: 'm', temperature: false }, messages, false),
+    ).toEqual({ supportsTemperature: false })
+  })
+
+  it('gives adaptive thinking to Claude 4.6 and later only (pi), with dash or dot ids', () => {
+    const effort = [{ type: 'effort', values: ['low', 'high'] }]
+    const adaptive = (id: string) =>
+      modelHints({ id, reasoning_options: effort }, messages, false)
+        .forceAdaptiveThinking === true
+    expect(adaptive('claude-opus-4-7')).toBe(true)
+    expect(adaptive('anthropic/claude-opus-4.7')).toBe(true)
+    expect(adaptive('anthropic/claude-sonnet-4.6')).toBe(true)
+    expect(adaptive('claude-fable-5-1')).toBe(true)
+    expect(adaptive('claude-opus-4-5')).toBe(false)
+    expect(adaptive('anthropic/claude-sonnet-4.5')).toBe(false)
+    expect(adaptive('claude-sonnet-4-20250514')).toBe(false)
+    // models.dev lists `effort` for it, but a gateway gives it budget thinking.
+    expect(adaptive('openai/gpt-5')).toBe(false)
   })
 
   it('follows the effort option for reasoning_effort when the row asks for it', () => {
diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index 5fda2a0f2b..780fad4803 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -2052,6 +2052,8 @@ class TextEngine<
       if (responseId !== undefined) metadata.responseId = responseId
       if (incoming?.responseItems !== undefined)
         metadata.responseItems = incoming.responseItems
+      if (incoming?.reasoningEffort !== undefined)
+        metadata.reasoningEffort = incoming.reasoningEffort
     }
     if (chunk.type === EventType.RUN_ERROR) {
       metadata.stopReason ??= 'error'
diff --git a/packages/ai/src/reasoning.ts b/packages/ai/src/reasoning.ts
index 0db74031e5..9fac401cce 100644
--- a/packages/ai/src/reasoning.ts
+++ b/packages/ai/src/reasoning.ts
@@ -79,10 +79,23 @@ export interface ReasoningRequest {
 
 /**
  * A model's reasoning data at runtime. `false`: the model does not reason.
- * Otherwise its level map (none means every level up to `high` passes as its
- * own name) and whether it takes a token budget.
+ * Otherwise:
+ * - `map`: the level map (none means every level up to `high` passes as its
+ *   own name).
+ * - `budget`: the model takes a token budget.
+ * - `adaptive` (Anthropic Messages): `true` sends adaptive thinking, `false`
+ *   sends budget thinking. Absent: the adapter decides from the model id.
+ * - `midConversationEffort` (Anthropic Messages): the level goes into the
+ *   messages, so a level change keeps the cached prefix.
  */
-export type ModelReasoning = false | { map?: ReasoningMap; budget: boolean }
+export type ModelReasoning =
+  | false
+  | {
+      map?: ReasoningMap
+      budget: boolean
+      adaptive?: boolean
+      midConversationEffort?: boolean
+    }
 
 /**
  * The reasoning capability of an adapter whose config can carry `reasoning`
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index 9860021892..40147bc509 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -696,6 +696,12 @@ export interface TanStackMessageMetadata {
    * message item's `id` and `phase` (`commentary` or `final_answer`).
    */
   responseItems?: Array<{ id: string; phase?: string }>
+  /**
+   * The provider effort of this assistant message's model call. The
+   * Anthropic adapter keeps it for a model with mid-conversation effort and
+   * sends it again before this message on the next turn.
+   */
+  reasoningEffort?: string
   /** Parent chat run that produced this assistant message. */
   runId?: string
   /**
@@ -743,6 +749,8 @@ export interface TanStackRunMetadata {
   responseId?: string
   /** The answer items of this model call. See `TanStackMessageMetadata.responseItems`. */
   responseItems?: TanStackMessageMetadata['responseItems']
+  /** The effort of this model call. See `TanStackMessageMetadata.reasoningEffort`. */
+  reasoningEffort?: string
   finishReason?: 'stop' | 'length' | 'content_filter' | 'tool_calls' | null
   /** TokenUsage fields that have no AG-UI `usage[]` equivalent. */
   usage?: TokenUsageLeftover

From 57ea69fed347c8b461311fc56a00d08e6e0a1636 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 17:57:38 +0200
Subject: [PATCH 265/286] docs, e2e: the Anthropic thinking shape from the
 record

- The config reasoning wire route sends four record configs: adaptive
  (Vercel anthropic/claude-sonnet-4.6), budget (Vercel openai/gpt-5),
  mid-conversation effort (OpenRouter anthropic/claude-opus-5.5), and
  reasoning: false. The spec checks the thinking fields, the effort
  message, and the two betas in the anthropic-beta header.
- Docs: adaptive and midConversationEffort in the reasoning config, the
  thinking shape from modelReasoning(record), a section for a level
  change during a conversation, and the object form of
  midConversationChannels.
- Changeset for @tanstack/ai, @tanstack/ai-anthropic, @tanstack/ai-models.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/anthropic-thinking-shape.md        | 13 +++
 docs/adapters/anthropic.md                    | 35 ++++++++
 docs/chat/reasoning.md                        |  8 +-
 docs/models/catalog.md                        |  5 ++
 .../api.adapter-config-reasoning-wire.ts      | 84 +++++++++++++------
 .../adapter-config-reasoning-wire.spec.ts     | 55 +++++++++---
 6 files changed, 161 insertions(+), 39 deletions(-)
 create mode 100644 .changeset/anthropic-thinking-shape.md

diff --git a/.changeset/anthropic-thinking-shape.md b/.changeset/anthropic-thinking-shape.md
new file mode 100644
index 0000000000..6f661322a9
--- /dev/null
+++ b/.changeset/anthropic-thinking-shape.md
@@ -0,0 +1,13 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-anthropic': minor
+'@tanstack/ai-models': minor
+---
+
+Send the Anthropic thinking shape that the model record gives.
+
+- `ModelReasoning.adaptive`: `true` sends adaptive thinking with the effort, `false` sends budget thinking. Without it, the adapter picks from the model id, as before. Adaptive thinking without a level map now sends pi's default effort (`minimal` and `low` give `low`, `medium` gives `medium`, the rest give `high`).
+- `ModelReasoning.midConversationEffort`: the level goes into the messages as an effort `system` message, with `block_binding`, a fixed `output_config.effort: 'high'`, and the `mid-conversation-output-config-2026-07-01` and `thinking-binding-controls-2026-08-01` betas. Each answer keeps its level in `metadata.tanstack.reasoningEffort`, so a level change keeps the cached start.
+- `midConversationChannels` takes `{ tools?: boolean; systemPrompts?: boolean }` to turn on one channel only.
+
+`modelReasoning(record)` sets `adaptive` from `compat.forceAdaptiveThinking` and `midConversationEffort` from the new `compat.supportsMidConvoEffort` for `anthropic-messages` records. The catalog flags now equal pi's: Claude 4.6 and later think adaptively on every provider (also with dot ids such as `anthropic/claude-opus-4.7`), and the other Vercel AI Gateway models think with a budget.
diff --git a/docs/adapters/anthropic.md b/docs/adapters/anthropic.md
index ae4ddc23f0..47d4a33ba9 100644
--- a/docs/adapters/anthropic.md
+++ b/docs/adapters/anthropic.md
@@ -310,6 +310,35 @@ What the adapter sends for each kind of model:
 
 The thinking text streams back as thinking parts. Pass `summary: false` to keep it hidden: `reasoning: { level: "high", summary: false }`. See [Reasoning](../chat/reasoning) for the levels and how a level the model does not have moves to the nearest one.
 
+#### Change the level during a conversation
+
+A new level changes the start of the request, so Claude reads nothing from the cache. On `claude-fable-5-1`, `claude-opus-5`, and `claude-opus-5-5`, the level can go into the messages instead. Then a new level keeps the cached start.
+
+Set `midConversationEffort: true` in the `reasoning` config. `modelReasoning(record)` sets it for these models in the [model catalog](../models/catalog), also for their OpenRouter ids:
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+import { getModel, modelReasoning } from "@tanstack/ai-models";
+
+const record = getModel("anthropic", "claude-opus-5-5");
+if (record) {
+  const stream = chat({
+    adapter: anthropicText(record.id, { reasoning: modelReasoning(record) }),
+    messages: [{ role: "user", content: "Plan a database migration." }],
+    reasoning: "low",
+  });
+}
+```
+
+What the adapter sends with `midConversationEffort`:
+
+- `thinking` with `type: "adaptive"` and `block_binding`, and `output_config.effort: "high"`, on every request.
+- At the end of the messages, a `system` message with no content and `output_config.effort` set to the level of this call.
+- The same message before each earlier answer of this adapter, with the level of that answer. The answer keeps it in `metadata.tanstack.reasoningEffort`.
+- The `anthropic-beta` header with `mid-conversation-output-config-2026-07-01` and `thinking-binding-controls-2026-08-01`.
+- No `temperature`.
+
 ### Prompt Caching
 
 `chat()` caches Claude prompts by default. It adds `cache_control` markers to the system prompt, the last tool, and the last user message. To send no markers, pass `promptCache: 'none'`. For the retention, the cache key, and the cost, see [Prompt Caching](../advanced/prompt-caching).
@@ -363,6 +392,7 @@ The channels are on by default with Anthropic's own API. With a custom `baseURL`
 
 - `false`: send the full lists on every call.
 - `true`: use the channels with a custom `baseURL`, `fetch`, or `ANTHROPIC_BASE_URL`. Set it only when that endpoint sends the request and the `anthropic-beta` header to Anthropic as they are.
+- `{ systemPrompts: true }` or `{ tools: true }`: use only that channel, for an endpoint that passes only one. With `{ systemPrompts: true }`, an added prompt goes into a `system` message, and an added tool goes out in the full `tools` list.
 
 ```typescript
 import { anthropicText } from "@tanstack/ai-anthropic";
@@ -375,6 +405,11 @@ export const throughProxy = anthropicText("claude-opus-5-5", {
   baseURL: "https://llm-proxy.example.com",
   midConversationChannels: true,
 });
+
+export const promptsOnly = anthropicText("claude-opus-5-5", {
+  baseURL: "https://llm-gateway.example.com",
+  midConversationChannels: { systemPrompts: true },
+});
 ```
 
 See [Mid-Conversation Changes](../advanced/mid-conversation-changes) for how the library finds the changes.
diff --git a/docs/chat/reasoning.md b/docs/chat/reasoning.md
index 8739431742..e6fafd1dd3 100644
--- a/docs/chat/reasoning.md
+++ b/docs/chat/reasoning.md
@@ -103,7 +103,11 @@ const adapter = createAnthropicChat(
   process.env.AI_GATEWAY_API_KEY ?? "",
   {
     baseURL: "https://ai-gateway.vercel.sh",
-    reasoning: { map: { minimal: null, xhigh: null, max: "max" }, budget: true },
+    reasoning: {
+      map: { minimal: null, xhigh: null, max: "max" },
+      budget: true,
+      adaptive: true,
+    },
   },
 );
 
@@ -119,6 +123,8 @@ The `reasoning` config has the same shape on every adapter:
 - `false`: the model does not reason. No reasoning field goes out, and the types take no level.
 - `map`: the provider value for each level. `null` means that the model does not have the level. A level with no entry passes as its own name, except `xhigh` and `max`.
 - `budget`: `true` when the model thinks with a token budget.
+- `adaptive` (Anthropic): `true` sends adaptive thinking with the effort, and `false` sends thinking with a token budget. Without it, the adapter picks from the model id.
+- `midConversationEffort` (Anthropic): the level goes into the messages, so a new level keeps the cached start. See [Change the level during a conversation](../adapters/anthropic#change-the-level-during-a-conversation).
 
 With `reasoning` in the config, the types take every level. The adapter moves a level that the model does not have to the nearest one, as in [A level from the user](#a-level-from-the-user). The config wins over the adapter's own data, also for a model in its list.
 
diff --git a/docs/models/catalog.md b/docs/models/catalog.md
index d29359afff..df6ec972c1 100644
--- a/docs/models/catalog.md
+++ b/docs/models/catalog.md
@@ -80,6 +80,11 @@ if (record) {
 }
 ```
 
+For an `anthropic-messages` record, `modelReasoning(record)` also gives the thinking shape:
+
+- `adaptive`: from `compat.forceAdaptiveThinking`. It is `true` for Claude 4.6 and later, Kimi For Coding, and most Fireworks models. The other models think with a token budget.
+- `midConversationEffort`: from `compat.supportsMidConvoEffort`. See [Change the level during a conversation](../adapters/anthropic#change-the-level-during-a-conversation).
+
 Pick the adapter from the record's `api`:
 
 | `api` | Adapter |
diff --git a/testing/e2e/src/routes/api.adapter-config-reasoning-wire.ts b/testing/e2e/src/routes/api.adapter-config-reasoning-wire.ts
index 3541f55842..39cdce9339 100644
--- a/testing/e2e/src/routes/api.adapter-config-reasoning-wire.ts
+++ b/testing/e2e/src/routes/api.adapter-config-reasoning-wire.ts
@@ -8,18 +8,49 @@ const DUMMY_KEY = 'sk-ant-e2e-test-dummy-key'
 /** A gateway id that the Anthropic adapter does not list. */
 const GATEWAY_MODEL = 'anthropic/claude-sonnet-4.6'
 
-/** The reasoning data of its catalog record (budget thinking). */
-const RECORD_REASONING: ModelReasoning = {
-  map: { minimal: null, xhigh: null, max: 'max' },
-  budget: true,
-}
+/**
+ * Model ids and the reasoning data of their catalog records
+ * (`modelReasoning(record)` of `@tanstack/ai-models`).
+ */
+const CASES: Array<{ model: string; reasoning: ModelReasoning }> = [
+  // Vercel AI Gateway: Claude 4.6 thinks adaptively.
+  {
+    model: GATEWAY_MODEL,
+    reasoning: {
+      map: { off: 'none', minimal: null, xhigh: null, max: 'max' },
+      budget: true,
+      adaptive: true,
+    },
+  },
+  // Vercel AI Gateway: a model of another vendor thinks with a budget.
+  {
+    model: 'openai/gpt-5',
+    reasoning: {
+      map: { off: null, xhigh: null, max: null },
+      budget: false,
+      adaptive: false,
+    },
+  },
+  // OpenRouter: mid-conversation effort.
+  {
+    model: 'anthropic/claude-opus-5.5',
+    reasoning: {
+      map: { off: null, minimal: null, xhigh: 'xhigh', max: 'max' },
+      budget: false,
+      adaptive: true,
+      midConversationEffort: true,
+    },
+  },
+  // `reasoning: false`: no thinking field.
+  { model: GATEWAY_MODEL, reasoning: false },
+]
 
 /**
  * Wire-format verification for the `reasoning` config of an adapter.
  *
- * The route runs `chat({ reasoning: 'high' })` two times on a model id that
- * the Anthropic adapter does not list: once with the record's reasoning data
- * in the config, once with `reasoning: false`. A custom `fetch` records each
+ * The route runs `chat({ reasoning: 'high' })` once for each of `CASES`:
+ * model ids that the Anthropic adapter does not list, with the reasoning
+ * data of their records in the config. A custom `fetch` records each
  * Messages request and answers with a synthetic Claude stream, the same
  * approach as `api.anthropic-sonnet-5-5-wire.ts`.
  */
@@ -77,6 +108,7 @@ export const Route = createFileRoute('/api/adapter-config-reasoning-wire')({
     handlers: {
       POST: async () => {
         const capturedRequests: Array<Record<string, unknown> | null> = []
+        const capturedBetas: Array<string | null> = []
 
         /** Records the outgoing request and answers with the synthetic stream. */
         const capturingFetch: typeof fetch = async (input, init) => {
@@ -86,6 +118,7 @@ export const Route = createFileRoute('/api/adapter-config-reasoning-wire')({
           capturedRequests.push(
             rawBody ? (JSON.parse(rawBody) as Record<string, unknown>) : null,
           )
+          capturedBetas.push(req.headers.get('anthropic-beta'))
           return new Response(makeSyntheticAnthropicStream(), {
             status: 200,
             headers: {
@@ -96,34 +129,31 @@ export const Route = createFileRoute('/api/adapter-config-reasoning-wire')({
         }
 
         try {
-          for await (const _ of chat({
-            adapter: createAnthropicChat(GATEWAY_MODEL, DUMMY_KEY, {
-              fetch: capturingFetch,
-              reasoning: RECORD_REASONING,
-            }),
-            messages: [{ role: 'user', content: '[config-reasoning] plan it' }],
-            reasoning: 'high',
-          })) {
-            // Drain the stream.
-          }
-          for await (const _ of chat({
-            adapter: createAnthropicChat(GATEWAY_MODEL, DUMMY_KEY, {
-              fetch: capturingFetch,
-              reasoning: false,
-            }),
-            messages: [{ role: 'user', content: '[config-reasoning] plan it' }],
-          })) {
-            // Drain the stream.
+          for (const { model, reasoning } of CASES) {
+            for await (const _ of chat({
+              adapter: createAnthropicChat(model, DUMMY_KEY, {
+                fetch: capturingFetch,
+                reasoning,
+              }),
+              messages: [
+                { role: 'user', content: '[config-reasoning] plan it' },
+              ],
+              reasoning: 'high',
+              promptCache: 'none',
+            })) {
+              // Drain the stream.
+            }
           }
         } catch (error) {
           return Response.json({
             ok: false,
             error: error instanceof Error ? error.message : String(error),
             capturedRequests,
+            capturedBetas,
           })
         }
 
-        return Response.json({ ok: true, capturedRequests })
+        return Response.json({ ok: true, capturedRequests, capturedBetas })
       },
     },
   },
diff --git a/testing/e2e/tests/adapter-config-reasoning-wire.spec.ts b/testing/e2e/tests/adapter-config-reasoning-wire.spec.ts
index 9285fd4c62..6e2b663983 100644
--- a/testing/e2e/tests/adapter-config-reasoning-wire.spec.ts
+++ b/testing/e2e/tests/adapter-config-reasoning-wire.spec.ts
@@ -3,19 +3,24 @@ import { test, expect } from './fixtures'
 /**
  * Wire-format verification for the `reasoning` config of an adapter.
  *
- * `/api/adapter-config-reasoning-wire` runs `chat()` on
- * `anthropic/claude-sonnet-4.6`, a gateway id that the Anthropic adapter does
- * not list. With the record's reasoning data in the config, the request
- * carries a thinking budget. With `reasoning: false`, it carries none.
+ * `/api/adapter-config-reasoning-wire` runs `chat({ reasoning: 'high' })` on
+ * model ids that the Anthropic adapter does not list, with the reasoning
+ * data of their catalog records in the config:
+ * - `anthropic/claude-sonnet-4.6` (`adaptive: true`): adaptive thinking.
+ * - `openai/gpt-5` (`adaptive: false`): budget thinking.
+ * - `anthropic/claude-opus-5.5` (`midConversationEffort: true`): the level
+ *   goes into the messages.
+ * - `reasoning: false`: no thinking field.
  */
 type WireResponse = {
   ok: boolean
   error?: string
   capturedRequests: Array<Record<string, unknown> | null>
+  capturedBetas: Array<string | null>
 }
 
 test.describe('adapter reasoning config wire format', () => {
-  test('a model id outside the adapter list gets thinking from the config', async ({
+  test('a model id outside the adapter list gets its thinking shape from the config', async ({
     request,
   }) => {
     const res = await request.post('/api/adapter-config-reasoning-wire')
@@ -24,14 +29,42 @@ test.describe('adapter reasoning config wire format', () => {
     expect(payload.error).toBeUndefined()
     expect(payload.ok).toBe(true)
 
-    expect(payload.capturedRequests).toHaveLength(2)
-    const [withRecord, withFalse] = payload.capturedRequests
-    expect(withRecord?.['model']).toBe('anthropic/claude-sonnet-4.6')
-    expect(withRecord?.['thinking']).toEqual({
+    expect(payload.capturedRequests).toHaveLength(4)
+    const [adaptive, budget, managed, off] = payload.capturedRequests
+
+    expect(adaptive?.['model']).toBe('anthropic/claude-sonnet-4.6')
+    expect(adaptive?.['thinking']).toEqual({
+      type: 'adaptive',
+      display: 'summarized',
+    })
+    expect(adaptive?.['output_config']).toEqual({ effort: 'high' })
+
+    expect(budget?.['model']).toBe('openai/gpt-5')
+    expect(budget?.['thinking']).toEqual({
       type: 'enabled',
       budget_tokens: 16384,
     })
-    expect(withFalse).not.toHaveProperty('thinking')
-    expect(withFalse).not.toHaveProperty('output_config')
+    expect(budget).not.toHaveProperty('output_config')
+
+    expect(managed?.['model']).toBe('anthropic/claude-opus-5.5')
+    expect(managed?.['thinking']).toEqual({
+      type: 'adaptive',
+      display: 'summarized',
+      block_binding: { prefix_mismatch_behavior: 'drop_block' },
+    })
+    expect(managed?.['output_config']).toEqual({ effort: 'high' })
+    expect(managed?.['messages']).toEqual([
+      { role: 'user', content: '[config-reasoning] plan it' },
+      { role: 'system', content: [], output_config: { effort: 'high' } },
+    ])
+    expect(payload.capturedBetas[2]?.split(',')).toEqual(
+      expect.arrayContaining([
+        'mid-conversation-output-config-2026-07-01',
+        'thinking-binding-controls-2026-08-01',
+      ]),
+    )
+
+    expect(off).not.toHaveProperty('thinking')
+    expect(off).not.toHaveProperty('output_config')
   })
 })

From bffca337027322b6be1bb02a9756b193ad99e8ca Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 18:07:43 +0200
Subject: [PATCH 266/286] docs(harness): the coding agent hub, snapshots, the
 mcp() plugin, and usage cost

- Coding agent: the plugins/coding import, project instructions (put the
  plugin last), session titles, and the cost, with links to the new pages.
- Snapshots: /undo, /redo, diff(), and their limits.
- MCP: the mcp() plugin, its status, code mode, and the time limit.
- Usage: /usage reads session.usage(), a cost in the session list, a
  context meter, and the limits.
---
 docs/harness/coding-agent.md |  93 +++++++++++++-------
 docs/harness/mcp.md          | 160 +++++++++++++++++++++++++++++------
 docs/harness/snapshots.md    | 122 ++++++++++++++++++++++++++
 docs/harness/usage.md        |  87 ++++++++++++++++++-
 4 files changed, 400 insertions(+), 62 deletions(-)
 create mode 100644 docs/harness/snapshots.md

diff --git a/docs/harness/coding-agent.md b/docs/harness/coding-agent.md
index 63bda3a8d5..03419e6818 100644
--- a/docs/harness/coding-agent.md
+++ b/docs/harness/coding-agent.md
@@ -2,20 +2,24 @@
 title: Build a coding agent
 id: harness-coding-agent
 order: 6
-description: "Turn a harness into a coding agent with file tools, permission modes, a todo list, a model picker, project instructions, and /compact."
+description: "Turn a harness into a coding agent with file tools, permission modes, undo, a todo list, a model picker, project instructions, session titles, a cost count, and /compact."
 keywords:
   - tanstack ai
   - harness
   - coding agent
   - permissions
   - workspace tools
+  - project instructions
+  - undo
 ---
 
-You want your own coding agent in the terminal: it reads and edits files, runs commands after you approve them, and keeps a todo list. The first-party plugins in `@tanstack/ai-harness/plugins` give you those parts. You pick the model and the rules.
+You want your own coding agent in the terminal. It reads and edits files, and runs commands after you approve them. When a turn goes wrong, you undo it. The first-party plugins in `@tanstack/ai-harness/plugins` and `@tanstack/ai-harness/plugins/coding` give you those parts. You pick the model and the rules.
 
 ## 1. Define the agent
 
 ```ts group=harness-coding-agent
+import { homedir } from 'node:os'
+import { join } from 'node:path'
 import { defineHarness } from '@tanstack/ai-harness'
 import {
   compact,
@@ -23,56 +27,96 @@ import {
   modelPicker,
   permissions,
   projectInstructions,
+  title,
   todos,
   usage,
 } from '@tanstack/ai-harness/plugins'
-import { workspaceTools } from '@tanstack/ai-harness/plugins/coding'
+import { snapshots, workspaceTools } from '@tanstack/ai-harness/plugins/coding'
 import { runCli } from '@tanstack/ai-harness-cli'
 import { openaiText } from '@tanstack/ai-openai'
 
 const root = process.cwd()
-const smart = openaiText('gpt-5.6')
-const fast = openaiText('gpt-5.6-luna')
+const smart = openaiText('gpt-6.1-sol')
+const fast = openaiText('gpt-6-luna')
 
 const coder = defineHarness({
   name: 'acme/coder',
   adapter: smart,
   systemPrompts: ['You are a careful coding agent. Read before you edit.'],
   plugins: () => [
-    permissions(),
+    permissions({ root }),
     workspaceTools({ root }),
+    snapshots({ root, dataDir: join(homedir(), '.acme-coder', 'snapshots') }),
     todos(),
     modelPicker({ choices: { smart, fast }, default: 'smart' }),
-    projectInstructions({ root }),
     fileCommands({ dir: `${root}/.claude/commands` }),
     compact({ adapter: fast }),
+    title({ adapter: fast }),
     usage(),
+    // Keep this plugin last. See "Project instructions" below.
+    projectInstructions({ root }),
   ],
 })
 
 process.exitCode = await runCli(coder)
 ```
 
+Both plugin entries run only in Node. The coding tools use the file system and the shell of the machine.
+
 ## 2. Run it
 
-Run the file with `npx tsx coder.ts`. Ask for a change. The agent reads files freely and asks before it writes a file or runs a command. Type `y` to allow a call or `n` to refuse it.
+1. Run `npx tsx coder.ts` in your project.
+2. Ask for a change. The agent reads files freely, and asks before it writes a file or runs a command.
+3. Answer `once` to allow the call, `always` to allow it from now on, or `reject` to refuse it.
+4. If you do not like the result, run `/undo`. The files go back to how they were before the turn.
 
 ## What each plugin adds
 
 | Plugin | Adds |
 |---|---|
-| `permissions()` | Asks before risky tool calls. `/mode` switches between `default`, `plan` (read-only), `acceptEdits` (edits run without asking), and `bypass`. |
-| `workspaceTools({ root })` | `read_file`, `write_file`, `edit_file`, `list_files`, `grep`, and `bash`, in `root`. A path outside `root` is refused, or asks first with `outside: 'ask'`. |
+| `permissions({ root })` | Asks before risky tool calls. `/mode` switches between `default`, `plan` (read-only), `acceptEdits` (edits run without asking), and `bypass`. See [Ask before risky tool calls](./permissions). |
+| `workspaceTools({ root })` | Tools that read, search, and change the files in `root`, run commands, and read web pages. A path outside `root` is refused, or asks first with `outside: 'ask'`. See [Give your agent coding tools](./coding-tools). |
+| `snapshots({ root, dataDir })` | `/undo` puts the files back as they were before the last turn, and `/redo` brings them back. It needs `git`. See [Undo a turn](./snapshots). |
 | `todos()` | A `todo_write` tool the model uses for multi-step work, and `/todos`. |
 | `modelPicker({ choices })` | `/model <name>` switches the model at the next turn. |
-| `projectInstructions({ root })` | Adds `AGENTS.md` and `CLAUDE.md` to the system prompt. |
 | `fileCommands({ dir })` | Each `.md` file becomes a slash command. `$ARGUMENTS` is replaced by what you type after it. |
 | `compact({ adapter })` | `/compact` replaces a long conversation with a summary. |
-| `usage()` | `/usage` shows the tokens of the session: the lead turn and every agent. Its state also has `contextTokens`, the prompt size of the last lead call, for a context meter. |
-| `goal({ judge })` | `/goal <text>` keeps the agent working until a judge model says that the goal is met. See [Work until a goal is met](./goal). |
+| `title({ adapter })` | Names the session from its first message. |
+| `usage()` | `/usage` shows the tokens and the cost of the session, with a line for each model. See [Track usage and cost](./usage). |
+| `projectInstructions({ root })` | Adds `AGENTS.md`, `CLAUDE.md`, and facts about the environment to the system prompt. |
 
 To compact on its own before the context limit, see [Compact a harness session](./compaction).
 
+## Project instructions
+
+Your repository has an `AGENTS.md` or a `CLAUDE.md` with its rules. `projectInstructions({ root })` gives them to the model:
+
+- It reads `AGENTS.md` and `CLAUDE.md` in each folder from the repository root (the folder with `.git`) down to `root`. Set other file names with `files`.
+- `global` adds files that come first, for example `['~/.config/AGENTS.md']`.
+- When `read_file` reads a file in a subfolder, the model also gets the instruction files of the folders on the way, once each.
+- An environment block gives the date, the platform, the working folder, and the git repository and branch. `env: false` turns it off.
+- When you change an instruction file, the next turn sends the new text as a note.
+
+Put `projectInstructions()` last in the plugin list. Then a changed file goes into the conversation as a [mid-conversation change](../advanced/mid-conversation-changes), and the prompt cache stays. When the prompt of another plugin comes after it, a change builds the system prompt again, and the prompt cache starts again.
+
+## Session titles and cost
+
+`title({ adapter })` and `usage()` write to the session index, one entry per thread:
+
+- `title` names the session from its first message. The turn does not wait for it.
+- When `usage` knows the cost of the session, it writes the cost. A cost that the provider reports is used as it is.
+- To price the calls of a provider that reports no cost, pass `usage({ model })`. [Track usage and cost](./usage#show-usage-and-price-the-calls) shows how.
+
+A [sidebar of sessions](./sessions) reads the title and the cost from the index. The `usage()` state also has `contextTokens`, the size of the lead model's context at its latest call, for a context meter.
+
+## Add more
+
+- `agents({ adapter })`: named agents with their own prompt, tools, and model. `/agent plan` switches to a read-only agent. See [Switch between agent profiles](./agents).
+- `question()`: a `question` tool. The model asks the user to pick an option, and waits for the answer.
+- `goal({ judge })`: `/goal <text>` keeps the agent working until a judge model says that the goal is met. See [Work until a goal is met](./goal).
+- `mcp({ servers })` from `@tanstack/ai-mcp/harness`: tools from MCP servers. See [Use MCP servers](./mcp).
+- `formatter({ root })`: formats each file after a write. See [Format each file after a write](./coding-tools-backends#format-each-file-after-a-write).
+
 ## Add your own rules
 
 Tool plugins add permission rules to the `PermissionRules` extension point. Add your own for any tool:
@@ -89,25 +133,9 @@ export const noDeploys = definePlugin({
 })
 ```
 
-A trailing `*` matches every tool that starts with the text. The last matching rule wins.
-
-The workspace tools run on your machine with your permissions. Run code you do not trust in a sandbox.
-
-## Ask before the agent goes outside the workspace
-
-Now and then the agent needs a file from another project, but you do not want to open the whole disk. Pass `outside: 'ask'`:
-
-```ts group=harness-coding-agent
-export const askOutside = workspaceTools({
-  root: process.cwd(),
-  outside: 'ask',
-})
-```
+A trailing `*` matches every tool that starts with the text. The last matching rule wins. [Ask before risky tool calls](./permissions) explains the rules, the modes, and the saved answers.
 
-- A path outside `root` asks the user first. A yes allows that folder, and the folders in it, until the session ends.
-- `list_files` and `grep` take a `path`, so the agent can search an allowed folder.
-- `/mode bypass` allows every path without a question.
-- Without the option, a path outside `root` is refused.
+The workspace tools run on your machine with your permissions. For code that you do not trust, [run the tools in a sandbox](./coding-tools-backends#run-the-tools-in-a-sandbox).
 
 ## Hand work to Claude Code or Codex
 
@@ -116,5 +144,8 @@ Your agent can also give tasks to coding agents you already use. [Delegate to co
 ## What you have now
 
 - A terminal coding agent with file tools, approvals, modes, a todo list, and a model picker.
+- `/undo` and `/redo` for the file changes of a turn.
+- The rules of your repository in every turn. A change to them keeps the prompt cache.
+- A title and a cost for each session.
 
 Next: connect the agent to GitHub and other services with [auth and connectors](./auth).
diff --git a/docs/harness/mcp.md b/docs/harness/mcp.md
index a9fe622a20..f2533d69ad 100644
--- a/docs/harness/mcp.md
+++ b/docs/harness/mcp.md
@@ -2,22 +2,24 @@
 title: Use MCP servers
 id: harness-mcp
 order: 8
-description: "Connect a harness to Notion, Linear, or another MCP server that signs in with OAuth. The user signs in once in the browser, and the tools appear after sign-in."
+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
+  - code mode
   - notion
   - linear
 ---
 
-Your agent needs to read the user's Linear issues and Notion pages. Both services run MCP servers that sign in with OAuth, so you do not register an app or copy an API key. `mcpConnector` adds `/connect linear`, keeps the token in your credential store, and gives the model the server's tools after sign-in.
+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 connectors
+## 1. Add the servers
 
 <!-- ::start:tabs variant="package-manager" mode="install" -->
 
@@ -34,34 +36,61 @@ vanilla: @tanstack/ai-harness @tanstack/ai-mcp
 
 ```ts group=harness-mcp
 import { defineHarness } from '@tanstack/ai-harness'
-import { mcpConnector } from '@tanstack/ai-mcp/connector'
+import { mcp } from '@tanstack/ai-mcp/harness'
 import { openaiText } from '@tanstack/ai-openai'
 
-const notion = mcpConnector({
-  id: 'notion',
-  label: 'Notion',
-  url: 'https://mcp.notion.com/mcp',
-})
-const linear = mcpConnector({
-  id: 'linear',
-  label: 'Linear',
-  url: 'https://mcp.linear.app/mcp',
-})
-
 export const assistant = defineHarness({
   name: 'acme/assistant',
-  adapter: openaiText('gpt-5.6'),
-  plugins: () => [notion, linear],
+  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 },
+      },
+    }),
+  ],
 })
 ```
 
-Any MCP server that speaks Streamable HTTP and OAuth works the same way. Give it an `id`, a `label`, and its `url`.
+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
 
-## 2. Sign in
+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](./custom-ui), read the same list from `state.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.`
+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`.
@@ -76,13 +105,89 @@ The sign-in follows the MCP authorization spec:
 
 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.
+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.
+
+To make the `docs` tools ask first, add a permission rule for them, next to `permissions()`:
+
+```ts group=harness-mcp
+import { definePlugin } from '@tanstack/ai-harness'
+import { PermissionRules, permissions } from '@tanstack/ai-harness/plugins'
+
+const askForDocs = definePlugin({
+  name: 'acme/ask-for-docs',
+  setup: () => ({
+    contribute: [PermissionRules.item({ tool: 'docs_*', decision: 'ask' })],
+  }),
+})
+
+export const careful = defineHarness({
+  name: 'acme/careful',
+  adapter: openaiText('gpt-6.1-sol'),
+  plugins: () => [
+    permissions(),
+    mcp({ servers: { docs: { type: 'http', url: 'https://mcp.example.com/mcp' } } }),
+    askForDocs,
+  ],
+})
+```
+
+[Ask before risky tool calls](./permissions) explains the rules and the modes.
 
-## 3. Choose which tools ask first
+## Move the tools into code mode
 
-The connector names each tool `<id>_<tool>`, for example `linear_list_issues`. A tool that the server does not mark read-only asks for approval before it runs. To change that rule, pass `needsApproval`:
+A server with many tools fills each request with their schemas. Set `codeMode: true` on the server, and add the [`codeMode()` plugin](./code-mode). The model then calls the tools from one TypeScript program:
 
 ```ts group=harness-mcp
+import { codeMode } from '@tanstack/ai-code-mode/harness'
+import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs'
+
+export const coded = defineHarness({
+  name: 'acme/coded',
+  adapter: openaiText('gpt-6.1-sol'),
+  plugins: () => [
+    mcp({
+      servers: {
+        docs: { type: 'http', url: 'https://mcp.example.com/mcp', codeMode: true },
+      },
+    }),
+    codeMode({ driver: createQuickJSIsolateDriver() }),
+  ],
+})
+```
+
+- Without the `codeMode()` plugin, `codeMode: true` changes nothing.
+- A call inside the program does not stop for a question. So a marked tool moves only when it is safe to run without one.
+- Safe means: the tool does not need approval, the `PermissionRules` of your plugins allow it in plan mode, and it declares no permission resources.
+- A tool that is not safe stays a normal tool call, with its question. For example, a rule that asks for `docs_*` keeps the `docs` tools out of code mode.
+
+## Set a time limit
+
+`timeoutMs` limits the tool list and each tool call of one server:
+
+```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 does not send its tool list in time gets the status `failed`.
+- `timeoutMs` does not limit the connect step. A server that does not answer while it connects can keep the first turn waiting for longer than `timeoutMs`.
+
+## 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',
@@ -92,8 +197,9 @@ export const linearWithoutWrites = mcpConnector({
 })
 ```
 
-Other options:
+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`.
@@ -103,7 +209,6 @@ Other options:
 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> = []
@@ -121,6 +226,7 @@ export const lateTools = definePlugin({
 
 ## What you have now
 
-- `/connect` and `/disconnect` for Notion, Linear, and other MCP servers.
+- 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.
-- Server tools in the model's tool list, with approval for tools that change data.
+- A question before the tools that change data, and code mode for the tools that are safe.
diff --git a/docs/harness/snapshots.md b/docs/harness/snapshots.md
new file mode 100644
index 0000000000..bc962505ee
--- /dev/null
+++ b/docs/harness/snapshots.md
@@ -0,0 +1,122 @@
+---
+title: Undo a turn
+id: harness-snapshots
+order: 8
+description: "Let the user undo the file changes of the last agent turn with /undo, bring them back with /redo, and show what each model step changed."
+keywords:
+  - tanstack ai
+  - harness
+  - coding agent
+  - snapshots
+  - undo
+  - diff
+---
+
+The agent changed five files, and the result is wrong. You want the files back as they were before that turn, and you do not want a reset in your own git repository. `snapshots()` saves the files of the workspace at each model step, in a git repository of its own. `/undo` puts the files back and removes the turn from the conversation.
+
+## 1. Add the plugin
+
+```ts group=harness-snapshots
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { defineHarness } from '@tanstack/ai-harness'
+import { permissions } from '@tanstack/ai-harness/plugins'
+import { snapshots, workspaceTools } from '@tanstack/ai-harness/plugins/coding'
+import { runCli } from '@tanstack/ai-harness-cli'
+import { openaiText } from '@tanstack/ai-openai'
+
+const root = process.cwd()
+const history = snapshots({
+  root,
+  dataDir: join(homedir(), '.acme-coder', 'snapshots'),
+})
+
+const coder = defineHarness({
+  name: 'acme/coder',
+  adapter: openaiText('gpt-6.1-sol'),
+  plugins: () => [permissions({ root }), workspaceTools({ root }), history],
+})
+
+process.exitCode = await runCli(coder)
+```
+
+- `root` is the workspace folder, an absolute path.
+- `dataDir` is a folder for the snapshot repositories, an absolute path. Put it outside `root`. Each workspace gets its own repository in it.
+- The plugin needs the `git` command. Your project does not need to be a git repository, and the plugin never uses the `.git` folder of your project.
+
+## 2. Undo and redo a turn
+
+1. Run `npx tsx coder.ts`, and ask for a change.
+2. Run `/undo`. The CLI prints the number of files that it put back, for example `Undid the last turn. Files restored: 3.`
+3. Look at your files: they are as they were before the turn. The turn is gone from the conversation too.
+4. To bring back the files and the turn, run `/redo`. The CLI prints `Redid the last turn.`
+
+- `/undo` restores every change in `root` during the turn: the edits of the file tools, and the changes of `bash` commands.
+- The snapshots skip the files that `.gitignore` names, like `node_modules`. `/undo` does not touch them.
+- A new turn clears `/redo`.
+
+In your own UI, call `client.command('undo')`. The result text arrives as a `harness.command.result` event.
+
+## See what a step changed
+
+Each model step that changed files leaves a step: `{ from, to, files }`. `from` and `to` are the ids of two snapshots, and `files` lists the changed paths. `history.diff(from, to)` gives the changed files and a unified diff.
+
+On a [durable host](./durable-sessions), the steps are `tanstack/snapshots:step` records in the session log:
+
+```ts group=harness-snapshots
+import { createHarnessHost } from '@tanstack/ai-harness'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+
+const log = memoryLogStore()
+const host = createHarnessHost({
+  persistence: { stores: { log, runs: memoryPersistence().stores.runs } },
+})
+const session = await host.open(coder, { threadId: 'fix-login' })
+await session.prompt('Fix the login form.')
+
+for (const { record } of await log.read('fix-login')) {
+  if (record.type !== 'tanstack/snapshots:step') continue
+  if (typeof record.from !== 'string' || typeof record.to !== 'string') continue
+  const { files, patch } = await history.diff(record.from, record.to)
+  console.log(files.join(', '))
+  console.log(patch)
+}
+```
+
+- Without `to`, `diff` compares with the files now. `history.diff(record.to)` shows what changed after that step.
+- On a host without a log, the steps are a list in the plugin state, `snapshot().plugins['tanstack/snapshots']`.
+- A step that changed no file is not saved.
+
+## In a sandbox
+
+When the [coding tools run in a sandbox](./coding-tools-backends#run-the-tools-in-a-sandbox), give `snapshots()` the same `backend`:
+
+```ts group=harness-snapshots-sandbox
+import { snapshots } from '@tanstack/ai-harness/plugins/coding'
+import { sandboxWorkspaceBackend } from '@tanstack/ai-sandbox/harness'
+import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
+
+const sandbox = await dockerSandbox({ image: 'node:22' }).create({})
+
+export const sandboxHistory = snapshots({
+  root: '/workspace',
+  dataDir: '/tmp/snapshots',
+  backend: sandboxWorkspaceBackend(sandbox),
+})
+```
+
+Git then runs in the sandbox, and `dataDir` is a path in the sandbox. The sandbox image needs `git`.
+
+## Known limits
+
+- One level of undo. A second `/undo` answers `Nothing to undo.` After a `/redo`, `/undo` works again.
+- `/undo` and `/redo` work only when the session is idle. During a turn, they answer `Wait until the turn ends, then try again.`
+- The undo point is kept in memory. After a restart, or when the session opens again, `/undo` works again after the next turn.
+- If you sent a message while the turn ran, `/undo` removes the conversation from that message on. The files still go back to the start of the turn.
+- Without `git`, the plugin prints `snapshots: git was not found. Snapshots are off.` once, and adds no commands. `diff()` throws. The turns run as usual.
+
+## What you have now
+
+- `/undo` and `/redo` for the file changes of the last turn, also the changes of shell commands.
+- A list of changed files and a unified diff for each model step.
+- Snapshots that never touch the git repository of your project.
diff --git a/docs/harness/usage.md b/docs/harness/usage.md
index 8bfedd4145..0859577d73 100644
--- a/docs/harness/usage.md
+++ b/docs/harness/usage.md
@@ -2,7 +2,7 @@
 title: Track usage and cost
 id: harness-usage
 order: 7
-description: "Read the tokens and the cost of a thread, in total, by model, and by sender. Show a live total, and stop a person who is over budget."
+description: "Read the tokens and the cost of a thread, in total, by model, and by sender. Show a live total, stop a person who is over budget, and add /usage with your own prices."
 keywords:
   - tanstack ai
   - harness
@@ -23,7 +23,7 @@ import { openaiText } from '@tanstack/ai-openai'
 
 export const assistant = defineHarness({
   name: 'acme/assistant',
-  adapter: openaiText('gpt-5.6'),
+  adapter: openaiText('gpt-6.1-sol'),
 })
 
 const host = createHarnessHost({ persistence: memoryPersistence() })
@@ -36,13 +36,13 @@ await session.prompt('Summarize the open tickets.')
 
 const { total, byModel, bySender } = session.usage()
 console.log(total.calls, total.totalTokens, total.cost)
-console.log(byModel['openai/gpt-5.6']?.totalTokens, bySender.ada?.cost)
+console.log(byModel['openai/gpt-6.1-sol']?.totalTokens, bySender.ada?.cost)
 ```
 
 The totals have three groups. `snapshot().usage` has the same data:
 
 - `total`: every model call of the thread.
-- `byModel`: the calls of each model, keyed by `provider/model`, for example `openai/gpt-5.6`.
+- `byModel`: the calls of each model, keyed by `provider/model`, for example `openai/gpt-6.1-sol`.
 - `bySender`: the calls of each person, keyed by the principal id. It has only the calls of a known sender, so its sum can be less than `total`.
 
 Each entry has `calls`, `promptTokens`, `completionTokens`, `totalTokens`, `cachedTokens`, and `cacheWriteTokens`. If a provider reported a cost, the entry also has `cost`. The harness adds the costs that the providers report, in their currency. It uses no price list of its own.
@@ -105,9 +105,88 @@ export async function send(threadId: string, userId: string, text: string) {
 }
 ```
 
+## Show usage and price the calls
+
+Many providers report no cost, so `cost` stays empty. The `usage()` plugin adds a `/usage` command, and can price those calls with your own price list. Install `@tanstack/ai-models` for the prices:
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: @tanstack/ai-models
+vue: @tanstack/ai-models
+solid: @tanstack/ai-models
+svelte: @tanstack/ai-models
+preact: @tanstack/ai-models
+angular: @tanstack/ai-models
+octane: @tanstack/ai-models
+vanilla: @tanstack/ai-models
+
+<!-- ::end:tabs -->
+
+```ts group=harness-usage
+import { usage } from '@tanstack/ai-harness/plugins'
+import { getModel } from '@tanstack/ai-models'
+
+export const priced = defineHarness({
+  name: 'acme/priced',
+  adapter: openaiText('gpt-6.1-sol'),
+  plugins: () => [usage({ model: (id) => getModel('openai', id) })],
+})
+```
+
+`/usage` reads `session.usage()` and shows the total. When the thread used more than one model, it also shows a line for each model:
+
+```text
+3 model calls, 41200 input tokens (30000 cache read, 0 cache write), 2100 output tokens, 43300 total. Cost: $0.0432.
+openai/gpt-6.1-sol: 2 model calls, 40000 input tokens (30000 cache read, 0 cache write), 2000 output tokens, 42000 total.
+openai/gpt-6-luna: 1 model calls, 1200 input tokens, 100 output tokens, 1300 total.
+```
+
+How the plugin finds the cost:
+
+- A call with a cost from its provider keeps that cost, as it is.
+- `model` prices only the calls with no provider cost. It gets the model id without the provider, like `gpt-6.1-sol`. It returns `{ cost }` with prices in USD per 1M tokens, or `undefined`.
+- Without `model`, `/usage` shows `Cost:` only when a provider reported a cost.
+- A call with no price adds a note, for example `(cost unknown for 1 call)`.
+
+`session.usage()` keeps only the costs that the providers report. The prices of `model` show in `/usage` and in the session index.
+
+## Show the cost in a list of sessions
+
+With `stores.sessions`, each [session index](./sessions) entry has a `usage` field:
+
+- The host writes the token counts of `session.usage()` at the end of each turn. `turns` is the number of model calls.
+- The `usage()` plugin writes `usage.cost` whenever it has a cost: the provider costs plus the prices of `model`.
+
+Read them in the browser with `listSessions`:
+
+```ts group=harness-usage-client
+const page = await client.listSessions({ limit: 20 })
+for (const entry of page.entries) {
+  const cost = entry.usage?.cost
+  console.log(entry.title ?? 'New chat', cost === undefined ? '' : `$${cost.toFixed(2)}`)
+}
+```
+
+## Show a context meter
+
+The plugin state, `state.plugins['tanstack/usage']`, has a copy of `session.usage().total` and one more field:
+
+- `contextTokens`: the input tokens of the latest call of the lead model. This is how much of the context window the conversation fills now.
+
+Compare `contextTokens` with the context window of the model, and show the result as a meter in [your own UI](./custom-ui).
+
+## Known limits
+
+- A host with no `usage()` plugin writes no cost to the index entry. The token counts are still there.
+- On a host with a log, the cost in the index entry and the state copy can miss the last call of a run. They get it at the end of the next run.
+- A background agent can end after the turn. Then the index entry counts its tokens at the end of the next turn.
+- For one model, when some calls have a provider cost and others do not, `model` does not price the others.
+- `model` uses the base prices only. Higher prices for a long input, like the `tiers` of `@tanstack/ai-models`, do not apply.
+
 ## What you have now
 
 - The tokens and the cost of a thread, in total, by model, and by sender.
 - Totals that stay after a restart.
 - A live total in your UI, from the `harness.usage` event.
 - A budget check before each prompt.
+- `/usage` with your own prices, a cost for each session in the session index, and a context meter.

From 25bf72f6831babf95369e80c83640d0313b4a8a2 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 18:07:43 +0200
Subject: [PATCH 267/286] test(e2e): the coding agent plugins

One scenario each for /agent and the step limit, the environment block,
/undo, formatter(), the mcp() status and a tool call, and title().
---
 testing/e2e/fixtures/harness/plugins.json  | 125 +++++++++
 testing/e2e/src/routes/api.harness-test.ts | 311 ++++++++++++++++++++-
 testing/e2e/tests/harness-plugins.spec.ts  | 169 +++++++++++
 3 files changed, 604 insertions(+), 1 deletion(-)
 create mode 100644 testing/e2e/fixtures/harness/plugins.json
 create mode 100644 testing/e2e/tests/harness-plugins.spec.ts

diff --git a/testing/e2e/fixtures/harness/plugins.json b/testing/e2e/fixtures/harness/plugins.json
new file mode 100644
index 0000000000..6faec4ddab
--- /dev/null
+++ b/testing/e2e/fixtures/harness/plugins.json
@@ -0,0 +1,125 @@
+{
+  "fixtures": [
+    {
+      "match": {
+        "userMessage": "[harness-agents] first"
+      },
+      "response": {
+        "content": "Built it."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-agents] second",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [{ "name": "lookup", "arguments": "{}" }]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-agents] second",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Stopped at the step limit."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-env] where am i"
+      },
+      "response": {
+        "content": "You are in a new repository."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-undo] change a.txt",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "write_file",
+            "arguments": "{\"path\":\"a.txt\",\"content\":\"two\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-undo] change a.txt",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Changed a.txt."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-format] write b.txt",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "write_file",
+            "arguments": "{\"path\":\"b.txt\",\"content\":\"quiet text\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-format] write b.txt",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Wrote b.txt."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-mcp] echo hello",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "local_echo",
+            "arguments": "{\"text\":\"hello from mcp\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-mcp] echo hello",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "The server said hello from mcp."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-title] plan a trip to Rome",
+        "model": "gpt-5.4-nano"
+      },
+      "response": {
+        "content": "\"Trip to Rome\""
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-title] plan a trip to Rome",
+        "model": "gpt-5.5"
+      },
+      "response": {
+        "content": "Here is a plan for Rome."
+      }
+    }
+  ]
+}
diff --git a/testing/e2e/src/routes/api.harness-test.ts b/testing/e2e/src/routes/api.harness-test.ts
index db0901277d..de89ae7538 100644
--- a/testing/e2e/src/routes/api.harness-test.ts
+++ b/testing/e2e/src/routes/api.harness-test.ts
@@ -1,16 +1,35 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { createFileRoute } from '@tanstack/react-router'
 import { chat, defineAgent, toolDefinition } from '@tanstack/ai'
 import {
   HARNESS_EVENTS,
   createHarnessHost,
   defineHarness,
+  definePlugin,
   harnessText,
   retryTransientErrors,
 } from '@tanstack/ai-harness'
 import { createOpenaiChat } from '@tanstack/ai-openai'
 import Anthropic from '@anthropic-ai/sdk'
 import { createAnthropicChatWithClient } from '@tanstack/ai-anthropic'
-import { permissions } from '@tanstack/ai-harness/plugins'
+import {
+  TitleFailed,
+  agents,
+  permissions,
+  projectInstructions,
+  title,
+} from '@tanstack/ai-harness/plugins'
+import {
+  FormatFailed,
+  formatter,
+  hostBackend,
+  snapshots,
+  workspaceTools,
+} from '@tanstack/ai-harness/plugins/coding'
+import { mcp } from '@tanstack/ai-mcp/harness'
+import { createMCPServer } from '@tanstack/ai-mcp/server'
 import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
 import { z } from 'zod'
 import type { ModelMessage, UIMessage } from '@tanstack/ai'
@@ -466,6 +485,272 @@ async function toolOrder(
   return { log, text: turn.text }
 }
 
+/**
+ * `agents()`: the first turn runs with the default `build` agent. `/agent
+ * brief` switches to an agent with `steps: 1`. Its turn calls `lookup` once,
+ * then the step limit makes the last call without tools. The spec reads the
+ * model calls in aimock's journal.
+ */
+async function agentProfiles(
+  host: HarnessHost,
+  openai: () => ReturnType<typeof createTextAdapter>['adapter'],
+) {
+  const lookup = toolDefinition({
+    name: 'lookup',
+    description: 'Look up a fact',
+    inputSchema: z.object({}),
+  }).server(async () => 'A fact.')
+  const session = await host.open(
+    defineHarness({
+      name: 'e2e/harness-agents',
+      adapter: openai(),
+      tools: [lookup],
+      plugins: () => [
+        agents({
+          adapter: () => openai(),
+          agents: [
+            {
+              name: 'brief',
+              description: 'Answers after one tool step',
+              mode: 'primary',
+              system: 'You are the brief agent.',
+              steps: 1,
+            },
+          ],
+        }),
+      ],
+    }),
+    { threadId: 'e2e-agents' },
+  )
+  const first = (await session.prompt('[harness-agents] first')).text
+  const switched = await session.command('agent', 'brief')
+  const second = (await session.prompt('[harness-agents] second')).text
+  return { first, switched, second }
+}
+
+/**
+ * `projectInstructions()` in a new git repository on the branch `e2e-env`.
+ * Returns the folder and the platform, so the spec can find the environment
+ * block in the system prompt of the model call.
+ */
+async function environmentPrompt(
+  host: HarnessHost,
+  openai: () => ReturnType<typeof createTextAdapter>['adapter'],
+) {
+  const root = await mkdtemp(join(tmpdir(), 'e2e-env-'))
+  try {
+    // The branch line needs a commit.
+    const git = await hostBackend.exec(
+      'git init -q -b e2e-env && git -c user.name=e2e -c user.email=e2e@example.com commit -q --allow-empty -m init',
+      { cwd: root, timeoutMs: 30_000 },
+    )
+    if (git.exitCode !== 0) throw new Error(`git failed: ${git.stderr}`)
+    const session = await host.open(
+      defineHarness({
+        name: 'e2e/harness-env',
+        adapter: openai(),
+        plugins: () => [projectInstructions({ root })],
+      }),
+      { threadId: 'e2e-env' },
+    )
+    const turn = await session.prompt('[harness-env] where am i')
+    return { root, platform: process.platform, text: turn.text }
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+}
+
+/**
+ * `snapshots()`: a turn writes `a.txt` with `write_file`, then `/undo` puts
+ * the file back and removes the turn. The workspace and the snapshot data
+ * are in a new temp folder.
+ */
+async function undoTurn(
+  host: HarnessHost,
+  openai: () => ReturnType<typeof createTextAdapter>['adapter'],
+) {
+  const base = await mkdtemp(join(tmpdir(), 'e2e-undo-'))
+  const root = join(base, 'work')
+  try {
+    await mkdir(root)
+    await writeFile(join(root, 'a.txt'), 'one')
+    const session = await host.open(
+      defineHarness({
+        name: 'e2e/harness-undo',
+        adapter: openai(),
+        plugins: () => [
+          workspaceTools({ root }),
+          snapshots({ root, dataDir: join(base, 'data') }),
+        ],
+      }),
+      { threadId: 'e2e-undo' },
+    )
+    const turn = await session.prompt('[harness-undo] change a.txt')
+    const written = await readFile(join(root, 'a.txt'), 'utf8')
+    const undo = await session.command('undo')
+    return {
+      text: turn.text,
+      written,
+      undo,
+      restored: await readFile(join(root, 'a.txt'), 'utf8'),
+      transcript: await session.transcript(),
+    }
+  } finally {
+    await rm(base, { recursive: true, force: true })
+  }
+}
+
+/**
+ * `formatter()` with one test formatter for `.txt` files and no built-in
+ * formatters. The formatter is a node one-liner that makes the text upper
+ * case. Returns the file after the turn wrote it, and each `FormatFailed`.
+ */
+async function formatAfterWrite(
+  host: HarnessHost,
+  openai: () => ReturnType<typeof createTextAdapter>['adapter'],
+) {
+  const root = await mkdtemp(join(tmpdir(), 'e2e-format-'))
+  try {
+    const failures: Array<string> = []
+    const listener = definePlugin({
+      name: 'e2e/format-failures',
+      setup: (ctx) => {
+        ctx.on(FormatFailed, (failure) => failures.push(failure.message))
+      },
+    })
+    const session = await host.open(
+      defineHarness({
+        name: 'e2e/harness-format',
+        adapter: openai(),
+        plugins: () => [
+          workspaceTools({ root }),
+          formatter({
+            root,
+            builtins: false,
+            formatters: [
+              {
+                name: 'e2e-upper',
+                extensions: ['.txt'],
+                command: (file) =>
+                  `node -e "const fs = require('fs'); const file = process.argv[1]; fs.writeFileSync(file, fs.readFileSync(file, 'utf8').toUpperCase())" ${file}`,
+              },
+            ],
+          }),
+          listener,
+        ],
+      }),
+      { threadId: 'e2e-format' },
+    )
+    const turn = await session.prompt('[harness-format] write b.txt')
+    return {
+      text: turn.text,
+      content: await readFile(join(root, 'b.txt'), 'utf8'),
+      failures,
+    }
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+}
+
+/**
+ * `mcp()` with two servers and no network. `local` is an MCP server in this
+ * process with an `echo` tool. The fetch of `broken` fails. Returns `/mcp`,
+ * the plugin state, and each tool result of the turn.
+ */
+async function mcpServers(
+  host: HarnessHost,
+  openai: () => ReturnType<typeof createTextAdapter>['adapter'],
+) {
+  const echo = toolDefinition({
+    name: 'echo',
+    description: 'Echo text',
+    inputSchema: z.object({ text: z.string() }),
+  }).server(async ({ text }) => text)
+  const server = createMCPServer({
+    name: 'echo',
+    version: '1.0.0',
+    tools: [echo],
+  })
+  const results: Array<unknown> = []
+  const session = await host.open(
+    defineHarness({
+      name: 'e2e/harness-mcp',
+      adapter: openai(),
+      plugins: () => [
+        mcp({
+          servers: {
+            local: {
+              type: 'http',
+              url: 'http://mcp.test/mcp',
+              fetch: async (input, init) =>
+                server.fetch(new Request(input, init)),
+            },
+            broken: {
+              type: 'http',
+              url: 'http://mcp.test/broken',
+              fetch: async () => {
+                throw new TypeError('connection refused')
+              },
+            },
+          },
+        }),
+      ],
+      middleware: [
+        {
+          name: 'e2e/tool-results',
+          onAfterToolCall: (_ctx, info) => {
+            results.push({ tool: info.toolName, result: info.result })
+          },
+        },
+      ],
+    }),
+    { threadId: 'e2e-mcp' },
+  )
+  const turn = await session.prompt('[harness-mcp] echo hello')
+  return {
+    status: await session.command('mcp'),
+    state: session.snapshot().plugins['tanstack/mcp'],
+    results,
+    text: turn.text,
+  }
+}
+
+/**
+ * `title()` names the session from its first turn. The title call runs next
+ * to the turn, with the model `gpt-5.4-nano`, so the fixtures tell the two
+ * calls apart by model. Waits up to 5 seconds for the title in the session
+ * index.
+ */
+async function sessionTitle(
+  host: HarnessHost,
+  openai: () => ReturnType<typeof createTextAdapter>['adapter'],
+  titleModel: ReturnType<typeof createTextAdapter>['adapter'],
+) {
+  const failures: Array<string> = []
+  const listener = definePlugin({
+    name: 'e2e/title-failures',
+    setup: (ctx) => {
+      ctx.on(TitleFailed, (failure) => failures.push(failure.message))
+    },
+  })
+  const session = await host.open(
+    defineHarness({
+      name: 'e2e/harness-title',
+      adapter: openai(),
+      plugins: () => [listener, title({ adapter: titleModel })],
+    }),
+    { threadId: 'e2e-title' },
+  )
+  const turn = await session.prompt('[harness-title] plan a trip to Rome')
+  const deadline = Date.now() + 5_000
+  let entry = await host.sessions.get('e2e-title')
+  while (!entry?.title && failures.length === 0 && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 50))
+    entry = await host.sessions.get('e2e-title')
+  }
+  return { text: turn.text, title: entry?.title, failures }
+}
+
 /**
  * Harness session. The main model and the agent are real OpenAI adapters
  * against aimock.
@@ -935,6 +1220,30 @@ export const Route = createFileRoute('/api/harness-test')({
               ),
             )
           }
+          if (body.scenario === 'plugin-agents') {
+            return Response.json(await agentProfiles(host, openai))
+          }
+          if (body.scenario === 'plugin-env') {
+            return Response.json(await environmentPrompt(host, openai))
+          }
+          if (body.scenario === 'plugin-undo') {
+            return Response.json(await undoTurn(host, openai))
+          }
+          if (body.scenario === 'plugin-format') {
+            return Response.json(await formatAfterWrite(host, openai))
+          }
+          if (body.scenario === 'plugin-mcp') {
+            return Response.json(await mcpServers(host, openai))
+          }
+          if (body.scenario === 'plugin-title') {
+            const titleModel = createTextAdapter(
+              'openai',
+              'gpt-5.4-nano',
+              aimockPort,
+              testId,
+            ).adapter
+            return Response.json(await sessionTitle(host, openai, titleModel))
+          }
           if (body.scenario === 'agent') {
             const result = await session.agents.pricer.run({
               task: '[harness-agent] price vendor a',
diff --git a/testing/e2e/tests/harness-plugins.spec.ts b/testing/e2e/tests/harness-plugins.spec.ts
new file mode 100644
index 0000000000..cc4819b695
--- /dev/null
+++ b/testing/e2e/tests/harness-plugins.spec.ts
@@ -0,0 +1,169 @@
+import { test, expect } from './fixtures'
+import type { APIRequestContext } from '@playwright/test'
+
+/**
+ * First-party harness plugins in a session: `agents()`,
+ * `projectInstructions()`, `snapshots()`, `formatter()`, `mcp()`, and
+ * `title()`. Each test runs one scenario of `/api/harness-test`. 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: {
+    messages?: Array<{ role: string; content: unknown }>
+    tool_choice?: unknown
+  } | null
+}
+
+/** This test's model calls, in order, from aimock's journal. */
+async function modelCalls(
+  request: APIRequestContext,
+  aimockPort: number,
+  testId: string,
+) {
+  const journal = await request.get(
+    `http://127.0.0.1:${aimockPort}/v1/_requests`,
+  )
+  const entries: Array<JournalEntry> = await journal.json()
+  return entries.filter((entry) => entry.headers?.['x-test-id'] === testId)
+}
+
+/** The system prompt text of one model call. */
+const systemOf = (call: JournalEntry | undefined) =>
+  (call?.body?.messages ?? [])
+    .filter((message) => message.role === 'system')
+    .map((message) =>
+      typeof message.content === 'string' ? message.content : '',
+    )
+    .join('\n')
+
+test.describe('harness plugins', () => {
+  test('agents(): /agent switches the profile, and the step limit makes a last call without tools', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'plugin-agents', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    expect(await response.json()).toEqual({
+      first: 'Built it.',
+      switched: 'Agent: brief. It applies at the next turn.',
+      second: 'Stopped at the step limit.',
+    })
+
+    const calls = await modelCalls(request, aimockPort, testId)
+    expect(calls.map((call) => call.body?.tool_choice)).toEqual([
+      undefined,
+      undefined,
+      'none',
+    ])
+    expect(systemOf(calls[0])).toContain('You are the build agent.')
+    expect(systemOf(calls[1])).toContain('You are the brief agent.')
+    expect(systemOf(calls[1])).not.toContain('You are the build agent.')
+    expect(systemOf(calls[1])).not.toContain('step limit')
+    expect(systemOf(calls[2])).toContain('You reached the step limit.')
+  })
+
+  test('projectInstructions(): the environment block reaches the model', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'plugin-env', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    const body = await response.json()
+    expect(body.text).toBe('You are in a new repository.')
+
+    const [call] = await modelCalls(request, aimockPort, testId)
+    const system = systemOf(call)
+    expect(system).toMatch(/Environment:\n- Date: \d{4}-\d{2}-\d{2}\n/)
+    expect(system).toContain(
+      [
+        `- Platform: ${body.platform}`,
+        `- Working folder: ${body.root}`,
+        '- Git repository: yes',
+        '- Git branch: e2e-env',
+      ].join('\n'),
+    )
+  })
+
+  test('snapshots(): /undo restores the file and removes the turn', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'plugin-undo', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    expect(await response.json()).toEqual({
+      text: 'Changed a.txt.',
+      written: 'two',
+      undo: 'Undid the last turn. Files restored: 1.',
+      restored: 'one',
+      transcript: [],
+    })
+  })
+
+  test('formatter(): a test formatter runs after write_file', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'plugin-format', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    expect(await response.json()).toEqual({
+      text: 'Wrote b.txt.',
+      content: 'QUIET TEXT',
+      failures: [],
+    })
+  })
+
+  test('mcp(): each server has a status, and the model calls <server>_<tool>', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'plugin-mcp', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    const error =
+      'Failed to connect to MCP server: Version negotiation probe failed: connection refused'
+    expect(await response.json()).toEqual({
+      status: `local: connected (1 tool)\nbroken: failed: ${error}`,
+      state: {
+        servers: [
+          { name: 'local', status: 'connected', toolCount: 1 },
+          { name: 'broken', status: 'failed', error, toolCount: 0 },
+        ],
+      },
+      results: [{ tool: 'local_echo', result: 'hello from mcp' }],
+      text: 'The server said hello from mcp.',
+    })
+  })
+
+  test('title(): the first turn names the session in the session index', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-test', {
+      data: { scenario: 'plugin-title', testId, aimockPort },
+    })
+    expect(response.ok()).toBe(true)
+    expect(await response.json()).toEqual({
+      text: 'Here is a plan for Rome.',
+      title: 'Trip to Rome',
+      failures: [],
+    })
+  })
+})

From 2128e1613d017eb662b133d3bddcacb32157389c Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 18:34:21 +0200
Subject: [PATCH 268/286] docs: add the new harness pages to the nav, and use
 the newest models

- Nav entries for sessions, coding tools, the sandbox backend, permissions,
  snapshots, and agent profiles, and the dates of the changed pages.
- The samples written for these pages use gpt-6.1-sol, and gpt-6-luna as
  the small model.
- Links from subagents to the agent limits, and from coding agents to the
  permission modes.
---
 docs/config.json                      | 61 +++++++++++++++++++++------
 docs/harness/coding-agents.md         |  4 +-
 docs/harness/coding-tools-backends.md |  6 +--
 docs/harness/coding-tools.md          |  4 +-
 docs/harness/fork-and-reset.md        |  2 +-
 docs/harness/inputs.md                |  4 +-
 docs/harness/sessions.md              |  4 +-
 docs/harness/subagents.md             | 18 ++++----
 8 files changed, 68 insertions(+), 35 deletions(-)

diff --git a/docs/config.json b/docs/config.json
index 1a232750be..b18c1c6eda 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -166,7 +166,7 @@
           "label": "Subagents",
           "to": "chat/subagents",
           "addedAt": "2026-09-21",
-          "updatedAt": "2026-10-02"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Agentic Cycle",
@@ -243,7 +243,7 @@
           "label": "Tools",
           "to": "tools/tools",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-10-04"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Server Tools",
@@ -308,7 +308,7 @@
           "label": "Middleware",
           "to": "advanced/middleware",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-10-04"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Built-in Middleware",
@@ -727,7 +727,7 @@
           "label": "Store Reference",
           "to": "persistence/store-reference",
           "addedAt": "2026-08-04",
-          "updatedAt": "2026-10-01"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "How Persistence Works",
@@ -918,11 +918,16 @@
           "addedAt": "2026-09-26",
           "updatedAt": "2026-10-05"
         },
+        {
+          "label": "List, rename, and fork sessions",
+          "to": "harness/sessions",
+          "addedAt": "2026-10-06"
+        },
         {
           "label": "Send inputs safely",
           "to": "harness/inputs",
           "addedAt": "2026-09-30",
-          "updatedAt": "2026-10-05"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Run side effects once",
@@ -940,7 +945,7 @@
           "label": "Control how a turn ends",
           "to": "harness/turn-control",
           "addedAt": "2026-10-01",
-          "updatedAt": "2026-10-05"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Store settings per thread",
@@ -955,7 +960,8 @@
         {
           "label": "Fork and reset a thread",
           "to": "harness/fork-and-reset",
-          "addedAt": "2026-10-05"
+          "addedAt": "2026-10-05",
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Share one log between sessions",
@@ -972,7 +978,32 @@
           "label": "Build a coding agent",
           "to": "harness/coding-agent",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-10-04"
+          "updatedAt": "2026-10-06"
+        },
+        {
+          "label": "Give your agent coding tools",
+          "to": "harness/coding-tools",
+          "addedAt": "2026-10-06"
+        },
+        {
+          "label": "Sandbox and extend the coding tools",
+          "to": "harness/coding-tools-backends",
+          "addedAt": "2026-10-06"
+        },
+        {
+          "label": "Ask before risky tool calls",
+          "to": "harness/permissions",
+          "addedAt": "2026-10-06"
+        },
+        {
+          "label": "Undo a turn",
+          "to": "harness/snapshots",
+          "addedAt": "2026-10-06"
+        },
+        {
+          "label": "Switch between agent profiles",
+          "to": "harness/agents",
+          "addedAt": "2026-10-06"
         },
         {
           "label": "Connect model providers",
@@ -994,13 +1025,14 @@
         {
           "label": "Track usage and cost",
           "to": "harness/usage",
-          "addedAt": "2026-10-05"
+          "addedAt": "2026-10-05",
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Use MCP servers",
           "to": "harness/mcp",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-09-28"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Use from any MCP client",
@@ -1039,7 +1071,7 @@
           "label": "Run agents from a harness",
           "to": "harness/subagents",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-10-05"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Deploy a harness",
@@ -1049,7 +1081,8 @@
         {
           "label": "Self-host the dashboard",
           "to": "harness/dashboard",
-          "addedAt": "2026-09-26"
+          "addedAt": "2026-09-26",
+          "updatedAt": "2026-10-06"
         }
       ]
     },
@@ -1096,7 +1129,7 @@
           "label": "Tools",
           "to": "sandbox/tools",
           "addedAt": "2026-06-29",
-          "updatedAt": "2026-08-12"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Policy",
@@ -1367,7 +1400,7 @@
           "label": "Ollama",
           "to": "adapters/ollama",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-09-03"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Grok (xAI)",
diff --git a/docs/harness/coding-agents.md b/docs/harness/coding-agents.md
index 94e65175c5..ce4ed7d33d 100644
--- a/docs/harness/coding-agents.md
+++ b/docs/harness/coding-agents.md
@@ -44,7 +44,7 @@ const repo = '/path/to/your/repo'
 
 export const lead = defineHarness({
   name: 'acme/lead',
-  adapter: openaiText('gpt-5.6'),
+  adapter: openaiText('gpt-6.1-sol'),
   plugins: () => [
     permissions(),
     codingAgents({
@@ -103,7 +103,7 @@ Use `'shared'` when the agents build on each other's changes. Use `'per-agent'`
 
 ## Plan mode
 
-When the `permissions()` plugin is in `plan` mode, the agents start read-only:
+When the `permissions()` plugin is in [`plan` mode](./permissions#pick-a-mode), the agents start read-only:
 
 - Claude Code gets `permissionMode: 'plan'`.
 - Codex gets `sandboxMode: 'read-only'`.
diff --git a/docs/harness/coding-tools-backends.md b/docs/harness/coding-tools-backends.md
index 573b2bde5c..8a391df688 100644
--- a/docs/harness/coding-tools-backends.md
+++ b/docs/harness/coding-tools-backends.md
@@ -52,7 +52,7 @@ const root = '/workspace'
 
 export const sandboxed = defineHarness({
   name: 'acme/sandboxed-coder',
-  adapter: openaiText('gpt-5.6'),
+  adapter: openaiText('gpt-6.1-sol'),
   plugins: () => [
     permissions({ root }),
     workspaceTools({ root, backend: sandboxWorkspaceBackend(sandbox) }),
@@ -162,7 +162,7 @@ import { openaiText } from '@tanstack/ai-openai'
 
 export const formatted = defineHarness({
   name: 'acme/formatted-coder',
-  adapter: openaiText('gpt-5.6'),
+  adapter: openaiText('gpt-6.1-sol'),
   plugins: () => [
     permissions({ root }),
     workspaceTools({ root }),
@@ -238,7 +238,7 @@ import { boundToolOutput } from '@tanstack/ai-harness/plugins'
 
 export const bounded = defineHarness({
   name: 'acme/bounded-coder',
-  adapter: openaiText('gpt-5.6'),
+  adapter: openaiText('gpt-6.1-sol'),
   plugins: () => [
     workspaceTools({ root }),
     boundToolOutput({ dir: '.agent/tool-output' }),
diff --git a/docs/harness/coding-tools.md b/docs/harness/coding-tools.md
index a70545641b..326e67830f 100644
--- a/docs/harness/coding-tools.md
+++ b/docs/harness/coding-tools.md
@@ -61,7 +61,7 @@ const root = process.cwd()
 
 const coder = defineHarness({
   name: 'acme/coder',
-  adapter: openaiText('gpt-5.6'),
+  adapter: openaiText('gpt-6.1-sol'),
   plugins: () => [permissions({ root }), workspaceTools({ root })],
 })
 
@@ -228,7 +228,7 @@ import { openaiText } from '@tanstack/ai-openai'
 
 const repos = defineHarness({
   name: 'acme/repos',
-  adapter: openaiText('gpt-5.6'),
+  adapter: openaiText('gpt-6.1-sol'),
   plugins: () => [workspaceTools({ root: '/srv/repos' })],
 })
 
diff --git a/docs/harness/fork-and-reset.md b/docs/harness/fork-and-reset.md
index 1a776f1ba9..e9130171da 100644
--- a/docs/harness/fork-and-reset.md
+++ b/docs/harness/fork-and-reset.md
@@ -25,7 +25,7 @@ import { openaiText } from '@tanstack/ai-openai'
 
 export const assistant = defineHarness({
   name: 'acme/assistant',
-  adapter: openaiText('gpt-5.6'),
+  adapter: openaiText('gpt-6.1-sol'),
 })
 
 const host = createHarnessHost({ persistence: memoryPersistence() })
diff --git a/docs/harness/inputs.md b/docs/harness/inputs.md
index 93af922049..8bfb58bf29 100644
--- a/docs/harness/inputs.md
+++ b/docs/harness/inputs.md
@@ -27,7 +27,7 @@ import { openaiText } from '@tanstack/ai-openai'
 
 const assistant = defineHarness({
   name: 'acme/assistant',
-  adapter: openaiText('gpt-5.6'),
+  adapter: openaiText('gpt-6.1-sol'),
 })
 const host = createHarnessHost({
   persistence: {
@@ -185,7 +185,7 @@ const openRecord = toolDefinition({
 
 const records = defineHarness({
   name: 'acme/records',
-  adapter: openaiText('gpt-5.6'),
+  adapter: openaiText('gpt-6.1-sol'),
   tools: [openRecord],
 })
 const recordSession = await host.open(records, { threadId: 'user-1-records' })
diff --git a/docs/harness/sessions.md b/docs/harness/sessions.md
index 264b12e3a1..ed27a64ba5 100644
--- a/docs/harness/sessions.md
+++ b/docs/harness/sessions.md
@@ -30,8 +30,8 @@ import { openaiText } from '@tanstack/ai-openai'
 
 export const assistant = defineHarness({
   name: 'acme/assistant',
-  adapter: openaiText('gpt-5.6'),
-  plugins: () => [title({ adapter: openaiText('gpt-5.4-nano') })],
+  adapter: openaiText('gpt-6.1-sol'),
+  plugins: () => [title({ adapter: openaiText('gpt-6-luna') })],
 })
 
 const host = createHarnessHost({ persistence: memoryPersistence() })
diff --git a/docs/harness/subagents.md b/docs/harness/subagents.md
index 388f164ea9..c2c939b88d 100644
--- a/docs/harness/subagents.md
+++ b/docs/harness/subagents.md
@@ -30,7 +30,7 @@ const explorer = defineAgent({
   inputSchema: z.object({ task: z.string() }),
   run: (ctx) =>
     ctx.chat({
-      adapter: openaiText('gpt-5.6-luna'),
+      adapter: openaiText('gpt-6-luna'),
       messages: [{ role: 'user', content: ctx.input.task }],
       stream: false,
     }),
@@ -89,7 +89,7 @@ const migrator = defineAgent({
     const exportId = await ctx.step.do('export', () => startExport(ctx.input.customer))
     await ctx.step.do('import', () => importInto('eu-west', exportId))
     return ctx.chat({
-      adapter: openaiText('gpt-5.6'),
+      adapter: openaiText('gpt-6.1-sol'),
       messages: [{ role: 'user', content: `Write a short report about ${exportId}.` }],
       stream: false,
     })
@@ -139,7 +139,7 @@ import { z } from 'zod'
 const writer = defineAgent({
   name: 'writer',
   description: 'Writes blog posts',
-  run: (ctx) => ctx.chat({ adapter: openaiText('gpt-5.6'), stream: false }),
+  run: (ctx) => ctx.chat({ adapter: openaiText('gpt-6.1-sol'), stream: false }),
 })
 
 const pricer = defineAgent({
@@ -148,7 +148,7 @@ const pricer = defineAgent({
   inputSchema: z.object({ vendor: z.string() }),
   run: (ctx) =>
     ctx.chat({
-      adapter: openaiText('gpt-5.6'),
+      adapter: openaiText('gpt-6.1-sol'),
       messages: [{ role: 'user', content: `Compare the plans of ${ctx.input.vendor}` }],
       stream: false,
     }),
@@ -156,7 +156,7 @@ const pricer = defineAgent({
 
 export const studio = defineHarness({
   name: 'acme/studio',
-  adapter: openaiText('gpt-5.6'),
+  adapter: openaiText('gpt-6.1-sol'),
   agents: [writer, pricer],
   routing: {
     router: async ({ agents, messages, adapter }) => {
@@ -207,12 +207,12 @@ import { defineHarness, harnessAgent } from '@tanstack/ai-harness'
 const reviewer = defineHarness({
   name: 'acme/reviewer',
   description: 'Reviews a change and lists the risks',
-  adapter: openaiText('gpt-5.6'),
+  adapter: openaiText('gpt-6.1-sol'),
 })
 
 export const lead = defineHarness({
   name: 'acme/lead',
-  adapter: openaiText('gpt-5.6'),
+  adapter: openaiText('gpt-6.1-sol'),
   subagents: { agents: [harnessAgent(reviewer)] },
 })
 ```
@@ -289,7 +289,7 @@ export const coder = defineHarness({
 })
 ```
 
-The permission rules of an `agents()` profile apply only while that profile is the primary agent. They do not apply inside a child run.
+The permission rules of an `agents()` profile apply only while that profile is the primary agent. They do not apply inside a child run. See [Known limits](./agents#known-limits).
 
 ## Stay within limits
 
@@ -298,7 +298,7 @@ A harness always limits its children. Without `subagents.limits`, it uses a dept
 ```ts group=harness-subagents
 export const careful = defineHarness({
   name: 'acme/careful',
-  adapter: openaiText('gpt-5.6'),
+  adapter: openaiText('gpt-6.1-sol'),
   subagents: {
     agents: [explorer],
     limits: { maxDepth: 1, maxConcurrent: 2, maxCalls: 6, timeoutMs: 60_000 },

From ac33982dcfd4299ea0fb63340ea0898835857154 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 18:51:56 +0200
Subject: [PATCH 269/286] fix(ai-harness): share the rules of permissions()
 with other plugins

permissions() now adds its own rules to the PermissionRules extension
point. Before, code mode read only the rules of other plugins, so a tool
that a user rule makes ask could move into code mode and run there
without the question. The decisions of permissions() do not change: its
own rules still come last.
---
 packages/ai-code-mode/tests/harness.test.ts   | 23 +++++++-
 .../ai-harness/src/first-party/permissions.ts | 15 ++++-
 packages/ai-harness/tests/permissions.test.ts | 58 +++++++++++++++++--
 3 files changed, 87 insertions(+), 9 deletions(-)

diff --git a/packages/ai-code-mode/tests/harness.test.ts b/packages/ai-code-mode/tests/harness.test.ts
index d09e9fc304..606b449000 100644
--- a/packages/ai-code-mode/tests/harness.test.ts
+++ b/packages/ai-code-mode/tests/harness.test.ts
@@ -8,7 +8,7 @@ import {
   defineHarness,
   definePlugin,
 } from '@tanstack/ai-harness'
-import { PermissionResources } from '@tanstack/ai-harness/plugins'
+import { PermissionResources, permissions } from '@tanstack/ai-harness/plugins'
 import { codeMode } from '../src/harness'
 import type { AnyTextAdapter, AnyTool, StreamChunk } from '@tanstack/ai'
 import type { HarnessPlugin } from '@tanstack/ai-harness'
@@ -406,6 +406,27 @@ describe('codeMode', () => {
     ])
   })
 
+  it('keeps a tool that a rule of permissions() asks for as a tool call', async () => {
+    const names = await firstToolNames({
+      tools: [
+        markedTool('docs_search'),
+        markedTool('notes_search'),
+        tools.lookup,
+      ],
+      plugins: [
+        permissions({
+          rules: [
+            { tool: 'docs_*', decision: 'ask' },
+            { tool: 'lookup', decision: 'ask' },
+          ],
+        }),
+        codeMode({ driver: fakeDriver().driver }),
+      ],
+    })
+    // A call inside the isolate skips the question, so both tools stay.
+    expect(names).toEqual(['docs_search', 'lookup', 'execute_typescript'])
+  })
+
   it('keeps a tool that declares permission resources as a tool call', async () => {
     const resources = definePlugin({
       name: 'test/resources',
diff --git a/packages/ai-harness/src/first-party/permissions.ts b/packages/ai-harness/src/first-party/permissions.ts
index 7148e7e73a..030f356fd1 100644
--- a/packages/ai-harness/src/first-party/permissions.ts
+++ b/packages/ai-harness/src/first-party/permissions.ts
@@ -23,7 +23,10 @@ export interface PermissionRule {
   kind?: 'read' | 'edit' | 'execute'
 }
 
-/** Tool plugins add their rules here. `permissions()` reads them. */
+/**
+ * Tool plugins add their rules here. `permissions()` reads them, and adds its
+ * own `rules` too, so other readers like `codeMode()` see them.
+ */
 export const PermissionRules = createExtensionPoint<PermissionRule>(
   'tanstack/permission-rules',
 )
@@ -439,7 +442,10 @@ export function permissions(
         return resources
       }
       /** The rules an `always` answer saves: one allow for each resource. */
-      const rulesToSave = (tool: string, resources: CallResources | undefined) => {
+      const rulesToSave = (
+        tool: string,
+        resources: CallResources | undefined,
+      ) => {
         if (resources === undefined) {
           return [{ tool, decision: 'allow' as const }]
         }
@@ -547,6 +553,11 @@ export function permissions(
           const current = mode()
           return tools.filter((tool) => !isHidden(rules, tool.name, current))
         },
+        // Other readers, like codeMode(), must see the user's rules too. The
+        // checks above add them again at the end, so they still win there.
+        contribute: (options.rules ?? []).map((rule) =>
+          PermissionRules.item(rule),
+        ),
         // The lead turn and every agent run check the same rules. Each run
         // gets only one of the two lists, so a call is checked once.
         middleware: [check],
diff --git a/packages/ai-harness/tests/permissions.test.ts b/packages/ai-harness/tests/permissions.test.ts
index 2d86434dcb..9028f00478 100644
--- a/packages/ai-harness/tests/permissions.test.ts
+++ b/packages/ai-harness/tests/permissions.test.ts
@@ -26,10 +26,15 @@ function read(
   path: string,
   options: { root?: string; rules?: Array<PermissionRule> } = {},
 ) {
-  return decidePermission(options.rules ?? readAllowed, 'read_file', 'default', {
-    resources: { paths: [path] },
-    root: options.root ?? ROOT,
-  })
+  return decidePermission(
+    options.rules ?? readAllowed,
+    'read_file',
+    'default',
+    {
+      resources: { paths: [path] },
+      root: options.root ?? ROOT,
+    },
+  )
 }
 
 /** Run `fn` as if the host were `platform`. Letter case rules depend on it. */
@@ -248,7 +253,11 @@ function fakeTools() {
           decision: 'allow',
           kind: 'read',
         }),
-        PermissionRules.item({ tool: 'bash', decision: 'ask', kind: 'execute' }),
+        PermissionRules.item({
+          tool: 'bash',
+          decision: 'ask',
+          kind: 'execute',
+        }),
         PermissionResources.item({
           read_file: { paths: (input) => [field(input, 'path')] },
           bash: { commands: (input) => field(input, 'command').split(' && ') },
@@ -268,7 +277,11 @@ async function open(
   const { adapter, calls } = mockAdapter([...replies, () => text('done')])
   const host = createHarnessHost({ persistence })
   const session = await host.open(
-    defineHarness({ name: 'test/permissions', adapter, plugins: () => plugins }),
+    defineHarness({
+      name: 'test/permissions',
+      adapter,
+      plugins: () => plugins,
+    }),
     { threadId },
   )
   return { host, session, calls }
@@ -440,6 +453,39 @@ describe('permissions()', () => {
     await host.close()
   })
 
+  it('shares its rules with other plugins, and they still beat the rules of tool plugins', async () => {
+    const tools = fakeTools()
+    let seen: Array<PermissionRule> = []
+    // Another plugin that reads the rules, like codeMode() does.
+    const reader = definePlugin({
+      name: 'test/reader',
+      setup: (ctx) => {
+        const rules = ctx.collect(PermissionRules)
+        return {
+          prepareTools: ({ tools: list }) => {
+            seen = [...rules]
+            return list
+          },
+        }
+      },
+    })
+    const rule: PermissionRule = { tool: 'read_file', decision: 'ask' }
+    const { host, session } = await open(
+      memoryPersistence(),
+      // The tool plugin comes after permissions(), and it allows read_file.
+      [permissions({ root: ROOT, rules: [rule] }), tools.plugin, reader],
+      [() => toolCall('read_file', { path: 'src/a.ts' }, 'c1')],
+    )
+
+    const turn = session.prompt('read a file')
+    expect(await answer(session, { answer: 'reject' })).toContain('src/a.ts')
+    await turn
+
+    expect(tools.ran).toEqual([])
+    expect(seen).toContainEqual(rule)
+    await host.close()
+  })
+
   it('never lets a saved answer beat a deny', async () => {
     const persistence = memoryPersistence()
     await persistence.stores.metadata.set(

From a521105c70017e72077cd342831ec241dd67e722 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 18:51:56 +0200
Subject: [PATCH 270/286] test(e2e): a middleware replaces a tool result

A tool-replace mode returns replaceResult from onAfterToolCall. The client
shows the new result, and the next model call gets it.
---
 testing/e2e/src/routes/api.middleware-test.ts | 13 +++++
 testing/e2e/src/routes/middleware-test.tsx    |  1 +
 testing/e2e/tests/middleware.spec.ts          | 56 +++++++++++++++++++
 3 files changed, 70 insertions(+)

diff --git a/testing/e2e/src/routes/api.middleware-test.ts b/testing/e2e/src/routes/api.middleware-test.ts
index 2977005c34..8c7213fe5a 100644
--- a/testing/e2e/src/routes/api.middleware-test.ts
+++ b/testing/e2e/src/routes/api.middleware-test.ts
@@ -166,6 +166,17 @@ const toolSkipMiddleware: ChatMiddleware = {
   },
 }
 
+const toolReplaceMiddleware: ChatMiddleware = {
+  name: 'tool-replace',
+  onAfterToolCall(_ctx, info) {
+    if (info.toolName !== 'get_weather') return
+    return {
+      type: 'replaceResult',
+      result: { replaced: true, reason: 'middleware' },
+    }
+  },
+}
+
 /**
  * Capability provide/consume flow (`capability` mode).
  *
@@ -566,6 +577,8 @@ export const Route = createFileRoute('/api/middleware-test')({
             middleware.push(chunkTransformMiddleware)
           if (middlewareMode === 'tool-skip')
             middleware.push(toolSkipMiddleware)
+          if (middlewareMode === 'tool-replace')
+            middleware.push(toolReplaceMiddleware)
           if (middlewareMode === 'capability') {
             // Order matters: the provider's setup() must run before the
             // consumer reads the capability. Array order is preserved.
diff --git a/testing/e2e/src/routes/middleware-test.tsx b/testing/e2e/src/routes/middleware-test.tsx
index 398b3ba775..6bde171f32 100644
--- a/testing/e2e/src/routes/middleware-test.tsx
+++ b/testing/e2e/src/routes/middleware-test.tsx
@@ -18,6 +18,7 @@ const MIDDLEWARE_MODES = [
   { id: 'none', label: 'No Middleware' },
   { id: 'chunk-transform', label: 'Chunk Transform (prefix text)' },
   { id: 'tool-skip', label: 'Tool Skip (skip with custom result)' },
+  { id: 'tool-replace', label: 'Tool Replace (replace result after call)' },
   { id: 'capability', label: 'Capability (provide/consume prefix)' },
   { id: 'phase-recorder', label: 'Phase Recorder (capture phase + chunks)' },
   { id: 'otel', label: 'OpenTelemetry (capture spans/metrics)' },
diff --git a/testing/e2e/tests/middleware.spec.ts b/testing/e2e/tests/middleware.spec.ts
index c7e05b6d47..dd1d3dcd72 100644
--- a/testing/e2e/tests/middleware.spec.ts
+++ b/testing/e2e/tests/middleware.spec.ts
@@ -132,6 +132,62 @@ test.describe('Middleware Lifecycle', () => {
     expect(toolResults[0].content).toContain('skipped')
   })
 
+  test('onAfterToolCall replaceResult changes what the client and the model see', async ({
+    page,
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const params = new URLSearchParams()
+    if (testId) params.set('testId', testId)
+    if (aimockPort) params.set('aimockPort', String(aimockPort))
+    const qs = params.toString()
+    await page.goto(`/middleware-test${qs ? '?' + qs : ''}`)
+    await page.waitForTimeout(2000)
+    await page.locator('#mw-scenario-select').selectOption('with-tool')
+    await page.locator('#mw-mode-select').selectOption('tool-replace')
+    await page.locator('#mw-run-button').click()
+
+    await page.waitForFunction(
+      () =>
+        document
+          .querySelector('#mw-metadata')
+          ?.getAttribute('data-test-complete') === 'true',
+      { timeout: 10000 },
+    )
+
+    // get_weather returns {"city":"NYC","temperature":72,...}. The
+    // tool-replace middleware swaps it for this value after the call.
+    const replaced = '{"replaced":true,"reason":"middleware"}'
+
+    // The client gets the replaced result in TOOL_CALL_RESULT.
+    const messagesJson = await page.locator('#mw-messages-json').textContent()
+    const messages = JSON.parse(messagesJson || '[]')
+    const toolResults = messages.flatMap((m: any) =>
+      m.parts.filter((p: any) => p.type === 'tool-result'),
+    )
+    expect(toolResults).toHaveLength(1)
+    expect(toolResults[0].content).toBe(replaced)
+
+    // The model gets the replaced result on the next call. aimock journals
+    // the Responses `function_call_output` as a `role: 'tool'` 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 calls = entries.filter(
+      (entry) => entry.headers?.['x-test-id'] === testId,
+    )
+    expect(calls).toHaveLength(2)
+    const toolMessage = calls[1]?.body?.messages?.find(
+      (message) => message.role === 'tool',
+    )
+    expect(toolMessage?.content).toBe(replaced)
+  })
+
   test('capability provide/consume flow surfaces the consumed value in the stream', async ({
     page,
     testId,

From 6656c1d711bd7922288aa785dd75b9a445cfb4c9 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 18:54:50 +0200
Subject: [PATCH 271/286] fix(ai-vercel-gateway): Gemma 4 31B reasons, as in
 the catalog

The reasoning drift test (test:maintainer) failed: the catalog now says
Vercel google/gemma-4-31b-it reasons, and the ai-vercel-gateway table
said it does not. models.dev has no reasoning for it at Vercel, but
Vercel's own model list tags it `reasoning`, and Google, OpenRouter, and
pi 0.87.1 list it.

The ai-vercel-gateway target gets the same override, and its table entry
is the one the sync script writes ({ budget: false }). The other drift
that the sync script finds (models added with main) is left for its own
sync.

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 packages/ai-models/scripts/overrides.ts           | 4 ++--
 packages/ai-vercel-gateway/src/model-reasoning.ts | 6 +++++-
 scripts/model-sync/reasoning-targets.ts           | 6 ++++++
 3 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/packages/ai-models/scripts/overrides.ts b/packages/ai-models/scripts/overrides.ts
index d8e1ff6067..16a19260ad 100644
--- a/packages/ai-models/scripts/overrides.ts
+++ b/packages/ai-models/scripts/overrides.ts
@@ -86,7 +86,7 @@ export const MODEL_OVERRIDES: Readonly<
       reasoningMap: only('none', 'high', 'max'),
     },
   },
-  // models.dev lists no reasoning for it at Vercel. Google, OpenRouter, and
-  // pi 0.87.1 list it.
+  // models.dev lists no reasoning for it at Vercel. Vercel's own model list
+  // tags it `reasoning`, and Google, OpenRouter, and pi 0.87.1 list it.
   'vercel-ai-gateway': { 'google/gemma-4-31b-it': { reasoning: true } },
 }
diff --git a/packages/ai-vercel-gateway/src/model-reasoning.ts b/packages/ai-vercel-gateway/src/model-reasoning.ts
index 2bb3e3dec4..4dab7e8ab2 100644
--- a/packages/ai-vercel-gateway/src/model-reasoning.ts
+++ b/packages/ai-vercel-gateway/src/model-reasoning.ts
@@ -250,6 +250,10 @@ export type VercelGatewayModelReasoningByName = {
     levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
     budget: false
   }
+  'google/gemma-4-31b-it': {
+    levels: 'off' | 'minimal' | 'low' | 'medium' | 'high'
+    budget: false
+  }
   'inception/mercury-2': { levels: 'low' | 'medium' | 'high'; budget: false }
   'inception/mercury-2.5': {
     levels: 'off' | 'low' | 'medium' | 'high'
@@ -1385,7 +1389,7 @@ export const VERCEL_GATEWAY_MODEL_REASONING: Readonly<
     budget: false,
   },
   'google/gemma-4-26b-a4b-it': { budget: false },
-  'google/gemma-4-31b-it': false,
+  'google/gemma-4-31b-it': { budget: false },
   'inception/mercury-2': {
     map: {
       off: null,
diff --git a/scripts/model-sync/reasoning-targets.ts b/scripts/model-sync/reasoning-targets.ts
index 1d4ca1b760..7c236fd2cb 100644
--- a/scripts/model-sync/reasoning-targets.ts
+++ b/scripts/model-sync/reasoning-targets.ts
@@ -210,6 +210,12 @@ export const REASONING_TARGETS: ReadonlyArray<ReasoningTarget> = [
     constPrefix: 'VERCEL_GATEWAY',
     sources: ['vercel'],
     gateway: 'vercel',
+    overrides: {
+      // models.dev lists no reasoning for it at Vercel. Vercel's own model
+      // list tags it `reasoning`, and Google, OpenRouter, and pi 0.87.1 list
+      // it (also in `packages/ai-models/scripts/overrides.ts`).
+      'google/gemma-4-31b-it': { budget: false },
+    },
   },
   {
     pkg: 'ai-claude-code',

From 70ef41c9494cce5c8b51ae52a0c1695916ee89f4 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 19:10:15 +0200
Subject: [PATCH 272/286] fix(ai-harness): clients set only exposed config and
 run only exposed commands

A client could send a config input or a command with no expose check, so
it could set the permission mode to bypass and run tools with no
question. defineHarness now takes expose.config and expose.commands, like
expose.settings and expose.agents. Nothing is exposed by default, and
other names get not_exposed. Server code is not affected.
---
 docs/harness/connect.md                       |  35 +++++-
 docs/harness/custom-ui.md                     |   9 +-
 docs/harness/permissions.md                   |  34 +++++-
 packages/ai-harness/src/define.ts             |  19 ++++
 packages/ai-harness/src/protocol.ts           |  30 +++--
 packages/ai-harness/tests/auth-wait.test.ts   |   2 +
 .../ai-harness/tests/client-reads.test.ts     |   1 +
 .../ai-harness/tests/expose-inputs.test.ts    | 107 ++++++++++++++++++
 8 files changed, 222 insertions(+), 15 deletions(-)
 create mode 100644 packages/ai-harness/tests/expose-inputs.test.ts

diff --git a/docs/harness/connect.md b/docs/harness/connect.md
index c5bf7bc288..42f81730c8 100644
--- a/docs/harness/connect.md
+++ b/docs/harness/connect.md
@@ -48,9 +48,39 @@ The handler answers these paths under your route:
 - `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.
+- `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.
 
+## 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
+import { permissions, todos } from '@tanstack/ai-harness/plugins'
+
+export const team = defineHarness({
+  name: 'acme/team-assistant',
+  adapter: openaiText('gpt-6.1-sol'),
+  plugins: () => [permissions(), todos()],
+  expose: { settings: ['instructions'], commands: ['todos'] },
+})
+```
+
+| 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' }`.
+- Server code that calls the session is not limited. `session.setConfig()` and `session.command()` work for every key and command.
+- `defineHarness` checks the names in `agents`. Plugins add their config keys and commands when a session opens, so it does not check those names.
+
+Do not expose the `mode` of `permissions()` to clients that you do not trust. With `bypass`, every tool call runs with no question. See [Keep the mode on the server](./permissions#keep-the-mode-on-the-server).
+
 ## Talk to it from a web app
 
 `createHarnessClient` wraps those endpoints. Import the harness with `import type`, so no server code reaches the browser.
@@ -209,6 +239,8 @@ serveAcp({ host, harness: assistant })
 
 Tool approvals become permission requests in the editor. Image blocks, audio blocks, and embedded files in a prompt go to the media store of the session. ACP v2 is still a draft, so this API is experimental.
 
+The editor does not show harness questions, for example the questions of `permissions()`. A tool call that asks a question waits, and the editor cannot answer it. See [Known limits](./permissions#known-limits).
+
 ## 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:
@@ -231,6 +263,7 @@ If a plugin picks the model of the harness, the harness has no adapter to read i
 ## 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.
 - A WebSocket, an ACP agent for editors, and a harness you can call from `chat()`.
diff --git a/docs/harness/custom-ui.md b/docs/harness/custom-ui.md
index 20d34cb08c..b3142abad0 100644
--- a/docs/harness/custom-ui.md
+++ b/docs/harness/custom-ui.md
@@ -163,12 +163,19 @@ Start and stop work:
 - `view.cancel()`: cancels the running turn.
 - `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`.
+
+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.
-- `question.answer(value)`: answers a question.
+- `question.answer(value)`: answers a question. For the answers to a permission question, see [Answer a question](./permissions#answer-a-question).
 
 If a turn waits for more than one approval or client tool, the turn continues after you answer all of them.
 
diff --git a/docs/harness/permissions.md b/docs/harness/permissions.md
index 7bf16db9d2..7684dc165e 100644
--- a/docs/harness/permissions.md
+++ b/docs/harness/permissions.md
@@ -64,11 +64,40 @@ The `mode` setting decides how much runs without a question:
 Switch the mode in one of these places:
 
 - The CLI: type `/mode plan`. `/mode` alone shows the current mode.
-- A client: call `client.setConfig('mode', 'plan')`, or `view.setConfig('mode', 'plan')` in a [session view](./custom-ui).
 - Server code: call `session.setConfig('mode', 'plan')`.
+- A client: only when the harness exposes `mode`. See [Keep the mode on the server](#keep-the-mode-on-the-server).
 
 In `acceptEdits` mode, an edit outside `root` or of a `.env` file still asks.
 
+### Keep the mode on the server
+
+A client that can set `mode` can set `bypass`. Then every call runs with no question. So by default, a client cannot change the mode:
+
+- `client.setConfig('mode', 'bypass')` gets `{ status: 'rejected', reason: 'not_exposed' }`. The mode stays.
+- The `/mode` command from a client gets the same receipt.
+- The CLI and server code can still change the mode.
+
+A client can set only the config keys in `expose.config`. It can run only the commands in `expose.commands`. This harness lets a client pick the model, but not the mode:
+
+```ts group=harness-permissions
+import { modelPicker } from '@tanstack/ai-harness/plugins'
+
+export const team = defineHarness({
+  name: 'acme/team-coder',
+  adapter: openaiText('gpt-6.1-sol'),
+  plugins: () => [
+    permissions({ root }),
+    workspaceTools({ root }),
+    modelPicker({
+      choices: { sol: openaiText('gpt-6.1-sol'), pro: openaiText('gpt-6.1-sol-pro') },
+    }),
+  ],
+  expose: { config: ['model'], commands: ['model'] },
+})
+```
+
+Add `mode` to `expose.config` or `expose.commands` only for clients that you trust. Each of these clients can turn the questions off. [Choose what clients can change](./connect#choose-what-clients-can-change) lists every `expose` field.
+
 ## Write rules
 
 Add your own rules with `rules`:
@@ -273,13 +302,14 @@ Now `{ tool: 'copy_file', resource: 'docs/**', decision: 'allow' }` copies files
 
 - A rule that allows a tool with no `kind` also lets it run in `plan` mode. For example, an `allow` for `webfetch` lets it fetch pages in `plan` mode. `plan` denies only edits, commands, and calls that ask.
 - `serveAcp` does not show harness questions. An editor that uses [ACP](./connect#use-it-from-an-editor-acp) shows tool approvals only, so a call that asks waits.
-- A client that can send inputs to the thread can change the mode, also to `bypass`. It can also answer the questions. Control who opens a thread with `canAccess`. See [Connect clients](./connect).
+- A client that can send inputs to the thread can answer the questions, also with `always`. Control who opens a thread with `canAccess`. See [Connect clients](./connect).
 - There is no command to forget a saved `always` answer.
 
 ## What you have now
 
 - A question before each edit, command, and web fetch.
 - Modes to plan, to edit fast, or to run everything.
+- A mode that a client cannot change, unless you expose it.
 - Rules for folders, files, and commands, and saved answers for each project.
 - The same rules in every agent run.
 
diff --git a/packages/ai-harness/src/define.ts b/packages/ai-harness/src/define.ts
index 11191004aa..38f9169c84 100644
--- a/packages/ai-harness/src/define.ts
+++ b/packages/ai-harness/src/define.ts
@@ -207,6 +207,25 @@ export interface HarnessConfig<
      * system prompt, so expose them only to clients you trust.
      */
     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
+     * 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
+     * `mode` on the server, or expose it only to clients you trust.
+     */
+    config?: ReadonlyArray<string>
+    /**
+     * The commands a client may run with a `command` input, for example
+     * `client.command('undo')`, or `/undo` in a session view on a client.
+     * An input with any other command is refused with `not_exposed`. Server
+     * code that calls `session.command()` can run every command. Warning:
+     * `/mode bypass` of `permissions()` turns approvals off, so expose `mode`
+     * only to clients you trust. Plugins add their commands when a session
+     * opens, so `defineHarness` does not check these names.
+     */
+    commands?: ReadonlyArray<string>
   }
 }
 
diff --git a/packages/ai-harness/src/protocol.ts b/packages/ai-harness/src/protocol.ts
index 34cc2d15d2..b06523bdc7 100644
--- a/packages/ai-harness/src/protocol.ts
+++ b/packages/ai-harness/src/protocol.ts
@@ -136,10 +136,12 @@ export function parseControlFrame(data: string): ControlFrame {
 }
 
 /**
- * Apply a client input to a session. Only agents in `expose.agents` can run
- * from a client. 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.
+ * Apply a client input to a session. A client can run only the agents in
+ * `expose.agents` and 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,
@@ -157,6 +159,11 @@ export async function applyInput(
       ? { 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, {
@@ -183,6 +190,10 @@ export async function applyInput(
     case 'setDelivery':
       return session.setDelivery(input.inputId, 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,
@@ -201,6 +212,9 @@ export async function applyInput(
     case 'answer':
       return session.answer(input.questionId, input.value)
     case 'config':
+      if (!(harness.expose?.config ?? []).includes(input.key)) {
+        return notExposed
+      }
       return session.setConfig(input.key, input.value)
     case 'configure': {
       // A client changes only the settings the harness exposes.
@@ -208,13 +222,7 @@ export async function applyInput(
       const isExposed = Object.keys(input.settings).every((key) =>
         exposed.includes(key),
       )
-      if (!isExposed) {
-        return {
-          inputId: input.inputId ?? '',
-          status: 'rejected',
-          reason: 'not_exposed',
-        }
-      }
+      if (!isExposed) return notExposed
       return session.configure(input.settings, id)
     }
     case 'reset':
diff --git a/packages/ai-harness/tests/auth-wait.test.ts b/packages/ai-harness/tests/auth-wait.test.ts
index e01d9fda5c..e20be02d0f 100644
--- a/packages/ai-harness/tests/auth-wait.test.ts
+++ b/packages/ai-harness/tests/auth-wait.test.ts
@@ -374,6 +374,7 @@ describe('sign-ins in a shared thread', () => {
       name: 'test/auth-wait-shared-http',
       adapter,
       plugins: () => [github(seen, true)],
+      expose: { commands: ['connect:github'] },
     })
     const handler = createHarnessHandler({
       host,
@@ -441,6 +442,7 @@ describe('sign-ins in a shared thread', () => {
           }),
         }),
       ],
+      expose: { commands: ['whoami'] },
     })
     const handler = createHarnessHandler({
       host,
diff --git a/packages/ai-harness/tests/client-reads.test.ts b/packages/ai-harness/tests/client-reads.test.ts
index 642578d4c9..f7bf784050 100644
--- a/packages/ai-harness/tests/client-reads.test.ts
+++ b/packages/ai-harness/tests/client-reads.test.ts
@@ -33,6 +33,7 @@ function setup(
     name: 'test/client-reads',
     adapter,
     plugins: () => [asker],
+    expose: { config: ['tone'], commands: ['confirm'] },
   })
   const host = createHarnessHost({ persistence: memoryPersistence() })
   const handler = createHarnessHandler({
diff --git a/packages/ai-harness/tests/expose-inputs.test.ts b/packages/ai-harness/tests/expose-inputs.test.ts
new file mode 100644
index 0000000000..04ecca45a6
--- /dev/null
+++ b/packages/ai-harness/tests/expose-inputs.test.ts
@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { applyInput, createHarnessHost, defineHarness } from '../src'
+import { permissions } from '../src/first-party'
+import { mockAdapter } from './helpers'
+import type { HarnessSession } from '../src'
+
+async function open(expose?: {
+  config?: Array<string>
+  commands?: Array<string>
+}) {
+  const harness = defineHarness({
+    name: 'test/expose-inputs',
+    adapter: mockAdapter([]).adapter,
+    plugins: () => [permissions()],
+    ...(expose ? { expose } : {}),
+  })
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const session = await host.open(harness, { threadId: 't' })
+  return { host, harness, session }
+}
+
+/** The `mode` setting of `permissions()`, as the session has it now. */
+const modeOf = (session: HarnessSession) =>
+  session.describe().config.find((entry) => entry.key === 'mode')?.value
+
+describe('client config and command inputs', () => {
+  it('refuses a config key that is not exposed, and the mode stays', async () => {
+    const { host, harness, session } = await open()
+
+    const receipt = await applyInput(harness, session, {
+      op: 'config',
+      key: 'mode',
+      value: 'bypass',
+      inputId: 'c-1',
+    })
+
+    expect(receipt).toEqual({
+      inputId: 'c-1',
+      status: 'rejected',
+      reason: 'not_exposed',
+    })
+    expect(modeOf(session)).toBe('default')
+    await host.close()
+  })
+
+  it('sets an exposed config key', async () => {
+    const { host, harness, session } = await open({ config: ['mode'] })
+
+    const receipt = await applyInput(harness, session, {
+      op: 'config',
+      key: 'mode',
+      value: 'plan',
+    })
+
+    expect(receipt.status).toBe('accepted')
+    expect(modeOf(session)).toBe('plan')
+    await host.close()
+  })
+
+  it('refuses a command that is not exposed, and the command does not run', async () => {
+    const { host, harness, session } = await open({ commands: ['undo'] })
+
+    const receipt = await applyInput(harness, session, {
+      op: 'command',
+      name: 'mode',
+      input: 'bypass',
+    })
+
+    expect(receipt).toEqual({
+      inputId: '',
+      status: 'rejected',
+      reason: 'not_exposed',
+    })
+    expect(modeOf(session)).toBe('default')
+    await host.close()
+  })
+
+  it('runs an exposed command', async () => {
+    const { host, harness, session } = await open({ commands: ['mode'] })
+
+    const receipt = await applyInput(harness, session, {
+      op: 'command',
+      name: 'mode',
+      input: 'plan',
+    })
+
+    expect(receipt.status).toBe('accepted')
+    await expect(session.operation(receipt.operationId ?? '')).resolves.toBe(
+      'Mode: plan.',
+    )
+    expect(modeOf(session)).toBe('plan')
+    await host.close()
+  })
+
+  it('lets server code set every key and run every command', async () => {
+    const { host, session } = await open()
+
+    expect((await session.setConfig('mode', 'plan')).status).toBe('accepted')
+    expect(modeOf(session)).toBe('plan')
+    expect(await session.command('mode', 'acceptEdits')).toBe(
+      'Mode: acceptEdits.',
+    )
+    expect(modeOf(session)).toBe('acceptEdits')
+    await host.close()
+  })
+})

From 618d7112128da21194740f872fe89f1077798b68 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 19:45:22 +0200
Subject: [PATCH 273/286] test(ai-isolate-e2b): cover stderr without an
 out-of-memory report

Coverage failed on this PR for ai-isolate-e2b (branches 81.48% vs
82.22%), although the package did not change. The false side of
`recent.includes('heap out of memory')` in `onStderr` was hit only by
the memory test, and only when the host read V8's first GC block as its
own stderr chunk. On a Linux runner the writes usually merge into one
chunk, so that side is missed.

The new test writes ordinary stderr and exits with code 2. It must fail
as E2BExecutionError with the stderr tail, not as MemoryLimitError. It
fails when every stderr chunk sets `outOfMemory`, and it also covers the
stderr tail in the exit message.

The thinking-shape changeset also lists @tanstack/ai-vercel-gateway
(the Gemma 4 31B fix in 6656c1d71).

Claude-Session: https://claude.ai/code/session_01APYv1qshKyjPPpkFyRZhfZ
---
 .changeset/anthropic-thinking-shape.md               |  3 +++
 packages/ai-isolate-e2b/tests/isolate-driver.test.ts | 11 +++++++++++
 2 files changed, 14 insertions(+)

diff --git a/.changeset/anthropic-thinking-shape.md b/.changeset/anthropic-thinking-shape.md
index 6f661322a9..966a86add5 100644
--- a/.changeset/anthropic-thinking-shape.md
+++ b/.changeset/anthropic-thinking-shape.md
@@ -2,6 +2,7 @@
 '@tanstack/ai': minor
 '@tanstack/ai-anthropic': minor
 '@tanstack/ai-models': minor
+'@tanstack/ai-vercel-gateway': patch
 ---
 
 Send the Anthropic thinking shape that the model record gives.
@@ -11,3 +12,5 @@ Send the Anthropic thinking shape that the model record gives.
 - `midConversationChannels` takes `{ tools?: boolean; systemPrompts?: boolean }` to turn on one channel only.
 
 `modelReasoning(record)` sets `adaptive` from `compat.forceAdaptiveThinking` and `midConversationEffort` from the new `compat.supportsMidConvoEffort` for `anthropic-messages` records. The catalog flags now equal pi's: Claude 4.6 and later think adaptively on every provider (also with dot ids such as `anthropic/claude-opus-4.7`), and the other Vercel AI Gateway models think with a budget.
+
+Vercel `google/gemma-4-31b-it` reasons, in the catalog and in `@tanstack/ai-vercel-gateway`. Vercel's own model list tags it `reasoning`. Seven Fireworks records take Fireworks' own effort levels.
diff --git a/packages/ai-isolate-e2b/tests/isolate-driver.test.ts b/packages/ai-isolate-e2b/tests/isolate-driver.test.ts
index 676ea64e4f..d0adaf2a15 100644
--- a/packages/ai-isolate-e2b/tests/isolate-driver.test.ts
+++ b/packages/ai-isolate-e2b/tests/isolate-driver.test.ts
@@ -403,6 +403,17 @@ describe('createE2BIsolateDriver', () => {
     expect(result.error?.message).toContain('code 3')
   })
 
+  // The memory test alone is not enough: whether its stderr arrives in a chunk
+  // without "heap out of memory" depends on pipe timing.
+  it('reports ordinary stderr on exit as an execution error, not a memory limit breach', async () => {
+    const { result } = await run(
+      "process.stderr.write('boom\\n', () => process.exit(2)); await new Promise(() => {})",
+    )
+    expect(result.error?.name).toBe('E2BExecutionError')
+    expect(result.error?.message).toContain('code 2')
+    expect(result.error?.message).toContain('stderr: boom')
+  })
+
   it('kills an in-flight execution on dispose and refuses new ones', async () => {
     const fake = localSandbox()
     const context = await createE2BIsolateDriver({

From 3fea32e9edca75d8b6a5f965d81aa07d75c9749b Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 19:46:30 +0200
Subject: [PATCH 274/286] fix(ai-harness, ai-code-mode): code mode asks
 permissions() which tools are safe

permissions() provides PermissionDecisionCapability, which decides a tool
with all rules in their order, the user rules last, and the default.
Code mode moves a tool into its isolate only when that answer is allow in
plan mode. So permissions({ default: 'ask' }) keeps a tool with no rule
out of code mode, and a looser rule from a plugin mounted later does not
move a tool that a user rule makes ask. Without permissions(), code mode
reads the PermissionRules list as before.
---
 docs/harness/code-mode.md                     |  5 ++
 docs/harness/permissions.md                   | 26 ++++++++
 packages/ai-code-mode/src/harness.ts          | 13 +++-
 packages/ai-code-mode/tests/harness.test.ts   | 37 ++++++++++++
 packages/ai-harness/src/first-party/index.ts  |  1 +
 .../ai-harness/src/first-party/permissions.ts | 28 +++++++--
 packages/ai-harness/src/index.ts              |  1 +
 packages/ai-harness/tests/permissions.test.ts | 59 +++++++++++++++++++
 8 files changed, 162 insertions(+), 8 deletions(-)

diff --git a/docs/harness/code-mode.md b/docs/harness/code-mode.md
index b3c962a9a4..a3e54768b4 100644
--- a/docs/harness/code-mode.md
+++ b/docs/harness/code-mode.md
@@ -74,6 +74,11 @@ A call inside the program does not stop for approval. So by default, a tool move
 - The permission rules allow it in plan mode. File reads move. `write_file` and `bash` stay.
 - MCP tools that the server does not mark read-only ask for approval, so they stay too.
 
+Where the permission rules come from:
+
+- With [`permissions()`](./permissions) in the plugin list, code mode asks it about each tool. The answer is the one a call gets in plan mode: your `rules` win, and a tool with no rule gets your `default`. So with `default: 'ask'`, a tool with no rule stays.
+- Without `permissions()`, code mode reads the rules that tool plugins add.
+
 Every other tool stays a normal tool call, with its approvals. To pick the tools yourself, pass `include`:
 
 ```ts group=harness-code-mode
diff --git a/docs/harness/permissions.md b/docs/harness/permissions.md
index 7684dc165e..538053ec84 100644
--- a/docs/harness/permissions.md
+++ b/docs/harness/permissions.md
@@ -298,6 +298,32 @@ Now `{ tool: 'copy_file', resource: 'docs/**', decision: 'allow' }` copies files
 - If a tool does not say what it touches, a rule with a `resource` counts for every call. So a `deny` for one folder denies every call of the tool.
 - [Code mode](./code-mode) keeps a tool with resources as a normal tool call, so the plugin still checks each call.
 
+## Ask for a decision from your plugin
+
+Your plugin must know what `permissions()` decides for a tool before the model calls it. Read the answer with `PermissionDecisionCapability`:
+
+```ts
+import { PermissionDecisionCapability, definePlugin } from '@tanstack/ai-harness'
+
+export const planTools = definePlugin({
+  name: 'acme/plan-tools',
+  optionalRequires: [PermissionDecisionCapability],
+  setup: (ctx) => ({
+    // Give the model only the tools that permissions() allows in plan mode.
+    prepareTools: ({ tools }) => {
+      const decide = ctx.getOptional(PermissionDecisionCapability)
+      if (!decide) return tools
+      return tools.filter((tool) => decide(tool.name, 'plan') === 'allow')
+    },
+  }),
+})
+```
+
+- The answer is `'allow'`, `'ask'`, or `'deny'`. It uses all rules in their order, your `rules` last, and your `default`.
+- Read it when the plugin runs, not in `setup`. Then `permissions()` can come before or after your plugin.
+- Saved `always` answers are not part of it. They can only allow, so a check that needs `'allow'` stays strict.
+- [Code mode](./code-mode) uses this answer. With `default: 'ask'`, a tool with no rule stays a normal tool call.
+
 ## Known limits
 
 - A rule that allows a tool with no `kind` also lets it run in `plan` mode. For example, an `allow` for `webfetch` lets it fetch pages in `plan` mode. `plan` denies only edits, commands, and calls that ask.
diff --git a/packages/ai-code-mode/src/harness.ts b/packages/ai-code-mode/src/harness.ts
index ddfa73acda..2185e5809e 100644
--- a/packages/ai-code-mode/src/harness.ts
+++ b/packages/ai-code-mode/src/harness.ts
@@ -1,4 +1,5 @@
 import {
+  PermissionDecisionCapability,
   PermissionResources,
   PermissionRules,
   decidePermission,
@@ -14,8 +15,9 @@ export interface CodeModePluginOptions extends Omit<
 > {
   /**
    * Which tools move into code mode. Default: every server tool that does
-   * not need approval and that the permission rules allow in plan mode (so
-   * no edits, no commands, nothing that asks first). A safe tool with
+   * not need approval and that `permissions()` allows in plan mode (so no
+   * edits, no commands, nothing that asks first). Without `permissions()`,
+   * the rules of tool plugins decide. A safe tool with
    * `metadata.codeMode: true`, for example a tool of an `mcp()` server with
    * `codeMode: true`, moves even when `include` does not pick it.
    */
@@ -77,6 +79,7 @@ export function codeMode(options: CodeModePluginOptions) {
   const { include, lazy = false, ...config } = options
   return definePlugin({
     name: 'tanstack/code-mode',
+    optionalRequires: [PermissionDecisionCapability],
     setup: (ctx) => {
       const rules = ctx.collect(PermissionRules)
       const resources = ctx.collect(PermissionResources)
@@ -85,9 +88,13 @@ export function codeMode(options: CodeModePluginOptions) {
       return {
         prompts: [{ id: 'tanstack/code-mode', text: () => prompt }],
         prepareTools: ({ tools }) => {
+          // Ask permissions() when it is mounted: it knows all rules in its
+          // order and its default. Read here, so it can come after code mode.
+          const decide = ctx.getOptional(PermissionDecisionCapability)
           const safe = (tool: CodeModeTool) =>
             !tool.needsApproval &&
-            decidePermission(rules, tool.name, 'plan') === 'allow'
+            (decide?.(tool.name, 'plan') ??
+              decidePermission(rules, tool.name, 'plan')) === 'allow'
           const moves = (tool: CodeModeTool) => {
             // The permission checks run on tool calls of the model. A call
             // inside the isolate skips them, so such a tool stays a tool call.
diff --git a/packages/ai-code-mode/tests/harness.test.ts b/packages/ai-code-mode/tests/harness.test.ts
index 606b449000..14b41a7901 100644
--- a/packages/ai-code-mode/tests/harness.test.ts
+++ b/packages/ai-code-mode/tests/harness.test.ts
@@ -427,6 +427,43 @@ describe('codeMode', () => {
     expect(names).toEqual(['docs_search', 'lookup', 'execute_typescript'])
   })
 
+  it.each(['before', 'after'])(
+    'keeps a tool with no rule as a tool call when permissions() asks by default, mounted %s code mode',
+    async (order) => {
+      const guard = permissions({
+        default: 'ask',
+        rules: [{ tool: 'lookup', decision: 'allow' }],
+      })
+      const code = codeMode({ driver: fakeDriver().driver })
+      const names = await firstToolNames({
+        tools: [markedTool('docs_search'), tools.lookup],
+        plugins: order === 'before' ? [guard, code] : [code, guard],
+      })
+      expect(names).toEqual(['docs_search', 'execute_typescript'])
+    },
+  )
+
+  it('keeps a tool that a rule of permissions() asks for, when a later plugin allows it', async () => {
+    const later = definePlugin({
+      name: 'test/later-allow',
+      setup: () => ({
+        contribute: [
+          PermissionRules.item({ tool: 'docs_search', decision: 'allow' }),
+        ],
+      }),
+    })
+    const names = await firstToolNames({
+      tools: [markedTool('docs_search'), tools.lookup],
+      plugins: [
+        permissions({ rules: [{ tool: 'docs_search', decision: 'ask' }] }),
+        later,
+        codeMode({ driver: fakeDriver().driver }),
+      ],
+    })
+    // permissions() checks its own rules last, so the call would ask.
+    expect(names).toEqual(['docs_search', 'execute_typescript'])
+  })
+
   it('keeps a tool that declares permission resources as a tool call', async () => {
     const resources = definePlugin({
       name: 'test/resources',
diff --git a/packages/ai-harness/src/first-party/index.ts b/packages/ai-harness/src/first-party/index.ts
index 7ebced7a39..95d285e1f8 100644
--- a/packages/ai-harness/src/first-party/index.ts
+++ b/packages/ai-harness/src/first-party/index.ts
@@ -3,6 +3,7 @@
 export { modelPicker } from './model-picker'
 export {
   PERMISSION_MODES,
+  PermissionDecisionCapability,
   PermissionResources,
   PermissionRules,
   decidePermission,
diff --git a/packages/ai-harness/src/first-party/permissions.ts b/packages/ai-harness/src/first-party/permissions.ts
index 030f356fd1..c2b22f4032 100644
--- a/packages/ai-harness/src/first-party/permissions.ts
+++ b/packages/ai-harness/src/first-party/permissions.ts
@@ -1,4 +1,4 @@
-import { getMetadata } from '@tanstack/ai'
+import { createCapability, getMetadata } from '@tanstack/ai'
 import { defineCommand } from '../commands'
 import { configOption } from '../config'
 import { createExtensionPoint } from '../extensions'
@@ -60,6 +60,16 @@ export const PERMISSION_MODES = [
 ] as const
 export type PermissionMode = (typeof PERMISSION_MODES)[number]
 
+/**
+ * What `permissions()` decides for a call of `tool` in `mode`, when the call
+ * declares no `PermissionResources`. It uses all rules in their order and the
+ * `default`. Other plugins, like `codeMode()`, ask it. Saved answers are not
+ * used: they only allow more, so an answer here is never looser than a call.
+ */
+export const PermissionDecisionCapability = createCapability<
+  (tool: string, mode: PermissionMode) => PermissionDecision
+>()('tanstack/permission-decision')
+
 /** Is the user's answer a yes: `true`, `y`, or `yes`? */
 export function isYes(answer: unknown) {
   return answer === true || /^y(es)?$/i.test(String(answer).trim())
@@ -392,9 +402,17 @@ export function permissions(
 ) {
   return definePlugin({
     name: 'tanstack/permissions',
+    provides: [PermissionDecisionCapability],
     setup: (ctx) => {
       const contributed = ctx.collect(PermissionRules)
       const declared = ctx.collect(PermissionResources)
+      // The rules of tool plugins, then the user's rules, so the user's win.
+      const configured = () => [...contributed, ...(options.rules ?? [])]
+      ctx.provide(PermissionDecisionCapability, (tool, current) =>
+        decidePermission(configured(), tool, current, {
+          fallback: options.default,
+        }),
+      )
       const mode = (): PermissionMode => {
         const value = ctx.config.get('mode')
         return (
@@ -470,12 +488,12 @@ export function permissions(
       ) => {
         const resources = resourcesOf(tool, input)
         const settings = { fallback: options.default, resources, root }
-        const configured = [...contributed, ...(options.rules ?? [])]
+        const rules = configured()
         // A saved answer turns an ask into an allow. It never beats a deny.
-        if (decidePermission(configured, tool, current, settings) === 'deny') {
+        if (decidePermission(rules, tool, current, settings) === 'deny') {
           return { decision: 'deny' as const, resources }
         }
-        const rules = [...configured, ...(await loadSaved(metadata))]
+        rules.push(...(await loadSaved(metadata)))
         const decision = decidePermission(rules, tool, current, settings)
         return { decision, resources }
       }
@@ -549,7 +567,7 @@ export function permissions(
           }),
         },
         prepareTools: ({ tools }) => {
-          const rules = [...contributed, ...(options.rules ?? [])]
+          const rules = configured()
           const current = mode()
           return tools.filter((tool) => !isHidden(rules, tool.name, current))
         },
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index c14a707229..39da2c7e34 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -44,6 +44,7 @@ export { createExtensionPoint, createPluginEvent } from './extensions'
 // Portable (no Node imports), so edge-safe plugins such as code mode can read
 // the permission rules and resources without the Node-only `./plugins` entry.
 export {
+  PermissionDecisionCapability,
   PermissionResources,
   PermissionRules,
   decidePermission,
diff --git a/packages/ai-harness/tests/permissions.test.ts b/packages/ai-harness/tests/permissions.test.ts
index 9028f00478..daabfd53aa 100644
--- a/packages/ai-harness/tests/permissions.test.ts
+++ b/packages/ai-harness/tests/permissions.test.ts
@@ -3,6 +3,7 @@ import { toolDefinition } from '@tanstack/ai'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { createHarnessHost, defineHarness, definePlugin } from '../src'
 import {
+  PermissionDecisionCapability,
   PermissionResources,
   PermissionRules,
   decidePermission,
@@ -11,6 +12,7 @@ import {
 import { mockAdapter, text, toolCall } from './helpers'
 import type { HarnessPersistence, HarnessPlugin, HarnessSession } from '../src'
 import type {
+  PermissionDecision,
   PermissionMode,
   PermissionRule,
 } from '../src/first-party/permissions'
@@ -486,6 +488,63 @@ describe('permissions()', () => {
     await host.close()
   })
 
+  it('tells other plugins the decision a call gets, for a rule, the default, and plan mode', async () => {
+    const ran: Array<string> = []
+    const tool = (name: string) =>
+      toolDefinition({ name, description: name }).server(async () => {
+        ran.push(name)
+        return `${name} done`
+      })
+    let decide:
+      | ((tool: string, mode: PermissionMode) => PermissionDecision)
+      | undefined
+    // Another plugin that asks permissions(), like codeMode() does.
+    const reader = definePlugin({
+      name: 'test/reader',
+      optionalRequires: [PermissionDecisionCapability],
+      setup: (ctx) => {
+        decide = ctx.getOptional(PermissionDecisionCapability)
+        return { tools: [tool('lookup'), tool('deploy')] }
+      },
+    })
+    const { host, session, calls } = await open(
+      memoryPersistence(),
+      [
+        permissions({
+          default: 'ask',
+          rules: [{ tool: 'lookup', decision: 'allow' }],
+        }),
+        reader,
+      ],
+      [
+        () => toolCall('lookup', {}, 'c1'),
+        () => toolCall('deploy', {}, 'c2'),
+        () => text('asked'),
+        () => toolCall('lookup', {}, 'c3'),
+        () => toolCall('deploy', {}, 'c4'),
+      ],
+    )
+
+    // The rule allows lookup, and deploy has no rule, so it asks.
+    const turn = session.prompt('look up, then deploy')
+    expect(await answer(session, { answer: 'reject' })).toContain('deploy')
+    await turn
+    expect(ran).toEqual(['lookup'])
+    expect(decide?.('lookup', 'default')).toBe('allow')
+    expect(decide?.('deploy', 'default')).toBe('ask')
+
+    // Plan mode denies what would ask.
+    await session.command('mode', 'plan')
+    await session.prompt('again, in plan mode')
+    expect(ran).toEqual(['lookup', 'lookup'])
+    expect(JSON.stringify(calls.at(-1).messages)).toContain(
+      'This tool is not allowed in plan mode.',
+    )
+    expect(decide?.('lookup', 'plan')).toBe('allow')
+    expect(decide?.('deploy', 'plan')).toBe('deny')
+    await host.close()
+  })
+
   it('never lets a saved answer beat a deny', async () => {
     const persistence = memoryPersistence()
     await persistence.stores.metadata.set(

From 41baf9c78e2f0d58c92a109a2c4e4cede40aa375 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 19:47:51 +0200
Subject: [PATCH 275/286] test(e2e): open a thread from a dashboard host row

With allowRemoteStart, a thread opened from the host row form gets a
message and answers. Without it, the first input shows the refusal.
---
 testing/e2e/tests/dashboard.spec.ts | 76 +++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)

diff --git a/testing/e2e/tests/dashboard.spec.ts b/testing/e2e/tests/dashboard.spec.ts
index 786a8f0363..340818f271 100644
--- a/testing/e2e/tests/dashboard.spec.ts
+++ b/testing/e2e/tests/dashboard.spec.ts
@@ -65,6 +65,36 @@ function echoAdapter(): AnyTextAdapter {
   }
 }
 
+/** Start a dashboard, and pair a host that lists no threads with it. */
+async function pairedHost(allowRemoteStart: boolean) {
+  const dashboard = await startDashboard({ port: 0 })
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const connection = await connectDashboard({
+    host,
+    harness: defineHarness({ name: 'acme/open-demo', adapter: echoAdapter() }),
+    url: dashboard.url,
+    allowRemoteStart,
+    onPairingCode: (code) =>
+      void fetch(`${dashboard.url}/api/pair/approve`, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${dashboard.ownerToken}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ code }),
+      }),
+  })
+  return {
+    host,
+    pageUrl: `${dashboard.url}/#token=${dashboard.ownerToken}`,
+    close: async () => {
+      connection.close()
+      await host.close()
+      await dashboard.close()
+    },
+  }
+}
+
 test.describe('dashboard', () => {
   test('a paired host shows up, and a prompt from a phone reaches it', async ({
     page,
@@ -121,4 +151,50 @@ test.describe('dashboard', () => {
       await dashboard.close()
     }
   })
+
+  test('a thread opened from a host row gets a message and answers', async ({
+    page,
+  }) => {
+    const { host, pageUrl, close } = await pairedHost(true)
+    try {
+      // The host refuses an input that comes before it attaches the thread.
+      const attached = (async () => {
+        for await (const event of host.events())
+          if (event.type === 'status' && event.threadId === 'fresh') return
+      })()
+      await page.goto(pageUrl)
+      await page.getByRole('textbox', { name: 'Thread id' }).fill('fresh')
+      await page.getByRole('button', { name: 'Open', exact: true }).click()
+      await expect(page.getByRole('heading', { name: 'fresh' })).toBeVisible()
+      await attached
+
+      await page.getByPlaceholder('Send a message').fill('hello from the view')
+      await page.getByRole('button', { name: 'Send' }).click()
+      await expect(
+        page.getByText('You said: hello from the view'),
+      ).toBeVisible()
+    } finally {
+      await close()
+    }
+  })
+
+  test('a host without allowRemoteStart refuses the first input', async ({
+    page,
+  }) => {
+    const { pageUrl, close } = await pairedHost(false)
+    try {
+      await page.goto(pageUrl)
+      await page.getByRole('textbox', { name: 'Thread id' }).fill('fresh')
+      await page.getByRole('button', { name: 'Open', exact: true }).click()
+      await expect(page.getByRole('heading', { name: 'fresh' })).toBeVisible()
+
+      await page.getByPlaceholder('Send a message').fill('hello')
+      await page.getByRole('button', { name: 'Send' }).click()
+      await expect(
+        page.getByText('Refused: remote_start_disabled'),
+      ).toBeVisible()
+    } finally {
+      await close()
+    }
+  })
 })

From 08db37475026ec561daa8f7cfc03cabddddf92f6 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 19:49:49 +0200
Subject: [PATCH 276/286] fix(ai-mcp): the harness MCP server lists only
 exposed commands

createHarnessMcpServer made a tool for every plugin command, so an MCP
client could run /mode bypass. It now makes command tools only for the
names in expose.commands, like the agents in expose.agents.

- The CLI and e2e harnesses expose the commands and config they use, and
  an e2e test checks that the rest is refused.
- The docs show expose where a client sends a command or config.
---
 docs/harness/agents.md                        |  2 +-
 docs/harness/auth.md                          |  4 +-
 docs/harness/cli.md                           |  2 +
 docs/harness/mcp-server.md                    |  4 +-
 docs/harness/snapshots.md                     |  2 +-
 docs/harness/thread-settings.md               |  2 +-
 packages/ai-harness-cli/tests/cli.test.ts     |  1 +
 packages/ai-mcp/src/harness.ts                | 10 ++-
 packages/ai-mcp/tests/harness.test.ts         | 63 ++++++++++++++++++-
 .../e2e/src/routes/api.harness-protocol.$.ts  |  9 ++-
 testing/e2e/tests/harness-protocol.spec.ts    | 26 ++++++++
 11 files changed, 115 insertions(+), 10 deletions(-)

diff --git a/docs/harness/agents.md b/docs/harness/agents.md
index 0cdec35659..0a149b1cb0 100644
--- a/docs/harness/agents.md
+++ b/docs/harness/agents.md
@@ -52,7 +52,7 @@ process.exitCode = await runCli(coder)
 - `/agent` alone shows the current agent and the list: `Agent: build. Agents: build, plan.`
 - A switch applies at the next turn.
 
-A client changes the `agent` setting. The [session view](./custom-ui) lists its options for a menu:
+A client can change the `agent` setting when the harness exposes it. Add `expose: { config: ['agent'] }` to `defineHarness` (see [Choose what clients can change](./connect#choose-what-clients-can-change)). The [session view](./custom-ui) lists the options for a menu:
 
 ```ts group=harness-agents-client
 import { createHarnessClient } from '@tanstack/ai-harness/client'
diff --git a/docs/harness/auth.md b/docs/harness/auth.md
index f9c7fa52e9..2b33a130ba 100644
--- a/docs/harness/auth.md
+++ b/docs/harness/auth.md
@@ -96,6 +96,8 @@ export const assistant = defineHarness({
   name: 'acme/assistant',
   adapter: openaiText('gpt-5.6'),
   plugins: () => [github],
+  // A web app starts the sign-in with this command.
+  expose: { commands: ['connect:github'] },
 })
 ```
 
@@ -111,7 +113,7 @@ When the credential is missing, the turn stops with an interrupt:
 - `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:
+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. 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'
diff --git a/docs/harness/cli.md b/docs/harness/cli.md
index 8c603a1f52..648a4fc766 100644
--- a/docs/harness/cli.md
+++ b/docs/harness/cli.md
@@ -57,6 +57,8 @@ To use the harness from another program:
 - `--mcp`: serve the harness as an MCP server over stdio, for Claude Code, Cursor, and other MCP clients. Needs `@tanstack/ai-mcp`. Add `--yes` to approve every tool call. Read [Use a harness from any MCP client](./mcp-server).
 - `--serve`: serve the session protocol over HTTP on `127.0.0.1:8787`. Every request needs the bearer token. Pass `--token`, set `HARNESS_TOKEN`, or copy the token the CLI prints. With `@tanstack/ai-mcp`, it also serves MCP at `/mcp`.
 
+`--mcp` and `--serve` run only the commands in `expose.commands` of the harness. `--serve` also sets only the config keys in `expose.config`. Add the names to `expose` in `defineHarness`, for example `expose: { commands: ['connect:github'] }`. Line mode and `-p` run every command. See [Choose what clients can change](./connect#choose-what-clients-can-change).
+
 Line mode reads one message or command per line and waits for each turn. It works the same in a terminal and with piped input. In a terminal, it also opens sign-in links in the browser.
 
 ## 3. Use it in CI
diff --git a/docs/harness/mcp-server.md b/docs/harness/mcp-server.md
index 852852ff3a..5afa5a973c 100644
--- a/docs/harness/mcp-server.md
+++ b/docs/harness/mcp-server.md
@@ -78,7 +78,9 @@ To answer the harness:
 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 plugin command. The command `connect:notion` becomes the tool `command_connect_notion`.
+- `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.
 
diff --git a/docs/harness/snapshots.md b/docs/harness/snapshots.md
index bc962505ee..c62cfb48d4 100644
--- a/docs/harness/snapshots.md
+++ b/docs/harness/snapshots.md
@@ -55,7 +55,7 @@ process.exitCode = await runCli(coder)
 - The snapshots skip the files that `.gitignore` names, like `node_modules`. `/undo` does not touch them.
 - A new turn clears `/redo`.
 
-In your own UI, call `client.command('undo')`. The result text arrives as a `harness.command.result` event.
+In your own UI, add `expose: { commands: ['undo', 'redo'] }` to `defineHarness`. A client can run only the commands that the harness exposes (see [Choose what clients can change](./connect#choose-what-clients-can-change)). Then call `client.command('undo')`. The result text arrives as a `harness.command.result` event.
 
 ## See what a step changed
 
diff --git a/docs/harness/thread-settings.md b/docs/harness/thread-settings.md
index 43a5988c63..6037fb62cc 100644
--- a/docs/harness/thread-settings.md
+++ b/docs/harness/thread-settings.md
@@ -72,7 +72,7 @@ An unknown field, model, or plugin, or a bad value, gets a receipt with `status:
 
 ## 3. Let the user pick
 
-A client can change only the fields in `expose.settings` of the harness. The harness above exposes `model` and `reasoning`.
+A client can change only the fields in `expose.settings` of the harness. The harness above exposes `model` and `reasoning`. [Choose what clients can change](./connect#choose-what-clients-can-change) lists the other `expose` fields.
 
 - A client input with another field gets `status: 'rejected'` with the reason `not_exposed`. Nothing changes.
 - With no `expose.settings`, a client can change no field.
diff --git a/packages/ai-harness-cli/tests/cli.test.ts b/packages/ai-harness-cli/tests/cli.test.ts
index a566f494ac..ca2f46c2de 100644
--- a/packages/ai-harness-cli/tests/cli.test.ts
+++ b/packages/ai-harness-cli/tests/cli.test.ts
@@ -453,6 +453,7 @@ describe('a host and a principal', () => {
         name: 'test/serve-principal',
         adapter: scripted([]).adapter,
         plugins: () => [providerKeys({ providers: [acme] })],
+        expose: { commands: ['connect:acme'] },
       }),
       port: 0,
       hostname: '127.0.0.1',
diff --git a/packages/ai-mcp/src/harness.ts b/packages/ai-mcp/src/harness.ts
index 1a89008301..737a29955e 100644
--- a/packages/ai-mcp/src/harness.ts
+++ b/packages/ai-mcp/src/harness.ts
@@ -150,7 +150,8 @@ const attachmentsSchema: JSONSchema = {
  *
  * 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.
+ * `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 })`.
  *
@@ -460,7 +461,12 @@ export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
       }),
   )
 
-  const commands = session.describe().commands
+  // 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({
diff --git a/packages/ai-mcp/tests/harness.test.ts b/packages/ai-mcp/tests/harness.test.ts
index 39681af237..8c925d80e9 100644
--- a/packages/ai-mcp/tests/harness.test.ts
+++ b/packages/ai-mcp/tests/harness.test.ts
@@ -425,7 +425,16 @@ async function harnessServer(
     adapter: model.adapter,
     tools: [remove, pickColor],
     agents: [pricer, broken, waiter],
-    expose: { agents: ['pricer', 'broken', 'waiter'] },
+    expose: {
+      agents: ['pricer', 'broken', 'waiter'],
+      commands: [
+        'confirm',
+        'connect:notion',
+        'fail',
+        'greet',
+        'release/v2.1-beta',
+      ],
+    },
     plugins: () => [commands],
     ...(reviewer === undefined
       ? {}
@@ -483,7 +492,7 @@ async function connect(
 }
 
 describe('createHarnessMcpServer', () => {
-  it('lists the control tools, one tool per exposed agent, and one per command', async () => {
+  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)
 
@@ -555,6 +564,7 @@ describe('createHarnessMcpServer', () => {
         name: 'test/clash',
         adapter: scripted([]).adapter,
         plugins: () => [clashing],
+        expose: { commands: ['connect_notion', 'connect:notion'] },
       }),
     )
     const { client } = await connect(server)
@@ -588,6 +598,55 @@ describe('createHarnessMcpServer', () => {
     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: {},
diff --git a/testing/e2e/src/routes/api.harness-protocol.$.ts b/testing/e2e/src/routes/api.harness-protocol.$.ts
index f319c970fc..1e60b67ba2 100644
--- a/testing/e2e/src/routes/api.harness-protocol.$.ts
+++ b/testing/e2e/src/routes/api.harness-protocol.$.ts
@@ -120,7 +120,14 @@ function harnessFor(request: Request) {
         run: async (ctx) => ctx.input.text,
       }),
     ],
-    expose: { agents: ['echo'], settings: ['model', 'instructions'] },
+    // `mode` of `permissions()` stays on the server, so a client cannot pick
+    // `bypass`.
+    expose: {
+      agents: ['echo'],
+      settings: ['model', 'instructions'],
+      config: ['tone'],
+      commands: ['greet'],
+    },
     plugins: () => [
       ...asks,
       todos(),
diff --git a/testing/e2e/tests/harness-protocol.spec.ts b/testing/e2e/tests/harness-protocol.spec.ts
index 6b856de9e8..35c76674fd 100644
--- a/testing/e2e/tests/harness-protocol.spec.ts
+++ b/testing/e2e/tests/harness-protocol.spec.ts
@@ -95,6 +95,32 @@ test.describe('harness protocol', () => {
     expect(command.operationId).toMatch(/^op-command-/)
   })
 
+  test('refuses a command and a config key that the harness does not expose', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    // `x-harness-permissions: 1` adds `permissions()`, so `mode` exists.
+    const control = async (input: unknown) =>
+      (
+        await request.post('/api/harness-protocol/control', {
+          headers: {
+            ...headers(testId, aimockPort),
+            'x-harness-permissions': '1',
+            '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,

From d59df51e6792338ad4acb06613c0d810bf8746bb Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 19:50:33 +0200
Subject: [PATCH 277/286] docs: update the dates of the pages that changed
 after the nav pass

connect, custom-ui, code-mode, auth, cli, and mcp-server got content
about expose and the code mode decision.
---
 docs/config.json | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/config.json b/docs/config.json
index b18c1c6eda..b22802ff40 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -899,7 +899,7 @@
           "label": "Connect clients",
           "to": "harness/connect",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-10-05"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Send and show media",
@@ -910,7 +910,7 @@
           "label": "Run in the terminal",
           "to": "harness/cli",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-10-05"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Durable sessions",
@@ -1015,7 +1015,7 @@
           "label": "Auth and connectors",
           "to": "harness/auth",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-10-05"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Share a thread between people",
@@ -1038,13 +1038,13 @@
           "label": "Use from any MCP client",
           "to": "harness/mcp-server",
           "addedAt": "2026-09-28",
-          "updatedAt": "2026-09-29"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Code mode in a harness",
           "to": "harness/code-mode",
           "addedAt": "2026-09-26",
-          "updatedAt": "2026-10-01"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Add skills",
@@ -1065,7 +1065,7 @@
           "label": "Build your own UI",
           "to": "harness/custom-ui",
           "addedAt": "2026-09-28",
-          "updatedAt": "2026-10-05"
+          "updatedAt": "2026-10-06"
         },
         {
           "label": "Run agents from a harness",

From 6b42bb37ccc7bbcebb53cfc644c33aea2daa4255 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 19:52:40 +0200
Subject: [PATCH 278/286] fix(ai-dashboard): an input that arrives while its
 thread opens waits

The host refused an input with remote_start_disabled when it came in
while host.open() for that thread still ran, even with allowRemoteStart.
The host now keeps one open per thread, and frames for that thread wait
for it. Two subscribe frames for one thread also no longer send each event
twice.
---
 packages/ai-dashboard/src/connect.ts      | 23 ++++++++---
 packages/ai-dashboard/tests/relay.test.ts | 47 +++++++++++++++++++++++
 2 files changed, 64 insertions(+), 6 deletions(-)

diff --git a/packages/ai-dashboard/src/connect.ts b/packages/ai-dashboard/src/connect.ts
index 98eda603aa..cc36f1e916 100644
--- a/packages/ai-dashboard/src/connect.ts
+++ b/packages/ai-dashboard/src/connect.ts
@@ -130,12 +130,9 @@ export async function connectDashboard(options: ConnectDashboardOptions) {
   }
   await hello()
 
-  const attached = new Map<string, HarnessSession>()
-  const attach = async (threadId: string): Promise<HarnessSession> => {
-    const existing = attached.get(threadId)
-    if (existing) return existing
+  /** Open a thread and send its events to the dashboard. */
+  const open = async (threadId: string): Promise<HarnessSession> => {
     const session = await options.host.open(options.harness, { threadId })
-    attached.set(threadId, session)
     // Batch events so a streaming answer is a few requests, not one per token.
     let pending: Array<unknown> = []
     let timer: ReturnType<typeof setTimeout> | undefined
@@ -162,6 +159,19 @@ export async function connectDashboard(options: ConnectDashboardOptions) {
     })()
     return session
   }
+  // Keep the open while it runs, so a frame that comes before it ends waits
+  // for it, and a second attach does not open the thread again.
+  const attached = new Map<string, Promise<HarnessSession>>()
+  const attach = (threadId: string): Promise<HarnessSession> => {
+    const existing = attached.get(threadId)
+    if (existing) return existing
+    const opening = open(threadId)
+    attached.set(threadId, opening)
+    // A failed open leaves no entry. Its inputs are refused, and a later
+    // open tries again.
+    opening.catch(() => attached.delete(threadId))
+    return opening
+  }
   for (const threadId of options.threads ?? []) await attach(threadId)
 
   const handle = async (envelope: unknown) => {
@@ -177,7 +187,8 @@ export async function connectDashboard(options: ConnectDashboardOptions) {
         await attach(threadId)
       return
     }
-    const session = attached.get(threadId)
+    // Wait for an open that still runs. A failed open refuses the input.
+    const session = await attached.get(threadId)?.catch(() => undefined)
     if (!session) {
       if (
         frame.type === 'harness.input' &&
diff --git a/packages/ai-dashboard/tests/relay.test.ts b/packages/ai-dashboard/tests/relay.test.ts
index 51969acf41..3c62faefa4 100644
--- a/packages/ai-dashboard/tests/relay.test.ts
+++ b/packages/ai-dashboard/tests/relay.test.ts
@@ -266,6 +266,53 @@ describe('dashboard relay', () => {
     },
   )
 
+  it(
+    'sends an input that arrives while the thread still opens',
+    { timeout: 20_000 },
+    async () => {
+      const dashboard = await startDashboard({ port: 0 })
+      cleanups.push(() => dashboard.close())
+      const { host, hostId, owner } = await onlineHost(dashboard, true)
+      // Hold the open of `fresh` until the host opens `marker`. The relay
+      // sends frames in order, so the host has the input for `fresh` before
+      // it opens `marker`.
+      let openMarker = () => {}
+      const markerOpened = new Promise<void>((resolve) => {
+        openMarker = resolve
+      })
+      const open = host.open.bind(host)
+      host.open = async (harness, options) => {
+        if (options.threadId === 'marker') openMarker()
+        else await markerOpened
+        return open(harness, options)
+      }
+      const session = `${dashboard.url}/api/sessions/${hostId}/fresh`
+      const until = await openEvents(
+        `${session}/events?token=${dashboard.ownerToken}`,
+      )
+
+      // Open the thread and send a prompt at once, with no wait between.
+      await fetch(`${session}/open`, { method: 'POST', headers: owner })
+      await fetch(`${session}/input`, {
+        method: 'POST',
+        headers: owner,
+        body: JSON.stringify({ input: { op: 'prompt', message: 'hi' } }),
+      })
+      await fetch(`${dashboard.url}/api/sessions/${hostId}/marker/open`, {
+        method: 'POST',
+        headers: owner,
+      })
+
+      expect(await until('harness.receipt')).toContainEqual(
+        expect.objectContaining({
+          type: 'harness.receipt',
+          status: 'accepted',
+        }),
+      )
+      expect(await until('harness.operation.finished')).toContainEqual(answered)
+    },
+  )
+
   it(
     'refuses inputs to a thread the host does not let the dashboard start',
     { timeout: 20_000 },

From e8cedb2d00b6a63188c792f21f336a185881a009 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 19:57:10 +0200
Subject: [PATCH 279/286] fix(ai-dashboard): report a frame the host cannot
 handle

The host control loop did not catch an error from a frame, so a thread
that could not open became an unhandled rejection that could stop the
process. The error now goes to onError, and the connection stays. The
receipts and error frames also carry the harness name, so a refused thread
shows its harness in the sessions list.
---
 docs/harness/dashboard.md                 |  4 ++-
 packages/ai-dashboard/README.md           |  4 ++-
 packages/ai-dashboard/src/connect.ts      | 17 +++++++++--
 packages/ai-dashboard/tests/relay.test.ts | 35 +++++++++++++++++++++++
 4 files changed, 56 insertions(+), 4 deletions(-)

diff --git a/docs/harness/dashboard.md b/docs/harness/dashboard.md
index 9958fb5d7f..2e898f305c 100644
--- a/docs/harness/dashboard.md
+++ b/docs/harness/dashboard.md
@@ -123,10 +123,12 @@ const strict = await connectDashboard({
   harness: studio,
   url: 'http://127.0.0.1:8790',
   token: savedToken,
-  onError: (error) => console.error(`Pair this host again: ${error.message}`),
+  onError: (error) => console.error(`Dashboard: ${error.message}`),
 })
 ```
 
+`onError` also gets an error when the agent cannot handle a frame from the dashboard, for example when a thread cannot open. Then the connection stays.
+
 `connection.token` always holds the current host token. It changes when the agent pairs again.
 
 A revoked host also gets a `401`. If it has `onPairingCode`, it asks to pair again, and a new request shows under "Pairing requests". If you do not approve the request, the host does not connect. Each request expires after 10 minutes, and then the host asks again. To stop the requests, call `connection.close()` on that host, or stop the agent.
diff --git a/packages/ai-dashboard/README.md b/packages/ai-dashboard/README.md
index 5065313dab..ec4e0dbc7f 100644
--- a/packages/ai-dashboard/README.md
+++ b/packages/ai-dashboard/README.md
@@ -60,10 +60,12 @@ const connection = await connectDashboard({
   harness: studio,
   url: 'http://127.0.0.1:8790',
   token: savedToken,
-  onError: (error) => console.error(`Pair this host again: ${error.message}`),
+  onError: (error) => console.error(`Dashboard: ${error.message}`),
 })
 ```
 
+`onError` also gets an error when the agent cannot handle a frame from the dashboard, for example when a thread cannot open. Then the connection stays.
+
 `connection.token` always holds the current host token.
 
 ## Documentation
diff --git a/packages/ai-dashboard/src/connect.ts b/packages/ai-dashboard/src/connect.ts
index cc36f1e916..c1347704bf 100644
--- a/packages/ai-dashboard/src/connect.ts
+++ b/packages/ai-dashboard/src/connect.ts
@@ -22,7 +22,10 @@ export interface ConnectDashboardOptions {
   onPairingCode?: (code: string) => void
   /** Called with the new host token after pairing. Save it to skip pairing next time. */
   onToken?: (token: string) => void
-  /** Called when the dashboard refuses the host token and `onPairingCode` is not set. The connection stops. */
+  /**
+   * Called when the dashboard refuses the host token and `onPairingCode` is not set. The connection stops.
+   * Also called when the host fails to handle a frame from the dashboard, for example when a thread does not open. The connection stays.
+   */
   onError?: (error: Error) => void
   fetch?: typeof fetch
   /** Wait between reconnects, doubled up to 30 s. Default 1000 ms. */
@@ -196,6 +199,7 @@ export async function connectDashboard(options: ConnectDashboardOptions) {
       ) {
         await post('/api/host/frames', {
           threadId,
+          harness: options.harness.name,
           frames: [
             {
               type: 'harness.receipt',
@@ -217,6 +221,7 @@ export async function connectDashboard(options: ConnectDashboardOptions) {
         )
         await post('/api/host/frames', {
           threadId,
+          harness: options.harness.name,
           frames: [
             { type: 'harness.receipt', requestId: frame.requestId, ...receipt },
           ],
@@ -224,6 +229,7 @@ export async function connectDashboard(options: ConnectDashboardOptions) {
       } catch (error) {
         await post('/api/host/frames', {
           threadId,
+          harness: options.harness.name,
           frames: [
             {
               type: 'harness.error',
@@ -248,7 +254,14 @@ export async function connectDashboard(options: ConnectDashboardOptions) {
           await hello()
         } else {
           delay = options.reconnectDelayMs ?? 1000
-          for await (const envelope of sseData(response)) void handle(envelope)
+          for await (const envelope of sseData(response)) {
+            // A frame that fails does not stop the host. Report it.
+            void handle(envelope).catch((error: unknown) =>
+              options.onError?.(
+                error instanceof Error ? error : new Error(String(error)),
+              ),
+            )
+          }
         }
       } catch {
         if (stopped.signal.aborted) return
diff --git a/packages/ai-dashboard/tests/relay.test.ts b/packages/ai-dashboard/tests/relay.test.ts
index 3c62faefa4..1f91c3f0ba 100644
--- a/packages/ai-dashboard/tests/relay.test.ts
+++ b/packages/ai-dashboard/tests/relay.test.ts
@@ -100,6 +100,7 @@ async function openEvents(url: string) {
 async function onlineHost(
   dashboard: { url: string; ownerToken: string },
   allowRemoteStart: boolean,
+  onError?: (error: Error) => void,
 ) {
   const owner = {
     Authorization: `Bearer ${dashboard.ownerToken}`,
@@ -129,6 +130,7 @@ async function onlineHost(
     url: dashboard.url,
     token,
     allowRemoteStart,
+    onError,
   })
   cleanups.push(() => connection.close())
   await vi.waitFor(async () => {
@@ -313,6 +315,32 @@ describe('dashboard relay', () => {
     },
   )
 
+  it(
+    'reports a frame that the host fails to handle',
+    { timeout: 20_000 },
+    async () => {
+      const dashboard = await startDashboard({ port: 0 })
+      cleanups.push(() => dashboard.close())
+      const errors: Array<Error> = []
+      const { host, hostId, owner } = await onlineHost(
+        dashboard,
+        true,
+        (error) => errors.push(error),
+      )
+      host.open = () => Promise.reject(new Error('The thread cannot open.'))
+
+      await fetch(`${dashboard.url}/api/sessions/${hostId}/broken/open`, {
+        method: 'POST',
+        headers: owner,
+      })
+      await vi.waitFor(() =>
+        expect(errors.map((error) => error.message)).toEqual([
+          'The thread cannot open.',
+        ]),
+      )
+    },
+  )
+
   it(
     'refuses inputs to a thread the host does not let the dashboard start',
     { timeout: 20_000 },
@@ -345,6 +373,13 @@ describe('dashboard relay', () => {
           reason: 'remote_start_disabled',
         }),
       )
+      // The sessions list names the harness of the refused thread.
+      const sessions = await (
+        await fetch(`${dashboard.url}/api/sessions`, { headers: owner })
+      ).json()
+      expect(sessions).toMatchObject([
+        { threadId: 'fresh', harness: 'acme/remote' },
+      ])
     },
   )
 

From 065b91d712b48de17ae8280fdccd52945ca56fa6 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 19:59:22 +0200
Subject: [PATCH 280/286] chore: changesets for the opencode primitives

Core, adapters, harness, and dashboard. The plugins changeset now says that
workspaceTools is in the plugins/coding entry.
---
 .changeset/harness-p3-plugins.md            |  2 +-
 .changeset/opencode-primitives-adapters.md  | 15 +++++++++++++++
 .changeset/opencode-primitives-core.md      | 12 ++++++++++++
 .changeset/opencode-primitives-dashboard.md |  9 +++++++++
 .changeset/opencode-primitives-harness.md   | 19 +++++++++++++++++++
 5 files changed, 56 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/opencode-primitives-adapters.md
 create mode 100644 .changeset/opencode-primitives-core.md
 create mode 100644 .changeset/opencode-primitives-dashboard.md
 create mode 100644 .changeset/opencode-primitives-harness.md

diff --git a/.changeset/harness-p3-plugins.md b/.changeset/harness-p3-plugins.md
index 54c883daa5..7f03d928e3 100644
--- a/.changeset/harness-p3-plugins.md
+++ b/.changeset/harness-p3-plugins.md
@@ -10,6 +10,6 @@ Harness plugins can now do everything a Claude Code style agent needs.
 - **Plugin API.** `setup` can return `commands` (`defineCommand`, with typed input), `config` (`configOption.select`, `.boolean`, `.text`, `.number`), `contribute` for extension points (`createExtensionPoint`), and `adapter` to pick the main model. The setup context adds `collect`, typed events (`createPluginEvent`, `emit`, `on`), `state` (saved in the metadata store, published as `STATE_SNAPSHOT`), `config`, `credentials`, and `session` (`ask`, `prompt`, `transcript`, `setConfig`). Prompts can be functions called for each turn.
 - **Session.** `session.command`, `session.commands`, `session.setConfig`, `session.config`, `session.answer`, and `session.inspect`. The protocol accepts `command`, `answer`, and `config` inputs.
 - **Auth.** `oauthConnector` adds `connect:<id>` and `disconnect:<id>` commands and gives tools a fresh token. The OAuth runner (`loopbackLogin`, `deviceLogin`, `createPkce`, `exchangeCode`, `refreshCredential`) uses PKCE S256 and a single-use loopback on `127.0.0.1`. Tools that need a missing credential emit `harness.auth_required`.
-- **First-party plugins** in `@tanstack/ai-harness/plugins`: `permissions` (with `default`, `plan`, `acceptEdits`, and `bypass` modes and the `PermissionRules` extension point), `workspaceTools`, `todos`, `modelPicker`, `projectInstructions`, `fileCommands`, `compact`, and `usage`.
+- **First-party plugins** in `@tanstack/ai-harness/plugins`: `permissions` (with `default`, `plan`, `acceptEdits`, and `bypass` modes and the `PermissionRules` extension point), `todos`, `modelPicker`, `projectInstructions`, `fileCommands`, `compact`, and `usage`. `workspaceTools` is in the Node entry `@tanstack/ai-harness/plugins/coding`.
 - **`@tanstack/ai-persistence`** adds the optional `credentials` store (`CredentialStore`, `defineCredentialStore`) and compare-and-set on the memory metadata store. **`@tanstack/ai`** adds optional `getVersioned` and `setIf` to `MetadataStore`.
 - **CLI.** Plugin commands, `/config`, `/connect`, and `/disconnect`. Questions from plugins are answered on the next line. Sign-in links open in the browser.
diff --git a/.changeset/opencode-primitives-adapters.md b/.changeset/opencode-primitives-adapters.md
new file mode 100644
index 0000000000..b8ed7b9bd7
--- /dev/null
+++ b/.changeset/opencode-primitives-adapters.md
@@ -0,0 +1,15 @@
+---
+'@tanstack/ai-anthropic': patch
+'@tanstack/ai-bedrock': patch
+'@tanstack/ai-gemini': patch
+'@tanstack/ai-grok': patch
+'@tanstack/ai-mistral': patch
+'@tanstack/ai-openrouter': patch
+---
+
+Send `chat({ toolChoice })` to each provider.
+
+- **Anthropic and Bedrock Converse.** Claude Fable 5.1, Mythos 5.1, Opus 5.5, and Sonnet 5.5 reject a forced tool, and every Claude model rejects one while thinking is on. On those, `'required'` and a named tool fall back to `auto`.
+- **Bedrock Converse** has no `none`. `'none'` sends no tool config, except after tool calls in the history: then it sends the tools with `auto`, because Bedrock needs a tool config there.
+- **Gemini** maps the choice to `functionCallingConfig` (`AUTO`, `NONE`, `ANY`, and `allowedFunctionNames`). With only provider tools, such as Google Search, it sends no tool config.
+- **Grok, Mistral, and OpenRouter** (Chat Completions and Responses) send their own `tool_choice` shape.
diff --git a/.changeset/opencode-primitives-core.md b/.changeset/opencode-primitives-core.md
new file mode 100644
index 0000000000..9458dd4a95
--- /dev/null
+++ b/.changeset/opencode-primitives-core.md
@@ -0,0 +1,12 @@
+---
+'@tanstack/ai': minor
+'@tanstack/openai-base': minor
+---
+
+New `chat()` options for coding agents.
+
+- **`toolChoice`.** `chat({ toolChoice })` takes `'auto'`, `'none'`, `'required'`, or `{ type: 'tool', name }`. A middleware can change it for one model call. A tool choice in `modelOptions` wins. No tool choice goes out when the request has no tools.
+- **`replaceResult`.** `onAfterToolCall` can return `{ type: 'replaceResult', result }` to change the result that the client and the next model call see. Several middlewares chain.
+- **`toolExecution`.** `'parallel'` (the default) or `'sequential'`. With `'sequential'`, each tool call ends before the next one starts.
+- **One subagent tool.** With `subagents: { tool: 'single' }`, the model picks an agent by name in one `subagent` tool. An agent with an `inputSchema` takes `input`, and an agent without one takes an optional `prompt`. A `sessionId` continues an earlier child (with `withPersistence`), and `background` runs the child in the background.
+- **`@tanstack/openai-base`** sends `tool_choice` from Chat Completions and Responses, and exports `toChatCompletionsToolChoice` and `toResponsesToolChoice`.
diff --git a/.changeset/opencode-primitives-dashboard.md b/.changeset/opencode-primitives-dashboard.md
new file mode 100644
index 0000000000..c7333c50e1
--- /dev/null
+++ b/.changeset/opencode-primitives-dashboard.md
@@ -0,0 +1,9 @@
+---
+'@tanstack/ai-dashboard': minor
+---
+
+The dashboard host recovers from a restart, and the page opens threads.
+
+- **Pair again.** After a dashboard restart, a saved host token gets a `401`. With `onPairingCode`, the host pairs again and calls `onToken` with the new token. Without it, the new `onError` option gets the error. `connection.token` holds the current token.
+- **`onError`** also gets an error when the host cannot handle a frame, for example when a thread cannot open. The connection stays.
+- **Open a thread.** Each host row on the page has an "Open a thread" form. The host must set `allowRemoteStart`. A message sent right after the open waits for the thread, and a refused thread keeps its harness name in the sessions list.
diff --git a/.changeset/opencode-primitives-harness.md b/.changeset/opencode-primitives-harness.md
new file mode 100644
index 0000000000..88589e033c
--- /dev/null
+++ b/.changeset/opencode-primitives-harness.md
@@ -0,0 +1,19 @@
+---
+'@tanstack/ai-harness': minor
+'@tanstack/ai-persistence': minor
+'@tanstack/ai-sandbox': minor
+'@tanstack/ai-mcp': minor
+'@tanstack/ai-code-mode': minor
+---
+
+Session lists, coding tools, and safer clients for the harness.
+
+- **Session index.** `host.sessions` lists, renames, deletes, and forks sessions (`fork(harness, threadId, { before | through })`). `host.fork` takes `at: null` to copy no messages. `host.events()` is a status feed (`running`, `waiting`, `idle`). Over HTTP: `GET sessions`, `POST sessions`, and `GET host-events`. Subagent runs show up as child sessions of their thread. `@tanstack/ai-persistence` adds the `SessionIndexStore` contract, a memory store, and conformance tests.
+- **Waiting inputs.** `session.inputs()` lists them. The `cancelInput` and `setDelivery` inputs cancel one or move it between steer and queue.
+- **Coding tools** in the new Node entry `@tanstack/ai-harness/plugins/coding`: `workspaceTools` (moved here) gives `read_file` (text pages, images, PDFs), `write_file`, `edit_file` or `patch` (`editStyle`), `list_files`, `grep`, `bash` (with `background`), `webfetch`, and `websearch`. A `WorkspaceBackend` runs them on the host or in a sandbox (`sandboxWorkspaceBackend` from `@tanstack/ai-sandbox/harness`). Also new here: `snapshots()` with `/undo` and `/redo`, and `formatter()`. `@vscode/ripgrep` and `turndown` are optional peers.
+- **More plugins** in `@tanstack/ai-harness/plugins`: `agents()` (profiles, Markdown agents, `/agent`, and a step limit), `question()`, `title()`, and `boundToolOutput`. `projectInstructions()` reads up to the repo root and adds an environment block. `usage()` shows `session.usage()` and prices only the calls with no provider cost.
+- **Permissions.** Rules can match the paths and commands that a call touches (`PermissionResources`). Questions take once, always, or reject with a message. The rules apply in subagent runs too. `webfetch` asks by default. `PermissionDecisionCapability` lets other plugins ask what `permissions()` decides, and code mode uses it.
+- **Clients set only what you expose.** `defineHarness({ expose: { config, commands } })`. A client config input or command outside these lists gets `not_exposed`, so a client cannot switch the permission mode to `bypass`. Nothing is exposed by default, and server code is not affected. The harness MCP server also makes tools only for exposed commands.
+- **`mcp()` harness plugin** in `@tanstack/ai-mcp/harness`: MCP servers by name, tools named `<server>_<tool>`, `/mcp` status, and `codeMode: true`.
+- **Code mode** moves a tool marked `metadata.codeMode` only when `permissions()` allows it in plan mode, and never moves a tool that declares permission resources.
+- **Plugin API.** `ctx.session.note(text, { wake })`, `ctx.session.entry()` and `updateEntry(patch)`, `prepareTools({ tools, model })`, and the `WorkspaceHooks` extension point. `ctx.collect()` now works with every array method.

From ab9c6bb3ce781a5b87da63b09fbc105f9592ffc8 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 20:00:01 +0200
Subject: [PATCH 281/286] test(e2e): continue a subagent by its sessionId

With the single subagent tool, the model starts a child, then continues the
same child by its sessionId. The child gets its earlier messages, and the
parent gets both results. A route middleware puts the real child id into
the second call, because a fixture cannot know it.
---
 .../e2e/fixtures/subagents/single-tool.json   | 59 +++++++++++++++++++
 testing/e2e/src/lib/subagents-test.ts         |  5 +-
 testing/e2e/src/routes/api.subagents-test.ts  | 59 ++++++++++++++++++-
 testing/e2e/tests/subagents.spec.ts           | 28 ++++++++-
 4 files changed, 148 insertions(+), 3 deletions(-)
 create mode 100644 testing/e2e/fixtures/subagents/single-tool.json

diff --git a/testing/e2e/fixtures/subagents/single-tool.json b/testing/e2e/fixtures/subagents/single-tool.json
new file mode 100644
index 0000000000..6c3a892105
--- /dev/null
+++ b/testing/e2e/fixtures/subagents/single-tool.json
@@ -0,0 +1,59 @@
+{
+  "fixtures": [
+    {
+      "match": {
+        "userMessage": "[subagent-session] take squid notes",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "subagent",
+            "arguments": "{\"agent\":\"researcher\",\"prompt\":\"[subagent-session-task] Note one squid fact.\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[subagent-session-task] Note one squid fact.",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "content": "Squids have three hearts."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[subagent-session] take squid notes",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "subagent",
+            "arguments": "{\"agent\":\"researcher\",\"sessionId\":\"first-child\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[subagent-session-task] Note one squid fact.",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Squids also have blue blood."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[subagent-session] take squid notes",
+        "sequenceIndex": 2
+      },
+      "response": {
+        "content": "Both notes are ready."
+      }
+    }
+  ]
+}
diff --git a/testing/e2e/src/lib/subagents-test.ts b/testing/e2e/src/lib/subagents-test.ts
index 1b50135a93..8130d06678 100644
--- a/testing/e2e/src/lib/subagents-test.ts
+++ b/testing/e2e/src/lib/subagents-test.ts
@@ -24,6 +24,7 @@ export type SubagentScenario =
   | 'tool'
   | 'brief'
   | 'result'
+  | 'session'
 
 /** The user message for each scenario. It matches `fixtures/subagents`. */
 export const SUBAGENT_PROMPTS: Record<SubagentScenario, string> = {
@@ -32,6 +33,7 @@ export const SUBAGENT_PROMPTS: Record<SubagentScenario, string> = {
   tool: '[subagent-tool] research squids',
   brief: '[subagent-brief] compare squid facts',
   result: '[subagent-result] price vendor a',
+  session: '[subagent-session] take squid notes',
 }
 
 export function isSubagentScenario(value: unknown): value is SubagentScenario {
@@ -40,6 +42,7 @@ export function isSubagentScenario(value: unknown): value is SubagentScenario {
     value === 'approval' ||
     value === 'tool' ||
     value === 'brief' ||
-    value === 'result'
+    value === 'result' ||
+    value === 'session'
   )
 }
diff --git a/testing/e2e/src/routes/api.subagents-test.ts b/testing/e2e/src/routes/api.subagents-test.ts
index b6306745ce..de9d71b5b0 100644
--- a/testing/e2e/src/routes/api.subagents-test.ts
+++ b/testing/e2e/src/routes/api.subagents-test.ts
@@ -6,8 +6,14 @@ import {
   maxIterations,
   toServerSentEventsResponse,
 } from '@tanstack/ai'
+import { memoryPersistence, withPersistence } from '@tanstack/ai-persistence'
 import { z } from 'zod'
-import type { DefinedAgent, ReasoningRequest, Tool } from '@tanstack/ai'
+import type {
+  ChatMiddleware,
+  DefinedAgent,
+  ReasoningRequest,
+  Tool,
+} from '@tanstack/ai'
 import { createTextAdapter } from '@/lib/providers'
 import {
   deleteLogs,
@@ -33,6 +39,9 @@ import type { SubagentScenario } from '@/lib/subagents-test'
  * - `result`: no router. `pricer` calls the bound `ctx.chat` with
  *   `stream: false`, so its `run` resolves to a string. The string streams as
  *   the child's text and goes back to the parent model as the result.
+ * - `session`: no router, one `subagent` tool. The parent model starts
+ *   `researcher`, then a second call continues it by its `sessionId`.
+ *   `withPersistence` stores the child, so that call loads its transcript.
  */
 function subagentsFor(
   scenario: SubagentScenario,
@@ -113,9 +122,48 @@ function subagentsFor(
     const agents: Array<DefinedAgent> = [pricer]
     return { agents }
   }
+  if (scenario === 'session') {
+    return { agents: [child('researcher', [])], tool: 'single' as const }
+  }
   return { agents: [child('researcher', [])] }
 }
 
+/**
+ * aimock replies are fixed, so the second `subagent` call in
+ * `fixtures/subagents/single-tool.json` cannot hold the random id of the
+ * first child. It sends `sessionId: 'first-child'`. This middleware does what
+ * a real model does: it copies the `subagentRunId` of the first result.
+ */
+function fillSessionId(): ChatMiddleware {
+  let first: string | undefined
+  return {
+    name: 'fill-session-id',
+    onAfterToolCall(_ctx, { result }) {
+      if (
+        first === undefined &&
+        typeof result === 'object' &&
+        result !== null &&
+        'subagentRunId' in result &&
+        typeof result.subagentRunId === 'string'
+      ) {
+        first = result.subagentRunId
+      }
+    },
+    onBeforeToolCall(_ctx, { args }) {
+      if (
+        first === undefined ||
+        typeof args !== 'object' ||
+        args === null ||
+        !('sessionId' in args) ||
+        args.sessionId !== 'first-child'
+      ) {
+        return undefined
+      }
+      return { type: 'transformArgs', args: { ...args, sessionId: first } }
+    },
+  }
+}
+
 export const Route = createFileRoute('/api/subagents-test')({
   server: {
     handlers: {
@@ -147,6 +195,15 @@ export const Route = createFileRoute('/api/subagents-test')({
             ...(params.parentRunId ? { parentRunId: params.parentRunId } : {}),
             ...(params.resume ? { resume: params.resume } : {}),
             subagents: subagentsFor(scenario, aimockPort, testId),
+            // One run holds both calls, so a store per request is enough.
+            ...(scenario === 'session'
+              ? {
+                  middleware: [
+                    withPersistence(memoryPersistence()),
+                    fillSessionId(),
+                  ],
+                }
+              : {}),
             agentLoopStrategy: maxIterations(4),
             abortController,
           })
diff --git a/testing/e2e/tests/subagents.spec.ts b/testing/e2e/tests/subagents.spec.ts
index c596063fe6..bfaf2e1dbb 100644
--- a/testing/e2e/tests/subagents.spec.ts
+++ b/testing/e2e/tests/subagents.spec.ts
@@ -14,7 +14,7 @@ async function run(page: Page) {
 
 function open(
   page: Page,
-  scenario: 'route' | 'approval' | 'tool' | 'brief' | 'result',
+  scenario: 'route' | 'approval' | 'tool' | 'brief' | 'result' | 'session',
   testId: string,
   aimockPort: number,
 ) {
@@ -149,4 +149,30 @@ test.describe('subagents', () => {
       'text:Vendor A costs 42 EUR.',
     )
   })
+
+  test('the single subagent tool continues a child by its sessionId', async ({
+    page,
+    testId,
+    aimockPort,
+  }) => {
+    await open(page, 'session', testId, aimockPort)
+    await run(page)
+
+    // The parent model runs a third time only after the second call gave it
+    // the child's result.
+    await expect(page.getByTestId('parent-text')).toHaveText(
+      'Both notes are ready.',
+    )
+    await expect(page.getByTestId('card-status-researcher')).toHaveText(
+      'finished',
+    )
+    const card = page.getByTestId('card-researcher')
+    await expect(card).toContainText('text:Squids have three hearts.')
+    // The second call has no prompt, so the child's last user message is the
+    // task it stored from the first call. Only that fixture gives this reply.
+    // A child that did not get its earlier messages would get no reply.
+    await expect(card).toContainText('text:Squids also have blue blood.')
+    // One card: the second call continued the same child.
+    await expect(card).toHaveCount(1)
+  })
 })

From a24b0a7637069f8a290b76efb9c666daa7935aaa Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 20:01:37 +0200
Subject: [PATCH 282/286] test(e2e): the coding tools in a harness turn

The tools-test route runs coding-* scenarios as one harness turn with
workspaceTools in a temp folder. One test each for read_file, the edit_file
fallback, patch, grep, and bash checks the tool result, the final text, and
the files on disk. The README names the new specs and fixture prefixes.
---
 testing/e2e/README.md                         |  42 +++--
 .../e2e/fixtures/tools-test/coding-tools.json | 111 ++++++++++++
 testing/e2e/src/routes/api.tools-test.ts      |  63 ++++++-
 .../e2e/tests/tools-test/coding-tools.spec.ts | 158 ++++++++++++++++++
 4 files changed, 355 insertions(+), 19 deletions(-)
 create mode 100644 testing/e2e/fixtures/tools-test/coding-tools.json
 create mode 100644 testing/e2e/tests/tools-test/coding-tools.spec.ts

diff --git a/testing/e2e/README.md b/testing/e2e/README.md
index e81b8286ec..abf3694fa4 100644
--- a/testing/e2e/README.md
+++ b/testing/e2e/README.md
@@ -24,6 +24,7 @@ Each test iterates over supported providers using `providersFor('feature')`:
 | structured-output        | 7         | `tests/structured-output.spec.ts`        |
 | structured-output-stream | 4         | `tests/structured-output-stream.spec.ts` |
 | tool-calling             | 7         | `tests/tool-calling.spec.ts`             |
+| tool-choice              | 1         | `tests/tool-choice.spec.ts`              |
 | parallel-tool-calls      | 6         | `tests/parallel-tool-calls.spec.ts`      |
 | tool-approval            | 6         | `tests/tool-approval.spec.ts`            |
 | text-tool-text           | 6         | `tests/text-tool-text.spec.ts`           |
@@ -42,17 +43,22 @@ Each test iterates over supported providers using `providersFor('feature')`:
 | audio-gen                | 1         | `tests/audio-gen.spec.ts`                |
 | video-understanding      | 1         | `tests/video-understanding.spec.ts`      |
 
+`tool-choice` runs openai through `/api/chat`, and reads `tool_choice` from the aimock journal. aimock drops `tool_choice` from Anthropic requests, so the Anthropic cases use `/api/tool-choice-wire`. That route captures the request body.
+
 ### Tools-test page
 
 Deterministic scenarios covering tool execution flows:
 
-| Spec file                                         | Tests | What it covers                                           |
-| ------------------------------------------------- | ----- | -------------------------------------------------------- |
-| `tests/tools-test/chat-flow.spec.ts`              | 5     | Text-only, server tool, client tool, tool call structure |
-| `tests/tools-test/approval-flow.spec.ts`          | 6     | Approve, deny, sequential, parallel, mixed flows         |
-| `tests/tools-test/client-tool.spec.ts`            | 5     | Single, sequential, parallel, triple, server+client      |
-| `tests/tools-test/race-conditions.spec.ts`        | 8     | No blocking, no deadlocks, timing, mixed flows           |
-| `tests/tools-test/server-client-sequence.spec.ts` | 5     | Server→client, parallel server, ordering                 |
+| Spec file                                         | Tests | What it covers                                                                                            |
+| ------------------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------- |
+| `tests/tools-test/chat-flow.spec.ts`              | 5     | Text-only, server tool, client tool, tool call structure                                                  |
+| `tests/tools-test/approval-flow.spec.ts`          | 6     | Approve, deny, sequential, parallel, mixed flows                                                          |
+| `tests/tools-test/client-tool.spec.ts`            | 5     | Single, sequential, parallel, triple, server+client                                                       |
+| `tests/tools-test/race-conditions.spec.ts`        | 8     | No blocking, no deadlocks, timing, mixed flows                                                            |
+| `tests/tools-test/server-client-sequence.spec.ts` | 5     | Server→client, parallel server, ordering                                                                  |
+| `tests/tools-test/coding-tools.spec.ts`           | 5     | `workspaceTools()` in a temp folder: `read_file`, the `edit_file` fallback match, `patch`, `grep`, `bash` |
+
+`coding-tools.spec.ts` does not use the page. It sends each `coding-*` scenario to `/api/tools-test` with a temp folder as `root`. The route runs one harness turn with `workspaceTools()` in that folder. The spec checks the `TOOL_CALL_RESULT` chunks and the files after the turn.
 
 ### Interrupt playground
 
@@ -81,15 +87,15 @@ Notes:
 
 ### Advanced feature tests
 
-| Spec file                      | What it covers                                            |
-| ------------------------------ | --------------------------------------------------------- |
-| `tests/abort.spec.ts`          | Stop button cancels in-flight generation                  |
-| `tests/lazy-tools.spec.ts`     | `__lazy__tool__discovery__` discovers and uses lazy tools |
-| `tests/custom-events.spec.ts`  | Server tool `emitCustomEvent` received by client          |
-| `tests/middleware.spec.ts`     | `onChunk` transform, `onBeforeToolCall` skip              |
-| `tests/error-handling.spec.ts` | Server RUN_ERROR, aimock error fixture                    |
-| `tests/tool-error.spec.ts`     | Tool throws error, agentic loop continues                 |
-| `tests/activity.spec.ts`       | AG-UI activity snapshot, send filter, reconstruct hydrate |
+| Spec file                      | What it covers                                                                  |
+| ------------------------------ | ------------------------------------------------------------------------------- |
+| `tests/abort.spec.ts`          | Stop button cancels in-flight generation                                        |
+| `tests/lazy-tools.spec.ts`     | `__lazy__tool__discovery__` discovers and uses lazy tools                       |
+| `tests/custom-events.spec.ts`  | Server tool `emitCustomEvent` received by client                                |
+| `tests/middleware.spec.ts`     | `onChunk` transform, `onBeforeToolCall` skip, `onAfterToolCall` `replaceResult` |
+| `tests/error-handling.spec.ts` | Server RUN_ERROR, aimock error fixture                                          |
+| `tests/tool-error.spec.ts`     | Tool throws error, agentic loop continues                                       |
+| `tests/activity.spec.ts`       | AG-UI activity snapshot, send filter, reconstruct hydrate                       |
 
 ### Durable / detachable run tests
 
@@ -130,7 +136,7 @@ E2E coverage is mandatory for every feature, bug fix, or behavior change (see th
 | New provider adapter                    | Add provider to `feature-support.ts` + `test-matrix.ts`. Existing feature tests auto-run.                                                                                                                  |
 | New feature (e.g., new generation type) | Add feature to types, feature config, support matrix. Create fixture + spec file.                                                                                                                          |
 | Bug fix in chat/streaming               | Add a test case to `chat.spec.ts` or `tools-test/` that reproduces the bug.                                                                                                                                |
-| Tool system change                      | Add scenario to `tools-test-scenarios.ts` + test in `tools-test/` specs.                                                                                                                                   |
+| Tool system change                      | Add scenario to `src/lib/tools-test-tools.ts` + test in `tools-test/` specs.                                                                                                                               |
 | Middleware change                       | Add test to `middleware.spec.ts` with appropriate scenario.                                                                                                                                                |
 | Client-side change (useChat, etc.)      | Add test covering the observable behavior change.                                                                                                                                                          |
 | joinRun + client-tool continuation      | Add a spec that reloads mid-run, tails with `joinRun`, and asserts the client-tool result POSTs after replay (see `tests/join-run-client-tool.spec.ts`).                                                   |
@@ -206,7 +212,7 @@ Clean up the fixture:
 }
 ```
 
-Existing prefixes: `[chat]`, `[oneshot]`, `[reasoning]`, `[multiturn-1]`, `[multiturn-2]`, `[toolcall]`, `[parallel]`, `[approval]`, `[approval-deny]`, `[text-tool-text]`, `[structured]`, `[structured-stream]`, `[structured-stream-abort]`, `[agentic]`, `[mmimage]`, `[mmstruct]`, `[summarize]`, `[imagegen]`, `[tts]`, `[transcription]`, `[abort-test]`, `[error-test]`.
+Existing prefixes: `[chat]`, `[oneshot]`, `[reasoning]`, `[multiturn-1]`, `[multiturn-2]`, `[toolcall]`, `[parallel]`, `[approval]`, `[approval-deny]`, `[text-tool-text]`, `[structured]`, `[structured-stream]`, `[structured-stream-abort]`, `[agentic]`, `[mmimage]`, `[mmstruct]`, `[summarize]`, `[imagegen]`, `[tts]`, `[transcription]`, `[abort-test]`, `[error-test]`, `[coding-read]`, `[coding-edit]`, `[coding-patch]`, `[coding-grep]`, `[coding-bash]`, `[harness-agent]`, `[harness-agents]`, `[harness-always]`, `[harness-chatclient]`, `[harness-context]`, `[harness-durable]`, `[harness-env]`, `[harness-fast-resolve]`, `[harness-fork]`, `[harness-format]`, `[harness-limits]`, `[harness-mcp]`, `[harness-media]`, `[harness-media-image]`, `[harness-plan-subagent]`, `[harness-plan-writer]`, `[harness-protocol]`, `[harness-queue]`, `[harness-queue-moved]`, `[harness-reject]`, `[harness-rejoin]`, `[harness-reset]`, `[harness-restart-resolve]`, `[harness-routing]`, `[harness-routing-fix]`, `[harness-routing:pricer]`, `[harness-routing:researcher]`, `[harness-routing:seo]`, `[harness-routing:writer]`, `[harness-runid]`, `[harness-sender]`, `[harness-settings]`, `[harness-title]`, `[harness-tool-order]`, `[harness-turns]`, `[harness-undo]`, `[harness-usage]`.
 
 ## 4. Writing a Test
 
diff --git a/testing/e2e/fixtures/tools-test/coding-tools.json b/testing/e2e/fixtures/tools-test/coding-tools.json
new file mode 100644
index 0000000000..c4c772a2a8
--- /dev/null
+++ b/testing/e2e/fixtures/tools-test/coding-tools.json
@@ -0,0 +1,111 @@
+{
+  "fixtures": [
+    {
+      "match": {
+        "userMessage": "[coding-read] run test",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          { "name": "read_file", "arguments": "{\"path\":\"notes.txt\"}" }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[coding-read] run test",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "notes.txt has two lines."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[coding-edit] run test",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "edit_file",
+            "arguments": "{\"path\":\"notes.txt\",\"old\":\"alpha\\nbeta\",\"new\":\"gamma\\nbeta\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[coding-edit] run test",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Edited notes.txt."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[coding-patch] run test",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "patch",
+            "arguments": "{\"patch\":\"*** Begin Patch\\n*** Update File: notes.txt\\n-alpha\\n+delta\\n beta\\n*** Add File: added.txt\\n+added by patch\\n*** End Patch\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[coding-patch] run test",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Patched notes.txt and added added.txt."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[coding-grep] run test",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [{ "name": "grep", "arguments": "{\"pattern\":\"beta\"}" }]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[coding-grep] run test",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "beta is in two files."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[coding-bash] run test",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "bash",
+            "arguments": "{\"command\":\"node -e \\\"require('fs').writeFileSync('bash.txt', 'AGENT=' + process.env.AGENT); console.log('done')\\\"\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[coding-bash] run test",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "The command ran."
+      }
+    }
+  ]
+}
diff --git a/testing/e2e/src/routes/api.tools-test.ts b/testing/e2e/src/routes/api.tools-test.ts
index 4c2b114db4..1577880067 100644
--- a/testing/e2e/src/routes/api.tools-test.ts
+++ b/testing/e2e/src/routes/api.tools-test.ts
@@ -1,3 +1,5 @@
+import { tmpdir } from 'node:os'
+import { resolve, sep } from 'node:path'
 import { createFileRoute } from '@tanstack/react-router'
 import {
   EventType,
@@ -6,7 +8,13 @@ import {
   maxIterations,
   toServerSentEventsResponse,
 } from '@tanstack/ai'
-import type { AnyTextAdapter, AdapterYieldChunk } from '@tanstack/ai'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { workspaceTools } from '@tanstack/ai-harness/plugins/coding'
+import type {
+  AnyTextAdapter,
+  AdapterYieldChunk,
+  StreamChunk,
+} from '@tanstack/ai'
 import type { TestRuntimeContext } from '@/lib/tools-test-tools'
 import { createTextAdapter } from '@/lib/providers'
 import {
@@ -470,6 +478,40 @@ function createInterleavedArgsAdapter(): AnyTextAdapter {
   }
 }
 
+/**
+ * A `coding-*` scenario: one harness turn with `workspaceTools()` in `root`,
+ * as the chunks the client gets. `coding-patch` gets the `patch` tool, the
+ * other scenarios get `edit_file`. No `permissions()` is mounted, so no tool
+ * asks for approval.
+ */
+async function* codingTurn(
+  scenario: string,
+  root: string,
+  threadId: string,
+  adapter: AnyTextAdapter,
+): AsyncGenerator<StreamChunk> {
+  const host = createHarnessHost()
+  try {
+    const session = await host.open(
+      defineHarness({
+        name: 'e2e/tools-test-coding',
+        adapter,
+        plugins: () => [
+          workspaceTools({
+            root,
+            editStyle: scenario === 'coding-patch' ? 'patch' : 'edit',
+          }),
+        ],
+      }),
+      { threadId },
+    )
+    // The session keeps its own history, so the turn gets the prompt only.
+    yield* session.prompt(`[${scenario}] run test`).stream()
+  } finally {
+    await host.close()
+  }
+}
+
 export const Route = createFileRoute('/api/tools-test')({
   server: {
     handlers: {
@@ -528,6 +570,25 @@ export const Route = createFileRoute('/api/tools-test')({
             return toServerSentEventsResponse(errorStream, { abortController })
           }
 
+          if (scenario.startsWith('coding-')) {
+            const root = typeof fp.root === 'string' ? resolve(fp.root) : ''
+            // The tools write files and run commands: only in a temp folder.
+            if (!root.startsWith(resolve(tmpdir()) + sep)) {
+              return new Response('root must be in the temp folder', {
+                status: 400,
+              })
+            }
+            const { adapter } = createTextAdapter(
+              'openai',
+              'gpt-5.5',
+              aimockPort,
+              testId,
+            )
+            return toServerSentEventsResponse(
+              codingTurn(scenario, root, params.threadId, adapter),
+            )
+          }
+
           const adapterOptions =
             scenario === 'interleaved-args'
               ? { adapter: createInterleavedArgsAdapter() }
diff --git a/testing/e2e/tests/tools-test/coding-tools.spec.ts b/testing/e2e/tests/tools-test/coding-tools.spec.ts
new file mode 100644
index 0000000000..4cb31c8139
--- /dev/null
+++ b/testing/e2e/tests/tools-test/coding-tools.spec.ts
@@ -0,0 +1,158 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { test, expect } from '../fixtures'
+import type { APIRequestContext } from '@playwright/test'
+
+/**
+ * The coding tools of `workspaceTools()` from
+ * `@tanstack/ai-harness/plugins/coding`. A `coding-*` scenario of
+ * `/api/tools-test` runs one harness turn in a temp folder that the test
+ * makes. aimock gives one tool call, and the tool works on real files. Each
+ * test checks the `TOOL_CALL_RESULT` that the client gets, and the files
+ * after the turn. No `permissions()` is mounted, so no tool waits for
+ * approval.
+ */
+
+type Chunk = { type: string; delta?: string; content?: string }
+
+/** The chunks of an SSE body. */
+const sse = (body: string): Array<Chunk> =>
+  body
+    .split('\n')
+    .filter((line) => line.startsWith('data: '))
+    .map((line) => JSON.parse(line.slice('data: '.length)))
+
+/** The workspace of the running test. */
+let root = ''
+const file = (path: string) => join(root, path)
+const read = (path: string) => readFile(file(path), 'utf8')
+
+/** Run `scenario` in `root`. Gives the tool results and the text the client got. */
+async function runScenario(
+  request: APIRequestContext,
+  scenario: string,
+  testId: string,
+  aimockPort: number,
+) {
+  const response = await request.post('/api/tools-test', {
+    data: {
+      threadId: `${scenario}-${testId}`,
+      runId: `${scenario}-run-${testId}`,
+      state: {},
+      messages: [{ id: 'u1', role: 'user', content: `[${scenario}] run test` }],
+      tools: [],
+      context: [],
+      forwardedProps: { scenario, testId, aimockPort, root },
+    },
+  })
+  const body = await response.text()
+  expect(response.ok(), body).toBe(true)
+  const chunks = sse(body)
+  expect(
+    chunks.filter((chunk) => chunk.type === 'RUN_ERROR'),
+    body,
+  ).toEqual([])
+  return {
+    results: chunks
+      .filter((chunk) => chunk.type === 'TOOL_CALL_RESULT')
+      .map((chunk) => chunk.content),
+    text: chunks
+      .filter((chunk) => chunk.type === 'TEXT_MESSAGE_CONTENT')
+      .map((chunk) => chunk.delta)
+      .join(''),
+  }
+}
+
+test.describe('Coding tools (tools-test route)', () => {
+  test.beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'e2e-coding-'))
+  })
+
+  test.afterEach(async () => {
+    await rm(root, { recursive: true, force: true })
+  })
+
+  test('read_file gives the lines with their numbers', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    await writeFile(file('notes.txt'), 'alpha\nbeta\n')
+
+    expect(
+      await runScenario(request, 'coding-read', testId, aimockPort),
+    ).toEqual({
+      results: ['1\talpha\n2\tbeta'],
+      text: 'notes.txt has two lines.',
+    })
+    expect(await read('notes.txt')).toBe('alpha\nbeta\n')
+  })
+
+  test('edit_file finds the old text when the file has spaces at the end of a line', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    // The old text is `alpha\nbeta`. The exact text is not in the file.
+    await writeFile(file('notes.txt'), 'alpha  \nbeta\n')
+
+    expect(
+      await runScenario(request, 'coding-edit', testId, aimockPort),
+    ).toEqual({
+      results: ['Edited notes.txt (1 change).'],
+      text: 'Edited notes.txt.',
+    })
+    // The match covers the trailing spaces, so they go too.
+    expect(await read('notes.txt')).toBe('gamma\nbeta\n')
+  })
+
+  test('patch updates one file and adds another', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    await writeFile(file('notes.txt'), 'alpha\nbeta\n')
+
+    expect(
+      await runScenario(request, 'coding-patch', testId, aimockPort),
+    ).toEqual({
+      results: ['Applied the patch:\nupdated notes.txt\nadded added.txt'],
+      text: 'Patched notes.txt and added added.txt.',
+    })
+    expect(await read('notes.txt')).toBe('delta\nbeta\n')
+    expect(await read('added.txt')).toBe('added by patch\n')
+  })
+
+  test('grep gives each match as file:line: text', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    await writeFile(file('notes.txt'), 'alpha\nbeta\n')
+    await writeFile(file('more.txt'), 'more beta\n')
+
+    expect(
+      await runScenario(request, 'coding-grep', testId, aimockPort),
+    ).toEqual({
+      results: ['more.txt:1: more beta\nnotes.txt:2: beta'],
+      text: 'beta is in two files.',
+    })
+    expect(await read('notes.txt')).toBe('alpha\nbeta\n')
+  })
+
+  test('bash runs the command in the workspace with AGENT=1', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    // The command is `node -e "..."`: it writes bash.txt and prints `done`.
+    expect(
+      await runScenario(request, 'coding-bash', testId, aimockPort),
+    ).toEqual({
+      results: ['exit code: 0\ndone\n'],
+      text: 'The command ran.',
+    })
+    expect(await read('bash.txt')).toBe('AGENT=1')
+  })
+})

From 57e3a527185d9a274e2b2fa6b80315708cf64407 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Tue, 6 Oct 2026 20:03:50 +0200
Subject: [PATCH 283/286] chore: format the files of the opencode primitives
 with oxfmt

---
 .../src/first-party/bound-output.ts           | 10 ++++--
 .../ai-harness/src/first-party/coding/bash.ts | 13 ++++----
 .../src/first-party/coding/index.ts           |  6 +---
 .../src/first-party/coding/patch.ts           |  8 +++--
 .../src/first-party/coding/snapshots.ts       |  4 ++-
 packages/ai-harness/src/first-party/title.ts  |  4 ++-
 .../ai-harness/tests/bound-output.test.ts     |  5 ++-
 .../ai-harness/tests/coding-backend.test.ts   |  4 +--
 packages/ai-harness/tests/coding-bash.test.ts | 31 ++++++++++++++-----
 .../ai-harness/tests/coding-formatter.test.ts | 11 +++----
 .../ai-harness/tests/coding-patch.test.ts     | 19 ++++++++----
 .../ai-harness/tests/coding-search.test.ts    | 24 ++++++++++----
 .../ai-harness/tests/coding-snapshots.test.ts |  4 ++-
 packages/ai-harness/tests/coding-web.test.ts  | 14 +++++++--
 packages/ai-harness/tests/define.test.ts      |  6 +---
 packages/ai-harness/tests/plugin-apis.test.ts |  6 +++-
 packages/ai-harness/tests/protocol.test.ts    | 13 ++++----
 packages/ai-harness/tests/question.test.ts    |  3 +-
 packages/ai-harness/tests/status-feed.test.ts | 11 ++++---
 packages/ai-harness/tests/view-reduce.test.ts |  6 ++--
 packages/ai-mcp/skills/ai-mcp/SKILL.md        |  6 +++-
 packages/ai-mcp/src/harness-plugin.ts         |  5 +--
 packages/ai-mcp/tests/harness-plugin.test.ts  |  3 +-
 .../ai-openai/tests/tool-choice-wire.test.ts  | 14 +++++----
 packages/ai-persistence/src/subagent-runs.ts  |  3 +-
 .../ai-persistence/src/testkit/conformance.ts |  4 ++-
 .../tests/subagent-persistence-cards.test.ts  |  6 +++-
 packages/ai-sandbox/src/workspace-backend.ts  |  3 +-
 .../src/activities/chat/middleware/types.ts   |  7 +++--
 29 files changed, 160 insertions(+), 93 deletions(-)

diff --git a/packages/ai-harness/src/first-party/bound-output.ts b/packages/ai-harness/src/first-party/bound-output.ts
index e157e25479..0cd811144b 100644
--- a/packages/ai-harness/src/first-party/bound-output.ts
+++ b/packages/ai-harness/src/first-party/bound-output.ts
@@ -88,8 +88,14 @@ export function boundText(
     : firstPart(text, bytes, limits)
   const shown = `${countLines(kept)} of ${lines} lines, ${encoder.encode(kept).length} of ${bytes.length} bytes`
   return isTail
-    ? { text: `[Output cut. Showing the last ${shown}.]\n\n${kept}`, truncated: true }
-    : { text: `${kept}\n\n[Output cut. Showing the first ${shown}.]`, truncated: true }
+    ? {
+        text: `[Output cut. Showing the last ${shown}.]\n\n${kept}`,
+        truncated: true,
+      }
+    : {
+        text: `${kept}\n\n[Output cut. Showing the first ${shown}.]`,
+        truncated: true,
+      }
 }
 
 /**
diff --git a/packages/ai-harness/src/first-party/coding/bash.ts b/packages/ai-harness/src/first-party/coding/bash.ts
index 9e5187cb13..cc4e471e02 100644
--- a/packages/ai-harness/src/first-party/coding/bash.ts
+++ b/packages/ai-harness/src/first-party/coding/bash.ts
@@ -130,8 +130,12 @@ export function bashTools(
     signal?: AbortSignal
   } = {},
 ) {
-  const { timeoutMs: defaultTimeoutMs = 120_000, note, spillDir, signal } =
-    options
+  const {
+    timeoutMs: defaultTimeoutMs = 120_000,
+    note,
+    spillDir,
+    signal,
+  } = options
   // ponytail: jobs live in memory only. A restart forgets them.
   const jobs = new Set<{ kill: () => void }>()
   let started = 0
@@ -142,10 +146,7 @@ export function bashTools(
   /** Save the full output in `dir`. Gives back the note for the model. */
   const spill = async (dir: string, output: string) => {
     const { join, resolve } = pathsOf(env.backend)
-    const path = join(
-      resolve(env.root, dir),
-      `bash-${crypto.randomUUID()}.txt`,
-    )
+    const path = join(resolve(env.root, dir), `bash-${crypto.randomUUID()}.txt`)
     try {
       await env.backend.writeFile(path, output)
       return `[Full output saved to ${env.shown(path)}.]`
diff --git a/packages/ai-harness/src/first-party/coding/index.ts b/packages/ai-harness/src/first-party/coding/index.ts
index f6620a0b18..a8adcfdcfe 100644
--- a/packages/ai-harness/src/first-party/coding/index.ts
+++ b/packages/ai-harness/src/first-party/coding/index.ts
@@ -9,8 +9,4 @@ export type { SearchProvider, WebToolsOptions } from './web'
 export { snapshots } from './snapshots'
 export type { SnapshotStep, SnapshotsOptions } from './snapshots'
 export { FormatFailed, formatter } from './formatter'
-export type {
-  Formatter,
-  FormatterOptions,
-  FormatterProject,
-} from './formatter'
+export type { Formatter, FormatterOptions, FormatterProject } from './formatter'
diff --git a/packages/ai-harness/src/first-party/coding/patch.ts b/packages/ai-harness/src/first-party/coding/patch.ts
index d3e7e182d3..a2a3d09969 100644
--- a/packages/ai-harness/src/first-party/coding/patch.ts
+++ b/packages/ai-harness/src/first-party/coding/patch.ts
@@ -349,7 +349,9 @@ async function applyAll(env: ToolEnv, steps: ReadonlyArray<Step>) {
             )
           }
           if (planned.has(full)) {
-            throw new Error(`Cannot move ${shown}: the patch changes it before.`)
+            throw new Error(
+              `Cannot move ${shown}: the patch changes it before.`,
+            )
           }
           // The target must be free: no file, or a file that the patch
           // removes before.
@@ -364,7 +366,9 @@ async function applyAll(env: ToolEnv, steps: ReadonlyArray<Step>) {
         }
         const known = planned.get(full)
         if (known === null) {
-          throw new Error(`Cannot update ${shown}: the patch removes it before.`)
+          throw new Error(
+            `Cannot update ${shown}: the patch removes it before.`,
+          )
         }
         const before = known ?? (await readText(backend, full))
         planned.set(to, applyChunks(before, operation.chunks, shown))
diff --git a/packages/ai-harness/src/first-party/coding/snapshots.ts b/packages/ai-harness/src/first-party/coding/snapshots.ts
index b538849cdc..792b8ed73c 100644
--- a/packages/ai-harness/src/first-party/coding/snapshots.ts
+++ b/packages/ai-harness/src/first-party/coding/snapshots.ts
@@ -123,7 +123,9 @@ function shadowRepo(options: SnapshotsOptions) {
     restore: (tree: string) =>
       serial(async () => {
         // The index must list the files on disk, so the reset sees them.
-        await exec(`${git} add -A && ${git} read-tree --reset -u ${quote(tree)}`)
+        await exec(
+          `${git} add -A && ${git} read-tree --reset -u ${quote(tree)}`,
+        )
       }),
   }
 }
diff --git a/packages/ai-harness/src/first-party/title.ts b/packages/ai-harness/src/first-party/title.ts
index 637bcc37ff..a0a753f72e 100644
--- a/packages/ai-harness/src/first-party/title.ts
+++ b/packages/ai-harness/src/first-party/title.ts
@@ -55,7 +55,9 @@ export function title(options: {
         const message = textOf(first).slice(0, 2000)
         const answer = await chat({
           adapter: await ctx.keys.adapter(options.adapter),
-          messages: [{ role: 'user', content: `${TITLE_PROMPT}\n\n${message}` }],
+          messages: [
+            { role: 'user', content: `${TITLE_PROMPT}\n\n${message}` },
+          ],
           stream: false,
         })
         const text = cleanTitle(answer)
diff --git a/packages/ai-harness/tests/bound-output.test.ts b/packages/ai-harness/tests/bound-output.test.ts
index 1cfc3eaddc..b4c257e053 100644
--- a/packages/ai-harness/tests/bound-output.test.ts
+++ b/packages/ai-harness/tests/bound-output.test.ts
@@ -128,7 +128,10 @@ describe('boundText', () => {
       'x\n\n[Output cut. Showing the first 1 of 1 lines, 1 of 5 bytes.]',
     ],
   ])('keeps the head of text with %s', (_case, input, limits, expected) => {
-    expect(boundText(input, limits)).toEqual({ text: expected, truncated: true })
+    expect(boundText(input, limits)).toEqual({
+      text: expected,
+      truncated: true,
+    })
   })
 
   it.each([
diff --git a/packages/ai-harness/tests/coding-backend.test.ts b/packages/ai-harness/tests/coding-backend.test.ts
index 96f27fe3dd..6b2825c7ae 100644
--- a/packages/ai-harness/tests/coding-backend.test.ts
+++ b/packages/ai-harness/tests/coding-backend.test.ts
@@ -86,9 +86,7 @@ describe('hostBackend', () => {
   })
 
   it('kills a background command', async () => {
-    const job = hostBackend.spawn(
-      `node -e "setTimeout(function () {}, 60000)"`,
-    )
+    const job = hostBackend.spawn(`node -e "setTimeout(function () {}, 60000)"`)
     job.kill()
     expect((await job.wait()).exitCode).not.toBe(0)
   })
diff --git a/packages/ai-harness/tests/coding-bash.test.ts b/packages/ai-harness/tests/coding-bash.test.ts
index 1404fd793a..ed3a310f25 100644
--- a/packages/ai-harness/tests/coding-bash.test.ts
+++ b/packages/ai-harness/tests/coding-bash.test.ts
@@ -7,7 +7,10 @@ import {
   splitCommand,
 } from '../src/first-party/coding/bash'
 import { decidePermission } from '../src/first-party/permissions'
-import type { ToolEnv, WorkspaceBackend } from '../src/first-party/coding/backend'
+import type {
+  ToolEnv,
+  WorkspaceBackend,
+} from '../src/first-party/coding/backend'
 import type { PermissionRule } from '../src/first-party/permissions'
 
 type ExecOptions = Parameters<WorkspaceBackend['exec']>[1]
@@ -162,9 +165,21 @@ describe('bash', () => {
 
   it.each([
     { name: 'the factory timeout without one', args: {}, expected: 30_000 },
-    { name: 'the timeout of the call', args: { timeoutMs: 5_000 }, expected: 5_000 },
-    { name: 'at most 10 minutes', args: { timeoutMs: 3_600_000 }, expected: 600_000 },
-    { name: 'the factory timeout for 0', args: { timeoutMs: 0 }, expected: 30_000 },
+    {
+      name: 'the timeout of the call',
+      args: { timeoutMs: 5_000 },
+      expected: 5_000,
+    },
+    {
+      name: 'at most 10 minutes',
+      args: { timeoutMs: 3_600_000 },
+      expected: 600_000,
+    },
+    {
+      name: 'the factory timeout for 0',
+      args: { timeoutMs: 0 },
+      expected: 30_000,
+    },
   ])('gives exec $name', async ({ args, expected }) => {
     const { env, execs } = workspace(OK)
     await bash(env, { command: 'make', ...args }, { timeoutMs: 30_000 })
@@ -210,9 +225,7 @@ describe('bash', () => {
     })
     expect(
       await bash(env, { command: 'test' }, { spillDir: '.agent/bash' }),
-    ).toBe(
-      `${LONG_RESULT}\n[The full output was not saved: Error: disk full]`,
-    )
+    ).toBe(`${LONG_RESULT}\n[The full output was not saved: Error: disk full]`)
   })
 })
 
@@ -240,7 +253,9 @@ describe('bash in the background', () => {
     expect(notes).toEqual([])
     end(2)
     await settle()
-    expect(notes).toEqual(['Background job bash-1 ended.\nexit code: 2\nbuilt\n'])
+    expect(notes).toEqual([
+      'Background job bash-1 ended.\nexit code: 2\nbuilt\n',
+    ])
   })
 
   it('kills running jobs when the signal aborts, and sends no note', async () => {
diff --git a/packages/ai-harness/tests/coding-formatter.test.ts b/packages/ai-harness/tests/coding-formatter.test.ts
index c99e4926a9..3680ef4219 100644
--- a/packages/ai-harness/tests/coding-formatter.test.ts
+++ b/packages/ai-harness/tests/coding-formatter.test.ts
@@ -35,11 +35,7 @@ const quoted = (path: string) => `'${join(root, path)}'`
  * `shell: 'sh'`, the project is at `/workspace` with POSIX paths, like a
  * Linux sandbox. Else it is at `root` on this machine.
  */
-function project(
-  files: Record<string, string>,
-  exec: Exec = ok,
-  shell?: 'sh',
-) {
+function project(files: Record<string, string>, exec: Exec = ok, shell?: 'sh') {
   const paths = shell === 'sh' ? posix : nodePath
   const base = shell === 'sh' ? '/workspace' : root
   const store = new Map<string, Uint8Array>()
@@ -199,8 +195,9 @@ describe('formatOnWrite', () => {
 
   it('keeps POSIX paths in a sandbox, also on a Windows host', async () => {
     const { backend, runs } = project(prettier, ok, 'sh')
-    const afterWrite = formatOnWrite({ root: '/workspace', backend }, () =>
-      undefined,
+    const afterWrite = formatOnWrite(
+      { root: '/workspace', backend },
+      () => undefined,
     )
     await afterWrite('/workspace/src/a.ts')
     expect(runs).toEqual([
diff --git a/packages/ai-harness/tests/coding-patch.test.ts b/packages/ai-harness/tests/coding-patch.test.ts
index a43d554e51..9ff5a176aa 100644
--- a/packages/ai-harness/tests/coding-patch.test.ts
+++ b/packages/ai-harness/tests/coding-patch.test.ts
@@ -181,14 +181,12 @@ describe('parsePatch', () => {
     {
       name: 'an added line without +',
       text: patch('*** Add File: a.txt', '+one', 'two'),
-      error:
-        'Patch line 4: each line of an added file must start with "+".',
+      error: 'Patch line 4: each line of an added file must start with "+".',
     },
     {
       name: 'a chunk line without a prefix',
       text: patch('*** Update File: a.txt', '@@', ' one', 'two'),
-      error:
-        'Patch line 5: each chunk line must start with " ", "-", or "+".',
+      error: 'Patch line 5: each chunk line must start with " ", "-", or "+".',
     },
     {
       name: 'an update without changes',
@@ -253,7 +251,8 @@ describe('patch tool', () => {
   })
 
   it('searches from the @@ line', async () => {
-    const file = 'function a() {\n  return 1\n}\nfunction b() {\n  return 1\n}\n'
+    const file =
+      'function a() {\n  return 1\n}\nfunction b() {\n  return 1\n}\n'
     const text = patch(
       '*** Update File: a.txt',
       '@@ function b() {',
@@ -274,7 +273,15 @@ describe('patch tool', () => {
 
   it('searches each chunk after the chunk before it', async () => {
     // `x` is in the file twice, but once after the first chunk.
-    const text = patch('*** Update File: a.txt', '@@', '-a', '+A', '@@', '-x', '+X')
+    const text = patch(
+      '*** Update File: a.txt',
+      '@@',
+      '-a',
+      '+A',
+      '@@',
+      '-x',
+      '+X',
+    )
     expect(await patchFile('x\na\nx\n', text)).toBe('x\nA\nX\n')
   })
 
diff --git a/packages/ai-harness/tests/coding-search.test.ts b/packages/ai-harness/tests/coding-search.test.ts
index 895a6e906d..91052cde68 100644
--- a/packages/ai-harness/tests/coding-search.test.ts
+++ b/packages/ai-harness/tests/coding-search.test.ts
@@ -1,7 +1,15 @@
 import { mkdtemp, rm, symlink } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join, resolve, sep } from 'node:path'
-import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest'
 import { hostBackend } from '../src/first-party/coding/backend'
 import { quoteArg } from '../src/first-party/coding/search'
 import { createWorkspaceTools } from '../src/first-party/coding/workspace'
@@ -132,7 +140,8 @@ describe('list_files and grep engines', () => {
   }
   // What rg prints for `files`: not sorted, with `./`, NUL after each path.
   // A long line is cut after 2000 bytes, with a note after it.
-  const rgFiles = './src/b.ts\0./src/a.ts\0./long.txt\0./image.png\0./.github/ci.yml\0'
+  const rgFiles =
+    './src/b.ts\0./src/a.ts\0./long.txt\0./image.png\0./.github/ci.yml\0'
   const rgMatches = [
     './src/b.ts\x001:const two = 2\r',
     './.github/ci.yml\x001:two: yes',
@@ -427,10 +436,13 @@ describe('quoteArg', () => {
     { value: 'C:\\dir\\', posix: `'C:\\dir\\'`, win32: '^"C:\\dir\\\\^"' },
   ]
 
-  it.each(hostile)('quotes $value for sh and cmd.exe', ({ value, posix, win32 }) => {
-    expect(quoteArg(value, 'linux')).toBe(posix)
-    expect(quoteArg(value, 'win32')).toBe(win32)
-  })
+  it.each(hostile)(
+    'quotes $value for sh and cmd.exe',
+    ({ value, posix, win32 }) => {
+      expect(quoteArg(value, 'linux')).toBe(posix)
+      expect(quoteArg(value, 'win32')).toBe(win32)
+    },
+  )
 
   it('refuses a line break for cmd.exe', () => {
     expect(() => quoteArg('a\nb', 'win32')).toThrow('line break')
diff --git a/packages/ai-harness/tests/coding-snapshots.test.ts b/packages/ai-harness/tests/coding-snapshots.test.ts
index 5932786e73..eefee6228e 100644
--- a/packages/ai-harness/tests/coding-snapshots.test.ts
+++ b/packages/ai-harness/tests/coding-snapshots.test.ts
@@ -150,7 +150,9 @@ describe.skipIf(!hasGit)('snapshots', () => {
     const commands = exec.mock.calls.map(([command]) => command)
     // `git --version` and `git init` once, the turn start, and one snapshot
     // after each tool step. Step starts reuse the snapshot before them.
-    expect(commands.filter((command) => /write-tree/.test(command))).toHaveLength(3)
+    expect(
+      commands.filter((command) => /write-tree/.test(command)),
+    ).toHaveLength(3)
     // The second step changed nothing, so it needs no diff.
     expect(commands.filter((command) => / diff /.test(command))).toHaveLength(1)
     expect(commands.length).toBeLessThanOrEqual(6)
diff --git a/packages/ai-harness/tests/coding-web.test.ts b/packages/ai-harness/tests/coding-web.test.ts
index 9135b8bb3a..547b343ee5 100644
--- a/packages/ai-harness/tests/coding-web.test.ts
+++ b/packages/ai-harness/tests/coding-web.test.ts
@@ -1,5 +1,13 @@
 import { createServer } from 'node:http'
-import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest'
 import { webTools } from '../src/first-party/coding/web'
 import type { AddressInfo } from 'node:net'
 import type {
@@ -84,7 +92,9 @@ beforeEach(() => {
 describe('webfetch formats', () => {
   const html =
     '<html><head><title>Doc</title><style>p { color: red }</style></head><body><h1>Hello</h1><p>Tom &amp; <strong>Jerry</strong> &lt;3 &#x41;&#66;</p><script>alert("x")</script></body></html>'
-  const routes = { 'https://example.com/': page(html, 'text/html; charset=utf-8') }
+  const routes = {
+    'https://example.com/': page(html, 'text/html; charset=utf-8'),
+  }
 
   it('gives back HTML as markdown when turndown is installed', async () => {
     const result = await webfetch({ url: 'https://example.com/' }, routes)
diff --git a/packages/ai-harness/tests/define.test.ts b/packages/ai-harness/tests/define.test.ts
index 47147c6cb1..004ab83f3b 100644
--- a/packages/ai-harness/tests/define.test.ts
+++ b/packages/ai-harness/tests/define.test.ts
@@ -2,11 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { z } from 'zod'
 import { defineAgent, toolDefinition } from '@tanstack/ai'
 import { memoryPersistence } from '@tanstack/ai-persistence'
-import {
-  createHarnessHost,
-  defineHarness,
-  isHarnessDefinition,
-} from '../src'
+import { createHarnessHost, defineHarness, isHarnessDefinition } from '../src'
 import { mockAdapter, text, toolCall } from './helpers'
 
 const agent = (name: string) =>
diff --git a/packages/ai-harness/tests/plugin-apis.test.ts b/packages/ai-harness/tests/plugin-apis.test.ts
index 15df564c67..e554374c78 100644
--- a/packages/ai-harness/tests/plugin-apis.test.ts
+++ b/packages/ai-harness/tests/plugin-apis.test.ts
@@ -16,7 +16,11 @@ async function openWithApi(adapter: AnyTextAdapter) {
   })
   const host = createHarnessHost({ persistence: memoryPersistence() })
   const session = await host.open(
-    defineHarness({ name: 'test/plugin-apis', adapter, plugins: () => [probe] }),
+    defineHarness({
+      name: 'test/plugin-apis',
+      adapter,
+      plugins: () => [probe],
+    }),
     { threadId: 't' },
   )
   const api = apis[0]
diff --git a/packages/ai-harness/tests/protocol.test.ts b/packages/ai-harness/tests/protocol.test.ts
index 21058f802e..7cbaf6a603 100644
--- a/packages/ai-harness/tests/protocol.test.ts
+++ b/packages/ai-harness/tests/protocol.test.ts
@@ -268,13 +268,14 @@ describe('HTTP handler', () => {
     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 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' },
-    )
+    expect(await control({ op: 'cancelInput', inputId: 'f-1' })).toMatchObject({
+      status: 'rejected',
+      reason: 'not_waiting',
+    })
     release.open()
     await host.close()
   })
diff --git a/packages/ai-harness/tests/question.test.ts b/packages/ai-harness/tests/question.test.ts
index 2be07da990..0abfa6c8e4 100644
--- a/packages/ai-harness/tests/question.test.ts
+++ b/packages/ai-harness/tests/question.test.ts
@@ -54,8 +54,7 @@ async function reply(session: HarnessSession, value: unknown) {
 function toolResult(
   calls: Array<{ messages: Array<{ role: string; content: unknown }> }>,
 ) {
-  return calls[1]?.messages.find((message) => message.role === 'tool')
-    ?.content
+  return calls[1]?.messages.find((message) => message.role === 'tool')?.content
 }
 
 describe('question()', () => {
diff --git a/packages/ai-harness/tests/status-feed.test.ts b/packages/ai-harness/tests/status-feed.test.ts
index b0bcfdc747..c51644b4af 100644
--- a/packages/ai-harness/tests/status-feed.test.ts
+++ b/packages/ai-harness/tests/status-feed.test.ts
@@ -111,7 +111,12 @@ describe('host.events', () => {
 
     await vi.waitFor(() => expect(feed.seen).toHaveLength(2))
     expect(feed.seen).toEqual([
-      { type: 'status', threadId: 'a', status: 'waiting', at: expect.any(Number) },
+      {
+        type: 'status',
+        threadId: 'a',
+        status: 'waiting',
+        at: expect.any(Number),
+      },
       { type: 'status', threadId: 'b', status: 'idle', at: expect.any(Number) },
     ])
     await feed.stop()
@@ -197,9 +202,7 @@ describe('GET host-events', () => {
     )
 
     await bob.prompt('hi')
-    await vi.waitFor(async () =>
-      expect(await bob.transcript()).toHaveLength(2),
-    )
+    await vi.waitFor(async () => expect(await bob.transcript()).toHaveLength(2))
     // Alice owns this thread, but `canAccess` refuses it.
     await host.open(harness, { threadId: 'hidden', principal: { id: 'alice' } })
     await alice.prompt('hi')
diff --git a/packages/ai-harness/tests/view-reduce.test.ts b/packages/ai-harness/tests/view-reduce.test.ts
index 2dc4c6e2a9..1a5651fa55 100644
--- a/packages/ai-harness/tests/view-reduce.test.ts
+++ b/packages/ai-harness/tests/view-reduce.test.ts
@@ -434,9 +434,9 @@ describe('view reducer', () => {
       { inputId: 'in-1', delivery: 'steer', message: 'later' },
     ])
     // A snapshot without the list has no waiting inputs.
-    expect(applySnapshot(moved, sessionSnapshot(), factory).waitingInputs).toEqual(
-      [],
-    )
+    expect(
+      applySnapshot(moved, sessionSnapshot(), factory).waitingInputs,
+    ).toEqual([])
   })
 
   it('reads a client tool interrupt as a client tool, not an approval', () => {
diff --git a/packages/ai-mcp/skills/ai-mcp/SKILL.md b/packages/ai-mcp/skills/ai-mcp/SKILL.md
index 71e95163ef..323ab7ab74 100644
--- a/packages/ai-mcp/skills/ai-mcp/SKILL.md
+++ b/packages/ai-mcp/skills/ai-mcp/SKILL.md
@@ -851,7 +851,11 @@ const agent = defineHarness({
           timeoutMs: 10_000,
           codeMode: true,
         },
-        notion: { type: 'http', url: 'https://mcp.notion.com/mcp', oauth: true },
+        notion: {
+          type: 'http',
+          url: 'https://mcp.notion.com/mcp',
+          oauth: true,
+        },
       },
     }),
   ],
diff --git a/packages/ai-mcp/src/harness-plugin.ts b/packages/ai-mcp/src/harness-plugin.ts
index e0e1dc3942..e28a3b977c 100644
--- a/packages/ai-mcp/src/harness-plugin.ts
+++ b/packages/ai-mcp/src/harness-plugin.ts
@@ -212,10 +212,7 @@ function requestOptionsOf(server: McpServerConfig) {
 }
 
 /** Marks the tools of a `codeMode: true` server for the `codeMode()` plugin. */
-function forCodeMode(
-  server: McpServerConfig,
-  tools: ReadonlyArray<AnyTool>,
-) {
+function forCodeMode(server: McpServerConfig, tools: ReadonlyArray<AnyTool>) {
   if (server.codeMode !== true) return tools
   return tools.map((tool) => ({
     ...tool,
diff --git a/packages/ai-mcp/tests/harness-plugin.test.ts b/packages/ai-mcp/tests/harness-plugin.test.ts
index e40d100f7e..56ca558409 100644
--- a/packages/ai-mcp/tests/harness-plugin.test.ts
+++ b/packages/ai-mcp/tests/harness-plugin.test.ts
@@ -118,7 +118,8 @@ if (process.env[childEnv] === '1') {
       const { session, model } = await openWith({
         slow: httpServer(
           async (request) => {
-            const body = request.method === 'POST' ? await request.clone().text() : ''
+            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>(() => {})
diff --git a/packages/ai-openai/tests/tool-choice-wire.test.ts b/packages/ai-openai/tests/tool-choice-wire.test.ts
index f09e102088..3121cb8165 100644
--- a/packages/ai-openai/tests/tool-choice-wire.test.ts
+++ b/packages/ai-openai/tests/tool-choice-wire.test.ts
@@ -84,17 +84,19 @@ const adapters = [
     adapter: 'openaiCompatible (Chat Completions)',
     namedChoice: chatCompletionsChoice,
     send: (fetch, request) =>
-      compatible(fetch, 'chat-completions')('my-model').chatStream(
-        callOptions('my-model', request),
-      ),
+      compatible(
+        fetch,
+        'chat-completions',
+      )('my-model').chatStream(callOptions('my-model', request)),
   },
   {
     adapter: 'openaiCompatible (Responses)',
     namedChoice: responsesChoice,
     send: (fetch, request) =>
-      compatible(fetch, 'responses')('my-model').chatStream(
-        callOptions('my-model', request),
-      ),
+      compatible(
+        fetch,
+        'responses',
+      )('my-model').chatStream(callOptions('my-model', request)),
   },
 ] satisfies Array<{ adapter: string; send: Send }>
 
diff --git a/packages/ai-persistence/src/subagent-runs.ts b/packages/ai-persistence/src/subagent-runs.ts
index 297f1e43e4..ace5182a61 100644
--- a/packages/ai-persistence/src/subagent-runs.ts
+++ b/packages/ai-persistence/src/subagent-runs.ts
@@ -551,8 +551,7 @@ export function createSubagentRunRecorder(stores: {
       // after the whole stored transcript.
       const resumes = storedSubagentInfo(raw)?.status === 'suspended'
       // Only the first call gives the prompt. A later call keeps it.
-      const prompt =
-        raw.length > 0 ? marker.prompt : call && callPrompt(call)
+      const prompt = raw.length > 0 ? marker.prompt : call && callPrompt(call)
       children.set(id, {
         name: chunk.name,
         threadId: input.threadId,
diff --git a/packages/ai-persistence/src/testkit/conformance.ts b/packages/ai-persistence/src/testkit/conformance.ts
index abaaedb4e6..571e785406 100644
--- a/packages/ai-persistence/src/testkit/conformance.ts
+++ b/packages/ai-persistence/src/testkit/conformance.ts
@@ -1996,7 +1996,9 @@ export function runPersistenceConformance(
         )
 
         expect(
-          threadIds(await store.list({ principal: owner, parentThreadId: null })),
+          threadIds(
+            await store.list({ principal: owner, parentThreadId: null }),
+          ),
         ).toEqual([parent])
       })
 
diff --git a/packages/ai-persistence/tests/subagent-persistence-cards.test.ts b/packages/ai-persistence/tests/subagent-persistence-cards.test.ts
index edb441e986..d134ec9db1 100644
--- a/packages/ai-persistence/tests/subagent-persistence-cards.test.ts
+++ b/packages/ai-persistence/tests/subagent-persistence-cards.test.ts
@@ -663,7 +663,11 @@ describe('subagent run recorder', () => {
     await feed(recorder, 'run-1', [
       childStarted('child', { parentToolCallId: 'call_1' }),
       ...textMessage('m1', 'Old notes', { subagentRunId: 'child' }),
-      { type: EventType.SUBAGENT_FINISHED, subagentRunId: 'child', timestamp: t },
+      {
+        type: EventType.SUBAGENT_FINISHED,
+        subagentRunId: 'child',
+        timestamp: t,
+      },
     ])
 
     // run-2 continues the child. It writes, then waits for an approval. The
diff --git a/packages/ai-sandbox/src/workspace-backend.ts b/packages/ai-sandbox/src/workspace-backend.ts
index d19631bbe6..9e34eeeac6 100644
--- a/packages/ai-sandbox/src/workspace-backend.ts
+++ b/packages/ai-sandbox/src/workspace-backend.ts
@@ -109,8 +109,7 @@ export function sandboxWorkspaceBackend(handle: SandboxHandle) {
       return Promise.all(
         entries.map(async (entry) => {
           const isLink =
-            lstat !== undefined &&
-            (await lstat(entry.path))?.type === 'symlink'
+            lstat !== undefined && (await lstat(entry.path))?.type === 'symlink'
           const type = isLink ? ('link' as const) : entry.type
           return { name: entry.name, type }
         }),
diff --git a/packages/ai/src/activities/chat/middleware/types.ts b/packages/ai/src/activities/chat/middleware/types.ts
index c7a2b1030b..734a2079e4 100644
--- a/packages/ai/src/activities/chat/middleware/types.ts
+++ b/packages/ai/src/activities/chat/middleware/types.ts
@@ -477,9 +477,10 @@ export interface AfterToolCallInfo {
  *   the stream see it. The next middleware gets it as `info.result`. An error
  *   result stays an error.
  */
-export type AfterToolCallDecision =
-  | void
-  | { type: 'replaceResult'; result: unknown }
+export type AfterToolCallDecision = void | {
+  type: 'replaceResult'
+  result: unknown
+}
 
 // ===========================
 // Iteration Info

From 2c014c06abeb3bf947360bc4879e4851f6537a70 Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 7 Oct 2026 10:13:45 +0200
Subject: [PATCH 284/286] fix: type errors and an env-dependent test found by
 the quality gate

- The tool-choice wire tests of ai-openai, ai-vercel-gateway, and ai-lovable
  name namedChoice in their satisfies type.
- The sandbox workspace backend test keeps plain Uint8Array values.
- harness-cli-batman imports workspaceTools from plugins/coding, and its
  footer reads calls from the usage state.
- A background command test passes --no-warnings, so a runner that sets
  NO_COLOR and FORCE_COLOR does not add a node warning to the output.
---
 examples/harness-cli-batman/src/harness.ts                | 2 +-
 examples/harness-cli-batman/src/screen/keys.ts            | 3 ++-
 packages/ai-harness/tests/coding-backend.test.ts          | 4 +++-
 packages/ai-lovable/tests/tool-choice-wire.test.ts        | 2 +-
 packages/ai-openai/tests/tool-choice-wire.test.ts         | 2 +-
 packages/ai-sandbox/tests/workspace-backend.test.ts       | 2 +-
 packages/ai-vercel-gateway/tests/tool-choice-wire.test.ts | 2 +-
 7 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/examples/harness-cli-batman/src/harness.ts b/examples/harness-cli-batman/src/harness.ts
index cea583d4c8..e38e69bdec 100644
--- a/examples/harness-cli-batman/src/harness.ts
+++ b/examples/harness-cli-batman/src/harness.ts
@@ -12,8 +12,8 @@ import {
   providerKeys,
   todos,
   usage,
-  workspaceTools,
 } from '@tanstack/ai-harness/plugins'
+import { workspaceTools } from '@tanstack/ai-harness/plugins/coding'
 import { ANTHROPIC_MODELS, createAnthropicChat } from '@tanstack/ai-anthropic'
 import { anthropicByok } from '@tanstack/ai-anthropic/byok'
 import { claudeCodeText } from '@tanstack/ai-claude-code'
diff --git a/examples/harness-cli-batman/src/screen/keys.ts b/examples/harness-cli-batman/src/screen/keys.ts
index ccd6c1ae9b..91daf57ae0 100644
--- a/examples/harness-cli-batman/src/screen/keys.ts
+++ b/examples/harness-cli-batman/src/screen/keys.ts
@@ -57,6 +57,7 @@ export function isOn(
 
 /** The totals of the usage plugin. */
 export interface Usage {
+  /** Model calls: `calls` in the state. */
   turns: number
   promptTokens: number
   completionTokens: number
@@ -71,7 +72,7 @@ export function usageIn(saved: unknown): Usage {
     return typeof value === 'number' ? value : 0
   }
   return {
-    turns: read('turns'),
+    turns: read('calls'),
     promptTokens: read('promptTokens'),
     completionTokens: read('completionTokens'),
     contextTokens: read('contextTokens'),
diff --git a/packages/ai-harness/tests/coding-backend.test.ts b/packages/ai-harness/tests/coding-backend.test.ts
index 6b2825c7ae..aa6da36eb2 100644
--- a/packages/ai-harness/tests/coding-backend.test.ts
+++ b/packages/ai-harness/tests/coding-backend.test.ts
@@ -78,7 +78,9 @@ describe('hostBackend', () => {
   })
 
   it('starts a background command, then gives its exit code and output', async () => {
-    const job = hostBackend.spawn(`node -e "console.log('done')"`, {
+    // --no-warnings: a runner that sets NO_COLOR and FORCE_COLOR makes node
+    // print a warning to the output.
+    const job = hostBackend.spawn(`node --no-warnings -e "console.log('done')"`, {
       cwd: dir,
     })
     expect(await job.wait()).toEqual({ exitCode: 0 })
diff --git a/packages/ai-lovable/tests/tool-choice-wire.test.ts b/packages/ai-lovable/tests/tool-choice-wire.test.ts
index 16df20d88c..dcf03489a1 100644
--- a/packages/ai-lovable/tests/tool-choice-wire.test.ts
+++ b/packages/ai-lovable/tests/tool-choice-wire.test.ts
@@ -47,7 +47,7 @@ const adapters = [
         model,
       ).chatStream({ logger, model, messages, ...request }),
   },
-] satisfies Array<{ adapter: string; send: Send }>
+] satisfies Array<{ adapter: string; namedChoice: object; send: Send }>
 
 /** Runs one streaming call and returns the JSON body sent over HTTP. */
 async function sentBody(send: Send, request: ToolRequest) {
diff --git a/packages/ai-openai/tests/tool-choice-wire.test.ts b/packages/ai-openai/tests/tool-choice-wire.test.ts
index 3121cb8165..84262deca9 100644
--- a/packages/ai-openai/tests/tool-choice-wire.test.ts
+++ b/packages/ai-openai/tests/tool-choice-wire.test.ts
@@ -98,7 +98,7 @@ const adapters = [
         'responses',
       )('my-model').chatStream(callOptions('my-model', request)),
   },
-] satisfies Array<{ adapter: string; send: Send }>
+] satisfies Array<{ adapter: string; namedChoice: object; send: Send }>
 
 /** Runs one streaming call and returns the JSON body sent over HTTP. */
 async function sentBody(send: Send, request: ToolRequest) {
diff --git a/packages/ai-sandbox/tests/workspace-backend.test.ts b/packages/ai-sandbox/tests/workspace-backend.test.ts
index bb6aceb649..78958d92dd 100644
--- a/packages/ai-sandbox/tests/workspace-backend.test.ts
+++ b/packages/ai-sandbox/tests/workspace-backend.test.ts
@@ -32,7 +32,7 @@ interface FsSeed {
  * `withLstat: false`, it has no `lstat`.
  */
 function memoryFs(seed: FsSeed, withLstat = true) {
-  const files = new Map(
+  const files = new Map<string, Uint8Array>(
     Object.entries(seed.files ?? {}).map(([path, text]) => [
       path,
       encoder.encode(text),
diff --git a/packages/ai-vercel-gateway/tests/tool-choice-wire.test.ts b/packages/ai-vercel-gateway/tests/tool-choice-wire.test.ts
index 6ca2e706d3..a0e0a53d9f 100644
--- a/packages/ai-vercel-gateway/tests/tool-choice-wire.test.ts
+++ b/packages/ai-vercel-gateway/tests/tool-choice-wire.test.ts
@@ -47,7 +47,7 @@ const adapters = [
         model,
       ).chatStream({ logger, model, messages, ...request }),
   },
-] satisfies Array<{ adapter: string; send: Send }>
+] satisfies Array<{ adapter: string; namedChoice: object; send: Send }>
 
 /** Runs one streaming call and returns the JSON body sent over HTTP. */
 async function sentBody(send: Send, request: ToolRequest) {

From 00234bde851559fbfec8cdca4ff45fac6f4ef7ea Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 7 Oct 2026 10:26:21 +0200
Subject: [PATCH 285/286] fix(ai-vertex): resolve the same @google/genai copy
 as ai-gemini

The new optional peers of ai-harness made pnpm resolve peers again, and
ai-vertex, with no zod of its own, got a @google/genai copy whose MCP SDK
peer uses zod 4.6.5. ai-gemini keeps zod 4.3.6, so the vertex factory test
mocked a different copy than the one ai-gemini builds. ai-vertex now has
zod as a dev dependency, like ai-gemini, and both use one copy.
---
 packages/ai-vertex/package.json | 3 ++-
 pnpm-lock.yaml                  | 7 +++++--
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/packages/ai-vertex/package.json b/packages/ai-vertex/package.json
index 96967ba4c1..5f1f13fa05 100644
--- a/packages/ai-vertex/package.json
+++ b/packages/ai-vertex/package.json
@@ -62,6 +62,7 @@
     "@google/genai": "^2.10.0",
     "@tanstack/ai": "workspace:*",
     "@vitest/coverage-v8": "4.1.10",
-    "vite": "^8.2.1"
+    "vite": "^8.2.1",
+    "zod": "^4.2.0"
   }
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5e3af227e0..f6d7c41bfb 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -3816,7 +3816,7 @@ importers:
     devDependencies:
       '@google/genai':
         specifier: ^2.10.0
-        version: 2.10.0(@modelcontextprotocol/sdk@1.29.0(zod@4.6.5))
+        version: 2.10.0(@modelcontextprotocol/sdk@1.29.0(zod@4.3.6))
       '@tanstack/ai':
         specifier: workspace:*
         version: link:../ai
@@ -3826,6 +3826,9 @@ importers:
       vite:
         specifier: ^8.2.1
         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)
+      zod:
+        specifier: ^4.2.0
+        version: 4.3.6
 
   packages/ai-vue:
     dependencies:
@@ -22919,7 +22922,7 @@ snapshots:
 
   '@modelcontextprotocol/core@2.1.0':
     dependencies:
-      zod: 4.3.6
+      zod: 4.6.5
 
   '@modelcontextprotocol/ext-apps@1.7.4(@modelcontextprotocol/sdk@1.29.0(supports-color@7.2.0)(zod@4.2.1))(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(zod@3.25.76)':
     dependencies:

From 694fa0021b950d0eab245f32ec07e169d2b4f9eb Mon Sep 17 00:00:00 2001
From: Alem Tuzlak <t.zlak@hotmail.com>
Date: Wed, 7 Oct 2026 10:39:46 +0200
Subject: [PATCH 286/286] chore(knip): ignore the zod dev dependency of
 ai-vertex

ai-vertex imports no zod. The dev dependency only keeps its @google/genai
peer copy the same as the one ai-gemini uses.
---
 knip.json | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/knip.json b/knip.json
index bcaf1c98b0..1343b74fa2 100644
--- a/knip.json
+++ b/knip.json
@@ -58,6 +58,9 @@
     "packages/ai-sandbox-cloudflare": {
       "ignoreDependencies": ["cloudflare"]
     },
+    "packages/ai-vertex": {
+      "ignoreDependencies": ["zod"]
+    },
     "packages/ai-react": {
       "ignoreDependencies": ["@mcp-ui/client", "react-dom"]
     },